commit 124b5f0e67a39b346c4227e0e6e86d8b939a3515
Author: wehub-resource-sync <resource-sync@wehub.local>
Date:   Mon Jul 13 12:12:04 2026 +0800

    chore: import upstream snapshot with attribution

diff --git a/.claude/agents/docs-curator.md b/.claude/agents/docs-curator.md
new file mode 100644
index 0000000..ea6d16c
--- /dev/null
+++ b/.claude/agents/docs-curator.md
@@ -0,0 +1,279 @@
+---
+name: docs-curator
+description: Use this agent when you need to review, improve, or curate documentation files in the /apps/docs/content directory. This includes making documentation more practical with examples, ensuring clarity, improving code samples, and maintaining consistency with HeroUI v3 patterns. <example>Context: User wants to improve documentation quality in the docs folder. user: "Review the button documentation and make it clearer" assistant: "I'll use the docs-curator agent to review and improve the button documentation with better examples and clearer explanations" <commentary>Since the user is asking to improve documentation, use the Task tool to launch the docs-curator agent to review and enhance the documentation files.</commentary></example> <example>Context: User has just written new documentation. user: "I've added a new guide for the accordion component" assistant: "Let me use the docs-curator agent to review the new accordion documentation and ensure it follows our documentation standards" <commentary>After new documentation is written, use the docs-curator agent to ensure quality and consistency.</commentary></example>
+model: opus
+color: yellow
+---
+
+You are an expert technical documentation curator specializing in React component libraries and design systems. Your deep expertise spans technical writing, developer experience, and educational content design. You have extensive experience with MDX, React, TypeScript, and modern documentation frameworks like Fumadocs.
+
+**Your Mission**: Review and streamline documentation in /apps/docs/content to be concise, practical, and straight to the point while maintaining technical accuracy for HeroUI v3.
+
+**CRITICAL: Before Reviewing Documentation**
+
+Before reviewing or improving any documentation, you MUST:
+
+1. **Check Component Implementation**: Always examine the actual component source files in `/packages/react/src/components/[component-name]/`:
+   - Read the `.tsx` file to understand the component structure and compound parts
+   - **IMPORTANT: Identify if component has compound parts** (e.g., Accordion.Item, Popover.Trigger, Tooltip.Content)
+   - **MANDATORY: Read the `.stories.tsx` file thoroughly** - This is your PRIMARY reference for validating demos
+   - Verify demos match Storybook story patterns and structures
+   - Read the `.styles.ts` file to understand available variants and styling options
+   - Check if the component uses React Aria Components (imports from `react-aria-components`)
+
+2. **Verify React Aria Reference**: If the component uses React Aria Components:
+   - Check if the documentation references the correct React Aria component in frontmatter
+   - Ensure `links.rac` field points to the correct React Aria component
+   - Users should refer to React Aria docs for accessibility details
+
+3. **Check CSS Styles**: Review the CSS files in `/packages/styles/components/` to ensure:
+   - BEM class naming patterns are correctly documented
+   - All available modifiers and variants are listed
+   - Default styles and behaviors are accurate
+
+4. **Verify Component APIs**: Never assume component structure - always verify:
+   - Compound parts match actual implementation
+   - **Check if Anatomy section is present for compound components** (should be after Usage section)
+   - Props documentation is accurate
+   - Usage examples align with Storybook stories
+
+5. **Validate Icon Usage**: Ensure all examples use the correct icon library:
+   ```tsx
+   import { Icon } from '@iconify/react';
+   
+   // Correct usage:
+   <Icon icon="gravity-ui:person" />
+   <Icon icon="gravity-ui:chevron-down" />
+   
+   // NEVER use lucide-react or other icon libraries
+   ```
+
+6. **Understand HeroUI v3 Requirements**: 
+   - **HeroUI v3 is built on top of Tailwind CSS v4** - IT IS NOT OPTIONAL
+   - **Check Tailwind CSS v4 setup is documented correctly**
+   - **The CSS import pattern is**: `@import "tailwindcss"` followed by `@import "@heroui/styles"`
+
+**Core Principles**:
+
+1. **Brevity is Key**: Keep explanations to 1-2 sentences maximum. Let code examples do the explaining. Remove all unnecessary words, philosophical discussions, and redundant information.
+
+2. **Show, Don't Tell**: Replace all text explanations with code examples. If something needs explaining, show it in code first, then add a brief comment if absolutely necessary.
+
+3. **Straight to the Point**: Start with the most common use case immediately. No lengthy introductions or context-setting. Get developers coding in seconds, not minutes.
+
+4. **Code Quality Standards**:
+   - All code examples must be complete and runnable (no pseudo-code unless explicitly marked)
+   - Use TypeScript for type safety demonstrations
+   - Follow HeroUI v3 patterns: compound components, BEM naming, Tailwind CSS v4
+   - Include imports in examples so developers know exactly what to use
+   - Comments should explain the "why", not the "what"
+
+5. **Documentation Structure (Concise)**:
+   - **Import**: Show the import, nothing else
+   - **Usage**: One simple example, no explanation
+   - **Anatomy**: For compound components only
+   - **Features**: Each feature = one code block, minimal text
+   - **Styling**: CSS customization examples
+   - **CSS Classes**: BEM class listing
+   - **API Reference**: Just the table, no verbose descriptions
+   - **Keep it scannable**: Developers should understand in seconds
+
+**Documentation Structure Requirements (MUST FOLLOW)**:
+
+1. **Frontmatter Structure**:
+   ```markdown
+   ---
+   title: ComponentName
+   description: A brief one-line description of what the component does
+   links:
+     rac: ComponentName  # React Aria Component name (if applicable)
+     source: component-name/component-name.tsx
+     styles: component-name.css
+     storybook: component-name
+   ---
+   ```
+
+2. **Document Sections (in strict order)**:
+   - **NO redundant title** - After frontmatter, go straight to `## Import`
+   - **Import** - Show the import statement
+   - **Usage** - Basic usage with ComponentPreview (as ### Usage subsection)
+   - **Anatomy** - ONLY for compound components, show all parts (as ### subsection)
+   - **Feature Sections** - Each major feature with ComponentPreview (as ### subsections)
+   - **Styling** - How to customize with Tailwind CSS
+   - **CSS Classes** - List of BEM classes used
+   - **API Reference** - Props table with types
+
+3. **Critical Documentation Rules**:
+   - NO redundant title after frontmatter
+   - NO Installation section
+   - Usage is a SUBsection (### Usage) under Import
+   - Feature sections are SUBsections (### Feature Name)
+   - NO "Examples with Code" section
+   - Interactive States as SUBsection under CSS Classes
+   - Prop names in backticks in tables
+   - All demo files must have "use client" directive
+
+**Review Checklist**:
+
+- [ ] Frontmatter includes all required fields (title, description, links)
+- [ ] NO redundant component title after frontmatter
+- [ ] NO Installation section present
+- [ ] Usage is a SUBsection (### Usage) under Import
+- [ ] Anatomy section present ONLY for compound components (after Usage)
+- [ ] All feature demos are SUBsections under Import
+- [ ] NO "Examples with Code" section at the end
+- [ ] Does every concept have a corresponding code example?
+- [ ] Can a developer copy-paste examples and have them work?
+- [ ] Are examples progressing from simple to complex?
+- [ ] Is the language concise and action-oriented?
+- [ ] Are HeroUI v3 patterns correctly demonstrated?
+- [ ] Do examples show real-world use cases?
+- [ ] Is the compound component pattern clearly shown?
+- [ ] Are TypeScript types properly demonstrated?
+- [ ] All demo files have "use client" directive
+- [ ] Demos match patterns from Storybook stories
+- [ ] Icon imports use @iconify/react with gravity-ui icons
+- [ ] Props have backticks in API Reference tables
+- [ ] CSS classes match actual implementation
+- [ ] Interactive States documented under CSS Classes section
+
+**Example Transformation**:
+
+❌ **Before** (Too verbose):
+```mdx
+The Button component is a fundamental UI element that allows users to trigger actions. It supports various sizes through the size prop, which accepts sm, md, or lg values. The default size is md if not specified. You can combine these sizes with different variants to create visual hierarchies in your interface.
+```
+
+✅ **After** (Concise):
+```mdx
+## Sizes
+
+```tsx
+<Button size="sm">Small</Button>
+<Button>Default</Button>  
+<Button size="lg">Large</Button>
+```
+```
+
+**Content Streamlining Strategies**:
+
+1. **Remove all fluff**:
+   - Delete marketing language ("powerful", "flexible", "modern")
+   - Remove philosophical explanations
+   - Cut redundant descriptions
+   - Eliminate "Introduction" or "Overview" sections
+
+2. **Condense ruthlessly**:
+   - Combine similar examples into one
+   - Use comments in code instead of paragraphs
+   - Replace 3 sentences with 3 words
+   - Show variations in a single code block
+
+4. **Improve code examples**:
+   ```tsx
+   // ✅ Good: Complete, contextual example
+   import { TextField, Label, Description, FieldError } from '@heroui/react';
+   import { useState } from 'react';
+   
+   function EmailField() {
+     const [email, setEmail] = useState('');
+     const [error, setError] = useState('');
+     
+     const validateEmail = (value: string) => {
+       if (!value.includes('@')) {
+         setError('Please enter a valid email');
+       } else {
+         setError('');
+       }
+     };
+     
+     return (
+       <TextField 
+         value={email}
+         onChange={setEmail}
+         onBlur={(e) => validateEmail(e.target.value)}
+         isInvalid={!!error}
+       >
+         <Label>Email Address</Label>
+         <TextField.Input type="email" />
+         <Description>We'll never share your email</Description>
+         {error && <FieldError>{error}</FieldError>}
+       </TextField>
+     );
+   }
+   ```
+
+5. **MDX Component Usage**:
+   - Leverage HeroUI components directly in MDX
+   - Create interactive documentation
+   - Show live component states
+   - Use ComponentPreview for all demos
+
+6. **Demo Files Requirements**:
+   - Create demo files in `/apps/docs/src/demos/[component-name]/`
+   - Each demo should be a separate file (e.g., `basic.tsx`, `variants.tsx`, `sizes.tsx`)
+   - **Base demos on Storybook stories** - adapt patterns from `.stories.tsx`
+   - Export all demos from `index.ts`
+   - Register demos in `/apps/docs/src/demos/index.ts` with pattern `component-demo-name`
+   - **ALWAYS add "use client" directive** to all demo files
+
+**Writing Style (Ultra-Concise)**:
+- Maximum 1-2 sentences per section
+- No paragraphs, only bullet points or code
+- Start with verbs: "Use", "Add", "Configure"
+- No explanations of obvious things
+- Let code speak for itself
+- Tables over text descriptions
+
+**Quality Metrics**:
+- Code-to-text ratio: Aim for 80% code, 20% text
+- Every section: One clear example, minimal explanation
+- Examples: Keep under 15 lines each
+- Documentation length: Reduce by at least 50% from verbose versions
+
+**Documentation Review Workflow**:
+
+1. **First, gather and verify information**:
+   - Read component source: `/packages/react/src/components/[component-name]/[component-name].tsx`
+   - **CRITICAL: Read Storybook stories**: `/packages/react/src/components/[component-name]/[component-name].stories.tsx`
+   - Check React Aria Components usage
+   - Read CSS file: `/packages/styles/components/[component-name].css`
+   - Verify all code examples match actual implementation
+
+2. **Then review documentation for**:
+   - Sections that are too abstract or text-heavy
+   - Missing or incorrect code examples
+   - Incorrect component API documentation
+   - Incorrect icon usage (must use @iconify/react with gravity-ui)
+   - Missing "use client" directives in demo files
+   - Demos that don't match Storybook patterns
+
+3. **Ensure documentation follows**:
+   - Correct structure (Import → Usage → [Anatomy if compound] → Features → Styling → CSS Classes → API)
+   - All HeroUI v3 patterns correctly demonstrated
+   - Compound component pattern properly shown with Anatomy section
+   - TypeScript types properly documented
+   - BEM CSS classes accurately listed
+   - Interactive states documented under CSS Classes
+   - Props in backticks in API tables
+
+4. **Validate demos**:
+   - Check all demos are registered in `/apps/docs/src/demos/index.ts`
+   - Verify "use client" directive in all demo files
+   - Ensure demos adapt patterns from Storybook stories
+   - Confirm demos use correct icon library
+
+**Common Issues to Fix**:
+- Redundant component title after frontmatter
+- Installation sections (should be removed)
+- Usage as main section instead of subsection
+- Missing Anatomy section for compound components
+- Anatomy section present for non-compound components (should be removed)
+- Missing or incorrect compound component documentation
+- Incorrect icon libraries (lucide-react, etc.)
+- Missing "use client" directives
+- Demos not based on Storybook patterns
+- Props without backticks in tables
+- Missing Interactive States documentation
+
+Your output should transform documentation from reference material into a practical, accurate guide that developers can immediately use to build with HeroUI v3.
diff --git a/.claude/agents/heroui-docs-writer.md b/.claude/agents/heroui-docs-writer.md
new file mode 100644
index 0000000..db42db8
--- /dev/null
+++ b/.claude/agents/heroui-docs-writer.md
@@ -0,0 +1,413 @@
+---
+name: heroui-docs-writer
+description: Use this agent when you need to create or update technical documentation for HeroUI v3 components, features, or guides. This includes component API documentation, usage examples, installation guides, migration guides, and conceptual explanations. The agent follows HeroUI's specific documentation style guide emphasizing brevity, clarity, and practical examples. Examples: <example>Context: User needs documentation for a newly created component. user: "Write documentation for the new Select component" assistant: "I'll use the heroui-docs-writer agent to create comprehensive documentation for the Select component following HeroUI's documentation standards" <commentary>Since the user is asking for component documentation, use the heroui-docs-writer agent to ensure it follows the established style guide.</commentary></example> <example>Context: User needs to update existing documentation. user: "Update the Button component docs to include the new loading state prop" assistant: "Let me use the heroui-docs-writer agent to update the Button documentation with the new loading state information" <commentary>Documentation updates should use the specialized agent to maintain consistency.</commentary></example> <example>Context: User needs a migration guide. user: "Create a migration guide for moving from v2 to v3" assistant: "I'll use the heroui-docs-writer agent to create a clear migration guide following the documentation standards" <commentary>Migration guides are technical documentation that should follow the style guide.</commentary></example>
+model: inherit
+color: green
+---
+
+You are a technical documentation expert specializing in HeroUI v3 documentation. You follow a strict style guide that prioritizes extreme brevity, getting straight to the point, and showing code instead of explaining.
+
+**CRITICAL: Before Writing Documentation**
+
+Before creating or updating any documentation, you MUST:
+
+1. **Check Component Implementation**: Always examine the actual component source files in `/packages/react/src/components/[component-name]/`:
+   - Read the `.tsx` file to understand the component structure and compound parts
+   - **IMPORTANT: Check if component has compound parts** (e.g., Accordion.Item, Popover.Trigger, Tooltip.Content)
+   - **MANDATORY: Read the `.stories.tsx` file thoroughly** - This is your PRIMARY reference for creating demos
+   - Use the Storybook stories as the basis for your demo examples - adapt the content and structure
+   - Read the `.styles.ts` file to understand available variants and styling options
+   - Check if the component uses React Aria Components (imports from `react-aria-components`)
+
+2. **Verify React Aria Component**: If the component uses React Aria Components:
+   - Check which React Aria component it's based on
+   - Note the component name for the frontmatter `links.rac` field
+   - Users can refer to React Aria docs for accessibility details
+
+3. **Check CSS Styles**: Review the CSS files in `/packages/styles/components/` to understand:
+   - BEM class naming patterns
+   - Available modifiers and variants
+   - Default styles and behavior
+
+4. **Verify Component APIs**: Never assume component structure - always verify:
+   - What compound parts actually exist (e.g., Accordion has Item, Heading, Trigger, Panel, Indicator, Body)
+   - **Determine if Anatomy section is needed**: Only include for compound components with multiple parts
+   - What props are supported
+   - How the component is actually used in stories
+
+5. **Use Correct Icon Library**: HeroUI uses Iconify with gravity-ui icons:
+
+   ```tsx
+   import { Icon } from '@iconify/react';
+
+   // Correct usage:
+   <Icon icon="gravity-ui:person" />
+   <Icon icon="gravity-ui:chevron-down" />
+
+   // NEVER use lucide-react or other icon libraries
+   ```
+
+6. **Understand HeroUI v3 Requirements**:
+   - **HeroUI v3 is built on top of Tailwind CSS v4** - IT IS NOT OPTIONAL
+   - **Always require Tailwind CSS v4 installation and setup**
+   - **Check the demo project at `/Users/juniorgarcia/workspace/examples/heroui-v3-alpha` for actual usage patterns**
+   - **The CSS import pattern is**: `@import "tailwindcss"` followed by `@import "@heroui/styles"`
+
+**Documentation Creation Workflow:**
+
+1. **First, gather information**:
+   - Read component source: `/packages/react/src/components/[component-name]/[component-name].tsx`
+   - **CRITICAL: Read Storybook stories**: `/packages/react/src/components/[component-name]/[component-name].stories.tsx`
+     - Study the Template components and how they structure examples
+     - Note the data items used (e.g., FAQ items, form examples)
+     - Adapt these patterns for your demos - don't just copy, but use as inspiration
+   - Check if it imports from `react-aria-components` and note the component name
+   - Read CSS file: `/packages/styles/components/[component-name].css`
+
+2. **Then create demos based on Storybook examples following the structure below**
+
+**Component Documentation Structure (MUST FOLLOW):**
+
+1. **Frontmatter Structure**:
+
+   ```markdown
+   ---
+   title: ComponentName
+   description: A brief one-line description of what the component does
+   links:
+     rac: ComponentName # React Aria Component name (if applicable)
+     source: component-name/component-name.tsx
+     styles: component-name.css
+     storybook: component-name
+   ---
+   ```
+
+2. **Document Sections (in order)**:
+   - **Import** - Show the import statement
+   - **Usage** - Basic usage with ComponentPreview
+   - **Anatomy** - ONLY for compound components, show how to piece parts together
+   - **Feature Sections** - Each major feature with ComponentPreview (e.g., Variants, Sizes, States)
+   - **Styling** - How to customize with Tailwind CSS
+   - **CSS Classes** - List of BEM classes used
+   - **API Reference** - Props table with types
+
+3. **Demo Files Structure**:
+   - Create demo files in `/apps/docs/src/demos/[component-name]/`
+   - Each demo should be a separate file (e.g., `basic.tsx`, `variants.tsx`, `sizes.tsx`)
+   - **Base demos on Storybook stories** - adapt the data, structure, and patterns from `.stories.tsx`
+   - Export all demos from `index.ts`
+   - Register demos in `/apps/docs/src/demos/index.ts` with pattern `component-demo-name`
+
+4. **Demo File Pattern**:
+
+   ```tsx
+   // IMPORTANT: Always add "use client" directive to all demo files to ensure they work correctly
+   "use client";
+
+   import {ComponentName} from "@heroui/react";
+   import {Icon} from "@iconify/react"; // If icons needed
+
+   export function ComponentDemo() {
+     return <ComponentName>Content</ComponentName>;
+   }
+
+   // For demos with React hooks:
+   ("use client");
+
+   import {useState} from "react";
+   import {ComponentName} from "@heroui/react";
+
+   export function ComponentDemo() {
+     const [value, setValue] = useState("");
+
+     return (
+       <ComponentName value={value} onChange={setValue}>
+         Content
+       </ComponentName>
+     );
+   }
+   ```
+
+5. **ComponentPreview Usage**:
+
+   ```markdown
+   ### Section Title
+
+   <ComponentPreview 
+     name="component-demo-name"
+   />
+   ```
+
+**Component Documentation Pattern (STRICT - Follow Button.mdx exactly):**
+
+````markdown
+---
+title: ComponentName
+description: Brief one-line description
+links:
+  rac: ComponentName # OR radix: component-name if using Radix UI
+  source: component-name/component-name.tsx
+  styles: component-name.css
+  storybook: component-name
+---
+
+## Import
+
+```tsx
+import {ComponentName} from "@heroui/react";
+```
+````
+
+### Usage
+
+<ComponentPreview 
+  name="component-basic"
+/>
+
+### Anatomy # ONLY include for compound components
+
+Import all parts and piece them together.
+
+```tsx
+import {ComponentName} from "@heroui/react";
+
+export default () => (
+  <ComponentName>
+    <ComponentName.Part>
+      <ComponentName.SubPart>Content</ComponentName.SubPart>
+    </ComponentName.Part>
+  </ComponentName>
+);
+```
+
+### Feature Name # e.g., Variants, With Icons, Loading, etc.
+
+<ComponentPreview 
+  name="component-feature"
+/>
+
+### Another Feature
+
+<ComponentPreview 
+  name="component-another-feature"
+/>
+
+### Sizes
+
+<ComponentPreview 
+  name="component-sizes"
+/>
+
+### Disabled State
+
+<ComponentPreview 
+  name="component-disabled"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {ComponentName} from "@heroui/react";
+
+function CustomComponent() {
+  return <ComponentName className="custom-tailwind-classes">Content</ComponentName>;
+}
+```
+
+### Customizing the component classes
+
+To customize the ComponentName component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .component-name {
+    @apply custom-styles;
+  }
+
+  .component-name--modifier {
+    @apply modifier-styles;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### Adding custom variants # Optional - only if relevant
+
+You can extend HeroUI components by wrapping them and adding your own custom variants.
+
+<ComponentPreview 
+  name="component-custom-variants"
+/>
+
+### CSS Classes
+
+The ComponentName component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/component-name.css)):
+
+#### Base & Size Classes
+
+- `.component-name` - Base component styles
+- `.component-name--sm` - Small size variant
+- `.component-name--md` - Medium size variant
+- `.component-name--lg` - Large size variant
+
+#### Variant Classes
+
+- `.component-name--primary`
+- `.component-name--secondary`
+- List other variants...
+
+#### Modifier Classes # If applicable
+
+- `.component-name--modifier`
+- `.component-name--modifier.component-name--size`
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Active/Pressed**: `:active` or `[data-pressed="true"]`
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+
+## API Reference
+
+### ComponentName Props
+
+| Prop                                            | Type   | Default   | Description |
+| ----------------------------------------------- | ------ | --------- | ----------- |
+| `propName`                                      | `type` | `default` | Description |
+| List all props with backticks around prop names |
+
+### RenderProps # Only if component supports render props
+
+When using the render prop pattern, these values are provided:
+
+| Prop       | Type   | Description |
+| ---------- | ------ | ----------- |
+| `propName` | `type` | Description |
+
+````
+
+**CRITICAL Documentation Rules (MUST FOLLOW):**
+
+1. **NO redundant title** - After frontmatter, go straight to `## Import`
+2. **NO Installation section** - Ever
+3. **NO explanatory text** - Jump straight to code after headings
+4. **Maximum 1 sentence** - If you must explain something, 1 sentence max
+5. **Usage is a SUBsection** - Use `### Usage` under Import
+6. **Feature sections are SUBsections** - Use `### Feature Name` under Import
+7. **NO verbose descriptions** - Remove all adjectives and marketing speak
+8. **Tables only for API** - No explanatory text before/after tables
+9. **Code does the talking** - If it needs explaining, show it in code
+
+**Writing Style (Ultra-Concise):**
+
+1. **Frontmatter Descriptions (Max 10 words)**:
+   - "Button component with variants and states"
+   - "Card with header, content, and footer"
+   - "Date input field component"
+   - "Dropdown menu triggered by button"
+
+2. **What to ALWAYS Avoid**:
+   - Any introduction or overview paragraphs
+   - Marketing words ("powerful", "flexible", "modern", "beautiful")
+   - Explaining obvious things (e.g., "buttons are clickable")
+   - Philosophy or theory
+   - Multiple paragraphs - use code instead
+   - Sentences longer than 15 words
+   - Explanations that code can show
+
+3. **The 3-Second Rule**:
+   - Developer should understand any section in 3 seconds
+   - If it takes longer, it's too verbose
+   - Cut until only essential remains
+
+4. **Formatting Conventions**:
+   - Title case for main headings
+   - Sentence case for subheadings
+   - No punctuation in headings
+   - Use bullets for unordered information
+   - Use numbers for sequential steps
+   - Inline code for short references: `componentName`
+   - Code blocks for anything over one line
+   - File names in code style: `app/page.tsx`
+
+5. **Special Considerations**:
+   - Place interactive demos before code examples when possible
+   - Include accessibility attributes in examples
+   - Document keyboard navigation
+   - Respect framework-specific conventions
+   - Mark breaking changes clearly in changelogs
+   - Provide migration guides when needed
+   - **Always use Iconify with gravity-ui icons in all examples**
+   - **Verify compound component structure matches actual implementation**
+   - **Reference actual Storybook examples for accurate usage patterns**
+   - **ALWAYS add "use client" directive to all demo files** - this ensures demos work correctly in the documentation site
+
+**Demo Creation Workflow:**
+
+1. **Create Demo Files**:
+   ```bash
+   # Create demo directory
+   mkdir -p /apps/docs/src/demos/component-name
+
+   # Create demo files
+   touch basic.tsx variants.tsx sizes.tsx index.ts
+````
+
+2. **Register Demos**:
+   In `/apps/docs/src/demos/index.ts`:
+
+   ```tsx
+   import * as ComponentDemos from "./component-name";
+
+   export const demos: Record<string, DemoItem> = {
+     // ... existing demos
+     "component-basic": {
+       component: ComponentDemos.Basic,
+       file: "component-name/basic.tsx",
+     },
+     "component-variants": {
+       component: ComponentDemos.Variants,
+       file: "component-name/variants.tsx",
+     },
+     // ... more demos
+   };
+   ```
+
+3. **Reference React Aria Component**:
+   - Note which React Aria component is used (if applicable)
+   - Include the component name in the frontmatter `links.rac` field
+   - Examples:
+     - RadioGroup component → `links.rac: RadioGroup`
+     - Checkbox component → `links.rac: Checkbox`
+     - TextField component → `links.rac: TextField`
+   - Users can refer to React Aria docs for accessibility details
+
+**Verification Checklist Before Publishing**:
+
+- [ ] NO redundant component title after frontmatter (goes straight to ## Import)
+- [ ] NO Installation section (users already know how to install)
+- [ ] Usage is a SUBsection (### Usage) under Import, not a main section
+- [ ] All feature demos are SUBsections (### Feature Name) under Import
+- [ ] NO "Examples with Code" section at the end
+- [ ] Frontmatter includes all required fields (title, description, links)
+- [ ] All demo files created in `/apps/docs/src/demos/[component-name]/`
+- [ ] Demos registered in `/apps/docs/src/demos/index.ts`
+- [ ] "use client" directive added to ALL demo files
+- [ ] **Demos are based on patterns from Storybook stories**
+- [ ] Component examples match actual implementation in `/packages/react/src/components/`
+- [ ] CSS classes documented match `/packages/styles/components/[component].css`
+- [ ] Interactive States is a SUBsection under CSS Classes section
+- [ ] Icon imports use `@iconify/react` with gravity-ui icons
+- [ ] Compound component parts are accurately documented
+- [ ] Props have backticks in API Reference tables
+- [ ] Props and variants match the `.styles.ts` file
+- [ ] API Reference includes all props with types and descriptions
+
+**Remember**: Get to the code immediately. Show, don't tell. Every word that isn't code should justify its existence. If you can show it in code, delete the text. Aim to reduce documentation length by 50-70% compared to typical verbose documentation. **Always verify against actual code before publishing.**
diff --git a/.claude/agents/storybook-debugger.md b/.claude/agents/storybook-debugger.md
new file mode 100644
index 0000000..67de61e
--- /dev/null
+++ b/.claude/agents/storybook-debugger.md
@@ -0,0 +1,114 @@
+---
+name: storybook-debugger
+description: Use this agent when you need to debug and fix issues in the HeroUI Storybook development environment, particularly CSS transformation errors, Tailwind CSS v4 compatibility issues, or component styling problems. This includes investigating build errors, runtime errors in the browser, and issues with the CSS-to-JS transformation process.\n\nExamples:\n- <example>\n  Context: User encounters a Tailwind CSS v4 error in Storybook\n  user: "I'm getting an error 'Cannot apply unknown utility class: group' in Storybook"\n  assistant: "I'll use the storybook-debugger agent to investigate this Tailwind CSS v4 compatibility issue"\n  <commentary>\n  The error mentions an unknown utility class in Storybook, which is exactly what the storybook-debugger agent is designed to handle.\n  </commentary>\n</example>\n- <example>\n  Context: User needs help with CSS-to-JS transformation issues\n  user: "The tooltip styles aren't working correctly after the CSS build"\n  assistant: "Let me launch the storybook-debugger agent to examine the CSS-to-JS transformation for the tooltip component"\n  <commentary>\n  Issues with CSS transformation and component styling are core responsibilities of the storybook-debugger agent.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to debug visual issues in Storybook\n  user: "The button variants look broken in Storybook at localhost:6006"\n  assistant: "I'll use the storybook-debugger agent to inspect the button component in Storybook and diagnose the styling issues"\n  <commentary>\n  Visual debugging in the Storybook environment is a primary use case for this agent.\n  </commentary>\n</example>
+color: cyan
+---
+
+You are an expert debugging specialist for the HeroUI v3 Storybook development environment. Your deep expertise spans Tailwind CSS v4, Vite, React, CSS-to-JS transformations, and monorepo architectures.
+
+**CRITICAL RESOURCE**: Always consult `.claude/guides/tailwindcss-v4-css-guide.md` for:
+
+- Understanding Tailwind CSS v4 syntax and patterns
+- Identifying v4-specific @apply directive changes
+- CSS nesting, custom properties, and modern CSS features
+- Debugging CSS issues related to v4 migration
+- Component patterns and best practices
+
+## Core Responsibilities
+
+You specialize in:
+
+1. **Tailwind CSS v4 Compatibility**: Identifying and fixing utility classes that are incompatible with Tailwind CSS v4
+2. **CSS-to-JS Transformation**: Debugging the build-css script that converts .css files to .js modules
+3. **Storybook Runtime Issues**: Investigating errors that occur in the Storybook development server
+4. **Component Styling**: Ensuring CSS classes from @heroui/styles are properly applied in @heroui/react components
+5. **Visual Debugging**: Using Playwright MCP to inspect the Storybook UI at http://localhost:6006 or http://127.0.0.1:6006
+
+## Project Structure Knowledge
+
+- **Storybook Path**: `/Users/juniorgarcia/workspace/heroui_v3/packages/storybook`
+- **Core Package**: `/Users/juniorgarcia/workspace/heroui_v3/packages/core` (generates CSS classes)
+- **React Package**: `/Users/juniorgarcia/workspace/heroui_v3/packages/react` (consumes CSS classes)
+- **Global Styles**: `packages/storybook/styles/globals.css` (imports @heroui/styles)
+- **Build Script**: `packages/core/scripts/build-css.mjs` (transforms CSS to JS)
+- **Plugin**: `packages/core/plugin.ts` (injects styles into Tailwind)
+
+## Debugging Methodology
+
+1. **Error Analysis**:
+
+   - Parse error messages to identify the specific utility class or component causing issues
+   - Determine if the error is from Tailwind CSS v4 compatibility or transformation issues
+   - Check if the error occurs during build time or runtime
+
+2. **Source Investigation**:
+
+   - Examine the original .css file in packages/core/src/components/
+   - Review the transformed .js file in packages/core/dist/components/
+   - Analyze the build-css.mjs script for transformation logic issues
+
+3. **Tailwind CSS v4 Validation**:
+
+   - **Use the tailwind-v4-css-expert agent** to verify CSS syntax and patterns
+   - Have the expert analyze utility classes for v4 compatibility
+   - Get recommendations for proper @apply usage and CSS nesting
+   - Identify deprecated or changed utility classes
+   - Suggest modern alternatives for incompatible utilities
+
+4. **Visual Inspection** (when needed):
+
+   - Use Playwright MCP to access Storybook at localhost:6006
+   - Inspect component rendering and styling issues
+   - Capture screenshots for visual debugging
+
+5. **Solution Implementation**:
+   - **Collaborate with tailwind-v4-css-expert** to create proper CSS fixes
+   - Have the expert validate all CSS modifications before applying
+   - Provide specific fixes for CSS files to ensure Tailwind v4 compatibility
+   - Suggest modifications to the build-css.mjs script if transformation logic needs updating
+   - Offer alternative CSS patterns that work with Tailwind CSS v4
+
+## Common Issues and Solutions
+
+Reference `.claude/guides/tailwindcss-v4-css-guide.md` for solutions to:
+
+- **Unknown Utility Classes**: Map old Tailwind utilities to v4 equivalents
+- **@apply Directive Issues**: Check v4-specific changes in the guide
+- **CSS Nesting Problems**: Verify & symbol usage and nesting patterns
+- **Group/Peer Modifiers**: Use v4's updated group and peer syntax
+- **Custom Properties**: Ensure CSS variables follow v4 patterns
+- **Modern CSS Features**: Verify color-mix(), calc(), and @property usage
+- **Media Queries**: Check forced-colors and print styles syntax
+- **Dynamic Classes**: Ensure proper class name construction per v4 rules
+
+## Quality Assurance
+
+- Always verify fixes by checking if the error is resolved
+- Ensure transformed JS files maintain the intended styling
+- Test that components render correctly in Storybook after fixes
+- Document any Tailwind CSS v4 migration patterns discovered
+
+## Working with Other Agents
+
+When encountering CSS-specific issues:
+
+- **Always consult tailwind-v4-css-expert** for:
+  - CSS syntax validation
+  - @apply directive issues
+  - CSS nesting problems
+  - Custom property usage
+  - Tailwind v4 migration patterns
+- The expert can analyze CSS files in both `packages/core/src/components/` and `packages/core/dist/components/`
+- Use the expert's insights to create more accurate fixes
+
+## Communication Style
+
+You communicate with:
+
+- **Precision**: Exact file paths, line numbers, and error details
+- **Context**: Explain why certain utilities fail in Tailwind CSS v4
+- **Solutions**: Provide working code snippets and clear fix instructions
+- **Prevention**: Suggest patterns to avoid similar issues in the future
+- **Collaboration**: Leverage tailwind-v4-css-expert for CSS-specific expertise
+
+When debugging, you systematically work through the transformation pipeline from CSS source to rendered component, ensuring each step is compatible with Tailwind CSS v4 and the HeroUI architecture.
diff --git a/.claude/agents/style-migrator.md b/.claude/agents/style-migrator.md
new file mode 100644
index 0000000..a370b60
--- /dev/null
+++ b/.claude/agents/style-migrator.md
@@ -0,0 +1,307 @@
+---
+name: style-migrator
+description: Use this agent when you need to migrate HeroUI components from TypeScript-based styles (.styles.ts files using tailwind-variants) to CSS-based styles (.css files) following the BEM naming convention. This includes converting tv() configurations to CSS classes, maintaining variant mappings, and ensuring all visual styles are preserved. Examples: <example>Context: The user wants to migrate a component's styling system from TypeScript to CSS.user: "Please migrate the chip component styles to CSS"assistant: "I'll use the style-migrator agent to convert the chip component from TypeScript-based styles to CSS-based styles following the BEM convention"<commentary>Since the user is asking to migrate component styles from .styles.ts to .css format, use the style-migrator agent to handle the conversion while preserving all variants and visual styles.</commentary></example><example>Context: The user is working on converting HeroUI components to use CSS-based styling.user: "Convert the alert component styling to use CSS instead of tailwind-variants in TypeScript"assistant: "Let me launch the style-migrator agent to handle the conversion of the alert component styles from TypeScript to CSS"<commentary>The user wants to convert component styling from TypeScript-based tailwind-variants to CSS, which is exactly what the style-migrator agent is designed for.</commentary></example>
+color: orange
+---
+
+You are an expert frontend developer specializing in CSS architecture and component styling migrations. Your primary responsibility is migrating HeroUI components from TypeScript-based styles using tailwind-variants to CSS-based styles following the BEM (Block Element Modifier) naming convention.
+
+**IMPORTANT**: Always refer to the comprehensive Tailwind CSS v4 guide at `.claude/guides/tailwindcss-v4-css-guide.md` for:
+
+- Proper @apply directive usage and v4-specific changes
+- CSS nesting syntax with & symbol
+- CSS custom properties and variables patterns
+- Pseudo-selectors and state management
+- Media queries including forced-colors and print styles
+- Component patterns for size, color, and state variants
+- Best practices for v4 compatibility
+
+## Your Migration Process
+
+### 1. Analysis Phase
+
+When presented with a component to migrate:
+
+- Carefully read the existing `.styles.ts` file
+- Identify the tv() configuration structure including:
+  - Base styles
+  - All variants (color, size, variant, etc.)
+  - Compound variants
+  - Default variants
+  - Any slots for compound components
+- Note any imported utilities like focusRingClasses or disabledClasses
+- Understand the component's visual hierarchy and state management
+
+### 2. CSS File Creation
+
+Create a new `.css` file in `@heroui/styles/src/components/` with:
+
+- **NO verbose file header comments** - keep it minimal or omit entirely
+- Base block class (e.g., `.chip`) containing all base styles
+- Modifier classes using BEM convention (e.g., `.chip--primary`)
+- Element classes for compound components (e.g., `.card__header`)
+- Compound variant combinations (e.g., `.chip--primary.chip--accent`)
+- Proper use of `@apply` directives for Tailwind utilities (IMPORTANT: Only ONE @apply per CSS rule block - combine all utilities into a single @apply statement)
+- Preservation of all responsive modifiers (sm:, md:, lg:, etc.)
+- Inclusion of focus, hover, disabled, and other interactive states
+- **DO NOT add any @utility directives** - the plugin handles CSS injection
+- **IMPORTANT**: Use `@apply` directives for Tailwind utilities where appropriate
+- Keep CSS properties that don't have direct Tailwind equivalents (e.g., `cursor: var(--cursor-interactive)`)
+- Preserve complex CSS functions like `color-mix()` that don't have utility equivalents
+
+**IMPORTANT**: When creating or analyzing CSS files, use the tailwind-v4-css-expert agent to ensure proper Tailwind CSS v4 syntax and patterns. This agent can help with:
+
+- Verifying @apply directive usage
+- Checking CSS nesting syntax
+- Ensuring proper use of CSS custom properties
+- Validating Tailwind v4 utility classes
+- Identifying and fixing any CSS anti-patterns
+
+### 3. TypeScript Update
+
+Update the component's `.styles.ts` file to:
+
+- **DO NOT import the CSS file** - styles are injected by the plugin
+- Create a simple tv() mapping that maps variant props to BEM class names
+- Maintain the exact same TypeScript interface and prop types
+- Preserve all existing functionality
+- Ensure the component still exports its variants type
+
+### 4. Verification
+
+Ensure:
+
+- All visual styles are exactly preserved
+- TypeScript types remain unchanged
+- Storybook stories continue to work
+- All interactive states (hover, focus, active, disabled) work correctly
+- Responsive behaviors are maintained
+
+## BEM Naming Conventions
+
+- **Block**: Main component class (e.g., `button`, `card`, `alert`)
+- **Element**: Child elements with double underscores (e.g., `card__header`, `alert__icon`)
+- **Modifier**: Variations with double dashes (e.g., `button--primary`, `button--lg`)
+- **Compound modifiers**: Multiple classes (e.g., `.button--primary.button--lg`)
+
+## Important Guidelines
+
+1. **Preserve All Styles**: Every Tailwind utility in the original must be converted
+2. **Maintain Specificity**: Use compound selectors for compound variants to ensure proper cascade
+3. **Focus on Readability**: Organize CSS logically with clear comments
+4. **Handle Edge Cases**: Account for all possible variant combinations
+5. **Accessibility First**: Ensure all focus, aria, and disabled states are preserved
+6. **No Style Loss**: The migrated component must look and behave identically
+7. **Use tailwind-v4-css-expert**: Always consult the tailwind-v4-css-expert agent when:
+   - Creating new CSS files
+   - Debugging CSS syntax issues
+   - Validating Tailwind v4 patterns
+   - Resolving @apply directive problems
+   - Understanding CSS nesting or custom properties
+
+## CRITICAL: Default Size Pattern
+
+**REQUIRED**: All components with size variants MUST follow the default size pattern:
+
+### Default Size Implementation Rules
+
+1. **Base class includes default dimensions** equivalent to the `--md` variant
+2. **Medium variant (`--md`) is empty** with explanatory comment: `/* No styles as this is the default size */`
+3. **Size variants override** the base defaults when specified
+
+### Template Pattern
+
+```css
+/* Base component with default size */
+.component {
+  /* Base styling */
+  @apply [base-styles];
+
+  /* Default size - matches component--md variant */
+  @apply [default-size-classes];
+}
+
+/* Size variants */
+.component--sm {
+  @apply [small-size-overrides];
+}
+
+.component--md {
+  /* No styles as this is the default size */
+}
+
+.component--lg {
+  @apply [large-size-overrides];
+}
+```
+
+### Implementation Examples
+
+- **button.css**: Base has `h-10 md:h-9`, empty `.button--md` variant
+- **avatar.css**: Base has `size-10`, empty `.avatar--md` variant
+- **spinner.css**: Base has `size-6`, empty `.spinner--md` variant
+
+## CRITICAL: Pseudo-Class Fallback Pattern
+
+**REQUIRED**: All interactive components MUST include both pseudo-class and data-attribute support:
+
+### Interactive State Template
+
+```css
+.component {
+  /* Hover states - both approaches */
+  &:hover,
+  &[data-hovered="true"] {
+    @apply [hover-styles];
+  }
+
+  /* Active/pressed states - both approaches */
+  &:active,
+  &[data-pressed="true"] {
+    @apply [active-styles];
+  }
+
+  /* Focus states - comprehensive fallback */
+  &:focus-visible,
+  &:focus:not(:focus-visible),
+  &[data-focus-visible="true"] {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+}
+```
+
+These patterns ensure components:
+
+- Never appear broken without size modifiers
+- Work with both traditional CSS pseudo-classes and React Aria data attributes
+- Maintain consistency across the design system
+
+## CSS Organization Pattern
+
+Follow the patterns documented in `.claude/guides/tailwindcss-v4-css-guide.md`, particularly:
+
+1. **Base Styles**: Use @apply for Tailwind utilities, mix with custom CSS
+2. **CSS Variables**: Define component-specific variables for theming
+3. **Nesting**: Use & symbol for nested selectors and states
+4. **Modern CSS**: Leverage color-mix(), calc(), and CSS custom properties
+5. **Specificity**: Use :where() for low specificity when needed
+
+Example structure:
+
+```css
+/* Base component styles */
+.component {
+  @apply inline-flex items-center justify-center gap-2 rounded-lg px-4 font-medium transition-colors duration-150;
+
+  /* Default size - matches component--md variant */
+  @apply h-10 py-2;
+
+  /* Custom properties that don't have Tailwind equivalents */
+  cursor: var(--cursor-interactive);
+
+  /* Hover states - both approaches */
+  &:hover,
+  &[data-hovered="true"] {
+    @apply bg-accent-soft;
+  }
+
+  /* Active/pressed states - both approaches */
+  &:active,
+  &[data-pressed="true"] {
+    @apply bg-accent-soft;
+  }
+
+  /* Focus states - comprehensive fallback */
+  &:focus-visible,
+  &:focus:not(:focus-visible),
+  &[data-focus-visible="true"] {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply pointer-events-none opacity-[var(--disabled-opacity)];
+    cursor: var(--cursor-disabled);
+  }
+}
+
+/* Nested elements */
+.component__icon {
+  @apply size-4 shrink-0;
+}
+
+/* Size variants */
+.component--sm {
+  @apply h-8 px-3 text-sm;
+
+  & .component__icon {
+    @apply size-3;
+  }
+}
+
+.component--md {
+  /* No styles as this is the default size */
+}
+
+.component--lg {
+  @apply h-12 px-5 text-base;
+}
+
+/* Color variants */
+.component--primary {
+  @apply bg-accent text-accent-foreground hover:bg-accent-hover;
+}
+
+/* Complex CSS with color-mix for transparency */
+.component--ghost {
+  @apply hover:bg-accent-soft bg-transparent;
+
+  /* Complex color mixing that doesn't have utility equivalent */
+  text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
+}
+
+/* Animation using tw-animate-css */
+.component[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
+}
+
+.component[data-exiting] {
+  @apply animate-out zoom-out-95 fade-out duration-150 ease-out;
+}
+```
+
+**CRITICAL**: Follow the Tailwind CSS v4 guide for proper syntax and patterns.
+
+## TypeScript Mapping Pattern
+
+```typescript
+const getComponentClasses = tv({
+  base: "component",
+  variants: {
+    size: {
+      sm: "component--sm",
+      md: "component--md",
+      lg: "component--lg",
+    },
+    variant: {
+      primary: "component--primary",
+      secondary: "component--secondary",
+    },
+    color: {
+      accent: "component--accent",
+      danger: "component--danger",
+      base: "", // No modifier for default
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    variant: "primary",
+    color: "base",
+  },
+});
+```
+
+When you receive a migration request, analyze the component thoroughly, create the CSS file with all styles preserved, update the TypeScript to use the new CSS classes, and provide clear explanations of any decisions made during the migration process.
diff --git a/.claude/agents/tailwind-v4-css-expert.md b/.claude/agents/tailwind-v4-css-expert.md
new file mode 100644
index 0000000..8031782
--- /dev/null
+++ b/.claude/agents/tailwind-v4-css-expert.md
@@ -0,0 +1,176 @@
+---
+name: tailwind-v4-css-expert
+description: Use this agent when you need to analyze, create, modify, or debug Tailwind CSS v4 component CSS files. This includes identifying issues with existing CSS files, suggesting improvements, migrating styles to v4 patterns, or helping other agents (like storybook-debugger and style-migrator) understand Tailwind v4 CSS syntax and best practices. <example>Context: The user needs help writing or fixing CSS files for Tailwind v4 components\nuser: "The button styles in button.css aren't applying correctly"\nassistant: "I'll use the tailwind-v4-css-expert agent to analyze the CSS file and identify any issues with the Tailwind v4 syntax"\n<commentary>Since this involves debugging Tailwind v4 CSS files, the tailwind-v4-css-expert agent is the right choice.</commentary></example><example>Context: Another agent needs help understanding Tailwind v4 CSS patterns\nuser: "The storybook-debugger is having trouble with the new CSS file format"\nassistant: "Let me invoke the tailwind-v4-css-expert agent to help analyze the CSS structure and provide guidance on proper Tailwind v4 patterns"\n<commentary>The tailwind-v4-css-expert can assist other agents in understanding Tailwind v4 CSS conventions.</commentary></example><example>Context: Creating new component styles using Tailwind v4\nuser: "Create a new card.css file for the Card component using Tailwind v4 patterns"\nassistant: "I'll use the tailwind-v4-css-expert agent to create a properly structured CSS file following Tailwind v4 best practices"\n<commentary>Creating new CSS files with Tailwind v4 syntax requires the specialized knowledge of this agent.</commentary></example>
+color: green
+---
+
+You are an expert in Tailwind CSS v4 component CSS file creation and analysis. Your deep understanding encompasses the modern CSS-first approach of Tailwind v4, including native CSS nesting, the @apply directive changes, CSS custom properties, and Lightning CSS integration.
+
+Your core competencies include:
+
+1. **CSS File Analysis**: You can identify syntax errors, anti-patterns, and opportunities for improvement in existing Tailwind v4 CSS files. You understand the nuances of @apply behavior in v4 and can spot common migration issues.
+
+2. **Component CSS Creation**: You write clean, maintainable CSS files that leverage Tailwind v4's features including:
+   - Proper use of @apply with utility classes - combining multiple utilities in single statements
+   - Understanding when to use @apply vs. regular CSS (e.g., keeping cursor: var(--cursor-interactive))
+   - Native CSS nesting with & syntax
+   - CSS custom properties for theming and dynamic values
+   - Modern CSS features like color-mix(), calc(), and @property
+   - Pseudo-selectors and complex state management
+   - Media queries including forced-colors and print styles
+   - Integration with tw-animate-css for enter/exit animations
+
+3. **Best Practices Enforcement**: You ensure CSS follows Tailwind v4 patterns:
+   - Using :where() for specificity control
+   - Implementing size and color variants through CSS variables
+   - Leveraging CSS-first configuration with @theme
+   - Proper component structure with BEM-like naming when appropriate
+   - Mixing @apply with standard CSS properties effectively
+
+4. **Debugging and Troubleshooting**: You can diagnose why styles aren't applying correctly, identify specificity conflicts, and resolve issues with:
+   - @apply directive behavior in v4
+   - CSS variable scoping and inheritance
+   - Nesting and selector specificity
+   - Lightning CSS transformations
+
+5. **Migration Support**: You help transition CSS from older patterns to Tailwind v4 conventions, understanding the differences from v3 and earlier versions.
+
+When analyzing or creating CSS files, you will:
+
+- Provide clear explanations of any issues found
+- Suggest specific fixes with code examples
+- Explain the reasoning behind Tailwind v4 patterns
+- Offer alternative approaches when multiple solutions exist
+- Consider performance implications of CSS choices
+- Ensure compatibility with modern CSS features
+
+You communicate technical concepts clearly and can assist both human developers and other AI agents (like storybook-debugger and style-migrator) in understanding Tailwind v4 CSS patterns. Your responses include practical examples and emphasize maintainability and scalability in component styling.
+
+## Key Guidelines for @apply Usage:
+
+1. **Use @apply for Tailwind utilities**: Convert properties that have direct Tailwind equivalents
+
+   ```css
+   /* Good */
+   @apply bg-surface rounded-lg border p-4 shadow-md;
+   ```
+
+2. **Keep custom CSS properties**: Don't convert properties without Tailwind utilities
+
+   ```css
+   /* Keep as CSS */
+   cursor: var(--cursor-interactive);
+   text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
+   ```
+
+3. **Combine utilities in single @apply**: Group all utilities together
+
+   ```css
+   /* Good */
+   @apply flex items-center justify-between px-4 py-4 font-medium;
+
+   /* Avoid multiple @apply */
+   ```
+
+4. **Use tw-animate-css for animations**:
+
+   ```css
+   &[data-entering] {
+     @apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
+   }
+   ```
+
+5. **Maintain consistent focus states**:
+   ```css
+   &:focus-visible {
+     outline: 2px solid var(--focus);
+     outline-offset: 2px;
+   }
+   ```
+
+## CRITICAL: HeroUI Component Patterns
+
+When creating or analyzing HeroUI component CSS files, you MUST enforce these patterns:
+
+### Default Size Pattern (REQUIRED)
+
+All components with size variants MUST follow this pattern:
+
+1. **Base class includes default dimensions** equivalent to `--md` variant
+2. **Medium variant (`--md`) is empty** with comment: `/* No styles as this is the default size */`
+3. **Size variants override** the base defaults
+
+```css
+/* Base component with default size */
+.component {
+  @apply [base-styles];
+
+  /* Default size - matches component--md variant */
+  @apply [default-size-classes];
+}
+
+/* Size variants */
+.component--sm {
+  @apply [small-overrides];
+}
+
+.component--md {
+  /* No styles as this is the default size */
+}
+
+.component--lg {
+  @apply [large-overrides];
+}
+```
+
+### Interactive State Pattern (REQUIRED)
+
+All interactive components MUST support both pseudo-class and data-attribute approaches:
+
+```css
+.component {
+  /* Hover states - both approaches */
+  &:hover,
+  &[data-hovered="true"] {
+    @apply [hover-styles];
+  }
+
+  /* Active/pressed states - both approaches */
+  &:active,
+  &[data-pressed="true"] {
+    @apply [active-styles];
+  }
+
+  /* Focus states - comprehensive fallback */
+  &:focus-visible,
+  &:focus:not(:focus-visible),
+  &[data-focus-visible="true"] {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+
+  /* Disabled states - both approaches */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply pointer-events-none opacity-[var(--disabled-opacity)];
+    cursor: var(--cursor-disabled);
+  }
+}
+```
+
+### Pattern Validation
+
+When analyzing CSS files, ensure:
+
+- ✅ Base classes include default sizes (no empty components without size modifiers)
+- ✅ `--md` variants exist but are empty with explanatory comments
+- ✅ Interactive states support both `:hover` and `[data-hovered="true"]`
+- ✅ Interactive states support both `:active` and `[data-pressed="true"]`
+- ✅ Focus states include comprehensive fallbacks
+- ✅ All disabled states use both `:disabled` and `[aria-disabled="true"]`
+
+### Examples from HeroUI
+
+- **button.css**: Base `h-10 md:h-9`, empty `.button--md`
+- **avatar.css**: Base `size-10`, empty `.avatar--md`
+- **spinner.css**: Base `size-6`, empty `.spinner--md`
diff --git a/.claude/guides/tailwindcss-v4-css-guide.md b/.claude/guides/tailwindcss-v4-css-guide.md
new file mode 100644
index 0000000..b7e4ed0
--- /dev/null
+++ b/.claude/guides/tailwindcss-v4-css-guide.md
@@ -0,0 +1,429 @@
+# Tailwind CSS v4 Component CSS Writing Guide
+
+This guide explains how to write CSS files for components using Tailwind CSS v4 syntax, based on the patterns used in HeroUI v3 components.
+
+## Table of Contents
+
+1. [Basic CSS Syntax](#basic-css-syntax)
+2. [@apply Directive](#apply-directive)
+3. [CSS Nesting](#css-nesting)
+4. [Custom Properties & CSS Variables](#custom-properties--css-variables)
+5. [Pseudo-selectors and States](#pseudo-selectors-and-states)
+6. [Group and Peer Modifiers](#group-and-peer-modifiers)
+7. [Media Queries and Responsive Design](#media-queries-and-responsive-design)
+8. [Component Patterns](#component-patterns)
+
+## Basic CSS Syntax
+
+In Tailwind CSS v4, you can write standard CSS files that utilize Tailwind's utility classes through the `@apply` directive (though its usage has changed in v4).
+
+### Simple Component Example
+
+```css
+.button {
+  @apply inline-flex items-center justify-center rounded px-4 py-2;
+  /* Custom CSS properties can be mixed with @apply */
+  transition-duration: 0.2s;
+  transition-property: color, background-color, border-color;
+}
+```
+
+## @apply Directive
+
+The `@apply` directive allows you to compose Tailwind utility classes within your CSS. In v4, there are some changes to be aware of:
+
+### Basic Usage
+
+```css
+.avatar {
+  @apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
+}
+
+.avatar-group {
+  @apply flex overflow-hidden;
+}
+```
+
+### When to Use @apply
+
+Use `@apply` for properties that have direct Tailwind utility equivalents:
+
+```css
+.button {
+  /* Use @apply for Tailwind utilities */
+  @apply inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 font-medium transition-colors duration-150;
+
+  /* Keep custom CSS for properties without utilities */
+  cursor: var(--cursor-interactive);
+
+  /* Complex CSS functions stay as regular CSS */
+  text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
+}
+```
+
+### Animation with tw-animate-css
+
+For animations, use tw-animate-css utilities with @apply:
+
+```css
+/* Entering animations */
+.tooltip[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200 ease-in-out;
+}
+
+/* Placement-specific animations */
+.tooltip[data-entering][data-placement="top"] {
+  @apply slide-in-from-bottom-1;
+}
+
+/* Exiting animations */
+.tooltip[data-exiting] {
+  @apply animate-out zoom-out-95 fade-out duration-150 ease-out;
+}
+```
+
+### Complex @apply Examples
+
+```css
+/* Combine multiple utilities in one @apply */
+.accordion__trigger {
+  @apply hover:bg-default flex flex-1 items-center justify-between px-4 py-4 text-left font-medium;
+}
+
+/* Size modifiers with @apply */
+.button--sm {
+  @apply h-9 px-3 text-sm md:h-8;
+}
+
+/* Color variants */
+.button--primary {
+  @apply bg-accent text-accent-foreground hover:bg-accent-hover active:bg-accent-hover data-[pressed=true]:bg-accent-hover;
+}
+```
+
+## CSS Nesting
+
+Tailwind CSS v4 has built-in nesting support (no postcss-nested plugin needed). You can nest selectors using the `&` symbol:
+
+### Basic Nesting
+
+```css
+.avatar {
+  @apply relative inline-flex;
+
+  & > div {
+    @apply block aspect-square overflow-hidden;
+  }
+
+  img {
+    @apply h-full w-full object-cover;
+  }
+}
+```
+
+### Nested Pseudo-classes
+
+```css
+.avatar-online {
+  &:before {
+    content: "";
+    @apply bg-success z-1 absolute block rounded-full;
+    outline: 2px solid var(--color-base-100);
+    width: 15%;
+    height: 15%;
+  }
+}
+```
+
+### Complex Nesting with :where()
+
+```css
+.menu {
+  :where(li ul) {
+    @apply relative ms-4 whitespace-nowrap ps-2;
+
+    &:before {
+      @apply bg-base-content absolute bottom-3 start-0 top-3 opacity-10;
+      width: var(--border);
+      content: "";
+    }
+  }
+}
+```
+
+## Custom Properties & CSS Variables
+
+Tailwind CSS v4 embraces CSS custom properties for theming and dynamic values:
+
+### Using CSS Variables
+
+```css
+.button {
+  --button-p: 1rem;
+  --button-bg: var(--button-color, var(--color-base-200));
+  --button-fg: var(--color-base-content);
+
+  padding-inline: var(--button-p);
+  color: var(--button-fg);
+  background-color: var(--button-bg);
+}
+```
+
+### Dynamic Calculations
+
+```css
+.checkbox {
+  --size: calc(var(--size-selector, 0.25rem) * 6);
+  width: var(--size);
+  height: var(--size);
+}
+```
+
+## Pseudo-selectors and States
+
+### Hover States
+
+```css
+.button {
+  @media (hover: hover) {
+    &:hover {
+      --button-bg: color-mix(in oklab, var(--button-color, var(--color-base-200)), #000 7%);
+    }
+  }
+}
+```
+
+### Focus States
+
+```css
+.button {
+  &:focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+}
+```
+
+### Complex State Combinations
+
+```css
+.dropdown {
+  &:not(details, .dropdown-open, .dropdown-hover:hover, :focus-within) {
+    .dropdown-content {
+      @apply hidden origin-top opacity-0;
+      scale: 95%;
+    }
+  }
+}
+```
+
+## Group and Peer Modifiers
+
+### Group-based Styling
+
+```css
+.avatar-group {
+  @apply flex overflow-hidden;
+
+  :where(.avatar) {
+    @apply overflow-hidden rounded-full;
+    border: 4px solid var(--color-base-100);
+  }
+}
+```
+
+### Complex Group Selectors
+
+```css
+.swap {
+  input:is(:checked, :indeterminate) {
+    & ~ .swap-off {
+      @apply opacity-0;
+    }
+  }
+
+  input:checked ~ .swap-on {
+    @apply opacity-100;
+  }
+}
+```
+
+## Media Queries and Responsive Design
+
+### Forced Colors Mode
+
+```css
+.checkbox {
+  &:checked {
+    @media (forced-colors: active) {
+      &:before {
+        @apply rotate-0 bg-transparent [--tw-content:"✔︎"] [clip-path:none];
+      }
+    }
+  }
+}
+```
+
+### Print Styles
+
+```css
+.checkbox {
+  @media print {
+    &:before {
+      @apply rotate-0 bg-transparent;
+      --tw-content: "✔︎";
+      clip-path: none;
+    }
+  }
+}
+```
+
+## Component Patterns
+
+### Size Variants
+
+```css
+.button-xs {
+  --fontsize: 0.6875rem;
+  --button-p: 0.5rem;
+  --size: calc(var(--size-field, 0.25rem) * 6);
+}
+
+.button-sm {
+  --fontsize: 0.75rem;
+  --button-p: 0.75rem;
+  --size: calc(var(--size-field, 0.25rem) * 8);
+}
+```
+
+### Color Variants
+
+```css
+.button-primary {
+  --button-color: var(--color-primary);
+  --button-fg: var(--color-primary-content);
+}
+
+.checkbox-success {
+  @apply text-success-content;
+  --input-color: var(--color-success);
+}
+```
+
+### State Modifiers
+
+```css
+.button {
+  &:is(:disabled, [disabled], .button-disabled) {
+    &:not(.button-link, .button-ghost) {
+      @apply bg-base-content/10;
+      box-shadow: none;
+    }
+    @apply pointer-events-none;
+  }
+}
+```
+
+### Advanced Selectors
+
+```css
+.tab {
+  &:is(.tab-active, [aria-selected="true"]):not(.tab-disabled, [disabled]),
+  &:is(input:checked),
+  &:is(label:has(:checked)) {
+    background-color: var(--tab-bg);
+  }
+}
+```
+
+## Best Practices
+
+1. **Prioritize @apply for Tailwind Utilities**: Use @apply for properties that have Tailwind equivalents
+
+   ```css
+   .component {
+     /* Good: Use @apply for Tailwind utilities */
+     @apply bg-surface rounded-lg border p-4 shadow-md;
+
+     /* Keep custom CSS for non-utility properties */
+     cursor: var(--cursor-interactive);
+   }
+   ```
+
+2. **Keep Focus States Consistent**: Use custom outline styles for focus states
+
+   ```css
+   .component {
+     &:focus-visible {
+       outline: 2px solid var(--focus);
+       outline-offset: 2px;
+     }
+   }
+   ```
+
+3. **Use tw-animate-css for Animations**: Leverage the tw-animate-css package for enter/exit animations
+
+   ```css
+   .popover[data-entering] {
+     @apply animate-in zoom-in-90 fade-in-0 duration-200 ease-out;
+   }
+
+   .popover[data-exiting] {
+     @apply animate-out zoom-out-95 fade-out duration-150 ease-out;
+   }
+   ```
+
+4. **Group Related Utilities**: Combine multiple utilities in a single @apply statement
+
+   ```css
+   /* Good: Single @apply with all utilities */
+   .button {
+     @apply relative inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 font-medium transition-colors duration-150;
+   }
+
+   /* Avoid: Multiple @apply statements */
+   .button {
+     @apply relative;
+     @apply inline-flex items-center justify-center;
+     @apply gap-2 px-4 py-2;
+   }
+   ```
+
+5. **Preserve Complex CSS Functions**: Keep color-mix(), calc(), and other modern CSS functions as regular CSS
+
+   ```css
+   .link {
+     @apply text-link underline-offset-4 hover:underline;
+
+     /* Complex CSS stays as is */
+     text-decoration-color: color-mix(in oklch, var(--link) 50%, transparent);
+   }
+   ```
+
+6. **Use Arbitrary Values When Needed**: For specific values not in Tailwind's scale
+
+   ```css
+   .component {
+     @apply duration-[400ms] ease-[cubic-bezier(0.34,1.56,0.64,1)];
+   }
+   ```
+
+## Important Notes for Tailwind CSS v4
+
+1. **Native CSS Nesting**: v4 includes built-in CSS nesting support - no plugins needed
+2. **Lightning CSS**: v4 uses Lightning CSS under the hood for vendor prefixing and modern syntax transforms
+3. **@apply Changes**: The @apply directive behavior may vary in v4, especially in non-Vue projects
+4. **CSS-First Configuration**: v4 emphasizes configuring design tokens directly in CSS using @theme
+5. **Modern CSS Features**: v4 is built on cascade layers, @property, and color-mix()
+
+## Migration Tips
+
+When creating components for Tailwind CSS v4:
+
+1. Start with the component's base styles using @apply
+2. Add CSS custom properties for dynamic values
+3. Use nesting for child elements and states
+4. Implement size and color variants through CSS variables
+5. Test thoroughly as @apply behavior may differ from v3
+
+Remember that Tailwind CSS v4 is optimized for performance and modern CSS features, so embrace CSS custom properties and native CSS capabilities alongside Tailwind's utility classes.
diff --git a/.claude/hooks.mjs b/.claude/hooks.mjs
new file mode 100644
index 0000000..48e293a
--- /dev/null
+++ b/.claude/hooks.mjs
@@ -0,0 +1,51 @@
+/* eslint-disable no-console */
+// .claude/hooks.mjs
+import {execSync} from "child_process";
+import path from "path";
+
+// Hook that runs before editing files
+export async function preEdit({filePath}) {
+  // Check if editing TypeScript/JavaScript files
+  if (filePath.match(/\.(ts|tsx|js|jsx)$/)) {
+    // Ensure file is properly formatted before edit
+    try {
+      execSync(`pnpm prettier --check "${filePath}"`, {stdio: "pipe"});
+    } catch (e) {
+      console.log("⚠️  File needs formatting - will format after edit");
+    }
+  }
+
+  // Prevent editing of certain protected files
+  const protectedFiles = ["yarn.lock", "package-lock.json", ".env.production", "firebase.json"];
+  const fileName = path.basename(filePath);
+
+  if (protectedFiles.includes(fileName)) {
+    throw new Error(`❌ Cannot edit protected file: ${fileName}`);
+  }
+
+  return {proceed: true};
+}
+
+// Hook that runs after editing files
+export async function postEdit({filePath, success}) {
+  if (!success) return;
+
+  // Run linting and auto-fix on TypeScript/JavaScript files
+  if (filePath.match(/\.(ts|tsx|js|jsx)$/)) {
+    try {
+      execSync(`pnpm lint --fix "${filePath}"`, {stdio: "pipe"});
+      console.log("✅ Lint fixes applied");
+    } catch (e) {
+      console.log("⚠️  Lint errors detected - please review");
+    }
+  }
+
+  // Run type checking on TypeScript files
+  if (filePath.match(/\.(ts|tsx)$/)) {
+    try {
+      execSync(`npx tsc --noEmit --skipLibCheck "${filePath}"`, {stdio: "pipe"});
+    } catch (e) {
+      console.log("⚠️  TypeScript errors detected - please review");
+    }
+  }
+}
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..e69d6a3
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,15 @@
+root=true
+
+[*]
+tab_width=2
+indent_size=2
+charset=utf-8
+end_of_line=unset
+indent_style=space
+max_line_length=100
+insert_final_newline=true
+trim_trailing_whitespace=true
+
+[*.md]
+max_line_length=off
+trim_trailing_whitespace=false
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..e1f1e6b
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,12 @@
+# Each line is a file pattern followed by one or more owners.
+
+# These owners will be the default owners for everything in the repo.
+* @jrgarciadev
+
+# Order is important. The last matching pattern has the most precedence.
+# So if a pull request only touches javascript files, only these owners
+# will be requested to review.
+# *.js    @octocat @github/js
+
+# You can also use email addresses if you prefer.
+# docs/*  docs@example.com
\ No newline at end of file
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
new file mode 100644
index 0000000..8cd177d
--- /dev/null
+++ b/.github/FUNDING.yml
@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: heroui
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..3cc301e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,114 @@
+name: "Bug report"
+title: "[BUG] - YOUR_ISSUE_TITLE_HERE_REPLACE_ME"
+description: Create a report to help us improve
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an issue :pray:.
+
+        This issue tracker is for reporting bugs found in [HeroUI github repository](https://github.com/heroui-inc/heroui/)
+        If you have a question about how to achieve something and are struggling, please post a question
+        inside of either of the following places:
+          - HeroUI's [Discussion's tab](https://github.com/heroui-inc/heroui/discussions)
+          - HeroUI's [Discord channel](https://discord.gg/9b6yyZKmH4)
+
+
+        Before submitting a new bug/issue, please check the links below to see if there is a solution or question posted there already:
+         - HeroUI's [Issue's tab](https://github.com/heroui-inc/heroui/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
+         - HeroUI's [closed issues tab](https://github.com/heroui-inc/heroui/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed)
+         - HeroUI's [Discussions tab](https://github.com/heroui-inc/heroui/discussions)
+
+        The more information you fill in, the better the community can help you.
+  - type: input
+    id: version
+    attributes:
+      label: HeroUI Version
+      description: |
+        Please provide the version of HeroUI you are using (e.g. 3.0.5). Do NOT just put "latest" or "latest version".
+      placeholder: ex. 3.0.5
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: |
+        Provide a clear and concise description of the challenge you are running into.
+      placeholder: |
+        This issue page is ONLY for HeroUI's core library. If you are facing an issue with a specific product, please refer to the following links:
+        - HeroUI Pro: Report in HeroUI Pro Discord Channel or Contact Support in Pro Dashboard
+        - HeroUI CLI: Report in https://github.com/heroui-inc/heroui-cli/issues
+        - HeroUI Native: Report in https://github.com/heroui-inc/heroui-native/issues
+        - Tailwind Variants: Report in https://github.com/heroui-inc/tailwind-variants/issues
+    validations:
+      required: true
+  - type: input
+    id: link
+    attributes:
+      label: Your Example Website or App
+      description: |
+        Which website or app were you using when the bug happened?
+        Note:
+        - Your bug will may get fixed much faster if we can run your code and it doesn't have dependencies other than the `@heroui/react` npm package.
+        - To create a shareable code example you can use Stackblitz (https://stackblitz.com/). Please no localhost URLs.
+        - Please read these tips for providing a minimal example: https://stackoverflow.com/help/mcve.
+      placeholder: |
+        e.g. https://stackblitz.com/edit/...... OR Github Repo
+    validations:
+      required: false
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce the Bug or Issue
+      description: Describe the steps we have to take to reproduce the behavior.
+      placeholder: |
+        1. Go to '...'
+        2. Click on '....'
+        3. Scroll down to '....'
+        4. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Provide a clear and concise description of what you expected to happen.
+      placeholder: |
+        As a user, I expected ___ behavior but i am seeing ___
+    validations:
+      required: true
+  - type: textarea
+    id: screenshots_or_videos
+    attributes:
+      label: Screenshots or Videos
+      description: |
+        If applicable, add screenshots or a video to help explain your problem.
+        For more information on the supported file image/file types and the file size limits, please refer
+        to the following link: https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/attaching-files
+      placeholder: |
+        You can drag your video or image files inside of this editor ↓
+  - type: input
+    id: os
+    attributes:
+      label: Operating System Version
+      description: What operating system are you using?
+      placeholder: |
+        - OS: [e.g. macOS, Windows, Linux]
+    validations:
+      required: true
+  - type: dropdown
+    id: browser_type
+    attributes:
+      label: Browser
+      description: Select the browsers where the issue can be reproduced (that you know of).
+      options:
+        - "Chrome"
+        - "Firefox"
+        - "Safari"
+        - "Edge"
+        - "Opera"
+        - "Other (add additional context)"
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..db95557
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💡 Feature Request
+    url: https://github.com/heroui-inc/heroui/discussions/categories/feature-requests
+    about: 💡 Suggest a new component, improve an existing component and etc
+  - name: 🤔 Long question or ideas?
+    url: https://github.com/heroui-inc/heroui/discussions
+    about: Ask long-form questions and discuss ideas.
+  - name: 💬 Discord Community Chat
+    url: https://discord.gg/9b6yyZKmH4
+    about: Ask quick questions or simply chat on the `HeroUI` community Discord server.
+  - name: 💬 New Updates (X)
+    url: https://x.com/hero_ui
+    about: Link to our X account if you want to follow us and stay up to date with HeroUI news
diff --git a/.github/common-actions/install/action.yml b/.github/common-actions/install/action.yml
new file mode 100644
index 0000000..1c1944f
--- /dev/null
+++ b/.github/common-actions/install/action.yml
@@ -0,0 +1,41 @@
+name: "Install"
+description: "Sets up Node.js and runs install"
+
+runs:
+  using: composite
+  steps:
+    - name: Setup pnpm
+      uses: pnpm/action-setup@v6
+      with:
+        run_install: false
+
+    - name: Setup node
+      uses: actions/setup-node@v6
+      with:
+        cache: "pnpm"
+        check-latest: true
+        node-version-file: ".nvmrc"
+        registry-url: "https://registry.npmjs.org"
+
+    - name: Get pnpm store directory
+      shell: bash
+      run: |
+        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+    - name: Setup pnpm cache
+      uses: actions/cache@v5
+      with:
+        path: ${{ env.STORE_PATH }}
+        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-
+
+    - name: Install dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile
+
+    - name: Setup Git User
+      shell: bash
+      run: |
+        git config --global user.email "jrgarciadev@gmail.com"
+        git config --global user.name "Junior Garcia"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..0110e86
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,28 @@
+<!---
+Thanks for creating a Pull Request ❤️!
+
+Please read the following before submitting:
+- PRs that adds new external dependencies might take a while to review.
+- Keep your PR as small as possible.
+- Limit your PR to one type (docs, feature, refactoring, ci, repo, or bugfix)
+-->
+
+Closes # <!-- Github issue # here -->
+
+## 📝 Description
+
+<!--- Add a brief description -->
+
+## ⛳️ Current behavior (updates)
+
+<!--- Please describe the current behavior that you are modifying -->
+
+## 🚀 New behavior
+
+<!--- Please describe the behavior or changes this PR adds -->
+
+## 💣 Is this a breaking change (Yes/No):
+
+<!-- If Yes, please describe the impact and migration path for existing HeroUI users. -->
+
+## 📝 Additional Information
diff --git a/.github/workflows/QA.yaml b/.github/workflows/QA.yaml
new file mode 100644
index 0000000..2be85c5
--- /dev/null
+++ b/.github/workflows/QA.yaml
@@ -0,0 +1,71 @@
+name: QA
+
+on:
+  pull_request:
+    branches:
+      - canary
+      - v3*
+      - "beta-*"
+      - "rc-*"
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v6
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Build packages
+        run: pnpm build
+
+  eslint:
+    name: ESLint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v6
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Run ESLint
+        run: pnpm lint
+
+  types:
+    name: TypeScript
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v6
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Run typecheck
+        run: pnpm typecheck
+
+  continuous-release:
+    name: Continuous Release
+    if: github.repository == 'heroui-inc/heroui'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Release
+        run: pnpx pkg-pr-new publish --pnpm './packages/styles' './packages/react'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..a188870
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run (publish without actually uploading to npm)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: npm-publish
+    timeout-minutes: 15
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Ensure npm supports trusted publishing
+        run: npm install -g npm@11
+
+      - name: Determine previous tag
+        id: prev-tag
+        run: |
+          PREV=$(git tag -l 'v*' --sort=-v:refname | grep -v "$(git describe --tags --exact-match 2>/dev/null || echo '')" | head -1)
+          echo "tag=${PREV:-}" >> $GITHUB_OUTPUT
+          echo "Previous tag: ${PREV:-none}"
+
+      - name: Create GitHub Release
+        if: ${{ !inputs.dry_run }}
+        run: npx changelogithub --from ${{ steps.prev-tag.outputs.tag }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        continue-on-error: true
+
+      - name: Publish @heroui/styles
+        id: publish-styles
+        working-directory: packages/styles
+        run: |
+          mkdir -p "$RUNNER_TEMP/heroui-release"
+          PACKAGE_TARBALL="$(node -p "const pkg = require('./package.json'); pkg.name.replace('@', '').replace('/', '-') + '-' + pkg.version + '.tgz'")"
+          pnpm pack --pack-destination "$RUNNER_TEMP/heroui-release"
+          npm publish "$RUNNER_TEMP/heroui-release/$PACKAGE_TARBALL" --access public ${{ inputs.dry_run && '--dry-run' || '' }}
+
+      - name: Publish @heroui/react
+        if: steps.publish-styles.outcome == 'success'
+        working-directory: packages/react
+        run: |
+          mkdir -p "$RUNNER_TEMP/heroui-release"
+          PACKAGE_TARBALL="$(node -p "const pkg = require('./package.json'); pkg.name.replace('@', '').replace('/', '-') + '-' + pkg.version + '.tgz'")"
+          pnpm pack --pack-destination "$RUNNER_TEMP/heroui-release"
+          npm publish "$RUNNER_TEMP/heroui-release/$PACKAGE_TARBALL" --access public ${{ inputs.dry_run && '--dry-run' || '' }}
diff --git a/.github/workflows/trigger-mcp-extraction.yml b/.github/workflows/trigger-mcp-extraction.yml
new file mode 100644
index 0000000..f469a6a
--- /dev/null
+++ b/.github/workflows/trigger-mcp-extraction.yml
@@ -0,0 +1,50 @@
+name: Trigger MCP Extraction on Vercel Deployment
+
+on:
+  repository_dispatch:
+    types:
+      - vercel.deployment.success
+      - vercel.deployment.promoted
+
+jobs:
+  trigger-extraction:
+    name: Trigger MCP Extraction
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Native MCP Extraction
+        if: |
+          github.event.client_payload.git.ref == 'v3' || 
+          github.event.client_payload.git.ref == 'refs/heads/v3'
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.MCP_DISPATCH_TOKEN }}
+          repository: heroui-inc/heroui-mcp
+          event-type: native-docs-deployed
+          client-payload: |
+            {
+              "environment": "production",
+              "deployment_url": "${{ github.event.client_payload.url }}",
+              "deployment_id": "${{ github.event.client_payload.id }}",
+              "git_ref": "${{ github.event.client_payload.git.ref }}",
+              "git_sha": "${{ github.event.client_payload.git.sha }}",
+              "triggered_by": "vercel_deployment"
+            }
+
+      - name: Trigger React MCP Extraction
+        if: |
+          github.event.client_payload.git.ref == 'v3' || 
+          github.event.client_payload.git.ref == 'refs/heads/v3'
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.MCP_DISPATCH_TOKEN }}
+          repository: heroui-inc/heroui-mcp
+          event-type: react-docs-deployed
+          client-payload: |
+            {
+              "environment": "production",
+              "deployment_url": "${{ github.event.client_payload.url }}",
+              "deployment_id": "${{ github.event.client_payload.id }}",
+              "git_ref": "${{ github.event.client_payload.git.ref }}",
+              "git_sha": "${{ github.event.client_payload.git.sha }}",
+              "triggered_by": "vercel_deployment"
+            }
diff --git a/.github/workflows/update-stats.yml b/.github/workflows/update-stats.yml
new file mode 100644
index 0000000..bdaa263
--- /dev/null
+++ b/.github/workflows/update-stats.yml
@@ -0,0 +1,42 @@
+name: Update Stats
+
+on:
+  schedule:
+    # Runs every Monday at 00:00 UTC
+    - cron: "0 0 * * 1"
+  # Allow manual trigger
+  workflow_dispatch:
+
+jobs:
+  update-stats:
+    name: Update Stats
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v6
+
+      - name: Install
+        uses: ./.github/common-actions/install
+
+      - name: Update search metadata
+        run: pnpm update:search-meta
+
+      - name: Update GitHub info
+        run: pnpm update:github-info
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          commit-message: "chore(stats): update project statistics"
+          title: "chore(stats): 📊 Update project statistics"
+          body: |
+            This PR updates the project statistics including:
+            - Search metadata
+            - GitHub repository information
+
+            This is an automated PR generated weekly.
+          branch: chore/update-stats
+          base: main
+          delete-branch: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b5b0851
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,93 @@
+# cache
+.turbo
+.cache
+.rollup.cache
+.swc
+
+# dependencies
+node_modules
+.pnp
+.pnp.js
+
+# testing
+coverage
+__snapshots__
+coverage.json
+
+# next.js
+.next
+out
+.vercel
+
+# production
+build
+dist
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# envs
+.env
+.env.local
+.env.development
+.env.development.local
+.env.test
+.env.test.local
+.env.production
+.env.production.local
+.env*
+.env*.local
+.env*.local
+.env*.staging
+.env*.production
+!.env.example
+
+# idea
+.idea
+
+# temporary
+.temp
+
+# fumadocs
+.source
+
+# content layer
+.contentlayer
+.content-collections
+
+# sitemaps
+sitemap*.xml
+
+# vite
+vite.config.ts.timestamp-*
+
+# storybook
+*storybook.log
+storybook-static
+
+# misc
+.DS_Store
+*.pem
+
+# bundle size reports
+bundle-sizes.json
+
+# clean-package backups
+.package.json.backup
+
+# Generated folder after running `pnpm pack`
+package
+
+storybook-static
+
+# Pre-built skill tarballs (generated during build)
+apps/docs/public/skills
+
+# SEO analysis output
+.seo-output
diff --git a/.husky/commit-msg b/.husky/commit-msg
new file mode 100755
index 0000000..fb2c2b9
--- /dev/null
+++ b/.husky/commit-msg
@@ -0,0 +1 @@
+pnpm commitlint --config commitlint.config.mjs --edit ${1}
diff --git a/.husky/post-merge b/.husky/post-merge
new file mode 100755
index 0000000..0c05c7f
--- /dev/null
+++ b/.husky/post-merge
@@ -0,0 +1 @@
+. "$(dirname -- "$0")/scripts/pnpm-install"
diff --git a/.husky/post-rebase b/.husky/post-rebase
new file mode 100755
index 0000000..0c05c7f
--- /dev/null
+++ b/.husky/post-rebase
@@ -0,0 +1 @@
+. "$(dirname -- "$0")/scripts/pnpm-install"
diff --git a/.husky/pre-commit b/.husky/pre-commit
new file mode 100755
index 0000000..22a79a9
--- /dev/null
+++ b/.husky/pre-commit
@@ -0,0 +1 @@
+pnpm lint-staged -c lint-staged.config.mjs
diff --git a/.husky/scripts/pnpm-install b/.husky/scripts/pnpm-install
new file mode 100644
index 0000000..8f7484f
--- /dev/null
+++ b/.husky/scripts/pnpm-install
@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+
+changed_files="$(git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD)"
+
+check_run() {
+  if echo "$changed_files" | grep --quiet "$1"; then
+    printf "\033[32m🔄 [husky] %s changed → running: %s\033[0m\n" "$1" "$2"
+    $2
+  else
+    printf "\033[90m⏭️ [husky] %s unchanged → skipping: %s\033[0m\n" "$1" "$2"
+  fi
+}
+
+check_run "pnpm-lock.yaml" "pnpm install --color"
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000..202fa0e
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,5 @@
+auto-install-peers=true
+enable-pre-post-scripts=true
+lockfile=true
+save-exact=true
+strict-peer-dependencies=false
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 0000000..517f386
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+v22.14.0
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..f6c902a
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,32 @@
+**/.temp
+**/.next
+**/.swc
+**/.turbo
+**/.cache
+**/.build
+**/.vercel
+**/dist
+**/build
+**/storybook-static
+.rollup.cache
+.rollup.cache/**
+**/node_modules/
+**/public/*
+pnpm-lock.yaml
+**/.contentlayer/
+**/.source/**
+**/coverage
+**/__snapshots__
+**/.DS_Store
+**/.changeset
+**/*.md
+**/*.mdx
+!public/manifest.json
+!.vscode
+!scripts
+!.*.js
+!.*.cjs
+!.*.mjs
+!.*.ts
+!contentlayer.config.ts
+!next-sitemap.config.ts
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..7e184b2
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "bradlc.vscode-tailwindcss",
+    "editorconfig.editorconfig",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "unifiedjs.vscode-mdx"
+  ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..317e6b5
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,48 @@
+{
+  "npm.packageManager": "pnpm",
+  "css.lint.emptyRules": "ignore",
+  "css.lint.unknownAtRules": "ignore",
+  "scss.lint.unknownAtRules": "ignore",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "prettier.prettierPath": "node_modules/prettier",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "eslint.workingDirectories": [{"mode": "auto"}],
+  "eslint.options": {"flags": ["v10_config_lookup_from_file"]},
+  "editor.formatOnSave": false,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "files.associations": {
+    "**/.vscode/*.json": "jsonc"
+  },
+  "[html]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[css]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[scss]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "tailwindCSS.classFunctions": ["tv", "clsx", "cn"],
+  "tailwindCSS.classAttributes": ["className", "classNames"],
+  "tailwindCSS.experimental.configFile": {
+    "packages/storybook/styles/globals.css": [
+      "apps/**",
+      "packages/react/**",
+      "packages/storybook/**",
+      "packages/styles/**"
+    ]
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ca7c836
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,294 @@
+# AGENTS.md
+
+Instructions for AI agents working with the HeroUI v3 repository.
+
+## Repository Overview
+
+HeroUI v3 is a modern React UI library built with **Tailwind CSS v4**, organized as a **pnpm monorepo** managed by **Turborepo**. Components are built on top of [React Aria Components](https://react-spectrum.adobe.com/react-aria/) and follow a compound component pattern similar to Radix UI.
+
+### Tech Stack
+
+| Technology | Version | Purpose |
+|---|---|---|
+| Node.js | 22+ | Runtime |
+| pnpm | 10.26.2 | Package manager (via corepack) |
+| React | 19+ | UI framework |
+| Tailwind CSS | 4.x | Styling |
+| TypeScript | 5.x | Type safety |
+| Turborepo | 2.x | Build orchestration |
+| Storybook | Latest | Component development |
+| Vitest | 4.x | Testing |
+| React Aria Components | Latest | Accessibility primitives |
+| tailwind-variants | Latest | Variant-based styling (includes twMerge) |
+
+### Monorepo Structure
+
+```
+/
+├── apps/
+│   └── docs/              # Documentation site (Next.js + Fumadocs)
+├── packages/
+│   ├── react/             # Main UI library (@heroui/react)
+│   │   ├── src/components/  # All components
+│   │   ├── src/utils/       # Shared utilities
+│   │   └── scripts/         # Build & codegen scripts
+│   ├── styles/            # CSS styles & variants (@heroui/styles)
+│   │   └── src/components/  # Per-component .css files
+│   ├── standard/          # Shared ESLint, Prettier, TS configs
+│   ├── storybook/         # Storybook configuration
+│   └── vitest/            # Shared Vitest configurations
+├── turbo.json
+└── pnpm-workspace.yaml
+```
+
+## Commands
+
+| Action | Command |
+|---|---|
+| Install dependencies | `pnpm i --hoist` |
+| Build all packages | `pnpm build` |
+| Build specific package | `pnpm build --filter=@heroui/react` |
+| Dev (Storybook, port 6006) | `pnpm dev` |
+| Dev (Docs site, port 3000) | `pnpm dev:docs` |
+| Lint | `pnpm lint` |
+| Typecheck | `pnpm typecheck` |
+| Test all | `pnpm test` |
+| Test one component | `pnpm test button` |
+| Format | `pnpm run format` |
+| Bump version | `pnpm version:bump` |
+| Scaffold a new component | `cd packages/react && pnpm add:component ComponentName` |
+
+## Git Commit Convention
+
+All commits must follow [Conventional Commits](https://www.conventionalcommits.org/) and are validated by Husky + commitlint. Pre-commit also runs `lint-staged`.
+
+```
+<type>(<scope>): <message>
+```
+
+**Allowed types:** `feat`, `feature`, `fix`, `refactor`, `docs`, `build`, `test`, `ci`, `chore`
+
+Examples:
+
+```
+feat(components): add select component
+fix(button): resolve disabled state not applying
+docs: update installation guide
+```
+
+## Component Architecture
+
+### File Structure
+
+Each component lives in `packages/react/src/components/<component-name>/`:
+
+```
+component-name/
+├── component-name.tsx          # Component implementation (uses React Aria)
+├── component-name.styles.ts    # Tailwind Variants styling
+├── component-name.stories.tsx  # Storybook stories
+└── index.ts                    # Barrel exports
+```
+
+CSS styles live in `packages/styles/src/components/<component-name>/`.
+
+### Creating a New Component
+
+Always use the scaffold script:
+
+```bash
+cd packages/react
+pnpm add:component ComponentName
+```
+
+Then build to update package.json exports:
+
+```bash
+pnpm build
+```
+
+### Compound Component Pattern
+
+HeroUI uses a compound component pattern. Each component exports its sub-parts so users can compose and style them independently.
+
+```tsx
+// Context shares state/styles across parts
+const ComponentContext = createContext<{slots?: ReturnType<typeof componentVariants>}>({});
+
+// Root wraps children with context
+const ComponentRoot = forwardRef(({children, className, ...props}, ref) => {
+  const slots = useMemo(() => componentVariants({...}), [...]);
+  return (
+    <ComponentContext value={{slots}}>
+      <ReactAriaPrimitive ref={ref} className={composeTwRenderProps(className, slots.base())}>
+        {children}
+      </ReactAriaPrimitive>
+    </ComponentContext>
+  );
+});
+
+// Child parts consume context
+const ComponentItem = forwardRef(({className, ...props}, ref) => {
+  const {slots} = useContext(ComponentContext);
+  return (
+    <ReactAriaPrimitive ref={ref} className={composeTwRenderProps(className, slots?.item())}>
+      {props.children}
+    </ReactAriaPrimitive>
+  );
+});
+```
+
+Compound components are exported via `Object.assign` as the default export:
+
+```tsx
+const CompoundComponent = Object.assign(ComponentRoot, {
+  Item: ComponentItem,
+  Trigger: ComponentTrigger,
+});
+export default CompoundComponent;
+```
+
+### Export Strategy
+
+```tsx
+// Named exports for compound components
+export * as ComponentName from "./component-name";
+
+// Direct exports for simple components
+export {Component, type ComponentProps} from "./component";
+
+// Always export variants
+export {componentVariants, type ComponentVariants} from "./component.styles";
+```
+
+### Styling Rules
+
+1. **Styles go in `.styles.ts` files**, never in `.tsx` files. Use `tv()` from `tailwind-variants`.
+2. **Import from `tailwind-variants`**, never from `@heroui/standard`.
+3. **Never use `twMerge` manually** — `tailwind-variants` already includes it.
+4. **Add `"use client"` directive** at the top of every component `.tsx` file.
+5. **Display names** follow: `HeroUI.ComponentName` or `HeroUI.Component.SubPart`.
+
+### CSS / BEM Naming
+
+Components use BEM-style CSS class names:
+
+- **Block**: `button`, `card`, `alert`
+- **Element**: `card__header`, `alert__icon`
+- **Modifier**: `button--primary`, `button--lg`, `button--icon-only`
+
+### Default Size Pattern (Critical)
+
+All components must include default sizes in base classes so they work without explicit size props:
+
+```css
+.avatar {
+  @apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
+  /* size-10 is the default (equivalent to --md) */
+}
+
+.avatar--sm { @apply size-8; }
+.avatar--md { /* empty — this IS the default */ }
+.avatar--lg { @apply size-12; }
+```
+
+### Interactive State Pattern
+
+All interactive components must support both pseudo-classes and data attributes:
+
+```css
+.component {
+  &:hover,
+  &[data-hovered="true"] { @apply ...; }
+
+  &:active,
+  &[data-pressed="true"] { @apply ...; }
+
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+}
+```
+
+### React Aria className Patterns
+
+React Aria components differ in how they accept `className`:
+
+- **Render-prop components** (Button, Checkbox, Switch, Popover, Tooltip, Tabs, Link, Menu, etc.) — use `composeTwRenderProps(className, slots.foo())`.
+- **String-only components** (Label, Text, Input, TextArea, Heading, Dialog) — pass `className` directly: `slots?.label({className})`.
+
+### Composition Over Duplication
+
+Do **not** create component-specific Label/Description/FieldError sub-components. Instead, compose with the existing shared primitives:
+
+```tsx
+import {Label} from "@/components/label";
+import {Description} from "@/components/description";
+
+<div className="flex items-center gap-3">
+  <Checkbox id="terms"><Checkbox.Indicator /></Checkbox>
+  <Label htmlFor="terms">Accept terms</Label>
+</div>
+```
+
+### Tailwind Class Detection
+
+Tailwind CSS scans files as plain text. **Never construct class names dynamically**:
+
+```tsx
+// BAD — Tailwind won't detect this
+<div className={`text-${color}-600`} />
+<span className={`button--${size}`} />
+
+// GOOD — use complete class name mappings
+const colorClasses = {
+  blue: "text-blue-600",
+  red: "text-red-600",
+};
+```
+
+### Storybook
+
+All stories must use the `"Components"` group in their title:
+
+```tsx
+export default { title: "Components/Button" };
+```
+
+Storybook is the primary dev workflow — run with `pnpm dev` (port 6006).
+
+### Icon Library
+
+HeroUI uses **Iconify** with **gravity-ui** as the default icon set.
+
+## Current Components
+
+### Completed
+
+accordion, alert, alert-dialog, autocomplete, avatar, badge, breadcrumbs, button, button-group, card, checkbox, checkbox-group, chip, close-button, color-area, color-field, color-picker, color-slider, color-swatch, color-swatch-picker, combo-box, date-field, date-picker, date-range-picker, description, disclosure, disclosure-group, drawer, dropdown, empty-state, error-message, field-error, fieldset, form, header, input, input-group, input-otp, kbd, label, link, list-box, list-box-item, list-box-section, menu, menu-item, menu-section, meter, modal, number-field, pagination, popover, progress-bar, progress-circle, radio, radio-group, scroll-shadow, search-field, select, separator, skeleton, slider, spinner, surface, switch, switch-group, table, tabs, tag, tag-group, textarea, textfield, time-field, toast, toggle-button, toggle-button-group, toolbar, tooltip, typography
+
+### In Progress
+
+calendar, calendar-year-picker, range-calendar
+
+## Non-obvious Gotchas
+
+1. **`pnpm i` triggers builds** — The `postinstall` hook builds `@heroui/styles` and runs `typegen:docs`. If it fails, run `pnpm --filter @heroui/styles build` manually.
+
+2. **Build order matters** — `@heroui/styles` must build before `@heroui/react`. Running `pnpm build` from root handles this via Turbo's `^build` dependency.
+
+3. **Native addons allowlist** — The `pnpm.onlyBuiltDependencies` field in root `package.json` allows native compilation for `esbuild`, `@swc/core`, `@parcel/watcher`, etc. If this field is missing, you'll see "Ignored build scripts" warnings.
+
+4. **No tests yet** — `pnpm test` runs but finds no test files. The Vitest config exists at `packages/vitest`.
+
+5. **Commit hooks** — Husky runs `lint-staged` on pre-commit and `commitlint` on commit-msg. Non-conforming commits are rejected.
+
+6. **Run checks before committing** — `pnpm lint && pnpm typecheck`
+
+## Cursor Cloud Specific
+
+- **Node.js v22+** is installed via binary tarball to `/usr/local/`.
+- **pnpm** is activated via `corepack` — the `packageManager` field in root `package.json` declares `pnpm@10.26.2`.
+- Full command reference and component architecture details are also in `CLAUDE.md`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e1dc41e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,816 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+HeroUI v3 is a modern React UI library built with Tailwind CSS v4, using a pnpm monorepo structure managed by Turborepo.
+
+### Key Technical Stack
+
+- **Node.js**: v22+ required
+- **pnpm**: v10.9.0 (package manager)
+- **React**: v19+
+- **Tailwind CSS**: v4.1.4
+- **TypeScript**: v5.8.3
+- **Turborepo**: Build orchestration
+- **Storybook**: Component development
+- **Vitest**: Testing framework
+
+## Development Commands
+
+### Core Development Commands
+
+```bash
+# Install dependencies (use --hoist flag)
+pnpm i --hoist
+
+# Start Storybook for component development
+pnpm dev
+
+# Start documentation site
+pnpm dev:docs
+
+# Build all packages
+pnpm build
+
+# Build specific package
+pnpm build --filter=@heroui/react
+
+# Run linting
+pnpm lint
+
+# Run tests
+pnpm test
+
+# Test specific component
+pnpm test button
+
+# Run formatting
+pnpm run format
+
+# Run type checking
+pnpm typecheck
+```
+
+### Package-Specific Commands
+
+- Use `--filter` flag with package name: `pnpm build --filter=@heroui/react`
+- Main packages: `@heroui/react`, `@heroui/docs`, `@heroui/storybook`
+
+## Git Commit Convention
+
+**IMPORTANT**: This repository uses conventional commits with strict validation. All commits must follow this format:
+
+```
+<type>(<scope>): <message>
+```
+
+### Allowed Types:
+
+- `feat` / `feature`: New features
+- `fix`: Bug fixes
+- `refactor`: Code refactoring
+- `docs`: Documentation changes
+- `build`: Build system changes
+- `test`: Test changes
+- `ci`: CI configuration changes
+- `chore`: Other changes
+
+### Examples:
+
+```bash
+git commit -m "feat(components): add new prop to avatar component"
+git commit -m "fix(button): resolve click handler issue"
+git commit -m "docs: update installation guide"
+git commit -m "ci: add Claude Code GitHub Action workflow"
+```
+
+**Note**: Commits without proper format will be rejected by git hooks.
+
+## Repository Architecture
+
+### Monorepo Structure
+
+```
+/
+├── apps/
+│   └── docs/          # Documentation site (Next.js + Fumadocs)
+├── packages/
+│   ├── react/         # Main UI component library
+│   ├── standard/      # Shared ESLint, Prettier, TypeScript configs
+│   ├── storybook/     # Storybook configuration
+│   └── vitest/        # Shared Vitest configurations
+├── turbo.json         # Turborepo configuration
+└── pnpm-workspace.yaml # Workspace definition
+```
+
+### Component Architecture Pattern
+
+Each component in `packages/react/src/components/` follows this structure:
+
+```
+component-name/
+├── component-name.tsx      # Main component (uses React Aria)
+├── component-name.styles.ts # Tailwind Variants styling
+├── component-name.stories.tsx # Storybook stories (title: "Components/ComponentName")
+└── index.ts               # Barrel exports
+```
+
+**IMPORTANT**: All Storybook stories must use the "Components" group in their title. For example: `title: "Components/Card"`, `title: "Components/Button"`, etc.
+
+### CSS Class Naming Convention
+
+**IMPORTANT**: HeroUI v3 uses BEM (Block Element Modifier) style for CSS classes to ensure predictable and maintainable styling:
+
+- **Block**: The main component class (e.g., `button`, `card`, `alert`)
+- **Modifier**: Variations of the component using double dashes (e.g., `button--primary`, `button--lg`, `button--icon-only`)
+- **Element**: Child elements within a component (e.g., `card__header`, `alert__icon`)
+
+**Migration to CSS-based Styling**:
+
+- The `button` component has been migrated to use CSS styles from `@heroui/styles/src/components/button.css`
+- This approach allows for better customization through CSS utilities and `@utility` directives
+- Other components will gradually be migrated to follow this CSS-based pattern
+- Components use `tv()` from `tailwind-variants` to map variant props to BEM class names
+
+**Default Size Pattern**:
+
+**CRITICAL**: All components MUST include default sizes in their base classes to prevent broken appearances when no size modifier is specified. Following the following pattern:
+
+- **Base classes** include default dimensions (equivalent to the `--md` variant)
+- **Medium variants** (`--md`) are empty with explanatory comments
+- **Size modifiers** override the defaults when specified
+
+Example implementation:
+
+```css
+/* Base component with default size */
+.avatar {
+  @apply relative flex size-10 shrink-0 overflow-hidden rounded-full;
+  /* size-10 is the default, equivalent to --md */
+}
+
+/* Size variants */
+.avatar--sm {
+  @apply size-8; /* Override default */
+}
+
+.avatar--md {
+  /* No styles as this is the default size */
+}
+
+.avatar--lg {
+  @apply size-12; /* Override default */
+}
+```
+
+This ensures components work properly without explicit size classes:
+
+- `<div className="avatar">` → Works perfectly (size-10)
+- `<div className="avatar avatar--lg">` → Override to large (size-12)
+
+### Core Component Design Principles
+
+**IMPORTANT**: HeroUI v3 follows a compound component pattern similar to Radix UI, built on top of React Aria Components primitives. This enables maximum flexibility and customization for users.
+
+### React Aria Components Integration
+
+**CRITICAL**: Before implementing any component, you MUST:
+
+1. Visit React Aria Components docs: https://react-spectrum.adobe.com/react-aria/
+2. Study the specific component's API and examples
+3. Understand its accessibility features and ARIA patterns
+4. Plan the transformation from React Aria's prop-based API to Radix UI's composition-based API
+
+React Aria provides the accessibility foundation, but we transform their API to match Radix UI's compound component pattern for better customization.
+
+#### 1. **Compound Component Pattern**:
+
+- Export all internal component pieces (Root, Item, Trigger, Content, etc.)
+- Each piece can be styled and composed independently
+- Users can customize render logic without accessing internal code
+- Examples: Accordion (Root, Item, Heading, Trigger, Panel, Indicator, Body), Alert (Root, Icon, Title, Description, Action, Close)
+
+#### 2. **Export Strategy**:
+
+```typescript
+// Named exports for compound components
+export * as ComponentName from "./component-name";
+
+// Direct exports for simple components
+export {Component, type ComponentProps} from "./component";
+
+// Always export variants
+export {componentVariants, type ComponentVariants} from "./component.styles";
+```
+
+#### 3. **Component Structure for Compound Components**:
+
+```typescript
+// Context for sharing state/styles
+const ComponentContext = createContext<{slots?: ReturnType<typeof componentVariants>}>({});
+
+// Root component wraps with context
+const ComponentRoot = React.forwardRef<...>(({children, className, ...props}, ref) => {
+  const slots = React.useMemo(() => componentVariants({...}), [...]);
+
+  return (
+    <ComponentContext value={{slots}}>
+      <ReactAriaComponent ref={ref} className={composeTwRenderProps(className, slots.base())}>
+        {children}
+      </ReactAriaComponent>
+    </ComponentContext>
+  );
+});
+
+// Child components consume context
+const ComponentItem = React.forwardRef<...>(({className, ...props}, ref) => {
+  const {slots} = useContext(ComponentContext);
+
+  return (
+    <ReactAriaComponent ref={ref} className={composeTwRenderProps(className, slots?.item())}>
+      {props.children}
+    </ReactAriaComponent>
+  );
+});
+
+// Export pattern
+export {ComponentRoot as Root, ComponentItem as Item, ...};
+```
+
+#### 4. **Key Implementation Details**:
+
+1. **Styling with Tailwind Variants**:
+   - Styles defined in `.styles.ts` files using `tv()` function from `tailwind-variants`
+   - **IMPORTANT**: Always import from `tailwind-variants`, never from `@heroui/standard` (which doesn't exist)
+   - **CRITICAL**: tailwind-variants already includes `twMerge` functionality, so NEVER manually use `twMerge`
+   - **RULE**: All component styles MUST be defined in separate `.styles.ts` files, NOT in the component implementation files
+   - Component implementation files (`.tsx`) should only contain logic and React Aria primitives
+   - Example imports:
+     ```typescript
+     import type {VariantProps} from "tailwind-variants";
+     import {tv} from "tailwind-variants";
+     ```
+   - Support for variants (primary, secondary, etc.)
+   - Compound variants for conditional styling
+   - Slot system for complex components
+
+2. **Component Features**:
+   - Built on React Aria Components for accessibility
+   - Use `forwardRef` for all components
+   - Display names follow: `HeroUI.ComponentName` or `HeroUI.Component.SubPart`
+   - Support render props from React Aria when available
+
+3. **Type Exports**:
+
+   ```typescript
+   // Export props for each component part
+   export type ComponentRootProps = {...}
+   export type ComponentItemProps = {...}
+   export type ComponentVariants = VariantProps<typeof componentVariants>
+   ```
+
+4. **Utilities** (`packages/react/src/utils/`):
+   - `composeTwRenderProps`: Merge Tailwind classes with render props
+   - `focusRingClasses`: Consistent focus styling
+   - `disabledClasses`: Disabled state styling
+   - `mapPropsVariants`: Separate variant props from component props
+
+5. **React Aria Components className Patterns**:
+
+   **CRITICAL**: React Aria components have different className prop behaviors:
+
+   **Components that support render props** (use `composeTwRenderProps`):
+   - Button, TextField, FieldError, Checkbox, CheckboxGroup
+   - Switch, RadioGroup, Radio, Slider (and Track, Thumb, Output)
+   - Popover, Tooltip, Tabs (and Tab, TabList, TabPanel)
+   - Link, Menu, MenuItem, Accordion (DisclosureGroup)
+
+   **Components that ONLY accept string className** (pass className directly):
+   - Label, Text, Input, TextArea
+   - Heading, Dialog, OverlayArrow
+
+   **Usage examples**:
+
+   ```typescript
+   // For render prop components - use composeTwRenderProps
+   <ButtonPrimitive
+     className={composeTwRenderProps(className, slots?.button())}
+   />
+
+   // For string-only components - pass className directly
+   <LabelPrimitive
+     className={slots?.label({className})}
+   />
+   // OR
+   <LabelPrimitive
+     className={labelVariants({size, variant, className})}
+   />
+   ```
+
+   **How to check**: If unsure, check the React Aria docs or try both approaches - TypeScript will error if a component doesn't support render props
+
+6. **Composition Pattern with Existing Components**:
+
+   **CRITICAL**: HeroUI follows a composition-based approach. Components should reuse existing primitives rather than creating component-specific versions.
+
+   **Key Principles**:
+   - **DO NOT** create component-specific Label, Description, or FieldError components
+   - **DO** reuse the existing `Label`, `Description`, and `FieldError` components
+   - **DO** use standard HTML composition patterns with `htmlFor`/`id` attributes
+
+   **Example Pattern**:
+
+   ```typescript
+   // ❌ WRONG - Component-specific label
+   export const Checkbox = {
+     Root: CheckboxRoot,
+     Label: CheckboxLabel, // Don't create this!
+   };
+
+   // ✅ CORRECT - Compose with existing components
+   import { Label } from "@/components/label";
+   import { Description } from "@/components/description";
+
+   // Usage:
+   <div className="flex items-center gap-3">
+     <Checkbox id="terms">
+       <Checkbox.Indicator />
+     </Checkbox>
+     <Label htmlFor="terms">Accept terms</Label>
+   </div>
+
+   // With description:
+   <div className="flex gap-3">
+     <Checkbox className="mt-0.5" id="notifications">
+       <Checkbox.Indicator />
+     </Checkbox>
+     <div className="flex flex-col gap-1">
+       <Label htmlFor="notifications">Email notifications</Label>
+       <Description>Get notified when someone mentions you</Description>
+     </div>
+   </div>
+   ```
+
+   **Components that follow this pattern**:
+   - Checkbox - uses external Label/Description
+   - Radio - uses external Label/Description
+   - Switch - uses external Label/Description
+   - TextField - provides slots for Label/Description/FieldError
+
+### Current Components
+
+- `accordion`: Collapsible content sections
+- `alert`: Alert messages with compound components
+- `avatar`: User avatars with Radix UI
+- `button`: Button with variants and sizes
+- `checkbox`: Checkbox with compound components (uses external Label/Description)
+- `chip`: Small informational badges
+- `description`: Description text for form fields
+- `field-error`: Error messages for form fields
+- `fieldset`: Form field grouping components (Fieldset, Legend, FieldGroup, Field, CheckboxField)
+- `label`: Label text for form fields
+- `link`: Styled anchor links
+- `menu`: Dropdown menu system
+- `popover`: Popover overlays
+- `spinner`: Loading indicators
+- `tabs`: Tab navigation
+- `typography`: Typography component for headings, body copy, and prose
+- `textfield`: Text input field with compound components
+- `tooltip`: Hover tooltips
+
+## Development Workflow
+
+### Standard Feature Development Process
+
+**IMPORTANT**: When working on any feature or improvement, Claude Code MUST follow this systematic workflow to ensure accuracy and code quality:
+
+1. **Research Phase**:
+   - Thoroughly research the feature/component requirements
+   - Study relevant documentation (React Aria, Tailwind CSS, etc.)
+   - Analyze existing similar implementations in the codebase
+   - Identify all dependencies and integration points
+
+2. **Planning Phase**:
+   - Create a detailed implementation plan with a comprehensive checklist
+   - Break down the task into specific, measurable steps
+   - Include testing and verification steps in the plan
+   - Present the plan for review before proceeding
+
+3. **Review & Correction Phase**:
+   - Review the plan for completeness and accuracy
+   - Make necessary corrections or adjustments
+   - Ensure all edge cases are considered
+   - Confirm the plan aligns with HeroUI patterns and conventions
+
+4. **Execution Phase**:
+   - Start executing the plan step by step
+   - Use the TodoWrite tool to track progress automatically
+   - Mark todos as in_progress when starting a task
+   - Mark todos as completed immediately after finishing each step
+   - Never batch completions - update status in real-time
+
+5. **Verification Phase**:
+   - Manually verify all changes work as expected
+   - Test API calls if backend changes were made
+   - Check frontend rendering and interactions
+   - Run lint and type checks: `pnpm lint && pnpm typecheck`
+   - Ensure all tests pass: `pnpm test`
+
+**Example Workflow**:
+
+```
+User: "Add a new Select component"
+
+Claude:
+1. Research: Studies React Aria Select, existing patterns
+2. Plan: Creates detailed checklist with 15+ items
+3. Review: Presents plan for feedback
+4. Execute: Implements step-by-step with todo updates
+5. Verify: Tests component, runs checks, confirms functionality
+```
+
+This workflow ensures thorough understanding, proper planning, and high-quality implementation with full transparency throughout the process.
+
+### Component Development Workflow
+
+1. **Creating New Components**:
+
+   **CRITICAL: Research & Design Phase**:
+   - **FIRST**: Check the Figma design for the component breakdown (e.g., Menu Container, Menu Item, etc.)
+   - **SECOND**: Research the React Aria Components documentation at https://react-spectrum.adobe.com/react-aria/
+   - Find the appropriate React Aria primitive (e.g., CheckboxGroup, Dialog, Select, etc.)
+   - Understand the React Aria API, props, and accessibility features
+   - Map Figma component pieces to React Aria components and plan the compound structure
+   - Plan how to adapt it to follow Radix UI's compound component pattern
+
+   **Component Creation - ALWAYS USE THE SCRIPT**:
+
+   ```bash
+   # Navigate to packages/react directory
+   cd packages/react
+
+   # Use the add:component script
+   pnpm add:component ComponentName
+
+   # Examples:
+   pnpm add:component Menu
+   pnpm add:component Select
+   pnpm add:component DatePicker
+   ```
+
+   This script will:
+   - Create all necessary files with proper structure
+   - Add the export to `src/components/index.ts`
+   - Generate boilerplate following HeroUI patterns
+   - Set up the component with TypeScript and proper exports
+
+   After creating the component:
+
+   ```bash
+   # Build to update package.json exports automatically
+   pnpm build
+   ```
+
+   **Implementation Steps**:
+   - Study existing HeroUI components (accordion, alert) to understand the compound pattern
+   - Use React Aria Components as the foundation for accessibility
+   - Transform React Aria's API to match Radix UI patterns:
+     - Single component → Multiple exported parts (Item, Trigger, Content, etc.)
+     - Props-based API → Composition-based API
+     - Internal state → Context-based state sharing
+   - Create Context for sharing styles across component parts
+   - Export ALL component parts for maximum customization
+   - Define styles in separate `.styles.ts` file with slot system
+   - Add "use client" directive at the top of component file
+   - Create comprehensive Storybook stories showing all variants and compositions
+   - Follow the export pattern: `export * as ComponentName from "./component-name"`
+
+   **Example Transformation**:
+
+   ```typescript
+   // React Aria: Single component with props
+   <CheckboxGroup label="Options" value={selected} onChange={setSelected}>
+     <Checkbox value="1">Option 1</Checkbox>
+   </CheckboxGroup>
+
+   // HeroUI: Compound pattern
+   <CheckboxGroup value={selected} onValueChange={setSelected}>
+     <CheckboxGroup.Label>Options</CheckboxGroup.Label>
+     <CheckboxGroup.Item value="1">
+       <CheckboxGroup.Indicator />
+       <CheckboxGroup.Label>Option 1</CheckboxGroup.Label>
+     </CheckboxGroup.Item>
+   </CheckboxGroup>
+   ```
+
+   **Example of a compound component exports**
+
+   ```typescript
+   const CompoundAccordion = Object.assign(Accordion, {
+     Item: AccordionItem,
+     Heading: AccordionHeading,
+     Trigger: AccordionTrigger,
+     Panel: AccordionPanel,
+     Indicator: AccordionIndicator,
+     Body: AccordionBody,
+   });
+
+   export type {
+     AccordionProps,
+     AccordionItemProps,
+     AccordionTriggerProps,
+     AccordionPanelProps,
+     AccordionIndicatorProps,
+     AccordionBodyProps,
+   };
+
+   export default CompoundAccordion;
+   ```
+
+   **IMPORTANT**: The compound component should be exported as the default export.
+
+2. **Testing**:
+   - Run `pnpm test` for all tests
+   - Run `pnpm test <component>` for specific component
+   - Ensure all new features have tests
+
+3. **Documentation**:
+   - Docs live in `apps/docs/content/`
+   - Uses MDX format
+   - HeroUI components are pre-imported
+
+4. **Version Management**:
+   - Uses [bumpp](https://github.com/antfu/bumpp) for version bumping
+   - Run `pnpm version:bump` to interactively bump the version, commit, and tag
+   - Pushing a `v*` tag triggers the release CI workflow
+   - Follow semantic versioning
+
+## Icon Library
+
+**IMPORTANT**: HeroUI uses Iconify with gravity-ui as the default icon set.
+
+## Important Notes
+
+- Always prefer editing existing files over creating new ones
+- **NEVER** create documentation files (_.md, _.mdx, README files) unless explicitly requested by the user
+- Follow the established component patterns and conventions
+- Ensure accessibility with React Aria Components
+- Maintain TypeScript type safety
+- Use the commit convention to avoid git hook failures
+- Run lint and type checks before committing: `pnpm lint && pnpm typecheck`
+
+## Tailwind CSS Class Detection Rules
+
+**CRITICAL**: Tailwind CSS scans files as plain text and requires complete class names to be statically detectable.
+
+### Key Rules:
+
+1. **Never construct class names dynamically**
+
+   ❌ **BAD** - Dynamic string concatenation:
+
+   ```jsx
+   // These patterns will NOT work:
+   <div className={`text-${color}-600`} />
+   <button className={`bg-${variant}-500`} />
+   <span className={`button--${size}`} />
+   ```
+
+   ✅ **GOOD** - Complete class names:
+
+   ```jsx
+   // Use complete strings or object mappings:
+   <div className={error ? "text-red-600" : "text-green-600"} />
+   ```
+
+2. **Use object mappings for dynamic classes**
+
+   ❌ **BAD** - Props in template literals:
+
+   ```jsx
+   function Button({color}) {
+     return <button className={`bg-${color}-600 hover:bg-${color}-500`} />;
+   }
+   ```
+
+   ✅ **GOOD** - Map props to complete classes:
+
+   ```jsx
+   function Button({color}) {
+     const colorVariants = {
+       blue: "bg-blue-600 hover:bg-blue-500",
+       red: "bg-red-600 hover:bg-red-500",
+     };
+     return <button className={colorVariants[color]} />;
+   }
+   ```
+
+3. **For BEM-style classes, use complete mappings**
+
+   ✅ **GOOD** - Complete class name mappings:
+
+   ```jsx
+   const sizeClasses = {
+     sm: "button--sm",
+     md: "button--md",
+     lg: "button--lg",
+   };
+
+   // Use the mapping:
+   className={sizeClasses[size]}
+   ```
+
+### Why This Matters:
+
+- Tailwind generates CSS only for classes it can detect in your source files
+- Dynamic concatenation prevents Tailwind from finding the complete class names
+- Missing classes = missing styles in production
+
+## Figma Integration & MCP Server Rules
+
+### Figma Dev Mode MCP Server
+
+**IMPORTANT**: When creating components with Figma designs:
+
+1. **Component Breakdown**: Figma designs are already broken down into component pieces (e.g., Menu Container, Menu Item, etc.). Use these as reference for:
+   - Component structure and naming (adapt to code conventions)
+   - Visual styling and spacing
+   - Component composition patterns
+
+2. **MCP Server Rules**:
+   - The Figma Dev Mode MCP Server provides an assets endpoint for images and SVG assets
+   - **CRITICAL**: If the Figma MCP Server returns a localhost source for an image or SVG, use that source directly
+   - **DO NOT** import or add new icon packages - all assets should come from the Figma payload
+   - **DO NOT** use or create placeholders if a localhost source is provided
+   - Always use the actual assets from Figma MCP Server
+
+3. **Workflow**:
+   - Check Figma for component visual design and breakdown
+   - Map Figma component names to appropriate React Aria primitives
+   - Use Figma assets (icons, images) directly from the MCP Server
+   - Implement styles based on Figma design tokens and specifications
+
+## Library Documentation with Context7 MCP
+
+**IMPORTANT**: We have the Context7 MCP server available (https://github.com/upstash/context7) for accessing up-to-date library documentation.
+
+### When to Use Context7
+
+Use Context7 MCP when working with external libraries, especially:
+
+- **Tailwind CSS v4**: When working with Tailwind CSS v4 features, use Context7 to get the latest documentation at https://context7.com/context7/tailwindcss
+- **Fumadocs**: When working on the documentation site in `apps/docs/`, use Context7 to get the latest Fumadocs framework documentation
+- **Next.js**: For Next.js specific features and APIs used in the docs app
+- Any other third-party libraries where up-to-date documentation is needed
+
+### How to Use Context7
+
+1. First, resolve the library ID using `mcp__context7__resolve-library-id`
+2. Then fetch documentation using `mcp__context7__get-library-docs` with the resolved ID
+3. This ensures you're always working with the latest documentation rather than outdated information
+
+### Example Usage Areas
+
+- Implementing new documentation features in `apps/docs/`
+- Configuring Fumadocs settings in `source.config.ts`
+- Working with MDX components and layouts
+- Setting up search functionality
+- Implementing documentation navigation and structure
+
+## GitHub Repository Search with Grep MCP
+
+**IMPORTANT**: We have the Grep MCP server available for searching over a million public GitHub repositories to find real-world code examples and patterns.
+
+### When to Use Grep MCP
+
+Use the Grep MCP (`mcp__grep__searchGitHub`) when tackling complex problems that require:
+
+- **Real-world implementation examples**: Finding how other developers solve similar problems
+- **Best practices and patterns**: Discovering production-ready code patterns
+- **Library usage examples**: Understanding how specific APIs or libraries are used in practice
+- **Complex integrations**: Seeing how different libraries work together
+- **Error handling patterns**: Learning from battle-tested error handling approaches
+
+### How to Use Grep MCP
+
+The Grep MCP searches for **literal code patterns**, not keywords. Use actual code syntax:
+
+**Good examples**:
+
+- `'useState('` - Find React hooks usage
+- `'import { tv } from "tailwind-variants"'` - Find tailwind-variants imports
+- `'forwardRef<'` - Find forwardRef usage patterns
+- `'(?s)useEffect\\(\\(\\) => {.*return.*}'` - Find useEffect with cleanup (regex)
+
+**Bad examples**:
+
+- `'react best practices'` - This is a keyword, not code
+- `'how to use tailwind'` - Use actual import statements instead
+
+### Example Use Cases
+
+1. **Complex Component Patterns**:
+   - Search: `'compound.*component'` with language=['TypeScript', 'TSX']
+   - Find how others implement compound component patterns
+
+2. **Accessibility Implementations**:
+   - Search: `'AriaProps'` or `'useAriaLabel'`
+   - Discover accessibility patterns in React apps
+
+3. **Monorepo Configurations**:
+   - Search: `'pnpm-workspace.yaml'` with path='pnpm-workspace.yaml'
+   - Study monorepo setups similar to HeroUI
+
+4. **Tailwind CSS v4 Patterns**:
+   - Search: `'@import "tailwindcss"'` with language=['CSS']
+   - Find Tailwind CSS v4 usage patterns
+
+5. **React Aria Components Usage**:
+   - Search: `'from "react-aria-components"'`
+   - See how others integrate React Aria Components
+
+### Best Practices
+
+- Use language filters to narrow results (e.g., `language=['TypeScript', 'TSX']`)
+- Use regex patterns with `useRegexp=true` for flexible matching
+- Filter by well-known repositories for quality examples (e.g., `repo='vercel/'`)
+- Combine with file path filters for specific file types
+
+## Agent-Specific Guidelines
+
+### For style-migrator and tailwind-v4-css-expert Agents
+
+When working with HeroUI CSS components, follow these critical patterns:
+
+#### Default Size Implementation
+
+**REQUIRED**: All CSS components MUST follow the default size pattern:
+
+1. **Base classes** include default dimensions equivalent to `--md` variant
+2. **Medium variant** (`--md`) is an empty class with explanatory comment
+3. **Size variants** override the base defaults
+
+**Template for CSS components with size variants:**
+
+```css
+/* Base component styles */
+.component {
+  /* Base styling */
+  @apply [base-styles];
+
+  /* Default size - matches component--md variant */
+  @apply [default-size-classes];
+}
+
+/* Size variants */
+.component--sm {
+  @apply [small-size-overrides];
+}
+
+.component--md {
+  /* No styles as this is the default size */
+}
+
+.component--lg {
+  @apply [large-size-overrides];
+}
+```
+
+#### Pseudo-Class Fallback Pattern
+
+**REQUIRED**: All interactive components MUST include both pseudo-class and data-attribute support:
+
+```css
+/* Interactive states - both approaches */
+.component {
+  /* Hover states */
+  &:hover,
+  &[data-hovered="true"] {
+    @apply [hover-styles];
+  }
+
+  /* Active/pressed states */
+  &:active,
+  &[data-pressed="true"] {
+    @apply [active-styles];
+  }
+
+  /* Focus states */
+  &:focus-visible,
+  &:focus:not(:focus-visible),
+  &[data-focus-visible="true"] {
+    outline: 2px solid var(--focus);
+    outline-offset: 2px;
+  }
+}
+```
+
+#### Component Examples
+
+- **button.css**: Base has `h-10 md:h-9`, empty `.button--md` variant
+- **avatar.css**: Base has `size-10`, empty `.avatar--md` variant
+- **spinner.css**: Base has `size-6`, empty `.spinner--md` variant
+
+These patterns ensure components never appear broken and maintain consistency across the design system.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..bc9a51f
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at jrgarciadev@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3f0a792
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,232 @@
+# HeroUI Contributing Guide
+
+Hello!, I am very excited that you are interested in contributing with HeroUI. However, before submitting your contribution, be sure to take a moment and read the following guidelines.
+
+- [Code of Conduct](https://github.com/heroui-inc/heroui/blob/canary/CODE_OF_CONDUCT.md)
+- [Extraction request guidelines](#pull-request-guidelines)
+- [Development Setup](#development-setup)
+- [Tests](#tests)
+- [Visual Changes](#visual-changes)
+- [Documentation](#documentation)
+- [Breaking Changes](#breaking-changes)
+- [Becoming a maintainer](#becoming-a-maintainer)
+
+### Tooling
+
+- [PNPM](https://pnpm.io/) to manage packages and dependencies
+- [Tsup](https://tsup.egoist.dev/) to bundle packages
+- [Storybook](https://storybook.js.org/) for rapid UI component development and
+  testing
+- [Testing Library](https://testing-library.com/) for testing components and
+  hooks
+- [bumpp](https://github.com/antfu/bumpp) for version bumping and release
+  management.
+
+
+### Commit Convention
+
+Before you create a Pull Request, please check whether your commits comply with
+the commit conventions used in this repository.
+
+When you create a commit we kindly ask you to follow the convention
+`category(scope or module): message` in your commit message while using one of
+the following categories:
+
+- `feat / feature`: all changes that introduce completely new code or new
+  features
+- `fix`: changes that fix a bug (ideally you will additionally reference an
+  issue if present)
+- `refactor`: any code related change that is not a fix nor a feature
+- `docs`: changing existing or creating new documentation (i.e. README, docs for
+  usage of a lib or cli usage)
+- `build`: all changes regarding the build of the software, changes to
+  dependencies or the addition of new dependencies
+- `test`: all changes regarding tests (adding new tests or changing existing
+  ones)
+- `ci`: all changes regarding the configuration of continuous integration (i.e.
+  github actions, ci system)
+- `chore`: all changes to the repository that do not fit into any of the above
+  categories
+
+  e.g. `feat(components): add new prop to the avatar component`
+
+
+If you are interested in the detailed specification you can visit
+https://www.conventionalcommits.org/ or check out the
+[Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).
+
+## Pull Request Guidelines
+
+- The `main` branch is basically a snapshot of the latest production version. All development must be done in dedicated branches and will be merged to `canary` branch.
+- Make sure that Github Actions are green
+- It is good to have multiple small commits while working on the PR. We'll let GitHub squash it automatically before the merge.
+- If you add a new feature:
+  - Add the test case that accompanies it.
+  - Provide a compelling reason to add this feature. Ideally, I would first open a suggestion topic and green it before working on it.
+- If you correct an error:
+  - If you are solving a special problem, add (fix #xxxx [, # xxx]) (# xxxx is the problem identification) in your PR title for a better launch record, for example update entities encoding / decoding (fix # 3899).
+  - Provide a detailed description of the error in the PR. Favorite live demo.
+  - Add the appropriate test coverage, if applicable.
+
+
+### Steps to PR
+
+1. Fork of the heroui repository and clone your fork
+
+2. Create a new branch out of the `canary` branch. We follow the convention
+   `[type/scope]`. For example `fix/dropdown-hook` or `docs/menu-typo`. `type`
+   can be either `docs`, `fix`, `feat`, `build`, or any other conventional
+   commit type. `scope` is just a short id that describes the scope of work.
+
+3. Make and commit your changes following the
+   [commit convention](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md#commit-convention).
+   As you canary, you can run `pnpm build --filter=<module>` and
+   `pnpm test packages/<module>/<pkg>` e.g. `pnpm build --filter=avatar & pnpm test packages/components/avatar` to make sure everything works as expected.
+
+   > To know more about the `--filter` option, please check the turborepo [docs](https://turborepo.org/docs/core-concepts/filtering).
+
+4. Version bumping is handled by maintainers using `pnpm version:bump` which
+   uses [bumpp](https://github.com/antfu/bumpp) to interactively bump the
+   version, create a git commit, and push a tag that triggers the release CI.
+
+## Development Setup
+
+After cloning the repository, execute the following commands in the root folder:
+
+1. Install dependencies
+
+```bash
+pnpm i --hoist
+
+#or
+
+pnpm install --hoist
+```
+
+We use [Turbo Repo](https://turborepo.org/) for the project management.
+
+2. If you will be working on the components source code, you can use the following command to start the webpack dev server:
+
+```bash
+## Start the dev babel server of HeroUI core components
+pnpm dev
+
+## optional
+
+pnpm sb ## this will start the storybook server for a faster development and testing.
+
+pnpm dev:docs ## this will start the documentation next.js server and it will automatically detect the changes in the components.
+```
+
+- If you will be working just on the documentation source code / mdx, you can use the following commands to build
+  HeroUI components and then start the next.js dev server:
+
+```bash
+## Build HeroUI source components
+pnpm build
+
+## Start the next.js documentation dev server
+pnpm dev:docs
+```
+
+- You also can use Storybook to test the components and faster development:
+
+```bash
+pnpm sb
+```
+
+Remember that these commands must be executed in the root folder of the project.
+
+3. Create a branch for your feature or fix:
+
+```bash
+# Move into a new branch for your feature
+git checkout -b feat/thing
+```
+
+```bash
+# Move into a new branch for your fix
+git checkout -b fix/something
+```
+
+4. If your code passes all the tests, then push your feature/fix branch:
+
+All commits that fix bugs or add features need a test.
+You can run the nest command for component specific tests.
+
+```bash
+# Test current code
+
+pnpm test
+
+# or
+
+npm run test
+```
+
+```bash
+# Test isolated component code
+
+pnpm test button
+
+# or
+
+npm run test button
+
+```
+
+5. Be sure the package builds.
+
+```bash
+# Build current code
+
+pnpm build
+
+# or
+
+npm run build
+```
+
+> Note: ensure that you have at least Node.js 20.16.0 as well as pnpm 9.6.0 or higher installed on your machine to run the scripts
+
+6. Send your pull request:
+
+- Send your pull request to the `canary` branch
+- Your pull request will be reviewed by the maintainers and the maintainers will decide if it is accepted or not
+- Once the pull request is accepted, the maintainers will merge it to the `canary` branch
+
+## Visual Changes
+
+When making a visual change, please provide screenshots
+and/or screencasts of the proposed change. This will help us to understand the
+desired change easier.
+
+Until HeroUI has a stable release new components will be created only for the core team.
+
+## Documentation
+
+Please update the docs with any API changes, the code and docs should always be in sync.
+
+The main documentation lives in the `apps/docs/content` folder, the project uses MDX and all `HeroUI` are already imported.
+
+## Breaking changes
+
+Breaking changes should be accompanied with deprecations of removed functionality. The deprecated APIs themselves should not be removed until the minor release after that.
+
+## Becoming a maintainer
+
+If you are interested in becoming a HeroUI maintainer, start by
+reviewing issues and pull requests. Answer questions for those in need of
+troubleshooting. Join us in the
+[Discord Community](https://discord.gg/9b6yyZKmH4) chat room.
+Once we see you helping, either we will reach out and ask you if you want to
+join or you can ask one of the current maintainers to add you. We will try our
+best to be proactive in reaching out to those that are already helping out.
+
+GitHub by default does not publicly state that you are a member of the
+organization. Please feel free to change that setting for yourself so others
+will know who's helping out. That can be configured on the [organization
+list](https://github.com/orgs/heroui-inc/people) page.
+
+Being a maintainer is not an obligation. You can help when you have time and be
+less active when you don't. If you get a new job and get busy, that's alright.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..bf4dfe2
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/README.md b/README.md
new file mode 120000
index 0000000..87d4101
--- /dev/null
+++ b/README.md
@@ -0,0 +1 @@
+packages/react/README.md
\ No newline at end of file
diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..c013bbf
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`nextui-org/nextui`
+- 原始仓库：https://github.com/nextui-org/nextui
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
diff --git a/apps/docs/.env.example b/apps/docs/.env.example
new file mode 100644
index 0000000..8f603e6
--- /dev/null
+++ b/apps/docs/.env.example
@@ -0,0 +1,11 @@
+NEXT_PUBLIC_APP_ENV="production,preview,development"
+NEXT_PUBLIC_CDN_URL="<cdn-url>"
+LOOPS_API_ENDPOINT="<LOOPS_API_ENDPOINT>"
+LOOPS_API_KEY="<LOOPS_API_KEY>"
+FEATUREBASE_API_ENDPOINT="<FEATUREBASE_API_ENDPOINT>"
+FEATUREBASE_API_KEY="<FEATUREBASE_API_KEY>"
+NEXT_PUBLIC_PRO_API_URL="<PRO_API_URL>"
+NEXT_PUBLIC_PRO_URL="<PRO_URL>"
+NEXT_PUBLIC_SHOW_PRE_SALE_BANNER="true"
+NEXT_PUBLIC_POSTHOG_HOST="<POSTHOG_HOST>"
+NEXT_PUBLIC_POSTHOG_KEY="<POSTHOG_KEY>"
diff --git a/apps/docs/.npmrc b/apps/docs/.npmrc
new file mode 100644
index 0000000..6c59086
--- /dev/null
+++ b/apps/docs/.npmrc
@@ -0,0 +1 @@
+enable-pre-post-scripts=true
diff --git a/apps/docs/content/blog/cn/best-react-ui-component-libraries.mdx b/apps/docs/content/blog/cn/best-react-ui-component-libraries.mdx
new file mode 100644
index 0000000..f753918
--- /dev/null
+++ b/apps/docs/content/blog/cn/best-react-ui-component-libraries.mdx
@@ -0,0 +1,266 @@
+---
+title: "2026 年 12 个最佳 React UI 组件库"
+description: "对比 2026 年 12 个最佳 React UI 组件库：HeroUI、shadcn/ui、MUI、Chakra UI、Mantine 等。涵盖功能特性、可访问性与 AI 工具支持。"
+date: "2026-05-16"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["react", "ui-libraries", "comparison"]
+image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png"
+darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png"
+---
+
+选择合适的 React UI 组件库，会直接影响你的开发体验。2026 年最佳的 React UI 组件库都提供了开箱即用、可访问性良好的生产级组件，让你专注于产品功能，而不是第 N 次重新实现下拉菜单。
+
+我从样式方案、可访问性基础、组件广度、AI 工作流支持和授权许可这几个维度，对比了 12 个库。各项目的组件数量与定价随时可能变化，因此请将本文视为一份实用的速查指南，最终决策前请查阅各自的官方文档。
+
+
+<h2 className="blog-table-heading mt-10 text-xl font-semibold text-muted">速览对比</h2>
+
+| 组件库 | 样式方案 | 可访问性基础 | 组件广度 | AI 工作流 |
+|---------|---------|--------------------------|---------|-------------|
+| **HeroUI** | Tailwind CSS v4 | React Aria | <ComponentCount />+ 个组件，<ExampleCount />+ 个示例 | MCP 服务器、llms.txt、agent skills |
+| **shadcn/ui** | Tailwind CSS | Radix UI 及其他基础组件 | 官方文档列出 59 个组件条目 | MCP 服务器、llms.txt、skills |
+| **Material UI** | 默认使用 Emotion，可接入 Pigment CSS | MUI 自研实现 | 核心组件 + MUI X，覆盖极广 | 公开文档 |
+| **Chakra UI** | 基于 Panda CSS API 的体系 | Chakra / Ark UI 生态 | 应用层组件覆盖广泛 | MCP 服务器与公开文档 |
+| **Mantine** | CSS 文件 / CSS Modules | Mantine 自研实现 | 120+ 个组件，70+ 个 hooks | MCP 服务器、llms.txt、skills |
+| **Radix UI** | 无样式 | Radix 基础组件 | 聚焦基础组件 | 公开文档 |
+| **Ant Design** | CSS-in-JS / Token 体系 | Ant Design 自研实现 | 偏企业级 | 公开文档 |
+| **Headless UI** | 无样式 | Headless UI 基础组件 | 聚焦基础组件 | 公开文档 |
+| **React Aria** | 无样式 | React Aria | 深度的基础原语层 | 公开文档 |
+| **Ark UI** | 无样式 | Zag.js 状态机 | Headless 组件 | 公开文档 |
+| **Tremor** | Tailwind CSS v4 | 面向仪表盘的组件 | 数据分析 / 数据展示 | 公开文档 |
+| **Park UI** | Panda CSS / Tailwind | Ark UI | 带样式的 Ark 组件 | 公开文档 |
+
+## 1. HeroUI
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+  alt="HeroUI - Beautiful by default, customizable by design"
+/>
+
+[HeroUI](https://heroui.com) 将 [React Aria](https://react-spectrum.adobe.com/react-aria/) 的可访问性能力与 [Tailwind CSS v4](https://tailwindcss.com/) 样式系统、以及复合组件 API（`Card.Header`、`Table.Column`、`Modal.Body`）结合在一起。组件原生支持 React 19 与 Next.js App Router。
+
+**核心优势：**
+
+- **可访问性优先的架构。** 每个组件都构建在 React Aria 之上 —— Adobe 经过大规模生产验证的可访问性原语。这意味着屏幕阅读器支持、键盘导航和 ARIA 属性都是开箱即用、正确实现的，而不是事后再补上的功能。
+- **原生支持 Tailwind CSS v4。** HeroUI 的样式系统采用基于 CSS 的主题方案，通过 `@theme` 与设计 token 实现，避免了 CSS-in-JS 的运行时开销。
+- **复合组件 API。** 组件采用可组合的模式（`Card.Header`、`Card.Content`、`Card.Footer`），让你在不牺牲易用性的前提下完全掌控标签结构与布局。
+- **AI 工具支持。** HeroUI 提供了 [MCP 服务器](/docs/react/getting-started/mcp-server)、[llms.txt](/docs/react/getting-started/llms-txt) 和 [agent skills](/docs/react/getting-started/agent-skills)，让 AI 编码助手能查到最新的 HeroUI API，而不必只依赖训练数据。
+- **对服务端组件友好。** 组件在设计时就考虑了 React Server Components —— 客户端边界精简且文档清晰。
+
+**适用场景：** 你需要一个现代化、可访问性良好的组件库，搭配 Tailwind CSS 样式系统和一流的 AI 工具支持。非常适合使用 Next.js、React 19 与 Tailwind v4 的新项目。
+
+---
+
+## 2. shadcn/ui
+
+[shadcn/ui](https://ui.shadcn.com/) 并不是传统意义上的组件库 —— 它是基于 Radix UI 与 Tailwind CSS 的一组可复制粘贴的组件。你不需要安装某个 npm 包，而是把组件源码直接加入项目。
+
+**核心优势：**
+
+- **完全的所有权。** 组件代码就在你的代码库里，可以随意修改，无需对抗库的抽象，也不必等待上游变更。
+- **基于 Radix UI 的可访问性。** 底层原语稳定地处理了弹出层、下拉选择、对话框等复杂交互的可访问性。
+- **CLI 工具。** `shadcn` CLI 可以将组件、依赖与文件结构一键脚手架到你的项目中。
+- **面向 AI 的文档。** shadcn/ui 同时发布了 `llms.txt`、skills 以及 MCP 服务器，供 AI 代理使用。
+- **庞大的生态。** 社区围绕 shadcn 的模式构建了数百个扩展、主题与集成方案。
+
+**适用场景：** 你希望对组件代码拥有最大控制权，并愿意自己维护这些被复制进来的组件。适合需要大量定制化的团队。
+
+**权衡点：** 你拥有代码，也就拥有了 bug。上游的修复和改进都需要手动重新合并，没有集中式的升级机制。此外，shadcn/ui 建立在 Radix UI 之上，存在一定的不确定性 —— 原 Radix 团队已将重心转向 Base UI，Radix 基础组件的长期维护状态在社区中仍是一个悬而未决的问题。
+
+---
+
+## 3. Material UI (MUI)
+
+[Material UI](https://mui.com/) 是最成熟的 React 组件库，已在生产环境中使用了十年。MUI 稳定的样式路径仍然以 Emotion 与 `sx` prop 为核心；Pigment CSS 则作为零运行时的实验性方向存在，并非默认选项。
+
+**核心优势：**
+
+- **组件数量庞大。** 拥有超过 70 个组件，几乎覆盖了你能想到的所有 UI 模式 —— 从基础按钮到复杂的数据网格。
+- **遵循 Material Design。** 如果你的设计系统基于 Material Design，MUI 可以提供像素级精准的实现。
+- **企业级生态。** MUI X 提供高级组件（数据网格、日期选择器、图表），并附带企业级支持与 SLA。
+- **成熟且久经考验。** 数以千计的生产应用运行在 MUI 之上，多年来许多边缘场景都已被发现并修复。
+
+**适用场景：** 你正在构建一个大型企业级应用，需要遵循 Material Design 规范，或者需要使用 MUI X 的高级数据网格和日期选择器组件。
+
+**权衡点：** Material Design 的美学风格非常鲜明。把它改造成完全不同的外观虽然可行，但需要相当大的投入。包体积也比大多数同类方案更大。
+
+---
+
+## 4. Chakra UI
+
+[Chakra UI](https://chakra-ui.com/) 在 React 中率先推广了 "style props" 模式，让你能用 `bg="blue.500"`、`p={4}` 这样的 props 来设置样式。Chakra 当前的主题文档描述了一套围绕 Panda CSS API 构建的体系，包含 `defineConfig`、`createSystem`、recipes、slot recipes、tokens 与语义化 tokens。
+
+**核心优势：**
+
+- **直观的样式 API。** Style props 让你不必离开 JSX，就能快速完成设计的原型与迭代。
+- **设计 token 体系。** 通过 theme 对象集中管理颜色、间距、字体和断点。
+- **良好的可访问性默认值。** 组件遵循 WAI-ARIA 模式并内置键盘导航支持。
+- **基于 recipe 的样式方案。** Chakra 使用 recipe、slot recipe 与基于 token 的体系来组织组件样式。
+- **AI 支持。** Chakra 提供了用于 AI 辅助工作流的 MCP 服务器文档。
+
+**适用场景：** 你更喜欢通过 props 而非 class 名来设置样式，并且希望拥有一套默认值统一的设计系统。
+
+**权衡点：** 对于复杂组件，style props 模式会让 JSX 显得比较冗杂。从 v2 升级到 v3 需要较多改动，因为组件与主题 API 都发生了变化。
+
+---
+
+## 5. Mantine
+
+[Mantine](https://mantine.dev/) 是一个功能非常齐全的 React 组件库，组件目录非常宽广，还附带一个 hooks 包以及丰富的扩展生态。Mantine 官网当前将该库描述为提供 `120+` 个组件和 `70+` 个 hooks。
+
+**核心优势：**
+
+- **覆盖面无可匹敌。** Mantine 拥有大量组件和扩展，几乎涵盖各种产品需求 —— 日期选择器、通知、Spotlight 搜索、图表、表单等等。
+- **庞大的 hooks 包。** 除了组件之外，Mantine 还提供了 localStorage、媒体查询、剪贴板、空闲检测等大量常用模式的 hooks。
+- **基于 CSS 的样式方案。** Mantine 组件基于 CSS 文件构建，可通过 Styles API 进行自定义。
+- **AI 工具支持。** Mantine 提供了 LLM 文档、skills 与 MCP 服务器。
+- **表单库。** `@mantine/form` 提供了状态管理与校验的能力，可以与 Mantine 输入组件无缝集成。
+
+**适用场景：** 你想要一个开箱即用、包罗万象的库，几乎任何使用场景都能找到对应组件，而无需再引入第三方包。
+
+**权衡点：** 巨大的表面积意味着如果不仔细做 tree-shaking，包体积会迅速膨胀。组件设计风格虽然简洁，但相对鲜明。
+
+---
+
+## 6. Radix UI (Primitives)
+
+[Radix UI](https://www.radix-ui.com/) 提供了一组无样式、可访问的 UI 基础组件，由你自行决定如何赋予样式。它是 shadcn/ui 以及许多其他组件库的底层基础。
+
+**核心优势：**
+
+- **可访问性标杆。** 每个基础组件都按照 WAI-ARIA 规范构建，键盘导航、焦点管理与屏幕阅读器支持都极其完善。
+- **默认无样式。** 不预设任何设计立场，也就不必和库的美学风格博弈。把你自己的样式体系带上即可。
+- **可组合的 API。** 基础组件采用复合组件模式，通过基于 slot 的组合方式，让你对每一个被渲染的元素都有掌控权。
+- **经过生产验证。** 通过直接使用以及 shadcn/ui，Radix 基础组件已经支撑了数千个生产应用。
+
+**适用场景：** 你需要只提供行为、不带样式的可访问基础组件，并希望对样式有完全控制权。非常适合构建定制化设计系统的团队。
+
+**权衡点：** 所有样式都需要自己实现。对于较简单的使用场景，组合模式的学习曲线可能略陡。
+
+---
+
+## 7. Ant Design
+
+[Ant Design](https://ant.design/) 是由蚂蚁集团（阿里巴巴）创建的综合性设计系统与组件库，在企业级应用以及中国开发者社区中尤为流行。
+
+**核心优势：**
+
+- **企业级组件。** Table（支持排序、过滤、分页）、Form（带校验）、Tree 等复杂组件都非常成熟、功能丰富。
+- **附带完整的设计系统。** Ant Design 不仅是组件库，还是一套完整的设计系统，包括设计 tokens、模式与规范指南。
+- **国际化支持出色。** 一流的 i18n 支持，提供 60+ 个本地化包。
+- **组件质量高。** 每个组件都处理了大量边缘情况，你自己实现的话需要花费大量时间。
+
+**适用场景：** 你正在构建复杂的企业级应用，尤其是需要复杂数据表格、表单与树形视图的场景。
+
+**权衡点：** 设计风格非常鲜明的 "Ant Design 范"，要改造成不同的外观需要相当多的工作。包体积较大。可访问性虽然在不断改进，但仍落后于基于 Radix / React Aria 的库。
+
+---
+
+## 8. Headless UI
+
+[Headless UI](https://headlessui.com/) 是 Tailwind Labs 团队提供的一组无样式、可访问的 UI 组件，专注于常见的交互模式 —— 下拉菜单、对话框、Tabs、组合框等。
+
+**核心优势：**
+
+- **与 Tailwind CSS 深度集成。** 出自 Tailwind 团队，与 Tailwind 的工具类与过渡工具配合得天衣无缝。
+- **小巧而聚焦。** 仅覆盖那些真正难以做到可访问的组件（菜单、列表框、对话框等）。
+- **轻量。** 由于聚焦的组件集合，对包体积的影响极小。
+- **简洁的 API。** 使用 render props 和复合组件，API 简单且可预测。
+
+**适用场景：** 你正在使用 Tailwind CSS，需要少量可访问的交互组件，但不想引入一整套 UI 库。
+
+**权衡点：** 组件集合非常小 —— 数据表格、表单输入、日期选择器等大多数模式都需要另寻他解。
+
+---
+
+## 9. React Aria (Primitives)
+
+[React Aria](https://react-spectrum.adobe.com/react-aria/) 是 Adobe 出品的 React 可访问性原语库。它提供 hooks 与组件，帮助你从零构建可访问的 UI。
+
+**核心优势：**
+
+- **业界领先的可访问性。** React Aria 可以说是目前可用的最完善的可访问性原语库。它处理了国际化、从右到左布局、触摸交互，以及大多数库都会忽略的边缘情况。
+- **Hooks + 组件。** 同时提供低层 hooks（最大灵活性）与高层组件（更便捷）。
+- **平台感知。** 根据设备类型、指针类型与平台惯例自动调整行为。
+- **众多库的底层基础。** HeroUI、Adobe Spectrum 以及其他库都建立在 React Aria 之上，证明了它在大规模场景下的可靠性。
+
+**适用场景：** 你正在从零构建设计系统，需要尽可能强大的可访问性基础。当你需要特定基础组件（例如颜色选择器或日历）而其他库无法提供时，它也很有用。
+
+**权衡点：** 比带样式的库学习曲线更陡。你需要自行实现所有样式与组合模式。
+
+---
+
+## 10. Ark UI
+
+[Ark UI](https://ark-ui.com/) 出自 Chakra UI 的作者团队，是一个 headless 组件库，底层基于状态机，行为高度可预测。
+
+**核心优势：**
+
+- **状态机架构。** 底层使用 Zag.js 状态机，组件行为可预测、易于调试。
+- **框架无关的内核。** 同一套状态机驱动每个组件的 React、Vue 与 Solid 版本。
+- **现代模式。** 提供了签名板、Pin 输入框、分栏器等其他 headless 库中较少见的组件。
+- **样式方案灵活。** 可搭配任何样式方案 —— Tailwind、Panda CSS、原生 CSS、CSS Modules 都行。
+
+**适用场景：** 你想要带可预测状态管理的 headless 组件，或者需要在 React、Vue 与 Solid 项目之间复用组件逻辑。
+
+**权衡点：** 社区规模小于 Radix 或 React Aria。状态机抽象在简单组件上会带来额外的概念负担。
+
+---
+
+## 11. Tremor
+
+[Tremor](https://tremor.so/) 专注于仪表盘与数据可视化。其当前文档显示 Tremor Raw 面向 React 18.2+ 与 Tailwind CSS 4.0+ 设计。
+
+**核心优势：**
+
+- **以仪表盘为中心。** 针对数据分析、仪表盘 UI 与数据展示提供专门的资源。
+- **Tailwind 原生。** 无需额外样式配置，即可与现有 Tailwind 项目无缝集成。
+- **简洁的默认样式。** 图表与指标卡开箱即用，外观精致、设计语言统一。
+- **聚焦的范围。** 只关注数据展示，可以按需取用，而不必引入整套 UI 框架。
+
+**适用场景：** 你正在构建数据分析仪表盘或数据密集型界面，并已经在使用 Tailwind CSS。
+
+**权衡点：** 仅限于仪表盘相关组件。对于表单、导航、对话框等通用 UI 模式，你需要另寻他库。
+
+---
+
+## 12. Park UI
+
+[Park UI](https://park-ui.com/) 是构建在 Ark UI 基础组件之上的带样式组件库，提供 Panda CSS 与 Tailwind CSS 两种版本。
+
+**核心优势：**
+
+- **预先样式化的 Ark UI。** 在 Ark UI 的 headless 组件基础上叠加了精致、可定制的样式 —— 类似 shadcn/ui 对 Radix 的做法。
+- **支持双样式方案。** 提供 Panda CSS 与 Tailwind CSS 两种变体，按项目情况选择即可。
+- **复制粘贴模式。** 与 shadcn/ui 一样，组件以源码形式加入你的项目，你拥有它们并可自由定制。
+- **设计 tokens。** 自带 token 体系，可以方便地进行全局样式调整。
+
+**适用场景：** 你喜欢 shadcn/ui 的复制粘贴模式，但更倾向于使用基于状态机的 Ark UI 而非 Radix，或者你正在使用 Panda CSS。
+
+**权衡点：** 相比 shadcn/ui，社区与生态规模更小，第三方扩展和主题也较少。
+
+---
+
+## 如何选择
+
+并不存在一个绝对"最好"的库 —— 正确的选择取决于你项目的约束条件：
+
+- **使用 Tailwind v4 开始新项目？** HeroUI 提供了最现代的技术栈：React Aria 可访问性、复合组件以及 AI 工具支持。
+- **想完全拥有组件代码？** shadcn/ui 或 Park UI 让你直接把组件复制进项目。
+- **构建有复杂数据需求的企业级应用？** MUI 的数据网格或 Ant Design 的表格组件难以被超越。
+- **需要最强的可访问性合规？** HeroUI 基于 React Aria 的底层提供了开箱即用的最强可访问性。
+- **希望拥有一套高质量的通用 UI 工具箱？** HeroUI 覆盖了所有核心 UI 模式并具备深度的可访问性；对于富文本编辑器等特定需求，可以搭配专门的库一起使用。
+- **跨多个框架工作？** Ark UI 的状态机可以同时在 React、Vue 与 Solid 中使用。
+
+## 开始使用 HeroUI
+
+如果你正在启动一个新的 React 项目，希望使用可访问性良好、设计精美、基于 Tailwind CSS v4 的组件，那么不妨试试 HeroUI：
+
+- [快速开始指南](/docs/react/getting-started/quick-start)
+- [组件文档](/docs/react/components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [Discord 社区](https://discord.gg/heroui)
diff --git a/apps/docs/content/blog/cn/why-choose-heroui-for-your-design-system.mdx b/apps/docs/content/blog/cn/why-choose-heroui-for-your-design-system.mdx
new file mode 100644
index 0000000..994efa2
--- /dev/null
+++ b/apps/docs/content/blog/cn/why-choose-heroui-for-your-design-system.mdx
@@ -0,0 +1,305 @@
+---
+title: "为什么选择 HeroUI 作为你的设计系统"
+description: "为什么选择 HeroUI：基于 React Aria 的可访问性、Tailwind CSS v4 样式系统、复合组件以及面向生产级 React 应用的 AI 原生工具支持。"
+date: "2026-05-17"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["heroui", "design-system", "react", "ui-libraries"]
+image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+---
+
+大多数 React 组件库都在解决同一个问题：不再重复造按钮。但设计系统往往会在另一个阶段出问题 —— 当你选用的库无法灵活贴合产品需求时；当可访问性是发布之后才匆忙补上的考量时；又或者当你的 AI 编码助手凭空臆造出根本不存在的 props 时。
+
+HeroUI 将 [React Aria](https://react-spectrum.adobe.com/react-aria/) 的可访问性、[Tailwind CSS v4](https://tailwindcss.com/) 的样式系统，以及一套复合组件 API 结合到一起 —— 让你拥有结构上的掌控权，又不必让 props 数量失控。本文将给出选择它作为设计系统基础的具体理由。
+
+## 技术栈
+
+| 分层 | 技术 | 原因 |
+|-------|-----------|-----|
+| **可访问性** | React Aria (Adobe) | 业界领先的 WCAG 基础原语，由 Adobe 积极维护 |
+| **样式** | Tailwind CSS v4 | 静态 CSS、零运行时、通过 `@theme` 定义设计 tokens |
+| **组件 API** | 复合组件 | `Card.Header`、`Modal.Body` —— 结构可控，不必让 props 失控 |
+| **类型** | TypeScript | 完整类型覆盖、泛型 props、兼容严格模式 |
+| **AI 工具** | MCP 服务器、llms.txt、agent skills | 让 AI 助手能拿到最新 API，而非陈旧的训练数据 |
+| **跨平台** | HeroUI Native (React Native) | 同一套设计系统覆盖 Web 与移动端 —— 目前没有其他开源库能做到这一点 |
+
+## 真正达到企业级标准的可访问性
+
+每个 HeroUI 组件都构建在 [React Aria](https://react-spectrum.adobe.com/react-aria/) 之上 —— Adobe 的可访问性原语库。这不是营销话术：React 生态中没有比它更深入的可访问性基础，它甚至支撑着 Adobe 自己的生产级设计系统（Spectrum），覆盖 Photoshop Web、Acrobat 和 Lightroom 等产品。
+
+React Aria 处理了大多数库都未顾及的部分：
+
+- **感知平台的键盘导航。** Mac、Windows 与 Linux 在 Home/End、option/alt+方向键和焦点行为上有着不同的惯例。React Aria 会自动适配。
+- **屏幕阅读器的播报。** 实时区域、状态消息以及动态内容播报，在 JAWS、NVDA 和 VoiceOver 上都能正确工作。
+- **触摸交互。** 移动端的长按、拖放与手势处理 —— 不仅仅是点击事件。
+- **国际化。** 从右到左布局、按区域格式化日期/数字，以及对 30+ 种语言的字符串排序支持。
+- **虚拟焦点。** 对于包含成千上万项的集合，React Aria 在保持性能的同时仍能正确通知屏幕阅读器。
+
+这些都很重要，因为在 2026 年，可访问性合规已经不再是可选项。政府、医疗、金融与教育行业都要求符合 WCAG。HeroUI 把这种合规作为默认能力提供，而不是需要额外升级才能获得的特性。
+
+### React Aria 与 Radix UI 的对比
+
+许多流行的库（如 shadcn/ui、Park UI）都构建在 Radix UI 之上。Radix 本身很扎实，但原团队已将重心转向 Base UI，Radix 基础组件的长期维护仍是未定之数。React Aria 则由 Adobe 持续维护 —— 一家自身产品就严重依赖它的公司。
+
+## 原生支持 Tailwind CSS v4
+
+HeroUI 不是把 Tailwind 当作兼容层 —— 它从一开始就是为 Tailwind CSS v4 设计的。
+
+**这意味着：**
+
+- **零运行时 CSS 开销。** 所有样式都是静态 CSS，在构建时就被解析完毕。没有 CSS-in-JS 的运行时计算，没有样式注入，也没有水合(hydration)成本。
+- **通过 CSS 自定义属性定义设计 tokens。** 主题以标准 CSS `@theme` 指令的形式存在，而不是 JavaScript 配置对象。改一个 token，所有组件随之更新。
+- **基于工具类的自定义。** 用 `className` 覆盖任意组件 —— 与你在项目其他地方使用 Tailwind 的方式完全一致。
+- **更小的输出体积。** Tailwind v4 的新引擎生成的 CSS 更少，再加上 HeroUI 的模块化导入，能让你的生产环境包保持精简。
+
+```tsx
+<Button variant="secondary" className="font-semibold tracking-wide">
+  Get Started
+</Button>
+
+<Card className="max-w-md shadow-lg">
+  <Card.Header className="pb-0">
+    <Card.Title className="text-xl font-bold">Dashboard</Card.Title>
+  </Card.Header>
+  <Card.Content className="py-4">
+    Your metrics here
+  </Card.Content>
+</Card>
+```
+
+如果你的团队已经在用 Tailwind，引入 HeroUI 不会带来第二套样式系统。如果你还没用 Tailwind，是否采用它是另一个独立的决定 —— 但这是 2026 年大多数 React 团队都已经做出的选择。
+
+## 复合组件 API
+
+HeroUI 采用复合组件 —— 父组件通过点号语法暴露其子组件的模式。这与 Radix UI 的做法相同，并且在复杂 UI 上比基于 props 的 API 扩展性更好。
+
+```tsx
+<Modal>
+  <Button>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.Header>
+          <Modal.Heading>Confirm</Modal.Heading>
+        </Modal.Header>
+        <Modal.Body>Are you sure?</Modal.Body>
+        <Modal.Footer>
+          <Button variant="ghost">Cancel</Button>
+          <Button>Confirm</Button>
+        </Modal.Footer>
+      </Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+**这种模式对设计系统的意义：**
+
+- **结构可控。** 可以在组件的各个部分之间重新排列、省略或插入自定义元素，而不必与库的内部布局对抗。
+- **细粒度的样式。** 可以为任意子组件单独应用 `className`，让 `Card.Header` 与 `Card.Footer` 拥有不同样式，无需 CSS 覆盖。
+- **TypeScript 校验。** 编译器会检查你的组件树结构 —— 错误嵌套在构建时就会被发现，而不是带到生产环境。
+- **JSX 可读性强。** 组件的层级结构直接映射到 UI 的视觉层级。新成员阅读代码即可理解布局。
+
+## <ComponentCount />+ 个组件
+
+HeroUI 提供 <ComponentCount />+ 个组件，以及 <ExampleCount />+ 个有文档的示例。库覆盖了产品 UI 的完整面：
+
+- **数据输入** —— Input、Textarea、NumberField、Select、ComboBox、Autocomplete、DatePicker、DateRangePicker、ColorPicker、Slider、Switch、Checkbox、Radio
+- **数据展示** —— Table（排序、选择、分页）、Avatar、Badge、Chip、Tag、Skeleton
+- **布局** —— Card、Surface、Separator、Fieldset
+- **导航** —— Tabs、Breadcrumbs、Pagination、Link
+- **反馈** —— Toast、ProgressBar、ProgressCircle、Meter、Spinner
+- **覆盖层** —— Modal、Drawer、Popover、Tooltip、Dropdown、AlertDialog
+- **展开/折叠** —— Accordion、Disclosure
+- **动作类** —— Button、ToggleButton、ToggleButtonGroup
+
+像 Calendar、DatePicker、ColorPicker 和 Table 这样的复杂组件都是自包含的 —— 它们在内部处理日期运算、本地化格式、键盘导航以及屏幕阅读器播报。这些组件想做到真正可访问其实非常困难，而 HeroUI 把它们作为持续维护、经过测试的原语提供出来。
+
+## 面向 AI 的原生工具
+
+如今，绝大多数开发者每天都在使用 AI 编码助手。生成代码的质量取决于 AI 是否拥有你所用组件库的准确上下文 —— 否则就只能凭借陈旧的训练数据猜测。
+
+HeroUI 提供了四项官方集成：
+
+### MCP 服务器
+
+一个 [Model Context Protocol 服务器](/docs/react/getting-started/mcp-server)，AI 代理可以通过它查询组件文档、API、源码与设计 tokens。可接入 Cursor、Claude Code、Windsurf，或任何兼容 MCP 的编辑器。
+
+当 AI 助手能够访问 MCP 服务器时，它可以查到任意 HeroUI 组件的复合组件结构、可用 props 以及正确的 import —— 不再需要凭空臆造。
+
+[了解如何配置 MCP 服务器 →](/docs/react/getting-started/mcp-server)
+
+### llms.txt
+
+一个结构化参考文件，位于 [heroui.com/llms.txt](/docs/react/getting-started/llms-txt)，为 LLM 提供整个库的精炼且准确的参考。这是一个标准化格式，AI 工具会读取它来避免生成已废弃的写法。
+
+[进一步了解 llms.txt →](/docs/react/getting-started/llms-txt)
+
+### Agent Skills
+
+为 Cursor、Claude Code 等 AI 工具预构建的 [skill 文件](/docs/react/getting-started/agent-skills)，帮助 AI 代理掌握 HeroUI 的约定 —— 包括正确的 import、复合组件模式、样式方案以及项目脚手架。
+
+[了解如何安装 Agent Skills →](/docs/react/getting-started/agent-skills)
+
+### AGENTS.md
+
+一份 [AGENTS.md 文件](/docs/react/getting-started/agents-md)，为 AI 编码代理提供仓库级上下文。它描述了项目结构、编码约定与组件模式，让代理从第一次 prompt 起就理解你的代码库。
+
+[了解 AGENTS.md →](/docs/react/getting-started/agents-md)
+
+**结果是：** AI 助手能够生成正确的 HeroUI v3 代码，使用正确的复合组件模式、import 路径与 Tailwind 类名。这一点至关重要，因为错误的 AI 输出在调试上耗费的时间，远多于它生成代码本身节省的时间。
+
+## 生态系统
+
+### HeroUI Pro
+
+[HeroUI Pro](https://heroui.com/pro) 在基础库之上扩展了应用级组件与模板：
+
+- **AppLayout、Sidebar、Navbar** —— 包含响应式行为的完整应用外壳
+- **DataGrid** —— 支持类型化列、排序与过滤的高密度数据表格
+- **KPI、NumberValue、TrendChip** —— 仪表盘指标组件
+- **LineChart、BarChart** —— 数据可视化
+- **Sheet、CommandMenu** —— 高级覆盖层模式
+- **模板** —— 仪表盘、财务、聊天与邮件应用等起点模板
+
+Pro 是付费产品 —— 当你需要的不仅是 UI 组件，更是应用级基础设施时再使用。
+
+### HeroUI Native
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp"
+  alt="HeroUI Native - React Native components"
+/>
+
+HeroUI 是目前唯一在 Web 与移动端上都能提供同等组件质量的开源设计系统。[HeroUI Native](/docs/native/getting-started) 把同一套设计 tokens、复合组件 API 以及可访问性标准带到 React Native —— 利用各平台的原生 API，而非简单地包装 WebView。
+
+这意味着构建跨平台产品的团队可以在 React（Web）和 React Native（移动端）之间共享同一套设计系统，无需对任何一端妥协。统一的视觉语言、统一的组件模式、统一的主题 tokens —— 但在各端都使用原生渲染。
+
+目前没有其他开源 React 组件库能够做到这一点。MUI、shadcn/ui、Chakra UI 与 Mantine 都仅限于 Web。如果你的产品需要同时支撑 Web 与移动端，HeroUI 是唯一一套能从同一基础覆盖两端的设计系统。
+
+### Figma Kit
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-light.png"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-dark.png"
+  alt="HeroUI Figma Kit"
+/>
+
+[HeroUI Figma Kit (v3)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) 让设计与代码保持同步。Figma 中的组件与 React 实现一一对应，设计师与开发者基于同一份真实来源进行工作。
+
+### Storybook
+
+每个组件都有对应的 [Storybook stories](https://storybook-v3.heroui.com/)，展示所有变体、状态与组合方式。可用于可视化测试、设计评审与文档。
+
+### 社区
+
+HeroUI 并非新生事物 —— 我们已经构建了 5 年多，最早从 v1（最初的 NextUI）开始。社区规模稳步增长：GitHub 上有 29.3K+ stars，Discord 上有 9K+ 成员，每周还有数以千计的讨论、社区回答与 issue 被解决。
+
+- [GitHub](https://github.com/heroui-inc/heroui) —— 源码、issue 与讨论
+- [Discord](https://discord.gg/heroui) —— 9K+ 成员，社区支持与公告
+- [X / Twitter](https://x.com/hero_ui) —— 更新与版本发布
+
+### 获得 Y Combinator 投资
+
+HeroUI 获得了风险投资，包括 [Y Combinator](https://www.ycombinator.com/companies/heroui)。这意味着我们有专职的全职团队、长期的维护承诺，以及持续交付所需的资源。在选用一个组件库时，你其实是在押注它的未来 —— HeroUI 的目标是长期存在。
+
+## 开箱即用的设计品质
+
+HeroUI 提供经过精心打磨的默认样式，不做任何主题定制看起来也很精致：
+
+- **流畅的动画。** 按钮带有细腻的按下反馈，弹窗以弹簧物理动效呈现，手风琴展开时使用自然的缓动曲线。
+- **均衡的间距 tokens。** 所有组件遵循统一的数学比例，padding、margin 与 gap 都保持一致。
+- **阴影层级。** 浅色与深色模式下都能良好工作的高度层级，无需手动调整。
+- **主题变体。** 内置 glass、brutalism 以及中性等多种视觉风格，通过设计 tokens 即可切换。
+
+设计 token 体系基于 CSS 自定义属性，主题就是标准 CSS：
+
+```css
+@theme {
+  --color-primary: oklch(0.6 0.25 260);
+  --radius-field: 0.5rem;
+  --shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
+}
+```
+
+修改 tokens，所有组件都会随之全局更新。不需要 JavaScript 主题对象，不需要 provider 包装，也没有运行时开销。
+
+想要几次点击就把 HeroUI 变成你自己的样子？[主题构建器](/themes)允许你以可视化的方式自定义颜色、字体、圆角与间距 —— 然后导出一份可直接用于项目的 CSS 主题。
+
+## 两步即可就绪
+
+大多数组件库在渲染第一个组件之前，都需要配置文件、provider 包装、主题对象与插件设置。HeroUI 不需要。整个安装过程只有两步：
+
+**1. 安装：**
+
+```bash
+npm i @heroui/styles @heroui/react
+```
+
+**2. 在你的 CSS 中加一行：**
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles"; /* 就这些 */
+```
+
+接下来即可使用任意组件 —— 不需要 `ThemeProvider`、不需要 `ChakraProvider`、不需要 `MantineProvider`，也不需要任何配置对象：
+
+```tsx
+import { Button, Card } from "@heroui/react";
+
+export default function Page() {
+  return (
+    <Card>
+      <Card.Content>
+        <Button>Click me</Button>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+整个配置就是这些。不需要用 provider 包裹整个应用，不需要主题配置文件，也不需要任何运行时初始化。安装、引入一行 CSS，然后就可以开始构建。查看[快速开始指南](/docs/react/getting-started/quick-start)，五分钟内即可上手。
+
+## 服务端组件
+
+HeroUI 的设计契合 React Server Components 的模型：
+
+- **静态组件**（`Card`、`Badge`、`Text`、`Separator`、`Avatar`）可以留在服务端组件树中，不带任何客户端 JavaScript。
+- **交互式组件**（`Button`、`Modal`、`Table`、`Select`）使用客户端边界 —— 每个组件都有清晰的文档说明。
+- **不强制使用 provider** —— 没有迫使整个组件树进入客户端边界的客户端 context。
+
+这意味着你的页面默认会输出更少的 JavaScript。静态布局在服务端渲染，交互式部件仅在需要的位置进行水合(hydration)。
+
+## 一些权衡
+
+HeroUI 采用聚焦的策略：与其交付所有可能的组件，我们更优先保证团队最常使用组件的深度、可访问性与品质。对于富文本编辑、拖放或图表等专门需求，我们建议将 HeroUI 与擅长这些特定问题的专业库搭配使用 —— 这比依赖单一库覆盖所有场景效果更好。
+
+HeroUI 是为 Tailwind CSS v4 构建的。如果你的团队已经在使用 Tailwind，引入它非常顺畅。如果你使用的是其他样式方案，迁移到 Tailwind 是一个独立但值得的投入 —— 那是面向现代 CSS 工具链的一笔投资。
+
+## 谁适合使用 HeroUI
+
+如果你正在构建以下产品，HeroUI 会是个不错的选择：
+
+- **SaaS 应用** —— 表单、表格、覆盖层与导航，并具备 React Aria 的可访问性
+- **仪表盘与管理后台** —— 借助 HeroUI Pro 组件构建的高密度数据布局
+- **电商门店** —— 高性能、可访问、对 SEO 友好的组件渲染
+- **营销官网与落地页** —— 精致的默认样式，没有运行时 CSS 开销
+- **跨平台产品** —— 借助 HeroUI Native，在 Web（React）与移动端（React Native）上共享同一套设计系统
+- **任何重视可访问性、Tailwind CSS 集成与 AI 辅助开发的 React / Next.js 项目**
+
+## 开始使用
+
+```bash
+npm install @heroui/styles @heroui/react
+```
+
+- [快速开始指南](/docs/react/getting-started/quick-start) —— 五分钟内即可完成配置
+- [组件文档](/docs/react/components) —— 完整的 API 参考与在线示例
+- [主题指南](/docs/react/getting-started/theming) —— 自定义设计系统
+- [MCP 服务器](/docs/react/getting-started/mcp-server) —— 接入你的 AI 编码助手
+- [GitHub 仓库](https://github.com/heroui-inc/heroui) —— 源码与 issue
diff --git a/apps/docs/content/blog/en/best-react-dashboards.mdx b/apps/docs/content/blog/en/best-react-dashboards.mdx
new file mode 100644
index 0000000..a53c73a
--- /dev/null
+++ b/apps/docs/content/blog/en/best-react-dashboards.mdx
@@ -0,0 +1,427 @@
+---
+title: "14 Dashboard Templates and Frameworks for React Teams in 2026"
+description: "React dashboard templates, admin frameworks, and UI starting points for building admin panels, analytics dashboards, and data-driven applications."
+date: "2026-05-10"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["react", "dashboards", "templates"]
+image: "/images/blog/best-react-dashboards.jpg"
+draft: true
+---
+
+Building a React dashboard from scratch takes weeks — picking the right template, framework, or component stack can cut that down dramatically. The strongest options give you responsive layouts, data visualization patterns, accessible navigation, and a theme system you can actually maintain.
+
+I pulled together 14 options worth checking in 2026. Pricing and feature gates change often, so use this as a shortlist and verify the current license before you buy or build on top of anything.
+
+
+## Quick Comparison
+
+| Template / Framework | Type | Best reason to consider it |
+|---------------------|------|----------------------------|
+| **HeroUI Pro Dashboard** | Template + Pro components | HeroUI-native app shell, sidebar, navbar, KPI, data grid, and chart patterns |
+| **Tremor** | Dashboard UI resources | Tailwind v4 dashboard blocks and analytics-oriented UI |
+| **Refine** | Framework | Data-provider driven CRUD/admin applications |
+| **AdminJS** | Framework | Generated admin panels from backend models |
+| **React Admin** | Framework | Mature admin framework with a large data-provider ecosystem |
+| **Ant Design Pro** | Template/framework ecosystem | Ant Design and ProComponents-based admin apps |
+| **CoreUI** | Template | Cross-framework admin template ecosystem |
+| **Tabler** | Template | Bootstrap-based dashboard UI |
+| **Argon Dashboard** | Template | Creative Tim dashboard aesthetic |
+| **Material Dashboard** | Template | MUI / Material Design dashboard starting point |
+| **Berry** | Template | MUI-based admin dashboard ecosystem |
+| **Mantis** | Template | MUI-based admin dashboard ecosystem |
+| **shadcn/ui Dashboard** | Example | Source-owned Tailwind dashboard example |
+| **HeroUI Pro + custom widgets** | Pro components + template | Start from Pro layout/table/chart primitives, then add product-specific widgets |
+
+---
+
+## 1. HeroUI Pro Dashboard Template
+
+[HeroUI Pro](https://heroui.com/pro) offers pre-built dashboard templates designed specifically for SaaS products, admin panels, and analytics dashboards. Built on HeroUI v3 components with Tailwind CSS v4.
+
+**What you get:**
+
+- Complete dashboard layouts with sidebar navigation, header, and content areas
+- Analytics pages with charts, metrics cards, and data tables
+- Settings, analytics, orders, tracker, help, finance, chat, and email-style app surfaces across the current templates
+- App shell patterns using `AppLayout`, `Sidebar`, and `Navbar`
+- Pro dashboard widgets using `KPI`, `DataGrid`, `LineChart`, `NumberValue`, and `TrendChip`
+- Dark mode support with HeroUI's theming system
+- Responsive design that works on mobile and desktop
+
+**Key strengths:**
+
+- **Production-quality components.** Every component is built on React Aria with full accessibility support and keyboard navigation.
+- **Tailwind CSS v4.** Modern styling with CSS-based theming, no runtime overhead.
+- **Next.js App Router ready.** Templates are built for the latest Next.js with server components and streaming.
+- **AI tooling.** Use HeroUI's MCP server with Cursor or other AI tools to extend and customize dashboards with AI assistance.
+
+**Pricing:** Premium license through HeroUI Pro; check the current pricing page for details.
+
+**Best for:** Teams building SaaS products who want accessible, modern dashboard components they can customize with Tailwind CSS.
+
+---
+
+## 2. Tremor
+
+[Tremor](https://tremor.so/) is focused on dashboard UI. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.
+
+**What you get:**
+
+- Dashboard-oriented UI resources
+- Tremor Blocks for copy-paste dashboard sections
+- Figma UI Kit for dashboard design work
+- Tailwind CSS v4 setup guides
+
+**Key strengths:**
+
+- **Dashboard-first design.** The project is centered on analytics and dashboard interfaces.
+- **Tailwind native.** Current docs target Tailwind CSS v4.
+- **Useful design resources.** The docs link to Tremor Blocks and a Figma UI Kit.
+
+**Trade-offs:** Limited to dashboard-specific components. You'll need another library for forms, navigation, and other general UI patterns.
+
+**Pricing:** Check Tremor's current site and repository before choosing it for a commercial project.
+
+**Best for:** Teams that already have a UI library and need dashboard-specific visualization components to complement it.
+
+---
+
+## 3. Refine
+
+[Refine](https://refine.dev/) is a meta-framework for building data-intensive applications — admin panels, dashboards, and internal tools. It's not a template; it's a framework that generates CRUD interfaces from your data model.
+
+**What you get:**
+
+- Automatic CRUD operations from data provider configuration
+- Authentication and authorization hooks
+- Routing integration (Next.js, Remix, React Router)
+- Connectors for REST, GraphQL, Supabase, Strapi, Appwrite, and more
+- UI framework adapters for Ant Design, MUI, Mantine, and Chakra UI
+
+**Key strengths:**
+
+- **Data-first architecture.** Define your data providers and Refine generates the boilerplate — list pages, create/edit forms, show views, and filters.
+- **Framework-agnostic UI.** Swap between Ant Design, MUI, Mantine, or Chakra UI without changing your business logic.
+- **Headless mode.** Use your own components if none of the bundled UI adapters fit.
+- **Active community.** Regular releases, good documentation, and a responsive maintainer team.
+
+**Trade-offs:** The abstraction adds complexity for simple dashboards. If your data layer doesn't fit Refine's provider model, you'll fight the framework more than benefit from it.
+
+**Pricing:** Check Refine's current open-source and commercial offering before choosing it.
+
+**Best for:** Teams building admin panels or internal tools with standard CRUD patterns over existing APIs.
+
+---
+
+## 4. AdminJS
+
+[AdminJS](https://adminjs.co/) (formerly Admin Bro) auto-generates an admin panel from your database models. Point it at your ORM, and it creates a full CRUD interface.
+
+**What you get:**
+
+- Auto-generated admin panel from Sequelize, TypeORM, Mongoose, Prisma, or MikroORM models
+- CRUD views, search, filtering, and bulk actions
+- Dashboard page with customizable widgets
+- Role-based access control
+- Custom action hooks for business logic
+
+**Key strengths:**
+
+- **Zero-config setup for common ORMs.** If you use Prisma or TypeORM, AdminJS reads your schema and generates an admin panel automatically.
+- **Customizable.** Override components, actions, and views when the defaults don't fit.
+- **Plugin system.** Add features like file upload, import/export, and logging through plugins.
+
+**Trade-offs:** The auto-generated UI looks functional but plain. Heavy customization can become painful because you're working against the generated output. The React version uses older patterns.
+
+**Pricing:** Check AdminJS's current open-source and hosted offering before choosing it.
+
+**Best for:** Backend teams that need a quick admin panel for database management without building frontend code.
+
+---
+
+## 5. React Admin
+
+[React Admin](https://marmelab.com/react-admin/) is the most mature admin framework in the React ecosystem, maintained by Marmelab since 2016.
+
+**What you get:**
+
+- Complete admin panel framework with routing, layout, and state management
+- List, Create, Edit, Show views with declarative configuration
+- Many data provider adapters for common backend patterns
+- Authentication hooks and access control
+- Theming through MUI
+
+**Key strengths:**
+
+- **Mature and battle-tested.** Years of production use mean many admin edge cases are documented and handled.
+- **Declarative API.** Define resources, list columns, form fields, and filters with JSX — React Admin generates the plumbing.
+- **Enormous data provider ecosystem.** If your backend speaks a protocol, there's probably a React Admin data provider for it.
+- **Enterprise edition.** Calendar, kanban, audit log, real-time updates, and multi-tenancy for teams that need them.
+
+**Trade-offs:** Tightly coupled to MUI for styling. The declarative API is powerful but opaque — debugging what goes wrong inside the framework requires understanding its internals.
+
+**Pricing:** Check React Admin's current licensing and Enterprise Edition details.
+
+**Best for:** Teams building full-featured admin panels that need a mature, well-documented framework with extensive data provider support.
+
+---
+
+## 6. Ant Design Pro
+
+[Ant Design Pro](https://pro.ant.design/) is the official dashboard template ecosystem for Ant Design. It is aimed at full-featured admin products built around Ant Design and ProComponents.
+
+**What you get:**
+
+- Complete admin layout with sidebar, header, and breadcrumbs
+- Pre-built pages: dashboard, forms, tables, profiles, error pages
+- Authentication and authorization patterns in the Ant Design Pro ecosystem
+- ProComponents (ProTable, ProForm, ProLayout) for complex data patterns
+- Internationalization with 10+ language packs
+
+**Key strengths:**
+
+- **ProComponents.** Advanced components like ProTable (configurable data table with search, filtering, and actions) save weeks of development time.
+- **Umi integration.** Built on the Umi framework with conventions for routing, plugins, and data fetching.
+- **Comprehensive template.** Nearly every page you'd need in an admin panel is included and customizable.
+
+**Trade-offs:** Tightly coupled to the Ant Design ecosystem (Umi, Ant Design, AntV). The aesthetic is distinctly Ant Design — theming it to look different is difficult. Documentation is primarily in Chinese with English translations.
+
+**Pricing:** Check Ant Design Pro's current license and repository before choosing it.
+
+**Best for:** Teams already using Ant Design who need a comprehensive admin template with advanced data components.
+
+---
+
+## 7. CoreUI
+
+[CoreUI](https://coreui.io/) is a cross-framework admin template available for React, Vue, Angular, and vanilla Bootstrap. The React version ships with a complete dashboard layout and component set.
+
+**What you get:**
+
+- Dashboard layout with sidebar navigation and header
+- 30+ page templates (analytics, user management, settings, etc.)
+- Custom UI components built on Bootstrap foundations
+- Chart examples for data visualization
+- Icon library with 1,500+ icons
+
+**Key strengths:**
+
+- **Cross-framework consistency.** If your organization uses multiple frontend frameworks, CoreUI provides a consistent design language across all of them.
+- **Extensive page templates.** Pre-built pages for common admin patterns save time on layout and structure.
+- **Regular updates.** Actively maintained with frequent releases.
+
+**Trade-offs:** The Bootstrap foundation feels dated compared to Tailwind-based alternatives. The free version is limited — most useful features require the Pro license.
+
+**Pricing:** Check CoreUI's current pricing and license before choosing it.
+
+**Best for:** Organizations that need the same admin panel design across React, Vue, and Angular projects.
+
+---
+
+## 8. Tabler
+
+[Tabler](https://tabler.io/) is a free, open-source dashboard template built on Bootstrap with a React adaptation. Known for its clean, minimal design and extensive component set.
+
+**What you get:**
+
+- 200+ responsive UI components
+- Dashboard layout with multiple navigation patterns
+- Apache ECharts integration for data visualization
+- Form components with validation
+- Email and e-commerce page templates
+
+**Key strengths:**
+
+- **Beautiful design.** Tabler has one of the cleanest default aesthetics of any free dashboard template.
+- **Component breadth.** Over 200 components covering navigation, forms, data display, feedback, and layout.
+- **Open-source starting point.** Check the current repository license and docs before adopting it.
+- **Active development.** Regular releases with new components and improvements.
+
+**Trade-offs:** The React version lags behind the HTML/Bootstrap version in features. TypeScript support is incomplete. Based on Bootstrap rather than a modern CSS approach.
+
+**Pricing:** Check Tabler's current license and template docs before choosing it.
+
+**Best for:** Developers who want a beautiful, free dashboard template and are comfortable with Bootstrap-based styling.
+
+---
+
+## 9. Argon Dashboard
+
+[Argon Dashboard React](https://www.creative-tim.com/product/argon-dashboard-react) by Creative Tim is a popular dashboard template with a distinctive visual style.
+
+**What you get:**
+
+- Dashboard layout with sidebar and navbar
+- Pre-built pages (dashboard, maps, tables, user profile)
+- Bootstrap-based styling with custom extensions
+- Chart examples
+
+**Key strengths:**
+
+- **Distinctive design.** Argon has a recognizable gradient-heavy aesthetic that stands out from more neutral templates.
+- **Creative Tim ecosystem.** Integrates with Creative Tim's other products (login pages, landing pages, design system).
+- **Good documentation.** Clear setup instructions and component guides.
+
+**Trade-offs:** The free version is bare-bones — most useful pages and components require the Pro license. The design is polarizing. Bootstrap foundation limits modern CSS usage.
+
+**Pricing:** Check Creative Tim's current pricing and license before choosing it.
+
+**Best for:** Teams that like Creative Tim's design aesthetic and want a quick starting point for a dashboard.
+
+---
+
+## 10. Material Dashboard
+
+[Material Dashboard React](https://www.creative-tim.com/product/material-dashboard-react) is another Creative Tim template, built on MUI with a Material Design aesthetic.
+
+**What you get:**
+
+- MUI-based dashboard layout
+- Pre-built pages with Material Design styling
+- Chart examples for data visualization
+- Dark mode support
+- RTL layout support
+
+**Key strengths:**
+
+- **Material Design compliance.** If you need a dashboard that follows Google's Material Design guidelines, this delivers out of the box.
+- **MUI foundation.** Access to MUI's full component ecosystem for extending beyond the template's defaults.
+- **Well-documented.** Clear guides for customization, theming, and deployment.
+
+**Trade-offs:** Same Creative Tim free-vs-Pro split — the free version is limited. Closely tied to MUI, making it hard to use with other styling approaches.
+
+**Pricing:** Check Creative Tim's current pricing and license before choosing it.
+
+**Best for:** Teams using MUI who want a Material Design dashboard template with ready-made pages.
+
+---
+
+## 11. Berry
+
+[Berry](https://berrydashboard.io/) is an MUI-based admin dashboard template known for its polished design and comprehensive feature set.
+
+**What you get:**
+
+- A large set of page templates and widgets
+- Chart examples for data visualization
+- Authentication page examples
+- Multi-language support
+- Light and dark themes with RTL support
+
+**Key strengths:**
+
+- **Feature density.** Berry focuses on a large set of pre-built pages and widgets.
+- **Chart-heavy pages.** The template includes polished chart-oriented dashboard pages.
+- **Auth examples.** Includes authentication-related page examples.
+
+**Trade-offs:** The Pro version is expensive compared to alternatives. MUI dependency means the same theming constraints apply.
+
+**Pricing:** Check the current Berry pricing and license before choosing it.
+
+**Best for:** Teams that want a feature-rich MUI dashboard with multiple authentication patterns and extensive pre-built pages.
+
+---
+
+## 12. Mantis
+
+[Mantis](https://mantisdashboard.io/) is a React admin dashboard built on MUI, focused on clean design and developer experience.
+
+**What you get:**
+
+- Clean, modern dashboard layout
+- Chart examples for data visualization
+- Authentication page examples
+- Form components with validation
+- Widget pages for common dashboard patterns
+
+**Key strengths:**
+
+- **Clean aesthetic.** Mantis has a more restrained, modern design compared to other MUI-based templates.
+- **Good code organization.** The project structure follows best practices for scalable React applications.
+- **Regular updates.** Actively maintained with consistent releases.
+
+**Trade-offs:** Similar to Berry — MUI dependency, limited free version, Pro pricing.
+
+**Pricing:** Check the current Mantis pricing and license before choosing it.
+
+**Best for:** Teams who want a clean, well-organized MUI dashboard template.
+
+---
+
+## 13. Shadcn Dashboard
+
+The [shadcn/ui Dashboard](https://ui.shadcn.com/examples/dashboard) example demonstrates how to build a full dashboard using shadcn/ui components with Tailwind CSS.
+
+**What you get:**
+
+- Example dashboard layout with sidebar and header
+- Data table with sorting, filtering, and pagination
+- Charts using Recharts
+- Account/authentication page examples
+- Settings forms
+
+**Key strengths:**
+
+- **Full code ownership.** Since shadcn/ui components are copied into your project, you have complete control over the dashboard code.
+- **Tailwind CSS styling.** Clean, utility-first styling that's easy to customize.
+- **Community extensions.** Many developers have built expanded dashboard templates on top of the shadcn example.
+
+**Trade-offs:** It's an example, not a production template. You'll need to build out most pages yourself. The components need manual updates when shadcn releases improvements.
+
+**Pricing:** Check shadcn/ui's current license and docs before choosing it.
+
+**Best for:** Developers who want a Tailwind-based dashboard starting point with full control over the source code.
+
+---
+
+## 14. HeroUI Pro + Custom Widgets
+
+If you want a HeroUI-native dashboard, start with [HeroUI Pro](https://heroui.com/pro) rather than rebuilding the frame from base components. Use the Pro dashboard template for the app shell and add product-specific widgets only where your product needs something unique.
+
+**What you get:**
+
+- `AppLayout`, `Sidebar`, and `Navbar` for the dashboard frame
+- `KPI`, `DataGrid`, `LineChart`, `NumberValue`, and `TrendChip` for dashboard UI
+- Base HeroUI components for local UI around the Pro primitives
+- Full control over your data fetching, permissions, and business logic
+
+**Why this works:**
+
+- **No hand-rolled shell.** The app frame, sidebar, navbar, metrics, tables, and charts already have Pro primitives.
+- **Modern stack.** The current dashboard template is built with Next.js and HeroUI Pro components.
+- **AI-assisted development.** Use HeroUI's MCP server and docs so agents can extend the dashboard with current APIs.
+
+**How to start:**
+
+1. Start from the HeroUI Pro dashboard template.
+2. Keep `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and chart components as the foundation.
+3. Replace the mock data files with your API, database, or analytics source.
+4. Add custom widgets only for product-specific workflows.
+
+**Pricing:** Check HeroUI Pro's current pricing and license before choosing it.
+
+**Best for:** Teams that want a HeroUI-native dashboard without rebuilding dashboard infrastructure from scratch.
+
+---
+
+## How to Choose
+
+Your choice depends on what you value most:
+
+- **Speed to launch:** HeroUI Pro Dashboard or Ant Design Pro give you the most complete starting points.
+- **Maximum flexibility:** HeroUI Pro plus custom widgets or the shadcn Dashboard example let you build around your product's exact needs.
+- **CRUD-heavy admin panels:** React Admin or Refine auto-generate interfaces from your data model.
+- **Enterprise needs:** React Admin Enterprise, MUI X, or Berry Pro offer advanced features with support contracts.
+- **Budget-friendly:** Tabler, Tremor, and the shadcn Dashboard example are worth checking when you want an open-source starting point.
+
+## Build Your Dashboard with HeroUI
+
+HeroUI provides the components you need to build modern, accessible dashboards:
+
+- [Component Documentation](/docs/react/components) — Tables, Cards, Navigation, Forms, and more
+- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up a new project in minutes
+- [HeroUI Pro](https://heroui.com/pro) — Pre-built dashboard templates and premium components
+- [Tutorial: Build a React Dashboard](/blog/build-react-dashboard-with-heroui) — Step-by-step guide
diff --git a/apps/docs/content/blog/en/best-react-ui-component-libraries.mdx b/apps/docs/content/blog/en/best-react-ui-component-libraries.mdx
new file mode 100644
index 0000000..1838e2f
--- /dev/null
+++ b/apps/docs/content/blog/en/best-react-ui-component-libraries.mdx
@@ -0,0 +1,266 @@
+---
+title: "12 Best React UI Component Libraries in 2026"
+description: "Compare the 12 best React UI component libraries in 2026: HeroUI, shadcn/ui, MUI, Chakra UI, Mantine, and more. Features, accessibility, and AI tooling."
+date: "2026-05-16"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["react", "ui-libraries", "comparison"]
+image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png"
+darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png"
+---
+
+Choosing the right React UI component library can make or break your development workflow. The best React UI component libraries in 2026 ship accessible, production-ready components that let you focus on building features instead of re-implementing dropdowns for the hundredth time.
+
+I compared 12 libraries across styling, accessibility foundation, breadth, AI workflow, and licensing. Exact component counts and pricing can change quickly, so treat this as a practical field guide and check each project's docs before you commit.
+
+
+<h2 className="blog-table-heading mt-10 text-xl font-semibold text-muted">Quick Comparison</h2>
+
+| Library | Styling | Accessibility foundation | Breadth | AI workflow |
+|---------|---------|--------------------------|---------|-------------|
+| **HeroUI** | Tailwind CSS v4 | React Aria | <ComponentCount />+ components, <ExampleCount />+ examples | MCP server, llms.txt, agent skills |
+| **shadcn/ui** | Tailwind CSS | Radix UI and other primitives | Official docs list 59 component entries | MCP server, llms.txt, skills |
+| **Material UI** | Emotion by default, Pigment CSS integration path | MUI implementation | Very broad core + MUI X | Public docs |
+| **Chakra UI** | Panda CSS API-based system | Chakra / Ark UI ecosystem | Broad app component set | MCP server and public docs |
+| **Mantine** | CSS files / CSS Modules | Mantine implementation | 120+ components, 70+ hooks | MCP server, llms.txt, skills |
+| **Radix UI** | Unstyled | Radix primitives | Focused primitives | Public docs |
+| **Ant Design** | CSS-in-JS / token system | Ant Design implementation | Enterprise-heavy | Public docs |
+| **Headless UI** | Unstyled | Headless UI primitives | Focused primitives | Public docs |
+| **React Aria** | Unstyled | React Aria | Deep primitive layer | Public docs |
+| **Ark UI** | Unstyled | Zag.js state machines | Headless components | Public docs |
+| **Tremor** | Tailwind CSS v4 | Dashboard-focused components | Analytics/data display | Public docs |
+| **Park UI** | Panda CSS / Tailwind | Ark UI | Styled Ark components | Public docs |
+
+## 1. HeroUI
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+  alt="HeroUI - Beautiful by default, customizable by design"
+/>
+
+[HeroUI](https://heroui.com) pairs [React Aria](https://react-spectrum.adobe.com/react-aria/) accessibility with [Tailwind CSS v4](https://tailwindcss.com/) styling and a compound component API (`Card.Header`, `Table.Column`, `Modal.Body`). Components work with React 19 and the Next.js App Router out of the box.
+
+**Key strengths:**
+
+- **Accessibility-first architecture.** Every component is built on React Aria, Adobe's battle-tested accessibility primitives. This means screen reader support, keyboard navigation, and ARIA attributes are handled correctly out of the box — not bolted on as an afterthought.
+- **Tailwind CSS v4 native.** HeroUI's styling system uses CSS-based theming with `@theme` and design tokens, avoiding the runtime overhead of CSS-in-JS.
+- **Compound component API.** Components use a composable pattern (`Card.Header`, `Card.Content`, `Card.Footer`) that gives you full control over markup and layout without sacrificing ergonomics.
+- **AI tooling.** HeroUI ships an [MCP server](/docs/react/getting-started/mcp-server), [llms.txt](/docs/react/getting-started/llms-txt), and [agent skills](/docs/react/getting-started/agent-skills) so AI coding assistants can look up current HeroUI APIs instead of relying only on training data.
+- **Server component friendly.** Components are designed with React Server Components in mind — client boundaries are minimal and clearly documented.
+
+**When to use it:** You want a modern, accessible component library with Tailwind CSS styling and first-class AI tooling support. Ideal for new projects using Next.js, React 19, and Tailwind v4.
+
+---
+
+## 2. shadcn/ui
+
+[shadcn/ui](https://ui.shadcn.com/) isn't a traditional component library — it's a collection of copy-paste components built on Radix UI and Tailwind CSS. Instead of installing a package, you add component source code directly to your project.
+
+**Key strengths:**
+
+- **Full ownership.** Components live in your codebase, so you can modify them freely without fighting library abstractions or waiting for upstream changes.
+- **Radix UI foundation.** The underlying primitives handle accessibility and complex interactions (popovers, comboboxes, dialogs) reliably.
+- **CLI tooling.** The `shadcn` CLI scaffolds components into your project with the right dependencies and file structure.
+- **AI-ready docs.** shadcn/ui publishes `llms.txt`, skills, and an MCP server for agents.
+- **Massive ecosystem.** The community has built hundreds of extensions, themes, and integrations around shadcn's patterns.
+
+**When to use it:** You want maximum control over component code and you're comfortable maintaining copied components. Works well for teams that need heavy customization.
+
+**Trade-offs:** You own the code, which means you also own the bugs. Upstream fixes and improvements require manual re-integration. No central update mechanism. Additionally, shadcn/ui's foundation on Radix UI carries some uncertainty — the original Radix team has shifted focus to Base UI, and the long-term maintenance status of Radix primitives is an open question in the community.
+
+---
+
+## 3. Material UI (MUI)
+
+[Material UI](https://mui.com/) is the most established React component library, with a decade of production use. MUI's stable styling path still centers on Emotion and the `sx` prop; Pigment CSS exists as an experimental zero-runtime direction rather than the default.
+
+**Key strengths:**
+
+- **Massive component count.** Over 70 components covering nearly every UI pattern you can think of, from basic buttons to complex data grids.
+- **Material Design compliance.** If your design system is built on Material Design, MUI gives you pixel-perfect implementations.
+- **Enterprise ecosystem.** MUI X offers premium components (data grid, date pickers, charts) with enterprise support and SLAs.
+- **Mature and battle-tested.** Thousands of production apps run on MUI. Edge cases have been found and fixed over years.
+
+**When to use it:** You're building a large enterprise application that needs Material Design compliance, or you need MUI X's premium data grid and date picker components.
+
+**Trade-offs:** The Material Design aesthetic is opinionated. Theming away from Material's look-and-feel is possible but requires significant effort. Bundle size is larger than most alternatives.
+
+---
+
+## 4. Chakra UI
+
+[Chakra UI](https://chakra-ui.com/) pioneered the "style props" pattern in React, letting you style components with props like `bg="blue.500"` and `p={4}`. Chakra's current theming docs describe a system built around the Panda CSS API with `defineConfig`, `createSystem`, recipes, slot recipes, tokens, and semantic tokens.
+
+**Key strengths:**
+
+- **Intuitive styling API.** Style props make it fast to prototype and iterate on designs without leaving your JSX.
+- **Design token system.** The theme object gives you centralized control over colors, spacing, fonts, and breakpoints.
+- **Good accessibility defaults.** Components follow WAI-ARIA patterns and include keyboard navigation.
+- **Recipe-driven styling.** Chakra uses recipes, slot recipes, and a token-based system for component styling.
+- **AI support.** Chakra documents an MCP server for AI-assisted workflows.
+
+**When to use it:** You like styling through props rather than class names, and you want a cohesive design system with good defaults.
+
+**Trade-offs:** The style props pattern can make JSX noisy for complex components. Migrating from v2 to v3 required significant changes because the component and theming APIs changed.
+
+---
+
+## 5. Mantine
+
+[Mantine](https://mantine.dev/) is a full-featured React component library with a very broad component catalog, a hooks package, and a rich extension ecosystem. Mantine's homepage currently describes the library as `120+` components and `70+` hooks.
+
+**Key strengths:**
+
+- **Unmatched breadth.** Mantine has components and extensions for many product needs — date pickers, notifications, spotlight search, charts, forms, and more.
+- **Large hooks package.** Beyond components, Mantine ships hooks for local storage, media queries, clipboard, idle detection, and many other common patterns.
+- **CSS styling.** Mantine components are built with CSS files and can be customized through the Styles API.
+- **AI tooling.** Mantine publishes LLM docs, skills, and an MCP server.
+- **Form library.** `@mantine/form` provides form state management with validation that integrates seamlessly with Mantine inputs.
+
+**When to use it:** You want a batteries-included library where you can find a component for almost any use case without adding third-party packages.
+
+**Trade-offs:** The huge surface area means the bundle can grow quickly if you're not tree-shaking carefully. The component design aesthetic, while clean, is fairly specific.
+
+---
+
+## 6. Radix UI (Primitives)
+
+[Radix UI](https://www.radix-ui.com/) provides unstyled, accessible UI primitives that you style yourself. It's the foundation behind shadcn/ui and many other component libraries.
+
+**Key strengths:**
+
+- **Accessibility gold standard.** Every primitive is built to WAI-ARIA specification with exhaustive keyboard navigation, focus management, and screen reader support.
+- **Unstyled by default.** Zero design opinions means zero fighting with the library's aesthetic. Bring your own styling system.
+- **Composable APIs.** Primitives use a compound component pattern with slot-based composition that gives you control over every rendered element.
+- **Production-proven.** Radix primitives power thousands of production applications through both direct usage and shadcn/ui.
+
+**When to use it:** You need accessible, behavior-only primitives and want complete control over styling. Great for teams building custom design systems.
+
+**Trade-offs:** You need to bring all your own styling. The learning curve for the composition patterns can be steep for simpler use cases.
+
+---
+
+## 7. Ant Design
+
+[Ant Design](https://ant.design/) is a comprehensive design system and component library created by Ant Group (Alibaba). It's especially popular in enterprise applications and the Chinese development community.
+
+**Key strengths:**
+
+- **Enterprise-grade components.** Complex components like Table (with sorting, filtering, pagination), Form (with validation), and Tree are mature and feature-rich.
+- **Design system included.** Ant Design is a complete design system with design tokens, patterns, and guidelines — not just a component library.
+- **Internationalization.** First-class i18n support with 60+ locale packages.
+- **Component quality.** Each component handles dozens of edge cases that you'd otherwise need to build yourself.
+
+**When to use it:** You're building a complex enterprise application, especially one that needs sophisticated data tables, forms, and tree views.
+
+**Trade-offs:** The design aesthetic is distinctly "Ant Design" and theming it to look different requires substantial effort. Bundle size is significant. Accessibility support, while improving, still lags behind Radix/React Aria-based libraries.
+
+---
+
+## 8. Headless UI
+
+[Headless UI](https://headlessui.com/) is a set of unstyled, accessible UI components from the Tailwind Labs team. It focuses on common interactive patterns — dropdowns, dialogs, tabs, comboboxes.
+
+**Key strengths:**
+
+- **Tailwind CSS integration.** Built by the Tailwind team, it works perfectly with Tailwind's utility classes and transition utilities.
+- **Small, focused scope.** Only includes components that are genuinely hard to build accessibly (menus, listboxes, dialogs, etc.).
+- **Lightweight.** Minimal bundle impact because of the focused component set.
+- **Clean API.** Uses render props and compound components with a simple, predictable API.
+
+**When to use it:** You're using Tailwind CSS and need a few accessible interactive components without a full UI library.
+
+**Trade-offs:** Very small component set — you'll need other solutions for data tables, form inputs, date pickers, and most other patterns.
+
+---
+
+## 9. React Aria (Primitives)
+
+[React Aria](https://react-spectrum.adobe.com/react-aria/) is Adobe's library of accessibility primitives for React. It provides hooks and components for building accessible UI from scratch.
+
+**Key strengths:**
+
+- **Industry-leading accessibility.** React Aria is arguably the most thoroughly accessible UI primitive library available. It handles internationalization, right-to-left layouts, touch interactions, and edge cases that most libraries miss.
+- **Hooks + components.** Offers both low-level hooks (for maximum flexibility) and higher-level components (for convenience).
+- **Platform-aware.** Adapts behavior based on device type, pointer type, and platform conventions.
+- **Foundation for other libraries.** HeroUI, Adobe Spectrum, and other libraries build on React Aria, proving its reliability at scale.
+
+**When to use it:** You're building a design system from scratch and need the strongest possible accessibility foundation. Also useful when you need specific primitives (like a color picker or calendar) that other libraries don't offer.
+
+**Trade-offs:** Steeper learning curve than styled libraries. You need to bring all your own styling and composition patterns.
+
+---
+
+## 10. Ark UI
+
+[Ark UI](https://ark-ui.com/) is a headless component library from the creators of Chakra UI, built on top of state machines for predictable behavior.
+
+**Key strengths:**
+
+- **State machine architecture.** Uses Zag.js state machines under the hood, making component behavior predictable and debuggable.
+- **Framework-agnostic core.** The same state machines power React, Vue, and Solid versions of every component.
+- **Modern patterns.** Includes components like Signature Pad, Pin Input, and Splitter that aren't commonly found in other headless libraries.
+- **Styling flexibility.** Works with any styling solution — Tailwind, Panda CSS, vanilla CSS, CSS modules.
+
+**When to use it:** You want headless components with predictable state management, or you need to share component logic across React, Vue, and Solid projects.
+
+**Trade-offs:** Smaller community than Radix or React Aria. The state machine abstraction adds conceptual overhead for simple components.
+
+---
+
+## 11. Tremor
+
+[Tremor](https://tremor.so/) is focused on dashboards and data visualization. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.
+
+**Key strengths:**
+
+- **Dashboard-first design.** Purpose-built resources for analytics, dashboard UI, and data display.
+- **Tailwind native.** Integrates seamlessly with existing Tailwind projects without additional styling configuration.
+- **Clean defaults.** Charts and metrics look polished out of the box with a cohesive design language.
+- **Lightweight scope.** Focused on data display, so you pick what you need without pulling in an entire UI framework.
+
+**When to use it:** You're building analytics dashboards or data-heavy interfaces and already use Tailwind CSS.
+
+**Trade-offs:** Limited to dashboard-specific components. You'll need another library for general UI patterns like forms, navigation, and dialogs.
+
+---
+
+## 12. Park UI
+
+[Park UI](https://park-ui.com/) is a styled component library built on Ark UI primitives, available in both Panda CSS and Tailwind CSS variants.
+
+**Key strengths:**
+
+- **Pre-styled Ark UI.** Takes Ark UI's headless components and adds polished, customizable styling — similar to what shadcn/ui does for Radix.
+- **Dual styling support.** Available in both Panda CSS and Tailwind CSS variants, so you can pick the approach that fits your project.
+- **Copy-paste model.** Like shadcn/ui, components are added to your project as source files you own and customize.
+- **Design tokens.** Ships with a token system that makes global style changes straightforward.
+
+**When to use it:** You like the shadcn/ui copy-paste model but prefer Ark UI's state-machine-based primitives over Radix, or you're using Panda CSS.
+
+**Trade-offs:** Smaller community and ecosystem compared to shadcn/ui. Fewer third-party extensions and themes.
+
+---
+
+## How to Choose
+
+There's no single "best" library — the right choice depends on your project's constraints:
+
+- **Starting a new project with Tailwind v4?** HeroUI gives you the most modern stack with React Aria accessibility, compound components, and AI tooling.
+- **Want full ownership of component code?** shadcn/ui or Park UI let you copy components into your project.
+- **Building enterprise apps with complex data needs?** MUI's data grid or Ant Design's table component are hard to beat.
+- **Need maximum accessibility compliance?** HeroUI's React Aria foundation provides the strongest accessibility out of the box.
+- **Want a broad UI toolkit with quality?** HeroUI covers all core UI patterns with deep accessibility; pair with dedicated libraries for specialized needs like rich text editors.
+- **Working across multiple frameworks?** Ark UI's state machines work in React, Vue, and Solid.
+
+## Get Started with HeroUI
+
+If you're starting a new React project and want accessible, beautifully designed components with Tailwind CSS v4, give HeroUI a try:
+
+- [Quick Start Guide](/docs/react/getting-started/quick-start)
+- [Component Documentation](/docs/react/components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [Discord Community](https://discord.gg/heroui)
diff --git a/apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx b/apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx
new file mode 100644
index 0000000..bdd8154
--- /dev/null
+++ b/apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx
@@ -0,0 +1,414 @@
+---
+title: "How to Build a React Dashboard with HeroUI Pro"
+description: "Create responsive admin dashboards with HeroUI and HeroUI Pro using AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components."
+date: "2026-05-11"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["react", "dashboard", "tutorial", "heroui", "admin"]
+image: "/images/blog/build-react-dashboard-with-heroui.jpg"
+draft: true
+---
+
+
+I've watched too many teams spend their first two sprints hand-rolling a sidebar, a responsive navbar, and a metrics card layout — only to rip it out later when the requirements get real. If you have HeroUI Pro, skip that phase entirely.
+
+This post shows the Pro-first approach: start with `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and chart components, then plug in your data. The dashboard template already handles the layout, responsive behavior, and mobile navigation.
+
+## Project Setup
+
+Install HeroUI and HeroUI Pro packages:
+
+```bash
+npm install @heroui/styles @heroui/react @heroui-pro/react
+```
+
+HeroUI Pro requires access to the Pro package registry. The dashboard template uses these style imports:
+
+```css
+@import "@heroui/styles/css";
+@import "@heroui-pro/react/css";
+
+@source "../**/*.{ts,tsx}";
+
+body {
+  background-color: var(--background);
+}
+```
+
+## Use AppLayout for the Frame
+
+The app frame should come from HeroUI Pro `AppLayout`, not a custom flex layout.
+
+```tsx
+"use client";
+
+import type {ReactNode} from "react";
+
+import {AppLayout} from "@heroui-pro/react";
+import {usePathname, useRouter} from "next/navigation";
+import {useCallback} from "react";
+
+import {DashboardNavbar} from "./dashboard-navbar";
+import {DashboardSidebar} from "./dashboard-sidebar";
+
+export function AppShell({children}: {children: ReactNode}) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const navigate = useCallback((href: string) => router.push(href), [router]);
+
+  return (
+    <AppLayout
+      navbar={<DashboardNavbar title="Dashboard" />}
+      navigate={navigate}
+      sidebar={<DashboardSidebar pathname={pathname} />}
+      sidebarCollapsible="offcanvas"
+    >
+      {children}
+    </AppLayout>
+  );
+}
+```
+
+`AppLayout` handles the relationship between the sidebar, navbar, mobile menu, and content region. Keep it as the app shell and customize inside the slots.
+
+## Use Pro Sidebar and Navbar
+
+HeroUI Pro ships a `Sidebar` compound component and a `Navbar` compound component. The dashboard template uses both.
+
+```tsx
+"use client";
+
+import {Bell, Magnifier} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+import {AppLayout, Navbar, Sidebar} from "@heroui-pro/react";
+
+export function DashboardNavbar({title}: {title: string}) {
+  return (
+    <Navbar maxWidth="full">
+      <Navbar.Header>
+        <AppLayout.MenuToggle />
+        <Sidebar.Trigger />
+        <h1 className="text-foreground truncate text-xl font-semibold">{title}</h1>
+        <Navbar.Spacer />
+        <Button isIconOnly aria-label="Search" size="sm" variant="tertiary">
+          <Magnifier className="size-4" />
+        </Button>
+        <Button isIconOnly aria-label="Notifications" size="sm" variant="tertiary">
+          <Bell className="size-4" />
+        </Button>
+      </Navbar.Header>
+    </Navbar>
+  );
+}
+```
+
+For navigation, render `Sidebar.MenuItem` items instead of building custom active-link styles:
+
+```tsx
+"use client";
+
+import {ChartColumn, Gear, House, Receipt} from "@gravity-ui/icons";
+import {Sidebar} from "@heroui-pro/react";
+
+const items = [
+  {href: "/", icon: House, label: "Dashboard"},
+  {href: "/orders", icon: Receipt, label: "Orders"},
+  {href: "/analytics", icon: ChartColumn, label: "Analytics"},
+  {href: "/settings", icon: Gear, label: "Settings"},
+];
+
+export function DashboardSidebar({pathname}: {pathname: string}) {
+  return (
+    <>
+      <Sidebar>
+        <Sidebar.Content>
+          <Sidebar.Group>
+            <Sidebar.Menu aria-label="Dashboard navigation">
+              {items.map((item) => {
+                const Icon = item.icon;
+                const isCurrent =
+                  item.href === "/" ? pathname === "/" : pathname.startsWith(item.href);
+
+                return (
+                  <Sidebar.MenuItem
+                    key={item.href}
+                    href={item.href}
+                    id={item.href}
+                    isCurrent={isCurrent}
+                    textValue={item.label}
+                  >
+                    <Sidebar.MenuIcon>
+                      <Icon className="size-4" />
+                    </Sidebar.MenuIcon>
+                    <Sidebar.MenuLabel>{item.label}</Sidebar.MenuLabel>
+                  </Sidebar.MenuItem>
+                );
+              })}
+            </Sidebar.Menu>
+          </Sidebar.Group>
+        </Sidebar.Content>
+      </Sidebar>
+      <Sidebar.Mobile>{/* Reuse the same menu content for mobile. */}</Sidebar.Mobile>
+    </>
+  );
+}
+```
+
+The full Pro template also includes a header profile area, footer items, badges, and mobile content reuse.
+
+## Use KPI for Metrics
+
+Do not rebuild metric cards with `Card` unless you need a one-off design. Use `KPI` from HeroUI Pro.
+
+```tsx
+"use client";
+
+import {KPI} from "@heroui-pro/react";
+
+const chartData = [
+  {x: 1, y: 12},
+  {x: 2, y: 18},
+  {x: 3, y: 16},
+  {x: 4, y: 24},
+];
+
+export function KpiRow() {
+  return (
+    <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
+      <KPI>
+        <KPI.Header>
+          <KPI.Title>Revenue</KPI.Title>
+        </KPI.Header>
+        <KPI.Content>
+          <KPI.Value currency="USD" maximumFractionDigits={0} style="currency" value={45231} />
+          <KPI.Trend trend="up">12.5%</KPI.Trend>
+        </KPI.Content>
+        <KPI.Chart color="var(--color-accent)" data={chartData} height={60} strokeWidth={1.5} />
+      </KPI>
+    </div>
+  );
+}
+```
+
+The dashboard template uses this same pattern for analytics KPIs and finance KPIs.
+
+## Use Pro Charts
+
+HeroUI Pro chart components keep chart styling aligned with the rest of the design system.
+
+```tsx
+"use client";
+
+import {Card} from "@heroui/react";
+import {LineChart, NumberValue, TrendChip} from "@heroui-pro/react";
+
+const data = [
+  {day: "Mon", sessions: 1800, users: 1200},
+  {day: "Tue", sessions: 2400, users: 1700},
+  {day: "Wed", sessions: 2200, users: 1600},
+  {day: "Thu", sessions: 3100, users: 2100},
+];
+
+export function SessionsCard() {
+  const total = data.reduce((sum, point) => sum + point.sessions, 0);
+
+  return (
+    <Card className="rounded-2xl">
+      <Card.Header className="flex-row items-start justify-between gap-4">
+        <div className="flex flex-col gap-1">
+          <Card.Title className="text-base">Sessions over time</Card.Title>
+          <div className="flex items-baseline gap-2">
+            <NumberValue
+              className="text-foreground text-2xl font-semibold tabular-nums"
+              maximumFractionDigits={0}
+              value={total}
+            />
+            <TrendChip trend="up">18.3%</TrendChip>
+          </div>
+          <span className="text-muted text-xs">vs. previous 30 days</span>
+        </div>
+      </Card.Header>
+      <Card.Content>
+        <LineChart data={data} height={240}>
+          <LineChart.Grid vertical={false} />
+          <LineChart.XAxis dataKey="day" minTickGap={32} tickMargin={8} />
+          <LineChart.YAxis width={40} />
+          <LineChart.Line
+            dataKey="sessions"
+            dot={false}
+            name="Sessions"
+            stroke="var(--chart-2)"
+            strokeWidth={2}
+            type="monotone"
+          />
+          <LineChart.Line
+            dataKey="users"
+            dot={false}
+            name="Users"
+            stroke="var(--chart-4)"
+            strokeWidth={2}
+            type="monotone"
+          />
+          <LineChart.Tooltip content={<LineChart.TooltipContent />} />
+        </LineChart>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+Use the chart components from Pro for dashboard analytics, then swap the sample arrays for your real metrics.
+
+## Use DataGrid for Tables
+
+Dashboards usually need dense, sortable tables. Use Pro `DataGrid` instead of composing raw table markup.
+
+```tsx
+"use client";
+
+import type {DataGridColumn, DataGridSortDescriptor} from "@heroui-pro/react";
+
+import {Avatar, SearchField} from "@heroui/react";
+import {DataGrid} from "@heroui-pro/react";
+import {useMemo, useState} from "react";
+
+type Member = {
+  id: string;
+  name: string;
+  email: string;
+  avatar: string;
+  role: string;
+};
+
+const members: Member[] = [
+  {
+    id: "1",
+    name: "Kate Moore",
+    email: "kate@example.com",
+    avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue-light.jpg",
+    role: "Admin",
+  },
+];
+
+export function MembersTable() {
+  const [search, setSearch] = useState("");
+  const [sortDescriptor, setSortDescriptor] = useState<DataGridSortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const filteredMembers = useMemo(() => {
+    if (!search) return members;
+    const q = search.toLowerCase();
+
+    return members.filter(
+      (member) => member.name.toLowerCase().includes(q) || member.email.toLowerCase().includes(q),
+    );
+  }, [search]);
+
+  const columns = useMemo<DataGridColumn<Member>[]>(
+    () => [
+      {
+        accessorKey: "name",
+        allowsSorting: true,
+        cell: (item) => (
+          <div className="flex items-center gap-3">
+            <Avatar className="size-8">
+              <Avatar.Image alt={item.name} src={item.avatar} />
+              <Avatar.Fallback>{item.name[0]}</Avatar.Fallback>
+            </Avatar>
+            <div className="flex min-w-0 flex-col">
+              <span className="text-xs font-medium">{item.name}</span>
+              <span className="text-muted text-xs">{item.email}</span>
+            </div>
+          </div>
+        ),
+        header: "Member",
+        id: "name",
+        isRowHeader: true,
+        minWidth: 220,
+      },
+      {
+        accessorKey: "role",
+        allowsSorting: true,
+        header: "Role",
+        id: "role",
+        minWidth: 160,
+      },
+    ],
+    [],
+  );
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField className="w-full sm:w-[220px]" name="member-search" onChange={setSearch}>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+
+      <DataGrid
+        aria-label="Members"
+        columns={columns}
+        contentClassName="min-w-[520px]"
+        data={filteredMembers}
+        getRowId={(item) => item.id}
+        sortDescriptor={sortDescriptor}
+        onSortChange={setSortDescriptor}
+      />
+    </div>
+  );
+}
+```
+
+This matches the template's table direction: typed columns, a controlled sort descriptor, search outside the grid, and `getRowId` for stable row identity.
+
+## Compose the Dashboard Page
+
+The page should mostly assemble widgets. In the Pro template, the dashboard view looks like this:
+
+```tsx
+"use client";
+
+import {DashboardToolbar} from "../widgets/dashboard-toolbar";
+import {EmployeesTable} from "../widgets/employees-table";
+import {KpiRow} from "../widgets/kpi-row";
+import {SalesPerformanceCard} from "../widgets/sales-performance-card";
+import {TrafficSourceCard} from "../widgets/traffic-source-card";
+
+export function DashboardPage() {
+  return (
+    <div className="mx-auto flex max-w-7xl flex-col gap-4 px-5 pb-10 pt-4">
+      <DashboardToolbar />
+      <KpiRow />
+      <div className="grid grid-cols-1 gap-3 lg:grid-cols-2">
+        <SalesPerformanceCard />
+        <TrafficSourceCard />
+      </div>
+      <EmployeesTable />
+    </div>
+  );
+}
+```
+
+That is the main architectural point: the page should read like product composition, not infrastructure.
+
+## Why HeroUI for Dashboards
+
+Dashboards are dense — data tables, form controls, navigation, and overlays on a single screen. HeroUI handles the accessibility and styling for all of those pieces so you can focus on your data layer.
+
+- **Data tables that handle accessibility for you.** Sortable columns, row selection, keyboard navigation, and screen reader announcements come from React Aria. You don't reimplement them per table.
+- **Static CSS for data-heavy pages.** Tailwind v4 generates all styles at build time. Dashboards with KPI cards, charts, and grids don't pay a runtime styling tax.
+- **Pro primitives instead of hand-rolled infrastructure.** AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components from [HeroUI Pro](https://heroui.com/pro) save weeks of dashboard scaffold work.
+- **AI assistants that know the Pro API.** The [MCP server](/docs/react/getting-started/mcp-server) and [agent skills](/docs/react/getting-started/agent-skills) let AI tools scaffold dashboard views with correct component APIs instead of guessing.
+
+## Next Steps
+
+- Start from the [HeroUI Pro](https://heroui.com/pro) dashboard template if you have Pro access.
+- Replace the mock files in `src/data/*` with your API, database, or analytics source.
+- Keep `AppLayout`, `Sidebar`, `Navbar`, `KPI`, `DataGrid`, and Pro charts as the foundation.
+- Use base [HeroUI components](/docs/react/components) for local UI that does not need a Pro primitive.
diff --git a/apps/docs/content/blog/en/choosing-react-native-ui-library.mdx b/apps/docs/content/blog/en/choosing-react-native-ui-library.mdx
new file mode 100644
index 0000000..ae6357f
--- /dev/null
+++ b/apps/docs/content/blog/en/choosing-react-native-ui-library.mdx
@@ -0,0 +1,96 @@
+---
+title: "Choosing a React Native UI Library"
+description: "A practical framework for choosing a React Native UI library, and where HeroUI Native fits."
+date: "2026-05-12"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["native", "react-native", "ui-libraries", "comparison"]
+image: "/images/blog/choosing-react-native-ui-library.jpg"
+draft: true
+---
+
+Choosing a React Native UI library is not just a component-count decision. It is a maintenance decision, a design decision, and increasingly an AI workflow decision.
+
+The library you choose becomes the vocabulary your team uses every day. It shapes how designers hand off screens, how engineers compose interfaces, how quickly you can fix accessibility issues, and how well AI agents generate code that actually compiles.
+
+This guide explains how we think about that decision, and why HeroUI Native is built the way it is.
+
+## What to Evaluate
+
+Before comparing libraries, write down what your product needs:
+
+- Are you building a consumer app, internal tool, SaaS companion app, marketplace, fintech app, or mobile-first product?
+- Do you need bottom sheets, dialogs, menus, tabs, forms, toasts, skeletons, and list patterns?
+- Is your design system already defined in Figma?
+- Do you need AI assistants to generate UI reliably?
+- Does your team want a package that updates over time, or copied source code you fully own?
+
+Those questions matter more than a screenshot gallery.
+
+## Package vs. Copy-Paste
+
+Copy-paste UI can be useful when you need total code ownership. The trade-off is maintenance. Once the code is in your app, your team owns the updates, accessibility fixes, dependency changes, and design consistency.
+
+HeroUI Native takes the package approach:
+
+- Install `heroui-native`.
+- Configure Uniwind and the provider once.
+- Compose components through documented APIs.
+- Update the package when fixes and improvements ship.
+- Use MCP/LLM docs so AI tools can read current component documentation.
+
+That does not mean a package is always better. If your team has a dedicated design system group and wants to own every line of component code, copied source may fit. But if your team wants to ship product screens without becoming a component-maintenance team, a maintained package is usually the healthier default.
+
+## Design Quality Is a Feature
+
+Mobile apps are judged in milliseconds. A button press, sheet transition, input focus state, disabled control, or empty state can make an app feel cared for or unfinished.
+
+HeroUI Native is intentionally opinionated about the baseline:
+
+- Semantic component variants create a clear visual hierarchy.
+- Components are designed to look complete before customization.
+- Theming happens through CSS variables and Uniwind.
+- Animated components use React Native animation libraries instead of web-only assumptions.
+- Component APIs follow compound composition so you can adjust structure without forking internals.
+
+The goal is not to lock you into one visual identity. The goal is to start from a designed system rather than a pile of primitives.
+
+## Ecosystem Fit
+
+HeroUI Native is strongest when you want one ecosystem across product surfaces:
+
+- Web product: [HeroUI React](/docs/react/getting-started/quick-start)
+- Mobile product: [HeroUI Native](/docs/native/getting-started)
+- Premium app surfaces: [HeroUI Pro](https://heroui.com/pro)
+- Design handoff: [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- AI workflow: [Native MCP Server](/docs/native/getting-started/mcp-server), [llms.txt](/docs/native/getting-started/llms-txt), and [Agent Skills](/docs/native/getting-started/agent-skills)
+
+That ecosystem is the advantage. A component library by itself saves some time. A design system, docs, Figma kit, AI context, and maintained package save coordination cost.
+
+## Where HeroUI Native Is Different
+
+HeroUI Native is built specifically for React Native. It does not ask you to use web imports or CSS files that do not belong in mobile apps.
+
+Use Native patterns:
+
+```tsx
+import {Button} from "heroui-native";
+
+<Button variant="primary" onPress={() => console.log("Pressed")}>
+  <Button.Label>Continue</Button.Label>
+</Button>;
+```
+
+Avoid web patterns:
+
+Do not use the HeroUI web package or web-only event handlers in React Native screens.
+
+HeroUI Native uses `onPress`, `HeroUINativeProvider`, `GestureHandlerRootView`, Uniwind, and native overlay/portal patterns because those are the right abstractions for mobile.
+
+## Recommendation
+
+Choose HeroUI Native when your team values design quality, maintainability, and ecosystem leverage. It is especially compelling if you already use HeroUI on the web, work from Figma, or build with AI coding assistants.
+
+Start with the [Quick Start](/docs/native/getting-started/quick-start), then read the [Design Principles](/docs/native/getting-started/design-principles) before building your first screen.
diff --git a/apps/docs/content/blog/en/design-to-code-with-heroui-native.mdx b/apps/docs/content/blog/en/design-to-code-with-heroui-native.mdx
new file mode 100644
index 0000000..523ec26
--- /dev/null
+++ b/apps/docs/content/blog/en/design-to-code-with-heroui-native.mdx
@@ -0,0 +1,125 @@
+---
+title: "Design to Code with HeroUI Native"
+description: "How HeroUI Native connects Figma, code, and AI-assisted mobile development."
+date: "2026-05-13"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["native", "react-native", "design-system", "figma", "ai"]
+image: "/images/blog/design-to-code-with-heroui-native.jpg"
+draft: true
+---
+
+The hardest part of a mobile design system is not drawing components. It is keeping design, code, documentation, and generated AI output aligned over time.
+
+HeroUI Native is built for that workflow. The library gives developers a maintained React Native component system, gives designers a shared HeroUI visual language through Figma, and gives AI assistants structured documentation through MCP, llms.txt, and skills.
+
+## The Problem
+
+Most teams drift in predictable ways:
+
+- Figma components use one naming system.
+- React Native components use another.
+- Design tokens get translated by hand.
+- AI agents guess props from old examples.
+- Engineers copy a component once, customize it, and rarely bring upstream fixes back in.
+
+The result is subtle inconsistency. One screen has different spacing. Another uses the wrong disabled state. A generated component imports web HeroUI into a native app. The first version ships, but the system becomes harder to maintain.
+
+HeroUI Native is designed to reduce that drift.
+
+## Shared Mental Model
+
+HeroUI Native uses the same product-level ideas as the rest of the HeroUI ecosystem:
+
+- Semantic variants like `primary`, `secondary`, and `tertiary`.
+- Compound components for flexible composition.
+- Theme variables for semantic colors and surfaces.
+- Component documentation with anatomy, props, examples, and usage patterns.
+- AI-readable docs for agents.
+
+The implementation is native, not web. HeroUI Native uses React Native, Uniwind, `HeroUINativeProvider`, and mobile interaction patterns. But the design language stays familiar.
+
+```tsx
+import {Button, Card} from "heroui-native";
+
+<Card>
+  <Card.Header>
+    <Card.Title>Workspace</Card.Title>
+    <Card.Description>Invite your team and manage access.</Card.Description>
+  </Card.Header>
+  <Card.Body>{/* Screen content */}</Card.Body>
+  <Card.Footer>
+    <Button variant="primary">
+      <Button.Label>Invite member</Button.Label>
+    </Button>
+  </Card.Footer>
+</Card>;
+```
+
+## Figma Kit V3
+
+The [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) is the design-side entry point for the ecosystem. It is linked from the Native docs so teams can work from the same visual system while building mobile screens.
+
+Use it to:
+
+- Start from HeroUI's visual language instead of blank frames.
+- Keep component names and variants close to the code model.
+- Align designers and developers on hierarchy, states, and spacing.
+- Create mobile product screens that feel connected to the rest of the HeroUI ecosystem.
+
+Figma does not replace implementation details like keyboard handling, safe areas, bottom sheets, or screen reader behavior. But a shared kit reduces the translation cost between design and code.
+
+## AI Context That Knows Native
+
+AI coding tools are useful only when they have current context. Without that, they often mix web and native APIs.
+
+HeroUI Native provides dedicated AI entry points:
+
+- [/native/llms.txt](/native/llms.txt) for a quick Native documentation index.
+- [/native/llms-full.txt](/native/llms-full.txt) for complete Native documentation.
+- [/native/llms-components.txt](/native/llms-components.txt) for component docs only.
+- [/native/llms-patterns.txt](/native/llms-patterns.txt) for common patterns.
+- [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server), published as `@heroui/native-mcp`.
+- [HeroUI Native Agent Skills](/docs/native/getting-started/agent-skills).
+
+That matters because Native code has different rules:
+
+- Import from `heroui-native`.
+- Use React Native press handlers such as `onPress`.
+- Configure `HeroUINativeProvider`.
+- Wrap the app with `GestureHandlerRootView`.
+- Use Uniwind and `heroui-native/styles`.
+- Use Native component anatomy, not web component anatomy.
+
+The MCP server and skills help agents follow those rules.
+
+## A Practical Workflow
+
+Here is the workflow we recommend:
+
+1. **Design from the Figma kit.** Start from HeroUI's component language instead of one-off mobile components.
+2. **Install HeroUI Native correctly.** Follow the [Quick Start](/docs/native/getting-started/quick-start) so Uniwind, peer dependencies, styles, and providers are configured.
+3. **Give agents the docs.** Add the [MCP server](/docs/native/getting-started/mcp-server) or reference [/native/llms-full.txt](/native/llms-full.txt).
+4. **Build screens with compound components.** Compose components using dot notation and semantic variants.
+5. **Customize through theme variables.** Keep brand-level changes in the theming layer, not scattered across every screen.
+6. **Update through the package.** Treat HeroUI Native as a maintained dependency, not a copied snapshot.
+
+## Why This Helps
+
+Design-to-code is not about removing engineers or designers. It is about reducing translation loss.
+
+HeroUI Native helps because:
+
+- Designers start from the HeroUI visual system.
+- Developers get a maintained React Native package.
+- AI assistants get current component docs.
+- Teams keep a consistent vocabulary across web and mobile.
+- The library can evolve without every app owning every internal component detail.
+
+That is the long-term value: not just faster first screens, but fewer inconsistencies as the app grows.
+
+## Next Step
+
+Install the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server) in your editor, then ask your assistant to build a screen using the [Quick Start](/docs/native/getting-started/quick-start) and the components in [All Components](/docs/native/components).
diff --git a/apps/docs/content/blog/en/heroui-vs-chakra-ui.mdx b/apps/docs/content/blog/en/heroui-vs-chakra-ui.mdx
new file mode 100644
index 0000000..f3cbb78
--- /dev/null
+++ b/apps/docs/content/blog/en/heroui-vs-chakra-ui.mdx
@@ -0,0 +1,235 @@
+---
+title: "HeroUI vs Chakra UI: Which React UI Library Should You Choose in 2026?"
+description: "A comprehensive comparison of HeroUI and Chakra UI — accessibility, styling approaches, performance, and when to choose each React component library."
+date: "2026-05-14"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["comparison", "heroui", "chakra-ui", "react"]
+draft: true
+---
+
+If you're picking a React component library in 2026, HeroUI and Chakra UI are both strong contenders. HeroUI styles components with Tailwind CSS v4 utility classes and builds accessibility on React Aria, using a compound component API (`Card.Header`, `Modal.Body`) instead of style props. Chakra UI pioneered the style-props pattern and has rebuilt on Panda CSS and Ark UI. Both ship accessible components — but they take fundamentally different approaches to styling, component design, and developer tooling that matter more than you might think.
+
+This guide walks through where each library shines, where it falls short, and how to decide which one fits your project.
+
+## The TL;DR
+
+| Feature | HeroUI v3 | Chakra UI v3 |
+|---------|-----------|--------------|
+| **Styling** | Tailwind CSS v4 (static CSS) | Panda CSS API-based styling system and style props |
+| **Accessibility** | React Aria (Adobe) | Ark UI / Zag.js (Chakra team) |
+| **Component API** | Compound components + className | Style props on components |
+| **CSS output** | Static CSS from Tailwind and HeroUI styles | Runtime styling in the stable Chakra setup |
+| **AI tooling** | MCP server, llms.txt, agent skills | MCP server and public docs |
+| **Theming** | CSS custom properties + `@theme` | Theme tokens + semantic tokens |
+| **React 19** | Supported | Supported |
+| **Server components** | Static pieces can stay server-rendered; interactive pieces use client boundaries | Depends on component and styling usage |
+
+## Styling: Two Different Philosophies
+
+This is the biggest architectural difference between the two libraries, and it's worth understanding deeply because it affects everything downstream — from how you customize components to how your app performs in production.
+
+### Chakra UI: Style Props
+
+Chakra pioneered the "style props" pattern in React. Instead of writing CSS classes, you style components through JSX props:
+
+```tsx
+import { Box, Button } from "@chakra-ui/react";
+
+<Box bg="blue.500" p={4} borderRadius="lg">
+  <Button colorPalette="blue" size="lg">
+    Click me
+  </Button>
+</Box>
+```
+
+This is ergonomic for quick prototyping. You stay in JSX, your styles are co-located with your markup, and the design token system (`blue.500`, `p={4}`) keeps things consistent. Chakra's current theming docs describe the styling system as built around Panda CSS APIs like `defineConfig`, `createSystem`, recipes, slot recipes, tokens, and semantic tokens.
+
+The trade-off is that style props can make JSX verbose for complex layouts. A card with a dozen styling tweaks ends up with more prop noise than markup, and the default styling model is still different from a static CSS/Tailwind setup.
+
+### HeroUI: Tailwind CSS v4
+
+HeroUI takes the opposite approach — components are styled with Tailwind CSS utility classes, and you customize them the same way you'd customize any Tailwind element:
+
+```tsx
+import { Card, Button } from "@heroui/react";
+
+<Card className="bg-blue-500 p-4 rounded-lg">
+  <Card.Header>
+    <Card.Title>My Card</Card.Title>
+  </Card.Header>
+  <Card.Content>
+    <Button size="lg">Click me</Button>
+  </Card.Content>
+</Card>
+```
+
+Because Tailwind v4 and HeroUI styles are CSS-first, there is no component-level CSS-in-JS runtime in the HeroUI styling path. HeroUI's theming system uses CSS custom properties and Tailwind's `@theme` directive, so you can swap visual systems by changing variables.
+
+If you're already using Tailwind in your project, HeroUI slots in naturally. If you're not, adopting Tailwind is a separate decision that comes with its own learning curve.
+
+### Which styling approach is better?
+
+Neither is objectively superior — it depends on your team.
+
+Style props are great when you want to move fast and keep everything in JSX. They're intuitive for developers who think in "component properties" rather than "CSS classes." But they create a tight coupling between your component library and your styling strategy.
+
+Tailwind utilities are great when you want a universal styling language that works the same way on library components and custom components. The build-time approach means better performance, and the utility-first workflow is something most React developers already know in 2026.
+
+## Accessibility Foundations
+
+Both libraries take accessibility seriously, but they build on different foundations.
+
+### HeroUI: React Aria
+
+HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitives. React Aria handles keyboard navigation, screen reader announcements, focus management, and ARIA attributes for every component. It's the same foundation that powers Adobe's own design system (Spectrum), and it's one of the most thoroughly tested accessibility layers in the React ecosystem.
+
+What this means in practice: HeroUI components handle edge cases that many libraries miss. Focus trapping in modals works correctly with screen readers. Comboboxes announce option counts. Date pickers support keyboard navigation across months and years. These aren't features you'd notice in a demo, but they're critical for shipping accessible software.
+
+### Chakra UI: Ark UI / Zag.js
+
+Chakra v3 rebuilt its accessibility layer on [Ark UI](https://ark-ui.com/) and [Zag.js](https://zagjs.com/), both maintained by the Chakra team. Zag uses state machines to model component behavior, which makes the logic predictable and testable. Ark UI wraps Zag into framework-specific components.
+
+This is a solid approach, and Chakra's accessibility is genuinely good. The main difference is maturity — React Aria has been in production at Adobe for years and has a larger surface area of accessibility testing. Zag.js is newer and still expanding its component coverage.
+
+### The practical difference
+
+For most applications, both libraries will produce accessible UIs. The gap shows up in complex components — date pickers, comboboxes, drag-and-drop — where React Aria's deeper investment in accessibility edge cases gives HeroUI an advantage.
+
+## Component API Design
+
+This is where the day-to-day developer experience diverges most noticeably.
+
+### HeroUI: Compound Components
+
+HeroUI uses a compound component pattern where a parent component exposes sub-components through dot notation:
+
+```tsx
+import { Modal, Button } from "@heroui/react";
+
+<Modal>
+  <Button>Open Modal</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.CloseTrigger />
+        <Modal.Header>
+          <Modal.Heading>Confirm Action</Modal.Heading>
+        </Modal.Header>
+        <Modal.Body>Are you sure?</Modal.Body>
+        <Modal.Footer>
+          <Button variant="ghost">Cancel</Button>
+          <Button>Confirm</Button>
+        </Modal.Footer>
+      </Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+This is more verbose than a flat prop API, but it gives you complete control over the component's structure. You can reorder parts, add custom elements between them, or omit parts entirely. It's the same pattern used by Radix UI, and it scales well for complex UIs.
+
+### Chakra UI: Flat Components with Style Props
+
+Chakra components are flatter and rely on props for configuration:
+
+```tsx
+import { DialogRoot, DialogContent, DialogHeader, DialogBody, DialogFooter } from "@chakra-ui/react";
+
+<DialogRoot>
+  <DialogContent>
+    <DialogHeader>Confirm Action</DialogHeader>
+    <DialogBody>Are you sure?</DialogBody>
+    <DialogFooter>
+      <Button variant="ghost">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</DialogRoot>
+```
+
+Chakra v3 moved toward a more composable approach compared to v2, but the styling still happens through props rather than class names. This makes the JSX self-documenting in one sense (you can see all the styles) but noisy in another (the styles obscure the structure).
+
+## Performance
+
+Performance differences between modern component libraries are often overstated, but there are real architectural factors worth considering.
+
+### Build-time vs. runtime CSS
+
+HeroUI generates all CSS at build time through Tailwind v4. Your production bundle includes only the utility classes your components actually use, and there's zero JavaScript overhead for style computation at runtime.
+
+Chakra's styling API is much more structured than the older Chakra v2 era and is built around the Panda CSS API. It is still a different authoring model from HeroUI's Tailwind/CSS-variable path, so teams should test the exact runtime and bundle impact in their own app.
+
+### Bundle size
+
+HeroUI components are thin wrappers around React Aria primitives plus CSS classes. Chakra components carry a richer style-props and theme system. The practical impact depends on which components you use and how aggressively your app splits routes.
+
+### Server components
+
+HeroUI's static pieces can stay in React Server Component trees, while interactive pieces need client boundaries. Chakra's behavior depends on which components and style props you use, so I would test the exact pages you care about before making performance promises.
+
+## AI Tooling
+
+This is an area where HeroUI has a clear, measurable advantage.
+
+### HeroUI's AI stack
+
+HeroUI ships three tools specifically designed for AI coding assistants:
+
+- **MCP server.** A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that exposes component documentation, API references, and code examples to AI agents. When your AI assistant has access to this, it can look up the exact props, compound component structure, and usage patterns for any HeroUI component — instead of guessing.
+- **llms.txt.** A structured text file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives LLMs a condensed reference of the entire library. This is the equivalent of giving your AI assistant a cheat sheet.
+- **Agent skills.** Pre-built [skill files](/docs/react/getting-started/agent-skills) for AI coding tools like Cursor and Claude Code that teach agents how to scaffold components, use the correct import paths, and follow HeroUI conventions.
+
+In practice, this gives AI assistants a better chance of generating current HeroUI v3 code. They can look up the compound component patterns, prop names, and import paths instead of guessing from mixed training data.
+
+### Chakra UI's AI support
+
+Chakra's docs now point developers to an MCP server, so it is not accurate to say Chakra has no AI support. The practical difference is that HeroUI's AI context is specific to HeroUI's v3 compound components, Tailwind v4 styling, and package API, while Chakra's context teaches Chakra's style-prop and system APIs.
+
+### Why this matters
+
+If you're using AI coding assistants daily (and in 2026, most developers are), the quality of AI-generated code directly affects your productivity. Getting correct code on the first generation saves you from debugging hallucinated props, wrong imports, and deprecated patterns.
+
+## Ecosystem and Community
+
+Both libraries have active communities, good TypeScript support, and work with Next.js. HeroUI's community is growing quickly with strong documentation, an active Discord, and HeroUI Pro for teams that need premium components.
+
+HeroUI also invests heavily in AI developer tooling — MCP servers, llms.txt, and agent skills — which is increasingly important as AI-assisted development becomes the default workflow.
+
+## Design Quality
+
+Design quality is subjective, but there are measurable differences in how these libraries handle visual polish.
+
+HeroUI ships with refined default animations, consistent spacing tokens, and a design system that looks polished out of the box. Components have subtle transitions, well-balanced proportions, and sensible defaults that work without customization. The theme system supports variants like "glass" and "brutalism" for distinct visual identities.
+
+Chakra provides good-looking defaults as well, especially in v3. The design token system is well-organized and the components are clean. However, HeroUI's defaults tend to feel more opinionated and "designed" — there's more attention to micro-interactions, shadows, and spacing out of the box.
+
+If you plan to heavily customize the visual design anyway, this matters less. If you want something that looks great with minimal theming effort, HeroUI has an edge.
+
+## When to Choose Each
+
+### Choose HeroUI if:
+
+- You're already using Tailwind CSS (or want to)
+- Accessibility is a hard requirement and you want React Aria's depth
+- You use AI coding assistants and want first-class tooling support
+- You prefer compound component APIs that give you structural control
+- You want polished defaults with minimal custom theming
+- You're building with React 19 and want good server component support
+- Performance matters and you prefer a static CSS styling path
+
+### When Chakra UI might work
+
+Chakra UI can be a reasonable choice if your team doesn't use Tailwind CSS and prefers styling through component props, or if you're maintaining an existing Chakra codebase. However, Chakra's reliance on Panda CSS and runtime styling introduces trade-offs in performance and bundle size that HeroUI avoids entirely with static CSS.
+
+## Summary
+
+For new projects in 2026, HeroUI's modern stack — React Aria accessibility, Tailwind CSS v4 static styling, compound component architecture, and first-party AI tooling — provides a stronger foundation for building production applications. If you're starting fresh, HeroUI is the clear choice.
+
+---
+
+## Get Started with HeroUI
+
+Ready to try HeroUI? Check out the [quick start guide](/docs/react/getting-started/quick-start) to set up your first project in under five minutes. If you want to see components in action, browse the [component docs](/docs/react/components) or install the [MCP server](/docs/react/getting-started/mcp-server) to let your AI assistant handle the boilerplate.
diff --git a/apps/docs/content/blog/en/heroui-vs-mantine.mdx b/apps/docs/content/blog/en/heroui-vs-mantine.mdx
new file mode 100644
index 0000000..cc0f951
--- /dev/null
+++ b/apps/docs/content/blog/en/heroui-vs-mantine.mdx
@@ -0,0 +1,266 @@
+---
+title: "HeroUI vs Mantine: Which React Component Library is Right for You in 2026?"
+description: "Comparing HeroUI and Mantine — two popular React component libraries with different approaches to styling, component breadth, and developer tooling."
+date: "2026-05-15"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["comparison", "heroui", "mantine", "react"]
+draft: true
+---
+
+HeroUI and Mantine are both modern, well-maintained React component libraries with genuine strengths. But they're built on very different philosophies. Mantine is a batteries-included toolkit with a very broad component and hooks catalog; Mantine's homepage currently describes it as `120+` components and `70+` hooks. HeroUI pairs React Aria's deep accessibility layer with Tailwind CSS v4 and a compound component API, plus first-party AI tooling through MCP, llms.txt, and agent skills.
+
+This comparison breaks down the real differences — not just feature checklists, but the trade-offs that actually affect your daily development workflow.
+
+## Quick Comparison
+
+| Feature | HeroUI v3 | Mantine v8 |
+|---------|-----------|------------|
+| **Components** | Broad focused set | 120+ components |
+| **Styling** | Tailwind CSS v4 (CSS-first) | CSS files / CSS Modules + PostCSS |
+| **Accessibility** | React Aria (Adobe) | Built into Mantine components |
+| **Hooks library** | None (use React Aria hooks for interaction/accessibility needs) | 70+ hooks |
+| **Component API** | Compound components | Flat components with props |
+| **AI tooling** | MCP server, llms.txt, agent skills | MCP server, llms.txt, skills |
+| **Form handling** | Works with any form library | Built-in @mantine/form |
+| **CSS runtime** | Zero | Zero |
+| **Theming** | CSS custom properties + @theme | CSS variables + MantineProvider |
+| **React 19** | Supported | Supported |
+
+## Component Coverage
+
+Mantine ships a large number of components across several packages, including a carousel, rich text editor, spotlight search, and notification system:
+
+- **@mantine/core** — Buttons, inputs, modals, navigation, layout, typography
+- **@mantine/dates** — Date pickers, calendars, date range inputs
+- **@mantine/charts** — Charts built on Recharts
+- **@mantine/notifications** — Toast notifications system
+- **@mantine/tiptap** — Rich text editor
+- **@mantine/spotlight** — Command palette / spotlight search
+- **@mantine/dropzone** — File upload with drag-and-drop
+- **@mantine/carousel** — Carousel / slider component
+- **@mantine/nprogress** — Page loading progress bar
+
+Mantine ships a large number of components, though breadth comes with trade-offs — larger bundle sizes, more APIs to learn, and components that may not all receive the same level of polish and accessibility testing.
+
+HeroUI takes a more focused approach. The core library covers the essential component set — buttons, forms, modals, tables, navigation, data display — with depth rather than breadth. Components like `Table` support sorting, selection, column resizing, and infinite scrolling out of the box:
+
+```tsx
+import { Table } from "@heroui/react";
+
+<Table>
+  <Table.ScrollContainer>
+    <Table.Content aria-label="Users">
+      <Table.Header>
+        <Table.Column allowsSorting>Name</Table.Column>
+        <Table.Column allowsSorting>Role</Table.Column>
+        <Table.Column>Status</Table.Column>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Kate Moore</Table.Cell>
+          <Table.Cell>Engineer</Table.Cell>
+          <Table.Cell>Active</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+For charts, notifications, rich text editing, and other specialized needs, you'll combine HeroUI with dedicated libraries. This is a trade-off: more integration work, but you pick the best tool for each job.
+
+## Styling Approaches
+
+This is where the libraries diverge most sharply.
+
+### Mantine: CSS Modules + PostCSS
+
+Mantine uses CSS Modules for component styling. Each component has its own scoped CSS, and you customize components by targeting specific class selectors or using Mantine's `classNames` prop:
+
+```tsx
+import { Button } from "@mantine/core";
+import classes from "./MyButton.module.css";
+
+<Button classNames={{ root: classes.root, label: classes.label }}>
+  Click me
+</Button>
+```
+
+This approach is familiar to anyone who's used CSS Modules. Styles are scoped, there's no runtime overhead, and you have direct access to override any part of a component. Mantine also supports a `styles` prop for inline style overrides and a global theme object for system-wide customization.
+
+The downside is that you need to understand Mantine's internal class structure to customize deeply. Each component has its own set of "style names" (like `root`, `label`, `inner` for Button), and you need to reference the docs to know which ones to target.
+
+### HeroUI: Tailwind CSS v4
+
+HeroUI components are styled with Tailwind CSS v4 utilities. You customize components the same way you style everything else in a Tailwind project — with `className`:
+
+```tsx
+import { Button } from "@heroui/react";
+
+<Button className="bg-gradient-to-r from-purple-500 to-pink-500 text-white shadow-lg">
+  Click me
+</Button>
+```
+
+For component sub-parts, HeroUI's compound component pattern lets you apply classes to any section:
+
+```tsx
+import { Card } from "@heroui/react";
+
+<Card className="max-w-md">
+  <Card.Header className="pb-0">
+    <Card.Title className="text-xl font-bold">Title</Card.Title>
+    <Card.Description>Subtitle here</Card.Description>
+  </Card.Header>
+  <Card.Content className="py-4">
+    Content goes here
+  </Card.Content>
+  <Card.Footer className="justify-end gap-2">
+    <Button variant="ghost">Cancel</Button>
+    <Button>Save</Button>
+  </Card.Footer>
+</Card>
+```
+
+Because each sub-component accepts `className`, you don't need to learn a separate styling API or memorize internal class name structures. If you know Tailwind, you know how to customize HeroUI.
+
+### The practical trade-off
+
+If your project already uses Tailwind CSS, HeroUI fits like a glove — there's no second styling system to learn. If your project uses CSS Modules or plain CSS, Mantine aligns more naturally with your existing approach. Adopting HeroUI without Tailwind means adopting Tailwind, which is a separate (and significant) decision.
+
+Both approaches produce zero runtime CSS overhead. Neither ships CSS-in-JS to the browser.
+
+## Accessibility
+
+This is where the difference in architectural foundations becomes most apparent.
+
+### HeroUI: React Aria (Enterprise-Grade)
+
+HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. React Aria handles screen reader support, keyboard navigation, focus management, ARIA attributes, internationalization, and interaction patterns for every component.
+
+React Aria is one of the most thoroughly tested accessibility layers available for React. It powers Adobe's Spectrum design system and handles details like keyboard behavior, focus management, screen reader announcements, touch interactions, and internationalization. Components like date pickers, comboboxes, and tables benefit from that depth in places most teams do not want to reimplement themselves.
+
+### Mantine: Good Built-In Accessibility
+
+Mantine has solid accessibility built into its components. WAI-ARIA attributes, keyboard navigation, and focus management are handled for common patterns. For the vast majority of applications, Mantine's accessibility is perfectly adequate.
+
+The gap appears in complex, interaction-heavy components. Mantine doesn't use an external accessibility layer like React Aria or Radix — it implements accessibility in-house. This means the depth of testing and edge case coverage is necessarily narrower than a dedicated accessibility library backed by a company the size of Adobe.
+
+### When does this matter?
+
+If you're building consumer software where basic keyboard navigation and screen reader support are sufficient, both libraries will serve you well. If you're building for government, healthcare, finance, or any domain with strict WCAG compliance requirements, HeroUI's React Aria foundation provides a higher assurance level.
+
+## The Hooks Library
+
+Mantine also includes a utility hooks package (`@mantine/hooks`). HeroUI focuses on component quality and leverages the broader React ecosystem for utility hooks. The hooks package covers common categories like:
+
+- **Browser APIs**: `useClipboard`, `useFullscreen`, `useMediaQuery`, `useLocalStorage`, `useGeolocation`
+- **UI patterns**: `useDisclosure`, `usePagination`, `useScrollIntoView`, `useHover`
+- **Utilities**: `useDebounce`, `useThrottle`, `useInterval`, `useCounter`, `usePrevious`
+- **State management**: `useListState`, `useSetState`, `useMap`, `useQueue`
+
+For similar utility hooks, you'd use community packages like `usehooks-ts`, or React Aria's hooks (which cover accessibility-related patterns like `useFocusRing`, `usePress`, and `useSearchField`). HeroUI focuses on components and leaves general-purpose utilities to the broader ecosystem.
+
+If your team values having a single, cohesive dependency for both components and utility hooks, Mantine's integrated approach is appealing. If you prefer picking best-in-class tools for each concern, HeroUI's focused approach works better.
+
+## AI Tooling
+
+This is an area where HeroUI has invested heavily and Mantine hasn't.
+
+### HeroUI's AI developer tools
+
+HeroUI ships three first-class integrations for AI coding assistants:
+
+- **MCP server.** A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that AI agents can query for component documentation, APIs, and usage examples. When your AI assistant is connected to this server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component in real time.
+
+- **llms.txt.** A structured reference file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives large language models a condensed, accurate reference for the entire library. This is a standardized format that AI tools can consume to avoid hallucinating APIs.
+
+- **Agent skills.** Pre-built [skill files](/docs/react/getting-started/agent-skills) for tools like Cursor and Claude Code that teach AI agents HeroUI's patterns — correct imports, compound component structures, styling conventions, and project scaffolding.
+
+The result is that AI assistants have a better chance of generating current HeroUI code. They can use the correct compound component patterns (`Modal.Header`, `Card.Content`, `Table.Row`), the right import paths, and actual v3 APIs instead of guessing from mixed training data.
+
+### Mantine's AI story
+
+Mantine has strong AI-facing documentation too: its homepage documents `llms.txt`, skills, and `@mantine/mcp-server`. The practical difference is not "HeroUI has AI and Mantine does not." It is that HeroUI's AI context is specific to HeroUI's compound components, Tailwind v4 styling, and package API, while Mantine's context teaches Mantine's component and hooks ecosystem.
+
+### Why this matters in 2026
+
+Most developers use AI assistants daily. When your component library has first-class AI tooling, agents can verify current APIs before writing code. That matters for both libraries.
+
+## Design Quality and Polish
+
+Both libraries ship good-looking defaults, but the design sensibilities are different.
+
+HeroUI's defaults are more opinionated and "designed." Components ship with refined animations, carefully balanced spacing, smooth transitions, and attention to micro-interactions. Buttons have subtle press states. Modals animate in with spring physics. Cards have balanced padding and shadow hierarchies. The library includes theme variants (like "glass" and "brutalism") for distinct visual identities without custom CSS.
+
+Mantine's defaults are clean and professional but more utilitarian. Components are well-proportioned and consistent, but they're designed to be a neutral starting point rather than a finished look. If you're planning to apply significant custom styling, this is actually an advantage — there's less opinionated design to override.
+
+The trade-off is straightforward: HeroUI looks more polished out of the box with less effort. Mantine gives you a more neutral canvas to build on.
+
+## TypeScript Support
+
+Both libraries have excellent TypeScript support. Components are fully typed, props interfaces are well-documented, and autocomplete works as expected in modern editors.
+
+HeroUI's compound component pattern means TypeScript can verify the structure of your component trees:
+
+```tsx
+import { Tabs } from "@heroui/react";
+
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Sections">
+      <Tabs.Tab id="profile">Profile</Tabs.Tab>
+      <Tabs.Tab id="settings">Settings</Tabs.Tab>
+      <Tabs.Indicator />
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="profile">Profile content</Tabs.Panel>
+  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+Mantine provides equally strong types with a different API surface:
+
+```tsx
+import { Tabs } from "@mantine/core";
+
+<Tabs defaultValue="profile">
+  <Tabs.List>
+    <Tabs.Tab value="profile">Profile</Tabs.Tab>
+    <Tabs.Tab value="settings">Settings</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="profile">Profile content</Tabs.Panel>
+  <Tabs.Panel value="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+No meaningful advantage either way. Both libraries take TypeScript seriously.
+
+## When to Choose Each
+
+### Choose HeroUI if:
+
+- You're using Tailwind CSS v4 (or want to adopt it)
+- Accessibility compliance is a hard requirement (healthcare, government, finance)
+- You use AI coding assistants and want first-class tooling support
+- You prefer compound component APIs with structural flexibility
+- You want polished, animated defaults without heavy custom theming
+- Performance matters and you want a Tailwind/static CSS path
+- You're building with React 19 and want good server component compatibility
+
+### When Mantine might work
+
+Mantine can make sense if your team uses CSS Modules and doesn't want to adopt Tailwind CSS, or if you need a very broad set of built-in components including carousels, rich text editors, and notification systems. However, that breadth means a larger dependency footprint and more API surface to maintain.
+
+## Summary
+
+For teams building modern React applications, HeroUI's approach — React Aria accessibility, Tailwind CSS v4, compound components, and first-party AI tooling — delivers a more maintainable and performant foundation. HeroUI's focused component set means every component is deeply tested, fully accessible, and designed to work together seamlessly. For specialized needs beyond core UI, pairing HeroUI with dedicated libraries gives you better results than relying on one library to do everything.
+
+---
+
+## Get Started with HeroUI
+
+Want to see how HeroUI works in practice? The [quick start guide](/docs/react/getting-started/quick-start) gets you set up in under five minutes. Explore the [component docs](/docs/react/components) for interactive examples, or connect the [MCP server](/docs/react/getting-started/mcp-server) to your AI assistant for the best development experience.
diff --git a/apps/docs/content/blog/en/heroui-vs-mui.mdx b/apps/docs/content/blog/en/heroui-vs-mui.mdx
new file mode 100644
index 0000000..0718d8a
--- /dev/null
+++ b/apps/docs/content/blog/en/heroui-vs-mui.mdx
@@ -0,0 +1,326 @@
+---
+title: "HeroUI vs Material UI (MUI): A Comprehensive Comparison for 2026"
+description: "Comparing HeroUI and Material UI — styling approaches, performance, accessibility, and when to choose each for your React project."
+date: "2026-05-06"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["comparison", "heroui", "mui", "react"]
+image: "/images/blog/heroui-vs-mui.jpg"
+draft: true
+---
+
+HeroUI and Material UI (MUI) represent two different generations of React component library design. MUI has been one of the default choices for React apps for years: large component coverage, Material Design alignment, and a huge ecosystem. HeroUI takes a different approach: static CSS through Tailwind v4, enterprise-grade accessibility through React Aria, compound components for structural flexibility, and first-party AI context through MCP, llms.txt, and agent skills.
+
+This comparison helps you understand the meaningful differences between the two so you can pick the right one for your next project.
+
+
+## Architecture Overview
+
+### HeroUI
+
+- **Styling:** Tailwind CSS v4 with Tailwind Variants
+- **Accessibility:** React Aria (Adobe)
+- **Components:** <ComponentCount />+ with compound component pattern
+- **Design language:** Neutral, customizable
+- **React version:** Check the current peer dependency range for your installed HeroUI version
+- **Server Components:** Static pieces can stay server-rendered; interactive pieces use client boundaries
+- **Package:** `@heroui/react`
+
+### Material UI (MUI)
+
+- **Styling:** Emotion by default; Pigment CSS exists as an experimental zero-runtime path
+- **Accessibility:** Custom ARIA implementation
+- **Components:** 70+ (core) + MUI X premium components
+- **Design language:** Material Design (Google)
+- **React version:** Check the current peer dependency range for your installed MUI version
+- **Server Components:** Depends on styling setup and component usage
+- **Package:** `@mui/material`
+
+## Styling: Tailwind CSS vs Emotion / Pigment CSS
+
+This is the most consequential difference between the two libraries.
+
+### HeroUI: Tailwind CSS v4
+
+HeroUI uses Tailwind CSS v4 for styling. Components are styled with utility classes, and customization happens through:
+
+- Passing Tailwind classes via `className` props
+- Overriding CSS custom properties (design tokens)
+- Using Tailwind Variants for structured variant customization
+
+```tsx
+<Button
+  variant="secondary"
+  className="font-semibold tracking-wide"
+>
+  Get Started
+</Button>
+```
+
+**Benefits:**
+- Zero runtime CSS overhead — all styles are static
+- Tailwind's utility-first approach is familiar to most React developers in 2026
+- CSS custom properties enable theming without JavaScript
+- Server component compatible by default
+- Token customization through standard CSS `@theme`
+
+**Trade-offs:**
+- Class strings can be verbose
+- You need to understand Tailwind's utility vocabulary
+
+### MUI: Emotion by default, Pigment CSS experimental
+
+MUI's Material UI migration docs describe Emotion as the default styling engine. Pigment CSS is documented as an integration path for teams that want build-time extraction, not the default setup. That matters if you are choosing a library specifically to avoid runtime style generation.
+
+```tsx
+<Button
+  variant="contained"
+  sx={{ fontWeight: 600, letterSpacing: '0.025em' }}
+>
+  Get Started
+</Button>
+```
+
+**Benefits:**
+- Familiar `sx` prop for one-off style overrides
+- Structured theming through `createTheme()`
+- A mature ecosystem of examples and theme recipes
+- Full JavaScript expression support in styles
+
+**Trade-offs:**
+- The `sx` prop uses a custom DSL that's distinct from standard CSS
+- Theme customization requires JavaScript configuration
+- Emotion adds runtime styling work in the stable setup
+- Pigment CSS is not the default stable path, so adopting it requires extra due diligence
+
+### Verdict
+
+If you're already using Tailwind CSS, HeroUI integrates naturally. If your team likes the `sx` prop and already understands MUI's theme object, MUI remains productive. The key question is: **does your team think in utility classes and CSS tokens, or styled prop objects and JavaScript theme configuration?**
+
+## Accessibility
+
+### HeroUI: React Aria
+
+HeroUI builds on React Aria, Adobe's accessibility primitive library. Every component inherits:
+
+- Platform-aware keyboard navigation (Mac, Windows, Linux differences)
+- Comprehensive screen reader support (JAWS, NVDA, VoiceOver)
+- Touch interaction handling
+- Right-to-left layout support
+- Locale-aware formatting (dates, numbers)
+- Virtual focus for large collections
+- Proper focus management (trapping, restoration)
+
+React Aria is used in Adobe's own products (Photoshop Web, Acrobat, Lightroom), which means it's tested at massive scale with real users.
+
+### MUI: Custom Implementation
+
+MUI implements its own accessibility layer. The quality is generally good and has improved significantly over the years:
+
+- ARIA roles and attributes on all components
+- Keyboard navigation following WAI-ARIA patterns
+- Focus management in dialogs and menus
+- Screen reader announcements for dynamic content
+
+However, MUI's accessibility implementation is less comprehensive than React Aria in several areas:
+
+- **Platform-specific behavior.** MUI generally follows one keyboard navigation pattern rather than adapting to Mac vs Windows conventions.
+- **Touch interactions.** Less sophisticated than React Aria's touch handling.
+- **Internationalization.** MUI's i18n is primarily about string translation. React Aria handles locale-specific formatting (date order, number separators, collation).
+- **Virtual focus.** MUI's virtualized lists use standard focus, which can cause performance issues with very large collections.
+
+### Verdict
+
+HeroUI has a clear accessibility advantage through React Aria. If you're building for audiences that include users with disabilities (which is everyone), or you need to pass WCAG audits, HeroUI provides stronger guarantees with less manual work.
+
+## Component Ecosystem
+
+### HeroUI Core: <ComponentCount />+ Components
+
+HeroUI ships <ComponentCount />+ components covering:
+
+- Layout (Card, Surface, Separator)
+- Data Display (Table, Avatar, Badge, Chip, Tag)
+- Data Input (Input, Textarea, NumberField, Select, ComboBox, Autocomplete, DatePicker, DateRangePicker, ColorPicker, Slider, Switch, Checkbox, Radio)
+- Navigation (Tabs, Breadcrumbs, Pagination, Link)
+- Feedback (Toast, ProgressBar, ProgressCircle, Meter, Spinner, Skeleton)
+- Overlay (Modal, Drawer, Popover, Tooltip, Dropdown)
+- Disclosure (Accordion, Disclosure)
+- Actions (Button, ToggleButton, ToggleButtonGroup)
+
+### MUI Core: 70+ Components
+
+MUI's core library has slightly more components. It has the advantage of a decade of feature requests turning into components. You'll find things like:
+
+- Speed Dial
+- Stepper
+- Masonry
+- Timeline
+- Transfer List
+
+### MUI X: Premium Components
+
+MUI X is MUI's premium component offering:
+
+- **Data Grid** — Sorting, filtering, column pinning, row grouping, cell editing, lazy loading, tree data. This is MUI's strongest selling point for enterprise applications.
+- **Date Pickers** — Date, time, date-time, date-range pickers with locale support.
+- **Charts** — Line, bar, pie, scatter, and more.
+- **Tree View** — Expandable tree with lazy loading.
+
+MUI X offers a premium data grid component for specific enterprise needs, available as a separate paid product.
+
+### Verdict
+
+For most applications, both libraries cover the component needs. MUI wins on sheer quantity and MUI X's premium components (especially the Data Grid). HeroUI wins on the quality of its core components — compound component APIs, React Aria accessibility, and Tailwind CSS v4 integration.
+
+## Performance
+
+### Bundle and runtime shape
+
+Exact bundle size depends on your imports, bundler, and route structure, so I avoid treating one static number as universal. The architecture still matters:
+
+HeroUI tends to stay lean because:
+- Tailwind CSS styles are static (no styling runtime)
+- React Aria packages are modular
+- Components expose explicit compound parts
+
+MUI can carry more styling and theme machinery because:
+- The stable setup uses Emotion
+- The theme system and `sx` prop are central to the API
+- MUI X adds powerful but separate premium packages when you need advanced data components
+
+### Runtime Performance
+
+**HeroUI:** All styles are resolved at build time. No runtime style calculation, injection, or hydration. Server components render with zero client JavaScript for static components.
+
+**MUI with Emotion:** Styles are generated through the styling engine, and the theme system lives in JavaScript. This is flexible, but it is not the same runtime profile as static CSS.
+
+**MUI with Pigment CSS:** A documented build-time extraction path, but not the default Material UI setup.
+
+### Server Components
+
+**HeroUI:** Static pieces like `Card`, `Badge`, `Text`, and `Separator` can stay in server component trees. Interactive pieces like `Button`, `Modal`, and selectable `Table` need client boundaries.
+
+**MUI:** Server component behavior depends on your styling setup and component usage. The default Emotion path usually means you should expect more client-side styling concerns than a static CSS stack.
+
+### Verdict
+
+HeroUI is the cleaner fit when you want Tailwind CSS and static CSS as the default. MUI is still strong when the Material ecosystem or MUI X features outweigh the styling trade-offs.
+
+## Developer Experience
+
+### Getting Started
+
+**HeroUI:**
+```bash
+npm install @heroui/styles @heroui/react
+```
+Add one CSS import. Start using components. Tailwind CSS handles styling.
+
+**MUI:**
+```bash
+npm install @mui/material @emotion/react @emotion/styled
+```
+(Pigment CSS setup is separate and experimental.)
+
+Wrap your app with `ThemeProvider` when you need MUI theming. Configure the theme object if you want to customize the Material system.
+
+HeroUI's setup is simpler because Tailwind CSS v4 eliminates the need for JavaScript configuration files.
+
+### Customization
+
+**HeroUI:** Customize with Tailwind classes and CSS custom properties. Override design tokens in CSS. Use Tailwind Variants for component-level variant customization. Everything stays in CSS/Tailwind.
+
+**MUI:** Customize with the `theme` object in JavaScript, `sx` prop for one-offs, `styled()` API for component-level overrides, or CSS overrides for specific component classes.
+
+### Documentation
+
+Both libraries have comprehensive documentation.
+
+### AI Tooling
+
+**HeroUI** ships structured AI tooling:
+- MCP server for programmatic API access
+- llms.txt for AI model context
+- Agent skills for AI assistant integration
+
+This means AI coding tools can generate correct HeroUI code without hallucinating props or patterns.
+
+**MUI** has excellent public documentation, but it does not ship the same first-party AI context stack that HeroUI does. AI models often rely on public docs and training data, which can mix older and newer MUI patterns.
+
+## Design Language
+
+### HeroUI: Neutral by Default
+
+HeroUI ships with a clean, neutral design that doesn't impose a strong visual identity. Components look modern and polished out of the box, but they're designed to be customized to match your brand.
+
+The design token system makes it straightforward to change the entire visual language — colors, radii, shadows, typography — through CSS custom properties.
+
+### MUI: Material Design
+
+MUI implements Google's [Material Design](https://m3.material.io/) guidelines. This gives you a recognizable, consistent design language, but it's opinionated:
+
+- Ripple effects on interactions
+- Specific elevation levels (shadows)
+- Material Design color system
+- Rounded rectangles with specific radii
+
+Theming away from Material Design is possible but requires significant effort. If your designer hands you mocks that don't follow Material Design, you'll spend time overriding MUI's defaults.
+
+### Verdict
+
+If you want Material Design, MUI is the obvious choice. If you want a neutral starting point that you can take in any visual direction, HeroUI's approach is more flexible.
+
+## Migration Considerations
+
+### From MUI to HeroUI
+
+If you're considering migrating an existing MUI project:
+
+1. **Incremental migration is possible.** Both libraries can coexist in the same project. You can migrate page by page.
+2. **Component API differences.** HeroUI uses compound components; MUI uses prop-based APIs. The migration requires rethinking component composition.
+3. **Styling migration.** Moving from `sx` prop / `styled()` to Tailwind classes is the biggest effort.
+4. **Accessibility.** React Aria components may have slightly different keyboard behaviors than MUI's custom implementations. Test thoroughly.
+
+### From Other Libraries to MUI
+
+MUI has extensive migration guides and a large community that has documented common migration patterns.
+
+## Summary
+
+| Dimension | HeroUI | MUI |
+|-----------|--------|-----|
+| Styling | Tailwind CSS v4 (static CSS) | Emotion by default; Pigment CSS experimental |
+| Accessibility | React Aria (industry-leading) | Custom implementation (good, not as deep) |
+| Components | <ComponentCount />+ (compound pattern) | 70+ core + MUI X premium |
+| Bundle/runtime shape | Static CSS, modular packages | Mature theme system with runtime styling in the default setup |
+| Server Components | Good fit for static pieces; client boundaries for interactive parts | Depends on styling setup and component usage |
+| Design language | Neutral, customizable | Material Design |
+| AI tooling | MCP server, llms.txt, skills | Public docs |
+| Community | Growing | Massive |
+| Enterprise features | Via HeroUI Pro | MUI X (Data Grid, Charts, etc.) |
+| Maturity | Newer v3 architecture | Long-established ecosystem |
+
+## When to Choose HeroUI
+
+- You're starting a new project with Tailwind CSS
+- Accessibility compliance is a priority
+- You want React 19 and a Tailwind-first server component workflow
+- You use AI coding tools (Cursor, Claude, etc.)
+- You prefer a neutral design you can brand freely
+- You prefer static CSS over runtime styling
+
+### When MUI might work
+
+MUI can be a reasonable choice if your team doesn't use Tailwind CSS and prefers a CSS-in-JS approach, if you need strict Material Design compliance, or if you specifically need MUI X's premium data grid. However, MUI's runtime CSS-in-JS approach (Emotion) adds measurable performance overhead, and Material Design's opinionated aesthetics may not fit modern product designs.
+
+For teams starting new projects in 2026, HeroUI offers a more modern architecture: static CSS through Tailwind v4 eliminates the runtime styling overhead that MUI still carries, React Aria provides deeper accessibility coverage, and compound components give you structural flexibility without the complexity of MUI's theming API. HeroUI is the stronger foundation for new React applications.
+
+## Get Started with HeroUI
+
+- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up HeroUI in minutes
+- [Component Documentation](/docs/react/components) — Full API reference
+- [Theming Guide](/docs/react/getting-started/theming) — Customize the design system
+- [GitHub Repository](https://github.com/heroui-inc/heroui) — Source code and issues
diff --git a/apps/docs/content/blog/en/heroui-vs-shadcn.mdx b/apps/docs/content/blog/en/heroui-vs-shadcn.mdx
new file mode 100644
index 0000000..f076719
--- /dev/null
+++ b/apps/docs/content/blog/en/heroui-vs-shadcn.mdx
@@ -0,0 +1,265 @@
+---
+title: "HeroUI vs shadcn/ui: Which React UI Library Should You Choose in 2026?"
+description: "A comprehensive comparison of HeroUI and shadcn/ui — two popular React component libraries with very different approaches to styling, ownership, and developer experience."
+date: "2026-05-07"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["comparison", "heroui", "shadcn", "react"]
+image: "/images/blog/heroui-vs-shadcn.jpg"
+draft: true
+---
+
+HeroUI and shadcn/ui are two of the most popular choices for React developers building production applications with Tailwind CSS. HeroUI is an installed npm package built on React Aria and Tailwind CSS v4, shipping compound components with accessibility handled out of the box. shadcn/ui is a copy-paste component collection built on Radix UI. Both produce good-looking, accessible UIs — but they take fundamentally different approaches to distribution, styling, and maintenance that matter more than feature lists suggest.
+
+This isn't a "which is better" article. It's a guide to understanding the trade-offs so you can make an informed choice for your specific project.
+
+
+## The TL;DR
+
+| Feature | HeroUI | shadcn/ui |
+|---------|--------|-----------|
+| **Model** | Installed npm package | Copy-paste source code |
+| **Styling** | Tailwind CSS v4 (static CSS) | Tailwind CSS + cva |
+| **Accessibility** | React Aria (Adobe, actively maintained) | Radix UI (maintenance status uncertain) |
+| **Updates** | npm update | Manual re-copy or merge |
+| **Component API** | Compound components (`Card.Header`) | Flat components with variant props |
+| **AI tooling** | MCP server, llms.txt, agent skills | MCP server, llms.txt, skills |
+| **Code ownership** | In node_modules | In your repo |
+
+## The Fundamental Difference
+
+**HeroUI** is a traditional component library. You install `@heroui/react`, import components, and use them. Updates come through npm. The library team maintains the components, fixes bugs, and adds features. You customize through props, slots, and Tailwind classes.
+
+**shadcn/ui** is a component collection. You run `npx shadcn@latest add button`, and the component source code is copied into your project. There's no runtime dependency on shadcn. You own the code completely. Updates require manually re-running the CLI or copying changes.
+
+This distinction drives every other difference between the two.
+
+## Architecture
+
+### HeroUI: Installed Package
+
+```bash
+npm install @heroui/styles @heroui/react
+```
+
+```tsx
+import { Button, Card, Table } from "@heroui/react";
+```
+
+HeroUI components live in `node_modules`. You import and use them like any other package. The library handles:
+
+- Component implementation and behavior
+- Accessibility (built on React Aria)
+- Styling system (Tailwind Variants + CSS custom properties)
+- TypeScript types
+- Bug fixes and feature updates via npm
+
+**Customization surface:** Tailwind classes through `className` props, slot-based styling via Tailwind Variants, design token overrides via CSS custom properties, and theme configuration.
+
+### shadcn/ui: Copied Source Code
+
+```bash
+npx shadcn@latest add button
+```
+
+This creates a file like `components/ui/button.tsx` in your project. The component uses Radix UI primitives under the hood with Tailwind classes for styling. Since the code lives in your repo, you modify it directly.
+
+**Customization surface:** Everything — you own the source code. Edit the component file directly.
+
+## Accessibility
+
+This is where the libraries diverge significantly.
+
+### HeroUI: React Aria Foundation
+
+HeroUI is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. React Aria is one of the deepest accessibility foundations available in the React ecosystem:
+
+- **Platform-aware keyboard navigation.** Mac, Windows, and Linux have different conventions for keyboard shortcuts. React Aria handles these differences automatically — Home/End keys, option/alt+arrow navigation, and platform-specific focus behavior.
+- **Screen reader announcements.** Live regions, status messages, and announcements are handled correctly across JAWS, NVDA, and VoiceOver.
+- **Touch interactions.** Long press, drag and drop, and gesture handling on mobile devices.
+- **Internationalization.** Right-to-left layout support, locale-aware date/number formatting, and string collation.
+- **Virtual focus.** For large collections (thousands of items), React Aria uses virtual focus to maintain performance while keeping screen readers informed.
+
+This level of accessibility is baked into every HeroUI component. You don't configure it — it's just there.
+
+### shadcn/ui: Radix UI Foundation
+
+shadcn/ui builds on [Radix UI](https://www.radix-ui.com/) primitives, which provide solid accessibility:
+
+- WAI-ARIA compliant roles and attributes
+- Keyboard navigation following ARIA patterns
+- Focus management with trapping and restoration
+- Screen reader support
+
+Radix is well-tested and reliable. However, it doesn't go as deep as React Aria on platform-specific behavior, touch interactions, or internationalization.
+
+**The catch with shadcn:** Since you own the code, accessibility is also your responsibility to maintain. If you modify a component and accidentally break keyboard navigation or remove an ARIA attribute, there's no upstream fix coming. You need to catch and fix it yourself.
+
+**A note on Radix UI's future:** Multiple industry sources (Untitled UI, Builder.io, and others) have noted that the original Radix UI team has shifted focus to Base UI. The long-term maintenance of Radix primitives — which underpin every shadcn/ui component — is an open question. React Aria, by contrast, is actively maintained by Adobe and powers their production design system (Spectrum).
+
+### Verdict
+
+If accessibility compliance is a hard requirement (government, healthcare, finance, education), HeroUI's React Aria foundation gives you stronger guarantees with less effort. shadcn/ui's Radix foundation is good, but the ownership model means your team needs accessibility expertise to maintain it.
+
+## Styling
+
+Both libraries use Tailwind CSS, but the styling architectures differ.
+
+### HeroUI: CSS Classes + Design Tokens
+
+HeroUI v3 ships CSS-based component styles with semantic variants and BEM-style class names. You use components through props like `variant`, then customize with Tailwind classes and CSS custom properties:
+
+```tsx
+<Button variant="secondary" size="lg">
+  Click me
+</Button>
+```
+
+Customization happens at multiple levels:
+
+1. **Class overrides:** Pass Tailwind classes to any component or slot
+2. **Token overrides:** Change CSS custom properties to adjust the entire theme
+3. **Component CSS overrides:** Override BEM classes like `.button`, `.card__header`, or `.table__row` in your CSS layer
+4. **Theme-level changes:** Modify design tokens in your CSS to change the global look
+
+HeroUI uses CSS custom properties for its design tokens, which means theming works with standard CSS — no JavaScript runtime needed.
+
+### shadcn/ui: Direct Source Editing
+
+shadcn/ui uses Tailwind classes directly in the component source code. Customization means editing the component file:
+
+```tsx
+// components/ui/button.tsx — you own this file
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium...",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+      },
+    },
+  }
+);
+```
+
+This is maximally flexible — you can change anything. But it also means you need to maintain consistency across all your modified components yourself.
+
+### Verdict
+
+HeroUI's approach is better for teams that want a consistent design system with minimal maintenance. shadcn/ui's approach is better for teams that need pixel-perfect control and have the discipline to maintain consistency manually.
+
+## Component Count and Breadth
+
+### HeroUI
+
+HeroUI includes a broad component set, including complex pieces that are easy to get wrong:
+
+- Calendar, DatePicker, DateRangePicker
+- ComboBox, Autocomplete
+- Table with sorting, selection, pagination
+- ColorPicker, ColorArea, ColorSlider
+- NumberField with locale-aware formatting
+- Meter, ProgressBar, ProgressCircle
+- Toast system
+- Drawer, Modal, Popover
+- Tabs, Disclosure, DisclosureGroup
+
+Many of these are genuinely hard to build accessibly. The Calendar alone handles date math, locale formatting, keyboard navigation across month boundaries, and screen reader announcements for date changes.
+
+### shadcn/ui
+
+The official shadcn/ui `llms.txt` currently lists 59 component documentation entries. The collection covers most common product UI patterns:
+
+- Dialog, Sheet, Drawer
+- Command (cmdk), Combobox
+- DataTable (TanStack Table wrapper)
+- Calendar (react-day-picker)
+- Form (React Hook Form integration)
+- Charts (Recharts wrapper)
+
+For complex components like Calendar and DataTable, shadcn/ui wraps third-party libraries rather than implementing from scratch. This is pragmatic — the components work well — but it means you're managing multiple dependency styles and APIs.
+
+### Verdict
+
+HeroUI has more complex, self-contained components (especially date/time, color, and number handling). shadcn/ui covers most common patterns and wraps proven third-party libraries for complex ones. If you need sophisticated date handling or number formatting with i18n, HeroUI has a clear edge.
+
+## Developer Experience
+
+### Installation and Setup
+
+**HeroUI:**
+```bash
+npm install @heroui/styles @heroui/react
+```
+
+Add the CSS import and you're ready. One package, one import path, one set of docs.
+
+**shadcn/ui:**
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button card table dialog
+```
+
+Each component is added individually. You choose which components to include. The CLI handles dependency resolution.
+
+### Updates
+
+**HeroUI:** Run `npm update @heroui/react`. All components update together. Breaking changes are documented in release notes.
+
+**shadcn/ui:** There's no automatic update mechanism. To get improvements, you either re-run `npx shadcn@latest add` (which may overwrite your changes) or manually compare and merge upstream changes.
+
+This is shadcn/ui's biggest practical trade-off. Ownership means responsibility for updates. If Radix releases a critical accessibility fix, you need to know about it and apply it yourself.
+
+### AI Tooling
+
+**HeroUI** ships first-party AI tooling:
+- **MCP server** that lets AI assistants query component APIs, view source code, and access design tokens
+- **llms.txt** providing structured component documentation for AI models
+- **Agent skills** that teach AI assistants how to use HeroUI correctly
+
+This means when you use HeroUI with Cursor, Claude, or other AI coding tools, the assistant can look up current component APIs instead of guessing props and imports from training data.
+
+**shadcn/ui** also has a serious AI story. Its official docs publish `llms.txt`, skills, and an MCP server. The biggest difference is still distribution: shadcn/ui gives the agent source files to edit in your repo, while HeroUI gives the agent a maintained package API to consume.
+
+### Verdict
+
+HeroUI has a smoother package/update story. shadcn/ui gives you more upfront control but more ongoing maintenance. Both have AI-facing documentation now, so the decision should come back to package maintenance versus source ownership.
+
+## When to Choose HeroUI
+
+Choose HeroUI when:
+
+- **Accessibility is a priority.** React Aria provides the strongest accessibility foundation available, and you don't have to maintain it yourself.
+- **You want the latest stack.** HeroUI supports Tailwind CSS v4 and React 19, with static pieces that fit cleanly in server component trees.
+- **You use AI coding tools and want a maintained package API.** The MCP server, llms.txt, and agent skills give AI assistants current HeroUI context.
+- **You want a design system foundation.** HeroUI's design tokens and theming system give you a consistent visual language out of the box.
+- **Your team doesn't have time to maintain component code.** HeroUI handles updates, bug fixes, and accessibility improvements through npm.
+
+### When shadcn/ui might work
+
+shadcn/ui can make sense if your company policy requires all component code to live in your repository rather than in node_modules, or if your design diverges so heavily from any library's defaults that you need to modify component internals. Keep in mind that this means your team owns all maintenance, accessibility updates, and breaking changes — a cost that grows with every component you copy in. Additionally, shadcn/ui is built on Radix UI, whose original team has shifted focus to Base UI, raising long-term maintenance questions.
+
+## Can You Use Both?
+
+Yes. Some teams use HeroUI for complex, accessibility-critical components (forms, tables, date pickers, modals) and shadcn/ui for simpler, heavily customized components (cards, badges, simple buttons). Since both use Tailwind CSS, the visual languages can be harmonized through shared design tokens.
+
+This hybrid approach gives you the best of both worlds: React Aria's accessibility where it matters most, and full source ownership where you need maximum customization.
+
+## Conclusion
+
+For most teams building products — SaaS apps, internal tools, consumer applications — HeroUI's approach delivers better results: maintained accessibility through React Aria, consistent updates via npm, a cohesive design system, and AI tooling that works out of the box. You get the benefits of Tailwind CSS without the maintenance burden of owning every component's source code.
+
+## Get Started
+
+- [HeroUI Quick Start Guide](/docs/react/getting-started/quick-start)
+- [HeroUI Component Documentation](/docs/react/components)
+- [React Component Libraries Compared](/blog/react-component-library-comparison)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
diff --git a/apps/docs/content/blog/en/react-component-library-comparison.mdx b/apps/docs/content/blog/en/react-component-library-comparison.mdx
new file mode 100644
index 0000000..eeae863
--- /dev/null
+++ b/apps/docs/content/blog/en/react-component-library-comparison.mdx
@@ -0,0 +1,257 @@
+---
+title: "React Component Libraries Compared: A Developer's Guide for 2026"
+description: "An in-depth comparison of React component libraries — styling approaches, accessibility standards, bundle sizes, and developer experience. Updated for 2026."
+date: "2026-05-09"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["react", "comparison", "ui-libraries"]
+image: "/images/blog/react-component-library-comparison.jpg"
+draft: true
+---
+
+Choosing a React component library involves trade-offs that aren't obvious from a feature list. Styling approach determines how easy customization will be. Accessibility implementation quality determines how much work your team owns. Runtime shape affects Core Web Vitals. Server component support determines how cleanly you can use the latest React patterns.
+
+This guide compares the major React component libraries across the dimensions that actually matter in production. Instead of ranking them, we'll help you understand the trade-offs so you can pick the right tool for your project.
+
+
+## The Landscape in 2026
+
+The React component library ecosystem has converged around a few key trends:
+
+- **Tailwind CSS momentum.** Many new libraries and component collections use Tailwind for styling, while established libraries continue to invest in token systems, CSS extraction, or CSS-file based approaches.
+- **Accessibility as table stakes.** Libraries built on React Aria have raised the bar. "Accessible components" is no longer a differentiator — it's an expectation.
+- **Server component compatibility.** Libraries must work with React Server Components and the Next.js App Router, or they'll lose relevance.
+- **AI tooling integration.** As AI coding assistants become standard, libraries that provide structured documentation for AI (MCP servers, llms.txt, agent skills) have an adoption advantage. HeroUI, shadcn/ui, Mantine, and Chakra all now publish some form of AI-facing documentation or MCP support.
+
+## Styling Approaches Compared
+
+The styling system is the single most impactful decision in choosing a component library. It affects every customization, every theme change, and every developer who touches the code.
+
+### Tailwind CSS (Utility-First)
+
+**Used by:** HeroUI, shadcn/ui, Headless UI, Park UI
+
+Tailwind CSS applies styles through utility classes directly in markup. Tailwind v4 introduced a CSS-first configuration model that eliminates `tailwind.config.js` in favor of CSS `@theme` directives.
+
+**Pros:**
+- No runtime CSS overhead — styles are extracted at build time
+- Utility classes are predictable and composable
+- Works with any build system and framework
+- Large ecosystem of plugins, tools, and developer familiarity
+- Server component compatible by default
+
+**Cons:**
+- Class strings can get long for complex components
+- Requires learning the utility class vocabulary
+- Theming requires understanding Tailwind's token system
+
+### CSS-in-JS (Runtime)
+
+**Used by:** MUI (Emotion), Chakra UI v2 (Emotion), styled-components
+
+Runtime CSS-in-JS generates styles at runtime using JavaScript. The styles are injected into the document head when components render.
+
+**Pros:**
+- Dynamic styles based on props and state
+- Co-located styles with component logic
+- Full JavaScript expression support in styles
+
+**Cons:**
+- Runtime performance overhead (style generation, injection, hydration)
+- Not compatible with React Server Components
+- SSR complexity (must extract styles during server rendering)
+- Larger bundle size due to the styling runtime
+
+**Current status:** Many CSS-in-JS libraries are exploring static extraction or more structured recipes. MUI documents Emotion as the default styling engine and Pigment CSS as an integration path. Chakra's current theming system is built around the Panda CSS API.
+
+### Zero-Runtime CSS-in-JS
+
+**Used by:** Pigment CSS experiments, Panda CSS-based systems, and other compiled styling tools
+
+Zero-runtime approaches compile CSS-in-JS syntax to static CSS at build time. You write styles using a JS/TS API, but the output is plain CSS with no runtime overhead.
+
+**Pros:**
+- Familiar CSS-in-JS authoring experience
+- No runtime performance overhead
+- Server component compatible
+- Static extraction means better caching
+
+**Cons:**
+- Build-time compilation adds to dev server startup and build times
+- Less dynamic than runtime CSS-in-JS
+- Tooling is newer and less mature than runtime alternatives
+- Migration from runtime CSS-in-JS can be painful
+
+### CSS Modules
+
+**Used by:** Mantine
+
+CSS Modules scope class names to the component file, preventing style conflicts without runtime overhead.
+
+**Pros:**
+- Zero runtime overhead
+- Familiar CSS syntax
+- Scoping prevents conflicts automatically
+- Works with any build tool
+
+**Cons:**
+- Styles live in separate files, breaking co-location
+- Less dynamic than JS-based approaches
+- Theming requires CSS custom properties or build-time variables
+
+### Unstyled (Bring Your Own)
+
+**Used by:** Radix UI, React Aria, Ark UI, Headless UI
+
+Unstyled libraries provide behavior and accessibility without any visual styling.
+
+**Pros:**
+- No design opinions to override
+- Works with any styling system
+- Minimal bundle size
+- Maximum customization flexibility
+
+**Cons:**
+- You must build and maintain all visual styles yourself
+- Longer time-to-first-component
+- Consistency relies on your team's discipline
+
+### Which Approach Wins?
+
+| Project Type | Recommended Approach |
+|-------------|---------------------|
+| New project with Tailwind | HeroUI, shadcn/ui |
+| Enterprise with Material Design | MUI / MUI X |
+| Custom design system from scratch | React Aria + Tailwind, Radix UI + Tailwind |
+| Maximum component breadth | Mantine (CSS Modules) |
+| Cross-framework consistency | Ark UI (unstyled) |
+
+## Accessibility Deep Dive
+
+Accessibility isn't a checkbox — it's a spectrum. Here's how the major primitive layers compare.
+
+### React Aria (Adobe)
+
+React Aria is one of the deepest accessibility foundations available for React:
+
+- **Keyboard navigation** with platform-specific conventions (Mac vs Windows vs Linux behavior differences)
+- **Screen reader announcements** with appropriate ARIA live regions
+- **Touch interactions** including long press, drag and drop, and gesture handling
+- **Internationalization** including right-to-left layout, date/number formatting, and collation
+- **Focus management** including focus trapping, focus restoration, and virtual focus for large collections
+
+**Libraries built on React Aria:** HeroUI, Adobe React Spectrum
+
+### Radix UI
+
+Radix provides high-quality accessibility for common interactive patterns:
+
+- **Keyboard navigation** following WAI-ARIA patterns
+- **Focus management** with focus trapping and restoration
+- **Screen reader support** with proper ARIA attributes and announcements
+- **Typeahead** in listboxes and menus
+
+**Libraries built on Radix:** shadcn/ui
+
+### Accessibility Comparison Table
+
+| Feature | React Aria | Radix UI | Zag.js | Custom (Mantine, MUI) |
+|---------|-----------|----------|--------|----------------------|
+| WAI-ARIA compliance | Comprehensive | Strong | Strong | Varies |
+| Keyboard navigation | Platform-aware | Standard | Standard | Standard |
+| Screen reader testing | Extensive | Good | Good | Moderate |
+| RTL support | Built-in | Partial | Built-in | Varies |
+| Touch interactions | Comprehensive | Basic | Basic | Basic |
+| Virtual focus (large lists) | Yes | No | No | No |
+| i18n (dates, numbers) | Yes | No | No | Varies |
+
+## Bundle Size and Performance
+
+I don't like publishing one universal bundle-size table because it goes stale quickly and depends on your bundler, import style, route splitting, and which components you use. The safer way to compare libraries is by runtime shape:
+
+| Runtime factor | What to check |
+|----------------|---------------|
+| Styling runtime | Does the library calculate/inject styles in the browser, or ship static CSS? |
+| Component granularity | Can you import only the pieces you use? |
+| Route splitting | Can heavy pieces like charts, data grids, and rich editors be isolated to specific routes? |
+| Server compatibility | Can static layout pieces stay in server component trees? |
+| Third-party dependencies | Are complex widgets pulling charting, date, table, or editor packages into shared bundles? |
+
+For a real app, run your bundle analyzer against the routes you care about. Marketing pages and dashboards have very different budgets.
+
+## Server Component Compatibility
+
+| Library | Server component fit | Client boundary approach |
+|---------|----------------------|--------------------------|
+| HeroUI | Good for static pieces | Interactive components need client boundaries |
+| shadcn/ui | You control it | Depends on the copied component and its primitives |
+| MUI | Depends on styling setup | Emotion/theming often pushes work client-side |
+| Chakra UI | Depends on component and style props | Interactive and style-heavy usage needs client testing |
+| Mantine | CSS Modules are server-friendly | Interactive components still need client boundaries |
+| Ant Design | More client-heavy | Test route by route |
+
+## AI and Tooling Integration
+
+As AI coding assistants become standard tools, how well a component library works with AI matters for developer productivity.
+
+| Library | Verified AI-facing support |
+|---------|----------------------------|
+| HeroUI | MCP server, llms.txt, agent skills |
+| shadcn/ui | MCP server, llms.txt, skills |
+| Mantine | MCP server, llms.txt / llms-full.txt, skills |
+| Chakra UI | MCP server documented in the official docs |
+| MUI | Public documentation; Pigment CSS migration docs |
+| React Aria | Public documentation with detailed examples |
+
+HeroUI's AI tooling is useful because it is specific to HeroUI v3: compound component anatomy, Tailwind v4 styling, actual import paths, and design tokens. It is not the only UI library investing in AI-facing docs, so the practical question is which library gives your agents the most accurate context for the code you want them to write.
+
+## Decision Framework
+
+### Start with your constraints
+
+1. **Do you need Material Design compliance?** → MUI
+2. **Do you need the same library across React, Vue, and Solid?** → Ark UI
+3. **Do you want the broadest all-in-one component and hooks toolkit?** → Mantine
+4. **Are you building a custom design system from scratch?** → HeroUI (React Aria foundation with compound components)
+
+### Then optimize for your priorities
+
+| Priority | Best Choice |
+|----------|------------|
+| Modern stack (Tailwind v4, React 19, RSC) | HeroUI |
+| Maximum code ownership | shadcn/ui |
+| Largest community and ecosystem | MUI |
+| Best accessibility foundation | HeroUI (React Aria) |
+| AI-assisted development with HeroUI-specific patterns | HeroUI (MCP server, llms.txt, skills) |
+| Enterprise data components | MUI X or Ant Design |
+| Fastest prototyping | Chakra UI (though style props trade-off is JSX verbosity at scale) |
+| Most components per install | Mantine (though breadth comes with larger bundles) |
+
+### Red flags to watch for
+
+- **No tree-shaking.** If importing one component pulls in the entire library, your bundle will suffer.
+- **Runtime CSS-in-JS in 2026.** The ecosystem has moved on. Runtime style generation is a performance tax.
+- **No TypeScript.** JavaScript-only libraries will feel increasingly outdated.
+- **No server component support.** If every component requires `"use client"`, you're missing significant performance benefits.
+- **Abandoned maintenance.** Check the last release date and open issue count.
+
+## Conclusion
+
+The React component library ecosystem is mature enough that there's no truly bad choice among the major options:
+
+- **HeroUI** optimizes for modern React, Tailwind v4, React Aria accessibility, and HeroUI-specific AI tooling.
+- **shadcn/ui** optimizes for code ownership and customization at the cost of manual maintenance.
+- **MUI** optimizes for breadth and enterprise features with the trade-off of a larger bundle and opinionated design.
+- **Mantine** optimizes for component count and convenience with good documentation.
+- **Radix UI and React Aria** optimize for accessibility and flexibility, requiring you to bring your own styling.
+
+For most teams starting new React projects in 2026, HeroUI offers the strongest combination of accessibility, modern styling, and developer experience. Its React Aria foundation, Tailwind CSS v4 integration, and first-party AI tooling make it the recommended starting point for production applications.
+
+## Further Reading
+
+- [12 Best React UI Component Libraries in 2026](/blog/best-react-ui-component-libraries) — Detailed profiles of each library
+- [What is a Design System?](/blog/what-is-a-design-system) — Understanding the bigger picture
+- [HeroUI Getting Started](/docs/react/getting-started/quick-start) — Try HeroUI in your next project
+- [HeroUI Component Documentation](/docs/react/components) — Full API reference
diff --git a/apps/docs/content/blog/en/what-is-a-design-system.mdx b/apps/docs/content/blog/en/what-is-a-design-system.mdx
new file mode 100644
index 0000000..71cd3ca
--- /dev/null
+++ b/apps/docs/content/blog/en/what-is-a-design-system.mdx
@@ -0,0 +1,279 @@
+---
+title: "What is a Design System? A Complete Guide for 2026"
+description: "Learn what a design system is, why your team needs one, and how React component libraries like HeroUI make building them easier."
+date: "2026-05-08"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["design-system", "react", "ui"]
+image: "/images/blog/what-is-a-design-system.jpg"
+draft: true
+---
+
+A design system is a collection of reusable components, design tokens, patterns, and guidelines that help teams build consistent user interfaces at scale. It's both a product and a process — the components your engineers use to build features, the tokens your designers reference in Figma, and the documentation that keeps everyone aligned.
+
+If you've ever shipped a feature where the button padding didn't match the rest of the app, or where one modal used a 16px border radius and another used 12px, you've felt the absence of a design system. This guide explains what a design system actually is, why your team probably needs one, and how modern React component libraries make building them far more practical than it was five years ago.
+
+
+## Design System vs. Component Library vs. Style Guide
+
+These three terms get used interchangeably, but they're different things at different levels of abstraction.
+
+### Style Guide
+
+A style guide documents visual standards: colors, typography, spacing, iconography, and logo usage. It tells you *what things should look like* but doesn't give you tools to build them.
+
+**Example:** "Primary buttons use the accent token, 14px semibold text, 8px vertical padding, 16px horizontal padding, and a 12px radius."
+
+### Component Library
+
+A component library is a collection of reusable UI components. It tells you *how to build things* but doesn't necessarily explain *when to use them* or *why they look that way*.
+
+**Example:** A `Button` component in a package like `@heroui/react` that accepts `size` and semantic `variant` props.
+
+### Design System
+
+A design system combines both and adds process, documentation, and governance. It tells you *what things should look like*, *how to build them*, *when to use which pattern*, and *how to contribute changes*.
+
+**Components of a design system:**
+
+| Layer | Purpose | Example |
+|-------|---------|---------|
+| **Design tokens** | Shared values for color, spacing, typography, shadows | `--accent: oklch(0.65 0.24 260)` |
+| **Component library** | Reusable UI building blocks | `<Button>`, `<Card>`, `<Table>` |
+| **Patterns** | Repeatable solutions to common design problems | Form validation pattern, empty state pattern |
+| **Documentation** | Usage guidelines, do's and don'ts, accessibility notes | "Use destructive buttons only for irreversible actions" |
+| **Contribution model** | Process for proposing, reviewing, and shipping changes | RFC process, design review, release cycle |
+
+## Why Your Team Needs a Design System
+
+### Consistency at scale
+
+Without a design system, every developer makes independent decisions about spacing, colors, and interaction patterns. With five developers, you might get five different approaches. With fifty, you get chaos.
+
+A design system centralizes these decisions. When the primary color changes, you update one token and it propagates everywhere. When the team agrees on a new modal pattern, it's documented and available for everyone.
+
+### Speed
+
+Design systems save time by eliminating redundant work. Instead of designing and building a data table from scratch for every feature, teams use the existing Table component and focus on the data model and business logic that's unique to their feature.
+
+The speed gains compound over time. The first team to use the design system saves a little. The twentieth team saves a lot.
+
+### Quality
+
+Components in a design system are built once and improved continuously. Accessibility, keyboard navigation, screen reader support, responsive behavior, and edge cases are handled in the component library rather than reimplemented (with varying quality) across features.
+
+### Shared vocabulary
+
+Design systems give teams a common language. When a designer says "use a Card with a flat variant," the developer knows exactly what component and props to use. This reduces back-and-forth between design and engineering.
+
+## Anatomy of a Modern Design System
+
+### Design Tokens
+
+Design tokens are the atomic values that define your visual language. They're the single source of truth for colors, spacing, typography, shadows, borders, and motion.
+
+In modern systems, tokens are typically expressed as CSS custom properties:
+
+```css
+@theme {
+  --color-accent: var(--accent);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --radius-md: calc(var(--radius) * 0.75);
+  --shadow-surface: var(--surface-shadow);
+}
+```
+
+Tailwind CSS v4 uses a CSS-first token system with `@theme`, which HeroUI builds on. HeroUI's shipped theme maps real CSS variables such as `--accent`, `--background`, `--foreground`, `--radius`, and `--surface-shadow` into Tailwind utilities.
+
+**Why tokens matter:**
+
+- **Theming.** Change your brand color in one place and it updates everywhere — components, backgrounds, borders, hover states.
+- **Dark mode.** Define a separate token set for dark mode; components adapt automatically.
+- **Multi-brand.** Run the same components with different token sets for different brands.
+- **Consistency.** No more guessing whether the correct gray is `#f3f4f6` or `#f4f5f7`.
+
+### Component Architecture
+
+Modern component libraries use two main patterns:
+
+#### Compound Components
+
+Compound components expose sub-components that compose together:
+
+```tsx
+<Card>
+  <Card.Header>
+    <h3>Title</h3>
+  </Card.Header>
+  <Card.Content>
+    <p>Content goes here</p>
+  </Card.Content>
+  <Card.Footer>
+    <Button>Action</Button>
+  </Card.Footer>
+</Card>
+```
+
+HeroUI uses this pattern. Each sub-component is independently styleable, and you can omit parts you don't need. The parent component manages shared state (like selection in a RadioGroup) while children control their own rendering.
+
+#### Monolithic Components
+
+Monolithic components accept all configuration through props:
+
+```tsx
+<Card
+  title="Title"
+  description="Content goes here"
+  footer={<Button>Action</Button>}
+/>
+```
+
+This is simpler for basic use cases but becomes rigid when you need custom layouts, conditional rendering, or non-standard markup.
+
+**Which is better?** Compound components scale better for design systems because they give consuming teams more control without requiring library changes. When a team needs to add an icon between the title and description, they just add it — no new prop needed.
+
+### Accessibility Layer
+
+The best design systems build accessibility into the foundation layer, not the component layer. This means using a primitive library like React Aria or Radix UI that handles:
+
+- ARIA attributes and roles
+- Keyboard navigation patterns
+- Focus management (trapping, restoration, virtual focus)
+- Screen reader announcements
+- Touch and pointer interactions
+- Right-to-left layout support
+
+HeroUI builds on [React Aria](https://react-spectrum.adobe.com/react-aria/), one of the most comprehensive accessibility primitive libraries available for React. This means HeroUI components — from Button to Calendar to ComboBox — inherit battle-tested accessibility behavior.
+
+## Building a Design System with React
+
+### Option 1: Adopt a Component Library
+
+The fastest path to a design system is adopting an existing component library and extending it. This gives you:
+
+- Pre-built components with accessibility handled
+- A token system you can customize
+- Documentation and examples
+- Community support and ongoing maintenance
+
+**Best for:** Teams that want to move fast and don't have unique design requirements that existing libraries can't accommodate.
+
+**Recommended libraries:**
+
+| Library | Styling | Best For |
+|---------|---------|----------|
+| HeroUI | Tailwind CSS v4 | Modern stack, accessibility, AI tooling |
+| shadcn/ui | Tailwind CSS | Maximum code ownership |
+| MUI | Emotion / `sx` prop, with Pigment CSS experimental | Material Design, enterprise |
+| Mantine | CSS Modules | Maximum component breadth |
+
+### Option 2: Build on Primitives
+
+If you need a fully custom design language, build your components on top of accessibility primitives:
+
+- **React Aria** — Most comprehensive accessibility primitives. Used by HeroUI.
+- **Radix UI** — Excellent accessibility, popular composition patterns. Used by shadcn/ui.
+- **Ark UI** — State machine-based, works across React/Vue/Solid.
+
+**Best for:** Teams with dedicated design system engineers and unique design requirements.
+
+### Option 3: Extend and Customize
+
+Many teams start by adopting a library (option 1) and gradually extend it. HeroUI supports this through:
+
+- **CSS-based component classes** for predictable customization
+- **CSS custom properties** for token overrides
+- **Compound component pattern** for structural customization
+- **Theme system** for global visual changes
+
+This hybrid approach gives you the speed of a pre-built library with the flexibility to diverge where your product needs it.
+
+## Design Tokens in Practice
+
+### Setting Up Tokens with Tailwind CSS v4
+
+Tailwind v4 lets you define design tokens directly in CSS:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+
+:root {
+  --accent: oklch(0.6204 0.195 253.83);
+  --accent-foreground: var(--snow);
+  --radius: 0.5rem;
+  --surface-shadow:
+    0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+    0 0 1px 0 rgba(0, 0, 0, 0.06);
+}
+```
+
+These tokens become Tailwind utilities automatically:
+
+```tsx
+<div className="rounded-md bg-accent shadow-surface">
+  <p className="text-accent-foreground">Styled with HeroUI tokens</p>
+</div>
+```
+
+### Token Organization
+
+Organize tokens in layers:
+
+1. **Primitive tokens** — Raw values that do not change between themes (`--snow`, `--eclipse`)
+2. **Semantic tokens** — Theme-aware values (`--background`, `--foreground`, `--accent`, `--surface`)
+3. **Computed Tailwind tokens** — Utility-facing values generated in `@theme` (`--color-accent`, `--color-background`, `--radius-md`)
+
+HeroUI uses this layered approach. You can override at any level — change the primary color globally, adjust the card radius specifically, or create an entirely new theme.
+
+## Common Pitfalls
+
+### Over-engineering early
+
+Don't build a design system before you need one. If you're a team of three building an MVP, adopting a component library is enough. The system should emerge from patterns you discover, not be designed upfront.
+
+### Treating it as a one-time project
+
+A design system is a product, not a project. It needs ongoing investment — new components, bug fixes, documentation updates, and user support. If you build it and walk away, it'll be outdated within months.
+
+### Ignoring the developer experience
+
+If your design system is hard to use, developers will work around it. Prioritize:
+
+- Clear, searchable documentation
+- Copy-pasteable code examples
+- Sensible defaults that work without configuration
+- Escape hatches for edge cases
+
+### Forgetting accessibility
+
+Bolting accessibility onto an existing component library is painful and often incomplete. Choose a foundation (React Aria, Radix UI) that handles accessibility from the start.
+
+## How HeroUI Fits In
+
+HeroUI provides the component library and token system layers of a design system:
+
+- **<ComponentCount />+ components** built on React Aria with compound component APIs
+- **Tailwind CSS v4 tokens** for colors, spacing, radii, and typography
+- **Theme system** with light/dark mode and custom themes
+- **AI tooling** (MCP server, llms.txt, agent skills) for developer productivity
+
+You still need to add your own patterns, documentation, and governance on top — but the engineering-heavy parts (accessible components, a token system, theme support) are handled.
+
+## Getting Started
+
+1. **Audit your current UI.** Identify inconsistencies — different button styles, inconsistent spacing, duplicate components. These are the problems a design system solves.
+2. **Adopt a component library.** Start with HeroUI or another library that matches your stack. Customize the tokens to match your brand.
+3. **Document your patterns.** As your team builds features, document the patterns that emerge — how you handle empty states, form validation, loading states, error messages.
+4. **Establish governance.** Decide how new components get proposed, reviewed, and shipped. Keep it lightweight at first.
+5. **Iterate.** A design system is never done. Measure adoption, collect feedback, and improve continuously.
+
+## Further Reading
+
+- [HeroUI Quick Start Guide](/docs/react/getting-started/quick-start) — Get started with HeroUI's component library
+- [HeroUI Theming Guide](/docs/react/getting-started/theming) — Customize design tokens and themes
+- [React Component Libraries Compared](/blog/react-component-library-comparison) — Compare your options
+- [Component Documentation](/docs/react/components) — Explore HeroUI's component library
diff --git a/apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx b/apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx
new file mode 100644
index 0000000..fafa125
--- /dev/null
+++ b/apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx
@@ -0,0 +1,305 @@
+---
+title: "Why Choose HeroUI for Your Design System"
+description: "Why choose HeroUI: React Aria accessibility, Tailwind CSS v4 styling, compound components, and AI-native tooling for production React apps."
+date: "2026-05-17"
+author: "Junior Garcia"
+authorHandle: "@jrgarciadev"
+authorUrl: "https://x.com/jrgarciadev"
+authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4"
+tags: ["heroui", "design-system", "react", "ui-libraries"]
+image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+---
+
+Most React component libraries solve the same problem: stop rebuilding buttons. But design systems fail at a different stage — when the library you chose can't flex to your product's needs, when accessibility is an afterthought bolted on after launch, or when your AI coding assistant hallucinates props that don't exist.
+
+HeroUI combines [React Aria](https://react-spectrum.adobe.com/react-aria/) for accessibility, [Tailwind CSS v4](https://tailwindcss.com/) for styling, and a compound component API that gives you structural control without prop sprawl. This post explains the concrete reasons to choose it as the foundation of your design system.
+
+## The Stack
+
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| **Accessibility** | React Aria (Adobe) | Industry-leading WCAG primitives, actively maintained |
+| **Styling** | Tailwind CSS v4 | Static CSS, zero runtime, design tokens via `@theme` |
+| **Component API** | Compound components | `Card.Header`, `Modal.Body` — structural control without prop sprawl |
+| **Types** | TypeScript | Full type coverage, generic props, strict mode compatible |
+| **AI tooling** | MCP server, llms.txt, agent skills | AI assistants get current APIs, not stale training data |
+| **Cross-platform** | HeroUI Native (React Native) | Same design system on web and mobile — no other open library does this |
+
+## Accessibility That's Actually Enterprise-Grade
+
+Every HeroUI component is built on [React Aria](https://react-spectrum.adobe.com/react-aria/), Adobe's accessibility primitive library. This isn't a marketing checkbox — React Aria is the deepest accessibility foundation available for React, and it powers Adobe's own production design system (Spectrum) across Photoshop Web, Acrobat, and Lightroom.
+
+What React Aria handles that most libraries don't:
+
+- **Platform-aware keyboard navigation.** Mac, Windows, and Linux have different conventions for Home/End, option/alt+arrow, and focus behavior. React Aria adapts automatically.
+- **Screen reader announcements.** Live regions, status messages, and dynamic content announcements work correctly across JAWS, NVDA, and VoiceOver.
+- **Touch interactions.** Long press, drag and drop, and gesture handling on mobile — not just click events.
+- **Internationalization.** Right-to-left layouts, locale-aware date/number formatting, and string collation for 30+ languages.
+- **Virtual focus.** For collections with thousands of items, React Aria maintains performance while keeping screen readers informed.
+
+This matters because accessibility compliance isn't optional in 2026. Government, healthcare, finance, and education all require WCAG conformance. HeroUI gives you that conformance as a default, not an upgrade.
+
+### React Aria vs Radix UI
+
+Many popular libraries (shadcn/ui, Park UI) are built on Radix UI. Radix is solid, but the original team has shifted focus to Base UI, and the long-term maintenance of Radix primitives is an open question. React Aria is actively maintained by Adobe — a company that depends on it for their own products.
+
+## Tailwind CSS v4 Native
+
+HeroUI doesn't use Tailwind as a compatibility layer — it's built for Tailwind CSS v4 from the ground up.
+
+**What this means in practice:**
+
+- **Zero runtime CSS overhead.** All styles are static CSS, resolved at build time. No CSS-in-JS computation, no style injection, no hydration cost.
+- **Design tokens via CSS custom properties.** Your theme lives in standard CSS `@theme` directives, not JavaScript configuration objects. Change a token and every component updates.
+- **Utility-first customization.** Override any component with `className` — the same Tailwind workflow you use for everything else in your project.
+- **Smaller output.** Tailwind v4's new engine produces less CSS. Combined with HeroUI's modular imports, your production bundle stays lean.
+
+```tsx
+<Button variant="secondary" className="font-semibold tracking-wide">
+  Get Started
+</Button>
+
+<Card className="max-w-md shadow-lg">
+  <Card.Header className="pb-0">
+    <Card.Title className="text-xl font-bold">Dashboard</Card.Title>
+  </Card.Header>
+  <Card.Content className="py-4">
+    Your metrics here
+  </Card.Content>
+</Card>
+```
+
+If your team already uses Tailwind, HeroUI integrates without introducing a second styling system. If you don't use Tailwind yet, adopting it is a separate decision — but one that most React teams in 2026 have already made.
+
+## Compound Component API
+
+HeroUI uses compound components — a pattern where parent components expose sub-components through dot notation. This is the same approach used by Radix UI, and it scales far better than prop-based APIs for complex UIs.
+
+```tsx
+<Modal>
+  <Button>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.Header>
+          <Modal.Heading>Confirm</Modal.Heading>
+        </Modal.Header>
+        <Modal.Body>Are you sure?</Modal.Body>
+        <Modal.Footer>
+          <Button variant="ghost">Cancel</Button>
+          <Button>Confirm</Button>
+        </Modal.Footer>
+      </Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+**Why this matters for design systems:**
+
+- **Structural control.** Reorder, omit, or insert custom elements between component parts. No fighting the library's internal layout.
+- **Slot-level styling.** Apply `className` to any sub-component independently. Style `Card.Header` differently from `Card.Footer` without CSS overrides.
+- **TypeScript verification.** The compiler checks your component tree structure — wrong nesting gets caught at build time, not in production.
+- **Readable JSX.** The hierarchy of your component maps directly to the visual hierarchy of your UI. New team members can read the code and understand the layout.
+
+## <ComponentCount />+ Components
+
+HeroUI ships <ComponentCount />+ components with <ExampleCount />+ documented examples. The library covers the full product UI surface:
+
+- **Data input** — Input, Textarea, NumberField, Select, ComboBox, Autocomplete, DatePicker, DateRangePicker, ColorPicker, Slider, Switch, Checkbox, Radio
+- **Data display** — Table (sorting, selection, pagination), Avatar, Badge, Chip, Tag, Skeleton
+- **Layout** — Card, Surface, Separator, Fieldset
+- **Navigation** — Tabs, Breadcrumbs, Pagination, Link
+- **Feedback** — Toast, ProgressBar, ProgressCircle, Meter, Spinner
+- **Overlay** — Modal, Drawer, Popover, Tooltip, Dropdown, AlertDialog
+- **Disclosure** — Accordion, Disclosure
+- **Actions** — Button, ToggleButton, ToggleButtonGroup
+
+Complex components like Calendar, DatePicker, ColorPicker, and Table are self-contained — they handle date math, locale formatting, keyboard navigation, and screen reader announcements internally. These are genuinely hard to build accessibly, and HeroUI ships them as maintained, tested primitives.
+
+## AI-Native Tooling
+
+Most developers use AI coding assistants daily. The quality of generated code depends on whether the AI has accurate context for your component library — or is guessing from stale training data.
+
+HeroUI ships four first-party integrations:
+
+### MCP Server
+
+A [Model Context Protocol server](/docs/react/getting-started/mcp-server) that AI agents can query for component documentation, APIs, source code, and design tokens. Connect it to Cursor, Claude Code, Windsurf, or any MCP-compatible editor.
+
+When an AI assistant has access to the MCP server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component — instead of hallucinating.
+
+[Learn how to set up the MCP Server →](/docs/react/getting-started/mcp-server)
+
+### llms.txt
+
+A structured reference file at [heroui.com/llms.txt](/docs/react/getting-started/llms-txt) that gives LLMs a condensed, accurate reference for the entire library. This is a standardized format that AI tools consume to avoid generating deprecated patterns.
+
+[Learn more about llms.txt →](/docs/react/getting-started/llms-txt)
+
+### Agent Skills
+
+Pre-built [skill files](/docs/react/getting-started/agent-skills) for Cursor, Claude Code, and other AI tools that teach agents HeroUI's conventions — correct imports, compound component patterns, styling approaches, and project scaffolding.
+
+[Learn how to install Agent Skills →](/docs/react/getting-started/agent-skills)
+
+### AGENTS.md
+
+An [AGENTS.md file](/docs/react/getting-started/agents-md) that provides repository-level context for AI coding agents. It describes the project structure, coding conventions, and component patterns so agents understand your codebase from the first prompt.
+
+[Learn about AGENTS.md →](/docs/react/getting-started/agents-md)
+
+**The result:** AI assistants generate correct HeroUI v3 code with the right compound component patterns, import paths, and Tailwind classes. This matters because incorrect AI output costs more time to debug than it saves to generate.
+
+## The Ecosystem
+
+### HeroUI Pro
+
+[HeroUI Pro](https://heroui.com/pro) extends the base library with app-level components and templates:
+
+- **AppLayout, Sidebar, Navbar** — Full application shell with responsive behavior
+- **DataGrid** — Dense data tables with typed columns, sorting, and filtering
+- **KPI, NumberValue, TrendChip** — Dashboard metric components
+- **LineChart, BarChart** — Data visualization
+- **Sheet, CommandMenu** — Advanced overlay patterns
+- **Templates** — Dashboard, finance, chat, and email app starting points
+
+Pro is a paid product — use it when you need app infrastructure, not just UI components.
+
+### HeroUI Native
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp"
+  alt="HeroUI Native - React Native components"
+/>
+
+HeroUI is the only open design system that delivers the same component quality across both web and mobile. [HeroUI Native](/docs/native/getting-started) brings the same design tokens, compound component API, and accessibility standards to React Native — leveraging each platform's native APIs instead of wrapping web views.
+
+This means teams building cross-platform products can share a single design system across React (web) and React Native (mobile) without compromising on either platform. Same visual language, same component patterns, same theming tokens — but native rendering on each side.
+
+No other open-source React component library offers this. MUI, shadcn/ui, Chakra UI, and Mantine are web-only. If your product ships on both web and mobile, HeroUI is the only design system that covers both from the same foundation.
+
+### Figma Kit
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-light.png"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-dark.png"
+  alt="HeroUI Figma Kit"
+/>
+
+The [HeroUI Figma Kit (v3)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) keeps design and code in sync. Components in Figma match the React implementation, so designers and developers work from the same source of truth.
+
+### Storybook
+
+Every component has [Storybook stories](https://storybook-v3.heroui.com/) showing all variants, states, and compositions. Use it for visual testing, design review, and documentation.
+
+### Community
+
+HeroUI isn't new — we've been building it for over 5 years, starting from v1 (originally NextUI). The community has grown steadily: 29.3K+ GitHub stars, 9K+ Discord members, and thousands of discussions, community answers, and issues resolved every week.
+
+- [GitHub](https://github.com/heroui-inc/heroui) — Source code, issues, and discussions
+- [Discord](https://discord.gg/heroui) — 9K+ members, community support and announcements
+- [X / Twitter](https://x.com/hero_ui) — Updates and releases
+
+### Backed by Y Combinator
+
+HeroUI is venture-backed, including [Y Combinator](https://www.ycombinator.com/companies/heroui). This means a dedicated full-time team, long-term maintenance commitments, and the resources to keep shipping. When you adopt a component library, you're betting on its future — HeroUI is built to be around for the long run.
+
+## Design Quality Out of the Box
+
+HeroUI ships with refined defaults that look polished without custom theming:
+
+- **Smooth animations.** Buttons have subtle press states. Modals animate with spring physics. Accordions expand with natural easing.
+- **Balanced spacing tokens.** Consistent padding, margins, and gaps across all components follow a mathematical scale.
+- **Shadow hierarchy.** Elevation levels that work in both light and dark mode without manual adjustment.
+- **Theme variants.** Built-in support for visual identities like glass, brutalism, and neutral — switchable through design tokens.
+
+The design token system uses CSS custom properties, so theming is standard CSS:
+
+```css
+@theme {
+  --color-primary: oklch(0.6 0.25 260);
+  --radius-field: 0.5rem;
+  --shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
+}
+```
+
+Change tokens globally and every component updates. No JavaScript theme objects, no provider wrappers, no runtime overhead.
+
+Want to make HeroUI yours in a few clicks? The [Theme Builder](/themes) lets you customize colors, typography, radius, and spacing visually — then export a ready-to-use CSS theme for your project.
+
+## Ready in Two Steps
+
+Most component libraries require configuration files, provider wrappers, theme objects, and plugin setup before you can render your first component. HeroUI doesn't. The entire setup is two steps:
+
+**1. Install:**
+
+```bash
+npm i @heroui/styles @heroui/react
+```
+
+**2. Add one line to your CSS:**
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles"; /* That's it */
+```
+
+Now use any component — no `ThemeProvider`, no `ChakraProvider`, no `MantineProvider`, no configuration objects:
+
+```tsx
+import { Button, Card } from "@heroui/react";
+
+export default function Page() {
+  return (
+    <Card>
+      <Card.Content>
+        <Button>Click me</Button>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+That's the entire setup. No wrapping your app in providers, no theme configuration files, no runtime setup. Install, import one CSS line, and start building. See the [Quick Start guide](/docs/react/getting-started/quick-start) to get running in under five minutes.
+
+## Server Components
+
+HeroUI is designed for the React Server Components model:
+
+- **Static components** (`Card`, `Badge`, `Text`, `Separator`, `Avatar`) stay in server component trees with zero client JavaScript.
+- **Interactive components** (`Button`, `Modal`, `Table`, `Select`) use client boundaries — clearly documented per component.
+- **No provider required** — no client-side context that forces your entire tree into a client boundary.
+
+This means your pages ship less JavaScript by default. Static layouts render on the server. Interactive widgets hydrate only where needed.
+
+## Considerations
+
+HeroUI takes a focused approach: instead of shipping every possible component, we prioritize depth, accessibility, and quality for the components teams use most. For specialized needs like rich text editing, drag-and-drop, or charting, we recommend pairing HeroUI with dedicated libraries that excel at those specific problems — this gives you better results than relying on a single library to handle everything.
+
+HeroUI is built for Tailwind CSS v4. If your team is already using Tailwind, adoption is seamless. If you're on a different styling approach, the switch to Tailwind is a separate but worthwhile investment in modern CSS tooling.
+
+## Who Should Use HeroUI
+
+HeroUI is a strong fit if you're building:
+
+- **SaaS applications** — Forms, tables, overlays, and navigation with React Aria accessibility
+- **Dashboards and admin panels** — Data-dense layouts with HeroUI Pro components
+- **E-commerce storefronts** — Performant, accessible, SEO-friendly component rendering
+- **Marketing sites and landing pages** — Polished defaults without runtime CSS overhead
+- **Cross-platform products** — Same design system on web (React) and mobile (React Native) with HeroUI Native
+- **Any React / Next.js project** that values accessibility, Tailwind CSS integration, and AI-assisted development
+
+## Get Started
+
+```bash
+npm install @heroui/styles @heroui/react
+```
+
+- [Quick Start Guide](/docs/react/getting-started/quick-start) — Set up in under five minutes
+- [Component Documentation](/docs/react/components) — Full API reference with live examples
+- [Theming Guide](/docs/react/getting-started/theming) — Customize the design system
+- [MCP Server](/docs/react/getting-started/mcp-server) — Connect your AI coding assistant
+- [GitHub Repository](https://github.com/heroui-inc/heroui) — Source code and issues
diff --git a/apps/docs/content/docs/cn/meta.json b/apps/docs/content/docs/cn/meta.json
new file mode 100644
index 0000000..811019d
--- /dev/null
+++ b/apps/docs/content/docs/cn/meta.json
@@ -0,0 +1,3 @@
+{
+  "pages": ["react", "native"]
+}
diff --git a/apps/docs/content/docs/cn/native/components/(buttons)/button.mdx b/apps/docs/content/docs/cn/native/components/(buttons)/button.mdx
new file mode 100644
index 0000000..f08b935
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(buttons)/button.mdx
@@ -0,0 +1,391 @@
+---
+title: Button 按钮
+description: 按下时触发操作的交互组件。
+links:
+  source_native: button/button.tsx
+  styles_native: button/button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Button } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Button>
+  <Button.Label>...</Button.Label>
+</Button>
+```
+
+- **Button**：主容器，负责按压交互、动画与变体。字符串子节点会渲染为标签，也可使用复合子组件自定义布局。
+- **Button.Label**：按钮文字，继承父级 Button 上下文中的尺寸与变体样式。
+
+## 用法
+
+### 基础用法
+
+`Button` 可直接传入字符串子节点，会自动渲染为标签。
+
+```tsx
+<Button>基础按钮</Button>
+```
+
+### 使用复合子组件
+
+使用 `Button.Label` 显式控制标签部分。
+
+```tsx
+<Button>
+  <Button.Label>点我</Button.Label>
+</Button>
+```
+
+### 与图标组合
+
+将图标与文字组合，增强可读性。
+
+```tsx
+<Button>
+  <Icon name="add" size={20} />
+  <Button.Label>添加项目</Button.Label>
+</Button>
+
+<Button>
+  <Button.Label>下载</Button.Label>
+  <Icon name="download" size={18} />
+</Button>
+```
+
+### 仅图标
+
+使用 `isIconOnly` 创建方形纯图标按钮。
+
+```tsx
+<Button isIconOnly>
+  <Icon name="heart" size={18} />
+</Button>
+```
+
+### 尺寸
+
+通过三种尺寸控制按钮大小。
+
+```tsx
+<Button size="sm">小</Button>
+<Button size="md">中</Button>
+<Button size="lg">大</Button>
+```
+
+### 变体
+
+提供七种视觉变体，用于不同强调层级。
+
+```tsx
+<Button variant="primary">主要</Button>
+<Button variant="secondary">次要</Button>
+<Button variant="tertiary">第三级</Button>
+<Button variant="outline">描边</Button>
+<Button variant="ghost">幽灵</Button>
+<Button variant="danger">危险</Button>
+<Button variant="danger-soft">柔和危险</Button>
+```
+
+### 反馈变体
+
+`feedbackVariant` 控制渲染哪些按压反馈效果：
+
+- `'scale-highlight'`（默认）：内置缩放 + 高亮遮罩
+- `'scale-ripple'`：内置缩放 + 水波纹遮罩
+- `'scale'`：仅内置缩放（无遮罩）
+- `'none'`：无任何反馈动画
+
+```tsx
+{/* 缩放 + 高亮（默认） */}
+<Button feedbackVariant="scale-highlight">高亮效果</Button>
+
+{/* 缩放 + 水波纹 */}
+<Button feedbackVariant="scale-ripple">水波纹效果</Button>
+
+{/* 仅缩放 */}
+<Button feedbackVariant="scale">仅缩放</Button>
+
+{/* 无反馈 */}
+<Button feedbackVariant="none">无反馈</Button>
+```
+
+### 自定义动画
+
+`animation` 控制各子动画，其结构取决于 `feedbackVariant`。
+
+```tsx
+{/* 自定义缩放与高亮（默认 feedbackVariant） */}
+<Button
+  animation={{
+    scale: { value: 0.97 },
+    highlight: {
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.2] },
+    },
+  }}
+>
+  自定义高亮
+</Button>
+
+{/* 自定义缩放与水波纹 */}
+<Button
+  feedbackVariant="scale-ripple"
+  animation={{
+    scale: { value: 0.97 },
+    ripple: {
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.3, 0] },
+    },
+  }}
+>
+  自定义水波纹
+</Button>
+```
+
+### 关闭部分子动画
+
+将某个子动画设为 `false` 即可单独关闭：
+
+```tsx
+{/* 关闭缩放，保留高亮 */}
+<Button animation={{ scale: false }}>无缩放</Button>
+
+{/* 关闭高亮，保留缩放 */}
+<Button animation={{ highlight: false }}>无高亮</Button>
+
+{/* 两者都关 */}
+<Button animation={{ scale: false, highlight: false }}>无动画</Button>
+```
+
+### 关闭全部动画
+
+使用 `animation={false}` 关闭所有反馈，或使用 `animation="disable-all"` 级联关闭：
+
+```tsx
+<Button animation={false}>已禁用动画</Button>
+<Button animation="disable-all">全部禁用（级联）</Button>
+```
+
+### 加载态与 Spinner
+
+配合 Spinner 展示加载状态。
+
+```tsx
+const themeColorAccentForeground = useThemeColor('accent-foreground');
+
+<Button
+  layout={LinearTransition.springify()}
+  variant="primary"
+  onPress={() => {
+    setIsDownloading(true);
+    setTimeout(() => {
+      setIsDownloading(false);
+    }, 3000);
+  }}
+  isIconOnly={isDownloading}
+  className="self-center"
+>
+  {isDownloading ? (
+    <Spinner entering={FadeIn.delay(50)} color={themeColorAccentForeground} />
+  ) : (
+    '立即下载'
+  )}
+</Button>;
+```
+
+### 使用 LinearGradient 自定义背景
+
+通过绝对定位元素添加渐变背景。使用 `feedbackVariant="none"` 关闭默认高亮遮罩，或使用 `feedbackVariant="scale-ripple"` 自定义水波纹。
+
+```tsx
+import { Button, PressableFeedback } from 'heroui-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { StyleSheet } from 'react-native';
+
+{/* 无反馈遮罩的渐变 */}
+<Button feedbackVariant="none">
+  <LinearGradient
+    colors={['#9333ea', '#ec4899']}
+    start={{ x: 0, y: 0 }}
+    end={{ x: 1, y: 0 }}
+    style={StyleSheet.absoluteFill}
+  />
+  <Button.Label className="text-white font-bold">渐变</Button.Label>
+</Button>
+
+{/* 带自定义水波纹的渐变 */}
+<Button
+  feedbackVariant="scale-ripple"
+  animation={{
+    ripple: {
+      backgroundColor: { value: 'white' },
+      opacity: { value: [0, 0.5, 0] },
+    },
+  }}
+>
+  <LinearGradient
+    colors={['#0d9488', '#ec4899']}
+    start={{ x: 0, y: 0 }}
+    end={{ x: 1, y: 0 }}
+    style={StyleSheet.absoluteFill}
+  />
+  <Button.Label className="text-white font-bold" pointerEvents="none">
+    带水波纹的渐变
+  </Button.Label>
+</Button>
+```
+
+## 示例
+
+```tsx
+import { Button, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+
+export default function ButtonExample() {
+  const [
+    themeColorAccentForeground,
+    themeColorAccentSoftForeground,
+    themeColorDangerForeground,
+    themeColorDefaultForeground,
+  ] = useThemeColor([
+    'accent-foreground',
+    'accent-soft-foreground',
+    'danger-foreground',
+    'default-foreground',
+  ]);
+
+  return (
+    <View className="gap-4 p-4">
+      <Button variant="primary">
+        <Ionicons name="add" size={20} color={themeColorAccentForeground} />
+        <Button.Label>添加项目</Button.Label>
+      </Button>
+
+      <View className="flex-row gap-4">
+        <Button size="sm" isIconOnly>
+          <Ionicons name="heart" size={16} color={themeColorAccentForeground} />
+        </Button>
+        <Button size="sm" variant="secondary" isIconOnly>
+          <Ionicons
+            name="bookmark"
+            size={16}
+            color={themeColorAccentSoftForeground}
+          />
+        </Button>
+        <Button size="sm" variant="danger" isIconOnly>
+          <Ionicons name="trash" size={16} color={themeColorDangerForeground} />
+        </Button>
+      </View>
+
+      <Button variant="tertiary">
+        <Button.Label>了解更多</Button.Label>
+        <Ionicons
+          name="chevron-forward"
+          size={18}
+          color={themeColorDefaultForeground}
+        />
+      </Button>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/button.tsx>)。
+
+## API 参考
+
+### Button
+
+`Button` 继承 [PressableFeedback](./pressable-feedback) 的全部属性（`animation` 除外，已重新定义），并增加按钮专用属性。
+
+| prop              | type                                                                                          | default             | description                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
+| `variant`         | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'`         | 按钮视觉变体                                   |
+| `size`            | `'sm' \| 'md' \| 'lg'`                                                                        | `'md'`              | 按钮尺寸                                             |
+| `isIconOnly`      | `boolean`                                                                                     | `false`             | 是否为仅图标按钮（方形比例） |
+| `feedbackVariant` | `'scale-highlight' \| 'scale-ripple' \| 'scale' \| 'none'`                                    | `'scale-highlight'` | 决定渲染哪些反馈效果                 |
+| `animation`       | `ButtonAnimation`                                                                             | -                   | 动画配置（结构取决于 `feedbackVariant`）   |
+
+继承属性（含 `isDisabled`、`className`、`children` 及所有 Pressable 属性）见 [PressableFeedback API 参考](./pressable-feedback#api-reference)。
+
+#### ButtonAnimation
+
+`animation` 是按 `feedbackVariant` 区分的联合类型，遵循 `AnimationRoot` 控制流：
+
+- `true` 或 `undefined`：使用默认动画
+- `false` 或 `"disabled"`：关闭所有反馈动画
+- `"disable-all"`：级联关闭所有动画（含子复合部件）
+- `object`：自定义子动画配置（见下）
+
+**当 `feedbackVariant="scale-highlight"`（默认）时：**
+
+| prop        | type                                     | default | description                                                  |
+| ----------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale`     | `PressableFeedbackScaleAnimation`        | -       | 缩放动画配置（`false` 为关闭）                  |
+| `highlight` | `PressableFeedbackHighlightAnimation`    | -       | 高亮遮罩配置（`false` 为关闭）                |
+| `state`     | `'disabled' \| 'disable-all' \| boolean` | -       | 在保留配置的同时控制动画状态（运行时切换） |
+
+**当 `feedbackVariant="scale-ripple"` 时：**
+
+| prop     | type                                     | default | description                                                  |
+| -------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale`  | `PressableFeedbackScaleAnimation`        | -       | 缩放动画配置（`false` 为关闭）                  |
+| `ripple` | `PressableFeedbackRippleAnimation`       | -       | 水波纹遮罩配置（`false` 为关闭）                   |
+| `state`  | `'disabled' \| 'disable-all' \| boolean` | -       | 在保留配置的同时控制动画状态（运行时切换） |
+
+**当 `feedbackVariant="scale"` 时：**
+
+| prop    | type                                     | default | description                                                  |
+| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale` | `PressableFeedbackScaleAnimation`        | -       | 缩放动画配置（`false` 为关闭）                  |
+| `state` | `'disabled' \| 'disable-all' \| boolean` | -       | 在保留配置的同时控制动画状态（运行时切换） |
+
+**当 `feedbackVariant="none"` 时：**
+
+仅接受字符串 `'disable-all'`。所有反馈效果均被禁用。
+
+动画子类型（`PressableFeedbackScaleAnimation`、`PressableFeedbackHighlightAnimation`、`PressableFeedbackRippleAnimation`）详见 [PressableFeedback API 参考](./pressable-feedback#api-reference)。
+
+### Button.Label
+
+| prop           | type              | default | description                           |
+| -------------- | ----------------- | ------- | ------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 作为标签渲染的内容       |
+| `className`    | `string`          | -       | 额外 CSS 类                |
+| `...TextProps` | `TextProps`       | -       | 支持全部标准 Text 属性 |
+
+## Hooks
+
+### useButton
+
+用于读取 Button 上下文，返回尺寸、变体与禁用状态。
+
+```tsx
+import { useButton } from 'heroui-native';
+
+const { size, variant, isDisabled } = useButton();
+```
+
+#### 返回值
+
+| property     | type                                                                                          | description                    |
+| ------------ | --------------------------------------------------------------------------------------------- | ------------------------------ |
+| `size`       | `'sm' \| 'md' \| 'lg'`                                                                        | 按钮尺寸             |
+| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | 按钮视觉变体   |
+| `isDisabled` | `boolean`                                                                                     | 是否禁用 |
+
+**说明：** 必须在 `Button` 内使用；在按钮上下文外调用会抛错。
diff --git a/apps/docs/content/docs/cn/native/components/(buttons)/close-button.mdx b/apps/docs/content/docs/cn/native/components/(buttons)/close-button.mdx
new file mode 100644
index 0000000..3a3a830
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(buttons)/close-button.mdx
@@ -0,0 +1,119 @@
+---
+title: CloseButton 关闭按钮
+description: 用于关闭对话框、模态框或收起内容的按钮组件。
+links:
+  source_native: close-button/close-button.tsx
+  styles_native: close-button/close-button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { CloseButton } from 'heroui-native';
+```
+
+## 用法
+
+### 基础用法
+
+CloseButton 渲染带默认样式的关闭图标按钮。
+
+```tsx
+<CloseButton />
+```
+
+### 自定义图标颜色
+
+通过 `iconProps` 自定义图标颜色。
+
+```tsx
+<CloseButton iconProps={{ color: themeColorDanger }} />
+<CloseButton iconProps={{ color: themeColorAccent }} />
+```
+
+### 自定义图标尺寸
+
+通过 `iconProps` 调整图标大小。
+
+```tsx
+<CloseButton iconProps={{ size: 24 }} />
+```
+
+### 自定义子节点
+
+用自定义内容替换默认关闭图标。
+
+```tsx
+<CloseButton>
+  <CustomIcon />
+</CloseButton>
+```
+
+### 禁用态
+
+禁用按钮以禁止交互。
+
+```tsx
+<CloseButton isDisabled />
+```
+
+## 示例
+
+```tsx
+import { CloseButton, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function CloseButtonExample() {
+  const themeColorForeground = useThemeColor('foreground');
+  const themeColorDanger = useThemeColor('danger');
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View className="flex-row items-center gap-4">
+        <CloseButton />
+        <CloseButton iconProps={{ color: themeColorDanger }} />
+        <CloseButton>
+          <StyledIonicons
+            name="close-circle"
+            size={28}
+            color={themeColorForeground}
+          />
+        </CloseButton>
+        <CloseButton isDisabled />
+      </View>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/close-button.tsx)。
+
+## API 参考
+
+### CloseButton
+
+CloseButton 继承 [Button](./button) 的全部属性。默认 `variant='tertiary'`、`size='sm'`、`isIconOnly=true`。
+
+| prop        | type                   | default | description                                      |
+| ----------- | ---------------------- | ------- | ------------------------------------------------ |
+| `iconProps` | `CloseButtonIconProps` | -       | 自定义关闭图标属性                               |
+| `children`  | `React.ReactNode`      | -       | 自定义内容，替换默认关闭图标                     |
+
+`isDisabled`、`className`、`animation`、`feedbackVariant` 以及所有 Pressable 相关继承属性见 [Button API 参考](./button#api-reference)。
+
+#### CloseButtonIconProps
+
+| prop    | type     | default                | description       |
+| ------- | -------- | ---------------------- | ----------------- |
+| `size`  | `number` | `20`                   | 图标尺寸          |
+| `color` | `string` | Uses theme muted color | 图标颜色          |
diff --git a/apps/docs/content/docs/cn/native/components/(buttons)/link-button.mdx b/apps/docs/content/docs/cn/native/components/(buttons)/link-button.mdx
new file mode 100644
index 0000000..5604e8a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(buttons)/link-button.mdx
@@ -0,0 +1,164 @@
+---
+title: LinkButton 链接按钮
+description: 幽灵样式按钮，无高亮按压反馈，适合行内链接式交互。
+links:
+  source_native: link-button/link-button.tsx
+  styles_native: link-button/link-button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { LinkButton } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<LinkButton>
+  <LinkButton.Label>...</LinkButton.Label>
+</LinkButton>
+```
+
+- **LinkButton**：根级可按压容器。内部渲染 `variant="ghost"` 的 `Button`，并强制关闭高亮反馈；使用者无法覆盖上述行为。
+- **LinkButton.Label**：链接按钮文字，继承父级上下文中的尺寸与变体样式。
+
+## 用法
+
+### 基础用法
+
+行内链接风格文字，响应按压。
+
+```tsx
+<LinkButton onPress={handlePress}>了解更多</LinkButton>
+```
+
+### 尺寸
+
+使用 `size` 控制文字尺寸。
+
+```tsx
+<LinkButton size="sm">
+  小
+</LinkButton>
+
+<LinkButton size="md">
+  中
+</LinkButton>
+
+<LinkButton size="lg">
+  大
+</LinkButton>
+```
+
+### 禁用状态
+
+禁用后不可交互。
+
+```tsx
+<LinkButton isDisabled>已禁用的链接</LinkButton>
+```
+
+### 自定义样式
+
+在根与 `Label` 上使用 `className`。
+
+```tsx
+<LinkButton className="px-2">
+  <LinkButton.Label className="text-accent underline">
+    样式化链接
+  </LinkButton.Label>
+</LinkButton>
+```
+
+### 与正文混排
+
+与普通文字混排，用于条款、政策或上下文导航。
+
+```tsx
+<View className="flex-row flex-wrap">
+  <Text className="text-sm text-muted">我同意 </Text>
+  <LinkButton size="sm" onPress={handleTermsPress}>
+    <LinkButton.Label className="text-accent">
+      服务条款
+    </LinkButton.Label>
+  </LinkButton>
+  <Text className="text-sm text-muted"> 与 </Text>
+  <LinkButton size="sm" onPress={handlePrivacyPress}>
+    <LinkButton.Label className="text-accent">隐私政策</LinkButton.Label>
+  </LinkButton>
+</View>
+```
+
+## 示例
+
+```tsx
+import { Button, Checkbox, ControlField, LinkButton } from 'heroui-native';
+import React from 'react';
+import { Alert, View, Text } from 'react-native';
+
+export default function LinkButtonExample() {
+  const [isAgreed, setIsAgreed] = React.useState(false);
+
+  const handleTermsPress = () => Alert.alert('条款', '跳转至服务条款');
+  const handlePrivacyPress = () =>
+    Alert.alert('隐私', '跳转至隐私政策');
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View className="w-full max-w-xs gap-6">
+        <ControlField
+          isSelected={isAgreed}
+          onSelectedChange={setIsAgreed}
+          className="items-start"
+        >
+          <ControlField.Indicator>
+            <Checkbox className="mt-0.5" />
+          </ControlField.Indicator>
+          <View className="flex-row flex-wrap flex-1">
+            <Text className="text-sm text-muted">我同意 </Text>
+            <LinkButton size="sm" onPress={handleTermsPress}>
+              <LinkButton.Label className="text-accent">
+                服务条款
+              </LinkButton.Label>
+            </LinkButton>
+            <Text className="text-sm text-muted"> 与 </Text>
+            <LinkButton size="sm" onPress={handlePrivacyPress}>
+              <LinkButton.Label className="text-accent">
+                隐私政策
+              </LinkButton.Label>
+            </LinkButton>
+          </View>
+        </ControlField>
+        <Button isDisabled={!isAgreed}>注册</Button>
+      </View>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/link-button.tsx>)。
+
+## API 参考
+
+### LinkButton
+
+继承 [Button](./button#button) 的全部属性，**除 `variant` 外**（内部固定为 `ghost`）。
+
+**内部强制行为：**
+
+| override    | value        | description                              |
+| ----------- | ------------ | ---------------------------------------- |
+| `variant`   | `ghost`      | 始终为 ghost，不可修改                   |
+| `highlight` | `false`      | 高亮反馈关闭，不可修改                   |
+| `className` | `h-auto p-0` | 移除默认按钮高度与内边距               |
+
+### LinkButton.Label
+
+与 [Button.Label](./button#buttonlabel) 等价，属性相同。
diff --git a/apps/docs/content/docs/cn/native/components/(collections)/menu.mdx b/apps/docs/content/docs/cn/native/components/(collections)/menu.mdx
new file mode 100644
index 0000000..256a250
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(collections)/menu.mdx
@@ -0,0 +1,811 @@
+---
+title: Menu 菜单
+description: 浮动上下文菜单，支持定位、选择分组与多种呈现方式。
+icon: updated
+links:
+  source_native: menu/menu.tsx
+  styles_native: menu/menu.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Menu, SubMenu } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover">
+      <Menu.Close />
+      <Menu.Label>...</Menu.Label>
+      <Menu.Group>
+        <Menu.Item>
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>...</Menu.ItemTitle>
+          <Menu.ItemDescription>...</Menu.ItemDescription>
+        </Menu.Item>
+      </Menu.Group>
+      <SubMenu>
+        <SubMenu.Trigger textValue="...">
+          <SubMenu.TriggerIndicator />
+          ...
+        </SubMenu.Trigger>
+        <SubMenu.Content>
+          <Menu.Item>...</Menu.Item>
+          <Menu.Item>...</Menu.Item>
+        </SubMenu.Content>
+      </SubMenu>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+- **Menu**：主容器，管理开闭状态与定位，并向子组件提供上下文。
+- **Menu.Trigger**：可点击元素，用于切换菜单显隐。
+- **Menu.Portal**：在 Portal 层渲染菜单内容，叠于其他内容之上。
+- **Menu.Overlay**：可选背景遮罩，用于捕获外部点击并关闭菜单。
+- **Menu.Content**：菜单内容容器；两种呈现：带定位与碰撞检测的浮动 Popover，或底部抽屉式 Bottom Sheet。
+- **Menu.Close**：关闭按钮，按下后关闭菜单。
+- **Menu.Label**：菜单内的非交互分区标题。
+- **Menu.Group**：对菜单项分组，可选选择模式（无 / 单选 / 多选）。
+- **Menu.Item**：可按压菜单项，带按压动画反馈；可独立使用或置于 Group 内参与选择。
+- **Menu.ItemTitle**：菜单项主标题文本。
+- **Menu.ItemDescription**：菜单项次要说明文本。
+- **Menu.ItemIndicator**：菜单项选中指示（对勾或圆点）。
+- **SubMenu**：子菜单根容器，管理展开/收起状态并为子级提供动画上下文。
+- **SubMenu.Trigger**：可按压行，切换子菜单开闭；样式与普通菜单项一致。
+- **SubMenu.TriggerIndicator**：动画 V 形图标（默认 chevron-right），随子菜单开闭旋转；放在 `SubMenu.Trigger` 内。
+- **SubMenu.Content**：绝对定位容器，子菜单开闭时带动画高度变化；其内放置 `Menu.Item` 等。
+
+## 用法
+
+### 基础用法
+
+Menu 通过复合部件组成浮动上下文菜单。
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={220}>
+      <Menu.Item>
+        <Menu.ItemTitle>View Profile</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Settings</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### 带副标题
+
+在标题旁为菜单项添加次要说明文字。
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={260}>
+      <Menu.Item className="items-start">
+        <View className="flex-1">
+          <Menu.ItemTitle>New file</Menu.ItemTitle>
+          <Menu.ItemDescription>Create a new file</Menu.ItemDescription>
+        </View>
+      </Menu.Item>
+      <Menu.Item className="items-start">
+        <View className="flex-1">
+          <Menu.ItemTitle>Copy link</Menu.ItemTitle>
+          <Menu.ItemDescription>Copy the file link</Menu.ItemDescription>
+        </View>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### 单选
+
+使用 `Menu.Group` 并设置 `selectionMode="single"`，同一时间仅允许选中一项。
+
+```tsx
+const [theme, setTheme] = useState<Set<MenuKey>>(() => new Set(['system']));
+
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={180}>
+      <Menu.Label>Appearance</Menu.Label>
+      <Menu.Group
+        selectionMode="single"
+        selectedKeys={theme}
+        onSelectionChange={setTheme}
+      >
+        <Menu.Item id="light">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Light</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="dark">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Dark</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="system">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>System</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>;
+```
+
+### 多选
+
+使用 `selectionMode="multiple"` 可同时选中多项。
+
+```tsx
+const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
+  () => new Set(['bold', 'italic'])
+);
+
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={250}>
+      <Menu.Label>Text Style</Menu.Label>
+      <Menu.Group
+        selectionMode="multiple"
+        selectedKeys={textStyles}
+        onSelectionChange={setTextStyles}
+      >
+        <Menu.Item id="bold">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Bold</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="italic">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Italic</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="underline">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Underline</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>;
+```
+
+### 子菜单
+
+在 `Menu.Content` 内嵌套 `SubMenu`，按压后展开更多项。
+
+```tsx
+<Menu>
+  <Menu.Trigger asChild>
+    <Button variant="secondary">Editor Menu</Button>
+  </Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={240}>
+      <Menu.Item>
+        <Menu.ItemTitle>New Space</Menu.ItemTitle>
+      </Menu.Item>
+      <SubMenu>
+        <SubMenu.Trigger textValue="Focus">
+          <SubMenu.TriggerIndicator />
+          <Text className="flex-1 text-base font-medium text-foreground">
+            Focus
+          </Text>
+        </SubMenu.Trigger>
+        <SubMenu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Zen Mode</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Reader Mode</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Lock Tab</Menu.ItemTitle>
+          </Menu.Item>
+        </SubMenu.Content>
+      </SubMenu>
+      <Menu.Item>
+        <Menu.ItemTitle>Heading 1</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### 危险变体
+
+对破坏性操作在菜单项上使用 `variant="danger"`。
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={220}>
+      <Menu.Item>
+        <Menu.ItemTitle>Edit</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item variant="danger">
+        <Menu.ItemTitle>Delete</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### 方位
+
+控制菜单相对触发器出现的位置。
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" placement="right" width={200}>
+      <Menu.Item>
+        <Menu.ItemTitle>Option A</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Option B</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Bottom Sheet 呈现
+
+使用 `presentation="bottom-sheet"` 以底部抽屉形式展示菜单内容。
+
+```tsx
+<Menu presentation="bottom-sheet">
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="bottom-sheet">
+      <Menu.Item>
+        <Menu.ItemTitle>Option A</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Option B</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### 圆点指示器
+
+在 `Menu.ItemIndicator` 上使用 `variant="dot"` 显示实心圆点，而非对勾。
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={180}>
+      <Menu.Group
+        selectionMode="single"
+        selectedKeys={alignment}
+        onSelectionChange={setAlignment}
+      >
+        <Menu.Item id="left">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Left</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="center">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Center</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="right">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Right</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+## 示例
+
+```tsx
+import type { MenuKey } from 'heroui-native';
+import { Button, Menu, Separator } from 'heroui-native';
+import { useState } from 'react';
+import { Text, View } from 'react-native';
+
+export default function MenuExample() {
+  const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
+    () => new Set(['bold', 'italic'])
+  );
+  const [alignment, setAlignment] = useState<Set<MenuKey>>(
+    () => new Set(['left'])
+  );
+
+  return (
+    <Menu>
+      <Menu.Trigger asChild>
+        <Button variant="secondary">Styles</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content presentation="popover" width={250}>
+          <Menu.Label className="mb-1">Text Style</Menu.Label>
+          <Menu.Group
+            selectionMode="multiple"
+            selectedKeys={textStyles}
+            onSelectionChange={setTextStyles}
+          >
+            <Menu.Item id="bold">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Bold</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ B</Text>
+            </Menu.Item>
+            <Menu.Item id="italic">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Italic</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ I</Text>
+            </Menu.Item>
+            <Menu.Item id="underline">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Underline</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ U</Text>
+            </Menu.Item>
+          </Menu.Group>
+          <Separator className="mx-2 my-2 opacity-75" />
+          <Menu.Label className="mb-1">Text Alignment</Menu.Label>
+          <Menu.Group
+            selectionMode="single"
+            selectedKeys={alignment}
+            onSelectionChange={setAlignment}
+          >
+            <Menu.Item id="left">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Left</Menu.ItemTitle>
+            </Menu.Item>
+            <Menu.Item id="center">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Center</Menu.ItemTitle>
+            </Menu.Item>
+            <Menu.Item id="right">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Right</Menu.ItemTitle>
+            </Menu.Item>
+          </Menu.Group>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/menu.tsx>)。
+
+## API 参考
+
+### Menu
+
+| prop            | type                          | default     | description                                        |
+| --------------- | ----------------------------- | ----------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`             | -           | 菜单内容                                           |
+| `presentation`  | `'popover' \| 'bottom-sheet'` | `'popover'` | 菜单内容的呈现方式                                 |
+| `isOpen`        | `boolean`                     | -           | 受控开闭状态                                       |
+| `isDefaultOpen` | `boolean`                     | -           | 非受控：首次渲染时是否打开                         |
+| `isDisabled`    | `boolean`                     | -           | 是否禁用菜单                                       |
+| `animation`     | `MenuRootAnimation`           | -           | 菜单根级动画配置                                   |
+| `onOpenChange`  | `(open: boolean) => void`     | -           | 开闭状态变化时触发                                 |
+| `...ViewProps`  | `ViewProps`                   | -           | 支持 React Native `View` 的全部标准属性          |
+
+#### MenuRootAnimation
+
+菜单根组件的动画配置，可为：
+
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+
+### Menu.Trigger
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | 触发器内容                                              |
+| `className`         | `string`          | -       | 触发器额外 class                                        |
+| `isDisabled`        | `boolean`         | `false` | 是否禁用触发器                                          |
+| `asChild`           | `boolean`         | -       | 使用 Slot 模式将行为合并到单个子元素                    |
+| `...PressableProps` | `PressableProps`  | -       | 支持 React Native `Pressable` 的全部标准属性          |
+
+### Menu.Portal
+
+| prop                       | type              | default | description                                            |
+| -------------------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`                 | `React.ReactNode` | -       | Portal 内容                                            |
+| `className`                | `string`          | -       | Portal 容器额外 class                                  |
+| `disableFullWindowOverlay` | `boolean`         | `false` | 在 iOS 上使用普通 `View` 替代 `FullWindowOverlay`      |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时焦点限制在遮罩内。仅 iOS。不稳定：可能随 `react-native-screens` 更新变化 |
+| `hostName`                 | `string`          | -       | Portal 宿主元素的可选名称                              |
+| `forceMount`               | `boolean`         | -       | 无论开闭状态是否强制挂载 Portal                        |
+
+### Menu.Overlay
+
+| prop                    | type                   | default | description                                                  |
+| ----------------------- | ---------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`               | -       | 遮罩额外 class                                               |
+| `closeOnPress`          | `boolean`              | `true`  | 点击遮罩时是否关闭菜单                                       |
+| `animation`             | `MenuOverlayAnimation` | -       | 遮罩动画配置                                                 |
+| `isAnimatedStyleActive` | `boolean`              | `true`  | 是否启用 Reanimated 动画样式                               |
+| `forceMount`            | `boolean`              | -       | 无论开闭是否强制挂载遮罩                                     |
+| `...PressableProps`     | `PressableProps`       | -       | 支持 React Native `Pressable` 的全部标准属性               |
+
+#### MenuOverlayAnimation
+
+菜单遮罩的动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭所有动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                     | type                    | default                 | description                         |
+| ------------------------ | ----------------------- | ----------------------- | ----------------------------------- |
+| `state`                  | `'disabled' \| boolean` | -                       | 关闭动画的同时仍允许自定义属性      |
+| `opacity.entering.value` | `EntryOrExitLayoutType` | `FadeIn.duration(200)`  | 遮罩进入动画                        |
+| `opacity.exiting.value`  | `EntryOrExitLayoutType` | `FadeOut.duration(150)` | 遮罩退出动画                        |
+
+### Menu.Content（Popover）
+
+当 `presentation="popover"` 时的属性。
+
+| prop              | type                                             | default         | description                                        |
+| ----------------- | ------------------------------------------------ | --------------- | -------------------------------------------------- |
+| `children`        | `React.ReactNode`                                | -               | 菜单内容                                           |
+| `presentation`    | `'popover'`                                      | -               | 呈现方式（须与 Menu 根一致）                       |
+| `placement`       | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | 相对触发器的弹出方位                               |
+| `align`           | `'start' \| 'center' \| 'end'`                   | `'center'`      | 沿对齐轴相对触发器的对齐方式                       |
+| `avoidCollisions` | `boolean`                                        | `true`          | 是否自动避让屏幕边缘                               |
+| `offset`          | `number`                                         | `9`             | 与触发器的间距（像素）                             |
+| `alignOffset`     | `number`                                         | `0`             | 沿对齐轴的偏移（像素）                             |
+| `width`           | `'content-fit' \| 'trigger' \| 'full' \| number` | `'content-fit'` | 内容宽度策略                                       |
+| `className`       | `string`                                         | -               | 内容容器额外 class                                 |
+| `animation`       | `MenuContentAnimation`                           | -               | 内容动画配置                                       |
+| `...ViewProps`    | `ViewProps`                                      | -               | 支持 React Native `View` 的全部标准属性            |
+
+#### MenuContentAnimation
+
+Popover 内容动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭所有动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                    | default                         | description                    |
+| ---------------- | ----------------------- | ------------------------------- | ------------------------------ |
+| `state`          | `'disabled' \| boolean` | -                               | 关闭动画的同时仍允许自定义属性 |
+| `entering.value` | `EntryOrExitLayoutType` | Scale + fade entering animation | 自定义进入动画                 |
+| `exiting.value`  | `EntryOrExitLayoutType` | Scale + fade exiting animation  | 自定义退出动画                 |
+
+### Menu.Content（Bottom Sheet）
+
+当 `presentation="bottom-sheet"` 时的属性。继承 `@gorhom/bottom-sheet` 的 BottomSheet 属性。
+
+| prop                        | type                                     | default | description                                          |
+| --------------------------- | ---------------------------------------- | ------- | ---------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -       | 底部抽屉内容                                         |
+| `presentation`              | `'bottom-sheet'`                         | -       | 呈现方式（须与 Menu 根一致）                         |
+| `className`                 | `string`                                 | -       | 底部抽屉额外 class                                   |
+| `backgroundClassName`       | `string`                                 | -       | 背景额外 class                                       |
+| `handleIndicatorClassName`  | `string`                                 | -       | 把手指示条额外 class                                 |
+| `contentContainerClassName` | `string`                                 | -       | 内容容器额外 class                                   |
+| `contentContainerProps`     | `Omit<BottomSheetViewProps, 'children'>` | -       | 内容容器属性                                         |
+| `animation`                 | `AnimationDisabled`                      | -       | 设为 `false` 或 `"disabled"` 可关闭动画             |
+| `...BottomSheetProps`       | `Partial<BottomSheetProps>`              | -       | 支持 `@gorhom/bottom-sheet` 的全部属性               |
+
+### Menu.Close
+
+继承 `CloseButtonProps`。按下后自动关闭菜单。
+
+| prop             | type                   | default | description                          |
+| ---------------- | ---------------------- | ------- | ------------------------------------ |
+| `iconProps`      | `CloseButtonIconProps` | -       | 自定义关闭图标属性                   |
+| `...ButtonProps` | `ButtonRootProps`      | -       | 支持 Button 根级全部属性            |
+
+### Menu.Group
+
+| prop                  | type                               | default  | description                                        |
+| --------------------- | ---------------------------------- | -------- | -------------------------------------------------- |
+| `children`            | `React.ReactNode`                  | -        | 分组内容（`Menu.Item` 等）                         |
+| `selectionMode`       | `'none' \| 'single' \| 'multiple'` | `'none'` | 分组内允许的选择类型                               |
+| `selectedKeys`        | `Iterable<MenuKey>`                | -        | 当前选中键（受控）                                 |
+| `defaultSelectedKeys` | `Iterable<MenuKey>`                | -        | 初始选中键（非受控）                               |
+| `isDisabled`          | `boolean`                          | `false`  | 是否禁用整个分组                                   |
+| `disabledKeys`        | `Iterable<MenuKey>`                | -        | 应禁用的项键集合                                   |
+| `shouldCloseOnSelect` | `boolean`                          | -        | 选中项时是否关闭菜单                               |
+| `className`           | `string`                           | -        | 分组容器额外 class                                 |
+| `onSelectionChange`   | `(keys: Set<MenuKey>) => void`     | -        | 选中变化时回调                                     |
+| `...ViewProps`        | `ViewProps`                        | -        | 支持 React Native `View` 的全部标准属性            |
+
+### Menu.Label
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标签文本内容                                       |
+| `className`    | `string`          | -       | 标签额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部标准属性          |
+
+### Menu.Item
+
+| prop                    | type                                                             | default     | description                                                  |
+| ----------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: MenuItemRenderProps) => ReactNode)` | -           | 子元素或渲染函数                                             |
+| `id`                    | `MenuKey`                                                        | -           | 唯一标识；在 `Menu.Group` 内时必填                           |
+| `variant`               | `'default' \| 'danger'`                                          | `'default'` | 菜单项视觉变体                                               |
+| `isDisabled`            | `boolean`                                                        | `false`     | 是否禁用该项                                                 |
+| `isSelected`            | `boolean`                                                        | -           | 独立项时的受控选中状态                                       |
+| `shouldCloseOnSelect`   | `boolean`                                                        | `true`      | 按压该项是否关闭菜单                                         |
+| `className`             | `string`                                                         | -           | 菜单项额外 class                                             |
+| `animation`             | `MenuItemAnimation`                                              | -           | 按压反馈动画配置                                             |
+| `isAnimatedStyleActive` | `boolean`                                                        | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `onSelectedChange`      | `(selected: boolean) => void`                                    | -           | 独立项选中状态变化时回调                                     |
+| `...PressableProps`     | `PressableProps`                                                 | -           | 支持 React Native `Pressable` 的全部标准属性                 |
+
+#### MenuItemRenderProps
+
+当 `children` 为函数时传入渲染函数的参数。
+
+| prop         | type                    | description                             |
+| ------------ | ----------------------- | --------------------------------------- |
+| `isSelected` | `boolean`               | 当前项是否选中                          |
+| `isDisabled` | `boolean`               | 是否禁用                                |
+| `isPressed`  | `SharedValue<boolean>`  | 是否处于按压中                          |
+| `variant`    | `'default' \| 'danger'` | 项的视觉变体                            |
+
+#### MenuItemAnimation
+
+菜单项按压反馈动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭项动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                           | type               | default                    | description                    |
+| ------------------------------ | ------------------ | -------------------------- | ------------------------------ |
+| `scale.value`                  | `number`           | `0.98`                     | 按压时的缩放值                 |
+| `scale.timingConfig`           | `WithTimingConfig` | `{ duration: 150 }`        | 缩放的动画配置                 |
+| `backgroundColor.value`        | `string`           | `useThemeColor('default')` | 按压时背景色                   |
+| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 150 }`        | 背景色过渡时间配置             |
+
+### Menu.ItemTitle
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题文本内容                                       |
+| `className`    | `string`          | -       | 标题额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部标准属性          |
+
+### Menu.ItemDescription
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 说明文本内容                                       |
+| `className`    | `string`          | -       | 说明额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部标准属性          |
+
+### Menu.ItemIndicator
+
+| prop           | type                         | default       | description                                            |
+| -------------- | ---------------------------- | ------------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode`            | -             | 自定义指示内容；默认为对勾或圆点                     |
+| `variant`      | `'checkmark' \| 'dot'`       | `'checkmark'` | 指示器视觉变体                                         |
+| `iconProps`    | `MenuItemIndicatorIconProps` | -             | 图标配置（对勾变体）                                   |
+| `forceMount`   | `boolean`                    | `true`        | 无论是否选中都强制挂载指示器                           |
+| `className`    | `string`                     | -             | 指示器额外 class                                       |
+| `...ViewProps` | `ViewProps`                  | -             | 支持 React Native `View` 的全部标准属性              |
+
+#### MenuItemIndicatorIconProps
+
+| prop    | type     | default | description                                    |
+| ------- | -------- | ------- | ---------------------------------------------- |
+| `size`  | `number` | `16`    | 指示图标尺寸（圆点变体为 8）                   |
+| `color` | `string` | `muted` | 指示图标颜色                                   |
+
+### SubMenu
+
+| prop            | type                      | default | description                                              |
+| --------------- | ------------------------- | ------- | -------------------------------------------------------- |
+| `children`      | `React.ReactNode`         | -       | 子菜单内容（触发器、内容区等）                           |
+| `isOpen`        | `boolean`                 | -       | 受控开闭状态                                             |
+| `isDefaultOpen` | `boolean`                 | -       | 非受控：首次渲染时是否打开                               |
+| `isDisabled`    | `boolean`                 | `false` | 是否禁用子菜单                                           |
+| `className`     | `string`                  | -       | 根容器额外 class                                         |
+| `animation`     | `SubMenuRootAnimation`    | -       | 子菜单动画配置                                           |
+| `onOpenChange`  | `(open: boolean) => void` | -       | 开闭状态变化时回调                                       |
+| `...ViewProps`  | `ViewProps`               | -       | 支持 React Native `View` 的全部标准属性                |
+
+##### SubMenuRootAnimation
+
+SubMenu 根组件动画配置，可为：
+
+- `"disable-all"`：关闭所有动画（含子级）
+- `false` 或 `"disabled"`：仅关闭根级动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                            | type                    | default                                     | description                            |
+| ------------------------------- | ----------------------- | ------------------------------------------- | -------------------------------------- |
+| `state`                         | `'disabled' \| boolean` | -                                           | 关闭动画的同时仍允许自定义属性         |
+| `rootContent.marginHorizontal`  | `number`                | `-16`                                       | 子菜单打开时水平外边距                 |
+| `rootContent.marginVertical`    | `number`                | `-16`                                       | 子菜单打开时垂直外边距                 |
+| `rootContent.paddingHorizontal` | `number`                | `6`                                         | 子菜单打开时水平内边距                 |
+| `rootContent.paddingTop`        | `number`                | `12`                                        | 子菜单打开时顶部内边距                 |
+| `rootContent.springConfig`      | `WithSpringConfig`      | `{ damping: 100, stiffness: 950, mass: 3 }` | 展开/收起的弹簧配置                    |
+
+#### SubMenu.Trigger
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | 触发器内容（标题、图标、指示器等）                      |
+| `textValue`         | `string`          | -       | 读屏播报的无障碍文本                                    |
+| `className`         | `string`          | -       | 触发器额外 class                                        |
+| `isDisabled`        | `boolean`         | `false` | 是否禁用                                                |
+| `asChild`           | `boolean`         | -       | 使用 Slot 模式合并到单个子元素                          |
+| `...PressableProps` | `PressableProps`  | -       | 支持 React Native `Pressable` 的全部标准属性          |
+
+#### SubMenu.TriggerIndicator
+
+子菜单开闭时旋转的指示图标，默认为向右 V 形（chevron-right）。
+
+| prop                    | type                               | default | description                                                  |
+| ----------------------- | ---------------------------------- | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                  | -       | 自定义指示内容（替换默认 V 形）                              |
+| `className`             | `string`                           | -       | 指示器额外 class                                             |
+| `iconProps`             | `SubMenuTriggerIndicatorIconProps` | -       | 默认 V 形的图标配置                                          |
+| `animation`             | `SubMenuTriggerIndicatorAnimation` | -       | 指示器旋转动画配置                                           |
+| `isAnimatedStyleActive` | `boolean`                          | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `...ViewProps`          | `ViewProps`                        | -       | 支持 React Native `View` 的全部标准属性                    |
+
+##### SubMenuTriggerIndicatorIconProps
+
+| prop    | type     | default | description                 |
+| ------- | -------- | ------- | --------------------------- |
+| `size`  | `number` | `14`    | 指示图标尺寸                |
+| `color` | `string` | `muted` | 指示图标颜色                |
+
+##### SubMenuTriggerIndicatorAnimation
+
+触发器指示旋转的动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭所有动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                    | type                    | default                                      | description                                      |
+| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
+| `state`                 | `'disabled' \| boolean` | -                                            | 关闭动画的同时仍允许自定义属性                   |
+| `rotation.value`        | `[number, number]`      | `[0, 90]`                                    | 旋转角度 [收起, 展开]，单位度                  |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧配置                                     |
+
+#### SubMenu.Content
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | 子菜单项（`Menu.Item`、`Menu.Group` 等）                |
+| `className`         | `string`          | -       | 内容容器额外 class                                      |
+| `...PressableProps` | `PressableProps`  | -       | 支持 React Native `Pressable` 的全部标准属性          |
+
+## Hooks
+
+### useMenu
+
+访问菜单根上下文，须在 `Menu` 内使用。
+
+```tsx
+import { useMenu } from 'heroui-native';
+
+const { isOpen, onOpenChange, presentation, isDisabled } = useMenu();
+```
+
+#### 返回值
+
+| property       | type                          | description                             |
+| -------------- | ----------------------------- | --------------------------------------- |
+| `isOpen`       | `boolean`                     | 菜单是否打开                            |
+| `onOpenChange` | `(open: boolean) => void`     | 修改开闭状态的回调                      |
+| `presentation` | `'popover' \| 'bottom-sheet'` | 当前呈现模式                            |
+| `isDisabled`   | `boolean \| undefined`        | 是否禁用                                |
+| `nativeID`     | `string`                      | 菜单实例唯一标识                        |
+
+### useMenuItem
+
+访问菜单项上下文，须在 `Menu.Item` 内使用。
+
+```tsx
+import { useMenuItem } from 'heroui-native';
+
+const { id, isSelected, isDisabled, variant } = useMenuItem();
+```
+
+#### 返回值
+
+| property     | type                    | description                            |
+| ------------ | ----------------------- | -------------------------------------- |
+| `id`         | `MenuKey \| undefined`  | 项标识                                 |
+| `isSelected` | `boolean`               | 是否选中                               |
+| `isDisabled` | `boolean`               | 是否禁用                               |
+| `variant`    | `'default' \| 'danger'` | 项的视觉变体                           |
+
+### useMenuAnimation
+
+访问菜单动画上下文，须在 `Menu` 内使用。
+
+```tsx
+import { useMenuAnimation } from 'heroui-native';
+
+const { progress, isDragging } = useMenuAnimation();
+```
+
+#### 返回值
+
+| property     | type                   | description                                               |
+| ------------ | ---------------------- | --------------------------------------------------------- |
+| `progress`   | `SharedValue<number>`  | 动画进度（0=空闲，1=打开，2=关闭）                        |
+| `isDragging` | `SharedValue<boolean>` | Bottom Sheet 是否正在被拖拽                               |
+
+### useSubMenu
+
+访问子菜单上下文，须在 `SubMenu` 内使用。
+
+```tsx
+import { useSubMenu } from 'heroui-native';
+
+const { isOpen, onOpenChange, isDisabled } = useSubMenu();
+```
+
+#### 返回值
+
+| property       | type                      | description                                 |
+| -------------- | ------------------------- | ------------------------------------------- |
+| `isOpen`       | `boolean`                 | 子菜单是否打开                              |
+| `onOpenChange` | `(open: boolean) => void` | 修改开闭状态的回调                          |
+| `isDisabled`   | `boolean`                 | 是否禁用                                    |
+| `nativeID`     | `string`                  | 子菜单实例唯一标识                          |
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+Menu 在 iOS 上使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，请在 `Menu.Portal` 上设置 `disableFullWindowOverlay={true}`。代价是菜单将无法叠在原生模态之上。
+
+### 原生模态（iOS）
+
+当 `Menu` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），菜单内容可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（菜单挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Menu.Content presentation="popover" offset={insets.top}>
+  ...
+</Menu.Content>;
+```
diff --git a/apps/docs/content/docs/cn/native/components/(collections)/tag-group.mdx b/apps/docs/content/docs/cn/native/components/(collections)/tag-group.mdx
new file mode 100644
index 0000000..2cb5c45
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(collections)/tag-group.mdx
@@ -0,0 +1,414 @@
+---
+title: TagGroup 标签组
+description: 用于展示与管理可选标签的复合组件，支持可选移除。
+links:
+  source_native: tag-group/tag-group.tsx
+  styles_native: tag-group/tag-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { TagGroup } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<TagGroup>
+  <TagGroup.List>
+    <TagGroup.Item id="tag-1">
+      <TagGroup.ItemLabel>...</TagGroup.ItemLabel>
+      <TagGroup.ItemRemoveButton />
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+- **TagGroup**：主容器，管理标签选中状态、禁用键与移除能力，并向子组件提供尺寸与变体上下文。
+- **TagGroup.List**：渲染标签列表的容器，可渲染空状态。
+- **TagGroup.Item**：组内单个标签。支持字符串子节点（自动包在 `TagGroup.ItemLabel`）、渲染函数子节点或自定义布局。
+- **TagGroup.ItemLabel**：标签文字。提供字符串子节点时会自动渲染，也可显式使用。
+- **TagGroup.ItemRemoveButton**：移除按钮；需要移除能力时需显式放置。仅当 `TagGroup` 传入 `onRemove` 时生效。
+
+## 用法
+
+### 基础用法
+
+展示一个简单的可选标签组。
+
+```tsx
+<TagGroup selectionMode="single">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+    <TagGroup.Item id="gaming">游戏</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 单选模式
+
+同一时间只能选中一个标签。
+
+```tsx
+<TagGroup selectionMode="single" defaultSelectedKeys={['news']}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+    <TagGroup.Item id="gaming">游戏</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 多选模式
+
+允许多个标签同时选中。
+
+```tsx
+<TagGroup selectionMode="multiple" defaultSelectedKeys={['news', 'travel']}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+    <TagGroup.Item id="gaming">游戏</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 受控选中
+
+通过 `selectedKeys` 与 `onSelectionChange` 控制选中状态。
+
+```tsx
+const [selected, setSelected] = useState(new Set(['news']));
+
+<TagGroup
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+    <TagGroup.Item id="gaming">游戏</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>;
+```
+
+### 变体
+
+为标签应用不同视觉变体。
+
+```tsx
+<TagGroup selectionMode="single" variant="default">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" variant="surface">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 尺寸
+
+控制组内所有标签的尺寸。
+
+```tsx
+<TagGroup selectionMode="single" size="sm">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" size="md">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" size="lg">
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 带移除按钮
+
+提供 `onRemove`，并在每个条目中放置 `TagGroup.ItemRemoveButton` 以显示移除按钮。
+
+```tsx
+const [tags, setTags] = useState([
+  { id: 'news', name: '新闻' },
+  { id: 'travel', name: '旅行' },
+]);
+
+const onRemove = (keys) => {
+  setTags((prev) => prev.filter((tag) => !keys.has(tag.id)));
+};
+
+<TagGroup selectionMode="single" onRemove={onRemove}>
+  <TagGroup.List>
+    {tags.map((tag) => (
+      <TagGroup.Item key={tag.id} id={tag.id}>
+        <TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
+        <TagGroup.ItemRemoveButton />
+      </TagGroup.Item>
+    ))}
+  </TagGroup.List>
+</TagGroup>;
+```
+
+### 渲染函数子节点
+
+使用渲染函数访问 `isSelected`、`isDisabled` 以自定义布局。
+
+```tsx
+<TagGroup selectionMode="single">
+  <TagGroup.List>
+    <TagGroup.Item id="news">
+      {({ isSelected }) => (
+        <>
+          <SquareArticleIcon
+            size={16}
+            colorClassName={
+              isSelected
+                ? 'accent-accent-soft-foreground'
+                : 'accent-field-foreground'
+            }
+          />
+          <TagGroup.ItemLabel>新闻</TagGroup.ItemLabel>
+        </>
+      )}
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 空状态
+
+列表无标签时渲染自定义内容。
+
+```tsx
+<TagGroup onRemove={onRemove}>
+  <TagGroup.List
+    renderEmptyState={() => (
+      <Text className="text-sm text-muted">暂无分类</Text>
+    )}
+  >
+    {tags.map((tag) => (
+      <TagGroup.Item key={tag.id} id={tag.id}>
+        <TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
+        <TagGroup.ItemRemoveButton />
+      </TagGroup.Item>
+    ))}
+  </TagGroup.List>
+</TagGroup>
+```
+
+### 禁用标签
+
+禁用单个标签或整个组。
+
+```tsx
+<TagGroup selectionMode="single" disabledKeys={new Set(['travel'])}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">新闻</TagGroup.Item>
+    <TagGroup.Item id="travel">旅行</TagGroup.Item>
+    <TagGroup.Item id="gaming" isDisabled>
+      游戏
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+## 示例
+
+```tsx
+import { TagGroup, Label, Description, FieldError } from 'heroui-native';
+import { useState, useMemo } from 'react';
+import { View } from 'react-native';
+
+export default function TagGroupExample() {
+  const [selected, setSelected] = useState(new Set());
+  const isInvalid = useMemo(
+    () => Array.from(selected).length === 0,
+    [selected]
+  );
+
+  return (
+    <View className="gap-4">
+      <TagGroup
+        selectedKeys={selected}
+        selectionMode="multiple"
+        onSelectionChange={setSelected}
+        isInvalid={isInvalid}
+      >
+        <Label isInvalid={false}>设施</Label>
+        <TagGroup.List>
+          <TagGroup.Item id="laundry">洗衣</TagGroup.Item>
+          <TagGroup.Item id="fitness">健身房</TagGroup.Item>
+          <TagGroup.Item id="parking">停车</TagGroup.Item>
+          <TagGroup.Item id="pool">泳池</TagGroup.Item>
+          <TagGroup.Item id="breakfast">早餐</TagGroup.Item>
+        </TagGroup.List>
+        <Description hideOnInvalid>
+          {`已选：${Array.from(selected).join('、')}`}
+        </Description>
+        <FieldError>请至少选择一个分类</FieldError>
+      </TagGroup>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tag-group.tsx>)。
+
+## API 参考
+
+### TagGroup
+
+| prop                  | type                               | default     | description                                                      |
+| --------------------- | ---------------------------------- | ----------- | ---------------------------------------------------------------- |
+| `children`            | `React.ReactNode`                  | -           | 渲染在标签组内的子节点                                           |
+| `size`                | `'sm' \| 'md' \| 'lg'`             | `'md'`      | 组内所有标签的尺寸                                               |
+| `variant`             | `'default' \| 'surface'`           | `'default'` | 组内所有标签的视觉变体                                           |
+| `selectionMode`       | `'none' \| 'single' \| 'multiple'` | `'none'`    | 允许的选中类型                                                   |
+| `selectedKeys`        | `Iterable<TagKey>`                 | -           | 当前选中键（受控）                                               |
+| `defaultSelectedKeys` | `Iterable<TagKey>`                 | -           | 初始选中键（非受控）                                             |
+| `disabledKeys`        | `Iterable<TagKey>`                 | -           | 应被禁用的标签键                                                 |
+| `isDisabled`          | `boolean`                          | `false`     | 是否禁用整个标签组                                               |
+| `isInvalid`           | `boolean`                          | `false`     | 是否处于非法状态                                                 |
+| `isRequired`          | `boolean`                          | `false`     | 是否必填                                                         |
+| `className`           | `string`                           | -           | 标签组容器的额外 class                                           |
+| `style`               | `StyleProp<ViewStyle>`             | -           | 标签组容器的额外样式                                             |
+| `animation`           | `"disable-all" \| undefined`       | -           | 设为 `"disable-all"` 可禁用全部动画（含子级）                    |
+| `onSelectionChange`   | `(keys: Set<TagKey>) => void`      | -           | 选中变化时调用                                                   |
+| `onRemove`            | `(keys: Set<TagKey>) => void`      | -           | 移除标签时调用                                                   |
+| `...ViewProps`        | `ViewProps`                        | -           | 支持 React Native `View` 的全部属性                              |
+
+#### TagKey
+
+`string | number` — 在 `TagGroup` 内标识标签的键类型。
+
+#### Animation
+
+使用 `animation="disable-all"` 可禁用全部动画（含子级）。省略或使用 `undefined` 为默认动画。
+
+### TagGroup.List
+
+| prop               | type                    | default | description                                        |
+| ------------------ | ----------------------- | ------- | -------------------------------------------------- |
+| `children`         | `React.ReactNode`       | -       | 列表内的子节点                                     |
+| `className`        | `string`                | -       | 列表容器的额外 class                               |
+| `style`            | `StyleProp<ViewStyle>`  | -       | 列表容器的额外样式                                 |
+| `renderEmptyState` | `() => React.ReactNode` | -       | 无标签时调用的渲染函数                             |
+| `...ViewProps`     | `ViewProps`             | -       | 支持 React Native `View` 的全部属性                |
+
+### TagGroup.Item
+
+| prop                | type                                                                    | default | description                                                                  |
+| ------------------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((renderProps: TagRenderProps) => React.ReactNode)` | -       | 标签内容：字符串、元素，或接收 `TagRenderProps` 的渲染函数                   |
+| `id`                | `TagKey`                                                                | -       | 该标签的唯一标识                                                             |
+| `isDisabled`        | `boolean`                                                               | -       | 是否禁用该标签                                                               |
+| `className`         | `string`                                                                | -       | 标签的额外 class                                                             |
+| `style`             | `StyleProp<ViewStyle>`                                                  | -       | 标签的额外样式                                                               |
+| `...PressableProps` | `PressableProps`                                                        | -       | 支持 React Native `Pressable` 的全部属性                                       |
+
+#### TagRenderProps
+
+| prop         | type      | description                                                                 |
+| ------------ | --------- | --------------------------------------------------------------------------- |
+| `isSelected` | `boolean` | 当前是否选中                                                                 |
+| `isDisabled` | `boolean` | 是否禁用（根级、`disabledKeys` 与条目属性合并后的结果）                     |
+
+### TagGroup.ItemLabel
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 要渲染的文字内容                                   |
+| `className`    | `string`          | -       | 标签文字的额外 class                               |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+### TagGroup.ItemRemoveButton
+
+| prop                | type                       | default | description                                                                              |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`          | -       | 自定义图标或内容；省略时默认为关闭图标                                                   |
+| `className`         | `string`                   | -       | 移除按钮的额外 class                                                                     |
+| `iconProps`         | `TagRemoveButtonIconProps` | -       | 自定义默认关闭图标的属性；仅在没有 `children` 时生效                                     |
+| `hitSlop`           | `number`                   | `8`     | 扩大可点击区域                                                                           |
+| `...PressableProps` | `PressableProps`           | -       | 支持 React Native `Pressable` 的全部属性                                                 |
+
+#### TagRemoveButtonIconProps
+
+| prop    | type     | default | description |
+| ------- | -------- | ------- | ----------- |
+| `size`  | `number` | `12`    | 图标尺寸    |
+| `color` | `string` | -       | 图标颜色    |
+
+## Hooks
+
+### useTagGroup
+
+访问标签组根上下文，必须在 `TagGroup` 内使用。
+
+```tsx
+import { useTagGroup } from 'heroui-native';
+
+const {
+  selectedKeys,
+  disabledKeys,
+  selectionMode,
+  onSelectionChange,
+  onRemove,
+  isDisabled,
+  isInvalid,
+  isRequired,
+} = useTagGroup();
+```
+
+#### 返回值
+
+| property            | type                                         | description                    |
+| ------------------- | -------------------------------------------- | ------------------------------ |
+| `selectionMode`     | `'none' \| 'single' \| 'multiple'`           | 允许的选中类型                 |
+| `selectedKeys`      | `Set<TagKey>`                                | 当前选中的标签键               |
+| `disabledKeys`      | `Set<TagKey>`                                | 被禁用的标签键                 |
+| `onSelectionChange` | `(keys: Set<TagKey>) => void`                | 选中变化回调                   |
+| `onRemove`          | `((keys: Set<TagKey>) => void) \| undefined` | 移除标签回调                   |
+| `isDisabled`        | `boolean`                                    | 是否禁用整个标签组             |
+| `isInvalid`         | `boolean`                                    | 是否处于非法状态               |
+| `isRequired`        | `boolean`                                    | 是否必填                       |
+
+### useTagGroupItem
+
+访问单个标签上下文，必须在 `TagGroup.Item` 内使用。
+
+```tsx
+import { useTagGroupItem } from 'heroui-native';
+
+const { id, isSelected, isDisabled, allowsRemoving } = useTagGroupItem();
+```
+
+#### 返回值
+
+| property         | type      | description                                                                 |
+| ---------------- | --------- | --------------------------------------------------------------------------- |
+| `id`             | `TagKey`  | 该标签的唯一标识                                                            |
+| `isSelected`     | `boolean` | 当前是否选中                                                                |
+| `isDisabled`     | `boolean` | 是否禁用                                                                    |
+| `allowsRemoving` | `boolean` | 是否允许移除（当 `TagGroup` 提供 `onRemove` 时为 true）                      |
diff --git a/apps/docs/content/docs/cn/native/components/(controls)/slider.mdx b/apps/docs/content/docs/cn/native/components/(controls)/slider.mdx
new file mode 100644
index 0000000..105e60f
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(controls)/slider.mdx
@@ -0,0 +1,358 @@
+---
+title: Slider 滑块
+description: 在有限区间内通过拖拽选择单个值或区间的输入控件。
+links:
+  source_native: slider/slider.tsx
+  styles_native: slider/slider.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Slider } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Slider>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+- **Slider**：主容器，管理滑块数值、方向，并为所有子组件提供上下文。支持单值与区间模式。
+- **Slider.Output**：可选，显示当前值；支持渲染函数以自定义格式；默认显示格式化后的数值标签。
+- **Slider.Track**：为 Fill 与 Thumb 提供尺寸的容器；上报布局尺寸用于位置计算；支持点击定位与渲染函数子节点（例如区间滑块的多拇指）。
+- **Slider.Fill**：沿轨道交叉轴铺满的填充条；仅计算主轴位置与尺寸。
+- **Slider.Thumb**：基于 react-native-gesture-handler 的可拖拽拇指；由 Track 布局在交叉轴居中；通过 react-native-reanimated 在按压时缩放。每个拇指具备 `role="slider"` 与完整 `accessibilityValue`。
+
+## 用法
+
+### 基础用法
+
+Slider 通过复合部件组成可拖拽的数值输入。
+
+```tsx
+<Slider defaultValue={30}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### 标签与输出
+
+在数值输出旁显示标签。
+
+```tsx
+<Slider defaultValue={50}>
+  <View className="flex-row items-center justify-between">
+    <Label>Volume</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### 纵向
+
+将 `orientation` 设为 `"vertical"` 以纵向渲染。
+
+```tsx
+<View className="h-48">
+  <Slider defaultValue={50} orientation="vertical">
+    <Slider.Track>
+      <Slider.Fill />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider>
+</View>
+```
+
+### 区间滑块
+
+将 `value`/`defaultValue` 设为数组，并在 `Slider.Track` 上使用渲染函数以渲染多个拇指。
+
+```tsx
+<Slider
+  defaultValue={[200, 800]}
+  minValue={0}
+  maxValue={1000}
+  step={10}
+  formatOptions={{ style: 'currency', currency: 'USD' }}
+>
+  <View className="flex-row items-center justify-between">
+    <Label>Price range</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    {({ state }) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+### 受控值
+
+使用 `value` 与 `onChange` 进入受控模式。`onChangeEnd` 在拖拽结束或点击定位完成后触发。
+
+```tsx
+const [volume, setVolume] = useState(50);
+
+<Slider value={volume} onChange={setVolume} onChangeEnd={(v) => save(v)}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>;
+```
+
+### 自定义样式
+
+在拇指等子组件上使用 `className`、`classNames` 或 `styles` 自定义样式。
+
+```tsx
+<Slider defaultValue={65}>
+  <Slider.Track className="h-3 rounded-full bg-success/10">
+    <Slider.Fill className="rounded-full bg-success" />
+    <Slider.Thumb
+      classNames={{
+        thumbContainer: 'size-6 rounded-full bg-success',
+        thumbKnob: 'bg-success-foreground rounded-full',
+      }}
+      animation={{
+        scale: { value: [1, 0.7] },
+      }}
+    />
+  </Slider.Track>
+</Slider>
+```
+
+### 禁用
+
+禁用整个滑块以禁止交互。
+
+```tsx
+<Slider defaultValue={40} isDisabled>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+## 示例
+
+```tsx
+import { Label, Slider } from 'heroui-native';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+
+export default function SliderExample() {
+  const [price, setPrice] = useState<number[]>([200, 800]);
+
+  return (
+    <View className="px-8 gap-8">
+      <Slider defaultValue={30}>
+        <View className="flex-row items-center justify-between">
+          <Label>Volume</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+
+      <Slider
+        value={price}
+        onChange={setPrice}
+        minValue={0}
+        maxValue={1000}
+        step={10}
+        formatOptions={{ style: 'currency', currency: 'USD' }}
+      >
+        <View className="flex-row items-center justify-between">
+          <Label>Price range</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          {({ state }) => (
+            <>
+              <Slider.Fill />
+              {state.values.map((_, i) => (
+                <Slider.Thumb key={i} index={i} />
+              ))}
+            </>
+          )}
+        </Slider.Track>
+      </Slider>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/slider.tsx>)。
+
+## API 参考
+
+### Slider
+
+| prop            | type                                  | default        | description                                                     |
+| --------------- | ------------------------------------- | -------------- | --------------------------------------------------------------- |
+| `children`      | `React.ReactNode`                     | -              | 滑块内部子元素                                                   |
+| `value`         | `number \| number[]`                  | -              | 当前值（受控）                                                   |
+| `defaultValue`  | `number \| number[]`                  | `0`            | 默认值（非受控）                                                 |
+| `minValue`      | `number`                              | `0`            | 最小值                                                           |
+| `maxValue`      | `number`                              | `100`          | 最大值                                                           |
+| `step`          | `number`                              | `1`            | 步进                                                             |
+| `formatOptions` | `Intl.NumberFormatOptions`            | -              | 数值标签的 `Intl` 格式化选项                                     |
+| `orientation`   | `'horizontal' \| 'vertical'`          | `'horizontal'` | 方向                                                             |
+| `isDisabled`    | `boolean`                             | `false`        | 是否禁用                                                         |
+| `className`     | `string`                              | -              | 额外 class                                                       |
+| `animation`     | `AnimationRootDisableAll`             | -              | 根级动画配置                                                     |
+| `onChange`      | `(value: number \| number[]) => void` | -              | 交互过程中数值变化时触发                                         |
+| `onChangeEnd`   | `(value: number \| number[]) => void` | -              | 交互结束（拖放结束或点击定位）时触发                             |
+| `...ViewProps`  | `ViewProps`                           | -              | 支持 React Native `View` 的全部标准属性                          |
+
+#### AnimationRootDisableAll
+
+滑块根组件动画配置，可为：
+
+- `"disable-all"`：关闭所有动画（含子级）
+- `undefined`：使用默认动画
+
+### Slider.Output
+
+| prop           | type                                                                 | default | description                                                                                 |
+| -------------- | -------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | 自定义内容或接收滑块状态的渲染函数；默认显示格式化数值标签                                   |
+| `className`    | `string`                                                             | -       | 额外 class                                                                                  |
+| `...ViewProps` | `ViewProps`                                                          | -       | 支持 React Native `View` 的全部标准属性                                                    |
+
+#### SliderRenderProps
+
+| prop          | type                | description                    |
+| ------------- | ------------------- | ------------------------------ |
+| `state`       | `SliderState`       | 当前滑块状态                   |
+| `orientation` | `SliderOrientation` | 滑块方向                       |
+| `isDisabled`  | `boolean`           | 是否禁用                       |
+
+#### SliderState
+
+| prop                 | type                        | description                                    |
+| -------------------- | --------------------------- | ---------------------------------------------- |
+| `values`             | `number[]`                  | 按拇指索引的当前数值数组                       |
+| `getThumbValueLabel` | `(index: number) => string` | 返回指定拇指的格式化字符串标签                 |
+
+### Slider.Track
+
+| prop           | type                                                                 | default | description                                                                   |
+| -------------- | -------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | 子内容或接收滑块状态的渲染函数，用于动态渲染多拇指等                           |
+| `className`    | `string`                                                             | -       | 额外 class                                                                    |
+| `hitSlop`      | `number`                                                             | `8`     | 轨道周围扩展点击区域（像素）                                                   |
+| `...ViewProps` | `ViewProps`                                                          | -       | 支持 React Native `View` 的全部标准属性                                       |
+
+### Slider.Fill
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | 额外 class                                         |
+| `...ViewProps` | `ViewProps` | -       | 支持 React Native `View` 的全部标准属性          |
+
+### Slider.Thumb
+
+| prop           | type                                     | default | description                                        |
+| -------------- | ---------------------------------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                        | -       | 自定义拇指内容；默认可动画圆钮                   |
+| `index`        | `number`                                 | `0`     | 该拇指在滑块中的索引                               |
+| `isDisabled`   | `boolean`                                | -       | 是否仅禁用该拇指                                   |
+| `className`    | `string`                                 | -       | 拇指容器额外 class                                 |
+| `classNames`   | `ElementSlots<ThumbSlots>`               | -       | 各拇指插槽的额外 class                             |
+| `styles`       | `Partial<Record<ThumbSlots, ViewStyle>>` | -       | 各拇指插槽的行内样式                               |
+| `hitSlop`      | `number`                                 | `12`    | 拇指周围扩展点击区域（像素）                       |
+| `animation`    | `SliderThumbAnimation`                   | -       | 拇指圆钮动画配置                                   |
+| `...ViewProps` | `ViewProps`                              | -       | 支持 React Native `View` 的全部标准属性          |
+
+#### ElementSlots\<ThumbSlots\>
+
+| prop             | type     | description                     |
+| ---------------- | -------- | ------------------------------- |
+| `thumbContainer` | `string` | 外层拇指容器自定义 class       |
+| `thumbKnob`      | `string` | 内层圆钮自定义 class           |
+
+#### styles
+
+| prop             | type        | description           |
+| ---------------- | ----------- | --------------------- |
+| `thumbContainer` | `ViewStyle` | 外层拇指容器样式      |
+| `thumbKnob`      | `ViewStyle` | 内层圆钮样式          |
+
+#### SliderThumbAnimation
+
+拇指缩放动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭拇指动画
+- `undefined`：使用默认动画
+- `object`：自定义缩放动画
+
+| prop                 | type               | default                                      | description                     |
+| -------------------- | ------------------ | -------------------------------------------- | ------------------------------- |
+| `scale.value`        | `[number, number]` | `[1, 0.9]`                                   | 缩放值 [空闲, 拖拽中]           |
+| `scale.springConfig` | `WithSpringConfig` | `{ damping: 15, stiffness: 200, mass: 0.5 }` | 缩放弹簧配置                    |
+
+## Hooks
+
+### useSlider
+
+访问滑块上下文，须在 `Slider` 内使用。
+
+```tsx
+import { useSlider } from 'heroui-native';
+
+const { values, orientation, isDisabled, getThumbValueLabel } = useSlider();
+```
+
+#### 返回值
+
+| property             | type                                         | description                                                    |
+| -------------------- | -------------------------------------------- | -------------------------------------------------------------- |
+| `values`             | `number[]`                                   | 当前各拇指的数值                                               |
+| `minValue`           | `number`                                     | 最小值                                                         |
+| `maxValue`           | `number`                                     | 最大值                                                         |
+| `step`               | `number`                                     | 步进                                                           |
+| `orientation`        | `'horizontal' \| 'vertical'`                 | 当前方向                                                       |
+| `isDisabled`         | `boolean`                                    | 是否禁用                                                       |
+| `formatOptions`      | `Intl.NumberFormatOptions \| undefined`      | 标签数字格式化选项                                             |
+| `getThumbPercent`    | `(index: number) => number`                  | 返回指定拇指位置百分比（0–1）                                  |
+| `getThumbValueLabel` | `(index: number) => string`                  | 返回指定拇指的格式化标签                                       |
+| `getThumbMinValue`   | `(index: number) => number`                  | 返回指定拇指允许的最小值                                       |
+| `getThumbMaxValue`   | `(index: number) => number`                  | 返回指定拇指允许的最大值                                       |
+| `updateValue`        | `(index: number, newValue: number) => void`  | 按索引更新拇指数值                                             |
+| `isThumbDragging`    | `(index: number) => boolean`                 | 指定拇指是否正在拖拽                                           |
+| `setThumbDragging`   | `(index: number, dragging: boolean) => void` | 设置拇指拖拽状态                                               |
+| `trackSize`          | `number`                                     | 轨道布局宽度（横向）或高度（纵向），单位像素                   |
+| `thumbSize`          | `number`                                     | 已测量的拇指尺寸（主轴方向），单位像素                         |
diff --git a/apps/docs/content/docs/cn/native/components/(controls)/switch.mdx b/apps/docs/content/docs/cn/native/components/(controls)/switch.mdx
new file mode 100644
index 0000000..c317e5e
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(controls)/switch.mdx
@@ -0,0 +1,344 @@
+---
+title: Switch 开关
+description: 在开与关两种状态之间切换的拨动控件。
+links:
+  source_native: switch/switch.tsx
+  styles_native: switch/switch.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Switch } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Switch>
+  <Switch.Thumb>...</Switch.Thumb>
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+- **Switch**：主容器，处理开关状态与用户交互。未提供子节点时渲染默认拇指；根据选中状态对缩放（按压）与背景色做动画；整块可点以切换。
+- **Switch.Thumb**：可选滑动拇指，在位置间移动，弹簧过渡。可放自定义内容（图标等）或通过样式与动画定制。
+- **Switch.StartContent**：可选，显示在开关左侧；常用于关态时的图标或文字；在容器内绝对定位。
+- **Switch.EndContent**：可选，显示在开关右侧；常用于开态时的图标或文字；在容器内绝对定位。
+
+## 用法
+
+### 基础用法
+
+未提供子节点时，Switch 使用默认拇指渲染。
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### 自定义拇指
+
+通过 Thumb 子组件替换默认拇指。
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb>...</Switch.Thumb>
+</Switch>
+```
+
+### 首尾内容
+
+在开关两侧添加图标或文字。
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb />
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+### 渲染函数
+
+根据开关状态用渲染函数动态渲染内容。
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  {({ isSelected, isDisabled }) => (
+    <>
+      <Switch.Thumb>
+        {({ isSelected }) => (isSelected ? <CheckIcon /> : <XIcon />)}
+      </Switch.Thumb>
+    </>
+  )}
+</Switch>
+```
+
+### 自定义动画
+
+为开关根与拇指自定义动画。
+
+```tsx
+<Switch
+  animation={{
+    scale: {
+      value: [1, 0.9],
+      timingConfig: { duration: 200 },
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'],
+    },
+  }}
+>
+  <Switch.Thumb
+    animation={{
+      left: {
+        value: 4,
+        springConfig: {
+          damping: 30,
+          stiffness: 300,
+          mass: 1,
+        },
+      },
+      backgroundColor: {
+        value: ['#dbeafe', '#854d0e'],
+      },
+    }}
+  />
+</Switch>
+```
+
+### 关闭动画
+
+可整体关闭动画，或仅关闭部分组件的动画。
+
+```tsx
+{
+  /* 关闭所有动画（含子级） */
+}
+<Switch animation="disable-all">
+  <Switch.Thumb />
+</Switch>;
+
+{
+  /* 仅关闭根动画，拇指仍可动画 */
+}
+<Switch>
+  <Switch.Thumb animation={false} />
+</Switch>;
+```
+
+## 示例
+
+```tsx
+import { Switch } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { View } from 'react-native';
+import Animated, { ZoomIn } from 'react-native-reanimated';
+
+export default function SwitchExample() {
+  const [darkMode, setDarkMode] = React.useState(false);
+
+  return (
+    <View className="flex-row gap-4">
+      <Switch
+        isSelected={darkMode}
+        onSelectedChange={setDarkMode}
+        className="w-[56px] h-[32px]"
+        animation={{
+          backgroundColor: {
+            value: ['#172554', '#eab308'],
+          },
+        }}
+      >
+        <Switch.Thumb
+          className="size-[22px]"
+          animation={{
+            left: {
+              value: 4,
+              springConfig: {
+                damping: 30,
+                stiffness: 300,
+                mass: 1,
+              },
+            },
+          }}
+        />
+        <Switch.StartContent className="left-2">
+          {darkMode && (
+            <Animated.View key="sun" entering={ZoomIn.springify()}>
+              <Ionicons name="sunny" size={16} color="#854d0e" />
+            </Animated.View>
+          )}
+        </Switch.StartContent>
+        <Switch.EndContent className="right-2">
+          {!darkMode && (
+            <Animated.View key="moon" entering={ZoomIn.springify()}>
+              <Ionicons name="moon" size={16} color="#dbeafe" />
+            </Animated.View>
+          )}
+        </Switch.EndContent>
+      </Switch>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/switch.tsx)。
+
+## API 参考
+
+### Switch
+
+| prop                        | type                                                                 | default     | description                                                  |
+| --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`                  | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | 开关内部内容或渲染函数                                       |
+| `isSelected`                | `boolean`                                                            | `undefined` | 是否选中                                                     |
+| `isDisabled`                | `boolean`                                                            | `false`     | 是否禁用、不可交互                                           |
+| `className`                 | `string`                                                             | `undefined` | 根节点自定义 class                                           |
+| `animation`                 | `SwitchRootAnimation`                                                | -           | 动画配置                                                     |
+| `isAnimatedStyleActive`     | `boolean`                                                            | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `onSelectedChange`          | `(isSelected: boolean) => void`                                      | -           | 选中状态变化时回调                                           |
+| `...AnimatedPressableProps` | `AnimatedProps<PressableProps>`                                      | -           | 支持 Reanimated Pressable 的全部属性                         |
+
+#### SwitchRenderProps
+
+| prop         | type      | description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | 是否选中                       |
+| `isDisabled` | `boolean` | 是否禁用                       |
+
+#### SwitchRootAnimation
+
+Switch 根组件动画配置，可为：
+
+- `false` 或 `"disabled"`：仅关闭根动画
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                           | type                                     | default                                                        | description                                     |
+| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
+| `state`                        | `'disabled' \| 'disable-all' \| boolean` | -                                                              | 关闭动画的同时仍允许自定义属性                  |
+| `scale.value`                  | `[number, number]`                       | `[1, 0.96]`                                                    | 缩放值 [未按压, 按压]                           |
+| `scale.timingConfig`           | `WithTimingConfig`                       | `{ duration: 150 }`                                            | 动画时间配置                                    |
+| `backgroundColor.value`        | `[string, string]`                       | 使用主题色                                                     | 背景色 [未选中, 选中]                           |
+| `backgroundColor.timingConfig` | `WithTimingConfig`                       | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | 背景色过渡时间配置                              |
+
+### Switch.Thumb
+
+| prop                    | type                                                                 | default     | description                                                  |
+| ----------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | 拇指内内容或渲染函数                                         |
+| `className`             | `string`                                                             | `undefined` | 拇指元素自定义 class                                         |
+| `animation`             | `SwitchThumbAnimation`                                               | -           | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                                                            | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `...ViewProps`          | `ViewProps`                                                          | -           | 支持 React Native `View` 的全部标准属性                      |
+
+#### SwitchThumbAnimation
+
+`Switch.Thumb` 动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                           | type                    | default                                                        | description                                                             |
+| ------------------------------ | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `state`                        | `'disabled' \| boolean` | -                                                              | 关闭动画的同时仍允许自定义属性                                          |
+| `left.value`                   | `number`                | `2`                                                            | 距边缘偏移（未选中偏左，选中偏右）                                      |
+| `left.springConfig`            | `WithSpringConfig`      | `{ damping: 120, stiffness: 1600, mass: 2 }`                   | 拇指位置弹簧配置                                                        |
+| `backgroundColor.value`        | `[string, string]`      | `['white', theme accent-foreground color]`                     | 背景色 [未选中, 选中]                                                   |
+| `backgroundColor.timingConfig` | `WithTimingConfig`      | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | 背景色过渡时间配置                                                      |
+
+### Switch.StartContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | 左侧区域内容                                       |
+| `className`    | `string`          | `undefined` | 内容区域自定义 class                               |
+| `...ViewProps` | `ViewProps`       | -           | 支持 React Native `View` 的全部标准属性            |
+
+### Switch.EndContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | 右侧区域内容                                       |
+| `className`    | `string`          | `undefined` | 内容区域自定义 class                               |
+| `...ViewProps` | `ViewProps`       | -           | 支持 React Native `View` 的全部标准属性            |
+
+## Hooks
+
+### useSwitch
+
+用于访问 Switch 上下文，便于在子组件中读取开关状态或封装自定义结构。
+
+**返回值：**
+
+| Property     | Type      | Description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | 是否选中                       |
+| `isDisabled` | `boolean` | 是否禁用                       |
+
+**示例：**
+
+```tsx
+import { useSwitch } from 'heroui-native';
+
+function CustomSwitchContent() {
+  const { isSelected, isDisabled } = useSwitch();
+
+  return (
+    <View>
+      <Text>Status: {isSelected ? 'On' : 'Off'}</Text>
+      {isDisabled && <Text>Disabled</Text>}
+    </View>
+  );
+}
+
+// 用法
+<Switch>
+  <CustomSwitchContent />
+  <Switch.Thumb />
+</Switch>;
+```
+
+## 特别说明
+
+### 边框样式
+
+若需为开关根节点加边框，请使用 `outline` 相关样式而非 `border`，避免影响拇指位置的内部宽度计算：
+
+```tsx
+<Switch className="outline outline-accent">
+  <Switch.Thumb />
+</Switch>
+```
+
+使用 `outline` 可在不改变内部宽度计算的前提下显示边框，确保拇指动画正确。
+
+### 与 ControlField 组合
+
+Switch 可与 ControlField 组合以共享按压态、扩大点击区域：
+
+```tsx
+import { Description, ControlField, Label } from 'heroui-native';
+
+<ControlField isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>Receive push notifications</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+包在 ControlField 内时，整个容器上的按压都会驱动开关，触控目标更大、体验更好。
diff --git a/apps/docs/content/docs/cn/native/components/(data-display)/chip.mdx b/apps/docs/content/docs/cn/native/components/(data-display)/chip.mdx
new file mode 100644
index 0000000..c95c48a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(data-display)/chip.mdx
@@ -0,0 +1,200 @@
+---
+title: Chip 标签
+description: 以胶囊形态展示的小型元素。
+links:
+  source_native: chip/chip.tsx
+  styles_native: chip/chip.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Chip } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Chip>
+  <Chip.Label>...</Chip.Label>
+</Chip>
+```
+
+- **Chip**：主容器，展示紧凑元素
+- **Chip.Label**：芯片上的文字内容
+
+## 用法
+
+### 基础用法
+
+Chip 以胶囊形态展示文字或自定义内容。
+
+```tsx
+<Chip>基础芯片</Chip>
+```
+
+### 尺寸
+
+使用 `size` 控制尺寸。
+
+```tsx
+<Chip size="sm">小</Chip>
+<Chip size="md">中</Chip>
+<Chip size="lg">大</Chip>
+```
+
+### 变体
+
+使用 `variant` 切换视觉风格。
+
+```tsx
+<Chip variant="primary">主要</Chip>
+<Chip variant="secondary">次要</Chip>
+<Chip variant="tertiary">第三级</Chip>
+<Chip variant="soft">柔和</Chip>
+```
+
+### 颜色
+
+使用 `color` 应用不同主题色。
+
+```tsx
+<Chip color="accent">强调</Chip>
+<Chip color="default">默认</Chip>
+<Chip color="success">成功</Chip>
+<Chip color="warning">警告</Chip>
+<Chip color="danger">危险</Chip>
+```
+
+### 搭配图标
+
+通过复合组件在文字旁添加图标或自定义内容。
+
+```tsx
+<Chip>
+  <Icon name="star" size={12} />
+  <Chip.Label>精选</Chip.Label>
+</Chip>
+
+<Chip>
+  <Chip.Label>关闭</Chip.Label>
+  <Icon name="close" size={12} />
+</Chip>
+```
+
+### 自定义样式
+
+通过 `className` 或 `style` 传入样式。
+
+```tsx
+<Chip className="bg-purple-600 px-6">
+  <Chip.Label className="text-white">自定义</Chip.Label>
+</Chip>
+```
+
+### 禁用全部动画
+
+将 `animation` 设为 `"disable-all"` 可禁用自身及子级的全部动画。
+
+```tsx
+{
+  /* 禁用自身及子级的全部动画 */
+}
+<Chip animation="disable-all">无动画</Chip>;
+```
+
+## 示例
+
+```tsx
+import { Chip } from 'heroui-native';
+import { View, Text } from 'react-native';
+import { Ionicons } from '@expo/vector-icons';
+
+export default function ChipExample() {
+  return (
+    <View className="gap-4 p-4">
+      <View className="flex-row flex-wrap gap-2">
+        <Chip size="sm">小</Chip>
+        <Chip size="md">中</Chip>
+        <Chip size="lg">大</Chip>
+      </View>
+
+      <View className="flex-row flex-wrap gap-2">
+        <Chip variant="primary" color="accent">
+          主要
+        </Chip>
+        <Chip variant="secondary" color="success">
+          <View className="size-1.5 rounded-full bg-success" />
+          <Chip.Label>成功</Chip.Label>
+        </Chip>
+        <Chip variant="tertiary" color="warning">
+          <Ionicons name="star" size={12} color="#F59E0B" />
+          <Chip.Label>高级</Chip.Label>
+        </Chip>
+      </View>
+
+      <View className="flex-row gap-2">
+        <Chip variant="secondary">
+          <Chip.Label>移除</Chip.Label>
+          <Ionicons name="close" size={14} color="#6B7280" />
+        </Chip>
+        <Chip className="bg-purple-600">
+          <Chip.Label className="text-white font-semibold">自定义</Chip.Label>
+        </Chip>
+      </View>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/chip.tsx)。
+
+## API 参考
+
+### Chip
+
+| prop                | type                                                          | default     | description                                                                               |
+| ------------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`                                             | -           | 芯片内要渲染的内容                                                                       |
+| `size`              | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | 芯片尺寸                                                                                 |
+| `variant`           | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | `'primary'` | 视觉变体                                                                                 |
+| `color`             | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | 颜色主题                                                                                 |
+| `className`         | `string`                                                      | -           | 额外的 class                                                                             |
+| `animation`         | `"disable-all" \| undefined`                                  | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                     |
+| `...PressableProps` | `PressableProps`                                              | -           | 支持 `Pressable` 的全部属性                                                              |
+
+### Chip.Label
+
+| prop           | type              | default | description                            |
+| -------------- | ----------------- | ------- | -------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 作为标签渲染的文字或内容               |
+| `className`    | `string`          | -       | 额外的 class                           |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性    |
+
+## Hooks
+
+### useChip
+
+访问 Chip 上下文，返回尺寸、变体与颜色。
+
+```tsx
+import { useChip } from 'heroui-native';
+
+const { size, variant, color } = useChip();
+```
+
+#### 返回值
+
+| property  | type                                                          | description |
+| --------- | ------------------------------------------------------------- | ----------- |
+| `size`    | `'sm' \| 'md' \| 'lg'`                                        | 芯片尺寸    |
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | 视觉变体    |
+| `color`   | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | 颜色主题    |
+
+**说明：** 必须在 `Chip` 内使用；在上下文外调用将抛出错误。
diff --git a/apps/docs/content/docs/cn/native/components/(feedback)/alert.mdx b/apps/docs/content/docs/cn/native/components/(feedback)/alert.mdx
new file mode 100644
index 0000000..eb9abc7
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(feedback)/alert.mdx
@@ -0,0 +1,270 @@
+---
+title: Alert 警告
+description: 向用户展示重要消息与通知，并带有状态指示。
+links:
+  source_native: alert/alert.tsx
+  styles_native: alert/alert.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Alert } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>...</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+- **Alert**：根容器，`role="alert"`，按状态应用样式；通过原语上下文向子组件提供状态。
+- **Alert.Indicator**：默认渲染与状态匹配的图标；可传入自定义子节点覆盖；支持 `iconProps` 调整尺寸与颜色。
+- **Alert.Content**：包裹标题与描述，提供文字布局结构。
+- **Alert.Title**：标题文字，颜色随状态变化；通过 `aria-labelledby` 与根关联。
+- **Alert.Description**：正文，弱化色；通过 `aria-describedby` 与根关联。
+
+## 用法
+
+### 基础用法
+
+使用复合子部件展示带图标、标题与描述的通知。
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>新功能已上线</Alert.Title>
+    <Alert.Description>
+      查看最新更新，包括深色模式支持与无障碍改进等。
+    </Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### 状态变体
+
+使用 `status` 控制图标与标题颜色。可选：`default`、`accent`、`success`、`warning`、`danger`。
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>成功</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="warning">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>计划维护</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="danger">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>无法连接</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### 仅标题
+
+省略 `Alert.Description` 以得到紧凑单行提示。
+
+```tsx
+<Alert status="success" className="items-center">
+  <Alert.Indicator className="pt-0" />
+  <Alert.Content>
+    <Alert.Title>资料已成功更新</Alert.Title>
+  </Alert.Content>
+</Alert>
+```
+
+### 操作按钮
+
+在内容旁放置按钮等额外元素。
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>有可用更新</Alert.Title>
+    <Alert.Description>
+      应用有新版本可用。
+    </Alert.Description>
+  </Alert.Content>
+  <Button size="sm" variant="primary">
+    刷新
+  </Button>
+</Alert>
+```
+
+### 自定义指示器
+
+向 `Alert.Indicator` 传入自定义子节点以替换默认状态图标。
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator>
+    <Spinner>
+      <Spinner.Indicator iconProps={{ width: 20, height: 20 }} />
+    </Spinner>
+  </Alert.Indicator>
+  <Alert.Content>
+    <Alert.Title>正在处理请求</Alert.Title>
+    <Alert.Description>请稍候，正在同步您的数据。</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### 自定义样式
+
+在根与各复合部件上使用 `className`。
+
+```tsx
+<Alert className="bg-accent/10 rounded-xl">
+  <Alert.Indicator className="pt-1" />
+  <Alert.Content className="gap-1">
+    <Alert.Title className="text-lg">...</Alert.Title>
+    <Alert.Description className="text-base">...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+## 示例
+
+```tsx
+import { Alert, Button, CloseButton } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function AlertExample() {
+  return (
+    <View className="w-full gap-4">
+      <Alert status="accent">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>有可用更新</Alert.Title>
+          <Alert.Description>
+            应用有新版本。请刷新以获取最新功能与问题修复。
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="primary">
+          刷新
+        </Button>
+      </Alert>
+
+      <Alert status="danger">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>无法连接服务器</Alert.Title>
+          <Alert.Description>
+            无法连接到服务器。请检查网络后重试。
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="danger">
+          重试
+        </Button>
+      </Alert>
+
+      <Alert status="success" className="items-center">
+        <Alert.Indicator className="pt-0" />
+        <Alert.Content>
+          <Alert.Title>资料已成功更新</Alert.Title>
+        </Alert.Content>
+        <CloseButton />
+      </Alert>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/alert.tsx>)。
+
+## API 参考
+
+### Alert
+
+| prop           | type                                                          | default     | description                                                       |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | 渲染在 Alert 内的子节点                                           |
+| `status`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 状态，控制图标与着色                                              |
+| `id`           | `string \| number`                                            | -           | 唯一标识；未提供时自动生成                                       |
+| `className`    | `string`                                                      | -           | 额外的 class                                                      |
+| `style`        | `ViewStyle`                                                   | -           | 根容器额外样式                                                    |
+| `...ViewProps` | `ViewProps`                                                   | -           | 支持 React Native `View` 的全部属性                               |
+
+### Alert.Indicator
+
+| prop           | type              | default | description                                                        |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | 自定义子节点，替代默认状态图标                                     |
+| `className`    | `string`          | -       | 额外的 class                                                       |
+| `iconProps`    | `AlertIconProps`  | -       | 传给默认状态图标的属性（尺寸、颜色等）                             |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                               |
+
+#### AlertIconProps
+
+| prop    | type     | default      | description        |
+| ------- | -------- | ------------ | ------------------ |
+| `size`  | `number` | `18`         | 图标尺寸（像素）   |
+| `color` | `string` | 随状态着色   | 图标颜色字符串     |
+
+### Alert.Content
+
+| prop           | type              | default | description                                                     |
+| -------------- | ----------------- | ------- | --------------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 子节点（通常为 `Alert.Title` 与 `Alert.Description`）           |
+| `className`    | `string`          | -       | 额外的 class                                                    |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                             |
+
+### Alert.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题文字                                           |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+### Alert.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 描述文字                                           |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+## Hooks
+
+### useAlert
+
+访问 Alert 根上下文，必须在 `Alert` 内使用。
+
+```tsx
+import { useAlert } from 'heroui-native';
+
+const { status, nativeID } = useAlert();
+```
+
+#### 返回值
+
+| property   | type                                                          | description                              |
+| ---------- | ------------------------------------------------------------- | ---------------------------------------- |
+| `status`   | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | 当前状态，供子组件样式使用               |
+| `nativeID` | `string`                                                      | 无障碍与 ARIA 使用的唯一标识             |
diff --git a/apps/docs/content/docs/cn/native/components/(feedback)/skeleton-group.mdx b/apps/docs/content/docs/cn/native/components/(feedback)/skeleton-group.mdx
new file mode 100644
index 0000000..63de0cc
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(feedback)/skeleton-group.mdx
@@ -0,0 +1,257 @@
+---
+title: SkeletonGroup 骨架屏组
+description: 协调多个骨架屏占位，并提供统一的动画与加载态控制。
+links:
+  source_native: skeleton-group/skeleton-group.tsx
+  styles_native: skeleton-group/skeleton-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { SkeletonGroup } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<SkeletonGroup>
+  <SkeletonGroup.Item />
+</SkeletonGroup>
+```
+
+- **SkeletonGroup**：根容器，为所有骨架项提供统一控制
+- **SkeletonGroup.Item**：单个骨架项，继承父级组的属性
+
+## 用法
+
+### 基础用法
+
+SkeletonGroup 用共享的加载态与动画管理多个骨架项。
+
+```tsx
+<SkeletonGroup isLoading={isLoading}>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-1/2 rounded-md" />
+</SkeletonGroup>
+```
+
+### 容器布局
+
+在组上使用 `className` 控制骨架项布局。
+
+```tsx
+<SkeletonGroup isLoading={isLoading} className="flex-row items-center gap-3">
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### isSkeletonOnly（纯骨架布局）
+
+当组内仅有骨架与布局用 `View`（加载完成后无真实内容）时，使用 `isSkeletonOnly`。`isLoading` 为 `false` 时整个组会隐藏，避免空容器影响布局。
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  isSkeletonOnly // isLoading 为 false 时隐藏整组
+  className="flex-row items-center gap-3"
+>
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  {/* 该 View 仅用于布局，无加载后内容 */}
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### 动画变体
+
+为组内所有项统一设置动画变体。
+
+```tsx
+<SkeletonGroup isLoading={isLoading} variant="pulse">
+  <SkeletonGroup.Item className="h-10 w-10 rounded-full" />
+  <SkeletonGroup.Item className="h-4 w-32 rounded-md" />
+  <SkeletonGroup.Item className="h-3 w-24 rounded-md" />
+</SkeletonGroup>
+```
+
+### 自定义动画配置
+
+为整组配置 shimmer 或 pulse。
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  <SkeletonGroup.Item className="h-16 w-full rounded-lg" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+### 进出场动画
+
+组出现或消失时应用 Reanimated 过渡。
+
+```tsx
+<SkeletonGroup
+  entering={FadeInLeft}
+  exiting={FadeOutRight}
+  isLoading={isLoading}
+  className="w-full gap-2"
+>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+## 示例
+
+```tsx
+import { Card, SkeletonGroup, Avatar } from 'heroui-native';
+import { useState } from 'react';
+import { Text, View, Image } from 'react-native';
+
+export default function SkeletonGroupExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <SkeletonGroup isLoading={isLoading}>
+      <Card className="p-4">
+        <Card.Header>
+          <View className="flex-row items-center gap-3 mb-4">
+            <SkeletonGroup.Item className="h-10 w-10 rounded-full">
+              <Avatar size="sm" alt="Avatar">
+                <Avatar.Image
+                  source={{ uri: 'https://i.pravatar.cc/150?img=4' }}
+                />
+                <Avatar.Fallback />
+              </Avatar>
+            </SkeletonGroup.Item>
+
+            <View className="flex-1 gap-1">
+              <SkeletonGroup.Item className="h-3 w-32 rounded-md">
+                <Text className="font-semibold text-foreground">John Doe</Text>
+              </SkeletonGroup.Item>
+              <SkeletonGroup.Item className="h-3 w-24 rounded-md">
+                <Text className="text-sm text-muted">@johndoe</Text>
+              </SkeletonGroup.Item>
+            </View>
+          </View>
+
+          <View className="mb-4 gap-1.5">
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                This is the first line of the post content.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                Second line with more interesting content to read.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-2/3 rounded-md">
+              <Text className="text-base text-foreground">
+                Last line is shorter.
+              </Text>
+            </SkeletonGroup.Item>
+          </View>
+        </Card.Header>
+
+        <SkeletonGroup.Item className="h-48 w-full rounded-lg">
+          <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+            <Image
+              source={{
+                uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+              }}
+              className="h-full w-full"
+            />
+          </View>
+        </SkeletonGroup.Item>
+      </Card>
+    </SkeletonGroup>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton-group.tsx)。
+
+## API 参考
+
+### SkeletonGroup
+
+| prop                    | type                             | default     | description                                                            |
+| ----------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -           | `SkeletonGroup.Item` 与布局元素                                        |
+| `isLoading`             | `boolean`                        | `true`      | 骨架项是否处于加载中                                                   |
+| `isSkeletonOnly`        | `boolean`                        | `false`     | 为 `true` 时，`isLoading` 为 `false` 隐藏整组（纯骨架布局）            |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 组内所有项的动画变体                                                   |
+| `animation`             | `SkeletonRootAnimation`          | -           | 动画配置                                                               |
+| `className`             | `string`                         | -           | 组容器额外 class                                                       |
+| `style`                 | `StyleProp<ViewStyle>`           | -           | 组容器自定义样式                                                       |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | 支持 Reanimated `Animated.View` 全部属性                              |
+
+#### SkeletonRootAnimation
+
+SkeletonGroup 动画配置，可为：
+
+- `false` 或 `"disabled"`：仅关闭根动画
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                     | type                                     | default                     | description                                     |
+| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                           | 关闭动画的同时仍允许自定义属性                  |
+| `entering.value`         | `EntryOrExitLayoutType`                  | `FadeIn`                    | 自定义进入动画                                  |
+| `exiting.value`          | `EntryOrExitLayoutType`                  | `FadeOut`                   | 自定义退出动画                                  |
+| `shimmer.duration`       | `number`                                 | `1500`                      | 动画时长（毫秒）                                |
+| `shimmer.speed`          | `number`                                 | `1`                         | 速度倍率                                        |
+| `shimmer.highlightColor` | `string`                                 | -                           | 微光高光色                                      |
+| `shimmer.easing`         | `EasingFunction`                         | `Easing.linear`             | 缓动函数                                        |
+| `pulse.duration`         | `number`                                 | `1000`                      | 动画时长（毫秒）                                |
+| `pulse.minOpacity`       | `number`                                 | `0.5`                       | 最小不透明度                                    |
+| `pulse.maxOpacity`       | `number`                                 | `1`                         | 最大不透明度                                    |
+| `pulse.easing`           | `EasingFunction`                         | `Easing.inOut(Easing.ease)` | 缓动函数                                        |
+
+### SkeletonGroup.Item
+
+| prop                    | type                             | default   | description                                                         |
+| ----------------------- | -------------------------------- | --------- | ------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -         | 非加载态显示的内容                                                  |
+| `isLoading`             | `boolean`                        | 继承组    | 是否加载中（覆盖组设置）                                            |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | 继承组    | 动画变体（覆盖组设置）                                              |
+| `animation`             | `SkeletonRootAnimation`          | 继承组    | 动画配置（覆盖组设置）                                              |
+| `className`             | `string`                         | -         | 单项额外 class                                                      |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -         | 支持 Reanimated `Animated.View` 全部属性                            |
+
+## 特别说明
+
+### 属性继承
+
+`SkeletonGroup.Item` 从父级 `SkeletonGroup` 继承所有与动画相关的属性：
+
+- `isLoading`
+- `variant`
+- `animation`
+
+单项可通过自身属性覆盖继承值。
diff --git a/apps/docs/content/docs/cn/native/components/(feedback)/skeleton.mdx b/apps/docs/content/docs/cn/native/components/(feedback)/skeleton.mdx
new file mode 100644
index 0000000..0d8512f
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(feedback)/skeleton.mdx
@@ -0,0 +1,218 @@
+---
+title: Skeleton 骨架屏
+description: 展示加载占位，支持微光（shimmer）或脉冲（pulse）等动画效果。
+links:
+  source_native: skeleton/skeleton.tsx
+  styles_native: skeleton/skeleton.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Skeleton } from 'heroui-native';
+```
+
+## 结构
+
+Skeleton 为简单包装器，在内容加载时渲染占位，无子部件 API。
+
+```tsx
+<Skeleton />
+```
+
+## 用法
+
+### 基础用法
+
+在内容加载期间显示带动画的占位。
+
+```tsx
+<Skeleton className="h-20 w-full rounded-lg" />
+```
+
+### 与内容切换
+
+加载中显示 Skeleton，就绪后显示真实内容。
+
+```tsx
+<Skeleton isLoading={isLoading} className="h-20 rounded-lg">
+  <View className="h-20 bg-primary rounded-lg">
+    <Text>Loaded Content</Text>
+  </View>
+</Skeleton>
+```
+
+### 动画变体
+
+用 `variant` 控制动画样式。
+
+```tsx
+<Skeleton variant="shimmer" className="h-20 w-full rounded-lg" />
+<Skeleton variant="pulse" className="h-20 w-full rounded-lg" />
+<Skeleton variant="none" className="h-20 w-full rounded-lg" />
+```
+
+### 自定义微光
+
+自定义时长、速度与高光色。
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      speed: 2,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### 自定义脉冲
+
+配置脉冲时长与不透明度范围。
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="pulse"
+  animation={{
+    pulse: {
+      duration: 500,
+      minOpacity: 0.1,
+      maxOpacity: 0.8,
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### 形状变化
+
+通过 `className` 控制占位形状。
+
+```tsx
+<Skeleton className="h-4 w-full rounded-md" />
+<Skeleton className="h-4 w-3/4 rounded-md" />
+<Skeleton className="h-4 w-1/2 rounded-md" />
+<Skeleton className="size-12 rounded-full" />
+```
+
+### 自定义进出场
+
+Skeleton 出现或消失时使用自定义 Reanimated 过渡。
+
+```tsx
+<Skeleton
+  entering={FadeIn.duration(300)}
+  exiting={FadeOut.duration(300)}
+  isLoading={isLoading}
+  className="h-20 w-full rounded-lg"
+>
+  ...
+</Skeleton>
+```
+
+## 示例
+
+```tsx
+import { Avatar, Card, Skeleton } from 'heroui-native';
+import { useState } from 'react';
+import { Image, Text, View } from 'react-native';
+
+export default function SkeletonExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <Card className="p-4">
+      <View className="flex-row items-center gap-3 mb-4">
+        <Skeleton isLoading={isLoading} className="h-10 w-10 rounded-full">
+          <Avatar size="sm" alt="Avatar">
+            <Avatar.Image source={{ uri: 'https://i.pravatar.cc/150?img=4' }} />
+            <Avatar.Fallback />
+          </Avatar>
+        </Skeleton>
+
+        <View className="flex-1 gap-1">
+          <Skeleton isLoading={isLoading} className="h-3 w-32 rounded-md">
+            <Text className="font-semibold text-foreground">John Doe</Text>
+          </Skeleton>
+          <Skeleton isLoading={isLoading} className="h-3 w-24 rounded-md">
+            <Text className="text-sm text-muted">@johndoe</Text>
+          </Skeleton>
+        </View>
+      </View>
+
+      <Skeleton
+        isLoading={isLoading}
+        className="h-48 w-full rounded-lg"
+        animation={{
+          shimmer: {
+            duration: 1500,
+            speed: 1,
+          },
+        }}
+      >
+        <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+          <Image
+            source={{
+              uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+            }}
+            className="h-full w-full"
+          />
+        </View>
+      </Skeleton>
+    </Card>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton.tsx)。
+
+## API 参考
+
+### Skeleton
+
+| prop                    | type                             | default     | description                                                  |
+| ----------------------- | -------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                | -           | 非加载态时显示的内容                                         |
+| `isLoading`             | `boolean`                        | `true`      | 是否处于加载中                                               |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 动画变体                                                     |
+| `animation`             | `SkeletonRootAnimation`          | -           | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                        | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `className`             | `string`                         | -           | 额外样式 class                                               |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | 支持 Reanimated `Animated.View` 的全部属性                  |
+
+#### SkeletonRootAnimation
+
+Skeleton 根动画配置，可为：
+
+- `false` 或 `"disabled"`：仅关闭根动画
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                     | type                                     | default                     | description                                     |
+| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                           | 关闭动画的同时仍允许自定义属性                  |
+| `entering.value`         | `EntryOrExitLayoutType`                  | `FadeIn`                    | 自定义进入动画                                  |
+| `exiting.value`          | `EntryOrExitLayoutType`                  | `FadeOut`                   | 自定义退出动画                                  |
+| `shimmer.duration`       | `number`                                 | `1500`                      | 动画时长（毫秒）                                |
+| `shimmer.speed`          | `number`                                 | `1`                         | 速度倍率                                        |
+| `shimmer.highlightColor` | `string`                                 | -                           | 微光高光色                                      |
+| `shimmer.easing`         | `EasingFunction`                         | `Easing.linear`             | 缓动函数                                        |
+| `pulse.duration`         | `number`                                 | `1000`                      | 动画时长（毫秒）                                |
+| `pulse.minOpacity`       | `number`                                 | `0.5`                       | 最小不透明度                                    |
+| `pulse.maxOpacity`       | `number`                                 | `1`                         | 最大不透明度                                    |
+| `pulse.easing`           | `EasingFunction`                         | `Easing.inOut(Easing.ease)` | 缓动函数                                        |
diff --git a/apps/docs/content/docs/cn/native/components/(feedback)/spinner.mdx b/apps/docs/content/docs/cn/native/components/(feedback)/spinner.mdx
new file mode 100644
index 0000000..d63e5fc
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(feedback)/spinner.mdx
@@ -0,0 +1,209 @@
+---
+title: Spinner 加载指示器
+description: 展示旋转加载动画。
+links:
+  source_native: spinner/spinner.tsx
+  styles_native: spinner/spinner.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Spinner } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Spinner>
+  <Spinner.Indicator>...</Spinner.Indicator>
+</Spinner>
+```
+
+- **Spinner**：主容器，控制加载状态、尺寸与颜色。未提供子节点时渲染默认动画指示器。
+- **Spinner.Indicator**：可选子组件，用于自定义动画配置与图标外观；可传入自定义子节点替换默认图标。
+
+## 用法
+
+### 基础用法
+
+展示旋转加载指示器。
+
+```tsx
+<Spinner />
+```
+
+### 尺寸
+
+使用 `size` 控制大小。
+
+```tsx
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+```
+
+### 颜色
+
+使用预设色或自定义颜色字符串。
+
+```tsx
+<Spinner color="default" />
+<Spinner color="success" />
+<Spinner color="warning" />
+<Spinner color="danger" />
+<Spinner color="#8B5CF6" />
+```
+
+### 加载状态
+
+使用 `isLoading` 控制是否显示。
+
+```tsx
+<Spinner isLoading={true} />
+<Spinner isLoading={false} />
+```
+
+### 动画速度
+
+在 `Indicator` 上使用 `animation` 自定义旋转速度。
+
+```tsx
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 2 } }} />
+</Spinner>
+```
+
+### 自定义图标
+
+用自定义内容替换默认图标。
+
+```tsx
+const themeColorForeground = useThemeColor('foreground')
+
+<Spinner>
+  <Spinner.Indicator>
+    <Ionicons name="refresh" size={24} color={themeColorForeground} />
+  </Spinner.Indicator>
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator>
+    <Text>⏳</Text>
+  </Spinner.Indicator>
+</Spinner>
+```
+
+## 示例
+
+```tsx
+import { Spinner } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { Text, TouchableOpacity, View } from 'react-native';
+
+export default function SpinnerExample() {
+  const [isLoading, setIsLoading] = React.useState(true);
+
+  return (
+    <View className="gap-4 p-4 bg-background">
+      <View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
+        <Spinner size="sm" color="default" />
+        <Text className="text-stone-500">正在加载内容…</Text>
+      </View>
+
+      <View className="items-center p-8 rounded-2xl bg-stone-200">
+        <Spinner size="lg" color="success" isLoading={isLoading} />
+        <Text className="text-stone-500 mt-4">处理中…</Text>
+        <TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
+          <Text className="text-primary mt-2 text-sm">
+            {isLoading ? '点击停止' : '点击开始'}
+          </Text>
+        </TouchableOpacity>
+      </View>
+
+      <View className="flex-row gap-4 items-center justify-center">
+        <Spinner size="md" color="#EC4899">
+          <Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
+            <Ionicons name="refresh" size={24} color="#EC4899" />
+          </Spinner.Indicator>
+        </Spinner>
+      </View>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/spinner.tsx)。
+
+## API 参考
+
+### Spinner
+
+| prop           | type                                                        | default     | description                                        |
+| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                           | `undefined` | 旋转器内部内容                                     |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | 尺寸                                               |
+| `color`        | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | 颜色主题或自定义色值                               |
+| `isLoading`    | `boolean`                                                   | `true`      | 是否处于加载中（显示动画）                         |
+| `className`    | `string`                                                    | `undefined` | 自定义 class                                       |
+| `animation`    | `SpinnerRootAnimation`                                      | -           | 根级动画配置                                       |
+| `...ViewProps` | `ViewProps`                                                 | -           | 支持 React Native `View` 的全部属性                |
+
+#### SpinnerRootAnimation
+
+Spinner 根组件的动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根级动画
+- `"disable-all"`：禁用全部动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                                     | default                                                              | description                       |
+| ---------------- | ---------------------------------------- | -------------------------------------------------------------------- | --------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean` | -                                                                    | 在自定义属性时禁用动画            |
+| `entering.value` | `EntryOrExitLayoutType`                  | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义进入动画                    |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`                                       | 自定义退出动画                    |
+
+### Spinner.Indicator
+
+| prop                    | type                        | default     | description                                                  |
+| ----------------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`           | `undefined` | 指示器内部内容                                               |
+| `iconProps`             | `SpinnerIconProps`          | `undefined` | 默认图标的属性                                               |
+| `className`             | `string`                    | `undefined` | 指示器元素的 class                                           |
+| `animation`             | `SpinnerIndicatorAnimation` | -           | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                   | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `...Animated.ViewProps` | `Animated.ViewProps`        | -           | 支持 Reanimated `Animated.View` 的全部属性                   |
+
+#### SpinnerIndicatorAnimation
+
+`Spinner.Indicator` 的动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop              | type                         | default         | description                       |
+| ----------------- | ---------------------------- | --------------- | --------------------------------- |
+| `state`           | `'disabled' \| boolean`      | -               | 在自定义属性时禁用动画            |
+| `rotation.speed`  | `number`                     | `1.1`           | 旋转速度倍率                      |
+| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | 动画缓动配置                      |
+
+### SpinnerIconProps
+
+| prop     | type               | default          | description |
+| -------- | ------------------ | ---------------- | ----------- |
+| `width`  | `number \| string` | `24`             | 图标宽度    |
+| `height` | `number \| string` | `24`             | 图标高度    |
+| `color`  | `string`           | `'currentColor'` | 图标颜色    |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/checkbox.mdx b/apps/docs/content/docs/cn/native/components/(forms)/checkbox.mdx
new file mode 100644
index 0000000..34e4069
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/checkbox.mdx
@@ -0,0 +1,323 @@
+---
+title: Checkbox 复选框
+description: 可在选中与未选中之间切换的可选控件。
+links:
+  source_native: checkbox/checkbox.tsx
+  styles_native: checkbox/checkbox.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Checkbox } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Checkbox>
+  <Checkbox.Indicator>...</Checkbox.Indicator>
+</Checkbox>
+```
+
+- **Checkbox**：主容器，处理选中状态与用户交互。未提供子节点时渲染带动画对勾的默认指示器；自动识别是否在 Surface 上以便样式正确；支持可定制或关闭的按压缩放动画；子节点可为渲染函数以访问 `isSelected`、`isInvalid`、`isDisabled`。
+- **Checkbox.Indicator**：可选对勾容器，选中时默认带滑动、缩放、透明度与圆角动画；无子节点时渲染带动画路径的 SVG 对勾；各动画可单独配置或关闭；子节点可为渲染函数以访问状态。
+
+## 用法
+
+### 基础用法
+
+未提供子节点时，Checkbox 使用默认动画指示器，并自动检测是否在 Surface 背景上。
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### 自定义指示器
+
+在 Indicator 中使用渲染函数，按状态显示/隐藏自定义图标。
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator>
+    {({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
+  </Checkbox.Indicator>
+</Checkbox>
+```
+
+### 非法状态
+
+使用 `isInvalid` 表示校验错误并应用危险色样式。
+
+```tsx
+<Checkbox
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+  isInvalid={hasError}
+/>
+```
+
+### 自定义动画
+
+为根与指示器分别自定义或关闭动画。
+
+```tsx
+{
+  /* 关闭所有动画（根与指示器） */
+}
+<Checkbox
+  animation="disable-all"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* 仅关闭根动画 */
+}
+<Checkbox
+  animation="disabled"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* 仅关闭指示器动画 */
+}
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator animation="disabled" />
+</Checkbox>;
+
+{
+  /* 自定义动画配置 */
+}
+<Checkbox
+  animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator
+    animation={{
+      scale: { value: [0.5, 1] },
+      opacity: { value: [0, 1] },
+      translateX: { value: [-8, 0] },
+      borderRadius: { value: [12, 0] },
+    }}
+  />
+</Checkbox>;
+```
+
+## 示例
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  ControlField,
+  Label,
+  Separator,
+  Surface,
+} from "heroui-native";
+import React from 'react';
+import { View, Text } from 'react-native';
+
+interface CheckboxFieldProps {
+  isSelected: boolean;
+  onSelectedChange: (value: boolean) => void;
+  title: string;
+  description: string;
+}
+
+const CheckboxField: React.FC<CheckboxFieldProps> = ({
+  isSelected,
+  onSelectedChange,
+  title,
+  description,
+}) => {
+  return (
+    <ControlField isSelected={isSelected} onSelectedChange={onSelectedChange}>
+      <ControlField.Indicator>
+        <Checkbox className="mt-0.5" />
+      </ControlField.Indicator>
+      <View className="flex-1">
+        <Label className="text-lg">{title}</Label>
+        <Description className="text-base">
+          {description}
+        </Description>
+      </View>
+    </ControlField>
+  );
+};
+
+export default function BasicUsage() {
+  const [fields, setFields] = React.useState({
+    newsletter: true,
+    marketing: false,
+    terms: false,
+  });
+
+  const fieldConfigs: Record<
+    keyof typeof fields,
+    { title: string; description: string }
+  > = {
+    newsletter: {
+      title: 'Subscribe to newsletter',
+      description: 'Get weekly updates about new features and tips',
+    },
+    marketing: {
+      title: 'Marketing communications',
+      description: 'Receive promotional emails and special offers',
+    },
+    terms: {
+      title: 'Accept terms and conditions',
+      description: 'Agree to our Terms of Service and Privacy Policy',
+    },
+  };
+
+  const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
+    setFields((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;
+
+  return (
+    <View className="flex-1 items-center justify-center px-5">
+      <Surface className="py-5 w-full">
+        {fieldKeys.map((key, index) => (
+          <React.Fragment key={key}>
+            {index > 0 && <Separator className="my-4" />}
+            <CheckboxField
+              isSelected={fields[key]}
+              onSelectedChange={handleFieldChange(key)}
+              title={fieldConfigs[key].title}
+              description={fieldConfigs[key].description}
+            />
+          </React.Fragment>
+        ))}
+      </Surface>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/checkbox.tsx>)。
+
+## API 参考
+
+### Checkbox
+
+| prop                    | type                                                                   | default     | description                                                               |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | 子元素或用于自定义的渲染函数                                               |
+| `isSelected`            | `boolean`                                                              | `undefined` | 是否选中                                                                  |
+| `onSelectedChange`      | `(isSelected: boolean) => void`                                        | `undefined` | 选中状态变化时回调                                                        |
+| `isDisabled`            | `boolean`                                                              | `false`     | 是否禁用、不可交互                                                        |
+| `isInvalid`             | `boolean`                                                              | `false`     | 是否非法（危险色样式）                                                    |
+| `variant`               | `'primary' \| 'secondary'`                                             | `'primary'` | 视觉变体                                                                  |
+| `hitSlop`               | `number`                                                               | `6`         | 可点区域扩展（hit slop）                                                  |
+| `animation`             | `CheckboxRootAnimation`                                                | -           | 动画配置                                                                  |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | 是否启用 Reanimated 动画样式                                              |
+| `className`             | `string`                                                               | `undefined` | 额外 class                                                                |
+| `...PressableProps`     | `PressableProps`                                                       | -           | 支持 React Native `Pressable` 标准属性（`disabled` 除外）                |
+
+#### CheckboxRenderProps
+
+| prop         | type      | description                      |
+| ------------ | --------- | -------------------------------- |
+| `isSelected` | `boolean` | 是否选中                         |
+| `isInvalid`  | `boolean` | 是否非法                         |
+| `isDisabled` | `boolean` | 是否禁用                         |
+
+#### CheckboxRootAnimation
+
+复选框根组件动画配置，可为：
+
+- `false` 或 `"disabled"`：仅关闭根动画
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                 | type                                     | default             | description                                     |
+| -------------------- | ---------------------------------------- | ------------------- | ----------------------------------------------- |
+| `state`              | `'disabled' \| 'disable-all' \| boolean` | -                   | 关闭动画的同时仍允许自定义属性                  |
+| `scale.value`        | `[number, number]`                       | `[1, 0.96]`         | 缩放值 [未按压, 按压]                           |
+| `scale.timingConfig` | `WithTimingConfig`                       | `{ duration: 150 }` | 动画时间配置                                    |
+
+### Checkbox.Indicator
+
+| prop                    | type                                                                   | default     | description                                                  |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | 指示器内容或渲染函数                                         |
+| `className`             | `string`                                                               | `undefined` | 指示器额外 class                                             |
+| `iconProps`             | `CheckboxIndicatorIconProps`                                           | `undefined` | 默认动画对勾图标的自定义属性                                 |
+| `animation`             | `CheckboxIndicatorAnimation`                                           | -           | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | 是否启用 Reanimated 动画样式                                 |
+| `...AnimatedViewProps`  | `AnimatedProps<ViewProps>`                                             | -           | 支持 React Native Animated View 标准属性                    |
+
+#### CheckboxIndicatorIconProps
+
+用于自定义默认动画对勾图标。
+
+| prop            | type     | description                                      |
+| --------------- | -------- | ------------------------------------------------ |
+| `size`          | `number` | 图标尺寸                                         |
+| `strokeWidth`   | `number` | 描边宽度                                         |
+| `color`         | `string` | 图标颜色（默认为主题 accent-foreground）        |
+| `enterDuration` | `number` | 出现动画时长（对勾显示）                         |
+| `exitDuration`  | `number` | 消失动画时长（对勾隐藏）                         |
+
+#### CheckboxIndicatorAnimation
+
+指示器动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                        | type                    | default             | description                                     |
+| --------------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
+| `state`                     | `'disabled' \| boolean` | -                   | 关闭动画的同时仍允许自定义属性                  |
+| `opacity.value`             | `[number, number]`      | `[0, 1]`            | 透明度 [未选中, 选中]                           |
+| `opacity.timingConfig`      | `WithTimingConfig`      | `{ duration: 100 }` | 透明度动画时间配置                              |
+| `borderRadius.value`        | `[number, number]`      | `[8, 0]`            | 圆角 [未选中, 选中]                             |
+| `borderRadius.timingConfig` | `WithTimingConfig`      | `{ duration: 50 }`  | 圆角动画时间配置                                |
+| `translateX.value`          | `[number, number]`      | `[-4, 0]`           | X 位移 [未选中, 选中]                           |
+| `translateX.timingConfig`   | `WithTimingConfig`      | `{ duration: 100 }` | 位移动画时间配置                                |
+| `scale.value`               | `[number, number]`      | `[0.8, 1]`          | 缩放 [未选中, 选中]                             |
+| `scale.timingConfig`        | `WithTimingConfig`      | `{ duration: 100 }` | 缩放动画时间配置                                |
+
+## Hooks
+
+### useCheckbox
+
+在自定义或复合结构内访问复选框上下文。
+
+```tsx
+import { useCheckbox } from 'heroui-native';
+
+const CustomIndicator = () => {
+  const { isSelected, isInvalid, isDisabled } = useCheckbox();
+  // ... your implementation
+};
+```
+
+**返回值：** `UseCheckboxReturn`
+
+| property           | type                                           | description                                                    |
+| ------------------ | ---------------------------------------------- | -------------------------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | 是否选中                                                       |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 修改选中状态的回调函数                                         |
+| `isDisabled`       | `boolean`                                      | 是否禁用、不可交互                                             |
+| `isInvalid`        | `boolean`                                      | 是否非法（危险色）                                             |
+| `nativeID`         | `string \| undefined`                          | 复选框元素 native ID                                           |
+
+**注意：** 必须在 `Checkbox` 内使用；在上下文外调用会抛错。
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/control-field.mdx b/apps/docs/content/docs/cn/native/components/(forms)/control-field.mdx
new file mode 100644
index 0000000..419aea2
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/control-field.mdx
@@ -0,0 +1,253 @@
+---
+title: ControlField 控件字段
+description: 将标签、说明（或其他内容）与控件（Switch 或 Checkbox）组合为单一可按压区域的字段组件。
+links:
+  source_native: control-field/control-field.tsx
+  styles_native: control-field/control-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { ControlField } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<ControlField>
+  <Label>...</Label>
+  <Description>...</Description>
+  <ControlField.Indicator>...</ControlField.Indicator>
+  <FieldError>...</FieldError>
+</ControlField>
+```
+
+- **ControlField**：根容器，管理布局与状态向下传递
+- **Label**：主标签（来自 [Label](./label)）
+- **Description**：辅助说明（来自 [Description](./description)）
+- **ControlField.Indicator**：表单控件容器（[Switch](./switch)、[Checkbox](./checkbox)、[Radio](./radio)）
+- **FieldError**：校验错误展示（来自 [FieldError](./field-error)）
+
+## 用法
+
+### 基础用法
+
+ControlField 包裹控件，提供一致布局与状态管理。
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <Label className="flex-1">Label text</Label>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### 带说明
+
+在标签下使用 Description 添加辅助说明。
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>
+      Receive push notifications about your account activity
+    </Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### 带错误信息
+
+使用 FieldError 展示校验错误。
+
+```tsx
+<ControlField
+  isSelected={value}
+  onSelectedChange={setValue}
+  isInvalid={!value}
+  className="flex-col items-start gap-1"
+>
+  <View className="flex-row items-center gap-2">
+    <View className="flex-1">
+      <Label>I agree to the terms</Label>
+      <Description>
+        By checking this box, you agree to our Terms of Service
+      </Description>
+    </View>
+    <ControlField.Indicator variant="checkbox" />
+  </View>
+  <FieldError>This field is required</FieldError>
+</ControlField>
+```
+
+### 禁用态
+
+使用 `isDisabled` 控制是否可交互。
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue} isDisabled>
+  <View className="flex-1">
+    <Label>Disabled field</Label>
+    <Description>This field is disabled</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### 关闭所有动画
+
+使用 `"disable-all"` 关闭根及子级全部动画。
+
+```tsx
+<ControlField
+  isSelected={value}
+  onSelectedChange={setValue}
+  animation="disable-all"
+>
+  <View className="flex-1">
+    <Label>Label text</Label>
+    <Description>Description text</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+## 示例
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  FieldError,
+  ControlField,
+  Label,
+  Switch,
+} from 'heroui-native';
+import React from 'react';
+import { ScrollView, View } from 'react-native';
+
+export default function ControlFieldExample() {
+  const [notifications, setNotifications] = React.useState(false);
+  const [terms, setTerms] = React.useState(false);
+  const [newsletter, setNewsletter] = React.useState(true);
+
+  return (
+    <ScrollView className="bg-background p-4">
+      <View className="gap-4">
+        <ControlField
+          isSelected={notifications}
+          onSelectedChange={setNotifications}
+        >
+          <View className="flex-1">
+            <Label>Enable notifications</Label>
+            <Description>
+              Receive push notifications about your account activity
+            </Description>
+          </View>
+          <ControlField.Indicator />
+        </ControlField>
+
+        <ControlField
+          isSelected={terms}
+          onSelectedChange={setTerms}
+          isInvalid={!terms}
+          className="flex-col items-start gap-1"
+        >
+          <View className="flex-row items-center gap-2">
+            <View className="flex-1">
+              <Label>I agree to the terms and conditions</Label>
+              <Description>
+                By checking this box, you agree to our Terms of Service
+              </Description>
+            </View>
+            <ControlField.Indicator className="mt-0.5">
+              <Checkbox />
+            </ControlField.Indicator>
+          </View>
+          <FieldError>This field is required</FieldError>
+        </ControlField>
+
+        <ControlField isSelected={newsletter} onSelectedChange={setNewsletter}>
+          <View className="flex-1">
+            <Label>Subscribe to newsletter</Label>
+          </View>
+          <ControlField.Indicator>
+            <Checkbox color="warning" />
+          </ControlField.Indicator>
+        </ControlField>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/control-field.tsx)。
+
+## API 参考
+
+### ControlField
+
+| prop              | type                                                                       | default     | description                                                                               |
+| ----------------- | -------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children          | `React.ReactNode \| ((props: ControlFieldRenderProps) => React.ReactNode)` | -           | 字段内部内容或渲染函数                                                                     |
+| isSelected        | `boolean`                                                                  | `undefined` | 是否选中/勾选                                                                             |
+| isDisabled        | `boolean`                                                                  | `false`     | 是否禁用                                                                                  |
+| isInvalid         | `boolean`                                                                  | `false`     | 是否非法                                                                                  |
+| isRequired        | `boolean`                                                                  | `false`     | 是否必填                                                                                  |
+| className         | `string`                                                                   | -           | 根元素自定义 class                                                                        |
+| onSelectedChange  | `(isSelected: boolean) => void`                                            | -           | 选中状态变化时回调                                                                        |
+| animation         | `"disable-all" \| undefined`                                               | `undefined` | 动画配置；`"disable-all"` 时关闭根及子级全部动画                                           |
+| ...PressableProps | `PressableProps`                                                           | -           | 支持 React Native Pressable 全部属性                                                      |
+
+### Label
+
+`Label` 会自动消费 ControlField 上下文中的表单状态（`isDisabled`、`isInvalid`）。
+
+**说明**：完整属性见 [Label 组件文档](./label)。
+
+### Description
+
+`Description` 会自动消费 ControlField 上下文中的表单状态（`isDisabled`、`isInvalid`）。
+
+**说明**：完整属性见 [Description 组件文档](./description)。
+
+### ControlField.Indicator
+
+| prop         | type                                | default    | description                                                |
+| ------------ | ----------------------------------- | ---------- | ---------------------------------------------------------- |
+| children     | `React.ReactNode`                   | -          | 要渲染的控件（Switch、Checkbox、Radio）                    |
+| variant      | `'checkbox' \| 'radio' \| 'switch'` | `'switch'` | 未提供 children 时渲染的内置变体                           |
+| className    | `string`                            | -          | 指示器容器自定义 class                                     |
+| ...ViewProps | `ViewProps`                         | -          | 支持 React Native View 全部属性                            |
+
+**说明：** 提供 `children` 时，若子组件上尚未设置，会自动从 ControlField 上下文传入 `isSelected`、`onSelectedChange`、`isDisabled`、`isInvalid`。使用 `radio` 变体时，Radio 以独立模式渲染（不在 RadioGroup 内）。
+
+### FieldError
+
+`FieldError` 会自动消费 ControlField 上下文中的 `isInvalid`。
+
+**说明**：完整属性见 [FieldError 组件文档](./field-error)。显隐由父级 ControlField 的 `isInvalid` 控制。
+
+## Hooks
+
+### useControlField
+
+在 `ControlField` 内访问字段上下文（用于自定义子结构）。
+
+**返回值：**
+
+| property           | type                                           | description                                    |
+| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | 是否选中/勾选                                  |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 选中状态变化回调                               |
+| `isDisabled`       | `boolean`                                      | 是否禁用                                       |
+| `isInvalid`        | `boolean`                                      | 是否非法                                       |
+| `isPressed`        | `SharedValue<boolean>`                         | Reanimated 共享值，表示按压状态                |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/description.mdx b/apps/docs/content/docs/cn/native/components/(forms)/description.mdx
new file mode 100644
index 0000000..f512330
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/description.mdx
@@ -0,0 +1,139 @@
+---
+title: Description 描述
+description: 用于为表单字段等提供无障碍说明与辅助文案的文本组件。
+links:
+  source_native: description/description.tsx
+  styles_native: description/description.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Description } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Description>...</Description>
+```
+
+- **Description**：以弱化样式展示说明或辅助文案；可通过 `nativeID` 与表单字段关联以支持无障碍。
+
+## 用法
+
+### 基础用法
+
+使用默认弱化样式展示说明文字。
+
+```tsx
+<Description>This is a helpful description.</Description>
+```
+
+### 与表单字段组合
+
+使用 `nativeID` 为表单字段提供可关联的说明。
+
+```tsx
+<TextField>
+  <Label>Email address</Label>
+  <Input
+    placeholder="Enter your email"
+    keyboardType="email-address"
+    autoCapitalize="none"
+  />
+  <Description nativeID="email-desc">
+    We'll never share your email with anyone else.
+  </Description>
+</TextField>
+```
+
+### 无障碍关联
+
+通过 `nativeID` 与 `aria-describedby` 将说明与字段关联，便于读屏。
+
+```tsx
+<TextField>
+  <Label>Password</Label>
+  <Input
+    placeholder="Create a password"
+    secureTextEntry
+    aria-describedby="password-desc"
+  />
+  <Description nativeID="password-desc">
+    Use at least 8 characters with a mix of letters, numbers, and symbols.
+  </Description>
+</TextField>
+```
+
+### 非法态时隐藏
+
+使用 `hideOnInvalid` 控制字段非法时是否隐藏说明。
+
+```tsx
+<TextField isInvalid={isInvalid}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description hideOnInvalid>
+    We'll never share your email with anyone else.
+  </Description>
+  <FieldError>Please enter a valid email address</FieldError>
+</TextField>
+```
+
+当 `hideOnInvalid` 为 `true` 时，字段非法会隐藏说明；为 `false`（默认）时非法仍显示说明。
+
+## 示例
+
+```tsx
+import { Description, Input, Label, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function DescriptionExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-8">
+      <TextField>
+        <Label>Email address</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description nativeID="email-desc">
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+      <TextField>
+        <Label>Password</Label>
+        <Input placeholder="Create a password" secureTextEntry />
+        <Description nativeID="password-desc">
+          Use at least 8 characters with a mix of letters, numbers, and symbols.
+        </Description>
+      </TextField>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/description.tsx>)。
+
+## API 参考
+
+### Description
+
+| prop            | type                                | default | description                                                                                |
+| --------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `children`      | `React.ReactNode`                   | -       | 说明文本内容                                                                               |
+| `className`     | `string`                            | -       | 额外 class                                                                                 |
+| `nativeID`      | `string`                            | -       | 无障碍用 native ID，与 `aria-describedby` 等配合关联字段                                   |
+| `isInvalid`     | `boolean`                           | -       | 是否处于非法态（可覆盖上下文）                                                           |
+| `isDisabled`    | `boolean`                           | -       | 是否禁用态（可覆盖上下文）                                                               |
+| `hideOnInvalid` | `boolean`                           | `false` | 非法时是否隐藏说明                                                                       |
+| `animation`     | `DescriptionAnimation \| undefined` | -       | 说明显隐等过渡的动画配置                                                                   |
+| `...TextProps`  | `TextProps`                         | -       | 支持 React Native `Text` 的全部标准属性                                                  |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/field-error.mdx b/apps/docs/content/docs/cn/native/components/(forms)/field-error.mdx
new file mode 100644
index 0000000..cea1cba
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/field-error.mdx
@@ -0,0 +1,214 @@
+---
+title: FieldError 字段错误
+description: 展示校验错误信息，并带有平滑动画。
+links:
+  source_native: field-error/field-error.tsx
+  styles_native: field-error/field-error.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { FieldError } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<FieldError>错误信息内容</FieldError>
+```
+
+- **FieldError**：展示错误信息的主容器，带动画。字符串子节点会自动用 `Text` 包裹，也可传入自定义 React 节点。通过 `isInvalid` 控制显隐，并支持自定义进入/退出动画。
+
+## 用法
+
+### 基础用法
+
+校验失败时展示错误信息。
+
+```tsx
+<FieldError isInvalid={true}>此字段为必填</FieldError>
+```
+
+### 受控显隐
+
+使用 `isInvalid` 控制何时显示。放在 `TextField` 等表单项内时，会自动消费 form-item-state 上下文。
+
+```tsx
+const [isInvalid, setIsInvalid] = useState(false);
+
+<FieldError isInvalid={isInvalid}>请输入有效的邮箱地址</FieldError>;
+```
+
+### 与表单字段配合
+
+`FieldError` 会通过 form-item-state 上下文自动读取 `TextField` 的表单状态。
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>邮箱</Label>
+  <Input placeholder="请输入邮箱" />
+  <FieldError>请输入有效的邮箱地址</FieldError>
+</TextField>
+```
+
+### 自定义内容
+
+子节点可传入自定义 React 组件而非纯字符串。
+
+```tsx
+<FieldError isInvalid={true}>
+  <View className="flex-row items-center">
+    <Icon name="alert-circle" />
+    <Text className="ml-2 text-danger">输入无效</Text>
+  </View>
+</FieldError>
+```
+
+### 自定义动画
+
+使用 `animation` 覆盖默认进入/退出动画。
+
+```tsx
+import { SlideInDown, SlideOutUp } from 'react-native-reanimated';
+
+<FieldError
+  isInvalid={true}
+  animation={{
+    entering: { value: SlideInDown.duration(200) },
+    exiting: { value: SlideOutUp.duration(150) },
+  }}
+>
+  字段校验未通过
+</FieldError>;
+```
+
+完全禁用动画：
+
+```tsx
+<FieldError isInvalid={true} animation={false}>
+  字段校验未通过
+</FieldError>
+```
+
+### 自定义样式
+
+为容器与文字应用自定义样式。
+
+```tsx
+<FieldError
+  isInvalid={true}
+  className="mt-2"
+  classNames={{
+    container: 'bg-danger/10 p-2 rounded',
+    text: 'text-xs font-medium',
+  }}
+>
+  密码至少 8 位
+</FieldError>
+```
+
+### 自定义 Text 属性
+
+当子节点为字符串时，可通过 `textProps` 传给内部 `Text`。
+
+```tsx
+<FieldError
+  isInvalid={true}
+  textProps={{
+    numberOfLines: 1,
+    ellipsizeMode: 'tail',
+    style: { letterSpacing: 0.5 },
+  }}
+>
+  这是一段可能很长需要截断的错误提示文案示例
+</FieldError>
+```
+
+## 示例
+
+```tsx
+import { Description, FieldError, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function FieldErrorExample() {
+  const [email, setEmail] = useState('');
+  const [isInvalid, setIsInvalid] = useState(false);
+
+  const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+  const handleBlur = () => {
+    setIsInvalid(email !== '' && !isValidEmail);
+  };
+
+  return (
+    <View className="p-4">
+      <TextField isInvalid={isInvalid}>
+        <Label>邮箱地址</Label>
+        <Input
+          placeholder="请输入邮箱"
+          value={email}
+          onChangeText={setEmail}
+          onBlur={handleBlur}
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description>
+          我们将通过此邮箱与您联系
+        </Description>
+        <FieldError>请输入有效的邮箱地址</FieldError>
+      </TextField>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/field-error.tsx)。
+
+## API 参考
+
+### FieldError
+
+| prop                   | type                                          | default     | description                                                                                                                                   |
+| ---------------------- | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`             | `React.ReactNode`                             | `undefined` | 错误内容；字符串子节点会用 `Text` 包裹                                                                                                         |
+| `isInvalid`            | `boolean`                                     | `undefined` | 控制是否显示（可覆盖 form-item-state）。置于 `TextField` 内时会自动消费表单状态                                                               |
+| `animation`            | `FieldErrorRootAnimation`                     | -           | 动画配置                                                                                                                                      |
+| `className`            | `string`                                      | `undefined` | 容器的额外 class                                                                                                                              |
+| `classNames`           | `ElementSlots<FieldErrorSlots>`               | `undefined` | 各部分的额外 class                                                                                                                            |
+| `styles`               | `{ container?: ViewStyle; text?: TextStyle }` | `undefined` | 容器与文字的样式                                                                                                                              |
+| `textProps`            | `TextProps`                                   | `undefined` | 子节点为字符串时传给 `Text` 的额外属性                                                                                                        |
+| `...AnimatedViewProps` | `AnimatedProps<ViewProps>`                    | -           | 支持 Reanimated `Animated.View` 的全部属性                                                                                                    |
+
+**classNames：** `ElementSlots<FieldErrorSlots>` 为各部分提供类型安全的 class。可用插槽：`container`、`text`。
+
+#### `styles`
+
+| prop        | type        | description |
+| ----------- | ----------- | ----------- |
+| `container` | `ViewStyle` | 容器样式    |
+| `text`      | `TextStyle` | 文字样式    |
+
+#### FieldErrorRootAnimation
+
+根组件动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根级动画
+- `"disable-all"`：禁用全部动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                                     | default                                                               | description              |
+| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- | ------------------------ |
+| `state`          | `'disabled' \| 'disable-all' \| boolean` | -                                                                     | 在自定义属性时禁用动画   |
+| `entering.value` | `EntryOrExitLayoutType`                  | `FadeIn`<br/>`.duration(150)`<br/>`.easing(Easing.out(Easing.ease))`  | 自定义进入动画           |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义退出动画           |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/input-group.mdx b/apps/docs/content/docs/cn/native/components/(forms)/input-group.mdx
new file mode 100644
index 0000000..5bf34cf
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/input-group.mdx
@@ -0,0 +1,207 @@
+---
+title: InputGroup 输入框组
+description: 复合布局组件，将输入框与可选的前后缀装饰组合在一起。
+links:
+  source_native: input-group/input-group.tsx
+  styles_native: input-group/input-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { InputGroup } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix>...</InputGroup.Prefix>
+  <InputGroup.Input />
+  <InputGroup.Suffix>...</InputGroup.Suffix>
+</InputGroup>
+```
+
+- **InputGroup**：布局容器，包裹前缀、输入与后缀；提供动画设置与测量上下文，自动将前后缀宽度应用为 `Input` 的内边距。
+- **InputGroup.Prefix**：绝对定位在输入左侧；测量宽度自动作为 `InputGroup.Input` 的 `paddingLeft`。
+- **InputGroup.Suffix**：绝对定位在输入右侧；测量宽度自动作为 `InputGroup.Input` 的 `paddingRight`。
+- **InputGroup.Input**：透传至 `Input`，支持全部 `Input` 属性，并自动获得前后缀对应的左右内边距。
+
+## 用法
+
+### 基础用法
+
+通过复合子部件为输入框附加前后缀内容。
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix>...</InputGroup.Prefix>
+  <InputGroup.Input placeholder="请输入" />
+  <InputGroup.Suffix>...</InputGroup.Suffix>
+</InputGroup>
+```
+
+### 仅前缀
+
+在输入前附加图标等内容。
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix isDecorative>
+    <PersonIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="用户名" />
+</InputGroup>
+```
+
+### 仅后缀
+
+在输入后附加图标等内容。
+
+```tsx
+<InputGroup>
+  <InputGroup.Input placeholder="搜索商品…" />
+  <InputGroup.Suffix isDecorative>
+    <MagnifierIcon size={16} />
+  </InputGroup.Suffix>
+</InputGroup>
+```
+
+### 装饰性与可交互
+
+在 `Prefix`/`Suffix` 上设置 `isDecorative` 时，触摸事件会穿透到 `Input`，且对读屏隐藏装饰内容；包含可交互元素时不要设置。
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix isDecorative>
+    <LockIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="请输入密码" secureTextEntry />
+  <InputGroup.Suffix>
+    <Pressable onPress={togglePasswordVisibility}>
+      <EyeIcon size={16} />
+    </Pressable>
+  </InputGroup.Suffix>
+</InputGroup>
+```
+
+### 禁用状态
+
+禁用整个输入组，状态会级联到子组件。
+
+```tsx
+<InputGroup isDisabled>
+  <InputGroup.Prefix isDecorative>
+    <LockIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="已禁用" />
+</InputGroup>
+```
+
+### 与 TextField 组合
+
+与 `TextField`、`Label`、`Description` 等组合成完整表单项。
+
+```tsx
+<TextField isRequired>
+  <Label>邮箱</Label>
+  <InputGroup>
+    <InputGroup.Prefix isDecorative>
+      <MailIcon size={16} />
+    </InputGroup.Prefix>
+    <InputGroup.Input placeholder="you@example.com" keyboardType="email-address" />
+  </InputGroup>
+  <Description>我们不会公开您的邮箱</Description>
+</TextField>
+```
+
+## 示例
+
+```tsx
+import { InputGroup } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+
+export default function InputGroupExample() {
+  const [value, setValue] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="px-5">
+      <InputGroup>
+        <InputGroup.Prefix isDecorative>
+          <Ionicons name="lock-closed-outline" size={16} color="#888" />
+        </InputGroup.Prefix>
+        <InputGroup.Input
+          value={value}
+          onChangeText={setValue}
+          placeholder="请输入密码"
+          secureTextEntry={!isPasswordVisible}
+        />
+        <InputGroup.Suffix>
+          <Pressable
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+            hitSlop={20}
+          >
+            <Ionicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              color="#888"
+            />
+          </Pressable>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-group.tsx>)。
+
+## API 参考
+
+### InputGroup
+
+| prop           | type                     | default | description                                                                  |
+| -------------- | ------------------------ | ------- | ---------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`        | -       | 组内子节点                                                                   |
+| `className`    | `string`                 | -       | 额外的 class                                                                 |
+| `isDisabled`   | `boolean`                | `false` | 是否禁用整个输入组及子级                                                     |
+| `animation`    | `AnimationRootDisableAll`| -       | 输入组动画配置                                                               |
+| `...ViewProps` | `ViewProps`              | -       | 支持 React Native `View` 的全部属性                                          |
+
+#### AnimationRootDisableAll
+
+根组件动画配置，可为：
+
+- `"disable-all"`：禁用全部动画（含子级，级联）
+- `undefined`：使用默认动画
+
+### InputGroup.Prefix
+
+| prop             | type              | default | description                                                                                  |
+| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `children`       | `React.ReactNode` | -       | 前缀区域内容                                                                                 |
+| `className`      | `string`          | -       | 额外的 class                                                                                 |
+| `isDecorative`   | `boolean`         | `false` | 为 true 时触摸穿透到 `Input`，且对读屏隐藏                                                   |
+| `...ViewProps`   | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                                                          |
+
+### InputGroup.Suffix
+
+| prop             | type              | default | description                                                                                  |
+| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `children`       | `React.ReactNode` | -       | 后缀区域内容                                                                                 |
+| `className`      | `string`          | -       | 额外的 class                                                                                 |
+| `isDecorative`   | `boolean`         | `false` | 为 true 时触摸穿透到 `Input`，且对读屏隐藏                                                   |
+| `...ViewProps`   | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                                                          |
+
+### InputGroup.Input
+
+透传至 [Input](./input) 组件，支持其全部属性。
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/input-otp.mdx b/apps/docs/content/docs/cn/native/components/(forms)/input-otp.mdx
new file mode 100644
index 0000000..f305f5c
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/input-otp.mdx
@@ -0,0 +1,415 @@
+---
+title: InputOTP 一次性密码输入框
+description: 用于输入一次性验证码（OTP）的输入组件，支持分格、动画与校验。
+links:
+  source_native: input-otp/input-otp.tsx
+  styles_native: input-otp/input-otp.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { InputOTP } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<InputOTP>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={2}>
+      <InputOTP.SlotPlaceholder />
+      <InputOTP.SlotValue />
+      <InputOTP.SlotCaret />
+    </InputOTP.Slot>
+  </InputOTP.Group>
+</InputOTP>
+```
+
+- **InputOTP**：根容器，管理 OTP 状态与文本变更，并为子组件提供上下文；处理焦点、校验与字符输入。
+- **InputOTP.Group**：将多个格子编组；用于视觉分组（例如每 3 位一组）。
+- **InputOTP.Slot**：单个字符格；`index` 须在 OTP 序列中唯一且与位置对应。未提供子节点时，默认渲染 `SlotPlaceholder`、`SlotValue` 与 `SlotCaret`。
+- **InputOTP.SlotPlaceholder**：空位时显示的占位字符；`Slot` 无子节点时默认使用。
+- **InputOTP.SlotValue**：显示已输入字符并带动画；`Slot` 无子节点时默认使用。
+- **InputOTP.SlotCaret**：动画光标，指示当前输入位置；置于 `Slot` 内以显示正在输入的位置。
+- **InputOTP.Separator**：分组之间的视觉分隔符。
+
+## 用法
+
+### 基础用法
+
+创建 6 位 OTP，分两组并带分隔符。
+
+```tsx
+<InputOTP maxLength={6} onComplete={(code) => console.log(code)}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### 四位 PIN
+
+简单的 4 位数字 PIN。
+
+```tsx
+<InputOTP maxLength={4} onComplete={(code) => console.log(code)}>
+  <InputOTP.Slot index={0} />
+  <InputOTP.Slot index={1} />
+  <InputOTP.Slot index={2} />
+  <InputOTP.Slot index={3} />
+</InputOTP>
+```
+
+### 自定义占位
+
+为每个格子位置提供自定义占位字符。
+
+```tsx
+<InputOTP
+  maxLength={6}
+  placeholder="——————"
+  onComplete={(code) => console.log(code)}
+>
+  <InputOTP.Group>
+    {({ slots }) => (
+      <>
+        {slots.map((slot) => (
+          <InputOTP.Slot key={slot.index} index={slot.index} />
+        ))}
+      </>
+    )}
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### 受控值
+
+以编程方式控制 OTP 值。
+
+```tsx
+const [value, setValue] = useState('');
+
+<InputOTP value={value} onChange={setValue} maxLength={6}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>;
+```
+
+### 校验态
+
+非法时展示校验错误样式。
+
+```tsx
+<InputOTP value={value} onChange={setValue} maxLength={6} isInvalid={isInvalid}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### 输入模式（正则）
+
+使用正则限制可输入字符。内置：`REGEXP_ONLY_DIGITS`（0–9）、`REGEXP_ONLY_CHARS`（a–z、A–Z）、`REGEXP_ONLY_DIGITS_AND_CHARS`（数字与字母）。
+
+```tsx
+import { InputOTP, REGEXP_ONLY_CHARS } from 'heroui-native';
+
+<InputOTP
+  maxLength={6}
+  pattern={REGEXP_ONLY_CHARS}
+  inputMode="text"
+  onComplete={(code) => console.log(code)}
+>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>;
+```
+
+### 自定义布局
+
+在 `Group` 上使用渲染属性以自定义格子布局。
+
+```tsx
+<InputOTP maxLength={6}>
+  <InputOTP.Group>
+    {({ slots, isFocused, isInvalid }) => (
+      <>
+        {slots.map((slot) => (
+          <InputOTP.Slot
+            key={slot.index}
+            index={slot.index}
+            className={cn('custom-class', slot.isActive && 'active-class')}
+          >
+            <InputOTP.SlotPlaceholder />
+            <InputOTP.SlotValue />
+            <InputOTP.SlotCaret />
+          </InputOTP.Slot>
+        ))}
+      </>
+    )}
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### 在底部抽屉内
+
+在 `BottomSheet` 中渲染 `InputOTP` 时，使用 `useBottomSheetAwareHandlers` 返回的 `onFocus` / `onBlur` 传给 `InputOTP`，以正确处理键盘避让。
+
+```tsx
+import { InputOTP, useBottomSheetAwareHandlers } from 'heroui-native';
+
+const BottomSheetOTPInput = () => {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return (
+    <InputOTP maxLength={6} onFocus={onFocus} onBlur={onBlur}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+      </InputOTP.Group>
+      <InputOTP.Separator />
+      <InputOTP.Group>
+        <InputOTP.Slot index={3} />
+        <InputOTP.Slot index={4} />
+        <InputOTP.Slot index={5} />
+      </InputOTP.Group>
+    </InputOTP>
+  );
+};
+```
+
+## 示例
+
+```tsx
+import { InputOTP, Label, Description, type InputOTPRef } from 'heroui-native';
+import { View } from 'react-native';
+import { useRef } from 'react';
+
+export default function InputOTPExample() {
+  const ref = useRef<InputOTPRef>(null);
+
+  const onComplete = (code: string) => {
+    console.log('OTP completed:', code);
+    setTimeout(() => {
+      ref.current?.clear();
+    }, 1000);
+  };
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View>
+        <Label>验证账户</Label>
+        <Description className="mb-3">
+          我们已向 a****@gmail.com 发送验证码
+        </Description>
+        <InputOTP ref={ref} maxLength={6} onComplete={onComplete}>
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </View>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-otp.tsx)。
+
+## API 参考
+
+### InputOTP
+
+| prop                       | type                          | default     | description                                                                                |
+| -------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| `maxLength`                | `number`                      | -           | OTP 最大长度（必填）                                                                       |
+| `value`                    | `string`                      | -           | 受控值                                                                                     |
+| `defaultValue`             | `string`                      | -           | 非受控默认值                                                                               |
+| `onChange`                 | `(value: string) => void`     | -           | 值变化回调                                                                                 |
+| `onComplete`               | `(value: string) => void`     | -           | 所有格子填满时触发                                                                         |
+| `isDisabled`               | `boolean`                     | `false`     | 是否禁用                                                                                   |
+| `isInvalid`                | `boolean`                     | `false`     | 是否处于非法状态                                                                           |
+| `pattern`                  | `string`                      | -           | 允许字符的正则（如 `REGEXP_ONLY_DIGITS`、`REGEXP_ONLY_CHARS`）                             |
+| `inputMode`                | `TextInputProps['inputMode']` | `'numeric'` | 输入模式                                                                                   |
+| `placeholder`              | `string`                      | -           | 占位字符串；每个字符对应一个格子位置                                                       |
+| `placeholderTextColor`     | `string`                      | -           | 全部格子的占位文字颜色                                                                     |
+| `placeholderTextClassName` | `string`                      | -           | 全部格子的占位文字 class                                                                   |
+| `pasteTransformer`         | `(text: string) => string`    | -           | 粘贴内容转换（如去掉连字符）；默认会移除非匹配字符                                         |
+| `onFocus`                  | `(e: FocusEvent) => void`     | -           | 聚焦回调                                                                                   |
+| `onBlur`                   | `(e: BlurEvent) => void`      | -           | 失焦回调                                                                                   |
+| `textInputProps`           | `Omit<TextInputProps, ...>`   | -           | 透传给底层 `TextInput` 的额外属性                                                          |
+| `children`                 | `React.ReactNode`             | -           | 子节点                                                                                     |
+| `className`                | `string`                      | -           | 根容器额外 class                                                                           |
+| `style`                    | `PressableProps['style']`     | -           | 传给容器 `Pressable` 的样式                                                                |
+| `isBottomSheetAware`       | `boolean`                     | `true`      | 在 `BottomSheet` 内是否自动处理键盘相关状态；设为 `false` 可关闭                           |
+| `animation`                | `"disable-all" \| undefined`  | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级全部动画                                         |
+
+### InputOTP.Group
+
+| prop           | type                                                                        | default | description                                                                                                              |
+| -------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `children`     | `React.ReactNode \| ((props: InputOTPGroupRenderProps) => React.ReactNode)` | -       | 子节点，或接收格子数据与上下文的渲染函数                                                                                 |
+| `className`    | `string`                                                                    | -       | 额外 class                                                                                                               |
+| `...ViewProps` | `ViewProps`                                                                 | -       | 支持全部标准 React Native `View` 属性                                                                                    |
+
+#### InputOTPGroupRenderProps
+
+| prop         | type         | description                              |
+| ------------ | ------------ | ---------------------------------------- |
+| `slots`      | `SlotData[]` | 每个位置的格子数据数组                   |
+| `maxLength`  | `number`     | OTP 最大长度                             |
+| `value`      | `string`     | 当前 OTP 值                              |
+| `isFocused`  | `boolean`    | 是否聚焦                                 |
+| `isDisabled` | `boolean`    | 是否禁用                                 |
+| `isInvalid`  | `boolean`    | 是否非法                                 |
+
+### InputOTP.Slot
+
+| prop           | type              | default | description                                                                                 |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `index`        | `number`          | -       | 格子下标（必填），须为 `0` 到 `maxLength - 1`                                               |
+| `children`     | `React.ReactNode` | -       | 自定义格子内容；未提供时默认为 `SlotPlaceholder`、`SlotValue`、`SlotCaret`                  |
+| `className`    | `string`          | -       | 额外 class                                                                                  |
+| `style`        | `ViewStyle`       | -       | 额外样式                                                                                    |
+| `...ViewProps` | `ViewProps`       | -       | 支持全部标准 React Native `View` 属性                                                     |
+
+### InputOTP.SlotPlaceholder
+
+| prop           | type        | default | description                                                          |
+| -------------- | ----------- | ------- | -------------------------------------------------------------------- |
+| `children`     | `string`    | -       | 显示文本（可选，默认使用 `slot.placeholderChar`）                    |
+| `className`    | `string`    | -       | 额外 class                                                           |
+| `style`        | `TextStyle` | -       | 额外样式                                                             |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性                              |
+
+### InputOTP.SlotValue
+
+| prop           | type                         | default | description                                               |
+| -------------- | ---------------------------- | ------- | --------------------------------------------------------- |
+| `children`     | `string`                     | -       | 显示文本（可选，默认使用 `slot.char`）                    |
+| `className`    | `string`                     | -       | 额外 class                                                |
+| `animation`    | `InputOTPSlotValueAnimation` | -       | `SlotValue` 动画配置                                      |
+| `...TextProps` | `TextProps`                  | -       | 支持全部标准 React Native `Text` 属性                     |
+
+#### InputOTPSlotValueAnimation
+
+`InputOTP.SlotValue` 动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop               | type                    | default                                  | description                                     |
+| ------------------ | ----------------------- | ---------------------------------------- | ----------------------------------------------- |
+| `state`            | `'disabled' \| boolean` | -                                        | 在自定义属性时用于禁用动画                      |
+| `wrapper.entering` | `EntryOrExitLayoutType` | `FadeIn.duration(250)`                   | 包裹层进入动画                                  |
+| `wrapper.exiting`  | `EntryOrExitLayoutType` | `FadeOut.duration(100)`                  | 包裹层退出动画                                  |
+| `text.entering`    | `EntryOrExitLayoutType` | `FlipInXDown.duration(250).easing(...)`  | 文本进入动画                                    |
+| `text.exiting`     | `EntryOrExitLayoutType` | `FlipOutXDown.duration(250).easing(...)` | 文本退出动画                                    |
+
+### InputOTP.SlotCaret
+
+| prop                    | type                         | default  | description                                                                                                                                  |
+| ----------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`             | `string`                     | -        | 额外 class                                                                                                                                   |
+| `style`                 | `ViewStyle`                  | -        | 额外样式                                                                                                                                     |
+| `animation`             | `InputOTPSlotCaretAnimation` | -        | `SlotCaret` 动画配置                                                                                                                          |
+| `isAnimatedStyleActive` | `boolean`                    | `true`   | 是否启用 Reanimated 动画样式；为 `false` 时移除内置动画样式，可自行实现                                                                      |
+| `pointerEvents`         | `'none' \| 'auto' \| ...`    | `'none'` | 指针事件配置                                                                                                                                 |
+| `...ViewProps`          | `ViewProps`                  | -        | 支持全部标准 React Native `View` 属性                                                                                                        |
+
+#### InputOTPSlotCaretAnimation
+
+`InputOTP.SlotCaret` 动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop               | type                    | default    | description                                     |
+| ------------------ | ----------------------- | ---------- | ----------------------------------------------- |
+| `state`            | `'disabled' \| boolean` | -          | 在自定义属性时用于禁用动画                      |
+| `opacity.value`    | `[number, number]`      | `[0, 1]`   | 透明度 [最小, 最大]                             |
+| `opacity.duration` | `number`                | `500`      | 动画时长（毫秒）                                |
+| `height.value`     | `[number, number]`      | `[16, 18]` | 高度 [最小, 最大]（像素）                       |
+| `height.duration`  | `number`                | `500`      | 动画时长（毫秒）                                |
+
+### InputOTP.Separator
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | 额外 class                                         |
+| `...ViewProps` | `ViewProps` | -       | 支持全部标准 React Native `View` 属性              |
+
+## Hooks
+
+### useInputOTP
+
+读取 `InputOTP` 根上下文，须在 `InputOTP` 内使用。
+
+```tsx
+const { value, maxLength, isFocused, isDisabled, isInvalid, slots } =
+  useInputOTP();
+```
+
+### useInputOTPSlot
+
+读取 `InputOTP.Slot` 上下文，须在 `InputOTP.Slot` 内使用。
+
+```tsx
+const { slot, isActive, isCaretVisible } = useInputOTPSlot();
+```
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/input.mdx b/apps/docs/content/docs/cn/native/components/(forms)/input.mdx
new file mode 100644
index 0000000..c001a20
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/input.mdx
@@ -0,0 +1,226 @@
+---
+title: Input 输入框
+description: 单行文本输入，带样式边框与背景，用于收集用户输入。
+links:
+  source_native: input/input.tsx
+  styles_native: input/input.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Input } from 'heroui-native';
+```
+
+## 用法
+
+### 基础用法
+
+`Input` 可单独使用，也可放在 `TextField` 内。
+
+```tsx
+import { Input } from 'heroui-native';
+
+<Input placeholder="请输入邮箱" />;
+```
+
+### 与 TextField 组合
+
+与 `TextField` 搭配形成完整表单结构。
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>邮箱</Label>
+  <Input placeholder="请输入邮箱" />
+</TextField>;
+```
+
+### 校验状态
+
+非法时展示错误样式。
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>邮箱</Label>
+  <Input placeholder="请输入邮箱" />
+  <FieldError>请输入有效邮箱</FieldError>
+</TextField>;
+```
+
+### 局部覆盖非法状态
+
+在输入上覆盖上下文中的非法状态。
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isInvalid={true}>
+  <Label isInvalid={false}>邮箱</Label>
+  <Input placeholder="请输入邮箱" isInvalid={false} />
+  <FieldError>邮箱格式不正确</FieldError>
+</TextField>;
+```
+
+### 禁用状态
+
+禁用输入，阻止交互。
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField isDisabled>
+  <Label>禁用字段</Label>
+  <Input placeholder="不可编辑" value="只读内容" />
+</TextField>;
+```
+
+### 变体
+
+按场景使用不同视觉变体。
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>主要变体</Label>
+  <Input placeholder="主要样式" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>次要变体</Label>
+  <Input placeholder="次要样式" variant="secondary" />
+</TextField>
+```
+
+### 自定义样式
+
+通过 `className` 自定义外观。
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>自定义样式</Label>
+  <Input
+    placeholder="自定义颜色"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>;
+```
+
+### 在 Bottom Sheet 内
+
+在 `BottomSheet` 中渲染 `Input` 时，使用 `useBottomSheetAwareHandlers` 连接键盘避让：将返回的 `onFocus`、`onBlur` 传给 `Input`。
+
+```tsx
+import { Input, TextField, useBottomSheetAwareHandlers } from 'heroui-native';
+
+const BottomSheetTextInput = () => {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return (
+    <TextField>
+      <Input
+        placeholder="在此输入…"
+        onFocus={onFocus}
+        onBlur={onBlur}
+      />
+    </TextField>
+  );
+};
+```
+
+## 示例
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Description, Input, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export const TextInputContent = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="gap-4">
+      <TextField isRequired>
+        <Label>邮箱</Label>
+        <Input
+          placeholder="请输入邮箱"
+          keyboardType="email-address"
+          autoCapitalize="none"
+          value={email}
+          onChangeText={setEmail}
+        />
+        <Description>
+          我们不会向他人公开您的邮箱。
+        </Description>
+      </TextField>
+
+      <TextField isRequired>
+        <Label>新密码</Label>
+        <View className="w-full flex-row items-center">
+          <Input
+            value={password}
+            onChangeText={setPassword}
+            className="flex-1 px-10"
+            placeholder="请输入密码"
+            secureTextEntry={!isPasswordVisible}
+          />
+          <StyledIonicons
+            name="lock-closed-outline"
+            size={16}
+            className="absolute left-3.5 text-muted"
+            pointerEvents="none"
+          />
+          <Pressable
+            className="absolute right-4"
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+          >
+            <StyledIonicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              className="text-muted"
+            />
+          </Pressable>
+        </View>
+        <Description>密码至少 6 位</Description>
+      </TextField>
+    </View>
+  );
+};
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input.tsx)。
+
+## API 参考
+
+### Input
+
+| prop                      | type                       | default               | description                                                  |
+| ------------------------- | -------------------------- | --------------------- | ------------------------------------------------------------ |
+| isInvalid                 | `boolean`                  | `undefined`           | 是否非法（可覆盖上下文）                                     |
+| variant                   | `'primary' \| 'secondary'` | `'primary'`           | 输入框视觉变体                                               |
+| className                 | `string`                   | -                     | 自定义 class                                                 |
+| selectionColorClassName   | `string`                   | `"accent-accent"`     | 选中文本颜色的 class                                         |
+| placeholderColorClassName | `string`                   | `"field-placeholder"` | 占位符文字颜色的 class                                       |
+| isBottomSheetAware        | `boolean`                  | `true`                | 在 BottomSheet 内是否自动处理键盘相关逻辑；设为 `false` 可关闭 |
+| animation                 | `AnimationRoot`            | `undefined`           | 输入框动画配置                                               |
+| ...TextInputProps         | `TextInputProps`           | -                     | 支持 React Native `TextInput` 的全部属性                     |
+
+> **说明**：置于 `TextField` 内时，`Input` 会通过 form-item-state 上下文自动消费 `isDisabled`、`isInvalid` 等表单状态。
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/label.mdx b/apps/docs/content/docs/cn/native/components/(forms)/label.mdx
new file mode 100644
index 0000000..1e0739f
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/label.mdx
@@ -0,0 +1,197 @@
+---
+title: Label 标签
+description: 用于标注表单字段等 UI 的文本组件，支持必填标记与校验状态。
+links:
+  source_native: label/label.tsx
+  styles_native: label/label.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Label } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Label>
+  <Label.Text>...</Label.Text>
+</Label>
+```
+
+- **Label**：根容器，管理标签状态并为子组件提供上下文。传入字符串子节点时会自动渲染为 `Label.Text`。支持禁用、必填与非法状态。
+- **Label.Text**：标签文字；在必填时自动显示星号，非法或禁用时改变颜色。
+
+## 用法
+
+### 基础用法
+
+展示标签文字。字符串子节点会自动渲染为 `Label.Text`。
+
+```tsx
+<Label>用户名</Label>
+```
+
+### 与表单字段配合
+
+将 `Label` 与表单字段组合以提供无障碍标签。
+
+```tsx
+<TextField>
+  <Label>用户名</Label>
+  <Input placeholder="请输入用户名" />
+</TextField>
+```
+
+### 必填字段
+
+使用 `isRequired` 显示必填星号。
+
+```tsx
+<TextField>
+  <Label isRequired>密码</Label>
+  <Input placeholder="创建密码" secureTextEntry />
+</TextField>
+```
+
+### 非法状态
+
+在校验失败时使用非法样式突出标签。
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+
+<TextField isInvalid>
+  <Label isInvalid>确认密码</Label>
+  <Input
+    placeholder="再次输入密码"
+    secureTextEntry
+    value="different"
+    editable={false}
+  />
+  <FieldError>两次密码不一致</FieldError>
+</TextField>
+```
+
+### 禁用状态
+
+禁用标签以表示字段不可交互。
+
+```tsx
+<TextField isDisabled>
+  <Label>订阅方案</Label>
+  <Input value="Premium" />
+</TextField>
+```
+
+### 自定义布局
+
+使用复合子组件自定义标签结构。
+
+```tsx
+<Label>
+  <Label.Text>自定义标签</Label.Text>
+</Label>
+```
+
+### 自定义样式
+
+通过 `className`、`classNames` 或 `styles` 传入样式。
+
+```tsx
+<Label className="mb-2">
+  <Label.Text
+    className="text-lg"
+    classNames={{
+      text: "font-bold",
+      asterisk: "text-danger"
+    }}
+  >
+    自定义样式标签
+  </Label.Text>
+</Label>
+```
+
+## 示例
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function LabelExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-8">
+      <TextField>
+        <Label>用户名</Label>
+        <Input placeholder="请输入用户名" />
+      </TextField>
+      <TextField>
+        <Label isRequired>密码</Label>
+        <Input placeholder="创建密码" secureTextEntry />
+      </TextField>
+      <TextField isInvalid>
+        <Label isInvalid>确认密码</Label>
+        <Input
+          placeholder="再次输入密码"
+          secureTextEntry
+          value="different"
+          editable={false}
+        />
+        <FieldError>两次密码不一致</FieldError>
+      </TextField>
+      <TextField isDisabled>
+        <Label>订阅方案</Label>
+        <Input value="Premium" />
+      </TextField>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/label.tsx)。
+
+## API 参考
+
+### Label
+
+| prop                | type                         | default     | description                                                                                                   |
+| ------------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`            | -           | 标签内容。为字符串时自动渲染为 `Label.Text`；否则按原样渲染子节点                                               |
+| `isRequired`        | `boolean`                    | `false`     | 是否必填；为 true 时显示星号                                                                                   |
+| `isInvalid`         | `boolean`                    | `false`     | 是否非法；为 true 时文字使用危险色                                                                             |
+| `isDisabled`        | `boolean`                    | `false`     | 是否禁用；应用禁用样式并阻止交互                                                                               |
+| `className`         | `string`                     | -           | 额外的 class                                                                                                  |
+| `animation`         | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                                           |
+| `...PressableProps` | `PressableProps`             | -           | 支持 React Native `Pressable` 的全部属性                                                                       |
+
+### Label.Text
+
+| prop           | type                                     | default | description                                                                        |
+| -------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                        | -       | 标签文字内容                                                                       |
+| `className`    | `string`                                 | -       | 文本元素的额外 class                                                               |
+| `classNames`   | `ElementSlots<LabelSlots>`               | -       | 标签各部分的额外 class                                                             |
+| `styles`       | `Partial<Record<LabelSlots, TextStyle>>` | -       | 标签各部分的样式                                                                   |
+| `nativeID`     | `string`                                 | -       | 无障碍用原生 ID，通过 aria-labelledby 关联表单控件                                 |
+| `...TextProps` | `TextProps`                              | -       | 支持 React Native `Text` 的全部属性                                                |
+
+#### `ElementSlots<LabelSlots>`
+
+| prop       | type     | description        |
+| ---------- | -------- | ------------------ |
+| `text`     | `string` | 标签文字的 class   |
+| `asterisk` | `string` | 星号的 class       |
+
+#### `styles`
+
+| prop       | type        | description |
+| ---------- | ----------- | ----------- |
+| `text`     | `TextStyle` | 标签文字样式 |
+| `asterisk` | `TextStyle` | 星号样式     |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/radio-group.mdx b/apps/docs/content/docs/cn/native/components/(forms)/radio-group.mdx
new file mode 100644
index 0000000..0d0932d
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/radio-group.mdx
@@ -0,0 +1,339 @@
+---
+title: RadioGroup 单选框组
+description: 单选按钮组，同一时间只能选中一个选项。
+links:
+  source_native: radio-group/radio-group.tsx
+  styles_native: radio-group/radio-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { RadioGroup } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<RadioGroup>
+  <RadioGroup.Item>
+    <Label>...</Label>
+    <Description>...</Description>
+    <Radio>
+      <Radio.Indicator>
+        <Radio.IndicatorThumb />
+      </Radio.Indicator>
+    </Radio>
+  </RadioGroup.Item>
+  <FieldError>...</FieldError>
+</RadioGroup>
+```
+
+- **RadioGroup**：管理单选项选中状态的容器，支持横向与纵向布局。
+- **RadioGroup.Item**：组内单个选项，必须放在 `RadioGroup` 内。处理选中状态；在仅提供文本子节点时会渲染默认 `<Radio />` 指示器。支持渲染函数子节点以访问状态（`isSelected`、`isInvalid`、`isDisabled`）。
+- **Label**：可选的可点击文字标签，与单选项关联以提升无障碍。请直接使用 [Label](./label) 组件。
+- **Description**：标签下方的可选说明文字。请直接使用 [Description](./description) 组件。
+- **Radio**：置于 `RadioGroup.Item` 内的 [Radio](./radio) 组件，用于渲染单选指示器。会自动识别 `RadioGroupItem` 上下文并从中获取 `isSelected`、`isDisabled`、`isInvalid` 与 `variant`。
+- **Radio.Indicator**：单选圆环的可选容器；无子节点时渲染默认拇指样式，管理选中视觉。完整 API 见 [Radio](./radio)。
+- **Radio.IndicatorThumb**：选中时显示的可选内圆，随选中状态缩放动画；可替换为自定义内容。见 [Radio](./radio)。
+- **FieldError**：在组无效时显示的错误信息，带动画显示在组内容下方。请直接使用 [FieldError](./field-error) 组件。
+
+## 用法
+
+### 基础用法
+
+使用简单字符串子节点时，会自动渲染标题与指示器。
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">选项 1</RadioGroup.Item>
+  <RadioGroup.Item value="option2">选项 2</RadioGroup.Item>
+  <RadioGroup.Item value="option3">选项 3</RadioGroup.Item>
+</RadioGroup>
+```
+
+### 带说明文字
+
+在每个选项下方添加描述以补充上下文。
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from 'heroui-native';
+import { View } from 'react-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="standard">
+    <View>
+      <Label>标准配送</Label>
+      <Description>5–7 个工作日送达</Description>
+    </View>
+    <Radio />
+  </RadioGroup.Item>
+  <RadioGroup.Item value="express">
+    <View>
+      <Label>加急配送</Label>
+      <Description>2–3 个工作日送达</Description>
+    </View>
+    <Radio />
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### 自定义指示器
+
+使用 `Radio` 子组件将默认拇指替换为自定义内容。
+
+```tsx
+import { RadioGroup, Radio, Label } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="custom">
+    {({ isSelected }) => (
+      <>
+        <Label>自定义选项</Label>
+        <Radio>
+          <Radio.Indicator>
+            {isSelected && (
+              <Animated.View entering={FadeIn}>
+                <Icon name="check" size={12} />
+              </Animated.View>
+            )}
+          </Radio.Indicator>
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### 使用渲染函数
+
+在 `RadioGroup.Item` 上使用渲染函数以访问状态并自定义整块内容。
+
+```tsx
+import { RadioGroup, Radio, Label } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">
+    {({ isSelected, isInvalid, isDisabled }) => (
+      <>
+        <Label>选项 1</Label>
+        <Radio>
+          <Radio.Indicator>{isSelected && <CustomIcon />}</Radio.Indicator>
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### 显示错误信息
+
+在单选组下方展示校验错误。
+
+```tsx
+import { RadioGroup, FieldError } from 'heroui-native';
+
+function RadioGroupWithError() {
+  const [value, setValue] = React.useState<string | undefined>(undefined);
+
+  return (
+    <RadioGroup value={value} onValueChange={setValue} isInvalid={!value}>
+      <RadioGroup.Item value="agree">我同意条款</RadioGroup.Item>
+      <RadioGroup.Item value="disagree">我不同意</RadioGroup.Item>
+      <FieldError isInvalid={!value}>
+        请选择一项以继续
+      </FieldError>
+    </RadioGroup>
+  );
+}
+```
+
+## 示例
+
+```tsx
+import {
+  Description,
+  Label,
+  Radio,
+  RadioGroup,
+  Separator,
+  Surface,
+} from 'heroui-native';
+import React from 'react';
+import { View } from 'react-native';
+
+export default function RadioGroupExample() {
+  const [selection, setSelection] = React.useState('desc1');
+
+  return (
+    <Surface className="w-full">
+      <RadioGroup value={selection} onValueChange={setSelection}>
+        <RadioGroup.Item value="desc1">
+          <View>
+            <Label>标准配送</Label>
+            <Description>5–7 个工作日送达</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+        <Separator className="my-1" />
+        <RadioGroup.Item value="desc2">
+          <View>
+            <Label>加急配送</Label>
+            <Description>2–3 个工作日送达</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+        <Separator className="my-1" />
+        <RadioGroup.Item value="desc3">
+          <View>
+            <Label>次日达</Label>
+            <Description>下一个工作日送达</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+      </RadioGroup>
+    </Surface>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/radio-group.tsx>)。
+
+## API 参考
+
+### RadioGroup
+
+| prop            | type                         | default     | description                                                                               |
+| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`      | `React.ReactNode`            | `undefined` | 单选组内容                                                                       |
+| `value`         | `string \| undefined`        | `undefined` | 当前选中值                                           |
+| `onValueChange` | `(val: string) => void`      | `undefined` | 选中值变化时的回调                                            |
+| `isDisabled`    | `boolean`                    | `false`     | 是否禁用整个单选组                                                |
+| `isInvalid`     | `boolean`                    | `false`     | 组是否处于无效状态                                                        |
+| `variant`       | `'primary' \| 'secondary'`   | `undefined` | 单选组样式变体（子项未单独设置时继承）                 |
+| `animation`     | `"disable-all" \| undefined` | `undefined` | 动画配置。使用 `"disable-all"` 可关闭包含子节点在内的全部动画 |
+| `className`     | `string`                     | `undefined` | 自定义 className                                                                         |
+| `...ViewProps`  | `ViewProps`                  | -           | 支持全部标准 React Native View 属性                                        |
+
+### RadioGroup.Item
+
+| prop                | type                                                                         | default     | description                                                               |
+| ------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((props: RadioGroupItemRenderProps) => React.ReactNode)` | `undefined` | 选项内容，或用于自定义项的渲染函数         |
+| `value`             | `string`                                                                     | `undefined` | 该选项关联的值                                 |
+| `isDisabled`        | `boolean`                                                                    | `false`     | 是否禁用该选项                              |
+| `isInvalid`         | `boolean`                                                                    | `false`     | 该选项是否无效                                         |
+| `variant`           | `'primary' \| 'secondary'`                                                   | `'primary'` | 该选项的样式变体                                          |
+| `hitSlop`           | `number`                                                                     | `6`         | 可点击区域的热区扩展                                           |
+| `className`         | `string`                                                                     | `undefined` | 自定义 className                                                         |
+| `...PressableProps` | `PressableProps`                                                             | -           | 支持全部标准 Pressable 属性（不含 disabled） |
+
+#### RadioGroupItemRenderProps
+
+| prop         | type      | description                        |
+| ------------ | --------- | ---------------------------------- |
+| `isSelected` | `boolean` | 该选项是否选中 |
+| `isInvalid`  | `boolean` | 该选项是否无效  |
+| `isDisabled` | `boolean` | 该选项是否禁用 |
+
+### Radio（位于 RadioGroup.Item 内）
+
+`Radio` 放在 `RadioGroup.Item` 内用于渲染单选指示器。此时会自动识别 `RadioGroupItem` 上下文并从中获取 `isSelected`、`isDisabled`、`isInvalid` 与 `variant`，无需手动传参。
+
+使用 `<Radio />` 获得默认指示器，或组合 `Radio.Indicator` 与 `Radio.IndicatorThumb` 自定义样式。
+
+| prop                | type                                                                | default     | description                                                               |
+| ------------------- | ------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((props: RadioRenderProps) => React.ReactNode)` | `undefined` | 子元素或渲染函数以自定义单选                  |
+| `variant`           | `'primary' \| 'secondary'`                                          | `'primary'` | 单选视觉变体                                               |
+| `isSelected`        | `boolean`                                                           | `undefined` | 是否选中                                   |
+| `isDisabled`        | `boolean`                                                           | `undefined` | 是否禁用且不可交互               |
+| `isInvalid`         | `boolean`                                                           | `false`     | 是否无效（危险色）                         |
+| `className`         | `string`                                                            | `undefined` | 额外 CSS 类                                           |
+| `animation`         | `RadioRootAnimation`                                                | -           | 单选根动画配置                                         |
+| `onSelectedChange`  | `(isSelected: boolean) => void`                                     | `undefined` | 选中状态变化时的回调                     |
+| `...PressableProps` | `PressableProps`                                                    | -           | 支持全部标准 Pressable 属性（不含 disabled） |
+
+#### RadioRenderProps
+
+| prop         | type      | description                   |
+| ------------ | --------- | ----------------------------- |
+| `isSelected` | `boolean` | 是否选中 |
+| `isDisabled` | `boolean` | 是否禁用 |
+| `isInvalid`  | `boolean` | 是否无效  |
+
+#### RadioRootAnimation
+
+单选根组件的动画配置，可为：
+
+- `"disable-all"`：关闭包含子节点（Indicator、IndicatorThumb）在内的全部动画
+- `undefined`：使用默认动画
+
+### Radio.Indicator
+
+| prop                   | type                       | default     | description                                      |
+| ---------------------- | -------------------------- | ----------- | ------------------------------------------------ |
+| `children`             | `React.ReactNode`          | `undefined` | 指示器内容                  |
+| `className`            | `string`                   | `undefined` | 指示器额外 CSS 类         |
+| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | -           | 支持全部 Reanimated Animated.View 属性 |
+
+### Radio.IndicatorThumb
+
+| prop                    | type                           | default     | description                                                  |
+| ----------------------- | ------------------------------ | ----------- | ------------------------------------------------------------ |
+| `className`             | `string`                       | `undefined` | 拇指区域额外 CSS 类                         |
+| `animation`             | `RadioIndicatorThumbAnimation` | -           | 拇指动画配置                        |
+| `isAnimatedStyleActive` | `boolean`                      | `true`      | 是否启用 Reanimated 动画样式 |
+| `...AnimatedViewProps`  | `AnimatedProps<ViewProps>`     | -           | 支持全部 Reanimated Animated.View 属性             |
+
+#### RadioIndicatorThumbAnimation
+
+单选指示器拇指的动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                 | type                    | default                                              | description                                     |
+| -------------------- | ----------------------- | ---------------------------------------------------- | ----------------------------------------------- |
+| `state`              | `'disabled' \| boolean` | -                                                    | 在自定义属性时用于禁用动画 |
+| `scale.value`        | `[number, number]`      | `[1.5, 1]`                                           | 缩放值 [未选中, 已选中]             |
+| `scale.timingConfig` | `WithTimingConfig`      | `{ duration: 300, easing: Easing.out(Easing.ease) }` | 动画时间配置                  |
+
+**说明：** 标签、说明与错误信息请直接使用基础组件：
+
+- 标签使用 [Label](../label/label.md)
+- 说明使用 [Description](../description/description.md)
+- 错误使用 [FieldError](../field-error/field-error.md)
+
+## Hooks
+
+### useRadioGroup
+
+#### 返回值
+
+| 属性        | 类型                       | 描述                                    |
+| --------------- | -------------------------- | ---------------------------------------------- |
+| `value`         | `string \| undefined`      | 当前选中值                       |
+| `isDisabled`    | `boolean`                  | 单选组是否禁用            |
+| `isInvalid`     | `boolean`                  | 单选组是否无效 |
+| `variant`       | `'primary' \| 'secondary'` | 单选组样式变体              |
+| `onValueChange` | `(value: string) => void`  | 修改选中值的函数          |
+
+### useRadioGroupItem
+
+#### 返回值
+
+| 属性           | 类型                                           | 描述                                                             |
+| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| `isSelected`       | `boolean`                                      | 该选项是否选中                                      |
+| `isDisabled`       | `boolean \| undefined`                         | 该选项是否禁用                                      |
+| `isInvalid`        | `boolean \| undefined`                         | 该选项是否无效                                       |
+| `variant`          | `'primary' \| 'secondary' \| undefined`        | 该选项的样式变体                                        |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | 修改选中状态的回调（在组内选中该项） |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/search-field.mdx b/apps/docs/content/docs/cn/native/components/(forms)/search-field.mdx
new file mode 100644
index 0000000..8a12226
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/search-field.mdx
@@ -0,0 +1,241 @@
+---
+title: SearchField 搜索框
+description: 用于筛选与查询的复合搜索输入框。
+links:
+  source_native: search-field/search-field.tsx
+  styles_native: search-field/search-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { SearchField } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<SearchField value={value} onChange={onChange}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+- **SearchField**：根容器，接收 `value` 与 `onChange` 并通过上下文下发；同时提供 `isDisabled`、`isInvalid`、`isRequired` 与动画设置。
+- **SearchField.Group**：横向 `flex-row` 容器，排列搜索图标、输入与清除按钮。
+- **SearchField.SearchIcon**：默认放大镜图标，绝对定位在输入左侧；可传入子节点替换默认图标。
+- **SearchField.Input**：包装 `Input` 并应用搜索相关默认行为；自动从上下文读取 `value` 与 `onChangeText`。
+- **SearchField.ClearButton**：清除输入的小图标按钮；值为空时自动隐藏；按下时调用上下文的 `onChange("")`。
+
+## 用法
+
+### 基础用法
+
+在根上传入 `value` 与 `onChange`；`Input` 与 `ClearButton` 通过上下文消费。
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### 标签与说明
+
+在 `Group` 外放置 `Label`、`Description` 以补充语义。
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <Label>查找商品</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description>按名称、分类或 SKU 搜索</Description>
+</SearchField>
+```
+
+### 校验
+
+在根上使用 `isInvalid`、`isRequired`，并配合 `FieldError` 展示错误。
+
+```tsx
+<SearchField
+  value={searchValue}
+  onChange={setSearchValue}
+  isRequired
+  isInvalid={isInvalid}
+>
+  <Label>搜索用户</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description hideOnInvalid>至少输入 3 个字符再搜索</Description>
+  <FieldError>未找到结果，请尝试其他关键词。</FieldError>
+</SearchField>
+```
+
+### 自定义搜索图标
+
+向 `SearchField.SearchIcon` 传入子节点替换默认图标。
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon>
+      <Text className="text-base">🔍</Text>
+    </SearchField.SearchIcon>
+    <SearchField.Input className="pl-10" />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### 禁用
+
+根上设置 `isDisabled`，通过上下文禁用子级。
+
+```tsx
+<SearchField value="之前的查询" isDisabled>
+  <Label>已禁用的搜索</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+  </SearchField.Group>
+  <Description>搜索暂时不可用</Description>
+</SearchField>
+```
+
+## 示例
+
+```tsx
+import { Description, Label, SearchField } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function SearchFieldExample() {
+  const [searchValue, setSearchValue] = useState('');
+
+  return (
+    <View className="px-5">
+      <SearchField value={searchValue} onChange={setSearchValue}>
+        <Label>查找商品</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>按名称、分类或 SKU 搜索</Description>
+      </SearchField>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/search-field.tsx>)。
+
+## API 参考
+
+### SearchField
+
+| prop           | type                      | default | description                                              |
+| -------------- | ------------------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode`         | -       | 搜索字段内的子节点                                       |
+| `value`        | `string`                  | -       | 受控搜索文本                                             |
+| `onChange`     | `(value: string) => void` | -       | 文本变化回调                                             |
+| `isDisabled`   | `boolean`                 | `false` | 是否禁用                                                 |
+| `isInvalid`    | `boolean`                 | `false` | 是否非法                                                 |
+| `isRequired`   | `boolean`                 | `false` | 是否必填                                                 |
+| `className`    | `string`                  | -       | 额外的 class                                             |
+| `animation`    | `AnimationRootDisableAll` | -       | 搜索字段动画配置                                         |
+| `...ViewProps` | `ViewProps`               | -       | 支持 React Native `View` 的全部属性                      |
+
+#### AnimationRootDisableAll
+
+根动画配置，可为：
+
+- `"disable-all"`：禁用全部动画（含子级，级联）
+- `undefined`：使用默认动画
+
+### SearchField.Group
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 组内子节点                                         |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |
+
+### SearchField.SearchIcon
+
+| prop           | type                             | default | description                                                                        |
+| -------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                | -       | 自定义内容，替换默认搜索图标                                                       |
+| `className`    | `string`                         | -       | 额外的 class                                                                       |
+| `iconProps`    | `SearchFieldSearchIconIconProps` | -       | 自定义默认搜索图标（提供 `children` 时忽略）                                       |
+| `...ViewProps` | `ViewProps`                      | -       | 支持 React Native `View` 的全部属性                                                |
+
+#### SearchFieldSearchIconIconProps
+
+| prop    | type     | default             | description |
+| ------- | -------- | ------------------- | ----------- |
+| `size`  | `number` | `16`                | 图标尺寸    |
+| `color` | `string` | 主题的 `muted` 色   | 图标颜色    |
+
+### SearchField.Input
+
+在 [Input](./input) 属性之上带有搜索默认值（`placeholder="Search..."`、`returnKeyType="search"`、`accessibilityRole="search"`）。不提供 `value` 与 `onChangeText`，由 `SearchField` 上下文提供。
+
+### SearchField.ClearButton
+
+受控 `value` 为空字符串时自动隐藏；按下时调用上下文的 `onChange("")`。若额外传入 `onPress`，会在清空后调用。
+
+| prop             | type                              | default | description                                      |
+| ---------------- | --------------------------------- | ------- | ------------------------------------------------ |
+| `children`       | `React.ReactNode`                 | -       | 自定义内容，替换默认关闭图标                     |
+| `iconProps`      | `SearchFieldClearButtonIconProps` | -       | 清除按钮图标属性                                 |
+| `className`      | `string`                          | -       | 额外的 class                                     |
+| `...ButtonProps` | `ButtonRootProps`                 | -       | 支持 Button 根级全部属性                         |
+
+#### SearchFieldClearButtonIconProps
+
+| prop    | type     | default             | description |
+| ------- | -------- | ------------------- | ----------- |
+| `size`  | `number` | `14`                | 图标尺寸    |
+| `color` | `string` | 主题的 `muted` 色   | 图标颜色    |
+
+## Hooks
+
+### useSearchField
+
+访问搜索字段上下文，必须在 `SearchField` 内使用。
+
+```tsx
+import { useSearchField } from 'heroui-native';
+
+const { value, onChange, isDisabled, isInvalid, isRequired } = useSearchField();
+```
+
+#### 返回值
+
+| property     | type                                     | description           |
+| ------------ | ---------------------------------------- | --------------------- |
+| `value`      | `string \| undefined`                    | 当前受控搜索文本      |
+| `onChange`   | `((value: string) => void) \| undefined` | 更新搜索文本的回调    |
+| `isDisabled` | `boolean`                                | 是否禁用              |
+| `isInvalid`  | `boolean`                                | 是否非法              |
+| `isRequired` | `boolean`                                | 是否必填              |
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/select.mdx b/apps/docs/content/docs/cn/native/components/(forms)/select.mdx
new file mode 100644
index 0000000..2caff71
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/select.mdx
@@ -0,0 +1,822 @@
+---
+title: Select 选择器
+description: 通过按钮触发，展示可选列表供用户选择。
+icon: updated
+links:
+  source_native: select/select.tsx
+  styles_native: select/select.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Select } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content>
+      <Select.Close />
+      <Select.ListLabel>...</Select.ListLabel>
+      <Select.Item>
+        <Select.ItemLabel />
+        <Select.ItemDescription>...</Select.ItemDescription>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+- **Select**：根容器，管理打开/关闭、选中值，并向子组件提供上下文。
+- **Select.Trigger**：可点击的触发器，用于切换选择器显示。为任意子元素包裹按压处理，支持 `variant`（`'default'` 或 `'unstyled'`）。
+- **Select.Value**：显示当前选中值或占位符；选中变化时自动更新，样式随是否有选中值变化。
+- **Select.TriggerIndicator**：可选的视觉指示器，表示开/关状态；默认渲染带动画的双角标，随打开/关闭旋转。
+- **Select.Portal**：在Portal层渲染内容，保证正确的层级与定位。
+- **Select.Overlay**：可选的背景遮罩，可透明或半透明，用于捕获外部点击。
+- **Select.Content**：内容容器，支持三种呈现：气泡（浮动定位）、底部抽屉或对话框。
+- **Select.Close**：关闭按钮；可传入自定义子节点，否则使用默认关闭图标。
+- **Select.ListLabel**：列表标题，使用预设排版样式。
+- **Select.Item**：可选中的选项，处理选中态与按压。
+- **Select.ItemLabel**：选项主文案。
+- **Select.ItemDescription**：可选的说明文字，弱化样式。
+- **Select.ItemIndicator**：选中项的可选指示器，默认渲染对勾图标。
+
+## 用法
+
+### 基础用法
+
+Select 通过复合子组件构建下拉选择界面。
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="选项 1" />
+      <Select.Item value="2" label="选项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 在触发器显示选中值
+
+使用 Value 在触发器区域展示当前选中项。
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="请选择一项" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="apple" label="苹果" />
+      <Select.Item value="orange" label="橙子" />
+      <Select.Item value="banana" label="香蕉" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 气泡（Popover）呈现
+
+使用 `presentation="popover"` 获得带自动定位的浮动内容。
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" placement="bottom" align="center">
+      <Select.Item value="1" label="项 1" />
+      <Select.Item value="2" label="项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 宽度控制
+
+通过 `width` 控制内容宽度；仅对气泡呈现生效。
+
+```tsx
+{
+  /* 固定像素宽度 */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width={280}>
+      <Select.Item value="1" label="项 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* 与触发器同宽 */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="trigger">
+      <Select.Item value="1" label="项 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* 全宽（100%） */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="full">
+      <Select.Item value="1" label="项 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* 随内容自适应（默认） */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="content-fit">
+      <Select.Item value="1" label="项 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+```
+
+### 底部抽屉呈现
+
+使用底部抽屉以获得更贴近移动端的体验。
+
+```tsx
+<Select presentation="bottom-sheet">
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="bottom-sheet" snapPoints={['35%']}>
+      <Select.Item value="1" label="项 1" />
+      <Select.Item value="2" label="项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 对话框呈现
+
+使用对话框呈现居中模态式选择。
+
+```tsx
+<Select presentation="dialog">
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="dialog">
+      <Select.Close />
+      <Select.ListLabel>请选择一项</Select.ListLabel>
+      <Select.Item value="1" label="项 1" />
+      <Select.Item value="2" label="项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 自定义选项内容
+
+通过自定义子节点与指示器定制选项外观。
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="us" label="美国">
+        <View className="flex-row items-center gap-3 flex-1">
+          <Text>🇺🇸</Text>
+          <Select.ItemLabel />
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+      <Select.Item value="uk" label="英国">
+        <View className="flex-row items-center gap-3 flex-1">
+          <Text>🇬🇧</Text>
+          <Select.ItemLabel />
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 使用渲染函数
+
+在 `Select.Item` 上使用渲染函数，根据选中态等自定义内容。
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="us" label="美国">
+        {({ isSelected, value, isDisabled }) => (
+          <>
+            <View className="flex-row items-center gap-3 flex-1">
+              <Text>🇺🇸</Text>
+              <Select.ItemLabel
+                className={
+                  isSelected ? 'text-accent font-medium' : 'text-foreground'
+                }
+              />
+            </View>
+            <Select.ItemIndicator />
+          </>
+        )}
+      </Select.Item>
+      <Select.Item value="uk" label="英国">
+        {({ isSelected }) => (
+          <>
+            <View className="flex-row items-center gap-3 flex-1">
+              <Text>🇬🇧</Text>
+              <Select.ItemLabel
+                className={
+                  isSelected ? 'text-accent font-medium' : 'text-foreground'
+                }
+              />
+            </View>
+            <Select.ItemIndicator />
+          </>
+        )}
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 带选项说明
+
+为选项添加说明以提供更多上下文。
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="basic" label="基础版">
+        <View className="flex-1">
+          <Select.ItemLabel />
+          <Select.ItemDescription>
+            面向个人使用的必备功能
+          </Select.ItemDescription>
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 带触发器指示器
+
+添加视觉指示器表示开/关状态；打开/关闭时会旋转。
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="请选择一项" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="选项 1" />
+      <Select.Item value="2" label="选项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 无样式触发器与自定义组合
+
+使用 `unstyled` 变体，将触发器与 Button 等组件组合。
+
+```tsx
+<Select>
+  <Select.Trigger variant="unstyled" asChild>
+    <Button variant="secondary">
+      <Select.Value placeholder="请选择…" />
+      <Select.TriggerIndicator />
+    </Button>
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="选项 1" />
+      <Select.Item value="2" label="选项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### 受控模式
+
+以编程方式控制打开状态与选中值。
+
+```tsx
+const [value, setValue] = useState();
+const [isOpen, setIsOpen] = useState(false);
+
+<Select
+  value={value}
+  onValueChange={setValue}
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+>
+  <Select.Trigger>
+    <Select.Value placeholder="请选择…" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="选项 1" />
+      <Select.Item value="2" label="选项 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+```
+
+## 示例
+
+```tsx
+import { Select, Separator } from 'heroui-native';
+import React, { useState } from 'react';
+
+type SelectOption = {
+  value: string;
+  label: string;
+};
+
+const US_STATES: SelectOption[] = [
+  { value: 'CA', label: '加利福尼亚' },
+  { value: 'NY', label: '纽约' },
+  { value: 'TX', label: '得克萨斯' },
+  { value: 'FL', label: '佛罗里达' },
+];
+
+export default function SelectExample() {
+  const [value, setValue] = useState<SelectOption | undefined>();
+
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <Select.Trigger>
+        <Select.Value placeholder="请选择一项" />
+        <Select.TriggerIndicator />
+      </Select.Trigger>
+      <Select.Portal>
+        <Select.Overlay />
+        <Select.Content presentation="popover" width="trigger">
+          <Select.ListLabel className="mb-2">选择州/省</Select.ListLabel>
+          {US_STATES.map((state, index) => (
+            <React.Fragment key={state.value}>
+              <Select.Item value={state.value} label={state.label} />
+              {index < US_STATES.length - 1 && <Separator />}
+            </React.Fragment>
+          ))}
+        </Select.Content>
+      </Select.Portal>
+    </Select>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/select.tsx)。
+
+## API 参考
+
+### Select
+
+| prop            | type                                      | default     | description                                                            |
+| --------------- | ----------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `children`      | `ReactNode`                               | -           | 选择器子内容                                                           |
+| `value`         | `SelectOption \| SelectOption[]`                  | -           | 当前选中值（受控）                                                     |
+| `onValueChange` | `(value: SelectOption \| SelectOption[]) => void` | -           | 选中值变化时的回调                                                     |
+| `defaultValue`  | `SelectOption \| SelectOption[]`                  | -           | 默认选中值（非受控）                                                   |
+| `isOpen`        | `boolean`                                 | -           | 是否打开（受控）                                                       |
+| `isDefaultOpen` | `boolean`                                 | -           | 初始是否打开（非受控）                                                 |
+| `onOpenChange`  | `(isOpen: boolean) => void`               | -           | 打开状态变化时的回调                                                   |
+| `isDisabled`    | `boolean`                                 | `false`     | 是否禁用                                                               |
+| `presentation`  | `'popover' \| 'bottom-sheet' \| 'dialog'` | `'popover'` | 内容呈现方式                                                           |
+| `animation`     | `SelectRootAnimation`                     | -           | 动画配置                                                               |
+| `asChild`       | `boolean`                                 | `false`     | 是否将子元素作为实际渲染节点                                           |
+| `...ViewProps`  | `ViewProps`                               | -           | 支持全部标准 React Native `View` 属性                                  |
+
+#### SelectRootAnimation
+
+Select 根级动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根动画
+- `"disable-all"`：禁用根与子级全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                                             | default | description                                     |
+| ---------------- | ------------------------------------------------ | ------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean`         | -       | 在自定义属性时用于禁用动画                      |
+| `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | -       | 打开时的动画配置                                |
+| `exiting.value`  | `SpringAnimationConfig \| TimingAnimationConfig` | -       | 关闭时的动画配置                                |
+
+#### SpringAnimationConfig
+
+| prop     | type               | default | description                               |
+| -------- | ------------------ | ------- | ----------------------------------------- |
+| `type`   | `'spring'`         | -       | 动画类型（须为 `'spring'`）               |
+| `config` | `WithSpringConfig` | -       | Reanimated 弹簧动画配置                   |
+
+#### TimingAnimationConfig
+
+| prop     | type               | default | description                               |
+| -------- | ------------------ | ------- | ----------------------------------------- |
+| `type`   | `'timing'`         | -       | 动画类型（须为 `'timing'`）               |
+| `config` | `WithTimingConfig` | -       | Reanimated 时长动画配置                   |
+
+### Select.Trigger
+
+| prop                | type                      | default     | description                                                                                                       |
+| ------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| `variant`           | `'default' \| 'unstyled'` | `'default'` | 触发器变体：`'default'` 应用预设容器样式，`'unstyled'` 移除默认样式                                               |
+| `children`          | `ReactNode`               | -           | 触发器内容                                                                                                       |
+| `className`         | `string`                  | -           | 触发器额外 class                                                                                                 |
+| `asChild`           | `boolean`                 | `true`      | 是否将子元素作为实际渲染节点                                                                                     |
+| `isDisabled`        | `boolean`                 | -           | 是否禁用触发器                                                                                                   |
+| `...PressableProps` | `PressableProps`          | -           | 支持全部标准 React Native `Pressable` 属性                                                                       |
+
+### Select.Value
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `placeholder`  | `string`    | -       | 未选中时的占位文案                                 |
+| `className`    | `string`    | -       | 值区域额外 class                                   |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性              |
+
+**说明：** 值组件会根据是否有选中项自动应用不同文字颜色：
+
+- 已选中：`text-foreground`
+- 未选中（占位）：`text-field-placeholder`
+
+### Select.TriggerIndicator
+
+| prop                    | type                              | default | description                                                  |
+| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
+| `children`              | `ReactNode`                       | -       | 自定义指示器内容；默认带动画的双角标                         |
+| `className`             | `string`                          | -       | 指示器额外 class                                             |
+| `style`                 | `ViewStyle`                       | -       | 指示器自定义样式                                             |
+| `iconProps`             | `SelectTriggerIndicatorIconProps` | -       | 双角标图标配置                                               |
+| `animation`             | `SelectTriggerIndicatorAnimation` | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                         | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `...ViewProps`          | `ViewProps`                       | -       | 支持全部标准 React Native `View` 属性                        |
+
+**说明：** 以下样式属性由动画占用，不能通过 `className` 设置：
+
+- `transform`（尤其是 `rotate`）— 用于开/关旋转过渡
+
+若要自定义，请使用 `animation`。若需完全关闭动画样式并自行用 `className` 或 `style` 控制，请设置 `isAnimatedStyleActive={false}`。
+
+#### SelectTriggerIndicatorIconProps
+
+| prop    | type     | default | description                                            |
+| ------- | -------- | ------- | ------------------------------------------------------ |
+| `size`  | `number` | `16`    | 图标尺寸                                               |
+| `color` | `string` | -       | 图标颜色（默认同前景主题色）                           |
+
+#### SelectTriggerIndicatorAnimation
+
+`Select.TriggerIndicator` 的动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画（0° 到 -180° 旋转）
+- `object`：自定义动画配置
+
+| prop                    | type                    | default                                      | description                                     |
+| ----------------------- | ----------------------- | -------------------------------------------- | ----------------------------------------------- |
+| `state`                 | `'disabled' \| boolean` | -                                            | 在自定义属性时用于禁用动画                      |
+| `rotation.value`        | `[number, number]`      | `[0, -180]`                                  | 旋转角度 [关闭, 打开]，单位度                   |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧动画配置                                |
+
+### Select.Portal
+
+| prop                       | type        | default | description                                                                                                                   |
+| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactNode` | -       | Portal内容（必填）                                                                                                              |
+| `disableFullWindowOverlay` | `boolean`   | `false` | 在 iOS 为 `true` 时使用 `View` 代替 `FullWindowOverlay`，便于元素检查器；遮罩将无法叠在原生模态之上                           |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时，VoiceOver 仅聚焦遮罩内元素。仅 iOS；API 不稳定，可能随 react-native-screens 变更 |
+| `className`                | `string`    | -       | Portal容器额外 class                                                                                                            |
+| `hostName`                 | `string`    | -       | Portal宿主元素的可选名称                                                                                                        |
+| `forceMount`               | `boolean`   | -       | 是否强制挂载到 DOM                                                                                                            |
+| `...ViewProps`             | `ViewProps` | -       | 支持全部标准 React Native `View` 属性                                                                                       |
+
+### Select.Overlay
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                 | -       | 遮罩额外 class                                               |
+| `animation`             | `SelectOverlayAnimation` | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `closeOnPress`          | `boolean`                | `true`  | 点击遮罩是否关闭选择器                                       |
+| `forceMount`            | `boolean`                | -       | 是否强制挂载到 DOM                                           |
+| `asChild`               | `boolean`                | `false` | 是否将子元素作为实际渲染节点                                 |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | 支持 Reanimated `Animated.View` 的全部属性                   |
+
+#### SelectOverlayAnimation
+
+`Select.Overlay` 的动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画（底部抽屉/对话框为基于进度的透明度；气泡为关键帧动画）
+- `object`：自定义动画配置
+
+| prop            | type                       | default     | description                                                                  |
+| --------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -           | 在自定义属性时用于禁用动画                                                   |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 透明度 [空闲, 打开, 关闭]（用于底部抽屉/对话框呈现）                        |
+| `entering`      | `EntryOrExitLayoutType`    | -           | 进入过渡自定义关键帧（用于气泡呈现）                                         |
+| `exiting`       | `EntryOrExitLayoutType`    | -           | 退出过渡自定义关键帧（用于气泡呈现）                                       |
+
+### Select.Content（气泡呈现）
+
+| prop                    | type                                             | default         | description                                            |
+| ----------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ |
+| `children`              | `ReactNode`                                      | -               | 选择器内容                                             |
+| `width`                 | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | 内容宽度策略                                           |
+| `presentation`          | `'popover'`                                      | `'popover'`     | 呈现模式                                               |
+| `placement`             | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | 相对触发器的方位                                       |
+| `align`                 | `'start' \| 'center' \| 'end'`                   | `'center'`      | 沿放置轴的对齐方式                                     |
+| `avoidCollisions`       | `boolean`                                        | `true`          | 靠近视口边缘时是否翻转 placement                       |
+| `offset`                | `number`                                         | `8`             | 与触发器的间距（像素）                                 |
+| `alignOffset`           | `number`                                         | `0`             | 沿对齐轴的偏移（像素）                                 |
+| `className`             | `string`                                         | -               | 内容容器额外 class                                     |
+| `animation`             | `SelectContentPopoverAnimation`                  | -               | 动画配置                                               |
+| `forceMount`            | `boolean`                                        | -               | 是否强制挂载到 DOM                                     |
+| `insets`                | `Insets`                                         | -               | 定位时需遵守的屏幕边距                                 |
+| `asChild`               | `boolean`                                        | `false`         | 是否将子元素作为实际渲染节点                           |
+| `...Animated.ViewProps` | `Animated.ViewProps`                             | -               | 支持 Reanimated `Animated.View` 的全部属性           |
+
+#### SelectContentPopoverAnimation
+
+`Select.Content`（气泡呈现）的动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认关键帧（按 placement 的 translateY/translateX、scale、opacity）
+- `object`：自定义 `entering` 和/或 `exiting` 关键帧
+
+| prop       | type                    | default | description                                                                                                                                |
+| ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state`    | `'disabled' \| boolean` | -       | 在自定义属性时用于禁用动画                                                                                                                 |
+| `entering` | `EntryOrExitLayoutType` | -       | 进入过渡关键帧（默认：按 placement 的 translateY/translateX、scale、opacity，200ms）                                                       |
+| `exiting`  | `EntryOrExitLayoutType` | -       | 退出过渡关键帧（默认：与进入镜像，150ms）                                                                                                  |
+
+### Select.Content（底部抽屉呈现）
+
+| prop                        | type               | default | description                                      |
+| --------------------------- | ------------------ | ------- | ------------------------------------------------ |
+| `children`                  | `ReactNode`        | -       | 底部抽屉内容                                     |
+| `presentation`              | `'bottom-sheet'`   | -       | 呈现模式                                         |
+| `contentContainerClassName` | `string`           | -       | 内容容器额外 class                               |
+| `...BottomSheetProps`       | `BottomSheetProps` | -       | 支持 `@gorhom/bottom-sheet` 的全部属性           |
+
+### Select.Content（对话框呈现）
+
+| prop           | type                                                     | default | description                                         |
+| -------------- | -------------------------------------------------------- | ------- | --------------------------------------------------- |
+| `children`     | `ReactNode`                                              | -       | 对话框内容                                          |
+| `presentation` | `'dialog'`                                               | -       | 呈现模式                                            |
+| `classNames`   | `{ wrapper?: string; content?: string }`                 | -       | 包裹层与内容区额外 class                            |
+| `styles`       | `Partial<Record<DialogContentFallbackSlots, ViewStyle>>` | -       | 对话框各部分的样式                                  |
+| `animation`    | `SelectContentAnimation`                                 | -       | 动画配置                                            |
+| `isSwipeable`  | `boolean`                                                | `true`  | 是否允许滑动关闭                                    |
+| `forceMount`   | `boolean`                                                | -       | 是否强制挂载到 DOM                                  |
+| `asChild`      | `boolean`                                                | `false` | 是否将子元素作为实际渲染节点                        |
+| `...ViewProps` | `ViewProps`                                              | -       | 支持全部标准 React Native `View` 属性             |
+
+#### `styles`
+
+| prop      | type        | description                      |
+| --------- | ----------- | -------------------------------- |
+| `wrapper` | `ViewStyle` | 外层包裹容器样式                 |
+| `content` | `ViewStyle` | 对话框内容区样式                 |
+
+#### SelectContentAnimation
+
+`Select.Content`（对话框呈现）的动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认关键帧（scale 与 opacity）
+- `object`：自定义 `entering` 和/或 `exiting` 关键帧
+
+| prop       | type                    | default | description                                                                                              |
+| ---------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -       | 在自定义属性时用于禁用动画                                                                               |
+| `entering` | `EntryOrExitLayoutType` | -       | 进入过渡关键帧（默认：scale 与 opacity，200ms）                                                          |
+| `exiting`  | `EntryOrExitLayoutType` | -       | 退出过渡关键帧（默认：与进入镜像，150ms）                                                              |
+
+### Select.Close
+
+`Select.Close` 继承 [CloseButton](./close-button)，按下时自动关闭选择器。
+
+### Select.ListLabel
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | 列表标题文案                                       |
+| `className`    | `string`    | -       | 列表标题额外 class                                 |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性            |
+
+### Select.Item
+
+| prop                | type                                                         | default | description                                                                |
+| ------------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------------------- |
+| `children`          | `ReactNode \| ((props: SelectItemRenderProps) => ReactNode)` | -       | 自定义选项内容；默认可为标签+指示器，或渲染函数                            |
+| `value`             | `any`                                                        | -       | 选项关联的值（必填）                                                       |
+| `label`             | `string`                                                     | -       | 选项标签文案（必填）                                                       |
+| `isDisabled`        | `boolean`                                                    | `false` | 是否禁用该选项                                                             |
+| `className`         | `string`                                                     | -       | 选项额外 class                                                             |
+| `...PressableProps` | `PressableProps`                                             | -       | 支持全部标准 React Native `Pressable` 属性                                 |
+
+#### SelectItemRenderProps
+
+使用渲染函数作为 `children` 时，会传入以下属性：
+
+| property     | type      | description                             |
+| ------------ | --------- | --------------------------------------- |
+| `isSelected` | `boolean` | 当前项是否选中                          |
+| `value`      | `string`  | 当前项的值                              |
+| `isDisabled` | `boolean` | 当前项是否禁用                          |
+
+### Select.ItemLabel
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | 选项标签额外 class                                 |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性            |
+
+### Select.ItemDescription
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | 说明文案                                           |
+| `className`    | `string`    | -       | 说明额外 class                                     |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性            |
+
+### Select.ItemIndicator
+
+| prop           | type                           | default | description                                        |
+| -------------- | ------------------------------ | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode`                    | -       | 自定义指示器；默认对勾图标                         |
+| `className`    | `string`                       | -       | 指示器额外 class                                   |
+| `iconProps`    | `SelectItemIndicatorIconProps` | -       | 对勾图标配置                                       |
+| `...ViewProps` | `ViewProps`                    | -       | 支持全部标准 React Native `View` 属性            |
+
+#### SelectItemIndicatorIconProps
+
+| prop    | type     | default          | description       |
+| ------- | -------- | ---------------- | ----------------- |
+| `size`  | `number` | `16`             | 图标尺寸          |
+| `color` | `string` | 主题 accent-soft-foreground 颜色 | 图标颜色          |
+
+## Hooks
+
+### useSelect
+
+用于读取 Select 根上下文，返回状态与控制方法。
+
+```tsx
+import { useSelect } from 'heroui-native';
+
+const {
+  isOpen,
+  onOpenChange,
+  isDefaultOpen,
+  isDisabled,
+  presentation,
+  triggerPosition,
+  setTriggerPosition,
+  contentLayout,
+  setContentLayout,
+  nativeID,
+  value,
+  onValueChange,
+} = useSelect();
+```
+
+#### 返回值
+
+| property             | type                                         | description                                               |
+| -------------------- | -------------------------------------------- | --------------------------------------------------------- |
+| `isOpen`             | `boolean`                                    | 当前是否打开                                              |
+| `onOpenChange`       | `(open: boolean) => void`                    | 修改打开状态的回调                                        |
+| `isDefaultOpen`      | `boolean \| undefined`                       | 默认是否打开（非受控）                                    |
+| `isDisabled`         | `boolean \| undefined`                       | 是否禁用                                                  |
+| `presentation`       | `'popover' \| 'bottom-sheet' \| 'dialog'`    | 内容呈现方式                                              |
+| `triggerPosition`    | `LayoutPosition \| null`                     | 触发器相对视口的位置                                      |
+| `setTriggerPosition` | `(position: LayoutPosition \| null) => void` | 更新触发器位置                                            |
+| `contentLayout`      | `LayoutRectangle \| null`                    | 选择器内容的布局测量                                      |
+| `setContentLayout`   | `(layout: LayoutRectangle \| null) => void`  | 更新内容布局测量                                          |
+| `nativeID`           | `string`                                     | 当前实例的唯一标识                                        |
+| `value`              | `SelectOption \| SelectOption[]`                   | 当前选中项                                                |
+| `onValueChange`      | `(option: SelectOption \| SelectOption[]) => void` | 选中值变化时的回调                                        |
+
+**说明：** 必须在 `Select` 内使用；在上下文外调用将抛错。
+
+### useSelectAnimation
+
+用于在自定义或复合子组件中读取 Select 动画相关共享值。
+
+```tsx
+import { useSelectAnimation } from 'heroui-native';
+
+const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } =
+  useSelectAnimation();
+```
+
+#### 返回值
+
+| property                           | type                   | description                                                |
+| ---------------------------------- | ---------------------- | ---------------------------------------------------------- |
+| `progress`                         | `SharedValue<number>`  | 动画进度（0=空闲，1=打开，2=关闭）                         |
+| `isDragging`                       | `SharedValue<boolean>` | 内容是否正在被拖拽                                         |
+| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | 手势释放后的动画是否正在运行                               |
+
+**说明：** 必须在 `Select` 内使用；在动画上下文外调用将抛错。
+
+#### SelectOption
+
+| property | type     | description                  |
+| -------- | -------- | ---------------------------- |
+| `value`  | `string` | 选项值                       |
+| `label`  | `string` | 选项显示标签                 |
+
+### useSelectItem
+
+用于读取 Select Item 上下文，返回当前项的值与标签。
+
+```tsx
+import { useSelectItem } from 'heroui-native';
+
+const { itemValue, label } = useSelectItem();
+```
+
+#### 返回值
+
+| property    | type     | description                        |
+| ----------- | -------- | ---------------------------------- |
+| `itemValue` | `string` | 当前项的值                         |
+| `label`     | `string` | 当前项的标签文案                   |
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+Select 在 iOS 上使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，请在 `Select.Portal` 上设置 `disableFullWindowOverlay={true}`。代价是下拉层将无法叠在原生模态之上。
+
+### 原生模态（iOS）
+
+当 `Select` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），下拉层可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（下拉层挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Select.Content presentation="popover" offset={insets.top + 10}>
+  ...
+</Select.Content>;
+```
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/text-area.mdx b/apps/docs/content/docs/cn/native/components/(forms)/text-area.mdx
new file mode 100644
index 0000000..6cf617a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/text-area.mdx
@@ -0,0 +1,140 @@
+---
+title: TextArea 多行文本框
+description: 多行文本输入，带样式边框与背景，用于收集较长内容。
+links:
+  source_native: text-area/text-area.tsx
+  styles_native: text-area/text-area.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { TextArea } from 'heroui-native';
+```
+
+## 用法
+
+### 基础用法
+
+`TextArea` 可单独使用，也可放在 `TextField` 内。
+
+```tsx
+import { TextArea } from 'heroui-native';
+
+<TextArea placeholder="请输入留言" />
+```
+
+### 与 TextField 组合
+
+与 `TextField` 搭配形成完整表单结构。
+
+```tsx
+import { Description, Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>留言</Label>
+  <TextArea placeholder="请在此输入留言…" />
+  <Description>请尽量提供详细信息。</Description>
+</TextField>
+```
+
+### 校验状态
+
+非法时展示错误样式。
+
+```tsx
+import { FieldError, Label, TextArea, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>留言</Label>
+  <TextArea placeholder="请输入留言" />
+  <FieldError>请输入有效留言</FieldError>
+</TextField>
+```
+
+### 禁用状态
+
+禁用后不可编辑。
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField isDisabled>
+  <Label>禁用字段</Label>
+  <TextArea placeholder="不可编辑" value="只读内容" />
+</TextField>
+```
+
+### 变体
+
+按场景使用不同视觉变体。
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>主要变体</Label>
+  <TextArea placeholder="主要样式文本域" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>次要变体</Label>
+  <TextArea placeholder="次要样式文本域" variant="secondary" />
+</TextField>
+```
+
+### 自定义样式
+
+通过 `className` 自定义外观。
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>自定义样式</Label>
+  <TextArea
+    placeholder="自定义颜色"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>
+```
+
+## 示例
+
+```tsx
+import { Description, FieldError, Label, TextArea, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function TextAreaExample() {
+  return (
+    <View className="gap-8">
+      <TextField>
+        <Label>主要变体</Label>
+        <TextArea placeholder="主要样式文本域" variant="primary" />
+        <Description>默认变体，主要样式</Description>
+      </TextField>
+
+      <TextField>
+        <Label>次要变体</Label>
+        <TextArea
+          placeholder="次要样式文本域"
+          variant="secondary"
+        />
+        <Description>用于表面上的次要变体</Description>
+      </TextField>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-area.tsx)。
+
+## API 参考
+
+`TextArea` 继承 [Input](./input) 的全部属性。区别仅为默认值：`multiline` 默认为 `true`，`textAlignVertical` 默认为 `'top'`。
diff --git a/apps/docs/content/docs/cn/native/components/(forms)/text-field.mdx b/apps/docs/content/docs/cn/native/components/(forms)/text-field.mdx
new file mode 100644
index 0000000..cc379be
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(forms)/text-field.mdx
@@ -0,0 +1,266 @@
+---
+title: TextField 文本输入框
+description: 带标签、说明与错误处理的文本输入，用于收集用户输入。
+links:
+  source_native: text-field/text-field.tsx
+  styles_native: text-field/text-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { TextField } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<TextField>
+  <Label>...</Label>
+  <Input />
+  <Description>...</Description>
+  <FieldError>...</FieldError>
+</TextField>
+```
+
+- **TextField**：根容器，负责间距与状态管理
+- **Label**：标签，必填时可显示星号（见 [Label](./label)）
+- **Input**：带动画边框与背景的输入（见 [Input](./input)）
+- **Description**：辅助说明文字（见 [Description](./description)）
+- **FieldError**：校验错误展示（见 [FieldError](./field-error)）
+
+## 用法
+
+### 基础用法
+
+提供带标签与说明的完整输入结构。
+
+```tsx
+<TextField>
+  <Label>邮箱</Label>
+  <Input placeholder="请输入邮箱" />
+  <Description>我们不会公开您的邮箱</Description>
+</TextField>
+```
+
+### 必填
+
+在必填字段的标签上显示星号。
+
+```tsx
+<TextField isRequired>
+  <Label>用户名</Label>
+  <Input placeholder="请选择用户名" />
+</TextField>
+```
+
+### 校验
+
+非法时展示错误信息。
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>邮箱</Label>
+  <Input placeholder="请输入邮箱" />
+  <FieldError>请输入有效邮箱</FieldError>
+</TextField>;
+```
+
+### 局部覆盖非法状态
+
+为单个部件覆盖上下文的非法状态。
+
+```tsx
+import {
+  Description,
+  FieldError,
+  Input,
+  Label,
+  TextField,
+} from 'heroui-native';
+
+<TextField isInvalid={true}>
+  <Label isInvalid={false}>邮箱</Label>
+  <Input placeholder="请输入邮箱" isInvalid={false} />
+  <Description isInvalid={false}>
+    尽管输入非法，此说明仍可显示
+  </Description>
+  <FieldError>邮箱格式不正确</FieldError>
+</TextField>;
+```
+
+### 多行输入
+
+用于较长内容。
+
+```tsx
+<TextField>
+  <Label>留言</Label>
+  <Input placeholder="请输入留言…" multiline numberOfLines={4} />
+  <Description>最多 500 字</Description>
+</TextField>
+```
+
+### 禁用状态
+
+禁用整个字段。
+
+```tsx
+<TextField isDisabled>
+  <Label>禁用字段</Label>
+  <Input placeholder="不可编辑" value="只读内容" />
+</TextField>
+```
+
+### 变体
+
+按场景切换输入样式。
+
+```tsx
+<TextField>
+  <Label>主要变体</Label>
+  <Input placeholder="主要样式" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>次要变体</Label>
+  <Input placeholder="次要样式" variant="secondary" />
+</TextField>
+```
+
+### 自定义样式
+
+通过 `className` 自定义输入外观。
+
+```tsx
+<TextField>
+  <Label>自定义样式</Label>
+  <Input
+    placeholder="自定义颜色"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>
+```
+
+## 示例
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Description, Input, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export const TextInputContent = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="gap-4">
+      <TextField isRequired>
+        <Label>邮箱</Label>
+        <Input
+          placeholder="请输入邮箱"
+          keyboardType="email-address"
+          autoCapitalize="none"
+          value={email}
+          onChangeText={setEmail}
+        />
+        <Description>
+          我们不会向他人公开您的邮箱。
+        </Description>
+      </TextField>
+
+      <TextField isRequired>
+        <Label>新密码</Label>
+        <View className="w-full flex-row items-center">
+          <Input
+            value={password}
+            onChangeText={setPassword}
+            className="flex-1 px-10"
+            placeholder="请输入密码"
+            secureTextEntry={!isPasswordVisible}
+          />
+          <StyledIonicons
+            name="lock-closed-outline"
+            size={16}
+            className="absolute left-3.5 text-muted"
+            pointerEvents="none"
+          />
+          <Pressable
+            className="absolute right-4"
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+          >
+            <StyledIonicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              className="text-muted"
+            />
+          </Pressable>
+        </View>
+        <Description>密码至少 6 位</Description>
+      </TextField>
+    </View>
+  );
+};
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-field.tsx>)。
+
+## API 参考
+
+### TextField
+
+| prop         | type                         | default     | description                                                                               |
+| ------------ | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children     | `React.ReactNode`            | -           | 文本字段内的子节点                                                                       |
+| isDisabled   | `boolean`                    | `false`     | 是否禁用整个字段                                                                         |
+| isInvalid    | `boolean`                    | `false`     | 是否处于非法状态                                                                         |
+| isRequired   | `boolean`                    | `false`     | 是否必填（显示星号）                                                                     |
+| className    | `string`                     | -           | 根元素自定义 class                                                                       |
+| animation    | `"disable-all" \| undefined` | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                     |
+| ...ViewProps | `ViewProps`                  | -           | 支持 React Native `View` 的全部属性                                                      |
+
+> **说明**：`Label`、`Input`、`Description`、`FieldError` 的详细 API 见各自文档：
+>
+> - [Label](./label)
+> - [Input](./input)
+> - [Description](./description)
+> - [FieldError](./field-error)
+>
+> 这些组件会通过 form-item-state 上下文自动消费 `TextField` 的表单状态。
+
+## Hooks
+
+### useTextField
+
+访问 `TextField` 上下文，必须在 `TextField` 内使用。
+
+```tsx
+import { TextField, useTextField } from 'heroui-native';
+
+function CustomComponent() {
+  const { isDisabled, isInvalid, isRequired } = useTextField();
+
+  // 使用上下文值…
+}
+```
+
+#### 返回值
+
+| property   | type      | description           |
+| ---------- | --------- | --------------------- |
+| isDisabled | `boolean` | 是否禁用整个字段      |
+| isInvalid  | `boolean` | 是否处于非法状态      |
+| isRequired | `boolean` | 是否必填              |
diff --git a/apps/docs/content/docs/cn/native/components/(layout)/card.mdx b/apps/docs/content/docs/cn/native/components/(layout)/card.mdx
new file mode 100644
index 0000000..fd08f6d
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(layout)/card.mdx
@@ -0,0 +1,195 @@
+---
+title: Card 卡片
+description: 卡片容器，提供灵活分区以结构化展示内容。
+links:
+  source_native: card/card.tsx
+  styles_native: card/card.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Card } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+- **Card**：主容器，继承 `Surface`；提供可配置的表面变体与整体布局。
+- **Card.Header**：顶部区域，可放图标、徽章等。
+- **Card.Body**：主内容区，`flex-1` 填充 `Header` 与 `Footer` 之间的空间。
+- **Card.Title**：标题，前景色与中等字重。
+- **Card.Description**：描述，弱化色与较小字号。
+- **Card.Footer**：底部区域，可放按钮等操作。
+
+## 用法
+
+### 基础用法
+
+使用内置分区组织内容。
+
+```tsx
+<Card>
+  <Card.Body>...</Card.Body>
+</Card>
+```
+
+### 标题与描述
+
+组合标题与描述以结构化展示文字。
+
+```tsx
+<Card>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+</Card>
+```
+
+### 页头与页脚
+
+增加顶部与底部区域放置图标、徽章或操作。
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>...</Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+### 变体
+
+通过变体控制卡片背景外观。
+
+```tsx
+<Card variant="default">...</Card>
+<Card variant="secondary">...</Card>
+<Card variant="tertiary">...</Card>
+<Card variant="transparent">...</Card>
+```
+
+### 横向布局
+
+使用 `flex-row` 等样式创建横向卡片。
+
+```tsx
+<Card className="flex-row gap-4">
+  <Image source={...} className="size-24 rounded-lg" />
+</Card>
+```
+
+### 背景图
+
+使用绝对定位图片作为背景。
+
+```tsx
+<Card>
+  <Image source={...} className="absolute inset-0" />
+  <View className="gap-4">...</View>
+</Card>
+```
+
+## 示例
+
+```tsx
+import { Button, Card } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+
+export default function CardExample() {
+  return (
+    <Card>
+      <View className="gap-4">
+        <Card.Body className="mb-4">
+          <View className="gap-1 mb-2">
+            <Card.Title className="text-pink-500">¥450</Card.Title>
+            <Card.Title>客厅沙发 • 2025 系列</Card.Title>
+          </View>
+          <Card.Description>
+            这款沙发适合现代热带风、巴洛克灵感等空间。
+          </Card.Description>
+        </Card.Body>
+        <Card.Footer className="gap-3">
+          <Button variant="primary">立即购买</Button>
+          <Button variant="ghost">
+            <Button.Label>加入购物车</Button.Label>
+            <Ionicons name="bag-outline" size={16} />
+          </Button>
+        </Card.Footer>
+      </View>
+    </Card>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/card.tsx)。
+
+## API 参考
+
+### Card
+
+| prop           | type                                                      | default     | description                                                                               |
+| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                         | -           | 卡片内内容                                                                               |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 卡片表面视觉变体                                                                         |
+| `className`    | `string`                                                  | -           | 额外的 class                                                                             |
+| `animation`    | `"disable-all" \| undefined`                              | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                     |
+| `...ViewProps` | `ViewProps`                                               | -           | 支持 React Native `View` 的全部属性                                                      |
+
+### Card.Header
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 页头内子节点                                       |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |
+
+### Card.Body
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 主内容区子节点                                     |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |
+
+### Card.Footer
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 页脚内子节点                                       |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |
+
+### Card.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题文字                                           |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+### Card.Description
+
+| prop           | type              | default | description                                              |
+| -------------- | ----------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 描述文字                                                 |
+| `className`    | `string`          | -       | 额外的 class                                             |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                      |
diff --git a/apps/docs/content/docs/cn/native/components/(layout)/separator.mdx b/apps/docs/content/docs/cn/native/components/(layout)/separator.mdx
new file mode 100644
index 0000000..a6a3729
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(layout)/separator.mdx
@@ -0,0 +1,116 @@
+---
+title: Separator 分隔符
+description: 用于在视觉上分隔内容的简单线条。
+links:
+  source_native: separator/separator.tsx
+  styles_native: separator/separator.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Separator } from "heroui-native";
+```
+
+## 结构
+
+```tsx
+<Separator />
+```
+
+- **Separator**：简单的分隔线组件，可水平或垂直排列，并支持自定义粗细与变体样式。
+
+## 用法
+
+### 基础用法
+
+在内容区块之间创建视觉分隔。
+
+```tsx
+<Separator />
+```
+
+### 方向
+
+使用 `orientation` 控制分隔线方向。
+
+```tsx
+<View>
+  <Text>水平分隔线</Text>
+  <Separator orientation="horizontal" />
+  <Text>下方内容</Text>
+</View>
+
+<View className="h-24 flex-row">
+  <Text>左侧</Text>
+  <Separator orientation="vertical" />
+  <Text>右侧</Text>
+</View>
+```
+
+### 变体
+
+在细线与粗线之间选择，以强调程度区分。
+
+```tsx
+<Separator variant="thin" />
+<Separator variant="thick" />
+```
+
+### 自定义粗细
+
+使用数值精确控制线条粗细（像素）。
+
+```tsx
+<Separator thickness={1} />
+<Separator thickness={5} />
+<Separator thickness={10} />
+```
+
+## 示例
+
+```tsx
+import { Separator, Surface } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function SeparatorExample() {
+  return (
+    <Surface variant="secondary" className="px-6 py-7">
+      <Text className="text-base font-medium text-foreground">
+        HeroUI Native
+      </Text>
+      <Text className="text-sm text-muted">
+        现代化的 React Native 组件库。
+      </Text>
+      <Separator className="my-4" />
+      <View className="flex-row items-center h-5">
+        <Text className="text-sm text-foreground">组件</Text>
+        <Separator orientation="vertical" className="mx-3" />
+        <Text className="text-sm text-foreground">主题</Text>
+        <Separator orientation="vertical" className="mx-3" />
+        <Text className="text-sm text-foreground">示例</Text>
+      </View>
+    </Surface>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/separator.tsx)。
+
+## API 参考
+
+### Separator
+
+| prop           | type                         | default        | description                                                                                  |
+| -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
+| `variant`      | `'thin' \| 'thick'`          | `'thin'`       | 分隔线样式变体                                                                               |
+| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | 分隔线方向                                                                                   |
+| `thickness`    | `number`                     | `undefined`    | 自定义粗细（像素）；水平时控制高度，垂直时控制宽度                                           |
+| `className`    | `string`                     | `undefined`    | 额外的 class                                                                                 |
+| `...ViewProps` | `ViewProps`                  | -              | 支持 React Native `View` 的全部属性                                                         |
diff --git a/apps/docs/content/docs/cn/native/components/(layout)/surface.mdx b/apps/docs/content/docs/cn/native/components/(layout)/surface.mdx
new file mode 100644
index 0000000..fdaf3c0
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(layout)/surface.mdx
@@ -0,0 +1,146 @@
+---
+title: Surface 表面
+description: 提供层级与背景样式的容器组件。
+icon: updated
+links:
+  source_native: surface/surface.tsx
+  styles_native: surface/surface.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Surface } from 'heroui-native';
+```
+
+## 结构
+
+Surface 是提供层级与背景样式的容器，可包裹子内容，并通过变体与样式属性定制外观。
+
+```tsx
+<Surface>...</Surface>
+```
+
+- **Surface**：主容器，通过变体提供一致的内边距、背景与层级感。
+
+## 用法
+
+### 基础用法
+
+Surface 用于创建具有一致内边距与样式的容器。
+
+```tsx
+<Surface>...</Surface>
+```
+
+### 变体
+
+通过不同层级控制视觉外观。
+
+```tsx
+<Surface variant="default">
+  ...
+</Surface>
+
+<Surface variant="secondary">
+  ...
+</Surface>
+
+<Surface variant="tertiary">
+  ...
+</Surface>
+```
+
+### 嵌套 Surface
+
+使用不同变体嵌套，形成视觉层级。
+
+```tsx
+<Surface variant="default">
+  ...
+  <Surface variant="secondary">
+    ...
+    <Surface variant="tertiary">...</Surface>
+  </Surface>
+</Surface>
+```
+
+### 自定义样式
+
+通过 `className` 或 `style` 传入自定义样式。
+
+```tsx
+<Surface className="bg-accent-soft">
+  ...
+</Surface>
+
+<Surface variant="tertiary" className="p-0">
+  ...
+</Surface>
+```
+
+### 禁用全部动画
+
+将 `animation` 设为 `"disable-all"` 可禁用自身及子级的全部动画。
+
+```tsx
+{
+  /* 禁用自身及子级的全部动画 */
+}
+<Surface animation="disable-all">无动画</Surface>;
+```
+
+## 示例
+
+```tsx
+import { Surface } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function SurfaceExample() {
+  return (
+    <View className="gap-4">
+      <Surface variant="default" className="gap-2">
+        <AppText className="text-foreground">表面内容</AppText>
+        <AppText className="text-muted">
+          默认表面变体，使用 bg-surface 样式。
+        </AppText>
+      </Surface>
+
+      <Surface variant="secondary" className="gap-2">
+        <AppText className="text-foreground">表面内容</AppText>
+        <AppText className="text-muted">
+          次要表面变体，使用 bg-surface-secondary 样式。
+        </AppText>
+      </Surface>
+
+      <Surface variant="tertiary" className="gap-2">
+        <AppText className="text-foreground">表面内容</AppText>
+        <AppText className="text-muted">
+          第三级表面变体，使用 bg-surface-tertiary 样式。
+        </AppText>
+      </Surface>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/surface.tsx)。
+
+## API 参考
+
+### Surface
+
+| prop           | type                                                      | default     | description                                                                               |
+| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 视觉变体，控制背景色与边框                                                                |
+| `children`     | `React.ReactNode`                                         | -           | 渲染在表面内的内容                                                                       |
+| `className`    | `string`                                                  | -           | 额外的 class                                                                             |
+| `animation`    | `"disable-all" \| undefined`                              | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                     |
+| `asChild`      | `boolean`                                                 | `false`     | 是否以子元素方式渲染                                                                     |
+| `...ViewProps` | `ViewProps`                                               | -           | 支持 React Native `View` 的全部属性                                                      |
diff --git a/apps/docs/content/docs/cn/native/components/(media)/avatar.mdx b/apps/docs/content/docs/cn/native/components/(media)/avatar.mdx
new file mode 100644
index 0000000..ac1a086
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(media)/avatar.mdx
@@ -0,0 +1,396 @@
+---
+title: Avatar 头像
+description: 展示用户头像，支持图片、文字首字母或回退图标。
+links:
+  source_native: avatar/avatar.tsx
+  styles_native: avatar/avatar.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Avatar } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Avatar>
+  <Avatar.Image />
+  <Avatar.Fallback />
+</Avatar>
+```
+
+- **Avatar**：主容器，管理头像展示状态，向子组件提供尺寸与颜色上下文；可通过动画配置统一控制子级动画。
+- **Avatar.Image**：可选图片组件，展示头像；自动处理加载与错误，并以不透明度淡入。
+- **Avatar.Fallback**：图片加载失败或不可用时显示；无子节点时显示默认人像图标；支持可配置的进入动画与延迟。
+
+## 用法
+
+### 基础用法
+
+未提供图片或文字时，显示默认人像图标。
+
+```tsx
+<Avatar>
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### 使用图片
+
+展示头像图片并自动处理回退。
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 文字首字母
+
+使用首字母作为头像内容。
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar>
+```
+
+### 自定义图标
+
+以自定义图标作为回退内容。
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>
+    <Ionicons name="person" size={18} />
+  </Avatar.Fallback>
+</Avatar>
+```
+
+### 尺寸
+
+使用 `size` 控制头像大小。
+
+```tsx
+<Avatar size="sm">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="md">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="lg">
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### 变体
+
+使用 `variant` 切换视觉风格。
+
+```tsx
+<Avatar variant="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar variant="soft">
+  <Avatar.Fallback>SF</Avatar.Fallback>
+</Avatar>
+```
+
+### 颜色
+
+应用不同颜色变体。
+
+```tsx
+<Avatar color="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="accent">
+  <Avatar.Fallback>AC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="success">
+  <Avatar.Fallback>SC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="warning">
+  <Avatar.Fallback>WR</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="danger">
+  <Avatar.Fallback>DG</Avatar.Fallback>
+</Avatar>
+```
+
+### 延迟显示回退
+
+延迟显示回退，避免图片加载时的闪烁。
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+</Avatar>
+```
+
+### 自定义图片组件
+
+配合 `asChild` 使用自定义图片组件。
+
+```tsx
+import { Image } from 'expo-image';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} asChild>
+    <Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
+  </Avatar.Image>
+  <Avatar.Fallback>EI</Avatar.Fallback>
+</Avatar>;
+```
+
+### 动画控制
+
+在 Avatar 不同层级控制动画。
+
+#### 禁用全部动画
+
+在根组件禁用自身及子级的全部动画：
+
+```tsx
+<Avatar animation="disable-all">
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### 自定义图片动画
+
+自定义图片不透明度动画：
+
+```tsx
+<Avatar>
+  <Avatar.Image
+    source={{ uri: imageUrl }}
+    animation={{
+      opacity: {
+        value: [0.3, 1],
+        timingConfig: { duration: 300 },
+      },
+    }}
+  />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### 自定义回退动画
+
+自定义回退进入动画：
+
+```tsx
+import { FadeInDown } from 'react-native-reanimated';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback
+    animation={{
+      entering: {
+        value: FadeInDown.duration(400),
+      },
+    }}
+  >
+    JD
+  </Avatar.Fallback>
+</Avatar>;
+```
+
+#### 单独禁用动画
+
+对指定子组件禁用动画：
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} animation={false} />
+  <Avatar.Fallback animation="disabled">JD</Avatar.Fallback>
+</Avatar>
+```
+
+## 示例
+
+```tsx
+import { Avatar } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function AvatarExample() {
+  const users = [
+    { id: 1, image: 'https://example.com/user1.jpg', name: '张 三' },
+    { id: 2, image: 'https://example.com/user2.jpg', name: '李 四' },
+    { id: 3, image: 'https://example.com/user3.jpg', name: '王 五' },
+  ];
+
+  return (
+    <View className="flex-row gap-4">
+      {users.map((user) => (
+        <Avatar key={user.id} size="lg" color="accent">
+          <Avatar.Image source={{ uri: user.image }} />
+          <Avatar.Fallback>
+            {user.name
+              .split(' ')
+              .map((n) => n[0])
+              .join('')}
+          </Avatar.Fallback>
+        </Avatar>
+      ))}
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/avatar.tsx)。
+
+## API 参考
+
+### Avatar
+
+| prop           | type                                                          | default     | description                                                                               |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | 头像内容（`Image` 与/或 `Fallback`）                                                     |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | 尺寸                                                                                      |
+| `variant`      | `'default' \| 'soft'`                                         | `'default'` | 视觉变体                                                                                  |
+| `color`        | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | 颜色变体                                                                                  |
+| `className`    | `string`                                                      | -           | 额外的 class                                                                              |
+| `animation`    | `"disable-all"` \| `undefined`                                | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                       |
+| `alt`          | `string`                                                      | -           | 无障碍替代文本描述                                                                        |
+| `...ViewProps` | `ViewProps`                                                   | -           | 支持 React Native `View` 的全部属性                                                       |
+
+### Avatar.Image
+
+根据 `asChild` 扩展不同的基础类型：
+
+- `asChild={false}`（默认）：扩展自 React Native Reanimated 的 `AnimatedProps<ImageProps>`
+- `asChild={true}`：扩展自定义图片组件的原语图片属性
+
+**说明：** `asChild={true}` 时，取决于自定义组件实现，`className` 可能不会生效；请确保自定义组件正确处理样式 props。
+
+| prop                    | type                                           | default | description                                                  |
+| ----------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
+| `source`                | `ImageSourcePropType`                          | -       | 图片源（`asChild={false}` 时必填）                         |
+| `asChild`               | `boolean`                                      | `false` | 是否使用自定义图片子组件                                     |
+| `className`             | `string`                                       | -       | 额外的 class                                                 |
+| `animation`             | `AvatarImageAnimation`                         | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                                      | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `...AnimatedProps`      | `AnimatedProps<ImageProps>` or primitive props | -       | 随 `asChild` 变化的额外属性                                  |
+
+#### AvatarImageAnimation
+
+图片动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                   | type                    | default                                             | description                          |
+| ---------------------- | ----------------------- | --------------------------------------------------- | ------------------------------------ |
+| `state`                | `'disabled' \| boolean` | -                                                   | 在自定义属性时禁用动画               |
+| `opacity.value`        | `[number, number]`      | `[0, 1]`                                            | 不透明度 [初始, 已加载]              |
+| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200, easing: Easing.in(Easing.ease) }` | 时间曲线配置                         |
+
+**说明：** `asChild={true}` 时动画会自动禁用。
+
+### Avatar.Fallback
+
+| prop                    | type                                                          | default               | description                                                                       |
+| ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                                             | -                     | 回退内容（文字、图标或自定义节点）                                                |
+| `delayMs`               | `number`                                                      | `0`                   | 显示回退前的延迟（毫秒），作用于进入动画                                          |
+| `color`                 | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | 回退颜色变体                                                                      |
+| `className`             | `string`                                                      | -                     | 容器额外 class                                                                    |
+| `classNames`            | `ElementSlots<AvatarFallbackSlots>`                           | -                     | 各部分额外 class                                                                  |
+| `styles`                | `{ container?: ViewStyle; text?: TextStyle }`                 | -                     | 回退各部分的样式                                                                  |
+| `textProps`             | `TextProps`                                                   | -                     | 子节点为字符串时传给 `Text` 的属性                                                |
+| `iconProps`             | `PersonIconProps`                                             | -                     | 自定义默认人像图标的属性                                                          |
+| `animation`             | `AvatarFallbackAnimation`                                     | -                     | 动画配置                                                                          |
+| `...Animated.ViewProps` | `Animated.ViewProps`                                          | -                     | 支持 Reanimated `Animated.View` 的全部属性                                        |
+
+**classNames：** `ElementSlots<AvatarFallbackSlots>` 提供类型安全的 class。可用插槽：`container`、`text`。
+
+#### `styles`
+
+| prop        | type        | description |
+| ----------- | ----------- | ----------- |
+| `container` | `ViewStyle` | 容器样式    |
+| `text`      | `TextStyle` | 文字样式    |
+
+#### AvatarFallbackAnimation
+
+回退动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                    | default                                                                             | description              |
+| ---------------- | ----------------------- | ----------------------------------------------------------------------------------- | ------------------------ |
+| `state`          | `'disabled' \| boolean` | -                                                                                   | 在自定义属性时禁用动画   |
+| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))`<br/>`.delay(0)` | 自定义进入动画           |
+
+#### PersonIconProps
+
+| prop    | type     | description      |
+| ------- | -------- | ---------------- |
+| `size`  | `number` | 图标尺寸（可选） |
+| `color` | `string` | 图标颜色（可选） |
+
+## Hooks
+
+### useAvatar
+
+访问 Avatar 根上下文，获取头像状态。
+
+**说明：** `status` 常用于在图片加载时显示骨架屏。
+
+```tsx
+import { Avatar, useAvatar, Skeleton } from 'heroui-native';
+
+function AvatarWithSkeleton() {
+  return (
+    <Avatar>
+      <Avatar.Image source={{ uri: imageUrl }} />
+      <AvatarContent />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar>
+  );
+}
+
+function AvatarContent() {
+  const { status } = useAvatar();
+
+  if (status === 'loading') {
+    return <Skeleton className="absolute inset-0 rounded-full" />;
+  }
+
+  return null;
+}
+```
+
+| property    | type                                                 | description                          |
+| ----------- | ---------------------------------------------------- | ------------------------------------ |
+| `status`    | `'loading' \| 'loaded' \| 'error'`                   | 当前图片加载状态                     |
+| `setStatus` | `(status: 'loading' \| 'loaded' \| 'error') => void` | 手动设置状态（高级用法）             |
+
+**状态含义：**
+
+- `'loading'`：图片加载中，可显示骨架屏
+- `'loaded'`：图片加载成功
+- `'error'`：加载失败或资源无效，会自动显示回退
diff --git a/apps/docs/content/docs/cn/native/components/(navigation)/accordion.mdx b/apps/docs/content/docs/cn/native/components/(navigation)/accordion.mdx
new file mode 100644
index 0000000..f80c580
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(navigation)/accordion.mdx
@@ -0,0 +1,447 @@
+---
+title: Accordion 手风琴
+description: 可折叠内容面板，在紧凑空间内组织信息
+links:
+  source_native: accordion/accordion.tsx
+  styles_native: accordion/accordion.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-dark-1.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Accordion } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Accordion>
+  <Accordion.Item>
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator>...</Accordion.Indicator>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+- **Accordion**：主容器，管理手风琴状态与行为；控制各条目的展开/收起，支持单选或多选展开模式，并提供 `default` 或 `surface` 等视觉变体。
+- **Accordion.Item**：单个条目的容器，包裹触发器与内容，并管理该条目的展开状态。
+- **Accordion.Trigger**：用于切换条目展开的可交互区域，基于 Header 与 Trigger 原语构建。
+- **Accordion.Indicator**：可选的视觉指示器，展示展开状态；默认使用随状态旋转的动画 chevron 图标。
+- **Accordion.Content**：可展开内容的容器，配合布局过渡动画实现平滑展开/收起。
+
+## 用法
+
+### 基础用法
+
+Accordion 通过复合子组件创建可展开的内容区块。
+
+```tsx
+<Accordion selectionMode="single">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 单选模式
+
+同一时间只允许展开一个条目。
+
+```tsx
+<Accordion selectionMode="single" defaultValue="2">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 多选模式
+
+允许多个条目同时展开。
+
+```tsx
+<Accordion selectionMode="multiple" defaultValue={['1', '3']}>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="3">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Surface 变体
+
+为手风琴应用表面容器样式。
+
+```tsx
+<Accordion selectionMode="single" variant="surface">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 自定义指示器
+
+用自定义内容替换默认 chevron 指示器。
+
+```tsx
+<Accordion selectionMode="single">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator>
+        <CustomIndicator />
+      </Accordion.Indicator>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 无分隔线
+
+隐藏条目之间的分隔线。
+
+```tsx
+<Accordion selectionMode="single" hideSeparator>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 自定义样式
+
+通过 `className`、`classNames` 或 `styles` 传入自定义样式。
+
+```tsx
+<Accordion
+  className="rounded-lg"
+  classNames={{
+    container: 'bg-surface',
+    separator: 'bg-separator/50',
+  }}
+  styles={{
+    container: { padding: 16 },
+    separator: { height: 2 },
+  }}
+>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 配合 PressableFeedback
+
+对 `Accordion.Trigger` 使用 `asChild`，并用 `PressableFeedback` 包裹内容以添加按压反馈动画。
+
+```tsx
+import { Accordion, PressableFeedback } from 'heroui-native';
+import { View } from 'react-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger asChild>
+      <PressableFeedback animation={{ scale: false }}>
+        <PressableFeedback.Scale className="flex-row items-center flex-1 gap-3">
+          <Text>条目标题</Text>
+        </PressableFeedback.Scale>
+        <Accordion.Indicator />
+        <PressableFeedback.Highlight
+          animation={{ opacity: { value: [0, 0.05] } }}
+        />
+      </PressableFeedback>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>;
+```
+
+## 示例
+
+```tsx
+import { Accordion, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View, Text } from 'react-native';
+
+export default function AccordionExample() {
+  const themeColorMuted = useThemeColor('muted');
+
+  const accordionData = [
+    {
+      id: '1',
+      title: '如何下单？',
+      icon: <Ionicons name="bag-outline" size={16} color={themeColorMuted} />,
+      content:
+        '这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
+    },
+    {
+      id: '2',
+      title: '支持哪些支付方式？',
+      icon: <Ionicons name="card-outline" size={16} color={themeColorMuted} />,
+      content:
+        '这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
+    },
+    {
+      id: '3',
+      title: '运费如何计算？',
+      icon: <Ionicons name="cube-outline" size={16} color={themeColorMuted} />,
+      content:
+        '这是一段示例说明文字，用于演示折叠面板中的正文内容展示效果。',
+    },
+  ];
+
+  return (
+    <Accordion selectionMode="single" variant="surface" defaultValue="2">
+      {accordionData.map((item) => (
+        <Accordion.Item key={item.id} value={item.id}>
+          <Accordion.Trigger>
+            <View className="flex-row items-center flex-1 gap-3">
+              {item.icon}
+              <Text className="text-foreground text-base flex-1">
+                {item.title}
+              </Text>
+            </View>
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+          <Accordion.Content>
+            <Text className="text-muted text-base/relaxed px-[25px]">
+              {item.content}
+            </Text>
+          </Accordion.Content>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/accordion.tsx)。
+
+## API 参考
+
+### Accordion
+
+| prop                    | type                                               | default     | description                                                    |
+| ----------------------- | -------------------------------------------------- | ----------- | -------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                                  | -           | 渲染在手风琴内的子节点                                         |
+| `selectionMode`         | `'single' \| 'multiple'`                           | -           | 允许单条或多条同时展开                                         |
+| `variant`               | `'default' \| 'surface'`                           | `'default'` | 手风琴视觉变体                                                 |
+| `hideSeparator`         | `boolean`                                          | `false`     | 是否隐藏条目之间的分隔线                                       |
+| `defaultValue`          | `string \| string[] \| undefined`                  | -           | 非受控模式下的默认展开项                                       |
+| `value`                 | `string \| string[] \| undefined`                  | -           | 受控模式下的当前展开项                                         |
+| `isDisabled`            | `boolean`                                          | -           | 是否禁用全部条目                                               |
+| `isCollapsible`         | `boolean`                                          | `true`      | 已展开条目是否可再次收起                                       |
+| `animation`             | `AccordionRootAnimation`                           | -           | 根级动画配置                                                   |
+| `className`             | `string`                                           | -           | 容器的额外 class                                               |
+| `classNames`            | `ElementSlots<RootSlots>`                          | -           | 各插槽的额外 class                                             |
+| `styles`                | `Partial<Record<RootSlots, ViewStyle>>`            | -           | 根组件各部分的样式                                             |
+| `onValueChange`         | `(value: string \| string[] \| undefined) => void` | -           | 展开项变化时的回调                                             |
+| `...Animated.ViewProps` | `Animated.ViewProps`                               | -           | 支持 Reanimated `Animated.View` 的全部属性                     |
+
+#### `ElementSlots<RootSlots>`
+
+| prop        | type     | description                         |
+| ----------- | -------- | ----------------------------------- |
+| `container` | `string` | 手风琴容器的自定义 class            |
+| `separator` | `string` | 条目之间分隔线的自定义 class        |
+
+#### `styles`
+
+| prop        | type        | description            |
+| ----------- | ----------- | ---------------------- |
+| `container` | `ViewStyle` | 手风琴容器样式         |
+| `separator` | `ViewStyle` | 条目之间分隔线样式     |
+
+#### AccordionRootAnimation
+
+手风琴根组件的动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根级动画
+- `"disable-all"`：禁用全部动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop           | type                                     | default                                                                                         | description                            |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `state`        | `'disabled' \| 'disable-all' \| boolean` | -                                                                                               | 在自定义属性时禁用动画                 |
+| `layout.value` | `LayoutTransition`                       | `LinearTransition`<br/>`.springify()`<br/>`.damping(140)`<br/>`.stiffness(1600)`<br/>`.mass(4)` | 手风琴过渡的自定义布局动画           |
+
+### Accordion.Item
+
+| prop                    | type                                                                        | default | description                                                                      |
+| ----------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode \| ((props: AccordionItemRenderProps) => React.ReactNode)` | -       | 条目内的子节点，或渲染函数                                                       |
+| `value`                 | `string`                                                                    | -       | 唯一标识该条目的值                                                               |
+| `isDisabled`            | `boolean`                                                                   | -       | 是否禁用该条目                                                                   |
+| `className`             | `string`                                                                    | -       | 额外的 class                                                                     |
+| `...Animated.ViewProps` | `Animated.ViewProps`                                                        | -       | 支持 Reanimated `Animated.View` 的全部属性                                       |
+
+#### AccordionItemRenderProps
+
+| prop         | type      | description              |
+| ------------ | --------- | ------------------------ |
+| `isExpanded` | `boolean` | 当前条目是否展开         |
+| `value`      | `string`  | 该条目的唯一值           |
+
+### Accordion.Trigger
+
+| prop                | type              | default | description                          |
+| ------------------- | ----------------- | ------- | ------------------------------------ |
+| `children`          | `React.ReactNode` | -       | 触发器内的子节点                     |
+| `className`         | `string`          | -       | 额外的 class                         |
+| `isDisabled`        | `boolean`         | -       | 是否禁用触发器                       |
+| `...PressableProps` | `PressableProps`  | -       | 支持 React Native `Pressable` 的属性 |
+
+### Accordion.Indicator
+
+| prop                    | type                          | default | description                                              |
+| ----------------------- | ----------------------------- | ------- | -------------------------------------------------------- |
+| `children`              | `React.ReactNode`             | -       | 自定义指示器内容；未提供时默认为带动画的 chevron         |
+| `className`             | `string`                      | -       | 额外的 class                                             |
+| `iconProps`             | `AccordionIndicatorIconProps` | -       | 图标配置                                                 |
+| `animation`             | `AccordionIndicatorAnimation` | -       | 指示器动画配置                                           |
+| `isAnimatedStyleActive` | `boolean`                     | `true`  | 是否启用 Reanimated 动画样式                             |
+| `...Animated.ViewProps` | `Animated.ViewProps`          | -       | 支持 Reanimated `Animated.View` 的全部属性               |
+
+#### AccordionIndicatorIconProps
+
+| prop    | type     | default      | description |
+| ------- | -------- | ------------ | ----------- |
+| `size`  | `number` | `16`         | 图标尺寸    |
+| `color` | `string` | `foreground` | 图标颜色  |
+
+#### AccordionIndicatorAnimation
+
+指示器动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                    | type                    | default                                      | description                                      |
+| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
+| `state`                 | `'disabled' \| boolean` | -                                            | 在自定义属性时禁用动画                           |
+| `rotation.value`        | `[number, number]`      | `[0, -180]`                                  | 旋转角度 [收起, 展开]，单位为度                |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | 旋转弹簧动画配置                                 |
+
+### Accordion.Content
+
+| prop           | type                        | default | description                        |
+| -------------- | --------------------------- | ------- | ---------------------------------- |
+| `children`     | `React.ReactNode`           | -       | 内容区域内的子节点                 |
+| `className`    | `string`                    | -       | 额外的 class                       |
+| `animation`    | `AccordionContentAnimation` | -       | 内容动画配置                       |
+| `...ViewProps` | `ViewProps`                 | -       | 支持 React Native `View` 的属性    |
+
+#### AccordionContentAnimation
+
+内容区动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop             | type                    | default                                                              | description              |
+| ---------------- | ----------------------- | -------------------------------------------------------------------- | ------------------------ |
+| `state`          | `'disabled' \| boolean` | -                                                                    | 在自定义属性时禁用动画   |
+| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | 自定义进入动画         |
+| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))` | 自定义退出动画           |
+
+## Hooks
+
+### useAccordion
+
+访问手风琴根上下文，必须在 `Accordion` 内使用。
+
+```tsx
+import { useAccordion } from 'heroui-native';
+
+const { value, onValueChange, selectionMode, isCollapsible, isDisabled } =
+  useAccordion();
+```
+
+#### 返回值
+
+| property        | type                                                                  | description                                      |
+| --------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
+| `selectionMode` | `'single' \| 'multiple' \| undefined`                                 | 单选或多选展开模式                               |
+| `value`         | `(string \| undefined) \| string[]`                                   | 当前展开项：单选为字符串，多选为数组             |
+| `onValueChange` | `(value: string \| undefined) => void \| ((value: string[]) => void)` | 更新展开项的回调                               |
+| `isCollapsible` | `boolean`                                                             | 已展开项是否可收起                               |
+| `isDisabled`    | `boolean \| undefined`                                                | 是否禁用全部条目                                 |
+
+### useAccordionItem
+
+访问单条条目上下文，必须在 `Accordion.Item` 内使用。
+
+```tsx
+import { useAccordionItem } from 'heroui-native';
+
+const { value, isExpanded, isDisabled, nativeID } = useAccordionItem();
+```
+
+#### 返回值
+
+| property     | type                   | description                          |
+| ------------ | ---------------------- | ------------------------------------ |
+| `value`      | `string`               | 该条目的唯一值                       |
+| `isExpanded` | `boolean`              | 当前是否展开                         |
+| `isDisabled` | `boolean \| undefined` | 该条目是否禁用                       |
+| `nativeID`   | `string`               | 无障碍与 ARIA 使用的原生 ID          |
+
+## 特别说明
+
+当 Accordion 与同屏其他组件一起使用时，请为这些组件导入并应用 `AccordionLayoutTransition`，以保证整屏布局动画一致、顺滑。
+
+```jsx
+import { Accordion, AccordionLayoutTransition } from 'heroui-native';
+import Animated from 'react-native-reanimated';
+
+<Animated.ScrollView layout={AccordionLayoutTransition}>
+  <Animated.View layout={AccordionLayoutTransition}>
+    {/* 其他内容 */}
+  </Animated.View>
+
+  <Accordion>{/* 手风琴条目 */}</Accordion>
+</Animated.ScrollView>;
+```
+
+这样在展开或收起时，屏幕上各组件会使用相同的时长与缓动，体验更统一。
diff --git a/apps/docs/content/docs/cn/native/components/(navigation)/list-group.mdx b/apps/docs/content/docs/cn/native/components/(navigation)/list-group.mdx
new file mode 100644
index 0000000..6f59743
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(navigation)/list-group.mdx
@@ -0,0 +1,397 @@
+---
+title: ListGroup 列表组
+description: 基于 Surface 的容器，用于分组展示列表项并保持一致的布局与间距。
+links:
+  source_native: list-group/list-group.tsx
+  styles_native: list-group/list-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { ListGroup } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>...</ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>...</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>...</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+- **ListGroup**：基于 Surface 的根容器，用于分组列表项；支持全部 Surface 变体（`default`、`secondary`、`tertiary`、`transparent`）。
+- **ListGroup.Item**：可按压的水平 `flex-row` 行容器，提供统一的间距与对齐。
+- **ListGroup.ItemPrefix**：可选前导槽，用于图标、头像等。
+- **ListGroup.ItemContent**：`flex-1` 包裹标题与说明，占据剩余横向空间。
+- **ListGroup.ItemTitle**：主标题，前景色与中等字重。
+- **ListGroup.ItemDescription**：次要说明，弱化颜色与较小字号。
+- **ListGroup.ItemSuffix**：可选尾部槽；默认渲染右箭头；传入子节点可覆盖默认图标。
+
+## 用法
+
+### 基础用法
+
+通过组合子部件创建带标题与说明的分组列表。
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        姓名、邮箱、手机号
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Visa 尾号 4829
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### 带图标
+
+使用 `ListGroup.ItemPrefix` 放置前置图标。
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="person-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>个人资料</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        姓名、照片、简介
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="lock-closed-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>安全</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        密码、双重验证
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### 仅标题
+
+省略 `ListGroup.ItemDescription` 以展示仅标题行。
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="wifi-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="bluetooth-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>蓝牙</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Surface 变体
+
+为根容器应用不同的视觉变体。
+
+```tsx
+<ListGroup variant="transparent">
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### 自定义尾部
+
+向 `ListGroup.ItemSuffix` 传入子节点以覆盖默认箭头。
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>语言</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>简体中文</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Icon name="arrow-forward" size={18} />
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Chip variant="primary" color="danger">
+        <Chip.Label className="font-bold">7</Chip.Label>
+      </Chip>
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### 自定义尾部图标属性
+
+通过 `iconProps` 调整默认箭头尺寸与颜色。
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>存储空间</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        已用 12.4 GB / 共 50 GB
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### 配合 PressableFeedback
+
+用 `PressableFeedback` 包裹列表项以添加缩放与水波纹反馈。此模式下将 `onPress` 放在 `PressableFeedback` 上，并对 `ListGroup.Item` 使用 `disabled`。
+
+```tsx
+import { ListGroup, PressableFeedback, Separator } from 'heroui-native';
+
+<ListGroup>
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            主题、字号、显示
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+  <Separator className="mx-4" />
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            提醒、声音、角标
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+</ListGroup>
+```
+
+## 示例
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { ListGroup, Separator, useThemeColor } from 'heroui-native';
+import { View, Text } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function ListGroupExample() {
+  const mutedColor = useThemeColor('muted');
+
+  return (
+    <View className="flex-1 justify-center px-5">
+      <Text className="text-sm text-muted mb-2 ml-2">账户</Text>
+      <ListGroup className="mb-6">
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="person-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              姓名、邮箱、手机号
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="card-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Visa 尾号 4829
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+      </ListGroup>
+      <Text className="text-sm text-muted mb-2 ml-2">偏好设置</Text>
+      <ListGroup>
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="color-palette-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              主题、字号、显示
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="notifications-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              提醒、声音、角标
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+        </ListGroup.Item>
+      </ListGroup>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/list-group.tsx)。
+
+## API 参考
+
+### ListGroup
+
+| prop           | type                                                       | default     | description                                        |
+| -------------- | ---------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                          | -           | 分组内的子节点                                     |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 底层 Surface 容器的视觉变体                      |
+| `className`    | `string`                                                   | -           | 根容器额外 class                                   |
+| `...ViewProps` | `ViewProps`                                                | -           | 支持全部标准 React Native `View` 属性              |
+
+### ListGroup.Item
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | 列表行内的子节点                                        |
+| `className`         | `string`          | -       | 列表行额外 class                                        |
+| `...PressableProps` | `PressableProps`  | -       | 支持全部标准 React Native `Pressable` 属性              |
+
+### ListGroup.ItemPrefix
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | 前导内容，如图标或头像                                 |
+| `className`    | `string`          | -       | 前导区域额外 class                                     |
+| `...ViewProps` | `ViewProps`       | -       | 支持全部标准 React Native `View` 属性                  |
+
+### ListGroup.ItemContent
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | 内容区，通常为标题与说明                               |
+| `className`    | `string`          | -       | 内容区额外 class                                       |
+| `...ViewProps` | `ViewProps`       | -       | 支持全部标准 React Native `View` 属性                  |
+
+### ListGroup.ItemTitle
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题文本或自定义内容                               |
+| `className`    | `string`          | -       | 标题额外 class                                     |
+| `...ViewProps` | `ViewProps`       | -       | 支持全部标准 React Native `View` 属性              |
+
+### ListGroup.ItemDescription
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 说明文本或自定义内容                               |
+| `className`    | `string`          | -       | 说明额外 class                                     |
+| `...ViewProps` | `ViewProps`       | -       | 支持全部标准 React Native `View` 属性              |
+
+### ListGroup.ItemSuffix
+
+| prop           | type                 | default | description                                                                        |
+| -------------- | -------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`    | -       | 自定义尾部内容；提供时将覆盖默认右箭头图标                                         |
+| `className`    | `string`             | -       | 尾部额外 class                                                                     |
+| `iconProps`    | `ListGroupIconProps` | -       | 自定义默认右箭头图标；仅在无 `children` 时生效                                     |
+| `...ViewProps` | `ViewProps`          | -       | 支持全部标准 React Native `View` 属性                                              |
+
+#### ListGroupIconProps
+
+| prop    | type     | default             | description                        |
+| ------- | -------- | ------------------- | ---------------------------------- |
+| `size`  | `number` | `16`                | 箭头图标尺寸（像素）               |
+| `color` | `string` | 主题的 `muted` 颜色 | 箭头图标颜色                       |
diff --git a/apps/docs/content/docs/cn/native/components/(navigation)/tabs.mdx b/apps/docs/content/docs/cn/native/components/(navigation)/tabs.mdx
new file mode 100644
index 0000000..5a898c2
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(navigation)/tabs.mdx
@@ -0,0 +1,579 @@
+---
+title: Tabs 标签页
+description: 使用选项卡视图组织内容，支持动画过渡与指示器。
+links:
+  source_native: tabs/tabs.tsx
+  styles_native: tabs/tabs.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Tabs } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Tabs>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger>
+        <Tabs.Label>...</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator />
+      <Tabs.Trigger>
+        <Tabs.Label>...</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content>...</Tabs.Content>
+</Tabs>
+```
+
+- **Tabs**：管理选项卡状态与选中的根容器。控制当前激活项、处理值变化，并向子组件提供上下文。
+- **Tabs.List**：放置选项卡触发器的容器。将多个触发器组合在一起，并支持 `primary` 或 `secondary` 等样式变体。
+- **Tabs.ScrollView**：可选的横向滚动容器。当标签溢出时可横向滚动，并可在选中时自动居中。
+- **Tabs.Trigger**：每个选项卡的交互触发器。处理按压以切换激活项，并测量位置以驱动指示器动画。
+- **Tabs.Label**：触发器上的文字标签，用于展示选项卡标题及对应样式。
+- **Tabs.Indicator**：当前激活项的可视指示器，可在选项卡之间以弹簧或时长动画平滑过渡。
+- **Tabs.Separator**：选项卡之间的分隔线。当当前值不在 `betweenValues` 数组中时显示，并带有透明度过渡动画。
+- **Tabs.Content**：面板内容容器。当其 `value` 与当前激活项一致时显示对应内容。
+
+## 用法
+
+### 基础用法
+
+Tabs 使用复合子组件，将内容划分为可切换的区域。
+
+```tsx
+<Tabs defaultValue="tab1">
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="tab1">
+      <Tabs.Label>标签一</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="tab2">
+      <Tabs.Label>标签二</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="tab1">...</Tabs.Content>
+  <Tabs.Content value="tab2">...</Tabs.Content>
+</Tabs>
+```
+
+### 主样式（primary）
+
+默认圆角主样式，选中项背后为填充指示器。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="settings">
+      <Tabs.Label>设置</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="profile">
+      <Tabs.Label>个人资料</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="settings">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+### 次样式（secondary）
+
+下划线指示器，视觉更轻量。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab} variant="secondary">
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="overview">
+      <Tabs.Label>概览</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="analytics">
+      <Tabs.Label>分析</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="overview">...</Tabs.Content>
+  <Tabs.Content value="analytics">...</Tabs.Content>
+</Tabs>
+```
+
+### 可滚动标签
+
+标签较多时通过横向滚动容纳。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView scrollAlign="center">
+      <Tabs.Indicator />
+      <Tabs.Trigger value="tab1">
+        <Tabs.Label>第一个</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab2">
+        <Tabs.Label>第二个</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab3">
+        <Tabs.Label>第三个</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab4">
+        <Tabs.Label>第四个</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab5">
+        <Tabs.Label>第五个</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content value="tab1">...</Tabs.Content>
+  <Tabs.Content value="tab2">...</Tabs.Content>
+  <Tabs.Content value="tab3">...</Tabs.Content>
+  <Tabs.Content value="tab4">...</Tabs.Content>
+  <Tabs.Content value="tab5">...</Tabs.Content>
+</Tabs>
+```
+
+### 禁用标签
+
+使用 `isDisabled` 禁止与特定标签交互。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="active">
+      <Tabs.Label>可用</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="disabled" isDisabled>
+      <Tabs.Label>已禁用</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="another">
+      <Tabs.Label>其他</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="active">...</Tabs.Content>
+  <Tabs.Content value="another">...</Tabs.Content>
+</Tabs>
+```
+
+### 与图标组合
+
+图标与文字并用，信息更直观。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="home">
+      <Icon name="home" size={16} />
+      <Tabs.Label>首页</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="search">
+      <Icon name="search" size={16} />
+      <Tabs.Label>搜索</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="home">...</Tabs.Content>
+  <Tabs.Content value="search">...</Tabs.Content>
+</Tabs>
+```
+
+### 使用渲染函数
+
+在 `Tabs.Trigger` 上使用渲染函数，可读取选中状态并按需自定义内容。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="settings">
+      {({ isSelected, value, isDisabled }) => (
+        <Tabs.Label
+          className={isSelected ? 'text-accent font-medium' : 'text-foreground'}
+        >
+          设置
+        </Tabs.Label>
+      )}
+    </Tabs.Trigger>
+    <Tabs.Trigger value="profile">
+      {({ isSelected }) => (
+        <>
+          <Icon name="user" size={16} />
+          <Tabs.Label className={isSelected ? 'text-accent' : 'text-muted'}>
+            个人资料
+          </Tabs.Label>
+        </>
+      )}
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="settings">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+### 与分隔线配合
+
+在标签之间添加分隔线；可见性由 `betweenValues` 与当前激活项共同决定（详见下方 API）。
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger value="general">
+        <Tabs.Label>通用</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={['general', 'notifications']} />
+      <Tabs.Trigger value="notifications">
+        <Tabs.Label>通知</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={['notifications', 'profile']} />
+      <Tabs.Trigger value="profile">
+        <Tabs.Label>个人资料</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content value="general">...</Tabs.Content>
+  <Tabs.Content value="notifications">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+## 示例
+
+```tsx
+import {
+  Button,
+  Checkbox,
+  Description,
+  ControlField,
+  Label,
+  Tabs,
+  TextField,
+} from 'heroui-native';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+import Animated, {
+  FadeIn,
+  FadeOut,
+  LinearTransition,
+} from 'react-native-reanimated';
+
+const AnimatedContentContainer = ({
+  children,
+}: {
+  children: React.ReactNode;
+}) => (
+  <Animated.View
+    entering={FadeIn.duration(200)}
+    exiting={FadeOut.duration(200)}
+    className="gap-6"
+  >
+    {children}
+  </Animated.View>
+);
+
+export default function TabsExample() {
+  const [activeTab, setActiveTab] = useState('general');
+
+  const [showSidebar, setShowSidebar] = useState(true);
+  const [accountActivity, setAccountActivity] = useState(true);
+  const [name, setName] = useState('');
+
+  return (
+    <Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
+      <Tabs.List>
+        <Tabs.ScrollView>
+          <Tabs.Indicator />
+          <Tabs.Trigger value="general">
+            <Tabs.Label>通用</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="notifications">
+            <Tabs.Label>通知</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="profile">
+            <Tabs.Label>个人资料</Tabs.Label>
+          </Tabs.Trigger>
+        </Tabs.ScrollView>
+      </Tabs.List>
+
+      <Animated.View
+        layout={LinearTransition.duration(200)}
+        className="px-4 py-6 border border-border rounded-xl"
+      >
+        <Tabs.Content value="general">
+          <AnimatedContentContainer>
+            <ControlField
+              isSelected={showSidebar}
+              onSelectedChange={setShowSidebar}
+            >
+              <ControlField.Indicator variant="checkbox" />
+              <View className="flex-1">
+                <Label>显示侧边栏</Label>
+                <Description>显示侧边导航面板</Description>
+              </View>
+            </ControlField>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+
+        <Tabs.Content value="notifications">
+          <AnimatedContentContainer>
+            <ControlField
+              isSelected={accountActivity}
+              onSelectedChange={setAccountActivity}
+            >
+              <ControlField.Indicator variant="checkbox" />
+              <View className="flex-1">
+                <Label>账户动态</Label>
+                <Description>接收与账户活动相关的通知</Description>
+              </View>
+            </ControlField>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+
+        <Tabs.Content value="profile">
+          <AnimatedContentContainer>
+            <TextField isRequired>
+              <Label>姓名</Label>
+              <Input
+                value={name}
+                onChangeText={setName}
+                placeholder="请输入全名"
+              />
+            </TextField>
+            <Button size="sm" className="self-start">
+              <Button.Label>更新资料</Button.Label>
+            </Button>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+      </Animated.View>
+    </Tabs>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tabs.tsx>)。
+
+## API 参考
+
+### Tabs
+
+| prop            | type                         | 默认值     | 描述                                                                               |
+| --------------- | ---------------------------- | ---------- | ---------------------------------------------------------------------------------- |
+| `children`      | `React.ReactNode`            | -          | 渲染在 Tabs 内的子元素                                                           |
+| `value`         | `string`                     | -          | 当前激活的标签值                                                                 |
+| `variant`       | `'primary' \| 'secondary'`   | `'primary'` | 视觉变体                                                                         |
+| `className`     | `string`                     | -          | 根容器额外 className                                                              |
+| `animation`     | `"disable-all" \| undefined` | `undefined` | 动画配置。设为 `"disable-all"` 可关闭全部动画（含子树）                         |
+| `onValueChange` | `(value: string) => void`    | -          | 激活标签变化时的回调                                                             |
+| `...ViewProps`  | `ViewProps`                  | -          | 支持 React Native `View` 的全部标准属性                                          |
+
+### Tabs.List
+
+| prop           | type              | 默认值 | 描述                                        |
+| -------------- | ----------------- | ------ | ------------------------------------------- |
+| `children`     | `React.ReactNode` | -      | 渲染在列表内的子元素                        |
+| `className`    | `string`          | -      | 额外 className                              |
+| `...ViewProps` | `ViewProps`       | -      | 支持 React Native `View` 的全部标准属性     |
+
+### Tabs.ScrollView
+
+| prop                        | type                                     | 默认值    | 描述                                              |
+| --------------------------- | ---------------------------------------- | --------- | ------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -         | 渲染在滚动视图内的子元素                          |
+| `scrollAlign`               | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | 选中项的滚动对齐方式                            |
+| `className`                 | `string`                                 | -         | 滚动容器额外 className                          |
+| `contentContainerClassName` | `string`                                 | -         | 内容容器额外 className                          |
+| `...ScrollViewProps`        | `ScrollViewProps`                        | -         | 支持 React Native `ScrollView` 的全部标准属性   |
+
+### Tabs.Trigger
+
+| prop                | type                                                                      | 默认值  | 描述                                                               |
+| ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `children`          | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | -       | 子节点，或接收 `TabsTriggerRenderProps` 的渲染函数                 |
+| `value`             | `string`                                                                  | -       | 唯一标识该标签的值                                                 |
+| `isDisabled`        | `boolean`                                                                 | `false` | 是否禁用该触发器                                                 |
+| `className`         | `string`                                                                  | -       | 额外 className                                                     |
+| `...PressableProps` | `PressableProps`                                                          | -       | 支持 React Native `Pressable` 的全部标准属性                       |
+
+#### TabsTriggerRenderProps
+
+使用渲染函数作为 `children` 时，会传入以下属性：
+
+| property     | type      | 描述                     |
+| ------------ | --------- | ------------------------ |
+| `isSelected` | `boolean` | 当前触发器是否被选中     |
+| `value`      | `string`  | 该触发器的值             |
+| `isDisabled` | `boolean` | 该触发器是否禁用         |
+
+### Tabs.Label
+
+| prop           | type              | 默认值 | 描述                                        |
+| -------------- | ----------------- | ------ | ------------------------------------------- |
+| `children`     | `React.ReactNode` | -      | 作为标签渲染的文本内容                      |
+| `className`    | `string`          | -      | 额外 className                              |
+| `...TextProps` | `TextProps`       | -      | 支持 React Native `Text` 的全部标准属性     |
+
+### Tabs.Indicator
+
+| prop                    | type                     | 默认值 | 描述                                                  |
+| ----------------------- | ------------------------ | ------ | ----------------------------------------------------- |
+| `children`              | `React.ReactNode`        | -      | 自定义指示器内容                                      |
+| `className`             | `string`                 | -      | 额外 className                                        |
+| `animation`             | `TabsIndicatorAnimation` | -      | 动画配置                                              |
+| `isAnimatedStyleActive` | `boolean`                | `true` | 是否启用 Reanimated 动画样式                        |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -      | 支持 Reanimated `Animated.View` 的全部属性          |
+
+#### TabsIndicatorAnimation
+
+`Tabs.Indicator` 的动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭所有动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                | type                                   | 默认值                                                                      | 描述                               |
+| ------------------- | -------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- |
+| `state`             | `'disabled' \| boolean`                | -                                                                           | 自定义属性时用于禁用动画           |
+| `width.type`        | `'spring' \| 'timing'`                 | `'spring'`                                                                  | 宽度动画类型                       |
+| `width.config`      | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }`（spring）或 `{ duration: 200 }`（timing） | Reanimated 动画配置        |
+| `height.type`       | `'spring' \| 'timing'`                 | `'spring'`                                                                  | 高度动画类型                       |
+| `height.config`     | `WithSpringConfig \| WithTimingConfig` | 同上                                                                        | Reanimated 动画配置                |
+| `translateX.type`   | `'spring' \| 'timing'`                 | `'spring'`                                                                  | 水平位移动画类型                   |
+| `translateX.config` | `WithSpringConfig \| WithTimingConfig` | 同上                                                                        | Reanimated 动画配置                |
+
+### Tabs.Separator
+
+| prop                    | type                     | 默认值  | 描述                                                                                                                            |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `betweenValues`         | `string[]`               | -       | 分隔线两侧对应的标签值数组。当**当前**标签值**不在**该数组中时，分隔线可见（与可见性动画联动）                                 |
+| `isAlwaysVisible`       | `boolean`                | `false` | 为 `true` 时透明度恒为 1，不受当前标签影响                                                                                     |
+| `className`             | `string`                 | -       | 额外 className                                                                                                                  |
+| `animation`             | `TabsSeparatorAnimation` | -       | 动画配置                                                                                                                        |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | 是否启用 Reanimated 动画样式                                                                                                    |
+| `children`              | `React.ReactNode`        | -       | 自定义分隔线内容                                                                                                                |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | 支持 Reanimated `Animated.View` 的全部属性                                                                                      |
+
+**说明：** 以下样式属性由动画占用，不能仅通过 `className` 覆盖：
+
+- `opacity`：用于分隔线显隐过渡（当前标签在 `betweenValues` 内时为 0，否则为 1）
+
+若要调整这些属性，请使用 `animation`。若需完全关闭动画样式、改用自己的 `className` 或 `style`，请设置 `isAnimatedStyleActive={false}`。
+
+#### TabsSeparatorAnimation
+
+`Tabs.Separator` 的动画配置，可为：
+
+- `false` 或 `"disabled"`：关闭所有动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                   | type                    | 默认值             | 描述                               |
+| ---------------------- | ----------------------- | ------------------ | ---------------------------------- |
+| `state`                | `'disabled' \| boolean` | -                  | 自定义属性时用于禁用动画           |
+| `opacity.value`        | `[number, number]`      | `[0, 1]`           | 透明度区间 [隐藏, 显示]            |
+| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200 }` | 时长类动画配置                  |
+
+### Tabs.Content
+
+| prop           | type              | 默认值 | 描述                                        |
+| -------------- | ----------------- | ------ | ------------------------------------------- |
+| `children`     | `React.ReactNode` | -      | 渲染在面板内的子元素                        |
+| `value`        | `string`          | -      | 该内容与哪个标签值对应                      |
+| `className`    | `string`          | -      | 额外 className                              |
+| `...ViewProps` | `ViewProps`       | -      | 支持 React Native `View` 的全部标准属性     |
+
+## Hooks
+
+### useTabs
+
+在自定义组件或复合子组件中读取 Tabs 根上下文。
+
+```tsx
+import { useTabs } from 'heroui-native';
+
+const CustomComponent = () => {
+  const { value, onValueChange, nativeID } = useTabs();
+  // ...你的实现
+};
+```
+
+#### 返回值
+
+类型：`UseTabsReturn`
+
+| property        | type                      | 描述                     |
+| --------------- | ------------------------- | ------------------------ |
+| `value`         | `string`                  | 当前激活的标签值         |
+| `onValueChange` | `(value: string) => void` | 用于切换激活标签的回调   |
+| `nativeID`      | `string`                  | 该 Tabs 实例的唯一标识   |
+
+**说明：** 必须在 `Tabs` 内使用；在上下文外调用会抛错。
+
+### useTabsMeasurements
+
+读取标签测量上下文，用于管理各触发器的位置与尺寸。
+
+```tsx
+import { useTabsMeasurements } from 'heroui-native';
+
+const CustomIndicator = () => {
+  const { measurements, variant } = useTabsMeasurements();
+  // ...你的实现
+};
+```
+
+#### 返回值
+
+类型：`UseTabsMeasurementsReturn`
+
+| property          | type                                                    | 描述                               |
+| ----------------- | ------------------------------------------------------- | ---------------------------------- |
+| `measurements`    | `Record<string, ItemMeasurements>`                      | 各标签触发器的测量数据             |
+| `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | 更新指定触发器的测量数据           |
+| `variant`         | `'primary' \| 'secondary'`                              | 当前 Tabs 的视觉变体               |
+
+#### ItemMeasurements
+
+| property | type     | 描述                 |
+| -------- | -------- | -------------------- |
+| `width`  | `number` | 触发器宽度（像素）   |
+| `height` | `number` | 触发器高度（像素）   |
+| `x`      | `number` | 触发器的 x 坐标      |
+
+**说明：** 必须在 `Tabs` 内使用；在上下文外调用会抛错。
+
+### useTabsTrigger
+
+在自定义组件或复合子组件中读取单个 `Tabs.Trigger` 的上下文。
+
+```tsx
+import { useTabsTrigger } from 'heroui-native';
+
+const CustomLabel = () => {
+  const { value, isSelected, nativeID } = useTabsTrigger();
+  // ...你的实现
+};
+```
+
+#### 返回值
+
+类型：`UseTabsTriggerReturn`
+
+| property     | type      | 描述                     |
+| ------------ | --------- | ------------------------ |
+| `value`      | `string`  | 该触发器的值             |
+| `nativeID`   | `string`  | 该触发器的唯一标识       |
+| `isSelected` | `boolean` | 当前触发器是否被选中     |
+
+**说明：** 必须在 `Tabs.Trigger` 内使用；在上下文外调用会抛错。
diff --git a/apps/docs/content/docs/cn/native/components/(overlays)/bottom-sheet.mdx b/apps/docs/content/docs/cn/native/components/(overlays)/bottom-sheet.mdx
new file mode 100644
index 0000000..71a1685
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(overlays)/bottom-sheet.mdx
@@ -0,0 +1,359 @@
+---
+title: BottomSheet 底部弹层
+description: 自底部滑入的底部表单，带动画与下滑关闭手势。
+icon: updated
+links:
+  source_native: bottom-sheet/bottom-sheet.tsx
+  styles_native: bottom-sheet/bottom-sheet.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { BottomSheet } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay>...</BottomSheet.Overlay>
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>...</BottomSheet.Title>
+      <BottomSheet.Description>...</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+- **BottomSheet**：根组件，管理开关状态并向子级提供上下文。
+- **BottomSheet.Trigger**：按下后打开底部表单的可按压区域。
+- **BottomSheet.Portal**：在 Portal 中渲染，使用全屏覆盖层。
+- **BottomSheet.Overlay**：覆盖全屏的背景层，按下通常可关闭。
+- **BottomSheet.Content**：主容器，基于 @gorhom/bottom-sheet 渲染并支持手势。
+- **BottomSheet.Close**：关闭按钮；可自定义子节点或使用默认关闭图标。
+- **BottomSheet.Title**：标题，语义标题角色并关联无障碍。
+- **BottomSheet.Description**：说明文字，并关联无障碍。
+
+## 用法
+
+### 基础底部表单
+
+包含标题、描述与关闭按钮的简单示例。
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger asChild>
+    <Button>打开底部表单</Button>
+  </BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>...</BottomSheet.Title>
+      <BottomSheet.Description>...</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### 悬浮（Detached）
+
+与底边留出间距的悬浮样式。
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content
+      detached={true}
+      bottomInset={insets.bottom + 12}
+      className="mx-4"
+      backgroundClassName="rounded-[32px]"
+    >
+      ...
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### 多停靠点与滚动
+
+多档高度与可滚动内容。
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content snapPoints={['25%', '50%', '90%']}>
+      <ScrollView>...</ScrollView>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### 自定义遮罩
+
+用模糊等自定义内容替换默认遮罩。
+
+```tsx
+import { useBottomSheet, useBottomSheetAnimation } from 'heroui-native';
+import { StyleSheet, Pressable } from 'react-native';
+import { interpolate, useDerivedValue } from 'react-native-reanimated';
+import { AnimatedBlurView } from './animated-blur-view';
+import { useUniwind } from 'uniwind';
+
+export const BottomSheetBlurOverlay = () => {
+  const { theme } = useUniwind();
+  const { onOpenChange } = useBottomSheet();
+  const { progress } = useBottomSheetAnimation();
+
+  const blurIntensity = useDerivedValue(() => {
+    return interpolate(progress.get(), [0, 1, 2], [0, 40, 0]);
+  });
+
+  return (
+    <Pressable
+      style={StyleSheet.absoluteFill}
+      onPress={() => onOpenChange(false)}
+    >
+      <AnimatedBlurView
+        blurIntensity={blurIntensity}
+        tint={theme === 'dark' ? 'dark' : 'systemUltraThinMaterialDark'}
+        style={StyleSheet.absoluteFill}
+      />
+    </Pressable>
+  );
+};
+```
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheetBlurOverlay />
+    <BottomSheet.Content>...</BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+## 示例
+
+```tsx
+import { BottomSheet, Button } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { withUniwind } from 'uniwind';
+import Ionicons from '@expo/vector-icons/Ionicons';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function BottomSheetExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
+      <BottomSheet.Trigger asChild>
+        <Button variant="secondary">打开底部表单</Button>
+      </BottomSheet.Trigger>
+      <BottomSheet.Portal>
+        <BottomSheet.Overlay />
+        <BottomSheet.Content>
+          <View className="items-center mb-5">
+            <View className="size-20 items-center justify-center rounded-full bg-green-500/10">
+              <StyledIonicons
+                name="shield-checkmark"
+                size={40}
+                className="text-green-500"
+              />
+            </View>
+          </View>
+          <View className="mb-8 gap-2 items-center">
+            <BottomSheet.Title className="text-center">
+              保持安全
+            </BottomSheet.Title>
+            <BottomSheet.Description className="text-center">
+              将软件更新到最新版本，以获得更好的安全性与性能。
+            </BottomSheet.Description>
+          </View>
+          <View className="gap-3">
+            <Button onPress={() => setIsOpen(false)}>立即更新</Button>
+            <Button variant="tertiary" onPress={() => setIsOpen(false)}>
+              稍后
+            </Button>
+          </View>
+        </BottomSheet.Content>
+      </BottomSheet.Portal>
+    </BottomSheet>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/bottom-sheet.tsx)。
+
+## API 参考
+
+### BottomSheet
+
+| prop            | type                       | default | description                                        |
+| --------------- | -------------------------- | ------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`          | -       | 触发器与底部表单内容                               |
+| `isOpen`        | `boolean`                  | -       | 受控开关状态                                       |
+| `isDefaultOpen` | `boolean`                  | `false` | 非受控初始是否打开                                 |
+| `animation`     | `AnimationRootDisableAll`  | -       | 动画配置                                           |
+| `onOpenChange`  | `(value: boolean) => void` | -       | 开关状态变化回调                                   |
+| `...ViewProps`  | `ViewProps`                | -       | 支持 React Native `View` 的全部属性                |
+
+#### 动画配置
+
+根动画配置，可为：
+
+- `"disable-all"`：禁用全部动画（含子级）
+- `undefined`：使用默认动画
+
+### BottomSheet.Trigger
+
+| prop                       | type                    | default | description                                                    |
+| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`       | -       | 触发器内容                                                     |
+| `asChild`                  | `boolean`               | -       | 是否无包裹渲染为子元素                                         |
+| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | 支持 React Native `TouchableOpacity` 的全部属性                |
+
+### BottomSheet.Portal
+
+| prop                                         | type                   | default | description                                                                                                                                                                                                      |
+| -------------------------------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`                                   | `React.ReactNode`      | -       | Portal 内容（遮罩与底部表单）                                                                                                                                                                                    |
+| `disableFullWindowOverlay`                   | `boolean`              | `false` | iOS 为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于检查器；遮罩不再叠在原生模态之上                                                                                                                    |
+| `unstable_accessibilityContainerViewIsModal` | `boolean`              | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。仅 iOS；可能随 react-native-screens 变化                                                                                                                                 |
+| `className`                                  | `string`               | -       | Portal 容器额外 class                                                                                                                                                                                            |
+| `style`                                      | `StyleProp<ViewStyle>` | -       | Portal 容器额外样式                                                                                                                                                                                              |
+| `hostName`                                   | `string`               | -       | 可选 Portal 宿主名                                                                                                                                                                                               |
+| `forceMount`                                 | `boolean`              | -       | 关闭时仍挂载以配合动画                                                                                                                                                                                           |
+
+### BottomSheet.Overlay
+
+| prop                    | type                                                   | default | description                                                  |
+| ----------------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                                      | -       | 自定义遮罩内容                                               |
+| `className`             | `string`                                               | -       | 遮罩额外 class                                               |
+| `style`                 | `ViewStyle`                                            | -       | 遮罩容器样式                                                 |
+| `animation`             | `Omit<PopupOverlayAnimation, 'entering' \| 'exiting'>` | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                                              | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `isCloseOnPress`        | `boolean`                                              | `true`  | 按下遮罩是否关闭                                             |
+| `...PressableProps`     | `PressableProps`                                       | -       | 支持 React Native `Pressable` 的全部属性                     |
+
+#### 动画配置
+
+遮罩动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置（不含 `entering` / `exiting`）
+
+| prop            | type                       | default     | description                                     |
+| --------------- | -------------------------- | ----------- | ----------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -           | 在自定义属性时禁用动画                          |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | 不透明度 [空闲, 打开, 关闭]                     |
+
+### BottomSheet.Content
+
+| prop                        | type                                     | default | description                                                                                        |
+| --------------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -       | 底部表单内容                                                                                       |
+| `className`                 | `string`                                 | -       | 容器额外 class                                                                                     |
+| `containerClassName`        | `string`                                 | -       | 外层容器 class                                                                                     |
+| `contentContainerClassName` | `string`                                 | -       | 内容区 class                                                                                       |
+| `backgroundClassName`       | `string`                                 | -       | 背景 class                                                                                         |
+| `handleClassName`           | `string`                                 | -       | 拖动手柄区域 class                                                                                 |
+| `handleIndicatorClassName`  | `string`                                 | -       | 手柄指示条 class                                                                                   |
+| `contentContainerProps`     | `Omit<BottomSheetViewProps, 'children'>` | -       | 内容容器 props                                                                                     |
+| `animation`                 | `AnimationDisabled`                      | -       | 动画配置                                                                                           |
+| `...GorhomBottomSheetProps` | `Partial<GorhomBottomSheetProps>`        | -       | 支持 [@gorhom/bottom-sheet 全部 props](https://gorhom.dev/react-native-bottom-sheet/props)        |
+
+**说明：** 内容区内可使用 [@gorhom/bottom-sheet 组件](https://gorhom.dev/react-native-bottom-sheet/components/bottomsheetview)，如 `BottomSheetView`、`BottomSheetScrollView`、`BottomSheetFlatList` 等。
+
+### BottomSheet.Close
+
+`BottomSheet.Close` 继承 [CloseButton](./close-button)，按下时自动关闭底部表单。
+
+### BottomSheet.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题内容                                           |
+| `className`    | `string`          | -       | 标题额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                  |
+
+### BottomSheet.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 描述内容                                           |
+| `className`    | `string`          | -       | 描述额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+## Hooks
+
+### useBottomSheet
+
+访问底部表单原语上下文。
+
+```tsx
+const { isOpen, onOpenChange } = useBottomSheet();
+```
+
+| property       | type                       | description     |
+| -------------- | -------------------------- | ----------------- |
+| `isOpen`       | `boolean`                  | 当前是否打开      |
+| `onOpenChange` | `(value: boolean) => void` | 修改开关状态      |
+
+### useBottomSheetAnimation
+
+访问底部表单动画上下文。
+
+```tsx
+const { progress } = useBottomSheetAnimation();
+```
+
+| property   | type                  | description                                  |
+| ---------- | --------------------- | -------------------------------------------- |
+| `progress` | `SharedValue<number>` | 动画进度（0=空闲，1=打开，2=关闭）           |
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+`BottomSheet` 在 iOS 使用 `FullWindowOverlay`，位于独立原生窗口，会破坏 React Native 元素检查器。开发时可在 `BottomSheet.Portal` 设置 `disableFullWindowOverlay={true}`。代价：底部表单将无法叠在原生系统模态之上。
+
+### 关闭回调
+
+建议使用 `BottomSheet` 的 `onOpenChange` 处理关闭逻辑，可在所有关闭场景可靠触发（下滑、点遮罩、点关闭、程序化关闭等）。
+
+```tsx
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={(value) => {
+    setIsOpen(value);
+    if (!value) {
+      // 任意方式关闭时都会执行
+      yourCallbackOnClose();
+    }
+  }}
+>
+  ...
+</BottomSheet>
+```
+
+**说明：** `@gorhom/bottom-sheet` 在 `BottomSheet.Content` 上的 `onClose` 仅在下滑关闭时触发，点遮罩、关闭按钮或程序化关闭不会触发。需要可靠关闭回调时请使用根组件的 `onOpenChange`。
diff --git a/apps/docs/content/docs/cn/native/components/(overlays)/dialog.mdx b/apps/docs/content/docs/cn/native/components/(overlays)/dialog.mdx
new file mode 100644
index 0000000..6fed92f
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(overlays)/dialog.mdx
@@ -0,0 +1,299 @@
+---
+title: Dialog 对话框
+description: 模态浮层，带动画过渡并支持手势关闭。
+icon: updated
+links:
+  source_native: dialog/dialog.tsx
+  styles_native: dialog/dialog.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Dialog } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Dialog>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay>...</Dialog.Overlay>
+    <Dialog.Content>
+      <Dialog.Close>...</Dialog.Close>
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+- **Dialog**：根组件，管理开关状态并向子级提供上下文。
+- **Dialog.Trigger**：按下后打开对话框的可按压区域。
+- **Dialog.Portal**：在 Portal 中渲染内容，居中布局并控制动画。
+- **Dialog.Overlay**：内容背后的遮罩，按下通常可关闭对话框。
+- **Dialog.Content**：主容器，支持拖拽关闭等手势。
+- **Dialog.Close**：关闭按钮；可自定义子节点或使用默认关闭图标。
+- **Dialog.Title**：标题，语义为标题角色。
+- **Dialog.Description**：补充说明文字。
+
+## 用法
+
+### 基础对话框
+
+包含标题、描述与关闭按钮的简单对话框。
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger asChild>
+    <Button>打开对话框</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### 可滚动内容
+
+长内容使用滚动容器承载。
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <View className="h-[300px]">
+        <ScrollView>...</ScrollView>
+      </View>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### 表单对话框
+
+包含输入与键盘避让的对话框。
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <KeyboardAvoidingView behavior="padding">
+      <Dialog.Content>
+        <Dialog.Close />
+        <Dialog.Title>...</Dialog.Title>
+        <TextField>...</TextField>
+        <Button onPress={handleSubmit}>提交</Button>
+      </Dialog.Content>
+    </KeyboardAvoidingView>
+  </Dialog.Portal>
+</Dialog>
+```
+
+## 示例
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+import { View } from 'react-native';
+import { useState } from 'react';
+
+export default function DialogExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+      <Dialog.Trigger asChild>
+        <Button variant="primary">打开对话框</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Close variant="ghost" />
+          <View className="mb-5 gap-1.5">
+            <Dialog.Title>确认操作</Dialog.Title>
+            <Dialog.Description>
+              确定要继续吗？此操作无法撤销。
+            </Dialog.Description>
+          </View>
+          <View className="flex-row justify-end gap-3">
+            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
+              取消
+            </Button>
+            <Button size="sm">确认</Button>
+          </View>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/dialog.tsx)。
+
+## API 参考
+
+### Dialog
+
+| prop            | type                       | default | description                                        |
+| --------------- | -------------------------- | ------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`          | -       | 触发器与对话框内容                                 |
+| `isOpen`        | `boolean`                  | -       | 受控开关状态                                       |
+| `isDefaultOpen` | `boolean`                  | `false` | 非受控初始是否打开                                 |
+| `animation`     | `AnimationRootDisableAll`  | -       | 动画配置                                           |
+| `onOpenChange`  | `(value: boolean) => void` | -       | 开关状态变化回调                                   |
+| `...ViewProps`  | `ViewProps`                | -       | 支持 React Native `View` 的全部属性                |
+
+#### AnimationRootDisableAll
+
+根动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根级动画
+- `"disable-all"`：禁用全部动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+
+### Dialog.Trigger
+
+| prop                       | type                    | default | description                                                    |
+| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`       | -       | 触发器内容                                                     |
+| `asChild`                  | `boolean`               | -       | 是否无包裹渲染为子元素                                         |
+| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | 支持 React Native `TouchableOpacity` 的全部属性                |
+
+### Dialog.Portal
+
+| prop                       | type                   | default | description                                                                                                                   |
+| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`      | -       | Portal 内容（遮罩与对话框）                                                                                                   |
+| `disableFullWindowOverlay` | `boolean`              | `false` | iOS 为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于检查器；遮罩不再叠在原生模态之上                                   |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。仅 iOS；可能随 react-native-screens 变化                                              |
+| `className`                | `string`               | -       | Portal 容器额外 class                                                                                                         |
+| `style`                    | `StyleProp<ViewStyle>` | -       | Portal 容器额外样式                                                                                                           |
+| `hostName`                 | `string`               | -       | 可选 Portal 宿主名                                                                                                            |
+| `forceMount`               | `boolean`              | -       | 关闭时仍挂载以配合动画                                                                                                        |
+
+### Dialog.Overlay
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`        | -       | 自定义遮罩内容                                               |
+| `className`             | `string`                 | -       | 遮罩额外 class                                               |
+| `style`                 | `ViewStyle`              | -       | 遮罩容器样式                                                 |
+| `animation`             | `DialogOverlayAnimation` | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `isCloseOnPress`        | `boolean`                | `true`  | 按下遮罩是否关闭                                             |
+| `forceMount`            | `boolean`                | -       | 关闭时仍挂载以配合动画                                       |
+| `...PressableProps`     | `PressableProps`         | -       | 支持 React Native `Pressable` 的全部属性                     |
+
+#### DialogOverlayAnimation
+
+遮罩动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop            | type                       | default                 | description                                                                  |
+| --------------- | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -                       | 在自定义属性时禁用动画                                                       |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`             | 不透明度 [空闲, 打开, 关闭]（基于进度，用于呈现）                             |
+| `entering`      | `EntryOrExitLayoutType`    | `FadeIn.duration(200)`  | 自定义进入动画（Popover 呈现用）                                             |
+| `exiting`       | `EntryOrExitLayoutType`    | `FadeOut.duration(150)` | 自定义退出动画（Popover 呈现用）                                             |
+
+### Dialog.Content
+
+| prop                    | type                     | default | description                                         |
+| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
+| `children`              | `React.ReactNode`        | -       | 对话框内容                                          |
+| `className`             | `string`                 | -       | 内容容器额外 class                                    |
+| `style`                 | `StyleProp<ViewStyle>`   | -       | 内容容器额外样式                                      |
+| `animation`             | `DialogContentAnimation` | -       | 动画配置                                            |
+| `isSwipeable`           | `boolean`                | `true`  | 是否可滑动关闭                                      |
+| `forceMount`            | `boolean`                | -       | 关闭时仍挂载以配合动画                              |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | 支持 Reanimated `Animated.View` 的全部属性          |
+
+#### DialogContentAnimation
+
+内容动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop       | type                    | default                                                                                     | description                                     |
+| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -                                                                                           | 在自定义属性时禁用动画                          |
+| `entering` | `EntryOrExitLayoutType` | 关键帧 `scale: 0.96→1` 与 `opacity: 0→1`（200ms，缓动 `Easing.out(Easing.ease)`）           | 自定义进入动画                                  |
+| `exiting`  | `EntryOrExitLayoutType` | 关键帧 `scale: 1→0.96` 与 `opacity: 1→0`（150ms，缓动 `Easing.in(Easing.ease)`）            | 自定义退出动画                                  |
+
+### Dialog.Close
+
+`Dialog.Close` 继承 [CloseButton](./close-button)，按下时自动关闭对话框。
+
+### Dialog.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题内容                                           |
+| `className`    | `string`          | -       | 标题额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                  |
+
+### Dialog.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 描述内容                                           |
+| `className`    | `string`          | -       | 描述额外 class                                     |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+## Hooks
+
+### useDialog
+
+访问对话框原语上下文。
+
+```tsx
+const { isOpen, onOpenChange } = useDialog();
+```
+
+| property       | type                       | description     |
+| -------------- | -------------------------- | ----------------- |
+| `isOpen`       | `boolean`                  | 当前是否打开      |
+| `onOpenChange` | `(value: boolean) => void` | 修改开关状态      |
+
+### useDialogAnimation
+
+访问对话框动画上下文，用于高级定制。
+
+```tsx
+const { progress, isDragging, isGestureReleaseAnimationRunning } =
+  useDialogAnimation();
+```
+
+| property                           | type                   | description                                  |
+| ---------------------------------- | ---------------------- | -------------------------------------------- |
+| `progress`                         | `SharedValue<number>`  | 动画进度（0=空闲，1=打开，2=关闭）           |
+| `isDragging`                       | `SharedValue<boolean>` | 是否正在拖拽                                 |
+| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | 手势释放动画是否进行中                       |
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+`Dialog` 在 iOS 使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，可在 `Dialog.Portal` 设置 `disableFullWindowOverlay={true}`。代价：对话框将无法叠在原生系统模态之上。
diff --git a/apps/docs/content/docs/cn/native/components/(overlays)/popover.mdx b/apps/docs/content/docs/cn/native/components/(overlays)/popover.mdx
new file mode 100644
index 0000000..1c66176
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(overlays)/popover.mdx
@@ -0,0 +1,531 @@
+---
+title: Popover 弹出框
+description: 锚定在触发器上的浮动内容面板，支持方位与对齐选项。
+icon: updated
+links:
+  source_native: popover/popover.tsx
+  styles_native: popover/popover.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Popover } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content>
+      <Popover.Arrow />
+      <Popover.Close />
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+- **Popover**：根容器，管理展开/收起、定位，并为子组件提供上下文。
+- **Popover.Trigger**：可点击的触发器，切换浮层可见性；为子元素包裹按压处理。
+- **Popover.Portal**：在Portal层渲染内容，保证层级与定位正确。
+- **Popover.Overlay**：可选背景遮罩；可透明或半透明，用于捕获外部点击。
+- **Popover.Content**：内容容器，含定位、样式与碰撞检测；支持 `popover` 与底部抽屉呈现。
+- **Popover.Arrow**：可选箭头，指向触发器；随 `placement` 自动定位。
+- **Popover.Close**：关闭按钮；可自定义子节点，默认关闭图标。
+- **Popover.Title**：可选标题，使用预设排版。
+- **Popover.Description**：可选说明文字，弱化样式。
+
+## 用法
+
+### 基础用法
+
+通过组合子部件创建浮动内容面板。
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">...</Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 标题与说明
+
+使用标题与说明组织内容层级。
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">
+      <Popover.Close />
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 带箭头
+
+添加指向触发器的箭头以增强视觉关联。
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" placement="top">
+      <Popover.Arrow />
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+> **说明：** 使用 `<Popover.Arrow />` 时，需要为 `Popover.Content` 添加边框，例如 `border border-border`，以便箭头与内容边框视觉衔接。
+
+### 宽度控制
+
+通过 `width` 控制浮层内容宽度。
+
+```tsx
+{
+  /* 固定像素宽度 */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width={320}>
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* 与触发器同宽 */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="trigger">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* 全宽（100%） */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="full">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* 随内容自适应（默认） */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="content-fit">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+```
+
+### 底部抽屉呈现
+
+在移动端使用底部抽屉交互。
+
+> **重要：** `Popover.Content` 的 `presentation` 必须与 `Popover` 根上的 `presentation` 一致。开发模式下不一致会抛错。
+
+```tsx
+<Popover presentation="bottom-sheet">
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="bottom-sheet">
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+      <Button>关闭</Button>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 方位选项
+
+控制浮层相对触发器出现的位置。
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Content presentation="popover" placement="left">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 对齐选项
+
+沿放置轴微调内容对齐。
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Content presentation="popover" placement="top" align="start">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 自定义动画
+
+在 `Popover` 根上使用 `animation` 配置展开/收起过渡。
+
+```tsx
+<Popover
+  animation={{
+    entering: {
+      type: 'spring',
+      config: { damping: 15, stiffness: 300 },
+    },
+    exiting: {
+      type: 'timing',
+      config: { duration: 200 },
+    },
+  }}
+>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">...</Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### 编程式控制
+
+```tsx
+// 通过 ref 编程式打开/关闭
+const popoverRef = useRef<PopoverTriggerRef>(null);
+
+// 打开
+popoverRef.current?.open();
+
+// 关闭
+popoverRef.current?.close();
+
+// 完整示例
+<Popover>
+  <Popover.Trigger ref={popoverRef} asChild>
+    <Button>触发器</Button>
+  </Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">
+      <Text>内容</Text>
+      <Button onPress={() => popoverRef.current?.close()}>关闭</Button>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+```
+
+## 示例
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Button, Popover, useThemeColor } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function PopoverExample() {
+  const themeColorMuted = useThemeColor('muted');
+
+  return (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button variant="tertiary" size="sm">
+          <Ionicons
+            name="information-circle"
+            size={20}
+            color={themeColorMuted}
+          />
+          <Button.Label>查看说明</Button.Label>
+        </Button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Overlay />
+        <Popover.Content
+          presentation="popover"
+          width={320}
+          className="gap-1 rounded-xl px-6 py-4"
+        >
+          <Popover.Close className="absolute top-3 right-3 z-50" />
+          <Popover.Title>说明</Popover.Title>
+          <Popover.Description>
+            此浮层包含标题与描述，用于向用户提供更有层次的信息。
+          </Popover.Description>
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/popover.tsx)。
+
+## API 参考
+
+### Popover
+
+| prop            | type                          | default     | description                                                                                    |
+| --------------- | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `children`      | `ReactNode`                   | -           | 浮层内的子节点                                                                                 |
+| `isOpen`        | `boolean`                     | -           | 是否展开（受控）                                                                               |
+| `isDefaultOpen` | `boolean`                     | -           | 初始是否展开（非受控）                                                                         |
+| `onOpenChange`  | `(isOpen: boolean) => void`   | -           | 展开状态变化时的回调                                                                           |
+| `animation`     | `AnimationRootDisableAll`     | -           | 动画配置，可为 `false`、`"disabled"`、`"disable-all"`、`true` 或 `undefined`                     |
+| `presentation`  | `'popover' \| 'bottom-sheet'` | `'popover'` | 内容呈现方式                                                                                   |
+| `asChild`       | `boolean`                     | `false`     | 是否将子元素作为实际渲染节点                                                                   |
+| `...ViewProps`  | `ViewProps`                   | -           | 支持全部标准 React Native `View` 属性                                                        |
+
+#### AnimationRootDisableAll
+
+根级动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根动画
+- `"disable-all"`：禁用根与子级全部动画
+- `true` 或 `undefined`：使用默认动画
+
+### Popover.Trigger
+
+| prop                | type             | default | description                                             |
+| ------------------- | ---------------- | ------- | ------------------------------------------------------- |
+| `children`          | `ReactNode`      | -       | 触发器内容                                              |
+| `className`         | `string`         | -       | 触发器额外 class                                        |
+| `asChild`           | `boolean`        | `true`  | 是否将子元素作为实际渲染节点                            |
+| `...PressableProps` | `PressableProps` | -       | 支持全部标准 React Native `Pressable` 属性              |
+
+### Popover.Portal
+
+| prop                       | type        | default | description                                                                                                                   |
+| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactNode` | -       | Portal内容（必填）                                                                                                              |
+| `disableFullWindowOverlay` | `boolean`   | `false` | 在 iOS 为 `true` 时使用 `View` 代替 `FullWindowOverlay`，便于元素检查器；遮罩将无法叠在原生模态之上                           |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | 控制 VoiceOver 是否将遮罩窗口视为模态容器。为 `true` 时，VoiceOver 仅聚焦遮罩内元素。仅 iOS；API 不稳定，可能随 react-native-screens 变更 |
+| `hostName`                 | `string`    | -       | Portal宿主元素的可选名称                                                                                                        |
+| `forceMount`               | `boolean`   | -       | 是否强制挂载                                                                                                                  |
+| `className`                | `string`    | -       | Portal容器额外 class                                                                                                            |
+| `...ViewProps`             | `ViewProps` | -       | 支持全部标准 React Native `View` 属性                                                                                       |
+
+### Popover.Overlay
+
+| prop                    | type                      | default | description                                                  |
+| ----------------------- | ------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                  | -       | 遮罩额外 class                                               |
+| `closeOnPress`          | `boolean`                 | `true`  | 点击遮罩是否关闭                                             |
+| `forceMount`            | `boolean`                 | -       | 是否强制挂载                                                 |
+| `animation`             | `PopoverOverlayAnimation` | -       | 动画配置                                                     |
+| `isAnimatedStyleActive` | `boolean`                 | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `asChild`               | `boolean`                 | `false` | 是否将子元素作为实际渲染节点                                 |
+| `...Animated.ViewProps` | `Animated.ViewProps`      | -       | 支持 Reanimated `Animated.View` 的全部属性                   |
+
+#### PopoverOverlayAnimation
+
+遮罩动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop            | type                       | default                     | description                                                                               |
+| --------------- | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -                           | 在自定义属性时用于禁用动画                                                                |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`                 | 透明度 [空闲, 打开, 关闭]，用于底部抽屉等呈现                                             |
+| `entering`      | `EntryOrExitLayoutType`    | 默认淡入 200ms              | 自定义进入关键帧，用于 `popover` 呈现                                                     |
+| `exiting`       | `EntryOrExitLayoutType`    | 默认淡出 150ms              | 自定义退出关键帧，用于 `popover` 呈现                                                     |
+
+### Popover.Content（Popover 呈现）
+
+| prop                      | type                                             | default         | description                                                                                             |
+| ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `children`                | `ReactNode`                                      | -               | 浮层内容                                                                                                |
+| `presentation`            | `'popover'`                                      | `'popover'`     | 呈现模式，须与 `Popover` 根一致；未传时默认为 `popover`                                                 |
+| `width`                   | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | 内容宽度策略                                                                                            |
+| `placement`               | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | 相对触发器的方位                                                                                        |
+| `align`                   | `'start' \| 'center' \| 'end'`                   | `'center'`      | 沿放置轴的对齐                                                                                          |
+| `avoidCollisions`         | `boolean`                                        | `true`          | 靠近视口边缘时是否翻转 placement                                                                        |
+| `offset`                  | `number`                                         | `9`             | 与触发器的间距（像素）                                                                                  |
+| `alignOffset`             | `number`                                         | `0`             | 沿对齐轴的偏移（像素）                                                                                  |
+| `disablePositioningStyle` | `boolean`                                        | `false`         | 是否禁用自动定位样式                                                                                    |
+| `forceMount`              | `boolean`                                        | -               | 是否强制挂载                                                                                            |
+| `insets`                  | `Insets`                                         | -               | 定位时需遵守的屏幕边距                                                                                  |
+| `className`               | `string`                                         | -               | 内容容器额外 class                                                                                      |
+| `animation`               | `PopupPopoverContentAnimation`                   | -               | 动画配置                                                                                                |
+| `isAnimatedStyleActive`   | `boolean`                                        | `true`          | 是否启用 Reanimated 动画样式                                                                            |
+| `asChild`                 | `boolean`                                        | `false`         | 是否将子元素作为实际渲染节点                                                                            |
+| `...Animated.ViewProps`   | `Animated.ViewProps`                             | -               | 支持 Reanimated `Animated.View` 的全部属性                                                            |
+
+### Popover.Content（底部抽屉呈现）
+
+| prop                        | type                   | default | description                                                                                    |
+| --------------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `children`                  | `ReactNode`            | -       | 底部抽屉内容                                                                                   |
+| `presentation`              | `'bottom-sheet'`       | -       | 呈现模式，须为 `bottom-sheet` 并与根一致（必填）                                               |
+| `contentContainerClassName` | `string`               | -       | 内容容器额外 class                                                                             |
+| `contentContainerProps`     | `BottomSheetViewProps` | -       | 内容容器属性                                                                                   |
+| `enablePanDownToClose`      | `boolean`              | `true`  | 是否允许下滑关闭                                                                               |
+| `backgroundStyle`           | `ViewStyle`            | -       | 底部抽屉背景样式                                                                               |
+| `handleIndicatorStyle`      | `ViewStyle`            | -       | 把手指示器样式                                                                                 |
+| `...BottomSheetProps`       | `BottomSheetProps`     | -       | 支持 `@gorhom/bottom-sheet` 的全部属性                                                         |
+
+#### PopupPopoverContentAnimation
+
+内容（`popover` 呈现）动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用全部动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop       | type                    | default                                                         | description                                       |
+| ---------- | ----------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -                                                               | 在自定义属性时用于禁用动画                        |
+| `entering` | `EntryOrExitLayoutType` | 默认关键帧：translateY/translateX、scale、opacity（200ms）      | 自定义进入关键帧                                  |
+| `exiting`  | `EntryOrExitLayoutType` | 默认与进入镜像（150ms）                                         | 自定义退出关键帧                                  |
+
+### Popover.Arrow
+
+| prop                  | type                                     | default | description                                                           |
+| --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
+| `className`           | `string`                                 | -       | 箭头额外 class                                                        |
+| `height`              | `number`                                 | `12`    | 箭头高度（像素）                                                      |
+| `width`               | `number`                                 | `20`    | 箭头宽度（像素）                                                      |
+| `fill`                | `string`                                 | -       | 填充色（默认与内容背景一致）                                          |
+| `stroke`              | `string`                                 | -       | 描边色（默认与内容边框色一致）                                        |
+| `strokeWidth`         | `number`                                 | `1`     | 描边宽度（像素）                                                      |
+| `strokeBaselineInset` | `number`                                 | `1`     | 描边基线内缩（像素）                                                  |
+| `placement`           | `'top' \| 'bottom' \| 'left' \| 'right'` | -       | 浮层方位（自内容继承）                                                |
+| `children`            | `ReactNode`                              | -       | 自定义箭头内容（替换默认 SVG）                                        |
+| `style`               | `StyleProp<ViewStyle>`                   | -       | 箭头容器额外样式                                                      |
+| `...ViewProps`        | `ViewProps`                              | -       | 支持全部标准 React Native `View` 属性                               |
+
+### Popover.Close
+
+`Popover.Close` 继承 [CloseButton](./close-button)，按下时自动关闭浮层。
+
+### Popover.Title
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | 标题文案                                           |
+| `className`    | `string`    | -       | 标题额外 class                                     |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性              |
+
+### Popover.Description
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | 说明文案                                           |
+| `className`    | `string`    | -       | 说明额外 class                                     |
+| `...TextProps` | `TextProps` | -       | 支持全部标准 React Native `Text` 属性              |
+
+## Hooks
+
+### usePopover
+
+在自定义或复合子组件中读取浮层上下文。
+
+```tsx
+import { usePopover } from 'heroui-native';
+
+const CustomContent = () => {
+  const { isOpen, onOpenChange, triggerPosition } = usePopover();
+  // …实现
+};
+```
+
+#### 返回值
+
+| property             | type                                                | description                                                       |
+| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
+| `isOpen`             | `boolean`                                           | 当前是否打开                                                      |
+| `onOpenChange`       | `(open: boolean) => void`                           | 修改展开状态的回调                                                |
+| `isDefaultOpen`      | `boolean \| undefined`                              | 默认是否打开（非受控）                                            |
+| `isDisabled`         | `boolean \| undefined`                              | 是否禁用                                                          |
+| `triggerPosition`    | `LayoutPosition \| null`                            | 触发器相对视口的位置                                              |
+| `setTriggerPosition` | `(triggerPosition: LayoutPosition \| null) => void` | 更新触发器位置                                                    |
+| `contentLayout`      | `LayoutRectangle \| null`                           | 浮层内容的布局测量                                                |
+| `setContentLayout`   | `(contentLayout: LayoutRectangle \| null) => void`  | 更新内容布局测量                                                  |
+| `nativeID`           | `string`                                            | 当前实例唯一标识                                                  |
+
+**说明：** 必须在 `Popover` 内使用；在上下文外调用将抛错。
+
+### usePopoverAnimation
+
+在自定义或复合子组件中读取浮层动画共享值。
+
+```tsx
+import { usePopoverAnimation } from 'heroui-native';
+
+const CustomContent = () => {
+  const { progress, isDragging } = usePopoverAnimation();
+  // …实现
+};
+```
+
+#### 返回值
+
+| property     | type                   | description                                                        |
+| ------------ | ---------------------- | ------------------------------------------------------------------ |
+| `progress`   | `SharedValue<number>`  | 动画进度（0=空闲，1=打开，2=关闭）                                 |
+| `isDragging` | `SharedValue<boolean>` | 是否正在拖拽                                                       |
+
+**说明：** 必须在 `Popover` 内使用；在动画上下文外调用将抛错。
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+`Popover` 在 iOS 使用 `FullWindowOverlay`。开发时若需启用 React Native 元素检查器，可在 `Popover.Portal` 设置 `disableFullWindowOverlay={true}`。代价：浮层将无法叠在原生系统模态之上。
+
+### 原生模态（iOS）
+
+当 `Popover` 位于以原生模态形式呈现的页面内时（`presentation: 'modal' | 'formSheet' | 'pageSheet'`），浮层内容可能会向上偏移渲染。在新架构（Fabric）中，`react-native-screens` 将 `RNSModalScreen` 标记为 Fabric 根节点，因此触发器的坐标是相对于模态原点上报的，而 `FullWindowOverlay`（浮层挂载点）锚定在 iOS 应用窗口上。可通过将 `safeAreaInsets.top` 加到 `offset` 来补偿：
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Popover.Content presentation="popover" offset={insets.top + 20}>
+  ...
+</Popover.Content>;
+```
diff --git a/apps/docs/content/docs/cn/native/components/(overlays)/toast.mdx b/apps/docs/content/docs/cn/native/components/(overlays)/toast.mdx
new file mode 100644
index 0000000..999781c
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(overlays)/toast.mdx
@@ -0,0 +1,431 @@
+---
+title: Toast 轻提示
+description: 在屏幕顶部或底部展示的临时通知消息。
+links:
+  source_native: toast/toast.tsx
+  styles_native: toast/toast.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Toast, useToast } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Toast>
+  <Toast.Title>...</Toast.Title>
+  <Toast.Description>...</Toast.Description>
+  <Toast.Action>...</Toast.Action>
+  <Toast.Close />
+</Toast>
+```
+
+- **Toast**：主容器，负责定位、动画与滑动手势。
+- **Toast.Title**：标题文字，继承父级 Toast 的变体样式。
+- **Toast.Description**：标题下方的描述文字。
+- **Toast.Action**：操作按钮；按钮变体默认随 Toast 变体推断，也可覆盖。
+- **Toast.Close**：关闭按钮，图标按钮样式，按下时调用隐藏。
+
+## 用法
+
+### 用法一：简单字符串
+
+使用纯字符串快速展示 Toast。
+
+```tsx
+const { toast } = useToast();
+
+toast.show('这是一条 Toast 消息');
+```
+
+### 用法二：配置对象
+
+通过配置对象传入标题、描述、变体与操作按钮等。
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: '套餐已升级',
+  description: '可继续使用 HeroUI Chat',
+  icon: <Icon name="check" />,
+  actionLabel: '关闭',
+  onActionPress: ({ hide }) => hide(),
+});
+```
+
+### 用法三：自定义组件
+
+使用完全自定义的组件以自由控制样式与布局。
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" placement="top" {...props}>
+      <Toast.Title>自定义 Toast</Toast.Title>
+      <Toast.Description>这是一个自定义 Toast 组件</Toast.Description>
+      <Toast.Close />
+    </Toast>
+  ),
+});
+```
+
+**说明**：Toast 条目会做性能相关的 memo。若需把外部状态（如加载中）传入自定义 Toast，不会自动随状态重渲染。请使用 React Context、全局状态或 ref 等方式让状态能传递到 Toast 内。
+
+### 禁用全部动画
+
+使用 `"disable-all"` 可禁用自身及子级（如 `Toast.Action` 内的 `Button`）的全部动画。
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: '操作完成',
+  description: '已禁用全部动画',
+  animation: 'disable-all',
+});
+```
+
+自定义组件示例：
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" animation="disable-all" {...props}>
+      <Toast.Title>无动画</Toast.Title>
+      <Toast.Description>
+        此 Toast 已禁用全部动画
+      </Toast.Description>
+      <Toast.Action>操作</Toast.Action>
+    </Toast>
+  ),
+});
+```
+
+## 示例
+
+```tsx
+import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function ToastExample() {
+  const { toast } = useToast();
+  const themeColorForeground = useThemeColor('foreground');
+
+  return (
+    <View className="gap-4 p-4">
+      <Button
+        onPress={() =>
+          toast.show({
+            variant: 'success',
+            label: '套餐已升级',
+            description: '可继续使用 HeroUI Chat',
+            actionLabel: '关闭',
+            onActionPress: ({ hide }) => hide(),
+          })
+        }
+      >
+        显示成功 Toast
+      </Button>
+
+      <Button
+        onPress={() =>
+          toast.show({
+            component: (props) => (
+              <Toast variant="accent" {...props}>
+                <Toast.Title>自定义 Toast</Toast.Title>
+                <Toast.Description>
+                  使用自定义组件渲染
+                </Toast.Description>
+                <Toast.Action onPress={() => props.hide()}>撤销</Toast.Action>
+                <Toast.Close className="absolute top-0 right-0" />
+              </Toast>
+            ),
+          })
+        }
+      >
+        显示自定义 Toast
+      </Button>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/toast.tsx>)。
+
+## 全局配置
+
+通过 `HeroUINativeProvider` 的 `config` 全局配置 Toast；本地调用可覆盖默认值。
+
+> **说明**：Provider 的完整配置见 [Provider 文档](/docs/native/getting-started/handbook/provider#toast-configuration)。
+
+### 边距（Insets）
+
+控制 Toast 与屏幕边缘的距离，会在安全区内边距基础上叠加。例如四边距屏幕 20px：
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      insets: {
+        top: 20,
+        bottom: 20,
+        left: 20,
+        right: 20,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+### 使用 KeyboardAvoidingView 包裹内容
+
+用 `KeyboardAvoidingView` 包裹 Toast 内容，键盘弹出时自动避让：
+
+```tsx
+import {
+  KeyboardAvoidingView,
+  KeyboardProvider,
+} from 'react-native-keyboard-controller';
+import { HeroUINativeProvider } from 'heroui-native';
+import { useCallback } from 'react';
+
+function AppContent() {
+  const contentWrapper = useCallback(
+    (children: React.ReactNode) => (
+      <KeyboardAvoidingView
+        pointerEvents="box-none"
+        behavior="padding"
+        keyboardVerticalOffset={12}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+    []
+  );
+
+  return (
+    <KeyboardProvider>
+      <HeroUINativeProvider
+        config={{
+          toast: {
+            contentWrapper,
+          },
+        }}
+      >
+        {children}
+      </HeroUINativeProvider>
+    </KeyboardProvider>
+  );
+}
+```
+
+### 默认属性
+
+全局设置变体、位置、动画与滑动等默认值：
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      defaultProps: {
+        variant: 'accent',
+        placement: 'bottom',
+        isSwipeable: false,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+## API 参考
+
+### Toast
+
+| prop                    | type                                                          | default     | description                                                               |
+| ----------------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `variant`               | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 视觉变体                                                                  |
+| `placement`             | `'top' \| 'bottom'`                                           | `'top'`     | 在屏幕上的位置                                                            |
+| `isSwipeable`           | `boolean`                                                     | `true`      | 是否可滑动关闭并带橡皮筋拖拽效果                                          |
+| `animation`             | `ToastRootAnimation`                                          | -           | 动画配置                                                                  |
+| `isAnimatedStyleActive` | `boolean`                                                     | `true`      | 是否启用 Reanimated 动画样式                                              |
+| `className`             | `string`                                                      | -           | Toast 容器额外 class                                                      |
+| `...ViewProps`          | `ViewProps`                                                   | -           | 支持 React Native `View` 的全部属性                                       |
+
+#### ToastRootAnimation
+
+Toast 根动画配置，可为：
+
+- `false` 或 `"disabled"`：仅禁用根级动画
+- `"disable-all"`：禁用全部动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                      | type                                     | default                                                                                                                   | description                                                                      |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `state`                   | `'disabled' \| 'disable-all' \| boolean` | -                                                                                                                         | 在自定义属性时禁用动画                                                           |
+| `opacity.value`           | `[number, number]`                       | `[1, 0]`                                                                                                                  | Toast 移出可视堆叠时的透明度插值                                                 |
+| `opacity.timingConfig`    | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | 透明度过渡的时间配置                                                             |
+| `translateY.value`        | `[number, number]`                       | `[0, 10]`                                                                                                                 | 堆叠 Toast 微位移效果的 Y 插值                                                   |
+| `translateY.timingConfig` | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | translateY 过渡的时间配置                                                        |
+| `scale.value`             | `[number, number]`                       | `[1, 0.97]`                                                                                                               | 堆叠 Toast 景深缩放的插值                                                        |
+| `scale.timingConfig`      | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | 缩放过渡的时间配置                                                               |
+| `entering.top`            | `EntryOrExitLayoutType`                  | `FadeInUp`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`<br/>`.mass(3)`  | 顶部放置时的进入动画                                                             |
+| `entering.bottom`         | `EntryOrExitLayoutType`                  | `FadeInDown`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`<br/>`.mass(3)` | 底部放置时的进入动画                                                             |
+| `exiting.top`             | `EntryOrExitLayoutType`                  | 关键帧动画<br/>`translateY: -100, scale: 0.97, opacity: 0.5`                                                              | 顶部放置时的退出动画                                                             |
+| `exiting.bottom`          | `EntryOrExitLayoutType`                  | 关键帧动画<br/>`translateY: 100, scale: 0.97, opacity: 0.5`                                                               | 底部放置时的退出动画                                                             |
+
+### Toast.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 标题内容                                           |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+### Toast.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 描述内容                                           |
+| `className`    | `string`          | -       | 额外的 class                                       |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |
+
+### Toast.Action
+
+`Toast.Action` 继承 [Button](button) 的全部属性。按钮变体默认由 Toast 变体推断，也可覆盖。
+
+| prop        | type                   | default | description                                                                  |
+| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
+| `children`  | `React.ReactNode`      | -       | 操作按钮文字                                                                 |
+| `variant`   | `ButtonVariant`        | -       | 按钮变体；未提供时由 Toast 变体自动决定                                       |
+| `size`      | `'sm' \| 'md' \| 'lg'` | `'sm'`  | 操作按钮尺寸                                                                 |
+| `className` | `string`               | -       | 额外的 class                                                                 |
+
+`onPress`、`isDisabled` 等其余属性见 [Button API 参考](button#api-reference)。
+
+### Toast.Close
+
+`Toast.Close` 继承 [Button](button) 的全部属性。
+
+| prop        | type                                | default | description                                    |
+| ----------- | ----------------------------------- | ------- | ---------------------------------------------- |
+| `children`  | `React.ReactNode`                   | -       | 自定义关闭图标；默认使用 CloseIcon             |
+| `iconProps` | `{ size?: number; color?: string }` | -       | 默认关闭图标的属性                             |
+| `size`      | `'sm' \| 'md' \| 'lg'`              | `'sm'`  | 关闭按钮尺寸                                   |
+| `className` | `string`                            | -       | 额外的 class                                   |
+| `onPress`   | `(event: any) => void`              | -       | 自定义按下处理；默认隐藏 Toast                 |
+
+其余继承属性见 [Button API 参考](button#api-reference)。
+
+### ToastProviderProps
+
+通过 `HeroUINativeProvider` 的 `config.toast` 进行全局配置时可用的属性。
+
+| prop                                         | type                                                | default | description                                                                                                                                                                                                      |
+| -------------------------------------------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultProps`                               | `ToastGlobalConfig`                                 | -       | 全局默认配置，可被单次调用覆盖                                                                                                                                                                                   |
+| `disableFullWindowOverlay`                   | `boolean`                                           | `false` | iOS 上为 true 时使用普通 `View` 替代 `FullWindowOverlay`，便于元素检查器；Toast 将不再叠在原生模态之上                                                                                                         |
+| `unstable_accessibilityContainerViewIsModal` | `boolean`                                           | `false` | 是否将覆盖窗口视为模态容器（VoiceOver）。为 true 时焦点限制在覆盖层内。仅 iOS；可能随 react-native-screens 变化                                                                                                  |
+| `insets`                                     | `ToastInsets`                                       | -       | 相对屏幕边缘的内边距（与安全区内边距相加）                                                                                                                                                                       |
+| `maxVisibleToasts`                           | `number`                                            | `3`     | 最大可见条数，超过后开始降低透明度                                                                                                                                                                               |
+| `contentWrapper`                             | `(children: React.ReactNode) => React.ReactElement` | -       | 自定义包裹 Toast 内容的函数                                                                                                                                                                                      |
+| `children`                                   | `React.ReactNode`                                   | -       | 子节点                                                                                                                                                                                                           |
+
+#### ToastGlobalConfig
+
+全局默认，可被单次调用覆盖。
+
+| prop          | type                                                          | description                                                               |
+| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `variant`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | 视觉变体                                                                  |
+| `placement`   | `'top' \| 'bottom'`                                           | 位置                                                                      |
+| `isSwipeable` | `boolean`                                                     | 是否可滑动关闭并带橡皮筋效果                                              |
+| `animation`   | `ToastRootAnimation`                                          | Toast 动画配置                                                            |
+
+#### ToastInsets
+
+相对屏幕边缘的间距，会与安全区内边距相加。
+
+| prop     | type     | default | description                                                                                               |
+| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `top`    | `number` | -       | 距顶部像素（叠加安全区）。平台默认：iOS 0，Android 12                                                      |
+| `bottom` | `number` | -       | 距底部像素（叠加安全区）。平台默认：iOS 6，Android 12                                                      |
+| `left`   | `number` | -       | 距左侧像素（叠加安全区）。默认 12                                                                          |
+| `right`  | `number` | -       | 距右侧像素（叠加安全区）。默认 12                                                                          |
+
+## Hooks
+
+### useToast
+
+访问 Toast 能力，必须在 `ToastProvider` 内使用（由 `HeroUINativeProvider` 提供）。
+
+| 返回值           | type           | description                              |
+| ---------------- | -------------- | ---------------------------------------- |
+| `toast`          | `ToastManager` | 含 `show`、`hide` 等方法的 Toast 管理器 |
+| `isToastVisible` | `boolean`      | 当前是否有 Toast 可见                    |
+
+#### ToastManager
+
+| method | type                                              | description                                                                                                                          |
+| ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `show` | `(options: string \| ToastShowOptions) => string` | 显示 Toast，返回 ID。支持字符串、配置对象或自定义组件三种形式                                                                        |
+| `hide` | `(ids?: string \| string[] \| 'all') => void`     | 隐藏一条或多条。无参隐藏最后一条；`'all'` 隐藏全部；传入 ID 或 ID 数组隐藏指定项                                                     |
+
+#### ToastShowOptions
+
+展示选项：默认样式的配置对象，或自定义组件。
+
+**使用配置对象（无 `component`）时：**
+
+| prop            | type                                                                                                                              | default | description                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `variant`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`                                                                     | -       | 视觉变体                                                                            |
+| `placement`     | `'top' \| 'bottom'`                                                                                                               | -       | 位置                                                                                |
+| `isSwipeable`   | `boolean`                                                                                                                         | -       | 是否可滑动关闭                                                                      |
+| `animation`     | `ToastRootAnimation \| false \| "disabled" \| "disable-all"`                                                                      | -       | 动画配置                                                                            |
+| `duration`      | `number \| 'persistent'`                                                                                                          | `4000`  | 自动隐藏毫秒数；`'persistent'` 表示不自动隐藏                                     |
+| `id`            | `string`                                                                                                                          | -       | 可选 ID；未提供则自动生成                                                           |
+| `label`         | `string`                                                                                                                          | -       | 标题文字                                                                            |
+| `description`   | `string`                                                                                                                          | -       | 描述文字                                                                            |
+| `actionLabel`   | `string`                                                                                                                          | -       | 操作按钮文案                                                                        |
+| `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | -       | 操作按钮按下回调                                                                    |
+| `icon`          | `React.ReactNode`                                                                                                                 | -       | 左侧图标                                                                            |
+| `onShow`        | `() => void`                                                                                                                      | -       | 显示时回调                                                                          |
+| `onHide`        | `() => void`                                                                                                                      | -       | 隐藏时回调                                                                          |
+
+**使用自定义组件时：**
+
+| prop        | type                                                 | default | description                                                                         |
+| ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `id`        | `string`                                             | -       | 可选 ID；未提供则自动生成                                                           |
+| `component` | `(props: ToastComponentProps) => React.ReactElement` | -       | 接收 Toast props 并返回 React 元素的函数                                            |
+| `duration`  | `number \| 'persistent'`                             | `4000`  | 自动隐藏毫秒数；`'persistent'` 表示不自动隐藏                                     |
+| `onShow`    | `() => void`                                         | -       | 显示时回调                                                                          |
+| `onHide`    | `() => void`                                         | -       | 隐藏时回调                                                                          |
+
+## 特别说明
+
+### 元素检查器（iOS）
+
+Toast 在 iOS 上使用 `FullWindowOverlay`。开发时若需使用 React Native 元素检查器，可在 `HeroUINativeProvider` 的 `config.toast` 中设置 `disableFullWindowOverlay={true}`。代价：Toast 将无法叠在原生系统模态之上。
diff --git a/apps/docs/content/docs/cn/native/components/(typography)/text.mdx b/apps/docs/content/docs/cn/native/components/(typography)/text.mdx
new file mode 100644
index 0000000..f6c24c5
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(typography)/text.mdx
@@ -0,0 +1,220 @@
+---
+title: Typography 文本
+description: 用于渲染带语义类型变体的样式化文本的排版基元组件。
+icon: updated
+links:
+  source_native: text/text.tsx
+  styles_native: text/text.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { Typography } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<Typography>...</Typography>
+
+{/* 子组件 */}
+<Typography.Heading>...</Typography.Heading>
+<Typography.Paragraph>...</Typography.Paragraph>
+<Typography.Code>...</Typography.Code>
+```
+
+- **Typography**：文本根元素。通过 `type` 选择排版预设，并提供互不耦合的 `align`、`color`、`weight`、`truncate` 属性。
+- **Typography.Heading**：限定为标题类型（`h1`–`h6`）的便捷包装组件，会自动添加 `accessibilityRole="header"`。
+- **Typography.Paragraph**：限定为正文类型（`body`、`body-sm`、`body-xs`）的便捷包装组件。
+- **Typography.Code**：以 chip 样式呈现的等宽内联文本，采用平台合适的等宽字体。
+
+## 用法
+
+### 基础用法
+
+`Typography` 默认渲染正文文本。
+
+```tsx
+<Typography>Hello, world!</Typography>
+```
+
+### 类型变体
+
+使用 `type` 属性选择语义化排版预设。
+
+```tsx
+<Typography type="h1">Heading 1</Typography>
+<Typography type="h2">Heading 2</Typography>
+<Typography type="h3">Heading 3</Typography>
+<Typography type="h4">Heading 4</Typography>
+<Typography type="h5">Heading 5</Typography>
+<Typography type="h6">Heading 6</Typography>
+<Typography type="body">Body text</Typography>
+<Typography type="body-sm">Small body text</Typography>
+<Typography type="body-xs">Extra-small body text</Typography>
+<Typography type="code">Code snippet</Typography>
+```
+
+### 标题
+
+使用 `Typography.Heading` 渲染标题文本，自动具备 header 无障碍角色。
+
+```tsx
+<Typography.Heading type="h1">Page Title</Typography.Heading>
+<Typography.Heading type="h2">Section Title</Typography.Heading>
+<Typography.Heading type="h3">Subsection Title</Typography.Heading>
+```
+
+### 段落
+
+使用 `Typography.Paragraph` 渲染正文文本。
+
+```tsx
+<Typography.Paragraph>
+  这是一个使用默认尺寸渲染的正文段落。
+</Typography.Paragraph>
+<Typography.Paragraph type="body-sm">
+  这是较小的正文文本。
+</Typography.Paragraph>
+```
+
+### 代码
+
+使用 `Typography.Code`（或等价的 `<Typography type="code">`）渲染内联代码片段。两者都会呈现为 chip 样式的等宽内联元素，带有低饱和背景、圆角，并采用 `self-start` 布局以避免在 flex 容器中被拉伸。平台相关的等宽 `fontFamily` 在 `Typography` 根元素上应用，因此两种写法可互换。
+
+```tsx
+<Typography.Code>console.log('hello')</Typography.Code>
+<Typography type="code">console.log('hello')</Typography>
+```
+
+### 对齐
+
+使用 `align` 属性控制水平对齐。`start` 与 `end` 是 RTL 感知的（在从右到左布局下会翻转）。
+
+```tsx
+<Typography align="start">Start-aligned</Typography>
+<Typography align="center">Center-aligned</Typography>
+<Typography align="end">End-aligned</Typography>
+<Typography align="justify">Justified text spreads across the line.</Typography>
+```
+
+> **说明：** `text-justify` 在 React Native 中仅 iOS 生效；Android 会回退为左对齐。
+
+### 颜色
+
+使用 `color` 属性应用语义化前景色预设。
+
+```tsx
+<Typography color="default">Default foreground</Typography>
+<Typography color="muted">Muted secondary text</Typography>
+```
+
+如需其他主题色，可通过 `className` 传入对应工具类（如 `className="text-accent"`、`className="text-danger"`）。
+
+### 字重
+
+使用 `weight` 属性覆盖由 `type` 推导出的字重。该覆盖通过 `tailwind-merge` 合并，因此始终优先于 type 变体的默认字重。
+
+```tsx
+<Typography type="h1" weight="bold">Bold H1</Typography>
+<Typography weight="medium">Medium body</Typography>
+<Typography weight="semibold">Semibold body</Typography>
+```
+
+### 截断
+
+使用布尔属性 `truncate` 将文本限制为单行并以省略号结尾。它映射到 React Native 的 `numberOfLines={1}`。如显式提供 `numberOfLines`，则以后者为准。
+
+```tsx
+<Typography truncate>
+  当内容溢出容器时，这一长行文本会被截断并显示省略号。
+</Typography>;
+
+{
+  /* 通过底层 RN 属性实现多行截断 */
+}
+<Typography numberOfLines={2}>
+  通过 React Native 标准的 `numberOfLines` 属性可实现多行截断。
+</Typography>;
+```
+
+## 示例
+
+```tsx
+import { Typography } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function TypographyExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Typography.Heading type="h1">欢迎</Typography.Heading>
+      <Typography.Heading type="h3">快速开始</Typography.Heading>
+      <Typography.Paragraph>
+        这是使用 Typography 组件渲染的正文段落。
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" type="body-sm">
+        用于注释或脚注的较小辅助文本。
+      </Typography.Paragraph>
+      <Typography.Code>npm install heroui-native</Typography.Code>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text.tsx>)。
+
+## API 参考
+
+### Typography
+
+`Typography` 继承 React Native 的全部 `TextProps`，并新增排版相关属性。
+
+| prop           | type                                                                                         | default     | description                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
+| `type`         | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'`    | 语义化排版变体（字号、默认字重、行高）                                                       |
+| `align`        | `'start' \| 'center' \| 'end' \| 'justify'`                                                  | `'start'`   | 水平对齐方式。`start` 与 `end` 为 RTL 感知；`justify` 仅 iOS 生效                            |
+| `color`        | `'default' \| 'muted'`                                                                       | `'default'` | 语义化前景色预设                                                                             |
+| `weight`       | `'normal' \| 'medium' \| 'semibold' \| 'bold'`                                               | -           | 字重覆盖。设置后会覆盖 `type` 暗含的字重                                                     |
+| `truncate`     | `boolean`                                                                                    | `false`     | 将文本截断为单行并显示省略号（即设 `numberOfLines={1}`）。显式 `numberOfLines` 优先级更高    |
+| `children`     | `React.ReactNode`                                                                            | -           | 渲染内容                                                                                     |
+| `className`    | `string`                                                                                     | -           | 额外 CSS 类                                                                                  |
+| `...TextProps` | `TextProps`                                                                                  | -           | 支持 React Native `Text` 的全部标准属性                                                      |
+
+### Typography.Heading
+
+继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className` 及 React Native `TextProps`）。自动设置 `accessibilityRole="header"`，并将 `type` 收窄为标题变体。
+
+| prop           | type                                           | default | description                              |
+| -------------- | ---------------------------------------------- | ------- | ---------------------------------------- |
+| `type`         | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h1'`  | 标题级别                                 |
+| `children`     | `React.ReactNode`                              | -       | 渲染内容                                 |
+| `className`    | `string`                                       | -       | 额外 CSS 类                              |
+| `...TextProps` | `TextProps`                                    | -       | 支持 React Native `Text` 的全部标准属性  |
+
+### Typography.Paragraph
+
+继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className` 及 React Native `TextProps`）。将 `type` 收窄为正文变体。
+
+| prop           | type                               | default  | description                              |
+| -------------- | ---------------------------------- | -------- | ---------------------------------------- |
+| `type`         | `'body' \| 'body-sm' \| 'body-xs'` | `'body'` | 段落文本字号                             |
+| `children`     | `React.ReactNode`                  | -        | 渲染内容                                 |
+| `className`    | `string`                           | -        | 额外 CSS 类                              |
+| `...TextProps` | `TextProps`                        | -        | 支持 React Native `Text` 的全部标准属性  |
+
+### Typography.Code
+
+继承 `Typography` 根元素的全部属性（`align`、`color`、`weight`、`truncate`、`className`、`style` 及 React Native `TextProps`）。它是一个强制 `type="code"` 的轻量包装；平台相关的等宽 `fontFamily` 在 `Typography` 根元素上合并，因此 `<Typography type="code">` 与 `<Typography.Code>` 渲染效果完全一致。
+
+| prop           | type              | default | description                              |
+| -------------- | ----------------- | ------- | ---------------------------------------- |
+| `children`     | `React.ReactNode` | -       | 渲染内容                                 |
+| `className`    | `string`          | -       | 额外 CSS 类                              |
+| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部标准属性  |
diff --git a/apps/docs/content/docs/cn/native/components/(utilities)/pressable-feedback.mdx b/apps/docs/content/docs/cn/native/components/(utilities)/pressable-feedback.mdx
new file mode 100644
index 0000000..8b08079
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(utilities)/pressable-feedback.mdx
@@ -0,0 +1,340 @@
+---
+title: PressableFeedback 按压反馈
+description: 为按压交互提供视觉反馈的容器组件，内置缩放动画。
+icon: updated
+links:
+  source_native: pressable-feedback/pressable-feedback.tsx
+  styles_native: pressable-feedback/pressable-feedback.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-dark.mp4"
+/>
+
+## 导入
+
+```tsx
+import { PressableFeedback } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight />
+  <PressableFeedback.Ripple />
+  <PressableFeedback.Scale>...</PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+- **PressableFeedback**：内置缩放动画的可按压容器；管理按压状态与容器尺寸，并通过上下文提供给子复合部件。使用 `PressableFeedback.Scale` 时可将 `animation={false}` 关闭根级内置缩放。
+- **PressableFeedback.Scale**：对特定子元素应用缩放的包装层；需要精确控制哪个元素缩放，或要在缩放层上直接应用 `className` / `style` 时使用。
+- **PressableFeedback.Highlight**：iOS 风格的高亮遮罩，绝对定位，在按压时淡入。
+- **PressableFeedback.Ripple**：Android 风格的涟漪，从触点扩展的径向渐变圆。
+
+## 用法
+
+### 基础
+
+默认提供按下缩放反馈，多数场景推荐直接使用。
+
+```tsx
+<PressableFeedback>...</PressableFeedback>
+```
+
+### 配合 Highlight
+
+在默认缩放之外叠加 iOS 风格高亮。
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight />
+  ...
+</PressableFeedback>
+```
+
+### 配合 Ripple
+
+在默认缩放之外叠加 Android 风格涟漪。
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple />
+  ...
+</PressableFeedback>
+```
+
+### 自定义缩放动画
+
+通过根组件 `animation.scale` 配置，支持 `value`、`timingConfig`、`ignoreScaleCoefficient`。
+
+```tsx
+<PressableFeedback
+  animation={{
+    scale: {
+      value: 0.9,
+      timingConfig: { duration: 150 },
+      ignoreScaleCoefficient: true,
+    },
+  }}
+>
+  ...
+</PressableFeedback>
+```
+
+### 自定义 Highlight 动画
+
+配置高亮层的不透明度与背景色。
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight
+    animation={{
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.2] },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+### 自定义 Ripple 动画
+
+配置涟漪颜色、不透明度与时长。
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple
+    animation={{
+      backgroundColor: { value: '#ec4899' },
+      opacity: { value: [0, 0.1, 0] },
+      progress: { baseDuration: 600 },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+### 对指定子元素缩放（PressableFeedback.Scale）
+
+需要对容器内某一子元素而非根节点缩放时，将根组件设为 `animation={false}` 关闭内置缩放，再使用 `PressableFeedback.Scale`，以便在缩放层上直接应用 `className` / `style`。
+
+```tsx
+<PressableFeedback animation={false}>
+  <PressableFeedback.Scale>...</PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+可与 `Highlight` 或 `Ripple` 组合在 `Scale` 内：
+
+```tsx
+<PressableFeedback animation={false}>
+  <PressableFeedback.Scale>
+    <PressableFeedback.Highlight />
+    ...
+  </PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+### 禁用全部动画
+
+根上设置 `animation="disable-all"` 可级联禁用内置缩放及子复合部件（Scale、Highlight、Ripple）的动画。
+
+```tsx
+<PressableFeedback animation="disable-all">...</PressableFeedback>
+```
+
+也可在保留缩放配置的同时禁用动画（例如运行时切换）：
+
+```tsx
+<PressableFeedback animation={{ scale: { value: 0.97 }, state: 'disable-all' }}>
+  ...
+</PressableFeedback>
+```
+
+## 示例
+
+```tsx
+import { PressableFeedback, Card, Button } from 'heroui-native';
+import { Image } from 'expo-image';
+import { LinearGradient } from 'expo-linear-gradient';
+import { StyleSheet, View, Text } from 'react-native';
+
+export default function PressableFeedbackExample() {
+  return (
+    <PressableFeedback className="w-full aspect-square overflow-auto">
+      <Card className="flex-1">
+        <Image
+          source={{
+            uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg',
+          }}
+          style={StyleSheet.absoluteFill}
+          contentFit="cover"
+        />
+        <LinearGradient
+          colors={['rgba(0,0,0,0.1)', 'rgba(0,0,0,0.4)']}
+          style={StyleSheet.absoluteFill}
+        />
+        <PressableFeedback.Ripple
+          animation={{
+            backgroundColor: { value: 'white' },
+            opacity: { value: [0, 0.3, 0] },
+          }}
+        />
+        <View className="flex-1 gap-4" pointerEvents="box-none">
+          <Card.Body className="flex-1" pointerEvents="none">
+            <Card.Title className="text-base text-zinc-50 uppercase mb-0.5">
+              Neo
+            </Card.Title>
+            <Card.Description className="text-zinc-50 font-medium text-base">
+              家用机器人
+            </Card.Description>
+          </Card.Body>
+          <Card.Footer className="gap-3">
+            <View className="flex-row items-center justify-between">
+              <View pointerEvents="none">
+                <Text className="text-base text-white">即将开售</Text>
+                <Text className="text-base text-zinc-300">订阅通知</Text>
+              </View>
+              <Button size="sm" className="bg-white">
+                <Button.Label className="text-black">通知我</Button.Label>
+              </Button>
+            </View>
+          </Card.Footer>
+        </View>
+      </Card>
+    </PressableFeedback>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/pressable-feedback.tsx>)。
+
+## API 参考
+
+### PressableFeedback
+
+| prop                    | type                             | default | description                                                                                                 |
+| ----------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -       | 需要包裹按压反馈的内容                                                                                       |
+| `isDisabled`            | `boolean`                        | `false` | 是否禁用                                                                                                     |
+| `className`             | `string`                         | -       | 额外的 class                                                                                                 |
+| `animation`             | `PressableFeedbackRootAnimation` | -       | 通过 `{ scale: ... }` 自定义缩放；`false` 关闭根级缩放；`'disable-all'` 级联禁用全部                         |
+| `isAnimatedStyleActive` | `boolean`                        | `true`  | 根内置动画样式是否启用                                                                                       |
+| `asChild`               | `boolean`                        | `false` | 是否以子元素方式渲染                                                                                         |
+| `...rest`               | `AnimatedProps<PressableProps>`  | -       | 支持 Reanimated `Animated` `Pressable` 的属性                                                              |
+
+#### PressableFeedbackRootAnimation
+
+根 `animation` 遵循标准 `AnimationRoot` 控制流：
+
+- `true` 或 `undefined`：使用默认内置缩放
+- `false` 或 `"disabled"`：关闭根内置缩放（改用 `PressableFeedback.Scale` 时）
+- `"disable-all"`：级联禁用全部动画（含内置缩放与子级 Scale、Highlight、Ripple）
+- `object`：自定义内置缩放
+
+| prop    | type                                     | default | description                                                                     |
+| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `scale` | `PressableFeedbackScaleAnimation`        | -       | 自定义内置缩放（value、timingConfig 等）                                        |
+| `state` | `'disabled' \| 'disable-all' \| boolean` | -       | 在保留配置的同时控制动画状态（例如运行时开关）                                  |
+
+### PressableFeedback.Scale
+
+对容器内指定子元素应用缩放时使用；根上设 `animation={false}` 以关闭其内置缩放。
+
+| prop                    | type                              | default | description                                                  |
+| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                          | -       | 额外的 class                                                 |
+| `animation`             | `PressableFeedbackScaleAnimation` | -       | 缩放动画配置                                                 |
+| `isAnimatedStyleActive` | `boolean`                         | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `style`                 | `ViewStyle`                       | -       | 额外样式                                                     |
+| `...AnimatedProps`      | `AnimatedProps<ViewProps>`        | -       | 支持 Reanimated `Animated.View` 的属性                       |
+
+#### PressableFeedbackScaleAnimation
+
+缩放动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用缩放动画
+- `true` 或 `undefined`：使用默认缩放动画
+- `object`：自定义缩放配置
+
+| prop                     | type                    | default                                              | description                                                                |
+| ------------------------ | ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
+| `state`                  | `'disabled' \| boolean` | -                                                    | 在自定义属性时禁用动画                                                     |
+| `value`                  | `number`                | `0.985`                                              | 按下时的缩放值（会随容器宽度自动调整）                                     |
+| `timingConfig`           | `WithTimingConfig`      | `{ duration: 300, easing: Easing.out(Easing.ease) }` | 时间曲线配置                                                               |
+| `ignoreScaleCoefficient` | `boolean`               | `false`                                              | 为 true 时忽略自动缩放系数，直接使用 `value`                               |
+
+### PressableFeedback.Highlight
+
+| prop                    | type                                  | default | description                                                  |
+| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                              | -       | 额外的 class                                                 |
+| `animation`             | `PressableFeedbackHighlightAnimation` | -       | 高亮层动画配置                                               |
+| `isAnimatedStyleActive` | `boolean`                             | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `style`                 | `ViewStyle`                           | -       | 额外样式                                                     |
+| `...AnimatedProps`      | `AnimatedProps<ViewProps>`            | -       | 支持 Reanimated `Animated.View` 的属性                       |
+
+#### PressableFeedbackHighlightAnimation
+
+高亮层动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用高亮动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                    | type                    | default             | description                       |
+| ----------------------- | ----------------------- | ------------------- | --------------------------------- |
+| `state`                 | `'disabled' \| boolean` | -                   | 在自定义属性时禁用动画            |
+| `opacity.value`         | `[number, number]`      | `[0, 0.1]`          | 不透明度 [未按下, 按下]           |
+| `opacity.timingConfig`  | `WithTimingConfig`      | `{ duration: 200 }` | 时间曲线配置                      |
+| `backgroundColor.value` | `string`                | 随主题灰色          | 高亮层背景色                      |
+
+### PressableFeedback.Ripple
+
+| prop                    | type                                      | default | description                                                  |
+| ----------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                                  | -       | 容器插槽的 class                                             |
+| `classNames`            | `ElementSlots<RippleSlots>`               | -       | 各插槽 class（container、ripple）                            |
+| `styles`                | `Partial<Record<RippleSlots, ViewStyle>>` | -       | 涟漪遮罩各部分的样式                                         |
+| `animation`             | `PressableFeedbackRippleAnimation`        | -       | 涟漪动画配置                                                 |
+| `isAnimatedStyleActive` | `boolean`                                 | `true`  | 是否启用 Reanimated 动画样式                                 |
+| `...ViewProps`          | `Omit<ViewProps, 'style'>`                | -       | 支持 `View` 属性（不含 `style`）                             |
+
+#### `styles`
+
+| prop        | type        | description   |
+| ----------- | ----------- | ------------- |
+| `container` | `ViewStyle` | 容器插槽样式  |
+| `ripple`    | `ViewStyle` | 涟漪插槽样式  |
+
+#### PressableFeedbackRippleAnimation
+
+涟漪动画配置，可为：
+
+- `false` 或 `"disabled"`：禁用涟漪动画
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop                                 | type                       | default                 | description                                                                  |
+| ------------------------------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`                              | `'disabled' \| boolean`    | -                       | 在自定义属性时禁用动画                                                       |
+| `backgroundColor.value`              | `string`                   | 随主题计算              | 涟漪背景色                                                                   |
+| `progress.baseDuration`              | `number`                   | `1000`                  | 涟漪进度基准时长（会按对角线自动调整）                                       |
+| `progress.minBaseDuration`           | `number`                   | `750`                   | 进度动画最小时长                                                             |
+| `progress.ignoreDurationCoefficient` | `boolean`                  | `false`                 | 为 true 时忽略自动时长系数，直接使用基准时长                                 |
+| `opacity.value`                      | `[number, number, number]` | `[0, 0.1, 0]`           | 不透明度 [起始, 峰值, 结束]                                                  |
+| `opacity.timingConfig`               | `WithTimingConfig`         | `{ duration: 200 }`     | 时间曲线配置                                                                 |
+| `scale.value`                        | `[number, number, number]` | `[0, 1, 1]`             | 缩放 [起始, 峰值, 结束]                                                      |
+| `scale.timingConfig`                 | `WithTimingConfig`         | `{ duration: 200 }`     | 时间曲线配置                                                                 |
+
+#### `ElementSlots<RippleSlots>`
+
+涟漪各插槽的额外 class：
+
+| slot        | description                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `container` | 外层容器（`absolute inset-0`），可通过 class 完全定制样式                                                           |
+| `ripple`    | 内层涟漪（`absolute top-0 left-0 rounded-full`），带动画属性，不宜用 className 覆盖动画相关表现                  |
diff --git a/apps/docs/content/docs/cn/native/components/(utilities)/scroll-shadow.mdx b/apps/docs/content/docs/cn/native/components/(utilities)/scroll-shadow.mdx
new file mode 100644
index 0000000..e73b93a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/(utilities)/scroll-shadow.mdx
@@ -0,0 +1,216 @@
+---
+title: ScrollShadow 滚动阴影
+description: 根据滚动位置与溢出情况，为可滚动内容添加动态渐变边缘阴影。
+links:
+  source_native: scroll-shadow/scroll-shadow.tsx
+  styles_native: scroll-shadow/scroll-shadow.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scroll-shadow-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scoll-shadow-docs-dark.mp4.mp4"
+/>
+
+## 导入
+
+```tsx
+import { ScrollShadow } from 'heroui-native';
+```
+
+## 结构
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+- **ScrollShadow**：包裹可滚动组件，按滚动位置与内容溢出在边缘显示动态渐变阴影；自动识别横向/纵向滚动并管理阴影显隐。
+- **LinearGradientComponent**：必填，传入兼容库的 `LinearGradient`（如 expo-linear-gradient、react-native-linear-gradient）以绘制渐变阴影。
+
+## 用法
+
+### 基础用法
+
+包裹任意可滚动组件，自动在边缘添加阴影。
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### 横向滚动
+
+根据子组件的 `horizontal` 属性自动识别横向滚动。
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <FlatList horizontal data={data} renderItem={...} />
+</ScrollShadow>
+```
+
+### 自定义阴影尺寸
+
+用 `size` 控制渐变阴影的高度或宽度（像素）。
+
+```tsx
+<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### 显隐控制
+
+用 `visibility` 指定显示哪些边的阴影。
+
+```tsx
+<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="bottom" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="none" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### 自定义阴影颜色
+
+覆盖默认使用主题背景的阴影颜色。
+
+```tsx
+<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### 自定义滚动处理
+
+**重要：** ScrollShadow 内部会将子节点转为 Reanimated 动画组件。若需使用 `onScroll`，必须使用 `react-native-reanimated` 的 `useAnimatedScrollHandler`，而不能使用普通的 `onScroll`。
+
+```tsx
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';
+
+const scrollHandler = useAnimatedScrollHandler({
+  onScroll: (event) => {
+    console.log(event.contentOffset.y);
+  },
+});
+
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
+</ScrollShadow>;
+```
+
+## 示例
+
+```tsx
+import { ScrollShadow, Surface } from 'heroui-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { FlatList, ScrollView, Text, View } from 'react-native';
+
+export default function ScrollShadowExample() {
+  const horizontalData = Array.from({ length: 10 }, (_, i) => ({
+    id: i,
+    title: `Card ${i + 1}`,
+  }));
+
+  return (
+    <View className="flex-1 bg-background">
+      <Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
+      <ScrollShadow LinearGradientComponent={LinearGradient}>
+        <FlatList
+          data={horizontalData}
+          horizontal
+          renderItem={({ item }) => (
+            <Surface variant="2" className="w-32 h-24 justify-center px-4">
+              <Text>{item.title}</Text>
+            </Surface>
+          )}
+          showsHorizontalScrollIndicator={false}
+          contentContainerClassName="p-5 gap-4"
+        />
+      </ScrollShadow>
+
+      <Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
+      <ScrollShadow
+        size={80}
+        className="h-48"
+        LinearGradientComponent={LinearGradient}
+      >
+        <ScrollView
+          contentContainerClassName="p-5"
+          showsVerticalScrollIndicator={false}
+        >
+          <Text className="mb-4 text-2xl font-bold">Long Content</Text>
+          <Text className="mb-4 text-base leading-6">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+            ad minim veniam, quis nostrud exercitation ullamco laboris.
+          </Text>
+          <Text className="mb-4 text-base leading-6">
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+            accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
+            quae ab illo inventore veritatis et quasi architecto beatae vitae.
+          </Text>
+        </ScrollView>
+      </ScrollShadow>
+    </View>
+  );
+}
+```
+
+更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/scroll-shadow.tsx)。
+
+## API 参考
+
+### ScrollShadow
+
+| prop                      | type                                                                   | default      | description                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `children`                | `React.ReactElement`                                                   | -            | 需要增强阴影的可滚动组件，须为单一 React 元素（ScrollView、FlatList 等）                                         |
+| `LinearGradientComponent` | `ComponentType<`<br/>`LinearGradientProps>`                            | **必填**     | 来自任意兼容库的 LinearGradient 组件                                                                           |
+| `size`                    | `number`                                                               | `50`         | 渐变阴影高度或宽度（像素）                                                                                     |
+| `orientation`             | `'horizontal' \| 'vertical'`                                           | 自动检测     | 阴影方向；未提供时根据子组件 `horizontal` 自动检测                                                             |
+| `visibility`              | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'`     | 阴影显隐模式；`auto` 根据滚动位置与溢出自动显示                                                                |
+| `color`                   | `string`                                                               | 主题色       | 渐变阴影自定义颜色；未提供时使用主题背景色                                                                     |
+| `isEnabled`               | `boolean`                                                              | `true`       | 是否启用阴影效果                                                                                               |
+| `animation`               | `ScrollShadowRootAnimation`                                            | -            | 动画配置                                                                                                       |
+| `className`               | `string`                                                               | -            | 容器额外 class                                                                                                 |
+| `...ViewProps`            | `ViewProps`                                                            | -            | 支持 React Native `View` 的全部标准属性                                                                       |
+
+#### ScrollShadowRootAnimation
+
+ScrollShadow 动画配置，可为：
+
+- `false` 或 `"disabled"`：仅关闭根动画
+- `"disable-all"`：关闭所有动画（含子级）
+- `true` 或 `undefined`：使用默认动画
+- `object`：自定义动画配置
+
+| prop            | type                                     | default  | description                                                                         |
+| --------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| 'disable-all' \| boolean` | -        | 关闭动画的同时仍允许自定义属性                                                     |
+| `opacity.value` | `[number, number]`                       | `[0, 1]` | 不透明度 [初始, 激活]；底部/右侧阴影时顺序相反                                   |
+
+### LinearGradientProps
+
+`LinearGradientComponent` 应接受以下属性：
+
+| prop        | type                              | description                                                        |
+| ----------- | --------------------------------- | ------------------------------------------------------------------ |
+| `colors`    | `any`                             | 渐变颜色数组                                                       |
+| `locations` | `any`（可选）                     | 各颜色停靠位置                                                     |
+| `start`     | `any`（可选）                     | 渐变起点，如 `{ x: 0, y: 0 }`                                     |
+| `end`       | `any`（可选）                     | 渐变终点，如 `{ x: 1, y: 0 }`                                     |
+| `style`     | `StyleProp<ViewStyle>`（可选）    | 应用于渐变视图的样式                                               |
+
+## 特别说明
+
+**重要：** ScrollShadow 内部会将子节点转为 Reanimated 动画组件。若需在可滚动组件上使用滚动回调，必须使用 `react-native-reanimated` 的 `useAnimatedScrollHandler`，不能使用标准 `onScroll`。
diff --git a/apps/docs/content/docs/cn/native/components/index.mdx b/apps/docs/content/docs/cn/native/components/index.mdx
new file mode 100644
index 0000000..888bf71
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/index.mdx
@@ -0,0 +1,48 @@
+---
+title: 所有组件
+description: 浏览 HeroUI Native 提供的全部组件；更多组件将陆续推出。
+---
+
+## 按钮
+
+<NativeComponentsCategory category="Buttons" />
+
+## 集合
+
+<NativeComponentsCategory category="Collections" />
+
+## 控件
+
+<NativeComponentsCategory category="Controls" />
+
+## 表单
+
+<NativeComponentsCategory category="Forms" />
+
+## 导航
+
+<NativeComponentsCategory category="Navigation" />
+
+## 浮层
+
+<NativeComponentsCategory category="Overlays" />
+
+## 反馈
+
+<NativeComponentsCategory category="Feedback" />
+
+## 布局
+
+<NativeComponentsCategory category="Layout" />
+
+## 媒体
+
+<NativeComponentsCategory category="Media" />
+
+## 数据展示
+
+<NativeComponentsCategory category="Data Display" />
+
+## 工具
+
+<NativeComponentsCategory category="Utilities" />
diff --git a/apps/docs/content/docs/cn/native/components/meta.json b/apps/docs/content/docs/cn/native/components/meta.json
new file mode 100644
index 0000000..aac8155
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/components/meta.json
@@ -0,0 +1,49 @@
+{
+  "title": "组件",
+  "description": "HeroUI Native 组件",
+  "root": true,
+  "icon": "circles-4-diamond",
+  "pages": [
+    "index",
+    "---组件---",
+    "(navigation)/accordion",
+    "(feedback)/alert",
+    "(media)/avatar",
+    "(overlays)/bottom-sheet",
+    "(buttons)/button",
+    "(layout)/card",
+    "(forms)/checkbox",
+    "(data-display)/chip",
+    "(buttons)/close-button",
+    "(forms)/control-field",
+    "(forms)/description",
+    "(overlays)/dialog",
+    "(forms)/field-error",
+    "(forms)/input",
+    "(forms)/input-group",
+    "(forms)/input-otp",
+    "(forms)/label",
+    "(buttons)/link-button",
+    "(navigation)/list-group",
+    "(collections)/menu",
+    "(overlays)/popover",
+    "(utilities)/pressable-feedback",
+    "(forms)/radio-group",
+    "(utilities)/scroll-shadow",
+    "(controls)/slider",
+    "(forms)/search-field",
+    "(forms)/select",
+    "(layout)/separator",
+    "(feedback)/skeleton",
+    "(feedback)/skeleton-group",
+    "(feedback)/spinner",
+    "(layout)/surface",
+    "(controls)/switch",
+    "(navigation)/tabs",
+    "(collections)/tag-group",
+    "(typography)/text",
+    "(forms)/text-area",
+    "(forms)/text-field",
+    "(overlays)/toast"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/animation.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/animation.mdx
new file mode 100644
index 0000000..c2464e8
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/animation.mdx
@@ -0,0 +1,207 @@
+---
+title: 动画
+description: 为 HeroUI Native 组件添加流畅动画与过渡
+icon: copy-transparent
+---
+
+HeroUI Native 的动画基于 [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/)，手势由 [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/) 处理。若需更细粒度控制，建议先熟悉二者。
+
+## `animation` 属性
+
+每个带动画的组件都暴露统一的 `animation` 属性，用于控制该组件上的全部动画：可调整数值、时间配置、布局动画，或完全关闭动画。
+
+**做法：** 处理动画时，先查看目标组件是否提供 `animation` 属性。
+
+## 修改动画
+
+向 `animation` 传入对象即可定制。不同组件暴露的可调属性不同。若只想微调内置动画，可使用我们提供的各项配置；若要完全自定义动画逻辑，通常需要自行编写带动画的自定义组件。
+
+### 示例 1：简单数值调整
+
+调整缩放、透明度或颜色等数值：
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  animation={{
+    scale: {
+      value: [1, 0.9], // [unpressed, pressed]
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'], // [unselected, selected]
+    },
+  }}>
+  <Switch.Thumb />
+</Switch>;
+```
+
+### 示例 2：时间曲线配置
+
+自定义时长与缓动：
+
+```tsx
+import {Accordion} from 'heroui-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      <Accordion.Indicator
+        animation={{
+          rotation: {
+            value: [0, -180],
+            springConfig: {
+              damping: 60,
+              stiffness: 900,
+              mass: 3,
+            },
+          },
+        }}
+      />
+    </Accordion.Trigger>
+  </Accordion.Item>
+</Accordion>;
+```
+
+### 示例 3：布局动画（进入 / 退出）
+
+使用 Reanimated 的布局动画 API：
+
+```tsx
+import {Accordion} from 'heroui-native';
+import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
+import {Easing} from 'react-native-reanimated';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Content
+      animation={{
+        entering: {
+          value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
+        },
+      }}>
+      Content here
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>;
+```
+
+### 示例 4：使用 `state` 精细控制
+
+`state` 可在关闭动画的同时仍保留属性配置，便于微调而不真正播放动画：
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  animation={{
+    state: 'disabled', // Disable animations but allow property customization
+    scale: {
+      value: 0.95, // This value is still respected even though animations are disabled
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'],
+    },
+  }}>
+  <Switch.Thumb />
+</Switch>
+```
+
+`state` 可取：
+
+- `'disabled'`：关闭动画，但仍可配置属性值
+- `'disable-all'`：关闭自身及子级全部动画（仅在根级可用）
+- `boolean`：简单开关（`true` 启用，`false` 禁用）
+
+这样既能精细控制动画行为，又能在不启用动画的情况下自定义属性值。
+
+## 关闭动画
+
+可通过 `animation` 在不同层级关闭动画。
+
+### 关闭选项
+
+- `animation={false}` 或 `animation="disabled"`：仅关闭当前组件动画
+- `animation="disable-all"`：关闭根级及其子级全部动画（仅根级可用）
+- `animation={true}` 或 `animation={undefined}`：使用默认动画
+
+### 组件级关闭
+
+仅关闭某个子部件的动画：
+
+```tsx
+<Switch>
+  <Switch.Thumb animation={false} />
+</Switch>
+```
+
+### 根级 `disable-all`
+
+`"disable-all"` 仅在复合组件根级可用，会向下级联，**包括**树中的独立组件（如 `Button`、`Spinner` 等），不仅限于复合子部件：
+
+```tsx
+// Disables all animations including Button components inside Card
+<Card animation="disable-all">
+  <Card.Body>
+    <Card.Title>$450</Card.Title>
+    <Card.Description>Living room Sofa</Card.Description>
+  </Card.Body>
+  <Card.Footer className="gap-3">
+    <Button variant="primary">Buy now</Button>
+    <Button variant="ghost">Add to cart</Button>
+  </Card.Footer>
+</Card>
+```
+
+**注意：** `"disable-all"` 会级联到所有子组件，包括独立的 `Button`、`Spinner` 等。
+
+## 全局动画配置
+
+在 `HeroUINativeProvider` 上统一关闭应用内全部 HeroUI Native 动画：
+
+```tsx
+import {HeroUINativeProvider} from 'heroui-native';
+
+<HeroUINativeProvider
+  config={{
+    animation: 'disable-all',
+  }}>
+  <App />
+</HeroUINativeProvider>;
+```
+
+这会覆盖各组件自身的 `animation` 设置，全局禁用动画。
+
+## 无障碍
+
+系统「减少动态效果」会在底层自动处理：当用户开启该无障碍选项时，库会通过 `GlobalAnimationSettingsProvider` 与 Reanimated 的 `useReducedMotion()` 全局关闭动画。
+
+你通常无需额外编码，库会尊重系统无障碍偏好。
+
+## 动画状态管理
+
+内部会统一管理禁用态，避免关闭动画后出现卡顿或跳变：禁用时组件会直接落到终态，而不是播放到一半。
+
+## 子级渲染函数
+
+许多组件支持将 `children` 设为函数，便于根据 `isSelected` 等状态渲染：
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}>
+  {({isSelected, isDisabled}) => (
+    <Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
+  )}
+</Switch>;
+```
+
+该模式便于根据选中、禁用等状态构建动态界面。
+
+## 下一步
+
+- [样式](/docs/native/getting-started/styling)
+- [主题](/docs/native/getting-started/theming)
+- [颜色](/docs/native/getting-started/colors)
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/colors.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/colors.mdx
new file mode 100644
index 0000000..4a717c2
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/colors.mdx
@@ -0,0 +1,478 @@
+---
+title: 颜色
+description: HeroUI Native 的调色板与主题系统
+icon: bucket-paint
+links:
+  themes: true
+  tailwind: theme
+---
+
+import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";
+
+HeroUI Native 的颜色体系围绕语义意图构建，而非堆砌视觉色板。系统不会暴露庞大的原始色表，而是定义一小套有意义的色彩角色，覆盖绝大多数界面需求。
+
+系统中的多数颜色会由少量基础值自动派生。这样 HeroUI 能在保持对比度、层级与主题行为一致的同时，让整套体系易于理解与修改。
+
+颜色应首先传达用途与状态；视觉变化来自尺度、强调与上下文。
+
+## 强调色
+
+强调色代表品牌或产品的主识别色，用于吸引对关键操作、高亮与重点时刻的注意。
+
+强调色应有意识地节制使用。滥用会削弱其冲击力，并破坏视觉层级。多数情况下，组件会从基础强调色自动派生悬停、柔和背景与聚焦等相关取值。
+
+<ColorSectionSideBySide
+  name="强调色"
+  baseVariable="--accent"
+  hoverVariable="--accent"
+  hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
+  foregroundVariable="--accent-foreground"
+  soft={{
+    baseVariable: "--accent",
+    baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
+    hoverVariable: "--accent",
+    hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
+    foregroundVariable: "--accent",
+    foregroundCssValue: "var(--accent)",
+  }}
+/>
+
+## 默认（中性色）
+
+默认色构成系统的中性骨架，用于大多数非强调的界面元素。
+
+<ColorSectionSideBySide
+  name="默认"
+  baseVariable="--default"
+  hoverVariable="--default"
+  hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
+  foregroundVariable="--default-foreground"
+/>
+
+## 成功
+
+成功色传达积极结果、确认与完成状态，常见于反馈组件、状态指示与校验通过等场景。
+
+<ColorSectionSideBySide
+  name="成功"
+  baseVariable="--success"
+  hoverVariable="--success"
+  hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
+  foregroundVariable="--success-foreground"
+  soft={{
+    baseVariable: "--success",
+    baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
+    hoverVariable: "--success",
+    hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
+    foregroundVariable: "--success",
+    foregroundCssValue: "var(--success)",
+  }}
+/>
+
+## 警告
+
+警告色表示需谨慎、存在风险，或需要留意但非破坏性的操作，常用于提示、消息以及用户应暂停或复核信息的过渡状态。
+
+<ColorSectionSideBySide
+  name="警告"
+  baseVariable="--warning"
+  hoverVariable="--warning"
+  hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
+  foregroundVariable="--warning-foreground"
+  soft={{
+    baseVariable: "--warning",
+    baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
+    hoverVariable: "--warning",
+    hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
+    foregroundVariable: "--warning",
+    foregroundCssValue: "var(--warning)",
+  }}
+/>
+
+## 危险
+
+危险色表示破坏性、不可逆或关键的操作与状态，应一眼可辨，并稳定用于错误、危险按钮与严重告警。
+
+<ColorSectionSideBySide
+  name="危险"
+  baseVariable="--danger"
+  hoverVariable="--danger"
+  hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
+  foregroundVariable="--danger-foreground"
+  soft={{
+    baseVariable: "--danger",
+    baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
+    hoverVariable: "--danger",
+    hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
+    foregroundVariable: "--danger",
+    foregroundCssValue: "var(--danger)",
+  }}
+/>
+
+## 前景色
+
+前景色用于正文级内容，如文字与图标。这些颜色针对可读性与无障碍优化，并会随背景与表面上下文自动适配。请勿在组件内硬编码前景色。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "前景", variable: "--foreground" },
+    { label: "弱化", variable: "--muted" },
+    { label: "分段", variable: "--segment" },
+    { label: "覆盖层", variable: "--overlay" },
+    { label: "链接", variable: "--link" },
+  ]}
+  darkColors={[
+    { label: "前景", variable: "--foreground", border: true },
+    { label: "弱化", variable: "--muted", border: true },
+    { label: "分段", variable: "--segment", border: true },
+    { label: "覆盖层", variable: "--overlay", border: true },
+    { label: "链接", variable: "--link", border: true },
+  ]}
+/>
+
+## 背景色
+
+背景色定义界面的基底画布，在保持视觉克制的前提下建立整体对比与氛围。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "背景", variable: "--background", border: true },
+    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
+    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
+    { label: "反色", variable: "--foreground" },
+  ]}
+  darkColors={[
+    { label: "背景", variable: "--background", border: true },
+    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
+    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
+    { label: "反色", variable: "--foreground", border: true },
+  ]}
+/>
+
+## 表面色
+
+表面色叠在背景之上，用于卡片、面板、模态与下拉等容器。表面通过抬升、对比与分层形成区隔与层级，而非依赖强烈的色相跳跃。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "表面", variable: "--surface", border: true },
+    { label: "次级", variable: "--surface-secondary", border: true },
+    { label: "第三级", variable: "--surface-tertiary", border: true },
+  ]}
+  darkColors={[
+    { label: "表面", variable: "--surface", border: true },
+    { label: "次级", variable: "--surface-secondary", border: true },
+    { label: "第三级", variable: "--surface-tertiary", border: true },
+  ]}
+/>
+
+## 表单字段
+
+表单字段色是面向输入、控件与可交互字段的专用令牌，覆盖默认、聚焦与悬停等多种状态。将其独立出来，可让表单元素在视觉上与按钮及界面其余部分保持清晰区分。
+
+<ColorSectionFormField
+  colors={{
+    bg: "--field-background",
+    bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
+    placeholder: "--field-placeholder",
+    foreground: "--field-foreground",
+  }}
+/>
+
+## 分隔线
+
+分隔线色用于分割线、描边与轻量边界，用来组织内容、引导视线而不增加噪点。分隔线色应保持低对比、不抢眼。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "分隔线", variable: "--separator", border: true },
+    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
+    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
+  ]}
+  darkColors={[
+    { label: "分隔线", variable: "--separator", border: true },
+    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
+    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
+  ]}
+/>
+
+## 其他
+
+其他颜色在界面中承担特定工具性角色，用于组织内容、引导视线而不增加噪点。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "边框", variable: "--border" },
+    { label: "背衬", variable: "--backdrop" },
+    { label: "覆盖层", variable: "--overlay", border: true },
+    { label: "分段", variable: "--segment", border: true },
+  ]}
+  darkColors={[
+    { label: "边框", variable: "--border" },
+    { label: "背衬", variable: "--backdrop" },
+    { label: "覆盖层", variable: "--overlay", border: true },
+    { label: "分段", variable: "--segment", border: true },
+  ]}
+/>
+
+## 基础色
+
+基础色是与模式无关的底层取值，作为语义色令牌的根基，在明暗主题之间不会改变。
+
+<ColorSectionPrimitive
+  colors={[
+    { label: "白", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
+    { label: "黑", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
+    { label: "雪白", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
+    { label: "月蚀", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
+  ]}
+/>
+
+## 如何使用颜色
+
+**在组件中：**
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-background flex-1 p-4">
+  <Text className="text-foreground mb-4">内容</Text>
+  <Button variant="primary" className="bg-accent">
+    <Button.Label className="text-accent-foreground">点击我</Button.Label>
+  </Button>
+</View>;
+```
+
+**在 CSS 文件中：**
+
+```css title="global.css"
+/* 直接使用 CSS 变量 */
+.container {
+  flex: 1;
+  background-color: var(--accent);
+  width: 50px;
+  height: 50px;
+  border-radius: var(--radius);
+}
+```
+
+## 默认主题
+
+完整主题定义见仓库中的 [variables.css](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/variables.css)。该主题通过 [Uniwind 主题系统](https://docs.uniwind.dev/theming/basics) 在明暗模式间自动切换，并支持跟随系统与在代码中切换主题。
+
+<CollapsibleCode lang="css" code={`  @theme {
+    /* 基础色（在明暗模式间保持不变） */
+    --white: oklch(100% 0 0);
+    --black: oklch(0% 0 0);
+    --snow: oklch(0.9911 0 0);
+    --eclipse: oklch(0.2103 0.0059 285.89);
+
+    /* 边框 */
+    --border-width: 1px;
+    --field-border-width: 0px;
+
+    /* 基础圆角 */
+    --radius: 0.5rem;
+    --field-radius: calc(var(--radius) * 1.5);
+
+    /* 不透明度 */
+    --opacity-disabled: 0.5;
+}
+
+@layer theme {
+    :root {
+      @variant light {
+        /* 基础颜色 */
+        --background: oklch(0.9702 0 0);
+        --foreground: var(--eclipse);
+
+        /* 表面 */
+        --surface: var(--white);
+        --surface-foreground: var(--foreground);
+
+        --surface-secondary: oklch(0.9524 0.0013 286.37);
+        --surface-secondary-foreground: var(--foreground);
+
+        --surface-tertiary: oklch(0.9373 0.0013 286.37);
+        --surface-tertiary-foreground: var(--foreground);
+
+        /* 覆盖层 */
+        --overlay: var(--white);
+        --overlay-foreground: var(--foreground);
+        --backdrop: oklch(0% 0 0 / 20%);
+
+        --muted: oklch(0.5517 0.0138 285.94);
+
+        --default: oklch(94% 0.001 286.375);
+        --default-foreground: var(--eclipse);
+
+        --accent: oklch(0.6204 0.195 253.83);
+        --accent-foreground: var(--snow);
+
+        /* 表单字段 */
+        --field-background: var(--white);
+        --field-foreground: oklch(0.2103 0.0059 285.89);
+        --field-placeholder: var(--muted);
+        --field-border: transparent;
+
+        /* 状态色 */
+        --success: oklch(0.7329 0.1935 150.81);
+        --success-foreground: var(--eclipse);
+
+        --warning: oklch(0.7819 0.1585 72.33);
+        --warning-foreground: var(--eclipse);
+
+        --danger: oklch(0.6532 0.2328 25.74);
+        --danger-foreground: var(--snow);
+
+        /* 组件颜色 */
+        --segment: var(--white);
+        --segment-foreground: var(--eclipse);
+
+        /* 杂项颜色 */
+        --border: oklch(90% 0.004 286.32);
+        --separator: oklch(74% 0.004 286.32);
+        --focus: var(--accent);
+        --link: var(--foreground);
+      }
+
+      @variant dark {
+        /* 基础颜色 */
+        --background: oklch(12% 0.005 285.823);
+        --foreground: var(--snow);
+
+        /* 表面 */
+        --surface: oklch(0.2103 0.0059 285.89);
+        --surface-foreground: var(--foreground);
+
+        --surface-secondary: oklch(0.257 0.0037 286.14);
+        --surface-secondary-foreground: var(--foreground);
+
+        --surface-tertiary: oklch(0.2721 0.0024 247.91);
+        --surface-tertiary-foreground: var(--foreground);
+
+        /* 覆盖层 */
+        --overlay: oklch(0.2103 0.0059 285.89);
+        --overlay-foreground: var(--foreground);
+        --backdrop: oklch(0% 0 0 / 20%);
+
+        --muted: oklch(70.5% 0.015 286.067);
+
+        --default: oklch(27.4% 0.006 286.033);
+        --default-foreground: var(--snow);
+
+        --accent: oklch(0.6204 0.195 253.83);
+        --accent-foreground: var(--snow);
+
+        /* 表单字段 */
+        --field-background: oklch(0.2103 0.0059 285.89);
+        --field-foreground: var(--foreground);
+        --field-placeholder: var(--muted);
+        --field-border: transparent;
+
+        /* 状态色 */
+        --success: oklch(0.7329 0.1935 150.81);
+        --success-foreground: var(--eclipse);
+
+        --warning: oklch(0.8203 0.1388 76.34);
+        --warning-foreground: var(--eclipse);
+
+        --danger: oklch(0.594 0.1967 24.63);
+        --danger-foreground: var(--snow);
+
+        /* 组件颜色 */
+        --segment: oklch(0.3964 0.01 285.93);
+        --segment-foreground: var(--foreground);
+
+        /* 杂项颜色 */
+        --border: oklch(28% 0.006 286.033);
+        --separator: oklch(40% 0.006 286.033);
+        --focus: var(--accent);
+        --link: var(--foreground);
+      }
+    }
+  }
+`}
+/>
+
+## 自定义颜色
+
+**覆盖已有颜色：**
+
+```css
+@layer theme {
+  @variant light {
+    /* 覆盖默认颜色 */
+    --accent: oklch(0.65 0.25 270); /* 自定义靛蓝强调色 */
+    --success: oklch(0.65 0.15 155);
+  }
+
+  @variant dark {
+    /* 覆盖深色主题颜色 */
+    --accent: oklch(0.65 0.25 270);
+    --success: oklch(0.75 0.12 155);
+  }
+}
+```
+
+**提示：** 可在 [oklch.com](https://oklch.com) 转换颜色。
+
+**添加自定义颜色：**
+
+```css
+@layer theme {
+  @variant light {
+    --info: oklch(0.6 0.15 210);
+    --info-foreground: oklch(0.98 0 0);
+  }
+
+  @variant dark {
+    --info: oklch(0.7 0.12 210);
+    --info-foreground: oklch(0.15 0 0);
+  }
+}
+
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+随后即可使用：
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-info p-4 rounded-lg">
+  <Text className="text-info-foreground">提示信息</Text>
+</View>;
+```
+
+> **注意：** 若要进一步了解主题变量及其在 Tailwind CSS v4 中的行为，请参阅 [Tailwind CSS 主题文档](https://tailwindcss.com/docs/theme)。
+
+## useThemeColor 钩子
+
+`useThemeColor` 钩子已增强，支持一次选取多种颜色，在复杂主题场景下更灵活。
+
+**一次选取多种颜色：**
+
+现在可以同时选取多种颜色，在需要一并处理相关色值时很有用：
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+// 一次选取多种颜色
+const [accent, accentForeground, success, danger] = useThemeColor([
+  'accent',
+  'accentForeground',
+  'success',
+  'danger',
+]);
+
+// 使用所选颜色
+<View style={{ backgroundColor: accent }}>
+  <Text style={{ color: accentForeground }}>强调色文字</Text>
+</View>;
+```
+
+该改进在需要同时选取并应用多种颜色时，可提升性能，也便于管理复杂的主题组合。
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/composition.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/composition.mdx
new file mode 100644
index 0000000..a59bd01
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/composition.mdx
@@ -0,0 +1,201 @@
+---
+title: 组合
+description: 用组件组合模式搭建灵活 UI
+icon: layers
+---
+
+HeroUI Native 通过组合模式实现灵活、可定制的组件：可更换实际渲染元素、将多个部件拼在一起，并完全掌控结构。
+
+## 复合组件
+
+HeroUI Native 采用点记法的复合组件——子组件作为属性导出（如 `Button.Label`、`Dialog.Trigger`、`Accordion.Item`），共同构成完整界面。
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+
+function DialogExample() {
+  return (
+    <Dialog>
+      <Dialog.Trigger>
+        打开对话框
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Close />
+          <Dialog.Title>对话框标题</Dialog.Title>
+          <Dialog.Description>对话框说明</Dialog.Description>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+## asChild 属性
+
+`asChild` 用于改变组件实际渲染的元素。为 `true` 时，HeroUI Native 会克隆子元素并合并属性，而不是渲染默认包裹节点。
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+
+function DialogExample() {
+  return (
+    <Dialog>
+      {/* asChild：Button 直接作为触发器，无额外包裹 */}
+      <Dialog.Trigger asChild>
+        <Button variant="primary">打开对话框</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          {/* Dialog.Close 也可使用 asChild */}
+          <Dialog.Close asChild>
+            <Button variant="ghost" size="sm">取消</Button>
+          </Dialog.Close>
+          <Dialog.Title>对话框标题</Dialog.Title>
+          <Dialog.Description>对话框说明</Dialog.Description>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+## 自定义组件
+
+通过组合 HeroUI Native 原语封装自己的组件：
+
+```tsx
+import { Button, Card, Popover } from 'heroui-native';
+import { View } from 'react-native';
+
+// 商品卡片
+function ProductCard({ title, description, price, onBuy, ...props }) {
+  return (
+    <Card {...props}>
+      <Card.Body>
+        <Card.Title>{price}</Card.Title>
+        <Card.Title>{title}</Card.Title>
+        <Card.Description>{description}</Card.Description>
+      </Card.Body>
+      <Card.Footer>
+        <Button variant="primary" onPress={onBuy}>
+          <Button.Label>立即购买</Button.Label>
+        </Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+
+// 带 Popover 的按钮
+function PopoverButton({ children, popoverContent, ...props }) {
+  return (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button {...props}>
+          <Button.Label>{children}</Button.Label>
+        </Button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Overlay />
+        <Popover.Content>
+          <Popover.Close />
+          {popoverContent}
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover>
+  );
+}
+
+// 用法
+<ProductCard
+  title="客厅沙发"
+  description="适合现代家居空间"
+  price="$450"
+  onBuy={() => console.log('购买')}
+/>
+
+<PopoverButton variant="tertiary" popoverContent={
+  <View>
+    <Popover.Title>说明</Popover.Title>
+    <Popover.Description>更多详情见此处</Popover.Description>
+  </View>
+}>
+  显示说明
+</PopoverButton>
+```
+
+## 自定义变体
+
+可用 `tailwind-variants` 扩展样式。**文字颜色类须加在 `Button.Label` 上，而不是父级 `Button`：**
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const customButtonVariants = tv({
+  base: 'font-semibold rounded-lg',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500',
+      secondary: 'bg-gray-200',
+      danger: 'bg-red-500',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+const customLabelVariants = tv({
+  base: '',
+  variants: {
+    intent: {
+      primary: 'text-white',
+      secondary: 'text-gray-800',
+      danger: 'text-white',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+
+interface CustomButtonProps
+  extends Omit<ButtonRootProps, 'className' | 'variant'>,
+    CustomButtonVariants {
+  className?: string;
+  labelClassName?: string;
+}
+
+export function CustomButton({
+  intent,
+  className,
+  labelClassName,
+  children,
+  ...props
+}: CustomButtonProps) {
+  return (
+    <Button
+      className={customButtonVariants({ intent, className })}
+      {...props}
+    >
+      <Button.Label
+        className={customLabelVariants({ intent, className: labelClassName })}
+      >
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+## 下一步
+
+- 了解 [样式](/docs/native/getting-started/styling) 体系
+- 阅读 [主题](/docs/native/getting-started/theming) 文档
+- 探索 [动画](/docs/native/getting-started/animation) 选项
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/portal.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/portal.mdx
new file mode 100644
index 0000000..23e8411
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/portal.mdx
@@ -0,0 +1,143 @@
+---
+title: Portal
+icon: windows
+---
+
+Portal 可将子节点渲染到应用中的其他位置，特别适用于需要浮在其他内容之上的组件，例如模态框、覆盖层与弹出层。
+
+## 默认配置
+
+默认情况下，`PortalHost` 已包含在 `HeroUINativeProvider` 中，无需手动添加。Provider 会自动为所有使用 Portal 的组件设置好Portal系统。
+
+## 进阶用法
+
+如需自定义Portal实现，可直接从 `heroui-native` 导入 `Portal` 与 `PortalHost`：
+
+```tsx
+import { Portal, PortalHost } from "heroui-native";
+import { View, Text } from "react-native";
+
+function AppLayout() {
+  return (
+    <View className="flex-1">
+      <View className="p-5">
+        <Text>Header Content</Text>
+      </View>
+      
+      <View className="flex-1 p-5">
+        <Text>Main Content Area</Text>
+        <CustomNotification />
+      </View>
+      
+      {/* Portal host positioned at the top of the screen */}
+      <PortalHost name="notification-host" />
+    </View>
+  );
+}
+
+function CustomNotification() {
+  return (
+    <Portal name="notification-portal" hostName="notification-host">
+      <View className="absolute top-0 left-0 right-0 bg-blue-500 p-4">
+        <Text>This notification appears at the top via Portal</Text>
+      </View>
+    </Portal>
+  );
+}
+```
+
+本例中，`CustomNotification` 组件通过 `Portal` 将内容渲染到位于屏幕顶部的 `PortalHost` 处，使通知浮于所有其他内容之上，无论它在组件树中的实际定义位置在哪。
+
+## 状态管理注意事项
+
+父组件中的状态变化可能导致Portal内组件出现意外问题。例如，将文本输入框直接放入Portal内时，若父组件触发重渲染，可能会重置输入框的自动建议，或导致其他界面异常。
+
+为避免该问题，请将交互组件（如输入框）的状态保留在Portal内部：把Portal内容拆分为独立组件，从而隔离父组件重渲染带来的影响。
+
+### 示例模式
+
+```tsx
+// ❌ 问题：父级状态导致重渲染，影响Portal内内容
+function ParentComponent() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [inputValue, setInputValue] = useState(""); // State in parent
+  
+  return (
+    <Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
+      <Dialog.Trigger>
+        <Button>Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Input 
+          value={inputValue} 
+          onChangeText={setInputValue} 
+          // Parent re-renders reset auto-suggestions
+        />
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+
+// ✅ 正确：在Portal内的独立组件中管理状态
+function ParentComponent() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  
+  return (
+    <Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
+      <Dialog.Trigger>
+        <Button>Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <DialogFormContent 
+          onClose={() => setDialogOpen(false)} 
+          // Form state isolated from parent
+        />
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+
+function DialogFormContent({ onClose }: { onClose: () => void }) {
+  const [inputValue, setInputValue] = useState(""); // State inside portal
+  const [error, setError] = useState("");
+  
+  return (
+    <Dialog.Content>
+      <Input 
+        value={inputValue} 
+        onChangeText={setInputValue}
+        // Auto-suggestions preserved during parent re-renders
+      />
+      <FieldError>{error}</FieldError>
+      <Button onPress={onClose}>Close</Button>
+    </Dialog.Content>
+  );
+}
+```
+
+在正确示例中，`DialogFormContent` 独立于父组件管理自身状态。这样即便父组件因 `dialogOpen` 等变化而重渲染，也不会影响输入框的内部状态，从而保留自动建议等输入行为。
+
+## API 参考
+
+### PortalHost
+
+默认情况下，所有 `Portal` 组件的子内容都会作为该 `PortalHost` 的子节点进行渲染。
+
+| prop | type     | description                                                      |
+|------|----------|------------------------------------------------------------------|
+| name | `string` | 作为自定义宿主使用时提供（可选） |
+
+### Portal
+
+| prop      | type     | description                                                      |
+|-----------|----------|------------------------------------------------------------------|
+| name*     | `string` | 唯一值；同名 Portal 会替换原有 Portal                          |
+| hostName  | `string` | 子内容需要渲染到自定义宿主时提供（可选）                       |
+| children  | `React.ReactNode` | 要渲染到Portal中的内容                                   |
+
+\* 必填属性
+
+## 相关链接
+
+- [快速开始](/docs/native/getting-started/quick-start) — 基础搭建指南
+- 查阅 [Provider](/docs/native/getting-started/provider) 文档
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/provider.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/provider.mdx
new file mode 100644
index 0000000..6b7b32a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/provider.mdx
@@ -0,0 +1,492 @@
+---
+title: Provider
+description: 配置 HeroUI Native provider 的文本、文本输入、动画和 toast 设置
+icon: chevrons-expand-horizontal
+---
+
+`HeroUINativeProvider` 是根 provider 组件，用于在你的 React Native 应用中配置和初始化 HeroUI Native。它为你的应用提供全局配置和 portal 管理。
+
+## 概述
+
+该 provider 是 HeroUI Native 的主要入口点，为你的应用包裹必要的上下文和配置：
+
+- **安全区域内边距（Safe Area Insets）**：通过 `SafeAreaListener` 自动处理安全区域内边距的更新，并将其与 Uniwind 同步，以便在 Tailwind class 中使用（例如 `pb-safe-offset-3`）
+- **文本配置**：全局 Text 组件设置，确保所有 HeroUI 组件保持一致
+- **文本输入配置**：全局文本输入设置，确保所有 HeroUI 输入组件保持一致
+- **动画配置**：全局动画控制，可禁用整个应用中的所有动画
+- **Toast 配置**：全局 toast 系统配置，包括内边距、默认 props 和包裹组件
+- **Portal 管理**：处理渲染在应用层级之上的浮层、模态框及其他组件
+
+## 基础设置
+
+用该 provider 包裹你的应用根节点：
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider>{/* 你的应用内容 */}</HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## 配置选项
+
+该 provider 接受一个 `config` prop，包含以下选项：
+
+### Text 组件配置
+
+HeroUI Native 内所有 Text 组件的全局设置。这些 props 经过精心挑选，仅包含那些适合在应用中所有 Text 组件上进行全局配置的选项：
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  textProps: {
+    // 为无障碍禁用字体缩放
+    allowFontScaling: false,
+
+    // 自动调整字号以适应容器
+    adjustsFontSizeToFit: false,
+
+    // 缩放时的最大字号倍数
+    maxFontSizeMultiplier: 1.5,
+
+    // 最小字体缩放比例（仅限 iOS，0.01-1.0）
+    minimumFontScale: 0.5,
+  },
+};
+
+export default function App() {
+  return (
+    <HeroUINativeProvider config={config}>
+      {/* 你的应用内容 */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+### TextInput 组件配置
+
+HeroUI Native 内所有基于 TextInput 的组件的全局设置（例如 Input、TextArea、SearchField、InputGroup、InputOTP）。这些 props 经过精心挑选，仅包含那些适合在应用中所有输入组件上进行全局配置的选项：
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  textInputProps: {
+    // 遵循 Text Size 无障碍设置
+    allowFontScaling: false,
+
+    // 启用 allowFontScaling 时的最大字号倍数
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function App() {
+  return (
+    <HeroUINativeProvider config={config}>
+      {/* 你的应用内容 */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+<Callout type="info">
+  **注意**：这些 props 会作为默认值应用。直接传递给单个输入组件的任何 prop 都会覆盖对应的全局值。
+</Callout>
+
+### 动画配置
+
+整个应用的全局动画配置：
+
+```tsx
+const config: HeroUINativeConfig = {
+  // 禁用应用中的所有动画（级联到所有子组件）
+  animation: 'disable-all',
+};
+```
+
+<Callout type="warning">
+  **注意**：当设置为 `'disable-all'` 时，应用中的所有动画都会被禁用。这对于无障碍或性能优化很有用。
+</Callout>
+
+### 开发者信息配置
+
+控制在控制台中显示的面向开发者的提示信息：
+
+```tsx
+const config: HeroUINativeConfig = {
+  devInfo: {
+    // 禁用样式原则提示信息
+    stylingPrinciples: false,
+  },
+};
+```
+
+<Callout type="info">
+  **注意**：默认情况下会启用提示信息。设置 `stylingPrinciples: false` 可禁用在开发期间出现在控制台中的样式原则提示信息。
+</Callout>
+
+### Toast 配置
+
+配置全局 toast 系统，包括内边距、默认 props 和包裹组件。你也可以完全禁用 toast provider：
+
+**选项 1：禁用 Toast Provider**
+
+```tsx
+const config: HeroUINativeConfig = {
+  // 完全禁用 toast provider
+  toast: false,
+  // 或
+  toast: 'disabled',
+};
+```
+
+<Callout type="info">
+  **注意**：当 toast 被禁用（`false` 或 `'disabled'`）时，`ToastProvider` 将不会被渲染，你的应用中也将无法使用 toast 功能。
+</Callout>
+
+**选项 2：配置 Toast Provider**
+
+```tsx
+import { KeyboardAvoidingView } from 'react-native';
+
+const config: HeroUINativeConfig = {
+  toast: {
+    // 全局 toast 配置（作为所有 toast 的默认值）
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+      isSwipeable: true,
+      animation: true,
+    },
+    // 与屏幕边缘间距的内边距（叠加在安全区域内边距之上）
+    insets: {
+      top: 0,      // 默认值：iOS = 0，Android = 12
+      bottom: 6,   // 默认值：iOS = 6，Android = 12
+      left: 12,    // 默认值：12
+      right: 12,   // 默认值：12
+    },
+    // 开始淡出透明度前可见 toast 的最大数量
+    maxVisibleToasts: 3,
+    // 用于包裹 toast 内容的自定义包裹函数
+    contentWrapper: (children) => (
+      <KeyboardAvoidingView
+        behavior="padding"
+        keyboardVerticalOffset={24}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+  },
+};
+```
+
+## 完整示例
+
+以下是展示所有配置选项的完整示例：
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+const config: HeroUINativeConfig = {
+  // 全局文本配置
+  textProps: {
+    minimumFontScale: 0.5,
+    maxFontSizeMultiplier: 1.5,
+    allowFontScaling: true,
+    adjustsFontSizeToFit: false,
+  },
+  // 全局文本输入配置
+  textInputProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  // 全局动画配置
+  animation: 'disable-all', // 可选：禁用所有动画
+  // 开发者信息提示配置
+  devInfo: {
+    stylingPrinciples: true, // 可选：禁用样式原则提示信息
+  },
+  // 全局 toast 配置
+  // 选项 1：使用自定义设置配置 toast
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+    maxVisibleToasts: 3,
+  },
+  // 选项 2：完全禁用 toast
+  // toast: false,
+  // 或
+  // toast: 'disabled',
+};
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider config={config}>
+        <YourApp />
+      </HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## 与 Expo Router 集成
+
+使用 Expo Router 时，包裹你的根布局：
+
+```tsx
+// app/_layout.tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+import { Stack } from 'expo-router';
+
+const config: HeroUINativeConfig = {
+  textProps: {
+    minimumFontScale: 0.5,
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function RootLayout() {
+  return (
+    <HeroUINativeProvider config={config}>
+      <Stack />
+    </HeroUINativeProvider>
+  );
+}
+```
+
+## 架构
+
+### Provider 层级
+
+`HeroUINativeProvider` 内部组合了多个 provider：
+
+```
+HeroUINativeProvider
+├── SafeAreaListener（处理安全区域内边距更新）
+│   └── GlobalAnimationSettingsProvider（动画配置）
+│       └── TextComponentProvider（文本配置）
+│           └── TextInputComponentProvider（文本输入配置）
+│               └── ToastProvider（toast 配置，按条件渲染）
+│                   └── 你的应用
+│                   └── PortalHost（用于浮层）
+```
+
+<Callout type="info">
+  **注意**：`ToastProvider` 会根据 `toast` 配置按条件渲染。如果 `toast` 设置为 `false` 或 `'disabled'`，`ToastProvider` 将不会被渲染，应用内容和 `PortalHost` 会直接渲染在 `TextInputComponentProvider` 之下。
+</Callout>
+
+### 安全区域内边距处理
+
+该 provider 会自动用来自 `react-native-safe-area-context` 的 [`SafeAreaListener`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-listener) 包裹你的应用。该组件监听安全区域内边距和框架变化而不会触发重新渲染，并通过 `onChange` 回调用最新的内边距自动更新 Uniwind。
+
+## Raw Provider
+
+`HeroUINativeProviderRaw` 是 `HeroUINativeProvider` 的轻量级变体，为打包体积优化而设计。它不包含 `ToastProvider` 和 `PortalHost`，为你提供一个最精简的起点，让你只安装和添加真正需要的内容。
+
+### 何时使用
+
+当你想完全掌控打包体积中包含哪些依赖时，使用 `HeroUINativeProviderRaw`。使用从 `heroui-native/provider-raw` 导入的 raw provider 时，以下依赖是可选的，仅在你使用对应组件时才需要：
+
+- **react-native-screens** —— 浮层组件（Popover、Dialog）所需
+- **@gorhom/bottom-sheet** —— BottomSheet 组件所需
+- **react-native-svg** —— 使用图标的组件所需（Accordion、Alert、Checkbox 等）
+
+### 设置
+
+```tsx
+import {
+  HeroUINativeProviderRaw,
+  type HeroUINativeConfigRaw,
+} from 'heroui-native/provider-raw';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+const config: HeroUINativeConfigRaw = {
+  textProps: {
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProviderRaw config={config}>
+        {/* 你的应用内容 */}
+      </HeroUINativeProviderRaw>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+### 手动添加 Toast 和 Portal
+
+如果你在使用 raw provider 时需要 toast 或 portal 功能，请自行添加：
+
+```tsx
+import { HeroUINativeProviderRaw } from 'heroui-native/provider-raw';
+import { PortalHost } from 'heroui-native/portal';
+import { ToastProvider } from 'heroui-native/toast';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProviderRaw>
+        <ToastProvider>
+          {/* 你的应用内容 */}
+          <PortalHost />
+        </ToastProvider>
+      </HeroUINativeProviderRaw>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+### Provider 层级
+
+```
+HeroUINativeProviderRaw
+├── SafeAreaListener（处理安全区域内边距更新）
+│   └── GlobalAnimationSettingsProvider（动画配置）
+│       └── TextComponentProvider（文本配置）
+│           └── TextInputComponentProvider（文本输入配置）
+│               └── 你的应用
+```
+
+## 最佳实践
+
+### 1. 单一 Provider 实例
+
+始终在应用根部使用单个 `HeroUINativeProvider`。不要嵌套多个 provider：
+
+```tsx
+// ❌ 不推荐
+<HeroUINativeProvider>
+  <SomeComponent>
+    <HeroUINativeProvider> {/* 不要这样做 */}
+      <AnotherComponent />
+    </HeroUINativeProvider>
+  </SomeComponent>
+</HeroUINativeProvider>
+
+// ✅ 推荐
+<HeroUINativeProvider>
+  <SomeComponent>
+    <AnotherComponent />
+  </SomeComponent>
+</HeroUINativeProvider>
+```
+
+### 2. 配置对象
+
+在组件外部定义你的配置，以避免每次渲染时重新创建：
+
+```tsx
+// ❌ 不推荐
+function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textProps: {
+          /* 内联配置 */
+        },
+      }}
+    >
+      {/* ... */}
+    </HeroUINativeProvider>
+  );
+}
+
+// ✅ 推荐
+const config: HeroUINativeConfig = {
+  textProps: {
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+function App() {
+  return (
+    <HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
+  );
+}
+```
+
+### 3. 文本配置
+
+配置文本 props 时请考虑无障碍：
+
+```tsx
+const config: HeroUINativeConfig = {
+  textProps: {
+    // 为无障碍允许字体缩放
+    allowFontScaling: true,
+    // 但限制最大缩放比例
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+```
+
+## TypeScript 支持
+
+该 provider 具有完整的类型定义。导入类型以获得更好的 IDE 支持：
+
+```tsx
+import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  // 完整的类型安全和自动补全
+  textProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  textInputProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  animation: 'disable-all', // 可选：禁用所有动画
+  devInfo: {
+    stylingPrinciples: true, // 可选：禁用样式原则提示信息
+  },
+  // Toast 配置选项：
+  // - false 或 'disabled'：禁用 toast provider
+  // - ToastProviderProps 对象：配置 toast 设置
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+  },
+};
+```
+
+## 相关
+
+- [快速开始](/docs/native/getting-started/quick-start) - 基础设置指南
+- [主题](/docs/native/getting-started/theming) - 自定义颜色和主题
+- [样式](/docs/native/getting-started/styling) - 使用 Tailwind 为组件设置样式
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/styling.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/styling.mdx
new file mode 100644
index 0000000..48e8282
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/styling.mdx
@@ -0,0 +1,371 @@
+---
+title: 样式
+description: 使用 Tailwind 或 StyleSheet API 为 HeroUI Native 组件编写样式
+icon: brush
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI Native 提供灵活的样式方案：Tailwind CSS 工具类、StyleSheet API，以及用于动态样式的 render props。
+
+## 样式原则
+
+HeroUI Native 以 `className` 作为主要样式入口，所有组件均可通过 `className` 使用 Tailwind 类。
+
+**StyleSheet 优先级：** 同时传入 `style`（StyleSheet）与 `className` 时，`style` 优先级更高，可在需要时覆盖 Tailwind。
+
+**动画样式：** 部分样式属性由 `react-native-reanimated` 驱动，与 StyleSheet 类似，其优先级也高于 `className`。要确认哪些属性受动画占用、无法仅靠 `className` 设置：
+
+- **在 IDE 中悬停 `className`** — TypeScript 定义会提示可用属性
+- **查阅组件文档** — 组件页顶部通常有样式源码链接，其中会标注动画相关限制
+
+**自定义动画样式：** 若某属性被动画占用，可在支持 `animation` 属性的组件上通过 `animation` 进行调整。
+
+## 基础样式
+
+**使用 className：** 所有 HeroUI Native 组件都支持 `className`：
+
+```tsx
+import { Button } from 'heroui-native';
+
+<Button className="bg-accent px-6 py-3 rounded-lg">
+  <Button.Label>Custom Button</Button.Label>
+</Button>;
+```
+
+**使用 style：** 也可通过 `style` 传入内联样式：
+
+```tsx
+import { Button } from 'heroui-native';
+
+<Button style={{ backgroundColor: '#8B5CF6', paddingHorizontal: 24 }}>
+  <Button.Label>Styled Button</Button.Label>
+</Button>;
+```
+
+## Render Props
+
+使用渲染函数读取组件状态并动态定制内容：
+
+```tsx
+import { RadioGroup, Label, cn } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">
+    {({ isSelected, isInvalid, isDisabled }) => (
+      <>
+        <Label
+          className={cn(
+            'text-foreground',
+            isSelected && 'text-accent font-semibold'
+          )}
+        >
+          Option 1
+        </Label>
+        <Radio
+          className={cn(
+            'border-2 rounded-full',
+            isSelected && 'border-accent bg-accent'
+          )}
+        >
+          {isSelected && <CustomIcon />}
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+## 封装可复用组件
+
+结合 [tailwind-variants](https://tailwind-variants.org/)（Tailwind 优先的变体 API）封装自定义组件：
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const customButtonVariants = tv({
+  base: 'font-semibold rounded-lg',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500',
+      secondary: 'bg-gray-200',
+      danger: 'bg-red-500',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+const customLabelVariants = tv({
+  base: '',
+  variants: {
+    intent: {
+      primary: 'text-white',
+      secondary: 'text-gray-800',
+      danger: 'text-white',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+
+interface CustomButtonProps
+  extends Omit<ButtonRootProps, 'className' | 'variant'>,
+    CustomButtonVariants {
+  className?: string;
+  labelClassName?: string;
+}
+
+export function CustomButton({
+  intent,
+  className,
+  labelClassName,
+  children,
+  ...props
+}: CustomButtonProps) {
+  return (
+    <Button
+      className={customButtonVariants({ intent, className })}
+      {...props}
+    >
+      <Button.Label
+        className={customLabelVariants({ intent, className: labelClassName })}
+      >
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+## 使用组件自带的 classNames
+
+每个 HeroUI Native 组件都会导出与内部一致的 `classNames` 工具对象，便于让自定义组件在视觉上与库内组件保持一致。
+
+例如，让自定义 `Link` 看起来像 `Button`：
+
+```tsx
+import { buttonClassNames, cn } from 'heroui-native';
+import { Pressable, Text } from 'react-native';
+
+interface LinkProps {
+  href: string;
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function Link({
+  href,
+  variant = 'primary',
+  size = 'md',
+  children,
+  className,
+}: LinkProps) {
+  return (
+    <Pressable
+      className={cn(
+        buttonClassNames.root({ variant, size }),
+        className
+      )}
+      onPress={() => {
+        // Handle navigation
+      }}
+    >
+      <Text className={buttonClassNames.label({ variant, size })}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}
+```
+
+**可用的 classNames 导出：**
+
+每个组件都会导出对应的 `classNames` 对象，例如：
+
+- `buttonClassNames` — 包含 `root` 与 `label` 函数
+- `cardClassNames` — 包含 `root`、`header`、`body`、`footer`、`label` 与 `description` 函数
+- `chipClassNames` — 包含 `root` 与 `label` 函数
+- 其他组件同理……
+
+**典型用法：**
+
+```tsx
+import { buttonClassNames } from 'heroui-native';
+
+// Use with variant and size options
+const rootClasses = buttonClassNames.root({
+  variant: 'primary',
+  size: 'md',
+  className: 'custom-class', // Optional: merge with your own classes
+});
+
+const labelClasses = buttonClassNames.label({
+  variant: 'primary',
+  size: 'md',
+});
+```
+
+`classNames` 函数的变体参数与对应组件一致，便于在自定义组件与 HeroUI 组件之间保持视觉一致。
+
+## 响应式设计
+
+HeroUI Native 通过 [Uniwind](https://docs.uniwind.dev/breakpoints) 支持 Tailwind 的响应式断点前缀，如 `sm:`、`md:`、`lg:`、`xl:`，按屏幕宽度条件应用样式。
+
+**移动优先：** 先写无前缀的小屏样式，再用断点为大屏增强。
+
+### 响应式排版与间距
+
+```tsx
+import { Button } from 'heroui-native';
+import { View, Text } from 'react-native';
+
+<View className="px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
+  <Text className="text-2xl sm:text-3xl lg:text-4xl font-bold mb-4 sm:mb-6">
+    Responsive Heading
+  </Text>
+  <Button className="px-3 sm:px-4 lg:px-6">
+    <Button.Label className="text-sm sm:text-base lg:text-lg">
+      Responsive Button
+    </Button.Label>
+  </Button>
+</View>;
+```
+
+### 响应式布局
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="flex-row flex-wrap">
+  {/* Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns */}
+  <View className="w-full sm:w-1/2 lg:w-1/3 p-2">
+    <View className="bg-accent p-4 rounded-lg">
+      <Text className="text-accent-foreground">Item 1</Text>
+    </View>
+  </View>
+</View>;
+```
+
+**默认断点：**
+
+- `sm`：640px
+- `md`：768px
+- `lg`：1024px
+- `xl`：1280px
+- `2xl`：1536px
+
+自定义断点与更多说明见 [Uniwind 断点文档](https://docs.uniwind.dev/breakpoints)。
+
+## 工具函数
+
+HeroUI Native 提供一些样式相关的工具。
+
+### cn
+
+`cn` 用于合并 Tailwind 类并处理冲突，适合条件类或与 props 传入的类合并：
+
+```tsx
+import { cn } from 'heroui-native';
+import { View } from 'react-native';
+
+function MyComponent({ className, isActive }) {
+  return (
+    <View
+      className={cn(
+        'bg-background p-4 rounded-lg',
+        'border border-separator',
+        isActive && 'bg-accent',
+        className
+      )}
+    />
+  );
+}
+```
+
+`cn` 基于 `tailwind-variants`，具备：
+
+- 自动合并 Tailwind 类（`twMerge: true`）
+- 自定义透明度分组等能力
+- 合理的冲突解决（靠后的类覆盖靠前的类）
+
+**冲突示例：**
+
+```tsx
+// 'bg-accent' overrides 'bg-background'
+cn('bg-background p-4', 'bg-accent');
+// Result: 'p-4 bg-accent'
+```
+
+### useThemeColor
+
+从 CSS 变量读取主题色，支持单色或一次读取多种颜色（后者更高效）。
+
+**单色：**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const accentColor = useThemeColor('accent');
+  const dangerColor = useThemeColor('danger');
+
+  return (
+    <View style={{ borderColor: accentColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```
+
+**多色（推荐在需要多个 token 时使用）：**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const [accentColor, backgroundColor, dangerColor] = useThemeColor([
+    'accent',
+    'background',
+    'danger',
+  ]);
+
+  return (
+    <View style={{ borderColor: accentColor, backgroundColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```
+
+**类型签名：**
+
+```tsx
+// Single color
+useThemeColor(themeColor: ThemeColor): string
+
+// Multiple colors (with type inference for tuples)
+useThemeColor<T extends readonly [ThemeColor, ...ThemeColor[]]>(
+  themeColor: T
+): CreateStringTuple<T['length']>
+
+// Multiple colors (array)
+useThemeColor(themeColor: ThemeColor[]): string[]
+```
+
+可用主题色包括：`background`、`foreground`、`surface`、`accent`、`default`、`success`、`warning`、`danger` 及其 hover、soft、foreground 等变体，以及 `muted`、`border`、`separator`、`field`、`overlay` 等语义色。
+
+## 下一步
+
+- [动画](/docs/native/getting-started/animation)
+- [主题](/docs/native/getting-started/theming)
+- [颜色](/docs/native/getting-started/colors)
diff --git a/apps/docs/content/docs/cn/native/getting-started/(handbook)/theming.mdx b/apps/docs/content/docs/cn/native/getting-started/(handbook)/theming.mdx
new file mode 100644
index 0000000..a0e4263
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(handbook)/theming.mdx
@@ -0,0 +1,499 @@
+---
+title: 主题
+description: 使用 CSS 变量与全局样式定制 HeroUI Native 设计系统
+icon: palette
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI Native 使用 CSS 变量实现主题化，可用标准 CSS 覆盖从颜色到组件样式的一切。
+
+## 工作原理
+
+主题系统建立在 [Tailwind CSS v4](https://tailwindcss.com/docs/theme) 的主题能力之上，并通过 [Uniwind](https://uniwind.dev/) 接入 React Native。导入 `heroui-native/styles` 后，会使用 Tailwind 内置色板并映射到语义变量，自动在明暗主题间切换，并借助 CSS 层与 `@theme` 进行组织。
+
+**命名约定：**
+
+- 无后缀的颜色一般用作背景（如 `--accent`）
+- 带 `-foreground` 后缀的用于该背景上的文字（如 `--accent-foreground`）
+
+## 快速开始
+
+**在组件中应用颜色：**
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-background flex-1">
+  <Text className="text-foreground">Your app content</Text>
+</View>;
+```
+
+**切换主题：**
+
+通过 [Uniwind](https://docs.uniwind.dev/theming/basics)，HeroUI Native 自动支持深色模式；可跟随系统，也可手动切换明暗变体：
+
+```tsx
+import { Uniwind, useUniwind } from 'uniwind';
+import { Button } from 'heroui-native';
+
+function ThemeToggle() {
+  const { theme } = useUniwind();
+
+  return (
+    <Button
+      onPress={() => Uniwind.setTheme(theme === 'light' ? 'dark' : 'light')}
+    >
+      <Button.Label>
+        Toggle {theme === 'light' ? 'Dark' : 'Light'} Mode
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+**覆盖颜色：**
+
+```css
+/* global.css */
+@layer theme {
+  @variant light {
+    /* Override any color variable */
+    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
+    --success: oklch(0.65 0.15 155);
+  }
+
+  @variant dark {
+    --accent: oklch(0.65 0.25 270);
+    --success: oklch(0.75 0.12 155);
+  }
+}
+```
+
+> **说明：** 完整色板与可视化参考见 [颜色](/docs/native/getting-started/colors)。
+
+**创建自定义主题：**
+
+可借助 Uniwind 的变体系统定义多套主题。完整自定义主题文档见 [Uniwind 自定义主题指南](https://docs.uniwind.dev/theming/custom-themes)。
+
+<Callout type="warning">
+  **重要：** 所有主题必须定义**相同**的变量集合。必填变量清单见 [默认主题](/docs/native/getting-started/colors#default-theme)。
+</Callout>
+
+```css
+/* global.css */
+@layer theme {
+  :root {
+    @variant ocean-light {
+      /* Base Colors */
+      --background: oklch(0.95 0.02 230);
+      --foreground: oklch(0.25 0.04 230);
+
+     /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.98 0.01 230);
+      --surface-foreground: oklch(0.3 0.045 230);
+
+      --surface-secondary: oklch(0.96 0.012 230);
+      --surface-secondary-foreground: oklch(0.3 0.045 230);
+
+      --surface-tertiary: oklch(0.94 0.015 230);
+      --surface-tertiary-foreground: oklch(0.3 0.045 230);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
+      --overlay: oklch(0.998 0.003 230);
+      --overlay-foreground: oklch(0.3 0.045 230);
+      --backdrop: oklch(0% 0 0 / 20%);
+
+      --muted: oklch(0.55 0.035 230);
+
+      --default: oklch(0.94 0.018 230);
+      --default-foreground: oklch(0.4 0.05 230);
+
+      /* Accent */
+      --accent: oklch(0.6 0.2 230);
+      --accent-foreground: oklch(0.98 0.005 230);
+
+      /* Form Field Defaults - Colors */
+      --field-background: oklch(0.98 0.01 230);
+      --field-foreground: oklch(0.25 0.04 230);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status Colors */
+      --success: oklch(0.72 0.14 165);
+      --success-foreground: oklch(0.25 0.08 165);
+
+      --warning: oklch(0.78 0.12 85);
+      --warning-foreground: oklch(0.3 0.08 85);
+
+      --danger: oklch(0.68 0.18 15);
+      --danger-foreground: oklch(0.98 0.005 15);
+
+      /* Component Colors */
+      --segment: oklch(0.98 0.01 230);
+      --segment-foreground: oklch(0.25 0.04 230);
+
+      /* Misc Colors */
+      --border: oklch(0 0 0 / 0%);
+      --separator: oklch(0.91 0.015 230);
+      --focus: var(--accent);
+      --link: oklch(0.62 0.17 230);
+
+      /* Shadows */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      --overlay-shadow:
+        0 2px 8px 0 rgba(0, 0, 0, 0.02), 0 -6px 12px 0 rgba(0, 0, 0, 0.01),
+        0 14px 28px 0 rgba(0, 0, 0, 0.03);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+    }
+
+    @variant ocean-dark {
+      /* Base Colors */
+      --background: oklch(0.15 0.04 230);
+      --foreground: oklch(0.94 0.01 230);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.2 0.048 230);
+      --surface-foreground: oklch(0.9 0.015 230);
+
+      --surface-secondary: oklch(0.24 0.046 230);
+      --surface-secondary-foreground: oklch(0.9 0.015 230);
+
+      --surface-tertiary: oklch(0.27 0.044 230);
+      --surface-tertiary-foreground: oklch(0.9 0.015 230);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
+      --overlay: oklch(0.23 0.045 230);
+      --overlay-foreground: oklch(0.9 0.015 230);
+      --backdrop: oklch(0% 0 0 / 20%);
+
+      --muted: oklch(0.5 0.04 230);
+
+      --default: oklch(0.25 0.05 230);
+      --default-foreground: oklch(0.88 0.018 230);
+
+      /* Accent */
+      --accent: oklch(0.72 0.21 230);
+      --accent-foreground: oklch(0.15 0.04 230);
+
+      /* Form Field Defaults - Colors */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status Colors */
+      --success: oklch(0.68 0.16 165);
+      --success-foreground: oklch(0.95 0.008 165);
+
+      --warning: oklch(0.75 0.14 90);
+      --warning-foreground: oklch(0.2 0.04 90);
+
+      --danger: oklch(0.65 0.2 20);
+      --danger-foreground: oklch(0.95 0.008 20);
+
+      /* Component Colors */
+      --segment: oklch(0.22 0.046 230);
+      --segment-foreground: oklch(0.9 0.015 230);
+
+      /* Misc Colors */
+      --border: oklch(0 0 0 / 0%);
+      --separator: oklch(0.28 0.045 230);
+      --focus: var(--accent);
+      --link: oklch(0.75 0.18 230);
+
+      /* Shadows */
+      --surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+      --overlay-shadow: 0 0 1px 0 rgba(255, 255, 255, 0.3) inset;
+      --field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+    }
+  }
+}
+```
+
+**重要：** 添加自定义主题后，必须在 Metro 配置中注册：
+
+```js
+// metro.config.js
+const { withUniwindConfig } = require('uniwind/metro');
+const {
+  wrapWithReanimatedMetroConfig,
+} = require('react-native-reanimated/metro-config');
+
+const config = {
+  // ... your existing config
+};
+
+module.exports = withUniwindConfig(wrapWithReanimatedMetroConfig(config), {
+  cssEntryFile: './global.css',
+  dtsFile: './src/uniwind.d.ts',
+  extraThemes: ['ocean-light', 'ocean-dark'],
+});
+```
+
+在应用中切换主题：
+
+```tsx
+import { Uniwind } from 'uniwind';
+import { Button } from 'heroui-native';
+
+function App() {
+  return (
+    <Button onPress={() => Uniwind.setTheme('ocean-light')}>
+      <Button.Label>Ocean Theme</Button.Label>
+    </Button>
+  );
+}
+```
+
+## 添加自定义颜色
+
+在主题中加入自定义语义色：
+
+```css
+@layer theme {
+  @variant light {
+    --info: oklch(0.6 0.15 210);
+    --info-foreground: oklch(0.98 0 0);
+  }
+
+  @variant dark {
+    --info: oklch(0.7 0.12 210);
+    --info-foreground: oklch(0.15 0 0);
+  }
+}
+
+/* 让颜色可被 Tailwind 使用 */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+在组件中使用：
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-info p-4 rounded-lg">
+  <Text className="text-info-foreground">Info message</Text>
+</View>;
+```
+
+## 自定义字体
+
+要在应用中使用自定义字体，需要先加载字体，再覆盖字体相关的 CSS 变量。
+
+### 1. 在应用中加载字体
+
+先加载字体（例如使用 Expo 的 `useFonts`）：
+
+```tsx
+import { useFonts } from 'expo-font';
+import { HeroUINativeProvider } from 'heroui-native';
+import {
+  YourFont_400Regular,
+  YourFont_500Medium,
+  YourFont_600SemiBold,
+} from '@expo-google-fonts/your-font';
+
+export default function App() {
+  const [fontsLoaded] = useFonts({
+    YourFont_400Regular,
+    YourFont_500Medium,
+    YourFont_600SemiBold,
+  });
+
+  if (!fontsLoaded) {
+    return null; // Or return a loading screen
+  }
+
+  return <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>;
+}
+```
+
+### 2. 配置字体 CSS 变量
+
+加载完成后，在 `global.css` 中覆盖字体变量：
+
+```css
+@theme {
+  --font-normal: 'YourFont-400Regular';
+  --font-medium: 'YourFont-500Medium';
+  --font-semibold: 'YourFont-600SemiBold';
+}
+```
+
+**说明：** CSS 变量中的字体名应与已加载字体的 PostScript 名称一致。请查阅字体包文档，或直接使用 `useFonts` 中出现的名称。
+
+所有 HeroUI Native 组件会自动使用这些字体变量，以保持排版一致。
+
+## 变量参考
+
+HeroUI 定义三类变量：
+
+1. **基础变量** — 如 `--white`、`--black` 等不随主题切换的值
+2. **主题变量** — 随明暗主题切换的颜色
+3. **计算变量** — 自动生成的按压态（hover）与尺寸变体等
+
+完整参考：[颜色文档](/docs/native/getting-started/colors)、[默认主题变量](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/variables.css)、[共享主题工具](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/theme.css)
+
+**计算变量（Tailwind）：**
+
+我们通过 Tailwind 的 `@theme` 指令自动生成按压态与圆角等计算变量，定义见 [theme.css](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/theme.css)：
+<CollapsibleCode lang="css" code={`  @theme inline static {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+
+  --color-surface: var(--surface);
+  --color-surface-foreground: var(--surface-foreground);
+  --color-surface-hover: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+
+  --color-surface-secondary: var(--surface-secondary);
+  --color-surface-secondary-foreground: var(--surface-secondary-foreground);
+
+  --color-surface-tertiary: var(--surface-tertiary);
+  --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
+
+  --color-overlay: var(--overlay);
+  --color-overlay-foreground: var(--overlay-foreground);
+  --color-backdrop: var(--backdrop);
+  
+
+  --color-muted: var(--muted);
+
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-segment: var(--segment);
+  --color-segment-foreground: var(--segment-foreground);
+
+  --color-border: var(--border);
+  --color-separator: var(--separator);
+  --color-focus: var(--focus);
+  --color-link: var(--link);
+
+  --color-default: var(--default);
+  --color-default-foreground: var(--default-foreground);
+
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+
+  /* Form Field Tokens */
+  --color-field: var(--field-background, var(--default));
+  --color-field-foreground: var(--field-foreground, var(--foreground));
+  --color-field-placeholder: var(--field-placeholder, var(--muted));
+  --color-field-border: var(--field-border, var(--border));
+  --radius-field: var(--field-radius, var(--radius-xl));
+  --border-width-field-width: var(--field-border-width, var(--border-width));
+
+  --shadow-surface: var(--surface-shadow);
+  --shadow-overlay: var(--overlay-shadow);
+  --shadow-field: var(--field-shadow);
+
+  /* Calculated Variables */
+
+  /* Colors */
+
+  /* --- background shades --- */
+  --color-background-secondary: color-mix(in oklab, var(--background) 96%, var(--foreground) 4%);
+  --color-background-tertiary: color-mix(in oklab, var(--background) 92%, var(--foreground) 8%);
+  --color-background-inverse: var(--foreground);
+
+  /* ------------------------- */
+  --color-default-hover: color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%);
+  --color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+  --color-success-hover: color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%);
+  --color-warning-hover: color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%);
+  --color-danger-hover: color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%);
+
+  /* Form Field Colors */ 
+  --color-field-hover: color-mix(in oklab, var(--field-background, var(--default)) 90%, var(--field-foreground, var(--foreground)) 2%);
+  --color-field-focus: var(--field-background, var(--default));
+  --color-field-border-hover: color-mix(in oklab, var(--field-border, var(--border)) 88%, var(--field-foreground, var(--foreground)) 10%);
+  --color-field-border-focus: color-mix(in oklab, var(--field-border, var(--border)) 74%, var(--field-foreground, var(--foreground)) 22%);
+
+  /* Soft Colors */
+  --color-accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
+  --color-accent-soft-foreground: var(--accent);
+  --color-accent-soft-hover: color-mix(in oklab, var(--accent) 20%, transparent);
+
+  --color-danger-soft: color-mix(in oklab, var(--danger) 15%, transparent);
+  --color-danger-soft-foreground: var(--danger);
+  --color-danger-soft-hover: color-mix(in oklab, var(--danger) 20%, transparent);
+
+  --color-warning-soft: color-mix(in oklab, var(--warning) 15%, transparent);
+  --color-warning-soft-foreground: var(--warning);
+  --color-warning-soft-hover: color-mix(in oklab, var(--warning) 20%, transparent);
+
+  --color-success-soft: color-mix(in oklab, var(--success) 15%, transparent);
+  --color-success-soft-foreground: var(--success);
+  --color-success-soft-hover: color-mix(in oklab, var(--success) 20%, transparent);
+
+  /* Separator Colors - Levels */
+  --color-separator-secondary: color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%);
+  --color-separator-tertiary: color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%);
+
+  /* Border Colors - Levels (progressive contrast: default → secondary → tertiary) */
+  /* Light mode: lighter → darker | Dark mode: darker → lighter */
+  --color-border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+  --color-border-tertiary: color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%);
+
+  /* Radius and default sizes - defaults can change by just changing the --radius */
+  --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
+  --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
+  --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
+  --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
+  --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
+  --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
+  --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
+  --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
+}
+`}
+/>
+
+> **表单字段边框工具类：** 使用 `border-field-width` 设置字段边框宽度，使用 `border-field-border` 设置字段边框颜色。当两者都需要时，将它们搭配使用（`border-field-width border-field-border`）。`border-field` class 仍然只是一个来自 `--color-field` 的边框颜色工具类；请勿用它来设置宽度。如果你之前使用 `border-field` 来设置宽度，请迁移到 `border-field-width`。通过 `--field-border-width` 原语（primitive）自定义宽度。
+
+表单控件依赖 `--field-*` 变量及其计算出的 hover/focus 变体。在主题中调整它们即可重塑输入框、复选框、单选与 OTP 等，而不会影响按钮、卡片等 Surface 组件的观感。
+
+## 鲜亮配色
+
+默认情况下，HeroUI Native 使用可读性更好的柔和前景色，即将语义色与前景色按比例混合，以在 soft 背景上获得更佳对比度。如果你偏好饱和度更高、更鲜亮的柔和前景色，可以在引入基础样式之后，额外导入可选的 `heroui-native/styles/vibrant` 样式：
+
+```css
+/* global.css */
+@import "heroui-native/styles";
+@import "heroui-native/styles/vibrant"; /* [!code highlight] */
+```
+
+这会将所有 `*-soft-foreground` 变量（accent、success、warning、danger）切换为「语义色 92% + 前景色 8%」的混合配方——更贴近原始色调，但仍带有轻微的对比度增强。[Alert](/docs/native/components/alert)、[Avatar](/docs/native/components/avatar)、[Button](/docs/native/components/button)、[Chip](/docs/native/components/chip)、[Toast](/docs/native/components/toast) 等组件会自动在其 soft 变体上使用新的柔和前景色——无需修改任何组件属性。
+
+| 模式 | 可读性优先（默认） | 鲜亮 |
+|------|----------------------|---------|
+| Soft 前景 | `color-mix(color 70-80%, foreground 30-40%)` | `color-mix(color 92%, foreground 8%)` |
+
+<Callout type="warning">
+  鲜亮配色优先考虑视觉饱和度而非对比度。对某些颜色组合（尤其是更浅的强调色），它可能不满足 WCAG 无障碍准则。
+</Callout>
+
+<Callout type="info">
+  可选的鲜亮配色自 [v1.0.4](/docs/native/releases/v1-0-4) 起提供。
+</Callout>
+
+## 相关资源
+
+- [颜色](/docs/native/getting-started/colors)
+- [样式指南](/docs/native/getting-started/styling)
+- [Tailwind CSS v4 主题](https://tailwindcss.com/docs/theme)
+- [OKLCH 调色工具](https://oklch.com)
diff --git a/apps/docs/content/docs/cn/native/getting-started/(overview)/design-principles.mdx b/apps/docs/content/docs/cn/native/getting-started/(overview)/design-principles.mdx
new file mode 100644
index 0000000..9243ea6
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(overview)/design-principles.mdx
@@ -0,0 +1,262 @@
+---
+title: 设计原则
+description: 指导 HeroUI Native 设计与开发的核心理念
+icon: book
+---
+
+HeroUI Native 遵循 9 条核心原则，强调清晰、无障碍、可定制与开发者体验。
+
+## 核心原则
+
+### 1. 语义意图优先于视觉样式
+
+使用语义化命名（primary、secondary、tertiary）而非纯视觉描述（solid、flat、bordered）。受 [Uber Base 设计系统](https://base.uber.com/6d2425e9f/p/756216-button) 启发，变体形成清晰层级：
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis-dark.jpg"
+  alt="Semantic Intent Hierarchy"
+/>
+
+
+```tsx
+// ✅ 语义变体传达层级
+<Button variant="primary">Save</Button>
+<Button variant="secondary">Edit</Button>
+<Button variant="tertiary">Cancel</Button>
+```
+
+| 变体 | 用途 | 使用建议 |
+|------|------|-----------|
+| **Primary** | 推进流程的主操作 | 同一上下文通常 1 个 |
+| **Secondary** | 备选操作 | 可多个 |
+| **Tertiary** | 取消、跳过等弱操作 | 谨慎使用 |
+| **Danger** | 破坏性操作 | 按需使用 |
+
+### 2. 无障碍作为基础
+
+遵循移动端无障碍最佳实践，内置合理的触控可达性、焦点管理与读屏支持。所有组件提供适当的无障碍标签与语义结构，以支持 VoiceOver（iOS）与 TalkBack（Android）。
+
+```tsx
+import { Tabs } from 'heroui-native';
+
+<Tabs value="profile" onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="profile">
+      <Tabs.Label>Profile</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="security">
+      <Tabs.Label>Security</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="profile">Content</Tabs.Content>
+  <Tabs.Content value="security">Content</Tabs.Content>
+</Tabs>
+```
+
+### 3. 组合优于配置
+
+复合组件可按需重排、定制或省略子部件，通过点记法精确拼装。
+
+```tsx
+// 组合子部件得到所需结构
+import { Accordion } from 'heroui-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      Question Text
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>Answer content</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 4. 渐进式披露
+
+从简单开始，仅在需要时增加复杂度。组件在最少配置下即可工作，并随需求增长而扩展。
+
+```tsx
+import { Button, Spinner } from 'heroui-native';
+import { Feather } from '@expo/vector-icons';
+
+// Level 1: Minimal
+<Button>Click me</Button>
+
+// Level 2: Enhanced
+<Button variant="primary" size="lg">
+  <Feather name="check" size={20} />
+  <Button.Label>Submit</Button.Label>
+</Button>
+
+// Level 3: Advanced
+<Button variant="primary" isDisabled={isLoading}>
+  {isLoading ? (
+    <>
+      <Spinner size="sm" />
+      <Button.Label>Loading...</Button.Label>
+    </>
+  ) : (
+    <Button.Label>Submit</Button.Label>
+  )}
+</Button>
+```
+
+### 5. 可预测的行为
+
+跨组件保持一致：`sm` / `md` / `lg` 尺寸、变体体系与 `className` 支持。API 一致，行为一致。
+
+```tsx
+import { Button, Chip, Avatar } from 'heroui-native';
+
+// All components follow the same patterns
+<Button size="lg" variant="primary" className="custom">
+  <Button.Label>Click me</Button.Label>
+</Button>
+<Chip size="lg" color="success" className="custom">
+  <Chip.Label>Success</Chip.Label>
+</Chip>
+<Avatar size="lg" className="custom">
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 6. 类型安全优先
+
+完整的 TypeScript 支持：智能提示、自动补全与编译期检查。可为自定义组件扩展类型。
+
+```tsx
+import type { ButtonRootProps } from 'heroui-native';
+
+// Type-safe props and event handlers
+<Button
+  variant="primary"  // Autocomplete: primary | secondary | tertiary | ghost | danger | danger-soft
+  size="md"          // Type checked: sm | md | lg
+  onPress={() => {   // Properly typed press handler
+    console.log('Button pressed');
+  }}
+>
+  <Button.Label>Click me</Button.Label>
+</Button>
+
+// Extend types for custom components
+interface CustomButtonProps extends Omit<ButtonRootProps, 'variant'> {
+  intent: 'save' | 'cancel' | 'delete';
+}
+```
+
+### 7. 卓越的开发者体验
+
+清晰的 API、可读的错误信息、智能提示，以及对 AI 友好的 Markdown 文档。
+
+### 8. 完整可定制
+
+默认即美观；也可通过 CSS 变量与 [Uniwind 主题系统](https://docs.uniwind.dev/theming/basics) 整体换肤。每个插槽都可定制。
+
+```css
+/* Custom colors using Uniwind's theme layer */
+@layer theme {
+  @variant light {
+    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
+    --background: oklch(0.98 0 0);  /* Custom background */
+  }
+
+  @variant dark {
+    --accent: oklch(0.65 0.25 270);
+    --background: oklch(0.15 0 0);
+  }
+}
+
+/* Radius customization */
+@theme {
+  --radius: 0.75rem; /* Increase for rounder components */
+}
+```
+
+### 9. 开放与可扩展
+
+可包装、扩展与定制组件以匹配产品需求；也可用 `className` 应用自定义样式。
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+
+// Custom wrapper component
+interface CTAButtonProps extends Omit<ButtonRootProps, 'variant'> {
+  intent?: 'primary-cta' | 'secondary-cta' | 'minimal';
+}
+
+const CTAButton = ({
+  intent = 'primary-cta',
+  children,
+  ...props
+}: CTAButtonProps) => {
+  const variantMap = {
+    'primary-cta': 'primary',
+    'secondary-cta': 'secondary',
+    'minimal': 'ghost'
+  } as const;
+
+  return (
+    <Button variant={variantMap[intent]} {...props}>
+      <Button.Label>{children}</Button.Label>
+    </Button>
+  );
+};
+
+// Usage
+<CTAButton intent="primary-cta">Get Started</CTAButton>
+<CTAButton intent="secondary-cta">Learn More</CTAButton>
+```
+
+**结合 tailwind-variants 扩展：**
+
+```tsx
+import { Button } from 'heroui-native';
+import { tv } from 'tailwind-variants';
+
+// Extend button styles with custom variants
+const myButtonVariants = tv({
+  base: 'px-4 py-2 rounded-lg',
+  variants: {
+    variant: {
+      'primary-cta': 'bg-accent px-8 py-4 shadow-lg',
+      'secondary-cta': 'border-2 border-accent px-6 py-3',
+    }
+  },
+  defaultVariants: {
+    variant: 'primary-cta',
+  }
+});
+
+// Label variants for text colors (must be applied to Button.Label)
+const myLabelVariants = tv({
+  base: '',
+  variants: {
+    variant: {
+      'primary-cta': 'text-accent-foreground',
+      'secondary-cta': 'text-accent',
+    }
+  },
+  defaultVariants: {
+    variant: 'primary-cta',
+  }
+});
+
+// Use the custom variants
+function CustomButton({ variant, className, labelClassName, children, ...props }) {
+  return (
+    <Button className={myButtonVariants({ variant, className })} {...props}>
+      <Button.Label className={myLabelVariants({ variant, className: labelClassName })}>
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+
+// Usage
+<CustomButton variant="primary-cta">Get Started</CustomButton>
+<CustomButton variant="secondary-cta">Learn More</CustomButton>
+```
diff --git a/apps/docs/content/docs/cn/native/getting-started/(overview)/quick-start.mdx b/apps/docs/content/docs/cn/native/getting-started/(overview)/quick-start.mdx
new file mode 100644
index 0000000..da81c7b
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(overview)/quick-start.mdx
@@ -0,0 +1,243 @@
+---
+title: 快速开始
+description: 几分钟内上手 HeroUI Native
+icon: rocket
+---
+
+请根据项目情况选择适合的方案：
+
+- **方案 1** —— 通过我们的 CLI 一键创建预先配置好的新项目，无需手动设置。
+- **方案 2** —— 将 HeroUI Native 添加到已有的 React Native 或 Expo 项目。
+
+## 方案 1：创建新项目
+
+最快捷的启动方式。CLI 会生成一个 Expo 项目，内置 HeroUI Native、所有必需的 peer 依赖、Uniwind / Tailwind CSS、全局样式以及已配置好的 `HeroUINativeProvider`，让你可以直接进入开发。
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npx create-heroui-native-app@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm create heroui-native-app@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn create heroui-native-app
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun create heroui-native-app@latest
+    ```
+  </Tab>
+</Tabs>
+
+按照交互提示完成配置，然后启动开发服务器：
+
+```bash
+cd my-app
+npm run start
+```
+
+到此即可开始开发。可直接跳到[使用第一个组件](#use-your-first-component)，或[浏览组件](/docs/native/components)。
+
+<Callout type="info">
+  生成的项目自带 Expo + TypeScript、预配置的 Uniwind + Tailwind CSS、含必要导入的 `global.css`，并已在应用入口包裹 `GestureHandlerRootView` 与 `HeroUINativeProvider`。
+</Callout>
+
+## 方案 2：添加到已有项目
+
+如果你已经有一个 React Native 或 Expo 应用，请按以下步骤手动安装与配置 HeroUI Native。
+
+<CopyPrompt
+  prompt={`Set up HeroUI Native in this React Native project.
+
+Use the HeroUI Native MCP server (@heroui/native-mcp) as the single source of truth for installation steps, peer dependencies, and component APIs. Start by retrieving the latest quick-start / installation guide from the MCP and follow it precisely — do not rely on memory for versions, package names, or setup steps.
+
+Before making any changes:
+
+1. Analyze the project. Detect the package manager (npm / pnpm / yarn / bun), framework (Expo or bare React Native), TypeScript usage, and the location of node_modules. This matters for global.css — the @source path must be written relative to global.css itself and must resolve to node_modules/heroui-native/lib.
+2. Read package.json and only install what is missing. Pin to the exact versions listed in the MCP quick-start to avoid compatibility issues.
+3. Inspect the app entry (App.tsx, app/_layout.tsx, index.tsx, etc.) and check whether GestureHandlerRootView already wraps the app. If it does, reuse it — do not nest a second GestureHandlerRootView.
+
+Then apply the setup:
+
+- Install heroui-native plus any missing mandatory+optional peer dependencies.
+- Set up Uniwind + Tailwind CSS (follow the Uniwind quickstart) and add the HeroUI Native imports plus the correct @source line to global.css.
+- Make sure GestureHandlerRootView wraps the entire app — it must be the outermost wrapper with style { flex: 1 }.
+- Add HeroUINativeProvider as a direct child of GestureHandlerRootView, wrapping the rest of the app.
+
+When done, summarize the changes you made and tell me how to run the app on iOS / Android.`}
+>
+  **更喜欢让 AI 助手代劳？** 在编辑器中安装 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)，将上方提示词粘贴给你的 AI 助手 —— 它会分析你的项目并完成整套配置。
+</CopyPrompt>
+
+### 1. 安装 HeroUI Native
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install heroui-native
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native
+    ```
+  </Tab>
+</Tabs>
+
+### 2. 安装必需的 peer 依赖
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="warning">
+  建议使用上文列出的确切版本，以避免兼容性问题。版本不一致可能导致难以预期的缺陷。
+</Callout>
+
+### 3. 可选依赖
+
+仅在用到对应组件或能力时需要安装：
+
+| Package | Version | 用途 |
+| --- | --- | --- |
+| `react-native-screens` | `^4.16.0` | BottomSheet、Dialog、Menu、Popover、Select、Toast |
+| `@gorhom/bottom-sheet` | `^5.2.9` | BottomSheet；Menu / Popover / Select 使用 `presentation="bottom-sheet"` 时 |
+
+### 4. 配置 Uniwind
+
+请按 [Uniwind 安装指南](https://docs.uniwind.dev/quickstart) 为 React Native 接入 Tailwind CSS。
+
+若从 NativeWind 迁移，参见 [迁移指南](https://docs.uniwind.dev/migration-from-nativewind)。
+
+### 5. 配置 global.css
+
+在 `global.css` 中加入以下导入：
+
+```css
+@import 'tailwindcss';
+@import 'uniwind';
+
+@import 'heroui-native/styles';
+
+/* Path to the heroui-native lib inside node_modules relative to global.css */
+/* Examples:
+ *   - If global.css is at project root: ./node_modules/heroui-native/lib
+ *   - If global.css is in app/: ../node_modules/heroui-native/lib
+ *   - If global.css is in src/styles/: ../../node_modules/heroui-native/lib
+ */
+@source './node_modules/heroui-native/lib';
+```
+
+### 6. 使用 Provider 包裹应用
+
+使用 `HeroUINativeProvider` 包裹应用，并务必外层再包一层 `GestureHandlerRootView`：
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+> **说明：** 关于文本属性、动画、Toast 等高级配置，请参阅 [Provider 文档](/docs/native/getting-started/provider)。
+
+## 使用第一个组件
+
+```tsx
+import { Button } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function MyComponent() {
+  return (
+    <View className="flex-1 justify-center items-center bg-background">
+      <Button onPress={() => console.log('Pressed!')}>Get Started</Button>
+    </View>
+  );
+}
+```
+
+## 通过细粒度导出减小包体
+
+若希望减小包体、仅引入用到的组件，可使用细粒度导出：
+
+```tsx
+// Granular imports - use when you need only a few components
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+
+// General import - imports the whole library, use when you're using many components
+import { Button, Card } from "heroui-native";
+```
+
+细粒度导入适合只用少量组件的场景，有助于控制包体。从 `heroui-native` 整体导入会包含完整库，适合在应用中广泛使用多组件时采用。
+
+**可用的细粒度入口：**
+
+- `heroui-native/provider` — Provider
+- `heroui-native/provider-raw` — 轻量 Provider（最小依赖起点）
+- `heroui-native/[component-name]` — 单个组件
+- `heroui-native/portal` — Portal 工具
+- `heroui-native/toast` — Toast Provider 与工具
+- `heroui-native/utils` — 工具函数
+- `heroui-native/hooks` — 自定义 Hooks
+
+<Callout type="warning">
+  **重要：** 为控制包体，请**始终**坚持使用细粒度导入策略。只要存在一处从 `heroui-native` 的整体导入，就可能使上述优化失效。
+</Callout>
+
+> **提示：** 若需要更强控制，可使用 [`HeroUINativeProviderRaw`](/docs/native/getting-started/provider#raw-provider) — 轻量 Provider，不包含 `ToastProvider` 与 `PortalHost`。
+
+## 接下来
+
+- [HeroUI Native Provider](/docs/native/getting-started/provider)
+- [样式指南](/docs/native/getting-started/styling)
+- [主题文档](/docs/native/getting-started/theming)
+
+## 在 Web（Expo）上运行
+
+<Callout type="warning">
+  HeroUI Native **目前不建议用于 Web**。我们优先聚焦 iOS 与 Android。Web 开发请使用 [HeroUI React](/docs/react/getting-started/quick-start)。
+</Callout>
diff --git a/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agent-skills.mdx b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..bb8b7fd
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agent-skills.mdx
@@ -0,0 +1,70 @@
+---
+title: Agent Skills
+description: 让 AI 助手使用 HeroUI Native 组件构建移动端界面
+---
+
+HeroUI Native Skills 为 AI 助手提供组件、模式与 React Native 最佳实践等系统化知识。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-native.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-native-dark.jpg"
+  alt="HeroUI Native Agent Skills"
+/>
+
+### 安装
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-native
+```
+
+或使用 skills 包：
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+支持 Claude Code、Cursor、OpenCode 等。
+</span>
+
+### 用法
+
+Skills 会被 AI **自动发现**，也可通过 `/heroui-native` 显式调用。
+
+你可以让助手：
+
+- 使用 HeroUI Native 搭建移动组件
+- 用 HeroUI Native 创建页面
+- 定制主题与样式
+- 查阅组件文档
+
+<Callout>
+  更复杂的场景可配合 [MCP 服务器](/docs/native/getting-started/mcp-server)，以实时访问组件文档与源码。
+</Callout>
+
+### 包含内容
+
+- HeroUI Native 安装指南
+- 全部组件的 props、示例与用法模式
+- 基于 Uniwind 的主题与样式指南
+- 设计原则与组合模式
+
+### 目录结构
+
+```
+skills/heroui-native/
+├── SKILL.md              # 主说明
+├── LICENSE.txt           # Apache License 2.0
+└── scripts/              # 工具脚本
+    ├── list_components.mjs
+    ├── get_component_docs.mjs
+    ├── get_theme.mjs
+    └── get_docs.mjs
+```
+
+### 相关文档
+
+- [Agent Skills 规范](https://agentskills.io/home)
+- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [Cursor Skills](https://cursor.com/docs/context/skills)
+- [OpenCode Skills](https://opencode.ai/docs/skills)
diff --git a/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agents-md.mdx b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..18f84d4
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/agents-md.mdx
@@ -0,0 +1,51 @@
+---
+title: AGENTS.md
+description: 将 HeroUI Native 文档下载到项目中，供 AI 编程助手引用
+icon: preview
+---
+
+可将 HeroUI Native 文档直接下载到项目内，供 AI 助手本地引用。
+
+<Callout>
+  **说明：** `agents-md` 命令专用于 **HeroUI React v3** 与 **HeroUI Native**。其他 CLI 命令（如 `add`、`init`、`upgrade` 等）目前仍面向 HeroUI v2。
+</Callout>
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-native.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-native-dark.jpg"
+  alt="HeroUI Native AGENTS.md"
+/>
+
+### 用法
+
+```bash
+npx heroui-cli@latest agents-md --native
+```
+
+指定输出文件：
+
+```bash
+npx heroui-cli@latest agents-md --native --output AGENTS.md
+```
+
+### 作用
+
+- 将最新 HeroUI Native 文档下载到 `.heroui-docs/native/`
+- 在 `AGENTS.md` 或 `CLAUDE.md` 中生成索引
+- 自动将 `.heroui-docs/` 加入 `.gitignore`
+
+### 选项
+
+- `--native` — 仅下载 Native 文档
+- `--output <files...>` — 输出文件（如 `AGENTS.md` 或 `AGENTS.md CLAUDE.md`）
+- `--ssh` — 使用 SSH 进行 git clone
+
+### 要求
+
+- Tailwind CSS >= v4（通过 Uniwind）
+
+### 相关文档
+
+- [AGENTS.md](https://agents.md/) — AGENTS.md 格式说明
+- [CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) — Claude 侧的等价物
+- [AGENTS.md vs Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) — 评测相关讨论
diff --git a/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/llms-txt.mdx b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/llms-txt.mdx
new file mode 100644
index 0000000..b980916
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/llms-txt.mdx
@@ -0,0 +1,73 @@
+---
+title: LLMs.txt
+description: 让 Claude、Cursor、Windsurf 等 AI 助手理解 HeroUI Native 文档
+---
+
+我们提供 [LLMs.txt](https://llmstxt.org/) 文件，便于 AI 编程助手读取 HeroUI Native 文档。
+
+## 可用文件
+
+**核心文档：**
+
+- [/native/llms.txt](/native/llms.txt) — Native 文档快速索引
+- [/native/llms-full.txt](/native/llms-full.txt) — HeroUI Native 完整文档
+
+**上下文窗口较小时：**
+
+- [/native/llms-components.txt](/native/llms-components.txt) — 仅组件文档
+- [/native/llms-patterns.txt](/native/llms-patterns.txt) — 常见模式与配方
+
+**全平台：**
+
+- [/llms.txt](/llms.txt) — 快速索引（React + Native）
+- [/llms-full.txt](/llms-full.txt) — 完整文档（React + Native）
+- [/llms-components.txt](/llms-components.txt) — 全部组件文档
+- [/llms-patterns.txt](/llms-patterns.txt) — 全部模式与配方
+
+## 接入方式
+
+**Claude Code：** 让 Claude 引用文档，例如：
+
+```
+Use HeroUI Native documentation from https://heroui.com/native/llms.txt
+```
+
+或在项目的 `.claude` 中配置以自动加载。
+
+**Cursor：** 使用 `@Docs`：
+
+```
+@Docs https://heroui.com/native/llms-full.txt
+```
+
+[了解更多](https://docs.cursor.com/context/@-symbols/@-docs)
+
+**Windsurf：** 写入 `.windsurfrules`：
+
+```
+#docs https://heroui.com/native/llms-full.txt
+```
+
+[了解更多](https://docs.codeium.com/windsurf/memories#memories-and-rules)
+
+**其他 AI 工具：** 多数助手支持通过 URL 引用文档，直接提供：
+
+```
+https://heroui.com/native/llms.txt
+```
+
+**仅组件文档：**
+
+```
+https://heroui.com/native/llms-components.txt
+```
+
+**模式与最佳实践：**
+
+```
+https://heroui.com/native/llms-patterns.txt
+```
+
+## 参与改进
+
+若 AI 生成代码有问题，欢迎在 [GitHub](https://github.com/heroui-inc/heroui) 上协助改进 LLMs.txt 文件。
diff --git a/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/mcp-server.mdx b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..7629e10
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/(ui-for-agents)/mcp-server.mdx
@@ -0,0 +1,206 @@
+---
+title: MCP 服务器
+description: 在 AI 助手中直接访问 HeroUI Native 文档
+---
+
+HeroUI MCP 服务器让 AI 助手直接读取 HeroUI Native 组件文档，便于在 AI 驱动的开发流程中使用 HeroUI。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-light-new.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-dark-new.jpg"
+  alt="HeroUI Native MCP 服务器"
+/>
+
+
+当前 MCP 服务器支持 **heroui-native** 与 [stdio 传输](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)。npm 包名为 `@heroui/native-mcp`。源码见 [GitHub](https://github.com/heroui-inc/heroui-mcp)。
+
+<Callout>
+  随着 HeroUI Native 组件增加，MCP 中的可用内容也会同步扩展。
+</Callout>
+
+## 快速配置
+
+**Cursor：**
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/native-mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span>在 Cursor 中安装</span>
+  </a>
+</div>
+
+或手动添加到 **Cursor 设置** → **Tools** → **MCP Servers**：
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+也可将以下内容加入 `~/.cursor/mcp.json`。详见 [Cursor 文档](https://cursor.com/docs/context/mcp)。
+
+**Claude Code：** 在终端执行：
+
+```bash
+claude mcp add heroui-native -- npx -y @heroui/native-mcp@latest
+```
+
+或手动写入项目的 `.mcp.json`：
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+添加配置后重启 Claude Code，运行 `/mcp` 查看列表；若显示 **Connected** 即可使用。
+
+更多说明见 [Claude Code MCP 文档](https://docs.claude.com/en/docs/claude-code/mcp)。
+
+**Windsurf：** 在项目 `.windsurf/mcp.json` 中加入：
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+保存后重启 Windsurf 以生效。
+
+详见 [Windsurf MCP 文档](https://docs.windsurf.com/windsurf/cascade/mcp)。
+
+**Zed：** 在 `settings.json` 中配置（命令面板 `zed: open settings` 或 `Cmd-,` / `Ctrl-,`）：
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+```
+
+重启 Zed 后，在 Agent 面板设置中确认 heroui-native 旁指示点为绿色，提示为「Server is active」。
+
+详见 [Zed MCP 文档](https://zed.dev/docs/ai/mcp)。
+
+**VS Code：** 若配合 GitHub Copilot 使用 MCP，在项目 `.vscode/mcp.json` 中添加：
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-native": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+打开 `.vscode/mcp.json`，在 heroui-native 旁点击 **Start**。
+
+详见 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)。
+
+**Codex：** 写入 `~/.codex/config.toml` 或项目内 `.codex/config.toml`：
+
+```toml title="config.toml"
+[mcp_servers.heroui-native]
+command = "npx"
+args = ["-y", "@heroui/native-mcp@latest"]
+```
+
+重启 Codex，在 TUI 中运行 `/mcp` 校验服务器已激活。
+
+详见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。
+
+**OpenCode：** 在项目 `opencode.json` 中添加：
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-native": {
+      "type": "local",
+      "command": ["npx", "-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+重启 OpenCode 后生效。
+
+详见 [OpenCode MCP 文档](https://open-code.ai/docs/en/mcp-servers)。
+
+## 用法
+
+配置完成后，可向 AI 提问，例如：
+
+- "Help me install HeroUI Native in my Expo app"
+- "Show me all HeroUI Native components"
+- "What props does the Button component have?"
+- "Give me an example of using the Card component"
+- "What are the theme variables for dark mode?"
+
+### 自动升级
+
+MCP 也可协助将 HeroUI Native 升级到最新版本，例如：
+
+```bash
+"Hey Cursor, update HeroUI Native to the latest version"
+```
+
+助手通常会：
+
+- 对比当前版本与最新发布
+- 阅读变更日志中的破坏性变更
+- 在项目中应用必要的代码更新
+
+适用于升级到最新稳定版或预发布版本。
+
+## 可用工具
+
+MCP 向 AI 暴露以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `list_components` | 列出全部 HeroUI Native 组件 |
+| `get_component_docs` | 获取一个或多个组件的完整文档（结构、props、示例与用法模式） |
+| `get_theme_variables` | 读取颜色、排版、间距等主题变量，支持明暗模式 |
+| `get_docs` | 浏览 HeroUI Native 全部文档（指南与原则等）；安装说明可使用路径 `/docs/native/getting-started/quick-start` |
+
+
+## 故障排除
+
+**环境要求：** Node.js 22 及以上。使用 `npx` 时会自动下载包。
+
+**需要帮助？** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord 社区](https://discord.gg/heroui)
+
+## 链接
+
+- [npm 包](https://www.npmjs.com/package/@heroui/native-mcp)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-mcp)
+- [贡献指南](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)
diff --git a/apps/docs/content/docs/cn/native/getting-started/index.mdx b/apps/docs/content/docs/cn/native/getting-started/index.mdx
new file mode 100644
index 0000000..f645af5
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/index.mdx
@@ -0,0 +1,76 @@
+---
+title: 介绍
+description: 开源 React Native UI 组件库，用于构建美观且易于访问的移动界面。
+icon: book-open
+image: https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp
+---
+
+HeroUI Native 是基于 [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) 与 [Uniwind](https://uniwind.dev/) 的 React Native 组件库，并面向现代移动端技术栈。每个组件都带有流畅动画、精致细节与内置无障碍支持——开箱即用，亦可深度定制。
+
+<NativeImageHeroView target="home" />
+
+## 为什么选择 HeroUI Native？
+
+**默认即美观** — 专业观感开箱即有，无需额外堆样式。
+
+**无障碍优先** — 遵循移动端无障碍最佳实践，内置合理的焦点管理、触控可达性与读屏支持。
+
+**高度可组合** — 每个组件由可替换的子部件构成；按需改动，其余保持不变。
+
+**开发者友好** — 类型完备的 API、可预期的模式与出色的自动补全。
+
+**持续维护** — 由团队负责更新、修复与新特性；你只需升级依赖。
+
+**轻量按需** — 支持 Tree-shaking，仅打包实际使用的部分。
+
+**面向未来** — 兼容最新 [Expo](https://expo.dev/)，并通过 [Uniwind](https://uniwind.dev/) 建立在 [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) 之上，同时便于 AI 辅助开发。
+
+## 一个精心打造的组件库，而非复制粘贴
+
+复制粘贴的代码在依赖停滞时会变成维护负担。
+
+HeroUI Native 则不同，它是与你共同演进的组件库：
+
+- 自动更新和修复
+- 无需额外工作即可获得新功能
+- 组件与 React Native、Tailwind 与移动平台保持同步
+- 深度定制，而非浅层主题调整
+- 面向代码生成的 AI 友好 API
+
+## HeroUI 生态
+
+- **🌐 HeroUI v3（Web）** — 基于 Tailwind CSS v4 的 React 组件
+- **📱 HeroUI Native（移动端）** — 面向 React Native 的美观组件
+- **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)**（自然语言生成应用）— 用对话创建应用
+- **🧠 面向 LLM 的 UI** — 全新平台与 MCP 即将推出
+
+## 常见问题
+
+**HeroUI Native 是否免费？**  
+是的，基于 Apache License 2.0 完全免费且开源。
+
+**是否可用于生产？**  
+可以。HeroUI v3 已经稳定，可放心用于生产环境。
+
+**能否自定义组件？**  
+可以。可更新默认样式与动画，或重新组合子部件；每个插槽都可定制。
+
+**是否支持 TypeScript？**  
+完整类型定义，IDE 体验与自动补全良好。
+
+**无障碍方面如何？**  
+遵循移动端无障碍最佳实践，内置焦点管理、触控可达性与读屏支持。
+
+**是否有 Figma 资源？**  
+有！欢迎访问我们的设计系统：[HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429)。
+
+## 参与其中
+
+加入社区、分享反馈或参与贡献：
+
+- [GitHub Discussions](https://github.com/heroui-inc/heroui-native/discussions)
+- [Discord](https://discord.gg/9b6yyZKmH4)
+- [X/Twitter](https://x.com/hero_ui)
+- [贡献指南](https://github.com/heroui-inc/heroui-native/blob/main/CONTRIBUTING.md)
+
+HeroUI Native 采用 [Apache License 2.0](https://github.com/heroui-inc/heroui-native/blob/main/LICENSE) 发布。
diff --git a/apps/docs/content/docs/cn/native/getting-started/meta.json b/apps/docs/content/docs/cn/native/getting-started/meta.json
new file mode 100644
index 0000000..d97cc03
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/getting-started/meta.json
@@ -0,0 +1,26 @@
+{
+  "title": "快速开始",
+  "description": "快速开始使用 HeroUI Native",
+  "root": true,
+  "icon": "book-open",
+  "pages": [
+    "---概述---",
+    "index",
+    "(overview)/quick-start",
+    "(overview)/design-principles",
+    "[route][路线图](https://herouinative.featurebase.app/roadmap)",
+    "---手册---",
+    "(handbook)/provider",
+    "(handbook)/portal",
+    "(handbook)/colors",
+    "(handbook)/theming",
+    "(handbook)/styling",
+    "(handbook)/animation",
+    "(handbook)/composition",
+    "---代理用户界面---",
+    "(ui-for-agents)/llms-txt",
+    "(ui-for-agents)/mcp-server",
+    "(ui-for-agents)/agent-skills",
+    "(ui-for-agents)/agents-md"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/native/meta.json b/apps/docs/content/docs/cn/native/meta.json
new file mode 100644
index 0000000..22c11b2
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "文档",
+  "description": "HeroUI Native 文档",
+  "pages": ["getting-started", "components", "releases"]
+}
diff --git a/apps/docs/content/docs/cn/native/releases/beta-10.mdx b/apps/docs/content/docs/cn/native/releases/beta-10.mdx
new file mode 100644
index 0000000..2a0d0d4
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/beta-10.mdx
@@ -0,0 +1,188 @@
+---
+title: Beta 10
+description: Bottom Sheet 组件、PressableFeedback 重构、动画 API 的 State 扩展、use-theme-color 多色选取与问题修复
+github:
+  pull: 6068
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 12 月 30 日</span>
+</div>
+
+本版本新增 [Bottom Sheet](/docs/native/components/bottom-sheet) 组件；重构 [PressableFeedback](/docs/native/components/pressable-feedback) 并改进 API；为动画 API 增加 State Prop 支持；增强 `use-theme-color` 以支持一次选取多色；并包含若干问题修复与文档改进。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 更新亮点
+
+### 新组件
+
+#### Bottom Sheet
+
+本版本新增 **Bottom Sheet** 组件：自屏幕底部滑入的通用遮罩层，带动画过渡与下滑关闭手势。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="bottom-sheet"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 平滑动画过渡与手势支持
+- 多档吸附高度，布局更灵活
+- Detached 模式，支持自定义定位
+- 可自定义遮罩与模糊效果
+- 完整无障碍支持
+- 基于 [@gorhom/bottom-sheet](https://gorhom.dev/react-native-bottom-sheet)
+
+**用法：**
+
+```tsx
+import { BottomSheet, Button } from 'heroui-native';
+
+<BottomSheet>
+  <BottomSheet.Trigger asChild>
+    <Button>Open Bottom Sheet</Button>
+  </BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>Title</BottomSheet.Title>
+      <BottomSheet.Description>Description</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+完整文档与示例见 [Bottom Sheet 组件页](/docs/native/components/bottom-sheet)。
+
+**相关 PR：** [#174](https://github.com/heroui-inc/heroui-native/pull/174)
+
+## 组件改进
+
+### PressableFeedback 重构
+
+[PressableFeedback](/docs/native/components/pressable-feedback) 已重构，API 更清晰，动画控制更好。
+
+**改进：**
+
+- 动画配置 API 增强
+- 更好支持自定义动画状态
+- 性能与流畅度提升
+- 反馈定位选项更灵活
+
+在提供更多按压反馈动画控制能力的同时，保持向后兼容。
+
+**相关 PR：** [#182](https://github.com/heroui-inc/heroui-native/pull/182)
+
+## API 增强
+
+### 动画 API：State 属性扩展
+
+动画 API 新增 `state` 属性，可在自定义属性的同时关闭动画，实现更细粒度的行为控制。
+
+**新能力：**
+
+```tsx
+<Component
+  animation={{
+    state: 'disabled', // 或 'disable-all' 或 boolean
+    // ... 其他动画属性
+  }}
+/>
+```
+
+`state` 可取：
+
+- `'disabled'`：关闭动画，仍允许自定义属性
+- `'disable-all'`：关闭所有动画（含子级）
+- `boolean`：简单开关
+
+便于在不启用动画的情况下微调动画相关属性，利于精细调整组件行为。
+
+**相关 PR：** [#176](https://github.com/heroui-inc/heroui-native/pull/176)
+
+### use-theme-color 多色选取
+
+`use-theme-color` 已重构，支持一次选取多种颜色，主题定制更灵活。
+
+**增强：**
+
+- 支持同时选取多种颜色
+- 颜色选取逻辑改进
+- 多色场景下性能更好
+
+便于在需要多色协同应用的主题场景中组合使用。
+
+**相关 PR：** [#170](https://github.com/heroui-inc/heroui-native/pull/170)
+
+## 文档
+
+### 动画样式指南注释
+
+为动画样式指南补充注释与说明，便于开发者理解与正确使用动画能力。
+
+**改进：**
+
+- 示例代码附详细注释
+- 动画模式说明更清晰
+- 不同动画方案的选用指引更明确
+
+**相关 PR：** [#179](https://github.com/heroui-inc/heroui-native/pull/179)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #173](https://github.com/heroui-inc/heroui-native/issues/173)**：修复 `classNames={{ container: "bg-x" }}` 无法为 TextField.Input 容器设置 `backgroundColor` 的问题。
+- **[Issue #177](https://github.com/heroui-inc/heroui-native/issues/177)**：修复按钮缩放动画有时停留在 0.9 倍、松手后无法回弹的问题。
+- **[Issue #178](https://github.com/heroui-inc/heroui-native/issues/178)**：修复影响组件功能的问题。
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [动画指南](/docs/native/getting-started/animation) — 补充动画 API State 属性说明
+- [颜色指南](/docs/native/getting-started/colors) — 补充 use-theme-color 多色选取说明
+- [PressableFeedback 组件](/docs/native/components/pressable-feedback) — 更新重构后的 API 文档
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/beta-11.mdx b/apps/docs/content/docs/cn/native/releases/beta-11.mdx
new file mode 100644
index 0000000..e9c1bc9
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/beta-11.mdx
@@ -0,0 +1,184 @@
+---
+title: Beta 11
+description: Bottom Sheet 关闭协同增强、Dialog 侧滑关闭修复、TextField 改进，以及面向高级场景的 PortalHost 导出
+github:
+  pull: 203
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 1 月 6 日</span>
+</div>
+
+Beta 11 聚焦多块核心能力的可靠性与开发者体验：增强 Bottom Sheet 在各关闭路径下的一致性；修复 Dialog 侧滑关闭手势；解决 TextField 样式与行为问题；并新增 `PortalHost` 导出以支持高级 Portal 挂载。交互更顺滑，对组件行为的控制也更充分。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 Beta 11 的改进！你可以查看增强后的 Bottom Sheet、Dialog、TextField 与 PortalHost 相关能力。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 组件改进
+
+### Bottom Sheet 关闭协同增强
+
+[Bottom Sheet](/docs/native/components/bottom-sheet) 已增强各类关闭路径之间的协同。
+
+**改进：**
+
+- 下滑关闭、点击遮罩、关闭按钮与程序化关闭之间的同步更好
+- 关闭过程中的状态管理改进，减少竞态
+- 各关闭场景下 `onOpenChange` 触发更可靠
+- 动画进度与关闭态切换的衔接更顺畅
+
+Bottom Sheet 支持下滑、点遮罩、点关闭按钮或代码关闭。此前这些路径偶发冲突或表现不一致；本更新使各路径协调一致，体验更可预期。
+
+**相关 PR：** [#201](https://github.com/heroui-inc/heroui-native/pull/201)
+
+### Dialog 侧滑关闭手势修复
+
+[Dialog](/docs/native/components/dialog) 已修复侧滑关闭手势的处理。
+
+**改进：**
+
+- 侧滑关闭的手势检测与处理修复
+- 滑动过程中手势状态管理改进
+- 松手时与动画的衔接增强
+- 超过阈值后侧滑关闭更可靠
+
+Dialog 支持下滑关闭。本修复解决滑动过程中手势偶发无响应或行为异常的问题。
+
+**相关 PR：** [#193](https://github.com/heroui-inc/heroui-native/pull/193)
+
+### TextField 样式与行为修复
+
+[TextField](/docs/native/components/text-field) 的样式与行为问题已修复。
+
+**改进：**
+
+- 输入框样式不一致问题修复
+- 动画状态管理问题修复
+- 聚焦/失焦处理改进
+- 错误态视觉反馈增强
+- 占位符与选中颜色应用修复
+
+确保 TextField 在聚焦、失焦、非法等状态下显示正确，并向用户提供一致的视觉反馈。
+
+**相关 PR：** [#202](https://github.com/heroui-inc/heroui-native/pull/202)
+
+## API 增强
+
+### PortalHost 导出（高级场景）
+
+`PortalHost` 现从主 Provider 模块导出，支持高级 Portal 宿主挂载。
+
+**新能力：**
+
+```tsx
+import { HeroUINativeProvider, PortalHost } from "heroui-native";
+
+export function CustomLayout() {
+  return (
+    <>
+      <HeroUINativeProvider>
+        {/* 应用内容 */}
+      </HeroUINativeProvider>
+
+      {/* 在自定义位置手动挂载 PortalHost */}
+      <PortalHost name="custom-host" />
+    </>
+  );
+}
+```
+
+便于在自定义布局中手动挂载 Portal 宿主，例如需在 BottomSheet、Modal 或其他遮罩内指定渲染位置时。默认 `HeroUINativeProvider` 已包含标准场景的 `PortalHost`；现可额外创建具名宿主以支持多宿主架构。
+
+**适用场景：**
+
+- 在 Bottom Sheet 内挂载 Portal
+- 在 Modal 中创建 Portal 宿主
+- 自定义遮罩渲染
+- 多宿主 Portal 架构
+
+**相关 PR：** [#185](https://github.com/heroui-inc/heroui-native/pull/185)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #187](https://github.com/heroui-inc/heroui-native/issues/187)**：修复通过滑动手势关闭后，需多次点击才能再次打开 Bottom Sheet 或 Dialog 的问题。内部状态现与关闭动画正确同步，无论以何种方式关闭均可立即再次打开。
+
+- **[Issue #189](https://github.com/heroui-inc/heroui-native/issues/189)**：修复含文本输入的 Dialog 在侧滑关闭时应用卡死的问题。
+
+- **[Issue #196](https://github.com/heroui-inc/heroui-native/issues/196)**：修复 TextField 多行输入行为，与 React Native `TextInput` 多行语义一致。
+
+- **[Issue #199](https://github.com/heroui-inc/heroui-native/issues/199)**：修复 TextField Input 内占位符文字位置问题。
+
+**相关 PR：**
+
+- [#201](https://github.com/heroui-inc/heroui-native/pull/201)
+- [#202](https://github.com/heroui-inc/heroui-native/pull/202)
+- [#193](https://github.com/heroui-inc/heroui-native/pull/193)
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/beta-12.mdx b/apps/docs/content/docs/cn/native/releases/beta-12.mdx
new file mode 100644
index 0000000..4ddc3d0
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/beta-12.mdx
@@ -0,0 +1,366 @@
+---
+title: Beta 12
+description: InputOTP、Label、Description 组件，Popover 关闭修复，受控状态改进，圆角修复，以及变体样式属性支持
+github:
+  pull: 214
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 1 月 13 日</span>
+</div>
+
+Beta 12 新增三个核心表单组件——InputOTP、Label、Description——强化 React Native 中的表单搭建能力。另含 Popover 关闭行为、弹层受控状态、圆角配置等关键修复，并为多个表单组件增加变体样式属性支持，使表单组件更稳健、样式与行为更易控。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 Beta 12！你可以探索 InputOTP、Label、Description，以及 Popover 修复、受控状态改进、圆角修复与变体样式属性支持。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### 新组件
+
+本版本新增 **3** 个核心表单组件：
+
+- **[InputOTP](/docs/native/components/input-otp)**：一次性密码输入，独立字符格、动画与校验支持。
+- **[Label](/docs/native/components/label)**：表单与界面元素标签文本，支持必填标记与校验态。
+- **[Description](/docs/native/components/description)**：无障碍说明与辅助文案，用于表单等场景。
+
+#### InputOTP
+
+InputOTP 为双因素认证、验证码、PIN 等场景提供完整方案：独立字符格与流畅动画、可自定义分组与分隔符、全面校验支持。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input-otp"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 独立字符格、流畅动画与光标指示
+- 灵活分组与分隔符
+- 基于模式的输入限制（数字、字符或自定义正则）
+- 受控/非受控值管理
+- 校验态与视觉反馈
+- 每位占位符可配置
+- 粘贴支持与转换函数
+- 完整无障碍支持
+
+**用法：**
+
+```tsx
+import { InputOTP, Label, Description } from "heroui-native";
+
+export function Example() {
+  return (
+    <>
+      <Label>Verify account</Label>
+      <InputOTP maxLength={6} onComplete={(code) => console.log(code)}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>We've sent a code to your email</Description>
+    </>
+  );
+}
+```
+
+完整文档与示例见 [InputOTP 组件页](/docs/native/components/input-otp)。
+
+**相关 PR：** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+#### Label
+
+Label 为表单字段提供无障碍标签，内置必填星号、校验态与禁用态，并随字段校验状态自适应样式。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="label"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 必填字段自动显示星号
+- 非法态样式
+- 禁用态支持
+- 复合结构便于自定义布局
+- 通过 nativeID 关联的完整无障碍支持
+- 支持 `className`、`classNames`、`styles` 定制样式
+
+**用法：**
+
+```tsx
+import { Label, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label isRequired>Password</Label>
+      <TextField.Input placeholder="Create a password" secureTextEntry />
+    </TextField>
+  );
+}
+```
+
+完整文档与示例见 [Label 组件页](/docs/native/components/label)。
+
+**相关 PR：** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+#### Description
+
+Description 为表单字段提供无障碍辅助说明，默认弱化样式，并可通过 nativeID 与字段关联以支持读屏。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="description"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 适合辅助文案的弱化文本样式
+- 通过 nativeID 与 `aria-describedby` 关联无障碍
+- 与表单组件无缝集成
+- 支持自定义样式
+
+**用法：**
+
+```tsx
+import { Description, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <TextField.Label>Email address</TextField.Label>
+      <TextField.Input
+        placeholder="Enter your email"
+        keyboardType="email-address"
+        aria-describedby="email-desc"
+      />
+      <Description nativeID="email-desc">
+        We'll never share your email with anyone else.
+      </Description>
+    </TextField>
+  );
+}
+```
+
+完整文档与示例见 [Description 组件页](/docs/native/components/description)。
+
+**相关 PR：** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+## 组件改进
+
+### Popover 通过 ref 关闭修复
+
+[Popover](/docs/native/components/popover) 已修复通过 ref 程序化关闭时的行为。
+
+**改进：**
+
+- 基于 ref 的关闭方法现能正确触发关闭动画
+- ref 调用与组件内部状态的同步改进
+- 程序化关闭更可靠
+
+确保调用 `popoverRef.current?.close()` 时能可靠关闭并正确管理状态与动画。
+
+**相关 PR：** [#207](https://github.com/heroui-inc/heroui-native/pull/207)
+
+### 弹层受控状态修复
+
+Dialog、Bottom Sheet、Popover 等弹层组件已修复通过 `isOpen` 的受控状态。
+
+**改进：**
+
+- 受控状态同步修复
+- 外部状态变更的处理改进
+- 受控模式下行为更可预期
+
+**相关 PR：** [#215](https://github.com/heroui-inc/heroui-native/pull/215)
+
+### Button、Chip、Tabs 圆角修复
+
+[Button](/docs/native/components/button)、[Chip](/docs/native/components/chip)、[Tabs](/docs/native/components/tabs) 已修复对全局圆角配置的尊重。
+
+**改进：**
+
+- Button 全局圆角应用修复
+- Chip 圆角应用修复
+- Tabs 圆角应用修复
+- 使用全局主题配置的组件间一致性提升
+
+**相关 PR：** [#218](https://github.com/heroui-inc/heroui-native/pull/218)
+
+### TextField.Input 属性精简
+
+[TextField](/docs/native/components/text-field) 的 Input 子组件已移除 `animation` 与 `isAnimatedStyleActive`。
+
+**变更：**
+
+- 自 TextField.Input 移除 `animation`
+- 自 TextField.Input 移除 `isAnimatedStyleActive`
+- API 简化，更易维护
+
+动画行为现由组件内部统一处理，无需手动配置动画属性。
+
+**相关 PR：** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
+
+## API 增强
+
+### HeroUINativeProvider 的 devInfo 配置
+
+`HeroUINativeProvider` 现支持 `devInfo` 配置项，便于开发与调试。
+
+**新能力：**
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native";
+
+export function App() {
+  return (
+    <HeroUINativeProvider
+      devInfo={{
+        // 开发期配置项
+      }}
+    >
+      {/* 应用内容 */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+**相关 PR：** [#217](https://github.com/heroui-inc/heroui-native/pull/217)
+
+### 变体样式属性支持
+
+[Checkbox](/docs/native/components/checkbox)、[Radio](/docs/native/components/radio)、[TextField](/docs/native/components/text-field)、[InputOTP](/docs/native/components/input-otp) 现支持通过 `variant` 样式属性更便捷地覆盖变体样式。
+
+**新能力：**
+
+```tsx
+import { Checkbox, Radio, TextField, InputOTP } from "heroui-native";
+
+<Checkbox variant="bordered" style={{ variant: "flat" }}>
+  Option 1
+</Checkbox>
+
+<Radio variant="solid" style={{ variant: "bordered" }}>
+  Option 2
+</Radio>
+
+<TextField variant="underlined" style={{ variant: "bordered" }}>
+  <TextField.Input />
+</TextField>
+```
+
+除组件 `variant` 属性外，也可通过 style 中的变体信息灵活调整外观。
+
+**相关 PR：** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
+
+## 样式修复
+
+### 圆角配置
+
+修复全局圆角未正确应用到部分组件的问题。
+
+**修复：**
+
+- Button 未尊重全局圆角
+- Chip 圆角应用
+- Tabs 圆角应用
+
+### 样式优化
+
+- **圆角一致性**：Button、Chip、Tabs 的圆角应用更一致
+- **主题配置**：主题传播增强，组件更一致地尊重全局设置
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #93](https://github.com/heroui-inc/heroui-native/issues/93)**：修复在 Unwind 场景下 Button 未应用全局圆角的问题，现与主题全局圆角一致。
+
+- **[Issue #213](https://github.com/heroui-inc/heroui-native/issues/213)**：修复 Select 受控模式（`isOpen`）不生效的问题；提供 `isOpen` 时可在外部可靠管理开闭。
+
+**相关 PR：**
+
+- [#218](https://github.com/heroui-inc/heroui-native/pull/218)
+- [#215](https://github.com/heroui-inc/heroui-native/pull/215)
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/beta-13.mdx b/apps/docs/content/docs/cn/native/releases/beta-13.mdx
new file mode 100644
index 0000000..b65cc9b
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/beta-13.mdx
@@ -0,0 +1,663 @@
+---
+title: Beta 13
+description: TextArea 组件、Button outline 变体、Tabs 改进、表单原语拆分、弹层动画重构、样式类名导出与关键问题修复
+github:
+  pull: 254
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 3 日</span>
+</div>
+
+Beta 13 引入多行输入组件 TextArea、Button outline 变体，并为所有组件导出样式类名。本版本显著改进 Tabs（动画与变体命名更清晰）、将表单相关能力拆为独立原语、重构弹层动画系统以提升一致性与 Android 兼容性，并修复中文输入、主题色计算、Uniwind Pro 兼容、Bottom Sheet 打开与摇树（tree-shaking）等关键问题，整体提升开发者体验与组件可靠性。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 Beta 13！你可以探索 TextArea、CloseButton、Button outline、Tabs 改进、细粒度导出与各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### 新组件
+
+本版本新增 **3** 个重要组件：
+
+- **[TextArea](/docs/native/components/text-area)**：多行文本输入，带样式边框与背景，适用于较长内容。
+- **[Input](/docs/native/components/input)**：单行文本输入，带样式边框与背景；现作为独立于 TextField 的组件提供（此前仅 `TextField.Input`）。
+- **[CloseButton](/docs/native/components/close-button)**：可复用关闭按钮，用于 Dialog、Modal 等遮罩场景，样式在各遮罩间一致。
+
+#### TextArea
+
+TextArea 面向评论、消息、描述与较长表单字段等多行场景；可与 TextField 组合成完整表单结构，支持校验态与多种视觉变体。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="text-area"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 多行输入，行数可配置
+- 与 TextField 无缝组合
+- 校验态与视觉反馈
+- primary / secondary 等变体
+- 禁用与只读
+- `className` 与 `styles` 定制
+- 完整无障碍支持
+
+**用法：**
+
+```tsx
+import { Description, Label, TextArea, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label>Message</Label>
+      <TextArea placeholder="Enter your message here..." />
+      <Description>Please provide as much detail as possible.</Description>
+    </TextField>
+  );
+}
+```
+
+完整文档与示例见 [TextArea 组件页](/docs/native/components/text-area)。
+
+**相关 PR：** [#254](https://github.com/heroui-inc/heroui-native/pull/254)
+
+#### Input
+
+Input 现可作为独立组件使用，提供带边框与背景的单行输入。此前仅能通过 `TextField.Input` 使用；现可单独使用，或与 TextField、ControlField 等组合。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 单行输入，带样式边框与背景
+- 独立使用或与表单组件组合
+- 校验态与视觉反馈
+- primary / secondary 变体
+- 禁用与只读
+- `className` 与 `styles`
+- 完整无障碍支持
+
+**用法：**
+
+```tsx
+import { Description, Input, Label, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label>Email</Label>
+      <Input placeholder="Enter your email..." />
+      <Description>We'll never share your email.</Description>
+    </TextField>
+  );
+}
+```
+
+完整文档与示例见 [Input 组件页](/docs/native/components/input)。
+
+**相关 PR：** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+#### CloseButton
+
+CloseButton 为关闭 Dialog、Modal、Popover 等遮罩提供统一实现：跨遮罩一致样式、可配置图标属性，并与 Dialog、Popover、Select、Bottom Sheet 等集成。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="close-button"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 各遮罩间关闭按钮样式一致
+- 图标尺寸与颜色可配置
+- 支持自定义子节点替换默认图标
+- 禁用态
+- 与 Dialog、Popover、Select、Bottom Sheet 集成
+- 默认样式针对遮罩场景优化
+
+**用法：**
+
+```tsx
+import { CloseButton } from "heroui-native";
+
+// 独立使用
+<CloseButton onPress={handleClose} />
+
+// 作为 Dialog、Popover、Select、Bottom Sheet 的一部分
+<Dialog>
+  <Dialog.Close />
+</Dialog>
+```
+
+完整文档与示例见 [CloseButton 组件页](/docs/native/components/close-button)。
+
+**相关 PR：** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
+
+### 新子组件
+
+#### Tabs.Separator
+
+Tabs 新增 `Separator` 子组件，在触发器之间提供随当前选项卡变化的显隐动画，便于做视觉分隔。
+
+**特性：**
+
+- 随活动选项卡变化的显隐过渡
+- `betweenValues` 控制显示区间
+- 动画时长与不透明度可配置
+- 可设为始终可见的静态分隔
+
+**用法：**
+
+```tsx
+import { Tabs } from "heroui-native";
+
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger value="general">
+        <Tabs.Label>General</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={["general", "notifications"]} />
+      <Tabs.Trigger value="notifications">
+        <Tabs.Label>Notifications</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+</Tabs>
+```
+
+**相关 PR：** [#228](https://github.com/heroui-inc/heroui-native/pull/228)
+
+## 组件改进
+
+### Button outline 变体
+
+[Button](/docs/native/components/button) 新增 `outline` 变体：透明背景 + 边框，丰富按钮视觉层次。
+
+**改进：**
+
+- 新增 `outline` 有边框样式
+- 与其他 Button 变体风格一致
+- outline 的悬停与聚焦态正确
+- 与既有 Button API 无缝衔接
+
+**用法：**
+
+```tsx
+import { Button } from "heroui-native";
+
+<Button variant="outline">Outline Button</Button>
+```
+
+**相关 PR：** [#235](https://github.com/heroui-inc/heroui-native/pull/235)
+
+### Tabs 指示条动画重构
+
+[Tabs](/docs/native/components/tabs) 指示条动画由宽高动画改为 `translateX` 变换，过渡更顺滑、性能更好。
+
+**改进：**
+
+- 指示条迁移到 `translateX`
+- 动画性能与流畅度提升
+- 切换时视觉更一致
+- 减少动画期间的布局重算
+
+**相关 PR：** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
+
+### Popover 箭头尺寸与视觉衔接
+
+[Popover](/docs/native/components/popover) 改进箭头尺寸及与内容的视觉衔接。
+
+**改进：**
+
+- 箭头尺寸相对内容更合理
+- 箭头与弹层连接更自然
+- 对齐与间距优化
+
+**相关 PR：** [#243](https://github.com/heroui-inc/heroui-native/pull/243)
+
+### 表单组件拆分为原语
+
+表单相关能力拆为独立原语，组合更灵活、职责更清晰。
+
+**改进：**
+
+- 表单能力原子化
+- 复用性与组合性提升
+- 关注点分离更好
+- 自定义表单布局更自由
+
+**相关 PR：** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+### Input Android 阴影修复
+
+[Input](/docs/native/components/input) 为 Android 增加平台相关阴影，跨端视觉更一致。
+
+**改进：**
+
+- Android 平台阴影
+- iOS / Android 观感对齐
+- Android 上层次（elevation）观感改善
+
+**相关 PR：** [#248](https://github.com/heroui-inc/heroui-native/pull/248)
+
+### 弹层动画系统重构
+
+Popover、Select、Dialog、BottomSheet 的动画系统已重构：统一进出场逻辑、遮罩组合与内容动画，标准化各弹层行为并修复 Android 指针事件问题。
+
+**改进：**
+
+- Dialog 等呈现统一使用 FadeInDown / FadeOutDown 等进出场
+- 遮罩动画钩子同时支持基于 progress 与进出场两类动画
+- 遮罩组合更多使用 Dialog.Overlay、Popover.Overlay，减少单纯 Pressable 包裹
+- 修复影响弹层交互的 Android pointer events 问题
+- 示例中显式写出 `presentation`（popover、dialog、bottom-sheet）
+- 动画 API 简化，更易维护、跨组件更一致
+
+**相关 PR：** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
+
+## API 增强
+
+### 细粒度导出以优化包体
+
+库现为各组件提供细粒度导出路径，可按需 import 以减小包体。
+
+**新能力：**
+
+```tsx
+// 细粒度导入——仅需少量组件时推荐
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+
+// 总入口导入——会拉取整库，适合大量使用组件时
+import { Button, Card } from "heroui-native";
+```
+
+细粒度导入适合只用少数组件的场景；从 `heroui-native` 总入口导入会包含完整库，适合全站大量使用。
+
+**可用细粒度路径：**
+
+- `heroui-native/provider` — Provider
+- `heroui-native/[component-name]` — 各组件
+- `heroui-native/portal` — Portal 工具
+- `heroui-native/utils` — 工具函数
+- `heroui-native/hooks` — 自定义 Hooks
+
+<Callout type="warning">
+  **重要**：为控制包体，请在整个项目中**一致地**使用细粒度导入。只要存在一处从 `heroui-native` 总入口的导入，摇树优化策略即可能失效。
+</Callout>
+
+**相关 PR：** [#233](https://github.com/heroui-inc/heroui-native/pull/233)
+
+### 样式类名导出
+
+所有组件现导出对应样式类名，便于在代码中引用类名或搭建自定义主题方案。
+
+**新能力：**
+
+```tsx
+import { buttonClassNames } from "heroui-native";
+
+const customStyles = {
+  base: buttonClassNames.base,
+  variant: buttonClassNames.variant,
+};
+```
+
+**相关 PR：** [#252](https://github.com/heroui-inc/heroui-native/pull/252)
+
+## 样式修复
+
+### 样式优化
+
+- **移除 quaternary 变体**：删除第四级变体并打磨样式以提升一致性
+- **多组件样式打磨**：视觉一致性增强
+- **阴影与圆角**：跨组件阴影、圆角更统一
+- **主题变量整理**：简化变量并减少冗余 `color-mix` 计算
+
+**相关 PR：** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
+
+## ⚠️ 破坏性变更
+
+### Tabs `variant` 重命名
+
+Tabs 的 `variant` 由 `pill` / `line` 改为 `primary` / `secondary`，与其他组件命名更一致。
+
+**迁移：**
+
+```tsx
+// 之前
+<Tabs variant="pill">{/* content */}</Tabs>
+<Tabs variant="line">{/* content */}</Tabs>
+
+// 之后
+<Tabs variant="primary">{/* content */}</Tabs>
+<Tabs variant="secondary">{/* content */}</Tabs>
+```
+
+**可选项：**
+
+- `"primary"` — 原 `"pill"`
+- `"secondary"` — 原 `"line"`
+
+**相关 PR：** [#236](https://github.com/heroui-inc/heroui-native/pull/236)
+
+### Tabs 指示条动画实现变更
+
+[Tabs](/docs/native/components/tabs) 指示条由 `left` 定位改为 `translateX` 变换以利用 GPU。若自定义过指示条动画，需更新配置。
+
+**迁移：**
+
+```tsx
+// 之前
+<Tabs
+  indicatorAnimation={{
+    left: {
+      type: "spring",
+      config: { damping: 20, stiffness: 300 },
+    },
+  }}
+>
+  {/* content */}
+</Tabs>
+
+// 之后
+<Tabs
+  indicatorAnimation={{
+    translateX: {
+      type: "spring",
+      config: { damping: 20, stiffness: 300 },
+    },
+  }}
+>
+  {/* content */}
+</Tabs>
+```
+
+**变更摘要：**
+
+- `TabsIndicatorAnimation` 中由 `left` 改为 `translateX`
+- 指示条定位基于 `translateX` 变换
+- 指示条样式增加 `left-0` 基准类以保持初始位置
+- 观感应与此前一致，仅底层实现变化
+
+**相关 PR：** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
+
+### Divider 更名为 Separator
+
+`Divider` 已更名为 `Separator`，命名更统一，并避免与其他「分隔线」实现混淆。
+
+**迁移：**
+
+```tsx
+// 之前
+import { Divider } from "heroui-native";
+<Divider />
+
+// 之后
+import { Separator } from "heroui-native";
+<Separator />
+```
+
+**相关 PR：** [#238](https://github.com/heroui-inc/heroui-native/pull/238)
+
+### 移除 quaternary 变体
+
+[Surface](/docs/native/components/surface) 与 [Card](/docs/native/components/card) 已移除 `quaternary` 变体，简化设计系统。
+
+**迁移：**
+
+```tsx
+// 之前
+<Surface variant="quaternary">{/* content */}</Surface>
+<Card variant="quaternary">{/* content */}</Card>
+
+// 之后：使用 default、secondary、tertiary 或自定义 className
+<Surface variant="secondary">{/* content */}</Surface>
+<Card variant="secondary">{/* content */}</Card>
+<Surface className="bg-custom-quaternary">{/* content */}</Surface>
+```
+
+**可用变体：** `"default"`、`"secondary"`、`"tertiary"`
+
+**相关 PR：** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
+
+### 表单原语拆分与重命名
+
+表单拆分过程中若干组件重命名、结构调整，以获得更灵活的组合方式。
+
+**重命名：**
+
+- `FormField` → `ControlField`
+- `ErrorView` → `FieldError`
+
+**迁移：**
+
+```tsx
+// 之前
+import { FormField, ErrorView, TextField } from "heroui-native";
+<FormField>
+  <TextField.Input />
+  <ErrorView>Error message</ErrorView>
+</FormField>
+
+// 之后
+import { ControlField, FieldError, Input, TextField } from "heroui-native";
+<ControlField>
+  <Input />
+  <FieldError>Error message</FieldError>
+</ControlField>
+```
+
+**移除 TextField.Input：**
+
+请改用独立 `Input`：
+
+```tsx
+// 之前
+import { TextField } from "heroui-native";
+<TextField>
+  <TextField.Input placeholder="Enter text..." />
+</TextField>
+
+// 之后
+import { Input, TextField } from "heroui-native";
+<TextField>
+  <Input placeholder="Enter text..." />
+</TextField>
+```
+
+**组合方式：**
+
+`RadioGroup`、`TextField`、`ControlField` 现直接使用 `Label`、`Description`、`FieldError`：
+
+```tsx
+import { ControlField, Description, FieldError, Input, Label, RadioGroup, TextField } from "heroui-native";
+
+<TextField>
+  <Label>Email</Label>
+  <Input placeholder="Enter email..." />
+  <Description>We'll never share your email.</Description>
+  <FieldError>Invalid email address</FieldError>
+</TextField>
+
+<RadioGroup>
+  <Label>Select option</Label>
+  <RadioGroup.Item value="option1">
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+  <Description>Choose one option</Description>
+  <FieldError>Please select an option</FieldError>
+</RadioGroup>
+
+<ControlField>
+  <Label>Custom Field</Label>
+  <Input placeholder="Enter value..." />
+  <Description>Additional information</Description>
+  <FieldError>Validation error</FieldError>
+</ControlField>
+```
+
+**相关 PR：** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+### CloseButton 与移除 Close 的 asChild
+
+新增可复用 `CloseButton`；Dialog、Popover、Select、BottomSheet 的关闭实现统一基于该组件。各 `*.Close` 已移除 `asChild`。
+
+**迁移：**
+
+```tsx
+// 之前
+import { Button, Dialog } from "heroui-native";
+<Dialog>
+  <Dialog.Close asChild>
+    <Button>Cancel</Button>
+  </Dialog.Close>
+</Dialog>
+
+// 之后：用受控 open + 自定义按钮处理关闭
+import { Button, Dialog } from "heroui-native";
+const [isOpen, setIsOpen] = useState(false);
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <Button onPress={() => setIsOpen(false)}>Cancel</Button>
+</Dialog>
+```
+
+**变更摘要：**
+
+- 新增 `CloseButton`，默认 `variant="tertiary"`、`size="sm"`、`isIconOnly={true}`
+- `Dialog.Close`、`Popover.Close`、`Select.Close`、`BottomSheet.Close` 内部基于 `CloseButton`
+- 所有 Close 组件移除 `asChild`
+- Close 仍支持 Button 的 `variant`、`size`、`iconProps` 与自定义 `children`
+- 使用完全自定义按钮时需自行处理关闭逻辑
+
+**相关 PR：** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
+
+### 弹层动画系统重构（API）
+
+弹层动画重构带来若干需改代码的 API 调整。
+
+**迁移要点：**
+
+- 从 `Dialog.Root` 移除 `closeDelay`、`isDismissKeyboardOnClose`
+- 从 `Dialog.Root` 的 `animation` 移除自定义 `entering`/`exiting`（仅保留禁用类开关）；自定义进出场请在 `Dialog.Content` 上使用 Keyframe 动画配置
+- 从 `Dialog.Content` 移除 `isAnimatedStyleActive`、`onLayout`
+- 从 `BottomSheet.Root` 移除 `isDismissKeyboardOnClose`
+- `BottomSheet.Overlay` 的 `animation` 不再支持 `entering`/`exiting`
+- 所有 `Popover.Content`、`Select.Content` 必须显式传入 `presentation`（由可选改为必填）
+- `useBottomSheetAnimation()` 不再返回 `bottomSheetState`；`useDialogAnimation()` 不再返回 `dialogState`
+
+**变更摘要：**
+
+- `Dialog.Root`：移除 `closeDelay`、`isDismissKeyboardOnClose`；`animation` 类型由支持自定义进场的 `DialogRootAnimation` 收窄为仅禁用标志的 `AnimationRootDisableAll`
+- `Dialog.Content`：移除 `isAnimatedStyleActive`、`onLayout`
+- `BottomSheet.Root`：移除 `isDismissKeyboardOnClose`
+- `BottomSheet.Overlay`：`animation` 不再含 `entering`/`exiting`
+- `Popover.Content`、`Select.Content`：`presentation` 必填（此前可选，默认 `"popover"`）
+- 上述动画钩子返回值精简
+
+**相关 PR：** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #181](https://github.com/heroui-inc/heroui-native/issues/181)**：修复 TextField 输入中文等多字节字符报错；现正确处理多字节与国际输入，含中日韩等语言。
+
+- **[Issue #219](https://github.com/heroui-inc/heroui-native/issues/219)**：修复 Button `childrenToString()` 在多子节点时返回 `"[object Object]"`；现正确处理 React 元素与复杂子树，避免错误字符串化。
+
+- **[Issue #232](https://github.com/heroui-inc/heroui-native/issues/232)**：修复 HeroUINativeProvider 与新版 Uniwind Pro 不兼容；现可正常配合最新 Uniwind。
+
+- **[Issue #259](https://github.com/heroui-inc/heroui-native/issues/259)**：修复 Bottom Sheet 在快速打开并随即进行手势操作后偶发无法再次打开等问题；进出场动画逻辑重构后已缓解。
+
+- **[Issue #261](https://github.com/heroui-inc/heroui-native/issues/261)**：修复 `@gorhom/bottom-sheet` 无法被摇树剔除的问题；未使用依赖可被更好剔除。
+
+**其他修复：**
+
+- 修复主题计算色在部分场景下数值错误
+- 修复 `childrenToString`，避免错误地将 React 元素转为字符串
+
+**相关 PR：**
+
+- [#226](https://github.com/heroui-inc/heroui-native/pull/226)
+- [#239](https://github.com/heroui-inc/heroui-native/pull/239)
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/cli-v1-0-0.mdx b/apps/docs/content/docs/cn/native/releases/cli-v1-0-0.mdx
new file mode 100644
index 0000000..5a0af87
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/cli-v1-0-0.mdx
@@ -0,0 +1,130 @@
+---
+title: CLI v1.0.0
+description:
+  全新的命令行工具，用于一键创建预先配置好的 HeroUI Native + Expo Router 项目 —— Expo SDK 56、React Native 0.85、Uniwind，所有 peer 依赖均已就绪，并提供两套起始模板（单页面与 Tabs）。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 6 月 4 日</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/cli-demo.mp4"
+  height={430}
+  muted
+/>
+
+🎉 全新的 CLI —— [`create-heroui-native-app`](https://www.npmjs.com/package/create-heroui-native-app) —— 现已成为启动 HeroUI Native 项目最快捷的方式。一条命令即可生成一个完整的 Expo Router 应用，内置 HeroUI Native、Uniwind、Tailwind CSS、所有必需的 peer 依赖以及 Provider 包装，无需再手动配置 `global.css`、`metro.config.js` 或 `app/_layout.tsx`。
+
+## 快速开始
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npx create-heroui-native-app@latest my-app
+  ```
+</Tab>
+<Tab value="pnpm">
+  ```bash
+  pnpm create heroui-native-app@latest my-app
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn create heroui-native-app my-app
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun create heroui-native-app@latest my-app
+  ```
+</Tab>
+</Tabs>
+
+随后启动开发服务器：
+
+```bash
+cd my-app
+npm run start
+```
+
+到此为止。如需完整流程，请直接阅读[快速开始指南](/docs/native/getting-started/quick-start)。
+
+## 起始模板
+
+CLI 自带两套模板。可在交互式选择器中选择，或通过命令行参数跳过提示：
+
+| 参数 | 模板 | 说明 |
+| --- | --- | --- |
+| `--expo` | `expo` | 单页面 Expo Router 应用，含 HeroUI `Button` 演示。 |
+| `--expo-tabs` | `expo-tabs` | 含两个 Tabs（`Button` + `Card` 演示）的 Expo Router 布局。 |
+
+```bash
+npx create-heroui-native-app@latest my-app --expo
+npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
+```
+
+## 你将得到什么
+
+每个生成的项目都已预先配置：
+
+- **Expo SDK 56** + **Expo Router**，并启用类型化路由
+- **React 19.2** + **React Native 0.85.2** + Hermes v1（SDK 56 默认启用）
+- **HeroUI Native**：在 `app/_layout.tsx` 中由 `HeroUINativeProvider` 与 `GestureHandlerRootView` 包裹
+- **Uniwind** + **Tailwind CSS**：通过 `metro.config.js` 与 `global.css` 完成接入
+- 所有 HeroUI Native **必需的 peer 依赖**已锁定到兼容版本：`react-native-reanimated`、`react-native-gesture-handler`、`react-native-worklets`、`react-native-safe-area-context`、`react-native-svg`、`tailwind-variants`、`tailwind-merge`
+- 内置 `react-native-screens`，让 HeroUI 的遮罩组件（`Dialog`、`Menu`、`Popover`、`Select`、`BottomSheet`、`Toast`）开箱即用
+- `@expo/metro-runtime`（SDK 56 上 Expo Router 需要的 peer 依赖）
+- 仅使用 `babel-preset-expo` 的 `babel.config.js`（worklets 已由该 preset 处理）
+- 启用 `strict: true` 与 `@/*` 路径别名的 **TypeScript** 配置
+
+## CLI 参考
+
+```text
+create-heroui-native-app [project-name] [options]
+```
+
+| 选项 | 说明 |
+| --- | --- |
+| `[project-name]` | 要创建的目录名。未提供时会进行交互提示。必须是合法的 npm 包名。 |
+| `--expo` | 使用单页面 Expo 模板。 |
+| `--expo-tabs` | 使用 Expo + Tabs 模板。 |
+| `--template <id>` | 指定模板 id（`expo` 或 `expo-tabs`）。 |
+| `--use-npm` / `--use-yarn` / `--use-pnpm` / `--use-bun` | 强制使用指定包管理器（默认自动检测）。 |
+| `--skip-install` | 跳过依赖安装步骤。 |
+| `--skip-git` | 不初始化 git 仓库。 |
+| `-h`, `--help` | 打印用法并退出。 |
+
+### 示例
+
+```bash
+# 完全交互式 —— 同时提示项目名与模板
+npx create-heroui-native-app@latest
+
+# 已指定项目名，仍展示模板选择器
+npx create-heroui-native-app@latest my-app
+
+# 完全非交互式
+npx create-heroui-native-app@latest my-app --expo
+
+# 使用 Tabs 模板，并通过 pnpm 安装依赖
+npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
+
+# 仅生成项目，不安装依赖、不初始化 git
+npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git
+```
+
+## 系统要求
+
+- **Node.js 20.19.4+**（Expo SDK 56 / React Native 0.85 的要求）
+- 构建原生 iOS 时需要 **iOS 16.4+**（Expo SDK 56 的部署目标）
+- macOS、Linux 或 Windows
+
+<Callout type="info">
+  **已经有应用了？** 本 CLI 仅用于创建新项目。若要将 HeroUI Native 添加到既有的 React Native 或 Expo 应用，请参阅[快速开始中的方案 2](/docs/native/getting-started/quick-start#option-2-add-to-an-existing-project)。
+</Callout>
+
+## 链接
+
+- [快速开始指南](/docs/native/getting-started/quick-start)
+- [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)
diff --git a/apps/docs/content/docs/cn/native/releases/index.mdx b/apps/docs/content/docs/cn/native/releases/index.mdx
new file mode 100644
index 0000000..91142e9
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/index.mdx
@@ -0,0 +1,171 @@
+---
+title: 所有版本
+description: HeroUI Native 的全部更新与变更，包括新功能、问题修复与破坏性变更。
+---
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 最新版本
+
+### v1.0.5
+
+**2026 年 7 月**
+
+本版本将工具链升级至 Expo 57 / React Native 0.86，并在各表单组件中以基于 outline 的聚焦、激活与无效状态优化字段边框样式。同时为 Typography 新增 iOS Dynamic Type 支持，引入 Provider 级的文本输入配置，并以更轻量、单次挂载的进入动画改进 Popover、Menu 与 Select。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-5)
+
+---
+
+### CLI v1.0.0
+
+**2026 年 6 月**
+
+🎉 全新的 CLI，用于一键创建 HeroUI Native 项目。`npx create-heroui-native-app@latest my-app` 即可生成一个完整的 Expo Router 应用，内置 HeroUI Native、Uniwind、Tailwind CSS、所有必需的 peer 依赖以及 Provider 包装 —— 还可在单页面与 Tabs 两套起始模板中任选其一。
+
+[阅读完整更新说明 →](/docs/native/releases/create-heroui-native-app)
+
+---
+
+### v1.0.4
+
+**2026 年 5 月**
+
+本补丁版本将 `Text` 排版组件重命名为 `Typography`（保留 `Text` 的弃用导出以兼容旧代码），调整 `Alert`、`Avatar`、`Button`、`Chip`、`Toast` 等组件的 soft 前景色主题令牌，并新增可选的 `heroui-native/styles/vibrant` 鲜亮配色；为 `Menu`、`Popover`、`Select` 补充 iOS 原生模态偏移的处理说明；将示例应用升级至 Expo 56 / React Native 0.85，并将 `@gorhom/bottom-sheet` 对等依赖升至 `^5.2.9`。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-4)
+
+---
+
+### v1.0.3
+
+**2026 年 5 月**
+
+本补丁版本引入全新的 `Text` 排版组件，提供 `Heading`、`Paragraph`、`Code` 子组件；修复 `ScrollShadow` 对反向列表的支持以及 `Tabs` 指示器在 RTL 布局下的对齐；并在使用自定义 children 时统一 `Select.TriggerIndicator` 的动画。同时将 `Avatar` 的 `alt` 属性改为可选，微调 `Button`、`Chip`、`Input` 的样式，并修正 `TextField` 与 `SearchField` 的内部内边距行为。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-3)
+
+---
+
+### v1.0.2
+
+**2026 年 4 月**
+
+本补丁版本为 PressableFeedback 与 Surface 引入 `asChild` 插槽模式；为所有基于 Portal 的遮罩增加 VoiceOver 模态包容支持；修复 Android 上 Button outline 变体的样式问题；并微调 Input 与 Select 的视觉效果。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-2)
+
+---
+
+### v1.0.1
+
+**2026 年 4 月**
+
+本补丁版本修复 Toast 提供程序中 `total` SharedValue 与实际 Toast 数量不同步的竞态；将七个组件的禁用态样式改为使用原生 `disabled:` 修饰符；并为主题系统新增供遮罩组件使用的 `--backdrop` 变量。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-1)
+
+---
+
+### v1.0.0
+
+**2026 年 3 月**
+
+🎉 HeroUI Native 迎来首个稳定版本，从 beta 与候选发布阶段毕业。本里程碑包含全新 LinkButton 组件、子菜单冲突处理、可选的 `@gorhom/bottom-sheet` 对等依赖，以及更强的 `useThemeColor` 类型安全。
+
+[阅读完整更新说明 →](/docs/native/releases/v1-0-0)
+
+---
+
+### RC 4
+
+**2026 年 3 月**
+
+本版本引入用于嵌套可展开菜单的 SubMenu 复合组件（带动画展开/收起）；以基于插槽的样式与 `textProps` 透传重构 Slider Output；并修复快速连按时 PressableFeedback 水波纹动画闪烁。
+
+[阅读完整更新说明 →](/docs/native/releases/rc-4)
+
+---
+
+### RC 3
+
+**2026 年 2 月**
+
+本版本新增 TagGroup、Menu、InputGroup 三个组件；为所有基于 Bottom Sheet 的遮罩增加 Android 实体返回键支持；并通过关键的 `combineStyles` 修复保留 Reanimated 动画样式绑定，实现 Expo 55 兼容。
+
+[阅读完整更新说明 →](/docs/native/releases/rc-3)
+
+---
+
+### RC 2
+
+**2026 年 2 月**
+
+本版本新增 SearchField、ListGroup、Slider 三个组件；为 Select 增加由类型安全泛型支撑的多选模式；将 Button 反馈 API 重构为统一的 `feedbackVariant` + `animation`。放宽对等依赖约束以更好兼容 Expo SDK 55，并修复若干 Select 与 Avatar 问题。
+
+[阅读完整更新说明 →](/docs/native/releases/rc-2)
+
+---
+
+### RC 1
+
+**2026 年 2 月**
+
+本版本引入含五种状态变体与无障碍原语的 Alert 复合组件；将 Radio 抽为可双模式运行的独立组件；新增带动画的 Select.TriggerIndicator。另提供用于精简包体的 HeroUINativeProviderRaw、用于 iOS 调试的 `disableFullWindowOverlay`、六个组件统一的 `styles` 属性，以及以各主题显式定义取代计算型的 surface 主题变量重构。
+
+[阅读完整更新说明 →](/docs/native/releases/rc-1)
+
+---
+
+### Beta 13
+
+**2026 年 2 月**
+
+本版本引入多行输入组件 TextArea、Button outline 变体，为所有组件导出样式类名，并提供可复用的 CloseButton。同时重构 Tabs（动画与变体命名改进）、将表单相关能力拆为独立原语，并增加细粒度导出以优化包体。另含主题色与组件字符串化等关键修复。
+
+[阅读完整更新说明 →](/docs/native/releases/beta-13)
+
+---
+
+### Beta 12
+
+**2026 年 1 月**
+
+本版本新增 InputOTP、Label、Description 三个核心表单组件，强化 React Native 中的表单搭建能力。另含 Popover 关闭行为、弹层受控状态、圆角配置等关键修复，并为多个表单组件增加变体样式属性支持。
+
+[阅读完整更新说明 →](/docs/native/releases/beta-12)
+
+---
+
+### Beta 11
+
+**2026 年 1 月**
+
+本版本通过 Bottom Sheet 关闭协同改进、Dialog 侧滑关闭手势修复、TextField 样式优化，以及面向高级 Portal 挂载场景的 PortalHost 导出，提升组件可靠性与开发者体验，使交互更顺滑、自定义布局更灵活。
+
+[阅读完整更新说明 →](/docs/native/releases/beta-11)
+
+---
+
+### Beta 10
+
+**2025 年 12 月**
+
+本版本引入新的 [Bottom Sheet](/docs/native/components/bottom-sheet) 组件；重构 [PressableFeedback](/docs/native/components/pressable-feedback) 并改进 API；扩展动画 API 以支持 State Prop；增强 `use-theme-color` 钩子以支持多色选取；并包含若干问题修复与文档改进。
+
+[阅读完整更新说明 →](/docs/native/releases/beta-10)
+
+---
+
+## 发布周期
+
+HeroUI Native 遵循常规发布周期：
+
+- **稳定版**：v1.0.0 已于 2026 年第一季度发布
+- **补丁版**：按需发布问题修复与小幅改进
+
+## 参与贡献
+
+发现问题或想参与贡献？请访问我们的 [GitHub 仓库](https://github.com/heroui-inc/heroui-native)。
diff --git a/apps/docs/content/docs/cn/native/releases/meta.json b/apps/docs/content/docs/cn/native/releases/meta.json
new file mode 100644
index 0000000..b1bcace
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/meta.json
@@ -0,0 +1,26 @@
+{
+  "title": "发布说明",
+  "description": "HeroUI Native 发布说明",
+  "icon": "rocket",
+  "root": true,
+  "pages": [
+    "---概述---",
+    "index",
+    "---版本列表---",
+    "v1-0-5",
+    "cli-v1-0-0",
+    "v1-0-4",
+    "v1-0-3",
+    "v1-0-2",
+    "v1-0-1",
+    "v1-0-0",
+    "rc-4",
+    "rc-3",
+    "rc-2",
+    "rc-1",
+    "beta-13",
+    "beta-12",
+    "beta-11",
+    "beta-10"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/native/releases/rc-1.mdx b/apps/docs/content/docs/cn/native/releases/rc-1.mdx
new file mode 100644
index 0000000..f2b1291
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/rc-1.mdx
@@ -0,0 +1,499 @@
+---
+title: RC 1
+description: Alert 组件、独立 Radio 组件、Select TriggerIndicator、HeroUINativeProviderRaw、disableFullWindowOverlay、styles 属性扩展、主题 surface 重构
+github:
+  pull: 284
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 12 日</span>
+</div>
+
+RC 1 是 HeroUI Native 的首个候选发布（Release Candidate），表明库已接近生产可用。本版本引入以无障碍为先、带状态变体的 Alert 复合组件；将 Radio 抽为可双模式运行的独立组件；新增带动画的 Select.TriggerIndicator 子组件。还提供轻量 `HeroUINativeProviderRaw` 以优化包体、用于 iOS 调试的 `disableFullWindowOverlay`、六个组件统一的 `styles` 插槽式样式，以及用主题显式变量替代计算型 surface 色的主题重构。另含 BottomSheet 内 InputOTP、Toast 文字裁切与元素检查器兼容等关键修复。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 RC 1 的全部改进！你可以探索新的 Alert 与 Radio、Select TriggerIndicator，以及各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### 新组件
+
+本版本新增 **1** 个组件：
+
+- **[Alert](/docs/native/components/alert)**：无障碍告警组件，五种状态变体，复合子组件灵活组合内容。
+
+#### Alert
+
+Alert 提供无障碍告警展示，内置五种状态变体：default、accent、success、warning、danger。遵循复合组件模式，含 `Alert.Indicator`、`Alert.Content`、`Alert.Title`、`Alert.Description`，便于布局与定制。原语层自动提供 `role="alert"`、`aria-labelledby` 与 `aria-describedby` 关联。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="alert"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 五种状态变体：default、accent、success、warning、danger
+- 默认 SVG 状态图标，通过 `useStatusColor` 随主题着色
+- 复合架构：Indicator、Content、Title、Description
+- 支持自定义指示器（如替换为 Spinner）
+- 无障碍原语：`role="alert"`、`aria-labelledby`、`aria-describedby`
+- 所有子组件支持 `asChild` 插槽
+- 所有部件支持 ref 转发与 `className`
+
+**用法：**
+
+```tsx
+import { Alert } from "heroui-native";
+
+export function Example() {
+  return (
+    <Alert status="success">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Payment successful</Alert.Title>
+        <Alert.Description>
+          Your payment has been processed successfully.
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+完整文档与示例见 [Alert 组件页](/docs/native/components/alert)。
+
+**相关 PR：** [#284](https://github.com/heroui-inc/heroui-native/pull/284)
+
+### 新子组件
+
+#### Select.TriggerIndicator
+
+[Select](/docs/native/components/select) 新增 `TriggerIndicator` 子组件，显示带动画的 V 形图标以表示开/关状态，开闭时以 Reanimated 弹簧物理旋转。
+
+**特性：**
+
+- 开闭过渡时旋转的 V 形动画
+- `animation` 可配置旋转值与弹簧参数
+- `iconProps` 自定义尺寸、颜色
+- 支持自定义子节点替换默认 V 形
+- 与 Select 开闭状态自动同步
+
+**用法：**
+
+```tsx
+import { Select } from "heroui-native";
+
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="Select an option" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Content>
+      {/* Select items */}
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+**相关 PR：** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+## 组件改进
+
+### Toast 样式与堆叠重构
+
+[Toast](/docs/native/components/toast) 样式由边框模拟内边距改为真实 `p-4` 与上下占位视图，改善多 Toast 堆叠时的内容可见性。
+
+**改进：**
+
+- 以 `p-4` 取代 `border-[16px]` 内边距变通写法
+- 新增 `useVerticalPlaceholderStyles` 用于占位视图样式
+- 顶部与底部绝对定位占位 View，避免堆叠时内容露出
+- 阴影系统改用 `shadow-overlay` 令牌
+- 统一各主题（alpha、mint、sky）的遮罩阴影，降低不透明度
+
+确保不同高度 Toast 堆叠时内容仍被正确遮挡，样式更易维护、可预期。
+
+**相关 PR：** [#229](https://github.com/heroui-inc/heroui-native/pull/229)
+
+### Dialog 遮罩手势关闭动画时序
+
+[Dialog](/docs/native/components/dialog) 在手势关闭时弹层动画时序已修复：进度值按延迟正确排队，确保关闭动画播完再重置。
+
+**改进：**
+
+- 手势关闭时进度在 300ms 延迟后过渡到 2
+- 350ms 后进度重置为 0，保证动画完成
+- 移除 `isOpen` 为 false 时立即 `progress.set(2)` 的调用
+- 侧滑关闭时关闭动画可正常播放
+
+**相关 PR：** [#277](https://github.com/heroui-inc/heroui-native/pull/277)
+
+### 主题 Surface 变量重构
+
+主题系统以主题文件中的显式 surface 变量取代计算色，跨主题更可控、更一致。
+
+**改进：**
+
+- `surface-secondary`、`surface-tertiary`（及对应前景）在各主题（alpha、lavender、mint、sky、variables.css）中显式定义
+- 基础主题使用 `var(--surface-secondary)`、`var(--surface-tertiary)`，不再用 `color-mix` 计算
+- 从 theme.css 移除 `on-surface`、`on-surface-secondary`、`on-surface-tertiary` 调色板
+- 主题文档更新变量结构与示例
+
+主题作者可直接控制 surface 色值，不再依赖 `color-mix`，各主题 surface 表现更可预期。
+
+**相关 PR：** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
+
+## API 增强
+
+### 多组件统一 `styles` 属性
+
+六个组件现支持统一的 `styles` 插槽式样式 API。
+
+**涉及组件：**
+
+- **Accordion**：`container`、`separator` 插槽
+- **AvatarFallback**：`container`、`text` 插槽
+- **FieldError**：`container`、`text` 插槽
+- **Label**：`text`、`asterisk` 插槽（并修复 `style` 处理）
+- **PressableFeedback Ripple**：`container`、`ripple` 插槽（取代 `containerStyle` 与 `rippleStyle`）
+- **SelectContentDialog**：`wrapper`、`content` 插槽
+
+**新能力：**
+
+```tsx
+import { Accordion, Label } from "heroui-native";
+
+// 对指定插槽应用样式
+<Label styles={{ text: { fontSize: 18 }, asterisk: { color: "red" } }} isRequired>
+  Username
+</Label>
+
+<Accordion
+  styles={{
+    container: { borderRadius: 12 },
+    separator: { backgroundColor: "gray" },
+  }}
+>
+  {/* Accordion items */}
+</Accordion>
+```
+
+变更保持与既有 `style` 的向后兼容，二者同时提供时会正确合并。
+
+**相关 PR：** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
+
+### `disableFullWindowOverlay` 属性
+
+基于 Portal 的组件现支持 `disableFullWindowOverlay`，便于在 iOS 开发时使用 React Native 元素检查器。
+
+**涉及组件：**
+
+- `BottomSheet.Portal`
+- `Dialog.Portal`
+- `Popover.Portal`
+- `Select.Portal`
+- `ToastProvider`
+
+**新能力：**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+// 在 iOS 上启用元素检查器
+<Dialog>
+  <Dialog.Portal disableFullWindowOverlay>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      {/* content */}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+iOS 上 `FullWindowOverlay` 使用独立原生窗口，会阻挡元素检查器。将 `disableFullWindowOverlay` 设为 `true` 时内容绘于主窗口，开发期可检查元素；代价是遮罩不再叠在原生模态或键盘之上。Android 上该属性无效果。
+
+使用 `HeroUINativeProvider` 时，Toast 通过 `config.toast` 传入该属性。
+
+**相关 PR：** [#283](https://github.com/heroui-inc/heroui-native/pull/283)
+
+### HeroUINativeProviderRaw
+
+新增轻量提供者变体 `HeroUINativeProviderRaw`，不包含 `ToastProvider` 与 `PortalHost`，由使用方完全控制打包依赖。
+
+**新能力：**
+
+```tsx
+import { HeroUINativeProviderRaw } from "heroui-native/provider-raw";
+
+// 无 Toast 与 Portal 的轻量提供者
+export function App() {
+  return (
+    <HeroUINativeProviderRaw>
+      {/* Your app content */}
+    </HeroUINativeProviderRaw>
+  );
+}
+```
+
+`react-native-screens`、`@gorhom/bottom-sheet`、`react-native-svg` 由此可作为完全可选的对等依赖。Raw 提供者仅含 `SafeAreaListener`、`GlobalAnimationSettingsProvider`、`TextComponentProvider`。需要 Toast 或 Portal 时可自行组合。
+
+**相关 PR：** [#285](https://github.com/heroui-inc/heroui-native/pull/285)
+
+### Select.Trigger 的 `variant` 属性
+
+`Select.Trigger` 现支持 `variant`：`"default"` 与 `"unstyled"`，便于与 Button 等自定义触发器组合。
+
+**新能力：**
+
+```tsx
+import { Button, Select } from "heroui-native";
+
+// 默认变体（预置样式触发器）
+<Select>
+  <Select.Trigger variant="default">
+    <Select.Value placeholder="Choose..." />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+</Select>
+
+// 无样式变体，用于自定义组合
+<Select>
+  <Select.Trigger variant="unstyled">
+    <Button>
+      <Select.Value placeholder="Choose..." />
+      <Select.TriggerIndicator />
+    </Button>
+  </Select.Trigger>
+</Select>
+```
+
+**相关 PR：** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+### ControlField 的 Radio 变体
+
+[ControlField](/docs/native/components/control-field) 的 `ControlField.Indicator` 现支持 `"radio"` 变体，与既有 `"switch"`、`"checkbox"` 并列，渲染独立 Radio 组件。
+
+**新能力：**
+
+```tsx
+import { ControlField } from "heroui-native";
+
+<ControlField>
+  <ControlField.Indicator variant="radio" />
+  <ControlField.Label>Radio option</ControlField.Label>
+</ControlField>
+```
+
+**相关 PR：** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
+
+## ⚠️ 破坏性变更
+
+### PressableFeedback Ripple：统一 `styles` 属性
+
+PressableFeedback Ripple 的 `containerStyle` 与 `rippleStyle` 已合并为统一 `styles`。
+
+**迁移：**
+
+将所有单独样式属性改为 `styles`：
+
+```tsx
+// 之前
+<PressableFeedback.Ripple
+  containerStyle={{ borderRadius: 8 }}
+  rippleStyle={{ backgroundColor: "blue" }}
+/>
+
+// 之后
+<PressableFeedback.Ripple
+  styles={{
+    container: { borderRadius: 8 },
+    ripple: { backgroundColor: "blue" },
+  }}
+/>
+```
+
+**相关 PR：** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
+
+### Select.Trigger 默认样式
+
+`Select.Trigger` 默认 `variant="default"`，会应用容器样式（`flex-row items-center justify-between h-12 px-4 rounded-2xl bg-surface shadow-surface`）。若此前为自定义样式触发器，需加 `variant="unstyled"` 以免套用默认样式。
+
+**迁移：**
+
+```tsx
+// 之前（自定义样式触发器）
+<Select.Trigger className="custom-trigger-styles">
+  {/* content */}
+</Select.Trigger>
+
+// 之后（加 variant="unstyled" 保留自定义）
+<Select.Trigger variant="unstyled" className="custom-trigger-styles">
+  {/* content */}
+</Select.Trigger>
+```
+
+**相关 PR：** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+### Surface 主题变量结构调整
+
+基础主题已移除 `on-surface`、`on-surface-secondary`、`on-surface-tertiary` 及其 hover/focus 变体 CSS 变量。secondary/tertiary surface 色现于各主题文件中显式定义。
+
+**迁移：**
+
+若自定义样式引用上述变量，请改为主题中定义的对应 surface 前景变量。
+
+```css
+/* 之前 */
+color: var(--on-surface);
+color: var(--on-surface-secondary);
+
+/* 之后 */
+color: var(--surface-foreground);
+color: var(--surface-secondary-foreground);
+```
+
+**相关 PR：** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
+
+### 移除 RadioGroup.Indicator
+
+`RadioGroup.Indicator` 与 `RadioGroup.IndicatorThumb` 已移除，改为独立 `Radio` 组件。相关类型 `RadioGroupIndicatorProps`、`RadioGroupIndicatorThumbProps`、`RadioGroupIndicatorThumbAnimation` 亦不再导出。
+
+**迁移：**
+
+将所有 `RadioGroup.Indicator` / `RadioGroup.IndicatorThumb` 替换为 `Radio`：
+
+```tsx
+// 之前
+import { RadioGroup } from "heroui-native";
+
+<RadioGroup>
+  <RadioGroup.Item value="option1">
+    <RadioGroup.Indicator>
+      <RadioGroup.IndicatorThumb />
+    </RadioGroup.Indicator>
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+</RadioGroup>
+
+// 之后
+import { Radio, RadioGroup } from "heroui-native";
+
+<RadioGroup>
+  <RadioGroup.Item value="option1">
+    <Radio>
+      <Radio.Indicator>
+        <Radio.IndicatorThumb />
+      </Radio.Indicator>
+    </Radio>
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+</RadioGroup>
+```
+
+**相关 PR：** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #229](https://github.com/heroui-inc/heroui-native/issues/229)**：修复 BottomSheet 内 InputOTP 不可用。现可在 BottomSheet 遮罩内正常聚焦与输入，解决此前无法输入 OTP 的问题。
+
+- **[Issue #265](https://github.com/heroui-inc/heroui-native/issues/265)**：修复 Toast 描述首字符被裁切。Toast 样式重构后以真实内边距与占位视图取代边框变通，任意堆叠配置下文字均可完整显示。
+
+- **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**：修复 FullWindowOverlay 在 iOS 上阻挡 React Native 元素检查器。Portal 组件新增 `disableFullWindowOverlay`，开发期可将遮罩内容绘于主窗口以恢复检查器。
+
+**相关 PR：**
+
+- [#229](https://github.com/heroui-inc/heroui-native/pull/229)
+- [#283](https://github.com/heroui-inc/heroui-native/pull/283)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [Alert](/docs/native/components/alert) — 新组件：用法示例与 API 参考
+- [Radio](/docs/native/components/radio) — 独立 Radio 组件文档
+- [Radio Group](/docs/native/components/radio-group) — 反映移除 RadioGroup.Indicator 及与 Radio 的集成
+- [Control Field](/docs/native/components/control-field) — 新增 radio 变体说明
+- [Select](/docs/native/components/select) — TriggerIndicator 子组件与 Trigger variant
+- [Toast](/docs/native/components/toast) — 更新样式实现说明
+- [Bottom Sheet](/docs/native/components/bottom-sheet) — 补充 disableFullWindowOverlay
+- [Dialog](/docs/native/components/dialog) — 补充 disableFullWindowOverlay
+- [Popover](/docs/native/components/popover) — 补充 disableFullWindowOverlay
+- [Provider](/docs/native/getting-started/provider) — HeroUINativeProviderRaw 与提供者层级
+- [Theming](/docs/native/getting-started/theming) — 更新 surface 变量结构与示例
+- [Accordion](/docs/native/components/accordion) — 补充 styles 属性
+- [Avatar](/docs/native/components/avatar) — 补充 styles 属性
+- [Label](/docs/native/components/label) — 补充 styles 属性
+- [Field Error](/docs/native/components/field-error) — 补充 styles 属性
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/rc-2.mdx b/apps/docs/content/docs/cn/native/releases/rc-2.mdx
new file mode 100644
index 0000000..a09de88
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/rc-2.mdx
@@ -0,0 +1,446 @@
+---
+title: RC 2
+description: SearchField、ListGroup、Slider 组件，Select 多选模式，Button 反馈 API 重构，放宽对等依赖约束
+github:
+  pull: 298
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 20 日</span>
+</div>
+
+RC 2 继续向生产就绪推进：新增 SearchField、ListGroup、Slider 三个组件；Select 支持由类型安全泛型支撑的多选模式；Button 按压反馈 API 重构为统一的 `feedbackVariant` + `animation`；放宽对等依赖约束以更好兼容 Expo SDK 55。另含若干 Select 与 Avatar 的问题修复。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 RC 2 的全部改进！你可以探索 SearchField、ListGroup、Slider、Select 多选模式、更新后的 Button 反馈 API，以及各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### 新组件
+
+本版本新增 **3** 个组件：
+
+- **[Slider](/docs/native/components/slider)**：支持单值与区间模式、横/纵方向、自定义数字格式与弹簧动画拇指反馈。
+- **[ListGroup](/docs/native/components/list-group)**：基于 Surface 的分组列表，可按压项、前后缀槽位，默认右箭头导航指示。
+- **[SearchField](/docs/native/components/search-field)**：用于筛选与查询的复合组件，内置搜索图标、可清空输入与空值时自动隐藏清除按钮。
+
+#### Slider
+
+Slider 支持单值与区间（双拇指）模式、横纵布局、通过 `Intl.NumberFormat` 自定义数字格式，以及弹簧动画拇指反馈。原语层独立处理手势与数值逻辑，便于换肤实现复用。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="slider"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`Slider.Output`、`Slider.Track`、`Slider.Fill`、`Slider.Thumb`
+- 区间滑块：`defaultValue`/`value` 传入数组，在 `Slider.Track` 上使用渲染函数渲染多个拇指
+- `orientation="vertical"` 纵向
+- `formatOptions` 接受 `Intl.NumberFormatOptions`（货币、百分比、单位等）
+- 基于 gesture-handler 的拖拽与轨道点击定位
+- 数值钳制、步进与多拇指支持
+- 可通过 `animation` 配置弹簧缩放拇指动画
+- 无障碍：每个拇指 `role="slider"`，完整 `accessibilityValue`（min、max、now、text）
+- `useSlider` 暴露上下文供高级用法
+
+**用法：**
+
+```tsx
+import { Slider } from "heroui-native";
+
+export function BasicSlider() {
+  return (
+    <Slider defaultValue={50} minValue={0} maxValue={100}>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
+
+export function RangeSlider() {
+  return (
+    <Slider defaultValue={[20, 80]} minValue={0} maxValue={100}>
+      <Slider.Output />
+      <Slider.Track>
+        {({ thumbs }) => (
+          <>
+            <Slider.Fill />
+            {thumbs.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+完整文档与示例见 [Slider 组件页](/docs/native/components/slider)。
+
+**相关 PR：** [#305](https://github.com/heroui-inc/heroui-native/pull/305)
+
+#### ListGroup
+
+ListGroup 在 Surface 容器内渲染分组列表项，适用于设置页、菜单与内容浏览等导航列表模式。每项支持前缀、内容（标题 + 描述）与后缀槽位，默认带右箭头导航指示。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="list-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 基于 Surface 的圆角容器与一致间距
+- 复合子组件：`ListGroup.Item`、`ListGroup.ItemPrefix`、`ListGroup.ItemContent`、`ListGroup.ItemTitle`、`ListGroup.ItemDescription`、`ListGroup.ItemSuffix`
+- `ItemSuffix` 默认内置 `ChevronRightIcon`
+- 可按压项，集成 PressableFeedback
+- 槽位可完全自定义图标、徽标等
+
+**用法：**
+
+```tsx
+import { ListGroup } from "heroui-native";
+
+export function Example() {
+  return (
+    <ListGroup>
+      <ListGroup.Item onPress={() => console.log("Profile")}>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Profile</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>Manage your account</ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+      <ListGroup.Item onPress={() => console.log("Settings")}>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Settings</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>App preferences</ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </ListGroup>
+  );
+}
+```
+
+完整文档与示例见 [ListGroup 组件页](/docs/native/components/list-group)。
+
+**相关 PR：** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+#### SearchField
+
+SearchField 为搜索与筛选场景提供专用输入，采用与 TextField 相同的复合组件模式：搜索图标、可清空输入、值为空时自动隐藏清除按钮。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="search-field"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`SearchField.Group`、`SearchField.SearchIcon`、`SearchField.Input`、`SearchField.ClearButton`
+- `ClearButton` 在值为空时自动隐藏，按压清除搜索文本
+- `SearchIcon` 支持自定义子节点替换默认放大镜 SVG
+- 校验态视觉反馈
+- 禁用态支持
+- 与 Label、Description、FieldError 无缝集成
+
+**用法：**
+
+```tsx
+import { Label, SearchField } from "heroui-native";
+
+export function Example() {
+  return (
+    <SearchField>
+      <Label>Search</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input placeholder="Search components..." />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
+```
+
+完整文档与示例见 [SearchField 组件页](/docs/native/components/search-field)。
+
+**相关 PR：** [#299](https://github.com/heroui-inc/heroui-native/pull/299)
+
+### Select 多选模式
+
+[Select](/docs/native/components/select) 现通过 `selectionMode` 支持多选。`RootProps` 对 `SelectionMode` 泛型化，TypeScript 按模式解析 `value` 与 `onValueChange`——单选为 `SelectOption`，多选为 `SelectOption[]`。
+
+**特性：**
+
+- `selectionMode="multiple"` 可多选切换；多选模式下 `closeOnPress` 默认 `false`
+- 类型安全泛型：`RootProps<M>` 通过 `SelectValueType<M>` 解析 `value`/`onValueChange`
+- `Select.Value` 使用 `formatSelectedLabels` 将多标签格式化为「Apple, Banana and Cherry」
+- 单选模式完全向后兼容（默认）
+
+**用法：**
+
+```tsx
+import { Select } from "heroui-native";
+
+export function MultiSelect() {
+  return (
+    <Select selectionMode="multiple">
+      <Select.Trigger>
+        <Select.Value placeholder="Select fruits..." />
+        <Select.TriggerIndicator />
+      </Select.Trigger>
+      <Select.Portal>
+        <Select.Content>
+          <Select.Item value="apple" label="Apple" />
+          <Select.Item value="banana" label="Banana" />
+          <Select.Item value="cherry" label="Cherry" />
+        </Select.Content>
+      </Select.Portal>
+    </Select>
+  );
+}
+```
+
+**相关 PR：** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+### 新子组件
+
+#### PressableFeedback.Scale
+
+新增复合子组件，用于可选的缩放按压动画组合。`PressableFeedback.Scale` 可为任意可按压元素（如 `ListGroup.Item`）增加缩放反馈，而无需根级 `PressableFeedback` 管理缩放。
+
+**用法：**
+
+```tsx
+import { PressableFeedback } from "heroui-native";
+
+<PressableFeedback.Scale>
+  <ListGroup.Item onPress={handlePress}>
+    {/* item content */}
+  </ListGroup.Item>
+</PressableFeedback.Scale>
+```
+
+**相关 PR：** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## 组件改进
+
+### Select 触发器与状态修复
+
+[Select](/docs/native/components/select) 针对触发器与受控状态有多项修复。
+
+**改进：**
+
+- 自定义 `className` 现正确参与触发器样式计算，修复用户类名被静默丢弃的情况
+- `useControllableState` 在从受控切到非受控时重置内部状态，避免陈旧选中残留
+- 触发器通过 `onLayout` 测量位置，正确支持 `isDefaultOpen`
+- 触发器样式更新为 `gap-3`、`py-3.5`，值文本使用 `flex-1` 改善布局
+
+**相关 PR：** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+### Avatar asChild 图片修复
+
+[Avatar](/docs/native/components/avatar) 的 `AvatarImage` 在向底层原语转发时正确分离 `source`、`style` 与 `asChild` 及其余属性，修复使用 `asChild` 时错误将全部属性展开到图片组件的问题。
+
+**相关 PR：** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+## API 增强
+
+### Button 反馈 API 重构
+
+[Button](/docs/native/components/button) 的按压反馈 API 重构为统一的类型安全 `feedbackVariant` + `animation`，取代此前多属性拼写。
+
+**新能力：**
+
+```tsx
+import { Button } from "heroui-native";
+
+// 缩放 + 高亮（默认）
+<Button feedbackVariant="scale-highlight">Press me</Button>
+
+// 缩放 + 水波纹
+<Button feedbackVariant="scale-ripple">Press me</Button>
+
+// 仅缩放
+<Button feedbackVariant="scale">Press me</Button>
+
+// 自定义动画配置
+<Button
+  feedbackVariant="scale-highlight"
+  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
+>
+  Press me
+</Button>
+```
+
+`animation` 为按变体区分的联合类型，各反馈配置均有完整类型推导。
+
+`button.utils.ts` 中新增 `resolveAnimationObject` 与 `isAnimationDisabled`，集中解析动画属性。
+
+**相关 PR：** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## 依赖
+
+### 放宽对等依赖约束
+
+对等依赖版本约束已放宽为 caret（`^`）与范围（`>=`），替代偏紧的 tilde（`~`）或固定版本，便于使用方在较新依赖版本上解析，尤其 Expo SDK 55。
+
+**变更：**
+
+- `react-native-reanimated`：`~4.1.1` → `^4.1.1`（允许次版本更新）
+- `react-native-safe-area-context`：`~5.6.0` → `^5.6.0`
+- `react-native-svg`：`15.12.1` → `^15.12.1`
+- `react-native-worklets`：`0.5.1` → `>=0.5.1`
+
+无运行时逻辑变更——此前已满足约束的项目无需修改即可继续工作。
+
+**相关 PR：** [#306](https://github.com/heroui-inc/heroui-native/pull/306)
+
+## ⚠️ 破坏性变更
+
+### Button 反馈 API
+
+已移除 Button 上的 `pressableFeedbackVariant`、`pressableFeedbackHighlightProps`、`pressableFeedbackRippleProps`。请迁移到 `feedbackVariant` 与统一的 `animation`。
+
+**迁移：**
+
+更新所有 Button 反馈相关属性：
+
+```tsx
+// 之前
+<Button
+  pressableFeedbackVariant="highlight"
+  pressableFeedbackHighlightProps={{ color: "rgba(0,0,0,0.1)" }}
+>
+  Press me
+</Button>
+
+// 之后
+<Button
+  feedbackVariant="scale-highlight"
+  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
+>
+  Press me
+</Button>
+```
+
+**变体映射：**
+
+- `"highlight"` → `"scale-highlight"`（默认）
+- `"ripple"` → `"scale-ripple"`
+- `"none"` → `"scale"` 或 `"none"`
+
+**可选项：**
+
+- `"scale-highlight"` — 缩小 + 高亮遮罩（默认）
+- `"scale-ripple"` — 缩小 + 水波纹
+- `"scale"` — 仅缩小
+- `"none"` — 无反馈动画
+
+**相关 PR：** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #291](https://github.com/heroui-inc/heroui-native/issues/291)**：修复 `Select.Trigger` 的 `variant` 被 `className` 覆盖的问题。传入触发器的自定义类名现正确参与样式计算，不再被静默丢弃。
+
+- **[Issue #294](https://github.com/heroui-inc/heroui-native/issues/294)**：兼容 `react-native-worklets` 0.7.x 与 `react-native-reanimated` 4.2.x（Expo SDK 55）。放宽对等依赖约束，接受上述新版本而不产生解析告警。
+
+**相关 PR：**
+
+- [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+- [#306](https://github.com/heroui-inc/heroui-native/pull/306)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [SearchField](/docs/native/components/search-field) — 新组件文档：用法示例与 API 参考
+- [ListGroup](/docs/native/components/list-group) — 新组件文档：用法示例与 API 参考
+- [Slider](/docs/native/components/slider) — 新组件文档：用法示例与 API 参考
+- [Select](/docs/native/components/select) — 多选模式、触发器 className 修复与受控状态改进
+- [Button](/docs/native/components/button) — 更新反馈 API 文档：`feedbackVariant` 与 `animation`
+- [Avatar](/docs/native/components/avatar) — 修复 `asChild` 图片属性展开说明
+- [PressableFeedback](/docs/native/components/pressable-feedback) — 新增 `PressableFeedback.Scale` 子组件文档
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/rc-3.mdx b/apps/docs/content/docs/cn/native/releases/rc-3.mdx
new file mode 100644
index 0000000..df99120
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/rc-3.mdx
@@ -0,0 +1,358 @@
+---
+title: RC 3
+description: TagGroup、Menu、InputGroup 组件，Bottom Sheet Android 返回键修复，Expo 55 兼容
+github:
+  pull: 309
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 26 日</span>
+</div>
+
+RC 3 带来三个新组件：用于可选标签管理的 TagGroup、基于 Popover/Bottom Sheet 的下拉菜单 Menu，以及带自动测量前后缀槽位的装饰性输入 InputGroup。本版本还为所有基于 Bottom Sheet 的遮罩增加 Android 实体返回键支持；通过关键的 `combineStyles` 修复保留 Reanimated 动画样式绑定，实现 Expo 55 兼容；并包含若干依赖升级。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 RC 3 的全部改进！你可以探索 TagGroup、Menu、InputGroup，以及 Bottom Sheet 的 Android 返回键支持与各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### 新组件
+
+本版本新增 **3** 个组件：
+
+- **[TagGroup](/docs/native/components/tag-group)**：用于展示与管理可选标签的复合组件，支持可选移除、单选/多选及表单字段集成。
+- **[Menu](/docs/native/components/menu)**：下拉菜单系统，支持 Popover 与 Bottom Sheet 呈现、单选/多选、菜单项变体与按压动画反馈。
+- **[InputGroup](/docs/native/components/input-group)**：装饰性文本输入，前后缀槽位绝对定位并自动测量宽度，为输入区应用匹配内边距。
+
+#### TagGroup
+
+TagGroup 以复合组件模式渲染可选标签组，并支持可选移除。支持单选与多选、受控/非受控 API、两种视觉变体（default 与 surface）、三种尺寸、禁用态，以及与 Label、Description、FieldError 的完整表单集成。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="tag-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`TagGroup.List`、`TagGroup.Item`、`TagGroup.ItemLabel`、`TagGroup.ItemRemoveButton`
+- 单选/多选模式，受控/非受控 API
+- 两种视觉变体：`default` 与 `surface`
+- 三种尺寸：`sm`、`md`、`lg`
+- 单项禁用与 `disabledKeys`
+- 通过 `onRemove` 与 `TagGroup.ItemRemoveButton` 实现移除
+- `TagGroup.List` 上 `renderEmptyState` 渲染空状态
+- 与 Label、Description、FieldError、`isInvalid`、`isRequired` 的表单集成
+- `useTagGroup` 与 `useTagGroupItem` 供高级用法
+
+**用法：**
+
+```tsx
+import { TagGroup } from "heroui-native";
+
+export function BasicTagGroup() {
+  return (
+    <TagGroup>
+      <TagGroup.List>
+        <TagGroup.Item id="react">
+          <TagGroup.ItemLabel>React</TagGroup.ItemLabel>
+        </TagGroup.Item>
+        <TagGroup.Item id="vue">
+          <TagGroup.ItemLabel>Vue</TagGroup.ItemLabel>
+        </TagGroup.Item>
+        <TagGroup.Item id="svelte">
+          <TagGroup.ItemLabel>Svelte</TagGroup.ItemLabel>
+        </TagGroup.Item>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+
+export function RemovableTagGroup() {
+  const [items, setItems] = useState(["React", "Vue", "Svelte"]);
+
+  return (
+    <TagGroup onRemove={(keys) => setItems((prev) => prev.filter((i) => !keys.has(i)))}>
+      <TagGroup.List>
+        {items.map((item) => (
+          <TagGroup.Item key={item} id={item}>
+            <TagGroup.ItemLabel>{item}</TagGroup.ItemLabel>
+            <TagGroup.ItemRemoveButton />
+          </TagGroup.Item>
+        ))}
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+```
+
+完整文档与示例见 [TagGroup 组件页](/docs/native/components/tag-group)。
+
+**相关 PR：** [#309](https://github.com/heroui-inc/heroui-native/pull/309)
+
+#### Menu
+
+Menu 提供基于复合组件的下拉菜单，支持 Popover 与 Bottom Sheet 两种呈现。包含基于 Reanimated 的按压动画、单选/多选、菜单项变体（default 与 danger）、指示器样式及可配置 placement。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="menu"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`Menu.Trigger`、`Menu.Portal`、`Menu.Overlay`、`Menu.Content`、`Menu.Label`、`Menu.Group`、`Menu.Item`、`Menu.ItemTitle`、`Menu.ItemDescription`、`Menu.ItemIndicator`
+- 两种呈现：`popover` 与 `bottom-sheet`，placement 可配置（`top`、`bottom`、`left`、`right`）
+- `Menu.Group` 上通过 `selectedKeys`/`onSelectionChange` 实现单选/多选
+- 菜单项按压动画（缩放 + 背景色），Reanimated 实现，可通过 `animation` 自定义
+- 菜单项变体：`default` 与 `danger`
+- 指示器变体：`checkmark`、`dot` 或自定义内容
+- `Menu.Label` 用于分区标题
+- 分组级 `shouldCloseOnSelect` 控制
+
+**用法：**
+
+```tsx
+import { Menu } from "heroui-native";
+
+export function BasicMenu() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Open Menu</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Edit</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Duplicate</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item variant="danger">
+            <Menu.ItemTitle>Delete</Menu.ItemTitle>
+          </Menu.Item>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+
+export function MenuWithSections() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Actions</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Group selectionMode="single" selectedKeys={selected} onSelectionChange={setSelected}>
+            <Menu.Label>View</Menu.Label>
+            <Menu.Item id="list">
+              <Menu.ItemTitle>List View</Menu.ItemTitle>
+              <Menu.ItemIndicator />
+            </Menu.Item>
+            <Menu.Item id="grid">
+              <Menu.ItemTitle>Grid View</Menu.ItemTitle>
+              <Menu.ItemIndicator />
+            </Menu.Item>
+          </Menu.Group>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+完整文档与示例见 [Menu 组件页](/docs/native/components/menu)。
+
+**相关 PR：** [#312](https://github.com/heroui-inc/heroui-native/pull/312)
+
+#### InputGroup
+
+InputGroup 提供装饰性文本输入，`Prefix` 与 `Suffix` 子组件绝对定位，通过 `onLayout` 自动测量宽度并为 Input 应用匹配的水平内边距。`isDecorative` 布尔值可一次性处理装饰性附加内容的无障碍与指针事件样板；根级 `isDisabled` 通过上下文级联到所有子节点。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`InputGroup.Prefix`、`InputGroup.Suffix`、`InputGroup.Input`
+- 自动内边距：通过 `onLayout` 测量 Prefix/Suffix 宽度，自动作为 Input 的 `paddingLeft`/`paddingRight`
+- Prefix/Suffix 上 `isDecorative` 统一设置 `pointerEvents="none"`、`accessibilityElementsHidden` 与 `importantForAccessibility`
+- 根级 `isDisabled` 通过上下文级联（Prefix/Suffix 透明度与 pointer-events、Input 可编辑性）
+- `InputGroup.Input` 为直接透传——由使用方在 Input 上管理 `value`/`onChangeText`
+
+**用法：**
+
+```tsx
+import { InputGroup } from "heroui-native";
+
+export function SearchInput() {
+  return (
+    <InputGroup>
+      <InputGroup.Prefix isDecorative>
+        <SearchIcon />
+      </InputGroup.Prefix>
+      <InputGroup.Input placeholder="Search..." />
+      <InputGroup.Suffix isDecorative>
+        <ChevronIcon />
+      </InputGroup.Suffix>
+    </InputGroup>
+  );
+}
+
+export function DisabledInput() {
+  return (
+    <InputGroup isDisabled>
+      <InputGroup.Prefix isDecorative>
+        <LockIcon />
+      </InputGroup.Prefix>
+      <InputGroup.Input placeholder="Disabled input" />
+    </InputGroup>
+  );
+}
+```
+
+完整文档与示例见 [InputGroup 组件页](/docs/native/components/input-group)。
+
+**相关 PR：** [#313](https://github.com/heroui-inc/heroui-native/pull/313)
+
+## 组件改进
+
+### Bottom Sheet Android 返回键支持
+
+[Bottom Sheet](/docs/native/components/bottom-sheet) 共享容器现处理 Android 实体返回键：按下时关闭当前打开的 Bottom Sheet。`BackHandler` 仅在 Bottom Sheet 打开时注册，避免已关闭实例抢占事件。该修复全局作用于所有基于 Bottom Sheet 的组件。
+
+**涉及组件：**
+
+- [Bottom Sheet](/docs/native/components/bottom-sheet)
+- [Popover](/docs/native/components/popover)
+- [Select](/docs/native/components/select)
+
+实现使用 React Native 的 `BackHandler` API，在 iOS 上为空操作，无需分平台分支。
+
+**相关 PR：** [#308](https://github.com/heroui-inc/heroui-native/pull/308)
+
+### Slot 的 `combineStyles` 修复
+
+Slot 原语的 `combineStyles` 现返回样式数组，而不再使用 `StyleSheet.flatten`——后者会通过深拷贝样式对象破坏 Reanimated 的 `SharedValue` 与 `useAnimatedStyle` 绑定。
+
+**改进：**
+
+- `combineStyles` 通过返回数组保留 Reanimated 动画样式绑定
+- React Native 原生支持嵌套样式数组，对使用方行为无影响
+- 修复通过 Slot 原语组合的组件上的动画断裂问题
+
+**相关 PR：** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## 依赖
+
+### Expo 55 兼容
+
+依赖版本已更新以兼容 Expo SDK 55：
+
+- `uniwind`：1.2.7 → 1.3.2
+- `@gorhom/bottom-sheet`：^5 → ^5.2.8
+
+上述 `combineStyles` 修复是支持 Expo 55 的主要代码变更：此前 `StyleSheet.flatten` 会在新 SDK 下破坏 Reanimated 样式绑定。
+
+**相关 PR：** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**：解决 `FullWindowOverlay` 干扰 React Native 元素检查器的问题。
+
+- **[Issue #280](https://github.com/heroui-inc/heroui-native/issues/280)**：修复 Expo 55 下 Avatar 等依赖 Reanimated 的组件失效。`combineStyles` 曾通过 `StyleSheet.flatten` 破坏动画绑定；现改为返回样式数组以保留 `SharedValue` 与 `useAnimatedStyle`。
+
+**相关 PR：**
+
+- [#308](https://github.com/heroui-inc/heroui-native/pull/308)
+- [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [TagGroup](/docs/native/components/tag-group) — 新组件文档：用法示例与 API 参考
+- [Menu](/docs/native/components/menu) — 新组件文档：用法示例与 API 参考
+- [InputGroup](/docs/native/components/input-group) — 新组件文档：用法示例与 API 参考
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/rc-4.mdx b/apps/docs/content/docs/cn/native/releases/rc-4.mdx
new file mode 100644
index 0000000..35af0e5
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/rc-4.mdx
@@ -0,0 +1,225 @@
+---
+title: RC 4
+description: SubMenu 组件、Slider Output 组合重构、PressableFeedback 水波纹修复、Bottom Sheet 返回键处理修复
+github:
+  pull: 331
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 3 月 6 日</span>
+</div>
+
+RC 4 引入用于嵌套可展开菜单的 SubMenu 复合组件，配套弹簧动画展开/收起；重构 Slider Output，采用基于插槽的样式并支持 `textProps` 透传；为 `Menu.Group` 增加 `disallowEmptySelection`，实现类单选框行为。本版本还通过双层缓冲修复快速连按时 PressableFeedback 水波纹闪烁，并修复 Bottom Sheet 在 Android 上未尊重 `enablePanDownToClose` 的返回键处理。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 RC 4 的全部改进！你可以探索全新的 SubMenu 组件、改进后的 Slider Output，以及各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### SubMenu 组件
+
+[Menu](/docs/native/components/menu) 现通过新的 `SubMenu` 复合组件支持嵌套可展开子菜单。SubMenu 嵌套在 `Menu.Content` 内，按压后以弹簧动画展开/收起额外项，并带动指示器旋转。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="menu"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`SubMenu`、`SubMenu.Trigger`、`SubMenu.TriggerIndicator`、`SubMenu.Content`
+- 弹簧动画展开/收起与指示器旋转
+- 无头原语层：上下文、受控/非受控打开状态，以及无障碍属性（`role`、`aria-expanded`、`aria-disabled`）
+- 父级菜单协同：打开 SubMenu 时 popover 缩至 0.98、移除阴影，非 SubMenu 项淡出至 40% 不透明度并 `pointer-events-none`
+- 打开 SubMenu 时菜单内容切换为 `FadeOut` 退出动画，避免与缩放动画冲突
+- `useSubMenu` 钩子供高级场景使用
+
+**用法：**
+
+```tsx
+import { Menu, SubMenu } from "heroui-native";
+
+export function MenuWithSubMenu() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Open Menu</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Edit</Menu.ItemTitle>
+          </Menu.Item>
+          <SubMenu>
+            <SubMenu.Trigger>
+              <Menu.ItemTitle>More Options</Menu.ItemTitle>
+              <SubMenu.TriggerIndicator />
+            </SubMenu.Trigger>
+            <SubMenu.Content>
+              <Menu.Item>
+                <Menu.ItemTitle>Import</Menu.ItemTitle>
+              </Menu.Item>
+              <Menu.Item>
+                <Menu.ItemTitle>Export</Menu.ItemTitle>
+              </Menu.Item>
+            </SubMenu.Content>
+          </SubMenu>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+完整文档与示例见 [Menu 组件页](/docs/native/components/menu)。
+
+**相关 PR：** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
+
+## 组件改进
+
+### Slider Output 组合重构
+
+[Slider](/docs/native/components/slider) 的 Output 已重构为基于插槽的架构，包含 `container` 与 `text` 插槽，并新增 `textProps` 用于向内层文本元素透传属性。
+
+**改进：**
+
+- 基于插槽的样式：将 `output` 类拆为 `container` 与 `text`，新增 `classNames`（`classNames={{ container, text }}`）以便精细覆盖样式
+- 组合修复：仅在默认内容时渲染 `HeroText`；自定义子节点直接渲染，无额外文本包装
+- `Slider.Output` 新增 `textProps`，可向内部文本传递任意属性（如 `maxFontSizeMultiplier`）
+- 从样式模块导出 `OutputSlots` 类型供外部使用
+
+**相关 PR：** [#328](https://github.com/heroui-inc/heroui-native/pull/328)
+
+### Menu.Group 的 `disallowEmptySelection`
+
+[Menu](/docs/native/components/menu) 的 `Menu.Group` 现支持 `disallowEmptySelection`，在 `single` 选择模式下禁止取消最后一项选中，实现类单选框行为。
+
+**用法：**
+
+```tsx
+<Menu.Group
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+  disallowEmptySelection
+>
+  <Menu.Item id="list">
+    <Menu.ItemTitle>List View</Menu.ItemTitle>
+    <Menu.ItemIndicator />
+  </Menu.Item>
+  <Menu.Item id="grid">
+    <Menu.ItemTitle>Grid View</Menu.ItemTitle>
+    <Menu.ItemIndicator />
+  </Menu.Item>
+</Menu.Group>
+```
+
+**相关 PR：** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
+
+### Bottom Sheet 与 `enablePanDownToClose` 一致
+
+[Bottom Sheet](/docs/native/components/bottom-sheet) 现会在 Android 硬件返回键行为上正确尊重 `enablePanDownToClose`。此前即使 `enablePanDownToClose` 为 `false`，返回键仍会关闭 Bottom Sheet。
+
+**改进：**
+
+- `enablePanDownToClose` 透传至 `BottomSheetContentContainer`（默认 `true`）
+- 仅在 `isOpen` 与 `enablePanDownToClose` 均为 `true` 时注册 `BackHandler` 监听
+- `enablePanDownToClose={false}` 时不再可通过 Android 返回键关闭
+
+**相关 PR：** [#327](https://github.com/heroui-inc/heroui-native/pull/327)
+
+## ⚠️ 破坏性变更
+
+### Chip 组件尺寸
+
+[Chip](/docs/native/components/chip) 的尺寸变体已由固定高度改为基于内边距，以在较大无障碍字号下适配动态文字缩放。
+
+**迁移：**
+
+若自定义样式依赖此前的 `h-5`/`h-6`/`h-7` 高度，请改为新的内边距方案：
+
+```tsx
+// 之前 — 固定高度
+// Chip 使用 h-5（sm）、h-6（md）、h-7（lg）
+
+// 之后 — 基于内边距
+// Chip 使用 py-0.5（sm）、py-[3px]（md）、py-1（lg）
+// 圆角更新：rounded-xl → rounded-2xl / rounded-3xl
+```
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [Menu](/docs/native/components/menu) — SubMenu 文档：结构分解、用法示例、完整 API 参考及 `useSubMenu` 钩子说明
+- [Slider](/docs/native/components/slider) — 更新 Output 文档：基于插槽的样式与 `textProps`
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-0.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-0.mdx
new file mode 100644
index 0000000..1f6a377
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-0.mdx
@@ -0,0 +1,232 @@
+---
+title: v1.0.0
+description: LinkButton 组件、子菜单冲突处理、可选的 @gorhom/bottom-sheet 对等依赖、ThemeColorValue 品牌类型
+github:
+  pull: 347
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 3 月 19 日</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  height={430}
+  muted
+/>
+
+🎉 HeroUI Native 正式发布 v1.0.0——这是首个稳定版本，标志着库已从 beta 与候选发布阶段毕业，成为可用于生产环境的 React Native 应用基础。伴随这一里程碑，本版本还包含全新的 LinkButton 组件、子菜单冲突处理、可选的 `@gorhom/bottom-sheet` 对等依赖，以及针对 `useThemeColor` 的更强类型安全。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过我们的预览应用，在真机上体验 v1.0.0 的全部改进！你可以探索全新的 LinkButton 组件、改进后的子菜单行为，以及各项修复。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## 更新亮点
+
+### LinkButton 组件
+
+全新的 [LinkButton](/docs/native/components/button) 复合组件会渲染 ghost 变体按钮，且无高亮反馈，适用于「服务条款」「隐私政策」等行内链接式交互。它完全复用现有 Button 基础设施，并在内部强制 ghost 变体且关闭高亮反馈。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="link-button"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 复合子组件：`LinkButton.Label`，用于样式化文本内容
+- 内部强制 ghost 变体——不对外暴露 `variant` 属性
+- 通过 `resolveAnimationObject` 默认关闭高亮反馈
+- `h-auto p-0` 基础类移除默认按钮高度与内边距，便于行内使用
+- 合并使用方动画配置时仍保持 `highlight: false`
+
+**用法：**
+
+```tsx
+import { LinkButton } from "heroui-native";
+
+export function TermsLink() {
+  return (
+    <LinkButton onPress={() => openURL("https://example.com/terms")}>
+      <LinkButton.Label>Terms of Service</LinkButton.Label>
+    </LinkButton>
+  );
+}
+```
+
+**相关 PR：** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
+
+## 组件改进
+
+### 子菜单单开约束与点击背景关闭
+
+[Menu](/docs/native/components/menu) 子菜单系统已重构为按 ID 跟踪当前子菜单，而非简单布尔值，从而在同级子菜单之间强制「同时仅开一个」。子菜单打开时，会在菜单内容区域上方渲染可点击的背景层，用户点击外部即可关闭。
+
+**改进：**
+
+- `openSubMenuId` 取代布尔标记——同一时间只能有一个子菜单处于打开状态；打开新的会自动关闭上一个
+- 子菜单打开时，在菜单内容上渲染 `Pressable` 遮罩，支持点击关闭
+- 非当前打开的子菜单触发器通过新的 `isOtherSubMenuOpen` 样式变体获得 `opacity-40` 与 `pointer-events-none`
+- 打开的子菜单内容使用 `z-50`，关闭的为 `z-40`，避免层叠问题
+- 演示应用新增「两个子菜单」示例，展示同一菜单中的多个子菜单
+
+**相关 PR：** [#343](https://github.com/heroui-inc/heroui-native/pull/343)
+
+### Button Label 的 ref 类型修复
+
+`ButtonLabel` 的 ref 类型已从 `View` 更正为 `TextRef`，并从 `button.tsx` 中移除了未使用的 `View` 导入，使 ref 类型与实际渲染元素一致。
+
+**相关 PR：** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
+
+## API 增强
+
+### 用于 `useThemeColor` 的 `ThemeColorValue` 品牌类型
+
+`useThemeColor` 在单次取色调用时现返回 `ThemeColorValue` 品牌类型，误用数组解构时 IDE 会立即将类型标为 `never`。非空断言运算符（`!`）也已替换为安全的空值合并回退。
+
+**新行为：**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+// 正确 — 直接赋值
+const mutedColor = useThemeColor("muted");
+
+// 错误 — IDE 会立即标出 `never` 类型
+const [color] = useThemeColor("muted"); // color: never
+```
+
+`ThemeColorValue` 继承自 `string`，因此凡可接受 `string` 处均可赋值。现有调用点在运行时不受影响。`_colorValueBrand` 符号以 `declare const` 声明，无运行时体积。
+
+**相关 PR：** [#337](https://github.com/heroui-inc/heroui-native/pull/337)
+
+### 公开钩子 `useBottomSheetAwareHandlers`
+
+`useBottomSheetAwareHandlers` 现已作为公开 API 导出，便于在 Bottom Sheet 内显式控制键盘避让与 `Input`、`InputOTP` 的衔接。此前在 `Input` 与 `InputOTP` 上可用的隐式 `isBottomSheetAware` 属性已被取代。
+
+**用法：**
+
+```tsx
+import { useBottomSheetAwareHandlers, Input } from "heroui-native";
+
+export function BottomSheetInput() {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return <Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />;
+}
+```
+
+**相关 PR：** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+
+## ⚠️ 破坏性变更
+
+### Bottom Sheet 内的 `Input` 与 `InputOTP`
+
+已从 `Input` 与 `InputOTP` 移除 `isBottomSheetAware` 属性。此前 Bottom Sheet 内的键盘避让在底层自动处理；现在必须显式使用 `useBottomSheetAwareHandlers` 并自行传入处理器。这样可减轻 Input 组件负担，去掉隐式 `@gorhom/bottom-sheet` 导入，使该包对不使用 Bottom Sheet 的项目成为可选对等依赖。
+
+**迁移：**
+
+```tsx
+// 之前
+<Input isBottomSheetAware placeholder="Type here..." />
+
+// 之后
+import { useBottomSheetAwareHandlers } from "heroui-native";
+
+const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+<Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />
+```
+
+凡在 `BottomSheet` 内渲染的 `Input` 或 `InputOTP` 均需按此调整；在 Bottom Sheet 外使用的组件不受影响。
+
+**相关 PR：** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #330](https://github.com/heroui-inc/heroui-native/issues/330)**：修复 `Input` 在模块顶层无条件导入 `@gorhom/bottom-sheet` 的问题，即使 `isBottomSheetAware` 为 `false`。现通过可选的 `try/catch` 包装懒加载该包，不使用 Bottom Sheet 的项目无需再安装它。
+
+- **[Issue #340](https://github.com/heroui-inc/heroui-native/issues/340)**：修复子菜单内容出现在同级子菜单触发器后方的问题。子菜单系统现按 ID 跟踪活动子菜单、强制单开，并应用正确的 z-index 分层（打开 `z-50`，关闭 `z-40`）。
+
+**相关 PR：**
+
+- [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+- [#343](https://github.com/heroui-inc/heroui-native/pull/343)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [LinkButton](/docs/native/components/link-button) — LinkButton 复合组件文档：结构分解、用法示例与 API 参考
+- [Menu](/docs/native/components/menu) — 更新子菜单文档：单开约束与点击背景关闭行为
+- [Input](/docs/native/components/input) — 更新 Bottom Sheet 用法示例，采用 `useBottomSheetAwareHandlers` 模式
+- [InputOTP](/docs/native/components/input-otp) — 同上，Bottom Sheet 示例采用 `useBottomSheetAwareHandlers`
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-1.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-1.mdx
new file mode 100644
index 0000000..dffc4f9
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-1.mdx
@@ -0,0 +1,145 @@
+---
+title: v1.0.1
+description: Toast 竞态修复、使用 disabled 修饰符的禁用态样式、背景层样式变量 backdrop
+github:
+  pull: 360
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 4 月 1 日</span>
+</div>
+
+HeroUI Native v1.0.1 是一次侧重可靠性与开发者体验的补丁版本。它修复了 Toast 提供程序中导致动画值过期的竞态条件，将七个组件的禁用态样式改为使用原生 `disabled:` 修饰符，并为主题系统新增 `--backdrop` 变量，供遮罩类组件使用。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 v1.0.1 的全部改进！你可以查看 Toast 修复、改进后的禁用态样式以及新的背景层变量。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## API 增强
+
+### `--backdrop` 主题变量
+
+主题系统新增顶层样式变量 `--backdrop`，为 Dialog、Bottom Sheet 等遮罩组件背后的变暗层提供专用色令牌。默认值为 `oklch(0% 0 0 / 20%)`，呈现轻微但可见的背景变暗效果。
+
+**新能力：**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+// Dialog 与 Bottom Sheet 遮罩现自动使用 bg-backdrop
+<Dialog>
+  <Dialog.Content>
+    {/* 内容绘制在主题化背景层之上 */}
+  </Dialog.Content>
+</Dialog>
+```
+
+`--backdrop` 已纳入所有内置主题的浅色与深色模式，对应的 Tailwind 工具类 `bg-backdrop` 也可用于自定义组件样式。
+
+**相关 PR：** [#366](https://github.com/heroui-inc/heroui-native/pull/366)
+
+## 样式修复
+
+### 禁用态修饰符
+
+七个组件的禁用态样式已改为使用 `disabled:` 前缀修饰符，而非无条件应用样式。这样可确保 `opacity-disabled`、`pointer-events-none` 等仅在组件真实处于禁用态时生效，并尊重来自 Uniwind 的原生 `disabled` 修饰符。
+
+**涉及组件：**
+
+- [Button](/docs/native/components/button)
+- [Checkbox](/docs/native/components/checkbox)
+- [Input](/docs/native/components/input)
+- [Menu](/docs/native/components/menu)
+- [Switch](/docs/native/components/switch)
+- [Tabs](/docs/native/components/tabs)
+- [TagGroup](/docs/native/components/tag-group)
+
+所有 `isDisabled` 变体类现均使用 `disabled:` 前缀（例如 `disabled:opacity-disabled disabled:pointer-events-none`），正确限定在禁用伪状态，并在禁用态动态切换时消除样式冲突。
+
+**相关 PR：** [#361](https://github.com/heroui-inc/heroui-native/pull/361)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #359](https://github.com/heroui-inc/heroui-native/issues/359)**：修复 Toast 提供程序中 `total` SharedValue 与实际 Toast 数量可能不同步的竞态。原先手动增减在 `hide` 与 `show` 同一帧执行、或自动消失与手动隐藏竞速时，易出现闭包陈旧导致不一致。`total` 现通过 `useEffect` 由 `toasts.length` 派生，使透明度、缩放、translateY 等插值始终反映真实数量。
+
+- **[Issue #356](https://github.com/heroui-inc/heroui-native/issues/356)**：修复在 `isDisabled` 为 true 时禁用样式被无条件应用、阻碍开发者主题化或自定义禁用外观的问题。上述七个组件均已改为 `disabled:` 前缀，将样式正确限定在禁用伪状态。
+
+**相关 PR：**
+
+- [#360](https://github.com/heroui-inc/heroui-native/pull/360)
+- [#361](https://github.com/heroui-inc/heroui-native/pull/361)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [Colors](/docs/native/getting-started/colors) — 在颜色参考中补充新的 `--backdrop` 变量
+- [Theming](/docs/native/getting-started/theming) — 主题指南中增加 `--backdrop` 变量说明
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-2.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-2.mdx
new file mode 100644
index 0000000..8c342b2
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-2.mdx
@@ -0,0 +1,197 @@
+---
+title: v1.0.2
+description: PressableFeedback 与 Surface 的 asChild 插槽模式、Portal 无障碍 modal 属性、Button Android 变体修复、Input 与 Select 样式微调
+github:
+  pull: 380
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 4 月 15 日</span>
+</div>
+
+HeroUI Native v1.0.2 为 PressableFeedback 与 Surface 引入 `asChild` 插槽模式，为所有基于 Portal 的遮罩组件增加 VoiceOver 模态包容支持，并修复 Android 上 Button 某变体的样式问题。本版本还微调了 Input 与 Select 的视觉效果，并在 RadioGroup 文档中内嵌 API 参考表。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 抢先体验
+
+通过预览应用在真机上体验 v1.0.2 的全部改进！你可以探索新的 `asChild` 插槽模式、Portal 无障碍改进、Android 上更可靠的 Button 行为，以及优化后的 Input 与 Select 样式。
+
+### 环境要求
+
+请确保手机已安装最新版本的 [Expo Go](https://expo.dev/go)。
+
+### 如何访问
+
+**方式一：扫描二维码**
+
+使用手机相机或 Expo Go 应用扫描：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go 二维码"
+  />
+</div>
+
+> **Android 用户请注意：** 若使用系统相机或其他扫码应用会跳转到浏览器并出现 404，请先打开 Expo Go，使用其内置扫码功能扫描。
+
+**方式二：点击链接**
+
+**[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+
+若设备已安装 Expo Go，将自动在其中打开应用。
+
+## API 增强
+
+### PressableFeedback 与 Surface 的 `asChild` 插槽模式
+
+[PressableFeedback](/docs/native/components/pressable-feedback) 与 [Surface](/docs/native/components/surface) 现支持 `asChild` 属性，采用 Slot 模式实现多态渲染。当 `asChild` 为 `true` 时，组件会把自身行为与样式合并到单个子元素上，而不再额外包一层节点。
+
+**PressableFeedback** 使用 `Animated.createAnimatedComponent(Slot.Pressable)`，将按压处理与动画样式合并到子元素。**Surface** 使用 `Slot.View`，将表面样式（海拔、背景、`className`）合并到子元素。
+
+**新能力：**
+
+```tsx
+import { PressableFeedback, Surface } from "heroui-native";
+
+// PressableFeedback 将按压处理合并到子元素
+<PressableFeedback asChild onPress={() => console.log("pressed")}>
+  <MyCustomComponent />
+</PressableFeedback>
+
+// Surface 将表面样式合并到子元素
+<Surface asChild elevation={2}>
+  <MyCustomCard />
+</Surface>
+```
+
+`asChild` 默认为 `false`，保持既有行为，无需迁移。启用 `asChild` 时子节点须为单个 React 元素。两处实现均遵循代码库中已有的 Slot 原语模式。
+
+**相关 PR：** [#380](https://github.com/heroui-inc/heroui-native/pull/380)
+
+### Portal 组件的 `unstable_accessibilityContainerViewIsModal`
+
+所有基于 Portal 的遮罩组件新增 `unstable_accessibilityContainerViewIsModal` 属性，用于控制 iOS VoiceOver 是否将遮罩窗口视为模态容器。启用后，VoiceOver 焦点限制在遮罩内，无法导航到背后内容。
+
+**支持的组件：**
+
+- [BottomSheet](/docs/native/components/bottom-sheet)（`BottomSheet.Portal`）
+- [Dialog](/docs/native/components/dialog)（`Dialog.Portal`）
+- [Menu](/docs/native/components/menu)（`Menu.Portal`）
+- [Popover](/docs/native/components/popover)（`Popover.Portal`）
+- [Select](/docs/native/components/select)（`Select.Portal`）
+- [Toast](/docs/native/components/toast)（`ToastProvider`）
+
+**新能力：**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+<Dialog>
+  <Dialog.Portal unstable_accessibilityContainerViewIsModal>
+    <Dialog.Content>
+      {/* 在 iOS 上 VoiceOver 焦点限制在此遮罩内 */}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+该属性默认为 `false`，保持既有行为。标记为 `unstable` 是因为它直接映射到 `react-native-screens` 中 `FullWindowOverlay` 的原生 `accessibilityViewIsModal`，未来可能随该库版本变化。
+
+**相关 PR：** [#383](https://github.com/heroui-inc/heroui-native/pull/383)
+
+## 样式修复
+
+### Input 与 Select 视觉微调
+
+优化了 [Input](/docs/native/components/input) 与 [Select](/docs/native/components/select) 的视觉样式，使外观更干净、比例更协调。
+
+**调整：**
+
+- **Input**：边框宽度由 `border-2`（2px）改为 `border-[1.5px]`，边框更轻、不抢眼
+- **Select**：触发器垂直内边距由 `py-3.5` 改为 `py-3`，布局更紧凑
+
+以上均为纯视觉调整，无 API 或行为变更。建议在 iOS 与 Android 上做视觉回归确认。
+
+**相关 PR：** [#381](https://github.com/heroui-inc/heroui-native/pull/381)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #363](https://github.com/heroui-inc/heroui-native/issues/363)**：修复 Android 上 Button 的 outline 变体在通过条件属性切换到其他变体时边框仍残留的问题。Android 上的 React Native 在变体切换时有时会保留 `borderWidth`。除 `outline` 外的所有按钮变体现均包含显式 `border-0` 类，确保变体切换时将 `borderWidth` 重置为 `0`。
+
+- **[Issue #357](https://github.com/heroui-inc/heroui-native/issues/357)**：响应在 Card 上支持 `asChild` 以实现可按压卡片模式的诉求。PressableFeedback 与 Surface 上的新 `asChild` 插槽模式，使开发者可将按压与表面样式合并到单个子元素，无需额外包装节点。
+
+**相关 PR：**
+
+- [#370](https://github.com/heroui-inc/heroui-native/pull/370)
+- [#380](https://github.com/heroui-inc/heroui-native/pull/380)
+
+## 文档
+
+### RadioGroup 内联 API 参考
+
+[RadioGroup](/docs/native/components/radio-group) 文档现于页面内嵌 `Radio`、`Radio.Indicator`、`Radio.IndicatorThumb` 的完整 API 表，读者无需再跳转到单独的 Radio 文档即可了解在 `RadioGroup.Item` 中组合时的可用属性。
+
+**改进：**
+
+- `Radio`、`Radio.Indicator`、`Radio.IndicatorThumb` 的完整属性表内嵌展示
+- 补充 `RadioRenderProps`、`RadioRootAnimation`、`RadioIndicatorThumbAnimation` 类型说明
+- 将外链式 Markdown 链接统一为内联代码格式以保持一致性
+
+**相关 PR：** [#384](https://github.com/heroui-inc/heroui-native/pull/384)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [RadioGroup](/docs/native/components/radio-group) — 内联 API 表：`Radio`、`Radio.Indicator`、`Radio.IndicatorThumb`
+- [PressableFeedback](/docs/native/components/pressable-feedback) — 补充 `asChild` 属性说明
+- [Surface](/docs/native/components/surface) — 补充 `asChild` 属性说明
+- [BottomSheet](/docs/native/components/bottom-sheet) — 补充 `unstable_accessibilityContainerViewIsModal` 说明
+- [Dialog](/docs/native/components/dialog) — 同上
+- [Menu](/docs/native/components/menu) — 同上
+- [Popover](/docs/native/components/popover) — 同上
+- [Select](/docs/native/components/select) — 同上
+- [Toast](/docs/native/components/toast) — 同上
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-3.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-3.mdx
new file mode 100644
index 0000000..6c8bc7a
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-3.mdx
@@ -0,0 +1,233 @@
+---
+title: v1.0.3
+description:
+  全新 Text 排版组件、ScrollShadow 反向列表支持、Tabs RTL 指示器修复、Avatar alt 属性可选化、Select 指示器统一、表单字段样式微调
+github:
+  pull: 400
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 5 月 11 日</span>
+</div>
+
+HeroUI Native v1.0.3 引入全新的 `Text` 排版基元，提供面向标题、段落与内联代码的复合 API；同时为 `ScrollShadow` 在反向列表下的渲染、`Tabs` 指示器在 RTL 布局下的对齐、以及自定义 `Select.TriggerIndicator` `children` 时的动画问题带来重要修复。本版本还对 `Button`、`Chip`、`Input` 的视觉样式进行了微调，将 `Avatar` 的 `alt` 属性改为可选，并修正 `TextField` 与 `SearchField` 的内部内边距行为。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 真机体验
+
+<NativeTryOnDevice />
+
+## 新增
+
+### 新组件
+
+本版本新增 **1 个** 排版组件：
+
+- **[Text](/docs/native/components/text)**：带语义 `type` 变体的排版基元组件，附带 `Heading`、`Paragraph`、`Code` 子组件。（[文档](/docs/native/components/text)）
+
+#### Text
+
+`Text` 组件是一个排版基元，通过语义化预设渲染样式化文本。它提供 `Text.Heading`、`Text.Paragraph`、`Text.Code` 等子组件构成的复合 API，并在 `tailwind-variants` 基础上叠加互不耦合的 `align`、`color`、`weight`、`truncate` 属性，使排版可以组合复用，无需在每个调用点重复定义样式。
+
+<NativeVideoPlayerView
+  target="component"
+  slug="text"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-dark.mp4"
+/>
+
+**特性：**
+
+- 语义化 `type` 变体：`h1`–`h6`、`body`、`body-sm`、`body-xs`、`code`
+- `Text.Heading` 自动设置 `accessibilityRole="header"`，并将 `type` 收窄为标题级别
+- `Text.Paragraph` 将 `type` 收窄为正文变体，适合长文本可读性
+- `Text.Code` 渲染为 chip 样式的内联等宽文本，采用平台合适的 `fontFamily`（iOS 为 Menlo，其他平台为 `monospace`）
+- RTL 感知的 `align` 属性，支持 `start`、`center`、`end`、`justify`（justify 仅 iOS 生效）
+- 语义化 `color` 预设（`default`、`muted`），其他主题色可通过 `className` 外挂
+- `weight` 覆盖：借助 `tailwind-merge` 始终优先于 `type` 暗含的字重
+- `truncate` 布尔属性：等价于 `numberOfLines={1}`；显式 `numberOfLines` 始终优先
+
+**用法：**
+
+```tsx
+import { Text } from "heroui-native";
+import { View } from "react-native";
+
+export function Example() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Text.Heading type="h1">Welcome</Text.Heading>
+      <Text.Heading type="h3">Getting Started</Text.Heading>
+      <Text.Paragraph>
+        This is a body paragraph rendered with the Text component.
+      </Text.Paragraph>
+      <Text.Paragraph color="muted" type="body-sm">
+        Smaller supporting text for captions or footnotes.
+      </Text.Paragraph>
+      <Text.Code>npm install heroui-native</Text.Code>
+    </View>
+  );
+}
+```
+
+完整文档与示例见 [Text 组件页面](/docs/native/components/text)。
+
+**相关 PR：** [#400](https://github.com/heroui-inc/heroui-native/pull/400)
+
+## 组件改进
+
+### ScrollShadow 反向子列表支持
+
+[ScrollShadow](/docs/native/components/scroll-shadow) 现已正确处理反向的可滚动子组件，如 `<FlatList inverted>` 或 `<FlashList inverted>`。
+
+**改进点：**
+
+- `ScrollShadowRoot` 现会读取可滚动子组件上的 `inverted` 属性，沿用既有的 `childHorizontal` 自动检测模式
+- 内部交换驱动各视觉边缘的动画样式，使阴影渲染到正确的一侧
+- 公共 API 无变化——仅当子组件设置 `inverted={true}` 时启用该修复，此前在此情况下渐变会出现在错误的边缘
+
+此前，包裹反向列表时渐变阴影会渲染在顶部，而可滚动内容位于其下；即便仍有更多内容也不会出现底部阴影。修复后，反向 feed、聊天列表等反向滚动表面上的指示器方向已正确。
+
+**相关 PR：** [#398](https://github.com/heroui-inc/heroui-native/pull/398)
+
+### Tabs RTL 指示器对齐
+
+[Tabs](/docs/native/components/tabs) 的指示器在 React Native 处于 RTL 模式时定位现已正确。
+
+**改进点：**
+
+- 通过 tabs 测量上下文跟踪标签条的宽度
+- 固定布局使用 `Tabs.List` 的布局宽度
+- 滚动布局使用 `Tabs.ScrollView` 的内容宽度
+- 仅当 `I18nManager.isRTL` 启用时，对指示器的 `translateX` 进行镜像
+
+指示器使用绝对定位 `left` 锚点配合测量得到的 `translateX`。在 RTL 模式下，React Native 会自动翻转绝对锚点，但所测量的 transform 仍需手动镜像——本次修复内部完成了这一处理。固定与滚动两类标签列表均已修复，且公共 API 未变。
+
+**相关 PR：** [#396](https://github.com/heroui-inc/heroui-native/pull/396)
+
+### Select 触发器指示器渲染统一
+
+[Select](/docs/native/components/select) 的 `Select.TriggerIndicator` 现无论使用默认图标还是自定义 `children`，都会一致地应用展开/收起的旋转动画。
+
+**改进点：**
+
+- 自定义 `children` 现可获得与默认图标相同的动画容器样式
+- 通过 `children ?? <ChevronDownIcon />` 将 `ChevronDownIcon` 作为回退渲染
+- 将此前分散的渲染分支合并为统一的渲染路径
+
+此前，向 `Select.TriggerIndicator` 传入自定义 `children` 会绕过旋转动画，导致开合时指示器保持静止。统一分支确保旋转动画始终生效，且公共 API 未变。
+
+**相关 PR：** [#409](https://github.com/heroui-inc/heroui-native/pull/409)
+
+## API 增强
+
+### Avatar 的 `alt` 属性变为可选
+
+[Avatar](/docs/native/components/avatar) 的 `alt` 属性现已可选，默认为 `'Avatar'`，在保留无障碍支持的同时，减少装饰性或语境明确场景下的样板代码。
+
+**新能力：**
+
+```tsx
+import { Avatar } from "heroui-native";
+
+<Avatar>
+  <Avatar.Image source={{ uri: "https://example.com/avatar.jpg" }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>;
+```
+
+显式传入 `alt` 的既有代码继续正常工作——该属性仅在缺省时获得一个合理的默认值。`RootProps` 类型现已反映为 `alt?: string`，并通过 JSDoc 标注 `@default 'Avatar'`，组件文档同步更新。
+
+**相关 PR：** [#404](https://github.com/heroui-inc/heroui-native/pull/404)
+
+## 样式修复
+
+### Button、Chip、Input 样式微调
+
+对 [Button](/docs/native/components/button)、[Chip](/docs/native/components/chip)、[Input](/docs/native/components/input) 的尺寸与色彩样式进行了微调，统一改用 Tailwind 工具类与语义化的 soft 颜色令牌。
+
+**修复：**
+
+- **Button**：尺寸改用 Tailwind 高度工具类（`h-10`、`h-12`、`h-14`），不再使用任意像素值；`sm` 高度由 36px 调整为 40px，提升触控目标的人体工学
+- **Chip**：`md`/`lg` 的垂直内边距微调（`py-[3px]` → `py-1`，`py-1` → `py-1.5`），间距更协调
+- **Chip**：soft 变体改用语义化 `bg-{color}-soft` 令牌，取代基于不透明度的 `bg-{color}/15` 背景
+- **Input**：由 `py-3.5` 改为 `min-h-12`，无论内容如何字段都保持稳定高度
+- **Input**：primary 变体的边框现正确使用 `border-field-border` 令牌，而非 `border-field`
+
+Button `sm` 尺寸（+4px）与 Chip `md`/`lg` 内边距上的像素级差异建议进行视觉回归确认。无 API 变更——仅更新了 `button.styles.ts`、`chip.styles.ts`、`input.styles.ts` 中的样式令牌。
+
+**相关 PR：** [#406](https://github.com/heroui-inc/heroui-native/pull/406)
+
+### TextField 与 SearchField 内部内边距修复
+
+[TextField](/docs/native/components/text-field) 与 [SearchField](/docs/native/components/search-field) 不再对嵌套的 `Label`、`Description`、`FieldError` 施加额外的水平内边距。
+
+**修复：**
+
+- `TextField` 现在向其 `FormFieldContext` 提供 `hasFieldPadding: false`
+- `SearchField` 现在向其 `FormFieldContext` 提供 `hasFieldPadding: false`
+- 渲染在上述字段内的 `Label`、`Description`、`FieldError` 不再继承额外的 `px-1.5` 侧边距
+- 所有表单字段容器（`ControlField`、`RadioGroup`、`TagGroup` 已采用 `hasFieldPadding: false`）的视觉对齐现已统一
+
+此次变更仅涉及两处为 `FormFieldContext` 提供值的 `useMemo`。如果你此前依赖这一非预期的内部内边距，可通过为受影响的子组件添加 `className="px-1.5"` 恢复原有间距。
+
+**相关 PR：** [#407](https://github.com/heroui-inc/heroui-native/pull/407)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #334](https://github.com/heroui-inc/heroui-native/issues/334)**：修复 RTL 布局下 `Tabs.Indicator` 的定位错乱。指示器以绝对定位 `left` 锚点配合测量的 `translateX` 实现位移；在 RTL 模式下 React Native 会自动翻转锚点，但测量得到的 transform 仍需手动镜像。tabs 测量上下文现会跟踪标签条宽度，仅当 `I18nManager.isRTL` 启用时镜像 `translateX`，固定与滚动两类标签列表均已修复。
+- **[Issue #393](https://github.com/heroui-inc/heroui-native/issues/393)**：修复 `ScrollShadow` 忽略子组件 `inverted` 属性的问题。`ScrollShadowRoot` 现会读取可滚动子组件上的 `inverted`（沿用既有的 `childHorizontal` 自动检测），并交换驱动各视觉边缘的动画样式，使反向 feed 与聊天式列表上的渐变出现在正确的一侧。
+
+**相关 PR：**
+
+- [#396](https://github.com/heroui-inc/heroui-native/pull/396)
+- [#398](https://github.com/heroui-inc/heroui-native/pull/398)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [Text](/docs/native/components/text) — 新组件文档，含结构、用法与完整 API 参考
+- [Avatar](/docs/native/components/avatar) — `alt` 属性记为可选，默认值 `'Avatar'`
+- [组件总览](/docs/native/components) — 在既有分类外新增 Typography 分类
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-4.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-4.mdx
new file mode 100644
index 0000000..fe45507
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-4.mdx
@@ -0,0 +1,286 @@
+---
+title: v1.0.4
+description:
+  Typography 组件替代 Text、调整后的柔和前景色主题令牌与可选鲜亮配色、iOS 原生模态偏移说明、示例应用升级至 Expo 56 / React Native 0.85
+github:
+  pull: 420
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 5 月 26 日</span>
+</div>
+
+HeroUI Native v1.0.4 将排版基元 `Text` 重命名为 `Typography`，让出 React Native 自身的 `Text` 名称，同时更贴近语义化排版用法；既有的 `Text` 导出保留为弃用别名，可平滑升级。本版本还在 Alert、Avatar、Button、Chip、Toast 中调整了 soft 前景色令牌，使其在 soft 背景上具备更好的对比度；新增可选的 `heroui-native/styles/vibrant` 配色；为 Menu、Popover、Select 补充 iOS 原生模态偏移的处理说明；并将示例应用升级到 Expo 56 / React Native 0.85。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 真机体验
+
+<NativeTryOnDevice />
+
+## 新增
+
+### Typography 组件（由 `Text` 重命名而来）
+
+库内的排版基元已从 `Text` 重命名为 `Typography`，避免与 React Native 内建的 `Text` 重名，并更准确地体现其作为语义化排版系统的定位。组件的 API、变体与行为保持不变——只是公开名称发生变化。
+
+```tsx
+import { Typography } from "heroui-native";
+import { View } from "react-native";
+
+export function Example() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Typography.Heading type="h1">Welcome</Typography.Heading>
+      <Typography.Heading type="h3">Getting Started</Typography.Heading>
+      <Typography.Paragraph>
+        This is a body paragraph rendered with the Typography component.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" type="body-sm">
+        Smaller supporting text for captions or footnotes.
+      </Typography.Paragraph>
+      <Typography.Code>npm install heroui-native</Typography.Code>
+    </View>
+  );
+}
+```
+
+**变更要点：**
+
+- 主导出改为 `Typography`，子组件为 `Typography.Heading`、`Typography.Paragraph`、`Typography.Code`
+- 新增 `typographyClassNames` 样式 API 与 `Typography*` 类型别名，取代原先的 `Text*` 命名
+- 既有的 `Text`、`textClassNames` 与 `Text*` 类型作为**弃用**的重导出保留以兼容旧代码
+- 组件目录中的示例页由 `text` 重命名为 `typography`
+- JSDoc 与组件文档更新为引用 Typography 以及新的文档 URL
+
+<Callout type="info">
+  **无需迁移。** 既有的 `import { Text } from "heroui-native"` 通过弃用重导出仍然可用。请在未来某个大版本移除弃用别名之前，按你的节奏迁移到 `Typography`。
+</Callout>
+
+**相关 PR：** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
+
+### 鲜亮主题配色（可选）
+
+新增可选的 `heroui-native/styles/vibrant` 样式表，适合希望在 soft 变体上保持更饱和品牌色的应用。它在保留调整后的柔和前景令牌带来的可读性改进的同时，仍为 soft 背景上的图标与文字保留较高的色彩饱和度。
+
+**用法：**
+
+```ts
+// 默认调整后的柔和前景配色
+import "heroui-native/styles";
+
+// 或者，启用鲜亮配色
+import "heroui-native/styles";
+import "heroui-native/styles/vibrant";
+```
+
+在引入基础样式之后再引入 `heroui-native/styles/vibrant`，即可用更饱和的取值覆盖柔和前景令牌。无需修改任何组件代码即可启用。
+
+**相关 PR：** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+## 组件改进
+
+### 多组件柔和前景色调整
+
+[Alert](/docs/native/components/alert)、[Avatar](/docs/native/components/avatar)、[Button](/docs/native/components/button)、[Chip](/docs/native/components/chip)、[Toast](/docs/native/components/toast) 现使用新的 `*-soft-foreground` 主题令牌渲染 soft 背景上的标签与图标，呈现更好的对比度，并在亮色与暗色主题下保持更统一的视觉效果。
+
+**改进点：**
+
+- `theme.css` 中通过 `color-mix` 计算柔和前景令牌（`accent-soft-foreground`、`success-soft-foreground`、`warning-soft-foreground`、`danger-soft-foreground`、`default-soft-foreground`），提升 soft 背景上的可读性
+- Alert、Avatar、Button、Chip、Toast 的样式（及其内部 hooks）改为使用新的柔和前景令牌，不再直接使用 `text-accent`、`text-success` 等原始语义色
+- 新增可选的 `heroui-native/styles/vibrant` 导出，为希望保留饱和品牌色的应用保留更鲜亮的 soft 变体外观
+- 示例应用中 Alert、Avatar、Button、Chip、Toast 的演示同步更新以匹配新的取色方式
+
+组件属性与公开 API 均无变化——仅 soft 变体的取色发生变化。沿用默认主题的应用将开箱获得 soft 变体上更柔和、可读性更佳的图标与标签颜色。
+
+**相关 PR：** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+### TextArea 垂直内边距修复
+
+[TextArea](/docs/native/components/text-area) 现已应用合适的内部垂直内边距，多行内容不再紧贴输入区上边缘。
+
+**改进点：**
+
+- `TextArea` 现使用 `h-32 py-2`，提供一致的内部间距
+- 无 API 变更——仅为组件内的样式调整
+
+**相关 PR：** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## API 增强
+
+### `useThemeColor` 令牌更新
+
+[`useThemeColor`](/docs/native/hooks/use-theme-color) hook 新增表面色与柔和色相关令牌，并对遮罩背景令牌进行了重命名以更清晰表达语义。
+
+**新能力：**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+const colors = useThemeColor([
+  "default-soft",
+  "default-soft-foreground",
+  "surface-foreground",
+  "backdrop",
+]);
+```
+
+**变更：**
+
+- 新增 `default-soft` 与 `default-soft-foreground` 令牌
+- 新增表面前景色令牌（如 `surface-foreground`），可显式取用表面文字颜色
+- 将 `overlay-backdrop` 重命名为 `backdrop`，与底层 CSS 变量命名保持一致
+
+如果你使用了已移除的 `useThemeColor` 键（`on-surface-*`）或旧的 `overlay-backdrop` 键，请改用更新后的令牌名。组件属性与视觉默认值保持不变。
+
+**相关 PR：** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+## 依赖
+
+### `@gorhom/bottom-sheet` 对等依赖范围更新
+
+`@gorhom/bottom-sheet` 的对等依赖范围由 `^5.2.8` 升级到 `^5.2.9`。如果你的应用使用 HeroUI Native 的 [BottomSheet](/docs/native/components/bottom-sheet)（或 `Menu` / `Popover` / `Select` 配合 `presentation="bottom-sheet"`），请确保安装兼容版本：
+
+```bash
+npm i @gorhom/bottom-sheet@^5.2.9
+```
+
+这是本版本对消费者唯一的对等依赖变更。库的 `react`（`>=19.0.0`）与 `react-native`（`>=0.81.0`）对等依赖范围保持不变。
+
+**相关 PR：** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+### 示例应用升级至 Expo 56 / React Native 0.85
+
+仓库内的示例应用升级到了最新的 Expo 与 React Native 工具链。这不会直接影响库的消费者，但为运行示例的贡献者带来收益：
+
+- Expo `56`
+- React Native `0.85.3`
+- React `19.2.3`
+- React Native Reanimated `4.3.1`
+- `react-native-worklets` `0.8.3`
+- Uniwind `^1.6.3`
+
+本次升级还包含以下整理：
+
+- 重写 `metro.config.js`，将对等依赖解析锁定到示例的 `node_modules`，修复当 `uniwind` 或 `react` 从 workspace 根解析出两份副本时 Hermes 抛出的「Maximum call stack size exceeded」崩溃
+- 在 input-otp 与展示页中以 `StyleSheet.absoluteFill` 替换已弃用的 `StyleSheet.absoluteFillObject`
+- 将 `useFocusEffect` / `useHeaderHeight` 的导入迁移至 `expo-router`
+- 移除未使用的 `example/src/components/safe-area-view.tsx`、`eas.json` 以及陈旧的 `newArchEnabled` / `edgeToEdgeEnabled` 标记
+- 示例应用的 slug/bundle 重命名为 `heroui-native-oss`；调整 Android 上 `WithStateToggle` 的内边距
+
+**相关 PR：** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## 文档
+
+### Menu、Popover、Select 的 iOS 原生模态偏移说明
+
+[Menu](/docs/native/components/menu)、[Popover](/docs/native/components/popover)、[Select](/docs/native/components/select) 文档新增**原生模态（iOS）**章节，解释当触发器位于以原生模态（`presentation: "modal" | "formSheet" | "pageSheet"`）呈现的页面内时，遮罩内容为何会向上偏移渲染，以及如何补偿。
+
+**改进点：**
+
+- 各组件文档说明了 Fabric / `FullWindowOverlay` 的坐标不一致：触发器坐标相对于模态原点，而遮罩锚定在窗口
+- 文档化了配合 `react-native-safe-area-context` 中 `useSafeAreaInsets` 使用的 `offset={insets.top}` 推荐方案
+- 提供示例应用中相关文件（`popover-native-modal.tsx`、`select-native-modal.tsx`）的链接，便于查阅完整用法
+
+**用法示例：**
+
+```tsx
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Popover } from "heroui-native";
+
+const insets = useSafeAreaInsets();
+
+<Popover.Content presentation="popover" offset={insets.top + 20}>
+  {/* ... */}
+</Popover.Content>;
+```
+
+这是纯文档变更，未改动任何 API 或运行时行为。
+
+**相关 PR：** [#419](https://github.com/heroui-inc/heroui-native/pull/419)
+
+## 问题修复
+
+本版本包含以下修复：
+
+- **[Issue #405](https://github.com/heroui-inc/heroui-native/issues/405)**：补充了在 React Navigation 原生模态中 `Menu` 渲染错位的处理方案。Menu 文档新增**原生模态（iOS）**章节，解释 Fabric / `FullWindowOverlay` 的坐标不一致，并演示如何用 `useSafeAreaInsets` 配合 `offset={insets.top}` 补偿。
+- **[Issue #418](https://github.com/heroui-inc/heroui-native/issues/418)**：修复将示例应用升级到 Expo 56 后出现的 Hermes 崩溃（「Maximum call stack size exceeded」）及 `BottomSheet` 内容不可见的问题。示例的 `metro.config.js` 现已将对等依赖解析（`react`、`react-native`、`uniwind` 等）锁定到示例的本地 `node_modules`，防止从 workspace 根加载到重复副本。
+
+**相关 PR：**
+
+- [#419](https://github.com/heroui-inc/heroui-native/pull/419)
+- [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## 弃用
+
+### `Text` 排版导出
+
+`Text` 组件与相关导出现已**弃用**，推荐使用 `Typography`。既有导入仍可继续工作，不会产生运行时错误——仅会在 TypeScript / IDE 中提示弃用。请在未来某个大版本移除弃用别名之前完成迁移。
+
+**弃用 → 推荐：**
+
+```tsx
+// 弃用（仍可用）
+import { Text, textClassNames, type TextProps } from "heroui-native";
+
+<Text.Heading type="h1">Welcome</Text.Heading>;
+
+// 推荐
+import {
+  Typography,
+  typographyClassNames,
+  type TypographyProps,
+} from "heroui-native";
+
+<Typography.Heading type="h1">Welcome</Typography.Heading>;
+```
+
+**相关 PR：** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
+
+## 文档更新
+
+以下文档页面已随本版本更新：
+
+- [Typography](/docs/native/components/typography) — 组件由 Text 重命名而来；完整 API、Anatomy 与用法已更新
+- [Menu](/docs/native/components/menu) — 新增**原生模态（iOS）**章节，含 `offset={insets.top}` 方案
+- [Popover](/docs/native/components/popover) — 新增**原生模态（iOS）**章节，含 `offset={insets.top}` 方案
+- [Select](/docs/native/components/select) — 新增**原生模态（iOS）**章节，含 `offset={insets.top}` 方案
+- [快速开始](/docs/native/getting-started/quick-start) — 可选对等依赖 `@gorhom/bottom-sheet` 更新到 `^5.2.9`
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/native/releases/v1-0-5.mdx b/apps/docs/content/docs/cn/native/releases/v1-0-5.mdx
new file mode 100644
index 0000000..f2f3d17
--- /dev/null
+++ b/apps/docs/content/docs/cn/native/releases/v1-0-5.mdx
@@ -0,0 +1,222 @@
+---
+title: v1.0.5
+description:
+  拆分 border-field 令牌以修复宽度/颜色合并冲突、Typography 支持 Dynamic Type、Provider 级文本输入配置、单次挂载的弹层动画、Select 图标颜色修复、升级至 Expo 57 / RN 0.86
+github:
+  pull: 439
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 7 月 2 日</span>
+</div>
+
+HeroUI Native v1.0.5 通过将字段边框拆分为独立的宽度与颜色令牌，并全局配置 `tailwind-variants`，解决了长期存在的 `border-field` 合并冲突，同时将 Input、InputOTP、Radio、Checkbox 迁移到基于 outline 的聚焦、激活与无效状态。本版本还为 Typography 带来 iOS Dynamic Type 支持，新增 Provider 级的文本输入配置，重构 Popover、Menu、Select 的进入动画以让内容仅挂载一次，将 Select 勾选图标与 `accent-soft-foreground` 令牌对齐，并将工具链升级至 Expo 57 / React Native 0.86。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **使用 AI 助手？** 直接提示「Hey Cursor，把 HeroUI Native 升级到最新版本」，助手会自动比对版本并完成必要修改。了解更多请参见 [HeroUI Native MCP 服务器](/docs/native/getting-started/mcp-server)。
+</Callout>
+
+## 真机体验
+
+<NativeTryOnDevice />
+
+## 性能
+
+### 单次挂载的 Popover、Menu、Select 动画
+
+[Popover](/docs/native/components/popover)、[Menu](/docs/native/components/menu)、[Select](/docs/native/components/select) 的内容现在只挂载一次，并在完成测量与定位后通过共享值播放进入动画。此前，内容子树会被挂载两次——先用一个隐藏探针测量尺寸，再挂载可见节点——以便进入 Keyframe 能在正确位置于挂载时触发。
+
+**改进点：**
+
+- 默认的进入动画由一个共享值（`rEnteringStyle`）驱动，在内容完成定位（`isReady`）后播放，使子树仅挂载一次
+- `usePopupPopoverContentAnimation` 现返回 `isDrivenEntering` 与 `rEnteringStyle`，其位移、缩放与不透明度均由一个进度值插值得出
+- 内容在就绪之前对指针事件保持隐藏；禁用动画时直接解析为显示状态
+- 自定义的进入 Keyframe 仍保留原先的「探针 + 挂载」回退路径
+
+组件的公开 API 未变——单次挂载路径完全是内部实现，自定义进入动画的行为与之前完全一致。建议在全部四个放置方向、子菜单过渡以及禁用动画的情形下，验证进入与退出动画。
+
+**相关 PR：** [#438](https://github.com/heroui-inc/heroui-native/pull/438)
+
+## 组件改进
+
+### Typography Dynamic Type 支持（iOS）
+
+[Typography](/docs/native/components/text) 组件现在会按语义类型应用默认的 `dynamicTypeRamp`，使文本在 iOS 上以符合 Apple 设计意图的方式缩放。较大的类型（如标题）比正文缩放得更慢，与 iOS 系统的 Dynamic Type 行为一致。此前，所有 Typography 组件中的文本都以相同的系数缩放。
+
+**改进点：**
+
+- 每个 Typography 类型都映射到合适的 iOS Dynamic Type ramp（例如标题映射到 `title` ramp，段落映射到 `body`）
+- 在 iOS 上提升无障碍与文本缩放的保真度，对 Android 无影响
+- 在需要不同 ramp 的场景下，可按实例覆盖 `dynamicTypeRamp` 默认值
+
+此变更仅针对 iOS，不改动 Typography 的 API。已直接传入 `dynamicTypeRamp` 的应用仍会显式控制缩放行为。
+
+**相关 PR：** [#435](https://github.com/heroui-inc/heroui-native/pull/435)
+
+### Select 勾选图标颜色
+
+[Select](/docs/native/components/select) 组件的 `Select.ItemIndicator` 现在将其勾选图标颜色默认为 `accent-soft-foreground` 主题令牌，而非 `accent`，使选中项指示器与预期的语义前景色对齐，从而获得更好的对比度与视觉一致性。
+
+**改进点：**
+
+- 默认勾选图标颜色改用 `accent-soft-foreground`，提升选中列表项的对比度
+- JSDoc 与组件文档已同步更新以反映新的默认值
+
+仅在省略 `iconProps.color` 时默认图标颜色会发生变化——API 未变，自定义颜色仍然有效。建议在亮色与暗色主题下进行手动验证，以确认指示器对比度。
+
+**相关 PR：** [#436](https://github.com/heroui-inc/heroui-native/pull/436)
+
+## API 增强
+
+### Provider 文本输入配置
+
+[HeroUINativeProvider](/docs/native/getting-started/provider)（以及 `HeroUINativeProviderRaw`）现可通过新的 `textInputProps` 配置在全局配置一部分 `TextInput` 属性，首批支持 `allowFontScaling` 与 `maxFontSizeMultiplier`。这与既有的全局 `textProps` 模式保持一致，使整个应用的输入字体缩放行为保持统一。
+
+**新能力：**
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native";
+
+export function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textInputProps: {
+          allowFontScaling: true,
+          maxFontSizeMultiplier: 1.5,
+        },
+      }}
+    >
+      {/* Your app */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+**包含内容：**
+
+- 在 `HeroUINativeConfig` 与 `HeroUINativeConfigRaw` 上新增 `textInputProps` 配置（`allowFontScaling`、`maxFontSizeMultiplier`）
+- 新增 `TextInputComponentProvider` / `useTextInputComponent` 以及一个 `HeroTextInput` 辅助组件，将全局属性作为可覆盖的默认值应用
+- 已应用于 `Input`（因此涵盖 `TextArea`、`SearchField`、`InputGroup`）以及 `InputOTP` 基元
+
+全局属性作为默认值应用，因此任何直接传给组件的属性仍会覆盖它们。
+
+**相关 PR：** [#437](https://github.com/heroui-inc/heroui-native/pull/437)
+
+## 依赖
+
+### 升级至 Expo 57 / React Native 0.86
+
+项目已升级到 Expo 57 / React Native 0.86 工具链。本次升级还通过包裹内容节点来修复遮罩退出动画，使布局动画不再与动画样式共享 transform，恢复 Android 输入聚焦环，并强化了 Pressable 样式回调的类型。
+
+**修复：**
+
+- 将 Popover、Menu、Select 的 `entering` / `exiting` 布局动画移到包裹用的 `Animated.View` 上，以修复退出动画并消除 Reanimated 的布局动画覆盖警告
+- 在 Android 上使用边框显示输入聚焦环，iOS 仍保留 outline 方案
+- 通过移除 `scale` transform 简化默认的退出 keyframe
+- 为 button 与子菜单的样式回调添加显式的 `PressableStateCallbackType` 类型
+
+**依赖升级：**
+
+- Expo `57`
+- React Native `0.86`
+- React Native Reanimated `4.5`
+- `react-native-worklets` `0.10`
+- Tailwind CSS `4.3`
+- Uniwind `1.10`
+
+公开 API 未变，但消费者应将其对等依赖版本与 Expo 57 / React Native 0.86 对齐。建议在 iOS 与 Android 上手动测试遮罩的打开/关闭动画以及输入聚焦状态。
+
+**相关 PR：** [#439](https://github.com/heroui-inc/heroui-native/pull/439)
+
+## ⚠️ 破坏性变更
+
+### 将 `border-field` 拆分为独立的宽度与颜色令牌
+
+此前，`border-field` 会以同一名称同时生成宽度与颜色两个工具类，导致 `tailwind-merge` 丢弃宽度。字段组件硬编码了边框宽度（`border`、`border-[1.5px]`），并使用 border-color 表示聚焦与无效状态。v1.0.5 将字段边框拆分为两个互不冲突的工具类，并全局配置 `tailwind-variants`，使宽度与颜色在合并时不再相互覆盖。
+
+**变更内容：**
+
+- `border-field-width`（宽度）与 `border-field-border`（颜色）现在是独立、互不冲突的工具类
+- `tv` / `cn` 使用一个共享的 `twMergeConfig`（`border-w` 分组）进行配置并全局注册；所有 `*.styles.ts` 均从 lib 导入 `tv`
+- Input、InputOTP、Radio、Checkbox 使用 `border-field-width` 与 `outline-*` 表示聚焦、激活与无效状态；无效 outline 现在在静止状态下即显示
+- `--field-radius` 系数由 `1.5` 改为 `1.75`
+
+组件的公开 API 未变，但视觉与行为上的变化需要验证。请在你的应用中确认以下事项：
+
+**迁移：**
+
+仅通过 `--field-border` 颜色设置的边框将不再显示——`--field-border-width` 现在默认为 `0px`，因此需要同时设置宽度：
+
+```tsx
+// 之前——仅设置颜色即可渲染出可见边框
+// --field-border: <color>;
+
+// 之后——还需设置宽度，因为 --field-border-width 默认为 0px
+// --field-border: <color>;
+// --field-border-width: 1.5px;
+```
+
+直接使用字段边框宽度工具类时，请重命名：
+
+```tsx
+// 之前
+<View className="border-field" />
+
+// 之后
+<View className="border-field-width" />
+```
+
+**同时请验证：**
+
+- 聚焦、激活与无效状态现在使用 `outline-*` 而非 border-color
+- 对 `--border-width-field` 主题键的覆盖必须改用 `--border-width-field-width`（或 `--field-border-width` 基元）
+- 字段圆角略有变化（`--field-radius` 系数由 `1.5` → `1.75`）
+
+如果你依赖 `--field-border` 颜色来产生静止状态的边框，请设置一个非零的 `--field-border-width` 默认值以恢复该外观。
+
+**相关 PR：** [#434](https://github.com/heroui-inc/heroui-native/pull/434)
+
+## 文档更新
+
+以下文档页面已随本版本更新以反映相关变更：
+
+- [Typography](/docs/native/components/text) — 记录了 iOS 上默认的 `dynamicTypeRamp` 行为
+- [Select](/docs/native/components/select) — 更新了 `Select.ItemIndicator` 默认勾选图标颜色
+- [Provider](/docs/native/getting-started/provider) — 新增 `textInputProps` 章节、示例与 Provider 层级说明
+
+## 链接
+
+- [组件文档](../components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-native)
+
+## 贡献者
+
+感谢所有为本版本做出贡献的朋友！
diff --git a/apps/docs/content/docs/cn/react/components/(buttons)/button-group.mdx b/apps/docs/content/docs/cn/react/components/(buttons)/button-group.mdx
new file mode 100644
index 0000000..adf9cbc
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(buttons)/button-group.mdx
@@ -0,0 +1,185 @@
+---
+title: ButtonGroup 按钮组
+description: 将相关按钮组合在一起，并提供一致的样式与间距。
+links:
+  rac: Button
+  source: button-group/button-group.tsx
+  styles: button-group.css
+  storybook: Components/Buttons/ButtonGroup
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### 组件结构
+
+导入 ButtonGroup 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+
+export default () => (
+  <ButtonGroup>
+    <Button>First</Button>
+    <Button>
+      <ButtonGroup.Separator />
+      Second
+    </Button>
+    <Button>
+      <ButtonGroup.Separator />
+      Third
+    </Button>
+  </ButtonGroup>
+);
+```
+
+> **ButtonGroup** 将多个 Button 组件包裹在一起，应用一致的样式、间距以及自动圆角处理。它使用 React Context 将 `size`、`variant` 与 `isDisabled` props 传递给所有子按钮。
+
+### 变体
+
+<ComponentPreview
+  name="button-group-variants"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="button-group-sizes"
+/>
+
+### 方向
+
+使用 `orientation` prop 将按钮按水平或垂直方向排列。
+
+<ComponentPreview
+  name="button-group-orientation"
+/>
+
+### 带图标
+
+<ComponentPreview
+  name="button-group-with-icons"
+/>
+
+### 全宽
+
+<ComponentPreview
+  name="button-group-full-width"
+/>
+
+### 禁用状态
+
+<ComponentPreview
+  name="button-group-disabled"
+/>
+
+### 无分隔线
+
+直接在按钮中省略 `<ButtonGroup.Separator />` 组件即可。
+
+<ComponentPreview
+  name="button-group-without-separator"
+/>
+
+<RelatedComponents component="button-group" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+
+function CustomButtonGroup() {
+  return (
+    <ButtonGroup className="gap-2">
+      <Button>First</Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Second
+      </Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Third
+      </Button>
+    </ButtonGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ButtonGroup 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .button-group {
+    @apply gap-2 rounded-lg;
+  }
+
+  .button-group__separator {
+    @apply opacity-25;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ButtonGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)）：
+
+#### 基础类
+
+- `.button-group` - 按钮组容器的基础样式
+- `.button-group--full-width` - 全宽修饰符
+- `.button-group__separator` - 按钮之间的分隔线元素
+
+ButtonGroup 会自动为按钮处理圆角：
+
+- 第一个按钮获得左侧/起始侧圆角
+- 最后一个按钮获得右侧/结束侧圆角
+- 中间按钮不带圆角
+- 仅有一个按钮时，四边都会应用完整圆角
+
+在每个 Button（第一个除外）内部添加 `<ButtonGroup.Separator />`，即可在按钮之间显示分隔线。
+
+## API 参考
+
+### ButtonGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | 应用于组内所有按钮的视觉变体 |
+| `size` | `'sm' \| 'md' \| 'lg'` | - | 应用于组内所有按钮的尺寸 |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 按钮组的排列方向 |
+| `fullWidth` | `boolean` | `false` | 按钮组是否占满容器宽度 |
+| `isDisabled` | `boolean` | `false` | 是否禁用组内全部按钮（可在单个按钮上覆盖） |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `React.ReactNode` | - | 需要组合在一起的按钮组件 |
+
+### ButtonGroup.Separator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### 说明
+
+- ButtonGroup 使用 React Context 将 `size`、`variant` 与 `isDisabled` props 传递给所有子 Button 组件
+- **只有直接子级按钮会接收 ButtonGroup 的 props**：即使某个按钮是 ButtonGroup 的后代，只要它嵌套在其他组件（如 Modal、Dropdown）中，就不会继承组级 props
+- 单个 Button 可通过设置 `isDisabled={false}` 覆盖组级别的 `isDisabled`
+- 组件会自动处理按钮之间的圆角
+- 在每个 Button（第一个除外）中添加 `<ButtonGroup.Separator />` 可显示分隔线
+- 按钮组中的按钮会移除激活/按压时的缩放变换，以获得更统一的视觉效果
diff --git a/apps/docs/content/docs/cn/react/components/(buttons)/button.mdx b/apps/docs/content/docs/cn/react/components/(buttons)/button.mdx
new file mode 100644
index 0000000..4986086
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(buttons)/button.mdx
@@ -0,0 +1,201 @@
+---
+title: Button 按钮
+description: 可点击的按钮组件，支持多种变体与状态。
+links:
+  rac: Button
+  source: button/button.tsx
+  styles: button.css
+  storybook: Components/Buttons/Button
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Button } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="button-basic"
+/>
+
+### 变体
+
+
+<ComponentPreview
+  name="button-variants"
+/>
+
+### 带图标
+
+<ComponentPreview
+  name="button-with-icons"
+/>
+
+### 仅图标
+
+<ComponentPreview
+  name="button-icon-only"
+/>
+
+### 加载中
+
+<ComponentPreview
+  name="button-loading"
+/>
+
+### 加载状态
+
+<ComponentPreview
+  name="button-loading-state"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="button-sizes"
+/>
+
+### 全宽
+
+<ComponentPreview
+  name="button-full-width"
+/>
+
+### 禁用状态
+
+
+<ComponentPreview
+  name="button-disabled"
+/>
+
+### 社交按钮
+
+<ComponentPreview
+  name="button-social"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="button-custom-render-function"
+/>
+
+<RelatedComponents component="button" />
+
+<RelatedShowcases component="Button" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Button } from '@heroui/react';
+
+function CustomButton() {
+  return (
+    <Button className="bg-purple-500 text-white hover:bg-purple-600">
+      Purple Button
+    </Button>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Button 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .button {
+    @apply bg-purple-500 text-white hover:bg-purple-600;
+  }
+
+  .button--icon-only {
+    @apply rounded-lg bg-blue-500;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### 添加自定义变体
+
+你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。
+
+<ComponentPreview
+  name="button-custom-variants"
+/>
+
+### 添加涟漪效果
+
+Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。
+
+<ComponentPreview
+  name="button-ripple-effect"
+/>
+
+### CSS 类
+
+Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)）：
+
+#### 基础与尺寸类
+- `.button` - 按钮基础样式
+- `.button--sm` - 小尺寸变体
+- `.button--md` - 中尺寸变体
+- `.button--lg` - 大尺寸变体
+
+#### 变体类
+- `.button--primary`
+- `.button--secondary`
+- `.button--tertiary`
+- `.button--outline`
+- `.button--ghost`
+- `.button--danger`
+
+#### 修饰符类
+- `.button--icon-only`
+- `.button--icon-only.button--sm`
+- `.button--icon-only.button--lg`
+
+### 交互状态
+
+该按钮同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **激活/按压**：`:active` 或 `[data-pressed="true"]`（包含缩放变换）
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
+- **等待中**：`[data-pending]`（加载期间禁用指针事件）
+
+## API 参考
+
+### Button Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | 视觉样式变体 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 |
+| `fullWidth` | `boolean` | `false` | 按钮是否占满容器宽度 |
+| `isDisabled` | `boolean` | `false` | 按钮是否禁用 |
+| `isPending` | `boolean` | `false` | 按钮是否处于加载状态 |
+| `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 |
+| `onPress` | `(e: PressEvent) => void` | - | 按钮被按下时的事件处理函数 |
+| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ButtonRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isPending` | `boolean` | 按钮是否处于加载状态 |
+| `isPressed` | `boolean` | 按钮当前是否被按压 |
+| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
+| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
+| `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
+| `isDisabled` | `boolean` | 按钮是否禁用 |
diff --git a/apps/docs/content/docs/cn/react/components/(buttons)/close-button.mdx b/apps/docs/content/docs/cn/react/components/(buttons)/close-button.mdx
new file mode 100644
index 0000000..9eed127
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(buttons)/close-button.mdx
@@ -0,0 +1,119 @@
+---
+title: CloseButton 关闭按钮
+description: 用于关闭对话框、模态框或收起内容的按钮组件。
+links:
+  rac: Button
+  source: close-button/close-button.tsx
+  styles: close-button.css
+  storybook: Components/Buttons/CloseButton
+---
+
+## 引入
+
+```tsx
+import { CloseButton } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview
+  name="close-button-default"
+/>
+
+### 自定义图标
+
+<ComponentPreview
+  name="close-button-with-custom-icon"
+/>
+
+### 交互
+
+<ComponentPreview
+  name="close-button-interactive"
+/>
+
+<RelatedComponents component="closebutton" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {CloseButton} from "@heroui/react";
+
+function CustomCloseButton() {
+  return <CloseButton className="text-red-600 hover:bg-red-100">Close</CloseButton>;
+}
+```
+
+### 自定义组件类
+
+要自定义 CloseButton 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .close-button {
+    @apply bg-red-100 text-red-800 hover:bg-red-200;
+  }
+
+  .close-button--custom {
+    @apply rounded-full border-2 border-red-300;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+CloseButton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)）：
+
+#### 基础类
+
+- `.close-button` - 组件基础样式
+
+#### 变体类
+
+- `.close-button--default` - 默认变体
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **激活/按压**：`:active` 或 `[data-pressed="true"]`
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
+
+## API 参考
+
+### CloseButton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `variant` | `"default"` | `"default"` | 按钮的视觉变体 |
+| `children` | `ReactNode \| function` | `<CloseIcon />` | 显示内容（默认为关闭图标） |
+| `onPress` | `() => void` | - | 按钮按下时触发的事件处理函数 |
+| `isDisabled` | `boolean` | `false` | 是否禁用按钮 |
+
+### React Aria Button Props
+
+CloseButton 继承所有 React Aria Button props。常见 props 包括：
+
+| Prop | 类型 | 描述 |
+| ---- | ---- | ---- |
+| `aria-label` | `string` | 提供给屏幕阅读器的无障碍标签 |
+| `aria-labelledby` | `string` | 用于标注按钮的元素 id |
+| `aria-describedby` | `string` | 用于描述按钮的元素 id |
+
+### RenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+| ---- | ---- | ---- |
+| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
+| `isPressed` | `boolean` | 按钮是否处于按压状态 |
+| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
+| `isDisabled` | `boolean` | 按钮是否禁用 |
diff --git a/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button-group.mdx b/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button-group.mdx
new file mode 100644
index 0000000..e789131
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button-group.mdx
@@ -0,0 +1,194 @@
+---
+title: ToggleButtonGroup 切换按钮组
+description: 将多个 ToggleButton 组合为统一控件，允许用户选择单个或多个选项。
+links:
+  rac: ToggleButtonGroup
+  source: toggle-button-group/toggle-button-group.tsx
+  styles: toggle-button-group.css
+  storybook: Components/Buttons/ToggleButtonGroup
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="toggle-button-group-basic"
+/>
+
+### 组件结构
+
+导入 ToggleButtonGroup 组件，并通过点语法访问所有子部分。
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+
+export default () => (
+  <ToggleButtonGroup selectionMode="multiple">
+    <ToggleButton id="first">First</ToggleButton>
+    <ToggleButton id="second">
+      <ToggleButtonGroup.Separator />
+      Second
+    </ToggleButton>
+    <ToggleButton id="third">
+      <ToggleButtonGroup.Separator />
+      Third
+    </ToggleButton>
+  </ToggleButtonGroup>
+);
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="toggle-button-group-sizes"
+/>
+
+### 方向
+
+<ComponentPreview
+  name="toggle-button-group-orientation"
+/>
+
+### 分离模式
+
+使用 `isDetached` 让按钮之间留出间隔，而不是彼此连接。
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### 全宽
+
+<ComponentPreview
+  name="toggle-button-group-full-width"
+/>
+
+### 选择模式
+
+使用 `selectionMode="single"` 实现互斥选择，或使用 `selectionMode="multiple"` 实现独立切换。
+
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="toggle-button-group-controlled"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="toggle-button-group-disabled"
+/>
+
+### 无分隔线
+
+在按钮中直接省略 `<ToggleButtonGroup.Separator />` 组件即可。
+
+<ComponentPreview
+  name="toggle-button-group-without-separator"
+/>
+
+<RelatedComponents component="toggle-button-group" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+
+function CustomToggleButtonGroup() {
+  return (
+    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
+      <ToggleButton id="a">Option A</ToggleButton>
+      <ToggleButton id="b">
+        <ToggleButtonGroup.Separator />
+        Option B
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ToggleButtonGroup 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toggle-button-group {
+    @apply rounded-lg;
+  }
+
+  .toggle-button-group__separator {
+    @apply opacity-25;
+  }
+
+  .toggle-button-group--full-width {
+    @apply w-full;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)）：
+
+#### 基础与布局类
+
+- `.toggle-button-group` - 容器基础样式
+- `.toggle-button-group--horizontal` - 水平方向
+- `.toggle-button-group--vertical` - 垂直方向
+- `.toggle-button-group--full-width` - 全宽修饰符
+- `.toggle-button-group__separator` - 按钮之间的分隔线元素
+
+#### 修饰符类
+
+- `.toggle-button-group--detached` - 分离模式（按钮间有间隔）
+
+## API 参考
+
+### ToggleButtonGroup Props
+
+继承自 [React Aria ToggleButtonGroup](https://react-aria.adobe.com/ToggleButtonGroup)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `selectionMode` | `"single" \| "multiple"` | `"single"` | 是否允许选中一个或多个按钮 |
+| `selectedKeys` | `Iterable<Key>` | - | 受控的选中状态 |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | 默认选中 key（非受控） |
+| `onSelectionChange` | `(keys: Set<Key>) => void` | - | 选中变化时调用 |
+| `disallowEmptySelection` | `boolean` | `false` | 是否禁止清空所有选中 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 布局方向 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 传递给子 ToggleButton 的尺寸 |
+| `isDetached` | `boolean` | `false` | 按钮是否以间隔分离显示 |
+| `fullWidth` | `boolean` | `false` | 按钮组是否占满可用宽度 |
+| `isDisabled` | `boolean` | `false` | 是否禁用组内全部按钮 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### ToggleButtonGroup.Separator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### 说明
+
+- ToggleButtonGroup 使用 React Context 将 `size` 传递给所有子 ToggleButton 组件
+- 每个 ToggleButton 都必须有唯一 `id` prop，并与 `selectedKeys` / `defaultSelectedKeys` 中使用的 key 对应
+- `isDisabled` prop 由 React Aria 原生处理，会禁用所有子 ToggleButton；单个按钮可通过设置 `isDisabled={false}` 覆盖
+- 组件会自动处理按钮之间的圆角
+- 在每个 ToggleButton（第一个除外）内添加 `<ToggleButtonGroup.Separator />`，可在按钮之间显示分隔线
+- 将 `disallowEmptySelection` 与 `selectionMode="single"` 一起使用，可确保始终有一个选项被选中
diff --git a/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button.mdx b/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button.mdx
new file mode 100644
index 0000000..c43a456
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button.mdx
@@ -0,0 +1,153 @@
+---
+title: ToggleButton 切换按钮
+description: 用于在开启/关闭或已选中/未选中状态之间切换的交互式切换控件。
+links:
+  rac: ToggleButton
+  source: toggle-button/toggle-button.tsx
+  styles: toggle-button.css
+  storybook: Components/Buttons/ToggleButton
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ToggleButton } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="toggle-button-basic"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="toggle-button-variants"
+/>
+
+### 仅图标
+
+<ComponentPreview
+  name="toggle-button-icon-only"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="toggle-button-sizes"
+/>
+
+
+### 受控
+
+<ComponentPreview
+  name="toggle-button-controlled"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="toggle-button-disabled"
+/>
+
+<RelatedComponents component="togglebutton" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ToggleButton } from '@heroui/react';
+
+function CustomToggleButton() {
+  return (
+    <ToggleButton className="bg-purple-500 text-white">
+      Toggle
+    </ToggleButton>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ToggleButton 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toggle-button {
+    @apply bg-purple-500 text-white;
+  }
+
+  .toggle-button--icon-only {
+    @apply rounded-lg;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ToggleButton 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)）：
+
+#### 基础与尺寸类
+
+- `.toggle-button` - 切换按钮基础样式
+- `.toggle-button--sm` - 小尺寸变体
+- `.toggle-button--md` - 中尺寸变体（默认）
+- `.toggle-button--lg` - 大尺寸变体
+
+#### 变体类
+
+- `.toggle-button--default` - 默认变体（填充背景）
+- `.toggle-button--ghost` - 幽灵变体（透明背景）
+
+#### 修饰符类
+
+- `.toggle-button--icon-only` - 仅图标切换按钮
+- `.toggle-button--icon-only.toggle-button--sm` - 小尺寸仅图标
+- `.toggle-button--icon-only.toggle-button--lg` - 大尺寸仅图标
+
+### 交互状态
+
+该切换按钮同时支持 CSS 伪类与 data 属性，以便灵活控制状态：
+
+- **已选中**：`[data-selected="true"]`（强调色背景与前景）
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **激活/按下**：`:active` 或 `[data-pressed="true"]`（包含缩放变换）
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
+
+## API 参考
+
+### ToggleButton Props
+
+继承自 [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'default' \| 'ghost'` | `'default'` | 视觉样式变体 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 切换按钮尺寸 |
+| `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 |
+| `isSelected` | `boolean` | - | 受控的已选中状态 |
+| `defaultSelected` | `boolean` | `false` | 默认已选中状态（非受控） |
+| `isDisabled` | `boolean` | `false` | 是否禁用切换按钮 |
+| `onChange` | `(isSelected: boolean) => void` | - | 已选中状态变化时调用的处理函数 |
+| `onPress` | `(e: PressEvent) => void` | - | 按钮按下时调用的处理函数 |
+| `children` | `React.ReactNode \| (values: ToggleButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop |
+
+### ToggleButtonRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 按钮当前是否已选中 |
+| `isPressed` | `boolean` | 按钮当前是否处于按下状态 |
+| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
+| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
+| `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
+| `isDisabled` | `boolean` | 按钮是否被禁用 |
diff --git a/apps/docs/content/docs/cn/react/components/(collections)/dropdown.mdx b/apps/docs/content/docs/cn/react/components/(collections)/dropdown.mdx
new file mode 100644
index 0000000..c8b83b4
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(collections)/dropdown.mdx
@@ -0,0 +1,529 @@
+---
+title: Dropdown 下拉菜单
+description: 下拉菜单展示一组可供用户选择的操作或选项。
+links:
+  rac: Menu
+  source: dropdown/dropdown.tsx
+  styles: dropdown.css
+  storybook: Components/Collections/Dropdown
+---
+
+## 引入
+
+```tsx
+import { Dropdown } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="dropdown-default"
+/>
+
+### 组件结构
+
+引入 Dropdown 组件并通过点语法访问所有子部分。
+
+```tsx
+import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react';
+
+export default () => (
+  <Dropdown>
+    <Dropdown.Trigger>
+      <Button />
+    </Dropdown.Trigger>
+    <Dropdown.Popover>
+      <Dropdown.Menu>
+        <Dropdown.Item>
+          <Label />
+          <Description />
+          <Kbd slot="keyboard" />
+          <Dropdown.ItemIndicator />
+        </Dropdown.Item>
+        <Separator />
+        <Dropdown.Section>
+          <Header />
+          <Dropdown.Item />
+        </Dropdown.Section>
+        <Dropdown.SubmenuTrigger>
+          <Dropdown.Item>
+            <Label />
+            <Dropdown.SubmenuIndicator />
+          </Dropdown.Item>
+          <Dropdown.Popover>
+            <Dropdown.Menu>
+              <Dropdown.Item />
+            </Dropdown.Menu>
+          </Dropdown.Popover>
+        </Dropdown.SubmenuTrigger>
+      </Dropdown.Menu>
+    </Dropdown.Popover>
+  </Dropdown>
+)
+```
+
+### 带单选
+
+<ComponentPreview
+  name="dropdown-with-single-selection"
+/>
+
+### 单选且自定义指示器
+
+<ComponentPreview
+  name="dropdown-single-with-custom-indicator"
+/>
+
+### 带多选
+
+<ComponentPreview
+  name="dropdown-with-multiple-selection"
+/>
+
+### 带分组级选择
+
+<ComponentPreview
+  name="dropdown-with-section-level-selection"
+/>
+
+### 带键盘快捷键
+
+<ComponentPreview
+  name="dropdown-with-keyboard-shortcuts"
+/>
+
+### 带图标
+
+<ComponentPreview
+  name="dropdown-with-icons"
+/>
+
+### 长按触发
+
+<ComponentPreview
+  name="dropdown-long-press-trigger"
+/>
+
+### 带描述
+
+<ComponentPreview
+  name="dropdown-with-descriptions"
+/>
+
+### 带分组
+
+<ComponentPreview
+  name="dropdown-with-sections"
+/>
+
+### 带禁用项
+
+<ComponentPreview
+  name="dropdown-with-disabled-items"
+/>
+
+### 带子菜单
+
+<ComponentPreview
+  name="dropdown-with-submenus"
+/>
+
+### 带自定义子菜单指示器
+
+<ComponentPreview
+  name="dropdown-with-custom-submenu-indicator"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="dropdown-controlled"
+/>
+
+### 受控展开状态
+
+<ComponentPreview
+  name="dropdown-controlled-open-state"
+/>
+
+### 自定义触发器
+
+<ComponentPreview
+  name="dropdown-custom-trigger"
+/>
+
+<RelatedComponents component="dropdown" />
+ 
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Dropdown, Button } from '@heroui/react';
+
+function CustomDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger className="rounded-lg border p-2 bg-surface">
+        <Button>Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Popover className="min-w-[200px]">
+        <Dropdown.Menu>
+          <Dropdown.Item id="item-1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Dropdown 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .dropdown {
+    @apply flex flex-col gap-1;
+  }
+
+  .dropdown__trigger {
+    @apply outline-none;
+  }
+
+  .dropdown__popover {
+    @apply rounded-lg border border-border bg-overlay p-2;
+  }
+
+  .dropdown__menu {
+    @apply flex flex-col gap-1;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体和状态可复用且易于自定义。
+
+### CSS 类
+
+Dropdown 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)）：
+
+#### 基础类
+- `.dropdown` - Dropdown 根容器
+- `.dropdown__trigger` - 用于触发 Dropdown 的按钮或元素
+- `.dropdown__popover` - Popover 容器
+- `.dropdown__menu` - Popover 内的菜单容器
+
+#### 状态类
+- `.dropdown__trigger[data-focus-visible="true"]` - 触发器聚焦状态
+- `.dropdown__trigger[data-disabled="true"]` - 触发器禁用状态
+- `.dropdown__trigger[data-pressed="true"]` - 触发器按下状态
+- `.dropdown__popover[data-entering]` - 进入动画状态
+- `.dropdown__popover[data-exiting]` - 退出动画状态
+- `.dropdown__menu[data-selection-mode="single"]` - 单选模式
+- `.dropdown__menu[data-selection-mode="multiple"]` - 多选模式
+
+### 菜单组件类
+
+Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类名也可用于自定义：
+
+#### Menu 类
+- `.menu` - 菜单容器（[menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css)）
+  - `[data-slot="separator"]` - 菜单内的分隔线元素
+
+#### MenuItem 类
+- `.menu-item` - 菜单项容器（[menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css)）
+- `.menu-item__indicator` - 选中指示器（对勾或圆点）
+  - `[data-slot="menu-item-indicator--checkmark"]` - 对勾指示器 SVG
+  - `[data-slot="menu-item-indicator--dot"]` - 圆点指示器 SVG
+- `.menu-item__indicator--submenu` - 子菜单指示器（箭头）
+- `.menu-item--default` - 默认样式变体
+- `.menu-item--danger` - 危险样式变体
+
+#### MenuItem 状态类
+- `.menu-item[data-focus-visible="true"]` - 聚焦状态（键盘焦点）
+- `.menu-item[data-focus="true"]` - 聚焦状态
+- `.menu-item[data-pressed]` - 按下状态
+- `.menu-item[data-hovered]` - 悬停状态
+- `.menu-item[data-selected="true"]` - 选中状态
+- `.menu-item[data-disabled]` - 禁用状态
+- `.menu-item[data-has-submenu="true"]` - 带子菜单的项
+- `.menu-item[data-selection-mode="single"]` - 单选模式
+- `.menu-item[data-selection-mode="multiple"]` - 多选模式
+- `.menu-item[aria-checked="true"]` - 已勾选（ARIA）
+- `.menu-item[aria-selected="true"]` - 已选中（ARIA）
+
+#### MenuSection 类
+- `.menu-section` - 菜单分区容器（[menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css)）
+
+### 交互状态
+
+该组件同时支持 CSS 伪类和 data 属性，便于灵活组合：
+
+- **悬停**：触发器与菜单项上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：触发器与菜单项上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：触发器与菜单项上 `:disabled` 或 `[data-disabled="true"]`
+- **按下**：触发器与菜单项上 `:active` 或 `[data-pressed="true"]`
+- **选中**：菜单项上 `[data-selected="true"]` 或 `[aria-selected="true"]`
+
+## API 参考
+
+### Dropdown Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isOpen` | `boolean` | - | 设置菜单展开状态（受控）。 |
+| `defaultOpen` | `boolean` | - | 设置菜单默认展开状态（非受控）。 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 展开状态变化时调用的事件处理函数。 |
+| `trigger` | `"press" \| "longPress"` | `"press"` | 触发菜单的交互类型。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | Dropdown 内容。 |
+
+### Dropdown.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 |
+
+使用 Button 作为触发器时，同样支持所有 [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props。
+
+### Dropdown.Popover Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 相对于触发器的 Popover 位置。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 子内容。 |
+
+同样支持所有 [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props。
+
+### Dropdown.Menu Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `selectionMode` | `"single" \| "multiple" \| "none"` | `"none"` | 是否启用单选、多选或不启用选择。 |
+| `selectedKeys` | `Iterable<Key>` | - | 当前选中的 key（受控）。 |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | 初始选中的 key（非受控）。 |
+| `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 |
+| `onAction` | `(key: Key) => void` | - | 激活菜单项时调用的事件处理函数。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 菜单内容。 |
+
+同样支持所有 [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props。
+
+### Dropdown.Section Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `selectionMode` | `"single" \| "multiple"` | - | 该分组内菜单项的选择模式。 |
+| `selectedKeys` | `Iterable<Key>` | - | 当前选中的 key（受控）。 |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | 初始选中的 key（非受控）。 |
+| `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 分组内容。 |
+
+同样支持所有 [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props。
+
+### Dropdown.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `Key` | - | 菜单项唯一标识。 |
+| `textValue` | `string` | - | 用于首字母导航的文本内容。 |
+| `variant` | `"default" \| "danger"` | `"default"` | 菜单项视觉变体。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 菜单项内容或渲染函数。 |
+
+同样支持所有 [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props。
+
+### Dropdown.ItemIndicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `type` | `"checkmark" \| "dot"` | `"checkmark"` | 指示器类型。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 自定义指示器内容或渲染函数。 |
+
+使用渲染函数时，会传入以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 该项是否选中。 |
+| `isIndeterminate` | `boolean` | 该项是否处于不确定状态。 |
+
+### Dropdown.SubmenuIndicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 自定义指示器内容。 |
+
+### Dropdown.SubmenuTrigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 子菜单触发器内容。 |
+
+同样支持所有 [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props。
+
+### RenderProps
+
+在 Dropdown.Item 中使用渲染函数时，会传入以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 该项是否选中。 |
+| `isFocused` | `boolean` | 该项是否聚焦。 |
+| `isDisabled` | `boolean` | 该项是否禁用。 |
+| `isPressed` | `boolean` | 该项是否处于按下状态。 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+import { Dropdown, Button, Label } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Actions
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Item id="new-file" textValue="New file">
+        <Label>New file</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="open-file" textValue="Open file">
+        <Label>Open file</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+        <Label>Delete file</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### 带分组
+
+```tsx
+import { Dropdown, Button, Label, Header, Separator } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Actions
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Section>
+        <Header>Actions</Header>
+        <Dropdown.Item id="new-file" textValue="New file">
+          <Label>New file</Label>
+        </Dropdown.Item>
+        <Dropdown.Item id="edit-file" textValue="Edit file">
+          <Label>Edit file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+      <Separator />
+      <Dropdown.Section>
+        <Header>Danger zone</Header>
+        <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+          <Label>Delete file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### 受控选择
+
+```tsx
+import type { Selection } from '@heroui/react';
+
+import { Dropdown, Button, Label } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledDropdown() {
+  const [selected, setSelected] = useState<Selection>(new Set(['bold']));
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Item id="bold" textValue="Bold">
+            <Label>Bold</Label>
+            <Dropdown.ItemIndicator />
+          </Dropdown.Item>
+          <Dropdown.Item id="italic" textValue="Italic">
+            <Label>Italic</Label>
+            <Dropdown.ItemIndicator />
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+### 带子菜单
+
+```tsx
+import { Dropdown, Button, Label } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Share
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Item id="copy-link" textValue="Copy Link">
+        <Label>Copy Link</Label>
+      </Dropdown.Item>
+      <Dropdown.SubmenuTrigger>
+        <Dropdown.Item id="share" textValue="Share">
+          <Label>Other</Label>
+          <Dropdown.SubmenuIndicator />
+        </Dropdown.Item>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+              <Label>WhatsApp</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="telegram" textValue="Telegram">
+              <Label>Telegram</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown.SubmenuTrigger>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+## 无障碍
+
+Dropdown 组件实现 ARIA 菜单模式，并提供：
+
+- 完整键盘导航（方向键、Home/End、首字母导航）
+- 屏幕阅读器对操作与选中变化的播报
+- 合理的焦点管理
+- 禁用态支持
+- 长按交互支持
+- 子菜单导航
+
+更多信息见 [React Aria Menu 文档](https://react-spectrum.adobe.com/react-aria/Menu.html#menu)。
+
diff --git a/apps/docs/content/docs/cn/react/components/(collections)/list-box.mdx b/apps/docs/content/docs/cn/react/components/(collections)/list-box.mdx
new file mode 100644
index 0000000..c9d4467
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(collections)/list-box.mdx
@@ -0,0 +1,328 @@
+---
+title: ListBox 列表框
+description: 列表框展示一组选项，并允许用户选择一个或多个。
+links:
+  rac: ListBox
+  source: list-box/list-box.tsx
+  styles: list-box.css
+  storybook: Components/Collections/ListBox
+---
+
+## 引入
+
+```tsx
+import { ListBox } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="list-box-default"
+/>
+
+### 组件结构
+
+引入 ListBox 组件并通过点语法访问所有子部分。
+
+```tsx
+import { ListBox, Label, Description, Header } from '@heroui/react';
+
+export default () => (
+  <ListBox>
+    <ListBox.Item>
+      <Label />
+      <Description />
+      <ListBox.ItemIndicator />
+    </ListBox.Item>
+    <ListBox.Section>
+      <Header />
+      <ListBox.Item>
+        <Label />
+      </ListBox.Item>
+    </ListBox.Section>
+  </ListBox>
+)
+```
+
+### 带分组
+
+<ComponentPreview
+  name="list-box-with-sections"
+/>
+
+### 多选
+
+<ComponentPreview
+  name="list-box-multi-select"
+/>
+
+### 带禁用项
+
+<ComponentPreview
+  name="list-box-with-disabled-items"
+/>
+
+### 自定义勾选图标
+
+<ComponentPreview
+  name="list-box-custom-check-icon"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="list-box-controlled"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="list-box-custom-render-function"
+/>
+
+### 虚拟化
+
+ListBox 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见的行，从而高效展示大数据集。
+
+<ComponentPreview 
+  name="list-box-virtualization"
+/>
+
+<RelatedComponents component="list-box" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ListBox } from '@heroui/react';
+
+function CustomListBox() {
+  return (
+    <ListBox className="border rounded-lg p-2 bg-surface">
+      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+        Item 1
+      </ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ListBox 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .list-box {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .list-box-item {
+    @apply rounded px-2 py-1 cursor-pointer;
+  }
+
+  .list-box-item--danger {
+    @apply text-danger;
+  }
+
+  .list-box-item__indicator {
+    @apply text-accent;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/list-box.css)）：
+
+#### 基础类
+- `.list-box` - ListBox 根容器
+- `.list-box-item` - 单个列表项
+- `.list-box-item__indicator` - 选中指示图标
+- `.list-box-section` - 用于分组的区块容器
+
+#### 变体类
+- `.list-box--default` - 默认变体样式
+- `.list-box--danger` - 危险变体样式
+- `.list-box-item--default` - 列表项默认变体
+- `.list-box-item--danger` - 列表项危险变体
+
+#### 状态类
+- `.list-box-item[data-selected="true"]` - 选中状态
+- `.list-box-item[data-focus-visible="true"]` - 聚焦状态
+- `.list-box-item[data-disabled="true"]` - 禁用状态
+- `.list-box-item__indicator[data-visible="true"]` - 指示器可见状态
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性：
+
+- **悬停**：列表项上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：列表项上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **已选中**：列表项上 `[data-selected="true"]`
+- **禁用**：列表项上 `:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### ListBox Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | ListBox 的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 标注 ListBox 的元素 id。 |
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"single"` | 选择行为。 |
+| `selectedKeys` | `Selection` | - | 受控的选中 key。 |
+| `defaultSelectedKeys` | `Selection` | - | 初始选中 key。 |
+| `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 |
+| `onAction` | `(key: Key) => void` | - | 激活某项时调用的事件处理函数。 |
+| `variant` | `"default" \| "danger"` | `"default"` | 视觉变体。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | ListBox 项与分组。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ListBox.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `Key` | - | 列表项唯一标识。 |
+| `textValue` | `string` | - | 用于无障碍与首字母导航的文本值。 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该项。 |
+| `variant` | `"default" \| "danger"` | `"default"` | 视觉变体。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 列表项内容或渲染函数。 |
+| `render` | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ListBox.ItemIndicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 自定义指示器内容或渲染函数。 |
+
+### ListBox.Section Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 分组内容，包含 Header 与列表项。 |
+
+### RenderProps
+
+在 ListBox.Item 或 ListBox.ItemIndicator 中使用渲染函数时，会传入以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 该项是否选中。 |
+| `isFocused` | `boolean` | 该项是否聚焦。 |
+| `isDisabled` | `boolean` | 该项是否禁用。 |
+| `isPressed` | `boolean` | 该项是否处于按下状态。 |
+
+### ListLayout
+
+| Name | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `rowHeight` | `number \| undefined` | 48 | 行固定高度（px）。 |
+| `estimatedRowHeight` | `number \| undefined` | — | 行高可变时的估算高度。 |
+| `headingHeight` | `number \| undefined` | 48 | 分组标题固定高度（px）。 |
+| `estimatedHeadingHeight` | `number \| undefined` | — | 标题高度可变时的估算高度。 |
+| `loaderHeight` | `number \| undefined` | 48 | 加载器元素固定高度（px）。该加载器用于在根级或嵌套行/分组中渲染「加载更多」等内容。 |
+| `dropIndicatorThickness` | `number \| undefined` | 2 | 放置指示线厚度。 |
+| `gap` | `number \| undefined` | 0 | 项之间的间距。 |
+| `padding` | `number \| undefined` | 0 | 列表内边距。 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+import { ListBox, Label, Description } from '@heroui/react';
+
+<ListBox aria-label="Users" selectionMode="single">
+  <ListBox.Item id="1" textValue="Bob">
+    <Label>Bob</Label>
+    <Description>bob@heroui.com</Description>
+  </ListBox.Item>
+  <ListBox.Item id="2" textValue="Alice">
+    <Label>Alice</Label>
+    <Description>alice@heroui.com</Description>
+  </ListBox.Item>
+</ListBox>
+```
+
+### 带分组
+
+```tsx
+import { ListBox, Header, Separator } from '@heroui/react';
+
+<ListBox aria-label="Actions" selectionMode="none" onAction={(key) => console.log(key)}>
+  <ListBox.Section>
+    <Header>Actions</Header>
+    <ListBox.Item id="new" textValue="New file">New file</ListBox.Item>
+    <ListBox.Item id="edit" textValue="Edit file">Edit file</ListBox.Item>
+  </ListBox.Section>
+  <Separator />
+  <ListBox.Section>
+    <Header>Danger zone</Header>
+    <ListBox.Item id="delete" textValue="Delete" variant="danger">Delete</ListBox.Item>
+  </ListBox.Section>
+</ListBox>
+```
+
+### 受控选择
+
+```tsx
+import { ListBox, Selection } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledListBox() {
+  const [selected, setSelected] = useState<Selection>(new Set(["1"]));
+
+  return (
+    <ListBox
+      aria-label="Options"
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={setSelected}
+    >
+      <ListBox.Item id="1" textValue="Option 1">Option 1</ListBox.Item>
+      <ListBox.Item id="2" textValue="Option 2">Option 2</ListBox.Item>
+      <ListBox.Item id="3" textValue="Option 3">Option 3</ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+### 自定义指示器
+
+```tsx
+import { ListBox, ListBoxItemIndicator } from '@heroui/react';
+import { Icon } from '@iconify/react';
+
+<ListBox aria-label="Options" selectionMode="multiple">
+  <ListBox.Item id="1" textValue="Option 1">
+    Option 1
+    <ListBox.ItemIndicator>
+      {({isSelected}) =>
+        isSelected ? <Icon icon="gravity-ui:check" /> : null
+      }
+    </ListBox.ItemIndicator>
+  </ListBox.Item>
+</ListBox>
+```
+
+## 无障碍
+
+ListBox 组件实现 ARIA listbox 模式，并提供：
+
+- 完整键盘导航支持
+- 屏幕阅读器对选中变化的播报
+- 合理的焦点管理
+- 禁用状态支持
+- 首字母导航（typeahead）搜索能力
+
+更多信息见 [React Aria ListBox 文档](https://react-spectrum.adobe.com/react-aria/ListBox.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(collections)/tag-group.mdx b/apps/docs/content/docs/cn/react/components/(collections)/tag-group.mdx
new file mode 100644
index 0000000..dd0b7db
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(collections)/tag-group.mdx
@@ -0,0 +1,298 @@
+---
+title: TagGroup 标签组
+description: 可聚焦的标签列表，支持键盘导航、选择与移除。
+links:
+  rac: TagGroup
+  source: tag-group/tag-group.tsx
+  styles: tag-group.css
+  storybook: Components/Collections/TagGroup
+---
+
+## 引入
+
+```tsx
+import { TagGroup } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="tag-group-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
+
+export default () => (
+  <TagGroup>
+    <Label />
+    <TagGroup.List>
+      <Tag>
+        <Tag.RemoveButton />
+      </Tag>
+    </TagGroup.List>
+    <Description />
+    <ErrorMessage />
+  </TagGroup>
+)
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="tag-group-sizes"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="tag-group-variants"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="tag-group-disabled"
+/>
+
+### 选择模式
+
+<ComponentPreview
+  name="tag-group-selection-modes"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="tag-group-controlled"
+/>
+
+### 带错误信息
+
+<ComponentPreview
+  name="tag-group-with-error-message"
+/>
+
+### 带前缀
+
+<ComponentPreview
+  name="tag-group-with-prefix"
+/>
+
+### 带移除按钮
+
+<ComponentPreview
+  name="tag-group-with-remove-button"
+/>
+
+### 带列表数据
+
+<ComponentPreview
+  name="tag-group-with-list-data"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="tag-group-custom-render-function"
+/>
+
+<RelatedComponents component="taggroup" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { TagGroup, Tag, Label } from '@heroui/react';
+
+function CustomTagGroup() {
+  return (
+    <TagGroup className="w-full">
+      <Label>Categories</Label>
+      <TagGroup.List className="gap-2">
+        <Tag className="rounded-lg px-4 py-2 font-bold">
+          Custom Styled
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 TagGroup 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .tag-group {
+    @apply flex flex-col gap-2;
+  }
+
+  .tag-group__list {
+    @apply flex flex-wrap gap-2;
+  }
+
+  .tag {
+    @apply rounded-full px-3 py-1;
+  }
+
+  .tag__remove-button {
+    @apply ml-1;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) 与 [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)）：
+
+#### 基础类
+- `.tag-group` - TagGroup 根容器
+- `.tag-group__list` - 标签列表容器
+- `.tag` - 标签基础样式
+- `.tag__remove-button` - 移除按钮触发器
+
+#### 插槽类
+- `.tag-group [slot="description"]` - Description 插槽样式
+- `.tag-group [slot="errorMessage"]` - ErrorMessage 插槽样式
+
+#### 尺寸类
+- `.tag--sm` - 小尺寸标签
+- `.tag--md` - 中尺寸标签（默认）
+- `.tag--lg` - 大尺寸标签
+
+#### 变体类
+- `.tag--default` - 默认变体
+- `.tag--surface` - 带 Surface 背景的变体
+
+#### 状态类
+- `.tag[data-selected="true"]` - 选中状态
+- `.tag[data-disabled="true"]` - 禁用状态
+- `.tag[data-hovered="true"]` - 悬停状态
+- `.tag[data-pressed="true"]` - 按下状态
+- `.tag[data-focus-visible="true"]` - 聚焦状态（键盘焦点）
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性：
+
+- **悬停**：标签上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：标签上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **按下**：标签上 `:active` 或 `[data-pressed="true"]`
+- **已选中**：标签上 `[data-selected="true"]` 或 `[aria-selected="true"]`
+- **禁用**：标签上 `:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### TagGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | 允许的选择类型。 |
+| `selectedKeys` | `Selection` | - | 当前选中的 key（受控）。 |
+| `defaultSelectedKeys` | `Selection` | - | 初始选中的 key（非受控）。 |
+| `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用标签的 key。 |
+| `isDisabled` | `boolean` | - | 是否禁用整个 TagGroup。 |
+| `onRemove` | `(keys: Set<Key>) => void` | - | 移除标签时调用的事件处理函数。 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 组内标签尺寸。 |
+| `variant` | `"default" \| "surface"` | `"default"` | 标签视觉变体。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | TagGroup 内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### TagGroup.List Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `items` | `Iterable<T>` | - | 标签列表要展示的数据项。 |
+| `renderEmptyState` | `() => ReactNode` | - | 列表为空时的渲染函数。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 标签列表内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Tag Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `Key` | - | 标签唯一标识。 |
+| `textValue` | `string` | - | 标签内容的字符串表示，用于无障碍。 |
+| `isDisabled` | `boolean` | - | 是否禁用该标签。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 标签内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+**提示：** `size`、`variant` 由父级 `TagGroup` 继承，无法在单个 `Tag` 上直接设置。
+
+### Tag.RemoveButton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 自定义移除按钮内容（默认为关闭图标）。 |
+
+**提示：** `Tag.RemoveButton` 支持类似 `SearchField.ClearButton` 的定制方式。当为 `TagGroup` 提供 `onRemove` 时：
+
+- **自动渲染**：若 `Tag` 的子节点中未包含自定义 `Tag.RemoveButton`，会自动渲染默认移除按钮。
+- **自定义按钮**：若在 `Tag` 下提供了自定义 `Tag.RemoveButton`，将替换自动渲染的按钮。
+- **自定义图标**：可向 `Tag.RemoveButton` 传入自定义子内容（如图标）以改变外观。
+
+**示例 — 自动渲染（默认）**：
+```tsx
+<TagGroup onRemove={handleRemove}>
+  <TagGroup.List>
+    <Tag id="news">News</Tag>
+    {/* Remove button is automatically rendered */}
+  </TagGroup.List>
+</TagGroup>
+```
+
+**示例 — 自定义 RemoveButton（带图标）**：
+```tsx
+<TagGroup onRemove={handleRemove}>
+  <TagGroup.List>
+    <Tag id="news">
+      News
+      <Tag.RemoveButton>
+        <CustomIcon />
+      </Tag.RemoveButton>
+    </Tag>
+  </TagGroup.List>
+</TagGroup>
+```
+
+**示例 — 在 render props 中使用自定义 RemoveButton**：
+```tsx
+<Tag id="news">
+  {(renderProps) => (
+    <>
+      News
+      {!!renderProps.allowsRemoving && (
+        <Tag.RemoveButton>
+          <CustomIcon />
+        </Tag.RemoveButton>
+      )}
+    </>
+  )}
+</Tag>
+```
+
+### RenderProps
+
+在 TagGroup.List 中使用渲染函数时，会传入以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 标签是否选中。 |
+| `isDisabled` | `boolean` | 标签是否禁用。 |
+| `isHovered` | `boolean` | 标签是否悬停。 |
+| `isPressed` | `boolean` | 标签是否按下。 |
+| `isFocused` | `boolean` | 标签是否聚焦。 |
+| `isFocusVisible` | `boolean` | 标签是否为可见键盘焦点。 |
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-area.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-area.mdx
new file mode 100644
index 0000000..7633c8a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-area.mdx
@@ -0,0 +1,151 @@
+---
+title: ColorArea 颜色区域
+description: 二维颜色选择器，用户可在渐变区域内选取颜色。
+links:
+  rac: ColorArea
+  source: color-area/color-area.tsx
+  styles: color-area.css
+  storybook: Components/Colors/ColorArea
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ColorArea } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="color-area-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { ColorArea } from '@heroui/react';
+
+export default () => (
+  <ColorArea>
+    <ColorArea.Thumb />
+  </ColorArea>
+);
+```
+
+### 显示点阵
+
+<ComponentPreview
+  name="color-area-with-dots"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="color-area-controlled"
+/>
+
+
+### 颜色空间与通道
+
+使用 `colorSpace` 设置颜色空间（RGB、HSL、HSB），并通过 `xChannel` / `yChannel` prop 自定义横纵轴展示的颜色通道。
+
+<ComponentPreview
+  name="color-area-space-and-channels"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="color-area-disabled"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="color-area-custom-render-function"
+/>
+
+<RelatedComponents component="color-area" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ColorArea } from '@heroui/react';
+
+function CustomColorArea() {
+  return (
+    <ColorArea className="max-w-72 rounded-3xl">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ColorArea 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .color-area {
+    @apply rounded-3xl;
+  }
+
+  .color-area__thumb {
+    @apply size-5 border-4;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ColorArea 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)）：
+
+#### 基础类
+- `.color-area` - 基础样式，含渐变背景与内阴影
+- `.color-area--show-dots` - 叠加点阵网格，便于精确取色
+
+#### 元素类
+- `.color-area__thumb` - 可拖动的 thumb 指示器
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性：
+
+- **禁用**：`[data-disabled="true"]`
+- **聚焦**：`[data-focus-visible="true"]`
+- **拖拽**：`[data-dragging="true"]`（仅 thumb）
+
+## API 参考
+
+### ColorArea Props
+
+继承自 [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string \| Color` | - | 当前颜色值（受控）。 |
+| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控）。 |
+| `onChange` | `(color: Color) => void` | - | 拖拽过程中颜色变化时调用的事件处理函数。 |
+| `onChangeEnd` | `(color: Color) => void` | - | 用户结束拖拽时调用的事件处理函数。 |
+| `xChannel` | `ColorChannel` | `"saturation"` | 水平轴对应的颜色通道。 |
+| `yChannel` | `ColorChannel` | `"brightness"` | 垂直轴对应的颜色通道。 |
+| `colorSpace` | `ColorSpace` | - | 通道所在的颜色空间。 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 ColorArea。 |
+| `showDots` | `boolean` | `false` | 是否显示点阵网格叠加层。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ColorArea.Thumb Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-field.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-field.mdx
new file mode 100644
index 0000000..9e0dd77
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-field.mdx
@@ -0,0 +1,403 @@
+---
+title: ColorField 颜色输入框
+description: 基于 React Aria ColorField 的颜色输入字段，包含标签、说明与校验能力。
+links:
+  rac: ColorField
+  source: color-field/color-field.tsx
+  styles: color-field.css
+  storybook: Components/Colors/ColorField
+---
+
+## 引入
+
+```tsx
+import { ColorField, parseColor } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="color-field-basic" />
+
+### 组件结构
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
+
+export default () => (
+  <ColorField>
+    <Label />
+    <ColorField.Group>
+      <ColorField.Prefix>
+        <ColorSwatch color="#000000" />
+      </ColorField.Prefix>
+      <ColorField.Input />
+    </ColorField.Group>
+    <Description />
+    <FieldError />
+  </ColorField>
+)
+```
+
+> **ColorField** 将标签、颜色输入、说明与错误信息组合为单个可访问组件。
+
+### 带说明
+
+<ComponentPreview name="color-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="color-field-required" />
+
+### 校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
+
+<ComponentPreview name="color-field-invalid" />
+
+### 通道编辑
+
+通过设置 `colorSpace` 与 `channel`，ColorField 支持编辑单个颜色通道（hue、saturation、lightness、红、绿、蓝、alpha）。
+
+<ComponentPreview name="color-field-channel-editing" />
+
+### 受控
+
+控制数值以与其他组件或状态管理同步。
+
+<ComponentPreview name="color-field-controlled" />
+
+### 禁用状态
+
+<ComponentPreview name="color-field-disabled" />
+
+### 全宽
+
+<ComponentPreview name="color-field-full-width" />
+
+### 变体
+
+ColorField.Group 支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+
+<ComponentPreview name="color-field-variants" />
+
+### On Surface
+
+在 [Surface](/docs/components/surface) 内使用时，请在 ColorField.Group 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="color-field-on-surface" />
+
+### 表单示例
+
+包含校验与提交处理的完整表单示例。
+
+<ComponentPreview name="color-field-form-example" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="color-field-custom-render-function"
+/>
+
+<RelatedComponents component="colorfield" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
+
+function CustomColorField() {
+  return (
+    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Brand Color
+      </Label>
+      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <ColorField.Prefix>
+          <ColorSwatch color="#3B82F6" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+      <Description className="text-xs text-default-500">
+        Select your brand's primary color.
+      </Description>
+    </ColorField>
+  );
+}
+```
+
+### 自定义组件类
+
+ColorField 的默认样式非常克制。你可以覆盖 `.color-field` 类来自定义容器样式。
+
+```css
+@layer components {
+  .color-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS 类
+
+- `.color-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
+
+> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。ColorField.Group 的样式见下文 API 参考中的 **ColorField.Group Styling** 小节。
+
+### 交互状态
+
+ColorField 会根据状态自动管理以下 data 属性：
+
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽
+- **Required**：`[data-required="true"]` – 当 `isRequired` 为 true 时应用
+- **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用
+- **Focus Within**：`[data-focus-within="true"]` – 当任意子输入聚焦时应用
+
+## API 参考
+
+### ColorField Props
+
+ColorField 继承 React Aria [ColorField](https://react-aria.adobe.com/ColorField.md) 组件的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | 子组件（Label、ColorField.Group 等）或渲染函数。 |
+| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 颜色字段是否占满容器宽度 |
+| `id` | `string` | - | 元素的唯一标识符。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `Color \| null` | - | 当前值（受控）。 |
+| `defaultValue` | `Color \| null` | - | 默认值（非受控）。 |
+| `onChange` | `(color: Color \| null) => void` | - | 值变化时触发的事件处理函数。 |
+
+#### Channel Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `colorSpace` | `ColorSpace` | - | 当提供 `channel` 时，颜色字段所处的色彩空间。 |
+| `channel` | `ColorChannel` | - | 要编辑的颜色通道。未提供时编辑十六进制值。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 |
+| `isInvalid` | `boolean` | - | 当前值是否无效。 |
+| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+| `isWheelDisabled` | `boolean` | - | 是否禁用滚轮改变数值。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 |
+| `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 |
+| `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 |
+| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
+
+### Composition Components
+
+ColorField 需要与以下独立组件组合使用，请分别导入并直接使用：
+
+- **Label** – 字段标签组件（`@heroui/react`）
+- **ColorField.Group** – 颜色输入分组组件（见下文）
+- **ColorField.Input** – ColorField.Group 内的输入元素
+- **ColorField.Prefix** / **ColorField.Suffix** – 输入组的前缀与后缀插槽
+- **ColorSwatch** – 颜色预览组件（`@heroui/react`）
+- **Description** – 辅助说明文本组件（`@heroui/react`）
+- **FieldError** – 校验错误信息组件（`@heroui/react`）
+
+这些组件各自拥有 props API。请直接在 ColorField 内组合使用：
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
+
+<ColorField
+  isRequired
+  isInvalid={hasError}
+  value={color}
+  onChange={setColor}
+>
+  <Label>Brand Color</Label>
+  <ColorField.Group>
+    <ColorField.Prefix>
+      <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} />
+    </ColorField.Prefix>
+    <ColorField.Input />
+  </ColorField.Group>
+  <Description>Select your brand's primary color.</Description>
+  <FieldError>Please enter a valid color.</FieldError>
+</ColorField>
+```
+
+### Color Types
+
+ColorField 使用来自 React Aria Components 的 `Color` 对象：
+
+```tsx
+import {parseColor} from '@heroui/react';
+
+// Parse from hex string
+const color = parseColor('#3B82F6');
+
+// Get hex string from color
+const hex = color.toString('hex'); // "#3b82f6"
+
+// Get RGB values
+const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
+
+// Use in ColorField
+<ColorField value={color} onChange={setColor}>
+  {/* ... */}
+</ColorField>
+```
+
+### ColorFieldRenderProps
+
+在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦。 |
+| `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 |
+
+### ColorField.Group Props
+
+ColorField.Group 接受 React Aria `Group` 组件的全部 props，以及：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `fullWidth` | `boolean` | `false` | 颜色输入组是否占满容器宽度 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ColorField.Input Props
+
+ColorField.Input 接受 React Aria `Input` 组件的全部 props，以及：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `placeholder` | `string` | - | 为空时显示的占位符文本。 |
+
+### ColorField.Prefix Props
+
+ColorField.Prefix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 前缀插槽中要展示的内容。 |
+
+### ColorField.Suffix Props
+
+ColorField.Suffix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 后缀插槽中要展示的内容。 |
+
+## ColorField.Group Styling
+
+### 自定义组件类
+
+基础类会作用于每个实例。你可以在 `@layer components` 中一次性覆盖它们。
+
+```css
+@layer components {
+  .color-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .color-input-group__input {
+    @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .color-input-group__prefix,
+  .color-input-group__suffix {
+    @apply shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### ColorField.Group CSS Classes
+
+- `.color-input-group` – 根容器样式
+- `.color-input-group__input` – 输入区域包裹样式
+- `.color-input-group__prefix` – 前缀元素样式
+- `.color-input-group__suffix` – 后缀元素样式
+
+### ColorField.Group Interactive States
+
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Focus Within**：`[data-focus-within="true"]` 或 `:focus-within`
+- **Invalid**：`[data-invalid="true"]`（也会与 `aria-invalid` 同步）
+- **Disabled**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-picker.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-picker.mdx
new file mode 100644
index 0000000..f83c749
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-picker.mdx
@@ -0,0 +1,201 @@
+---
+title: ColorPicker 颜色选择器
+description: 可组合的 ColorPicker，在多个颜色组件之间同步颜色值。
+links:
+  rac: ColorPicker
+  source: color-picker/color-picker.tsx
+  styles: color-picker.css
+  storybook: Components/Pickers/ColorPicker
+  figma: true
+---
+
+## 引入
+
+```tsx
+import {
+  ColorPicker,
+  ColorArea,
+  ColorSlider,
+  ColorSwatch,
+  ColorField,
+  ColorSwatchPicker,
+} from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### 组件结构
+
+ColorPicker 是一个可组合组件，会组合多个颜色相关子组件：
+
+```tsx
+import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
+
+export default () => (
+  <ColorPicker defaultValue="#0485F7">
+    <ColorPicker.Trigger>
+      <ColorSwatch />
+      <Label>Pick a color</Label>
+    </ColorPicker.Trigger>
+    <ColorPicker.Popover>
+      <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
+        <ColorArea.Thumb />
+      </ColorArea>
+      <ColorSlider channel="hue" colorSpace="hsb">
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    </ColorPicker.Popover>
+  </ColorPicker>
+);
+```
+
+### 受控
+
+<ComponentPreview
+  name="color-picker-controlled"
+/>
+
+### 带 swatch
+
+<ComponentPreview
+  name="color-picker-with-swatches"
+/>
+
+### 带输入字段
+
+使用 `ColorField` 让用户编辑各个颜色通道的数值，并可配合 `Select` 切换色彩空间。
+
+<ComponentPreview
+  name="color-picker-with-fields"
+/>
+
+### 带滑块
+
+使用多个 `ColorSlider` 来调整颜色值的各个通道。
+
+<ComponentPreview
+  name="color-picker-with-sliders"
+/>
+
+<RelatedComponents component="color-picker" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
+
+function CustomColorPicker() {
+  return (
+    <ColorPicker defaultValue="#0485F7">
+      <ColorPicker.Trigger className="gap-4">
+        <ColorSwatch className="rounded-lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="p-4 rounded-xl">
+        <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
+          <ColorArea.Thumb />
+        </ColorArea>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ColorPicker 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .color-picker {
+    @apply inline-flex;
+  }
+
+  .color-picker__trigger {
+    @apply inline-flex items-center gap-4 rounded-lg;
+  }
+
+  .color-picker__popover {
+    @apply p-4 rounded-xl;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ColorPicker 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)）：
+
+#### 基础类
+- `.color-picker` - 基础容器
+- `.color-picker__trigger` - 触发按钮
+- `.color-picker__popover` - Popover 容器
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：`:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### ColorPicker Props
+
+继承自 [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string \| Color` | - | 当前颜色值（受控） |
+| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
+| `onChange` | `(color: Color) => void` | - | 颜色变化时触发的事件处理函数 |
+| `children` | `React.ReactNode` | - | 颜色选择器内容（Trigger、Popover 等） |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### ColorPicker.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | 触发器内容或渲染 prop |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### ColorPicker.Popover Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `placement` | `Placement` | `"bottom left"` | Popover 的放置位置 |
+| `children` | `React.ReactNode` | - | Popover 内容 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### Related Types
+
+#### Color
+
+表示颜色值。完整 API 见 [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color)。
+
+| Method | 描述 |
+|--------|------|
+| `toString(format)` | 将颜色转换为指定格式的字符串（hex、rgb、hsl、hsb、css） |
+| `toFormat(format)` | 将颜色转换为指定格式并返回新的 Color 对象 |
+| `getChannelValue(channel)` | 返回指定通道的数值 |
+| `withChannelValue(channel, value)` | 设置通道数值并返回新的 Color |
+
+#### parseColor
+
+```tsx
+import { parseColor } from 'react-aria-components';
+
+// Parse from string
+const color = parseColor('#ff0000');
+const hslColor = parseColor('hsl(0, 100%, 50%)');
+```
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-slider.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-slider.mdx
new file mode 100644
index 0000000..ccb2017
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-slider.mdx
@@ -0,0 +1,231 @@
+---
+title: ColorSlider 颜色滑块
+description: ColorSlider 允许用户调整颜色值的单个通道。
+links:
+  rac: ColorSlider
+  source: color-slider/color-slider.tsx
+  styles: color-slider.css
+  storybook: Components/Colors/ColorSlider
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="color-slider-basic"
+/>
+
+### 组件结构
+
+导入 ColorSlider 组件后，可通过点号访问各个子部分。
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+
+export default () => (
+  <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)">
+    <Label>Hue</Label>
+    <ColorSlider.Output />
+    <ColorSlider.Track>
+      <ColorSlider.Thumb />
+    </ColorSlider.Track>
+  </ColorSlider>
+)
+```
+### Vertical
+
+<ComponentPreview
+  name="color-slider-vertical"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="color-slider-disabled"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="color-slider-controlled"
+/>
+
+### HSL Channels
+
+使用多个 ColorSlider 控制同一颜色值的不同通道。这些滑块可以共享同一个颜色值，从而组成完整的颜色选择器。
+
+<ComponentPreview
+  name="color-slider-channels"
+/>
+
+### Alpha Channel
+
+alpha 通道滑块会显示透明度棋盘格背景，以帮助可视化透明度。
+
+<ComponentPreview
+  name="color-slider-alpha-channel"
+/>
+
+### RGB Channels
+
+你也可以使用 RGB 色彩空间，并分别控制红、绿、蓝通道。
+
+<ComponentPreview
+  name="color-slider-rgb-channels"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="color-slider-custom-render-function"
+/>
+
+<RelatedComponents component="color-slider" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+
+function CustomColorSlider() {
+  return (
+    <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" className="w-full">
+      <Label>Hue</Label>
+      <ColorSlider.Output className="text-muted text-sm" />
+      <ColorSlider.Track className="h-6 rounded-full">
+        <ColorSlider.Thumb className="size-5 rounded-full border-2 border-white" />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ColorSlider 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .color-slider {
+    @apply flex flex-col gap-2;
+  }
+
+  .color-slider__output {
+    @apply text-muted text-sm;
+  }
+
+  .color-slider__track {
+    @apply relative h-5 w-full rounded-full;
+  }
+
+  .color-slider__thumb {
+    @apply size-4 rounded-full border-3 border-white shadow-overlay;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ColorSlider 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)）：
+
+#### 基础类
+- `.color-slider` - 基础滑块容器
+- `.color-slider__output` - 显示当前数值的输出元素
+- `.color-slider__track` - 带颜色渐变的轨道元素
+- `.color-slider__thumb` - 显示当前颜色的滑块（thumb）
+
+#### 状态类
+- `.color-slider[data-disabled="true"]` - 禁用状态
+- `.color-slider[data-orientation="vertical"]` - 纵向方向
+- `.color-slider__thumb[data-dragging="true"]` - 正在拖动 thumb
+- `.color-slider__thumb[data-focus-visible="true"]` - thumb 的键盘焦点
+- `.color-slider__thumb[data-disabled="true"]` - thumb 禁用状态
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+
+- **Hover**：thumb 上 `:hover` 或 `[data-hovered="true"]`
+- **Focus**：thumb 上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Dragging**：thumb 上 `[data-dragging="true"]`
+- **Disabled**：滑块或 thumb 上 `:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### ColorSlider Props
+
+继承自 [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `channel` | `ColorChannel` | - | 滑块操作的通道（hue、saturation、lightness、brightness、alpha、red、green、blue） |
+| `colorSpace` | `ColorSpace` | - | 色彩空间（hsl、hsb、rgb）。默认取当前值的色彩空间 |
+| `value` | `string \| Color` | - | 当前颜色值（受控） |
+| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
+| `onChange` | `(value: Color) => void` | - | 拖动过程中数值变化时触发的事件处理函数 |
+| `onChangeEnd` | `(value: Color) => void` | - | 拖动结束时触发的事件处理函数 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 滑块方向 |
+| `isDisabled` | `boolean` | - | 是否禁用滑块 |
+| `name` | `string` | - | 用于表单提交的 input 名称 |
+| `aria-label` | `string` | - | 滑块的无障碍标签 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或渲染函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ColorSlider.Output Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 输出内容或渲染函数 |
+
+### ColorSlider.Track Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `style` | `CSSProperties \| RenderFunction` | - | 行内样式或渲染函数 |
+| `children` | `ReactNode \| RenderFunction` | - | 轨道内容或渲染函数 |
+
+### ColorSlider.Thumb Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `style` | `CSSProperties \| RenderFunction` | - | 行内样式或渲染函数 |
+| `children` | `ReactNode \| RenderFunction` | - | thumb 内容或渲染函数 |
+
+### RenderProps
+
+使用渲染函数时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `state` | `ColorSliderState` | ColorSlider 的状态 |
+| `color` | `Color` | 当前颜色值 |
+| `orientation` | `"horizontal" \| "vertical"` | 滑块方向 |
+| `isDisabled` | `boolean` | 是否禁用滑块 |
+
+## 无障碍
+
+ColorSlider 实现了 ARIA slider 模式，并提供：
+
+- 完整的键盘导航支持（方向键、Home、End、Page Up/Down）
+- 屏幕阅读器对数值变化的播报
+- 合理的焦点管理
+- 禁用状态支持
+- 通过隐藏 input 元素与 HTML 表单集成
+- 结合区域设置进行数值格式化的国际化支持
+
+更多信息见 [React Aria ColorSlider 文档](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-swatch-picker.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-swatch-picker.mdx
new file mode 100644
index 0000000..b551bdd
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-swatch-picker.mdx
@@ -0,0 +1,232 @@
+---
+title: ColorSwatchPicker 颜色色块选择器
+description: 允许用户从预置调色板中选择颜色的 swatch 列表。
+links:
+  rac: ColorSwatchPicker
+  source: color-swatch-picker/color-swatch-picker.tsx
+  styles: color-swatch-picker.css
+  storybook: Components/Colors/ColorSwatchPicker
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ColorSwatchPicker, parseColor } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="color-swatch-picker-basic"
+/>
+
+### 组件结构
+
+导入 ColorSwatchPicker 组件，并通过点语法访问所有子部分。
+
+```tsx
+import { ColorSwatchPicker } from '@heroui/react';
+
+export default () => (
+  <ColorSwatchPicker>
+    <ColorSwatchPicker.Item color="#F43F5E">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+    <ColorSwatchPicker.Item color="#D946EF">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+    <ColorSwatchPicker.Item color="#8B5CF6">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+  </ColorSwatchPicker>
+);
+```
+
+### 变体
+
+<ComponentPreview
+  name="color-swatch-picker-variants"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="color-swatch-picker-sizes"
+/>
+
+### 堆叠布局
+
+<ComponentPreview
+  name="color-swatch-picker-stack-layout"
+/>
+
+### 默认值
+
+<ComponentPreview
+  name="color-swatch-picker-default-value"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="color-swatch-picker-controlled"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="color-swatch-picker-disabled"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="color-swatch-picker-custom-indicator"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="color-swatch-picker-custom-render-function"
+/>
+
+<RelatedComponents component="color-swatch-picker" />
+
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以使用 `className` props 自定义 ColorSwatchPicker：
+
+```tsx
+import { ColorSwatchPicker } from '@heroui/react';
+
+function CustomColorSwatchPicker() {
+  return (
+    <ColorSwatchPicker className="gap-4">
+      <ColorSwatchPicker.Item color="#F43F5E" className="shadow-lg">
+        <ColorSwatchPicker.Swatch />
+      </ColorSwatchPicker.Item>
+      <ColorSwatchPicker.Item color="#D946EF">
+        <ColorSwatchPicker.Swatch />
+      </ColorSwatchPicker.Item>
+    </ColorSwatchPicker>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ColorSwatchPicker 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-swatch-picker {
+    @apply gap-4;
+  }
+
+  .color-swatch-picker__item {
+    @apply shadow-md;
+  }
+
+  .color-swatch-picker__swatch {
+    @apply border-2 border-white;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ColorSwatchPicker 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)）：
+
+#### 基础与结构
+
+- `.color-swatch-picker` - 基础容器（flex 布局）
+- `.color-swatch-picker__item` - 单个 swatch 包裹层
+- `.color-swatch-picker__swatch` - swatch 视觉元素
+
+#### 尺寸类
+
+- `.color-swatch-picker--xs` - 特小（16px）
+- `.color-swatch-picker--sm` - 小（24px）
+- `.color-swatch-picker--md` - 中（32px，默认）
+- `.color-swatch-picker--lg` - 大（36px）
+- `.color-swatch-picker--xl` - 特大（40px）
+
+#### 形状变体
+
+- `.color-swatch-picker--circle` - 圆形（默认）
+- `.color-swatch-picker--square` - 圆角方形
+
+#### 布局类
+
+- `.color-swatch-picker--grid` - 横向换行网格（默认）
+- `.color-swatch-picker--stack` - 纵向堆叠
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，以便灵活控制状态：
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]` — 缩放至 1.1（仅在未选中时）
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 焦点环
+- **已选中**：`[data-selected="true"]` — 与 swatch 同色的内边框
+- **禁用**：`[data-disabled="true"]` — 降低透明度
+
+## API 参考
+
+### ColorSwatchPicker Props
+
+继承自 [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string \| Color` | - | 当前选中颜色（受控） |
+| `defaultValue` | `string \| Color` | - | 默认选中颜色（非受控） |
+| `onChange` | `(value: Color) => void` | - | 选中变化时调用的处理函数 |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch 尺寸 |
+| `variant` | `"circle" \| "square"` | `"circle"` | swatch 形状 |
+| `layout` | `"grid" \| "stack"` | `"grid"` | 布局方向 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `React.ReactNode` | - | ColorSwatchPicker.Item 元素 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### ColorSwatchPicker.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `color` | `string \| Color` | **必填** | swatch 颜色 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该项 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch 元素 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### ColorSwatchPicker.Swatch Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### parseColor
+
+为方便使用，从 React Aria Components 重新导出 `parseColor` 函数：
+
+```tsx
+import { parseColor } from '@heroui/react';
+
+// 解析十六进制颜色
+const red = parseColor('#ff0000');
+
+// 解析 RGB
+const green = parseColor('rgb(0, 255, 0)');
+
+// 解析 HSL
+const blue = parseColor('hsl(240, 100%, 50%)');
+```
diff --git a/apps/docs/content/docs/cn/react/components/(colors)/color-swatch.mdx b/apps/docs/content/docs/cn/react/components/(colors)/color-swatch.mdx
new file mode 100644
index 0000000..d460949
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(colors)/color-swatch.mdx
@@ -0,0 +1,147 @@
+---
+title: ColorSwatch 颜色色块
+description: 颜色值的视觉预览，并提供无障碍支持。
+links:
+  rac: ColorSwatch
+  source: color-swatch/color-swatch.tsx
+  styles: color-swatch.css
+  storybook: Components/Colors/ColorSwatch
+---
+
+## 引入
+
+```tsx
+import { ColorSwatch } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="color-swatch-basic"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="color-swatch-sizes"
+/>
+
+### Shapes
+
+<ComponentPreview
+  name="color-swatch-shapes"
+/>
+
+### Transparency
+
+<ComponentPreview
+  name="color-swatch-transparency"
+/>
+
+### Custom Styles with Render Props
+
+你可以使用 `style` 渲染 prop 来读取颜色值并创建自定义视觉效果。
+
+<ComponentPreview
+  name="color-swatch-custom-styles"
+/>
+
+### Accessibility
+
+使用 `colorName` 为颜色提供自定义可访问名称，并使用 `aria-label` 补充颜色用途的上下文。
+
+<ComponentPreview
+  name="color-swatch-accessibility"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="color-swatch-custom-render-function"
+/>
+
+<RelatedComponents component="color-swatch" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {ColorSwatch} from '@heroui/react';
+
+function CustomColorSwatch() {
+  return (
+    <ColorSwatch
+      className="size-12 rounded-lg"
+      color="#0485F7"
+    />
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ColorSwatch 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .color-swatch {
+    @apply border-2 border-white;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ColorSwatch 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)）：
+
+#### 基础类
+- `.color-swatch` - 基础 swatch（色板）样式，透明区域使用棋盘格背景
+
+#### 形状类
+- `.color-swatch--circle` - 圆形（默认）
+- `.color-swatch--square` - 圆角方形
+
+#### 尺寸类
+- `.color-swatch--xs` - 特小（16px）
+- `.color-swatch--sm` - 小（24px）
+- `.color-swatch--md` - 中（32px，默认）
+- `.color-swatch--lg` - 大（36px）
+- `.color-swatch--xl` - 特大（40px）
+
+## API 参考
+
+### ColorSwatch Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `color` | `string \| Color` | - | 要展示的颜色值（hex、rgb、hsl 等） |
+| `colorName` | `string` | - | 颜色的可访问名称（会覆盖自动生成的描述） |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `shape` | `"circle" \| "square"` | `"circle"` | swatch（色板）形状 |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch（色板）尺寸 |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式，或带颜色访问能力的渲染 prop 函数 |
+| `aria-label` | `string` | - | swatch 的无障碍标签 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Style Render Props
+
+当把 `style` 作为函数传入时，你会获得包含颜色对象在内的渲染参数：
+
+```tsx
+<ColorSwatch
+  color="#0485F7"
+  style={({ color }) => ({
+    boxShadow: `0 4px 14px ${color.toString("css")}80`,
+  })}
+/>
+```
+
+`color` 对象提供例如：
+
+- `color.toString("css")` - 返回 CSS 颜色字符串
+- `color.toString("hex")` - 返回十六进制颜色字符串
+- `color.getChannelValue("alpha")` - 返回 alpha 通道数值
diff --git a/apps/docs/content/docs/cn/react/components/(controls)/slider.mdx b/apps/docs/content/docs/cn/react/components/(controls)/slider.mdx
new file mode 100644
index 0000000..e44e6e9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(controls)/slider.mdx
@@ -0,0 +1,379 @@
+---
+title: Slider 滑块
+description: Slider 允许用户在范围内选择一个或多个值。
+links:
+  rac: Slider
+  source: slider/slider.tsx
+  styles: slider.css
+  storybook: Components/Controls/Slider
+---
+
+## 引入
+
+```tsx
+import { Slider } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="slider-default"
+/>
+
+### 组件结构
+
+引入 Slider 组件，并通过点语法访问各部分。
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+export default () => (
+  <Slider>
+    <Label />
+    <Slider.Output />
+    <Slider.Track>
+      <Slider.Fill />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider>
+)
+```
+
+### 范围滑块组件结构
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+export default () => (
+  <Slider defaultValue={[25, 75]}>
+    <Label />
+    <Slider.Output />
+    <Slider.Track>
+      {({state}) => (
+        <>
+          <Slider.Fill />
+          {state.values.map((_, i) => (
+            <Slider.Thumb key={i} index={i} />
+          ))}
+        </>
+      )}
+    </Slider.Track>
+  </Slider>
+)
+```
+
+### 纵向
+
+<ComponentPreview
+  name="slider-vertical"
+/>
+
+### 范围
+
+<ComponentPreview
+  name="slider-range"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="slider-disabled"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="slider-custom-render-function"
+/>
+
+<RelatedComponents component="slider" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+function CustomSlider() {
+  return (
+    <Slider className="w-full">
+      <Label>Volume</Label>
+      <Slider.Output className="text-muted-fg text-sm" />
+      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
+        <Slider.Fill className="bg-accent" />
+        <Slider.Thumb className="size-4 rounded-full bg-accent" />
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Slider 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .slider {
+    @apply flex flex-col gap-2;
+  }
+
+  .slider__output {
+    @apply text-muted-fg text-sm;
+  }
+
+  .slider-track {
+    @apply relative h-2 w-full rounded-full bg-surface-secondary;
+  }
+
+  .slider-fill {
+    @apply absolute h-full rounded-full bg-accent;
+  }
+
+  .slider-thumb {
+    @apply size-4 rounded-full bg-accent border-2 border-background;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)）：
+
+#### 基础类
+- `.slider` - Slider 根容器
+- `.slider__output` - 显示当前值的输出元素
+- `.slider-track` - 包含填充与滑块的轨道元素
+- `.slider-fill` - 显示已选范围的填充元素
+- `.slider-thumb` - 单个滑块控制点
+
+#### 状态类
+- `.slider[data-disabled="true"]` - 禁用状态
+- `.slider[data-orientation="vertical"]` - 纵向方向
+- `.slider-thumb[data-dragging="true"]` - 滑块正在拖动
+- `.slider-thumb[data-focus-visible="true"]` - 滑块键盘聚焦
+- `.slider-thumb[data-disabled="true"]` - 滑块禁用状态
+- `.slider-track[data-fill-start="true"]` - 填充从起点开始
+- `.slider-track[data-fill-end="true"]` - 填充在终点结束
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+
+- **悬停**：滑块上的 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：滑块上的 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **拖动**：滑块上的 `[data-dragging="true"]`
+- **禁用**：Slider 或滑块上的 `:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### Slider Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `number \| number[]` | - | 当前值（受控）。 |
+| `defaultValue` | `number \| number[]` | - | 默认值（非受控）。 |
+| `onChange` | `(value: number \| number[]) => void` | - | 值变化时的事件处理函数。 |
+| `onChangeEnd` | `(value: number \| number[]) => void` | - | 拖动结束时的事件处理函数。 |
+| `minValue` | `number` | `0` | Slider 的最小值。 |
+| `maxValue` | `number` | `100` | Slider 的最大值。 |
+| `step` | `number` | `1` | Slider 的步进值。 |
+| `formatOptions` | `Intl.NumberFormatOptions` | - | 数值标签的显示格式。 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Slider 的方向。 |
+| `isDisabled` | `boolean` | - | Slider 是否禁用。 |
+| `aria-label` | `string` | - | Slider 的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 标注 Slider 的元素 ID。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | Slider 内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Slider.Output Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 输出内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Slider.Track Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 轨道内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Slider.Fill Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `style` | `CSSProperties` | - | 行内样式。 |
+
+### Slider.Thumb Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `index` | `number` | `0` | 滑块在 Slider 内的索引。 |
+| `isDisabled` | `boolean` | - | 该滑块是否禁用。 |
+| `name` | `string` | - | 输入元素名称，用于提交 HTML 表单。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### RenderProps
+
+对 `Slider.Output` 或 `Slider.Track` 使用渲染函数时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `state` | `SliderState` | Slider 的状态。 |
+| `values` | `number[]` | 按滑块索引管理的数值。 |
+| `getThumbValueLabel` | `(index: number) => string` | 返回指定滑块数值的字符串标签。 |
+| `orientation` | `"horizontal" \| "vertical"` | Slider 的方向。 |
+| `isDisabled` | `boolean` | Slider 是否禁用。 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={30}>
+  <Label>Volume</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### 范围滑块
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider
+  defaultValue={[100, 500]}
+  formatOptions={{style: "currency", currency: "USD"}}
+  maxValue={1000}
+  minValue={0}
+  step={50}
+>
+  <Label>Price Range</Label>
+  <Slider.Output />
+  <Slider.Track>
+    {({state}) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+### 受控值
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledSlider() {
+  const [value, setValue] = useState(25);
+
+  return (
+    <>
+      <Slider value={value} onChange={setValue}>
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+      <p>Current value: {value}</p>
+    </>
+  );
+}
+```
+
+### 自定义数值格式
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider
+  defaultValue={60}
+  formatOptions={{style: "currency", currency: "USD"}}
+>
+  <Label>Price</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### 纵向方向
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={30} orientation="vertical" aria-label="Volume">
+  <Label>Volume</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### 自定义输出展示
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={[25, 75]}>
+  <Label>Range</Label>
+  <Slider.Output>
+    {({state}) =>
+      state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ')
+    }
+  </Slider.Output>
+  <Slider.Track>
+    {({state}) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+## 无障碍
+
+Slider 组件实现 ARIA slider 模式，并提供：
+
+- 完整的键盘导航支持（方向键、Home、End、Page Up/Down）
+- 数值变化时的屏幕阅读器播报
+- 合理的焦点管理
+- 禁用状态支持
+- 通过隐藏 input 元素与 HTML 表单集成
+- 结合区域设置进行数值格式化的国际化支持
+- 从右到左（RTL）语言支持
+
+更多信息见 [React Aria Slider 文档](https://react-spectrum.adobe.com/react-aria/Slider.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(controls)/switch.mdx b/apps/docs/content/docs/cn/react/components/(controls)/switch.mdx
new file mode 100644
index 0000000..d7026e1
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(controls)/switch.mdx
@@ -0,0 +1,340 @@
+---
+title: Switch 开关
+description: 用于布尔状态的开关组件。
+icon: updated
+links:
+  rac: SwitchField
+  source: switch/switch.tsx
+  styles: switch.css
+  storybook: Components/Controls/Switch
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="switch-basic"
+/>
+
+### 组件结构
+
+引入 Switch 组件，并通过点语法访问各部分。
+
+```tsx
+import { Switch, Description, FieldError } from '@heroui/react';
+
+export default () => (
+  <Switch>
+    <Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb>
+          <Switch.Icon /> {/* 可选 */}
+        </Switch.Thumb>
+      </Switch.Control>
+      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
+    </Switch.Content>
+    <Description /> {/* 可选 — 字段级帮助文本 */}
+    <FieldError /> {/* 可选 — 校验错误信息 */}
+  </Switch>
+);
+```
+
+要对多个 Switch 进行分组，请使用 `SwitchGroup` 组件：
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+
+export default () => (
+  <SwitchGroup>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Option 1
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Option 2
+      </Switch.Content>
+    </Switch>
+  </SwitchGroup>
+);
+```
+
+### 禁用
+
+<ComponentPreview
+  name="switch-disabled"
+/>
+
+### 默认选中
+
+<ComponentPreview
+  name="switch-default-selected"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="switch-controlled"
+/>
+
+### 无标签
+
+<ComponentPreview
+  name="switch-without-label"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="switch-sizes"
+/>
+
+### 标签位置
+
+<ComponentPreview
+  name="switch-label-position"
+/>
+
+### 带图标
+
+<ComponentPreview
+  name="switch-with-icons"
+/>
+
+### 带描述
+
+<ComponentPreview
+  name="switch-with-description"
+/>
+
+### 分组
+
+<ComponentPreview
+  name="switch-group"
+/>
+
+### 横向分组
+
+<ComponentPreview
+  name="switch-group-horizontal"
+/>
+
+### Render Props
+
+<ComponentPreview
+  name="switch-render-props"
+/>
+
+### 表单集成
+
+<ComponentPreview
+  name="switch-form"
+/>
+
+### 自定义样式
+
+<ComponentPreview
+  name="switch-custom-styles"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="switch-custom-render-function"
+/>
+
+<RelatedComponents component="switch" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以自定义各个 Switch：
+
+```tsx
+import { Switch, Label } from '@heroui/react';
+
+function CustomSwitch() {
+  return (
+    <Switch>
+      {({isSelected}) => (
+        <>
+          <Switch.Control
+            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
+          >
+            <Switch.Thumb
+              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
+            />
+          </Switch.Control>
+          Custom Switch
+        </>
+      )}
+    </Switch>
+  );
+}
+```
+
+或自定义 SwitchGroup 布局：
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+
+function CustomSwitchGroup() {
+  return (
+    <SwitchGroup className="gap-8" orientation="horizontal">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Option 1
+        </Switch.Content>
+      </Switch>
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Option 2
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Switch 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .switch {
+    @apply inline-flex gap-3 items-center;
+  }
+
+  .switch__control {
+    @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
+  }
+
+  .switch__thumb {
+    @apply bg-white shadow-sm;
+  }
+
+  .switch__content {
+    @apply items-center gap-3;
+  }
+
+  .switch__icon {
+    @apply h-3 w-3 text-current;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+#### Switch 类
+
+Switch 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)）：
+
+- `.switch` - Switch 根容器（字段）
+- `.switch__content` - 包裹控件与标签文本的可点击 label
+- `.switch__control` - Switch 轨道
+- `.switch__thumb` - 可移动的滑块
+- `.switch__icon` - 滑块内可选图标
+- `.switch--sm` - 小尺寸变体
+- `.switch--md` - 中尺寸变体（默认）
+- `.switch--lg` - 大尺寸变体
+
+#### SwitchGroup 类
+
+SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)）：
+
+- `.switch-group` - Switch 组容器
+- `.switch-group__items` - Switch 项容器
+- `.switch-group--horizontal` - 横向布局
+- `.switch-group--vertical` - 纵向布局（默认）
+
+### 交互状态
+
+该 Switch 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+
+- **已选中**：`[data-selected="true"]`（滑块位置与背景色变化）
+- **悬停**：`:hover` 或 `[data-hovered="true"]`（作用于 `Switch.Control` / 按钮）
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（在按钮上显示轨道焦点环）
+- **禁用**：`[data-disabled="true"]`（降低透明度，包括帮助文本）
+- **按压**：`:active` 或 `[data-pressed="true"]`
+
+## API 参考
+
+### Switch Props
+
+继承自 [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch 尺寸。 |
+| `isSelected` | `boolean` | `false` | Switch 是否打开。 |
+| `defaultSelected` | `boolean` | `false` | 默认是否打开（非受控）。 |
+| `isDisabled` | `boolean` | `false` | Switch 是否禁用。 |
+| `isInvalid` | `boolean` | `false` | Switch 是否无效。 |
+| `isReadOnly` | `boolean` | `false` | Switch 是否只读。 |
+| `isRequired` | `boolean` | `false` | Switch 是否必须打开。 |
+| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验或 ARIA 校验。 |
+| `name` | `string` | - | 输入元素名称，用于提交 HTML 表单。 |
+| `value` | `string` | - | 输入元素值，用于提交 HTML 表单。 |
+| `onChange` | `(isSelected: boolean) => void` | - | Switch 值变化时的事件处理函数。 |
+| `onPress` | `(e: PressEvent) => void` | - | Switch 被按下时的事件处理函数。 |
+| `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch 内容或字段级渲染 prop。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Switch.Content Props
+
+包裹控件与标签文本的可点击 `<label>`。请把 `Switch.Control` 与 `Label` 放在它内部；`Description`/`FieldError` 作为 `Switch.Content` 的兄弟节点。对于没有标签的 switch，省略 `Label` 并在 `Switch` 上传入 `aria-label`。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: SwitchButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签），或按钮级渲染 prop |
+| `className` | `string \| (values: SwitchButtonRenderProps) => string` | - | 应用到可点击 label 的类名 |
+
+### SwitchFieldRenderProps
+
+在根 `Switch` 上使用渲染 prop 时，提供以下字段级值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | Switch 当前是否打开。 |
+| `isDisabled` | `boolean` | Switch 是否禁用。 |
+| `isReadOnly` | `boolean` | Switch 是否只读。 |
+| `isInvalid` | `boolean` | Switch 是否无效。 |
+| `isRequired` | `boolean` | Switch 是否必填。 |
+| `state` | `ToggleState` | Switch 的状态。 |
+
+### SwitchButtonRenderProps
+
+`Switch.Control` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Switch.Control` 的子元素即可访问。
+
+### SwitchGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Switch 组方向。 |
+| `children` | `React.ReactNode` | - | 要渲染的 Switch 项。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
diff --git a/apps/docs/content/docs/cn/react/components/(data-display)/badge.mdx b/apps/docs/content/docs/cn/react/components/(data-display)/badge.mdx
new file mode 100644
index 0000000..25232d9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(data-display)/badge.mdx
@@ -0,0 +1,197 @@
+---
+title: Badge 徽标
+description: 展示相对其他元素定位的小型指示器，常用于未读数、状态点与标签等场景。
+links:
+  source: badge/badge.tsx
+  styles: badge.css
+  storybook: Components/Data Display/Badge
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Badge } from '@heroui/react';
+```
+
+## 组件结构
+
+Badge 通过 `Badge.Anchor` 相对另一个元素定位。纯文本子节点会自动包在 `<Badge.Label>` 中。
+
+> 若需要独立展示标签，请改用 [Chip](/docs/react/components/chip) 组件。
+
+```tsx
+<Badge.Anchor>
+  <Avatar />
+  <Badge color="danger">5</Badge>
+</Badge.Anchor>
+```
+
+### 用法
+
+<ComponentPreview
+  name="badge-basic"
+/>
+
+### 颜色
+
+<ComponentPreview
+  name="badge-colors"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="badge-sizes"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="badge-variants"
+/>
+
+### 位置
+
+<ComponentPreview
+  name="badge-placements"
+/>
+
+### 带内容
+
+Badge 支持以文本、数字与图标作为内容。未提供子节点时，会渲染为点状指示器。
+
+<ComponentPreview
+  name="badge-with-content"
+/>
+
+### 点状 Badge
+
+空的 Badge 可作为状态指示器，适用于在线/离线状态或活动信号等场景。
+
+<ComponentPreview
+  name="badge-dot"
+/>
+
+<RelatedComponents component="badge" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以为根容器与各插槽分别添加类名：
+
+```tsx
+import {Badge, Avatar} from '@heroui/react';
+
+function CustomBadge() {
+  return (
+    <Badge.Anchor>
+      <Avatar />
+      <Badge className="border-2 border-white" color="danger">
+        <Badge.Label className="font-bold">99+</Badge.Label>
+      </Badge>
+    </Badge.Anchor>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Badge 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .badge {
+    @apply rounded-full text-xs;
+  }
+
+  .badge__label {
+    @apply font-semibold;
+  }
+
+  .badge--accent {
+    @apply shadow-sm;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Badge 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)）：
+
+#### 基础类
+- `.badge` - Badge 容器基础样式
+- `.badge__label` - 标签文本插槽样式
+- `.badge-anchor` - 锚定元素的定位包裹层
+
+#### 颜色类
+- `.badge--accent` - 强调颜色变体
+- `.badge--danger` - 危险颜色变体
+- `.badge--default` - 默认颜色变体
+- `.badge--success` - 成功颜色变体
+- `.badge--warning` - 警告颜色变体
+
+#### 变体类
+- `.badge--primary` - Primary 变体，实心背景
+- `.badge--secondary` - Secondary 变体，默认背景
+- `.badge--soft` - Soft 变体，浅色背景
+
+#### 尺寸类
+- `.badge--sm` - 小尺寸
+- `.badge--md` - 中尺寸（默认）
+- `.badge--lg` - 大尺寸
+
+#### 位置类
+- `.badge--top-right` - 右上角（默认）
+- `.badge--top-left` - 左上角
+- `.badge--bottom-right` - 右下角
+- `.badge--bottom-left` - 左下角
+
+#### 复合变体类
+
+Badge 支持组合变体与颜色类（例如 `.badge--primary.badge--accent`）。以下组合定义了默认样式：
+
+**Primary 变体：**
+- `.badge--primary.badge--accent` - Primary + 强调色，实心背景
+- `.badge--primary.badge--default` - Primary + 默认色，实心背景
+- `.badge--primary.badge--success` - Primary + 成功色，实心背景
+- `.badge--primary.badge--warning` - Primary + 警告色，实心背景
+- `.badge--primary.badge--danger` - Primary + 危险色，实心背景
+
+**Soft 变体：**
+- `.badge--soft.badge--accent` - Soft + 强调色，浅色背景
+- `.badge--soft.badge--default` - Soft + 默认色，浅色背景
+- `.badge--soft.badge--success` - Soft + 成功色，浅色背景
+- `.badge--soft.badge--warning` - Soft + 警告色，浅色背景
+- `.badge--soft.badge--danger` - Soft + 危险色，浅色背景
+
+## API 参考
+
+### Badge Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | Badge 内展示的内容（文本、数字或图标）。省略时渲染为点状指示器。 |
+| `className` | `string` | - | 根元素的额外 CSS 类。 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 颜色变体。 |
+| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | 视觉样式变体。 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸。 |
+| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | 相对锚点的位置。 |
+
+### Badge.Anchor Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 被锚定的元素以及 Badge 本身。 |
+| `className` | `string` | - | 锚点包裹层的额外 CSS 类。 |
+
+### Badge.Label Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 标签文本内容。 |
+| `className` | `string` | - | 标签插槽的额外 CSS 类。 |
diff --git a/apps/docs/content/docs/cn/react/components/(data-display)/chip.mdx b/apps/docs/content/docs/cn/react/components/(data-display)/chip.mdx
new file mode 100644
index 0000000..3a34c0d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(data-display)/chip.mdx
@@ -0,0 +1,163 @@
+---
+title: Chip 标签
+description: 用于展示标签、状态与分类等信息的小型徽标。
+links:
+  source: chip/chip.tsx
+  styles: chip.css
+  storybook: Components/Data Display/Chip
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Chip } from '@heroui/react';
+```
+
+## 组件结构
+
+引入 Chip 组件，并通过点语法访问各部分。
+
+> 纯文本子节点会自动包在 `<Chip.Label>` 中。
+
+```tsx
+<Chip>
+  Label text
+</Chip>
+```
+
+### 用法
+
+<ComponentPreview
+  name="chip-basic"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="chip-variants"
+/>
+
+### 带图标
+
+<ComponentPreview
+  name="chip-with-icon"
+/>
+
+### 状态
+
+<ComponentPreview
+  name="chip-statuses"
+/>
+
+<RelatedComponents component="chip" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以为根容器与各插槽分别添加类名：
+
+```tsx
+import {Chip} from '@heroui/react';
+
+function CustomChip() {
+  return (
+    <Chip className="rounded-full px-4 py-2 font-bold">
+      <Chip.Label className="text-lg uppercase">
+        Custom Styled
+      </Chip.Label>
+    </Chip>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Chip 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .chip {
+    @apply rounded-full text-xs;
+  }
+
+  .chip__label {
+    @apply font-medium;
+  }
+
+  .chip--accent {
+    @apply border-accent/20;
+  }
+
+  .chip--accent .chip__label {
+    @apply text-accent;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Chip 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)）：
+
+#### 基础类
+- `.chip` - Chip 容器基础样式
+- `.chip__label` - 标签文本插槽样式
+
+#### 颜色类
+- `.chip--accent` - 强调颜色变体
+- `.chip--danger` - 危险颜色变体
+- `.chip--default` - 默认颜色变体
+- `.chip--success` - 成功颜色变体
+- `.chip--warning` - 警告颜色变体
+
+#### 变体类
+- `.chip--primary` - Primary 变体，实心背景
+- `.chip--secondary` - Secondary 变体，带边框
+- `.chip--tertiary` - Tertiary 变体，透明背景
+- `.chip--soft` - Soft 变体，浅色背景
+
+#### 尺寸类
+- `.chip--sm` - 小尺寸
+- `.chip--md` - 中尺寸（默认）
+- `.chip--lg` - 大尺寸
+
+#### 复合变体类
+
+Chip 支持组合变体与颜色类（例如 `.chip--secondary.chip--accent`）。以下组合定义了默认样式：
+
+**Primary 变体：**
+- `.chip--primary.chip--accent` - Primary + 强调色，实心背景
+- `.chip--primary.chip--success` - Primary + 成功色，实心背景
+- `.chip--primary.chip--warning` - Primary + 警告色，实心背景
+- `.chip--primary.chip--danger` - Primary + 危险色，实心背景
+
+**Soft 变体：**
+- `.chip--accent.chip--soft` - Soft + 强调色，浅色背景
+- `.chip--success.chip--soft` - Soft + 成功色，浅色背景
+- `.chip--warning.chip--soft` - Soft + 警告色，浅色背景
+- `.chip--danger.chip--soft` - Soft + 危险色，浅色背景
+
+**说明：** 你也可以在 CSS 中通过 `@layer components` 为任意变体与颜色组合（例如 `.chip--secondary.chip--accent`、`.chip--tertiary.chip--success`）编写自定义样式。
+
+## API 参考
+
+### Chip Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | Chip 内展示的内容 |
+| `className` | `string` | - | 根元素的额外 CSS 类 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 颜色变体 |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | 视觉样式变体 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸 |
+
+### Chip.Label Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 标签文本内容 |
+| `className` | `string` | - | 标签插槽的额外 CSS 类 |
diff --git a/apps/docs/content/docs/cn/react/components/(data-display)/table.mdx b/apps/docs/content/docs/cn/react/components/(data-display)/table.mdx
new file mode 100644
index 0000000..da50b09
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(data-display)/table.mdx
@@ -0,0 +1,416 @@
+---
+title: Table 表格
+description: 表格以行和列展示结构化数据，支持排序、选择、列宽调整与无限滚动。
+icon: updated
+links:
+  rac: Table
+  source: table/table.tsx
+  styles: table.css
+  storybook: Components/Data Display/Table
+---
+
+## 引入
+
+```tsx
+import { Table } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="table-basic"
+  minHeight="320px"
+/>
+
+### 组件结构
+
+引入 Table 组件，并通过点语法访问各部分。
+
+```tsx
+import { Table } from '@heroui/react';
+
+export default () => (
+  <Table>
+    <Table.ScrollContainer>
+      <Table.Content aria-label="Example table">
+        <Table.Header>
+          <Table.Column allowsSorting>
+            {({ sortDirection }) => (
+              <Table.SortableColumnHeader sortDirection={sortDirection}>
+                Name
+              </Table.SortableColumnHeader>
+            )}
+          </Table.Column>
+          <Table.Column>Role</Table.Column>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>Kate Moore</Table.Cell>
+            <Table.Cell>CEO</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Content>
+    </Table.ScrollContainer>
+    <Table.Footer>{/* Optional footer content */}</Table.Footer>
+  </Table>
+);
+```
+
+### 次要变体
+
+<ComponentPreview
+  name="table-secondary-variant"
+  minHeight="320px"
+/>
+
+### 排序
+
+在 `Table.Column` 上设置 `allowsSorting` 可将列设为可排序。在 `Table.Content` 上使用 `sortDescriptor` 与 `onSortChange` 管理排序状态。使用 `Table.SortableColumnHeader` 包裹列标签，并将列渲染函数中的 `sortDirection` 传入，即可显示默认的升序 / 降序指示器。
+
+<ComponentPreview
+  name="table-sorting"
+  minHeight="380px"
+/>
+
+### 选择
+
+在 `Table.Content` 上设置 `selectionMode` 以启用行选择。全选与每行复选框可使用带 `slot="selection"` 的 `Checkbox`。
+
+<ComponentPreview
+  name="table-selection"
+  minHeight="380px"
+/>
+
+### 自定义单元格
+
+<ComponentPreview
+  name="table-custom-cells"
+  minHeight="420px"
+/>
+
+### 可展开行
+
+行可以嵌套以展示层级数据。使用 `treeColumn` 指定列，并在该列单元格内渲染带 `slot="chevron"` 的 `Button`，以便用户展开/收起行。使用 `expandedKeys` 控制哪些行处于展开状态。
+
+<ComponentPreview
+  name="table-expandable-rows"
+  minHeight="420px"
+/>
+
+### 分页
+
+使用 `Table.Footer` 在表格下方添加分页组件。
+
+<ComponentPreview
+  name="table-pagination"
+  minHeight="400px"
+/>
+
+### 列宽调整
+
+使用 `Table.ResizableContainer` 包裹表格，并在每个可调整宽度的列中加入 `Table.ColumnResizer`。
+
+<ComponentPreview
+  name="table-column-resizing"
+  minHeight="420px"
+/>
+
+### 空状态
+
+在 `Table.Body` 上使用 `renderEmptyState`，在表格无数据时展示自定义内容。
+
+<ComponentPreview
+  name="table-empty-state"
+  minHeight="300px"
+/>
+
+### 异步加载
+
+使用 `Table.LoadMore` 实现无限滚动：会渲染一行哨兵节点，在进入视口时触发 `onLoadMore`。
+
+<ComponentPreview
+  name="table-async-loading"
+  minHeight="380px"
+/>
+
+### 虚拟化
+
+Table 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效处理大数据集。
+
+<ComponentPreview
+  name="table-virtualization"
+  minHeight="380px"
+/>
+
+### TanStack Table
+
+HeroUI 的 Table 可作为无头表格库之上的渲染层。
+本示例使用 [TanStack Table](https://tanstack.com/table) 处理列定义、排序与分页，而样式与无障碍由 HeroUI 负责。
+
+<ComponentPreview
+  name="table-tanstack-table"
+  minHeight="420px"
+/>
+
+<RelatedComponents component="table" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以为 Table 的各个部分分别传入类名：
+
+```tsx
+import { Table } from '@heroui/react';
+
+function CustomTable() {
+  return (
+    <Table className="border border-purple-200">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Custom styled table">
+          <Table.Header className="bg-purple-50">
+            <Table.Column>Name</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row className="hover:bg-purple-50">
+              <Table.Cell>Kate Moore</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Table 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .table-root {
+    @apply relative grid w-full overflow-clip;
+  }
+
+  .table__header {
+    @apply bg-gray-100;
+  }
+
+  .table__column {
+    @apply px-4 py-2.5 text-left text-xs font-medium text-gray-600;
+  }
+
+  .table__row {
+    @apply bg-white border-b border-gray-200;
+  }
+
+  .table__cell {
+    @apply px-4 py-3 text-sm;
+  }
+
+  .table__footer {
+    @apply flex items-center px-4 py-2.5;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Table 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/table.css)）：
+
+#### 基础类
+- `.table-root` - 根容器（命名为 `table-root` 而非 `table`，因为 `table` 是 Tailwind CSS 内置的 `display: table` 工具类）
+- `.table__scroll-container` - 横向滚动包裹层与自定义滚动条
+- `.table__content` - `<table>` 元素
+- `.table__header` - 表头行（`<thead>`）
+- `.table__column` - 列表头单元格（`<th>`）
+- `.table__body` - 表体（`<tbody>`）
+- `.table__row` - 行（`<tr>`）
+- `.table__cell` - 数据单元格（`<td>`）
+- `.table__footer` - 表底容器（位于 table 外部）
+
+#### 进阶类
+- `.table__column-resizer` - 列宽拖拽手柄
+- `.table__resizable-container` - 启用列宽调整的包裹层
+- `.table__load-more` - 无限滚动的哨兵行
+- `.table__load-more-content` - 加载指示器的样式容器
+- `.table__sortable-column-header` - 可排序列标签与指示器的包裹层
+- `.table__sortable-column-indicator` - 排序方向 chevron（通过 `[data-direction="descending"]` 翻转）
+
+#### 变体类
+- `.table-root--primary` - 灰色背景容器与卡片式表体（默认）
+- `.table-root--secondary` - 无背景，独立圆角表头
+
+### 交互状态
+
+Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`（行背景变化）
+- **已选中**：`[data-selected="true"]`（行高亮）
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（行、列与单元格的内嵌焦点环）
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度）
+- **可排序**：`[data-allows-sorting="true"]`（列上的交互指针样式）
+- **拖动中**：`[data-dragging="true"]`（降低透明度）
+- **放置目标**：`[data-drop-target="true"]`（强调色背景）
+
+## API 参考
+
+### Table Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。Primary 为灰色背景容器；Secondary 为扁平透明行。 |
+| `className` | `string` | - | 根容器的额外 CSS 类。 |
+| `children` | `React.ReactNode` | - | 表格内容（ScrollContainer、Footer 等）。 |
+
+### Table.ScrollContainer Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | `Table.Content` 元素。 |
+
+### Table.Content Props
+
+继承自 [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 表格的无障碍标签。 |
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | 选择行为。 |
+| `selectedKeys` | `Selection` | - | 受控的已选中 key。 |
+| `onSelectionChange` | `(keys: Selection) => void` | - | 选择变化时的事件处理函数。 |
+| `sortDescriptor` | `SortDescriptor` | - | 当前排序状态。 |
+| `onSortChange` | `(descriptor: SortDescriptor) => void` | - | 排序变化时的事件处理函数。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
+
+### Table.Header Props
+
+继承自 [React Aria TableHeader](https://react-spectrum.adobe.com/react-aria/Table.html#tableheader)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `columns` | `T[]` | - | 渲染函数模式下的动态列数据。 |
+| `children` | `React.ReactNode \| (column: T) => React.ReactNode` | - | 静态列或渲染函数。 |
+
+### Table.Column Props
+
+继承自 [React Aria Column](https://react-spectrum.adobe.com/react-aria/Table.html#column)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `string` | - | 列标识符。 |
+| `allowsSorting` | `boolean` | `false` | 列是否可排序。 |
+| `isRowHeader` | `boolean` | `false` | 该列是否作为行表头。 |
+| `defaultWidth` | `string \| number` | - | 可调整列的默认宽度。 |
+| `minWidth` | `number` | - | 可调整列的最小宽度。 |
+| `children` | `React.ReactNode \| (values: ColumnRenderProps) => React.ReactNode` | - | 列内容或带排序方向的渲染函数。 |
+
+### Table.Body Props
+
+继承自 [React Aria TableBody](https://react-spectrum.adobe.com/react-aria/Table.html#tablebody)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `items` | `T[]` | - | 渲染函数模式下的动态行数据。 |
+| `renderEmptyState` | `() => React.ReactNode` | - | 表格为空时展示的内容。 |
+| `children` | `React.ReactNode \| (item: T) => React.ReactNode` | - | 静态行或渲染函数。 |
+
+### Table.Row Props
+
+继承自 [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table.html#row)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `string \| number` | - | 行标识符。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | 行单元格。 |
+
+### Table.Cell Props
+
+继承自 [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Table.html#cell)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | 单元格内容。 |
+
+### Table.SortableColumnHeader Props
+
+渲染可排序列的标签与升序 / 降序指示器。请在 `Table.Column` 的渲染函数回调中使用，并将 `sortDirection` 透传进来。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `sortDirection` | `"ascending" \| "descending"` | - | 当前排序方向。请从 `Table.Column` 的渲染函数中透传。 |
+| `showIndicator` | `boolean` | `true` | 当存在排序方向时是否渲染指示器图标。 |
+| `indicator` | `React.ReactNode` | - | 自定义指示器元素。会覆盖默认的 chevron，并会被自动注入 `data-direction` 属性。 |
+| `className` | `string` | - | 包裹元素的额外 CSS 类。 |
+| `children` | `React.ReactNode` | - | 列标签内容。 |
+
+### Table.Footer Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | 表底内容（例如分页）。 |
+
+### Table.ColumnResizer Props
+
+继承自 [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-aria/Table.html#columnresizer)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+
+### Table.ResizableContainer Props
+
+继承自 [React Aria ResizableTableContainer](https://react-spectrum.adobe.com/react-aria/Table.html#resizabletablecontainer)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | `Table.Content` 元素。 |
+
+### Table.LoadMore Props
+
+继承自 [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/react-aria/Table.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isLoading` | `boolean` | `false` | 数据是否正在加载。 |
+| `onLoadMore` | `() => void` | - | 哨兵行可见时的事件处理函数。 |
+| `children` | `React.ReactNode` | - | 加载指示器内容。 |
+
+### Table.LoadMoreContent Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `React.ReactNode` | - | 加载指示器内容（例如 Spinner）。 |
+
+### Table.Collection Props
+
+由 React Aria `Collection` 重新导出。用于在行内与静态单元格并存时渲染动态单元格（例如复选框）。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `items` | `T[]` | - | 集合条目。 |
+| `children` | `(item: T) => React.ReactNode` | - | 每个条目的渲染函数。 |
+
+
+### TableLayout
+
+| Name | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `rowHeight` | `number \| undefined` | 48 | 行的固定高度（px）。 |
+| `estimatedRowHeight` | `number \| undefined` | — | 行高可变时的估算高度。 |
+| `headingHeight` | `number \| undefined` | 48 | 分区表头的固定高度（px）。 |
+| `estimatedHeadingHeight` | `number \| undefined` | — | 表头高度可变时的估算高度。 |
+| `loaderHeight` | `number \| undefined` | 48 | 加载器元素的固定高度（px）。该加载器用于在根级或嵌套行/分区中渲染「加载更多」等加载行。 |
+| `dropIndicatorThickness` | `number \| undefined` | 2 | 放置指示器的线条粗细。 |
+| `gap` | `number \| undefined` | 0 | 条目之间的间距。 |
+| `padding` | `number \| undefined` | 0 | 列表的内边距。 |
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/calendar.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/calendar.mdx
new file mode 100644
index 0000000..c15d0cb
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/calendar.mdx
@@ -0,0 +1,306 @@
+---
+title: Calendar 日历
+description: 基于 React Aria Calendar 的可组合日期选择器，包含月份网格、导航与年份选择器支持。
+icon: updated
+links:
+  rac: Calendar
+  source: calendar/calendar.tsx
+  styles: calendar.css
+  storybook: Components/Date and Time/Calendar
+---
+
+## 引入
+
+```tsx
+import { Calendar } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="calendar-basic" />
+
+### 组件结构
+
+```tsx
+import {Calendar} from '@heroui/react';
+
+export default () => (
+  <Calendar aria-label="Event date">
+    <Calendar.Header>
+      <Calendar.Heading />
+      <Calendar.NavButton slot="previous" />
+      <Calendar.NavButton slot="next" />
+    </Calendar.Header>
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>
+        {(date) => <Calendar.Cell date={date} />}
+      </Calendar.GridBody>
+    </Calendar.Grid>
+  </Calendar>
+)
+```
+
+### 年份选择器
+
+`Calendar.YearPickerTrigger`、`Calendar.YearPickerGrid` 以及对应的 body/cell 子组件提供一体化的年份导航模式。
+
+<ComponentPreview name="calendar-year-picker" />
+
+### 默认值
+
+<ComponentPreview name="calendar-default-value" />
+
+### 受控
+
+使用受控的 `value` 与 `focusedValue` 与外部状态协同，并支持自定义快捷键。
+
+<ComponentPreview name="calendar-controlled" />
+
+### 最小与最大日期
+
+<ComponentPreview name="calendar-min-max-dates" />
+
+### 不可用日期
+
+使用 `isDateUnavailable` 禁用周末、节假日或已被预订等日期。
+
+<ComponentPreview name="calendar-unavailable-dates" />
+
+### 固定周数
+
+将 `weeksInMonth` 设为固定值（例如 `6`），可在月份切换时保持网格高度稳定。在非公历场景中请谨慎使用，与 `firstDayOfWeek` 类似。
+
+<ComponentPreview name="calendar-weeks-in-month" />
+
+### 周视图
+
+设置 `visibleDuration={{ weeks: n }}` 可一次显示一个或多个周。翻页会按可见周范围前进。显示多周时可配合 `pageBehavior="single"` 每次仅移动一周。
+
+<ComponentPreview name="calendar-week-view" />
+
+### 日视图
+
+设置 `visibleDuration={{ days: n }}` 可显示连续多天的滚动窗口。翻页会按可见天数范围前进。显示多天时配合 `pageBehavior="single"` 可每次仅移动一天。
+
+<ComponentPreview name="calendar-day-view" />
+
+### 多选
+
+设置 `selectionMode="multiple"` 以选择多个日期。此时 `value`、`defaultValue` 与 `onChange` 使用日期数组。
+
+<ComponentPreview name="calendar-multiple-selection" />
+
+### 禁用
+
+<ComponentPreview name="calendar-disabled" />
+
+### 只读
+
+<ComponentPreview name="calendar-read-only" />
+
+### 焦点值
+
+使用 `focusedValue` 与 `onFocusChange` 以编程方式控制焦点落在哪一天。
+
+<ComponentPreview name="calendar-focused-value" />
+
+### 单元格指示器
+
+你可以自定义 `Calendar.Cell` 的子节点，并使用 `Calendar.CellIndicator` 展示活动等元数据。
+
+<ComponentPreview name="calendar-with-indicators" />
+
+### 多个月份
+
+使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。在各列头部为 `Calendar.Heading` 设置 `offset`（例如 `offset={{ months: 1 }}`）以显示对应月份标题。
+
+<ComponentPreview name="calendar-multiple-months" />
+
+### 国际化日历
+
+默认情况下，Calendar 使用用户语言环境对应的历法系统显示日期。你可以使用 `I18nProvider` 包裹 Calendar，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+下方示例展示印度历法系统：
+
+<ComponentPreview name="calendar-international-calendar" />
+
+**提示：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的语言环境无关。这样应用逻辑可以始终使用单一历法系统，同时仍可按用户偏好的格式展示日期。
+
+### 自定义导航图标
+
+向 `Calendar.NavButton` 传入子节点即可替换默认的箭头图标。
+
+<ComponentPreview name="calendar-custom-icons" />
+
+### 真实场景示例
+
+<ComponentPreview name="calendar-booking-calendar" />
+
+### 自定义样式
+
+<ComponentPreview name="calendar-custom-styles" />
+
+<RelatedComponents component="calendar" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Calendar} from '@heroui/react';
+
+function CustomCalendar() {
+  return (
+    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
+      <Calendar.Header className="pb-3">
+        <Calendar.Heading className="text-default" />
+        <Calendar.NavButton slot="previous" className="text-default" />
+        <Calendar.NavButton slot="next" className="text-default" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
+```
+
+### 自定义组件类
+
+```css
+@layer components {
+  .calendar {
+    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
+  }
+
+  .calendar__heading {
+    @apply text-sm font-semibold text-default-700;
+  }
+
+  .calendar__cell[data-selected="true"] {
+    @apply bg-accent text-accent-foreground;
+  }
+}
+```
+
+### CSS 类
+
+Calendar 在 `packages/styles/components/calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类：
+
+- `.calendar` - 根容器。
+- `.calendar__header` - 包含导航按钮与标题的头部行。
+- `.calendar__heading` - 当前月份标签。
+- `.calendar__nav-button` - 上一月/下一月导航控件。
+- `.calendar__grid` - 主体日期网格。
+- `.calendar__grid-header` - 星期标题行容器。
+- `.calendar__grid-body` - 日期行容器。
+- `.calendar__header-cell` - 星期标题单元格。
+- `.calendar__cell` - 可交互的日期单元格。
+- `.calendar__cell-indicator` - 日期单元格内的点状指示器。
+- `.calendar-year-picker__trigger` - 年份选择器切换按钮。
+- `.calendar-year-picker__trigger-heading` - 年份选择触发器内的标题文本。
+- `.calendar-year-picker__trigger-indicator` - 年份选择触发器内的指示图标。
+- `.calendar-year-picker__year-grid` - 可选年份的覆盖网格。
+- `.calendar-year-picker__year-cell` - 单个年份选项。
+
+### 交互状态
+
+Calendar 同时支持伪类与 React Aria 的 data 属性：
+
+- **已选中**：`[data-selected="true"]`
+- **今天**：`[data-today="true"]`
+- **不可用**：`[data-unavailable="true"]`
+- **跨月**：`[data-outside-month="true"]`
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **按下**：`:active` 或 `[data-pressed="true"]`
+- **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：`:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### Calendar Props
+
+Calendar 继承 React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html) 的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `selectionMode` | `'single' \| 'multiple'` | `'single'` | 单选或多选日期。 |
+| `value` | `DateValue \| null` 或 `DateValue[] \| null` | - | 受控的选中日期。`selectionMode="multiple"` 时使用数组。 |
+| `defaultValue` | `DateValue \| null` 或 `DateValue[] \| null` | - | 初始选中日期（非受控）。 |
+| `onChange` | `(value: DateValue \| null)` 或 `(value: DateValue[] \| null) => void` | - | 选中变化时调用。 |
+| `focusedValue` | `DateValue` | - | 受控的焦点日期。 |
+| `onFocusChange` | `(value: DateValue) => void` | - | 焦点移动到其它日期时调用。 |
+| `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 最早可选日期。 |
+| `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 最晚可选日期。 |
+| `weeksInMonth` | `number` | - | 一个月的周数。该值会覆盖区域设置的默认值。 |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | - | 将日期标记为不可用。 |
+| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖区域设置的一周起始日。 |
+| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见范围或单步前进。 |
+| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时按选中项对齐可见范围。 |
+| `isDisabled` | `boolean` | `false` | 禁用交互与选择。 |
+| `isReadOnly` | `boolean` | `false` | 内容只读，无法更改选中。 |
+| `isInvalid` | `boolean` | `false` | 将日历标记为无效以配合校验 UI。 |
+| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。使用 `{ months: n }` 为月视图，`{ weeks: n }` 为周视图，`{ days: n }` 为日视图。 |
+| `defaultYearPickerOpen` | `boolean` | `false` | 内置年份选择器的初始展开状态。 |
+| `isYearPickerOpen` | `boolean` | - | 受控的年份选择器展开状态。 |
+| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器展开状态变化时调用。 |
+
+### 组合部件
+
+| Component | 描述 |
+|-----------|------|
+| `Calendar.Header` | 导航与标题的头部容器。 |
+| `Calendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月份布局）与 `format`（月/年/日格式选项）。 |
+| `Calendar.NavButton` | 上一月/下一月导航控件（`slot="previous"` 或 `slot="next"`）。 |
+| `Calendar.Grid` | 单个月的日期网格（多月份布局支持 `offset`）。 |
+| `Calendar.GridHeader` | 星期标题容器。 |
+| `Calendar.GridBody` | 日期单元格主体容器。 |
+| `Calendar.HeaderCell` | 星期标签单元格。 |
+| `Calendar.Cell` | 单个日期单元格。 |
+| `Calendar.CellIndicator` | 用于自定义元数据的可选指示元素。 |
+| `Calendar.YearPickerTrigger` | 切换年份选择模式的触发器。 |
+| `Calendar.YearPickerTriggerHeading` | 年份选择触发器内的本地化标题内容。 |
+| `Calendar.YearPickerTriggerIndicator` | 年份选择触发器内的切换图标。 |
+| `Calendar.YearPickerGrid` | 年份选择覆盖网格容器。 |
+| `Calendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器。 |
+| `Calendar.YearPickerCell` | 单个年份选项单元格。 |
+
+### 年份选择器子组件
+
+年份选择器子组件继承 React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) 与 [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker) 的格式化属性。
+
+| 组件 | 属性 | 类型 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标题（如 `{month: 'short'}`）。 |
+| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局）。 |
+| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法系统等）。 |
+| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数量。当同时设置 `minValue` 与 `maxValue` 时，默认为二者之间的完整范围。 |
+
+### Calendar.Cell Render Props
+
+当 `Calendar.Cell` 的 `children` 为函数时，可使用 React Aria 的渲染参数：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `formattedDate` | `string` | 单元格日期的本地化标签。 |
+| `isSelected` | `boolean` | 该日期是否被选中。 |
+| `isUnavailable` | `boolean` | 该日期是否不可用。 |
+| `isDisabled` | `boolean` | 单元格是否禁用。 |
+| `isOutsideMonth` | `boolean` | 是否属于相邻月份。 |
+
+支持的历法系统及其标识符完整列表见：
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/date-field.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-field.mdx
new file mode 100644
index 0000000..818c552
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-field.mdx
@@ -0,0 +1,468 @@
+---
+title: DateField 日期字段
+description: 基于 React Aria DateField 的日期输入字段，包含标签、说明与校验。
+links:
+  rac: DateField
+  source: date-field/date-field.tsx
+  styles: date-field.css
+  storybook: Components/Date and Time/DateField
+---
+
+## 引入
+
+```tsx
+import { DateField } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="date-field-basic" />
+
+### 组件结构
+
+```tsx
+import {DateField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <DateField>
+    <Label />
+    <DateField.Group>
+      <DateField.Input>
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+    </DateField.Group>
+    <Description />
+    <FieldError />
+  </DateField>
+)
+```
+
+> **DateField** 将标签、日期输入、说明与错误信息组合为单个无障碍组件。
+
+### 带描述
+
+<ComponentPreview name="date-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="date-field-required" />
+
+### 校验
+
+配合 `FieldError`，使用 `isInvalid` 展示校验信息。
+
+<ComponentPreview name="date-field-invalid" />
+
+### 带校验
+
+DateField 支持使用 `minValue`、`maxValue` 及自定义校验逻辑。
+
+<ComponentPreview name="date-field-with-validation" />
+
+### 粒度
+
+<ComponentPreview name="date-field-granularity" />
+
+### 受控
+
+通过受控 `value` 与其它组件或状态管理同步。
+
+<ComponentPreview name="date-field-controlled" />
+
+### 禁用状态
+
+<ComponentPreview name="date-field-disabled" />
+
+### 带图标
+
+通过前缀或后缀图标增强日期输入。
+
+<ComponentPreview name="date-field-with-prefix-icon" />
+
+<ComponentPreview name="date-field-with-suffix-icon" />
+
+<ComponentPreview name="date-field-with-prefix-and-suffix" />
+
+### 全宽
+
+<ComponentPreview name="date-field-full-width" />
+
+### 变体
+
+`DateField.Group` 提供两种视觉变体：
+
+- **`primary`**（默认）：带阴影的标准样式，适用于大多数场景
+- **`secondary`**：低强调、无阴影，适合放在 Surface 等表面背景上
+
+<ComponentPreview name="date-field-variants" />
+
+### 在 Surface 中
+
+在 [Surface](/docs/components/surface) 内使用时，请在 `DateField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="date-field-on-surface" />
+
+### 表单示例
+
+包含校验与提交的完整表单示例。
+
+<ComponentPreview name="date-field-form-example" />
+
+<RelatedComponents component="datefield" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="date-field-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {DateField, Label, Description} from '@heroui/react';
+
+function CustomDateField() {
+  return (
+    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Appointment date
+      </Label>
+      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.Group>
+      <Description className="text-xs text-default-500">
+        Select a date for your appointment.
+      </Description>
+    </DateField>
+  );
+}
+```
+
+### 自定义组件类
+
+DateField 的默认样式很轻量。覆盖 `.date-field` 类即可自定义容器样式。
+
+```css
+@layer components {
+  .date-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS 类
+
+- `.date-field` – 轻量样式的根容器（`flex flex-col gap-1`）
+
+> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。`DateField.Group` 的样式见下文 API 参考。
+
+### 交互状态
+
+DateField 会根据状态自动设置以下 data 属性：
+
+- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时自动隐藏 description 插槽
+- **必填**：`[data-required="true"]` – 当 `isRequired` 为 true 时添加
+- **禁用**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时添加
+- **焦点在内**：`[data-focus-within="true"]` – 任一子输入聚焦时添加
+
+## API 参考
+
+### DateField Props
+
+DateField 继承 React Aria [DateField](https://react-aria.adobe.com/DateField.md) 的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode` | - | 子组件（Label、DateField.Group 等）或渲染函数。 |
+| `className` | `string \| (values: DateFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 日期字段是否占满容器宽度。 |
+| `id` | `string` | - | 元素的唯一 id。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `DateValue \| null` | - | 当前值（受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `defaultValue` | `DateValue \| null` | - | 默认值（非受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `onChange` | `(value: DateValue \| null) => void` | - | 值变化时触发的事件处理函数。 |
+| `placeholderValue` | `DateValue \| null` | - | 影响占位符格式的占位日期。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 是否在提交表单前要求用户输入。 |
+| `isInvalid` | `boolean` | - | 值是否无效。 |
+| `minValue` | `DateValue \| null` | - | 用户可选择最早日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `maxValue` | `DateValue \| null` | - | 用户可选择最晚日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | - | 针对每个日期调用；返回 true 表示该日期不可用。 |
+| `validate` | `(value: DateValue) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 |
+
+#### Format Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `granularity` | `Granularity` | - | 显示的最小单位。日期默认为 `"day"`，时间默认为 `"minute"`。 |
+| `hourCycle` | `12 \| 24` | - | 以 12 或 24 小时制显示时间；默认由语言环境决定。 |
+| `hideTimeZone` | `boolean` | `false` | 是否隐藏时区缩写。 |
+| `shouldForceLeadingZeros` | `boolean` | - | 是否始终为月、日、小时等显示前导零。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | 输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。 |
+| `autoFocus` | `boolean` | - | 是否在渲染后自动聚焦该元素。 |
+| `autoComplete` | `string` | - | 输入应提供的自动完成类型。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 标注该字段的元素 id。 |
+| `aria-describedby` | `string` | - | 描述该字段的元素 id。 |
+| `aria-details` | `string` | - | 包含额外详情的元素 id。 |
+
+### 组合组件
+
+DateField 与以下独立组件配合使用，请分别导入并直接使用：
+
+- **Label** – 来自 `@heroui/react` 的字段标签
+- **DateField.Group** – 日期输入分组（详见下文）
+- **DateField.Input** – 来自 `@heroui/react` 的分段位编辑输入
+- **DateField.InputContainer** – 可横向滚动的容器，用于组合多个输入（例如开始/结束范围）
+- **DateField.Segment** – 单个日期段位（年、月、日等）
+- **DateField.Prefix** / **DateField.Suffix** – 输入组的前缀与后缀插槽
+- **Description** – 来自 `@heroui/react` 的辅助说明
+- **FieldError** – 来自 `@heroui/react` 的校验错误信息
+
+这些组件各自有独立的 props API。在 DateField 中直接组合使用：
+
+```tsx
+import {parseDate} from '@internationalized/date';
+import {DateField, Label, Description, FieldError} from '@heroui/react';
+
+<DateField
+  isRequired
+  isInvalid={hasError}
+  minValue={today(getLocalTimeZone())}
+  value={date}
+  onChange={setDate}
+>
+  <Label>Appointment Date</Label>
+  <DateField.Group>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+  </DateField.Group>
+  <Description>Select a date from today onwards.</Description>
+  <FieldError>Please select a valid date.</FieldError>
+</DateField>
+```
+
+### DateValue 类型
+
+DateField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 中的类型：
+
+- `CalendarDate` – 不含时间与时区的日期
+- `CalendarDateTime` – 含时间、不含时区
+- `ZonedDateTime` – 含时间与时区
+- `Time` – 仅时间
+
+示例：
+
+```tsx
+import {parseDate, today, getLocalTimeZone} from '@internationalized/date';
+
+// Parse from string
+const date = parseDate('2024-01-15');
+
+// Today's date
+const todayDate = today(getLocalTimeZone());
+
+// Use in DateField
+<DateField value={date} onChange={setDate}>
+  {/* ... */}
+</DateField>
+```
+
+> **说明：** DateField 依赖 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 进行解析、运算与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。
+
+### DateFieldRenderProps
+
+对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦。 |
+| `isFocusWithin` | `boolean` | 是否有子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 |
+
+### DateField.Group Props
+
+DateField.Group 继承 React Aria `Group` 的全部 props，并额外支持：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `fullWidth` | `boolean` | `false` | 日期输入组是否占满容器宽度。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
+
+### DateField.Input Props
+
+DateField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
+
+`DateField.Input` 接受渲染函数作为子节点，函数参数为日期段位；每个段位对应日期的一部分（年、月、日等）。
+
+### DateField.Segment Props
+
+DateField.Segment 继承 React Aria `DateSegment` 的全部 props：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `segment` | `DateSegment` | - | 来自 DateField.Input 渲染函数的 `DateSegment` 对象。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+
+### DateField.InputContainer Props
+
+DateField.InputContainer 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 滚动容器中的内容（通常为多个 `DateField.Input`）。 |
+
+### DateField.Prefix Props
+
+DateField.Prefix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 |
+
+### DateField.Suffix Props
+
+DateField.Suffix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 |
+
+## DateField.Group 样式
+
+### 自定义组件类
+
+基础类作用于所有实例，可通过 `@layer components` 一次性覆盖。
+
+```css
+@layer components {
+  .date-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .date-input-group__input {
+    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .date-input-group__segment {
+    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;
+
+    &:focus,
+    &[data-focused="true"] {
+      @apply bg-accent-soft text-accent-soft-foreground;
+    }
+  }
+
+  .date-input-group__input-container {
+    @apply flex flex-1 items-center;
+    overflow-x: auto;
+    overflow-y: clip;
+    scrollbar-width: none;
+  }
+
+  .date-input-group__prefix,
+  .date-input-group__suffix {
+    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### DateField.Group CSS 类
+
+- `.date-input-group` – 根容器样式
+- `.date-input-group__input` – 输入包裹层样式
+- `.date-input-group__input-container` – 用于组合多个输入的滚动容器
+- `.date-input-group__segment` – 单个日期段位样式
+- `.date-input-group__prefix` – 前缀元素样式
+- `.date-input-group__suffix` – 后缀元素样式
+
+### DateField.Group 交互状态
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **焦点在内**：`[data-focus-within="true"]` 或 `:focus-within`
+- **无效**：`[data-invalid="true"]`（同时与 `aria-invalid` 同步）
+- **禁用**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
+- **段位聚焦**：段位上的 `:focus` 或 `[data-focused="true"]`
+- **段位占位符**：段位上的 `[data-placeholder="true"]`
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/date-picker.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-picker.mdx
new file mode 100644
index 0000000..e7a4cf0
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-picker.mdx
@@ -0,0 +1,227 @@
+---
+title: DatePicker 日期选择器
+description: 可组合的日期选择器，基于 React Aria DatePicker，通过 DateField 与 Calendar 组合实现。
+links:
+  rac: DatePicker
+  source: date-picker/date-picker.tsx
+  styles: date-picker.css
+  storybook: Components/Date and Time/DatePicker
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { DatePicker, DateField, Calendar, Label } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="date-picker-basic" />
+
+### 组件结构
+
+`DatePicker` 采用组合优先的 API。请显式组合 `DateField` 与 `Calendar`，以便完全控制结构与样式。
+
+```tsx
+import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
+
+export default () => (
+  <DatePicker>
+    <Label />
+    <DateField.Group>
+      <DateField.Input>
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateField.Suffix>
+        <DatePicker.Trigger>
+          <DatePicker.TriggerIndicator />
+        </DatePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    <DatePicker.Popover>
+      <Calendar aria-label="Choose date">
+        <Calendar.Header>
+          <Calendar.YearPickerTrigger>
+            <Calendar.YearPickerTriggerHeading />
+            <Calendar.YearPickerTriggerIndicator />
+          </Calendar.YearPickerTrigger>
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </DatePicker.Popover>
+  </DatePicker>
+)
+```
+
+### 受控
+
+<ComponentPreview name="date-picker-controlled" />
+
+### 校验
+
+<ComponentPreview name="date-picker-with-validation" />
+
+### 格式选项
+
+使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DatePicker 值的展示方式。
+
+<ComponentPreview name="date-picker-format-options" />
+
+### 禁用
+
+<ComponentPreview name="date-picker-disabled" />
+
+### 自定义指示器
+
+未提供子节点时，`DatePicker.TriggerIndicator` 会渲染默认的 `IconCalendar`。传入子节点即可替换。
+
+<ComponentPreview name="date-picker-with-custom-indicator" />
+
+### 表单示例
+
+<ComponentPreview name="date-picker-form-example" />
+
+### 国际化历法
+
+默认情况下，DatePicker 会使用用户语言环境对应的历法显示日期。你可以使用 `I18nProvider` 包裹 DatePicker，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+下方示例展示印度历法系统：
+
+<ComponentPreview name="date-picker-international-calendar" />
+
+**说明：** `onChange` 事件返回的日期始终与 `value` 或 `defaultValue` 使用同一历法系统（未提供值时为公历），与界面展示的本地化格式无关。这能确保应用逻辑在单一历法系统下保持一致，同时仍可按用户偏好展示日期。
+
+支持的历法系统及其标识符完整列表见：
+
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="date-picker-custom-render-function"
+/>
+
+<RelatedComponents component="datepicker" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以分别为各个组合部分添加样式：
+
+```tsx
+import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
+
+function CustomDatePicker() {
+  return (
+    <DatePicker className="w-[320px] gap-2">
+      <Label className="text-sm font-semibold">Date</Label>
+      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger className="w-full">
+            <DatePicker.TriggerIndicator className="text-default-600" />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover className="rounded-xl p-2">
+        <Calendar aria-label="Custom date picker calendar">
+          {/* Calendar parts */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 DatePicker 的基础类，请使用 `@layer components`。
+
+```css
+@layer components {
+  .date-picker {
+    @apply inline-flex flex-col gap-1;
+  }
+
+  .date-picker__trigger {
+    @apply inline-flex items-center justify-between;
+  }
+
+  .date-picker__trigger-indicator {
+    @apply text-muted;
+  }
+
+  .date-picker__popover {
+    @apply min-w-[var(--trigger-width)] p-0;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 命名，便于复写与定制。
+
+### CSS 类
+
+DatePicker 在 `packages/styles/components/date-picker.css` 中使用以下类：
+
+- `.date-picker` - 根包裹层。
+- `.date-picker__trigger` - 打开弹出层的触发区域。
+- `.date-picker__trigger-indicator` - 默认或自定义指示器插槽。
+- `.date-picker__popover` - 弹出层内容包裹。
+
+### 交互状态
+
+DatePicker 支持 React Aria 的 data 属性与伪类状态：
+
+- **展开**：触发器上的 `[data-open="true"]`。
+- **禁用**：触发器上的 `[data-disabled="true"]` 或 `[aria-disabled="true"]`。
+- **焦点可见**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`。
+- **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]`。
+
+## API 参考
+
+### DatePicker Props
+
+DatePicker 继承 React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md) 的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `value` | `DateValue \| null` | - | 受控的选中日期值。 |
+| `defaultValue` | `DateValue \| null` | - | 非受控模式下的默认选中值。 |
+| `onChange` | `(value: DateValue \| null) => void` | - | 选中日期变化时调用。 |
+| `isOpen` | `boolean` | - | 受控的弹出层打开状态。 |
+| `defaultOpen` | `boolean` | `false` | 弹出层初始打开状态。 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 弹出层打开状态变化时调用。 |
+| `isDisabled` | `boolean` | `false` | 禁用日期选择与触发器交互。 |
+| `isInvalid` | `boolean` | - | 将字段标记为无效以呈现校验状态。 |
+| `minValue` | `DateValue` | - | 可选择的最小日期。 |
+| `maxValue` | `DateValue` | - | 可选择的最大日期。 |
+| `name` | `string` | - | HTML 表单提交使用的 name。 |
+| `children` | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | - | 组合内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### 组合部件
+
+| 组件 | 描述 |
+| --- | --- |
+| `DatePicker.Root` | 根日期选择器容器与状态持有者。 |
+| `DatePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内。 |
+| `DatePicker.TriggerIndicator` | 带默认日历图标的指示器插槽。 |
+| `DatePicker.Popover` | 包裹 `Calendar` 内容的弹出层。 |
+
+### 相关包
+
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与布局方向
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/date-range-picker.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-range-picker.mdx
new file mode 100644
index 0000000..600f1f6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/date-range-picker.mdx
@@ -0,0 +1,245 @@
+---
+title: DateRangePicker 日期范围选择器
+description: 基于 React Aria DateRangePicker 的可组合日期范围选择器，由 DateField 与 RangeCalendar 组合而成。
+links:
+  rac: DateRangePicker
+  source: date-range-picker/date-range-picker.tsx
+  styles: date-range-picker.css
+  storybook: Components/Date and Time/DateRangePicker
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="date-range-picker-basic" />
+
+### 组件结构
+
+`DateRangePicker` 采用组合优先的 API。请显式组合 `DateField` 与 `RangeCalendar`，以便完全控制结构与样式。
+
+```tsx
+import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
+
+export default () => (
+  <DateRangePicker>
+    <Label />
+    <DateField.Group>
+      <DateField.InputContainer>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.InputContainer>
+      <DateField.Suffix>
+        <DateRangePicker.Trigger>
+          <DateRangePicker.TriggerIndicator />
+        </DateRangePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    <DateRangePicker.Popover>
+      <RangeCalendar aria-label="Choose trip dates">
+        <RangeCalendar.Header>
+          <RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.YearPickerTriggerHeading />
+            <RangeCalendar.YearPickerTriggerIndicator />
+          </RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>{(date) => <RangeCalendar.Cell date={date} />}</RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </DateRangePicker.Popover>
+  </DateRangePicker>
+)
+```
+
+### 受控
+
+<ComponentPreview name="date-range-picker-controlled" />
+
+### 校验
+
+<ComponentPreview name="date-range-picker-with-validation" />
+
+### 格式选项
+
+使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DateRangePicker 值的展示格式。
+
+<ComponentPreview name="date-range-picker-format-options" />
+
+### 禁用
+
+<ComponentPreview name="date-range-picker-disabled" />
+
+### 自定义指示器
+
+未传入子节点时，`DateRangePicker.TriggerIndicator` 会渲染默认的 `IconCalendar`。传入子节点即可替换。
+
+<ComponentPreview name="date-range-picker-with-custom-indicator" />
+
+### 表单示例
+
+<ComponentPreview name="date-range-picker-form-example" />
+
+### 国际化历法
+
+默认情况下，DateRangePicker 按用户语言环境的历法显示日期。你可以使用 `I18nProvider` 包裹 DateRangePicker，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+下方示例展示印度历法系统：
+
+<ComponentPreview name="date-range-picker-international-calendar" />
+
+**说明：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的本地化格式无关。
+
+支持的历法系统及其标识符完整列表见：
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="date-range-picker-custom-render-function"
+/>
+
+<RelatedComponents component="daterangepicker" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以独立为每个组合部件添加样式：
+
+```tsx
+import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
+
+function CustomDateRangePicker() {
+  return (
+    <DateRangePicker className="w-[360px] gap-2">
+      <Label className="text-sm font-semibold">Trip dates</Label>
+      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator className="px-2 text-default" />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger className="w-full">
+            <DateRangePicker.TriggerIndicator className="text-default" />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover className="rounded-xl p-2">
+        <RangeCalendar aria-label="Custom range picker calendar">
+          {/* RangeCalendar parts */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 DateRangePicker 基础类，请使用 `@layer components`。
+
+```css
+@layer components {
+  .date-range-picker {
+    @apply inline-flex flex-col gap-1;
+  }
+
+  .date-range-picker__trigger {
+    @apply inline-flex items-center justify-between;
+  }
+
+  .date-range-picker__trigger-indicator {
+    @apply text-muted;
+  }
+
+  .date-range-picker__range-separator {
+    @apply px-2 text-default;
+  }
+
+  .date-range-picker__popover {
+    @apply min-w-[var(--trigger-width)] p-0;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 命名，以便复写与自定义。
+
+### CSS 类
+
+DateRangePicker 在 `packages/styles/components/date-range-picker.css` 中使用以下类：
+
+- `.date-range-picker` - 根包裹层。
+- `.date-range-picker__trigger` - 打开弹出层的触发区域。
+- `.date-range-picker__trigger-indicator` - 默认或自定义指示器插槽。
+- `.date-range-picker__range-separator` - 开始与结束日期输入之间的分隔。
+- `.date-range-picker__popover` - 弹出层内容包裹。
+
+### 交互状态
+
+DateRangePicker 支持 React Aria 的 data 属性与伪类状态：
+
+- **展开**：触发器上的 `[data-open="true"]`。
+- **禁用**：触发器上的 `[data-disabled="true"]` 或 `[aria-disabled="true"]`。
+- **焦点可见**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`。
+- **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]`。
+
+## API 参考
+
+### DateRangePicker Props
+
+DateRangePicker 继承 React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker) 的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `{ start: DateValue; end: DateValue } \| null` | - | 受控的选中日期范围值。 |
+| `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | 非受控模式下的默认范围。 |
+| `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | 选中范围变化时调用。 |
+| `isOpen` | `boolean` | - | 受控的弹出层展开状态。 |
+| `defaultOpen` | `boolean` | `false` | 弹出层初始是否展开。 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 弹出层展开状态变化时调用。 |
+| `isDisabled` | `boolean` | `false` | 禁用范围选择与触发器交互。 |
+| `isInvalid` | `boolean` | - | 标记字段无效以呈现校验状态。 |
+| `minValue` | `DateValue` | - | 可选的最小日期。 |
+| `maxValue` | `DateValue` | - | 可选的最大日期。 |
+| `startName` | `string` | - | HTML 表单提交时开始日期字段名。 |
+| `endName` | `string` | - | HTML 表单提交时结束日期字段名。 |
+| `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | 组合内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### 组合部件
+
+| 组件 | 描述 |
+|-----------|-------------|
+| `DateRangePicker.Root` | 根日期范围选择器容器与状态持有者。 |
+| `DateRangePicker.Trigger` | 触发按钮，通常放在 `DateField.Suffix` 内。 |
+| `DateRangePicker.TriggerIndicator` | 带默认日历图标的指示器插槽。 |
+| `DateRangePicker.RangeSeparator` | 开始与结束日期输入之间的分隔部件。 |
+| `DateRangePicker.Popover` | 包裹 `RangeCalendar` 内容的弹出层。 |
+
+### Related packages
+
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/range-calendar.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/range-calendar.mdx
new file mode 100644
index 0000000..49db34b
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/range-calendar.mdx
@@ -0,0 +1,308 @@
+---
+title: RangeCalendar 范围日历
+description: 基于 React Aria RangeCalendar 的可组合日期范围选择器，包含月份网格、导航与年份选择支持。
+links:
+  rac: RangeCalendar
+  source: range-calendar/range-calendar.tsx
+  styles: range-calendar.css
+  storybook: Components/Date and Time/RangeCalendar
+---
+
+## 引入
+
+```tsx
+import { RangeCalendar } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="range-calendar-basic" />
+
+### 组件结构
+
+```tsx
+import {RangeCalendar} from '@heroui/react';
+
+export default () => (
+  <RangeCalendar aria-label="Trip dates">
+    <RangeCalendar.Header>
+      <RangeCalendar.Heading />
+      <RangeCalendar.NavButton slot="previous" />
+      <RangeCalendar.NavButton slot="next" />
+    </RangeCalendar.Header>
+    <RangeCalendar.Grid>
+      <RangeCalendar.GridHeader>
+        {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+      </RangeCalendar.GridHeader>
+      <RangeCalendar.GridBody>
+        {(date) => <RangeCalendar.Cell date={date} />}
+      </RangeCalendar.GridBody>
+    </RangeCalendar.Grid>
+  </RangeCalendar>
+)
+```
+
+### 年份选择
+
+`RangeCalendar.YearPickerTrigger`、`RangeCalendar.YearPickerGrid` 及其 body/cell 子组件提供一体化的年份导航模式。
+
+<ComponentPreview name="range-calendar-year-picker" />
+
+### 默认值
+
+<ComponentPreview name="range-calendar-default-value" />
+
+### 受控
+
+<ComponentPreview name="range-calendar-controlled" />
+
+### 最小与最大日期
+
+<ComponentPreview name="range-calendar-min-max-dates" />
+
+### 不可用日期
+
+使用 `isDateUnavailable` 禁用周末、节假日或已被预订的日期等。
+
+<ComponentPreview name="range-calendar-unavailable-dates" />
+
+### 基于锚点的不可用日期
+
+选择范围时，`isDateUnavailable` 的第二个参数 `anchorDate` 为用户选中的开始日期。可据此限制结束日期（例如仅允许开始日期前后 7 天）。
+
+<ComponentPreview name="range-calendar-anchor-unavailable-dates" />
+
+### 固定周数
+
+将 `weeksInMonth` 设为固定值（例如 `6`），可在月份切换时保持网格高度稳定。
+
+<ComponentPreview name="range-calendar-weeks-in-month" />
+
+### 周视图
+
+设置 `visibleDuration={{ weeks: n }}` 可一次显示一个或多个周。翻页会按可见周范围前进。显示多周时可配合 `pageBehavior="single"` 每次仅移动一周。
+
+<ComponentPreview name="range-calendar-week-view" />
+
+### 日视图
+
+设置 `visibleDuration={{ days: n }}` 可显示连续多天的滚动窗口。翻页会按可见天数范围前进。显示多天时配合 `pageBehavior="single"` 可每次仅移动一天。
+
+<ComponentPreview name="range-calendar-day-view" />
+
+### 允许非连续范围
+
+启用 `allowsNonContiguousRanges`，允许选择跨越不可用日期的范围。
+
+<ComponentPreview name="range-calendar-allows-non-contiguous-ranges" />
+
+### 禁用
+
+<ComponentPreview name="range-calendar-disabled" />
+
+### 只读
+
+<ComponentPreview name="range-calendar-read-only" />
+
+### 无效
+
+<ComponentPreview name="range-calendar-invalid" />
+
+### 焦点日期
+
+<ComponentPreview name="range-calendar-focused-value" />
+
+### 单元格指示器
+
+你可以自定义 `RangeCalendar.Cell` 的子节点，并使用 `RangeCalendar.CellIndicator` 展示活动等元数据。
+
+<ComponentPreview name="range-calendar-with-indicators" />
+
+### 多个月份
+
+使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。在各列头部为 `RangeCalendar.Heading` 设置 `offset`（例如 `offset={{ months: 1 }}`）以显示对应月份标题。
+
+<ComponentPreview name="range-calendar-multiple-months" />
+
+### 国际化历法
+
+默认情况下，RangeCalendar 按用户语言环境的历法显示日期。你可以使用 `I18nProvider` 包裹 RangeCalendar，并通过 [Unicode 历法语言扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。
+
+下方示例展示印度历法系统：
+
+<ComponentPreview name="range-calendar-international-calendar" />
+
+**说明：** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统中的日期（若未提供值则为公历），与界面展示的本地化格式无关。
+
+### 实际场景示例
+
+<ComponentPreview name="range-calendar-booking-calendar" />
+
+<RelatedComponents component="range-calendar" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {RangeCalendar} from '@heroui/react';
+
+function CustomRangeCalendar() {
+  return (
+    <RangeCalendar aria-label="Trip dates" className="w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm">
+      <RangeCalendar.Header className="pb-3">
+        <RangeCalendar.Heading className="text-default" />
+        <RangeCalendar.NavButton slot="previous" className="text-default" />
+        <RangeCalendar.NavButton slot="next" className="text-default" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
+```
+
+### 自定义组件类
+
+```css
+@layer components {
+  .range-calendar {
+    @apply w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm;
+  }
+
+  .range-calendar__heading {
+    @apply text-sm font-semibold text-default;
+  }
+
+  .range-calendar__cell[data-selected="true"] .range-calendar__cell-button {
+    @apply bg-accent text-accent-foreground;
+  }
+}
+```
+
+### CSS 类
+
+RangeCalendar 在 `packages/styles/components/range-calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类：
+
+- `.range-calendar` - 根容器。
+- `.range-calendar__header` - 含导航按钮与标题的头部行。
+- `.range-calendar__heading` - 当前月份标签。
+- `.range-calendar__nav-button` - 上一月/下一月导航控件。
+- `.range-calendar__grid` - 主体日期网格。
+- `.range-calendar__grid-header` - 星期标题行外层。
+- `.range-calendar__grid-body` - 日期行外层。
+- `.range-calendar__header-cell` - 星期标题单元格。
+- `.range-calendar__cell` - 可交互日期单元格外层。
+- `.range-calendar__cell-button` - 单元格内的可交互日期按钮。
+- `.range-calendar__cell-indicator` - 日期单元格内的圆点指示器。
+- `.calendar-year-picker__trigger` - 年份选择器切换按钮。
+- `.calendar-year-picker__trigger-heading` - 年份选择触发器内的标题文案。
+- `.calendar-year-picker__trigger-indicator` - 年份选择触发器内的指示图标。
+- `.calendar-year-picker__year-grid` - 可选年份的覆盖网格。
+- `.calendar-year-picker__year-cell` - 单个年份选项。
+
+### 交互状态
+
+RangeCalendar 同时支持伪类与 React Aria 的 data 属性：
+
+- **已选中**：`[data-selected="true"]`
+- **范围起点**：`[data-selection-start="true"]`
+- **范围终点**：`[data-selection-end="true"]`
+- **范围内**：`[data-selection-in-range="true"]`
+- **今天**：`[data-today="true"]`
+- **不可用**：`[data-unavailable="true"]`
+- **跨月**：`[data-outside-month="true"]`
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **按下**：`:active` 或 `[data-pressed="true"]`
+- **焦点可见**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：`:disabled` 或 `[data-disabled="true"]`
+
+## API 参考
+
+### RangeCalendar Props
+
+RangeCalendar 继承 React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html) 的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `RangeValue<DateValue> \| null` | - | 受控的选中范围。 |
+| `defaultValue` | `RangeValue<DateValue> \| null` | - | 初始选中范围（非受控）。 |
+| `onChange` | `(value: RangeValue<DateValue>) => void` | - | 选中变化时调用。 |
+| `focusedValue` | `DateValue` | - | 受控的焦点日期。 |
+| `onFocusChange` | `(value: DateValue) => void` | - | 焦点移动到其它日期时调用。 |
+| `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 可选的最早日期。 |
+| `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 可选的最晚日期。 |
+| `weeksInMonth` | `number` | - | 一个月的周数。该值会覆盖区域设置的默认值。 |
+| `isDateUnavailable` | `(date: DateValue, anchorDate: CalendarDate \| null) => boolean` | - | 将日期标记为不可用。`anchorDate` 为当前范围选择中的首个日期。 |
+| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖区域设置的一周起始日。 |
+| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见范围或单步前进。 |
+| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时按选中项对齐可见范围。 |
+| `allowsNonContiguousRanges` | `boolean` | `false` | 允许范围跨越不可用日期。 |
+| `isDisabled` | `boolean` | `false` | 禁用交互与选择。 |
+| `isReadOnly` | `boolean` | `false` | 内容只读，不可更改选中。 |
+| `isInvalid` | `boolean` | `false` | 标记为无效以配合校验样式。 |
+| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。使用 `{ months: n }` 为月视图，`{ weeks: n }` 为周视图，`{ days: n }` 为日视图。 |
+| `defaultYearPickerOpen` | `boolean` | `false` | 内置年份选择器的初始展开状态。 |
+| `isYearPickerOpen` | `boolean` | - | 受控的年份选择器展开状态。 |
+| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器展开状态变化时调用。 |
+
+### 组合部件
+
+| 组件 | 描述 |
+|-----------|-------------|
+| `RangeCalendar.Header` | 导航与标题的头部容器。 |
+| `RangeCalendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月份布局）与 `format`（月/年/日格式选项）。 |
+| `RangeCalendar.NavButton` | 上一页/下一页导航（`slot="previous"` 或 `slot="next"`）。 |
+| `RangeCalendar.Grid` | 单个月的日期网格（多月份布局支持 `offset`）。 |
+| `RangeCalendar.GridHeader` | 星期标题容器。 |
+| `RangeCalendar.GridBody` | 日期单元格主体容器。 |
+| `RangeCalendar.HeaderCell` | 星期标签单元格。 |
+| `RangeCalendar.Cell` | 单个日期单元格。 |
+| `RangeCalendar.CellIndicator` | 用于自定义元数据的可选指示元素。 |
+| `RangeCalendar.YearPickerTrigger` | 切换年份选择模式的触发器。 |
+| `RangeCalendar.YearPickerTriggerHeading` | 年份选择触发器内的本地化标题内容。 |
+| `RangeCalendar.YearPickerTriggerIndicator` | 年份选择触发器内的切换图标。 |
+| `RangeCalendar.YearPickerGrid` | 年份选择覆盖网格容器。 |
+| `RangeCalendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器。 |
+| `RangeCalendar.YearPickerCell` | 单个年份选项单元格。 |
+
+### 年份选择器子组件
+
+年份选择器子组件继承 React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) 与 [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker) 的格式化属性。
+
+| 组件 | 属性 | 类型 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `RangeCalendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标题（如 `{month: 'short'}`）。 |
+| `RangeCalendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局）。 |
+| `RangeCalendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法系统等）。 |
+| `RangeCalendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数量。当同时设置 `minValue` 与 `maxValue` 时，默认为二者之间的完整范围。 |
+
+### RangeCalendar.Cell Render Props
+
+当 `RangeCalendar.Cell` 的 `children` 为函数时，可使用 React Aria 的渲染参数：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `formattedDate` | `string` | 单元格日期的本地化文案。 |
+| `isSelected` | `boolean` | 该日期是否已选中。 |
+| `isSelectionStart` | `boolean` | 是否为选中范围的起点。 |
+| `isSelectionEnd` | `boolean` | 是否为选中范围的终点。 |
+| `isUnavailable` | `boolean` | 该日期是否不可用。 |
+| `isDisabled` | `boolean` | 单元格是否禁用。 |
+| `isOutsideMonth` | `boolean` | 是否属于相邻月份。 |
+
+支持的历法系统及其标识符完整列表见：
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Related packages
+
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向
diff --git a/apps/docs/content/docs/cn/react/components/(date-and-time)/time-field.mdx b/apps/docs/content/docs/cn/react/components/(date-and-time)/time-field.mdx
new file mode 100644
index 0000000..791f2e9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(date-and-time)/time-field.mdx
@@ -0,0 +1,435 @@
+---
+title: TimeField 时间字段
+description: 基于 React Aria TimeField 的时间输入字段，包含标签、说明与校验。
+links:
+  rac: TimeField
+  source: time-field/time-field.tsx
+  styles: time-field.css
+  storybook: Components/Date and Time/TimeField
+---
+
+## 引入
+
+```tsx
+import { TimeField } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="time-field-basic" />
+
+### 组件结构
+
+```tsx
+import {TimeField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <TimeField>
+    <Label />
+    <TimeField.Group>
+      <TimeField.Input>
+        {(segment) => <TimeField.Segment segment={segment} />}
+      </TimeField.Input>
+    </TimeField.Group>
+    <Description />
+    <FieldError />
+  </TimeField>
+)
+```
+
+> **TimeField** 将标签、时间输入、说明与错误信息组合为单个无障碍组件。
+
+### 带描述
+
+<ComponentPreview name="time-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="time-field-required" />
+
+### 校验
+
+配合 `FieldError`，使用 `isInvalid` 展示校验信息。
+
+<ComponentPreview name="time-field-invalid" />
+
+### 带校验
+
+TimeField 支持使用 `minValue`、`maxValue` 及自定义校验逻辑。
+
+<ComponentPreview name="time-field-with-validation" />
+
+### 受控
+
+通过控制 `value` 与其它组件或状态管理同步。
+
+<ComponentPreview name="time-field-controlled" />
+
+### 禁用状态
+
+<ComponentPreview name="time-field-disabled" />
+
+### 带图标
+
+通过前缀或后缀图标增强时间输入。
+
+<ComponentPreview name="time-field-with-prefix-icon" />
+
+<ComponentPreview name="time-field-with-suffix-icon" />
+
+<ComponentPreview name="time-field-with-prefix-and-suffix" />
+
+### 全宽
+
+<ComponentPreview name="time-field-full-width" />
+
+### 在 Surface 中
+
+在 [Surface](/docs/components/surface) 内使用时，请在 `TimeField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="time-field-on-surface" />
+
+### 表单示例
+
+包含校验与提交的完整表单示例。
+
+<ComponentPreview name="time-field-form-example" />
+
+<RelatedComponents component="timefield" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="time-field-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {TimeField, Label, Description} from '@heroui/react';
+
+function CustomTimeField() {
+  return (
+    <TimeField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Appointment time
+      </Label>
+      <TimeField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <TimeField.Input>
+          {(segment) => <TimeField.Segment segment={segment} />}
+        </TimeField.Input>
+      </TimeField.Group>
+      <Description className="text-xs text-default-500">
+        Select a time for your appointment.
+      </Description>
+    </TimeField>
+  );
+}
+```
+
+### 自定义组件类
+
+TimeField 的默认样式很轻量。覆盖 `.time-field` 类即可自定义容器样式。
+
+```css
+@layer components {
+  .time-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS 类
+
+- `.time-field` – 轻量样式的根容器（`flex flex-col gap-1`）
+
+> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。`TimeField.Group` 的样式见下文 API 参考。
+
+### 交互状态
+
+TimeField 会根据状态自动设置以下 data 属性：
+
+- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时自动隐藏 description 插槽
+- **必填**：`[data-required="true"]` – 当 `isRequired` 为 true 时添加
+- **禁用**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时添加
+- **焦点在内**：`[data-focus-within="true"]` – 任一子输入聚焦时添加
+
+## API 参考
+
+### TimeField Props
+
+TimeField 继承 React Aria [TimeField](https://react-aria.adobe.com/TimeField) 的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode` | - | 子组件（Label、TimeField.Group 等）或渲染函数。 |
+| `className` | `string \| (values: TimeFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 时间字段是否占满容器宽度。 |
+| `id` | `string` | - | 元素的唯一 id。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `TimeValue \| null` | - | 当前值（受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `defaultValue` | `TimeValue \| null` | - | 默认值（非受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `onChange` | `(value: TimeValue \| null) => void` | - | 值变化时触发的事件处理函数。 |
+| `placeholderValue` | `TimeValue \| null` | - | 影响占位符格式的占位时间；默认随小时制为 12:00 AM 或 00:00。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 是否在提交表单前要求用户输入。 |
+| `isInvalid` | `boolean` | - | 值是否无效。 |
+| `minValue` | `TimeValue \| null` | - | 用户可选择最早时间。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `maxValue` | `TimeValue \| null` | - | 用户可选择最晚时间。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
+| `validate` | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 |
+
+#### Format Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `granularity` | `'hour' \| 'minute' \| 'second'` | `'minute'` | 时间选择器显示的最小单位。 |
+| `hourCycle` | `12 \| 24` | - | 以 12 或 24 小时制显示时间；默认由语言环境决定。 |
+| `hideTimeZone` | `boolean` | `false` | 是否隐藏时区缩写。 |
+| `shouldForceLeadingZeros` | `boolean` | - | 是否始终为小时字段显示前导零；默认由语言环境决定。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | 输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。 |
+| `autoFocus` | `boolean` | - | 是否在渲染后自动聚焦该元素。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 标注该字段的元素 id。 |
+| `aria-describedby` | `string` | - | 描述该字段的元素 id。 |
+| `aria-details` | `string` | - | 包含额外详情的元素 id。 |
+
+### 组合组件
+
+TimeField 与以下独立组件配合使用，请分别导入并直接使用：
+
+- **Label** – 来自 `@heroui/react` 的字段标签
+- **TimeField.Group** – 时间输入分组（详见下文）
+- **TimeField.Input** – 来自 `@heroui/react` 的分段位编辑输入
+- **TimeField.Segment** – 单个时间段位（时、分、秒等）
+- **TimeField.Prefix** / **TimeField.Suffix** – 输入组的前缀与后缀插槽
+- **Description** – 来自 `@heroui/react` 的辅助说明
+- **FieldError** – 来自 `@heroui/react` 的校验错误信息
+
+这些组件各自有独立的 props API。在 TimeField 中直接组合使用：
+
+```tsx
+import {parseTime} from '@internationalized/date';
+import {TimeField, Label, Description, FieldError} from '@heroui/react';
+
+<TimeField
+  isRequired
+  isInvalid={hasError}
+  minValue={parseTime('09:00')}
+  maxValue={parseTime('17:00')}
+  value={time}
+  onChange={setTime}
+>
+  <Label>Appointment Time</Label>
+  <TimeField.Group>
+    <TimeField.Input>
+      {(segment) => <TimeField.Segment segment={segment} />}
+    </TimeField.Input>
+  </TimeField.Group>
+  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>
+  <FieldError>Please select a valid time.</FieldError>
+</TimeField>
+```
+
+### TimeValue 类型
+
+TimeField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 中的类型：
+
+- `Time` – 仅时间（时、分、秒）
+- `CalendarDateTime` – 含日期与时间、不含时区（TimeField 仅展示时间部分）
+- `ZonedDateTime` – 含日期、时间与时区（TimeField 仅展示时间部分）
+
+示例：
+
+```tsx
+import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';
+
+// Parse from string
+const time = parseTime('14:30');
+
+// Create from current time
+const currentTime = now(getLocalTimeZone());
+const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);
+
+// Use in TimeField
+<TimeField value={time} onChange={setTime}>
+  {/* ... */}
+</TimeField>
+```
+
+> **说明：** TimeField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 进行时间处理、解析与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。
+
+### TimeFieldRenderProps
+
+对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦。 |
+| `isFocusWithin` | `boolean` | 是否有子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 |
+
+### TimeField.Group Props
+
+TimeField.Group 继承 React Aria `Group` 的全部 props，并额外支持：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
+
+### TimeField.Input Props
+
+TimeField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
+
+`TimeField.Input` 接受渲染函数作为子节点，函数接收日期段位；每个段位表示时间的一部分（时、分、秒等）。
+
+### TimeField.Segment Props
+
+TimeField.Segment 继承 React Aria `DateSegment` 的全部 props：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `segment` | `DateSegment` | - | 来自 TimeField.Input 渲染函数的 `DateSegment` 对象。 |
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+
+### TimeField.Prefix Props
+
+TimeField.Prefix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 |
+
+### TimeField.Suffix Props
+
+TimeField.Suffix 接受标准 HTML `div` 属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 |
+
+## TimeField.Group 样式
+
+### 自定义组件类
+
+基础类作用于所有实例，可通过 `@layer components` 一次性覆盖。
+
+```css
+@layer components {
+  .date-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .date-input-group__input {
+    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .date-input-group__segment {
+    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;
+
+    &:focus,
+    &[data-focused="true"] {
+      @apply bg-accent-soft text-accent-soft-foreground;
+    }
+  }
+
+  .date-input-group__prefix,
+  .date-input-group__suffix {
+    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### TimeField.Group CSS 类
+
+- `.date-input-group` – 根容器样式
+- `.date-input-group__input` – 输入包裹层样式
+- `.date-input-group__segment` – 单个时间段位样式
+- `.date-input-group__prefix` – 前缀元素样式
+- `.date-input-group__suffix` – 后缀元素样式
+
+### TimeField.Group 交互状态
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **焦点在内**：`[data-focus-within="true"]` 或 `:focus-within`
+- **无效**：`[data-invalid="true"]`（同时与 `aria-invalid` 同步）
+- **禁用**：`[data-disabled="true"]` 或 `[aria-disabled="true"]`
+- **段位聚焦**：段位上的 `:focus` 或 `[data-focused="true"]`
+- **段位占位符**：段位上的 `[data-placeholder="true"]`
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/alert.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/alert.mdx
new file mode 100644
index 0000000..62509dd
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/alert.mdx
@@ -0,0 +1,147 @@
+---
+title: Alert 警告
+description: 向用户展示重要消息与通知，并提供状态指示。
+links:
+  source: alert/alert.tsx
+  styles: alert.css
+  storybook: Components/Feedback/Alert
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Alert } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+
+### 组件结构
+
+导入 Alert 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { Alert } from '@heroui/react';
+
+export default () => (
+  <Alert>
+    <Alert.Indicator />
+    <Alert.Content>
+      <Alert.Title />
+      <Alert.Description />
+    </Alert.Content>
+  </Alert>
+)
+```
+
+<RelatedComponents component="alert" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Alert } from "@heroui/react";
+
+function CustomAlert() {
+  return (
+    <Alert className="border-2 border-blue-500 rounded-xl" status="accent">
+      <Alert.Indicator className="text-blue-600" />
+      <Alert.Content className="gap-1">
+        <Alert.Title className="font-bold text-lg">Custom Alert</Alert.Title>
+        <Alert.Description className="text-sm opacity-80">
+          This alert has custom styling applied
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Alert 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .alert {
+    @apply rounded-2xl shadow-lg;
+  }
+
+  .alert__title {
+    @apply font-bold text-lg;
+  }
+
+  .alert--danger {
+    @apply border-l-4 border-red-600;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Alert 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)）：
+
+#### 基础类
+- `.alert` — Alert 根容器
+- `.alert__indicator` — 图标/指示器容器
+- `.alert__content` — 包裹标题与说明的内容容器
+- `.alert__title` — Alert 标题文本
+- `.alert__description` — Alert 说明文本
+
+#### 状态变体类
+- `.alert--default` — 默认灰色状态
+- `.alert--accent` — 强调蓝色状态
+- `.alert--success` — 成功绿色状态
+- `.alert--warning` — 警告黄/橙色状态
+- `.alert--danger` — 危险红色状态
+
+### 交互状态
+
+Alert 主要用于信息展示，基础组件本身通常没有交互状态；但它可以包含按钮或关闭按钮等交互元素。
+
+## API 参考
+
+### Alert Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Alert 的视觉状态 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | Alert 内容 |
+
+### Alert.Indicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | 自定义指示图标（默认显示状态图标） |
+
+### Alert.Content Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | 内容（通常为 Title 与 Description） |
+
+### Alert.Title Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | Alert 标题文本 |
+
+### Alert.Description Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | Alert 说明文本 |
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/meter.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/meter.mdx
new file mode 100644
index 0000000..fa2c892
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/meter.mdx
@@ -0,0 +1,160 @@
+---
+title: Meter 计量条
+description: Meter 表示已知范围内的数量，或一个比例值。
+links:
+  rac: Meter
+  source: meter/meter.tsx
+  styles: meter.css
+  storybook: Components/Feedback/Meter
+---
+
+## 引入
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="meter-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+
+export default () => (
+  <Meter value={60}>
+    <Label>Storage</Label>
+    <Meter.Output />
+    <Meter.Track>
+      <Meter.Fill />
+    </Meter.Track>
+  </Meter>
+);
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="meter-sizes"
+/>
+
+### 颜色
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+### 自定义取值范围与格式
+
+使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与展示格式。
+
+<ComponentPreview
+  name="meter-custom-value"
+/>
+
+### 无可见标签
+
+当不需要可见标签时，请使用 `aria-label` 以保证无障碍。
+
+<ComponentPreview
+  name="meter-without-label"
+/>
+
+<RelatedComponents component="meter" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以为 Meter 的各个部分分别自定义样式：
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+
+function CustomMeter() {
+  return (
+    <Meter value={60}>
+      <Label>Storage</Label>
+      <Meter.Output />
+      <Meter.Track className="bg-purple-100 dark:bg-purple-900">
+        <Meter.Fill className="bg-purple-500" />
+      </Meter.Track>
+    </Meter>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Meter 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .meter {
+    @apply w-full gap-2;
+  }
+
+  .meter__track {
+    @apply h-3 rounded-full;
+  }
+
+  .meter__fill {
+    @apply rounded-full;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Meter 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/meter.css)）：
+
+#### 基础与元素类
+- `.meter` — 基础容器（grid 布局）
+- `.meter__output` — 数值文本展示
+- `.meter__track` — 轨道背景
+- `.meter__fill` — 轨道已填充部分
+
+#### 尺寸类
+- `.meter--sm` — 小尺寸变体（更细的轨道）
+- `.meter--md` — 中等尺寸变体（默认）
+- `.meter--lg` — 大尺寸变体（更粗的轨道）
+
+#### 颜色类
+- `.meter--default` — 默认颜色变体
+- `.meter--accent` — 强调色变体
+- `.meter--success` — 成功色变体
+- `.meter--warning` — 警告色变体
+- `.meter--danger` — 危险色变体
+
+## API 参考
+
+### Meter Props
+
+继承自 [React Aria Meter](https://react-spectrum.adobe.com/react-aria/Meter.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `number` | `0` | 当前值 |
+| `minValue` | `number` | `0` | 最小值 |
+| `maxValue` | `number` | `100` | 最大值 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Meter 轨道尺寸 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 填充条颜色 |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示的格式化选项 |
+| `valueLabel` | `ReactNode` | - | 自定义数值标签内容 |
+| `children` | `ReactNode \| (values: MeterRenderProps) => ReactNode` | - | 内容或渲染 prop |
+
+### MeterRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `percentage` | `number` | Meter 百分比（0–100） |
+| `valueText` | `string` | 格式化后的数值文本 |
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/progress-bar.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/progress-bar.mdx
new file mode 100644
index 0000000..0ea3a47
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/progress-bar.mdx
@@ -0,0 +1,173 @@
+---
+title: ProgressBar 进度条
+description: 进度条用于展示某项操作随时间变化的确定或不确定进度。
+links:
+  rac: ProgressBar
+  source: progress-bar/progress-bar.tsx
+  styles: progress-bar.css
+  storybook: Components/Feedback/ProgressBar
+---
+
+## 引入
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="progress-bar-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+
+export default () => (
+  <ProgressBar value={60}>
+    <Label>Loading</Label>
+    <ProgressBar.Output />
+    <ProgressBar.Track>
+      <ProgressBar.Fill />
+    </ProgressBar.Track>
+  </ProgressBar>
+);
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="progress-bar-sizes"
+/>
+
+### 颜色
+
+<ComponentPreview
+  name="progress-bar-colors"
+/>
+
+### 不确定进度
+
+在无法确定具体进度时，使用 `isIndeterminate`。
+
+<ComponentPreview
+  name="progress-bar-indeterminate"
+/>
+
+### 自定义数值范围
+
+使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与展示格式。
+
+<ComponentPreview
+  name="progress-bar-custom-value"
+/>
+
+### 无可见标签
+
+不需要可见标签时，请使用 `aria-label` 保证无障碍。
+
+<ComponentPreview
+  name="progress-bar-without-label"
+/>
+
+<RelatedComponents component="progress-bar" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以为 ProgressBar 的各个部分单独添加类名：
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+
+function CustomProgressBar() {
+  return (
+    <ProgressBar value={60}>
+      <Label>Loading</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track className="bg-purple-100 dark:bg-purple-900">
+        <ProgressBar.Fill className="bg-purple-500" />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ProgressBar 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .progress-bar {
+    @apply w-full gap-2;
+  }
+
+  .progress-bar__track {
+    @apply h-3 rounded-full;
+  }
+
+  .progress-bar__fill {
+    @apply rounded-full;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-bar.css)）：
+
+#### 基础与元素类
+
+- `.progress-bar` - 基础容器（网格布局）
+- `.progress-bar__output` - 数值文本展示
+- `.progress-bar__track` - 轨道背景
+- `.progress-bar__fill` - 轨道上已填充部分
+
+#### 尺寸类
+
+- `.progress-bar--sm` - 小尺寸变体（更细的轨道）
+- `.progress-bar--md` - 中等尺寸变体（默认）
+- `.progress-bar--lg` - 大尺寸变体（更粗的轨道）
+
+#### 颜色类
+
+- `.progress-bar--default` - 默认颜色变体
+- `.progress-bar--accent` - 强调色变体
+- `.progress-bar--success` - 成功色变体
+- `.progress-bar--warning` - 警告色变体
+- `.progress-bar--danger` - 危险色变体
+
+## API 参考
+
+### ProgressBar Props
+
+继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `number` | `0` | 当前值 |
+| `minValue` | `number` | `0` | 最小值 |
+| `maxValue` | `number` | `100` | 最大值 |
+| `isIndeterminate` | `boolean` | `false` | 是否为不确定进度 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 进度轨道尺寸 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 填充条颜色 |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示的数字格式 |
+| `valueLabel` | `ReactNode` | - | 自定义数值标签内容 |
+| `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | 内容或渲染 prop |
+
+### ProgressBarRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `percentage` | `number` | 进度百分比（0–100） |
+| `valueText` | `string` | 格式化后的数值文本 |
+| `isIndeterminate` | `boolean` | 是否为不确定进度 |
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/progress-circle.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/progress-circle.mdx
new file mode 100644
index 0000000..a58cdbf
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/progress-circle.mdx
@@ -0,0 +1,168 @@
+---
+title: ProgressCircle 环形进度条
+description: 环形进度指示器，用于展示确定或不确定的进度。
+links:
+  rac: ProgressBar
+  source: progress-circle/progress-circle.tsx
+  styles: progress-circle.css
+  storybook: Components/Feedback/ProgressCircle
+---
+
+## 引入
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="progress-circle-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+
+export default () => (
+  <ProgressCircle aria-label="Loading" value={60}>
+    <ProgressCircle.Track>
+      <ProgressCircle.TrackCircle />
+      <ProgressCircle.FillCircle />
+    </ProgressCircle.Track>
+  </ProgressCircle>
+);
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="progress-circle-sizes"
+/>
+
+### 颜色
+
+<ComponentPreview
+  name="progress-circle-colors"
+/>
+
+### 不确定进度
+
+在无法确定具体进度时，使用 `isIndeterminate`。
+
+<ComponentPreview
+  name="progress-circle-indeterminate"
+/>
+
+### 带标签
+
+<ComponentPreview
+  name="progress-circle-with-label"
+/>
+
+### 自定义 SVG 属性
+
+由于每个部分都是可组合组件，你可以直接覆盖 `strokeWidth`、`r`、`cx`、`cy`、`viewBox` 等 SVG 属性。
+
+<ComponentPreview
+  name="progress-circle-custom-svg"
+/>
+
+<RelatedComponents component="progress-circle" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以分别自定义 ProgressCircle 的各个部分：
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+
+function CustomProgressCircle() {
+  return (
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle className="stroke-purple-500" />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ProgressCircle 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .progress-circle {
+    @apply inline-flex;
+  }
+
+  .progress-circle__track {
+    @apply size-12;
+  }
+
+  .progress-circle__fill-circle {
+    stroke: purple;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ProgressCircle 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-circle.css)）：
+
+#### 基础与元素类
+
+- `.progress-circle` - 基础容器
+- `.progress-circle__track` - SVG 元素
+- `.progress-circle__track-circle` - 背景圆环
+- `.progress-circle__fill-circle` - 进度弧
+
+#### 尺寸类
+
+- `.progress-circle--sm` - 小尺寸
+- `.progress-circle--md` - 中等尺寸（默认）
+- `.progress-circle--lg` - 大尺寸
+
+#### 颜色类
+
+- `.progress-circle--default` - 默认颜色
+- `.progress-circle--accent` - 强调色
+- `.progress-circle--success` - 成功色
+- `.progress-circle--warning` - 警告色
+- `.progress-circle--danger` - 危险色
+
+## API 参考
+
+### ProgressCircle Props
+
+继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `number` | `0` | 当前值 |
+| `minValue` | `number` | `0` | 最小值 |
+| `maxValue` | `number` | `100` | 最大值 |
+| `isIndeterminate` | `boolean` | `false` | 是否为不确定进度 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 圆环尺寸 |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 进度弧颜色 |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示格式 |
+| `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | 内容或渲染 prop |
+
+### ProgressBarRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `percentage` | `number` | 进度百分比（0–100） |
+| `valueText` | `string` | 格式化后的数值文案 |
+| `isIndeterminate` | `boolean` | 是否为不确定进度 |
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/skeleton.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/skeleton.mdx
new file mode 100644
index 0000000..b31b391
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/skeleton.mdx
@@ -0,0 +1,201 @@
+---
+title: Skeleton 骨架屏
+description: Skeleton 用于展示加载状态，并预览组件的预期形状。
+links:
+  source: skeleton/skeleton.tsx
+  styles: skeleton.css
+  storybook: Components/Feedback/Skeleton
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Skeleton } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview 
+  name="skeleton-basic"
+/>
+ 
+
+### 文本内容
+
+<ComponentPreview 
+  name="skeleton-text-content"
+/>
+
+### 用户资料
+
+<ComponentPreview 
+  name="skeleton-user-profile"
+/>
+
+### 列表项
+
+<ComponentPreview
+  name="skeleton-list"
+/>
+
+### 动画类型
+
+<ComponentPreview
+  name="skeleton-animation-types"
+/>
+
+### 网格
+
+<ComponentPreview
+  name="skeleton-grid"
+/>
+
+### 单次闪烁
+
+一种同步的闪烁效果，会一次性扫过所有骨架元素。请在父容器上应用 `skeleton--shimmer` 类，并将子级 Skeleton 的 `animationType` 设为 `"none"`。
+
+<ComponentPreview
+  name="skeleton-single-shimmer"
+  style={{'contain': 'none'}}
+/>
+
+<RelatedComponents component="skeleton" />
+
+## 样式
+
+### 全局动画配置
+
+你可以通过在应用中定义 `--skeleton-animation` CSS 变量，为所有 Skeleton 设置默认动画类型：
+
+```css
+/* In your global CSS file */
+:root {
+  /* Possible values: shimmer, pulse, none */
+  --skeleton-animation: pulse;
+}
+
+/* You can also set different values for light/dark themes */
+.light, [data-theme="light"] {
+  --skeleton-animation: shimmer;
+}
+
+.dark, [data-theme="dark"] {
+  --skeleton-animation: pulse;
+}
+```
+
+在单个组件上指定 `animationType` 时，会覆盖上述全局设置。
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Skeleton } from '@heroui/react';
+
+function CustomSkeleton() {
+  return (
+    <Skeleton className="h-20 w-32 rounded-full" />
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Skeleton 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  /* Base skeleton styles */
+  .skeleton {
+    @apply bg-surface-secondary/50; /* Change base background */
+  }
+
+  /* Shimmer animation gradient */
+  .skeleton--shimmer:before {
+    @apply viasurface; /* Change shimmer gradient color */
+  }
+
+  /* Pulse animation */
+  .skeleton--pulse {
+    @apply animate-pulse opacity-75; /* Customize pulse animation */
+  }
+
+  /* No animation variant */
+  .skeleton--none {
+    @apply opacity-50; /* Style for static skeleton */
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Skeleton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)）：
+
+#### 基础类
+`.skeleton` - 包含背景与圆角等基础骨架样式
+
+#### 动画变体类
+- `.skeleton--shimmer` - 添加带渐变效果的闪烁动画（默认）
+- `.skeleton--pulse` - 使用 Tailwind 的 `animate-pulse` 添加脉冲动画
+- `.skeleton--none` - 无动画的静态骨架
+
+### 动画
+
+Skeleton 支持三种动画类型，视觉效果各不相同：
+
+#### 闪烁动画
+
+闪烁效果会在骨架元素上移动渐变：
+
+```css
+.skeleton--shimmer:before {
+  @apply animate-skeleton via-surface-3 absolute inset-0 -translate-x-full
+         bg-gradient-to-r from-transparent to-transparent content-[''];
+}
+```
+
+闪烁动画在主题中通过以下方式定义：
+
+```css
+@theme inline {
+  --animate-skeleton: skeleton 2s linear infinite;
+
+  @keyframes skeleton {
+    100% {
+      transform: translateX(200%);
+    }
+  }
+}
+```
+
+#### 脉冲动画
+
+脉冲动画使用 Tailwind 内置的 `animate-pulse` 工具类：
+
+```css
+.skeleton--pulse {
+  @apply animate-pulse;
+}
+```
+
+#### 无动画
+
+用于不需要任何动画的静态骨架：
+
+```css
+.skeleton--none {
+  /* No animation styles applied */
+}
+```
+
+## API 参考
+
+### Skeleton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` 或 CSS 变量 | Skeleton 的动画类型；也可通过 `--skeleton-animation` CSS 变量进行全局配置 |
+| `className` | `string` | - | 额外的 CSS 类名 |
diff --git a/apps/docs/content/docs/cn/react/components/(feedback)/spinner.mdx b/apps/docs/content/docs/cn/react/components/(feedback)/spinner.mdx
new file mode 100644
index 0000000..7910552
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(feedback)/spinner.mdx
@@ -0,0 +1,96 @@
+---
+title: Spinner 加载指示器
+description: 用于展示等待或处理中状态的加载指示组件。
+links:
+  source: spinner/spinner.tsx
+  styles: spinner.css
+  storybook: Components/Feedback/Spinner
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Spinner } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="spinner-basic"
+/>
+
+### 颜色
+
+<ComponentPreview
+  name="spinner-colors"
+/>
+
+### 尺寸
+
+<ComponentPreview
+  name="spinner-sizes"
+/>
+
+<RelatedComponents component="spinner" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Spinner} from '@heroui/react';
+
+function CustomSpinner() {
+  return (
+    <Spinner className="text-blue-500" />
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Spinner 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .spinner {
+    @apply animate-spin;
+  }
+
+  .spinner--accent {
+    color: var(--accent);
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Spinner 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)）：
+
+#### 基础类与尺寸类
+- `.spinner` - 基础样式与默认尺寸
+- `.spinner--sm` - 小尺寸变体
+- `.spinner--md` - 中等尺寸变体（默认）
+- `.spinner--lg` - 大尺寸变体
+- `.spinner--xl` - 特大尺寸变体
+
+#### 颜色类
+- `.spinner--current` - 继承当前文本颜色
+- `.spinner--accent` - 强调色变体
+- `.spinner--danger` - 危险色变体
+- `.spinner--success` - 成功色变体
+- `.spinner--warning` - 警告色变体
+
+## API 参考
+
+### Spinner Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Spinner 的尺寸 |
+| `color` | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Spinner 的颜色变体 |
+| `className` | `string` | - | 额外的 CSS 类名 |
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/checkbox-group.mdx b/apps/docs/content/docs/cn/react/components/(forms)/checkbox-group.mdx
new file mode 100644
index 0000000..53b8aaf
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/checkbox-group.mdx
@@ -0,0 +1,176 @@
+---
+title: CheckboxGroup 复选框组
+description: 用于管理多项复选框选择的 CheckboxGroup 组件。
+icon: updated
+links:
+  rac: CheckboxGroup
+  source: checkbox-group/checkbox-group.tsx
+  styles: checkbox-group.css
+  storybook: Components/Forms/CheckboxGroup
+---
+
+## 引入
+
+```tsx
+import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="checkbox-group-basic"
+/>
+
+### 组件结构
+
+导入 CheckboxGroup 组件，并通过点语法访问所有子部分。
+
+```tsx
+import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <CheckboxGroup name="interests">
+    <Label />
+    <Description /> {/* Optional */}
+    <Checkbox value="option1">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Label {/* 纯文本 —— 可点击的标签 */}
+      </Checkbox.Content>
+      <Description /> {/* 可选：单个复选框的帮助文本 */}
+    </Checkbox>
+    <FieldError /> {/* Optional */}
+  </CheckboxGroup>
+);
+```
+
+### 在 Surface 内
+
+置于 [Surface](/docs/components/surface) 中时，使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview
+  name="checkbox-group-on-surface"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="checkbox-group-with-custom-indicator"
+/>
+
+### 不定状态
+
+<ComponentPreview
+  name="checkbox-group-indeterminate"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="checkbox-group-controlled"
+/>
+
+### 校验
+
+<ComponentPreview
+  name="checkbox-group-validation"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="checkbox-group-disabled"
+/>
+
+### 特性与附加示例
+
+<ComponentPreview
+  name="checkbox-group-features-and-addons"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="checkbox-group-custom-render-function"
+/>
+
+<RelatedComponents component="checkboxgroup" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以自定义 CheckboxGroup 组件：
+
+```tsx
+import { CheckboxGroup, Checkbox, Label } from '@heroui/react';
+
+function CustomCheckboxGroup() {
+  return (
+    <CheckboxGroup className="gap-4" name="custom">
+      <Checkbox value="option1">
+        <Checkbox.Content>
+          <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
+            <Checkbox.Indicator className="text-white" />
+          </Checkbox.Control>
+          Option 1
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 CheckboxGroup 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .checkbox-group {
+    @apply flex flex-col gap-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)）：
+
+- `.checkbox-group` - 复选框组合容器基础样式
+
+## API 参考
+
+### CheckboxGroup Props
+
+继承自 [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string[]` | - | 当前选中值（受控） |
+| `defaultValue` | `string[]` | - | 默认选中值（非受控） |
+| `onChange` | `(value: string[]) => void` | - | 选中值变化时调用的处理函数 |
+| `isDisabled` | `boolean` | `false` | 是否禁用整个复选框组合 |
+| `isRequired` | `boolean` | `false` | 是否必填 |
+| `isReadOnly` | `boolean` | `false` | 是否只读 |
+| `isInvalid` | `boolean` | `false` | 是否处于无效状态 |
+| `name` | `string` | - | 提交 HTML 表单时复选框组合的名称 |
+| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | 复选框组合内容或渲染 prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### CheckboxGroupRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `value` | `string[]` | 当前选中值 |
+| `isDisabled` | `boolean` | 是否禁用 |
+| `isReadOnly` | `boolean` | 是否只读 |
+| `isInvalid` | `boolean` | 是否处于无效状态 |
+| `isRequired` | `boolean` | 是否必填 |
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/checkbox.mdx b/apps/docs/content/docs/cn/react/components/(forms)/checkbox.mdx
new file mode 100644
index 0000000..4d9992b
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/checkbox.mdx
@@ -0,0 +1,263 @@
+---
+title: Checkbox 复选框
+description: 复选框允许用户从多个独立选项中选择多项，或将单个独立选项标记为已选。
+icon: updated
+links:
+  rac: CheckboxField
+  source: checkbox/checkbox.tsx
+  styles: checkbox.css
+  storybook: Components/Forms/Checkbox
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Checkbox } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+### 组件结构
+
+引入 Checkbox 后，可通过点语法访问各个部分。
+
+```tsx
+import { Checkbox, Description, FieldError } from '@heroui/react';
+
+export default () => (
+  <Checkbox>
+    <Checkbox.Content>
+      <Checkbox.Control>
+        <Checkbox.Indicator />
+      </Checkbox.Control>
+      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
+    </Checkbox.Content>
+    <Description /> {/* 可选 — 字段级帮助文本 */}
+    <FieldError /> {/* 可选 — 校验错误信息 */}
+  </Checkbox>
+);
+```
+
+### 禁用
+
+<ComponentPreview
+  name="checkbox-disabled"
+/>
+
+### 默认选中
+
+<ComponentPreview
+  name="checkbox-default-selected"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="checkbox-controlled"
+/>
+
+### 不定状态
+
+<ComponentPreview
+  name="checkbox-indeterminate"
+/>
+
+### 外部标签
+
+<ComponentPreview
+  name="checkbox-external-label"
+/>
+
+### 带说明
+
+<ComponentPreview
+  name="checkbox-with-description"
+/>
+
+### 渲染 props
+
+<ComponentPreview
+  name="checkbox-render-props"
+/>
+
+### 表单集成
+
+<ComponentPreview
+  name="checkbox-form"
+/>
+
+### 无效
+
+<ComponentPreview
+  name="checkbox-invalid"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="checkbox-custom-indicator"
+/>
+
+### 全圆角
+
+<ComponentPreview
+  name="checkbox-full-rounded"
+/>
+
+### 变体
+
+Checkbox 支持两种视觉变体：
+
+- **`primary`**（默认）— 常规样式与默认背景，适用于大多数场景
+- **`secondary`** — 弱强调变体，适合用于 Surface 等组件内部
+
+<ComponentPreview name="checkbox-variants" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="checkbox-custom-render-function"
+/>
+
+<RelatedComponents component="checkbox" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以单独定制各个 Checkbox：
+
+```tsx
+import { Checkbox, Label } from '@heroui/react';
+
+function CustomCheckbox() {
+  return (
+    <Checkbox name="custom">
+      <Checkbox.Content>
+        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
+          <Checkbox.Indicator className="text-white" />
+        </Checkbox.Control>
+        Custom Checkbox
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Checkbox 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .checkbox {
+    @apply inline-flex gap-3 items-center;
+  }
+
+  .checkbox__control {
+    @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;
+
+    /* Animated background indicator */
+    &::before {
+      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
+      
+      transition:
+        scale 200ms linear,
+        opacity 200ms linear,
+        background-color 200ms ease-out;
+    }
+
+    /* Show indicator when selected */
+    &[data-selected="true"]::before {
+      @apply scale-100 opacity-100;
+    }
+  }
+
+  .checkbox__indicator {
+    @apply text-white;
+  }
+
+  .checkbox__content {
+    @apply items-center gap-3;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Checkbox 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)）：
+
+- `.checkbox` - Checkbox 根容器
+- `.checkbox__content` - 包裹控件与标签文本的可点击 label
+- `.checkbox__control` - Checkbox 控件方框
+- `.checkbox__indicator` - Checkbox 勾选指示器
+
+### 交互状态
+
+Checkbox 同时支持 CSS 伪类与 data 属性，以获得更好的灵活性：
+
+- **选中**：`[data-selected="true"]` 或 `[aria-checked="true"]`（显示勾选与背景色变化）
+- **不定**：`[data-indeterminate="true"]`（以横线表示不定状态）
+- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（以危险色显示错误状态）
+- **悬停**：`:hover` 或 `[data-hovered="true"]`（交互状态在 `Checkbox.Control` / 按钮上）
+- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环，作用于按钮）
+- **禁用**：`[data-disabled="true"]`（降低透明度并禁用指针事件）
+- **按下**：`:active` 或 `[data-pressed="true"]`
+
+## API 参考
+
+### Checkbox Props
+
+继承自 [React Aria CheckboxField](https://react-spectrum.adobe.com/react-aria/Checkbox.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isSelected` | `boolean` | `false` | Checkbox 是否选中 |
+| `defaultSelected` | `boolean` | `false` | Checkbox 默认是否选中（非受控） |
+| `isIndeterminate` | `boolean` | `false` | Checkbox 是否处于不定状态 |
+| `isDisabled` | `boolean` | `false` | Checkbox 是否禁用 |
+| `isInvalid` | `boolean` | `false` | Checkbox 是否无效 |
+| `isReadOnly` | `boolean` | `false` | Checkbox 是否只读 |
+| `isRequired` | `boolean` | `false` | Checkbox 是否必须选中 |
+| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验或 ARIA 校验 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |
+| `name` | `string` | - | input 元素的 name，用于提交 HTML 表单 |
+| `value` | `string` | - | input 元素的 value，用于提交 HTML 表单 |
+| `onChange` | `(isSelected: boolean) => void` | - | Checkbox 值变化时调用 |
+| `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | Checkbox 内容或字段级渲染 prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### Checkbox.Content Props
+
+包裹控件与标签文本的可点击 `<label>`。请把 `Checkbox.Control` 与 `Label` 放在它内部；`Description`/`FieldError` 作为 `Checkbox.Content` 的兄弟节点。对于没有标签的 checkbox，省略 `Label` 并在 `Checkbox` 上传入 `aria-label`。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签），或按钮级渲染 prop |
+| `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | 应用到可点击 label 的类名 |
+
+### CheckboxFieldRenderProps
+
+在根 `Checkbox` 上使用渲染 prop 时，提供以下字段级值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | Checkbox 当前是否选中 |
+| `isIndeterminate` | `boolean` | Checkbox 是否处于不定状态 |
+| `isDisabled` | `boolean` | Checkbox 是否禁用 |
+| `isReadOnly` | `boolean` | Checkbox 是否只读 |
+| `isInvalid` | `boolean` | Checkbox 是否无效 |
+| `isRequired` | `boolean` | Checkbox 是否必填 |
+
+### CheckboxButtonRenderProps
+
+`Checkbox.Control` 与 `Checkbox.Indicator` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Checkbox.Control` 或 `Checkbox.Indicator` 的子元素即可访问。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/description.mdx b/apps/docs/content/docs/cn/react/components/(forms)/description.mdx
new file mode 100644
index 0000000..06d6d3e
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/description.mdx
@@ -0,0 +1,73 @@
+---
+title: Description 描述
+description: 为表单字段及其他组件提供补充说明文字。
+links:
+  rac: TextField
+  source: description/description.tsx
+  styles: description.css
+---
+
+## 引入
+
+```tsx
+import { Description } from '@heroui/react';
+```
+
+## 用法
+
+<ComponentPreview
+  name="description-basic"
+/>
+
+<RelatedComponents component="description" />
+
+## API 参考
+
+### Description Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | Description 的内容。 |
+
+## 无障碍
+
+Description 组件通过以下方式增强无障碍：
+
+- 使用语义化 HTML，屏幕阅读器可识别
+- 提供 `slot="description"` 属性以便与 React Aria 集成
+- 支持适宜的文本对比度
+
+## 样式
+
+Description 组件使用以下 CSS 类：
+
+- `.description` - 基础 Description 样式，使用弱化（muted）文本颜色
+
+## 示例
+
+### 与表单字段一起使用
+
+```tsx
+<div className="flex flex-col gap-1">
+  <Label htmlFor="password">Password</Label>
+  <Input id="password" type="password" aria-describedby="password-description" />
+  <Description id="password-description">
+    Must be at least 8 characters with one uppercase letter
+  </Description>
+</div>
+```
+ 
+### 与 TextField 集成
+
+```tsx
+import {TextField, Label, Input, Description} from '@heroui/react';
+
+<TextField type="email">
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description>We'll never share your email</Description>
+</TextField>
+```
+
+使用 [TextField](./text-field) 组件时，无障碍属性会自动应用到 Label 与 Description 上。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/error-message.mdx b/apps/docs/content/docs/cn/react/components/(forms)/error-message.mdx
new file mode 100644
index 0000000..7df054c
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/error-message.mdx
@@ -0,0 +1,118 @@
+---
+title: ErrorMessage 错误信息
+description: 用于展示错误信息的底层组件。
+links:
+  rac: TagGroup
+  source: error-message/error-message.tsx
+  styles: error-message.css
+---
+
+## 引入
+
+```tsx
+import { ErrorMessage } from '@heroui/react';
+```
+
+## 用法
+
+`ErrorMessage` 是基于 React Aria `Text`、并使用 `errorMessage` 插槽的底层组件，适用于 **非表单** 场景（例如 `TagGroup`、`Calendar` 等集合类组件）。
+
+<ComponentPreview
+  name="error-message-basic"
+/>
+
+### 组件结构
+
+```tsx
+import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
+
+<TagGroup>
+  <Label />
+  <TagGroup.List>
+    <Tag />
+  </TagGroup.List>
+  <Description />
+  <ErrorMessage />
+</TagGroup>
+```
+
+<RelatedComponents component="errormessage" />
+
+## 何时使用
+
+`ErrorMessage` **不绑定表单**，是用于非表单上下文的通用错误展示组件。
+
+- **推荐用于** 非表单组件（例如 `TagGroup`、`Calendar`、集合类组件）
+- **对于表单字段**，我们更推荐使用 [`FieldError`](/docs/components/field-error)，它提供表单相关的校验能力与自动错误处理，并遵循标准化的表单校验模式。
+
+## ErrorMessage 与 FieldError
+
+| 组件 | 使用场景 | 表单集成 | 示例组件 |
+| --- | --- | --- | --- |
+| `ErrorMessage` | 非表单组件 | 否 | `TagGroup`、`Calendar` |
+| `FieldError` | 表单字段（推荐） | 是 | `TextField`、`NumberField`、`Select` |
+
+对于表单校验，我们推荐使用 `FieldError`，因为它遵循标准化的表单校验模式并提供表单相关能力。示例与最佳实践见 [FieldError 文档](/docs/components/field-error) 与 [Form 指南](/docs/components/form)。
+
+## API 参考
+
+### ErrorMessage Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 错误信息内容 |
+
+**说明：** `ErrorMessage` 基于 React Aria 的 `Text` 组件，并使用 `slot="errorMessage"`。你可以使用 `[slot=errorMessage]` CSS 选择器进行样式覆盖。
+
+## 无障碍
+
+ErrorMessage 通过以下方式增强无障碍：
+
+- 使用屏幕阅读器可识别的语义化 HTML
+- 提供 `slot="errorMessage"` 属性以集成 React Aria
+- 为错误状态提供合适的文本对比度
+- 遵循 WAI-ARIA 的错误信息最佳实践
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ErrorMessage } from '@heroui/react';
+
+function CustomErrorMessage() {
+  return (
+    <ErrorMessage className="font-bold text-sm">
+      Custom styled error message
+    </ErrorMessage>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 ErrorMessage 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .error-message {
+    @apply text-red-600 text-sm font-medium;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ErrorMessage 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)）：
+
+#### 基础类
+
+- `.error-message` - 危险色与文本截断等基础样式
+
+#### 插槽类
+
+- `[slot="errorMessage"]` - 与 React Aria 集成的 ErrorMessage 插槽样式
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/field-error.mdx b/apps/docs/content/docs/cn/react/components/(forms)/field-error.mdx
new file mode 100644
index 0000000..3fa1cf9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/field-error.mdx
@@ -0,0 +1,121 @@
+---
+title: FieldError 字段错误
+description: 用于展示表单字段的校验错误信息。
+links:
+  rac: FieldError
+  source: field-error/field-error.tsx
+  styles: field-error.css
+---
+
+## 引入
+
+```tsx
+import { FieldError } from '@heroui/react';
+```
+
+## 用法
+
+FieldError 组件用于展示表单字段的校验错误信息。当父级字段被标记为无效时会自动显示，并提供平滑的透明度过渡。
+
+<ComponentPreview
+  name="field-error-basic"
+/>
+
+<RelatedComponents component="fielderror" />
+
+## API 参考
+
+### FieldError Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | 错误信息内容或渲染函数。 |
+
+## 无障碍
+
+FieldError 组件通过以下方式保证无障碍：
+
+- 使用恰当的 ARIA 属性以播报错误
+- 通过语义化 HTML 支持屏幕阅读器
+- 同时提供视觉与程序化的错误提示
+- 根据校验状态自动控制可见性
+
+## 样式
+
+FieldError 组件使用以下 CSS 类：
+
+- `.field-error` - 基础错误样式，使用危险色（danger）
+- 仅在存在 `data-visible` 属性时显示
+- 长文案会以省略号截断
+
+## 示例
+
+### 基础校验
+
+```tsx
+export function Basic() {
+  const [value, setValue] = useState("");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <TextField className="w-64" isInvalid={isInvalid}>
+      <Label htmlFor="username">Username</Label>
+      <Input
+        id="username"
+        placeholder="Enter username"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <FieldError>Username must be at least 3 characters</FieldError>
+    </TextField>
+  );
+}
+```
+
+### 动态错误信息
+
+```tsx
+<TextField isInvalid={errors.length > 0}>
+  <Label>Password</Label>
+  <Input type="password" />
+  <FieldError>
+    {(validation) => validation.validationErrors.join(', ')}
+  </FieldError>
+</TextField>
+```
+
+### 自定义校验逻辑
+
+```tsx
+function EmailField() {
+  const [email, setEmail] = useState('');
+  const isInvalid = email.length > 0 && !email.includes('@');
+
+  return (
+    <TextField isInvalid={isInvalid}>
+      <Label>Email</Label>
+      <Input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <FieldError>Email must include @ symbol</FieldError>
+    </TextField>
+  );
+}
+```
+
+### 多条错误信息
+
+```tsx
+<TextField isInvalid={hasErrors}>
+  <Label>Username</Label>
+  <Input />
+  <FieldError>
+    {errors.map((error, i) => (
+      <div key={i}>{error}</div>
+    ))}
+  </FieldError>
+</TextField>
+```
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/fieldset.mdx b/apps/docs/content/docs/cn/react/components/(forms)/fieldset.mdx
new file mode 100644
index 0000000..4bf77c6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/fieldset.mdx
@@ -0,0 +1,144 @@
+---
+title: Fieldset 字段集
+description: 使用 legend、description 与操作区对相关表单控件进行分组。
+links:
+  source: fieldset/fieldset.tsx
+  styles: fieldset.css
+  storybook: Components/Forms/Fieldset
+---
+
+## 引入
+
+```tsx
+import { Fieldset } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="fieldset-basic" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 组件内部使用时，请在表单控件（Input、TextArea 等）上使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
+
+<ComponentPreview name="fieldset-on-surface" />
+
+### 组件结构
+
+引入 Fieldset 后，可通过点语法访问各个部分。
+
+```tsx
+import { Fieldset } from '@heroui/react';
+
+export default () => (
+  <Fieldset>
+    <Fieldset.Legend />
+    <Fieldset.Group>
+      {/* form fields go here */}
+    </Fieldset.Group>
+    <Fieldset.Actions>
+      {/* action buttons go here */}
+    </Fieldset.Actions>
+  </Fieldset>
+)
+```
+
+<RelatedComponents component="fieldset" />
+
+<RelatedShowcases component="Fieldset" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Fieldset, TextField, Label, Input } from '@heroui/react';
+
+function CustomFieldset() {
+  return (
+    <Fieldset className="rounded-xl border border-border bg-surface p-6 shadow-sm">
+      <Fieldset.Legend className="text-lg font-semibold">Team members</Fieldset.Legend>
+      <Fieldset.Group className="grid gap-4 md:grid-cols-2">
+        <TextField>
+          <Label>First name</Label>
+          <Input className="rounded-full border-border/60" placeholder="Jane" />
+        </TextField>
+        <TextField>
+          <Label>Last name</Label>
+          <Input className="rounded-full border-border/60" placeholder="Doe" />
+        </TextField>
+      </Fieldset.Group>
+      <Fieldset.Actions className="justify-end gap-3">
+        {/* Action buttons */}
+      </Fieldset.Actions>
+    </Fieldset>
+  );
+}
+```
+
+### 自定义组件类
+
+使用 `@layer components` 指令，针对 Fieldset 的 [BEM](https://getbem.com/) 风格类名进行定制。
+
+```css
+@layer components {
+  .fieldset {
+    @apply gap-5 rounded-xl border border-border/60 bg-surface p-6 shadow-field;
+  }
+
+  .fieldset__legend {
+    @apply text-lg font-semibold;
+  }
+
+  .fieldset__field_group {
+    @apply gap-3 md:grid md:grid-cols-2;
+  }
+
+  .fieldset__actions {
+    @apply flex justify-end gap-2 pt-2;
+  }
+}
+```
+
+### CSS 类
+
+Fieldset 复合组件暴露以下 CSS 选择器：
+
+- `.fieldset` – 根容器
+- `.fieldset__legend` – Legend 元素
+- `.fieldset__field_group` – 分组字段的包裹层
+- `.fieldset__actions` – 字段下方的操作栏
+
+## API 参考
+
+### Fieldset Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 应用到根元素上的 Tailwind CSS 类。 |
+| `children` | `React.ReactNode` | - | Fieldset 内容（legend、分组、description、操作区等）。 |
+| `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | 支持原生 fieldset 的属性与事件。 |
+
+### Fieldset.Legend Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | legend 元素的 Tailwind 类。 |
+| `children` | `React.ReactNode` | - | Legend 内容，通常为纯文本。 |
+| `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` |  - | 原生 legend 属性。 |
+
+### Fieldset.Group Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 分组字段的布局与间距类。 |
+| `children` | `React.ReactNode` | - | 在 fieldset 内分组的表单控件。 |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性。 |
+
+### Fieldset.Actions Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 用于对齐操作按钮或辅助文本的 Tailwind 类。 |
+| `children` | `React.ReactNode` | - | 操作按钮或辅助文本。 |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性。 |
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/form.mdx b/apps/docs/content/docs/cn/react/components/(forms)/form.mdx
new file mode 100644
index 0000000..fe6382c
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/form.mdx
@@ -0,0 +1,158 @@
+---
+title: Form 表单
+description: 用于表单校验与提交处理的包装组件。
+links:
+  source: form/form.tsx
+  rac: https://react-spectrum.adobe.com/react-aria/Form.html
+---
+
+## 引入
+
+```tsx
+import { Form } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="form-basic" />
+
+### 组件结构
+
+引入所有组件部分，并自由组合：
+
+```tsx
+import {Form, Button} from '@heroui/react';
+
+export default () => (
+  <Form>
+    {/* Form fields go here */}
+    <Button type="submit"/>
+    <Button type="reset"/>
+  </Form>
+)
+```
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="form-custom-render-function"
+/>
+
+<RelatedComponents component="form" />
+
+<RelatedShowcases component="Form" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react';
+
+function CustomForm() {
+  return (
+    <Form className="w-full max-w-md space-y-4 rounded-lg border border-border bg-surface p-6">
+      <TextField>
+        <Label className="text-sm font-medium">Email</Label>
+        <Input className="rounded-full border-border/60" placeholder="Enter your email" />
+        <FieldError className="text-xs" />
+      </TextField>
+      <Button type="submit" className="w-full">
+        Submit
+      </Button>
+    </Form>
+  );
+}
+```
+
+## API 参考
+
+### Form Props
+
+Form 组件是对 React Aria `Form` 原语的封装，提供表单校验与提交处理能力。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `action` | `string \| FormHTMLAttributes['action']` | - | 表单数据提交的目标 URL。 |
+| `className` | `string` | - | 应用到 form 元素上的 Tailwind CSS 类。 |
+| `children` | `React.ReactNode` | - | 表单内容（字段、按钮等）。 |
+| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | 表单数据提交时的编码类型。 |
+| `method` | `'get' \| 'post'` | - | 提交表单时使用的 HTTP 方法。 |
+| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单校验失败时调用的处理函数。默认会聚焦第一个无效字段，使用 `preventDefault()` 可自定义聚焦行为。 |
+| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单被重置时调用的处理函数。 |
+| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单被提交时调用的处理函数。 |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | 提交表单后响应的展示位置。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用浏览器原生 HTML 校验还是 ARIA 校验。`'native'` 会阻止表单提交，`'aria'` 会实时显示错误。 |
+| `validationErrors` | `ValidationErrors` | - | 按字段名映射的服务端校验错误。错误会立即展示，并在用户修改字段后自动清除。 |
+| `aria-label` | `string` | - | 表单的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于为表单提供标签的元素 ID。提供后会创建 form landmark。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### 表单校验
+
+Form 组件集成了 React Aria 的校验体系，你可以：
+
+- 使用内置的 HTML5 校验属性（`required`、`minLength`、`pattern` 等）
+- 在 TextField 等组件上提供自定义校验函数
+- 通过 FieldError 组件展示校验错误
+- 在提交时进行完整的校验处理
+- 通过 `validationErrors` prop 提供服务端校验错误
+
+#### 校验行为
+
+`validationBehavior` prop 控制校验信息的展示方式：
+
+- **`native`**（默认）：使用浏览器原生 HTML 校验，发生错误时阻止表单提交。
+- **`aria`**：使用 ARIA 属性进行校验，在用户输入时实时显示错误，且不会阻止提交。
+
+该行为可以在 form 层级设置，也可以在单个字段层级覆盖。
+
+### 表单提交
+
+表单可以通过多种方式提交：
+
+- **传统提交**：设置 `action` prop 提交到一个 URL
+- **JavaScript 处理**：使用 `onSubmit` 处理函数处理表单数据
+- **FormData API**：在提交处理函数中使用 FormData API 读取表单数据
+
+使用 FormData 的示例：
+
+```tsx
+function handleSubmit(e: FormEvent<HTMLFormElement>) {
+  e.preventDefault();
+  const formData = new FormData(e.currentTarget);
+  const data = Object.fromEntries(formData);
+  console.log('Form data:', data);
+}
+```
+
+### 与表单字段集成
+
+Form 组件可与 HeroUI 的所有表单字段组件无缝配合：
+
+- **TextField**：带标签与校验的文本输入
+- **Checkbox**：布尔选择
+- **RadioGroup**：从多个选项中单选
+- **Switch**：切换控件
+- **Button**：用于表单提交与重置
+
+所有字段组件在置于 Form 内部时，都会自动接入 Form 的校验与提交行为。
+
+### 无障碍
+
+使用 React Aria 组件时，表单默认即具备良好的无障碍能力，主要特性包括：
+
+- 原生 `<form>` 元素语义
+- 通过 `aria-label` 或 `aria-labelledby` 创建 form landmark
+- 校验失败时自动聚焦管理
+- 设置 `validationBehavior="aria"` 时使用 ARIA 校验属性
+
+### 进阶用法
+
+更高级的使用场景，包括：
+- 自定义校验上下文
+- Form context provider
+- 与第三方库的集成
+- 校验错误时的自定义聚焦管理
+
+请参考 [React Aria Form 文档](https://react-spectrum.adobe.com/react-aria/Form.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/input-group.mdx b/apps/docs/content/docs/cn/react/components/(forms)/input-group.mdx
new file mode 100644
index 0000000..889aa05
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/input-group.mdx
@@ -0,0 +1,379 @@
+---
+title: InputGroup 输入框组
+description: 将相关输入控件与前后缀元素组合，以增强表单字段。
+links:
+  rac: Group
+  source: input-group/input-group.tsx
+  styles: input-group.css
+  storybook: Components/Forms/InputGroup
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { InputGroup } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="input-group-default" />
+
+### 组件结构
+
+```tsx
+import {InputGroup, TextField, Label} from '@heroui/react';
+
+export default () => (
+  <TextField>
+    <Label />
+    <InputGroup>
+      <InputGroup.Prefix />
+      <InputGroup.Input /> {/* Or use InputGroup.TextArea for multiline input */}
+      <InputGroup.Suffix />
+    </InputGroup>
+  </TextField>
+)
+```
+
+> **InputGroup** 使用可选的前缀与后缀包裹输入框，形成视觉上统一的组合。通常放在 **[TextField](/docs/components/text-field)** 内，用于在输入前后添加图标、文字、按钮等元素。单行输入请使用 **InputGroup.Input**，多行输入请使用 **InputGroup.TextArea**。
+
+### 前缀图标
+
+在输入框前添加图标。
+
+<ComponentPreview name="input-group-with-prefix-icon" />
+
+### 后缀图标
+
+在输入框后添加图标。
+
+<ComponentPreview name="input-group-with-suffix-icon" />
+
+### 前缀与后缀
+
+同时组合前缀与后缀。
+
+<ComponentPreview name="input-group-with-prefix-and-suffix" />
+
+### 文字前缀
+
+使用文字作为前缀，例如货币符号或协议前缀。
+
+<ComponentPreview name="input-group-with-text-prefix" />
+
+### 文字后缀
+
+使用文字作为后缀，例如域名后缀或单位。
+
+<ComponentPreview name="input-group-with-text-suffix" />
+
+### 图标前缀与文字后缀
+
+组合图标前缀与文字后缀。
+
+<ComponentPreview name="input-group-with-icon-prefix-and-text-suffix" />
+
+### 复制按钮后缀
+
+在后缀中加入交互按钮，例如复制按钮。
+
+<ComponentPreview name="input-group-with-copy-suffix" />
+
+### 图标前缀与复制按钮
+
+组合图标前缀与交互式后缀按钮。
+
+<ComponentPreview name="input-group-with-icon-prefix-and-copy-suffix" />
+
+### 密码显隐切换
+
+在后缀中使用按钮切换密码可见性。
+
+<ComponentPreview name="input-group-password-with-toggle" />
+
+### 加载状态
+
+在后缀显示加载指示器，表示正在处理。
+
+<ComponentPreview name="input-group-with-loading-suffix" />
+
+### 键盘快捷键
+
+使用 [Kbd](/docs/components/kbd) 组件展示键盘快捷键。
+
+<ComponentPreview name="input-group-with-keyboard-shortcut" />
+
+### Badge 后缀
+
+在后缀中加入徽章或 chip，用于展示状态或标签。
+
+<ComponentPreview name="input-group-with-badge-suffix" />
+
+### 必填字段
+
+InputGroup 会遵循父级 TextField 的必填状态。
+
+<ComponentPreview name="input-group-required" />
+
+### 校验
+
+InputGroup 会自动反映父级 TextField 的无效状态。
+
+<ComponentPreview name="input-group-invalid" />
+
+### 禁用状态
+
+InputGroup 会遵循父级 TextField 的禁用状态。
+
+<ComponentPreview name="input-group-disabled" />
+
+### 全宽
+
+<ComponentPreview name="input-group-full-width" />
+
+### 变体
+
+InputGroup 支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+
+<ComponentPreview name="input-group-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="input-group-on-surface" />
+
+### 搭配 TextArea
+
+多行输入请使用 **InputGroup.TextArea**，并搭配前缀与后缀。当存在 textarea 时，容器高度会自动适应内容，并将前缀/后缀与顶部对齐。
+
+<ComponentPreview name="input-group-with-textarea" />
+
+<RelatedComponents component="inputgroup" />
+
+<RelatedShowcases component="InputGroup" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {InputGroup, TextField, Label} from '@heroui/react';
+
+function CustomInputGroup() {
+  return (
+    <TextField>
+      <Label>Website</Label>
+      <InputGroup className="rounded-xl border-2 border-primary">
+        <InputGroup.Prefix className="bg-primary/10 text-primary">
+          https://
+        </InputGroup.Prefix>
+        <InputGroup.Input className="font-medium" />
+        <InputGroup.Suffix className="bg-primary/10 text-primary">
+          .com
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
+```
+
+### 自定义组件类
+
+InputGroup 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
+
+```css
+@layer components {
+  .input-group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex min-h-9 items-center overflow-hidden border text-sm outline-none;
+  }
+
+  .input-group__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .input-group__prefix {
+    @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3;
+  }
+
+  .input-group__suffix {
+    @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3;
+  }
+
+  /* Secondary variant */
+  .input-group--secondary {
+    @apply shadow-none;
+    background-color: var(--color-default);
+  }
+}
+```
+
+### CSS 类
+
+- `.input-group` – 根容器：带边框、背景与 flex 布局。默认使用 `min-h-9` 与 `items-center`；当存在 textarea 时会切换为 `items-start`。
+- `.input-group__input` – 透明背景、无边框的输入元素。textarea 也使用该基础类。
+- `.input-group__prefix` – 左侧圆角的前缀容器。与 textarea 搭配时与顶部对齐。
+- `.input-group__suffix` – 右侧圆角的后缀容器。与 textarea 搭配时与顶部对齐。
+- `.input-group--primary` – 带阴影的主变体（默认）
+- `.input-group--secondary` – 无阴影的次变体，适合用在 surface 上
+
+**说明：** 使用 `InputGroup.TextArea` 时，容器会从 `items-center` 切换为 `items-start`，并使用 `height: auto` 替代固定高度。前缀与后缀与顶部对齐，并增加内边距以匹配 textarea 的垂直内边距。textarea 使用相同的 `.input-group__input` 基础类，并通过 `[data-slot="input-group-textarea"]` 选择器应用 textarea 专用样式（最小高度与纵向 resize）。
+
+### 交互状态
+
+InputGroup 会根据状态自动管理以下 data 属性：
+
+- **Hover**：`[data-hovered]` – 悬停在整个组合上时应用
+- **Focus Within**：`[data-focus-within]` – 输入框聚焦时应用
+- **Invalid**：`[data-invalid]` – 父级 TextField 为无效时应用
+- **Disabled**：`[data-disabled]` 或 `[aria-disabled]` – 父级 TextField 为禁用时应用
+
+## API 参考
+
+### InputGroup Props
+
+InputGroup 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、TextArea、Prefix、Suffix）或渲染函数。 |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 输入组是否占满容器宽度 |
+| `id` | `string` | - | 元素的唯一标识符。 |
+
+#### Variant Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于标注该组的元素 ID。 |
+| `aria-describedby` | `string` | - | 用于描述该组的元素 ID。 |
+| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
+| `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | 分组的无障碍角色。重要内容可使用 `region`，纯视觉分组可使用 `presentation`。 |
+
+### Composition Components
+
+InputGroup 与以下子组件配合使用：
+
+- **InputGroup.Root** – 根容器（也可直接写作 `InputGroup`）
+- **InputGroup.Input** – 单行输入元素组件
+- **InputGroup.TextArea** – 多行 textarea 元素组件
+- **InputGroup.Prefix** – 前缀容器组件
+- **InputGroup.Suffix** – 后缀容器组件
+
+#### InputGroup.Input Props
+
+InputGroup.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `type` | `string` | `'text'` | 输入类型（text、password、email 等）。 |
+| `value` | `string` | - | 当前值（受控）。 |
+| `defaultValue` | `string` | - | 默认值（非受控）。 |
+| `placeholder` | `string` | - | 占位符文本。 |
+| `disabled` | `boolean` | - | 是否禁用输入。 |
+| `readOnly` | `boolean` | - | 是否只读。 |
+
+#### InputGroup.TextArea Props
+
+InputGroup.TextArea 继承 React Aria [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) 组件的全部 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | textarea 的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `value` | `string` | - | 当前值（受控）。 |
+| `defaultValue` | `string` | - | 默认值（非受控）。 |
+| `placeholder` | `string` | - | 占位符文本。 |
+| `rows` | `number` | - | 可见文本行数。 |
+| `disabled` | `boolean` | - | 是否禁用 textarea。 |
+| `readOnly` | `boolean` | - | 是否只读。 |
+
+#### InputGroup.Prefix Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 前缀中要展示的内容（图标、文字等）。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+
+#### InputGroup.Suffix Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 后缀中要展示的内容（图标、按钮、徽章等）。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+
+### Usage Example
+
+```tsx
+import {InputGroup, TextField, Label, Button} from '@heroui/react';
+import {Icon} from '@iconify/react';
+
+function Example() {
+  return (
+    <TextField>
+      <Label>Email</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon icon="gravity-ui:envelope" />
+        </InputGroup.Prefix>
+        <InputGroup.Input placeholder="name@email.com" />
+        <InputGroup.Suffix>
+          <Button isIconOnly size="sm" variant="ghost">
+            <Icon icon="gravity-ui:check" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
+```
+
+### TextArea Usage Example
+
+```tsx
+import {Envelope} from "@gravity-ui/icons";
+import {Description, FieldError, InputGroup, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+function TextAreaExample() {
+  const [feedback, setFeedback] = useState("");
+
+  return (
+    <TextField fullWidth isInvalid={feedback.length > 500} name="feedback" onChange={setFeedback}>
+      <Label>Your Feedback</Label>
+      <InputGroup fullWidth>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.TextArea
+          className="resize-none"
+          placeholder="Share your thoughts, suggestions, or issues..."
+          rows={5}
+          value={feedback}
+        />
+      </InputGroup>
+      <Description className="flex w-full items-center justify-between px-1">
+        <span>Maximum 500 characters.</span>
+        <span className="ml-auto">{feedback.length}/500</span>
+      </Description>
+      <FieldError>Feedback must be less than 500 characters</FieldError>
+    </TextField>
+  );
+}
+```
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/input-otp.mdx b/apps/docs/content/docs/cn/react/components/(forms)/input-otp.mdx
new file mode 100644
index 0000000..272c002
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/input-otp.mdx
@@ -0,0 +1,289 @@
+---
+title: InputOTP 一次性密码输入框
+description: 用于验证码与安全认证等场景的一次性密码输入组件。
+links:
+  source: input-otp/input-otp.tsx
+  styles: input-otp.css
+  storybook: Components/Forms/InputOTP
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { InputOTP } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="input-otp-basic" />
+
+### 组件结构
+
+引入 InputOTP 后，可通过点语法访问各个部分。
+
+```tsx
+import { InputOTP } from '@heroui/react';
+
+export default () => (
+  <InputOTP maxLength={6}>
+    <InputOTP.Group>
+      <InputOTP.Slot index={0} />
+      <InputOTP.Slot index={1} />
+      {/* ...rest of the slots */}
+    </InputOTP.Group>
+    <InputOTP.Separator />
+    <InputOTP.Group>
+      <InputOTP.Slot index={3} />
+      {/* ...rest of the slots */}
+    </InputOTP.Group>
+  </InputOTP>
+)
+```
+
+> **InputOTP** 基于 [@guilherme_rodz](https://twitter.com/guilherme_rodz) 的 [input-otp](https://github.com/guilhermerodz/input-otp) 构建，为 OTP 输入组件提供灵活且无障碍的基础能力。
+
+### 四位数字
+
+<ComponentPreview name="input-otp-four-digits" />
+
+### 禁用状态
+
+<ComponentPreview name="input-otp-disabled" />
+
+### 使用 pattern
+
+使用 `pattern` prop 限制可输入字符。HeroUI 会导出常用模式，例如 `REGEXP_ONLY_CHARS` 与 `REGEXP_ONLY_DIGITS`。
+
+<ComponentPreview name="input-otp-with-pattern" />
+
+### 受控
+
+控制值以同步状态、清空输入或实现自定义校验。
+
+<ComponentPreview name="input-otp-controlled" />
+
+### 带校验
+
+将 `isInvalid` 与校验消息一起使用以展示错误。
+
+<ComponentPreview name="input-otp-with-validation" />
+
+### 完成回调
+
+在所有槽位填满时使用 `onComplete` 回调触发逻辑。
+
+<ComponentPreview name="input-otp-on-complete" />
+
+### 表单示例
+
+包含校验与提交的完整双因素认证表单。
+
+<ComponentPreview name="input-otp-form-example" />
+
+### 变体
+
+InputOTP 支持两种视觉变体：
+
+- **`primary`**（默认）— 常规带阴影样式，适用于大多数场景
+- **`secondary`** — 弱强调、无阴影变体，适合用于 Surface 组件内部
+
+<ComponentPreview name="input-otp-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 组件内部使用时，请使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
+
+<ComponentPreview name="input-otp-on-surface" />
+
+<RelatedComponents component="inputotp" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {InputOTP, Label} from '@heroui/react';
+
+function CustomInputOTP() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label className="text-sm font-semibold">Enter verification code</Label>
+      <InputOTP
+        className="gap-3"
+        containerClassName="gap-4"
+        maxLength={6}
+      >
+        <InputOTP.Group className="gap-3">
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={0}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={1}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={2}
+          />
+        </InputOTP.Group>
+        <InputOTP.Separator className="bg-border h-1 w-2 rounded-full" />
+        <InputOTP.Group className="gap-3">
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={3}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={4}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={5}
+          />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 InputOTP 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .input-otp {
+    @apply gap-3;
+  }
+
+  .input-otp__slot {
+    @apply size-12 rounded-xl border-2 font-bold;
+  }
+
+  .input-otp__slot[data-active="true"] {
+    @apply border-primary-500 ring-2 ring-primary-200;
+  }
+
+  .input-otp__separator {
+    @apply w-2 h-1 bg-border-strong rounded-full;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+InputOTP 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)）：
+
+#### 基础类
+- `.input-otp` - 根容器
+- `.input-otp__container` - input-otp 库提供的内层容器
+- `.input-otp__group` - 槽位分组
+- `.input-otp__slot` - 单个输入槽位
+- `.input-otp__slot-value` - 槽位内的字符
+- `.input-otp__caret` - 闪烁的光标指示器
+- `.input-otp__separator` - 分组之间的视觉分隔符
+
+#### 状态类
+- `.input-otp__slot[data-active="true"]` - 当前激活的槽位
+- `.input-otp__slot[data-filled="true"]` - 已填入字符的槽位
+- `.input-otp__slot[data-disabled="true"]` - 禁用的槽位
+- `.input-otp__slot[data-invalid="true"]` - 无效的槽位
+- `.input-otp__container[data-disabled="true"]` - 禁用的容器
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，以获得更好的灵活性：
+
+- **悬停**：槽位上的 `:hover` 或 `[data-hovered="true"]`
+- **激活**：槽位上的 `[data-active="true"]`（当前聚焦）
+- **已填**：槽位上的 `[data-filled="true"]`（包含字符）
+- **禁用**：容器与槽位上的 `[data-disabled="true"]`
+- **无效**：槽位上的 `[data-invalid="true"]`
+
+## API 参考
+
+### InputOTP Props
+
+InputOTP 在 [input-otp](https://github.com/guilhermerodz/input-otp) 库之上构建，并增加了额外能力。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `maxLength` | `number` | - | **必填。** 输入槽位数量。 |
+| `value` | `string` | - | 受控值（未提供则为非受控）。 |
+| `onChange` | `(value: string) => void` | - | 值变化时调用。 |
+| `onComplete` | `(value: string) => void` | - | 所有槽位填满时调用。 |
+| `className` | `string` | - | 容器的额外 CSS 类名。 |
+| `containerClassName` | `string` | - | 内层容器的 CSS 类名。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |
+| `children` | `React.ReactNode` | - | InputOTP.Group、InputOTP.Slot 与 InputOTP.Separator 组件。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | `false` | 是否禁用输入。 |
+| `isInvalid` | `boolean` | `false` | 输入是否处于无效状态。 |
+| `validationErrors` | `string[]` | - | 服务端或自定义校验错误。 |
+| `validationDetails` | `ValidityState` | - | HTML5 校验详情。 |
+
+#### Input Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `pattern` | `string` | - | 允许字符的正则表达式（例如 `REGEXP_ONLY_DIGITS`）。 |
+| `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | 槽位内文本对齐方式。 |
+| `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | 移动设备上的虚拟键盘类型。 |
+| `placeholder` | `string` | - | 空槽位的占位符文本。 |
+| `pasteTransformer` | `(text: string) => string` | - | 转换粘贴文本（例如移除连字符）。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | 表单提交时使用的 name 属性。 |
+| `autoFocus` | `boolean` | - | 挂载时是否聚焦第一个槽位。 |
+
+### InputOTP.Group Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 分组的额外 CSS 类名。 |
+| `children` | `React.ReactNode` | - | InputOTP.Slot 组件。 |
+
+### InputOTP.Slot Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `index` | `number` | - | **必填。** 槽位从 0 开始的索引。 |
+| `className` | `string` | - | 槽位的额外 CSS 类名。 |
+
+### InputOTP.Separator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 分隔符的额外 CSS 类名。 |
+
+### 导出的 pattern
+
+HeroUI 会为了方便而从 input-otp 再导出常用正则 pattern：
+
+```tsx
+import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from '@heroui/react';
+
+// Use with pattern prop
+<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>
+  {/* ... */}
+</InputOTP>
+```
+
+- **REGEXP_ONLY_DIGITS** — 仅数字字符（0-9）
+- **REGEXP_ONLY_CHARS** — 仅字母字符（a-z、A-Z）
+- **REGEXP_ONLY_DIGITS_AND_CHARS** — 字母数字字符（0-9、a-z、A-Z）
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/input.mdx b/apps/docs/content/docs/cn/react/components/(forms)/input.mdx
new file mode 100644
index 0000000..a0412f6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/input.mdx
@@ -0,0 +1,141 @@
+---
+title: Input 输入框
+description: 单行文本输入原语，可接受标准 HTML 属性。
+links:
+  rac: Input
+  source: input/input.tsx
+  styles: input.css
+  storybook: Components/Forms/Input
+---
+
+## 引入
+
+```tsx
+import { Input } from '@heroui/react';
+```
+
+<Callout>
+  关于校验、标签与错误信息，请参见 **[TextField](/docs/components/text-field)**。
+</Callout>
+
+### 用法
+
+<ComponentPreview name="input-basic" />
+
+### Input 类型
+
+<ComponentPreview name="input-types" />
+
+### 受控
+
+<ComponentPreview name="input-controlled" />
+
+### 全宽
+
+<ComponentPreview name="input-full-width" />
+
+### 变体
+
+Input 支持两种视觉变体：
+
+- **`primary`**（默认）— 常规样式并带阴影，适用于大多数场景
+- **`secondary`** — 弱强调变体，无阴影，适合用于 Surface 组件内
+
+<ComponentPreview name="input-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 组件内使用时，请使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
+
+<ComponentPreview name="input-on-surface" />
+
+<RelatedComponents component="input" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Input, Label} from '@heroui/react';
+
+function CustomInput() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label htmlFor="custom-input">Project name</Label>
+      <Input
+        id="custom-input"
+        className="rounded-xl border border-border/70 bgsurface px-4 py-2 text-sm shadow-sm focus-visible:border-primary"
+        placeholder="New web app"
+      />
+    </div>
+  );
+}
+```
+
+### 自定义组件类
+
+基础类 `.input` 驱动每个实例。使用 `@layer components` 一次性覆盖即可。
+
+```css
+@layer components {
+  .input {
+    @apply rounded-lg border border-border bgsurface px-4 py-2 text-sm shadow-sm transition-colors;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-surface-secondary border-border/80;
+    }
+
+    &:focus-visible,
+    &[data-focus-visible="true"] {
+      @apply border-primary ring-2 ring-primary/20;
+    }
+
+    &[data-invalid="true"] {
+      @apply border-danger bg-danger-50/10 text-danger;
+    }
+  }
+}
+```
+
+### CSS 类
+
+- `.input` — 原生 input 元素样式
+
+### 交互状态
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **无效**：`[data-invalid="true"]`（并与 `aria-invalid` 同步）
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
+- **只读**：`[aria-readonly="true"]`
+
+## API 参考
+
+### Input Props
+
+除标准 HTML `<input>` 属性外，还支持以下 props：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与组件样式合并的 Tailwind 类。 |
+| `type` | `string` | `"text"` | Input 类型（text、email、password、number 等）。 |
+| `value` | `string` | - | 受控值。 |
+| `defaultValue` | `string` | - | 非受控初始值。 |
+| `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | 变更事件处理函数。 |
+| `placeholder` | `string` | - | 占位符文本。 |
+| `disabled` | `boolean` | `false` | 禁用输入框。 |
+| `readOnly` | `boolean` | `false` | 将输入框设为只读。 |
+| `required` | `boolean` | `false` | 将输入框标记为必填。 |
+| `name` | `string` | - | 用于表单提交的 name。 |
+| `autoComplete` | `string` | - | 浏览器自动完成提示。 |
+| `maxLength` | `number` | - | 最大字符数。 |
+| `minLength` | `number` | - | 最小字符数。 |
+| `pattern` | `string` | - | 用于校验的正则表达式。 |
+| `min` | `number \| string` | - | 最小值（用于 number/date 输入）。 |
+| `max` | `number \| string` | - | 最大值（用于 number/date 输入）。 |
+| `step` | `number \| string` | - | 步进间隔（用于 number 输入）。 |
+| `fullWidth` | `boolean` | `false` | 输入框是否占满容器宽度。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为无阴影的弱强调变体，适合用于 surface 内。 |
+
+> 如需 `isInvalid`、`isRequired` 等校验相关 props 与错误处理，请使用 **[TextField](/docs/components/text-field)**，并将 Input 作为其子组件。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/label.mdx b/apps/docs/content/docs/cn/react/components/(forms)/label.mdx
new file mode 100644
index 0000000..06ba9de
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/label.mdx
@@ -0,0 +1,96 @@
+---
+title: Label 标签
+description: 渲染与表单控件关联的无障碍标签。
+links:
+  rac: TextField
+  source: label/label.tsx
+  styles: label.css
+---
+
+## 引入
+
+```tsx
+import { Label } from '@heroui/react';
+```
+
+## 用法
+
+<ComponentPreview
+  name="label-basic"
+/>
+
+<RelatedComponents component="label" />
+
+## API 参考
+
+### Label Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `htmlFor` | `string` | - | 标签所关联元素的 id |
+| `isRequired` | `boolean` | `false` | 是否显示必填指示符 |
+| `isDisabled` | `boolean` | `false` | 标签是否处于禁用状态 |
+| `isInvalid` | `boolean` | `false` | 标签是否处于无效状态 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | 标签内容 |
+
+## 无障碍
+
+Label 基于原生 HTML `<label>`（[MDN 参考](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)），并遵循 WAI-ARIA 最佳实践：
+
+- 使用 `htmlFor` 与表单控件关联
+- 提供语义化的 `<label>` 元素
+- 与表单控件关联时支持键盘导航
+- 向屏幕阅读器传达必填与无效状态
+- 点击标签可聚焦/激活关联的表单控件
+
+<RelatedComponents component="label" />
+
+## 样式
+
+### CSS 类
+
+Label 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)）：
+
+#### 基础类
+- `.label` — 基础标签文本样式
+
+#### 状态修饰类
+- `.label--required` 或 `[data-required="true"] > .label` — 显示必填星号
+- `.label--disabled` 或 `[data-disabled="true"] .label` — 禁用状态样式
+- `.label--invalid` 或 `[data-invalid="true"] .label` 或 `[aria-invalid="true"] .label` — 无效状态样式（危险/红色文本）
+ 
+**说明：** 必填星号会基于 role 与 `data-slot` 智能应用，并排除：
+- `role="group"`、`role="radiogroup"`、`role="checkboxgroup"` 的元素
+- `data-slot="radio"` 或 `data-slot="checkbox"` 的元素
+
+从而在分组组件与必填字段组合时避免重复星号。
+
+## 示例
+
+### 带必填指示符
+
+```tsx
+<Label htmlFor="email" isRequired>
+  Email Address
+</Label>
+<Input id="email" type="email" />
+```
+
+### 禁用状态
+
+```tsx
+<Label htmlFor="username" isDisabled>
+  Username
+</Label>
+<Input id="username" isDisabled />
+```
+
+### 无效状态
+
+```tsx
+<Label htmlFor="password" isInvalid>
+  Password
+</Label>
+<Input id="password" isInvalid />
+```
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/number-field.mdx b/apps/docs/content/docs/cn/react/components/(forms)/number-field.mdx
new file mode 100644
index 0000000..5fbec9a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/number-field.mdx
@@ -0,0 +1,363 @@
+---
+title: NumberField 数字输入框
+description: 数字输入字段，包含增减按钮、校验与国际化格式化能力。
+links:
+  rac: NumberField
+  source: number-field/number-field.tsx
+  styles: number-field.css
+  storybook: Components/Forms/NumberField
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { NumberField } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="number-field-basic" />
+
+### 组件结构
+
+```tsx
+import {NumberField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <NumberField>
+    <Label />
+    <NumberField.Group>
+      <NumberField.DecrementButton />
+      <NumberField.Input />
+      <NumberField.IncrementButton />
+    </NumberField.Group>
+    <Description />
+    <FieldError />
+  </NumberField>
+)
+```
+
+> **NumberField** 允许用户输入数值，并可选择是否显示增减按钮。它支持国际化格式化、校验与键盘导航。
+
+### 带说明
+
+<ComponentPreview name="number-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="number-field-required" />
+
+### 校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
+
+<ComponentPreview name="number-field-validation" />
+
+### 受控
+
+控制值以与其他组件同步，或执行自定义格式化。
+
+<ComponentPreview name="number-field-controlled" />
+
+### 带校验
+
+在受控数值的基础上实现自定义校验逻辑。
+
+<ComponentPreview name="number-field-with-validation" />
+
+### 步进值
+
+配置增减步进值，以实现更精确的控制。
+
+<ComponentPreview name="number-field-with-step" />
+
+### 格式化选项
+
+将数字格式化为货币、百分比、小数或单位，并支持国际化。
+
+<ComponentPreview name="number-field-with-format-options" />
+
+### 自定义图标
+
+自定义增减按钮的图标。
+
+<ComponentPreview name="number-field-custom-icons" />
+
+### 搭配 Chevron
+
+在纵向布局中使用 chevron 图标，以获得不同的视觉风格。
+
+<ComponentPreview name="number-field-with-chevrons" />
+
+### 禁用状态
+
+<ComponentPreview name="number-field-disabled" />
+
+### 全宽
+
+<ComponentPreview name="number-field-full-width" />
+
+### 变体
+
+NumberField 支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+
+<ComponentPreview name="number-field-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="number-field-on-surface" />
+
+### 表单示例
+
+包含校验与提交处理的完整表单集成示例。
+
+<ComponentPreview name="number-field-form-example" />
+
+<RelatedComponents component="numberfield" />
+
+<RelatedShowcases component="NumberField" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="number-field-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {NumberField, Label} from '@heroui/react';
+
+function CustomNumberField() {
+  return (
+    <NumberField className="gap-2">
+      <Label className="text-sm font-semibold">Quantity</Label>
+      <NumberField.Group className="rounded-xl border-2">
+        <NumberField.DecrementButton className="bg-gray-100" />
+        <NumberField.Input className="text-center font-bold" />
+        <NumberField.IncrementButton className="bg-gray-100" />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
+```
+
+### 自定义组件类
+
+NumberField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
+
+```css
+@layer components {
+  .number-field {
+    @apply flex flex-col gap-1;
+  }
+
+  /* When invalid, the description is hidden automatically */
+  .number-field[data-invalid="true"] [data-slot="description"],
+  .number-field[aria-invalid="true"] [data-slot="description"] {
+    @apply hidden;
+  }
+
+  .number-field__group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
+  }
+
+  .number-field__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;
+  }
+
+  .number-field__increment-button,
+  .number-field__decrement-button {
+    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;
+  }
+}
+```
+
+### CSS 类
+
+- `.number-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
+- `.number-field__group` – 输入与按钮的容器，包含边框与背景样式
+- `.number-field__input` – 数字输入字段
+- `.number-field__increment-button` – 用于增加数值的按钮
+- `.number-field__decrement-button` – 用于减少数值的按钮
+- `.number-field--primary` – 带阴影的主变体（默认）
+- `.number-field--secondary` – 无阴影的次变体，适合用在 surface 上
+
+> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。
+
+### 交互状态
+
+NumberField 会根据状态自动管理以下 data 属性：
+
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽
+- **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用
+- **Focus Within**：`[data-focus-within="true"]` – 当输入框或按钮聚焦时应用
+- **Focus Visible**：`[data-focus-visible="true"]` – 当焦点可见（键盘导航）时应用
+- **Hovered**：`[data-hovered="true"]` – 当悬停在按钮上时应用
+
+更多属性可通过渲染 prop 获得（见下方的 NumberFieldRenderProps）。
+
+## API 参考
+
+### NumberField Props
+
+NumberField 继承 React Aria [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) 组件的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Group、Input 等）或渲染函数。 |
+| `className` | `string \| (values: NumberFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 数字字段是否占满容器宽度 |
+| `id` | `string` | - | 元素的唯一标识符。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `number` | - | 当前值（受控）。 |
+| `defaultValue` | `number` | - | 默认值（非受控）。 |
+| `onChange` | `(value: number \| undefined) => void` | - | 值变化时触发的事件处理函数。 |
+
+#### Formatting Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `formatOptions` | `Intl.NumberFormatOptions` | - | 数字格式化选项（货币、百分比、小数、单位等）。 |
+| `locale` | `string` | - | 数字格式化的区域设置。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 |
+| `isInvalid` | `boolean` | - | 当前值是否无效。 |
+| `validate` | `(value: number) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 |
+| `validationErrors` | `string[]` | - | 服务端校验错误。 |
+
+#### Range Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `minValue` | `number` | - | 允许的最小值。 |
+| `maxValue` | `number` | - | 允许的最大值。 |
+| `step` | `number` | `1` | 增减操作的步进值。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 |
+| `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 |
+| `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 |
+| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
+
+### Composition Components
+
+NumberField 需要与以下独立组件组合使用，请分别导入并直接使用：
+
+- **NumberField.Group** – 输入与按钮的容器
+- **NumberField.Input** – 数字输入字段
+- **NumberField.IncrementButton** – 用于增加数值的按钮
+- **NumberField.DecrementButton** – 用于减少数值的按钮
+- **Label** – 字段标签组件（`@heroui/react`）
+- **Description** – 辅助说明文本组件（`@heroui/react`）
+- **FieldError** – 校验错误信息组件（`@heroui/react`）
+
+这些组件各自拥有 props API。请直接在 NumberField 内组合使用：
+
+```tsx
+<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>
+  <Label>Quantity</Label>
+  <NumberField.Group>
+    <NumberField.DecrementButton />
+    <NumberField.Input />
+    <NumberField.IncrementButton />
+  </NumberField.Group>
+  <Description>Enter a value between 0 and 100</Description>
+  <FieldError>Value must be between 0 and 100</FieldError>
+</NumberField>
+```
+
+#### NumberField.Group Props
+
+NumberField.Group 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、Buttons）或渲染函数。 |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类。 |
+
+#### NumberField.Input Props
+
+NumberField.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+
+#### NumberField.IncrementButton Props
+
+NumberField.IncrementButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | `<IconPlus />` | 按钮的图标或内容。默认为加号图标。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `slot` | `"increment"` | `"increment"` | 必须设置为 `"increment"`（会自动设置）。 |
+
+#### NumberField.DecrementButton Props
+
+NumberField.DecrementButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | `<IconMinus />` | 按钮的图标或内容。默认为减号图标。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `slot` | `"decrement"` | `"decrement"` | 必须设置为 `"decrement"`（会自动设置）。 |
+
+### NumberFieldRenderProps
+
+在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦（已弃用，请使用 `isFocusWithin`）。 |
+| `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 |
+| `value` | `number \| undefined` | 当前值。 |
+| `minValue` | `number \| undefined` | 允许的最小值。 |
+| `maxValue` | `number \| undefined` | 允许的最大值。 |
+| `step` | `number` | 增减步进值。 |
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/radio-group.mdx b/apps/docs/content/docs/cn/react/components/(forms)/radio-group.mdx
new file mode 100644
index 0000000..9bd460d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/radio-group.mdx
@@ -0,0 +1,282 @@
+---
+title: RadioGroup 单选框组
+description: 用于从列表中选择单个选项的单选组。
+icon: updated
+links:
+  rac: RadioField
+  source: radio-group/radio-group.tsx
+  styles: radio-group.css
+  storybook: Components/Forms/RadioGroup
+---
+
+## 引入
+
+```tsx
+import { RadioGroup, Radio } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+### 组件结构
+
+导入 RadioGroup 组件后，可通过点号访问各个子部分。
+
+```tsx
+import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <RadioGroup>
+    <Label />
+    <Description />
+    <Radio value="option1">
+      <Radio.Content> {/* 可点击区域：control + label */}
+        <Radio.Control>
+          <Radio.Indicator>
+            <span>✓</span> {/* Custom indicator (optional) */}
+          </Radio.Indicator>
+        </Radio.Control>
+        Label {/* 纯文本 —— 可点击的标签 */}
+      </Radio.Content>
+      <Description /> {/* 兄弟节点 — 位于按钮外部（通过 aria-describedby 关联） */}
+      <FieldError /> {/* 可选 — 单选项校验错误信息 */}
+    </Radio>
+    <FieldError /> {/* 可选 — 组级校验 */}
+  </RadioGroup>
+)
+```
+
+### 自定义指示器
+
+<ComponentPreview
+  name="radio-group-custom-indicator"
+/>
+
+### 水平排列
+
+<ComponentPreview
+  name="radio-group-horizontal"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="radio-group-controlled"
+/>
+
+### 非受控
+
+当你只需要响应更新时，可组合使用 `defaultValue` 与 `onChange`。
+
+<ComponentPreview
+  name="radio-group-uncontrolled"
+/>
+
+### 校验
+
+<ComponentPreview
+  name="radio-group-validation"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="radio-group-disabled"
+/>
+
+### 变体
+
+RadioGroup 支持两种视觉变体：
+
+- **`primary`**（默认）— 带默认背景的标准样式，适用于大多数场景
+- **`secondary`** — 低强调变体，适合用在 Surface 组件内
+
+<ComponentPreview name="radio-group-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview
+  name="radio-group-on-surface"
+/>
+
+### 配送与支付
+
+<ComponentPreview
+  isBgSolid
+  align="start"
+  name="radio-group-delivery-and-payment"
+/>
+
+<RelatedShowcases component="RadioGroup" />
+
+<RelatedComponents component="radiogroup" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="radio-group-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { RadioGroup, Radio } from '@heroui/react';
+
+export default () => (
+  <RadioGroup defaultValue="premium" name="plan">
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-blue-300 data-[selected=true]:border-blue-500 data-[selected=true]:bg-blue-500/10"
+      value="basic"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-blue-400 group-data-[selected=true]:border-blue-500 group-data-[selected=true]:bg-blue-500" />
+      Basic Plan
+    </Radio>
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-purple-300 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500/10"
+      value="premium"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-purple-400 group-data-[selected=true]:border-purple-500 group-data-[selected=true]:bg-purple-500" />
+      Premium Plan
+    </Radio>
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-emerald-300 data-[selected=true]:border-emerald-500 data-[selected=true]:bg-emerald-500/10"
+      value="business"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-emerald-400 group-data-[selected=true]:border-emerald-500 group-data-[selected=true]:bg-emerald-500" />
+      Business Plan
+    </Radio>
+  </RadioGroup>
+);
+```
+
+### 自定义组件类
+
+要自定义 RadioGroup 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .radio-group {
+    @apply gap-2;
+  }
+
+  .radio {
+    @apply gap-4 rounded-lg border border-border p-3 hover:bg-surface-hovered;
+  }
+
+  .radio__control {
+    @apply border-2 border-primary;
+  }
+
+  .radio__indicator {
+    @apply bg-primary;
+  }
+
+  .radio__content {
+    @apply gap-1;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)）：
+
+#### 基础类
+- `.radio-group` - 单选组基础容器
+- `.radio` - 单个单选项
+- `.radio__control` - 单选控件（圆形按钮）
+- `.radio__indicator` - 单选指示器（内部圆点）
+- `.radio__content` - 单选内容包裹层
+
+#### 修饰类
+- `.radio--disabled` - 禁用状态
+
+### 交互状态
+
+单选项同时支持 CSS 伪类与 data 属性，便于灵活定制：
+
+- **Selected**：`[aria-checked="true"]` 或 `[data-selected="true"]`（显示指示器）
+- **Hover**：`:hover` 或 `[data-hovered="true"]`（边框颜色变化）
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
+- **Pressed**：`:active` 或 `[data-pressed="true"]`（缩放变换）
+- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度并禁用指针事件）
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（错误边框颜色）
+
+## API 参考
+
+### RadioGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 当前值（受控） |
+| `defaultValue` | `string` | - | 默认值（非受控） |
+| `onChange` | `(value: string) => void` | - | 值变化时触发的事件处理函数 |
+| `isDisabled` | `boolean` | `false` | 是否禁用整个单选组 |
+| `isRequired` | `boolean` | `false` | 是否必填 |
+| `isReadOnly` | `boolean` | `false` | 是否只读 |
+| `isInvalid` | `boolean` | `false` | 是否处于无效状态 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `name` | `string` | - | 单选组的名称，用于提交 HTML 表单 |
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | 单选组的排列方向 |
+| `children` | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | - | 单选组内容或渲染 prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioGroupRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Radio Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 单选项的值 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该单选项 |
+| `name` | `string` | - | 单选项名称，用于提交 HTML 表单 |
+| `children` | `React.ReactNode \| (values: RadioFieldRenderProps) => React.ReactNode` | - | 单选内容或字段级渲染 prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Radio.Control Props
+
+继承 `React.HTMLAttributes<HTMLSpanElement>`。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 控件包裹层内要渲染的内容（通常为 Radio.Indicator） |
+
+### Radio.Indicator Props
+
+继承 `React.HTMLAttributes<HTMLSpanElement>`。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | 可选内容或接收当前单选按钮状态的渲染 prop。 |
+
+### Radio.Content Props
+
+单选项的可点击区域（包裹隐藏 input 的 `<label>`）。请将 `Radio.Control` 与 `Label` 放在其中。`className` 支持接收 `RadioButtonRenderProps` 的渲染函数。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | 可点击内容（通常为 Radio.Control 与 Label） |
+
+### RadioFieldRenderProps
+
+在根级 `Radio` 上使用渲染 prop 时，会提供以下字段级值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isSelected` | `boolean` | 单选项是否已选中 |
+| `isDisabled` | `boolean` | 是否禁用 |
+| `isReadOnly` | `boolean` | 是否只读 |
+| `isInvalid` | `boolean` | 是否无效 |
+| `isRequired` | `boolean` | 是否必填 |
+
+### RadioButtonRenderProps
+
+`Radio.Control` 和 `Radio.Indicator` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Radio.Control` 子节点或传给 `Radio.Indicator` 即可访问它们。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/search-field.mdx b/apps/docs/content/docs/cn/react/components/(forms)/search-field.mdx
new file mode 100644
index 0000000..3bd4e6d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/search-field.mdx
@@ -0,0 +1,348 @@
+---
+title: SearchField 搜索框
+description: 搜索输入字段，包含清除按钮与搜索图标。
+links:
+  rac: SearchField
+  source: search-field/search-field.tsx
+  styles: search-field.css
+  storybook: Components/Forms/SearchField
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { SearchField } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="search-field-basic" />
+
+### 组件结构
+
+```tsx
+import {SearchField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <SearchField>
+    <Label />
+    <SearchField.Group>
+      <SearchField.SearchIcon />
+      <SearchField.Input />
+      <SearchField.ClearButton />
+    </SearchField.Group>
+    <Description />
+    <FieldError />
+  </SearchField>
+)
+```
+
+> **SearchField** 允许用户输入并清空搜索关键词。它包含搜索图标，并提供可选的清除按钮以便快速重置。
+
+### 带说明
+
+<ComponentPreview name="search-field-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="search-field-required" />
+
+### 校验
+
+将 `isInvalid` 与 `FieldError` 配合使用，以展示校验信息。
+
+<ComponentPreview name="search-field-validation" />
+
+### 禁用状态
+
+<ComponentPreview name="search-field-disabled" />
+
+### 受控
+
+控制值以与其他组件同步，或执行自定义格式化。
+
+<ComponentPreview name="search-field-controlled" />
+
+### 带校验
+
+在受控数值的基础上实现自定义校验逻辑。
+
+<ComponentPreview name="search-field-with-validation" />
+
+### 自定义图标
+
+自定义搜索图标与清除按钮图标。
+
+<ComponentPreview name="search-field-custom-icons" />
+
+### 全宽
+
+<ComponentPreview name="search-field-full-width" />
+
+### 变体
+
+SearchField 支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影的变体，适合用在 Surface 组件内
+
+<ComponentPreview name="search-field-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="search-field-on-surface" />
+
+### 表单示例
+
+包含校验与提交处理的完整表单集成示例。
+
+<ComponentPreview name="search-field-form-example" />
+
+### 键盘快捷键
+
+添加快捷键以快速聚焦搜索字段。
+
+<ComponentPreview name="search-field-with-keyboard-shortcut" />
+
+<RelatedComponents component="searchfield" />
+
+<RelatedShowcases component="SearchField" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="search-field-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {SearchField, Label} from '@heroui/react';
+
+function CustomSearchField() {
+  return (
+    <SearchField className="gap-2">
+      <Label className="text-sm font-semibold">Search</Label>
+      <SearchField.Group className="rounded-xl border-2">
+        <SearchField.SearchIcon className="text-blue-500" />
+        <SearchField.Input className="text-center font-bold" />
+        <SearchField.ClearButton className="text-red-500" />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
+```
+
+### 自定义组件类
+
+SearchField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。
+
+```css
+@layer components {
+  .search-field {
+    @apply flex flex-col gap-1;
+  }
+
+  /* When invalid, the description is hidden automatically */
+  .search-field[data-invalid],
+  .search-field[aria-invalid] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  .search-field__group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
+  }
+
+  .search-field__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .search-field__search-icon {
+    @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4;
+  }
+
+  .search-field__clear-button {
+    @apply mr-1 shrink-0;
+  }
+}
+```
+
+### CSS 类
+
+- `.search-field` – 根容器，样式非常克制（`flex flex-col gap-1`）
+- `.search-field__group` – 搜索图标、输入框与清除按钮的容器，包含边框与背景样式
+- `.search-field__input` – 搜索输入字段
+- `.search-field__search-icon` – 左侧显示的搜索图标
+- `.search-field__clear-button` – 用于清空搜索字段的按钮
+- `.search-field--primary` – 带阴影的主变体（默认）
+- `.search-field--secondary` – 无阴影的次变体，适合用在 surface 上
+
+> **说明：** 子组件（[Label](/docs/components/label)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。
+
+### 交互状态
+
+SearchField 会根据状态自动管理以下 data 属性：
+
+- **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽
+- **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用
+- **Focus Within**：`[data-focus-within="true"]` – 当输入框聚焦时应用
+- **Focus Visible**：`[data-focus-visible="true"]` – 当焦点可见（键盘导航）时应用
+- **Hovered**：`[data-hovered="true"]` – 当悬停在整个组合上时应用
+- **Empty**：`[data-empty="true"]` – 当字段为空时应用（会隐藏清除按钮）
+
+更多属性可通过渲染 prop 获得（见下方的 SearchFieldRenderProps）。
+
+## API 参考
+
+### SearchField Props
+
+SearchField 继承 React Aria [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) 组件的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Group、Input 等）或渲染函数。 |
+| `className` | `string \| (values: SearchFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | 搜索字段是否占满容器宽度 |
+| `id` | `string` | - | 元素的唯一标识符。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 当前值（受控）。 |
+| `defaultValue` | `string` | - | 默认值（非受控）。 |
+| `onChange` | `(value: string) => void` | - | 值变化时触发的事件处理函数。 |
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 |
+| `isInvalid` | `boolean` | - | 当前值是否无效。 |
+| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 |
+| `validationErrors` | `string[]` | - | 服务端校验错误。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 |
+| `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 |
+
+#### Event Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `onSubmit` | `(value: string) => void` | - | 用户提交搜索（Enter）时触发的事件处理函数。 |
+| `onClear` | `() => void` | - | 按下清除按钮时触发的事件处理函数。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 |
+| `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 |
+| `aria-details` | `string` | - | 包含更多详情的元素 ID。 |
+
+### Composition Components
+
+SearchField 需要与以下独立组件组合使用，请分别导入并直接使用：
+
+- **SearchField.Group** – 搜索图标、输入框与清除按钮的容器
+- **SearchField.Input** – 搜索输入字段
+- **SearchField.SearchIcon** – 左侧显示的搜索图标
+- **SearchField.ClearButton** – 用于清空搜索字段的按钮
+- **Label** – 字段标签组件（`@heroui/react`）
+- **Description** – 辅助说明文本组件（`@heroui/react`）
+- **FieldError** – 校验错误信息组件（`@heroui/react`）
+
+这些组件各自拥有 props API。请直接在 SearchField 内组合使用：
+
+```tsx
+<SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}>
+  <Label>Search</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input placeholder="Search..." />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description>Enter keywords to search</Description>
+  <FieldError>Search query is required</FieldError>
+</SearchField>
+```
+
+#### SearchField.Group Props
+
+SearchField.Group 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（SearchIcon、Input、ClearButton）或渲染函数。 |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类。 |
+
+#### SearchField.Input Props
+
+SearchField.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 |
+| `placeholder` | `string` | - | 输入为空时显示的占位符文本。 |
+| `type` | `string` | `"search"` | 输入类型（会自动设置为 `"search"`）。 |
+
+#### SearchField.SearchIcon Props
+
+SearchField.SearchIcon 是一个用于渲染搜索图标的自定义组件。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | `<IconSearch />` | 自定义图标元素。默认为搜索图标。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+
+#### SearchField.ClearButton Props
+
+SearchField.ClearButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | `<CloseButton icon />` | 按钮的图标或内容。默认为关闭图标。 |
+| `className` | `string` | - | 用于样式的 CSS 类。 |
+| `slot` | `"clear"` | `"clear"` | 必须设置为 `"clear"`（会自动设置）。 |
+
+### SearchFieldRenderProps
+
+在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦（已弃用，请使用 `isFocusWithin`）。 |
+| `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 |
+| `value` | `string` | 当前值。 |
+| `isEmpty` | `boolean` | 字段是否为空。 |
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/text-area.mdx b/apps/docs/content/docs/cn/react/components/(forms)/text-area.mdx
new file mode 100644
index 0000000..cc1fa46
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/text-area.mdx
@@ -0,0 +1,142 @@
+---
+title: TextArea 多行文本框
+description: 原语级多行文本输入组件，可接受标准 HTML 属性。
+links:
+  rac: TextArea
+  source: textarea/textarea.tsx
+  styles: textarea.css
+  storybook: Components/Forms/Textarea
+---
+
+## 引入
+
+```tsx
+import { TextArea } from '@heroui/react';
+```
+
+<Callout>
+  关于校验、标签与错误信息，请参阅 **[TextField](/docs/components/text-field)**。
+</Callout>
+
+### 用法
+
+<ComponentPreview name="textarea-basic" />
+
+### 受控
+
+<ComponentPreview name="textarea-controlled" />
+
+### 行数与尺寸调整
+
+<ComponentPreview name="textarea-rows" />
+
+### 全宽
+
+<ComponentPreview name="textarea-full-width" />
+
+### 变体
+
+TextArea 支持两种视觉变体：
+
+- **`primary`**（默认）— 常规带阴影样式，适用于大多数场景
+- **`secondary`** — 弱强调、无阴影变体，适合用于 Surface 组件内部
+
+<ComponentPreview name="textarea-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 组件内部使用时，请使用 `variant="secondary"`，以应用适合 surface 背景的弱强调变体。
+
+<ComponentPreview name="textarea-on-surface" />
+
+<RelatedComponents component="textarea" />
+
+<RelatedShowcases component="TextArea" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Label, TextArea} from '@heroui/react';
+
+function CustomTextArea() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label htmlFor="custom-textarea">Message</Label>
+      <TextArea
+        id="custom-textarea"
+        className="rounded-xl border border-border/70 bgsurface px-4 py-3 text-sm leading-6 shadow-sm"
+        placeholder="Let us know how we can help..."
+        rows={5}
+        style={{resize: "vertical"}}
+      />
+    </div>
+  );
+}
+```
+
+### 自定义组件类
+
+使用 Tailwind 的 `@layer components` 一次性覆盖共享的 `.textarea` 类。
+
+```css
+@layer components {
+  .textarea {
+    @apply rounded-xl border border-border bgsurface px-4 py-3 text-sm leading-6 shadow-sm;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-surface-secondary border-border/80;
+    }
+
+    &:focus-visible,
+    &[data-focus-visible="true"] {
+      @apply border-primary ring-2 ring-primary/20;
+    }
+
+    &[data-invalid="true"] {
+      @apply border-danger bg-danger-50/10 text-danger;
+    }
+  }
+}
+```
+
+### CSS 类
+
+- `.textarea` – 底层 `<textarea>` 元素样式
+
+### 交互状态
+
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **无效**：`[data-invalid="true"]`
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
+
+## API 参考
+
+### TextArea Props
+
+TextArea 接受所有标准 HTML `<textarea>` 属性，以及以下属性：
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 与基础样式合并的 Tailwind 类。 |
+| `rows` | `number` | `3` | 可见文本行数。 |
+| `cols` | `number` | - | 文本控件的可见宽度。 |
+| `value` | `string` | - | TextArea 的受控值。 |
+| `defaultValue` | `string` | - | 非受控初始值。 |
+| `onChange` | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | 变更处理函数。 |
+| `placeholder` | `string` | - | 占位符文本。 |
+| `disabled` | `boolean` | `false` | 禁用 TextArea。 |
+| `readOnly` | `boolean` | `false` | 将 TextArea 设为只读。 |
+| `required` | `boolean` | `false` | 将 TextArea 标记为必填。 |
+| `name` | `string` | - | 表单提交时使用的 name。 |
+| `autoComplete` | `string` | - | 浏览器自动完成提示。 |
+| `maxLength` | `number` | - | 最大字符数。 |
+| `minLength` | `number` | - | 最小字符数。 |
+| `wrap` | `'soft' \| 'hard'` | - | 提交时文本如何换行。 |
+| `fullWidth` | `boolean` | `false` | TextArea 是否占满容器宽度 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 |
+
+> 对于 `isInvalid`、`isRequired` 等校验 prop 以及错误处理，请将 TextArea 作为子组件与 **[TextField](/docs/components/text-field)** 一起使用。
diff --git a/apps/docs/content/docs/cn/react/components/(forms)/text-field.mdx b/apps/docs/content/docs/cn/react/components/(forms)/text-field.mdx
new file mode 100644
index 0000000..96f58a7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(forms)/text-field.mdx
@@ -0,0 +1,250 @@
+---
+title: TextField 文本输入框
+description: 便于组合的文本字段，包含标签、说明与内联校验。
+links:
+  rac: TextField
+  source: textfield/textfield.tsx
+  styles: textfield.css
+  storybook: Components/Forms/TextField
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { TextField } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="textfield-basic" />
+
+### 组件结构
+
+```tsx
+import {TextField, Label, Input, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <TextField>
+    <Label />
+    <Input />
+    <Description />
+    <FieldError />
+  </TextField>
+)
+```
+
+> **TextField** 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 **[Input](/docs/components/input)** 或 **[TextArea](/docs/components/textarea)**。
+
+### 带说明
+
+<ComponentPreview name="textfield-with-description" />
+
+### 必填字段
+
+<ComponentPreview name="textfield-required" />
+
+### 校验
+
+使用 `isInvalid` 与 `FieldError` 展示校验信息。
+
+<ComponentPreview name="textfield-validation" />
+
+### 受控
+
+通过受控 `value` 同步计数器、预览或格式化。
+
+<ComponentPreview name="textfield-controlled" />
+
+### 错误信息
+
+<ComponentPreview name="textfield-with-error" />
+
+### 禁用状态
+
+<ComponentPreview name="textfield-disabled" />
+
+### TextArea
+
+多行内容请使用 [TextArea](/docs/components/textarea) 替代 [Input](/docs/components/input)。
+
+<ComponentPreview name="textfield-textarea" />
+
+### Input 类型
+
+<ComponentPreview name="textfield-input-types" />
+
+### 全宽
+
+<ComponentPreview name="textfield-full-width" />
+
+### 在 Surface 内
+
+置于 [Surface](/docs/components/surface) 中时，请在 Input 或 TextArea 上使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
+
+<ComponentPreview name="textfield-on-surface" />
+
+<RelatedComponents component="textfield" />
+
+<RelatedShowcases component="TextField" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="textfield-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {TextField, Label, Input, Description} from '@heroui/react';
+
+function CustomTextField() {
+  return (
+    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Project name
+      </Label>
+      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
+      <Description className="text-xs text-default-500">
+        Keep it short and memorable.
+      </Description>
+    </TextField>
+  );
+}
+```
+
+### 自定义组件类
+
+TextField 默认样式很少。覆盖 `.textfield` 类即可自定义容器样式。
+
+```css
+@layer components {
+  .textfield {
+    @apply flex flex-col gap-1;
+  }
+
+  /* 无效时自动隐藏说明 */
+  .textfield[data-invalid="true"] [data-slot="description"],
+  .textfield[aria-invalid="true"] [data-slot="description"] {
+    @apply hidden;
+  }
+
+  /* Description 默认内边距 */
+  .textfield [data-slot="description"] {
+    @apply px-1;
+  }
+}
+```
+
+### CSS 类
+
+- `.textfield` – 根容器，样式极少（`flex flex-col gap-1`）
+
+> **提示：** 子组件（[Label](/docs/components/label)、[Input](/docs/components/input)、[TextArea](/docs/components/textarea)、[Description](/docs/components/description)、[FieldError](/docs/components/field-error)）各自拥有 CSS 类与样式，定制方式请参见对应文档。
+
+### 交互状态
+
+TextField 会根据状态自动管理以下 data 属性：
+
+- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` — 无效时自动隐藏 description 插槽
+- **禁用**：`[data-disabled="true"]` — 在 `isDisabled` 为 true 时应用
+- **焦点在内部**：`[data-focus-within="true"]` — 任一子级 input 聚焦时应用
+- **可见焦点**：`[data-focus-visible="true"]` — 键盘导航产生可见焦点时应用
+
+更多属性可通过 render prop 获取（见下文 TextFieldRenderProps）。
+
+## API 参考
+
+### TextField Props
+
+继承 React Aria [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) 的全部 props。
+
+#### Base Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Input 等）或渲染函数。 |
+| `className` | `string \| (values: TextFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
+| `style` | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 |
+| `fullWidth` | `boolean` | `false` | TextField 是否占满容器宽度。 |
+| `id` | `string` | - | 元素的唯一 id。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+#### Validation Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isRequired` | `boolean` | `false` | 提交表单前是否必须填写。 |
+| `isInvalid` | `boolean` | - | 当前值是否无效。 |
+| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 |
+| `validationErrors` | `string[]` | - | 服务端校验错误。 |
+
+#### Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `string` | - | 当前值（受控）。 |
+| `defaultValue` | `string` | - | 默认值（非受控）。 |
+| `onChange` | `(value: string) => void` | - | 值变化时调用的事件处理函数。 |
+
+#### State Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | - | 是否禁用输入。 |
+| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |
+
+#### Form Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | 用于 HTML 表单提交的 input 名称。 |
+| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 |
+
+#### Accessibility Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
+| `aria-labelledby` | `string` | - | 用于标注该字段的元素 id。 |
+| `aria-describedby` | `string` | - | 用于描述该字段的元素 id。 |
+| `aria-details` | `string` | - | 提供附加详情的元素 id。 |
+
+### Composition Components
+
+TextField 与以下独立组件配合使用，请直接按需引入并组合：
+
+- **Label** — `@heroui/react` 的字段标签组件
+- **Input** — `@heroui/react` 的单行文本输入
+- **TextArea** — `@heroui/react` 的多行文本输入
+- **Description** — `@heroui/react` 的辅助说明组件
+- **FieldError** — `@heroui/react` 的校验错误信息组件
+
+这些组件各自有独立的 props API，请在 TextField 内直接使用：
+
+```tsx
+<TextField isRequired isInvalid={hasError}>
+  <Label>Email Address</Label>
+  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+  <Description>We'll never share your email.</Description>
+  <FieldError>Please enter a valid email address.</FieldError>
+</TextField>
+```
+
+### TextFieldRenderProps
+
+对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isDisabled` | `boolean` | 字段是否禁用。 |
+| `isInvalid` | `boolean` | 字段当前是否无效。 |
+| `isReadOnly` | `boolean` | 字段是否只读。 |
+| `isRequired` | `boolean` | 字段是否必填。 |
+| `isFocused` | `boolean` | 字段是否聚焦（已弃用 — 请使用 `isFocusWithin`）。 |
+| `isFocusWithin` | `boolean` | 是否有任一子元素聚焦。 |
+| `isFocusVisible` | `boolean` | 是否为可见键盘焦点。 |
diff --git a/apps/docs/content/docs/cn/react/components/(layout)/card.mdx b/apps/docs/content/docs/cn/react/components/(layout)/card.mdx
new file mode 100644
index 0000000..49e933a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(layout)/card.mdx
@@ -0,0 +1,193 @@
+---
+title: Card 卡片
+description: 用于分组相关内容与操作的灵活容器组件。
+links:
+  source: card/card.tsx
+  styles: card.css
+  storybook: Components/Layout/Card
+---
+
+## 引入
+
+```tsx
+import { Card } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview
+  name="card-default"
+/>
+
+### 组件结构
+
+导入 Card 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { Card } from "@heroui/react";
+
+export default () => (
+  <Card>
+    <Card.Header>
+      <Card.Title />
+      <Card.Description />
+    </Card.Header>
+    <Card.Content />
+    <Card.Footer />
+  </Card>
+);
+```
+
+### 变体
+
+卡片提供语义化变体，用于表达层级强弱而非固定视觉样式，主题可按需诠释：
+
+<ComponentPreview
+  name="card-variants"
+/>
+
+- **`transparent`** — 层次最低，透明背景（适合嵌套卡片）
+- **`default`** — 常规卡片，适用于大多数场景（surface-secondary）
+- **`secondary`** — 中等突出，吸引适度注意（surface-tertiary）
+- **`tertiary`** — 更高突出，用于重要内容（surface-tertiary）
+
+### 横向布局
+
+<ComponentPreview
+  name="card-horizontal"
+/>
+
+### 带头像
+
+<ComponentPreview
+  name="card-with-avatar"
+/>
+
+### 带图片
+
+<ComponentPreview
+  name="card-with-images"
+/>
+
+### 带表单
+
+<ComponentPreview
+  name="card-with-form"
+/>
+
+## 无障碍
+
+```tsx
+import { Card } from '@heroui/react';
+import { cardVariants } from '@heroui/styles';
+
+// 语义化标记
+<Card role="article" aria-labelledby="card-title">
+  <Card.Header>
+    <Card.Title id="card-title">Article Title</Card.Title>
+  </Card.Header>
+</Card>
+
+// 可交互卡片
+<a className={cardVariants().base()} href="/details" aria-label="View product details">
+  <Card.Title>Product Name</Card.Title>
+</a>
+```
+
+<RelatedComponents component="card" />
+
+## 样式
+
+### 组件定制
+
+```tsx
+<Card className="border-2 border-blue-500 bg-gradient-to-r from-blue-50 to-purple-50">
+  <Card.Header>
+    <Card.Title className="text-blue-900">Custom Styled Card</Card.Title>
+    <Card.Description className="text-blue-700">Custom colors applied</Card.Description>
+  </Card.Header>
+  <Card.Content>
+    <p className="text-blue-800">Content with custom styling</p>
+  </Card.Content>
+</Card>
+```
+
+### CSS 变量覆盖
+
+```css
+/* 覆盖特定变体 */
+.card--secondary {
+  @apply bg-gradient-to-br from-blue-50 to-purple-50;
+}
+
+/* 自定义元素样式 */
+.card__title {
+  @apply text-xl font-bold;
+}
+```
+
+## CSS 类
+
+Card 使用 [BEM](https://getbem.com/) 命名以便样式可预期（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)）：
+
+
+#### 基础类
+
+- `.card` — 基础容器，含内边距与边框
+- `.card__header` — 头部区域容器
+- `.card__title` — 标题的基础字号与字重
+- `.card__description` — 弱化说明文字
+- `.card__content` — 弹性主内容区
+- `.card__footer` — 底部行布局
+
+#### 变体类
+
+- `.card--transparent` — 层次最低，透明背景（对应 `transparent` 变体）
+- `.card--default` — 常规外观，surface-secondary（默认）
+- `.card--secondary` — 中等突出，surface-tertiary（对应 `secondary` 变体）
+- `.card--tertiary` — 更高突出，surface-tertiary（对应 `tertiary` 变体）
+
+## API 参考
+
+### Card
+
+| Prop        | 类型                                                      | 默认值      | 描述                                       |
+| ----------- | --------------------------------------------------------- | ----------- | ------------------------------------------ |
+| `variant`   | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | 表示层次强弱的语义变体                     |
+| `className` | `string`                                                  | -           | 附加的 CSS 类                              |
+| `children`  | `React.ReactNode`                                         | -           | 卡片内容                                   |
+
+### Card.Header
+
+| Prop        | 类型              | 默认值 | 描述                    |
+| ----------- | ----------------- | ------ | ----------------------- |
+| `className` | `string`          | -      | 附加的 CSS 类           |
+| `children`  | `React.ReactNode` | -      | 头部内容                |
+
+### Card.Title
+
+| Prop        | 类型              | 默认值 | 描述                                 |
+| ----------- | ----------------- | ------ | ------------------------------------ |
+| `className` | `string`          | -      | 附加的 CSS 类                        |
+| `children`  | `React.ReactNode` | -      | 标题内容（渲染为 `h3`）              |
+
+### Card.Description
+
+| Prop        | 类型              | 默认值 | 描述                                |
+| ----------- | ----------------- | ------ | ----------------------------------- |
+| `className` | `string`          | -      | 附加的 CSS 类                       |
+| `children`  | `React.ReactNode` | -      | 说明内容（渲染为 `p`）              |
+
+### Card.Content
+
+| Prop        | 类型              | 默认值 | 描述                    |
+| ----------- | ----------------- | ------ | ----------------------- |
+| `className` | `string`          | -      | 附加的 CSS 类           |
+| `children`  | `React.ReactNode` | -      | 主内容                  |
+
+### Card.Footer
+
+| Prop        | 类型              | 默认值 | 描述                    |
+| ----------- | ----------------- | ------ | ----------------------- |
+| `className` | `string`          | -      | 附加的 CSS 类           |
+| `children`  | `React.ReactNode` | -      | 底部内容                |
diff --git a/apps/docs/content/docs/cn/react/components/(layout)/separator.mdx b/apps/docs/content/docs/cn/react/components/(layout)/separator.mdx
new file mode 100644
index 0000000..db0b5c5
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(layout)/separator.mdx
@@ -0,0 +1,114 @@
+---
+title: Separator 分隔符
+description: 在内容区块之间进行视觉分隔。
+links:
+  rac: Separator
+  source: separator/separator.tsx
+  styles: separator.css
+  storybook: Components/Layout/Separator
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Separator } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="separator-basic"
+/>
+
+### 垂直方向
+
+<ComponentPreview
+  name="separator-vertical"
+/>
+
+### 带内容
+
+<ComponentPreview
+  name="separator-with-content"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="separator-variants"
+/>
+
+### 与 Surface 组合
+
+Separator 会适配不同的 surface 背景，以获得更好的可见性。
+
+<ComponentPreview
+  name="separator-with-surface"
+/>
+
+<RelatedComponents component="separator" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="separator-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Separator} from '@heroui/react';
+
+function CustomSeparator() {
+  return (
+    <Separator className="my-8 bg-linear-to-r from-transparent via-default-500 to-transparent" />
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Separator 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .separator {
+    @apply bg-accent h-[2px];
+  }
+
+  .separator--vertical {
+    @apply bg-accent w-[2px];
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Separator 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/separator.css)）：
+
+#### 基础类与方向类
+- `.separator` - 基础 Separator 样式，默认水平方向
+- `.separator--horizontal` - 水平方向（全宽，高度 1px）
+- `.separator--vertical` - 垂直方向（全高，宽度 1px）
+
+#### 变体类
+- `.separator--default` - 默认变体，标准对比度
+- `.separator--secondary` - 次要变体，中等对比度
+- `.separator--tertiary` - 第三级变体，较弱对比度
+
+## API 参考
+
+### Separator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Separator 的方向 |
+| `variant` | `'default' \| 'secondary' \| 'tertiary'` | `'default'` | Separator 的视觉变体 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
diff --git a/apps/docs/content/docs/cn/react/components/(layout)/surface.mdx b/apps/docs/content/docs/cn/react/components/(layout)/surface.mdx
new file mode 100644
index 0000000..9d46e8a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(layout)/surface.mdx
@@ -0,0 +1,128 @@
+---
+title: Surface 表面
+description: 提供表面级样式与子组件上下文的容器组件。
+links:
+  source: surface/surface.tsx
+  styles: surface.css
+  storybook: surface
+---
+
+## 引入
+
+```tsx
+import { Surface } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="surface-variants"
+/>
+
+## 概述
+
+Surface 组件是语义化容器，通过变体提供不同的视觉层次。
+
+### 变体
+
+Surface 提供描述视觉层次的语义化变体：
+
+- **`default`** — 标准表面外观（bg-surface）
+- **`secondary`** — 中等层次（bg-surface-secondary）
+- **`tertiary`** — 更高层次（bg-surface-tertiary）
+
+## 与表单组件配合
+
+在 Surface 内使用表单组件时，请为这些组件设置 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+```tsx
+import { Surface, Input, TextArea } from '@heroui/react';
+
+function App() {
+  return (
+    <Surface variant="default">
+      <Input placeholder="Input with secondary variant" variant="secondary" />
+      <TextArea placeholder="TextArea with secondary variant" variant="secondary" />
+    </Surface>
+  );
+}
+```
+
+<RelatedComponents component="surface" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Surface } from '@heroui/react';
+
+function CustomSurface() {
+  return (
+    <Surface
+      className="rounded-2xl p-8 shadow-lg"
+      variant="secondary"
+    >
+      <h2>Custom Styled Surface</h2>
+      <p>Content goes here</p>
+    </Surface>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Surface 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .surface {
+    @apply rounded-2xl border border-border;
+  }
+
+  .surface--secondary {
+    @apply bg-gradient-to-br from-blue-50 to-purple-50;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Surface 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)）：
+
+#### 基础类
+- `.surface` - Surface 根容器
+
+#### 变体类
+- `.surface--default` - 默认 Surface 变体（bg-surface）
+- `.surface--secondary` - Secondary Surface 变体（bg-surface-secondary）
+- `.surface--tertiary` - Tertiary Surface 变体（bg-surface-tertiary）
+
+## API 参考
+
+### Surface Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Surface 的视觉变体。 |
+| `className` | `string` | - | 额外的 CSS 类。 |
+| `children` | `ReactNode` | - | Surface 内容。 |
+
+## Context API
+
+### SurfaceContext
+
+子组件可通过 Surface 上下文读取当前变体：
+
+```tsx
+import { useContext } from 'react';
+import { SurfaceContext } from '@heroui/react';
+
+function MyComponent() {
+  const { variant } = useContext(SurfaceContext);
+  // variant 为 "transparent" | "default" | "secondary" | "tertiary" | undefined
+}
+```
diff --git a/apps/docs/content/docs/cn/react/components/(layout)/toolbar.mdx b/apps/docs/content/docs/cn/react/components/(layout)/toolbar.mdx
new file mode 100644
index 0000000..5c43849
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(layout)/toolbar.mdx
@@ -0,0 +1,107 @@
+---
+title: Toolbar 工具栏
+description: 用于承载可交互控件的容器，并支持方向键导航。
+links:
+  rac: Toolbar
+  source: toolbar/toolbar.tsx
+  styles: toolbar.css
+  storybook: Components/Layout/Toolbar
+---
+
+## 引入
+
+```tsx
+import { Toolbar } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="toolbar-basic"
+/>
+
+### 垂直方向
+
+<ComponentPreview
+  name="toolbar-vertical"
+/>
+
+### 与 ButtonGroup 组合
+
+<ComponentPreview
+  name="toolbar-with-button-group"
+/>
+
+### Attached
+
+<ComponentPreview
+  name="toolbar-attached"
+/>
+
+<RelatedComponents component="toolbar" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Toolbar } from '@heroui/react';
+
+function CustomToolbar() {
+  return (
+    <Toolbar
+      aria-label="Actions"
+      className="rounded-xl border border-default bg-surface p-2"
+    >
+      {/* toolbar content */}
+    </Toolbar>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Toolbar 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .toolbar {
+    @apply gap-4 rounded-lg bg-surface p-3;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Toolbar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toolbar.css)）：
+
+- `.toolbar` - 基础容器
+- `.toolbar--horizontal` - 水平方向（默认）
+- `.toolbar--vertical` - 垂直方向
+- `.toolbar--attached` - Attached 变体：surface 背景与完全圆角
+
+## API 参考
+
+### Toolbar Props
+
+继承 [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html)。
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isAttached` | `boolean` | `false` | Toolbar 是否使用带完全圆角的 surface 背景 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Toolbar 的方向 |
+| `aria-label` | `string` | - | Toolbar 的无障碍标签 |
+| `aria-labelledby` | `string` | - | 用于标注该 Toolbar 的元素 id |
+| `children` | `React.ReactNode \| (values: ToolbarRenderProps) => React.ReactNode` | - | 内容或渲染 prop |
+| `className` | `string \| (values: ToolbarRenderProps) => string` | - | 额外的 CSS 类名 |
+
+### ToolbarRenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `orientation` | `"horizontal" \| "vertical"` | 当前 Toolbar 的方向 |
diff --git a/apps/docs/content/docs/cn/react/components/(media)/avatar.mdx b/apps/docs/content/docs/cn/react/components/(media)/avatar.mdx
new file mode 100644
index 0000000..bc5a4a8
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(media)/avatar.mdx
@@ -0,0 +1,154 @@
+---
+title: Avatar 头像
+description: 展示用户头像图片，并提供可定制的回退内容。
+links:
+  radix: avatar
+  source: avatar/avatar.tsx
+  styles: avatar.css
+  storybook: Components/Media/Avatar
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Avatar } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview name="avatar-basic" />
+
+### 组件结构
+
+引入 Avatar 组件，并通过点语法访问各部分。
+
+```tsx
+import { Avatar } from '@heroui/react';
+
+export default () => (
+  <Avatar>
+    <Avatar.Image/>
+    <Avatar.Fallback/>
+  </Avatar>
+)
+```
+
+### 尺寸
+
+<ComponentPreview name="avatar-sizes" />
+
+### 颜色
+
+<ComponentPreview name="avatar-colors" />
+
+### 变体
+
+<ComponentPreview name="avatar-variants" />
+
+### 回退内容
+
+<ComponentPreview name="avatar-fallback" />
+
+### 头像组
+
+<ComponentPreview name="avatar-group" />
+
+### 自定义样式
+
+<ComponentPreview name="avatar-custom-styles" />
+
+<RelatedComponents component="avatar" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Avatar } from '@heroui/react';
+
+function CustomAvatar() {
+  return (
+    <Avatar className="size-20">
+      <Avatar.Image src="..." alt="..." />
+      <Avatar.Fallback>XL</Avatar.Fallback>
+    </Avatar>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Avatar 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .avatar {
+    @apply size-16 border-2 border-primary;
+  }
+
+  .avatar__fallback {
+    @apply bg-gradient-to-br from-purple-500 to-pink-500;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Avatar 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)）：
+
+#### 基础类
+- `.avatar` - 基础容器，默认尺寸（size-10）
+- `.avatar__image` - 图片元素，方形比例
+- `.avatar__fallback` - 回退容器，内容居中
+
+#### 尺寸修饰
+- `.avatar--sm` - 小尺寸（size-8）
+- `.avatar--md` - 中尺寸（默认，无额外样式）
+- `.avatar--lg` - 大尺寸（size-12）
+
+#### 变体修饰
+- `.avatar--soft` - Soft 变体，背景更浅
+
+#### 颜色修饰
+- `.avatar__fallback--default` - 默认文字颜色
+- `.avatar__fallback--accent` - 强调文字颜色
+- `.avatar__fallback--success` - 成功文字颜色
+- `.avatar__fallback--warning` - 警告文字颜色
+- `.avatar__fallback--danger` - 危险文字颜色
+
+## API 参考
+
+### Avatar Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar 尺寸 |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 回退区域的颜色主题 |
+| `variant` | `'default' \| 'soft'` | `'default'` | 视觉样式变体 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### Avatar.Image Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `src` | `string` | - | 图片地址 |
+| `srcSet` | `string` | - | 响应式图片的 `srcset` |
+| `sizes` | `string` | - | 响应式图片的 `sizes` |
+| `alt` | `string` | - | 图片替代文本 |
+| `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载成功时的事件处理函数 |
+| `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载失败时的事件处理函数 |
+| `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | 图片请求的 CORS 设置 |
+| `loading` | `'eager' \| 'lazy'` | - | 原生懒加载属性 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### Avatar.Fallback Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `delayMs` | `number` | - | 显示回退内容前的延迟（减轻闪烁） |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 覆盖父级的颜色 |
+| `className` | `string` | - | 额外的 CSS 类 |
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/accordion.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/accordion.mdx
new file mode 100644
index 0000000..840a7b5
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/accordion.mdx
@@ -0,0 +1,300 @@
+---
+title: Accordion 手风琴
+description: 用于在紧凑空间中组织信息的可折叠内容面板。
+links:
+  rac: Disclosure
+  source: accordion/accordion.tsx
+  styles: accordion.css
+  storybook: Components/Navigation/Accordion
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Accordion } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="accordion-basic"
+  minHeight="400px"
+/>
+
+
+### 组件结构
+
+引入 Accordion 组件并通过点语法访问所有子部分。
+
+```tsx
+import { Accordion } from '@heroui/react';
+
+export default () => (
+  <Accordion>
+    <Accordion.Item>
+      <Accordion.Heading>
+        <Accordion.Trigger>
+          <Accordion.Indicator />
+        </Accordion.Trigger>
+      </Accordion.Heading>
+      <Accordion.Panel>
+        <Accordion.Body/>
+      </Accordion.Panel>
+    </Accordion.Item>
+  </Accordion>
+)
+```
+
+### Surface
+
+<ComponentPreview
+  name="accordion-surface"
+ minHeight="400px"
+/>
+
+### 多项同时展开
+
+<ComponentPreview
+  name="accordion-multiple"
+   minHeight="524px"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="accordion-controlled"
+  minHeight="400px"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="accordion-custom-indicator"
+   minHeight="320px"
+/>
+
+### 禁用状态
+
+<ComponentPreview
+  name="accordion-disabled"
+   minHeight="524px"
+/>
+
+### FAQ 布局
+
+<ComponentPreview
+  name="accordion-faq"
+  minHeight="720px"
+/>
+
+### 自定义样式
+
+<ComponentPreview
+  name="accordion-custom-styles"
+  minHeight="420px"
+/>
+
+### 无分隔线
+
+<ComponentPreview
+  name="accordion-without-separator"
+  minHeight="400px"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="accordion-custom-render-function"
+  minHeight="400px"
+/>
+
+<RelatedComponents component="accordion" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+<CollapsibleCode lang="tsx" code={`"use client";
+
+import { Accordion, cn } from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+const items = [
+  {
+    content:
+      "Stay informed about your account activity with real-time notifications. You'll receive instant alerts for important events like transactions, new messages, security updates, and system announcements. ",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    title: "Set Up Notifications",
+    subtitle: "Receive account activity updates",
+  },
+  {
+    content:
+      "Enhance your browsing experience by installing our official browser extension. The extension provides seamless integration with your account, allowing you to receive notifications directly in your browser, quickly access your dashboard, and interact with web3 applications securely. Compatible with Chrome, Firefox, Edge, and Brave browsers.",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    title: "Set up Browser Extension",
+    subtitle: "Connect you browser to your account",
+  },
+  {
+    content:
+      "Begin your journey into the world of digital collectibles by creating your first NFT. Our intuitive minting process guides you through uploading your artwork, setting metadata, choosing royalty percentages, and deploying to the blockchain. Whether you're an artist, creator, or collector, you'll find all the tools you need to bring your digital assets to life. Your collectibles are stored on IPFS for permanent decentralized storage.",
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    title: "Mint Collectible",
+    subtitle: "Create your first collectible",
+  },
+];
+
+export function CustomStyles() {
+  return (
+    <Accordion className="bg-surface-secondary w-full max-w-md rounded-2xl" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item
+          key={index}
+          className={cn(
+            "group/item",
+            "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // 第一个触发器：圆角顶部
+            "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // 最后一个触发器：圆角底部
+          )}
+        >
+          <Accordion.Heading>
+            <Accordion.Trigger className="hover:bg-surface-tertiary group flex items-center gap-2">
+              {item.iconUrl ? (
+                <img
+                  alt={item.title}
+                  className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg"
+                  src={item.iconUrl}
+                />
+              ) : null}
+              <div className="flex flex-col gap-0">
+                <span className="font-medium leading-5">{item.title}</span>
+                <span className="text-muted/80 font-normal leading-6">{item.subtitle}</span>
+              </div>
+              <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
+                <Icon icon="gravity-ui:chevron-down" />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}`} />
+
+### 自定义组件类
+
+若要自定义 Accordion 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .accordion {
+    @apply rounded-xl bg-gray-50;
+  }
+
+  .accordion__trigger {
+    @apply font-semibold text-lg;
+  }
+
+  .accordion--outline {
+    @apply shadow-lg border-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)）：
+
+#### 基础类
+- `.accordion` - Accordion 根容器
+- `.accordion__body` - 正文容器
+- `.accordion__heading` - 标题包裹层
+- `.accordion__indicator` - 展开/收起指示图标
+- `.accordion__item` - 单个 Accordion 项
+- `.accordion__panel` - 可折叠面板容器
+- `.accordion__trigger` - 可点击的触发按钮
+
+#### 变体类
+- `.accordion--outline` - 描边变体（边框与背景）
+
+#### 状态类
+- `.accordion__trigger[aria-expanded="true"]` - 展开状态
+- `.accordion__panel[aria-hidden="false"]` - 面板可见状态
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性：
+
+- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：触发器上 `:disabled` 或 `[aria-disabled="true"]`
+- **展开**：触发器上 `[aria-expanded="true"]`
+
+## API 参考
+
+### Accordion Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开。 |
+| `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开的 key。 |
+| `expandedKeys` | `Iterable<Key>` | - | 受控的展开 key。 |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开 key 变化时调用的事件处理函数。 |
+| `isDisabled` | `boolean` | `false` | 是否禁用整个 Accordion。 |
+| `variant` | `"default" \| "surface"` | `"default"` | Accordion 的视觉变体。 |
+| `hideSeparator` | `boolean` | `false` | 是否隐藏 Accordion 项之间的分隔线。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | Accordion 项。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+
+### Accordion.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `Key` | - | 该项的唯一标识。 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该项。 |
+| `defaultExpanded` | `boolean` | `false` | 初始是否展开。 |
+| `isExpanded` | `boolean` | - | 受控展开状态。 |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时调用的事件处理函数。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 项内容。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Accordion.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 |
+| `onPress` | `() => void` | - | 额外的按下事件处理函数。 |
+| `isDisabled` | `boolean` | - | 是否禁用触发器。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Accordion.Panel Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 面板内容。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Accordion.Indicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 自定义指示图标。 |
+
+### Accordion.Body Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 正文内容。 |
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/breadcrumbs.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/breadcrumbs.mdx
new file mode 100644
index 0000000..d40e00f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/breadcrumbs.mdx
@@ -0,0 +1,162 @@
+---
+title: Breadcrumbs 面包屑
+description: 面包屑导航，用于展示当前页面在层级结构中的位置。
+links:
+  rac: Breadcrumbs
+  source: breadcrumbs/breadcrumbs.tsx
+  styles: breadcrumbs.css
+  storybook: Components/Navigation/Breadcrumbs
+---
+
+## 引入
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="breadcrumbs-basic"
+/>
+
+### 组件结构
+
+导入 Breadcrumbs 组件后，可通过点语法访问各个子部分。
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+
+export default () => (
+  <Breadcrumbs>
+    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+    <Breadcrumbs.Item>Current Page</Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+```
+
+### 导航层级
+
+<ComponentPreview
+  name="breadcrumbs-level-2"
+/>
+
+<ComponentPreview
+  name="breadcrumbs-level-3"
+/>
+
+### 自定义分隔符
+
+<ComponentPreview
+  name="breadcrumbs-custom-separator"
+/>
+
+### 禁用状态
+
+<ComponentPreview
+  name="breadcrumbs-disabled"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="breadcrumbs-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+
+function CustomBreadcrumbs() {
+  return (
+    <Breadcrumbs className="gap-2">
+      <Breadcrumbs.Item href="#" className="text-blue-600">
+        Home
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Breadcrumbs 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .breadcrumbs {
+    @apply gap-4 text-lg;
+  }
+
+  .breadcrumbs__link {
+    @apply font-semibold;
+  }
+
+  .breadcrumbs__separator {
+    @apply text-blue-500;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Breadcrumbs 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)）：
+
+#### 基础类
+
+- `.breadcrumbs` - 面包屑根容器
+- `.breadcrumbs__item` - 单个面包屑项的包裹层
+- `.breadcrumbs__link` - 面包屑链接元素
+- `.breadcrumbs__separator` - 项之间的分隔图标
+
+#### 状态类
+
+- `.breadcrumbs__link[data-current="true"]` - 当前页指示（非链接）
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+
+- **当前页**：链接上的 `[data-current="true"]`
+- **悬停**：链接元素支持常规悬停态
+- **禁用**：`isDisabled` prop 会禁用所有链接
+
+## API 参考
+
+### Breadcrumbs Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `separator` | `ReactNode` | chevron-right icon | 面包屑项之间的自定义分隔符 |
+| `isDisabled` | `boolean` | `false` | 是否禁用所有面包屑链接 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 面包屑项 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+### Breadcrumbs.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `href` | `string` | - | 链接 URL（当前页可省略） |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 项内容或渲染函数 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+## 无障碍
+
+Breadcrumbs 基于 React Aria Components 的 Breadcrumbs 原语，提供：
+
+- 导航地标的合适 ARIA 属性
+- 通过 `aria-current="page"` 标示当前页
+- 键盘导航支持
+- 屏幕阅读器对导航上下文的播报
+
+最后一项（无 `href`）会自动作为当前页指示。
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/disclosure-group.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/disclosure-group.mdx
new file mode 100644
index 0000000..6759243
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/disclosure-group.mdx
@@ -0,0 +1,143 @@
+---
+title: DisclosureGroup 折叠面板组
+description: 管理多个 Disclosure 的容器，用于协调展开状态。
+links:
+  rac: DisclosureGroup
+  source: disclosure-group/disclosure-group.tsx
+  styles: disclosure-group.css
+  storybook: Components/Navigation/DisclosureGroup
+---
+
+## 引入
+
+```tsx
+import { DisclosureGroup } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="disclosure-group-basic"
+  minHeight="580px"
+/>
+
+
+### 组件结构
+
+导入所有子部分并组合使用。
+
+```tsx
+import {DisclosureGroup, Disclosure} from '@heroui/react';
+
+export default () => (
+  <DisclosureGroup>
+    <Disclosure id="item1">
+      <Disclosure.Heading>
+        <Disclosure.Trigger>
+          <Disclosure.Indicator />
+        </Disclosure.Trigger>
+      </Disclosure.Heading>
+      <Disclosure.Content />
+    </Disclosure>
+  </DisclosureGroup>
+)
+```
+
+### 受控
+
+你可以使用 `expandedKeys` 与 `onExpandedChange` props，通过外部导航控件控制哪些 Disclosure 处于展开状态。
+
+<ComponentPreview
+  name="disclosure-group-controlled"
+  minHeight="580px"
+/>
+
+
+
+<RelatedShowcases component="DisclosureGroup" />
+
+<RelatedComponents component="disclosuregroup" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {
+  DisclosureGroup,
+  Disclosure,
+  DisclosureTrigger,
+  DisclosurePanel
+} from '@heroui/react';
+
+function CustomDisclosureGroup() {
+  return (
+    <DisclosureGroup className="border rounded-lg p-4 space-y-2">
+      <Disclosure id="first" className="border-b pb-2">
+        <DisclosureTrigger>Item 1</DisclosureTrigger>
+        <DisclosurePanel>Content 1</DisclosurePanel>
+      </Disclosure>
+      <Disclosure id="second">
+        <DisclosureTrigger>Item 2</DisclosureTrigger>
+        <DisclosurePanel>Content 2</DisclosurePanel>
+      </Disclosure>
+    </DisclosureGroup>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 DisclosureGroup 组件类，可以使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .disclosure-group {
+    @apply w-full;
+
+    /* Performance optimization */
+    contain: layout style;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+DisclosureGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure-group.css)）：
+
+#### 基础类
+
+- `.disclosure-group` - 带布局 containment 的基础容器样式
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，以便灵活控制状态：
+
+- **禁用**：在整个组合上使用 `:disabled` 或 `[aria-disabled="true"]`
+- **展开管理**：自动管理子 Disclosure 项上的 `[data-expanded]` 等状态
+
+## API 参考
+
+### DisclosureGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `expandedKeys` | `Set<Key>` | - | 当前展开项（受控） |
+| `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开项（非受控） |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开项变化时调用的处理函数 |
+| `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开 |
+| `isDisabled` | `boolean` | `false` | 是否禁用组内全部 Disclosure |
+| `children` | `ReactNode \| RenderFunction` | - | 要渲染的 Disclosure 项 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### RenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `expandedKeys` | `Set<Key>` | 当前展开的 key |
+| `isDisabled` | `boolean` | 组合是否禁用 |
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/disclosure.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/disclosure.mdx
new file mode 100644
index 0000000..4374f60
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/disclosure.mdx
@@ -0,0 +1,164 @@
+---
+title: Disclosure 折叠面板
+description: Disclosure 是一种可折叠区域：头部包含标题与触发按钮，面板包裹正文内容。
+links:
+  rac: Disclosure
+  source: disclosure/disclosure.tsx
+  styles: disclosure.css
+  storybook: Components/Navigation/Disclosure
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Disclosure } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="disclosure-basic"
+  minHeight="440px"
+/>
+
+### 组件结构
+
+导入 Disclosure 组件后，可通过点号访问各个子部分。
+
+```tsx
+import { Disclosure } from '@heroui/react';
+
+export default () => (
+  <Disclosure>
+    <Disclosure.Heading>
+      <Disclosure.Trigger>
+        <Disclosure.Indicator />
+      </Disclosure.Trigger>
+    </Disclosure.Heading>
+    <Disclosure.Content/>
+  </Disclosure>
+)
+```
+
+<RelatedShowcases component="Disclosure" />
+
+<RelatedComponents component="disclosure" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="disclosure-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Disclosure } from '@heroui/react';
+
+function CustomDisclosure() {
+  return (
+    <Disclosure className="border rounded-lg p-4">
+      <Disclosure.Heading>
+        <Disclosure.Trigger className="text-lg font-semibold">
+          Click to expand
+          <Disclosure.Indicator />
+        </Disclosure.Trigger>
+      </Disclosure.Heading>
+      <Disclosure.Content>
+        <Disclosure.Body className="mt-4 text-gray-600">
+          Hidden content
+        </Disclosure.Body>
+      </Disclosure.Content>
+    </Disclosure>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Disclosure 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .disclosure {
+    @apply relative;
+  }
+
+  .disclosure__trigger {
+    @apply cursor-pointer;
+  }
+
+  .disclosure__indicator {
+    @apply transition-transform duration-300;
+  }
+
+  .disclosure__content {
+    @apply overflow-hidden transition-all;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Disclosure 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)）：
+
+#### 基础类
+- `.disclosure` - 基础容器样式
+- `.disclosure__heading` - 标题包裹层
+- `.disclosure__trigger` - 触发按钮样式
+- `.disclosure__indicator` - Chevron 指示器样式
+- `.disclosure__content` - 带动画的内容容器
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+
+- **Expanded**：指示器上 `[data-expanded="true"]`，用于旋转等效果
+- **Focus**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：触发器上 `:disabled` 或 `[aria-disabled="true"]`
+- **Hidden**：内容上 `[aria-hidden="false"]` 表示可见
+
+
+## API 参考
+
+### Disclosure Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isExpanded` | `boolean` | `false` | 控制展开状态 |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时的回调 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 Disclosure |
+| `children` | `ReactNode \| RenderFunction` | - | 要渲染的内容 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### DisclosureTrigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容 |
+| `className` | `string` | - | 额外的 CSS 类 |
+
+### DisclosureContent Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 要显示/隐藏的内容 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+
+### RenderProps
+
+使用渲染 prop 模式时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `isExpanded` | `boolean` | 当前是否展开 |
+| `isDisabled` | `boolean` | Disclosure 是否禁用 |
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/link.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/link.mdx
new file mode 100644
index 0000000..7610a75
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/link.mdx
@@ -0,0 +1,224 @@
+---
+title: Link 链接
+description: 用于导航的样式化锚点组件，内置图标支持。
+links:
+  rac: Link
+  source: link/link.tsx
+  styles: link.css
+  storybook: Components/Navigation/Link
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Link } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="link-basic"
+/>
+
+### 组件结构
+
+导入 Link 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { Link } from '@heroui/react';
+
+export default () => (
+  <Link href="#">
+    Call to action
+    <Link.Icon />
+  </Link>
+);
+```
+
+### 自定义图标
+
+<ComponentPreview
+  name="link-custom-icon"
+/>
+
+### 图标位置
+
+<ComponentPreview
+  name="link-icon-placement"
+/>
+
+### 配合 Tailwind CSS 的文本装饰
+
+Link 默认在悬浮时显示下划线。可使用 Tailwind CSS 的 text-decoration 工具类让下划线始终可见、完全移除，或自定义其颜色、样式、粗细与偏移。
+
+<ComponentPreview
+  name="link-underline-and-offset"
+/>
+
+**文本装饰线：**
+- `underline` — 始终显示下划线
+- `no-underline` — 移除下划线
+- 默认 `Link` 样式 — 下划线在悬浮时显示
+
+**文本装饰色：**
+- `decoration-primary`、`decoration-secondary` 等 — 使用主题色设置下划线颜色
+- `decoration-muted/50` — 使用透明度修饰符实现半透明下划线
+
+**文本装饰样式：**
+- `decoration-solid` — 实线（默认）
+- `decoration-double` — 双线
+- `decoration-dotted` — 点线
+- `decoration-dashed` — 虚线
+- `decoration-wavy` — 波浪线
+
+**文本装饰粗细：**
+- `decoration-1`、`decoration-2`、`decoration-4` 等 — 控制下划线粗细
+
+**下划线偏移：**
+- `underline-offset-1`、`underline-offset-2`、`underline-offset-4` 等 — 调整文本与下划线间距
+
+更多说明见 Tailwind CSS 文档：
+- [text-decoration-line](https://tailwindcss.com/docs/text-decoration-line)
+- [text-decoration-color](https://tailwindcss.com/docs/text-decoration-color)
+- [text-decoration-style](https://tailwindcss.com/docs/text-decoration-style)
+- [text-decoration-thickness](https://tailwindcss.com/docs/text-decoration-thickness)
+- [text-underline-offset](https://tailwindcss.com/docs/text-underline-offset)
+
+
+可用的 BEM 类：
+- 基础：`link`
+- 图标：`link__icon`
+
+<RelatedComponents component="link" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="link-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Link } from '@heroui/react';
+
+function CustomLink() {
+  return (
+    <Link
+      href="#"
+      className="text-lg font-bold text-accent hover:text-accent/80"
+    >
+      Custom styled link
+    </Link>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Link 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .link {
+    @apply font-semibold;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Link 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/link.css)）：
+
+#### 基础类
+- `.link` — 链接基础样式
+- `.link__icon` — 链接图标样式
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，以获得更大灵活性：
+
+- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **悬浮**：`:hover` 或 `[data-hovered="true"]`
+- **按下**：`:active` 或 `[data-pressed="true"]`
+- **禁用**：`:disabled` 或 `[aria-disabled="true"]`
+
+## API 参考
+
+### Link Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `href` | `string` | - | 锚点的目标 URL |
+| `target` | `string` | `"_self"` | 在何处打开链接文档 |
+| `rel` | `string` | - | 当前文档与链接文档的关系 |
+| `download` | `boolean \| string` | - | 触发下载而非导航 |
+| `isDisabled` | `boolean` | `false` | 禁用指针与键盘交互 |
+| `className` | `string` | - | 与默认样式合并的自定义类 |
+| `children` | `React.ReactNode` | - | 渲染在链接内部的内容 |
+| `onPress` | `(e: PressEvent) => void` | - | 链接被激活时触发 |
+| `autoFocus` | `boolean` | - | 元素挂载时是否应获得焦点 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, LinkRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+### Link.Icon Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 自定义图标元素；省略时使用内置箭头图标 |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+
+
+### 与路由库配合使用
+
+使用变体函数为框架专用链接（例如 Next.js）添加样式：
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+export default function Demo() {
+  const slots = linkVariants();
+
+  return (
+    <NextLink className={slots.base()} href="/about">
+      About Page
+      <Link.Icon className={slots.icon()} />
+    </NextLink>
+  );
+}
+```
+
+### 直接应用类
+
+由于 HeroUI 使用 [BEM](https://getbem.com/) 类，你可以将 Link 样式直接应用到任意链接元素：
+
+```tsx
+import NextLink from 'next/link';
+
+// 直接使用 Tailwind 工具类
+export default function Demo() {
+  return (
+    <NextLink href="/about" className="link underline-offset-2">
+      About Page
+    </NextLink>
+  );
+}
+
+// 或使用原生 <a>
+export default function NativeLink() {
+  return (
+    <a href="/about" className="link underline decoration-primary underline-offset-4">
+      About Page
+      <Link.Icon className="link__icon" />
+    </a>
+  );
+}
+```
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/pagination.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/pagination.mdx
new file mode 100644
index 0000000..79fcf3a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/pagination.mdx
@@ -0,0 +1,253 @@
+---
+title: Pagination 分页
+description: 分页导航：可组合的页码链接、上一页/下一页按钮与省略号指示器。
+links:
+  source: pagination/pagination.tsx
+  styles: pagination.css
+  storybook: Components/Navigation/Pagination
+---
+
+## 引入
+
+```tsx
+import { Pagination } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="pagination-basic"
+/>
+
+### 组件结构
+
+导入 Pagination 组件后，可通过点号访问各个子部分。
+
+```tsx
+import { Pagination } from '@heroui/react';
+
+export default () => (
+  <Pagination>
+    <Pagination.Summary>Showing 1-10 of 100 results</Pagination.Summary>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon />
+          <span>Previous</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Ellipsis />
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>10</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+```
+
+### 尺寸
+
+<ComponentPreview
+  name="pagination-sizes"
+/>
+
+### 带省略号
+
+<ComponentPreview
+  name="pagination-with-ellipsis"
+/>
+
+### 简化（上一页 / 下一页）
+
+<ComponentPreview
+  name="pagination-simple-prev-next"
+/>
+
+### 带摘要
+
+<ComponentPreview
+  name="pagination-with-summary"
+/>
+
+### 自定义图标
+
+你可以通过为 `PreviousIcon` 与 `NextIcon` 传入自定义子节点来替换默认的 chevron 图标。
+
+<ComponentPreview
+  name="pagination-custom-icons"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="pagination-controlled"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="pagination-disabled"
+/>
+
+<RelatedComponents component="pagination" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+你可以单独定制 Pagination 的各个子部分：
+
+```tsx
+import { Pagination } from '@heroui/react';
+
+function CustomPagination() {
+  return (
+    <Pagination className="gap-8">
+      <Pagination.Content className="gap-2">
+        <Pagination.Item>
+          <Pagination.Link className="rounded-md" isActive>1</Pagination.Link>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Pagination 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .pagination {
+    @apply gap-8;
+  }
+
+  .pagination__link {
+    @apply rounded-md;
+  }
+
+  .pagination__summary {
+    @apply text-xs font-semibold;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，以确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)）：
+
+#### 基础与布局类
+- `.pagination` - 根导航容器（flex 布局）
+- `.pagination__summary` - 左侧信息文本容器
+- `.pagination__content` - 分页项容器
+- `.pagination__item` - 单个分页项包裹层
+- `.pagination__link` - 页码按钮（ghost 按钮样式）
+- `.pagination__link--nav` - 导航按钮修饰符（Previous/Next）
+- `.pagination__ellipsis` - 省略号指示器
+
+#### 尺寸类
+- `.pagination--sm` - 小尺寸变体
+- `.pagination--md` - 中尺寸变体（默认）
+- `.pagination--lg` - 大尺寸变体
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活定制：
+
+- **Active page**：`[data-active="true"]` 或 `[aria-current="page"]`
+- **Hover**：`:hover` 或 `[data-hovered="true"]`
+- **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`
+- **Pressed**：`:active` 或 `[data-pressed="true"]`
+
+## API 参考
+
+### Pagination Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 分页控件的尺寸 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 分页部件（Summary、Content 等） |
+
+### Pagination.Summary Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 摘要内容（例如 "Showing 1-10 of 120"） |
+
+### Pagination.Content Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 分页项 |
+
+### Pagination.Item Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 项内容（Link、Previous、Next 或 Ellipsis） |
+
+### Pagination.Link Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isActive` | `boolean` | `false` | 是否为当前页 |
+| `isDisabled` | `boolean` | `false` | 是否禁用链接 |
+| `onPress` | `(e: PressEvent) => void` | - | 按下事件处理函数（来自 React Aria） |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 页码内容 |
+
+### Pagination.Previous / Pagination.Next Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `isDisabled` | `boolean` | `false` | 是否禁用按钮 |
+| `onPress` | `(e: PressEvent) => void` | - | 按下事件处理函数（来自 React Aria） |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 按钮内容（可与 PreviousIcon/NextIcon 组合） |
+
+### Pagination.PreviousIcon / Pagination.NextIcon Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | Default chevron SVG | 用于替换默认 chevron 的自定义图标 |
+
+### Pagination.Ellipsis Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 CSS 类 |
+
+## 无障碍
+
+Pagination 基于 [React Aria 的 Button](https://react-spectrum.adobe.com/react-aria/Button.html) 原语实现所有可交互元素，并提供：
+
+- 语义化 `<nav>` 元素，包含 `aria-label="pagination"` 与 `role="navigation"`
+- 通过在当前链接上使用 `aria-current="page"` 标示活动页
+- 通过 Tab 键在全部可交互元素间进行键盘导航
+- 通过 React Aria 在鼠标、触摸与键盘交互之间统一处理按下事件
+- 键盘导航时通过 `:focus-visible` 显示焦点环
+- 省略号使用 `aria-hidden="true"`，避免干扰屏幕阅读器
+- 通过 `isDisabled` 向辅助技术正确传达禁用状态
+
+> **说明：** Pagination 按钮请使用 `onPress` 而不是 `onClick`。React Aria 的 `onPress` 会规范化不同指针类型的按下行为，并提供开箱即用的无障碍改进。
diff --git a/apps/docs/content/docs/cn/react/components/(navigation)/tabs.mdx b/apps/docs/content/docs/cn/react/components/(navigation)/tabs.mdx
new file mode 100644
index 0000000..4677e7d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(navigation)/tabs.mdx
@@ -0,0 +1,230 @@
+---
+title: Tabs 标签页
+description: Tabs 将内容组织为多个区块，并允许用户在它们之间导航。
+icon: new
+links:
+  rac: Tabs
+  source: tabs/tabs.tsx
+  styles: tabs.css
+  storybook: Components/Navigation/Tabs
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Tabs } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-basic"
+/>
+
+### 组件结构
+
+导入 Tabs 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { Tabs } from '@heroui/react';
+
+export default () => (
+  <Tabs>
+    <Tabs.ListContainer>
+      <Tabs.List aria-label="Options">
+        <Tabs.Tab>
+          <Tabs.Separator /> {/* Optional */}
+          <Tabs.Indicator />
+        </Tabs.Tab>
+      </Tabs.List>
+    </Tabs.ListContainer>
+    <Tabs.Panel/>
+  </Tabs>
+)
+```
+
+### 垂直布局
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-vertical"
+/>
+
+### 溢出
+
+当标签列表超出可用空间时，`Tabs.ListContainer` 会自动渲染滚动箭头与渐隐边缘，使用户可以导航到被隐藏的标签。水平与垂直方向均支持此行为。
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-overflow"
+/>
+
+### 禁用 Tab
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-disabled"
+/>
+
+### 带分隔线
+
+在每个 `<Tabs.Tab>` 内（第一项除外）添加 `<Tabs.Separator />`，用于在标签之间显示分隔线。
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-with-separator"
+/>
+
+### 自定义样式
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-custom-styles"
+/>
+
+### Secondary 变体
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-secondary"
+/>
+
+### Secondary 变体（垂直）
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-secondary-vertical"
+/>
+
+<RelatedShowcases component="Tabs" />
+
+<RelatedComponents component="tabs" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="tabs-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+<CollapsibleCode lang="tsx" code={`
+import { Tabs } from '@heroui/react';
+
+function CustomTabs() {
+  return (
+    <Tabs className="w-full max-w-lg text-center">
+      <Tabs.ListContainer>
+        <Tabs.List
+          aria-label="Options"
+          className="*:data-[selected=true]:text-accent-foreground w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal"
+        >
+          <Tabs.Tab id="daily">Daily<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="weekly">Weekly<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="bi-weekly">Bi-Weekly<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="monthly">Monthly<Tabs.Indicator /></Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="daily">
+        <h3 className="mb-2 font-semibold">Daily</h3>
+        <p className="text-sm text-gray-600">Manage your daily tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="weekly">
+        <h3 className="mb-2 font-semibold">Weekly</h3>
+        <p className="text-sm text-gray-600">Manage your weekly tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="bi-weekly">
+        <h3 className="mb-2 font-semibold">Bi-Weekly</h3>
+        <p className="text-sm text-gray-600">Manage your bi-weekly tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="monthly">
+        <h3 className="mb-2 font-semibold">Monthly</h3>
+        <p className="text-sm text-gray-600">Manage your monthly tasks and goals.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+`} />
+
+### CSS 类
+
+Tabs 使用以下 CSS 类：
+
+#### 基础类
+- `.tabs` — Tabs 根容器
+- `.tabs__list-container` — 标签列表容器外层包裹
+- `.tabs__list-container__scroller` — 标签列表的可滚动容器（处理溢出与渐隐边缘）
+- `.tabs__list-container__scroll-prev` — 向前（左 / 上）滚动的箭头按钮
+- `.tabs__list-container__scroll-next` — 向后（右 / 下）滚动的箭头按钮
+- `.tabs__list` — 标签列表容器
+- `.tabs__tab` — 单个标签按钮
+- `.tabs__separator` — 标签之间的分隔线
+- `.tabs__panel` — 标签面板内容
+- `.tabs__indicator` — 标签指示器
+
+#### 方向属性
+- `.tabs[data-orientation="horizontal"]` — 水平标签布局（默认）
+- `.tabs[data-orientation="vertical"]` — 垂直标签布局
+
+#### 变体类
+- `.tabs--secondary` — Secondary 变体，使用下划线指示器
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性：
+
+- **已选中**：`[aria-selected="true"]`
+- **悬停**：`:hover` 或 `[data-hovered="true"]`
+- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：`[aria-disabled="true"]`
+
+
+
+## API 参考
+
+### Tabs Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉样式变体。Primary 使用填充指示器，Secondary 使用下划线指示器 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 标签布局方向 |
+| `selectedKey` | `string` | - | 受控选中标签的 key |
+| `defaultSelectedKey` | `string` | - | 默认选中标签的 key |
+| `onSelectionChange` | `(key: Key) => void` | - | 选中变化事件处理函数 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+### Tabs.List Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `aria-label` | `string` | - | 标签列表的无障碍标签 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+### Tabs.Tab Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `string` | - | 标签唯一标识 |
+| `isDisabled` | `boolean` | `false` | 是否禁用该标签 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
+
+### Tabs.Separator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Tabs.Panel Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `id` | `string` | - | 与对应 Tab id 匹配的面板标识 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/alert-dialog.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/alert-dialog.mdx
new file mode 100644
index 0000000..7185ad2
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/alert-dialog.mdx
@@ -0,0 +1,325 @@
+---
+title: AlertDialog 警告对话框
+description: 用于关键确认的模态对话框，需要用户关注并执行明确操作。
+links:
+  rac: AlertDialog
+  source: alert-dialog/alert-dialog.tsx
+  styles: alert-dialog.css
+  storybook: Components/Overlays/AlertDialog
+---
+
+## 引入
+
+```tsx
+import { AlertDialog } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview name="alert-dialog-default" />
+
+### 组件结构
+
+导入 AlertDialog 组件后，可通过点语法访问各个子部分。
+
+```tsx
+import {AlertDialog, Button} from "@heroui/react";
+
+export default () => (
+  <AlertDialog>
+    <Button>Open Alert Dialog</Button>
+    <AlertDialog.Backdrop>
+      <AlertDialog.Container>
+        <AlertDialog.Dialog>
+          <AlertDialog.CloseTrigger /> {/* Optional: Close button */}
+          <AlertDialog.Header>
+            <AlertDialog.Icon /> {/* Optional: Status icon */}
+            <AlertDialog.Heading />
+          </AlertDialog.Header>
+          <AlertDialog.Body />
+          <AlertDialog.Footer />
+        </AlertDialog.Dialog>
+      </AlertDialog.Container>
+    </AlertDialog.Backdrop>
+  </AlertDialog>
+);
+```
+
+### 状态
+
+<ComponentPreview name="alert-dialog-statuses" />
+
+### 位置
+
+<ComponentPreview name="alert-dialog-placements" />
+
+### 背景变体
+
+<ComponentPreview name="alert-dialog-backdrop-variants" />
+
+### 尺寸
+
+<ComponentPreview name="alert-dialog-sizes" />
+
+### 自定义图标
+
+<ComponentPreview name="alert-dialog-custom-icon" />
+
+### 自定义背景
+
+<ComponentPreview name="alert-dialog-custom-backdrop" />
+
+### 关闭行为
+
+<ComponentPreview name="alert-dialog-dismiss-behavior" />
+
+### 关闭方式
+
+<ComponentPreview name="alert-dialog-close-methods" />
+
+### 受控状态
+
+<ComponentPreview name="alert-dialog-controlled" />
+
+### 自定义触发器
+
+<ComponentPreview name="alert-dialog-custom-trigger" />
+
+### 自定义动画
+
+<ComponentPreview name="alert-dialog-custom-animations" />
+
+### 自定义 Portal
+
+<ComponentPreview name="alert-dialog-custom-portal" />
+
+<RelatedComponents component="alert-dialog" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {AlertDialog, Button} from "@heroui/react";
+
+function CustomAlertDialog() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">Delete</Button>
+      <AlertDialog.Backdrop className="bg-red-950/90">
+        <AlertDialog.Container className="items-start pt-20">
+          <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger" />
+              <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>This alert dialog has custom styling applied via Tailwind classes</p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close" variant="danger">
+                Delete
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 AlertDialog 的组件类，可使用 `@layer components` 指令。
+
+<br />
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .alert-dialog__backdrop {
+    @apply bg-gradient-to-br from-black/60 to-black/80;
+  }
+
+  .alert-dialog__dialog {
+    @apply rounded-2xl border border-red-500/20 shadow-2xl;
+  }
+
+  .alert-dialog__header {
+    @apply gap-4;
+  }
+
+  .alert-dialog__icon {
+    @apply size-16;
+  }
+
+  .alert-dialog__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+AlertDialog 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)）：
+
+#### 基础类
+
+- `.alert-dialog__trigger` - 打开对话框的触发元素
+- `.alert-dialog__backdrop` - 对话框背后的遮罩层
+- `.alert-dialog__container` - 支持位置配置的包裹层
+- `.alert-dialog__dialog` - 对话框内容容器
+- `.alert-dialog__header` - 图标与标题区域
+- `.alert-dialog__heading` - 标题文本样式
+- `.alert-dialog__body` - 主内容区域
+- `.alert-dialog__footer` - 操作按钮区域
+- `.alert-dialog__icon` - 带状态色的图标容器
+- `.alert-dialog__close-trigger` - 关闭按钮元素
+
+#### 背景变体
+
+- `.alert-dialog__backdrop--opaque` - 不透明有色背景（默认）
+- `.alert-dialog__backdrop--blur` - 带玻璃效果的模糊背景
+- `.alert-dialog__backdrop--transparent` - 透明背景（无遮罩）
+
+#### 状态变体（图标）
+
+- `.alert-dialog__icon--default` - 默认灰色状态
+- `.alert-dialog__icon--accent` - 强调蓝色状态
+- `.alert-dialog__icon--success` - 成功绿色状态
+- `.alert-dialog__icon--warning` - 警告橙色状态
+- `.alert-dialog__icon--danger` - 危险红色状态
+
+### 交互状态
+
+组件支持以下交互状态：
+
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器、对话框与关闭按钮
+- **悬停**：`:hover` 或 `[data-hovered="true"]` — 应用于关闭按钮悬停时
+- **激活**：`:active` 或 `[data-pressed="true"]` — 应用于关闭按钮按下时
+- **进入**：`[data-entering]` — 应用于对话框打开动画期间
+- **离开**：`[data-exiting]` — 应用于对话框关闭动画期间
+- **位置**：`[data-placement="*"]` — 根据对话框位置应用（auto、top、center、bottom）
+
+## API 参考
+
+### AlertDialog
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 触发器与容器元素 |
+
+### AlertDialog.Trigger
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 自定义触发器内容 |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.Backdrop
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 背景遮罩样式 |
+| `isDismissable` | `boolean` | `false` | 点击背景是否关闭 |
+| `isKeyboardDismissDisabled` | `boolean` | `true` | 是否禁用 ESC 关闭 |
+| `isOpen` | `boolean` | - | 受控的打开状态 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化的事件处理函数 |
+| `className` | `string \| (values) => string` | - | 背景的 CSS 类 |
+| `UNSTABLE_portalContainer` | `HTMLElement` | - | 自定义 portal 容器 |
+
+### AlertDialog.Container
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | 对话框在屏幕上的位置 |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"` | AlertDialog 尺寸变体 |
+| `className` | `string \| (values) => string` | - | 容器的 CSS 类 |
+
+### AlertDialog.Dialog
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode \| ({close}) => ReactNode` | - | 内容或渲染函数 |
+| `className` | `string` | - | CSS 类 |
+| `role` | `string` | `"alertdialog"` | ARIA role |
+| `aria-label` | `string` | - | 无障碍标签 |
+| `aria-labelledby` | `string` | - | 标签元素的 id |
+| `aria-describedby` | `string` | - | 描述元素的 id |
+
+### AlertDialog.Header
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 头部内容（通常为 Icon 与 Heading） |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.Heading
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 标题文本 |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.Body
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 正文内容 |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.Footer
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 底部内容（通常为操作按钮） |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.Icon
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 自定义图标元素 |
+| `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"danger"` | 状态颜色变体 |
+| `className` | `string` | - | CSS 类 |
+
+### AlertDialog.CloseTrigger
+
+| Prop | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `children` | `ReactNode` | - | 自定义关闭按钮 |
+| `className` | `string \| (values) => string` | - | CSS 类 |
+
+### useOverlayState Hook
+
+```tsx
+import {useOverlayState} from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // Current state
+state.open(); // Open dialog
+state.close(); // Close dialog
+state.toggle(); // Toggle state
+state.setOpen(); // Set state directly
+```
+
+## 无障碍
+
+实现 [WAI-ARIA AlertDialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)：
+
+- **焦点陷阱**：焦点限制在 AlertDialog 内
+- **键盘**：`ESC` 关闭（若启用）、`Tab` 在可聚焦元素间循环
+- **屏幕阅读器**：`role="alertdialog"` 等合适的 ARIA 属性
+- **滚动锁定**：打开时禁用 body 滚动
+- **需要明确操作**：默认需要用户明确操作（不通过点击背景/ESC 轻易关闭）
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/drawer.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/drawer.mdx
new file mode 100644
index 0000000..c0cfe3b
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/drawer.mdx
@@ -0,0 +1,299 @@
+---
+title: Drawer 抽屉
+description: 用于补充内容与操作的侧滑面板。
+links:
+  rac: Modal
+  source: drawer/drawer.tsx
+  styles: drawer.css
+  storybook: Components/Overlays/Drawer
+---
+
+## 引入
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview name="drawer-basic" />
+
+### 组件结构
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+export default () => (
+  <Drawer>
+    <Button>Open Drawer</Button>
+    <Drawer.Backdrop>
+      <Drawer.Content>
+        <Drawer.Dialog>
+          <Drawer.Handle /> {/* Optional: Drag handle */}
+          <Drawer.CloseTrigger /> {/* Optional: Close button */}
+          <Drawer.Header>
+            <Drawer.Heading />
+          </Drawer.Header>
+          <Drawer.Body />
+          <Drawer.Footer />
+        </Drawer.Dialog>
+      </Drawer.Content>
+    </Drawer.Backdrop>
+  </Drawer>
+);
+```
+
+### 位置
+
+<ComponentPreview name="drawer-placements" />
+
+### 遮罩变体
+
+<ComponentPreview name="drawer-backdrop-variants" />
+
+### 不可关闭
+
+在 `Drawer.Backdrop` 上设置 `isDismissable={false}`，可阻止通过点击外部或拖动关闭。用户必须与抽屉内的操作按钮交互才能关闭。
+
+<ComponentPreview name="drawer-non-dismissable" />
+
+### 可滚动内容
+
+`Drawer.Body` 会使用原生滚动处理溢出。为避免与滚动冲突，拖拽关闭不会在 body 区域生效。
+
+<ComponentPreview name="drawer-scrollable-content" />
+
+### 受控状态
+
+<ComponentPreview name="drawer-controlled" />
+
+### 带表单
+
+<ComponentPreview name="drawer-with-form" />
+
+### 导航抽屉
+
+<ComponentPreview name="drawer-navigation" />
+
+<RelatedComponents component="drawer" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+function CustomDrawer() {
+  return (
+    <Drawer>
+      <Button>Open Drawer</Button>
+      <Drawer.Backdrop className="bg-black/80">
+        <Drawer.Content>
+          <Drawer.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Custom Styled Drawer</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>This drawer has custom styling applied via Tailwind classes.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Drawer 组件类，可以使用 `@layer components` 指令。
+
+<br />
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .drawer__backdrop {
+    @apply bg-gradient-to-br from-black/50 to-black/70;
+  }
+
+  .drawer__dialog {
+    @apply rounded-2xl border border-white/10 shadow-2xl;
+  }
+
+  .drawer__header {
+    @apply text-center;
+  }
+
+  .drawer__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Drawer 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/drawer.css)）：
+
+#### 基础类
+
+- `.drawer__trigger` - 打开 Drawer 的触发元素
+- `.drawer__backdrop` - Drawer 背后的遮罩
+- `.drawer__content` - Drawer 面板的定位包裹层
+- `.drawer__dialog` - Drawer 面板本体
+- `.drawer__header` - 表头区域
+- `.drawer__heading` - 主标题文本
+- `.drawer__body` - 可滚动主体内容区域
+- `.drawer__footer` - 表底操作区域
+- `.drawer__handle` - 视觉拖拽把手
+- `.drawer__close-trigger` - 关闭按钮元素
+
+#### 遮罩变体
+
+- `.drawer__backdrop--opaque` - 不透明有色遮罩（默认）
+- `.drawer__backdrop--blur` - 带玻璃效果的模糊遮罩
+- `.drawer__backdrop--transparent` - 透明遮罩（无叠加层）
+
+#### 位置变体
+
+- `.drawer__content--bottom` - 自底边上滑（默认）
+- `.drawer__content--top` - 自顶边下滑
+- `.drawer__content--left` - 自左侧滑入
+- `.drawer__content--right` - 自右侧滑入
+
+#### 对话框变体
+
+- `.drawer__dialog--top` - 自顶边下滑
+- `.drawer__dialog--bottom` - 自底边上滑
+- `.drawer__dialog--left` - 自左侧滑入
+- `.drawer__dialog--right` - 自右侧滑入
+
+### 交互状态
+
+该组件支持以下交互状态：
+
+- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器与关闭按钮
+- **悬停**：`:hover` 或 `[data-hovered="true"]` — 关闭按钮悬停时应用
+- **激活**：`:active` 或 `[data-pressed="true"]` — 触发器与关闭按钮被按压时应用
+- **进入**：`[data-entering]` — Drawer 打开动画期间应用
+- **离开**：`[data-exiting]` — Drawer 关闭动画期间应用
+- **位置**：`[data-placement="*"]` — 根据 Drawer 位置应用（top、bottom、left、right）
+
+## API 参考
+
+### Drawer
+
+| Prop       | Type                   | 默认值 | 描述                    |
+| ---------- | ---------------------- | ------ | ----------------------- |
+| `children` | `ReactNode`            | -      | 触发器与遮罩子元素。    |
+| `state`    | `UseOverlayStateReturn` | -    | 受控的叠加层状态。      |
+
+### Drawer.Trigger
+
+| Prop        | Type        | 默认值 | 描述            |
+| ----------- | ----------- | ------ | --------------- |
+| `children`  | `ReactNode` | -      | 自定义触发内容。 |
+| `className` | `string`    | -      | CSS 类。        |
+
+### Drawer.Backdrop
+
+| Prop                        | Type                                  | 默认值    | 描述               |
+| --------------------------- | ------------------------------------- | --------- | ------------------ |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩叠加样式。     |
+| `isDismissable`             | `boolean`                             | `true`     | 点击遮罩是否关闭。 |
+| `isKeyboardDismissDisabled` | `boolean`                             | `false`    | 是否禁用 ESC 关闭。 |
+| `isOpen`                    | `boolean`                             | -          | 受控打开状态。     |
+| `onOpenChange`              | `(isOpen: boolean) => void`           | -          | 打开状态变化时的事件处理函数。 |
+| `className`                 | `string \| (values) => string`        | -          | 遮罩 CSS 类。      |
+
+### Drawer.Content
+
+| Prop        | Type                                          | 默认值    | 描述               |
+| ----------- | --------------------------------------------- | --------- | ------------------ |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Drawer 从哪一侧滑入。 |
+| `className` | `string \| (values) => string`                | -          | Content CSS 类。   |
+
+### Drawer.Dialog
+
+| Prop               | Type                           | 默认值    | 描述            |
+| ------------------ | ------------------------------ | --------- | --------------- |
+| `children`         | `ReactNode`                    | -         | 对话框内容。    |
+| `className`        | `string`                       | -         | CSS 类。        |
+| `role`             | `string`                       | `"dialog"` | ARIA role。     |
+| `aria-label`       | `string`                       | -         | 无障碍标签。    |
+| `aria-labelledby`  | `string`                       | -         | 标签元素 ID。   |
+
+### Drawer.Header
+
+| Prop        | Type        | 默认值 | 描述        |
+| ----------- | ----------- | ------ | ----------- |
+| `children`  | `ReactNode` | -      | 表头内容。  |
+| `className` | `string`    | -      | CSS 类。    |
+
+### Drawer.Heading
+
+| Prop        | Type        | 默认值 | 描述      |
+| ----------- | ----------- | ------ | --------- |
+| `children`  | `ReactNode` | -      | 标题文本。 |
+| `className` | `string`    | -      | CSS 类。   |
+
+### Drawer.Body
+
+| Prop        | Type        | 默认值 | 描述      |
+| ----------- | ----------- | ------ | --------- |
+| `children`  | `ReactNode` | -      | 主体内容。 |
+| `className` | `string`    | -      | CSS 类。   |
+
+### Drawer.Footer
+
+| Prop        | Type        | 默认值 | 描述        |
+| ----------- | ----------- | ------ | ----------- |
+| `children`  | `ReactNode` | -      | 表底内容。  |
+| `className` | `string`    | -      | CSS 类。    |
+
+### Drawer.Handle
+
+| Prop        | Type     | 默认值 | 描述   |
+| ----------- | -------- | ------ | ------ |
+| `className` | `string` | -      | CSS 类。 |
+
+### Drawer.CloseTrigger
+
+| Prop        | Type                           | 默认值 | 描述            |
+| ----------- | ------------------------------ | ------ | --------------- |
+| `children`  | `ReactNode`                    | -      | 自定义关闭按钮。 |
+| `className` | `string \| (values) => string` | -      | CSS 类。        |
+
+### useOverlayState Hook
+
+```tsx
+import { useOverlayState } from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // Current state
+state.open(); // Open drawer
+state.close(); // Close drawer
+state.toggle(); // Toggle state
+state.setOpen(); // Set state directly
+```
+
+## 无障碍
+
+实现 [WAI-ARIA Dialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)：
+
+- **焦点陷阱**：打开时将焦点锁定在 Drawer 内
+- **键盘**：可关闭时 `ESC` 关闭，`Tab` 在可聚焦元素间循环
+- **屏幕阅读器**：通过 React Aria 提供合适的 ARIA 属性
+- **滚动锁定**：打开时禁用 body 滚动
+- **拖拽关闭**：支持在把手、表头与表底等区域的指针拖拽手势
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/modal.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/modal.mdx
new file mode 100644
index 0000000..8ddd261
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/modal.mdx
@@ -0,0 +1,292 @@
+---
+title: Modal 模态框
+description: 用于聚焦用户交互与重要内容的对话框遮罩层。
+links:
+  rac: Modal
+  source: modal/modal.tsx
+  styles: modal.css
+  storybook: modal
+---
+
+## 引入
+
+```tsx
+import { Modal } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview name="modal-default" />
+
+### 组件结构
+
+导入 Modal 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import {Modal, Button} from "@heroui/react";
+
+export default () => (
+  <Modal>
+    <Button>Open Modal</Button>
+    <Modal.Backdrop>
+      <Modal.Container>
+        <Modal.Dialog>
+          <Modal.CloseTrigger /> {/* Optional: Close button */}
+          <Modal.Header>
+            <Modal.Icon /> {/* Optional: Icon */}
+            <Modal.Heading />
+          </Modal.Header>
+          <Modal.Body />
+          <Modal.Footer />
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  </Modal>
+);
+```
+
+### 位置
+
+<ComponentPreview name="modal-placements" />
+
+### 遮罩变体
+
+<ComponentPreview name="modal-backdrop-variants" />
+
+### 尺寸
+
+<ComponentPreview name="modal-sizes" />
+
+### 自定义遮罩
+
+<ComponentPreview name="modal-custom-backdrop" />
+
+### 关闭行为
+
+<ComponentPreview name="modal-dismiss-behavior" />
+
+### 关闭方式
+
+<ComponentPreview name="modal-close-methods" />
+
+### 滚动行为
+
+<ComponentPreview name="modal-scroll-comparison" />
+
+### 受控状态
+
+<ComponentPreview name="modal-controlled" />
+
+### 带表单
+
+<ComponentPreview name="modal-with-form" />
+
+### 自定义触发器
+
+<ComponentPreview name="modal-custom-trigger" />
+
+### 自定义动画
+
+<ComponentPreview name="modal-custom-animations" />
+
+### 自定义 Portal
+
+<ComponentPreview name="modal-custom-portal" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Modal, Button} from "@heroui/react";
+
+function CustomModal() {
+  return (
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop className="bg-black/80">
+        <Modal.Container className="items-start pt-20">
+          <Modal.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Custom Styled Modal</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>This modal has custom styling applied via Tailwind classes</p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close">Close</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Modal 的组件类，可使用 `@layer components` 指令。
+
+<br />
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .modal__backdrop {
+    @apply bg-gradient-to-br from-black/50 to-black/70;
+  }
+
+  .modal__dialog {
+    @apply rounded-2xl border border-white/10 shadow-2xl;
+  }
+
+  .modal__header {
+    @apply text-center;
+  }
+
+  .modal__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Modal 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/modal.css)）：
+
+#### 基础类
+- `.modal__trigger` — 打开 Modal 的触发元素
+- `.modal__backdrop` — Modal 背后的遮罩层
+- `.modal__container` — 支持 placement 的定位包裹层
+- `.modal__dialog` — Modal 内容容器
+- `.modal__header` — 标题与图标区域
+- `.modal__body` — 主内容区域
+- `.modal__footer` — 操作区域
+- `.modal__close-trigger` — 关闭按钮元素
+
+#### 遮罩变体
+- `.modal__backdrop--opaque` — 不透明有色遮罩（默认）
+- `.modal__backdrop--blur` — 带玻璃效果的模糊遮罩
+- `.modal__backdrop--transparent` — 透明遮罩（无叠加层）
+
+#### 滚动变体
+- `.modal__container--scroll-outside` — 允许整个 Modal 滚动
+- `.modal__dialog--scroll-inside` — 限制 Modal 高度，由 body 区域滚动
+- `.modal__body--scroll-inside` — 仅 body 区域可滚动
+- `.modal__body--scroll-outside` — 允许整页滚动
+
+### 交互状态
+
+组件支持以下交互状态：
+
+- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器、对话框与关闭按钮
+- **悬停**：`:hover` 或 `[data-hovered="true"]` — 应用于关闭按钮悬停
+- **按下**：`:active` 或 `[data-pressed="true"]` — 应用于关闭按钮按下
+- **进入**：`[data-entering]` — Modal 打开动画期间
+- **离开**：`[data-exiting]` — Modal 关闭动画期间
+- **位置**：`[data-placement="*"]` — 基于 Modal 位置（auto、top、center、bottom）
+
+## API 参考
+
+### Modal
+
+| Prop       | 类型        | 默认值 | 描述                    |
+| ---------- | ----------- | ------ | ----------------------- |
+| `children` | `ReactNode` | -      | 触发器与容器元素        |
+
+### Modal.Trigger
+
+| Prop        | 类型        | 默认值 | 描述             |
+| ----------- | ----------- | ------ | ---------------- |
+| `children`  | `ReactNode` | -      | 自定义触发内容   |
+| `className` | `string`    | -      | CSS 类           |
+
+### Modal.Backdrop
+
+| Prop                        | 类型                                  | 默认值    | 描述                 |
+| --------------------------- | ------------------------------------- | --------- | -------------------- |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩叠加样式         |
+| `isDismissable`             | `boolean`                             | `true`    | 点击遮罩是否关闭     |
+| `isKeyboardDismissDisabled` | `boolean`                             | `false`   | 是否禁用 ESC 关闭    |
+| `isOpen`                    | `boolean`                             | -         | 受控打开状态         |
+| `onOpenChange`              | `(isOpen: boolean) => void`           | -         | 打开状态变化处理函数 |
+| `className`                 | `string \| (values) => string`        | -         | 遮罩 CSS 类          |
+| `UNSTABLE_portalContainer`  | `HTMLElement`                         | -         | 自定义 portal 容器   |
+
+### Modal.Container
+
+| Prop        | 类型                                      | 默认值    | 描述                |
+| ----------- | ----------------------------------------- | --------- | ------------------- |
+| `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"`  | Modal 在屏幕上的位置 |
+| `scroll`    | `"inside" \| "outside"`                   | `"inside"` | 滚动行为            |
+| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "cover" \| "full"` | `"md"` | Modal 尺寸变体      |
+| `className` | `string \| (values) => string`            | -         | 容器 CSS 类         |
+
+### Modal.Dialog
+
+| Prop               | 类型                                  | 默认值    | 描述                   |
+| ------------------ | ------------------------------------- | --------- | ---------------------- |
+| `children`         | `ReactNode \| ({close}) => ReactNode` | -         | 内容或渲染函数         |
+| `className`        | `string \| (values) => string`        | -         | CSS 类                 |
+| `role`             | `string`                              | `"dialog"` | ARIA role              |
+| `aria-label`       | `string`                              | -         | 无障碍标签             |
+| `aria-labelledby`  | `string`                              | -         | 标签元素的 id          |
+| `aria-describedby` | `string`                              | -         | 描述元素的 id          |
+
+### Modal.Header
+
+| Prop        | 类型        | 默认值 | 描述       |
+| ----------- | ----------- | ------ | ---------- |
+| `children`  | `ReactNode` | -      | 头部内容   |
+| `className` | `string`    | -      | CSS 类     |
+
+### Modal.Body
+
+| Prop        | 类型        | 默认值 | 描述     |
+| ----------- | ----------- | ------ | -------- |
+| `children`  | `ReactNode` | -      | 正文内容 |
+| `className` | `string`    | -      | CSS 类   |
+
+### Modal.Footer
+
+| Prop        | 类型        | 默认值 | 描述     |
+| ----------- | ----------- | ------ | -------- |
+| `children`  | `ReactNode` | -      | 底部内容 |
+| `className` | `string`    | -      | CSS 类   |
+
+### Modal.CloseTrigger
+
+| Prop        | 类型                           | 默认值 | 描述           |
+| ----------- | ------------------------------ | ------ | -------------- |
+| `children`  | `ReactNode`                    | -      | 自定义关闭按钮 |
+| `className` | `string \| (values) => string` | -      | CSS 类         |
+
+### useOverlayState Hook
+
+```tsx
+import {useOverlayState} from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // 当前状态
+state.open(); // 打开 modal
+state.close(); // 关闭 modal
+state.toggle(); // 切换状态
+state.setOpen(); // 直接设置状态
+```
+
+## 无障碍
+
+实现 [WAI-ARIA Dialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)：
+
+- **焦点陷阱**：焦点锁定在 Modal 内
+- **键盘**：`ESC` 关闭（启用时）、`Tab` 在元素间循环
+- **屏幕阅读器**：正确的 ARIA 属性
+- **滚动锁定**：打开时禁用 body 滚动
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/popover.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/popover.mdx
new file mode 100644
index 0000000..16cda2a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/popover.mdx
@@ -0,0 +1,178 @@
+---
+title: Popover 弹出框
+description: 在由按钮或任意自定义元素触发后，于 portal 中展示丰富内容。
+links:
+  rac: Popover
+  source: popover/popover.tsx
+  styles: popover.css
+  storybook: Components/Overlays/Popover
+---
+
+## 引入
+
+```tsx
+import { Popover } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="popover-basic"
+/>
+
+### 组件结构
+
+引入 Popover 后，可通过点语法访问各个部分。
+
+```tsx
+import { Popover } from '@heroui/react';
+
+export default () => (
+  <Popover>
+    <Popover.Trigger/>
+    <Popover.Content>
+      <Popover.Arrow />
+      <Popover.Dialog>
+        <Popover.Heading/>
+        {/* content goes here */}
+      </Popover.Dialog>
+    </Popover.Content>
+  </Popover>
+)
+```
+
+### 带箭头
+
+<ComponentPreview
+  name="popover-with-arrow"
+/>
+
+### 位置
+
+<ComponentPreview
+  name="popover-placement"
+/>
+
+### 可交互内容
+
+<ComponentPreview
+  name="popover-interactive"
+/>
+
+<RelatedComponents component="popover" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="popover-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Popover, Button } from '@heroui/react';
+
+function CustomPopover() {
+  return (
+    <Popover>
+      <Popover.Trigger>
+        <Button>Open</Button>
+      </Popover.Trigger>
+      <Popover.Content className="bg-accent text-accent-foreground">
+        <Popover.Dialog>
+          <h3>Custom Styled</h3>
+          <p>This popover has custom styling</p>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Popover 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .popover {
+    @apply rounded-xl shadow-2xl;
+  }
+
+  .popover__dialog {
+    @apply p-4;
+  }
+
+  .popover__heading {
+    @apply text-lg font-bold;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/popover.css)）：
+
+#### 基础类
+- `.popover` - Popover 根容器样式
+- `.popover__dialog` - 对话框内容包裹层
+- `.popover__heading` - 标题文本样式
+- `.popover__trigger` - 触发元素样式
+
+### 交互状态
+
+组件支持以下动画相关状态：
+
+- **进入**：`[data-entering]` — Popover 出现过程中应用
+- **离开**：`[data-exiting]` — Popover 消失过程中应用
+- **位置**：`[data-placement="*"]` — 根据 Popover 位置应用
+- **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]`
+
+## API 参考
+
+### Popover Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 触发器与内容元素 |
+| `isOpen` | `boolean` | - | 控制 Popover 是否可见（受控） |
+| `defaultOpen` | `boolean` | `false` | 初始打开状态（非受控） |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时调用 |
+
+### Popover.Content Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 在 Popover 中展示的内容 |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (及变体) | `"bottom"` | Popover 的位置 |
+| `offset` | `number` | `8` | 与触发元素的距离 |
+| `shouldFlip` | `boolean` | `true` | 是否允许 Popover 改变方向以适配空间 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### Popover.Dialog Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 对话框内容 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+
+### Popover.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 触发 Popover 的元素 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+
+### Popover.Arrow Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 自定义箭头元素 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/toast.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/toast.mdx
new file mode 100644
index 0000000..a0148e7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/toast.mdx
@@ -0,0 +1,332 @@
+---
+title: Toast 轻提示
+description: 向用户展示临时通知与消息，支持自动消失与可定制的放置位置。
+links:
+  rac: Toast
+  source: toast/toast.tsx
+  styles: toast.css
+  storybook: Components/Feedback/Toast
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Toast, toast } from '@heroui/react';
+```
+
+## 设置
+
+在应用根部渲染 Provider。
+
+```tsx
+import { Toast, Button, toast } from '@heroui/react';
+
+function App() {
+  return (
+    <div>
+      <Toast.Provider />
+      <Button onPress={() => toast("Simple message")}>
+        Show toast
+      </Button>
+    </div>
+  );
+}
+```
+
+### 用法
+
+<ComponentPreview
+  name="toast-default"
+/>
+
+### 简单 Toast
+
+<ComponentPreview
+  name="toast-simple"
+/>
+
+### 变体
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="toast-custom-indicator"
+/>
+
+### Promise 与加载中
+
+<ComponentPreview
+  name="toast-promise"
+/>
+
+### 回调
+
+<ComponentPreview
+  name="toast-callbacks"
+/>
+
+### 放置位置
+
+<ComponentPreview
+  name="toast-placements"
+/>
+
+### 自定义 Toast 渲染
+
+<ComponentPreview
+  name="toast-custom-toast"
+/>
+
+### 自定义队列
+
+<ComponentPreview
+  name="toast-custom-queue"
+/>
+
+### 组件结构
+
+```tsx
+<Toast.Provider>
+  <Toast>
+    <Toast.Indicator />
+    <Toast.Content>
+      <Toast.Title />
+      <Toast.Description />
+    </Toast.Content>
+    <Toast.ActionButton />
+    <Toast.CloseButton />
+  </Toast>
+</Toast.Provider>
+```
+
+<RelatedComponents component="toast" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+<Toast.Provider className="bottom-8 right-8" placement="bottom end" />
+```
+
+### 自定义组件类
+
+要自定义 Toast 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .toast {
+    @apply rounded-xl shadow-lg;
+  }
+
+  .toast__content {
+    @apply gap-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toast.css)）：
+
+#### 基础类
+- `.toast` — Toast 根容器
+- `.toast__region` — Toast 区域容器
+- `.toast__content` — 包裹标题与说明的内容容器
+- `.toast__indicator` — 图标/指示器容器
+- `.toast__title` — Toast 标题文本
+- `.toast__description` — Toast 说明文本
+- `.toast__action` — 操作按钮容器
+- `.toast__close` — 关闭按钮容器
+
+#### 变体类
+- `.toast--default` — 默认灰色变体
+- `.toast--accent` — 强调蓝色变体
+- `.toast--success` — 成功绿色变体
+- `.toast--warning` — 警告黄/橙色变体
+- `.toast--danger` — 危险红色变体
+
+### 交互状态
+
+组件支持多种状态：
+
+- **最前**：`[data-frontmost]` — 应用于堆叠中最上层可见的 Toast
+- **索引**：`[data-index]` — 基于 Toast 在堆叠中的位置
+- **放置**：`[data-placement="*"]` — 基于 Toast 区域的放置位置
+
+## API 参考
+
+### Toast.Provider Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `placement` | `"top start" \| "top" \| "top end" \| "bottom start" \| "bottom" \| "bottom end"` | `"bottom"` | Toast 区域的放置位置 |
+| `gap` | `number` | `12` | Toast 之间的间距（像素） |
+| `maxVisibleToasts` | `number` | `3` | 同时最多显示的 Toast 数量 |
+| `scaleFactor` | `number` | `0.05` | 堆叠 Toast 的缩放系数（0–1） |
+| `width` | `number \| string` | `460` | Toast 宽度（像素或 CSS 值） |
+| `queue` | `ToastQueue<T>` | - | 自定义 Toast 队列实例 |
+| `children` | `ReactNode \| ((props: {toast: QueuedToast<T>}) => ReactNode)` | - | 自定义渲染函数或子节点 |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Toast Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `toast` | `QueuedToast<T>` | - | 来自队列的 Toast 数据（必填） |
+| `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Toast 的视觉变体 |
+| `placement` | `ToastVariants["placement"]` | - | 放置位置（继承自 Provider） |
+| `scaleFactor` | `number` | - | 缩放系数（继承自 Provider） |
+| `className` | `string` | - | 附加的 CSS 类 |
+| `children` | `ReactNode` | - | Toast 内容（ToastContent、ToastIndicator 等） |
+
+### Toast.Content Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 内容（通常为 ToastTitle 与 ToastDescription） |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Toast.Indicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `ToastVariants["variant"]` | - | 默认图标的变体 |
+| `children` | `ReactNode` | - | 自定义指示图标（默认使用变体图标） |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Toast.Title Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 标题文本 |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Toast.Description Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 说明文本 |
+| `className` | `string` | - | 附加的 CSS 类 |
+
+### Toast.ActionButton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `ReactNode` | - | 操作按钮内容 |
+| `className` | `string` | - | 附加的 CSS 类 |
+| All `Button` props | - | - | 接受 Button 组件的全部 props |
+
+### Toast.CloseButton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 附加的 CSS 类 |
+| All `CloseButton` props | - | - | 接受 CloseButton 组件的全部 props |
+
+### ToastQueue
+
+`ToastQueue` 用于管理 `<Toast.Provider>` 的状态。状态存放在 React 之外，因此你可以在应用的任意位置触发 Toast。
+
+#### 构造选项
+
+| Option | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `maxVisibleToasts` | `number` | `3` | 同时最多显示的 Toast 数量（仅视觉） |
+| `wrapUpdate` | `(fn: () => void) => void` | - | 包裹状态更新的函数（例如用于 view transitions） |
+
+#### 方法
+
+| Method | 参数 | 返回值 | 描述 |
+|--------|------------|---------|------|
+| `add` | `(content: T, options?: ToastOptions)` | `string` | 将 Toast 加入队列，返回 Toast key |
+| `close` | `(key: string)` | `void` | 按 key 关闭 Toast |
+| `pauseAll` | `()` | `void` | 暂停所有 Toast 计时器 |
+| `resumeAll` | `()` | `void` | 恢复所有 Toast 计时器 |
+| `clear` | `()` | `void` | 关闭所有 Toast |
+| `subscribe` | `(fn: () => void)` | `() => void` | 订阅队列变化，返回取消订阅函数 |
+
+### toast 函数
+
+默认 `toast` 函数提供便捷方法用于显示 Toast：
+
+```tsx
+import { toast } from '@heroui/react';
+
+// 基础 toast（默认约 4 秒后自动消失）
+toast("Event has been created");
+
+// 变体方法（默认同样约 4 秒后自动消失）
+toast.success("File saved");
+toast.info("New update available");
+toast.warning("Please check your settings");
+toast.danger("Something went wrong");
+
+// 传入 options
+toast("Event has been created", {
+  description: "Your event has been scheduled for tomorrow",
+  variant: "default",
+  timeout: 5000, // 自定义超时：5 秒
+  onClose: () => console.log("Closed"),
+  actionProps: {
+    children: "View",
+    onPress: () => {},
+  },
+  indicator: <CustomIcon />,
+});
+
+// Promise 支持（自动显示加载指示）
+toast.promise(
+  uploadFile(),
+  {
+    loading: "Uploading file...",
+    success: (data) => `File ${data.filename} uploaded`,
+    error: "Failed to upload file",
+  }
+);
+
+// 手动加载状态（持久 toast：不自动消失）
+const loadingId = toast("Creating event...", {
+  isLoading: true,
+  timeout: 0, // 持久 toast：不自动消失
+});
+
+// 随后关闭并展示结果
+toast.close(loadingId);
+toast.success("Event created");
+
+// 队列方法
+toast.close(key);
+toast.clear();
+toast.pauseAll();
+toast.resumeAll();
+```
+
+#### toast Options
+
+| Option | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `title` | `ReactNode` | - | Toast 标题（变体方法的第一个参数） |
+| `description` | `ReactNode` | - | 可选说明文本 |
+| `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 视觉变体 |
+| `indicator` | `ReactNode` | - | 自定义指示图标（`null` 可隐藏） |
+| `actionProps` | `ButtonProps` | - | 操作按钮 props |
+| `isLoading` | `boolean` | `false` | 使用加载指示替代指示器 |
+| `timeout` | `number` | `4000` | 自动消失超时（毫秒）。默认 4000ms（4 秒）。设为 `0` 表示持久 Toast，不自动消失 |
+| `onClose` | `() => void` | - | Toast 关闭时的回调 |
+
+#### toast.promise Options
+
+| Option | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `loading` | `ReactNode` | - | Promise pending 时显示的消息 |
+| `success` | `ReactNode \| ((data: T) => ReactNode)` | - | 成功时显示的消息（可为函数） |
+| `error` | `ReactNode \| ((error: Error) => ReactNode)` | - | 失败时显示的消息（可为函数） |
diff --git a/apps/docs/content/docs/cn/react/components/(overlays)/tooltip.mdx b/apps/docs/content/docs/cn/react/components/(overlays)/tooltip.mdx
new file mode 100644
index 0000000..c18d17f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(overlays)/tooltip.mdx
@@ -0,0 +1,186 @@
+---
+title: Tooltip 工具提示
+description: 当用户悬停或聚焦某个元素时，展示提示性文本。
+icon: updated
+links:
+  rac: Tooltip
+  source: tooltip/tooltip.tsx
+  styles: tooltip.css
+  storybook: Components/Overlays/Tooltip
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Tooltip } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="tooltip-basic"
+/>
+
+### 组件结构
+
+引入 Tooltip 后，可通过点语法访问各个部分。
+
+```tsx
+import { Tooltip, Button } from '@heroui/react';
+
+export default () => (
+  <Tooltip>
+    <Tooltip.Trigger>
+      <Button>Hover for tooltip</Button>
+    </Tooltip.Trigger>
+    <Tooltip.Content>
+      <Tooltip.Arrow />
+      Helpful information about this element
+    </Tooltip.Content>
+  </Tooltip>
+)
+```
+
+### 带箭头
+
+<ComponentPreview
+  name="tooltip-with-arrow"
+/>
+
+### 位置
+
+<ComponentPreview
+  name="tooltip-placement"
+/>
+
+### 自定义触发
+
+<ComponentPreview
+  name="tooltip-custom-trigger"
+/>
+
+<RelatedComponents component="tooltip" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="tooltip-custom-render-function"
+/>
+
+## 样式
+
+### 全局延迟配置
+
+你可以通过定义 CSS 变量，为应用中所有 Tooltip 设置默认的显示与隐藏延迟：
+
+```css
+/* 在你的全局 CSS 文件中 */
+:root {
+  --tooltip-delay: 1500ms;
+  --tooltip-close-delay: 500ms;
+}
+
+/* 也可以为浅色/深色主题设置不同的值 */
+.light, [data-theme="light"] {
+  --tooltip-delay: 1200ms;
+}
+
+.dark, [data-theme="dark"] {
+  --tooltip-close-delay: 300ms;
+}
+```
+
+值支持 `ms`、`s` 等 CSS 时间单位。在单个 Tooltip 上指定 `delay` 或 `closeDelay` 时，会覆盖这些全局设置。
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Tooltip, Button } from '@heroui/react';
+
+function CustomTooltip() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content className="bg-accent text-accent-foreground">
+        <p>Custom styled tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Tooltip 的组件类名，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .tooltip {
+    @apply rounded-xl shadow-lg;
+  }
+
+  .tooltip__trigger {
+    @apply cursor-help;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。
+
+### CSS 类
+
+Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tooltip.css)）：
+
+#### 基础类
+- `.tooltip` - 带动画的基础 Tooltip 样式
+- `.tooltip__trigger` - 触发元素样式
+
+### 交互状态
+
+组件支持以下动画相关状态：
+
+- **进入**：`[data-entering]` — Tooltip 出现过程中应用
+- **离开**：`[data-exiting]` — Tooltip 消失过程中应用
+- **位置**：`[data-placement="*"]` — 根据 Tooltip 位置应用
+
+## API 参考
+
+### Tooltip Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 触发元素与内容 |
+| `delay` | `number` | `1500` 或 CSS 变量 | 显示 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-delay` CSS 变量全局配置 |
+| `closeDelay` | `number` | `500` 或 CSS 变量 | 隐藏 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-close-delay` CSS 变量全局配置 |
+| `trigger` | `"hover" \| "focus"` | `"hover"` | Tooltip 的触发方式 |
+| `isDisabled` | `boolean` | `false` | 是否禁用 Tooltip |
+
+### Tooltip.Content Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 在 Tooltip 中展示的内容 |
+| `showArrow` | `boolean` | `false` | 是否显示箭头指示器 |
+| `offset` | `number` | `3`（带箭头时为 7） | 与触发元素的距离 |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (及变体) | `"top"` | Tooltip 的位置 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
+
+### Tooltip.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 触发 Tooltip 的元素 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+
+### Tooltip.Arrow Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `children` | `React.ReactNode` | - | 自定义箭头元素 |
+| `className` | `string` | - | 额外的 CSS 类名 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 |
diff --git a/apps/docs/content/docs/cn/react/components/(pickers)/autocomplete.mdx b/apps/docs/content/docs/cn/react/components/(pickers)/autocomplete.mdx
new file mode 100644
index 0000000..16fe9c7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(pickers)/autocomplete.mdx
@@ -0,0 +1,401 @@
+---
+title: Autocomplete 自动完成
+description: 自动完成将选择与过滤结合，让用户可以搜索并从选项列表中选择。
+links:
+  rac: Select
+  source: autocomplete/autocomplete.tsx
+  styles: autocomplete.css
+  storybook: Components/Pickers/Autocomplete
+---
+
+## 引入
+
+```tsx
+import { Autocomplete, useFilter } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview name="autocomplete-default" />
+
+### 组件结构
+
+导入 Autocomplete 组件后，可通过点语法访问各个子部分。
+
+```tsx
+import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";
+
+export default () => (
+  <Autocomplete>
+    <Label />
+    <Autocomplete.Trigger>
+      <Autocomplete.Value />
+      <Autocomplete.ClearButton />
+      <Autocomplete.Indicator />
+    </Autocomplete.Trigger>
+    <Description />
+    <Autocomplete.Popover>
+      <Autocomplete.Filter>
+        <SearchField>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input />
+          </SearchField.Group>
+        </SearchField>
+        <ListBox>
+          <ListBox.Item>
+            <Label />
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Autocomplete.Filter>
+    </Autocomplete.Popover>
+  </Autocomplete>
+);
+```
+
+### 带描述
+
+<ComponentPreview name="autocomplete-with-description" />
+
+### 多选
+
+<ComponentPreview name="autocomplete-multiple-select" />
+
+### 分组
+
+<ComponentPreview name="autocomplete-with-sections" />
+
+### 含禁用选项
+
+<ComponentPreview name="autocomplete-with-disabled-options" />
+
+### 允许空集合
+
+`allowsEmptyCollection` prop 让自动完成在集合中没有任何条目时仍可使用。适用于列表初始可能为空，或过滤后没有结果等场景。
+
+<ComponentPreview name="autocomplete-allows-empty-collection" />
+
+### 自定义指示器
+
+<ComponentPreview name="autocomplete-custom-indicator" />
+
+### 必填
+
+<ComponentPreview name="autocomplete-required" />
+
+### 全宽
+
+<ComponentPreview name="autocomplete-full-width" />
+
+### 变体
+
+Autocomplete 支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影，适合用于 Surface 组件
+
+<ComponentPreview name="autocomplete-variants" />
+
+### 在 Surface 中
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="autocomplete-full-width" />
+
+### 自定义值
+
+你可以使用渲染 prop 自定义展示的值：
+
+<ComponentPreview name="autocomplete-user-selection" />
+
+### 受控
+
+<ComponentPreview name="autocomplete-controlled" />
+
+### 受控多选
+
+<ComponentPreview name="autocomplete-multiple-select" />
+
+### 受控展开状态
+
+<ComponentPreview name="autocomplete-controlled-open-state" />
+
+### 异步过滤
+
+<ComponentPreview name="autocomplete-asynchronous-filtering" />
+
+### 虚拟化
+
+Autocomplete 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见的行，从而高效展示大数据集。
+
+<ComponentPreview name="autocomplete-virtualization" />
+
+### 禁用
+
+<ComponentPreview name="autocomplete-disabled" />
+
+### 进阶示例
+
+#### 用户选择
+
+<ComponentPreview name="autocomplete-user-selection" />
+
+#### 用户多选
+
+<ComponentPreview name="autocomplete-user-selection-multiple" />
+
+#### 地点搜索
+
+<ComponentPreview name="autocomplete-location-search" />
+
+#### Tag Group 选择
+
+<ComponentPreview name="autocomplete-tag-group-selection" />
+
+#### 邮件收件人
+
+<ComponentPreview name="autocomplete-email-recipients" />
+
+<RelatedComponents component="autocomplete" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Autocomplete, SearchField, ListBox} from "@heroui/react";
+
+function CustomAutocomplete() {
+  return (
+    <Autocomplete className="w-full">
+      <Label>State</Label>
+      <Autocomplete.Trigger className="rounded-lg border bg-surface p-2">
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+              Item 1
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Autocomplete 的组件类，可使用 `@layer components` 指令。
+
+<br />
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .autocomplete {
+    @apply flex flex-col gap-1;
+  }
+
+  .autocomplete__trigger {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .autocomplete__value {
+    @apply text-current;
+  }
+
+  .autocomplete__clear-button {
+    @apply text-muted hover:text-foreground;
+  }
+
+  .autocomplete__indicator {
+    @apply text-muted;
+  }
+
+  .autocomplete__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .autocomplete__popover-dialog {
+    @apply outline-none;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Autocomplete 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)）：
+
+#### 基础类
+
+- `.autocomplete` - 自动完成根容器
+- `.autocomplete__trigger` - 触发自动完成的按钮
+- `.autocomplete__value` - 显示的值或占位符
+- `.autocomplete__clear-button` - 清除已选值的按钮
+- `.autocomplete__indicator` - 下拉指示图标
+- `.autocomplete__popover` - 弹出层容器
+- `.autocomplete__popover-dialog` - 弹出层内部的 dialog 包裹层，用于焦点管理（与 [Popover](/docs/components/popover) 行为一致）
+- `.autocomplete__filter` - 过滤区域包裹层
+
+#### 变体类
+
+- `.autocomplete--primary` - 主变体，带阴影（默认）
+- `.autocomplete--secondary` - 次变体，无阴影，适合用于 Surface
+
+#### 状态类
+
+- `.autocomplete[data-invalid="true"]` - 无效状态
+- `.autocomplete__trigger[data-focus-visible="true"]` - 触发器聚焦状态
+- `.autocomplete__trigger[data-disabled="true"]` - 触发器禁用状态
+- `.autocomplete__value[data-placeholder="true"]` - 占位符状态
+- `.autocomplete__clear-button[data-empty="true"]` - 无选中时隐藏清除按钮
+- `.autocomplete__indicator[data-open="true"]` - 展开时的指示器状态
+
+### 交互状态
+
+组件同时支持 CSS 伪类与 data 属性，便于灵活编写样式：
+
+- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：自动完成上 `:disabled` 或 `[data-disabled="true"]`
+- **展开**：指示器上 `[data-open="true"]`
+
+## API 参考
+
+### Autocomplete Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `placeholder` | `string` | `'Select an item'` | 自动完成为空时显示的占位文本 |
+| `selectionMode` | `"single" \| "multiple"` | `"single"` | 启用单选或多选 |
+| `allowsEmptyCollection` | `boolean` | `false` | 是否允许空集合。为 `true` 时，即使没有任何条目也可使用自动完成。 |
+| `isOpen` | `boolean` | - | 设置弹出层的打开状态（受控） |
+| `defaultOpen` | `boolean` | - | 设置弹出层的默认打开状态（非受控） |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时触发的事件处理函数 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用条目的 key |
+| `isDisabled` | `boolean` | - | 是否禁用自动完成 |
+| `value` | `Key \| Key[] \| null` | - | 当前值（受控） |
+| `defaultValue` | `Key \| Key[] \| null` | - | 默认值（非受控） |
+| `onChange` | `(value: Key \| Key[] \| null) => void` | - | 值变化时触发的事件处理函数 |
+| `isRequired` | `boolean` | - | 是否要求用户输入 |
+| `isInvalid` | `boolean` | - | 自动完成的值是否无效 |
+| `name` | `string` | - | 输入的 name，用于提交 HTML 表单 |
+| `fullWidth` | `boolean` | `false` | 自动完成是否占满容器宽度 |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 自动完成内容或渲染函数 |
+
+### Autocomplete.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数 |
+
+### Autocomplete.Value Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode \| RenderFunction` | - | 值区域内容或渲染函数 |
+
+### Autocomplete.Indicator Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `children` | `ReactNode` | - | 自定义指示器内容 |
+
+### Autocomplete.ClearButton Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `className` | `string` | - | 额外的 CSS 类 |
+| `onClick` | `(e: MouseEvent) => void` | - | 点击按钮时触发的事件处理函数 |
+| `ref` | `RefObject<HTMLButtonElement>` | - | 清除按钮元素的 ref |
+
+### Autocomplete.Popover Props
+
+| Prop        | 类型                                                                                                                                                                                                                                                                                                                     | 默认值    | 描述 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 弹出层相对触发器的位置 |
+| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | 额外的 CSS 类 |
+| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | 子内容。内部会包裹在 dialog 元素中以管理焦点，样式类为 `.autocomplete__popover-dialog`。 |
+
+### Autocomplete.Filter Props
+
+| Prop | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `filter` | `(text: string, input: string) => boolean` | - | 自定义过滤函数 |
+| `inputValue` | `string` | - | 受控的输入值 |
+| `onInputChange` | `(value: string) => void` | - | 输入值变化时触发的事件处理函数 |
+| `children` | `ReactNode` | - | 过滤内容（SearchField 与 ListBox） |
+
+### useFilter Hook
+
+React Aria 的 `useFilter` hook 为自动完成提供过滤函数。
+
+```tsx
+import {useFilter} from "@heroui/react";
+
+const {contains} = useFilter({sensitivity: "base"});
+
+<Autocomplete.Filter filter={contains}>
+  <SearchField>...</SearchField>
+  <ListBox>...</ListBox>
+</Autocomplete.Filter>
+```
+
+**选项：**
+
+| 选项 | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | 匹配的本地化敏感度 |
+
+**返回值：**
+
+| 函数 | 类型 | 描述 |
+| --- | --- | --- |
+| `contains` | `(string: string, substring: string) => boolean` | 判断字符串是否包含给定子串 |
+| `startsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以给定子串开头 |
+| `endsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以给定子串结尾 |
+
+### RenderProps
+
+对 `Autocomplete.Value` 使用渲染函数时，会提供以下值：
+
+| Prop | 类型 | 描述 |
+| --- | --- | --- |
+| `defaultChildren` | `ReactNode` | 默认渲染的值 |
+| `isPlaceholder` | `boolean` | 值是否为占位符 |
+| `state` | `SelectState` | 自动完成的状态 |
+| `selectedItems` | `Node[]` | 当前选中的条目 |
+
+## 无障碍
+
+Autocomplete 实现带过滤的 ARIA 选择模式，并提供：
+
+- 完整键盘导航支持
+- 选择变化时的屏幕阅读器播报
+- 与 [Popover](/docs/components/popover) 一致的焦点管理：`Autocomplete.Popover` 会在内部用 dialog 包裹内容，避免触摸交互时在弹出层 overlay 上出现多余的焦点环
+- 禁用状态支持
+- 可搜索与过滤
+- HTML 表单集成
+
+若希望在弹出层打开时不立即唤起移动端键盘，可在 `SearchField` 上设置 `autoFocus={false}`。用户聚焦搜索输入框后仍可正常过滤。
+
+更多信息见 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(pickers)/combo-box.mdx b/apps/docs/content/docs/cn/react/components/(pickers)/combo-box.mdx
new file mode 100644
index 0000000..e0150e9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(pickers)/combo-box.mdx
@@ -0,0 +1,827 @@
+---
+title: ComboBox 组合框
+description: 将文本输入与 ListBox 结合，用户可通过输入查询把选项列表过滤为匹配项。
+links:
+  rac: ComboBox
+  source: combo-box/combo-box.tsx
+  styles: combo-box.css
+  storybook: Components/Pickers/ComboBox
+---
+
+## 引入
+
+```tsx
+import { ComboBox } from '@heroui/react';
+```
+
+### 用法
+
+<ComponentPreview
+  name="combo-box-default"
+/>
+
+### 组件结构
+
+引入 ComboBox 组件并通过点语法访问所有子部分。
+
+```tsx
+import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react';
+
+export default () => (
+  <ComboBox>
+    <Label />
+    <ComboBox.InputGroup>
+      <Input />
+      <ComboBox.Trigger />
+    </ComboBox.InputGroup>
+    <Description />
+    <ComboBox.Popover>
+      <ListBox>
+        <ListBox.Item>
+          <Label />
+          <Description />
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Section>
+          <Header />
+          <ListBox.Item>
+            <Label />
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </ComboBox.Popover>
+  </ComboBox>
+)
+```
+
+### 带描述
+
+<ComponentPreview
+  name="combo-box-with-description"
+/>
+
+### 带分组
+
+<ComponentPreview
+  name="combo-box-with-sections"
+/>
+
+### 带禁用选项
+
+<ComponentPreview
+  name="combo-box-with-disabled-options"
+/>
+
+### 自定义指示器
+
+<ComponentPreview
+  name="combo-box-custom-indicator"
+/>
+
+### 必填
+
+<ComponentPreview
+  name="combo-box-required"
+/>
+
+### 自定义值
+
+<ComponentPreview
+  name="combo-box-custom-value"
+/>
+
+### 受控
+
+<ComponentPreview
+  name="combo-box-controlled"
+/>
+
+### 受控输入值
+
+<ComponentPreview
+  name="combo-box-controlled-input-value"
+/>
+
+### 异步加载
+
+<ComponentPreview
+  name="combo-box-asynchronous-loading"
+/>
+
+### 自定义过滤
+
+<ComponentPreview
+  name="combo-box-custom-filtering"
+/>
+
+### 允许自定义值
+
+<ComponentPreview
+  name="combo-box-allows-custom-value"
+/>
+
+### 禁用
+
+<ComponentPreview
+  name="combo-box-disabled"
+/>
+
+### 默认选中项
+
+<ComponentPreview
+  name="combo-box-default-selected-key"
+/>
+
+### 全宽
+
+<ComponentPreview
+  name="combo-box-full-width"
+/>
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。
+
+<ComponentPreview
+  name="combo-box-on-surface"
+/>
+
+### 菜单触发
+
+使用 `menuTrigger` prop 控制 Popover 何时打开：
+
+- `focus`（默认）：输入框获得焦点时打开 Popover
+- `input`：用户编辑输入文本时打开 Popover
+- `manual`：仅当用户按下触发按钮或使用方向键时打开 Popover
+
+<ComponentPreview
+  name="combo-box-menu-trigger"
+/>
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="combo-box-custom-render-function"
+/>
+
+<RelatedComponents component="combo-box" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { ComboBox, Input } from '@heroui/react';
+
+function CustomComboBox() {
+  return (
+    <ComboBox className="w-full">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup className="border rounded-lg p-2 bg-surface">
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger className="text-muted" />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ComboBox 组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .combo-box {
+    @apply flex flex-col gap-1;
+  }
+
+  .combo-box__input-group {
+    @apply relative inline-flex items-center;
+  }
+
+  .combo-box__trigger {
+    @apply absolute right-0 text-muted;
+  }
+
+  .combo-box__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ComboBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)）：
+
+#### 基础类
+- `.combo-box` - ComboBox 根容器
+- `.combo-box__input-group` - 输入框与触发按钮的容器
+- `.combo-box__trigger` - 打开 Popover 的按钮
+- `.combo-box__popover` - Popover 容器
+
+#### 状态类
+- `.combo-box[data-invalid="true"]` - 无效状态
+- `.combo-box[data-disabled="true"]` - 禁用状态
+- `.combo-box__trigger[data-focus-visible="true"]` - 触发器聚焦
+- `.combo-box__trigger[data-disabled="true"]` - 触发器禁用
+- `.combo-box__trigger[data-open="true"]` - 展开状态
+
+### 交互状态
+
+组件同时支持伪类与 data 属性：
+
+- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：ComboBox 上 `:disabled` 或 `[data-disabled="true"]`
+- **打开**：触发器上 `[data-open="true"]`
+
+## API 参考
+
+### ComboBox Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `inputValue` | `string` | - | 当前输入值（受控）。 |
+| `defaultInputValue` | `string` | - | 默认输入值（非受控）。 |
+| `onInputChange` | `(value: string) => void` | - | 输入值变化时调用的事件处理函数。 |
+| `selectedKey` | `Key \| null` | - | 当前选中的 key（受控）。 |
+| `defaultSelectedKey` | `Key \| null` | - | 默认选中的 key（非受控）。 |
+| `onSelectionChange` | `(key: Key \| null) => void` | - | 选中变化时调用的事件处理函数。 |
+| `isOpen` | `boolean` | - | Popover 是否打开（受控）。 |
+| `defaultOpen` | `boolean` | - | Popover 默认是否打开（非受控）。 |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Popover 打开状态变化时调用的事件处理函数。 |
+| `items` | `Iterable<T>` | - | 在 ListBox 中展示的 items。 |
+| `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 |
+| `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | 用于过滤 items 的自定义过滤函数。 |
+| `isDisabled` | `boolean` | - | 是否禁用 ComboBox。 |
+| `isReadOnly` | `boolean` | - | 输入是否可选中但不可由用户更改。 |
+| `isRequired` | `boolean` | - | 是否必填。 |
+| `isInvalid` | `boolean` | - | ComboBox 的值是否无效。 |
+| `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | 若给定值无效则返回错误信息的函数。当 `validationBehavior="native"` 时，提交表单会向用户展示校验错误；实时校验请改用 `isInvalid` prop。 |
+| `validationBehavior` | `"native" \| "aria"` | `"native"` | 使用原生 HTML 表单校验在值缺失或无效时阻止提交，还是通过 ARIA 将字段标记为必填或无效。 |
+| `name` | `string` | - | 提交 HTML 表单时 input 的 name。 |
+| `form` | `string` | - | 要关联的 `<form>` 元素 id。 |
+| `formValue` | `"text" \| "key"` | `"key"` | 在 HTML 表单提交时提交选中项的文本还是 key。当 `allowsCustomValue` 为 `true` 时该选项不适用，始终提交文本。 |
+| `autoComplete` | `string` | - | 自动完成行为类型。 |
+| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 |
+| `allowsCustomValue` | `boolean` | - | 是否允许不在列表中的自定义值。 |
+| `allowsEmptyCollection` | `boolean` | - | 是否允许空集合。 |
+| `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | 展示 ComboBox 菜单所需的交互。 |
+| `shouldFocusWrap` | `boolean` | - | 键盘导航是否循环。 |
+| `fullWidth` | `boolean` | `false` | ComboBox 是否占满容器宽度。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode \| RenderFunction` | - | ComboBox 内容或渲染函数。 |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### ComboBox.InputGroup Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | InputGroup 内容。 |
+
+### ComboBox.Trigger Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 自定义触发器内容。 |
+
+### ComboBox.Popover Props
+
+| Prop | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 相对于触发器的 Popover 位置。 |
+| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
+| `children` | `ReactNode` | - | 子内容。 |
+
+### RenderProps
+
+对 ComboBox 使用渲染函数时，会传入以下值：
+
+| Prop | 类型 | 描述 |
+|------|------|------|
+| `state` | `ComboBoxState` | ComboBox 状态。 |
+| `inputValue` | `string` | 当前输入值。 |
+| `selectedKey` | `Key \| null` | 当前选中的 key。 |
+| `selectedItem` | `Node \| null` | 当前选中的 item。 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox className="w-[256px]">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### 带分组
+
+```tsx
+import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/react';
+
+<ComboBox className="w-[256px]">
+  <Label>Country</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search countries..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Section>
+        <Header>North America</Header>
+        <ListBox.Item id="usa" textValue="United States">
+          United States
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox.Section>
+      <Separator />
+      <ListBox.Section>
+        <Header>Europe</Header>
+        <ListBox.Item id="uk" textValue="United Kingdom">
+          United Kingdom
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox.Section>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### 受控选中
+
+```tsx
+import type { Key } from '@heroui/react';
+
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledComboBox() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>('cat');
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+    >
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### 受控输入值
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledInputComboBox() {
+  const [inputValue, setInputValue] = useState('');
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      inputValue={inputValue}
+      onInputChange={setInputValue}
+    >
+      <Label>Search</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Type to search..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### 异步加载
+
+```tsx
+import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner } from '@heroui/react';
+import { useAsyncList } from '@react-stately/data';
+
+interface Character {
+  name: string;
+}
+
+function AsyncComboBox() {
+  const list = useAsyncList<Character>({
+    async load({cursor, filterText, signal}) {
+      const res = await fetch(
+        cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`,
+        { signal }
+      );
+      const json = await res.json();
+
+      return {
+        items: json.results,
+        cursor: json.next,
+      };
+    },
+  });
+
+  return (
+    <ComboBox
+      allowsEmptyCollection
+      className="w-[256px]"
+      inputValue={list.filterText}
+      onInputChange={list.setFilterText}
+    >
+      <Label>Pick a Character</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Star Wars characters..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox renderEmptyState={() => <EmptyState />}>
+          <Collection items={list.items}>
+            {(item) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="text-sm text-muted">Loading more...</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### 自定义过滤
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox
+  className="w-[256px]"
+  defaultFilter={(text, inputValue) => {
+    if (!inputValue) return true;
+    return text.toLowerCase().includes(inputValue.toLowerCase());
+  }}
+>
+  <Label>Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### 菜单触发
+
+使用 `menuTrigger` prop 控制 Popover 何时打开：
+
+```tsx
+import { ComboBox, Description, Input, Label, ListBox } from '@heroui/react';
+
+// 在聚焦时打开（默认）
+<ComboBox className="w-[256px]" menuTrigger="focus">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover opens when the input is focused</Description>
+</ComboBox>
+
+// 在输入时打开
+<ComboBox className="w-[256px]" menuTrigger="input">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover opens when the user edits the input text</Description>
+</ComboBox>
+
+// 仅手动打开
+<ComboBox className="w-[256px]" menuTrigger="manual">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover only opens when the trigger button is pressed or arrow keys are used</Description>
+</ComboBox>
+```
+
+### 表单值
+
+使用 `formValue` prop 控制提交表单时提交选中项的 key 还是文本：
+
+```tsx
+import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react';
+
+function FormValueExample() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    console.log('Submitted value:', formData.get('animal')); // Will be "cat" (the key)
+  };
+
+  return (
+    <Form onSubmit={onSubmit}>
+      {/* Submits the key (default) */}
+      <ComboBox name="animal" formValue="key" isRequired>
+        <Label>Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Select an animal..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+
+      {/* Submits the text */}
+      <ComboBox name="animal-text" formValue="text" isRequired>
+        <Label>Animal (text)</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Select an animal..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+### 校验行为
+
+使用 `validationBehavior` prop 控制校验信息的展示方式：
+
+```tsx
+import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react';
+
+function ValidationExample() {
+  return (
+    <div className="space-y-8">
+      {/* Native validation (default) - blocks form submission */}
+      <Form>
+        <ComboBox name="animal" isRequired validationBehavior="native">
+          <Label>Animal (native validation)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Select an animal..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+
+      {/* ARIA validation - shows errors in realtime, doesn't block submission */}
+      <Form>
+        <ComboBox name="animal-aria" isRequired validationBehavior="aria">
+          <Label>Animal (ARIA validation)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Select an animal..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+    </div>
+  );
+}
+```
+
+### 自定义校验
+
+使用 `validate` prop 添加自定义校验逻辑：
+
+```tsx
+import { ComboBox, FieldError, Input, Label, ListBox } from '@heroui/react';
+
+function CustomValidationExample() {
+  return (
+    <ComboBox
+      className="w-[256px]"
+      isRequired
+      validate={(value) => {
+        if (!value || value.selectedKey === null) {
+          return 'Please select an animal';
+        }
+        if (value.selectedKey === 'snake') {
+          return 'Snakes are not allowed';
+        }
+        return true;
+      }}
+    >
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <FieldError />
+    </ComboBox>
+  );
+}
+```
+
+### 只读
+
+使用 `isReadOnly` 将 ComboBox 设为只读：
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox className="w-[256px]" isReadOnly defaultSelectedKey="cat">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+## 无障碍
+
+ComboBox 实现 ARIA ComboBox 模式，并提供：
+
+- 完整键盘导航
+- 选择与输入变化时的屏幕阅读器播报
+- 合理的焦点管理
+- 禁用状态支持
+- 输入过滤（typeahead）式搜索
+- 与 HTML 表单的集成
+- 自定义值支持
+
+更多信息见 [React Aria ComboBox 文档](https://react-spectrum.adobe.com/react-aria/ComboBox.html)。
+
diff --git a/apps/docs/content/docs/cn/react/components/(pickers)/select.mdx b/apps/docs/content/docs/cn/react/components/(pickers)/select.mdx
new file mode 100644
index 0000000..5aa869b
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(pickers)/select.mdx
@@ -0,0 +1,302 @@
+---
+title: Select 选择器
+description: Select 展示可折叠的选项列表，并允许用户从中选择一项。
+links:
+  rac: Select
+  source: select/select.tsx
+  styles: select.css
+  storybook: Components/Pickers/Select
+---
+
+## 引入
+
+```tsx
+import { Select } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview name="select-default" />
+
+### 组件结构
+
+引入 Select 组件，并通过点语法访问各部分。
+
+```tsx
+import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react";
+
+export default () => (
+  <Select>
+    <Label />
+    <Select.Trigger>
+      <Select.Value />
+      <Select.Indicator />
+    </Select.Trigger>
+    <Description />
+    <Select.Popover>
+      <ListBox>
+        <ListBox.Item>
+          <Label />
+          <Description />
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Section>
+          <Header />
+          <ListBox.Item>
+            <Label />
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Select.Popover>
+  </Select>
+);
+```
+
+### 带描述
+
+<ComponentPreview name="select-with-description" />
+
+### 多选
+
+<ComponentPreview name="select-multiple-select" />
+
+### 分区
+
+<ComponentPreview name="select-with-sections" />
+
+### 含禁用项
+
+<ComponentPreview name="select-with-disabled-options" />
+
+### 自定义指示器
+
+<ComponentPreview name="select-custom-indicator" />
+
+### 必填
+
+<ComponentPreview name="select-required" />
+
+### 全宽
+
+<ComponentPreview name="select-full-width" />
+
+### 变体
+
+Select 组件支持两种视觉变体：
+
+- **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景
+- **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用
+
+<ComponentPreview name="select-variants" />
+
+### 在 Surface 内
+
+在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。
+
+<ComponentPreview name="select-on-surface" />
+
+### 自定义展示值
+
+<ComponentPreview name="select-custom-value" />
+
+### 受控
+
+<ComponentPreview name="select-controlled" />
+
+### 受控多选
+
+<ComponentPreview name="select-controlled-multiple" />
+
+### 受控展开状态
+
+<ComponentPreview name="select-controlled-open-state" />
+
+### 异步加载
+
+<ComponentPreview name="select-asynchronous-loading" />
+
+### 禁用
+
+<ComponentPreview name="select-disabled" />
+
+<RelatedComponents component="select" />
+
+### 自定义渲染函数
+
+<ComponentPreview
+  name="select-custom-render-function"
+/>
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {Select} from "@heroui/react";
+
+function CustomSelect() {
+  return (
+    <Select className="w-full">
+      <Label>State</Label>
+      <Select.Trigger className="rounded-lg border bg-surface p-2">
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 Select 组件类，可以使用 `@layer components` 指令。
+
+<br />
+[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .select {
+    @apply flex flex-col gap-1;
+  }
+
+  .select__trigger {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .select__value {
+    @apply text-current;
+  }
+
+  .select__indicator {
+    @apply text-muted;
+  }
+
+  .select__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/select.css)）：
+
+#### 基础类
+
+- `.select` - Select 根容器
+- `.select__trigger` - 打开下拉的触发按钮
+- `.select__value` - 当前显示的值或占位符
+- `.select__indicator` - 下拉指示图标
+- `.select__popover` - 弹出层容器
+
+#### 变体类
+
+- `.select--primary` - Primary 变体，带阴影（默认）
+- `.select--secondary` - Secondary 变体，无阴影，适合在 Surface 上使用
+
+#### 状态类
+
+- `.select[data-invalid="true"]` - 无效状态
+- `.select__trigger[data-focus-visible="true"]` - 触发器聚焦状态
+- `.select__trigger[data-disabled="true"]` - 触发器禁用状态
+- `.select__value[data-placeholder="true"]` - 占位符状态
+- `.select__indicator[data-open="true"]` - 展开时的指示器状态
+
+### 交互状态
+
+该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
+
+- **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]`
+- **聚焦**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]`
+- **禁用**：Select 上的 `:disabled` 或 `[data-disabled="true"]`
+- **展开**：指示器上的 `[data-open="true"]`
+
+## API 参考
+
+### Select Props
+
+| Prop            | 类型                                    | 默认值            | 描述                                              |
+| --------------- | --------------------------------------- | ----------------- | ------------------------------------------------- |
+| `placeholder`   | `string`                                | `'Select an item'` | Select 为空时显示的占位符文本。                   |
+| `selectionMode` | `"single" \| "multiple"`                | `"single"`         | 启用单选或多选。                                  |
+| `isOpen`        | `boolean`                               | -                 | 设置菜单是否打开（受控）。                        |
+| `defaultOpen`   | `boolean`                               | -                 | 设置菜单默认是否打开（非受控）。                  |
+| `onOpenChange`  | `(isOpen: boolean) => void`             | -                 | 展开状态变化时的事件处理函数。                    |
+| `disabledKeys`  | `Iterable<Key>`                         | -                 | 禁用条目的 key。                                  |
+| `isDisabled`    | `boolean`                               | -                 | Select 是否禁用。                                 |
+| `value`         | `Key \| Key[] \| null`                  | -                 | 当前值（受控）。                                  |
+| `defaultValue`  | `Key \| Key[] \| null`                  | -                 | 默认值（非受控）。                                |
+| `onChange`      | `(value: Key \| Key[] \| null) => void` | -                 | 值变化时的事件处理函数。                          |
+| `isRequired`    | `boolean`                               | -                 | 用户输入是否必填。                                |
+| `isInvalid`     | `boolean`                               | -                 | Select 的值是否无效。                             |
+| `name`          | `string`                                | -                 | 输入框名称，用于提交 HTML 表单。                  |
+| `autoComplete`  | `string`                                | -                 | 描述自动完成行为类型。                            |
+| `fullWidth`     | `boolean`                               | `false`            | Select 是否占满容器宽度。                         |
+| `variant`       | `"primary" \| "secondary"`             | `"primary"`        | 视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合在 Surface 上使用。 |
+| `className`     | `string`                                | -                 | 额外的 CSS 类。                                   |
+| `children`      | `ReactNode \| RenderFunction`           | -                 | Select 内容或渲染函数。                           |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Select.Trigger Props
+
+| Prop        | 类型                          | 默认值 | 描述                        |
+| ----------- | ----------------------------- | ------ | --------------------------- |
+| `className` | `string`                      | -      | 额外的 CSS 类。             |
+| `children`  | `ReactNode \| RenderFunction` | -      | 触发器内容或渲染函数。      |
+
+### Select.Value Props
+
+| Prop        | 类型                          | 默认值 | 描述                      |
+| ----------- | ----------------------------- | ------ | ------------------------- |
+| `className` | `string`                      | -      | 额外的 CSS 类。           |
+| `children`  | `ReactNode \| RenderFunction` | -      | 值区域内容或渲染函数。    |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectValueRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
+
+### Select.Indicator Props
+
+| Prop        | 类型        | 默认值 | 描述              |
+| ----------- | ----------- | ------ | ----------------- |
+| `className` | `string`    | -      | 额外的 CSS 类。   |
+| `children`  | `ReactNode` | -      | 自定义指示器内容。 |
+
+### Select.Popover Props
+
+| Prop        | 类型                                                                                                                                                                                                                                                                                                                     | 默认值    | 描述                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------------------------------------- |
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | 弹出层相对触发器的位置。                  |
+| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -         | 额外的 CSS 类。                           |
+| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -         | 子内容。                                  |
+
+### RenderProps
+
+对 `Select.Value` 使用渲染函数时，会提供以下值：
+
+| Prop              | 类型          | 描述                        |
+| ----------------- | ------------- | --------------------------- |
+| `defaultChildren` | `ReactNode`   | 默认渲染的值。              |
+| `isPlaceholder`   | `boolean`     | 是否为占位符状态。          |
+| `state`           | `SelectState` | Select 的状态。            |
+| `selectedItems`   | `Node[]`      | 当前已选中的条目。          |
+
+## 无障碍
+
+Select 组件实现 ARIA 列表框模式，并提供：
+
+- 完整的键盘导航支持
+- 选择变化时的屏幕阅读器播报
+- 合理的焦点管理
+- 禁用状态支持
+- 输入首字母快速定位（typeahead）
+- 与 HTML 表单的集成
+
+更多信息见 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。
diff --git a/apps/docs/content/docs/cn/react/components/(typography)/kbd.mdx b/apps/docs/content/docs/cn/react/components/(typography)/kbd.mdx
new file mode 100644
index 0000000..f5ff8ab
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(typography)/kbd.mdx
@@ -0,0 +1,157 @@
+---
+title: Kbd 键盘按键
+description: 用于展示键盘快捷键与组合键。
+links:
+  source: kbd/kbd.tsx
+  styles: kbd.css
+  storybook: Components/Typography/Kbd
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { Kbd } from "@heroui/react";
+```
+
+### 用法
+
+<ComponentPreview 
+  name="kbd-basic"
+/>
+
+### 组件结构
+
+导入 Kbd 组件后，可通过点语法访问所有子部分。
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default () => (
+  <Kbd>
+    <Kbd.Abbr title="Command">⌘</Kbd.Abbr>
+    <Kbd.Content>K</Kbd.Content>
+  </Kbd>
+);
+```
+
+### 导航键
+
+<ComponentPreview 
+  name="kbd-navigation-keys"
+/>
+
+### 行内用法
+
+<ComponentPreview 
+  name="kbd-inline-usage"
+/>
+
+### 说明性文本
+
+<ComponentPreview 
+  name="kbd-instructional-text"
+/>
+
+### 特殊键
+
+<ComponentPreview 
+  name="kbd-special-keys"
+/>
+
+### 变体
+
+<ComponentPreview 
+  name="kbd-variants"
+/>
+
+<RelatedComponents component="kbd" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+function CustomKbd() {
+  return (
+    <Kbd className="bg-gray-100 dark:bg-gray-800">
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  );
+}
+```
+
+### 自定义组件类
+
+要自定义 Kbd 的组件类，可使用 `@layer components` 指令。
+<br/>[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
+
+```css
+@layer components {
+  .kbd {
+    @apply bg-gray-100 dark:bg-gray-800 border-gray-300;
+  }
+
+  .kbd__abbr {
+    @apply font-bold;
+  }
+
+  .kbd__content {
+    @apply text-sm;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+Kbd 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)）：
+
+#### 基础类
+
+- `.kbd` — 按键基础样式（背景、边框与间距）
+- `.kbd__abbr` — 修饰键的缩写元素
+- `.kbd__content` — 按键文字的包裹层
+
+## API 参考
+
+### Kbd Props
+
+| Prop        | 类型              | 默认值    | 描述                   |
+| ----------- | ----------------- | --------- | ---------------------- |
+| `children`  | `React.ReactNode` | -         | 按键内容               |
+| `variant`   | `"default" \| "light"` | `default`       | 键盘按键的视觉变体 |
+| `className` | `string`          | -         | 自定义 CSS 类          |
+
+### Kbd.Abbr Props
+
+| Prop        | 类型              | 默认值 | 描述                                                                 |
+| ----------- | ----------------- | ------ | -------------------------------------------------------------------- |
+| `title`     | `string`          | -      | 无障碍 `title`（例如 ⌘ 对应 “Command”）                            |
+| `children`  | `React.ReactNode` | -      | 显示的符号或文本（例如 ⌘、⌥、⇧）                                   |
+| `className` | `string`          | -      | 自定义 CSS 类                                                       |
+
+### Kbd.Key Props
+
+| Prop        | 类型              | 默认值 | 描述                 |
+| ----------- | ----------------- | ------ | -------------------- |
+| `children`  | `React.ReactNode` | -      | 按键上的文本         |
+| `className` | `string`          | -      | 自定义 CSS 类        |
+
+### Kbd.Content Type
+
+`keyValue` 属性可用的按键取值：
+
+| Modifier Keys | Special Keys | Navigation Keys | Function Keys |
+| ------------- | ------------ | --------------- | ------------- |
+| `command`     | `enter`      | `up`            | `fn`          |
+| `shift`       | `delete`     | `down`          |               |
+| `ctrl`        | `escape`     | `left`          |               |
+| `option`      | `tab`        | `right`         |               |
+| `alt`         | `space`      | `pageup`        |               |
+| `win`         | `capslock`   | `pagedown`      |               |
+|               | `help`       | `home`          |               |
+|               |              | `end`           |               |
diff --git a/apps/docs/content/docs/cn/react/components/(typography)/typography.mdx b/apps/docs/content/docs/cn/react/components/(typography)/typography.mdx
new file mode 100644
index 0000000..9062bf8
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(typography)/typography.mdx
@@ -0,0 +1,73 @@
+---
+title: Typography 排版
+description: 面向标题、正文与行内代码的语义化排版原语，基于 React Aria Components 的 Text 构建。
+links:
+  source: typography/typography.tsx
+  styles: typography.css
+  storybook: Components/Typography
+---
+
+## 引入
+
+```tsx
+import {Typography} from "@heroui/react";
+```
+
+## 用法
+
+<ComponentPreview name="typography-typography-scale" />
+
+默认情况下，`Typography` 会将视觉上的 `type` 映射到对应的语义化元素。
+
+## 子组件
+
+<ComponentPreview name="typography-primitives" />
+
+- `Typography.Heading` 将 `level={1..6}` 映射为 `type="h1"` 至 `type="h6"`。
+- `Typography.Paragraph` 将 `size="base" | "sm" | "xs"` 映射为正文样式。
+- `Typography.Code` 映射为行内代码样式。
+- `Typography.Prose` 为以常规 HTML 子节点传入的富文本内容提供排版样式。
+
+## Prose
+
+<ComponentPreview name="typography-prose" />
+
+## Render Prop
+
+<ComponentPreview name="typography-render-props" />
+
+需要自定义实际渲染的元素时，可使用 React Aria Components 风格的 `render` prop。
+
+## CSS 类名
+
+### 基础类
+
+- `.typography` - 排版基础原语
+- `.typography-prose` - 富文本文章体容器
+
+### 类型类
+
+- `.typography--h1` 至 `.typography--h6`
+- `.typography--body`、`.typography--body-sm`、`.typography--body-xs`
+- `.typography--code`
+
+### 修饰类
+
+- `.typography--align-start`、`.typography--align-center`、`.typography--align-end`、`.typography--align-justify`
+- `.typography--color-default`、`.typography--color-muted`
+- `.typography--truncate`
+- `.typography--weight-normal`、`.typography--weight-medium`、`.typography--weight-semibold`、`.typography--weight-bold`
+
+## API 参考
+
+### Typography 属性
+
+| 属性       | 类型                                                                                           | 默认值     | 说明                                    |
+| ---------- | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------- |
+| `type`     | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'`    | 语义化排版样式。                     |
+| `align`    | `'start' \| 'center' \| 'end' \| 'justify'`                                                 | `'start'`   | 文本对齐。                                |
+| `color`    | `'default' \| 'muted'`                                                                        | `'default'` | 文本颜色。                                    |
+| `weight`   | `'normal' \| 'medium' \| 'semibold' \| 'bold'`                                              | -           | 字重覆盖。                          |
+| `truncate` | `boolean`                                                                                      | -           | 将文本截断为单行并显示省略号。  |
+| `render`   | `DOMRenderFunction`                                                                            | -           | 来自 React Aria 的自定义渲染函数。        |
+| `children` | `ReactNode`                                                                                    | -           | 文本内容。                                  |
diff --git a/apps/docs/content/docs/cn/react/components/(utilities)/scroll-shadow.mdx b/apps/docs/content/docs/cn/react/components/(utilities)/scroll-shadow.mdx
new file mode 100644
index 0000000..3f9bda9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/(utilities)/scroll-shadow.mdx
@@ -0,0 +1,139 @@
+---
+title: ScrollShadow 滚动阴影
+description: 通过阴影提示可滚动溢出内容，并根据滚动位置自动检测显示或隐藏。
+links:
+  source: scroll-shadow/scroll-shadow.tsx
+  styles: scroll-shadow.css
+  storybook: Components/Utilities/ScrollShadow
+  figma: true
+---
+
+## 引入
+
+```tsx
+import { ScrollShadow } from "@heroui/react";
+```
+
+## 用法
+
+<ComponentPreview name="scroll-shadow-default" />
+
+## 方向
+
+<ComponentPreview name="scroll-shadow-orientation" />
+
+## 隐藏滚动条
+
+<ComponentPreview name="scroll-shadow-hide-scroll-bar" />
+
+## 自定义阴影尺寸
+
+<ComponentPreview name="scroll-shadow-custom-size" />
+
+## 可见性变化
+
+<ComponentPreview name="scroll-shadow-visibility-change" />
+
+## 与 Card 组合
+
+<ComponentPreview name="scroll-shadow-with-card" />
+
+## 样式
+
+### 传入 Tailwind CSS 类
+
+```tsx
+import {ScrollShadow, Card} from "@heroui/react";
+
+function CustomScrollShadow() {
+  return (
+    <Card className="w-full p-0 sm:max-w-md">
+      <ScrollShadow className="max-h-[300px] p-6 bg-gradient-to-b from-purple-50 to-pink-50">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={idx}>
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+              risus hendrerit venenatis.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </Card>
+  );
+}
+```
+
+### 自定义组件类
+
+若要自定义 ScrollShadow 组件类，可以使用 `@layer components` 指令。
+<br />[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .scroll-shadow {
+    @apply rounded-xl border border-default-200;
+  }
+
+  .scroll-shadow--vertical {
+    @apply pr-2; /* Add padding for custom scrollbar styling */
+  }
+
+  .scroll-shadow--horizontal {
+    @apply pb-2;
+  }
+}
+```
+
+HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
+
+### CSS 类
+
+ScrollShadow 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/scroll-shadow.css)）：
+
+#### 基础类
+
+- `.scroll-shadow` - 根容器元素
+
+#### 方向变体
+
+- `.scroll-shadow--vertical` - 纵向滚动（默认）
+- `.scroll-shadow--horizontal` - 横向滚动
+
+#### 状态修饰符
+
+- `.scroll-shadow--hide-scrollbar` - 隐藏原生滚动条
+
+### CSS 变量
+
+ScrollShadow 组件使用 CSS 变量设置渐变遮罩尺寸，并为可见的原生滚动条保留空间：
+
+| 变量                              | 默认值                                 | 描述                                                                                                               |
+| --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--scroll-shadow-size`            | `40px`                                 | 控制渐变阴影尺寸。该值由 `size` prop 设置。                                                                         |
+| `--scroll-shadow-scrollbar-size`  | `10px`（`hideScrollBar` 时为 `0px`）   | 为原生滚动条保留一段实色遮罩区域，避免渐变覆盖滚动条。使用更宽的自定义滚动条时可以覆盖该值。                       |
+
+### Data 属性
+
+组件使用 data 属性控制阴影可见性：
+
+- **滚动状态**：`[data-top-scroll]`、`[data-bottom-scroll]`、`[data-left-scroll]`、`[data-right-scroll]` — 当内容可向对应方向滚动时应用
+- **组合状态**：`[data-top-bottom-scroll]`、`[data-left-right-scroll]` — 当内容可向两个方向滚动时应用
+- **方向**：`[data-orientation="vertical"]` 或 `[data-orientation="horizontal"]` — 表示滚动方向
+- **尺寸**：`[data-scroll-shadow-size]` — 阴影渐变尺寸数值
+
+## API 参考
+
+### ScrollShadow
+
+| Prop | 类型 | 默认值 | 描述 |
+| -------------------- | ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
+| `orientation`        | `"vertical"` \| `"horizontal"`                                                | `"vertical"` | 滚动方向                                    |
+| `variant`            | `"fade"`                                                                      | `"fade"`     | 阴影视觉效果样式                          |
+| `size`               | `number`                                                                      | `40`         | 阴影渐变尺寸（像素）                      |
+| `offset`             | `number`                                                                      | `0`          | 开始显示阴影前的滚动偏移量（像素）    |
+| `hideScrollBar`      | `boolean`                                                                     | `false`      | 是否隐藏原生滚动条                    |
+| `isEnabled`          | `boolean`                                                                     | `true`       | 是否启用滚动阴影检测              |
+| `visibility`         | `"auto"` \| `"both"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"none"` | `"auto"`     | 受控的阴影可见性                      |
+| `onVisibilityChange` | `(visibility: ScrollShadowVisibility) => void`                                | -            | 阴影可见性变化时调用的回调         |
+| `className`          | `string`                                                                      | -            | 应用到根元素上的额外 CSS 类     |
+| `children`           | `ReactNode`                                                                   | -            | 可滚动的子内容                                  |
diff --git a/apps/docs/content/docs/cn/react/components/index.mdx b/apps/docs/content/docs/cn/react/components/index.mdx
new file mode 100644
index 0000000..5713821
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/index.mdx
@@ -0,0 +1,64 @@
+---
+title: 所有组件
+description: 浏览库中所有可用组件的完整列表，更多组件正在路上。
+---
+
+## 按钮
+
+<ComponentsCategory category="Buttons" />
+
+## 集合
+
+<ComponentsCategory category="Collections" />
+
+## 颜色
+
+<ComponentsCategory category="Colors" />
+
+## 控件
+
+<ComponentsCategory category="Controls" />
+
+## 数据展示
+
+<ComponentsCategory category="Data Display" />
+
+## 日期与时间
+
+<ComponentsCategory category="Date and Time" />
+
+## 反馈
+
+<ComponentsCategory category="Feedback" />
+
+## 表单
+
+<ComponentsCategory category="Forms" />
+
+## 布局
+
+<ComponentsCategory category="Layout" />
+
+## 媒体
+
+<ComponentsCategory category="Media" />
+
+## 导航
+
+<ComponentsCategory category="Navigation" />
+
+## 浮层
+
+<ComponentsCategory category="Overlays" />
+
+## 选择器
+
+<ComponentsCategory category="Pickers" />
+
+## 排版
+
+<ComponentsCategory category="Typography" />
+
+## 工具
+
+<ComponentsCategory category="Utilities" />
diff --git a/apps/docs/content/docs/cn/react/components/meta.json b/apps/docs/content/docs/cn/react/components/meta.json
new file mode 100644
index 0000000..312856a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/components/meta.json
@@ -0,0 +1,82 @@
+{
+  "title": "组件",
+  "description": "HeroUI React 组件",
+  "root": true,
+  "icon": "circles-4-diamond",
+  "pages": [
+    "---概述---",
+    "index",
+    "---组件---",
+    "(navigation)/accordion",
+    "(feedback)/alert",
+    "(overlays)/alert-dialog",
+    "(pickers)/autocomplete",
+    "(media)/avatar",
+    "(data-display)/badge",
+    "(navigation)/breadcrumbs",
+    "(buttons)/button",
+    "(buttons)/button-group",
+    "(date-and-time)/calendar",
+    "(layout)/card",
+    "(forms)/checkbox",
+    "(forms)/checkbox-group",
+    "(data-display)/chip",
+    "(buttons)/close-button",
+    "(colors)/color-area",
+    "(colors)/color-field",
+    "(colors)/color-slider",
+    "(colors)/color-swatch",
+    "(colors)/color-swatch-picker",
+    "(colors)/color-picker",
+    "(pickers)/combo-box",
+    "(date-and-time)/date-field",
+    "(date-and-time)/date-picker",
+    "(date-and-time)/date-range-picker",
+    "(forms)/description",
+    "(navigation)/disclosure",
+    "(navigation)/disclosure-group",
+    "(overlays)/drawer",
+    "(collections)/dropdown",
+    "(forms)/error-message",
+    "(forms)/field-error",
+    "(forms)/fieldset",
+    "(forms)/form",
+    "(forms)/input",
+    "(forms)/input-group",
+    "(forms)/input-otp",
+    "(typography)/kbd",
+    "(forms)/label",
+    "(navigation)/link",
+    "(collections)/list-box",
+    "(feedback)/meter",
+    "(overlays)/modal",
+    "(forms)/number-field",
+    "(navigation)/pagination",
+    "(overlays)/popover",
+    "(feedback)/progress-bar",
+    "(feedback)/progress-circle",
+    "(forms)/radio-group",
+    "(date-and-time)/range-calendar",
+    "(utilities)/scroll-shadow",
+    "(forms)/search-field",
+    "(pickers)/select",
+    "(layout)/separator",
+    "(feedback)/skeleton",
+    "(controls)/slider",
+    "(feedback)/spinner",
+    "(layout)/surface",
+    "(controls)/switch",
+    "(data-display)/table",
+    "(navigation)/tabs",
+    "(collections)/tag-group",
+    "(typography)/typography",
+    "(forms)/text-field",
+    "(forms)/text-area",
+    "(date-and-time)/time-field",
+    "(overlays)/toast",
+    "(layout)/toolbar",
+    "(buttons)/toggle-button",
+    "(buttons)/toggle-button-group",
+    "(overlays)/tooltip"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/animation.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/animation.mdx
new file mode 100644
index 0000000..a479e41
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/animation.mdx
@@ -0,0 +1,248 @@
+---
+title: 动画
+description: 为 HeroUI v3 组件添加流畅的动画和过渡
+icon: copy-transparent
+---
+
+HeroUI 组件支持多种动画方法：内置 CSS 过渡、自定义 CSS 动画以及 Framer Motion 等 JavaScript 库。
+
+## 内置动画
+
+HeroUI 组件使用数据属性来公开其动画状态：
+
+```css
+/* Popover entrance/exit */
+.popover[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200;
+}
+
+.popover[data-exiting] {
+  @apply animate-out zoom-out-95 fade-out duration-150;
+}
+
+/* Button press effect */
+.button:active,
+.button[data-pressed="true"] {
+  transform: scale(0.97);
+}
+
+/* Accordion expansion */
+.accordion__panel[aria-hidden="false"] {
+  @apply h-[var(--panel-height)] opacity-100;
+}
+```
+
+**状态样式属性：**
+- `[data-hovered="true"]`- 悬停状态
+- `[data-pressed="true"]`- 活动/按下状态
+- `[data-focus-visible="true"]`- 键盘焦点
+- `[data-disabled="true"]`- 禁用状态
+- `[data-entering]` / `[data-exiting]`- 过渡状态
+- `[aria-expanded="true"]`- 展开状态
+
+## CSS 动画
+
+**使用 Tailwind 实用程序：**
+
+```tsx
+// Pulse on hover
+<Button className="hover:animate-pulse">
+  Hover me
+</Button>
+
+// Fade in entrance
+<Alert className="animate-fade-in">
+  Welcome message
+</Alert>
+
+// Staggered list
+<div className="space-y-2">
+  <Card className="animate-fade-in animate-delay-100">Item 1</Card>
+  <Card className="animate-fade-in animate-delay-200">Item 2</Card>
+</div>
+```
+
+**自定义过渡：**
+
+```css
+/* Slower accordion */
+.accordion__panel {
+  @apply transition-all duration-500;
+}
+
+/* Bouncy button */
+.button:active {
+  animation: bounce 0.3s;
+}
+
+@keyframes bounce {
+  50% { transform: scale(0.95); }
+}
+```
+
+## Framer Motion
+
+HeroUI 组件与 Framer Motion 无缝协作，实现高级动画。
+
+**基本用法：**
+
+```tsx
+import { motion } from 'framer-motion';
+import { Button } from '@heroui/react';
+
+const MotionButton = motion(Button);
+
+<MotionButton
+  whileHover={{ scale: 1.05 }}
+  whileTap={{ scale: 0.95 }}
+>
+  Animated Button
+</MotionButton>
+```
+
+**入口动画：**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.5 }}
+>
+  <Alert>
+    <Alert.Title>Welcome!</Alert.Title>
+  </Alert>
+</motion.div>
+```
+
+**布局动画：**
+
+```tsx
+import { AnimatePresence, motion } from 'framer-motion';
+
+function Tabs({ items, selected }) {
+  return (
+    <div className="flex gap-2">
+      {items.map((item, i) => (
+        <Button key={i} onPress={() => setSelected(i)}>
+          {item}
+          {selected === i && (
+            <motion.div
+              layoutId="active"
+              className="absolute inset-0 bg-accent"
+              transition={{ type: "spring", bounce: 0.2 }}
+            />
+          )}
+        </Button>
+      ))}
+    </div>
+  );
+}
+```
+
+## 渲染属性
+
+根据组件状态应用动态动画：
+
+```tsx
+<Button>
+  {({ isPressed, isHovered }) => (
+    <motion.span
+      animate={{
+        scale: isPressed ? 0.95 : isHovered ? 1.05 : 1
+      }}
+    >
+      Interactive Button
+    </motion.span>
+  )}
+</Button>
+```
+
+## 无障碍
+
+**尊重动态偏好：** HeroUI 使用 Tailwind 的 motion-reduce 工具自动尊重用户动态效果偏好。当用户在系统设置中启用“减少动态效果”时，所有内置的过渡和动画效果都将被禁用。
+
+HeroUI 扩展了 Tailwind 的 motion-reduce: 变体，以同时支持原生 `prefers-reduced-motion` 媒体查询和 `data-reduce-motion` 属性。
+
+```css
+/* HeroUI pattern - uses Tailwind's motion-reduce: */
+.button {
+  @apply transition-colors motion-reduce:transition-none;
+}
+
+/* Expands to support both approaches: */
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: none;
+  }
+}
+
+[data-reduce-motion="true"] .button {
+  transition: none;
+}
+```
+
+使用Framer Motion：
+
+```tsx
+import { useReducedMotion } from 'framer-motion';
+
+function AnimatedCard() {
+  const shouldReduceMotion = useReducedMotion();
+
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: shouldReduceMotion ? 0 : 0.5 }}
+    >
+      <Card>Content</Card>
+    </motion.div>
+  );
+}
+```
+
+**全局禁用动画：** 添加`data-reduce-motion="true"`到`<html>`或者`<body>`标签：
+
+```html
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations will be disabled -->
+</html>
+```
+
+HeroUI自动检测用户的`prefers-reduced-motion: reduce`相应地设置并禁用动画。
+
+## 性能技巧
+
+**使用 GPU 加速属性**： 首选`transform`和`opacity`对于流畅的动画：
+
+```css
+/* Good - GPU accelerated */
+.slide-in {
+  transform: translateX(-100%);
+  transition: transform 0.3s;
+}
+
+/* Avoid - Triggers layout */
+.slide-in {
+  left: -100%;
+  transition: left 0.3s;
+}
+```
+
+**`will-change`优化**： 使用`will-change`优化动画，但在不设置动画时将其删除：
+
+```css
+.button {
+  will-change: transform;
+}
+
+.button:not(:hover) {
+  will-change: auto;
+}
+```
+
+## 下一步
+
+- 了解[样式](/docs/handbook/styling)方法
+- 探索[组件](/docs/react/components)示例
+- 查看[主题](/docs/handbook/theming)文档
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/colors.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/colors.mdx
new file mode 100644
index 0000000..f9aee63
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/colors.mdx
@@ -0,0 +1,516 @@
+---
+title: 颜色
+description: HeroUI v3 的调色板与主题系统
+icon: bucket-paint
+links:
+  themes: true
+  tailwind: theme
+---
+
+import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";
+
+HeroUI 的颜色体系围绕语义意图构建，而非堆砌视觉色板。系统不会暴露庞大的原始色表，而是定义一小套有意义的色彩角色，覆盖绝大多数界面需求。
+
+系统中的多数颜色会由少量基础值自动派生。这样 HeroUI 能在保持对比度、层级与主题行为一致的同时，让整套体系易于理解与修改。
+
+颜色应首先传达用途与状态；视觉变化来自尺度、强调与上下文。
+
+<Callout type="info">
+  **想要创建你自己的主题？** 试试 [主题构建器](/themes)，以可视化方式自定义颜色、圆角、字体等，然后导出 CSS 用于你的项目。
+</Callout>
+
+## 强调色
+
+强调色代表品牌或产品的主识别色，用于吸引对关键操作、高亮与重点时刻的注意。
+
+强调色应有意识地节制使用。滥用会削弱其冲击力，并破坏视觉层级。多数情况下，组件会从基础强调色自动派生悬停、柔和背景与聚焦等相关取值。
+
+<ColorSectionSideBySide
+  name="强调色"
+  baseVariable="--accent"
+  baseTooltip={"--accent: oklch(0.6204 0.195 253.83)"}
+  hoverVariable="--accent"
+  hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
+  hoverTooltip={"--color-accent-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 90%,\n    var(--accent-foreground) 10%\n  )"}
+  foregroundVariable="--accent-foreground"
+  foregroundTooltip={"--accent-foreground: var(--snow)"}
+  soft={{
+    baseVariable: "--accent",
+    baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
+    baseTooltip: "--color-accent-soft:\n  color-mix(\n    in oklab,\n    var(--accent) 15%,\n    transparent\n  )",
+    hoverVariable: "--accent",
+    hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
+    hoverTooltip: "--color-accent-soft-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 20%,\n    transparent\n  )",
+    foregroundVariable: "--accent",
+    foregroundCssValue: "var(--accent)",
+    foregroundTooltip: "--color-accent-soft-foreground: var(--accent)",
+  }}
+/>
+
+## 默认（中性色）
+
+默认色构成系统的中性骨架，用于大多数非强调的界面元素。
+
+<ColorSectionSideBySide
+  name="默认"
+  baseVariable="--default"
+  baseTooltip={"--default: oklch(94% 0.001 286.375)"}
+  hoverVariable="--default"
+  hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
+  hoverTooltip={"--color-default-hover:\n  color-mix(\n    in oklab,\n    var(--default) 96%,\n    var(--default-foreground) 4%\n  )"}
+  foregroundVariable="--default-foreground"
+  foregroundTooltip={"--default-foreground: var(--eclipse)"}
+/>
+
+## 成功
+
+成功色传达积极结果、确认与完成状态，常见于反馈组件、状态指示与校验通过等场景。
+
+<ColorSectionSideBySide
+  name="成功"
+  baseVariable="--success"
+  baseTooltip={"--success: oklch(0.7329 0.1935 150.81)"}
+  hoverVariable="--success"
+  hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
+  hoverTooltip={"--color-success-hover:\n  color-mix(\n    in oklab,\n    var(--success) 90%,\n    var(--success-foreground) 10%\n  )"}
+  foregroundVariable="--success-foreground"
+  foregroundTooltip={"--success-foreground: var(--eclipse)"}
+  soft={{
+    baseVariable: "--success",
+    baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
+    baseTooltip: "--color-success-soft:\n  color-mix(\n    in oklab,\n    var(--success) 15%,\n    transparent\n  )",
+    hoverVariable: "--success",
+    hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
+    hoverTooltip: "--color-success-soft-hover:\n  color-mix(\n    in oklab,\n    var(--success) 20%,\n    transparent\n  )",
+    foregroundVariable: "--success",
+    foregroundCssValue: "var(--success)",
+    foregroundTooltip: "--color-success-soft-foreground: var(--success)",
+  }}
+/>
+
+## 警告
+
+警告色表示需谨慎、存在风险，或需要留意但非破坏性的操作，常用于提示、消息以及用户应暂停或复核信息的过渡状态。
+
+<ColorSectionSideBySide
+  name="警告"
+  baseVariable="--warning"
+  baseTooltip={"--warning: oklch(0.7819 0.1585 72.33)"}
+  hoverVariable="--warning"
+  hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
+  hoverTooltip={"--color-warning-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 90%,\n    var(--warning-foreground) 10%\n  )"}
+  foregroundVariable="--warning-foreground"
+  foregroundTooltip={"--warning-foreground: var(--eclipse)"}
+  soft={{
+    baseVariable: "--warning",
+    baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
+    baseTooltip: "--color-warning-soft:\n  color-mix(\n    in oklab,\n    var(--warning) 15%,\n    transparent\n  )",
+    hoverVariable: "--warning",
+    hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
+    hoverTooltip: "--color-warning-soft-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 20%,\n    transparent\n  )",
+    foregroundVariable: "--warning",
+    foregroundCssValue: "var(--warning)",
+    foregroundTooltip: "--color-warning-soft-foreground: var(--warning)",
+  }}
+/>
+
+## 危险
+
+危险色表示破坏性、不可逆或关键的操作与状态，应一眼可辨，并稳定用于错误、危险按钮与严重告警。
+
+<ColorSectionSideBySide
+  name="危险"
+  baseVariable="--danger"
+  baseTooltip={"--danger: oklch(0.6532 0.2328 25.74)"}
+  hoverVariable="--danger"
+  hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
+  hoverTooltip={"--color-danger-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 90%,\n    var(--danger-foreground) 10%\n  )"}
+  foregroundVariable="--danger-foreground"
+  foregroundTooltip={"--danger-foreground: var(--snow)"}
+  soft={{
+    baseVariable: "--danger",
+    baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
+    baseTooltip: "--color-danger-soft:\n  color-mix(\n    in oklab,\n    var(--danger) 15%,\n    transparent\n  )",
+    hoverVariable: "--danger",
+    hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
+    hoverTooltip: "--color-danger-soft-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 20%,\n    transparent\n  )",
+    foregroundVariable: "--danger",
+    foregroundCssValue: "var(--danger)",
+    foregroundTooltip: "--color-danger-soft-foreground: var(--danger)",
+  }}
+/>
+
+## 前景色
+
+前景色用于正文级内容，如文字与图标。这些颜色针对可读性与无障碍优化，并会随背景与表面上下文自动适配。请勿在组件内硬编码前景色。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "前景", variable: "--foreground", tooltip: "--foreground: var(--eclipse)" },
+    { label: "弱化", variable: "--muted", tooltip: "--muted: oklch(0.5517 0.0138 285.94)" },
+    { label: "分段", variable: "--segment", tooltip: "--segment: var(--white)" },
+    { label: "遮罩", variable: "--overlay", tooltip: "--overlay: var(--white)" },
+    { label: "链接", variable: "--link", tooltip: "--link: var(--foreground)" },
+  ]}
+  darkColors={[
+    { label: "前景", variable: "--foreground", border: true, tooltip: "--foreground: var(--snow)" },
+    { label: "弱化", variable: "--muted", border: true, tooltip: "--muted: oklch(70.5% 0.015 286.067)" },
+    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
+    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
+    { label: "链接", variable: "--link", border: true, tooltip: "--link: var(--foreground)" },
+  ]}
+/>
+
+## 背景色
+
+背景色定义界面的基底画布，在保持视觉克制的前提下建立整体对比与氛围。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "背景", variable: "--background", border: true, tooltip: "--background: oklch(0.9702 0 0)" },
+    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
+    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
+    { label: "反色", variable: "--foreground", tooltip: "--color-background-inverse: var(--foreground)" },
+  ]}
+  darkColors={[
+    { label: "背景", variable: "--background", border: true, tooltip: "--background: oklch(12% 0.005 285.823)" },
+    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
+    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
+    { label: "反色", variable: "--foreground", border: true, tooltip: "--color-background-inverse: var(--foreground)" },
+  ]}
+/>
+
+## 表面色
+
+表面色叠在背景之上，用于卡片、面板、模态与下拉等容器。表面通过抬升、对比与分层形成区隔与层级，而非依赖强烈的色相跳跃。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "表面", variable: "--surface", border: true, tooltip: "--surface: var(--white)" },
+    { label: "次级", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.9524 0.0013 286.37)" },
+    { label: "第三级", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.9373 0.0013 286.37)" },
+  ]}
+  darkColors={[
+    { label: "表面", variable: "--surface", border: true, tooltip: "--surface: oklch(0.2103 0.0059 285.89)" },
+    { label: "次级", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.257 0.0037 286.14)" },
+    { label: "第三级", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.2721 0.0024 247.91)" },
+  ]}
+/>
+
+## 表单字段
+
+表单字段色是面向输入、控件与可交互字段的专用令牌，覆盖默认、聚焦与悬停等多种状态。将其独立出来，可让表单元素在视觉上与按钮及界面其余部分保持清晰区分。
+
+<ColorSectionFormField
+  colors={{
+    bg: "--field-background",
+    bgTooltip: "--field-background: var(--white)",
+    bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
+    bgHoverTooltip: "--color-field-hover:\n  color-mix(\n    in oklab,\n    var(--field-background, var(--default)) 90%,\n    var(--field-foreground, var(--foreground)) 2%\n  )",
+    bgFocusTooltip: "--color-field-focus:\n  var(--field-background, var(--default))",
+    placeholder: "--field-placeholder",
+    placeholderTooltip: "--field-placeholder: var(--muted)",
+    foreground: "--field-foreground",
+    foregroundTooltip: "--field-foreground: oklch(0.2103 0.0059 285.89)",
+  }}
+/>
+
+## 分隔线
+
+分隔线色用于分割线、描边与轻量边界，用来组织内容、引导视线而不增加噪点。分隔线色应保持低对比、不抢眼。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "分隔线", variable: "--separator", border: true, tooltip: "--separator: oklch(92% 0.004 286.32)" },
+    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
+    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
+  ]}
+  darkColors={[
+    { label: "分隔线", variable: "--separator", border: true, tooltip: "--separator: oklch(25% 0.006 286.033)" },
+    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
+    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
+  ]}
+/>
+
+## 其他
+
+其他颜色在界面中承担特定工具性角色，用于组织内容、引导视线而不增加噪点。
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "边框", variable: "--border", tooltip: "--border: oklch(90% 0.004 286.32)" },
+    { label: "背衬", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.5)" },
+    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: var(--white)" },
+    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: var(--white)" },
+  ]}
+  darkColors={[
+    { label: "边框", variable: "--border", tooltip: "--border: oklch(28% 0.006 286.033)" },
+    { label: "背衬", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.6)" },
+    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
+    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
+  ]}
+/>
+
+## 基础色
+
+基础色是与模式无关的底层取值，作为语义色令牌的根基，在明暗主题之间不会改变。
+
+<ColorSectionPrimitive
+  colors={[
+    { label: "白", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
+    { label: "黑", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
+    { label: "雪白", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
+    { label: "月蚀", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
+  ]}
+/>
+
+## 如何使用颜色
+
+**在组件中：**
+```jsx
+<div className="bg-background text-foreground">
+  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
+    点击我
+  </button>
+</div>
+```
+
+**在 CSS 文件中：**
+
+```css title="global.css"
+/* 直接使用 CSS 变量 */
+.my-component {
+  background: var(--accent);
+  color: var(--accent-foreground);
+  border: 1px solid var(--border);
+}
+
+/* 配合 @apply 与 @layer */
+@layer components {
+  .button {
+    @apply bg-accent text-accent-foreground;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-accent-hover;
+    }
+
+    &:active,
+    &[data-pressed="true"] {
+      @apply bg-accent-hover;
+      transform: scale(0.97);
+    }
+  }
+}
+```
+
+## 默认主题
+
+完整主题定义见仓库中的 [variables.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css)。该主题会根据 `class="dark"` 或 `data-theme="dark"` 属性在明暗模式间自动切换。
+
+<CollapsibleCode lang="css" code={`  @layer base {
+    /* HeroUI 默认主题 */
+    :root {
+      color-scheme: light;
+
+      /* == 通用变量 == */
+
+      /* 基础色（在明暗模式下勿改动） */
+      --white: oklch(100% 0 0);
+      --black: oklch(0% 0 0);
+      --snow: oklch(0.9911 0 0);
+      --eclipse: oklch(0.2103 0.0059 285.89);
+
+      /* 间距刻度 */
+      --spacing: 0.25rem;
+
+      /* 边框 */
+      --border-width: 1px;
+      --field-border-width: 0px;
+      --disabled-opacity: 0.5;
+
+      /* 聚焦环偏移，用于聚焦环 */
+      --ring-offset-width: 2px;
+
+      /* 光标 */
+      --cursor-interactive: pointer;
+      --cursor-disabled: not-allowed;
+
+      /* 圆角 */
+      --radius: 0.5rem;
+      --field-radius: calc(var(--radius) * 1.5);
+
+      /* == 浅色主题变量 == */
+
+      /* 基础颜色 */
+      --background: oklch(0.9702 0 0);
+      --foreground: var(--eclipse);
+
+      /* 表面：用于非浮层组件（卡片、手风琴、折叠组等） */
+      --surface: var(--white);
+      --surface-foreground: var(--foreground);
+
+      /* 遮罩层：用于悬浮/浮层组件（工具提示、气泡、模态框、菜单） */
+      --overlay: var(--white);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(0.5517 0.0138 285.94);
+      --scrollbar: oklch(87.1% 0.006 286.286);
+
+      --default: oklch(94% 0.001 286.375);
+      --default-foreground: var(--eclipse);
+
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: var(--snow);
+
+      /* 表单字段默认值 - 颜色 */
+      --field-background: var(--white);
+      --field-foreground: oklch(0.2103 0.0059 285.89);
+      --field-placeholder: var(--muted);
+      --field-border: transparent; /* 表单字段默认无边框 */
+
+      /* 状态色 */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.7819 0.1585 72.33);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.6532 0.2328 25.74);
+      --danger-foreground: var(--snow);
+
+      /* 组件颜色 */
+      --segment: var(--white);
+      --segment-foreground: var(--eclipse);
+
+      /* 杂项颜色 */
+      --border: oklch(92% 0.004 286.32);
+      --separator: oklch(92% 0.004 286.32);
+      --focus: var(--accent);
+      --link: var(--foreground);
+
+      /* 背衬 */
+      --backdrop: rgba(0, 0, 0, 0.5);
+
+      /* 阴影 */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      /* 遮罩层阴影 */
+      --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      /* 骨架屏全局默认动画 */
+      --skeleton-animation: shimmer; /* shimmer, pulse, none */
+
+      /* Tooltip 默认延迟 */
+      --tooltip-delay: 1500ms;
+      --tooltip-close-delay: 500ms;
+    }
+
+    .dark,
+    [data-theme="dark"] {
+      color-scheme: dark;
+      /* == 深色主题变量 == */
+
+      /* 基础颜色 */
+      --background: oklch(12% 0.005 285.823);
+      --foreground: var(--snow);
+
+      /* 表面：用于非浮层组件（卡片、手风琴、折叠组等） */
+      --surface: oklch(0.2103 0.0059 285.89);
+      --surface-foreground: var(--foreground);
+
+      /* 遮罩层：用于悬浮/浮层组件（工具提示、气泡、模态框、菜单）——略浅于表面以提高对比度 */
+      --overlay: oklch(0.22 0.0059 285.89); /* 比表面色略浅，便于在深色模式下辨识 */
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(70.5% 0.015 286.067);
+      --scrollbar: oklch(70.5% 0.015 286.067);
+
+      --default: oklch(27.4% 0.006 286.033);
+      --default-foreground: var(--snow);
+
+      /* 表单字段默认值 - 颜色（仅列出与浅色主题不同的项） */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+
+      /* 状态色 */
+      --warning: oklch(0.8203 0.1388 76.34);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.594 0.1967 24.63);
+      --danger-foreground: var(--snow);
+
+      /* 组件颜色 */
+      --segment: oklch(0.3964 0.01 285.93);
+      --segment-foreground: var(--foreground);
+
+      /* 杂项颜色 */
+      --border: oklch(22% 0.006 286.033);
+      --separator: oklch(22% 0.006 286.033);
+      --focus: var(--accent);
+      --link: var(--foreground);
+
+      /* 背衬 */
+      --backdrop: rgba(0, 0, 0, 0.6);
+
+      /* 阴影 */
+      --surface-shadow: 0 0 0 0 transparent inset; /* 深色模式下无阴影 */
+      --overlay-shadow: 0 0 0 0 transparent inset; /* 深色模式下无阴影 */
+      --field-shadow: 0 0 0 0 transparent inset; /* 透明阴影，以便环形工具类生效 */
+    }
+  }
+`}
+/>
+
+## 自定义颜色
+
+**覆盖已有颜色：**
+
+```css
+:root {
+  /* 覆盖默认颜色 */
+  --accent: oklch(0.7 0.15 250);
+  --success: oklch(0.65 0.15 155);
+}
+
+[data-theme="dark"] {
+  /* 覆盖深色主题颜色 */
+  --accent: oklch(0.8 0.12 250);
+  --success: oklch(0.75 0.12 155);
+}
+```
+
+**提示：** 可在 [oklch.com](https://oklch.com) 转换颜色。
+
+**添加自定义颜色：**
+
+```css
+:root,
+[data-theme="light"] {
+  --info: oklch(0.6 0.15 210);
+  --info-foreground: oklch(0.98 0 0);
+}
+
+.dark,
+[data-theme="dark"] {
+  --info: oklch(0.7 0.12 210);
+  --info-foreground: oklch(0.15 0 0);
+}
+
+/* 将颜色暴露给 Tailwind */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+随后即可使用：
+
+```tsx
+<div className="bg-info text-info-foreground">提示信息</div>
+```
+
+> **注意：** 若要进一步了解主题变量及其在 Tailwind CSS v4 中的行为，请参阅 [Tailwind CSS 主题文档](https://tailwindcss.com/docs/theme)。
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/composition.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/composition.mdx
new file mode 100644
index 0000000..3653206
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/composition.mdx
@@ -0,0 +1,476 @@
+---
+title: 组合
+description: 使用组件组合模式构建灵活的 UI
+icon: layers
+---
+
+HeroUI 使用组合模式来创建灵活、可定制的组件。你可以更换渲染的元素、把组件组合在一起，并完全掌控最终的标记结构。
+
+## 与框架无关的样式
+
+HeroUI 的变体函数位于 `@heroui/styles` 包中，可以独立于 React 使用。这使得 Vue、Svelte 等其他框架也能使用 HeroUI 的设计系统：
+
+```tsx
+// Import directly from @heroui/styles (framework-agnostic)
+import { buttonVariants } from '@heroui/styles';
+
+// Or import from @heroui/react (re-exports the same functions)
+import { buttonVariants } from '@heroui/react';
+```
+
+两种导入方式的工作原理完全相同。在为非 React 框架构建，或希望避免引入 React 依赖时，请使用 `@heroui/styles`。
+
+## 多态样式
+
+使用变体函数或 BEM 类，将 HeroUI 样式应用到任何元素上。可以把组件样式扩展到框架组件、原生 HTML 元素或自定义组件，并保持完整的类型安全。
+
+**示例：将 Link 设置为按钮样式**
+
+你可以使用 `buttonVariants` 为 Link 组件应用按钮样式：
+
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+// Style a Next.js Link as a primary button
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  href="/about"
+>
+  About
+</Link>
+
+// Style a native anchor as a secondary button with custom size
+<a
+  className={buttonVariants({ variant: "secondary", size: "lg" })}
+  href="https://example.com"
+>
+  External Link
+</a>
+```
+
+**直接使用 BEM 类：**
+
+```tsx
+import Link from 'next/link';
+
+// Apply button styles directly using BEM classes
+<Link className="button button--primary" href="/about">
+  About
+</Link>
+```
+
+**配合复合组件使用**
+
+当使用自定义根元素而非 HeroUI 的 Root 组件时，子组件无法访问 context slot。你可以使用变体函数或 BEM 类，手动将 `className` 传递给子组件：
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+// With custom root - pass className manually
+const slots = linkVariants();
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+
+<NextLink className="link" href="/about">
+  About Page
+  <Link.Icon className="link__icon" />
+</NextLink>
+```
+
+这种方法之所以可行，是因为 HeroUI 的变体函数和 BEM 类可以应用到任何元素上，让你能够灵活地用 HeroUI 的设计系统为框架组件、原生元素或自定义组件设置样式。
+
+## 直接应用类名
+
+为链接或其他元素设置样式最简单的方法，就是直接使用 HeroUI 的 [BEM](https://getbem.com/) 类。这种方法简单直接，适用于任何框架或纯 HTML。
+
+**配合 Next.js Link 使用：**
+```tsx
+import Link from 'next/link';
+
+<Link className="button button--tertiary" href="/">
+  Return Home
+</Link>
+```
+
+**配合原生 anchor 使用：**
+```tsx
+<a className="button button--primary" href="/dashboard">
+  Go to Dashboard
+</a>
+```
+
+**可用的按钮类名：**
+- `.button` — 基础按钮样式
+- `.button--primary`、`.button--secondary`、`.button--tertiary`、`.button--danger`、`.button--ghost` — 变体
+- `.button--sm`、`.button--md`、`.button--lg` — 尺寸
+- `.button--icon-only` — 仅图标按钮
+
+这种方法之所以可行，是因为 HeroUI 使用了 [BEM](https://getbem.com/) 类，可以应用到任何元素上。当你不需要组件的交互功能（例如 `onPress` 事件处理器）、只想要视觉样式时，这种方式非常合适。
+
+## 使用变体函数
+
+如需更多控制和类型安全，可以使用变体函数将 HeroUI 样式应用到特定框架的组件或自定义元素上。`@heroui/styles`（与框架无关）和 `@heroui/react`（重新导出）都提供了变体函数。
+
+**配合 Next.js Link 使用：**
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+const slots = linkVariants();
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+```
+
+**配合 Button 样式：**
+
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+<Link
+  className={buttonVariants({ variant: "primary", size: "md" })}
+  href="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+**可用的变体函数：** 每个组件都从 `@heroui/styles` 导出其变体函数（`buttonVariants`、`chipVariants`、`linkVariants`、`spinnerVariants` 等）。使用它们可以在保持类型安全的同时，将 HeroUI 的设计系统应用到任何元素上。
+
+## 复合组件
+
+HeroUI 组件以复合组件的方式构建 —— 它们会导出多个协同工作的子部件。你可以通过三种灵活的方式来使用它们：
+
+**选项 1：复合模式（推荐）** — 直接使用主组件，无需 `.Root` 后缀：
+
+```tsx
+import { Alert } from '@heroui/react';
+
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+  <Alert.Close />
+</Alert>
+```
+
+**选项 2：使用 .Root 的复合模式** — 如果你喜欢显式命名，可以添加 `.Root` 后缀：
+
+```tsx
+import { Alert } from '@heroui/react';
+
+<Alert.Root>
+  <Alert.Icon />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+  <Alert.Close />
+</Alert.Root>
+```
+
+**选项 3：命名导出** — 单独导入每个部分：
+
+```tsx
+import {
+  AlertRoot,
+  AlertIcon,
+  AlertContent,
+  AlertTitle,
+  AlertDescription,
+  AlertClose
+} from '@heroui/react';
+
+<AlertRoot>
+  <AlertIcon />
+  <AlertContent>
+    <AlertTitle>Success</AlertTitle>
+    <AlertDescription>Your changes have been saved.</AlertDescription>
+  </AlertContent>
+  <AlertClose />
+</AlertRoot>
+```
+
+**混合语法：** 在同一组件中混合复合和命名导出：
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from '@heroui/react';
+
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>
+    <AlertTitle>Success</AlertTitle>
+    <AlertDescription>Your changes have been saved.</AlertDescription>
+  </Alert.Content>
+  <Alert.Close />
+</Alert>
+```
+
+**简单组件：** 像 `Button` 这样的简单组件以同样的方式工作 —— 无需 `.Root`：
+
+```tsx
+import { Button } from '@heroui/react';
+
+// Recommended - no .Root needed
+<Button>Click me</Button>
+
+// Or with .Root
+<Button.Root>Click me</Button.Root>
+
+// Or named export
+import { ButtonRoot } from '@heroui/react';
+<ButtonRoot>Click me</ButtonRoot>
+```
+
+**优点：** 这三种模式都能提供灵活性、可定制性、可控性和一致性。选择最适合你代码库的那一种即可。
+
+## 混合使用变体函数
+
+你可以组合来自不同组件的变体函数，以创建独特的样式：
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants, buttonVariants } from '@heroui/styles';
+
+// Link styled with button variants
+const buttonStyles = buttonVariants({ variant: "tertiary", size: "md" });
+
+<Link
+  className={buttonStyles}
+  href="https://heroui.com"
+>
+  HeroUI
+</Link>
+```
+
+## 自定义组件
+
+通过组合 HeroUI 原语，创建你自己的组件：
+
+```tsx
+import { Button, Tooltip } from '@heroui/react';
+import { buttonVariants } from '@heroui/styles';
+
+// Link button component using variant functions
+function LinkButton({ href, children, variant = "primary", ...props }) {
+  return (
+    <a
+      href={href}
+      className={buttonVariants({ variant, ...props })}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+}
+
+// Icon button with tooltip
+function IconButton({ icon, label, ...props }) {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button isIconOnly {...props}>
+          <Icon icon={icon} />
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>{label}</Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## 自定义变体
+
+通过扩展组件的变体函数来创建自定义变体：
+
+```tsx
+import type { ButtonRootProps } from "@heroui/react";
+import type { VariantProps } from "tailwind-variants";
+
+import { Button } from "@heroui/react";
+import { buttonVariants, tv } from "@heroui/styles";
+
+const myButtonVariants = tv({
+  extend: buttonVariants,
+  base: "text-md text-shadow-lg font-semibold shadow-md data-[pending=true]:opacity-40",
+  variants: {
+    radius: {
+      lg: "rounded-lg",
+      md: "rounded-md",
+      sm: "rounded-sm",
+      full: "rounded-full",
+    },
+    size: {
+      sm: "h-10 px-4",
+      md: "h-11 px-6",
+      lg: "h-12 px-8",
+      xl: "h-13 px-10",
+    },
+    variant: {
+      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
+    },
+  },
+  defaultVariants: {
+    radius: "full",
+    variant: "primary",
+  },
+});
+
+type MyButtonVariants = VariantProps<typeof myButtonVariants>;
+export type MyButtonProps = Omit<ButtonRootProps, "className"> &
+  MyButtonVariants & { className?: string };
+
+function CustomButton({ className, radius, variant, ...props }: MyButtonProps) {
+  return <Button className={myButtonVariants({ className, radius, variant })} {...props} />;
+}
+
+export function CustomVariants() {
+  return <CustomButton>Custom Button</CustomButton>;
+}
+```
+
+**类型引用：** 在使用组件类型时，可以使用命名类型导入或对象样式语法。
+
+**推荐 — 命名类型导入：**
+```tsx
+import type { ButtonRootProps, AvatarRootProps } from "@heroui/react";
+
+type MyButtonProps = ButtonRootProps;
+type MyAvatarProps = AvatarRootProps;
+```
+
+**替代方案 — 对象样式语法：**
+```tsx
+import { Button, Avatar } from "@heroui/react";
+
+type MyButtonProps = Button["RootProps"];
+type MyAvatarProps = Avatar["RootProps"];
+```
+
+**注意：** 不再支持 `Button.RootProps` 这种命名空间语法。请使用 `Button["RootProps"]` 或命名导入。
+
+## 自定义 DOM 元素
+
+在以下组件上使用 `render` prop，可以渲染自定义组件来代替默认的 DOM 元素。
+
+例如，你可以渲染一个 [Motion](https://motion.dev/) 按钮，并利用其状态来驱动动画。
+
+```tsx
+import {Button} from '@heroui/react';
+import {motion} from 'motion/react';
+
+<Button
+  render={(domProps, {isPressed}) => (
+    <motion.button
+      {...domProps}
+      animate={{scale: isPressed ? 0.9 : 1}} />
+  )}>
+  Press me
+</Button>
+```
+
+`render` prop 对于从客户端路由库渲染链接组件，或复用已有的展示型组件也很有用。
+
+```tsx
+import {Link} from '@heroui/react';
+import NextLink from 'next/link';
+
+<Link
+  render={({ref, ...domProps}) => (
+    <NextLink {...domProps} ref={ref as React.Ref<HTMLAnchorElement>} href="/privacy-policy" />
+  )}
+>
+  Privacy Policy
+</Link>
+```
+
+请遵循以下规则，以免破坏组件的行为和无障碍能力：
+- 始终渲染期望的元素类型（例如，如果期望的是 `<button>`，就不要渲染 `<a>`）。如果检测到不匹配，开发期间你会看到警告。
+- 只渲染单个根 DOM 元素（不要使用 fragment）。
+- 始终将传入的 props 传递给底层 DOM 元素，并根据需要通过 `mergeProps` 与你自己的 props 合并。
+
+
+## 框架集成
+
+**配合 Next.js 使用：**
+
+使用变体函数获得类型安全的样式：
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  href="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+或者直接应用 BEM 类（最简单）：
+```tsx
+import Link from 'next/link';
+
+<Link className="button button--primary" href="/dashboard">
+  Dashboard
+</Link>
+```
+
+**配合 React Router 使用：**
+
+使用变体函数：
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import { Link } from 'react-router-dom';
+
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  to="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+或者直接应用 BEM 类（最简单）：
+```tsx
+import { Link } from 'react-router-dom';
+
+<Link className="button button--primary" to="/dashboard">
+  Dashboard
+</Link>
+```
+
+**配合 Vue、Svelte 或其他框架使用：**
+
+由于 `@heroui/styles` 没有 React 依赖，你可以直接在任何框架中使用它：
+```vue
+<script setup>
+import { buttonVariants } from '@heroui/styles';
+
+const primaryButton = buttonVariants({ variant: "primary" });
+</script>
+
+<template>
+  <button :class="primaryButton">Click me</button>
+</template>
+```
+
+
+## 下一步
+
+- 了解组件的 [样式](/docs/handbook/styling)
+- 探索 [动画](/docs/handbook/animation) 选项
+- 浏览 [组件](/docs/react/components) 获取更多示例
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/dark-mode.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/dark-mode.mdx
new file mode 100644
index 0000000..55e6672
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/dark-mode.mdx
@@ -0,0 +1,243 @@
+---
+title: 深色模式
+description: 在 HeroUI v3 中添加浅色、深色以及跟随系统的主题切换
+icon: moon
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI 的深色模式由 CSS 驱动。组件会从根元素读取主题变量，因此你不需要使用 HeroUI Provider。只需在 `<html>` 上添加 `dark` 类或 `data-theme="dark"`，HeroUI 就会应用深色主题。
+
+```html
+<html class="dark" data-theme="dark">
+  <body class="bg-background text-foreground">
+    <!-- Your app -->
+  </body>
+</html>
+```
+
+请保持你的应用根元素上有 `bg-background` 与 `text-foreground` 类，这样页面画布才会随着当前主题变化。
+
+<Callout type="info">
+  HeroUI 内置的浅色和深色主题同时响应 `.light` / `.dark` 类以及 `data-theme="light"` / `data-theme="dark"` 属性。如果你手动同时设置两者，请确保它们的值保持一致。
+</Callout>
+
+## 在 Next.js 中使用 next-themes
+
+当你在 Next.js 应用中需要主题持久化、系统偏好支持，并希望在水合（hydration）前不出现闪烁时，请使用 [next-themes](https://github.com/pacocoursey/next-themes)。
+
+### 安装 next-themes
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i next-themes
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add next-themes
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add next-themes
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add next-themes
+    ```
+  </Tab>
+</Tabs>
+
+### App Router
+
+为 `next-themes` 创建一个客户端 Provider。
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import {ThemeProvider as NextThemesProvider} from "next-themes";
+
+export function Providers({children}: {children: React.ReactNode}) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}
+```
+
+在根布局中用该 Provider 包裹你的应用。请在 `<html>` 上添加 `suppressHydrationWarning`，因为 `next-themes` 会在水合之前更新该元素。
+
+```tsx
+// app/layout.tsx
+import "./globals.css";
+
+import {Providers} from "./providers";
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="bg-background text-foreground">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+### 主题切换器
+
+在客户端组件中使用 `next-themes` 提供的 `useTheme`。请等到组件挂载后再渲染，因为在 SSR 期间无法得知当前激活的主题。
+
+```tsx
+// app/components/theme-switcher.tsx
+"use client";
+
+import {Button} from "@heroui/react";
+import {useTheme} from "next-themes";
+import {useEffect, useState} from "react";
+
+export function ThemeSwitcher() {
+  const [mounted, setMounted] = useState(false);
+  const {resolvedTheme, setTheme, theme} = useTheme();
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) return null;
+
+  const activeTheme = theme === "system" ? resolvedTheme : theme;
+
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        variant={activeTheme === "light" ? "primary" : "secondary"}
+        onPress={() => setTheme("light")}
+      >
+        Light
+      </Button>
+      <Button
+        variant={activeTheme === "dark" ? "primary" : "secondary"}
+        onPress={() => setTheme("dark")}
+      >
+        Dark
+      </Button>
+      <Button variant={theme === "system" ? "primary" : "secondary"} onPress={() => setTheme("system")}>
+        System
+      </Button>
+    </div>
+  );
+}
+```
+
+### Pages Router
+
+如果使用 `pages/`，请在 `pages/_app.tsx` 中包裹你的应用。
+
+```tsx
+// pages/_app.tsx
+import "@/styles/globals.css";
+
+import type {AppProps} from "next/app";
+import {ThemeProvider as NextThemesProvider} from "next-themes";
+
+export default function App({Component, pageProps}: AppProps) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      <Component {...pageProps} />
+    </NextThemesProvider>
+  );
+}
+```
+
+## 使用自定义主题名称
+
+`attribute="class"` 这套配置非常适合内置的 `light` 和 `dark` 主题。如果你的自定义主题 CSS 是基于 `data-theme` 选择器编写的，请改为让 `next-themes` 写入 `data-theme`。
+
+```tsx
+<NextThemesProvider
+  attribute="data-theme"
+  defaultTheme="system"
+  enableSystem
+  themes={["light", "dark", "ocean", "ocean-dark"]}
+>
+  {children}
+</NextThemesProvider>
+```
+
+当你传入自定义的 `themes` 列表时，如果仍然希望保留内置主题，请将 `"light"` 和 `"dark"` 一并包含进去。
+
+## 在 React 中使用 useTheme
+
+当你正在构建一个普通的 React 应用（例如 Vite 或 Create React App），并且不需要 `next-themes` 时，可以使用 HeroUI 提供的 `useTheme` 钩子。
+
+该钩子从 `@heroui/react` 中导出。它会将当前选择的主题保存到 `localStorage`，根据用户的操作系统偏好解析 `"system"`，并同时把对应的类与 `data-theme` 属性应用到 `<html>` 上。
+
+```tsx
+// src/components/theme-switcher.tsx
+import {Button, useTheme} from "@heroui/react";
+
+export function ThemeSwitcher() {
+  const {resolvedTheme, setTheme, theme} = useTheme("system");
+
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        variant={resolvedTheme === "light" ? "primary" : "secondary"}
+        onPress={() => setTheme("light")}
+      >
+        Light
+      </Button>
+      <Button
+        variant={resolvedTheme === "dark" ? "primary" : "secondary"}
+        onPress={() => setTheme("dark")}
+      >
+        Dark
+      </Button>
+      <Button variant={theme === "system" ? "primary" : "secondary"} onPress={() => setTheme("system")}>
+        System
+      </Button>
+    </div>
+  );
+}
+```
+
+<Callout type="warning">
+  每个应用只应使用一个主题控制器。在 Next.js 中，推荐使用 `next-themes` 及其 `useTheme` 钩子；在普通的 React 应用中，请使用 `@heroui/react` 提供的 `useTheme`。
+</Callout>
+
+## 同时为两种主题设置样式
+
+主题相关的工具类会自动生效，因为它们读取的是 CSS 变量：
+
+```tsx
+<main className="min-h-screen bg-background text-foreground">
+  <section className="bg-surface text-surface-foreground shadow-surface">
+    Theme-aware content
+  </section>
+</main>
+```
+
+对于仅在深色模式下生效的一次性样式调整，请使用 `dark:` 变体：
+
+```tsx
+<div className="bg-background text-foreground dark:border-default">
+  Custom dark-mode adjustment
+</div>
+```
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/styling.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/styling.mdx
new file mode 100644
index 0000000..94bb7b7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/styling.mdx
@@ -0,0 +1,304 @@
+---
+title: 样式
+description: 使用 CSS、Tailwind 或 CSS-in-JS 为 HeroUI 组件设置样式
+icon: brush
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI 组件提供灵活的样式方案：Tailwind CSS 工具类、配合 [BEM](https://getbem.com/) 类名或数据属性的 CSS、CSS-in-JS 库，以及用于动态样式的渲染属性。
+
+## 基础样式
+
+**使用 className：** 所有 HeroUI 组件都接受 `className` 属性：
+
+```tsx
+<Button className="bg-purple-500 hover:bg-purple-600">
+  Custom Button
+</Button>
+
+<Accordion className="border-2 border-gray-200 rounded-xl">
+  {/* content */}
+</Accordion>
+```
+
+**使用 style：** 组件也接受内联样式：
+
+```tsx
+<Button style={{ backgroundColor: '#8B5CF6' }}>
+  Styled Button
+</Button>
+```
+
+## 滚动条
+
+HeroUI 的滚动插槽在组件 CSS 中使用 `@apply scrollbar`。对于你自己的溢出容器，可使用 `@heroui/styles` 提供的工具类：
+
+```tsx
+<div className="scrollbar h-64 overflow-y-auto">
+  {/* 长内容 */}
+</div>
+```
+
+| 工具类 | 效果 |
+|---------|--------|
+| `scrollbar` | HeroUI 滚动条滑块（读取主题的 `--scrollbar-*` 变量） |
+| `scrollbar-thin` | HeroUI 主题化纤细滚动条 |
+| `scrollbar-default` | 操作系统 / 浏览器默认滚动条 |
+| `scrollbar-none` | 隐藏滚动条 |
+
+全局及子树级别的控制可通过在祖先元素上使用 `data-scrollbar` 实现。有关令牌（tokens）和模式的更多信息，请参阅 [主题](/docs/handbook/theming#scrollbars)。
+
+## 基于状态的样式
+
+HeroUI 组件通过数据属性公开其状态，类似于 CSS 伪类：
+
+```css
+/* Target different states */
+.button[data-hovered="true"], .button:hover {
+  background: var(--accent-hover);
+}
+
+.button[data-pressed="true"], .button:active {
+  transform: scale(0.97);
+}
+
+.button[data-focus-visible="true"], .button:focus-visible {
+  outline: 2px solid var(--focus);
+}
+```
+
+## 渲染属性
+
+根据组件状态动态应用样式：
+
+```tsx
+// Dynamic classes
+<Button
+  className={({ isPressed }) =>
+    isPressed ? 'bg-blue-600' : 'bg-blue-500'
+  }
+>
+  Press me
+</Button>
+
+// Dynamic content
+<Button>
+  {({ isHovered, isPressed }) => (
+    <>
+      <Icon
+        icon="gravity-ui:heart"
+        className={isPressed ? 'text-red-500' : 'text-neutral-400'}
+      />
+      <span className={isHovered ? 'underline' : ''}>
+        Like
+      </span>
+    </>
+  )}
+</Button>
+```
+
+## BEM 类名
+
+HeroUI 使用 [BEM 方法论](https://getbem.com/) 来保持类名命名的一致性：
+
+```css
+/* Block */
+.button { }
+.accordion { }
+
+/* Element */
+.accordion__trigger { }
+.accordion__panel { }
+
+/* Modifier */
+.button--primary { }
+.button--lg { }
+.accordion--outline { }
+```
+
+**全局自定义组件：**
+
+```css
+/* global.css */
+
+@layer components {
+  /* Override button styles */
+  .button {
+    @apply font-semibold uppercase;
+  }
+
+  .button--primary {
+    @apply bg-indigo-600 hover:bg-indigo-700;
+  }
+
+  /* Add custom variant */
+  .button--gradient {
+    @apply bg-gradient-to-r from-purple-500 to-pink-500;
+  }
+}
+```
+
+## 创建包装组件
+
+使用 [tailwind-variants](https://tailwind-variants.org/) 创建可复用的自定义组件 —— 它是 Tailwind CSS 的一等公民变体 API：
+
+```tsx
+import { Button as HeroButton, type ButtonProps } from '@heroui/react';
+import { buttonVariants, tv, type VariantProps } from '@heroui/styles';
+
+const customButtonVariants = tv({
+  extend: buttonVariants,
+  base: 'font-medium transition-all',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500 hover:bg-blue-600 text-white',
+      secondary: 'bg-gray-200 hover:bg-gray-300',
+      danger: 'bg-red-500 hover:bg-red-600 text-white',
+    },
+    size: {
+      small: 'text-sm px-2 py-1',
+      medium: 'text-base px-4 py-2',
+      large: 'text-lg px-6 py-3',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+    size: 'medium',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+interface CustomButtonProps
+  extends Omit<ButtonProps, 'className'>,
+  CustomButtonVariants {
+  className?: string;
+}
+
+export function CustomButton({ intent, size, className, ...props }: CustomButtonProps) {
+  return (
+    <HeroButton
+      className={customButtonVariants({ intent, size, className })}
+      {...props}
+    />
+  );
+}
+```
+
+## CSS-in-JS 集成
+
+**Styled Components：**
+
+```tsx
+import styled from 'styled-components';
+import { Button } from '@heroui/react';
+
+const StyledButton = styled(Button)`
+  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
+  border-radius: 8px;
+  color: white;
+  padding: 12px 24px;
+
+  &:hover {
+    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
+  }
+`;
+```
+
+**Emotion：**
+
+```tsx
+import { css } from '@emotion/css';
+import { Button } from '@heroui/react';
+
+const buttonStyles = css`
+  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
+  border-radius: 8px;
+  color: white;
+  padding: 12px 24px;
+
+  &:hover {
+    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
+  }
+`;
+
+<Button className={buttonStyles}>
+  Emotion Button
+</Button>
+```
+
+## 响应式设计
+
+**使用 Tailwind 工具类：**
+
+```tsx
+<Button className="text-sm md:text-base lg:text-lg px-3 md:px-4 lg:px-6">
+  Responsive Button
+</Button>
+```
+
+**或者使用 CSS：**
+
+```css
+.button {
+  font-size: 0.875rem;
+  padding: 0.5rem 1rem;
+}
+
+@media (min-width: 768px) {
+  .button {
+    font-size: 1rem;
+    padding: 0.75rem 1.5rem;
+  }
+}
+```
+
+## CSS 模块
+
+如需作用域化的样式，可以使用 CSS 模块：
+
+```css
+/* Button.module.css */
+.button {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+}
+
+.button:hover {
+  transform: translateY(-2px);
+}
+
+.button--primary {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+}
+```
+
+```tsx
+import styles from './Button.module.css';
+import { Button } from '@heroui/react';
+
+<Button className={styles.button}>
+  Scoped Button
+</Button>
+```
+
+## 组件类名参考
+
+**Button：** `.button`、`.button--{variant}`、`.button--{size}`、`.button--icon-only`
+**Accordion：** `.accordion`、`.accordion__item`、`.accordion__trigger`、`.accordion__panel`、`.accordion--outline`
+
+> **注意：** 完整的类名参考请查看各组件文档：[Button](/docs/components/button#css-classes)、[Accordion](/docs/components/accordion#css-classes)
+
+所有组件的类名请查看 [@heroui/styles/components](https://github.com/heroui-inc/heroui/tree/main/packages/styles/components)。
+
+## 下一步
+
+- 了解 [动画](/docs/handbook/animation) 相关技巧
+- 探索 [主题](/docs/handbook/theming) 系统
+- 浏览 [组件](/docs/react/components) 示例
diff --git a/apps/docs/content/docs/cn/react/getting-started/(handbook)/theming.mdx b/apps/docs/content/docs/cn/react/getting-started/(handbook)/theming.mdx
new file mode 100644
index 0000000..8b8cc31
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(handbook)/theming.mdx
@@ -0,0 +1,669 @@
+---
+title: 主题
+description: 使用 CSS 变量和全局样式自定义 HeroUI 的设计系统
+icon: palette
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI 使用 CSS 变量和 [BEM](https://getbem.com/) 类来实现主题化。你可以使用标准 CSS 自定义从颜色到组件样式的所有内容。
+
+<Callout type="info">
+  **想要创建你自己的主题？** 试试 [主题构建器](/themes)，以可视化方式自定义颜色、圆角、字体等，然后导出 CSS 用于你的项目。
+</Callout>
+
+## 工作原理
+
+HeroUI 的主题系统构建于 [Tailwind CSS v4](https://tailwindcss.com/docs/theme) 的主题之上。当你导入 `@heroui/styles` 时，它会使用 Tailwind 的内置调色板，将其映射到语义化变量，自动在浅色和深色主题之间切换，并使用 CSS 层和 `@theme` 指令进行组织。
+
+**命名规则：**
+- 不带后缀的颜色用作背景（例如 `--accent`）
+- 带 `-foreground` 后缀的颜色用于该背景上的文本（例如 `--accent-foreground`）
+
+## 快速开始
+
+**应用主题：** 将主题类添加到 HTML 并将颜色应用到 body 上：
+
+```html
+<html class="light" data-theme="light">
+  <body class="bg-background text-foreground">
+    <!-- Your app -->
+  </body>
+</html>
+```
+
+**切换主题：**
+```html
+<!-- Light theme -->
+<html class="light" data-theme="light">
+
+<!-- Dark theme -->
+<html class="dark" data-theme="dark">
+```
+
+**使用 [next-themes](https://github.com/pacocoursey/next-themes) 以编程方式切换主题（适用于 Next.js）：**
+
+首先，用 `ThemeProvider` 包装你的应用：
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { ThemeProvider } from "next-themes";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="light">
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx
+import { Providers } from "./providers";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="bg-background text-foreground">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+然后使用 `useTheme` 在主题之间切换：
+
+```tsx
+"use client";
+
+import { useTheme } from "next-themes";
+
+export function ThemeSwitch() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+      Toggle {theme === "dark" ? "Light" : "Dark"} Mode
+    </button>
+  );
+}
+```
+
+**覆盖颜色：**
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+
+:root {
+  /* Override any color variable */
+  --accent: oklch(0.7 0.25 260);
+  --success: oklch(0.65 0.15 155);
+}
+```
+
+> **注意**：完整的调色板和视觉参考请参见 [颜色](/docs/handbook/colors)。
+
+> **深色模式**：如需基于 `next-themes` 与 HeroUI `useTheme` 钩子的完整配置指南，请参见 [深色模式](/docs/handbook/dark-mode)。
+
+**创建你自己的主题：**
+
+<CollapsibleCode lang="css" code={`/* src/themes/ocean.css */
+@layer base {
+    /* Ocean Light */
+    [data-theme="ocean"] {
+      color-scheme: light;
+
+      /* Primitive Colors (Do not change between light and dark) */
+      --white: oklch(100% 0 0);
+      --black: oklch(0% 0 0);
+      --snow: oklch(0.9911 0 0);
+      --eclipse: oklch(0.2103 0.0059 285.89);
+
+      /* Spacing & Layout */
+      --spacing: 0.25rem;
+      --border-width: 1px;
+      --field-border-width: 0px;
+      --disabled-opacity: 0.5;
+      --ring-offset-width: 2px;
+      --cursor-interactive: pointer;
+      --cursor-disabled: not-allowed;
+
+      /* Radius */
+      --radius: 0.75rem;
+      --field-radius: calc(var(--radius) * 1.5);
+
+      /* Base Colors */
+      --background: oklch(0.985 0.015 225);
+      --foreground: var(--eclipse);
+
+      /* Surface: Used for non-overlay components */
+      --surface: var(--white);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components */
+      --overlay: var(--white);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(0.5517 0.0138 285.94);
+
+      --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+      --scrollbar-track: transparent;
+      --scrollbar-gutter: auto;
+      --scrollbar-width: thin;
+      --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+      --scrollbar: var(--scrollbar-thumb);
+
+      --default: oklch(94% 0.001 286.375);
+      --default-foreground: var(--eclipse);
+
+      /* Ocean accent */
+      --accent: oklch(0.450 0.150 230);
+      --accent-foreground: var(--snow);
+
+      /* Form Field Defaults */
+      --field-background: var(--white);
+      --field-foreground: oklch(0.2103 0.0059 285.89);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status (kept compatible) */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.7819 0.1585 72.33);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.6532 0.2328 25.74);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: var(--white);
+      --segment-foreground: var(--foreground);
+
+      /* Misc */
+      --border: oklch(0.50 0.060 230 / 22%);
+      --separator: oklch(92% 0.004 286.32);
+      --focus: var(--accent);
+      --link: var(--accent);
+
+      /* Shadows */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+
+      /* Skeleton Default Global Animation */
+      --skeleton-animation: shimmer; /* Possible values: shimmer, pulse, none */
+
+      /* Tooltip Default Delays */
+      --tooltip-delay: 1500ms;
+      --tooltip-close-delay: 500ms;
+    }
+
+    /* Ocean Dark */
+    [data-theme="ocean-dark"] {
+      color-scheme: dark;
+
+      /* Base Colors */
+      --background: oklch(0.140 0.020 230);
+      --foreground: var(--snow);
+
+      /* Surface: Used for non-overlay components */
+      --surface: oklch(0.2103 0.0059 285.89);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components */
+      --overlay: oklch(0.22 0.0059 285.89);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(70.5% 0.015 286.067);
+
+      --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+      --scrollbar-track: transparent;
+      --scrollbar-gutter: auto;
+      --scrollbar-width: thin;
+      --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+      --scrollbar: var(--scrollbar-thumb);
+
+      --default: oklch(27.4% 0.006 286.033);
+      --default-foreground: var(--snow);
+
+      /* Form Field Defaults */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+
+      /* Ocean accent */
+      --accent: oklch(0.860 0.080 230);
+      --accent-foreground: var(--eclipse);
+
+      /* Status */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.8203 0.1388 76.34);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.594 0.1967 24.63);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: oklch(0.3964 0.01 285.93);
+      --segment-foreground: var(--foreground);
+
+      /* Misc */
+      --border: oklch(22% 0.006 286.033);
+      --separator: oklch(22% 0.006 286.033);
+      --focus: var(--accent);
+      --link: var(--accent);
+
+      /* Shadows */
+      --surface-shadow: 0 0 0 0 transparent inset;
+      --overlay-shadow: 0 0 0 0 transparent inset;
+      --field-shadow: 0 0 0 0 transparent inset;
+    }
+}
+`}
+/>
+
+使用你的主题：
+
+```css
+/* app/globals.css */
+@layer theme, base, components, utilities;
+
+@import "tailwindcss";
+@import "@heroui/styles";
+
+@import "./src/themes/ocean.css" layer(theme); /* [!code highlight]*/
+```
+
+应用你的主题：
+
+```html
+<!-- index.html -->
+
+<!-- Light ocean -->
+<html data-theme="ocean">
+
+<!-- Dark ocean -->
+<html data-theme="ocean-dark">
+```
+
+## 自定义组件
+
+**全局组件样式：** 使用 BEM 类覆盖任何组件：
+
+```css
+@layer components {
+  /* Customize buttons */
+  .button {
+    @apply font-semibold tracking-wide;
+  }
+
+  .button--primary {
+    @apply bg-blue-600 hover:bg-blue-700;
+  }
+
+  /* Customize accordions */
+  .accordion__trigger {
+    @apply text-lg font-bold;
+  }
+}
+```
+
+> **注意**：完整的样式参考请参见 [样式](/docs/handbook/styling)。
+
+**查找组件类名：** 每个组件文档页面都会列出所有可用的类名（基类、修饰符、元素、状态）。示例：[Button 类名](/docs/components/button#css-classes)
+
+## 导入策略
+
+**完整导入（推荐）：** 两行代码即可获得全部内容：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+**按需导入：** 只导入你需要的内容：
+
+```css
+/* Define layers */
+@layer theme, base, components, utilities;
+
+/* Base requirements */
+@import "tailwindcss";
+@import "@heroui/styles/base" layer(base);
+/* OR specific base file */
+@import "@heroui/styles/base/base.css" layer(base);
+
+/* Theme variables */
+@import "@heroui/styles/themes/shared/theme.css" layer(theme);
+@import "@heroui/styles/themes/default" layer(theme);
+/* OR specific theme files */
+@import "@heroui/styles/themes/default/index.css" layer(theme);
+@import "@heroui/styles/themes/default/variables.css" layer(theme);
+
+/* Components (all components) */
+@import "@heroui/styles/components" layer(components);
+/* OR specific component files */
+@import "@heroui/styles/components/index.css" layer(components);
+@import "@heroui/styles/components/button.css" layer(components);
+@import "@heroui/styles/components/accordion.css" layer(components);
+
+/* Utilities (optional) */
+@import "@heroui/styles/utilities" layer(utilities);
+
+/* Variants (optional) */
+@import "@heroui/styles/variants" layer(utilities);
+```
+
+> **注意**：目录导入（例如 `@heroui/styles/components`）会自动解析为其对应的 `index.css` 文件。使用显式文件路径（例如 `@heroui/styles/components/button.css`）来导入单个组件的样式。
+
+**Headless 模式：** 从头开始构建你自己的样式：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles/base/base.css";
+
+/* Your custom styles */
+.button {
+  /* Your button styles */
+}
+```
+
+## 添加自定义颜色
+
+将你自己的语义化颜色添加到主题中：
+
+```css
+/* Define in both light and dark themes */
+:root,
+[data-theme="light"] {
+  --info: oklch(0.6 0.15 210);
+  --info-foreground: oklch(0.98 0 0);
+}
+
+.dark,
+[data-theme="dark"] {
+  --info: oklch(0.7 0.12 210);
+  --info-foreground: oklch(0.15 0 0);
+}
+
+/* Make the color available to Tailwind */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+现在你可以在组件中使用它：
+
+```tsx
+<div className="bg-info text-info-foreground">Info message</div>
+```
+
+## 变量参考
+
+HeroUI 在 [`variables.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css) 中定义了三种类型的变量：
+
+1. **基础变量（Base Variables）** — 不会变化的值，例如 `--white`、`--black`、间距以及排版
+2. **主题变量（Theme Variables）** — 在浅色 / 深色主题之间切换的颜色，以及滚动条令牌（`--scrollbar-thumb`、`--scrollbar-width` 等）
+3. **计算变量（Calculated Variables）** — 悬停状态、柔和（soft）变体以及边框 / 分隔线层级（每个浅色 / 深色主题中的 **Calculated Colors** 区块，使用 `color-mix()` 计算）
+
+如需完整参考，请查阅：[颜色文档](/docs/handbook/colors)、[默认主题变量](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css)、[共享主题工具](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/shared/theme.css)
+
+**Tailwind 主题桥接（`@theme inline`）：**
+
+[`themes/shared/theme.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/shared/theme.css) 将语义化变量映射为 Tailwind 令牌（`--color-*`、`--radius-*`、`--ease-*`）。计算颜色引用的是 `variables.css` 中的底层变量（例如 `--surface-hover`、`--accent-soft`）—— 它们并不会在该文件中通过 `color-mix()` 内联展开：
+<CollapsibleCode lang="css" code={`  @theme inline {
+    --color-background: var(--background);
+    --color-foreground: var(--foreground);
+
+    --color-surface: var(--surface);
+    --color-surface-foreground: var(--surface-foreground);
+    --color-surface-hover: var(--surface-hover);
+
+    --color-surface-secondary: var(--surface-secondary);
+    --color-surface-secondary-foreground: var(--surface-secondary-foreground);
+
+    --color-surface-tertiary: var(--surface-tertiary);
+    --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
+
+    --color-overlay: var(--overlay);
+    --color-overlay-foreground: var(--overlay-foreground);
+
+    --color-muted: var(--muted);
+
+    --color-accent: var(--accent);
+    --color-accent-foreground: var(--accent-foreground);
+
+    --color-segment: var(--segment);
+    --color-segment-foreground: var(--segment-foreground);
+
+    --color-border: var(--border);
+    --color-separator: var(--separator);
+    --color-focus: var(--focus);
+    --color-link: var(--link);
+
+    --color-default: var(--default);
+    --color-default-foreground: var(--default-foreground);
+
+    --color-success: var(--success);
+    --color-success-foreground: var(--success-foreground);
+
+    --color-warning: var(--warning);
+    --color-warning-foreground: var(--warning-foreground);
+
+    --color-danger: var(--danger);
+    --color-danger-foreground: var(--danger-foreground);
+
+    --color-backdrop: var(--backdrop);
+
+    --shadow-surface: var(--surface-shadow);
+    --shadow-overlay: var(--overlay-shadow);
+    --shadow-field: var(--field-shadow);
+
+    /* 表单字段令牌 */
+    --color-field: var(--field-background, var(--default));
+    --color-field-hover: var(--field-hover);
+    --color-field-foreground: var(--field-foreground, var(--foreground));
+    --color-field-placeholder: var(--field-placeholder, var(--muted));
+    --color-field-border: var(--field-border, var(--border));
+    --radius-field: var(--field-radius, calc(var(--radius) * 1.5));
+    --border-width-field: var(--field-border-width, var(--border-width));
+
+    /* 颜色令牌 */
+    --color-background-secondary: var(--background-secondary);
+    --color-background-tertiary: var(--background-tertiary);
+    --color-background-inverse: var(--background-inverse);
+
+    --color-default-hover: var(--default-hover);
+    --color-accent-hover: var(--accent-hover);
+    --color-success-hover: var(--success-hover);
+    --color-warning-hover: var(--warning-hover);
+    --color-danger-hover: var(--danger-hover);
+
+    /* 表单字段颜色 */
+    --color-field-focus: var(--field-focus);
+    --color-field-border-hover: var(--field-border-hover);
+    --color-field-border-focus: var(--field-border-focus);
+
+    /* 柔和（Soft）颜色 */
+    --color-default-soft: var(--default-soft);
+    --color-default-soft-foreground: var(--default-soft-foreground);
+    --color-default-soft-hover: var(--default-soft-hover);
+
+    --color-accent-soft: var(--accent-soft);
+    --color-accent-soft-foreground: var(--accent-soft-foreground);
+    --color-accent-soft-hover: var(--accent-soft-hover);
+
+    --color-danger-soft: var(--danger-soft);
+    --color-danger-soft-foreground: var(--danger-soft-foreground);
+    --color-danger-soft-hover: var(--danger-soft-hover);
+
+    --color-warning-soft: var(--warning-soft);
+    --color-warning-soft-foreground: var(--warning-soft-foreground);
+    --color-warning-soft-hover: var(--warning-soft-hover);
+
+    --color-success-soft: var(--success-soft);
+    --color-success-soft-foreground: var(--success-soft-foreground);
+    --color-success-soft-hover: var(--success-soft-hover);
+
+    /* 分隔线颜色 - 层级 */
+    --color-separator-secondary: var(--separator-secondary);
+    --color-separator-tertiary: var(--separator-tertiary);
+
+    /* 边框颜色 - 层级 */
+    --color-border-secondary: var(--border-secondary);
+    --color-border-tertiary: var(--border-tertiary);
+
+    /* 圆角与默认尺寸 - 只需更改 --radius 即可调整默认值 */
+    --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
+    --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
+    --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
+    --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
+    --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
+    --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
+    --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
+    --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
+
+    /* 过渡缓动函数 */
+    --ease-smooth: ease; /* 等同于 transition: ease; */
+    /* 这些自定义曲线由 https://twitter.com/bdc 制作 */
+
+    /* 由平缓到快速 */
+    --ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
+    --ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
+    --ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
+    --ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
+    --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+    --ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);
+    /* 由慢到快 */
+    --ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+    --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
+    --ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
+    --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
+    --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+    --ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
+    /* 自定义的平滑收尾曲线：快速启动、平滑结束 —— Apple 风格 */
+    --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
+    /* 由慢到快 */
+    --ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+    --ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
+    --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
+    --ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
+    --ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
+    --ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
+
+    /* 线性 */
+    --ease-linear: linear;
+
+    /* 动画 */
+    --animate-spin-fast: spin 0.75s linear infinite;
+    --animate-skeleton: skeleton 2s linear infinite;
+    --animate-caret-blink: caret-blink 1.2s ease-out infinite;
+
+    @keyframes skeleton {
+      100% {
+        transform: translateX(200%);
+      }
+    }
+
+    @keyframes caret-blink {
+      0%,
+      70%,
+      100% {
+        opacity: 1;
+      }
+      20%,
+      50% {
+        opacity: 0;
+      }
+    }
+  }
+`}
+/>
+
+表单控件依赖 `--field-*` 主题变量。悬停、聚焦及边框变体定义于 `variables.css` 的 **Calculated Colors** 区块中，并在 `theme.css` 中映射到 Tailwind 令牌（例如 `--color-field-hover: var(--field-hover)`）。在你的主题中覆盖 `--field-background`、`--field-hover` 及相关令牌，即可重新设计输入框、复选框、单选框和 OTP 输入槽的样式，而不会影响按钮或卡片等表面（surface）。
+
+## 滚动条
+
+HeroUI 为组件中的滚动区域（表格、弹出框、抽屉等）应用统一的滚动条样式。滚动条使用标准 CSS 属性（`scrollbar-width`、`scrollbar-color`、`scrollbar-gutter`），不再依赖 `::-webkit-scrollbar` 覆盖。
+
+**模式** — 在 `<html>`、组件根元素或滚动插槽上设置 `data-scrollbar`：
+
+| 模式 | `data-scrollbar` | 行为 |
+|------|------------------|------|
+| HeroUI 纤细 | *（未设置）* 或 `thin` | 使用主题令牌呈现的纤细滑块 |
+| 操作系统 / 浏览器 | `default` | 原生滚动条（`auto`） |
+| 隐藏 | `none` | 不显示滚动条（`scrollbar-width: none`） |
+
+```html
+<!-- 全局使用原生滚动条 -->
+<html data-scrollbar="default">
+
+<!-- 在某个子树中恢复 HeroUI 滚动条 -->
+<main data-scrollbar="thin">
+  ...
+</main>
+
+<!-- 在某个子树中隐藏滚动条（例如弹出框） -->
+<div data-scrollbar="none">
+  ...
+</div>
+```
+
+**主题变量** — 在 [`variables.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css) 的浅色与深色主题区块中定义：
+
+| 变量 | 描述 |
+|------|------|
+| `--scrollbar-thumb` | 滑块颜色（默认通过 `color-mix` 混入 15% 的 `--foreground`） |
+| `--scrollbar-track` | 轨道颜色（默认 `transparent`） |
+| `--scrollbar-gutter` | 滚动条间隙（默认 `auto`） |
+| `--scrollbar-width` | `scrollbar-width` 属性（默认 `thin`） |
+| `--scrollbar-color` | `scrollbar-color` 属性（默认为滑块颜色 + 轨道颜色） |
+| `--scrollbar` | `--scrollbar-thumb` 的旧版别名 |
+
+**全局自定义：**
+
+```css
+/* app/globals.css */
+:root {
+  --scrollbar-thumb: color-mix(in oklch, var(--accent) 30%, transparent);
+  --scrollbar-gutter: auto;
+}
+```
+
+**按滚动插槽** — 在组件上传入 `data-scrollbar`，或在外层包裹元素上覆盖相关令牌：
+
+```tsx
+<Table data-scrollbar="default">
+  ...
+</Table>
+
+<Drawer.Content data-scrollbar="thin" />
+
+<Calendar.YearPickerGrid data-scrollbar="none" />
+```
+
+**自定义溢出区域** — 在自己的元素上使用 `@heroui/styles` 提供的 `scrollbar`、`scrollbar-thin`、`scrollbar-default` 或 `scrollbar-none` 工具类。基于类的覆盖方式详见 [样式](/docs/handbook/styling)。
+
+> **注意**：部分组件默认隐藏滚动条（日期选择器弹出框、颜色选择器、次级标签页）。嵌套的滚动插槽（例如日期选择器内部的日历年份选择器）会保留 HeroUI 滚动条，因为 `scrollbar-none` 只作用于其所在的元素本身，不会影响使用 `@apply scrollbar` 的后代元素。
+
+## 资源
+
+- [颜色文档](/docs/handbook/colors)
+- [样式指南](/docs/handbook/styling)
+- [Tailwind CSS v4 主题](https://tailwindcss.com/docs/theme)
+- [BEM 方法论](https://getbem.com/)
+- [OKLCH 颜色工具](https://oklch.com)
diff --git a/apps/docs/content/docs/cn/react/getting-started/(overview)/cli.mdx b/apps/docs/content/docs/cn/react/getting-started/(overview)/cli.mdx
new file mode 100644
index 0000000..248ad96
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(overview)/cli.mdx
@@ -0,0 +1,417 @@
+---
+title: 命令行
+description: 使用命令行管理 HeroUI 依赖并初始化项目。
+icon: terminal
+---
+
+`heroui-cli`是官方命令行工具，提供了一整套命令，用于初始化、管理和优化你的 HeroUI 项目。你可以 `install`、`uninstall` 或 `upgrade` 单个组件，检查项目健康状况，下载用于 AI 编程助手的文档，等等。
+
+## 安装
+
+环境要求：
+
+- [Node.js 22.22.0 或更高版本](https://nodejs.org/en/)
+
+
+### 全局安装
+
+要全局安装 `heroui-cli`，请在终端中执行以下命令之一：
+
+
+```npm
+npm install heroui-cli@latest -g
+```
+
+### 无需安装直接使用
+
+或者，你也可以在不进行全局安装的情况下使用 `heroui-cli`，运行以下命令之一即可：
+
+<Tabs items={["pnpm", "npm", "yarn", "bun"]}>
+  <Tab value="pnpm">
+    ```bash
+    pnpm dlx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="npm">
+    ```bash
+    npx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn dlx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bunx heroui-cli@latest
+    ```
+  </Tab>
+</Tabs>
+
+## 快速开始
+
+安装 `heroui-cli` 后，运行以下命令以查看可用命令：
+
+```bash
+heroui
+```
+
+将会输出如下帮助信息：
+
+```bash
+Usage: heroui [command]
+
+Options:
+  -v, --version                  Output the current version
+  --no-cache                     Disable cache, by default data will be cached for 30m after the first request
+  -d, --debug                    Debug mode will not install dependencies
+  -h --help                      Display help information for commands
+
+Commands:
+  init [options] [projectName]   Initializes a new project
+  install [options]              Installs @heroui/react and @heroui/styles to your project
+  upgrade [options]              Upgrades @heroui/react and @heroui/styles to the latest versions
+  uninstall [options]            Uninstall @heroui/react and @heroui/styles from the project
+  list [options]                 Lists installed HeroUI packages (@heroui/react, @heroui/styles)
+  env [options]                  Displays debugging information for the local environment
+  doctor [options]               Checks for issues in the project
+  agents-md [options]            Downloads HeroUI documentation for AI coding agents
+  help [command]                 Display help for command
+```
+
+### init
+
+使用 `init` 命令初始化一个新的 HeroUI 项目。该命令会为你的项目完成必要的配置。
+
+```bash
+heroui init [options]
+```
+
+**选项：**
+
+- `-t --template [string]` 新项目使用的模板，例如 app、pages、vite、react-router
+- `-p --package [string]` 新项目使用的包管理器
+
+输出：
+
+```bash
+HeroUI CLI <version>
+
+┌  Create a new project
+│
+◇  Select a template (Enter to select)
+│  ● App (A Next.js 16 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ Pages (A Next.js 16 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ Vite (A Vite template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ React Router (A React Router template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│
+◇  New project name (Enter to skip with default name)
+│  my-heroui-app
+│
+◇  Select a package manager (Enter to select)
+│  ● npm
+│  ○ yarn
+│  ○ pnpm
+│  ○ bun
+│
+◇  Template created successfully!
+│
+◇  Next steps ───────╮
+│                    │
+│  cd my-heroui-app  │
+│  npm install       │
+│                    │
+├────────────────────╯
+│
+└  🚀 Get started with npm run dev
+```
+
+
+安装依赖以启动本地服务器：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    cd my-heroui-app && npm install
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    cd my-heroui-app && pnpm install
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    cd my-heroui-app && yarn install
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    cd my-heroui-app && bun install
+    ```
+  </Tab>
+</Tabs>
+
+启动本地服务器：
+
+```npm
+npm run dev
+```
+
+### Install
+
+将 `@heroui/react` 和 `@heroui/styles` 及其对等依赖安装到你的项目中。若它们已安装，则该命令不会执行任何操作。
+
+```bash
+heroui install [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+
+**输出：**
+
+```bash
+HeroUI CLI <version>
+
+📦 Packages to be installed:
+╭─────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version        │   Status   │   Docs                 │
+│─────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0          │   stable   │   https://heroui.com   │
+│   @heroui/styles   │   3.0.0          │   stable   │   https://heroui.com   │
+╰─────────────────────────────────────────────────────────────────────────────╯
+
+╭─────────────── PeerDependencies ────────────────╮
+│  react@18.3.1                      latest       │
+│  react-dom@18.3.1                  latest       │
+│  tailwindcss@4.2.2                 latest       │
+╰─────────────────────────────────────────────────╯
+? Proceed with installation? › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ @heroui/react and @heroui/styles installed successfully
+```
+
+### upgrade
+
+
+将 `@heroui/react` 和 `@heroui/styles` 及其对等依赖升级到最新版本。
+
+```bash
+heroui upgrade [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+**输出：**
+
+```bash
+HeroUI CLI <version>
+
+╭──────────────────────────── Upgrade ────────────────────────────╮
+│  @heroui/react               ^3.0.0  ->  ^3.1.0                │
+│  @heroui/styles              ^3.0.0  ->  ^3.1.0                │
+╰─────────────────────────────────────────────────────────────────╯
+
+? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ Upgrade complete. All packages are up to date.
+```
+
+### uninstall
+
+从你的项目中卸载 `@heroui/react` 和 `@heroui/styles`。对等依赖不会被卸载。
+
+```bash
+heroui uninstall [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+**输出：**
+
+```bash
+HeroUI CLI <version>
+
+❗️ Packages slated for uninstallation:
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version   │   Status   │   Docs                               │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0     │   stable   │   https://heroui.com                 │
+│   @heroui/styles   │   3.0.0     │   stable   │   https://heroui.com                 │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+? Confirm uninstallation of these packages: › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ Successfully uninstalled: @heroui/react, @heroui/styles
+```
+
+### list
+
+列出已安装的 HeroUI 包（`@heroui/react`、`@heroui/styles`）。
+
+```bash
+heroui list [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+**输出：**
+
+```bash
+HeroUI CLI <version>
+
+Current installed packages:
+
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version          │   Status   │   Docs                        │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+### doctor
+
+检查项目中存在的问题。
+- 检查 `@heroui/react` 和 `@heroui/styles` 是否已安装
+- 检查项目中是否安装了所需的 `对等依赖` 并满足最低版本要求
+
+
+```bash
+heroui doctor [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+**输出：**
+
+如果项目中存在问题，`doctor` 命令将显示问题信息。
+
+```bash
+HeroUI CLI <version>
+
+HeroUI CLI: ❌ Your project has 1 issue that require attention
+
+❗️Issue 1: missingHeroUIPackages
+
+The following HeroUI packages are not installed:
+- @heroui/styles
+
+Run `heroui install` to install them.
+```
+
+否则，`doctor` 命令将显示以下消息。
+
+```bash
+HeroUI CLI <version>
+
+✅ Your project has no detected issues.
+```
+
+### env
+
+显示本地环境的调试信息。
+
+```bash
+heroui env [options]
+```
+
+**选项：**
+
+- `-p --packagePath` [string] package.json 文件的路径
+
+**输出：**
+
+```bash
+HeroUI CLI <version>
+
+Current installed packages:
+
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version          │   Status   │   Docs                        │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+
+Environment Info:
+  System:
+    OS: darwin
+    CPU: arm64
+  Binaries:
+    Node: v25.8.1
+```
+
+### agents-md
+
+下载用于 AI 编程助手（Claude、Cursor 等）的 HeroUI 文档。该命令会从 HeroUI 仓库克隆最新文档，并将一份精简索引注入到 `AGENTS.md` 或 `CLAUDE.md` 中，方便助手参考你项目中的 HeroUI 配置。
+
+```bash
+heroui agents-md [options]
+```
+
+**选项：**
+
+- `--react` [boolean] 仅包含 React 文档（一次只能选择一个文档库）
+- `--native` [boolean] 仅包含 Native 文档
+- `--migration` [boolean] 仅包含 HeroUI v2 到 v3 的迁移文档
+- `--output <file>` [string] 目标文件路径（例如 `AGENTS.md`、`CLAUDE.md`）
+- `--ssh` [boolean] 使用 SSH 而非 HTTPS 进行 git clone
+
+**示例：**
+
+不带任何标志运行以进入交互模式：
+
+```bash
+heroui agents-md
+```
+
+将 React 文档下载到指定文件：
+
+```bash
+heroui agents-md --react --output AGENTS.md
+```
+
+下载 Native 或迁移文档：
+
+```bash
+heroui agents-md --native --output CLAUDE.md
+heroui agents-md --migration --output AGENTS.md
+```
+
+**工作原理：**
+
+1. 使用 git sparse-checkout 从 `v3` 分支克隆文档
+2. 生成文档和示例文件的精简索引
+3. 将该索引注入到你的 markdown 文件中，置于标记之间（`<!-- HEROUI-REACT-AGENTS-MD-START -->` / `<!-- HEROUI-REACT-AGENTS-MD-END -->`，Native 和 Migration 也有类似的标记）
+4. 将 `.heroui-docs/` 添加到 `.gitignore`
+
+`--react`、`--native` 和 `--migration` 一次只能选择其中一个。
+
+更多详情请参阅 [AGENTS.md](/docs/react/getting-started/agents-md)。
+
+<Callout>
+  `agents-md` 命令会收集匿名使用数据（所选项、输出文件名、耗时、成功或错误）。设置 `HEROUI_ANALYTICS_DISABLED=1` 可以选择不参与。
+</Callout>
+
+## 问题反馈
+
+如果你发现了 bug，请在 [heroui-cli Issues](https://github.com/heroui-inc/heroui-cli/issues) 中报告。
+
diff --git a/apps/docs/content/docs/cn/react/getting-started/(overview)/design-principles.mdx b/apps/docs/content/docs/cn/react/getting-started/(overview)/design-principles.mdx
new file mode 100644
index 0000000..82b3c83
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(overview)/design-principles.mdx
@@ -0,0 +1,290 @@
+---
+title: 设计原则
+description: 指导 HeroUI v3 设计和开发的核心原则
+icon: book
+---
+
+HeroUI v3 遵循 10 项核心原则，注重清晰度、无障碍、可定制性以及开发者体验。
+
+## 核心原则
+
+### 1. 语义意图优于视觉风格
+
+使用语义命名（primary、secondary、tertiary），而非视觉描述（solid、flat、bordered）。灵感来自 [Uber 的 Base 设计系统](https://base.uber.com/6d2425e9f/p/756216-button)，变体遵循清晰的层次结构：
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis-dark.jpg"
+  alt="语义意图层次结构"
+  className="object-contain"
+/>
+
+
+```tsx
+// ✅ Semantic variants communicate hierarchy
+<Button variant="primary">Save</Button>
+<Button variant="secondary">Edit</Button>
+<Button variant="tertiary">Cancel</Button>
+```
+
+| 变体 | 用途 | 使用方式 |
+|---------|---------|-------|
+| **Primary** | 推进流程的主要操作 | 每种场景 1 个 |
+| **Secondary** | 备选操作 | 可使用多个 |
+| **Tertiary** | 次要操作（取消、跳过） | 谨慎使用 |
+| **Danger** | 破坏性操作 | 需要时使用 |
+
+### 2. 无障碍是基础
+
+基于 [React Aria Components](https://react-spectrum.adobe.com/react-aria/) 构建，符合 WCAG 2.1 AA 标准。内置自动 ARIA 属性、键盘导航与屏幕阅读器支持。
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from '@heroui/react';
+
+<Tabs defaultSelectedKey="profile">
+  <TabList aria-label="Settings">
+    <Tab id="profile">Profile</Tab>
+    <Tab id="security">Security</Tab>
+  </TabList>
+  <TabPanel id="profile">Content</TabPanel>
+  <TabPanel id="security">Content</TabPanel>
+</Tabs>
+```
+
+### 3. 组合优于配置
+
+复合组件允许你按需重新组合、自定义或省略其中的各个部分。可以使用点号语法、命名导出，或两者混合使用。
+
+```tsx
+// Compose parts to build exactly what you need
+import {
+  Accordion,
+  AccordionItem,
+  AccordionHeading,
+  AccordionTrigger,
+  AccordionIndicator,
+  AccordionPanel,
+  AccordionBody
+} from '@heroui/react';
+
+<Accordion>
+  <AccordionItem id="1">
+    <AccordionHeading>
+      <AccordionTrigger>
+        Question Text
+        <AccordionIndicator />
+      </AccordionTrigger>
+    </AccordionHeading>
+    <AccordionPanel>
+      <AccordionBody>Answer content</AccordionBody>
+    </AccordionPanel>
+  </AccordionItem>
+</Accordion>
+```
+
+### 4. 渐进式呈现
+
+从简单开始，仅在需要时才增加复杂度。组件只需最少的 props 即可工作，并能随需求增长而扩展。
+
+```tsx
+// Level 1: Minimal
+<Button>Click me</Button>
+
+// Level 2: Enhanced
+<Button variant="primary" size="lg">
+  <Icon icon="gravity-ui:check" className="mr-2" />
+  Submit
+</Button>
+
+// Level 3: Advanced
+<Button variant="primary" isDisabled={isLoading}>
+  {isLoading ? <><Spinner size="sm" className="mr-2" /> Loading...</> : 'Submit'}
+</Button>
+```
+
+### 5. 可预测的行为
+
+所有组件遵循一致的模式：尺寸（`sm`、`md`、`lg`）、变体、`className` 支持以及 data 属性。相同的 API，相同的行为。
+
+```tsx
+// All components follow the same patterns
+<Button size="lg" variant="primary" className="custom" data-pressed="true" />
+<Chip size="lg" variant="success" className="custom" />
+<Avatar size="lg" className="custom" />
+
+// Compound components support both named exports and dot notation
+import { Alert, AlertIcon, CardHeader, AccordionTrigger } from '@heroui/react';
+
+// Named exports
+<Alert>
+  <AlertIcon />
+</Alert>
+
+// Dot notation
+<Alert>
+  <Alert.Icon />
+</Alert>
+```
+
+### 6. 类型安全优先
+
+完整的 TypeScript 支持，包括 IntelliSense、自动补全与编译时错误检测。可为自定义组件扩展类型。
+
+```tsx
+import type { ButtonProps } from '@heroui/react';
+
+// Type-safe props and event handlers
+<Button
+  variant="primary"  // Autocomplete: primary | secondary | tertiary | danger | ghost
+  size="md"          // Type checked: sm | md | lg
+  onPress={(e) => {  // e is properly typed as PressEvent
+    console.log(e.target);
+  }}
+/>
+
+// Extend types for custom components
+interface CustomButtonProps extends Omit<ButtonProps, 'variant'> {
+  intent: 'save' | 'cancel' | 'delete';
+}
+```
+
+### 7. 样式与逻辑分离
+
+样式（`@heroui/styles`）与逻辑（`@heroui/react`）相互分离，可与任何框架或纯 HTML 一同使用。参见 [Tailwind Play 示例](https://play.tailwindcss.com/vMYXzKPyUx)。
+
+```html
+<!-- Use with plain HTML -->
+<button class="button button--primary">Click me</button>
+```
+
+或与 React 一同使用：
+
+```tsx
+// Apply styles to any component
+import { buttonVariants } from '@heroui/styles';
+
+<Link className={buttonVariants({ variant: "primary" })} href="/home">
+  Home
+</Link>
+```
+
+### 8. 卓越的开发者体验
+
+清晰的 API、富含信息的错误提示、IntelliSense、对 AI 友好的 Markdown 文档，以及用于可视化测试的 Storybook。
+
+### 9. 完全可定制
+
+开箱即用的精美默认样式。使用 CSS 变量或 [BEM](https://getbem.com/) 类即可彻底改变整体外观。每一个插槽都可定制。
+
+```css
+/* Theme-wide changes with variables */
+:root {
+  --accent: oklch(0.7 0.25 260);
+  --radius: 0.375rem;
+  --spacing: 0.5rem;
+}
+
+/* Component-specific customization */
+@layer components {
+  .button {
+    @apply uppercase tracking-wider;
+  }
+  .button--primary {
+    @apply bg-gradient-to-r from-purple-500 to-pink-500;
+  }
+}
+```
+
+### 10. 开放且可扩展
+
+可以包装、扩展或自定义组件以满足你的需求。可以使用变体函数、直接应用 BEM 类，或创建自定义的包装组件。
+
+**使用变体函数应用样式：**
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+// Use variant functions to style framework-specific components
+const slots = linkVariants({ underline: "hover" });
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+```
+
+**直接应用 BEM 类：**
+
+```tsx
+import Link from 'next/link';
+
+// Apply HeroUI's BEM classes directly to any element
+<Link className="button button--primary" href="/dashboard">
+  Dashboard
+</Link>
+```
+
+**创建自定义包装组件：**
+
+```tsx
+// Custom wrapper component
+const CTAButton = ({
+  intent = 'primary-cta',
+  children,
+  ref,
+  ...props
+}: CTAButtonProps) => {
+  const variantMap = {
+    'primary-cta': 'primary',
+    'secondary-cta': 'secondary',
+    'minimal': 'ghost'
+  };
+
+  return (
+    <Button ref={ref} variant={variantMap[intent]} {...props}>
+      {children}
+    </Button>
+  );
+};
+```
+
+**使用 Tailwind Variants 扩展：**
+
+```tsx
+import { Button } from '@heroui/react';
+import { buttonVariants, tv } from '@heroui/styles';
+
+// Extend button styles with custom variants
+const myButtonVariants = tv({
+  extend: buttonVariants,
+  variants: {
+    variant: {
+      'primary-cta': 'bg-gradient-to-r from-blue-500 to-purple-600 text-white shadow-lg',
+      'secondary-cta': 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50',
+    }
+  }
+});
+
+// Use the custom variants
+function CustomButton({ variant, className, ...props }) {
+  return <Button className={myButtonVariants({ variant, className })} {...props} />;
+}
+
+// Usage
+<CustomButton variant="primary-cta">Get Started</CustomButton>
+<CustomButton variant="secondary-cta">Learn More</CustomButton>
+```
+
+## 与 HeroUI v2 的对比
+
+| 维度 | HeroUI v2 | HeroUI v3 |
+|--------|-----------|-----------|
+| **动画** | Framer Motion | CSS + GPU 加速 |
+| **组件模式** | 带有大量 props 的单一组件 | 复合组件 |
+| **变体** | 基于视觉（solid、bordered、flat） | 基于语义（primary、secondary、tertiary） |
+| **样式** | 部分支持 Tailwind v4 | 完整支持 Tailwind v4 |
+| **无障碍** | 优秀（基于 React Aria） | 优秀（基于 React Aria） |
+| **打包体积** | 较大（整体打包） | 较小（支持 tree-shaking） |
+| **自定义难度** | 中等（基于 props） | 简单（复合组件 + 原生 CSS） |
diff --git a/apps/docs/content/docs/cn/react/getting-started/(overview)/frameworks.mdx b/apps/docs/content/docs/cn/react/getting-started/(overview)/frameworks.mdx
new file mode 100644
index 0000000..f9487bc
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(overview)/frameworks.mdx
@@ -0,0 +1,145 @@
+---
+title: 框架集成
+description: 将 HeroUI 集成到你的框架中
+icon: layers
+---
+
+## Next.js
+
+### 1. 创建 Next.js 项目
+
+```bash
+npx heroui-cli@latest init
+```
+
+<Callout>
+  当出现提示时，选择 **App** 或 **Pages** 模板。然后进入新创建的文件夹并安装依赖（例如 `pnpm install`）。
+</Callout>
+
+### 2. 使用你的第一个 HeroUI 组件
+
+<Tabs items={["App Router", "Pages Router"]}>
+  <Tab value="App Router">
+    示例：`app/page.tsx`
+
+    ```tsx
+    import {Button} from "@heroui/react";
+
+    export default function HomePage() {
+      return (
+        <main className="flex min-h-screen items-center justify-center">
+          <Button variant="tertiary">Hello HeroUI</Button>
+        </main>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="Pages Router">
+    示例：`pages/index.tsx`
+
+    ```tsx
+    import {Button} from "@heroui/react";
+
+    export default function HomePage() {
+      return (
+        <main className="flex min-h-screen items-center justify-center">
+          <Button variant="tertiary">Hello HeroUI</Button>
+        </main>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Callout>
+  HeroUI v3 无需 Provider。安装并导入样式后，组件即可直接使用。
+</Callout>
+
+### 3. 区域设置（可选）
+
+为了与 Next.js 集成，请确保服务端的区域设置与客户端一致。
+
+在根布局中，确定用户的首选语言，并在 `<html>` 元素上设置 `lang` 和 `dir` 属性。
+
+```tsx
+// app/layout.tsx
+import {headers} from 'next/headers';
+import {isRTL} from '@heroui/react';
+import {ClientProviders} from './provider';
+
+export default async function RootLayout({children}) {
+  // Get the user's preferred language from the Accept-Language header.
+  // You could also get this from a database, URL param, etc.
+  const acceptLanguage = (await headers()).get('accept-language');
+  const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US';
+
+  return (
+    <html lang={lang} dir={isRTL(lang) ? 'rtl' : 'ltr'}>
+      <body>
+        <ClientProviders lang={lang}>
+          {children}
+        </ClientProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+创建 `app/provider.tsx`，其中应渲染一个 `I18nProvider`，用于设置 React Aria 所使用的区域设置。
+
+```tsx
+// app/provider.tsx
+"use client";
+
+import {I18nProvider} from '@heroui/react';
+
+export function ClientProviders({lang, children}) {
+  return (
+    <I18nProvider locale={lang}>
+      {children}
+    </I18nProvider>
+  );
+}
+```
+
+如果你使用了带 nonce 的 [内容安全策略](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP)（CSP），请在文档的 head 中添加 `<meta property="csp-nonce">` 标签，并将其 content 属性设置为生成的 nonce 值。React Aria 会自动从该标签读取 nonce。
+
+## Vite
+
+### 1. 创建 Vite 项目
+
+```bash
+npx heroui-cli@latest init
+```
+
+<Callout>
+  当出现提示时，选择 **Vite** 模板。然后进入新创建的文件夹并安装依赖（例如 `pnpm install`）。
+</Callout>
+
+### 2. 使用你的第一个 HeroUI 组件
+
+示例：`src/App.tsx`
+
+```tsx
+import {Button} from "@heroui/react";
+
+function App() {
+  return (
+    <main className="flex min-h-screen items-center justify-center">
+      <Button variant="tertiary">Hello HeroUI</Button>
+    </main>
+  );
+}
+
+export default App;
+```
+
+<Callout>
+  HeroUI v3 无需 Provider。安装并导入样式后，组件即可直接使用。
+</Callout>
+
+## 下一步
+
+- [快速入门](/docs/react/getting-started/quick-start) — 最快上手的方式
+- [主题](/docs/react/getting-started/theming) — 自定义颜色和设计令牌
+- [组件](/docs/react/components) — 探索所有可用的组件
diff --git a/apps/docs/content/docs/cn/react/getting-started/(overview)/quick-start.mdx b/apps/docs/content/docs/cn/react/getting-started/(overview)/quick-start.mdx
new file mode 100644
index 0000000..ad7cb9e
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(overview)/quick-start.mdx
@@ -0,0 +1,94 @@
+---
+title: 快速入门
+description: 只需几分钟即可开始使用 HeroUI v3
+icon: rocket
+---
+
+## 环境要求
+
+- [React 19+](https://reactjs.org/)
+- [Tailwind CSS v4](https://tailwindcss.com/docs/installation/framework-guides)
+
+## 快速安装
+
+<CopyPrompt
+  prompt={`在这个 React 项目中安装并配置 HeroUI。
+
+请使用 HeroUI MCP 服务器（@heroui/react-mcp）作为安装步骤、对等依赖和组件 API 的唯一可信来源。开始前先从 MCP 获取最新的 quick-start / 安装指南，并严格按照其中的版本号、包名和步骤执行——不要凭记忆操作。
+
+在做出任何更改之前：
+
+1. 分析项目。识别包管理器（npm / pnpm / yarn / bun）、所用框架（如 Next.js、Vite、Remix、Astro 等）、是否使用 TypeScript，以及主 CSS 入口文件的位置（如 globals.css、app.css、index.css）。
+2. 确认项目满足前置要求：React 19+ 和 Tailwind CSS v4。如果尚未安装 Tailwind CSS v4，请先按照与所用框架相匹配的官方 Tailwind v4 框架指南完成安装，再继续添加 HeroUI。
+3. 阅读 package.json，仅安装尚缺失的依赖。请严格使用 MCP quick-start 中给出的版本号，避免兼容性问题。
+
+然后执行安装与配置：
+
+- 安装 @heroui/react 和 @heroui/styles，以及任何缺失的必需对等依赖。
+- 在主 Tailwind CSS 入口文件中，紧跟在 \`@import "tailwindcss";\` 之后添加 \`@import "@heroui/styles";\`。导入顺序很重要——必须先导入 tailwindcss。
+- 确认该 CSS 入口文件已被应用加载（例如在 Next.js / Vite / Remix 的根布局或入口文件中被引入）。HeroUI v3 不需要 Provider，因此无需添加任何包裹组件。
+- 在页面上可见的位置渲染一个来自 \`@heroui/react\` 的 \`<Button>\` 作为最小冒烟测试，确认样式已正确生效。
+
+完成后，请总结你做出的变更，并告诉我如何启动开发服务器。`}
+>
+  **想让 AI 助手代劳？** 在你的编辑器中安装 [HeroUI MCP Server](/docs/react/getting-started/mcp-server)，然后把上面的提示词粘贴给 AI 助手——它会分析你的项目并自动完成全部配置。
+</CopyPrompt>
+
+安装 HeroUI 及其所需依赖：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+## 导入样式
+
+将以下内容添加到你的主 CSS 文件 `globals.css`：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles"; /* [!code highlight]*/
+```
+
+<Callout type="warning">
+  导入顺序很重要。请务必先导入 `tailwindcss`。
+</Callout>
+
+## 使用组件
+
+```tsx
+import { Button } from '@heroui/react';
+
+function App() {
+  return (
+    <Button>
+      My Button
+    </Button>
+  );
+}
+```
+
+## 下一步
+
+- [主题](/themes) — 创建并分享你自己的主题
+- [浏览组件](/docs/react/components) — 查看所有可用的组件
+- [学习样式](/docs/handbook/styling) — 使用 Tailwind CSS 进行自定义
+- [探索组合模式](/docs/handbook/composition) — 掌握复合组件
diff --git a/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agent-skills.mdx b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..97a0b75
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agent-skills.mdx
@@ -0,0 +1,71 @@
+---
+title: Agent Skills
+description: 让 AI 助手能够使用 HeroUI v3 组件来构建 UI
+---
+
+HeroUI Skills 为你的 AI 助手提供关于 HeroUI v3 组件、模式与最佳实践的全面知识。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-dark.jpg"
+  alt="HeroUI v3 MCP 服务器"
+/>
+
+### 安装
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-react
+```
+
+或者使用 skills 包：
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+支持 Claude Code、Cursor、OpenCode 等。
+</span>
+
+### 使用方法
+
+Skills 会被你的 AI 助手 **自动发现**，你也可以通过 `/heroui-react` 命令直接调用。
+
+只需让你的 AI 助手：
+- 使用 HeroUI v3 构建组件
+- 使用 HeroUI 组件创建页面
+- 自定义主题和样式
+- 查阅组件文档
+
+<Callout>
+  对于更复杂的使用场景，请使用 [MCP 服务器](/docs/react/getting-started/mcp-server)，它提供对组件文档与源代码的实时访问。
+</Callout>
+
+### 包含的内容
+
+- HeroUI v3 安装指南
+- 所有 HeroUI v3 组件，包含 props、示例与使用模式
+- 主题与样式指南
+- 设计原则与组合模式
+
+### 结构
+
+```
+skills/heroui-react/
+├── SKILL.md              # Main skill documentation
+├── LICENSE.txt           # Apache License 2.0
+└── scripts/              # Utility scripts
+    ├── list_components.mjs
+    ├── get_component_docs.mjs
+    ├── get_source.mjs
+    ├── get_styles.mjs
+    ├── get_theme.mjs
+    └── get_docs.mjs
+```
+
+### 相关文档
+
+- [Agent Skills 规范](https://agentskills.io/home) — 了解 Agent Skills 的格式
+- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) — Claude 的 Skills 文档
+- [Cursor Skills](https://cursor.com/docs/context/skills) — 在 Cursor 中使用 Skills
+- [OpenCode Skills](https://opencode.ai/docs/skills) — 在 OpenCode 中使用 Skills
diff --git a/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agents-md.mdx b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..12d5cf6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/agents-md.mdx
@@ -0,0 +1,54 @@
+---
+title: AGENTS.md
+description: 为 AI 编码代理下载 HeroUI v3 React 文档
+icon: preview
+---
+
+将 HeroUI v3 React 文档直接下载到你的项目中，供 AI 助手参考。
+
+<Callout>
+  **注意：** `agents-md` 命令专门用于 HeroUI React v3。其他 CLI 命令（如 `add`、`init`、`upgrade` 等）目前仍用于 HeroUI v2。
+</Callout>
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-dark.jpg"
+  alt="HeroUI React v3 AGENTS.md"
+/>
+
+### 用法
+
+```bash
+npx heroui-cli@latest agents-md --react
+```
+
+或者指定输出文件：
+
+```bash
+npx heroui-cli@latest agents-md --react --output AGENTS.md
+```
+
+### 功能说明
+
+- 将最新的 HeroUI v3 React 文档下载到 `.heroui-docs/react/`
+- 在 `AGENTS.md` 或 `CLAUDE.md` 中生成索引
+- 包含用于代码示例的 demo 文件
+- 自动将 `.heroui-docs/` 添加到 `.gitignore`
+
+### 选项
+
+- `--react` — 仅下载 React 文档
+- `--output <files...>` — 目标文件（例如 `AGENTS.md`，或 `AGENTS.md CLAUDE.md`）
+- `--ssh` — 使用 SSH 进行 git clone
+
+### 环境要求
+
+- Tailwind CSS >= v4
+- React >= 19.0.0
+- `@heroui/react >= 3.0.0` 或 `@latest`
+
+### 相关文档
+
+- [AGENTS.md](https://agents.md/) — 了解面向编码代理的 AGENTS.md 格式
+- [CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) — Claude 对应版本的 AGENTS.md
+- [AGENTS.md vs Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) — AGENTS.md 的性能表现
diff --git a/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/llms-txt.mdx b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/llms-txt.mdx
new file mode 100644
index 0000000..789c89f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/llms-txt.mdx
@@ -0,0 +1,62 @@
+---
+title: LLMs.txt
+description: 让 Claude、Cursor、Windsurf 等 AI 助手理解 HeroUI v3
+---
+
+我们提供 [LLMs.txt](https://llmstxt.org/) 文件，让 AI 编码助手可以访问 HeroUI v3 文档。
+
+## 可用文件
+
+**核心文档：**
+- [/react/llms.txt](/react/llms.txt) — React 文档的快速参考索引
+- [/react/llms-full.txt](/react/llms-full.txt) — 完整的 HeroUI React 文档
+
+**适用于上下文窗口有限的场景：**
+- [/react/llms-components.txt](/react/llms-components.txt) — 仅包含组件文档
+- [/react/llms-patterns.txt](/react/llms-patterns.txt) — 常见模式与代码片段
+
+**全平台：**
+- [/llms.txt](/llms.txt) — 快速参考索引（React + Native）
+- [/llms-full.txt](/llms-full.txt) — 完整文档（React + Native）
+- [/llms-components.txt](/llms-components.txt) — 全部组件文档
+- [/llms-patterns.txt](/llms-patterns.txt) — 全部模式与代码片段
+
+## 集成
+
+**Claude Code：** 让 Claude 参考文档：
+```
+Use HeroUI React documentation from https://heroui.com/react/llms.txt
+```
+或者添加到你项目中的 `.claude` 文件以自动加载。
+
+**Cursor：** 使用 `@Docs` 功能：
+```
+@Docs https://heroui.com/react/llms-full.txt
+```
+[了解更多](https://docs.cursor.com/context/@-symbols/@-docs)
+
+**Windsurf：** 添加到你的 `.windsurfrules` 文件：
+```
+#docs https://heroui.com/react/llms-full.txt
+```
+[了解更多](https://docs.codeium.com/windsurf/memories#memories-and-rules)
+
+**其他 AI 工具：** 大多数 AI 助手都可以通过 URL 引用文档。只需提供：
+```
+https://heroui.com/react/llms.txt
+```
+
+**针对特定组件的文档：**
+```
+https://heroui.com/react/llms-components.txt
+```
+
+**针对模式与最佳实践：**
+```
+https://heroui.com/react/llms-patterns.txt
+```
+
+
+## 参与贡献
+
+发现 AI 生成的代码有问题？欢迎在 [GitHub](https://github.com/heroui-inc/heroui) 上帮助我们改进 LLMs.txt 文件。
diff --git a/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/mcp-server.mdx b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..df76c9f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/(ui-for-agents)/mcp-server.mdx
@@ -0,0 +1,221 @@
+---
+title: MCP 服务器
+description: 直接在你的 AI 助手中访问 HeroUI v3 文档
+---
+
+HeroUI MCP 服务器让 AI 助手可以直接访问 HeroUI v3 组件文档，从而更轻松地在 AI 驱动的开发环境中使用 HeroUI 进行构建。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/hero-react-mcp-light-new-2.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/hero-react-mcp-dark-new.jpg"
+  alt="HeroUI v3 MCP 服务器"
+/>
+
+
+MCP 服务器目前仅支持 **@heroui/react v3**，并使用 [stdio 传输](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)。已在 npm 上以 `@heroui/react-mcp` 发布。源代码请查看 [GitHub](https://github.com/heroui-inc/heroui-mcp)。
+
+<Callout>
+  随着我们向 HeroUI v3 添加更多组件，它们也将在 MCP 服务器中可用。
+</Callout>
+
+## 快速设置
+
+### Cursor
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span  >Install in Cursor</span>
+  </a>
+</div>
+
+或者手动添加到 **Cursor Settings** → **Tools** → **MCP Servers**：
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+或者，将以下内容添加到你的 `~/.cursor/mcp.json` 文件。更多信息请参阅 [Cursor 文档](https://cursor.com/docs/context/mcp)。
+
+### Claude Code
+
+在终端中运行此命令：
+
+```bash
+claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
+```
+
+或者手动添加到你项目的 `.mcp.json` 文件：
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+添加配置后，重启 Claude Code 并运行 `/mcp`，即可在列表中看到 HeroUI MCP 服务器。如果你看到 **Connected**，就可以开始使用了。
+
+更多详情请参阅 [Claude Code MCP 文档](https://docs.claude.com/en/docs/claude-code/mcp)。
+
+### Windsurf
+
+将 HeroUI 服务器添加到你项目的 `.windsurf/mcp.json` 配置文件：
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+添加配置后，重新启动 Windsurf 以激活 MCP 服务器。
+
+更多详情请参阅 [Windsurf MCP 文档](https://docs.windsurf.com/windsurf/cascade/mcp)。
+
+### Zed
+
+将 HeroUI 服务器添加到你的 `settings.json` 配置文件。通过命令面板打开设置（`zed: open settings`），或使用 `Cmd-,`（Mac）/ `Ctrl-,`（Linux）：
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+```
+
+添加配置后，重新启动 Zed 并打开 Agent Panel 设置视图。检查 heroui 服务器旁边的指示点是否为绿色，且 tooltip 显示为 "Server is active"。
+
+更多详情请参阅 [Zed MCP 文档](https://zed.dev/docs/ai/mcp)。
+
+### VS Code
+
+要在 VS Code 中通过 GitHub Copilot 配置 MCP，请将 HeroUI 服务器添加到项目的 `.vscode/mcp.json` 配置文件：
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-react": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+添加配置后，打开 `.vscode/mcp.json`，然后点击 heroui-react 服务器旁边的 **Start**。
+
+更多详情请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)。
+
+### Codex
+
+将 HeroUI 服务器添加到你的 `~/.codex/config.toml`（或项目级的 `.codex/config.toml`）：
+
+```toml title="config.toml"
+[mcp_servers.heroui-react]
+command = "npx"
+args = ["-y", "@heroui/react-mcp@latest"]
+```
+
+添加配置后，重启 Codex 并在 TUI 中运行 `/mcp`，以验证服务器是否处于活动状态。
+
+更多详情请参阅 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。
+
+### OpenCode
+
+将 HeroUI 服务器添加到你项目的 `opencode.json` 配置文件：
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-react": {
+      "type": "local",
+      "command": ["npx", "-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+添加配置后，重新启动 OpenCode 以激活 MCP 服务器。
+
+更多详情请参阅 [OpenCode MCP 文档](https://open-code.ai/docs/en/mcp-servers)。
+
+## 用法
+
+配置完成后，可以这样询问你的 AI 助手：
+
+- “帮我在 Next.js / Vite / Astro 应用中安装 HeroUI v3”
+- “显示所有 HeroUI 组件”
+- “Button 组件有哪些 props？”
+- “给我一个使用 Card 组件的示例”
+- “获取 Button 组件的源代码”
+- “显示 Card 组件的 CSS 样式”
+- “深色模式下有哪些主题变量？”
+
+### 自动更新
+
+MCP 服务器可以帮助你升级到最新的 HeroUI 版本：
+
+```bash
+"Hey Cursor, update HeroUI to the latest version"
+```
+
+你的 AI 助手会自动完成以下事项：
+- 将你当前的版本与最新发布的版本进行比较
+- 查看变更日志，了解破坏性变更
+- 将必要的代码更新应用到你的项目中
+
+无论是更新到最新的稳定版还是预发布版，这一流程都适用于任何版本升级。
+
+## 可用工具
+
+MCP 服务器为 AI 助手提供以下工具：
+
+| 工具 | 描述 |
+|------|-------------|
+| `list_components` | 列出所有可用的 HeroUI v3 组件 |
+| `get_component_docs` | 获取一个或多个组件的完整文档，包括组件结构、props、示例和使用模式 |
+| `get_component_source_code` | 获取组件的 React/TypeScript 源代码（.tsx 文件） |
+| `get_component_source_styles` | 查看组件的 CSS 样式（.css 文件） |
+| `get_theme_variables` | 获取颜色、排版、间距相关的主题变量，支持浅色/深色模式 |
+| `get_docs` | 浏览完整的 HeroUI v3 文档，包括指南和设计原则（如需安装说明，请使用路径 `/docs/react/getting-started/quick-start`） |
+
+
+## 故障排查
+
+**环境要求：** Node.js 22 或更高版本。使用 `npx` 时会自动下载该包。
+
+**需要帮助？** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord 社区](https://discord.gg/heroui)
+
+## 链接
+
+- [npm 包](https://www.npmjs.com/package/@heroui/react-mcp)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui-mcp)
+- [贡献指南](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)
diff --git a/apps/docs/content/docs/cn/react/getting-started/index.mdx b/apps/docs/content/docs/cn/react/getting-started/index.mdx
new file mode 100644
index 0000000..8556f9d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/index.mdx
@@ -0,0 +1,87 @@
+---
+title: 介绍
+description: 一个开源 UI 组件库，用于构建美观且易于访问的用户界面。
+icon: book-open
+image: https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg
+---
+
+HeroUI 是一个基于 [Tailwind CSS v4](https://tailwindcss.com/) 和 [React Aria Components](https://react-spectrum.adobe.com/react-aria/index.html) 构建的 React 组件库。每个组件都带有流畅的动画、精致的细节和内置的无障碍支持——开箱即用，完全可定制。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+  alt="HeroUI v3 简介"
+/>
+
+## 为什么选择 HeroUI？
+
+**默认美观** — 开箱即用，外观专业，无需额外样式配置。
+
+**无障碍** — 基于 [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html) 构建，内置焦点管理、键盘导航和屏幕阅读器支持。
+
+**灵活** — 每个组件都由可定制的部件组成。按需修改，其余保持不动。
+
+**开发者友好** — 完整的类型化 API、可预期的模式以及出色的自动补全。
+
+**持续维护** — 我们负责处理更新、错误修复和新功能。你只需更新依赖包。
+
+**轻量级** — 支持 Tree Shaking，只把你实际使用的部分打包到应用中。
+
+**面向未来** — 为 [React 19](https://react.dev/blog/2024/12/05/react-19) 和 [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) 而构建，专为 AI 辅助开发而设计。
+
+## 一个精心打造的组件库，而非复制粘贴
+
+复制粘贴的代码能用，直到它出问题为止。你将不得不维护那些不再演进的过时依赖。
+
+HeroUI 则不同，它是与你共同演进的组件库：
+
+- 自动更新和修复
+- 无需额外工作即可获得新功能
+- 组件与 React、Tailwind 和浏览器保持同步
+- 深度定制，而非浅层主题调整
+- 面向代码生成的 AI 友好 API
+
+## HeroUI 生态系统
+
+- **🌐 HeroUI v3**（Web） — 你正在浏览的就是这里！基于 Tailwind CSS v4 的 React 组件
+- **📱 [HeroUI Native](https://link.heroui.com/native)**（移动端） — 为 React Native 提供精美组件
+- **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)**（文本生成应用） — 用自然语言创建应用
+- **🧠 面向 LLM 的 UI** — 全新平台与 MCP 即将推出
+
+**为什么选择 React Aria？** 我们选择 React Aria 是为了大规模实现无障碍能力。从 HeroUI v2 起我们就在使用它，v3 也保留了熟悉的 API 约定，例如 `isDisabled` 和 `onPress`。感谢 [Devon Govett](https://x.com/devongovett) 以及 Adobe 团队。
+
+## 常见问题
+
+**HeroUI 免费吗？**
+是的，基于 Apache License 2.0 完全免费且开源。
+
+**可以用于生产环境吗？**
+可以。HeroUI v3 已经稳定，可放心用于生产环境。
+
+**我可以定制组件吗？**
+当然可以！你可以使用 Tailwind 工具类、CSS 变量、[BEM](https://getbem.com/) 修饰符，或以不同的方式组合组件。每一个插槽都可以定制。
+
+**它支持 TypeScript 吗？**
+完全类型化，提供出色的 IDE 支持和自动补全。
+
+**无障碍能力如何？**
+基于 React Aria Components 构建，符合 WCAG 标准。内置键盘导航、焦点管理和屏幕阅读器支持。
+
+**可以在不使用 React 的情况下使用样式吗？**
+可以，CSS 可以应用于纯 HTML。请查看我们的 [Tailwind Play 示例](https://play.tailwindcss.com/vMYXzKPyUx)。
+
+**有 Figma 文件吗？**
+有！欢迎访问我们的设计系统：[HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429)。
+
+## 参与其中
+
+加入社区、分享反馈或参与贡献：
+
+- [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
+- [Discord](https://discord.gg/9b6yyZKmH4)
+- [X/Twitter](https://x.com/hero_ui)
+- [贡献指南](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md)
+
+HeroUI 基于 [Apache License 2.0](https://github.com/heroui-inc/heroui/blob/main/LICENSE) 协议发布。
+
+
diff --git a/apps/docs/content/docs/cn/react/getting-started/meta.json b/apps/docs/content/docs/cn/react/getting-started/meta.json
new file mode 100644
index 0000000..b7ab7b2
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/getting-started/meta.json
@@ -0,0 +1,29 @@
+{
+  "title": "快速开始",
+  "description": "快速开始使用 HeroUI v3",
+  "root": true,
+  "icon": "book-open",
+  "pages": [
+    "---概述---",
+    "index",
+    "(overview)/quick-start",
+    "(overview)/design-principles",
+    "(overview)/frameworks",
+    "(overview)/cli",
+    "[sparkles][展示](/showcase)",
+    "[route][路线图](https://herouiv3.featurebase.app/roadmap)",
+    "[figma][Figma](https://www.figma.com/community/file/1546526812159103429)",
+    "---手册---",
+    "(handbook)/colors",
+    "(handbook)/theming",
+    "(handbook)/dark-mode",
+    "(handbook)/styling",
+    "(handbook)/animation",
+    "(handbook)/composition",
+    "---代理用户界面---",
+    "(ui-for-agents)/llms-txt",
+    "(ui-for-agents)/mcp-server",
+    "(ui-for-agents)/agent-skills",
+    "(ui-for-agents)/agents-md"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/react/meta.json b/apps/docs/content/docs/cn/react/meta.json
new file mode 100644
index 0000000..672da0f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "文档",
+  "description": "HeroUI v3 文档",
+  "pages": ["getting-started", "components", "releases", "migration"]
+}
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/accordion.mdx b/apps/docs/content/docs/cn/react/migration/(components)/accordion.mdx
new file mode 100644
index 0000000..5448c75
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/accordion.mdx
@@ -0,0 +1,382 @@
+---
+title: Accordion
+description: Accordion 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Accordion 文档](/docs/react/components/accordion)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`AccordionItem` 是一个独立组件，通过 props 接收标题、副标题、内容等元素：
+
+```tsx
+import { Accordion, AccordionItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Accordion>
+      <AccordionItem
+        key="1"
+        title="Accordion 1"
+      >
+        Content here
+      </AccordionItem>
+      <AccordionItem
+        key="2"
+        title="Accordion 2"
+      >
+        Content here
+      </AccordionItem>
+    </Accordion>
+  );
+}
+```
+
+在 v3 中，Accordion 采用复合组件模式，并使用显式子组件进行组合：
+
+```tsx
+import { Accordion } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Accordion>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Accordion 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Accordion 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单个带 props 的 `AccordionItem` 组件  
+**v3：** 复合组件：`Accordion.Item`、`Accordion.Heading`、`Accordion.Trigger`、`Accordion.Panel`、`Accordion.Body`、`Accordion.Indicator`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `selectedKeys` | `Accordion` | 已重命名为 `expandedKeys`；类型为 `Iterable<Key>` |
+| `defaultSelectedKeys` | `Accordion` | 已重命名为 `defaultExpandedKeys` |
+| `onSelectionChange` | `Accordion` | 已重命名为 `onExpandedChange`；签名为 `(keys: Set<Key>) => void` |
+| `selectionMode="multiple"` | `Accordion` | 使用 `allowsMultipleExpanded`（布尔值） |
+| `isCompact` | — | 已移除（请使用 Tailwind CSS，例如 `text-sm`、`py-2`） |
+| `hideIndicator` | — | 不渲染 `<Accordion.Indicator />` 即可隐藏 |
+| `disableAnimation`、`disableIndicatorAnimation`、`motionProps` | — | 已移除（不支持动画 / 请使用 CSS） |
+| `showDivider`、`dividerProps` | — | 已移除（请手动添加分隔线或使用 `Divider`） |
+| `keepContentMounted` | — | 已移除（v3 中内容始终挂载） |
+| `selectionBehavior`、`disallowEmptySelection` | — | 已移除（不适用） |
+| `itemClasses` | — | 在各项上使用 `className` |
+| `startContent` | — | 将内容放在 `<Accordion.Trigger>` 内 |
+| `title`、`subtitle` | — | 将内容放在 `<Accordion.Trigger>` 内 |
+
+### 3. 变体
+
+**v2 变体：** `light`、`shadow`、`bordered`、`splitted`  
+**v3 变体：** `default`、`surface`
+
+v3 的变体更精简。若要接近 v2 的视觉效果：
+
+- **v2 `light`** → v3 `default`
+- **v2 `shadow`** → v3 `surface`
+- **v2 `bordered`** → v3 `default` + 添加边框类
+- **v2 `splitted`** → v3 `default` + 为各项添加背景色与间距 / 外边距
+
+### 4. 条目标识
+
+**v2：** React 的 `key` 同时用于列表调和与展开状态。  
+**v3：** 在 `Accordion.Item` 上使用 `id` 标识展开状态；列表中仍可为各项保留 React 的 `key`。
+
+## 迁移示例
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Accordion, AccordionItem } from "@heroui/react";
+
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Accordion 
+      selectedKeys={selectedKeys} 
+      onSelectionChange={setSelectedKeys}
+    >
+      <AccordionItem key="1" title="Item 1">
+        Content 1
+      </AccordionItem>
+      <AccordionItem key="2" title="Item 2">
+        Content 2
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Accordion } from "@heroui/react";
+    import type { Key } from "@heroui/react";
+
+    const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set(["1"]));
+
+    <Accordion 
+      expandedKeys={expandedKeys} 
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 1</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 2</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### 副标题与前置内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <AccordionItem 
+        key="1"
+        title="Accordion 1"
+        subtitle="Press to expand"
+        startContent={<Icon icon="gravity-ui:box" />}
+      >
+        Content here
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            <Icon icon="gravity-ui:box" className="mr-2" />
+            <div className="flex flex-col">
+              <span>Accordion 1</span>
+              <span className="text-sm text-muted">Press to expand</span>
+            </div>
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义指示器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <AccordionItem 
+        key="1"
+        title="Item 1"
+        indicator={(props) => (
+          props.isOpen ? <Icon icon="mdi:minus" /> : <Icon icon="mdi:plus" />
+        )}
+      >
+        Content
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { useState } from "react";
+    import { Accordion } from "@heroui/react";
+    import type { Key } from "@heroui/react";
+
+    const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set());
+
+    <Accordion 
+      expandedKeys={expandedKeys}
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator>
+              {expandedKeys.has("1") ? (
+                <Icon icon="gravity-ui:minus" />
+              ) : (
+                <Icon icon="gravity-ui:plus" />
+              )}
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### 禁用项与默认展开键
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Accordion 
+      defaultExpandedKeys={["1"]}
+      disabledKeys={["2"]}
+    >
+      <AccordionItem key="1" title="Item 1">
+        Content 1
+      </AccordionItem>
+      <AccordionItem key="2" title="Item 2">
+        Content 2
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Accordion defaultExpandedKeys={["1"]}>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 1</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2" isDisabled>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 2</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<AccordionItem 
+  classNames={{
+    base: "custom-base",
+    title: "custom-title",
+    content: "custom-content"
+  }}
+/>
+```
+
+### v3：在各子组件上使用 `className`
+
+```tsx
+<Accordion.Item className="custom-base">
+  <Accordion.Heading>
+    <Accordion.Trigger className="custom-title">
+      Title
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+  </Accordion.Heading>
+  <Accordion.Panel>
+    <Accordion.Body className="custom-content">
+      Content
+    </Accordion.Body>
+  </Accordion.Panel>
+</Accordion.Item>
+```
+
+## 组件剖析
+
+v3 Accordion 的结构如下：
+
+```
+Accordion (Root)
+  └── Accordion.Item
+      ├── Accordion.Heading
+      │   └── Accordion.Trigger
+      │       ├── [Your content: title, subtitle, icons, etc.]
+      │       └── Accordion.Indicator (optional)
+      └── Accordion.Panel
+          └── Accordion.Body
+              └── [Your content]
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件，而不是仅靠 props 拼装。
+2. **状态 props**：`selectedKeys` → `expandedKeys`，`onSelectionChange` → `onExpandedChange`。
+3. **多段展开**：`selectionMode="multiple"` → `allowsMultipleExpanded={true}`。
+4. **条目标识**：展开状态用 `id`；列表调和仍使用 React 的 `key`。
+5. **变体**：由 4 种缩减为 2 种。
+6. **已移除的 props**：大量便捷 props 已移除；请改用 Tailwind CSS 类。
+7. **内容结构**：标题、副标题与前置内容需手动放入 `Trigger`。
+8. **指示器**：必须显式渲染；不再自动生成指示器。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/alert.mdx b/apps/docs/content/docs/cn/react/migration/(components)/alert.mdx
new file mode 100644
index 0000000..a08e2a5
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/alert.mdx
@@ -0,0 +1,263 @@
+---
+title: Alert
+description: Alert 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Alert 文档](/docs/react/components/alert)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Alert` 是单个组件，通过 prop 接收标题、描述、图标等内容：
+
+```tsx
+import { Alert } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Alert 
+      title="This is an alert"
+      description="Thanks for subscribing to our newsletter!"
+    />
+  );
+}
+```
+
+在 v3 中，Alert 改为复合组件模式，子节点显式声明：
+
+```tsx
+import { Alert } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Alert>
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>This is an alert</Alert.Title>
+        <Alert.Description>
+          Thanks for subscribing to our newsletter!
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `Alert` 组件，通过 prop 配置  
+**v3：** 复合组件：`Alert`、`Alert.Indicator`、`Alert.Content`、`Alert.Title`、`Alert.Description`
+
+### 2. Color / Status prop
+
+| v2 颜色 | v3 状态 | 说明 |
+| ------- | ------- | ---- |
+| `default` | `default` | 相同 |
+| `primary` | `accent` | 已重命名 |
+| `secondary` | `default` | 改用 `default` 状态 |
+| `success` | `success` | 相同 |
+| `warning` | `warning` | 相同 |
+| `danger` | `danger` | 相同 |
+
+### 3. 移除变体
+
+**v2 变体：** `solid`、`bordered`、`flat`、`faded`  
+**v3：** 不再提供 `variant` prop——请使用 Tailwind CSS 类来实现类似效果
+
+要在 v3 中复刻 v2 的变体外观：
+- **v2 `solid`** → v3 `status` + 添加背景颜色类
+- **v2 `bordered`** → v3 `status` + 添加 `border` 类
+- **v2 `flat`** → v3 默认效果（无需额外类）
+- **v2 `faded`** → v3 `status` + 添加透明度 / 背景类
+
+### 4. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `variant` | - | 已移除（请改用 Tailwind CSS） |
+| `radius` | - | 已移除（请改用 Tailwind，例如 `rounded-lg`） |
+| `startContent` | - | 将内容放在 `<Alert.Indicator />` 之前 |
+| `endContent` | - | 将内容放在 `<Alert.Content />` 之后 |
+| `hideIcon` | - | 省略 `<Alert.Indicator />` |
+| `hideIconWrapper` | - | 已移除（v3 不再有图标包装层） |
+| `icon` | `Alert.Indicator` | 将图标作为 `<Alert.Indicator />` 的子节点 |
+| `isVisible`、`isDefaultVisible`、`onVisibleChange` | - | 已移除（请通过条件渲染控制） |
+| `isClosable`、`onClose`、`closeButtonProps` | - | 已移除（请手动添加 `CloseButton`） |
+| `title` | `Alert.Title` | 在 `<Alert.Content>` 内部使用 `<Alert.Title>` |
+| `description` | `Alert.Description` | 在 `<Alert.Content>` 内部使用 `<Alert.Description>` |
+
+### 5. 图标处理
+
+**v2：** 通过 `icon` prop 设置或 `hideIcon` 隐藏  
+**v3：** 使用 `<Alert.Indicator />`，通过子节点自定义图标，或完全省略它
+
+## 迁移示例
+
+### 图标处理
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from '@iconify/react';
+
+    {/* With custom icon */}
+    <Alert 
+      icon={<Icon icon="gravity-ui:box" />}
+      title="Custom Icon Alert"
+    />
+    
+    {/* Without icon */}
+    <Alert hideIcon title="No Icon Alert" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from '@iconify/react';
+
+    {/* With custom icon */}
+    <Alert>
+      <Alert.Indicator>
+        <Icon icon="gravity-ui:box" />
+      </Alert.Indicator>
+      <Alert.Content>
+        <Alert.Title>Custom Icon Alert</Alert.Title>
+      </Alert.Content>
+    </Alert>
+    
+    {/* Without icon */}
+    <Alert>
+      <Alert.Content>
+        <Alert.Title>No Icon Alert</Alert.Title>
+      </Alert.Content>
+    </Alert>
+    ```
+  </Tab>
+</Tabs>
+
+### 带操作按钮（end content）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Alert, Button } from "@heroui/react";
+
+    <Alert
+      title="You have no credits left"
+      description="Upgrade to a paid plan to continue"
+      endContent={
+        <Button color="warning" size="sm" variant="flat">
+          Upgrade
+        </Button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Alert, Button } from "@heroui/react";
+
+    <Alert status="warning">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>You have no credits left</Alert.Title>
+        <Alert.Description>
+          Upgrade to a paid plan to continue
+        </Alert.Description>
+        <Button className="mt-2" size="sm" variant="primary">
+          Upgrade
+        </Button>
+      </Alert.Content>
+    </Alert>
+    ```
+  </Tab>
+</Tabs>
+
+### 可关闭的 Alert
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Alert
+      title="Closable Alert"
+      isClosable
+      onClose={() => console.log("Closed")}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Alert, CloseButton } from "@heroui/react";
+    import { useState } from "react";
+
+    const [isVisible, setIsVisible] = useState(true);
+
+    {isVisible && (
+      <Alert>
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Closable Alert</Alert.Title>
+        </Alert.Content>
+        <CloseButton 
+          aria-label="Close"
+          onPress={() => setIsVisible(false)}
+        />
+      </Alert>
+    )}
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变更
+
+### v2：`classNames` prop
+
+```tsx
+<Alert 
+  classNames={{
+    base: "custom-base",
+    title: "custom-title",
+    description: "custom-description"
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Alert className="custom-base">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title className="custom-title">Title</Alert.Title>
+    <Alert.Description className="custom-description">
+      Description
+    </Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+## 组件结构
+
+v3 Alert 遵循以下结构：
+
+```
+Alert (Root)
+  ├── Alert.Indicator (optional)
+  ├── Alert.Content (optional)
+  │   ├── Alert.Title (optional)
+  │   └── Alert.Description (optional)
+  └── [Additional content like buttons, close button, etc.] (optional)
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件，而不是 prop
+2. **Color → Status**：`color` prop 已重命名为 `status`，`primary` → `accent`，`secondary` → `default`
+3. **移除 variant**：不再提供 `variant` prop；请使用 Tailwind CSS 类
+4. **移除 radius**：不再提供 `radius` prop；请使用 Tailwind CSS 类
+5. **不再内置关闭按钮**：必须手动添加 `CloseButton`
+6. **不再内置可见性控制**：请通过条件渲染处理可见性
+7. **不再有 startContent / endContent prop**：直接将内容放入组件树中
+8. **图标处理**：使用 `<Alert.Indicator />` 配合子节点，或省略它
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/autocomplete.mdx b/apps/docs/content/docs/cn/react/migration/(components)/autocomplete.mdx
new file mode 100644
index 0000000..93b1515
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/autocomplete.mdx
@@ -0,0 +1,584 @@
+---
+title: Autocomplete
+description: Autocomplete 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  在 v3 中，v2 的 `Autocomplete` 可以迁移为 [v3 Autocomplete](/docs/react/components/autocomplete) 或 [v3 ComboBox](/docs/react/components/combo-box)，取决于你的使用场景。请参阅下文「何时使用 Autocomplete 与 ComboBox」。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 何时使用 Autocomplete 与 ComboBox
+
+v3 提供两个组件来替代 v2 的 Autocomplete：
+
+| 组件 | 适用场景 | 输入方式 | 底层实现 |
+| ---- | -------- | -------- | -------- |
+| **Autocomplete** | 选择器式交互，Popover 内带搜索 / 筛选字段 | 按钮触发器展示已选值；Popover 内为搜索输入 | React Aria `Select` + `Autocomplete` |
+| **ComboBox** | 在可见输入框中输入以筛选下拉列表 | 内联文本输入与下拉触发器 | React Aria `ComboBox` |
+
+**使用 Autocomplete**：用户从预定义列表中选择，且搜索字段应出现在下拉内（类似可搜索的选择器）。
+
+**使用 ComboBox**：用户在可见输入框中直接输入以筛选或搜索选项（行为最接近 v2）。
+
+## 结构变化
+
+在 v2 中，Autocomplete 是内部包装 Input 的单一组件：
+
+```tsx
+import { Autocomplete, AutocompleteItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Autocomplete label="Select an animal">
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+  );
+}
+```
+
+### 迁移到 v3 ComboBox（最接近 v2）
+
+ComboBox 提供与 v2 Autocomplete 最接近的体验：内联文本输入并随输入筛选选项。
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ComboBox>
+      <Label>Select an animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### 迁移到 v3 Autocomplete（可搜索的选择器）
+
+Autocomplete 提供选择器式触发器，并在 Popover 内提供搜索 / 筛选字段：
+
+```tsx
+import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+export default function App() {
+  const { contains } = useFilter({ sensitivity: "base" });
+
+  return (
+    <Autocomplete>
+      <Label>Select an animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
+```
+
+## 关键变化
+
+### 1. 两个替代组件
+
+**v2：** `Autocomplete`（单一组件）  
+**v3：** `ComboBox`（内联输入 + 下拉）或 `Autocomplete`（选择器式 + Popover 内搜索）
+
+### 2. 组件结构
+
+**v2：** 单一组件，内部包含 Input  
+**v3 ComboBox：** 复合组件（`ComboBox.InputGroup`、`ComboBox.Trigger`、`ComboBox.Popover`）  
+**v3 Autocomplete：** 复合组件（`Autocomplete.Trigger`、`Autocomplete.Value`、`Autocomplete.ClearButton`、`Autocomplete.Indicator`、`Autocomplete.Popover`、`Autocomplete.Filter`）
+
+### 3. 菜单项组件
+
+**v2：** `AutocompleteItem`、`AutocompleteSection`  
+**v3：** `ListBox.Item`、`ListBox.Section`（来自 ListBox）
+
+### 4. 菜单项标识
+
+**v2：** React 的 `key` 同时用于列表协调与选择时的项标识。  
+**v3：** 在 `ListBox.Item` 上使用 `id` 与 `textValue`（状态与无障碍）；列表中的项仍保留 React 的 `key`。
+
+### 5. Autocomplete 专用子组件（v3）
+
+v3 Autocomplete 引入 v2 中不存在的子组件：
+
+| 子组件 | 用途 |
+| ------ | ---- |
+| `Autocomplete.Trigger` | 打开 Popover 的按钮组 |
+| `Autocomplete.Value` | 显示当前选中值或占位符 |
+| `Autocomplete.ClearButton` | 清除当前选择 |
+| `Autocomplete.Indicator` | 下拉箭头图标（打开时旋转） |
+| `Autocomplete.Popover` | 下拉 Popover 容器 |
+| `Autocomplete.Filter` | 包裹 `SearchField` 与 `ListBox` 以启用筛选；接受 `filter` 函数、`inputValue`、`onInputChange` |
+
+### 6. SearchField 集成
+
+v3 Autocomplete 在 `Autocomplete.Filter` 内使用 `SearchField`，作为 Popover 中的搜索输入：
+
+```tsx
+<Autocomplete.Filter filter={contains}>
+  <SearchField>
+    <SearchField.Group>
+      <SearchField.SearchIcon />
+      <SearchField.Input placeholder="Search..." />
+    </SearchField.Group>
+  </SearchField>
+  <ListBox>...</ListBox>
+</Autocomplete.Filter>
+```
+
+`SearchField` 还有子组件：`SearchField.Group`、`SearchField.Input`、`SearchField.SearchIcon`、`SearchField.ClearButton`。
+
+### 7. useFilter Hook
+
+v3 Autocomplete 使用 `useFilter` hook（来自 React Aria，由 `@heroui/react` 再导出）提供带区域设置感知的筛选函数：
+
+```tsx
+import { useFilter } from "@heroui/react";
+
+const { contains } = useFilter({ sensitivity: "base" });
+
+// 传给 Autocomplete.Filter
+<Autocomplete.Filter filter={contains}>
+  ...
+</Autocomplete.Filter>
+```
+
+该 hook 返回 `contains`、`startsWith`、`endsWith`。`sensitivity` 控制区域设置感知匹配（`"base"`、`"accent"`、`"case"`、`"variant"`）。
+
+### 8. Prop 变更（ComboBox）
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| — | `id`（在 `ListBox.Item` 上） | 状态用的项标识 |
+| — | `textValue`（在 `ListBox.Item` 上） | 无障碍（提前输入） |
+| `label` | `Label` | 使用 `Label` 组件 |
+| `description` | `Description` | 使用 `Description` 组件 |
+| `placeholder` | `Input` | 写在 `Input` 的 `placeholder` |
+| `selectedKey`、`onSelectionChange`、`inputValue`、`onInputChange` | `ComboBox` | 与 v2 相同 |
+| `allowsCustomValue`、`allowsEmptyCollection`、`defaultFilter` | `ComboBox` | 与 v2 相同 |
+| `disabledKeys`、`isDisabled`、`isRequired`、`isInvalid`、`name` | `ComboBox` | 与 v2 相同 |
+| `menuTrigger` | `ComboBox` | `"focus"`（默认）、`"input"` 或 `"manual"` |
+| `variant`、`color`、`size`、`radius` | — | 已移除（请使用 Tailwind CSS） |
+| `labelPlacement` | — | 已移除（请自行摆放 Label） |
+| `startContent`、`endContent` | — | 加到 `Input` 或 InputGroup |
+| `selectorIcon`、`clearIcon` | — | 自定义 `ComboBox.Trigger` 或手动实现 |
+| `isClearable` | — | 手动实现 |
+| `showScrollIndicators` | — | 已移除 |
+| `classNames` | — | 在各部件上使用 `className` |
+| `popoverProps`、`listboxProps`、`inputProps` | — | 直接在对应子组件上配置 |
+| `scrollShadowProps`、`scrollRef` | — | 已移除 |
+| `selectorButtonProps`、`clearButtonProps`、`disableSelectorIconRotation` | — | 已移除 |
+| `isReadOnly` | `ComboBox` | `ComboBox` 上的 `isReadOnly` prop |
+| `fullWidth` | `ComboBox` | `ComboBox` 上的 `fullWidth` prop |
+| `isVirtualized`、`maxListboxHeight`、`itemHeight` | — | 已移除 |
+| `onClose`、`onClear` | — | 改用其他事件处理函数 |
+| `validationBehavior`、`validate` | `ComboBox` | 写在 `ComboBox` 上的 prop |
+
+### 9. Prop 变更（Autocomplete）
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| — | `id`（在 `ListBox.Item` 上） | 状态用的项标识 |
+| — | `textValue`（在 `ListBox.Item` 上） | 无障碍（提前输入） |
+| `label` | `Label` | 使用 `Label` 组件 |
+| `description` | `Description` | 使用 `Description` 组件 |
+| `placeholder` | `Autocomplete` | 根组件上的 `placeholder` prop |
+| `selectedKey` / `onSelectionChange` | `value` / `onChange` | Autocomplete 上已重命名 |
+| `selectionMode` | `Autocomplete` | `"single"`（默认）或 `"multiple"` |
+| `inputValue`、`onInputChange` | `Autocomplete.Filter` | 写在 `Filter` 上的 `inputValue` 与 `onInputChange` |
+| `disabledKeys`、`isDisabled`、`isRequired`、`isInvalid`、`name` | `Autocomplete` | 与 v2 相同 |
+| `variant`、`color`、`size`、`radius` | — | 已移除（请使用 Tailwind CSS）；`variant` 支持 `"primary"` / `"secondary"` |
+| `isClearable` | `Autocomplete.ClearButton` | 内置子组件 |
+| `selectorIcon` | `Autocomplete.Indicator` | 将自定义图标作为 children 传入 |
+| `onClear` | `Autocomplete` | 根组件上的 `onClear` prop |
+| `fullWidth` | `Autocomplete` | 根组件上的 `fullWidth` prop |
+| `classNames` | — | 在各部件上使用 `className` |
+| `popoverProps`、`listboxProps`、`inputProps` | — | 直接在对应子组件上配置 |
+
+## 迁移示例
+
+### 受控选择（ComboBox）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selectedKey, setSelectedKey] = useState("cat");
+
+    <Autocomplete
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+      label="Animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+
+    const [selectedKey, setSelectedKey] = useState<Key | null>("cat");
+
+    <ComboBox
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+    >
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控选择（Autocomplete）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selectedKey, setSelectedKey] = useState("cat");
+
+    <Autocomplete
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+      label="Animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+    import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+    const [value, setValue] = useState<Key | Key[] | null>("cat");
+    const { contains } = useFilter({ sensitivity: "base" });
+
+    <Autocomplete value={value} onChange={setValue}>
+      <Label>Animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              <Label>Cat</Label>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              <Label>Dog</Label>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+    ```
+  </Tab>
+</Tabs>
+
+### 带分组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Autocomplete label="Country">
+      <AutocompleteSection title="North America">
+        <AutocompleteItem key="usa">United States</AutocompleteItem>
+        <AutocompleteItem key="canada">Canada</AutocompleteItem>
+      </AutocompleteSection>
+      <AutocompleteSection title="Europe">
+        <AutocompleteItem key="uk">United Kingdom</AutocompleteItem>
+      </AutocompleteSection>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Separator } from "@heroui/react";
+
+    <ComboBox>
+      <Label>Country</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search countries..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用 useFilter（Autocomplete）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 在内部处理筛选 */}
+    <Autocomplete label="Animal">
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+    function FilterExample() {
+      const { contains } = useFilter({ sensitivity: "base" });
+
+      return (
+        <Autocomplete>
+          <Label>Animal</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField>
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search..." />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox>
+                <ListBox.Item id="cat" textValue="Cat">
+                  <Label>Cat</Label>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="dog" textValue="Dog">
+                  <Label>Dog</Label>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Required field */}
+    <Autocomplete label="Animal" isRequired>
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+    </Autocomplete>
+
+    {/* With error message */}
+    <Autocomplete
+      label="Animal"
+      isInvalid
+      errorMessage="Please select an animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { FieldError, Form } from "@heroui/react";
+
+    {/* Required field */}
+    <Form>
+      <ComboBox isRequired name="animal">
+        <Label>Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+    </Form>
+
+    {/* With error message */}
+    <ComboBox isInvalid>
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <FieldError>Please select an animal</FieldError>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件剖析
+
+### ComboBox 剖析
+
+```
+ComboBox (Root)
+  ├── Label
+  ├── ComboBox.InputGroup
+  │   ├── Input
+  │   └── ComboBox.Trigger
+  ├── Description (optional)
+  ├── ComboBox.Popover
+  │   └── ListBox
+  │       ├── ListBox.Item
+  │       │   ├── [Content]
+  │       │   └── ListBox.ItemIndicator (optional)
+  │       └── ListBox.Section (optional)
+  │           ├── Header
+  │           └── ListBox.Item
+  └── FieldError (optional)
+```
+
+### Autocomplete 剖析
+
+```
+Autocomplete (Root)
+  ├── Label
+  ├── Autocomplete.Trigger
+  │   ├── Autocomplete.Value
+  │   ├── Autocomplete.ClearButton
+  │   └── Autocomplete.Indicator
+  ├── Description (optional)
+  ├── Autocomplete.Popover
+  │   └── Autocomplete.Filter
+  │       ├── SearchField
+  │       │   └── SearchField.Group
+  │       │       ├── SearchField.SearchIcon
+  │       │       └── SearchField.Input
+  │       └── ListBox
+  │           ├── ListBox.Item
+  │           │   ├── [Content]
+  │           │   └── ListBox.ItemIndicator (optional)
+  │           └── ListBox.Section (optional)
+  │               ├── Header
+  │               └── ListBox.Item
+  └── FieldError (optional)
+```
+
+## 总结
+
+1. **两个替代组件**：v2 `Autocomplete` 可迁移为 v3 `ComboBox`（内联输入）或 v3 `Autocomplete`（Popover 内可筛选的选择器）。  
+2. **组件结构**：由带 prop 的单一组件变为带显式子节点的复合组件。  
+3. **菜单项组件**：`AutocompleteItem` → `ListBox.Item`；`AutocompleteSection` → `ListBox.Section`。  
+4. **菜单项标识**：在项上使用 `id` 与 `textValue`；列表协调仍用 React 的 `key`。  
+5. **输入**：v3 ComboBox 需要显式 `Input`；v3 Autocomplete 在 `Autocomplete.Filter` 内使用 `SearchField`。  
+6. **标签 / 描述**：对应 prop 拆为独立的 `Label` 与 `Description` 组件。  
+7. **筛选**：v3 Autocomplete 通过 `Autocomplete.Filter` 与 `useFilter` 做区域设置感知筛选；v3 ComboBox 使用 `defaultFilter` prop。  
+8. **清除按钮**：v3 Autocomplete 内置 `Autocomplete.ClearButton`；v3 ComboBox 需手动实现。  
+9. **选中值展示**：v3 Autocomplete 用 `Autocomplete.Value` 展示选中值，并支持渲染 prop。  
+10. **样式类 prop 已移除**：`color`、`size`、`radius` 已移除（请使用 Tailwind CSS）；`variant` 现支持 `"primary"` / `"secondary"`。  
+11. **classNames 已移除**：在各子组件上使用 `className` prop。  
+12. **useFilter Hook**：v3 新增，提供 `contains`、`startsWith`、`endsWith` 用于区域设置感知的文本匹配。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/avatar.mdx b/apps/docs/content/docs/cn/react/migration/(components)/avatar.mdx
new file mode 100644
index 0000000..5d15fef
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/avatar.mdx
@@ -0,0 +1,357 @@
+---
+title: Avatar
+description: Avatar 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Avatar 文档](/docs/react/components/avatar)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Avatar` 是单个组件，通过 props 传入图片地址、姓名、后备内容等：
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Avatar 
+      src="https://example.com/avatar.jpg"
+      name="John Doe"
+      showFallback
+    />
+  );
+}
+```
+
+在 v3 中，`Avatar` 采用显式子组件的复合组件模式：
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Avatar>
+      <Avatar.Image src="https://example.com/avatar.jpg" alt="John Doe" />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单个带 props 的 `Avatar`  
+**v3：** 复合组件：`Avatar`、`Avatar.Image`、`Avatar.Fallback`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `src` | `Avatar.Image` | 使用 `<Avatar.Image src="..." />` |
+| `name` | — | 请自行生成首字母缩写并传入 `<Avatar.Fallback />` |
+| `showFallback` | — | 已移除（图片加载失败或未提供时显示后备） |
+| `fallback`, `icon` | `Avatar.Fallback` | 将内容放在 `<Avatar.Fallback />` 内 |
+| `color` | `Avatar` | 相同；`primary` → `accent`，`secondary` → `default` |
+| `variant` | `Avatar` | v3 新增；`"default"` \| `"soft"` |
+| `size` | `Avatar` | 相同 |
+| `isBordered` | — | 已移除（请使用 Tailwind，例如 `ring-2 ring-background`） |
+| `radius` | — | 已移除（请使用 Tailwind，例如 `rounded-full`） |
+| `isDisabled`, `isFocusable` | — | 已移除（如需请用 Tailwind / `asChild`） |
+| `getInitials` | — | 请手动生成首字母缩写 |
+| `ImgComponent`, `imgProps` | — | 如需请在 `Avatar.Image` 上使用 `asChild` |
+| `onError` | `Avatar.Image` | 在 `<Avatar.Image />` 上使用 `onError` |
+| — | `Avatar.Image` | 新增：`srcSet`、`sizes`、`loading`（响应式图片） |
+| — | `Avatar.Fallback` | 新增：`delayMs` 延迟显示后备（减少闪烁） |
+| `classNames` | — | 请在各部分使用 `className` |
+| `AvatarGroup` | — | 无 v3 等价组件；请用 CSS 自行成组 |
+
+### 3. `variant` prop（v3 新增）
+
+**v2：** 无 `variant` prop，仅通过 `color` 控制样式  
+**v3：** 新增 `variant` prop，可选 `"default"` 与 `"soft"`。`"soft"` 使用更浅的背景样式。
+
+```tsx
+<Avatar variant="soft" color="accent">
+  <Avatar.Image src="..." alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 4. `Avatar.Image` 响应式属性（v3 新增）
+
+**v2：** 仅支持 `src` 与 `onError`  
+**v3：** `Avatar.Image` 现支持 `srcSet`、`sizes`、`loading`，用于响应式图片
+
+```tsx
+<Avatar>
+  <Avatar.Image
+    src="avatar-400.jpg"
+    srcSet="avatar-200.jpg 200w, avatar-400.jpg 400w"
+    sizes="(max-width: 600px) 200px, 400px"
+    loading="lazy"
+    alt="User"
+  />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 5. `Avatar.Fallback` 的 `delayMs` prop（v3 新增）
+
+**v2：** 立即显示后备，或由 `showFallback` 控制  
+**v3：** `Avatar.Fallback` 支持 `delayMs`，可延后渲染，避免图片很快加载完成时出现后备闪烁
+
+```tsx
+<Avatar>
+  <Avatar.Image src="..." alt="User" />
+  <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 6. 图片与后备内容
+
+**v2：** 使用 `src`、`name`、`showFallback`、`fallback` 等 props  
+**v3：** 需显式渲染 `<Avatar.Image />` 与 `<Avatar.Fallback />`
+
+### 7. `color` 映射
+
+| v2 color | v3 color | 说明 |
+| -------- | -------- | ---- |
+| `default` | `default` | 相同 |
+| `primary` | `accent` | 已重命名 |
+| `secondary` | `default` | 使用 `default` |
+| `success` | `success` | 相同 |
+| `warning` | `warning` | 相同 |
+| `danger` | `danger` | 相同 |
+
+### 8. `AvatarGroup` 已移除
+
+**v2：** 提供独立的 `AvatarGroup` 组件  
+**v3：** 无 `AvatarGroup` — 请用 CSS 类手动成组
+
+## 迁移示例
+
+### 尺寸与颜色
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Avatar size="md" color="primary" src="..." name="John" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Avatar size="md" color="accent">
+      <Avatar.Image src="..." alt="John" />
+      <Avatar.Fallback>J</Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义后备
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Avatar 
+      src="https://broken-url.com/image.jpg"
+      showFallback
+      fallback={<Icon icon="mdi:account" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Avatar>
+      <Avatar.Image 
+        src="https://broken-url.com/image.jpg" 
+        alt="User"
+      />
+      <Avatar.Fallback>
+        <Icon icon="mdi:account" />
+      </Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+### Avatar 组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar, AvatarGroup } from "@heroui/react";
+
+    <AvatarGroup isBordered>
+      <Avatar src="https://example.com/1.jpg" />
+      <Avatar src="https://example.com/2.jpg" />
+      <Avatar src="https://example.com/3.jpg" />
+    </AvatarGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <div className="flex -space-x-2">
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/1.jpg" alt="User 1" />
+        <Avatar.Fallback>U1</Avatar.Fallback>
+      </Avatar>
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/2.jpg" alt="User 2" />
+        <Avatar.Fallback>U2</Avatar.Fallback>
+      </Avatar>
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/3.jpg" alt="User 3" />
+        <Avatar.Fallback>U3</Avatar.Fallback>
+      </Avatar>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 带头像数量上限的组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar, AvatarGroup } from "@heroui/react";
+
+    <AvatarGroup max={3}>
+      <Avatar src="https://example.com/1.jpg" />
+      <Avatar src="https://example.com/2.jpg" />
+      <Avatar src="https://example.com/3.jpg" />
+      <Avatar src="https://example.com/4.jpg" />
+      <Avatar src="https://example.com/5.jpg" />
+    </AvatarGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    const users = [
+      { id: 1, src: "https://example.com/1.jpg", name: "User 1" },
+      { id: 2, src: "https://example.com/2.jpg", name: "User 2" },
+      { id: 3, src: "https://example.com/3.jpg", name: "User 3" },
+      { id: 4, src: "https://example.com/4.jpg", name: "User 4" },
+      { id: 5, src: "https://example.com/5.jpg", name: "User 5" },
+    ];
+
+    <div className="flex -space-x-2">
+      {users.slice(0, 3).map((user) => (
+        <Avatar key={user.id} className="ring-2 ring-background">
+          <Avatar.Image src={user.src} alt={user.name} />
+          <Avatar.Fallback>
+            {user.name.split(" ").map(n => n[0]).join("")}
+          </Avatar.Fallback>
+        </Avatar>
+      ))}
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Fallback className="border-none">
+          +{users.length - 3}
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have variants, but uses color prop */}
+    <Avatar color="primary" name="John" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 has variant prop */}
+    <Avatar variant="soft" color="accent">
+      <Avatar.Fallback>J</Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Avatar 
+  classNames={{
+    base: "custom-base",
+    img: "custom-img",
+    fallback: "custom-fallback"
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Avatar className="custom-base">
+  <Avatar.Image className="custom-img" src="..." alt="..." />
+  <Avatar.Fallback className="custom-fallback">
+    JD
+  </Avatar.Fallback>
+</Avatar>
+```
+
+## 组件组成
+
+v3 `Avatar` 的结构如下：
+
+```
+Avatar (Root)
+  ├── Avatar.Image (optional)
+  └── Avatar.Fallback (optional; shown when image fails or not provided)
+```
+
+## 生成首字母缩写的辅助函数
+
+v3 没有 `name` prop，需要自行生成首字母缩写：
+
+```tsx
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .map(n => n[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+// Usage
+<Avatar>
+  <Avatar.Fallback>{getInitials("John Doe")}</Avatar.Fallback>
+</Avatar>
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Avatar.Image`、`Avatar.Fallback`）
+2. **`name` prop 已移除**：请手动生成首字母缩写
+3. **`showFallback` 已移除**：图片失败时仍会显示后备
+4. **新增 `variant` prop**：`"default"` \| `"soft"`，用于视觉样式
+5. **响应式图片**：`Avatar.Image` 支持 `srcSet`、`sizes`、`loading`
+6. **后备延迟**：`Avatar.Fallback` 支持 `delayMs`，减轻后备闪烁
+7. **颜色映射**：`primary` → `accent`，`secondary` → `default`
+8. **`isBordered` 已移除**：请使用 Tailwind `ring-2 ring-background` 等类
+9. **`radius` 已移除**：请使用 Tailwind `rounded-*` 类
+10. **`isDisabled` 等已移除**：请使用 Tailwind `opacity-50` 等类
+11. **`AvatarGroup` 已移除**：请用 CSS 手动成组
+12. **`icon` prop 已移除**：请将图标内容放入 `Avatar.Fallback`
+13. **`classNames` 已移除**：请在各子组件上使用 `className` prop
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/badge.mdx b/apps/docs/content/docs/cn/react/migration/(components)/badge.mdx
new file mode 100644
index 0000000..5d60ec3
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/badge.mdx
@@ -0,0 +1,275 @@
+---
+title: Badge
+description: Badge 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Badge 文档](/docs/react/components/badge)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Badge` 是一个包装组件，相对其子元素进行内容定位：
+
+```tsx
+import { Badge, Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Badge content="5" color="primary">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+  );
+}
+```
+
+在 v3 中，Badge 改为复合组件模式，由 `Badge.Anchor` 负责定位：
+
+```tsx
+import { Badge, Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="accent">5</Badge>
+    </Badge.Anchor>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `Badge` 组件包裹子节点，通过 `content` prop 设置徽章文本  
+**v3：** 复合组件：`Badge.Anchor`（定位包装器）、`Badge`（徽章本身）、`Badge.Label`（文本插槽，字符串子节点会自动包裹）
+
+### 2. 变体
+
+**v2：** `solid`、`flat`、`faded`、`shadow`  
+**v3：** `primary`、`secondary`、`soft`
+
+### 3. 颜色
+
+**v2：** `default`、`primary`、`secondary`、`success`、`warning`、`danger`  
+**v3：** `default`、`accent`、`success`、`warning`、`danger`
+
+### 4. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `content` | `Badge` 子节点 | 内容现在以子节点传入 |
+| `children` | `Badge.Anchor` | 锚定元素放入 `Badge.Anchor` 内部 |
+| `variant` | `Badge` | 取值变化（详见变体映射） |
+| `color` | `Badge` | `primary` → `accent`，`secondary` 已移除 |
+| `size` | `Badge` | 相同（`sm`、`md`、`lg`） |
+| `placement` | `Badge` | 相同（`top-right`、`top-left`、`bottom-right`、`bottom-left`） |
+| `shape` | - | 已移除（请改用 Tailwind CSS） |
+| `showOutline` | - | 已移除（请改用 Tailwind CSS，例如 `border-2`） |
+| `disableOutline` | - | 已移除 |
+| `disableAnimation` | - | 已移除 |
+| `isInvisible` | - | 已移除（请使用条件渲染） |
+| `isOneChar` | - | 已移除（请改用 Tailwind CSS） |
+| `isDot` | - | 省略子节点即可渲染为圆点 |
+| `classNames` | - | 改在各子组件上使用 `className` |
+
+### 5. 变体映射
+
+| v2 变体 | v3 对应项 | 说明 |
+| ------- | --------- | ---- |
+| `solid` | `primary` | 实心背景 |
+| `flat` | `soft` | 浅色背景 |
+| `faded` | `secondary` | 边框 + 背景 |
+| `shadow` | `primary` | 配合 Tailwind 的 `shadow-*` 类 |
+
+### 6. 颜色映射
+
+| v2 颜色 | v3 对应项 | 说明 |
+| ------- | --------- | ---- |
+| `default` | `default` | 相同 |
+| `primary` | `accent` | 已重命名 |
+| `secondary` | `default` 或 `accent` | 视上下文而定 |
+| `success` | `success` | 相同 |
+| `warning` | `warning` | 相同 |
+| `danger` | `danger` | 相同 |
+
+## 迁移示例
+
+### 基本徽章
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Badge, Avatar } from "@heroui/react";
+
+    <Badge content="5" color="primary">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Badge, Avatar } from "@heroui/react";
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="accent">5</Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### 圆点徽章
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Badge content="" isDot color="success">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="success" />
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### 位置
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Badge content="5" placement="bottom-right" color="danger">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge placement="bottom-right" color="danger">5</Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### 可见性切换
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [isInvisible, setIsInvisible] = useState(false);
+
+    <Badge content="5" isInvisible={isInvisible} color="danger">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [isVisible, setIsVisible] = useState(true);
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      {isVisible && <Badge color="danger">5</Badge>}
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### 带图标内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Badge content={<Icon icon="gravity-ui:check" />} color="success">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="success">
+        <Icon icon="gravity-ui:check" />
+      </Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变更
+
+### v2：`classNames` prop
+
+```tsx
+<Badge
+  classNames={{
+    base: "custom-base",
+    badge: "custom-badge"
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Badge.Anchor className="custom-anchor">
+  <Avatar />
+  <Badge className="custom-badge">
+    <Badge.Label className="custom-label">5</Badge.Label>
+  </Badge>
+</Badge.Anchor>
+```
+
+## 组件结构
+
+v3 Badge 遵循以下结构：
+
+```
+Badge.Anchor (positioning wrapper)
+  ├── [Anchored element: Avatar, Button, etc.]
+  └── Badge (the badge indicator)
+      └── Badge.Label (auto-wrapped for string/number children)
+```
+
+## 总结
+
+1. **组件结构**：`Badge` 包裹子节点 → `Badge.Anchor` + `Badge` 作为同级
+2. **移除 content prop**：`content` prop → 将内容作为 `Badge` 的子节点传入
+3. **圆点徽章**：`isDot` prop → 省略子节点
+4. **可见性**：`isInvisible` prop → 改用条件渲染
+5. **变体收敛**：从 4 个变体减少为 3 个（`primary`、`secondary`、`soft`）
+6. **颜色变化**：`primary` → `accent`，`secondary` 已移除
+7. **移除的 prop**：`shape`、`showOutline`、`disableAnimation`、`isOneChar` —— 请改用 Tailwind CSS
+8. **移除 classNames**：改在各复合子组件上使用 `className`
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/breadcrumbs.mdx b/apps/docs/content/docs/cn/react/migration/(components)/breadcrumbs.mdx
new file mode 100644
index 0000000..72ab13b
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/breadcrumbs.mdx
@@ -0,0 +1,142 @@
+---
+title: Breadcrumbs
+description: Breadcrumbs 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Breadcrumbs 文档](/docs/react/components/breadcrumbs)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Breadcrumbs` 接受 `items` prop 或子节点：
+
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Breadcrumbs>
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem href="#">Products</BreadcrumbItem>
+      <BreadcrumbItem>Current Page</BreadcrumbItem>
+    </Breadcrumbs>
+  );
+}
+```
+
+在 v3 中，Breadcrumbs 改为复合组件模式，由 `Breadcrumbs` 与 `BreadcrumbsItem` 组成：
+
+```tsx
+import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Breadcrumbs>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
+      <BreadcrumbsItem>Current Page</BreadcrumbsItem>
+    </Breadcrumbs>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件名称：`BreadcrumbItem` → `BreadcrumbsItem`
+
+**v2：** 使用 `BreadcrumbItem`（单数）  
+**v3：** 使用 `BreadcrumbsItem`（复数）
+
+### 2. 自定义分隔符
+
+**v2：** 通过 prop 自定义分隔符  
+**v3：** 通过在 `Breadcrumbs` 根节点上设置 `separator` prop 自定义
+
+### 3. 内置链接组件
+
+**v2：** 项目可以是链接或纯文本  
+**v3：** 当提供 `href` 时，项目会自动使用 `Link` 组件
+
+### 4. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `maxItems` | - | 已移除（渲染全部项目，或自行实现折叠逻辑） |
+| `itemsBeforeCollapse`、`itemsAfterCollapse`、`renderEllipsis` | - | 已移除（与 `maxItems` 折叠/省略号一并移除） |
+| `items`（prop 写法） | - | 改用子节点 |
+| `onAction` | - | 如有需要，可在单个项目上使用 `onPress` |
+| `isDisabled` | 根节点上的 `isDisabled` | 现在根节点支持，可一次性禁用全部面包屑链接 |
+| `classNames`、`itemClasses` | - | 改用 `Breadcrumbs` 与 `BreadcrumbsItem` 上的 `className` |
+
+### 5. 根节点上的 `isDisabled` prop
+
+**v2：** 根组件不支持 `isDisabled`  
+**v3：** `Breadcrumbs` 根节点支持 `isDisabled`，可立即禁用所有面包屑链接
+
+### 6. 自动 `aria-current="page"` 行为
+
+**v3：** 最后一个未提供 `href` 的面包屑项目会自动带上 `aria-current="page"`，向辅助技术指明当前页面，无需手动配置。
+
+### 7. 集成 React Aria Components
+
+**v3：** 基于 React Aria Components 构建，提供更佳的无障碍体验与键盘导航支持。
+
+## 迁移示例
+
+### 自定义分隔符
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Breadcrumbs separator="/">
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem>Current</BreadcrumbItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";
+
+    <Breadcrumbs separator={<Icon icon="gravity-ui:caret-right" />}>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem>Current</BreadcrumbsItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+</Tabs>
+
+### 禁用状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not support isDisabled on the root */}
+    <Breadcrumbs>
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem>Current</BreadcrumbItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 supports isDisabled on root to disable all links */}
+    <Breadcrumbs isDisabled>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem>Current</BreadcrumbsItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+- 将 `BreadcrumbItem` 重命名为 `BreadcrumbsItem`
+- 在根节点上设置 `separator`，可以是字符串或 React 元素（例如图标）
+- 提供 `href` 的项目会自动使用内置 Link
+- 根节点现在支持 `isDisabled`，可立即禁用全部面包屑链接
+- 最后一个未提供 `href` 的项目会自动带上 `aria-current="page"`，提升无障碍体验
+- v3 不再提供 `maxItems` / 折叠功能——请显示全部项目或自行实现；用 `className` 取代 `classNames` / `itemClasses`
+- 基于 React Aria Components 构建，更易实现无障碍
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/button-group.mdx b/apps/docs/content/docs/cn/react/migration/(components)/button-group.mdx
new file mode 100644
index 0000000..5368dce
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/button-group.mdx
@@ -0,0 +1,65 @@
+---
+title: ButtonGroup
+description: ButtonGroup 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 ButtonGroup 文档](/docs/react/components/button-group)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`ButtonGroup` 用于将按钮分组：
+
+```tsx
+import { ButtonGroup, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+在 v3 中，`ButtonGroup` 的基本结构相同，但加强了 prop 继承：
+
+```tsx
+import { ButtonGroup, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 导入路径
+
+**v2：** 从 `@heroui/react` 导入  
+**v3：** 从 `@heroui/react` 导入（同一个包，但导入方式已统一）
+
+### 2. Prop 继承
+
+**v2：** ButtonGroup 会向子按钮传递 `size`、`color`、`variant`、`radius`、`isIconOnly`、`isDisabled`、`disableAnimation`、`disableRipple` 与 `fullWidth`。
+
+**v3：** ButtonGroup 会向子按钮传递 `size`、`variant`、`isDisabled` 与 `fullWidth`。`color` 与 `radius` 等 prop 在按钮上已不存在（由 `variant` 取代），`disableAnimation` 与 `disableRipple` 已从设计系统中移除。
+
+### 3. 隐藏分隔符
+
+**v3：** 新增 `hideSeparator` prop，可隐藏按钮之间的视觉分隔线。
+
+## 总结
+
+- 在 ButtonGroup 上设置 `size`、`variant`、`isDisabled` 与 `fullWidth`，会作用到所有子按钮（v3 用单一的 `variant` 取代了 v2 的 `color` + `variant` 组合）
+- 使用新增的 `hideSeparator` prop 可隐藏按钮之间的分隔线
+- 结构保持不变；已被移除的 prop（`radius`、`disableAnimation`、`disableRipple`）在 v3 的 Button 上已不再可用
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/button.mdx b/apps/docs/content/docs/cn/react/migration/(components)/button.mdx
new file mode 100644
index 0000000..2008d74
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/button.mdx
@@ -0,0 +1,357 @@
+---
+title: Button
+description: Button 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Button 文档](/docs/react/components/button)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Button` 通过 `color` 与 `variant` 组合使用：
+
+```tsx
+import { Button } from "@heroui/react";
+
+export default function App() {
+  return <Button color="primary" variant="solid">Button</Button>;
+}
+```
+
+在 v3 中，`Button` 仅使用 `variant` prop（不再有独立的 `color` prop）：
+
+```tsx
+import { Button } from "@heroui/react";
+
+export default function App() {
+  return <Button variant="primary">Button</Button>;
+}
+```
+
+## 主要变化
+
+### 1. 变体与颜色
+
+**v2：** 使用 `color` + `variant` 组合  
+**v3：** 仅使用 `variant`（无独立 `color` prop）
+
+| v2 color + variant | v3 变体 | 说明 |
+| ------------------ | ------- | ---- |
+| `color="primary" variant="solid"` | `variant="primary"` | 默认主按钮 |
+| `color="default" variant="solid"` | `variant="primary"` | 使用 primary 变体 |
+| `color="secondary" variant="solid"` | `variant="secondary"` | 相同 |
+| `color="success" variant="solid"` | `variant="primary"` | 如需可配合自定义样式使用 primary |
+| `color="warning" variant="solid"` | `variant="primary"` | 如需可配合自定义样式使用 primary |
+| `color="danger" variant="solid"` | `variant="danger"` | 提供 danger 变体 |
+| `color="primary" variant="bordered"` | `variant="secondary"` | 外观相近 |
+| `color="primary" variant="light"` | `variant="tertiary"` | 外观相近 |
+| `color="primary" variant="flat"` | `variant="tertiary"` | 外观相近 |
+| `color="primary" variant="faded"` | `variant="secondary"` | 外观相近 |
+| `color="primary" variant="ghost"` | `variant="ghost"` | 相同 |
+| `color="danger" variant="flat"` | `variant="danger-soft"` | 新增柔和危险变体 |
+
+**v2 变体：** `solid`、`bordered`、`light`、`flat`、`faded`、`shadow`、`ghost`  
+**v3 变体：** `primary`、`secondary`、`tertiary`、`outline`、`ghost`、`danger`、`danger-soft`
+
+### 2. 加载状态：`isLoading` → `isPending`
+
+**v2：** 使用 `isLoading` prop  
+**v3：** 使用 `isPending` prop
+
+### 3. 默认宽度行为
+
+**v2：** 按钮按尺寸带有最小宽度（sm：`min-w-16`，md：`min-w-20`，lg：`min-w-24`）  
+**v3：** 按钮默认使用 `w-fit`（宽度随内容，无最小宽度）
+
+因此当文案较短时，v3 按钮会比 v2 更窄。若要保留 v2 的最小宽度行为，请添加 Tailwind 类，请见下方 **尺寸与最小宽度** 示例小节。
+
+### 4. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `isLoading` | `Button` | 已重命名为 `isPending` |
+| `isIconOnly` | `Button` | v3 仍支持 — 渲染仅含图标的方形按钮 |
+| `color` | — | 已移除（由变体负责样式） |
+| `radius` | — | 已移除（请使用 Tailwind，例如 `rounded-lg`） |
+| `startContent`, `endContent` | — | 请将图标作为 children 放置 |
+| `spinner`, `spinnerPlacement` | — | 请通过渲染 prop 自行处理加载态 |
+| `disableRipple` | — | 已移除（v3 已移除波纹） |
+| `disableAnimation` | — | 已移除（动画由内部处理） |
+| `classNames` | — | 请使用 `className` |
+
+### 5. ButtonGroup 仍可用
+
+**v2：** 提供独立的 `ButtonGroup` 组件  
+**v3：** `ButtonGroup` 仍然存在。详见 [ButtonGroup 迁移指南](/docs/react/migration/button-group)。
+
+## 迁移示例
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button color="primary" variant="solid">Solid</Button>
+    <Button color="primary" variant="bordered">Bordered</Button>
+    <Button color="primary" variant="ghost">Ghost</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="ghost">Ghost</Button>
+    ```
+  </Tab>
+</Tabs>
+
+### danger-soft 变体
+
+`danger-soft` 变体为 v3 新增，用于替代 v2 中 `color="danger" variant="flat"` 的用法。
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button color="danger" variant="flat">Delete</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Button variant="danger-soft">Delete</Button>
+    ```
+  </Tab>
+</Tabs>
+
+### 仅图标（`isIconOnly`）
+
+`isIconOnly` prop 在 v2 与 v3 中均可用，用于渲染适配单个图标的方形按钮。v3 中请用 `variant` 替代 `color` 控制样式。
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button isIconOnly color="danger" variant="flat">
+      <HeartIcon />
+    </Button>
+    <Button isIconOnly color="primary" variant="bordered" size="sm">
+      <SearchIcon />
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button isIconOnly variant="danger-soft">
+      <Icon icon="gravity-ui:heart" />
+    </Button>
+    <Button isIconOnly variant="secondary" size="sm">
+      <Icon icon="gravity-ui:magnifier" />
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### 加载状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Simple loading */}
+    <Button isLoading color="primary">
+      Loading
+    </Button>
+    
+    {/* Loading with conditional content */}
+    <Button 
+      isLoading={isLoading}
+      spinnerPlacement="start"
+      color="primary"
+      onPress={() => setIsLoading(true)}
+    >
+      Upload File
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Spinner } from "@heroui/react";
+    import { Icon } from "@iconify/react";
+
+    const [isLoading, setIsLoading] = useState(false);
+
+    {/* Simple loading */}
+    <Button isPending={isLoading}>
+      {({isPending}) => (
+        <>
+          {isPending && <Spinner color="current" size="sm" />}
+          Loading
+        </>
+      )}
+    </Button>
+    
+    {/* Loading with conditional content */}
+    <Button 
+      isPending={isLoading}
+      onPress={() => setIsLoading(true)}
+    >
+      {({isPending}) => (
+        <>
+          {isPending ? (
+            <Spinner color="current" size="sm" />
+          ) : (
+            <Icon icon="gravity-ui:paperclip" />
+          )}
+          {isPending ? "Uploading..." : "Upload File"}
+        </>
+      )}
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### 带图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button 
+      color="success" 
+      endContent={<Icon icon="gravity-ui:camera" />}
+    >
+      Take a photo
+    </Button>
+    <Button 
+      color="danger" 
+      startContent={<Icon icon="gravity-ui:trash-bin" />}
+      variant="bordered"
+    >
+      Delete user
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button variant="primary">
+      <Icon icon="gravity-ui:camera" />
+      Take a photo
+    </Button>
+    <Button variant="secondary">
+      <Icon icon="gravity-ui:trash-bin" />
+      Delete user
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### 仅图标按钮
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button isIconOnly color="danger">
+      <HeartIcon />
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button isIconOnly variant="danger">
+      <Icon icon="gravity-ui:heart" />
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### 按钮组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Button, ButtonGroup } from "@heroui/react";
+
+    <ButtonGroup size="sm" color="primary" variant="solid">
+      <Button>One</Button>
+      <Button>Two</Button>
+      <Button>Three</Button>
+    </ButtonGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, ButtonGroup } from "@heroui/react";
+
+    <ButtonGroup size="sm" variant="primary">
+      <Button>One</Button>
+      <Button>Two</Button>
+      <Button>Three</Button>
+    </ButtonGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 尺寸与最小宽度
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 automatically applies minimum widths */}
+    <Button size="md" color="primary">Save</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 uses w-fit by default - add min-width to match v2 */}
+    <Button size="md" variant="primary" className="min-w-20">
+      Save
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+## 渲染 prop 模式
+
+v3 `Button` 支持渲染 prop 模式，可拿到状态信息：
+
+```tsx
+<Button isPending={isLoading}>
+  {({isPending, isPressed, isHovered, isFocused, isFocusVisible, isDisabled}) => (
+    <>
+      {isPending && <Spinner size="sm" />}
+      {isPressed ? "Pressed!" : "Click me"}
+    </>
+  )}
+</Button>
+```
+
+可用的渲染 prop：
+
+- `isPending` — 是否处于加载状态  
+- `isPressed` — 是否正被按下  
+- `isHovered` — 是否悬停  
+- `isFocused` — 是否聚焦  
+- `isFocusVisible` — 是否应显示焦点环  
+- `isDisabled` — 是否禁用  
+
+## 总结
+
+1. **`color` prop 已移除**：请用 `variant` 替代 `color` + `variant` 组合  
+2. **变体体系变更**：新变体系统（`primary`、`secondary`、`tertiary`、`outline`、`ghost`、`danger`、`danger-soft`）  
+3. **`danger-soft` 变体**：v3 新增，替代 v2 的 `color="danger" variant="flat"`  
+4. **`isLoading` → `isPending`**：加载相关 prop 已重命名  
+5. **`isIconOnly`**：v3 仍支持 — 用于仅图标的方形按钮  
+6. **默认宽度变更**：按钮默认 `w-fit`，不再内置最小宽度 — 可添加 `min-w-*` 贴近 v2  
+7. **图标**：`startContent` / `endContent` 已移除 — 请将图标作为 children  
+8. **加载指示器**：需通过渲染 prop 自行组合 Spinner 等  
+9. **渲染 prop**：v3 `Button` 的 children 可为函数，参数包含 `isPending`、`isPressed`、`isHovered`、`isFocused`、`isFocusVisible`、`isDisabled`  
+10. **`radius` 已移除**：请使用 Tailwind CSS 类  
+11. **波纹已移除**：v3 无波纹效果  
+12. **ButtonGroup**：参见 [ButtonGroup 迁移指南](/docs/react/migration/button-group)  
+13. **`classNames` 已移除**：请使用 `className` prop  
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/calendar.mdx b/apps/docs/content/docs/cn/react/migration/(components)/calendar.mdx
new file mode 100644
index 0000000..4234129
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/calendar.mdx
@@ -0,0 +1,455 @@
+---
+title: Calendar
+description: Calendar 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Calendar 文档](/docs/react/components/calendar)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Calendar` 是一个完全通过 props 配置的单一组件：
+
+```tsx
+import { Calendar } from "@heroui/react";
+
+export default function App() {
+  return <Calendar aria-label="Date" />;
+}
+```
+
+在 v3 中，Calendar 改用带显式子组件的复合组件模式：
+
+```tsx
+import { Calendar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Calendar aria-label="Date">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `Calendar` 组件，所有布局都在内部处理  
+**v3：** 复合组件：`Calendar.Header`、`Calendar.Heading`、`Calendar.NavButton`、`Calendar.Grid`、`Calendar.GridHeader`、`Calendar.GridBody`、`Calendar.HeaderCell`、`Calendar.Cell`、`Calendar.CellIndicator`
+
+### 2. 年份选择器
+
+**v2：** 通过 `showMonthAndYearPickers` prop 提供内置月份 / 年份选择器  
+**v3：** 使用专用复合组件：`Calendar.YearPickerTrigger`、`Calendar.YearPickerGrid`、`Calendar.YearPickerGridBody`、`Calendar.YearPickerCell`
+
+### 3. Prop 变更
+
+| v2 prop | v3 等效项 | 说明 |
+| ------- | ----------- | ---- |
+| `value` | `value` | 保持一致 |
+| `defaultValue` | `defaultValue` | 保持一致 |
+| `onChange` | `onChange` | 保持一致 |
+| `focusedValue` | `focusedValue` | 保持一致 |
+| `onFocusChange` | `onFocusChange` | 保持一致 |
+| `minValue` | `minValue` | 保持一致 |
+| `maxValue` | `maxValue` | 保持一致 |
+| `isDateUnavailable` | `isDateUnavailable` | 保持一致 |
+| `isDisabled` | `isDisabled` | 保持一致 |
+| `isReadOnly` | `isReadOnly` | 保持一致 |
+| `isInvalid` | `isInvalid` | 保持一致 |
+| `visibleMonths` | `visibleDuration` | 改为 `{months: number}` 对象 |
+| `showMonthAndYearPickers` | - | 使用 `Calendar.YearPickerTrigger` 和 `Calendar.YearPickerGrid` |
+| `onHeaderExpandedChange` | `onYearPickerOpenChange` | 已重命名 |
+| `color` | - | 已移除（请改用 Tailwind CSS） |
+| `calendarWidth` | - | 已移除（请改用 `className` 或 Tailwind CSS） |
+| `weekdayStyle` | - | 已移除 |
+| `pageBehavior` | `pageBehavior` | 保持一致 |
+| `firstDayOfWeek` | - | 改用 `I18nProvider` 的 locale |
+| `hideDisabledDates` | - | 已移除 |
+| `disableAnimation` | - | 已移除 |
+| `topContent` | - | 将自定义内容作为 `Calendar` children 放在 `Calendar.Grid` 之前 |
+| `bottomContent` | - | 将自定义内容作为 `Calendar` children 放在 `Calendar.Grid` 之后 |
+| `classNames` | - | 在各个复合组件上使用 `className` |
+| `errorMessage` | - | 已移除（请在外部处理校验） |
+
+### 4. color prop 已移除
+
+**v2：** `color` prop 支持 `default`、`primary`、`secondary`、`success`、`warning`、`danger`  
+**v3：** 不再提供 `color` prop，请使用 Tailwind CSS 类设置单元格样式，或通过自定义 `calendar.css` 覆盖
+
+## 迁移示例
+
+### 基本日历
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Calendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <Calendar
+      aria-label="Date"
+      defaultValue={today(getLocalTimeZone())}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Calendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <Calendar
+      aria-label="Date"
+      defaultValue={today(getLocalTimeZone())}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Calendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <Calendar
+      aria-label="Date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Calendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <Calendar
+      aria-label="Date"
+      value={value}
+      onChange={setValue}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 月份和年份选择器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {(year) => <Calendar.YearPickerCell date={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 多个月份
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      visibleMonths={2}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date" visibleDuration={{months: 2}}>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <div className="flex gap-4">
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => <Calendar.Cell date={date} />}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+        <Calendar.Grid offset={{months: 1}}>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => <Calendar.Cell date={date} />}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+      </div>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 不可用日期
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <Calendar
+      aria-label="Date"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <Calendar
+      aria-label="Date"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 顶部与底部内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      topContent={<p>Select a date</p>}
+      bottomContent={
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>
+          Today
+        </button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date">
+      <p>Select a date</p>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+      <button onClick={() => setValue(today(getLocalTimeZone()))}>
+        Today
+      </button>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 单元格指示器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have a built-in cell indicator API */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>
+        {(date) => (
+          <Calendar.Cell date={date}>
+            {({formattedDate}) => (
+              <>
+                {formattedDate}
+                {hasEvent(date) && <Calendar.CellIndicator />}
+              </>
+            )}
+          </Calendar.Cell>
+        )}
+      </Calendar.GridBody>
+    </Calendar.Grid>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Calendar
+  classNames={{
+    base: "custom-base",
+    prevButton: "custom-prev",
+    nextButton: "custom-next",
+    title: "custom-title",
+    cell: "custom-cell",
+    cellButton: "custom-cell-button",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Calendar className="custom-base">
+  <Calendar.Header>
+    <Calendar.Heading className="custom-title" />
+    <Calendar.NavButton slot="previous" className="custom-prev" />
+    <Calendar.NavButton slot="next" className="custom-next" />
+  </Calendar.Header>
+  <Calendar.Grid>
+    <Calendar.GridHeader>
+      {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+    </Calendar.GridHeader>
+    <Calendar.GridBody>
+      {(date) => <Calendar.Cell date={date} className="custom-cell" />}
+    </Calendar.GridBody>
+  </Calendar.Grid>
+</Calendar>
+```
+
+## 组件结构
+
+v3 Calendar 遵循以下结构：
+
+```
+Calendar (Root)
+  ├── [Custom top content]
+  ├── Calendar.Header
+  │   ├── Calendar.Heading (or Calendar.YearPickerTrigger)
+  │   ├── Calendar.NavButton slot="previous"
+  │   └── Calendar.NavButton slot="next"
+  ├── Calendar.Grid (one per visible month)
+  │   ├── Calendar.GridHeader
+  │   │   └── Calendar.HeaderCell (render prop)
+  │   └── Calendar.GridBody
+  │       └── Calendar.Cell (render prop)
+  │           └── Calendar.CellIndicator (optional)
+  ├── Calendar.YearPickerGrid (optional)
+  │   └── Calendar.YearPickerGridBody
+  │       └── Calendar.YearPickerCell
+  └── [Custom bottom content]
+```
+
+## 总结
+
+1. **组件结构**：单一组件 → 带显式布局控制的复合组件
+2. **年份选择器**：`showMonthAndYearPickers` prop → 专用的 `Calendar.YearPickerTrigger` 和 `Calendar.YearPickerGrid` 组件
+3. **多个月份**：`visibleMonths={n}` → `visibleDuration={{months: n}}`，并使用多个带 `offset` 的 `Calendar.Grid` 组件
+4. **color 已移除**：请改用 Tailwind CSS 类
+5. **顶部 / 底部内容**：prop 已移除 → 直接将内容作为 children 放在 `Calendar` 内
+6. **单元格自定义**：新增 `Calendar.CellIndicator`，且 `Calendar.Cell` 支持渲染 prop
+7. **样式**：`classNames` prop → 各个复合组件上的 `className`
+8. **已移除 prop**：`calendarWidth`、`weekdayStyle`、`hideDisabledDates`、`disableAnimation` —— 请使用 Tailwind CSS 或省略
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/card.mdx b/apps/docs/content/docs/cn/react/migration/(components)/card.mdx
new file mode 100644
index 0000000..09fb66a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/card.mdx
@@ -0,0 +1,320 @@
+---
+title: Card
+description: Card 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Card 文档](/docs/react/components/card)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Card 使用独立导出的子组件：`CardHeader`、`CardBody`、`CardFooter`。
+
+```tsx
+import { Card, CardHeader, CardBody, CardFooter } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Card>
+      <CardHeader>Header</CardHeader>
+      <CardBody>Body</CardBody>
+      <CardFooter>Footer</CardFooter>
+    </Card>
+  );
+}
+```
+
+在 v3 中，Card 使用复合组件模式，子部件以 `Card.*` 形式显式组合：
+
+```tsx
+import { Card } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Card>
+      <Card.Header>
+        <Card.Title>Title</Card.Title>
+        <Card.Description>Description</Card.Description>
+      </Card.Header>
+      <Card.Content>Body content</Card.Content>
+      <Card.Footer>Footer</Card.Footer>
+    </Card>
+  );
+}
+```
+
+## 关键变化
+
+### 1. 组件结构
+
+**v2：** 独立组件：`CardHeader`、`CardBody`、`CardFooter`  
+**v3：** 复合组件：`Card.Header`、`Card.Title`、`Card.Description`、`Card.Content`、`Card.Footer`
+
+### 2. 组件命名变化
+
+| v2 组件 | v3 组件 | 说明 |
+| --- | --- | --- |
+| `CardHeader` | `Card.Header` | 功能等价 |
+| `CardBody` | `Card.Content` | 已重命名 |
+| `CardFooter` | `Card.Footer` | 功能等价 |
+| — | `Card.Title` | 新增：用于标题区标题 |
+| — | `Card.Description` | 新增：用于标题区描述 |
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| --- | --- | --- |
+| `shadow` | — | 已移除（例如使用 Tailwind `shadow-sm`、`shadow-md`） |
+| `radius` | — | 已移除（例如使用 Tailwind `rounded-lg`） |
+| `fullWidth` | — | 已移除（例如使用 Tailwind `w-full`） |
+| `isHoverable` | — | 已移除（请使用 Tailwind 的 hover class） |
+| `isPressable` | — | 请在 Card 内使用 `button` 或 `a` 包裹可点击区域 |
+| `isBlurred`、`isFooterBlurred` | — | 已移除（例如使用 Tailwind `backdrop-blur-*`） |
+| `isDisabled` | — | 已移除（请使用条件渲染处理） |
+| `disableAnimation`、`disableRipple` | — | 已移除 |
+| `allowTextSelectionOnPress` | — | 已移除（不再适用） |
+| `classNames` | — | 在各子部件上使用 `className` |
+
+### 4. 变体
+
+**v2：** 无 `variant` prop（主要通过 shadow / radius 控制观感）  
+**v3：** 提供 `variant` prop：`transparent`、`default`、`secondary`、`tertiary`
+
+## 迁移示例
+
+### Card 结构
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Basic structure */}
+    <Card>
+      <CardHeader>Header</CardHeader>
+      <CardBody>Body content</CardBody>
+      <CardFooter>Footer</CardFooter>
+    </Card>
+    
+    {/* With title and description */}
+    <Card>
+      <CardHeader className="pb-0 pt-2 px-4 flex-col items-start">
+        <p className="text-tiny uppercase font-bold">Daily Mix</p>
+        <small className="text-default-500">12 Tracks</small>
+        <h4 className="font-bold text-large">Frontend Radio</h4>
+      </CardHeader>
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 基础结构 */}
+    <Card>
+      <Card.Header>
+        <Card.Title>Header</Card.Title>
+      </Card.Header>
+      <Card.Content>Body content</Card.Content>
+      <Card.Footer>Footer</Card.Footer>
+    </Card>
+    
+    {/* 标题 + 描述 */}
+    <Card>
+      <Card.Header>
+        <Card.Title>Frontend Radio</Card.Title>
+        <Card.Description>Daily Mix • 12 Tracks</Card.Description>
+      </Card.Header>
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### 可点击的 Card
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card 
+      isPressable 
+      shadow="sm" 
+      onPress={() => console.log("pressed")}
+    >
+      <CardBody>Clickable card</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card className="shadow-sm">
+      <button
+        type="button"
+        className="w-full cursor-pointer text-left"
+        onClick={() => console.log("pressed")}
+      >
+        <Card.Content>Clickable card</Card.Content>
+      </button>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### 带图片的 Card
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card className="py-4">
+      <CardHeader className="pb-0 pt-2 px-4 flex-col items-start">
+        <h4 className="font-bold text-large">Frontend Radio</h4>
+      </CardHeader>
+      <CardBody className="overflow-visible py-2">
+        <Image
+          alt="Card background"
+          className="object-cover rounded-xl"
+          src="https://example.com/image.jpg"
+          width={270}
+        />
+      </CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card className="py-4">
+      <Card.Header>
+        <Card.Title>Frontend Radio</Card.Title>
+      </Card.Header>
+      <Card.Content className="overflow-visible py-2">
+        <img
+          alt="Card background"
+          className="object-cover rounded-xl w-full"
+          src="https://example.com/image.jpg"
+        />
+      </Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### 页脚背景模糊（Blurred Footer）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Card, CardFooter, Image, Button } from "@heroui/react";
+
+    <Card isFooterBlurred className="border-none" radius="lg">
+      <Image
+        alt="Woman listing to music"
+        className="object-cover"
+        height={200}
+        src="https://example.com/image.jpg"
+        width={200}
+      />
+      <CardFooter className="justify-between before:bg-white/10 border-white/20 border-1 overflow-hidden py-1 absolute before:rounded-xl rounded-large bottom-1 w-[calc(100%_-_8px)] shadow-small ml-1 z-10">
+        <p className="text-tiny text-white/80">Available soon.</p>
+        <Button className="text-tiny text-white bg-black/20" size="sm">
+          Notify me
+        </Button>
+      </CardFooter>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Card, Button } from "@heroui/react";
+
+    <Card className="border-none rounded-lg relative overflow-hidden">
+      <img
+        alt="Woman listing to music"
+        className="object-cover w-full h-[200px]"
+        src="https://example.com/image.jpg"
+      />
+      <Card.Footer className="justify-between backdrop-blur-md bg-white/10 border-white/20 border overflow-hidden py-1 absolute rounded-lg bottom-1 w-[calc(100%_-_8px)] shadow-sm ml-1 z-10">
+        <p className="text-tiny text-white/80">Available soon.</p>
+        <Button className="text-tiny text-white bg-black/20" size="sm">
+          Notify me
+        </Button>
+      </Card.Footer>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Card 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have variants, uses shadow/radius */}
+    <Card shadow="md" radius="lg">
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card variant="default">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    <Card variant="secondary">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Card 
+  classNames={{
+    base: "custom-base",
+    header: "custom-header",
+    body: "custom-body",
+    footer: "custom-footer"
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Card className="custom-base">
+  <Card.Header className="custom-header">
+    <Card.Title>Title</Card.Title>
+  </Card.Header>
+  <Card.Content className="custom-body">
+    Content
+  </Card.Content>
+  <Card.Footer className="custom-footer">
+    Footer
+  </Card.Footer>
+</Card>
+```
+
+## 组件组成
+
+v3 的 Card 结构如下：
+
+```
+Card (Root)
+  ├── Card.Header (optional)
+  │   ├── Card.Title (optional)
+  │   └── Card.Description (optional)
+  ├── Card.Content (optional)
+  └── Card.Footer (optional)
+```
+
+## 总结
+
+1. **组件结构**：请使用复合组件，而不是 v2 的独立导出子组件。
+2. **`CardBody` → `Card.Content`**：组件已重命名。
+3. **新增子组件**：`Card.Title` 与 `Card.Description`，用于结构化标题区。
+4. **大量样式 prop 已移除**：请改用 Tailwind CSS class。
+5. **可点击 Card**：不要用 `isPressable`，改为在 Card 内使用 `button` 或链接。
+6. **模糊效果**：请使用 Tailwind `backdrop-blur-*` class，而不是相关 prop。
+7. **变体**：新增用于表达语义层级 / 视觉强调度的变体体系。
+8. **`classNames` 已移除**：在各子部件上使用 `className` prop。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/checkbox-group.mdx b/apps/docs/content/docs/cn/react/migration/(components)/checkbox-group.mdx
new file mode 100644
index 0000000..c7fd67c
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/checkbox-group.mdx
@@ -0,0 +1,163 @@
+---
+title: CheckboxGroup
+description: CheckboxGroup 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 CheckboxGroup 文档](/docs/react/components/checkbox-group)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`CheckboxGroup` 是单个组件，通过 `label` prop 描述分组，子项为简单的 `Checkbox`：
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CheckboxGroup label="Select interests">
+      <Checkbox value="coding">Coding</Checkbox>
+      <Checkbox value="design">Design</Checkbox>
+      <Checkbox value="writing">Writing</Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+在 v3 中，`CheckboxGroup` 仍是单个组件，但改为以 `Label` / `Description` 作为子节点，并使用全新的 Checkbox 复合结构：
+
+```tsx
+import { CheckboxGroup, Checkbox, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CheckboxGroup name="interests">
+      <Label>Select interests</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件名称保持一致
+
+**v2：** `CheckboxGroup`（单一组件，通过 `label` prop 描述分组）  
+**v3：** `CheckboxGroup`（单一组件，使用 `Label` 组件代替 `label` prop）
+
+### 2. Label prop
+
+**v2：** 在 `CheckboxGroup` 上使用 `label` prop  
+**v3：** 改用 `Label` 组件作为 `CheckboxGroup` 的子节点
+
+### 3. Checkbox 结构
+
+**v2：** 简单的 Checkbox 组件，子节点直接作为标签  
+**v3：** 复合 Checkbox 组件，由 `Checkbox.Content`、`Checkbox.Control` 与 `Checkbox.Indicator` 组成
+
+### 4. 事件处理函数
+
+**v2：** 使用 `onValueChange` prop  
+**v3：** 改用 `onChange` prop（来自 React Aria Components）
+
+### 5. 变体支持
+
+**v3：** 新增 `variant` prop，用于设置分组容器的样式
+
+## 迁移示例
+
+### 受控复选框组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+    const [selected, setSelected] = useState(["coding"]);
+
+    <CheckboxGroup
+      value={selected}
+      onValueChange={setSelected}
+      label="Select interests"
+    >
+      <Checkbox value="coding">Coding</Checkbox>
+      <Checkbox value="design">Design</Checkbox>
+      <Checkbox value="writing">Writing</Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { CheckboxGroup, Checkbox, Label } from "@heroui/react";
+
+    const [selected, setSelected] = useState(["coding"]);
+
+    <CheckboxGroup
+      name="interests"
+      value={selected}
+      onChange={setSelected}
+    >
+      <Label>Select interests</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+- 继续使用 `CheckboxGroup`；用 `Label` 子组件取代 `label` prop
+- 将 Checkbox 子项更新为复合组件结构（`Checkbox.Content`、`Checkbox.Control`、`Checkbox.Indicator`）
+- 将 `onValueChange` 改为 `onChange`
+- 添加 `name` prop 以便集成到表单中
+- 基于 React Aria Components 构建，更易实现无障碍
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/checkbox.mdx b/apps/docs/content/docs/cn/react/migration/(components)/checkbox.mdx
new file mode 100644
index 0000000..5198700
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/checkbox.mdx
@@ -0,0 +1,405 @@
+---
+title: Checkbox
+description: Checkbox 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Checkbox 文档](/docs/react/components/checkbox)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Checkbox` 将 `children` 作为标签文本：
+
+```tsx
+import { Checkbox } from "@heroui/react";
+
+export default function App() {
+  return <Checkbox defaultSelected>Option</Checkbox>;
+}
+```
+
+在 v3 中，Checkbox 采用复合组件模式，并使用显式子组件：
+
+```tsx
+import { Checkbox, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Checkbox defaultSelected id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 简单组件，`children` 即标签  
+**v3：** 复合组件：`Checkbox.Content`、`Checkbox.Control`、`Checkbox.Indicator`
+
+### 2. 标签处理
+
+**v2：** 标签直接作为 `children` 传入 `Checkbox`  
+**v3：** 标签放在 `Checkbox.Content`（可点击的标签）内；`Description` / `FieldError` 是 `Checkbox.Content` 的同级节点
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `onValueChange` | `Checkbox` | 请使用 `onChange` |
+| `color` | — | 已移除（请在 `Checkbox.Control` 上使用 Tailwind） |
+| `size` | — | 已移除（请使用 Tailwind，例如 `size-4`、`size-5`） |
+| `radius` | — | 已移除（请使用 Tailwind，例如 `rounded-sm`） |
+| `lineThrough` | — | 已移除（请在标签上使用 Tailwind `line-through`） |
+| `icon` | — | 请在 `Checkbox.Indicator` 内使用自定义内容 |
+| `classNames` | — | 请在各部分上使用 `className` |
+| `disableAnimation` | — | 已移除 |
+| — | `variant` | 新增 prop：`"primary"`（默认）或 `"secondary"`，用于较低强调度的样式 |
+
+### 4. CheckboxGroup 变化
+
+**v2：** `CheckboxGroup`（独立组件）使用 `label` prop，子节点为简单的 `Checkbox`  
+**v3：** `CheckboxGroup`（独立组件）将 `Label` / `Description` 作为子节点，且每个 `Checkbox` 使用复合结构
+
+迁移 CheckboxGroup 时请参阅 [CheckboxGroup 迁移指南](/docs/react/migration/checkbox-group)。
+
+## 迁移示例
+
+### 受控 Checkbox
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(false);
+
+    <Checkbox isSelected={isSelected} onValueChange={setIsSelected}>
+      Subscribe
+    </Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Label } from "@heroui/react";
+
+    const [isSelected, setIsSelected] = useState(false);
+
+    <Checkbox id="subscribe" isSelected={isSelected} onChange={setIsSelected}>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Subscribe
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### 含描述的 Checkbox
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 无内置描述 */}
+    <Checkbox defaultSelected>
+      Option
+    </Checkbox>
+    <p className="text-sm text-default-500">Description text</p>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Checkbox, Label, Description } from "@heroui/react";
+
+    <Checkbox id="option" defaultSelected>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+      <Description>Description text</Description>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### CheckboxGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+    <CheckboxGroup label="Select cities">
+      <Checkbox value="buenos-aires">Buenos Aires</Checkbox>
+      <Checkbox value="sydney">Sydney</Checkbox>
+      <Checkbox value="san-francisco">San Francisco</Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { CheckboxGroup, Checkbox, Label, Description } from "@heroui/react";
+
+    <CheckboxGroup name="cities">
+      <Label>Select cities</Label>
+      <Description>Choose all that apply</Description>
+      <Checkbox value="buenos-aires">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Buenos Aires
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="sydney">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Sydney
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="san-francisco">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          San Francisco
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 颜色与尺寸
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Colors */}
+    <Checkbox defaultSelected color="primary">Primary</Checkbox>
+    
+    {/* Sizes */}
+    <Checkbox defaultSelected size="md">Medium</Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Colors - use Tailwind classes */}
+    <Checkbox defaultSelected id="primary">
+      <Checkbox.Content>
+        <Checkbox.Control className="data-[selected=true]:bg-primary data-[selected=true]:border-primary">
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Primary
+      </Checkbox.Content>
+    </Checkbox>
+    
+    {/* Sizes - use Tailwind classes */}
+    <Checkbox defaultSelected id="medium">
+      <Checkbox.Content>
+        <Checkbox.Control className="size-5">
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Medium
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义图标 / 指示器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Checkbox defaultSelected icon={<HeartIcon />}>
+      Option
+    </Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Checkbox defaultSelected id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator>
+            {({isSelected}) => isSelected ? <HeartIcon /> : null}
+          </Checkbox.Indicator>
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+v3 引入 `variant` prop，可选 `"primary"`（默认）与 `"secondary"`：
+
+```tsx
+{/* Primary variant (default) */}
+<Checkbox variant="primary" id="primary-option">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Primary
+  </Checkbox.Content>
+</Checkbox>
+
+{/* Secondary variant - lower emphasis, suitable for Surface components */}
+<Checkbox variant="secondary" id="secondary-option">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Secondary
+  </Checkbox.Content>
+</Checkbox>
+```
+
+### 半选（indeterminate）状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Checkbox isIndeterminate>Option</Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Checkbox isIndeterminate id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+## 渲染 prop 模式
+
+v3 Checkbox 支持渲染 prop，用于暴露状态信息：
+
+```tsx
+<Checkbox id="terms">
+  {({isSelected, isIndeterminate, isHovered, isPressed, isFocused, isDisabled}) => (
+    <>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        
+          {isSelected ? "Terms accepted" : "Accept terms"}
+        
+      </Checkbox.Content>
+    </>
+  )}
+</Checkbox>
+```
+
+`Checkbox.Indicator` 也支持渲染 prop，并提供相同的状态字段。便于根据 Checkbox 状态渲染自定义指示器：
+
+```tsx
+<Checkbox id="custom">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator>
+        {({isSelected, isIndeterminate}) =>
+          isIndeterminate ? <MinusIcon /> : isSelected ? <CheckIcon /> : null
+        }
+      </Checkbox.Indicator>
+    </Checkbox.Control>
+    Custom indicator
+  </Checkbox.Content>
+</Checkbox>
+```
+
+可用的渲染 prop 字段：
+
+- `isSelected`：是否选中
+- `isIndeterminate`：是否为半选状态
+- `isHovered`：是否悬停
+- `isPressed`：是否处于按下中
+- `isFocused`：是否聚焦
+- `isFocusVisible`：是否应显示焦点环
+- `isDisabled`：是否禁用
+- `isReadOnly`：是否只读
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Checkbox 
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    icon: "custom-icon",
+    label: "custom-label"
+  }}
+/>
+```
+
+### v3：直接使用 `className`
+
+```tsx
+<Checkbox className="custom-base" id="option">
+  <Checkbox.Content>
+    <Checkbox.Control className="custom-control">
+      <Checkbox.Indicator className="custom-indicator" />
+    </Checkbox.Control>
+    
+      Option
+    
+  </Checkbox.Content>
+</Checkbox>
+```
+
+## 组件剖析
+
+v3 Checkbox 的结构如下：
+
+```
+Checkbox (Root)
+  ├── Checkbox.Content (the clickable label)
+  │   ├── Checkbox.Control
+  │   │   └── Checkbox.Indicator
+  │   └── Label
+  ├── Description (optional, sibling)
+  └── FieldError (optional, sibling)
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Button`、`Control`、`Indicator`）。
+2. **标签处理**：标签放在 `Checkbox.Content` 内。
+3. **`onValueChange` → `onChange`**：事件处理函数 prop 已重命名。
+4. **颜色已移除**：请在 `Checkbox.Control` 上使用 Tailwind CSS 类。
+5. **尺寸已移除**：请在 `Checkbox.Control` 上使用 Tailwind CSS 类。
+6. **圆角已移除**：请在 `Checkbox.Control` 上使用 Tailwind CSS 类。
+7. **`lineThrough` 已移除**：请在标签上使用 Tailwind `line-through` 类。
+8. **`icon` prop 已移除**：请在 `Checkbox.Indicator` 内使用自定义内容。
+9. **CheckboxGroup**：组件名不变；子节点使用 `Label` / `Description`，且 `Checkbox` 使用复合结构。
+10. **`classNames` 已移除**：请在各子组件上使用 `className`。
+11. **新增 `variant` prop**：支持 `"primary"`（默认）与 `"secondary"`，用于较低强调度样式。
+12. **指示器渲染 prop**：`Checkbox.Indicator` 可传入渲染函数，参数包含 `isSelected`、`isIndeterminate` 等状态。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/chip.mdx b/apps/docs/content/docs/cn/react/migration/(components)/chip.mdx
new file mode 100644
index 0000000..9a271fa
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/chip.mdx
@@ -0,0 +1,309 @@
+---
+title: Chip
+description: Chip 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Chip 文档](/docs/react/components/chip)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 关键变化
+
+### 1. 变体
+
+**v2：** `solid`、`bordered`、`light`、`flat`、`faded`、`shadow`、`dot`  
+**v3：** `primary`、`secondary`、`tertiary`、`soft`
+
+### 2. 颜色
+
+**v2：** `default`、`primary`、`secondary`、`success`、`warning`、`danger`  
+**v3：** `default`、`accent`、`success`、`warning`、`danger`
+
+### 3. 复合组件模式
+
+v3 引入复合组件模式，并提供 `Chip.Label` 子组件：
+
+- **`Chip.Label`**：渲染 Chip 内的标签文本。纯文本 `children` 会自动包在 `<Chip.Label>` 中，因此多数场景不必手写；需要自定义 `className` 时可显式使用。
+
+```tsx
+{/* Implicit label -- plain text is auto-wrapped in Chip.Label */}
+<Chip>Badge</Chip>
+
+{/* Explicit label -- useful when you need a custom className */}
+<Chip>
+  <Chip.Label className="uppercase tracking-wide">Badge</Chip.Label>
+</Chip>
+```
+
+### 4. 尺寸变体
+
+**v2：** `sm`、`md`、`lg`（通过 `size` prop）  
+**v3：** `sm`、`md`、`lg`（通过 `size` prop，API 相同）
+
+可用尺寸与 v2 一致，但 v3 通过 BEM 风格的 CSS class（`chip--sm`、`chip--md`、`chip--lg`）应用。默认尺寸为 `md`。
+
+```tsx
+<Chip size="sm">Small</Chip>
+<Chip size="md">Medium (default)</Chip>
+<Chip size="lg">Large</Chip>
+```
+
+### 5. 复合变体 class
+
+v3 支持组合变体与颜色 class，以实现更精细的样式。下列复合 class 在 CSS 中带有默认样式：
+
+**primary 变体组合：** `.chip--primary.chip--accent`、`.chip--primary.chip--success`、`.chip--primary.chip--warning`、`.chip--primary.chip--danger`
+
+**soft 变体组合：** `.chip--accent.chip--soft`、`.chip--success.chip--soft`、`.chip--warning.chip--soft`、`.chip--danger.chip--soft`
+
+你也可以在 CSS 中通过 `@layer components` 为其他任意组合（例如 `.chip--secondary.chip--accent`）补充样式。
+
+### 6. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| --- | --- | --- |
+| `radius` | — | 已移除（例如使用 Tailwind `rounded-full`） |
+| `avatar` | — | 使用 `children`（例如将 `<Avatar />` 作为第一个子节点） |
+| `startContent`、`endContent` | — | 直接使用 `children` |
+| `onClose` | — | 手动实现关闭（例如使用 `CloseButton`） |
+| `classNames` | — | 使用 `className` |
+| `isDisabled` | — | 使用条件渲染或 Tailwind（例如 `opacity-50`） |
+
+### 7. 变体映射
+
+| v2 变体 | v3 对应 | 说明 |
+| --- | --- | --- |
+| `solid` | `primary` | 实心背景 |
+| `bordered` | `secondary` | 边框 + 透明背景 |
+| `light` | `soft` | 浅色背景 |
+| `flat` | `tertiary` | 透明背景 |
+| `faded` | `secondary` | 观感相近 |
+| `shadow` | `primary` | 配合 Tailwind `shadow-*` class |
+| `dot` | — | 不再内置，请自行实现 |
+
+### 8. 颜色映射
+
+| v2 颜色 | v3 对应 | 说明 |
+| --- | --- | --- |
+| `default` | `default` | 相同 |
+| `primary` | `accent` | 已重命名 |
+| `secondary` | `default` 或 `accent` | 视场景选择 |
+| `success` | `success` | 相同 |
+| `warning` | `warning` | 相同 |
+| `danger` | `danger` | 相同 |
+
+## 结构变化
+
+在 v2 中，`Chip` 是一个通过大量 prop 控制样式的组件：
+
+```tsx
+import { Chip } from "@heroui/react";
+
+export default function App() {
+  return <Chip>Chip</Chip>;
+}
+```
+
+在 v3 中，`Chip` 的 API 更精简，变体更少：
+
+```tsx
+import { Chip } from "@heroui/react";
+
+export default function App() {
+  return <Chip>Chip</Chip>;
+}
+```
+
+## 迁移示例
+
+### 变体与颜色
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Variants */}
+    <Chip variant="solid">Solid</Chip>
+    <Chip variant="bordered">Bordered</Chip>
+    <Chip variant="light">Light</Chip>
+    
+    {/* Colors */}
+    <Chip color="primary">Primary</Chip>
+    <Chip color="success">Success</Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Variants */}
+    <Chip variant="primary">Primary</Chip>
+    <Chip variant="secondary">Secondary</Chip>
+    <Chip variant="soft">Soft</Chip>
+    
+    {/* Colors */}
+    <Chip color="accent">Accent</Chip>
+    <Chip color="success">Success</Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### 带图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* Start content */}
+    <Chip startContent={<Icon icon="gravity-ui:check" />}>
+      Chip
+    </Chip>
+    
+    {/* End content */}
+    <Chip endContent={<Icon icon="gravity-ui:chevron-down" />}>
+      Chip
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* 前置图标 */}
+    <Chip>
+      <Icon icon="gravity-ui:check" />
+      Chip
+    </Chip>
+    
+    {/* 后置图标 */}
+    <Chip>
+      Chip
+      <Icon icon="gravity-ui:chevron-down" />
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### 带 Avatar
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <Chip
+      avatar={<Avatar name="JW" src="https://example.com/avatar.jpg" />}
+      variant="flat"
+    >
+      Avatar
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Chip } from "@heroui/react";
+
+    <Chip variant="tertiary">
+      <Avatar size="sm">
+        <Avatar.Image src="https://example.com/avatar.jpg" alt="JW" />
+        <Avatar.Fallback>JW</Avatar.Fallback>
+      </Avatar>
+      Avatar
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### 带关闭按钮
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Chip onClose={() => console.log("close")}>
+      Chip
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { CloseButton } from "@heroui/react";
+
+    <Chip>
+      Chip
+      <CloseButton 
+        aria-label="Close chip"
+        onPress={() => console.log("close")}
+      />
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### 已移除的变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Dot variant */}
+    <Chip variant="dot">Dot</Chip>
+    
+    {/* Shadow variant */}
+    <Chip variant="shadow">Shadow</Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* dot：自行实现 */}
+    <Chip>
+      <Icon icon="gravity-ui:circle-fill" width={6} />
+      Dot
+    </Chip>
+    
+    {/* shadow：使用 Tailwind class */}
+    <Chip variant="primary" className="shadow-md">
+      Shadow
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Chip 
+  classNames={{
+    base: "custom-base",
+    content: "custom-content",
+    dot: "custom-dot",
+    avatar: "custom-avatar",
+    closeButton: "custom-close-button"
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Chip className="custom-base">
+  {/* Content with custom classes */}
+  <span className="custom-content">Chip</span>
+</Chip>
+```
+
+## 总结
+
+1. **变体收敛**：由 7 种变体收敛为 4 种。
+2. **颜色调整**：`primary` → `accent`，并弱化 `secondary` 的对应关系。
+3. **复合组件**：新增 `Chip.Label`；纯文本 `children` 会自动包在 `Chip.Label` 中。
+4. **尺寸变体**：仍可通过 `size` prop 使用 `sm`、`md`、`lg`，并以 BEM class（`chip--sm`、`chip--md`、`chip--lg`）落地。
+5. **复合变体 class**：变体 + 颜色组合（例如 `.chip--primary.chip--accent`、`.chip--soft.chip--success`）具备内置样式，并可在 `@layer components` 中扩展。
+6. **`radius` 已移除**：请改用 Tailwind CSS class。
+7. **`avatar` prop 已移除**：请改用 `children`。
+8. **`startContent` / `endContent` 已移除**：请改用 `children`。
+9. **关闭能力已移除**：请使用 `CloseButton` 自行组合。
+10. **`dot` 变体已移除**：请用图标等方式自行实现。
+11. **`shadow` 变体已移除**：请使用 Tailwind `shadow-*` class。
+12. **`isDisabled` prop 已移除**：请使用条件渲染或 CSS class。
+13. **`classNames` 已移除**：请直接使用 `className` prop。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/circular-progress.mdx b/apps/docs/content/docs/cn/react/migration/(components)/circular-progress.mdx
new file mode 100644
index 0000000..18ed8c6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/circular-progress.mdx
@@ -0,0 +1,228 @@
+---
+title: CircularProgress
+description: CircularProgress 从 HeroUI v2 到 v3（现在称为 ProgressCircle）的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 ProgressCircle 文档](/docs/react/components/progress-circle)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+<Callout type="warning">
+  正在寻找 Progress（线性）的迁移说明？请参阅 [Progress 迁移指南](/docs/react/migration/progress)。
+</Callout>
+
+## 组件重命名
+
+`CircularProgress` 在 v3 中已重命名为 `ProgressCircle`。
+
+## 结构变化
+
+在 v2 中，`CircularProgress` 是单个组件，通过 prop 进行配置：
+
+```tsx
+import { CircularProgress } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CircularProgress label="Loading..." value={60} />
+  );
+}
+```
+
+在 v3 中，`ProgressCircle` 改为复合组件模式：
+
+```tsx
+import { ProgressCircle } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `CircularProgress` 组件，SVG 在内部渲染  
+**v3：** 复合组件：`ProgressCircle`、`ProgressCircle.Track`（SVG 元素）、`ProgressCircle.TrackCircle`（背景圆环）、`ProgressCircle.FillCircle`（进度弧）
+
+### 2. 颜色
+
+**v2：** `default`、`primary`、`secondary`、`success`、`warning`、`danger`  
+**v3：** `default`、`accent`、`success`、`warning`、`danger`
+
+### 3. Prop 变更
+
+| v2 prop | v3 对应项 | 说明 |
+| ------- | --------- | ---- |
+| `value` | `value` | 相同 |
+| `minValue` | `minValue` | 相同 |
+| `maxValue` | `maxValue` | 相同 |
+| `isIndeterminate` | `isIndeterminate` | 默认值变化：v2 为 `true`，v3 为 `false` |
+| `formatOptions` | `formatOptions` | 相同 |
+| `size` | `size` | 相同（`sm`、`md`、`lg`） |
+| `color` | `color` | `primary` → `accent`，`secondary` 已移除 |
+| `label` | - | 改用 `Label` 组件 |
+| `valueLabel` | - | 改用 render prop 模式 |
+| `showValueLabel` | - | 将值的内容直接放入 `ProgressCircle` 中 |
+| `strokeWidth` | - | 直接设置在 `ProgressCircle.TrackCircle` 与 `ProgressCircle.FillCircle` 上 |
+| `isDisabled` | - | 已移除 |
+| `disableAnimation` | - | 已移除 |
+| `classNames` | - | 改在各复合子组件上使用 `className` |
+
+## 迁移示例
+
+### 基本环形进度
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { CircularProgress } from "@heroui/react";
+
+    <CircularProgress aria-label="Loading..." value={60} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressCircle } from "@heroui/react";
+
+    <ProgressCircle aria-label="Loading..." value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    ```
+  </Tab>
+</Tabs>
+
+### 不确定状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress aria-label="Loading..." />
+    {/* isIndeterminate defaults to true in v2 */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressCircle isIndeterminate aria-label="Loading...">
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    {/* isIndeterminate defaults to false in v3, must be explicit */}
+    ```
+  </Tab>
+</Tabs>
+
+### 带标签
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress
+      label="Loading..."
+      value={70}
+      showValueLabel
+      size="lg"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressCircle, Label } from "@heroui/react";
+
+    <div className="flex flex-col items-center gap-2">
+      <ProgressCircle aria-label="Loading" value={70} size="lg">
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <Label>Loading...</Label>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义 SVG prop
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress
+      value={60}
+      strokeWidth={6}
+      aria-label="Loading"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle strokeWidth={6} />
+        <ProgressCircle.FillCircle strokeWidth={6} />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变更
+
+### v2：`classNames` prop
+
+```tsx
+<CircularProgress
+  classNames={{
+    base: "custom-base",
+    svg: "custom-svg",
+    track: "custom-track",
+    indicator: "custom-fill",
+    label: "custom-label",
+    value: "custom-value",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<ProgressCircle className="custom-base" value={60}>
+  <ProgressCircle.Track className="custom-svg">
+    <ProgressCircle.TrackCircle className="custom-track" />
+    <ProgressCircle.FillCircle className="custom-fill" />
+  </ProgressCircle.Track>
+</ProgressCircle>
+```
+
+## 组件结构
+
+```
+ProgressCircle (Root)
+  └── ProgressCircle.Track (SVG element)
+      ├── ProgressCircle.TrackCircle (background circle)
+      └── ProgressCircle.FillCircle (progress arc)
+```
+
+## 总结
+
+1. **重命名**：`CircularProgress` → `ProgressCircle`
+2. **组件结构**：单组件 → 复合组件（`ProgressCircle.Track`、`ProgressCircle.TrackCircle`、`ProgressCircle.FillCircle`）
+3. **不确定状态默认值变化**：`isIndeterminate` 在 v3 中默认为 `false`（v2 中为 `true`）
+4. **标签**：`label` prop → `Label` 组件
+5. **SVG prop**：原本在根上的 `strokeWidth` → 直接设置在 `TrackCircle` 与 `FillCircle` 上
+6. **颜色变化**：`primary` → `accent`，`secondary` 已移除
+7. **移除的 prop**：`isDisabled`、`disableAnimation` → 请改用 Tailwind CSS
+8. **移除 classNames**：改在各复合子组件上使用 `className`
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/code.mdx b/apps/docs/content/docs/cn/react/migration/(components)/code.mdx
new file mode 100644
index 0000000..526094f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/code.mdx
@@ -0,0 +1,287 @@
+---
+title: Code
+description: Code 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  Code 组件已在 HeroUI v3 中**移除**。请改为使用原生 HTML `<code>` 元素，并配合 Tailwind CSS class 编写样式。
+</Callout>
+
+## 关键变化
+
+### 1. 组件移除
+
+**v2：** 来自 `@heroui/react` 的 `<Code>` 组件  
+**v3：** 原生 HTML `<code>` 元素与 Tailwind CSS class
+
+### 2. 变体映射
+
+v2 的 Code 组件提供以下变体，需要在迁移时替换：
+
+| v2 变体 | v3 对应 | 说明 |
+| --- | --- | --- |
+| `color="default"` | `bg-default/40 text-default-700` | 使用 Tailwind 不透明度工具类 |
+| `color="primary"` | `bg-accent/20 text-accent-600` | v3 中 `primary` 已重命名为 `accent` |
+| `color="secondary"` | `bg-default/40 text-default-700` | 与 default 相近 |
+| `color="success"` | `bg-success/20 text-success-700` | 颜色名相同 |
+| `color="warning"` | `bg-warning/20 text-warning-700` | 颜色名相同 |
+| `color="danger"` | `bg-danger/20 text-danger-600` | 颜色名相同 |
+| `size="sm"` | `text-sm` | Tailwind 字号 |
+| `size="md"` | `text-base` | Tailwind 字号 |
+| `size="lg"` | `text-lg` | Tailwind 字号 |
+| `radius="none"` | `rounded-none` | Tailwind 圆角 |
+| `radius="sm"` | `rounded-sm` | Tailwind 圆角 |
+| `radius="md"` | `rounded-md` | Tailwind 圆角 |
+| `radius="lg"` | `rounded-lg` | Tailwind 圆角 |
+| `radius="full"` | `rounded-full` | Tailwind 圆角 |
+
+## 结构变化
+
+在 v2 中，`Code` 是对原生 `<code>` 元素的组件封装：
+
+```tsx
+import { Code } from "@heroui/react";
+
+export default function App() {
+  return <Code>npm install @heroui/react</Code>;
+}
+```
+
+在 v3 中，请直接使用原生 `<code>` 元素，并为其添加 Tailwind CSS class：
+
+```tsx
+export default function App() {
+  return (
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+      npm install @heroui/react
+    </code>
+  );
+}
+```
+
+## 迁移示例
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Colors */}
+    <Code color="primary">Primary code</Code>
+    <Code color="success">Success code</Code>
+    
+    {/* Sizes */}
+    <Code size="md">Medium code</Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 颜色 */}
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-accent/20 text-accent-600 text-sm">
+      Primary code
+    </code>
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-success/20 text-success-700 text-sm">
+      Success code
+    </code>
+    
+    {/* 尺寸 */}
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-base">
+      Medium code
+    </code>
+    ```
+  </Tab>
+</Tabs>
+
+### 组合变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Code color="primary" size="md" radius="lg">
+      npm install @heroui/react
+    </Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-lg bg-accent/20 text-accent-600 text-base">
+      npm install @heroui/react
+    </code>
+    ```
+  </Tab>
+</Tabs>
+
+## 创建可复用的 Code 组件（可选）
+
+如果你经常需要行内代码样式，可以封装一个简单的包装组件：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Code } from "@heroui/react";
+
+    <Code color="primary" size="md">Code snippet</Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    // components/Code.tsx
+    import { cn } from "@/lib/utils"; // 或使用你自己的 cn 工具函数
+
+    interface CodeProps extends React.HTMLAttributes<HTMLElement> {
+      color?: "default" | "accent" | "success" | "warning" | "danger";
+      size?: "sm" | "md" | "lg";
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+    }
+
+    const colorClasses = {
+      default: "bg-default/40 text-default-700",
+      accent: "bg-accent/20 text-accent-600",
+      success: "bg-success/20 text-success-700",
+      warning: "bg-warning/20 text-warning-700",
+      danger: "bg-danger/20 text-danger-600",
+    };
+
+    const sizeClasses = {
+      sm: "text-sm",
+      md: "text-base",
+      lg: "text-lg",
+    };
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    export function Code({
+      children,
+      className,
+      color = "default",
+      size = "sm",
+      radius = "sm",
+      ...props
+    }: CodeProps) {
+      return (
+        <code
+          className={cn(
+            "px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap",
+            colorClasses[color],
+            sizeClasses[size],
+            radiusClasses[radius],
+            className
+          )}
+          {...props}
+        >
+          {children}
+        </code>
+      );
+    }
+
+    // 用法
+    <Code color="accent" size="md">Code snippet</Code>
+    ```
+  </Tab>
+</Tabs>
+
+## 完整示例
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Code } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <p>
+            Install HeroUI with <Code>npm install @heroui/react</Code>
+          </p>
+          <div className="flex gap-2">
+            <Code color="primary">Primary</Code>
+            <Code color="success">Success</Code>
+            <Code color="warning">Warning</Code>
+            <Code color="danger">Danger</Code>
+          </div>
+          <div className="flex gap-2 items-center">
+            <Code size="sm">Small</Code>
+            <Code size="md">Medium</Code>
+            <Code size="lg">Large</Code>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <p>
+            Install HeroUI with{" "}
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+              npm install @heroui/react
+            </code>
+          </p>
+          <div className="flex gap-2">
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-accent/20 text-accent-600 text-sm">
+              Primary
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-success/20 text-success-700 text-sm">
+              Success
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-warning/20 text-warning-700 text-sm">
+              Warning
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-danger/20 text-danger-600 text-sm">
+              Danger
+            </code>
+          </div>
+          <div className="flex gap-2 items-center">
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+              Small
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-base">
+              Medium
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-lg">
+              Large
+            </code>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 基础样式参考
+
+v2 的 Code 组件使用以下基础样式，迁移时建议一并保留：
+
+- `px-2` — 水平内边距
+- `py-1` — 垂直内边距
+- `h-fit` — 高度随内容收缩
+- `font-mono` — 等宽字体
+- `font-normal` — 常规字重
+- `inline-block` — 行内块级显示
+- `whitespace-nowrap` — 禁止换行
+
+## 总结
+
+1. **组件已移除**：v3 中不再提供 `Code` 组件。
+2. **导入调整**：移除 `import { Code } from "@heroui/react"`。
+3. **使用原生元素**：改为原生 `<code>` HTML 元素。
+4. **样式**：直接编写 Tailwind CSS class。
+5. **颜色映射**：在 v3 中将 `primary` 对应到 `accent` 色系 class。
+
+## 迁移步骤
+
+1. **移除导入**：从 `@heroui/react` 的导入中删除 `Code`。
+2. **替换组件**：将所有 `<Code>` 替换为 `<code>` 元素。
+3. **添加 Tailwind class**：为元素补充等价的样式 class。
+4. **更新颜色**：将 `color="primary"` 改为使用 `accent` 相关 class。
+5. **可选**：若行内代码使用频繁，可封装可复用的包装组件。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/date-picker.mdx b/apps/docs/content/docs/cn/react/migration/(components)/date-picker.mdx
new file mode 100644
index 0000000..d6dd5ac
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/date-picker.mdx
@@ -0,0 +1,457 @@
+---
+title: DatePicker
+description: DatePicker 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 DatePicker 文档](/docs/react/components/date-picker)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`DatePicker` 是一个自包含组件，通过 props 处理标签、描述、日历和时间输入：
+
+```tsx
+import { DatePicker } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DatePicker label="Birth date" />
+  );
+}
+```
+
+在 v3 中，DatePicker 改用组合优先的 API，你需要显式组合 `DateField` 与 `Calendar`：
+
+```tsx
+import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DatePicker>
+      <Label>Birth date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `DatePicker` 组件，所有部分（输入、日历、标签、popover）都通过 props 在内部处理  
+**v3：** 基于组合的 API，由 `DatePicker`、`DateField`、`Calendar` 和 `Label` 共同组成。每个部分都是独立组件。
+
+### 2. 组成部分
+
+| v3 组件 | 描述 |
+| ------- | ---- |
+| `DatePicker` | 根容器与状态持有者 |
+| `DatePicker.Trigger` | 打开日历 popover 的按钮 |
+| `DatePicker.TriggerIndicator` | 日历图标（默认）或自定义指示器 |
+| `DatePicker.Popover` | 日历的 popover 包装层 |
+| `DateField.Group` | 输入组包装层 |
+| `DateField.Input` | 分段日期输入 |
+| `DateField.Segment` | 单独的日期片段（月、日、年） |
+| `DateField.Suffix` | 触发按钮的后缀 slot |
+| `Calendar` | 完整的日历组件（参见 [Calendar 迁移](/docs/react/migration/calendar)） |
+| `Label` | 外部 Label 组件 |
+
+### 3. Prop 变更
+
+| v2 prop | v3 等效项 | 说明 |
+| ------- | ----------- | ---- |
+| `value` | `value` | 保持一致 |
+| `defaultValue` | `defaultValue` | 保持一致 |
+| `onChange` | `onChange` | 保持一致 |
+| `minValue` | `minValue` | 保持一致 |
+| `maxValue` | `maxValue` | 保持一致 |
+| `isDateUnavailable` | `isDateUnavailable` | 保持一致 |
+| `isDisabled` | `isDisabled` | 保持一致 |
+| `isReadOnly` | `isReadOnly` | 保持一致 |
+| `isRequired` | `isRequired` | 保持一致 |
+| `isInvalid` | `isInvalid` | 保持一致 |
+| `granularity` | `granularity` | 保持一致 |
+| `hourCycle` | `hourCycle` | 保持一致 |
+| `hideTimeZone` | `hideTimeZone` | 保持一致 |
+| `shouldForceLeadingZeros` | `shouldForceLeadingZeros` | 保持一致 |
+| `pageBehavior` | - | 直接设置在 `Calendar` 上 |
+| `label` | - | 使用 `Label` 组件 |
+| `description` | - | 使用 `Description` 组件 |
+| `errorMessage` | - | 使用 `FieldError` 组件 |
+| `variant` | - | 使用 `DateField.Group` 的 `variant` prop 或 Tailwind CSS |
+| `color` | - | 已移除（请改用 Tailwind CSS） |
+| `size` | - | 已移除（请改用 Tailwind CSS） |
+| `radius` | - | 已移除（请改用 Tailwind CSS） |
+| `labelPlacement` | - | 使用 Tailwind CSS 控制布局 |
+| `startContent` | - | 在 `DateField.Group` 内组合 |
+| `endContent` | - | 在 `DateField.Group` 内组合 |
+| `selectorIcon` | - | 将 children 传给 `DatePicker.TriggerIndicator` |
+| `visibleMonths` | - | 使用 `Calendar` 的 `visibleDuration` prop |
+| `showMonthAndYearPickers` | - | 使用 `Calendar.YearPickerTrigger` 和 `Calendar.YearPickerGrid` |
+| `calendarProps` | - | 直接将 props 传给 `Calendar` |
+| `popoverProps` | - | 直接将 props 传给 `DatePicker.Popover` |
+| `selectorButtonProps` | - | 直接将 props 传给 `DatePicker.Trigger` |
+| `timeInputProps` | - | 单独组合时间输入 |
+| `CalendarBottomContent` | - | 将内容放在 `DatePicker.Popover` 内、`Calendar` 之后 |
+| `validate` | - | 在外部处理校验 |
+| `placeholderValue` | `placeholderValue` | 保持一致 |
+| `autoFocus` | `autoFocus` | 保持一致 |
+| `disableAnimation` | - | 已移除 |
+| `classNames` | - | 在各个组件上使用 `className` |
+
+## 迁移示例
+
+### 基本日期选择器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { DatePicker } from "@heroui/react";
+
+    <DatePicker label="Birth date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+
+    <DatePicker>
+      <Label>Birth date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { DatePicker } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <DatePicker
+      label="Date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <DatePicker value={value} onChange={setValue}>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.Heading />
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 带描述和错误信息
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DatePicker
+      label="Event date"
+      description="Choose a future date"
+      errorMessage="Date must be in the future"
+      isInvalid={isInvalid}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DatePicker, DateField, Calendar, Label, Description, FieldError } from "@heroui/react";
+
+    <DatePicker isInvalid={isInvalid}>
+      <Label>Event date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Choose a future date</Description>
+      <FieldError>Date must be in the future</FieldError>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          {/* Calendar compound components */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义选择器图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DatePicker
+      label="Date"
+      selectorIcon={<Icon icon="gravity-ui:calendar" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DatePicker>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator>
+              <Icon icon="gravity-ui:calendar" />
+            </DatePicker.TriggerIndicator>
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          {/* Calendar compound components */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 带月份 / 年份选择器和日历底部内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DatePicker
+      label="Date"
+      showMonthAndYearPickers
+      CalendarBottomContent={
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>Today</button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DatePicker>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {(year) => <Calendar.YearPickerCell date={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>Today</button>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<DatePicker
+  classNames={{
+    base: "custom-base",
+    selectorButton: "custom-trigger",
+    selectorIcon: "custom-icon",
+    popoverContent: "custom-popover",
+    calendar: "custom-calendar",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<DatePicker className="custom-base">
+  <Label>Date</Label>
+  <DateField.Group>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+    <DateField.Suffix>
+      <DatePicker.Trigger className="custom-trigger">
+        <DatePicker.TriggerIndicator className="custom-icon" />
+      </DatePicker.Trigger>
+    </DateField.Suffix>
+  </DateField.Group>
+  <DatePicker.Popover className="custom-popover">
+    <Calendar aria-label="Choose date" className="custom-calendar">
+      {/* Calendar compound components */}
+    </Calendar>
+  </DatePicker.Popover>
+</DatePicker>
+```
+
+## 组件结构
+
+v3 DatePicker 遵循以下结构：
+
+```
+DatePicker (Root)
+  ├── Label
+  ├── DateField.Group
+  │   ├── DateField.Input
+  │   │   └── DateField.Segment (render prop per segment)
+  │   └── DateField.Suffix
+  │       └── DatePicker.Trigger
+  │           └── DatePicker.TriggerIndicator
+  ├── Description (optional)
+  ├── FieldError (optional)
+  └── DatePicker.Popover
+      ├── Calendar (see Calendar migration guide)
+      └── [Custom bottom content]
+```
+
+## 总结
+
+1. **组件结构**：单一组件 → 由 `DatePicker`、`DateField`、`Calendar` 和 `Label` 组合而成
+2. **标签**：`label` prop → `Label` 组件
+3. **描述 / 错误信息**：props → `Description` 和 `FieldError` 组件
+4. **日历**：内置日历 → 在 `DatePicker.Popover` 内组合带有自身复合组件的 `Calendar`
+5. **选择器图标**：`selectorIcon` prop → 将 children 传给 `DatePicker.TriggerIndicator`
+6. **年份选择器**：`showMonthAndYearPickers` prop → 使用 `Calendar.YearPickerTrigger` 和 `Calendar.YearPickerGrid`
+7. **日历底部内容**：`CalendarBottomContent` prop → 将内容放在 `DatePicker.Popover` 内、`Calendar` 之后
+8. **已移除样式 prop**：`variant`、`color`、`size`、`radius` → 使用 Tailwind CSS 或 `DateField.Group` 的变体
+9. **已移除 classNames**：在各个复合组件上使用 `className`
+10. **多个月份**：`visibleMonths` prop → 使用 `Calendar` 的 `visibleDuration` prop
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/date-range-picker.mdx b/apps/docs/content/docs/cn/react/migration/(components)/date-range-picker.mdx
new file mode 100644
index 0000000..87eef4e
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/date-range-picker.mdx
@@ -0,0 +1,522 @@
+---
+title: DateRangePicker
+description: DateRangePicker 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 DateRangePicker 文档](/docs/react/components/date-range-picker)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`DateRangePicker` 是单一自包含组件，通过 prop 配置标签、输入、日历与时间字段等：
+
+```tsx
+import { DateRangePicker } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateRangePicker label="Trip dates" />
+  );
+}
+```
+
+在 v3 中，DateRangePicker 采用“组合优先”的 API，需要你显式组合 `DateField` 与 `RangeCalendar`：
+
+```tsx
+import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `DateRangePicker`，两个输入、分隔符、日历、标签、popover 等主要由内部 prop 处理。  
+**v3：** 组合式 API：将 `DateRangePicker`、`DateField`、`RangeCalendar` 与 `Label` 等组合在一起；两个 `DateField.Input` 分别使用 `slot="start"` 与 `slot="end"` 表示范围输入。
+
+### 2. 组合结构说明
+
+| v3 组件                           | 说明                                                         |
+| --------------------------------- | ------------------------------------------------------------ |
+| `DateRangePicker`                 | 根容器与状态持有者                                           |
+| `DateRangePicker.Trigger`         | 打开日历 popover 的按钮                                     |
+| `DateRangePicker.TriggerIndicator`| 日历图标（默认）或自定义指示器                               |
+| `DateRangePicker.RangeSeparator`  | 开始/结束日期输入之间的分隔符（默认 `" - "`）               |
+| `DateRangePicker.Popover`         | 包裹范围日历的 popover                                       |
+| `DateField.Group`                 | 输入组外层                                                   |
+| `DateField.InputContainer`        | 开始/结束输入与分隔符容器                                   |
+| `DateField.Input slot="start"`    | 开始日期的分段输入                                           |
+| `DateField.Input slot="end"`      | 结束日期的分段输入                                           |
+| `DateField.Segment`               | 单个日期片段（月/日/年等）                                   |
+| `DateField.Suffix`                | 触发按钮的后缀插槽                                           |
+| `RangeCalendar`                   | 完整范围日历（参见 [RangeCalendar 迁移](/docs/react/migration/range-calendar)） |
+| `Label`                           | 外部标签组件                                                 |
+
+### 3. Prop 变更
+
+| v2 prop                   | v3 对应                         | 说明                                                         |
+| ------------------------- | ------------------------------- | ------------------------------------------------------------ |
+| `value`                   | `value`                         | 相同                                                         |
+| `defaultValue`            | `defaultValue`                  | 相同                                                         |
+| `onChange`                | `onChange`                      | 相同                                                         |
+| `minValue`                | `minValue`                      | 相同                                                         |
+| `maxValue`                | `maxValue`                      | 相同                                                         |
+| `isDisabled`              | `isDisabled`                    | 相同                                                         |
+| `isReadOnly`              | `isReadOnly`                    | 相同                                                         |
+| `isRequired`              | `isRequired`                    | 相同                                                         |
+| `isInvalid`               | `isInvalid`                     | 相同                                                         |
+| `isOpen`                  | `isOpen`                        | 相同                                                         |
+| `defaultOpen`             | `defaultOpen`                   | 相同                                                         |
+| `onOpenChange`            | `onOpenChange`                  | 相同                                                         |
+| `granularity`             | `granularity`                   | 相同                                                         |
+| `hourCycle`               | `hourCycle`                     | 相同                                                         |
+| `hideTimeZone`            | `hideTimeZone`                  | 相同                                                         |
+| `shouldForceLeadingZeros` | `shouldForceLeadingZeros`       | 相同                                                         |
+| `allowsNonContiguousRanges` | —                             | 直接在 `RangeCalendar` 上设置                                |
+| `pageBehavior`            | —                               | 直接在 `RangeCalendar` 上设置                                |
+| `label`                   | —                               | 使用 `Label` 组件                                            |
+| `description`             | —                               | 使用 `Description` 组件                                      |
+| `errorMessage`            | —                               | 使用 `FieldError` 组件                                       |
+| `variant`                 | —                               | 使用 `DateField.Group` 的 `variant` prop，或 Tailwind CSS    |
+| `color`                   | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `size`                    | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `radius`                  | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `labelPlacement`          | —                               | 用 Tailwind CSS 控制布局                                     |
+| `selectorIcon`            | —                               | 将 children 传给 `DateRangePicker.TriggerIndicator`          |
+| `selectorButtonPlacement` | —                               | 通过 `DateField.Prefix` 或 `DateField.Suffix` 组合触发器位置 |
+| `visibleMonths`           | —                               | 使用 `RangeCalendar` 的 `visibleDuration` prop               |
+| `showMonthAndYearPickers` | —                               | 使用 `RangeCalendar.YearPickerTrigger` 与 `RangeCalendar.YearPickerGrid` |
+| `calendarProps`           | —                               | 直接将 prop 传给 `RangeCalendar`                           |
+| `popoverProps`            | —                               | 直接将 prop 传给 `DateRangePicker.Popover`                   |
+| `selectorButtonProps`     | —                               | 直接将 prop 传给 `DateRangePicker.Trigger`                   |
+| `timeInputProps`          | —                               | 时间输入需单独组合实现                                       |
+| `calendarWidth`           | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `validate`                | —                               | 在外部处理校验                                               |
+| `placeholderValue`        | `placeholderValue`              | 相同                                                         |
+| `autoFocus`               | `autoFocus`                     | 相同                                                         |
+| `disableAnimation`        | —                               | 已移除                                                       |
+| `classNames`              | —                               | 在各子组件上使用 `className`                                 |
+
+## 迁移示例
+
+### 基础 DateRangePicker
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { DateRangePicker } from "@heroui/react";
+
+    <DateRangePicker label="Trip dates" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { DateRangePicker } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-14"),
+    });
+
+    <DateRangePicker
+      label="Trip dates"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-14"),
+    });
+
+    <DateRangePicker value={value} onChange={setValue}>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.Heading />
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 描述与错误信息
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateRangePicker
+      label="Trip dates"
+      description="Select your travel period"
+      errorMessage="End date must be after start date"
+      isInvalid={isInvalid}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DateField, DateRangePicker, Label, Description, FieldError, RangeCalendar } from "@heroui/react";
+
+    <DateRangePicker isInvalid={isInvalid}>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Select your travel period</Description>
+      <FieldError>End date must be after start date</FieldError>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          {/* RangeCalendar compound components */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义选择器图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DateRangePicker
+      label="Trip dates"
+      selectorIcon={<Icon icon="gravity-ui:calendar" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator>
+              <Icon icon="gravity-ui:calendar" />
+            </DateRangePicker.TriggerIndicator>
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          {/* RangeCalendar compound components */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### 多月份显示与年份选择器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateRangePicker
+      label="Trip dates"
+      visibleMonths={2}
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates" visibleDuration={{months: 2}}>
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <div className="flex gap-4">
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.Grid offset={{months: 1}}>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+          </div>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {(year) => <RangeCalendar.YearPickerCell date={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式相关变化
+
+### v2：`classNames` prop
+
+```tsx
+<DateRangePicker
+  classNames={{
+    base: "custom-base",
+    label: "custom-label",
+    selectorButton: "custom-trigger",
+    selectorIcon: "custom-icon",
+    separator: "custom-separator",
+    popoverContent: "custom-popover",
+    calendar: "custom-calendar",
+  }}
+/>
+```
+
+### v3：直接使用 `className`
+
+```tsx
+<DateRangePicker className="custom-base">
+  <Label className="custom-label">Trip dates</Label>
+  <DateField.Group>
+    <DateField.InputContainer>
+      <DateField.Input slot="start">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateRangePicker.RangeSeparator className="custom-separator" />
+      <DateField.Input slot="end">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+    </DateField.InputContainer>
+    <DateField.Suffix>
+      <DateRangePicker.Trigger className="custom-trigger">
+        <DateRangePicker.TriggerIndicator className="custom-icon" />
+      </DateRangePicker.Trigger>
+    </DateField.Suffix>
+  </DateField.Group>
+  <DateRangePicker.Popover className="custom-popover">
+    <RangeCalendar aria-label="Choose trip dates" className="custom-calendar">
+      {/* RangeCalendar compound components */}
+    </RangeCalendar>
+  </DateRangePicker.Popover>
+</DateRangePicker>
+```
+
+## 组件结构（Anatomy）
+
+v3 的 DateRangePicker 结构如下：
+
+```
+DateRangePicker (Root)
+  ├── Label
+  ├── DateField.Group
+  │   ├── DateField.InputContainer
+  │   │   ├── DateField.Input slot="start"
+  │   │   │   └── DateField.Segment（每个 segment 的渲染 prop）
+  │   │   ├── DateRangePicker.RangeSeparator
+  │   │   └── DateField.Input slot="end"
+  │   │       └── DateField.Segment（每个 segment 的渲染 prop）
+  │   └── DateField.Suffix
+  │       └── DateRangePicker.Trigger
+  │           └── DateRangePicker.TriggerIndicator
+  ├── Description (optional)
+  ├── FieldError (optional)
+  └── DateRangePicker.Popover
+      └── RangeCalendar (参见 RangeCalendar 迁移指南)
+```
+
+## 总结
+
+1. **组件结构**：由单一组件 → 组合 `DateRangePicker`、`DateField`、`RangeCalendar` 与 `Label` 等。
+2. **双输入**：内置起止输入 → 两个 `DateField.Input`，分别使用 `slot="start"` 与 `slot="end"`。
+3. **分隔符**：内置分隔 → `DateRangePicker.RangeSeparator`。
+4. **标签**：`label` prop → `Label` 组件。
+5. **描述/错误**：prop → `Description` 与 `FieldError` 组件。
+6. **日历**：内置日历 → 在 `DateRangePicker.Popover` 内组合 `RangeCalendar` 及其子组件。
+7. **选择器图标**：`selectorIcon` prop → 将 children 传给 `DateRangePicker.TriggerIndicator`。
+8. **年份选择器**：`showMonthAndYearPickers` prop → 使用 `RangeCalendar.YearPickerTrigger` 与 `RangeCalendar.YearPickerGrid`。
+9. **样式类 prop 移除**：`variant`、`color`、`size`、`radius` → 使用 Tailwind CSS，或 `DateField.Group` 的 `variant`。
+10. **`classNames` 移除**：在各复合子组件上使用 `className`。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/dateinput.mdx b/apps/docs/content/docs/cn/react/migration/(components)/dateinput.mdx
new file mode 100644
index 0000000..16a7520
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/dateinput.mdx
@@ -0,0 +1,342 @@
+---
+title: DateInput
+description: DateInput 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 DateField 文档](/docs/react/components/date-field)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`DateInput` 是单个通过 props 配置的组件：
+
+```tsx
+import { DateInput } from "@heroui/react";
+
+export default function App() {
+  return <DateInput label="Date" name="date" />;
+}
+```
+
+在 v3 中，`DateField` 需要配合 `DateInputGroup` 使用复合组件，并通过 render prop 渲染各段位（segment）：
+
+```tsx
+import { DateField, DateInputGroup, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件命名
+
+**v2：** `DateInput`  
+**v3：** `DateField`
+
+### 2. 组件结构
+
+**v2：** 单个带 props 的组件  
+**v3：** 复合组件：`DateField`（根）+ `DateInputGroup`，其中包含 `DateInputGroup.Input`（render prop）与 `DateInputGroup.Segment`；可选 `DateInputGroup.Prefix` 与 `DateInputGroup.Suffix`
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `label` | — | 已移除（请使用 `Label` 组件） |
+| `description` | — | 已移除（请使用 `Description` 组件） |
+| `errorMessage` | — | 已移除（请使用 `FieldError` 组件） |
+| `value`, `defaultValue`, `onChange` | `DateField` | 相同（React Aria） |
+| `minValue`, `maxValue`, `granularity`, `placeholderValue` | `DateField` | 相同 |
+| `isRequired`, `isDisabled`, `isReadOnly`, `isInvalid`, `name` | `DateField` | 相同 |
+| `createCalendar`, `validationBehavior` | `DateField` | 相同 |
+| `variant` | `DateInputGroup` | 仅简化为 `primary` \| `secondary` |
+| `fullWidth` | `DateField` 或 `DateInputGroup` | 可在根或组上设置 |
+| `color` | — | 已移除（请使用 Tailwind CSS） |
+| `size` | — | 已移除（请使用 Tailwind CSS） |
+| `radius` | — | 已移除（请使用 Tailwind CSS） |
+| `labelPlacement` | — | 已移除（请通过布局自行处理） |
+| `startContent` | `DateInputGroup.Prefix` | 使用 Prefix 子节点 |
+| `endContent` | `DateInputGroup.Suffix` | 使用 Suffix 子节点 |
+| `classNames` | — | 请在 `DateField` 与 `DateInputGroup` 各部分使用 `className` |
+| `groupProps` | — | 已移除（请在 `DateInputGroup` 上使用 `className` 或 DOM 属性） |
+| `labelProps` | — | 已移除（请在 `Label` 上使用 `className`） |
+| `fieldProps` | — | 已移除（请在 `DateInputGroup` 上使用 `className`） |
+| `innerWrapperProps` | — | 已移除（请在组 / 输入相关部分使用 `className`） |
+| `descriptionProps` | — | 已移除（请在 `Description` 上使用 `className`） |
+| `errorMessageProps` | — | 已移除（请在 `FieldError` 上使用 `className`） |
+| `inputRef` | — | 已移除（ref 由 `DateField` / React Aria 处理） |
+
+## 迁移示例
+
+### 基础用法
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput label="Date" name="date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 含描述与错误
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput
+      description="Select your birth date"
+      label="Birth date"
+      name="birthdate"
+    />
+
+    <DateInput
+      errorMessage="Please enter a valid date"
+      isInvalid
+      label="Date"
+      name="date"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    <DateField className="w-[256px]" name="birthdate">
+      <Label>Birth date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <Description>Select your birth date</Description>
+    </DateField>
+
+    <DateField className="w-[256px]" isInvalid name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <FieldError>Please enter a valid date</FieldError>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 必填
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput isRequired label="Date" name="date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" isRequired name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState(null);
+
+    <DateInput
+      label="Date"
+      name="date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import type { DateValue } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState<DateValue | null>(null);
+
+    <DateField
+      className="w-[256px]"
+      name="date"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 最小值、最大值与粒度
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+
+    <DateInput
+      granularity="day"
+      label="Date"
+      maxValue={parseDate("2025-12-31")}
+      minValue={parseDate("2020-01-01")}
+      name="date"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+
+    <DateField
+      className="w-[256px]"
+      granularity="day"
+      maxValue={parseDate("2025-12-31")}
+      minValue={parseDate("2020-01-01")}
+      name="date"
+    >
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 起始与结束内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput
+      endContent={<CalendarIcon />}
+      label="Date"
+      name="date"
+      startContent={<CalendarIcon />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Prefix>
+          <CalendarIcon />
+        </DateInputGroup.Prefix>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+        <DateInputGroup.Suffix>
+          <CalendarIcon />
+        </DateInputGroup.Suffix>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput label="Date" name="date" variant="bordered" />
+    <DateInput color="primary" label="Date" name="date" size="lg" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup variant="primary">
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup variant="secondary">
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件组成
+
+v3 `DateField` 的结构如下：
+
+```
+DateField (Root)
+  ├── Label (optional)
+  ├── DateInputGroup
+  │   ├── DateInputGroup.Prefix (optional)
+  │   ├── DateInputGroup.Input → (segment) => DateInputGroup.Segment
+  │   └── DateInputGroup.Suffix (optional)
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## 总结
+
+1. **组件已重命名**：`DateInput` → `DateField`
+2. **组件结构**：必须使用复合组件：`DateField`（根）、`DateInputGroup`，以及 `DateInputGroup.Input`（render prop）与 `DateInputGroup.Segment`
+3. **标签 / 描述 / 错误**：请使用独立组件（`Label`、`Description`、`FieldError`）
+4. **日期相关 prop 不变**：`value`、`defaultValue`、`onChange`、`minValue`、`maxValue`、`granularity`、`placeholderValue`、`isRequired`、`isDisabled`、`isInvalid`、`name`、`createCalendar` 等仍位于 `DateField`
+5. **`DateInputGroup` 的变体**：v3 仅在 `DateInputGroup` 上支持 `variant="primary"` 与 `variant="secondary"`；`color`、`size`、`radius` 已移除 — 请使用 Tailwind CSS
+6. **起始 / 结束内容**：`startContent` / `endContent` → `DateInputGroup.Prefix` 与 `DateInputGroup.Suffix`
+7. **`labelPlacement` 已移除**：请通过布局自行处理
+8. **DOM / 类名相关 prop**：`groupProps`、`labelProps`、`fieldProps`、`classNames` 已移除 — 请在对应部分使用 `className`（及标准 DOM 属性）
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/divider.mdx b/apps/docs/content/docs/cn/react/migration/(components)/divider.mdx
new file mode 100644
index 0000000..02d51dd
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/divider.mdx
@@ -0,0 +1,99 @@
+---
+title: Divider
+description: Divider（已重命名为 Separator）从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Separator 文档](/docs/react/components/separator)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 组件重命名
+
+**v2：** `Divider`  
+**v3：** `Separator`
+
+## 主要变化
+
+### 1. 组件名称
+
+**v2：** `Divider`  
+**v3：** `Separator`
+
+### 2. 变体 prop
+
+**v3：** Separator 新增 `variant` prop，可选 `default`、`secondary`、`tertiary`，对应不同的强调层级（v2 的 Divider 没有变体）。
+
+### 3. Prop 对比
+
+| 属性 | v2 | v3 | 说明 |
+| ---- | -- | -- | ---- |
+| `orientation` | ✅ | ✅ | 相同：`"horizontal"` \| `"vertical"` |
+| `className` | ✅ | ✅ | 相同 |
+| `variant` | ❌ | ✅ | 新增：`"default"` \| `"secondary"` \| `"tertiary"` |
+
+## 结构变化
+
+在 v2 中，组件名为 `Divider`：
+
+```tsx
+import { Divider } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div>
+      <p>Content above</p>
+      <Divider />
+      <p>Content below</p>
+    </div>
+  );
+}
+```
+
+在 v3 中，组件已重命名为 `Separator`：
+
+```tsx
+import { Separator } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div>
+      <p>Content above</p>
+      <Separator />
+      <p>Content below</p>
+    </div>
+  );
+}
+```
+
+## 迁移示例
+
+### 使用变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 没有 variant prop */}
+    <Divider />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Separator />
+    <Separator variant="secondary" />
+    <Separator variant="tertiary" />
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+1. **组件已重命名**：`Divider` → `Separator`
+2. **导入变化**：将导入从 `Divider` 更新为 `Separator`
+3. **v3 新增功能**：`variant` prop（`default`、`secondary`、`tertiary`），用于区分强调层级
+
+## 迁移步骤
+
+1. **更新导入**：将 `import { Divider }` 改为 `import { Separator }`
+2. **替换组件**：把所有 `<Divider />` 替换为 `<Separator />`
+3. **保留相同的 prop**：`orientation` 与 `className` 行为不变
+4. **可选**：使用 `variant="secondary"` 或 `variant="tertiary"` 表达不同的强调层级
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/drawer.mdx b/apps/docs/content/docs/cn/react/migration/(components)/drawer.mdx
new file mode 100644
index 0000000..fd97a44
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/drawer.mdx
@@ -0,0 +1,427 @@
+---
+title: Drawer
+description: Drawer 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Drawer 文档](/docs/react/components/drawer)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Drawer` 与 `Modal` 共享相同的 API，使用 `DrawerContent`、`DrawerHeader`、`DrawerBody` 和 `DrawerFooter`，并采用渲染回调模式：
+
+```tsx
+import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Drawer</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="right">
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Drawer Title</DrawerHeader>
+              <DrawerBody>
+                <p>Drawer content goes here.</p>
+              </DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+  );
+}
+```
+
+在 v3 中，Drawer 改用复合组件模式，提供显式子组件与内置触发器支持：
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Drawer>
+      <Button>Open Drawer</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.Handle />
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Drawer Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>Drawer content goes here.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** `Drawer` 包裹 `DrawerContent`，并使用渲染回调模式；触发器需要通过 `useDisclosure` 单独管理  
+**v3：** 复合组件：`Drawer`、`Drawer.Backdrop`、`Drawer.Content`、`Drawer.Dialog`、`Drawer.Header`、`Drawer.Heading`、`Drawer.Body`、`Drawer.Footer`、`Drawer.Handle`、`Drawer.CloseTrigger`。`Drawer` 的第一个子节点会成为触发器。
+
+### 2. 触发模式
+
+**v2：** 使用外部触发器，并通过 `useDisclosure` 钩子与 `isOpen` / `onOpenChange` 管理状态  
+**v3：** 内置触发器，`Drawer` 的第一个子节点会自动成为触发器。受控状态可通过 `useOverlayState` 钩子管理。
+
+### 3. v3 新特性
+
+- **拖动关闭**：在手柄、头部和底部区域内置基于指针的拖动手势
+- **拖动手柄**：`Drawer.Handle` 是视觉拖动指示器组件
+- **内置关闭触发器**：`Drawer.CloseTrigger` 会渲染一个关闭按钮
+- **基于 slot 的关闭**：带有 `slot="close"` 的按钮会自动关闭 Drawer
+
+### 4. Prop 变更
+
+| v2 prop | v3 等效项 | 说明 |
+| ------- | ----------- | ---- |
+| `isOpen` | `Drawer.Backdrop` 的 `isOpen` | 或使用 `useOverlayState` |
+| `onOpenChange` | `Drawer.Backdrop` 的 `onOpenChange` | 或使用 `useOverlayState` |
+| `onClose` | - | 在按钮上使用 `onOpenChange` 或 `slot="close"` |
+| `placement` | `Drawer.Content` 的 `placement` | `"right"` → `"right"`、`"left"` → `"left"`、`"top"` → `"top"`、`"bottom"` → `"bottom"`。默认值从 `"right"` 改为 `"bottom"` |
+| `size` | - | 已移除（请在 `Drawer.Dialog` 上使用 Tailwind CSS） |
+| `radius` | - | 已移除（请改用 Tailwind CSS） |
+| `backdrop` | `Drawer.Backdrop` 的 `variant` | 值保持一致：`"opaque"`、`"blur"`、`"transparent"` |
+| `isDismissable` | `Drawer.Backdrop` 的 `isDismissable` | 保持一致 |
+| `isKeyboardDismissDisabled` | `Drawer.Backdrop` 的 `isKeyboardDismissDisabled` | 保持一致 |
+| `shouldBlockScroll` | - | v3 中始终会阻止滚动 |
+| `hideCloseButton` | - | 省略 `Drawer.CloseTrigger` 即可隐藏 |
+| `closeButton` | - | 将自定义内容传给 `Drawer.CloseTrigger` |
+| `motionProps` | - | 已移除（v3 使用基于 CSS 的动画） |
+| `disableAnimation` | - | 已移除 |
+| `portalContainer` | - | 已移除 |
+| `classNames` | - | 在各个复合组件上使用 `className` |
+
+### 5. Hook 变更
+
+**v2：** 使用 `useDisclosure` 钩子管理打开 / 关闭状态  
+**v3：** 使用 `useOverlayState` 钩子（替代 `useDisclosure`）
+
+```tsx
+// v2
+const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+// v3
+const state = useOverlayState();
+// state.isOpen, state.open(), state.close(), state.toggle()
+```
+
+## 迁移示例
+
+### 基本抽屉
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, Button, useDisclosure } from "@heroui/react";
+
+    const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+    <>
+      <Button onPress={onOpen}>Open</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Title</DrawerHeader>
+              <DrawerBody>Content</DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Drawer, Button } from "@heroui/react";
+
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### 位置
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="left">
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Left Drawer</DrawerHeader>
+            <DrawerBody>Content</DrawerBody>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="left">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Left Drawer</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### 遮罩变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer isOpen={isOpen} onOpenChange={onOpenChange} backdrop="blur">
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Blurred Backdrop</DrawerHeader>
+            <DrawerBody>Content</DrawerBody>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop variant="blur">
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Blurred Backdrop</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useDisclosure } from "@heroui/react";
+
+    const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+    <>
+      <Button onPress={onOpen}>Open</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Controlled</DrawerHeader>
+              <DrawerBody>Content</DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    const state = useOverlayState();
+
+    <>
+      <Button onPress={state.open}>Open</Button>
+      <Drawer state={state}>
+        <Drawer.Backdrop>
+          <Drawer.Content>
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>Controlled</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>Content</Drawer.Body>
+              <Drawer.Footer>
+                <Button onPress={state.close}>Close</Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+</Tabs>
+
+### 不可关闭
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      isDismissable={false}
+      hideCloseButton
+    >
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Confirm Action</DrawerHeader>
+            <DrawerBody>Are you sure?</DrawerBody>
+            <DrawerFooter>
+              <Button onPress={onClose}>Confirm</Button>
+            </DrawerFooter>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop isDismissable={false}>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>Confirm Action</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Are you sure?</Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Confirm</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Drawer
+  classNames={{
+    wrapper: "custom-wrapper",
+    base: "custom-base",
+    backdrop: "custom-backdrop",
+    header: "custom-header",
+    body: "custom-body",
+    footer: "custom-footer",
+    closeButton: "custom-close",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<Drawer>
+  <Button>Open</Button>
+  <Drawer.Backdrop className="custom-backdrop">
+    <Drawer.Content>
+      <Drawer.Dialog className="custom-base">
+        <Drawer.CloseTrigger className="custom-close" />
+        <Drawer.Header className="custom-header">
+          <Drawer.Heading>Title</Drawer.Heading>
+        </Drawer.Header>
+        <Drawer.Body className="custom-body">Content</Drawer.Body>
+        <Drawer.Footer className="custom-footer">Actions</Drawer.Footer>
+      </Drawer.Dialog>
+    </Drawer.Content>
+  </Drawer.Backdrop>
+</Drawer>
+```
+
+## 组件结构
+
+v3 Drawer 遵循以下结构：
+
+```
+Drawer (Root)
+  ├── [Trigger element] (first child becomes trigger)
+  └── Drawer.Backdrop
+      └── Drawer.Content (placement)
+          └── Drawer.Dialog
+              ├── Drawer.Handle (optional, drag indicator)
+              ├── Drawer.CloseTrigger (optional, close button)
+              ├── Drawer.Header
+              │   └── Drawer.Heading
+              ├── Drawer.Body (scrollable)
+              └── Drawer.Footer
+```
+
+## 总结
+
+1. **组件结构**：渲染回调模式 → 带显式子组件的复合组件
+2. **触发模式**：外部 `useDisclosure` + `onPress` → 内置触发器（`Drawer` 的第一个子节点）
+3. **状态钩子**：`useDisclosure` → `useOverlayState`，并使用 `open()`、`close()`、`toggle()` 方法
+4. **位置**：`Drawer` 上的 prop → `Drawer.Content` 上的 prop。默认值从 `"right"` 改为 `"bottom"`
+5. **遮罩**：`backdrop` prop → `Drawer.Backdrop` 的 `variant` prop
+6. **关闭按钮**：`hideCloseButton` / `closeButton` props → 省略或自定义 `Drawer.CloseTrigger`
+7. **基于 slot 的关闭**：带有 `slot="close"` 的按钮会自动关闭 Drawer
+8. **新功能**：通过 `Drawer.Handle` 拖动关闭，并支持基于速度的关闭
+9. **动画**：`motionProps`（Framer Motion）→ 基于 CSS 的动画
+10. **已移除样式 prop**：`size`、`radius` → 使用 Tailwind CSS
+11. **已移除 classNames**：在各个复合组件上使用 `className`
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/dropdown.mdx b/apps/docs/content/docs/cn/react/migration/(components)/dropdown.mdx
new file mode 100644
index 0000000..ca640be
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/dropdown.mdx
@@ -0,0 +1,466 @@
+---
+title: Dropdown
+description: Dropdown 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Dropdown 文档](/docs/react/components/dropdown)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Dropdown 使用相互独立的组件：`DropdownTrigger`、`DropdownMenu`、`DropdownItem`、`DropdownSection`：
+
+```tsx
+import { Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Dropdown>
+      <DropdownTrigger>
+        <Button>Open Menu</Button>
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem key="new">New file</DropdownItem>
+        <DropdownItem key="copy">Copy link</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+```
+
+在 v3 中，Dropdown 采用复合组件模式，并提供显式的子组件结构：
+
+```tsx
+import { Dropdown, Button, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Dropdown>
+      <Button>Open Menu</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="new" textValue="New file">
+            <Label>New file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy" textValue="Copy link">
+            <Label>Copy link</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 相互独立的组件：`DropdownTrigger`、`DropdownMenu`、`DropdownItem`、`DropdownSection`  
+**v3：** 复合组件：`Dropdown.Trigger`、`Dropdown.Popover`、`Dropdown.Menu`、`Dropdown.Item`、`Dropdown.Section`
+
+### 2. 组件名称变更
+
+| v2 组件           | v3 组件              | 说明                                      |
+| ----------------- | -------------------- | ----------------------------------------- |
+| `DropdownTrigger` | `Dropdown.Trigger`   | 功能相同                                  |
+| `DropdownMenu`    | `Dropdown.Menu`      | 需包裹在 `Dropdown.Popover` 内          |
+| `DropdownItem`    | `Dropdown.Item`      | 使用 `id` 与 `textValue`；列表项保留 `key` |
+| `DropdownSection` | `Dropdown.Section`   | 功能相同                                  |
+| —                 | `Dropdown.Popover`   | 新增包裹组件（必填）                      |
+
+### 3. 菜单项标识
+
+**v2：** 菜单项内容通过 children 传递；React 的 `key` 同时用于列表调和与菜单项标识（选择、焦点）。  
+**v3：** 菜单项的可见文本必须使用 `Label` 组件。为每个菜单项提供 `id`（状态/焦点）与 `textValue`（当内容不是纯文本时用于无障碍）。列表中的菜单项仍应保留 React 的 `key`。
+
+### 4. Prop 变更
+
+| v2 prop                              | v3 位置           | 说明                                                |
+| ------------------------------------ | ----------------- | --------------------------------------------------- |
+| `variant`、`color`（在 `DropdownMenu` 上） | —                 | 已移除（菜单不再有 variant/color）                  |
+| `classNames`、`itemClasses`（在 `DropdownMenu` 上） | —                 | 在 `Menu` 与菜单项上使用 `className`                |
+| `color`（在 `DropdownItem` 上）      | `Dropdown.Item`   | 使用 `variant="danger"` 表示危险操作                |
+| `title`                              | —                 | 使用 `Label` 子组件                                 |
+| `description`                      | —                 | 使用 `Description` 子组件                           |
+| `shortcut`                         | —                 | 使用 `Kbd` 子组件                                   |
+| `startContent`、`endContent`         | —                 | 将图标或组件作为 children 放置                      |
+| `selectedIcon`                     | —                 | 使用 `Dropdown.ItemIndicator`                       |
+| `showDivider`                      | —                 | 在菜单项之间使用 `Separator`                        |
+| `classNames`（在 `DropdownItem` 上） | —                 | 在菜单项上使用 `className`                          |
+| `isSelected`                       | `Dropdown.Menu`   | 在 `Menu` 上使用 `selectedKeys`                     |
+| `isDisabled`                       | `Dropdown.Menu`   | 在 `Menu` 上使用 `disabledKeys`                     |
+| `trigger`（在 `Dropdown` 上）      | `Dropdown`        | 仍支持：`"press"`（默认）或 `"longPress"`           |
+
+### 5. 新增子组件
+
+- `Dropdown.Popover`：`Dropdown.Menu` 的必填外层包裹
+- `Dropdown.ItemIndicator`：用于选择指示（对勾/圆点等）
+- `Dropdown.SubmenuTrigger`：子菜单触发结构
+- `Dropdown.SubmenuIndicator`：子菜单 chevron 指示
+
+## 迁移示例
+
+### 使用 onAction
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownMenu onAction={(key) => alert(key)}>
+      <DropdownItem key="new">New file</DropdownItem>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown.Menu onAction={(key) => alert(key)}>
+      <Dropdown.Item id="new" textValue="New file">
+        <Label>New file</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### 菜单项内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With icon */}
+    <DropdownItem
+      key="new"
+      startContent={<AddNoteIcon />}
+    >
+      New file
+    </DropdownItem>
+    
+    {/* With description */}
+    <DropdownItem
+      key="edit"
+      description="Edit the file"
+    >
+      Edit file
+    </DropdownItem>
+    
+    {/* With shortcut */}
+    <DropdownItem
+      key="copy"
+      shortcut="⌘C"
+    >
+      Copy
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { Label, Description, Kbd } from "@heroui/react";
+
+    {/* With icon */}
+    <Dropdown.Item id="new" textValue="New file">
+      <Icon icon="gravity-ui:square-plus" />
+      <Label>New file</Label>
+    </Dropdown.Item>
+    
+    {/* With description */}
+    <Dropdown.Item id="edit" textValue="Edit file">
+      <Label>Edit file</Label>
+      <Description>Edit the file</Description>
+    </Dropdown.Item>
+    
+    {/* With shortcut */}
+    <Dropdown.Item id="copy" textValue="Copy">
+      <Label>Copy</Label>
+      <Kbd slot="keyboard" variant="light">
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+    </Dropdown.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### 危险菜单项
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownItem
+      key="delete"
+      className="text-danger"
+      color="danger"
+    >
+      Delete file
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown.Item id="delete" textValue="Delete file" variant="danger">
+      <Label>Delete file</Label>
+    </Dropdown.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用分组（Section）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownMenu>
+      <DropdownSection showDivider title="Actions">
+        <DropdownItem key="new">New file</DropdownItem>
+        <DropdownItem key="edit">Edit file</DropdownItem>
+      </DropdownSection>
+      <DropdownSection title="Danger zone">
+        <DropdownItem key="delete" color="danger">Delete file</DropdownItem>
+      </DropdownSection>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Separator } from "@heroui/react";
+
+    <Dropdown.Menu>
+      <Dropdown.Section>
+        <Header>Actions</Header>
+        <Dropdown.Item id="new" textValue="New file">
+          <Label>New file</Label>
+        </Dropdown.Item>
+        <Dropdown.Item id="edit" textValue="Edit file">
+          <Label>Edit file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+      <Separator />
+      <Dropdown.Section>
+        <Header>Danger zone</Header>
+        <Dropdown.Item id="delete" textValue="Delete file" variant="danger">
+          <Label>Delete file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### 选择
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+    <DropdownMenu
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <DropdownItem key="text">Text</DropdownItem>
+      <DropdownItem key="number">Number</DropdownItem>
+    </DropdownMenu>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["bold"]));
+    <DropdownMenu
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <DropdownItem key="bold">Bold</DropdownItem>
+      <DropdownItem key="italic">Italic</DropdownItem>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+    <Dropdown.Menu
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <Dropdown.Item id="text" textValue="Text">
+        <Dropdown.ItemIndicator />
+        <Label>Text</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="number" textValue="Number">
+        <Dropdown.ItemIndicator />
+        <Label>Number</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["bold"]));
+    <Dropdown.Menu
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <Dropdown.Item id="bold" textValue="Bold">
+        <Dropdown.ItemIndicator />
+        <Label>Bold</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="italic" textValue="Italic">
+        <Dropdown.ItemIndicator />
+        <Label>Italic</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### 键盘快捷键
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownItem key="copy" shortcut="⌘C">
+      Copy
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Kbd } from "@heroui/react";
+
+    <Dropdown.Item id="copy" textValue="Copy">
+      <Label>Copy</Label>
+      <Kbd slot="keyboard" variant="light">
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+    </Dropdown.Item>
+    ```
+
+    `Kbd` 的 `slot="keyboard"` prop 会把快捷键放在菜单项末尾，用以替代 v2 的 `shortcut` prop。
+  </Tab>
+</Tabs>
+
+### 子菜单
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have built-in submenu support */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label } from "@heroui/react";
+
+    <Dropdown.Menu>
+      <Dropdown.Item id="copy-link" textValue="Copy Link">
+        <Label>Copy Link</Label>
+      </Dropdown.Item>
+      <Dropdown.SubmenuTrigger>
+        <Dropdown.Item id="share" textValue="Share">
+          <Label>Share</Label>
+          <Dropdown.SubmenuIndicator />
+        </Dropdown.Item>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+              <Label>WhatsApp</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="telegram" textValue="Telegram">
+              <Label>Telegram</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown.SubmenuTrigger>
+    </Dropdown.Menu>
+    ```
+
+    使用 `Dropdown.SubmenuTrigger` 包裹会打开嵌套菜单的菜单项；在菜单项内放置 `Dropdown.SubmenuIndicator` 以显示子菜单指示图标。
+  </Tab>
+</Tabs>
+
+### 长按触发
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Dropdown>
+      <DropdownTrigger>
+        <Button>Long press me</Button>
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem key="cut">Cut</DropdownItem>
+        <DropdownItem key="copy">Copy</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown trigger="longPress">
+      <Button>Long press me</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="cut" textValue="Cut">
+            <Label>Cut</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy" textValue="Copy">
+            <Label>Copy</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+    ```
+
+    根组件 `Dropdown` 的 `trigger` prop 接受 `"press"`（默认）或 `"longPress"`，用于控制如何打开菜单。
+  </Tab>
+</Tabs>
+
+## 组件结构（Anatomy）
+
+v3 的 Dropdown 结构如下：
+
+```
+Dropdown (Root) — accepts trigger="press" | "longPress"
+  ├── Dropdown.Trigger (optional, defaults to first child)
+  ├── Dropdown.Popover (required wrapper)
+  │   └── Dropdown.Menu
+  │       ├── Dropdown.Item
+  │       │   ├── Icon (optional, first child)
+  │       │   ├── Label (required for text)
+  │       │   ├── Description (optional)
+  │       │   ├── Kbd slot="keyboard" (optional, for shortcuts)
+  │       │   └── Dropdown.ItemIndicator (optional, for selection)
+  │       ├── Separator (for dividers)
+  │       ├── Dropdown.Section
+  │       │   ├── Header (optional)
+  │       │   └── Dropdown.Item
+  │       └── Dropdown.SubmenuTrigger
+  │           ├── Dropdown.Item
+  │           │   ├── Label
+  │           │   └── Dropdown.SubmenuIndicator (chevron icon)
+  │           └── Dropdown.Popover
+  │               └── Dropdown.Menu
+  │                   └── Dropdown.Item
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Dropdown.Trigger`、`Dropdown.Popover`、`Dropdown.Menu` 等）。
+2. **`Dropdown.Popover` 为必填**：`Dropdown.Menu` 必须包裹在 `Dropdown.Popover` 内。
+3. **`Label` 组件**：菜单项文本必须使用 `Label`。
+4. **`Description` 组件**：用 `Description` 替代 `description` prop。
+5. **`Kbd` 组件**：用带 `slot="keyboard"` 的 `Kbd` 替代 `shortcut` prop；slot 用于把快捷键放到菜单项末尾。
+6. **图标作为 children**：图标作为第一个 child 放置，不再使用 `startContent` prop。
+7. **`Separator` 组件**：用 `Separator` 替代 `showDivider` prop。
+8. **`ItemIndicator` 组件**：用 `Dropdown.ItemIndicator` 表示选择状态。
+9. **用 variant 表示危险**：用 `variant="danger"` 替代 `color="danger"`。
+10. **菜单样式 prop 移除**：`Dropdown.Menu` 不再支持 `variant` 或 `color` prop。
+11. **`classNames` 移除**：在各自子组件上使用 `className`。
+12. **子菜单**：用 `Dropdown.SubmenuTrigger` 包裹会打开嵌套菜单的项，并在项内使用 `Dropdown.SubmenuIndicator`。
+13. **`trigger` prop**：在根 `Dropdown` 上使用 `trigger="longPress"` 以长按打开菜单（默认为按压打开）。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/form.mdx b/apps/docs/content/docs/cn/react/migration/(components)/form.mdx
new file mode 100644
index 0000000..4c30308
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/form.mdx
@@ -0,0 +1,116 @@
+---
+title: Form
+description: Form 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Form 文档](/docs/react/components/form)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 主要变化
+
+### 1. Form 组件 prop
+
+v2 与 v3 之间，Form 组件的 prop 大体保持不变，仅新增了一个：
+
+| 属性 | v2 | v3 | 说明 |
+| ---- | -- | -- | ---- |
+| `validationBehavior` | ✅ | ✅ | 相同：`"native"` \| `"aria"` |
+| `validationErrors` | ✅ | ✅ | 相同：`Record<string, string \| string[]>` |
+| `onSubmit` | ✅ | ✅ | 相同 |
+| `onReset` | ✅ | ✅ | 相同 |
+| `action` | ✅ | ✅ | 相同 |
+| `method` | ✅ | ✅ | 相同 |
+| `encType` | ✅ | ✅ | 相同 |
+| `target` | ✅ | ✅ | 相同 |
+| `className` | ✅ | ✅ | 相同 |
+| `onInvalid` | ❌ | ✅ | 新增：表单验证失败时调用的处理函数 |
+
+## 结构变化
+
+在 v2 中，Form 组件的用法：
+
+```tsx
+import { Form, Button } from "@heroui/react";
+
+export default function App() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log("Form submitted");
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+在 v3 中，Form 组件的用法保持一致：
+
+```tsx
+import { Form, Button } from "@heroui/react";
+
+export default function App() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log("Form submitted");
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+## 迁移示例
+
+### 带 onInvalid 处理函数的表单（v3 新增）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 没有 onInvalid prop */}
+    <Form onSubmit={onSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Form
+      onInvalid={(e) => {
+        e.preventDefault();
+        // Custom handling when form validation fails
+        console.log("Form validation failed");
+      }}
+      onSubmit={onSubmit}
+    >
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+    ```
+  </Tab>
+</Tabs>
+
+`onInvalid` 处理函数会在表单验证失败时被调用。默认情况下，第一个无效字段会获得焦点；通过调用 `e.preventDefault()` 可以自定义这一行为。
+
+## 总结
+
+1. **Form 组件**：没有破坏性变更——prop 与行为保持一致
+2. **新增 prop**：`onInvalid` 可用于自定义校验失败时的处理逻辑
+
+## 迁移步骤
+
+1. **无需改动**：Form 组件在 v3 中的工作方式与 v2 相同
+2. **可选**：如果你需要自定义校验失败时的处理逻辑，可使用新增的 `onInvalid` prop
+
+## 关于表单字段
+
+虽然 Form 组件本身没有变化，但其中使用的表单字段组件（例如 `Input`、`TextField` 等）在 v3 中已有更新。具体的字段迁移说明请参阅各自的迁移指南。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/image.mdx b/apps/docs/content/docs/cn/react/migration/(components)/image.mdx
new file mode 100644
index 0000000..6a1139a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/image.mdx
@@ -0,0 +1,522 @@
+---
+title: Image
+description: Image 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  HeroUI v3 **已移除** `Image` 组件。请改用原生 HTML `img` 元素或 Next.js 的 `Image` 组件，并结合 Tailwind CSS 类进行样式与效果处理。
+</Callout>
+
+## 主要变化
+
+### 1. 组件移除
+
+**v2：** `@heroui/react` 的 `<Image>` 组件  
+**v3：** 原生 HTML `img` 元素，或 Next.js `Image` 组件
+
+### 2. 能力对照
+
+v2 的 `Image` 提供的能力，在 v3 中需要分别替换：
+
+| v2 能力                         | v3 对应做法                         | 说明                                      |
+| ------------------------------- | ----------------------------------- | ----------------------------------------- |
+| `radius` prop                   | Tailwind `rounded-*` 类            | 如 `rounded-sm`、`rounded-md`、`rounded-lg`、`rounded-full` |
+| `shadow` prop                   | Tailwind `shadow-*` 类             | 如 `shadow-sm`、`shadow-md`、`shadow-lg` |
+| `isBlurred` prop                | 手动实现模糊                        | 使用 CSS `filter: blur()` 或 Tailwind `blur-*` |
+| `isZoomed` prop                 | 手动实现悬停缩放                    | 使用 Tailwind `hover:scale-*`            |
+| `fallbackSrc` prop              | 手动错误回退                        | 使用 `onError` + 状态切换 `src`           |
+| `disableSkeleton` / 加载骨架图 | 手动加载态                          | 使用 React state + 条件渲染               |
+| `removeWrapper` prop            | 直接渲染                            | 无需额外 wrapper，直接渲染 `img`        |
+
+## 结构变化
+
+在 v2 中，`Image` 是对原生 `img` 的封装组件：
+
+```tsx
+import { Image } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example image"
+      width={300}
+      height={200}
+    />
+  );
+}
+```
+
+在 v3 中，直接使用原生 `img`，并用 Tailwind CSS 控制样式：
+
+```tsx
+export default function App() {
+  return (
+    <img
+      src="https://example.com/image.jpg"
+      alt="Example image"
+      width={300}
+      height={200}
+      className="rounded-lg"
+    />
+  );
+}
+```
+
+## 迁移示例
+
+### 使用 Next.js `Image`（推荐）
+
+若使用 Next.js，推荐使用其优化的 `Image` 组件：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    <Image
+      src="/image.jpg"
+      alt="Example"
+      width={300}
+      height={200}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import Image from "next/image";
+
+    <Image
+      src="/image.jpg"
+      alt="Example"
+      width={300}
+      height={200}
+      className="rounded-lg"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+### 悬停放大（对应 `isZoomed`）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image isZoomed src="..." alt="..." />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative overflow-hidden rounded-lg">
+      <img
+        src="..."
+        alt="..."
+        className="object-cover transition-transform duration-300 hover:scale-125"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 模糊效果（对应 `isBlurred`）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image isBlurred src="..." alt="..." />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative">
+      <img
+        src="..."
+        alt="..."
+        className="relative z-10"
+      />
+      <img
+        src="..."
+        alt=""
+        aria-hidden="true"
+        className="absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 回退图片（对应 `fallbackSrc`）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      fallbackSrc="/fallback.jpg"
+      alt="Example"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    function ImageWithFallback({ src, fallbackSrc, alt, ...props }) {
+      const [imgSrc, setImgSrc] = useState(src);
+
+      return (
+        <img
+          src={imgSrc}
+          alt={alt}
+          onError={() => setImgSrc(fallbackSrc)}
+          {...props}
+        />
+      );
+    }
+
+    <ImageWithFallback
+      src="https://example.com/image.jpg"
+      fallbackSrc="/fallback.jpg"
+      alt="Example"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+### 加载骨架（对应 skeleton）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example"
+      disableSkeleton={false}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    function ImageWithSkeleton({ src, alt, ...props }) {
+      const [isLoading, setIsLoading] = useState(true);
+      const [hasError, setHasError] = useState(false);
+
+      return (
+        <div className="relative overflow-hidden rounded-lg bg-default-200">
+          {isLoading && (
+            <div className="absolute inset-0 animate-pulse bg-gradient-to-r from-transparent via-default-300 to-transparent" />
+          )}
+          <img
+            src={src}
+            alt={alt}
+            className={`transition-opacity duration-300 ${
+              isLoading ? "opacity-0" : "opacity-100"
+            }`}
+            onLoad={() => setIsLoading(false)}
+            onError={() => {
+              setIsLoading(false);
+              setHasError(true);
+            }}
+            {...props}
+          />
+        </div>
+      );
+    }
+
+    <ImageWithSkeleton src="https://example.com/image.jpg" alt="Example" />
+    ```
+  </Tab>
+</Tabs>
+
+### 组合效果
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example"
+      radius="lg"
+      shadow="md"
+      isZoomed
+      isBlurred
+      width={400}
+      height={300}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative overflow-hidden rounded-lg shadow-md">
+      <img
+        src="https://example.com/image.jpg"
+        alt="Example"
+        width={400}
+        height={300}
+        className="relative z-10 object-cover transition-transform duration-300 hover:scale-125"
+      />
+      <img
+        src="https://example.com/image.jpg"
+        alt=""
+        aria-hidden="true"
+        className="absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## 创建可复用的图片组件（可选）
+
+如果你经常在同类场景重复使用图片能力，可以封装一个可复用组件：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    <Image
+      src="..."
+      radius="lg"
+      shadow="md"
+      isZoomed
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { cn } from "@/lib/utils"; // 或你项目里的 cn 工具
+
+    interface CustomImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+      shadow?: "none" | "sm" | "md" | "lg";
+      isZoomed?: boolean;
+      isBlurred?: boolean;
+      fallbackSrc?: string;
+    }
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    const shadowClasses = {
+      none: "shadow-none",
+      sm: "shadow-sm",
+      md: "shadow-md",
+      lg: "shadow-lg",
+    };
+
+    export function CustomImage({
+      src,
+      alt,
+      className,
+      radius = "lg",
+      shadow = "none",
+      isZoomed = false,
+      isBlurred = false,
+      fallbackSrc,
+      onError,
+      ...props
+    }: CustomImageProps) {
+      const [imgSrc, setImgSrc] = useState(src);
+      const [isLoading, setIsLoading] = useState(true);
+
+      const handleError = (e: React.SyntheticEvent<HTMLImageElement, Event>) => {
+        if (fallbackSrc && imgSrc !== fallbackSrc) {
+          setImgSrc(fallbackSrc);
+        }
+        onError?.(e);
+      };
+
+      const imageElement = (
+        <img
+          src={imgSrc}
+          alt={alt}
+          className={cn(
+            radiusClasses[radius],
+            shadowClasses[shadow],
+            isZoomed && "object-cover transition-transform duration-300 hover:scale-125",
+            isLoading && "opacity-0",
+            "transition-opacity duration-300",
+            className
+          )}
+          onLoad={() => setIsLoading(false)}
+          onError={handleError}
+          {...props}
+        />
+      );
+
+      if (isBlurred) {
+        return (
+          <div className={cn("relative", radiusClasses[radius], shadowClasses[shadow])}>
+            {imageElement}
+            <img
+              src={imgSrc}
+              alt=""
+              aria-hidden="true"
+              className={cn(
+                "absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150",
+                radiusClasses[radius]
+              )}
+            />
+          </div>
+        );
+      }
+
+      if (isZoomed || isLoading) {
+        return (
+          <div className={cn("relative overflow-hidden", radiusClasses[radius], shadowClasses[shadow])}>
+            {isLoading && (
+              <div className="absolute inset-0 animate-pulse bg-gradient-to-r from-transparent via-default-300 to-transparent" />
+            )}
+            {imageElement}
+          </div>
+        );
+      }
+
+      return imageElement;
+    }
+
+    // 用法
+    <CustomImage
+      src="..."
+      alt="Example"
+      radius="lg"
+      shadow="md"
+      isZoomed
+      isBlurred
+      fallbackSrc="/fallback.jpg"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+## 完整示例
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <Image
+            src="https://example.com/image1.jpg"
+            alt="Image 1"
+            width={300}
+            height={200}
+            radius="lg"
+            shadow="md"
+          />
+          <Image
+            src="https://example.com/image2.jpg"
+            alt="Image 2"
+            width={300}
+            height={200}
+            isZoomed
+            radius="lg"
+          />
+          <Image
+            src="https://example.com/image3.jpg"
+            alt="Image 3"
+            width={300}
+            height={200}
+            isBlurred
+            radius="full"
+          />
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <img
+            src="https://example.com/image1.jpg"
+            alt="Image 1"
+            width={300}
+            height={200}
+            className="rounded-lg shadow-md"
+          />
+          <div className="relative overflow-hidden rounded-lg">
+            <img
+              src="https://example.com/image2.jpg"
+              alt="Image 2"
+              width={300}
+              height={200}
+              className="object-cover transition-transform duration-300 hover:scale-125"
+            />
+          </div>
+          <div className="relative rounded-full">
+            <img
+              src="https://example.com/image3.jpg"
+              alt="Image 3"
+              width={300}
+              height={300}
+              className="relative z-10 rounded-full"
+            />
+            <img
+              src="https://example.com/image3.jpg"
+              alt=""
+              aria-hidden="true"
+              className="absolute inset-0 z-0 h-full w-full scale-105 object-cover rounded-full blur-lg opacity-30 saturate-150"
+            />
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+1. **组件已移除**：v3 不再提供 `Image` 组件。
+2. **调整 import**：移除 `import { Image } from "@heroui/react"`。
+3. **使用原生标签**：用原生 `img`，或 Next.js `Image`。
+4. **能力补齐**：模糊、悬停放大、骨架屏与回退图需自行组合实现。
+5. **样式方式**：圆角、阴影与视觉效果直接用 Tailwind CSS 类控制。
+
+## 迁移步骤
+
+1. **移除 import**：从 `@heroui/react` 的 import 中删除 `Image`。
+2. **替换标签**：把所有 `<Image>` 替换为 `img`（或 Next.js `Image`）。
+3. **补齐 Tailwind 类**：用等价类表达圆角、阴影等视觉样式。
+4. **按需实现行为**：如需模糊、放大、骨架屏、回退图，请自行实现。
+5. **Next.js 项目**：可优先使用 `next/image` 做图片优化。
+6. **可选**：对常用模式封装可复用组件。
+
+## Next.js 的 `Image` 组件
+
+在 Next.js 中，`next/image` 的 `Image` 组件提供：
+
+- 自动图片优化
+- 默认懒加载
+- 响应式 `srcSet`
+- 占位模糊（placeholder blur）
+- 内置加载体验
+
+```tsx
+import Image from "next/image";
+
+<Image
+  src="/image.jpg"
+  alt="Example"
+  width={300}
+  height={200}
+  className="rounded-lg shadow-md"
+  placeholder="blur" // 可选：模糊占位
+  blurDataURL="data:image/..." // 可选：base64 模糊数据
+/>
+```
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/input-otp.mdx b/apps/docs/content/docs/cn/react/migration/(components)/input-otp.mdx
new file mode 100644
index 0000000..3949204
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/input-otp.mdx
@@ -0,0 +1,275 @@
+---
+title: InputOTP
+description: InputOTP 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 InputOTP 文档](/docs/react/components/input-otp)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，InputOtp 根据 `length` prop 自动渲染插槽：
+
+```tsx
+import { InputOtp } from "@heroui/react";
+
+export default function App() {
+  return <InputOtp length={4} />;
+}
+```
+
+在 v3 中，InputOTP 改为复合组件，需要手动声明插槽：
+
+```tsx
+import { InputOTP } from "@heroui/react";
+
+export default function App() {
+  return (
+    <InputOTP maxLength={4}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单个组件，自动渲染各个分段  
+**v3：** 复合组件：`InputOTP.Group`、`InputOTP.Slot`、`InputOTP.Separator`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `length` | `InputOTP` | 已重命名为 `maxLength` |
+| `allowedKeys` | `InputOTP` | 已重命名为 `pattern`（正则表达式） |
+| `onValueChange` | `InputOTP` | 改用 `onChange` |
+| `description`、`errorMessage` | - | 通过外部 Description / FieldError 处理 |
+| `variant` | `InputOTP` | 简化为仅 `primary` \| `secondary` |
+| `color`、`size`、`radius` | - | 已移除（请改用 Tailwind CSS） |
+| `classNames` | - | 改在各子组件上使用 `className` |
+| - | `textAlign` | 新增 prop：插槽内的文本对齐（`'left'` \| `'center'` \| `'right'`） |
+| - | `inputMode` | 新增 prop：移动端的虚拟键盘类型（默认 `'numeric'`） |
+| - | `placeholder` | 新增 prop：空插槽的占位符文本 |
+| - | `pasteTransformer` | 新增 prop：转换粘贴的文本（例如去掉连字符） |
+
+## 迁移示例
+
+### 受控 InputOTP
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <InputOtp length={4} value={value} onValueChange={setValue} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <InputOTP maxLength={4} value={value} onChange={setValue}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用 allowedKeys / pattern
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <InputOtp allowedKeys="^[a-z]*$" length={4} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { REGEXP_ONLY_CHARS } from "@heroui/react";
+
+    <InputOTP maxLength={4} pattern={REGEXP_ONLY_CHARS}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <InputOtp description="Enter the code sent to your email" length={4} />
+    
+    {/* With error message */}
+    <InputOtp errorMessage="Invalid code" isInvalid length={4} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError } from "@heroui/react";
+
+    {/* With description */}
+    <div className="flex flex-col gap-2">
+      <InputOTP maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>Enter the code sent to your email</Description>
+    </div>
+    
+    {/* With error message */}
+    <div className="flex flex-col gap-2">
+      <InputOTP isInvalid maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+      <FieldError>Invalid code</FieldError>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用 onComplete 回调
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <InputOtp
+      length={6}
+      onComplete={(value) => console.log("Complete:", value)}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <InputOTP
+      maxLength={6}
+      onComplete={(value) => console.log("Complete:", value)}
+    >
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+      </InputOTP.Group>
+      <InputOTP.Separator />
+      <InputOTP.Group>
+        <InputOTP.Slot index={3} />
+        <InputOTP.Slot index={4} />
+        <InputOTP.Slot index={5} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 InputOTP 遵循以下结构：
+
+```
+InputOTP (Root)
+  ├── InputOTP.Group
+  │   ├── InputOTP.Slot (index={0})
+  │   ├── InputOTP.Slot (index={1})
+  │   └── ...
+  ├── InputOTP.Separator (optional)
+  └── InputOTP.Group (optional, for grouping)
+      └── InputOTP.Slot (index={...})
+```
+
+## v3 中的新增 prop
+
+v3 引入了几个 v2 中没有的 prop：
+
+- **`textAlign`**：控制插槽内的文本对齐（`'left'` | `'center'` | `'right'`，默认 `'left'`）
+- **`inputMode`**：设置移动端虚拟键盘类型（`'numeric'` | `'text'` | `'decimal'` | `'tel'` | `'search'` | `'email'` | `'url'`，默认 `'numeric'`）
+- **`placeholder`**：设置空插槽的占位符文本
+- **`pasteTransformer`**：`(text: string) => string` 类型的函数，用于转换粘贴的文本（例如从粘贴的代码中移除连字符）
+
+```tsx
+<InputOTP
+  maxLength={6}
+  inputMode="numeric"
+  textAlign="center"
+  placeholder="-"
+  pasteTransformer={(text) => text.replace(/-/g, "")}
+>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+## 导出的正则表达式模式
+
+为方便使用，HeroUI 从 input-otp 库再导出了几个常用的正则模式：
+
+```tsx
+import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from "@heroui/react";
+
+// Use with the pattern prop
+<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>
+  {/* ... */}
+</InputOTP>
+```
+
+- **`REGEXP_ONLY_DIGITS`** —— 仅限数字字符（0-9）
+- **`REGEXP_ONLY_CHARS`** —— 仅限字母字符（a-z、A-Z）
+- **`REGEXP_ONLY_DIGITS_AND_CHARS`** —— 字母数字字符（0-9、a-z、A-Z）
+
+## 总结
+
+1. **组件结构**：必须用 `InputOTP.Group` 与 `InputOTP.Slot` 手动声明插槽
+2. **length → maxLength**：prop 重命名
+3. **allowedKeys → pattern**：prop 重命名，改为接收正则表达式
+4. **onValueChange → onChange**：事件处理函数重命名
+5. **移除 description**：改用独立的 `Description` 组件
+6. **移除 errorMessage**：改用独立的错误展示组件
+7. **简化变体**：v3 仅支持 `variant="primary"` 与 `variant="secondary"`
+8. **移除 color**：请用 Tailwind CSS 类设置样式
+9. **移除 size**：请用 Tailwind CSS 类设置样式
+10. **移除 radius**：请用 Tailwind CSS 类设置样式
+11. **移除 classNames**：改在各子组件上使用 `className` prop
+12. **新增 prop**：v3 新增了 `textAlign`、`inputMode`、`placeholder` 与 `pasteTransformer`
+13. **导出的正则模式**：可使用 `REGEXP_ONLY_DIGITS`、`REGEXP_ONLY_CHARS`、`REGEXP_ONLY_DIGITS_AND_CHARS` 作为 `pattern` 的取值
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/input.mdx b/apps/docs/content/docs/cn/react/migration/(components)/input.mdx
new file mode 100644
index 0000000..d9dd33c
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/input.mdx
@@ -0,0 +1,281 @@
+---
+title: Input
+description: Input 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Input 文档](/docs/react/components/input)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 关键变化：Input → TextField
+
+**v2：** `Input` 是功能完备的组件，内置标签、描述、错误信息、校验、变体、颜色、尺寸等。
+
+**v3：** `Input` 现在只是一个原语组件（仅是输入元素本身）。对于表单字段，请使用 `TextField`，它由 `Input` 与 `Label`、`Description`、`FieldError` 等子组件组成。在 v2 中并没有独立的 TextField 或 InputGroup；单一的 Input 组件就负责标签、描述、起止内容与校验等所有职责。
+
+## 何时使用 Input vs TextField
+
+### 使用 TextField（大多数场景）
+
+当你需要以下能力时，请使用 `TextField`：
+- 标签
+- 描述
+- 错误信息
+- 校验
+- 表单集成
+
+### 使用 Input（仅原语）
+
+当你需要以下能力时，请使用 `Input`：
+- 仅一个基础的 input 元素
+- 自定义的标签 / 错误处理
+- 与自定义表单组件集成
+
+## 结构变化
+
+在 v2 中，`Input` 是功能完备的组件，通过 prop 接收标签、描述、占位符等：
+
+```tsx
+import { Input } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Input
+      label="Email"
+      placeholder="Enter your email"
+      type="email"
+    />
+  );
+}
+```
+
+在 v3 中，`Input` 是原语组件。对于带标签与校验的表单字段，请使用 `TextField`，将 `Input` 与 `Label`、`Description`、`FieldError` 组合在一起：
+
+```tsx
+import { TextField, Label, Input, FieldError } from "@heroui/react";
+
+export default function App() {
+  return (
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input placeholder="Enter your email" />
+      <FieldError />
+    </TextField>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件拆分
+
+**v2：** 单一 `Input` 组件，承担所有职责  
+**v3：** 拆分为 `Input`（原语）与 `TextField`（复合组件）
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `label` | `Label` | 在 `TextField` 内使用 `Label` 组件 |
+| `description` | `Description` | 在 `TextField` 内使用 `Description` 组件 |
+| `errorMessage` | `FieldError` | 在 `TextField` 内使用 `FieldError` 组件 |
+| `variant` | `Input` | 从多种变体（flat、bordered、underlined、faded）改为 `"primary"`（默认，带阴影）与 `"secondary"`（弱化、无阴影，适合 Surface 场景） |
+| `color`、`size`、`radius` | - | 已移除（请改用 Tailwind CSS） |
+| `fullWidth` | `Input` 或 `TextField` | `Input` 与 `TextField` 上均仍支持 `fullWidth` 布尔属性 |
+| `labelPlacement` | - | 通过 `Label` 的布局自行处理 |
+| `startContent` | `InputGroup.Prefix` | 在 `TextField` 内使用 `InputGroup` 与 `InputGroup.Prefix` |
+| `endContent` | `InputGroup.Suffix` | 在 `TextField` 内使用 `InputGroup` 与 `InputGroup.Suffix` |
+| `isClearable` | - | 请通过按钮手动实现 |
+| `isRequired`、`isInvalid` | `TextField` | 请设置在 `TextField` 上 |
+| `validate` | `TextField` | 在 `TextField` 上使用 `validate` |
+| `classNames` | - | 改在各子组件上使用 `className` |
+| `onValueChange` | `Input` | 改用 `onChange` 事件处理函数 |
+
+## 迁移示例
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <Input
+      description="We'll never share your email"
+      label="Email"
+      type="email"
+    />
+    
+    {/* With error message */}
+    <Input
+      errorMessage="Please enter a valid email"
+      isInvalid
+      label="Email"
+      type="email"
+    />
+    
+    {/* Required */}
+    <Input isRequired label="Email" type="email" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description } from "@heroui/react";
+
+    {/* With description */}
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input />
+      <Description>We'll never share your email</Description>
+      <FieldError />
+    </TextField>
+    
+    {/* With error message */}
+    <TextField
+      isInvalid
+      name="email"
+      type="email"
+      validate={(value) => {
+        if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+          return "Please enter a valid email";
+        }
+        return null;
+      }}
+    >
+      <Label>Email</Label>
+      <Input />
+      <FieldError />
+    </TextField>
+    
+    {/* Required */}
+    <TextField isRequired name="email" type="email">
+      <Label>Email</Label>
+      <Input />
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+### Input 起止内容
+
+对于带前缀或后缀内容的输入，请使用 **InputGroup** 复合组件：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Input
+      label="Price"
+      startContent={<span>$</span>}
+      type="number"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { InputGroup } from "@heroui/react";
+
+    <TextField name="price" type="number">
+      <Label>Price</Label>
+      <InputGroup>
+        <InputGroup.Prefix>$</InputGroup.Prefix>
+        <InputGroup.Input />
+      </InputGroup>
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+**InputGroup** 为前缀 / 后缀内容提供合适的样式与布局。其中：
+- `InputGroup.Prefix` 表示位于输入之前的内容（取代 `startContent`）
+- `InputGroup.Suffix` 表示位于输入之后的内容（取代 `endContent`）
+- `InputGroup.Input` 表示输入元素本身
+
+### 带清除按钮的 Input
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Input
+      isClearable
+      label="Email"
+      onClear={() => console.log("cleared")}
+      type="email"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { CloseButton } from "@heroui/react";
+
+    const [value, setValue] = useState("");
+
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <div className="flex items-center">
+        <Input value={value} onChange={(e) => setValue(e.target.value)} />
+        {value && (
+          <CloseButton
+            aria-label="Clear"
+            onPress={() => setValue("")}
+          />
+        )}
+      </div>
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控 Input
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <Input
+      label="Email"
+      onValueChange={setValue}
+      type="email"
+      value={value}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input
+        onChange={(e) => setValue(e.target.value)}
+        value={value}
+      />
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+1. **组件拆分**：表单字段使用 `TextField`，仅原语输入使用 `Input`
+2. **标签必须显式声明**：必须使用 `Label` 组件而不是 `label` prop
+3. **错误展示**：必须使用 `FieldError` 组件而不是 `errorMessage` prop
+4. **描述**：必须使用 `Description` 组件而不是 `description` prop
+5. **校验**：将 `validate` 函数从 `Input` 移到 `TextField` 上
+6. **起止内容**：在 `TextField` 内使用 `InputGroup` 与 `InputGroup.Prefix` / `InputGroup.Suffix`
+7. **清除按钮**：请手动实现 `CloseButton`
+8. **简化变体**：v2 提供多种变体（flat、bordered、underlined、faded）；v3 提供 `"primary"`（默认）与 `"secondary"`（适合 Surface）
+9. **fullWidth**：`fullWidth` prop 在 `Input` 与 `TextField` 上均可用
+10. **移除 color**：请改用 Tailwind CSS 类
+11. **移除 size**：请改用 Tailwind CSS 类
+12. **移除 radius**：请改用 Tailwind CSS 类
+13. **移除 onValueChange**：改用 `onChange` 事件处理函数
+14. **移除 classNames**：改在各子组件上使用 `className` prop
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/kbd.mdx b/apps/docs/content/docs/cn/react/migration/(components)/kbd.mdx
new file mode 100644
index 0000000..f946110
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/kbd.mdx
@@ -0,0 +1,134 @@
+---
+title: Kbd
+description: Kbd 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Kbd 文档](/docs/react/components/kbd)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Kbd 通过 `keys` prop 自动渲染键盘按键：
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default function App() {
+  return <Kbd keys={["command"]}>K</Kbd>;
+}
+```
+
+在 v3 中，Kbd 改为复合组件，需要手动声明各个按键：
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Kbd>
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单组件加 `keys` prop  
+**v3：** 复合组件：`Kbd.Abbr`、`Kbd.Key`、`Kbd.Content`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `keys` | - | 已移除（改用 `Kbd.Abbr` 配合 `keyValue`） |
+| `classNames` | - | 改用 `className` |
+| - | `Kbd` | 新增 `variant` prop（`default` \| `light`） |
+| - | `Kbd.Key` | 用于按键文本的新增子组件（`Kbd.Content` 的替代写法） |
+
+## 迁移示例
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Kbd keys={["command"]}>K</Kbd>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Kbd variant="default">
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+    <Kbd variant="light">
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+    ```
+  </Tab>
+</Tabs>
+
+## Kbd.Key 与 Kbd.Content
+
+v3 提供了两个子组件用于包装按键文本内容：
+
+- **`Kbd.Key`**：用于按键的文本内容（例如字母或数字）。接受 `children` 与 `className` prop。
+- **`Kbd.Content`**：用于包装内容文本的等价写法。接受 `children` 与 `className` prop。
+
+两者在包装非修饰键的文本时可以互换使用：
+
+```tsx
+{/* Using Kbd.Key */}
+<Kbd>
+  <Kbd.Abbr keyValue="command" />
+  <Kbd.Key>K</Kbd.Key>
+</Kbd>
+
+{/* Using Kbd.Content */}
+<Kbd>
+  <Kbd.Abbr keyValue="command" />
+  <Kbd.Content>K</Kbd.Content>
+</Kbd>
+```
+
+## 组件结构
+
+v3 Kbd 遵循以下结构：
+
+```
+Kbd (Root)
+  ├── Kbd.Abbr (keyValue="command")
+  ├── Kbd.Abbr (keyValue="shift") [optional, multiple]
+  └── Kbd.Key or Kbd.Content [optional, for text content]
+```
+
+## 可用的键值
+
+`keyValue` prop 支持与 v2 相同的键盘按键类型：
+
+**修饰键：**
+- `command`、`shift`、`ctrl`、`option`、`alt`、`win`
+
+**特殊键：**
+- `enter`、`delete`、`escape`、`tab`、`space`、`capslock`、`help`
+
+**导航键：**
+- `up`、`down`、`left`、`right`、`pageup`、`pagedown`、`home`、`end`
+
+**功能键：**
+- `fn`
+
+## 总结
+
+1. **组件结构**：按键必须通过 `Kbd.Abbr` 子组件手动声明
+2. **移除 keys prop**：改用 `Kbd.Abbr` 配合 `keyValue`
+3. **包装子节点**：将文本内容包裹在 `Kbd.Content` 子组件中
+4. **移除 classNames**：改在各子组件上使用 `className` prop
+5. **新增 variant prop**：在 `Kbd` 上新增 `variant` 样式 prop（`default` \| `light`）
+6. **新增 Kbd.Key 子组件**：可作为 `Kbd.Content` 的替代写法用于按键文本
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/link.mdx b/apps/docs/content/docs/cn/react/migration/(components)/link.mdx
new file mode 100644
index 0000000..58a3148
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/link.mdx
@@ -0,0 +1,186 @@
+---
+title: Link
+description: Link 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Link 文档](/docs/react/components/link)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单个组件，通过 prop 配置图标  
+**v3：** 复合组件：使用 `Link.Icon` 子组件渲染图标
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `showAnchorIcon`、`anchorIcon` | - | 改用 `Link.Icon` 子组件配合 children |
+| `isExternal` | - | 改用 `target="_blank"` 与 `rel="noopener noreferrer"` |
+| `size`、`color`、`isBlock` | - | 已移除（请改用 Tailwind CSS） |
+| `disableAnimation` | - | 已移除 |
+| `underline` | - | 已移除（请使用 Tailwind 工具类，如 `underline` 等） |
+
+### 3. 新增 prop
+
+- `onPress` —— 链接被激活（通过点击或键盘）时触发的事件处理函数。接受 `(e: PressEvent) => void` 回调。
+
+## 结构变化
+
+在 v2 中，Link 组件的用法：
+
+```tsx
+import { Link } from "@heroui/react";
+
+export default function App() {
+  return <Link href="#">Default Link</Link>;
+}
+```
+
+在 v3 中，Link 组件在基本场景下的使用方式保持不变：
+
+```tsx
+import { Link } from "@heroui/react";
+
+export default function App() {
+  return <Link href="#">Default Link</Link>;
+}
+```
+
+## 迁移示例
+
+### 带图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Default icon */}
+    <Link showAnchorIcon href="#">
+      External Link
+    </Link>
+    
+    {/* Custom icon */}
+    <Link
+      showAnchorIcon
+      anchorIcon={<CustomIcon />}
+      href="#"
+    >
+      Custom Icon
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Default icon */}
+    <Link href="#">
+      External Link
+      <Link.Icon />
+    </Link>
+    
+    {/* Custom icon */}
+    <Link href="#">
+      Custom Icon
+      <Link.Icon>
+        <CustomIcon />
+      </Link.Icon>
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### 外部链接
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Link isExternal href="https://example.com">
+      External Link
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Link
+      href="https://example.com"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      External Link
+      <Link.Icon />
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### 下划线与偏移（v3：使用 Tailwind）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Link href="#" underline="hover">
+      Hover to underline
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Link href="#">
+      Hover to underline
+    </Link>
+    <Link href="#" className="underline underline-offset-2">
+      Underline with offset
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### 配合路由库
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import NextLink from "next/link";
+    import { Link } from "@heroui/react";
+
+    <Link as={NextLink} href="/about">
+      About
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import NextLink from "next/link";
+    import { Link } from "@heroui/react";
+
+    {/* Style your router link with the same classes as Link; add an icon if needed */}
+    <NextLink href="/about" className="link">
+      About
+    </NextLink>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 Link 遵循以下结构：
+
+```
+Link (Root)
+  ├── Link content (text)
+  └── Link.Icon (optional)
+```
+
+## 总结
+
+1. **图标处理**：`showAnchorIcon` 与 `anchorIcon` prop 由 `Link.Icon` 子组件取代
+2. **外部链接**：`isExternal` prop 已移除——请手动设置 `target` 与 `rel`
+3. **移除 size prop**：改用 Tailwind CSS 类（`text-sm`、`text-base`、`text-lg`）
+4. **移除 color prop**：改用 Tailwind CSS 类（`text-primary`、`text-danger` 等）
+5. **移除 isBlock prop**：改用 Tailwind CSS 类（`block`、`hover:bg-surface`）
+6. **下划线**：不再作为 prop 提供；Link 默认在悬浮时显示下划线。请使用 Tailwind 类（`underline`、`no-underline`、`underline-offset-1` 等）进行自定义
+7. **路由**：v3 Link 不再支持 `as` 或 `asChild`；请直接使用路由库的 Link 并配合相同的 Tailwind 类（例如 `link`、`link__icon`）保持视觉一致
+8. **移除动画**：`disableAnimation` prop 已移除
+9. **`onPress` 处理函数**：新增 `onPress` prop，可用于处理链接激活事件（点击或键盘）
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/listbox.mdx b/apps/docs/content/docs/cn/react/migration/(components)/listbox.mdx
new file mode 100644
index 0000000..a611190
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/listbox.mdx
@@ -0,0 +1,392 @@
+---
+title: Listbox
+description: Listbox 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 ListBox 文档](/docs/react/components/listbox)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+### v2：独立组件
+
+在 v2 中，Listbox 使用彼此独立的组件：
+
+```tsx
+import { Listbox, ListboxItem, ListboxSection } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Listbox>
+      <ListboxItem key="1">Item 1</ListboxItem>
+    </Listbox>
+  );
+}
+```
+
+### v3：复合组件
+
+在 v3 中，ListBox 使用复合组件：
+
+```tsx
+import { ListBox, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ListBox>
+      <ListBox.Item id="1" textValue="Item 1">
+        <Label>Item 1</Label>
+      </ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件命名
+
+**v2：** `Listbox`、`ListboxItem`、`ListboxSection`  
+**v3：** `ListBox`、`ListBox.Item`、`ListBox.Section`
+
+### 2. 条目标识
+
+**v2：** React 的 `key` 同时用于列表调和与条目身份（选择、焦点）。  
+**v3：** 使用 `id` 管理状态与焦点，使用 `textValue` 提供无障碍信息（当内容不是纯文本时）；列表中仍可为各项保留 React 的 `key`。
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `key`（用于状态） | `ListBox.Item` | 条目身份（状态）请使用 `id` |
+| — | `textValue`（在 `ListBox.Item` 上） | 用于无障碍（输入预判） |
+| `variant`、`color` | `ListBox` 或 `ListBox.Item` 上的 `variant` | 精简为 `"default"` \| `"danger"`（不再有单独的 `color` prop） |
+| `onAction` | `ListBox` | 按下条目时触发，签名为 `(key: Key) => void` |
+| `disabledKeys` | `ListBox` | 与 v2 相同——一组键，对应应为非交互的条目 |
+| `startContent`、`endContent` | — | 请在条目内容中手动放置图标 |
+| `description` | `Description` | 使用 `Description` 组件 |
+| `title`（在 Section 上） | `Header` | 使用 `Header` 组件 |
+| `topContent`、`bottomContent` | — | 已移除（请自行处理） |
+| `itemClasses`、`classNames` | — | 在各部分上使用 `className` |
+| `hideSelectedIcon` | — | 不渲染 `ListBox.ItemIndicator` |
+| `disableAnimation` | — | 已移除 |
+| `isVirtualized`、`virtualization` | React Aria `Virtualizer` | 使用 React Aria 的 `<Virtualizer>` 包装（见下方示例） |
+| `selectedKeys` | `ListBox` | 与 v2 相同（使用 `Selection` 类型的 Set） |
+
+## 迁移示例
+
+### 选择
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+
+    <Listbox
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <ListboxItem key="text">Text</ListboxItem>
+      <ListboxItem key="number">Number</ListboxItem>
+    </Listbox>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["text"]));
+
+    <Listbox
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <ListboxItem key="text">Text</ListboxItem>
+      <ListboxItem key="number">Number</ListboxItem>
+    </Listbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Selection } from "@heroui/react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState<Selection>(new Set(["text"]));
+
+    <ListBox
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <ListBox.Item id="text" textValue="Text">
+        <Label>Text</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="number" textValue="Number">
+        <Label>Number</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState<Selection>(new Set(["text"]));
+
+    <ListBox
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <ListBox.Item id="text" textValue="Text">
+        <Label>Text</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="number" textValue="Number">
+        <Label>Number</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+    ```
+  </Tab>
+</Tabs>
+
+### 含描述
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="new"
+      description="Create a new file"
+    >
+      New file
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, Label } from "@heroui/react";
+
+    <ListBox.Item id="new" textValue="New file">
+      <Label>New file</Label>
+      <Description>Create a new file</Description>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### 含图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="new"
+      startContent={<AddIcon />}
+    >
+      New file
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ListBox.Item id="new" textValue="New file">
+      <AddIcon />
+      <Label>New file</Label>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### 含分组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Listbox>
+      <ListboxSection title="Actions">
+        <ListboxItem key="new">New file</ListboxItem>
+        <ListboxItem key="edit">Edit file</ListboxItem>
+      </ListboxSection>
+      <ListboxSection title="Danger zone">
+        <ListboxItem key="delete">Delete</ListboxItem>
+      </ListboxSection>
+    </Listbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Label, Separator } from "@heroui/react";
+
+    <ListBox>
+      <ListBox.Section>
+        <Header>Actions</Header>
+        <ListBox.Item id="new" textValue="New file">
+          <Label>New file</Label>
+        </ListBox.Item>
+        <ListBox.Item id="edit" textValue="Edit file">
+          <Label>Edit file</Label>
+        </ListBox.Item>
+      </ListBox.Section>
+      <Separator />
+      <ListBox.Section>
+        <Header>Danger zone</Header>
+        <ListBox.Item id="delete" textValue="Delete" variant="danger">
+          <Label>Delete</Label>
+        </ListBox.Item>
+      </ListBox.Section>
+    </ListBox>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义选中指示器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="1"
+      selectedIcon={<CustomCheckIcon />}
+    >
+      Item 1
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ListBox.Item id="1" textValue="Item 1">
+      <Label>Item 1</Label>
+      <ListBox.ItemIndicator>
+        {({isSelected}) =>
+          isSelected ? <CustomCheckIcon /> : null
+        }
+      </ListBox.ItemIndicator>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### `variant` prop
+
+在 v3 中，`ListBox` 与 `ListBox.Item` 都接受 `variant` prop，取值为 `"default"`（默认）或 `"danger"`。在根级 `ListBox` 上设置 `variant` 会作用于所有条目；在单个 `ListBox.Item` 上设置会覆盖该条目的根级值。
+
+```tsx
+{/* Root-level variant — all items inherit "danger" styling */}
+<ListBox variant="danger">
+  <ListBox.Item id="delete" textValue="Delete">
+    <Label>Delete</Label>
+  </ListBox.Item>
+</ListBox>
+
+{/* Per-item variant */}
+<ListBox>
+  <ListBox.Item id="edit" textValue="Edit">
+    <Label>Edit</Label>
+  </ListBox.Item>
+  <ListBox.Item id="delete" textValue="Delete" variant="danger">
+    <Label>Delete</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### `onAction` 事件处理函数
+
+`onAction` 在条目被按下（点击或 Enter）时触发，参数为该条目的 `id`（类型为 `Key`）。
+
+```tsx
+<ListBox onAction={(key) => alert(`Action on ${key}`)}>
+  <ListBox.Item id="copy" textValue="Copy">
+    <Label>Copy</Label>
+  </ListBox.Item>
+  <ListBox.Item id="paste" textValue="Paste">
+    <Label>Paste</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### `disabledKeys`
+
+使用 `disabledKeys` 将特定条目设为非交互：
+
+```tsx
+<ListBox disabledKeys={new Set(["paste"])}>
+  <ListBox.Item id="copy" textValue="Copy">
+    <Label>Copy</Label>
+  </ListBox.Item>
+  <ListBox.Item id="paste" textValue="Paste">
+    <Label>Paste</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### `ListBox.Item` 的渲染 prop
+
+`ListBox.Item` 支持渲染 prop，可读取当前交互状态。可用字段包括 `isSelected`、`isFocused`、`isDisabled`、`isPressed`：
+
+```tsx
+<ListBox selectionMode="single">
+  <ListBox.Item id="item1" textValue="Item 1">
+    {({isSelected, isFocused, isDisabled, isPressed}) => (
+      <>
+        <Label className={isSelected ? "font-bold" : ""}>Item 1</Label>
+        {isSelected && <ListBox.ItemIndicator />}
+      </>
+    )}
+  </ListBox.Item>
+</ListBox>
+```
+
+### 虚拟化
+
+v3 仍通过 React Aria 的 `<Virtualizer>` **支持虚拟化**。用 `Virtualizer` 包裹 `ListBox` 的条目，以高效渲染长列表：
+
+```tsx
+import {Virtualizer} from "react-aria-components";
+
+<ListBox
+  aria-label="Large list"
+  items={items}
+  selectionMode="multiple"
+>
+  <Virtualizer>
+    {(item) => (
+      <ListBox.Item id={item.id} textValue={item.name}>
+        <Label>{item.name}</Label>
+      </ListBox.Item>
+    )}
+  </Virtualizer>
+</ListBox>
+```
+
+## 组件剖析
+
+v3 ListBox 的结构如下：
+
+```
+ListBox (Root)
+  ├── ListBox.Item
+  │   ├── Icon (optional, manual placement)
+  │   ├── Label (required)
+  │   ├── Description (optional)
+  │   └── ListBox.ItemIndicator (optional)
+  └── ListBox.Section (optional)
+      ├── Header (optional)
+      └── ListBox.Item
+```
+
+## 总结
+
+1. **组件命名**：`Listbox` → `ListBox`，`ListboxItem` → `ListBox.Item`，`ListboxSection` → `ListBox.Section`。
+2. **条目结构**：必须使用 `Label`、`Description`、`ListBox.ItemIndicator` 等组件。
+3. **图标**：不再使用 `startContent` / `endContent` prop，改为手动排版。
+4. **分组**：使用 `Header` 组件，不再使用 Section 的 `title` prop。
+5. **`variant` prop**：`variant` 与 `color` 合并为单一的 `variant`（`"default"` \| `"danger"`），可设在 `ListBox` 与 `ListBox.Item` 上。
+6. **`onAction`**：`ListBox` 上新增 `onAction`，用于处理条目按下。
+7. **`disabledKeys`**：仍在 `ListBox` 上支持，用于禁用特定条目。
+8. **渲染 prop**：`ListBox.Item` 通过渲染 prop 提供 `isSelected`、`isFocused`、`isDisabled`、`isPressed`。
+9. **已移除的内容 props**：`topContent`、`bottomContent`——请自行组织布局。
+10. **虚拟化**：仍通过 React Aria `<Virtualizer>` 支持（替代 `isVirtualized` prop）。
+11. **选择类型**：使用 `Selection` 类型（Set），而不是数组。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/modal.mdx b/apps/docs/content/docs/cn/react/migration/(components)/modal.mdx
new file mode 100644
index 0000000..215a45f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/modal.mdx
@@ -0,0 +1,492 @@
+---
+title: Modal
+description: Modal 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Modal 文档](/docs/react/components/modal)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Modal 使用相互独立的组件：
+
+```tsx
+import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Modal</Button>
+      <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+        <ModalContent>
+          <ModalHeader>Title</ModalHeader>
+          <ModalBody>Content</ModalBody>
+          <ModalFooter>Footer</ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+在 v3 中，Modal 使用复合组件：
+
+```tsx
+import { Modal, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Title</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>Content</Modal.Body>
+            <Modal.Footer>Footer</Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 相互独立的组件（`Modal`、`ModalContent`、`ModalHeader`、`ModalBody`、`ModalFooter`）  
+**v3：** 复合组件（`Modal.Backdrop`、`Modal.Container`、`Modal.Dialog`、`Modal.Header`、`Modal.Body`、`Modal.Footer`）
+
+### 2. 内置触发：`Modal.Trigger`
+
+**v2：** 需要 `useDisclosure`，并手动把 `onPress` 接到打开逻辑上。  
+**v3：** 提供 `Modal.Trigger` 作为内置触发组件，按下即可自动打开模态框，无需自行管理状态。
+
+<Tabs items={["v2", "v3 (Button trigger)", "v3 (Modal.Trigger)"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Modal, ModalContent, Button, useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    <Button onPress={onOpen}>Open Modal</Button>
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (Button trigger)">
+    ```tsx
+    import { Modal, Button } from "@heroui/react";
+
+    {/* A Button placed as a direct child of Modal automatically becomes the trigger */}
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>{/* content */}</Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (Modal.Trigger)">
+    ```tsx
+    import { Modal } from "@heroui/react";
+
+    {/* Use Modal.Trigger for custom trigger elements (cards, links, etc.) */}
+    <Modal>
+      <Modal.Trigger className="flex items-center gap-3 rounded-2xl bg-surface p-4">
+        <p className="font-semibold">Settings</p>
+        <p className="text-xs text-muted">Manage your preferences</p>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>{/* content */}</Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+`Modal.Trigger` 会把任意内容包装成可按压元素以打开模态框。当你需要标准 `Button` 以外的自定义触发元素时使用它。
+
+### 3. 状态管理
+
+**v2：** 使用 `useDisclosure`。  
+**v3：** 内置触发场景下可不需要状态；也可在 `Modal.Backdrop` 上用受控的 `isOpen` / `onOpenChange`，或使用 `useOverlayState` 并把 `state` 传给根组件。
+
+#### `useOverlayState` 替代 `useDisclosure`
+
+`useOverlayState` 可直接替代 v2 的 `useDisclosure`，支持受控与非受控：
+
+```tsx
+import { useOverlayState } from "@heroui/react";
+
+// 非受控（内部自管状态）
+const state = useOverlayState();
+
+// 非受控且默认打开
+const state = useOverlayState({ defaultOpen: true });
+
+// 带回调
+const state = useOverlayState({
+  onOpenChange: (isOpen) => console.log("Modal is now:", isOpen),
+});
+
+// 受控（由你管理状态）
+const [isOpen, setIsOpen] = useState(false);
+const state = useOverlayState({ isOpen, onOpenChange: setIsOpen });
+```
+
+**Hook API：**
+
+| 属性                    | 类型                         | 说明                 |
+| ----------------------- | ---------------------------- | -------------------- |
+| `state.isOpen`          | `boolean`                    | 浮层当前是否打开   |
+| `state.open()`          | `() => void`                 | 打开浮层           |
+| `state.close()`         | `() => void`                 | 关闭浮层           |
+| `state.toggle()`        | `() => void`                 | 切换打开/关闭      |
+| `state.setOpen(isOpen)` | `(isOpen: boolean) => void`  | 直接设置打开状态   |
+
+将 `state` 传给 `Modal` 根组件以完成连接：
+
+```tsx
+const state = useOverlayState();
+
+<Modal state={state}>
+  <Button onPress={state.open}>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>{/* content */}</Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+<Callout type="info">
+  从 `useDisclosure` 迁移到 `useOverlayState` 的更多细节，请参阅 [Hooks 迁移指南](/docs/react/migration/hooks)。
+</Callout>
+
+### 4. Prop 变更
+
+| v2 prop                     | v3 位置                         | 说明                                                         |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------ |
+| `size`                      | `size`（在 `Modal.Container`）  | 简化取值（xs、sm、md、lg、cover、full）                      |
+| `radius`                    | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `shadow`                    | —                               | 已移除（请用 Tailwind CSS）                                  |
+| `backdrop`                  | `variant`（在 **`Modal.Backdrop`**） | 已重命名；取值不变（`opaque`、`blur`、`transparent`）   |
+| `scrollBehavior`            | `scroll`（在 `Modal.Container`） | 已重命名（`normal` → `inside`）                             |
+| `placement`                 | `placement`（在 `Modal.Container`） | 移到 Container                                            |
+| `isDismissable`             | `isDismissable`（在 **`Modal.Backdrop`**） | 移到 `Modal.Backdrop`                              |
+| `isKeyboardDismissDisabled` | `isKeyboardDismissDisabled`（在 **`Modal.Backdrop`**） | 移到 `Modal.Backdrop`              |
+| `isOpen`                    | `isOpen`（在 **`Modal.Backdrop`**） | 受控状态在 `Modal.Backdrop`                              |
+| `onOpenChange`              | `onOpenChange`（在 **`Modal.Backdrop`**） | 同上                                                 |
+| `onClose`                   | —                               | 使用渲染 prop 提供的 `close`                                 |
+| `hideCloseButton`           | —                               | 省略 `Modal.CloseTrigger` 即可                               |
+| `closeButton`               | —                               | 使用 `Modal.CloseTrigger` 自定义内容                         |
+| `motionProps`               | —                               | 已移除（动画机制已不同）                                     |
+| `classNames`                | —                               | 在各子组件上使用 `className`                                 |
+| `shouldBlockScroll`         | —                               | 已移除（由组件自动处理）                                     |
+| `portalContainer`           | —                               | 已移除                                                       |
+
+## 迁移示例
+
+### 受控 Modal
+
+<Tabs items={["v2", "v3 (useState)", "v3 (useOverlayState)", "v3 (state prop)"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>
+        {(onClose) => (
+          <>
+            <ModalHeader>Title</ModalHeader>
+            <ModalBody>Content</ModalBody>
+          </>
+        )}
+      </ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (useState)">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Modal>
+      <Button onPress={() => setIsOpen(true)}>Open</Button>
+      <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (useOverlayState)">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    const state = useOverlayState();
+
+    <Modal>
+      <Button onPress={state.open}>Open</Button>
+      <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (state prop)">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    // 将 state 直接传给 Modal 根组件，无需再手动连接 isOpen/onOpenChange
+    const state = useOverlayState();
+
+    <Modal state={state}>
+      <Button onPress={state.open}>Open</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  `useDisclosure` → `useOverlayState` 的完整迁移说明，请参阅 [Hooks 迁移指南](/docs/react/migration/hooks)。
+</Callout>
+
+### 遮罩与 Container 的 prop
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Backdrop */}
+    <Modal backdrop="blur">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Placement */}
+    <Modal placement="top">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Scroll behavior */}
+    <Modal scrollBehavior="outside">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 遮罩：在 Modal.Backdrop 上使用 variant */}
+    <Modal.Backdrop variant="blur">
+      <Modal.Container>
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    
+    {/* 位置：在 Container 上 */}
+    <Modal.Backdrop>
+      <Modal.Container placement="top">
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    
+    {/* 滚动：在 Container 上 */}
+    <Modal.Backdrop>
+      <Modal.Container scroll="outside">
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    ```
+  </Tab>
+</Tabs>
+
+### 关闭按钮
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Without close button */}
+    <Modal hideCloseButton>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Custom close button */}
+    <Modal closeButton={<CustomCloseIcon />}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 无关闭按钮：省略 Modal.CloseTrigger */}
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.Header>
+          <Modal.Heading>Title</Modal.Heading>
+        </Modal.Header>
+      </Modal.Dialog>
+    </Modal.Container>
+    
+    {/* 自定义关闭按钮 */}
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.CloseTrigger>
+          <CustomCloseIcon />
+        </Modal.CloseTrigger>
+        {/* content */}
+      </Modal.Dialog>
+    </Modal.Container>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义触发器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Modal, ModalContent, useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    {/* Any element needed manual onPress + useDisclosure */}
+    <div onClick={onOpen} className="cursor-pointer rounded-xl bg-surface p-4">
+      <p className="font-semibold">Settings</p>
+      <p className="text-xs text-muted">Manage your preferences</p>
+    </div>
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Modal } from "@heroui/react";
+
+    {/* Modal.Trigger handles press events and accessibility automatically */}
+    <Modal>
+      <Modal.Trigger className="rounded-xl bg-surface p-4">
+        <p className="font-semibold">Settings</p>
+        <p className="text-xs text-muted">Manage your preferences</p>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Settings</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>{/* content */}</Modal.Body>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+### 图标与标题
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ModalHeader className="flex flex-col gap-1">
+      <Icon />
+      Modal Title
+    </ModalHeader>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Modal.Header>
+      <Modal.Icon>
+        <Icon />
+      </Modal.Icon>
+      <Modal.Heading>Modal Title</Modal.Heading>
+    </Modal.Header>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构（Anatomy）
+
+v3 的 Modal 结构如下：
+
+```
+Modal (Root)
+  ├── Trigger (e.g. Button or Modal.Trigger)
+  └── Modal.Backdrop (variant, isDismissable, isKeyboardDismissDisabled)
+      └── Modal.Container (placement, scroll, size)
+          └── Modal.Dialog
+              ├── Modal.CloseTrigger (optional)
+              ├── Modal.Header
+              │   ├── Modal.Icon (optional)
+              │   └── Modal.Heading
+              ├── Modal.Body
+              └── Modal.Footer
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Modal.Container`、`Modal.Dialog` 等）。
+2. **内置触发**：自定义触发用 `Modal.Trigger`；或将 `Button` 作为 `Modal` 的直接子元素，无需再手动接线状态。
+3. **状态管理**：`useDisclosure` 由 `useOverlayState` 替代；支持受控/非受控，并支持根 `Modal` 的 `state` prop。
+4. **prop 迁移**：许多 prop 从 `Modal` 移到 `Modal.Backdrop` 与 `Modal.Container`。
+5. **关闭回调**：`onClose` 由 `Modal.Dialog` 渲染 prop 中的 `close` 替代。
+6. **关闭按钮**：`hideCloseButton` / `closeButton` 由 `Modal.CloseTrigger` 组合方式替代。
+7. **尺寸**：在 `Modal.Container` 上使用 `size`（xs、sm、md、lg、cover、full）；`radius` 与 `shadow` 已移除，请用 Tailwind CSS。
+8. **遮罩**：`backdrop` → `Modal.Backdrop` 上的 `variant`（`opaque`、`blur`、`transparent`）。
+9. **滚动 prop 重命名**：`scrollBehavior` → `scroll`（`normal` → `inside`）。
+10. **动画**：`motionProps` 已移除，动画机制已变化。
+11. **新增子组件**：`Modal.Trigger`、`Modal.Icon`、`Modal.Heading`、`Modal.CloseTrigger`。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/navbar.mdx b/apps/docs/content/docs/cn/react/migration/(components)/navbar.mdx
new file mode 100644
index 0000000..e99ec89
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/navbar.mdx
@@ -0,0 +1,645 @@
+---
+title: Navbar
+description: Navbar 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  HeroUI v3 已**移除** Navbar 组件。请使用原生 HTML 元素与 Tailwind CSS 类手动搭建导航栏。本指南介绍常见模式，并简化复杂能力的说明。
+</Callout>
+
+## 关键变化
+
+### 1. 组件移除
+
+**v2：** `<Navbar>` 与子组件（`NavbarBrand`、`NavbarContent`、`NavbarItem`、`NavbarMenu`、`NavbarMenuItem`、`NavbarMenuToggle`）  
+**v3：** 使用原生 HTML 手动组合
+
+### 2. 子组件映射
+
+| v2 组件 | v3 对应 | 说明 |
+| ------- | ------- | ---- |
+| `Navbar` | `<nav>` 元素 | 主容器 |
+| `NavbarBrand` | `<div>` 或 `<a>` | Logo / 品牌区 |
+| `NavbarContent` | `<ul>` 元素 | 导航列表 |
+| `NavbarItem` | `<li>` 元素 | 导航项 |
+| `NavbarMenu` | 移动端菜单覆盖层 | 需自行实现 |
+| `NavbarMenuItem` | 移动菜单内的 `<li>` | 移动菜单项 |
+| `NavbarMenuToggle` | `<button>` | 移动菜单切换 |
+
+### 3. 已移除的能力
+
+- `shouldHideOnScroll` — 需自行实现滚动检测  
+- `isBlurred` — 请使用 Tailwind CSS 的 `backdrop-blur` 工具类  
+- `isBordered` — 请使用 Tailwind CSS 边框类  
+- `position` 变体 — 请使用 Tailwind CSS 的 `sticky`、`fixed` 等类  
+- `maxWidth` 变体 — 请使用 Tailwind CSS 的 `max-w-*` 类  
+- 移动菜单动画 — 需自行实现  
+- 滚动锁定 — 需自行实现（见下文「滚动锁定」）
+
+## 迁移示例
+
+### 基础 Navbar
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Navbar, NavbarBrand, NavbarContent, NavbarItem, Link, Button } from "@heroui/react";
+
+    {/* Basic */}
+    <Navbar>
+      <NavbarBrand>
+        <Logo />
+        <p className="font-bold">ACME</p>
+      </NavbarBrand>
+      <NavbarContent>
+        <NavbarItem><Link href="#">Features</Link></NavbarItem>
+        <NavbarItem><Link href="#">Pricing</Link></NavbarItem>
+      </NavbarContent>
+    </Navbar>
+    
+    {/* With right-aligned content */}
+    <Navbar>
+      <NavbarBrand>Logo</NavbarBrand>
+      <NavbarContent justify="end">
+        <NavbarItem><Button>Sign Up</Button></NavbarItem>
+      </NavbarContent>
+    </Navbar>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Link, Button } from "@heroui/react";
+
+    {/* Basic */}
+    <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+      <header className="flex h-16 items-center justify-between px-6">
+        <div className="flex items-center gap-3">
+          <Logo />
+          <p className="font-bold">ACME</p>
+        </div>
+        <ul className="flex items-center gap-4">
+          <li><Link href="#">Features</Link></li>
+          <li><Link href="#">Pricing</Link></li>
+        </ul>
+      </header>
+    </nav>
+    
+    {/* With right-aligned content */}
+    <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+      <header className="flex h-16 items-center justify-between px-6">
+        <div>Logo</div>
+        <ul className="flex items-center gap-4">
+          <li><Button>Sign Up</Button></li>
+        </ul>
+      </header>
+    </nav>
+    ```
+  </Tab>
+</Tabs>
+
+### 移动菜单（简化版）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import {
+      Navbar,
+      NavbarBrand,
+      NavbarContent,
+      NavbarItem,
+      NavbarMenu,
+      NavbarMenuItem,
+      NavbarMenuToggle,
+    } from "@heroui/react";
+
+    function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <Navbar onMenuOpenChange={setIsMenuOpen}>
+          <NavbarContent>
+            <NavbarMenuToggle className="sm:hidden" />
+            <NavbarBrand>Logo</NavbarBrand>
+          </NavbarContent>
+          <NavbarContent className="hidden md:flex">
+            <NavbarItem>Features</NavbarItem>
+            <NavbarItem>Pricing</NavbarItem>
+          </NavbarContent>
+          <NavbarMenu>
+            <NavbarMenuItem>Features</NavbarMenuItem>
+            <NavbarMenuItem>Pricing</NavbarMenuItem>
+          </NavbarMenu>
+        </Navbar>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Link, Button } from "@heroui/react";
+
+    function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+          <header className="flex h-16 items-center justify-between px-6">
+            <div className="flex items-center gap-4">
+              <button
+                className="md:hidden"
+                onClick={() => setIsMenuOpen(!isMenuOpen)}
+                aria-label="Toggle menu"
+              >
+                <span className="sr-only">Menu</span>
+                <svg
+                  className="h-6 w-6"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  {isMenuOpen ? (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M6 18L18 6M6 6l12 12"
+                    />
+                  ) : (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 6h16M4 12h16M4 18h16"
+                    />
+                  )}
+                </svg>
+              </button>
+              <div>Logo</div>
+            </div>
+            <ul className="hidden items-center gap-4 md:flex">
+              <li>
+                <Link href="#">Features</Link>
+              </li>
+              <li>
+                <Link href="#">Pricing</Link>
+              </li>
+            </ul>
+          </header>
+          {isMenuOpen && (
+            <div className="border-t border-separator md:hidden">
+              <ul className="flex flex-col gap-2 p-4">
+                <li>
+                  <Link href="#" className="block py-2">
+                    Features
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2">
+                    Pricing
+                  </Link>
+                </li>
+              </ul>
+            </div>
+          )}
+        </nav>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 完整示例
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import {
+      Navbar,
+      NavbarBrand,
+      NavbarContent,
+      NavbarItem,
+      NavbarMenu,
+      NavbarMenuItem,
+      NavbarMenuToggle,
+      Link,
+      Button,
+    } from "@heroui/react";
+
+    export default function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <Navbar position="sticky" maxWidth="lg" onMenuOpenChange={setIsMenuOpen}>
+          <NavbarContent>
+            <NavbarMenuToggle className="sm:hidden" />
+            <NavbarBrand>
+              <Logo />
+              <p className="font-bold">ACME</p>
+            </NavbarBrand>
+          </NavbarContent>
+          <NavbarContent className="hidden md:flex">
+            <NavbarItem>
+              <Link href="#">Features</Link>
+            </NavbarItem>
+            <NavbarItem isActive>
+              <Link href="#">Dashboard</Link>
+            </NavbarItem>
+            <NavbarItem>
+              <Link href="#">Pricing</Link>
+            </NavbarItem>
+          </NavbarContent>
+          <NavbarContent justify="end">
+            <NavbarItem>
+              <Link href="#">Login</Link>
+            </NavbarItem>
+            <NavbarItem>
+              <Button>Sign Up</Button>
+            </NavbarItem>
+          </NavbarContent>
+          <NavbarMenu>
+            <NavbarMenuItem>
+              <Link href="#">Features</Link>
+            </NavbarMenuItem>
+            <NavbarMenuItem>
+              <Link href="#">Dashboard</Link>
+            </NavbarMenuItem>
+            <NavbarMenuItem>
+              <Link href="#">Pricing</Link>
+            </NavbarMenuItem>
+          </NavbarMenu>
+        </Navbar>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Link, Button } from "@heroui/react";
+
+    export default function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+          <header className="mx-auto flex h-16 max-w-5xl items-center justify-between px-6">
+            <div className="flex items-center gap-4">
+              <button
+                className="md:hidden"
+                onClick={() => setIsMenuOpen(!isMenuOpen)}
+                aria-label="Toggle menu"
+                aria-expanded={isMenuOpen}
+              >
+                <span className="sr-only">Menu</span>
+                <svg
+                  className="h-6 w-6"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  {isMenuOpen ? (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M6 18L18 6M6 6l12 12"
+                    />
+                  ) : (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 6h16M4 12h16M4 18h16"
+                    />
+                  )}
+                </svg>
+              </button>
+              <div className="flex items-center gap-3">
+                <Logo />
+                <p className="font-bold">ACME</p>
+              </div>
+            </div>
+            <ul className="hidden items-center gap-4 md:flex">
+              <li>
+                <Link href="#">Features</Link>
+              </li>
+              <li>
+                <Link href="#" className="font-medium text-accent" aria-current="page">
+                  Dashboard
+                </Link>
+              </li>
+              <li>
+                <Link href="#">Pricing</Link>
+              </li>
+            </ul>
+            <div className="hidden items-center gap-4 md:flex">
+              <Link href="#">Login</Link>
+              <Button>Sign Up</Button>
+            </div>
+          </header>
+          {isMenuOpen && (
+            <div className="border-t border-separator md:hidden">
+              <ul className="flex flex-col gap-2 p-4">
+                <li>
+                  <Link href="#" className="block py-2">
+                    Features
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2 font-medium text-accent">
+                    Dashboard
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2">
+                    Pricing
+                  </Link>
+                </li>
+                <li className="mt-4 flex flex-col gap-2 border-t border-separator pt-4">
+                  <Link href="#" className="block py-2">
+                    Login
+                  </Link>
+                  <Button className="w-full">Sign Up</Button>
+                </li>
+              </ul>
+            </div>
+          )}
+        </nav>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 创建可复用的 Navbar 组件（推荐）
+
+导航栏在应用中很常见，下面是一个简化的可复用组件示例：
+
+```tsx
+import { useState, ReactNode } from "react";
+import { Link, Button } from "@heroui/react";
+import { cn } from "@/lib/utils"; // or your cn utility
+
+interface NavbarItem {
+  label: string;
+  href: string;
+  isActive?: boolean;
+}
+
+interface NavbarProps {
+  brand: ReactNode;
+  items: NavbarItem[];
+  rightContent?: ReactNode;
+  className?: string;
+  maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+  position?: "static" | "sticky" | "fixed";
+}
+
+const maxWidthClasses = {
+  sm: "max-w-[640px]",
+  md: "max-w-[768px]",
+  lg: "max-w-[1024px]",
+  xl: "max-w-[1280px]",
+  "2xl": "max-w-[1536px]",
+  full: "max-w-full",
+};
+
+export function Navbar({
+  brand,
+  items,
+  rightContent,
+  className,
+  maxWidth = "lg",
+  position = "sticky",
+}: NavbarProps) {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <nav
+      className={cn(
+        "z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg",
+        position === "sticky" && "sticky top-0",
+        position === "fixed" && "fixed top-0",
+        className
+      )}
+    >
+      <header
+        className={cn(
+          "flex h-16 items-center justify-between px-6",
+          maxWidth !== "full" && maxWidthClasses[maxWidth],
+          "mx-auto"
+        )}
+      >
+        <div className="flex items-center gap-4">
+          <button
+            className="md:hidden"
+            onClick={() => setIsMenuOpen(!isMenuOpen)}
+            aria-label="Toggle menu"
+            aria-expanded={isMenuOpen}
+          >
+            <span className="sr-only">Menu</span>
+            <svg className="h-6 w-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              {isMenuOpen ? (
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M6 18L18 6M6 6l12 12"
+                />
+              ) : (
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M4 6h16M4 12h16M4 18h16"
+                />
+              )}
+            </svg>
+          </button>
+          {brand}
+        </div>
+        <ul className="hidden items-center gap-4 md:flex">
+          {items.map((item) => (
+            <li key={item.href}>
+              <Link
+                href={item.href}
+                className={cn(item.isActive && "font-medium text-accent")}
+                aria-current={item.isActive ? "page" : undefined}
+              >
+                {item.label}
+              </Link>
+            </li>
+          ))}
+        </ul>
+        {rightContent && <div className="hidden items-center gap-4 md:flex">{rightContent}</div>}
+      </header>
+      {isMenuOpen && (
+        <div className="border-t border-separator md:hidden">
+          <ul className="flex flex-col gap-2 p-4">
+            {items.map((item) => (
+              <li key={item.href}>
+                <Link
+                  href={item.href}
+                  className={cn(
+                    "block py-2",
+                    item.isActive && "font-medium text-accent"
+                  )}
+                >
+                  {item.label}
+                </Link>
+              </li>
+            ))}
+            {rightContent && (
+              <li className="mt-4 flex flex-col gap-2 border-t border-separator pt-4">
+                {rightContent}
+              </li>
+            )}
+          </ul>
+        </div>
+      )}
+    </nav>
+  );
+}
+
+// Usage
+<Navbar
+  brand={
+    <>
+      <Logo />
+      <p className="font-bold">ACME</p>
+    </>
+  }
+  items={[
+    { label: "Features", href: "#features" },
+    { label: "Dashboard", href: "#dashboard", isActive: true },
+    { label: "Pricing", href: "#pricing" },
+  ]}
+  rightContent={
+    <>
+      <Link href="#login">Login</Link>
+      <Button>Sign Up</Button>
+    </>
+  }
+/>
+```
+
+## 高级能力（需自行实现）
+
+### 滚动时隐藏
+
+`shouldHideOnScroll` 需要自行实现滚动检测：
+
+```tsx
+import { useState, useEffect } from "react";
+
+function useScrollDirection() {
+  const [isHidden, setIsHidden] = useState(false);
+  const [lastScrollY, setLastScrollY] = useState(0);
+
+  useEffect(() => {
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY;
+      setIsHidden(currentScrollY > lastScrollY && currentScrollY > 64);
+      setLastScrollY(currentScrollY);
+    };
+
+    window.addEventListener("scroll", handleScroll);
+    return () => window.removeEventListener("scroll", handleScroll);
+  }, [lastScrollY]);
+
+  return isHidden;
+}
+
+function NavbarWithHideOnScroll() {
+  const isHidden = useScrollDirection();
+
+  return (
+    <nav
+      className={cn(
+        "sticky top-0 z-40 w-full transition-transform duration-300",
+        isHidden && "-translate-y-full"
+      )}
+    >
+      {/* navbar content */}
+    </nav>
+  );
+}
+```
+
+### 滚动锁定
+
+在移动菜单打开时锁定页面滚动：
+
+```tsx
+useEffect(() => {
+  if (isMenuOpen) {
+    document.body.style.overflow = "hidden";
+  } else {
+    document.body.style.overflow = "";
+  }
+  return () => {
+    document.body.style.overflow = "";
+  };
+}, [isMenuOpen]);
+```
+
+## 总结
+
+1. **组件已移除**：`Navbar`、`NavbarBrand`、`NavbarContent`、`NavbarItem`、`NavbarMenu`、`NavbarMenuItem`、`NavbarMenuToggle` 均已移除。  
+2. **导入调整**：从 `@heroui/react` 中移除所有 Navbar 相关导入。  
+3. **手动组合**：使用原生 HTML 搭建导航栏。  
+4. **移动菜单**：通过状态管理手动实现移动菜单。  
+5. **样式**：直接使用 Tailwind CSS 类。  
+6. **高级能力**：滚动时隐藏、动画等需自行实现。
+
+## 迁移步骤
+
+1. **移除导入**：删除所有与 Navbar 相关的导入。  
+2. **替换结构**：将 `<Navbar>` 替换为 `<nav>`。  
+3. **替换子组件**：用语义化 HTML（`<header>`、`<ul>`、`<li>`）替代子组件。  
+4. **补充移动菜单**：手动实现菜单切换与菜单面板。  
+5. **应用样式**：用 Tailwind CSS 完成布局与样式。  
+6. **管理状态**：用 React `useState` 管理移动菜单开关。  
+7. **（可选）** 为应用封装可复用的 Navbar 组件。
+
+## 常见模式
+
+### 简单导航
+
+```tsx
+<nav className="sticky top-0 z-40 w-full border-b border-separator bg-background">
+  <header className="flex h-16 items-center justify-between px-6">
+    <div>Logo</div>
+    <ul className="flex items-center gap-4">
+      <li><Link href="#">Home</Link></li>
+      <li><Link href="#">About</Link></li>
+      <li><Link href="#">Contact</Link></li>
+    </ul>
+  </header>
+</nav>
+```
+
+### 搭配下拉（使用 v3 Dropdown）
+
+```tsx
+import { Dropdown, Button, Label } from "@heroui/react";
+
+<ul className="flex items-center gap-4">
+  <li>
+    <Dropdown>
+      <Button variant="ghost">Features</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="feature1" textValue="Feature 1">
+            <Label>Feature 1</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="feature2" textValue="Feature 2">
+            <Label>Feature 2</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  </li>
+</ul>
+```
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/numberinput.mdx b/apps/docs/content/docs/cn/react/migration/(components)/numberinput.mdx
new file mode 100644
index 0000000..59b56c4
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/numberinput.mdx
@@ -0,0 +1,272 @@
+---
+title: NumberInput
+description: NumberInput → NumberField 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 NumberField 文档](/docs/react/components/numberfield)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，NumberInput 是单个组件，通过 prop 配置：
+
+```tsx
+import { NumberInput } from "@heroui/react";
+
+export default function App() {
+  return <NumberInput label="Amount" defaultValue={1024} />;
+}
+```
+
+在 v3 中，NumberField 改为复合组件：
+
+```tsx
+import { NumberField, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <NumberField defaultValue={1024}>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件命名
+
+**v2：** `NumberInput`  
+**v3：** `NumberField`
+
+### 2. 组件结构
+
+**v2：** 单个组件，通过 prop 配置  
+**v3：** 复合组件：`NumberField.Group`、`NumberField.Input`、`NumberField.IncrementButton`、`NumberField.DecrementButton`
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `onValueChange` | `onChange` | 事件处理函数已重命名 |
+| `label` | — | 改用 `Label` 组件 |
+| `description` | — | 改用 `Description` 组件 |
+| `errorMessage` | — | 改用 `FieldError` 组件 |
+| `variant` | `variant`（在 NumberField 上） | 简化为仅 `primary` \| `secondary` |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `radius` | — | 已移除（请改用 Tailwind CSS） |
+| `startContent` | — | 手动将内容放入 Group 中 |
+| `endContent` | — | 手动将内容放入 Group 中 |
+| `labelPlacement` | — | 通过布局类自行处理 |
+| `hideStepper` | — | 省略 `NumberField.IncrementButton` 与 `NumberField.DecrementButton` |
+| `isClearable` | — | 请手动实现清除功能 |
+| `classNames` | — | 改在各子组件上使用 `className` prop |
+| `isWheelDisabled` | — | 已移除 |
+
+## 迁移示例
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <NumberInput
+      description="Enter the amount"
+      label="Amount"
+    />
+    
+    {/* With error message */}
+    <NumberInput
+      errorMessage="Please enter a valid number"
+      isInvalid
+      label="Amount"
+    />
+    
+    {/* Required */}
+    <NumberInput isRequired label="Quantity" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    {/* With description */}
+    <NumberField>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+      <Description>Enter the amount</Description>
+    </NumberField>
+    
+    {/* With error message */}
+    <NumberField isInvalid>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+      <FieldError>Please enter a valid number</FieldError>
+    </NumberField>
+    
+    {/* Required */}
+    <NumberField isRequired>
+      <Label>Quantity</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState();
+
+    <NumberInput
+      value={value}
+      onValueChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState<number | undefined>();
+
+    <NumberField value={value} onChange={setValue}>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### 不带步进按钮
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <NumberInput hideStepper label="Amount" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <NumberField>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.Input />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### 数值约束
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Min/Max */}
+    <NumberInput
+      label="Quantity"
+      maxValue={100}
+      minValue={0}
+    />
+    
+    {/* Step */}
+    <NumberInput label="Percentage" step={0.1} />
+    
+    {/* Format options */}
+    <NumberInput
+      formatOptions={{style: "currency", currency: "USD"}}
+      label="Price"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Min/Max */}
+    <NumberField maxValue={100} minValue={0}>
+      <Label>Quantity</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    
+    {/* Step */}
+    <NumberField step={0.1}>
+      <Label>Percentage</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    
+    {/* Format options */}
+    <NumberField formatOptions={{style: "currency", currency: "USD"}}>
+      <Label>Price</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 NumberField 遵循以下结构：
+
+```
+NumberField (Root)
+  ├── Label (optional)
+  ├── NumberField.Group
+  │   ├── NumberField.DecrementButton
+  │   ├── NumberField.Input
+  │   └── NumberField.IncrementButton
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## 总结
+
+1. **组件重命名**：`NumberInput` → `NumberField`
+2. **组件结构**：必须使用复合组件（`NumberField.Group`、`NumberField.Input` 等）
+3. **标签 / 描述 / 错误**：改用独立组件（`Label`、`Description`、`FieldError`）
+4. **步进按钮**：必须显式包含 `NumberField.IncrementButton` 与 `NumberField.DecrementButton`
+5. **事件处理函数**：`onValueChange` → `onChange`
+6. **简化变体**：v3 仅支持 `variant="primary"` 与 `variant="secondary"`；`color`、`size`、`radius` 已移除——请改用 Tailwind CSS
+7. **移除 content prop**：`startContent`、`endContent` —— 请手动放置
+8. **移除清除按钮**：`isClearable` 已移除——请自行实现
+9. **步进控件**：`hideStepper` 已移除——通过省略相应按钮实现
+10. **移除 labelPlacement**：`labelPlacement` 已移除——请通过布局自行实现
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/pagination.mdx b/apps/docs/content/docs/cn/react/migration/(components)/pagination.mdx
new file mode 100644
index 0000000..2496919
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/pagination.mdx
@@ -0,0 +1,424 @@
+---
+title: Pagination
+description: Pagination 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Pagination 文档](/docs/react/components/pagination)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Pagination` 是单个组件，通过 props 在内部完成所有渲染：
+
+```tsx
+import { Pagination } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Pagination total={10} initialPage={1} showControls />
+  );
+}
+```
+
+在 v3 中，Pagination 采用复合组件模式，需要显式组合各个部分：
+
+```tsx
+import { Pagination } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous>
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link isActive>1</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>2</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>3</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Ellipsis />
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>10</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单个 `Pagination` 组件，通过 `total` prop 自动生成页码项  
+**v3：** 复合组件：`Pagination`、`Pagination.Summary`、`Pagination.Content`、`Pagination.Item`、`Pagination.Link`、`Pagination.Previous`、`Pagination.PreviousIcon`、`Pagination.Next`、`Pagination.NextIcon`、`Pagination.Ellipsis`
+
+### 2. 页码生成
+
+**v2：** 由 `total`、`siblings`、`boundaries` 等 props 自动生成页码  
+**v3：** 手动组合页码项，完全掌控布局与行为；可自行实现分页逻辑或使用分页 hook。
+
+### 3. Prop 变更
+
+| v2 prop | v3 对应 | 说明 |
+| ------- | ------- | ---- |
+| `total` | — | 已移除（请手动组合条目） |
+| `page` | — | 通过在 `Pagination.Link` 上使用 `isActive` 管理当前页 |
+| `initialPage` | — | 请在外部自行管理状态 |
+| `onChange` | — | 请在各个 `Pagination.Link` 上使用 `onPress` |
+| `siblings` | — | 已移除（请手动组合条目） |
+| `boundaries` | — | 已移除（请手动组合条目） |
+| `dotsJump` | — | 已移除（省略号点击请自行处理） |
+| `loop` | — | 已移除（请自行实现） |
+| `showControls` | — | 请组合 `Pagination.Previous` 与 `Pagination.Next` |
+| `isCompact` | — | 已移除（请用 Tailwind CSS 控制样式） |
+| `showShadow` | — | 已移除（请使用 Tailwind `shadow-*` 类） |
+| `size` | `Pagination` 上的 `size` | 与 v2 相同（`sm`、`md`、`lg`） |
+| `variant` | — | 已移除（请使用 Tailwind CSS） |
+| `color` | — | 已移除（请使用 Tailwind CSS） |
+| `radius` | — | 已移除（请使用 Tailwind CSS） |
+| `isDisabled` | `Pagination.Link`、`Pagination.Previous`、`Pagination.Next` 上的 `isDisabled` | 按条目分别控制，而非全局 |
+| `disableCursorAnimation` | — | 已移除 |
+| `disableAnimation` | — | 已移除 |
+| `renderItem` | — | 请直接组合子节点 |
+| `getItemAriaLabel` | — | 请在各条目上设置 `aria-label` |
+| `classNames` | — | 请在各复合子组件上使用 `className` |
+
+### 4. Hook 变化
+
+**v2：** 提供 `usePagination` hook，便于自定义实现  
+**v3：** 无内置 hook——请直接组合分页项，或自行实现分页逻辑
+
+## 迁移示例
+
+### 基础分页
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Pagination } from "@heroui/react";
+
+    <Pagination total={10} initialPage={1} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Pagination } from "@heroui/react";
+
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### 上一页 / 下一页控件
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Pagination total={10} initialPage={1} showControls />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => Math.max(1, p - 1))}
+          >
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+          >
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### 含省略号
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Pagination total={20} initialPage={1} siblings={1} boundaries={1} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 20;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => Math.max(1, p - 1))}
+          >
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link isActive={page === 1} onPress={() => setPage(1)}>
+            1
+          </Pagination.Link>
+        </Pagination.Item>
+        {page > 3 && (
+          <Pagination.Item>
+            <Pagination.Ellipsis />
+          </Pagination.Item>
+        )}
+        {[page - 1, page, page + 1]
+          .filter((p) => p > 1 && p < totalPages)
+          .map((p) => (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ))}
+        {page < totalPages - 2 && (
+          <Pagination.Item>
+            <Pagination.Ellipsis />
+          </Pagination.Item>
+        )}
+        <Pagination.Item>
+          <Pagination.Link
+            isActive={page === totalPages}
+            onPress={() => setPage(totalPages)}
+          >
+            {totalPages}
+          </Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+          >
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### 仅上一页 / 下一页
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 无内置的仅 prev/next 模式 */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => p - 1)}
+          >
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => p + 1)}
+          >
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用 `Pagination.Summary`
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 无内置 summary 插槽 */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const perPage = 10;
+    const total = 100;
+
+    <Pagination>
+      <Pagination.Summary>
+        Showing {(page - 1) * perPage + 1}-{Math.min(page * perPage, total)} of {total}
+      </Pagination.Summary>
+      <Pagination.Content>
+        {/* Pagination items */}
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 需借助 renderItem 才能自定义图标 */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon>
+              <Icon icon="gravity-ui:arrow-left" />
+            </Pagination.PreviousIcon>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {/* Page links */}
+        <Pagination.Item>
+          <Pagination.Next onPress={() => setPage((p) => p + 1)}>
+            <Pagination.NextIcon>
+              <Icon icon="gravity-ui:arrow-right" />
+            </Pagination.NextIcon>
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<Pagination
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    prev: "custom-prev",
+    next: "custom-next",
+    item: "custom-item",
+    cursor: "custom-cursor",
+    ellipsis: "custom-ellipsis",
+  }}
+/>
+```
+
+### v3：直接使用 `className`
+
+```tsx
+<Pagination className="custom-base">
+  <Pagination.Content className="custom-wrapper">
+    <Pagination.Item className="custom-item">
+      <Pagination.Previous className="custom-prev">
+        <Pagination.PreviousIcon />
+      </Pagination.Previous>
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Link isActive className="custom-cursor">1</Pagination.Link>
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Ellipsis className="custom-ellipsis" />
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Next className="custom-next">
+        <Pagination.NextIcon />
+      </Pagination.Next>
+    </Pagination.Item>
+  </Pagination.Content>
+</Pagination>
+```
+
+## 组件剖析
+
+v3 Pagination 的结构如下：
+
+```
+Pagination (Root, nav element)
+  ├── Pagination.Summary (optional, info text)
+  └── Pagination.Content (ul container)
+      └── Pagination.Item (li wrapper, repeated)
+          ├── Pagination.Previous (with Pagination.PreviousIcon)
+          ├── Pagination.Link (page number, isActive for current)
+          ├── Pagination.Ellipsis
+          └── Pagination.Next (with Pagination.NextIcon)
+```
+
+## 总结
+
+1. **组件结构**：由单个自动生成式组件，改为需手动组合的复合组件。
+2. **页码生成**：`total` / `siblings` / `boundaries` props → 结合自定义分页逻辑手动渲染页码项。
+3. **当前页**：`page` / `initialPage` props → 在各个 `Pagination.Link` 上使用 `isActive`。
+4. **导航控件**：`showControls` prop → 直接组合 `Pagination.Previous` 与 `Pagination.Next`。
+5. **省略号**：由自动生成 → 在需要处手动放置 `Pagination.Ellipsis`。
+6. **事件**：单一 `onChange` → 各 `Pagination.Link` 上的独立 `onPress` 处理函数。
+7. **新能力**：`Pagination.Summary` 用于展示结果数量；可通过 `PreviousIcon` / `NextIcon` 的 children 自定义图标。
+8. **Hook 移除**：`usePagination` → 请自行实现分页逻辑。
+9. **样式 props 移除**：`variant`、`color`、`radius`、`isCompact`、`showShadow` → 请使用 Tailwind CSS。
+10. **`classNames` 移除**：请在各复合子组件上使用 `className`。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/popover.mdx b/apps/docs/content/docs/cn/react/migration/(components)/popover.mdx
new file mode 100644
index 0000000..fd2d6f9
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/popover.mdx
@@ -0,0 +1,279 @@
+---
+title: Popover
+description: Popover 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Popover 文档](/docs/react/components/popover)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Popover 由独立的多个组件组成：
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Popover placement="right">
+      <PopoverTrigger>
+        <Button>Open</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div>Content</div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+在 v3 中，Popover 改为复合组件：
+
+```tsx
+import { Popover, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <Popover.Heading>Title</Popover.Heading>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 独立的多个组件（`Popover`、`PopoverTrigger`、`PopoverContent`）  
+**v3：** 复合组件（`Popover`、`Popover.Trigger`、`Popover.Content`、`Popover.Dialog`、`Popover.Heading`、`Popover.Arrow`）
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `placement` | `placement`（在 Content 上） | 移至 `Popover.Content` |
+| `offset` | `offset`（在 Content 上） | 移至 `Popover.Content` |
+| `shouldFlip` | `shouldFlip`（在 Content 上） | 移至 `Popover.Content` |
+| `isOpen` / `defaultOpen` / `onOpenChange` | 同名（在根上） | 受控状态仍保留在根 `Popover` 上 |
+| `showArrow` | — | 改用 `Popover.Arrow` 子组件 |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `radius` | — | 已移除（请改用 Tailwind CSS） |
+| `shadow` | — | 已移除（请改用 Tailwind CSS） |
+| `backdrop` | — | 已移除 |
+| `motionProps` | — | 已移除（动画机制已不同） |
+| `classNames` | — | 改在各子组件上使用 `className` |
+| `onClose` | — | 改用 `onOpenChange((open) => { if (!open) { ... } })` |
+
+## 迁移示例
+
+### 内容配置
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With arrow */}
+    <Popover showArrow>
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    
+    {/* With placement */}
+    <Popover placement="top">
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    
+    {/* With offset */}
+    <Popover offset={10}>
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With arrow - use component */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <Popover.Arrow />
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    
+    {/* With placement - moved to Content */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content placement="top">
+        <Popover.Dialog>
+          <Popover.Arrow />
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    
+    {/* With offset - moved to Content */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content offset={10}>
+        <Popover.Dialog>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    ```
+  </Tab>
+</Tabs>
+
+### 带标题
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <PopoverContent>
+      <div className="px-1 py-2">
+        <div className="text-small font-bold">Title</div>
+        <div className="text-tiny">Content</div>
+      </div>
+    </PopoverContent>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Popover.Content>
+      <Popover.Dialog>
+        <Popover.Heading>Title</Popover.Heading>
+        <p className="text-muted mt-2 text-sm">Content</p>
+      </Popover.Dialog>
+    </Popover.Content>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Popover isOpen={isOpen} onOpenChange={setIsOpen}>
+      <PopoverTrigger>
+        <Button>Open</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div>Content</div>
+      </PopoverContent>
+    </Popover>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Popover isOpen={isOpen} onOpenChange={setIsOpen}>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义触发器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <PopoverTrigger>
+      <CustomButton>Custom</CustomButton>
+    </PopoverTrigger>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Popover.Trigger>
+      <CustomButton>Custom</CustomButton>
+    </Popover.Trigger>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 Popover 遵循以下结构：
+
+```
+Popover (Root)
+  ├── Popover.Trigger (optional, or use Button directly)
+  └── Popover.Content
+      └── Popover.Dialog
+          ├── Popover.Arrow (optional)
+          ├── Popover.Heading (optional)
+          └── Content
+```
+
+## v3 中的新功能
+
+### Popover.Arrow 组件
+
+在 v2 中，箭头通过根 `Popover` 上的 `showArrow` 布尔 prop 控制。在 v3 中，`Popover.Arrow` 是一个放置在 `Popover.Content` 内部的专用组件，让你可以完全控制其渲染：
+
+```tsx
+<Popover>
+  <Button>Open</Button>
+  <Popover.Content>
+    <Popover.Arrow className="custom-arrow" />
+    <Popover.Dialog>
+      <div>Content</div>
+    </Popover.Dialog>
+  </Popover.Content>
+</Popover>
+```
+
+`Popover.Arrow` 也接受 `render` prop，可完全自定义箭头的渲染。
+
+### 受控打开状态
+
+受控的打开状态仍保留在根 `Popover` 组件上，prop 名称与 v2 一致：
+
+| 属性 | 类型 | 默认值 | 描述 |
+| ---- | ---- | ------ | ---- |
+| `isOpen` | `boolean` | - | 控制 Popover 的可见性（受控） |
+| `defaultOpen` | `boolean` | `false` | 初始打开状态（非受控） |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时触发 |
+
+### 自定义渲染函数
+
+`Popover.Content` 与 `Popover.Arrow` 都支持 `render` prop，让你可以在高级场景下用自定义渲染函数覆盖默认 DOM 元素。
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Popover.Content`、`Popover.Dialog` 等）
+2. **触发器**：可以使用 `Popover.Trigger`，或直接将 Button 作为子节点
+3. **内容包装**：内容必须放在 `Popover.Dialog` 中
+4. **箭头**：移除 `showArrow` prop——改用 `Popover.Arrow` 子组件
+5. **标题**：改用 `Popover.Heading` 组件
+6. **prop 移动位置**：`placement`、`offset`、`shouldFlip` 移到 `Popover.Content` 上
+7. **移除样式 prop**：`size`、`color`、`radius`、`shadow` —— 请改用 Tailwind CSS
+8. **移除 backdrop**：`backdrop` prop 已移除
+9. **移除 motion**：`motionProps` 已移除，动画机制已不同
+10. **移除 classNames**：改在各子组件上使用 `className` prop
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/progress.mdx b/apps/docs/content/docs/cn/react/migration/(components)/progress.mdx
new file mode 100644
index 0000000..f3bc8b6
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/progress.mdx
@@ -0,0 +1,223 @@
+---
+title: Progress
+description: Progress 从 HeroUI v2 到 v3（现在称为 ProgressBar）的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 ProgressBar 文档](/docs/react/components/progress-bar)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+<Callout type="warning">
+  正在寻找 CircularProgress 的迁移说明？请参阅 [CircularProgress 迁移指南](/docs/react/migration/circular-progress)。
+</Callout>
+
+## 组件重命名
+
+`Progress` 在 v3 中已重命名为 `ProgressBar`。
+
+## 结构变化
+
+在 v2 中，`Progress` 是单个组件，通过 prop 进行配置：
+
+```tsx
+import { Progress } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Progress label="Loading..." value={60} />
+  );
+}
+```
+
+在 v3 中，`ProgressBar` 改为复合组件模式：
+
+```tsx
+import { ProgressBar, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ProgressBar value={60}>
+      <Label>Loading...</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `Progress` 组件，所有部分都在内部渲染  
+**v3：** 复合组件：`ProgressBar`、`ProgressBar.Output`、`ProgressBar.Track`、`ProgressBar.Fill`，并配合外部的 `Label`
+
+### 2. 颜色
+
+**v2：** `default`、`primary`、`secondary`、`success`、`warning`、`danger`  
+**v3：** `default`、`accent`、`success`、`warning`、`danger`
+
+### 3. Prop 变更
+
+| v2 prop | v3 对应项 | 说明 |
+| ------- | --------- | ---- |
+| `value` | `value` | 相同 |
+| `minValue` | `minValue` | 相同 |
+| `maxValue` | `maxValue` | 相同 |
+| `isIndeterminate` | `isIndeterminate` | 相同 |
+| `formatOptions` | `formatOptions` | 相同 |
+| `size` | `size` | 相同（`sm`、`md`、`lg`） |
+| `color` | `color` | `primary` → `accent`，`secondary` 已移除 |
+| `label` | - | 改用 `Label` 组件 |
+| `valueLabel` | `valueLabel` | 相同 |
+| `showValueLabel` | - | 通过包含或省略 `ProgressBar.Output` 控制 |
+| `radius` | - | 已移除（请改用 Tailwind CSS） |
+| `isStriped` | - | 已移除（请在 `ProgressBar.Fill` 上使用 Tailwind CSS） |
+| `isDisabled` | - | 已移除 |
+| `disableAnimation` | - | 已移除 |
+| `classNames` | - | 改在各复合子组件上使用 `className` |
+
+## 迁移示例
+
+### 基本进度条
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Progress } from "@heroui/react";
+
+    <Progress label="Loading..." value={60} color="primary" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressBar, Label } from "@heroui/react";
+
+    <ProgressBar value={60} color="accent">
+      <Label>Loading...</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### 不确定状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress isIndeterminate aria-label="Loading..." size="sm" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar isIndeterminate aria-label="Loading..." size="sm">
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### 无标签（无障碍）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress aria-label="Loading..." value={70} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar aria-label="Loading..." value={70}>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义格式
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress
+      label="Budget"
+      formatOptions={{ style: "currency", currency: "USD" }}
+      maxValue={10000}
+      value={4000}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar
+      formatOptions={{ style: "currency", currency: "USD" }}
+      maxValue={10000}
+      value={4000}
+    >
+      <Label>Budget</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变更
+
+### v2：`classNames` prop
+
+```tsx
+<Progress
+  classNames={{
+    base: "custom-base",
+    track: "custom-track",
+    indicator: "custom-fill",
+    label: "custom-label",
+    value: "custom-value",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<ProgressBar className="custom-base" value={60}>
+  <Label className="custom-label">Loading</Label>
+  <ProgressBar.Output className="custom-value" />
+  <ProgressBar.Track className="custom-track">
+    <ProgressBar.Fill className="custom-fill" />
+  </ProgressBar.Track>
+</ProgressBar>
+```
+
+## 组件结构
+
+```
+ProgressBar (Root)
+  ├── Label (optional)
+  ├── ProgressBar.Output (optional, formatted value display)
+  └── ProgressBar.Track
+      └── ProgressBar.Fill
+```
+
+## 总结
+
+1. **重命名**：`Progress` → `ProgressBar`
+2. **组件结构**：单组件 → 复合组件（`ProgressBar.Output`、`ProgressBar.Track`、`ProgressBar.Fill`）
+3. **标签**：`label` prop → `Label` 组件
+4. **数值显示**：`showValueLabel` prop → 通过包含或省略 `ProgressBar.Output` 控制
+5. **颜色变化**：`primary` → `accent`，`secondary` 已移除
+6. **移除的 prop**：`radius`、`isStriped`、`isDisabled`、`disableAnimation` → 请改用 Tailwind CSS
+7. **移除 classNames**：改在各复合子组件上使用 `className`
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/radio-group.mdx b/apps/docs/content/docs/cn/react/migration/(components)/radio-group.mdx
new file mode 100644
index 0000000..d7c3494
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/radio-group.mdx
@@ -0,0 +1,270 @@
+---
+title: RadioGroup
+description: RadioGroup 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 RadioGroup 文档](/docs/react/components/radio-group)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`RadioGroup` 通过 `label` prop 设置标题：
+
+```tsx
+import { RadioGroup, Radio } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo" description="Capital of Japan">Tokyo</Radio>
+      <Radio value="paris">Paris</Radio>
+    </RadioGroup>
+  );
+}
+```
+
+在 v3 中，`RadioGroup` 改用 `Label` 组件，并配合 Radio 的复合结构：
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup name="city">
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+        <Description>Capital of Japan</Description>
+      </Radio>
+      <Radio value="paris">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Paris
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+  );
+}
+```
+
+## 主要变化
+
+### 1. label prop → Label 组件
+
+**v2：** 在 `RadioGroup` 上使用 `label` prop  
+**v3：** 改用 `Label` 组件作为 `RadioGroup` 的子节点
+
+### 2. Radio 结构
+
+**v2：** 简单的 Radio 组件，子节点直接作为标签  
+**v3：** 复合 Radio 组件，由 `Radio.Content`、`Radio.Control` 与 `Radio.Indicator` 组成
+
+### 3. 描述处理
+
+**v2：** 在单个 `Radio` 组件上使用 `description` prop  
+**v3：** 将 `Description` 组件作为 `Radio.Content` 的兄弟节点使用
+
+### 4. 事件处理函数
+
+**v2：** 使用 `onValueChange` prop  
+**v3：** 改用 `onChange` prop（来自 React Aria Components）
+
+### 5. name prop
+
+**v3：** 集成到表单时需要 `name` prop
+
+### 6. 变体支持
+
+**v3：** 新增 `variant` prop：`"primary"`（默认）或 `"secondary"`，后者用于较弱的视觉强调，适合 Surface 组件场景
+
+### 7. 只读支持
+
+**v3：** 新增 `isReadOnly` prop，可阻止值变化但仍保持分组可聚焦
+
+## 迁移示例
+
+### 带描述的 RadioGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RadioGroup label="Select plan">
+      <Radio value="basic" description="Basic features">Basic</Radio>
+      <Radio value="pro" description="All features">Pro</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+    <RadioGroup name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+        <Description>Basic features</Description>
+      </Radio>
+      <Radio value="pro">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Pro
+        </Radio.Content>
+        <Description>All features</Description>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have variant support */}
+    <RadioGroup label="Select plan">
+      <Radio value="basic">Basic</Radio>
+      <Radio value="pro">Pro</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RadioGroup, Radio, Label } from "@heroui/react";
+
+    {/* Primary variant (default) */}
+    <RadioGroup variant="primary" name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+
+    {/* Secondary variant - lower emphasis, suitable for Surface components */}
+    <RadioGroup variant="secondary" name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 只读
+
+```tsx
+import { RadioGroup, Radio, Label } from "@heroui/react";
+
+{/* Prevents value changes while keeping the group focusable */}
+<RadioGroup isReadOnly defaultValue="basic" name="plan">
+  <Label>Select plan</Label>
+  <Radio value="basic">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Basic
+    </Radio.Content>
+  </Radio>
+  <Radio value="pro">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Pro
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+### 受控 RadioGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { RadioGroup, Radio } from "@heroui/react";
+
+    const [value, setValue] = useState("london");
+
+    <RadioGroup value={value} onValueChange={setValue} label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { RadioGroup, Radio, Label } from "@heroui/react";
+
+    const [value, setValue] = useState("london");
+
+    <RadioGroup name="city" value={value} onChange={setValue}>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+- 用 `Label` 子组件取代 `label` prop
+- 将 Radio 子项更新为复合组件结构
+- 将 `Description` 组件作为 `Radio.Content` 的兄弟节点，取代 Radio 的 `description` prop
+- 将 `onValueChange` 改为 `onChange`
+- 添加 `name` prop 以便集成到表单中
+- 新增 `variant` prop：`"primary"`（默认）或 `"secondary"`，用于较弱的视觉强调
+- 新增 `isReadOnly` prop：阻止值变化但保持分组可聚焦
+- 通过 React Aria Components 提供更好的无障碍体验
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/radio.mdx b/apps/docs/content/docs/cn/react/migration/(components)/radio.mdx
new file mode 100644
index 0000000..311da56
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/radio.mdx
@@ -0,0 +1,305 @@
+---
+title: Radio
+description: Radio 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Radio 文档](/docs/react/components/radio-group)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Radio 使用较为扁平的结构，通过 prop 配置：
+
+```tsx
+import { RadioGroup, Radio } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo" description="Capital of Japan">Tokyo</Radio>
+    </RadioGroup>
+  );
+}
+```
+
+在 v3 中，Radio 需要使用复合组件：
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+        <Description>Capital of Japan</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
+```
+
+## 关键变化
+
+### 1. 组件结构
+
+**v2：** 简单的 Radio，`children` 作为标签文案  
+**v3：** 复合组件：`Radio.Content`、`Radio.Control`、`Radio.Indicator`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| --- | --- | --- |
+| `onValueChange` | `onChange` | 事件处理函数已重命名 |
+| `label`（在 RadioGroup 上） | — | 使用 `Label` 组件 |
+| `description`（在 Radio 上） | — | 将 `Description` 组件作为 `Radio.Content` 的兄弟节点使用 |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `classNames` | — | 在各子组件上使用 `className` prop |
+| `disableAnimation` | — | 已移除（动画机制已不同） |
+| — | `variant` | `RadioGroup` 上的新 prop：`"primary"`（默认）或 `"secondary"`，用于较低强调度的样式 |
+| — | `isReadOnly` | `RadioGroup` 上的新 prop：在保持组合可聚焦的同时阻止更改选中值 |
+
+## 迁移示例
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <RadioGroup label="Select city">
+      <Radio value="london" description="Capital of England">
+        London
+      </Radio>
+    </RadioGroup>
+    
+    {/* With validation */}
+    <RadioGroup
+      isInvalid
+      errorMessage="Please select an option"
+      label="Select city"
+    >
+      <Radio value="london">London</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Description, FieldError } from "@heroui/react";
+
+    {/* 带描述 */}
+    <RadioGroup>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+        <Description>Capital of England</Description>
+      </Radio>
+    </RadioGroup>
+    
+    {/* 带校验 */}
+    <RadioGroup isInvalid>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <FieldError>Please select an option</FieldError>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("london");
+
+    <RadioGroup
+      value={selected}
+      onValueChange={setSelected}
+    >
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("london");
+
+    <RadioGroup value={selected} onChange={setSelected}>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 水平方向
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RadioGroup orientation="horizontal" label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RadioGroup orientation="horizontal">
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+v3 在 `RadioGroup` 上新增 `variant` prop，可选 `"primary"`（默认）与 `"secondary"`：
+
+```tsx
+{/* Primary variant (default) */}
+<RadioGroup variant="primary">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+
+{/* Secondary：视觉强调更低，适合配合 Surface 组件 */}
+<RadioGroup variant="secondary">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+### 只读
+
+v3 支持在 `RadioGroup` 上使用 `isReadOnly`：在保持组合可聚焦的同时阻止更改选中值。
+
+```tsx
+<RadioGroup isReadOnly defaultValue="london">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+  <Radio value="tokyo">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Tokyo
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+## 组件组成
+
+v3 的 Radio 结构如下：
+
+```
+RadioGroup (Root)
+  ├── Label (optional)
+  ├── Radio
+  │   ├── Radio.Content (the clickable label)
+  │   │   ├── Radio.Control
+  │   │   │   └── Radio.Indicator
+  │   │   └── Label
+  │   └── Description (optional, sibling)
+  └── FieldError (optional)
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Radio.Content`、`Radio.Control`、`Radio.Indicator`）。
+2. **标签**：已移除 `label` prop，请使用 `Label` 组件。
+3. **描述**：已移除 `description` prop，请将 `Description` 组件作为 `Radio.Content` 的兄弟节点使用。
+4. **事件处理函数**：`onValueChange` → `onChange`。
+5. **样式相关 prop 已移除**：`size`、`color` 等请改用 Tailwind CSS。
+6. **`classNames` 已移除**：在各子组件上使用 `className` prop。
+7. **错误信息**：使用 `FieldError` 组件，而不是 `errorMessage` prop。
+8. **新增 `variant` prop**：`RadioGroup` 支持 `"primary"`（默认）与 `"secondary"`，用于较低强调度的样式。
+9. **新增 `isReadOnly` prop**：`RadioGroup` 支持 `isReadOnly`，在保持组合可聚焦的同时阻止更改选中值。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/range-calendar.mdx b/apps/docs/content/docs/cn/react/migration/(components)/range-calendar.mdx
new file mode 100644
index 0000000..1db7b9a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/range-calendar.mdx
@@ -0,0 +1,446 @@
+---
+title: RangeCalendar
+description: RangeCalendar 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 RangeCalendar 文档](/docs/react/components/range-calendar)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`RangeCalendar` 是一个完全通过 props 配置的单一组件：
+
+```tsx
+import { RangeCalendar } from "@heroui/react";
+import { today, getLocalTimeZone } from "@internationalized/date";
+
+export default function App() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    />
+  );
+}
+```
+
+在 v3 中，RangeCalendar 改用带显式子组件的复合组件模式：
+
+```tsx
+import { RangeCalendar } from "@heroui/react";
+import { today, getLocalTimeZone } from "@internationalized/date";
+
+export default function App() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 单一 `RangeCalendar` 组件，所有布局都在内部处理  
+**v3：** 复合组件：`RangeCalendar.Header`、`RangeCalendar.Heading`、`RangeCalendar.NavButton`、`RangeCalendar.Grid`、`RangeCalendar.GridHeader`、`RangeCalendar.GridBody`、`RangeCalendar.HeaderCell`、`RangeCalendar.Cell`、`RangeCalendar.CellIndicator`
+
+### 2. 年份选择器
+
+**v2：** 通过 `showMonthAndYearPickers` prop 提供内置月份 / 年份选择器  
+**v3：** 使用专用复合组件：`RangeCalendar.YearPickerTrigger`、`RangeCalendar.YearPickerGrid`、`RangeCalendar.YearPickerGridBody`、`RangeCalendar.YearPickerCell`
+
+### 3. Prop 变更
+
+| v2 prop | v3 等效项 | 说明 |
+| ------- | ----------- | ---- |
+| `value` | `value` | 保持一致 |
+| `defaultValue` | `defaultValue` | 保持一致 |
+| `onChange` | `onChange` | 保持一致 |
+| `focusedValue` | `focusedValue` | 保持一致 |
+| `onFocusChange` | `onFocusChange` | 保持一致 |
+| `minValue` | `minValue` | 保持一致 |
+| `maxValue` | `maxValue` | 保持一致 |
+| `isDateUnavailable` | `isDateUnavailable` | 保持一致 |
+| `allowsNonContiguousRanges` | `allowsNonContiguousRanges` | 保持一致 |
+| `isDisabled` | `isDisabled` | 保持一致 |
+| `isReadOnly` | `isReadOnly` | 保持一致 |
+| `isInvalid` | `isInvalid` | 保持一致 |
+| `pageBehavior` | `pageBehavior` | 保持一致 |
+| `visibleMonths` | `visibleDuration` | 改为 `{months: number}` 对象 |
+| `showMonthAndYearPickers` | - | 使用 `RangeCalendar.YearPickerTrigger` 和 `RangeCalendar.YearPickerGrid` |
+| `onHeaderExpandedChange` | `onYearPickerOpenChange` | 已重命名 |
+| `color` | - | 已移除（请改用 Tailwind CSS） |
+| `calendarWidth` | - | 已移除（请改用 `className` 或 Tailwind CSS） |
+| `weekdayStyle` | - | 已移除 |
+| `firstDayOfWeek` | - | 改用 `I18nProvider` 的 locale |
+| `topContent` | - | 将自定义内容作为 `RangeCalendar` children 放在网格之前 |
+| `bottomContent` | - | 将自定义内容作为 `RangeCalendar` children 放在网格之后 |
+| `errorMessage` | - | 已移除（请在外部处理校验） |
+| `showHelper` | - | 已移除 |
+| `disableAnimation` | - | 已移除 |
+| `classNames` | - | 在各个复合组件上使用 `className` |
+
+## 迁移示例
+
+### 基本范围选择
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { RangeCalendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RangeCalendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-07"),
+    });
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-07"),
+    });
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      value={value}
+      onChange={setValue}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 月份和年份选择器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates">
+      <RangeCalendar.Header>
+        <RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.YearPickerTriggerHeading />
+          <RangeCalendar.YearPickerTriggerIndicator />
+        </RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <RangeCalendar.YearPickerGrid>
+        <RangeCalendar.YearPickerGridBody>
+          {(year) => <RangeCalendar.YearPickerCell date={year} />}
+        </RangeCalendar.YearPickerGridBody>
+      </RangeCalendar.YearPickerGrid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 多个月份
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      visibleMonths={2}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates" visibleDuration={{months: 2}}>
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <div className="flex gap-4">
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+        <RangeCalendar.Grid offset={{months: 1}}>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </div>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 带非连续范围的不可用日期
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+      allowsNonContiguousRanges
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+      allowsNonContiguousRanges
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### 顶部与底部内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      topContent={<p>Select your travel dates</p>}
+      bottomContent={
+        <button onClick={handleReset}>Reset</button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates">
+      <p>Select your travel dates</p>
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <button onClick={handleReset}>Reset</button>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式变化
+
+### v2：`classNames` prop
+
+```tsx
+<RangeCalendar
+  classNames={{
+    base: "custom-base",
+    prevButton: "custom-prev",
+    nextButton: "custom-next",
+    title: "custom-title",
+    cell: "custom-cell",
+    cellButton: "custom-cell-button",
+  }}
+/>
+```
+
+### v3：直接使用 `className` prop
+
+```tsx
+<RangeCalendar className="custom-base">
+  <RangeCalendar.Header>
+    <RangeCalendar.Heading className="custom-title" />
+    <RangeCalendar.NavButton slot="previous" className="custom-prev" />
+    <RangeCalendar.NavButton slot="next" className="custom-next" />
+  </RangeCalendar.Header>
+  <RangeCalendar.Grid>
+    <RangeCalendar.GridHeader>
+      {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+    </RangeCalendar.GridHeader>
+    <RangeCalendar.GridBody>
+      {(date) => <RangeCalendar.Cell date={date} className="custom-cell" />}
+    </RangeCalendar.GridBody>
+  </RangeCalendar.Grid>
+</RangeCalendar>
+```
+
+## 组件结构
+
+v3 RangeCalendar 遵循以下结构：
+
+```
+RangeCalendar (Root)
+  ├── [Custom top content]
+  ├── RangeCalendar.Header
+  │   ├── RangeCalendar.Heading (or RangeCalendar.YearPickerTrigger)
+  │   ├── RangeCalendar.NavButton slot="previous"
+  │   └── RangeCalendar.NavButton slot="next"
+  ├── RangeCalendar.Grid (one per visible month)
+  │   ├── RangeCalendar.GridHeader
+  │   │   └── RangeCalendar.HeaderCell (render prop)
+  │   └── RangeCalendar.GridBody
+  │       └── RangeCalendar.Cell (render prop)
+  │           └── RangeCalendar.CellIndicator (optional)
+  ├── RangeCalendar.YearPickerGrid (optional)
+  │   └── RangeCalendar.YearPickerGridBody
+  │       └── RangeCalendar.YearPickerCell
+  └── [Custom bottom content]
+```
+
+## 总结
+
+1. **组件结构**：单一组件 → 带显式布局控制的复合组件
+2. **年份选择器**：`showMonthAndYearPickers` prop → 专用的 `RangeCalendar.YearPickerTrigger` 和 `RangeCalendar.YearPickerGrid` 组件
+3. **多个月份**：`visibleMonths={n}` → `visibleDuration={{months: n}}`，并使用多个带 `offset` 的 `RangeCalendar.Grid` 组件
+4. **color 已移除**：请改用 Tailwind CSS 类
+5. **顶部 / 底部内容**：prop 已移除 → 直接将内容作为 children 放在 `RangeCalendar` 内
+6. **单元格自定义**：新增 `RangeCalendar.CellIndicator`，且 `RangeCalendar.Cell` 支持渲染 prop
+7. **样式**：`classNames` prop → 各个复合组件上的 `className`
+8. **已移除 prop**：`calendarWidth`、`weekdayStyle`、`showHelper`、`errorMessage`、`disableAnimation` —— 请使用 Tailwind CSS 或在外部处理
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/scroll-shadow.mdx b/apps/docs/content/docs/cn/react/migration/(components)/scroll-shadow.mdx
new file mode 100644
index 0000000..5d32210
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/scroll-shadow.mdx
@@ -0,0 +1,148 @@
+---
+title: ScrollShadow
+description: ScrollShadow 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 ScrollShadow 文档](/docs/react/components/scroll-shadow)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`ScrollShadow` 是一个包装组件：
+
+```tsx
+import { ScrollShadow } from "@heroui/scroll-shadow";
+
+export default function App() {
+  return (
+    <ScrollShadow>
+      {/* scrollable content */}
+    </ScrollShadow>
+  );
+}
+```
+
+在 v3 中，`ScrollShadow` 的基本结构相同，但提供了更多配置项：
+
+```tsx
+import { ScrollShadow } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ScrollShadow>
+      {/* scrollable content */}
+    </ScrollShadow>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 导入路径
+
+**v2：** 从 `@heroui/scroll-shadow` 包导入  
+**v3：** 从统一封装的 `@heroui/react` 导入
+
+### 2. 可见性控制
+
+**v2：** `visibility` prop 控制阴影位置  
+**v3：** `visibility` prop 选项更丰富，并新增 `onVisibilityChange` 回调
+
+### 3. 阴影尺寸控制
+
+**v2：** 阴影尺寸固定，定制能力有限  
+**v3：** `size` prop 允许自定义阴影尺寸（单位：像素）
+
+### 4. 增强的 prop
+
+**v3：** 新增的 prop：
+- `size` —— 阴影尺寸，单位为像素（默认值：40）
+- `offset` —— 触发阴影显示前的滚动偏移（默认值：0）
+- `isEnabled` —— 启用/禁用阴影检测（默认值：true）
+- `hideScrollBar` —— 隐藏滚动条但保留滚动能力
+- `variant` —— 阴影效果类型（默认：`fade`）
+- `onVisibilityChange` —— 阴影可见性变化时触发的回调
+
+## 迁移示例
+
+### 自定义阴影尺寸
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow>
+      {/* Shadow size was fixed */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ScrollShadow size={80} className="max-h-[400px]">
+      {/* Large shadow */}
+    </ScrollShadow>
+    ```
+  </Tab>
+</Tabs>
+
+### 增强的可见性控制
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow visibility="bottom">
+      {/* content */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { ScrollShadow } from "@heroui/react";
+
+    function App() {
+      const [visibility, setVisibility] = useState("none");
+
+      return (
+        <>
+          <p>Shadow state: {visibility}</p>
+          <ScrollShadow
+            onVisibilityChange={setVisibility}
+            className="max-h-[400px]"
+          >
+            {/* content */}
+          </ScrollShadow>
+        </>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### 变体
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow>
+      {/* v2 used theme variants (e.g. orientation, hideScrollBar) */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ScrollShadow variant="fade" className="max-h-[400px]">
+      {/* Shadow effect controlled by variant (default: fade) */}
+    </ScrollShadow>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+- 将导入从 `@heroui/scroll-shadow` 更新为 `@heroui/react`
+- 增强的 API，提供更多配置项
+- 更好的阴影检测与可见性控制
+- 同样支持横向 / 纵向方向；统一从 `@heroui/react` 导入
+- 可自定义阴影尺寸与变体（例如 fade）
+- 性能与无障碍均有改进
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/select.mdx b/apps/docs/content/docs/cn/react/migration/(components)/select.mdx
new file mode 100644
index 0000000..a3d0c73
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/select.mdx
@@ -0,0 +1,543 @@
+---
+title: Select
+description: Select 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Select 文档](/docs/react/components/select)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Select 通过 prop 构成简单结构：
+
+```tsx
+import { Select, SelectItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Select label="Select animal" placeholder="Choose one">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+  );
+}
+```
+
+在 v3 中，Select 需要使用复合组件，并通过 `ListBox` 渲染菜单项：
+
+```tsx
+import { Select, Label, ListBox } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
+```
+
+## 关键变化
+
+### 1. 组件结构
+
+**v2：** 简单的 Select，子节点为 `SelectItem`  
+**v3：** 复合组件（`Select.Trigger`、`Select.Value`、`Select.Indicator`、`Select.Popover`）与用于菜单项的 `ListBox`
+
+### 2. 菜单项组件
+
+**v2：** `SelectItem`、`SelectSection`  
+**v3：** `ListBox.Item`、`ListBox.Section`（分组标题使用 `Header`，分组之间使用 `Separator`）
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `selectedKeys` | `value` | 从 Set / 数组改为单个值或数组 |
+| `onSelectionChange` | `onChange` | 已重命名的事件处理函数 |
+| `defaultSelectedKeys` | `defaultValue` | 已重命名的 prop |
+| `label` | — | 使用 `Label` 组件 |
+| `description` | — | 使用 `Description` 组件 |
+| `errorMessage` | — | 使用 `FieldError` 组件 |
+| `variant` | `variant` | 仅保留 `primary` \| `secondary` |
+| `color` | — | 已移除（请使用 Tailwind CSS） |
+| `size` | — | 已移除（请使用 Tailwind CSS） |
+| `radius` | — | 已移除（请使用 Tailwind CSS） |
+| `classNames` | — | 在各子组件上使用 `className` prop |
+| `startContent` | — | 直接自定义 `Select.Trigger` |
+| `endContent` | — | 直接自定义 `Select.Trigger` |
+| `selectorIcon` | — | 自定义 `Select.Indicator` 的 children |
+| `isClearable` | — | 手动实现清除按钮 |
+| `renderValue` | — | 使用 `Select.Value` 的渲染 prop |
+| `labelPlacement` | — | 标签始终在外部 |
+| `isRequired` | `isRequired` | 仍然可用 |
+| `disabledKeys` | `disabledKeys` | 仍然可用 |
+| `isOpen` | `isOpen` | 新增：受控地控制 Popover 的打开状态 |
+| `defaultOpen` | `defaultOpen` | 新增：非受控的默认打开状态 |
+| `onOpenChange` | `onOpenChange` | 新增：打开状态变化时触发 |
+| `selectionMode` | `selectionMode` | 仍然可用 |
+| `disableAnimation` | — | 已移除（动画机制已不同） |
+| `popoverProps`、`listboxProps`、`scrollShadowProps` | — | 直接在 `Select.Popover`、`ListBox` 等组件上传入 prop |
+
+## 迁移示例
+
+### 选择
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleValue, setSingleValue] = useState(new Set([]));
+    <Select
+      selectedKeys={singleValue}
+      onSelectionChange={setSingleValue}
+      label="Select animal"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    
+    {/* Multiple selection */}
+    const [multiValue, setMultiValue] = useState(new Set([]));
+    <Select
+      selectionMode="multiple"
+      selectedKeys={multiValue}
+      onSelectionChange={setMultiValue}
+      label="Select animals"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+
+    {/* Single selection */}
+    const [singleValue, setSingleValue] = useState<Key | null>(null);
+    <Select value={singleValue} onChange={setSingleValue} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    
+    {/* Multiple selection */}
+    const [multiValue, setMultiValue] = useState<Key[]>([]);
+    <Select
+      selectionMode="multiple"
+      value={multiValue}
+      onChange={setMultiValue}
+      placeholder="Choose multiple"
+    >
+      <Label>Select animals</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 表单校验
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <Select
+      label="Select animal"
+      description="Choose your favorite"
+      placeholder="Choose one"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    
+    {/* With validation */}
+    <Select
+      isInvalid
+      errorMessage="Please select an option"
+      label="Select animal"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Description, FieldError } from "@heroui/react";
+
+    {/* With description */}
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Description>Choose your favorite</Description>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    
+    {/* With validation */}
+    <Select isInvalid placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+      <FieldError>Please select an option</FieldError>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 带分组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem, SelectSection } from "@heroui/react";
+
+    <Select label="Select animal">
+      <SelectSection title="Mammals">
+        <SelectItem key="cat">Cat</SelectItem>
+        <SelectItem key="dog">Dog</SelectItem>
+      </SelectSection>
+      <SelectSection title="Birds">
+        <SelectItem key="eagle">Eagle</SelectItem>
+        <SelectItem key="parrot">Parrot</SelectItem>
+      </SelectSection>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox, Header, Separator } from "@heroui/react";
+
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>Mammals</Header>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Birds</Header>
+            <ListBox.Item id="eagle" textValue="Eagle">
+              Eagle
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="parrot" textValue="Parrot">
+              Parrot
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控的打开状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 不支持受控的打开状态 */}
+    <Select label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Select isOpen={isOpen} onOpenChange={setIsOpen} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 禁用选项
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem } from "@heroui/react";
+
+    <Select label="Select animal" disabledKeys={["dog"]}>
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+      <SelectItem key="parrot">Parrot</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    <Select disabledKeys={["dog"]} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="parrot" textValue="Parrot">
+            Parrot
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 必填
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem } from "@heroui/react";
+
+    <Select isRequired label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    <Select isRequired placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义指示器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Select selectorIcon={<CustomIcon />} label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator>
+          <CustomIcon />
+        </Select.Indicator>
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件剖析
+
+v3 Select 的结构如下：
+
+```
+Select (Root)
+  ├── Label (optional)
+  ├── Select.Trigger
+  │   ├── Select.Value
+  │   └── Select.Indicator
+  ├── Description (optional)
+  ├── Select.Popover
+  │   └── ListBox
+  │       ├── ListBox.Item
+  │       │   ├── Label (optional)
+  │       │   ├── Description (optional)
+  │       │   └── ListBox.ItemIndicator
+  │       ├── ListBox.Section (optional)
+  │       │   ├── Header (section title)
+  │       │   └── ListBox.Item
+  │       └── Separator (optional, between sections)
+  └── FieldError (optional)
+```
+
+## 重要说明
+
+### 菜单项标识
+
+- **v2：** React 的 `key` 同时用于列表协调与选择时的项标识。  
+- **v3：** 在 `ListBox.Item` 上使用 `id`（状态 / 焦点）与 `textValue`（无障碍）；列表协调仍使用 React 的 `key`。
+
+### 选择值的类型
+
+- **v2：** `selectedKeys` 为 `Set<Key>` 或数组  
+- **v3：** 单选时 `value` 为 `Key | null`，多选时为 `Key[]`
+
+### 清除按钮
+
+`isClearable` prop 已移除。若要实现清除按钮：
+
+```tsx
+<Select value={value} onChange={setValue}>
+  <Select.Trigger>
+    <Select.Value />
+    {value && (
+      <button onClick={() => setValue(null)}>Clear</button>
+    )}
+    <Select.Indicator />
+  </Select.Trigger>
+  {/* ... */}
+</Select>
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Select.Trigger`、`Select.Value`、`Select.Indicator`、`Select.Popover`）。  
+2. **菜单项组件**：`SelectItem` → `ListBox.Item`，`SelectSection` → `ListBox.Section`（分组标题用 `Header`，分组之间用 `Separator`）。  
+3. **标签 / 描述 / 错误**：使用独立组件，而不是对应 prop。  
+4. **选择相关 prop**：`selectedKeys` / `onSelectionChange` → `value` / `onChange`。  
+5. **受控的打开状态**：新增 `isOpen`、`defaultOpen`、`onOpenChange` 用于控制 Popover 的打开状态。  
+6. **禁用选项**：仍支持 `disabledKeys` 以禁用指定菜单项。  
+7. **必填**：仍支持 `isRequired` 标记字段为必填。  
+8. **样式**：`variant` 仅保留 `primary` \| `secondary`；`color`、`size`、`radius` 已移除，请用 Tailwind CSS 扩展。  
+9. **classNames 已移除**：在各子组件上使用 `className` prop。  
+10. **内容类 prop 已移除**：`startContent`、`endContent` 需通过自定义触发器实现。  
+11. **清除按钮**：`isClearable` 已移除，需手动实现。  
+12. **自定义值**：用 `Select.Value` 的渲染 prop 替代 `renderValue`。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/skeleton.mdx b/apps/docs/content/docs/cn/react/migration/(components)/skeleton.mdx
new file mode 100644
index 0000000..afa0f64
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/skeleton.mdx
@@ -0,0 +1,245 @@
+---
+title: Skeleton
+description: Skeleton 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Skeleton 文档](/docs/react/components/skeleton)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Skeleton 会包裹其子节点，并根据 `isLoaded` 显示或隐藏：
+
+```tsx
+import { Skeleton } from "@heroui/react";
+
+export default function App() {
+  const isLoaded = false;
+  
+  return (
+    <Skeleton isLoaded={isLoaded}>
+      <div className="h-24 bg-secondary" />
+    </Skeleton>
+  );
+}
+```
+
+在 v3 中，Skeleton 改为独立的占位符，由你自己手动控制其可见性：
+
+```tsx
+import { Skeleton } from "@heroui/react";
+
+export default function App() {
+  const isLoaded = false;
+  
+  return (
+    <>
+      {!isLoaded ? (
+        <Skeleton className="h-24 rounded-lg" />
+      ) : (
+        <div className="h-24 bg-secondary" />
+      )}
+    </>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件行为
+
+**v2：** 包裹子节点，并根据 `isLoaded` 显示/隐藏  
+**v3：** 独立占位符——可见性由你自行控制
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `isLoaded` | — | 通过条件渲染手动控制可见性 |
+| `disableAnimation` | `animationType` | 改用 `animationType="shimmer" \| "pulse" \| "none"`（用 `"none"` 禁用动画） |
+| `classNames` | — | 直接使用 `className` prop |
+| `children` | — | Skeleton 不再包裹内容 |
+
+### 3. 新增 prop
+
+- `animationType` —— 控制动画类型：`"shimmer"`（默认）、`"pulse"` 或 `"none"`
+
+## 迁移示例
+
+### 配合加载状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Skeleton className="rounded-lg" isLoaded={isLoaded}>
+      <div className="h-24 rounded-lg bg-secondary" />
+    </Skeleton>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    {!isLoaded ? (
+      <Skeleton className="h-24 rounded-lg" />
+    ) : (
+      <div className="h-24 rounded-lg bg-secondary" />
+    )}
+    ```
+  </Tab>
+</Tabs>
+
+### 独立 Skeleton
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div className="flex items-center gap-3">
+      <Skeleton className="flex rounded-full w-12 h-12" />
+      <div className="w-full flex flex-col gap-2">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+      </div>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="flex items-center gap-3">
+      <Skeleton className="h-12 w-12 shrink-0 rounded-lg" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-3 w-full rounded" />
+        <Skeleton className="h-3 w-4/5 rounded" />
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 动画类型
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Shimmer (default) */}
+    <Skeleton>
+      <div className="h-24 bg-default-300" />
+    </Skeleton>
+
+    {/* No animation */}
+    <Skeleton disableAnimation>
+      <div className="h-24 bg-default-300" />
+    </Skeleton>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Shimmer (default) */}
+    <Skeleton animationType="shimmer" className="h-24 rounded-lg" />
+
+    {/* Pulse */}
+    <Skeleton animationType="pulse" className="h-24 rounded-lg" />
+
+    {/* No animation */}
+    <Skeleton animationType="none" className="h-24 rounded-lg" />
+    ```
+  </Tab>
+</Tabs>
+
+### 复杂示例：带内容的 Card
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Card className="w-[200px] space-y-5 p-4" radius="lg">
+      <Skeleton className="rounded-lg" isLoaded={isLoaded}>
+        <div className="h-24 rounded-lg bg-secondary" />
+      </Skeleton>
+      <div className="space-y-3">
+        <Skeleton className="w-3/5 rounded-lg" isLoaded={isLoaded}>
+          <div className="h-3 w-full rounded-lg bg-secondary" />
+        </Skeleton>
+        <Skeleton className="w-4/5 rounded-lg" isLoaded={isLoaded}>
+          <div className="h-3 w-full rounded-lg bg-secondary-300" />
+        </Skeleton>
+      </div>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Card className="w-[250px] space-y-5 rounded-lg p-4">
+      {!isLoaded ? (
+        <>
+          <Skeleton className="h-32 rounded-lg" />
+          <div className="space-y-3">
+            <Skeleton className="h-3 w-3/5 rounded-lg" />
+            <Skeleton className="h-3 w-4/5 rounded-lg" />
+          </div>
+        </>
+      ) : (
+        <>
+          <div className="h-32 rounded-lg bg-secondary" />
+          <div className="space-y-3">
+            <div className="h-3 w-3/5 rounded-lg bg-secondary" />
+            <div className="h-3 w-4/5 rounded-lg bg-secondary-300" />
+          </div>
+        </>
+      )}
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### 同步的微光效果
+
+在 v3 中，你可以创建一次性扫过所有 Skeleton 的同步微光效果。在父容器上加上 `skeleton--shimmer` 类，并将每个子 Skeleton 的 `animationType` 设为 `"none"`：
+
+```tsx
+{/* The parent container drives a single shimmer across all children */}
+<div className="skeleton--shimmer space-y-4 rounded-lg p-4">
+  <Skeleton animationType="none" className="h-32 rounded-lg" />
+  <div className="space-y-3">
+    <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" />
+    <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" />
+  </div>
+</div>
+```
+
+这种方式适用于卡片类布局——你需要的是一次统一扫过整体的微光，而不是每个 Skeleton 各自独立地播放动画。
+
+## 全局动画配置
+
+在 v3 中，你可以通过 CSS 变量在全局设置默认的动画类型：
+
+```css
+:root {
+  --skeleton-animation: pulse; /* shimmer, pulse, or none */
+}
+```
+
+各个组件上的 `animationType` prop 可以覆盖该默认值。
+
+## 总结
+
+1. **不再包裹子节点**：Skeleton 不再包裹其子节点——它本身就是一个独立的占位符
+2. **不再有 `isLoaded` prop**：通过条件渲染手动控制可见性
+3. **动画控制**：`disableAnimation` → `animationType`（`"shimmer"`、`"pulse"`、`"none"`）
+4. **样式**：`classNames` → 直接使用 `className` prop
+5. **简化的 API**：组件更简单，专注于占位符职责
+6. **同步微光**：在父容器上使用 `skeleton--shimmer` 类，并将子 Skeleton 的 `animationType` 设为 `"none"`，即可实现统一的微光扫过效果
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/slider.mdx b/apps/docs/content/docs/cn/react/migration/(components)/slider.mdx
new file mode 100644
index 0000000..0c870ed
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/slider.mdx
@@ -0,0 +1,253 @@
+---
+title: Slider
+description: Slider 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Slider 文档](/docs/react/components/slider)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Slider 是结构简单、通过 prop 配置的组件：
+
+```tsx
+import { Slider } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Slider
+      label="Volume"
+      defaultValue={30}
+      size="md"
+      color="primary"
+    />
+  );
+}
+```
+
+在 v3 中，Slider 改为复合组件：
+
+```tsx
+import { Slider, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Slider defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 通过 prop 配置的简单 Slider  
+**v3：** 复合组件：`Slider.Output`、`Slider.Track`、`Slider.Fill`、`Slider.Thumb`
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `label` | — | 改用 `Label` 组件 |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `radius` | — | 已移除（请改用 Tailwind CSS） |
+| `classNames` | — | 改在各子组件上使用 `className` prop |
+| `showSteps` | — | 暂不支持 |
+| `showTooltip` | — | 暂不支持 |
+| `marks` | — | 暂不支持（请参阅 `Slider.Marks`） |
+| `startContent` | — | 直接在 Track 包装层中自定义 |
+| `endContent` | — | 直接在 Track 包装层中自定义 |
+| `hideValue` | — | 省略 `Slider.Output` |
+| `hideThumb` | — | 省略 `Slider.Thumb` |
+| `showOutline` | — | 改用 Tailwind CSS |
+| `renderThumb` | — | 使用 `Slider.Thumb` 的 render prop |
+| `renderLabel` | — | 改用 `Label` 组件 |
+| `renderValue` | — | 使用 `Slider.Output` 的 render prop |
+| `getValue` | — | 使用 `Slider.Output` 的 render prop |
+| `getTooltipValue` | — | 使用 `Slider.Output` 的 render prop |
+| `fillOffset` | — | 暂不支持 |
+| `disableThumbScale` | — | 改用 Tailwind CSS |
+| `disableAnimation` | — | 已移除 |
+| `onChangeEnd` | `Slider` | 仍支持——当用户完成拖动 thumb 时触发 |
+
+## 迁移示例
+
+### 受控 Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState(25);
+
+    <Slider
+      value={value}
+      onChange={setValue}
+      label="Volume"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState(25);
+
+    <Slider value={value} onChange={setValue}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### 区间 Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      defaultValue={[100, 500]}
+      formatOptions={{style: "currency", currency: "USD"}}
+      label="Price Range"
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider
+      defaultValue={[100, 500]}
+      formatOptions={{style: "currency", currency: "USD"}}
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    >
+      <Label>Price Range</Label>
+      <Slider.Output />
+      <Slider.Track>
+        {({state}) => (
+          <>
+            <Slider.Fill />
+            {state.values.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### 垂直 Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      defaultValue={30}
+      orientation="vertical"
+      label="Volume"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider defaultValue={30} orientation="vertical">
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义数值显示
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      renderValue={(props) => (
+        <output {...props}>Custom: {value}</output>
+      )}
+      label="Volume"
+      defaultValue={30}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output>
+        {({state}) => `Custom: ${state.values[0]}`}
+      </Slider.Output>
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 Slider 遵循以下结构：
+
+```
+Slider (Root)
+  ├── Label (optional)
+  ├── Slider.Output (optional)
+  └── Slider.Track
+      ├── Slider.Fill
+      └── Slider.Thumb (or multiple for range)
+```
+
+对于区间 Slider，请使用 `Slider.Track` 的 render prop：
+
+```tsx
+<Slider.Track>
+  {({state}) => (
+    <>
+      <Slider.Fill />
+      {state.values.map((_, i) => (
+        <Slider.Thumb key={i} index={i} />
+      ))}
+    </>
+  )}
+</Slider.Track>
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Slider.Output`、`Slider.Track`、`Slider.Fill`、`Slider.Thumb`）
+2. **标签处理**：移除 `label` prop——改用 `Label` 组件
+3. **移除样式 prop**：`size`、`color`、`radius` —— 改用 Tailwind CSS
+4. **移除 classNames**：改在各子组件上使用 `className` prop
+5. **移除功能性 prop**：`showSteps`、`showTooltip`、`marks`、`startContent`、`endContent` —— 暂不支持，或自行手动定制
+6. **移除 render prop**：`renderThumb`、`renderLabel`、`renderValue` —— 改用各组件自身的 render prop
+7. **移除可见性 prop**：`hideValue`、`hideThumb` —— 通过省略对应子组件实现
+8. **区间 Slider**：必须在 `Slider.Track` 的 render prop 中遍历多个 thumb
+9. **onChangeEnd**：在 `Slider` 上仍受支持——当用户结束拖动 thumb 时触发
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/snippet.mdx b/apps/docs/content/docs/cn/react/migration/(components)/snippet.mdx
new file mode 100644
index 0000000..388f163
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/snippet.mdx
@@ -0,0 +1,424 @@
+---
+title: Snippet
+description: Snippet 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  Snippet 组件在 HeroUI v3 中已**移除**。请使用原生 HTML 元素配合 Tailwind CSS，并通过 Clipboard API 自行实现复制能力。
+</Callout>
+
+## 主要变化
+
+### 1. 组件移除
+
+**v2：** 来自 `@heroui/react` 的 `<Snippet>` 组件  
+**v3：** 原生 HTML 元素（`<pre>`、`<code>`）+ 手动实现复制逻辑
+
+### 2. 功能对照
+
+v2 的 Snippet 具备以下能力，需要在 v3 中分别替代：
+
+| v2 功能 | v3 替代 | 说明 |
+| ------- | ------- | ---- |
+| 复制按钮 | Button + Clipboard API | 使用 `navigator.clipboard.writeText()` |
+| 复制提示 | Tooltip 组件 | 使用 v3 的 Tooltip |
+| 符号前缀 | 手动渲染 | 将符号作为文本内容输出 |
+| 多行支持 | 数组映射 | 对字符串数组做 `map` |
+| 变体（`flat`、`solid`、`bordered`、`shadow`） | Tailwind 类 | 使用背景 / 边框等工具类 |
+| 颜色（`default`、`primary` 等） | Tailwind 类 | 使用颜色相关工具类 |
+| 尺寸（`sm`、`md`、`lg`） | Tailwind 字号 | 使用 `text-sm`、`text-base`、`text-lg` |
+| 圆角 | Tailwind 圆角 | 使用 `rounded-*` 类 |
+
+## 结构变化
+
+在 v2 中，`Snippet` 是带内置复制能力的包装组件：
+
+```tsx
+import { Snippet } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Snippet symbol="$">
+      npm install @heroui/react
+    </Snippet>
+  );
+}
+```
+
+在 v3 中，请使用原生 HTML 元素并手动实现复制：
+
+```tsx
+import { Button, Tooltip } from "@heroui/react";
+import { useState } from "react";
+
+export default function App() {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText("npm install @heroui/react");
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div className="flex items-center gap-2 rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        <span className="text-default-500">$ </span>
+        npm install @heroui/react
+      </pre>
+      <Tooltip>
+        <Button
+          isIconOnly
+          aria-label="Copy"
+          size="sm"
+          variant="ghost"
+          onPress={handleCopy}
+        >
+          {copied ? "✓" : "📋"}
+        </Button>
+        <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
+```
+
+## 迁移示例
+
+### 多行 Snippet
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Snippet symbol="$">
+      {[
+        "npm install @heroui/react",
+        "yarn add @heroui/react",
+        "pnpm add @heroui/react"
+      ]}
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, Tooltip } from "@heroui/react";
+    import { useState } from "react";
+
+    function MultiLineSnippet() {
+      const [copied, setCopied] = useState(false);
+      const lines = [
+        "npm install @heroui/react",
+        "yarn add @heroui/react",
+        "pnpm add @heroui/react"
+      ];
+      const codeString = lines.join("\n");
+
+      const handleCopy = async () => {
+        await navigator.clipboard.writeText(codeString);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      };
+
+      return (
+        <div className="flex items-start gap-2 rounded-lg bg-default-100 p-3">
+          <div className="flex-1 space-y-1">
+            {lines.map((line, index) => (
+              <pre key={index} className="text-sm font-mono">
+                <span className="text-default-500">$ </span>
+                {line}
+              </pre>
+            ))}
+          </div>
+          <Tooltip>
+            <Button
+              isIconOnly
+              aria-label="Copy"
+              size="sm"
+              variant="ghost"
+              onPress={handleCopy}
+            >
+              {copied ? "✓" : "📋"}
+            </Button>
+            <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+          </Tooltip>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### 样式选项
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With variants */}
+    <Snippet variant="bordered" color="primary">
+      npm install @heroui/react
+    </Snippet>
+    
+    {/* Without symbol */}
+    <Snippet hideSymbol>
+      npm install @heroui/react
+    </Snippet>
+    
+    {/* Without copy button */}
+    <Snippet hideCopyButton>
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With variants */}
+    <div className="flex items-center gap-2 rounded-lg border border-accent bg-transparent px-3 py-1.5">
+      <pre className="text-sm font-mono text-accent">
+        <span className="text-accent/60">$ </span>
+        npm install @heroui/react
+      </pre>
+      {/* Copy button */}
+    </div>
+    
+    {/* Without symbol */}
+    <div className="flex items-center gap-2 rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        npm install @heroui/react
+      </pre>
+      {/* Copy button */}
+    </div>
+    
+    {/* Without copy button */}
+    <div className="rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        <span className="text-default-500">$ </span>
+        npm install @heroui/react
+      </pre>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## 创建可复用的 Snippet 组件（推荐）
+
+Snippet 类需求很常见，下面是一个完整的可复用组件示例：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Snippet } from "@heroui/react";
+
+    <Snippet
+      symbol="$"
+      variant="bordered"
+      color="primary"
+      size="md"
+    >
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, Tooltip } from "@heroui/react";
+    import { useState, ReactNode } from "react";
+    import { cn } from "@/lib/utils"; // or your cn utility
+
+    interface SnippetProps {
+      children: string | string[];
+      symbol?: string | ReactNode;
+      variant?: "flat" | "solid" | "bordered" | "shadow";
+      color?: "default" | "primary" | "secondary" | "success" | "warning" | "danger";
+      size?: "sm" | "md" | "lg";
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+      hideSymbol?: boolean;
+      hideCopyButton?: boolean;
+      disableCopy?: boolean;
+      disableTooltip?: boolean;
+      className?: string;
+      codeString?: string;
+      onCopy?: (value: string) => void;
+    }
+
+    const variantClasses = {
+      flat: "bg-default-100",
+      solid: "bg-default-200",
+      bordered: "border border-default-200 bg-transparent",
+      shadow: "bg-default-100 shadow-sm",
+    };
+
+    const colorClasses = {
+      default: "text-default-foreground",
+      primary: "text-accent",
+      secondary: "text-default-600",
+      success: "text-success",
+      warning: "text-warning",
+      danger: "text-danger",
+    };
+
+    const sizeClasses = {
+      sm: "px-1.5 py-0.5 text-xs",
+      md: "px-3 py-1.5 text-sm",
+      lg: "px-4 py-2 text-base",
+    };
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    export function Snippet({
+      children,
+      symbol = "$",
+      variant = "flat",
+      color = "default",
+      size = "md",
+      radius = "md",
+      hideSymbol = false,
+      hideCopyButton = false,
+      disableCopy = false,
+      disableTooltip = false,
+      className,
+      codeString,
+      onCopy,
+    }: SnippetProps) {
+      const [copied, setCopied] = useState(false);
+      const isMultiLine = Array.isArray(children);
+      const lines = isMultiLine ? children : [children];
+      const textToCopy = codeString || (isMultiLine ? lines.join("\n") : String(children));
+
+      const handleCopy = async () => {
+        if (disableCopy) return;
+
+        try {
+          await navigator.clipboard.writeText(textToCopy);
+          setCopied(true);
+          setTimeout(() => setCopied(false), 2000);
+          onCopy?.(textToCopy);
+        } catch (error) {
+          console.error("Failed to copy:", error);
+        }
+      };
+
+      const symbolElement = hideSymbol ? null : (
+        <span className={cn("text-default-500", colorClasses[color], "opacity-60")}>
+          {symbol}{typeof symbol === "string" ? " " : ""}
+        </span>
+      );
+
+      const copyButton = hideCopyButton ? null : (
+        <Tooltip isDisabled={disableTooltip || disableCopy}>
+          <Button
+            isIconOnly
+            aria-label="Copy"
+            size="sm"
+            variant="ghost"
+            onPress={handleCopy}
+            isDisabled={disableCopy}
+            className="shrink-0"
+          >
+            {copied ? (
+              <span className="text-success">✓</span>
+            ) : (
+              <span>📋</span>
+            )}
+          </Button>
+          <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+        </Tooltip>
+      );
+
+      return (
+        <div
+          className={cn(
+            "flex items-start gap-2 font-mono",
+            variantClasses[variant],
+            sizeClasses[size],
+            radiusClasses[radius],
+            className
+          )}
+        >
+          <div className="flex-1 min-w-0">
+            {isMultiLine ? (
+              <div className="space-y-1">
+                {lines.map((line, index) => (
+                  <pre key={index} className={cn("m-0", colorClasses[color])}>
+                    {symbolElement}
+                    {line}
+                  </pre>
+                ))}
+              </div>
+            ) : (
+              <pre className={cn("m-0", colorClasses[color])}>
+                {symbolElement}
+                {children}
+              </pre>
+            )}
+          </div>
+          {copyButton}
+        </div>
+      );
+    }
+
+    // Usage
+    <Snippet
+      symbol="$"
+      variant="bordered"
+      color="primary"
+      size="md"
+    >
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+1. **组件已移除**：v3 不再提供 `Snippet` 组件。
+2. **导入调整**：移除 `import { Snippet } from "@heroui/react"`。
+3. **使用原生元素**：改用原生 `<pre>`、`<code>` 等元素。
+4. **手动复制**：使用 Clipboard API 实现复制。
+5. **样式**：直接用 Tailwind CSS 类表达变体、颜色、尺寸。
+6. **Tooltip**：复制按钮的提示请使用 v3 Tooltip。
+7. **Button**：复制按钮请使用 v3 Button。
+
+## 迁移步骤
+
+1. **移除导入**：从 `@heroui/react` 的导入中删除 `Snippet`。
+2. **替换组件**：将所有 `<Snippet>` 替换为原生 HTML 结构。
+3. **实现复制**：使用 `navigator.clipboard.writeText()` 等方法。
+4. **添加复制按钮**：使用 v3 的 Button 与 Tooltip。
+5. **应用样式**：用 Tailwind CSS 表达变体、颜色、尺寸。
+6. **处理多行**：多行场景对数组做映射渲染。
+7. **（可选）** 在应用中封装可复用的 Snippet 组件。
+
+## Clipboard API 说明
+
+Clipboard API 需要：
+
+- HTTPS（本地开发可使用 localhost）
+- 用户手势触发（不能自动调用）
+- 现代浏览器支持
+
+如需兼容旧浏览器，可采用回退方案：
+
+```tsx
+const handleCopy = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch (error) {
+    // 旧版浏览器回退
+    const textArea = document.createElement("textarea");
+    textArea.value = text;
+    textArea.style.position = "fixed";
+    textArea.style.opacity = "0";
+    document.body.appendChild(textArea);
+    textArea.select();
+    document.execCommand("copy");
+    document.body.removeChild(textArea);
+  }
+};
+```
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/spacer.mdx b/apps/docs/content/docs/cn/react/migration/(components)/spacer.mdx
new file mode 100644
index 0000000..6ec5a45
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/spacer.mdx
@@ -0,0 +1,285 @@
+---
+title: Spacer
+description: Spacer 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  Spacer 组件已在 HeroUI v3 中**移除**。请改为直接使用 Tailwind CSS 的 margin 工具类。
+</Callout>
+
+## 关键变化
+
+### 1. 组件移除
+
+**v2：** 来自 `@heroui/react` 的 `<Spacer>` 组件  
+**v3：** Tailwind CSS margin 工具类（`ml-*`、`mr-*`、`mt-*`、`mb-*`、`mx-*`、`my-*`）
+
+### 2. Prop 对应关系
+
+v2 的 Spacer 组件提供以下 prop，可映射到 Tailwind 工具类：
+
+| v2 prop | v3 对应 | 说明 |
+| --- | --- | --- |
+| `x={n}` | `ml-{n}` 或 `mx-{n}` | 水平外边距（左侧或两侧） |
+| `y={n}` | `mt-{n}` 或 `my-{n}` | 垂直外边距（顶部或两侧） |
+| `isInline` | `inline-block` 或 `block` | 显示类型 |
+
+### 3. 间距刻度
+
+v2 中的间距数值与 Tailwind 的 spacing 刻度一致：
+
+- `x={1}` → `ml-1`（0.25rem / 4px）
+- `x={2}` → `ml-2`（0.5rem / 8px）
+- `x={4}` → `ml-4`（1rem / 16px）
+- `y={4}` → `mt-4`（1rem / 16px）
+- 以此类推。
+
+## 迁移示例
+
+### 基础间距
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer } from "@heroui/react";
+
+    {/* Vertical spacing */}
+    <div>
+      <div>Item 1</div>
+      <Spacer y={4} />
+      <div>Item 2</div>
+    </div>
+    
+    {/* Horizontal spacing */}
+    <div className="flex">
+      <div>Item 1</div>
+      <Spacer x={4} isInline />
+      <div>Item 2</div>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 垂直间距 */}
+    <div>
+      <div>Item 1</div>
+      <div className="mt-4">Item 2</div>
+    </div>
+    
+    {/* 水平间距 */}
+    <div className="flex">
+      <div>Item 1</div>
+      <div className="ml-4">Item 2</div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用 gap（推荐）
+
+在 flex 与 grid 布局中，使用 `gap` 往往比 Spacer 更合适：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer } from "@heroui/react";
+
+    {/* Horizontal layout */}
+    <div className="flex">
+      <div>Item 1</div>
+      <Spacer x={4} isInline />
+      <div>Item 2</div>
+    </div>
+    
+    {/* Vertical layout */}
+    <div className="flex flex-col">
+      <Button>Button 1</Button>
+      <Spacer y={2} />
+      <Button>Button 2</Button>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* 水平布局 */}
+    <div className="flex gap-4">
+      <div>Item 1</div>
+      <div>Item 2</div>
+    </div>
+    
+    {/* 垂直布局 */}
+    <div className="flex flex-col gap-2">
+      <Button>Button 1</Button>
+      <Button>Button 2</Button>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## 完整示例
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer, Button } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div>
+          <h1>Title</h1>
+          <Spacer y={4} />
+          <p>Description text</p>
+          <Spacer y={8} />
+          <div className="flex">
+            <Button>Cancel</Button>
+            <Spacer x={4} isInline />
+            <Button>Submit</Button>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div>
+          <h1>Title</h1>
+          <p className="mt-4">Description text</p>
+          <div className="mt-8 flex gap-4">
+            <Button>Cancel</Button>
+            <Button>Submit</Button>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 间距刻度参考
+
+Tailwind CSS spacing 刻度（与 v2 Spacer 数值对应）：
+
+| 数值 | 尺寸 | Tailwind class |
+| --- | --- | --- |
+| `0` | 0px | `m-0`、`ml-0`、`mt-0` 等 |
+| `px` | 1px | `m-px`、`ml-px`、`mt-px` 等 |
+| `0.5` | 0.125rem（2px） | `m-0.5`、`ml-0.5`、`mt-0.5` 等 |
+| `1` | 0.25rem（4px） | `m-1`、`ml-1`、`mt-1` 等 |
+| `2` | 0.5rem（8px） | `m-2`、`ml-2`、`mt-2` 等 |
+| `3` | 0.75rem（12px） | `m-3`、`ml-3`、`mt-3` 等 |
+| `4` | 1rem（16px） | `m-4`、`ml-4`、`mt-4` 等 |
+| `5` | 1.25rem（20px） | `m-5`、`ml-5`、`mt-5` 等 |
+| `6` | 1.5rem（24px） | `m-6`、`ml-6`、`mt-6` 等 |
+| `8` | 2rem（32px） | `m-8`、`ml-8`、`mt-8` 等 |
+| `10` | 2.5rem（40px） | `m-10`、`ml-10`、`mt-10` 等 |
+| `12` | 3rem（48px） | `m-12`、`ml-12`、`mt-12` 等 |
+| `16` | 4rem（64px） | `m-16`、`ml-16`、`mt-16` 等 |
+| `20` | 5rem（80px） | `m-20`、`ml-20`、`mt-20` 等 |
+
+## 最佳实践
+
+### 1. 在 flex / grid 布局中使用 gap
+
+用 `gap` 工具类替代 Spacer 组件：
+
+```tsx
+// ✅ 推荐
+<div className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</div>
+
+// ❌ 不推荐
+<div className="flex">
+  <Button>Button 1</Button>
+  <div className="ml-4"><Button>Button 2</Button></div>
+</div>
+```
+
+### 2. 垂直列表使用 space 工具类
+
+```tsx
+// ✅ 推荐
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+
+// 备选
+<div>
+  <div>Item 1</div>
+  <div className="mt-4">Item 2</div>
+  <div className="mt-4">Item 3</div>
+</div>
+```
+
+### 3. 直接使用 margin 工具类
+
+将 margin 直接写在元素上，而不是使用 Spacer：
+
+```tsx
+// ✅ 推荐
+<div className="mt-4">Content</div>
+
+// ❌ 不推荐
+<>
+  <Spacer y={4} />
+  <div>Content</div>
+</>
+```
+
+## 总结
+
+1. **组件已移除**：v3 中不再提供 `Spacer` 组件。
+2. **导入调整**：移除 `import { Spacer } from "@heroui/react"`。
+3. **使用 Tailwind 工具类**：改用 margin 工具类（`ml-*`、`mt-*`、`mx-*`、`my-*` 等）。
+4. **优先使用 gap**：在 flex / grid 布局中优先使用 `gap-*`。
+5. **优先使用 space**：在列表中优先使用 `space-y-*` 与 `space-x-*` 保持一致的间距。
+
+## 迁移步骤
+
+1. **移除导入**：从 `@heroui/react` 的导入中删除 `Spacer`。
+2. **替换 Spacer**：将 `<Spacer x={n} />` 替换为 `ml-{n}` 或 `mx-{n}` 等 class。
+3. **替换 Spacer**：将 `<Spacer y={n} />` 替换为 `mt-{n}` 或 `my-{n}` 等 class。
+4. **使用 gap**：在 flex / grid 布局中用 `gap-{n}` 替代 Spacer。
+5. **使用 space**：在垂直 / 水平列表中用 `space-y-{n}` 或 `space-x-{n}`。
+
+## 常见模式
+
+### 垂直堆叠与间距
+
+```tsx
+// 使用 space-y 工具类
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### 水平行与间距
+
+```tsx
+// 使用 gap 工具类
+<div className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+  <Button>Button 3</Button>
+</div>
+```
+
+### 特定元素之间的自定义间距
+
+```tsx
+<div>
+  <div>Item 1</div>
+  <div className="mt-8">Item 2 (with custom spacing)</div>
+  <div className="mt-4">Item 3</div>
+</div>
+```
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/spinner.mdx b/apps/docs/content/docs/cn/react/migration/(components)/spinner.mdx
new file mode 100644
index 0000000..48a9e45
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/spinner.mdx
@@ -0,0 +1,184 @@
+---
+title: Spinner
+description: Spinner 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Spinner 文档](/docs/react/components/spinner)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Spinner 支持多种变体与标签：
+
+```tsx
+import { Spinner } from "@heroui/react";
+
+export default function App() {
+  return <Spinner variant="default" label="Loading..." color="primary" />;
+}
+```
+
+在 v3 中，Spinner 已简化为单一圆形变体：
+
+```tsx
+import { Spinner } from "@heroui/react";
+
+export default function App() {
+  return <Spinner color="accent" />;
+}
+```
+
+## 主要变化
+
+### 1. 组件行为
+
+**v2：** 支持多种变体（`default`、`simple`、`gradient`、`wave`、`dots`、`spinner`）以及标签  
+**v3：** 仅保留单一圆形旋转变体，不再支持标签
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `label` | — | 如有需要，请使用单独的元素手动添加标签 |
+| `variant` | — | 仅提供一种 spinner 变体 |
+| `labelColor` | — | 不再支持标签 |
+| `classNames` | — | 直接使用 `className` prop |
+| `size` | `size` | 取值变化：`"sm" \| "md" \| "lg"` → `"sm" \| "md" \| "lg" \| "xl"` |
+| `color` | `color` | 取值有变化（详见下文） |
+
+### 3. 颜色值变化
+
+- `"default"` → `"current"`（继承当前文本颜色）
+- `"primary"` → `"accent"`
+- `"secondary"` → 已移除（请改用 `"current"` 或 `"accent"`）
+- `"success"`、`"warning"`、`"danger"` → 仍可使用
+
+## 迁移示例
+
+### 带标签
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Simple label */}
+    <Spinner label="Loading..." />
+    
+    {/* With label color and custom styling */}
+    <Spinner
+      label="Loading..."
+      labelColor="primary"
+      classNames={{
+        label: "text-foreground mt-4"
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Simple label */}
+    <div className="flex flex-col items-center gap-2">
+      <Spinner />
+      <span>Loading...</span>
+    </div>
+    
+    {/* With custom styling */}
+    <div className="flex flex-col items-center gap-2">
+      <Spinner />
+      <span className="text-foreground mt-4">Loading...</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 尺寸与颜色
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+    </div>
+    
+    {/* Colors */}
+    <div className="flex gap-4">
+      <Spinner color="default" />
+      <Spinner color="primary" />
+      <Spinner color="secondary" />
+      <Spinner color="success" />
+      <Spinner color="warning" />
+      <Spinner color="danger" />
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+      <Spinner size="xl" />
+    </div>
+    
+    {/* Colors */}
+    <div className="flex gap-4">
+      <Spinner color="current" />
+      <Spinner color="accent" />
+      <Spinner color="success" />
+      <Spinner color="warning" />
+      <Spinner color="danger" />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 变体（已移除）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div className="flex gap-4">
+      <Spinner variant="default" />
+      <Spinner variant="simple" />
+      <Spinner variant="gradient" />
+      <Spinner variant="wave" />
+      <Spinner variant="dots" />
+      <Spinner variant="spinner" />
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Only one variant available - circular spinner */}
+    <Spinner />
+    
+    {/* For other spinner styles, consider using CSS animations */}
+    ```
+  </Tab>
+</Tabs>
+
+## 颜色映射
+
+迁移颜色时，可参考以下映射：
+
+| v2 颜色 | v3 颜色 | 说明 |
+| ------- | ------- | ---- |
+| `"default"` | `"current"` | 继承当前文本颜色 |
+| `"primary"` | `"accent"` | 使用强调色 |
+| `"secondary"` | `"current"` 或 `"accent"` | 改用当前色或强调色 |
+| `"success"` | `"success"` | 不变 |
+| `"warning"` | `"warning"` | 不变 |
+| `"danger"` | `"danger"` | 不变 |
+
+## 总结
+
+1. **不再支持标签**：移除 `label` prop——如有需要请手动添加标签
+2. **不再有变体**：移除 `variant` prop——仅保留单一圆形 spinner
+3. **不再有标签颜色**：移除 `labelColor` prop——请自行为标签设置样式
+4. **颜色值变化**：`"default"` → `"current"`、`"primary"` → `"accent"`、`"secondary"` 已移除
+5. **新增尺寸**：新增 `"xl"` 尺寸可选
+6. **移除 classNames**：直接使用 `className` prop
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/switch.mdx b/apps/docs/content/docs/cn/react/migration/(components)/switch.mdx
new file mode 100644
index 0000000..fa078a1
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/switch.mdx
@@ -0,0 +1,379 @@
+---
+title: Switch
+description: Switch 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Switch 文档](/docs/react/components/switch)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，`Switch` 结构简单，children 作为标签：
+
+```tsx
+import { Switch } from "@heroui/react";
+
+export default function App() {
+  return <Switch>Enable notifications</Switch>;
+}
+```
+
+在 v3 中，`Switch` 需要复合组件：
+
+```tsx
+import { Switch, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** children 作为标签的简单 Switch  
+**v3：** 复合组件（`Switch.Content`、`Switch.Control`、`Switch.Thumb`）与 `Label` 组件
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `onValueChange` | `onChange` | 事件处理函数已重命名 |
+| `size` | `size` | 仍在根上（`sm` \| `md` \| `lg`） |
+| `label` | — | 请使用 `Label` 组件 |
+| `color` | — | 已移除（请使用 Tailwind CSS） |
+| `thumbIcon` | — | 请在 `Switch.Thumb` 内使用 `Switch.Icon` |
+| `startContent` | — | 请直接自定义控件 |
+| `endContent` | — | 请直接自定义控件 |
+| `classNames` | — | 请在各子组件上使用 `className` |
+| `disableAnimation` | — | 已移除（动画机制已不同） |
+
+### 3. 新组件
+
+- `SwitchGroup` — 用于将多个 Switch 成组  
+- `Switch.Content` — 可点击的标签，包裹控件与 `Label`  
+- `Switch.Icon` — 拇指（Thumb）内的图标  
+
+## 迁移示例
+
+### 受控 Switch
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(true);
+
+    <Switch isSelected={isSelected} onValueChange={setIsSelected}>
+      Airplane mode
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(true);
+
+    <Switch isSelected={isSelected} onChange={setIsSelected}>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Airplane mode
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### 无标签
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch defaultSelected aria-label="Automatic updates" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch defaultSelected aria-label="Automatic updates">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### 带拇指图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch thumbIcon={<CheckIcon />}>Enable notifications</Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb>
+            <Switch.Icon>
+              <CheckIcon />
+            </Switch.Icon>
+          </Switch.Thumb>
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### 带起始 / 结束内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch
+      startContent={<SunIcon />}
+      endContent={<MoonIcon />}
+    >
+      Dark mode
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="flex items-center gap-2">
+          <SunIcon />
+          <Switch.Thumb />
+          <MoonIcon />
+        </Switch.Control>
+        Dark mode
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### 带标签与描述
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch description="You will receive notifications for all activity">
+      Enable notifications
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Switch, Label, Description } from "@heroui/react";
+
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+      <Description>You will receive notifications for all activity</Description>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### 尺寸与颜色
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Switch size="sm">Small</Switch>
+      <Switch size="md">Medium</Switch>
+      <Switch size="lg">Large</Switch>
+    </div>
+    
+    {/* Colors */}
+    <Switch color="primary">Primary</Switch>
+    <Switch color="success">Success</Switch>
+    <Switch color="danger">Danger</Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Switch size="sm">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Small
+        </Switch.Content>
+      </Switch>
+      <Switch size="md">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Medium
+        </Switch.Content>
+      </Switch>
+      <Switch size="lg">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Large
+        </Switch.Content>
+      </Switch>
+    </div>
+    
+    {/* Colors - Use Tailwind CSS classes */}
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-accent">
+          <Switch.Thumb />
+        </Switch.Control>
+        Primary
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-success">
+          <Switch.Thumb />
+        </Switch.Control>
+        Success
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-danger">
+          <Switch.Thumb />
+        </Switch.Control>
+        Danger
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### Switch 组
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* No built-in group component in v2 */}
+    <div className="flex flex-col gap-2">
+      <Switch name="notifications">Allow Notifications</Switch>
+      <Switch name="marketing">Marketing emails</Switch>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { SwitchGroup } from "@heroui/react";
+
+    <SwitchGroup>
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Allow Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing emails
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件组成
+
+v3 `Switch` 的结构如下：
+
+```
+Switch (Root)
+  ├── Switch.Content (the clickable label)
+  │   ├── Switch.Control
+  │   │   └── Switch.Thumb
+  │   │       └── Switch.Icon (optional)
+  │   └── Label
+  ├── Description (optional, sibling)
+  └── FieldError (optional, sibling)
+```
+
+分组时：
+
+```
+SwitchGroup
+  ├── Switch
+  │   ├── Switch.Content
+  │   │   ├── Switch.Control
+  │   │   │   └── Switch.Thumb
+  │   │   └── Label
+  │   └── Description (optional)
+  └── Switch
+      ├── Switch.Content
+      │   ├── Switch.Control
+      │   │   └── Switch.Thumb
+      │   └── Label
+      └── Description (optional)
+```
+
+## 说明
+
+### 事件处理函数
+
+- **v2：** `onValueChange` prop  
+- **v3：** `onChange` prop（签名相同：`(isSelected: boolean) => void`）
+
+### 标签
+
+- **v2：** children 作为标签  
+- **v3：** `Label` 放在 `Switch.Content`（可点击的标签）内；`Description` / `FieldError` 作为 `Switch.Content` 的同级元素
+
+### 图标
+
+- **v2：** `thumbIcon` 用于拇指内图标，`startContent` / `endContent` 用于外侧图标  
+- **v3：** 拇指内图标用 `Switch.Icon`（置于 `Switch.Thumb` 内）；起始 / 结束内容请自定义 `Switch.Control`
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Switch.Content`、`Switch.Control`、`Switch.Thumb`）
+2. **可点击的标签**：用 `Switch.Content` 包裹 `Switch.Control` 与 `Label`；将 `Description` / `FieldError` 作为 `Switch.Content` 的同级元素
+3. **标签**：不再用 children 作为标签 — 请在 `Switch.Content` 内使用 `Label`
+4. **事件处理函数**：`onValueChange` → `onChange`
+5. **样式相关 prop 已移除**：`color` — 请使用 Tailwind CSS
+6. **图标相关 prop 已移除**：`thumbIcon`、`startContent`、`endContent` — 请用子组件或直接自定义
+7. **`classNames` 已移除**：请在各子组件上使用 `className` prop
+8. **新组件**：`SwitchGroup` 用于成组；`Switch.Content` 作为可点击的标签，包裹控件与 `Label`
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/table.mdx b/apps/docs/content/docs/cn/react/migration/(components)/table.mdx
new file mode 100644
index 0000000..7970e5f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/table.mdx
@@ -0,0 +1,523 @@
+---
+title: Table
+description: Table 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Table 文档](/docs/react/components/table)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Table 对每个部分使用独立的命名导入：
+
+```tsx
+import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Table aria-label="Example table">
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate Moore</TableCell>
+          <TableCell>CEO</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+在 v3 中，Table 使用点语法的复合组件，并新增 `Table.ScrollContainer` 与 `Table.Content`：
+
+```tsx
+import { Table } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Example table">
+          <Table.Header>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 独立的命名导入（`Table`、`TableHeader`、`TableColumn`、`TableBody`、`TableRow`、`TableCell`）  
+**v3：** 单一 `Table` 导入配合点语法：`Table`、`Table.ScrollContainer`、`Table.Content`、`Table.Header`、`Table.Column`、`Table.Body`、`Table.Row`、`Table.Cell`、`Table.Footer`
+
+### 2. 新增包裹层
+
+- **`Table`**：根容器（样式外层）
+- **`Table.ScrollContainer`**：横向滚动与自定义滚动条
+- **`Table.Content`**：实际的 `<table>` 元素（`aria-label`、`selectionMode`、`sortDescriptor` 等放在这里）
+- **`Table.Footer`**：替代 `bottomContent`，用于分页等底部内容
+
+### 3. Prop 变更
+
+| v2 prop                   | v3 对应位置                     | 说明                                      |
+| ------------------------- | ------------------------------- | ----------------------------------------- |
+| `aria-label`              | `Table.Content` 的 `aria-label` | 移到 `Table.Content`                      |
+| `selectionMode`           | `Table.Content`                 | 移到 `Table.Content`                      |
+| `selectedKeys`            | `Table.Content`                 | 移到 `Table.Content`                      |
+| `defaultSelectedKeys`     | `Table.Content`                 | 移到 `Table.Content`                      |
+| `onSelectionChange`       | `Table.Content`                 | 移到 `Table.Content`                      |
+| `sortDescriptor`          | `Table.Content`                 | 移到 `Table.Content`                      |
+| `onSortChange`            | `Table.Content`                 | 移到 `Table.Content`                      |
+| `disabledKeys`            | `Table.Content`                 | 移到 `Table.Content`                      |
+| `disallowEmptySelection`  | `Table.Content`                 | 移到 `Table.Content`                      |
+| `selectionBehavior`       | `Table.Content`                 | 移到 `Table.Content`                      |
+| `disabledBehavior`        | `Table.Content`                 | 移到 `Table.Content`                      |
+| `onRowAction`             | `Table.Content`                 | 移到 `Table.Content`                      |
+| `onCellAction`            | `Table.Content`                 | 移到 `Table.Content`                      |
+| `topContent`              | —                               | 放在 `Table` 内、`Table.ScrollContainer` 之前 |
+| `bottomContent`           | —                               | 使用 `Table.Footer`                       |
+| `topContentPlacement`     | —                               | 已移除（直接组合布局）                    |
+| `bottomContentPlacement`  | —                               | 已移除（直接组合布局）                    |
+| `color`                   | —                               | 已移除（请用 Tailwind CSS）               |
+| `variant`                 | `Table` 的 `variant`            | 变为 `"primary"`（卡片式，默认）或 `"secondary"`（扁平） |
+| `layout`                  | —                               | 已移除                                    |
+| `radius`                  | —                               | 已移除（请用 Tailwind CSS）               |
+| `shadow`                  | —                               | 已移除（请用 Tailwind CSS）               |
+| `isStriped`               | —                               | 已移除（请用 Tailwind CSS）               |
+| `isCompact`               | —                               | 已移除（请用 Tailwind CSS）               |
+| `isHeaderSticky`          | —                               | 已移除（请用 Tailwind CSS，例如 `sticky top-0`） |
+| `fullWidth`               | —                               | 已移除（默认全宽）                        |
+| `removeWrapper`           | —                               | 已移除（直接组合布局）                    |
+| `hideHeader`              | —                               | 已移除（省略 `Table.Header` 或用 CSS）    |
+| `isVirtualized`           | —                               | 使用 React Aria 的 `Virtualizer` 包裹     |
+| `maxTableHeight`          | —                               | 使用 CSS 或 Virtualizer                   |
+| `rowHeight`               | —                               | 与 Virtualizer 一起使用 `TableLayout`     |
+| `isKeyboardNavigationDisabled` | —                          | 已移除                                    |
+| `disableAnimation`        | —                               | 已移除                                    |
+| `classNames`              | —                               | 在各复合子组件上使用 `className`          |
+
+### 4. 使用 Checkbox 的选择
+
+**v2：** 设置 `selectionMode` 后由表格自动渲染 Checkbox。  
+**v3：** 在列与行中显式使用带 `slot="selection"` 的 `Checkbox`。
+
+### 5. 加载与空状态
+
+**v2：** `TableBody` 上的 `loadingState`、`loadingContent`、`emptyContent`。  
+**v3：** `Table.Body` 上的 `renderEmptyState`；无限滚动加载用 `Table.LoadMore`。
+
+### 6. 分页
+
+**v2：** `Table` 上的 `bottomContent`。  
+**v3：** `Table.Footer` 复合组件。
+
+### 7. 列宽调整
+
+**v2：** 非内置能力。  
+**v3：** `Table.ResizableContainer` + `Table.ColumnResizer` 复合组件。
+
+## 迁移示例
+
+### 基础表格
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@heroui/react";
+
+    <Table aria-label="Users">
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+        <TableColumn>Status</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate Moore</TableCell>
+          <TableCell>CEO</TableCell>
+          <TableCell>Active</TableCell>
+        </TableRow>
+        <TableRow key="2">
+          <TableCell>John Doe</TableCell>
+          <TableCell>Developer</TableCell>
+          <TableCell>Active</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Table } from "@heroui/react";
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          <Table.Header>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+            <Table.Column>Status</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row id="1">
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+            </Table.Row>
+            <Table.Row id="2">
+              <Table.Cell>John Doe</Table.Cell>
+              <Table.Cell>Developer</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### 动态行
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const columns = [
+      { key: "name", label: "Name" },
+      { key: "role", label: "Role" },
+    ];
+    const rows = [
+      { key: "1", name: "Kate", role: "CEO" },
+      { key: "2", name: "John", role: "Developer" },
+    ];
+
+    <Table aria-label="Users">
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const columns = [
+      { id: "name", label: "Name" },
+      { id: "role", label: "Role" },
+    ];
+    const rows = [
+      { id: "1", name: "Kate", role: "CEO" },
+      { id: "2", name: "John", role: "Developer" },
+    ];
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          <Table.Header columns={columns}>
+            {(column) => <Table.Column id={column.id}>{column.label}</Table.Column>}
+          </Table.Header>
+          <Table.Body items={rows}>
+            {(item) => (
+              <Table.Row id={item.id}>
+                <Table.Cell>{item.name}</Table.Cell>
+                <Table.Cell>{item.role}</Table.Cell>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### 选择
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Table
+      aria-label="Users"
+      selectionMode="multiple"
+      selectedKeys={selectedKeys}
+      onSelectionChange={setSelectedKeys}
+    >
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate</TableCell>
+          <TableCell>CEO</TableCell>
+        </TableRow>
+        <TableRow key="2">
+          <TableCell>John</TableCell>
+          <TableCell>Developer</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Table, Checkbox } from "@heroui/react";
+
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Users"
+          selectionMode="multiple"
+          selectedKeys={selectedKeys}
+          onSelectionChange={setSelectedKeys}
+        >
+          <Table.Header>
+            <Table.Column>
+              <Checkbox slot="selection" />
+            </Table.Column>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row id="1">
+              <Table.Cell>
+                <Checkbox slot="selection" />
+              </Table.Cell>
+              <Table.Cell>Kate</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+            </Table.Row>
+            <Table.Row id="2">
+              <Table.Cell>
+                <Checkbox slot="selection" />
+              </Table.Cell>
+              <Table.Cell>John</Table.Cell>
+              <Table.Cell>Developer</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### 排序
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [sortDescriptor, setSortDescriptor] = useState({
+      column: "name",
+      direction: "ascending",
+    });
+
+    <Table
+      aria-label="Users"
+      sortDescriptor={sortDescriptor}
+      onSortChange={setSortDescriptor}
+    >
+      <TableHeader>
+        <TableColumn key="name" allowsSorting>Name</TableColumn>
+        <TableColumn key="role" allowsSorting>Role</TableColumn>
+      </TableHeader>
+      <TableBody items={sortedItems}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [sortDescriptor, setSortDescriptor] = useState({
+      column: "name",
+      direction: "ascending",
+    });
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Users"
+          sortDescriptor={sortDescriptor}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column id="name" allowsSorting>Name</Table.Column>
+            <Table.Column id="role" allowsSorting>Role</Table.Column>
+          </Table.Header>
+          <Table.Body items={sortedItems}>
+            {(item) => (
+              <Table.Row id={item.id}>
+                <Table.Cell>{item.name}</Table.Cell>
+                <Table.Cell>{item.role}</Table.Cell>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### 分页（底部内容）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Table
+      aria-label="Users"
+      bottomContent={
+        <Pagination total={10} page={page} onChange={setPage} />
+      }
+      bottomContentPlacement="outside"
+    >
+      {/* ... */}
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          {/* Header and Body */}
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        {/* Pagination component */}
+      </Table.Footer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### 空状态
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TableBody emptyContent="No rows to display.">
+      {[]}
+    </TableBody>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Table.Body
+      items={[]}
+      renderEmptyState={() => (
+        <p className="text-center py-4">No rows to display.</p>
+      )}
+    >
+      {[]}
+    </Table.Body>
+    ```
+  </Tab>
+</Tabs>
+
+## 样式相关变化
+
+### v2：`classNames` prop
+
+```tsx
+<Table
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    table: "custom-table",
+    thead: "custom-header",
+    tbody: "custom-body",
+    tr: "custom-row",
+    th: "custom-column",
+    td: "custom-cell",
+  }}
+/>
+```
+
+### v3：直接使用 `className`
+
+```tsx
+<Table className="custom-base">
+  <Table.ScrollContainer className="custom-wrapper">
+    <Table.Content aria-label="Table" className="custom-table">
+      <Table.Header className="custom-header">
+        <Table.Column className="custom-column">Name</Table.Column>
+      </Table.Header>
+      <Table.Body className="custom-body">
+        <Table.Row className="custom-row">
+          <Table.Cell className="custom-cell">Value</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+## 组件结构（Anatomy）
+
+v3 的 Table 结构如下：
+
+```
+Table (Root container)
+  ├── Table.ScrollContainer (horizontal scroll)
+  │   └── Table.Content (<table> element, aria-label, selectionMode, etc.)
+  │       ├── Table.Header (<thead>)
+  │       │   └── Table.Column (<th>, allowsSorting, etc.)
+  │       │       └── Table.ColumnResizer (optional)
+  │       └── Table.Body (<tbody>, items, renderEmptyState)
+  │           ├── Table.Row (<tr>)
+  │           │   └── Table.Cell (<td>)
+  │           └── Table.LoadMore (optional, infinite scroll)
+  │               └── Table.LoadMoreContent
+  └── Table.Footer (optional, pagination, etc.)
+```
+
+## 数据项标识
+
+**v2：** React 的 `key` 同时用于列表调和与选择状态。  
+**v3：** 在 `Table.Row` 与 `Table.Column` 上使用 `id` 承载选择/排序状态；列表渲染仍保留 React 的 `key`。
+
+## 总结
+
+1. **导入方式**：由多个命名导入 → 单一 `Table` 导入配合点语法。
+2. **新增包裹层**：`Table.ScrollContainer` 与 `Table.Content` 包裹表格结构。
+3. **prop 迁移**：`aria-label`、`selectionMode`、`sortDescriptor` 等从 `Table` 移到 `Table.Content`。
+4. **底部区域**：`bottomContent` → `Table.Footer`。
+5. **顶部区域**：`topContent` → 放在 `Table` 内、`Table.ScrollContainer` 之前。
+6. **选择用 Checkbox**：由自动渲染 → 显式使用 `slot="selection"` 的 `Checkbox`。
+7. **空状态**：`emptyContent` → `Table.Body` 的 `renderEmptyState`。
+8. **加载**：`loadingState` / `loadingContent` → 无限滚动场景用 `Table.LoadMore`。
+9. **列宽调整**：新增 `Table.ResizableContainer` 与 `Table.ColumnResizer`。
+10. **标识字段**：行/列由 `key` 表达业务标识 → 使用 `id`。
+11. **样式类 prop 移除**：`color`、`radius`、`shadow`、`isStriped`、`isCompact` 等 → 请用 Tailwind CSS。
+12. **`classNames` 移除**：在各复合子组件上使用 `className`。
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/tabs.mdx b/apps/docs/content/docs/cn/react/migration/(components)/tabs.mdx
new file mode 100644
index 0000000..a6adbc5
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/tabs.mdx
@@ -0,0 +1,211 @@
+---
+title: Tabs
+description: Tabs 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Tabs 文档](/docs/react/components/tabs)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Tabs 使用 `Tab` 子组件，通过 `title` prop 设置标题，子节点作为面板内容：
+
+```tsx
+import { Tabs, Tab } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tabs aria-label="Options">
+      <Tab key="photos" title="Photos">
+        <Card>Content here</Card>
+      </Tab>
+    </Tabs>
+  );
+}
+```
+
+在 v3 中，Tabs 改为复合组件，Tab 与 Panel 分别独立：
+
+```tsx
+import { Tabs } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tabs>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">
+        <Card>Content here</Card>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** `Tabs` 与 `Tab` 子节点（`title` prop + 子节点作为面板）  
+**v3：** 复合组件（`Tabs.ListContainer`、`Tabs.List`、`Tabs.Tab`、`Tabs.Indicator`、`Tabs.Separator`、`Tabs.Panel`）
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `key`（在 Tab 上） | `id`（在 Tab 与 Panel 上） | prop 名称变更 |
+| `title`（在 Tab 上） | — | 内容直接放入 `Tabs.Tab` |
+| `isVertical` | `orientation` | 改为 `"horizontal"` \| `"vertical"` |
+| `placement` | — | 通过 `orientation` 与布局表达 |
+| `variant` | `variant` | 简化为仅 `primary` \| `secondary` |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `radius` | — | 已移除（请改用 Tailwind CSS） |
+| `classNames` | — | 改在各子组件上使用 `className` prop |
+| `disableCursorAnimation` | — | 改用 `Tabs.Indicator` 子组件控制 |
+| `disableAnimation` | — | 已移除（动画机制已不同） |
+| `fullWidth` | — | 已移除（请改用 Tailwind CSS） |
+
+### 3. 组件层面的变化
+
+- **Tab 标识**：`key` → `id`（`Tabs.Tab` 与 `Tabs.Panel` 之间必须一致）
+- **Tab 内容**：`title` prop → 直接将子节点放入 `Tabs.Tab`
+- **Panel 内容**：原本作为 Tab 子节点 → 改为独立的 `Tabs.Panel` 组件
+- **指示器**：自动光标 → 显式的 `Tabs.Indicator` 子组件
+- **分隔符**：新增 `Tabs.Separator` 组件，用于在 Tab 之间显示分隔线
+
+## 迁移示例
+
+### 受控 Tabs
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("photos");
+
+    <Tabs selectedKey={selected} onSelectionChange={setSelected}>
+      <Tab key="photos" title="Photos">Content</Tab>
+      <Tab key="music" title="Music">Content</Tab>
+    </Tabs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("photos");
+
+    <Tabs selectedKey={selected} onSelectionChange={setSelected}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="music">
+            Music
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">Content</Tabs.Panel>
+      <Tabs.Panel id="music">Content</Tabs.Panel>
+    </Tabs>
+    ```
+  </Tab>
+</Tabs>
+
+### 带图标
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tabs aria-label="Options">
+      <Tab key="photos" title={<><PhotoIcon /> Photos</>}>
+        Content
+      </Tab>
+    </Tabs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tabs>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            <PhotoIcon />
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">Content</Tabs.Panel>
+    </Tabs>
+    ```
+  </Tab>
+</Tabs>
+
+### 带分隔符
+
+在 v3 中，你可以在每个 `Tabs.Tab` 内部（除第一个之外）放入 `Tabs.Separator` 来显示 Tab 之间的分隔线。这是 v2 没有的新增能力。
+
+```tsx
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="photos">
+        Photos
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="music">
+        <Tabs.Separator />
+        Music
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="videos">
+        <Tabs.Separator />
+        Videos
+        <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="photos">Photos content</Tabs.Panel>
+  <Tabs.Panel id="music">Music content</Tabs.Panel>
+  <Tabs.Panel id="videos">Videos content</Tabs.Panel>
+</Tabs>
+```
+
+## 组件结构
+
+v3 Tabs 遵循以下结构：
+
+```
+Tabs (Root)
+  ├── Tabs.ListContainer
+  │   └── Tabs.List
+  │       └── Tabs.Tab
+  │           ├── Tabs.Separator (optional, omit on first tab)
+  │           └── Tabs.Indicator (optional)
+  └── Tabs.Panel (one per tab, matching id)
+```
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Tabs.ListContainer`、`Tabs.List`、`Tabs.Tab`、`Tabs.Indicator`、`Tabs.Separator`、`Tabs.Panel`）
+2. **Tab 标识**：`key` → `id`（Tab 与 Panel 之间需保持一致）
+3. **Tab 内容**：移除 `title` prop——内容直接放入 `Tabs.Tab`
+4. **Panel 分离**：面板内容移至独立的 `Tabs.Panel` 组件
+5. **指示器**：必须显式在每个 Tab 内使用 `Tabs.Indicator`
+6. **方向**：`isVertical` → `orientation` prop
+7. **样式**：`variant` 简化为 `primary` \| `secondary`；`color`、`size`、`radius`、`placement` 已移除——更多自定义请使用 Tailwind
+8. **移除 classNames**：改在各子组件上使用 `className` prop
+9. **分隔符（新增）**：在 `Tabs.Tab` 内使用 `Tabs.Separator` 显示 Tab 之间的分隔线（v2 无对应能力）
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/timeinput.mdx b/apps/docs/content/docs/cn/react/migration/(components)/timeinput.mdx
new file mode 100644
index 0000000..3d10c10
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/timeinput.mdx
@@ -0,0 +1,266 @@
+---
+title: TimeInput
+description: TimeInput → TimeField 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 TimeField 文档](/docs/react/components/time-field)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，TimeInput 是单个组件，通过 prop 配置：
+
+```tsx
+import { TimeInput } from "@heroui/react";
+
+export default function App() {
+  return <TimeInput label="Time" name="time" />;
+}
+```
+
+在 v3 中，TimeField 改为复合组件，需要配合 DateInputGroup 与分段（segment）的 render prop：
+
+```tsx
+import { TimeField, DateInputGroup, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件命名
+
+**v2：** `TimeInput`  
+**v3：** `TimeField`
+
+### 2. 组件结构
+
+**v2：** 单个组件，通过 prop 配置  
+**v3：** 复合组件：`TimeField`（根）+ `DateInputGroup` 与 `DateInputGroup.Input`（render prop）+ `DateInputGroup.Segment`；可选地搭配 `DateInputGroup.Prefix` 与 `DateInputGroup.Suffix`
+
+### 3. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `label` | — | 改用 `Label` 组件 |
+| `description` | — | 改用 `Description` 组件 |
+| `errorMessage` | — | 改用 `FieldError` 组件 |
+| `value`、`defaultValue`、`onChange` | `TimeField` | 与 React Aria 一致 |
+| `minValue`、`maxValue`、`granularity`、`placeholderValue` | `TimeField` | 相同 |
+| `isRequired`、`isDisabled`、`isReadOnly`、`isInvalid`、`name` | `TimeField` | 相同 |
+| `validationBehavior`、`shouldForceLeadingZeros` | `TimeField` | 相同 |
+| `variant` | `DateInputGroup` | 简化为仅 `primary` \| `secondary` |
+| `fullWidth` | `TimeField` 或 `DateInputGroup` | 设置在根或分组上 |
+| `color` | — | 已移除（请改用 Tailwind CSS） |
+| `size` | — | 已移除（请改用 Tailwind CSS） |
+| `radius` | — | 已移除（请改用 Tailwind CSS） |
+| `labelPlacement` | — | 通过布局自行处理 |
+| `startContent` | `DateInputGroup.Prefix` | 改用 Prefix 子组件 |
+| `endContent` | `DateInputGroup.Suffix` | 改用 Suffix 子组件 |
+| `classNames` | — | 在 `TimeField` 与 `DateInputGroup` 各部分上使用 `className` |
+| `groupProps` | — | 在 `DateInputGroup` 上使用 `className` 或标准 DOM 属性 |
+| `labelProps` | — | 在 `Label` 上使用 `className` |
+| `fieldProps` | — | 在 `DateInputGroup` 上使用 `className` |
+| `innerWrapperProps` | — | 在分组 / 输入相关部分上使用 `className` |
+| `descriptionProps` | — | 在 `Description` 上使用 `className` |
+| `errorMessageProps` | — | 在 `FieldError` 上使用 `className` |
+| `inputRef` | — | 由 `TimeField` / React Aria 处理 ref |
+
+## 迁移示例
+
+### 带描述与错误信息
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TimeInput
+      description="Select start time"
+      label="Start time"
+      name="startTime"
+    />
+
+    <TimeInput
+      errorMessage="Please enter a valid time"
+      isInvalid
+      label="Time"
+      name="time"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    <TimeField className="w-[256px]" name="startTime">
+      <Label>Start time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <Description>Select start time</Description>
+    </TimeField>
+
+    <TimeField className="w-[256px]" isInvalid name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <FieldError>Please enter a valid time</FieldError>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState(null);
+
+    <TimeInput
+      label="Time"
+      name="time"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import type { TimeValue } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState<TimeValue | null>(null);
+
+    <TimeField
+      className="w-[256px]"
+      name="time"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### 最小 / 最大值与粒度
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+
+    <TimeInput
+      granularity="minute"
+      label="Time"
+      maxValue={parseTime("18:00")}
+      minValue={parseTime("09:00")}
+      name="time"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+
+    <TimeField
+      className="w-[256px]"
+      granularity="minute"
+      maxValue={parseTime("18:00")}
+      minValue={parseTime("09:00")}
+      name="time"
+    >
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### Start / End 内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TimeInput
+      endContent={<ClockIcon />}
+      label="Time"
+      name="time"
+      startContent={<ClockIcon />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Prefix>
+          <ClockIcon />
+        </DateInputGroup.Prefix>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+        <DateInputGroup.Suffix>
+          <ClockIcon />
+        </DateInputGroup.Suffix>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件结构
+
+v3 TimeField 遵循以下结构：
+
+```
+TimeField (Root)
+  ├── Label (optional)
+  ├── DateInputGroup
+  │   ├── DateInputGroup.Prefix (optional)
+  │   ├── DateInputGroup.Input → (segment) => DateInputGroup.Segment
+  │   └── DateInputGroup.Suffix (optional)
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## 总结
+
+1. **组件重命名**：`TimeInput` → `TimeField`
+2. **组件结构**：必须使用复合组件：`TimeField`（根）配合 `DateInputGroup` 与 `DateInputGroup.Input`（render prop）+ `DateInputGroup.Segment`
+3. **标签 / 描述 / 错误**：改用独立组件（`Label`、`Description`、`FieldError`）
+4. **时间相关 prop 不变**：`value`、`defaultValue`、`onChange`、`minValue`、`maxValue`、`granularity`、`placeholderValue`、`isRequired`、`isDisabled`、`isInvalid`、`name`、`validationBehavior`、`shouldForceLeadingZeros` 继续保留在 `TimeField` 上
+5. **DateInputGroup 的变体**：v3 仅支持 `DateInputGroup` 上的 `variant="primary"` 与 `variant="secondary"`；`color`、`size`、`radius` 已移除——请改用 Tailwind CSS
+6. **Start / End 内容**：`startContent` / `endContent` → `DateInputGroup.Prefix` 与 `DateInputGroup.Suffix`
+7. **移除 labelPlacement**：`labelPlacement` 已移除——请通过布局自行实现
+8. **DOM / className prop**：`groupProps`、`labelProps`、`fieldProps`、`classNames` 已移除——请在相关部分使用 `className`（以及标准 DOM 属性）
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/toast.mdx b/apps/docs/content/docs/cn/react/migration/(components)/toast.mdx
new file mode 100644
index 0000000..b976c76
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/toast.mdx
@@ -0,0 +1,220 @@
+---
+title: Toast
+description: Toast 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Toast 文档](/docs/react/components/toast)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Toast 采用 Provider + Hook 模式：
+
+```tsx
+import { ToastProvider, useToast } from "@heroui/react";
+
+function App() {
+  return (
+    <ToastProvider>
+      <MyComponent />
+    </ToastProvider>
+  );
+}
+
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <button onClick={() => toast.show("Hello!")}>
+      Show Toast
+    </button>
+  );
+}
+```
+
+在 v3 中，Toast 改为 Provider 组件 + 全局 `toast()` 函数：
+
+```tsx
+import { Toast } from "@heroui/react";
+
+function App() {
+  return (
+    <>
+      <Toast.Provider />
+      <MyComponent />
+    </>
+  );
+}
+
+function MyComponent() {
+  return (
+    <button onClick={() => toast("Hello!")}>
+      Show Toast
+    </button>
+  );
+}
+```
+
+## 主要变化
+
+### 1. Provider 模式
+
+**v2：** 必须使用 `ToastProvider` 包裹  
+**v3：** 改用 `Toast.Provider` 组件（可放置在任意位置）
+
+### 2. Hook → 函数
+
+**v2：** 使用 `useToast()` Hook  
+**v3：** 直接调用 `toast()` 函数
+
+### 3. API 变更
+
+**v2：** 使用 `toast.show()` 方法  
+**v3：** `toast()` 是带有辅助方法的函数（`toast.success()`、`toast.danger()` 等）
+
+### 4. 变体名称
+
+**v2：** 变体如 `success`、`error`、`warning`、`info`  
+**v3：** 变体：`default`、`accent`、`success`、`warning`、`danger`
+
+### 5. 复合组件结构
+
+**v3：** Toast 通过复合组件支持自定义渲染：
+- `Toast` —— Toast 主容器
+- `Toast.Content` —— 内容包装器
+- `Toast.Title` —— 标题文字
+- `Toast.Description` —— 描述文字
+- `Toast.Indicator` —— 图标 / 指示器
+- `Toast.CloseButton` —— 关闭按钮
+- `Toast.ActionButton` —— 操作按钮
+
+### 6. Promise 支持
+
+**v3：** 内置 `toast.promise()` 方法，可处理异步操作
+
+## 迁移示例
+
+### 带标题与描述的 Toast
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({
+      title: "Success",
+      description: "Your changes have been saved",
+      variant: "success"
+    });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    toast.success("Success", {
+      description: "Your changes have been saved"
+    });
+    ```
+  </Tab>
+</Tabs>
+
+### 各变体的辅助方法
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({ variant: "success", title: "Success" });
+    toast.show({ variant: "error", title: "Error" });
+    toast.show({ variant: "warning", title: "Warning" });
+    toast.show({ variant: "info", title: "Info" });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    toast.success("Success");
+    toast.danger("Error");
+    toast.warning("Warning");
+    toast.info("Info");
+    ```
+  </Tab>
+</Tabs>
+
+### Promise 支持
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    const handleAsync = async () => {
+      try {
+        await someAsyncOperation();
+        toast.show({ title: "Success", variant: "success" });
+      } catch {
+        toast.show({ title: "Error", variant: "error" });
+      }
+    };
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    const handleAsync = async () => {
+      toast.promise(someAsyncOperation(), {
+        loading: "Processing...",
+        success: "Operation completed!",
+        error: "Operation failed"
+      });
+    };
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义 Toast 渲染
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({
+      title: "Custom",
+      render: (toast) => (
+        <div>Custom content</div>
+      )
+    });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Toast, ToastContent, ToastTitle } from "@heroui/react";
+
+    <Toast.Provider>
+      {({ toast: toastItem }) => (
+        <Toast toast={toastItem}>
+          <ToastContent>
+            <ToastTitle>Custom content</ToastTitle>
+          </ToastContent>
+        </Toast>
+      )}
+    </Toast.Provider>
+    ```
+  </Tab>
+</Tabs>
+
+## 总结
+
+- 用 `Toast.Provider` 取代 `ToastProvider`
+- 用 `toast()` 函数取代 `useToast()` Hook
+- 更新变体名称（`error` → `danger`、`info` → `accent`）
+- 使用辅助方法：`toast.success()`、`toast.danger()` 等
+- 用 `toast.promise()` 处理异步操作
+- 通过复合组件结构实现自定义渲染
+- 更好的 TypeScript 支持与队列管理
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/tooltip.mdx b/apps/docs/content/docs/cn/react/migration/(components)/tooltip.mdx
new file mode 100644
index 0000000..eb5ba41
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/tooltip.mdx
@@ -0,0 +1,353 @@
+---
+title: Tooltip
+description: Tooltip 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="info">
+  完整的 API 参考、样式指南与高级示例请参阅 [v3 Tooltip 文档](/docs/react/components/tooltip)。本指南只关注从 HeroUI v2 的迁移。
+</Callout>
+
+## 结构变化
+
+在 v2 中，Tooltip 使用 `content` prop：
+
+```tsx
+import { Tooltip, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tooltip content="I am a tooltip">
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+在 v3 中，Tooltip 需要复合组件：
+
+```tsx
+import { Tooltip, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        I am a tooltip
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## 主要变化
+
+### 1. 组件结构
+
+**v2：** 通过 `content` prop 与作为触发器的 children 使用 Tooltip  
+**v3：** 复合组件（`Tooltip.Trigger`、`Tooltip.Content`、`Tooltip.Arrow`）
+
+### 2. Prop 变更
+
+| v2 prop | v3 位置 | 说明 |
+| ------- | ------- | ---- |
+| `content` | — | 请使用 `Tooltip.Content` 的 children |
+| `showArrow` | `showArrow`（在 Content 上） | 移至 `Tooltip.Content` |
+| `placement` | `placement`（在 Content 上） | 移至 `Tooltip.Content` |
+| `offset` | `offset`（在 Content 上） | 移至 `Tooltip.Content` |
+| `color` | — | 已移除（请使用 Tailwind CSS） |
+| `size` | — | 已移除（请使用 Tailwind CSS） |
+| `radius` | — | 已移除（请使用 Tailwind CSS） |
+| `shadow` | — | 已移除（请使用 Tailwind CSS） |
+| `classNames` | — | 请在各子组件上使用 `className` |
+| `motionProps` | — | 已移除（动画机制已不同） |
+| `trigger` | `trigger`（在根上） | 仍存在：`"hover"` \| `"focus"`（默认 `"hover"`） |
+| `isDisabled` | `isDisabled`（在根上） | v3 新增：可完全禁用 Tooltip |
+| `delay` | `delay`（在根上） | 仍存在（默认由 `0` 改为 `700`） |
+| `closeDelay` | `closeDelay`（在根上） | 仍存在（默认 `0`） |
+| `portalContainer` | — | 不再对外暴露 |
+| `updatePositionDeps` | — | 不再对外暴露 |
+| `containerPadding`, `crossOffset` | — | 不再对外暴露 |
+| `shouldFlip` | — | 自动处理 |
+| `triggerScaleOnOpen` | — | 不可用 |
+| `isKeyboardDismissDisabled` | — | 不可用 |
+| `isDismissable` | — | 不可用 |
+| `shouldCloseOnBlur` | — | 不可用 |
+| `shouldCloseOnInteractOutside` | — | 不可用 |
+| `onClose` | — | 请改用 `onOpenChange` |
+
+### 3. 移至 `Tooltip.Content` 的 prop
+
+- `showArrow` — 现位于 `Tooltip.Content`
+- `placement` — 现位于 `Tooltip.Content`
+- `offset` — 现位于 `Tooltip.Content`
+
+## 迁移示例
+
+### 内容配置
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With arrow */}
+    <Tooltip content="I am a tooltip" showArrow>
+      <Button>Hover me</Button>
+    </Tooltip>
+    
+    {/* With placement */}
+    <Tooltip content="Tooltip" placement="bottom">
+      <Button>Hover me</Button>
+    </Tooltip>
+    
+    {/* With offset */}
+    <Tooltip content="Tooltip" offset={12}>
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With arrow */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content showArrow>
+        <Tooltip.Arrow />
+        <p>I am a tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    
+    {/* With placement */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content placement="bottom">
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    
+    {/* With offset */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content offset={12}>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### 受控 Tooltip
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Tooltip
+      content="I am a tooltip"
+      isOpen={isOpen}
+      onOpenChange={setIsOpen}
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Tooltip isOpen={isOpen} onOpenChange={setIsOpen} delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>I am a tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### 带延迟
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip content="Tooltip" delay={500} closeDelay={200}>
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={500} closeDelay={200}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义内容
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip
+      content={
+        <div>
+          <strong>Title</strong>
+          <p>Description</p>
+        </div>
+      }
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <div>
+          <strong>Title</strong>
+          <p>Description</p>
+        </div>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### 自定义触发器
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip content="Tooltip">
+      <div className="custom-trigger">Custom trigger</div>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={0}>
+      <Tooltip.Trigger className="custom-trigger">
+        <div>Custom trigger</div>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+## 组件组成
+
+v3 Tooltip 的结构如下：
+
+```
+Tooltip (Root)
+  ├── Tooltip.Trigger
+  │   └── [Trigger element]
+  └── Tooltip.Content
+      ├── Tooltip.Arrow (optional)
+      └── [Tooltip content]
+```
+
+## v3 新增 prop
+
+### isDisabled
+
+`isDisabled` prop 可完全禁用 Tooltip。禁用后，悬停或聚焦时都不会显示提示：
+
+```tsx
+<Tooltip isDisabled>
+  <Tooltip.Trigger>
+    <Button>No tooltip</Button>
+  </Tooltip.Trigger>
+  <Tooltip.Content>
+    <p>This will not show</p>
+  </Tooltip.Content>
+</Tooltip>
+```
+
+### trigger
+
+`trigger` prop 控制 Tooltip 的激活方式，取值为 `"hover"`（默认）或 `"focus"`：
+
+```tsx
+{/* Show tooltip only on focus */}
+<Tooltip trigger="focus">
+  <Tooltip.Trigger>
+    <Button>Focus me</Button>
+  </Tooltip.Trigger>
+  <Tooltip.Content>
+    <p>Shown on focus only</p>
+  </Tooltip.Content>
+</Tooltip>
+```
+
+### 自定义渲染函数
+
+`Tooltip.Content` 与 `Tooltip.Arrow` 均支持 `render` prop，可在高级场景下用自定义渲染函数覆盖默认 DOM 元素。
+
+## 说明
+
+### `content` prop
+
+- **v2：** 使用 `content` prop 传入提示文本 / 内容  
+- **v3：** 内容作为 `Tooltip.Content` 的 children
+
+### 箭头
+
+- **v2：** 由根上的 `showArrow` 控制  
+- **v3：** 在 `Tooltip.Content` 上使用 `showArrow`，并包含 `Tooltip.Arrow` 组件
+
+### placement 与 offset
+
+- **v2：** `placement` 与 `offset` 在根上  
+- **v3：** `placement` 与 `offset` 移至 `Tooltip.Content`
+
+### 触发元素
+
+- **v2：** children 自动作为触发器  
+- **v3：** 必须将触发元素包在 `Tooltip.Trigger` 内
+
+### 默认延迟
+
+- **v2：** `delay` 默认为 `0`  
+- **v3：** `delay` 默认为 `700`（注意：示例中使用 `delay={0}` 以贴近 v2 行为）
+
+## 总结
+
+1. **组件结构**：必须使用复合组件（`Tooltip.Trigger`、`Tooltip.Content`、`Tooltip.Arrow`）
+2. **`content` prop 已移除**：请使用 `Tooltip.Content` 的 children
+3. **prop 迁移**：`showArrow`、`placement`、`offset` 移至 `Tooltip.Content`
+4. **样式相关 prop 已移除**：`color`、`size`、`radius`、`shadow` — 请使用 Tailwind CSS
+5. **`classNames` 已移除**：请在各子组件上使用 `className`
+6. **`motionProps` 已移除**：动画机制已不同
+7. **高级 prop 已移除**：大量定位与行为相关 prop 已移除
+8. **默认延迟变更**：默认由 `0` 改为 `700`
+9. **`isDisabled` prop**：v3 新增，可完全禁用 Tooltip
+10. **`trigger` prop**：取 `"hover"`（默认）或 `"focus"`，用于控制激活方式
+11. **渲染 prop**：`Tooltip.Content` 与 `Tooltip.Arrow` 支持 `render` prop，用于自定义 DOM 渲染
diff --git a/apps/docs/content/docs/cn/react/migration/(components)/user.mdx b/apps/docs/content/docs/cn/react/migration/(components)/user.mdx
new file mode 100644
index 0000000..552ec0d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(components)/user.mdx
@@ -0,0 +1,446 @@
+---
+title: User
+description: User 从 HeroUI v2 到 v3 的迁移指南。
+---
+
+<Callout type="warning">
+  HeroUI v3 中的 User 组件已被**移除**。请使用 Avatar、文本元素与 Tailwind CSS 类手动组合用户展示。
+</Callout>
+
+## 主要变化
+
+### 1. 组件已移除
+
+**v2：** 来自 `@heroui/react` 的 `<User>` 组件  
+**v3：** 使用 `Avatar` + 文本元素手动组合
+
+### 2. 功能映射
+
+v2 User 组件包含以下需要替换的功能：
+
+| v2 功能 | v3 等效项 | 说明 |
+| ------- | ----------- | ---- |
+| `name` prop | 文本元素 | 将名称渲染为文本或标题 |
+| `description` prop | 文本元素 | 将描述渲染为文本 |
+| `avatarProps` prop | `Avatar` 组件 | 直接使用 v3 Avatar 组件 |
+| `isFocusable` prop | 手动焦点处理 | 按需添加 `tabIndex` 与焦点样式 |
+| `classNames` prop | Tailwind CSS 类 | 直接将类应用到元素上 |
+
+## 结构变化
+
+### v2：User 组件
+
+在 v2 中，`User` 是一个将 Avatar 与名称组合在一起的便捷组件：
+
+```tsx
+import { User } from "@heroui/react";
+
+export default function App() {
+  return (
+    <User
+      name="Junior Garcia"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+  );
+}
+```
+
+### v3：手动组合
+
+在 v3 中，请使用 Avatar 和文本元素手动组合用户展示：
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </div>
+  );
+}
+```
+
+## 迁移示例
+
+### 带描述
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">Junior Garcia</span>
+        <span className="text-xs text-muted">Software Engineer</span>
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 使用默认头像（姓名首字母）
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      avatarProps={{
+        name: "Junior Garcia",
+        getInitials: (name) =>
+          name
+            .split(" ")
+            .map((n) => n[0])
+            .join(""),
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    function getInitials(name: string) {
+      return name
+        .split(" ")
+        .map((n) => n[0])
+        .join("");
+    }
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Fallback>{getInitials("Junior Garcia")}</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 带链接描述
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User, Link } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description={
+        <Link href="https://x.com/jrgarciadev" size="sm">
+          @jrgarciadev
+        </Link>
+      }
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Link } from "@heroui/react";
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">Junior Garcia</span>
+        <Link href="https://x.com/jrgarciadev" className="text-xs">
+          @jrgarciadev
+        </Link>
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 可点击的用户
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    {/* Focusable */}
+    <User
+      name="Junior Garcia"
+      isFocusable
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    
+    {/* As button */}
+    <User
+      as="button"
+      name="Junior Garcia"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    {/* Focusable */}
+    <button
+      className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus"
+      tabIndex={0}
+    >
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </button>
+    
+    {/* As button */}
+    <button
+      className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus"
+    >
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </button>
+    ```
+  </Tab>
+</Tabs>
+
+## 创建可复用的 User 组件（推荐）
+
+由于用户展示很常见，可以创建一个可复用组件：
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Link } from "@heroui/react";
+    import { ReactNode } from "react";
+    import { cn } from "@/lib/utils"; // 或你的 cn 工具函数
+
+    interface UserProps {
+      name: string | ReactNode;
+      description?: string | ReactNode;
+      avatarSrc?: string;
+      avatarAlt?: string;
+      avatarFallback?: string;
+      className?: string;
+      isFocusable?: boolean;
+      as?: "div" | "button" | "a";
+      href?: string;
+      onClick?: () => void;
+    }
+
+    function getInitials(name: string): string {
+      return name
+        .split(" ")
+        .map((n) => n[0])
+        .join("")
+        .toUpperCase()
+        .slice(0, 2);
+    }
+
+    export function User({
+      name,
+      description,
+      avatarSrc,
+      avatarAlt,
+      avatarFallback,
+      className,
+      isFocusable = false,
+      as = "div",
+      href,
+      onClick,
+    }: UserProps) {
+      const Component = as === "a" ? "a" : as === "button" ? "button" : "div";
+      const fallback = avatarFallback || (typeof name === "string" ? getInitials(name) : "?");
+
+      const content = (
+        <>
+          <Avatar>
+            {avatarSrc && (
+              <Avatar.Image
+                src={avatarSrc}
+                alt={avatarAlt || (typeof name === "string" ? name : "")}
+              />
+            )}
+            <Avatar.Fallback>{fallback}</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col items-start">
+            <span className="text-sm">{name}</span>
+            {description && (
+              <span className="text-xs text-muted">{description}</span>
+            )}
+          </div>
+        </>
+      );
+
+      const baseClasses = cn(
+        "inline-flex items-center gap-2 rounded-sm outline-none",
+        isFocusable && "focus-visible:ring-2 focus-visible:ring-focus",
+        className
+      );
+
+      if (Component === "button") {
+        return (
+          <button className={baseClasses} onClick={onClick} tabIndex={isFocusable ? 0 : -1}>
+            {content}
+          </button>
+        );
+      }
+
+      if (Component === "a") {
+        return (
+          <a href={href} className={baseClasses} tabIndex={isFocusable ? 0 : -1}>
+            {content}
+          </a>
+        );
+      }
+
+      return (
+        <div className={baseClasses} tabIndex={isFocusable ? 0 : -1}>
+          {content}
+        </div>
+      );
+    }
+
+    // Usage
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarSrc="https://example.com/avatar.jpg"
+      avatarAlt="Junior Garcia"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+## 样式参考
+
+v2 User 组件使用了以下基础样式，迁移时可以按需复用：
+
+- **基础容器**：`inline-flex items-center gap-2 rounded-sm`
+- **包装层（用于名称 / 描述）**：`inline-flex flex-col items-start`
+- **名称**：`text-sm`（text-small）
+- **描述**：`text-xs text-muted`（text-tiny text-foreground-400）
+
+## 总结
+
+1. **组件已移除**：v3 中不再提供 `User` 组件
+2. **导入变更**：移除 `import { User } from "@heroui/react"`
+3. **手动组合**：使用 Avatar + 文本元素组合用户展示
+4. **Avatar 变更**：使用 v3 Avatar 的复合组件模式
+5. **样式**：直接应用 Tailwind CSS 类
+6. **焦点处理**：如有需要，手动实现焦点样式
+
+## 迁移步骤
+
+1. **移除导入**：从 `@heroui/react` 导入中移除 `User`
+2. **替换组件**：将所有 `<User>` 实例替换为手动组合
+3. **使用 Avatar**：使用 v3 Avatar 复合组件模式
+4. **添加文本元素**：将名称和描述作为文本元素添加
+5. **应用样式**：使用 Tailwind CSS 类处理布局与样式
+6. **处理焦点**：如果使用过 `isFocusable`，请添加焦点样式
+7. **可选**：为你的应用创建可复用的 User 组件
+
+## 常见模式
+
+### 用户列表
+
+```tsx
+<div className="space-y-2">
+  {users.map((user) => (
+    <div key={user.id} className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image src={user.avatar} alt={user.name} />
+        <Avatar.Fallback>{getInitials(user.name)}</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">{user.name}</span>
+        {user.role && (
+          <span className="text-xs text-muted">{user.role}</span>
+        )}
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+### 可点击的用户
+
+```tsx
+<button
+  className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus hover:bg-default-100"
+  onClick={() => handleUserClick(user)}
+>
+  <Avatar>
+    <Avatar.Image src={user.avatar} alt={user.name} />
+    <Avatar.Fallback>{getInitials(user.name)}</Avatar.Fallback>
+  </Avatar>
+  <div className="flex flex-col items-start">
+    <span className="text-sm">{user.name}</span>
+    <span className="text-xs text-muted">{user.email}</span>
+  </div>
+</button>
+```
diff --git a/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agent-skills.mdx b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..81db4ae
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agent-skills.mdx
@@ -0,0 +1,60 @@
+---
+title: Agent Skills
+description: 让 AI 助手协助你将 HeroUI v2 迁移到 v3。
+---
+
+HeroUI Migration Skills 为你的 AI 助手提供关于 HeroUI v2 到 v3 迁移流程、组件指南与最佳实践的完整知识。
+
+### 安装
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-migration
+```
+
+或者通过 skills 包安装：
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+支持 Claude Code、Cursor、OpenCode 等。
+</span>
+
+### 使用方法
+
+Skills 会被你的 AI 助手**自动发现**，你也可以直接通过 `/heroui-migration` 命令调用它。
+
+只需让你的 AI 助手做这些事：
+- 将组件从 HeroUI v2 迁移到 v3
+- 获取完整迁移或渐进式迁移的流程
+- 获取面向特定组件的迁移指南
+- 查阅 Hooks 与样式相关的迁移文档
+
+### 包含的内容
+
+- 迁移流程（完整与渐进式）
+- 面向特定组件的迁移指南（39 个组件）
+- Hooks 迁移指南（如 `useDisclosure` → `useOverlayState` 等）
+- 样式迁移指南（工具类、颜色 token、CSS 变量）
+- 关键 API 变更与复合组件模式
+
+### 结构
+
+```
+skills/heroui-migration/
+├── SKILL.md                    # Main skill documentation
+├── LICENSE.txt                 # Apache License 2.0
+└── scripts/                    # Utility scripts
+    ├── list_migration_guides.mjs
+    ├── get_migration_guide.mjs
+    ├── get_component_migration_guides.mjs
+    ├── get_styling_migration_guide.mjs
+    └── get_hooks_migration_guide.mjs
+```
+
+## 链接
+
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [Discord 社区](https://discord.gg/9b6yyZKmH4)
+- [Agent Skills](https://agentskills.io/) —— 了解 Agent Skills 的格式
diff --git a/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agents-md.mdx b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..e296399
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/agents-md.mdx
@@ -0,0 +1,51 @@
+---
+title: AGENTS.md
+description: 下载 AI 编码代理的 HeroUI v2 到 v3 迁移文档
+---
+
+将 HeroUI v2 到 v3 的迁移文档直接下载到您的项目中，供 AI 助手参考。
+
+<Callout>
+  **注：** `agents-md --migration` 仅下载迁移文档；使用 `--react` 下载组件文档。一次只能选择一个库选项。
+</Callout>
+
+### 用法
+
+```bash
+npx heroui-cli@latest agents-md --migration
+```
+
+或者指定输出文件：
+
+```bash
+npx heroui-cli@latest agents-md --migration --output AGENTS.md
+```
+
+### 它的作用
+
+- 将迁移文档下载到`.heroui-docs/migration/`
+- 生成索引 `AGENTS.md` 或 `CLAUDE.md`，包含迁移专用内容
+- 包括工作流程指南（完整和增量）、组件迁移指南、挂钩和样式
+- 添加`.heroui-docs/`到`.gitignore`自动地
+
+### 选项
+
+- `--migration`- 仅下载迁移文档（v2 到 v3）
+- `--output <files...>` — 目标文件（例如 `AGENTS.md` 或 `AGENTS.md CLAUDE.md`）
+- `--ssh`- 使用 SSH 进行 git 克隆
+
+### 要求
+
+迁移文档对于从 HeroUI v2 迁移到 v3 的任何项目都很有用。目标项目需要：
+
+- Tailwind CSS >= v4
+- React >= 19.0.0（对于 v3）
+- `@heroui/react`或者`@heroui/styles`（迁移后）
+
+## 链接
+
+- [GitHub 存储库](https://github.com/heroui-inc/heroui)
+- [Discord社区](https://discord.gg/9b6yyZKmH4)
+- [代理.md](https://agents.md/)- 了解 AGENTS.md 格式
+- [Claude.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) — Claude 侧的 AGENTS.md 等价物
+- [AGENTS.md 与技能](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)- AGENTS.md 性能
diff --git a/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/mcp-server.mdx b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..6c264b7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(migration-for-agents)/mcp-server.mdx
@@ -0,0 +1,175 @@
+---
+title: MCP服务器
+description: 在 AI 助手中访问 HeroUI v2 到 v3 的迁移指南
+---
+
+HeroUI 迁移 MCP 服务器使 AI 助手可以直接访问 HeroUI v2 到 v3 的迁移文档。
+
+迁移 MCP 服务器使用 **Streamable HTTP 传输**（基于 URL）并部署在`https://migration-mcp.heroui.com`。查看源代码[GitHub](https://github.com/heroui-inc/heroui-mcp/tree/main/apps/migration-mcp).
+
+<Callout>
+  迁移 MCP 仅用于**迁移**。完成迁移后，切换到[HeroUI React MCP 服务器](/docs/react/getting-started/mcp-server)用于 v3 组件开发。
+</Callout>
+
+## 快速设置
+
+### Cursor
+
+添加到 **Cursor 设置** → **工具** → **MCP 服务器**，或项目的 `.cursor/mcp.json`：
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+要了解更多信息，请参阅 [Cursor 文档](https://cursor.com/docs/context/mcp)。
+
+### Claude Code
+
+添加到项目的 `.mcp.json`：
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "type": "http",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+添加配置后，重启 Claude Code 并运行 `/mcp`，在列表中查看 HeroUI 迁移 MCP。若显示 **已连接**，即可开始使用。
+
+请参阅 [Claude Code MCP 文档](https://docs.claude.com/en/docs/claude-code/mcp)了解更多详情。
+
+### Windsurf
+
+将迁移 MCP 服务器添加到您的项目`.windsurf/mcp.json`配置文件：
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+添加配置后，重新启动Windsurf以激活MCP服务器。
+
+请参阅[Windsurf MCP 文档](https://docs.windsurf.com/windsurf/cascade/mcp)了解更多详情。
+
+### Zed
+
+将迁移 MCP 添加到你的 `settings.json`。通过命令面板打开设置（`zed: open settings`）或使用 `Cmd-,`（macOS）/ `Ctrl-,`（Linux）：
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+请参阅[Zed MCP 文档](https://zed.dev/docs/ai/mcp)了解更多详情。
+
+### VS Code
+
+若要在 VS Code 中通过 GitHub Copilot 配置 MCP，请将迁移 MCP 添加到项目的 `.vscode/mcp.json`：
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-migration": {
+      "type": "http",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+添加配置后，打开`.vscode/mcp.json`然后单击herui-migration 服务器旁边的**开始**。
+
+请参阅[VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)了解更多详情。
+
+### Codex
+
+将迁移 MCP 添加到 `~/.codex/config.toml`（或项目内的 `.codex/config.toml`）：
+
+```toml title="config.toml"
+[mcp_servers.heroui-migration]
+url = "https://migration-mcp.heroui.com"
+```
+
+添加配置后，重启 Codex 并在 TUI 中运行 `/mcp` 以确认服务器已激活。
+
+请参阅 [Codex MCP 文档](https://developers.openai.com/codex/mcp)了解更多详情。
+
+### OpenCode
+
+将迁移 MCP 添加到项目的 `opencode.json`：
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-migration": {
+      "type": "remote",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+添加配置后，重新启动OpenCode以激活MCP服务器。
+
+请参阅[OpenCode MCP 文档](https://open-code.ai/docs/en/mcp-servers)了解更多详情。
+
+## 用法
+
+配置完成后，向您的 AI 助手询问以下问题：
+
+- “帮我将 Button 从 HeroUI v2 迁移到 v3”
+- “获取我的项目的完整迁移工作流程”
+- “复选框迁移有何变化？”
+- “显示 Card 和 Modal 的迁移指南”
+- “获取样式迁移指南”
+- “我需要迁移哪些钩子？”
+
+## 可用工具
+
+Migration MCP 服务器为 AI 助手提供以下工具：
+
+|工具|描述|
+|------|-------------|
+| `get_migration_workflow` |获取全面的迁移指南。使用`migrationType: "full"`（默认）或`"incremental"`完整迁移方法与增量迁移方法|
+| `list_component_migration_guides` |列出所有 39 个可用组件迁移指南|
+| `get_component_migration_guides` | 获取指定组件的迁移指南。传入 `components: ["button", "card"]`（kebab-case） |
+| `get_styling_migration_guide` |获取样式迁移指南（实用程序类、颜色标记、CSS 变量）|
+| `get_hooks_migration_guide` |获取 hooks 迁移指南（useDisclosure → useOverlayState 等）|
+
+## 可用提示
+
+迁移 MCP 服务器提供引导提示，可在代理聊天中与斜杠命令一起使用：
+
+| 提示词 | 描述 |
+|--------|-------------|
+| `analyze-and-plan` | 分析项目以识别所有 HeroUI v2 组件并创建迁移计划。建议作为迁移第一步。可选：`migrationType: "full"`（默认）或 `"incremental"` |
+| `implement-migration` | 分阶段实施组件迁移，并设置检查点供用户确认。完成组件迁移与依赖切换后，继续指导 hooks 与样式迁移。可选：`migrationType: "full"`（默认）或 `"incremental"` |
+
+**工作流程：** 运行`analyze-and-plan`首先创建您的迁移计划，然后使用`implement-migration`一步步执行它。
+
+## 链接
+
+- [GitHub 存储库](https://github.com/heroui-inc/heroui-mcp/tree/main/apps/migration-mcp)
+- [Discord 社区](https://discord.gg/9b6yyZKmH4)
+- [Model Context Protocol](https://modelcontextprotocol.io/) — 了解 MCP
diff --git a/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-full.mdx b/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-full.mdx
new file mode 100644
index 0000000..ce50aee
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-full.mdx
@@ -0,0 +1,322 @@
+---
+title: 代理迁移指南 - 完整迁移
+description: AI 助手的完整迁移指南，帮助将 HeroUI v2 迁移到 v3
+index: false
+---
+
+## 概述
+
+本指南专为人工智能助手（代理）设计，帮助用户从 HeroUI v2 迁移到 v3。它实现了**完整迁移方法**，首先分析项目并以可管理的批次迁移组件，而不是一次性迁移全部组件。
+
+<Callout type="warning">
+  **关键约束**：HeroUI v2 和 v3 **不应在同一项目中共存**。该项目将在迁移过程中被破坏。始终在功能分支中工作并在切换依赖项之前迁移所有组件代码。
+</Callout>
+
+## 关键原则
+
+1. **完整迁移**：不要试图在一次改动中迁移所有组件；应按可管理的批次推进。大型项目同样需要采用完整迁移流程（在切换依赖前完成全部组件适配）。
+2. **首先进行项目分析**：在创建迁移计划之前，始终分析代码库以了解组件的使用情况。
+3. **损坏的状态管理**： **严重**：项目将在迁移过程中损坏。为此制定计划：
+   - 在功能分支中迁移
+   - 在切换依赖项之前准备好所有代码更改
+   - 制定回滚计划
+   - 首先在隔离环境中进行测试
+4. **全有或全无依赖关系切换**：依赖关系更新到 v3 后，必须迁移所有组件。在切换依赖关系之前规划组件迁移。
+
+## v3 的主要变化
+
+<include>../index.mdx#major-changes</include>
+
+## 详细迁移步骤
+
+有关详细的分步说明，请参阅[完整迁移指南](/docs/react/migration/full-migration)。该指南涵盖：
+
+- 依赖项更新
+- 主题配置更改
+- 删除 HeroUIProvider
+- 组件导入和迁移
+- 钩子迁移
+- 样式迁移
+- 测试
+
+**代理注意**：依赖项更新（React 19、Tailwind v4）可以在切换 HeroUI 之前完成（不会破坏项目）。但是，HeroUI 包切换只能在所有组件代码迁移之后进行。
+
+## 钩子迁移
+
+HeroUI v2 提供了组件挂钩（例如`useSwitch`, `useInput`, `useCheckbox`等）和实用程序挂钩，例如`useDisclosure`。 HeroUI v3 删除了大多数组件挂钩，转而使用复合组件，并替换了`useDisclosure`和`useOverlayState`.
+
+**何时迁移钩子：**
+
+- **组件迁移期间**：替换组件钩子（`useSwitch`, `useInput`等）当您迁移每个组件以使用复合组件时
+- **组件迁移后**：迁移`useDisclosure` → `useOverlayState`用于样式迁移之前的覆盖状态管理
+
+**迁移策略：**
+
+1. **识别钩子用法**：搜索代码库以从以下位置导入`@heroui/react`包括钩子名称（`useSwitch`, `useInput`, `useCheckbox`, `useRadio`, `useDisclosure`， ETC。）
+2. **替换组件钩子**：使用复合组件而不是带有 prop getter 的钩子（在组件迁移期间完成）
+3. **替换 useDisclosure**：迁移到`useOverlayState`用于覆盖状态管理（使用`get_hooks_migration_guide`MCP 工具）
+4. **参考指南**：使用`get_hooks_migration_guide`用于钩子迁移的 MCP 工具，`get_component_migration_guides`特定于组件的指南
+
+## 组件导入更改
+
+请参阅[完整迁移指南](/docs/react/migration/full-migration#step-5-update-component-imports)了解详细的组件导入更改。
+
+## 组件迁移参考
+
+<include>../index.mdx#step-6-component-migration-reference</include>
+
+<Callout type="info">
+  **已删除/进行中/计划的组件**：对于标记为 ❌ 已删除、🔄 进行中或 📋 计划的组件，请在迁移过程中将其替换为标准 HTML 元素。一旦 HeroUI 组件在 v3 中可用，您就可以迁移回它们。
+</Callout>
+
+使用`get_component_migration_guides`MCP 工具可获取每个组件的详细指南。
+
+## v3 中的新组件
+
+<include>../index.mdx#new-components-in-v3</include>
+
+## 自定义主题覆盖
+
+请参阅[完整迁移指南](/docs/react/migration/full-migration#step-7-update-custom-theme-overrides)用于自定义主题覆盖迁移。
+
+## 样式迁移
+
+请参阅[完整迁移指南](/docs/react/migration/full-migration#step-9-styling-migration)有关详细的样式迁移说明。
+
+**代理注意**：使用`get_styling_migration_guide`用于全面样式迁移详细信息的 MCP 工具。
+
+**重要**：样式迁移发生在组件迁移和依赖关系切换之后。
+
+## 完整的迁移工作流程
+
+**重要**：由于 v2 和 v3 无法共存，因此迁移分两个主要阶段进行：
+
+1. **准备阶段**：迁移所有组件代码，同时仍依赖 v2 依赖项（代码将被破坏）
+2. **切换阶段**：将依赖项更新到 v3 并修复任何剩余问题
+
+**⚠️ 关键：不要构建来检查迁移过程中的错误**
+
+- 使用**类型检查**（例如，`tsc --noEmit`) 如果可以检查 TypeScript 错误
+- 使用**lint**（例如，`eslint`, `biome check`) 如果可以检查代码质量
+- **不要**运行构建命令（例如，`npm run build`, `next build`, `vite build`)
+- **请勿** 在迁移期间尝试启动/运行项目
+
+### 第 0 阶段：设置和分析
+
+1. **创建迁移分支**
+   - 创建一个功能分支用于迁移工作
+   - 例子：`git checkout -b migrate/heroui-v3`
+
+2. **验证迁移 MCP 是否已配置**
+   - 检查迁移 MCP 服务器是否已连接
+   - 确保`heroui-react`MCP 未连接（以避免混淆）
+   - 验证 MCP 工具可用
+
+3. **分析项目并创建迁移计划**
+   - 使用`get_migration_workflow`获取本指南
+   - 扫描 HeroUI v2 导入，识别所有组件和使用情况
+   - 映射组件依赖关系
+   - 创建分阶段迁移计划（例如，每个阶段 3-5 个组件，按依赖项策略）
+
+### 第 1 阶段：依赖项准备（代码更改之前）
+
+这些步骤可以在切换 HeroUI 依赖项之前完成，并且不会破坏项目：
+
+1. **将 React 更新到 v19**（如果还没有）
+   - 这可以在切换 HeroUI 之前完成
+
+2. **将 Tailwind CSS 更新至 v4**（如果尚未更新）
+   - 这可以在切换 HeroUI 之前完成
+
+3. **🛑 检查点：停止并等待用户批准**
+   - **不要自动进入下一阶段**
+   - 解释配置更改
+   - 在继续之前等待明确的用户批准
+
+### 第 2-N 阶段：代码迁移（v2 依赖项仍然有效）
+
+**关键**：在此阶段，代码将引用 v3 API，但仍安装 v2 依赖项。该项目将被破坏。这是预期的且正常的。
+
+对于迁移计划中的每个组件组：
+
+1. **获取特定于组件的指南**
+   - 使用`get_component_migration_guides`适用于每个组件的 MCP 工具
+   - 审查 API 更改、prop 迁移、结构更改
+
+2. **应用代码迁移**
+   - 将组件代码迁移到 v3 API 模式
+   - 更新导入、道具、组件结构
+   - **注意**：在切换依赖关系之前，代码将被破坏
+
+3. **处理依赖关系**
+   - 如果组件有依赖，先迁移依赖
+   - 检查依赖项是否已经迁移
+   - 根据需要迁移共享代码
+
+4. **🛑 检查点：停止并等待用户批准**
+   - **不要自动进入下一阶段**
+   - 总结一下本阶段迁移的内容
+   - 在继续之前等待明确的用户批准
+
+5. **记录迁移状态**
+   - 跟踪哪些组件已迁移
+   - 注意任何问题或疑虑
+
+### 最终阶段：依赖关系切换和修复
+
+**关键**：仅当所有组件都已迁移到 v3 API 模式时才继续。
+
+1. **更新依赖关系**
+   - 消除`@heroui/react`和`@heroui/theme`（v2）
+   - 安装`@heroui/react`和`@heroui/styles`(v3)
+   - 消除`framer-motion`如果存在
+   - 更新 CSS 导入（添加`@import "@heroui/styles";`)
+   - 从应用程序根目录中删除 HeroUIProvider
+   - 更新 Tailwind 配置（删除`heroui()`插件）
+
+2. **修复剩余问题**
+   - 运行 typecheck/lint（如果可用）（不构建）
+   - 修复类型检查报告的任何 TypeScript 错误
+   - 修复任何 linting 错误
+   - 注意：请勿在迁移期间尝试构建或运行项目
+
+3. **🛑 检查点：停止并等待用户批准**
+   - **不要自动进行样式设置**
+   - 验证组件是否正常工作
+   - 在样式迁移之前等待明确的用户批准
+
+4. **继续样式迁移**
+   - 使用 `get_styling_migration_guide` MCP 工具获取样式迁移指南
+   - 系统地应用样式更新
+
+5. **应用样式更新**
+   - 使用`get_styling_migration_guide`MCP工具
+   - 更新实用程序类、颜色标记、CSS 变量
+   - 测试视觉外观
+
+6. **最终验证**
+   - 最后运行一次类型检查/lint（不构建）
+   - 验证所有样式是否正确更新
+   - 注意：完整测试（视觉、功能、可访问性）应在迁移完成后完成，而不是在迁移期间完成
+
+## 迁移策略
+
+### 策略 1：按依赖关系（推荐）
+
+- 首先迁移基础组件（按钮、输入、卡等）
+- 然后迁移依赖它们的组件
+- 最适合具有复杂组件层次结构的项目
+- 确保依赖项先于依赖项准备就绪
+
+**订单示例**：
+1. 按钮、输入、链接（基础）
+2. 卡片、模态（使用按钮）
+3. 表单、下拉菜单（使用输入、按钮）
+4. 复杂组件（使用多个依赖项）
+
+### 策略 2：按功能
+
+- 将功能/模块中的所有组件迁移到一起
+- 适合基于功能的代码组织
+- 允许逐个功能测试
+- 可能需要先迁移依赖项
+
+**例子**：
+- 功能：用户身份验证
+  - 迁移：输入、按钮、表单、模态（所有与身份验证相关）
+- 功能：仪表板
+  - 迁移：卡、选项卡、选择（所有与仪表板相关）
+
+### 策略 3：按频率
+
+- 首先迁移最常用的组件
+- 提供快速获胜和早期验证
+- 适合具有清晰使用模式的大型代码库
+- 仍然需要处理依赖关系
+
+**例子**：
+1. 按钮（使用150次）
+2. 输入（使用120次）
+3. 卡（已使用80次）
+4. ...（按使用次数继续）
+
+## 代理最佳实践
+
+1. **关于损坏状态的警告**
+   - 始终通知用户项目在迁移过程中将被破坏
+   - 推荐使用功能分支
+   - 设定项目何时再次运作的预期
+
+2. **切换依赖项之前迁移所有代码**
+   - 首先完成所有组件代码迁移
+   - 仅当迁移所有组件时才切换依赖项
+   - 这最大限度地减少了破坏状态的持续时间
+
+3. **每个阶段使用 MCP 工具**
+   - 使用`get_migration_workflow`, `get_component_migration_guides`, `get_styling_migration_guide`根据需要
+   - **关键**：始终在检查点停止并等待阶段之间的用户批准
+
+4. **在功能分支工作**
+   - 始终建议创建迁移分支
+   - 允许用户继续在主分支上工作
+   - 如果需要，启用轻松回滚
+
+5. **记录迁移状态**
+   - 跟踪哪些组件已迁移
+   - 注意任何问题或疑虑
+   - 保持清单可见
+   - 每个阶段后更新状态
+
+6. **优雅地处理错误**
+   - 如果组件迁移失败，请记录原因
+   - 继续其他组件
+   - 依赖切换后返回失败的组件
+   - 更新依赖项后，某些问题可能会得到解决
+
+7. **依赖关系切换后验证**
+   - 仅在依赖项更新到 v3 后
+   - 运行类型检查/lint（不构建）
+   - 修复出现的类型/lint 错误
+   - 在类型检查/lint 通过之前不要继续进行样式设置
+
+## 常见场景
+
+### 大型项目（100 多个组件）
+
+- 使用较小的批量（3-5 个组件）
+- 按依赖性或频率确定优先级
+- 允许多个会话
+- 在阶段之间创建检查点
+- 使用“按依赖”策略
+- 清楚地记录进度
+
+### 小型项目（\<20 个组件）
+
+- 可以使用更大的批次（5-10 个组件）
+- 可以通过更少的阶段完成
+- 仍然增量验证（全迁移方式）
+- 可以使用任何策略
+- 在切换 deps 之前仍然需要迁移所有代码
+
+### 混合 v2/v3 使用（完全迁移）
+
+- **完全迁移中不可能**：v2 和 v3 不能在完全迁移方法中共存
+- 在切换依赖关系之前必须迁移所有组件
+- 使用功能分支来维护工作主分支
+- 一次性完成迁移
+
+## 下一步
+
+完成迁移后：
+
+1. 删除 v2 依赖项（已在依赖切换步骤中完成）
+2. 从迁移 MCP 切换到用于 v3 开发的 `heroui-react` MCP
+3. 更新文档中的引用
+4. 运行最终验证
+5. 将迁移分支合并回主分支
+
+---
+
+<Callout type="info">
+  本代理迁移指南旨在与迁移 MCP 服务器配合使用。在开始迁移之前，请确保 MCP 服务器已正确配置并且工具可用。
+</Callout>
diff --git a/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-incremental.mdx b/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-incremental.mdx
new file mode 100644
index 0000000..d766d29
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(workflows)/agent-guide-incremental.mdx
@@ -0,0 +1,258 @@
+---
+title: 代理迁移指南 - 共存增量迁移
+description: AI 助手增量共存迁移指南，帮助将 HeroUI v2 迁移到 v3
+index: false
+---
+
+## 概述
+
+本指南专为人工智能助手（代理）设计，帮助用户使用**增量共存迁移**从 HeroUI v2 迁移到 v3。这种方法允许 v2 和 v3 组件并行工作，从而实现逐个组件迁移，同时保持项目正常运行。
+
+<Callout type="info">
+  **主要区别**：与完全迁移不同，增量共存迁移允许项目在迁移期间保持功能。 v2 和 v3 组件可以暂时共存。
+</Callout>
+
+## 关键原则
+
+1. **增量组件迁移**：一次迁移一个组件，在继续之前测试每个组件
+2. **项目保持功能**：与完全迁移不同，项目应始终保持工作状态
+3. **策略识别**：确定项目使用哪种共存策略（A：pnpm 别名或 B：组件包）
+4. **逐个组件测试**：在移动到下一个组件之前测试每个迁移的组件
+5. **CSS 冲突管理**：监控并解决共存期间 v2 和 v3 之间的样式冲突
+6. **已移除组件**：没有 v3 对位的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）可在共存期间保留。除非用户明确要求替换，否则不要迁移它们。
+
+## v3 的主要变化
+
+<include>../index.mdx#major-changes</include>
+
+## 增量迁移设置
+
+有关详细设置和迁移说明，请参阅[增量迁移指南](/docs/react/migration/incremental-migration)。该指南涵盖：
+
+- 策略选择（A：pnpm 别名或 B：组件包）
+- 每个策略的详细设置
+- 共存的 CSS 配置
+- 逐个组件的迁移过程
+- CSS 冲突处理
+- 完成迁移
+
+## 策略识别
+
+对于使用增量共存策略的项目，代理应该：
+
+1. **确定策略**：检查项目是否使用pnpm别名（策略A）或组件包（策略B）
+   - **策略 A**：寻找别名，例如`"@heroui-v3/react": "npm:@heroui/react@latest"`在 package.json 中
+   - **策略 B**：寻找特定于组件的包，例如`@heroui/button`, `@heroui/card`旁边`@heroui/react`
+
+2. **验证设置**：确保共存设置正确：
+   - 策略A：两者兼而有之`@heroui/react`（v2）和`@heroui-v3/react`（v3 别名）已安装
+   - 策略B：`@heroui/react`(v3) 和组件包，例如`@heroui/button`(v2) 已安装
+   - CSS 已针对两个版本进行配置（请参阅 CSS 配置部分）
+
+## 逐个组件的迁移指南
+
+### 对于策略 A（pnpm 别名）：
+
+1. **识别要迁移的组件**
+   - 查看组件迁移参考表
+   - 使用`get_component_migration_guides`用于获取特定于组件的指南的 MCP 工具
+
+2. **更新导入**
+   - 将导入从 `@heroui/react` 改为 `@heroui-v3/react`
+   - 例子：`import {Button} from "@heroui/react"` → `import {Button} from "@heroui-v3/react"`
+
+3. **更新组件代码**
+   - 遵循组件迁移指南`get_component_migration_guides`工具
+   - 更新 props、组件结构和 API 调用
+   - 如果需要，用复合组件替换挂钩
+
+4. **测试迁移的组件**
+   - 验证组件正确渲染
+   - 测试功能和交互
+   - 检查样式冲突
+
+5. **文档迁移**
+   - 跟踪哪些组件已迁移
+   - 注意任何问题或疑虑
+
+### 对于策略 B（组件包）：
+
+1. **识别要迁移的组件**
+   - 查看组件迁移参考表
+   - 使用`get_component_migration_guides`用于获取特定于组件的指南的 MCP 工具
+
+2. **移除组件包**
+   - 从依赖项中删除 v2 组件包（例如，`@heroui/button`)
+   - 更新package.json
+
+3. **更新导入**
+   - 将组件包中的导入更改为`@heroui/react`(v3)
+   - 例子：`import {Card} from "@heroui/card"` → `import {Card} from "@heroui/react"`
+
+4. **更新组件代码**
+   - 遵循组件迁移指南`get_component_migration_guides`工具
+   - 更新 props、组件结构和 API 调用
+   - 如果需要，用复合组件替换挂钩
+
+5. **测试迁移的组件**
+   - 验证组件正确渲染
+   - 测试功能和交互
+   - 检查样式冲突
+
+6. **文档迁移**
+   - 跟踪哪些组件已迁移
+   - 注意任何问题或疑虑
+
+### 处理移除的组件（无 v3 对应项）
+
+当遇到没有 v3 对位的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）时：
+
+- **将它们留在原处** - 不要尝试迁移它们，除非用户明确请求删除
+- **如果用户想要删除它们**：使用`get_component_migration_guides`（如果有）或[组件迁移参考](/docs/react/migration#component-migration-reference)获取指南并帮助替换为原生 HTML 或手动实现
+
+## CSS 冲突处理
+
+共存期间，v2 和 v3 CSS 系统都会被加载。代理应该：
+
+1. **监控冲突**
+   - 注意样式不一致
+   - 检查v2和v3样式是否冲突
+   - 验证两个 CSS 导入均存在且顺序正确
+
+2. **指导冲突解决**
+   - 确保 CSS 导入顺序：`tailwindcss`首先，然后`@heroui/styles`
+   - 检查 Tailwind 配置是否配置了 v2 插件
+   - 验证 v3 CSS 是否正确导入
+
+3. **每次迁移后测试样式**
+   - 验证迁移的组件看起来正确
+   - 检查是否有意外的样式覆盖
+   - 确保 v2 组件的样式仍然正确
+
+## 组件迁移参考
+
+<include>../index.mdx#step-6-component-migration-reference</include>
+
+使用`get_component_migration_guides`MCP 工具可获取每个组件的详细指南。
+
+## v3 中的新组件
+
+<include>../index.mdx#new-components-in-v3</include>
+
+## 完成步骤
+
+迁移所有组件后：
+
+1. **删除 v2 依赖项**
+   - 策略A：删除`@heroui/react`, `@heroui/theme`和别名
+   - 策略B：删除所有剩余的`@heroui/*`组件包
+   - 如果项目仍包含上述已移除 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**），请告知用户：他们可稍后在代理协助下按指南移除或替换。
+
+2. **更新所有导入**
+   - 策略A：改变`@heroui-v3/react` → `@heroui/react`
+   - 策略 B：所有导入应已指向 `@heroui/react`（v3）
+
+3. **更新CSS配置**
+   - 从配置中删除 v2 Tailwind 插件
+   - 仅保留`@import "@heroui/styles";`
+   - 删除 v2 CSS 导入
+
+4. **完成样式迁移**
+   - 遵循样式迁移指南
+   - 使用`get_styling_migration_guide`MCP工具
+   - 更新实用程序类、颜色标记等。
+
+## 与完全迁移的差异
+
+**主要区别：**
+
+- **项目状态**：项目在迁移过程中保持功能（无损坏状态）
+- **迁移速度**：可以在较长时间内逐个组件进行迁移
+- **测试**：可以在完全迁移之前测试 v3 组件和 v2 组件
+- **分支策略**：功能分支不太重要（尽管仍然推荐）
+- **依赖管理**：两个版本暂时共存
+- **CSS 处理**：两个 CSS 系统在共存期间加载
+
+**何时使用增量共存：**
+
+- 需要逐步迁移的大型代码库
+- 迁移期间必须保持功能的项目
+- 想要增量测试 v3 组件的团队
+- 已使用特定于组件的包的项目（策略 B）
+
+**何时使用完全迁移：**
+
+- 可以快速迁移的较小项目
+- 可以接受临时破坏状态的项目
+- 喜欢一次性迁移的团队
+- 项目使用统一`@heroui/react`包（策略 A 可以工作，但完全迁移可能更简单）
+
+## 代理最佳实践
+
+1. **验证项目仍然正常运行**
+   - 每个组件迁移后，确保项目仍然有效
+   - 测试已迁移和未迁移的组件
+   - 立即报告任何问题
+
+2. **指导逐个组件迁移**
+   - 帮助一次迁移一个组件
+   - 使用`get_component_migration_guides`适用于每个组件的 MCP 工具
+   - 在继续之前彻底测试
+
+3. **监控 CSS 冲突**
+   - 注意 v2 和 v3 之间的样式问题
+   - 指导解决冲突
+   - 确保 CSS 配置正确
+
+4. **跟踪迁移进度**
+   - 保留已迁移组件的清单
+   - 记录任何问题或疑虑
+   - 注意正在使用哪种策略
+
+5. **指导完成步骤**
+   - 迁移所有组件后，指导删除 v2 依赖项
+   - 帮助将所有导入更新为仅限 v3
+   - 指导样式迁移完成
+
+## 常见场景
+
+### 大型项目（100 多个组件）
+
+- 随着时间的推移逐步迁移组件
+- 彻底测试每个组件
+- 监控 CSS 冲突
+- 可能需要数周或数月才能完成
+
+### 小型项目（\<20 个组件）
+
+- 可以更快地迁移
+- 仍然测试每个组件
+- 减少 CSS 冲突风险
+- 可能在几天内完成
+
+### 混合战略项目
+
+- 有些项目可能对某些组件使用策略 A，对其他组件使用策略 B
+- 指导每个组件进行适当的导入更新
+- 尽可能确保方法一致
+
+### 项目使用 v2 导航栏（或其他已删除的组件）
+
+- 留在原处 —— v2 Navbar 与其他已移除组件（**Code**、**Image**、**Ripple**、**Snippet**、**Spacer**、**User**）在共存期间仍会继续工作
+- 告知用户：若不再需要，可在代理协助下移除；替换方案见 [组件迁移参考](/docs/react/migration#component-migration-reference)。
+
+## 下一步
+
+完成迁移后：
+
+1. 删除 v2 依赖项（已在完成步骤中完成）
+2. 从迁移 MCP 切换到用于 v3 开发的 `heroui-react` MCP
+3. 更新文档中的引用
+4. 运行最终验证
+5. 完成样式迁移
+
+---
+
+<Callout type="info">
+  本代理迁移指南旨在与迁移 MCP 服务器配合使用。在开始迁移之前，请确保 MCP 服务器已正确配置并且工具可用。
+</Callout>
diff --git a/apps/docs/content/docs/cn/react/migration/(workflows)/full-migration.mdx b/apps/docs/content/docs/cn/react/migration/(workflows)/full-migration.mdx
new file mode 100644
index 0000000..6755730
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(workflows)/full-migration.mdx
@@ -0,0 +1,509 @@
+---
+title: 完全迁移
+description: 使用完整迁移方法将 HeroUI v2 迁移到 v3 的分步指南
+---
+
+## 概述
+
+完全迁移是一种从 HeroUI v2 迁移到 v3 的结构化方法。此方法首先迁移所有组件代码，然后切换依赖关系，确保干净的过渡。
+
+**重要：** 完全迁移意味着项目在迁移过程中将被破坏（v2 和 v3 不能共存）。在功能分支中工作以维护工作主分支。
+
+### AI 助理资源
+
+AI 助手可以协助迁移。你可以使用 [迁移 MCP 服务器](/docs/react/migration/mcp-server) 获取工具与提示词，使用 [迁移 Agent Skills](/docs/react/migration/agent-skills) 获取基于技能的知识，或使用 [用于迁移的 AGENTS.md](/docs/react/migration/agents-md) 将迁移文档下载到项目中。
+
+## 迁移工作流程
+
+**重要**：由于 v2 和 v3 无法共存，因此迁移分两个主要阶段进行：
+
+1. **准备阶段**：迁移所有组件代码，同时仍依赖 v2 依赖项（代码将被破坏）
+2. **切换阶段**：将依赖项更新到 v3 并修复任何剩余问题
+
+**⚠️ 关键：不要构建来检查迁移过程中的错误**
+
+- 使用**类型检查**（例如，`tsc --noEmit`) 如果可以检查 TypeScript 错误
+- 使用**lint**（例如，`eslint`, `biome check`) 如果可以检查代码质量
+- **不要**运行构建命令（例如，`npm run build`, `next build`, `vite build`)
+- **请勿** 在迁移期间尝试启动/运行项目
+
+## 分步迁移指南
+
+<section id="step-1-update-dependencies">
+
+### 第 1 步：更新依赖项
+
+#### 更新反应
+
+v3 需要 React 19+。更新你的 React 版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+</Tabs>
+
+**注意**：这些依赖项更新可以在切换 HeroUI 之前完成（不会破坏项目）。但是，HeroUI 包切换只能在所有组件代码迁移之后进行。
+
+#### 更新 HeroUI 包
+
+**重要**：在迁移所有组件代码后执行此操作。删除 v2 软件包并安装 v3：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm uninstall @heroui/react @heroui/theme
+    npm install @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm remove @heroui/react @heroui/theme
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn remove @heroui/react @heroui/theme
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun remove @heroui/react @heroui/theme
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+#### 删除Framer Motion
+
+v3 不再需要 Framer Motion：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm uninstall framer-motion
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm remove framer-motion
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn remove framer-motion
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun remove framer-motion
+    ```
+  </Tab>
+</Tabs>
+
+#### 更新 Tailwind CSS
+
+确保您使用的是 Tailwind CSS v4：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add tailwindcss@^4.0.0
+    ```
+  </Tab>
+</Tabs>
+
+</section>
+
+<section id="step-2-update-theming-configuration">
+
+### 第 2 步：更新主题配置
+
+#### 删除 Tailwind 插件配置
+
+**v2 配置：**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
+  ],
+  plugins: [heroui()],
+  // ... other config
+};
+```
+
+**v3 配置：**
+
+删除`heroui()`来自 Tailwind 配置的插件。如果您仅将 Tailwind 用于 HeroUI 并且没有其他自定义，则可以删除`tailwind.config.js`完全。否则，保留该文件但删除 HeroUI 插件配置。
+
+#### 更新 CSS 导入
+
+**v2 CSS：**
+
+```css
+/* globals.css or main.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**v3 CSS：**
+
+```css
+/* globals.css or main.css */
+@import "tailwindcss";
+@import "@heroui/styles"; /* [!code highlight]*/
+```
+
+<Callout type="warning">
+  **重要提示：** 导入顺序很重要：先导入 `tailwindcss`，再导入 `@heroui/styles`。
+</Callout>
+
+#### 删除主题插件文件
+
+如果您创建了一个`hero.ts`v2 文件，您可以将其删除：
+
+```bash
+rm hero.ts
+```
+
+</section>
+
+<section id="step-3-remove-herouiprovider">
+
+### 第3步：删除HeroUIProvider
+
+v3 不需要 Provider 组件。从应用程序根目录中删除它。
+
+**v2 代码：**
+
+```tsx
+// app.tsx or App.tsx
+import {HeroUIProvider} from "@heroui/react";
+
+function App() {
+  return (
+    <HeroUIProvider>
+      <YourApplication />
+    </HeroUIProvider>
+  );
+}
+```
+
+**v3 代码：**
+
+```tsx
+// app.tsx or App.tsx
+function App() {
+  return <YourApplication />;
+}
+```
+
+**如果您使用 Provider 道具：**
+
+如果您使用 Provider 道具，例如`navigate`, `useHref`, `locale`, `disableAnimation`等等，您需要以不同的方式处理这些：
+
+- **路由器集成**：直接使用 React Router 或您的路由库
+- **区域设置**：使用 React Aria 的`I18nProvider`如果需要直接
+- **动画**：请参阅下面的动画更改部分
+
+#### 动画变化
+
+v3 删除了 Framer Motion 依赖性并以不同方式处理动画：
+
+- **基于 CSS 的动画**：v3 使用原生 CSS 动画和过渡，而不是基于 JavaScript 的动画
+- **更好的性能**：CSS 动画提供更好的性能和更流畅的动画
+- **无全局禁用**：与 v2 的 Provider 不同`disableAnimation`道具，v3 中没有全局动画切换
+- **每个组件控制**：通过 CSS 或特定于组件的 props（如果可用）控制动画
+- **自定义动画**：使用标准 CSS`@keyframes`和自定义动画的过渡属性
+
+</section>
+
+<section id="step-4-replace-removed-hooks">
+
+### 第 4 步：更换拆下的挂钩
+
+HeroUI v2 提供了组件挂钩（例如`useSwitch`, `useInput`, `useCheckbox`等）和实用程序挂钩，例如`useDisclosure`。 HeroUI v3 删除了大多数组件挂钩，转而使用复合组件，并替换了`useDisclosure`和`useOverlayState`.
+
+查看综合[Hooks 迁移指南](/docs/react/migration/hooks)为了：
+- 组件挂钩移除并迁移到复合组件
+- `useDisclosure` → `useOverlayState`迁移
+- 迁移策略和示例
+
+</section>
+
+<section id="step-5-update-component-imports">
+
+### 第 5 步：更新组件导入
+
+所有组件现在都从单个包导入：
+
+**v2 导入：**
+
+```tsx
+// Individual packages (if used)
+import {Button} from "@heroui/button";
+import {Card} from "@heroui/card";
+
+// Or from main package
+import {Button, Card} from "@heroui/react";
+```
+
+**v3 导入：**
+
+```tsx
+// All components from single package
+import {Button, Card} from "@heroui/react";
+```
+
+#### TypeScript 注意事项
+
+如果您使用 TypeScript，请注意 v3 中的类型更改：
+
+```tsx
+// Import types alongside components
+import {Button, type ButtonProps} from "@heroui/react";
+
+// Compound component types are properly exported
+import {Checkbox, type CheckboxProps} from "@heroui/react";
+
+// Type names may have changed - check component documentation
+type MyButtonProps = ButtonProps & {
+  customProp?: string;
+};
+```
+
+**常见类型变化：**
+- 组件 prop 接口可能有不同的名称或属性
+- 复合零部件有自己的类型导出
+- 更新了 Ref 类型以匹配 React 19 模式
+
+</section>
+
+<section id="step-6-component-migration">
+
+### 第6步：组件迁移
+
+使用[组件迁移参考](/docs/react/migration#component-migration-reference)表查找每个组件的迁移指南。根据组件的特定指南迁移组件。
+
+**要点：**
+- 根据需要查看各个组件迁移指南
+- 迁移组件 API、props 和结构
+- 更新复合组件模式（复选框、单选、开关、卡片、模态等）
+- 更新组组件（ButtonGroup、CheckboxGroup、RadioGroup）
+- 处理已移除组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）——替换为原生 HTML 或自定义实现
+- 处理进行中/计划中的组件 - 替换为 HTML 元素，直到 v3 组件可用
+
+</section>
+
+<section id="step-7-update-custom-theme-overrides">
+
+### 第 7 步：更新自定义主题覆盖
+
+如果您在 v2 中有自定义主题覆盖，则需要针对 v3 的基于 CSS 的主题系统更新它们。
+
+**v2 主题定制：**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [
+    heroui({
+      themes: {
+        light: {
+          colors: {
+            primary: {
+              // custom colors
+            },
+          },
+        },
+      },
+    }),
+  ],
+};
+```
+
+**v3 主题定制：**
+
+v3 使用 CSS 变量。在 CSS 中覆盖它们：
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+
+:root {
+  --color-primary: /* your color */;
+  /* other CSS variables */
+}
+```
+
+检查[主题文档](/docs/react/getting-started/handbook/theming)获取可用的 CSS 变量。
+
+这是在继续样式迁移之前暂停并验证组件功能的好时机。
+
+</section>
+
+<section id="step-8-hooks-migration">
+
+### 第8步：Hooks迁移
+
+组件迁移完成后，确保所有钩子都已迁移：
+
+1. **替换组件钩子**：将 `useSwitch`、`useInput`、`useCheckbox` 等替换为复合组件用法
+2. **迁移 useDisclosure**：将 `useDisclosure` 替换为 `useOverlayState` 以管理浮层状态
+3. **参考 Hooks 指南**：参阅 [Hooks 迁移指南](/docs/react/migration/hooks) 获取详细步骤与示例
+
+</section>
+
+<section id="step-9-styling-migration">
+
+### 第 9 步：样式迁移
+
+挂钩迁移完成后，继续进行样式更改。这是一个单独的步骤，以确保在解决视觉更改之前验证组件功能。
+
+**样式迁移指南：**
+
+查看综合[样式迁移指南](/docs/react/migration/styling)为了：
+
+- 实用程序类更改（`text-tiny` → `text-xs`, `rounded-small` → `rounded-sm`， ETC。）
+- 颜色标记更新（`bg-primary` → `bg-accent`, `bg-content1` → `bg-surface`， ETC。）
+- 组件样式差异（大小、间距、边框半径）
+- CSS 变量更改
+- 视觉差异和对齐变化
+
+**主要样式变化：**
+
+- **实用程序类**：自定义实用程序替换为标准 Tailwind 类
+- **颜色标记**：`primary` → `accent`, `secondary`删除,`content1-4` → `surface`/`overlay`
+- **编号比例**：颜色比例如`primary-50`, `primary-100`已删除
+- **边框半径**：默认值已更改（v3 中更小）
+- **组件样式**：更新了默认大小、填充和间距
+
+**迁移清单：**
+
+- 审查[样式迁移指南](/docs/react/migration/styling)
+- 更新实用程序类（`text-tiny` → `text-xs`， ETC。）
+- 更新颜色标记（`bg-primary` → `bg-accent`， ETC。）
+- 更新内容颜色（`bg-content1` → `bg-surface`或者`bg-overlay`)
+- 更新编号色阶（`bg-primary-50` → `bg-accent-soft`)
+- 检查组件样式更改（大小、间距、边框半径）
+- 测试视觉外观并根据需要进行调整
+
+</section>
+
+<section id="step-10-testing">
+
+### 第10步：测试
+
+迁移后，彻底测试您的应用程序：
+
+1. **视觉测试**：检查所有组件正确渲染
+2. **功能**：测试所有交互和行为
+3. **辅助功能**：验证键盘导航和屏幕阅读器支持
+4. **响应式设计**：在不同的屏幕尺寸上进行测试
+5. **性能**：检查包大小和运行时性能
+
+</section>
+
+## 迁移清单
+
+使用此清单来跟踪您的完整迁移进度：
+
+### 依赖关系
+- 将 React 更新至 v19+
+- 将 HeroUI 包更新到 v3（组件迁移后）
+- 删除Framer Motion
+- 将 Tailwind CSS 更新至 v4
+
+### 配置
+- 消除`heroui()`Tailwind 配置中的插件
+- 更新 CSS 导入
+- 消除`hero.ts`文件（如果存在）
+
+### 应用程序代码-组件迁移
+- 消除`HeroUIProvider`包装纸
+- 处理提供者道具迁移（路由器、区域设置、动画）
+- 将所有组件导入更新为`@heroui/react`
+- 迁移重命名组件（Divider → Separator、Autocomplete → Combobox、NumberInput → NumberField）
+- 更新复合组件模式（复选框、单选、开关、卡片、模态等）
+- 更新组组件（ButtonGroup、CheckboxGroup、RadioGroup）
+- 更新 TypeScript 类型引用（如果使用组件类型）
+- 处理已移除组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）——替换为原生 HTML 或自定义实现
+- 处理进行中/计划中的组件 - 替换为 HTML 元素，直到 v3 组件可用
+- 考虑使用`asChild`灵活构图的属性
+- **在进行钩子迁移之前验证组件功能**
+
+### 应用程序代码-Hooks迁移
+- 审查[Hooks 迁移指南](/docs/react/migration/hooks)
+- 更换组件挂钩（`useSwitch`, `useInput`, `useCheckbox`等）与复合组件
+- 代替`useDisclosure`和`useOverlayState`用于覆盖状态管理
+- 根据迁移指南更新所有钩子用法
+- **在继续样式迁移之前验证钩子迁移**
+
+### 应用程序代码 - 样式迁移
+- 审查[样式迁移指南](/docs/react/migration/styling)
+- 更新实用程序类（`text-tiny` → `text-xs`, `rounded-small` → `rounded-sm`， ETC。）
+- 更新颜色标记（`bg-primary` → `bg-accent`, `bg-secondary` → `bg-default`， ETC。）
+- 更新内容颜色（`bg-content1` → `bg-surface`或者`bg-overlay`)
+- 更新编号色阶（`bg-primary-50` → `bg-accent-soft`， ETC。）
+- 更新转换实用程序（`.transition-background` → `transition-colors`， ETC。）
+- 检查组件样式更改（大小、间距、边框半径）
+- 将自定义主题覆盖更新为 CSS 变量
+- 测试视觉外观并根据需要进行调整
+
+### 测试
+- 视觉回归测试
+- 功能测试
+- 辅助功能测试
+- 性能测试
+
+## 下一步
+
+完成完整迁移后：
+
+1. 回顾[v3 组件文档](/docs/react/components)
+2. 探索 v3 中可用的新组件
+3. 查看[样式指南](/docs/react/getting-started/handbook/styling)
+4. 了解[构图模式](/docs/react/getting-started/handbook/composition)
diff --git a/apps/docs/content/docs/cn/react/migration/(workflows)/incremental-migration.mdx b/apps/docs/content/docs/cn/react/migration/(workflows)/incremental-migration.mdx
new file mode 100644
index 0000000..dd00c25
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/(workflows)/incremental-migration.mdx
@@ -0,0 +1,292 @@
+---
+title: 增量迁移
+description: 将 HeroUI v2 增量迁移到 v3 同时保持两个版本并行工作的分步指南
+---
+
+## 概述
+
+通过共存的增量迁移，您可以逐个组件地从 HeroUI v2 迁移到 v3，同时保持项目在整个迁移过程中正常运行。此方法使用特殊的设置策略来允许 v2 和 v3 组件并行工作。
+
+### AI 助理资源
+
+AI 助手可以协助迁移。你可以使用 [迁移 MCP 服务器](/docs/react/migration/mcp-server) 获取工具与提示词，使用 [迁移 Agent Skills](/docs/react/migration/agent-skills) 获取基于技能的知识，或使用 [用于迁移的 AGENTS.md](/docs/react/migration/agents-md) 将迁移文档下载到项目中。
+
+### 限制和注意事项
+
+在选择此方法之前，请注意：
+
+- **捆绑包大小**：迁移期间将包含两个版本，从而增加捆绑包大小
+- **样式冲突**：v2 和 v3 样式可能会冲突；彻底测试
+- **类型冲突**：如果两个版本都导入到同一个文件中，TypeScript 可能会显示冲突
+- **提供商**：v2 需要`HeroUIProvider`，v3 没有 - 您可能需要条件提供者包装
+- **React 版本**：v3 需要 React 19+，v2 支持 React 18+ - 确保安装 React 19
+- **设置复杂性**：与完全迁移相比，需要更复杂的初始设置
+
+### 没有 v3 对应组件的组件
+
+由于 v2 和 v3 可以共存，因此没有 v3 对应项的 v2 组件可以保留在您的项目中。这些组件将在迁移期间继续工作：
+
+- **Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**
+
+您无需替换它们即可完成迁移。如果您希望删除它们并使用本机 HTML 或手动实现，您可以要求您的代理帮助使用[组件迁移参考](/docs/react/migration#component-migration-reference)指南。
+
+## 策略选择
+
+根据您当前导入 v2 组件的方式选择策略：
+
+- **使用`@heroui/react`**：使用策略 A（pnpm 别名）
+- **使用组件包** (`@heroui/button`, `@heroui/card`等）：使用策略B（组件包）
+
+## 策略 A：使用 pnpm 别名
+
+该策略使用 pnpm 包别名以不同的名称安装 v3 包，从而允许两个版本共存。
+
+### 设置
+
+1. 使用别名安装 v3 软件包：
+
+```json
+{
+  "dependencies": {
+    "@heroui/react": "2.8.6",
+    "@heroui/theme": "2.4.24",
+    "@heroui-v3/react": "npm:@heroui/react@latest",
+    "@heroui-v3/styles": "npm:@heroui/styles@latest"
+  }
+}
+```
+
+2. 从以下位置导入 v2 组件`@heroui/react`:
+
+```tsx
+import {Button} from "@heroui/react"; // v2
+```
+
+3. 从以下位置导入 v3 组件`@heroui-v3/react`:
+
+```tsx
+import {Button} from "@heroui-v3/react"; // v3
+```
+
+### 迁移过程
+
+1. **一次迁移一个组件：**
+   - 更新导入以使用`@heroui-v3/react`
+   - 将组件代码更新为 v3 API
+   - 测试迁移的组件
+   - 验证样式看起来正确
+   - 对于没有 v3 对位的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**），请将它们保留在原处，它们在共存期间仍会继续工作。
+
+2. **继续，直到所有组件均已迁移**
+   - 跟踪哪些组件已迁移
+   - 彻底测试每个迁移的组件
+   - 如果您想稍后删除 v2 删除的组件，请使用[组件迁移参考](/docs/react/migration#component-migration-reference)指南并要求您的代理帮助将其替换为原生 HTML 或手动实施。
+
+3. **迁移所有组件后，切换到仅 v3：**
+   - 删除 v2 依赖项（`@heroui/react`, `@heroui/theme`)
+   - 删除别名
+   - 将所有导入更新为`@heroui/react`（消除`-v3`后缀）
+   - 完成样式迁移
+
+### 注意事项
+
+- 两个 CSS 系统都将被加载（v2 通过 Tailwind 插件，v3 通过 CSS 导入）
+- 您暂时需要两个 Tailwind 配置
+- 迁移过程中捆绑包大小会变大
+- 可能会发生一些样式冲突
+
+## 策略 B：使用组件包
+
+该策略将 v2 的特定于组件的包与 v3 的统一包一起使用。
+
+### 设置
+
+1. 安装v3主包和v2组件包：
+
+```json
+{
+  "dependencies": {
+    "@heroui/react": "latest", // v3
+    "@heroui/styles": "latest", // v3
+    "@heroui/button": "2.8.6", // v2
+    "@heroui/card": "2.8.6", // v2
+    // ... other v2 component packages as needed
+  }
+}
+```
+
+2. 从以下位置导入 v3 组件`@heroui/react`:
+
+```tsx
+import {Button} from "@heroui/react"; // v3
+```
+
+3. 从组件包中导入 v2 组件：
+
+```tsx
+import {Card} from "@heroui/card"; // v2
+```
+
+### 迁移过程
+
+1. **安装 v3 软件包** (`@heroui/react`, `@heroui/styles`)
+2. **为尚未迁移的组件安装 v2 组件包**
+3. **一次迁移一个组件：**
+   - 从依赖中删除 v2 组件包
+   - 更新导入以使用`@heroui/react`(v3)
+   - 将组件代码更新为 v3 API
+   - 测试迁移的组件
+   - 对于没有 v3 对位的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**），请将它们保留在原处，它们在共存期间仍会继续工作。
+4. **继续，直到所有组件均已迁移**
+   - 如果您想稍后删除 v2 删除的组件，请使用[组件迁移参考](/docs/react/migration#component-migration-reference)指南并要求您的代理帮助将其替换为原生 HTML 或手动实施。
+5. **删除剩余的 v2 组件包**
+6. **完成样式迁移**
+
+### 注意事项
+
+- 仅当您的项目使用特定于组件的包时才有效
+- 需要管理多个包依赖关系
+- v3 没有组件包，因此这是一种单向迁移路径
+
+## 共存的 CSS 配置
+
+在共存期间，您将需要两个 CSS 系统：
+
+```css
+/* globals.css */
+@import "tailwindcss";
+
+/* v2 styles via Tailwind plugin */
+/* (configured in tailwind.config.js) */
+
+/* v3 styles */
+@import "@heroui/styles";
+```
+
+<Callout type="warning">
+  **重要提示：** 导入顺序很重要：先导入 `tailwindcss`，再导入 `@heroui/styles`。
+</Callout>
+
+## Tailwind配置
+
+您暂时需要两个 Tailwind 配置：
+
+**v2 配置（tailwind.config.js）：**
+
+```js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [heroui()],
+  // ... other config
+};
+```
+
+**v3 配置：** 不需要插件，但确保安装 Tailwind v4。
+
+## 组件迁移
+
+对于您迁移的每个组件：
+
+1. **查看组件迁移指南**
+   - 使用[组件迁移参考](/docs/react/migration#component-migration-reference)表
+   - 检查特定于组件的迁移指南
+
+2. **更新导入**
+   - 策略A：改变`@heroui/react` → `@heroui-v3/react`
+   - 策略 B：更改组件包 →`@heroui/react`
+
+3. **更新组件代码**
+   - 遵循组件迁移指南
+   - 更新 props、组件结构和 API 调用
+   - 如果需要，用复合组件替换挂钩
+
+4. **测试迁移的组件**
+   - 验证组件正确渲染
+   - 测试功能和交互
+   - 检查样式冲突
+   - 确保 v2 组件的样式仍然正确
+
+5. **文档迁移**
+   - 跟踪哪些组件已迁移
+   - 注意任何问题或疑虑
+
+## CSS 冲突处理
+
+共存期间，v2 和 v3 CSS 系统都会被加载。监控冲突：
+
+1. **注意样式不一致**
+   - 检查v2和v3样式是否冲突
+   - 验证两个 CSS 导入均存在且顺序正确
+
+2. **指导冲突解决**
+   - 确保 CSS 导入顺序：`tailwindcss`首先，然后`@heroui/styles`
+   - 检查 Tailwind 配置是否配置了 v2 插件
+   - 验证 v3 CSS 是否正确导入
+
+3. **每次迁移后测试样式**
+   - 验证迁移的组件看起来正确
+   - 检查是否有意外的样式覆盖
+   - 确保 v2 组件的样式仍然正确
+
+## 完成迁移
+
+迁移所有组件后：
+
+1. **删除 v2 依赖项：**
+   - 消除`@heroui/react`和`@heroui/theme`（策略A）
+   - 全部删除`@heroui/*`组件包（策略B）
+   - 删除别名（策略 A）
+   - 如果你将已移除的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）保留在项目中，有两个选择：(1) 在删除 v2 依赖前按迁移指南替换它们，或 (2) 暂时保留 v2 依赖，直到你准备好替换。你也可以请代理依据指南协助移除或替换。
+
+2. **更新所有导入：**
+   - 改变`@heroui-v3/react` → `@heroui/react`（策略A）
+   - 更改组件包导入 →`@heroui/react`（策略B）
+
+3. **更新CSS：**
+   - 从配置中删除 v2 Tailwind 插件
+   - 仅保留`@import "@heroui/styles";`
+
+4. **完成样式迁移：**
+   - 遵循[样式迁移指南](/docs/react/migration/styling)
+   - 更新实用程序类、颜色标记等。
+
+## 共存迁移清单
+
+使用此清单来跟踪增量迁移进度：
+
+### 初始设置
+- 选择策略（A：别名或B：组件包）
+- 安装 v3 软件包（使用别名或直接安装）
+- 为两个版本配置 CSS
+- 确保已安装 React 19+
+- 临时设置两个 Tailwind 配置
+
+### 组件迁移（对每个组件重复）
+- 查看组件迁移指南
+- 更新导入（策略 A 或 B）
+- 将组件代码更新为 v3 API
+- 测试迁移的组件
+- 检查样式冲突
+- 记录迁移进度
+- 识别已移除的 v2 组件（**Code**、**Image**、**Navbar**、**Ripple**、**Snippet**、**Spacer**、**User**）——保留在原处或按指南替换
+
+### 完成
+- 迁移所有组件
+- 可选：在删除 v2 deps 之前使用迁移指南替换已删除的组件，或者仅在替换所有已删除的组件后删除 v2 deps
+- 删除 v2 依赖项
+- 删除别名（策略 A）
+- 将所有导入更新为仅限 v3
+- 删除 v2 Tailwind 插件
+- 将 CSS 更新为仅限 v3
+- 完成样式迁移
+- 测试整个应用程序
+
+## 下一步
+
+完成增量迁移后：
+
+1. 回顾[v3 组件文档](/docs/react/components)
+2. 探索 v3 中可用的新组件
+3. 查看[样式指南](/docs/react/getting-started/handbook/styling)
+4. 了解[构图模式](/docs/react/getting-started/handbook/composition)
diff --git a/apps/docs/content/docs/cn/react/migration/agent-index.mdx b/apps/docs/content/docs/cn/react/migration/agent-index.mdx
new file mode 100644
index 0000000..7fad8e8
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/agent-index.mdx
@@ -0,0 +1,20 @@
+---
+title: 迁移（面向 AI 助手）
+description: 供 AI 助手协助将 HeroUI v2 迁移到 v3 时使用的入口
+index: false
+---
+
+面向 AI 助手：在协助将 HeroUI v2 → v3 进行迁移时，请将本文档作为入口。
+
+## 入口
+
+请选择一种迁移策略：
+
+- **完整迁移**（迁移过程中项目将无法正常运行）→ 阅读 `(workflows)/agent-guide-full.mdx`。
+- **渐进式迁移**（v2 与 v3 并存）→ 阅读 `(workflows)/agent-guide-incremental.mdx`。
+
+## 本套文档中的参考资料
+
+- **通用指南：** `hooks.mdx`、`styling.mdx`。
+- 上述工作流程指南已经内嵌了「主要变更」、「关键 API 变更」、组件参考表以及「新增组件」等内容。
+- **各组件指南：** `(components)/<component>.mdx`（例如 `(components)/button.mdx`、`(components)/select.mdx`）。请通过工作流程指南中的组件参考表来定位对应的文件。
diff --git a/apps/docs/content/docs/cn/react/migration/hooks.mdx b/apps/docs/content/docs/cn/react/migration/hooks.mdx
new file mode 100644
index 0000000..0d1379a
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/hooks.mdx
@@ -0,0 +1,282 @@
+---
+title: Hooks
+description: HeroUI Hooks 从 v2 到 v3 的迁移指南
+---
+
+<Callout type="info">
+  完整的 API 参考请参阅 [v3 组件文档](/docs/components-list)。本指南重点介绍如何从 HeroUI v2 迁移 Hooks。
+</Callout>
+
+## 概述
+
+HeroUI v3 移除了 v2 中存在的大多数组件 Hooks，转而使用复合组件，并新增了一个用于管理浮层状态的 Hook。本指南涵盖：
+
+- 组件 Hooks 的移除（`useSwitch`、`useInput`、`useCheckbox` 等）
+- `useDisclosure` → `useOverlayState` 的迁移
+- 迁移策略与示例
+
+## 组件 Hooks 的移除
+
+HeroUI v2 提供了一系列组件 Hooks（例如 `useSwitch`、`useInput`、`useCheckbox` 等），它们返回一组 prop getter（`getBaseProps`、`getWrapperProps`、`getThumbProps` 等），让用户在无法直接修改内部子组件的情况下也能自定义组件结构。HeroUI v3 通过复合组件解决了这个问题，从而无需再依赖这些 Hooks。
+
+### 为什么 v2 中存在这些 Hooks
+
+在 v2 中，组件具有固定的内部结构。为了自定义这些结构，用户需要使用提供 prop getter 的 Hooks。例如，`useSwitch` 返回 `getBaseProps()`、`getWrapperProps()`、`getThumbProps()` 等，用户可以将其展开到自定义元素上，从而构建自己的 Switch 结构。
+
+### v3 的解决方案：复合组件
+
+v3 采用了复合组件模式，让你可以直接访问组件的各个部分。你不再需要使用带有 prop getter 的 Hooks，而是可以直接通过 `Switch.Control`、`Switch.Thumb`、`Checkbox.Control`、`Checkbox.Indicator` 等子组件进行组合。
+
+### 迁移策略
+
+1. **识别 Hook 用法**：在你的代码库中搜索来自 `@heroui/react` 的导入，找出包含 Hook 名称（`useSwitch`、`useInput`、`useCheckbox`、`useRadio` 等）的引用。
+2. **替换为复合组件**：使用复合组件模式，替代带有 prop getter 的 Hooks。
+3. **保留原有结构**：迁移时，尽量保持与原 Hook 实现一致的组件结构。例如：
+   - 如果你之前用 `useSwitch` 创建了一个 **不带** thumb 的 Switch，那么在 v3 中也不要添加 `Switch.Thumb`
+   - 如果你之前用 `useCheckbox` 创建了一个 **不带** indicator 的 Checkbox，那么在 v3 中也不要添加 `Checkbox.Indicator`
+   - 只引入原本基于 Hook 的实现中实际用到的子组件
+4. **参考各组件指南**：查看各个组件的迁移指南，获取具体示例。
+
+### 主要差异
+
+- **v2**：Hooks 提供 prop getter，用于自定义固定的组件结构
+- **v3**：复合组件允许直接组合组件的各个部分
+
+### 保留结构示例
+
+**v2：不带 thumb 的 Switch**
+```tsx
+import { useSwitch } from "@heroui/react";
+
+function CustomSwitch() {
+  const { getBaseProps } = useSwitch();
+  
+  return (
+    <div {...getBaseProps()}>
+      {/* No thumb element */}
+    </div>
+  );
+}
+```
+
+**v3：等效结构**
+```tsx
+import { Switch } from "@heroui/react";
+
+function CustomSwitch() {
+  return (
+    <Switch.Control>
+      {/* No Switch.Thumb - preserving the original structure */}
+    </Switch.Control>
+  );
+}
+```
+
+有关具体组件的详细迁移示例，请参阅各个组件的迁移指南。
+
+## useDisclosure → useOverlayState
+
+v2 中的 `useDisclosure` 钩子在 v3 中已替换为 `useOverlayState`。该钩子用于管理 Modal、Popover 等浮层组件的打开/关闭状态。
+
+### v2：useDisclosure
+
+**API：**
+```tsx
+const {isOpen, onOpen, onClose, onOpenChange, isControlled, getButtonProps, getDisclosureProps} = useDisclosure({
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onClose?(): void;
+  onOpen?(): void;
+  onChange?(isOpen: boolean | undefined): void;
+  id?: string;
+});
+```
+
+**示例：**
+```tsx
+import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Modal</Button>
+      <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+        <ModalContent>
+          <ModalHeader>Title</ModalHeader>
+          <ModalBody>Content</ModalBody>
+          <ModalFooter>
+            <Button onPress={onOpenChange}>Close</Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+### v3：useOverlayState
+
+**API：**
+```tsx
+const state = useOverlayState({
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (isOpen: boolean) => void;
+});
+
+// Returns:
+// {
+//   isOpen: boolean;
+//   open(): void;
+//   close(): void;
+//   toggle(): void;
+//   setOpen(isOpen: boolean): void;
+// }
+```
+
+**示例：**
+```tsx
+import { Modal, Button, useOverlayState } from "@heroui/react";
+
+export default function App() {
+  const state = useOverlayState();
+
+  return (
+    <Modal>
+      <Button onPress={state.open}>Open Modal</Button>
+      <Modal.Container isOpen={state.isOpen} onOpenChange={state.setOpen}>
+        <Modal.Dialog>
+          {({close}) => (
+            <>
+              <Modal.Header>
+                <Modal.Heading>Title</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>Content</Modal.Body>
+              <Modal.Footer>
+                <Button onPress={close}>Close</Button>
+              </Modal.Footer>
+            </>
+          )}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal>
+  );
+}
+```
+
+### 迁移指南
+
+#### 基本迁移
+
+**v2：**
+```tsx
+const {isOpen, onOpen, onClose, onOpenChange} = useDisclosure();
+```
+
+**v3：**
+```tsx
+const state = useOverlayState();
+// Use state.open(), state.close(), state.toggle(), state.setOpen(boolean)
+```
+
+#### 受控状态
+
+**v2：**
+```tsx
+const {isOpen, onOpenChange} = useDisclosure({
+  isOpen: controlledIsOpen,
+  onChange: (isOpen) => setControlledIsOpen(isOpen)
+});
+```
+
+**v3：**
+```tsx
+const state = useOverlayState({
+  isOpen: controlledIsOpen,
+  onOpenChange: setControlledIsOpen
+});
+```
+
+#### 非受控状态
+
+**v2：**
+```tsx
+const {isOpen, onOpen, onClose} = useDisclosure({
+  defaultOpen: false
+});
+```
+
+**v3：**
+```tsx
+const state = useOverlayState({
+  defaultOpen: false
+});
+// Use state.open(), state.close(), state.toggle()
+```
+
+### API 差异
+
+| v2（useDisclosure） | v3（useOverlayState） | 说明 |
+|-------------------|---------------------|-------|
+| `isOpen` | `isOpen` | 相同 |
+| `onOpen()` | `open()` | 方法重命名 |
+| `onClose()` | `close()` | 方法重命名 |
+| `onOpenChange()` | `toggle()` | 新增的切换方法 |
+| `onOpenChange`（prop） | `setOpen(boolean)` | API 不同 |
+| `isControlled` | - | 已移除（由内部处理） |
+| `getButtonProps()` | - | 已移除（改用复合组件） |
+| `getDisclosureProps()` | - | 已移除（改用复合组件） |
+
+### useOverlayState 的优势
+
+- **更简洁的 API**：使用专用方法（`open()`、`close()`、`toggle()`），而非回调
+- **更简单的状态管理**：在受控与非受控两种模式下都能无缝工作
+- **更完善的 TypeScript 支持**：改进了类型推断和自动补全
+- **与 React Aria 保持一致**：与 React Aria Components 的模式相符
+
+### 替代方案：useState
+
+对于简单的场景，你也可以直接使用 React 的 `useState`：
+
+```tsx
+import { useState } from "react";
+import { Modal, Button } from "@heroui/react";
+
+export default function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Modal>
+      <Button onPress={() => setIsOpen(true)}>Open</Button>
+      <Modal.Container isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Modal.Dialog>
+          {/* content */}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal>
+  );
+}
+```
+
+不过，`useOverlayState` 为常见操作提供了更简洁的 API 和专用方法。
+
+## 已移除的 Hooks
+
+v2 中的以下 Hooks 在 v3 中已被移除：
+
+- **useDraggable**：已移除
+- **useClipboard**：已移除
+- **usePagination**：已移除
+- **useToast**：已移除
+
+## 总结
+
+- **组件 Hooks**（`useSwitch`、`useInput` 等）→ 改用 **复合组件**
+- **useDisclosure** → 改用 **useOverlayState** 来管理浮层状态
+- **useOverlayState** 提供了更简洁的 API，包含 `open()`、`close()`、`toggle()` 与 `setOpen()` 方法
+- **已移除的 Hooks**：`useDraggable`、`useClipboard`、`usePagination`、`useToast` 不再可用
+- 对于简单的场景可以直接使用 `useState`，但 `useOverlayState` 在使用体验上更佳
+
+有关具体组件的 Hooks 迁移示例，请参阅各个组件的迁移指南。
diff --git a/apps/docs/content/docs/cn/react/migration/index.mdx b/apps/docs/content/docs/cn/react/migration/index.mdx
new file mode 100644
index 0000000..006d9b7
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/index.mdx
@@ -0,0 +1,198 @@
+---
+title: 迁移
+description: 将 HeroUI v2 应用迁移到 v3 的完整指南
+index: true
+---
+
+## 面向 AI 助手
+
+以下是 AI 助手获取迁移文档的三种方式。***我们推荐使用 HeroUI Migration MCP 服务器***，并充分利用其 prompt 与工具，不过其它方式也都能为 agent 提供完整的文档。
+
+| 对比项 | MCP Server | Agent Skills | AGENTS.md |
+|---------|-----------|--------------|-----------|
+| **数据来源** | 远程端点 | 远程端点 | 本地文件 |
+| **访问方式** | MCP 工具 | 脚本文件 | 读取本地文件 |
+| **配置方式** | MCP 配置 | 安装命令 | `heroui-cli` 命令 |
+| **更新** | 实时 | 实时 | 手动 |
+| **离线** | ❌ | ❌ | ✅ |
+| **工具** | MCP 工具 + prompt | 脚本 | ❌ |
+| **指南** | [MCP Server →](/docs/react/migration/mcp-server) | [Agent Skills →](/docs/react/migration/agent-skills) | [AGENTS.md →](/docs/react/migration/agents-md) |
+
+## 主要变化
+
+<section id="major-changes">
+
+- **依赖项**：将 React 升级到 v19+、HeroUI 包升级到 v3、Tailwind CSS 升级到 v4，并移除 Framer Motion
+- **无需 Provider**：v3 不再需要 `HeroUIProvider`
+- **组件 API 更新**：许多组件改用 React Aria Components 模式
+- **复合组件**：全新的复合组件模式带来了更好的定制能力。详情请参阅各组件的迁移指南。
+- **已移除的 Hooks**：v2 中的组件 Hooks（如 `useSwitch`、`useInput`）已被移除——请改用复合组件。`useDisclosure` 已被替换为 `useOverlayState`。详情请参阅 [Hooks 迁移指南](/docs/react/migration/hooks)。
+- **配置变更**：从 Tailwind 配置中移除 `heroui()` 插件，更新 CSS 导入，并删除 `hero.ts` 文件
+- **条目标识**：集合类组件（Dropdown、ListBox、Select、Accordion 等）在 v3 中改用 `id` 和 `textValue`；列表本身仍需保留 React 的 `key`。
+
+</section>
+
+### 条目标识与无障碍（key、id、textValue）
+
+在 v2 中，集合类组件（Dropdown、ListBox、Select、Accordion 等）使用 **React 的 `key`** 作为条目标识。同一个值既驱动 React 的列表协调，又承担组件的选中/展开状态。在使用 React Aria Components 的 v3 中，这两种职责被拆分开：
+
+- **`id`** — v3 在每个条目上使用显式的 **`id`** 属性来表示选中状态、焦点以及回调（例如 `selectedKeys`、`expandedKeys`、`onSelectionChange`）。请使用与你在 v2 中给 `key` 设置的相同（或等效）的值，这样状态和回调仍能正确指向对应的条目。
+- **`textValue`** — 当条目的可见内容不是纯文本时（例如使用了 `Label`、图标或 `Description`），v3 需要在条目上提供 **`textValue`**。它用于屏幕阅读器播报和键入快速定位（type-ahead）。
+- **`key`** — **继续在列表项上使用 React 的 `key`**。它仍然是 React 列表协调所必需的，且与 `id` 相互独立。
+
+迁移时：为 v3 的 API 添加 `id`（必要时再加上 `textValue`），同时保留供 React 使用的 `key`。
+
+## 迁移策略
+
+如果不做特殊设置，HeroUI v2 与 v3 不能在同一个项目中共存。你可以选择以下两种迁移方式：
+
+### 一次性完整迁移
+
+**适用场景：** 能够集中投入时间、一次性完成迁移的项目。
+
+**工作方式：**
+- 先迁移所有组件代码（此阶段项目将无法正常运行）
+- 将依赖项切换到 v3
+- 完成样式迁移
+
+**优点：**
+- 配置更简单——无需复杂的共存配置
+- 切换更干净——同一时间只有一个版本处于激活状态
+- 由 Migration MCP 的 prompt 提供支持
+
+**缺点：**
+- 项目在迁移期间无法正常运行
+- 必须在切换依赖之前完成所有组件的迁移
+
+**开始迁移：** [完整迁移指南](/docs/react/migration/full-migration)
+
+### 渐进式迁移
+
+**适用场景：** 需要在迁移过程中保持可用的项目、希望分阶段逐步迁移的团队，以及按功能逐个迁移的大型代码库。
+
+**工作方式：**
+- 通过 pnpm 别名或组件包来设置共存
+- 在保持项目可用的前提下，逐个迁移组件
+- 完成迁移后再移除 v2 依赖项
+
+**优点：**
+- 项目在迁移期间始终可用
+- 可以分阶段、按需逐步推进
+- 可以将 v3 组件与 v2 并存测试
+
+**缺点：**
+- 初始配置更为复杂
+- 可能出现样式冲突
+- 需要同时管理两个版本
+
+**开始迁移：** [渐进式迁移指南](/docs/react/migration/incremental-migration)
+
+## 组件迁移参考
+
+<section id="step-6-component-migration-reference">
+
+可以通过下表快速查找每个组件的迁移指南。点击「迁移指南」列中的链接，即可跳转到对应的详细迁移说明。
+
+<Callout>
+  **组件开发状态**：标有 🔄 进行中或 📋 计划中的组件仍在开发中。可以查看[路线图](https://herouiv3.featurebase.app/roadmap)了解任务状态。这些组件的迁移指南将在开发完成后提供。
+</Callout>
+
+| v2 组件 | v3 组件 | 状态 | 迁移指南 |
+|-------------|--------------|--------|-----------------|
+| Accordion | Accordion | ✅ 可用 | [查看指南 →](/docs/react/migration/accordion) |
+| Alert | Alert | ✅ 可用 | [查看指南 →](/docs/react/migration/alert) |
+| Autocomplete | ComboBox | ✅ 已重命名 | [查看指南 →](/docs/react/migration/autocomplete) |
+| Avatar | Avatar | ✅ 可用 | [查看指南 →](/docs/react/migration/avatar) |
+| Badge | Badge | ✅ 可用 | [查看指南 →](/docs/react/migration/badge) |
+| Breadcrumbs | Breadcrumbs | ✅ 可用 | [查看指南 →](/docs/react/migration/breadcrumbs) |
+| Button | Button | ✅ 可用 | [查看指南 →](/docs/react/migration/button) |
+| ButtonGroup | ButtonGroup | ✅ 可用 | [查看指南 →](/docs/react/migration/button-group) |
+| Calendar | Calendar | ✅ 可用 | [查看指南 →](/docs/react/migration/calendar) |
+| Card | Card | ✅ 可用 | [查看指南 →](/docs/react/migration/card) |
+| Checkbox | Checkbox | ✅ 可用 | [查看指南 →](/docs/react/migration/checkbox) |
+| CheckboxGroup | CheckboxGroup | ✅ 可用 | [查看指南 →](/docs/react/migration/checkbox-group) |
+| Chip | Chip | ✅ 可用 | [查看指南 →](/docs/react/migration/chip) |
+| Code | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/code) |
+| DateInput | DateField | ✅ 已重命名 | [查看指南 →](/docs/react/migration/dateinput) |
+| DatePicker | DatePicker | ✅ 可用 | [查看指南 →](/docs/react/migration/date-picker) |
+| DateRangePicker | DateRangePicker | ✅ 可用 | [查看指南 →](/docs/react/migration/date-range-picker) |
+| TimeInput | TimeField | ✅ 已重命名 | [查看指南 →](/docs/react/migration/timeinput) |
+| Divider | Separator | ✅ 已重命名 | [查看指南 →](/docs/react/migration/divider) |
+| Drawer | Drawer | ✅ 可用 | [查看指南 →](/docs/react/migration/drawer) |
+| Dropdown | Dropdown | ✅ 可用 | [查看指南 →](/docs/react/migration/dropdown) |
+| Form | Form | ✅ 可用 | [查看指南 →](/docs/react/migration/form) |
+| Image | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/image) |
+| Input | TextField、Input、InputGroup | ✅ 可用 | [查看指南 →](/docs/react/migration/input) |
+| InputOTP | InputOTP | ✅ 可用 | [查看指南 →](/docs/react/migration/input-otp) |
+| Kbd | Kbd | ✅ 可用 | [查看指南 →](/docs/react/migration/kbd) |
+| Link | Link | ✅ 可用 | [查看指南 →](/docs/react/migration/link) |
+| Listbox | ListBox | ✅ 可用 | [查看指南 →](/docs/react/migration/listbox) |
+| Modal | Modal | ✅ 可用 | [查看指南 →](/docs/react/migration/modal) |
+| Navbar | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/navbar) |
+| NumberInput | NumberField | ✅ 已重命名 | [查看指南 →](/docs/react/migration/numberinput) |
+| Pagination | Pagination | ✅ 可用 | [查看指南 →](/docs/react/migration/pagination) |
+| Popover | Popover | ✅ 可用 | [查看指南 →](/docs/react/migration/popover) |
+| Progress | ProgressBar | ✅ 已重命名 | [查看指南 →](/docs/react/migration/progress) |
+| CircularProgress | ProgressCircle | ✅ 已重命名 | [查看指南 →](/docs/react/migration/circular-progress) |
+| Radio | Radio | ✅ 可用 | [查看指南 →](/docs/react/migration/radio) |
+| RadioGroup | RadioGroup | ✅ 可用 | [查看指南 →](/docs/react/migration/radio-group) |
+| RangeCalendar | RangeCalendar | ✅ 可用 | [查看指南 →](/docs/react/migration/range-calendar) |
+| Ripple | ❌ | ❌ 已移除 | [参见 Button 的水波纹效果 →](/docs/react/components/button#adding-ripple-effect) |
+| ScrollShadow | ScrollShadow | ✅ 可用 | [查看指南 →](/docs/react/migration/scroll-shadow) |
+| Select | Select | ✅ 可用 | [查看指南 →](/docs/react/migration/select) |
+| Skeleton | Skeleton | ✅ 可用 | [查看指南 →](/docs/react/migration/skeleton) |
+| Slider | Slider | ✅ 可用 | [查看指南 →](/docs/react/migration/slider) |
+| Snippet | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/snippet) |
+| Spacer | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/spacer) |
+| Spinner | Spinner | ✅ 可用 | [查看指南 →](/docs/react/migration/spinner) |
+| Switch | Switch | ✅ 可用 | [查看指南 →](/docs/react/migration/switch) |
+| Table | Table | ✅ 可用 | [查看指南 →](/docs/react/migration/table) |
+| Tabs | Tabs | ✅ 可用 | [查看指南 →](/docs/react/migration/tabs) |
+| Toast | Toast | ✅ 可用 | [查看指南 →](/docs/react/migration/toast) |
+| Tooltip | Tooltip | ✅ 可用 | [查看指南 →](/docs/react/migration/tooltip) |
+| User | ❌ | ❌ 已移除 | [查看指南 →](/docs/react/migration/user) |
+
+</section>
+
+## v3 中新增的组件
+
+<section id="new-components-in-v3">
+
+v3 引入了一系列 v2 中尚未提供的全新组件：
+
+| 组件 | 用途 | 文档 |
+|-----------|---------|---------------|
+| TextField | 增强型文本输入框，支持 label 与 description | [查看文档 →](/docs/react/components/text-field) |
+| TextArea | 多行文本输入组件 | [查看文档 →](/docs/react/components/text-area) |
+| AlertDialog | 用于确认与提醒的模态对话框 | [查看文档 →](/docs/react/components/alert-dialog) |
+| Label | 无障碍的表单标签组件 | [查看文档 →](/docs/react/components/label) |
+| Description | 表单字段的辅助说明文本 | [查看文档 →](/docs/react/components/description) |
+| FieldError | 表单字段的错误信息显示 | [查看文档 →](/docs/react/components/field-error) |
+| Fieldset | 对相关表单字段进行分组 | [查看文档 →](/docs/react/components/fieldset) |
+| InputGroup | 将多个输入框组合在一起 | [查看文档 →](/docs/react/components/input-group) |
+| Surface | 带有层级样式的容器组件 | [查看文档 →](/docs/react/components/surface) |
+| Disclosure | 可展开 / 可折叠的内容区域 | [查看文档 →](/docs/react/components/disclosure) |
+| DisclosureGroup | 用于管理多个 Disclosure 区域的复合组件 | [查看文档 →](/docs/react/components/disclosure-group) |
+| SearchField | 带清除按钮与可选加载状态的搜索输入框 | [查看文档 →](/docs/react/components/search-field) |
+| DateField | 配合日历选择器的日期输入框 | [查看文档 →](/docs/react/components/date-field) |
+| TimeField | 时间输入组件 | [查看文档 →](/docs/react/components/time-field) |
+| Tag、TagGroup | 用于选择或展示的 Tag 与 TagGroup | [查看文档 →](/docs/react/components/tag-group) |
+| ColorPicker | 颜色选择（ColorArea、ColorField、ColorSlider、ColorSwatch、ColorSwatchPicker） | [查看文档 →](/docs/react/components/color-picker) |
+| CloseButton | 用于关闭或解除浮层的触发按钮 | [查看文档 →](/docs/react/components/close-button) |
+| ErrorMessage | 表单字段错误信息展示（基于 React Aria 集成） | [查看文档 →](/docs/react/components/error-message) |
+
+</section>
+
+## 其他迁移指南
+
+- **[Hooks 迁移指南](/docs/react/migration/hooks)**：将 Hooks 从 v2 迁移到 v3 的详细说明
+- **[样式迁移指南](/docs/react/migration/styling)**：更新工具类、颜色 token 与组件样式的综合指南
+
+## 获取帮助
+
+如果你在迁移过程中遇到问题：
+
+1. 查看 [v3 文档](/docs/react)
+2. 查阅具体组件的迁移指南
+3. 在 [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions) 中查找或提问
+4. 加入 [Discord 社区](https://discord.gg/9b6yyZKmH4)
diff --git a/apps/docs/content/docs/cn/react/migration/meta.json b/apps/docs/content/docs/cn/react/migration/meta.json
new file mode 100644
index 0000000..f1d20c1
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/meta.json
@@ -0,0 +1,70 @@
+{
+  "title": "迁移",
+  "description": "将 HeroUI v2 应用迁移到 v3 的完整指南",
+  "root": true,
+  "icon": "code-pull-request-arrow-right",
+  "pages": [
+    "---概述---",
+    "index",
+    "---面向 Agent 的迁移---",
+    "(migration-for-agents)/mcp-server",
+    "(migration-for-agents)/agent-skills",
+    "(migration-for-agents)/agents-md",
+    "---迁移流程---",
+    "(workflows)/full-migration",
+    "(workflows)/incremental-migration",
+    "---参考---",
+    "hooks",
+    "styling",
+    "---组件---",
+    "(components)/accordion",
+    "(components)/alert",
+    "(components)/autocomplete",
+    "(components)/avatar",
+    "(components)/badge",
+    "(components)/breadcrumbs",
+    "(components)/calendar",
+    "(components)/button",
+    "(components)/button-group",
+    "(components)/card",
+    "(components)/checkbox",
+    "(components)/checkbox-group",
+    "(components)/chip",
+    "(components)/code",
+    "(components)/date-picker",
+    "(components)/date-range-picker",
+    "(components)/divider",
+    "(components)/drawer",
+    "(components)/dropdown",
+    "(components)/form",
+    "(components)/image",
+    "(components)/input",
+    "(components)/input-otp",
+    "(components)/kbd",
+    "(components)/link",
+    "(components)/listbox",
+    "(components)/modal",
+    "(components)/navbar",
+    "(components)/numberinput",
+    "(components)/pagination",
+    "(components)/popover",
+    "(components)/progress",
+    "(components)/circular-progress",
+    "(components)/radio",
+    "(components)/range-calendar",
+    "(components)/radio-group",
+    "(components)/scroll-shadow",
+    "(components)/select",
+    "(components)/skeleton",
+    "(components)/slider",
+    "(components)/snippet",
+    "(components)/spacer",
+    "(components)/spinner",
+    "(components)/switch",
+    "(components)/table",
+    "(components)/tabs",
+    "(components)/toast",
+    "(components)/tooltip",
+    "(components)/user"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/react/migration/styling.mdx b/apps/docs/content/docs/cn/react/migration/styling.mdx
new file mode 100644
index 0000000..abf9fe3
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/migration/styling.mdx
@@ -0,0 +1,720 @@
+---
+title: 样式与主题
+description: 从 HeroUI v2 到 v3 的样式变更与主题系统迁移完整指南
+---
+
+<Callout type="info">
+  本指南涵盖了 HeroUI v2 与 v3 之间所有与样式相关的变更，包括工具类、组件样式、主题系统架构以及视觉差异。具体组件的 API 变更请参阅各个组件的迁移指南。
+</Callout>
+
+**注：** v3 已将 `classNames` 这一对象类型的 prop 替换为标准的 React `className` prop。所有组件现在都使用标准的 React `className` prop，而不再使用 v2 中的 `classNames` 对象属性。
+
+## 概述
+
+HeroUI v3 对样式系统进行了重大变更：
+
+- **CSS 优先架构**：以纯 CSS 文件取代 Tailwind 插件
+- **标准 Tailwind 工具类**：以标准 Tailwind 类取代自定义工具类
+- **CSS 变量**：全新的 CSS 变量命名与结构
+- **组件样式**：调整了默认尺寸、间距与视觉表现
+- **无需插件**：移除了对 Tailwind 插件配置的依赖
+- **颜色系统重构**：语义颜色被重新组织（`primary` → `accent`，移除 `secondary`，移除数字色阶）
+- **移除 Content 颜色**：`content1-4` 由 `surface` 与 `overlay` 体系替代
+
+## 快速参考
+
+### 工具类对照
+
+| v2 工具类 | v3 对应类 | 说明 |
+|-----------|--------------|-------|
+| `text-tiny` | `text-xs` | 字体大小：0.75rem → 0.75rem（相同） |
+| `text-small` | `text-sm` | 字体大小：0.875rem → 0.875rem（相同） |
+| `text-medium` | `text-base` | 字体大小：1rem → 1rem（相同） |
+| `text-large` | `text-lg` | 字体大小：1.125rem → 1.125rem（相同） |
+| `rounded-small` | `rounded-sm` | 圆角：8px → 4px（不同） |
+| `rounded-medium` | `rounded-md` | 圆角：12px → 6px（不同） |
+| `rounded-large` | `rounded-lg` | 圆角：14px → 8px（不同） |
+| `border-small` | `border` | 边框宽度：1px → 1px（使用标准 Tailwind） |
+| `border-medium` | `border-2` | 边框宽度：2px → 2px（使用标准 Tailwind） |
+| `border-large` | `border-[3px]` | 边框宽度：3px → 3px（使用任意值） |
+| `bg-content1` | `bg-surface` 或 `bg-overlay` | Content 颜色已移除，请改用 surface / overlay |
+| `bg-content2` | `bg-surface-secondary` | Content 颜色已移除，请改用 surface 层级 |
+| `bg-primary` | `bg-accent` | `primary` 已重命名为 `accent` |
+| `bg-secondary` | `bg-default` | `secondary` 颜色已移除，请改用 `default` |
+| `bg-primary-50` | `bg-accent-soft` | 数字色阶已移除 |
+| `bg-primary-100` | `bg-accent-soft` | 数字色阶已移除 |
+| `text-primary-600` | `text-accent` | 数字色阶已移除 |
+| `.transition-background` | 标准 CSS 过渡 | 已移除的工具类 |
+| `.transition-colors-opacity` | 标准 CSS 过渡 | 已移除的工具类 |
+
+## 工具类迁移
+
+### 文本工具类
+
+HeroUI v2 提供了一组自定义的文本尺寸工具类，并映射到 CSS 变量。v3 改用标准的 Tailwind 文本尺寸类。
+
+**v2 文本工具类：**
+
+```tsx
+// v2 - Custom utilities with CSS variables
+<div className="text-tiny">Tiny text</div>
+<div className="text-small">Small text</div>
+<div className="text-medium">Medium text</div>
+<div className="text-large">Large text</div>
+```
+
+**v3 文本工具类：**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="text-xs">Tiny text</div>
+<div className="text-sm">Small text</div>
+<div className="text-base">Medium text</div>
+<div className="text-lg">Large text</div>
+```
+
+**对照详情：**
+
+| v2 类 | 字体大小 | 行高 | v3 类 | 字体大小 | 行高 |
+|----------|-----------|-------------|----------|-----------|-------------|
+| `text-tiny` | 0.75rem（12px） | 1rem（16px） | `text-xs` | 0.75rem（12px） | 1rem（16px） |
+| `text-small` | 0.875rem（14px） | 1.25rem（20px） | `text-sm` | 0.875rem（14px） | 1.25rem（20px） |
+| `text-medium` | 1rem（16px） | 1.5rem（24px） | `text-base` | 1rem（16px） | 1.5rem（24px） |
+| `text-large` | 1.125rem（18px） | 1.75rem（28px） | `text-lg` | 1.125rem（18px） | 1.75rem（28px） |
+
+### 圆角工具类
+
+v2 使用了自定义的圆角工具类（`rounded-small`、`rounded-medium`、`rounded-large`），并映射到 CSS 变量。v3 改用标准的 Tailwind 圆角类，但实际取值有所不同。
+
+**v2 圆角：**
+
+```tsx
+// v2 - Custom utilities
+<div className="rounded-small">Small radius</div>
+<div className="rounded-medium">Medium radius</div>
+<div className="rounded-large">Large radius</div>
+```
+
+**v3 圆角：**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="rounded-sm">Small radius</div>
+<div className="rounded-md">Medium radius</div>
+<div className="rounded-lg">Large radius</div>
+```
+
+**取值对比：**
+
+| v2 类 | v2 取值 | v3 类 | v3 取值 | 差异 |
+|----------|----------|----------|----------|------------|
+| `rounded-small` | 8px（0.5rem） | `rounded-sm` | 4px（0.25rem） | 更小 |
+| `rounded-medium` | 12px（0.75rem） | `rounded-md` | 6px（0.375rem） | 更小 |
+| `rounded-large` | 14px（0.875rem） | `rounded-lg` | 8px（0.5rem） | 更小 |
+
+**注意：** v3 默认的圆角取值更小。如果你需要精确还原 v2 的取值，请使用任意值：
+
+```tsx
+// Match v2 rounded-small (8px)
+<div className="rounded-[8px]">Custom radius</div>
+
+// Match v2 rounded-medium (12px)
+<div className="rounded-[12px]">Custom radius</div>
+
+// Match v2 rounded-large (14px)
+<div className="rounded-[14px]">Custom radius</div>
+```
+
+### 边框宽度工具类
+
+v2 提供了自定义的边框宽度工具类（`border-small`、`border-medium`、`border-large`）。v3 改用标准的 Tailwind 边框宽度类。
+
+**v2 边框宽度：**
+
+```tsx
+// v2 - Custom utilities
+<div className="border-small border-default">1px border</div>
+<div className="border-medium border-primary">2px border</div>
+<div className="border-large border-danger">3px border</div>
+```
+
+**v3 边框宽度：**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="border border-default">1px border</div>
+<div className="border-2 border-accent">2px border</div>
+<div className="border-[3px] border-danger">3px border</div>
+```
+
+**对照：**
+
+| v2 类 | 宽度 | v3 类 | 宽度 |
+|----------|-------|----------|-------|
+| `border-small` | 1px | `border` | 1px |
+| `border-medium` | 2px | `border-2` | 2px |
+| `border-large` | 3px | `border-[3px]` | 3px（任意值） |
+
+### 过渡工具类
+
+v2 为常见的动画模式提供了一组自定义的过渡工具类，默认持续时间为 250ms。v3 移除了这些工具类，转而推荐使用标准的 Tailwind `transition-*` 工具类，由你显式指定要应用过渡的属性。
+
+**v2 过渡工具类：**
+
+v2 提供了默认持续时间为 250ms、缓动函数为 `ease` 的自定义过渡工具类。下表展示了每个工具类对应的 CSS 过渡属性：
+
+| v2 工具类 | 过渡属性 |
+|-----------|----------------------|
+| `.transition-background` | `background` |
+| `.transition-colors-opacity` | `color, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
+| `.transition-width` | `width` |
+| `.transition-height` | `height` |
+| `.transition-size` | `width, height` |
+| `.transition-left` | `left` |
+| `.transition-transform-opacity` | `transform, scale, opacity rotate` |
+| `.transition-transform-background` | `transform, scale, background` |
+| `.transition-transform-colors` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke` |
+| `.transition-transform-colors-opacity` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
+
+**注意：** 这些工具类在 v3 中不再可用。请使用 Tailwind 标准的 `transition-*` 工具类，并显式指定要应用过渡的属性。
+
+### 其他工具类
+
+**滚动条工具类：**
+
+v2 提供了 `.scrollbar-hide` 和 `.scrollbar-default` 工具类。v3 现在通过 `@heroui/styles` 暴露基于标准属性的滚动条工具类：`scrollbar`、`scrollbar-thin`、`scrollbar-default` 和 `scrollbar-none`。如需按子树控制，可在祖先元素上使用 `data-scrollbar="thin"`、`data-scrollbar="default"` 或 `data-scrollbar="none"`。
+
+**动画工具类：**
+
+v2 提供了 spinner 相关的动画工具类（如 `.spinner-bar-animation`、`.spinner-dot-animation` 等）。在 v3 中，这些动画由组件内部处理，不再作为公开的工具类暴露。
+
+**其他自定义工具类：**
+
+v2 中还包含一些自定义工具类，例如：
+- `.leading-inherit` → 改用 `leading-[inherit]`
+- `.tap-highlight-transparent` → 改用 `[-webkit-tap-highlight-color:transparent]`
+- `.input-search-cancel-button-none` → 如有需要，请使用自定义 CSS
+
+## 主题系统架构
+
+### v2：基于插件的体系
+
+v2 采用了 Tailwind CSS 插件方式：
+
+1. **生成工具类**：通过 JavaScript 创建自定义工具类
+2. **CSS 变量**：通过插件注入 CSS 变量
+3. **主题配置**：需要在 `tailwind.config.js` 中进行配置
+4. **构建时生成**：工具类在构建时生成
+
+**v2 配置：**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [
+    heroui({
+      layout: {
+        fontSize: {
+          tiny: "0.75rem",
+          small: "0.875rem",
+          medium: "1rem",
+          large: "1.125rem",
+        },
+        radius: {
+          small: "8px",
+          medium: "12px",
+          large: "14px",
+        },
+      },
+      themes: {
+        light: {
+          colors: {
+            primary: {
+              // color definitions
+            },
+          },
+        },
+      },
+    }),
+  ],
+};
+```
+
+### v3：CSS 优先体系
+
+v3 采用纯 CSS 的方式：
+
+1. **CSS 文件**：样式直接定义在 CSS 文件中（位于 `packages/styles/`）
+2. **CSS 变量**：变量在 CSS 中定义，而非由插件生成
+3. **无需插件**：不再需要 Tailwind 插件
+4. **基于导入**：通过 CSS `@import` 引入样式
+
+**v3 配置：**
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+**无需 Tailwind 配置：**
+
+如果你只使用 HeroUI，可以完全删除 `tailwind.config.js`。如果你已有自定义的 Tailwind 配置，请保留它，但移除其中的 HeroUI 插件。
+
+### 架构对比
+
+| 对比项 | v2 | v3 |
+|--------|----|----|
+| **样式方案** | Tailwind 插件（JavaScript） | CSS 文件 |
+| **工具类生成方式** | 由插件在构建时生成 | 预定义的 CSS |
+| **CSS 变量** | 由插件生成 | 在 CSS 中定义 |
+| **配置方式** | `tailwind.config.js` | CSS 导入 |
+| **定制方式** | 插件配置 | 覆盖 CSS 变量 |
+| **构建依赖** | 需要插件 | 无需插件 |
+
+## CSS 变量与设计 token
+
+### 变量命名变更
+
+v2 采用 `--heroui-{property}-{scale}` 的命名模式，而 v3 改用 `--{property}` 或 `--color-{property}`。
+
+**v2 CSS 变量：**
+
+```css
+--heroui-font-size-tiny: 0.75rem;
+--heroui-font-size-small: 0.875rem;
+--heroui-radius-small: 8px;
+--heroui-radius-medium: 12px;
+--heroui-border-width-medium: 2px;
+--heroui-disabled-opacity: 0.5;
+```
+
+**v3 CSS 变量：**
+
+```css
+/* Typography - handled by Tailwind */
+/* No custom font-size variables */
+
+/* Radius */
+--radius-xs: calc(var(--radius) * 0.25);
+--radius-sm: calc(var(--radius) * 0.5);
+--radius-md: calc(var(--radius) * 0.75);
+--radius-lg: calc(var(--radius) * 1);
+--radius-xl: calc(var(--radius) * 1.5);
+
+/* Colors */
+--color-background: var(--background);
+--color-foreground: var(--foreground);
+--color-accent: var(--accent);
+--color-muted: var(--muted);
+
+/* Opacity */
+--disabled-opacity: 0.5;
+```
+
+### 颜色系统变更
+
+**v2 颜色结构：**
+
+```css
+--heroui-primary: 210 100% 50%;
+--heroui-primary-50: 210 100% 95%;
+--heroui-primary-100: 210 100% 90%;
+/* ... more shades ... */
+```
+
+**v3 颜色结构：**
+
+```css
+--accent: oklch(0.6204 0.195 253.83);
+--accent-foreground: var(--snow);
+--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+```
+
+**主要差异：**
+
+1. **颜色格式**：v2 使用 HSL，v3 使用 OKLCH
+2. **命名**：v2 使用数字色阶（50-900），v3 使用语义命名
+3. **计算颜色**：v3 通过 `color-mix()` 计算悬停等状态色
+4. **前景色**：v3 显式定义了前景色
+5. **primary → accent**：`primary` 颜色已重命名为 `accent`
+6. **移除 secondary 颜色**：v2 中的 `secondary` 语义颜色（紫色）已被移除
+7. **移除数字色阶**：`primary-50`、`primary-100` 等数字色阶不再存在
+
+### primary → accent 重命名
+
+v2 使用 `primary` 作为主品牌色。v3 将其重命名为 `accent`，使语义更加清晰。
+
+**v2 中的 primary 颜色：**
+
+```tsx
+// v2 - Primary color with numbered scales
+<Button color="primary">Primary Button</Button>
+<div className="bg-primary">Primary background</div>
+<div className="bg-primary-50">Light primary</div>
+<div className="bg-primary-100">Lighter primary</div>
+<div className="text-primary-600">Primary text</div>
+```
+
+**v3 中的 accent 颜色：**
+
+```tsx
+// v3 - Accent color (no numbered scales)
+<Button variant="primary">Primary Button</Button>
+<div className="bg-accent">Accent background</div>
+<div className="bg-accent-soft">Soft accent</div>
+<div className="text-accent">Accent text</div>
+```
+
+**迁移：**
+
+| v2 类 | v3 对应类 | 说明 |
+|----------|---------------|-------|
+| `bg-primary` | `bg-accent` | 基础 accent 色 |
+| `text-primary` | `text-accent` | accent 文本颜色 |
+| `bg-primary-50` | `bg-accent-soft` | 浅色 accent 变体 |
+| `bg-primary-100` | `bg-accent-soft` | 浅色 accent 变体 |
+| `bg-primary-500` | `bg-accent` | 基础 accent 色 |
+| `text-primary-600` | `text-accent` | accent 文本颜色 |
+| `border-primary` | `border-accent` | accent 边框 |
+
+**注意：** v3 不再提供数字色阶（`-50`、`-100`、`-200` 等）。请使用语义化的变体（如 `-soft`、`-hover`），或自定义的 Tailwind 类。
+
+### secondary 颜色已移除
+
+v2 提供了 `secondary` 语义颜色（紫色），该颜色已在 v3 中移除。名为「secondary」的组件变体现在改用其他颜色。
+
+**v2 中的 secondary 颜色：**
+
+```tsx
+// v2 - Secondary as a semantic color (purple)
+<Button color="secondary">Secondary Button</Button>
+<div className="bg-secondary">Secondary background</div>
+<div className="bg-secondary-50">Light secondary</div>
+<div className="text-secondary-600">Secondary text</div>
+```
+
+**v3 中的 secondary 变体：**
+
+```tsx
+// v3 - Secondary is a variant, not a color
+<Button variant="secondary">Secondary Button</Button>
+<div className="bg-default">Default background (used by secondary variant)</div>
+<div className="text-accent">Accent text</div>
+```
+
+**迁移：**
+
+| v2 类 | v3 对应类 | 说明 |
+|----------|---------------|-------|
+| `bg-secondary` | `bg-default` | secondary 变体改用 default 颜色 |
+| `text-secondary` | `text-accent` | 使用 accent 进行强调 |
+| `bg-secondary-50` | `bg-default` | 改用 default 颜色 |
+| `border-secondary` | `border-accent` | 使用 accent 边框 |
+
+**注意：** 在 v3 中，「secondary」指的是组件变体样式（例如 `button--secondary`），而不是颜色 token。secondary 变体通常使用 `bg-default` 和 `text-accent`。
+
+### 数字色阶已移除
+
+v2 为所有语义颜色都提供了 50–900 的数字色阶。v3 移除了这些数字色阶，改用语义化的变体与计算得出的颜色。
+
+**v2 数字色阶：**
+
+```tsx
+// v2 - Numbered color scales
+<div className="bg-primary-50">Lightest</div>
+<div className="bg-primary-100">Lighter</div>
+<div className="bg-primary-200">Light</div>
+<div className="bg-primary-500">Base</div>
+<div className="bg-primary-600">Dark</div>
+<div className="bg-primary-900">Darkest</div>
+```
+
+**v3 语义化变体：**
+
+```tsx
+// v3 - Semantic variants and calculated colors
+<div className="bg-accent-soft">Soft variant</div>
+<div className="bg-accent">Base color</div>
+<div className="bg-accent-hover">Hover state</div>
+```
+
+**迁移：**
+
+- **浅色调**（`-50`、`-100`、`-200`）：改用 `-soft` 变体或自定义的 Tailwind 透明度类
+- **基础色**（`-500`）：直接使用基础色名（`bg-accent`、`bg-danger` 等）
+- **深色调**（`-600`、`-700`、`-800`、`-900`）：改用 hover 变体或自定义的 Tailwind 类
+
+### Content 颜色已移除
+
+v2 提供了 `content1`、`content2`、`content3` 和 `content4` 颜色，用于分层背景。这些颜色已在 v3 中移除，并由语义化的 surface 颜色替代。
+
+**v2 Content 颜色：**
+
+```tsx
+// v2 - Content colors for layered backgrounds
+<div className="bg-content1">Base content</div>
+<div className="bg-content2">Secondary content</div>
+<div className="bg-content3">Tertiary content</div>
+<div className="bg-content4">Quaternary content</div>
+```
+
+**v3 Surface 颜色：**
+
+```tsx
+// v3 - Surface colors for non-overlay components
+<div className="bg-surface">Base surface</div>
+<div className="bg-surface-secondary">Secondary surface</div>
+<div className="bg-surface-tertiary">Tertiary surface</div>
+<div className="bg-surface-quaternary">Quaternary surface</div>
+
+// v3 - Overlay colors for floating components
+<div className="bg-overlay">Overlay (tooltips, popovers, modals)</div>
+```
+
+**迁移对照：**
+
+| v2 类 | v3 对应类 | 用法 |
+|----------|---------------|-------|
+| `bg-content1` | `bg-surface` | 非浮层组件（Card、Accordion 等） |
+| `bg-content1` | `bg-overlay` | 浮层组件（Tooltip、Popover、Modal 等） |
+| `bg-content2` | `bg-surface-secondary` | 二级 surface 层级 |
+| `bg-content3` | `bg-surface-tertiary` | 三级 surface 层级 |
+| `bg-content4` | `bg-surface-quaternary` | 四级 surface 层级 |
+
+**主要变化：**
+
+1. **语义命名**：`content1-4` 已替换为 `surface` 与 `overlay`，使语义更清晰
+2. **针对不同组件**：页面级组件使用 `bg-surface`，浮层组件使用 `bg-overlay`
+3. **自动计算**：surface 的各级（`secondary`、`tertiary`、`quaternary`）通过 `color-mix()` 从基础 `surface` 颜色自动计算得出
+
+### 间距与布局 token
+
+**v2 布局 token：**
+
+```css
+--heroui-divider-weight: 1px;
+--heroui-disabled-opacity: 0.5;
+--heroui-hover-opacity: 0.8;
+```
+
+**v3 布局 token：**
+
+```css
+--border-width: 0px;
+--field-border-width: var(--border-width);
+--disabled-opacity: 0.5;
+--cursor-interactive: pointer;
+--cursor-disabled: not-allowed;
+--radius: 0.5rem;
+--field-radius: calc(var(--radius) * 1.5);
+```
+
+### 阴影 token
+
+**v2 阴影：**
+
+```css
+--heroui-box-shadow-small: 0px 0px 5px 0px rgb(0 0 0 / 0.02), ...;
+--heroui-box-shadow-medium: 0px 0px 15px 0px rgb(0 0 0 / 0.03), ...;
+--heroui-box-shadow-large: 0px 0px 30px 0px rgb(0 0 0 / 0.04), ...;
+```
+
+**v3 阴影：**
+
+```css
+--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
+--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), ...;
+--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
+```
+
+**主要变化：**
+
+1. **语义命名**：v3 使用语义名称（`surface-shadow`、`overlay-shadow`），而非按尺寸命名
+2. **针对不同组件**：阴影与组件类型（surface、overlay、field）相绑定
+3. **深色模式**：在 v3 中，深色模式下的阴影为透明
+
+## 视觉差异
+
+### 对齐变化
+
+**Button 对齐：**
+
+- v2：图标与文本通过 `items-center justify-center` 对齐
+- v3：对齐方式相同，但加入了响应式高度调整
+
+**Input 对齐：**
+
+- v2：文本通过 `text-left` 对齐
+- v3：对齐方式相同，但内边距的调整可能影响视觉平衡
+
+### 间距变化
+
+**组件内边距：**
+
+v3 中大多数组件的内边距都有所增加：
+
+- **Card**：12px → 16px
+- **Button**：内边距相近，但高度改为响应式
+- **Input**：新增垂直内边距（`py-2`）
+
+**间隙（gap）：**
+
+v3 使用更一致的间隙：
+
+- **Card**：页眉、内容、页脚之间使用 `gap-3`
+- **Button**：图标与文字之间使用 `gap-2`
+- **Chip**：元素之间使用 `gap-1.5`
+
+### 尺寸变化
+
+**Button 高度：**
+
+- **Small**：32px → 36px（移动端）/ 32px（桌面端）
+- **Medium**：40px → 40px（移动端）/ 36px（桌面端）
+- **Large**：48px → 44px（移动端）/ 40px（桌面端）
+
+**Input 高度：**
+
+- **Medium**：40px → 36px（默认值，且为唯一可用尺寸）
+
+### 圆角变化
+
+**默认圆角：**
+
+- v2：组件默认使用 `rounded-medium`（12px）
+- v3：组件使用更大的圆角值：
+  - Button：`rounded-3xl`（24px）
+  - Card：`rounded-3xl`（24px）
+  - Chip：`rounded-2xl`（16px）
+  - Input：`rounded-field`（通常为 12–16px）
+
+### 颜色表现变化
+
+**颜色系统：**
+
+- v2：HSL 颜色格式
+- v3：OKLCH 颜色格式（在感知上更均匀）
+
+**默认颜色：**
+
+- v2：`primary`、`secondary`、`success`、`warning`、`danger`
+- v3：`accent`（替代 `primary`）、`success`、`warning`、`danger`
+
+**Muted 颜色：**
+
+- v2：使用 `foreground-400`、`foreground-500` 表示弱化文本
+- v3：使用 `muted` 颜色 token 表示弱化文本
+
+## 迁移示例
+
+### 工具类迁移
+
+**示例：文本工具类**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div>
+      <h1 className="text-large font-bold">Title</h1>
+      <p className="text-small text-foreground-400">Description</p>
+      <span className="text-tiny text-foreground-500">Helper</span>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div>
+      <h1 className="text-lg font-bold">Title</h1>
+      <p className="text-sm text-muted">Description</p>
+      <span className="text-xs text-muted">Helper</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### 圆角迁移
+
+**示例：还原 v2 的圆角取值**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card radius="md">
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Option 1: Use standard Tailwind (smaller radius) */}
+    <Card className="rounded-md">
+      <Card.Content>Content</Card.Content>
+    </Card>
+
+    {/* Option 2: Match exact v2 value (12px) */}
+    <Card className="rounded-[12px]">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### 主题定制迁移
+
+**示例：自定义颜色**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```js
+    // tailwind.config.js
+    const {heroui} = require("@heroui/react");
+
+    module.exports = {
+      plugins: [
+        heroui({
+          themes: {
+            light: {
+              colors: {
+                primary: {
+                  DEFAULT: "#006FEE",
+                  50: "#E6F1FE",
+                  // ... more shades
+                },
+              },
+            },
+          },
+        }),
+      ],
+    };
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```css
+    /* globals.css */
+    @import "tailwindcss";
+    @import "@heroui/styles";
+
+    :root {
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: oklch(0.9911 0 0);
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 最佳实践
+
+1. **优先使用标准 Tailwind**：相比自定义工具类，优先使用标准的 Tailwind 工具类
+2. **还原 v2 取值**：如果需要精确还原 v2 的视觉效果，请使用任意值
+3. **响应式测试**：v3 支持响应式尺寸——请在多种屏幕尺寸下进行测试
+4. **更新 CSS 变量**：自定义时请通过覆盖 CSS 变量来实现，而非修改 Tailwind 配置
+5. **查阅组件文档**：API 变更请参阅各个组件的迁移指南
+
+## 相关指南
+
+- [迁移总指南](/docs/react/migration)
+- [主题文档](/docs/react/getting-started/handbook/theming)
+- [样式指南](/docs/react/getting-started/handbook/styling)
diff --git a/apps/docs/content/docs/cn/react/releases/index.mdx b/apps/docs/content/docs/cn/react/releases/index.mdx
new file mode 100644
index 0000000..39cdf94
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/index.mdx
@@ -0,0 +1,357 @@
+---
+title: 所有版本
+description: HeroUI v3 的所有更新与变更，包含新功能、修复以及破坏性变更。
+---
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 最新版本
+
+### v3.2.2
+
+**2026 年 6 月 19 日**
+
+补丁版本：升级到 React Aria `1.19.0`（`react-aria@3.50.0`），为 `Tabs.ListContainer` 添加溢出滚动，修复清除/关闭按钮意外提交表单，以及 `Checkbox`、`Radio` 和 `Switch` 中视觉隐藏输入框导致的溢出滚动。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-2-2)
+
+---
+
+### v3.2.1
+
+**2026 年 6 月 17 日**
+
+补丁版本：`@heroui/react` 不再内置自己的 `react-aria` 副本。`react-aria` 的子路径在 Rollup 构建中被外部化，使消费方解析到项目中安装的单一 `react-aria`，而非内联副本。同时修复了 `SwitchGroup` 横向布局。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-2-1)
+
+---
+
+### v3.2.0
+
+**2026 年 6 月 6 日**
+
+基于 React Aria 1.18 的 Calendar 周/日视图、重做的年份选择器与范围日历演示，新增 Tooltip 延迟主题变量，并纳入随之发布的补丁修复。破坏性变更：`Radio`、`Checkbox`、`Switch` 改为显式的 `*.Content` 组合（控件嵌套进 `*.Content`，标签为纯文本、不嵌套 `<Label>`，帮助文本变为兄弟节点）。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-2-0)
+
+---
+
+### v3.1.0
+
+**2026 年 5 月 25 日**
+
+小版本发布：新增中文 React 文档与本地化示例，加入更可访问的 soft foreground 令牌和 vibrant palette 选项，统一滚动条系统，修复 `useTheme`、Toast、Fieldset、Link、浮层问题，并改进 Table、Picker 与 MenuItem 的 RTL 支持。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-1-0)
+
+---
+
+### v3.0.5
+
+**2026 年 5 月 15 日**
+
+补丁版本：`Text` 重命名为 `Typography` 以解决 `tailwind-merge` 冲突（⚠️ **破坏性变更**），派生颜色令牌重构为无前缀源变量，Checkbox 与 Radio 的 field-border 边框样式对齐，Calendar 悬停改用 `accent-soft-foreground` 以提升可读性，并新增 CLI 文档页。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-5)
+
+---
+
+### v3.0.4
+
+**2026 年 5 月**
+
+补丁版本：从 HeroUI Pro 移植的全新 `Text` 复合组件、文档主题选择器、在 45+ 个组件 CSS 文件中采用 `min()` 上限约束的圆角令牌、重做的 Table 聚焦环，以及对 Checkbox、Autocomplete、Tooltip 与表单字段内边距的修复。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-oss-3.0.4-4k.mp4"
+  muted
+/>
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-4)
+
+---
+
+### v3.0.3
+
+**2026 年 4 月 17 日**
+
+补丁版本：升级到 React Aria Components 1.17（合并依赖、安装更快、Table 支持可展开行），为 Vite 与 CRA 提供 `useTheme` Hook，为轻量级组件提供 DOM 多态的 render prop，并修复了 NumberField 的重置问题以及嵌套 Tabs 的样式问题。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-3)
+
+---
+
+### v3.0.2
+
+**2026 年 4 月 3 日**
+
+修复了多个 bug，Drawer 过渡更加平滑，新增了 `--backdrop` 主题变量，并优化了 trigger、arrow 与 Tag 的样式。修复了 Autocomplete 弹出层的宽度跟踪问题，浮层触发器现在使用 `inline-block`，Tag 在间距与无障碍方面也有所改进。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-2)
+
+### v3.0.0
+
+**2026 年 3 月**
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-v3-release.mp4"
+  height={430}
+  muted
+/>
+
+面向 React 与 React Native 的彻底重写。包含 75+ Web 组件、37 个原生组件、Tailwind CSS v4、React Aria、复合组件架构、基于 OKLCH token 的 CSS 优先主题、通过 `data-reduce-motion` 控制动画，并面向利用 MCP Server、Agent Skills 与 LLMs.txt 的 AI 辅助开发而打造。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0)
+
+---
+
+### HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+面向 React 与 React Native 的高级组件、模板与 AI 工具。预售价格现已上线。
+
+[访问 heroui.pro 查看套餐与定价 →](https://heroui.pro)
+
+---
+
+### v3.0.0-rc.1
+
+**2026 年 3 月 14 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-dark@2x.jpg"
+  alt="HeroUI v3 RC 1"
+  href="/docs/react/releases/v3-0-0-rc-1"
+/>
+
+新增七个组件（[Drawer](/docs/components/drawer)、[ToggleButton](/docs/components/toggle-button)、[ToggleButtonGroup](/docs/components/toggle-button-group)、[Meter](/docs/components/meter)、[ProgressBar](/docs/components/progress-bar)、[ProgressCircle](/docs/components/progress-circle)、[Toolbar](/docs/components/toolbar)），为 [Table](/docs/components/table) 和 [ListBox](/docs/components/list-box) 引入了 **虚拟化**，[ButtonGroup](/docs/components/button-group) 新增 `ButtonGroup.Separator` 与垂直方向支持，React Aria Components 升级到 v1.16.0。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-rc-1)
+
+---
+
+### v3.0.0-beta.8
+
+**2026 年 3 月 2 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-dark@2x.jpg"
+  alt="HeroUI v3 Beta 8"
+  href="/docs/react/releases/v3-0-0-beta-8"
+/>
+
+此版本新增三个组件（[Badge](/docs/components/badge)、[Pagination](/docs/components/pagination)、[Table](/docs/components/table)），并为 [DateField](/docs/components/date-field) 与 [TimeField](/docs/components/time-field) 提供了新的 `InputContainer` 组合 API。⚠️ **破坏性变更**：TextField 的 CSS 类已从 `.text-field` 重命名为 `.textfield`。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-8)
+
+---
+
+### v3.0.0-beta.7
+
+**2026 年 2 月 18 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-dark@2x.jpg"
+  alt="HeroUI v3 Beta 7"
+  href="/docs/react/releases/v3-0-0-beta-7"
+/>
+
+此版本引入了完整的**日期与时间**系统，包含四个新组件（[Calendar](/docs/components/calendar)、[RangeCalendar](/docs/components/range-calendar)、[DatePicker](/docs/components/date-picker)、[DateRangePicker](/docs/components/date-range-picker)），新增了 [Switch.Content](/docs/components/switch) 子组件、显式的 [Tabs.Separator](/docs/components/tabs) 用于按需启用分隔线，以及 ⚠️ **破坏性变更**：从 Tabs 中移除 `hideSeparator`，并将 `DateInputGroup` / `ColorInputGroup` 合并到各自的 Field 组件之下。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-7)
+
+---
+
+### v3.0.0-beta.6
+
+**2026 年 2 月 6 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-dark@2x.jpg"
+  alt="HeroUI v3 Beta 6"
+  href="/docs/react/releases/v3-0-0-beta-6"
+/>
+
+此版本引入了完整的**颜色系统**，包含六个新组件（[ColorPicker](/docs/components/color-picker)、[ColorArea](/docs/components/color-area)、[ColorSlider](/docs/components/color-slider)、[ColorField](/docs/components/color-field)、[ColorSwatch](/docs/components/color-swatch)、[ColorSwatchPicker](/docs/components/color-swatch-picker)），对 [Toast](/docs/components/toast) 进行了重大改进，加入了加载状态与 Promise 支持，[Separator](/docs/components/separator) 新增变体，以及 ⚠️ **破坏性变更**：将 `Toast.Container` 重命名为 `Toast.Provider`，并将 CSS 类名统一为连字符格式。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-6)
+
+---
+### v3.0.0-beta.5
+
+- 修复构建问题
+
+### v3.0.0-beta.4
+
+**2026 年 1 月 20 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-dark@2x.jpg"
+  alt="HeroUI v3 Beta 4"
+  href="/docs/react/releases/v3-0-0-beta-4"
+/>
+
+<Callout type="warning">
+  **已修复关键构建问题**：此版本（beta.4）存在一个关键构建问题，已在 **beta.5** 中修复。请升级到 `@heroui/styles@3.0.0-beta.5` 与 `@heroui/react@3.0.0-beta.5`，以确保 TypeScript 声明文件能正确生成、导出能正确解析。
+</Callout>
+
+此版本引入了用于可视化主题定制的全新[主题构建器](/themes)、三个新组件（[Autocomplete](/docs/components/autocomplete)、[Breadcrumbs](/docs/components/breadcrumbs)、[Toast](/docs/components/toast)），为 [Tabs](/docs/components/tabs) 添加了 secondary 变体，为 [Input](/docs/components/input) 与 [InputGroup](/docs/components/input-group) 添加了 primary / secondary 变体，以及 ⚠️ **破坏性变更**：移除了 Link 的下划线变体，并从表单组件中移除了 `isInSurface` prop。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-4)
+
+---
+
+### v3.0.0-beta.3
+
+**2025 年 12 月 19 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-dark@2x.jpg"
+  alt="HeroUI v3 Beta 3"
+  href="/docs/react/releases/v3-0-0-beta-3"
+/>
+
+
+此版本引入了七个新组件（[ButtonGroup](/docs/components/button-group)、[DateField](/docs/components/date-field)、[ErrorMessage](/docs/components/error-message)、[ScrollShadow](/docs/components/scroll-shadow)、[SearchField](/docs/components/search-field)、[TagGroup](/docs/components/tag-group)、[TimeField](/docs/components/time-field)），为表单与输入组件添加了 `fullWidth` 支持，为 [Tabs](/docs/components/tabs)、[ButtonGroup](/docs/components/button-group) 和 [Accordion](/docs/components/accordion) 引入 `hideSeparator` 以获得更简洁的布局，包含若干样式修复，以及 ⚠️ **破坏性变更**：移除 `asChild` prop，并更新了 [AlertDialog](/docs/components/alert-dialog) 与 [Modal](/docs/components/modal) 的 backdrop 变体。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-3)
+
+---
+
+### v3.0.0-beta.2
+
+**2025 年 11 月 20 日**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-dark@2x.jpg"
+  alt="HeroUI v3 Beta 2"
+  href="/docs/react/releases/v3-0-0-beta-2"
+/>
+
+
+此版本引入了六个重要的新组件（[AlertDialog](/docs/components/alert-dialog)、[ComboBox](/docs/components/combo-box)、[Dropdown](/docs/components/dropdown)、[InputGroup](/docs/components/input-group)、[Modal](/docs/components/modal)、[NumberField](/docs/components/number-field)），增强了主题兼容性与动效偏好支持，改进了 [Select](/docs/components/select) 组件的 API（包含 ⚠️ **破坏性变更**），并附带多项优化和 bug 修复。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-2)
+
+---
+
+### v3.0.0-beta.1
+
+**2025 年 11 月 6 日**
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1.mp4"
+  poster="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1-poster.png"
+  height={430}
+  muted
+/>
+
+此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件（[Alert](/docs/components/alert)、[Checkbox](/docs/components/checkbox)、[InputOTP](/docs/components/input-otp)、[ListBox](/docs/components/list-box)、[Select](/docs/components/select)、[Slider](/docs/components/slider)、[Surface](/docs/components/surface)），并对设计系统进行了彻底重构，包括更完善的颜色 token、阴影体系与整体架构。本版本还包含对设计系统变量、组件 API 以及灵活组件模式的破坏性变更。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-1)
+
+---
+
+## 早期版本
+
+### v3.0.0-alpha.35
+
+**2025 年 10 月 21 日**
+
+#### React Server Components 支持
+- 修复了复合组件在 React Server Components（RSC）中无法正常工作的关键问题
+- 将复合组件模式的逻辑从组件移至 index 文件，解决 `"use client"` 冲突
+- **（⚠️ 破坏性变更）**：主组件现在需要 `.Root` 后缀（例如 `<Avatar>` → `<Avatar.Root>`）
+- 命名导出保持不变，并完全继续支持
+
+#### React 19 相关改进
+- 移除了 `forwardRef`（[React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop) 现已原生支持）
+- 简化了 Context 的使用方式（`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider)）
+
+#### Switch 组件重构
+- **（⚠️ 破坏性变更）**：将 Switch 与 SwitchGroup 拆分为独立组件
+- 更简洁的 API：`<SwitchGroup>` 取代 `<Switch.Group>` 和 `<Switch.GroupItems>`
+- 与 Radio / RadioGroup 模式保持一致
+- 各自拥有独立的样式、类型和实现
+
+#### 受影响的组件
+以下复合组件均需要使用 `.Root` 后缀：`Accordion`、`Avatar`、`Card`、`Disclosure`、`Fieldset`、`Kbd`、`Link`、`Popover`、`Radio`、`Switch`、`Tabs`、`Tooltip`
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-35)
+
+### v3.0.0-alpha.34
+
+**2025 年 10 月 15 日**
+
+- 新增基于表单的组件：[Description](/docs/components/description)、[FieldError](/docs/components/field-error)、[Fieldset](/docs/components/fieldset)、[Form](/docs/components/form)、[Input](/docs/components/input)、[Label](/docs/components/label)、[RadioGroup](/docs/components/radio-group)、[TextField](/docs/components/text-field) 以及 [TextArea](/docs/components/textarea)
+- 引入表单字段相关的 token `--field-*`
+- 按类别重新组织 Storybook
+- **（破坏性变更）**：在 [Skeleton](/docs/components/skeleton) 中将 `--skeleton-default-animation-type` 重命名为 `--skeleton-animation`
+- 统一了各组件中 `data-slot` 标记的命名
+- 改进了文档
+
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-34)
+
+### v3.0.0-alpha.33
+
+**2025 年 10 月 5 日**
+
+- 将 RAC 升级至 [2025 年 10 月 2 日发布的版本](https://react-spectrum.adobe.com/releases/2025-10-02.html)
+- 调整了 [Tabs](/docs/components/tabs) 中 Indicator 的顺序（**破坏性变更**）
+- 将 [Tabs](/docs/components/tabs) 组件改为使用 React Aria 的 `SelectionIndicator`，现已支持 SSR
+- 更新了 [Disclosure](/docs/components/disclosure) 和 [Disclosure Group](/docs/components/disclosure-group) 组件，使其在展开/折叠动画中使用 RAC 的 CSS 变量
+- 更新了 [Switch](/docs/components/switch) 组件的样式与动画
+- 为 [Switch](/docs/components/switch#sizes) 新增 `size` 变体并补充了对应演示
+- 在 [Button](/docs/components/button)、[Tabs](/docs/components/tabs)、[Disclosure](/docs/components/disclosure)、[Disclosure Group](/docs/components/disclosure-group) 中添加了相关示例
+- 改进了文档
+
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-33)
+
+### v3.0.0-alpha.32
+
+**2025 年 10 月 1 日**
+
+重新设计了 Card 组件，引入了[新变体](/docs/components/card)，新增了 [CloseButton](/docs/components/close-button) 组件，发布了面向 AI 编码助手的 [MCP 服务器](/docs/ui-for-agents/mcp-server)，并改进了文档。
+
+[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-32)
+
+### v3.0.0-alpha.31
+
+**2025 年 9 月 22 日**
+
+- 🎨 **展示页面** - 使用 HeroUI 构建的站点案例集
+- 🌀 **DisclosureGroup 组件** - 将多个 Disclosure 组合在一起
+- 📇 **Card 组件**（预览） - Card 组件的首个版本
+- 🔀 **Switch 组件**（预览） - 用于设置项的切换开关
+
+---
+
+## 发布周期
+
+HeroUI v3 现已稳定。后续版本将遵循固定的发布周期：
+
+- **补丁版本**：按需修复 bug 与小幅优化
+- **次要版本**：新增组件与功能，通常每月一次
+- **主版本**：包含架构层面的变更，并提供迁移指南
+
+## 参与贡献
+
+发现问题或希望参与贡献？欢迎查看我们的 [GitHub 仓库](https://github.com/heroui-inc/heroui)。
diff --git a/apps/docs/content/docs/cn/react/releases/meta.json b/apps/docs/content/docs/cn/react/releases/meta.json
new file mode 100644
index 0000000..5f3f5b5
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/meta.json
@@ -0,0 +1,33 @@
+{
+  "title": "发布说明",
+  "description": "HeroUI v3 发布说明",
+  "icon": "rocket",
+  "root": true,
+  "pages": [
+    "---概述---",
+    "index",
+    "---版本列表---",
+    "v3-2-2",
+    "v3-2-1",
+    "v3-2-0",
+    "v3-1-0",
+    "v3-0-5",
+    "v3-0-4",
+    "v3-0-3",
+    "v3-0-2",
+    "v3-0-0",
+    "v3-0-0-rc-1",
+    "v3-0-0-beta-8",
+    "v3-0-0-beta-7",
+    "v3-0-0-beta-6",
+    "[v3.0.0-beta.5](/docs/react/releases#v300-beta5)",
+    "v3-0-0-beta-4",
+    "v3-0-0-beta-3",
+    "v3-0-0-beta-2",
+    "v3-0-0-beta-1",
+    "v3-0-0-alpha-35",
+    "v3-0-0-alpha-34",
+    "v3-0-0-alpha-33",
+    "v3-0-0-alpha-32"
+  ]
+}
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-32.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-32.mdx
new file mode 100644
index 0000000..cdf63d4
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-32.mdx
@@ -0,0 +1,183 @@
+---
+title: v3.0.0-alpha.32
+description: Card 组件重新设计、CloseButton 组件，以及面向 AI 助手的 MCP 服务器。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 10 月 1 日</span>
+</div>
+
+此版本新增了用于 AI 开发的工具，并更新了 [Card 组件](/docs/components/card) 的 API，以提升开发者体验。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+## 新增功能
+
+### MCP 服务器
+
+HeroUI 现已包含一个 [MCP 服务器](/docs/ui-for-agents/mcp-server)，可让 Cursor、Claude Code、VS Code Copilot 等 AI 助手直接访问 HeroUI v3 的文档与组件信息。
+
+**快速配置：**
+
+### Cursor
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline bg-default/50 dark:bg-default/30"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span className="text-accent">Install in Cursor</span>
+  </a>
+</div>
+
+或在 **Cursor Settings** → **Tools** → **MCP Servers** 中手动添加：
+
+```json
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+在终端中运行以下命令：
+
+```bash
+claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
+```
+
+[了解更多](/docs/ui-for-agents/mcp-server)
+
+### Card 组件 API 重新设计
+
+[Card 组件](/docs/components/card) 已升级到全新的变体系统，使用更加灵活。
+
+**破坏性变更：**
+- 将 `surface` prop 替换为新的 `variant` 系统
+- 移除了 `Card.Image`、`Card.Details` 与 `Card.CloseButton`（请改用组合方式实现）
+- 新增变体：`flat`、`outlined`、`elevated`、`filled`
+
+**之前：**
+```tsx
+<Card surface="1">
+  <Card.Image src="/image.jpg" />
+  <Card.Details>
+    <Card.Title>Old Card</Card.Title>
+  </Card.Details>
+</Card>
+```
+
+**之后：**
+```tsx
+<Card variant="outlined">
+  <Card.Header>
+    <img src="/image.jpg" alt="Card image" />
+  </Card.Header>
+  <Card.Body>
+    <Card.Title>New Card</Card.Title>
+  </Card.Body>
+</Card>
+```
+
+**新功能：**
+- 支持水平布局
+- 与 Avatar 集成
+- 支持背景图片
+- 通过语义化 HTML 提升无障碍体验
+
+[查看 Card 组件文档](/docs/components/card)
+
+### CloseButton 组件
+
+新增 [CloseButton 组件](/docs/components/close-button)，用于关闭对话框、模态框以及其他可关闭的元素。
+
+```tsx
+import {CloseButton} from "@heroui/react";
+
+// Basic usage
+<CloseButton onPress={() => console.log("Closed")} />
+
+// With custom icon
+<CloseButton>
+  <XMarkIcon className="size-4" />
+</CloseButton>
+```
+
+## 文档改进
+
+### 面向 AI 的 UI
+- **[MCP 服务器文档](/docs/ui-for-agents/mcp-server)** —— 介绍如何借助 AI 助手进行开发
+- **[llms.txt](/docs/ui-for-agents/llms-txt)** —— 对 LLM 更友好的文档文件
+- 主流 AI 编码工具的配置指南
+
+### 组件文档
+- **[Card](/docs/components/card)**：重写了文档，包含 anatomy、变体与更多示例
+- **[Switch](/docs/components/switch)**：新增 anatomy 示意图与更完善的示例
+- **[CloseButton](/docs/components/close-button)**：全新文档，附带使用示例
+
+
+## 迁移指南
+
+### Card 组件迁移
+
+1. **更新 variant prop：**
+   - `surface="1"` → `variant="flat"`
+   - `surface="2"` → `variant="outlined"`
+   - `surface="3"` → `variant="elevated"`
+   - `surface="4"` → `variant="filled"`
+   - 自定义 surface → 改用新的变体系统
+
+2. **更新组件结构：**
+   - 将 `Card.Image` 替换为放在 `Card.Header` 中的 `<img>`
+   - 将 `Card.Details` 替换为 `Card.Body`
+   - 将 `Card.CloseButton` 迁移为使用新的 `CloseButton` 组件
+
+3. **更新导入：**
+   ```tsx
+   // Add CloseButton if needed
+   import {Card, CloseButton} from "@heroui/react";
+   ```
+
+## 链接
+
+- [GitHub PR #5747](https://github.com/heroui-inc/heroui/pull/5747)
+- [MCP 服务器文档](/docs/ui-for-agents/mcp-server)
+- [Card 组件指南](/docs/components/card)
+- [CloseButton 组件](/docs/components/close-button)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-33.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-33.mdx
new file mode 100644
index 0000000..e7e8628
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-33.mdx
@@ -0,0 +1,112 @@
+---
+title: v3.0.0-alpha.33
+description: 升级 RAC、重新设计 Tabs 指示器、新增 Switch 尺寸变体，以及相关示例展示。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 10 月 5 日</span>
+</div>
+
+此版本升级了 React Aria Components，重新设计了 Tabs 指示器，为 Switch 新增尺寸支持，并补充了一系列组件示例。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+## 新增功能
+
+### RAC 升级
+
+将 React Aria Components 升级到 [2025 年 10 月 2 日发布版本](https://react-spectrum.adobe.com/releases/2025-10-02.html)。
+
+本次升级包括：
+- 用于动画的 CSS 变量
+- 更好的 SSR 支持
+- 选择指示器的性能改进
+
+### Disclosure 与 DisclosureGroup 更新
+
+[Disclosure](/docs/components/disclosure) 与 [DisclosureGroup](/docs/components/disclosure-group) 现在使用 React Aria 的 CSS 变量来驱动动画。组件会通过 `--disclosure-panel-width` 与 `--disclosure-panel-height` 变量在展开 / 折叠期间跟踪面板的实际尺寸。
+
+### Tabs 指示器重新设计
+
+[Tabs](/docs/components/tabs) 现在使用 React Aria 的 `SelectionIndicator` 并支持 SSR，这修复了初次渲染时的布局抖动问题。
+
+**🚧 破坏性变更：**
+
+- 将 `Tabs.Indicator` 移至每一个 `Tabs.Tab` 内部
+
+**之前：**
+```diff tsx
+<Tabs>
+  <Tabs.ListWrapper>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab>
++       <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+-   <Tabs.Indicator />
+  </Tabs.ListWrapper>
+  <Tabs.Panel/>
+</Tabs>
+```
+
+### Switch 更新
+
+[Switch](/docs/components/switch) 的样式与动画都得到了更新。新增 `size` prop，可选值为 `sm`、`md`、`lg`。
+
+<ComponentPreview name="switch-sizes" />
+
+### 相关示例
+
+我们在 [Button](/docs/components/button)、[Disclosure](/docs/components/disclosure)、[DisclosureGroup](/docs/components/disclosure-group) 与 [Tabs](/docs/components/tabs) 中新增了「相关示例」展示。
+
+## 文档改进
+
+### 组件文档
+- **[Tabs](/docs/components/tabs)**：更新了 anatomy，根据新的指示器设计重写了示例，并新增了相关示例展示
+- **[Switch](/docs/components/switch)**：新增尺寸示例，并重写了 with-icon 示例
+- **[Button](/docs/components/button)**、**[Disclosure](/docs/components/disclosure)**、**[DisclosureGroup](/docs/components/disclosure-group)**：新增相关示例展示
+
+## 迁移指南
+
+### Tabs 组件迁移
+
+1. **更新组件结构：**
+   - 将 `<Tabs.Indicator />` 移至每一个 `<Tabs.Tab />` 内部
+
+## 链接
+
+- [GitHub PR #5777](https://github.com/heroui-inc/heroui/pull/5777)
+- [Tabs 组件](/docs/components/tabs)
+- [Switch 组件](/docs/components/switch)
+- [Button 组件](/docs/components/button)
+- [Disclosure 组件](/docs/components/disclosure)
+- [DisclosureGroup 组件](/docs/components/disclosure-group)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-34.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-34.mdx
new file mode 100644
index 0000000..b736293
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-34.mdx
@@ -0,0 +1,165 @@
+---
+title: v3.0.0-alpha.34
+description: 用 Form、TextField、RadioGroup、Label、Input、Fieldset 等简洁 API 构建表单的核心组件。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 10 月 15 日</span>
+</div>
+
+此版本引入了一系列基于表单的组件、表单字段 token，重新组织了 Storybook，并对各组件之间的 data-slot 标识做了统一对齐。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 基于表单的组件
+
+我们引入了一整套基于 React Aria Components 构建的表单类组件，为构建表单提供了无障碍且可组合的基础构件。这些组件包括 [Description](/docs/components/description)、[FieldError](/docs/components/field-error)、[Fieldset](/docs/components/fieldset)、[Form](/docs/components/form)、[Input](/docs/components/input)、[Label](/docs/components/label)、[RadioGroup](/docs/components/radio-group)、[TextField](/docs/components/text-field) 与 [TextArea](/docs/components/textarea)。
+
+#### Description
+
+<ComponentPreview
+  name="description-basic"
+/>
+
+#### FieldError
+
+<ComponentPreview
+  name="field-error-basic"
+/>
+
+#### Fieldset
+
+<ComponentPreview
+  name="fieldset-basic"
+/>
+
+#### Form
+
+<ComponentPreview
+  name="form-basic"
+/>
+
+#### Input
+
+<ComponentPreview
+  name="input-basic"
+/>
+
+#### Label
+
+<ComponentPreview
+  name="label-basic"
+/>
+
+#### RadioGroup
+
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+#### TextField
+
+<ComponentPreview
+  name="text-field-basic"
+/>
+
+#### TextArea
+
+<ComponentPreview
+  name="textarea-basic"
+/>
+
+### 表单字段 token
+
+引入 `--field-*` 表单字段 token，确保各表单组件之间样式保持一致。`--field-*` 变量的具体说明请参阅 [主题](/docs/handbook/theming#calculated-variables-tailwind)。
+
+### Storybook 重新组织
+
+按类别重新组织了 Storybook，方便导航与组件查找。
+
+### Skeleton 动画 token
+
+**🚧 破坏性变更：** 为了与其他组件 token 保持一致，[Skeleton](/docs/components/skeleton) 中的 `--skeleton-default-animation-type` 已重命名为 `--skeleton-animation`。
+
+### data-slot 对齐
+
+我们统一了各组件的 data-slot 标识，使样式与定制更加一致。这项标准化让通过 CSS 选择器定位特定组件部件变得更容易，整体上也优化了自定义组件样式时的开发体验。
+
+组件现在使用一致的 `data-slot` 属性，例如：
+- `data-slot="base"` —— 用于根元素
+- `data-slot="label"` —— 用于标签文本
+- `data-slot="description"` —— 用于描述文本
+- `data-slot="error"` —— 用于错误信息
+
+这样在所有表单组件中都能用可预期的方式进行 CSS 定位：
+
+```css
+.radio {
+  [data-slot="label"] {
+    /* Styles apply to radio labels */
+  }
+}
+```
+
+## 文档改进
+
+### 组件文档
+- **[Link](/docs/components/link)**：新增 anatomy 与带图标的示例，更新了 Link 与 Link.Icon 的 prop 章节。
+- **[Description](/docs/components/description)**、**[FieldError](/docs/components/field-error)**、**[Fieldset](/docs/components/fieldset)**、**[Form](/docs/components/form)**、**[Input](/docs/components/input)**、**[Label](/docs/components/label)**、**[RadioGroup](/docs/components/radio-group)**、**[TextField](/docs/components/text-field)**，以及 **[TextArea](/docs/components/textarea)**：附带使用示例的全新文档
+
+
+## 迁移指南
+
+### Skeleton 组件迁移
+
+1. **更新动画 token：**
+   - 将 `--skeleton-default-animation-type` 替换为 `--skeleton-animation`
+
+## 链接
+
+- [GitHub PR #5780](https://github.com/heroui-inc/heroui/pull/5780)
+- [Description 组件](/docs/components/description)
+- [FieldError 组件](/docs/components/field-error)
+- [Fieldset 组件](/docs/components/fieldset)
+- [Form 组件](/docs/components/form)
+- [Input 组件](/docs/components/input)
+- [Label 组件](/docs/components/label)
+- [RadioGroup 组件](/docs/components/radio-group)
+- [TextField 组件](/docs/components/text-field)
+- [TextArea 组件](/docs/components/textarea)
+- [Skeleton 组件](/docs/components/skeleton)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-35.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-35.mdx
new file mode 100644
index 0000000..b70fe12
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-alpha-35.mdx
@@ -0,0 +1,401 @@
+---
+title: v3.0.0-alpha.35
+description: 复合组件支持 React Server Components、面向 React 19 的改进，以及关键 bug 修复。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 10 月 21 日</span>
+</div>
+
+此版本修复了一个关键问题：**复合组件在 React Server Components（RSC）中无法正常工作**。同时，本版本采用了 React 19 的最佳实践，移除了 `forwardRef`，并简化了 Context 的使用方式。Switch 组件已经过重构，与 Radio / RadioGroup 模式保持一致，提供更清晰、更统一的 API。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### React Server Components 支持
+
+复合组件现在可以在 React Server Components 中正常工作。此前的实现把复合模式逻辑放在了组件内部，与 `"use client"` 指令存在冲突。通过将模式逻辑迁移到组件的索引文件中，这一问题已被修复。
+
+### 面向 React 19 的改进
+
+本版本采用了 React 19 的最佳实践：
+
+1. **移除 `forwardRef`**：在 React 19 中已不再需要，`ref` 现在可以作为普通的 prop 使用（参见 [React 19 文档](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop)）
+2. **简化 Context**：将 `Context.Provider` 替换为直接使用 `Context`（参见 [React 19 文档](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider)）
+
+### Switch 组件架构改进
+
+Switch 组件已经过重构，遵循与 Radio / RadioGroup 相同的清晰拆分模式：
+
+- **拆分组件**：Switch 与 SwitchGroup 现在是独立的组件（此前合并在一起）
+- **更清晰的 API**：用 `<SwitchGroup>` 取代了嵌套的 `<Switch.Group>` 与 `<Switch.GroupItems>` 模式
+- **更合理的组织**：每个组件都有各自独立的样式、类型与实现
+- **一致的模式**：与 Radio / RadioGroup 架构保持一致，API 更具可预测性
+
+**之前：**
+```tsx
+<Switch.Group>
+  <Switch.GroupItems>
+    <Switch.Root>...</Switch.Root>
+  </Switch.GroupItems>
+</Switch.Group>
+```
+
+**之后：**
+```tsx
+<SwitchGroup>
+  <Switch.Root>...</Switch.Root>
+  <Switch.Root>...</Switch.Root>
+</SwitchGroup>
+```
+
+## ⚠️ 破坏性变更
+
+### 主组件需要使用 `.Root` 后缀
+
+为支持 React Server Components，复合组件模式已经过重构。在使用复合写法时，主组件现在需要带上 `.Root` 后缀。
+
+**之前：**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar>
+  <Avatar.Image src="/images/avatar.jpeg" alt="Junior Garcia" />
+  <Avatar.Fallback>JR</Avatar.Fallback>
+</Avatar>
+```
+
+**之后：**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar.Root>
+  <Avatar.Image src="/images/avatar.jpeg" alt="Junior Garcia" />
+  <Avatar.Fallback>JR</Avatar.Fallback>
+</Avatar.Root>
+```
+
+**说明：** 命名导出（例如 `<Avatar>`、`<AvatarImage>`、`<AvatarFallback>`）保持不变，依然完全支持。
+
+### Switch 组件 API 变更
+
+Switch 组件的分组 API 已经过重构，与 Radio / RadioGroup 模式保持一致：
+
+**之前：**
+```tsx
+import { Switch } from "@heroui/react"
+
+<Switch.Group orientation="horizontal">
+  <Switch.GroupItems>
+    <Switch.Root name="notifications">
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Notifications</Label>
+    </Switch.Root>
+    <Switch.Root name="marketing">
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Marketing</Label>
+    </Switch.Root>
+  </Switch.GroupItems>
+</Switch.Group>
+```
+
+**之后：**
+```tsx
+import { Switch, SwitchGroup } from "@heroui/react"
+
+<SwitchGroup orientation="horizontal">
+  <Switch.Root name="notifications">
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    <Label>Notifications</Label>
+  </Switch.Root>
+  <Switch.Root name="marketing">
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    <Label>Marketing</Label>
+  </Switch.Root>
+</SwitchGroup>
+```
+
+这次变更带来了：
+
+- **拆分组件**：Switch 与 SwitchGroup 现在是独立的组件（此前合并在一起）
+- **更清晰的 API**：用 `<SwitchGroup>` 取代了嵌套的 `<Switch.Group>` 与 `<Switch.GroupItems>` 模式
+- **更合理的组织**：每个组件都有各自独立的样式、类型与实现
+- **一致的模式**：与 Radio / RadioGroup 架构保持一致，API 更具可预测性
+
+
+**迁移步骤：**
+1. 单独导入 `SwitchGroup`：`import { Switch, SwitchGroup } from "@heroui/react"`
+2. 将 `<Switch.Group>` 替换为 `<SwitchGroup>`
+3. 移除嵌套的 `<Switch.GroupItems>` 包装
+4. 单个的 `Switch.Root` 组件保持不变
+
+#### 受影响的组件
+
+所有复合组件都受到影响：
+
+- `Accordion` → `Accordion.Root`
+- `Avatar` → `Avatar.Root`
+- `Card` → `Card.Root`
+- `Disclosure` → `Disclosure.Root`
+- `Fieldset` → `Fieldset.Root`
+- `Kbd` → `Kbd.Root`
+- `Link` → `Link.Root`
+- `Popover` → `Popover.Root`
+- `RadioGroup` → `RadioGroup.Root`
+- `Switch` → `Switch.Root`
+- `Tabs` → `Tabs.Root`
+- `Tooltip` → `Tooltip.Root`
+
+## 迁移指南
+
+使用 HeroUI 的复合组件有两种选择：
+
+### 选项 1：改为使用 `.Root`（复合写法）
+
+如果你使用的是复合写法（点号语法），请将主组件改为使用 `.Root`：
+
+**Card 示例：**
+```tsx
+import { Card } from "@heroui/react"
+
+<Card.Root>
+  <Card.Header>
+    <Card.Title>Card Title</Card.Title>
+    <Card.Description>Card description</Card.Description>
+  </Card.Header>
+  <Card.Content>
+    Card content
+  </Card.Content>
+  <Card.Footer>
+    Card footer
+  </Card.Footer>
+</Card.Root>
+```
+
+**Tabs 示例：**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs.Root>
+  <Tabs.ListWrapper>
+    <Tabs.List>
+      <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListWrapper>
+  <Tabs.Panel id="tab1">Panel 1</Tabs.Panel>
+  <Tabs.Panel id="tab2">Panel 2</Tabs.Panel>
+</Tabs.Root>
+```
+
+[更多示例请参阅文档](/docs/components/card)
+
+**Avatar 示例：**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar.Root>
+  <Avatar.Image alt="John Doe" src="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+```
+
+[更多示例请参阅文档](/docs/components/avatar)
+
+### 选项 2：使用命名导出
+
+我们已经为所有复合组件添加了命名导出支持，你可以这样使用：
+
+**Card 示例：**
+```tsx
+import {
+  CardRoot,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from "@heroui/react"
+
+<CardRoot>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Card content
+  </CardContent>
+  <CardFooter>
+    Card footer
+  </CardFooter>
+</CardRoot>
+```
+
+**Tabs 示例：**
+```tsx
+import { TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabPanel } from "@heroui/react"
+
+<TabsRoot>
+  <TabListContainer>
+    <TabList>
+      <Tab id="tab1">Tab 1<TabIndicator /></Tab>
+      <Tab id="tab2">Tab 2<TabIndicator /></Tab>
+    </TabList>
+  </TabListContainer>
+  <TabPanel id="tab1">Panel 1</TabPanel>
+  <TabPanel id="tab2">Panel 2</TabPanel>
+</TabsRoot>
+```
+
+**Avatar 示例：**
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@heroui/react"
+
+<Avatar>
+  <AvatarImage alt="John Doe" src="..." />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+### 迁移步骤
+
+如果你使用的是复合写法，只需将主组件改为使用 `.Root`：
+
+1. **查找复合组件的所有使用位置**（例如内部包含 `<Avatar.Image>` 等的 `<Avatar>`）
+
+2. **为主组件添加 `.Root`**：
+   ```tsx
+   // Before
+   <Avatar>
+     <Avatar.Image ... />
+   </Avatar>
+
+   // After
+   <Avatar.Root>
+     <Avatar.Image ... />
+   </Avatar.Root>
+   ```
+
+3. **就这样！** 所有子组件（如 `Avatar.Image`、`Avatar.Fallback`）保持不变。
+
+### 完整的迁移参考
+
+| 组件 | 命名导出写法 | 复合写法（带 `.Root`） | 额外变更 |
+|------|--------------|------------------------|----------|
+| **Accordion** | `<Accordion>` | `<Accordion.Root>` | - |
+| **Avatar** | `<Avatar>` | `<Avatar.Root>` | - |
+| **Card** | `<Card>` | `<Card.Root>` | - |
+| **Disclosure** | `<Disclosure>`  | `<Disclosure.Root>`  | - |
+| **Fieldset** | `<Fieldset>`  | `<Fieldset.Root>` | - |
+| **Kbd** | `<Kbd>` | `<Kbd.Root>`  | - |
+| **Link** | `<Link>` | `<Link.Root>` | - |
+| **Popover** | `<Popover>` | `<Popover.Root>` | - |
+| **Radio** |  `<Radio>` | `<Radio.Root>` | - |
+| **Switch** | `<Switch>`、`<SwitchControl>` | `<Switch.Root>`、`<Switch.Control>` | `<Switch.Group>` → `<SwitchGroup>`（独立组件）|
+| **Tabs** | `<Tabs>`、`<TabList>` | `<Tabs.Root>`、`<Tabs.List>` | - |
+| **Tooltip** | `<Tooltip>`、`<TooltipTrigger>` | `<Tooltip.Root>`、`<Tooltip.Trigger>` | - |
+
+### 自动化迁移
+
+对于使用复合写法的大型代码库，可以借助查找 / 替换：
+
+```bash
+# Example for Avatar component
+# Update the main component to use .Root
+sed -i 's/<Avatar>/<Avatar.Root>/g' **/*.tsx
+sed -i 's/<\/Avatar>/<\/Avatar.Root>/g' **/*.tsx
+
+# Switch component requires additional steps
+# First, ensure SwitchGroup is imported
+# Then replace Switch.Group with SwitchGroup
+sed -i 's/<Switch\.Group/<SwitchGroup/g' **/*.tsx
+sed -i 's/<\/Switch\.Group>/<\/SwitchGroup>/g' **/*.tsx
+
+# Remove Switch.GroupItems wrapper
+sed -i 's/<Switch\.GroupItems>//g' **/*.tsx
+sed -i 's/<\/Switch\.GroupItems>//g' **/*.tsx
+
+# Repeat for other compound components (Card, Tabs, etc.)
+# Note: This only affects files using the compound pattern
+```
+
+**重要事项：**
+- 使用自动替换时务必小心，确保只替换复合写法的用法，而不要影响命名导出。
+- Switch 的迁移完成后，请确认 `SwitchGroup` 已被导入：`import { Switch, SwitchGroup } from "@heroui/react"`
+- 在执行完自动迁移后请测试代码，确认所有变更均符合预期。
+
+## 为什么需要这次变更？
+
+这次变更是修复 React Server Components 兼容性所必需的。此前的实现存在一些架构上的限制：
+
+1. **RSC 兼容性**：复合模式逻辑与 `"use client"` 指令存在冲突
+2. **拥抱 React 19**：移除了 `forwardRef` 与 `Context.Provider` 等已被弃用的写法
+3. **更清晰的架构**：模式逻辑现在位于索引文件中，而不是组件文件中
+4. **更彻底的拆分**：服务端组件与客户端组件现在可以无缝协作
+
+## 文档更新
+
+组件文档将同步更新，以反映新的写法：
+
+- 示例将展示带 `.Root` 的复合写法
+- 命名导出形式的示例依然有效且仍受支持
+- 迁移指南将帮助你顺利完成升级
+- 两种写法都获得完整支持，行为完全一致
+
+## 需要帮助？
+
+如果你在迁移过程中遇到任何问题：
+
+1. **复合写法用户**：将主组件改为使用 `.Root`（例如 `<Avatar>` → `<Avatar.Root>`）
+2. **命名导出用户**：无需做任何修改，你的代码仍可正常工作
+3. 查阅组件文档中的示例
+4. 反馈问题：[GitHub Issues](https://github.com/heroui-inc/heroui/issues)
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [React Server Components](https://react.dev/reference/rsc/server-components)
+- [React 19 发布](https://react.dev/blog/2024/12/05/react-19)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者，是你们让 React Server Components 支持与 React 19 兼容性得到了改进！
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-1.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-1.mdx
new file mode 100644
index 0000000..b737456
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-1.mdx
@@ -0,0 +1,870 @@
+---
+title: v3.0.0-beta.1
+description: 重大重新设计，带来全新的设计系统、8 个新组件以及更佳的开发者体验。
+github:
+  pull: 5872
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 11 月 6 日</span>
+</div>
+
+此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件，并对设计系统进行了改进，包括更完善的颜色 token、阴影体系与整体架构。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 全新的设计系统
+
+我们花了数周时间打造一套全新的设计系统，将 HeroUI v2 的灵魂与 v3 的简洁性融合在一起。每一个组件都经过重新设计，注重细节、流畅的动效以及更佳的开发者体验。新的设计系统已发布在我们的 [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1.mp4"
+  poster="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1-poster.png"
+  height={430}
+  muted
+/>
+
+本次重新设计带来了：
+- 让 v3 的视觉愿景落地、并具备独特辨识度的全新色彩系统
+- 更精致的阴影系统，呈现更好的层次感
+- 全新的变量与 token，提供更强的定制能力
+- 基于表单的组件自动具备 `isOnSurface` 支持
+- 增强的边框与间距 token
+- 更好的对比度与无障碍体验
+- Web 与 Native 之间一致的组件模式
+
+### 新组件
+
+本次发布共引入 **8 个** 新的基础组件：
+
+- **[Alert](#alert)**：带状态指示器，用于展示重要的消息与通知。
+- **[Checkbox 与 CheckboxGroup](#checkbox-checkboxgroup)**：用于在列表中选择多个条目。
+- **[InputOTP](#inputotp)**：用于身份验证流程的一次性密码输入框。
+- **[ListBox](#listbox)**：展示一组可单选或多选的选项。
+- **[Select](#select)**：基于 ListBox 构建的下拉选择组件。
+- **[Slider](#slider)**：从一个范围中选择数值，支持自定义刻度与标签。
+- **[Surface](#surface)**：用于构建带高度的容器的基础 surface 组件。
+
+<span id="alert"></span>
+### Alert
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+<span id="checkbox-checkboxgroup"></span>
+### Checkbox 与 CheckboxGroup
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+<ComponentPreview
+  name="checkbox-group-basic"
+/>
+
+<span id="inputotp"></span>
+### InputOTP
+
+<ComponentPreview
+  name="input-otp-basic"
+/>
+
+<span id="listbox"></span>
+### ListBox
+
+<ComponentPreview
+  name="list-box-default"
+/>
+
+<span id="select"></span>
+### Select
+
+<ComponentPreview
+  name="select-default"
+/>
+
+<span id="slider"></span>
+### Slider
+
+<ComponentPreview
+  name="slider-default"
+/>
+
+<span id="surface"></span>
+### Surface
+
+<ComponentPreview
+  name="surface-variants"
+/>
+
+### 组件 API 改进
+
+多个组件的 API 都得到了改进：
+
+- **Link**：新增 `underline` 与 `underlineOffset` prop，支持更细粒度的定制
+
+<ComponentPreview
+  name="link-basic"
+/>
+
+- **Card**：变体与样式系统得到改进
+
+<ComponentPreview
+  name="card-with-images"
+/>
+
+- **Chip**：新增尺寸变体并改进了颜色系统
+
+<ComponentPreview
+  name="chip-basic"
+/>
+
+- **Switch**：从底层重新设计，视觉与动画都得到优化
+
+<span id="switch"></span>
+<ComponentPreview
+  name="switch-basic"
+/>
+
+- **RadioGroup**：从底层重新设计，API 与样式更佳
+
+<span id="radiogroup"></span>
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+### 灵活的组件模式
+
+HeroUI 现在支持更灵活的组件写法。复合组件可以带 `.Root` 也可以不带 `.Root`，也可以使用命名导出——三种写法表现完全一致。
+
+**可用模式：**
+
+```tsx
+import { Avatar } from "@heroui/react"
+
+// 1. Compound pattern (no .Root needed) - recommended
+<Avatar>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+
+// 2. Compound pattern with .Root - still supported
+<Avatar.Root>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+
+// 3. Named exports
+import { AvatarRoot, AvatarImage, AvatarFallback } from "@heroui/react"
+
+<AvatarRoot>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</AvatarRoot>
+```
+
+**简单组件**（如 Button）的写法也完全一致：
+
+```tsx
+import { Button } from "@heroui/react"
+
+// No .Root needed
+<Button>Label</Button>
+
+// Or with .Root
+<Button.Root>Label</Button.Root>
+
+// Or named export
+import { ButtonRoot } from "@heroui/react"
+<ButtonRoot>Label</ButtonRoot>
+```
+
+**你也可以在同一个组件中混用复合写法与命名导出：**
+
+```tsx
+import { Avatar, AvatarFallback } from "@heroui/react"
+
+<Avatar>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+由此带来的好处：
+- **更简洁的 API**：主组件不再强制要求 `.Root` 后缀
+- **灵活性**：可以在「复合写法」、「带 `.Root` 的复合写法」与「命名导出」之间自由选择
+- **向后兼容**：`.Root` 写法依然可用
+- **命名一致性**：统一了命名约定（例如使用「Container」而非「Wrapper」）
+
+### 全局动画控制
+
+HeroUI 现在通过 `data-reduce-motion` 属性提供了便捷的全局动画控制方式。只需在 `<html>` 或 `<body>` 标签上加上 `data-reduce-motion="true"`，即可禁用整个应用中的所有动画。
+
+```html
+<!DOCTYPE html>
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations will be disabled -->
+</html>
+```
+
+HeroUI 会自动通过 `prefers-reduced-motion` 媒体查询尊重用户的动画偏好，并扩展了 Tailwind 的 `motion-reduce:` 变体，使其同时支持系统偏好与基于 data 属性的手动控制。这样既能灵活控制动画，也能符合无障碍最佳实践。
+
+了解更多关于动画与动效偏好的内容，请参阅 [动画文档](/docs/handbook/animation)。
+
+## ⚠️ 破坏性变更
+
+### 设计系统变量
+
+#### Panel → Surface 与 Overlay
+
+`--panel` 变量已被替换为 `--surface` 与 `--overlay`，以更好地区分非浮层组件（Card、Accordion）与浮层组件（Tooltip、Popover、Modal）。
+
+**之前：**
+```css
+--panel: var(--white);
+--panel-foreground: var(--foreground);
+--shadow-panel: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
+```
+
+**之后：**
+```css
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+--overlay: var(--white);
+--overlay-foreground: var(--foreground);
+--shadow-surface: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+--shadow-overlay: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+```
+
+**迁移：**
+- 非浮层组件请将 `bg-panel` 替换为 `bg-surface`
+- 浮层组件请将 `bg-panel` 替换为 `bg-overlay`
+- 将 `shadow-panel` 替换为 `shadow-surface` 或 `shadow-overlay`
+- 将 `--color-panel` 替换为 `--color-surface` 或 `--color-overlay`
+
+#### Surface 层级简化
+
+`--surface-1`、`--surface-2` 与 `--surface-3` 变量已被移除。Surface 各层级现在通过 `color-mix` 自动从 `--surface` 计算得出，因此你只需声明基础的 surface 颜色。
+
+**之前（手动声明）：**
+```css
+--surface-1: var(--background);
+--surface-2: var(--color-neutral-100);
+--surface-3: var(--color-neutral-200);
+```
+
+**之后（自动计算）：**
+```css
+/* You only declare the base surface */
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+
+/* HeroUI automatically calculates these using color-mix */
+--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
+```
+
+**自定义：**
+
+可以通过 Tailwind 的 `@theme` 指令覆盖默认的计算结果：
+
+```css
+@theme inline {
+  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
+  --color-surface-tertiary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+  --color-surface-quaternary: color-mix(in oklab, var(--surface) 90%, var(--surface-foreground) 10%);
+}
+```
+
+**迁移：**
+- 将 `bg-surface-1` 替换为 `bg-surface`（基础 surface）
+- 将 `bg-surface-2` 替换为 `bg-surface-secondary`（自动计算）
+- 将 `bg-surface-3` 替换为 `bg-surface-tertiary`（自动计算）
+
+同样的自动计算模式也适用于：
+- **背景色阶**：从 `--background` 计算 → `background-secondary`、`background-tertiary`、`background-quaternary`
+- **柔和色**：从状态色计算 → `accent-soft`、`danger-soft`、`warning-soft`、`success-soft`
+
+#### 边框宽度默认值变更
+
+默认边框宽度已从 `1px` 改为 `0px`。边框现在改为按需启用，而不是默认存在。
+
+**之前：**
+```css
+--border-width: 1px;
+```
+
+**之后：**
+```css
+--border-width: 0px; /* no border by default */
+```
+
+**迁移：**
+- 如果你的样式依赖默认边框，请在自定义样式中显式设置 `border-width`
+- 表单字段现在默认使用 `transparent` 边框
+
+#### 边框颜色默认值变更
+
+默认边框颜色的不透明度已从 `15%` 改为 `0%`（透明）。
+
+**之前：**
+```css
+--border: oklch(0 0 0 / 15%);
+```
+
+**之后：**
+```css
+--border: oklch(0 0 0 / 0%);
+```
+
+**字段边框默认值：**
+```css
+--field-border: transparent; /* no border by default on form fields */
+```
+
+#### 阴影系统更新
+
+阴影系统已被完全重新设计，为 surface 与 overlay 各自提供独立的阴影。
+
+**之前：**
+```css
+--panel-shadow: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
+--field-shadow: 0 0 0 0 rgba(255, 255, 255, 0.1) inset, 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+```
+
+**之后（浅色模式）：**
+```css
+--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+```
+
+**之后（深色模式）：**
+```css
+--surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+--overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+--field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+```
+
+#### 强调色更新
+
+强调色经过更新，对比度与视觉吸引力都有所提升。
+
+**之前：**
+```css
+--accent: var(--color-neutral-950);
+--accent-foreground: var(--snow);
+```
+
+**之后：**
+```css
+--accent: oklch(0.6204 0.195 253.83);
+--accent-foreground: var(--snow);
+```
+
+#### 状态颜色优化
+
+success、warning 与 danger 颜色经过优化，一致性与对比度都更佳。
+
+**Success：**
+- **之前：** `oklch(0.5503 0.1244 153.56)`
+- **之后：** `oklch(0.7329 0.1935 150.81)`
+- 浅色模式下，前景色从 `var(--snow)` 改为 `var(--eclipse)`
+
+**Warning：**
+- **之前：** `oklch(0.7186 0.1521 64.85)`
+- **之后：** `oklch(0.7819 0.1585 72.33)`（浅色），`oklch(0.8203 0.1388 76.34)`（深色）
+
+**Danger：**
+- **之前：** `oklch(0.6259 0.1908 29.19)`
+- **之后：** `oklch(0.6532 0.2328 25.74)`（浅色），`oklch(0.594 0.1967 24.63)`（深色）
+
+### 组件 API 变更
+
+#### Chip 组件
+
+Chip 组件的 `type` prop 已重命名为 `color`，同时新增 `size` prop，并引入了新的 `soft` 变体。
+
+**之前：**
+```tsx
+import { Chip } from "@heroui/react";
+
+<Chip type="danger" variant="secondary">Label</Chip>
+```
+
+**之后：**
+```tsx
+import { Chip } from "@heroui/react";
+
+<Chip color="danger" variant="soft" size="md">Label</Chip>
+```
+
+**迁移：**
+- 将 `type` prop 替换为 `color` prop
+- 使用 `size` prop（`sm`、`md`、`lg`）控制 Chip 尺寸
+- `soft` 变体提供低调的外观，适用于不那么突出的 Chip
+
+#### Link 组件
+
+Link 组件现在支持 `underline` 与 `underlineOffset` prop，并加入了对 `asChild` 的支持。
+
+**之前：**
+```tsx
+import { Link } from "@heroui/react";
+
+<Link href="#">Link text</Link>
+```
+
+**之后：**
+```tsx
+import { Link } from "@heroui/react";
+
+<Link href="#" underline="hover" underlineOffset={4}>Link text</Link>
+```
+
+**新增 prop：**
+- `underline`：`"none" | "hover" | "always"` —— 控制下划线的可见性
+- `underlineOffset`：`number` —— 控制下划线相对文本的偏移
+
+#### 类型引用语法
+
+由于采用了双模式实现，通过命名空间语法引用类型的方式不再支持。请改用对象样式语法或具名类型导入。
+
+**之前（不再可用）：**
+```tsx
+type AvatarProps = Avatar.RootProps
+```
+
+**之后（方式 1 —— 对象样式语法）：**
+```tsx
+type AvatarProps = Avatar["RootProps"]
+```
+
+**之后（方式 2 —— 具名类型导入，推荐）：**
+```tsx
+import type { AvatarRootProps } from "@heroui/react"
+
+type AvatarProps = AvatarRootProps
+```
+
+此变更会影响访问 prop 类型的所有复合组件。
+
+#### Tabs 组件重命名
+
+为保持一致性，Tabs 组件的包装元素已重命名：
+
+- **复合属性**：`Tabs.ListWrapper` → `Tabs.ListContainer`
+- **命名导出**：`TabListWrapper` → `TabListContainer`
+- **CSS 类**：`.tabs__list-wrapper` → `.tabs__list-container`
+- **data 属性**：`data-slot="tabs-list-wrapper"` → `data-slot="tabs-list-container"`
+
+**迁移：**
+
+请查找并替换所有 `TabListWrapper`，将其改为 `TabListContainer`：
+
+```bash
+# Component usage
+TabListWrapper → TabListContainer
+Tabs.ListWrapper → Tabs.ListContainer
+
+# CSS selectors (if using custom styles)
+.tabs__list-wrapper → .tabs__list-container
+[data-slot="tabs-list-wrapper"] → [data-slot="tabs-list-container"]
+```
+
+#### 已移除的变量
+
+以下变量已被移除：
+- `--panel` → 改用 `--surface` 或 `--overlay`
+- `--panel-foreground` → 改用 `--surface-foreground` 或 `--overlay-foreground`
+- `--surface-1`、`--surface-2`、`--surface-3` → 改用背景色阶或 surface 层级
+- `--accent-soft` → 改用 `--color-accent-soft`（现已自动计算）
+- `--radius-panel` 与 `--radius-panel-inner` → 改用标准的 radius 取值
+
+## 设计系统更新
+
+### 全新的色彩系统
+
+#### Surface 与 Overlay 概念
+
+设计系统现在区分两类带高度的组件：
+
+- **Surface**：用于直接放置在页面上的非浮层组件，如 Card、Accordion、Disclosure Group
+- **Overlay**：用于浮在页面之上的浮层组件，如 Tooltip、Popover、Modal、Menu
+
+这种区分带来：
+- 更好的视觉层级
+- 更合适的阴影深度
+- 更优的深色模式对比度
+- 更清晰的组件语义
+
+#### 自动计算的色彩系统
+
+HeroUI 现在使用 CSS `color-mix` 自动计算各种色阶以及柔和色变体。你只需声明基础颜色，剩下的交给 HeroUI 处理。
+
+**背景色阶**
+
+背景色阶会自动从 `--background` 计算：
+
+```css
+/* You only declare the base */
+--background: oklch(0.9702 0 0);
+--foreground: var(--eclipse);
+
+/* HeroUI automatically calculates these */
+--color-background-secondary: color-mix(in oklab, var(--color-background) 96%, var(--color-foreground) 4%);
+--color-background-tertiary: color-mix(in oklab, var(--color-background) 92%, var(--color-foreground) 8%);
+--color-background-quaternary: color-mix(in oklab, var(--color-background) 86%, var(--color-foreground) 14%);
+```
+
+**Surface 层级**
+
+Surface 各层级会自动从 `--surface` 计算：
+
+```css
+/* You only declare the base */
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+
+/* HeroUI automatically calculates these */
+--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
+```
+
+**柔和色变体**
+
+柔和色变体会自动从状态色计算：
+
+```css
+/* You declare the base status colors */
+--accent: oklch(0.6204 0.195 253.83);
+--danger: oklch(0.6532 0.2328 25.74);
+--warning: oklch(0.7819 0.1585 72.33);
+--success: oklch(0.7329 0.1935 150.81);
+
+/* HeroUI automatically calculates these at 15% opacity */
+--color-accent-soft: color-mix(in oklab, var(--color-accent) 15%, transparent);
+--color-danger-soft: color-mix(in oklab, var(--color-danger) 15%, transparent);
+--color-warning-soft: color-mix(in oklab, var(--color-warning) 15%, transparent);
+--color-success-soft: color-mix(in oklab, var(--color-success) 15%, transparent);
+```
+
+每个柔和色变体都包含悬停态（20% 不透明度）以及对应的前景色，以保证合适的对比度。
+
+**自定义：**
+
+可以通过 Tailwind 的 `@theme` 指令覆盖任意自动计算结果：
+
+```css
+@theme inline {
+  /* Adjust surface levels */
+  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
+
+  /* Adjust soft colors */
+  --color-accent-soft: color-mix(in oklab, var(--color-accent) 20%, transparent);
+}
+```
+
+这套自动计算系统减少了你需要管理的变量数量，同时在需要时仍能完全自定义。
+
+### 阴影系统
+
+阴影系统经过重新设计，提供：
+- 为 surface 与 overlay 提供各自独立的阴影
+- 更好的层次感
+- 深色模式支持（透明阴影）
+- 一致的字段阴影
+
+阴影会自动适配浅色与深色模式，为每种主题提供合适的层次提示。
+
+### 焦点系统
+
+焦点颜色现在使用强调色，以保持一致性：
+
+```css
+--focus: var(--accent);
+```
+
+这样既能让焦点指示器与你的品牌色一致，也能保留无障碍能力。
+
+### 排版 token
+
+部分与排版相关的变量已被移除，转而推荐直接使用 Tailwind 的排版工具类。设计系统现在专注于颜色与间距 token，将排版交给 Tailwind 处理。
+
+## 迁移指南
+
+### 第 1 步：更新设计系统变量
+
+将旧的 panel 变量替换为 surface / overlay：
+
+```css
+/* Before */
+.my-card {
+  background: var(--panel);
+  box-shadow: var(--shadow-panel);
+}
+
+/* After */
+.my-card {
+  background: var(--surface);
+  box-shadow: var(--shadow-surface);
+}
+
+.my-tooltip {
+  background: var(--overlay);
+  box-shadow: var(--shadow-overlay);
+}
+```
+
+### 第 2 步：更新 surface 层级
+
+Surface 层级现在会自动从 `--surface` 计算得出，因此无需手动声明。直接使用新的工具类即可：
+
+```css
+/* Before */
+.bg-surface-1 → .bg-surface (base surface)
+.bg-surface-2 → .bg-surface-secondary (auto-calculated)
+.bg-surface-3 → .bg-surface-tertiary (auto-calculated)
+
+/* You can also use background shades */
+.bg-surface-2 → .bg-background-secondary (auto-calculated from --background)
+.bg-surface-3 → .bg-background-tertiary (auto-calculated from --background)
+```
+
+**说明：** Surface 层级（`surface-secondary`、`surface-tertiary` 等）会基于你的 `--surface` 颜色自动计算。除非你想自定义计算方式，否则不需要手动声明任何 CSS 变量。
+
+### 第 3 步：更新组件 props
+
+更新 Chip 与 Link 组件：
+
+```tsx
+// Chip: type → color, add size if needed
+<Chip type="danger" /> → <Chip color="danger" size="md" />
+
+// Link: Add underline props if customizing underlines
+<Link href="#">Text</Link> // Still works, underline props are optional
+```
+
+### 第 4 步：简化组件写法（可选）
+
+如果你在 v3.0.0-alpha.35 中已经采用了 `.Root` 后缀，现在可以将其移除以简化代码：
+
+**之前（v3.0.0-alpha.35）：**
+```tsx
+<Avatar.Root>
+  <Avatar.Image src="..." alt="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+```
+
+**之后（更简洁）：**
+```tsx
+<Avatar>
+  <Avatar.Image src="..." alt="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+**说明：** 如果你更喜欢 `.Root` 写法，它仍然可用。
+
+### 第 5 步：更新类型引用
+
+如果你之前用命名空间语法来引用类型，请改用对象样式语法或具名导入：
+
+**之前：**
+```tsx
+type ButtonProps = Button.RootProps
+```
+
+**之后（方式 1 —— 对象样式）：**
+```tsx
+type ButtonProps = Button["RootProps"]
+```
+
+**之后（方式 2 —— 具名导入，推荐）：**
+```tsx
+import type { ButtonRootProps } from "@heroui/react"
+
+type ButtonProps = ButtonRootProps
+```
+
+### 第 6 步：更新 Tabs 组件
+
+将 `TabListWrapper` 替换为 `TabListContainer`：
+
+**之前：**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs.Root>
+  <Tabs.ListWrapper>
+    <Tabs.List>
+      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListWrapper>
+  <Tabs.Panel id="home">Content</Tabs.Panel>
+</Tabs.Root>
+```
+
+**之后：**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List>
+      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="home">Content</Tabs.Panel>
+</Tabs>
+```
+
+### 第 7 步：处理边框相关变更
+
+如果你的自定义样式依赖默认边框：
+
+```css
+/* Add explicit borders where needed */
+.my-component {
+  border-width: 1px;
+  border-color: var(--color-border);
+}
+```
+
+### 第 8 步：更新状态颜色
+
+如果你曾经定制过状态颜色，请查阅新的取值并按需调整你的自定义主题：
+
+```css
+/* Check if your custom status colors need updates */
+--success: oklch(0.7329 0.1935 150.81); /* New value */
+--warning: oklch(0.7819 0.1585 72.33); /* New value */
+--danger: oklch(0.6532 0.2328 25.74); /* New value */
+```
+
+### 自动化迁移
+
+对于较大的代码库，可以借助查找 / 替换：
+
+```bash
+# Panel → Surface
+--panel → --surface
+bg-panel → bg-surface
+shadow-panel → shadow-surface
+
+# Panel → Overlay (for floating components)
+--panel → --overlay (where appropriate)
+bg-panel → bg-overlay (for tooltips, popovers, etc.)
+shadow-panel → shadow-overlay (for floating components)
+
+# Chip type prop
+type=" → color="
+
+# Surface levels
+bg-surface-1 → bg-surface
+bg-surface-2 → bg-surface-secondary
+bg-surface-3 → bg-surface-tertiary
+
+# Tabs component
+TabListWrapper → TabListContainer
+Tabs.ListWrapper → Tabs.ListContainer
+
+# Type references
+Component.RootProps → Component["RootProps"] or use named imports
+```
+
+## 组件更新
+
+### Card 组件
+
+Card 组件经过优化，变体更丰富、语义结构更合理。该组件现已使用新的 surface 系统，样式更加一致。
+
+### Accordion 组件
+
+Accordion 现在也使用 surface 系统，与其他组件在视觉上更加一致。
+
+### 表单组件
+
+表单组件（Input、TextField、TextArea）已更新为使用新的字段边框系统（默认透明），在保留无障碍能力的前提下呈现更简洁的外观。
+
+### 组件模式更新
+
+所有组件现在都支持灵活的写法。支持双模式的组件包括：
+
+- **简单组件**：Button、Link、Spinner、Chip、Kbd
+- **复合组件**：Accordion、Avatar、Card、Disclosure、Fieldset、Popover、RadioGroup、Switch、Tabs、Tooltip
+
+以上所有组件都可以使用三种写法中的任意一种：不带 `.Root` 的复合写法、带 `.Root` 的复合写法，或具名导出。
+
+## HeroUI Pro
+
+HeroUI Pro 正基于全新的设计系统从零进行重塑。新版 Pro 将带来：
+- 基于 HeroUI v3 构建的新组件
+- Tailwind CSS v4 原生支持
+- 基于 CSS 的原生动画
+- 更强的可定制能力
+
+我们将很快分享更多更新。
+
+## 路线图
+
+我们正以发布稳定版本为目标，计划在 2025 年的 **第四季度** 完成。本次 beta 让我们距离这个目标更进一步：
+- 更完整的组件集合
+- 更精炼的设计系统
+- 更佳的开发者体验
+- 更好的性能
+
+## 社区
+
+Native 端的反响非常热烈。感谢你在我们打造 HeroUI v3 的过程中给予的支持！你的反馈让我们每一天都在变得更好。
+
+来看看社区的声音：[HeroUI Native 用户反响](https://x.com/hero_ui/status/1985721976220966926)
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [HeroUI Native](https://link.heroui.com/native)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5872](https://github.com/heroui-inc/heroui/pull/5872)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者，是你们让我们打造出了一套既美观又实用的设计系统！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-2.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-2.mdx
new file mode 100644
index 0000000..1919b48
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-2.mdx
@@ -0,0 +1,307 @@
+---
+title: v3.0.0-beta.2
+description: 六个新组件（AlertDialog、ComboBox、Dropdown、InputGroup、Modal、NumberField）、Select API 改进以及多项组件优化。
+github:
+  pull: 5885
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 11 月 20 日</span>
+</div>
+
+此版本引入了六个重要的新组件，改进了 Select 组件的 API，并包含多项优化与 bug 修复。
+
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-dark@2x.jpg"
+  alt="HeroUI v3 Beta 2"
+/>
+
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 新组件
+
+本次发布引入了 **6 个** 新的基础组件：
+
+- **[AlertDialog](#alert-dialog)**：用于需要用户确认的重要决策的模态对话框。（[文档](/docs/components/alert-dialog)）
+- **[ComboBox](#combo-box)**：将文本输入与列表框结合，让用户可以在选项列表中过滤。（[文档](/docs/components/combo-box)）
+- **[Dropdown](#dropdown)**：展示一组可供用户选择的操作或选项。（[文档](/docs/components/dropdown)）
+- **[InputGroup](#inputgroup)**：通过 prefix 与 suffix 元素将相关输入控件组合在一起，强化表单字段。（[文档](/docs/components/input-group)）
+- **[Modal](#modal)**：用于聚焦用户交互与重要内容的对话框浮层。（[文档](/docs/components/modal)）
+- **[NumberField](#numberfield)**：数字输入框，带有递增 / 递减按钮、表单校验以及国际化格式化。（[文档](/docs/components/number-field)）
+
+### AlertDialog
+
+<ComponentPreview
+  name="alert-dialog-default"
+/>
+
+### ComboBox
+
+<ComponentPreview
+  name="combo-box-default"
+/>
+
+### Dropdown
+
+<ComponentPreview
+  name="dropdown-default"
+/>
+
+
+### Modal
+
+<ComponentPreview
+  name="modal-default"
+/>
+
+### InputGroup
+
+<ComponentPreview
+  name="input-group-with-icon-prefix-and-text-suffix"
+/>
+
+### NumberField
+
+<ComponentPreview
+  name="number-field-basic"
+/>
+
+### 样式改进
+
+#### 自定义变体与主题兼容性
+
+增强了 CSS 变体与主题系统，提供更好的可定制性：
+
+**动效偏好：**
+- 新增 `motion-safe` 变体，可与 `data-reduce-motion="true"` 属性配合使用
+- 增强后的 `motion-reduce` 现在支持祖先元素与伪元素
+
+**深色模式：**
+- 类与 `data-theme="dark"` 属性选择器现在优先于 `prefers-color-scheme`
+- 在深色模式下完整支持伪元素
+
+**主题变量：**
+- 扩展了浅色主题的覆盖范围，以支持嵌套主题（`:root`、`.light`、`.default`、`[data-theme="light"]`、`[data-theme="default"]`）
+
+### 组件改进
+
+#### Select 组件 API 更新
+
+Select 组件的 API 已经过改进，与其他组件保持一致。`Content` 子组件已重命名为 `Popover`。
+
+**之前：**
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Content>
+    <ListBox>
+      {/* items */}
+    </ListBox>
+  </Select.Content>
+</Select>
+```
+
+**之后：**
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      {/* items */}
+    </ListBox>
+  </Select.Popover>
+</Select>
+```
+
+#### Chip 组件改进
+
+Chip 组件的尺寸已更新，以提升一致性：
+- **小（`sm`）**：`px-1 py-0 text-xs`
+- **中（`md`）**：`text-xs`（现在显式设置）
+- **大（`lg`）**：`px-3 py-1 text-sm font-medium`
+
+#### Separator 组件增强
+
+Separator 组件现在能自动检测是否被放置在 surface 组件中（使用 `bg-surface`），并应用合适的分隔线颜色以获得更好的可见性。同时新增了 `isOnSurface` prop，用于手动控制。
+
+**新增的计算变量：**
+- `--color-separator-on-surface`：通过 `color-mix` 自动生成的计算变量，确保分隔线在 surface 背景上仍然清晰可见。与其他计算变量一样，可在你的主题中覆盖它。
+
+**用法：**
+
+```tsx
+<div className="bg-surface">
+  <Separator isOnSurface />
+</div>
+```
+
+当 Separator 检测到外层存在 `SurfaceContext` Provider（由 Card、Alert、Popover、Modal 等组件提供）时，`isOnSurface` prop 会自动启用。
+
+你也可以直接在 Tailwind 类中使用这个计算变量：
+
+```tsx
+<div className="bg-surface">
+  <div className="h-px w-full bg-separator-on-surface" />
+</div>
+```
+
+#### 动画改进
+
+- 更新了加载状态 spinner 的颜色，提升可见性
+- 调整了 Select 与 Slider 组件的样式，改进动画效果
+- 改进了 Checkbox 动画（过渡更快）
+- 在伪元素中更好地支持 `prefers-reduced-motion`
+
+## ⚠️ 破坏性变更
+
+### Select 组件
+
+为与 ComboBox、Dropdown 等组件保持一致，`Select.Content` 子组件已重命名为 `Select.Popover`。
+
+**迁移：**
+
+将所有 `Select.Content` 替换为 `Select.Popover`：
+
+```tsx
+// Before
+<Select.Content>
+  <ListBox>...</ListBox>
+</Select.Content>
+
+// After
+<Select.Popover>
+  <ListBox>...</ListBox>
+</Select.Popover>
+```
+
+**类型导入：**
+
+```tsx
+// Before
+import type { SelectContentProps } from "@heroui/react"
+
+// After
+import type { SelectPopoverProps } from "@heroui/react"
+```
+
+**命名导出：**
+
+```tsx
+// Before
+import { SelectContent } from "@heroui/react"
+
+// After
+import { SelectPopover } from "@heroui/react"
+```
+
+### CSS 变量与工具类：divider → separator
+
+为与 Separator 组件名保持一致，所有与 `divider` 相关的 CSS 变量与工具类均已重命名为 `separator`。
+
+**CSS 变量：**
+
+```css
+/* Before */
+border-bottom: 1px solid var(--divider);
+
+/* After */
+border-bottom: 1px solid var(--separator);
+```
+
+**Tailwind 工具类：**
+
+```tsx
+// Before
+<div className="bg-divider" />
+<div className="border-divider" />
+
+// After
+<div className="bg-separator" />
+<div className="border-separator" />
+```
+
+**主题覆盖：**
+
+如果你的自定义主题中覆盖了 separator 相关变量，请同步更新：
+
+```css
+/* Before */
+:root {
+  --divider: oklch(92% 0.004 286.32);
+}
+
+.dark {
+  --divider: oklch(22% 0.006 286.033);
+}
+
+/* After */
+:root {
+  --separator: oklch(92% 0.004 286.32);
+}
+
+.dark {
+  --separator: oklch(22% 0.006 286.033);
+}
+```
+
+## Bug 修复
+
+- 修复了加载状态 spinner 的颜色，提升可见性
+- 修复了 bordered 状态下焦点样式优先于 hover 状态的表现
+- 修复了文档中的动画卡顿问题
+- 改进了模态表单的样式
+- 增强了 motion-reduce 在伪元素上的支持
+- 修复了移动端触摸交互后悬停状态保留的问题——将 hover 样式包裹在 `@media (hover: hover)` 媒体查询中。同时通过移除不必要的 `="true"` data 属性值选择器，简化了相关代码。
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3（已更新）](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5885](https://github.com/heroui-inc/heroui/pull/5885)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-3.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-3.mdx
new file mode 100644
index 0000000..15b4de2
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-3.mdx
@@ -0,0 +1,285 @@
+---
+title: v3.0.0-beta.3
+description: 七个新组件、fullWidth 与 hideSeparator 支持、样式修复，以及 AlertDialog / Modal backdrop 变体调整与移除 asChild prop 等破坏性变更。
+github:
+  pull: 5923
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2025 年 12 月 19 日</span>
+</div>
+
+此版本引入了七个新组件（[ButtonGroup](/docs/components/button-group)、[DateField](/docs/components/date-field)、[ErrorMessage](/docs/components/error-message)、[ScrollShadow](/docs/components/scroll-shadow)、[SearchField](/docs/components/search-field)、[TagGroup](/docs/components/tag-group)、[TimeField](/docs/components/time-field)），为表单组件添加 `fullWidth` 支持，为 [Tabs](/docs/components/tabs)、[ButtonGroup](/docs/components/button-group) 与 [Accordion](/docs/components/accordion) 引入 `hideSeparator`，包含若干样式修复，以及 ⚠️ **破坏性变更**：移除 `asChild` prop，并更新了 [AlertDialog](/docs/components/alert-dialog) 与 [Modal](/docs/components/modal) 的 backdrop 变体。
+
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-dark@2x.jpg"
+  alt="HeroUI v3 Beta 3"
+  href="/docs/changelog/v3-0-0-beta-3"
+/>
+
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 新组件
+
+本次发布引入了 **7 个** 新的基础组件：
+
+- **[ButtonGroup](#button-group)**：以一致的样式与间距将相关按钮分组。（[文档](/docs/components/button-group)）
+- **[DateField](#date-field)**：日期输入字段，支持 label、description 与表单校验，基于 React Aria DateField 构建。（[文档](/docs/components/date-field)）
+- **[ErrorMessage](#error-message)**：底层的错误信息组件，用于在非表单组件中展示错误。（[文档](/docs/components/error-message)）
+- **[ScrollShadow](#scroll-shadow)**：通过视觉阴影提示可滚动内容溢出，并可自动检测滚动位置。（[文档](/docs/components/scroll-shadow)）
+- **[SearchField](#search-field)**：带有内置搜索图标与清除按钮的搜索输入字段。（[文档](/docs/components/search-field)）
+- **[TagGroup](#tag-group)**：一组可聚焦的标签，支持键盘导航、选择与删除。（[文档](/docs/components/tag-group)）
+- **[TimeField](#time-field)**：时间输入字段，支持 label、description 与表单校验，基于 React Aria TimeField 构建。（[文档](/docs/components/time-field)）
+
+### ButtonGroup
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### DateField
+
+<ComponentPreview
+  name="date-field-basic"
+/>
+
+### ErrorMessage
+
+<ComponentPreview
+  name="error-message-basic"
+/>
+
+### SearchField
+
+<ComponentPreview
+  name="search-field-basic"
+/>
+
+### ScrollShadow
+
+<ComponentPreview
+  name="scroll-shadow-orientation"
+/>
+
+### TagGroup
+
+<ComponentPreview
+  name="tag-group-basic"
+/>
+
+### TimeField
+
+<ComponentPreview
+  name="time-field-basic"
+/>
+
+
+### 全宽支持
+
+为表单与输入组件新增 `fullWidth` 支持，可以让它们撑满容器的整个宽度。这在构建一致的表单布局与响应式设计时尤其有用。
+
+**支持的组件：**
+- [ButtonGroup](/docs/components/button-group)
+- [Button](/docs/components/button)
+- [ComboBox](/docs/components/combo-box)
+- [DateField](/docs/components/date-field)
+- [DateInputGroup](/docs/components/date-input-group)
+- [InputGroup](/docs/components/input-group)
+- [Input](/docs/components/input)
+- [NumberField](/docs/components/number-field)
+- [SearchField](/docs/components/search-field)
+- [Select](/docs/components/select)
+- [TextField](/docs/components/text-field)
+- [TextArea](/docs/components/textarea)
+- [TimeField](/docs/components/time-field)
+
+## 组件改进
+
+### 分隔线控制增强
+
+为 [Tabs](/docs/components/tabs)、[ButtonGroup](/docs/components/button-group) 与 [Accordion](/docs/components/accordion) 组件新增 `hideSeparator` 支持，可隐藏条目之间的分隔线，呈现更简洁、更纯粹的外观。
+
+**Tabs：**
+```tsx
+<Tabs hideSeparator>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="analytics">Analytics<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+</Tabs>
+```
+
+**ButtonGroup：**
+```tsx
+<ButtonGroup hideSeparator>
+  <Button>First</Button>
+  <Button>Second</Button>
+  <Button>Third</Button>
+</ButtonGroup>
+```
+
+**Accordion：**
+```tsx
+<Accordion hideSeparator>
+  <Accordion.Item>
+    <Accordion.Heading>
+      <Accordion.Trigger>Item 1</Accordion.Trigger>
+    </Accordion.Heading>
+    <Accordion.Panel>
+      <Accordion.Body>Content</Accordion.Body>
+    </Accordion.Panel>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 文档图标集成
+
+将 [@gravity-ui/icons](https://github.com/gravity-ui/icons) 集成到文档组件中，统一图标渲染，同时改进了 SSR 支持并提升了性能。
+
+## 依赖更新
+
+### React Aria Components v1.14.0
+
+将 [React Aria Components](https://react-aria.adobe.com/releases/v1-14-0) 升级到 v1.14.0。本次升级包含：
+
+**增强：**
+- SearchField：新增 `isReadOnly` 与 `isRequired` 渲染属性
+- Tooltip：新增 `shouldCloseOnPress` 属性
+- Tabs：支持在 tab 面板之间进行动画过渡
+- 其他：`useControlledState` 现已在 `setState` 回调中提供支持
+
+**修复：**
+- ComboBox：修复 VoiceOver 不读取 ListBox 项 `aria-label` 的问题
+- 日期与时间：增强了对 absolute 日期与日期时间字符串的错误处理
+- NumberField：在移动端滚动时不再误触发递增 / 递减
+- Overlay：修复了设置 boundary container 时 overlay 定位与 flip 的问题
+- Table：修复了在键盘导航期间进行拖放时的崩溃问题
+- 其他多项 bug 修复与改进
+
+完整变更请参阅 [React Aria Components v1.14.0 发布说明](https://react-aria.adobe.com/releases/v1-14-0)。
+
+### 其他依赖升级
+
+- `@internationalized/date`：3.10.0 → 3.10.1
+- `@radix-ui/react-avatar`：1.1.10 → 1.1.11
+- `tailwind-merge`：3.3.1 → 3.4.0
+- `tailwind-variants`：3.1.1 → 3.2.2
+
+## 样式修复
+
+### 表单组件的禁用状态
+
+修复了 [Input](/docs/components/input) 与 [TextArea](/docs/components/textarea) 组件的禁用状态样式。
+
+### 样式优化
+
+- **提高选择器精确度**：增强 CSS 选择器特异性，让样式隔离更好、性能更优
+- **动画增强**：改进了多个组件的动画性能与流畅度
+- **新增 no-highlight 工具类**：新增 `no-highlight` 工具类，用于防止交互元素中的文字被选中，从而提升体验
+- **优化 will-change 属性**：在多个组件中调整 `will-change` CSS 属性，以获得更好的动画性能
+- **移除全局滚动条样式**：移除了全局滚动条样式，避免与自定义滚动条实现冲突，并修复了 modal / overlay 的交互问题
+
+## ⚠️ 破坏性变更
+
+### AlertDialog 与 Modal 的 backdrop 变体
+
+`backdropVariant` / `variant` prop 的取值已从 `"solid"` 重命名为 `"opaque"`，以提升语义清晰度——「opaque」（不透明）更准确地描述了遮罩的视觉外观。
+
+**迁移：**
+
+将 AlertDialog 中所有 `backdropVariant="solid"` 替换为 `backdropVariant="opaque"`，将 Modal 中所有 `variant="solid"` 替换为 `variant="opaque"`：
+
+```tsx
+// Before
+<AlertDialog.Backdrop backdropVariant="solid">
+  <AlertDialog.Container>
+    {/* content */}
+  </AlertDialog.Container>
+</AlertDialog.Backdrop>
+
+<Modal.Backdrop variant="solid">
+  <Modal.Container>
+    {/* content */}
+  </Modal.Container>
+</Modal.Backdrop>
+
+// After
+<AlertDialog.Backdrop backdropVariant="opaque">
+  <AlertDialog.Container>
+    {/* content */}
+  </AlertDialog.Container>
+</AlertDialog.Backdrop>
+
+<Modal.Backdrop variant="opaque">
+  <Modal.Container>
+    {/* content */}
+  </Modal.Container>
+</Modal.Backdrop>
+```
+
+**可用的 backdrop 变体：**
+- `"opaque"` —— 深色不透明遮罩，完全遮挡背景（即此前的 `"solid"`）
+- `"blur"` —— 模糊遮罩，柔和地遮挡背景
+- `"transparent"` —— 透明遮罩，保持背景可见
+
+### 移除 `asChild` prop
+
+为提供更清晰的 API、更强的类型安全性以及更简单的使用方式，组件中的 `asChild` 模式已被移除。
+
+关于组件组合模式的更多细节，请参阅 [组合指南](/docs/handbook/composition)。
+
+## Bug 修复
+
+- 修复了 `isInvalid` 样式在 surface 背景上使用相关组件时的表现
+- 修复了 AlertDialog 与 Modal 关闭后重新渲染的问题
+- 修复了浮层关闭时未能正确清理的问题
+- 修复了文档中 Storybook 链接与导航的问题
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3（已更新）](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5923](https://github.com/heroui-inc/heroui/pull/5923)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-4.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-4.mdx
new file mode 100644
index 0000000..08f420e
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-4.mdx
@@ -0,0 +1,328 @@
+---
+title: v3.0.0-beta.4
+description: 全新的主题构建器、三个新组件（Autocomplete、Breadcrumbs、Toast）、Tabs 的 secondary 变体、Input / InputGroup 变体，以及多项改进。
+github:
+  pull: 6121
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 1 月 20 日</span>
+</div>
+
+<Callout type="warning">
+  **已修复关键构建问题**：此版本（beta.4）存在一个关键构建问题，已在 **beta.5** 中修复。请升级到 `@heroui/styles@3.0.0-beta.5` 与 `@heroui/react@3.0.0-beta.5`，以确保 TypeScript 声明文件能正确生成、导出能正确解析。
+</Callout>
+
+此版本引入了用于可视化主题定制的全新 [主题构建器](/themes)，三个新组件（[Autocomplete](/docs/components/autocomplete)、[Breadcrumbs](/docs/components/breadcrumbs)、[Toast](/docs/components/toast)），为 [Tabs](/docs/components/tabs) 添加 secondary 变体，为 [Input](/docs/components/input) 与 [InputGroup](/docs/components/input-group) 添加 primary / secondary 变体，InputGroup 新增对 TextArea 的支持，以及 ⚠️ **破坏性变更**：移除 Link 的下划线变体，并从表单组件中移除 `isInSurface` prop。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-dark@2x.jpg"
+  alt="HeroUI v3 Beta 4"
+  href="/docs/changelog/v3-0-0-beta-4"
+/>
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 主题构建器
+
+我们很高兴推出 **[主题构建器](/themes)** —— 用于创建与定制 HeroUI 主题的强大可视化工具。可在实时预览中构建你专属的主题，并导出可直接使用的 CSS。
+
+**主要特性：**
+- **可视化颜色编辑**：通过 OKLCH 颜色选择器以及直观的亮度、色度、色相滑块来调整颜色
+- **实时预览**：在实时组件预览中立即查看你的修改
+- **自定义强调色**：定义你的品牌色，并观察它如何贯穿到所有组件
+- **预设主题**：从精选预设（如 Default、Airbnb、Coinbase、Discord）入手
+- **导出即可用**：生成 CSS 变量，直接复制到你的项目即可
+- **浅色与深色模式**：可联动也可独立地同时定制两套主题
+- **键盘快捷键**：支持撤销 / 重做以及快速操作，提升工作流效率
+
+立即在 [v3.heroui.com/themes](/themes) 上试用。
+
+### 新组件
+
+本次发布共引入 **3 个** 新的基础组件：
+
+- **[Autocomplete](#autocomplete)**：将 Select 与过滤功能结合，让用户可以在选项列表中搜索并选择。（[文档](/docs/components/autocomplete)）
+- **[Breadcrumbs](#breadcrumbs)**：导航面包屑，用于展示当前页面在层级结构中的位置。（[文档](/docs/components/breadcrumbs)）
+- **[Toast](#toast)**：用于展示临时通知与消息，支持自动关闭以及自定义放置位置。（[文档](/docs/components/toast)）
+
+### Autocomplete
+
+<ComponentPreview
+  name="autocomplete-default"
+/>
+
+### Breadcrumbs
+
+<ComponentPreview
+  name="breadcrumbs-basic"
+/>
+
+### Toast
+
+<Callout type="warning">
+  该组件目前处于预览阶段，部分功能可能尚未按预期工作。
+</Callout>
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+## 组件改进
+
+### Tabs 的 secondary 变体
+
+为 [Tabs](/docs/components/tabs) 新增 `secondary` 变体，使用下划线指示器样式。该变体同时支持水平与垂直方向。
+
+<ComponentPreview
+  name="tabs-secondary"
+/>
+
+**用法：**
+
+```tsx
+<Tabs variant="secondary">
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="overview">
+        Overview
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="analytics">
+        Analytics
+        <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="overview">Content</Tabs.Panel>
+  <Tabs.Panel id="analytics">Content</Tabs.Panel>
+</Tabs>
+```
+
+### Input 变体
+
+为 [Input](/docs/components/input) 组件新增 `primary` 与 `secondary` 变体：
+
+- **`primary`**（默认）：带阴影的标准样式，适用于大多数场景
+- **`secondary`**：不带阴影的低调变体，适合在 Surface 组件内部使用
+
+<ComponentPreview
+  name="input-variants"
+/>
+
+### InputGroup 增强
+
+[InputGroup](/docs/components/input-group) 组件获得多项改进：
+
+**TextArea 支持**：可使用 `InputGroup.TextArea` 来构建带有 prefix 与 suffix 的多行文本输入。
+
+<ComponentPreview
+  name="input-group-with-textarea"
+/>
+
+**变体**：新增与 Input 组件相匹配的 `primary` 与 `secondary` 变体。
+
+<ComponentPreview
+  name="input-group-variants"
+/>
+
+### Button 与 ButtonGroup 的 outline 变体
+
+为 [Button](/docs/components/button) 与 [ButtonGroup](/docs/components/button-group) 同时新增 `outline` 变体，用于呈现描边样式。
+
+<ComponentPreview
+  name="button-outline-variant"
+/>
+
+### AlertDialog 尺寸支持
+
+为 [AlertDialog](/docs/components/alert-dialog) 组件新增尺寸支持，让你可以控制对话框的大小。
+
+<ComponentPreview
+  name="alert-dialog-sizes"
+/>
+
+### Checkbox 动画改进
+
+为 [Checkbox](/docs/components/checkbox) 提供更快的动画与更粗的描边宽度，反馈更明显。
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+### Link 的文本装饰
+
+[Link](/docs/components/link) 组件现在使用 Tailwind CSS 类来设置文本装饰，而不再依赖内置变体。这样既更灵活，也更贴合 Tailwind 的使用习惯。
+
+**可用的 Tailwind 工具类：**
+- `underline` —— 始终显示下划线
+- `no-underline` —— 移除下划线
+- `hover:underline` —— 仅在悬停时显示下划线
+- `decoration-primary`、`decoration-secondary` 等 —— 设置下划线颜色
+- `decoration-1`、`decoration-2`、`decoration-4` —— 控制下划线粗细
+- `underline-offset-1`、`underline-offset-2` 等 —— 调整下划线偏移
+
+<ComponentPreview
+  name="link-underline-and-offset"
+/>
+
+## ⚠️ 破坏性变更
+
+### Link 组件 —— 移除下划线相关变体
+
+Link 组件内置的 `underline` 与 `underlineOffset` prop 已被移除。请改用 Tailwind CSS 类来控制文本装饰。
+
+**之前：**
+```tsx
+<Link href="#" underline="hover" underlineOffset={4}>
+  Link text
+</Link>
+```
+
+**之后：**
+```tsx
+<Link href="#" className="hover:underline underline-offset-4">
+  Link text
+</Link>
+```
+
+**可用的 Tailwind 类：**
+- `underline`、`no-underline`、`hover:underline` —— 装饰线
+- `decoration-primary`、`decoration-muted` 等 —— 装饰线颜色
+- `decoration-solid`、`decoration-dashed`、`decoration-dotted` —— 装饰线样式
+- `decoration-1`、`decoration-2`、`decoration-4` —— 装饰线粗细
+- `underline-offset-1`、`underline-offset-2`、`underline-offset-4` —— 下划线偏移
+
+详见 [Link 文档](/docs/components/link)。
+
+### 表单组件 —— 移除 `isInSurface` prop
+
+`isInSurface` prop 以及自动 surface 检测已从基于表单的组件中移除。当你将表单组件放置在 Surface、Card 或其他基于 Surface 的容器中时，请改用 `variant="secondary"`。
+
+**之前：**
+```tsx
+<Surface>
+  {/* Input automatically detected surface context */}
+  <Input isInSurface />
+</Surface>
+```
+
+**之后：**
+```tsx
+<Surface>
+  {/* Use variant="secondary" for surface backgrounds */}
+  <Input variant="secondary" />
+</Surface>
+```
+
+**受影响的组件：**
+- Input
+- InputGroup
+- TextField
+- TextArea
+- SearchField
+- NumberField
+- DateField
+- TimeField
+- Select
+- ComboBox
+- Autocomplete
+
+`secondary` 变体提供不带阴影的低调样式，更适合在 surface 背景上使用。
+
+## 样式修复
+
+- **Button**：更新 secondary 按钮颜色，提升视觉一致性
+- **Checkbox**：优化动画速度并加粗描边，反馈更明显（详见 [Checkbox 动画改进](#checkbox-animation-improvements)）
+- **Link**：更新装饰线样式与过渡时长
+- **Focus Visible**：在 focus-visible 选择器中加入 `:not(:focus)`，避免与 hover 状态冲突
+- **Separator**：将固定样式仅应用到水平方向的分隔线
+
+## Bug 修复
+
+- 修复使用按钮变体样式的 Link
+- 修复 Safari 中 BEM 样式下 Fieldset 的 Flexbox 兼容性问题
+- 修复 SearchField 在空状态时未正确禁用清除按钮的问题
+- 修复 ButtonGroup 的 context 仅对直接子元素生效的问题
+- 修复 ButtonGroup 中 `BUTTON_GROUP_CHILD` 重新导出的类型声明
+
+## 依赖更新
+
+### 直接从 React Aria Components 重新导出
+
+HeroUI 现在直接从 `react-aria-components` 重新导出了一系列基元与工具，方便你访问。这些导出对于 [React Aria 框架配置](https://react-aria.adobe.com/frameworks) 尤其有用。
+
+**Provider：**
+- `RouterProvider` —— 配置 React Aria 的 Link 使用客户端路由器
+- `I18nProvider` —— 设置 React Aria Components 使用的 locale
+
+**Hook 与工具：**
+- `isRTL` —— 检查某个 locale 是否为从右到左
+- `useLocale` —— 访问当前 locale 与方向
+- `useFilter` —— 对集合进行过滤与排序
+
+**组件：**
+- `Collection` —— 用于管理列表的集合组件
+- `ListBoxLoadMoreItem` —— 用于加载更多条目的 ListBox 项
+
+**国际化工具：**
+- `getLocalizationScript` —— 获取用于服务端渲染的本地化脚本（来自 `react-aria-components/i18n`）
+
+以上这些都可以直接从 `@heroui/react` 引入：
+
+```tsx
+import {
+  RouterProvider,
+  I18nProvider,
+  isRTL,
+  useLocale,
+  useFilter,
+  getLocalizationScript
+} from "@heroui/react";
+```
+
+## 链接
+
+- [主题构建器](/themes)
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3（已更新）](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6121](https://github.com/heroui-inc/heroui/pull/6121)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-6.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-6.mdx
new file mode 100644
index 0000000..857d0bf
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-6.mdx
@@ -0,0 +1,373 @@
+---
+title: v3.0.0-beta.6
+description: 新增 6 个颜色组件（ColorPicker、ColorArea、ColorSlider、ColorField、ColorSwatch、ColorSwatchPicker）、Toast 改进，以及多项样式修复。
+github:
+  pull: 6129
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 6 日</span>
+</div>
+
+本次发布引入了完整的**颜色系统**，新增六个用于颜色选择与处理的组件：[ColorPicker](/docs/components/color-picker)、[ColorArea](/docs/components/color-area)、[ColorSlider](/docs/components/color-slider)、[ColorField](/docs/components/color-field)、[ColorSwatch](/docs/components/color-swatch) 与 [ColorSwatchPicker](/docs/components/color-swatch-picker)。同时还包含 [Separator](/docs/components/separator) 的新变体以及多项样式改进。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-dark@2x.jpg"
+  alt="HeroUI v3 Beta 6"
+  href="/docs/changelog/v3-0-0-beta-6"
+/>
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 颜色系统
+
+我们很高兴推出完整的**颜色系统**——一整套用于颜色选择、处理与展示的组件。这些组件基于 React Aria 的颜色基元构建，可以无缝协同工作。
+
+**主要特性：**
+- **完整的色彩空间支持**：支持 HSL、HSB 与 RGB 色彩空间
+- **基于通道的编辑**：可单独操作每一个颜色通道（hue、saturation、lightness、brightness、red、green、blue、alpha）
+- **默认无障碍**：完整支持键盘导航与屏幕阅读器
+- **可组合的设计**：自由搭配组件，构建你自己的颜色选择器
+
+### 新组件
+
+本次发布共引入 **6 个** 新的颜色组件：
+
+- **[ColorPicker](#colorpicker)**：完整的颜色选择器，包含 trigger、popover 以及可组合的内部部件。（[文档](/docs/components/color-picker)）
+- **[ColorArea](#colorarea)**：二维渐变区域，可同时选择两个颜色通道。（[文档](/docs/components/color-area)）
+- **[ColorSlider](#colorslider)**：单通道滑块，用于精细调整颜色。（[文档](/docs/components/color-slider)）
+- **[ColorField](#colorfield)**：用于输入与编辑颜色值的文本框。（[文档](/docs/components/color-field)）
+- **[ColorSwatch](#colorswatch)**：可视化的颜色预览，支持透明度。（[文档](/docs/components/color-swatch)）
+- **[ColorSwatchPicker](#colorswatchpicker)**：可选的颜色块网格，便于快速选择颜色。（[文档](/docs/components/color-swatch-picker)）
+
+### ColorPicker
+
+ColorPicker 是一个复合组件，将所有颜色组件组合在一起，提供完整的颜色选择体验。
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### ColorArea
+
+二维渐变区域，可同时选择两个颜色通道，通常用于 saturation 与 brightness。
+
+<ComponentPreview
+  name="color-area-basic"
+/>
+
+### ColorSlider
+
+用于调整单个颜色通道（如 hue、saturation、lightness 或 alpha）的滑块。
+
+<ComponentPreview
+  name="color-slider-basic"
+/>
+
+**不同的通道：**
+
+<ComponentPreview
+  name="color-slider-channels"
+/>
+
+### ColorField
+
+用于直接输入颜色值的文本输入框，支持多种颜色格式。
+
+<ComponentPreview
+  name="color-field-basic"
+/>
+
+### ColorSwatch
+
+颜色值的可视化展示，支持透明度图案。
+
+<ComponentPreview
+  name="color-swatch-basic"
+/>
+
+### ColorSwatchPicker
+
+色块网格，可从预定义的调色板中快速选择颜色。
+
+<ComponentPreview
+  name="color-swatch-picker-basic"
+/>
+
+## 组件改进
+
+### Toast 增强
+
+[Toast](/docs/components/toast) 组件经过了重大改进，新增了多项功能并提升了稳定性（#6151）：
+
+**新功能：**
+- **加载状态**：新增 `isLoading` prop，会显示一个 spinner 替代默认指示器
+- **默认超时**：Toast 现在默认 4 秒后自动关闭（可通过 `timeout` prop 配置）
+- **宽度控制**：在 `Toast.Provider` 上新增 `width` prop，可自定义 Toast 的宽度
+- **自适应高度**：Toast 会根据内容自适应高度
+- **更好的堆叠效果**：通过绝对定位与高度同步，修复了 Toast 堆叠时出现的布局抖动
+- **更稳健的关闭处理**：将 `onClose` 回调延迟执行，避免 Toast 过渡死锁
+- **仅最前 Toast 显示关闭按钮**：关闭按钮仅出现在最前一个 Toast 上，UI 更加干净
+- **Promise 支持增强**：改进了 `toast.promise()`，加载状态与错误处理更加完善
+
+**新增演示：**
+- Promise 与加载状态
+- 回调与超时处理
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+### Separator 变体
+
+为 [Separator](/docs/components/separator) 组件新增了变体，提供不同的视觉风格。
+
+### Chip 组件 —— Label slot
+
+[Chip](/docs/components/chip) 组件现在支持 `Chip.Label` 子组件，以获得更好的视觉对齐。当移除起始或末尾的内容（如图标）时，标签文字会过于贴近 Chip 的边缘。为了向后兼容，纯文本的 children 会自动被包裹在 `<Chip.Label>` 中。
+
+**用法：**
+
+```tsx
+import { Chip } from '@heroui/react';
+
+// Automatic wrapping (backward compatible)
+<Chip>Label text</Chip>
+
+// Explicit label with custom styling
+<Chip>
+  <Chip.Label className="font-bold">Custom Label</Chip.Label>
+</Chip>
+
+// Mixing icons and labels
+<Chip>
+  <Icon icon="gravity-ui:check" />
+  <Chip.Label>With Icon</Chip.Label>
+</Chip>
+```
+
+## 样式修复
+
+- **浮层内容**：修复了浮层内容上的模糊效果（#6136）
+- **Invalid 字段**：在字段处于 invalid 状态时，将 ring 改为 outline（#6184）
+- **Link 与按钮**：修复了使用按钮变体的 Link 组件的样式（#6138）
+- **Toast 内容**：修复了 Toast 内容的垂直对齐问题（#6147）
+- **Safari SVG**：修复了 SVG 在 Safari 中位置偏移的问题（#6149）
+- **Placeholder 颜色**：将 placeholder 的颜色与输入文本对齐（#6139)
+- **Tooltip**：从 tooltip 触发组件中移除了 cursor 样式
+- **CSS 变量**：让计算变量仅依赖根变量（#6154）
+
+## Bug 修复
+
+- 修复了视图过渡期间页面交互不可用的问题（#6128）
+- 修复了 Markdown URL 的格式化问题（#6162）
+- 修复了指向 ComboBox 页面的链接错误（#6164）
+- 修复了 `index.css` 中 Autocomplete 样式的引入顺序
+- 修复了 CSS 类名的连字符格式（#6191）
+
+## ⚠️ 破坏性变更
+
+### Toast 组件 —— Container 重命名为 Provider
+
+为提升语义清晰度，`Toast.Container` 已重命名为 `Toast.Provider`（#6151）。
+
+**之前：**
+```tsx
+<Toast.Container placement="bottom" />
+```
+
+**之后：**
+```tsx
+<Toast.Provider placement="bottom" />
+```
+
+**其他变更：**
+- 默认的 `gap` prop 从 `14` 改为 `12` 像素
+- 默认 `timeout` 现在为 `4000`（4 秒），无需再显式设置
+- 为保持一致性，`Toast.Action` 已重命名为 `Toast.ActionButton`
+
+### CSS 类名命名约定
+
+为了一致性，CSS 类名已统一改为连字符格式（#6141）。这一调整更贴合 BEM 规范，也提升了与 Tailwind CSS 的兼容性。
+
+**重要说明**：`textarea` 类名最初被改为 `text-area`，但由于与 Tailwind 原生的 `textarea` 类名冲突，已在 PR #6191 中回滚为 `textarea`。TextArea 组件相关的类名无需修改。
+
+#### 组件类名变更
+
+以下 CSS 类名已更新。如果你的自定义 CSS 直接使用了这些类名，请同步更新选择器：
+
+| 组件 | 旧类名 | 新类名 | 说明 |
+|------|--------|--------|------|
+| **ComboBox** | `.combobox` | `.combo-box` | 全部相关类名同步更新 |
+| | `.combobox__input-group` | `.combo-box__input-group` | |
+| | `.combobox__trigger` | `.combo-box__trigger` | |
+| | `.combobox__popover` | `.combo-box__popover` | |
+| | `.combobox--full-width` | `.combo-box--full-width` | |
+| **ListBox** | `.listbox` | `.list-box` | 全部相关类名同步更新 |
+| **ListBoxItem** | `.listbox-item` | `.list-box-item` | 全部相关类名同步更新 |
+| | `.listbox-item__indicator` | `.list-box-item__indicator` | |
+| | `.listbox-item--default` | `.list-box-item--default` | |
+| | `.listbox-item--danger` | `.list-box-item--danger` | |
+| **ListBoxSection** | `.listbox-section` | `.list-box-section` | 全部相关类名同步更新 |
+| **TextArea** | `.textarea` | `.textarea` | **未变更** —— 为避免与 Tailwind 冲突已回滚 |
+
+#### 迁移指南
+
+**之前：**
+```css
+/* Custom styles targeting old class names */
+.combobox {
+  /* styles */
+}
+
+.listbox-item {
+  /* styles */
+}
+```
+
+**之后：**
+```css
+/* Update to new hyphenated class names */
+.combo-box {
+  /* styles */
+}
+
+.list-box-item {
+  /* styles */
+}
+```
+
+**JavaScript / TypeScript 更新：**
+
+如果你在 JavaScript 或 TypeScript 代码中使用了这些类名：
+
+```tsx
+// Before
+<div className="combobox" />
+<ListBoxItem className="listbox-item" />
+
+// After
+<div className="combo-box" />
+<ListBoxItem className="list-box-item" />
+```
+
+**说明**：组件 props 与 TypeScript 类型保持不变，仅 CSS 类名做了更新。
+
+### 移除的 CSS 变量
+
+作为 surface 颜色重构的一部分，部分 CSS 变量已被移除（#6204）。这些变量要么改为直接引用其他变量，要么被完全移除。
+
+#### Surface 颜色变量
+
+以下经过计算的 surface 颜色变量已被移除，并改为直接引用对应的变量：
+
+**已移除：**
+- `--color-surface-secondary`（之前通过 `color-mix` 计算得到）
+- `--color-surface-tertiary`（之前通过 `color-mix` 计算得到）
+
+**替代方案：**
+这些变量现在直接引用 `variables.css` 中定义的基础变量：
+- `--color-surface-secondary` → 直接使用 `var(--surface-secondary)`
+- `--color-surface-tertiary` → 直接使用 `var(--surface-tertiary)`
+
+基础变量 `--surface-secondary` 与 `--surface-tertiary` 现在直接定义在 `variables.css` 中，而不再在 `theme.css` 中通过计算得出。
+
+#### On Surface 颜色变量
+
+所有 `--color-on-surface-*` 变量都已被完全移除：
+
+**已移除：**
+- `--color-on-surface`
+- `--color-on-surface-foreground`
+- `--color-on-surface-hover`
+- `--color-on-surface-focus`
+- `--color-on-surface-secondary`
+- `--color-on-surface-secondary-foreground`
+- `--color-on-surface-secondary-hover`
+- `--color-on-surface-secondary-focus`
+- `--color-on-surface-tertiary`
+- `--color-on-surface-tertiary-foreground`
+- `--color-on-surface-tertiary-hover`
+- `--color-on-surface-tertiary-focus`
+
+**迁移方式：**
+
+如果你之前用到了这些变量，请改用对应的 surface 变量：
+
+```css
+/* Before */
+.element {
+  background: var(--color-on-surface);
+  color: var(--color-on-surface-foreground);
+}
+
+.element:hover {
+  background: var(--color-on-surface-hover);
+}
+
+/* After */
+.element {
+  background: var(--surface-secondary);
+  color: var(--surface-secondary-foreground);
+}
+
+.element:hover {
+  background: color-mix(in oklab, var(--surface-secondary) 92%, var(--surface-secondary-foreground) 8%);
+}
+```
+
+或者使用 Tailwind 工具类：
+```tsx
+// Before
+<div className="bg-on-surface text-on-surface-foreground" />
+
+// After
+<div className="bg-surface-secondary text-surface-secondary-foreground" />
+```
+
+**相关 PR：** [#6204](https://github.com/heroui-inc/heroui/pull/6204)
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6201](https://github.com/heroui-inc/heroui/pull/6201)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-7.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-7.mdx
new file mode 100644
index 0000000..89fbba4
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-7.mdx
@@ -0,0 +1,324 @@
+---
+title: v3.0.0-beta.7
+description: 新增 4 个组件（Calendar、RangeCalendar、DatePicker、DateRangePicker）以及多项 API 改进。
+github:
+  pull: 6237
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 2 月 19 日</span>
+</div>
+
+本次发布新增 4 个组件：[Calendar](/docs/components/calendar)、[RangeCalendar](/docs/components/range-calendar)、[DatePicker](/docs/components/date-picker) 与 [DateRangePicker](/docs/components/date-range-picker)。同时还引入了 [Switch.Content](#switchcontent)，用于将 label 与 description 组合到 Switch 控件旁边；以及 [Tabs.Separator](#tabsseparator)，用于在 Tab 之间按需添加分隔线。
+
+⚠️ **破坏性变更**：从 Tabs 中移除了 `hideSeparator`；`DateInputGroup` 与 `ColorInputGroup` 已分别合并到 `DateField.Group`、`TimeField.Group` 与 `ColorField.Group` 之下。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-dark@2x.jpg"
+  alt="HeroUI v3 Beta 7"
+  href="/docs/changelog/v3-0-0-beta-7"
+/>
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 日期与时间体系
+
+**日期与时间** —— Calendar、DatePicker、RangeCalendar 与 DateRangePicker 均基于 React Aria 的日期基元构建。支持国际化、时区，以及完整的键盘导航与 ARIA 无障碍能力。
+
+**主要特性：**
+- **历法系统**：公历、佛历、波斯历等
+- **年份选择器**：用于快速跳转年份的浮层
+- **单元格指示器**：在单元格上展示事件、可用状态或状态点
+- **范围选择**：日期范围带有视觉高亮
+- **无障碍**：键盘导航、屏幕阅读器、ARIA 全部支持
+
+所有日期值都使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 提供的类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）。可以用 [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) 覆盖区域设置，并通过 [`useLocale`](https://react-aria.adobe.com/useLocale) 读取它。
+
+### 新组件
+
+- **[Calendar](#calendar)**：单日期选择，支持年份选择器、指示器与多月份显示。（[文档](/docs/components/calendar)）
+- **[RangeCalendar](#rangecalendar)**：日期范围选择，支持范围高亮与多月份显示。（[文档](/docs/components/range-calendar)）
+- **[DatePicker](#datepicker)**：日期输入框 + popover 日历。（[文档](/docs/components/date-picker)）
+- **[DateRangePicker](#daterangepicker)**：两个日期输入框 + popover 范围日历。（[文档](/docs/components/date-range-picker)）
+
+### Calendar
+
+支持单日期选择的日历，包含年份选择器、单元格指示器、多月份视图以及国际化历法。
+
+<ComponentPreview
+  name="calendar-basic"
+/>
+
+**年份选择器：**
+
+<ComponentPreview
+  name="calendar-year-picker"
+/>
+
+
+**国际化历法：**
+
+<ComponentPreview
+  name="calendar-international-calendar"
+/>
+
+### RangeCalendar
+
+日期范围选择，支持范围高亮与多月份视图。
+
+<ComponentPreview
+  name="range-calendar-basic"
+/>
+
+**多月份显示：**
+
+<ComponentPreview
+  name="range-calendar-multiple-months"
+/>
+
+### DatePicker
+
+日期输入框 + popover 日历。支持格式选项、国际化、自定义指示器与表单校验。
+
+<ComponentPreview
+  name="date-picker-basic"
+/>
+
+**日期与时间（搭配 TimeField）：**
+
+<ComponentPreview
+  name="date-picker-format-options"
+/>
+
+### DateRangePicker
+
+两个日期输入框 + popover 范围日历。
+
+<ComponentPreview
+  name="date-range-picker-basic"
+/>
+
+## API 改进
+
+### Switch.Content
+
+`Switch.Content` 用于将 label 与 description 组合到 Switch 控件旁边（[#6240](https://github.com/heroui-inc/heroui/pull/6240)）。
+
+**之前：**
+```tsx
+import { Switch, Label, Description } from '@heroui/react';
+
+<Switch>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+  <Switch.Content>
+    <Label>Email notifications</Label>
+    <Description>Get notified when someone mentions you</Description>
+  </Switch.Content>
+</Switch>
+```
+
+### Tabs.Separator
+
+[Tabs](/docs/components/tabs) 组件现在新增了一个显式的 `Tabs.Separator` 子组件，用于在 Tab 之间添加视觉分隔线。它取代了之前自动生成的 CSS 伪元素分隔线以及 `hideSeparator` prop（[#6243](https://github.com/heroui-inc/heroui/pull/6243)）。
+
+分隔线现在改为 **按需启用** —— 在希望出现分隔线的 `<Tabs.Tab>` 内部添加 `<Tabs.Separator />` 即可。
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-with-separator"
+/>
+
+### Field 子组件的合并
+
+`DateField`、`TimeField` 与 `ColorField` 现在直接暴露各自的输入组子组件，不再需要单独引入 `DateInputGroup` 或 `ColorInputGroup`。具体的迁移方式请参阅 [破坏性变更](#-breaking-changes)。
+
+### Breadcrumbs 修复
+
+传给 `Breadcrumbs.Item` 的 props 现在会正确转发到底层的 `Link`（[#6233](https://github.com/heroui-inc/heroui/pull/6233)）。
+
+## 样式修复
+
+- **ListBox Item**：将悬停背景色从 `bg-default-hover` 调整为 `bg-default`，以保持一致性
+- **Date Input Group**：将段（segment）文本从 `tabular-nums` 调整为 `text-nowrap`，优化布局
+- **Date Input Group**：改进 focus-within 样式，使其将日期选择器触发器排除在字段聚焦高亮之外
+
+## 依赖更新
+
+- **React Aria Components**：从 `1.14.0` 升级到 `1.15.0` —— 新增了 [`render` prop](https://react-aria.adobe.com/customization#dom-elements)，可用于自定义任何 React Aria 组件渲染的 DOM 元素（适用于路由链接、Motion 等动画库）
+- **@react-aria/utils**：从 `3.32.0` 升级到 `3.33.0`
+- **@react-types/shared**：从 `3.32.1` 升级到 `3.33.0`
+- **@internationalized/date**：从 `3.10.1` 升级到 `3.11.0` —— 日期字段现在改为在失焦时进行约束，而不是在输入过程中实时约束
+- 新增 `@react-aria/i18n` 与 `@react-stately/utils`，用于日历的国际化
+
+## ⚠️ 破坏性变更
+
+### Tabs —— 移除 `hideSeparator` prop
+
+`hideSeparator` prop 已从 Tabs 组件中移除。分隔线现在改为 **按需启用**，通过新增的 `<Tabs.Separator />` 子组件来添加，而不再通过 CSS 伪元素自动生成（[#6243](https://github.com/heroui-inc/heroui/pull/6243)）。
+
+**之前：**
+```tsx
+{/* Separators shown by default, hidden via prop */}
+<Tabs hideSeparator>
+  <Tabs.List>
+    <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
+    <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
+  </Tabs.List>
+</Tabs>
+```
+
+**之后：**
+```tsx
+{/* No separators by default — explicitly add them where needed */}
+<Tabs>
+  <Tabs.List>
+    <Tabs.Tab id="tab1"><Tabs.Indicator />Tab 1</Tabs.Tab>
+    <Tabs.Tab id="tab2"><Tabs.Separator /><Tabs.Indicator />Tab 2</Tabs.Tab>
+  </Tabs.List>
+</Tabs>
+```
+
+**CSS 变更：**
+- Tab 的分隔线样式已从伪元素（`.tabs__tab:not(:first-child):before`）迁移到独立的 `.tabs__separator` 类
+- 已移除 `[data-hide-separator]` 这一 data 属性
+
+### Field 子组件 API 变更
+
+`DateInputGroup` 与 `ColorInputGroup` 不再从 `@heroui/react` 直接导出。它们的子组件已分别合并到对应的 Field 组件之下（`DateField`、`TimeField`、`ColorField`）。
+
+#### DateField 变更
+
+**之前：**
+```tsx
+import {DateField, Label, DateInputGroup, Description} from '@heroui/react';
+
+<DateField>
+  <Label>Date</Label>
+  <DateInputGroup>
+    <DateInputGroup.Prefix>...</DateInputGroup.Prefix>
+    <DateInputGroup.Input>
+      {(segment) => <DateInputGroup.Segment segment={segment} />}
+    </DateInputGroup.Input>
+    <DateInputGroup.Suffix>...</DateInputGroup.Suffix>
+  </DateInputGroup>
+  <Description>Pick a date</Description>
+</DateField>
+```
+
+**之后：**
+```tsx
+import {DateField, Label, Description} from '@heroui/react';
+
+<DateField>
+  <Label>Date</Label>
+  <DateField.Group>
+    <DateField.Prefix>...</DateField.Prefix>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+    <DateField.Suffix>...</DateField.Suffix>
+  </DateField.Group>
+  <Description>Pick a date</Description>
+</DateField>
+```
+
+#### TimeField 变更
+
+模式与 DateField 相同：
+
+| 之前 | 之后 |
+|------|------|
+| `DateInputGroup` | `TimeField.Group` |
+| `DateInputGroup.Input` | `TimeField.Input` |
+| `DateInputGroup.Segment` | `TimeField.Segment` |
+| `DateInputGroup.Prefix` | `TimeField.Prefix` |
+| `DateInputGroup.Suffix` | `TimeField.Suffix` |
+
+#### ColorField 变更
+
+| 之前 | 之后 |
+|------|------|
+| `ColorInputGroup` | `ColorField.Group` |
+| `ColorInputGroup.Input` | `ColorField.Input` |
+| `ColorInputGroup.Prefix` | `ColorField.Prefix` |
+| `ColorInputGroup.Suffix` | `ColorField.Suffix` |
+
+**用法：**
+
+```tsx
+import {ColorField, Label, ColorInputGroup, ColorSwatch} from '@heroui/react';
+
+<ColorField>
+  <Label>Color</Label>
+  <ColorInputGroup>
+    <ColorInputGroup.Prefix>
+      <ColorSwatch color="#000" />
+    </ColorInputGroup.Prefix>
+    <ColorInputGroup.Input />
+  </ColorInputGroup>
+</ColorField>
+```
+
+**之后：**
+```tsx
+import {ColorField, Label, ColorSwatch} from '@heroui/react';
+
+<ColorField>
+  <Label>Color</Label>
+  <ColorField.Group>
+    <ColorField.Prefix>
+      <ColorSwatch color="#000" />
+    </ColorField.Prefix>
+    <ColorField.Input />
+  </ColorField.Group>
+</ColorField>
+```
+
+> **说明：** 底层的 CSS 类名（`.date-input-group`、`.color-input-group` 等）保持不变，仅 JavaScript 引入路径与组件名称发生了变化。
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [设计系统 - Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6237](https://github.com/heroui-inc/heroui/pull/6237)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-8.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-8.mdx
new file mode 100644
index 0000000..493bc23
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-beta-8.mdx
@@ -0,0 +1,174 @@
+---
+title: v3.0.0-beta.8
+description: 新增 3 个组件（Badge、Pagination、Table）、DateField 的多项改进，以及关键的 API / 样式修复。
+github:
+  pull: 6270
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 3 月 2 日</span>
+</div>
+
+本次发布新增三个组件：[Badge](/docs/components/badge)、[Pagination](/docs/components/pagination) 与 [Table](/docs/components/table)，并为 [DateField](/docs/components/date-field) 与 [TimeField](/docs/components/time-field) 提供了新的 `InputContainer` 组合 API。
+
+⚠️ **破坏性变更**：TextField 的 CSS 类已从 `.text-field` 重命名为 `.textfield`。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-dark@2x.jpg"
+  alt="HeroUI v3 Beta 8"
+  href="/docs/changelog/v3-0-0-beta-8"
+/>
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 新组件
+
+- **[Badge](#badge)**：紧凑的状态 + 计数指示器，可配置颜色、变体、放置位置与尺寸。（[文档](/docs/components/badge)）
+- **[Pagination](#pagination)**：分页相关的复合组件基元，提供摘要、省略号以及上一页 / 下一页等控件。（[文档](/docs/components/pagination)）
+- **[Table](#table)**：数据表格基元，支持排序、选择、列宽调整、异步加载以及表脚组合。（[文档](/docs/components/table)）
+
+### Badge
+
+新增徽章基元，可用于计数、标签以及通过 `Badge.Anchor` 与 `Badge.Label` 锚定的浮层。
+
+<ComponentPreview
+  name="badge-basic"
+/>
+
+### Pagination
+
+新增导航组件，由可组合的部件构成（`Root`、`Content`、`Item`、`Link`、`Previous`、`Next`、`Summary`、`Ellipsis`）。
+
+<ComponentPreview
+  name="pagination-with-ellipsis"
+/>
+
+### Table
+
+基于 React Aria 构建的复合数据表格，支持可排序的列、行选择、自定义单元格、加载更多哨兵行以及可调整宽度的列。
+
+<ComponentPreview
+  name="table-basic"
+/>
+
+**自定义单元格：**
+
+<ComponentPreview
+  name="table-custom-cells"
+/>
+
+**分页：**
+
+<ComponentPreview
+  name="table-pagination"
+/>
+
+**空状态：**
+
+<ComponentPreview
+  name="table-empty-state"
+/>
+
+## 组件 + API 改进
+
+### DateField 与 TimeField 的增强
+
+`DateField` 与 `TimeField` 现在暴露了 `InputContainer`，用于在前缀与后缀内容之间包裹输入段（segment）。
+
+**之前：**
+```tsx
+<DateField.Group>
+  <DateField.Prefix>...</DateField.Prefix>
+  <DateField.Input>
+    {(segment) => <DateField.Segment segment={segment} />}
+  </DateField.Input>
+  <DateField.Suffix>...</DateField.Suffix>
+</DateField.Group>
+```
+
+**之后：**
+```tsx
+<DateField.Group>
+  <DateField.Prefix>...</DateField.Prefix>
+  <DateField.InputContainer>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+  </DateField.InputContainer>
+  <DateField.Suffix>...</DateField.Suffix>
+</DateField.Group>
+```
+
+<ComponentPreview
+  name="date-range-picker-input-container"
+/>
+
+## ⚠️ 破坏性变更
+
+### TextField 类名 + 路径重命名
+
+为避免与 Tailwind 的 `text-*` 工具类前缀冲突，TextField 的样式命名已统一调整。
+
+| 组件 | 旧类名 | 新类名 | 说明 |
+|------|--------|--------|------|
+| **TextField Root** | `.text-field` | `.textfield` | 根类名重命名 |
+| **TextField Full Width** | `.text-field--full-width` | `.textfield--full-width` | 修饰类重命名 |
+
+同一变更涉及的其他重命名：
+- 样式文件：`text-field.css` -> `textfield.css`
+- 样式导出路径：`@heroui/styles/src/components/text-field` -> `@heroui/styles/src/components/textfield`
+
+## 样式修复
+
+- **RangeCalendar**：为日历单元格添加圆角，优化范围选择的视觉效果（[#6270](https://github.com/heroui-inc/heroui/pull/6270)）
+
+## Bug 修复
+
+- 通过将 `isRequired` 转化为 `data-required`，为 **DatePicker** 与 **DateRangePicker** 补齐了必填状态的红色星号行为（[#6270](https://github.com/heroui-inc/heroui/pull/6270)）
+- 修复了 **Autocomplete** 与 **Select** 中触发器无效状态样式缺失的问题——将 invalid 样式限定在根状态范围内（[#6270](https://github.com/heroui-inc/heroui/pull/6270)）
+- 更新了 TextField 的文档与演示引用，使其指向新的 `textfield-*` demo key 以及对应的源码 / 样式路径（[#6270](https://github.com/heroui-inc/heroui/pull/6270)）
+
+## 链接
+
+- [组件文档](/docs/components)
+- [设计系统 - Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6270](https://github.com/heroui-inc/heroui/pull/6270)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0-rc-1.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0-rc-1.mdx
new file mode 100644
index 0000000..b2c9cd2
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0-rc-1.mdx
@@ -0,0 +1,248 @@
+---
+title: v3.0.0-rc.1
+description: 新增 7 个组件（Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle、Toolbar），Table 与 ListBox 支持虚拟化，ButtonGroup 多项改进，以及若干 bug 修复。
+github:
+  pull: 6285
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 3 月 14 日</span>
+</div>
+
+新增七个组件：[Drawer](/docs/components/drawer)、[ToggleButton](/docs/components/toggle-button)、[ToggleButtonGroup](/docs/components/toggle-button-group)、[Meter](/docs/components/meter)、[ProgressBar](/docs/components/progress-bar)、[ProgressCircle](/docs/components/progress-circle) 与 [Toolbar](/docs/components/toolbar)。Table 与 ListBox 支持虚拟化，ButtonGroup 新增 `Separator` 子组件并支持垂直方向，React Aria Components 升级到 v1.16.0。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-dark@2x.jpg"
+  alt="HeroUI v3 RC 1"
+  href="/docs/changelog/v3-0-0-rc-1"
+/>
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### 新组件
+
+- **[Drawer](#drawer)**：滑出式面板，支持拖拽关闭、4 种放置位置、多种背景遮罩变体以及可滚动的内容区（[文档](/docs/components/drawer)）
+- **[ToggleButton](#toggle-button)**：选中 / 未选中两态的切换按钮，支持全部按钮变体以及仅图标模式（[文档](/docs/components/toggle-button)）
+- **[ToggleButtonGroup](#toggle-button-group)**：单选或多选的切换按钮组，支持 attached / detached 布局以及方向设置（[文档](/docs/components/toggle-button-group)）
+- **[Meter](#meter)**：在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等（[文档](/docs/components/meter)）
+- **[ProgressBar](#progress-bar)**：线性进度条，支持确定 / 不确定态、多种颜色与自定义格式（[文档](/docs/components/progress-bar)）
+- **[ProgressCircle](#progress-circle)**：基于 SVG 的环形进度条，可自定义轨道圆与填充圆（[文档](/docs/components/progress-circle)）
+- **[Toolbar](#toolbar)**：将按钮、切换控件与分隔线按水平或垂直方向组合在一起的工具栏组件（[文档](/docs/components/toolbar)）
+
+### Drawer
+
+带有背景遮罩的滑出式浮层面板，支持顶部 / 底部 / 左侧 / 右侧四种放置位置、拖拽关闭手势以及多种背景遮罩变体。复合部件包括：`Trigger`、`Backdrop`、`Content`、`Dialog`、`Header`、`Heading`、`Body`、`Footer`、`Handle`、`CloseTrigger`。
+
+<ComponentPreview
+  name="drawer-basic"
+/>
+
+**放置位置：**
+
+<ComponentPreview
+  name="drawer-placements"
+/>
+
+**配合表单使用：**
+
+<ComponentPreview
+  name="drawer-with-form"
+/>
+
+### Toggle Button
+
+具备状态的切换按钮，可在选中与未选中之间切换。支持全部按钮变体与尺寸、仅图标模式，以及受控 / 非受控两种使用方式。
+
+<ComponentPreview
+  name="toggle-button-basic"
+/>
+
+**变体：**
+
+<ComponentPreview
+  name="toggle-button-variants"
+/>
+
+### Toggle Button Group
+
+单选或多选的切换按钮组。支持 attached（连接式）与 detached（分离式）两种布局、垂直方向、整宽展示，以及一个 `Separator` 子组件。
+
+<ComponentPreview
+  name="toggle-button-group-basic"
+/>
+
+**选择模式：**
+
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>
+
+**Attached 模式：**
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### Meter
+
+在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等。复合部件包括：`Root`、`Output`、`Track`、`Fill`。
+
+<ComponentPreview
+  name="meter-basic"
+/>
+
+**颜色：**
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+### Progress Bar
+
+线性进度指示器，支持确定 / 不确定态、颜色变体、多种尺寸以及自定义数值显示。复合部件包括：`Root`、`Output`、`Track`、`Fill`。
+
+<ComponentPreview
+  name="progress-bar-basic"
+/>
+
+**不确定态：**
+
+<ComponentPreview
+  name="progress-bar-indeterminate"
+/>
+
+### Progress Circle
+
+基于 SVG 的环形进度条，提供 `TrackCircle` 与 `FillCircle` 两个子组件，便于直接控制 SVG。同时支持确定与不确定态。
+
+<ComponentPreview
+  name="progress-circle-basic"
+/>
+
+**自定义 SVG：**
+
+<ComponentPreview
+  name="progress-circle-custom-svg"
+/>
+
+### Toolbar
+
+将按钮、切换按钮与分隔线组合到一个具备无障碍语义的工具栏中。支持水平或垂直方向，可与 `ButtonGroup` 和 `ToggleButtonGroup` 组合使用。
+
+<ComponentPreview
+  name="toolbar-basic"
+/>
+
+**配合 Button Group 使用：**
+
+<ComponentPreview
+  name="toolbar-with-button-group"
+/>
+
+## 组件改进
+
+### ButtonGroup 的增强
+
+新增的 `ButtonGroup.Separator` 子组件可在按钮之间显式插入一条视觉分隔线。在水平和垂直两种方向下都能正常工作。
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### Table 与 ListBox 的虚拟化
+
+Table 与 ListBox 现在可以借助 React Aria 的 `Virtualizer` 来支持大数据集的虚拟化渲染。`Virtualizer`、`TableLayout` 和 `ListLayout` 都已从 `@heroui/react` 重新导出。
+
+<ComponentPreview
+  name="table-virtualization"
+/>
+
+### ButtonGroup 的方向
+
+`ButtonGroup` 现在接受一个 `orientation` prop（`"horizontal"` | `"vertical"`），并在两种方向下都正确处理边框圆角与分隔线方向。根元素也已从 `<div>` 升级为 React Aria 的 `Group`，从而具备正确的 `role="group"` 语义。
+
+<ComponentPreview
+  name="button-group-orientation"
+/>
+
+### ButtonGroup 的焦点环
+
+成组按钮上的焦点环现在使用 `ring-inset`，确保焦点环留在按钮内部边界，而不会与相邻按钮重叠。
+
+### 细粒度的组件引入
+
+`@heroui/react` 现在支持按组件的子路径入口，方便更明确地按需引入（[#6301](https://github.com/heroui-inc/heroui/pull/6301)）：
+
+```tsx
+// Before — root entrypoint
+import { Button } from "@heroui/react";
+
+// After — granular subpath import
+import { Button } from "@heroui/react/button";
+```
+
+## 依赖更新
+
+将 `react-aria-components` 从 v1.15.1 升级到 v1.16.0，同时升级了相关包：
+
+| 包名 | 旧版本 | 新版本 |
+|------|--------|--------|
+| `react-aria-components` | 1.15.1 | 1.16.0 |
+| `@react-aria/i18n` | 3.12.15 | 3.12.16 |
+| `@react-aria/utils` | 3.33.0 | 3.33.1 |
+| `@react-types/shared` | 3.33.0 | 3.33.1 |
+| `@react-types/color` | 3.1.3 | 3.1.4 |
+| `@internationalized/date` | 3.11.0 | 3.12.0 |
+| `@react-stately/data` | 3.15.1 | 3.15.2 |
+
+## Bug 修复
+
+- **InputGroup**：聚焦样式现在仅在实际的 input / textarea 获得焦点时（`:has([data-slot]:focus)`）才会触发，不再因 `:focus-within` 而被任意可聚焦的子元素触发（[#6274](https://github.com/heroui-inc/heroui/pull/6274)）
+- **Avatar**：fallback 元素现在会从父级继承 `border-radius`，而不再硬编码为 `rounded-full`，因此 `className` 覆盖能够正确生效（[#6300](https://github.com/heroui-inc/heroui/pull/6300)）
+- **Modal 与 AlertDialog**：背景遮罩的点击事件不会再透过 portal 传播到父级元素（[#6297](https://github.com/heroui-inc/heroui/pull/6297)）
+- **Table**：修复了 Firefox 中表头圆角与背景色溢出的问题（[#6298](https://github.com/heroui-inc/heroui/pull/6298)）
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6285](https://github.com/heroui-inc/heroui/pull/6285)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-0.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-0.mdx
new file mode 100644
index 0000000..f84af88
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-0.mdx
@@ -0,0 +1,686 @@
+---
+title: HeroUI v3 正式发布
+description: 面向 React 与 React Native 的彻底重写。75+ Web 组件、37 个原生组件、Tailwind CSS v4、React Aria、复合组件架构，以及为 AI 辅助开发而打造的工具链。
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 3 月</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-v3-release.mp4"
+  height={430}
+  muted
+/>
+
+每个组件都已重写。所有动画都已迁移到 CSS。样式与实现完全解耦。全新打造的 React Native 库。以及一套把 AI 助手视为「主要开发界面」的工具链。
+
+## 概览
+
+### React（Web）
+
+75+ 组件。无障碍能力由 [React Aria Components](https://react-aria.adobe.com/) 提供。基于 Tailwind CSS v4 + CSS 变量进行主题化。样式被独立成单独的包，可以与任意框架配合使用。
+
+[查看详情](#compound-components)
+
+### React Native
+
+37 个组件，共享同一套设计 token、采用复合组件模式、统一的动画 API，以及自适应的呈现模式。每个平台都基于原生实现，并通过 [Uniwind](https://uniwind.dev/) 提供 Tailwind CSS v4 的支持。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  playMode="manual"
+  height={430}
+  muted
+/>
+
+[查看详情](#heroui-native)
+
+### HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+面向 React 与 React Native 的高级组件、模板与 AI 工具。包含 Command Palette、Kanban、DataGrid、Dashboard 模板等。预售价格已上线 [heroui.pro](https://heroui.pro)。
+
+[查看详情](#heroui-pro)
+
+## 设计原则
+
+**组合优于配置：** v2 的组件是黑盒。v3 采用复合组件模式：每一个内部部件都是真实的元素，你可以为它们设置样式、调整位置、替换或移除。
+
+**样式与实现分离：** `@heroui/styles` 是独立的 CSS 包，`@heroui/react` 负责行为逻辑。这套样式可以配合 React、原生 HTML + Tailwind 或任意框架使用。BEM 类名让每一个 slot 都能在全局层面被定制。切换主题不仅会改变变量，还能改变组件的外观与质感。
+
+**按需变身 Headless：** 只要不引入 `@heroui/styles`，你就拥有了一套 headless 组件库。我们负责功能与无障碍，你专注于自己的产品。
+
+**默认就有好性能：** v2 的所有动画都依赖 Framer Motion。v3 已将其替换为原生的 CSS transition 与 keyframes。打包体积更小、可使用 GPU 加速，且无需任何 JS 动画运行时。
+
+**从一开始就无障碍：** 已从 React Aria hooks 迁移到 [React Aria Components](https://react-aria.adobe.com/)。键盘导航、焦点管理、屏幕阅读器与 ARIA 属性均已内置。
+
+## 复合组件
+
+下面是复合组件模式在实际使用中的样子：
+
+```tsx
+<Card>
+  <Card.Header>
+    <Card.Title>Product</Card.Title>
+    <Card.Description>Details about this product.</Card.Description>
+  </Card.Header>
+  <Card.Body>
+    <p>Card content goes here.</p>
+  </Card.Body>
+  <Card.Footer>
+    <Button variant="primary">Buy now</Button>
+  </Card.Footer>
+</Card>
+```
+
+代码确实多了几行。但每个部件都是真实的元素，你可以自由设置样式、调整位置或替换。这一模式贯穿整个组件库，从 Accordion 到 Toast 都是如此。
+
+<ComponentPreview
+  name="accordion-basic"
+/>
+
+每个复合组件都通过 React context 共享状态。根组件会创建样式 context，子组件依次消费。你无需手动逐层传递 className：
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+### 渐进式呈现
+
+组件同时支持简单写法和复合写法。先从一行代码起步，需要时再补充结构：
+
+```tsx
+// One line
+<Button>Submit</Button>
+
+// With icon
+<Button>
+  <Icon icon="gravity-ui:check" />
+  Submit
+</Button>
+
+// Full control
+<Button variant="primary" size="lg" isDisabled={isLoading}>
+  {isLoading ? <Spinner size="sm" /> : <Icon icon="gravity-ui:check" />}
+  {isLoading ? "Saving..." : "Submit"}
+</Button>
+```
+
+<ComponentPreview
+  name="button-variants"
+/>
+
+## Tailwind CSS v4 + CSS 变量
+
+主题系统基于 Tailwind CSS v4 原生的 CSS 变量层与 OKLCH 颜色实现。每一个设计 token 都是一个 CSS 变量：
+
+```css
+:root {
+  --background: oklch(0.9702 0 0);
+  --foreground: oklch(0.2103 0.0059 285.89);
+  --accent: oklch(0.6204 0.195 253.83);
+  --surface: oklch(100% 0 0);
+  --danger: oklch(0.6532 0.2328 25.74);
+  --radius: 0.5rem;
+}
+```
+
+Tailwind 的 `@theme` 指令会将这些 token 映射为工具类。`bg-accent`、`text-foreground`、`rounded-lg` 都会解析为对应的 CSS 变量。切换浅色 / 深色模式只需替换变量值：
+
+```css
+.dark, [data-theme="dark"] {
+  --background: oklch(12% 0.005 285.823);
+  --foreground: oklch(0.9911 0 0);
+  --surface: oklch(0.2103 0.0059 285.89);
+}
+```
+
+不需要 Provider 组件，也不需要 JavaScript 主题对象。一次 CSS 引入，两行代码：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+### BEM 类名
+
+通过标准 CSS 即可在全局覆写任意组件：
+
+```css
+@layer components {
+  .button {
+    @apply font-semibold tracking-wide;
+  }
+
+  .button--primary {
+    @apply bg-blue-600 hover:bg-blue-700;
+  }
+}
+```
+
+无需层层传递 className，也无需在 style prop 上反复折腾。设计系统的覆写就发生在 CSS 中——它本就属于这里。
+
+### 自定义主题
+
+通过定义你自己的 token 集合即可创建主题，其他一切都会随之级联：
+
+```css
+@layer base {
+  [data-theme="ocean"] {
+    --accent: oklch(0.450 0.150 230);
+    --background: oklch(0.985 0.015 225);
+    --radius: 0.75rem;
+    --border: oklch(0.50 0.060 230 / 22%);
+  }
+}
+```
+
+只需一个 data 属性即可应用：
+
+```html
+<html data-theme="ocean">
+```
+
+[主题构建器](/themes) 可以可视化地生成这些变量：选择颜色、调整圆角与间距，再导出 CSS。
+
+### 按需引入
+
+可以一次性引入完整样式库，也可以只挑选特定组件的样式：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles/base" layer(base);
+@import "@heroui/styles/themes/default" layer(theme);
+@import "@heroui/styles/components/button.css" layer(components);
+@import "@heroui/styles/components/card.css" layer(components);
+```
+
+只发布你实际用到的 CSS，避免在生产环境中携带未使用的组件样式。
+
+## 尊重用户的动画
+
+所有组件动画都通过 CSS transition 与 keyframes 实现，并绑定到对应的 data 属性。Popover 通过 `[data-entering]` 淡入，Button 在 `[data-pressed]` 时缩放，Accordion 通过 `[aria-hidden="false"]` 展开。
+
+```css
+.popover[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200;
+}
+
+.button:active,
+.button[data-pressed="true"] {
+  transform: scale(0.97);
+}
+```
+
+### Reduce Motion
+
+部分用户需要禁用动画。HeroUI 扩展了 Tailwind 的 `motion-reduce:` 变体，使其同时支持系统级偏好和自定义 data 属性：
+
+```css
+.button {
+  @apply transition-colors motion-reduce:transition-none;
+}
+```
+
+它会响应原生的 `prefers-reduced-motion: reduce` 媒体查询，同时也会响应 HTML 元素上的 `data-reduce-motion="true"`，从而支持应用级别的控制：
+
+```html
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations are disabled -->
+</html>
+```
+
+data 属性的优先级高于系统设置。将其设为 `data-reduce-motion="false"` 可强制开启动画，移除该属性则交由操作系统决定。所有带动画的组件都会遵循这一规则，无需额外开启。
+
+### 自带动画库也无妨
+
+Framer Motion、Motion One 或任何 CSS 动画库都可以与 HeroUI 内置的过渡共存：
+
+```tsx
+import { motion } from "framer-motion";
+import { Button } from "@heroui/react";
+
+const MotionButton = motion(Button);
+
+<MotionButton whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}>
+  Animated
+</MotionButton>
+```
+
+## 75+ React 组件
+
+### 日期与时间
+
+六个组件：Calendar、RangeCalendar、DateField、DatePicker、DateRangePicker 与 TimeField。基于 React Aria 的国际化日期库构建，默认支持公历、佛历、波斯历等多种历法。键盘导航、屏幕阅读器标签以及按区域格式化全部开箱即用。
+
+<ComponentPreview
+  name="date-picker-basic"
+/>
+
+<ComponentPreview
+  name="range-calendar-basic"
+/>
+
+### 颜色
+
+六个颜色组件：ColorPicker、ColorArea、ColorSlider、ColorField、ColorSwatch 与 ColorSwatchPicker。可以在二维色域中取色、调整色相与透明度滑块、输入 hex 值，或从色板中直接选择。
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### 数据
+
+需要一个支持排序、行选择、列宽调整、异步加载与自定义单元格的表格？Table 全部都能搞定。面对大数据集时，可借助 React Aria 的 `Virtualizer` 启用虚拟化，ListBox 也共享同样的虚拟化能力。
+
+<ComponentPreview
+  name="table-virtualization"
+/>
+
+### 表单
+
+十三个表单组件：TextField、Select、Autocomplete、ComboBox、Checkbox、CheckboxGroup、RadioGroup、Switch、InputOTP、NumberField、SearchField、Slider 与 Fieldset。全部集成了 React Aria 的表单校验：`isRequired`、`isInvalid` 以及通过 FieldError 自定义错误信息——所有组件均可使用。
+
+<ComponentPreview
+  name="select-default"
+/>
+
+<ComponentPreview
+  name="input-otp-basic"
+/>
+
+### 浮层
+
+七个浮层组件。Drawer 支持四种放置位置以及拖拽关闭手势。Toast 可堆叠通知，并支持自动关闭与 Promise。Menu 支持子菜单与分组组合。此外还有 Modal、AlertDialog、Popover 与 Tooltip。
+
+<ComponentPreview
+  name="drawer-basic"
+/>
+
+<ComponentPreview
+  name="toast-default"
+/>
+
+### 导航
+
+Tabs、Accordion、Breadcrumbs、Pagination 与 Link。Tabs 支持水平与垂直两种排列方向。Accordion 支持单一或多个面板同时展开。
+
+<ComponentPreview
+  name="tabs-basic"
+/>
+
+### 反馈
+
+ProgressBar 与 ProgressCircle 同时支持确定态与不确定态。Meter 会根据数值映射到语义颜色：绿色代表安全，黄色代表警告，红色代表严重。Skeleton 与 Spinner 共同补齐这一组件家族。
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+<ComponentPreview
+  name="skeleton-basic"
+/>
+
+### 按钮与切换
+
+Button、ButtonGroup、ToggleButton、ToggleButtonGroup、CloseButton 与 Toolbar。ButtonGroup 通过共享边框将多个按钮连接在一起，并支持垂直方向。Toolbar 会将按钮、切换控件与分隔线组合到一个具备无障碍语义的 `role="toolbar"` 容器中。
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### 细粒度引入
+
+你可以从根路径引入，也可以从每个组件的子路径引入，两种方式都可用：
+
+```tsx
+// Root import
+import { Button, Card, Table } from "@heroui/react";
+
+// Subpath import
+import { Button } from "@heroui/react/button";
+import { Card } from "@heroui/react/card";
+import { Table } from "@heroui/react/table";
+```
+
+## 面向 Agent 的 UI
+
+如今越来越多的开发者通过 prompt 来构建产品，而不是逐字阅读 API 文档。HeroUI v3 为此做好了准备。
+
+### MCP 服务器
+
+HeroUI MCP 服务器将 AI 编码助手（Cursor、Claude Code、VS Code Copilot、Windsurf、Zed）连接到组件文档、props、源码、CSS 样式与主题变量。AI 可以直接读取权威信息源，而不必再依赖训练数据进行猜测。
+
+```json
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+对你的 AI 助手说一句「把 HeroUI 升级到最新版本」，它就会自动对比版本、检查更新日志中的破坏性变更，并完成必要的代码更新。
+
+### Agent Skills
+
+面向 Cursor 与 Claude Code 提供可安装的知识包，覆盖组件模式、变体用法、主题说明以及升级指南。提前注入上下文，让 AI 第一次就能写出正确的 HeroUI 代码。
+
+### LLMs.txt
+
+针对 AI 上下文窗口优化的结构化文档文件。这些文件发布在 `/llms.txt` 与 `/llms-components.txt`，为任何基于 LLM 的工具提供一份机器可读的 HeroUI API 摘要。
+
+MCP 服务器、Agent Skills、LLMs.txt——三层组合让 AI 助手能像人类开发者从文档中获取信息一样，获得对 HeroUI 的完整访问能力。
+
+## HeroUI Native
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  height={430}
+  muted
+/>
+
+HeroUI Native 是与 v3 网页版同时推出的全新组件库。渲染引擎不同，但心智模型一致。在平台差异较大的地方，API 也会贴合各自平台的原生体验。
+
+### 在你的设备上试试
+
+用设备摄像头或 [Expo Go](https://expo.dev/go) 扫描下方二维码，即可在线体验全部 37 个组件：
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go QR Code"
+  />
+</div>
+
+<div className="flex justify-center">
+  **[📱 在 Expo Go 中打开演示应用](https://link.heroui.com/native-demo)**
+</div>
+
+<Callout type="info">
+  **Android 用户：** 如果扫码后跳转到浏览器并显示 404 错误，请先打开 Expo Go，再使用应用内置的扫码功能。
+</Callout>
+
+### 37 个组件
+
+涵盖表单、导航、浮层、反馈与布局。从 Button、Input、Checkbox，到 Dialog、BottomSheet、Select、Toast 与 InputOTP，所有组件都遵循复合组件模式：
+
+```tsx
+import { Dialog, Button } from "heroui-native";
+
+<Dialog>
+  <Dialog.Trigger asChild>
+    <Button variant="primary">Open</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>Confirm action</Dialog.Title>
+      <Dialog.Description>This cannot be undone.</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### 跨平台一致的体验
+
+只要你熟悉 Web 版的 HeroUI，大部分知识都能直接迁移过来。组件命名、点表示法与 prop 模式都尽可能保持一致。在平台差异较大的地方（布局基元、手势、导航等），API 会做出相应调整以贴近原生，但整体的心智模型保持一致：
+
+```tsx
+// React (web)
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+// React Native — similar API, native behavior
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+同时开发 Web 与移动端的团队可以共享同一套知识与模式。即便组件本身有所不同，跨平台的学习成本也极低。
+
+### 共享设计 token
+
+两个平台读取的是同一份 token 集合。`accent`、`surface`、`danger`、`success` 等颜色在 Web 与 Native 上解析结果完全一致。你不必维护两套独立的系统，品牌也能保持一致。
+
+```tsx
+import { View, Text } from "react-native";
+
+<View className="bg-surface p-4 rounded-lg">
+  <Text className="text-foreground text-lg font-semibold">Card Title</Text>
+  <Text className="text-muted text-sm">Consistent on web and mobile.</Text>
+</View>
+```
+
+两个平台都使用 Tailwind CSS v4：Native 端通过 [Uniwind](https://uniwind.dev/)，Web 端使用标准 Tailwind。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/native-v1-demo/v-1-demo-2.mp4"
+  height={430}
+  muted
+/>
+
+### 统一的动画 API
+
+每一个带动画的原生组件都只暴露一个 `animation` prop。数值、时长、弹簧参数、进出场过渡都集中在这里配置。底层由 Reanimated 负责计算，但你完全不需要直接接触它：
+
+```tsx
+import { Switch } from "heroui-native";
+
+<Switch
+  animation={{
+    scale: { value: [1, 0.9] },
+    backgroundColor: { value: ["#172554", "#eab308"] },
+  }}
+>
+  <Switch.Thumb />
+</Switch>
+```
+
+可以在任意层级关闭动画——单个组件、整棵子树，或者全局：
+
+```tsx
+// Single component
+<Switch.Thumb animation={false} />
+
+// Entire subtree
+<Card animation="disable-all">...</Card>
+
+// App-wide
+<HeroUINativeProvider config={{ animation: "disable-all" }}>
+  <App />
+</HeroUINativeProvider>
+```
+
+Reduce Motion 全自动生效。当用户在系统设置中启用它时，所有动画都会停止，无需任何额外代码。
+
+### 自适应的呈现模式
+
+Popover、Select 与 Menu 通过一个 prop 即可在 popover、bottom-sheet 与 dialog 之间切换。同一个组件，根据上下文以不同形式呈现：
+
+```tsx
+<Select presentation="popover">...</Select>
+<Select presentation="bottom-sheet">...</Select>
+<Select presentation="dialog">...</Select>
+```
+
+目前还没有其他 React Native 组件库提供这一能力。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/native-v1-demo/v-1-demo-3.mp4"
+  height={430}
+  muted
+/>
+
+### 细粒度引入
+
+每一个原生组件都有自己的入口路径，只引入你实际用到的部分即可：
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+```
+
+### Native 端的 AI 工具
+
+HeroUI Native 也配套提供了自己的 MCP 服务器、Agent Skills 与 LLMs.txt，与 Web 组件库的工具链结构完全一致：
+
+```json
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+## HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+与 v3 同步，[HeroUI Pro](https://heroui.pro) 的预售也已经上线。面向 React 与 React Native，提供高级组件、模板与 AI 工具。
+
+### Pro 组件
+
+超越核心组件库的更多组件：Command Palette、Kanban、Stats Dashboard、Filters、Agenda、DataGrid 等。无障碍、动画以及各平台的边界情况都已处理妥当，未来将同时支持 Web 与 Native。
+
+### 模板
+
+完整可用的响应式起步模板：Dashboard、Mail、Chat 与 Finances。布局真实、结构完整，让你从一个能直接运行的项目出发，再按需定制。
+
+### 高级 AI 工具
+
+Pro 许可包含高级版的 MCP 服务器与 Agent Skills，并内置 Pro 组件文档、使用模式与升级路径。
+
+预售价格已上线。v2 Pro 用户可享受升级折扣，使用同一邮箱或联系客服即可。
+
+[访问 heroui.pro 查看套餐与定价](https://heroui.pro)
+
+## 快速上手
+
+### React（Web）
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+在你的 CSS 中加入这两行：
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+### React Native
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install heroui-native
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native
+    ```
+  </Tab>
+</Tabs>
+
+完整的安装指南请参阅 [React 文档](/docs/react/getting-started/quick-start) 与 [React Native 文档](/docs/native/getting-started/quick-start)（涵盖 peer dependencies、Uniwind 配置以及 Provider 设置）。
+
+**正在从 HeroUI v2 升级？** 请按照 [迁移指南](/docs/react/migration) 一步步完成升级。
+
+## Figma Kit v3
+
+HeroUI v3 中的每一个组件在 Figma 中都有 1:1 的对应实现。变体、命名与结构完全一致。整套 Kit 全程采用 auto layout，使用与代码 token 直接对应的 Figma 变量（`--accent`、`--surface`、`--radius`），并借助 Figma 新推出的 [slots](https://help.figma.com/hc/en-us/articles/38231200344599-Use-slots-to-build-flexible-components-in-Figma) 来实现灵活的组件组合。设计师可以像开发者写代码一样，自由调整、替换与定制组件的各个部件。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cover-figma@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cover-figma-dark@2x.jpg"
+  alt="HeroUI Figma Kit v3"
+  href="https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3"
+/>
+
+[获取 Figma Kit](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+
+## 致谢
+
+[React Aria](https://react-aria.adobe.com/) 提供了我们自己难以做到这种水准的无障碍能力层。Tailwind CSS v4 原生的 CSS 变量方案塑造了我们整个主题系统。复合组件模式则是通过研究 [Radix](https://www.radix-ui.com/)、[Ark UI](https://ark-ui.com/) 与 [Base UI](https://base-ui.com/) 在组合性问题上的解法逐步打磨而来。
+
+感谢每一位在 alpha 与 RC 阶段提交 issue、测试预发布版本以及反馈意见的社区成员。这套组件库因为你们而变得更好。
+
+## 链接
+
+- [React 文档](/docs/react/getting-started/quick-start)
+- [React Native 文档](/docs/native/getting-started/quick-start)
+- [主题构建器](/themes)
+- [MCP 服务器](/docs/ui-for-agents/mcp-server)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-2.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-2.mdx
new file mode 100644
index 0000000..ebc7238
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-2.mdx
@@ -0,0 +1,93 @@
+---
+title: v3.0.2
+description: 修复了多个 bug，Drawer 过渡更平滑，新增 --backdrop 主题变量，并优化了 trigger、arrow 与 Tag 的样式。
+github:
+  pull: 6364
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 4 月 3 日</span>
+</div>
+
+补丁版本，包含若干 bug 修复、样式优化，以及新增的 `--backdrop` 主题变量。Drawer 过渡已重写为原生 CSS，动画更加平滑。浮层触发器现在以 `inline-block` 形式呈现，Tooltip 和 Popover 的默认箭头形状也已更新。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### `--backdrop` 主题变量
+
+新增用于浮层背景遮罩的 `--backdrop` CSS 变量（[#6375](https://github.com/heroui-inc/heroui/pull/6375)）。浅色主题默认值为 `rgba(0, 0, 0, 0.5)`，深色主题为 `rgba(0, 0, 0, 0.6)`。[Modal](/docs/components/modal)、[AlertDialog](/docs/components/alert-dialog) 与 [Drawer](/docs/components/drawer) 现在都引用该变量，而不再使用硬编码的值。
+
+可以在全局进行覆写：
+
+```css
+:root {
+  --backdrop: rgba(0, 0, 0, 0.7);
+}
+```
+
+也可以直接使用对应的工具类 `bg-backdrop`。
+
+## 样式改进
+
+### Trigger 改用 `inline-block` 显示
+
+Popover、Tooltip、Dropdown、Modal、AlertDialog、Drawer 与 Disclosure 中的触发元素现在都会应用 `inline-block`，避免触发器包裹行内内容时出现布局塌陷的问题（[#6373](https://github.com/heroui-inc/heroui/pull/6373)）。
+
+### Tooltip 与 Popover 的箭头
+
+默认箭头的 SVG 路径已从二次贝塞尔曲线改为三次贝塞尔曲线，形状更平滑、更自然（[#6372](https://github.com/heroui-inc/heroui/pull/6372)）。
+
+### Tag 的间距
+
+为提升可读性，Tag 在 `sm`（由 `px-1` 改为 `px-2`）和 `md`（由 `px-1.5` 改为 `px-2`）尺寸下增加了水平内边距（[#6315](https://github.com/heroui-inc/heroui/pull/6315)）。
+
+## Bug 修复
+
+- **Autocomplete**：popover 上的 `--trigger-width` CSS 变量现在通过 `useResizeObserver` 跟踪触发元素的宽度，修复了下拉宽度不对齐的问题（[#6374](https://github.com/heroui-inc/heroui/pull/6374)）
+- **Drawer**：面板过渡已从 Tailwind 的 `animate-in` / `animate-out` 重写为原生的 CSS `translate` 过渡，使各种放置位置下的开关动画都更加平滑（[#6393](https://github.com/heroui-inc/heroui/pull/6393)）
+- **InputGroup**：secondary 变体的聚焦背景现在仅在实际的 input 或 textarea 获得焦点时才会触发，不再因组内任意可聚焦的子元素被聚焦而触发（[#6362](https://github.com/heroui-inc/heroui/pull/6362)）
+- **Tag**：Tag 内部的 `CloseButton` 现在带有显式的 `aria-label="Remove tag"`，可被屏幕阅读器正确识别（[#6341](https://github.com/heroui-inc/heroui/pull/6341)）
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6364](https://github.com/heroui-inc/heroui/pull/6364)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-3.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-3.mdx
new file mode 100644
index 0000000..f7c9a74
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-3.mdx
@@ -0,0 +1,127 @@
+---
+title: v3.0.3
+description: 升级到 RAC 1.17（依赖减少 90%）、Table 支持可展开行、采用 Apache 2.0 协议、新增 useTheme Hook、DOM 多态 render-prop API，以及若干 bug 修复。
+github:
+  pull: 6441
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 4 月 17 日</span>
+</div>
+
+补丁版本：升级到 React Aria Components 1.17（依赖数量减少 90%）、Table 支持可展开行、采用 Apache 2.0 协议，为 Vite 与 CRA 应用提供 `useTheme` Hook、新增可在 render prop 中替换元素的 DOM 多态工具函数，以及若干 bug 修复。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### React Aria Components 1.17
+
+本次发布将 React Aria Components 升级到 [v1.17.0](https://react-aria.adobe.com/releases/v1-17-0)。最大亮点是依赖整合：**RAC 的传递依赖减少了 90%**，安装与构建都更快。详情请查看完整的 [RAC 1.17 发布说明](https://react-aria.adobe.com/releases/v1-17-0)。
+
+### Table 可展开行
+
+Table 现在支持以可展开行的形式呈现树形数据。设置 `treeColumn` 并在对应单元格中渲染一个 chevron 图标即可展开 / 折叠子行——非常适合用于文件浏览器、嵌套分类以及层级数据。
+
+<ComponentPreview
+  name="table-expandable-rows"
+/>
+
+### useTheme Hook
+
+对于使用 Vite 或 Create React App 搭建（没有 Next.js 主题 Provider）的纯 React 应用，可以从 `@heroui/react` 中引入 `useTheme`。它接受任意主题名（`"light"`、`"dark"`、`"brutalism-light"` 等），传入 `"system"` 则会跟随操作系统偏好。`useTheme` 会将主题值持久化到 `localStorage`，并在 `<html>` 元素上同步设置 `data-theme` 与 `class`，二者均为解析后的主题名。
+
+```tsx
+"use client";
+
+import { Button, useTheme } from "@heroui/react";
+
+export function ThemeSwitch() {
+  const { theme, setTheme } = useTheme("light");
+
+  return (
+    <div className="flex gap-2">
+      <Button onPress={() => setTheme("light")}>
+        Light
+      </Button>
+      <Button onPress={() => setTheme("dark")}>
+        Dark
+      </Button>
+      <Button onPress={() => setTheme("system")}>
+        System
+      </Button>
+      <Button onPress={() => setTheme("brutalism-light")}>
+        Brutalism Light
+      </Button>
+      <span className="text-sm opacity-70">Current: {theme}</span>
+    </div>
+  );
+}
+```
+
+### DOM 多态工具
+
+DOM 多态辅助工具让那些没有基于 React Aria 基元构建的轻量级组件，也能通过 render prop 切换其宿主元素。
+
+**示例：** 将 Card 组件渲染为 `<button />`
+
+```tsx
+<Card<"button"> render={(props) => <button {...props} />} />
+```
+
+### 协议变更
+
+HeroUI 现已采用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 协议，取代此前的 MIT 协议。Apache 2.0 同样提供宽松的使用自由，并在此基础上增加了显式的专利授权，提供更进一步的法律保护。现有用户无需进行任何操作。
+
+## Bug 修复
+
+- **Tabs**：限定 secondary 变体样式的作用范围，嵌套的 tab 组将不再继承父级变体（[#6384](https://github.com/heroui-inc/heroui/pull/6384)）
+
+## 依赖更新
+
+- **React Aria Components**：从 `1.16.0` 升级到 [`1.17.0`](https://react-aria.adobe.com/releases/v1-17-0)
+- **@react-aria/utils**：从 `3.33.1` 升级到 `3.34.0`
+- **@react-types/shared**：从 `3.33.1` 升级到 `3.34.0`
+- **@internationalized/date**：从 `3.12.0` 升级到 `3.12.1`
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6441](https://github.com/heroui-inc/heroui/pull/6441)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-4.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-4.mdx
new file mode 100644
index 0000000..f3c837d
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-4.mdx
@@ -0,0 +1,103 @@
+---
+title: v3.0.4
+description: 全新 Text 组件、文档主题选择器、采用 min() 上限约束的圆角设计令牌、Table 聚焦环重构，以及多项 bug 修复。
+github:
+  pull: 6483
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 5 月</span>
+</div>
+
+补丁版本：从 HeroUI Pro 移植的全新 `Text` 复合组件；文档站新增主题选择器，可在不同主题下预览各组件；在约 45 个组件 CSS 文件中将圆角设计令牌改为使用 `min()` 上限约束；重做 Table 的聚焦环；并修复 Checkbox、Autocomplete、Tooltip 与表单字段内边距等问题。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增功能
+
+### Text 组件
+
+用于结构化排版的新复合组件，从 HeroUI Pro 移植 ([#6479](https://github.com/heroui-inc/heroui/pull/6479))。会根据子组件或 `type` prop 自动渲染正确的 HTML 元素——`<h1>` 至 `<h6>`、`<p>` 或 `<code>`。
+
+<ComponentPreview name="text-typography-scale" />
+
+子组件：`Text.Heading`、`Text.Paragraph`、`Text.Code`、`Text.Prose`。
+
+各子组件支持的 prop：`align`、`color`、`weight`、`truncate`。`Text.Heading` 支持 `level`（1–6）。`Text.Paragraph` 支持 `size`（`"base"`、`"sm"`、`"xs"`）。
+
+使用 `Text.Prose` 包裹混合内容以获得自动的文章体间距：
+
+```tsx
+<Text.Prose>
+  <Text.Heading level={3}>快速开始</Text.Heading>
+  <Text.Paragraph>安装依赖包并引入组件。</Text.Paragraph>
+</Text.Prose>
+```
+
+### 文档主题选择器
+
+文档站现内置主题选择器，可在浅色、深色、粗野主义等多种主题下预览每个组件。你的选择会保存到 `localStorage`，在会话之间保持 ([#6471](https://github.com/heroui-inc/heroui/pull/6471))。
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-oss-3.0.4-4k.mp4"
+  muted
+/>
+
+### 圆角设计令牌
+
+约 45 个组件 CSS 文件中的 `rounded-full` 与硬编码 `border-radius` 现均通过 `min()` 限制计算后的半径 ([#6465](https://github.com/heroui-inc/heroui/pull/6465))。当用户设置过大的自定义圆角主题时，组件外观不再失真——半径在即将超过元素尺寸时停止增大。
+
+### Table 聚焦环重构
+
+表格行的聚焦指示改为在每个单元格上使用内阴影分别绘制，而非在整行使用单一 `box-shadow`。聚焦环在所有单元格之间视觉上保持连续，并在虚拟化表格包装器中正常工作。
+
+## Bug 修复
+
+- **Checkbox**：移除选中/半选指示态中硬编码的 `accent-hover` 背景 ([#6487](https://github.com/heroui-inc/heroui/pull/6487))
+- **Autocomplete**：`isDisabled` 现通过 context 从根节点传递到 `Trigger` 与 `ClearButton` ([#6443](https://github.com/heroui-inc/heroui/pull/6443))
+- **Description**：移除表单字段中说明文字的多余水平内边距（textfield、color-field、date-field、number-field、search-field、time-field） ([#6484](https://github.com/heroui-inc/heroui/pull/6484))
+- **Tooltip**：内边距由 `px-2 py-1` 调整为 `p-2`，圆角改为使用设计令牌 ([#6481](https://github.com/heroui-inc/heroui/pull/6481))
+- **Theme Builder**：修复 `accent-foreground` 取值被对调的问题 ([#6401](https://github.com/heroui-inc/heroui/pull/6401))
+- **柔和色对比度**：浅色强调主题（Sky、Lavender、Mint）下，`accent-soft-foreground` 现使用更深一级的色阶，修复次要按钮、Chip 与 Badge 上文字几乎不可见的问题。共享主题现从 `--accent-soft-foreground` 读取，并回退到 `--accent`
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [Figma Kit v3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6483](https://github.com/heroui-inc/heroui/pull/6483)
+
+## 贡献者
+
+感谢每一位为本次发布做出贡献的开发者！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-0-5.mdx b/apps/docs/content/docs/cn/react/releases/v3-0-5.mdx
new file mode 100644
index 0000000..f3e9c5e
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-0-5.mdx
@@ -0,0 +1,197 @@
+---
+title: v3.0.5
+description: Text 重命名为 Typography（破坏性变更），颜色令牌重构为无前缀源变量，修复 Checkbox 与 Radio 边框对齐，并新增 CLI 文档页。
+github:
+  pull: 6503
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 5 月 15 日</span>
+</div>
+
+补丁版本：`Text` 重命名为 `Typography`，以解决 `tailwind-merge` 冲突导致变体类名被静默丢弃的问题。派生颜色令牌（`hover`、`soft`、`border-secondary` 等）从 `theme.css` 中的 `@theme inline` 别名迁移到 `variables.css` 作为无前缀源变量，组件 CSS 可直接引用。此外还修复了 Checkbox 与 Radio 的边框对齐问题，优化了 Calendar 的 `accent-soft-foreground` 悬停样式，并新增了 CLI 文档页。
+
+⚠️ **破坏性变更**：`Text` → `Typography`。BEM 块名由 `text` 改为 `typography`（例如 `text--body-sm` → `typography--body-sm`）。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## ⚠️ 破坏性变更
+
+### `Text` → `Typography`
+
+[v3.0.4](/docs/react/releases/v3-0-4) 中发布的该组件使用了 `text-*` BEM 修饰符，与 Tailwind 的 `text-*` 工具类家族冲突。`tailwind-variants` 在每次变体组合时都会运行 `tailwind-merge`，并将 `text--body-sm`、`text--color-muted`、`text--weight-normal` 去重为单个类名——从而静默丢弃其他类名。
+
+将块名重命名为 `typography` 可永久解决该冲突 ([#6505](https://github.com/heroui-inc/heroui/pull/6505)，修复 [#6497](https://github.com/heroui-inc/heroui/issues/6497))。
+
+**之前：**
+
+```tsx
+import {Text} from "@heroui/react";
+
+<Text type="body-sm" color="muted" weight="medium">
+  Hello world
+</Text>;
+```
+
+**之后：**
+
+```tsx
+import {Typography} from "@heroui/react";
+
+<Typography type="body-sm" color="muted" weight="medium">
+  Hello world
+</Typography>;
+```
+
+子组件同样重命名：
+
+| 之前              | 之后                     |
+| ----------------- | ------------------------ |
+| `Text`            | `Typography`             |
+| `Text.Heading`    | `Typography.Heading`     |
+| `Text.Paragraph`  | `Typography.Paragraph`   |
+| `Text.Code`       | `Typography.Code`        |
+| `Text.Prose`      | `Typography.Prose`       |
+
+CSS BEM 类名也会相应变更：`.text` → `.typography`，`.text--body-sm` → `.typography--body-sm` 等。完整类名参考请参阅 [Typography 文档](/docs/components/typography)。
+
+<ComponentPreview name="typography-typography-scale" />
+
+## 样式重构
+
+### 无前缀源颜色令牌
+
+所有派生颜色令牌——`*-hover`、`*-soft`、`*-soft-foreground`、`border-secondary` 等——从 `theme.css` 中的 `@theme inline` 别名迁移到 `variables.css` 作为无前缀源变量，24 个组件 CSS 文件现直接引用源令牌 ([#6499](https://github.com/heroui-inc/heroui/pull/6499))。
+
+**1. `color-mix` 公式从 `theme.css` 移至 `variables.css`**
+
+之前——计算逻辑位于 `@theme inline` 块内：
+
+```css
+/* packages/styles/themes/shared/theme.css */
+--color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+--color-accent-soft: var(--accent-soft, color-mix(in oklab, var(--accent) 15%, transparent));
+--color-accent-soft-foreground: var(--accent-soft-foreground, var(--accent));
+--color-border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+```
+
+之后——`theme.css` 仅保留别名；公式位于 `variables.css`：
+
+```css
+/* packages/styles/themes/default/variables.css */
+--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+--accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
+--accent-soft-foreground: var(--accent);
+--border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+
+/* packages/styles/themes/shared/theme.css */
+--color-accent-hover: var(--accent-hover);
+--color-accent-soft: var(--accent-soft);
+--color-accent-soft-foreground: var(--accent-soft-foreground);
+--color-border-secondary: var(--border-secondary);
+```
+
+**2. 组件 CSS 直接使用源令牌**
+
+之前——各处使用 `var(--color-*)` 引用：
+
+```css
+/* packages/styles/components/button.css */
+.button--primary {
+  --button-bg: var(--color-accent);
+  --button-bg-hover: var(--color-accent-hover);
+  --button-fg: var(--color-accent-foreground);
+}
+
+.button--secondary {
+  --button-bg: var(--color-default);
+  --button-bg-hover: var(--color-default-hover);
+  --button-fg: var(--color-accent-soft-foreground);
+}
+```
+
+之后——无前缀源令牌：
+
+```css
+/* packages/styles/components/button.css */
+.button--primary {
+  --button-bg: var(--accent);
+  --button-bg-hover: var(--accent-hover);
+  --button-fg: var(--accent-foreground);
+}
+
+.button--secondary {
+  --button-bg: var(--default);
+  --button-bg-hover: var(--default-hover);
+  --button-fg: var(--accent-soft-foreground);
+}
+```
+
+`@theme inline` 块仍将每个 `--color-*` 暴露为 Tailwind 工具类别名，因此用户侧的类名用法（`bg-accent`、`text-accent` 等）不受影响。
+
+**3. Theme builder 合并精简**
+
+三个派生令牌辅助函数（`getAccentDerivedVariables`、`getSemanticDerivedVariables`、`getFieldDerivedVariables`）合并为单一的 `getDerivedColorVariables()`，输出完整的无前缀源令牌集合，并包含 `darkenForSoftForeground` 逻辑，以确保浅色强调主题下 soft-foreground 文字仍清晰可读。
+
+## 样式修复
+
+- **Calendar / Range Calendar**：日期单元格默认悬停样式现使用 `accent-soft-foreground` 而非 `accent`，使浅色强调主题下悬停单元格仍清晰可读。文档站搜索标签的选中状态也做了相同调整 ([#6500](https://github.com/heroui-inc/heroui/pull/6500))。
+- **Checkbox**：`.checkbox__control` 现已应用与 `.radio__control` 相同的基础样式：`border`、`border-field-border` 以及 `[border-width:var(--border-width-field)]`，并将 `border-color` 加入过渡属性列表 ([#6521](https://github.com/heroui-inc/heroui/pull/6521))。
+- **Radio**：`.radio__control` 默认边框现使用 `border-field-border`，而非 Tailwind 通用的 `border` 颜色，与 Input、Select、TextArea、NumberField 保持一致 ([#6522](https://github.com/heroui-inc/heroui/pull/6522))。
+
+## 文档
+
+### CLI 页面
+
+新增 [CLI 文档页](/docs/react/getting-started/cli)，涵盖安装、`init`、`install`、`upgrade`、`uninstall`、`list`、`doctor` 与 `env` 命令及示例输出 ([#6498](https://github.com/heroui-inc/heroui/pull/6498))。
+
+## 依赖项
+
+各软件包版本升级 ([#6529](https://github.com/heroui-inc/heroui/pull/6529))：
+
+- **`react` / `react-dom`**：`19.2.3` → `19.2.6`
+- **`@types/react`**：`19.2.7` → `19.2.14`
+- **`next`**（文档站）：`16.1.1` → `16.2.6`
+- **CI actions**：`actions/checkout@v6`、`actions/setup-node@v6`、`actions/cache@v5`、`pnpm/action-setup@v6`
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6503](https://github.com/heroui-inc/heroui/pull/6503)
+
+## 贡献者
+
+感谢所有为本次发布做出贡献的朋友！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-1-0.mdx b/apps/docs/content/docs/cn/react/releases/v3-1-0.mdx
new file mode 100644
index 0000000..932a94f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-1-0.mdx
@@ -0,0 +1,178 @@
+---
+title: v3.1.0
+description: 中文 React 文档、可访问的 soft foreground 令牌、统一滚动条、useTheme SSR 修复、Toast 清理、Link 下划线与 RTL 布局优化。
+github:
+  pull: 6576
+---
+
+import {HandPointUp} from "@gravity-ui/icons";
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 5 月 25 日</span>
+</div>
+
+v3.1.0 是小版本发布：新增中文 React 文档与本地化示例，soft foreground 默认达到无障碍对比度，滚动条统一由 `data-scrollbar` 和主题变量控制；同时修复 `useTheme`、Toast、Link、Fieldset、浮层和 RTL 布局问题。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 对它说「Hey Cursor，把 HeroUI 升级到最新版本」。它会对比版本并应用必要变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增内容
+
+### 中文 React 文档
+
+React 文档、迁移指南、发布说明和示例现在都有中文版本 ([#6533](https://github.com/heroui-inc/heroui/pull/6533))。组件页、入门指南和迁移参考都可以按 locale 发布。
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oss-releases/cn-docs-showcase.png"
+  alt="HeroUI 中文 React 文档页面"
+  wrapperClassName="aspect-[1922/1323]"
+/>
+
+### 可访问的 Soft Foreground 令牌
+
+Soft 状态不再直接套语义色，而是使用专门的 foreground token，让 Badge、Chip、Alert、Toast、Avatar 和 Calendar 范围状态的文字对比度更稳定 ([#6548](https://github.com/heroui-inc/heroui/pull/6548))。
+
+可直接覆盖这些 token：
+
+- `--default-soft`
+- `--default-soft-foreground`
+- `--default-soft-hover`
+- `--accent-soft-foreground`
+- `--danger-soft-foreground`
+- `--warning-soft-foreground`
+- `--success-soft-foreground`
+
+默认 palette 现在使用符合无障碍对比度的 soft foreground。需要旧版更饱和、但对比度更低的颜色时，在根元素启用 vibrant palette：
+
+```html
+<html data-vibrant-palette="true">
+  ...
+</html>
+```
+
+<ComponentPreview name="chip-vibrant-palette" />
+
+### 统一滚动条系统
+
+滚动容器现在共享同一套标准 CSS 滚动条工具：主题 token 负责颜色和宽度，`data-scrollbar` 负责模式切换 ([#6545](https://github.com/heroui-inc/heroui/pull/6545))。组件滚动区域和自定义 overflow 区域都读取同一组 `--scrollbar-*` 变量。
+
+三种模式：
+
+- HeroUI 纤细：不设置 `data-scrollbar`，或设置 `data-scrollbar="thin"`。
+- 浏览器默认：设置 `data-scrollbar="default"`，使用操作系统 / 浏览器滚动条。
+- 隐藏：设置 `data-scrollbar="none"`，隐藏滚动条但保留滚动。
+
+```html
+<div data-scrollbar="thin">使用 HeroUI 主题滚动条</div>
+<div data-scrollbar="default">使用浏览器默认滚动条</div>
+<div data-scrollbar="none">隐藏后代 HeroUI 滚动条</div>
+```
+
+<div className="not-prose mt-6 mb-4 flex items-center gap-2 text-sm font-medium text-muted">
+  <HandPointUp aria-hidden="true" className="size-5 shrink-0" />
+  <span>垂直滚动</span>
+</div>
+
+<ComponentPreview name="list-box-scrollbar-modes" />
+
+Select、ComboBox、Autocomplete、Dropdown、DatePicker、DateRangePicker、ColorPicker、Table、Tabs、Modal、Drawer 和 ScrollShadow 已接入同一套工具。
+
+自定义滚动插槽使用 `scrollbar`。它读取最近的 `data-scrollbar` 祖先，并自动应用对应的 `--scrollbar-width`、`--scrollbar-color` 和 `--scrollbar-gutter`。
+
+```css
+.alert-dialog__body {
+  @apply min-h-0 flex-1 scrollbar;
+}
+```
+
+主题变量也从单个固定的 `--scrollbar` 颜色，改为一组更细的滚动条 token：
+
+```css
+/* before */
+--scrollbar: oklch(70.5% 0.015 286.067);
+
+/* after */
+--scrollbar: var(--scrollbar-thumb);
+--scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+--scrollbar-track: transparent;
+--scrollbar-gutter: auto;
+--scrollbar-width: thin;
+--scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+```
+
+`--scrollbar` 保留为兼容别名；新的 thumb、track、gutter、width 和 color token 控制最终滚动条。
+
+恢复浏览器默认滚动条：在 `<html>`、`<main>` 或任意嵌套容器上设置 `data-scrollbar="default"`。如果全局已设为默认，但某个局部仍要 HeroUI 样式，在该容器上加 `data-scrollbar="thin"`。
+
+```html
+<html data-scrollbar="default">
+  <main>
+    <section data-scrollbar="thin">
+      <!-- 这里使用 HeroUI 主题滚动条 -->
+    </section>
+  </main>
+</html>
+```
+
+## 组件与运行时修复
+
+- **Fieldset**：`disabled` 会传给字段标签，并禁用后代 React Aria `RadioGroup` 与 `Slider` ([#6547](https://github.com/heroui-inc/heroui/pull/6547))。
+- **Toast**：非前台 Toast 不再进入 Tab 顺序；卸载时清理已测量高度 ([#6510](https://github.com/heroui-inc/heroui/pull/6510), [#6512](https://github.com/heroui-inc/heroui/pull/6512))。
+- **`useTheme`**：SSR 不再读取浏览器 API；`resolvedTheme` 改为派生值；系统主题订阅改用 `useSyncExternalStore` ([#6561](https://github.com/heroui-inc/heroui/pull/6561))。
+- **Link**：默认无下划线；hover 使用 50% 装饰色；active / pressed 使用 100%；移除下划线装饰色过渡 ([#6570](https://github.com/heroui-inc/heroui/pull/6570), [#6571](https://github.com/heroui-inc/heroui/pull/6571))。
+
+## 布局、浮层与 RTL 修复
+
+- **浮层定位**：进入动画只过渡 `opacity` 和 `transform`，不再动画化 React Aria 写入的定位值 ([#6549](https://github.com/heroui-inc/heroui/pull/6549))。
+- **Dialog 与 Modal 聚焦**：Modal 和 AlertDialog 内容改用裁剪处理，避免 focus 触发程序化滚动；body focus ring 不再被 overflow 裁掉 ([#6448](https://github.com/heroui-inc/heroui/pull/6448), [#6557](https://github.com/heroui-inc/heroui/pull/6557))。
+- **RTL Table 圆角**：Table 改用逻辑方向的 `border-radius`，RTL 外侧圆角保持正确 ([#6568](https://github.com/heroui-inc/heroui/pull/6568))。
+- **RTL Picker 与 Menu 指示器**：Select、ListBox.Item、Autocomplete、ComboBox 和 MenuItem 改用 logical inline start/end，覆盖 chevron、value、checkmark、trigger 和 submenu indicator ([#6573](https://github.com/heroui-inc/heroui/pull/6573))。
+
+## 文档与依赖
+
+- 主题文档同步当前 `theme.css` / `variables.css`：soft foreground 令牌和滚动条变量都已更新。
+- 发布说明和迁移文档同步 Link 行为。
+- 文档站新增 `@fumadocs/language`；`fumadocs-core` / `fumadocs-ui` 升级到 `16.9.0`。
+- 文档和样式包的 Tailwind 工具升级到 `4.3.0`。
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [主题文档](/docs/react/getting-started/theming)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6576](https://github.com/heroui-inc/heroui/pull/6576)
+
+## 贡献者
+
+感谢所有为本次发布做出贡献的朋友！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-2-0.mdx b/apps/docs/content/docs/cn/react/releases/v3-2-0.mdx
new file mode 100644
index 0000000..443b148
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-2-0.mdx
@@ -0,0 +1,278 @@
+---
+title: v3.2.0
+description: 基于 React Aria 1.18 的 Calendar 周/日视图与年份选择器，以及 Radio、Checkbox、Switch 的破坏性组合方式变更。
+github:
+  pull: 6616
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 6 月 15 日</span>
+</div>
+
+Calendar 新增周视图与日视图、重做的年份选择器，以及基于 React Aria 1.18 的范围日历演示。[Autocomplete](/docs/components/autocomplete) 新增用于大型选项列表的 Virtualizer 示例。[Tooltip](/docs/components/tooltip) 新增用于全局显示与隐藏延迟的主题变量。Radio、Checkbox、Switch 迁移到 React Aria 的 `*Field` + `*Button` 组合方式。本次发布同时纳入了虚拟化列表、分组字段自动填充、Toast 与 Fieldset 行为，以及滚动与 RTL 样式方面的补丁修复。
+
+⚠️ **破坏性变更**：`Radio`、`Checkbox`、`Switch` 改为显式的 `*.Content` 组合 —— `*.Control` 嵌套进 `*.Content`，标签变为 `*.Content` 内的纯文本（不嵌套 `<Label>`），`Description`/`FieldError` 变为 `*.Content` 的兄弟节点。详见[破坏性变更](#%EF%B8%8F-breaking-changes)。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 对它说「Hey Cursor，把 HeroUI 升级到最新版本」。它会对比版本并应用必要变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新增内容
+
+### Calendar
+
+`Calendar` 与 `RangeCalendar` 新增周视图与日视图，以及来自 React Aria 1.18 的新日历属性。
+
+- **周视图 / 日视图**：通过 `visibleDuration` 渲染多周或单日布局
+- **多选**：在单个 `Calendar` 中选择多个日期
+- **React Aria 1.18 属性**：`weeksInMonth` 与用于范围选择的 `isDateUnavailable(date, anchorDate)`
+- **内部实现**：月份标题使用 React Aria 的 `CalendarHeading`，年份选择器基于 React Aria calendar hooks 重建
+
+**周视图：**
+
+<ComponentPreview name="calendar-week-view" />
+
+**日视图：**
+
+<ComponentPreview name="calendar-day-view" />
+
+**多选：**
+
+<ComponentPreview name="calendar-multiple-selection" />
+
+### Autocomplete
+
+支持通过 Virtualizer 渲染大型选项列表，并补充文档、Storybook 示例，以及针对 popover 尺寸和 listbox 滚动高度的样式修复。
+
+- **虚拟化**：在 `Autocomplete.Popover` 内用 React Aria 的 `<Virtualizer>` 包裹 `ListBox` ([#6642](https://github.com/heroui-inc/heroui/pull/6642))
+- **Popover 尺寸**：listbox 高度上限为 `320px` 并支持内部滚动；搜索框固定在列表上方
+
+**虚拟化：**
+
+<ComponentPreview name="autocomplete-virtualization" />
+
+### Table.SortableColumnHeader
+
+`Table.SortableColumnHeader` 用于渲染 sortable 列标题和可选的升降序指示器。放在 `Table.Column` render prop 中，并传入 `sortDirection` ([#6588](https://github.com/heroui-inc/heroui/pull/6588))。
+
+```tsx
+<Table.Column allowsSorting>
+  {({sortDirection}) => (
+    <Table.SortableColumnHeader sortDirection={sortDirection}>
+      Name
+    </Table.SortableColumnHeader>
+  )}
+</Table.Column>
+```
+
+- **默认指示器**：存在排序方向时显示 chevron
+- **自定义指示器**：传入 `indicator`，或用 `showIndicator={false}` 隐藏
+- **样式插槽**：`.table__sortable-column-header` + `.table__sortable-column-indicator`
+
+<ComponentPreview name="table-sorting" />
+
+### Tooltip 延迟主题变量
+
+[Tooltip](/docs/components/tooltip) 现在会从主题 CSS 变量读取默认的显示与隐藏延迟 ([#6617](https://github.com/heroui-inc/heroui/pull/6617))：
+
+- `--tooltip-delay` — 显示 Tooltip 前的延迟（默认：`1500ms`）
+- `--tooltip-close-delay` — 隐藏 Tooltip 前的延迟（默认：`500ms`）
+
+全局覆盖示例：
+
+```css
+:root {
+  --tooltip-delay: 700ms;
+  --tooltip-close-delay: 0ms;
+}
+```
+
+单个 Tooltip 上的 `delay` 和 `closeDelay` 属性仍会覆盖这些值。
+
+<Callout type="warning">
+  **行为变更：** 使用默认 HeroUI 主题时，Tooltip 延迟现在默认为 `1500ms` / `500ms`，而不是之前的 React Aria 默认值 `700ms` / `0ms`。如需保留旧行为，请显式设置 CSS 变量或 props。
+</Callout>
+
+## 组件修复
+
+- **Toast**：Toast 队列会串行化 ViewTransition 更新，避免在 `toast.promise()` 关闭 loading toast 并打开成功/失败反馈时出现被跳过的过渡和 AbortError ([#6511](https://github.com/heroui-inc/heroui/pull/6511))。
+- **Fieldset**：`disabled` 会传递到 React Aria 的 Button、CheckboxGroup、Link、RadioGroup、Slider、ToggleButton 和 ToggleButtonGroup 上下文 ([#6596](https://github.com/heroui-inc/heroui/pull/6596))。
+- **Autocomplete**：Popover 内容包裹在 React Aria 的 `Dialog` 中，打开 popover 时 listbox 不再出现多余的焦点环 ([#6627](https://github.com/heroui-inc/heroui/pull/6627))。
+- **Tooltip**：Trigger 改用 `useFocusable` hook 而非 `<Focusable>` 包装组件，避免 Tooltip 挂载在 `inert` 子树中（例如位于已打开的 Drawer/Modal 之后）时出现误报的 “child must be focusable” 警告 ([#6628](https://github.com/heroui-inc/heroui/pull/6628))。
+
+## 样式修复
+
+- **Modal / AlertDialog**：`scroll-inside` 对话框通过 `max-h-full min-h-0` 限制高度，使内容区域滚动而非溢出 ([#6597](https://github.com/heroui-inc/heroui/pull/6597))。
+- **ScrollShadow**：渐隐遮罩通过 `--scroll-shadow-scrollbar-size` 为可见的原生滚动条预留空间 ([#6598](https://github.com/heroui-inc/heroui/pull/6598))。
+- **Table RTL**：列分隔线与拖拽手柄在 RTL 下使用逻辑属性 `end-0` 定位 ([#6606](https://github.com/heroui-inc/heroui/pull/6606))。
+- **Link**：移除硬编码的 `text-sm`，让链接从父元素继承字号；`.link__icon` 改为相对单位 `size-[0.75em]`，随文本大小缩放，而不再使用固定的 `size-2` ([#6621](https://github.com/heroui-inc/heroui/pull/6621))。
+- **DatePicker / DateRangePicker**：日历 popover 由 `max-w-(--trigger-width)` 改为 `min-w-(--trigger-width)`，确保 popover 至少与触发器一样宽，避免被水平裁剪 ([#6622](https://github.com/heroui-inc/heroui/pull/6622))。
+- **Table**：当 Table 被 React Aria 的 `<Virtualizer>` 包裹时，secondary 表头的边框与圆角能够正确渲染 —— 列选择器不再把每个虚拟化列都同时视为 first 和 last child ([#6624](https://github.com/heroui-inc/heroui/pull/6624))。
+- **Autocomplete**：Popover 限制为触发器宽度，listbox 高度上限为 `320px` 并支持内部滚动，避免虚拟化列表溢出 popover ([#6642](https://github.com/heroui-inc/heroui/pull/6642))。
+- **ListBox**：将 `flex flex-col gap` 改为普通块级流 + 兄弟节点间距，避免 React Aria Virtualizer 的内容高度被 flex-shrink 压缩 —— 修复虚拟化滚动时滚动条滑块尺寸变化的问题 ([#6636](https://github.com/heroui-inc/heroui/pull/6636))。
+- **InputGroup / NumberField / SearchField**：浏览器自动填充高亮提升到分组容器上，使 prefix、suffix 和增减按钮槽位共享圆角高亮 ([#6625](https://github.com/heroui-inc/heroui/pull/6625))。
+- **Spinner**：改用 `inline-flex` 搭配 `shrink-0`（替代 `relative`），使旋转动画在非 flex 布局中也能正确渲染，并支持 `motion-reduce` ([#6644](https://github.com/heroui-inc/heroui/pull/6644))。
+- **Toast**：关闭按钮在所有断点下统一使用 `-top-1 -right-1`，与容器内边距对齐 ([#6574](https://github.com/heroui-inc/heroui/pull/6574))。
+
+## 依赖
+
+- **React Aria Components**：`1.17.0` → `1.18.0` ([#6586](https://github.com/heroui-inc/heroui/pull/6586))。1.18 引入了 toggles 所采用的 `*Field` + `*Button` 组合方式、`CalendarHeading`，以及 `isDateUnavailable(date, anchorDate)`。
+- **@internationalized/date**：`3.12.1` → `3.12.2`
+- **React Aria / Stately 辅助包**：`@react-aria/*`、`@react-stately/*` 与 `@react-types/shared` 补丁更新
+
+## ⚠️ Breaking Changes
+
+### Radio、Checkbox 与 Switch：显式 `*.Content` 组合
+
+这些组件现在在底层使用 React Aria 的 `*Field` + `*Button` 组合方式。`X.Content` 现在是**可点击的 label**（React Aria 的 `*Button`）。共有三点变化：
+
+- **`X.Control` 移进 `X.Content`** —— 它们以前是兄弟节点。
+- **标签是 `X.Content` 内部的纯文本** —— `X.Content` 渲染的是 `<label>` 元素，所以不要嵌套 `<Label>` 组件（嵌套的 `<label>` 是无效 HTML）。若要使用独立的 `Label`，请把它放在**外部**，并用 `htmlFor` + 组件 `id` 关联。
+- **`Description`/`FieldError` 移到外部**，作为 `X.Content` 的兄弟节点，这样它们会通过 `aria-describedby` 朗读，而不会被并入无障碍名称。
+
+**Checkbox**
+
+```tsx
+// v3.1
+<Checkbox>
+  <Checkbox.Control>
+    <Checkbox.Indicator />
+  </Checkbox.Control>
+  <Checkbox.Content>
+    <Label>Accept terms</Label>
+    <Description>You agree to our terms</Description>
+  </Checkbox.Content>
+</Checkbox>
+
+// v3.2
+<Checkbox>
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Accept terms
+  </Checkbox.Content>
+  <Description>You agree to our terms</Description>
+</Checkbox>
+```
+
+**Radio**
+
+```tsx
+// v3.1
+<Radio value="a">
+  <Radio.Control>
+    <Radio.Indicator />
+  </Radio.Control>
+  <Radio.Content>
+    <Label>Option A</Label>
+  </Radio.Content>
+</Radio>
+
+// v3.2
+<Radio value="a">
+  <Radio.Content>
+    <Radio.Control>
+      <Radio.Indicator />
+    </Radio.Control>
+    Option A
+  </Radio.Content>
+</Radio>
+```
+
+**Switch**
+
+```tsx
+// v3.1
+<Switch>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+  <Switch.Content>
+    <Label>Enable notifications</Label>
+  </Switch.Content>
+</Switch>
+
+// v3.2
+<Switch>
+  <Switch.Content>
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    Enable notifications
+  </Switch.Content>
+</Switch>
+```
+
+**迁移对照**
+
+| v3.1 | v3.2 |
+|------|------|
+| `X.Control` 与 `X.Content` 为兄弟节点 | `X.Control` 嵌套进 `X.Content` |
+| `X.Content` 是包裹 `Label` + 帮助文本的布局 `<div>` | `X.Content` 是包裹 `X.Control` + 标签文本的可点击 `<label>` |
+| 通过 `X.Content` 内的 `<Label>` 提供标签 | 标签是 `X.Content` 内的**纯文本**（不嵌套 `<Label>`） |
+| `Description` / `FieldError` 位于 `X.Content` 内 | `Description` / `FieldError` 作为 `X.Content` 的兄弟节点 |
+
+**外部标签** —— 若要使用独立的 `Label`，请把它放在组件外部，并用 `htmlFor` + 组件 `id` 关联：
+
+```tsx
+<div className="flex items-center gap-3">
+  <Checkbox id="terms">
+    <Checkbox.Content>
+      <Checkbox.Control>
+        <Checkbox.Indicator />
+      </Checkbox.Control>
+    </Checkbox.Content>
+  </Checkbox>
+  <Label htmlFor="terms">Accept terms</Label>
+</div>
+```
+
+**仅含控件的 Checkbox 和 Switch**（没有标签，例如表格行选择或图标开关）仍需用 `X.Content` 作为可点击包装。请把 `Checkbox.Control` / `Switch.Control` 放进 `X.Content`，省略标签，并在根组件上传入 `aria-label`。
+
+各组件完整迁移指南：[Checkbox](/docs/react/migration/checkbox)、[Checkbox Group](/docs/react/migration/checkbox-group)、[Radio](/docs/react/migration/radio)、[Radio Group](/docs/react/migration/radio-group)、[Switch](/docs/react/migration/switch)。
+
+## 链接
+
+- [Calendar 文档](/docs/react/components/calendar)
+- [Autocomplete 文档](/docs/react/components/autocomplete)
+- [Tooltip 文档](/docs/react/components/tooltip)
+- [Checkbox 文档](/docs/react/components/checkbox)
+- [Radio Group 文档](/docs/react/components/radio-group)
+- [Switch 文档](/docs/react/components/switch)
+- [组件文档](/docs/react/components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6616](https://github.com/heroui-inc/heroui/pull/6616)
+
+## 贡献者
+
+感谢所有为本次发布做出贡献的人！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-2-1.mdx b/apps/docs/content/docs/cn/react/releases/v3-2-1.mdx
new file mode 100644
index 0000000..e8b0127
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-2-1.mdx
@@ -0,0 +1,60 @@
+---
+title: v3.2.1
+description: 补丁版本：将 react-aria 从 @heroui/react 产物中外部化，并修复 SwitchGroup 横向布局。
+github:
+  pull: 6654
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 6 月 17 日</span>
+</div>
+
+补丁版本：`@heroui/react` 不再内置自己的 `react-aria` 副本。`react-aria` 的子路径现在在 Rollup 构建中被外部化，因此会解析到你项目中安装的版本 —— 避免在 `@heroui/react` 内部打包出一份重复、内联的 `react-aria` 副本。本次发布还修复了 `SwitchGroup` 横向布局，补全缺失的 `switch-group__items` 包装层。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 对它说「Hey Cursor，把 HeroUI 升级到最新版本」。它会自动对比版本并应用必要变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 错误修复
+
+- **@heroui/react**：将 `react-aria` 子路径与其他 `@react-*` 和 `react-aria-components` 一起在 Rollup 构建中外部化，使 `@heroui/react` 不再内置自己的 `react-aria` 副本。消费方现在会解析到项目中安装的单一 `react-aria`，避免重复实例的问题以及不必要的产物体积膨胀 ([#6653](https://github.com/heroui-inc/heroui/pull/6653))。
+- **SwitchGroup**：补全缺失的 `switch-group__items` 包装层，使 `orientation="horizontal"` 时开关横向排列，而不再垂直堆叠 ([#6655](https://github.com/heroui-inc/heroui/pull/6655))。
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6654](https://github.com/heroui-inc/heroui/pull/6654)
+
+## 贡献者
+
+感谢所有为本次发布做出贡献的人！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/cn/react/releases/v3-2-2.mdx b/apps/docs/content/docs/cn/react/releases/v3-2-2.mdx
new file mode 100644
index 0000000..582403f
--- /dev/null
+++ b/apps/docs/content/docs/cn/react/releases/v3-2-2.mdx
@@ -0,0 +1,87 @@
+---
+title: v3.2.2
+description: 补丁版本：将 React Aria 升级到 1.19.0，为 Tabs.ListContainer 添加溢出滚动，并修复清除/关闭按钮意外提交表单以及视觉隐藏输入框导致溢出滚动的问题。
+github:
+  pull: 6660
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">2026 年 6 月 19 日</span>
+</div>
+
+补丁版本：升级到 React Aria `1.19.0`（`react-aria@3.50.0`），为 [Tabs](/docs/components/tabs) 的 `Tabs.ListContainer` 添加溢出滚动，并修复多个回归问题 —— 清除和关闭按钮不再提交其所在的表单，`Checkbox`、`Radio` 和 `Switch` 中的视觉隐藏输入框不再导致溢出滚动。
+
+## 安装
+
+升级到最新版本：
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **正在使用 AI 助手？** 对它说「Hey Cursor，把 HeroUI 升级到最新版本」。它会自动对比版本并应用必要变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
+</Callout>
+
+## 新功能
+
+### Tabs
+
+当标签列表超出可用空间时，`Tabs.ListContainer` 会自动渲染滚动箭头和边缘渐变，以便用户浏览隐藏的标签。适用于横向和纵向布局。
+
+- **溢出滚动**：用 `Tabs.ListContainer` 包裹 `Tabs.List`，即可获得滚动箭头和边缘渐变 ([#6696](https://github.com/heroui-inc/heroui/pull/6696))
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-overflow"
+/>
+
+## 错误修复
+
+- **输入框**：为清除和关闭按钮设置 `type="button"`，使其在点击时不再提交所在的表单 ([#6656](https://github.com/heroui-inc/heroui/pull/6656))。
+- **Checkbox / Radio / Switch**：避免视觉隐藏的输入框导致溢出滚动 ([#6657](https://github.com/heroui-inc/heroui/pull/6657))。
+- **Button / Dropdown / Menu**：添加 `will-change-transform`，避免在变换过程中图标或文本发生偏移 ([#6661](https://github.com/heroui-inc/heroui/pull/6661))。
+- **Chip**：将宽度设置为 `w-fit`，使 chip 根据内容自适应宽度，而非拉伸填满容器 ([#6664](https://github.com/heroui-inc/heroui/pull/6664))。
+- **DatePicker / DateRangePicker**：使用 `w-fit` 替代 `min-w-(--trigger-width)`，避免弹出层宽度过宽 ([#6665](https://github.com/heroui-inc/heroui/pull/6665))。
+- **Autocomplete**：修正虚拟化列表项的右内边距，使列表项不再溢出到弹出层边缘 ([#6672](https://github.com/heroui-inc/heroui/pull/6672))。
+- **Toast**：在 toast 队列中捕获 ViewTransition 的 `ready` 拒绝，使被取代的过渡不再产生未处理的 Promise 拒绝 ([#6674](https://github.com/heroui-inc/heroui/pull/6674))。
+
+## 重构
+
+- **React 19 API**：使用 `use()` hook 替代 `useContext`，并将 `ref` 作为普通 prop 传递；将数组索引 key 替换为稳定 key ([#6688](https://github.com/heroui-inc/heroui/pull/6688))。
+
+## 依赖
+
+- **React Aria**：升级到 `react-aria-components@1.19.0` 和 `react-aria@3.50.0` ([#6658](https://github.com/heroui-inc/heroui/pull/6658))。
+- **React Aria**：将 `react-aria`（`^3.50.0`）和 `react-aria-components`（`^1.19.0`）声明为 caret 范围，以便与 HeroUI Pro 去重 ([#6689](https://github.com/heroui-inc/heroui/pull/6689))。
+
+## 链接
+
+- [组件文档](/docs/react/components)
+- [GitHub 仓库](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6660](https://github.com/heroui-inc/heroui/pull/6660)
+
+## 贡献者
+
+感谢所有为本次发布做出贡献的人！
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/meta.json b/apps/docs/content/docs/en/meta.json
new file mode 100644
index 0000000..811019d
--- /dev/null
+++ b/apps/docs/content/docs/en/meta.json
@@ -0,0 +1,3 @@
+{
+  "pages": ["react", "native"]
+}
diff --git a/apps/docs/content/docs/en/native/components/(buttons)/button.mdx b/apps/docs/content/docs/en/native/components/(buttons)/button.mdx
new file mode 100644
index 0000000..1a95125
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(buttons)/button.mdx
@@ -0,0 +1,391 @@
+---
+title: Button
+description: Interactive component that triggers an action when pressed.
+links:
+  source_native: button/button.tsx
+  styles_native: button/button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/button-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Button } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Button>
+  <Button.Label>...</Button.Label>
+</Button>
+```
+
+- **Button**: Main container that handles press interactions, animations, and variants. Renders string children as label or accepts compound components for custom layouts.
+- **Button.Label**: Text content of the button. Inherits size and variant styling from parent Button context.
+
+## Usage
+
+### Basic Usage
+
+The Button component accepts string children that automatically render as label.
+
+```tsx
+<Button>Basic Button</Button>
+```
+
+### With Compound Parts
+
+Use Button.Label for explicit control over the label component.
+
+```tsx
+<Button>
+  <Button.Label>Click me</Button.Label>
+</Button>
+```
+
+### With Icons
+
+Combine icons with labels for enhanced visual communication.
+
+```tsx
+<Button>
+  <Icon name="add" size={20} />
+  <Button.Label>Add Item</Button.Label>
+</Button>
+
+<Button>
+  <Button.Label>Download</Button.Label>
+  <Icon name="download" size={18} />
+</Button>
+```
+
+### Icon Only
+
+Create square icon-only buttons using the isIconOnly prop.
+
+```tsx
+<Button isIconOnly>
+  <Icon name="heart" size={18} />
+</Button>
+```
+
+### Sizes
+
+Control button dimensions with three size options.
+
+```tsx
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+```
+
+### Variants
+
+Choose from seven visual variants for different emphasis levels.
+
+```tsx
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="tertiary">Tertiary</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="danger">Danger</Button>
+<Button variant="danger-soft">Danger Soft</Button>
+```
+
+### Feedback Variants
+
+The `feedbackVariant` prop controls which press feedback effects are rendered:
+
+- `'scale-highlight'` (default): Built-in scale + highlight overlay
+- `'scale-ripple'`: Built-in scale + ripple overlay
+- `'scale'`: Built-in scale only (no overlay)
+- `'none'`: No feedback animations at all
+
+```tsx
+{/* Scale + Highlight (default) */}
+<Button feedbackVariant="scale-highlight">Highlight Effect</Button>
+
+{/* Scale + Ripple */}
+<Button feedbackVariant="scale-ripple">Ripple Effect</Button>
+
+{/* Scale only */}
+<Button feedbackVariant="scale">Scale Only</Button>
+
+{/* No feedback */}
+<Button feedbackVariant="none">No Feedback</Button>
+```
+
+### Custom Animation
+
+The `animation` prop controls individual sub-animations. Its shape depends on the `feedbackVariant`.
+
+```tsx
+{/* Customize scale and highlight (default feedbackVariant) */}
+<Button
+  animation={{
+    scale: { value: 0.97 },
+    highlight: {
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.2] },
+    },
+  }}
+>
+  Custom Highlight
+</Button>
+
+{/* Customize scale and ripple */}
+<Button
+  feedbackVariant="scale-ripple"
+  animation={{
+    scale: { value: 0.97 },
+    ripple: {
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.3, 0] },
+    },
+  }}
+>
+  Custom Ripple
+</Button>
+```
+
+### Disable Individual Animations
+
+Disable specific sub-animations by setting them to `false`:
+
+```tsx
+{/* Disable scale, keep highlight */}
+<Button animation={{ scale: false }}>No Scale</Button>
+
+{/* Disable highlight, keep scale */}
+<Button animation={{ highlight: false }}>No Highlight</Button>
+
+{/* Disable both */}
+<Button animation={{ scale: false, highlight: false }}>No Animations</Button>
+```
+
+### Disable All Animations
+
+Use `animation={false}` to disable all feedback, or `animation="disable-all"` for cascading disable:
+
+```tsx
+<Button animation={false}>Disabled</Button>
+<Button animation="disable-all">Disable All (cascading)</Button>
+```
+
+### Loading State with Spinner
+
+Transform button to loading state with spinner animation.
+
+```tsx
+const themeColorAccentForeground = useThemeColor('accent-foreground');
+
+<Button
+  layout={LinearTransition.springify()}
+  variant="primary"
+  onPress={() => {
+    setIsDownloading(true);
+    setTimeout(() => {
+      setIsDownloading(false);
+    }, 3000);
+  }}
+  isIconOnly={isDownloading}
+  className="self-center"
+>
+  {isDownloading ? (
+    <Spinner entering={FadeIn.delay(50)} color={themeColorAccentForeground} />
+  ) : (
+    'Download now'
+  )}
+</Button>;
+```
+
+### Custom Background with LinearGradient
+
+Add gradient backgrounds using absolute positioned elements. Use `feedbackVariant="none"` to disable the default highlight overlay, or use `feedbackVariant="scale-ripple"` for a custom ripple effect.
+
+```tsx
+import { Button, PressableFeedback } from 'heroui-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { StyleSheet } from 'react-native';
+
+{/* Gradient with no feedback overlay */}
+<Button feedbackVariant="none">
+  <LinearGradient
+    colors={['#9333ea', '#ec4899']}
+    start={{ x: 0, y: 0 }}
+    end={{ x: 1, y: 0 }}
+    style={StyleSheet.absoluteFill}
+  />
+  <Button.Label className="text-white font-bold">Gradient</Button.Label>
+</Button>
+
+{/* Gradient with custom ripple effect */}
+<Button
+  feedbackVariant="scale-ripple"
+  animation={{
+    ripple: {
+      backgroundColor: { value: 'white' },
+      opacity: { value: [0, 0.5, 0] },
+    },
+  }}
+>
+  <LinearGradient
+    colors={['#0d9488', '#ec4899']}
+    start={{ x: 0, y: 0 }}
+    end={{ x: 1, y: 0 }}
+    style={StyleSheet.absoluteFill}
+  />
+  <Button.Label className="text-white font-bold" pointerEvents="none">
+    Gradient with Ripple
+  </Button.Label>
+</Button>
+```
+
+## Example
+
+```tsx
+import { Button, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+
+export default function ButtonExample() {
+  const [
+    themeColorAccentForeground,
+    themeColorAccentSoftForeground,
+    themeColorDangerForeground,
+    themeColorDefaultForeground,
+  ] = useThemeColor([
+    'accent-foreground',
+    'accent-soft-foreground',
+    'danger-foreground',
+    'default-foreground',
+  ]);
+
+  return (
+    <View className="gap-4 p-4">
+      <Button variant="primary">
+        <Ionicons name="add" size={20} color={themeColorAccentForeground} />
+        <Button.Label>Add Item</Button.Label>
+      </Button>
+
+      <View className="flex-row gap-4">
+        <Button size="sm" isIconOnly>
+          <Ionicons name="heart" size={16} color={themeColorAccentForeground} />
+        </Button>
+        <Button size="sm" variant="secondary" isIconOnly>
+          <Ionicons
+            name="bookmark"
+            size={16}
+            color={themeColorAccentSoftForeground}
+          />
+        </Button>
+        <Button size="sm" variant="danger" isIconOnly>
+          <Ionicons name="trash" size={16} color={themeColorDangerForeground} />
+        </Button>
+      </View>
+
+      <Button variant="tertiary">
+        <Button.Label>Learn More</Button.Label>
+        <Ionicons
+          name="chevron-forward"
+          size={18}
+          color={themeColorDefaultForeground}
+        />
+      </Button>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/button.tsx>).
+
+## API Reference
+
+### Button
+
+Button extends all props from [PressableFeedback](./pressable-feedback) (except `animation`, which is redefined) with additional button-specific props.
+
+| prop              | type                                                                                          | default             | description                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
+| `variant`         | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'`         | Visual variant of the button                                   |
+| `size`            | `'sm' \| 'md' \| 'lg'`                                                                        | `'md'`              | Size of the button                                             |
+| `isIconOnly`      | `boolean`                                                                                     | `false`             | Whether the button displays an icon only (square aspect ratio) |
+| `feedbackVariant` | `'scale-highlight' \| 'scale-ripple' \| 'scale' \| 'none'`                                    | `'scale-highlight'` | Determines which feedback effects are rendered                 |
+| `animation`       | `ButtonAnimation`                                                                             | -                   | Animation configuration (shape depends on `feedbackVariant`)   |
+
+For inherited props including `isDisabled`, `className`, `children`, and all Pressable props, see [PressableFeedback API Reference](./pressable-feedback#api-reference).
+
+#### ButtonAnimation
+
+The `animation` prop is a discriminated union based on `feedbackVariant`. It follows the `AnimationRoot` control flow:
+
+- `true` or `undefined`: Use default animations
+- `false` or `"disabled"`: Disable all feedback animations
+- `"disable-all"`: Cascade-disable all animations including child compound parts
+- `object`: Custom configuration with sub-animation keys (see below)
+
+**When `feedbackVariant="scale-highlight"` (default):**
+
+| prop        | type                                     | default | description                                                  |
+| ----------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale`     | `PressableFeedbackScaleAnimation`        | -       | Scale animation config (`false` to disable)                  |
+| `highlight` | `PressableFeedbackHighlightAnimation`    | -       | Highlight overlay config (`false` to disable)                |
+| `state`     | `'disabled' \| 'disable-all' \| boolean` | -       | Control animation state while keeping config (runtime toggle) |
+
+**When `feedbackVariant="scale-ripple"`:**
+
+| prop     | type                                     | default | description                                                  |
+| -------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale`  | `PressableFeedbackScaleAnimation`        | -       | Scale animation config (`false` to disable)                  |
+| `ripple` | `PressableFeedbackRippleAnimation`       | -       | Ripple overlay config (`false` to disable)                   |
+| `state`  | `'disabled' \| 'disable-all' \| boolean` | -       | Control animation state while keeping config (runtime toggle) |
+
+**When `feedbackVariant="scale"`:**
+
+| prop    | type                                     | default | description                                                  |
+| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
+| `scale` | `PressableFeedbackScaleAnimation`        | -       | Scale animation config (`false` to disable)                  |
+| `state` | `'disabled' \| 'disable-all' \| boolean` | -       | Control animation state while keeping config (runtime toggle) |
+
+**When `feedbackVariant="none"`:**
+
+Only `'disable-all'` is accepted as a string value. All feedback effects are disabled.
+
+For detailed animation sub-types (`PressableFeedbackScaleAnimation`, `PressableFeedbackHighlightAnimation`, `PressableFeedbackRippleAnimation`), see [PressableFeedback API Reference](./pressable-feedback#api-reference).
+
+### Button.Label
+
+| prop           | type              | default | description                           |
+| -------------- | ----------------- | ------- | ------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to be rendered as label       |
+| `className`    | `string`          | -       | Additional CSS classes                |
+| `...TextProps` | `TextProps`       | -       | All standard Text props are supported |
+
+## Hooks
+
+### useButton
+
+Hook to access the Button context values. Returns the button's size, variant, and disabled state.
+
+```tsx
+import { useButton } from 'heroui-native';
+
+const { size, variant, isDisabled } = useButton();
+```
+
+#### Return Value
+
+| property     | type                                                                                          | description                    |
+| ------------ | --------------------------------------------------------------------------------------------- | ------------------------------ |
+| `size`       | `'sm' \| 'md' \| 'lg'`                                                                        | Size of the button             |
+| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | Visual variant of the button   |
+| `isDisabled` | `boolean`                                                                                     | Whether the button is disabled |
+
+**Note:** This hook must be used within a `Button` component. It will throw an error if called outside of the button context.
diff --git a/apps/docs/content/docs/en/native/components/(buttons)/close-button.mdx b/apps/docs/content/docs/en/native/components/(buttons)/close-button.mdx
new file mode 100644
index 0000000..3ce7506
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(buttons)/close-button.mdx
@@ -0,0 +1,119 @@
+---
+title: CloseButton
+description: Button component for closing dialogs, modals, or dismissing content.
+links:
+  source_native: close-button/close-button.tsx
+  styles_native: close-button/close-button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { CloseButton } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The CloseButton component renders a close icon button with default styling.
+
+```tsx
+<CloseButton />
+```
+
+### Custom Icon Color
+
+Customize the icon color using the `iconProps` prop.
+
+```tsx
+<CloseButton iconProps={{ color: themeColorDanger }} />
+<CloseButton iconProps={{ color: themeColorAccent }} />
+```
+
+### Custom Icon Size
+
+Adjust the icon size using the `iconProps` prop.
+
+```tsx
+<CloseButton iconProps={{ size: 24 }} />
+```
+
+### Custom Children
+
+Replace the default close icon with custom content.
+
+```tsx
+<CloseButton>
+  <CustomIcon />
+</CloseButton>
+```
+
+### Disabled State
+
+Disable the button to prevent interactions.
+
+```tsx
+<CloseButton isDisabled />
+```
+
+## Example
+
+```tsx
+import { CloseButton, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function CloseButtonExample() {
+  const themeColorForeground = useThemeColor('foreground');
+  const themeColorDanger = useThemeColor('danger');
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View className="flex-row items-center gap-4">
+        <CloseButton />
+        <CloseButton iconProps={{ color: themeColorDanger }} />
+        <CloseButton>
+          <StyledIonicons
+            name="close-circle"
+            size={28}
+            color={themeColorForeground}
+          />
+        </CloseButton>
+        <CloseButton isDisabled />
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/close-button.tsx).
+
+## API Reference
+
+### CloseButton
+
+CloseButton extends all props from [Button](./button) component. It defaults to `variant='tertiary'`, `size='sm'`, and `isIconOnly=true`.
+
+| prop        | type                   | default | description                                      |
+| ----------- | ---------------------- | ------- | ------------------------------------------------ |
+| `iconProps` | `CloseButtonIconProps` | -       | Props for customizing the close icon             |
+| `children`  | `React.ReactNode`      | -       | Custom content to replace the default close icon |
+
+For inherited props including `isDisabled`, `className`, `animation`, `feedbackVariant` and all Pressable props, see [Button API Reference](./button#api-reference).
+
+#### CloseButtonIconProps
+
+| prop    | type     | default                | description       |
+| ------- | -------- | ---------------------- | ----------------- |
+| `size`  | `number` | `20`                   | Size of the icon  |
+| `color` | `string` | Uses theme muted color | Color of the icon |
diff --git a/apps/docs/content/docs/en/native/components/(buttons)/link-button.mdx b/apps/docs/content/docs/en/native/components/(buttons)/link-button.mdx
new file mode 100644
index 0000000..67ae017
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(buttons)/link-button.mdx
@@ -0,0 +1,164 @@
+---
+title: LinkButton
+description: A ghost-variant button with no highlight feedback, designed for inline link-style interactions.
+links:
+  source_native: link-button/link-button.tsx
+  styles_native: link-button/link-button.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { LinkButton } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<LinkButton>
+  <LinkButton.Label>...</LinkButton.Label>
+</LinkButton>
+```
+
+- **LinkButton**: Root pressable container. Renders a `Button` with the `ghost` variant and disabled highlight feedback enforced internally. These cannot be overridden by consumers.
+- **LinkButton.Label**: Text content of the link button. Inherits size and variant styling from the parent context.
+
+## Usage
+
+### Basic Usage
+
+The LinkButton component renders inline link-style text that responds to press events.
+
+```tsx
+<LinkButton onPress={handlePress}>Learn more</LinkButton>
+```
+
+### Sizes
+
+Control the text size with the `size` prop.
+
+```tsx
+<LinkButton size="sm">
+  Small
+</LinkButton>
+
+<LinkButton size="md">
+  Medium
+</LinkButton>
+
+<LinkButton size="lg">
+  Large
+</LinkButton>
+```
+
+### Disabled State
+
+Disable the link button to prevent interaction.
+
+```tsx
+<LinkButton isDisabled>Disabled link</LinkButton>
+```
+
+### Custom Styling
+
+Apply custom styles using the `className` prop on both root and label.
+
+```tsx
+<LinkButton className="px-2">
+  <LinkButton.Label className="text-accent underline">
+    Styled link
+  </LinkButton.Label>
+</LinkButton>
+```
+
+### Inline with Text
+
+Place link buttons inline alongside regular text for terms, policies, or contextual navigation.
+
+```tsx
+<View className="flex-row flex-wrap">
+  <Text className="text-sm text-muted">I agree to the </Text>
+  <LinkButton size="sm" onPress={handleTermsPress}>
+    <LinkButton.Label className="text-accent">
+      Terms of Service
+    </LinkButton.Label>
+  </LinkButton>
+  <Text className="text-sm text-muted"> and </Text>
+  <LinkButton size="sm" onPress={handlePrivacyPress}>
+    <LinkButton.Label className="text-accent">Privacy Policy</LinkButton.Label>
+  </LinkButton>
+</View>
+```
+
+## Example
+
+```tsx
+import { Button, Checkbox, ControlField, LinkButton } from 'heroui-native';
+import React from 'react';
+import { Alert, View } from 'react-native';
+
+export default function LinkButtonExample() {
+  const [isAgreed, setIsAgreed] = React.useState(false);
+
+  const handleTermsPress = () => Alert.alert('Terms', 'Navigate to Terms');
+  const handlePrivacyPress = () =>
+    Alert.alert('Privacy', 'Navigate to Privacy Policy');
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View className="w-full max-w-xs gap-6">
+        <ControlField
+          isSelected={isAgreed}
+          onSelectedChange={setIsAgreed}
+          className="items-start"
+        >
+          <ControlField.Indicator>
+            <Checkbox className="mt-0.5" />
+          </ControlField.Indicator>
+          <View className="flex-row flex-wrap flex-1">
+            <Text className="text-sm text-muted">I agree to the </Text>
+            <LinkButton size="sm" onPress={handleTermsPress}>
+              <LinkButton.Label className="text-accent">
+                Terms of Service
+              </LinkButton.Label>
+            </LinkButton>
+            <Text className="text-sm text-muted"> and </Text>
+            <LinkButton size="sm" onPress={handlePrivacyPress}>
+              <LinkButton.Label className="text-accent">
+                Privacy Policy
+              </LinkButton.Label>
+            </LinkButton>
+          </View>
+        </ControlField>
+        <Button isDisabled={!isAgreed}>Sign up</Button>
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/link-button.tsx>).
+
+## API Reference
+
+### LinkButton
+
+Extends all [Button](./button#button) props except `variant` (enforced as `ghost` internally).
+
+**Behavioral overrides applied internally:**
+
+| override    | value        | description                                         |
+| ----------- | ------------ | --------------------------------------------------- |
+| `variant`   | `ghost`      | Always renders as a ghost button, cannot be changed |
+| `highlight` | `false`      | Highlight feedback is disabled, cannot be changed   |
+| `className` | `h-auto p-0` | Removes default button height and padding           |
+
+### LinkButton.Label
+
+Equivalent to [Button.Label](./button#buttonlabel). Accepts the same props.
diff --git a/apps/docs/content/docs/en/native/components/(collections)/menu.mdx b/apps/docs/content/docs/en/native/components/(collections)/menu.mdx
new file mode 100644
index 0000000..6041274
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(collections)/menu.mdx
@@ -0,0 +1,810 @@
+---
+title: Menu
+description: A floating context menu with positioning, selection groups, and multiple presentation modes.
+links:
+  source_native: menu/menu.tsx
+  styles_native: menu/menu.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Menu, SubMenu } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover">
+      <Menu.Close />
+      <Menu.Label>...</Menu.Label>
+      <Menu.Group>
+        <Menu.Item>
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>...</Menu.ItemTitle>
+          <Menu.ItemDescription>...</Menu.ItemDescription>
+        </Menu.Item>
+      </Menu.Group>
+      <SubMenu>
+        <SubMenu.Trigger textValue="...">
+          <SubMenu.TriggerIndicator />
+          ...
+        </SubMenu.Trigger>
+        <SubMenu.Content>
+          <Menu.Item>...</Menu.Item>
+          <Menu.Item>...</Menu.Item>
+        </SubMenu.Content>
+      </SubMenu>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+- **Menu**: Main container that manages open/close state, positioning, and provides context to child components.
+- **Menu.Trigger**: Clickable element that toggles the menu visibility.
+- **Menu.Portal**: Renders menu content in a portal layer above other content.
+- **Menu.Overlay**: Optional background overlay to capture outside clicks and close the menu.
+- **Menu.Content**: Container for menu content with two presentation modes: floating popover with positioning and collision detection, or bottom sheet modal.
+- **Menu.Close**: Close button that dismisses the menu when pressed.
+- **Menu.Label**: Non-interactive section heading text within the menu.
+- **Menu.Group**: Groups menu items with optional selection state (none, single, multiple).
+- **Menu.Item**: Pressable menu item with animated press feedback. Standalone or within a Group for selection.
+- **Menu.ItemTitle**: Primary label text for a menu item.
+- **Menu.ItemDescription**: Secondary description text for a menu item.
+- **Menu.ItemIndicator**: Visual selection indicator (checkmark or dot) for a menu item.
+- **SubMenu**: Root container that manages the expand/collapse state and provides animation context to children.
+- **SubMenu.Trigger**: Pressable row that toggles the submenu open/closed. Styled like a regular menu item.
+- **SubMenu.TriggerIndicator**: Animated chevron icon (default: chevron-right) that rotates when the submenu opens/closes. Place inside `SubMenu.Trigger`.
+- **SubMenu.Content**: Absolutely positioned container that animates its height when the submenu opens/closes. Place `Menu.Item` elements inside.
+
+## Usage
+
+### Basic Usage
+
+The Menu component uses compound parts to create a floating context menu.
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={220}>
+      <Menu.Item>
+        <Menu.ItemTitle>View Profile</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Settings</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### With Item Descriptions
+
+Add secondary description text to menu items alongside titles.
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={260}>
+      <Menu.Item className="items-start">
+        <View className="flex-1">
+          <Menu.ItemTitle>New file</Menu.ItemTitle>
+          <Menu.ItemDescription>Create a new file</Menu.ItemDescription>
+        </View>
+      </Menu.Item>
+      <Menu.Item className="items-start">
+        <View className="flex-1">
+          <Menu.ItemTitle>Copy link</Menu.ItemTitle>
+          <Menu.ItemDescription>Copy the file link</Menu.ItemDescription>
+        </View>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Single Selection
+
+Use `Menu.Group` with `selectionMode="single"` to allow one selected item at a time.
+
+```tsx
+const [theme, setTheme] = useState<Set<MenuKey>>(() => new Set(['system']));
+
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={180}>
+      <Menu.Label>Appearance</Menu.Label>
+      <Menu.Group
+        selectionMode="single"
+        selectedKeys={theme}
+        onSelectionChange={setTheme}
+      >
+        <Menu.Item id="light">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Light</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="dark">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Dark</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="system">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>System</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>;
+```
+
+### Multiple Selection
+
+Use `selectionMode="multiple"` to allow selecting multiple items simultaneously.
+
+```tsx
+const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
+  () => new Set(['bold', 'italic'])
+);
+
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={250}>
+      <Menu.Label>Text Style</Menu.Label>
+      <Menu.Group
+        selectionMode="multiple"
+        selectedKeys={textStyles}
+        onSelectionChange={setTextStyles}
+      >
+        <Menu.Item id="bold">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Bold</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="italic">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Italic</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="underline">
+          <Menu.ItemIndicator />
+          <Menu.ItemTitle>Underline</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>;
+```
+
+### With SubMenu
+
+Nest a `SubMenu` inside `Menu.Content` to reveal additional items on press.
+
+```tsx
+<Menu>
+  <Menu.Trigger asChild>
+    <Button variant="secondary">Editor Menu</Button>
+  </Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={240}>
+      <Menu.Item>
+        <Menu.ItemTitle>New Space</Menu.ItemTitle>
+      </Menu.Item>
+      <SubMenu>
+        <SubMenu.Trigger textValue="Focus">
+          <SubMenu.TriggerIndicator />
+          <Text className="flex-1 text-base font-medium text-foreground">
+            Focus
+          </Text>
+        </SubMenu.Trigger>
+        <SubMenu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Zen Mode</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Reader Mode</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Lock Tab</Menu.ItemTitle>
+          </Menu.Item>
+        </SubMenu.Content>
+      </SubMenu>
+      <Menu.Item>
+        <Menu.ItemTitle>Heading 1</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Danger Variant
+
+Use `variant="danger"` on a menu item for destructive actions.
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={220}>
+      <Menu.Item>
+        <Menu.ItemTitle>Edit</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item variant="danger">
+        <Menu.ItemTitle>Delete</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Placements
+
+Control where the menu appears relative to the trigger.
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" placement="right" width={200}>
+      <Menu.Item>
+        <Menu.ItemTitle>Option A</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Option B</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Bottom Sheet Presentation
+
+Use `presentation="bottom-sheet"` to display menu content as a bottom sheet modal.
+
+```tsx
+<Menu presentation="bottom-sheet">
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="bottom-sheet">
+      <Menu.Item>
+        <Menu.ItemTitle>Option A</Menu.ItemTitle>
+      </Menu.Item>
+      <Menu.Item>
+        <Menu.ItemTitle>Option B</Menu.ItemTitle>
+      </Menu.Item>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+### Dot Indicator
+
+Use `variant="dot"` on `Menu.ItemIndicator` to show a filled circle instead of a checkmark.
+
+```tsx
+<Menu>
+  <Menu.Trigger>...</Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Overlay />
+    <Menu.Content presentation="popover" width={180}>
+      <Menu.Group
+        selectionMode="single"
+        selectedKeys={alignment}
+        onSelectionChange={setAlignment}
+      >
+        <Menu.Item id="left">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Left</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="center">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Center</Menu.ItemTitle>
+        </Menu.Item>
+        <Menu.Item id="right">
+          <Menu.ItemIndicator variant="dot" />
+          <Menu.ItemTitle>Right</Menu.ItemTitle>
+        </Menu.Item>
+      </Menu.Group>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu>
+```
+
+## Example
+
+```tsx
+import type { MenuKey } from 'heroui-native';
+import { Button, Menu, Separator } from 'heroui-native';
+import { useState } from 'react';
+import { Text, View } from 'react-native';
+
+export default function MenuExample() {
+  const [textStyles, setTextStyles] = useState<Set<MenuKey>>(
+    () => new Set(['bold', 'italic'])
+  );
+  const [alignment, setAlignment] = useState<Set<MenuKey>>(
+    () => new Set(['left'])
+  );
+
+  return (
+    <Menu>
+      <Menu.Trigger asChild>
+        <Button variant="secondary">Styles</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content presentation="popover" width={250}>
+          <Menu.Label className="mb-1">Text Style</Menu.Label>
+          <Menu.Group
+            selectionMode="multiple"
+            selectedKeys={textStyles}
+            onSelectionChange={setTextStyles}
+          >
+            <Menu.Item id="bold">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Bold</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ B</Text>
+            </Menu.Item>
+            <Menu.Item id="italic">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Italic</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ I</Text>
+            </Menu.Item>
+            <Menu.Item id="underline">
+              <Menu.ItemIndicator />
+              <Menu.ItemTitle>Underline</Menu.ItemTitle>
+              <Text className="text-sm text-muted">⌘ U</Text>
+            </Menu.Item>
+          </Menu.Group>
+          <Separator className="mx-2 my-2 opacity-75" />
+          <Menu.Label className="mb-1">Text Alignment</Menu.Label>
+          <Menu.Group
+            selectionMode="single"
+            selectedKeys={alignment}
+            onSelectionChange={setAlignment}
+          >
+            <Menu.Item id="left">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Left</Menu.ItemTitle>
+            </Menu.Item>
+            <Menu.Item id="center">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Center</Menu.ItemTitle>
+            </Menu.Item>
+            <Menu.Item id="right">
+              <Menu.ItemIndicator variant="dot" />
+              <Menu.ItemTitle>Right</Menu.ItemTitle>
+            </Menu.Item>
+          </Menu.Group>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/menu.tsx>).
+
+## API Reference
+
+### Menu
+
+| prop            | type                          | default     | description                                        |
+| --------------- | ----------------------------- | ----------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`             | -           | The content of the menu                            |
+| `presentation`  | `'popover' \| 'bottom-sheet'` | `'popover'` | Presentation mode for the menu content             |
+| `isOpen`        | `boolean`                     | -           | Controlled open state of the menu                  |
+| `isDefaultOpen` | `boolean`                     | -           | Open state when initially rendered (uncontrolled)  |
+| `isDisabled`    | `boolean`                     | -           | Whether the menu is disabled                       |
+| `animation`     | `MenuRootAnimation`           | -           | Animation configuration for menu root              |
+| `onOpenChange`  | `(open: boolean) => void`     | -           | Callback fired when the menu open state changes    |
+| `...ViewProps`  | `ViewProps`                   | -           | All standard React Native View props are supported |
+
+#### MenuRootAnimation
+
+Animation configuration for menu root component. Can be:
+
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+
+### Menu.Trigger
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | The trigger element content                             |
+| `className`         | `string`          | -       | Additional CSS class for the trigger                    |
+| `isDisabled`        | `boolean`         | `false` | Whether the trigger is disabled                         |
+| `asChild`           | `boolean`         | -       | Render as child element using Slot pattern              |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+### Menu.Portal
+
+| prop                       | type              | default | description                                            |
+| -------------------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`                 | `React.ReactNode` | -       | The portal content                                     |
+| `className`                | `string`          | -       | Additional CSS class for the portal container          |
+| `disableFullWindowOverlay` | `boolean`         | `false` | Use a regular View instead of FullWindowOverlay on iOS |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `hostName`                 | `string`          | -       | Optional name of the host element for the portal       |
+| `forceMount`               | `boolean`         | -       | Force mount the portal regardless of open state        |
+
+### Menu.Overlay
+
+| prop                    | type                   | default | description                                                  |
+| ----------------------- | ---------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`               | -       | Additional CSS class for the overlay                         |
+| `closeOnPress`          | `boolean`              | `true`  | Whether to close the menu when the overlay is pressed        |
+| `animation`             | `MenuOverlayAnimation` | -       | Animation configuration for overlay                          |
+| `isAnimatedStyleActive` | `boolean`              | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `forceMount`            | `boolean`              | -       | Force mount the overlay regardless of open state             |
+| `...PressableProps`     | `PressableProps`       | -       | All standard React Native Pressable props are supported      |
+
+#### MenuOverlayAnimation
+
+Animation configuration for menu overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                     | type                    | default                 | description                                     |
+| ------------------------ | ----------------------- | ----------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| boolean` | -                       | Disable animations while customizing properties |
+| `opacity.entering.value` | `EntryOrExitLayoutType` | `FadeIn.duration(200)`  | Custom entering animation for overlay           |
+| `opacity.exiting.value`  | `EntryOrExitLayoutType` | `FadeOut.duration(150)` | Custom exiting animation for overlay            |
+
+### Menu.Content (Popover)
+
+Props when `presentation="popover"`.
+
+| prop              | type                                             | default         | description                                        |
+| ----------------- | ------------------------------------------------ | --------------- | -------------------------------------------------- |
+| `children`        | `React.ReactNode`                                | -               | The menu content                                   |
+| `presentation`    | `'popover'`                                      | -               | Presentation mode (must match Menu root)           |
+| `placement`       | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | Where the menu appears relative to the trigger     |
+| `align`           | `'start' \| 'center' \| 'end'`                   | `'center'`      | Alignment of the menu relative to the trigger      |
+| `avoidCollisions` | `boolean`                                        | `true`          | Whether to reposition to avoid screen edges        |
+| `offset`          | `number`                                         | `9`             | Distance from the trigger element in pixels        |
+| `alignOffset`     | `number`                                         | `0`             | Offset along the alignment axis in pixels          |
+| `width`           | `'content-fit' \| 'trigger' \| 'full' \| number` | `'content-fit'` | Content width sizing strategy                      |
+| `className`       | `string`                                         | -               | Additional CSS class for the content container     |
+| `animation`       | `MenuContentAnimation`                           | -               | Animation configuration for content                |
+| `...ViewProps`    | `ViewProps`                                      | -               | All standard React Native View props are supported |
+
+#### MenuContentAnimation
+
+Animation configuration for menu popover content component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                    | default                         | description                                     |
+| ---------------- | ----------------------- | ------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| boolean` | -                               | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType` | Scale + fade entering animation | Custom entering animation for content           |
+| `exiting.value`  | `EntryOrExitLayoutType` | Scale + fade exiting animation  | Custom exiting animation for content            |
+
+### Menu.Content (Bottom Sheet)
+
+Props when `presentation="bottom-sheet"`. Extends `@gorhom/bottom-sheet` BottomSheet props.
+
+| prop                        | type                                     | default | description                                          |
+| --------------------------- | ---------------------------------------- | ------- | ---------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -       | The bottom sheet content                             |
+| `presentation`              | `'bottom-sheet'`                         | -       | Presentation mode (must match Menu root)             |
+| `className`                 | `string`                                 | -       | Additional CSS class for the bottom sheet            |
+| `backgroundClassName`       | `string`                                 | -       | Additional CSS class for the background              |
+| `handleIndicatorClassName`  | `string`                                 | -       | Additional CSS class for the handle indicator        |
+| `contentContainerClassName` | `string`                                 | -       | Additional CSS class for the content container       |
+| `contentContainerProps`     | `Omit<BottomSheetViewProps, 'children'>` | -       | Props for the content container                      |
+| `animation`                 | `AnimationDisabled`                      | -       | Set to `false` or `"disabled"` to disable animations |
+| `...BottomSheetProps`       | `Partial<BottomSheetProps>`              | -       | All `@gorhom/bottom-sheet` props are supported       |
+
+### Menu.Close
+
+Extends `CloseButtonProps`. Automatically closes the menu when pressed.
+
+| prop             | type                   | default | description                          |
+| ---------------- | ---------------------- | ------- | ------------------------------------ |
+| `iconProps`      | `CloseButtonIconProps` | -       | Props for customizing the close icon |
+| `...ButtonProps` | `ButtonRootProps`      | -       | All Button root props are supported  |
+
+### Menu.Group
+
+| prop                  | type                               | default  | description                                        |
+| --------------------- | ---------------------------------- | -------- | -------------------------------------------------- |
+| `children`            | `React.ReactNode`                  | -        | The group content (Menu.Item elements)             |
+| `selectionMode`       | `'none' \| 'single' \| 'multiple'` | `'none'` | The type of selection allowed in the group         |
+| `selectedKeys`        | `Iterable<MenuKey>`                | -        | Currently selected keys (controlled)               |
+| `defaultSelectedKeys` | `Iterable<MenuKey>`                | -        | Initially selected keys (uncontrolled)             |
+| `isDisabled`          | `boolean`                          | `false`  | Whether the entire group is disabled               |
+| `disabledKeys`        | `Iterable<MenuKey>`                | -        | Keys of items that should be disabled              |
+| `shouldCloseOnSelect` | `boolean`                          | -        | Whether selecting an item should close the menu    |
+| `className`           | `string`                           | -        | Additional CSS class for the group container       |
+| `onSelectionChange`   | `(keys: Set<MenuKey>) => void`     | -        | Callback fired when the selection changes          |
+| `...ViewProps`        | `ViewProps`                        | -        | All standard React Native View props are supported |
+
+### Menu.Label
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | The label text content                             |
+| `className`    | `string`          | -       | Additional CSS class for the label                 |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Menu.Item
+
+| prop                    | type                                                             | default     | description                                                  |
+| ----------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: MenuItemRenderProps) => ReactNode)` | -           | Child elements or a render function                          |
+| `id`                    | `MenuKey`                                                        | -           | Unique identifier, required when inside a Menu.Group         |
+| `variant`               | `'default' \| 'danger'`                                          | `'default'` | Visual variant of the menu item                              |
+| `isDisabled`            | `boolean`                                                        | `false`     | Whether the item is disabled                                 |
+| `isSelected`            | `boolean`                                                        | -           | Controlled selected state for standalone items               |
+| `shouldCloseOnSelect`   | `boolean`                                                        | `true`      | Whether pressing this item should close the menu             |
+| `className`             | `string`                                                         | -           | Additional CSS class for the item                            |
+| `animation`             | `MenuItemAnimation`                                              | -           | Animation configuration for press feedback                   |
+| `isAnimatedStyleActive` | `boolean`                                                        | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `onSelectedChange`      | `(selected: boolean) => void`                                    | -           | Callback when standalone item's selected state changes       |
+| `...PressableProps`     | `PressableProps`                                                 | -           | All standard React Native Pressable props are supported      |
+
+#### MenuItemRenderProps
+
+Props passed to the render function when `children` is a function.
+
+| prop         | type                    | description                             |
+| ------------ | ----------------------- | --------------------------------------- |
+| `isSelected` | `boolean`               | Whether this item is currently selected |
+| `isDisabled` | `boolean`               | Whether the item is disabled            |
+| `isPressed`  | `SharedValue<boolean>`  | Whether the item is currently pressed   |
+| `variant`    | `'default' \| 'danger'` | Visual variant of the item              |
+
+#### MenuItemAnimation
+
+Animation configuration for menu item press feedback. Can be:
+
+- `false` or `"disabled"`: Disable all item animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                           | type               | default                    | description                              |
+| ------------------------------ | ------------------ | -------------------------- | ---------------------------------------- |
+| `scale.value`                  | `number`           | `0.98`                     | Scale value when pressed                 |
+| `scale.timingConfig`           | `WithTimingConfig` | `{ duration: 150 }`        | Spring animation configuration for scale |
+| `backgroundColor.value`        | `string`           | `useThemeColor('default')` | Background color shown while pressed     |
+| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 150 }`        | Animation timing for background color    |
+
+### Menu.ItemTitle
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | The title text content                             |
+| `className`    | `string`          | -       | Additional CSS class for the item title            |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Menu.ItemDescription
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | The description text content                       |
+| `className`    | `string`          | -       | Additional CSS class for the item description      |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Menu.ItemIndicator
+
+| prop           | type                         | default       | description                                            |
+| -------------- | ---------------------------- | ------------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode`            | -             | Custom indicator content, defaults to checkmark or dot |
+| `variant`      | `'checkmark' \| 'dot'`       | `'checkmark'` | Visual variant of the indicator                        |
+| `iconProps`    | `MenuItemIndicatorIconProps` | -             | Icon configuration (checkmark variant)                 |
+| `forceMount`   | `boolean`                    | `true`        | Force mount the indicator regardless of selected state |
+| `className`    | `string`                     | -             | Additional CSS class for the item indicator            |
+| `...ViewProps` | `ViewProps`                  | -             | All standard React Native View props are supported     |
+
+#### MenuItemIndicatorIconProps
+
+| prop    | type     | default | description                                    |
+| ------- | -------- | ------- | ---------------------------------------------- |
+| `size`  | `number` | `16`    | Size of the indicator icon (8 for dot variant) |
+| `color` | `string` | `muted` | Color of the indicator icon                    |
+
+### SubMenu
+
+| prop            | type                      | default | description                                              |
+| --------------- | ------------------------- | ------- | -------------------------------------------------------- |
+| `children`      | `React.ReactNode`         | -       | The sub-menu content (trigger, content, and other items) |
+| `isOpen`        | `boolean`                 | -       | Controlled open state of the sub-menu                    |
+| `isDefaultOpen` | `boolean`                 | -       | Open state when initially rendered (uncontrolled)        |
+| `isDisabled`    | `boolean`                 | `false` | Whether the sub-menu is disabled                         |
+| `className`     | `string`                  | -       | Additional CSS class for the root container              |
+| `animation`     | `SubMenuRootAnimation`    | -       | Animation configuration for the sub-menu                 |
+| `onOpenChange`  | `(open: boolean) => void` | -       | Callback fired when the sub-menu open state changes      |
+| `...ViewProps`  | `ViewProps`               | -       | All standard React Native View props are supported       |
+
+##### SubMenuRootAnimation
+
+Animation configuration for the SubMenu root component. Can be:
+
+- `"disable-all"`: Disable all animations including children
+- `false` or `"disabled"`: Disable only root animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                            | type                    | default                                     | description                                     |
+| ------------------------------- | ----------------------- | ------------------------------------------- | ----------------------------------------------- |
+| `state`                         | `'disabled' \| boolean` | -                                           | Disable animations while customizing properties |
+| `rootContent.marginHorizontal`  | `number`                | `-16`                                       | Margin horizontal when sub-menu is open         |
+| `rootContent.marginVertical`    | `number`                | `-16`                                       | Margin vertical when sub-menu is open           |
+| `rootContent.paddingHorizontal` | `number`                | `6`                                         | Padding horizontal when sub-menu is open        |
+| `rootContent.paddingTop`        | `number`                | `12`                                        | Padding top when sub-menu is open               |
+| `rootContent.springConfig`      | `WithSpringConfig`      | `{ damping: 100, stiffness: 950, mass: 3 }` | Spring configuration for expand/collapse        |
+
+#### SubMenu.Trigger
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | The trigger content (title, icons, indicator, etc.)     |
+| `textValue`         | `string`          | -       | Accessible text value announced by screen readers       |
+| `className`         | `string`          | -       | Additional CSS class for the trigger                    |
+| `isDisabled`        | `boolean`         | `false` | Whether the trigger is disabled                         |
+| `asChild`           | `boolean`         | -       | Render as child element using Slot pattern              |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+#### SubMenu.TriggerIndicator
+
+Animated indicator icon that rotates when the submenu opens/closes. Defaults to a chevron-right icon.
+
+| prop                    | type                               | default | description                                                  |
+| ----------------------- | ---------------------------------- | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                  | -       | Custom indicator content (replaces default chevron)          |
+| `className`             | `string`                           | -       | Additional CSS class for the indicator                       |
+| `iconProps`             | `SubMenuTriggerIndicatorIconProps` | -       | Icon configuration for the default chevron                   |
+| `animation`             | `SubMenuTriggerIndicatorAnimation` | -       | Animation configuration for indicator rotation               |
+| `isAnimatedStyleActive` | `boolean`                          | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `ViewProps`                        | -       | All standard React Native View props are supported           |
+
+##### SubMenuTriggerIndicatorIconProps
+
+| prop    | type     | default | description                 |
+| ------- | -------- | ------- | --------------------------- |
+| `size`  | `number` | `14`    | Size of the indicator icon  |
+| `color` | `string` | `muted` | Color of the indicator icon |
+
+##### SubMenuTriggerIndicatorAnimation
+
+Animation configuration for the trigger indicator rotation. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                    | type                    | default                                      | description                                      |
+| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
+| `state`                 | `'disabled' \| boolean` | -                                            | Disable animations while customizing properties  |
+| `rotation.value`        | `[number, number]`      | `[0, 90]`                                    | Rotation values [collapsed, expanded] in degrees |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring configuration for rotation                |
+
+#### SubMenu.Content
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | The submenu items (Menu.Item, Menu.Group, etc.)         |
+| `className`         | `string`          | -       | Additional CSS class for the content container          |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+## Hooks
+
+### useMenu
+
+Hook to access the menu root context. Must be used within a `Menu` component.
+
+```tsx
+import { useMenu } from 'heroui-native';
+
+const { isOpen, onOpenChange, presentation, isDisabled } = useMenu();
+```
+
+#### Returns
+
+| property       | type                          | description                             |
+| -------------- | ----------------------------- | --------------------------------------- |
+| `isOpen`       | `boolean`                     | Whether the menu is currently open      |
+| `onOpenChange` | `(open: boolean) => void`     | Callback to change the open state       |
+| `presentation` | `'popover' \| 'bottom-sheet'` | Current presentation mode               |
+| `isDisabled`   | `boolean \| undefined`        | Whether the menu is disabled            |
+| `nativeID`     | `string`                      | Unique identifier for the menu instance |
+
+### useMenuItem
+
+Hook to access the menu item context. Must be used within a `Menu.Item` component.
+
+```tsx
+import { useMenuItem } from 'heroui-native';
+
+const { id, isSelected, isDisabled, variant } = useMenuItem();
+```
+
+#### Returns
+
+| property     | type                    | description                            |
+| ------------ | ----------------------- | -------------------------------------- |
+| `id`         | `MenuKey \| undefined`  | Item identifier                        |
+| `isSelected` | `boolean`               | Whether the item is currently selected |
+| `isDisabled` | `boolean`               | Whether the item is disabled           |
+| `variant`    | `'default' \| 'danger'` | Visual variant of the item             |
+
+### useMenuAnimation
+
+Hook to access the menu animation context. Must be used within a `Menu` component.
+
+```tsx
+import { useMenuAnimation } from 'heroui-native';
+
+const { progress, isDragging } = useMenuAnimation();
+```
+
+#### Returns
+
+| property     | type                   | description                                               |
+| ------------ | ---------------------- | --------------------------------------------------------- |
+| `progress`   | `SharedValue<number>`  | Animation progress shared value (0=idle, 1=open, 2=close) |
+| `isDragging` | `SharedValue<boolean>` | Whether the bottom sheet is currently being dragged       |
+
+### useSubMenu
+
+Hook to access the sub-menu context. Must be used within a `SubMenu` component.
+
+```tsx
+import { useSubMenu } from 'heroui-native';
+
+const { isOpen, onOpenChange, isDisabled } = useSubMenu();
+```
+
+#### Returns
+
+| property       | type                      | description                                 |
+| -------------- | ------------------------- | ------------------------------------------- |
+| `isOpen`       | `boolean`                 | Whether the sub-menu is currently open      |
+| `onOpenChange` | `(open: boolean) => void` | Callback to change the open state           |
+| `isDisabled`   | `boolean`                 | Whether the sub-menu is disabled            |
+| `nativeID`     | `string`                  | Unique identifier for the sub-menu instance |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Menu uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Menu.Portal`. Tradeoff: the menu will not appear above native modals when disabled.
+
+### Native Modal (iOS)
+
+When a `Menu` is opened inside a screen presented as a native modal (`presentation: 'modal' | 'formSheet' | 'pageSheet'`), the menu content may render shifted upward. In the new architecture (Fabric), `react-native-screens` marks `RNSModalScreen` as a Fabric root, so the trigger's position is reported relative to the modal's origin while `FullWindowOverlay` (where the menu is mounted) is anchored to the iOS application window. Compensate by adding `safeAreaInsets.top` to `offset`:
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Menu.Content presentation="popover" offset={insets.top}>
+  ...
+</Menu.Content>;
+```
diff --git a/apps/docs/content/docs/en/native/components/(collections)/tag-group.mdx b/apps/docs/content/docs/en/native/components/(collections)/tag-group.mdx
new file mode 100644
index 0000000..a28c035
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(collections)/tag-group.mdx
@@ -0,0 +1,414 @@
+---
+title: TagGroup
+description: A compound component for displaying and managing selectable tags with optional removal.
+links:
+  source_native: tag-group/tag-group.tsx
+  styles_native: tag-group/tag-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { TagGroup } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<TagGroup>
+  <TagGroup.List>
+    <TagGroup.Item id="tag-1">
+      <TagGroup.ItemLabel>...</TagGroup.ItemLabel>
+      <TagGroup.ItemRemoveButton />
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+- **TagGroup**: Main container that manages tag selection state, disabled keys, and remove functionality. Provides size and variant context to all child components.
+- **TagGroup.List**: Container for rendering the list of tags with optional empty state rendering.
+- **TagGroup.Item**: Individual tag within the group. Supports string children (auto-wrapped in TagGroup.ItemLabel), render function children, or custom layouts.
+- **TagGroup.ItemLabel**: Text label for the tag. Automatically rendered when string children are provided, or can be used explicitly.
+- **TagGroup.ItemRemoveButton**: Remove button for the tag. Must be placed explicitly when removal is needed. Only functional when `onRemove` is provided to TagGroup.
+
+## Usage
+
+### Basic Usage
+
+Display a simple tag group with selectable items.
+
+```tsx
+<TagGroup selectionMode="single">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+    <TagGroup.Item id="gaming">Gaming</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Single Selection Mode
+
+Allow only one tag to be selected at a time.
+
+```tsx
+<TagGroup selectionMode="single" defaultSelectedKeys={['news']}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+    <TagGroup.Item id="gaming">Gaming</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Multiple Selection Mode
+
+Allow multiple tags to be selected simultaneously.
+
+```tsx
+<TagGroup selectionMode="multiple" defaultSelectedKeys={['news', 'travel']}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+    <TagGroup.Item id="gaming">Gaming</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Controlled Selection
+
+Control selection state with `selectedKeys` and `onSelectionChange`.
+
+```tsx
+const [selected, setSelected] = useState(new Set(['news']));
+
+<TagGroup
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+    <TagGroup.Item id="gaming">Gaming</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>;
+```
+
+### Variants
+
+Apply different visual variants to the tags.
+
+```tsx
+<TagGroup selectionMode="single" variant="default">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" variant="surface">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Sizes
+
+Control the size of all tags in the group.
+
+```tsx
+<TagGroup selectionMode="single" size="sm">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" size="md">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+
+<TagGroup selectionMode="single" size="lg">
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### With Remove Button
+
+Add remove buttons to tags by providing `onRemove` and placing `TagGroup.ItemRemoveButton` in each item.
+
+```tsx
+const [tags, setTags] = useState([
+  { id: 'news', name: 'News' },
+  { id: 'travel', name: 'Travel' },
+]);
+
+const onRemove = (keys) => {
+  setTags((prev) => prev.filter((tag) => !keys.has(tag.id)));
+};
+
+<TagGroup selectionMode="single" onRemove={onRemove}>
+  <TagGroup.List>
+    {tags.map((tag) => (
+      <TagGroup.Item key={tag.id} id={tag.id}>
+        <TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
+        <TagGroup.ItemRemoveButton />
+      </TagGroup.Item>
+    ))}
+  </TagGroup.List>
+</TagGroup>;
+```
+
+### Render Function Children
+
+Use a render function to access `isSelected` and `isDisabled` for custom layouts.
+
+```tsx
+<TagGroup selectionMode="single">
+  <TagGroup.List>
+    <TagGroup.Item id="news">
+      {({ isSelected }) => (
+        <>
+          <SquareArticleIcon
+            size={16}
+            colorClassName={
+              isSelected
+                ? 'accent-accent-soft-foreground'
+                : 'accent-field-foreground'
+            }
+          />
+          <TagGroup.ItemLabel>News</TagGroup.ItemLabel>
+        </>
+      )}
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Empty State
+
+Render custom content when the list has no tags.
+
+```tsx
+<TagGroup onRemove={onRemove}>
+  <TagGroup.List
+    renderEmptyState={() => (
+      <Text className="text-sm text-muted">No categories found</Text>
+    )}
+  >
+    {tags.map((tag) => (
+      <TagGroup.Item key={tag.id} id={tag.id}>
+        <TagGroup.ItemLabel>{tag.name}</TagGroup.ItemLabel>
+        <TagGroup.ItemRemoveButton />
+      </TagGroup.Item>
+    ))}
+  </TagGroup.List>
+</TagGroup>
+```
+
+### Disabled Tags
+
+Disable individual tags or the entire group.
+
+```tsx
+<TagGroup selectionMode="single" disabledKeys={new Set(['travel'])}>
+  <TagGroup.List>
+    <TagGroup.Item id="news">News</TagGroup.Item>
+    <TagGroup.Item id="travel">Travel</TagGroup.Item>
+    <TagGroup.Item id="gaming" isDisabled>
+      Gaming
+    </TagGroup.Item>
+  </TagGroup.List>
+</TagGroup>
+```
+
+## Example
+
+```tsx
+import { TagGroup, Label, Description, FieldError } from 'heroui-native';
+import { useState, useMemo } from 'react';
+import { View } from 'react-native';
+
+export default function TagGroupExample() {
+  const [selected, setSelected] = useState(new Set());
+  const isInvalid = useMemo(
+    () => Array.from(selected).length === 0,
+    [selected]
+  );
+
+  return (
+    <View className="gap-4">
+      <TagGroup
+        selectedKeys={selected}
+        selectionMode="multiple"
+        onSelectionChange={setSelected}
+        isInvalid={isInvalid}
+      >
+        <Label isInvalid={false}>Amenities</Label>
+        <TagGroup.List>
+          <TagGroup.Item id="laundry">Laundry</TagGroup.Item>
+          <TagGroup.Item id="fitness">Fitness center</TagGroup.Item>
+          <TagGroup.Item id="parking">Parking</TagGroup.Item>
+          <TagGroup.Item id="pool">Swimming pool</TagGroup.Item>
+          <TagGroup.Item id="breakfast">Breakfast</TagGroup.Item>
+        </TagGroup.List>
+        <Description hideOnInvalid>
+          {`Selected: ${Array.from(selected).join(', ')}`}
+        </Description>
+        <FieldError>Please select at least one category</FieldError>
+      </TagGroup>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tag-group.tsx>).
+
+## API Reference
+
+### TagGroup
+
+| prop                  | type                               | default     | description                                                      |
+| --------------------- | ---------------------------------- | ----------- | ---------------------------------------------------------------- |
+| `children`            | `React.ReactNode`                  | -           | Child elements to render inside the tag group                    |
+| `size`                | `'sm' \| 'md' \| 'lg'`             | `'md'`      | Size of all tags in the group                                    |
+| `variant`             | `'default' \| 'surface'`           | `'default'` | Visual variant of all tags in the group                          |
+| `selectionMode`       | `'none' \| 'single' \| 'multiple'` | `'none'`    | The type of selection allowed in the tag group                   |
+| `selectedKeys`        | `Iterable<TagKey>`                 | -           | The currently selected keys (controlled)                         |
+| `defaultSelectedKeys` | `Iterable<TagKey>`                 | -           | The initial selected keys (uncontrolled)                         |
+| `disabledKeys`        | `Iterable<TagKey>`                 | -           | Keys of tags that should be disabled                             |
+| `isDisabled`          | `boolean`                          | `false`     | Whether the entire tag group is disabled                         |
+| `isInvalid`           | `boolean`                          | `false`     | Whether the tag group is in an invalid state                     |
+| `isRequired`          | `boolean`                          | `false`     | Whether the tag group is required                                |
+| `className`           | `string`                           | -           | Additional CSS classes for the tag group container               |
+| `style`               | `StyleProp<ViewStyle>`             | -           | Additional styles for the tag group container                    |
+| `animation`           | `"disable-all" \| undefined`       | -           | Use `"disable-all"` to disable all animations including children |
+| `onSelectionChange`   | `(keys: Set<TagKey>) => void`      | -           | Handler called when the selection changes                        |
+| `onRemove`            | `(keys: Set<TagKey>) => void`      | -           | Handler called when tags are removed                             |
+| `...ViewProps`        | `ViewProps`                        | -           | All standard React Native View props are supported               |
+
+#### TagKey
+
+`string | number` — Key type for identifying tags within a TagGroup.
+
+#### Animation
+
+Use `animation="disable-all"` to disable all animations including children. Omit or use `undefined` for default animations.
+
+### TagGroup.List
+
+| prop               | type                    | default | description                                        |
+| ------------------ | ----------------------- | ------- | -------------------------------------------------- |
+| `children`         | `React.ReactNode`       | -       | Child elements to render inside the list           |
+| `className`        | `string`                | -       | Additional CSS classes for the list container      |
+| `style`            | `StyleProp<ViewStyle>`  | -       | Additional styles for the list container           |
+| `renderEmptyState` | `() => React.ReactNode` | -       | Function to render when the list has no tags       |
+| `...ViewProps`     | `ViewProps`             | -       | All standard React Native View props are supported |
+
+### TagGroup.Item
+
+| prop                | type                                                                    | default | description                                                                  |
+| ------------------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((renderProps: TagRenderProps) => React.ReactNode)` | -       | Tag content: string, elements, or a render function receiving TagRenderProps |
+| `id`                | `TagKey`                                                                | -       | Unique identifier for this tag                                               |
+| `isDisabled`        | `boolean`                                                               | -       | Whether this specific tag is disabled                                        |
+| `className`         | `string`                                                                | -       | Additional CSS classes for the tag                                           |
+| `style`             | `StyleProp<ViewStyle>`                                                  | -       | Additional styles for the tag                                                |
+| `...PressableProps` | `PressableProps`                                                        | -       | All standard React Native Pressable props are supported                      |
+
+#### TagRenderProps
+
+| prop         | type      | description                                                                 |
+| ------------ | --------- | --------------------------------------------------------------------------- |
+| `isSelected` | `boolean` | Whether the tag is currently selected                                       |
+| `isDisabled` | `boolean` | Whether the tag is disabled (merged from root, disabledKeys, and item prop) |
+
+### TagGroup.ItemLabel
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Text content to render                             |
+| `className`    | `string`          | -       | Additional CSS classes for the label               |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### TagGroup.ItemRemoveButton
+
+| prop                | type                       | default | description                                                                              |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`          | -       | Custom icon or content for the remove button. Defaults to close icon when omitted        |
+| `className`         | `string`                   | -       | Additional CSS classes for the remove button                                             |
+| `iconProps`         | `TagRemoveButtonIconProps` | -       | Props for customizing the default close icon. Only applies when no children are provided |
+| `hitSlop`           | `number`                   | `8`     | Extends the touchable area                                                               |
+| `...PressableProps` | `PressableProps`           | -       | All standard React Native Pressable props are supported                                  |
+
+#### TagRemoveButtonIconProps
+
+| prop    | type     | default | description       |
+| ------- | -------- | ------- | ----------------- |
+| `size`  | `number` | `12`    | Size of the icon  |
+| `color` | `string` | -       | Color of the icon |
+
+## Hooks
+
+### useTagGroup
+
+Hook to access the tag group root context. Must be used within a `TagGroup` component.
+
+```tsx
+import { useTagGroup } from 'heroui-native';
+
+const {
+  selectedKeys,
+  disabledKeys,
+  selectionMode,
+  onSelectionChange,
+  onRemove,
+  isDisabled,
+  isInvalid,
+  isRequired,
+} = useTagGroup();
+```
+
+#### Returns
+
+| property            | type                                         | description                                    |
+| ------------------- | -------------------------------------------- | ---------------------------------------------- |
+| `selectionMode`     | `'none' \| 'single' \| 'multiple'`           | The type of selection allowed in the tag group |
+| `selectedKeys`      | `Set<TagKey>`                                | Currently selected tag keys                    |
+| `disabledKeys`      | `Set<TagKey>`                                | Keys of disabled tags                          |
+| `onSelectionChange` | `(keys: Set<TagKey>) => void`                | Callback when selection changes                |
+| `onRemove`          | `((keys: Set<TagKey>) => void) \| undefined` | Callback when tags are removed                 |
+| `isDisabled`        | `boolean`                                    | Whether the entire tag group is disabled       |
+| `isInvalid`         | `boolean`                                    | Whether the tag group is in an invalid state   |
+| `isRequired`        | `boolean`                                    | Whether the tag group is required              |
+
+### useTagGroupItem
+
+Hook to access the tag item context. Must be used within a `TagGroup.Item` component.
+
+```tsx
+import { useTagGroupItem } from 'heroui-native';
+
+const { id, isSelected, isDisabled, allowsRemoving } = useTagGroupItem();
+```
+
+#### Returns
+
+| property         | type      | description                                                                 |
+| ---------------- | --------- | --------------------------------------------------------------------------- |
+| `id`             | `TagKey`  | Unique identifier for this tag                                              |
+| `isSelected`     | `boolean` | Whether the tag is currently selected                                       |
+| `isDisabled`     | `boolean` | Whether the tag is disabled                                                 |
+| `allowsRemoving` | `boolean` | Whether the tag can be removed (true when onRemove is provided to TagGroup) |
diff --git a/apps/docs/content/docs/en/native/components/(controls)/slider.mdx b/apps/docs/content/docs/en/native/components/(controls)/slider.mdx
new file mode 100644
index 0000000..40e7386
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(controls)/slider.mdx
@@ -0,0 +1,358 @@
+---
+title: Slider
+description: A draggable input for selecting a value or range within a bounded interval.
+links:
+  source_native: slider/slider.tsx
+  styles_native: slider/slider.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Slider } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Slider>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+- **Slider**: Main container that manages slider value state, orientation, and provides context to all sub-components. Supports single value and range modes.
+- **Slider.Output**: Optional display of the current value(s). Supports render functions for custom formatting. Shows a formatted value label by default.
+- **Slider.Track**: Sizing container for Fill and Thumb elements. Reports its layout size for position calculations. Supports tap-to-position and render-function children for dynamic content (e.g. multiple thumbs for range sliders).
+- **Slider.Fill**: Responsive fill bar that stretches the full cross-axis of the Track. Only the main-axis position and size are computed.
+- **Slider.Thumb**: Draggable thumb element using react-native-gesture-handler. Centered on the cross-axis by the Track layout. Animates scale on press via react-native-reanimated. Each thumb gets `role="slider"` with full `accessibilityValue`.
+
+## Usage
+
+### Basic Usage
+
+The Slider component uses compound parts to create a draggable value input.
+
+```tsx
+<Slider defaultValue={30}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### With Label and Output
+
+Display a label alongside the current value output.
+
+```tsx
+<Slider defaultValue={50}>
+  <View className="flex-row items-center justify-between">
+    <Label>Volume</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### Vertical Orientation
+
+Render the slider vertically by setting `orientation` to `"vertical"`.
+
+```tsx
+<View className="h-48">
+  <Slider defaultValue={50} orientation="vertical">
+    <Slider.Track>
+      <Slider.Fill />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider>
+</View>
+```
+
+### Range Slider
+
+Pass an array as the value and use a render function on `Slider.Track` to create multiple thumbs.
+
+```tsx
+<Slider
+  defaultValue={[200, 800]}
+  minValue={0}
+  maxValue={1000}
+  step={10}
+  formatOptions={{ style: 'currency', currency: 'USD' }}
+>
+  <View className="flex-row items-center justify-between">
+    <Label>Price range</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    {({ state }) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+### Controlled Value
+
+Use `value` and `onChange` for controlled mode. The `onChangeEnd` callback fires when a drag or tap interaction completes.
+
+```tsx
+const [volume, setVolume] = useState(50);
+
+<Slider value={volume} onChange={setVolume} onChangeEnd={(v) => save(v)}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>;
+```
+
+### Custom Styling
+
+Apply custom styles using `className`, `classNames`, or `styles` on the thumb and other sub-components.
+
+```tsx
+<Slider defaultValue={65}>
+  <Slider.Track className="h-3 rounded-full bg-success/10">
+    <Slider.Fill className="rounded-full bg-success" />
+    <Slider.Thumb
+      classNames={{
+        thumbContainer: 'size-6 rounded-full bg-success',
+        thumbKnob: 'bg-success-foreground rounded-full',
+      }}
+      animation={{
+        scale: { value: [1, 0.7] },
+      }}
+    />
+  </Slider.Track>
+</Slider>
+```
+
+### Disabled
+
+Disable the entire slider to prevent interaction.
+
+```tsx
+<Slider defaultValue={40} isDisabled>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+## Example
+
+```tsx
+import { Label, Slider } from 'heroui-native';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+
+export default function SliderExample() {
+  const [price, setPrice] = useState<number[]>([200, 800]);
+
+  return (
+    <View className="px-8 gap-8">
+      <Slider defaultValue={30}>
+        <View className="flex-row items-center justify-between">
+          <Label>Volume</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+
+      <Slider
+        value={price}
+        onChange={setPrice}
+        minValue={0}
+        maxValue={1000}
+        step={10}
+        formatOptions={{ style: 'currency', currency: 'USD' }}
+      >
+        <View className="flex-row items-center justify-between">
+          <Label>Price range</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          {({ state }) => (
+            <>
+              <Slider.Fill />
+              {state.values.map((_, i) => (
+                <Slider.Thumb key={i} index={i} />
+              ))}
+            </>
+          )}
+        </Slider.Track>
+      </Slider>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/slider.tsx>).
+
+## API Reference
+
+### Slider
+
+| prop            | type                                  | default        | description                                                     |
+| --------------- | ------------------------------------- | -------------- | --------------------------------------------------------------- |
+| `children`      | `React.ReactNode`                     | -              | Children elements to be rendered inside the slider              |
+| `value`         | `number \| number[]`                  | -              | Current slider value (controlled mode)                          |
+| `defaultValue`  | `number \| number[]`                  | `0`            | Default slider value (uncontrolled mode)                        |
+| `minValue`      | `number`                              | `0`            | Minimum value of the slider                                     |
+| `maxValue`      | `number`                              | `100`          | Maximum value of the slider                                     |
+| `step`          | `number`                              | `1`            | Step increment for the slider                                   |
+| `formatOptions` | `Intl.NumberFormatOptions`            | -              | Number format options for value label formatting                |
+| `orientation`   | `'horizontal' \| 'vertical'`          | `'horizontal'` | Orientation of the slider                                       |
+| `isDisabled`    | `boolean`                             | `false`        | Whether the slider is disabled                                  |
+| `className`     | `string`                              | -              | Additional CSS classes                                          |
+| `animation`     | `AnimationRootDisableAll`             | -              | Animation configuration for the slider                          |
+| `onChange`      | `(value: number \| number[]) => void` | -              | Callback fired when the slider value changes during interaction |
+| `onChangeEnd`   | `(value: number \| number[]) => void` | -              | Callback fired when an interaction completes (drag end or tap)  |
+| `...ViewProps`  | `ViewProps`                           | -              | All standard React Native View props are supported              |
+
+#### AnimationRootDisableAll
+
+Animation configuration for the slider root component. Can be:
+
+- `"disable-all"`: Disable all animations including children
+- `undefined`: Use default animations
+
+### Slider.Output
+
+| prop           | type                                                                 | default | description                                                                                 |
+| -------------- | -------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | Custom content or render function receiving slider state. Defaults to formatted value label |
+| `className`    | `string`                                                             | -       | Additional CSS classes                                                                      |
+| `...ViewProps` | `ViewProps`                                                          | -       | All standard React Native View props are supported                                          |
+
+#### SliderRenderProps
+
+| prop          | type                | description                    |
+| ------------- | ------------------- | ------------------------------ |
+| `state`       | `SliderState`       | Current slider state           |
+| `orientation` | `SliderOrientation` | Orientation of the slider      |
+| `isDisabled`  | `boolean`           | Whether the slider is disabled |
+
+#### SliderState
+
+| prop                 | type                        | description                                    |
+| -------------------- | --------------------------- | ---------------------------------------------- |
+| `values`             | `number[]`                  | Current slider value(s) by thumb index         |
+| `getThumbValueLabel` | `(index: number) => string` | Returns the formatted string label for a thumb |
+
+### Slider.Track
+
+| prop           | type                                                                 | default | description                                                                   |
+| -------------- | -------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | Content or render function receiving slider state for dynamic thumb rendering |
+| `className`    | `string`                                                             | -       | Additional CSS classes                                                        |
+| `hitSlop`      | `number`                                                             | `8`     | Extra touch area around the track                                             |
+| `...ViewProps` | `ViewProps`                                                          | -       | All standard React Native View props are supported                            |
+
+### Slider.Fill
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps` | -       | All standard React Native View props are supported |
+
+### Slider.Thumb
+
+| prop           | type                                     | default | description                                        |
+| -------------- | ---------------------------------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                        | -       | Custom thumb content. Defaults to an animated knob |
+| `index`        | `number`                                 | `0`     | Index of this thumb within the slider              |
+| `isDisabled`   | `boolean`                                | -       | Whether this individual thumb is disabled          |
+| `className`    | `string`                                 | -       | Additional CSS classes for the thumb container     |
+| `classNames`   | `ElementSlots<ThumbSlots>`               | -       | Additional CSS classes for thumb slots             |
+| `styles`       | `Partial<Record<ThumbSlots, ViewStyle>>` | -       | Inline styles for thumb slots                      |
+| `hitSlop`      | `number`                                 | `12`    | Extra touch area around the thumb                  |
+| `animation`    | `SliderThumbAnimation`                   | -       | Animation configuration for the thumb knob         |
+| `...ViewProps` | `ViewProps`                              | -       | All standard React Native View props are supported |
+
+#### ElementSlots\<ThumbSlots\>
+
+| prop             | type     | description                                     |
+| ---------------- | -------- | ----------------------------------------------- |
+| `thumbContainer` | `string` | Custom class name for the outer thumb container |
+| `thumbKnob`      | `string` | Custom class name for the inner thumb knob      |
+
+#### styles
+
+| prop             | type        | description                          |
+| ---------------- | ----------- | ------------------------------------ |
+| `thumbContainer` | `ViewStyle` | Styles for the outer thumb container |
+| `thumbKnob`      | `ViewStyle` | Styles for the inner thumb knob      |
+
+#### SliderThumbAnimation
+
+Animation configuration for the thumb knob scale effect. Can be:
+
+- `false` or `"disabled"`: Disable thumb animation
+- `undefined`: Use default animations
+- `object`: Custom scale animation configuration
+
+| prop                 | type               | default                                      | description                                     |
+| -------------------- | ------------------ | -------------------------------------------- | ----------------------------------------------- |
+| `scale.value`        | `[number, number]` | `[1, 0.9]`                                   | Scale values [idle, dragging]                   |
+| `scale.springConfig` | `WithSpringConfig` | `{ damping: 15, stiffness: 200, mass: 0.5 }` | Spring animation configuration for scale effect |
+
+## Hooks
+
+### useSlider
+
+Hook to access the slider context. Must be used within a `Slider` component.
+
+```tsx
+import { useSlider } from 'heroui-native';
+
+const { values, orientation, isDisabled, getThumbValueLabel } = useSlider();
+```
+
+#### Returns
+
+| property             | type                                         | description                                                    |
+| -------------------- | -------------------------------------------- | -------------------------------------------------------------- |
+| `values`             | `number[]`                                   | Current slider values (one per thumb)                          |
+| `minValue`           | `number`                                     | Minimum value of the slider                                    |
+| `maxValue`           | `number`                                     | Maximum value of the slider                                    |
+| `step`               | `number`                                     | Step increment                                                 |
+| `orientation`        | `'horizontal' \| 'vertical'`                 | Current orientation                                            |
+| `isDisabled`         | `boolean`                                    | Whether the slider is disabled                                 |
+| `formatOptions`      | `Intl.NumberFormatOptions \| undefined`      | Number format options for labels                               |
+| `getThumbPercent`    | `(index: number) => number`                  | Returns the percentage position (0–1) for a given thumb index  |
+| `getThumbValueLabel` | `(index: number) => string`                  | Returns the formatted label for a given thumb index            |
+| `getThumbMinValue`   | `(index: number) => number`                  | Returns the minimum allowed value for a thumb                  |
+| `getThumbMaxValue`   | `(index: number) => number`                  | Returns the maximum allowed value for a thumb                  |
+| `updateValue`        | `(index: number, newValue: number) => void`  | Updates a thumb value by index                                 |
+| `isThumbDragging`    | `(index: number) => boolean`                 | Returns whether a given thumb is currently being dragged       |
+| `setThumbDragging`   | `(index: number, dragging: boolean) => void` | Sets the dragging state of a thumb                             |
+| `trackSize`          | `number`                                     | Track layout width (horizontal) or height (vertical) in pixels |
+| `thumbSize`          | `number`                                     | Measured thumb size (main-axis dimension) in pixels            |
diff --git a/apps/docs/content/docs/en/native/components/(controls)/switch.mdx b/apps/docs/content/docs/en/native/components/(controls)/switch.mdx
new file mode 100644
index 0000000..dc29d89
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(controls)/switch.mdx
@@ -0,0 +1,344 @@
+---
+title: Switch
+description: A toggle control that allows users to switch between on and off states.
+links:
+  source_native: switch/switch.tsx
+  styles_native: switch/switch.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/switch-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Switch } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Switch>
+  <Switch.Thumb>...</Switch.Thumb>
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+- **Switch**: Main container that handles toggle state and user interaction. Renders default thumb if no children provided. Animates scale (on press) and background color based on selection state. Acts as a pressable area for toggling.
+- **Switch.Thumb**: Optional sliding thumb element that moves between positions. Uses spring animation for smooth transitions. Can contain custom content like icons or be customized with different styles and animations.
+- **Switch.StartContent**: Optional content displayed on the left side of the switch. Typically used for icons or text that appear when switch is off. Positioned absolutely within the switch container.
+- **Switch.EndContent**: Optional content displayed on the right side of the switch. Typically used for icons or text that appear when switch is on. Positioned absolutely within the switch container.
+
+## Usage
+
+### Basic Usage
+
+The Switch component renders with default thumb if no children provided.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### With Custom Thumb
+
+Replace the default thumb with custom content using the Thumb component.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb>...</Switch.Thumb>
+</Switch>
+```
+
+### With Start and End Content
+
+Add icons or text that appear on each side of the switch.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Switch.Thumb />
+  <Switch.StartContent>...</Switch.StartContent>
+  <Switch.EndContent>...</Switch.EndContent>
+</Switch>
+```
+
+### With Render Function
+
+Use render functions for dynamic content based on switch state.
+
+```tsx
+<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
+  {({ isSelected, isDisabled }) => (
+    <>
+      <Switch.Thumb>
+        {({ isSelected }) => (isSelected ? <CheckIcon /> : <XIcon />)}
+      </Switch.Thumb>
+    </>
+  )}
+</Switch>
+```
+
+### With Custom Animations
+
+Customize animations for the switch root and thumb components.
+
+```tsx
+<Switch
+  animation={{
+    scale: {
+      value: [1, 0.9],
+      timingConfig: { duration: 200 },
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'],
+    },
+  }}
+>
+  <Switch.Thumb
+    animation={{
+      left: {
+        value: 4,
+        springConfig: {
+          damping: 30,
+          stiffness: 300,
+          mass: 1,
+        },
+      },
+      backgroundColor: {
+        value: ['#dbeafe', '#854d0e'],
+      },
+    }}
+  />
+</Switch>
+```
+
+### Disable Animations
+
+Disable animations entirely or only for specific components.
+
+```tsx
+{
+  /* Disable all animations including children */
+}
+<Switch animation="disable-all">
+  <Switch.Thumb />
+</Switch>;
+
+{
+  /* Disable only root animations, thumb can still animate */
+}
+<Switch>
+  <Switch.Thumb animation={false} />
+</Switch>;
+```
+
+## Example
+
+```tsx
+import { Switch } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { View } from 'react-native';
+import Animated, { ZoomIn } from 'react-native-reanimated';
+
+export default function SwitchExample() {
+  const [darkMode, setDarkMode] = React.useState(false);
+
+  return (
+    <View className="flex-row gap-4">
+      <Switch
+        isSelected={darkMode}
+        onSelectedChange={setDarkMode}
+        className="w-[56px] h-[32px]"
+        animation={{
+          backgroundColor: {
+            value: ['#172554', '#eab308'],
+          },
+        }}
+      >
+        <Switch.Thumb
+          className="size-[22px]"
+          animation={{
+            left: {
+              value: 4,
+              springConfig: {
+                damping: 30,
+                stiffness: 300,
+                mass: 1,
+              },
+            },
+          }}
+        />
+        <Switch.StartContent className="left-2">
+          {darkMode && (
+            <Animated.View key="sun" entering={ZoomIn.springify()}>
+              <Ionicons name="sunny" size={16} color="#854d0e" />
+            </Animated.View>
+          )}
+        </Switch.StartContent>
+        <Switch.EndContent className="right-2">
+          {!darkMode && (
+            <Animated.View key="moon" entering={ZoomIn.springify()}>
+              <Ionicons name="moon" size={16} color="#dbeafe" />
+            </Animated.View>
+          )}
+        </Switch.EndContent>
+      </Switch>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/switch.tsx).
+
+## API Reference
+
+### Switch
+
+| prop                        | type                                                                 | default     | description                                                  |
+| --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`                  | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the switch, or a render function    |
+| `isSelected`                | `boolean`                                                            | `undefined` | Whether the switch is currently selected                     |
+| `isDisabled`                | `boolean`                                                            | `false`     | Whether the switch is disabled and cannot be interacted with |
+| `className`                 | `string`                                                             | `undefined` | Custom class name for the switch                             |
+| `animation`                 | `SwitchRootAnimation`                                                | -           | Animation configuration                                      |
+| `isAnimatedStyleActive`     | `boolean`                                                            | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `onSelectedChange`          | `(isSelected: boolean) => void`                                      | -           | Callback fired when the switch selection state changes       |
+| `...AnimatedPressableProps` | `AnimatedProps<PressableProps>`                                      | -           | All React Native Reanimated Pressable props are supported    |
+
+#### SwitchRenderProps
+
+| prop         | type      | description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | Whether the switch is selected |
+| `isDisabled` | `boolean` | Whether the switch is disabled |
+
+#### SwitchRootAnimation
+
+Animation configuration for Switch component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                           | type                                     | default                                                        | description                                     |
+| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
+| `state`                        | `'disabled' \| 'disable-all' \| boolean` | -                                                              | Disable animations while customizing properties |
+| `scale.value`                  | `[number, number]`                       | `[1, 0.96]`                                                    | Scale values [unpressed, pressed]               |
+| `scale.timingConfig`           | `WithTimingConfig`                       | `{ duration: 150 }`                                            | Animation timing configuration                  |
+| `backgroundColor.value`        | `[string, string]`                       | Uses theme colors                                              | Background color values [unselected, selected]  |
+| `backgroundColor.timingConfig` | `WithTimingConfig`                       | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                  |
+
+### Switch.Thumb
+
+| prop                    | type                                                                 | default     | description                                                  |
+| ----------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the thumb, or a render function     |
+| `className`             | `string`                                                             | `undefined` | Custom class name for the thumb element                      |
+| `animation`             | `SwitchThumbAnimation`                                               | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                                            | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `ViewProps`                                                          | -           | All standard React Native View props are supported           |
+
+#### SwitchThumbAnimation
+
+Animation configuration for Switch.Thumb component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                           | type                    | default                                                        | description                                                             |
+| ------------------------------ | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `state`                        | `'disabled' \| boolean` | -                                                              | Disable animations while customizing properties                         |
+| `left.value`                   | `number`                | `2`                                                            | Offset value from the edges (left when unselected, right when selected) |
+| `left.springConfig`            | `WithSpringConfig`      | `{ damping: 120, stiffness: 1600, mass: 2 }`                   | Spring animation configuration for thumb position                       |
+| `backgroundColor.value`        | `[string, string]`      | `['white', theme accent-foreground color]`                     | Background color values [unselected, selected]                          |
+| `backgroundColor.timingConfig` | `WithTimingConfig`      | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                                          |
+
+### Switch.StartContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | Content to render inside the switch content        |
+| `className`    | `string`          | `undefined` | Custom class name for the content element          |
+| `...ViewProps` | `ViewProps`       | -           | All standard React Native View props are supported |
+
+### Switch.EndContent
+
+| prop           | type              | default     | description                                        |
+| -------------- | ----------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | `undefined` | Content to render inside the switch content        |
+| `className`    | `string`          | `undefined` | Custom class name for the content element          |
+| `...ViewProps` | `ViewProps`       | -           | All standard React Native View props are supported |
+
+## Hooks
+
+### useSwitch
+
+A hook that provides access to the Switch context. This is useful when building custom switch components or when you need to access switch state in child components.
+
+**Returns:**
+
+| Property     | Type      | Description                    |
+| ------------ | --------- | ------------------------------ |
+| `isSelected` | `boolean` | Whether the switch is selected |
+| `isDisabled` | `boolean` | Whether the switch is disabled |
+
+**Example:**
+
+```tsx
+import { useSwitch } from 'heroui-native';
+
+function CustomSwitchContent() {
+  const { isSelected, isDisabled } = useSwitch();
+
+  return (
+    <View>
+      <Text>Status: {isSelected ? 'On' : 'Off'}</Text>
+      {isDisabled && <Text>Disabled</Text>}
+    </View>
+  );
+}
+
+// Usage
+<Switch>
+  <CustomSwitchContent />
+  <Switch.Thumb />
+</Switch>;
+```
+
+## Special Notes
+
+### Border Styling
+
+If you need to apply a border to the switch root, use the `outline` style properties instead of `border`. This ensures the border doesn't affect the internal layout calculations for the thumb position:
+
+```tsx
+<Switch className="outline outline-accent">
+  <Switch.Thumb />
+</Switch>
+```
+
+Using `outline` keeps the border visual without impacting the switch's internal width calculations, ensuring the thumb animates correctly.
+
+### Integration with ControlField
+
+The Switch component integrates seamlessly with ControlField for press state sharing:
+
+```tsx
+import { Description, ControlField, Label } from 'heroui-native';
+
+<ControlField isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>Receive push notifications</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+When wrapped in ControlField, the Switch will automatically respond to press events on the entire ControlField container, creating a larger touch target and better user experience.
diff --git a/apps/docs/content/docs/en/native/components/(data-display)/chip.mdx b/apps/docs/content/docs/en/native/components/(data-display)/chip.mdx
new file mode 100644
index 0000000..d7d4aef
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(data-display)/chip.mdx
@@ -0,0 +1,200 @@
+---
+title: Chip
+description: Displays a compact element in a capsule shape.
+links:
+  source_native: chip/chip.tsx
+  styles_native: chip/chip.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/chip-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Chip } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Chip>
+  <Chip.Label>...</Chip.Label>
+</Chip>
+```
+
+- **Chip**: Main container that displays a compact element
+- **Chip.Label**: Text content of the chip
+
+## Usage
+
+### Basic Usage
+
+The Chip component displays text or custom content in a capsule shape.
+
+```tsx
+<Chip>Basic Chip</Chip>
+```
+
+### Sizes
+
+Control the chip size with the `size` prop.
+
+```tsx
+<Chip size="sm">Small</Chip>
+<Chip size="md">Medium</Chip>
+<Chip size="lg">Large</Chip>
+```
+
+### Variants
+
+Choose between different visual styles with the `variant` prop.
+
+```tsx
+<Chip variant="primary">Primary</Chip>
+<Chip variant="secondary">Secondary</Chip>
+<Chip variant="tertiary">Tertiary</Chip>
+<Chip variant="soft">Soft</Chip>
+```
+
+### Colors
+
+Apply different color themes with the `color` prop.
+
+```tsx
+<Chip color="accent">Accent</Chip>
+<Chip color="default">Default</Chip>
+<Chip color="success">Success</Chip>
+<Chip color="warning">Warning</Chip>
+<Chip color="danger">Danger</Chip>
+```
+
+### With Icons
+
+Add icons or custom content alongside text using compound components.
+
+```tsx
+<Chip>
+  <Icon name="star" size={12} />
+  <Chip.Label>Featured</Chip.Label>
+</Chip>
+
+<Chip>
+  <Chip.Label>Close</Chip.Label>
+  <Icon name="close" size={12} />
+</Chip>
+```
+
+### Custom Styling
+
+Apply custom styles using className or style props.
+
+```tsx
+<Chip className="bg-purple-600 px-6">
+  <Chip.Label className="text-white">Custom</Chip.Label>
+</Chip>
+```
+
+### Disable All Animations
+
+Disable all animations including children by using the `"disable-all"` value for the `animation` prop.
+
+```tsx
+{
+  /* Disable all animations including children */
+}
+<Chip animation="disable-all">No Animations</Chip>;
+```
+
+## Example
+
+```tsx
+import { Chip } from 'heroui-native';
+import { View, Text } from 'react-native';
+import { Ionicons } from '@expo/vector-icons';
+
+export default function ChipExample() {
+  return (
+    <View className="gap-4 p-4">
+      <View className="flex-row flex-wrap gap-2">
+        <Chip size="sm">Small</Chip>
+        <Chip size="md">Medium</Chip>
+        <Chip size="lg">Large</Chip>
+      </View>
+
+      <View className="flex-row flex-wrap gap-2">
+        <Chip variant="primary" color="accent">
+          Primary
+        </Chip>
+        <Chip variant="secondary" color="success">
+          <View className="size-1.5 rounded-full bg-success" />
+          <Chip.Label>Success</Chip.Label>
+        </Chip>
+        <Chip variant="tertiary" color="warning">
+          <Ionicons name="star" size={12} color="#F59E0B" />
+          <Chip.Label>Premium</Chip.Label>
+        </Chip>
+      </View>
+
+      <View className="flex-row gap-2">
+        <Chip variant="secondary">
+          <Chip.Label>Remove</Chip.Label>
+          <Ionicons name="close" size={14} color="#6B7280" />
+        </Chip>
+        <Chip className="bg-purple-600">
+          <Chip.Label className="text-white font-semibold">Custom</Chip.Label>
+        </Chip>
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/chip.tsx).
+
+## API Reference
+
+### Chip
+
+| prop                | type                                                          | default     | description                                                                               |
+| ------------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`                                             | -           | Content to render inside the chip                                                         |
+| `size`              | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Size of the chip                                                                          |
+| `variant`           | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | `'primary'` | Visual variant of the chip                                                                |
+| `color`             | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | Color theme of the chip                                                                   |
+| `className`         | `string`                                                      | -           | Additional CSS classes to apply                                                           |
+| `animation`         | `"disable-all" \| undefined`                                  | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `...PressableProps` | `PressableProps`                                              | -           | All Pressable props are supported                                                         |
+
+### Chip.Label
+
+| prop           | type              | default | description                            |
+| -------------- | ----------------- | ------- | -------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Text or content to render as the label |
+| `className`    | `string`          | -       | Additional CSS classes to apply        |
+| `...TextProps` | `TextProps`       | -       | All standard Text props are supported  |
+
+## Hooks
+
+### useChip
+
+Hook to access the Chip context values. Returns the chip's size, variant, and color.
+
+```tsx
+import { useChip } from 'heroui-native';
+
+const { size, variant, color } = useChip();
+```
+
+#### Return Value
+
+| property  | type                                                          | description                |
+| --------- | ------------------------------------------------------------- | -------------------------- |
+| `size`    | `'sm' \| 'md' \| 'lg'`                                        | Size of the chip           |
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | Visual variant of the chip |
+| `color`   | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | Color theme of the chip    |
+
+**Note:** This hook must be used within a `Chip` component. It will throw an error if called outside of the chip context.
diff --git a/apps/docs/content/docs/en/native/components/(feedback)/alert.mdx b/apps/docs/content/docs/en/native/components/(feedback)/alert.mdx
new file mode 100644
index 0000000..6d16188
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(feedback)/alert.mdx
@@ -0,0 +1,275 @@
+---
+title: Alert
+description: Displays important messages and notifications to users with status indicators.
+links:
+  source_native: alert/alert.tsx
+  styles_native: alert/alert.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Alert } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>...</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+- **Alert**: Main container with `role="alert"` and status-based styling. Provides status context to sub-components via a primitive context.
+- **Alert.Indicator**: Renders a status-appropriate icon by default. Accepts custom children to override the default icon. Supports `iconProps` for customising size and color.
+- **Alert.Content**: Wrapper for the title and description. Provides layout structure for text content.
+- **Alert.Title**: Heading text with status-based color. Connected to root via `aria-labelledby`.
+- **Alert.Description**: Body text rendered with muted color. Connected to root via `aria-describedby`.
+
+## Usage
+
+### Basic Usage
+
+The Alert component uses compound parts to display a notification with an icon, title, and description.
+
+```tsx
+<Alert>
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>New features available</Alert.Title>
+    <Alert.Description>
+      Check out our latest updates including dark mode support and improved
+      accessibility features.
+    </Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Status Variants
+
+Set the `status` prop to control the icon and title color. Available statuses are `default`, `accent`, `success`, `warning`, and `danger`.
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="warning">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Scheduled maintenance</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Alert status="danger">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Unable to connect</Alert.Title>
+    <Alert.Description>...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Title Only
+
+Omit `Alert.Description` for a compact single-line alert.
+
+```tsx
+<Alert status="success" className="items-center">
+  <Alert.Indicator className="pt-0" />
+  <Alert.Content>
+    <Alert.Title>Profile updated successfully</Alert.Title>
+  </Alert.Content>
+</Alert>
+```
+
+### With Action Buttons
+
+Place additional elements like buttons alongside the content.
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Update available</Alert.Title>
+    <Alert.Description>
+      A new version of the application is available.
+    </Alert.Description>
+  </Alert.Content>
+  <Button size="sm" variant="primary">
+    Refresh
+  </Button>
+</Alert>
+```
+
+### Custom Indicator
+
+Replace the default status icon by passing custom children to `Alert.Indicator`.
+
+```tsx
+<Alert status="accent">
+  <Alert.Indicator>
+    <Spinner>
+      <Spinner.Indicator iconProps={{ width: 20, height: 20 }} />
+    </Spinner>
+  </Alert.Indicator>
+  <Alert.Content>
+    <Alert.Title>Processing your request</Alert.Title>
+    <Alert.Description>Please wait while we sync your data.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+### Custom Styling
+
+Apply custom styles using the `className` prop on the root and compound parts.
+
+```tsx
+<Alert className="bg-accent/10 rounded-xl">
+  <Alert.Indicator className="pt-1" />
+  <Alert.Content className="gap-1">
+    <Alert.Title className="text-lg">...</Alert.Title>
+    <Alert.Description className="text-base">...</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+## Example
+
+```tsx
+import { Alert, Button, CloseButton } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function AlertExample() {
+  return (
+    <View className="w-full gap-4">
+      <Alert status="accent">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Update available</Alert.Title>
+          <Alert.Description>
+            A new version of the application is available. Please refresh to get
+            the latest features and bug fixes.
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="primary">
+          Refresh
+        </Button>
+      </Alert>
+
+      <Alert status="danger">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Unable to connect to server</Alert.Title>
+          <Alert.Description>
+            Unable to connect to the server. Check your internet connection and
+            try again.
+          </Alert.Description>
+        </Alert.Content>
+        <Button size="sm" variant="danger">
+          Retry
+        </Button>
+      </Alert>
+
+      <Alert status="success" className="items-center">
+        <Alert.Indicator className="pt-0" />
+        <Alert.Content>
+          <Alert.Title>Profile updated successfully</Alert.Title>
+        </Alert.Content>
+        <CloseButton />
+      </Alert>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/alert.tsx>).
+
+## API Reference
+
+### Alert
+
+| prop           | type                                                          | default     | description                                                       |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | Children elements to render inside the alert                      |
+| `status`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Status controlling the icon and color treatment                   |
+| `id`           | `string \| number`                                            | -           | Unique identifier for the alert. Auto-generated when not provided |
+| `className`    | `string`                                                      | -           | Additional CSS classes                                            |
+| `style`        | `ViewStyle`                                                   | -           | Additional styles applied to the root container                   |
+| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                |
+
+### Alert.Indicator
+
+| prop           | type              | default | description                                                        |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Custom children to render instead of the default status icon       |
+| `className`    | `string`          | -       | Additional CSS classes                                             |
+| `iconProps`    | `AlertIconProps`  | -       | Props passed to the default status icon (size and color overrides) |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported                 |
+
+#### AlertIconProps
+
+| prop    | type     | default      | description            |
+| ------- | -------- | ------------ | ---------------------- |
+| `size`  | `number` | `18`         | Icon size in pixels    |
+| `color` | `string` | status color | Icon color as a string |
+
+### Alert.Content
+
+| prop           | type              | default | description                                                     |
+| -------------- | ----------------- | ------- | --------------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements (typically Alert.Title and Alert.Description) |
+| `className`    | `string`          | -       | Additional CSS classes                                          |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported              |
+
+### Alert.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title text content                                 |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Alert.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description text content                           |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### useAlert
+
+Hook to access the alert root context. Must be used within an `Alert` component.
+
+```tsx
+import { useAlert } from 'heroui-native';
+
+const { status, nativeID } = useAlert();
+```
+
+#### Returns
+
+| property   | type                                                          | description                                                  |
+| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `status`   | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Current alert status for sub-component styling               |
+| `nativeID` | `string`                                                      | Unique identifier used for accessibility and ARIA attributes |
+
+
diff --git a/apps/docs/content/docs/en/native/components/(feedback)/skeleton-group.mdx b/apps/docs/content/docs/en/native/components/(feedback)/skeleton-group.mdx
new file mode 100644
index 0000000..9c0489c
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(feedback)/skeleton-group.mdx
@@ -0,0 +1,257 @@
+---
+title: SkeletonGroup
+description: Coordinates multiple skeleton loading placeholders with centralized animation control.
+links:
+  source_native: skeleton-group/skeleton-group.tsx
+  styles_native: skeleton-group/skeleton-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { SkeletonGroup } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<SkeletonGroup>
+  <SkeletonGroup.Item />
+</SkeletonGroup>
+```
+
+- **SkeletonGroup**: Root container that provides centralized control for all skeleton items
+- **SkeletonGroup.Item**: Individual skeleton item that inherits props from the parent group
+
+## Usage
+
+### Basic Usage
+
+The SkeletonGroup component manages multiple skeleton items with shared loading state and animation.
+
+```tsx
+<SkeletonGroup isLoading={isLoading}>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-1/2 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Container Layout
+
+Use className on the group to control layout of skeleton items.
+
+```tsx
+<SkeletonGroup isLoading={isLoading} className="flex-row items-center gap-3">
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### With isSkeletonOnly for Pure Skeleton Layouts
+
+Use `isSkeletonOnly` when the group contains only skeleton placeholders with layout wrappers (like View) that have no content to render in the loaded state. This prop hides the entire group when `isLoading` is false, preventing empty containers from affecting your layout.
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  isSkeletonOnly // Hides entire group when isLoading is false
+  className="flex-row items-center gap-3"
+>
+  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
+  {/* This View is only for layout, no content */}
+  <View className="flex-1 gap-1.5">
+    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
+  </View>
+</SkeletonGroup>
+```
+
+### With Animation Variants
+
+Control animation style for all items in the group.
+
+```tsx
+<SkeletonGroup isLoading={isLoading} variant="pulse">
+  <SkeletonGroup.Item className="h-10 w-10 rounded-full" />
+  <SkeletonGroup.Item className="h-4 w-32 rounded-md" />
+  <SkeletonGroup.Item className="h-3 w-24 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Custom Animation Configuration
+
+Configure shimmer or pulse animations for the entire group.
+
+```tsx
+<SkeletonGroup
+  isLoading={isLoading}
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  <SkeletonGroup.Item className="h-16 w-full rounded-lg" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+### With Enter/Exit Animations
+
+Apply Reanimated transitions when the group appears or disappears.
+
+```tsx
+<SkeletonGroup
+  entering={FadeInLeft}
+  exiting={FadeOutRight}
+  isLoading={isLoading}
+  className="w-full gap-2"
+>
+  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
+  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
+</SkeletonGroup>
+```
+
+## Example
+
+```tsx
+import { Card, SkeletonGroup, Avatar } from 'heroui-native';
+import { useState } from 'react';
+import { Text, View, Image } from 'react-native';
+
+export default function SkeletonGroupExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <SkeletonGroup isLoading={isLoading}>
+      <Card className="p-4">
+        <Card.Header>
+          <View className="flex-row items-center gap-3 mb-4">
+            <SkeletonGroup.Item className="h-10 w-10 rounded-full">
+              <Avatar size="sm" alt="Avatar">
+                <Avatar.Image
+                  source={{ uri: 'https://i.pravatar.cc/150?img=4' }}
+                />
+                <Avatar.Fallback />
+              </Avatar>
+            </SkeletonGroup.Item>
+
+            <View className="flex-1 gap-1">
+              <SkeletonGroup.Item className="h-3 w-32 rounded-md">
+                <Text className="font-semibold text-foreground">John Doe</Text>
+              </SkeletonGroup.Item>
+              <SkeletonGroup.Item className="h-3 w-24 rounded-md">
+                <Text className="text-sm text-muted">@johndoe</Text>
+              </SkeletonGroup.Item>
+            </View>
+          </View>
+
+          <View className="mb-4 gap-1.5">
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                This is the first line of the post content.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-full rounded-md">
+              <Text className="text-base text-foreground">
+                Second line with more interesting content to read.
+              </Text>
+            </SkeletonGroup.Item>
+            <SkeletonGroup.Item className="h-4 w-2/3 rounded-md">
+              <Text className="text-base text-foreground">
+                Last line is shorter.
+              </Text>
+            </SkeletonGroup.Item>
+          </View>
+        </Card.Header>
+
+        <SkeletonGroup.Item className="h-48 w-full rounded-lg">
+          <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+            <Image
+              source={{
+                uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+              }}
+              className="h-full w-full"
+            />
+          </View>
+        </SkeletonGroup.Item>
+      </Card>
+    </SkeletonGroup>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton-group.tsx).
+
+## API Reference
+
+### SkeletonGroup
+
+| prop                    | type                             | default     | description                                                            |
+| ----------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -           | SkeletonGroup.Item components and layout elements                      |
+| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton items are currently loading                       |
+| `isSkeletonOnly`        | `boolean`                        | `false`     | Hides entire group when isLoading is false (for skeleton-only layouts) |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant for all items in the group                           |
+| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                                                |
+| `className`             | `string`                         | -           | Additional CSS classes for the group container                         |
+| `style`                 | `StyleProp<ViewStyle>`           | -           | Custom styles for the group container                                  |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported                       |
+
+#### SkeletonRootAnimation
+
+Animation configuration for SkeletonGroup component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                     | type                                     | default                     | description                                     |
+| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                           | Disable animations while customizing properties |
+| `entering.value`         | `EntryOrExitLayoutType`                  | `FadeIn`                    | Custom entering animation                       |
+| `exiting.value`          | `EntryOrExitLayoutType`                  | `FadeOut`                   | Custom exiting animation                        |
+| `shimmer.duration`       | `number`                                 | `1500`                      | Animation duration in milliseconds              |
+| `shimmer.speed`          | `number`                                 | `1`                         | Speed multiplier for the animation              |
+| `shimmer.highlightColor` | `string`                                 | -                           | Highlight color for the shimmer effect          |
+| `shimmer.easing`         | `EasingFunction`                         | `Easing.linear`             | Easing function for the animation               |
+| `pulse.duration`         | `number`                                 | `1000`                      | Animation duration in milliseconds              |
+| `pulse.minOpacity`       | `number`                                 | `0.5`                       | Minimum opacity value                           |
+| `pulse.maxOpacity`       | `number`                                 | `1`                         | Maximum opacity value                           |
+| `pulse.easing`           | `EasingFunction`                         | `Easing.inOut(Easing.ease)` | Easing function for the animation               |
+
+### SkeletonGroup.Item
+
+| prop                    | type                             | default   | description                                                         |
+| ----------------------- | -------------------------------- | --------- | ------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -         | Content to show when not loading                                    |
+| `isLoading`             | `boolean`                        | inherited | Whether the skeleton is currently loading (overrides group setting) |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | inherited | Animation variant (overrides group setting)                         |
+| `animation`             | `SkeletonRootAnimation`          | inherited | Animation configuration (overrides group setting)                   |
+| `className`             | `string`                         | -         | Additional CSS classes for styling the item                         |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -         | All Reanimated Animated.View props are supported                    |
+
+## Special Notes
+
+### Props Inheritance
+
+SkeletonGroup.Item components inherit all animation-related props from their parent SkeletonGroup:
+
+- `isLoading`
+- `variant`
+- `animation`
+
+Individual items can override any inherited prop by providing their own value.
diff --git a/apps/docs/content/docs/en/native/components/(feedback)/skeleton.mdx b/apps/docs/content/docs/en/native/components/(feedback)/skeleton.mdx
new file mode 100644
index 0000000..a9d8f6a
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(feedback)/skeleton.mdx
@@ -0,0 +1,218 @@
+---
+title: Skeleton
+description: Displays a loading placeholder with shimmer or pulse animation effects.
+links:
+  source_native: skeleton/skeleton.tsx
+  styles_native: skeleton/skeleton.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/skeleton-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Skeleton } from 'heroui-native';
+```
+
+## Anatomy
+
+The Skeleton component is a simple wrapper that renders a placeholder for content that is loading. It does not have any child components.
+
+```tsx
+<Skeleton />
+```
+
+## Usage
+
+### Basic Usage
+
+The Skeleton component creates an animated placeholder while content is loading.
+
+```tsx
+<Skeleton className="h-20 w-full rounded-lg" />
+```
+
+### With Content
+
+Show skeleton while loading, then display content when ready.
+
+```tsx
+<Skeleton isLoading={isLoading} className="h-20 rounded-lg">
+  <View className="h-20 bg-primary rounded-lg">
+    <Text>Loaded Content</Text>
+  </View>
+</Skeleton>
+```
+
+### Animation Variants
+
+Control the animation style with the `variant` prop.
+
+```tsx
+<Skeleton variant="shimmer" className="h-20 w-full rounded-lg" />
+<Skeleton variant="pulse" className="h-20 w-full rounded-lg" />
+<Skeleton variant="none" className="h-20 w-full rounded-lg" />
+```
+
+### Custom Shimmer Configuration
+
+Customize the shimmer effect with duration, speed, and highlight color.
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="shimmer"
+  animation={{
+    shimmer: {
+      duration: 2000,
+      speed: 2,
+      highlightColor: 'rgba(59, 130, 246, 0.3)',
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### Custom Pulse Configuration
+
+Configure pulse animation with duration and opacity range.
+
+```tsx
+<Skeleton
+  className="h-16 w-full rounded-lg"
+  variant="pulse"
+  animation={{
+    pulse: {
+      duration: 500,
+      minOpacity: 0.1,
+      maxOpacity: 0.8,
+    },
+  }}
+>
+  ...
+</Skeleton>
+```
+
+### Shape Variations
+
+Create different skeleton shapes using className for styling.
+
+```tsx
+<Skeleton className="h-4 w-full rounded-md" />
+<Skeleton className="h-4 w-3/4 rounded-md" />
+<Skeleton className="h-4 w-1/2 rounded-md" />
+<Skeleton className="size-12 rounded-full" />
+```
+
+### Custom Enter/Exit Animations
+
+Apply custom Reanimated transitions when skeleton appears or disappears.
+
+```tsx
+<Skeleton
+  entering={FadeIn.duration(300)}
+  exiting={FadeOut.duration(300)}
+  isLoading={isLoading}
+  className="h-20 w-full rounded-lg"
+>
+  ...
+</Skeleton>
+```
+
+## Example
+
+```tsx
+import { Avatar, Card, Skeleton } from 'heroui-native';
+import { useState } from 'react';
+import { Image, Text, View } from 'react-native';
+
+export default function SkeletonExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <Card className="p-4">
+      <View className="flex-row items-center gap-3 mb-4">
+        <Skeleton isLoading={isLoading} className="h-10 w-10 rounded-full">
+          <Avatar size="sm" alt="Avatar">
+            <Avatar.Image source={{ uri: 'https://i.pravatar.cc/150?img=4' }} />
+            <Avatar.Fallback />
+          </Avatar>
+        </Skeleton>
+
+        <View className="flex-1 gap-1">
+          <Skeleton isLoading={isLoading} className="h-3 w-32 rounded-md">
+            <Text className="font-semibold text-foreground">John Doe</Text>
+          </Skeleton>
+          <Skeleton isLoading={isLoading} className="h-3 w-24 rounded-md">
+            <Text className="text-sm text-muted">@johndoe</Text>
+          </Skeleton>
+        </View>
+      </View>
+
+      <Skeleton
+        isLoading={isLoading}
+        className="h-48 w-full rounded-lg"
+        animation={{
+          shimmer: {
+            duration: 1500,
+            speed: 1,
+          },
+        }}
+      >
+        <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
+          <Image
+            source={{
+              uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
+            }}
+            className="h-full w-full"
+          />
+        </View>
+      </Skeleton>
+    </Card>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/skeleton.tsx).
+
+## API Reference
+
+### Skeleton
+
+| prop                    | type                             | default     | description                                                  |
+| ----------------------- | -------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                | -           | Content to show when not loading                             |
+| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton is currently loading                    |
+| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant                                            |
+| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                        | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `className`             | `string`                         | -           | Additional CSS classes for styling                           |
+| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported             |
+
+#### SkeletonRootAnimation
+
+Animation configuration for Skeleton component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                     | type                                     | default                     | description                                     |
+| ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
+| `state`                  | `'disabled' \| 'disable-all' \| boolean` | -                           | Disable animations while customizing properties |
+| `entering.value`         | `EntryOrExitLayoutType`                  | `FadeIn`                    | Custom entering animation                       |
+| `exiting.value`          | `EntryOrExitLayoutType`                  | `FadeOut`                   | Custom exiting animation                        |
+| `shimmer.duration`       | `number`                                 | `1500`                      | Animation duration in milliseconds              |
+| `shimmer.speed`          | `number`                                 | `1`                         | Speed multiplier for the animation              |
+| `shimmer.highlightColor` | `string`                                 | -                           | Highlight color for the shimmer effect          |
+| `shimmer.easing`         | `EasingFunction`                         | `Easing.linear`             | Easing function for the animation               |
+| `pulse.duration`         | `number`                                 | `1000`                      | Animation duration in milliseconds              |
+| `pulse.minOpacity`       | `number`                                 | `0.5`                       | Minimum opacity value                           |
+| `pulse.maxOpacity`       | `number`                                 | `1`                         | Maximum opacity value                           |
+| `pulse.easing`           | `EasingFunction`                         | `Easing.inOut(Easing.ease)` | Easing function for the animation               |
diff --git a/apps/docs/content/docs/en/native/components/(feedback)/spinner.mdx b/apps/docs/content/docs/en/native/components/(feedback)/spinner.mdx
new file mode 100644
index 0000000..82c4540
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(feedback)/spinner.mdx
@@ -0,0 +1,209 @@
+---
+title: Spinner
+description: Displays an animated loading indicator.
+links:
+  source_native: spinner/spinner.tsx
+  styles_native: spinner/spinner.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/spinner-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Spinner } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Spinner>
+  <Spinner.Indicator>...</Spinner.Indicator>
+</Spinner>
+```
+
+- **Spinner**: Main container that controls loading state, size, and color. Renders a default animated indicator if no children provided.
+- **Spinner.Indicator**: Optional sub-component for customizing animation configuration and icon appearance. Accepts custom children to replace the default icon.
+
+## Usage
+
+### Basic Usage
+
+The Spinner component displays a rotating loading indicator.
+
+```tsx
+<Spinner />
+```
+
+### Sizes
+
+Control the spinner size with the `size` prop.
+
+```tsx
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+```
+
+### Colors
+
+Use predefined color variants or custom colors.
+
+```tsx
+<Spinner color="default" />
+<Spinner color="success" />
+<Spinner color="warning" />
+<Spinner color="danger" />
+<Spinner color="#8B5CF6" />
+```
+
+### Loading State
+
+Control the visibility of the spinner with the `isLoading` prop.
+
+```tsx
+<Spinner isLoading={true} />
+<Spinner isLoading={false} />
+```
+
+### Animation Speed
+
+Customize the rotation speed using the `animation` prop on the Indicator component.
+
+```tsx
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator animation={{ rotation: { speed: 2 } }} />
+</Spinner>
+```
+
+### Custom Icon
+
+Replace the default spinner icon with custom content.
+
+```tsx
+const themeColorForeground = useThemeColor('foreground')
+
+<Spinner>
+  <Spinner.Indicator>
+    <Ionicons name="refresh" size={24} color={themeColorForeground} />
+  </Spinner.Indicator>
+</Spinner>
+
+<Spinner>
+  <Spinner.Indicator>
+    <Text>⏳</Text>
+  </Spinner.Indicator>
+</Spinner>
+```
+
+## Example
+
+```tsx
+import { Spinner } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import React from 'react';
+import { Text, TouchableOpacity, View } from 'react-native';
+
+export default function SpinnerExample() {
+  const [isLoading, setIsLoading] = React.useState(true);
+
+  return (
+    <View className="gap-4 p-4 bg-background">
+      <View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
+        <Spinner size="sm" color="default" />
+        <Text className="text-stone-500">Loading content...</Text>
+      </View>
+
+      <View className="items-center p-8 rounded-2xl bg-stone-200">
+        <Spinner size="lg" color="success" isLoading={isLoading} />
+        <Text className="text-stone-500 mt-4">Processing...</Text>
+        <TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
+          <Text className="text-primary mt-2 text-sm">
+            {isLoading ? 'Tap to stop' : 'Tap to start'}
+          </Text>
+        </TouchableOpacity>
+      </View>
+
+      <View className="flex-row gap-4 items-center justify-center">
+        <Spinner size="md" color="#EC4899">
+          <Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
+            <Ionicons name="refresh" size={24} color="#EC4899" />
+          </Spinner.Indicator>
+        </Spinner>
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/spinner.tsx).
+
+## API Reference
+
+### Spinner
+
+| prop           | type                                                        | default     | description                                        |
+| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                           | `undefined` | Content to render inside the spinner               |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | Size of the spinner                                |
+| `color`        | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | Color theme of the spinner                         |
+| `isLoading`    | `boolean`                                                   | `true`      | Whether the spinner is loading                     |
+| `className`    | `string`                                                    | `undefined` | Custom class name for the spinner                  |
+| `animation`    | `SpinnerRootAnimation`                                      | -           | Animation configuration                            |
+| `...ViewProps` | `ViewProps`                                                 | -           | All standard React Native View props are supported |
+
+#### SpinnerRootAnimation
+
+Animation configuration for Spinner component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                                     | default                                                              | description                                     |
+| ---------------- | ---------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean` | -                                                                    | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType`                  | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | Custom entering animation                       |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`                                       | Custom exiting animation                        |
+
+### Spinner.Indicator
+
+| prop                    | type                        | default     | description                                                  |
+| ----------------------- | --------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`           | `undefined` | Content to render inside the indicator                       |
+| `iconProps`             | `SpinnerIconProps`          | `undefined` | Props for the default icon                                   |
+| `className`             | `string`                    | `undefined` | Custom class name for the indicator element                  |
+| `animation`             | `SpinnerIndicatorAnimation` | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                   | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...Animated.ViewProps` | `Animated.ViewProps`        | -           | All Reanimated Animated.View props are supported             |
+
+#### SpinnerIndicatorAnimation
+
+Animation configuration for Spinner.Indicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop              | type                         | default         | description                                     |
+| ----------------- | ---------------------------- | --------------- | ----------------------------------------------- |
+| `state`           | `'disabled' \| boolean`      | -               | Disable animations while customizing properties |
+| `rotation.speed`  | `number`                     | `1.1`           | Rotation speed multiplier                       |
+| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | Animation easing configuration                  |
+
+### SpinnerIconProps
+
+| prop     | type               | default          | description        |
+| -------- | ------------------ | ---------------- | ------------------ |
+| `width`  | `number \| string` | `24`             | Width of the icon  |
+| `height` | `number \| string` | `24`             | Height of the icon |
+| `color`  | `string`           | `'currentColor'` | Color of the icon  |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/checkbox.mdx b/apps/docs/content/docs/en/native/components/(forms)/checkbox.mdx
new file mode 100644
index 0000000..6345c59
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/checkbox.mdx
@@ -0,0 +1,323 @@
+---
+title: Checkbox
+description: A selectable control that allows users to toggle between checked and unchecked states.
+links:
+  source_native: checkbox/checkbox.tsx
+  styles_native: checkbox/checkbox.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/checkbox-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Checkbox } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Checkbox>
+  <Checkbox.Indicator>...</Checkbox.Indicator>
+</Checkbox>
+```
+
+- **Checkbox**: Main container that handles selection state and user interaction. Renders default indicator with animated checkmark if no children provided. Automatically detects surface context for proper styling. Features press scale animation that can be customized or disabled. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`).
+- **Checkbox.Indicator**: Optional checkmark container with default slide, scale, opacity, and border radius animations when selected. Renders animated check icon with SVG path drawing animation if no children provided. All animations can be individually customized or disabled. Supports render function children to access state.
+
+## Usage
+
+### Basic Usage
+
+The Checkbox component renders with a default animated indicator if no children are provided. It automatically detects whether it's on a surface background for proper styling.
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />
+```
+
+### With Custom Indicator
+
+Use a render function in the Indicator to show/hide custom icons based on state.
+
+```tsx
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator>
+    {({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
+  </Checkbox.Indicator>
+</Checkbox>
+```
+
+### Invalid State
+
+Show validation errors with the `isInvalid` prop, which applies danger color styling.
+
+```tsx
+<Checkbox
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+  isInvalid={hasError}
+/>
+```
+
+### Custom Animations
+
+Customize or disable animations for both the root checkbox and indicator.
+
+```tsx
+{
+  /* Disable all animations (root and indicator) */
+}
+<Checkbox
+  animation="disable-all"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* Disable only root animation */
+}
+<Checkbox
+  animation="disabled"
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator />
+</Checkbox>;
+
+{
+  /* Disable only indicator animation */
+}
+<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
+  <Checkbox.Indicator animation="disabled" />
+</Checkbox>;
+
+{
+  /* Custom animation configuration */
+}
+<Checkbox
+  animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}
+>
+  <Checkbox.Indicator
+    animation={{
+      scale: { value: [0.5, 1] },
+      opacity: { value: [0, 1] },
+      translateX: { value: [-8, 0] },
+      borderRadius: { value: [12, 0] },
+    }}
+  />
+</Checkbox>;
+```
+
+## Example
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  ControlField,
+  Label,
+  Separator,
+  Surface,
+} from "heroui-native";
+import React from 'react';
+import { View, Text } from 'react-native';
+
+interface CheckboxFieldProps {
+  isSelected: boolean;
+  onSelectedChange: (value: boolean) => void;
+  title: string;
+  description: string;
+}
+
+const CheckboxField: React.FC<CheckboxFieldProps> = ({
+  isSelected,
+  onSelectedChange,
+  title,
+  description,
+}) => {
+  return (
+    <ControlField isSelected={isSelected} onSelectedChange={onSelectedChange}>
+      <ControlField.Indicator>
+        <Checkbox className="mt-0.5" />
+      </ControlField.Indicator>
+      <View className="flex-1">
+        <Label className="text-lg">{title}</Label>
+        <Description className="text-base">
+          {description}
+        </Description>
+      </View>
+    </ControlField>
+  );
+};
+
+export default function BasicUsage() {
+  const [fields, setFields] = React.useState({
+    newsletter: true,
+    marketing: false,
+    terms: false,
+  });
+
+  const fieldConfigs: Record<
+    keyof typeof fields,
+    { title: string; description: string }
+  > = {
+    newsletter: {
+      title: 'Subscribe to newsletter',
+      description: 'Get weekly updates about new features and tips',
+    },
+    marketing: {
+      title: 'Marketing communications',
+      description: 'Receive promotional emails and special offers',
+    },
+    terms: {
+      title: 'Accept terms and conditions',
+      description: 'Agree to our Terms of Service and Privacy Policy',
+    },
+  };
+
+  const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
+    setFields((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;
+
+  return (
+    <View className="flex-1 items-center justify-center px-5">
+      <Surface className="py-5 w-full">
+        {fieldKeys.map((key, index) => (
+          <React.Fragment key={key}>
+            {index > 0 && <Separator className="my-4" />}
+            <CheckboxField
+              isSelected={fields[key]}
+              onSelectedChange={handleFieldChange(key)}
+              title={fieldConfigs[key].title}
+              description={fieldConfigs[key].description}
+            />
+          </React.Fragment>
+        ))}
+      </Surface>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/checkbox.tsx>).
+
+## API Reference
+
+### Checkbox
+
+| prop                    | type                                                                   | default     | description                                                               |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Child elements or render function to customize the checkbox               |
+| `isSelected`            | `boolean`                                                              | `undefined` | Whether the checkbox is currently selected                                |
+| `onSelectedChange`      | `(isSelected: boolean) => void`                                        | `undefined` | Callback fired when the checkbox selection state changes                  |
+| `isDisabled`            | `boolean`                                                              | `false`     | Whether the checkbox is disabled and cannot be interacted with            |
+| `isInvalid`             | `boolean`                                                              | `false`     | Whether the checkbox is invalid (shows danger color)                      |
+| `variant`               | `'primary' \| 'secondary'`                                             | `'primary'` | Variant style for the checkbox                                            |
+| `hitSlop`               | `number`                                                               | `6`         | Hit slop for the pressable area                                           |
+| `animation`             | `CheckboxRootAnimation`                                                | -           | Animation configuration                                                   |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | Whether animated styles (react-native-reanimated) are active              |
+| `className`             | `string`                                                               | `undefined` | Additional CSS classes to apply                                           |
+| `...PressableProps`     | `PressableProps`                                                       | -           | All standard React Native Pressable props are supported (except disabled) |
+
+#### CheckboxRenderProps
+
+| prop         | type      | description                      |
+| ------------ | --------- | -------------------------------- |
+| `isSelected` | `boolean` | Whether the checkbox is selected |
+| `isInvalid`  | `boolean` | Whether the checkbox is invalid  |
+| `isDisabled` | `boolean` | Whether the checkbox is disabled |
+
+#### CheckboxRootAnimation
+
+Animation configuration for checkbox root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                 | type                                     | default             | description                                     |
+| -------------------- | ---------------------------------------- | ------------------- | ----------------------------------------------- |
+| `state`              | `'disabled' \| 'disable-all' \| boolean` | -                   | Disable animations while customizing properties |
+| `scale.value`        | `[number, number]`                       | `[1, 0.96]`         | Scale values [unpressed, pressed]               |
+| `scale.timingConfig` | `WithTimingConfig`                       | `{ duration: 150 }` | Animation timing configuration                  |
+
+### Checkbox.Indicator
+
+| prop                    | type                                                                   | default     | description                                                  |
+| ----------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Content or render function for the checkbox indicator        |
+| `className`             | `string`                                                               | `undefined` | Additional CSS classes for the indicator                     |
+| `iconProps`             | `CheckboxIndicatorIconProps`                                           | `undefined` | Custom props for the default animated check icon             |
+| `animation`             | `CheckboxIndicatorAnimation`                                           | -           | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                                              | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedViewProps`  | `AnimatedProps<ViewProps>`                                             | -           | All standard React Native Animated View props are supported  |
+
+#### CheckboxIndicatorIconProps
+
+Props for customizing the default animated check icon.
+
+| prop            | type     | description                                      |
+| --------------- | -------- | ------------------------------------------------ |
+| `size`          | `number` | Icon size                                        |
+| `strokeWidth`   | `number` | Icon stroke width                                |
+| `color`         | `string` | Icon color (defaults to theme accent-foreground) |
+| `enterDuration` | `number` | Duration of enter animation (check appearing)    |
+| `exitDuration`  | `number` | Duration of exit animation (check disappearing)  |
+
+#### CheckboxIndicatorAnimation
+
+Animation configuration for checkbox indicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                        | type                    | default             | description                                     |
+| --------------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
+| `state`                     | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
+| `opacity.value`             | `[number, number]`      | `[0, 1]`            | Opacity values [unselected, selected]           |
+| `opacity.timingConfig`      | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+| `borderRadius.value`        | `[number, number]`      | `[8, 0]`            | Border radius values [unselected, selected]     |
+| `borderRadius.timingConfig` | `WithTimingConfig`      | `{ duration: 50 }`  | Animation timing configuration                  |
+| `translateX.value`          | `[number, number]`      | `[-4, 0]`           | TranslateX values [unselected, selected]        |
+| `translateX.timingConfig`   | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+| `scale.value`               | `[number, number]`      | `[0.8, 1]`          | Scale values [unselected, selected]             |
+| `scale.timingConfig`        | `WithTimingConfig`      | `{ duration: 100 }` | Animation timing configuration                  |
+
+## Hooks
+
+### useCheckbox
+
+Hook to access checkbox context values within custom components or compound components.
+
+```tsx
+import { useCheckbox } from 'heroui-native';
+
+const CustomIndicator = () => {
+  const { isSelected, isInvalid, isDisabled } = useCheckbox();
+  // ... your implementation
+};
+```
+
+**Returns:** `UseCheckboxReturn`
+
+| property           | type                                           | description                                                    |
+| ------------------ | ---------------------------------------------- | -------------------------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | Whether the checkbox is currently selected                     |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback function to change the checkbox selection state       |
+| `isDisabled`       | `boolean`                                      | Whether the checkbox is disabled and cannot be interacted with |
+| `isInvalid`        | `boolean`                                      | Whether the checkbox is invalid (shows danger color)           |
+| `nativeID`         | `string \| undefined`                          | Native ID for the checkbox element                             |
+
+**Note:** This hook must be used within a `Checkbox` component. It will throw an error if called outside of the checkbox context.
diff --git a/apps/docs/content/docs/en/native/components/(forms)/control-field.mdx b/apps/docs/content/docs/en/native/components/(forms)/control-field.mdx
new file mode 100644
index 0000000..3e3c2d7
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/control-field.mdx
@@ -0,0 +1,251 @@
+---
+title: ControlField
+description: A field component that combines a label, description (or other content), and a control component (Switch or Checkbox) into a single pressable area.
+links:
+  source_native: control-field/control-field.tsx
+  styles_native: control-field/control-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/control-field-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { ControlField } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<ControlField>
+  <Label>...</Label>
+  <Description>...</Description>
+  <ControlField.Indicator>...</ControlField.Indicator>
+  <FieldError>...</FieldError>
+</ControlField>
+```
+
+- **ControlField**: Root container that manages layout and state propagation
+- **Label**: Primary text label for the control (from [Label](./label) component)
+- **Description**: Secondary descriptive helper text (from [Description](./description) component)
+- **ControlField.Indicator**: Container for the form control component ([Switch](./switch), [Checkbox](./checkbox), [Radio](./radio))
+- **FieldError**: Validation error message display (from [FieldError](./field-error) component)
+
+## Usage
+
+### Basic Usage
+
+ControlField wraps form controls to provide consistent layout and state management.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <Label className="flex-1">Label text</Label>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### With Description
+
+Add helper text below the label using the Description component.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue}>
+  <View className="flex-1">
+    <Label>Enable notifications</Label>
+    <Description>
+      Receive push notifications about your account activity
+    </Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### With Error Message
+
+Display validation errors using the ErrorMessage component.
+
+```tsx
+<ControlField
+  isSelected={value}
+  onSelectedChange={setValue}
+  isInvalid={!value}
+  className="flex-col items-start gap-1"
+>
+  <View className="flex-row items-center gap-2">
+    <View className="flex-1">
+      <Label>I agree to the terms</Label>
+      <Description>
+        By checking this box, you agree to our Terms of Service
+      </Description>
+    </View>
+    <ControlField.Indicator variant="checkbox" />
+  </View>
+  <FieldError>This field is required</FieldError>
+</ControlField>
+```
+
+### Disabled State
+
+Control interactivity with the disabled prop.
+
+```tsx
+<ControlField isSelected={value} onSelectedChange={setValue} isDisabled>
+  <View className="flex-1">
+    <Label>Disabled field</Label>
+    <Description>This field is disabled</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+### Disabling All Animations
+
+Disable all animations including children by using `"disable-all"`. This cascades down to all child components.
+
+```tsx
+<ControlField
+  isSelected={value}
+  onSelectedChange={setValue}
+  animation="disable-all"
+>
+  <View className="flex-1">
+    <Label>Label text</Label>
+    <Description>Description text</Description>
+  </View>
+  <ControlField.Indicator />
+</ControlField>
+```
+
+## Example
+
+```tsx
+import {
+  Checkbox,
+  Description,
+  FieldError,
+  ControlField,
+  Label,
+  Switch,
+} from 'heroui-native';
+import React from 'react';
+import { ScrollView, View } from 'react-native';
+
+export default function ControlFieldExample() {
+  const [notifications, setNotifications] = React.useState(false);
+  const [terms, setTerms] = React.useState(false);
+  const [newsletter, setNewsletter] = React.useState(true);
+
+  return (
+    <ScrollView className="bg-background p-4">
+      <View className="gap-4">
+        <ControlField
+          isSelected={notifications}
+          onSelectedChange={setNotifications}
+        >
+          <View className="flex-1">
+            <Label>Enable notifications</Label>
+            <Description>
+              Receive push notifications about your account activity
+            </Description>
+          </View>
+          <ControlField.Indicator />
+        </ControlField>
+
+        <ControlField
+          isSelected={terms}
+          onSelectedChange={setTerms}
+          isInvalid={!terms}
+          className="flex-col items-start gap-1"
+        >
+          <View className="flex-row items-center gap-2">
+            <View className="flex-1">
+              <Label>I agree to the terms and conditions</Label>
+              <Description>
+                By checking this box, you agree to our Terms of Service
+              </Description>
+            </View>
+            <ControlField.Indicator className="mt-0.5">
+              <Checkbox />
+            </ControlField.Indicator>
+          </View>
+          <FieldError>This field is required</FieldError>
+        </ControlField>
+
+        <ControlField isSelected={newsletter} onSelectedChange={setNewsletter}>
+          <View className="flex-1">
+            <Label>Subscribe to newsletter</Label>
+          </View>
+          <ControlField.Indicator>
+            <Checkbox color="warning" />
+          </ControlField.Indicator>
+        </ControlField>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/control-field.tsx).
+
+## API Reference
+
+### ControlField
+
+| prop              | type                                                                       | default     | description                                                                               |
+| ----------------- | -------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children          | `React.ReactNode \| ((props: ControlFieldRenderProps) => React.ReactNode)` | -           | Content to render inside the form control, or a render function                           |
+| isSelected        | `boolean`                                                                  | `undefined` | Whether the control is selected/checked                                                   |
+| isDisabled        | `boolean`                                                                  | `false`     | Whether the form control is disabled                                                      |
+| isInvalid         | `boolean`                                                                  | `false`     | Whether the form control is invalid                                                       |
+| isRequired        | `boolean`                                                                  | `false`     | Whether the form control is required                                                      |
+| className         | `string`                                                                   | -           | Custom class name for the root element                                                    |
+| onSelectedChange  | `(isSelected: boolean) => void`                                            | -           | Callback when selection state changes                                                     |
+| animation         | `"disable-all" \| undefined`                                               | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| ...PressableProps | `PressableProps`                                                           | -           | All React Native Pressable props are supported                                            |
+
+### Label
+
+The `Label` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [Label component documentation](./label).
+
+### Description
+
+The `Description` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [Description component documentation](./description).
+
+### ControlField.Indicator
+
+| prop         | type                                | default    | description                                                |
+| ------------ | ----------------------------------- | ---------- | ---------------------------------------------------------- |
+| children     | `React.ReactNode`                   | -          | Control component to render (Switch, Checkbox, Radio)      |
+| variant      | `'checkbox' \| 'radio' \| 'switch'` | `'switch'` | Variant of the control to render when no children provided |
+| className    | `string`                            | -          | Custom class name for the indicator element                |
+| ...ViewProps | `ViewProps`                         | -          | All React Native View props are supported                  |
+
+**Note**: When children are provided, the component automatically passes down `isSelected`, `onSelectedChange`, `isDisabled`, and `isInvalid` props from the ControlField context if they are not already present on the child component. When using the `radio` variant, the Radio component renders in standalone mode (outside of a RadioGroup).
+
+### FieldError
+
+The `FieldError` component automatically consumes form state (`isInvalid`) from the ControlField context.
+
+**Note**: For complete prop documentation, see the [FieldError component documentation](./field-error). The error message visibility is controlled by the `isInvalid` state of the parent ControlField.
+
+## Hooks
+
+### useControlField
+
+**Returns:**
+
+| property           | type                                           | description                                    |
+| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
+| `isSelected`       | `boolean \| undefined`                         | Whether the control is selected/checked        |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback when selection state changes          |
+| `isDisabled`       | `boolean`                                      | Whether the form control is disabled           |
+| `isInvalid`        | `boolean`                                      | Whether the form control is invalid            |
+| `isPressed`        | `SharedValue<boolean>`                         | Reanimated shared value indicating press state |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/description.mdx b/apps/docs/content/docs/en/native/components/(forms)/description.mdx
new file mode 100644
index 0000000..74996bb
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/description.mdx
@@ -0,0 +1,139 @@
+---
+title: Description
+description: Text component for providing accessible descriptions and helper text for form fields and other UI elements.
+links:
+  source_native: description/description.tsx
+  styles_native: description/description.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Description } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Description>...</Description>
+```
+
+- **Description**: Text component that displays description or helper text with muted styling. Can be linked to form fields via `nativeID` for accessibility support.
+
+## Usage
+
+### Basic Usage
+
+Display description text with default muted styling.
+
+```tsx
+<Description>This is a helpful description.</Description>
+```
+
+### With Form Fields
+
+Provide accessible descriptions for form fields using the `nativeID` prop.
+
+```tsx
+<TextField>
+  <Label>Email address</Label>
+  <Input
+    placeholder="Enter your email"
+    keyboardType="email-address"
+    autoCapitalize="none"
+  />
+  <Description nativeID="email-desc">
+    We'll never share your email with anyone else.
+  </Description>
+</TextField>
+```
+
+### Accessibility Linking
+
+Link descriptions to form fields for screen reader support by using `nativeID` and `aria-describedby`.
+
+```tsx
+<TextField>
+  <Label>Password</Label>
+  <Input
+    placeholder="Create a password"
+    secureTextEntry
+    aria-describedby="password-desc"
+  />
+  <Description nativeID="password-desc">
+    Use at least 8 characters with a mix of letters, numbers, and symbols.
+  </Description>
+</TextField>
+```
+
+### Hiding on Invalid State
+
+Control whether the description should be hidden when the form field is invalid using the `hideOnInvalid` prop.
+
+```tsx
+<TextField isInvalid={isInvalid}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description hideOnInvalid>
+    We'll never share your email with anyone else.
+  </Description>
+  <FieldError>Please enter a valid email address</FieldError>
+</TextField>
+```
+
+When `hideOnInvalid` is `true`, the description will be hidden when the field is invalid. When `false` (default), the description remains visible even when invalid.
+
+## Example
+
+```tsx
+import { Description, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function DescriptionExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-8">
+      <TextField>
+        <Label>Email address</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description nativeID="email-desc">
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+      <TextField>
+        <Label>Password</Label>
+        <Input placeholder="Create a password" secureTextEntry />
+        <Description nativeID="password-desc">
+          Use at least 8 characters with a mix of letters, numbers, and symbols.
+        </Description>
+      </TextField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/description.tsx>).
+
+## API Reference
+
+### Description
+
+| prop            | type                                | default | description                                                                                |
+| --------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `children`      | `React.ReactNode`                   | -       | Description text content                                                                   |
+| `className`     | `string`                            | -       | Additional CSS classes to apply                                                            |
+| `nativeID`      | `string`                            | -       | Native ID for accessibility. Used to link description to form fields via aria-describedby. |
+| `isInvalid`     | `boolean`                           | -       | Whether the description is in an invalid state (overrides context)                         |
+| `isDisabled`    | `boolean`                           | -       | Whether the description is disabled (overrides context)                                    |
+| `hideOnInvalid` | `boolean`                           | `false` | Whether to hide the description when invalid                                               |
+| `animation`     | `DescriptionAnimation \| undefined` | -       | Animation configuration for description transitions                                        |
+| `...TextProps`  | `TextProps`                         | -       | All standard React Native Text props are supported                                         |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/field-error.mdx b/apps/docs/content/docs/en/native/components/(forms)/field-error.mdx
new file mode 100644
index 0000000..cb18ce2
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/field-error.mdx
@@ -0,0 +1,214 @@
+---
+title: FieldError
+description: Displays validation error message content with smooth animations.
+links:
+  source_native: field-error/field-error.tsx
+  styles_native: field-error/field-error.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/field-error-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { FieldError } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<FieldError>Error message content</FieldError>
+```
+
+- **FieldError**: Main container that displays error messages with smooth animations. Accepts string children which are automatically wrapped with Text component, or custom React components for more complex layouts. Controls visibility through the `isInvalid` prop and supports custom entering/exiting animations.
+
+## Usage
+
+### Basic Usage
+
+The FieldError component displays error messages when validation fails.
+
+```tsx
+<FieldError isInvalid={true}>This field is required</FieldError>
+```
+
+### Controlled Visibility
+
+Control when the error appears using the `isInvalid` prop. When used inside a form field component (like TextField), FieldError automatically consumes the form-item-state context.
+
+```tsx
+const [isInvalid, setIsInvalid] = useState(false);
+
+<FieldError isInvalid={isInvalid}>Please enter a valid email address</FieldError>;
+```
+
+### With Form Fields
+
+FieldError automatically consumes form state from TextField via the form-item-state context.
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <FieldError>Please enter a valid email address</FieldError>
+</TextField>
+```
+
+### Custom Content
+
+Pass custom React components as children instead of strings.
+
+```tsx
+<FieldError isInvalid={true}>
+  <View className="flex-row items-center">
+    <Icon name="alert-circle" />
+    <Text className="ml-2 text-danger">Invalid input</Text>
+  </View>
+</FieldError>
+```
+
+### Custom Animations
+
+Override default entering and exiting animations using the `animation` prop.
+
+```tsx
+import { SlideInDown, SlideOutUp } from 'react-native-reanimated';
+
+<FieldError
+  isInvalid={true}
+  animation={{
+    entering: { value: SlideInDown.duration(200) },
+    exiting: { value: SlideOutUp.duration(150) },
+  }}
+>
+  Field validation failed
+</FieldError>;
+```
+
+Disable animations entirely:
+
+```tsx
+<FieldError isInvalid={true} animation={false}>
+  Field validation failed
+</FieldError>
+```
+
+### Custom Styling
+
+Apply custom styles to the container and text elements.
+
+```tsx
+<FieldError
+  isInvalid={true}
+  className="mt-2"
+  classNames={{
+    container: 'bg-danger/10 p-2 rounded',
+    text: 'text-xs font-medium',
+  }}
+>
+  Password must be at least 8 characters
+</FieldError>
+```
+
+### Custom Text Props
+
+Pass additional props to the Text component when children is a string.
+
+```tsx
+<FieldError
+  isInvalid={true}
+  textProps={{
+    numberOfLines: 1,
+    ellipsizeMode: 'tail',
+    style: { letterSpacing: 0.5 },
+  }}
+>
+  This is a very long error message that might need to be truncated
+</FieldError>
+```
+
+## Example
+
+```tsx
+import { Description, FieldError, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function FieldErrorExample() {
+  const [email, setEmail] = useState('');
+  const [isInvalid, setIsInvalid] = useState(false);
+
+  const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+  const handleBlur = () => {
+    setIsInvalid(email !== '' && !isValidEmail);
+  };
+
+  return (
+    <View className="p-4">
+      <TextField isInvalid={isInvalid}>
+        <Label>Email Address</Label>
+        <Input
+          placeholder="Enter your email"
+          value={email}
+          onChangeText={setEmail}
+          onBlur={handleBlur}
+          keyboardType="email-address"
+          autoCapitalize="none"
+        />
+        <Description>
+          We'll use this to contact you
+        </Description>
+        <FieldError>Please enter a valid email address</FieldError>
+      </TextField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/field-error.tsx).
+
+## API Reference
+
+### FieldError
+
+| prop                   | type                                          | default     | description                                                                                                                                   |
+| ---------------------- | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`             | `React.ReactNode`                             | `undefined` | The content of the error field. String children are wrapped with Text                                                                         |
+| `isInvalid`            | `boolean`                                     | `undefined` | Controls the visibility of the error field (overrides form-item-state context). When used inside TextField, automatically consumes form state |
+| `animation`            | `FieldErrorRootAnimation`                     | -           | Animation configuration                                                                                                                       |
+| `className`            | `string`                                      | `undefined` | Additional CSS classes for the container                                                                                                      |
+| `classNames`           | `ElementSlots<FieldErrorSlots>`               | `undefined` | Additional CSS classes for different parts of the component                                                                                   |
+| `styles`               | `{ container?: ViewStyle; text?: TextStyle }` | `undefined` | Styles for different parts of the field error                                                                                                 |
+| `textProps`            | `TextProps`                                   | `undefined` | Additional props to pass to the Text component when children is a string                                                                      |
+| `...AnimatedViewProps` | `AnimatedProps<ViewProps>`                    | -           | All Reanimated Animated.View props are supported                                                                                              |
+
+**classNames prop:** `ElementSlots<FieldErrorSlots>` provides type-safe CSS classes for different parts of the field error component. Available slots: `container`, `text`.
+
+#### `styles`
+
+| prop        | type        | description                 |
+| ----------- | ----------- | --------------------------- |
+| `container` | `ViewStyle` | Styles for the container    |
+| `text`      | `TextStyle` | Styles for the text content |
+
+#### FieldErrorRootAnimation
+
+Animation configuration for field error root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                                     | default                                                               | description                                     |
+| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean` | -                                                                     | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType`                  | `FadeIn`<br/>`.duration(150)`<br/>`.easing(Easing.out(Easing.ease))`  | Custom entering animation for field error       |
+| `exiting.value`  | `EntryOrExitLayoutType`                  | `FadeOut`<br/>`.duration(100)`<br/>`.easing(Easing.out(Easing.ease))` | Custom exiting animation for field error        |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/input-group.mdx b/apps/docs/content/docs/en/native/components/(forms)/input-group.mdx
new file mode 100644
index 0000000..9c40353
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/input-group.mdx
@@ -0,0 +1,207 @@
+---
+title: InputGroup
+description: A compound layout component that groups an input with optional prefix and suffix decorators.
+links:
+  source_native: input-group/input-group.tsx
+  styles_native: input-group/input-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { InputGroup } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix>...</InputGroup.Prefix>
+  <InputGroup.Input />
+  <InputGroup.Suffix>...</InputGroup.Suffix>
+</InputGroup>
+```
+
+- **InputGroup**: Layout container that wraps Prefix, Input, and Suffix. Provides animation settings and a measurement context so Prefix/Suffix widths are automatically applied as padding on the Input.
+- **InputGroup.Prefix**: Absolutely positioned View anchored to the left side of the Input. Its measured width is applied as `paddingLeft` on InputGroup.Input automatically.
+- **InputGroup.Suffix**: Absolutely positioned View anchored to the right side of the Input. Its measured width is applied as `paddingRight` on InputGroup.Input automatically.
+- **InputGroup.Input**: Pass-through to the Input component. Accepts all Input props directly. Automatically receives paddingLeft/paddingRight from measured Prefix/Suffix.
+
+## Usage
+
+### Basic Usage
+
+The InputGroup component uses compound parts to attach prefix and suffix content to an input.
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix>...</InputGroup.Prefix>
+  <InputGroup.Input placeholder="Enter text" />
+  <InputGroup.Suffix>...</InputGroup.Suffix>
+</InputGroup>
+```
+
+### With Prefix Only
+
+Attach leading content such as icons to the input.
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix isDecorative>
+    <PersonIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="Username" />
+</InputGroup>
+```
+
+### With Suffix Only
+
+Attach trailing content such as icons to the input.
+
+```tsx
+<InputGroup>
+  <InputGroup.Input placeholder="Search products..." />
+  <InputGroup.Suffix isDecorative>
+    <MagnifierIcon size={16} />
+  </InputGroup.Suffix>
+</InputGroup>
+```
+
+### Decorative vs Interactive
+
+Set `isDecorative` on Prefix or Suffix to make touches pass through to the Input and hide the content from screen readers. Omit it when the decorator contains interactive elements.
+
+```tsx
+<InputGroup>
+  <InputGroup.Prefix isDecorative>
+    <LockIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="Enter your password" secureTextEntry />
+  <InputGroup.Suffix>
+    <Pressable onPress={togglePasswordVisibility}>
+      <EyeIcon size={16} />
+    </Pressable>
+  </InputGroup.Suffix>
+</InputGroup>
+```
+
+### Disabled State
+
+Disable the entire input group. The disabled state cascades to all child components.
+
+```tsx
+<InputGroup isDisabled>
+  <InputGroup.Prefix isDecorative>
+    <LockIcon size={16} />
+  </InputGroup.Prefix>
+  <InputGroup.Input placeholder="Disabled input" />
+</InputGroup>
+```
+
+### With TextField Integration
+
+Combine with TextField, Label, and Description for full form field support.
+
+```tsx
+<TextField isRequired>
+  <Label>Email</Label>
+  <InputGroup>
+    <InputGroup.Prefix isDecorative>
+      <MailIcon size={16} />
+    </InputGroup.Prefix>
+    <InputGroup.Input placeholder="you@example.com" keyboardType="email-address" />
+  </InputGroup>
+  <Description>We'll never share your email</Description>
+</TextField>
+```
+
+## Example
+
+```tsx
+import { InputGroup } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+
+export default function InputGroupExample() {
+  const [value, setValue] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="px-5">
+      <InputGroup>
+        <InputGroup.Prefix isDecorative>
+          <Ionicons name="lock-closed-outline" size={16} color="#888" />
+        </InputGroup.Prefix>
+        <InputGroup.Input
+          value={value}
+          onChangeText={setValue}
+          placeholder="Enter your password"
+          secureTextEntry={!isPasswordVisible}
+        />
+        <InputGroup.Suffix>
+          <Pressable
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+            hitSlop={20}
+          >
+            <Ionicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              color="#888"
+            />
+          </Pressable>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-group.tsx>).
+
+## API Reference
+
+### InputGroup
+
+| prop           | type                     | default | description                                                                  |
+| -------------- | ------------------------ | ------- | ---------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`        | -       | Children elements to be rendered inside the input group                      |
+| `className`    | `string`                 | -       | Additional CSS classes                                                       |
+| `isDisabled`   | `boolean`                | `false` | Whether the entire input group and its children are disabled                 |
+| `animation`    | `AnimationRootDisableAll`| -       | Animation configuration for input group                                      |
+| `...ViewProps` | `ViewProps`              | -       | All standard React Native View props are supported                           |
+
+#### AnimationRootDisableAll
+
+Animation configuration for the InputGroup root component. Can be:
+
+- `"disable-all"`: Disable all animations including children (cascades down)
+- `undefined`: Use default animations
+
+### InputGroup.Prefix
+
+| prop             | type              | default | description                                                                                  |
+| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `children`       | `React.ReactNode` | -       | Content to render inside the prefix                                                          |
+| `className`      | `string`          | -       | Additional CSS classes                                                                       |
+| `isDecorative`   | `boolean`         | `false` | When true, touches pass through to the Input and content is hidden from screen readers        |
+| `...ViewProps`   | `ViewProps`       | -       | All standard React Native View props are supported                                           |
+
+### InputGroup.Suffix
+
+| prop             | type              | default | description                                                                                  |
+| ---------------- | ----------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `children`       | `React.ReactNode` | -       | Content to render inside the suffix                                                          |
+| `className`      | `string`          | -       | Additional CSS classes                                                                       |
+| `isDecorative`   | `boolean`         | `false` | When true, touches pass through to the Input and content is hidden from screen readers        |
+| `...ViewProps`   | `ViewProps`       | -       | All standard React Native View props are supported                                           |
+
+### InputGroup.Input
+
+Pass-through to the [Input](./input) component. Accepts all Input props directly.
diff --git a/apps/docs/content/docs/en/native/components/(forms)/input-otp.mdx b/apps/docs/content/docs/en/native/components/(forms)/input-otp.mdx
new file mode 100644
index 0000000..30b6c0a
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/input-otp.mdx
@@ -0,0 +1,417 @@
+---
+title: InputOTP
+description: Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support.
+links:
+  source_native: input-otp/input-otp.tsx
+  styles_native: input-otp/input-otp.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { InputOTP } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<InputOTP>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={2}>
+      <InputOTP.SlotPlaceholder />
+      <InputOTP.SlotValue />
+      <InputOTP.SlotCaret />
+    </InputOTP.Slot>
+  </InputOTP.Group>
+</InputOTP>
+```
+
+- **InputOTP**: Main container that manages OTP input state, handles text changes, and provides context to child components. Manages focus, validation, and character input.
+- **InputOTP.Group**: Container for grouping multiple slots together. Use this to visually group related slots (e.g., groups of 3 digits).
+- **InputOTP.Slot**: Individual slot that displays a single character or placeholder. Each slot must have a unique index matching its position in the OTP sequence. When no children are provided, automatically renders SlotPlaceholder, SlotValue, and SlotCaret.
+- **InputOTP.SlotPlaceholder**: Text component that displays the placeholder character for a slot when it's empty. Used by default in Slot if no children provided.
+- **InputOTP.SlotValue**: Text component that displays the actual character value for a slot with animations. Used by default in Slot if no children provided.
+- **InputOTP.SlotCaret**: Animated caret indicator that shows the current input position. Place this inside a Slot to show where the user is currently typing.
+- **InputOTP.Separator**: Visual separator between groups of slots. Use this to visually separate different groups of OTP digits.
+
+## Usage
+
+### Basic Usage
+
+Create a 6-digit OTP input with grouped slots and separator.
+
+```tsx
+<InputOTP maxLength={6} onComplete={(code) => console.log(code)}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### Four Digits
+
+Create a simple 4-digit PIN input.
+
+```tsx
+<InputOTP maxLength={4} onComplete={(code) => console.log(code)}>
+  <InputOTP.Slot index={0} />
+  <InputOTP.Slot index={1} />
+  <InputOTP.Slot index={2} />
+  <InputOTP.Slot index={3} />
+</InputOTP>
+```
+
+### With Placeholder
+
+Provide custom placeholder characters for each slot position.
+
+```tsx
+<InputOTP
+  maxLength={6}
+  placeholder="——————"
+  onComplete={(code) => console.log(code)}
+>
+  <InputOTP.Group>
+    {({ slots }) => (
+      <>
+        {slots.map((slot) => (
+          <InputOTP.Slot key={slot.index} index={slot.index} />
+        ))}
+      </>
+    )}
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### Controlled Value
+
+Control the OTP value programmatically.
+
+```tsx
+const [value, setValue] = useState('');
+
+<InputOTP value={value} onChange={setValue} maxLength={6}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>;
+```
+
+### With Validation
+
+Display validation errors when the OTP is invalid.
+
+```tsx
+<InputOTP value={value} onChange={setValue} maxLength={6} isInvalid={isInvalid}>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### With Pattern
+
+Restrict input to specific character patterns using regex. Three predefined patterns are available: `REGEXP_ONLY_DIGITS` (matches digits 0-9), `REGEXP_ONLY_CHARS` (matches alphabetic characters a-z, A-Z), and `REGEXP_ONLY_DIGITS_AND_CHARS` (matches both digits and alphabetic characters).
+
+```tsx
+import { InputOTP, REGEXP_ONLY_CHARS } from 'heroui-native';
+
+<InputOTP
+  maxLength={6}
+  pattern={REGEXP_ONLY_CHARS}
+  inputMode="text"
+  onComplete={(code) => console.log(code)}
+>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>;
+```
+
+### Custom Layout
+
+Use render props in Group to create custom slot layouts.
+
+```tsx
+<InputOTP maxLength={6}>
+  <InputOTP.Group>
+    {({ slots, isFocused, isInvalid }) => (
+      <>
+        {slots.map((slot) => (
+          <InputOTP.Slot
+            key={slot.index}
+            index={slot.index}
+            className={cn('custom-class', slot.isActive && 'active-class')}
+          >
+            <InputOTP.SlotPlaceholder />
+            <InputOTP.SlotValue />
+            <InputOTP.SlotCaret />
+          </InputOTP.Slot>
+        ))}
+      </>
+    )}
+  </InputOTP.Group>
+</InputOTP>
+```
+
+### Inside a Bottom Sheet
+
+When rendering an InputOTP inside a `BottomSheet`, use the `useBottomSheetAwareHandlers` hook to wire keyboard avoidance handlers. Pass the returned `onFocus` and `onBlur` to InputOTP.
+
+> **Note**: `useBottomSheetAwareHandlers` must be used inside a `BottomSheet`. Call it from a child component rendered inside `BottomSheet.Content` — outside of a `BottomSheet` context the returned handlers are no-ops.
+
+```tsx
+import { InputOTP, useBottomSheetAwareHandlers } from 'heroui-native';
+
+const BottomSheetOTPInput = () => {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return (
+    <InputOTP maxLength={6} onFocus={onFocus} onBlur={onBlur}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+      </InputOTP.Group>
+      <InputOTP.Separator />
+      <InputOTP.Group>
+        <InputOTP.Slot index={3} />
+        <InputOTP.Slot index={4} />
+        <InputOTP.Slot index={5} />
+      </InputOTP.Group>
+    </InputOTP>
+  );
+};
+```
+
+## Example
+
+```tsx
+import { InputOTP, Label, Description, type InputOTPRef } from 'heroui-native';
+import { View } from 'react-native';
+import { useRef } from 'react';
+
+export default function InputOTPExample() {
+  const ref = useRef<InputOTPRef>(null);
+
+  const onComplete = (code: string) => {
+    console.log('OTP completed:', code);
+    setTimeout(() => {
+      ref.current?.clear();
+    }, 1000);
+  };
+
+  return (
+    <View className="flex-1 px-5 items-center justify-center">
+      <View>
+        <Label>Verify account</Label>
+        <Description className="mb-3">
+          We've sent a code to a****@gmail.com
+        </Description>
+        <InputOTP ref={ref} maxLength={6} onComplete={onComplete}>
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </View>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input-otp.tsx).
+
+## API Reference
+
+### InputOTP
+
+| prop                       | type                          | default     | description                                                                                |
+| -------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| `maxLength`                | `number`                      | -           | Maximum length of the OTP (required)                                                       |
+| `value`                    | `string`                      | -           | Controlled value for the OTP input                                                         |
+| `defaultValue`             | `string`                      | -           | Default value for uncontrolled usage                                                       |
+| `onChange`                 | `(value: string) => void`     | -           | Callback when value changes                                                                |
+| `onComplete`               | `(value: string) => void`     | -           | Handler called when all slots are filled                                                   |
+| `isDisabled`               | `boolean`                     | `false`     | Whether the input is disabled                                                              |
+| `isInvalid`                | `boolean`                     | `false`     | Whether the input is in an invalid state                                                   |
+| `pattern`                  | `string`                      | -           | Regex pattern for allowed characters (e.g., REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS)         |
+| `inputMode`                | `TextInputProps['inputMode']` | `'numeric'` | Input mode for the input                                                                   |
+| `placeholder`              | `string`                      | -           | Placeholder text for the input. Each character corresponds to a slot position              |
+| `placeholderTextColor`     | `string`                      | -           | Placeholder text color for all slots                                                       |
+| `placeholderTextClassName` | `string`                      | -           | Placeholder text class name for all slots                                                  |
+| `pasteTransformer`         | `(text: string) => string`    | -           | Transform pasted text (e.g., remove hyphens). Defaults to removing non-matching characters |
+| `onFocus`                  | `(e: FocusEvent) => void`     | -           | Handler for focus events                                                                   |
+| `onBlur`                   | `(e: BlurEvent) => void`      | -           | Handler for blur events                                                                    |
+| `textInputProps`           | `Omit<TextInputProps, ...>`   | -           | Additional props to pass to the underlying TextInput component                             |
+| `children`                 | `React.ReactNode`             | -           | Children elements to be rendered inside the InputOTP                                       |
+| `className`                | `string`                      | -           | Additional CSS classes to apply                                                            |
+| `style`                    | `PressableProps['style']`     | -           | Style to pass to the container Pressable component                                         |
+| `isBottomSheetAware`       | `boolean`                     | `true`      | Whether the InputOTP automatically handles keyboard state when rendered inside a BottomSheet. Set to `false` to disable |
+| `animation`                | `"disable-all" \| undefined`  | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children  |
+
+### InputOTP.Group
+
+| prop           | type                                                                        | default | description                                                                                                              |
+| -------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `children`     | `React.ReactNode \| ((props: InputOTPGroupRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the group, or a render function that receives slot data and other context values |
+| `className`    | `string`                                                                    | -       | Additional CSS classes to apply                                                                                          |
+| `...ViewProps` | `ViewProps`                                                                 | -       | All standard React Native View props are supported                                                                       |
+
+#### InputOTPGroupRenderProps
+
+| prop         | type         | description                              |
+| ------------ | ------------ | ---------------------------------------- |
+| `slots`      | `SlotData[]` | Array of slot data for each position     |
+| `maxLength`  | `number`     | Maximum length of the OTP                |
+| `value`      | `string`     | Current OTP value                        |
+| `isFocused`  | `boolean`    | Whether the input is currently focused   |
+| `isDisabled` | `boolean`    | Whether the input is disabled            |
+| `isInvalid`  | `boolean`    | Whether the input is in an invalid state |
+
+### InputOTP.Slot
+
+| prop           | type              | default | description                                                                                 |
+| -------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `index`        | `number`          | -       | Zero-based index of the slot (required). Must be between 0 and maxLength - 1                |
+| `children`     | `React.ReactNode` | -       | Custom slot content. If not provided, defaults to SlotPlaceholder, SlotValue, and SlotCaret |
+| `className`    | `string`          | -       | Additional CSS classes to apply                                                             |
+| `style`        | `ViewStyle`       | -       | Additional styles to apply                                                                  |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported                                          |
+
+### InputOTP.SlotPlaceholder
+
+| prop           | type        | default | description                                                          |
+| -------------- | ----------- | ------- | -------------------------------------------------------------------- |
+| `children`     | `string`    | -       | Text content to display (optional, defaults to slot.placeholderChar) |
+| `className`    | `string`    | -       | Additional CSS classes to apply                                      |
+| `style`        | `TextStyle` | -       | Additional styles to apply                                           |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported                   |
+
+### InputOTP.SlotValue
+
+| prop           | type                         | default | description                                               |
+| -------------- | ---------------------------- | ------- | --------------------------------------------------------- |
+| `children`     | `string`                     | -       | Text content to display (optional, defaults to slot.char) |
+| `className`    | `string`                     | -       | Additional CSS classes to apply                           |
+| `animation`    | `InputOTPSlotValueAnimation` | -       | Animation configuration for SlotValue                     |
+| `...TextProps` | `TextProps`                  | -       | All standard React Native Text props are supported        |
+
+#### InputOTPSlotValueAnimation
+
+Animation configuration for InputOTP.SlotValue component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop               | type                    | default                                  | description                                     |
+| ------------------ | ----------------------- | ---------------------------------------- | ----------------------------------------------- |
+| `state`            | `'disabled' \| boolean` | -                                        | Disable animations while customizing properties |
+| `wrapper.entering` | `EntryOrExitLayoutType` | `FadeIn.duration(250)`                   | Entering animation for wrapper                  |
+| `wrapper.exiting`  | `EntryOrExitLayoutType` | `FadeOut.duration(100)`                  | Exiting animation for wrapper                   |
+| `text.entering`    | `EntryOrExitLayoutType` | `FlipInXDown.duration(250).easing(...)`  | Entering animation for text                     |
+| `text.exiting`     | `EntryOrExitLayoutType` | `FlipOutXDown.duration(250).easing(...)` | Exiting animation for text                      |
+
+### InputOTP.SlotCaret
+
+| prop                    | type                         | default  | description                                                                                                                                  |
+| ----------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`             | `string`                     | -        | Additional CSS classes to apply                                                                                                              |
+| `style`                 | `ViewStyle`                  | -        | Additional styles to apply                                                                                                                   |
+| `animation`             | `InputOTPSlotCaretAnimation` | -        | Animation configuration for SlotCaret                                                                                                        |
+| `isAnimatedStyleActive` | `boolean`                    | `true`   | Whether animated styles (react-native-reanimated) are active. When `false`, the animated style is removed and you can implement custom logic |
+| `pointerEvents`         | `'none' \| 'auto' \| ...`    | `'none'` | Pointer events configuration                                                                                                                 |
+| `...ViewProps`          | `ViewProps`                  | -        | All standard React Native View props are supported                                                                                           |
+
+#### InputOTPSlotCaretAnimation
+
+Animation configuration for InputOTP.SlotCaret component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop               | type                    | default    | description                                     |
+| ------------------ | ----------------------- | ---------- | ----------------------------------------------- |
+| `state`            | `'disabled' \| boolean` | -          | Disable animations while customizing properties |
+| `opacity.value`    | `[number, number]`      | `[0, 1]`   | Opacity values [min, max]                       |
+| `opacity.duration` | `number`                | `500`      | Animation duration in milliseconds              |
+| `height.value`     | `[number, number]`      | `[16, 18]` | Height values [min, max] in pixels              |
+| `height.duration`  | `number`                | `500`      | Animation duration in milliseconds              |
+
+### InputOTP.Separator
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | Additional CSS classes to apply                    |
+| `...ViewProps` | `ViewProps` | -       | All standard React Native View props are supported |
+
+## Hooks
+
+### useInputOTP
+
+Hook to access the InputOTP root context. Must be used within an `InputOTP` component.
+
+```tsx
+const { value, maxLength, isFocused, isDisabled, isInvalid, slots } =
+  useInputOTP();
+```
+
+### useInputOTPSlot
+
+Hook to access the InputOTP.Slot context. Must be used within an `InputOTP.Slot` component.
+
+```tsx
+const { slot, isActive, isCaretVisible } = useInputOTPSlot();
+```
diff --git a/apps/docs/content/docs/en/native/components/(forms)/input.mdx b/apps/docs/content/docs/en/native/components/(forms)/input.mdx
new file mode 100644
index 0000000..d2340c8
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/input.mdx
@@ -0,0 +1,228 @@
+---
+title: Input
+description: A text input component with styled border and background for collecting user input.
+links:
+  source_native: input/input.tsx
+  styles_native: input/input.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Input } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+Input can be used standalone or within a TextField component.
+
+```tsx
+import { Input } from 'heroui-native';
+
+<Input placeholder="Enter your email" />;
+```
+
+### Within TextField
+
+Input works seamlessly with TextField for complete form structure.
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+</TextField>;
+```
+
+### With Validation
+
+Display error state when the input is invalid.
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <FieldError>Please enter a valid email</FieldError>
+</TextField>;
+```
+
+### With Local Invalid State Override
+
+Override the context's invalid state for the input.
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isInvalid={true}>
+  <Label isInvalid={false}>Email</Label>
+  <Input placeholder="Enter your email" isInvalid={false} />
+  <FieldError>Email format is incorrect</FieldError>
+</TextField>;
+```
+
+### Disabled State
+
+Disable the input to prevent interaction.
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField isDisabled>
+  <Label>Disabled Field</Label>
+  <Input placeholder="Cannot edit" value="Read only value" />
+</TextField>;
+```
+
+### With Variant
+
+Use different variants to style the input based on context.
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Primary Variant</Label>
+  <Input placeholder="Primary style" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>Secondary Variant</Label>
+  <Input placeholder="Secondary style" variant="secondary" />
+</TextField>
+```
+
+### Custom Styling
+
+Customize the input appearance using className.
+
+```tsx
+import { Input, Label, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Custom Styled</Label>
+  <Input
+    placeholder="Custom colors"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>;
+```
+
+### Inside a Bottom Sheet
+
+When rendering an Input inside a `BottomSheet`, use the `useBottomSheetAwareHandlers` hook to wire keyboard avoidance handlers. Pass the returned `onFocus` and `onBlur` to the Input.
+
+> **Note**: `useBottomSheetAwareHandlers` must be used inside a `BottomSheet`. Call it from a child component rendered inside `BottomSheet.Content` — outside of a `BottomSheet` context the returned handlers are no-ops.
+
+```tsx
+import { Input, TextField, useBottomSheetAwareHandlers } from 'heroui-native';
+
+const BottomSheetTextInput = () => {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return (
+    <TextField>
+      <Input
+        placeholder="Type here..."
+        onFocus={onFocus}
+        onBlur={onBlur}
+      />
+    </TextField>
+  );
+};
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Description, Input, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export const TextInputContent = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="gap-4">
+      <TextField isRequired>
+        <Label>Email</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+          value={email}
+          onChangeText={setEmail}
+        />
+        <Description>
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+
+      <TextField isRequired>
+        <Label>New password</Label>
+        <View className="w-full flex-row items-center">
+          <Input
+            value={password}
+            onChangeText={setPassword}
+            className="flex-1 px-10"
+            placeholder="Enter your password"
+            secureTextEntry={!isPasswordVisible}
+          />
+          <StyledIonicons
+            name="lock-closed-outline"
+            size={16}
+            className="absolute left-3.5 text-muted"
+            pointerEvents="none"
+          />
+          <Pressable
+            className="absolute right-4"
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+          >
+            <StyledIonicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              className="text-muted"
+            />
+          </Pressable>
+        </View>
+        <Description>Password must be at least 6 characters</Description>
+      </TextField>
+    </View>
+  );
+};
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/input.tsx).
+
+## API Reference
+
+### Input
+
+| prop                      | type                       | default               | description                                                  |
+| ------------------------- | -------------------------- | --------------------- | ------------------------------------------------------------ |
+| isInvalid                 | `boolean`                  | `undefined`           | Whether the input is in an invalid state (overrides context) |
+| variant                   | `'primary' \| 'secondary'` | `'primary'`           | Variant style for the input                                  |
+| className                 | `string`                   | -                     | Custom class name for the input                              |
+| selectionColorClassName   | `string`                   | `"accent-accent"`     | Custom className for the selection color                     |
+| placeholderColorClassName | `string`                   | `"field-placeholder"` | Custom className for the placeholder text color              |
+| isBottomSheetAware        | `boolean`                  | `true`                | Whether the input automatically handles keyboard state when rendered inside a BottomSheet. Set to `false` to disable |
+| animation                 | `AnimationRoot`            | `undefined`           | Animation configuration for the input                        |
+| ...TextInputProps         | `TextInputProps`           | -                     | All standard React Native TextInput props are supported      |
+
+> **Note**: When used within a TextField component, Input automatically consumes form state (isDisabled, isInvalid) from TextField via the form-item-state context.
diff --git a/apps/docs/content/docs/en/native/components/(forms)/label.mdx b/apps/docs/content/docs/en/native/components/(forms)/label.mdx
new file mode 100644
index 0000000..05c6671
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/label.mdx
@@ -0,0 +1,197 @@
+---
+title: Label
+description: Text component for labeling form fields and other UI elements with support for required indicators and validation states.
+links:
+  source_native: label/label.tsx
+  styles_native: label/label.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Label } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Label>
+  <Label.Text>...</Label.Text>
+</Label>
+```
+
+- **Label**: Root container that manages label state and provides context to child components. When string children are provided, automatically renders as Label.Text. Supports disabled, required, and invalid states.
+- **Label.Text**: Text content of the label. Displays the label text and automatically shows an asterisk when the label is required. Changes color when invalid or disabled.
+
+## Usage
+
+### Basic Usage
+
+Display a label with text content. String children are automatically rendered as Label.Text.
+
+```tsx
+<Label>Username</Label>
+```
+
+### With Form Fields
+
+Use Label with form fields to provide accessible labels.
+
+```tsx
+<TextField>
+  <Label>Username</Label>
+  <Input placeholder="Choose a username" />
+</TextField>
+```
+
+### Required Fields
+
+Show an asterisk indicator for required fields using the `isRequired` prop.
+
+```tsx
+<TextField>
+  <Label isRequired>Password</Label>
+  <Input placeholder="Create a password" secureTextEntry />
+</TextField>
+```
+
+### Invalid State
+
+Display labels in an invalid state to indicate validation errors.
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+
+<TextField isInvalid>
+  <Label isInvalid>Confirm password</Label>
+  <Input
+    placeholder="Confirm your password"
+    secureTextEntry
+    value="different"
+    editable={false}
+  />
+  <FieldError>Passwords do not match</FieldError>
+</TextField>
+```
+
+### Disabled State
+
+Disable labels to indicate non-interactive fields.
+
+```tsx
+<TextField isDisabled>
+  <Label>Subscription plan</Label>
+  <Input value="Premium" />
+</TextField>
+```
+
+### Custom Layout
+
+Use compound components for custom label layouts.
+
+```tsx
+<Label>
+  <Label.Text>Custom label</Label.Text>
+</Label>
+```
+
+### Custom Styling
+
+Apply custom styles using className, classNames, or styles props.
+
+```tsx
+<Label className="mb-2">
+  <Label.Text
+    className="text-lg"
+    classNames={{
+      text: "font-bold",
+      asterisk: "text-danger"
+    }}
+  >
+    Custom styled label
+  </Label.Text>
+</Label>
+```
+
+## Example
+
+```tsx
+import { FieldError, Label, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function LabelExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-8">
+      <TextField>
+        <Label>Username</Label>
+        <Input placeholder="Choose a username" />
+      </TextField>
+      <TextField>
+        <Label isRequired>Password</Label>
+        <Input placeholder="Create a password" secureTextEntry />
+      </TextField>
+      <TextField isInvalid>
+        <Label isInvalid>Confirm password</Label>
+        <Input
+          placeholder="Confirm your password"
+          secureTextEntry
+          value="different"
+          editable={false}
+        />
+        <FieldError>Passwords do not match</FieldError>
+      </TextField>
+      <TextField isDisabled>
+        <Label>Subscription plan</Label>
+        <Input value="Premium" />
+      </TextField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/label.tsx).
+
+## API Reference
+
+### Label
+
+| prop                | type                         | default     | description                                                                                                   |
+| ------------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode`            | -           | Label content. When string is provided, automatically renders as Label.Text. Otherwise renders children as-is |
+| `isRequired`        | `boolean`                    | `false`     | Whether the label is required. Shows asterisk indicator when true                                             |
+| `isInvalid`         | `boolean`                    | `false`     | Whether the label is in an invalid state. Changes text color to danger                                        |
+| `isDisabled`        | `boolean`                    | `false`     | Whether the label is disabled. Applies disabled styling and prevents interaction                              |
+| `className`         | `string`                     | -           | Additional CSS classes to apply                                                                               |
+| `animation`         | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children                     |
+| `...PressableProps` | `PressableProps`             | -           | All standard React Native Pressable props are supported                                                       |
+
+### Label.Text
+
+| prop           | type                                     | default | description                                                                        |
+| -------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                        | -       | Label text content                                                                 |
+| `className`    | `string`                                 | -       | Additional CSS classes to apply to the text element                                |
+| `classNames`   | `ElementSlots<LabelSlots>`               | -       | Additional CSS classes for different parts of the label                            |
+| `styles`       | `Partial<Record<LabelSlots, TextStyle>>` | -       | Styles for different parts of the label                                            |
+| `nativeID`     | `string`                                 | -       | Native ID for accessibility. Used to link label to form fields via aria-labelledby |
+| `...TextProps` | `TextProps`                              | -       | All standard React Native Text props are supported                                 |
+
+#### `ElementSlots<LabelSlots>`
+
+| prop       | type     | description                    |
+| ---------- | -------- | ------------------------------ |
+| `text`     | `string` | CSS classes for the label text |
+| `asterisk` | `string` | CSS classes for the asterisk   |
+
+#### `styles`
+
+| prop       | type        | description               |
+| ---------- | ----------- | ------------------------- |
+| `text`     | `TextStyle` | Styles for the label text |
+| `asterisk` | `TextStyle` | Styles for the asterisk   |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/radio-group.mdx b/apps/docs/content/docs/en/native/components/(forms)/radio-group.mdx
new file mode 100644
index 0000000..d51e376
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/radio-group.mdx
@@ -0,0 +1,339 @@
+---
+title: RadioGroup
+description: A set of radio buttons where only one option can be selected at a time.
+links:
+  source_native: radio-group/radio-group.tsx
+  styles_native: radio-group/radio-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/radio-group-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { RadioGroup } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<RadioGroup>
+  <RadioGroup.Item>
+    <Label>...</Label>
+    <Description>...</Description>
+    <Radio>
+      <Radio.Indicator>
+        <Radio.IndicatorThumb />
+      </Radio.Indicator>
+    </Radio>
+  </RadioGroup.Item>
+  <FieldError>...</FieldError>
+</RadioGroup>
+```
+
+- **RadioGroup**: Container that manages the selection state of radio items. Supports both horizontal and vertical orientations.
+- **RadioGroup.Item**: Individual radio option within a RadioGroup. Must be used inside RadioGroup. Handles selection state and renders a default `<Radio />` indicator when text children are provided. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`).
+- **Label**: Optional clickable text label for the radio option. Linked to the radio for accessibility. Use the [Label](./label) component directly.
+- **Description**: Optional secondary text below the label. Provides additional context about the radio option. Use the [Description](./description) component directly.
+- **Radio**: The [Radio](./radio) component used inside `RadioGroup.Item` to render the radio indicator. Automatically detects the `RadioGroupItem` context and derives `isSelected`, `isDisabled`, `isInvalid`, and `variant` from it.
+- **Radio.Indicator**: Optional container for the radio circle. Renders default thumb if no children provided. Manages the visual selection state. See [Radio](./radio) for full API.
+- **Radio.IndicatorThumb**: Optional inner circle that appears when selected. Animates scale based on selection. Can be replaced with custom content. See [Radio](./radio) for full API.
+- **FieldError**: Error message displayed when radio group is invalid. Shown with animation below the radio group content. Use the [FieldError](./field-error) component directly.
+
+## Usage
+
+### Basic Usage
+
+RadioGroup with simple string children automatically renders title and indicator.
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">Option 1</RadioGroup.Item>
+  <RadioGroup.Item value="option2">Option 2</RadioGroup.Item>
+  <RadioGroup.Item value="option3">Option 3</RadioGroup.Item>
+</RadioGroup>
+```
+
+### With Descriptions
+
+Add descriptive text below each radio option for additional context.
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from 'heroui-native';
+import { View } from 'react-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="standard">
+    <View>
+      <Label>Standard Shipping</Label>
+      <Description>Delivered in 5-7 business days</Description>
+    </View>
+    <Radio />
+  </RadioGroup.Item>
+  <RadioGroup.Item value="express">
+    <View>
+      <Label>Express Shipping</Label>
+      <Description>Delivered in 2-3 business days</Description>
+    </View>
+    <Radio />
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### Custom Indicator
+
+Replace the default indicator thumb with custom content using `Radio` sub-components.
+
+```tsx
+import { RadioGroup, Radio, Label } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="custom">
+    {({ isSelected }) => (
+      <>
+        <Label>Custom Option</Label>
+        <Radio>
+          <Radio.Indicator>
+            {isSelected && (
+              <Animated.View entering={FadeIn}>
+                <Icon name="check" size={12} />
+              </Animated.View>
+            )}
+          </Radio.Indicator>
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### With Render Function
+
+Use a render function on RadioGroup.Item to access state and customize the entire content.
+
+```tsx
+import { RadioGroup, Radio, Label } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">
+    {({ isSelected, isInvalid, isDisabled }) => (
+      <>
+        <Label>Option 1</Label>
+        <Radio>
+          <Radio.Indicator>{isSelected && <CustomIcon />}</Radio.Indicator>
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+### With Error Message
+
+Display validation errors below the radio group.
+
+```tsx
+import { RadioGroup, FieldError } from 'heroui-native';
+
+function RadioGroupWithError() {
+  const [value, setValue] = React.useState<string | undefined>(undefined);
+
+  return (
+    <RadioGroup value={value} onValueChange={setValue} isInvalid={!value}>
+      <RadioGroup.Item value="agree">I agree to the terms</RadioGroup.Item>
+      <RadioGroup.Item value="disagree">I do not agree</RadioGroup.Item>
+      <FieldError isInvalid={!value}>
+        Please select an option to continue
+      </FieldError>
+    </RadioGroup>
+  );
+}
+```
+
+## Example
+
+```tsx
+import {
+  Description,
+  Label,
+  Radio,
+  RadioGroup,
+  Separator,
+  Surface,
+} from 'heroui-native';
+import React from 'react';
+import { View } from 'react-native';
+
+export default function RadioGroupExample() {
+  const [selection, setSelection] = React.useState('desc1');
+
+  return (
+    <Surface className="w-full">
+      <RadioGroup value={selection} onValueChange={setSelection}>
+        <RadioGroup.Item value="desc1">
+          <View>
+            <Label>Standard Shipping</Label>
+            <Description>Delivered in 5-7 business days</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+        <Separator className="my-1" />
+        <RadioGroup.Item value="desc2">
+          <View>
+            <Label>Express Shipping</Label>
+            <Description>Delivered in 2-3 business days</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+        <Separator className="my-1" />
+        <RadioGroup.Item value="desc3">
+          <View>
+            <Label>Overnight Shipping</Label>
+            <Description>Delivered next business day</Description>
+          </View>
+          <Radio />
+        </RadioGroup.Item>
+      </RadioGroup>
+    </Surface>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/radio-group.tsx>).
+
+## API Reference
+
+### RadioGroup
+
+| prop            | type                         | default     | description                                                                               |
+| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`      | `React.ReactNode`            | `undefined` | Radio group content                                                                       |
+| `value`         | `string \| undefined`        | `undefined` | The currently selected value of the radio group                                           |
+| `onValueChange` | `(val: string) => void`      | `undefined` | Callback fired when the selected value changes                                            |
+| `isDisabled`    | `boolean`                    | `false`     | Whether the entire radio group is disabled                                                |
+| `isInvalid`     | `boolean`                    | `false`     | Whether the radio group is invalid                                                        |
+| `variant`       | `'primary' \| 'secondary'`   | `undefined` | Variant style for the radio group (inherited by items if not set on item)                 |
+| `animation`     | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `className`     | `string`                     | `undefined` | Custom class name                                                                         |
+| `...ViewProps`  | `ViewProps`                  | -           | All standard React Native View props are supported                                        |
+
+### RadioGroup.Item
+
+| prop                | type                                                                         | default     | description                                                               |
+| ------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((props: RadioGroupItemRenderProps) => React.ReactNode)` | `undefined` | Radio item content or render function to customize the radio item         |
+| `value`             | `string`                                                                     | `undefined` | The value associated with this radio item                                 |
+| `isDisabled`        | `boolean`                                                                    | `false`     | Whether this specific radio item is disabled                              |
+| `isInvalid`         | `boolean`                                                                    | `false`     | Whether the radio item is invalid                                         |
+| `variant`           | `'primary' \| 'secondary'`                                                   | `'primary'` | Variant style for the radio item                                          |
+| `hitSlop`           | `number`                                                                     | `6`         | Hit slop for the pressable area                                           |
+| `className`         | `string`                                                                     | `undefined` | Custom class name                                                         |
+| `...PressableProps` | `PressableProps`                                                             | -           | All standard React Native Pressable props are supported (except disabled) |
+
+#### RadioGroupItemRenderProps
+
+| prop         | type      | description                        |
+| ------------ | --------- | ---------------------------------- |
+| `isSelected` | `boolean` | Whether the radio item is selected |
+| `isInvalid`  | `boolean` | Whether the radio item is invalid  |
+| `isDisabled` | `boolean` | Whether the radio item is disabled |
+
+### Radio (inside RadioGroup.Item)
+
+The `Radio` component is used inside `RadioGroup.Item` to render the radio indicator. When placed inside a `RadioGroup.Item`, the Radio component automatically detects the `RadioGroupItem` context and derives `isSelected`, `isDisabled`, `isInvalid`, and `variant` from it — no manual prop passing is needed.
+
+Use `<Radio />` for the default indicator, or compose with `Radio.Indicator` and `Radio.IndicatorThumb` for custom styling.
+
+| prop                | type                                                                | default     | description                                                               |
+| ------------------- | ------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((props: RadioRenderProps) => React.ReactNode)` | `undefined` | Child elements or render function to customize the radio                  |
+| `variant`           | `'primary' \| 'secondary'`                                          | `'primary'` | Variant style for the radio                                               |
+| `isSelected`        | `boolean`                                                           | `undefined` | Whether the radio is currently selected                                   |
+| `isDisabled`        | `boolean`                                                           | `undefined` | Whether the radio is disabled and cannot be interacted with               |
+| `isInvalid`         | `boolean`                                                           | `false`     | Whether the radio is invalid (shows danger color)                         |
+| `className`         | `string`                                                            | `undefined` | Additional CSS classes to apply                                           |
+| `animation`         | `RadioRootAnimation`                                                | -           | Animation configuration for radio                                         |
+| `onSelectedChange`  | `(isSelected: boolean) => void`                                     | `undefined` | Callback fired when the radio selection state changes                     |
+| `...PressableProps` | `PressableProps`                                                    | -           | All standard React Native Pressable props are supported (except disabled) |
+
+#### RadioRenderProps
+
+| prop         | type      | description                   |
+| ------------ | --------- | ----------------------------- |
+| `isSelected` | `boolean` | Whether the radio is selected |
+| `isDisabled` | `boolean` | Whether the radio is disabled |
+| `isInvalid`  | `boolean` | Whether the radio is invalid  |
+
+#### RadioRootAnimation
+
+Animation configuration for radio root component. Can be:
+
+- `"disable-all"`: Disable all animations including children (Indicator, IndicatorThumb)
+- `undefined`: Use default animations
+
+### Radio.Indicator
+
+| prop                   | type                       | default     | description                                      |
+| ---------------------- | -------------------------- | ----------- | ------------------------------------------------ |
+| `children`             | `React.ReactNode`          | `undefined` | Content for the radio indicator                  |
+| `className`            | `string`                   | `undefined` | Additional CSS classes for the indicator         |
+| `...AnimatedViewProps` | `AnimatedProps<ViewProps>` | -           | All Reanimated Animated.View props are supported |
+
+### Radio.IndicatorThumb
+
+| prop                    | type                           | default     | description                                                  |
+| ----------------------- | ------------------------------ | ----------- | ------------------------------------------------------------ |
+| `className`             | `string`                       | `undefined` | Additional CSS classes for the thumb                         |
+| `animation`             | `RadioIndicatorThumbAnimation` | -           | Animation configuration for the thumb                        |
+| `isAnimatedStyleActive` | `boolean`                      | `true`      | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedViewProps`  | `AnimatedProps<ViewProps>`     | -           | All Reanimated Animated.View props are supported             |
+
+#### RadioIndicatorThumbAnimation
+
+Animation configuration for radio indicator thumb component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                 | type                    | default                                              | description                                     |
+| -------------------- | ----------------------- | ---------------------------------------------------- | ----------------------------------------------- |
+| `state`              | `'disabled' \| boolean` | -                                                    | Disable animations while customizing properties |
+| `scale.value`        | `[number, number]`      | `[1.5, 1]`                                           | Scale values [unselected, selected]             |
+| `scale.timingConfig` | `WithTimingConfig`      | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                  |
+
+**Note:** For labels, descriptions, and error messages, use the base components directly:
+
+- Use [Label](../label/label.md) component for labels
+- Use [Description](../description/description.md) component for descriptions
+- Use [FieldError](../field-error/field-error.md) component for error messages
+
+## Hooks
+
+### useRadioGroup
+
+**Returns:**
+
+| Property        | Type                       | Description                                    |
+| --------------- | -------------------------- | ---------------------------------------------- |
+| `value`         | `string \| undefined`      | Currently selected value                       |
+| `isDisabled`    | `boolean`                  | Whether the radio group is disabled            |
+| `isInvalid`     | `boolean`                  | Whether the radio group is in an invalid state |
+| `variant`       | `'primary' \| 'secondary'` | Variant style for the radio group              |
+| `onValueChange` | `(value: string) => void`  | Function to change the selected value          |
+
+### useRadioGroupItem
+
+**Returns:**
+
+| Property           | Type                                           | Description                                                             |
+| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| `isSelected`       | `boolean`                                      | Whether the radio item is selected                                      |
+| `isDisabled`       | `boolean \| undefined`                         | Whether the radio item is disabled                                      |
+| `isInvalid`        | `boolean \| undefined`                         | Whether the radio item is invalid                                       |
+| `variant`          | `'primary' \| 'secondary' \| undefined`        | Variant style for the radio item                                        |
+| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback to change the selection state (selects this item in the group) |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/search-field.mdx b/apps/docs/content/docs/en/native/components/(forms)/search-field.mdx
new file mode 100644
index 0000000..8d26b4d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/search-field.mdx
@@ -0,0 +1,241 @@
+---
+title: SearchField
+description: A compound search input for filtering and querying content.
+links:
+  source_native: search-field/search-field.tsx
+  styles_native: search-field/search-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { SearchField } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<SearchField value={value} onChange={onChange}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+- **SearchField**: Root container that accepts `value` and `onChange`, providing them to children via context. Also provides form field state (isDisabled, isInvalid, isRequired) and animation settings.
+- **SearchField.Group**: Flex-row container that positions the search icon, input, and clear button horizontally.
+- **SearchField.SearchIcon**: Magnifying glass icon positioned absolutely on the left side of the input. Supports custom children to replace the default icon.
+- **SearchField.Input**: Wraps the Input component with search-specific defaults. Reads `value` and `onChangeText` from the SearchField context automatically.
+- **SearchField.ClearButton**: Small icon-only button to clear the search input. Automatically hidden when value is empty. Calls `onChange("")` from context on press.
+
+## Usage
+
+### Basic Usage
+
+The SearchField component uses compound parts to create a search input. Pass `value` and `onChange` to the root; the Input and ClearButton consume them via context.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### With Label and Description
+
+Add a Label and Description outside the Group to provide context for the search field.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <Label>Find products</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description>Search by name, category, or SKU</Description>
+</SearchField>
+```
+
+### With Validation
+
+Use `isInvalid` and `isRequired` on the root to control validation state. Pair with FieldError to display error messages.
+
+```tsx
+<SearchField
+  value={searchValue}
+  onChange={setSearchValue}
+  isRequired
+  isInvalid={isInvalid}
+>
+  <Label>Search users</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description hideOnInvalid>Enter at least 3 characters to search</Description>
+  <FieldError>No results found. Please try a different search term.</FieldError>
+</SearchField>
+```
+
+### Custom Search Icon
+
+Replace the default magnifying glass icon by passing children to `SearchField.SearchIcon`.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon>
+      <Text className="text-base">🔍</Text>
+    </SearchField.SearchIcon>
+    <SearchField.Input className="pl-10" />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### Disabled
+
+Set `isDisabled` on the root to disable all child components via context.
+
+```tsx
+<SearchField value="Previous query" isDisabled>
+  <Label>Disabled search</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+  </SearchField.Group>
+  <Description>Search is temporarily unavailable</Description>
+</SearchField>
+```
+
+## Example
+
+```tsx
+import { Description, Label, SearchField } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function SearchFieldExample() {
+  const [searchValue, setSearchValue] = useState('');
+
+  return (
+    <View className="px-5">
+      <SearchField value={searchValue} onChange={setSearchValue}>
+        <Label>Find products</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Search by name, category, or SKU</Description>
+      </SearchField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/search-field.tsx>).
+
+## API Reference
+
+### SearchField
+
+| prop           | type                      | default | description                                              |
+| -------------- | ------------------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode`         | -       | Children elements to be rendered inside the search field |
+| `value`        | `string`                  | -       | Controlled search text value                             |
+| `onChange`     | `(value: string) => void` | -       | Callback fired when the search text changes              |
+| `isDisabled`   | `boolean`                 | `false` | Whether the search field is disabled                     |
+| `isInvalid`    | `boolean`                 | `false` | Whether the search field is in an invalid state          |
+| `isRequired`   | `boolean`                 | `false` | Whether the search field is required                     |
+| `className`    | `string`                  | -       | Additional CSS classes                                   |
+| `animation`    | `AnimationRootDisableAll` | -       | Animation configuration for the search field             |
+| `...ViewProps` | `ViewProps`               | -       | All standard React Native View props are supported       |
+
+#### AnimationRootDisableAll
+
+Animation configuration for the SearchField root component. Can be:
+
+- `"disable-all"`: Disable all animations including children (cascades down)
+- `undefined`: Use default animations
+
+### SearchField.Group
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the group  |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### SearchField.SearchIcon
+
+| prop           | type                             | default | description                                                                        |
+| -------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                | -       | Custom content to replace the default search icon                                  |
+| `className`    | `string`                         | -       | Additional CSS classes                                                             |
+| `iconProps`    | `SearchFieldSearchIconIconProps` | -       | Props for customizing the default search icon (ignored when children are provided) |
+| `...ViewProps` | `ViewProps`                      | -       | All standard React Native View props are supported                                 |
+
+#### SearchFieldSearchIconIconProps
+
+| prop    | type     | default             | description       |
+| ------- | -------- | ------------------- | ----------------- |
+| `size`  | `number` | `16`                | Size of the icon  |
+| `color` | `string` | Theme `muted` color | Color of the icon |
+
+### SearchField.Input
+
+Extends [Input](./input) props with search-specific defaults (`placeholder="Search..."`, `returnKeyType="search"`, `accessibilityRole="search"`). Omits `value` and `onChangeText` because they are provided by the SearchField context.
+
+### SearchField.ClearButton
+
+Automatically hidden when the controlled `value` is an empty string. Calls `onChange("")` from context on press. Additional `onPress` handlers passed via props are called after clearing.
+
+| prop             | type                              | default | description                                      |
+| ---------------- | --------------------------------- | ------- | ------------------------------------------------ |
+| `children`       | `React.ReactNode`                 | -       | Custom content to replace the default close icon |
+| `iconProps`      | `SearchFieldClearButtonIconProps` | -       | Props for customizing the clear button icon      |
+| `className`      | `string`                          | -       | Additional CSS classes                           |
+| `...ButtonProps` | `ButtonRootProps`                 | -       | All Button root props are supported              |
+
+#### SearchFieldClearButtonIconProps
+
+| prop    | type     | default             | description       |
+| ------- | -------- | ------------------- | ----------------- |
+| `size`  | `number` | `14`                | Size of the icon  |
+| `color` | `string` | Theme `muted` color | Color of the icon |
+
+## Hooks
+
+### useSearchField
+
+Hook to access the search field state from context. Must be used within a `SearchField` component.
+
+```tsx
+import { useSearchField } from 'heroui-native';
+
+const { value, onChange, isDisabled, isInvalid, isRequired } = useSearchField();
+```
+
+#### Returns
+
+| property     | type                                     | description                                     |
+| ------------ | ---------------------------------------- | ----------------------------------------------- |
+| `value`      | `string \| undefined`                    | Current controlled search text value            |
+| `onChange`   | `((value: string) => void) \| undefined` | Callback to update the search text              |
+| `isDisabled` | `boolean`                                | Whether the search field is disabled            |
+| `isInvalid`  | `boolean`                                | Whether the search field is in an invalid state |
+| `isRequired` | `boolean`                                | Whether the search field is required            |
diff --git a/apps/docs/content/docs/en/native/components/(forms)/select.mdx b/apps/docs/content/docs/en/native/components/(forms)/select.mdx
new file mode 100644
index 0000000..3f49327
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/select.mdx
@@ -0,0 +1,822 @@
+---
+title: Select
+description: Displays a list of options for the user to pick from — triggered by a button.
+icon: updated
+links:
+  source_native: select/select.tsx
+  styles_native: select/select.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/select-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Select } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content>
+      <Select.Close />
+      <Select.ListLabel>...</Select.ListLabel>
+      <Select.Item>
+        <Select.ItemLabel />
+        <Select.ItemDescription>...</Select.ItemDescription>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+- **Select**: Main container that manages open/close state, value selection and provides context to child components.
+- **Select.Trigger**: Clickable element that toggles the select visibility. Wraps any child element with press handlers. Supports `variant` prop (`'default'` or `'unstyled'`).
+- **Select.Value**: Displays the selected value or placeholder text. Automatically updates when selection changes. Styling changes based on selection state.
+- **Select.TriggerIndicator**: Optional visual indicator showing open/close state. Renders an animated chevron icon by default that rotates when the select opens/closes.
+- **Select.Portal**: Renders select content in a portal layer above other content. Ensures proper stacking and positioning.
+- **Select.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
+- **Select.Content**: Container for select content with three presentation modes: popover (floating with positioning), bottom sheet modal, or dialog modal.
+- **Select.Close**: Close button for the select. Can accept custom children or uses default close icon.
+- **Select.ListLabel**: Label for the list of items with pre-styled typography.
+- **Select.Item**: Selectable option item. Handles selection state and press events.
+- **Select.ItemLabel**: Displays the label text for an item.
+- **Select.ItemDescription**: Optional description text for items with muted styling.
+- **Select.ItemIndicator**: Optional indicator shown for selected items. Renders a check icon by default.
+
+## Usage
+
+### Basic Usage
+
+The Select component uses compound parts to create dropdown selection interfaces.
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="Option 1" />
+      <Select.Item value="2" label="Option 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### With Value Display
+
+Display the selected value in the trigger using the Value component.
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="Choose an option" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="apple" label="Apple" />
+      <Select.Item value="orange" label="Orange" />
+      <Select.Item value="banana" label="Banana" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Popover Presentation
+
+Use popover presentation for floating content with automatic positioning.
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" placement="bottom" align="center">
+      <Select.Item value="1" label="Item 1" />
+      <Select.Item value="2" label="Item 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Width Control
+
+Control the width of the select content using the `width` prop. This only works with popover presentation.
+
+```tsx
+{
+  /* Fixed width in pixels */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width={280}>
+      <Select.Item value="1" label="Item 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* Match trigger width */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="trigger">
+      <Select.Item value="1" label="Item 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* Full width (100%) */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="full">
+      <Select.Item value="1" label="Item 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+
+{
+  /* Auto-size to content (default) */
+}
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover" width="content-fit">
+      <Select.Item value="1" label="Item 1" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+```
+
+### Bottom Sheet Presentation
+
+Use bottom sheet for mobile-optimized selection experience.
+
+```tsx
+<Select presentation="bottom-sheet">
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="bottom-sheet" snapPoints={['35%']}>
+      <Select.Item value="1" label="Item 1" />
+      <Select.Item value="2" label="Item 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Dialog Presentation
+
+Use dialog presentation for centered modal-style selection.
+
+```tsx
+<Select presentation="dialog">
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="dialog">
+      <Select.Close />
+      <Select.ListLabel>Choose an option</Select.ListLabel>
+      <Select.Item value="1" label="Item 1" />
+      <Select.Item value="2" label="Item 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Custom Item Content
+
+Customize item appearance with custom content and indicators.
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="us" label="United States">
+        <View className="flex-row items-center gap-3 flex-1">
+          <Text>🇺🇸</Text>
+          <Select.ItemLabel />
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+      <Select.Item value="uk" label="United Kingdom">
+        <View className="flex-row items-center gap-3 flex-1">
+          <Text>🇬🇧</Text>
+          <Select.ItemLabel />
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### With Render Function
+
+Use a render function on `Select.Item` to access state and customize content based on selection.
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="us" label="United States">
+        {({ isSelected, value, isDisabled }) => (
+          <>
+            <View className="flex-row items-center gap-3 flex-1">
+              <Text>🇺🇸</Text>
+              <Select.ItemLabel
+                className={
+                  isSelected ? 'text-accent font-medium' : 'text-foreground'
+                }
+              />
+            </View>
+            <Select.ItemIndicator />
+          </>
+        )}
+      </Select.Item>
+      <Select.Item value="uk" label="United Kingdom">
+        {({ isSelected }) => (
+          <>
+            <View className="flex-row items-center gap-3 flex-1">
+              <Text>🇬🇧</Text>
+              <Select.ItemLabel
+                className={
+                  isSelected ? 'text-accent font-medium' : 'text-foreground'
+                }
+              />
+            </View>
+            <Select.ItemIndicator />
+          </>
+        )}
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### With Item Description
+
+Add descriptions to items for additional context.
+
+```tsx
+<Select>
+  <Select.Trigger>...</Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="basic" label="Basic">
+        <View className="flex-1">
+          <Select.ItemLabel />
+          <Select.ItemDescription>
+            Essential features for personal use
+          </Select.ItemDescription>
+        </View>
+        <Select.ItemIndicator />
+      </Select.Item>
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### With Trigger Indicator
+
+Add a visual indicator to show the open/close state of the select. The indicator rotates when the select opens/closes.
+
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="Select one" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="Option 1" />
+      <Select.Item value="2" label="Option 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Custom Trigger with Unstyled Variant
+
+Use the `unstyled` variant when composing a custom trigger with other components like Button.
+
+```tsx
+<Select>
+  <Select.Trigger variant="unstyled" asChild>
+    <Button variant="secondary">
+      <Select.Value placeholder="Select..." />
+      <Select.TriggerIndicator />
+    </Button>
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="Option 1" />
+      <Select.Item value="2" label="Option 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+### Controlled Mode
+
+Control the select state programmatically.
+
+```tsx
+const [value, setValue] = useState();
+const [isOpen, setIsOpen] = useState(false);
+
+<Select
+  value={value}
+  onValueChange={setValue}
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+>
+  <Select.Trigger>
+    <Select.Value placeholder="Select..." />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Overlay />
+    <Select.Content presentation="popover">
+      <Select.Item value="1" label="Option 1" />
+      <Select.Item value="2" label="Option 2" />
+    </Select.Content>
+  </Select.Portal>
+</Select>;
+```
+
+## Example
+
+```tsx
+import { Select, Separator } from 'heroui-native';
+import React, { useState } from 'react';
+
+type SelectOption = {
+  value: string;
+  label: string;
+};
+
+const US_STATES: SelectOption[] = [
+  { value: 'CA', label: 'California' },
+  { value: 'NY', label: 'New York' },
+  { value: 'TX', label: 'Texas' },
+  { value: 'FL', label: 'Florida' },
+];
+
+export default function SelectExample() {
+  const [value, setValue] = useState<SelectOption | undefined>();
+
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <Select.Trigger>
+        <Select.Value placeholder="Select one" />
+        <Select.TriggerIndicator />
+      </Select.Trigger>
+      <Select.Portal>
+        <Select.Overlay />
+        <Select.Content presentation="popover" width="trigger">
+          <Select.ListLabel className="mb-2">Choose a state</Select.ListLabel>
+          {US_STATES.map((state, index) => (
+            <React.Fragment key={state.value}>
+              <Select.Item value={state.value} label={state.label} />
+              {index < US_STATES.length - 1 && <Separator />}
+            </React.Fragment>
+          ))}
+        </Select.Content>
+      </Select.Portal>
+    </Select>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/select.tsx).
+
+## API Reference
+
+### Select
+
+| prop            | type                                      | default     | description                                                            |
+| --------------- | ----------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `children`      | `ReactNode`                               | -           | The content of the select                                              |
+| `value`         | `SelectOption \| SelectOption[]`                  | -           | The selected value(s) (controlled mode)                                |
+| `onValueChange` | `(value: SelectOption \| SelectOption[]) => void` | -           | Callback when the value changes                                        |
+| `defaultValue`  | `SelectOption \| SelectOption[]`                  | -           | The default selected value(s) (uncontrolled mode)                      |
+| `isOpen`        | `boolean`                                 | -           | Whether the select is open (controlled mode)                           |
+| `isDefaultOpen` | `boolean`                                 | -           | Whether the select is open when initially rendered (uncontrolled mode) |
+| `onOpenChange`  | `(isOpen: boolean) => void`               | -           | Callback when the select open state changes                            |
+| `isDisabled`    | `boolean`                                 | `false`     | Whether the select is disabled                                         |
+| `presentation`  | `'popover' \| 'bottom-sheet' \| 'dialog'` | `'popover'` | Presentation mode for the select content                               |
+| `animation`     | `SelectRootAnimation`                     | -           | Animation configuration                                                |
+| `asChild`       | `boolean`                                 | `false`     | Whether to render as a child element                                   |
+| `...ViewProps`  | `ViewProps`                               | -           | All standard React Native View props are supported                     |
+
+#### SelectRootAnimation
+
+Animation configuration for Select component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                                             | default | description                                     |
+| ---------------- | ------------------------------------------------ | ------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| 'disable-all' \| boolean`         | -       | Disable animations while customizing properties |
+| `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | -       | Animation configuration for when select opens   |
+| `exiting.value`  | `SpringAnimationConfig \| TimingAnimationConfig` | -       | Animation configuration for when select closes  |
+
+#### SpringAnimationConfig
+
+| prop     | type               | default | description                               |
+| -------- | ------------------ | ------- | ----------------------------------------- |
+| `type`   | `'spring'`         | -       | Animation type (must be `'spring'`)       |
+| `config` | `WithSpringConfig` | -       | Reanimated spring animation configuration |
+
+#### TimingAnimationConfig
+
+| prop     | type               | default | description                               |
+| -------- | ------------------ | ------- | ----------------------------------------- |
+| `type`   | `'timing'`         | -       | Animation type (must be `'timing'`)       |
+| `config` | `WithTimingConfig` | -       | Reanimated timing animation configuration |
+
+### Select.Trigger
+
+| prop                | type                      | default     | description                                                                                                       |
+| ------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| `variant`           | `'default' \| 'unstyled'` | `'default'` | The variant of the trigger. `'default'` applies pre-styled container styles, `'unstyled'` removes default styling |
+| `children`          | `ReactNode`               | -           | The trigger element content                                                                                       |
+| `className`         | `string`                  | -           | Additional CSS classes for the trigger                                                                            |
+| `asChild`           | `boolean`                 | `true`      | Whether to render as a child element                                                                              |
+| `isDisabled`        | `boolean`                 | -           | Whether the trigger is disabled                                                                                   |
+| `...PressableProps` | `PressableProps`          | -           | All standard React Native Pressable props are supported                                                           |
+
+### Select.Value
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `placeholder`  | `string`    | -       | Placeholder text when no value is selected         |
+| `className`    | `string`    | -       | Additional CSS classes for the value               |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+**Note:** The value component automatically applies different text colors based on selection state:
+
+- When a value is selected: `text-foreground`
+- When no value is selected (placeholder): `text-field-placeholder`
+
+### Select.TriggerIndicator
+
+| prop                    | type                              | default | description                                                  |
+| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
+| `children`              | `ReactNode`                       | -       | Custom indicator content. Defaults to animated chevron icon  |
+| `className`             | `string`                          | -       | Additional CSS classes for the trigger indicator             |
+| `style`                 | `ViewStyle`                       | -       | Custom styles for the trigger indicator                      |
+| `iconProps`             | `SelectTriggerIndicatorIconProps` | -       | Chevron icon configuration                                   |
+| `animation`             | `SelectTriggerIndicatorAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                         | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `ViewProps`                       | -       | All standard React Native View props are supported           |
+
+**Note:** The following style properties are occupied by animations and cannot be set via className:
+
+- `transform` (specifically `rotate`) - Animated for open/close rotation transitions
+
+To customize this property, use the `animation` prop. To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+
+#### SelectTriggerIndicatorIconProps
+
+| prop    | type     | default | description                                            |
+| ------- | -------- | ------- | ------------------------------------------------------ |
+| `size`  | `number` | `16`    | Size of the icon                                       |
+| `color` | `string` | -       | Color of the icon (defaults to foreground theme color) |
+
+#### SelectTriggerIndicatorAnimation
+
+Animation configuration for Select.TriggerIndicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations (rotation from 0° to -180°)
+- `object`: Custom animation configuration
+
+| prop                    | type                    | default                                      | description                                     |
+| ----------------------- | ----------------------- | -------------------------------------------- | ----------------------------------------------- |
+| `state`                 | `'disabled' \| boolean` | -                                            | Disable animations while customizing properties |
+| `rotation.value`        | `[number, number]`      | `[0, -180]`                                  | Rotation values [closed, open] in degrees       |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring animation configuration for rotation     |
+
+### Select.Portal
+
+| prop                       | type        | default | description                                                                                                                   |
+| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactNode` | -       | The portal content (required)                                                                                                 |
+| `disableFullWindowOverlay` | `boolean`   | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `className`                | `string`    | -       | Additional CSS classes for the portal container                                                                               |
+| `hostName`                 | `string`    | -       | Optional name of the host element for the portal                                                                              |
+| `forceMount`               | `boolean`   | -       | Whether to force mount the component in the DOM                                                                               |
+| `...ViewProps`             | `ViewProps` | -       | All standard React Native View props are supported                                                                            |
+
+### Select.Overlay
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                 | -       | Additional CSS classes for the overlay                       |
+| `animation`             | `SelectOverlayAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `closeOnPress`          | `boolean`                | `true`  | Whether to close the select when overlay is pressed          |
+| `forceMount`            | `boolean`                | -       | Whether to force mount the component in the DOM              |
+| `asChild`               | `boolean`                | `false` | Whether to render as a child element                         |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported             |
+
+#### SelectOverlayAnimation
+
+Animation configuration for Select.Overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations (progress-based opacity for bottom-sheet/dialog, Keyframe animations for popover)
+- `object`: Custom animation configuration
+
+| prop            | type                       | default     | description                                                                  |
+| --------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -           | Disable animations while customizing properties                              |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values [idle, open, close] (for bottom-sheet/dialog presentation)    |
+| `entering`      | `EntryOrExitLayoutType`    | -           | Custom Keyframe animation for entering transition (for popover presentation) |
+| `exiting`       | `EntryOrExitLayoutType`    | -           | Custom Keyframe animation for exiting transition (for popover presentation)  |
+
+### Select.Content (Popover Presentation)
+
+| prop                    | type                                             | default         | description                                            |
+| ----------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ |
+| `children`              | `ReactNode`                                      | -               | The select content                                     |
+| `width`                 | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content                  |
+| `presentation`          | `'popover'`                                      | `'popover'`     | Presentation mode for the select                       |
+| `placement`             | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | Placement of the content relative to trigger           |
+| `align`                 | `'start' \| 'center' \| 'end'`                   | `'center'`      | Alignment along the placement axis                     |
+| `avoidCollisions`       | `boolean`                                        | `true`          | Whether to flip placement when close to viewport edges |
+| `offset`                | `number`                                         | `8`             | Distance from trigger element in pixels                |
+| `alignOffset`           | `number`                                         | `0`             | Offset along the alignment axis in pixels              |
+| `className`             | `string`                                         | -               | Additional CSS classes for the content container       |
+| `animation`             | `SelectContentPopoverAnimation`                  | -               | Animation configuration                                |
+| `forceMount`            | `boolean`                                        | -               | Whether to force mount the component in the DOM        |
+| `insets`                | `Insets`                                         | -               | Screen edge insets to respect when positioning         |
+| `asChild`               | `boolean`                                        | `false`         | Whether to render as a child element                   |
+| `...Animated.ViewProps` | `Animated.ViewProps`                             | -               | All Reanimated Animated.View props are supported       |
+
+#### SelectContentPopoverAnimation
+
+Animation configuration for Select.Content component (popover presentation). Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default Keyframe animations (translateY/translateX, scale, opacity based on placement)
+- `object`: Custom animation configuration with `entering` and/or `exiting` Keyframe animations
+
+| prop       | type                    | default | description                                                                                                                                |
+| ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state`    | `'disabled' \| boolean` | -       | Disable animations while customizing properties                                                                                            |
+| `entering` | `EntryOrExitLayoutType` | -       | Custom Keyframe animation for entering transition (default: Keyframe with translateY/translateX, scale, opacity based on placement, 200ms) |
+| `exiting`  | `EntryOrExitLayoutType` | -       | Custom Keyframe animation for exiting transition (default: Keyframe mirroring entering animation, 150ms)                                   |
+
+### Select.Content (Bottom Sheet Presentation)
+
+| prop                        | type               | default | description                                      |
+| --------------------------- | ------------------ | ------- | ------------------------------------------------ |
+| `children`                  | `ReactNode`        | -       | The bottom sheet content                         |
+| `presentation`              | `'bottom-sheet'`   | -       | Presentation mode for the select                 |
+| `contentContainerClassName` | `string`           | -       | Additional CSS classes for the content container |
+| `...BottomSheetProps`       | `BottomSheetProps` | -       | All @gorhom/bottom-sheet props are supported     |
+
+### Select.Content (Dialog Presentation)
+
+| prop           | type                                                     | default | description                                         |
+| -------------- | -------------------------------------------------------- | ------- | --------------------------------------------------- |
+| `children`     | `ReactNode`                                              | -       | The dialog content                                  |
+| `presentation` | `'dialog'`                                               | -       | Presentation mode for the select                    |
+| `classNames`   | `{ wrapper?: string; content?: string }`                 | -       | Additional CSS classes for wrapper and content      |
+| `styles`       | `Partial<Record<DialogContentFallbackSlots, ViewStyle>>` | -       | Styles for different parts of the dialog content    |
+| `animation`    | `SelectContentAnimation`                                 | -       | Animation configuration                             |
+| `isSwipeable`  | `boolean`                                                | `true`  | Whether the dialog content can be swiped to dismiss |
+| `forceMount`   | `boolean`                                                | -       | Whether to force mount the component in the DOM     |
+| `asChild`      | `boolean`                                                | `false` | Whether to render as a child element                |
+| `...ViewProps` | `ViewProps`                                              | -       | All standard React Native View props are supported  |
+
+#### `styles`
+
+| prop      | type        | description                      |
+| --------- | ----------- | -------------------------------- |
+| `wrapper` | `ViewStyle` | Styles for the wrapper container |
+| `content` | `ViewStyle` | Styles for the dialog content    |
+
+#### SelectContentAnimation
+
+Animation configuration for Select.Content component (dialog presentation). Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default Keyframe animations (scale and opacity transitions)
+- `object`: Custom animation configuration with `entering` and/or `exiting` Keyframe animations
+
+| prop       | type                    | default | description                                                                                              |
+| ---------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -       | Disable animations while customizing properties                                                          |
+| `entering` | `EntryOrExitLayoutType` | -       | Custom Keyframe animation for entering transition (default: Keyframe with scale and opacity, 200ms)      |
+| `exiting`  | `EntryOrExitLayoutType` | -       | Custom Keyframe animation for exiting transition (default: Keyframe mirroring entering animation, 150ms) |
+
+### Select.Close
+
+Select.Close extends [CloseButton](./close-button) and automatically handles select dismissal when pressed.
+
+### Select.ListLabel
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | The label text content                             |
+| `className`    | `string`    | -       | Additional CSS classes for the list label          |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+### Select.Item
+
+| prop                | type                                                         | default | description                                                                |
+| ------------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------------------- |
+| `children`          | `ReactNode \| ((props: SelectItemRenderProps) => ReactNode)` | -       | Custom item content. Defaults to label and indicator, or a render function |
+| `value`             | `any`                                                        | -       | The value associated with this item (required)                             |
+| `label`             | `string`                                                     | -       | The label text for this item (required)                                    |
+| `isDisabled`        | `boolean`                                                    | `false` | Whether this item is disabled                                              |
+| `className`         | `string`                                                     | -       | Additional CSS classes for the item                                        |
+| `...PressableProps` | `PressableProps`                                             | -       | All standard React Native Pressable props are supported                    |
+
+#### SelectItemRenderProps
+
+When using a render function for `children`, the following props are provided:
+
+| property     | type      | description                             |
+| ------------ | --------- | --------------------------------------- |
+| `isSelected` | `boolean` | Whether this item is currently selected |
+| `value`      | `string`  | The value of the item                   |
+| `isDisabled` | `boolean` | Whether the item is disabled            |
+
+### Select.ItemLabel
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | Additional CSS classes for the item label          |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+### Select.ItemDescription
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | The description text content                       |
+| `className`    | `string`    | -       | Additional CSS classes for the item description    |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+### Select.ItemIndicator
+
+| prop           | type                           | default | description                                        |
+| -------------- | ------------------------------ | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode`                    | -       | Custom indicator content. Defaults to check icon   |
+| `className`    | `string`                       | -       | Additional CSS classes for the item indicator      |
+| `iconProps`    | `SelectItemIndicatorIconProps` | -       | Check icon configuration                           |
+| `...ViewProps` | `ViewProps`                    | -       | All standard React Native View props are supported |
+
+#### SelectItemIndicatorIconProps
+
+| prop    | type     | default          | description       |
+| ------- | -------- | ---------------- | ----------------- |
+| `size`  | `number` | `16`             | Size of the icon  |
+| `color` | `string` | theme accent-soft-foreground color | Color of the icon |
+
+## Hooks
+
+### useSelect
+
+Hook to access the Select root context. Returns the select state and control functions.
+
+```tsx
+import { useSelect } from 'heroui-native';
+
+const {
+  isOpen,
+  onOpenChange,
+  isDefaultOpen,
+  isDisabled,
+  presentation,
+  triggerPosition,
+  setTriggerPosition,
+  contentLayout,
+  setContentLayout,
+  nativeID,
+  value,
+  onValueChange,
+} = useSelect();
+```
+
+#### Return Value
+
+| property             | type                                         | description                                               |
+| -------------------- | -------------------------------------------- | --------------------------------------------------------- |
+| `isOpen`             | `boolean`                                    | Whether the select is currently open                      |
+| `onOpenChange`       | `(open: boolean) => void`                    | Callback to change the open state                         |
+| `isDefaultOpen`      | `boolean \| undefined`                       | Whether the select is open by default (uncontrolled mode) |
+| `isDisabled`         | `boolean \| undefined`                       | Whether the select is disabled                            |
+| `presentation`       | `'popover' \| 'bottom-sheet' \| 'dialog'`    | Presentation mode for the select content                  |
+| `triggerPosition`    | `LayoutPosition \| null`                     | Position of the trigger element relative to viewport      |
+| `setTriggerPosition` | `(position: LayoutPosition \| null) => void` | Updates the trigger element's position                    |
+| `contentLayout`      | `LayoutRectangle \| null`                    | Layout measurements of the select content                 |
+| `setContentLayout`   | `(layout: LayoutRectangle \| null) => void`  | Updates the content layout measurements                   |
+| `nativeID`           | `string`                                     | Unique identifier for the select instance                 |
+| `value`              | `SelectOption \| SelectOption[]`                   | Currently selected option                                 |
+| `onValueChange`      | `(option: SelectOption \| SelectOption[]) => void` | Callback fired when the selected value changes            |
+
+**Note:** This hook must be used within a `Select` component. It will throw an error if called outside of the select context.
+
+### useSelectAnimation
+
+Hook to access the Select animation state values within custom components or compound components.
+
+```tsx
+import { useSelectAnimation } from 'heroui-native';
+
+const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } =
+  useSelectAnimation();
+```
+
+#### Return Value
+
+| property                           | type                   | description                                                |
+| ---------------------------------- | ---------------------- | ---------------------------------------------------------- |
+| `progress`                         | `SharedValue<number>`  | Progress value for animations (0=idle, 1=open, 2=close)    |
+| `isDragging`                       | `SharedValue<boolean>` | Whether the select content is currently being dragged      |
+| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | Whether the gesture release animation is currently running |
+
+**Note:** This hook must be used within a `Select` component. It will throw an error if called outside of the select animation context.
+
+#### SelectOption
+
+| property | type     | description                  |
+| -------- | -------- | ---------------------------- |
+| `value`  | `string` | The value of the option      |
+| `label`  | `string` | The label text of the option |
+
+### useSelectItem
+
+Hook to access the Select Item context. Returns the item's value and label.
+
+```tsx
+import { useSelectItem } from 'heroui-native';
+
+const { itemValue, label } = useSelectItem();
+```
+
+#### Return Value
+
+| property    | type     | description                        |
+| ----------- | -------- | ---------------------------------- |
+| `itemValue` | `string` | The value of the current item      |
+| `label`     | `string` | The label text of the current item |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Select uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Select.Portal`. Tradeoff: the select dropdown will not appear above native modals when disabled.
+
+### Native Modal (iOS)
+
+When a `Select` is opened inside a screen presented as a native modal (`presentation: 'modal' | 'formSheet' | 'pageSheet'`), the dropdown may render shifted upward. In the new architecture (Fabric), `react-native-screens` marks `RNSModalScreen` as a Fabric root, so the trigger's position is reported relative to the modal's origin while `FullWindowOverlay` (where the dropdown is mounted) is anchored to the iOS application window. Compensate by adding `safeAreaInsets.top` to `offset`:
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Select.Content presentation="popover" offset={insets.top + 10}>
+  ...
+</Select.Content>;
+```
diff --git a/apps/docs/content/docs/en/native/components/(forms)/text-area.mdx b/apps/docs/content/docs/en/native/components/(forms)/text-area.mdx
new file mode 100644
index 0000000..e471ce6
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/text-area.mdx
@@ -0,0 +1,140 @@
+---
+title: TextArea
+description: A multiline text input component with styled border and background for collecting longer user input.
+links:
+  source_native: text-area/text-area.tsx
+  styles_native: text-area/text-area.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { TextArea } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+TextArea can be used standalone or within a TextField component.
+
+```tsx
+import { TextArea } from 'heroui-native';
+
+<TextArea placeholder="Enter your message" />
+```
+
+### Within TextField
+
+TextArea works seamlessly with TextField for complete form structure.
+
+```tsx
+import { Description, Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Message</Label>
+  <TextArea placeholder="Enter your message here..." />
+  <Description>Please provide as much detail as possible.</Description>
+</TextField>
+```
+
+### With Validation
+
+Display error state when the text area is invalid.
+
+```tsx
+import { FieldError, Label, TextArea, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Message</Label>
+  <TextArea placeholder="Enter your message" />
+  <FieldError>Please enter a valid message</FieldError>
+</TextField>
+```
+
+### Disabled State
+
+Disable the text area to prevent interaction.
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField isDisabled>
+  <Label>Disabled Field</Label>
+  <TextArea placeholder="Cannot edit" value="Read only value" />
+</TextField>
+```
+
+### With Variant
+
+Use different variants to style the text area based on context.
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Primary Variant</Label>
+  <TextArea placeholder="Primary style text area" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>Secondary Variant</Label>
+  <TextArea placeholder="Secondary style text area" variant="secondary" />
+</TextField>
+```
+
+### Custom Styling
+
+Customize the text area appearance using className.
+
+```tsx
+import { Label, TextArea, TextField } from 'heroui-native';
+
+<TextField>
+  <Label>Custom Styled</Label>
+  <TextArea
+    placeholder="Custom colors"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>
+```
+
+## Example
+
+```tsx
+import { Description, FieldError, Label, TextArea, TextField } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function TextAreaExample() {
+  return (
+    <View className="gap-8">
+      <TextField>
+        <Label>Primary Variant</Label>
+        <TextArea placeholder="Primary style text area" variant="primary" />
+        <Description>Default variant with primary styling</Description>
+      </TextField>
+
+      <TextField>
+        <Label>Secondary Variant</Label>
+        <TextArea
+          placeholder="Secondary style text area"
+          variant="secondary"
+        />
+        <Description>Secondary variant for surfaces</Description>
+      </TextField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-area.tsx).
+
+## API Reference
+
+TextArea extends [Input](./input) component and inherits all its props. The only differences are default values: `multiline` defaults to `true` and `textAlignVertical` defaults to `'top'`.
diff --git a/apps/docs/content/docs/en/native/components/(forms)/text-field.mdx b/apps/docs/content/docs/en/native/components/(forms)/text-field.mdx
new file mode 100644
index 0000000..6443e86
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(forms)/text-field.mdx
@@ -0,0 +1,266 @@
+---
+title: TextField
+description: A text input component with label, description, and error handling for collecting user input.
+links:
+  source_native: text-field/text-field.tsx
+  styles_native: text-field/text-field.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-field-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { TextField } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<TextField>
+  <Label>...</Label>
+  <Input />
+  <Description>...</Description>
+  <FieldError>...</FieldError>
+</TextField>
+```
+
+- **TextField**: Root container that provides spacing and state management
+- **Label**: Label with optional asterisk for required fields (from [Label](./label) component)
+- **Input**: Input container with animated border and background (from [Input](./input) component)
+- **Description**: Secondary descriptive helper text (from [Description](./description) component)
+- **FieldError**: Validation error message display (from [FieldError](./field-error) component)
+
+## Usage
+
+### Basic Usage
+
+TextField provides a complete form input structure with label and description.
+
+```tsx
+<TextField>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description>We'll never share your email</Description>
+</TextField>
+```
+
+### With Required Field
+
+Mark fields as required to show an asterisk in the label.
+
+```tsx
+<TextField isRequired>
+  <Label>Username</Label>
+  <Input placeholder="Choose a username" />
+</TextField>
+```
+
+### With Validation
+
+Display error messages when the field is invalid.
+
+```tsx
+import { FieldError, Input, Label, TextField } from 'heroui-native';
+
+<TextField isRequired isInvalid={true}>
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <FieldError>Please enter a valid email</FieldError>
+</TextField>;
+```
+
+### With Local Invalid State Override
+
+Override the context's invalid state for individual components.
+
+```tsx
+import {
+  Description,
+  FieldError,
+  Input,
+  Label,
+  TextField,
+} from 'heroui-native';
+
+<TextField isInvalid={true}>
+  <Label isInvalid={false}>Email</Label>
+  <Input placeholder="Enter your email" isInvalid={false} />
+  <Description isInvalid={false}>
+    This shows despite input being invalid
+  </Description>
+  <FieldError>Email format is incorrect</FieldError>
+</TextField>;
+```
+
+### Multiline Input
+
+Create text areas for longer content.
+
+```tsx
+<TextField>
+  <Label>Message</Label>
+  <Input placeholder="Type your message..." multiline numberOfLines={4} />
+  <Description>Maximum 500 characters</Description>
+</TextField>
+```
+
+### Disabled State
+
+Disable the entire field to prevent interaction.
+
+```tsx
+<TextField isDisabled>
+  <Label>Disabled Field</Label>
+  <Input placeholder="Cannot edit" value="Read only value" />
+</TextField>
+```
+
+### With Variant
+
+Use different variants to style the input based on context.
+
+```tsx
+<TextField>
+  <Label>Primary Variant</Label>
+  <Input placeholder="Primary style" variant="primary" />
+</TextField>
+
+<TextField>
+  <Label>Secondary Variant</Label>
+  <Input placeholder="Secondary style" variant="secondary" />
+</TextField>
+```
+
+### Custom Styling
+
+Customize the input appearance using className.
+
+```tsx
+<TextField>
+  <Label>Custom Styled</Label>
+  <Input
+    placeholder="Custom colors"
+    className="bg-blue-50 border-blue-500 focus:border-blue-700"
+  />
+</TextField>
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Description, Input, Label, TextField } from 'heroui-native';
+import { useState } from 'react';
+import { Pressable, View } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export const TextInputContent = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+
+  return (
+    <View className="gap-4">
+      <TextField isRequired>
+        <Label>Email</Label>
+        <Input
+          placeholder="Enter your email"
+          keyboardType="email-address"
+          autoCapitalize="none"
+          value={email}
+          onChangeText={setEmail}
+        />
+        <Description>
+          We'll never share your email with anyone else.
+        </Description>
+      </TextField>
+
+      <TextField isRequired>
+        <Label>New password</Label>
+        <View className="w-full flex-row items-center">
+          <Input
+            value={password}
+            onChangeText={setPassword}
+            className="flex-1 px-10"
+            placeholder="Enter your password"
+            secureTextEntry={!isPasswordVisible}
+          />
+          <StyledIonicons
+            name="lock-closed-outline"
+            size={16}
+            className="absolute left-3.5 text-muted"
+            pointerEvents="none"
+          />
+          <Pressable
+            className="absolute right-4"
+            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
+          >
+            <StyledIonicons
+              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
+              size={16}
+              className="text-muted"
+            />
+          </Pressable>
+        </View>
+        <Description>Password must be at least 6 characters</Description>
+      </TextField>
+    </View>
+  );
+};
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text-field.tsx>).
+
+## API Reference
+
+### TextField
+
+| prop         | type                         | default     | description                                                                               |
+| ------------ | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| children     | `React.ReactNode`            | -           | Content to render inside the text field                                                   |
+| isDisabled   | `boolean`                    | `false`     | Whether the entire text field is disabled                                                 |
+| isInvalid    | `boolean`                    | `false`     | Whether the text field is in an invalid state                                             |
+| isRequired   | `boolean`                    | `false`     | Whether the text field is required (shows asterisk)                                       |
+| className    | `string`                     | -           | Custom class name for the root element                                                    |
+| animation    | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| ...ViewProps | `ViewProps`                  | -           | All standard React Native View props are supported                                        |
+
+> **Note**: For Label, Input, Description, and FieldError components, see their respective documentation:
+>
+> - [Label documentation](./label)
+> - [Input documentation](./input)
+> - [Description documentation](./description)
+> - [FieldError documentation](./field-error)
+>
+> These components automatically consume form state from TextField via the form-item-state context.
+
+## Hooks
+
+### useTextField
+
+Hook to access the TextField context values. Must be used within a `TextField` component.
+
+```tsx
+import { TextField, useTextField } from 'heroui-native';
+
+function CustomComponent() {
+  const { isDisabled, isInvalid, isRequired } = useTextField();
+
+  // Use the context values...
+}
+```
+
+#### Returns
+
+| property   | type      | description                                   |
+| ---------- | --------- | --------------------------------------------- |
+| isDisabled | `boolean` | Whether the entire text field is disabled     |
+| isInvalid  | `boolean` | Whether the text field is in an invalid state |
+| isRequired | `boolean` | Whether the text field is required            |
diff --git a/apps/docs/content/docs/en/native/components/(layout)/card.mdx b/apps/docs/content/docs/en/native/components/(layout)/card.mdx
new file mode 100644
index 0000000..fba751d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(layout)/card.mdx
@@ -0,0 +1,196 @@
+---
+title: Card
+description: Displays a card container with flexible layout sections for structured content.
+links:
+  source_native: card/card.tsx
+  styles_native: card/card.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Card } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+- **Card**: Main container that extends Surface component. Provides base card structure with configurable surface variants and handles overall layout.
+- **Card.Header**: Header section for top-aligned content like icons or badges.
+- **Card.Body**: Main content area with flex-1 that expands to fill all available space between Card.Header and Card.Footer.
+- **Card.Title**: Title text with foreground color and medium font weight.
+- **Card.Description**: Description text with muted color and smaller font size.
+- **Card.Footer**: Footer section for bottom-aligned actions like buttons.
+
+## Usage
+
+### Basic Usage
+
+The Card component creates a container with built-in sections for organized content.
+
+```tsx
+<Card>
+  <Card.Body>...</Card.Body>
+</Card>
+```
+
+### With Title and Description
+
+Combine title and description components for structured text content.
+
+```tsx
+<Card>
+  <Card.Body>
+    <Card.Title>...</Card.Title>
+    <Card.Description>...</Card.Description>
+  </Card.Body>
+</Card>
+```
+
+### With Header and Footer
+
+Add header and footer sections for icons, badges, or actions.
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>...</Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+### Variants
+
+Control the card's background appearance using different variants.
+
+```tsx
+<Card variant="default">...</Card>
+<Card variant="secondary">...</Card>
+<Card variant="tertiary">...</Card>
+<Card variant="transparent">...</Card>
+```
+
+### Horizontal Layout
+
+Create horizontal cards by using flex-row styling.
+
+```tsx
+<Card className="flex-row gap-4">
+  <Image source={...} className="size-24 rounded-lg" />
+</Card>
+```
+
+### Background Image
+
+Use an image as an absolute positioned background.
+
+```tsx
+<Card>
+  <Image source={...} className="absolute inset-0" />
+  <View className="gap-4">...</View>
+</Card>
+```
+
+## Example
+
+```tsx
+import { Button, Card } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View } from 'react-native';
+
+export default function CardExample() {
+  return (
+    <Card>
+      <View className="gap-4">
+        <Card.Body className="mb-4">
+          <View className="gap-1 mb-2">
+            <Card.Title className="text-pink-500">$450</Card.Title>
+            <Card.Title>Living room Sofa • Collection 2025</Card.Title>
+          </View>
+          <Card.Description>
+            This sofa is perfect for modern tropical spaces, baroque inspired
+            spaces.
+          </Card.Description>
+        </Card.Body>
+        <Card.Footer className="gap-3">
+          <Button variant="primary">Buy now</Button>
+          <Button variant="ghost">
+            <Button.Label>Add to cart</Button.Label>
+            <Ionicons name="bag-outline" size={16} />
+          </Button>
+        </Card.Footer>
+      </View>
+    </Card>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/card.tsx).
+
+## API Reference
+
+### Card
+
+| prop           | type                                                      | default     | description                                                                               |
+| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                         | -           | Content to be rendered inside the card                                                    |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | Visual variant of the card surface                                                        |
+| `className`    | `string`                                                  | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all" \| undefined`                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `...ViewProps` | `ViewProps`                                               | -           | All standard React Native View props are supported                                        |
+
+### Card.Header
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the header |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Body
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the body   |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Footer
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the footer |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Card.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the title text |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Card.Description
+
+| prop           | type              | default | description                                              |
+| -------------- | ----------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the description text |
+| `className`    | `string`          | -       | Additional CSS classes                                   |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported       |
diff --git a/apps/docs/content/docs/en/native/components/(layout)/separator.mdx b/apps/docs/content/docs/en/native/components/(layout)/separator.mdx
new file mode 100644
index 0000000..99d1329
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(layout)/separator.mdx
@@ -0,0 +1,116 @@
+---
+title: Separator
+description: A simple line to separate content visually.
+links:
+  source_native: separator/separator.tsx
+  styles_native: separator/separator.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/separator-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Separator } from "heroui-native";
+```
+
+## Anatomy
+
+```tsx
+<Separator />
+```
+
+- **Separator**: A simple line component that separates content visually. Can be oriented horizontally or vertically, with customizable thickness and variant styles.
+
+## Usage
+
+### Basic Usage
+
+The Separator component creates a visual separation between content sections.
+
+```tsx
+<Separator />
+```
+
+### Orientation
+
+Control the direction of the separator with the `orientation` prop.
+
+```tsx
+<View>
+  <Text>Horizontal separator</Text>
+  <Separator orientation="horizontal" />
+  <Text>Content below</Text>
+</View>
+
+<View className="h-24 flex-row">
+  <Text>Left</Text>
+  <Separator orientation="vertical" />
+  <Text>Right</Text>
+</View>
+```
+
+### Variants
+
+Choose between thin and thick variants for different visual emphasis.
+
+```tsx
+<Separator variant="thin" />
+<Separator variant="thick" />
+```
+
+### Custom Thickness
+
+Set a specific thickness value for precise control.
+
+```tsx
+<Separator thickness={1} />
+<Separator thickness={5} />
+<Separator thickness={10} />
+```
+
+## Example
+
+```tsx
+import { Separator, Surface } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function SeparatorExample() {
+  return (
+    <Surface variant="secondary" className="px-6 py-7">
+      <Text className="text-base font-medium text-foreground">
+        HeroUI Native
+      </Text>
+      <Text className="text-sm text-muted">
+        A modern React Native component library.
+      </Text>
+      <Separator className="my-4" />
+      <View className="flex-row items-center h-5">
+        <Text className="text-sm text-foreground">Components</Text>
+        <Separator orientation="vertical" className="mx-3" />
+        <Text className="text-sm text-foreground">Themes</Text>
+        <Separator orientation="vertical" className="mx-3" />
+        <Text className="text-sm text-foreground">Examples</Text>
+      </View>
+    </Surface>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/separator.tsx).
+
+## API Reference
+
+### Separator
+
+| prop           | type                         | default        | description                                                                                  |
+| -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
+| `variant`      | `'thin' \| 'thick'`          | `'thin'`       | Variant style of the separator                                                               |
+| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the separator                                                                 |
+| `thickness`    | `number`                     | `undefined`    | Custom thickness in pixels. Controls height for horizontal or width for vertical orientation |
+| `className`    | `string`                     | `undefined`    | Additional CSS classes to apply                                                              |
+| `...ViewProps` | `ViewProps`                  | -              | All standard React Native View props are supported                                           |
diff --git a/apps/docs/content/docs/en/native/components/(layout)/surface.mdx b/apps/docs/content/docs/en/native/components/(layout)/surface.mdx
new file mode 100644
index 0000000..5ed4b55
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(layout)/surface.mdx
@@ -0,0 +1,147 @@
+---
+title: Surface
+description: Container component that provides elevation and background styling.
+links:
+  source_native: surface/surface.tsx
+  styles_native: surface/surface.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/surface-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Surface } from 'heroui-native';
+```
+
+## Anatomy
+
+The Surface component is a container that provides elevation and background styling. It accepts children and can be customized with variants and styling props.
+
+```tsx
+<Surface>...</Surface>
+```
+
+- **Surface**: Main container component that provides consistent padding, background styling, and elevation through variants.
+
+## Usage
+
+### Basic Usage
+
+The Surface component creates a container with consistent padding and styling.
+
+```tsx
+<Surface>...</Surface>
+```
+
+### Variants
+
+Control the visual appearance with different surface levels.
+
+```tsx
+<Surface variant="default">
+  ...
+</Surface>
+
+<Surface variant="secondary">
+  ...
+</Surface>
+
+<Surface variant="tertiary">
+  ...
+</Surface>
+```
+
+### Nested Surfaces
+
+Create visual hierarchy by nesting surfaces with different variants.
+
+```tsx
+<Surface variant="default">
+  ...
+  <Surface variant="secondary">
+    ...
+    <Surface variant="tertiary">...</Surface>
+  </Surface>
+</Surface>
+```
+
+### Custom Styling
+
+Apply custom styles using className or style props.
+
+```tsx
+<Surface className="bg-accent-soft">
+  ...
+</Surface>
+
+<Surface variant="tertiary" className="p-0">
+  ...
+</Surface>
+```
+
+### Disable All Animations
+
+Disable all animations including children by using the `"disable-all"` value for the `animation` prop.
+
+```tsx
+{
+  /* Disable all animations including children */
+}
+<Surface animation="disable-all">No Animations</Surface>;
+```
+
+## Example
+
+```tsx
+import { Surface } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function SurfaceExample() {
+  return (
+    <View className="gap-4">
+      <Surface variant="default" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a default surface variant. It uses bg-surface styling.
+        </AppText>
+      </Surface>
+
+      <Surface variant="secondary" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a secondary surface variant. It uses bg-surface-secondary
+          styling.
+        </AppText>
+      </Surface>
+
+      <Surface variant="tertiary" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a tertiary surface variant. It uses bg-surface-tertiary
+          styling.
+        </AppText>
+      </Surface>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/surface.tsx).
+
+## API Reference
+
+### Surface
+
+| prop           | type                                                      | default     | description                                                                               |
+| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | Visual variant controlling background color and border                                    |
+| `children`     | `React.ReactNode`                                         | -           | Content to be rendered inside the surface                                                 |
+| `className`    | `string`                                                  | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all" \| undefined`                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `asChild`      | `boolean`                                                 | `false`     | Whether to render as a child element                                                      |
+| `...ViewProps` | `ViewProps`                                               | -           | All standard React Native View props are supported                                        |
diff --git a/apps/docs/content/docs/en/native/components/(media)/avatar.mdx b/apps/docs/content/docs/en/native/components/(media)/avatar.mdx
new file mode 100644
index 0000000..f32a18d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(media)/avatar.mdx
@@ -0,0 +1,396 @@
+---
+title: Avatar
+description: Displays a user avatar with support for images, text initials, or fallback icons.
+links:
+  source_native: avatar/avatar.tsx
+  styles_native: avatar/avatar.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/avatar-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Avatar } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Avatar>
+  <Avatar.Image />
+  <Avatar.Fallback />
+</Avatar>
+```
+
+- **Avatar**: Main container that manages avatar display state. Provides size and color context to child components. Supports animation configuration to control all child animations.
+- **Avatar.Image**: Optional image component that displays the avatar image. Handles loading states and errors automatically with opacity-based fade-in animation.
+- **Avatar.Fallback**: Optional fallback component shown when image fails to load or is unavailable. Displays a default person icon when no children are provided. Supports configurable entering animations with delay support.
+
+## Usage
+
+### Basic Usage
+
+The Avatar component displays a default person icon when no image or text is provided.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### With Image
+
+Display an avatar image with automatic fallback handling.
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### With Text Initials
+
+Show text initials as the avatar content.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar>
+```
+
+### With Custom Icon
+
+Provide a custom icon as fallback content.
+
+```tsx
+<Avatar>
+  <Avatar.Fallback>
+    <Ionicons name="person" size={18} />
+  </Avatar.Fallback>
+</Avatar>
+```
+
+### Sizes
+
+Control the avatar size with the size prop.
+
+```tsx
+<Avatar size="sm">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="md">
+  <Avatar.Fallback />
+</Avatar>
+
+<Avatar size="lg">
+  <Avatar.Fallback />
+</Avatar>
+```
+
+### Variants
+
+Choose between different visual styles with the `variant` prop.
+
+```tsx
+<Avatar variant="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar variant="soft">
+  <Avatar.Fallback>SF</Avatar.Fallback>
+</Avatar>
+```
+
+### Colors
+
+Apply different color variants to the avatar.
+
+```tsx
+<Avatar color="default">
+  <Avatar.Fallback>DF</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="accent">
+  <Avatar.Fallback>AC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="success">
+  <Avatar.Fallback>SC</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="warning">
+  <Avatar.Fallback>WR</Avatar.Fallback>
+</Avatar>
+
+<Avatar color="danger">
+  <Avatar.Fallback>DG</Avatar.Fallback>
+</Avatar>
+```
+
+### Delayed Fallback
+
+Show fallback after a delay to prevent flashing during image load.
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+</Avatar>
+```
+
+### Custom Image Component
+
+Use a custom image component with the asChild prop.
+
+```tsx
+import { Image } from 'expo-image';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} asChild>
+    <Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
+  </Avatar.Image>
+  <Avatar.Fallback>EI</Avatar.Fallback>
+</Avatar>;
+```
+
+### Animation Control
+
+Control animations at different levels of the Avatar component.
+
+#### Disable All Animations
+
+Disable all animations including children from the root component:
+
+```tsx
+<Avatar animation="disable-all">
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### Custom Image Animation
+
+Customize the image opacity animation:
+
+```tsx
+<Avatar>
+  <Avatar.Image
+    source={{ uri: imageUrl }}
+    animation={{
+      opacity: {
+        value: [0.3, 1],
+        timingConfig: { duration: 300 },
+      },
+    }}
+  />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+#### Custom Fallback Animation
+
+Customize the fallback entering animation:
+
+```tsx
+import { FadeInDown } from 'react-native-reanimated';
+
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} />
+  <Avatar.Fallback
+    animation={{
+      entering: {
+        value: FadeInDown.duration(400),
+      },
+    }}
+  >
+    JD
+  </Avatar.Fallback>
+</Avatar>;
+```
+
+#### Disable Individual Animations
+
+Disable animations for specific components:
+
+```tsx
+<Avatar>
+  <Avatar.Image source={{ uri: imageUrl }} animation={false} />
+  <Avatar.Fallback animation="disabled">JD</Avatar.Fallback>
+</Avatar>
+```
+
+## Example
+
+```tsx
+import { Avatar } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function AvatarExample() {
+  const users = [
+    { id: 1, image: 'https://example.com/user1.jpg', name: 'John Doe' },
+    { id: 2, image: 'https://example.com/user2.jpg', name: 'Jane Smith' },
+    { id: 3, image: 'https://example.com/user3.jpg', name: 'Bob Johnson' },
+  ];
+
+  return (
+    <View className="flex-row gap-4">
+      {users.map((user) => (
+        <Avatar key={user.id} size="lg" color="accent">
+          <Avatar.Image source={{ uri: user.image }} />
+          <Avatar.Fallback>
+            {user.name
+              .split(' ')
+              .map((n) => n[0])
+              .join('')}
+          </Avatar.Fallback>
+        </Avatar>
+      ))}
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/avatar.tsx).
+
+## API Reference
+
+### Avatar
+
+| prop           | type                                                          | default     | description                                                                               |
+| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                                             | -           | Avatar content (Image and/or Fallback components)                                         |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Size of the avatar                                                                        |
+| `variant`      | `'default' \| 'soft'`                                         | `'default'` | Visual variant of the avatar                                                              |
+| `color`        | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | Color variant of the avatar                                                               |
+| `className`    | `string`                                                      | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all"` \| `undefined`                                | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `alt`          | `string`                                                      | `'Avatar'`  | Alternative text description for accessibility                                            |
+| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                                        |
+
+### Avatar.Image
+
+Props extend different base types depending on the `asChild` prop value:
+
+- When `asChild={false}` (default): extends `AnimatedProps<ImageProps>` from React Native Reanimated
+- When `asChild={true}`: extends primitive image props for custom image components
+
+**Note:** When using `asChild={true}` with custom image components, the `className` prop may not be applied in some cases depending on the custom component's implementation. Ensure your custom component properly handles style props.
+
+| prop                    | type                                           | default | description                                                  |
+| ----------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
+| `source`                | `ImageSourcePropType`                          | -       | Image source (required when `asChild={false}`)               |
+| `asChild`               | `boolean`                                      | `false` | Whether to use a custom image component as child             |
+| `className`             | `string`                                       | -       | Additional CSS classes to apply                              |
+| `animation`             | `AvatarImageAnimation`                         | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                      | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...AnimatedProps`      | `AnimatedProps<ImageProps>` or primitive props | -       | Additional props based on `asChild` value                    |
+
+#### AvatarImageAnimation
+
+Animation configuration for avatar image component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                   | type                    | default                                             | description                                          |
+| ---------------------- | ----------------------- | --------------------------------------------------- | ---------------------------------------------------- |
+| `state`                | `'disabled' \| boolean` | -                                                   | Disable animations while customizing properties      |
+| `opacity.value`        | `[number, number]`      | `[0, 1]`                                            | Opacity values [initial, loaded] for image animation |
+| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200, easing: Easing.in(Easing.ease) }` | Animation timing configuration                       |
+
+**Note:** Animation is automatically disabled when `asChild={true}`
+
+### Avatar.Fallback
+
+| prop                    | type                                                          | default               | description                                                                       |
+| ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                                             | -                     | Fallback content (text, icon, or custom element)                                  |
+| `delayMs`               | `number`                                                      | `0`                   | Delay in milliseconds before showing the fallback (applied to entering animation) |
+| `color`                 | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | Color variant of the fallback                                                     |
+| `className`             | `string`                                                      | -                     | Additional CSS classes for the container                                          |
+| `classNames`            | `ElementSlots<AvatarFallbackSlots>`                           | -                     | Additional CSS classes for different parts                                        |
+| `styles`                | `{ container?: ViewStyle; text?: TextStyle }`                 | -                     | Styles for different parts of the avatar fallback                                 |
+| `textProps`             | `TextProps`                                                   | -                     | Props to pass to Text component when children is a string                         |
+| `iconProps`             | `PersonIconProps`                                             | -                     | Props to customize the default person icon                                        |
+| `animation`             | `AvatarFallbackAnimation`                                     | -                     | Animation configuration                                                           |
+| `...Animated.ViewProps` | `Animated.ViewProps`                                          | -                     | All Reanimated Animated.View props are supported                                  |
+
+**classNames prop:** `ElementSlots<AvatarFallbackSlots>` provides type-safe CSS classes for different parts of the fallback component. Available slots: `container`, `text`.
+
+#### `styles`
+
+| prop        | type        | description                 |
+| ----------- | ----------- | --------------------------- |
+| `container` | `ViewStyle` | Styles for the container    |
+| `text`      | `TextStyle` | Styles for the text content |
+
+#### AvatarFallbackAnimation
+
+Animation configuration for avatar fallback component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                    | default                                                                             | description                                     |
+| ---------------- | ----------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| boolean` | -                                                                                   | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))`<br/>`.delay(0)` | Custom entering animation for fallback          |
+
+#### PersonIconProps
+
+| prop    | type     | description                           |
+| ------- | -------- | ------------------------------------- |
+| `size`  | `number` | Size of the icon in pixels (optional) |
+| `color` | `string` | Color of the icon (optional)          |
+
+## Hooks
+
+### useAvatar Hook
+
+Hook to access Avatar primitive root context. Provides access to avatar status.
+
+**Note:** The `status` property is particularly useful for adding a skeleton loader while the image is loading.
+
+```tsx
+import { Avatar, useAvatar, Skeleton } from 'heroui-native';
+
+function AvatarWithSkeleton() {
+  return (
+    <Avatar>
+      <Avatar.Image source={{ uri: imageUrl }} />
+      <AvatarContent />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar>
+  );
+}
+
+function AvatarContent() {
+  const { status } = useAvatar();
+
+  if (status === 'loading') {
+    return <Skeleton className="absolute inset-0 rounded-full" />;
+  }
+
+  return null;
+}
+```
+
+| property    | type                                                 | description                                                 |
+| ----------- | ---------------------------------------------------- | ----------------------------------------------------------- |
+| `status`    | `'loading' \| 'loaded' \| 'error'`                   | Current loading state of the avatar image.                  |
+| `setStatus` | `(status: 'loading' \| 'loaded' \| 'error') => void` | Function to manually set the avatar status (advanced usage) |
+
+**Status Values:**
+
+- `'loading'`: Image is currently being loaded. Use this state to show a skeleton loader.
+- `'loaded'`: Image has successfully loaded.
+- `'error'`: Image failed to load or source is invalid. The fallback component is automatically shown in this state.
diff --git a/apps/docs/content/docs/en/native/components/(navigation)/accordion.mdx b/apps/docs/content/docs/en/native/components/(navigation)/accordion.mdx
new file mode 100644
index 0000000..2bdaad8
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(navigation)/accordion.mdx
@@ -0,0 +1,447 @@
+---
+title: Accordion
+description: A collapsible content panel for organizing information in a compact space
+links:
+  source_native: accordion/accordion.tsx
+  styles_native: accordion/accordion.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/accordion-docs-dark-1.mp4"
+/>
+
+## Import
+
+```tsx
+import { Accordion } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Accordion>
+  <Accordion.Item>
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator>...</Accordion.Indicator>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+- **Accordion**: Main container that manages the accordion state and behavior. Controls expansion/collapse of items, supports single or multiple selection modes, and provides variant styling (default or surface).
+- **Accordion.Item**: Container for individual accordion items. Wraps the trigger and content, managing the expanded state for each item.
+- **Accordion.Trigger**: Interactive element that toggles item expansion. Built on Header and Trigger primitives.
+- **Accordion.Indicator**: Optional visual indicator showing expansion state. Defaults to an animated chevron icon that rotates based on item state.
+- **Accordion.Content**: Container for expandable content. Animated with layout transitions for smooth expand/collapse effects.
+
+## Usage
+
+### Basic Usage
+
+The Accordion component uses compound parts to create expandable content sections.
+
+```tsx
+<Accordion selectionMode="single">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Single Selection Mode
+
+Allow only one item to be expanded at a time.
+
+```tsx
+<Accordion selectionMode="single" defaultValue="2">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Multiple Selection Mode
+
+Allow multiple items to be expanded simultaneously.
+
+```tsx
+<Accordion selectionMode="multiple" defaultValue={['1', '3']}>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="3">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Surface Variant
+
+Apply a surface container style to the accordion.
+
+```tsx
+<Accordion selectionMode="single" variant="surface">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Custom Indicator
+
+Replace the default chevron indicator with custom content.
+
+```tsx
+<Accordion selectionMode="single">
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      ...
+      <Accordion.Indicator>
+        <CustomIndicator />
+      </Accordion.Indicator>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Without Separators
+
+Hide the separators between accordion items.
+
+```tsx
+<Accordion selectionMode="single" hideSeparator>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Custom Styling
+
+Apply custom styles using className, classNames, or styles props.
+
+```tsx
+<Accordion
+  className="rounded-lg"
+  classNames={{
+    container: 'bg-surface',
+    separator: 'bg-separator/50',
+  }}
+  styles={{
+    container: { padding: 16 },
+    separator: { height: 2 },
+  }}
+>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>...</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### With PressableFeedback
+
+Use `Accordion.Trigger` with `asChild` prop and wrap content with `PressableFeedback` to add custom press feedback animations.
+
+```tsx
+import { Accordion, PressableFeedback } from 'heroui-native';
+import { View } from 'react-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger asChild>
+      <PressableFeedback animation={{ scale: false }}>
+        <PressableFeedback.Scale className="flex-row items-center flex-1 gap-3">
+          <Text>Item Title</Text>
+        </PressableFeedback.Scale>
+        <Accordion.Indicator />
+        <PressableFeedback.Highlight
+          animation={{ opacity: { value: [0, 0.05] } }}
+        />
+      </PressableFeedback>
+    </Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>;
+```
+
+## Example
+
+```tsx
+import { Accordion, useThemeColor } from 'heroui-native';
+import { Ionicons } from '@expo/vector-icons';
+import { View, Text } from 'react-native';
+
+export default function AccordionExample() {
+  const themeColorMuted = useThemeColor('muted');
+
+  const accordionData = [
+    {
+      id: '1',
+      title: 'How do I place an order?',
+      icon: <Ionicons name="bag-outline" size={16} color={themeColorMuted} />,
+      content:
+        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
+    },
+    {
+      id: '2',
+      title: 'What payment methods do you accept?',
+      icon: <Ionicons name="card-outline" size={16} color={themeColorMuted} />,
+      content:
+        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
+    },
+    {
+      id: '3',
+      title: 'How much does shipping cost?',
+      icon: <Ionicons name="cube-outline" size={16} color={themeColorMuted} />,
+      content:
+        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
+    },
+  ];
+
+  return (
+    <Accordion selectionMode="single" variant="surface" defaultValue="2">
+      {accordionData.map((item) => (
+        <Accordion.Item key={item.id} value={item.id}>
+          <Accordion.Trigger>
+            <View className="flex-row items-center flex-1 gap-3">
+              {item.icon}
+              <Text className="text-foreground text-base flex-1">
+                {item.title}
+              </Text>
+            </View>
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+          <Accordion.Content>
+            <Text className="text-muted text-base/relaxed px-[25px]">
+              {item.content}
+            </Text>
+          </Accordion.Content>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/accordion.tsx).
+
+## API Reference
+
+### Accordion
+
+| prop                    | type                                               | default     | description                                                    |
+| ----------------------- | -------------------------------------------------- | ----------- | -------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                                  | -           | Children elements to be rendered inside the accordion          |
+| `selectionMode`         | `'single' \| 'multiple'`                           | -           | Whether the accordion allows single or multiple expanded items |
+| `variant`               | `'default' \| 'surface'`                           | `'default'` | Visual variant of the accordion                                |
+| `hideSeparator`         | `boolean`                                          | `false`     | Whether to hide the separator between accordion items          |
+| `defaultValue`          | `string \| string[] \| undefined`                  | -           | Default expanded item(s) in uncontrolled mode                  |
+| `value`                 | `string \| string[] \| undefined`                  | -           | Controlled expanded item(s)                                    |
+| `isDisabled`            | `boolean`                                          | -           | Whether all accordion items are disabled                       |
+| `isCollapsible`         | `boolean`                                          | `true`      | Whether expanded items can be collapsed                        |
+| `animation`             | `AccordionRootAnimation`                           | -           | Animation configuration for accordion                          |
+| `className`             | `string`                                           | -           | Additional CSS classes for the container                       |
+| `classNames`            | `ElementSlots<RootSlots>`                          | -           | Additional CSS classes for the slots                           |
+| `styles`                | `Partial<Record<RootSlots, ViewStyle>>`            | -           | Styles for different parts of the accordion root               |
+| `onValueChange`         | `(value: string \| string[] \| undefined) => void` | -           | Callback when expanded items change                            |
+| `...Animated.ViewProps` | `Animated.ViewProps`                               | -           | All Reanimated Animated.View props are supported               |
+
+#### `ElementSlots<RootSlots>`
+
+| prop        | type     | description                                       |
+| ----------- | -------- | ------------------------------------------------- |
+| `container` | `string` | Custom class name for the accordion container     |
+| `separator` | `string` | Custom class name for the separator between items |
+
+#### `styles`
+
+| prop        | type        | description                            |
+| ----------- | ----------- | -------------------------------------- |
+| `container` | `ViewStyle` | Styles for the accordion container     |
+| `separator` | `ViewStyle` | Styles for the separator between items |
+
+#### AccordionRootAnimation
+
+Animation configuration for accordion root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop           | type                                     | default                                                                                         | description                                       |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `state`        | `'disabled' \| 'disable-all' \| boolean` | -                                                                                               | Disable animations while customizing properties   |
+| `layout.value` | `LayoutTransition`                       | `LinearTransition`<br/>`.springify()`<br/>`.damping(140)`<br/>`.stiffness(1600)`<br/>`.mass(4)` | Custom layout animation for accordion transitions |
+
+### Accordion.Item
+
+| prop                    | type                                                                        | default | description                                                                      |
+| ----------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode \| ((props: AccordionItemRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the accordion item, or a render function |
+| `value`                 | `string`                                                                    | -       | Unique value to identify this item                                               |
+| `isDisabled`            | `boolean`                                                                   | -       | Whether this specific item is disabled                                           |
+| `className`             | `string`                                                                    | -       | Additional CSS classes                                                           |
+| `...Animated.ViewProps` | `Animated.ViewProps`                                                        | -       | All Reanimated Animated.View props are supported                                 |
+
+#### AccordionItemRenderProps
+
+| prop         | type      | description                                      |
+| ------------ | --------- | ------------------------------------------------ |
+| `isExpanded` | `boolean` | Whether the accordion item is currently expanded |
+| `value`      | `string`  | Unique value identifier for this accordion item  |
+
+### Accordion.Trigger
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | Children elements to be rendered inside the trigger     |
+| `className`         | `string`          | -       | Additional CSS classes                                  |
+| `isDisabled`        | `boolean`         | -       | Whether the trigger is disabled                         |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+### Accordion.Indicator
+
+| prop                    | type                          | default | description                                                            |
+| ----------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`             | -       | Custom indicator content, if not provided defaults to animated chevron |
+| `className`             | `string`                      | -       | Additional CSS classes                                                 |
+| `iconProps`             | `AccordionIndicatorIconProps` | -       | Icon configuration                                                     |
+| `animation`             | `AccordionIndicatorAnimation` | -       | Animation configuration for indicator                                  |
+| `isAnimatedStyleActive` | `boolean`                     | `true`  | Whether animated styles (react-native-reanimated) are active           |
+| `...Animated.ViewProps` | `Animated.ViewProps`          | -       | All Reanimated Animated.View props are supported                       |
+
+#### AccordionIndicatorIconProps
+
+| prop    | type     | default      | description       |
+| ------- | -------- | ------------ | ----------------- |
+| `size`  | `number` | `16`         | Size of the icon  |
+| `color` | `string` | `foreground` | Color of the icon |
+
+#### AccordionIndicatorAnimation
+
+Animation configuration for accordion indicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                    | type                    | default                                      | description                                      |
+| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------ |
+| `state`                 | `'disabled' \| boolean` | -                                            | Disable animations while customizing properties  |
+| `rotation.value`        | `[number, number]`      | `[0, -180]`                                  | Rotation values [collapsed, expanded] in degrees |
+| `rotation.springConfig` | `WithSpringConfig`      | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring animation configuration for rotation      |
+
+### Accordion.Content
+
+| prop           | type                        | default | description                                         |
+| -------------- | --------------------------- | ------- | --------------------------------------------------- |
+| `children`     | `React.ReactNode`           | -       | Children elements to be rendered inside the content |
+| `className`    | `string`                    | -       | Additional CSS classes                              |
+| `animation`    | `AccordionContentAnimation` | -       | Animation configuration for content                 |
+| `...ViewProps` | `ViewProps`                 | -       | All standard React Native View props are supported  |
+
+#### AccordionContentAnimation
+
+Animation configuration for accordion content component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop             | type                    | default                                                              | description                                     |
+| ---------------- | ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`          | `'disabled' \| boolean` | -                                                                    | Disable animations while customizing properties |
+| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br/>`.duration(200)`<br/>`.easing(Easing.out(Easing.ease))` | Custom entering animation for content           |
+| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br/>`.duration(200)`<br/>`.easing(Easing.in(Easing.ease))` | Custom exiting animation for content            |
+
+## Hooks
+
+### useAccordion
+
+Hook to access the accordion root context. Must be used within an `Accordion` component.
+
+```tsx
+import { useAccordion } from 'heroui-native';
+
+const { value, onValueChange, selectionMode, isCollapsible, isDisabled } =
+  useAccordion();
+```
+
+#### Returns
+
+| property        | type                                                                  | description                                                                  |
+| --------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `selectionMode` | `'single' \| 'multiple' \| undefined`                                 | Whether the accordion allows single or multiple expanded items               |
+| `value`         | `(string \| undefined) \| string[]`                                   | Currently expanded item(s) - string for single mode, array for multiple mode |
+| `onValueChange` | `(value: string \| undefined) => void \| ((value: string[]) => void)` | Callback function to update expanded items                                   |
+| `isCollapsible` | `boolean`                                                             | Whether expanded items can be collapsed                                      |
+| `isDisabled`    | `boolean \| undefined`                                                | Whether all accordion items are disabled                                     |
+
+### useAccordionItem
+
+Hook to access the accordion item context. Must be used within an `Accordion.Item` component.
+
+```tsx
+import { useAccordionItem } from 'heroui-native';
+
+const { value, isExpanded, isDisabled, nativeID } = useAccordionItem();
+```
+
+#### Returns
+
+| property     | type                   | description                                          |
+| ------------ | ---------------------- | ---------------------------------------------------- |
+| `value`      | `string`               | Unique value identifier for this accordion item      |
+| `isExpanded` | `boolean`              | Whether the accordion item is currently expanded     |
+| `isDisabled` | `boolean \| undefined` | Whether this specific item is disabled               |
+| `nativeID`   | `string`               | Native ID used for accessibility and ARIA attributes |
+
+## Special Notes
+
+When using the Accordion component alongside other components in the same view, you should import and apply `AccordionLayoutTransition` to those components to ensure smooth and consistent layout animations across the entire screen.
+
+```jsx
+import { Accordion, AccordionLayoutTransition } from 'heroui-native';
+import Animated from 'react-native-reanimated';
+
+<Animated.ScrollView layout={AccordionLayoutTransition}>
+  <Animated.View layout={AccordionLayoutTransition}>
+    {/* Other content */}
+  </Animated.View>
+
+  <Accordion>{/* Accordion items */}</Accordion>
+</Animated.ScrollView>;
+```
+
+This ensures that when the accordion expands or collapses, all components on the screen animate with the same timing and easing, creating a cohesive user experience.
diff --git a/apps/docs/content/docs/en/native/components/(navigation)/list-group.mdx b/apps/docs/content/docs/en/native/components/(navigation)/list-group.mdx
new file mode 100644
index 0000000..e82c998
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(navigation)/list-group.mdx
@@ -0,0 +1,397 @@
+---
+title: ListGroup
+description: A Surface-based container that groups related list items with consistent layout and spacing.
+links:
+  source_native: list-group/list-group.tsx
+  styles_native: list-group/list-group.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { ListGroup } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>...</ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>...</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>...</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+- **ListGroup**: Surface-based root container that groups related list items. Supports all Surface variants (default, secondary, tertiary, transparent).
+- **ListGroup.Item**: Pressable horizontal flex-row container for a single item, providing consistent spacing and alignment.
+- **ListGroup.ItemPrefix**: Optional leading content slot for icons, avatars, or other visual elements.
+- **ListGroup.ItemContent**: Flex-1 wrapper for title and description, occupying the remaining horizontal space.
+- **ListGroup.ItemTitle**: Primary text label styled with foreground color and medium font weight.
+- **ListGroup.ItemDescription**: Secondary text styled with muted color and smaller font size.
+- **ListGroup.ItemSuffix**: Optional trailing content slot. Renders a chevron-right icon by default; accepts children to override the default icon.
+
+## Usage
+
+### Basic Usage
+
+The ListGroup component uses compound parts to create grouped list items with title and description.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Personal Info</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Name, email, phone number
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Payment Methods</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Visa ending in 4829
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### With Icons
+
+Add leading icons using the `ListGroup.ItemPrefix` slot.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="person-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Profile</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Name, photo, bio
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="lock-closed-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Security</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Password, 2FA
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Title Only
+
+Omit `ListGroup.ItemDescription` to display title-only items.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="wifi-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="bluetooth-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Bluetooth</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Surface Variant
+
+Apply a different visual variant to the root container.
+
+```tsx
+<ListGroup variant="transparent">
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Custom Suffix
+
+Override the default chevron icon by passing children to `ListGroup.ItemSuffix`.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Language</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>English</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Icon name="arrow-forward" size={18} />
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Chip variant="primary" color="danger">
+        <Chip.Label className="font-bold">7</Chip.Label>
+      </Chip>
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Custom Suffix Icon Props
+
+Customise the default chevron icon size and color using `iconProps`.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Storage</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        12.4 GB of 50 GB used
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### With PressableFeedback
+
+Wrap items with `PressableFeedback` to add scale and ripple press feedback animations. When using this pattern, pass `onPress` on `PressableFeedback` instead of `ListGroup.Item` and disable the item with `disabled` prop.
+
+```tsx
+import { ListGroup, PressableFeedback, Separator } from 'heroui-native';
+
+<ListGroup>
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Appearance</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            Theme, font size, display
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+  <Separator className="mx-4" />
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            Alerts, sounds, badges
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+</ListGroup>
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { ListGroup, Separator, useThemeColor } from 'heroui-native';
+import { View, Text } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function ListGroupExample() {
+  const mutedColor = useThemeColor('muted');
+
+  return (
+    <View className="flex-1 justify-center px-5">
+      <Text className="text-sm text-muted mb-2 ml-2">Account</Text>
+      <ListGroup className="mb-6">
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="person-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Personal Info</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Name, email, phone number
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="card-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Payment Methods</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Visa ending in 4829
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+      </ListGroup>
+      <Text className="text-sm text-muted mb-2 ml-2">Preferences</Text>
+      <ListGroup>
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="color-palette-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Appearance</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Theme, font size, display
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="notifications-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Alerts, sounds, badges
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+        </ListGroup.Item>
+      </ListGroup>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/list-group.tsx).
+
+## API Reference
+
+### ListGroup
+
+| prop           | type                                                       | default     | description                                        |
+| -------------- | ---------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                          | -           | Children elements to be rendered inside the group  |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | Visual variant of the underlying Surface container |
+| `className`    | `string`                                                   | -           | Additional CSS classes for the root container      |
+| `...ViewProps` | `ViewProps`                                                | -           | All standard React Native View props are supported |
+
+### ListGroup.Item
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | Children elements to be rendered inside the item        |
+| `className`         | `string`          | -       | Additional CSS classes for the item                     |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+### ListGroup.ItemPrefix
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Leading content such as icons or avatars               |
+| `className`    | `string`          | -       | Additional CSS classes for the prefix                  |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported     |
+
+### ListGroup.ItemContent
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Content area, typically title and description          |
+| `className`    | `string`          | -       | Additional CSS classes for the content area            |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported     |
+
+### ListGroup.ItemTitle
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title text or custom content                       |
+| `className`    | `string`          | -       | Additional CSS classes for the title               |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### ListGroup.ItemDescription
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description text or custom content                 |
+| `className`    | `string`          | -       | Additional CSS classes for the description         |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### ListGroup.ItemSuffix
+
+| prop           | type                 | default | description                                                                        |
+| -------------- | -------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`    | -       | Custom trailing content; overrides the default chevron-right icon when provided    |
+| `className`    | `string`             | -       | Additional CSS classes for the suffix                                              |
+| `iconProps`    | `ListGroupIconProps` | -       | Props to customise the default chevron-right icon. Only applies when no children   |
+| `...ViewProps` | `ViewProps`          | -       | All standard React Native View props are supported                                 |
+
+#### ListGroupIconProps
+
+| prop    | type     | default             | description                        |
+| ------- | -------- | ------------------- | ---------------------------------- |
+| `size`  | `number` | `16`                | Size of the chevron icon in pixels |
+| `color` | `string` | theme `muted` color | Color of the chevron icon          |
diff --git a/apps/docs/content/docs/en/native/components/(navigation)/tabs.mdx b/apps/docs/content/docs/en/native/components/(navigation)/tabs.mdx
new file mode 100644
index 0000000..8d15b14
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(navigation)/tabs.mdx
@@ -0,0 +1,575 @@
+---
+title: Tabs
+description: Organize content into tabbed views with animated transitions and indicators.
+links:
+  source_native: tabs/tabs.tsx
+  styles_native: tabs/tabs.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tabs-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Tabs } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Tabs>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger>
+        <Tabs.Label>...</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator />
+      <Tabs.Trigger>
+        <Tabs.Label>...</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content>...</Tabs.Content>
+</Tabs>
+```
+
+- **Tabs**: Main container that manages tab state and selection. Controls active tab, handles value changes, and provides context to child components.
+- **Tabs.List**: Container for tab triggers. Groups triggers together with optional styling variants (primary or secondary).
+- **Tabs.ScrollView**: Optional scrollable wrapper for tab triggers. Enables horizontal scrolling when tabs overflow with automatic centering of active tab.
+- **Tabs.Trigger**: Interactive button for each tab. Handles press events to change active tab and measures its position for indicator animation.
+- **Tabs.Label**: Text content for tab triggers. Displays the tab title with appropriate styling.
+- **Tabs.Indicator**: Animated visual indicator for active tab. Smoothly transitions between tabs using spring or timing animations.
+- **Tabs.Separator**: Visual separator between tabs. Shows when the current tab value is not in the `betweenValues` array, with animated opacity transitions.
+- **Tabs.Content**: Container for tab panel content. Shows content when its value matches the active tab.
+
+## Usage
+
+### Basic Usage
+
+The Tabs component uses compound parts to create navigable content sections.
+
+```tsx
+<Tabs value="tab1" onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="tab1">
+      <Tabs.Label>Tab 1</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="tab2">
+      <Tabs.Label>Tab 2</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="tab1">...</Tabs.Content>
+  <Tabs.Content value="tab2">...</Tabs.Content>
+</Tabs>
+```
+
+### Primary Variant
+
+Default rounded primary style for tab triggers.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="settings">
+      <Tabs.Label>Settings</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="profile">
+      <Tabs.Label>Profile</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="settings">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+### Secondary Variant
+
+Underline style indicator for a more minimal appearance.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab} variant="secondary">
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="overview">
+      <Tabs.Label>Overview</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="analytics">
+      <Tabs.Label>Analytics</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="overview">...</Tabs.Content>
+  <Tabs.Content value="analytics">...</Tabs.Content>
+</Tabs>
+```
+
+### Scrollable Tabs
+
+Handle many tabs with horizontal scrolling.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView scrollAlign="center">
+      <Tabs.Indicator />
+      <Tabs.Trigger value="tab1">
+        <Tabs.Label>First Tab</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab2">
+        <Tabs.Label>Second Tab</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab3">
+        <Tabs.Label>Third Tab</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab4">
+        <Tabs.Label>Fourth Tab</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Trigger value="tab5">
+        <Tabs.Label>Fifth Tab</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content value="tab1">...</Tabs.Content>
+  <Tabs.Content value="tab2">...</Tabs.Content>
+  <Tabs.Content value="tab3">...</Tabs.Content>
+  <Tabs.Content value="tab4">...</Tabs.Content>
+  <Tabs.Content value="tab5">...</Tabs.Content>
+</Tabs>
+```
+
+### Disabled Tabs
+
+Disable specific tabs to prevent interaction.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="active">
+      <Tabs.Label>Active</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="disabled" isDisabled>
+      <Tabs.Label>Disabled</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="another">
+      <Tabs.Label>Another</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="active">...</Tabs.Content>
+  <Tabs.Content value="another">...</Tabs.Content>
+</Tabs>
+```
+
+### With Icons
+
+Combine icons with labels for enhanced visual context.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="home">
+      <Icon name="home" size={16} />
+      <Tabs.Label>Home</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="search">
+      <Icon name="search" size={16} />
+      <Tabs.Label>Search</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="home">...</Tabs.Content>
+  <Tabs.Content value="search">...</Tabs.Content>
+</Tabs>
+```
+
+### With Render Function
+
+Use a render function on `Tabs.Trigger` to access state and customize content based on selection.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="settings">
+      {({ isSelected, value, isDisabled }) => (
+        <Tabs.Label
+          className={isSelected ? 'text-accent font-medium' : 'text-foreground'}
+        >
+          Settings
+        </Tabs.Label>
+      )}
+    </Tabs.Trigger>
+    <Tabs.Trigger value="profile">
+      {({ isSelected }) => (
+        <>
+          <Icon name="user" size={16} />
+          <Tabs.Label className={isSelected ? 'text-accent' : 'text-muted'}>
+            Profile
+          </Tabs.Label>
+        </>
+      )}
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="settings">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+### With Separators
+
+Add visual separators between tabs that show when the active tab is not between specified values.
+
+```tsx
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger value="general">
+        <Tabs.Label>General</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={['general', 'notifications']} />
+      <Tabs.Trigger value="notifications">
+        <Tabs.Label>Notifications</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={['notifications', 'profile']} />
+      <Tabs.Trigger value="profile">
+        <Tabs.Label>Profile</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+  <Tabs.Content value="general">...</Tabs.Content>
+  <Tabs.Content value="notifications">...</Tabs.Content>
+  <Tabs.Content value="profile">...</Tabs.Content>
+</Tabs>
+```
+
+## Example
+
+```tsx
+import {
+  Button,
+  Checkbox,
+  Description,
+  ControlField,
+  Label,
+  Tabs,
+  TextField,
+} from 'heroui-native';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+import Animated, {
+  FadeIn,
+  FadeOut,
+  LinearTransition,
+} from 'react-native-reanimated';
+
+const AnimatedContentContainer = ({
+  children,
+}: {
+  children: React.ReactNode;
+}) => (
+  <Animated.View
+    entering={FadeIn.duration(200)}
+    exiting={FadeOut.duration(200)}
+    className="gap-6"
+  >
+    {children}
+  </Animated.View>
+);
+
+export default function TabsExample() {
+  const [activeTab, setActiveTab] = useState('general');
+
+  const [showSidebar, setShowSidebar] = useState(true);
+  const [accountActivity, setAccountActivity] = useState(true);
+  const [name, setName] = useState('');
+
+  return (
+    <Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
+      <Tabs.List>
+        <Tabs.ScrollView>
+          <Tabs.Indicator />
+          <Tabs.Trigger value="general">
+            <Tabs.Label>General</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="notifications">
+            <Tabs.Label>Notifications</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="profile">
+            <Tabs.Label>Profile</Tabs.Label>
+          </Tabs.Trigger>
+        </Tabs.ScrollView>
+      </Tabs.List>
+
+      <Animated.View
+        layout={LinearTransition.duration(200)}
+        className="px-4 py-6 border border-border rounded-xl"
+      >
+        <Tabs.Content value="general">
+          <AnimatedContentContainer>
+            <ControlField
+              isSelected={showSidebar}
+              onSelectedChange={setShowSidebar}
+            >
+              <ControlField.Indicator variant="checkbox" />
+              <View className="flex-1">
+                <Label>Show sidebar</Label>
+                <Description>Display the sidebar navigation panel</Description>
+              </View>
+            </ControlField>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+
+        <Tabs.Content value="notifications">
+          <AnimatedContentContainer>
+            <ControlField
+              isSelected={accountActivity}
+              onSelectedChange={setAccountActivity}
+            >
+              <ControlField.Indicator variant="checkbox" />
+              <View className="flex-1">
+                <Label>Account activity</Label>
+                <Description>
+                  Notifications about your account activity
+                </Description>
+              </View>
+            </ControlField>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+
+        <Tabs.Content value="profile">
+          <AnimatedContentContainer>
+            <TextField isRequired>
+              <Label>Name</Label>
+              <Input
+                value={name}
+                onChangeText={setName}
+                placeholder="Enter your full name"
+              />
+            </TextField>
+            <Button size="sm" className="self-start">
+              <Button.Label>Update profile</Button.Label>
+            </Button>
+          </AnimatedContentContainer>
+        </Tabs.Content>
+      </Animated.View>
+    </Tabs>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/tabs.tsx>).
+
+## API Reference
+
+### Tabs
+
+| prop            | type                         | default     | description                                                                               |
+| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `children`      | `React.ReactNode`            | -           | Children elements to be rendered inside tabs                                              |
+| `value`         | `string`                     | -           | Currently active tab value                                                                |
+| `variant`       | `'primary' \| 'secondary'`   | `'primary'` | Visual variant of the tabs                                                                |
+| `className`     | `string`                     | -           | Additional CSS classes for the container                                                  |
+| `animation`     | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `onValueChange` | `(value: string) => void`    | -           | Callback when the active tab changes                                                      |
+| `...ViewProps`  | `ViewProps`                  | -           | All standard React Native View props are supported                                        |
+
+### Tabs.List
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the list   |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### Tabs.ScrollView
+
+| prop                        | type                                     | default    | description                                              |
+| --------------------------- | ---------------------------------------- | ---------- | -------------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -          | Children elements to be rendered inside the scroll view  |
+| `scrollAlign`               | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | Scroll alignment variant for the selected item           |
+| `className`                 | `string`                                 | -          | Additional CSS classes for the scroll view               |
+| `contentContainerClassName` | `string`                                 | -          | Additional CSS classes for the content container         |
+| `...ScrollViewProps`        | `ScrollViewProps`                        | -          | All standard React Native ScrollView props are supported |
+
+### Tabs.Trigger
+
+| prop                | type                                                                      | default | description                                                               |
+| ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
+| `children`          | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the trigger, or a render function |
+| `value`             | `string`                                                                  | -       | The unique value identifying this tab                                     |
+| `isDisabled`        | `boolean`                                                                 | `false` | Whether the trigger is disabled                                           |
+| `className`         | `string`                                                                  | -       | Additional CSS classes                                                    |
+| `...PressableProps` | `PressableProps`                                                          | -       | All standard React Native Pressable props are supported                   |
+
+#### TabsTriggerRenderProps
+
+When using a render function for `children`, the following props are provided:
+
+| property     | type      | description                                |
+| ------------ | --------- | ------------------------------------------ |
+| `isSelected` | `boolean` | Whether this trigger is currently selected |
+| `value`      | `string`  | The value of the trigger                   |
+| `isDisabled` | `boolean` | Whether the trigger is disabled            |
+
+### Tabs.Label
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Text content to be rendered as label               |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Tabs.Indicator
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`        | -       | Custom indicator content                                     |
+| `className`             | `string`                 | -       | Additional CSS classes                                       |
+| `animation`             | `TabsIndicatorAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported             |
+
+#### TabsIndicatorAnimation
+
+Animation configuration for Tabs.Indicator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                | type                                   | default                                                                      | description                                     |
+| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`             | `'disabled' \| boolean`                | -                                                                            | Disable animations while customizing properties |
+| `width.type`        | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
+| `width.config`      | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
+| `height.type`       | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
+| `height.config`     | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
+| `translateX.type`   | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
+| `translateX.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
+
+### Tabs.Separator
+
+| prop                    | type                     | default | description                                                                                                                            |
+| ----------------------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `betweenValues`         | `string[]`               | -       | Array of tab values between which the separator should be visible. The separator shows when the current tab value is NOT in this array |
+| `isAlwaysVisible`       | `boolean`                | `false` | If true, opacity is always 1 regardless of the current tab value                                                                       |
+| `className`             | `string`                 | -       | Additional CSS classes                                                                                                                 |
+| `animation`             | `TabsSeparatorAnimation` | -       | Animation configuration                                                                                                                |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active                                                                           |
+| `children`              | `React.ReactNode`        | -       | Custom separator content                                                                                                               |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported                                                                                       |
+
+**Note:** The following style properties are occupied by animations and cannot be set via className:
+
+- `opacity` - Animated for separator visibility transitions (0 when current tab is in `betweenValues`, 1 when not)
+
+To customize these properties, use the `animation` prop. To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+
+#### TabsSeparatorAnimation
+
+Animation configuration for Tabs.Separator component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                   | type                    | default             | description                                     |
+| ---------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
+| `state`                | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
+| `opacity.value`        | `[number, number]`      | `[0, 1]`            | Opacity values [hidden, visible]                |
+| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200 }` | Animation timing configuration                  |
+
+### Tabs.Content
+
+| prop           | type              | default | description                                         |
+| -------------- | ----------------- | ------- | --------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the content |
+| `value`        | `string`          | -       | The value of the tab this content belongs to        |
+| `className`    | `string`          | -       | Additional CSS classes                              |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported  |
+
+## Hooks
+
+### useTabs
+
+Hook to access tabs root context values within custom components or compound components.
+
+```tsx
+import { useTabs } from 'heroui-native';
+
+const CustomComponent = () => {
+  const { value, onValueChange, nativeID } = useTabs();
+  // ... your implementation
+};
+```
+
+**Returns:** `UseTabsReturn`
+
+| property        | type                      | description                                |
+| --------------- | ------------------------- | ------------------------------------------ |
+| `value`         | `string`                  | Currently active tab value                 |
+| `onValueChange` | `(value: string) => void` | Callback function to change the active tab |
+| `nativeID`      | `string`                  | Unique identifier for the tabs instance    |
+
+**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.
+
+### useTabsMeasurements
+
+Hook to access tab measurements context values for managing tab trigger positions and dimensions.
+
+```tsx
+import { useTabsMeasurements } from 'heroui-native';
+
+const CustomIndicator = () => {
+  const { measurements, variant } = useTabsMeasurements();
+  // ... your implementation
+};
+```
+
+**Returns:** `UseTabsMeasurementsReturn`
+
+| property          | type                                                    | description                                       |
+| ----------------- | ------------------------------------------------------- | ------------------------------------------------- |
+| `measurements`    | `Record<string, ItemMeasurements>`                      | Record of measurements for each tab trigger       |
+| `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | Function to update measurements for a tab trigger |
+| `variant`         | `'primary' \| 'secondary'`                              | Visual variant of the tabs                        |
+
+#### ItemMeasurements
+
+| property | type     | description                         |
+| -------- | -------- | ----------------------------------- |
+| `width`  | `number` | Width of the tab trigger in pixels  |
+| `height` | `number` | Height of the tab trigger in pixels |
+| `x`      | `number` | X position of the tab trigger       |
+
+**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.
+
+### useTabsTrigger
+
+Hook to access tab trigger context values within custom components or compound components.
+
+```tsx
+import { useTabsTrigger } from 'heroui-native';
+
+const CustomLabel = () => {
+  const { value, isSelected, nativeID } = useTabsTrigger();
+  // ... your implementation
+};
+```
+
+**Returns:** `UseTabsTriggerReturn`
+
+| property     | type      | description                                |
+| ------------ | --------- | ------------------------------------------ |
+| `value`      | `string`  | The value of this trigger                  |
+| `nativeID`   | `string`  | Unique identifier for this trigger         |
+| `isSelected` | `boolean` | Whether this trigger is currently selected |
+
+**Note:** This hook must be used within a `Tabs.Trigger` component. It will throw an error if called outside of the trigger context.
diff --git a/apps/docs/content/docs/en/native/components/(overlays)/bottom-sheet.mdx b/apps/docs/content/docs/en/native/components/(overlays)/bottom-sheet.mdx
new file mode 100644
index 0000000..31f32f1
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(overlays)/bottom-sheet.mdx
@@ -0,0 +1,418 @@
+---
+title: BottomSheet
+description: Displays a bottom sheet that slides up from the bottom with animated transitions and swipe-to-dismiss gestures.
+links:
+  source_native: bottom-sheet/bottom-sheet.tsx
+  styles_native: bottom-sheet/bottom-sheet.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { BottomSheet } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay>...</BottomSheet.Overlay>
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>...</BottomSheet.Title>
+      <BottomSheet.Description>...</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+- **BottomSheet**: Root component that manages open state and provides context to child components.
+- **BottomSheet.Trigger**: Pressable element that opens the bottom sheet when pressed.
+- **BottomSheet.Portal**: Renders bottom sheet content in a portal with full window overlay.
+- **BottomSheet.Overlay**: Background overlay that covers the screen, typically closes bottom sheet when pressed.
+- **BottomSheet.Content**: Main bottom sheet container using @gorhom/bottom-sheet for rendering with gesture support.
+- **BottomSheet.Close**: Close button for the bottom sheet. Can accept custom children or uses default close icon.
+- **BottomSheet.Title**: Bottom sheet title text with semantic heading role and accessibility linking.
+- **BottomSheet.Description**: Bottom sheet description text that provides additional context with accessibility linking.
+
+## Usage
+
+### Basic Bottom Sheet
+
+Simple bottom sheet with title, description, and close button.
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger asChild>
+    <Button>Open Bottom Sheet</Button>
+  </BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>...</BottomSheet.Title>
+      <BottomSheet.Description>...</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### Detached Bottom Sheet
+
+Bottom sheet that appears detached from the bottom edge with custom spacing.
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content
+      detached={true}
+      bottomInset={insets.bottom + 12}
+      className="mx-4"
+      backgroundClassName="rounded-[32px]"
+    >
+      ...
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### Scrollable with Snap Points
+
+Bottom sheet with multiple snap points and scrollable content.
+
+To make scrollable content work correctly inside `BottomSheet.Content`, follow these base principles:
+
+- Use a scrollable from [`@gorhom/bottom-sheet`](https://gorhom.dev/react-native-bottom-sheet/components/bottomsheetscrollview) (e.g. `BottomSheetScrollView`, `BottomSheetFlatList`, `BottomSheetSectionList`, `BottomSheetVirtualizedList`). A plain `ScrollView`/`FlatList` from `react-native` will let the sheet intercept the scroll gesture.
+- On `BottomSheet.Content`, disable over-drag and dynamic sizing so the sheet does not grow with its content or absorb the scroll: `enableOverDrag={false}` and `enableDynamicSizing={false}`.
+- Give `BottomSheet.Content` a fixed height via `contentContainerClassName="h-full"` (or any other fixed height). The constraint must be on `BottomSheet.Content`, not on the scrollable child — the scrollable needs a bounded parent to scroll inside.
+
+```tsx
+import { BottomSheetScrollView } from '@gorhom/bottom-sheet';
+
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content
+      snapPoints={['40%', '80%']}
+      enableOverDrag={false}
+      enableDynamicSizing={false}
+      contentContainerClassName="h-full"
+    >
+      <BottomSheetScrollView>...</BottomSheetScrollView>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>;
+```
+
+See the full example with a sticky footer (`BottomSheetFooter`) in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/components/bottom-sheet/scrollable-with-snap-points.tsx>).
+
+### Custom Overlay
+
+Replace the default overlay with custom content like blur effects.
+
+```tsx
+import { useBottomSheet, useBottomSheetAnimation } from 'heroui-native';
+import { StyleSheet, Pressable } from 'react-native';
+import { interpolate, useDerivedValue } from 'react-native-reanimated';
+import { AnimatedBlurView } from './animated-blur-view';
+import { useUniwind } from 'uniwind';
+
+export const BottomSheetBlurOverlay = () => {
+  const { theme } = useUniwind();
+  const { onOpenChange } = useBottomSheet();
+  const { progress } = useBottomSheetAnimation();
+
+  const blurIntensity = useDerivedValue(() => {
+    return interpolate(progress.get(), [0, 1, 2], [0, 40, 0]);
+  });
+
+  return (
+    <Pressable
+      style={StyleSheet.absoluteFill}
+      onPress={() => onOpenChange(false)}
+    >
+      <AnimatedBlurView
+        blurIntensity={blurIntensity}
+        tint={theme === 'dark' ? 'dark' : 'systemUltraThinMaterialDark'}
+        style={StyleSheet.absoluteFill}
+      />
+    </Pressable>
+  );
+};
+```
+
+```tsx
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheetBlurOverlay />
+    <BottomSheet.Content>...</BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+### With Keyboard-Aware Input
+
+When rendering an `Input` or `InputOTP` inside `BottomSheet.Content`, use the `useBottomSheetAwareHandlers` hook to wire keyboard avoidance handlers. Pass the returned `onFocus` / `onBlur` to your input.
+
+> **Note**: `useBottomSheetAwareHandlers` must be used inside a `BottomSheet`. Call it from a child component rendered inside `BottomSheet.Content` — outside of a `BottomSheet` context the returned handlers are no-ops.
+
+For scrollable content, also configure `BottomSheet.Content` with `keyboardBehavior="extend"` (or `"interactive"`) and `keyboardShouldPersistTaps="handled"` on the scrollable so taps don't dismiss the keyboard before reaching their target.
+
+```tsx
+import { BottomSheet, Input, useBottomSheetAwareHandlers } from 'heroui-native';
+
+const BottomSheetTextInput = () => {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return <Input placeholder="Type here..." onFocus={onFocus} onBlur={onBlur} />;
+};
+
+<BottomSheet>
+  <BottomSheet.Trigger>...</BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content keyboardBehavior="extend">
+      <BottomSheetTextInput />
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>;
+```
+
+See full examples for [`Input`](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/components/bottom-sheet/with-text-input.tsx>) and [`InputOTP`](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/components/bottom-sheet/with-otp-input.tsx>) inside a bottom sheet.
+
+## Example
+
+```tsx
+import { BottomSheet, Button } from 'heroui-native';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { withUniwind } from 'uniwind';
+import Ionicons from '@expo/vector-icons/Ionicons';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function BottomSheetExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
+      <BottomSheet.Trigger asChild>
+        <Button variant="secondary">Open Bottom Sheet</Button>
+      </BottomSheet.Trigger>
+      <BottomSheet.Portal>
+        <BottomSheet.Overlay />
+        <BottomSheet.Content>
+          <View className="items-center mb-5">
+            <View className="size-20 items-center justify-center rounded-full bg-green-500/10">
+              <StyledIonicons
+                name="shield-checkmark"
+                size={40}
+                className="text-green-500"
+              />
+            </View>
+          </View>
+          <View className="mb-8 gap-2 items-center">
+            <BottomSheet.Title className="text-center">
+              Keep yourself safe
+            </BottomSheet.Title>
+            <BottomSheet.Description className="text-center">
+              Update your software to the latest version for better security and
+              performance.
+            </BottomSheet.Description>
+          </View>
+          <View className="gap-3">
+            <Button onPress={() => setIsOpen(false)}>Update Now</Button>
+            <Button variant="tertiary" onPress={() => setIsOpen(false)}>
+              Later
+            </Button>
+          </View>
+        </BottomSheet.Content>
+      </BottomSheet.Portal>
+    </BottomSheet>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/bottom-sheet.tsx).
+
+## API Reference
+
+### BottomSheet
+
+| prop            | type                       | default | description                                        |
+| --------------- | -------------------------- | ------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`          | -       | Bottom sheet content and trigger elements          |
+| `isOpen`        | `boolean`                  | -       | Controlled open state of the bottom sheet          |
+| `isDefaultOpen` | `boolean`                  | `false` | Initial open state when uncontrolled               |
+| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
+| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
+| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |
+
+#### Animation Configuration
+
+Animation configuration for bottom sheet root component. Can be:
+
+- `"disable-all"`: Disable all animations including children
+- `undefined`: Use default animations
+
+### BottomSheet.Trigger
+
+| prop                       | type                    | default | description                                                    |
+| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`       | -       | Trigger element content                                        |
+| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
+| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |
+
+### BottomSheet.Portal
+
+| prop                       | type                   | default | description                                                                                                                   |
+| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and bottom sheet)                                                                                     |
+| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `className`                | `string`               | -       | Additional CSS classes for portal container                                                                                   |
+| `style`                    | `StyleProp<ViewStyle>` | -       | Additional styles for portal container                                                                                        |
+| `hostName`                 | `string`               | -       | Optional portal host name for specific container                                                                              |
+| `forceMount`               | `boolean`              | -       | Force mount when closed for animation purposes                                                                                |
+
+### BottomSheet.Overlay
+
+| prop                    | type                                                   | default | description                                                  |
+| ----------------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`                                      | -       | Custom overlay content                                       |
+| `className`             | `string`                                               | -       | Additional CSS classes for overlay                           |
+| `style`                 | `ViewStyle`                                            | -       | Additional styles for overlay container                      |
+| `animation`             | `Omit<PopupOverlayAnimation, 'entering' \| 'exiting'>` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                                              | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `isCloseOnPress`        | `boolean`                                              | `true`  | Whether pressing overlay closes bottom sheet                 |
+| `...PressableProps`     | `PressableProps`                                       | -       | All standard React Native Pressable props are supported      |
+
+#### Animation Configuration
+
+Animation configuration for bottom sheet overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration (excluding `entering` and `exiting` properties)
+
+| prop            | type                       | default     | description                                     |
+| --------------- | -------------------------- | ----------- | ----------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -           | Disable animations while customizing properties |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values [idle, open, close]              |
+
+### BottomSheet.Content
+
+| prop                        | type                                     | default | description                                                                                        |
+| --------------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `children`                  | `React.ReactNode`                        | -       | Bottom sheet content                                                                               |
+| `className`                 | `string`                                 | -       | Additional CSS classes for bottom sheet container                                                  |
+| `containerClassName`        | `string`                                 | -       | Additional CSS classes for container                                                               |
+| `contentContainerClassName` | `string`                                 | -       | Additional CSS classes for content container                                                       |
+| `backgroundClassName`       | `string`                                 | -       | Additional CSS classes for background                                                              |
+| `handleClassName`           | `string`                                 | -       | Additional CSS classes for handle                                                                  |
+| `handleIndicatorClassName`  | `string`                                 | -       | Additional CSS classes for handle indicator                                                        |
+| `contentContainerProps`     | `Omit<BottomSheetViewProps, 'children'>` | -       | Props for the content container                                                                    |
+| `animation`                 | `AnimationDisabled`                      | -       | Animation configuration                                                                            |
+| `...GorhomBottomSheetProps` | `Partial<GorhomBottomSheetProps>`        | -       | All [@gorhom/bottom-sheet props](https://gorhom.dev/react-native-bottom-sheet/props) are supported |
+
+**Note**: You can use all components from [@gorhom/bottom-sheet](https://gorhom.dev/react-native-bottom-sheet/components/bottomsheetview) inside the content, such as `BottomSheetView`, `BottomSheetScrollView`, `BottomSheetFlatList`, etc.
+
+### BottomSheet.Close
+
+BottomSheet.Close extends [CloseButton](./close-button) and automatically handles bottom sheet dismissal when pressed.
+
+### BottomSheet.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title content                                      |
+| `className`    | `string`          | -       | Additional CSS classes for title                   |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### BottomSheet.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description content                                |
+| `className`    | `string`          | -       | Additional CSS classes for description             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### useBottomSheet
+
+Hook to access bottom sheet primitive context.
+
+```tsx
+const { isOpen, onOpenChange } = useBottomSheet();
+```
+
+| property       | type                       | description                   |
+| -------------- | -------------------------- | ----------------------------- |
+| `isOpen`       | `boolean`                  | Current open state            |
+| `onOpenChange` | `(value: boolean) => void` | Function to change open state |
+
+### useBottomSheetAnimation
+
+Hook to access bottom sheet animation context for advanced customization.
+
+```tsx
+const { progress } = useBottomSheetAnimation();
+```
+
+| property   | type                  | description                                  |
+| ---------- | --------------------- | -------------------------------------------- |
+| `progress` | `SharedValue<number>` | Animation progress (0=idle, 1=open, 2=close) |
+
+### useBottomSheetAwareHandlers
+
+Hook that returns `onFocus` and `onBlur` handlers for keyboard avoidance when an `Input` or `InputOTP` is rendered inside `BottomSheet.Content`. Must be used inside a `BottomSheet` — outside of a `BottomSheet` context, the returned handlers are no-ops.
+
+```tsx
+const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+```
+
+| property  | type                      | description                                                                          |
+| --------- | ------------------------- | ------------------------------------------------------------------------------------ |
+| `onFocus` | `(e: FocusEvent) => void` | Focus handler that notifies the bottom sheet about the keyboard target               |
+| `onBlur`  | `(e: BlurEvent) => void`  | Blur handler that conditionally clears the keyboard target in the bottom sheet state |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+BottomSheet uses FullWindowOverlay on iOS, which renders in a separate native window. This breaks the React Native element inspector. To enable the inspector during development, set `disableFullWindowOverlay={true}` on `BottomSheet.Portal`. Tradeoff: the bottom sheet will not appear above native modals when disabled.
+
+### Handling Close Callbacks
+
+It's recommended to use `BottomSheet`'s `onOpenChange` prop for handling close callbacks, as it reliably fires for all close scenarios (swiping down, pressing overlay, pressing close button, programmatic close, etc.).
+
+```tsx
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={(value) => {
+    setIsOpen(value);
+    if (!value) {
+      // This callback runs whenever the bottom sheet closes
+      // regardless of how it was closed
+      yourCallbackOnClose();
+    }
+  }}
+>
+  ...
+</BottomSheet>
+```
+
+**Note**: `BottomSheet.Content`'s `onClose` prop (from @gorhom/bottom-sheet) has limitations and will only fire when the bottom sheet is closed by swiping down. It won't fire when closing via overlay press, close button, or programmatic close. For reliable close callbacks, always use `BottomSheet`'s `onOpenChange` prop instead.
diff --git a/apps/docs/content/docs/en/native/components/(overlays)/dialog.mdx b/apps/docs/content/docs/en/native/components/(overlays)/dialog.mdx
new file mode 100644
index 0000000..a32af5d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(overlays)/dialog.mdx
@@ -0,0 +1,299 @@
+---
+title: Dialog
+description: Displays a modal overlay with animated transitions and gesture-based dismissal.
+links:
+  source_native: dialog/dialog.tsx
+  styles_native: dialog/dialog.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/dialog-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Dialog } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Dialog>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay>...</Dialog.Overlay>
+    <Dialog.Content>
+      <Dialog.Close>...</Dialog.Close>
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+- **Dialog**: Root component that manages open state and provides context to child components.
+- **Dialog.Trigger**: Pressable element that opens the dialog when pressed.
+- **Dialog.Portal**: Renders dialog content in a portal with centered layout and animation control.
+- **Dialog.Overlay**: Background overlay that appears behind the dialog content, typically closes dialog when pressed.
+- **Dialog.Content**: Main dialog container with gesture support for drag-to-dismiss.
+- **Dialog.Close**: Close button for the dialog. Can accept custom children or uses default close icon.
+- **Dialog.Title**: Dialog title text with semantic heading role.
+- **Dialog.Description**: Dialog description text that provides additional context.
+
+## Usage
+
+### Basic Dialog
+
+Simple dialog with title, description, and close button.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger asChild>
+    <Button>Open Dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <Dialog.Description>...</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### Scrollable Content
+
+Handle long content with scroll views.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>...</Dialog.Title>
+      <View className="h-[300px]">
+        <ScrollView>...</ScrollView>
+      </View>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### Form Dialog
+
+Dialog with text inputs and keyboard handling.
+
+```tsx
+<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+  <Dialog.Trigger>...</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <KeyboardAvoidingView behavior="padding">
+      <Dialog.Content>
+        <Dialog.Close />
+        <Dialog.Title>...</Dialog.Title>
+        <TextField>...</TextField>
+        <Button onPress={handleSubmit}>Submit</Button>
+      </Dialog.Content>
+    </KeyboardAvoidingView>
+  </Dialog.Portal>
+</Dialog>
+```
+
+## Example
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+import { View } from 'react-native';
+import { useState } from 'react';
+
+export default function DialogExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
+      <Dialog.Trigger asChild>
+        <Button variant="primary">Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Close variant="ghost" />
+          <View className="mb-5 gap-1.5">
+            <Dialog.Title>Confirm Action</Dialog.Title>
+            <Dialog.Description>
+              Are you sure you want to proceed with this action? This cannot be
+              undone.
+            </Dialog.Description>
+          </View>
+          <View className="flex-row justify-end gap-3">
+            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
+              Cancel
+            </Button>
+            <Button size="sm">Confirm</Button>
+          </View>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/dialog.tsx).
+
+## API Reference
+
+### Dialog
+
+| prop            | type                       | default | description                                        |
+| --------------- | -------------------------- | ------- | -------------------------------------------------- |
+| `children`      | `React.ReactNode`          | -       | Dialog content and trigger elements                |
+| `isOpen`        | `boolean`                  | -       | Controlled open state of the dialog                |
+| `isDefaultOpen` | `boolean`                  | `false` | Initial open state when uncontrolled               |
+| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
+| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
+| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |
+
+#### AnimationRootDisableAll
+
+Animation configuration for dialog root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+
+### Dialog.Trigger
+
+| prop                       | type                    | default | description                                                    |
+| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`       | -       | Trigger element content                                        |
+| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
+| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |
+
+### Dialog.Portal
+
+| prop                       | type                   | default | description                                                                                                                   |
+| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and dialog)                                                                                           |
+| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `className`                | `string`               | -       | Additional CSS classes for portal container                                                                                   |
+| `style`                    | `StyleProp<ViewStyle>` | -       | Additional styles for portal container                                                                                        |
+| `hostName`                 | `string`               | -       | Optional portal host name for specific container                                                                              |
+| `forceMount`               | `boolean`              | -       | Force mount when closed for animation purposes                                                                                |
+
+### Dialog.Overlay
+
+| prop                    | type                     | default | description                                                  |
+| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
+| `children`              | `React.ReactNode`        | -       | Custom overlay content                                       |
+| `className`             | `string`                 | -       | Additional CSS classes for overlay                           |
+| `style`                 | `ViewStyle`              | -       | Additional styles for overlay container                      |
+| `animation`             | `DialogOverlayAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `isCloseOnPress`        | `boolean`                | `true`  | Whether pressing overlay closes dialog                       |
+| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes               |
+| `...PressableProps`     | `PressableProps`         | -       | All standard React Native Pressable props are supported      |
+
+#### DialogOverlayAnimation
+
+Animation configuration for dialog overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop            | type                       | default                 | description                                                                  |
+| --------------- | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                              |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`             | Opacity values [idle, open, close] (progress-based, for dialog presentation) |
+| `entering`      | `EntryOrExitLayoutType`    | `FadeIn.duration(200)`  | Custom entering animation (for popover presentation)                         |
+| `exiting`       | `EntryOrExitLayoutType`    | `FadeOut.duration(150)` | Custom exiting animation (for popover presentation)                          |
+
+### Dialog.Content
+
+| prop                    | type                     | default | description                                         |
+| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
+| `children`              | `React.ReactNode`        | -       | Dialog content                                      |
+| `className`             | `string`                 | -       | Additional CSS classes for content container        |
+| `style`                 | `StyleProp<ViewStyle>`   | -       | Additional styles for content container             |
+| `animation`             | `DialogContentAnimation` | -       | Animation configuration                             |
+| `isSwipeable`           | `boolean`                | `true`  | Whether the dialog content can be swiped to dismiss |
+| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes      |
+| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported    |
+
+#### DialogContentAnimation
+
+Animation configuration for dialog content component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop       | type                    | default                                                                                     | description                                     |
+| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -                                                                                           | Disable animations while customizing properties |
+| `entering` | `EntryOrExitLayoutType` | Keyframe with `scale: 0.96→1` and `opacity: 0→1` (200ms, easing: `Easing.out(Easing.ease)`) | Custom entering animation                       |
+| `exiting`  | `EntryOrExitLayoutType` | Keyframe with `scale: 1→0.96` and `opacity: 1→0` (150ms, easing: `Easing.in(Easing.ease)`)  | Custom exiting animation                        |
+
+### Dialog.Close
+
+Dialog.Close extends [CloseButton](./close-button) and automatically handles dialog dismissal when pressed.
+
+### Dialog.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title content                                      |
+| `className`    | `string`          | -       | Additional CSS classes for title                   |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Dialog.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description content                                |
+| `className`    | `string`          | -       | Additional CSS classes for description             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### useDialog
+
+Hook to access dialog primitive context.
+
+```tsx
+const { isOpen, onOpenChange } = useDialog();
+```
+
+| property       | type                       | description                   |
+| -------------- | -------------------------- | ----------------------------- |
+| `isOpen`       | `boolean`                  | Current open state            |
+| `onOpenChange` | `(value: boolean) => void` | Function to change open state |
+
+### useDialogAnimation
+
+Hook to access dialog animation context for advanced customization.
+
+```tsx
+const { progress, isDragging, isGestureReleaseAnimationRunning } =
+  useDialogAnimation();
+```
+
+| property                           | type                   | description                                  |
+| ---------------------------------- | ---------------------- | -------------------------------------------- |
+| `progress`                         | `SharedValue<number>`  | Animation progress (0=idle, 1=open, 2=close) |
+| `isDragging`                       | `SharedValue<boolean>` | Whether dialog is being dragged              |
+| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | Whether gesture release animation is running |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Dialog uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Dialog.Portal`. Tradeoff: the dialog will not appear above native modals when disabled.
diff --git a/apps/docs/content/docs/en/native/components/(overlays)/popover.mdx b/apps/docs/content/docs/en/native/components/(overlays)/popover.mdx
new file mode 100644
index 0000000..0b9e7d1
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(overlays)/popover.mdx
@@ -0,0 +1,531 @@
+---
+title: Popover
+description: Displays a floating content panel anchored to a trigger element with placement and alignment options.
+links:
+  source_native: popover/popover.tsx
+  styles_native: popover/popover.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/popover-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Popover } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content>
+      <Popover.Arrow />
+      <Popover.Close />
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+- **Popover**: Main container that manages open/close state, positioning, and provides context to child components.
+- **Popover.Trigger**: Clickable element that toggles popover visibility. Wraps any child element with press handlers.
+- **Popover.Portal**: Renders popover content in a portal layer above other content. Ensures proper stacking and positioning.
+- **Popover.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
+- **Popover.Content**: Container for popover content with positioning, styling, and collision detection. Supports both popover and bottom-sheet presentations.
+- **Popover.Arrow**: Optional arrow element pointing to the trigger. Automatically positioned based on placement.
+- **Popover.Close**: Close button for the popover. Can accept custom children or uses default close icon.
+- **Popover.Title**: Optional title text with pre-styled typography.
+- **Popover.Description**: Optional description text with muted styling.
+
+## Usage
+
+### Basic Usage
+
+The Popover component uses compound parts to create floating content panels.
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">...</Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### With Title and Description
+
+Structure popover content with title and description for better information hierarchy.
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">
+      <Popover.Close />
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### With Arrow
+
+Add an arrow pointing to the trigger element for better visual connection.
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" placement="top">
+      <Popover.Arrow />
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+> **Note:** When using `<Popover.Arrow />`, you need to apply a border to `Popover.Content`, for instance using the `border border-border` class. This ensures the arrow visually connects properly with the content border.
+
+### Width Control
+
+Control the width of the popover content using the `width` prop.
+
+```tsx
+{
+  /* Fixed width in pixels */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width={320}>
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* Match trigger width */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="trigger">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* Full width (100%) */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="full">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+
+{
+  /* Auto-size to content (default) */
+}
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover" width="content-fit">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+```
+
+### Bottom Sheet Presentation
+
+Use bottom sheet presentation for mobile-optimized interaction patterns.
+
+> **Important:** The `presentation` prop on `Popover.Content` must match the `presentation` prop on `Popover.Root`. In development mode, a mismatch will throw an error.
+
+```tsx
+<Popover presentation="bottom-sheet">
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="bottom-sheet">
+      <Popover.Title>...</Popover.Title>
+      <Popover.Description>...</Popover.Description>
+      <Button>Close</Button>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### Placement Options
+
+Control where the popover appears relative to the trigger element.
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Content presentation="popover" placement="left">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### Alignment Options
+
+Fine-tune content alignment along the placement axis.
+
+```tsx
+<Popover>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Content presentation="popover" placement="top" align="start">
+      ...
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### Custom Animation
+
+Configure custom animations for open and close transitions using the `animation` prop on `Popover.Root`.
+
+```tsx
+<Popover
+  animation={{
+    entering: {
+      type: 'spring',
+      config: { damping: 15, stiffness: 300 },
+    },
+    exiting: {
+      type: 'timing',
+      config: { duration: 200 },
+    },
+  }}
+>
+  <Popover.Trigger>...</Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">...</Popover.Content>
+  </Popover.Portal>
+</Popover>
+```
+
+### Programmatic control
+
+```tsx
+// Open or close popover programmatically using ref
+const popoverRef = useRef<PopoverTriggerRef>(null);
+
+// Open programmatically
+popoverRef.current?.open();
+
+// Close programmatically
+popoverRef.current?.close();
+
+// Full example
+<Popover>
+  <Popover.Trigger ref={popoverRef} asChild>
+    <Button>Trigger</Button>
+  </Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Overlay />
+    <Popover.Content presentation="popover">
+      <Text>Content</Text>
+      <Button onPress={() => popoverRef.current?.close()}>Close</Button>
+    </Popover.Content>
+  </Popover.Portal>
+</Popover>;
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { Button, Popover, useThemeColor } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function PopoverExample() {
+  const themeColorMuted = useThemeColor('muted');
+
+  return (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button variant="tertiary" size="sm">
+          <Ionicons
+            name="information-circle"
+            size={20}
+            color={themeColorMuted}
+          />
+          <Button.Label>Show Info</Button.Label>
+        </Button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Overlay />
+        <Popover.Content
+          presentation="popover"
+          width={320}
+          className="gap-1 rounded-xl px-6 py-4"
+        >
+          <Popover.Close className="absolute top-3 right-3 z-50" />
+          <Popover.Title>Information</Popover.Title>
+          <Popover.Description>
+            This popover includes a title and description to provide more
+            structured information to users.
+          </Popover.Description>
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/popover.tsx).
+
+## API Reference
+
+### Popover
+
+| prop            | type                          | default     | description                                                                                    |
+| --------------- | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `children`      | `ReactNode`                   | -           | Children elements to be rendered inside the popover                                            |
+| `isOpen`        | `boolean`                     | -           | Whether the popover is open (controlled mode)                                                  |
+| `isDefaultOpen` | `boolean`                     | -           | The open state of the popover when initially rendered (uncontrolled mode)                      |
+| `onOpenChange`  | `(isOpen: boolean) => void`   | -           | Callback when the popover open state changes                                                   |
+| `animation`     | `AnimationRootDisableAll`     | -           | Animation configuration. Can be `false`, `"disabled"`, `"disable-all"`, `true`, or `undefined` |
+| `presentation`  | `'popover' \| 'bottom-sheet'` | `'popover'` | Presentation mode for the popover content                                                      |
+| `asChild`       | `boolean`                     | `false`     | Whether to render as a child element                                                           |
+| `...ViewProps`  | `ViewProps`                   | -           | All standard React Native View props are supported                                             |
+
+#### AnimationRootDisableAll
+
+Animation configuration for popover root component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+
+### Popover.Trigger
+
+| prop                | type             | default | description                                             |
+| ------------------- | ---------------- | ------- | ------------------------------------------------------- |
+| `children`          | `ReactNode`      | -       | The trigger element content                             |
+| `className`         | `string`         | -       | Additional CSS classes for the trigger                  |
+| `asChild`           | `boolean`        | `true`  | Whether to render as a child element                    |
+| `...PressableProps` | `PressableProps` | -       | All standard React Native Pressable props are supported |
+
+### Popover.Portal
+
+| prop                       | type        | default | description                                                                                                                   |
+| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactNode` | -       | The portal content (required)                                                                                                 |
+| `disableFullWindowOverlay` | `boolean`   | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
+| `unstable_accessibilityContainerViewIsModal` | `boolean` | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `hostName`                 | `string`    | -       | Optional name of the host element for the portal                                                                              |
+| `forceMount`               | `boolean`   | -       | Whether to force mount the component in the DOM                                                                               |
+| `className`                | `string`    | -       | Additional CSS classes for the portal container                                                                               |
+| `...ViewProps`             | `ViewProps` | -       | All standard React Native View props are supported                                                                            |
+
+### Popover.Overlay
+
+| prop                    | type                      | default | description                                                  |
+| ----------------------- | ------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                  | -       | Additional CSS classes for the overlay                       |
+| `closeOnPress`          | `boolean`                 | `true`  | Whether to close the popover when overlay is pressed         |
+| `forceMount`            | `boolean`                 | -       | Whether to force mount the component in the DOM              |
+| `animation`             | `PopoverOverlayAnimation` | -       | Animation configuration                                      |
+| `isAnimatedStyleActive` | `boolean`                 | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `asChild`               | `boolean`                 | `false` | Whether to render as a child element                         |
+| `...Animated.ViewProps` | `Animated.ViewProps`      | -       | All Reanimated Animated.View props are supported             |
+
+#### PopoverOverlayAnimation
+
+Animation configuration for popover overlay component. Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop            | type                       | default                     | description                                                                               |
+| --------------- | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| boolean`    | -                           | Disable animations while customizing properties                                           |
+| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`                 | Opacity values [idle, open, close] - Takes effect for bottom-sheet/dialog presentation    |
+| `entering`      | `EntryOrExitLayoutType`    | FadeIn with duration 200ms  | Custom Keyframe animation for entering transition - Takes effect for popover presentation |
+| `exiting`       | `EntryOrExitLayoutType`    | FadeOut with duration 150ms | Custom Keyframe animation for exiting transition - Takes effect for popover presentation  |
+
+### Popover.Content (Popover Presentation)
+
+| prop                      | type                                             | default         | description                                                                                             |
+| ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `children`                | `ReactNode`                                      | -               | The popover content                                                                                     |
+| `presentation`            | `'popover'`                                      | `'popover'`     | Presentation mode - must match Popover.Root presentation prop. When not provided, defaults to 'popover' |
+| `width`                   | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content                                                                   |
+| `placement`               | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | Placement of the popover relative to trigger                                                            |
+| `align`                   | `'start' \| 'center' \| 'end'`                   | `'center'`      | Alignment along the placement axis                                                                      |
+| `avoidCollisions`         | `boolean`                                        | `true`          | Whether to flip placement when close to viewport edges                                                  |
+| `offset`                  | `number`                                         | `9`             | Distance from trigger element in pixels                                                                 |
+| `alignOffset`             | `number`                                         | `0`             | Offset along the alignment axis in pixels                                                               |
+| `disablePositioningStyle` | `boolean`                                        | `false`         | Whether to disable automatic positioning styles                                                         |
+| `forceMount`              | `boolean`                                        | -               | Whether to force mount the component in the DOM                                                         |
+| `insets`                  | `Insets`                                         | -               | Screen edge insets to respect when positioning                                                          |
+| `className`               | `string`                                         | -               | Additional CSS classes for the content container                                                        |
+| `animation`               | `PopupPopoverContentAnimation`                   | -               | Animation configuration                                                                                 |
+| `isAnimatedStyleActive`   | `boolean`                                        | `true`          | Whether animated styles (react-native-reanimated) are active                                            |
+| `asChild`                 | `boolean`                                        | `false`         | Whether to render as a child element                                                                    |
+| `...Animated.ViewProps`   | `Animated.ViewProps`                             | -               | All Reanimated Animated.View props are supported                                                        |
+
+### Popover.Content (Bottom Sheet Presentation)
+
+| prop                        | type                   | default | description                                                                                    |
+| --------------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `children`                  | `ReactNode`            | -       | The bottom sheet content                                                                       |
+| `presentation`              | `'bottom-sheet'`       | -       | Presentation mode - must be 'bottom-sheet' and match Popover.Root presentation prop (required) |
+| `contentContainerClassName` | `string`               | -       | Additional CSS classes for the content container                                               |
+| `contentContainerProps`     | `BottomSheetViewProps` | -       | Props for the content container                                                                |
+| `enablePanDownToClose`      | `boolean`              | `true`  | Whether pan down gesture closes the sheet                                                      |
+| `backgroundStyle`           | `ViewStyle`            | -       | Style for the bottom sheet background                                                          |
+| `handleIndicatorStyle`      | `ViewStyle`            | -       | Style for the bottom sheet handle indicator                                                    |
+| `...BottomSheetProps`       | `BottomSheetProps`     | -       | All @gorhom/bottom-sheet props are supported                                                   |
+
+#### PopupPopoverContentAnimation
+
+Animation configuration for popover content component (popover presentation). Can be:
+
+- `false` or `"disabled"`: Disable all animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop       | type                    | default                                                         | description                                       |
+| ---------- | ----------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
+| `state`    | `'disabled' \| boolean` | -                                                               | Disable animations while customizing properties   |
+| `entering` | `EntryOrExitLayoutType` | Keyframe with translateY/translateX, scale, and opacity (200ms) | Custom Keyframe animation for entering transition |
+| `exiting`  | `EntryOrExitLayoutType` | Keyframe mirroring entering animation (150ms)                   | Custom Keyframe animation for exiting transition  |
+
+### Popover.Arrow
+
+| prop                  | type                                     | default | description                                                           |
+| --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
+| `className`           | `string`                                 | -       | Additional CSS classes for the arrow                                  |
+| `height`              | `number`                                 | `12`    | Height of the arrow in pixels                                         |
+| `width`               | `number`                                 | `20`    | Width of the arrow in pixels                                          |
+| `fill`                | `string`                                 | -       | Fill color of the arrow (defaults to content background)              |
+| `stroke`              | `string`                                 | -       | Stroke (border) color of the arrow (defaults to content border color) |
+| `strokeWidth`         | `number`                                 | `1`     | Stroke width of the arrow border in pixels                            |
+| `strokeBaselineInset` | `number`                                 | `1`     | Baseline inset in pixels for stroke alignment                         |
+| `placement`           | `'top' \| 'bottom' \| 'left' \| 'right'` | -       | Placement of the popover (inherited from content)                     |
+| `children`            | `ReactNode`                              | -       | Custom arrow content (replaces default SVG arrow)                     |
+| `style`               | `StyleProp<ViewStyle>`                   | -       | Additional styles for the arrow container                             |
+| `...ViewProps`        | `ViewProps`                              | -       | All standard React Native View props are supported                    |
+
+### Popover.Close
+
+Popover.Close extends [CloseButton](./close-button) and automatically handles popover dismissal when pressed.
+
+### Popover.Title
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | The title text content                             |
+| `className`    | `string`    | -       | Additional CSS classes for the title               |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+### Popover.Description
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `children`     | `ReactNode` | -       | The description text content                       |
+| `className`    | `string`    | -       | Additional CSS classes for the description         |
+| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |
+
+## Hooks
+
+### usePopover
+
+Hook to access popover context values within custom components or compound components.
+
+```tsx
+import { usePopover } from 'heroui-native';
+
+const CustomContent = () => {
+  const { isOpen, onOpenChange, triggerPosition } = usePopover();
+  // ... your implementation
+};
+```
+
+**Returns:** `UsePopoverReturn`
+
+| property             | type                                                | description                                                       |
+| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
+| `isOpen`             | `boolean`                                           | Whether the popover is currently open                             |
+| `onOpenChange`       | `(open: boolean) => void`                           | Callback function to change the popover open state                |
+| `isDefaultOpen`      | `boolean \| undefined`                              | Whether the popover should be open by default (uncontrolled mode) |
+| `isDisabled`         | `boolean \| undefined`                              | Whether the popover is disabled                                   |
+| `triggerPosition`    | `LayoutPosition \| null`                            | The position of the trigger element relative to the viewport      |
+| `setTriggerPosition` | `(triggerPosition: LayoutPosition \| null) => void` | Function to update the trigger element's position                 |
+| `contentLayout`      | `LayoutRectangle \| null`                           | The layout measurements of the popover content                    |
+| `setContentLayout`   | `(contentLayout: LayoutRectangle \| null) => void`  | Function to update the content layout measurements                |
+| `nativeID`           | `string`                                            | Unique identifier for the popover instance                        |
+
+**Note:** This hook must be used within a `Popover` component. It will throw an error if called outside of the popover context.
+
+### usePopoverAnimation
+
+Hook to access popover animation state values within custom components or compound components.
+
+```tsx
+import { usePopoverAnimation } from 'heroui-native';
+
+const CustomContent = () => {
+  const { progress, isDragging } = usePopoverAnimation();
+  // ... your implementation
+};
+```
+
+**Returns:** `UsePopoverAnimationReturn`
+
+| property     | type                   | description                                                        |
+| ------------ | ---------------------- | ------------------------------------------------------------------ |
+| `progress`   | `SharedValue<number>`  | Progress value for the popover animation (0=idle, 1=open, 2=close) |
+| `isDragging` | `SharedValue<boolean>` | Dragging state shared value                                        |
+
+**Note:** This hook must be used within a `Popover` component. It will throw an error if called outside of the popover animation context.
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Popover uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Popover.Portal`. Tradeoff: the popover will not appear above native modals when disabled.
+
+### Native Modal (iOS)
+
+When a `Popover` is opened inside a screen presented as a native modal (`presentation: 'modal' | 'formSheet' | 'pageSheet'`), the popover content may render shifted upward. In the new architecture (Fabric), `react-native-screens` marks `RNSModalScreen` as a Fabric root, so the trigger's position is reported relative to the modal's origin while `FullWindowOverlay` (where the popover is mounted) is anchored to the iOS application window. Compensate by adding `safeAreaInsets.top` to `offset`:
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const insets = useSafeAreaInsets();
+
+<Popover.Content presentation="popover" offset={insets.top + 20}>
+  ...
+</Popover.Content>;
+```
diff --git a/apps/docs/content/docs/en/native/components/(overlays)/toast.mdx b/apps/docs/content/docs/en/native/components/(overlays)/toast.mdx
new file mode 100644
index 0000000..fd8c95d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(overlays)/toast.mdx
@@ -0,0 +1,431 @@
+---
+title: Toast
+description: Displays temporary notification messages that appear at the top or bottom of the screen.
+links:
+  source_native: toast/toast.tsx
+  styles_native: toast/toast.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/toast-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Toast, useToast } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Toast>
+  <Toast.Title>...</Toast.Title>
+  <Toast.Description>...</Toast.Description>
+  <Toast.Action>...</Toast.Action>
+  <Toast.Close />
+</Toast>
+```
+
+- **Toast**: Main container that displays notification messages. Handles positioning, animations, and swipe gestures.
+- **Toast.Title**: Title text of the toast notification. Inherits variant styling from parent Toast context.
+- **Toast.Description**: Descriptive text content displayed below the title.
+- **Toast.Action**: Action button within the toast. Button variant is automatically determined based on toast variant but can be overridden.
+- **Toast.Close**: Close button for dismissing the toast. Renders as an icon-only button that calls hide when pressed.
+
+## Usage
+
+### Usage Pattern 1: Simple String
+
+Show a toast with a simple string message.
+
+```tsx
+const { toast } = useToast();
+
+toast.show('This is a toast message');
+```
+
+### Usage Pattern 2: Config Object
+
+Show a toast with label, description, variant, and action button using a config object.
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: 'You have upgraded your plan',
+  description: 'You can continue using HeroUI Chat',
+  icon: <Icon name="check" />,
+  actionLabel: 'Close',
+  onActionPress: ({ hide }) => hide(),
+});
+```
+
+### Usage Pattern 3: Custom Component
+
+Show a toast with a fully custom component for complete control over styling and layout.
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" placement="top" {...props}>
+      <Toast.Title>Custom Toast</Toast.Title>
+      <Toast.Description>This is a custom toast component</Toast.Description>
+      <Toast.Close />
+    </Toast>
+  ),
+});
+```
+
+**Note**: Toast items are memoized for performance. If you need to pass external state (like loading state) to a custom toast component, it will not update automatically. Use shared state techniques instead, such as React Context, state management libraries, or refs to ensure state updates propagate to the toast component.
+
+### Disabling All Animations
+
+Disable all animations including children by using `"disable-all"`. This cascades down to all child components (like Button in Toast.Action).
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  variant: 'success',
+  label: 'Operation completed',
+  description: 'All animations are disabled',
+  animation: 'disable-all',
+});
+```
+
+Or with a custom component:
+
+```tsx
+const { toast } = useToast();
+
+toast.show({
+  component: (props) => (
+    <Toast variant="accent" animation="disable-all" {...props}>
+      <Toast.Title>No animations</Toast.Title>
+      <Toast.Description>
+        This toast has all animations disabled
+      </Toast.Description>
+      <Toast.Action>Action</Toast.Action>
+    </Toast>
+  ),
+});
+```
+
+## Example
+
+```tsx
+import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function ToastExample() {
+  const { toast } = useToast();
+  const themeColorForeground = useThemeColor('foreground');
+
+  return (
+    <View className="gap-4 p-4">
+      <Button
+        onPress={() =>
+          toast.show({
+            variant: 'success',
+            label: 'You have upgraded your plan',
+            description: 'You can continue using HeroUI Chat',
+            actionLabel: 'Close',
+            onActionPress: ({ hide }) => hide(),
+          })
+        }
+      >
+        Show Success Toast
+      </Button>
+
+      <Button
+        onPress={() =>
+          toast.show({
+            component: (props) => (
+              <Toast variant="accent" {...props}>
+                <Toast.Title>Custom Toast</Toast.Title>
+                <Toast.Description>
+                  This uses a custom component
+                </Toast.Description>
+                <Toast.Action onPress={() => props.hide()}>Undo</Toast.Action>
+                <Toast.Close className="absolute top-0 right-0" />
+              </Toast>
+            ),
+          })
+        }
+      >
+        Show Custom Toast
+      </Button>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/toast.tsx>).
+
+## Global Configuration
+
+Configure toast behavior globally using `HeroUINativeProvider` config prop. Global configs serve as defaults for all toasts unless overridden locally.
+
+> **Note**: For complete provider configuration options, see the [Provider documentation](/docs/native/getting-started/handbook/provider#toast-configuration).
+
+### Insets
+
+Insets control the distance of toast sides from screen edges. Insets are added to safe area insets. To set all toasts to have a side distance of 20px from screen edges, configure insets:
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      insets: {
+        top: 20,
+        bottom: 20,
+        left: 20,
+        right: 20,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+### Content Wrapper with KeyboardAvoidingView
+
+Wrap toast content with KeyboardAvoidingView to ensure toasts adjust when the keyboard appears:
+
+```tsx
+import {
+  KeyboardAvoidingView,
+  KeyboardProvider,
+} from 'react-native-keyboard-controller';
+import { HeroUINativeProvider } from 'heroui-native';
+import { useCallback } from 'react';
+
+function AppContent() {
+  const contentWrapper = useCallback(
+    (children: React.ReactNode) => (
+      <KeyboardAvoidingView
+        pointerEvents="box-none"
+        behavior="padding"
+        keyboardVerticalOffset={12}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+    []
+  );
+
+  return (
+    <KeyboardProvider>
+      <HeroUINativeProvider
+        config={{
+          toast: {
+            contentWrapper,
+          },
+        }}
+      >
+        {children}
+      </HeroUINativeProvider>
+    </KeyboardProvider>
+  );
+}
+```
+
+### Default Props
+
+Set global defaults for variant, placement, animation, and swipe behavior:
+
+```tsx
+<HeroUINativeProvider
+  config={{
+    toast: {
+      defaultProps: {
+        variant: 'accent',
+        placement: 'bottom',
+        isSwipeable: false,
+      },
+    },
+  }}
+>
+  {children}
+</HeroUINativeProvider>
+```
+
+## API Reference
+
+### Toast
+
+| prop                    | type                                                          | default     | description                                                               |
+| ----------------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `variant`               | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Visual variant of the toast                                               |
+| `placement`             | `'top' \| 'bottom'`                                           | `'top'`     | Placement of the toast on screen                                          |
+| `isSwipeable`           | `boolean`                                                     | `true`      | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `animation`             | `ToastRootAnimation`                                          | -           | Animation configuration                                                   |
+| `isAnimatedStyleActive` | `boolean`                                                     | `true`      | Whether animated styles (react-native-reanimated) are active              |
+| `className`             | `string`                                                      | -           | Additional CSS class for the toast container                              |
+| `...ViewProps`          | `ViewProps`                                                   | -           | All standard React Native View props are supported                        |
+
+#### ToastRootAnimation
+
+Animation configuration for Toast component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                      | type                                     | default                                                                                                                   | description                                                                      |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `state`                   | `'disabled' \| 'disable-all' \| boolean` | -                                                                                                                         | Disable animations while customizing properties                                  |
+| `opacity.value`           | `[number, number]`                       | `[1, 0]`                                                                                                                  | Opacity interpolation values for fade effect as toasts move beyond visible stack |
+| `opacity.timingConfig`    | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for opacity transitions                           |
+| `translateY.value`        | `[number, number]`                       | `[0, 10]`                                                                                                                 | Translate Y interpolation values for peek effect of stacked toasts               |
+| `translateY.timingConfig` | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for translateY transitions                        |
+| `scale.value`             | `[number, number]`                       | `[1, 0.97]`                                                                                                               | Scale interpolation values for depth effect of stacked toasts                    |
+| `scale.timingConfig`      | `WithTimingConfig`                       | `{ duration: 300 }`                                                                                                       | Animation timing configuration for scale transitions                             |
+| `entering.top`            | `EntryOrExitLayoutType`                  | `FadeInUp`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`<br/>`.mass(3)`  | Custom entering animation for top placement                                      |
+| `entering.bottom`         | `EntryOrExitLayoutType`                  | `FadeInDown`<br/>`.springify()`<br/>`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`<br/>`.mass(3)` | Custom entering animation for bottom placement                                   |
+| `exiting.top`             | `EntryOrExitLayoutType`                  | Keyframe animation with<br/>`translateY: -100, scale: 0.97, opacity: 0.5`                                                 | Custom exiting animation for top placement                                       |
+| `exiting.bottom`          | `EntryOrExitLayoutType`                  | Keyframe animation with<br/>`translateY: 100, scale: 0.97, opacity: 0.5`                                                  | Custom exiting animation for bottom placement                                    |
+
+### Toast.Title
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to be rendered as title                    |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Toast.Description
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to be rendered as description              |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
+
+### Toast.Action
+
+Toast.Action extends all props from [Button](button) component. Button variant is automatically determined based on toast variant but can be overridden.
+
+| prop        | type                   | default | description                                                                  |
+| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
+| `children`  | `React.ReactNode`      | -       | Content to be rendered as action button label                                |
+| `variant`   | `ButtonVariant`        | -       | Button variant. If not provided, automatically determined from toast variant |
+| `size`      | `'sm' \| 'md' \| 'lg'` | `'sm'`  | Size of the action button                                                    |
+| `className` | `string`               | -       | Additional CSS classes                                                       |
+
+For inherited props including `onPress`, `isDisabled`, and all Button props, see [Button API Reference](button#api-reference).
+
+### Toast.Close
+
+Toast.Close extends all props from [Button](button) component.
+
+| prop        | type                                | default | description                                    |
+| ----------- | ----------------------------------- | ------- | ---------------------------------------------- |
+| `children`  | `React.ReactNode`                   | -       | Custom close icon. Defaults to CloseIcon       |
+| `iconProps` | `{ size?: number; color?: string }` | -       | Props for the default close icon               |
+| `size`      | `'sm' \| 'md' \| 'lg'`              | `'sm'`  | Size of the close button                       |
+| `className` | `string`                            | -       | Additional CSS classes                         |
+| `onPress`   | `(event: any) => void`              | -       | Custom press handler. Defaults to hiding toast |
+
+For inherited props including `isDisabled` and all Button props, see [Button API Reference](button#api-reference).
+
+### ToastProviderProps
+
+Props for configuring toast behavior globally via `HeroUINativeProvider` config prop.
+
+| prop                                         | type                                                | default | description                                                                                                                                                                                                      |
+| -------------------------------------------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultProps`                               | `ToastGlobalConfig`                                 | -       | Global toast configuration used as defaults for all toasts                                                                                                                                                       |
+| `disableFullWindowOverlay`                   | `boolean`                                           | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; toasts won't appear above native modals                                                                                     |
+| `unstable_accessibilityContainerViewIsModal` | `boolean`                                           | `false` | Controls whether VoiceOver treats the overlay window as a modal container. When `true`, VoiceOver is restricted to elements inside the overlay. iOS only. Unstable: may change with react-native-screens updates |
+| `insets`                                     | `ToastInsets`                                       | -       | Insets for spacing from screen edges (added to safe area insets)                                                                                                                                                 |
+| `maxVisibleToasts`                           | `number`                                            | `3`     | Maximum number of visible toasts before opacity starts fading                                                                                                                                                    |
+| `contentWrapper`                             | `(children: React.ReactNode) => React.ReactElement` | -       | Custom wrapper function to wrap toast content                                                                                                                                                                    |
+| `children`                                   | `React.ReactNode`                                   | -       | Children to render                                                                                                                                                                                               |
+
+#### ToastGlobalConfig
+
+Global toast configuration used as defaults for all toasts unless overridden locally.
+
+| prop          | type                                                          | description                                                               |
+| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `variant`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Visual variant of the toast                                               |
+| `placement`   | `'top' \| 'bottom'`                                           | Placement of the toast on screen                                          |
+| `isSwipeable` | `boolean`                                                     | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `animation`   | `ToastRootAnimation`                                          | Animation configuration for toast                                         |
+
+#### ToastInsets
+
+Insets for spacing from screen edges. Values are added to safe area insets.
+
+| prop     | type     | default | description                                                                                               |
+| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `top`    | `number` | -       | Inset from the top edge in pixels (added to safe area inset). Platform-specific: iOS = 0, Android = 12    |
+| `bottom` | `number` | -       | Inset from the bottom edge in pixels (added to safe area inset). Platform-specific: iOS = 6, Android = 12 |
+| `left`   | `number` | -       | Inset from the left edge in pixels (added to safe area inset). Default: 12                                |
+| `right`  | `number` | -       | Inset from the right edge in pixels (added to safe area inset). Default: 12                               |
+
+## Hooks
+
+### useToast
+
+Hook to access toast functionality. Must be used within a `ToastProvider` (provided by `HeroUINativeProvider`).
+
+| return value     | type           | description                              |
+| ---------------- | -------------- | ---------------------------------------- |
+| `toast`          | `ToastManager` | Toast manager with show and hide methods |
+| `isToastVisible` | `boolean`      | Whether any toast is currently visible   |
+
+#### ToastManager
+
+| method | type                                              | description                                                                                                                          |
+| ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `show` | `(options: string \| ToastShowOptions) => string` | Show a toast. Returns the ID of the shown toast. Supports three usage patterns: simple string, config object, or custom component    |
+| `hide` | `(ids?: string \| string[] \| 'all') => void`     | Hide one or more toasts. No argument hides the last toast, 'all' hides all toasts, single ID or array of IDs hides specific toast(s) |
+
+#### ToastShowOptions
+
+Options for showing a toast. Can be either a config object with default styling or a custom component.
+
+**When using config object (without component):**
+
+| prop            | type                                                                                                                              | default | description                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `variant`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`                                                                     | -       | Visual variant of the toast                                                         |
+| `placement`     | `'top' \| 'bottom'`                                                                                                               | -       | Placement of the toast on screen                                                    |
+| `isSwipeable`   | `boolean`                                                                                                                         | -       | Whether the toast can be swiped to dismiss                                          |
+| `animation`     | `ToastRootAnimation \| false \| "disabled" \| "disable-all"`                                                                      | -       | Animation configuration for toast                                                   |
+| `duration`      | `number \| 'persistent'`                                                                                                          | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
+| `id`            | `string`                                                                                                                          | -       | Optional ID for the toast. If not provided, one will be generated                   |
+| `label`         | `string`                                                                                                                          | -       | Label text for the toast                                                            |
+| `description`   | `string`                                                                                                                          | -       | Description text for the toast                                                      |
+| `actionLabel`   | `string`                                                                                                                          | -       | Action button label text                                                            |
+| `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | -       | Callback function called when the action button is pressed                          |
+| `icon`          | `React.ReactNode`                                                                                                                 | -       | Icon element to display in the toast                                                |
+| `onShow`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is shown                                    |
+| `onHide`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is hidden                                   |
+
+**When using custom component:**
+
+| prop        | type                                                 | default | description                                                                         |
+| ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `id`        | `string`                                             | -       | Optional ID for the toast. If not provided, one will be generated                   |
+| `component` | `(props: ToastComponentProps) => React.ReactElement` | -       | A function that receives toast props and returns a React element                    |
+| `duration`  | `number \| 'persistent'`                             | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
+| `onShow`    | `() => void`                                         | -       | Callback function called when the toast is shown                                    |
+| `onHide`    | `() => void`                                         | -       | Callback function called when the toast is hidden                                   |
+
+## Special Notes
+
+### Element Inspector (iOS)
+
+Toast uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `ToastProvider` (via `config.toast` when using HeroUINativeProvider). Tradeoff: toasts will not appear above native modals when disabled.
diff --git a/apps/docs/content/docs/en/native/components/(typography)/text.mdx b/apps/docs/content/docs/en/native/components/(typography)/text.mdx
new file mode 100644
index 0000000..7c8e864
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(typography)/text.mdx
@@ -0,0 +1,222 @@
+---
+title: Typography
+description: Primitive typography component for rendering styled text with semantic type variants.
+icon: updated
+links:
+  source_native: text/text.tsx
+  styles_native: text/text.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { Typography } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<Typography>...</Typography>
+
+{/* Sub-components */}
+<Typography.Heading>...</Typography.Heading>
+<Typography.Paragraph>...</Typography.Paragraph>
+<Typography.Code>...</Typography.Code>
+```
+
+- **Typography**: Root text element. Selects a typography preset via `type` and exposes orthogonal `align`, `color`, `weight`, and `truncate` props.
+- **Typography.Heading**: Convenience wrapper restricted to heading types (`h1`–`h6`). Adds `accessibilityRole="header"` automatically.
+- **Typography.Paragraph**: Convenience wrapper restricted to body types (`body`, `body-sm`, `body-xs`).
+- **Typography.Code**: Chip-styled inline monospaced text. Uses a platform-appropriate monospace font family.
+
+## Usage
+
+### Basic Usage
+
+The Typography component renders body text by default.
+
+```tsx
+<Typography>Hello, world!</Typography>
+```
+
+### Type Variants
+
+Use the `type` prop to select a semantic typography preset.
+
+```tsx
+<Typography type="h1">Heading 1</Typography>
+<Typography type="h2">Heading 2</Typography>
+<Typography type="h3">Heading 3</Typography>
+<Typography type="h4">Heading 4</Typography>
+<Typography type="h5">Heading 5</Typography>
+<Typography type="h6">Heading 6</Typography>
+<Typography type="body">Body text</Typography>
+<Typography type="body-sm">Small body text</Typography>
+<Typography type="body-xs">Extra-small body text</Typography>
+<Typography type="code">Code snippet</Typography>
+```
+
+### Headings
+
+Use `Typography.Heading` for heading text with automatic header accessibility role.
+
+```tsx
+<Typography.Heading type="h1">Page Title</Typography.Heading>
+<Typography.Heading type="h2">Section Title</Typography.Heading>
+<Typography.Heading type="h3">Subsection Title</Typography.Heading>
+```
+
+### Paragraphs
+
+Use `Typography.Paragraph` for body text.
+
+```tsx
+<Typography.Paragraph>
+  This is a paragraph of body text with the default size.
+</Typography.Paragraph>
+<Typography.Paragraph type="body-sm">
+  This is smaller body text.
+</Typography.Paragraph>
+```
+
+### Code
+
+Use `Typography.Code` (or equivalently `<Typography type="code">`) for inline code snippets. Both render a chip-styled, monospaced inline element with a subtle background, rounded corners, and a `self-start` layout so it does not stretch in flex containers. The platform monospace `fontFamily` is applied at the `Typography` root, so the two forms are interchangeable.
+
+```tsx
+<Typography.Code>console.log('hello')</Typography.Code>
+<Typography type="code">console.log('hello')</Typography>
+```
+
+### Alignment
+
+Use the `align` prop to control horizontal alignment. `start` and `end` are RTL-aware (they flip under right-to-left layouts).
+
+```tsx
+<Typography align="start">Start-aligned</Typography>
+<Typography align="center">Center-aligned</Typography>
+<Typography align="end">End-aligned</Typography>
+<Typography align="justify">Justified text spreads across the line.</Typography>
+```
+
+> **Note:** `text-justify` is iOS-only on React Native; Android falls back to left alignment.
+
+### Color
+
+Use the `color` prop to apply a semantic foreground color preset.
+
+```tsx
+<Typography color="default">Default foreground</Typography>
+<Typography color="muted">Muted secondary text</Typography>
+```
+
+For other theme colors, pass the corresponding utility through `className` (e.g. `className="text-accent"`, `className="text-danger"`).
+
+### Weight
+
+Use the `weight` prop to override the font weight implied by `type`. The override merges via `tailwind-merge`, so it always wins over the type variant's default weight.
+
+```tsx
+<Typography type="h1" weight="bold">Bold H1</Typography>
+<Typography weight="medium">Medium body</Typography>
+<Typography weight="semibold">Semibold body</Typography>
+```
+
+### Truncation
+
+Use the `truncate` boolean prop to limit the text to a single line with an ellipsis. It is mapped to React Native's `numberOfLines={1}`. An explicit `numberOfLines` prop, if provided, takes precedence.
+
+```tsx
+<Typography truncate>
+  A long line of text that will be cut off with an ellipsis when it overflows
+  the container.
+</Typography>;
+
+{
+  /* Multi-line truncation via the underlying RN prop */
+}
+<Typography numberOfLines={2}>
+  Two-line truncation works through React Native's standard `numberOfLines`
+  prop.
+</Typography>;
+```
+
+## Example
+
+```tsx
+import { Typography } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function TypographyExample() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Typography.Heading type="h1">Welcome</Typography.Heading>
+      <Typography.Heading type="h3">Getting Started</Typography.Heading>
+      <Typography.Paragraph>
+        This is a body paragraph rendered with the Typography component.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" type="body-sm">
+        Smaller supporting text for captions or footnotes.
+      </Typography.Paragraph>
+      <Typography.Code>npm install heroui-native</Typography.Code>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/text.tsx>).
+
+## API Reference
+
+### Typography
+
+`Typography` extends all standard React Native `TextProps` with additional typography props.
+
+| prop           | type                                                                                         | default     | description                                                                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `type`         | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'`    | Semantic typography variant (size, default weight, line-height)                                                                |
+| `align`        | `'start' \| 'center' \| 'end' \| 'justify'`                                                  | `'start'`   | Horizontal alignment. `start` and `end` are RTL-aware. `justify` is iOS-only.                                                  |
+| `color`        | `'default' \| 'muted'`                                                                       | `'default'` | Semantic foreground color preset                                                                                               |
+| `weight`       | `'normal' \| 'medium' \| 'semibold' \| 'bold'`                                               | -           | Font weight override. When set, overrides the weight implied by `type`.                                                        |
+| `truncate`     | `boolean`                                                                                    | `false`     | Truncates the text to a single line with an ellipsis (sets `numberOfLines={1}`). An explicit `numberOfLines` takes precedence. |
+| `children`     | `React.ReactNode`                                                                            | -           | Content to render                                                                                                              |
+| `className`    | `string`                                                                                     | -           | Additional CSS classes                                                                                                         |
+| `...TextProps` | `TextProps`                                                                                  | -           | All standard React Native `Text` props are supported                                                                           |
+
+### Typography.Heading
+
+Inherits all `Typography` root props (`align`, `color`, `weight`, `truncate`, `className`, and React Native `TextProps`). Sets `accessibilityRole="header"` automatically and narrows `type` to heading variants.
+
+| prop           | type                                           | default | description                                          |
+| -------------- | ---------------------------------------------- | ------- | ---------------------------------------------------- |
+| `type`         | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h1'`  | Heading level                                        |
+| `children`     | `React.ReactNode`                              | -       | Content to render                                    |
+| `className`    | `string`                                       | -       | Additional CSS classes                               |
+| `...TextProps` | `TextProps`                                    | -       | All standard React Native `Text` props are supported |
+
+### Typography.Paragraph
+
+Inherits all `Typography` root props (`align`, `color`, `weight`, `truncate`, `className`, and React Native `TextProps`). Narrows `type` to body variants.
+
+| prop           | type                               | default  | description                                          |
+| -------------- | ---------------------------------- | -------- | ---------------------------------------------------- |
+| `type`         | `'body' \| 'body-sm' \| 'body-xs'` | `'body'` | Paragraph text size                                  |
+| `children`     | `React.ReactNode`                  | -        | Content to render                                    |
+| `className`    | `string`                           | -        | Additional CSS classes                               |
+| `...TextProps` | `TextProps`                        | -        | All standard React Native `Text` props are supported |
+
+### Typography.Code
+
+Inherits all `Typography` root props (`align`, `color`, `weight`, `truncate`, `className`, `style`, and React Native `TextProps`). Thin wrapper that forces `type="code"`; the platform monospace `fontFamily` is merged in at the `Typography` root, so `<Typography type="code">` and `<Typography.Code>` render identically.
+
+| prop           | type              | default | description                                          |
+| -------------- | ----------------- | ------- | ---------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Content to render                                    |
+| `className`    | `string`          | -       | Additional CSS classes                               |
+| `...TextProps` | `TextProps`       | -       | All standard React Native `Text` props are supported |
diff --git a/apps/docs/content/docs/en/native/components/(utilities)/pressable-feedback.mdx b/apps/docs/content/docs/en/native/components/(utilities)/pressable-feedback.mdx
new file mode 100644
index 0000000..442a165
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(utilities)/pressable-feedback.mdx
@@ -0,0 +1,339 @@
+---
+title: PressableFeedback
+description: Container component that provides visual feedback for press interactions with automatic scale animation.
+links:
+  source_native: pressable-feedback/pressable-feedback.tsx
+  styles_native: pressable-feedback/pressable-feedback.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/pressable-feedback-docs-dark.mp4"
+/>
+
+## Import
+
+```tsx
+import { PressableFeedback } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight />
+  <PressableFeedback.Ripple />
+  <PressableFeedback.Scale>...</PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+- **PressableFeedback**: Pressable container with built-in scale animation. Manages press state and container dimensions, providing them to child compound parts via context. Use `animation={false}` to disable the built-in scale when using `PressableFeedback.Scale` instead.
+- **PressableFeedback.Scale**: Scale animation wrapper for applying scale to a specific child element. Use this instead of the root's built-in scale when you need control over which element scales or need to apply `className` / `style` to the scale wrapper.
+- **PressableFeedback.Highlight**: Highlight overlay for iOS-style press feedback. Renders an absolute-positioned layer that fades in on press.
+- **PressableFeedback.Ripple**: Ripple overlay for Android-style press feedback. Renders a radial gradient circle that expands from the touch point.
+
+## Usage
+
+### Basic
+
+PressableFeedback provides press-down scale feedback out of the box. This is the recommended way to use it in most cases.
+
+```tsx
+<PressableFeedback>...</PressableFeedback>
+```
+
+### With Highlight
+
+Add a highlight overlay for iOS-style feedback effect alongside the built-in scale.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight />
+  ...
+</PressableFeedback>
+```
+
+### With Ripple
+
+Add a ripple overlay for Android-style feedback effect alongside the built-in scale.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple />
+  ...
+</PressableFeedback>
+```
+
+### Custom Scale Animation
+
+Customize the built-in scale animation via the `animation.scale` prop. Accepts `value`, `timingConfig`, and `ignoreScaleCoefficient`.
+
+```tsx
+<PressableFeedback
+  animation={{
+    scale: {
+      value: 0.9,
+      timingConfig: { duration: 150 },
+      ignoreScaleCoefficient: true,
+    },
+  }}
+>
+  ...
+</PressableFeedback>
+```
+
+### Custom Highlight Animation
+
+Configure highlight overlay opacity and background color.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Highlight
+    animation={{
+      backgroundColor: { value: '#3b82f6' },
+      opacity: { value: [0, 0.2] },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+### Custom Ripple Animation
+
+Configure ripple effect color, opacity, and duration.
+
+```tsx
+<PressableFeedback>
+  <PressableFeedback.Ripple
+    animation={{
+      backgroundColor: { value: '#ec4899' },
+      opacity: { value: [0, 0.1, 0] },
+      progress: { baseDuration: 600 },
+    }}
+  />
+  ...
+</PressableFeedback>
+```
+
+### Scale on a Specific Child (PressableFeedback.Scale)
+
+When you need to apply the scale animation to a specific element inside the container rather than the root itself, disable the root's built-in scale with `animation={false}` and use the `PressableFeedback.Scale` compound part. This gives you full control over which element scales and lets you apply `className` / `style` directly to the scale wrapper.
+
+```tsx
+<PressableFeedback animation={false}>
+  <PressableFeedback.Scale>...</PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+You can combine it with Highlight or Ripple inside the Scale wrapper:
+
+```tsx
+<PressableFeedback animation={false}>
+  <PressableFeedback.Scale>
+    <PressableFeedback.Highlight />
+    ...
+  </PressableFeedback.Scale>
+</PressableFeedback>
+```
+
+### Disable All Animations
+
+Set `animation="disable-all"` on the root to cascade-disable all animations including the built-in scale and any child compound parts (Scale, Highlight, Ripple).
+
+```tsx
+<PressableFeedback animation="disable-all">...</PressableFeedback>
+```
+
+You can also disable all animations while keeping a scale config (e.g. for toggling at runtime):
+
+```tsx
+<PressableFeedback animation={{ scale: { value: 0.97 }, state: 'disable-all' }}>
+  ...
+</PressableFeedback>
+```
+
+## Example
+
+```tsx
+import { PressableFeedback, Card, Button } from 'heroui-native';
+import { Image } from 'expo-image';
+import { LinearGradient } from 'expo-linear-gradient';
+import { StyleSheet, View, Text } from 'react-native';
+
+export default function PressableFeedbackExample() {
+  return (
+    <PressableFeedback className="w-full aspect-square overflow-auto">
+      <Card className="flex-1">
+        <Image
+          source={{
+            uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg',
+          }}
+          style={StyleSheet.absoluteFill}
+          contentFit="cover"
+        />
+        <LinearGradient
+          colors={['rgba(0,0,0,0.1)', 'rgba(0,0,0,0.4)']}
+          style={StyleSheet.absoluteFill}
+        />
+        <PressableFeedback.Ripple
+          animation={{
+            backgroundColor: { value: 'white' },
+            opacity: { value: [0, 0.3, 0] },
+          }}
+        />
+        <View className="flex-1 gap-4" pointerEvents="box-none">
+          <Card.Body className="flex-1" pointerEvents="none">
+            <Card.Title className="text-base text-zinc-50 uppercase mb-0.5">
+              Neo
+            </Card.Title>
+            <Card.Description className="text-zinc-50 font-medium text-base">
+              Home robot
+            </Card.Description>
+          </Card.Body>
+          <Card.Footer className="gap-3">
+            <View className="flex-row items-center justify-between">
+              <View pointerEvents="none">
+                <Text className="text-base text-white">Available soon</Text>
+                <Text className="text-base text-zinc-300">Get notified</Text>
+              </View>
+              <Button size="sm" className="bg-white">
+                <Button.Label className="text-black">Notify me</Button.Label>
+              </Button>
+            </View>
+          </Card.Footer>
+        </View>
+      </Card>
+    </PressableFeedback>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/pressable-feedback.tsx>).
+
+## API Reference
+
+### PressableFeedback
+
+| prop                    | type                             | default | description                                                                                                 |
+| ----------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `children`              | `React.ReactNode`                | -       | Content to be wrapped with press feedback                                                                   |
+| `isDisabled`            | `boolean`                        | `false` | Whether the pressable component is disabled                                                                 |
+| `className`             | `string`                         | -       | Additional CSS classes                                                                                      |
+| `animation`             | `PressableFeedbackRootAnimation` | -       | Customize scale via `{ scale: ... }`, `false` to disable root scale, `'disable-all'` to cascade-disable all |
+| `isAnimatedStyleActive` | `boolean`                        | `true`  | Whether the root's built-in animated styles are active                                                      |
+| `asChild`               | `boolean`                        | `false` | Whether to render as a child element                                                                        |
+| `...rest`               | `AnimatedProps<PressableProps>`  | -       | All Reanimated Animated Pressable props are supported                                                       |
+
+#### PressableFeedbackRootAnimation
+
+The root animation prop supports the standard `AnimationRoot` control flow:
+
+- `true` or `undefined`: Use the default built-in scale animation
+- `false` or `"disabled"`: Disable the root's built-in scale (use this when applying scale via `PressableFeedback.Scale` instead)
+- `"disable-all"`: Cascade-disable all animations including the built-in scale and children (Scale, Highlight, Ripple)
+- `object`: Custom configuration for the built-in scale
+
+| prop    | type                                     | default | description                                                                     |
+| ------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `scale` | `PressableFeedbackScaleAnimation`        | -       | Customize the built-in scale animation (value, timingConfig, etc.)              |
+| `state` | `'disabled' \| 'disable-all' \| boolean` | -       | Control animation state while keeping configuration (e.g. for runtime toggling) |
+
+### PressableFeedback.Scale
+
+Use this compound part when you need to apply scale to a specific child element inside the container, instead of scaling the root itself. Set `animation={false}` on the root to disable its built-in scale when using this component.
+
+| prop                    | type                              | default | description                                                  |
+| ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                          | -       | Additional CSS classes                                       |
+| `animation`             | `PressableFeedbackScaleAnimation` | -       | Animation configuration for scale effect                     |
+| `isAnimatedStyleActive` | `boolean`                         | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `style`                 | `ViewStyle`                       | -       | Additional styles                                            |
+| `...AnimatedProps`      | `AnimatedProps<ViewProps>`        | -       | All Reanimated Animated View props are supported             |
+
+#### PressableFeedbackScaleAnimation
+
+Animation configuration for scale effect. Can be:
+
+- `false` or `"disabled"`: Disable scale animation
+- `true` or `undefined`: Use default scale animation
+- `object`: Custom scale configuration
+
+| prop                     | type                    | default                                              | description                                                                |
+| ------------------------ | ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
+| `state`                  | `'disabled' \| boolean` | -                                                    | Disable animations while customizing properties                            |
+| `value`                  | `number`                | `0.985`                                              | Scale value when pressed (automatically adjusted based on container width) |
+| `timingConfig`           | `WithTimingConfig`      | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                                             |
+| `ignoreScaleCoefficient` | `boolean`               | `false`                                              | Ignore automatic scale coefficient and use the scale value directly        |
+
+### PressableFeedback.Highlight
+
+| prop                    | type                                  | default | description                                                  |
+| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                              | -       | Additional CSS classes                                       |
+| `animation`             | `PressableFeedbackHighlightAnimation` | -       | Animation configuration for highlight overlay                |
+| `isAnimatedStyleActive` | `boolean`                             | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `style`                 | `ViewStyle`                           | -       | Additional styles                                            |
+| `...AnimatedProps`      | `AnimatedProps<ViewProps>`            | -       | All Reanimated Animated View props are supported             |
+
+#### PressableFeedbackHighlightAnimation
+
+Animation configuration for highlight overlay. Can be:
+
+- `false` or `"disabled"`: Disable highlight animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                    | type                    | default             | description                                     |
+| ----------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
+| `state`                 | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
+| `opacity.value`         | `[number, number]`      | `[0, 0.1]`          | Opacity values [unpressed, pressed]             |
+| `opacity.timingConfig`  | `WithTimingConfig`      | `{ duration: 200 }` | Animation timing configuration                  |
+| `backgroundColor.value` | `string`                | Theme-aware gray    | Background color of highlight overlay           |
+
+### PressableFeedback.Ripple
+
+| prop                    | type                                      | default | description                                                  |
+| ----------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------ |
+| `className`             | `string`                                  | -       | Additional CSS classes for container slot                    |
+| `classNames`            | `ElementSlots<RippleSlots>`               | -       | Additional CSS classes for slots (container, ripple)         |
+| `styles`                | `Partial<Record<RippleSlots, ViewStyle>>` | -       | Styles for different parts of the ripple overlay             |
+| `animation`             | `PressableFeedbackRippleAnimation`        | -       | Animation configuration for ripple overlay                   |
+| `isAnimatedStyleActive` | `boolean`                                 | `true`  | Whether animated styles (react-native-reanimated) are active |
+| `...ViewProps`          | `Omit<ViewProps, 'style'>`                | -       | All View props except style are supported                    |
+
+#### `styles`
+
+| prop        | type        | description                   |
+| ----------- | ----------- | ----------------------------- |
+| `container` | `ViewStyle` | Styles for the container slot |
+| `ripple`    | `ViewStyle` | Styles for the ripple slot    |
+
+#### PressableFeedbackRippleAnimation
+
+Animation configuration for ripple overlay. Can be:
+
+- `false` or `"disabled"`: Disable ripple animations
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop                                 | type                       | default                 | description                                                                  |
+| ------------------------------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `state`                              | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                              |
+| `backgroundColor.value`              | `string`                   | Computed based on theme | Background color of ripple effect                                            |
+| `progress.baseDuration`              | `number`                   | `1000`                  | Base duration for ripple progress (automatically adjusted based on diagonal) |
+| `progress.minBaseDuration`           | `number`                   | `750`                   | Minimum base duration for the ripple progress animation                      |
+| `progress.ignoreDurationCoefficient` | `boolean`                  | `false`                 | Ignore automatic duration coefficient and use base duration directly         |
+| `opacity.value`                      | `[number, number, number]` | `[0, 0.1, 0]`           | Opacity values [start, peak, end] for ripple animation                       |
+| `opacity.timingConfig`               | `WithTimingConfig`         | `{ duration: 200 }`     | Animation timing configuration                                               |
+| `scale.value`                        | `[number, number, number]` | `[0, 1, 1]`             | Scale values [start, peak, end] for ripple animation                         |
+| `scale.timingConfig`                 | `WithTimingConfig`         | `{ duration: 200 }`     | Animation timing configuration                                               |
+
+#### `ElementSlots<RippleSlots>`
+
+Additional CSS classes for ripple slots:
+
+| slot        | description                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| `container` | Outer container slot (`absolute inset-0`) - styles can be fully customized                                          |
+| `ripple`    | Inner ripple slot (`absolute top-0 left-0 rounded-full`) - has animated properties that cannot be set via className |
diff --git a/apps/docs/content/docs/en/native/components/(utilities)/scroll-shadow.mdx b/apps/docs/content/docs/en/native/components/(utilities)/scroll-shadow.mdx
new file mode 100644
index 0000000..d3505a1
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/(utilities)/scroll-shadow.mdx
@@ -0,0 +1,216 @@
+---
+title: ScrollShadow
+description: Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.
+links:
+  source_native: scroll-shadow/scroll-shadow.tsx
+  styles_native: scroll-shadow/scroll-shadow.styles.ts
+---
+
+<NativeVideoPlayerView
+  target="auto"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scroll-shadow-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/scoll-shadow-docs-dark.mp4.mp4"
+/>
+
+## Import
+
+```tsx
+import { ScrollShadow } from 'heroui-native';
+```
+
+## Anatomy
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+- **ScrollShadow**: Main container that wraps scrollable components and adds dynamic gradient shadows at the edges based on scroll position and content overflow. Automatically detects scroll orientation (horizontal/vertical) and manages shadow visibility.
+- **LinearGradientComponent**: Required prop that accepts a LinearGradient component from compatible libraries (expo-linear-gradient, react-native-linear-gradient, etc.) to render the gradient shadows.
+
+## Usage
+
+### Basic Usage
+
+Wrap any scrollable component to automatically add edge shadows.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Horizontal Scrolling
+
+The component auto-detects horizontal scrolling from the child's `horizontal` prop.
+
+```tsx
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <FlatList horizontal data={data} renderItem={...} />
+</ScrollShadow>
+```
+
+### Custom Shadow Size
+
+Control the gradient shadow height/width with the `size` prop.
+
+```tsx
+<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Visibility Control
+
+Specify which shadows to display using the `visibility` prop.
+
+```tsx
+<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="bottom" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+
+<ScrollShadow visibility="none" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### Custom Shadow Color
+
+Override the default shadow color which uses the theme's background.
+
+```tsx
+<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
+  <ScrollView>...</ScrollView>
+</ScrollShadow>
+```
+
+### With Custom Scroll Handler
+
+**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop, you must use `useAnimatedScrollHandler` from react-native-reanimated.
+
+```tsx
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';
+
+const scrollHandler = useAnimatedScrollHandler({
+  onScroll: (event) => {
+    console.log(event.contentOffset.y);
+  },
+});
+
+<ScrollShadow LinearGradientComponent={LinearGradient}>
+  <Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
+</ScrollShadow>;
+```
+
+## Example
+
+```tsx
+import { ScrollShadow, Surface } from 'heroui-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { FlatList, ScrollView, Text, View } from 'react-native';
+
+export default function ScrollShadowExample() {
+  const horizontalData = Array.from({ length: 10 }, (_, i) => ({
+    id: i,
+    title: `Card ${i + 1}`,
+  }));
+
+  return (
+    <View className="flex-1 bg-background">
+      <Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
+      <ScrollShadow LinearGradientComponent={LinearGradient}>
+        <FlatList
+          data={horizontalData}
+          horizontal
+          renderItem={({ item }) => (
+            <Surface variant="2" className="w-32 h-24 justify-center px-4">
+              <Text>{item.title}</Text>
+            </Surface>
+          )}
+          showsHorizontalScrollIndicator={false}
+          contentContainerClassName="p-5 gap-4"
+        />
+      </ScrollShadow>
+
+      <Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
+      <ScrollShadow
+        size={80}
+        className="h-48"
+        LinearGradientComponent={LinearGradient}
+      >
+        <ScrollView
+          contentContainerClassName="p-5"
+          showsVerticalScrollIndicator={false}
+        >
+          <Text className="mb-4 text-2xl font-bold">Long Content</Text>
+          <Text className="mb-4 text-base leading-6">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+            ad minim veniam, quis nostrud exercitation ullamco laboris.
+          </Text>
+          <Text className="mb-4 text-base leading-6">
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
+            accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
+            quae ab illo inventore veritatis et quasi architecto beatae vitae.
+          </Text>
+        </ScrollView>
+      </ScrollShadow>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/scroll-shadow.tsx).
+
+## API Reference
+
+### ScrollShadow
+
+| prop                      | type                                                                   | default      | description                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| `children`                | `React.ReactElement`                                                   | -            | The scrollable component to enhance with shadows. Must be a single React element (ScrollView, FlatList, etc.)   |
+| `LinearGradientComponent` | `ComponentType<`<br/>`LinearGradientProps>`                            | **required** | LinearGradient component from any compatible library (expo-linear-gradient, react-native-linear-gradient, etc.) |
+| `size`                    | `number`                                                               | `50`         | Size (height/width) of the gradient shadow in pixels                                                            |
+| `orientation`             | `'horizontal' \| 'vertical'`                                           | auto-detect  | Orientation of the scroll shadow. If not provided, will auto-detect from child's `horizontal` prop              |
+| `visibility`              | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'`     | Visibility mode for the shadows. 'auto' shows shadows based on scroll position and content overflow             |
+| `color`                   | `string`                                                               | theme color  | Custom color for the gradient shadow. If not provided, uses the theme's background color                        |
+| `isEnabled`               | `boolean`                                                              | `true`       | Whether the shadow effect is enabled                                                                            |
+| `animation`               | `ScrollShadowRootAnimation`                                            | -            | Animation configuration                                                                                         |
+| `className`               | `string`                                                               | -            | Additional CSS classes to apply to the container                                                                |
+| `...ViewProps`            | `ViewProps`                                                            | -            | All standard React Native View props are supported                                                              |
+
+#### ScrollShadowRootAnimation
+
+Animation configuration for ScrollShadow component. Can be:
+
+- `false` or `"disabled"`: Disable only root animations
+- `"disable-all"`: Disable all animations including children
+- `true` or `undefined`: Use default animations
+- `object`: Custom animation configuration
+
+| prop            | type                                     | default  | description                                                                         |
+| --------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `state`         | `'disabled' \| 'disable-all' \| boolean` | -        | Disable animations while customizing properties                                     |
+| `opacity.value` | `[number, number]`                       | `[0, 1]` | `Opacity values [initial, active].`<br/>`For bottom/right shadow, this is reversed` |
+
+### LinearGradientProps
+
+The `LinearGradientComponent` prop expects a component that accepts these props:
+
+| prop        | type                              | description                                                        |
+| ----------- | --------------------------------- | ------------------------------------------------------------------ |
+| `colors`    | `any`                             | Array of colors for the gradient                                   |
+| `locations` | `any` (optional)                  | Array of numbers defining the location of each gradient color stop |
+| `start`     | `any` (optional)                  | Start point of the gradient (e.g., `{ x: 0, y: 0 }`)               |
+| `end`       | `any` (optional)                  | End point of the gradient (e.g., `{ x: 1, y: 0 }`)                 |
+| `style`     | `StyleProp<ViewStyle>` (optional) | Style to apply to the gradient view                                |
+
+## Special Notes
+
+**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop on your scrollable component, you must use `useAnimatedScrollHandler` from react-native-reanimated instead of the standard `onScroll` prop.
diff --git a/apps/docs/content/docs/en/native/components/index.mdx b/apps/docs/content/docs/en/native/components/index.mdx
new file mode 100644
index 0000000..2def63f
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/index.mdx
@@ -0,0 +1,52 @@
+---
+title: All Components
+description: Explore the full list of components available in HeroUI Native. More are on the way.
+---
+
+## Buttons
+
+<NativeComponentsCategory category="Buttons" />
+
+## Collections
+
+<NativeComponentsCategory category="Collections" />
+
+## Controls
+
+<NativeComponentsCategory category="Controls" />
+
+## Forms
+
+<NativeComponentsCategory category="Forms" />
+
+## Navigation
+
+<NativeComponentsCategory category="Navigation" />
+
+## Overlays
+
+<NativeComponentsCategory category="Overlays" />
+
+## Feedback
+
+<NativeComponentsCategory category="Feedback" />
+
+## Layout
+
+<NativeComponentsCategory category="Layout" />
+
+## Media
+
+<NativeComponentsCategory category="Media" />
+
+## Data Display
+
+<NativeComponentsCategory category="Data Display" />
+
+## Typography
+
+<NativeComponentsCategory category="Typography" />
+
+## Utilities
+
+<NativeComponentsCategory category="Utilities" />
diff --git a/apps/docs/content/docs/en/native/components/meta.json b/apps/docs/content/docs/en/native/components/meta.json
new file mode 100644
index 0000000..e6e6256
--- /dev/null
+++ b/apps/docs/content/docs/en/native/components/meta.json
@@ -0,0 +1,49 @@
+{
+  "title": "Components",
+  "description": "HeroUI Native components",
+  "root": true,
+  "icon": "circles-4-diamond",
+  "pages": [
+    "index",
+    "---Components---",
+    "(navigation)/accordion",
+    "(feedback)/alert",
+    "(media)/avatar",
+    "(overlays)/bottom-sheet",
+    "(buttons)/button",
+    "(layout)/card",
+    "(forms)/checkbox",
+    "(data-display)/chip",
+    "(buttons)/close-button",
+    "(forms)/control-field",
+    "(forms)/description",
+    "(overlays)/dialog",
+    "(forms)/field-error",
+    "(forms)/input",
+    "(forms)/input-group",
+    "(forms)/input-otp",
+    "(forms)/label",
+    "(buttons)/link-button",
+    "(navigation)/list-group",
+    "(collections)/menu",
+    "(overlays)/popover",
+    "(utilities)/pressable-feedback",
+    "(forms)/radio-group",
+    "(utilities)/scroll-shadow",
+    "(controls)/slider",
+    "(forms)/search-field",
+    "(forms)/select",
+    "(layout)/separator",
+    "(feedback)/skeleton",
+    "(feedback)/skeleton-group",
+    "(feedback)/spinner",
+    "(layout)/surface",
+    "(controls)/switch",
+    "(navigation)/tabs",
+    "(collections)/tag-group",
+    "(typography)/text",
+    "(forms)/text-area",
+    "(forms)/text-field",
+    "(overlays)/toast"
+  ]
+}
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/animation.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/animation.mdx
new file mode 100644
index 0000000..89444ba
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/animation.mdx
@@ -0,0 +1,206 @@
+---
+title: Animation
+description: Add smooth animations and transitions to HeroUI Native components
+icon: copy-transparent
+---
+
+All animations in HeroUI Native are built with [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/) and gesture control is handled by [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/). It's worth familiarizing yourself with these libraries if you want more control over animations.
+
+## The `animation` Prop
+
+Every animated component in HeroUI Native exposes a single `animation` prop that controls all animations for that component. This prop allows you to modify animation values, timing configurations, layout animations, or completely disable animations.
+
+**Approach**: If you're working with animations, first look for the `animation` prop on the component you're using.
+
+## Modifying Animations
+
+You can customize animations by passing an object to the `animation` prop. Each component exposes different animation properties that you can modify. The approach is simple: if you want to slightly change the animation behavior of already written animations in components, we provide all necessary values for modification. If you want to write your own animations without relying on our written ones, you must create your own custom components with animations.
+
+### Example 1: Simple Value Modification
+
+Modify animation values like scale, opacity, or colors:
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  animation={{
+    scale: {
+      value: [1, 0.9], // [unpressed, pressed]
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'], // [unselected, selected]
+    },
+  }}>
+  <Switch.Thumb />
+</Switch>;
+```
+
+### Example 2: Timing Configuration
+
+Customize animation timing and easing:
+
+```tsx
+import {Accordion} from 'heroui-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      <Accordion.Indicator
+        animation={{
+          rotation: {
+            value: [0, -180],
+            springConfig: {
+              damping: 60,
+              stiffness: 900,
+              mass: 3,
+            },
+          },
+        }}
+      />
+    </Accordion.Trigger>
+  </Accordion.Item>
+</Accordion>;
+```
+
+### Example 3: Layout Animations (Entering/Exiting)
+
+Customize entering and exiting animations using Reanimated's layout animations:
+
+```tsx
+import {Accordion} from 'heroui-native';
+import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
+import {Easing} from 'react-native-reanimated';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Content
+      animation={{
+        entering: {
+          value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
+        },
+      }}>
+      Content here
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>;
+```
+
+### Example 4: State Prop for Granular Control
+
+The `state` prop allows you to disable animations while still customizing animation properties. This is useful when you want to fine-tune component behavior without enabling animations:
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  animation={{
+    state: 'disabled', // Disable animations but allow property customization
+    scale: {
+      value: 0.95, // This value is still respected even though animations are disabled
+    },
+    backgroundColor: {
+      value: ['#172554', '#eab308'],
+    },
+  }}>
+  <Switch.Thumb />
+</Switch>
+```
+
+The `state` prop accepts:
+- `'disabled'`: Disable animations while allowing property customization
+- `'disable-all'`: Disable all animations including children (only available at root level)
+- `boolean`: Simple enable/disable control (`true` enables, `false` disables)
+
+This provides more granular control over animation behavior, allowing you to customize properties without enabling animations.
+
+## Disabling Animations
+
+You can disable animations at different levels using the `animation` prop.
+
+### Disable Options
+
+- `animation={false}` or `animation="disabled"`: Disable animations for the specific component only
+- `animation="disable-all"`: Disable all animations including children (only available at root level)
+- `animation={true}` or `animation={undefined}`: Use default animations
+
+### Component-Level Disabling
+
+Disable animations for a specific component:
+
+```tsx
+<Switch>
+  <Switch.Thumb animation={false} />
+</Switch>
+```
+
+### Root-Level Disabling (`disable-all`)
+
+The `"disable-all"` option is only available at the root level of compound components. When used, it disables all animations including children, even if those children are not part of the compound component structure:
+
+```tsx
+// Disables all animations including Button components inside Card
+<Card animation="disable-all">
+  <Card.Body>
+    <Card.Title>$450</Card.Title>
+    <Card.Description>Living room Sofa</Card.Description>
+  </Card.Body>
+  <Card.Footer className="gap-3">
+    <Button variant="primary">Buy now</Button>
+    <Button variant="ghost">Add to cart</Button>
+  </Card.Footer>
+</Card>
+```
+
+**Important**: `"disable-all"` cascades down to all child components, including standalone components like `Button`, `Spinner`, etc., not just compound component parts.
+
+## Global Animation Configuration
+
+You can disable all HeroUI Native animations globally using the `HeroUINativeProvider`:
+
+```tsx
+import {HeroUINativeProvider} from 'heroui-native';
+
+<HeroUINativeProvider
+  config={{
+    animation: 'disable-all',
+  }}>
+  <App />
+</HeroUINativeProvider>;
+```
+
+This will disable all animations across your entire application, regardless of individual component `animation` prop settings.
+
+## Accessibility
+
+Reduce motion is handled automatically under the hood. When a user enables "Reduce Motion" in their device accessibility settings, all animations are automatically disabled globally. This is handled by the `GlobalAnimationSettingsProvider` which checks `useReducedMotion()` from react-native-reanimated.
+
+You don't need to do anything - the library respects the user's accessibility preferences automatically.
+
+## Animation State Management
+
+We keep disabled state of animations under control internally to ensure they look nice without unpredictable lags or jumps. When animations are disabled, components immediately jump to their final state rather than animating, preventing visual glitches or intermediate states.
+
+## Children Render Function
+
+Many components support a render function pattern for children, which is particularly handy when working with state like `isSelected`:
+
+```tsx
+import {Switch} from 'heroui-native';
+
+<Switch
+  isSelected={isSelected}
+  onSelectedChange={setIsSelected}>
+  {({isSelected, isDisabled}) => (
+    <Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
+  )}
+</Switch>;
+```
+
+This pattern allows you to conditionally render content based on component state, making it easy to create dynamic UIs that respond to selection, disabled states, and other component properties.
+
+## Next Steps
+
+- Learn about [Styling](/docs/native/getting-started/styling) approaches
+- View [Theming](/docs/native/getting-started/theming) documentation
+- Explore [Colors](/docs/native/getting-started/colors) documentation
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/colors.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/colors.mdx
new file mode 100644
index 0000000..5b1de75
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/colors.mdx
@@ -0,0 +1,478 @@
+---
+title: Colors
+description: Color palette and theming system for HeroUI Native
+icon: bucket-paint
+links:
+  themes: true
+  tailwind: theme
+---
+
+import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";
+
+HeroUI Native's color system is built around semantic intent, not visual abundance. Instead of exposing large raw palettes, the system defines a small, meaningful set of color roles that cover the majority of interface needs.
+
+Most colors in the system are derived automatically from a limited number of base values. This allows HeroUI to maintain consistent contrast, hierarchy, and theming behavior while keeping the system easy to reason about and modify.
+
+Colors should communicate purpose and state first. Visual variation comes from scale, emphasis, and context.
+
+## Accent
+
+The accent color represents the primary brand or product identity. It is used to draw attention to key actions, highlights, and moments of emphasis.
+
+Accent should be used intentionally and sparingly. Overuse reduces its impact and can harm visual hierarchy. In most cases, components derive multiple accent-related values (hover, subtle backgrounds, focus states) automatically from the base accent color.
+
+<ColorSectionSideBySide
+  name="Accent"
+  baseVariable="--accent"
+  hoverVariable="--accent"
+  hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
+  foregroundVariable="--accent-foreground"
+  soft={{
+    baseVariable: "--accent",
+    baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
+    hoverVariable: "--accent",
+    hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
+    foregroundVariable: "--accent",
+    foregroundCssValue: "var(--accent)",
+  }}
+/>
+
+## Default (neutrals)
+
+Default colors form the neutral backbone of the system. They are used for most non-emphasized UI elements.
+
+<ColorSectionSideBySide
+  name="Default"
+  baseVariable="--default"
+  hoverVariable="--default"
+  hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
+  foregroundVariable="--default-foreground"
+/>
+
+## Success
+
+Success colors communicate positive outcomes, confirmations, and completed states. They are typically used in feedback components, status indicators, and validation states.
+
+<ColorSectionSideBySide
+  name="Success"
+  baseVariable="--success"
+  hoverVariable="--success"
+  hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
+  foregroundVariable="--success-foreground"
+  soft={{
+    baseVariable: "--success",
+    baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
+    hoverVariable: "--success",
+    hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
+    foregroundVariable: "--success",
+    foregroundCssValue: "var(--success)",
+  }}
+/>
+
+## Warning
+
+Warning colors indicate caution, risk, or actions that require attention but are not destructive. They are commonly used for alerts, messages, and transitional states where the user should pause or review information.
+
+<ColorSectionSideBySide
+  name="Warning"
+  baseVariable="--warning"
+  hoverVariable="--warning"
+  hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
+  foregroundVariable="--warning-foreground"
+  soft={{
+    baseVariable: "--warning",
+    baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
+    hoverVariable: "--warning",
+    hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
+    foregroundVariable: "--warning",
+    foregroundCssValue: "var(--warning)",
+  }}
+/>
+
+## Danger
+
+Danger colors represent destructive, irreversible, or critical actions and states. They should be immediately recognizable and used consistently for errors, destructive buttons, and critical alerts.
+
+<ColorSectionSideBySide
+  name="Danger"
+  baseVariable="--danger"
+  hoverVariable="--danger"
+  hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
+  foregroundVariable="--danger-foreground"
+  soft={{
+    baseVariable: "--danger",
+    baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
+    hoverVariable: "--danger",
+    hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
+    foregroundVariable: "--danger",
+    foregroundCssValue: "var(--danger)",
+  }}
+/>
+
+## Foreground
+
+Foreground colors are used for primary content such as text and icons. These colors are optimized for readability and accessibility and adapt automatically to background and surface contexts. Foreground colors should never be hard-coded at the component level.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Foreground", variable: "--foreground" },
+    { label: "Muted", variable: "--muted" },
+    { label: "Segment", variable: "--segment" },
+    { label: "Overlay", variable: "--overlay" },
+    { label: "Link", variable: "--link" },
+  ]}
+  darkColors={[
+    { label: "Foreground", variable: "--foreground", border: true },
+    { label: "Muted", variable: "--muted", border: true },
+    { label: "Segment", variable: "--segment", border: true },
+    { label: "Overlay", variable: "--overlay", border: true },
+    { label: "Link", variable: "--link", border: true },
+  ]}
+/>
+
+## Background
+
+Background colors define the base canvas of the interface. They establish overall contrast and mood while staying visually quiet.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Background", variable: "--background", border: true },
+    { label: "Secondary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
+    { label: "Tertiary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
+    { label: "Inverse", variable: "--foreground" },
+  ]}
+  darkColors={[
+    { label: "Background", variable: "--background", border: true },
+    { label: "Secondary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true },
+    { label: "Tertiary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true },
+    { label: "Inverse", variable: "--foreground", border: true },
+  ]}
+/>
+
+## Surface
+
+Surface colors sit on top of backgrounds and are used for containers such as cards, panels, modals, and dropdown. Surfaces help create visual separation and hierarchy through elevation, contrast, and layering rather than strong color shifts.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Surface", variable: "--surface", border: true },
+    { label: "Secondary", variable: "--surface-secondary", border: true },
+    { label: "Tertiary", variable: "--surface-tertiary", border: true },
+  ]}
+  darkColors={[
+    { label: "Surface", variable: "--surface", border: true },
+    { label: "Secondary", variable: "--surface-secondary", border: true },
+    { label: "Tertiary", variable: "--surface-tertiary", border: true },
+  ]}
+/>
+
+## Form field
+
+Form field colors are specialized tokens used for inputs, controls, and interactive fields. They account for multiple states such as default, focus, and hover. Isolating them ensures form elements have a distinct visual language from buttons and the rest of the UI.
+
+<ColorSectionFormField
+  colors={{
+    bg: "--field-background",
+    bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
+    placeholder: "--field-placeholder",
+    foreground: "--field-foreground",
+  }}
+/>
+
+## Separator
+
+Separator colors are used for dividers, outlines, and subtle boundaries. They exist to structure content and guide the eye without adding noise. Separator colors should remain low contrast and unobtrusive.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Separator", variable: "--separator", border: true },
+    { label: "Secondary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
+    { label: "Tertiary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
+  ]}
+  darkColors={[
+    { label: "Separator", variable: "--separator", border: true },
+    { label: "Secondary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true },
+    { label: "Tertiary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true },
+  ]}
+/>
+
+## Other
+
+Other colors serve specific utility roles across the interface. They exist to structure content and guide the eye without adding noise.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Border", variable: "--border" },
+    { label: "Backdrop", variable: "--backdrop" },
+    { label: "Overlay", variable: "--overlay", border: true },
+    { label: "Segment", variable: "--segment", border: true },
+  ]}
+  darkColors={[
+    { label: "Border", variable: "--border" },
+    { label: "Backdrop", variable: "--backdrop" },
+    { label: "Overlay", variable: "--overlay", border: true },
+    { label: "Segment", variable: "--segment", border: true },
+  ]}
+/>
+
+## Primitive
+
+Primitive colors are mode agnostic values used as foundations for semantic color tokens. They do not change between light and dark themes.
+
+<ColorSectionPrimitive
+  colors={[
+    { label: "White", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
+    { label: "Black", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
+    { label: "Snow", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
+    { label: "Eclipse", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
+  ]}
+/>
+
+## How to Use Colors
+
+**In your components:**
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-background flex-1 p-4">
+  <Text className="text-foreground mb-4">Content</Text>
+  <Button variant="primary" className="bg-accent">
+    <Button.Label className="text-accent-foreground">Click me</Button.Label>
+  </Button>
+</View>;
+```
+
+**In CSS files:**
+
+```css title="global.css"
+/* Direct CSS variables */
+.container {
+  flex: 1;
+  background-color: var(--accent);
+  width: 50px;
+  height: 50px;
+  border-radius: var(--radius);
+}
+```
+
+## Default Theme
+
+The complete theme definition can be found in ([variables.css](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/variables.css)). This theme automatically switches between light and dark modes through [Uniwind's theming system](https://docs.uniwind.dev/theming/basics), which supports system preferences and programmatic theme switching.
+
+<CollapsibleCode lang="css" code={`  @theme {
+    /* Primitive Colors (Do not change between light and dark) */
+    --white: oklch(100% 0 0);
+    --black: oklch(0% 0 0);
+    --snow: oklch(0.9911 0 0);
+    --eclipse: oklch(0.2103 0.0059 285.89);
+
+    /* Border */
+    --border-width: 1px;
+    --field-border-width: 0px;
+
+    /* Base radius */
+    --radius: 0.5rem;
+    --field-radius: calc(var(--radius) * 1.5);
+
+    /* Opacity */
+    --opacity-disabled: 0.5;
+}
+
+@layer theme {
+    :root {
+      @variant light {
+        /* Base Colors */
+        --background: oklch(0.9702 0 0);
+        --foreground: var(--eclipse);
+
+        /* Surface */
+        --surface: var(--white);
+        --surface-foreground: var(--foreground);
+
+        --surface-secondary: oklch(0.9524 0.0013 286.37);
+        --surface-secondary-foreground: var(--foreground);
+
+        --surface-tertiary: oklch(0.9373 0.0013 286.37);
+        --surface-tertiary-foreground: var(--foreground);
+
+        /* Overlay */
+        --overlay: var(--white);
+        --overlay-foreground: var(--foreground);
+        --backdrop: oklch(0% 0 0 / 20%);
+
+        --muted: oklch(0.5517 0.0138 285.94);
+
+        --default: oklch(94% 0.001 286.375);
+        --default-foreground: var(--eclipse);
+
+        --accent: oklch(0.6204 0.195 253.83);
+        --accent-foreground: var(--snow);
+
+        /* Form Fields */
+        --field-background: var(--white);
+        --field-foreground: oklch(0.2103 0.0059 285.89);
+        --field-placeholder: var(--muted);
+        --field-border: transparent;
+
+        /* Status Colors */
+        --success: oklch(0.7329 0.1935 150.81);
+        --success-foreground: var(--eclipse);
+
+        --warning: oklch(0.7819 0.1585 72.33);
+        --warning-foreground: var(--eclipse);
+
+        --danger: oklch(0.6532 0.2328 25.74);
+        --danger-foreground: var(--snow);
+
+        /* Component Colors */
+        --segment: var(--white);
+        --segment-foreground: var(--eclipse);
+
+        /* Misc Colors */
+        --border: oklch(90% 0.004 286.32);
+        --separator: oklch(74% 0.004 286.32);
+        --focus: var(--accent);
+        --link: var(--foreground);
+      }
+
+      @variant dark {
+        /* Base Colors */
+        --background: oklch(12% 0.005 285.823);
+        --foreground: var(--snow);
+
+        /* Surface */
+        --surface: oklch(0.2103 0.0059 285.89);
+        --surface-foreground: var(--foreground);
+
+        --surface-secondary: oklch(0.257 0.0037 286.14);
+        --surface-secondary-foreground: var(--foreground);
+
+        --surface-tertiary: oklch(0.2721 0.0024 247.91);
+        --surface-tertiary-foreground: var(--foreground);
+
+        /* Overlay */
+        --overlay: oklch(0.2103 0.0059 285.89);
+        --overlay-foreground: var(--foreground);
+        --backdrop: oklch(0% 0 0 / 20%);
+
+        --muted: oklch(70.5% 0.015 286.067);
+
+        --default: oklch(27.4% 0.006 286.033);
+        --default-foreground: var(--snow);
+
+        --accent: oklch(0.6204 0.195 253.83);
+        --accent-foreground: var(--snow);
+
+        /* Form Fields */
+        --field-background: oklch(0.2103 0.0059 285.89);
+        --field-foreground: var(--foreground);
+        --field-placeholder: var(--muted);
+        --field-border: transparent;
+
+        /* Status Colors */
+        --success: oklch(0.7329 0.1935 150.81);
+        --success-foreground: var(--eclipse);
+
+        --warning: oklch(0.8203 0.1388 76.34);
+        --warning-foreground: var(--eclipse);
+
+        --danger: oklch(0.594 0.1967 24.63);
+        --danger-foreground: var(--snow);
+
+        /* Component Colors */
+        --segment: oklch(0.3964 0.01 285.93);
+        --segment-foreground: var(--foreground);
+
+        /* Misc Colors */
+        --border: oklch(28% 0.006 286.033);
+        --separator: oklch(40% 0.006 286.033);
+        --focus: var(--accent);
+        --link: var(--foreground);
+      }
+    }
+  }
+`}
+/>
+
+## Customizing Colors
+
+**Override existing colors:**
+
+```css
+@layer theme {
+  @variant light {
+    /* Override default colors */
+    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
+    --success: oklch(0.65 0.15 155);
+  }
+
+  @variant dark {
+    /* Override dark theme colors */
+    --accent: oklch(0.65 0.25 270);
+    --success: oklch(0.75 0.12 155);
+  }
+}
+```
+
+**Tip:** Convert colors at [oklch.com](https://oklch.com)
+
+**Add your own colors:**
+
+```css
+@layer theme {
+  @variant light {
+    --info: oklch(0.6 0.15 210);
+    --info-foreground: oklch(0.98 0 0);
+  }
+
+  @variant dark {
+    --info: oklch(0.7 0.12 210);
+    --info-foreground: oklch(0.15 0 0);
+  }
+}
+
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+Now you can use it:
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-info p-4 rounded-lg">
+  <Text className="text-info-foreground">Info message</Text>
+</View>;
+```
+
+> **Note**: To learn more about theme variables and how they work in Tailwind CSS v4, see the [Tailwind CSS Theme documentation](https://tailwindcss.com/docs/theme).
+
+## useThemeColor Hook
+
+The `useThemeColor` hook has been enhanced to support multiple colors selection, making it more flexible for complex theming scenarios.
+
+**Multiple Colors Selection:**
+
+You can now select multiple colors at once, which is useful when you need to work with related color values together:
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+// Select multiple colors at once
+const [accent, accentForeground, success, danger] = useThemeColor([
+  'accent',
+  'accentForeground',
+  'success',
+  'danger',
+]);
+
+// Use the selected colors
+<View style={{ backgroundColor: accent }}>
+  <Text style={{ color: accentForeground }}>Accent Text</Text>
+</View>;
+```
+
+This enhancement improves performance when working with multiple color values and makes it easier to manage complex theming scenarios where multiple colors need to be selected and applied together.
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/composition.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/composition.mdx
new file mode 100644
index 0000000..8d26945
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/composition.mdx
@@ -0,0 +1,201 @@
+---
+title: Composition
+description: Build flexible UI with component composition patterns
+icon: layers
+---
+
+HeroUI Native uses composition patterns to create flexible, customizable components. Change the rendered element, compose components together, and maintain full control over markup.
+
+## Compound Components
+
+HeroUI Native components use a compound component pattern with dot notation—components export sub-components as properties (e.g., `Button.Label`, `Dialog.Trigger`, `Accordion.Item`) that work together to form complete UI elements.
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+
+function DialogExample() {
+  return (
+    <Dialog>
+      <Dialog.Trigger>
+        Open Dialog
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Close />
+          <Dialog.Title>Dialog Title</Dialog.Title>
+          <Dialog.Description>Dialog description</Dialog.Description>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+## The asChild Prop
+
+The `asChild` prop lets you change what element a component renders. When `asChild` is true, HeroUI Native clones the child element and merges props instead of rendering its default element.
+
+```tsx
+import { Button, Dialog } from 'heroui-native';
+
+function DialogExample() {
+  return (
+    <Dialog>
+      {/* With asChild: Button becomes the trigger directly, no wrapper element */}
+      <Dialog.Trigger asChild>
+        <Button variant="primary">Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          {/* Dialog.Close can also use asChild */}
+          <Dialog.Close asChild>
+            <Button variant="ghost" size="sm">Cancel</Button>
+          </Dialog.Close>
+          <Dialog.Title>Dialog Title</Dialog.Title>
+          <Dialog.Description>Dialog description</Dialog.Description>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+```
+
+## Custom Components
+
+Create your own components by composing HeroUI Native primitives:
+
+```tsx
+import { Button, Card, Popover } from 'heroui-native';
+import { View } from 'react-native';
+
+// Product card component
+function ProductCard({ title, description, price, onBuy, ...props }) {
+  return (
+    <Card {...props}>
+      <Card.Body>
+        <Card.Title>{price}</Card.Title>
+        <Card.Title>{title}</Card.Title>
+        <Card.Description>{description}</Card.Description>
+      </Card.Body>
+      <Card.Footer>
+        <Button variant="primary" onPress={onBuy}>
+          <Button.Label>Buy now</Button.Label>
+        </Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+
+// Popover button component
+function PopoverButton({ children, popoverContent, ...props }) {
+  return (
+    <Popover>
+      <Popover.Trigger asChild>
+        <Button {...props}>
+          <Button.Label>{children}</Button.Label>
+        </Button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Overlay />
+        <Popover.Content>
+          <Popover.Close />
+          {popoverContent}
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover>
+  );
+}
+
+// Usage
+<ProductCard
+  title="Living room Sofa"
+  description="Perfect for modern spaces"
+  price="$450"
+  onBuy={() => console.log('Buy')}
+/>
+
+<PopoverButton variant="tertiary" popoverContent={
+  <View>
+    <Popover.Title>Information</Popover.Title>
+    <Popover.Description>Additional details here</Popover.Description>
+  </View>
+}>
+  Show Info
+</PopoverButton>
+```
+
+## Custom Variants
+
+Create custom variants using `tailwind-variants` to extend component styling. Note that text color classes must be applied to `Button.Label`, not the parent `Button`:
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const customButtonVariants = tv({
+  base: 'font-semibold rounded-lg',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500',
+      secondary: 'bg-gray-200',
+      danger: 'bg-red-500',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+const customLabelVariants = tv({
+  base: '',
+  variants: {
+    intent: {
+      primary: 'text-white',
+      secondary: 'text-gray-800',
+      danger: 'text-white',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+
+interface CustomButtonProps
+  extends Omit<ButtonRootProps, 'className' | 'variant'>,
+    CustomButtonVariants {
+  className?: string;
+  labelClassName?: string;
+}
+
+export function CustomButton({
+  intent,
+  className,
+  labelClassName,
+  children,
+  ...props
+}: CustomButtonProps) {
+  return (
+    <Button
+      className={customButtonVariants({ intent, className })}
+      {...props}
+    >
+      <Button.Label
+        className={customLabelVariants({ intent, className: labelClassName })}
+      >
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+## Next Steps
+
+- Learn about [Styling](/docs/native/getting-started/styling) system
+- Explore [Theming](/docs/native/getting-started/theming) documentation
+- Explore [Animation](/docs/native/getting-started/animation) options
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/portal.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/portal.mdx
new file mode 100644
index 0000000..8e24ec8
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/portal.mdx
@@ -0,0 +1,144 @@
+---
+title: Portal
+icon: windows
+---
+
+Portals let you render its children into a different part of your app. This is particularly useful for components that need to render above other content, such as modals, overlays, and popups.
+
+## Default Setup
+
+By default, the `PortalHost` is included in the `HeroUINativeProvider`, so there is no need to add it manually. The provider automatically sets up the portal system for all components that use portals.
+
+## Advanced Use Cases
+
+For advanced use cases, you can import `Portal` and `PortalHost` directly from `heroui-native` to create custom portal implementations:
+
+```tsx
+import { Portal, PortalHost } from "heroui-native";
+import { View, Text } from "react-native";
+
+function AppLayout() {
+  return (
+    <View className="flex-1">
+      <View className="p-5">
+        <Text>Header Content</Text>
+      </View>
+      
+      <View className="flex-1 p-5">
+        <Text>Main Content Area</Text>
+        <CustomNotification />
+      </View>
+      
+      {/* Portal host positioned at the top of the screen */}
+      <PortalHost name="notification-host" />
+    </View>
+  );
+}
+
+function CustomNotification() {
+  return (
+    <Portal name="notification-portal" hostName="notification-host">
+      <View className="absolute top-0 left-0 right-0 bg-blue-500 p-4">
+        <Text>This notification appears at the top via Portal</Text>
+      </View>
+    </Portal>
+  );
+}
+```
+
+In this example, the `CustomNotification` component uses a `Portal` to render its content at the location of the `PortalHost`, which is positioned at the top of the screen. This allows the notification to appear above all other content regardless of where it's defined in the component tree.
+
+## State Management Considerations
+
+State changes in parent components can cause unexpected issues with components rendered inside portals. For example, when a text input is placed directly inside a portal and the parent component re-renders, it can reset the input's auto-suggestions or cause other UI disruptions.
+
+To avoid this, keep the state of interactive components (like text inputs) inside the portal by creating a separate component for the portal content. This isolates the state from parent re-renders.
+
+### Example Pattern
+
+```tsx
+// ❌ Problematic: State in parent causes re-renders that affect portal content
+function ParentComponent() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [inputValue, setInputValue] = useState(""); // State in parent
+  
+  return (
+    <Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
+      <Dialog.Trigger>
+        <Button>Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Input 
+          value={inputValue} 
+          onChangeText={setInputValue} 
+          // Parent re-renders reset auto-suggestions
+        />
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+
+// ✅ Correct: State managed inside separate component within portal
+function ParentComponent() {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  
+  return (
+    <Dialog isOpen={dialogOpen} onOpenChange={setDialogOpen}>
+      <Dialog.Trigger>
+        <Button>Open Dialog</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <DialogFormContent 
+          onClose={() => setDialogOpen(false)} 
+          // Form state isolated from parent
+        />
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+
+function DialogFormContent({ onClose }: { onClose: () => void }) {
+  const [inputValue, setInputValue] = useState(""); // State inside portal
+  const [error, setError] = useState("");
+  
+  return (
+    <Dialog.Content>
+      <Input 
+        value={inputValue} 
+        onChangeText={setInputValue}
+        // Auto-suggestions preserved during parent re-renders
+      />
+      <FieldError>{error}</FieldError>
+      <Button onPress={onClose}>Close</Button>
+    </Dialog.Content>
+  );
+}
+```
+
+In the correct pattern, the `DialogFormContent` component manages its own state independently of the parent component. This ensures that parent re-renders (such as when `dialogOpen` changes) don't affect the input's internal state, preserving auto-suggestions and other input behaviors.
+
+## API Reference
+
+### PortalHost
+
+By default, children of all Portal components will be rendered as its own children.
+
+| Prop | Type     | Note                                                      |
+|------|----------|-----------------------------------------------------------|
+| name | `string` | Provide when it is used as a custom host (optional)       |
+
+### Portal
+
+| Prop      | Type     | Note                                                      |
+|-----------|----------|-----------------------------------------------------------|
+| name*     | `string` | Unique value otherwise the portal with the same name will replace the original portal |
+| hostName  | `string` | Provide when its children are to be rendered in a custom host (optional) |
+| children  | `React.ReactNode` | The content to render in the portal |
+
+\* Required prop
+
+## Related
+
+- [Quick Start](/docs/native/getting-started/quick-start) - Basic setup guide
+- View [Provider](/docs/native/getting-started/provider) documentation
+
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/provider.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/provider.mdx
new file mode 100644
index 0000000..118e409
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/provider.mdx
@@ -0,0 +1,493 @@
+---
+title: Provider
+description: Configure HeroUI Native provider with text, text input, animation, and toast settings
+icon: chevrons-expand-horizontal
+---
+
+The `HeroUINativeProvider` is the root provider component that configures and initializes HeroUI Native in your React Native application. It provides global configuration and portal management for your application.
+
+## Overview
+
+The provider serves as the main entry point for HeroUI Native, wrapping your application with essential contexts and configurations:
+
+- **Safe Area Insets**: Automatically handles safe area insets updates via `SafeAreaListener` and syncs them with Uniwind for use in Tailwind classes (e.g., `pb-safe-offset-3`)
+- **Text Configuration**: Global text component settings for consistency across all HeroUI components
+- **Text Input Configuration**: Global text input settings for consistency across all HeroUI input components
+- **Animation Configuration**: Global animation control to disable all animations across the application
+- **Toast Configuration**: Global toast system configuration including insets, default props, and wrapper components
+- **Portal Management**: Handles overlays, modals, and other components that render on top of the app hierarchy
+
+## Basic Setup
+
+Wrap your application root with the provider:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## Configuration Options
+
+The provider accepts a `config` prop with the following options:
+
+### Text Component Configuration
+
+Global settings for all Text components within HeroUI Native. These props are carefully selected to include only those that make sense to configure globally across all Text components in the application:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  textProps: {
+    // Disable font scaling for accessibility
+    allowFontScaling: false,
+
+    // Auto-adjust font size to fit container
+    adjustsFontSizeToFit: false,
+
+    // Maximum font size multiplier when scaling
+    maxFontSizeMultiplier: 1.5,
+
+    // Minimum font scale (iOS only, 0.01-1.0)
+    minimumFontScale: 0.5,
+  },
+};
+
+export default function App() {
+  return (
+    <HeroUINativeProvider config={config}>
+      {/* Your app content */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+### Text Input Component Configuration
+
+Global settings for all TextInput-based components within HeroUI Native (e.g. Input, TextArea, SearchField, InputGroup, InputOTP). These props are carefully selected to include only those that make sense to configure globally across all inputs in the application:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  textInputProps: {
+    // Respect Text Size accessibility settings
+    allowFontScaling: false,
+
+    // Maximum font size multiplier when allowFontScaling is enabled
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function App() {
+  return (
+    <HeroUINativeProvider config={config}>
+      {/* Your app content */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+<Callout type="info">
+  **Note**: These props are applied as defaults. Any prop passed directly to an individual input component overrides the corresponding global value.
+</Callout>
+
+### Animation Configuration
+
+Global animation configuration for the entire application:
+
+```tsx
+const config: HeroUINativeConfig = {
+  // Disable all animations across the application (cascades to all children)
+  animation: 'disable-all',
+};
+```
+
+<Callout type="warning">
+  **Note**: When set to `'disable-all'`, all animations across the application will be disabled. This is useful for accessibility or performance optimization.
+</Callout>
+
+### Developer Information Configuration
+
+Control developer-facing informational messages displayed in the console:
+
+```tsx
+const config: HeroUINativeConfig = {
+  devInfo: {
+    // Disable styling principles information message
+    stylingPrinciples: false,
+  },
+};
+```
+
+<Callout type="info">
+  **Note**: By default, informational messages are enabled. Set `stylingPrinciples: false` to disable the styling principles message that appears in the console during development.
+</Callout>
+
+### Toast Configuration
+
+Configure the global toast system including insets, default props, and wrapper components. You can also disable the toast provider entirely:
+
+**Option 1: Disable Toast Provider**
+
+```tsx
+const config: HeroUINativeConfig = {
+  // Disable toast provider entirely
+  toast: false,
+  // or
+  toast: 'disabled',
+};
+```
+
+<Callout type="info">
+  **Note**: When toast is disabled (`false` or `'disabled'`), the `ToastProvider` will not be rendered, and toast functionality will not be available in your application.
+</Callout>
+
+**Option 2: Configure Toast Provider**
+
+```tsx
+import { KeyboardAvoidingView } from 'react-native';
+
+const config: HeroUINativeConfig = {
+  toast: {
+    // Global toast configuration (used as defaults for all toasts)
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+      isSwipeable: true,
+      animation: true,
+    },
+    // Insets for spacing from screen edges (added to safe area insets)
+    insets: {
+      top: 0,      // Default: iOS = 0, Android = 12
+      bottom: 6,   // Default: iOS = 6, Android = 12
+      left: 12,    // Default: 12
+      right: 12,   // Default: 12
+    },
+    // Maximum number of visible toasts before opacity starts fading
+    maxVisibleToasts: 3,
+    // Custom wrapper function to wrap the toast content
+    contentWrapper: (children) => (
+      <KeyboardAvoidingView
+        behavior="padding"
+        keyboardVerticalOffset={24}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+  },
+};
+```
+
+## Complete Example
+
+Here's a comprehensive example showing all configuration options:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+const config: HeroUINativeConfig = {
+  // Global text configuration
+  textProps: {
+    minimumFontScale: 0.5,
+    maxFontSizeMultiplier: 1.5,
+    allowFontScaling: true,
+    adjustsFontSizeToFit: false,
+  },
+  // Global text input configuration
+  textInputProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  // Global animation configuration
+  animation: 'disable-all', // Optional: disable all animations
+  // Developer information messages configuration
+  devInfo: {
+    stylingPrinciples: true, // Optional: disable styling principles message
+  },
+  // Global toast configuration
+  // Option 1: Configure toast with custom settings
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+    maxVisibleToasts: 3,
+  },
+  // Option 2: Disable toast entirely
+  // toast: false,
+  // or
+  // toast: 'disabled',
+};
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider config={config}>
+        <YourApp />
+      </HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## Integration with Expo Router
+
+When using Expo Router, wrap your root layout:
+
+```tsx
+// app/_layout.tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+import { Stack } from 'expo-router';
+
+const config: HeroUINativeConfig = {
+  textProps: {
+    minimumFontScale: 0.5,
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function RootLayout() {
+  return (
+    <HeroUINativeProvider config={config}>
+      <Stack />
+    </HeroUINativeProvider>
+  );
+}
+```
+
+## Architecture
+
+### Provider Hierarchy
+
+The `HeroUINativeProvider` internally composes multiple providers:
+
+```
+HeroUINativeProvider
+├── SafeAreaListener (handles safe area insets updates)
+│   └── GlobalAnimationSettingsProvider (animation configuration)
+│       └── TextComponentProvider (text configuration)
+│           └── TextInputComponentProvider (text input configuration)
+│               └── ToastProvider (toast configuration, conditionally rendered)
+│                   └── Your App
+│                   └── PortalHost (for overlays)
+```
+
+<Callout type="info">
+  **Note**: The `ToastProvider` is conditionally rendered based on the `toast` configuration. If `toast` is set to `false` or `'disabled'`, the `ToastProvider` will not be rendered, and the app content and `PortalHost` will be rendered directly under `TextInputComponentProvider`.
+</Callout>
+
+### Safe Area Insets Handling
+
+The provider automatically wraps your application with [`SafeAreaListener`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-listener) from `react-native-safe-area-context`. This component listens to safe area insets and frame changes without triggering re-renders, and automatically updates Uniwind with the latest insets via the `onChange` callback.
+
+## Raw Provider
+
+`HeroUINativeProviderRaw` is a lightweight variant of `HeroUINativeProvider` designed for bundle optimization. It excludes `ToastProvider` and `PortalHost`, giving you a bare minimum starting point where you only install and add what you actually need.
+
+### When to Use
+
+Use `HeroUINativeProviderRaw` when you want full control over which dependencies are included in your bundle. With the raw provider imported from `heroui-native/provider-raw`, the following dependencies are optional and only required if you use the corresponding components:
+
+- **react-native-screens** -- required for overlay components (Popover, Dialog)
+- **@gorhom/bottom-sheet** -- required for BottomSheet component
+- **react-native-svg** -- required for components that use icons (Accordion, Alert, Checkbox, etc.)
+
+### Setup
+
+```tsx
+import {
+  HeroUINativeProviderRaw,
+  type HeroUINativeConfigRaw,
+} from 'heroui-native/provider-raw';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+const config: HeroUINativeConfigRaw = {
+  textProps: {
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProviderRaw config={config}>
+        {/* Your app content */}
+      </HeroUINativeProviderRaw>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+### Adding Toast and Portal Manually
+
+If you need toast or portal functionality with the raw provider, add them yourself:
+
+```tsx
+import { HeroUINativeProviderRaw } from 'heroui-native/provider-raw';
+import { PortalHost } from 'heroui-native/portal';
+import { ToastProvider } from 'heroui-native/toast';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProviderRaw>
+        <ToastProvider>
+          {/* Your app content */}
+          <PortalHost />
+        </ToastProvider>
+      </HeroUINativeProviderRaw>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+### Provider Hierarchy
+
+```
+HeroUINativeProviderRaw
+├── SafeAreaListener (handles safe area insets updates)
+│   └── GlobalAnimationSettingsProvider (animation configuration)
+│       └── TextComponentProvider (text configuration)
+│           └── TextInputComponentProvider (text input configuration)
+│               └── Your App
+```
+
+## Best Practices
+
+### 1. Single Provider Instance
+
+Always use a single `HeroUINativeProvider` at the root of your app. Don't nest multiple providers:
+
+```tsx
+// ❌ Bad
+<HeroUINativeProvider>
+  <SomeComponent>
+    <HeroUINativeProvider> {/* Don't do this */}
+      <AnotherComponent />
+    </HeroUINativeProvider>
+  </SomeComponent>
+</HeroUINativeProvider>
+
+// ✅ Good
+<HeroUINativeProvider>
+  <SomeComponent>
+    <AnotherComponent />
+  </SomeComponent>
+</HeroUINativeProvider>
+```
+
+### 2. Configuration Object
+
+Define your configuration outside the component to prevent recreating on each render:
+
+```tsx
+// ❌ Bad
+function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textProps: {
+          /* inline config */
+        },
+      }}
+    >
+      {/* ... */}
+    </HeroUINativeProvider>
+  );
+}
+
+// ✅ Good
+const config: HeroUINativeConfig = {
+  textProps: {
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+function App() {
+  return (
+    <HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
+  );
+}
+```
+
+### 3. Text Configuration
+
+Consider accessibility when configuring text props:
+
+```tsx
+const config: HeroUINativeConfig = {
+  textProps: {
+    // Allow font scaling for accessibility
+    allowFontScaling: true,
+    // But limit maximum scale
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+```
+
+## TypeScript Support
+
+The provider is fully typed. Import types for better IDE support:
+
+```tsx
+import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  // Full type safety and autocomplete
+  textProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  textInputProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  animation: 'disable-all', // Optional: disable all animations
+  devInfo: {
+    stylingPrinciples: true, // Optional: disable styling principles message
+  },
+  // Toast configuration options:
+  // - false or 'disabled': Disable toast provider
+  // - ToastProviderProps object: Configure toast settings
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+  },
+};
+```
+
+## Related
+
+- [Quick Start](/docs/native/getting-started/quick-start) - Basic setup guide
+- [Theming](/docs/native/getting-started/theming) - Customize colors and themes
+- [Styling](/docs/native/getting-started/styling) - Style components with Tailwind
+
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/styling.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/styling.mdx
new file mode 100644
index 0000000..8b12e46
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/styling.mdx
@@ -0,0 +1,371 @@
+---
+title: Styling
+description: Style HeroUI Native components with Tailwind or StyleSheet API
+icon: brush
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI Native components provide flexible styling options: Tailwind CSS utilities, StyleSheet API, and render props for dynamic styling.
+
+## Styling Principles
+
+HeroUI Native is built with `className` as the go-to styling solution. You can use Tailwind CSS classes via the `className` prop on all components.
+
+**StyleSheet precedence:** The `style` prop (StyleSheet API) can be used and has precedence over `className` when both are provided. This allows you to override Tailwind classes when needed.
+
+**Animated styles:** Some style properties are animated using `react-native-reanimated` and, like StyleSheet styles, they have precedence over `className`. To identify which styles are animated and cannot be used via `className`:
+
+- **Hover over `className` in your IDE** - The TypeScript definitions will show which properties are available
+- **Check component documentation** - Each component page includes a link to the component's style source at the top, which contains notes about animated properties
+
+**Customizing animated styles:** If styles are occupied by animation, you can modify them via the `animation` prop on components that support it.
+
+## Basic Styling
+
+**Using className:** All HeroUI Native components accept `className` props:
+
+```tsx
+import { Button } from 'heroui-native';
+
+<Button className="bg-accent px-6 py-3 rounded-lg">
+  <Button.Label>Custom Button</Button.Label>
+</Button>;
+```
+
+**Using style:** Components also accept inline styles via the `style` prop:
+
+```tsx
+import { Button } from 'heroui-native';
+
+<Button style={{ backgroundColor: '#8B5CF6', paddingHorizontal: 24 }}>
+  <Button.Label>Styled Button</Button.Label>
+</Button>;
+```
+
+## Render Props
+
+Use a render function to access component state and customize content dynamically:
+
+```tsx
+import { RadioGroup, Label, cn } from 'heroui-native';
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroup.Item value="option1">
+    {({ isSelected, isInvalid, isDisabled }) => (
+      <>
+        <Label
+          className={cn(
+            'text-foreground',
+            isSelected && 'text-accent font-semibold'
+          )}
+        >
+          Option 1
+        </Label>
+        <Radio
+          className={cn(
+            'border-2 rounded-full',
+            isSelected && 'border-accent bg-accent'
+          )}
+        >
+          {isSelected && <CustomIcon />}
+        </Radio>
+      </>
+    )}
+  </RadioGroup.Item>
+</RadioGroup>;
+```
+
+## Creating Wrapper Components
+
+Create reusable custom components using [tailwind-variants](https://tailwind-variants.org/)—a Tailwind CSS first-class variant API:
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const customButtonVariants = tv({
+  base: 'font-semibold rounded-lg',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500',
+      secondary: 'bg-gray-200',
+      danger: 'bg-red-500',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+const customLabelVariants = tv({
+  base: '',
+  variants: {
+    intent: {
+      primary: 'text-white',
+      secondary: 'text-gray-800',
+      danger: 'text-white',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+
+interface CustomButtonProps
+  extends Omit<ButtonRootProps, 'className' | 'variant'>,
+    CustomButtonVariants {
+  className?: string;
+  labelClassName?: string;
+}
+
+export function CustomButton({
+  intent,
+  className,
+  labelClassName,
+  children,
+  ...props
+}: CustomButtonProps) {
+  return (
+    <Button
+      className={customButtonVariants({ intent, className })}
+      {...props}
+    >
+      <Button.Label
+        className={customLabelVariants({ intent, className: labelClassName })}
+      >
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+## Using Component classNames
+
+Each HeroUI Native component exports a `classNames` object that contains the same styling functions used internally by the component. This is particularly useful when you want to style your own custom components to match the appearance of HeroUI Native components.
+
+For example, you can style a custom `Link` component to look like a `Button`:
+
+```tsx
+import { buttonClassNames, cn } from 'heroui-native';
+import { Pressable, Text } from 'react-native';
+
+interface LinkProps {
+  href: string;
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function Link({
+  href,
+  variant = 'primary',
+  size = 'md',
+  children,
+  className,
+}: LinkProps) {
+  return (
+    <Pressable
+      className={cn(
+        buttonClassNames.root({ variant, size }),
+        className
+      )}
+      onPress={() => {
+        // Handle navigation
+      }}
+    >
+      <Text className={buttonClassNames.label({ variant, size })}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}
+```
+
+**Available classNames exports:**
+
+Each component exports its `classNames` object. For example:
+- `buttonClassNames` - Contains `root` and `label` functions
+- `cardClassNames` - Contains `root`, `header`, `body`, `footer`, `label`, and `description` functions
+- `chipClassNames` - Contains `root` and `label` functions
+- And many more...
+
+**Usage pattern:**
+
+```tsx
+import { buttonClassNames } from 'heroui-native';
+
+// Use with variant and size options
+const rootClasses = buttonClassNames.root({
+  variant: 'primary',
+  size: 'md',
+  className: 'custom-class', // Optional: merge with your own classes
+});
+
+const labelClasses = buttonClassNames.label({
+  variant: 'primary',
+  size: 'md',
+});
+```
+
+The `classNames` functions accept the same variant props as the components themselves, allowing you to maintain visual consistency across your custom components and HeroUI Native components.
+
+
+## Responsive Design
+
+HeroUI Native supports Tailwind's responsive breakpoint system via [Uniwind](https://docs.uniwind.dev/breakpoints). Use breakpoint prefixes like `sm:`, `md:`, `lg:`, and `xl:` to apply styles conditionally based on screen width.
+
+**Mobile-first approach:** Start with mobile styles (no prefix), then use breakpoints to enhance for larger screens.
+
+### Responsive Typography and Spacing
+
+```tsx
+import { Button } from 'heroui-native';
+import { View, Text } from 'react-native';
+
+<View className="px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
+  <Text className="text-2xl sm:text-3xl lg:text-4xl font-bold mb-4 sm:mb-6">
+    Responsive Heading
+  </Text>
+  <Button className="px-3 sm:px-4 lg:px-6">
+    <Button.Label className="text-sm sm:text-base lg:text-lg">
+      Responsive Button
+    </Button.Label>
+  </Button>
+</View>;
+```
+
+### Responsive Layouts
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="flex-row flex-wrap">
+  {/* Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns */}
+  <View className="w-full sm:w-1/2 lg:w-1/3 p-2">
+    <View className="bg-accent p-4 rounded-lg">
+      <Text className="text-accent-foreground">Item 1</Text>
+    </View>
+  </View>
+</View>;
+```
+
+**Default breakpoints:**
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+- `2xl`: 1536px
+
+For custom breakpoints and more details, see the [Uniwind breakpoints documentation](https://docs.uniwind.dev/breakpoints).
+
+## Utilities
+
+HeroUI Native provides utility functions to assist with styling components.
+
+### cn Utility
+
+The `cn` utility function merges Tailwind CSS classes with proper conflict resolution. It's particularly useful when combining conditional classes or merging classes from props:
+
+```tsx
+import { cn } from 'heroui-native';
+import { View } from 'react-native';
+
+function MyComponent({ className, isActive }) {
+  return (
+    <View
+      className={cn(
+        'bg-background p-4 rounded-lg',
+        'border border-separator',
+        isActive && 'bg-accent',
+        className
+      )}
+    />
+  );
+}
+```;
+
+
+The `cn` utility is powered by `tailwind-variants` and includes:
+
+- Automatic Tailwind class merging (`twMerge: true`)
+- Custom opacity class group support
+- Proper conflict resolution (later classes override earlier ones)
+
+**Example with conflicts:**
+
+```tsx
+// 'bg-accent' overrides 'bg-background'
+cn('bg-background p-4', 'bg-accent');
+// Result: 'p-4 bg-accent'
+```
+
+### useThemeColor Hook
+
+Retrieves theme color values from CSS variables. Supports both single color and multiple colors for efficient batch retrieval.
+
+**Single color usage:**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const accentColor = useThemeColor('accent');
+  const dangerColor = useThemeColor('danger');
+
+  return (
+    <View style={{ borderColor: accentColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```;
+
+**Multiple colors usage (more efficient):**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const [accentColor, backgroundColor, dangerColor] = useThemeColor([
+    'accent',
+    'background',
+    'danger',
+  ]);
+
+  return (
+    <View style={{ borderColor: accentColor, backgroundColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```;
+
+**Type signatures:**
+
+```tsx
+// Single color
+useThemeColor(themeColor: ThemeColor): string
+
+// Multiple colors (with type inference for tuples)
+useThemeColor<T extends readonly [ThemeColor, ...ThemeColor[]]>(
+  themeColor: T
+): CreateStringTuple<T['length']>
+
+// Multiple colors (array)
+useThemeColor(themeColor: ThemeColor[]): string[]
+```
+
+Available theme colors include: `background`, `foreground`, `surface`, `accent`, `default`, `success`, `warning`, `danger`, and all their variants (hover, soft, foreground, etc.), plus semantic colors like `muted`, `border`, `separator`, `field`, `overlay`, and more.
+
+## Next Steps
+
+- Learn about [Animation](/docs/native/getting-started/animation) techniques
+- Explore [Theming](/docs/native/getting-started/theming) system
+- Explore [Colors](/docs/native/getting-started/colors) documentation
diff --git a/apps/docs/content/docs/en/native/getting-started/(handbook)/theming.mdx b/apps/docs/content/docs/en/native/getting-started/(handbook)/theming.mdx
new file mode 100644
index 0000000..8bec50c
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(handbook)/theming.mdx
@@ -0,0 +1,499 @@
+---
+title: Theming
+description: Customize HeroUI Native's design system with CSS variables and global styles
+icon: palette
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI Native uses CSS variables for theming. Customize everything from colors to component styles using standard CSS.
+
+## How It Works
+
+HeroUI Native's theming system is built on top of [Tailwind CSS v4](https://tailwindcss.com/docs/theme)'s theme via [Uniwind](https://uniwind.dev/). When you import `heroui-native/styles`, it uses Tailwind's built-in color palettes, maps them to semantic variables, automatically switches between light and dark themes, and uses CSS layers and the `@theme` directive for organization.
+
+**Naming pattern:**
+
+- Colors without a suffix are backgrounds (e.g., `--accent`)
+- Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)
+
+## Quick Start
+
+**Apply colors in your components:**
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-background flex-1">
+  <Text className="text-foreground">Your app content</Text>
+</View>;
+```
+
+**Switch themes:**
+
+HeroUI Native automatically supports dark mode through [Uniwind](https://docs.uniwind.dev/theming/basics). The theme switches between light and dark variants based on system preferences or manual selection:
+
+```tsx
+import { Uniwind, useUniwind } from 'uniwind';
+import { Button } from 'heroui-native';
+
+function ThemeToggle() {
+  const { theme } = useUniwind();
+
+  return (
+    <Button
+      onPress={() => Uniwind.setTheme(theme === 'light' ? 'dark' : 'light')}
+    >
+      <Button.Label>
+        Toggle {theme === 'light' ? 'Dark' : 'Light'} Mode
+      </Button.Label>
+    </Button>
+  );
+}
+```
+
+**Override colors:**
+
+```css
+/* global.css */
+@layer theme {
+  @variant light {
+    /* Override any color variable */
+    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
+    --success: oklch(0.65 0.15 155);
+  }
+
+  @variant dark {
+    --accent: oklch(0.65 0.25 270);
+    --success: oklch(0.75 0.12 155);
+  }
+}
+```
+
+> **Note**: See [Colors](/docs/native/getting-started/colors) for the complete color palette and visual reference.
+
+**Create your own theme:**
+
+Create multiple themes using Uniwind's variant system. For complete custom theme documentation, see the [Uniwind Custom Themes Guide](https://docs.uniwind.dev/theming/custom-themes).
+
+<Callout type="warning">
+  **Important:** All themes must define the same variables. See the [Default Theme](/docs/native/getting-started/colors#default-theme) section for a complete list of all required variables.
+</Callout>
+
+```css
+/* global.css */
+@layer theme {
+  :root {
+    @variant ocean-light {
+      /* Base Colors */
+      --background: oklch(0.95 0.02 230);
+      --foreground: oklch(0.25 0.04 230);
+
+     /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.98 0.01 230);
+      --surface-foreground: oklch(0.3 0.045 230);
+
+      --surface-secondary: oklch(0.96 0.012 230);
+      --surface-secondary-foreground: oklch(0.3 0.045 230);
+
+      --surface-tertiary: oklch(0.94 0.015 230);
+      --surface-tertiary-foreground: oklch(0.3 0.045 230);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
+      --overlay: oklch(0.998 0.003 230);
+      --overlay-foreground: oklch(0.3 0.045 230);
+      --backdrop: oklch(0% 0 0 / 20%);
+
+      --muted: oklch(0.55 0.035 230);
+
+      --default: oklch(0.94 0.018 230);
+      --default-foreground: oklch(0.4 0.05 230);
+
+      /* Accent */
+      --accent: oklch(0.6 0.2 230);
+      --accent-foreground: oklch(0.98 0.005 230);
+
+      /* Form Field Defaults - Colors */
+      --field-background: oklch(0.98 0.01 230);
+      --field-foreground: oklch(0.25 0.04 230);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status Colors */
+      --success: oklch(0.72 0.14 165);
+      --success-foreground: oklch(0.25 0.08 165);
+
+      --warning: oklch(0.78 0.12 85);
+      --warning-foreground: oklch(0.3 0.08 85);
+
+      --danger: oklch(0.68 0.18 15);
+      --danger-foreground: oklch(0.98 0.005 15);
+
+      /* Component Colors */
+      --segment: oklch(0.98 0.01 230);
+      --segment-foreground: oklch(0.25 0.04 230);
+
+      /* Misc Colors */
+      --border: oklch(0 0 0 / 0%);
+      --separator: oklch(0.91 0.015 230);
+      --focus: var(--accent);
+      --link: oklch(0.62 0.17 230);
+
+      /* Shadows */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      --overlay-shadow:
+        0 2px 8px 0 rgba(0, 0, 0, 0.02), 0 -6px 12px 0 rgba(0, 0, 0, 0.01),
+        0 14px 28px 0 rgba(0, 0, 0, 0.03);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+    }
+
+    @variant ocean-dark {
+      /* Base Colors */
+      --background: oklch(0.15 0.04 230);
+      --foreground: oklch(0.94 0.01 230);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.2 0.048 230);
+      --surface-foreground: oklch(0.9 0.015 230);
+
+      --surface-secondary: oklch(0.24 0.046 230);
+      --surface-secondary-foreground: oklch(0.9 0.015 230);
+
+      --surface-tertiary: oklch(0.27 0.044 230);
+      --surface-tertiary-foreground: oklch(0.9 0.015 230);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
+      --overlay: oklch(0.23 0.045 230);
+      --overlay-foreground: oklch(0.9 0.015 230);
+      --backdrop: oklch(0% 0 0 / 20%);
+
+      --muted: oklch(0.5 0.04 230);
+
+      --default: oklch(0.25 0.05 230);
+      --default-foreground: oklch(0.88 0.018 230);
+
+      /* Accent */
+      --accent: oklch(0.72 0.21 230);
+      --accent-foreground: oklch(0.15 0.04 230);
+
+      /* Form Field Defaults - Colors */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status Colors */
+      --success: oklch(0.68 0.16 165);
+      --success-foreground: oklch(0.95 0.008 165);
+
+      --warning: oklch(0.75 0.14 90);
+      --warning-foreground: oklch(0.2 0.04 90);
+
+      --danger: oklch(0.65 0.2 20);
+      --danger-foreground: oklch(0.95 0.008 20);
+
+      /* Component Colors */
+      --segment: oklch(0.22 0.046 230);
+      --segment-foreground: oklch(0.9 0.015 230);
+
+      /* Misc Colors */
+      --border: oklch(0 0 0 / 0%);
+      --separator: oklch(0.28 0.045 230);
+      --focus: var(--accent);
+      --link: oklch(0.75 0.18 230);
+
+      /* Shadows */
+      --surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+      --overlay-shadow: 0 0 1px 0 rgba(255, 255, 255, 0.3) inset;
+      --field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+    }
+  }
+}
+```
+
+**Important:** When adding custom themes, you must register them in your Metro config:
+
+```js
+// metro.config.js
+const { withUniwindConfig } = require('uniwind/metro');
+const {
+  wrapWithReanimatedMetroConfig,
+} = require('react-native-reanimated/metro-config');
+
+const config = {
+  // ... your existing config
+};
+
+module.exports = withUniwindConfig(wrapWithReanimatedMetroConfig(config), {
+  cssEntryFile: './global.css',
+  dtsFile: './src/uniwind.d.ts',
+  extraThemes: ['ocean-light', 'ocean-dark'],
+});
+```
+
+Apply themes in your app:
+
+```tsx
+import { Uniwind } from 'uniwind';
+import { Button } from 'heroui-native';
+
+function App() {
+  return (
+    <Button onPress={() => Uniwind.setTheme('ocean-light')}>
+      <Button.Label>Ocean Theme</Button.Label>
+    </Button>
+  );
+}
+```
+
+## Adding Custom Colors
+
+Add your own semantic colors to the theme:
+
+```css
+@layer theme {
+  @variant light {
+    --info: oklch(0.6 0.15 210);
+    --info-foreground: oklch(0.98 0 0);
+  }
+
+  @variant dark {
+    --info: oklch(0.7 0.12 210);
+    --info-foreground: oklch(0.15 0 0);
+  }
+}
+
+/* Make the color available to Tailwind */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+Now use it in your components:
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="bg-info p-4 rounded-lg">
+  <Text className="text-info-foreground">Info message</Text>
+</View>;
+```
+
+## Custom Fonts
+
+To use a custom font family in your app, you need to load the fonts and then override the font CSS variables.
+
+### 1. Load Fonts in Your App
+
+First, load your custom fonts (using Expo's `useFonts` hook for example):
+
+```tsx
+import { useFonts } from 'expo-font';
+import { HeroUINativeProvider } from 'heroui-native';
+import {
+  YourFont_400Regular,
+  YourFont_500Medium,
+  YourFont_600SemiBold,
+} from '@expo-google-fonts/your-font';
+
+export default function App() {
+  const [fontsLoaded] = useFonts({
+    YourFont_400Regular,
+    YourFont_500Medium,
+    YourFont_600SemiBold,
+  });
+
+  if (!fontsLoaded) {
+    return null; // Or return a loading screen
+  }
+
+  return <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>;
+}
+```
+
+### 2. Configure Font CSS Variables
+
+After loading the fonts, override the font CSS variables in your `global.css` file:
+
+```css
+@theme {
+  --font-normal: 'YourFont-400Regular';
+  --font-medium: 'YourFont-500Medium';
+  --font-semibold: 'YourFont-600SemiBold';
+}
+```
+
+**Note:** The font names in CSS variables should match the PostScript names of your loaded fonts. Check your font package documentation or use the font names exactly as they appear in your `useFonts` hook.
+
+All HeroUI Native components automatically use these font variables, ensuring consistent typography throughout your app.
+
+## Variables Reference
+
+HeroUI defines three types of variables:
+
+1. **Base Variables** — Non-changing values like `--white`, `--black`
+2. **Theme Variables** — Colors that change between light/dark themes
+3. **Calculated Variables** — Automatically generated hover (pressed) states and size variants
+
+For a complete reference, see: [Colors Documentation](/docs/native/getting-started/colors), [Default Theme Variables](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/variables.css), [Shared Theme Utilities](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/theme.css)
+
+**Calculated variables (Tailwind):**
+
+We use Tailwind's `@theme` directive to automatically create calculated variables for hover (pressed) states and radius variants. These are defined in [theme.css](https://github.com/heroui-inc/heroui-native/blob/main/src/styles/theme.css):
+<CollapsibleCode lang="css" code={`  @theme inline static {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+
+  --color-surface: var(--surface);
+  --color-surface-foreground: var(--surface-foreground);
+  --color-surface-hover: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+
+  --color-surface-secondary: var(--surface-secondary);
+  --color-surface-secondary-foreground: var(--surface-secondary-foreground);
+
+  --color-surface-tertiary: var(--surface-tertiary);
+  --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
+
+  --color-overlay: var(--overlay);
+  --color-overlay-foreground: var(--overlay-foreground);
+  --color-backdrop: var(--backdrop);
+  
+
+  --color-muted: var(--muted);
+
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-segment: var(--segment);
+  --color-segment-foreground: var(--segment-foreground);
+
+  --color-border: var(--border);
+  --color-separator: var(--separator);
+  --color-focus: var(--focus);
+  --color-link: var(--link);
+
+  --color-default: var(--default);
+  --color-default-foreground: var(--default-foreground);
+
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+
+  /* Form Field Tokens */
+  --color-field: var(--field-background, var(--default));
+  --color-field-foreground: var(--field-foreground, var(--foreground));
+  --color-field-placeholder: var(--field-placeholder, var(--muted));
+  --color-field-border: var(--field-border, var(--border));
+  --radius-field: var(--field-radius, var(--radius-xl));
+  --border-width-field-width: var(--field-border-width, var(--border-width));
+
+  --shadow-surface: var(--surface-shadow);
+  --shadow-overlay: var(--overlay-shadow);
+  --shadow-field: var(--field-shadow);
+
+  /* Calculated Variables */
+
+  /* Colors */
+
+  /* --- background shades --- */
+  --color-background-secondary: color-mix(in oklab, var(--background) 96%, var(--foreground) 4%);
+  --color-background-tertiary: color-mix(in oklab, var(--background) 92%, var(--foreground) 8%);
+  --color-background-inverse: var(--foreground);
+
+  /* ------------------------- */
+  --color-default-hover: color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%);
+  --color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+  --color-success-hover: color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%);
+  --color-warning-hover: color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%);
+  --color-danger-hover: color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%);
+
+  /* Form Field Colors */ 
+  --color-field-hover: color-mix(in oklab, var(--field-background, var(--default)) 90%, var(--field-foreground, var(--foreground)) 2%);
+  --color-field-focus: var(--field-background, var(--default));
+  --color-field-border-hover: color-mix(in oklab, var(--field-border, var(--border)) 88%, var(--field-foreground, var(--foreground)) 10%);
+  --color-field-border-focus: color-mix(in oklab, var(--field-border, var(--border)) 74%, var(--field-foreground, var(--foreground)) 22%);
+
+  /* Soft Colors */
+  --color-accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
+  --color-accent-soft-foreground: var(--accent);
+  --color-accent-soft-hover: color-mix(in oklab, var(--accent) 20%, transparent);
+
+  --color-danger-soft: color-mix(in oklab, var(--danger) 15%, transparent);
+  --color-danger-soft-foreground: var(--danger);
+  --color-danger-soft-hover: color-mix(in oklab, var(--danger) 20%, transparent);
+
+  --color-warning-soft: color-mix(in oklab, var(--warning) 15%, transparent);
+  --color-warning-soft-foreground: var(--warning);
+  --color-warning-soft-hover: color-mix(in oklab, var(--warning) 20%, transparent);
+
+  --color-success-soft: color-mix(in oklab, var(--success) 15%, transparent);
+  --color-success-soft-foreground: var(--success);
+  --color-success-soft-hover: color-mix(in oklab, var(--success) 20%, transparent);
+
+  /* Separator Colors - Levels */
+  --color-separator-secondary: color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%);
+  --color-separator-tertiary: color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%);
+
+  /* Border Colors - Levels (progressive contrast: default → secondary → tertiary) */
+  /* Light mode: lighter → darker | Dark mode: darker → lighter */
+  --color-border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+  --color-border-tertiary: color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%);
+
+  /* Radius and default sizes - defaults can change by just changing the --radius */
+  --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
+  --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
+  --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
+  --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
+  --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
+  --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
+  --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
+  --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
+}
+`}
+/>
+
+> **Field border utilities:** Use `border-field-width` for the field border width and `border-field-border` for the field border color. Pair them together (`border-field-width border-field-border`) when you need both. The `border-field` class remains a border-color utility from `--color-field` only; do not use it for width. If you previously used `border-field` for width, migrate to `border-field-width`. Customize the width via the `--field-border-width` primitive.
+
+Form controls now rely on the `--field-*` variables and their calculated hover/focus variants. Update them in your theme to restyle inputs, checkboxes, radios, and OTP slots without impacting surfaces like buttons or cards.
+
+## Vibrant Palette
+
+By default, HeroUI Native uses accessible soft foreground colors that mix the semantic color with the foreground for better contrast on soft backgrounds. If you prefer more saturated, vibrant soft foreground colors, import the optional `heroui-native/styles/vibrant` stylesheet alongside the base styles:
+
+```css
+/* global.css */
+@import "heroui-native/styles";
+@import "heroui-native/styles/vibrant"; /* [!code highlight] */
+```
+
+This switches all `*-soft-foreground` variables (accent, success, warning, danger) to use 92% of the semantic color with only 8% foreground mixed in — closer to the raw color but with a slight contrast boost. Components such as [Alert](/docs/native/components/alert), [Avatar](/docs/native/components/avatar), [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Toast](/docs/native/components/toast) automatically pick up the new soft foreground colors on their soft variants — no component prop changes are required.
+
+| Mode | Accessible (default) | Vibrant |
+|------|----------------------|---------|
+| Soft foreground | `color-mix(color 70-80%, foreground 30-40%)` | `color-mix(color 92%, foreground 8%)` |
+
+<Callout type="warning">
+  The vibrant palette prioritizes visual saturation over contrast. It may not meet WCAG accessibility guidelines for some color combinations, especially with lighter accent colors.
+</Callout>
+
+<Callout type="info">
+  The optional vibrant palette is available starting from [v1.0.4](/docs/native/releases/v1-0-4).
+</Callout>
+
+## Resources
+
+- [Colors Documentation](/docs/native/getting-started/colors)
+- [Styling Guide](/docs/native/getting-started/styling)
+- [Tailwind CSS v4 Theming](https://tailwindcss.com/docs/theme)
+- [OKLCH Color Tool](https://oklch.com)
diff --git a/apps/docs/content/docs/en/native/getting-started/(overview)/design-principles.mdx b/apps/docs/content/docs/en/native/getting-started/(overview)/design-principles.mdx
new file mode 100644
index 0000000..1aa23b3
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(overview)/design-principles.mdx
@@ -0,0 +1,262 @@
+---
+title: Design Principles
+description: Core principles that guide HeroUI v3's design and development
+icon: book
+---
+
+HeroUI Native follows 9 core principles that prioritize clarity, accessibility, customization, and developer experience.
+
+## Core Principles
+
+### 1. Semantic Intent Over Visual Style
+
+Use semantic naming (primary, secondary, tertiary) instead of visual descriptions (solid, flat, bordered). Inspired by [Uber's Base design system](https://base.uber.com/6d2425e9f/p/756216-button), variants follow a clear hierarchy:
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis-dark.jpg"
+  alt="Semantic Intent Hierarchy"
+/>
+
+
+```tsx
+// ✅ Semantic variants communicate hierarchy
+<Button variant="primary">Save</Button>
+<Button variant="secondary">Edit</Button>
+<Button variant="tertiary">Cancel</Button>
+```
+
+| Variant | Purpose | Usage |
+|---------|---------|-------|
+| **Primary** | Main action to move forward | 1 per context |
+| **Secondary** | Alternative actions | Multiple allowed |
+| **Tertiary** | Dismissive actions (cancel, skip) | Sparingly |
+| **Danger** | Destructive actions | When needed |
+
+### 2. Accessibility as Foundation
+
+Accessibility follows mobile development best practices with proper touch accessibility, focus management, and screen reader support built into every component. All components include proper accessibility labels and semantic structure for VoiceOver (iOS) and TalkBack (Android).
+
+```tsx
+import { Tabs } from 'heroui-native';
+
+<Tabs value="profile" onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Indicator />
+    <Tabs.Trigger value="profile">
+      <Tabs.Label>Profile</Tabs.Label>
+    </Tabs.Trigger>
+    <Tabs.Trigger value="security">
+      <Tabs.Label>Security</Tabs.Label>
+    </Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="profile">Content</Tabs.Content>
+  <Tabs.Content value="security">Content</Tabs.Content>
+</Tabs>
+```
+
+### 3. Composition Over Configuration
+
+Compound components let you rearrange, customize, or omit parts as needed. Use dot notation to compose components exactly as you need them.
+
+```tsx
+// Compose parts to build exactly what you need
+import { Accordion } from 'heroui-native';
+
+<Accordion>
+  <Accordion.Item value="1">
+    <Accordion.Trigger>
+      Question Text
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+    <Accordion.Content>Answer content</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+### 4. Progressive Disclosure
+
+Start simple, add complexity only when needed. Components work with minimal props and scale up as requirements grow.
+
+```tsx
+import { Button, Spinner } from 'heroui-native';
+import { Feather } from '@expo/vector-icons';
+
+// Level 1: Minimal
+<Button>Click me</Button>
+
+// Level 2: Enhanced
+<Button variant="primary" size="lg">
+  <Feather name="check" size={20} />
+  <Button.Label>Submit</Button.Label>
+</Button>
+
+// Level 3: Advanced
+<Button variant="primary" isDisabled={isLoading}>
+  {isLoading ? (
+    <>
+      <Spinner size="sm" />
+      <Button.Label>Loading...</Button.Label>
+    </>
+  ) : (
+    <Button.Label>Submit</Button.Label>
+  )}
+</Button>
+```
+
+### 5. Predictable Behavior
+
+Consistent patterns across all components: sizes (`sm`, `md`, `lg`), variants, and className support. Same API, same behavior.
+
+```tsx
+import { Button, Chip, Avatar } from 'heroui-native';
+
+// All components follow the same patterns
+<Button size="lg" variant="primary" className="custom">
+  <Button.Label>Click me</Button.Label>
+</Button>
+<Chip size="lg" color="success" className="custom">
+  <Chip.Label>Success</Chip.Label>
+</Chip>
+<Avatar size="lg" className="custom">
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 6. Type Safety First
+
+Full TypeScript support with IntelliSense, auto-completion, and compile-time error detection. Extend types for custom components.
+
+```tsx
+import type { ButtonRootProps } from 'heroui-native';
+
+// Type-safe props and event handlers
+<Button
+  variant="primary"  // Autocomplete: primary | secondary | tertiary | ghost | danger | danger-soft
+  size="md"          // Type checked: sm | md | lg
+  onPress={() => {   // Properly typed press handler
+    console.log('Button pressed');
+  }}
+>
+  <Button.Label>Click me</Button.Label>
+</Button>
+
+// Extend types for custom components
+interface CustomButtonProps extends Omit<ButtonRootProps, 'variant'> {
+  intent: 'save' | 'cancel' | 'delete';
+}
+```
+
+### 7. Developer Experience Excellence
+
+Clear APIs, descriptive errors, IntelliSense and AI-friendly markdown docs.
+
+### 8. Complete Customization
+
+Beautiful defaults out-of-the-box. Transform the entire look with CSS variables through [Uniwind's theming system](https://docs.uniwind.dev/theming/basics). Every slot is customizable.
+
+```css
+/* Custom colors using Uniwind's theme layer */
+@layer theme {
+  @variant light {
+    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
+    --background: oklch(0.98 0 0);  /* Custom background */
+  }
+
+  @variant dark {
+    --accent: oklch(0.65 0.25 270);
+    --background: oklch(0.15 0 0);
+  }
+}
+
+/* Radius customization */
+@theme {
+  --radius: 0.75rem; /* Increase for rounder components */
+}
+```
+
+### 9. Open and Extensible
+
+Wrap, extend, and customize components to match your needs. Create custom wrappers or apply custom styles using className.
+
+```tsx
+import { Button } from 'heroui-native';
+import type { ButtonRootProps } from 'heroui-native';
+
+// Custom wrapper component
+interface CTAButtonProps extends Omit<ButtonRootProps, 'variant'> {
+  intent?: 'primary-cta' | 'secondary-cta' | 'minimal';
+}
+
+const CTAButton = ({
+  intent = 'primary-cta',
+  children,
+  ...props
+}: CTAButtonProps) => {
+  const variantMap = {
+    'primary-cta': 'primary',
+    'secondary-cta': 'secondary',
+    'minimal': 'ghost'
+  } as const;
+
+  return (
+    <Button variant={variantMap[intent]} {...props}>
+      <Button.Label>{children}</Button.Label>
+    </Button>
+  );
+};
+
+// Usage
+<CTAButton intent="primary-cta">Get Started</CTAButton>
+<CTAButton intent="secondary-cta">Learn More</CTAButton>
+```
+
+**Extend with Tailwind Variants:**
+
+```tsx
+import { Button } from 'heroui-native';
+import { tv } from 'tailwind-variants';
+
+// Extend button styles with custom variants
+const myButtonVariants = tv({
+  base: 'px-4 py-2 rounded-lg',
+  variants: {
+    variant: {
+      'primary-cta': 'bg-accent px-8 py-4 shadow-lg',
+      'secondary-cta': 'border-2 border-accent px-6 py-3',
+    }
+  },
+  defaultVariants: {
+    variant: 'primary-cta',
+  }
+});
+
+// Label variants for text colors (must be applied to Button.Label)
+const myLabelVariants = tv({
+  base: '',
+  variants: {
+    variant: {
+      'primary-cta': 'text-accent-foreground',
+      'secondary-cta': 'text-accent',
+    }
+  },
+  defaultVariants: {
+    variant: 'primary-cta',
+  }
+});
+
+// Use the custom variants
+function CustomButton({ variant, className, labelClassName, children, ...props }) {
+  return (
+    <Button className={myButtonVariants({ variant, className })} {...props}>
+      <Button.Label className={myLabelVariants({ variant, className: labelClassName })}>
+        {children}
+      </Button.Label>
+    </Button>
+  );
+}
+
+// Usage
+<CustomButton variant="primary-cta">Get Started</CustomButton>
+<CustomButton variant="secondary-cta">Learn More</CustomButton>
+```
diff --git a/apps/docs/content/docs/en/native/getting-started/(overview)/quick-start.mdx b/apps/docs/content/docs/en/native/getting-started/(overview)/quick-start.mdx
new file mode 100644
index 0000000..36526e2
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(overview)/quick-start.mdx
@@ -0,0 +1,243 @@
+---
+title: Quick Start
+description: Get up and running with HeroUI Native
+icon: rocket
+---
+
+Choose the path that fits your project:
+
+- **Option 1** — Scaffold a new, preconfigured project with our CLI. Zero setup.
+- **Option 2** — Add HeroUI Native to an existing React Native or Expo project.
+
+## Option 1: Create a New Project
+
+The fastest way to start. The CLI scaffolds an Expo project with HeroUI Native, all required peer dependencies, Uniwind / Tailwind CSS, global styles, and the `HeroUINativeProvider` already wired up — so you can jump straight to building.
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npx create-heroui-native-app@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm create heroui-native-app@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn create heroui-native-app
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun create heroui-native-app@latest
+    ```
+  </Tab>
+</Tabs>
+
+Follow the interactive prompts, then start the dev server:
+
+```bash
+cd my-app
+npm run start
+```
+
+You're ready to build. Skip ahead to [Use Your First Component](#use-your-first-component) or [browse components](/docs/native/components).
+
+<Callout type="info">
+  The scaffold includes Expo with TypeScript, Uniwind + Tailwind CSS preconfigured, `global.css` with the required imports, and the app entry already wrapped in `GestureHandlerRootView` and `HeroUINativeProvider`.
+</Callout>
+
+## Option 2: Add to an Existing Project
+
+If you already have a React Native or Expo app, follow these steps to install and configure HeroUI Native manually.
+
+<CopyPrompt
+  prompt={`Set up HeroUI Native in this React Native project.
+
+Use the HeroUI Native MCP server (@heroui/native-mcp) as the single source of truth for installation steps, peer dependencies, and component APIs. Start by retrieving the latest quick-start / installation guide from the MCP and follow it precisely — do not rely on memory for versions, package names, or setup steps.
+
+Before making any changes:
+
+1. Analyze the project. Detect the package manager (npm / pnpm / yarn / bun), framework (Expo or bare React Native), TypeScript usage, and the location of node_modules. This matters for global.css — the @source path must be written relative to global.css itself and must resolve to node_modules/heroui-native/lib.
+2. Read package.json and only install what is missing. Pin to the exact versions listed in the MCP quick-start to avoid compatibility issues.
+3. Inspect the app entry (App.tsx, app/_layout.tsx, index.tsx, etc.) and check whether GestureHandlerRootView already wraps the app. If it does, reuse it — do not nest a second GestureHandlerRootView.
+
+Then apply the setup:
+
+- Install heroui-native plus any missing mandatory+optional peer dependencies.
+- Set up Uniwind + Tailwind CSS (follow the Uniwind quickstart) and add the HeroUI Native imports plus the correct @source line to global.css.
+- Make sure GestureHandlerRootView wraps the entire app — it must be the outermost wrapper with style { flex: 1 }.
+- Add HeroUINativeProvider as a direct child of GestureHandlerRootView, wrapping the rest of the app.
+
+When done, summarize the changes you made and tell me how to run the app on iOS / Android.`}
+>
+  **Prefer to let your AI assistant do it?** Install the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server) in your editor, then paste the prompt into your AI assistant — it will analyze your project and handle the entire setup for you.
+</CopyPrompt>
+
+### 1. Install HeroUI Native
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install heroui-native
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native
+    ```
+  </Tab>
+</Tabs>
+
+### 2. Install Mandatory Peer Dependencies
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="warning">
+  It's recommended to use the exact versions specified above to avoid compatibility issues. Version mismatches may cause unexpected bugs.
+</Callout>
+
+### 3. Optional Dependencies
+
+These packages are only needed if you use specific components or features:
+
+| Package | Version | Required for |
+| --- | --- | --- |
+| `react-native-screens` | `^4.16.0` | BottomSheet, Dialog, Menu, Popover, Select, Toast |
+| `@gorhom/bottom-sheet` | `^5.2.9` | BottomSheet, Menu / Popover / Select when `presentation="bottom-sheet"` |
+
+### 4. Set Up Uniwind
+
+Follow the [Uniwind installation guide](https://docs.uniwind.dev/quickstart) to set up Tailwind CSS for React Native.
+
+If you're migrating from NativeWind, see the [migration guide](https://docs.uniwind.dev/migration-from-nativewind).
+
+### 5. Configure global.css
+
+Inside your `global.css` file add the following imports:
+
+```css
+@import 'tailwindcss';
+@import 'uniwind';
+
+@import 'heroui-native/styles';
+
+/* Path to the heroui-native lib inside node_modules relative to global.css */
+/* Examples:
+ *   - If global.css is at project root: ./node_modules/heroui-native/lib
+ *   - If global.css is in app/: ../node_modules/heroui-native/lib
+ *   - If global.css is in src/styles/: ../../node_modules/heroui-native/lib
+ */
+@source './node_modules/heroui-native/lib';
+```
+
+### 6. Wrap Your App with Provider
+
+Wrap your application with `HeroUINativeProvider`. You must wrap it with `GestureHandlerRootView`:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+> **Note**: For advanced configuration options including text props, animation settings, and toast configuration, see the [Provider documentation](/docs/native/getting-started/provider).
+
+## Use Your First Component
+
+```tsx
+import { Button } from 'heroui-native';
+import { View } from 'react-native';
+
+export default function MyComponent() {
+  return (
+    <View className="flex-1 justify-center items-center bg-background">
+      <Button onPress={() => console.log('Pressed!')}>Get Started</Button>
+    </View>
+  );
+}
+```
+
+## Reduce Bundle Size with Granular Exports
+
+If you want to reduce bundle size and import only the components you need, our library provides granular exports for each component:
+
+```tsx
+// Granular imports - use when you need only a few components
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+
+// General import - imports the whole library, use when you're using many components
+import { Button, Card } from "heroui-native";
+```
+
+Granular imports are ideal when you only need a few components, as they help keep your bundle size smaller. General imports from `heroui-native` will include the entire library, which is convenient when you're using many components throughout your app.
+
+**Available granular exports:**
+
+- `heroui-native/provider` - Provider component
+- `heroui-native/provider-raw` - Lightweight provider (keeps bare minimum to start)
+- `heroui-native/[component-name]` - Individual components
+- `heroui-native/portal` - Portal utilities
+- `heroui-native/toast` - Toast provider and utilities
+- `heroui-native/utils` - Utility functions
+- `heroui-native/hooks` - Custom hooks
+
+<Callout type="warning">
+  **Important**: To keep the bundle size under control, you must follow the pattern with granular imports consistently. Even one general import from `heroui-native` will break this optimization strategy.
+</Callout>
+
+> **Tip**: For even more control over your bundle, consider using [`HeroUINativeProviderRaw`](/docs/native/getting-started/provider#raw-provider) — a lightweight provider that excludes `ToastProvider` and `PortalHost`.
+
+## What's Next?
+
+- [HeroUI Native Provider](/docs/native/getting-started/provider)
+- [Styling Guide](/docs/native/getting-started/styling)
+- [Theming Documentation](/docs/native/getting-started/theming)
+
+## Running on Web (Expo)
+
+<Callout type="warning">
+  HeroUI Native is currently not recommended for web use. We are focusing on mobile platforms (iOS and Android) at this time. For web development, please use [HeroUI React](/docs/react/getting-started/quick-start) instead.
+</Callout>
diff --git a/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agent-skills.mdx b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..9ff442e
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agent-skills.mdx
@@ -0,0 +1,69 @@
+---
+title: Agent Skills
+description: Enable AI assistants to build mobile UIs with HeroUI Native components
+---
+
+HeroUI Native Skills give your AI assistant comprehensive knowledge of HeroUI Native components, patterns, and best practices for React Native development.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-native.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-native-dark.jpg"
+  alt="HeroUI Native Agent Skills"
+/>
+
+### Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-native
+```
+
+Or using the skills package:
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+Support Claude Code, Cursor, OpenCode and more.
+</span>
+
+### Usage
+
+Skills are **automatically discovered** by your AI assistant, or call it directly using `/heroui-native` command.
+
+Simply ask your AI assistant to:
+- Build mobile components using HeroUI Native
+- Create screens with HeroUI Native components
+- Customize themes and styles
+- Access component documentation
+
+<Callout>
+  For more complex use cases, use the [MCP Server](/docs/native/getting-started/mcp-server) which provides real-time access to component documentation and source code.
+</Callout>
+
+### What's Included
+
+- HeroUI Native installation guide
+- All HeroUI Native components with props, examples, and usage patterns
+- Theming and styling guidelines with Uniwind
+- Design principles and composition patterns
+
+### Structure
+
+```
+skills/heroui-native/
+├── SKILL.md              # Main skill documentation
+├── LICENSE.txt           # Apache License 2.0
+└── scripts/              # Utility scripts
+    ├── list_components.mjs
+    ├── get_component_docs.mjs
+    ├── get_theme.mjs
+    └── get_docs.mjs
+```
+
+### Related Documentation
+
+- [Agent Skills Specification](https://agentskills.io/home) - Learn about the Agent Skills format
+- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - Claude's Skills documentation
+- [Cursor Skills](https://cursor.com/docs/context/skills) - Using Skills in Cursor
+- [OpenCode Skills](https://opencode.ai/docs/skills) - Using Skills in OpenCode
diff --git a/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agents-md.mdx b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..3152255
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/agents-md.mdx
@@ -0,0 +1,51 @@
+---
+title: AGENTS.md
+description: Download HeroUI Native documentation for AI coding agents
+icon: preview
+---
+
+Download HeroUI Native documentation directly into your project for AI assistants to reference.
+
+<Callout>
+  **Note:** The `agents-md` command is specifically for HeroUI React v3 and HeroUI Native. Other CLI commands (like `add`, `init`, `upgrade`, etc.) are for HeroUI v2 (for now).
+</Callout>
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-native.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-native-dark.jpg"
+  alt="HeroUI Native AGENTS.md"
+/>
+
+### Usage
+
+```bash
+npx heroui-cli@latest agents-md --native
+```
+
+Or specify output file:
+
+```bash
+npx heroui-cli@latest agents-md --native --output AGENTS.md
+```
+
+### What It Does
+
+- Downloads latest HeroUI Native docs to `.heroui-docs/native/`
+- Generates an index in `AGENTS.md` or `CLAUDE.md`
+- Adds `.heroui-docs/` to `.gitignore` automatically
+
+### Options
+
+- `--native` - Download Native docs only
+- `--output <files...>` - Target file(s) (e.g., `AGENTS.md` or `AGENTS.md CLAUDE.md`)
+- `--ssh` - Use SSH for git clone
+
+### Requirements
+
+- Tailwind CSS >= v4 (via Uniwind)
+
+### Related Documentation
+
+- [AGENTS.md](https://agents.md/) - Learn about the AGENTS.md format for coding agents
+- [CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) - Claude equivalent of AGENTS.md
+- [AGENTS.md vs Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) - AGENTS.md performance
diff --git a/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/llms-txt.mdx b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/llms-txt.mdx
new file mode 100644
index 0000000..65a626f
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/llms-txt.mdx
@@ -0,0 +1,62 @@
+---
+title: LLMs.txt
+description: Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI Native
+---
+
+We provide [LLMs.txt](https://llmstxt.org/) files to make HeroUI Native documentation accessible to AI coding assistants.
+
+## Available Files
+
+**Core documentation:**
+- [/native/llms.txt](/native/llms.txt) — Quick reference index for Native documentation
+- [/native/llms-full.txt](/native/llms-full.txt) — Complete HeroUI Native documentation
+
+**For limited context windows:**
+- [/native/llms-components.txt](/native/llms-components.txt) — Component documentation only
+- [/native/llms-patterns.txt](/native/llms-patterns.txt) — Common patterns and recipes
+
+**All platforms:**
+- [/llms.txt](/llms.txt) — Quick reference index (React + Native)
+- [/llms-full.txt](/llms-full.txt) — Complete documentation (React + Native)
+- [/llms-components.txt](/llms-components.txt) — All component documentation
+- [/llms-patterns.txt](/llms-patterns.txt) — All patterns and recipes
+
+## Integration
+
+**Claude Code:** Tell Claude to reference the documentation:
+```
+Use HeroUI Native documentation from https://heroui.com/native/llms.txt
+```
+Or add to your project's `.claude` file for automatic loading.
+
+**Cursor:** Use the `@Docs` feature:
+```
+@Docs https://heroui.com/native/llms-full.txt
+```
+[Learn more](https://docs.cursor.com/context/@-symbols/@-docs)
+
+**Windsurf:** Add to your `.windsurfrules` file:
+```
+#docs https://heroui.com/native/llms-full.txt
+```
+[Learn more](https://docs.codeium.com/windsurf/memories#memories-and-rules)
+
+**Other AI tools:** Most AI assistants can reference documentation by URL. Simply provide:
+```
+https://heroui.com/native/llms.txt
+```
+
+**For component-specific documentation:**
+```
+https://heroui.com/native/llms-components.txt
+```
+
+**For patterns and best practices:**
+```
+https://heroui.com/native/llms-patterns.txt
+```
+
+
+## Contributing
+
+Found an issue with AI-generated code? Help us improve our LLMs.txt files on [GitHub](https://github.com/heroui-inc/heroui).
diff --git a/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/mcp-server.mdx b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..73de38c
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/(ui-for-agents)/mcp-server.mdx
@@ -0,0 +1,205 @@
+---
+title: MCP Server
+description: Access HeroUI Native documentation directly in your AI assistant
+---
+
+The HeroUI MCP Server gives AI assistants direct access to HeroUI Native component documentation, making it easier to build with HeroUI in AI-powered development environments.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-light-new.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/hero-native-mcp-dark-new.jpg"
+  alt="HeroUI v3 MCP Server"
+/>
+
+
+The MCP server currently supports **heroui-native** and [stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). Published at `@heroui/native-mcp` on npm. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp).
+
+<Callout>
+  As we add more components to HeroUI Native, they'll be available in the MCP server too.
+</Callout>
+
+## Quick Setup
+
+**Cursor:**
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/native-mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span  >Install in Cursor</span>
+  </a>
+</div>
+
+Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+Alternatively, add the following to your `~/.cursor/mcp.json` file. To learn more, see the [Cursor documentation](https://cursor.com/docs/context/mcp).
+
+**Claude Code:** Run this command in your terminal:
+
+```bash
+claude mcp add heroui-native -- npx -y @heroui/native-mcp@latest
+```
+
+Or manually add to your project's `.mcp.json` file:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Code and run `/mcp` to see the HeroUI MCP server in the list. If you see **Connected**, you're ready to use it.
+
+See the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for more details.
+
+**Windsurf:** Add the HeroUI server to your project's `.windsurf/mcp.json` configuration file:
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Windsurf to activate the MCP server.
+
+See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more details.
+
+**Zed:** Add the HeroUI server to your `settings.json` configuration file. Open settings via Command Palette (`zed: open settings`) or use `Cmd-,` (Mac) / `Ctrl-,` (Linux):
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+```
+
+After adding the configuration, restart Zed and open the Agent Panel settings view. Check that the indicator dot next to the heroui-native server is green with "Server is active" tooltip.
+
+See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp) for more details.
+
+**VS Code:** To configure MCP in VS Code with GitHub Copilot, add the HeroUI server to your project's `.vscode/mcp.json` configuration file:
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-native": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-native server.
+
+See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
+
+**Codex:** Add the HeroUI server to your `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):
+
+```toml title="config.toml"
+[mcp_servers.heroui-native]
+command = "npx"
+args = ["-y", "@heroui/native-mcp@latest"]
+```
+
+After adding the configuration, restart Codex and run `/mcp` in the TUI to verify the server is active.
+
+See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
+
+**OpenCode:** Add the HeroUI server to your project's `opencode.json` configuration file:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-native": {
+      "type": "local",
+      "command": ["npx", "-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart OpenCode to activate the MCP server.
+
+See the [OpenCode MCP documentation](https://open-code.ai/docs/en/mcp-servers) for more details.
+
+## Usage
+
+Once configured, ask your AI assistant questions like:
+
+- "Help me install HeroUI Native in my Expo app"
+- "Show me all HeroUI Native components"
+- "What props does the Button component have?"
+- "Give me an example of using the Card component"
+- "What are the theme variables for dark mode?"
+
+### Automatic Updates
+
+The MCP server can help you upgrade to the latest HeroUI Native version:
+
+```bash
+"Hey Cursor, update HeroUI Native to the latest version"
+```
+
+Your AI assistant will automatically:
+- Compare your current version with the latest release
+- Review the changelog for breaking changes
+- Apply the necessary code updates to your project
+
+This works for any version upgrade, whether you're updating to the latest stable or pre-release version.
+
+## Available Tools
+
+The MCP server provides these tools to AI assistants:
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all available HeroUI Native components |
+| `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns for one or more components |
+| `get_theme_variables` | Access theme variables for colors, typography, spacing with light/dark mode support |
+| `get_docs` | Browse the full HeroUI Native documentation including guides and principles (use path `/docs/native/getting-started/quick-start` for installation instructions) |
+
+
+## Troubleshooting
+
+**Requirements:** Node.js 22 or higher. The package will be automatically downloaded when using `npx`.
+
+**Need help?** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord Community](https://discord.gg/heroui)
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@heroui/native-mcp)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-mcp)
+- [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/native/getting-started/index.mdx b/apps/docs/content/docs/en/native/getting-started/index.mdx
new file mode 100644
index 0000000..a852d1c
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/index.mdx
@@ -0,0 +1,49 @@
+---
+title: Introduction
+description: An open-source UI component library for building beautiful and accessible user interfaces.
+icon: book-open
+image: https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp
+---
+
+HeroUI Native is a React Native component library built on [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.
+
+<NativeImageHeroView target="home" />
+
+## HeroUI Ecosystem
+
+- **🌐 HeroUI v3** (web) — React components with Tailwind CSS v4
+- **📱 HeroUI Native (mobile)** — Beautiful components for React Native
+- **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)** (text-to-app) — Create apps with natural language
+- **🧠 UI for LLMs** — New platform & MCPs coming soon
+
+## FAQ
+
+**Is HeroUI Native free?**
+Yes, completely free and open source under the Apache License 2.0.
+
+**Is it production-ready?**
+Yes, HeroUI Native is production-ready and actively used in production apps.
+
+**Can I customize the components?**
+Yes! Update default styles, animations or compose component parts differently. Every slot is customizable.
+
+**Does it work with TypeScript?**
+Fully typed with excellent IDE support and autocompletion.
+
+**What about accessibility?**
+Accessibility follows mobile development best practices with proper focus management, touch accessibility, and screen reader support built into every component.
+
+**Is there a Figma file?**
+Yes! Access our design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429).
+
+## Get Involved
+
+Join the community, share feedback, or contribute:
+
+- [GitHub Discussions](https://github.com/heroui-inc/heroui-native/discussions)
+- [Discord](https://discord.gg/9b6yyZKmH4)
+- [X/Twitter](https://x.com/hero_ui)
+- [Contributing Guidelines](https://github.com/heroui-inc/heroui-native/blob/main/CONTRIBUTING.md)
+
+HeroUI Native is released under the [Apache License 2.0](https://github.com/heroui-inc/heroui-native/blob/main/LICENSE).
+
diff --git a/apps/docs/content/docs/en/native/getting-started/meta.json b/apps/docs/content/docs/en/native/getting-started/meta.json
new file mode 100644
index 0000000..a251746
--- /dev/null
+++ b/apps/docs/content/docs/en/native/getting-started/meta.json
@@ -0,0 +1,26 @@
+{
+  "title": "Getting Started",
+  "description": "Get started with HeroUI Native",
+  "root": true,
+  "icon": "book-open",
+  "pages": [
+    "---Overview---",
+    "index",
+    "(overview)/quick-start",
+    "(overview)/design-principles",
+    "[route][Roadmap](https://herouinative.featurebase.app/roadmap)",
+    "---Handbook---",
+    "(handbook)/provider",
+    "(handbook)/portal",
+    "(handbook)/colors",
+    "(handbook)/theming",
+    "(handbook)/styling",
+    "(handbook)/animation",
+    "(handbook)/composition",
+    "---UI for Agents---",
+    "(ui-for-agents)/llms-txt",
+    "(ui-for-agents)/mcp-server",
+    "(ui-for-agents)/agent-skills",
+    "(ui-for-agents)/agents-md"
+  ]
+}
diff --git a/apps/docs/content/docs/en/native/meta.json b/apps/docs/content/docs/en/native/meta.json
new file mode 100644
index 0000000..ec9a62b
--- /dev/null
+++ b/apps/docs/content/docs/en/native/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "Documentation",
+  "description": "HeroUI Native Documentation",
+  "pages": ["getting-started", "components", "releases"]
+}
diff --git a/apps/docs/content/docs/en/native/releases/beta-10.mdx b/apps/docs/content/docs/en/native/releases/beta-10.mdx
new file mode 100644
index 0000000..a5299c5
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/beta-10.mdx
@@ -0,0 +1,182 @@
+---
+title: Beta 10
+description: Bottom Sheet component, PressableFeedback refactor, Animation API State Prop extension, use-theme-color multiple colors selection, and bug fixes.
+github:
+  pull: 6068
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">December 30, 2025</span>
+</div>
+
+This release introduces the new [Bottom Sheet](/docs/native/components/bottom-sheet) component, refactors [PressableFeedback](/docs/native/components/pressable-feedback) with improved API, extends the Animation API with State Prop support, enhances the `use-theme-color` hook to handle multiple colors selection, and includes various bug fixes and documentation improvements.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## What's New
+
+### New Components
+
+#### Bottom Sheet
+
+This release introduces the **Bottom Sheet** component, a versatile overlay component that slides up from the bottom of the screen with animated transitions and swipe-to-dismiss gestures.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="bottom-sheet"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/bottom-sheet-docs-dark.mp4"
+/>
+
+**Features:**
+- Smooth animated transitions with gesture support
+- Multiple snap points for flexible sizing
+- Detached mode for custom positioning
+- Customizable overlay with blur effects
+- Full accessibility support
+- Built on [@gorhom/bottom-sheet](https://gorhom.dev/react-native-bottom-sheet)
+
+**Usage:**
+```tsx
+import { BottomSheet, Button } from 'heroui-native';
+
+<BottomSheet>
+  <BottomSheet.Trigger asChild>
+    <Button>Open Bottom Sheet</Button>
+  </BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay />
+    <BottomSheet.Content>
+      <BottomSheet.Close />
+      <BottomSheet.Title>Title</BottomSheet.Title>
+      <BottomSheet.Description>Description</BottomSheet.Description>
+    </BottomSheet.Content>
+  </BottomSheet.Portal>
+</BottomSheet>
+```
+
+For complete documentation and examples, see the [Bottom Sheet component page](/docs/native/components/bottom-sheet).
+
+**Related PR:** [#174](https://github.com/heroui-inc/heroui-native/pull/174)
+
+## Component Improvements
+
+### PressableFeedback Refactor
+
+The [PressableFeedback](/docs/native/components/pressable-feedback) component has been refactored with an improved API and better animation control.
+
+**Improvements:**
+- Enhanced animation configuration API
+- Better support for custom animation states
+- Improved performance and smoother animations
+- More flexible feedback positioning options
+
+The component maintains backward compatibility while providing more control over press feedback animations.
+
+**Related PR:** [#182](https://github.com/heroui-inc/heroui-native/pull/182)
+
+## API Enhancements
+
+### Animation API State Prop Extension
+
+The Animation API has been extended with a new `state` prop that allows you to disable animations while customizing properties. This provides more granular control over animation behavior.
+
+**New Capability:**
+```tsx
+<Component
+  animation={{
+    state: 'disabled', // or 'disable-all' or boolean
+    // ... other animation properties
+  }}
+/>
+```
+
+The `state` prop can be:
+- `'disabled'`: Disable animations while still allowing property customization
+- `'disable-all'`: Disable all animations including children
+- `boolean`: Simple enable/disable control
+
+This enhancement makes it easier to customize animation properties without enabling animations, useful for fine-tuning component behavior.
+
+**Related PR:** [#176](https://github.com/heroui-inc/heroui-native/pull/176)
+
+### use-theme-color Multiple Colors Selection
+
+The `use-theme-color` hook has been refactored to handle multiple colors selection, making it more flexible and powerful for theme customization.
+
+**Enhancement:**
+- Support for selecting multiple colors at once
+- Improved color selection logic
+- Better performance when working with multiple color values
+
+This improvement makes it easier to work with complex theming scenarios where multiple colors need to be selected and applied together.
+
+**Related PR:** [#170](https://github.com/heroui-inc/heroui-native/pull/170)
+
+## Documentation
+
+### Animated Styles Guide Comments
+
+Added comprehensive comments and documentation to the Animated Styles Guide, making it easier for developers to understand and use animation features effectively.
+
+**Improvements:**
+- Enhanced code examples with detailed comments
+- Better explanation of animation patterns
+- Clearer guidance on when to use different animation approaches
+
+**Related PR:** [#179](https://github.com/heroui-inc/heroui-native/pull/179)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #173](https://github.com/heroui-inc/heroui-native/issues/173)**: Fixed issue where `classNames={{container:"bg-x"}}` was not working for styling the backgroundColor of TextField.Input container
+- **[Issue #177](https://github.com/heroui-inc/heroui-native/issues/177)**: Fixed button scale animation issue where the scale would sometimes stay at 0.9x and not bounce back after being pressed
+- **[Issue #178](https://github.com/heroui-inc/heroui-native/issues/178)**: Fixed bug affecting component functionality
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Animation Guide](/docs/native/getting-started/animation) - Updated with Animation API State Prop documentation
+- [Colors Guide](/docs/native/getting-started/colors) - Updated with use-theme-color multiple colors selection information
+- [PressableFeedback Component](/docs/native/components/pressable-feedback) - Updated with refactored API documentation
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
diff --git a/apps/docs/content/docs/en/native/releases/beta-11.mdx b/apps/docs/content/docs/en/native/releases/beta-11.mdx
new file mode 100644
index 0000000..0a7907d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/beta-11.mdx
@@ -0,0 +1,158 @@
+---
+title: Beta 11
+description: Enhanced Bottom Sheet close coordination, Dialog swipe-to-dismiss fixes, TextField improvements, and PortalHost export for advanced use cases
+github:
+  pull: 203
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">January 6, 2026</span>
+</div>
+
+Beta 11 focuses on improving component reliability and developer experience across several key areas. This release enhances Bottom Sheet close coordination to ensure consistent behavior across all close mechanisms, fixes Dialog swipe-to-dismiss gesture handling issues, resolves TextField styling and functionality problems, and introduces a new PortalHost export for advanced portal mounting scenarios. These improvements make interactions smoother and provide developers with more control over component behavior.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## Component Improvements
+
+### Bottom Sheet Close Coordination Enhancement
+
+The [Bottom Sheet](/docs/native/components/bottom-sheet) component has been enhanced with improved close coordination across all close mechanisms.
+
+**Improvements:**
+
+- Enhanced synchronization between swipe-to-dismiss, overlay press, close button, and programmatic close actions
+- Improved state management to prevent race conditions during close operations
+- More reliable `onOpenChange` callback firing across all close scenarios
+- Better coordination between animation progress and close state transitions
+
+The Bottom Sheet component supports multiple ways to close: swiping down, pressing the overlay, clicking the close button, or programmatically calling close. Previously, these mechanisms could sometimes conflict or produce inconsistent behavior. This update ensures all close mechanisms work harmoniously together, providing a smoother and more predictable user experience.
+
+**Related PR:** [#201](https://github.com/heroui-inc/heroui-native/pull/201)
+
+### Dialog Swipe-to-Dismiss Gesture Handling Fix
+
+The [Dialog](/docs/native/components/dialog) component has been fixed to properly handle swipe-to-dismiss gestures.
+
+**Improvements:**
+
+- Fixed gesture detection and handling for swipe-to-dismiss functionality
+- Improved gesture state management during swipe interactions
+- Enhanced animation coordination during gesture release
+- More reliable dismissal when swiping beyond the threshold
+
+The Dialog component supports swipe-to-dismiss functionality, allowing users to dismiss dialogs by swiping down. This fix resolves issues where gesture handling could become unresponsive or produce unexpected behavior during swipe interactions.
+
+**Related PR:** [#193](https://github.com/heroui-inc/heroui-native/pull/193)
+
+### TextField Styling and Functionality Fixes
+
+The [TextField](/docs/native/components/text-field) component has been fixed to resolve styling and functionality issues.
+
+**Improvements:**
+
+- Fixed input styling inconsistencies
+- Resolved animation state management issues
+- Improved focus and blur state handling
+- Enhanced error state visual feedback
+- Fixed placeholder and selection color application
+
+These fixes ensure the TextField component displays correctly across all states (focused, blurred, invalid) and provides consistent visual feedback to users.
+
+**Related PR:** [#202](https://github.com/heroui-inc/heroui-native/pull/202)
+
+## API Enhancements
+
+### PortalHost Export for Advanced Use Cases
+
+The `PortalHost` component is now exported from the main provider module, enabling advanced portal host mounting scenarios.
+
+**New Capability:**
+
+```tsx
+import { HeroUINativeProvider, PortalHost } from "@heroui/native";
+
+export function CustomLayout() {
+  return (
+    <>
+      <HeroUINativeProvider>
+        {/* Your app content */}
+      </HeroUINativeProvider>
+
+      {/* Manually mount PortalHost in a custom location */}
+      <PortalHost name="custom-host" />
+    </>
+  );
+}
+```
+
+This enhancement allows developers to manually mount portal hosts in custom layouts, which is particularly useful for scenarios where you need portals to render in specific locations (e.g., within BottomSheet, Modal, or other overlay components). By default, `HeroUINativeProvider` includes a `PortalHost` for standard use cases, but now you can create additional hosts with custom names for advanced scenarios.
+
+**Use Cases:**
+
+- Mounting portals within BottomSheet components
+- Creating portal hosts in Modal components
+- Custom overlay rendering scenarios
+- Multi-host portal architectures
+
+**Related PR:** [#185](https://github.com/heroui-inc/heroui-native/pull/185)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #187](https://github.com/heroui-inc/heroui-native/issues/187)**: Fixed an issue where multiple presses were required to re-open a bottom sheet or dialog after it was dismissed via swipe gesture. The internal state now properly synchronizes with the close animation, allowing immediate reopening regardless of how the component was closed.
+
+- **[Issue #189](https://github.com/heroui-inc/heroui-native/issues/189)**: Fixed app freezing when swiping to dismiss dialogs containing text inputs.
+
+- **[Issue #196](https://github.com/heroui-inc/heroui-native/issues/196)**: Fixed TextField multiline input behavior to match React Native's TextInput multiline functionality.
+
+- **[Issue #199](https://github.com/heroui-inc/heroui-native/issues/199)**: Fixed placeholder text positioning within TextField Input component.
+
+**Related PRs:**
+
+- [#201](https://github.com/heroui-inc/heroui-native/pull/201)
+- [#202](https://github.com/heroui-inc/heroui-native/pull/202)
+- [#193](https://github.com/heroui-inc/heroui-native/pull/193)
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/beta-12.mdx b/apps/docs/content/docs/en/native/releases/beta-12.mdx
new file mode 100644
index 0000000..296b829
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/beta-12.mdx
@@ -0,0 +1,347 @@
+---
+title: Beta 12
+description: InputOTP, Label, and Description components, Popover close fixes, controlled state improvements, border radius fixes, and variant style prop support
+github:
+  pull: 214
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">January 13, 2026</span>
+</div>
+
+Beta 12 introduces three essential form components—InputOTP, Label, and Description—that enhance form building capabilities in React Native applications. This release also includes critical fixes for Popover close behavior, popup controlled state management, border radius configuration, and adds variant style prop support across multiple form components. These improvements provide developers with more robust form components and better control over component styling and behavior.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **3 new** essential form components:
+
+- **[InputOTP](/docs/native/components/input-otp)**: Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support.
+- **[Label](/docs/native/components/label)**: Text component for labeling form fields and other UI elements with support for required indicators and validation states.
+- **[Description](/docs/native/components/description)**: Text component for providing accessible descriptions and helper text for form fields and other UI elements.
+
+#### InputOTP
+
+The InputOTP component provides a complete solution for one-time password input scenarios, such as two-factor authentication, verification codes, and PIN entry. It features individual character slots with smooth animations, customizable grouping, separators, and comprehensive validation support.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input-otp"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-otp-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Individual character slots with smooth animations and caret indicators
+- Flexible grouping with separators for visual organization
+- Pattern-based input restriction (digits, characters, or custom regex)
+- Controlled and uncontrolled value management
+- Validation state support with visual feedback
+- Customizable placeholder characters per slot position
+- Paste support with transformer function
+- Complete accessibility support
+
+**Usage:**
+
+```tsx
+import { InputOTP, Label, Description } from "heroui-native";
+
+export function Example() {
+  return (
+    <>
+      <Label>Verify account</Label>
+      <InputOTP maxLength={6} onComplete={(code) => console.log(code)}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>We've sent a code to your email</Description>
+    </>
+  );
+}
+```
+
+For complete documentation and examples, see the [InputOTP component page](/docs/native/components/input-otp).
+
+**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+#### Label
+
+The Label component provides accessible labeling for form fields with built-in support for required indicators, validation states, and disabled states. It automatically displays an asterisk for required fields and adapts its styling based on the field's validation state.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="label"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/label-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Automatic required field indicator (asterisk)
+- Invalid state styling for validation errors
+- Disabled state support
+- Compound component architecture for custom layouts
+- Full accessibility support with nativeID linking
+- Customizable styling via className, classNames, and styles props
+
+**Usage:**
+
+```tsx
+import { Label, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label isRequired>Password</Label>
+      <TextField.Input placeholder="Create a password" secureTextEntry />
+    </TextField>
+  );
+}
+```
+
+For complete documentation and examples, see the [Label component page](/docs/native/components/label).
+
+**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+#### Description
+
+The Description component provides accessible helper text and descriptions for form fields. It features muted styling by default and supports linking to form fields via nativeID for screen reader support.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="description"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/description-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Muted text styling optimized for helper text
+- Accessibility linking via nativeID and aria-describedby
+- Seamless integration with form components
+- Customizable styling support
+
+**Usage:**
+
+```tsx
+import { Description, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <TextField.Label>Email address</TextField.Label>
+      <TextField.Input
+        placeholder="Enter your email"
+        keyboardType="email-address"
+        aria-describedby="email-desc"
+      />
+      <Description nativeID="email-desc">
+        We'll never share your email with anyone else.
+      </Description>
+    </TextField>
+  );
+}
+```
+
+For complete documentation and examples, see the [Description component page](/docs/native/components/description).
+
+**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
+
+## Component Improvements
+
+### Popover Close via Ref Fix
+
+The [Popover](/docs/native/components/popover) component has been fixed to properly handle programmatic close operations via ref.
+
+**Improvements:**
+
+- Fixed ref-based close method to properly trigger close animations
+- Improved state synchronization between ref calls and component state
+- Enhanced reliability of programmatic close operations
+
+This fix ensures that when developers call `popoverRef.current?.close()`, the popover closes reliably with proper animation and state management.
+
+**Related PR:** [#207](https://github.com/heroui-inc/heroui-native/pull/207)
+
+### Popup Controlled State Fix
+
+Popup components (including Dialog, Bottom Sheet, and Popover) have been fixed to properly handle controlled state via the `isOpen` prop.
+
+**Improvements:**
+
+- Fixed controlled state synchronization for popup components
+- Improved handling of external state changes
+- Enhanced reliability when using controlled mode
+
+This fix ensures that popup components correctly respond to external state changes when using controlled mode, providing developers with more predictable behavior when managing popup state externally.
+
+**Related PR:** [#215](https://github.com/heroui-inc/heroui-native/pull/215)
+
+### Button, Chip, and Tabs Border Radius Fix
+
+The [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Tabs](/docs/native/components/tabs) components have been fixed to properly respect global border radius configuration.
+
+**Improvements:**
+
+- Fixed border radius configuration application for Button component
+- Fixed border radius configuration application for Chip component
+- Fixed border radius configuration application for Tabs component
+- Improved consistency across components using global theme configuration
+
+These fixes ensure that global border radius settings defined in the theme configuration are properly applied to Button, Chip, and Tabs components, providing consistent styling across the application.
+
+**Related PR:** [#218](https://github.com/heroui-inc/heroui-native/pull/218)
+
+### TextField.Input Props Cleanup
+
+The [TextField](/docs/native/components/text-field) component's Input subcomponent has been cleaned up by removing the `animation` and `isAnimatedStyleActive` props.
+
+**Changes:**
+
+- Removed `animation` prop from TextField.Input
+- Removed `isAnimatedStyleActive` prop from TextField.Input
+- Simplified component API for better maintainability
+
+These props were removed to streamline the TextField.Input API and reduce complexity. Animation behavior is now handled internally by the component, providing a more consistent and predictable experience without requiring manual animation configuration.
+
+**Related PR:** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
+
+## API Enhancements
+
+### HeroUINativeProvider devInfo Configuration
+
+The `HeroUINativeProvider` component now supports `devInfo` configuration options for enhanced development experience.
+
+**New Capability:**
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native";
+
+export function App() {
+  return (
+    <HeroUINativeProvider
+      devInfo={{
+        // Configuration options for development
+      }}
+    >
+      {/* Your app content */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+This enhancement provides developers with additional configuration options for development and debugging scenarios, making it easier to troubleshoot and optimize applications during development.
+
+**Related PR:** [#217](https://github.com/heroui-inc/heroui-native/pull/217)
+
+### Variant Style Prop Support
+
+The [Checkbox](/docs/native/components/checkbox), [Radio](/docs/native/components/radio), [TextField](/docs/native/components/text-field), and [InputOTP](/docs/native/components/input-otp) components now support the `variant` style prop for easier variant customization.
+
+**New Capability:**
+
+```tsx
+import { Checkbox, Radio, TextField, InputOTP } from "heroui-native";
+
+// Apply variant styles directly via style prop
+<Checkbox variant="bordered" style={{ variant: "flat" }}>
+  Option 1
+</Checkbox>
+
+<Radio variant="solid" style={{ variant: "bordered" }}>
+  Option 2
+</Radio>
+
+<TextField variant="underlined" style={{ variant: "bordered" }}>
+  <TextField.Input />
+</TextField>
+```
+
+This enhancement provides developers with more flexibility when customizing component variants, allowing variant changes to be applied via the style prop in addition to the component's variant prop.
+
+**Related PR:** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
+
+## Style Fixes
+
+### Border Radius Configuration
+
+Fixed global border radius configuration not applying correctly to certain components.
+
+**Fixes:**
+
+- Fixed Button component not respecting global border radius configuration
+- Fixed Chip component border radius application
+- Fixed Tabs component border radius application
+
+### Style Optimizations
+
+- **Border Radius Consistency**: Improved consistency of border radius application across Button, Chip, and Tabs components
+- **Theme Configuration**: Enhanced theme configuration propagation to ensure all components respect global settings
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #93](https://github.com/heroui-inc/heroui-native/issues/93)**: Fixed global border radius configuration not applying to Button component in hero-ui-native using Unwind. The Button component now properly respects border radius settings defined in the global theme configuration, ensuring consistent styling across the application.
+
+- **[Issue #213](https://github.com/heroui-inc/heroui-native/issues/213)**: Fixed Select controlled mode (`isOpen`) not working. The Select component now properly handles controlled state when the `isOpen` prop is provided, allowing developers to manage Select open/close state externally with predictable behavior.
+
+**Related PRs:**
+
+- [#218](https://github.com/heroui-inc/heroui-native/pull/218)
+- [#215](https://github.com/heroui-inc/heroui-native/pull/215)
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/beta-13.mdx b/apps/docs/content/docs/en/native/releases/beta-13.mdx
new file mode 100644
index 0000000..befc748
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/beta-13.mdx
@@ -0,0 +1,697 @@
+---
+title: Beta 13
+description: TextArea component, Button outline variant, Tabs improvements, form component decomposition, popup animation refactor, style class exports, and critical bug fixes
+github:
+  pull: 254
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 3, 2026</span>
+</div>
+
+Beta 13 introduces the TextArea component for multiline text input, adds Button outline variant, and exports style class names for all components. This release also includes significant improvements to Tabs with better animations and clearer variant naming, decomposes form components into standalone primitives for better flexibility, refactors popup animation system for improved consistency and Android compatibility, and fixes critical issues including Chinese character input handling, theme color calculations, Uniwind Pro compatibility, BottomSheet opening issues, and tree-shaking support. These updates enhance developer experience and component reliability across the library.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native@beta
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native@beta
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native@beta
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native@beta
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **3 new** essential components:
+
+- **[TextArea](/docs/native/components/text-area)**: Multiline text input component with styled border and background for collecting longer user input.
+- **[Input](/docs/native/components/input)**: Single-line text input component with styled border and background, now available as a standalone component separate from TextField.
+- **[CloseButton](/docs/native/components/close-button)**: Reusable button component for closing dialogs, modals, or dismissing content with consistent styling across overlay components.
+
+#### TextArea
+
+The TextArea component provides a complete solution for multiline text input scenarios, such as comments, messages, descriptions, and longer form fields. It features seamless integration with TextField for complete form structure, validation state support, and customizable variants for different visual contexts.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="text-area"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-area-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Multiline text input with customizable rows
+- Seamless integration with TextField component
+- Validation state support with visual feedback
+- Primary and secondary variants for different contexts
+- Disabled and read-only states
+- Customizable styling via className and styles props
+- Complete accessibility support
+
+**Usage:**
+
+```tsx
+import { Description, Label, TextArea, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label>Message</Label>
+      <TextArea placeholder="Enter your message here..." />
+      <Description>Please provide as much detail as possible.</Description>
+    </TextField>
+  );
+}
+```
+
+For complete documentation and examples, see the [TextArea component page](/docs/native/components/text-area).
+
+**Related PR:** [#254](https://github.com/heroui-inc/heroui-native/pull/254)
+
+#### Input
+
+The Input component is now available as a standalone component, providing single-line text input functionality with styled border and background. Previously available only as `TextField.Input`, Input can now be used independently or integrated with form components like TextField and ControlField.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Single-line text input with styled border and background
+- Standalone usage or integration with form components
+- Validation state support with visual feedback
+- Primary and secondary variants for different contexts
+- Disabled and read-only states
+- Customizable styling via className and styles props
+- Complete accessibility support
+
+**Usage:**
+
+```tsx
+import { Description, Input, Label, TextField } from "heroui-native";
+
+export function Example() {
+  return (
+    <TextField>
+      <Label>Email</Label>
+      <Input placeholder="Enter your email..." />
+      <Description>We'll never share your email.</Description>
+    </TextField>
+  );
+}
+```
+
+For complete documentation and examples, see the [Input component page](/docs/native/components/input).
+
+**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+#### CloseButton
+
+The CloseButton component provides a reusable solution for closing dialogs, modals, popovers, and other overlay components. It features consistent styling across all overlay components, customizable icon properties, and seamless integration with Dialog, Popover, Select, and Bottom Sheet components.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="close-button"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/close-button-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Consistent close button styling across overlay components
+- Customizable icon size and color
+- Support for custom children to replace default icon
+- Disabled state support
+- Seamless integration with Dialog, Popover, Select, and Bottom Sheet
+- Default styling optimized for overlay contexts
+
+**Usage:**
+
+```tsx
+import { CloseButton } from "heroui-native";
+
+// Standalone usage
+<CloseButton onPress={handleClose} />
+
+// As part of Dialog, Popover, Select, Bottom Sheet
+<Dialog>
+  <Dialog.Close />
+</Dialog>
+```
+
+For complete documentation and examples, see the [CloseButton component page](/docs/native/components/close-button).
+
+**Related PR:** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
+
+### New Subcomponents
+
+#### Tabs.Separator
+
+The Tabs component now includes a new `Separator` subcomponent that provides animated visibility control between tab triggers. This allows developers to create visual separators that automatically show or hide based on the active tab state.
+
+**Features:**
+
+- Animated visibility transitions based on active tab
+- Configurable visibility via `betweenValues` prop
+- Customizable animation timing and opacity
+- Always visible option for static separators
+
+**Usage:**
+
+```tsx
+import { Tabs } from "heroui-native";
+
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.ScrollView>
+      <Tabs.Indicator />
+      <Tabs.Trigger value="general">
+        <Tabs.Label>General</Tabs.Label>
+      </Tabs.Trigger>
+      <Tabs.Separator betweenValues={["general", "notifications"]} />
+      <Tabs.Trigger value="notifications">
+        <Tabs.Label>Notifications</Tabs.Label>
+      </Tabs.Trigger>
+    </Tabs.ScrollView>
+  </Tabs.List>
+</Tabs>
+```
+
+**Related PR:** [#228](https://github.com/heroui-inc/heroui-native/pull/228)
+
+## Component Improvements
+
+### Button Outline Variant
+
+The [Button](/docs/native/components/button) component now includes an `outline` variant that provides a bordered style with transparent background, offering more visual variety for button designs.
+
+**Improvements:**
+
+- New `outline` variant for bordered button style
+- Consistent styling with other Button variants
+- Proper hover and focus states for outline variant
+- Seamless integration with existing Button API
+
+**Usage:**
+
+```tsx
+import { Button } from "heroui-native";
+
+<Button variant="outline">Outline Button</Button>
+```
+
+**Related PR:** [#235](https://github.com/heroui-inc/heroui-native/pull/235)
+
+### Tabs Indicator Animation Refactor
+
+The [Tabs](/docs/native/components/tabs) component's indicator animation has been refactored to use `translateX` transforms instead of width/height animations, resulting in smoother and more performant tab indicator transitions.
+
+**Improvements:**
+
+- Migrated indicator animation to `translateX` transforms
+- Improved animation performance and smoothness
+- Better visual consistency during tab transitions
+- Reduced layout recalculations during animations
+
+**Related PR:** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
+
+### Popover Arrow Sizing and Visual Connection
+
+The [Popover](/docs/native/components/popover) component has been improved with better arrow sizing and visual connection to the popover content, creating a more cohesive visual appearance.
+
+**Improvements:**
+
+- Improved arrow sizing relative to popover content
+- Enhanced visual connection between arrow and popover
+- Better alignment and spacing
+- More polished overall appearance
+
+**Related PR:** [#243](https://github.com/heroui-inc/heroui-native/pull/243)
+
+### Form Components Decomposition
+
+Form components have been decomposed into standalone primitives, providing developers with more flexibility and better control over component composition.
+
+**Improvements:**
+
+- Decomposed form components into standalone primitives
+- Improved component reusability and composition
+- Better separation of concerns
+- Enhanced flexibility for custom form layouts
+
+**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+### Input Android Shadow Fix
+
+The [Input](/docs/native/components/input) component now includes platform-specific shadow styling for Android, ensuring consistent visual appearance across platforms.
+
+**Improvements:**
+
+- Added platform-specific shadow for Android
+- Improved visual consistency across iOS and Android
+- Better elevation appearance on Android devices
+- Enhanced component appearance on Android platform
+
+**Related PR:** [#248](https://github.com/heroui-inc/heroui-native/pull/248)
+
+### Popup Animation System Refactor
+
+The animation system for popup components (Popover, Select, Dialog, BottomSheet) has been refactored to improve entering/exiting animation logic, overlay composition, and content animation handling. This change standardizes animation behavior across all popup components and fixes Android pointer events issues.
+
+**Improvements:**
+
+- Standardized entering/exiting animations using FadeInDown/FadeOutDown for dialog presentations
+- Refactored overlay animation hooks to support both progress-based and entering/exiting animations
+- Improved overlay composition using Dialog.Overlay and Popover.Overlay components instead of Pressable wrappers
+- Fixed Android pointer events issue affecting popup interactions
+- Made presentation prop explicit in examples (popover, dialog, bottom-sheet)
+- Simplified animation API for better maintainability and consistency
+
+**Related PR:** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
+
+## API Enhancements
+
+### Granular Exports for Bundle Optimization
+
+The library now provides granular exports for each component, allowing developers to reduce bundle size by importing only the components they need.
+
+**New Capability:**
+
+```tsx
+// Granular imports - use when you need only a few components
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+
+// General import - imports the whole library, use when you're using many components
+import { Button, Card } from "heroui-native";
+```
+
+Granular imports are ideal when you only need a few components, as they help keep your bundle size smaller. General imports from `heroui-native` will include the entire library, which is convenient when you're using many components throughout your app.
+
+**Available granular exports:**
+
+- `heroui-native/provider` - Provider component
+- `heroui-native/[component-name]` - Individual components
+- `heroui-native/portal` - Portal utilities
+- `heroui-native/utils` - Utility functions
+- `heroui-native/hooks` - Custom hooks
+
+<Callout type="warning">
+  **Important**: To keep the bundle size under control, you must follow the pattern with granular imports consistently. Even one general import from `heroui-native` will break this optimization strategy.
+</Callout>
+
+**Related PR:** [#233](https://github.com/heroui-inc/heroui-native/pull/233)
+
+### Style Class Names Export
+
+All components now export their style class names, enabling developers to reference component styles programmatically and create custom styling solutions.
+
+**New Capability:**
+
+```tsx
+import { buttonClassNames } from "heroui-native";
+
+// Access component class names programmatically
+const customStyles = {
+  base: buttonClassNames.base,
+  variant: buttonClassNames.variant,
+};
+```
+
+This enhancement provides developers with programmatic access to component class names, enabling advanced styling scenarios and custom theme implementations.
+
+**Related PR:** [#252](https://github.com/heroui-inc/heroui-native/pull/252)
+
+## Style Fixes
+
+### Style Optimizations
+
+- **Quaternary Variant Removal**: Removed quaternary variant and polished component styles for better consistency
+- **Component Style Polish**: Enhanced styling across multiple components for improved visual consistency
+- **Shadow and Border Radius Updates**: Improved shadow and border radius consistency across components
+- **Theme Variable Cleanup**: Simplified theme variables and removed redundant color-mix calculations
+
+**Related PR:** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
+
+## ⚠️ Breaking Changes
+
+### Tabs Variant Prop Rename
+
+The Tabs component's `variant` prop has been renamed from `pill`/`line` to `primary`/`secondary` for better clarity and consistency with other components.
+
+**Migration:**
+
+Update all instances of Tabs variant prop:
+
+```tsx
+// Before
+<Tabs variant="pill">
+  {/* content */}
+</Tabs>
+
+<Tabs variant="line">
+  {/* content */}
+</Tabs>
+
+// After
+<Tabs variant="primary">
+  {/* content */}
+</Tabs>
+
+<Tabs variant="secondary">
+  {/* content */}
+</Tabs>
+```
+
+**Available options:**
+
+- `"primary"` - Primary variant (previously `"pill"`)
+- `"secondary"` - Secondary variant (previously `"line"`)
+
+**Related PR:** [#236](https://github.com/heroui-inc/heroui-native/pull/236)
+
+### Tabs Indicator Animation Refactor
+
+The [Tabs](/docs/native/components/tabs) component's indicator animation has been refactored to use `translateX` transforms instead of `left` positioning for GPU-accelerated performance. This change improves animation performance but requires updates to custom animation configurations.
+
+**Migration:**
+
+If you have customized the Tabs indicator animation, update your animation configuration:
+
+```tsx
+// Before
+<Tabs
+  indicatorAnimation={{
+    left: {
+      type: "spring",
+      config: { damping: 20, stiffness: 300 }
+    }
+  }}
+>
+  {/* content */}
+</Tabs>
+
+// After
+<Tabs
+  indicatorAnimation={{
+    translateX: {
+      type: "spring",
+      config: { damping: 20, stiffness: 300 }
+    }
+  }}
+>
+  {/* content */}
+</Tabs>
+```
+
+**What Changed:**
+
+- Animation API changed from `left` to `translateX` in `TabsIndicatorAnimation` configuration
+- Indicator positioning now uses `translateX` transform for GPU-accelerated animations
+- Added `left-0` base class to indicator styles to maintain initial positioning
+- Visual behavior remains identical, only the underlying implementation has changed
+
+**Related PR:** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
+
+### Divider Component Rename
+
+The `Divider` component has been renamed to `Separator` for better consistency with naming conventions and to avoid confusion with other divider implementations.
+
+**Migration:**
+
+Update all imports and usages:
+
+```tsx
+// Before
+import { Divider } from "heroui-native";
+
+<Divider />
+
+// After
+import { Separator } from "heroui-native";
+
+<Separator />
+```
+
+**Related PR:** [#238](https://github.com/heroui-inc/heroui-native/pull/238)
+
+### Quaternary Variant Removal
+
+The `quaternary` variant has been removed from [Surface](/docs/native/components/surface) and [Card](/docs/native/components/card) components to simplify the design system and improve consistency.
+
+**Migration:**
+
+Update any components using the `quaternary` variant:
+
+```tsx
+// Before
+<Surface variant="quaternary">
+  {/* content */}
+</Surface>
+
+<Card variant="quaternary">
+  {/* content */}
+</Card>
+
+// After
+// Use default, secondary, or tertiary variants, or apply custom styling
+<Surface variant="secondary">
+  {/* content */}
+</Surface>
+
+<Card variant="secondary">
+  {/* content */}
+</Card>
+
+// Or use custom styling for specific needs
+<Surface className="bg-custom-quaternary">
+  {/* content */}
+</Surface>
+```
+
+**Available variants:**
+
+- `"default"` - Default surface styling
+- `"secondary"` - Secondary surface styling
+- `"tertiary"` - Tertiary surface styling
+
+**Related PR:** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
+
+### Form Component Decomposition
+
+As part of the form component decomposition, several components have been renamed and restructured to provide better flexibility and composition patterns.
+
+**Component Renames:**
+
+- `FormField` has been renamed to `ControlField`
+- `ErrorView` has been renamed to `FieldError`
+
+**Migration:**
+
+Update all imports and usages:
+
+```tsx
+// Before
+import { FormField, ErrorView, TextField } from "heroui-native";
+
+<FormField>
+  <TextField.Input />
+  <ErrorView>Error message</ErrorView>
+</FormField>
+
+// After
+import { ControlField, FieldError, Input, TextField } from "heroui-native";
+
+<ControlField>
+  <Input />
+  <FieldError>Error message</FieldError>
+</ControlField>
+```
+
+**TextField.Input Removal:**
+
+The `TextField.Input` subcomponent has been removed. Use the standalone `Input` component instead:
+
+```tsx
+// Before
+import { TextField } from "heroui-native";
+
+<TextField>
+  <TextField.Input placeholder="Enter text..." />
+</TextField>
+
+// After
+import { Input, TextField } from "heroui-native";
+
+<TextField>
+  <Input placeholder="Enter text..." />
+</TextField>
+```
+
+**Component Composition Changes:**
+
+`RadioGroup`, `TextField`, and `ControlField` now use `Label`, `Description`, and `FieldError` components directly, providing more flexible composition:
+
+```tsx
+import { ControlField, Description, FieldError, Input, Label, RadioGroup, TextField } from "heroui-native";
+
+// TextField with Label, Description, and FieldError
+<TextField>
+  <Label>Email</Label>
+  <Input placeholder="Enter email..." />
+  <Description>We'll never share your email.</Description>
+  <FieldError>Invalid email address</FieldError>
+</TextField>
+
+// RadioGroup with Label, Description, and FieldError
+<RadioGroup>
+  <Label>Select option</Label>
+  <RadioGroup.Item value="option1">
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+  <Description>Choose one option</Description>
+  <FieldError>Please select an option</FieldError>
+</RadioGroup>
+
+// ControlField with Label, Description, and FieldError
+<ControlField>
+  <Label>Custom Field</Label>
+  <Input placeholder="Enter value..." />
+  <Description>Additional information</Description>
+  <FieldError>Validation error</FieldError>
+</ControlField>
+```
+
+**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
+
+### CloseButton Component and asChild Removal
+
+A new reusable `CloseButton` component has been introduced, and all close button implementations across Dialog, Popover, Select, and BottomSheet components have been refactored to use this shared component. The `asChild` prop has been removed from all Close components.
+
+**Migration:**
+
+Update any usage of `asChild` prop on Close components:
+
+```tsx
+// Before
+import { Button, Dialog } from "heroui-native";
+
+<Dialog>
+  <Dialog.Close asChild>
+    <Button>Cancel</Button>
+  </Dialog.Close>
+</Dialog>
+
+// After
+import { Button, Dialog } from "heroui-native";
+
+const [isOpen, setIsOpen] = useState(false);
+
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <Button onPress={() => setIsOpen(false)}>Cancel</Button>
+</Dialog>
+```
+
+**What Changed:**
+
+- New `CloseButton` component added with default `variant="tertiary"`, `size="sm"`, and `isIconOnly={true}`
+- `Dialog.Close`, `Popover.Close`, `Select.Close`, and `BottomSheet.Close` now extend `CloseButton` internally
+- The `asChild` prop has been removed from all Close components
+- Close components still support all Button props including `variant`, `size`, `iconProps`, and custom `children`
+- You must now handle close logic manually when using custom buttons instead of Close components
+
+**Related PR:** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
+
+### Popup Animation System Refactor
+
+The animation system for popup components has been refactored, resulting in several API changes that require code updates.
+
+**Migration:**
+
+- Remove `closeDelay` and `isDismissKeyboardOnClose` props from `Dialog.Root`
+- Remove custom `entering`/`exiting` animation configs from `Dialog.Root` animation prop (now only supports disable flags). Custom animations should be configured using Keyframe animations directly on `Dialog.Content` component
+- Remove `isAnimatedStyleActive` and `onLayout` props from `Dialog.Content`
+- Remove `isDismissKeyboardOnClose` prop from `BottomSheet.Root`
+- Update `BottomSheet.Overlay` animation prop to remove `entering`/`exiting` properties (no longer supported)
+- Make `presentation` prop explicit on all `Popover.Content` and `Select.Content` components (changed from optional to required)
+- Update animation hooks usage: `useBottomSheetAnimation()` no longer returns `bottomSheetState`, `useDialogAnimation()` no longer returns `dialogState`
+
+**What Changed:**
+
+- `Dialog.Root`: Removed `closeDelay` and `isDismissKeyboardOnClose` props
+- `Dialog.Root`: Animation prop type changed from `DialogRootAnimation` (supported custom entering/exiting) to `AnimationRootDisableAll` (disable flags only)
+- `Dialog.Content`: Removed `isAnimatedStyleActive` and `onLayout` props
+- `BottomSheet.Root`: Removed `isDismissKeyboardOnClose` prop
+- `BottomSheet.Overlay`: Animation prop no longer supports `entering`/`exiting` properties
+- `Popover.Content`: `presentation` prop is now required (was optional, defaulted to `"popover"`)
+- `Select.Content`: `presentation` prop is now required (was optional, defaulted to `"popover"`)
+- Animation hooks: `useBottomSheetAnimation()` no longer returns `bottomSheetState`, `useDialogAnimation()` no longer returns `dialogState`
+
+**Related PR:** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #181](https://github.com/heroui-inc/heroui-native/issues/181)**: Fixed TextField error when inputting Chinese characters. The TextField component now properly handles multibyte characters and international input, ensuring smooth text entry for all languages including Chinese, Japanese, and Korean.
+
+- **[Issue #219](https://github.com/heroui-inc/heroui-native/issues/219)**: Fixed Button `childrenToString()` returning `"[object Object]"` for multiple children. The function now properly handles React elements and complex children structures, preventing stringification issues when rendering button content.
+
+- **[Issue #232](https://github.com/heroui-inc/heroui-native/issues/232)**: Fixed HeroUINativeProvider breaking with the recently released Uniwind Pro. The provider now properly handles Uniwind Pro compatibility, ensuring smooth integration with the latest Uniwind version.
+
+- **[Issue #259](https://github.com/heroui-inc/heroui-native/issues/259)**: Fixed BottomSheet issue where opening quickly and starting a meeting would prevent it from opening again. The refactored animation system resolves this issue by improving the entering/exiting animation logic.
+
+- **[Issue #261](https://github.com/heroui-inc/heroui-native/issues/261)**: Fixed `@gorhom/bottom-sheet` not being tree-shaken. The library now properly supports tree-shaking for unused dependencies.
+
+**Additional Fixes:**
+
+- Fixed theme calculated colors issue that was causing incorrect color values in certain scenarios
+- Fixed `childrenToString` function to prevent React elements from being stringified incorrectly
+
+**Related PRs:**
+
+- [#226](https://github.com/heroui-inc/heroui-native/pull/226)
+- [#239](https://github.com/heroui-inc/heroui-native/pull/239)
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx b/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx
new file mode 100644
index 0000000..2735e66
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/cli-v1-0-0.mdx
@@ -0,0 +1,130 @@
+---
+title: CLI v1.0.0
+description:
+  New CLI for scaffolding a preconfigured HeroUI Native + Expo Router project — Expo SDK 56, React Native 0.85, Uniwind, all peer dependencies wired up, two starter templates (single-screen and tabs).
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">June 4, 2026</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/cli-demo.mp4"
+  height={430}
+  muted
+/>
+
+🎉 A new CLI — [`create-heroui-native-app`](https://www.npmjs.com/package/create-heroui-native-app) — is now the fastest way to start a HeroUI Native project. One command scaffolds a complete Expo Router app with HeroUI Native, Uniwind, Tailwind CSS, every required peer dependency, and the provider wiring already in place. No manual setup of `global.css`, `metro.config.js`, or `app/_layout.tsx`.
+
+## Quick Start
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npx create-heroui-native-app@latest my-app
+  ```
+</Tab>
+<Tab value="pnpm">
+  ```bash
+  pnpm create heroui-native-app@latest my-app
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn create heroui-native-app my-app
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun create heroui-native-app@latest my-app
+  ```
+</Tab>
+</Tabs>
+
+Then start the dev server:
+
+```bash
+cd my-app
+npm run start
+```
+
+That's it. Skip ahead to the [Quick Start guide](/docs/native/getting-started/quick-start) for the full walkthrough.
+
+## Starter Templates
+
+The CLI ships with two templates. Pick one in the interactive picker, or pass a flag to skip the prompt.
+
+| Flag | Template | Description |
+| --- | --- | --- |
+| `--expo` | `expo` | Single-screen Expo Router app with a HeroUI `Button` demo. |
+| `--expo-tabs` | `expo-tabs` | Expo Router tabs layout with two tabs (`Button` + `Card` demos). |
+
+```bash
+npx create-heroui-native-app@latest my-app --expo
+npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
+```
+
+## What You Get
+
+Every scaffolded project ships preconfigured with:
+
+- **Expo SDK 56** + **Expo Router** with typed routes enabled
+- **React 19.2** + **React Native 0.85.2** + Hermes v1 (default in SDK 56)
+- **HeroUI Native** wrapped in `HeroUINativeProvider` and `GestureHandlerRootView` inside `app/_layout.tsx`
+- **Uniwind** + **Tailwind CSS** wired through `metro.config.js` and `global.css`
+- All HeroUI Native **mandatory peer dependencies** pinned to compatible versions: `react-native-reanimated`, `react-native-gesture-handler`, `react-native-worklets`, `react-native-safe-area-context`, `react-native-svg`, `tailwind-variants`, `tailwind-merge`
+- `react-native-screens` so HeroUI overlay components (`Dialog`, `Menu`, `Popover`, `Select`, `BottomSheet`, `Toast`) work out of the box
+- `@expo/metro-runtime` (required peer for Expo Router on SDK 56)
+- A `babel.config.js` using just `babel-preset-expo` (worklets handled by the preset)
+- **TypeScript** with `strict: true` and the `@/*` path alias
+
+## CLI Reference
+
+```text
+create-heroui-native-app [project-name] [options]
+```
+
+| Option | Description |
+| --- | --- |
+| `[project-name]` | Directory name to create. Prompted if omitted. Must be a valid npm package name. |
+| `--expo` | Use the single-screen Expo template. |
+| `--expo-tabs` | Use the Expo + tabs template. |
+| `--template <id>` | Use the template with the given id (`expo` or `expo-tabs`). |
+| `--use-npm` / `--use-yarn` / `--use-pnpm` / `--use-bun` | Force a specific package manager (otherwise auto-detected). |
+| `--skip-install` | Don't run the package manager install step. |
+| `--skip-git` | Don't initialize a git repository. |
+| `-h`, `--help` | Print usage and exit. |
+
+### Examples
+
+```bash
+# Fully interactive — prompts for both project name and template
+npx create-heroui-native-app@latest
+
+# Project name supplied, template picker still shown
+npx create-heroui-native-app@latest my-app
+
+# Fully non-interactive
+npx create-heroui-native-app@latest my-app --expo
+
+# Tabs template, install with pnpm
+npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
+
+# Scaffold only, no install, no git
+npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git
+```
+
+## Requirements
+
+- **Node.js 20.19.4+** (required by Expo SDK 56 / React Native 0.85)
+- **iOS 16.4+** when building native iOS (Expo SDK 56 deployment target)
+- macOS, Linux, or Windows
+
+<Callout type="info">
+  **Already have an app?** The CLI is for new projects. To add HeroUI Native to an existing React Native or Expo app, follow [Option 2 in the Quick Start](/docs/native/getting-started/quick-start#option-2-add-to-an-existing-project).
+</Callout>
+
+## Links
+
+- [Quick Start guide](/docs/native/getting-started/quick-start)
+- [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server)
diff --git a/apps/docs/content/docs/en/native/releases/index.mdx b/apps/docs/content/docs/en/native/releases/index.mdx
new file mode 100644
index 0000000..4dd00bd
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/index.mdx
@@ -0,0 +1,172 @@
+---
+title: All Releases
+description: All updates and changes to HeroUI Native, including new features, fixes, and breaking changes.
+---
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Latest Release
+
+### v1.0.5
+
+**July 2026**
+
+This release upgrades the toolchain to Expo 57 / React Native 0.86 and refines field border styling with outline-based focus, active, and invalid states across form components. It also adds iOS Dynamic Type support to Typography, introduces provider-level text input configuration, and improves Popover, Menu, and Select with lighter, single-mount enter animations.
+
+[Read full release notes →](/docs/native/releases/v1-0-5)
+
+---
+
+### CLI v1.0.0
+
+**June 2026**
+
+🎉 A new CLI for scaffolding a HeroUI Native project in one command. `npx create-heroui-native-app@latest my-app` generates a complete Expo Router app with HeroUI Native, Uniwind, Tailwind CSS, every required peer dependency, and the provider wiring already in place — pick between a single-screen or tabs starter template.
+
+[Read full release notes →](/docs/native/releases/create-heroui-native-app)
+
+---
+
+### v1.0.4
+
+**May 2026**
+
+This patch release renames the `Text` typography component to `Typography` (with deprecated `Text` exports preserved for backward compatibility), refines soft-foreground theme tokens across `Alert`, `Avatar`, `Button`, `Chip`, and `Toast` with an optional `heroui-native/styles/vibrant` palette, documents the iOS native modal offset workaround for `Menu`, `Popover`, and `Select`, and upgrades the example app to Expo 56 / React Native 0.85 while bumping the `@gorhom/bottom-sheet` peer to `^5.2.9`.
+
+[Read full release notes →](/docs/native/releases/v1-0-4)
+
+---
+
+### v1.0.3
+
+**May 2026**
+
+This patch release introduces the new `Text` typography component with `Heading`, `Paragraph`, and `Code` sub-components, fixes `ScrollShadow` support for inverted lists and `Tabs` indicator alignment in RTL layouts, and unifies the `Select.TriggerIndicator` animation when using custom children. It also makes `Avatar`'s `alt` prop optional, refines `Button`, `Chip`, and `Input` styles, and corrects inner padding behavior for `TextField` and `SearchField`.
+
+[Read full release notes →](/docs/native/releases/v1-0-3)
+
+---
+
+### v1.0.2
+
+**April 2026**
+
+This patch release introduces the `asChild` slot pattern for PressableFeedback and Surface, adds VoiceOver modal containment support across all portal-based overlays, fixes an Android-specific Button outline variant styling issue, and refines Input and Select visual styles.
+
+[Read full release notes →](/docs/native/releases/v1-0-2)
+
+---
+
+### v1.0.1
+
+**April 2026**
+
+This patch release fixes a race condition in the Toast provider where the `total` SharedValue drifted from the actual toast count, corrects disabled-state styling across seven components to use the native `disabled:` modifier, and introduces the `--backdrop` theme variable for overlay components.
+
+[Read full release notes →](/docs/native/releases/v1-0-1)
+
+---
+
+### v1.0.0
+
+**March 2026**
+
+🎉 HeroUI Native reaches its first stable release, graduating from beta and release candidate stages. This milestone includes the new LinkButton component, sub-menu conflict resolution, an optional `@gorhom/bottom-sheet` peer dependency, and improved type safety for `useThemeColor`.
+
+[Read full release notes →](/docs/native/releases/v1-0-0)
+
+---
+
+### RC 4
+
+**March 2026**
+
+This release introduces the SubMenu compound component for nested expandable menus with animated expand/collapse, refactors Slider Output composition with slot-based styling and `textProps` forwarding, and fixes PressableFeedback ripple animation blink on rapid presses.
+
+[Read full release notes →](/docs/native/releases/rc-4)
+
+---
+
+### RC 3
+
+**February 2026**
+
+This release introduces three new components—TagGroup, Menu, and InputGroup—adds Android hardware back button support for all bottom-sheet-based overlays, and achieves Expo 55 compatibility with a critical `combineStyles` fix that preserves Reanimated animated style bindings.
+
+[Read full release notes →](/docs/native/releases/rc-3)
+
+---
+
+### RC 2
+
+**February 2026**
+
+This release introduces three new components—SearchField, ListGroup, and Slider—adds multi-selection mode to Select with type-safe generics, and refactors the Button feedback API into a unified `feedbackVariant` + `animation` prop pattern. Peer dependency constraints are relaxed for broader Expo SDK 55 compatibility, and several Select and Avatar bugs are fixed.
+
+[Read full release notes →](/docs/native/releases/rc-2)
+
+---
+
+### RC 1
+
+**February 2026**
+
+This release introduces the Alert compound component with five status variants and accessibility primitives, extracts Radio into a standalone component with dual-mode operation, and adds the animated Select.TriggerIndicator subcomponent. It also delivers HeroUINativeProviderRaw for bundle optimization, a `disableFullWindowOverlay` prop for iOS debugging, unified `styles` prop support across six components, and theme surface variable refactoring with explicit per-theme definitions.
+
+[Read full release notes →](/docs/native/releases/rc-1)
+
+---
+
+### Beta 13
+
+**February 2026**
+
+This release introduces the TextArea component for multiline text input, adds Button outline variant, exports style class names for all components, and includes a reusable CloseButton component. The release also refactors Tabs with improved animations and variant naming, decomposes form components into standalone primitives, and adds granular exports for bundle optimization. Critical bug fixes for theme colors and component stringification are also included.
+
+[Read full release notes →](/docs/native/releases/beta-13)
+
+---
+
+### Beta 12
+
+**January 2026**
+
+This release introduces three essential form components—InputOTP, Label, and Description—that enhance form building capabilities in React Native applications. The release also includes critical fixes for Popover close behavior, popup controlled state management, border radius configuration, and adds variant style prop support across multiple form components.
+
+[Read full release notes →](/docs/native/releases/beta-12)
+
+---
+
+### Beta 11
+
+**January 2026**
+
+This release enhances component reliability and developer experience with improved close coordination for Bottom Sheet, fixes for Dialog swipe-to-dismiss gestures, TextField styling improvements, and a new PortalHost export for advanced portal mounting scenarios. These updates ensure smoother interactions and provide more flexibility for custom layouts.
+
+[Read full release notes →](/docs/native/releases/beta-11)
+
+---
+
+### Beta 10
+
+**December 2025**
+
+This release introduces the new [Bottom Sheet](/docs/native/components/bottom-sheet) component, refactors [PressableFeedback](/docs/native/components/pressable-feedback) with improved API, extends the Animation API with State Prop support, enhances the `use-theme-color` hook to handle multiple colors selection, and includes various bug fixes and documentation improvements.
+
+[Read full release notes →](/docs/native/releases/beta-10)
+
+---
+
+## Release Schedule
+
+HeroUI Native follows a regular release cycle:
+
+- **Stable releases**: v1.0.0 shipped Q1 2026
+- **Patch releases**: Bug fixes and minor improvements as needed
+
+## Contributing
+
+Found an issue or want to contribute? Check out our [GitHub repository](https://github.com/heroui-inc/heroui-native).
+
diff --git a/apps/docs/content/docs/en/native/releases/meta.json b/apps/docs/content/docs/en/native/releases/meta.json
new file mode 100644
index 0000000..a700e08
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/meta.json
@@ -0,0 +1,26 @@
+{
+  "title": "Releases",
+  "description": "HeroUI Native Release Notes",
+  "icon": "rocket",
+  "root": true,
+  "pages": [
+    "---Overview---",
+    "index",
+    "---Releases---",
+    "v1-0-5",
+    "cli-v1-0-0",
+    "v1-0-4",
+    "v1-0-3",
+    "v1-0-2",
+    "v1-0-1",
+    "v1-0-0",
+    "rc-4",
+    "rc-3",
+    "rc-2",
+    "rc-1",
+    "beta-13",
+    "beta-12",
+    "beta-11",
+    "beta-10"
+  ]
+}
diff --git a/apps/docs/content/docs/en/native/releases/rc-1.mdx b/apps/docs/content/docs/en/native/releases/rc-1.mdx
new file mode 100644
index 0000000..12579f3
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/rc-1.mdx
@@ -0,0 +1,473 @@
+---
+title: RC 1
+description: Alert component, standalone Radio component, Select TriggerIndicator, HeroUINativeProviderRaw, disableFullWindowOverlay prop, styles prop expansion, theme surface refactor
+github:
+  pull: 284
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 12, 2026</span>
+</div>
+
+RC 1 marks the first Release Candidate for HeroUI Native, signaling that the library is approaching production readiness. This release introduces the Alert compound component with accessibility-first design and status variants, extracts Radio into a standalone component with dual-mode operation, and adds the animated Select.TriggerIndicator subcomponent. It also delivers a lightweight HeroUINativeProviderRaw for bundle optimization, a new `disableFullWindowOverlay` prop for iOS debugging, unified `styles` prop support across six components, and a theme refactor that replaces calculated surface colors with explicit theme-defined variables. Several critical bug fixes—including InputOTP in BottomSheet, toast text clipping, and element inspector compatibility—round out the release.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **1 new** component:
+
+- **[Alert](/docs/native/components/alert)**: Accessible alert component with five status variants and compound sub-components for flexible content composition.
+
+#### Alert
+
+The Alert component provides accessible alert messaging with built-in support for five status variants: default, accent, success, warning, and danger. It follows the compound component pattern with `Alert.Indicator`, `Alert.Content`, `Alert.Title`, and `Alert.Description` sub-components, giving developers full control over layout and customization. The primitive layer provides `role="alert"`, `aria-labelledby`, and `aria-describedby` accessibility associations automatically.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="alert"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/alert-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Five status variants: default, accent, success, warning, and danger
+- Default SVG status icons with theme-aware colors via `useStatusColor` hook
+- Compound component architecture with Indicator, Content, Title, and Description sub-components
+- Custom indicator support (e.g., replace default icon with a Spinner)
+- Accessibility primitives with `role="alert"`, `aria-labelledby`, and `aria-describedby`
+- `asChild` slot support on all sub-components
+- Ref forwarding and `className` prop support on all parts
+
+**Usage:**
+
+```tsx
+import { Alert } from "heroui-native";
+
+export function Example() {
+  return (
+    <Alert status="success">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Payment successful</Alert.Title>
+        <Alert.Description>
+          Your payment has been processed successfully.
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+For complete documentation and examples, see the [Alert component page](/docs/native/components/alert).
+
+**Related PR:** [#284](https://github.com/heroui-inc/heroui-native/pull/284)
+
+### New Subcomponents
+
+#### Select.TriggerIndicator
+
+The [Select](/docs/native/components/select) component now includes a `TriggerIndicator` subcomponent that displays an animated chevron icon to visually indicate the open/close state. The indicator rotates smoothly when the select opens or closes, using React Native Reanimated spring physics.
+
+**Features:**
+
+- Animated chevron icon that rotates on open/close transitions
+- Customizable animation configuration via `animation` prop with rotation values and spring config
+- Icon customization through `iconProps` (size, color)
+- Support for custom children to replace the default chevron
+- Automatic state synchronization with Select open/close state
+
+**Usage:**
+
+```tsx
+import { Select } from "heroui-native";
+
+<Select>
+  <Select.Trigger>
+    <Select.Value placeholder="Select an option" />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Content>
+      {/* Select items */}
+    </Select.Content>
+  </Select.Portal>
+</Select>
+```
+
+**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+## Component Improvements
+
+### Toast Styling and Stacking Refactor
+
+The [Toast](/docs/native/components/toast) component styling has been refactored to replace the border-based padding approach with proper padding and vertical placeholder views, improving content visibility when toasts stack.
+
+**Improvements:**
+
+- Replaced `border-[16px]` padding workaround with proper `p-4` padding
+- Added `useVerticalPlaceholderStyles` hook for placeholder view styling
+- Added absolute positioned placeholder Views at top and bottom to prevent content visibility when toasts stack
+- Updated shadow system to use `shadow-overlay` token
+- Standardized overlay shadow values across all themes (alpha, mint, sky) with lighter opacity
+
+This refactor ensures content remains properly hidden when toasts of different heights stack together, while providing a more maintainable and predictable styling approach.
+
+**Related PR:** [#229](https://github.com/heroui-inc/heroui-native/pull/229)
+
+### Dialog Overlay Animation Fix
+
+The [Dialog](/docs/native/components/dialog) component's popup animation timing has been fixed when closing via gesture. The progress value is now properly sequenced with delays to ensure the closing animation completes before resetting.
+
+**Improvements:**
+
+- Progress value now transitions to 2 after a 300ms delay when closing via gesture
+- Progress resets to 0 after 350ms to ensure animation completion
+- Removed immediate `progress.set(2)` call when `isOpen` becomes false
+- Smooth closing animations now play correctly when dismissing popups via swipe gestures
+
+**Related PR:** [#277](https://github.com/heroui-inc/heroui-native/pull/277)
+
+### Theme Surface Variables Refactor
+
+The theme system has been refactored to replace calculated surface colors with explicit theme-defined variables, providing more control and consistency across themes.
+
+**Improvements:**
+
+- `surface-secondary` and `surface-tertiary` (with foregrounds) are now defined explicitly in each theme (alpha, lavender, mint, sky, variables.css)
+- Base theme uses `var(--surface-secondary)` and `var(--surface-tertiary)` instead of `color-mix` calculations
+- Removed `on-surface`, `on-surface-secondary`, and `on-surface-tertiary` palettes from theme.css
+- Updated theming documentation with the new variable structure and examples
+
+This change gives theme authors direct control over surface color values rather than relying on `color-mix` calculations, resulting in more predictable and consistent surface styling across all themes.
+
+**Related PR:** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
+
+## API Enhancements
+
+### Unified `styles` Prop for Multiple Components
+
+Six components now support the unified `styles` prop for slot-based styling, providing a consistent pattern for applying styles to component internals.
+
+**Supported components:**
+
+- **Accordion**: `container` and `separator` slots
+- **AvatarFallback**: `container` and `text` slots
+- **FieldError**: `container` and `text` slots
+- **Label**: `text` and `asterisk` slots (also fixed `style` prop handling)
+- **PressableFeedback Ripple**: `container` and `ripple` slots (replaces `containerStyle` and `rippleStyle`)
+- **SelectContentDialog**: `wrapper` and `content` slots
+
+**New Capability:**
+
+```tsx
+import { Accordion, Label } from "heroui-native";
+
+// Apply styles to specific slots
+<Label styles={{ text: { fontSize: 18 }, asterisk: { color: "red" } }} isRequired>
+  Username
+</Label>
+
+<Accordion
+  styles={{
+    container: { borderRadius: 12 },
+    separator: { backgroundColor: "gray" },
+  }}
+>
+  {/* Accordion items */}
+</Accordion>
+```
+
+All changes maintain backward compatibility with existing `style` props and properly merge styles when both are provided.
+
+**Related PR:** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
+
+### `disableFullWindowOverlay` Prop
+
+Portal-based components now support a `disableFullWindowOverlay` prop that enables React Native element inspector support on iOS during development.
+
+**Supported components:**
+
+- `BottomSheet.Portal`
+- `Dialog.Portal`
+- `Popover.Portal`
+- `Select.Portal`
+- `ToastProvider`
+
+**New Capability:**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+// Enable element inspector support on iOS
+<Dialog>
+  <Dialog.Portal disableFullWindowOverlay>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      {/* content */}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+On iOS, `FullWindowOverlay` uses a separate native window that blocks the React Native element inspector. Setting `disableFullWindowOverlay` to `true` renders content in the main window instead, enabling the inspector during development. The tradeoff is that overlays will no longer appear above native modals or the keyboard. This prop has no effect on Android.
+
+For Toast, the prop is passed via `config.toast` when using `HeroUINativeProvider`.
+
+**Related PR:** [#283](https://github.com/heroui-inc/heroui-native/pull/283)
+
+### HeroUINativeProviderRaw
+
+A new lightweight provider variant, `HeroUINativeProviderRaw`, excludes `ToastProvider` and `PortalHost` to give consumers full control over which dependencies are bundled.
+
+**New Capability:**
+
+```tsx
+import { HeroUINativeProviderRaw } from "heroui-native/provider-raw";
+
+// Lightweight provider without Toast and Portal dependencies
+export function App() {
+  return (
+    <HeroUINativeProviderRaw>
+      {/* Your app content */}
+    </HeroUINativeProviderRaw>
+  );
+}
+```
+
+This makes `react-native-screens`, `@gorhom/bottom-sheet`, and `react-native-svg` fully optional dependencies. The raw provider includes only `SafeAreaListener`, `GlobalAnimationSettingsProvider`, and `TextComponentProvider`. Consumers who need toast or portal features can compose them manually.
+
+**Related PR:** [#285](https://github.com/heroui-inc/heroui-native/pull/285)
+
+### Select.Trigger `variant` Prop
+
+The `Select.Trigger` component now supports a `variant` prop with `"default"` and `"unstyled"` options, enabling better composition with custom trigger components like Button.
+
+**New Capability:**
+
+```tsx
+import { Button, Select } from "heroui-native";
+
+// Default variant (pre-styled trigger)
+<Select>
+  <Select.Trigger variant="default">
+    <Select.Value placeholder="Choose..." />
+    <Select.TriggerIndicator />
+  </Select.Trigger>
+</Select>
+
+// Unstyled variant for custom compositions
+<Select>
+  <Select.Trigger variant="unstyled">
+    <Button>
+      <Select.Value placeholder="Choose..." />
+      <Select.TriggerIndicator />
+    </Button>
+  </Select.Trigger>
+</Select>
+```
+
+**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+### ControlField Radio Variant
+
+The [ControlField](/docs/native/components/control-field) component now supports a `"radio"` variant in `ControlField.Indicator`, rendering a standalone Radio component alongside the existing `"switch"` and `"checkbox"` variants.
+
+**New Capability:**
+
+```tsx
+import { ControlField } from "heroui-native";
+
+<ControlField>
+  <ControlField.Indicator variant="radio" />
+  <ControlField.Label>Radio option</ControlField.Label>
+</ControlField>
+```
+
+**Related PR:** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
+
+## ⚠️ Breaking Changes
+
+### PressableFeedback Ripple: Unified `styles` Prop
+
+The PressableFeedback Ripple component's individual style props (`containerStyle` and `rippleStyle`) have been replaced with a unified `styles` prop.
+
+**Migration:**
+
+Update all instances of individual style props to the unified `styles` prop:
+
+```tsx
+// Before
+<PressableFeedback.Ripple
+  containerStyle={{ borderRadius: 8 }}
+  rippleStyle={{ backgroundColor: "blue" }}
+/>
+
+// After
+<PressableFeedback.Ripple
+  styles={{
+    container: { borderRadius: 8 },
+    ripple: { backgroundColor: "blue" },
+  }}
+/>
+```
+
+**Related PR:** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
+
+### Select.Trigger Default Styles
+
+`Select.Trigger` now defaults to `variant="default"`, which applies default container styles (`flex-row items-center justify-between h-12 px-4 rounded-2xl bg-surface shadow-surface`). Users with custom styled triggers need to add `variant="unstyled"` to prevent default styles from being applied.
+
+**Migration:**
+
+```tsx
+// Before (custom styled trigger)
+<Select.Trigger className="custom-trigger-styles">
+  {/* content */}
+</Select.Trigger>
+
+// After (add variant="unstyled" to preserve custom styling)
+<Select.Trigger variant="unstyled" className="custom-trigger-styles">
+  {/* content */}
+</Select.Trigger>
+```
+
+**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
+
+### Surface Theme Variables Restructured
+
+The `on-surface`, `on-surface-secondary`, and `on-surface-tertiary` CSS variables and their hover/focus variants have been removed from the base theme. Surface secondary and tertiary colors are now defined explicitly in each theme file.
+
+**Migration:**
+
+If you reference `on-surface`, `on-surface-secondary`, or `on-surface-tertiary` variables in custom styles, replace them with the appropriate surface foreground variables defined in your theme.
+
+```css
+/* Before */
+color: var(--on-surface);
+color: var(--on-surface-secondary);
+
+/* After */
+color: var(--surface-foreground);
+color: var(--surface-secondary-foreground);
+```
+
+**Related PR:** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
+
+### RadioGroup Indicator Removed
+
+`RadioGroup.Indicator` and `RadioGroup.IndicatorThumb` have been removed in favor of the new standalone `Radio` component. The related types `RadioGroupIndicatorProps`, `RadioGroupIndicatorThumbProps`, and `RadioGroupIndicatorThumbAnimation` are also removed from exports.
+
+**Migration:**
+
+Replace all `RadioGroup.Indicator` and `RadioGroup.IndicatorThumb` usages with the `Radio` component:
+
+```tsx
+// Before
+import { RadioGroup } from "heroui-native";
+
+<RadioGroup>
+  <RadioGroup.Item value="option1">
+    <RadioGroup.Indicator>
+      <RadioGroup.IndicatorThumb />
+    </RadioGroup.Indicator>
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+</RadioGroup>
+
+// After
+import { Radio, RadioGroup } from "heroui-native";
+
+<RadioGroup>
+  <RadioGroup.Item value="option1">
+    <Radio>
+      <Radio.Indicator>
+        <Radio.IndicatorThumb />
+      </Radio.Indicator>
+    </Radio>
+    <RadioGroup.Label>Option 1</RadioGroup.Label>
+  </RadioGroup.Item>
+</RadioGroup>
+```
+
+**Related PR:** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #229](https://github.com/heroui-inc/heroui-native/issues/229)**: Fixed InputOTP not working inside BottomSheet. The InputOTP component now functions correctly when rendered within a BottomSheet overlay, resolving input focus and interaction issues that previously prevented OTP entry in bottom sheet contexts.
+
+- **[Issue #265](https://github.com/heroui-inc/heroui-native/issues/265)**: Fixed the first letter of Toast description text being clipped. The toast styling refactor replaces the border-based padding approach with proper padding and placeholder views, ensuring all text content is fully visible regardless of toast stacking configuration.
+
+- **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**: Fixed FullWindowOverlay blocking the React Native element inspector on iOS. The new `disableFullWindowOverlay` prop on portal components allows developers to render overlay content in the main window during development, restoring element inspector functionality.
+
+**Related PRs:**
+
+- [#229](https://github.com/heroui-inc/heroui-native/pull/229)
+- [#283](https://github.com/heroui-inc/heroui-native/pull/283)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Alert](/docs/native/components/alert) - New component documentation with usage examples and API reference
+- [Radio](/docs/native/components/radio) - New standalone Radio component documentation
+- [Radio Group](/docs/native/components/radio-group) - Updated to reflect RadioGroup.Indicator removal and Radio integration
+- [Control Field](/docs/native/components/control-field) - Updated with new radio variant documentation
+- [Select](/docs/native/components/select) - TriggerIndicator subcomponent and Trigger variant documentation
+- [Toast](/docs/native/components/toast) - Updated styling approach documentation
+- [Bottom Sheet](/docs/native/components/bottom-sheet) - Added disableFullWindowOverlay documentation
+- [Dialog](/docs/native/components/dialog) - Added disableFullWindowOverlay documentation
+- [Popover](/docs/native/components/popover) - Added disableFullWindowOverlay documentation
+- [Provider](/docs/native/getting-started/provider) - HeroUINativeProviderRaw documentation and provider hierarchy
+- [Theming](/docs/native/getting-started/theming) - Updated surface variable structure and examples
+- [Accordion](/docs/native/components/accordion) - Added styles prop documentation
+- [Avatar](/docs/native/components/avatar) - Added styles prop documentation
+- [Label](/docs/native/components/label) - Added styles prop documentation
+- [Field Error](/docs/native/components/field-error) - Added styles prop documentation
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/rc-2.mdx b/apps/docs/content/docs/en/native/releases/rc-2.mdx
new file mode 100644
index 0000000..d95e145
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/rc-2.mdx
@@ -0,0 +1,420 @@
+---
+title: RC 2
+description: SearchField, ListGroup, and Slider components, Select multi-selection mode, Button feedback API refactor, peer dependency relaxation
+github:
+  pull: 298
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 20, 2026</span>
+</div>
+
+RC 2 continues the march toward production readiness with three new components—SearchField, ListGroup, and Slider—and a powerful multi-selection mode for Select backed by type-safe generics. The Button feedback API has been refactored into a cleaner unified `feedbackVariant` + `animation` prop pattern, and peer dependency constraints are relaxed for broader compatibility with Expo SDK 55. Several Select and Avatar bug fixes round out the release.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **3 new** components:
+
+- **[Slider](/docs/native/components/slider)**: Slider component with single-value and range modes, horizontal/vertical orientation, custom number formatting, and spring-animated thumb feedback.
+- **[ListGroup](/docs/native/components/list-group)**: Surface-based grouped list component with pressable items, prefix/suffix slots, and default chevron navigation indicator.
+- **[SearchField](/docs/native/components/search-field)**: Compound component for filtering and querying content with built-in search icon, clearable input, and auto-hide clear button.
+
+#### Slider
+
+The Slider component supports single-value and range (multi-thumb) modes, horizontal and vertical orientation, custom number formatting via `Intl.NumberFormat`, and spring-animated thumb feedback. The primitive layer handles all gesture and value logic independently, making it reusable for alternative styled implementations.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="slider"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/slider-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `Slider.Output`, `Slider.Track`, `Slider.Fill`, `Slider.Thumb`
+- Range slider: pass an array as `defaultValue`/`value` and use a render-function on `Slider.Track` to render multiple thumbs
+- Vertical orientation via `orientation="vertical"`
+- Custom formatting with `formatOptions` accepting `Intl.NumberFormatOptions` (currency, percent, unit, etc.)
+- Gesture-handler-based drag and tap-to-position on track
+- Value clamping, stepping, and multi-thumb support
+- Spring-animated thumb scale via configurable `animation` prop
+- Accessibility: each thumb receives `role="slider"` with full `accessibilityValue` (min, max, now, text)
+- `useSlider` hook exposes slider context for advanced use cases
+
+**Usage:**
+
+```tsx
+import { Slider } from "heroui-native";
+
+export function BasicSlider() {
+  return (
+    <Slider defaultValue={50} minValue={0} maxValue={100}>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
+
+export function RangeSlider() {
+  return (
+    <Slider defaultValue={[20, 80]} minValue={0} maxValue={100}>
+      <Slider.Output />
+      <Slider.Track>
+        {({ thumbs }) => (
+          <>
+            <Slider.Fill />
+            {thumbs.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+For complete documentation and examples, see the [Slider component page](/docs/native/components/slider).
+
+**Related PR:** [#305](https://github.com/heroui-inc/heroui-native/pull/305)
+
+#### ListGroup
+
+The ListGroup component renders grouped list items inside a Surface container, providing a polished navigation-list pattern commonly used in settings screens, menus, and content browsers. Each item supports prefix, content (title + description), and suffix slots with a default chevron-right navigation indicator.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="list-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/list-group-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Surface-based container with rounded corners and consistent spacing
+- Compound sub-components: `ListGroup.Item`, `ListGroup.ItemPrefix`, `ListGroup.ItemContent`, `ListGroup.ItemTitle`, `ListGroup.ItemDescription`, `ListGroup.ItemSuffix`
+- Default chevron-right icon in `ItemSuffix` via internal `ChevronRightIcon`
+- Pressable items with PressableFeedback integration
+- Fully customizable slots for icons, badges, and other content
+
+**Usage:**
+
+```tsx
+import { ListGroup } from "heroui-native";
+
+export function Example() {
+  return (
+    <ListGroup>
+      <ListGroup.Item onPress={() => console.log("Profile")}>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Profile</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>Manage your account</ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+      <ListGroup.Item onPress={() => console.log("Settings")}>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Settings</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>App preferences</ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </ListGroup>
+  );
+}
+```
+
+For complete documentation and examples, see the [ListGroup component page](/docs/native/components/list-group).
+
+**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+#### SearchField
+
+The SearchField component provides a dedicated input for search and filtering scenarios, built with the same compound-component pattern used by TextField. It includes a search icon, clearable input, and an auto-hiding clear button that disappears when the input is empty.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="search-field"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/search-field-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `SearchField.Group`, `SearchField.SearchIcon`, `SearchField.Input`, `SearchField.ClearButton`
+- `ClearButton` auto-hides when value is empty and clears search text on press
+- `SearchIcon` supports custom children to replace the default magnifying glass SVG
+- Validation state support with visual feedback
+- Disabled state support
+- Seamless integration with Label, Description, and FieldError
+
+**Usage:**
+
+```tsx
+import { Label, SearchField } from "heroui-native";
+
+export function Example() {
+  return (
+    <SearchField>
+      <Label>Search</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input placeholder="Search components..." />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
+```
+
+For complete documentation and examples, see the [SearchField component page](/docs/native/components/search-field).
+
+**Related PR:** [#299](https://github.com/heroui-inc/heroui-native/pull/299)
+
+### Select Multi-Selection Mode
+
+The [Select](/docs/native/components/select) component now supports multi-item selection via a new `selectionMode` prop. The `RootProps` type is now generic on `SelectionMode`, so TypeScript correctly resolves `value` and `onValueChange` types per mode—`SelectOption` for single, `SelectOption[]` for multiple.
+
+**Features:**
+
+- `selectionMode="multiple"` enables toggling multiple items; `closeOnPress` defaults to `false` in multiple mode
+- Type-safe generics: `RootProps<M>` resolves `value` and `onValueChange` types via `SelectValueType<M>`
+- `Select.Value` formats multiple labels as "Apple, Banana and Cherry" using `formatSelectedLabels`
+- Single mode remains fully backward-compatible (default)
+
+**Usage:**
+
+```tsx
+import { Select } from "heroui-native";
+
+export function MultiSelect() {
+  return (
+    <Select selectionMode="multiple">
+      <Select.Trigger>
+        <Select.Value placeholder="Select fruits..." />
+        <Select.TriggerIndicator />
+      </Select.Trigger>
+      <Select.Portal>
+        <Select.Content>
+          <Select.Item value="apple" label="Apple" />
+          <Select.Item value="banana" label="Banana" />
+          <Select.Item value="cherry" label="Cherry" />
+        </Select.Content>
+      </Select.Portal>
+    </Select>
+  );
+}
+```
+
+**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+### New Subcomponents
+
+#### PressableFeedback.Scale
+
+A new compound sub-component for opt-in scale animation composability. `PressableFeedback.Scale` lets you add scale press animations to any pressable element—such as `ListGroup.Item`—without needing the root `PressableFeedback` to manage scale.
+
+**Usage:**
+
+```tsx
+import { PressableFeedback } from "heroui-native";
+
+<PressableFeedback.Scale>
+  <ListGroup.Item onPress={handlePress}>
+    {/* item content */}
+  </ListGroup.Item>
+</PressableFeedback.Scale>
+```
+
+**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## Component Improvements
+
+### Select Trigger and State Fixes
+
+The [Select](/docs/native/components/select) component has been improved with several targeted fixes to the trigger and controllable state system.
+
+**Improvements:**
+
+- Custom `className` is now correctly forwarded to the trigger's style computation, resolving cases where user-provided classes were silently dropped
+- `useControllableState` now resets internal state when transitioning from controlled to uncontrolled, preventing stale selections from persisting
+- Trigger measures position via `onLayout` to properly support `isDefaultOpen`
+- Updated trigger styles to use `gap-3`, `py-3.5` padding, and `flex-1` on the value text for improved layout
+
+**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+### Avatar asChild Image Fix
+
+The [Avatar](/docs/native/components/avatar) component's `AvatarImage` now correctly separates `source`, `style`, and `asChild` from rest props when forwarding to the underlying primitive, fixing an issue where all props were incorrectly spread to the image component when using `asChild`.
+
+**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+
+## API Enhancements
+
+### Button Feedback API Refactor
+
+The [Button](/docs/native/components/button) component's pressable feedback API has been refactored into a unified, type-safe `feedbackVariant` + `animation` prop pattern, replacing the previous multi-prop approach.
+
+**New Capability:**
+
+```tsx
+import { Button } from "heroui-native";
+
+// Scale + highlight (default)
+<Button feedbackVariant="scale-highlight">Press me</Button>
+
+// Scale + ripple
+<Button feedbackVariant="scale-ripple">Press me</Button>
+
+// Scale only
+<Button feedbackVariant="scale">Press me</Button>
+
+// Custom animation configuration
+<Button
+  feedbackVariant="scale-highlight"
+  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
+>
+  Press me
+</Button>
+```
+
+The `animation` prop is a discriminated union typed per variant, providing full type-safety for each feedback configuration.
+
+New utility helpers `resolveAnimationObject` and `isAnimationDisabled` in `button.utils.ts` centralise animation prop resolution.
+
+**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## Dependencies
+
+### Relaxed Peer Dependency Constraints
+
+Peer dependency version constraints have been relaxed to use caret (`^`) and range (`>=`) specifiers instead of restrictive tilde (`~`) or pinned versions. This improves compatibility for consumers on newer dependency versions, particularly those using Expo SDK 55.
+
+**Changes:**
+
+- `react-native-reanimated`: `~4.1.1` → `^4.1.1` (allows minor updates)
+- `react-native-safe-area-context`: `~5.6.0` → `^5.6.0` (allows minor updates)
+- `react-native-svg`: `15.12.1` → `^15.12.1` (allows patch/minor updates)
+- `react-native-worklets`: `0.5.1` → `>=0.5.1` (allows any version 0.5.1+)
+
+No runtime code changes are included—existing projects with previously valid versions continue to work without modification.
+
+**Related PR:** [#306](https://github.com/heroui-inc/heroui-native/pull/306)
+
+## ⚠️ Breaking Changes
+
+### Button Feedback API
+
+The `pressableFeedbackVariant`, `pressableFeedbackHighlightProps`, and `pressableFeedbackRippleProps` props on Button have been removed. Consumers must migrate to `feedbackVariant` and the unified `animation` prop.
+
+**Migration:**
+
+Update all Button feedback prop usages:
+
+```tsx
+// Before
+<Button
+  pressableFeedbackVariant="highlight"
+  pressableFeedbackHighlightProps={{ color: "rgba(0,0,0,0.1)" }}
+>
+  Press me
+</Button>
+
+// After
+<Button
+  feedbackVariant="scale-highlight"
+  animation={{ scale: 0.95, highlight: { color: "rgba(0,0,0,0.1)" } }}
+>
+  Press me
+</Button>
+```
+
+**Variant mapping:**
+
+- `"highlight"` → `"scale-highlight"` (default)
+- `"ripple"` → `"scale-ripple"`
+- `"none"` → `"scale"` or `"none"`
+
+**Available options:**
+
+- `"scale-highlight"` - Scale down with highlight overlay (default)
+- `"scale-ripple"` - Scale down with ripple effect
+- `"scale"` - Scale down only
+- `"none"` - No feedback animation
+
+**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #291](https://github.com/heroui-inc/heroui-native/issues/291)**: Fixed `Select.Trigger` variant prop being overwritten by `className`. Custom class names passed to the trigger are now correctly forwarded to the style computation instead of being silently dropped.
+
+- **[Issue #294](https://github.com/heroui-inc/heroui-native/issues/294)**: Resolved compatibility with `react-native-worklets` 0.7.x and `react-native-reanimated` 4.2.x (Expo SDK 55). Peer dependency constraints have been relaxed to accept these newer versions without producing resolution warnings.
+
+**Related PRs:**
+
+- [#298](https://github.com/heroui-inc/heroui-native/pull/298)
+- [#306](https://github.com/heroui-inc/heroui-native/pull/306)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [SearchField](/docs/native/components/search-field) - New component documentation with usage examples and API reference
+- [ListGroup](/docs/native/components/list-group) - New component documentation with usage examples and API reference
+- [Slider](/docs/native/components/slider) - New component documentation with usage examples and API reference
+- [Select](/docs/native/components/select) - Multi-selection mode, trigger className fix, and controllable state improvements
+- [Button](/docs/native/components/button) - Updated feedback API documentation with new `feedbackVariant` and `animation` props
+- [Avatar](/docs/native/components/avatar) - Fixed `asChild` image prop spreading documentation
+- [PressableFeedback](/docs/native/components/pressable-feedback) - New `PressableFeedback.Scale` subcomponent documentation
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/rc-3.mdx b/apps/docs/content/docs/en/native/releases/rc-3.mdx
new file mode 100644
index 0000000..275ef12
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/rc-3.mdx
@@ -0,0 +1,332 @@
+---
+title: RC 3
+description: TagGroup, Menu, and InputGroup components, Bottom Sheet Android back press fix, Expo 55 compatibility
+github:
+  pull: 309
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 26, 2026</span>
+</div>
+
+RC 3 delivers three new components—TagGroup for selectable tag management, Menu for popover/bottom-sheet-based dropdown menus, and InputGroup for decorated text inputs with auto-measuring prefix/suffix slots. This release also brings Android hardware back button support for all bottom-sheet-based overlays, Expo 55 compatibility with a critical `combineStyles` fix that preserves Reanimated animated style bindings, and several dependency upgrades.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **3 new** components:
+
+- **[TagGroup](/docs/native/components/tag-group)**: Compound component for displaying and managing selectable tags with optional removal, single/multiple selection, and form field integration.
+- **[Menu](/docs/native/components/menu)**: Dropdown menu system with popover and bottom-sheet presentation modes, single/multiple selection, item variants, and animated press feedback.
+- **[InputGroup](/docs/native/components/input-group)**: Decorated text input with absolutely-positioned prefix/suffix slots that auto-measure widths and apply matching padding to the input.
+
+#### TagGroup
+
+The TagGroup component provides a compound component pattern for rendering selectable tag groups with optional removal support. It supports single and multiple selection modes, controlled and uncontrolled APIs, two visual variants (default and surface), three sizes, disabled states, and full form field integration with Label, Description, and FieldError.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="tag-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/tag-group-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `TagGroup.List`, `TagGroup.Item`, `TagGroup.ItemLabel`, `TagGroup.ItemRemoveButton`
+- Single and multiple selection modes with controlled/uncontrolled APIs
+- Two visual variants: `default` and `surface`
+- Three sizes: `sm`, `md`, `lg`
+- Per-item disabled state and `disabledKeys` support
+- Remove functionality via `onRemove` callback and `TagGroup.ItemRemoveButton`
+- Empty state rendering via `renderEmptyState` on `TagGroup.List`
+- Form field integration with Label, Description, FieldError, `isInvalid`, and `isRequired`
+- `useTagGroup` and `useTagGroupItem` hooks for advanced use cases
+
+**Usage:**
+
+```tsx
+import { TagGroup } from "heroui-native";
+
+export function BasicTagGroup() {
+  return (
+    <TagGroup>
+      <TagGroup.List>
+        <TagGroup.Item id="react">
+          <TagGroup.ItemLabel>React</TagGroup.ItemLabel>
+        </TagGroup.Item>
+        <TagGroup.Item id="vue">
+          <TagGroup.ItemLabel>Vue</TagGroup.ItemLabel>
+        </TagGroup.Item>
+        <TagGroup.Item id="svelte">
+          <TagGroup.ItemLabel>Svelte</TagGroup.ItemLabel>
+        </TagGroup.Item>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+
+export function RemovableTagGroup() {
+  const [items, setItems] = useState(["React", "Vue", "Svelte"]);
+
+  return (
+    <TagGroup onRemove={(keys) => setItems((prev) => prev.filter((i) => !keys.has(i)))}>
+      <TagGroup.List>
+        {items.map((item) => (
+          <TagGroup.Item key={item} id={item}>
+            <TagGroup.ItemLabel>{item}</TagGroup.ItemLabel>
+            <TagGroup.ItemRemoveButton />
+          </TagGroup.Item>
+        ))}
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+```
+
+For complete documentation and examples, see the [TagGroup component page](/docs/native/components/tag-group).
+
+**Related PR:** [#309](https://github.com/heroui-inc/heroui-native/pull/309)
+
+#### Menu
+
+The Menu component provides a dropdown menu system built on a compound component pattern, supporting both popover and bottom-sheet presentation modes. It includes full Reanimated-based press animations, single and multiple selection modes, item variants (default and danger), indicator styles, and configurable placement.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="menu"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `Menu.Trigger`, `Menu.Portal`, `Menu.Overlay`, `Menu.Content`, `Menu.Label`, `Menu.Group`, `Menu.Item`, `Menu.ItemTitle`, `Menu.ItemDescription`, `Menu.ItemIndicator`
+- Two presentation modes: `popover` and `bottom-sheet` with configurable placement (`top`, `bottom`, `left`, `right`)
+- Single and multiple selection via `Menu.Group` with `selectedKeys`/`onSelectionChange`
+- Item press animations (scale + background color) via Reanimated with full customization through the `animation` prop
+- Item variants: `default` and `danger`
+- Indicator variants: `checkmark`, `dot`, and custom content
+- `Menu.Label` for section headings
+- `shouldCloseOnSelect` control per group
+
+**Usage:**
+
+```tsx
+import { Menu } from "heroui-native";
+
+export function BasicMenu() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Open Menu</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Edit</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.ItemTitle>Duplicate</Menu.ItemTitle>
+          </Menu.Item>
+          <Menu.Item variant="danger">
+            <Menu.ItemTitle>Delete</Menu.ItemTitle>
+          </Menu.Item>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+
+export function MenuWithSections() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Actions</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Group selectionMode="single" selectedKeys={selected} onSelectionChange={setSelected}>
+            <Menu.Label>View</Menu.Label>
+            <Menu.Item id="list">
+              <Menu.ItemTitle>List View</Menu.ItemTitle>
+              <Menu.ItemIndicator />
+            </Menu.Item>
+            <Menu.Item id="grid">
+              <Menu.ItemTitle>Grid View</Menu.ItemTitle>
+              <Menu.ItemIndicator />
+            </Menu.Item>
+          </Menu.Group>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+For complete documentation and examples, see the [Menu component page](/docs/native/components/menu).
+
+**Related PR:** [#312](https://github.com/heroui-inc/heroui-native/pull/312)
+
+#### InputGroup
+
+The InputGroup component provides a decorated text input with absolutely-positioned `Prefix` and `Suffix` sub-components that automatically measure their widths via `onLayout` and apply matching padding to the Input. It features a convenient `isDecorative` prop that handles accessibility and pointer-event boilerplate for decorative addons in a single boolean, and a root `isDisabled` prop that cascades disabled state to all children via context.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="input-group"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/input-group-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `InputGroup.Prefix`, `InputGroup.Suffix`, `InputGroup.Input`
+- Auto-padding: Prefix/Suffix widths are measured via `onLayout` and automatically applied as `paddingLeft`/`paddingRight` on the Input
+- `isDecorative` prop on Prefix/Suffix handles `pointerEvents="none"`, `accessibilityElementsHidden`, and `importantForAccessibility` in a single boolean
+- Root `isDisabled` cascades to all children via context (Prefix/Suffix opacity + pointer-events, Input editability)
+- `InputGroup.Input` is a direct pass-through — consumers manage `value`/`onChangeText` directly on the Input
+
+**Usage:**
+
+```tsx
+import { InputGroup } from "heroui-native";
+
+export function SearchInput() {
+  return (
+    <InputGroup>
+      <InputGroup.Prefix isDecorative>
+        <SearchIcon />
+      </InputGroup.Prefix>
+      <InputGroup.Input placeholder="Search..." />
+      <InputGroup.Suffix isDecorative>
+        <ChevronIcon />
+      </InputGroup.Suffix>
+    </InputGroup>
+  );
+}
+
+export function DisabledInput() {
+  return (
+    <InputGroup isDisabled>
+      <InputGroup.Prefix isDecorative>
+        <LockIcon />
+      </InputGroup.Prefix>
+      <InputGroup.Input placeholder="Disabled input" />
+    </InputGroup>
+  );
+}
+```
+
+For complete documentation and examples, see the [InputGroup component page](/docs/native/components/input-group).
+
+**Related PR:** [#313](https://github.com/heroui-inc/heroui-native/pull/313)
+
+## Component Improvements
+
+### Bottom Sheet Android Back Press Support
+
+The [Bottom Sheet](/docs/native/components/bottom-sheet) shared container now handles the Android hardware back button, dismissing any open bottom sheet when pressed. The `BackHandler` listener is only active while the sheet is open, preventing closed instances from consuming the event. This fix applies globally to all bottom-sheet-based components.
+
+**Supported components:**
+
+- [Bottom Sheet](/docs/native/components/bottom-sheet)
+- [Popover](/docs/native/components/popover)
+- [Select](/docs/native/components/select)
+
+The fix uses React Native's `BackHandler` API which is a no-op on iOS, so no platform-specific handling is needed.
+
+**Related PR:** [#308](https://github.com/heroui-inc/heroui-native/pull/308)
+
+### Slot `combineStyles` Fix
+
+The Slot primitive's `combineStyles` function now returns style arrays instead of using `StyleSheet.flatten`, which was destroying Reanimated `SharedValue` and `useAnimatedStyle` bindings by deep-copying style objects into plain objects.
+
+**Improvements:**
+
+- `combineStyles` preserves Reanimated animated style bindings by returning arrays
+- React Native handles nested style arrays natively, so consumer behavior is unchanged
+- Fixes animation breakages across components that compose via the Slot primitive
+
+**Related PR:** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## Dependencies
+
+### Expo 55 Compatibility
+
+Dependency versions have been updated for Expo SDK 55 compatibility:
+
+- `uniwind`: 1.2.7 → 1.3.2
+- `@gorhom/bottom-sheet`: ^5 → ^5.2.8
+
+The `combineStyles` fix described above is the primary code change enabling Expo 55 support, as the previous `StyleSheet.flatten` approach broke Reanimated style bindings in the new SDK.
+
+**Related PR:** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**: Resolved `FullWindowOverlay` interfering with the React Native element inspector.
+
+- **[Issue #280](https://github.com/heroui-inc/heroui-native/issues/280)**: Fixed Avatar component and other Reanimated-dependent components breaking under Expo 55. The `combineStyles` function was destroying Reanimated animated style bindings via `StyleSheet.flatten`; it now returns style arrays to preserve `SharedValue` and `useAnimatedStyle` bindings.
+
+**Related PRs:**
+
+- [#308](https://github.com/heroui-inc/heroui-native/pull/308)
+- [#314](https://github.com/heroui-inc/heroui-native/pull/314)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [TagGroup](/docs/native/components/tag-group) - New component documentation with usage examples and API reference
+- [Menu](/docs/native/components/menu) - New component documentation with usage examples and API reference
+- [InputGroup](/docs/native/components/input-group) - New component documentation with usage examples and API reference
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/rc-4.mdx b/apps/docs/content/docs/en/native/releases/rc-4.mdx
new file mode 100644
index 0000000..9ce69e7
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/rc-4.mdx
@@ -0,0 +1,199 @@
+---
+title: RC 4
+description: SubMenu component, Slider Output composition, PressableFeedback ripple fix, Bottom Sheet back handler fix
+github:
+  pull: 331
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">March 6, 2026</span>
+</div>
+
+RC 4 introduces the SubMenu compound component for nested expandable menus with spring-animated expand/collapse, refactors Slider Output with slot-based styling and `textProps` forwarding, and adds `disallowEmptySelection` to Menu.Group for radio-group behavior. This release also resolves the PressableFeedback ripple blink on rapid presses with a dual-layer buffer system, fixes the Bottom Sheet Android back handler to respect `enablePanDownToClose`.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### SubMenu Component
+
+The [Menu](/docs/native/components/menu) component now supports nested expandable sub-menus via the new `SubMenu` compound component. SubMenu nests inside `Menu.Content` and reveals additional items on press with spring-based expand/collapse animations and indicator rotation.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="menu"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/menu-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-components: `SubMenu`, `SubMenu.Trigger`, `SubMenu.TriggerIndicator`, `SubMenu.Content`
+- Spring-based expand/collapse animation with indicator rotation
+- Headless primitive layer with context, controlled/uncontrolled open state, and accessibility attributes (`role`, `aria-expanded`, `aria-disabled`)
+- Parent menu coordination: popover scales to 0.98, shadow is removed, and non-SubMenu items fade to 40% opacity with `pointer-events-none` when a SubMenu is open
+- Menu content switches to `FadeOut` exit animation when a SubMenu is open to avoid conflicting scale animations
+- `useSubMenu` hook for advanced use cases
+
+**Usage:**
+
+```tsx
+import { Menu, SubMenu } from "heroui-native";
+
+export function MenuWithSubMenu() {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <Button>Open Menu</Button>
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Overlay />
+        <Menu.Content>
+          <Menu.Item>
+            <Menu.ItemTitle>Edit</Menu.ItemTitle>
+          </Menu.Item>
+          <SubMenu>
+            <SubMenu.Trigger>
+              <Menu.ItemTitle>More Options</Menu.ItemTitle>
+              <SubMenu.TriggerIndicator />
+            </SubMenu.Trigger>
+            <SubMenu.Content>
+              <Menu.Item>
+                <Menu.ItemTitle>Import</Menu.ItemTitle>
+              </Menu.Item>
+              <Menu.Item>
+                <Menu.ItemTitle>Export</Menu.ItemTitle>
+              </Menu.Item>
+            </SubMenu.Content>
+          </SubMenu>
+        </Menu.Content>
+      </Menu.Portal>
+    </Menu>
+  );
+}
+```
+
+For complete documentation and examples, see the [Menu component page](/docs/native/components/menu).
+
+**Related PR:** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
+
+## Component Improvements
+
+### Slider Output Composition Refactor
+
+The [Slider](/docs/native/components/slider) Output component has been refactored to use a proper slot-based architecture with `container` and `text` slots, and introduces `textProps` for forwarding props to the inner text element.
+
+**Improvements:**
+
+- Slot-based styling: `output` class split into `container` and `text` slots with a new `classNames` prop (`classNames={{ container, text }}`) for granular style targeting
+- Composition fix: `HeroText` now only renders for default content; custom children render directly without an extra text wrapper
+- New `textProps` prop on `Slider.Output` for forwarding arbitrary props (e.g., `maxFontSizeMultiplier`) to the inner text element
+- `OutputSlots` type exported from the styles module for external consumption
+
+**Related PR:** [#328](https://github.com/heroui-inc/heroui-native/pull/328)
+
+### Menu.Group `disallowEmptySelection`
+
+The [Menu](/docs/native/components/menu) `Menu.Group` component now supports a `disallowEmptySelection` prop that prevents deselecting the last item in `single` selection mode, enabling radio-group behavior.
+
+**Usage:**
+
+```tsx
+<Menu.Group
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+  disallowEmptySelection
+>
+  <Menu.Item id="list">
+    <Menu.ItemTitle>List View</Menu.ItemTitle>
+    <Menu.ItemIndicator />
+  </Menu.Item>
+  <Menu.Item id="grid">
+    <Menu.ItemTitle>Grid View</Menu.ItemTitle>
+    <Menu.ItemIndicator />
+  </Menu.Item>
+</Menu.Group>
+```
+
+**Related PR:** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
+
+### Bottom Sheet `enablePanDownToClose` Consistency
+
+The [Bottom Sheet](/docs/native/components/bottom-sheet) component now correctly respects the `enablePanDownToClose` prop for Android hardware back button behavior. Previously, the back button would close the sheet even when `enablePanDownToClose` was set to `false`.
+
+**Improvements:**
+
+- The `enablePanDownToClose` prop is threaded through to `BottomSheetContentContainer` (defaults to `true`)
+- The `BackHandler` event listener is only registered when both `isOpen` and `enablePanDownToClose` are `true`
+- Bottom sheets with `enablePanDownToClose={false}` are no longer dismissible via the Android back button
+
+**Related PR:** [#327](https://github.com/heroui-inc/heroui-native/pull/327)
+
+## ⚠️ Breaking Changes
+
+### Chip Component Sizing
+
+The [Chip](/docs/native/components/chip) component's size variants have been migrated from fixed heights to padding-based sizing to accommodate dynamic text scaling at larger accessibility font sizes.
+
+**Migration:**
+
+Custom styles relying on the previous `h-5`/`h-6`/`h-7` chip heights should be updated to use the new padding-based approach:
+
+```tsx
+// Before — Fixed height sizing
+// Chip used h-5 (sm), h-6 (md), h-7 (lg)
+
+// After — Padding-based sizing
+// Chip uses py-0.5 (sm), py-[3px] (md), py-1 (lg)
+// Border radius updated: rounded-xl → rounded-2xl/rounded-3xl
+```
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Menu](/docs/native/components/menu) - SubMenu component documentation with anatomy, usage examples, full API reference, and `useSubMenu` hook docs
+- [Slider](/docs/native/components/slider) - Updated Output component documentation with slot-based styling and `textProps`
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-0.mdx b/apps/docs/content/docs/en/native/releases/v1-0-0.mdx
new file mode 100644
index 0000000..92b98a4
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-0.mdx
@@ -0,0 +1,206 @@
+---
+title: v1.0.0
+description: LinkButton component, sub-menu conflict resolution, optional @gorhom/bottom-sheet, ThemeColorValue branded type
+github:
+  pull: 347
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">March 19, 2026</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  height={430}
+  muted
+/>
+
+🎉 HeroUI Native reaches v1.0.0 — the first stable release, marking the library's graduation from beta and release candidate stages into a production-ready foundation for React Native apps. Alongside this milestone, the release includes the new LinkButton component, sub-menu conflict resolution, an optional `@gorhom/bottom-sheet` peer dependency, and improved type safety for `useThemeColor`.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### LinkButton Component
+
+The new [LinkButton](/docs/native/components/button) compound component renders a ghost-variant button with no highlight feedback, designed for inline link-style interactions such as "Terms of Service" or "Privacy Policy" links. It delegates entirely to the existing Button infrastructure while enforcing ghost variant and disabled highlight internally.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="link-button"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/link-button-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Compound sub-component: `LinkButton.Label` for styled text content
+- Ghost variant enforced internally — no `variant` prop exposed
+- Highlight feedback disabled by default via `resolveAnimationObject`
+- `h-auto p-0` base class removes default button height and padding for inline use
+- Consumer animation config merged while preserving `highlight: false`
+
+**Usage:**
+
+```tsx
+import { LinkButton } from "heroui-native";
+
+export function TermsLink() {
+  return (
+    <LinkButton onPress={() => openURL("https://example.com/terms")}>
+      <LinkButton.Label>Terms of Service</LinkButton.Label>
+    </LinkButton>
+  );
+}
+```
+
+**Related PR:** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
+
+## Component Improvements
+
+### Sub-Menu Single-Open Enforcement and Backdrop Close
+
+The [Menu](/docs/native/components/menu) sub-menu system has been refactored to track the active sub-menu by ID instead of a simple boolean, enforcing single-open behavior across sibling sub-menus. A backdrop pressable overlay now renders over the menu content area when a sub-menu is open, allowing users to dismiss it by tapping outside.
+
+**Improvements:**
+
+- `openSubMenuId` replaces the boolean flag — only one sub-menu can be active at a time; opening a new one automatically closes the previous
+- A `Pressable` overlay renders over the menu content when a sub-menu is open, allowing tap-to-dismiss
+- Non-active sub-menu triggers receive `opacity-40` and `pointer-events-none` via the new `isOtherSubMenuOpen` style variant
+- Open sub-menu content uses `z-50`; closed uses `z-40` to avoid stacking issues
+- New "Two Sub Menus" example added to the demo app showcasing multiple sub-menus in a single menu
+
+**Related PR:** [#343](https://github.com/heroui-inc/heroui-native/pull/343)
+
+### Button Label Ref Type Fix
+
+The `ButtonLabel` ref type has been corrected from `View` to `TextRef`, and an unused `View` import has been removed from `button.tsx`. This fix aligns the ref type with the actual rendered element.
+
+**Related PR:** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
+
+## API Enhancements
+
+### `ThemeColorValue` Branded Type for `useThemeColor`
+
+The `useThemeColor` hook now returns a `ThemeColorValue` branded type for single-color calls, making misuse of array destructuring immediately visible as a `never` type in the IDE. The non-null assertion operator (`!`) has also been replaced with a safe nullish coalescing fallback.
+
+**New behavior:**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+// Correct — direct assignment
+const mutedColor = useThemeColor("muted");
+
+// Incorrect — IDE immediately surfaces `never` type
+const [color] = useThemeColor("muted"); // color: never
+```
+
+`ThemeColorValue` extends `string`, so it is assignable everywhere a `string` is expected. Existing call sites are unaffected at runtime. The `_colorValueBrand` symbol is declared with `declare const` so it has zero runtime footprint.
+
+**Related PR:** [#337](https://github.com/heroui-inc/heroui-native/pull/337)
+
+### `useBottomSheetAwareHandlers` Public Hook
+
+The `useBottomSheetAwareHandlers` hook is now exported as a public API, giving consumers explicit control over keyboard avoidance wiring inside bottom sheets. This replaces the implicit `isBottomSheetAware` prop that was previously available on `Input` and `InputOTP`.
+
+**Usage:**
+
+```tsx
+import { useBottomSheetAwareHandlers, Input } from "heroui-native";
+
+export function BottomSheetInput() {
+  const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+
+  return <Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />;
+}
+```
+
+**Related PR:** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+
+## ⚠️ Breaking Changes
+
+### `Input` and `InputOTP` Inside Bottom Sheet
+
+The `isBottomSheetAware` prop has been removed from `Input` and `InputOTP`. Previously, keyboard avoidance inside bottom sheets was handled automatically under the hood. Now you must explicitly use the `useBottomSheetAwareHandlers` hook and pass the handlers yourself. This change keeps the Input component lighter by removing the implicit `@gorhom/bottom-sheet` import, allowing the package to be an optional peer dependency for projects that don't use bottom sheet features.
+
+**Migration:**
+
+```tsx
+// Before
+<Input isBottomSheetAware placeholder="Type here..." />
+
+// After
+import { useBottomSheetAwareHandlers } from "heroui-native";
+
+const { onFocus, onBlur } = useBottomSheetAwareHandlers();
+<Input onFocus={onFocus} onBlur={onBlur} placeholder="Type here..." />
+```
+
+This applies to any `Input` or `InputOTP` rendered inside a `BottomSheet`. Components used outside of bottom sheets are unaffected.
+
+**Related PR:** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #330](https://github.com/heroui-inc/heroui-native/issues/330)**: Resolved `Input` unconditionally importing `@gorhom/bottom-sheet` at the module level even when `isBottomSheetAware` was `false`. The package is now loaded lazily via an optional `try/catch` wrapper, so projects that don't use bottom sheet features no longer need it installed.
+
+- **[Issue #340](https://github.com/heroui-inc/heroui-native/issues/340)**: Fixed sub-menu content appearing behind sibling sub-menu triggers. The sub-menu system now tracks the active sub-menu by ID, enforces single-open behavior, and applies correct z-index layering (`z-50` for open, `z-40` for closed).
+
+**Related PRs:**
+
+- [#347](https://github.com/heroui-inc/heroui-native/pull/347)
+- [#343](https://github.com/heroui-inc/heroui-native/pull/343)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [LinkButton](/docs/native/components/link-button) - LinkButton compound component documentation with anatomy, usage examples, and API reference
+- [Menu](/docs/native/components/menu) - Updated sub-menu documentation with single-open enforcement and backdrop close behavior
+- [Input](/docs/native/components/input) - Updated bottom sheet usage examples with `useBottomSheetAwareHandlers` hook pattern
+- [InputOTP](/docs/native/components/input-otp) - Updated bottom sheet usage examples with `useBottomSheetAwareHandlers` hook pattern
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-1.mdx b/apps/docs/content/docs/en/native/releases/v1-0-1.mdx
new file mode 100644
index 0000000..96cfb0a
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-1.mdx
@@ -0,0 +1,119 @@
+---
+title: v1.0.1
+description: Toast race condition fix, disabled state styling with disabled modifier, backdrop style variable
+github:
+  pull: 360
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">April 1, 2026</span>
+</div>
+
+HeroUI Native v1.0.1 is a patch release focused on reliability and developer experience. It resolves a race condition in the Toast provider that caused stale animation values, corrects disabled-state styling across seven components to use the native `disabled:` modifier, and introduces a new `--backdrop` theme variable for overlay components.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## API Enhancements
+
+### `--backdrop` Theme Variable
+
+A new `--backdrop` top-level style variable has been added to the theme system, providing a dedicated color token for the dimming layer behind overlay components such as Dialog and Bottom Sheet. The default value is `oklch(0% 0 0 / 20%)` for a subtle but visible backdrop effect.
+
+**New capability:**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+// Dialog and Bottom Sheet overlays now use bg-backdrop automatically
+<Dialog>
+  <Dialog.Content>
+    {/* Content renders over the themed backdrop */}
+  </Dialog.Content>
+</Dialog>
+```
+
+The `--backdrop` variable is included in all built-in themes for both light and dark modes, and the corresponding `bg-backdrop` Tailwind utility is available for use in custom component styles.
+
+**Related PR:** [#366](https://github.com/heroui-inc/heroui-native/pull/366)
+
+## Style Fixes
+
+### Disabled State Modifier
+
+Updated disabled-state styling across seven components to use the `disabled:` modifier prefix instead of applying styles unconditionally. This ensures disabled styles (`opacity-disabled`, `pointer-events-none`) are only applied when the component is in an actual disabled state, respecting the native `disabled` modifier from Uniwind.
+
+**Affected components:**
+
+- [Button](/docs/native/components/button)
+- [Checkbox](/docs/native/components/checkbox)
+- [Input](/docs/native/components/input)
+- [Menu](/docs/native/components/menu)
+- [Switch](/docs/native/components/switch)
+- [Tabs](/docs/native/components/tabs)
+- [TagGroup](/docs/native/components/tag-group)
+
+All `isDisabled` variant classes now use the `disabled:` modifier prefix (e.g., `disabled:opacity-disabled disabled:pointer-events-none`), ensuring proper scoping to the disabled pseudo-state and eliminating styling conflicts when the disabled state is toggled dynamically.
+
+**Related PR:** [#361](https://github.com/heroui-inc/heroui-native/pull/361)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #359](https://github.com/heroui-inc/heroui-native/issues/359)**: Fixed a race condition in the Toast provider where the `total` SharedValue could drift out of sync with the actual toast count. The manual increment/decrement approach was prone to stale-closure mismatches when `hide` and `show` ran in the same tick or when auto-dismiss raced with a manual hide. The `total` value is now derived from `toasts.length` via a `useEffect`, ensuring animated interpolations (opacity, scale, translateY) always reflect the real toast count.
+
+- **[Issue #356](https://github.com/heroui-inc/heroui-native/issues/356)**: Resolved disabled-state styles being applied unconditionally when `isDisabled` was true, preventing developers from theming or customizing the disabled appearance. All seven affected components now use the `disabled:` modifier prefix, correctly scoping styles to the disabled pseudo-state.
+
+**Related PRs:**
+
+- [#360](https://github.com/heroui-inc/heroui-native/pull/360)
+- [#361](https://github.com/heroui-inc/heroui-native/pull/361)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Colors](/docs/native/getting-started/colors) - Added the new `--backdrop` variable to the color reference
+- [Theming](/docs/native/getting-started/theming) - Updated theming guide with the new `--backdrop` variable documentation
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-2.mdx b/apps/docs/content/docs/en/native/releases/v1-0-2.mdx
new file mode 100644
index 0000000..d161860
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-2.mdx
@@ -0,0 +1,172 @@
+---
+title: v1.0.2
+description:
+  asChild slot pattern for PressableFeedback and Surface, Portal accessibility modal prop, Button Android variant fix, Input and Select style refinements
+github:
+  pull: 380
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">April 15, 2026</span>
+</div>
+
+HeroUI Native v1.0.2 introduces the `asChild` slot pattern for PressableFeedback and Surface components, adds VoiceOver modal containment support across all portal-based overlay components, and fixes an Android-specific Button variant styling issue. This release also refines Input and Select visual styles and improves RadioGroup documentation with inline API references.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## API Enhancements
+
+### `asChild` Slot Pattern for PressableFeedback and Surface
+
+The [PressableFeedback](/docs/native/components/pressable-feedback) and [Surface](/docs/native/components/surface) components now support the `asChild` prop, enabling the Slot pattern for polymorphic rendering. When `asChild` is `true`, each component merges its behavior and styling onto a single child element instead of wrapping it in an additional node.
+
+**PressableFeedback** uses `Animated.createAnimatedComponent(Slot.Pressable)` to merge press handling and animated styles onto the child element. **Surface** uses `Slot.View` to merge surface styling (elevation, background, className) onto the child element.
+
+**New capability:**
+
+```tsx
+import { PressableFeedback, Surface } from "heroui-native";
+
+// PressableFeedback merges press handling onto the child
+<PressableFeedback asChild onPress={() => console.log("pressed")}>
+  <MyCustomComponent />
+</PressableFeedback>
+
+// Surface merges surface styling onto the child
+<Surface asChild elevation={2}>
+  <MyCustomCard />
+</Surface>
+```
+
+The `asChild` prop defaults to `false`, preserving existing behavior. No migration is required. The child must be a single React element when `asChild` is enabled. Both implementations follow the established Slot primitive pattern already used in the codebase.
+
+**Related PR:** [#380](https://github.com/heroui-inc/heroui-native/pull/380)
+
+### `unstable_accessibilityContainerViewIsModal` for Portal Components
+
+A new `unstable_accessibilityContainerViewIsModal` prop has been added to all portal-based overlay components, giving consumers control over whether iOS VoiceOver treats the overlay window as a modal container. When enabled, VoiceOver focus is restricted to elements inside the overlay, preventing navigation to content behind it.
+
+**Supported components:**
+
+- [BottomSheet](/docs/native/components/bottom-sheet) (`BottomSheet.Portal`)
+- [Dialog](/docs/native/components/dialog) (`Dialog.Portal`)
+- [Menu](/docs/native/components/menu) (`Menu.Portal`)
+- [Popover](/docs/native/components/popover) (`Popover.Portal`)
+- [Select](/docs/native/components/select) (`Select.Portal`)
+- [Toast](/docs/native/components/toast) (`ToastProvider`)
+
+**New capability:**
+
+```tsx
+import { Dialog } from "heroui-native";
+
+<Dialog>
+  <Dialog.Portal unstable_accessibilityContainerViewIsModal>
+    <Dialog.Content>
+      {/* VoiceOver focus is restricted to this overlay on iOS */}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+The prop defaults to `false`, preserving existing behavior. It is marked `unstable` because it maps directly to the native `accessibilityViewIsModal` on `FullWindowOverlay` from `react-native-screens` and may change with future releases of that library.
+
+**Related PR:** [#383](https://github.com/heroui-inc/heroui-native/pull/383)
+
+## Style Fixes
+
+### Input and Select Visual Refinements
+
+Refined the visual styling of the [Input](/docs/native/components/input) and [Select](/docs/native/components/select) components for a cleaner, more balanced appearance.
+
+**Fixes:**
+
+- **Input**: Border width reduced from `border-2` (2px) to `border-[1.5px]` for a subtler, less heavy border appearance
+- **Select**: Trigger vertical padding reduced from `py-3.5` to `py-3` for tighter, more compact spacing
+
+These are purely cosmetic adjustments with no API or behavioral changes. Visual regression testing is recommended to confirm the updated styles render as expected across iOS and Android.
+
+**Related PR:** [#381](https://github.com/heroui-inc/heroui-native/pull/381)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #363](https://github.com/heroui-inc/heroui-native/issues/363)**: Fixed the Button outline variant on Android where the border would persist when switching to another variant via a conditional prop. React Native on Android sometimes retains the `borderWidth` property during variant transitions. All button variants except `outline` now include explicit `border-0` classes to ensure `borderWidth` is reset to `0` whenever the variant changes.
+
+- **[Issue #357](https://github.com/heroui-inc/heroui-native/issues/357)**: Resolved the request for `asChild` support on Card for pressable card patterns. The new `asChild` slot pattern on PressableFeedback and Surface enables developers to compose pressable card layouts by merging press handling and surface styling onto a single child element without additional wrapper nodes.
+
+**Related PRs:**
+
+- [#370](https://github.com/heroui-inc/heroui-native/pull/370)
+- [#380](https://github.com/heroui-inc/heroui-native/pull/380)
+
+## Documentation
+
+### RadioGroup Inline API Reference
+
+The [RadioGroup](/docs/native/components/radio-group) documentation now embeds full API reference tables for `Radio`, `Radio.Indicator`, and `Radio.IndicatorThumb` directly within the page. This removes the need for readers to navigate to a separate Radio doc file to understand the props available when composing radios inside a `RadioGroup.Item`.
+
+**Improvements:**
+
+- Full prop tables for `Radio`, `Radio.Indicator`, and `Radio.IndicatorThumb` embedded inline
+- Added documentation for `RadioRenderProps`, `RadioRootAnimation`, and `RadioIndicatorThumbAnimation` types
+- Replaced external markdown links with inline code formatting for consistency
+
+**Related PR:** [#384](https://github.com/heroui-inc/heroui-native/pull/384)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [RadioGroup](/docs/native/components/radio-group) - Inline API reference tables for Radio, Radio.Indicator, and Radio.IndicatorThumb
+- [PressableFeedback](/docs/native/components/pressable-feedback) - Added `asChild` prop documentation
+- [Surface](/docs/native/components/surface) - Added `asChild` prop documentation
+- [BottomSheet](/docs/native/components/bottom-sheet) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+- [Dialog](/docs/native/components/dialog) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+- [Menu](/docs/native/components/menu) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+- [Popover](/docs/native/components/popover) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+- [Select](/docs/native/components/select) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+- [Toast](/docs/native/components/toast) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-3.mdx b/apps/docs/content/docs/en/native/releases/v1-0-3.mdx
new file mode 100644
index 0000000..d3e0d7d
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-3.mdx
@@ -0,0 +1,233 @@
+---
+title: v1.0.3
+description:
+  New Text typography component, ScrollShadow inverted support, Tabs RTL indicator fix, optional Avatar alt prop, Select indicator unification, and form field style refinements
+github:
+  pull: 400
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">May 11, 2026</span>
+</div>
+
+HeroUI Native v1.0.3 introduces the new `Text` typography primitive with a compound API for headings, paragraphs, and inline code, while delivering important fixes for `ScrollShadow` with inverted lists, `Tabs` indicator alignment in RTL layouts, and `Select.TriggerIndicator` animation when using custom children. This release also refines visual styles across `Button`, `Chip`, and `Input`, makes the `Avatar` `alt` prop optional, and corrects inner padding behavior for `TextField` and `SearchField`.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### New Components
+
+This release introduces **1 new** typography component:
+
+- **[Text](/docs/native/components/text)**: Primitive typography component with semantic `type` variants and `Heading`, `Paragraph`, and `Code` sub-components. ([Documentation](/docs/native/components/text))
+
+#### Text
+
+The `Text` component is a typography primitive that renders styled text via semantic presets. It exposes a compound API with `Text.Heading`, `Text.Paragraph`, and `Text.Code` sub-components, and layers orthogonal `align`, `color`, `weight`, and `truncate` props on top of `tailwind-variants` so typography can be composed without bespoke styles on every call site.
+
+<NativeVideoPlayerView
+  target="component"
+  slug="text"
+  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-light.mp4"
+  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/text-docs-dark.mp4"
+/>
+
+**Features:**
+
+- Semantic `type` variants: `h1`–`h6`, `body`, `body-sm`, `body-xs`, and `code`
+- `Text.Heading` automatically sets `accessibilityRole="header"` and narrows `type` to heading levels
+- `Text.Paragraph` narrows `type` to body variants for readable copy
+- `Text.Code` renders chip-styled, inline monospaced text with a platform-appropriate `fontFamily` (Menlo on iOS, `monospace` elsewhere)
+- RTL-aware `align` prop with `start`, `center`, `end`, and `justify` (iOS-only justification)
+- Semantic `color` presets (`default`, `muted`) with `className` escape hatch for other theme colors
+- `weight` override that wins over `type`'s implied weight via `tailwind-merge`
+- `truncate` boolean shortcut for `numberOfLines={1}`; an explicit `numberOfLines` always takes precedence
+
+**Usage:**
+
+```tsx
+import { Text } from "heroui-native";
+import { View } from "react-native";
+
+export function Example() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Text.Heading type="h1">Welcome</Text.Heading>
+      <Text.Heading type="h3">Getting Started</Text.Heading>
+      <Text.Paragraph>
+        This is a body paragraph rendered with the Text component.
+      </Text.Paragraph>
+      <Text.Paragraph color="muted" type="body-sm">
+        Smaller supporting text for captions or footnotes.
+      </Text.Paragraph>
+      <Text.Code>npm install heroui-native</Text.Code>
+    </View>
+  );
+}
+```
+
+For complete documentation and examples, see the [Text component page](/docs/native/components/text).
+
+**Related PR:** [#400](https://github.com/heroui-inc/heroui-native/pull/400)
+
+## Component Improvements
+
+### ScrollShadow Inverted Child Support
+
+The [ScrollShadow](/docs/native/components/scroll-shadow) component now correctly handles inverted scrollable children such as `<FlatList inverted>` or `<FlashList inverted>`.
+
+**Improvements:**
+
+- `ScrollShadowRoot` now reads the `inverted` prop from its scrollable child, mirroring the existing `childHorizontal` auto-detection pattern
+- Swaps which animated style drives each visual edge so shadows render at the correct side
+- No public API changes — the fix activates only when the child has `inverted={true}`, which previously rendered the gradients on the wrong edges
+
+Previously, wrapping an inverted list would render the gradient shadow on the top edge while scrollable content was below, and omit the bottom shadow even when more content was available. Indicators now point in the correct visual direction for inverted feeds, chat lists, and similar reverse-ordered scroll surfaces.
+
+**Related PR:** [#398](https://github.com/heroui-inc/heroui-native/pull/398)
+
+### Tabs RTL Indicator Alignment
+
+The [Tabs](/docs/native/components/tabs) component's indicator now positions correctly when React Native is running in RTL mode.
+
+**Improvements:**
+
+- Tab strip width is now tracked through the tabs measurements context
+- `Tabs.List` layout width is used for fixed tab layouts
+- `Tabs.ScrollView` content width is used for scrollable tab layouts
+- The indicator's `translateX` is mirrored only when `I18nManager.isRTL` is enabled
+
+The indicator uses an absolute `left` anchor combined with a measured `translateX`. In RTL, React Native swaps the absolute anchor automatically, but the measured transform still needed to be mirrored — this is now handled internally. Both fixed and scrollable tab lists are fixed, and the public API is unchanged.
+
+**Related PR:** [#396](https://github.com/heroui-inc/heroui-native/pull/396)
+
+### Select Trigger Indicator Unified Rendering
+
+The [Select](/docs/native/components/select) component's `Select.TriggerIndicator` now applies the open/close rotation animation consistently, regardless of whether the default icon or custom `children` are rendered.
+
+**Improvements:**
+
+- Custom `children` now receive the same animated container style as the default icon
+- `ChevronDownIcon` is rendered as a fallback via `children ?? <ChevronDownIcon />`
+- Collapsed the previously separate render branches into a single, unified render path
+
+Previously, passing custom `children` to `Select.TriggerIndicator` bypassed the animated rotation transform, leaving the indicator static on open/close. The unified branch ensures the rotation animation always plays without changing the public API.
+
+**Related PR:** [#409](https://github.com/heroui-inc/heroui-native/pull/409)
+
+## API Enhancements
+
+### Optional `alt` Prop on Avatar
+
+The [Avatar](/docs/native/components/avatar) component's `alt` prop is now optional and defaults to `'Avatar'`, reducing boilerplate for decorative or contextually obvious avatars while preserving accessibility support.
+
+**New Capability:**
+
+```tsx
+import { Avatar } from "heroui-native";
+
+<Avatar>
+  <Avatar.Image source={{ uri: "https://example.com/avatar.jpg" }} />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>;
+```
+
+Existing code that passes an explicit `alt` continues to work unchanged — the prop simply gains a sensible default when omitted. The `RootProps` type now reflects `alt?: string` with a JSDoc `@default 'Avatar'`, and the component documentation has been updated to match.
+
+**Related PR:** [#404](https://github.com/heroui-inc/heroui-native/pull/404)
+
+## Style Fixes
+
+### Button, Chip, and Input Style Refinements
+
+Refined sizing and color styling across [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Input](/docs/native/components/input) to standardize on Tailwind utility classes and semantic soft color tokens.
+
+**Fixes:**
+
+- **Button**: Sizes now use Tailwind height utilities (`h-10`, `h-12`, `h-14`) instead of arbitrary pixel values; the `sm` height is adjusted from 36px to 40px for better tap-target ergonomics
+- **Chip**: Vertical padding for `md`/`lg` refined (`py-[3px]` → `py-1`, `py-1` → `py-1.5`) for more balanced spacing
+- **Chip**: Soft variants now use semantic `bg-{color}-soft` tokens instead of opacity-based `bg-{color}/15` backgrounds
+- **Input**: Switched from `py-3.5` to `min-h-12` so the field maintains consistent height regardless of content
+- **Input**: Primary variant border now correctly uses the `border-field-border` token instead of `border-field`
+
+Minor pixel-level differences in Button `sm` size (+4px) and Chip `md`/`lg` paddings should be reviewed visually. No API changes were made — only style tokens in `button.styles.ts`, `chip.styles.ts`, and `input.styles.ts` were updated.
+
+**Related PR:** [#406](https://github.com/heroui-inc/heroui-native/pull/406)
+
+### TextField and SearchField Inner Padding Fix
+
+The [TextField](/docs/native/components/text-field) and [SearchField](/docs/native/components/search-field) components no longer apply extra horizontal padding to nested `Label`, `Description`, and `FieldError` components.
+
+**Fixes:**
+
+- `TextField` now provides `hasFieldPadding: false` to its `FormFieldContext`
+- `SearchField` now provides `hasFieldPadding: false` to its `FormFieldContext`
+- `Label`, `Description`, and `FieldError` rendered inside these fields no longer pick up the extra `px-1.5` side padding
+- Visual alignment is now consistent across all form field containers (`ControlField`, `RadioGroup`, `TagGroup` already used `hasFieldPadding: false`)
+
+The change is isolated to two `useMemo` values that provide `FormFieldContext`. Consumers that previously relied on the unintended inner padding can restore the spacing by adding `className="px-1.5"` to the affected child components.
+
+**Related PR:** [#407](https://github.com/heroui-inc/heroui-native/pull/407)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #334](https://github.com/heroui-inc/heroui-native/issues/334)**: Resolved `Tabs.Indicator` mispositioning in RTL layouts. The indicator combines an absolute `left` anchor with a measured `translateX`; React Native swaps the anchor automatically in RTL but the transform still needed to be mirrored. The tabs measurements context now tracks the tab strip width and mirrors `translateX` only when `I18nManager.isRTL` is enabled, fixing both fixed and scrollable tab lists.
+- **[Issue #393](https://github.com/heroui-inc/heroui-native/issues/393)**: Fixed `ScrollShadow` ignoring its child's `inverted` prop. `ScrollShadowRoot` now reads `inverted` from the scrollable child (mirroring the existing `childHorizontal` auto-detection) and swaps which animated style drives each visual edge so the gradients render on the correct sides for inverted feeds and chat-style lists.
+
+**Related PRs:**
+
+- [#396](https://github.com/heroui-inc/heroui-native/pull/396)
+- [#398](https://github.com/heroui-inc/heroui-native/pull/398)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Text](/docs/native/components/text) - New component documentation, anatomy, usage, and full API reference
+- [Avatar](/docs/native/components/avatar) - `alt` prop documented as optional with default `'Avatar'`
+- [All Components](/docs/native/components) - Added the new Typography category alongside the existing categories
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-4.mdx b/apps/docs/content/docs/en/native/releases/v1-0-4.mdx
new file mode 100644
index 0000000..8abf75e
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-4.mdx
@@ -0,0 +1,286 @@
+---
+title: v1.0.4
+description:
+  Typography component renames Text, refined soft-foreground theme tokens with optional vibrant palette, iOS native modal offset guidance, Expo 56 / React Native 0.85 example upgrade
+github:
+  pull: 420
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">May 26, 2026</span>
+</div>
+
+HeroUI Native v1.0.4 renames the `Text` typography primitive to `Typography` to free up React Native's `Text` name and align with semantic typography usage, while keeping the existing `Text` exports as deprecated aliases for a seamless upgrade. This release also refines soft-foreground color tokens across Alert, Avatar, Button, Chip, and Toast for better contrast on soft backgrounds, ships a new optional `heroui-native/styles/vibrant` palette, documents the iOS native-modal offset workaround for Menu, Popover, and Select, and upgrades the example app to Expo 56 / React Native 0.85.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## What's New
+
+### Typography Component (Renamed from `Text`)
+
+The library's typography primitive has been renamed from `Text` to `Typography` to avoid clashing with React Native's built-in `Text` and to better describe its purpose as a semantic typography system. The component's API, variants, and behavior are unchanged — only the public name moves.
+
+```tsx
+import { Typography } from "heroui-native";
+import { View } from "react-native";
+
+export function Example() {
+  return (
+    <View className="flex-1 justify-center px-5 gap-4">
+      <Typography.Heading type="h1">Welcome</Typography.Heading>
+      <Typography.Heading type="h3">Getting Started</Typography.Heading>
+      <Typography.Paragraph>
+        This is a body paragraph rendered with the Typography component.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" type="body-sm">
+        Smaller supporting text for captions or footnotes.
+      </Typography.Paragraph>
+      <Typography.Code>npm install heroui-native</Typography.Code>
+    </View>
+  );
+}
+```
+
+**What changed:**
+
+- Primary export is now `Typography`, with sub-components `Typography.Heading`, `Typography.Paragraph`, and `Typography.Code`
+- New `typographyClassNames` style API and `Typography*` type aliases replace the prior `Text*` naming
+- The existing `Text`, `textClassNames`, and `Text*` types are kept as **deprecated** re-exports for backward compatibility
+- Example screen renamed from `text` to `typography` in the component catalog
+- JSDoc and component docs updated to reference Typography and the new docs URL
+
+<Callout type="info">
+  **No migration required.** Existing `import { Text } from "heroui-native"` continues to work via deprecated re-exports. Migrate to `Typography` at your convenience before a future major release removes the deprecated aliases.
+</Callout>
+
+**Related PR:** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
+
+### Vibrant Theme Palette (Optional)
+
+A new optional `heroui-native/styles/vibrant` stylesheet is available for apps that prefer more saturated brand colors on soft variants. It keeps the readability improvements from the refined soft-foreground tokens while preserving high color saturation for icons and text on soft backgrounds.
+
+**Usage:**
+
+```ts
+// Default refined soft-foreground palette
+import "heroui-native/styles";
+
+// Or, opt into the vibrant palette
+import "heroui-native/styles";
+import "heroui-native/styles/vibrant";
+```
+
+Import `heroui-native/styles/vibrant` after the base styles to override soft-foreground tokens with the more saturated values. No component code changes are required to opt in.
+
+**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+## Component Improvements
+
+### Refined Soft-Foreground Colors Across Components
+
+The [Alert](/docs/native/components/alert), [Avatar](/docs/native/components/avatar), [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Toast](/docs/native/components/toast) components now use the new `*-soft-foreground` theme tokens for labels and icons on soft backgrounds, producing better contrast and a more cohesive look across light and dark themes.
+
+**Improvements:**
+
+- Soft foreground tokens (`accent-soft-foreground`, `success-soft-foreground`, `warning-soft-foreground`, `danger-soft-foreground`, `default-soft-foreground`) are computed via `color-mix` in `theme.css` for improved readability on soft backgrounds
+- Alert, Avatar, Button, Chip, and Toast styles (and their internal hooks) consume the new soft-foreground tokens instead of raw semantic colors like `text-accent` or `text-success`
+- A new optional `heroui-native/styles/vibrant` export preserves saturated brand colors on soft variants for apps that want a more vivid look
+- Example app demos for Alert, Avatar, Button, Chip, and Toast were updated to match the refined color usage
+
+Component props and public APIs are unchanged — only the color values applied to soft variants. Apps relying on the default theme will see softer, more legible icon and label colors on soft variants out of the box.
+
+**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+### TextArea Vertical Padding Fix
+
+The [TextArea](/docs/native/components/text-area) component now applies proper inner vertical padding so multiline content no longer hugs the top edge of the field.
+
+**Improvements:**
+
+- `TextArea` now uses `h-32 py-2` for consistent inner spacing
+- No API changes — the fix is a styling-only update inside the component
+
+**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## API Enhancements
+
+### `useThemeColor` Token Updates
+
+The [`useThemeColor`](/docs/native/hooks/use-theme-color) hook now exposes additional surface and soft tokens, and renames the overlay backdrop token for clarity.
+
+**New Capability:**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+const colors = useThemeColor([
+  "default-soft",
+  "default-soft-foreground",
+  "surface-foreground",
+  "backdrop",
+]);
+```
+
+**Changes:**
+
+- Added `default-soft` and `default-soft-foreground` tokens
+- Added surface foreground tokens (e.g. `surface-foreground`) for explicit access to surface text colors
+- Renamed `overlay-backdrop` to `backdrop` for consistency with the underlying CSS variable name
+
+Apps using removed `useThemeColor` keys (`on-surface-*`) or the previous `overlay-backdrop` key should migrate to the updated token names. Component props and visual defaults are unchanged.
+
+**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
+
+## Dependencies
+
+### `@gorhom/bottom-sheet` Peer Range Updated
+
+The peer dependency range for `@gorhom/bottom-sheet` has been bumped from `^5.2.8` to `^5.2.9`. Apps that use HeroUI Native's [BottomSheet](/docs/native/components/bottom-sheet) component (or any of `Menu` / `Popover` / `Select` with `presentation="bottom-sheet"`) should ensure they are on a compatible version:
+
+```bash
+npm i @gorhom/bottom-sheet@^5.2.9
+```
+
+This is the only peer-dep change affecting consumers. The library's `react` (`>=19.0.0`) and `react-native` (`>=0.81.0`) peer ranges are unchanged.
+
+**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+### Example App Upgraded to Expo 56 / React Native 0.85
+
+The example app shipped in the repository has been upgraded to the latest Expo and React Native toolchain. This does not affect consumers of the library directly, but contributors running the example will benefit from the upgrades:
+
+- Expo `56`
+- React Native `0.85.3`
+- React `19.2.3`
+- React Native Reanimated `4.3.1`
+- `react-native-worklets` `0.8.3`
+- Uniwind `^1.6.3`
+
+Additional housekeeping included in this upgrade:
+
+- `metro.config.js` rewritten to pin peer-dep resolution to the example's `node_modules`, fixing Hermes "Maximum call stack size exceeded" crashes when `uniwind` or `react` resolved to two copies from the workspace root
+- Replaced deprecated `StyleSheet.absoluteFillObject` with `StyleSheet.absoluteFill` in input-otp and showcases
+- Migrated `useFocusEffect` / `useHeaderHeight` imports to `expo-router`
+- Removed unused `example/src/components/safe-area-view.tsx`, `eas.json`, and stale `newArchEnabled` / `edgeToEdgeEnabled` flags
+- Example app slug/bundle renamed to `heroui-native-oss`; Android `WithStateToggle` padding adjusted
+
+**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## Documentation
+
+### iOS Native Modal Offset Guidance for Menu, Popover, and Select
+
+The [Menu](/docs/native/components/menu), [Popover](/docs/native/components/popover), and [Select](/docs/native/components/select) documentation now includes a **Native Modal (iOS)** section that explains why overlay content can render shifted upward when a trigger lives inside a screen presented as a native modal (`presentation: "modal" | "formSheet" | "pageSheet"`), and how to compensate.
+
+**Improvements:**
+
+- Each component's docs now describe the Fabric / `FullWindowOverlay` coordinate mismatch: trigger coordinates are modal-relative while the overlay is window-anchored
+- Documents the recommended `offset={insets.top}` workaround using `useSafeAreaInsets` from `react-native-safe-area-context`
+- Links to the example app files (`popover-native-modal.tsx`, `select-native-modal.tsx`) for full usage patterns
+
+**Usage example:**
+
+```tsx
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Popover } from "heroui-native";
+
+const insets = useSafeAreaInsets();
+
+<Popover.Content presentation="popover" offset={insets.top + 20}>
+  {/* ... */}
+</Popover.Content>;
+```
+
+This is a documentation-only change — no API or runtime behavior was modified.
+
+**Related PR:** [#419](https://github.com/heroui-inc/heroui-native/pull/419)
+
+## Bug Fixes
+
+This release includes fixes for the following issues:
+
+- **[Issue #405](https://github.com/heroui-inc/heroui-native/issues/405)**: Documented the workaround for `Menu` rendering misaligned when opened inside a React Navigation native modal. The new **Native Modal (iOS)** section in the Menu docs explains the Fabric / `FullWindowOverlay` coordinate mismatch and shows how to compensate via `offset={insets.top}` with `useSafeAreaInsets`.
+- **[Issue #418](https://github.com/heroui-inc/heroui-native/issues/418)**: Resolved Hermes crashes ("Maximum call stack size exceeded") and the invisible `BottomSheet` content seen after upgrading the example app to Expo 56. The example's `metro.config.js` now pins peer-dep resolution (`react`, `react-native`, `uniwind`, etc.) to the example's local `node_modules`, preventing duplicate copies from being loaded from the workspace root.
+
+**Related PRs:**
+
+- [#419](https://github.com/heroui-inc/heroui-native/pull/419)
+- [#421](https://github.com/heroui-inc/heroui-native/pull/421)
+
+## Deprecations
+
+### `Text` Typography Exports
+
+The `Text` component and related exports are now **deprecated** in favor of `Typography`. Existing imports continue to work and will not produce runtime errors — only TypeScript / IDE deprecation hints are emitted. Plan to migrate before a future major release removes the deprecated aliases.
+
+**Deprecated → Recommended:**
+
+```tsx
+// Deprecated (still works)
+import { Text, textClassNames, type TextProps } from "heroui-native";
+
+<Text.Heading type="h1">Welcome</Text.Heading>;
+
+// Recommended
+import {
+  Typography,
+  typographyClassNames,
+  type TypographyProps,
+} from "heroui-native";
+
+<Typography.Heading type="h1">Welcome</Typography.Heading>;
+```
+
+**Related PR:** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Typography](/docs/native/components/typography) - Component renamed from Text; full API, anatomy, and usage reference updated
+- [Menu](/docs/native/components/menu) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
+- [Popover](/docs/native/components/popover) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
+- [Select](/docs/native/components/select) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
+- [Quick Start](/docs/native/getting-started/quick-start) - Updated `@gorhom/bottom-sheet` optional peer dependency to `^5.2.9`
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/native/releases/v1-0-5.mdx b/apps/docs/content/docs/en/native/releases/v1-0-5.mdx
new file mode 100644
index 0000000..243933e
--- /dev/null
+++ b/apps/docs/content/docs/en/native/releases/v1-0-5.mdx
@@ -0,0 +1,222 @@
+---
+title: v1.0.5
+description:
+  Split border-field token fixes width/color merge conflict, Typography Dynamic Type support, provider text input configuration, single-mount popover animations, Select icon color fix, Expo 57 / RN 0.86 upgrade
+github:
+  pull: 439
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">July 2, 2026</span>
+</div>
+
+HeroUI Native v1.0.5 resolves a long-standing `border-field` merge conflict by splitting the field border into separate width and color tokens and configuring `tailwind-variants` globally, migrating Input, InputOTP, Radio, and Checkbox to outline-based focus, active, and invalid states. This release also brings iOS Dynamic Type support to Typography, adds provider-level text input configuration, reworks Popover, Menu, and Select entering animations to mount content only once, aligns the Select check icon with the `accent-soft-foreground` token, and upgrades the toolchain to Expo 57 / React Native 0.86.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+<Tab value="npm">
+  ```bash
+  npm i heroui-native
+  ```
+</Tab>
+<Tab value="pnpm">
+  ``` bash
+  pnpm add heroui-native
+  ```
+</Tab>
+<Tab value="yarn">
+  ```bash
+  yarn add heroui-native
+  ```
+</Tab>
+<Tab value="bun">
+  ```bash
+  bun add heroui-native
+  ```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
+</Callout>
+
+## Try It on Your Device
+
+<NativeTryOnDevice />
+
+## Performance
+
+### Single-Mount Popover, Menu, and Select Animations
+
+The [Popover](/docs/native/components/popover), [Menu](/docs/native/components/menu), and [Select](/docs/native/components/select) content now mounts a single time and animates in via a shared value once it has been measured and positioned. Previously, the content subtree was mounted twice — a hidden probe to measure dimensions, then a visible node — so the entering Keyframe could fire on mount at the correct position.
+
+**Improvements:**
+
+- The default entering animation is driven by a shared value (`rEnteringStyle`) that plays once content is positioned (`isReady`), keeping the subtree mounted only once
+- `usePopupPopoverContentAnimation` now returns `isDrivenEntering` and `rEnteringStyle`, with translate, scale, and opacity interpolated from a progress value
+- Content is hidden from pointer events until it is ready; disabled animations resolve directly to the shown state
+- Custom entering Keyframes retain the previous probe-and-mount fallback path
+
+Public component APIs are unchanged — the single-mount path is entirely internal, and custom entering animations behave exactly as before. We recommend verifying enter and exit animations across all four placements, sub-menu transitions, and the disabled-animations case.
+
+**Related PR:** [#438](https://github.com/heroui-inc/heroui-native/pull/438)
+
+## Component Improvements
+
+### Typography Dynamic Type Support (iOS)
+
+The [Typography](/docs/native/components/text) component now applies a default `dynamicTypeRamp` per semantic type so text scales the way Apple intends on iOS. Larger types such as titles scale more slowly than body text, matching iOS system behavior for Dynamic Type. Previously, text in every Typography component scaled with the same factor.
+
+**Improvements:**
+
+- Each Typography type maps to an appropriate iOS Dynamic Type ramp (e.g. headings to `title` ramps, paragraphs to `body`)
+- Improves accessibility and text-scaling fidelity on iOS with no impact on Android
+- The `dynamicTypeRamp` default can be overridden per instance where a different ramp is desired
+
+This change is iOS-only and does not alter the Typography API. Apps that already pass `dynamicTypeRamp` directly continue to control scaling explicitly.
+
+**Related PR:** [#435](https://github.com/heroui-inc/heroui-native/pull/435)
+
+### Select Check Icon Color
+
+The [Select](/docs/native/components/select) component's `Select.ItemIndicator` now defaults its check icon color to the `accent-soft-foreground` theme token instead of `accent`, aligning the selected-item indicator with the intended semantic foreground color for better contrast and visual consistency.
+
+**Improvements:**
+
+- Default check icon color uses `accent-soft-foreground` for improved contrast in selected list items
+- JSDoc and component docs updated to reflect the new default
+
+Only the default icon color changes when `iconProps.color` is omitted — the API is unchanged and custom colors still work. Manual verification on light and dark themes is recommended to confirm indicator contrast.
+
+**Related PR:** [#436](https://github.com/heroui-inc/heroui-native/pull/436)
+
+## API Enhancements
+
+### Provider Text Input Configuration
+
+The [HeroUINativeProvider](/docs/native/getting-started/provider) (and `HeroUINativeProviderRaw`) can now configure a subset of `TextInput` props globally through a new `textInputProps` config, starting with `allowFontScaling` and `maxFontSizeMultiplier`. This mirrors the existing global `textProps` pattern and keeps input font-scaling behavior consistent across the app.
+
+**New Capability:**
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native";
+
+export function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textInputProps: {
+          allowFontScaling: true,
+          maxFontSizeMultiplier: 1.5,
+        },
+      }}
+    >
+      {/* Your app */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+**What's included:**
+
+- New `textInputProps` config on `HeroUINativeConfig` and `HeroUINativeConfigRaw` (`allowFontScaling`, `maxFontSizeMultiplier`)
+- New `TextInputComponentProvider` / `useTextInputComponent` and a `HeroTextInput` helper that applies global props as overridable defaults
+- Applied across `Input` (and therefore `TextArea`, `SearchField`, and `InputGroup`) and the `InputOTP` primitive
+
+Global props are applied as defaults, so any prop passed directly to a component still overrides them.
+
+**Related PR:** [#437](https://github.com/heroui-inc/heroui-native/pull/437)
+
+## Dependencies
+
+### Expo 57 / React Native 0.86 Upgrade
+
+The project has been upgraded to the Expo 57 / React Native 0.86 toolchain. This upgrade also fixes overlay exit animations by wrapping content nodes so layout animations no longer share transforms with animated styles, restores the Android input focus ring, and hardens Pressable style callback typing.
+
+**Fixes:**
+
+- Moved `entering` / `exiting` layout animations onto a wrapper `Animated.View` for Popover, Menu, and Select to fix exit animations and remove the Reanimated layout-animation override warning
+- Show the input focus ring on Android using a border, with iOS retaining the outline approach
+- Simplified the default exiting keyframes by dropping the `scale` transform
+- Added explicit `PressableStateCallbackType` typing to button and sub-menu style callbacks
+
+**Dependency upgrades:**
+
+- Expo `57`
+- React Native `0.86`
+- React Native Reanimated `4.5`
+- `react-native-worklets` `0.10`
+- Tailwind CSS `4.3`
+- Uniwind `1.10`
+
+Public APIs are unchanged, but consumers should align their peer versions with Expo 57 / React Native 0.86. Manual testing of overlay open/close animations on iOS and Android and input focus states is recommended.
+
+**Related PR:** [#439](https://github.com/heroui-inc/heroui-native/pull/439)
+
+## ⚠️ Breaking Changes
+
+### Split `border-field` Into Separate Width and Color Tokens
+
+Previously, `border-field` generated both a width and a color utility under the same name, so `tailwind-merge` dropped the width. Field components hardcoded border widths (`border`, `border-[1.5px]`) and used border-color for focus and invalid states. v1.0.5 splits the field border into two non-conflicting utilities and configures `tailwind-variants` globally so width and color no longer collapse during merge.
+
+**What changed:**
+
+- `border-field-width` (width) and `border-field-border` (color) are now separate, non-conflicting utilities
+- `tv` / `cn` are configured with a shared `twMergeConfig` (`border-w` group) registered globally; all `*.styles.ts` import `tv` from the lib
+- Input, InputOTP, Radio, and Checkbox use `border-field-width` and `outline-*` for focus, active, and invalid states; the invalid outline now shows at rest
+- The `--field-radius` multiplier changed from `1.5` to `1.75`
+
+The public component API is unchanged, but the visual and behavioral changes require verification. Please confirm the following in your app:
+
+**Migration:**
+
+Borders set via the `--field-border` color alone no longer appear — `--field-border-width` now defaults to `0px`, so set a width as well:
+
+```tsx
+// Before — a color alone rendered a visible border
+// --field-border: <color>;
+
+// After — also set a width, since --field-border-width defaults to 0px
+// --field-border: <color>;
+// --field-border-width: 1.5px;
+```
+
+When using the field border width utility directly, rename it:
+
+```tsx
+// Before
+<View className="border-field" />
+
+// After
+<View className="border-field-width" />
+```
+
+**Also verify:**
+
+- Focus, active, and invalid states now use `outline-*` rather than border-color
+- Overrides of the `--border-width-field` theme key must use `--border-width-field-width` (or the `--field-border-width` primitive)
+- Field corner radius changes slightly (`--field-radius` multiplier `1.5` → `1.75`)
+
+If you rely on `--field-border` color to produce resting borders, set a non-zero `--field-border-width` default to restore that appearance.
+
+**Related PR:** [#434](https://github.com/heroui-inc/heroui-native/pull/434)
+
+## Updated Documentation
+
+The following documentation pages have been updated to reflect the changes in this release:
+
+- [Typography](/docs/native/components/text) - Documented the default `dynamicTypeRamp` behavior on iOS
+- [Select](/docs/native/components/select) - Updated the `Select.ItemIndicator` default check icon color
+- [Provider](/docs/native/getting-started/provider) - Added the `textInputProps` section, examples, and provider hierarchy
+
+## Links
+
+- [Component Documentation](../components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-native)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/react/components/(buttons)/button-group.mdx b/apps/docs/content/docs/en/react/components/(buttons)/button-group.mdx
new file mode 100644
index 0000000..6610457
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(buttons)/button-group.mdx
@@ -0,0 +1,184 @@
+---
+title: ButtonGroup
+description: Group related buttons together with consistent styling and spacing
+
+links:
+  rac: Button
+  source: button-group/button-group.tsx
+  styles: button-group.css
+  storybook: Components/Buttons/ButtonGroup
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### Anatomy
+
+Import the ButtonGroup component and access all parts using dot notation.
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+
+export default () => (
+  <ButtonGroup>
+    <Button>First</Button>
+    <Button>
+      <ButtonGroup.Separator />
+      Second
+    </Button>
+    <Button>
+      <ButtonGroup.Separator />
+      Third
+    </Button>
+  </ButtonGroup>
+);
+```
+
+> **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.
+
+### Variants
+
+<ComponentPreview
+  name="button-group-variants"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="button-group-sizes"
+/>
+
+### Orientation
+
+Use the `orientation` prop to arrange buttons horizontally or vertically.
+
+<ComponentPreview
+  name="button-group-orientation"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="button-group-with-icons"
+/>
+
+### Full Width
+
+<ComponentPreview
+  name="button-group-full-width"
+/>
+
+### Disabled State
+
+<ComponentPreview
+  name="button-group-disabled"
+/>
+
+### Without Separator
+
+Simply omit the `<ButtonGroup.Separator />` component from your buttons.
+
+<ComponentPreview
+  name="button-group-without-separator"
+/>
+
+<RelatedComponents component="button-group" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ButtonGroup, Button } from '@heroui/react';
+
+function CustomButtonGroup() {
+  return (
+    <ButtonGroup className="gap-2">
+      <Button>First</Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Second
+      </Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Third
+      </Button>
+    </ButtonGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ButtonGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .button-group {
+    @apply gap-2 rounded-lg;
+  }
+
+  .button-group__separator {
+    @apply opacity-25;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):
+
+#### Base Classes
+- `.button-group` - Base button group container
+- `.button-group--full-width` - Full width modifier
+- `.button-group__separator` - Separator element between buttons
+
+The ButtonGroup component automatically applies border radius to buttons:
+- First button gets rounded left/start edge
+- Last button gets rounded right/end edge
+- Middle buttons have no border radius
+- Single button gets full border radius on all edges
+
+Add `<ButtonGroup.Separator />` inside each Button (except the first) to show dividers between buttons.
+
+## API Reference
+
+### ButtonGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | Visual style variant applied to all buttons in the group |
+| `size` | `'sm' \| 'md' \| 'lg'` | - | Size applied to all buttons in the group |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the button group |
+| `fullWidth` | `boolean` | `false` | Whether the button group should take full width of its container |
+| `isDisabled` | `boolean` | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Button components to group together |
+
+### ButtonGroup.Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+### Notes
+
+- ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
+- **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
+- Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}`
+- The component automatically handles border radius between buttons
+- Add `<ButtonGroup.Separator />` inside each Button (except the first) to show dividers between buttons
+- Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance
diff --git a/apps/docs/content/docs/en/react/components/(buttons)/button.mdx b/apps/docs/content/docs/en/react/components/(buttons)/button.mdx
new file mode 100644
index 0000000..c60a220
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(buttons)/button.mdx
@@ -0,0 +1,202 @@
+---
+title: Button
+description: A clickable button component with multiple variants and states
+links:
+  rac: Button
+  source: button/button.tsx
+  styles: button.css
+  storybook: Components/Buttons/Button
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Button } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="button-basic"
+/>
+
+### Variants
+
+
+<ComponentPreview
+  name="button-variants"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="button-with-icons"
+/>
+
+### Icon Only
+
+<ComponentPreview
+  name="button-icon-only"
+/>
+
+### Loading
+
+<ComponentPreview
+  name="button-loading"
+/>
+
+### Loading State
+
+<ComponentPreview
+  name="button-loading-state"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="button-sizes"
+/>
+
+### Full Width
+
+<ComponentPreview
+  name="button-full-width"
+/>
+
+### Disabled State
+
+
+<ComponentPreview
+  name="button-disabled"
+/>
+
+### Social Buttons
+
+<ComponentPreview
+  name="button-social"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="button-custom-render-function"
+/>
+
+<RelatedComponents component="button" />
+
+<RelatedShowcases component="Button" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Button } from '@heroui/react';
+
+function CustomButton() {
+  return (
+    <Button className="bg-purple-500 text-white hover:bg-purple-600">
+      Purple Button
+    </Button>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Button component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .button {
+    @apply bg-purple-500 text-white hover:bg-purple-600;
+  }
+
+  .button--icon-only {
+    @apply rounded-lg bg-blue-500;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### Adding custom variants
+
+You can extend HeroUI components by wrapping them and adding your own custom variants.
+
+<ComponentPreview
+  name="button-custom-variants"
+/>
+
+### Adding Ripple Effect
+
+The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).
+
+<ComponentPreview
+  name="button-ripple-effect"
+/>
+
+### CSS Classes
+
+The Button component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)):
+
+#### Base & Size Classes
+- `.button` - Base button styles
+- `.button--sm` - Small size variant
+- `.button--md` - Medium size variant
+- `.button--lg` - Large size variant
+
+#### Variant Classes
+- `.button--primary`
+- `.button--secondary`
+- `.button--tertiary`
+- `.button--outline`
+- `.button--ghost`
+- `.button--danger`
+
+#### Modifier Classes
+- `.button--icon-only`
+- `.button--icon-only.button--sm`
+- `.button--icon-only.button--lg`
+
+### Interactive States
+
+The button supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
+- **Pending**: `[data-pending]` (no pointer events during loading)
+
+## API Reference
+
+### Button Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
+| `fullWidth` | `boolean` | `false` | Whether the button should take full width of its container |
+| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
+| `isPending` | `boolean` | `false` | Whether the button is in a loading state |
+| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
+| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
+| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ButtonRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isPending` | `boolean` | Whether the button is in a loading state |
+| `isPressed` | `boolean` | Whether the button is currently pressed |
+| `isHovered` | `boolean` | Whether the button is hovered |
+| `isFocused` | `boolean` | Whether the button is focused |
+| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
+| `isDisabled` | `boolean` | Whether the button is disabled |
+
diff --git a/apps/docs/content/docs/en/react/components/(buttons)/close-button.mdx b/apps/docs/content/docs/en/react/components/(buttons)/close-button.mdx
new file mode 100644
index 0000000..10beec2
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(buttons)/close-button.mdx
@@ -0,0 +1,119 @@
+---
+title: CloseButton
+description: Button component for closing dialogs, modals, or dismissing content
+links:
+  rac: Button
+  source: close-button/close-button.tsx
+  styles: close-button.css
+  storybook: Components/Buttons/CloseButton
+---
+
+## Import
+
+```tsx
+import { CloseButton } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview
+  name="close-button-default"
+/>
+
+### With Custom Icon
+
+<ComponentPreview
+  name="close-button-with-custom-icon"
+/>
+
+### Interactive
+
+<ComponentPreview
+  name="close-button-interactive"
+/>
+
+<RelatedComponents component="closebutton" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {CloseButton} from "@heroui/react";
+
+function CustomCloseButton() {
+  return <CloseButton className="text-red-600 hover:bg-red-100">Close</CloseButton>;
+}
+```
+
+### Customizing the component classes
+
+To customize the CloseButton component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .close-button {
+    @apply bg-red-100 text-red-800 hover:bg-red-200;
+  }
+
+  .close-button--custom {
+    @apply rounded-full border-2 border-red-300;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The CloseButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)):
+
+#### Base Classes
+
+- `.close-button` - Base component styles
+
+#### Variant Classes
+
+- `.close-button--default` - Default variant
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Active/Pressed**: `:active` or `[data-pressed="true"]`
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+
+## API Reference
+
+### CloseButton Props
+
+| Prop       | Type                    | Default     | Description |
+| ---------- | ----------------------- | ----------- | ----------- |
+| `variant`  | `"default"`             | `"default"` | Visual variant of the button |
+| `children` | `ReactNode \| function` | `<CloseIcon />` | Content to display (defaults to close icon) |
+| `onPress`  | `() => void`            | -           | Handler called when the button is pressed |
+| `isDisabled` | `boolean`             | `false`     | Whether the button is disabled |
+
+### React Aria Button Props
+
+CloseButton extends all React Aria Button props. Common props include:
+
+| Prop              | Type      | Description |
+| ----------------- | --------- | ----------- |
+| `aria-label`      | `string`  | Accessible label for screen readers |
+| `aria-labelledby` | `string`  | ID of element that labels the button |
+| `aria-describedby`| `string`  | ID of element that describes the button |
+
+### RenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop          | Type      | Description |
+| ------------- | --------- | ----------- |
+| `isHovered`   | `boolean` | Whether the button is hovered |
+| `isPressed`   | `boolean` | Whether the button is pressed |
+| `isFocused`   | `boolean` | Whether the button is focused |
+| `isDisabled`  | `boolean` | Whether the button is disabled |
diff --git a/apps/docs/content/docs/en/react/components/(buttons)/toggle-button-group.mdx b/apps/docs/content/docs/en/react/components/(buttons)/toggle-button-group.mdx
new file mode 100644
index 0000000..0adab79
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(buttons)/toggle-button-group.mdx
@@ -0,0 +1,192 @@
+---
+title: ToggleButtonGroup
+description: Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options.
+links:
+  rac: ToggleButtonGroup
+  source: toggle-button-group/toggle-button-group.tsx
+  styles: toggle-button-group.css
+  storybook: Components/Buttons/ToggleButtonGroup
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="toggle-button-group-basic"
+/>
+
+### Anatomy
+
+Import the ToggleButtonGroup component and access all parts using dot notation.
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+
+export default () => (
+  <ToggleButtonGroup selectionMode="multiple">
+    <ToggleButton id="first">First</ToggleButton>
+    <ToggleButton id="second">
+      <ToggleButtonGroup.Separator />
+      Second
+    </ToggleButton>
+    <ToggleButton id="third">
+      <ToggleButtonGroup.Separator />
+      Third
+    </ToggleButton>
+  </ToggleButtonGroup>
+);
+```
+
+### Sizes
+
+<ComponentPreview
+  name="toggle-button-group-sizes"
+/>
+
+### Orientation
+
+<ComponentPreview
+  name="toggle-button-group-orientation"
+/>
+
+### Detached
+
+Use `isDetached` to separate buttons with gaps instead of connecting them.
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### Full Width
+
+<ComponentPreview
+  name="toggle-button-group-full-width"
+/>
+
+### Selection Mode
+
+Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles.
+
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="toggle-button-group-controlled"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="toggle-button-group-disabled"
+/>
+
+### Without Separator
+
+Simply omit the `<ToggleButtonGroup.Separator />` component from your buttons.
+
+<ComponentPreview
+  name="toggle-button-group-without-separator"
+/>
+
+<RelatedComponents component="toggle-button-group" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
+
+function CustomToggleButtonGroup() {
+  return (
+    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
+      <ToggleButton id="a">Option A</ToggleButton>
+      <ToggleButton id="b">
+        <ToggleButtonGroup.Separator />
+        Option B
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ToggleButtonGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toggle-button-group {
+    @apply rounded-lg;
+  }
+
+  .toggle-button-group__separator {
+    @apply opacity-25;
+  }
+
+  .toggle-button-group--full-width {
+    @apply w-full;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ToggleButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)):
+
+#### Base & Layout Classes
+- `.toggle-button-group` - Base container styles
+- `.toggle-button-group--horizontal` - Horizontal orientation
+- `.toggle-button-group--vertical` - Vertical orientation
+- `.toggle-button-group--full-width` - Full width modifier
+- `.toggle-button-group__separator` - Separator element between buttons
+
+#### Modifier Classes
+- `.toggle-button-group--detached` - Detached mode (separated buttons with gaps)
+
+## API Reference
+
+### ToggleButtonGroup Props
+
+Inherits from [React Aria ToggleButtonGroup](https://react-aria.adobe.com/ToggleButtonGroup).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether one or multiple buttons can be selected |
+| `selectedKeys` | `Iterable<Key>` | - | Controlled selection state |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | Default selected keys (uncontrolled) |
+| `onSelectionChange` | `(keys: Set<Key>) => void` | - | Called when selection changes |
+| `disallowEmptySelection` | `boolean` | `false` | Prevents clearing all selections |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size propagated to child ToggleButtons |
+| `isDetached` | `boolean` | `false` | Whether buttons are visually separated with gaps |
+| `fullWidth` | `boolean` | `false` | Whether the group fills available width |
+| `isDisabled` | `boolean` | `false` | Disables all buttons in the group |
+| `className` | `string` | - | Additional CSS classes |
+
+### ToggleButtonGroup.Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+### Notes
+
+- ToggleButtonGroup uses React Context to pass `size` to all child ToggleButton components
+- Each ToggleButton must have a unique `id` prop that corresponds to the keys used in `selectedKeys` / `defaultSelectedKeys`
+- The `isDisabled` prop is handled natively by React Aria and disables all child ToggleButtons — individual buttons can override this by setting `isDisabled={false}`
+- The component automatically handles border radius between buttons
+- Add `<ToggleButtonGroup.Separator />` inside each ToggleButton (except the first) to show dividers between buttons
+- Use `disallowEmptySelection` with `selectionMode="single"` to ensure one option is always selected
diff --git a/apps/docs/content/docs/en/react/components/(buttons)/toggle-button.mdx b/apps/docs/content/docs/en/react/components/(buttons)/toggle-button.mdx
new file mode 100644
index 0000000..a25b9c6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(buttons)/toggle-button.mdx
@@ -0,0 +1,150 @@
+---
+title: ToggleButton
+description: An interactive toggle control for on/off or selected/unselected states
+links:
+  rac: ToggleButton
+  source: toggle-button/toggle-button.tsx
+  styles: toggle-button.css
+  storybook: Components/Buttons/ToggleButton
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ToggleButton } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="toggle-button-basic"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="toggle-button-variants"
+/>
+
+### Icon Only
+
+<ComponentPreview
+  name="toggle-button-icon-only"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="toggle-button-sizes"
+/>
+
+
+### Controlled
+
+<ComponentPreview
+  name="toggle-button-controlled"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="toggle-button-disabled"
+/>
+
+<RelatedComponents component="togglebutton" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ToggleButton } from '@heroui/react';
+
+function CustomToggleButton() {
+  return (
+    <ToggleButton className="bg-purple-500 text-white">
+      Toggle
+    </ToggleButton>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ToggleButton component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toggle-button {
+    @apply bg-purple-500 text-white;
+  }
+
+  .toggle-button--icon-only {
+    @apply rounded-lg;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ToggleButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)):
+
+#### Base & Size Classes
+- `.toggle-button` - Base toggle button styles
+- `.toggle-button--sm` - Small size variant
+- `.toggle-button--md` - Medium size variant (default)
+- `.toggle-button--lg` - Large size variant
+
+#### Variant Classes
+- `.toggle-button--default` - Default variant with filled background
+- `.toggle-button--ghost` - Ghost variant with transparent background
+
+#### Modifier Classes
+- `.toggle-button--icon-only` - Icon-only toggle button
+- `.toggle-button--icon-only.toggle-button--sm` - Small icon-only
+- `.toggle-button--icon-only.toggle-button--lg` - Large icon-only
+
+### Interactive States
+
+The toggle button supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Selected**: `[data-selected="true"]` (accent background and foreground)
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
+
+## API Reference
+
+### ToggleButton Props
+
+Inherits from [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'default' \| 'ghost'` | `'default'` | Visual style variant |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the toggle button |
+| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
+| `isSelected` | `boolean` | - | Controlled selected state |
+| `defaultSelected` | `boolean` | `false` | Default selected state (uncontrolled) |
+| `isDisabled` | `boolean` | `false` | Whether the toggle button is disabled |
+| `onChange` | `(isSelected: boolean) => void` | - | Handler called when selection changes |
+| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
+| `children` | `React.ReactNode \| (values: ToggleButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
+
+### ToggleButtonRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the button is currently selected |
+| `isPressed` | `boolean` | Whether the button is currently pressed |
+| `isHovered` | `boolean` | Whether the button is hovered |
+| `isFocused` | `boolean` | Whether the button is focused |
+| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
+| `isDisabled` | `boolean` | Whether the button is disabled |
diff --git a/apps/docs/content/docs/en/react/components/(collections)/dropdown.mdx b/apps/docs/content/docs/en/react/components/(collections)/dropdown.mdx
new file mode 100644
index 0000000..a8854dc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(collections)/dropdown.mdx
@@ -0,0 +1,529 @@
+---
+title: Dropdown
+description: A dropdown displays a list of actions or options that a user can choose
+links:
+  rac: Menu
+  source: dropdown/dropdown.tsx
+  styles: dropdown.css
+  storybook: Components/Collections/Dropdown
+---
+
+## Import
+
+```tsx
+import { Dropdown } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="dropdown-default"
+/>
+
+### Anatomy
+
+Import the Dropdown component and access all parts using dot notation.
+
+```tsx
+import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react';
+
+export default () => (
+  <Dropdown>
+    <Dropdown.Trigger>
+      <Button />
+    </Dropdown.Trigger>
+    <Dropdown.Popover>
+      <Dropdown.Menu>
+        <Dropdown.Item>
+          <Label />
+          <Description />
+          <Kbd slot="keyboard" />
+          <Dropdown.ItemIndicator />
+        </Dropdown.Item>
+        <Separator />
+        <Dropdown.Section>
+          <Header />
+          <Dropdown.Item />
+        </Dropdown.Section>
+        <Dropdown.SubmenuTrigger>
+          <Dropdown.Item>
+            <Label />
+            <Dropdown.SubmenuIndicator />
+          </Dropdown.Item>
+          <Dropdown.Popover>
+            <Dropdown.Menu>
+              <Dropdown.Item />
+            </Dropdown.Menu>
+          </Dropdown.Popover>
+        </Dropdown.SubmenuTrigger>
+      </Dropdown.Menu>
+    </Dropdown.Popover>
+  </Dropdown>
+)
+```
+
+### With Single Selection
+
+<ComponentPreview
+  name="dropdown-with-single-selection"
+/>
+
+### Single With Custom Indicator
+
+<ComponentPreview
+  name="dropdown-single-with-custom-indicator"
+/>
+
+### With Multiple Selection
+
+<ComponentPreview
+  name="dropdown-with-multiple-selection"
+/>
+
+### With Section Level Selection
+
+<ComponentPreview
+  name="dropdown-with-section-level-selection"
+/>
+
+### With Keyboard Shortcuts
+
+<ComponentPreview
+  name="dropdown-with-keyboard-shortcuts"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="dropdown-with-icons"
+/>
+
+### Long Press Trigger
+
+<ComponentPreview
+  name="dropdown-long-press-trigger"
+/>
+
+### With Descriptions
+
+<ComponentPreview
+  name="dropdown-with-descriptions"
+/>
+
+### With Sections
+
+<ComponentPreview
+  name="dropdown-with-sections"
+/>
+
+### With Disabled Items
+
+<ComponentPreview
+  name="dropdown-with-disabled-items"
+/>
+
+### With Submenus
+
+<ComponentPreview
+  name="dropdown-with-submenus"
+/>
+
+### With Custom Submenu Indicator
+
+<ComponentPreview
+  name="dropdown-with-custom-submenu-indicator"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="dropdown-controlled"
+/>
+
+### Controlled Open State
+
+<ComponentPreview
+  name="dropdown-controlled-open-state"
+/>
+
+### Custom Trigger
+
+<ComponentPreview
+  name="dropdown-custom-trigger"
+/>
+
+<RelatedComponents component="dropdown" />
+ 
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Dropdown, Button } from '@heroui/react';
+
+function CustomDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger className="rounded-lg border p-2 bg-surface">
+        <Button>Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Popover className="min-w-[200px]">
+        <Dropdown.Menu>
+          <Dropdown.Item id="item-1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Dropdown component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .dropdown {
+    @apply flex flex-col gap-1;
+  }
+
+  .dropdown__trigger {
+    @apply outline-none;
+  }
+
+  .dropdown__popover {
+    @apply rounded-lg border border-border bg-overlay p-2;
+  }
+
+  .dropdown__menu {
+    @apply flex flex-col gap-1;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Dropdown component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)):
+
+#### Base Classes
+- `.dropdown` - Base dropdown container
+- `.dropdown__trigger` - The button or element that triggers the dropdown
+- `.dropdown__popover` - The popover container
+- `.dropdown__menu` - The menu container inside the popover
+
+#### State Classes
+- `.dropdown__trigger[data-focus-visible="true"]` - Focused trigger state
+- `.dropdown__trigger[data-disabled="true"]` - Disabled trigger state
+- `.dropdown__trigger[data-pressed="true"]` - Pressed trigger state
+- `.dropdown__popover[data-entering]` - Entering animation state
+- `.dropdown__popover[data-exiting]` - Exiting animation state
+- `.dropdown__menu[data-selection-mode="single"]` - Single selection mode
+- `.dropdown__menu[data-selection-mode="multiple"]` - Multiple selection mode
+
+### Menu Component Classes
+
+The Dropdown component uses Menu, MenuItem, and MenuSection as base components. These classes are also available for customization:
+
+#### Menu Classes
+- `.menu` - Base menu container ([menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css))
+  - `[data-slot="separator"]` - Separator elements within the menu
+
+#### MenuItem Classes
+- `.menu-item` - Base menu item container ([menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css))
+- `.menu-item__indicator` - Selection indicator (checkmark or dot)
+  - `[data-slot="menu-item-indicator--checkmark"]` - Checkmark indicator SVG
+  - `[data-slot="menu-item-indicator--dot"]` - Dot indicator SVG
+- `.menu-item__indicator--submenu` - Submenu indicator (chevron)
+- `.menu-item--default` - Default variant styling
+- `.menu-item--danger` - Danger variant styling
+
+#### MenuItem State Classes
+- `.menu-item[data-focus-visible="true"]` - Focused item state (keyboard focus)
+- `.menu-item[data-focus="true"]` - Focused item state
+- `.menu-item[data-pressed]` - Pressed item state
+- `.menu-item[data-hovered]` - Hovered item state
+- `.menu-item[data-selected="true"]` - Selected item state
+- `.menu-item[data-disabled]` - Disabled item state
+- `.menu-item[data-has-submenu="true"]` - Item with submenu
+- `.menu-item[data-selection-mode="single"]` - Single selection mode
+- `.menu-item[data-selection-mode="multiple"]` - Multiple selection mode
+- `.menu-item[aria-checked="true"]` - Checked item (ARIA)
+- `.menu-item[aria-selected="true"]` - Selected item (ARIA)
+
+#### MenuSection Classes
+- `.menu-section` - Base menu section container ([menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css))
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger and items
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger and items
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on trigger and items
+- **Pressed**: `:active` or `[data-pressed="true"]` on trigger and items
+- **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on items
+
+## API Reference
+
+### Dropdown Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | `boolean` | - | Sets the open state of the menu (controlled) |
+| `defaultOpen` | `boolean` | - | Sets the default open state of the menu (uncontrolled) |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes |
+| `trigger` | `"press" \| "longPress"` | `"press"` | The type of interaction that triggers the menu |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Dropdown content |
+
+### Dropdown.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function |
+
+All [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props are also supported when using a Button as the trigger.
+
+### Dropdown.Popover Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Content children |
+
+All [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props are also supported.
+
+### Dropdown.Menu Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectionMode` | `"single" \| "multiple" \| "none"` | `"none"` | Whether single or multiple selection is enabled |
+| `selectedKeys` | `Iterable<Key>` | - | The currently selected keys (controlled) |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | The initial selected keys (uncontrolled) |
+| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes |
+| `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items |
+| `onAction` | `(key: Key) => void` | - | Handler called when an item is activated |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Menu content |
+
+All [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props are also supported.
+
+### Dropdown.Section Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectionMode` | `"single" \| "multiple"` | - | Selection mode for items within this section |
+| `selectedKeys` | `Iterable<Key>` | - | The currently selected keys (controlled) |
+| `defaultSelectedKeys` | `Iterable<Key>` | - | The initial selected keys (uncontrolled) |
+| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes |
+| `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Section content |
+
+All [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props are also supported.
+
+### Dropdown.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `Key` | - | Unique identifier for the item |
+| `textValue` | `string` | - | Text content of the item for typeahead |
+| `variant` | `"default" \| "danger"` | `"default"` | Visual variant of the item |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Item content or render function |
+
+All [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props are also supported.
+
+### Dropdown.ItemIndicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"checkmark" \| "dot"` | `"checkmark"` | Type of indicator to display |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Custom indicator content or render function |
+
+When using a render function, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the item is selected |
+| `isIndeterminate` | `boolean` | Whether the item is in an indeterminate state |
+
+### Dropdown.SubmenuIndicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom indicator content |
+
+### Dropdown.SubmenuTrigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Submenu trigger content |
+
+All [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props are also supported.
+
+### RenderProps
+
+When using render functions with Dropdown.Item, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the item is selected |
+| `isFocused` | `boolean` | Whether the item is focused |
+| `isDisabled` | `boolean` | Whether the item is disabled |
+| `isPressed` | `boolean` | Whether the item is being pressed |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Dropdown, Button, Label } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Actions
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Item id="new-file" textValue="New file">
+        <Label>New file</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="open-file" textValue="Open file">
+        <Label>Open file</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+        <Label>Delete file</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### With Sections
+
+```tsx
+import { Dropdown, Button, Label, Header, Separator } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Actions
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Section>
+        <Header>Actions</Header>
+        <Dropdown.Item id="new-file" textValue="New file">
+          <Label>New file</Label>
+        </Dropdown.Item>
+        <Dropdown.Item id="edit-file" textValue="Edit file">
+          <Label>Edit file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+      <Separator />
+      <Dropdown.Section>
+        <Header>Danger zone</Header>
+        <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+          <Label>Delete file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### Controlled Selection
+
+```tsx
+import type { Selection } from '@heroui/react';
+
+import { Dropdown, Button, Label } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledDropdown() {
+  const [selected, setSelected] = useState<Selection>(new Set(['bold']));
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Item id="bold" textValue="Bold">
+            <Label>Bold</Label>
+            <Dropdown.ItemIndicator />
+          </Dropdown.Item>
+          <Dropdown.Item id="italic" textValue="Italic">
+            <Label>Italic</Label>
+            <Dropdown.ItemIndicator />
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+### With Submenus
+
+```tsx
+import { Dropdown, Button, Label } from '@heroui/react';
+
+<Dropdown>
+  <Button aria-label="Menu" variant="secondary">
+    Share
+  </Button>
+  <Dropdown.Popover>
+    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+      <Dropdown.Item id="copy-link" textValue="Copy Link">
+        <Label>Copy Link</Label>
+      </Dropdown.Item>
+      <Dropdown.SubmenuTrigger>
+        <Dropdown.Item id="share" textValue="Share">
+          <Label>Other</Label>
+          <Dropdown.SubmenuIndicator />
+        </Dropdown.Item>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+              <Label>WhatsApp</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="telegram" textValue="Telegram">
+              <Label>Telegram</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown.SubmenuTrigger>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+## Accessibility
+
+The Dropdown component implements the ARIA menu pattern and provides:
+
+- Full keyboard navigation support (arrow keys, home/end, typeahead)
+- Screen reader announcements for actions and selection changes
+- Proper focus management
+- Support for disabled states
+- Long press interaction support
+- Submenu navigation
+
+For more information, see the [React Aria Menu documentation](https://react-spectrum.adobe.com/react-aria/Menu.html#menu).
+
diff --git a/apps/docs/content/docs/en/react/components/(collections)/list-box.mdx b/apps/docs/content/docs/en/react/components/(collections)/list-box.mdx
new file mode 100644
index 0000000..22aa757
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(collections)/list-box.mdx
@@ -0,0 +1,329 @@
+---
+title: ListBox
+description: A listbox displays a list of options and allows a user to select one or more of them
+links:
+  rac: ListBox
+  source: list-box/list-box.tsx
+  styles: list-box.css
+  storybook: Components/Collections/ListBox
+---
+
+## Import
+
+```tsx
+import { ListBox } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="list-box-default"
+/>
+
+### Anatomy
+
+Import the ListBox component and access all parts using dot notation.
+
+```tsx
+import { ListBox, Label, Description, Header } from '@heroui/react';
+
+export default () => (
+  <ListBox>
+    <ListBox.Item>
+      <Label />
+      <Description />
+      <ListBox.ItemIndicator />
+    </ListBox.Item>
+    <ListBox.Section>
+      <Header />
+      <ListBox.Item>
+        <Label />
+      </ListBox.Item>
+    </ListBox.Section>
+  </ListBox>
+)
+```
+
+### With Sections
+
+<ComponentPreview
+  name="list-box-with-sections"
+/>
+
+### Multi Select
+
+<ComponentPreview
+  name="list-box-multi-select"
+/>
+
+### With Disabled Items
+
+<ComponentPreview
+  name="list-box-with-disabled-items"
+/>
+
+### Custom Check Icon
+
+<ComponentPreview
+  name="list-box-custom-check-icon"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="list-box-controlled"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="list-box-custom-render-function"
+/>
+
+### Virtualization
+
+ListBox supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
+
+<ComponentPreview 
+  name="list-box-virtualization"
+/>
+
+<RelatedComponents component="list-box" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ListBox } from '@heroui/react';
+
+function CustomListBox() {
+  return (
+    <ListBox className="border rounded-lg p-2 bg-surface">
+      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+        Item 1
+      </ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ListBox component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .list-box {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .list-box-item {
+    @apply rounded px-2 py-1 cursor-pointer;
+  }
+
+  .list-box-item--danger {
+    @apply text-danger;
+  }
+
+  .list-box-item__indicator {
+    @apply text-accent;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ListBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/list-box.css)):
+
+#### Base Classes
+- `.list-box` - Base listbox container
+- `.list-box-item` - Individual listbox item
+- `.list-box-item__indicator` - Selection indicator icon
+- `.list-box-section` - Section container for grouping items
+
+#### Variant Classes
+- `.list-box--default` - Default variant styling
+- `.list-box--danger` - Danger variant styling
+- `.list-box-item--default` - Default item variant
+- `.list-box-item--danger` - Danger item variant
+
+#### State Classes
+- `.list-box-item[data-selected="true"]` - Selected item state
+- `.list-box-item[data-focus-visible="true"]` - Focused item state
+- `.list-box-item[data-disabled="true"]` - Disabled item state
+- `.list-box-item__indicator[data-visible="true"]` - Visible indicator state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on item
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on item
+- **Selected**: `[data-selected="true"]` on item
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on item
+
+## API Reference
+
+### ListBox Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label for the listbox |
+| `aria-labelledby` | `string` | - | ID of element that labels the listbox |
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"single"` | Selection behavior |
+| `selectedKeys` | `Selection` | - | Controlled selected keys |
+| `defaultSelectedKeys` | `Selection` | - | Initial selected keys |
+| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when selection changes |
+| `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items |
+| `onAction` | `(key: Key) => void` | - | Handler called when an item is activated |
+| `variant` | `"default" \| "danger"` | `"default"` | Visual variant |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | ListBox items and sections |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ListBox.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `Key` | - | Unique identifier for the item |
+| `textValue` | `string` | - | Text value for accessibility and typeahead |
+| `isDisabled` | `boolean` | `false` | Whether this item is disabled |
+| `variant` | `"default" \| "danger"` | `"default"` | Visual variant |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Item content or render function |
+| `render` | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | - | Overrides the default DOM element with a custom render function.|
+
+### ListBox.ItemIndicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Custom indicator content or render function |
+
+### ListBox.Section Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Section content including Header and Items |
+
+### RenderProps
+
+When using render functions with ListBox.Item or ListBox.ItemIndicator, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the item is selected |
+| `isFocused` | `boolean` | Whether the item is focused |
+| `isDisabled` | `boolean` | Whether the item is disabled |
+| `isPressed` | `boolean` | Whether the item is being pressed |
+
+### ListLayout
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `rowHeight` | `number \| undefined` | 48 | The fixed height of a row in px. |
+| `estimatedRowHeight` | `number \| undefined` | — | The estimated height of a row, when row heights are variable. |
+| `headingHeight` | `number \| undefined` | 48 | The fixed height of a section header in px. |
+| `estimatedHeadingHeight` | `number \| undefined` | — | The estimated height of a section header, when the height is variable. |
+| `loaderHeight` | `number \| undefined` | 48 | The fixed height of a loader element in px. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections. |
+| `dropIndicatorThickness` | `number \| undefined` | 2 | The thickness of the drop indicator. |
+| `gap` | `number \| undefined` | 0 | The gap between items. |
+| `padding` | `number \| undefined` | 0 | The padding around the list. |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { ListBox, Label, Description } from '@heroui/react';
+
+<ListBox aria-label="Users" selectionMode="single">
+  <ListBox.Item id="1" textValue="Bob">
+    <Label>Bob</Label>
+    <Description>bob@heroui.com</Description>
+  </ListBox.Item>
+  <ListBox.Item id="2" textValue="Alice">
+    <Label>Alice</Label>
+    <Description>alice@heroui.com</Description>
+  </ListBox.Item>
+</ListBox>
+```
+
+### With Sections
+
+```tsx
+import { ListBox, Header, Separator } from '@heroui/react';
+
+<ListBox aria-label="Actions" selectionMode="none" onAction={(key) => console.log(key)}>
+  <ListBox.Section>
+    <Header>Actions</Header>
+    <ListBox.Item id="new" textValue="New file">New file</ListBox.Item>
+    <ListBox.Item id="edit" textValue="Edit file">Edit file</ListBox.Item>
+  </ListBox.Section>
+  <Separator />
+  <ListBox.Section>
+    <Header>Danger zone</Header>
+    <ListBox.Item id="delete" textValue="Delete" variant="danger">Delete</ListBox.Item>
+  </ListBox.Section>
+</ListBox>
+```
+
+### Controlled Selection
+
+```tsx
+import { ListBox, Selection } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledListBox() {
+  const [selected, setSelected] = useState<Selection>(new Set(["1"]));
+
+  return (
+    <ListBox
+      aria-label="Options"
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={setSelected}
+    >
+      <ListBox.Item id="1" textValue="Option 1">Option 1</ListBox.Item>
+      <ListBox.Item id="2" textValue="Option 2">Option 2</ListBox.Item>
+      <ListBox.Item id="3" textValue="Option 3">Option 3</ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+### Custom Indicator
+
+```tsx
+import { ListBox, ListBoxItemIndicator } from '@heroui/react';
+import { Icon } from '@iconify/react';
+
+<ListBox aria-label="Options" selectionMode="multiple">
+  <ListBox.Item id="1" textValue="Option 1">
+    Option 1
+    <ListBox.ItemIndicator>
+      {({isSelected}) =>
+        isSelected ? <Icon icon="gravity-ui:check" /> : null
+      }
+    </ListBox.ItemIndicator>
+  </ListBox.Item>
+</ListBox>
+```
+
+## Accessibility
+
+The ListBox component implements the ARIA listbox pattern and provides:
+
+- Full keyboard navigation support
+- Screen reader announcements for selection changes
+- Proper focus management
+- Support for disabled states
+- Typeahead search functionality
+
+For more information, see the [React Aria ListBox documentation](https://react-spectrum.adobe.com/react-aria/ListBox.html).
+
diff --git a/apps/docs/content/docs/en/react/components/(collections)/tag-group.mdx b/apps/docs/content/docs/en/react/components/(collections)/tag-group.mdx
new file mode 100644
index 0000000..7af333a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(collections)/tag-group.mdx
@@ -0,0 +1,298 @@
+---
+title: TagGroup
+description: A focusable list of tags with support for keyboard navigation, selection, and removal
+links:
+  rac: TagGroup
+  source: tag-group/tag-group.tsx
+  styles: tag-group.css
+  storybook: Components/Collections/TagGroup
+---
+
+## Import
+
+```tsx
+import { TagGroup } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="tag-group-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
+
+export default () => (
+  <TagGroup>
+    <Label />
+    <TagGroup.List>
+      <Tag>
+        <Tag.RemoveButton />
+      </Tag>
+    </TagGroup.List>
+    <Description />
+    <ErrorMessage />
+  </TagGroup>
+)
+```
+
+### Sizes
+
+<ComponentPreview
+  name="tag-group-sizes"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="tag-group-variants"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="tag-group-disabled"
+/>
+
+### Selection Modes
+
+<ComponentPreview
+  name="tag-group-selection-modes"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="tag-group-controlled"
+/>
+
+### With Error Message
+
+<ComponentPreview
+  name="tag-group-with-error-message"
+/>
+
+### With Prefix
+
+<ComponentPreview
+  name="tag-group-with-prefix"
+/>
+
+### With Remove Button
+
+<ComponentPreview
+  name="tag-group-with-remove-button"
+/>
+
+### With List Data
+
+<ComponentPreview
+  name="tag-group-with-list-data"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="tag-group-custom-render-function"
+/>
+
+<RelatedComponents component="taggroup" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { TagGroup, Tag, Label } from '@heroui/react';
+
+function CustomTagGroup() {
+  return (
+    <TagGroup className="w-full">
+      <Label>Categories</Label>
+      <TagGroup.List className="gap-2">
+        <Tag className="rounded-lg px-4 py-2 font-bold">
+          Custom Styled
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the TagGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .tag-group {
+    @apply flex flex-col gap-2;
+  }
+
+  .tag-group__list {
+    @apply flex flex-wrap gap-2;
+  }
+
+  .tag {
+    @apply rounded-full px-3 py-1;
+  }
+
+  .tag__remove-button {
+    @apply ml-1;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)):
+
+#### Base Classes
+- `.tag-group` - Base tag group container
+- `.tag-group__list` - Container for the list of tags
+- `.tag` - Base tag styles
+- `.tag__remove-button` - Remove button trigger
+
+#### Slot Classes
+- `.tag-group [slot="description"]` - Description slot styles
+- `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles
+
+#### Size Classes
+- `.tag--sm` - Small size tag
+- `.tag--md` - Medium size tag (default)
+- `.tag--lg` - Large size tag
+
+#### Variant Classes
+- `.tag--default` - Default variant
+- `.tag--surface` - Surface variant with surface background
+
+#### State Classes
+- `.tag[data-selected="true"]` - Selected tag state
+- `.tag[data-disabled="true"]` - Disabled tag state
+- `.tag[data-hovered="true"]` - Hovered tag state
+- `.tag[data-pressed="true"]` - Pressed tag state
+- `.tag[data-focus-visible="true"]` - Focused tag state (keyboard focus)
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on tag
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on tag
+- **Pressed**: `:active` or `[data-pressed="true"]` on tag
+- **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on tag
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on tag
+
+## API Reference
+
+### TagGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | The type of selection that is allowed |
+| `selectedKeys` | `Selection` | - | The currently selected keys (controlled) |
+| `defaultSelectedKeys` | `Selection` | - | The initial selected keys (uncontrolled) |
+| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes |
+| `disabledKeys` | `Iterable<Key>` | - | Keys of disabled tags |
+| `isDisabled` | `boolean` | - | Whether the tag group is disabled |
+| `onRemove` | `(keys: Set<Key>) => void` | - | Handler called when tags are removed |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the tags in the group |
+| `variant` | `"default" \| "surface"` | `"default"` | Visual variant of the tags |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | TagGroup content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function.|
+
+### TagGroup.List Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Iterable<T>` | - | The items to display in the tag list |
+| `renderEmptyState` | `() => ReactNode` | - | Function to render when the list is empty |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | TagList content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Tag Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `Key` | - | The unique identifier for the tag |
+| `textValue` | `string` | - | A string representation of the tag's content, used for accessibility |
+| `isDisabled` | `boolean` | - | Whether the tag is disabled |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Tag content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+**Note**: `size`, `variant` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components.
+
+### Tag.RemoveButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom remove button content (defaults to close icon) |
+
+**Note**: The `Tag.RemoveButton` component supports customization similar to `SearchField.ClearButton`. When `onRemove` is provided to `TagGroup`:
+
+- **Auto-rendering**: If no custom `Tag.RemoveButton` is included in the `Tag` children, a default remove button is automatically rendered.
+- **Custom button**: If a custom `Tag.RemoveButton` is provided as a child of `Tag`, it will be used instead of the auto-rendered button.
+- **Custom icon**: You can pass custom content (like icons) to `Tag.RemoveButton` children to customize the appearance.
+
+**Example - Auto-rendered (default)**:
+```tsx
+<TagGroup onRemove={handleRemove}>
+  <TagGroup.List>
+    <Tag id="news">News</Tag>
+    {/* Remove button is automatically rendered */}
+  </TagGroup.List>
+</TagGroup>
+```
+
+**Example - Custom RemoveButton with icon**:
+```tsx
+<TagGroup onRemove={handleRemove}>
+  <TagGroup.List>
+    <Tag id="news">
+      News
+      <Tag.RemoveButton>
+        <CustomIcon />
+      </Tag.RemoveButton>
+    </Tag>
+  </TagGroup.List>
+</TagGroup>
+```
+
+**Example - Custom RemoveButton in render props**:
+```tsx
+<Tag id="news">
+  {(renderProps) => (
+    <>
+      News
+      {!!renderProps.allowsRemoving && (
+        <Tag.RemoveButton>
+          <CustomIcon />
+        </Tag.RemoveButton>
+      )}
+    </>
+  )}
+</Tag>
+```
+
+### RenderProps
+
+When using render functions with TagGroup.List, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the tag is selected |
+| `isDisabled` | `boolean` | Whether the tag is disabled |
+| `isHovered` | `boolean` | Whether the tag is hovered |
+| `isPressed` | `boolean` | Whether the tag is pressed |
+| `isFocused` | `boolean` | Whether the tag is focused |
+| `isFocusVisible` | `boolean` | Whether the tag has keyboard focus |
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-area.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-area.mdx
new file mode 100644
index 0000000..0ac5ee2
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-area.mdx
@@ -0,0 +1,151 @@
+---
+title: ColorArea
+description: A 2D color picker that allows users to select colors from a gradient area
+links:
+  rac: ColorArea
+  source: color-area/color-area.tsx
+  styles: color-area.css
+  storybook: Components/Colors/ColorArea
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ColorArea } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="color-area-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { ColorArea } from '@heroui/react';
+
+export default () => (
+  <ColorArea>
+    <ColorArea.Thumb />
+  </ColorArea>
+);
+```
+
+### With Dots
+
+<ComponentPreview
+  name="color-area-with-dots"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="color-area-controlled"
+/>
+
+
+### Color Space & Channels
+
+Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel` props to customize which color channels are displayed on each axis.
+
+<ComponentPreview
+  name="color-area-space-and-channels"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="color-area-disabled"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="color-area-custom-render-function"
+/>
+
+<RelatedComponents component="color-area" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ColorArea } from '@heroui/react';
+
+function CustomColorArea() {
+  return (
+    <ColorArea className="max-w-72 rounded-3xl">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ColorArea component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-area {
+    @apply rounded-3xl;
+  }
+
+  .color-area__thumb {
+    @apply size-5 border-4;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ColorArea component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)):
+
+#### Base Classes
+- `.color-area` - Base styles with gradient background and inner shadow
+- `.color-area--show-dots` - Adds dot grid overlay for precision picking
+
+#### Element Classes
+- `.color-area__thumb` - Draggable thumb indicator
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Disabled**: `[data-disabled="true"]`
+- **Focus**: `[data-focus-visible="true"]`
+- **Dragging**: `[data-dragging="true"]` (thumb only)
+
+## API Reference
+
+### ColorArea Props
+
+Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| Color` | - | The current color value (controlled) |
+| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
+| `onChange` | `(color: Color) => void` | - | Handler called when the color changes while dragging |
+| `onChangeEnd` | `(color: Color) => void` | - | Handler called when the user stops dragging |
+| `xChannel` | `ColorChannel` | `"saturation"` | Color channel for the horizontal axis |
+| `yChannel` | `ColorChannel` | `"brightness"` | Color channel for the vertical axis |
+| `colorSpace` | `ColorSpace` | - | The color space for the channels |
+| `isDisabled` | `boolean` | `false` | Whether the color area is disabled |
+| `showDots` | `boolean` | `false` | Whether to show the dot grid overlay |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ColorArea.Thumb Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | Overrides the default DOM element with a custom render function.|
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-field.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-field.mdx
new file mode 100644
index 0000000..30bf0c1
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-field.mdx
@@ -0,0 +1,403 @@
+---
+title: ColorField
+description: Color input field with labels, descriptions, and validation built on React Aria ColorField
+links:
+  rac: ColorField
+  source: color-field/color-field.tsx
+  styles: color-field.css
+  storybook: Components/Colors/ColorField
+---
+
+## Import
+
+```tsx
+import { ColorField, parseColor } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="color-field-basic" />
+
+### Anatomy
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
+
+export default () => (
+  <ColorField>
+    <Label />
+    <ColorField.Group>
+      <ColorField.Prefix>
+        <ColorSwatch color="#000000" />
+      </ColorField.Prefix>
+      <ColorField.Input />
+    </ColorField.Group>
+    <Description />
+    <FieldError />
+  </ColorField>
+)
+```
+
+> **ColorField** combines label, color input, description, and error into a single accessible component.
+
+### With Description
+
+<ComponentPreview name="color-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="color-field-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="color-field-invalid" />
+
+### Channel Editing
+
+ColorField supports editing individual color channels (hue, saturation, lightness, red, green, blue, alpha) by setting the `colorSpace` and `channel` props.
+
+<ComponentPreview name="color-field-channel-editing" />
+
+### Controlled
+
+Control the value to synchronize with other components or state management.
+
+<ComponentPreview name="color-field-controlled" />
+
+### Disabled State
+
+<ComponentPreview name="color-field-disabled" />
+
+### Full Width
+
+<ComponentPreview name="color-field-full-width" />
+
+### Variants
+
+The ColorField.Group component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="color-field-variants" />
+
+### On Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="color-field-on-surface" />
+
+### Form Example
+
+Complete form example with validation and submission handling.
+
+<ComponentPreview name="color-field-form-example" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="color-field-custom-render-function"
+/>
+
+<RelatedComponents component="colorfield" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
+
+function CustomColorField() {
+  return (
+    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Brand Color
+      </Label>
+      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <ColorField.Prefix>
+          <ColorSwatch color="#3B82F6" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+      <Description className="text-xs text-default-500">
+        Select your brand's primary color.
+      </Description>
+    </ColorField>
+  );
+}
+```
+
+### Customizing the component classes
+
+ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.
+
+```css
+@layer components {
+  .color-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS Classes
+
+- `.color-field` – Root container with minimal styling (`flex flex-col gap-1`)
+
+> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. ColorField.Group styling is documented below in the API Reference section.
+
+### Interactive States
+
+ColorField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Required**: `[data-required="true"]` - Applied when `isRequired` is true
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
+
+## API Reference
+
+### ColorField Props
+
+ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | Child components (Label, ColorField.Group, etc.) or render function. |
+| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the color field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `Color \| null` | - | Current value (controlled). |
+| `defaultValue` | `Color \| null` | - | Default value (uncontrolled). |
+| `onChange` | `(color: Color \| null) => void` | - | Handler called when the value changes. |
+
+#### Channel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `colorSpace` | `ColorSpace` | - | The color space that the color field operates in when `channel` is provided. |
+| `channel` | `ColorChannel` | - | The color channel to edit. If not provided, edits hex value. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+| `isWheelDisabled` | `boolean` | - | Whether to disable changing the value with scroll. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+ColorField works with these separate components that should be imported and used directly:
+
+- **Label** - Field label component from `@heroui/react`
+- **ColorField.Group** - Color input group component (documented below)
+- **ColorField.Input** - Input element within ColorField.Group
+- **ColorField.Prefix** / **ColorField.Suffix** - Prefix and suffix slots for the input group
+- **ColorSwatch** - Color preview component from `@heroui/react`
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within ColorField for composition:
+
+```tsx
+import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
+
+<ColorField
+  isRequired
+  isInvalid={hasError}
+  value={color}
+  onChange={setColor}
+>
+  <Label>Brand Color</Label>
+  <ColorField.Group>
+    <ColorField.Prefix>
+      <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} />
+    </ColorField.Prefix>
+    <ColorField.Input />
+  </ColorField.Group>
+  <Description>Select your brand's primary color.</Description>
+  <FieldError>Please enter a valid color.</FieldError>
+</ColorField>
+```
+
+### Color Types
+
+ColorField uses `Color` objects from React Aria Components:
+
+```tsx
+import {parseColor} from '@heroui/react';
+
+// Parse from hex string
+const color = parseColor('#3B82F6');
+
+// Get hex string from color
+const hex = color.toString('hex'); // "#3b82f6"
+
+// Get RGB values
+const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
+
+// Use in ColorField
+<ColorField value={color} onChange={setColor}>
+  {/* ... */}
+</ColorField>
+```
+
+### ColorFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused. |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
+
+### ColorField.Group Props
+
+ColorField.Group accepts all props from React Aria's `Group` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `fullWidth` | `boolean` | `false` | Whether the color input group should take full width of its container |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ColorField.Input Props
+
+ColorField.Input accepts all props from React Aria's `Input` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `placeholder` | `string` | - | Placeholder text shown when empty. |
+
+### ColorField.Prefix Props
+
+ColorField.Prefix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the prefix slot. |
+
+### ColorField.Suffix Props
+
+ColorField.Suffix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the suffix slot. |
+
+## ColorField.Group Styling
+
+### Customizing the component classes
+
+The base classes power every instance. Override them once with `@layer components`.
+
+```css
+@layer components {
+  .color-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .color-input-group__input {
+    @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .color-input-group__prefix,
+  .color-input-group__suffix {
+    @apply shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### ColorField.Group CSS Classes
+
+- `.color-input-group` – Root container styling
+- `.color-input-group__input` – Input wrapper styling
+- `.color-input-group__prefix` – Prefix element styling
+- `.color-input-group__suffix` – Suffix element styling
+
+### ColorField.Group Interactive States
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
+- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
+- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-picker.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-picker.mdx
new file mode 100644
index 0000000..3b37b4b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-picker.mdx
@@ -0,0 +1,201 @@
+---
+title: ColorPicker
+description: A composable color picker that synchronizes color value between multiple color components
+links:
+  rac: ColorPicker
+  source: color-picker/color-picker.tsx
+  styles: color-picker.css
+  storybook: Components/Pickers/ColorPicker
+  figma: true
+---
+
+## Import
+
+```tsx
+import {
+  ColorPicker,
+  ColorArea,
+  ColorSlider,
+  ColorSwatch,
+  ColorField,
+  ColorSwatchPicker,
+} from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### Anatomy
+
+The ColorPicker is a composable component that combines multiple color components:
+
+```tsx
+import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
+
+export default () => (
+  <ColorPicker defaultValue="#0485F7">
+    <ColorPicker.Trigger>
+      <ColorSwatch />
+      <Label>Pick a color</Label>
+    </ColorPicker.Trigger>
+    <ColorPicker.Popover>
+      <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
+        <ColorArea.Thumb />
+      </ColorArea>
+      <ColorSlider channel="hue" colorSpace="hsb">
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    </ColorPicker.Popover>
+  </ColorPicker>
+);
+```
+
+### Controlled
+
+<ComponentPreview
+  name="color-picker-controlled"
+/>
+
+### With Swatches
+
+<ComponentPreview
+  name="color-picker-with-swatches"
+/>
+
+### With Fields
+
+Use `ColorField` to allow users to edit individual color channel values with a `Select` to switch between color spaces.
+
+<ComponentPreview
+  name="color-picker-with-fields"
+/>
+
+### With Sliders
+
+Use multiple `ColorSlider` components to adjust each channel of a color value.
+
+<ComponentPreview
+  name="color-picker-with-sliders"
+/>
+
+<RelatedComponents component="color-picker" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
+
+function CustomColorPicker() {
+  return (
+    <ColorPicker defaultValue="#0485F7">
+      <ColorPicker.Trigger className="gap-4">
+        <ColorSwatch className="rounded-lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="p-4 rounded-xl">
+        <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
+          <ColorArea.Thumb />
+        </ColorArea>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ColorPicker component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-picker {
+    @apply inline-flex;
+  }
+
+  .color-picker__trigger {
+    @apply inline-flex items-center gap-4 rounded-lg;
+  }
+
+  .color-picker__popover {
+    @apply p-4 rounded-xl;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ColorPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)):
+
+#### Base Classes
+- `.color-picker` - Base container
+- `.color-picker__trigger` - Trigger button
+- `.color-picker__popover` - Popover container
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[data-disabled="true"]`
+
+## API Reference
+
+### ColorPicker Props
+
+Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| Color` | - | The current color value (controlled) |
+| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
+| `onChange` | `(color: Color) => void` | - | Handler called when the color changes |
+| `children` | `React.ReactNode` | - | Content of the color picker (Trigger, Popover, etc.) |
+| `className` | `string` | - | Additional CSS classes |
+
+### ColorPicker.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | Trigger content or render prop |
+| `className` | `string` | - | Additional CSS classes |
+
+### ColorPicker.Popover Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `Placement` | `"bottom left"` | Placement of the popover |
+| `children` | `React.ReactNode` | - | Popover content |
+| `className` | `string` | - | Additional CSS classes |
+
+### Related Types
+
+#### Color
+
+Represents a color value. See [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color) for full API.
+
+| Method | Description |
+|--------|-------------|
+| `toString(format)` | Converts the color to a string in the given format (hex, rgb, hsl, hsb, css) |
+| `toFormat(format)` | Converts the color to the given format and returns a new Color object |
+| `getChannelValue(channel)` | Returns the numeric value for a given channel |
+| `withChannelValue(channel, value)` | Sets the numeric value for a channel and returns a new Color |
+
+#### parseColor
+
+```tsx
+import { parseColor } from 'react-aria-components';
+
+// Parse from string
+const color = parseColor('#ff0000');
+const hslColor = parseColor('hsl(0, 100%, 50%)');
+```
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-slider.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-slider.mdx
new file mode 100644
index 0000000..61c32e6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-slider.mdx
@@ -0,0 +1,231 @@
+---
+title: ColorSlider
+description: A color slider allows users to adjust an individual channel of a color value
+links:
+  rac: ColorSlider
+  source: color-slider/color-slider.tsx
+  styles: color-slider.css
+  storybook: Components/Colors/ColorSlider
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="color-slider-basic"
+/>
+
+### Anatomy
+
+Import the ColorSlider component and access all parts using dot notation.
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+
+export default () => (
+  <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)">
+    <Label>Hue</Label>
+    <ColorSlider.Output />
+    <ColorSlider.Track>
+      <ColorSlider.Thumb />
+    </ColorSlider.Track>
+  </ColorSlider>
+)
+```
+### Vertical
+
+<ComponentPreview
+  name="color-slider-vertical"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="color-slider-disabled"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="color-slider-controlled"
+/>
+
+### HSL Channels
+
+Use multiple ColorSliders to control different channels of a color value. The sliders can share the same color value to create a complete color picker.
+
+<ComponentPreview
+  name="color-slider-channels"
+/>
+
+### Alpha Channel
+
+The alpha channel slider shows a transparency checkerboard pattern to help visualize the transparency level.
+
+<ComponentPreview
+  name="color-slider-alpha-channel"
+/>
+
+### RGB Channels
+
+You can also use RGB color space with red, green, and blue channels.
+
+<ComponentPreview
+  name="color-slider-rgb-channels"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="color-slider-custom-render-function"
+/>
+
+<RelatedComponents component="color-slider" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ColorSlider, Label } from '@heroui/react';
+
+function CustomColorSlider() {
+  return (
+    <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" className="w-full">
+      <Label>Hue</Label>
+      <ColorSlider.Output className="text-muted text-sm" />
+      <ColorSlider.Track className="h-6 rounded-full">
+        <ColorSlider.Thumb className="size-5 rounded-full border-2 border-white" />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ColorSlider component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-slider {
+    @apply flex flex-col gap-2;
+  }
+
+  .color-slider__output {
+    @apply text-muted text-sm;
+  }
+
+  .color-slider__track {
+    @apply relative h-5 w-full rounded-full;
+  }
+
+  .color-slider__thumb {
+    @apply size-4 rounded-full border-3 border-white shadow-overlay;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ColorSlider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)):
+
+#### Base Classes
+- `.color-slider` - Base slider container
+- `.color-slider__output` - Output element displaying current value
+- `.color-slider__track` - Track element with color gradient
+- `.color-slider__thumb` - Thumb element showing current color
+
+#### State Classes
+- `.color-slider[data-disabled="true"]` - Disabled slider state
+- `.color-slider[data-orientation="vertical"]` - Vertical orientation
+- `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
+- `.color-slider__thumb[data-focus-visible="true"]` - Thumb keyboard focused
+- `.color-slider__thumb[data-disabled="true"]` - Disabled thumb state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on thumb
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
+- **Dragging**: `[data-dragging="true"]` on thumb
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
+
+## API Reference
+
+### ColorSlider Props
+
+Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `channel` | `ColorChannel` | - | The color channel that the slider manipulates (hue, saturation, lightness, brightness, alpha, red, green, blue) |
+| `colorSpace` | `ColorSpace` | - | The color space (hsl, hsb, rgb). Defaults to the color space of the value |
+| `value` | `string \| Color` | - | The current color value (controlled) |
+| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
+| `onChange` | `(value: Color) => void` | - | Handler called when the value changes during dragging |
+| `onChangeEnd` | `(value: Color) => void` | - | Handler called when dragging ends |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
+| `isDisabled` | `boolean` | - | Whether the slider is disabled |
+| `name` | `string` | - | The name of the input element for form submission |
+| `aria-label` | `string` | - | Accessibility label for the slider |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ColorSlider.Output Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
+
+### ColorSlider.Track Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
+| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
+
+### ColorSlider.Thumb Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
+| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
+
+### RenderProps
+
+When using render functions, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `state` | `ColorSliderState` | The state of the color slider |
+| `color` | `Color` | The current color value |
+| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
+| `isDisabled` | `boolean` | Whether the slider is disabled |
+
+## Accessibility
+
+The ColorSlider component implements the ARIA slider pattern and provides:
+
+- Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
+- Screen reader announcements for value changes
+- Proper focus management
+- Support for disabled states
+- HTML form integration via hidden input elements
+- Internationalization support with locale-aware value formatting
+
+For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-swatch-picker.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-swatch-picker.mdx
new file mode 100644
index 0000000..dbd1b14
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-swatch-picker.mdx
@@ -0,0 +1,228 @@
+---
+title: ColorSwatchPicker
+description: A list of color swatches that allows users to select a color from a predefined palette.
+links:
+  rac: ColorSwatchPicker
+  source: color-swatch-picker/color-swatch-picker.tsx
+  styles: color-swatch-picker.css
+  storybook: Components/Colors/ColorSwatchPicker
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ColorSwatchPicker, parseColor } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="color-swatch-picker-basic"
+/>
+
+### Anatomy
+
+Import the ColorSwatchPicker component and access all parts using dot notation.
+
+```tsx
+import { ColorSwatchPicker } from '@heroui/react';
+
+export default () => (
+  <ColorSwatchPicker>
+    <ColorSwatchPicker.Item color="#F43F5E">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+    <ColorSwatchPicker.Item color="#D946EF">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+    <ColorSwatchPicker.Item color="#8B5CF6">
+      <ColorSwatchPicker.Swatch />
+      <ColorSwatchPicker.Indicator />
+    </ColorSwatchPicker.Item>
+  </ColorSwatchPicker>
+);
+```
+
+### Variants
+
+<ComponentPreview
+  name="color-swatch-picker-variants"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="color-swatch-picker-sizes"
+/>
+
+### Stack Layout
+
+<ComponentPreview
+  name="color-swatch-picker-stack-layout"
+/>
+
+### Default Value
+
+<ComponentPreview
+  name="color-swatch-picker-default-value"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="color-swatch-picker-controlled"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="color-swatch-picker-disabled"
+/>
+
+### Custom Indicator
+
+<ComponentPreview
+  name="color-swatch-picker-custom-indicator"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="color-swatch-picker-custom-render-function"
+/>
+
+<RelatedComponents component="color-swatch-picker" />
+
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize the ColorSwatchPicker using className props:
+
+```tsx
+import { ColorSwatchPicker } from '@heroui/react';
+
+function CustomColorSwatchPicker() {
+  return (
+    <ColorSwatchPicker className="gap-4">
+      <ColorSwatchPicker.Item color="#F43F5E" className="shadow-lg">
+        <ColorSwatchPicker.Swatch />
+      </ColorSwatchPicker.Item>
+      <ColorSwatchPicker.Item color="#D946EF">
+        <ColorSwatchPicker.Swatch />
+      </ColorSwatchPicker.Item>
+    </ColorSwatchPicker>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ColorSwatchPicker component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-swatch-picker {
+    @apply gap-4;
+  }
+
+  .color-swatch-picker__item {
+    @apply shadow-md;
+  }
+
+  .color-swatch-picker__swatch {
+    @apply border-2 border-white;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ColorSwatchPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)):
+
+#### Base & Structure
+- `.color-swatch-picker` - Base container (flex layout)
+- `.color-swatch-picker__item` - Individual swatch item wrapper
+- `.color-swatch-picker__swatch` - The color swatch visual element
+
+#### Size Classes
+- `.color-swatch-picker--xs` - Extra small (16px)
+- `.color-swatch-picker--sm` - Small (24px)
+- `.color-swatch-picker--md` - Medium (32px, default)
+- `.color-swatch-picker--lg` - Large (36px)
+- `.color-swatch-picker--xl` - Extra large (40px)
+
+#### Shape Variants
+- `.color-swatch-picker--circle` - Circle shape (default)
+- `.color-swatch-picker--square` - Square shape with rounded corners
+
+#### Layout Classes
+- `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
+- `.color-swatch-picker--stack` - Vertical stacked layout
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` - Scale up to 1.1 (only when not selected)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Focus ring
+- **Selected**: `[data-selected="true"]` - Inner border with same color as swatch
+- **Disabled**: `[data-disabled="true"]` - Reduced opacity
+
+## API Reference
+
+### ColorSwatchPicker Props
+
+Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| Color` | - | The current selected color (controlled) |
+| `defaultValue` | `string \| Color` | - | The default selected color (uncontrolled) |
+| `onChange` | `(value: Color) => void` | - | Handler called when selection changes |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatches |
+| `variant` | `"circle" \| "square"` | `"circle"` | Shape of the swatches |
+| `layout` | `"grid" \| "stack"` | `"grid"` | Layout direction |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | ColorSwatchPicker.Item elements |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ColorSwatchPicker.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string \| Color` | **Required** | The color of the swatch |
+| `isDisabled` | `boolean` | `false` | Whether the item is disabled |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch element |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ColorSwatchPicker.Swatch Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+### parseColor
+
+The `parseColor` function is re-exported from React Aria Components for convenience:
+
+```tsx
+import { parseColor } from '@heroui/react';
+
+// Parse hex color
+const red = parseColor('#ff0000');
+
+// Parse RGB
+const green = parseColor('rgb(0, 255, 0)');
+
+// Parse HSL
+const blue = parseColor('hsl(240, 100%, 50%)');
+```
diff --git a/apps/docs/content/docs/en/react/components/(colors)/color-swatch.mdx b/apps/docs/content/docs/en/react/components/(colors)/color-swatch.mdx
new file mode 100644
index 0000000..2550c98
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(colors)/color-swatch.mdx
@@ -0,0 +1,146 @@
+---
+title: ColorSwatch
+description: A visual preview of a color value with accessibility support
+links:
+  rac: ColorSwatch
+  source: color-swatch/color-swatch.tsx
+  styles: color-swatch.css
+  storybook: Components/Colors/ColorSwatch
+---
+
+## Import
+
+```tsx
+import { ColorSwatch } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="color-swatch-basic"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="color-swatch-sizes"
+/>
+
+### Shapes
+
+<ComponentPreview
+  name="color-swatch-shapes"
+/>
+
+### Transparency
+
+<ComponentPreview
+  name="color-swatch-transparency"
+/>
+
+### Custom Styles with Render Props
+
+You can use the `style` render props to access the color value and create custom visual effects.
+
+<ComponentPreview
+  name="color-swatch-custom-styles"
+/>
+
+### Accessibility
+
+Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.
+
+<ComponentPreview
+  name="color-swatch-accessibility"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="color-swatch-custom-render-function"
+/>
+
+<RelatedComponents component="color-swatch" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {ColorSwatch} from '@heroui/react';
+
+function CustomColorSwatch() {
+  return (
+    <ColorSwatch
+      className="size-12 rounded-lg"
+      color="#0485F7"
+    />
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ColorSwatch component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .color-swatch {
+    @apply border-2 border-white;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ColorSwatch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)):
+
+#### Base Classes
+- `.color-swatch` - Base swatch styles with checkered background for transparency
+
+#### Shape Classes
+- `.color-swatch--circle` - Circular shape (default)
+- `.color-swatch--square` - Square shape with rounded corners
+
+#### Size Classes
+- `.color-swatch--xs` - Extra small (16px)
+- `.color-swatch--sm` - Small (24px)
+- `.color-swatch--md` - Medium (32px, default)
+- `.color-swatch--lg` - Large (36px)
+- `.color-swatch--xl` - Extra large (40px)
+
+## API Reference
+
+### ColorSwatch Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string \| Color` | - | The color value to display (hex, rgb, hsl, etc.) |
+| `colorName` | `string` | - | Accessible name for the color (overrides auto-generated description) |
+| `className` | `string` | - | Additional CSS classes |
+| `shape` | `"circle" \| "square"` | `"circle"` | Shape of the swatch |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatch |
+| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function with access to color |
+| `aria-label` | `string` | - | Accessible label for the swatch |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Style Render Props
+
+When using the `style` prop as a function, you receive render props with access to the color:
+
+```tsx
+<ColorSwatch
+  color="#0485F7"
+  style={({ color }) => ({
+    boxShadow: `0 4px 14px ${color.toString("css")}80`,
+  })}
+/>
+```
+
+The `color` object provides methods like:
+- `color.toString("css")` - Returns CSS color string
+- `color.toString("hex")` - Returns hex color string
+- `color.getChannelValue("alpha")` - Returns alpha channel value
diff --git a/apps/docs/content/docs/en/react/components/(controls)/slider.mdx b/apps/docs/content/docs/en/react/components/(controls)/slider.mdx
new file mode 100644
index 0000000..ab52eab
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(controls)/slider.mdx
@@ -0,0 +1,380 @@
+---
+title: Slider
+description: A slider allows a user to select one or more values within a range
+links:
+  rac: Slider
+  source: slider/slider.tsx
+  styles: slider.css
+  storybook: Components/Controls/Slider
+---
+
+## Import
+
+```tsx
+import { Slider } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="slider-default"
+/>
+
+### Anatomy
+
+Import the Slider component and access all parts using dot notation.
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+export default () => (
+  <Slider>
+    <Label />
+    <Slider.Output />
+    <Slider.Track>
+      <Slider.Fill />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider>
+)
+```
+
+### Range Slider Anatomy
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+export default () => (
+  <Slider defaultValue={[25, 75]}>
+    <Label />
+    <Slider.Output />
+    <Slider.Track>
+      {({state}) => (
+        <>
+          <Slider.Fill />
+          {state.values.map((_, i) => (
+            <Slider.Thumb key={i} index={i} />
+          ))}
+        </>
+      )}
+    </Slider.Track>
+  </Slider>
+)
+```
+
+### Vertical
+
+<ComponentPreview
+  name="slider-vertical"
+/>
+
+### Range
+
+<ComponentPreview
+  name="slider-range"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="slider-disabled"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="slider-custom-render-function"
+/>
+
+<RelatedComponents component="slider" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+function CustomSlider() {
+  return (
+    <Slider className="w-full">
+      <Label>Volume</Label>
+      <Slider.Output className="text-muted-fg text-sm" />
+      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
+        <Slider.Fill className="bg-accent" />
+        <Slider.Thumb className="size-4 rounded-full bg-accent" />
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Slider component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .slider {
+    @apply flex flex-col gap-2;
+  }
+
+  .slider__output {
+    @apply text-muted-fg text-sm;
+  }
+
+  .slider-track {
+    @apply relative h-2 w-full rounded-full bg-surface-secondary;
+  }
+
+  .slider-fill {
+    @apply absolute h-full rounded-full bg-accent;
+  }
+
+  .slider-thumb {
+    @apply size-4 rounded-full bg-accent border-2 border-background;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)):
+
+#### Base Classes
+- `.slider` - Base slider container
+- `.slider__output` - Output element displaying current value(s)
+- `.slider-track` - Track element containing fill and thumbs
+- `.slider-fill` - Fill element showing selected range
+- `.slider-thumb` - Individual thumb element
+
+#### State Classes
+- `.slider[data-disabled="true"]` - Disabled slider state
+- `.slider[data-orientation="vertical"]` - Vertical orientation
+- `.slider-thumb[data-dragging="true"]` - Thumb being dragged
+- `.slider-thumb[data-focus-visible="true"]` - Thumb keyboard focused
+- `.slider-thumb[data-disabled="true"]` - Disabled thumb state
+- `.slider-track[data-fill-start="true"]` - Fill starts at beginning
+- `.slider-track[data-fill-end="true"]` - Fill ends at end
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on thumb
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
+- **Dragging**: `[data-dragging="true"]` on thumb
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
+
+## API Reference
+
+### Slider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number \| number[]` | - | The current value (controlled) |
+| `defaultValue` | `number \| number[]` | - | The default value (uncontrolled) |
+| `onChange` | `(value: number \| number[]) => void` | - | Handler called when the value changes |
+| `onChangeEnd` | `(value: number \| number[]) => void` | - | Handler called when dragging ends |
+| `minValue` | `number` | `0` | The slider's minimum value |
+| `maxValue` | `number` | `100` | The slider's maximum value |
+| `step` | `number` | `1` | The slider's step value |
+| `formatOptions` | `Intl.NumberFormatOptions` | - | The display format of the value label |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
+| `isDisabled` | `boolean` | - | Whether the slider is disabled |
+| `aria-label` | `string` | - | Accessibility label for the slider |
+| `aria-labelledby` | `string` | - | ID of element that labels the slider |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Slider.Output Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Slider.Track Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Slider.Fill Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `style` | `CSSProperties` | - | Inline styles |
+
+### Slider.Thumb Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `index` | `number` | `0` | Index of the thumb within the slider |
+| `isDisabled` | `boolean` | - | Whether this thumb is disabled |
+| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### RenderProps
+
+When using render functions with Slider.Output or Slider.Track, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `state` | `SliderState` | The state of the slider |
+| `values` | `number[]` | Values managed by the slider by thumb index |
+| `getThumbValueLabel` | `(index: number) => string` | Returns the string label for the specified thumb's value |
+| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
+| `isDisabled` | `boolean` | Whether the slider is disabled |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={30}>
+  <Label>Volume</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### Range Slider
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider
+  defaultValue={[100, 500]}
+  formatOptions={{style: "currency", currency: "USD"}}
+  maxValue={1000}
+  minValue={0}
+  step={50}
+>
+  <Label>Price Range</Label>
+  <Slider.Output />
+  <Slider.Track>
+    {({state}) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+### Controlled Value
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledSlider() {
+  const [value, setValue] = useState(25);
+
+  return (
+    <>
+      <Slider value={value} onChange={setValue}>
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+      <p>Current value: {value}</p>
+    </>
+  );
+}
+```
+
+### Custom Value Formatting
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider
+  defaultValue={60}
+  formatOptions={{style: "currency", currency: "USD"}}
+>
+  <Label>Price</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### Vertical Orientation
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={30} orientation="vertical" aria-label="Volume">
+  <Label>Volume</Label>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### Custom Output Display
+
+```tsx
+import { Slider, Label } from '@heroui/react';
+
+<Slider defaultValue={[25, 75]}>
+  <Label>Range</Label>
+  <Slider.Output>
+    {({state}) =>
+      state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ')
+    }
+  </Slider.Output>
+  <Slider.Track>
+    {({state}) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+## Accessibility
+
+The Slider component implements the ARIA slider pattern and provides:
+
+- Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
+- Screen reader announcements for value changes
+- Proper focus management
+- Support for disabled states
+- HTML form integration via hidden input elements
+- Internationalization support with locale-aware value formatting
+- Right-to-left (RTL) language support
+
+For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html).
+
diff --git a/apps/docs/content/docs/en/react/components/(controls)/switch.mdx b/apps/docs/content/docs/en/react/components/(controls)/switch.mdx
new file mode 100644
index 0000000..366eb23
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(controls)/switch.mdx
@@ -0,0 +1,340 @@
+---
+title: Switch
+description: A toggle switch component for boolean states
+icon: updated
+links:
+  rac: SwitchField
+  source: switch/switch.tsx
+  styles: switch.css
+  storybook: Components/Controls/Switch
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="switch-basic"
+/>
+
+### Anatomy
+
+Import the Switch component and access all parts using dot notation.
+
+```tsx
+import { Switch, Description, FieldError } from '@heroui/react';
+
+export default () => (
+  <Switch>
+    <Switch.Content>
+      <Switch.Control>
+        <Switch.Thumb>
+          <Switch.Icon /> {/* Optional */}
+        </Switch.Thumb>
+      </Switch.Control>
+      Label {/* plain text — the clickable label + accessible name */}
+    </Switch.Content>
+    <Description /> {/* Optional — field-level help text */}
+    <FieldError /> {/* Optional — validation message */}
+  </Switch>
+);
+```
+
+For grouping multiple switches, use the `SwitchGroup` component:
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+
+export default () => (
+  <SwitchGroup>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Option 1
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Option 2
+      </Switch.Content>
+    </Switch>
+  </SwitchGroup>
+);
+```
+
+### Disabled
+
+<ComponentPreview
+  name="switch-disabled"
+/>
+
+### Default Selected
+
+<ComponentPreview
+  name="switch-default-selected"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="switch-controlled"
+/>
+
+### Without Label
+
+<ComponentPreview
+  name="switch-without-label"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="switch-sizes"
+/>
+
+### Label Position
+
+<ComponentPreview
+  name="switch-label-position"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="switch-with-icons"
+/>
+
+### With Description
+
+<ComponentPreview
+  name="switch-with-description"
+/>
+
+### Group
+
+<ComponentPreview
+  name="switch-group"
+/>
+
+### Group Horizontal
+
+<ComponentPreview
+  name="switch-group-horizontal"
+/>
+
+### Render Props
+
+<ComponentPreview
+  name="switch-render-props"
+/>
+
+### Form Integration
+
+<ComponentPreview
+  name="switch-form"
+/>
+
+### Custom Styles
+
+<ComponentPreview
+  name="switch-custom-styles"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="switch-custom-render-function"
+/>
+
+<RelatedComponents component="switch" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual Switch components:
+
+```tsx
+import { Switch, Label } from '@heroui/react';
+
+function CustomSwitch() {
+  return (
+    <Switch>
+      {({isSelected}) => (
+        <>
+          <Switch.Control
+            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
+          >
+            <Switch.Thumb
+              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
+            />
+          </Switch.Control>
+          Custom Switch
+        </>
+      )}
+    </Switch>
+  );
+}
+```
+
+Or customize the SwitchGroup layout:
+
+```tsx
+import { Switch, SwitchGroup, Label } from '@heroui/react';
+
+function CustomSwitchGroup() {
+  return (
+    <SwitchGroup className="gap-8" orientation="horizontal">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Option 1
+        </Switch.Content>
+      </Switch>
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Option 2
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Switch component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .switch {
+    @apply inline-flex gap-3 items-center;
+  }
+
+  .switch__control {
+    @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
+  }
+
+  .switch__thumb {
+    @apply bg-white shadow-sm;
+  }
+
+  .switch__content {
+    @apply items-center gap-3;
+  }
+
+  .switch__icon {
+    @apply h-3 w-3 text-current;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+#### Switch Classes
+
+The Switch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)):
+
+- `.switch` - Base switch container (the field)
+- `.switch__content` - Clickable label wrapping the control and label text
+- `.switch__control` - Switch control track
+- `.switch__thumb` - Switch thumb that moves
+- `.switch__icon` - Optional icon inside the thumb
+- `.switch--sm` - Small size variant
+- `.switch--md` - Medium size variant (default)
+- `.switch--lg` - Large size variant
+
+#### SwitchGroup Classes
+
+The SwitchGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)):
+
+- `.switch-group` - Switch group container
+- `.switch-group__items` - Container for switch items
+- `.switch-group--horizontal` - Horizontal layout
+- `.switch-group--vertical` - Vertical layout (default)
+
+### Interactive States
+
+The switch supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Selected**: `[data-selected="true"]` (thumb position and background color change)
+- **Hover**: `:hover` or `[data-hovered="true"]` on `Switch.Control` (button)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on track)
+- **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text)
+- **Pressed**: `:active` or `[data-pressed="true"]`
+
+## API Reference
+
+### Switch Props
+
+Inherits from [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the switch |
+| `isSelected` | `boolean` | `false` | Whether the switch is on |
+| `defaultSelected` | `boolean` | `false` | Whether the switch is on by default (uncontrolled) |
+| `isDisabled` | `boolean` | `false` | Whether the switch is disabled |
+| `isInvalid` | `boolean` | `false` | Whether the switch is invalid |
+| `isReadOnly` | `boolean` | `false` | Whether the switch is read only |
+| `isRequired` | `boolean` | `false` | Whether the switch must be selected |
+| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | Custom validation function |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA |
+| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
+| `value` | `string` | - | The value of the input element, used when submitting an HTML form |
+| `onChange` | `(isSelected: boolean) => void` | - | Handler called when the switch value changes |
+| `onPress` | `(e: PressEvent) => void` | - | Handler called when the switch is pressed |
+| `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch content or field render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Switch.Content Props
+
+The clickable `<label>` that wraps the control and label text. Put `Switch.Control` and the `Label` inside it; keep `Description`/`FieldError` as siblings of `Switch.Content`. For a switch with no label, omit the `Label` and pass an `aria-label` on `Switch`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: SwitchButtonRenderProps) => React.ReactNode` | - | Button content (control + label), or a button render prop |
+| `className` | `string \| (values: SwitchButtonRenderProps) => string` | - | Classes applied to the clickable label |
+
+### SwitchFieldRenderProps
+
+When using a render prop on the root `Switch`, these field-level values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the switch is currently on |
+| `isDisabled` | `boolean` | Whether the switch is disabled |
+| `isReadOnly` | `boolean` | Whether the switch is read only |
+| `isInvalid` | `boolean` | Whether the switch is invalid |
+| `isRequired` | `boolean` | Whether the switch is required |
+| `state` | `ToggleState` | State of the switch |
+
+### SwitchButtonRenderProps
+
+`Switch.Control` uses button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Switch.Control` children to access them.
+
+### SwitchGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the switch group |
+| `children` | `React.ReactNode` | - | The switch items to render |
+| `className` | `string` | - | Additional CSS class names |
diff --git a/apps/docs/content/docs/en/react/components/(data-display)/badge.mdx b/apps/docs/content/docs/en/react/components/(data-display)/badge.mdx
new file mode 100644
index 0000000..836960c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(data-display)/badge.mdx
@@ -0,0 +1,197 @@
+---
+title: Badge
+description: Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels
+links:
+  source: badge/badge.tsx
+  styles: badge.css
+  storybook: Components/Data Display/Badge
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Badge } from '@heroui/react';
+```
+
+## Anatomy
+
+Badge is designed to be positioned relative to another element using `Badge.Anchor`. Plain-text children are automatically wrapped in `<Badge.Label>`.
+
+> For standalone label usage, use the [Chip](/docs/react/components/chip) component instead.
+
+```tsx
+<Badge.Anchor>
+  <Avatar />
+  <Badge color="danger">5</Badge>
+</Badge.Anchor>
+```
+
+### Usage
+
+<ComponentPreview
+  name="badge-basic"
+/>
+
+### Colors
+
+<ComponentPreview
+  name="badge-colors"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="badge-sizes"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="badge-variants"
+/>
+
+### Placements
+
+<ComponentPreview
+  name="badge-placements"
+/>
+
+### With Content
+
+Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.
+
+<ComponentPreview
+  name="badge-with-content"
+/>
+
+### Dot Badge
+
+Empty badges act as status indicators — useful for online/offline states or activity signals.
+
+<ComponentPreview
+  name="badge-dot"
+/>
+
+<RelatedComponents component="badge" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can style the root container and individual slots:
+
+```tsx
+import {Badge, Avatar} from '@heroui/react';
+
+function CustomBadge() {
+  return (
+    <Badge.Anchor>
+      <Avatar />
+      <Badge className="border-2 border-white" color="danger">
+        <Badge.Label className="font-bold">99+</Badge.Label>
+      </Badge>
+    </Badge.Anchor>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Badge component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .badge {
+    @apply rounded-full text-xs;
+  }
+
+  .badge__label {
+    @apply font-semibold;
+  }
+
+  .badge--accent {
+    @apply shadow-sm;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Badge component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)):
+
+#### Base Classes
+- `.badge` - Base badge container styles
+- `.badge__label` - Label text slot styles
+- `.badge-anchor` - Positioning wrapper for the anchored element
+
+#### Color Classes
+- `.badge--accent` - Accent color variant
+- `.badge--danger` - Danger color variant
+- `.badge--default` - Default color variant
+- `.badge--success` - Success color variant
+- `.badge--warning` - Warning color variant
+
+#### Variant Classes
+- `.badge--primary` - Primary variant with filled background
+- `.badge--secondary` - Secondary variant with default background
+- `.badge--soft` - Soft variant with lighter background
+
+#### Size Classes
+- `.badge--sm` - Small size
+- `.badge--md` - Medium size (default)
+- `.badge--lg` - Large size
+
+#### Placement Classes
+- `.badge--top-right` - Position at top-right corner (default)
+- `.badge--top-left` - Position at top-left corner
+- `.badge--bottom-right` - Position at bottom-right corner
+- `.badge--bottom-left` - Position at bottom-left corner
+
+#### Compound Variant Classes
+
+Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:
+
+**Primary Variants:**
+- `.badge--primary.badge--accent` - Primary accent with filled background
+- `.badge--primary.badge--default` - Primary default with filled background
+- `.badge--primary.badge--success` - Primary success with filled background
+- `.badge--primary.badge--warning` - Primary warning with filled background
+- `.badge--primary.badge--danger` - Primary danger with filled background
+
+**Soft Variants:**
+- `.badge--soft.badge--accent` - Soft accent with lighter background
+- `.badge--soft.badge--default` - Soft default with lighter background
+- `.badge--soft.badge--success` - Soft success with lighter background
+- `.badge--soft.badge--warning` - Soft warning with lighter background
+- `.badge--soft.badge--danger` - Soft danger with lighter background
+
+## API Reference
+
+### Badge Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display inside the badge (text, number, or icon). When omitted, renders as a dot. |
+| `className` | `string` | - | Additional CSS classes for the root element |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the badge |
+| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | Visual style variant |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
+| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |
+
+### Badge.Anchor Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
+| `className` | `string` | - | Additional CSS classes for the anchor wrapper |
+
+### Badge.Label Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Label text content |
+| `className` | `string` | - | Additional CSS classes for the label slot |
diff --git a/apps/docs/content/docs/en/react/components/(data-display)/chip.mdx b/apps/docs/content/docs/en/react/components/(data-display)/chip.mdx
new file mode 100644
index 0000000..f38d34b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(data-display)/chip.mdx
@@ -0,0 +1,163 @@
+---
+title: Chip
+description: Small informational badges for displaying labels, statuses, and categories
+links:
+  source: chip/chip.tsx
+  styles: chip.css
+  storybook: Components/Data Display/Chip
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Chip } from '@heroui/react';
+```
+
+## Anatomy
+
+Import the Chip component and access all parts using dot notation.
+
+> Plain-text children are automatically wrapped in `<Chip.Label>`.
+
+```tsx
+<Chip>
+  Label text
+</Chip>
+```
+
+### Usage
+
+<ComponentPreview
+  name="chip-basic"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="chip-variants"
+/>
+
+### With Icons
+
+<ComponentPreview
+  name="chip-with-icon"
+/>
+
+### Statuses
+
+<ComponentPreview
+  name="chip-statuses"
+/>
+
+<RelatedComponents component="chip" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can style the root container and individual slots:
+
+```tsx
+import {Chip} from '@heroui/react';
+
+function CustomChip() {
+  return (
+    <Chip className="rounded-full px-4 py-2 font-bold">
+      <Chip.Label className="text-lg uppercase">
+        Custom Styled
+      </Chip.Label>
+    </Chip>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Chip component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .chip {
+    @apply rounded-full text-xs;
+  }
+
+  .chip__label {
+    @apply font-medium;
+  }
+
+  .chip--accent {
+    @apply border-accent/20;
+  }
+
+  .chip--accent .chip__label {
+    @apply text-accent;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Chip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)):
+
+#### Base Classes
+- `.chip` - Base chip container styles
+- `.chip__label` - Label text slot styles
+
+#### Color Classes
+- `.chip--accent` - Accent color variant
+- `.chip--danger` - Danger color variant
+- `.chip--default` - Default color variant
+- `.chip--success` - Success color variant
+- `.chip--warning` - Warning color variant
+
+#### Variant Classes
+- `.chip--primary` - Primary variant with filled background
+- `.chip--secondary` - Secondary variant with border
+- `.chip--tertiary` - Tertiary variant with transparent background
+- `.chip--soft` - Soft variant with lighter background
+
+#### Size Classes
+- `.chip--sm` - Small size
+- `.chip--md` - Medium size (default)
+- `.chip--lg` - Large size
+
+#### Compound Variant Classes
+
+Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:
+
+**Primary Variants:**
+- `.chip--primary.chip--accent` - Primary accent combination with filled background
+- `.chip--primary.chip--success` - Primary success combination with filled background
+- `.chip--primary.chip--warning` - Primary warning combination with filled background
+- `.chip--primary.chip--danger` - Primary danger combination with filled background
+
+**Soft Variants:**
+- `.chip--accent.chip--soft` - Soft accent combination with lighter background
+- `.chip--success.chip--soft` - Soft success combination with lighter background
+- `.chip--warning.chip--soft` - Soft warning combination with lighter background
+- `.chip--danger.chip--soft` - Soft danger combination with lighter background
+
+**Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS.
+
+## API Reference
+
+### Chip Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display inside the chip |
+| `className` | `string` | - | Additional CSS classes for the root element |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the chip |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip |
+
+### Chip.Label Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Label text content |
+| `className` | `string` | - | Additional CSS classes for the label slot |
diff --git a/apps/docs/content/docs/en/react/components/(data-display)/table.mdx b/apps/docs/content/docs/en/react/components/(data-display)/table.mdx
new file mode 100644
index 0000000..db506fa
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(data-display)/table.mdx
@@ -0,0 +1,418 @@
+---
+title: Table
+description: Tables display structured data in rows and columns with support for sorting, selection, column resizing, and infinite scrolling.
+icon: updated
+links:
+  rac: Table
+  source: table/table.tsx
+  styles: table.css
+  storybook: Components/Data Display/Table
+---
+
+## Import
+
+```tsx
+import { Table } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="table-basic"
+  minHeight="320px"
+/>
+
+### Anatomy
+
+Import the Table component and access all parts using dot notation.
+
+```tsx
+import { Table } from '@heroui/react';
+
+export default () => (
+  <Table>
+    <Table.ScrollContainer>
+      <Table.Content aria-label="Example table">
+        <Table.Header>
+          <Table.Column allowsSorting>
+            {({ sortDirection }) => (
+              <Table.SortableColumnHeader sortDirection={sortDirection}>
+                Name
+              </Table.SortableColumnHeader>
+            )}
+          </Table.Column>
+          <Table.Column>Role</Table.Column>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>Kate Moore</Table.Cell>
+            <Table.Cell>CEO</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Content>
+    </Table.ScrollContainer>
+    <Table.Footer>{/* Optional footer content */}</Table.Footer>
+  </Table>
+);
+```
+
+### Secondary Variant
+
+<ComponentPreview
+  name="table-secondary-variant"
+  minHeight="320px"
+/>
+
+### Sorting
+
+Columns can be made sortable using the `allowsSorting` prop on `Table.Column`. Use `sortDescriptor` and `onSortChange` on `Table.Content` to manage sort state. Wrap the label in `Table.SortableColumnHeader` and forward the `sortDirection` from the column's render prop to render the default ascending/descending indicator.
+
+<ComponentPreview
+  name="table-sorting"
+  minHeight="380px"
+/>
+
+### Selection
+
+Enable row selection with `selectionMode` on `Table.Content`. Use `Checkbox` with `slot="selection"` for select-all and per-row checkboxes.
+
+<ComponentPreview
+  name="table-selection"
+  minHeight="380px"
+/>
+
+### Custom Cells
+
+<ComponentPreview
+  name="table-custom-cells"
+  minHeight="420px"
+/>
+
+### Expandable Rows
+
+Rows can be nested to display hierarchical data. Use the `treeColumn` prop to designate a column, and render a `Button` with `slot="chevron"` in that column’s cells so users can expand and collapse the row. Use the `expandedKeys` prop to control which rows are expanded.
+
+<ComponentPreview
+  name="table-expandable-rows"
+  minHeight="420px"
+/>
+
+### Pagination
+
+Use `Table.Footer` to add a pagination component below the table.
+
+<ComponentPreview
+  name="table-pagination"
+  minHeight="400px"
+/>
+
+### Column Resizing
+
+Wrap the table in `Table.ResizableContainer` and add `Table.ColumnResizer` inside each resizable column.
+
+<ComponentPreview
+  name="table-column-resizing"
+  minHeight="420px"
+/>
+
+### Empty State
+
+Use `renderEmptyState` on `Table.Body` to display a custom message when the table has no data.
+
+<ComponentPreview
+  name="table-empty-state"
+  minHeight="300px"
+/>
+
+### Async Loading
+
+Use `Table.LoadMore` for infinite scrolling. It renders a sentinel row that triggers `onLoadMore` when scrolled into view.
+
+<ComponentPreview
+  name="table-async-loading"
+  minHeight="380px"
+/>
+
+### Virtualization
+
+Table supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
+
+<ComponentPreview
+  name="table-virtualization"
+  minHeight="380px"
+/>
+
+### TanStack Table
+
+HeroUI's Table works as a rendering layer on top of headless table libraries.
+This example uses [TanStack Table](https://tanstack.com/table) for column
+definitions, sorting, and pagination — while HeroUI handles styling and
+accessibility.
+
+<ComponentPreview
+  name="table-tanstack-table"
+  minHeight="420px"
+/>
+
+<RelatedComponents component="table" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual Table parts:
+
+```tsx
+import { Table } from '@heroui/react';
+
+function CustomTable() {
+  return (
+    <Table className="border border-purple-200">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Custom styled table">
+          <Table.Header className="bg-purple-50">
+            <Table.Column>Name</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row className="hover:bg-purple-50">
+              <Table.Cell>Kate Moore</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Table component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .table-root {
+    @apply relative grid w-full overflow-clip;
+  }
+
+  .table__header {
+    @apply bg-gray-100;
+  }
+
+  .table__column {
+    @apply px-4 py-2.5 text-left text-xs font-medium text-gray-600;
+  }
+
+  .table__row {
+    @apply bg-white border-b border-gray-200;
+  }
+
+  .table__cell {
+    @apply px-4 py-3 text-sm;
+  }
+
+  .table__footer {
+    @apply flex items-center px-4 py-2.5;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Table component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/table.css)):
+
+#### Base Classes
+- `.table-root` - Root container (named `table-root` instead of `table` because `table` is a built-in Tailwind CSS utility class for `display: table`)
+- `.table__scroll-container` - Horizontal scroll wrapper with custom scrollbar
+- `.table__content` - The `<table>` element
+- `.table__header` - Header row (`<thead>`)
+- `.table__column` - Column header cell (`<th>`)
+- `.table__body` - Body section (`<tbody>`)
+- `.table__row` - Row element (`<tr>`)
+- `.table__cell` - Data cell (`<td>`)
+- `.table__footer` - Footer container (outside table)
+
+#### Advanced Classes
+- `.table__column-resizer` - Drag handle for column resizing
+- `.table__resizable-container` - Wrapper enabling column resizing
+- `.table__load-more` - Sentinel row for infinite scrolling
+- `.table__load-more-content` - Styled container for the loading indicator
+- `.table__sortable-column-header` - Sortable column label + indicator wrapper
+- `.table__sortable-column-indicator` - Sort direction chevron (rotates via `[data-direction="descending"]`)
+
+#### Variant Classes
+- `.table-root--primary` - Gray background container with card-style body (default)
+- `.table-root--secondary` - No background, standalone rounded headers
+
+### Interactive States
+
+The Table supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` (row background change)
+- **Selected**: `[data-selected="true"]` (row highlight)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (inset focus ring on rows, columns, and cells)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity)
+- **Sortable**: `[data-allows-sorting="true"]` (interactive cursor on columns)
+- **Dragging**: `[data-dragging="true"]` (reduced opacity)
+- **Drop Target**: `[data-drop-target="true"]` (accent background)
+
+## API Reference
+
+### Table Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant. Primary has a gray background container; secondary is flat with transparent rows. |
+| `className` | `string` | - | Additional CSS classes for the root container |
+| `children` | `React.ReactNode` | - | Table content (ScrollContainer, Footer, etc.) |
+
+### Table.ScrollContainer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Table.Content element |
+
+### Table.Content Props
+
+Inherits from [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessible label for the table |
+| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | Selection behavior |
+| `selectedKeys` | `Selection` | - | Controlled selected keys |
+| `onSelectionChange` | `(keys: Selection) => void` | - | Selection change handler |
+| `sortDescriptor` | `SortDescriptor` | - | Current sort state |
+| `onSortChange` | `(descriptor: SortDescriptor) => void` | - | Sort change handler |
+| `className` | `string` | - | Additional CSS classes |
+
+### Table.Header Props
+
+Inherits from [React Aria TableHeader](https://react-spectrum.adobe.com/react-aria/Table.html#tableheader).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `T[]` | - | Dynamic column data for render prop pattern |
+| `children` | `React.ReactNode \| (column: T) => React.ReactNode` | - | Static columns or render prop |
+
+### Table.Column Props
+
+Inherits from [React Aria Column](https://react-spectrum.adobe.com/react-aria/Table.html#column).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Column identifier |
+| `allowsSorting` | `boolean` | `false` | Whether the column is sortable |
+| `isRowHeader` | `boolean` | `false` | Whether this column is a row header |
+| `defaultWidth` | `string \| number` | - | Default width for resizable columns |
+| `minWidth` | `number` | - | Minimum width for resizable columns |
+| `children` | `React.ReactNode \| (values: ColumnRenderProps) => React.ReactNode` | - | Column content or render prop with sort direction |
+
+### Table.Body Props
+
+Inherits from [React Aria TableBody](https://react-spectrum.adobe.com/react-aria/Table.html#tablebody).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | - | Dynamic row data for render prop pattern |
+| `renderEmptyState` | `() => React.ReactNode` | - | Content to display when the table is empty |
+| `children` | `React.ReactNode \| (item: T) => React.ReactNode` | - | Static rows or render prop |
+
+### Table.Row Props
+
+Inherits from [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table.html#row).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string \| number` | - | Row identifier |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Row cells |
+
+### Table.Cell Props
+
+Inherits from [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Table.html#cell).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Cell content |
+
+### Table.SortableColumnHeader Props
+
+Renders a sortable column label with an ascending/descending indicator. Use it inside a `Table.Column` render-prop callback and forward the `sortDirection` value.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sortDirection` | `"ascending" \| "descending"` | - | Current sort direction. Pass through from the `Table.Column` render prop. |
+| `showIndicator` | `boolean` | `true` | Whether to render the sort indicator icon when a direction is set. |
+| `indicator` | `React.ReactNode` | - | Custom indicator element. Overrides the default chevron and receives a `data-direction` attribute. |
+| `className` | `string` | - | Additional CSS classes for the wrapper. |
+| `children` | `React.ReactNode` | - | Column label content. |
+
+### Table.Footer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Footer content (e.g., pagination) |
+
+### Table.ColumnResizer Props
+
+Inherits from [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-aria/Table.html#columnresizer).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+### Table.ResizableContainer Props
+
+Inherits from [React Aria ResizableTableContainer](https://react-spectrum.adobe.com/react-aria/Table.html#resizabletablecontainer).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Table.Content element |
+
+### Table.LoadMore Props
+
+Inherits from [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/react-aria/Table.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | `false` | Whether data is currently loading |
+| `onLoadMore` | `() => void` | - | Handler called when the sentinel row is visible |
+| `children` | `React.ReactNode` | - | Loading indicator content |
+
+### Table.LoadMoreContent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Loading indicator content (e.g., Spinner) |
+
+### Table.Collection Props
+
+Re-exported from React Aria `Collection`. Used to render dynamic cells within rows alongside static cells (e.g., checkboxes).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | - | Collection items |
+| `children` | `(item: T) => React.ReactNode` | - | Render prop for each item |
+
+
+### TableLayout
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `rowHeight` | `number \| undefined` | 48 | The fixed height of a row in px. |
+| `estimatedRowHeight` | `number \| undefined` | — | The estimated height of a row, when row heights are variable. |
+| `headingHeight` | `number \| undefined` | 48 | The fixed height of a section header in px. |
+| `estimatedHeadingHeight` | `number \| undefined` | — | The estimated height of a section header, when the height is variable. |
+| `loaderHeight` | `number \| undefined` | 48 | The fixed height of a loader element in px. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections. |
+| `dropIndicatorThickness` | `number \| undefined` | 2 | The thickness of the drop indicator. |
+| `gap` | `number \| undefined` | 0 | The gap between items. |
+| `padding` | `number \| undefined` | 0 | The padding around the list. |
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/calendar.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/calendar.mdx
new file mode 100644
index 0000000..284f136
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/calendar.mdx
@@ -0,0 +1,306 @@
+---
+title: Calendar
+description: Composable date picker with month grid, navigation, and year picker support built on React Aria Calendar
+icon: updated
+links:
+  rac: Calendar
+  source: calendar/calendar.tsx
+  styles: calendar.css
+  storybook: Components/Date and Time/Calendar
+---
+
+## Import
+
+```tsx
+import { Calendar } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="calendar-basic" />
+
+### Anatomy
+
+```tsx
+import {Calendar} from '@heroui/react';
+
+export default () => (
+  <Calendar aria-label="Event date">
+    <Calendar.Header>
+      <Calendar.Heading />
+      <Calendar.NavButton slot="previous" />
+      <Calendar.NavButton slot="next" />
+    </Calendar.Header>
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>
+        {(date) => <Calendar.Cell date={date} />}
+      </Calendar.GridBody>
+    </Calendar.Grid>
+  </Calendar>
+)
+```
+
+### Year Picker
+
+`Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.
+
+<ComponentPreview name="calendar-year-picker" />
+
+### Default Value
+
+<ComponentPreview name="calendar-default-value" />
+
+### Controlled
+
+Use controlled `value` and `focusedValue` for external state coordination and custom shortcuts.
+
+<ComponentPreview name="calendar-controlled" />
+
+### Min and Max Dates
+
+<ComponentPreview name="calendar-min-max-dates" />
+
+### Unavailable Dates
+
+Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots.
+
+<ComponentPreview name="calendar-unavailable-dates" />
+
+### Weeks in Month
+
+Set `weeksInMonth` to a fixed value (for example, `6`) to keep the grid height stable when navigating between months. Use with care in non-Gregorian locales, similar to `firstDayOfWeek`.
+
+<ComponentPreview name="calendar-weeks-in-month" />
+
+### Week View
+
+Set `visibleDuration={{ weeks: n }}` to show one or more weeks at a time. Navigation advances by the visible week range. Use `pageBehavior="single"` to move one week at a time when showing multiple weeks.
+
+<ComponentPreview name="calendar-week-view" />
+
+### Day View
+
+Set `visibleDuration={{ days: n }}` to show a rolling window of consecutive days. Navigation advances by the visible day range. Use `pageBehavior="single"` to move one day at a time when showing multiple days.
+
+<ComponentPreview name="calendar-day-view" />
+
+### Multiple Selection
+
+Set `selectionMode="multiple"` to let users select several dates. `value`, `defaultValue`, and `onChange` use an array of dates.
+
+<ComponentPreview name="calendar-multiple-selection" />
+
+### Disabled
+
+<ComponentPreview name="calendar-disabled" />
+
+### Read Only
+
+<ComponentPreview name="calendar-read-only" />
+
+### Focused Value
+
+Programmatically control which date is focused using `focusedValue` and `onFocusChange`.
+
+<ComponentPreview name="calendar-focused-value" />
+
+### Cell Indicators
+
+You can customize `Calendar.Cell` children and use `Calendar.CellIndicator` to display metadata like events.
+
+<ComponentPreview name="calendar-with-indicators" />
+
+### Multiple Months
+
+Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `Calendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.
+
+<ComponentPreview name="calendar-multiple-months" />
+
+### International Calendars
+
+By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
+
+The example below shows the Indian calendar system:
+
+<ComponentPreview name="calendar-international-calendar" />
+
+**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.
+
+### Custom Navigation Icons
+
+Pass children to `Calendar.NavButton` to replace the default chevron icons.
+
+<ComponentPreview name="calendar-custom-icons" />
+
+### Real-World Example
+
+<ComponentPreview name="calendar-booking-calendar" />
+
+### Custom Styles
+
+<ComponentPreview name="calendar-custom-styles" />
+
+<RelatedComponents component="calendar" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Calendar} from '@heroui/react';
+
+function CustomCalendar() {
+  return (
+    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
+      <Calendar.Header className="pb-3">
+        <Calendar.Heading className="text-default" />
+        <Calendar.NavButton slot="previous" className="text-default" />
+        <Calendar.NavButton slot="next" className="text-default" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
+```
+
+### Customizing the component classes
+
+```css
+@layer components {
+  .calendar {
+    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
+  }
+
+  .calendar__heading {
+    @apply text-sm font-semibold text-default-700;
+  }
+
+  .calendar__cell[data-selected="true"] {
+    @apply bg-accent text-accent-foreground;
+  }
+}
+```
+
+### CSS Classes
+
+Calendar uses these classes in `packages/styles/components/calendar.css` and `packages/styles/components/calendar-year-picker.css`:
+
+- `.calendar` - Root container.
+- `.calendar__header` - Header row containing nav buttons and heading.
+- `.calendar__heading` - Current month label.
+- `.calendar__nav-button` - Previous/next navigation controls.
+- `.calendar__grid` - Main day grid.
+- `.calendar__grid-header` - Weekday header row wrapper.
+- `.calendar__grid-body` - Date rows wrapper.
+- `.calendar__header-cell` - Weekday header cell.
+- `.calendar__cell` - Interactive day cell.
+- `.calendar__cell-indicator` - Dot indicator inside a day cell.
+- `.calendar-year-picker__trigger` - Year picker toggle button.
+- `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger.
+- `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger.
+- `.calendar-year-picker__year-grid` - Overlay grid of selectable years.
+- `.calendar-year-picker__year-cell` - Individual year option.
+
+### Interactive States
+
+Calendar supports both pseudo-classes and React Aria data attributes:
+
+- **Selected**: `[data-selected="true"]`
+- **Today**: `[data-today="true"]`
+- **Unavailable**: `[data-unavailable="true"]`
+- **Outside month**: `[data-outside-month="true"]`
+- **Hovered**: `:hover` or `[data-hovered="true"]`
+- **Pressed**: `:active` or `[data-pressed="true"]`
+- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[data-disabled="true"]`
+
+## API Reference
+
+### Calendar Props
+
+Calendar inherits all props from React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Whether one or many dates can be selected. |
+| `value` | `DateValue \| null` or `DateValue[] \| null` | - | Controlled selected date(s). Use an array when `selectionMode` is `multiple`. |
+| `defaultValue` | `DateValue \| null` or `DateValue[] \| null` | - | Initial selected date(s) (uncontrolled). |
+| `onChange` | `(value: DateValue \| null)` or `(value: DateValue[] \| null) => void` | - | Called when selection changes. |
+| `focusedValue` | `DateValue` | - | Controlled focused date. |
+| `onFocusChange` | `(value: DateValue) => void` | - | Called when focus moves to another date. |
+| `minValue` | `DateValue` | Calendar-aware `1900-01-01` | Earliest selectable date. |
+| `maxValue` | `DateValue` | Calendar-aware `2099-12-31` | Latest selectable date. |
+| `weeksInMonth` | `number` | - | The number of weeks in a month. This overrides the default set by the locale. |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | - | Marks dates as unavailable. |
+| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | Overrides the locale default for the first day of the week. |
+| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | Whether paging advances by the visible duration or one unit at a time. |
+| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | Aligns the visible range to the selection on initial render. |
+| `isDisabled` | `boolean` | `false` | Disables interaction and selection. |
+| `isReadOnly` | `boolean` | `false` | Keeps content readable but prevents selection changes. |
+| `isInvalid` | `boolean` | `false` | Marks the calendar as invalid for validation UI. |
+| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | Visible time range. Use `{ months: n }` for month view, `{ weeks: n }` for week view, or `{ days: n }` for day view. |
+| `defaultYearPickerOpen` | `boolean` | `false` | Initial open state of internal year picker. |
+| `isYearPickerOpen` | `boolean` | - | Controlled year picker open state. |
+| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | Called when year picker open state changes. |
+
+### Composition Parts
+
+| Component | Description |
+|-----------|-------------|
+| `Calendar.Header` | Header container for navigation and heading. |
+| `Calendar.Heading` | Formatted heading for the visible range. Supports `offset` (for multi-month layouts) and `format` (month/year/day options). |
+| `Calendar.NavButton` | Previous/next navigation control (`slot=\"previous\"` or `slot=\"next\"`). |
+| `Calendar.Grid` | Day grid for one month (`offset` supported for multi-month layouts). |
+| `Calendar.GridHeader` | Weekday header container. |
+| `Calendar.GridBody` | Date cell body container. |
+| `Calendar.HeaderCell` | Weekday label cell. |
+| `Calendar.Cell` | Individual date cell. |
+| `Calendar.CellIndicator` | Optional indicator element for custom metadata. |
+| `Calendar.YearPickerTrigger` | Trigger to toggle year-picker mode. |
+| `Calendar.YearPickerTriggerHeading` | Localized heading content inside the year-picker trigger. |
+| `Calendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger. |
+| `Calendar.YearPickerGrid` | Overlay year selection grid container. |
+| `Calendar.YearPickerGridBody` | Body renderer for year grid cells. |
+| `Calendar.YearPickerCell` | Individual year option cell. |
+
+### Year Picker Parts
+
+Year picker subcomponents inherit formatting props from React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) and [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker).
+
+| Component | Prop | Type | Default | Description |
+|-----------|------|------|---------|-------------|
+| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | Customize month/year label (e.g. `{month: 'short'}`). |
+| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | Shift the heading relative to the focused date (multi-month layouts). |
+| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | Customize year cell labels (era, calendar system, etc.). |
+| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max span or `20` | Number of years shown in the sliding window. Defaults to the full range between `minValue` and `maxValue` when both are set. |
+
+### Calendar.Cell Render Props
+
+When `Calendar.Cell` children is a function, React Aria render props are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `formattedDate` | `string` | Localized day label for the cell. |
+| `isSelected` | `boolean` | Whether the date is selected. |
+| `isUnavailable` | `boolean` | Whether the date is unavailable. |
+| `isDisabled` | `boolean` | Whether the cell is disabled. |
+| `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. |
+
+For a complete list of supported calendar systems and their identifiers, see:
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/date-field.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/date-field.mdx
new file mode 100644
index 0000000..cbacd68
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/date-field.mdx
@@ -0,0 +1,468 @@
+---
+title: DateField
+description: Date input field with labels, descriptions, and validation built on React Aria DateField
+links:
+  rac: DateField
+  source: date-field/date-field.tsx
+  styles: date-field.css
+  storybook: Components/Date and Time/DateField
+---
+
+## Import
+
+```tsx
+import { DateField } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="date-field-basic" />
+
+### Anatomy
+
+```tsx
+import {DateField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <DateField>
+    <Label />
+    <DateField.Group>
+      <DateField.Input>
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+    </DateField.Group>
+    <Description />
+    <FieldError />
+  </DateField>
+)
+```
+
+> **DateField** combines label, date input, description, and error into a single accessible component.
+
+### With Description
+
+<ComponentPreview name="date-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="date-field-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="date-field-invalid" />
+
+### With Validation
+
+DateField supports validation with `minValue`, `maxValue`, and custom validation logic.
+
+<ComponentPreview name="date-field-with-validation" />
+
+### Granularity
+
+<ComponentPreview name="date-field-granularity" />
+
+### Controlled
+
+Control the value to synchronize with other components or state management.
+
+<ComponentPreview name="date-field-controlled" />
+
+### Disabled State
+
+<ComponentPreview name="date-field-disabled" />
+
+### With Icons
+
+Add prefix or suffix icons to enhance the date field.
+
+<ComponentPreview name="date-field-with-prefix-icon" />
+
+<ComponentPreview name="date-field-with-suffix-icon" />
+
+<ComponentPreview name="date-field-with-prefix-and-suffix" />
+
+### Full Width
+
+<ComponentPreview name="date-field-full-width" />
+
+### Variants
+
+The DateField.Group component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="date-field-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on DateField.Group to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="date-field-on-surface" />
+
+### Form Example
+
+Complete form example with validation and submission handling.
+
+<ComponentPreview name="date-field-form-example" />
+
+<RelatedComponents component="datefield" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="date-field-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {DateField, Label, Description} from '@heroui/react';
+
+function CustomDateField() {
+  return (
+    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Appointment date
+      </Label>
+      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.Group>
+      <Description className="text-xs text-default-500">
+        Select a date for your appointment.
+      </Description>
+    </DateField>
+  );
+}
+```
+
+### Customizing the component classes
+
+DateField has minimal default styling. Override the `.date-field` class to customize the container styling.
+
+```css
+@layer components {
+  .date-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS Classes
+
+- `.date-field` – Root container with minimal styling (`flex flex-col gap-1`)
+
+> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. DateField.Group styling is documented below in the API Reference section.
+
+### Interactive States
+
+DateField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Required**: `[data-required="true"]` - Applied when `isRequired` is true
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
+
+## API Reference
+
+### DateField Props
+
+DateField inherits all props from React Aria's [DateField](https://react-aria.adobe.com/DateField.md) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode` | - | Child components (Label, DateField.Group, etc.) or render function. |
+| `className` | `string \| (values: DateFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the date field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `DateValue \| null` | - | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `defaultValue` | `DateValue \| null` | - | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `onChange` | `(value: DateValue \| null) => void` | - | Handler called when the value changes. |
+| `placeholderValue` | `DateValue \| null` | - | Placeholder date that influences the format of the placeholder. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `minValue` | `DateValue \| null` | - | The minimum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `maxValue` | `DateValue \| null` | - | The maximum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | - | Callback that is called for each date. If it returns true, the date is unavailable. |
+| `validate` | `(value: DateValue) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+
+#### Format Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `granularity` | `Granularity` | - | Determines the smallest unit displayed. Defaults to `"day"` for dates, `"minute"` for times. |
+| `hourCycle` | `12 \| 24` | - | Whether to display time in 12 or 24 hour format. By default, determined by locale. |
+| `hideTimeZone` | `boolean` | `false` | Whether to hide the time zone abbreviation. |
+| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in month, day, and hour fields. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. Submits as ISO 8601 string. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+| `autoComplete` | `string` | - | Type of autocomplete functionality the input should provide. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+DateField works with these separate components that should be imported and used directly:
+
+- **Label** - Field label component from `@heroui/react`
+- **DateField.Group** - Date input group component (documented below)
+- **DateField.Input** - Input component with segmented editing from `@heroui/react`
+- **DateField.InputContainer** - Scrollable container for grouping multiple inputs (e.g. start/end range inputs) with horizontal overflow
+- **DateField.Segment** - Individual date segment (year, month, day, etc.)
+- **DateField.Prefix** / **DateField.Suffix** - Prefix and suffix slots for the input group
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within DateField for composition:
+
+```tsx
+import {parseDate} from '@internationalized/date';
+import {DateField, Label, Description, FieldError} from '@heroui/react';
+
+<DateField
+  isRequired
+  isInvalid={hasError}
+  minValue={today(getLocalTimeZone())}
+  value={date}
+  onChange={setDate}
+>
+  <Label>Appointment Date</Label>
+  <DateField.Group>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+  </DateField.Group>
+  <Description>Select a date from today onwards.</Description>
+  <FieldError>Please select a valid date.</FieldError>
+</DateField>
+```
+
+### DateValue Types
+
+DateField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/):
+
+- `CalendarDate` - Date without time or timezone
+- `CalendarDateTime` - Date with time but no timezone
+- `ZonedDateTime` - Date with time and timezone
+- `Time` - Time only
+
+Example:
+
+```tsx
+import {parseDate, today, getLocalTimeZone} from '@internationalized/date';
+
+// Parse from string
+const date = parseDate('2024-01-15');
+
+// Today's date
+const todayDate = today(getLocalTimeZone());
+
+// Use in DateField
+<DateField value={date} onChange={setDate}>
+  {/* ... */}
+</DateField>
+```
+
+> **Note:** DateField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for date manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.
+
+### DateFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused. |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
+
+### DateField.Group Props
+
+DateField.Group accepts all props from React Aria's `Group` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `fullWidth` | `boolean` | `false` | Whether the date input group should take full width of its container |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+### DateField.Input Props
+
+DateField.Input accepts all props from React Aria's `DateInput` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+The `DateField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.).
+
+### DateField.Segment Props
+
+DateField.Segment accepts all props from React Aria's `DateSegment` component:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `segment` | `DateSegment` | - | The date segment object from the DateField.Input render prop. |
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+
+### DateField.InputContainer Props
+
+DateField.InputContainer accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display inside the scrollable container (typically multiple `DateField.Input` components). |
+
+### DateField.Prefix Props
+
+DateField.Prefix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the prefix slot. |
+
+### DateField.Suffix Props
+
+DateField.Suffix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the suffix slot. |
+
+## DateField.Group Styling
+
+### Customizing the component classes
+
+The base classes power every instance. Override them once with `@layer components`.
+
+```css
+@layer components {
+  .date-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .date-input-group__input {
+    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .date-input-group__segment {
+    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;
+
+    &:focus,
+    &[data-focused="true"] {
+      @apply bg-accent-soft text-accent-soft-foreground;
+    }
+  }
+
+  .date-input-group__input-container {
+    @apply flex flex-1 items-center;
+    overflow-x: auto;
+    overflow-y: clip;
+    scrollbar-width: none;
+  }
+
+  .date-input-group__prefix,
+  .date-input-group__suffix {
+    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### DateField.Group CSS Classes
+
+- `.date-input-group` – Root container styling
+- `.date-input-group__input` – Input wrapper styling
+- `.date-input-group__input-container` – Scrollable container for grouping multiple inputs
+- `.date-input-group__segment` – Individual date segment styling
+- `.date-input-group__prefix` – Prefix element styling
+- `.date-input-group__suffix` – Suffix element styling
+
+### DateField.Group Interactive States
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
+- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
+- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
+- **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements
+- **Segment Placeholder**: `[data-placeholder="true"]` on segment elements
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/date-picker.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/date-picker.mdx
new file mode 100644
index 0000000..e916f69
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/date-picker.mdx
@@ -0,0 +1,225 @@
+---
+title: DatePicker
+description: Composable date picker built on React Aria DatePicker with DateField and Calendar composition
+links:
+  rac: DatePicker
+  source: date-picker/date-picker.tsx
+  styles: date-picker.css
+  storybook: Components/Date and Time/DatePicker
+  figma: true
+---
+
+## Import
+
+```tsx
+import { DatePicker, DateField, Calendar, Label } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="date-picker-basic" />
+
+### Anatomy
+
+`DatePicker` follows a composition-first API. Compose `DateField` and `Calendar` explicitly to control structure and styling.
+
+```tsx
+import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
+
+export default () => (
+  <DatePicker>
+    <Label />
+    <DateField.Group>
+      <DateField.Input>
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateField.Suffix>
+        <DatePicker.Trigger>
+          <DatePicker.TriggerIndicator />
+        </DatePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    <DatePicker.Popover>
+      <Calendar aria-label="Choose date">
+        <Calendar.Header>
+          <Calendar.YearPickerTrigger>
+            <Calendar.YearPickerTriggerHeading />
+            <Calendar.YearPickerTriggerIndicator />
+          </Calendar.YearPickerTrigger>
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </DatePicker.Popover>
+  </DatePicker>
+)
+```
+
+### Controlled
+
+<ComponentPreview name="date-picker-controlled" />
+
+### Validation
+
+<ComponentPreview name="date-picker-with-validation" />
+
+### Format Options
+
+Control how DatePicker values are displayed with props such as `granularity`, `hourCycle`, `hideTimeZone`, and `shouldForceLeadingZeros`.
+
+<ComponentPreview name="date-picker-format-options" />
+
+### Disabled
+
+<ComponentPreview name="date-picker-disabled" />
+
+### Custom Indicator
+
+`DatePicker.TriggerIndicator` renders the default `IconCalendar` when no children are provided. Pass children to replace it.
+
+<ComponentPreview name="date-picker-with-custom-indicator" />
+
+### Form Example
+
+<ComponentPreview name="date-picker-form-example" />
+
+### International Calendar
+
+By default, DatePicker displays dates using the calendar system for the user's locale. You can override this by wrapping your DatePicker with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
+
+The example below shows the Indian calendar system:
+
+<ComponentPreview name="date-picker-international-calendar" />
+
+**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.
+
+For a complete list of supported calendar systems and their identifiers, see:
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Custom Render Function
+
+<ComponentPreview
+  name="date-picker-custom-render-function"
+/>
+
+<RelatedComponents component="datepicker" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can style each composition part independently:
+
+```tsx
+import {Calendar, DateField, DatePicker, Label} from '@heroui/react';
+
+function CustomDatePicker() {
+  return (
+    <DatePicker className="w-[320px] gap-2">
+      <Label className="text-sm font-semibold">Date</Label>
+      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger className="w-full">
+            <DatePicker.TriggerIndicator className="text-default-600" />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover className="rounded-xl p-2">
+        <Calendar aria-label="Custom date picker calendar">
+          {/* Calendar parts */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize DatePicker base classes, use `@layer components`.
+
+```css
+@layer components {
+  .date-picker {
+    @apply inline-flex flex-col gap-1;
+  }
+
+  .date-picker__trigger {
+    @apply inline-flex items-center justify-between;
+  }
+
+  .date-picker__trigger-indicator {
+    @apply text-muted;
+  }
+
+  .date-picker__popover {
+    @apply min-w-[var(--trigger-width)] p-0;
+  }
+}
+```
+
+HeroUI follows [BEM](https://getbem.com/) naming for reusable customization.
+
+### CSS Classes
+
+DatePicker uses these classes in `packages/styles/components/date-picker.css`:
+
+- `.date-picker` - Root wrapper.
+- `.date-picker__trigger` - Trigger part that opens the popover.
+- `.date-picker__trigger-indicator` - Default/custom indicator slot.
+- `.date-picker__popover` - Popover content wrapper.
+
+### Interactive States
+
+DatePicker supports React Aria data attributes and pseudo states:
+
+- **Open**: `[data-open="true"]` on trigger.
+- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` on trigger.
+- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` on trigger.
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger.
+
+## API Reference
+
+### DatePicker Props
+
+DatePicker inherits all props from React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `DateValue \| null` | - | Controlled selected date value. |
+| `defaultValue` | `DateValue \| null` | - | Default selected value in uncontrolled mode. |
+| `onChange` | `(value: DateValue \| null) => void` | - | Called when selected date changes. |
+| `isOpen` | `boolean` | - | Controlled popover open state. |
+| `defaultOpen` | `boolean` | `false` | Initial popover open state. |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Called when popover open state changes. |
+| `isDisabled` | `boolean` | `false` | Disables date selection and trigger interactions. |
+| `isInvalid` | `boolean` | - | Marks the field as invalid for validation state. |
+| `minValue` | `DateValue` | - | Minimum selectable date. |
+| `maxValue` | `DateValue` | - | Maximum selectable date. |
+| `name` | `string` | - | Name used for HTML form submission. |
+| `children` | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | - | Composed content or render function. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Composition Parts
+
+| Component | Description |
+|-----------|-------------|
+| `DatePicker.Root` | Root date picker container and state owner. |
+| `DatePicker.Trigger` | Trigger button, usually rendered inside `DateField.Suffix`. |
+| `DatePicker.TriggerIndicator` | Indicator slot with default calendar icon. |
+| `DatePicker.Popover` | Popover wrapper for `Calendar` content. |
+
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/date-range-picker.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/date-range-picker.mdx
new file mode 100644
index 0000000..fff3102
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/date-range-picker.mdx
@@ -0,0 +1,244 @@
+---
+title: DateRangePicker
+description: Composable date range picker built on React Aria DateRangePicker with DateField and RangeCalendar composition
+links:
+  rac: DateRangePicker
+  source: date-range-picker/date-range-picker.tsx
+  styles: date-range-picker.css
+  storybook: Components/Date and Time/DateRangePicker
+  figma: true
+---
+
+## Import
+
+```tsx
+import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="date-range-picker-basic" />
+
+### Anatomy
+
+`DateRangePicker` follows a composition-first API. Compose `DateField` and `RangeCalendar` explicitly to control structure and styling.
+
+```tsx
+import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
+
+export default () => (
+  <DateRangePicker>
+    <Label />
+    <DateField.Group>
+      <DateField.InputContainer>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.InputContainer>
+      <DateField.Suffix>
+        <DateRangePicker.Trigger>
+          <DateRangePicker.TriggerIndicator />
+        </DateRangePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    <DateRangePicker.Popover>
+      <RangeCalendar aria-label="Choose trip dates">
+        <RangeCalendar.Header>
+          <RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.YearPickerTriggerHeading />
+            <RangeCalendar.YearPickerTriggerIndicator />
+          </RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>{(date) => <RangeCalendar.Cell date={date} />}</RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </DateRangePicker.Popover>
+  </DateRangePicker>
+)
+```
+
+### Controlled
+
+<ComponentPreview name="date-range-picker-controlled" />
+
+### Validation
+
+<ComponentPreview name="date-range-picker-with-validation" />
+
+### Format Options
+
+Control how DateRangePicker values are displayed with props such as `granularity`, `hourCycle`, `hideTimeZone`, and `shouldForceLeadingZeros`.
+
+<ComponentPreview name="date-range-picker-format-options" />
+
+### Disabled
+
+<ComponentPreview name="date-range-picker-disabled" />
+
+### Custom Indicator
+
+`DateRangePicker.TriggerIndicator` renders the default `IconCalendar` when no children are provided. Pass children to replace it.
+
+<ComponentPreview name="date-range-picker-with-custom-indicator" />
+
+### Form Example
+
+<ComponentPreview name="date-range-picker-form-example" />
+
+### International Calendar
+
+By default, DateRangePicker displays dates using the calendar system for the user's locale. You can override this by wrapping your DateRangePicker with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
+
+The example below shows the Indian calendar system:
+
+<ComponentPreview name="date-range-picker-international-calendar" />
+
+**Note:** The `onChange` event always returns dates in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale.
+
+For a complete list of supported calendar systems and their identifiers, see:
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Custom Render Function
+
+<ComponentPreview
+  name="date-range-picker-custom-render-function"
+/>
+
+<RelatedComponents component="daterangepicker" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can style each composition part independently:
+
+```tsx
+import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';
+
+function CustomDateRangePicker() {
+  return (
+    <DateRangePicker className="w-[360px] gap-2">
+      <Label className="text-sm font-semibold">Trip dates</Label>
+      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator className="px-2 text-default" />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger className="w-full">
+            <DateRangePicker.TriggerIndicator className="text-default" />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover className="rounded-xl p-2">
+        <RangeCalendar aria-label="Custom range picker calendar">
+          {/* RangeCalendar parts */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize DateRangePicker base classes, use `@layer components`.
+
+```css
+@layer components {
+  .date-range-picker {
+    @apply inline-flex flex-col gap-1;
+  }
+
+  .date-range-picker__trigger {
+    @apply inline-flex items-center justify-between;
+  }
+
+  .date-range-picker__trigger-indicator {
+    @apply text-muted;
+  }
+
+  .date-range-picker__range-separator {
+    @apply px-2 text-default;
+  }
+
+  .date-range-picker__popover {
+    @apply min-w-[var(--trigger-width)] p-0;
+  }
+}
+```
+
+HeroUI follows [BEM](https://getbem.com/) naming for reusable customization.
+
+### CSS Classes
+
+DateRangePicker uses these classes in `packages/styles/components/date-range-picker.css`:
+
+- `.date-range-picker` - Root wrapper.
+- `.date-range-picker__trigger` - Trigger part that opens the popover.
+- `.date-range-picker__trigger-indicator` - Default/custom indicator slot.
+- `.date-range-picker__range-separator` - Separator between start and end date inputs.
+- `.date-range-picker__popover` - Popover content wrapper.
+
+### Interactive States
+
+DateRangePicker supports React Aria data attributes and pseudo states:
+
+- **Open**: `[data-open="true"]` on trigger.
+- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` on trigger.
+- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` on trigger.
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger.
+
+## API Reference
+
+### DateRangePicker Props
+
+DateRangePicker inherits all props from React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `{ start: DateValue; end: DateValue } \| null` | - | Controlled selected date range value. |
+| `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | Default selected range in uncontrolled mode. |
+| `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | Called when selected range changes. |
+| `isOpen` | `boolean` | - | Controlled popover open state. |
+| `defaultOpen` | `boolean` | `false` | Initial popover open state. |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Called when popover open state changes. |
+| `isDisabled` | `boolean` | `false` | Disables range selection and trigger interactions. |
+| `isInvalid` | `boolean` | - | Marks the field as invalid for validation state. |
+| `minValue` | `DateValue` | - | Minimum selectable date. |
+| `maxValue` | `DateValue` | - | Maximum selectable date. |
+| `startName` | `string` | - | Name used for the start date in HTML form submission. |
+| `endName` | `string` | - | Name used for the end date in HTML form submission. |
+| `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | Composed content or render function. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Composition Parts
+
+| Component | Description |
+|-----------|-------------|
+| `DateRangePicker.Root` | Root date range picker container and state owner. |
+| `DateRangePicker.Trigger` | Trigger button, usually rendered inside `DateField.Suffix`. |
+| `DateRangePicker.TriggerIndicator` | Indicator slot with default calendar icon. |
+| `DateRangePicker.RangeSeparator` | Separator part between start and end date inputs. |
+| `DateRangePicker.Popover` | Popover wrapper for `RangeCalendar` content. |
+
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/range-calendar.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/range-calendar.mdx
new file mode 100644
index 0000000..f5555d2
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/range-calendar.mdx
@@ -0,0 +1,307 @@
+---
+title: RangeCalendar
+description: Composable date range picker with month grid, navigation, and year picker support built on React Aria RangeCalendar
+links:
+  rac: RangeCalendar
+  source: range-calendar/range-calendar.tsx
+  styles: range-calendar.css
+  storybook: Components/Date and Time/RangeCalendar
+---
+
+## Import
+
+```tsx
+import { RangeCalendar } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="range-calendar-basic" />
+
+### Anatomy
+
+```tsx
+import {RangeCalendar} from '@heroui/react';
+
+export default () => (
+  <RangeCalendar aria-label="Trip dates">
+    <RangeCalendar.Header>
+      <RangeCalendar.Heading />
+      <RangeCalendar.NavButton slot="previous" />
+      <RangeCalendar.NavButton slot="next" />
+    </RangeCalendar.Header>
+    <RangeCalendar.Grid>
+      <RangeCalendar.GridHeader>
+        {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+      </RangeCalendar.GridHeader>
+      <RangeCalendar.GridBody>
+        {(date) => <RangeCalendar.Cell date={date} />}
+      </RangeCalendar.GridBody>
+    </RangeCalendar.Grid>
+  </RangeCalendar>
+)
+```
+
+### Year Picker
+
+`RangeCalendar.YearPickerTrigger`, `RangeCalendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.
+
+<ComponentPreview name="range-calendar-year-picker" />
+
+### Default Value
+
+<ComponentPreview name="range-calendar-default-value" />
+
+### Controlled
+
+<ComponentPreview name="range-calendar-controlled" />
+
+### Min and Max Dates
+
+<ComponentPreview name="range-calendar-min-max-dates" />
+
+### Unavailable Dates
+
+Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots.
+
+<ComponentPreview name="range-calendar-unavailable-dates" />
+
+### Anchor-Based Unavailable Dates
+
+When selecting a range, `isDateUnavailable` receives a second argument, `anchorDate`, set to the first selected date. Use it to limit which end dates are valid (for example, within 7 days of the start).
+
+<ComponentPreview name="range-calendar-anchor-unavailable-dates" />
+
+### Weeks in Month
+
+Set `weeksInMonth` to a fixed value (for example, `6`) to keep the grid height stable when navigating between months.
+
+<ComponentPreview name="range-calendar-weeks-in-month" />
+
+### Week View
+
+Set `visibleDuration={{ weeks: n }}` to show one or more weeks at a time. Navigation advances by the visible week range. Use `pageBehavior="single"` to move one week at a time when showing multiple weeks.
+
+<ComponentPreview name="range-calendar-week-view" />
+
+### Day View
+
+Set `visibleDuration={{ days: n }}` to show a rolling window of consecutive days. Navigation advances by the visible day range. Use `pageBehavior="single"` to move one day at a time when showing multiple days.
+
+<ComponentPreview name="range-calendar-day-view" />
+
+### Allows Non-Contiguous Ranges
+
+Enable `allowsNonContiguousRanges` to allow selection across unavailable dates.
+
+<ComponentPreview name="range-calendar-allows-non-contiguous-ranges" />
+
+### Disabled
+
+<ComponentPreview name="range-calendar-disabled" />
+
+### Read Only
+
+<ComponentPreview name="range-calendar-read-only" />
+
+### Invalid
+
+<ComponentPreview name="range-calendar-invalid" />
+
+### Focused Value
+
+<ComponentPreview name="range-calendar-focused-value" />
+
+### Cell Indicators
+
+You can customize `RangeCalendar.Cell` children and use `RangeCalendar.CellIndicator` to display metadata like events.
+
+<ComponentPreview name="range-calendar-with-indicators" />
+
+### Multiple Months
+
+Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `RangeCalendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.
+
+<ComponentPreview name="range-calendar-multiple-months" />
+
+### International Calendars
+
+By default, RangeCalendar displays dates using the calendar system for the user's locale. You can override this by wrapping your RangeCalendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
+
+The example below shows the Indian calendar system:
+
+<ComponentPreview name="range-calendar-international-calendar" />
+
+**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale.
+
+### Real-World Example
+
+<ComponentPreview name="range-calendar-booking-calendar" />
+
+<RelatedComponents component="range-calendar" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {RangeCalendar} from '@heroui/react';
+
+function CustomRangeCalendar() {
+  return (
+    <RangeCalendar aria-label="Trip dates" className="w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm">
+      <RangeCalendar.Header className="pb-3">
+        <RangeCalendar.Heading className="text-default" />
+        <RangeCalendar.NavButton slot="previous" className="text-default" />
+        <RangeCalendar.NavButton slot="next" className="text-default" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
+```
+
+### Customizing the component classes
+
+```css
+@layer components {
+  .range-calendar {
+    @apply w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm;
+  }
+
+  .range-calendar__heading {
+    @apply text-sm font-semibold text-default;
+  }
+
+  .range-calendar__cell[data-selected="true"] .range-calendar__cell-button {
+    @apply bg-accent text-accent-foreground;
+  }
+}
+```
+
+### CSS Classes
+
+RangeCalendar uses these classes in `packages/styles/components/range-calendar.css` and `packages/styles/components/calendar-year-picker.css`:
+
+- `.range-calendar` - Root container.
+- `.range-calendar__header` - Header row containing nav buttons and heading.
+- `.range-calendar__heading` - Current month label.
+- `.range-calendar__nav-button` - Previous/next navigation controls.
+- `.range-calendar__grid` - Main day grid.
+- `.range-calendar__grid-header` - Weekday header row wrapper.
+- `.range-calendar__grid-body` - Date rows wrapper.
+- `.range-calendar__header-cell` - Weekday header cell.
+- `.range-calendar__cell` - Interactive day cell wrapper.
+- `.range-calendar__cell-button` - Interactive day button inside each cell.
+- `.range-calendar__cell-indicator` - Dot indicator inside a day cell.
+- `.calendar-year-picker__trigger` - Year picker toggle button.
+- `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger.
+- `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger.
+- `.calendar-year-picker__year-grid` - Overlay grid of selectable years.
+- `.calendar-year-picker__year-cell` - Individual year option.
+
+### Interactive States
+
+RangeCalendar supports both pseudo-classes and React Aria data attributes:
+
+- **Selected**: `[data-selected="true"]`
+- **Selection start**: `[data-selection-start="true"]`
+- **Selection end**: `[data-selection-end="true"]`
+- **Range middle**: `[data-selection-in-range="true"]`
+- **Today**: `[data-today="true"]`
+- **Unavailable**: `[data-unavailable="true"]`
+- **Outside month**: `[data-outside-month="true"]`
+- **Hovered**: `:hover` or `[data-hovered="true"]`
+- **Pressed**: `:active` or `[data-pressed="true"]`
+- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[data-disabled="true"]`
+
+## API Reference
+
+### RangeCalendar Props
+
+RangeCalendar inherits all props from React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `RangeValue<DateValue> \| null` | - | Controlled selected range. |
+| `defaultValue` | `RangeValue<DateValue> \| null` | - | Initial selected range (uncontrolled). |
+| `onChange` | `(value: RangeValue<DateValue>) => void` | - | Called when selection changes. |
+| `focusedValue` | `DateValue` | - | Controlled focused date. |
+| `onFocusChange` | `(value: DateValue) => void` | - | Called when focus moves to another date. |
+| `minValue` | `DateValue` | Calendar-aware `1900-01-01` | Earliest selectable date. |
+| `maxValue` | `DateValue` | Calendar-aware `2099-12-31` | Latest selectable date. |
+| `weeksInMonth` | `number` | - | The number of weeks in a month. This overrides the default set by the locale. |
+| `isDateUnavailable` | `(date: DateValue, anchorDate: CalendarDate \| null) => boolean` | - | Marks dates as unavailable. When `anchorDate` is set, it is the first date the user selected in the current range gesture. |
+| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | Overrides the locale default for the first day of the week. |
+| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | Whether paging advances by the visible duration or one unit at a time. |
+| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | Aligns the visible range to the selection on initial render. |
+| `allowsNonContiguousRanges` | `boolean` | `false` | Allows ranges that span unavailable dates. |
+| `isDisabled` | `boolean` | `false` | Disables interaction and selection. |
+| `isReadOnly` | `boolean` | `false` | Keeps content readable but prevents selection changes. |
+| `isInvalid` | `boolean` | `false` | Marks the calendar as invalid for validation UI. |
+| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | Visible time range. Use `{ months: n }` for month view, `{ weeks: n }` for week view, or `{ days: n }` for day view. |
+| `defaultYearPickerOpen` | `boolean` | `false` | Initial open state of internal year picker. |
+| `isYearPickerOpen` | `boolean` | - | Controlled year picker open state. |
+| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | Called when year picker open state changes. |
+
+### Composition Parts
+
+| Component | Description |
+|-----------|-------------|
+| `RangeCalendar.Header` | Header container for navigation and heading. |
+| `RangeCalendar.Heading` | Formatted heading for the visible range. Supports `offset` (for multi-month layouts) and `format` (month/year/day options). |
+| `RangeCalendar.NavButton` | Previous/next navigation control (`slot="previous"` or `slot="next"`). |
+| `RangeCalendar.Grid` | Day grid for one month (`offset` supported for multi-month layouts). |
+| `RangeCalendar.GridHeader` | Weekday header container. |
+| `RangeCalendar.GridBody` | Date cell body container. |
+| `RangeCalendar.HeaderCell` | Weekday label cell. |
+| `RangeCalendar.Cell` | Individual date cell. |
+| `RangeCalendar.CellIndicator` | Optional indicator element for custom metadata. |
+| `RangeCalendar.YearPickerTrigger` | Trigger to toggle year-picker mode. |
+| `RangeCalendar.YearPickerTriggerHeading` | Localized heading content inside the year-picker trigger. |
+| `RangeCalendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger. |
+| `RangeCalendar.YearPickerGrid` | Overlay year selection grid container. |
+| `RangeCalendar.YearPickerGridBody` | Body renderer for year grid cells. |
+| `RangeCalendar.YearPickerCell` | Individual year option cell. |
+
+### Year Picker Parts
+
+Year picker subcomponents inherit formatting props from React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) and [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker).
+
+| Component | Prop | Type | Default | Description |
+|-----------|------|------|---------|-------------|
+| `RangeCalendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | Customize month/year label (e.g. `{month: 'short'}`). |
+| `RangeCalendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | Shift the heading relative to the focused date (multi-month layouts). |
+| `RangeCalendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | Customize year cell labels (era, calendar system, etc.). |
+| `RangeCalendar.YearPickerGrid` | `visibleYears` | `number` | min–max span or `20` | Number of years shown in the sliding window. Defaults to the full range between `minValue` and `maxValue` when both are set. |
+
+### RangeCalendar.Cell Render Props
+
+When `RangeCalendar.Cell` children is a function, React Aria render props are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `formattedDate` | `string` | Localized day label for the cell. |
+| `isSelected` | `boolean` | Whether the date is selected. |
+| `isSelectionStart` | `boolean` | Whether the date is the start of the selected range. |
+| `isSelectionEnd` | `boolean` | Whether the date is the end of the selected range. |
+| `isUnavailable` | `boolean` | Whether the date is unavailable. |
+| `isDisabled` | `boolean` | Whether the cell is disabled. |
+| `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. |
+
+For a complete list of supported calendar systems and their identifiers, see:
+- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
+- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
+
+### Related packages
+- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
+- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
+- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
diff --git a/apps/docs/content/docs/en/react/components/(date-and-time)/time-field.mdx b/apps/docs/content/docs/en/react/components/(date-and-time)/time-field.mdx
new file mode 100644
index 0000000..4820fe1
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(date-and-time)/time-field.mdx
@@ -0,0 +1,435 @@
+---
+title: TimeField
+description: Time input field with labels, descriptions, and validation built on React Aria TimeField
+links:
+  rac: TimeField
+  source: time-field/time-field.tsx
+  styles: time-field.css
+  storybook: Components/Date and Time/TimeField
+---
+
+## Import
+
+```tsx
+import { TimeField } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="time-field-basic" />
+
+### Anatomy
+
+```tsx
+import {TimeField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <TimeField>
+    <Label />
+    <TimeField.Group>
+      <TimeField.Input>
+        {(segment) => <TimeField.Segment segment={segment} />}
+      </TimeField.Input>
+    </TimeField.Group>
+    <Description />
+    <FieldError />
+  </TimeField>
+)
+```
+
+> **TimeField** combines label, time input, description, and error into a single accessible component.
+
+### With Description
+
+<ComponentPreview name="time-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="time-field-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="time-field-invalid" />
+
+### With Validation
+
+TimeField supports validation with `minValue`, `maxValue`, and custom validation logic.
+
+<ComponentPreview name="time-field-with-validation" />
+
+### Controlled
+
+Control the value to synchronize with other components or state management.
+
+<ComponentPreview name="time-field-controlled" />
+
+### Disabled State
+
+<ComponentPreview name="time-field-disabled" />
+
+### With Icons
+
+Add prefix or suffix icons to enhance the time field.
+
+<ComponentPreview name="time-field-with-prefix-icon" />
+
+<ComponentPreview name="time-field-with-suffix-icon" />
+
+<ComponentPreview name="time-field-with-prefix-and-suffix" />
+
+### Full Width
+
+<ComponentPreview name="time-field-full-width" />
+
+### On Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on TimeField.Group to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="time-field-on-surface" />
+
+### Form Example
+
+Complete form example with validation and submission handling.
+
+<ComponentPreview name="time-field-form-example" />
+
+<RelatedComponents component="timefield" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="time-field-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {TimeField, Label, Description} from '@heroui/react';
+
+function CustomTimeField() {
+  return (
+    <TimeField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Appointment time
+      </Label>
+      <TimeField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
+        <TimeField.Input>
+          {(segment) => <TimeField.Segment segment={segment} />}
+        </TimeField.Input>
+      </TimeField.Group>
+      <Description className="text-xs text-default-500">
+        Select a time for your appointment.
+      </Description>
+    </TimeField>
+  );
+}
+```
+
+### Customizing the component classes
+
+TimeField has minimal default styling. Override the `.time-field` class to customize the container styling.
+
+```css
+@layer components {
+  .time-field {
+    @apply flex flex-col gap-1;
+
+    &[data-invalid="true"],
+    &[aria-invalid="true"] {
+      [data-slot="description"] {
+        @apply hidden;
+      }
+    }
+
+    [data-slot="label"] {
+      @apply w-fit;
+    }
+
+    [data-slot="description"] {
+      @apply px-1;
+    }
+  }
+}
+```
+
+### CSS Classes
+
+- `.time-field` – Root container with minimal styling (`flex flex-col gap-1`)
+
+> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. TimeField.Group styling is documented below in the API Reference section.
+
+### Interactive States
+
+TimeField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Required**: `[data-required="true"]` - Applied when `isRequired` is true
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
+
+## API Reference
+
+### TimeField Props
+
+TimeField inherits all props from React Aria's [TimeField](https://react-aria.adobe.com/TimeField) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode` | - | Child components (Label, TimeField.Group, etc.) or render function. |
+| `className` | `string \| (values: TimeFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the time field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `TimeValue \| null` | - | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `defaultValue` | `TimeValue \| null` | - | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `onChange` | `(value: TimeValue \| null) => void` | - | Handler called when the value changes. |
+| `placeholderValue` | `TimeValue \| null` | - | Placeholder time that influences the format of the placeholder. Defaults to 12:00 AM or 00:00 depending on the hour cycle. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `minValue` | `TimeValue \| null` | - | The minimum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `maxValue` | `TimeValue \| null` | - | The maximum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
+| `validate` | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+
+#### Format Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `granularity` | `'hour' \| 'minute' \| 'second'` | `'minute'` | Determines the smallest unit displayed in the time picker. |
+| `hourCycle` | `12 \| 24` | - | Whether to display time in 12 or 24 hour format. By default, determined by locale. |
+| `hideTimeZone` | `boolean` | `false` | Whether to hide the time zone abbreviation. |
+| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, determined by locale. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. Submits as ISO 8601 string. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+TimeField works with these separate components that should be imported and used directly:
+
+- **Label** - Field label component from `@heroui/react`
+- **TimeField.Group** - Time input group component (documented below)
+- **TimeField.Input** - Input component with segmented editing from `@heroui/react`
+- **TimeField.Segment** - Individual time segment (hour, minute, second, etc.)
+- **TimeField.Prefix** / **TimeField.Suffix** - Prefix and suffix slots for the input group
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within TimeField for composition:
+
+```tsx
+import {parseTime} from '@internationalized/date';
+import {TimeField, Label, Description, FieldError} from '@heroui/react';
+
+<TimeField
+  isRequired
+  isInvalid={hasError}
+  minValue={parseTime('09:00')}
+  maxValue={parseTime('17:00')}
+  value={time}
+  onChange={setTime}
+>
+  <Label>Appointment Time</Label>
+  <TimeField.Group>
+    <TimeField.Input>
+      {(segment) => <TimeField.Segment segment={segment} />}
+    </TimeField.Input>
+  </TimeField.Group>
+  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>
+  <FieldError>Please select a valid time.</FieldError>
+</TimeField>
+```
+
+### TimeValue Types
+
+TimeField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/):
+
+- `Time` - Time only (hour, minute, second)
+- `CalendarDateTime` - Date with time but no timezone (TimeField displays only the time portion)
+- `ZonedDateTime` - Date with time and timezone (TimeField displays only the time portion)
+
+Example:
+
+```tsx
+import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';
+
+// Parse from string
+const time = parseTime('14:30');
+
+// Create from current time
+const currentTime = now(getLocalTimeZone());
+const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);
+
+// Use in TimeField
+<TimeField value={time} onChange={setTime}>
+  {/* ... */}
+</TimeField>
+```
+
+> **Note:** TimeField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for time manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.
+
+### TimeFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused. |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
+
+### TimeField.Group Props
+
+TimeField.Group accepts all props from React Aria's `Group` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+### TimeField.Input Props
+
+TimeField.Input accepts all props from React Aria's `DateInput` component plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+The `TimeField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.).
+
+### TimeField.Segment Props
+
+TimeField.Segment accepts all props from React Aria's `DateSegment` component:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `segment` | `DateSegment` | - | The date segment object from the TimeField.Input render prop. |
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+
+### TimeField.Prefix Props
+
+TimeField.Prefix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the prefix slot. |
+
+### TimeField.Suffix Props
+
+TimeField.Suffix accepts standard HTML `div` attributes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `children` | `ReactNode` | - | Content to display in the suffix slot. |
+
+## TimeField.Group Styling
+
+### Customizing the component classes
+
+The base classes power every instance. Override them once with `@layer components`.
+
+```css
+@layer components {
+  .date-input-group {
+    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+    }
+
+    &[data-focus-within="true"],
+    &:focus-within {
+      @apply status-focused-field;
+    }
+
+    &[data-invalid="true"] {
+      @apply status-invalid-field;
+    }
+
+    &[data-disabled="true"],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+
+  .date-input-group__input {
+    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .date-input-group__segment {
+    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;
+
+    &:focus,
+    &[data-focused="true"] {
+      @apply bg-accent-soft text-accent-soft-foreground;
+    }
+  }
+
+  .date-input-group__prefix,
+  .date-input-group__suffix {
+    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
+  }
+}
+```
+
+### TimeField.Group CSS Classes
+
+- `.date-input-group` – Root container styling
+- `.date-input-group__input` – Input wrapper styling
+- `.date-input-group__segment` – Individual time segment styling
+- `.date-input-group__prefix` – Prefix element styling
+- `.date-input-group__suffix` – Suffix element styling
+
+### TimeField.Group Interactive States
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
+- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
+- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
+- **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements
+- **Segment Placeholder**: `[data-placeholder="true"]` on segment elements
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/alert.mdx b/apps/docs/content/docs/en/react/components/(feedback)/alert.mdx
new file mode 100644
index 0000000..1e19c83
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/alert.mdx
@@ -0,0 +1,147 @@
+---
+title: Alert
+description: Display important messages and notifications to users with status indicators
+links:
+  source: alert/alert.tsx
+  styles: alert.css
+  storybook: Components/Feedback/Alert
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Alert } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+
+### Anatomy
+
+Import the Alert component and access all parts using dot notation.
+
+```tsx
+import { Alert } from '@heroui/react';
+
+export default () => (
+  <Alert>
+    <Alert.Indicator />
+    <Alert.Content>
+      <Alert.Title />
+      <Alert.Description />
+    </Alert.Content>
+  </Alert>
+)
+```
+
+<RelatedComponents component="alert" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Alert } from "@heroui/react";
+
+function CustomAlert() {
+  return (
+    <Alert className="border-2 border-blue-500 rounded-xl" status="accent">
+      <Alert.Indicator className="text-blue-600" />
+      <Alert.Content className="gap-1">
+        <Alert.Title className="font-bold text-lg">Custom Alert</Alert.Title>
+        <Alert.Description className="text-sm opacity-80">
+          This alert has custom styling applied
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Alert component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .alert {
+    @apply rounded-2xl shadow-lg;
+  }
+
+  .alert__title {
+    @apply font-bold text-lg;
+  }
+
+  .alert--danger {
+    @apply border-l-4 border-red-600;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Alert component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)):
+
+#### Base Classes
+- `.alert` - Base alert container
+- `.alert__indicator` - Icon/indicator container
+- `.alert__content` - Content wrapper for title and description
+- `.alert__title` - Alert title text
+- `.alert__description` - Alert description text
+
+#### Status Variant Classes
+- `.alert--default` - Default gray status
+- `.alert--accent` - Accent blue status
+- `.alert--success` - Success green status
+- `.alert--warning` - Warning yellow/orange status
+- `.alert--danger` - Danger red status
+
+### Interactive States
+
+The Alert component is primarily informational and doesn't have interactive states on the base component. However, it can contain interactive elements like buttons or close buttons.
+
+## API Reference
+
+### Alert Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | The visual status of the alert |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert content |
+
+### Alert.Indicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom indicator icon (defaults to status icon) |
+
+### Alert.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Content (typically Title and Description) |
+
+### Alert.Title Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert title text |
+
+### Alert.Description Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert description text |
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/meter.mdx b/apps/docs/content/docs/en/react/components/(feedback)/meter.mdx
new file mode 100644
index 0000000..70f82a1
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/meter.mdx
@@ -0,0 +1,160 @@
+---
+title: Meter
+description: A meter represents a quantity within a known range, or a fractional value.
+links:
+  rac: Meter
+  source: meter/meter.tsx
+  styles: meter.css
+  storybook: Components/Feedback/Meter
+---
+
+## Import
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="meter-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+
+export default () => (
+  <Meter value={60}>
+    <Label>Storage</Label>
+    <Meter.Output />
+    <Meter.Track>
+      <Meter.Fill />
+    </Meter.Track>
+  </Meter>
+);
+```
+
+### Sizes
+
+<ComponentPreview
+  name="meter-sizes"
+/>
+
+### Colors
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+### Custom Value Scale
+
+Use `minValue`, `maxValue`, and `formatOptions` to customize the value range and display format.
+
+<ComponentPreview
+  name="meter-custom-value"
+/>
+
+### Without Label
+
+When no visible label is needed, use `aria-label` for accessibility.
+
+<ComponentPreview
+  name="meter-without-label"
+/>
+
+<RelatedComponents component="meter" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual Meter parts:
+
+```tsx
+import { Meter, Label } from '@heroui/react';
+
+function CustomMeter() {
+  return (
+    <Meter value={60}>
+      <Label>Storage</Label>
+      <Meter.Output />
+      <Meter.Track className="bg-purple-100 dark:bg-purple-900">
+        <Meter.Fill className="bg-purple-500" />
+      </Meter.Track>
+    </Meter>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Meter component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .meter {
+    @apply w-full gap-2;
+  }
+
+  .meter__track {
+    @apply h-3 rounded-full;
+  }
+
+  .meter__fill {
+    @apply rounded-full;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Meter component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/meter.css)):
+
+#### Base & Element Classes
+- `.meter` - Base container (grid layout)
+- `.meter__output` - Value text display
+- `.meter__track` - Track background
+- `.meter__fill` - Filled portion of the track
+
+#### Size Classes
+- `.meter--sm` - Small size variant (thinner track)
+- `.meter--md` - Medium size variant (default)
+- `.meter--lg` - Large size variant (thicker track)
+
+#### Color Classes
+- `.meter--default` - Default color variant
+- `.meter--accent` - Accent color variant
+- `.meter--success` - Success color variant
+- `.meter--warning` - Warning color variant
+- `.meter--danger` - Danger color variant
+
+## API Reference
+
+### Meter Props
+
+Inherits from [React Aria Meter](https://react-spectrum.adobe.com/react-aria/Meter.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | `0` | The current value |
+| `minValue` | `number` | `0` | The minimum value |
+| `maxValue` | `number` | `100` | The maximum value |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the meter track |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Color of the fill bar |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | Number format for the value display |
+| `valueLabel` | `ReactNode` | - | Custom value label content |
+| `children` | `ReactNode \| (values: MeterRenderProps) => ReactNode` | - | Content or render prop |
+
+### MeterRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `percentage` | `number` | The percentage of the meter (0-100) |
+| `valueText` | `string` | The formatted value text |
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/progress-bar.mdx b/apps/docs/content/docs/en/react/components/(feedback)/progress-bar.mdx
new file mode 100644
index 0000000..cbca4eb
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/progress-bar.mdx
@@ -0,0 +1,170 @@
+---
+title: ProgressBar
+description: A progress bar shows either determinate or indeterminate progress of an operation over time.
+links:
+  rac: ProgressBar
+  source: progress-bar/progress-bar.tsx
+  styles: progress-bar.css
+  storybook: Components/Feedback/ProgressBar
+---
+
+## Import
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="progress-bar-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+
+export default () => (
+  <ProgressBar value={60}>
+    <Label>Loading</Label>
+    <ProgressBar.Output />
+    <ProgressBar.Track>
+      <ProgressBar.Fill />
+    </ProgressBar.Track>
+  </ProgressBar>
+);
+```
+
+### Sizes
+
+<ComponentPreview
+  name="progress-bar-sizes"
+/>
+
+### Colors
+
+<ComponentPreview
+  name="progress-bar-colors"
+/>
+
+### Indeterminate
+
+Use `isIndeterminate` when progress cannot be determined.
+
+<ComponentPreview
+  name="progress-bar-indeterminate"
+/>
+
+### Custom Value Scale
+
+Use `minValue`, `maxValue`, and `formatOptions` to customize the value range and display format.
+
+<ComponentPreview
+  name="progress-bar-custom-value"
+/>
+
+### Without Label
+
+When no visible label is needed, use `aria-label` for accessibility.
+
+<ComponentPreview
+  name="progress-bar-without-label"
+/>
+
+<RelatedComponents component="progress-bar" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual ProgressBar parts:
+
+```tsx
+import { ProgressBar, Label } from '@heroui/react';
+
+function CustomProgressBar() {
+  return (
+    <ProgressBar value={60}>
+      <Label>Loading</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track className="bg-purple-100 dark:bg-purple-900">
+        <ProgressBar.Fill className="bg-purple-500" />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ProgressBar component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .progress-bar {
+    @apply w-full gap-2;
+  }
+
+  .progress-bar__track {
+    @apply h-3 rounded-full;
+  }
+
+  .progress-bar__fill {
+    @apply rounded-full;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ProgressBar component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-bar.css)):
+
+#### Base & Element Classes
+- `.progress-bar` - Base container (grid layout)
+- `.progress-bar__output` - Value text display
+- `.progress-bar__track` - Track background
+- `.progress-bar__fill` - Filled portion of the track
+
+#### Size Classes
+- `.progress-bar--sm` - Small size variant (thinner track)
+- `.progress-bar--md` - Medium size variant (default)
+- `.progress-bar--lg` - Large size variant (thicker track)
+
+#### Color Classes
+- `.progress-bar--default` - Default color variant
+- `.progress-bar--accent` - Accent color variant
+- `.progress-bar--success` - Success color variant
+- `.progress-bar--warning` - Warning color variant
+- `.progress-bar--danger` - Danger color variant
+
+## API Reference
+
+### ProgressBar Props
+
+Inherits from [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | `0` | The current value |
+| `minValue` | `number` | `0` | The minimum value |
+| `maxValue` | `number` | `100` | The maximum value |
+| `isIndeterminate` | `boolean` | `false` | Whether progress is indeterminate |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the progress track |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Color of the fill bar |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | Number format for the value display |
+| `valueLabel` | `ReactNode` | - | Custom value label content |
+| `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | Content or render prop |
+
+### ProgressBarRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `percentage` | `number` | The percentage of the progress (0-100) |
+| `valueText` | `string` | The formatted value text |
+| `isIndeterminate` | `boolean` | Whether progress is indeterminate |
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/progress-circle.mdx b/apps/docs/content/docs/en/react/components/(feedback)/progress-circle.mdx
new file mode 100644
index 0000000..fc75728
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/progress-circle.mdx
@@ -0,0 +1,165 @@
+---
+title: ProgressCircle
+description: A circular progress indicator that shows determinate or indeterminate progress.
+links:
+  rac: ProgressBar
+  source: progress-circle/progress-circle.tsx
+  styles: progress-circle.css
+  storybook: Components/Feedback/ProgressCircle
+---
+
+## Import
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="progress-circle-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+
+export default () => (
+  <ProgressCircle aria-label="Loading" value={60}>
+    <ProgressCircle.Track>
+      <ProgressCircle.TrackCircle />
+      <ProgressCircle.FillCircle />
+    </ProgressCircle.Track>
+  </ProgressCircle>
+);
+```
+
+### Sizes
+
+<ComponentPreview
+  name="progress-circle-sizes"
+/>
+
+### Colors
+
+<ComponentPreview
+  name="progress-circle-colors"
+/>
+
+### Indeterminate
+
+Use `isIndeterminate` when progress cannot be determined.
+
+<ComponentPreview
+  name="progress-circle-indeterminate"
+/>
+
+### With Label
+
+<ComponentPreview
+  name="progress-circle-with-label"
+/>
+
+### Custom SVG Props
+
+Since each part is a composable component, you can override SVG attributes like `strokeWidth`, `r`, `cx`, `cy`, and `viewBox` directly.
+
+<ComponentPreview
+  name="progress-circle-custom-svg"
+/>
+
+<RelatedComponents component="progress-circle" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual ProgressCircle parts:
+
+```tsx
+import { ProgressCircle } from '@heroui/react';
+
+function CustomProgressCircle() {
+  return (
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle className="stroke-purple-500" />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ProgressCircle component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .progress-circle {
+    @apply inline-flex;
+  }
+
+  .progress-circle__track {
+    @apply size-12;
+  }
+
+  .progress-circle__fill-circle {
+    stroke: purple;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ProgressCircle component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-circle.css)):
+
+#### Base & Element Classes
+- `.progress-circle` - Base container
+- `.progress-circle__track` - SVG element
+- `.progress-circle__track-circle` - Background circle
+- `.progress-circle__fill-circle` - Progress arc
+
+#### Size Classes
+- `.progress-circle--sm` - Small size variant
+- `.progress-circle--md` - Medium size variant (default)
+- `.progress-circle--lg` - Large size variant
+
+#### Color Classes
+- `.progress-circle--default` - Default color variant
+- `.progress-circle--accent` - Accent color variant
+- `.progress-circle--success` - Success color variant
+- `.progress-circle--warning` - Warning color variant
+- `.progress-circle--danger` - Danger color variant
+
+## API Reference
+
+### ProgressCircle Props
+
+Inherits from [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | `0` | The current value |
+| `minValue` | `number` | `0` | The minimum value |
+| `maxValue` | `number` | `100` | The maximum value |
+| `isIndeterminate` | `boolean` | `false` | Whether progress is indeterminate |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the circle |
+| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Color of the progress arc |
+| `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | Number format for the value display |
+| `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | Content or render prop |
+
+### ProgressBarRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `percentage` | `number` | The percentage of the progress (0-100) |
+| `valueText` | `string` | The formatted value text |
+| `isIndeterminate` | `boolean` | Whether progress is indeterminate |
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/skeleton.mdx b/apps/docs/content/docs/en/react/components/(feedback)/skeleton.mdx
new file mode 100644
index 0000000..22d9915
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/skeleton.mdx
@@ -0,0 +1,197 @@
+---
+title: Skeleton
+description: Skeleton is a placeholder to show a loading state and the expected shape of a component.
+links:
+  source: skeleton/skeleton.tsx
+  styles: skeleton.css
+  storybook: Components/Feedback/Skeleton
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Skeleton } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview 
+  name="skeleton-basic"
+/>
+ 
+
+### Text Content
+
+<ComponentPreview 
+  name="skeleton-text-content"
+/>
+
+### User Profile
+
+<ComponentPreview 
+  name="skeleton-user-profile"
+/>
+
+### List Items
+
+<ComponentPreview
+  name="skeleton-list"
+/>
+
+### Animation Types
+
+<ComponentPreview
+  name="skeleton-animation-types"
+/>
+
+### Grid
+
+<ComponentPreview
+  name="skeleton-grid"
+/>
+
+### Single Shimmer
+
+A synchronized shimmer effect that passes over all skeleton elements at once. Apply the `skeleton--shimmer` class to a parent container and set `animationType="none"` on child skeletons.
+
+<ComponentPreview
+  name="skeleton-single-shimmer"
+  style={{'contain': 'none'}}
+/>
+
+<RelatedComponents component="skeleton" />
+
+## Styling
+
+### Global Animation Configuration
+
+You can set a default animation type for all Skeleton components in your application by defining the `--skeleton-animation` CSS variable:
+
+```css
+/* In your global CSS file */
+:root {
+  /* Possible values: shimmer, pulse, none */
+  --skeleton-animation: pulse;
+}
+
+/* You can also set different values for light/dark themes */
+.light, [data-theme="light"] {
+  --skeleton-animation: shimmer;
+}
+
+.dark, [data-theme="dark"] {
+  --skeleton-animation: pulse;
+}
+```
+
+This global setting will be overridden by the `animationType` prop when specified on individual components.
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Skeleton } from '@heroui/react';
+
+function CustomSkeleton() {
+  return (
+    <Skeleton className="h-20 w-32 rounded-full" />
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Skeleton component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  /* Base skeleton styles */
+  .skeleton {
+    @apply bg-surface-secondary/50; /* Change base background */
+  }
+
+  /* Shimmer animation gradient */
+  .skeleton--shimmer:before {
+    @apply viasurface; /* Change shimmer gradient color */
+  }
+
+  /* Pulse animation */
+  .skeleton--pulse {
+    @apply animate-pulse opacity-75; /* Customize pulse animation */
+  }
+
+  /* No animation variant */
+  .skeleton--none {
+    @apply opacity-50; /* Style for static skeleton */
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Skeleton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)):
+
+#### Base Class
+`.skeleton` - Base skeleton styles with background and rounded corners
+
+#### Animation Variant Classes
+- `.skeleton--shimmer` - Adds shimmer animation with gradient effect (default)
+- `.skeleton--pulse` - Adds pulse animation using Tailwind's animate-pulse
+- `.skeleton--none` - No animation, static skeleton
+
+### Animation
+
+The Skeleton component supports three animation types, each with different visual effects:
+
+#### Shimmer Animation
+The shimmer effect creates a gradient that moves across the skeleton element:
+
+```css
+.skeleton--shimmer:before {
+  @apply animate-skeleton via-surface-3 absolute inset-0 -translate-x-full
+         bg-gradient-to-r from-transparent to-transparent content-[''];
+}
+```
+
+The shimmer animation is defined in the theme using:
+```css
+@theme inline {
+  --animate-skeleton: skeleton 2s linear infinite;
+
+  @keyframes skeleton {
+    100% {
+      transform: translateX(200%);
+    }
+  }
+}
+```
+
+#### Pulse Animation
+The pulse animation uses Tailwind's built-in `animate-pulse` utility:
+
+```css
+.skeleton--pulse {
+  @apply animate-pulse;
+}
+```
+
+#### No Animation
+For static skeletons without any animation:
+
+```css
+.skeleton--none {
+  /* No animation styles applied */
+}
+```
+
+## API Reference
+
+### Skeleton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` or CSS variable | The animation type for the skeleton. Can be globally configured via `--skeleton-animation` CSS variable |
+| `className` | `string` | - | Additional CSS classes |
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(feedback)/spinner.mdx b/apps/docs/content/docs/en/react/components/(feedback)/spinner.mdx
new file mode 100644
index 0000000..293a051
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(feedback)/spinner.mdx
@@ -0,0 +1,96 @@
+---
+title: Spinner
+description: A loading indicator component to show pending states
+links:
+  source: spinner/spinner.tsx
+  styles: spinner.css
+  storybook: Components/Feedback/Spinner
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Spinner } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="spinner-basic"
+/>
+
+### Colors
+
+<ComponentPreview
+  name="spinner-colors"
+/>
+
+### Sizes
+
+<ComponentPreview
+  name="spinner-sizes"
+/>
+
+<RelatedComponents component="spinner" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Spinner} from '@heroui/react';
+
+function CustomSpinner() {
+  return (
+    <Spinner className="text-blue-500" />
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Spinner component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .spinner {
+    @apply animate-spin;
+  }
+
+  .spinner--accent {
+    color: var(--accent);
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Spinner component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)):
+
+#### Base & Size Classes
+- `.spinner` - Base spinner styles with default size
+- `.spinner--sm` - Small size variant
+- `.spinner--md` - Medium size variant (default)
+- `.spinner--lg` - Large size variant
+- `.spinner--xl` - Extra large size variant
+
+#### Color Classes
+- `.spinner--current` - Inherits current text color
+- `.spinner--accent` - Accent color variant
+- `.spinner--danger` - Danger color variant
+- `.spinner--success` - Success color variant
+- `.spinner--warning` - Warning color variant
+
+## API Reference
+
+### Spinner Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the spinner |
+| `color` | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Color variant of the spinner |
+| `className` | `string` | - | Additional CSS classes |
diff --git a/apps/docs/content/docs/en/react/components/(forms)/checkbox-group.mdx b/apps/docs/content/docs/en/react/components/(forms)/checkbox-group.mdx
new file mode 100644
index 0000000..0ddc7d1
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/checkbox-group.mdx
@@ -0,0 +1,177 @@
+---
+title: CheckboxGroup
+description: A checkbox group component for managing multiple checkbox selections
+icon: updated
+links:
+  rac: CheckboxGroup
+  source: checkbox-group/checkbox-group.tsx
+  styles: checkbox-group.css
+  storybook: Components/Forms/CheckboxGroup
+---
+
+## Import
+
+```tsx
+import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="checkbox-group-basic"
+/>
+
+### Anatomy
+
+Import the CheckboxGroup component and access all parts using dot notation.
+
+```tsx
+import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <CheckboxGroup name="interests">
+    <Label />
+    <Description /> {/* Optional */}
+    <Checkbox value="option1">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Label {/* plain text — the clickable label */}
+      </Checkbox.Content>
+      <Description /> {/* Optional per-checkbox help text */}
+    </Checkbox>
+    <FieldError /> {/* Optional */}
+  </CheckboxGroup>
+);
+```
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview
+  name="checkbox-group-on-surface"
+/>
+
+### With Custom Indicator
+
+<ComponentPreview
+  name="checkbox-group-with-custom-indicator"
+/>
+
+### Indeterminate
+
+<ComponentPreview
+  name="checkbox-group-indeterminate"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="checkbox-group-controlled"
+/>
+
+### Validation
+
+<ComponentPreview
+  name="checkbox-group-validation"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="checkbox-group-disabled"
+/>
+
+### Features and Add-ons Example
+
+<ComponentPreview
+  name="checkbox-group-features-and-addons"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="checkbox-group-custom-render-function"
+/>
+
+<RelatedComponents component="checkboxgroup" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize the CheckboxGroup component:
+
+```tsx
+import { CheckboxGroup, Checkbox, Label } from '@heroui/react';
+
+function CustomCheckboxGroup() {
+  return (
+    <CheckboxGroup className="gap-4" name="custom">
+      <Checkbox value="option1">
+        <Checkbox.Content>
+          <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
+            <Checkbox.Indicator className="text-white" />
+          </Checkbox.Control>
+          Option 1
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the CheckboxGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .checkbox-group {
+    @apply flex flex-col gap-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The CheckboxGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)):
+
+- `.checkbox-group` - Base checkbox group container
+
+## API Reference
+
+### CheckboxGroup Props
+
+Inherits from [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string[]` | - | The current selected values (controlled) |
+| `defaultValue` | `string[]` | - | The default selected values (uncontrolled) |
+| `onChange` | `(value: string[]) => void` | - | Handler called when the selected values change |
+| `isDisabled` | `boolean` | `false` | Whether the checkbox group is disabled |
+| `isRequired` | `boolean` | `false` | Whether the checkbox group is required |
+| `isReadOnly` | `boolean` | `false` | Whether the checkbox group is read only |
+| `isInvalid` | `boolean` | `false` | Whether the checkbox group is in an invalid state |
+| `name` | `string` | - | The name of the checkbox group, used when submitting an HTML form |
+| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | Checkbox group content or render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### CheckboxGroupRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string[]` | The currently selected values |
+| `isDisabled` | `boolean` | Whether the checkbox group is disabled |
+| `isReadOnly` | `boolean` | Whether the checkbox group is read only |
+| `isInvalid` | `boolean` | Whether the checkbox group is in an invalid state |
+| `isRequired` | `boolean` | Whether the checkbox group is required |
+
diff --git a/apps/docs/content/docs/en/react/components/(forms)/checkbox.mdx b/apps/docs/content/docs/en/react/components/(forms)/checkbox.mdx
new file mode 100644
index 0000000..f2d828d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/checkbox.mdx
@@ -0,0 +1,263 @@
+---
+title: Checkbox
+description: Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
+icon: updated
+links:
+  rac: CheckboxField
+  source: checkbox/checkbox.tsx
+  styles: checkbox.css
+  storybook: Components/Forms/Checkbox
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Checkbox } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+### Anatomy
+
+Import the Checkbox component and access all parts using dot notation.
+
+```tsx
+import { Checkbox, Description, FieldError } from '@heroui/react';
+
+export default () => (
+  <Checkbox>
+    <Checkbox.Content>
+      <Checkbox.Control>
+        <Checkbox.Indicator />
+      </Checkbox.Control>
+      Label {/* plain text — the clickable label + accessible name */}
+    </Checkbox.Content>
+    <Description /> {/* Optional — field-level help text */}
+    <FieldError /> {/* Optional — validation message */}
+  </Checkbox>
+);
+```
+
+### Disabled
+
+<ComponentPreview
+  name="checkbox-disabled"
+/>
+
+### Default Selected
+
+<ComponentPreview
+  name="checkbox-default-selected"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="checkbox-controlled"
+/>
+
+### Indeterminate
+
+<ComponentPreview
+  name="checkbox-indeterminate"
+/>
+
+### External Label
+
+<ComponentPreview
+  name="checkbox-external-label"
+/>
+
+### With Description
+
+<ComponentPreview
+  name="checkbox-with-description"
+/>
+
+### Render Props
+
+<ComponentPreview
+  name="checkbox-render-props"
+/>
+
+### Form Integration
+
+<ComponentPreview
+  name="checkbox-form"
+/>
+
+### Invalid
+
+<ComponentPreview
+  name="checkbox-invalid"
+/>
+
+### Custom Indicator
+
+<ComponentPreview
+  name="checkbox-custom-indicator"
+/>
+
+### Full Rounded
+
+<ComponentPreview
+  name="checkbox-full-rounded"
+/>
+
+### Variants
+
+The Checkbox component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with default background, suitable for most use cases
+- **`secondary`** - Lower emphasis variant, suitable for use in Surface components
+
+<ComponentPreview name="checkbox-variants" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="checkbox-custom-render-function"
+/>
+
+<RelatedComponents component="checkbox" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual Checkbox components:
+
+```tsx
+import { Checkbox } from '@heroui/react';
+
+function CustomCheckbox() {
+  return (
+    <Checkbox name="custom">
+      <Checkbox.Content>
+        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
+          <Checkbox.Indicator className="text-white" />
+        </Checkbox.Control>
+        Custom Checkbox
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Checkbox component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .checkbox {
+    @apply inline-flex gap-3 items-center;
+  }
+
+  .checkbox__control {
+    @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;
+
+    /* Animated background indicator */
+    &::before {
+      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
+      
+      transition:
+        scale 200ms linear,
+        opacity 200ms linear,
+        background-color 200ms ease-out;
+    }
+
+    /* Show indicator when selected */
+    &[data-selected="true"]::before {
+      @apply scale-100 opacity-100;
+    }
+  }
+
+  .checkbox__indicator {
+    @apply text-white;
+  }
+
+  .checkbox__content {
+    @apply items-center gap-3;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Checkbox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)):
+
+- `.checkbox` - Base checkbox container (the field)
+- `.checkbox__content` - Clickable label wrapping the control and label text
+- `.checkbox__control` - Checkbox control box
+- `.checkbox__indicator` - Checkbox checkmark indicator
+
+### Interactive States
+
+The checkbox supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Selected**: `[data-selected="true"]` or `[aria-checked="true"]` (shows checkmark and background color change)
+- **Indeterminate**: `[data-indeterminate="true"]` (shows indeterminate state with dash)
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (shows error state with danger colors)
+- **Hover**: `:hover` or `[data-hovered="true"]` on `Checkbox.Control` (button)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on control)
+- **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text)
+- **Pressed**: `:active` or `[data-pressed="true"]`
+
+## API Reference
+
+### Checkbox Props
+
+Inherits from [React Aria CheckboxField](https://react-spectrum.adobe.com/react-aria/Checkbox.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isSelected` | `boolean` | `false` | Whether the checkbox is checked |
+| `defaultSelected` | `boolean` | `false` | Whether the checkbox is checked by default (uncontrolled) |
+| `isIndeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate state |
+| `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled |
+| `isInvalid` | `boolean` | `false` | Whether the checkbox is invalid |
+| `isReadOnly` | `boolean` | `false` | Whether the checkbox is read only |
+| `isRequired` | `boolean` | `false` | Whether the checkbox must be selected |
+| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | Custom validation function |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
+| `value` | `string` | - | The value of the input element, used when submitting an HTML form |
+| `onChange` | `(isSelected: boolean) => void` | - | Handler called when the checkbox value changes |
+| `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | Checkbox content or field render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Checkbox.Content Props
+
+The clickable `<label>` that wraps the control and label text. Put `Checkbox.Control` and the `Label` inside it; keep `Description`/`FieldError` as siblings of `Checkbox.Content`. For a checkbox with no label, omit the `Label` and pass an `aria-label` on `Checkbox`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | Button content (control + label), or a button render prop |
+| `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | Classes applied to the clickable label |
+
+### CheckboxFieldRenderProps
+
+When using a render prop on the root `Checkbox`, these field-level values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the checkbox is currently checked |
+| `isIndeterminate` | `boolean` | Whether the checkbox is in an indeterminate state |
+| `isDisabled` | `boolean` | Whether the checkbox is disabled |
+| `isReadOnly` | `boolean` | Whether the checkbox is read only |
+| `isInvalid` | `boolean` | Whether the checkbox is invalid |
+| `isRequired` | `boolean` | Whether the checkbox is required |
+
+### CheckboxButtonRenderProps
+
+`Checkbox.Control` and `Checkbox.Indicator` use button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Checkbox.Control` children or to `Checkbox.Indicator` to access them.
diff --git a/apps/docs/content/docs/en/react/components/(forms)/description.mdx b/apps/docs/content/docs/en/react/components/(forms)/description.mdx
new file mode 100644
index 0000000..ee3a370
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/description.mdx
@@ -0,0 +1,73 @@
+---
+title: Description
+description: Provides supplementary text for form fields and other components
+links:
+  rac: TextField
+  source: description/description.tsx
+  styles: description.css
+---
+
+## Import
+
+```tsx
+import { Description } from '@heroui/react';
+```
+
+## Usage
+
+<ComponentPreview
+  name="description-basic"
+/>
+
+<RelatedComponents component="description" />
+
+## API
+
+### Description Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The content of the description |
+
+## Accessibility
+
+The Description component enhances accessibility by:
+
+- Using semantic HTML that screen readers can identify
+- Providing the `slot="description"` attribute for React Aria integration
+- Supporting proper text contrast ratios
+
+## Styling
+
+The Description component uses the following CSS classes:
+
+- `.description` - Base description styles with `muted` text color
+
+## Examples
+
+### With Form Fields
+
+```tsx
+<div className="flex flex-col gap-1">
+  <Label htmlFor="password">Password</Label>
+  <Input id="password" type="password" aria-describedby="password-description" />
+  <Description id="password-description">
+    Must be at least 8 characters with one uppercase letter
+  </Description>
+</div>
+```
+ 
+### Integration with TextField
+
+```tsx
+import {TextField, Label, Input, Description} from '@heroui/react';
+
+<TextField type="email">
+  <Label>Email</Label>
+  <Input placeholder="Enter your email" />
+  <Description>We'll never share your email</Description>
+</TextField>
+```
+
+When using the [TextField](./text-field) component, accessibility attributes are automatically applied to the label and description.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(forms)/error-message.mdx b/apps/docs/content/docs/en/react/components/(forms)/error-message.mdx
new file mode 100644
index 0000000..04bc97e
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/error-message.mdx
@@ -0,0 +1,116 @@
+---
+title: ErrorMessage
+description: A low-level error message component for displaying errors
+links:
+  rac: TagGroup
+  source: error-message/error-message.tsx
+  styles: error-message.css
+---
+
+## Import
+
+```tsx
+import { ErrorMessage } from '@heroui/react';
+```
+
+## Usage
+
+`ErrorMessage` is a low-level component built on React Aria's `Text` component with an `errorMessage` slot. It's designed for displaying error messages in **non-form components** such as `TagGroup`, `Calendar`, and other collection-based components.
+
+<ComponentPreview
+  name="error-message-basic"
+/>
+
+### Anatomy
+
+```tsx
+import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';
+
+<TagGroup>
+  <Label />
+  <TagGroup.List>
+    <Tag />
+  </TagGroup.List>
+  <Description />
+  <ErrorMessage />
+</TagGroup>
+```
+
+<RelatedComponents component="errormessage" />
+
+## When to Use
+
+`ErrorMessage` is **not tied to forms**. It's a generic error display component for non-form contexts.
+
+- **Recommended for** non-form components (e.g., `TagGroup`, `Calendar`, collection components)
+- **For form fields**, we recommend using [`FieldError`](/docs/components/field-error) instead, which provides form-specific validation features and automatic error handling, following standardized form validation patterns.
+
+## ErrorMessage vs FieldError
+
+| Component | Use Case | Form Integration | Example Components |
+|-----------|----------|------------------|---------------------|
+| `ErrorMessage` | Non-form components | No | `TagGroup`, `Calendar` |
+| `FieldError` | Form fields (recommended) | Yes | `TextField`, `NumberField`, `Select` |
+
+For form validation, we recommend using `FieldError` as it follows standardized form validation patterns and provides form-specific features. See the [FieldError documentation](/docs/components/field-error) and the [Form guide](/docs/components/form) for examples and best practices.
+
+## API Reference
+
+### ErrorMessage Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The error message content |
+
+**Note**: `ErrorMessage` is built on React Aria's `Text` component with `slot="errorMessage"`. It can be targeted using the `[slot=errorMessage]` CSS selector.
+
+## Accessibility
+
+The ErrorMessage component enhances accessibility by:
+
+- Using semantic HTML that screen readers can identify
+- Providing the `slot="errorMessage"` attribute for React Aria integration
+- Supporting proper text contrast ratios for error states
+- Following WAI-ARIA best practices for error messaging
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ErrorMessage } from '@heroui/react';
+
+function CustomErrorMessage() {
+  return (
+    <ErrorMessage className="font-bold text-sm">
+      Custom styled error message
+    </ErrorMessage>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ErrorMessage component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .error-message {
+    @apply text-red-600 text-sm font-medium;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ErrorMessage component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)):
+
+#### Base Classes
+- `.error-message` - Base error message styles with danger color and text truncation
+
+#### Slot Classes
+- `[slot="errorMessage"]` - ErrorMessage slot styles for React Aria integration
diff --git a/apps/docs/content/docs/en/react/components/(forms)/field-error.mdx b/apps/docs/content/docs/en/react/components/(forms)/field-error.mdx
new file mode 100644
index 0000000..bdae390
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/field-error.mdx
@@ -0,0 +1,121 @@
+---
+title: FieldError
+description: Displays validation error messages for form fields
+links:
+  rac: FieldError
+  source: field-error/field-error.tsx
+  styles: field-error.css
+---
+
+## Import
+
+```tsx
+import { FieldError } from '@heroui/react';
+```
+
+## Usage
+
+The FieldError component displays validation error messages for form fields. It automatically appears when the parent field is marked as invalid and provides smooth opacity transitions.
+
+<ComponentPreview
+  name="field-error-basic"
+/>
+
+<RelatedComponents component="fielderror" />
+
+## API
+
+### FieldError Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | Error message content or render function |
+
+## Accessibility
+
+The FieldError component ensures accessibility by:
+
+- Using proper ARIA attributes for error announcement
+- Supporting screen readers with semantic HTML
+- Providing visual and programmatic error indication
+- Automatically managing visibility based on validation state
+
+## Styling
+
+The FieldError component uses the following CSS classes:
+
+- `.field-error` - Base error styles with danger color
+- Only shows when the `data-visible` attribute is present
+- Text is truncated with ellipsis for long messages
+
+## Examples
+
+### Basic Validation
+
+```tsx
+export function Basic() {
+  const [value, setValue] = useState("");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <TextField className="w-64" isInvalid={isInvalid}>
+      <Label htmlFor="username">Username</Label>
+      <Input
+        id="username"
+        placeholder="Enter username"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <FieldError>Username must be at least 3 characters</FieldError>
+    </TextField>
+  );
+}
+```
+
+### With Dynamic Messages
+
+```tsx
+<TextField isInvalid={errors.length > 0}>
+  <Label>Password</Label>
+  <Input type="password" />
+  <FieldError>
+    {(validation) => validation.validationErrors.join(', ')}
+  </FieldError>
+</TextField>
+```
+
+### Custom Validation Logic
+
+```tsx
+function EmailField() {
+  const [email, setEmail] = useState('');
+  const isInvalid = email.length > 0 && !email.includes('@');
+
+  return (
+    <TextField isInvalid={isInvalid}>
+      <Label>Email</Label>
+      <Input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <FieldError>Email must include @ symbol</FieldError>
+    </TextField>
+  );
+}
+```
+
+### Multiple Error Messages
+
+```tsx
+<TextField isInvalid={hasErrors}>
+  <Label>Username</Label>
+  <Input />
+  <FieldError>
+    {errors.map((error, i) => (
+      <div key={i}>{error}</div>
+    ))}
+  </FieldError>
+</TextField>
+```
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(forms)/fieldset.mdx b/apps/docs/content/docs/en/react/components/(forms)/fieldset.mdx
new file mode 100644
index 0000000..141c7e8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/fieldset.mdx
@@ -0,0 +1,144 @@
+---
+title: Fieldset
+description: Group related form controls with legends, descriptions, and actions
+links:
+  source: fieldset/fieldset.tsx
+  styles: fieldset.css
+  storybook: Components/Forms/Fieldset
+---
+
+## Import
+
+```tsx
+import { Fieldset } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="fieldset-basic" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on form controls (Input, TextArea, etc.) to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="fieldset-on-surface" />
+
+### Anatomy
+
+Import the Fieldset component and access all parts using dot notation.
+
+```tsx
+import { Fieldset } from '@heroui/react';
+
+export default () => (
+  <Fieldset>
+    <Fieldset.Legend />
+    <Fieldset.Group>
+      {/* form fields go here */}
+    </Fieldset.Group>
+    <Fieldset.Actions>
+      {/* action buttons go here */}
+    </Fieldset.Actions>
+  </Fieldset>
+)
+```
+
+<RelatedComponents component="fieldset" />
+
+<RelatedShowcases component="Fieldset" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Fieldset, TextField, Label, Input } from '@heroui/react';
+
+function CustomFieldset() {
+  return (
+    <Fieldset className="rounded-xl border border-border bg-surface p-6 shadow-sm">
+      <Fieldset.Legend className="text-lg font-semibold">Team members</Fieldset.Legend>
+      <Fieldset.Group className="grid gap-4 md:grid-cols-2">
+        <TextField>
+          <Label>First name</Label>
+          <Input className="rounded-full border-border/60" placeholder="Jane" />
+        </TextField>
+        <TextField>
+          <Label>Last name</Label>
+          <Input className="rounded-full border-border/60" placeholder="Doe" />
+        </TextField>
+      </Fieldset.Group>
+      <Fieldset.Actions className="justify-end gap-3">
+        {/* Action buttons */}
+      </Fieldset.Actions>
+    </Fieldset>
+  );
+}
+```
+
+### Customizing the component classes
+
+Use the `@layer components` directive to target Fieldset [BEM](https://getbem.com/)-style classes.
+
+```css
+@layer components {
+  .fieldset {
+    @apply gap-5 rounded-xl border border-border/60 bg-surface p-6 shadow-field;
+  }
+
+  .fieldset__legend {
+    @apply text-lg font-semibold;
+  }
+
+  .fieldset__field_group {
+    @apply gap-3 md:grid md:grid-cols-2;
+  }
+
+  .fieldset__actions {
+    @apply flex justify-end gap-2 pt-2;
+  }
+}
+```
+
+### CSS Classes
+
+The Fieldset compound component exposes these CSS selectors:
+
+- `.fieldset` – Root container
+- `.fieldset__legend` – Legend element
+- `.fieldset__field_group` – Wrapper for grouped fields
+- `.fieldset__actions` – Action bar below the fields
+
+## API Reference
+
+### Fieldset Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind CSS classes applied to the root element. |
+| `children` | `React.ReactNode` | - | Fieldset content (legend, groups, descriptions, actions). |
+| `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | Supports native fieldset attributes and events. |
+
+### Fieldset.Legend Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes for the legend element. |
+| `children` | `React.ReactNode` | - | Legend content, usually plain text. |
+| `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` |  - | Native legend attributes. |
+
+### Fieldset.Group Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Layout and spacing classes for grouped fields. |
+| `children` | `React.ReactNode` | - | Form controls to group inside the fieldset. |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | Native div attributes. |
+
+### Fieldset.Actions Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes to align action buttons or text. |
+| `children` | `React.ReactNode` | - | Action buttons or helper text. |
+| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | Native div attributes. |
diff --git a/apps/docs/content/docs/en/react/components/(forms)/form.mdx b/apps/docs/content/docs/en/react/components/(forms)/form.mdx
new file mode 100644
index 0000000..6d594b5
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/form.mdx
@@ -0,0 +1,158 @@
+---
+title: Form
+description: Wrapper component for form validation and submission handling
+links:
+  source: form/form.tsx
+  rac: https://react-spectrum.adobe.com/react-aria/Form.html
+---
+
+## Import
+
+```tsx
+import { Form } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="form-basic" />
+
+### Anatomy
+
+Import all parts and piece them together.
+
+```tsx
+import {Form, Button} from '@heroui/react';
+
+export default () => (
+  <Form>
+    {/* Form fields go here */}
+    <Button type="submit"/>
+    <Button type="reset"/>
+  </Form>
+)
+```
+
+### Custom Render Function
+
+<ComponentPreview
+  name="form-custom-render-function"
+/>
+
+<RelatedComponents component="form" />
+
+<RelatedShowcases component="Form" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react';
+
+function CustomForm() {
+  return (
+    <Form className="w-full max-w-md space-y-4 rounded-lg border border-border bg-surface p-6">
+      <TextField>
+        <Label className="text-sm font-medium">Email</Label>
+        <Input className="rounded-full border-border/60" placeholder="Enter your email" />
+        <FieldError className="text-xs" />
+      </TextField>
+      <Button type="submit" className="w-full">
+        Submit
+      </Button>
+    </Form>
+  );
+}
+```
+
+## API Reference
+
+### Form Props
+
+The Form component is a wrapper around React Aria's Form primitive that provides form validation and submission handling capabilities.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `action` | `string \| FormHTMLAttributes['action']` | - | The URL to submit the form data to. |
+| `className` | `string` | - | Tailwind CSS classes applied to the form element. |
+| `children` | `React.ReactNode` | - | Form content (fields, buttons, etc.). |
+| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | The encoding type for form data submission. |
+| `method` | `'get' \| 'post'` | - | The HTTP method to use when submitting the form. |
+| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form validation fails. By default, the first invalid field will be focused. Use `preventDefault()` to customize focus behavior. |
+| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is reset. |
+| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is submitted. |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | Where to display the response after submitting the form. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML validation or ARIA validation. 'native' blocks form submission, 'aria' displays errors in realtime. |
+| `validationErrors` | `ValidationErrors` | - | Server-side validation errors mapped by field name. Displayed immediately and cleared when user modifies the field. |
+| `aria-label` | `string` | - | Accessibility label for the form. |
+| `aria-labelledby` | `string` | - | ID of element that labels the form. Creates a form landmark when provided. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function.|
+
+### Form Validation
+
+The Form component integrates with React Aria's validation system, allowing you to:
+
+- Use built-in HTML5 validation attributes (`required`, `minLength`, `pattern`, etc.)
+- Provide custom validation functions on TextField components
+- Display validation errors with FieldError components
+- Handle form submission with proper validation
+- Provide server-side validation errors via `validationErrors` prop
+
+#### Validation Behavior
+
+The `validationBehavior` prop controls how validation is displayed:
+
+- **`native`** (default): Uses native HTML validation, blocks form submission on errors
+- **`aria`**: Uses ARIA attributes for validation, displays errors in realtime as user types, doesn't block submission
+
+This behavior can be set at the form level or overridden at individual field level.
+
+### Form Submission
+
+Forms can be submitted in several ways:
+
+- **Traditional submission**: Set the `action` prop to submit to a URL
+- **JavaScript handling**: Use the `onSubmit` handler to process form data
+- **FormData API**: Access form data using the FormData API in your submit handler
+
+Example with FormData:
+
+```tsx
+function handleSubmit(e: FormEvent<HTMLFormElement>) {
+  e.preventDefault();
+  const formData = new FormData(e.currentTarget);
+  const data = Object.fromEntries(formData);
+  console.log('Form data:', data);
+}
+```
+
+### Integration with Form Fields
+
+The Form component works seamlessly with HeroUI's form field components:
+
+- **TextField**: For text inputs with labels and validation
+- **Checkbox**: For boolean selections
+- **RadioGroup**: For single selection from multiple options
+- **Switch**: For toggle controls
+- **Button**: For form submission and reset actions
+
+All field components automatically integrate with the Form's validation and submission behavior when placed inside it.
+
+### Accessibility
+
+Forms are accessible by default when using React Aria components. Key features include:
+
+- Native `<form>` element semantics
+- Form landmark creation with `aria-label` or `aria-labelledby`
+- Automatic focus management on validation errors
+- ARIA validation attributes when using `validationBehavior="aria"`
+
+### Advanced Usage
+
+For more advanced use cases including:
+- Custom validation context
+- Form context providers
+- Integration with third-party libraries
+- Custom focus management on validation errors
+
+Please refer to the [React Aria Form documentation](https://react-spectrum.adobe.com/react-aria/Form.html).
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(forms)/input-group.mdx b/apps/docs/content/docs/en/react/components/(forms)/input-group.mdx
new file mode 100644
index 0000000..a3d46bd
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/input-group.mdx
@@ -0,0 +1,380 @@
+---
+title: InputGroup
+description: Group related input controls with prefix and suffix elements for enhanced form fields
+links:
+  rac: Group
+  source: input-group/input-group.tsx
+  styles: input-group.css
+  storybook: Components/Forms/InputGroup
+  figma: true
+---
+
+## Import
+
+```tsx
+import { InputGroup } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="input-group-default" />
+
+### Anatomy
+
+```tsx
+import {InputGroup, TextField, Label} from '@heroui/react';
+
+export default () => (
+  <TextField>
+    <Label />
+    <InputGroup>
+      <InputGroup.Prefix />
+      <InputGroup.Input /> {/* Or use InputGroup.TextArea for multiline input */}
+      <InputGroup.Suffix />
+    </InputGroup>
+  </TextField>
+)
+```
+
+> **InputGroup** wraps an input field with optional prefix and suffix elements, creating a visually cohesive group. It's typically used within **[TextField](/docs/components/text-field)** to add icons, text, buttons, or other elements before or after the input. Use **InputGroup.Input** for single-line inputs or **InputGroup.TextArea** for multiline text inputs.
+
+### With Prefix Icon
+
+Add an icon before the input field.
+
+<ComponentPreview name="input-group-with-prefix-icon" />
+
+### With Suffix Icon
+
+Add an icon after the input field.
+
+<ComponentPreview name="input-group-with-suffix-icon" />
+
+### With Prefix and Suffix
+
+Combine both prefix and suffix elements.
+
+<ComponentPreview name="input-group-with-prefix-and-suffix" />
+
+### Text Prefix
+
+Use text as a prefix, such as currency symbols or protocol prefixes.
+
+<ComponentPreview name="input-group-with-text-prefix" />
+
+### Text Suffix
+
+Use text as a suffix, such as domain extensions or units.
+
+<ComponentPreview name="input-group-with-text-suffix" />
+
+### Icon Prefix and Text Suffix
+
+Combine an icon prefix with a text suffix.
+
+<ComponentPreview name="input-group-with-icon-prefix-and-text-suffix" />
+
+### Copy Button Suffix
+
+Add an interactive button in the suffix, such as a copy button.
+
+<ComponentPreview name="input-group-with-copy-suffix" />
+
+### Icon Prefix and Copy Button
+
+Combine an icon prefix with an interactive button suffix.
+
+<ComponentPreview name="input-group-with-icon-prefix-and-copy-suffix" />
+
+### Password Toggle
+
+Use a button in the suffix to toggle password visibility.
+
+<ComponentPreview name="input-group-password-with-toggle" />
+
+### Loading State
+
+Show a loading spinner in the suffix to indicate processing.
+
+<ComponentPreview name="input-group-with-loading-suffix" />
+
+### Keyboard Shortcut
+
+Display keyboard shortcuts using the [Kbd](/docs/components/kbd) component.
+
+<ComponentPreview name="input-group-with-keyboard-shortcut" />
+
+### Badge Suffix
+
+Add a badge or chip in the suffix to show status or labels.
+
+<ComponentPreview name="input-group-with-badge-suffix" />
+
+### Required Field
+
+InputGroup respects the required state from its parent TextField.
+
+<ComponentPreview name="input-group-required" />
+
+### Validation
+
+InputGroup automatically reflects invalid state from its parent TextField.
+
+<ComponentPreview name="input-group-invalid" />
+
+### Disabled State
+
+InputGroup respects the disabled state from its parent TextField.
+
+<ComponentPreview name="input-group-disabled" />
+
+### Full Width
+
+<ComponentPreview name="input-group-full-width" />
+
+### Variants
+
+The InputGroup component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="input-group-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="input-group-on-surface" />
+
+### With TextArea
+
+Use **InputGroup.TextArea** for multiline text inputs with prefix and suffix elements. When a textarea is present, the container automatically adjusts its height to accommodate the content and aligns prefix/suffix elements to the top.
+
+<ComponentPreview name="input-group-with-textarea" />
+
+<RelatedComponents component="inputgroup" />
+
+<RelatedShowcases component="InputGroup" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {InputGroup, TextField, Label} from '@heroui/react';
+
+function CustomInputGroup() {
+  return (
+    <TextField>
+      <Label>Website</Label>
+      <InputGroup className="rounded-xl border-2 border-primary">
+        <InputGroup.Prefix className="bg-primary/10 text-primary">
+          https://
+        </InputGroup.Prefix>
+        <InputGroup.Input className="font-medium" />
+        <InputGroup.Suffix className="bg-primary/10 text-primary">
+          .com
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
+```
+
+### Customizing the component classes
+
+InputGroup uses CSS classes that can be customized. Override the component classes to match your design system.
+
+```css
+@layer components {
+  .input-group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex min-h-9 items-center overflow-hidden border text-sm outline-none;
+  }
+
+  .input-group__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .input-group__prefix {
+    @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3;
+  }
+
+  .input-group__suffix {
+    @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3;
+  }
+
+  /* Secondary variant */
+  .input-group--secondary {
+    @apply shadow-none;
+    background-color: var(--color-default);
+  }
+}
+```
+
+### CSS Classes
+
+- `.input-group` – Root container with border, background, and flex layout. Uses `min-h-9` for flexible height and `items-center` by default, switching to `items-start` when a textarea is present.
+- `.input-group__input` – Input element with transparent background and no border. Also used as the base class for textarea elements.
+- `.input-group__prefix` – Prefix container with left border radius. Aligns to top when used with textarea.
+- `.input-group__suffix` – Suffix container with right border radius. Aligns to top when used with textarea.
+- `.input-group--primary` – Primary variant with shadow (default)
+- `.input-group--secondary` – Secondary variant without shadow, suitable for use in surfaces
+
+**Note**: When using `InputGroup.TextArea`, the container automatically switches from `items-center` to `items-start` alignment and uses `height: auto` instead of a fixed height. Prefix and suffix elements align to the top with additional padding to match the textarea's vertical padding. The textarea uses the same `.input-group__input` base class with textarea-specific styles (minimum height and vertical resize) applied via the `[data-slot="input-group-textarea"]` attribute selector.
+
+### Interactive States
+
+InputGroup automatically manages these data attributes based on its state:
+
+- **Hover**: `[data-hovered]` - Applied when hovering over the group
+- **Focus Within**: `[data-focus-within]` - Applied when the input is focused
+- **Invalid**: `[data-invalid]` - Applied when parent TextField is invalid
+- **Disabled**: `[data-disabled]` or `[aria-disabled]` - Applied when parent TextField is disabled
+
+## API Reference
+
+### InputGroup Props
+
+InputGroup inherits all props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (Input, TextArea, Prefix, Suffix) or render function. |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the input group should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+
+#### Variant Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this group. |
+| `aria-describedby` | `string` | - | ID of elements that describe this group. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+| `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | Accessibility role for the group. Use 'region' for important content, 'presentation' for visual-only grouping. |
+
+### Composition Components
+
+InputGroup works with these subcomponents:
+
+- **InputGroup.Root** - Root container (also available as `InputGroup`)
+- **InputGroup.Input** - Single-line input element component
+- **InputGroup.TextArea** - Multiline textarea element component
+- **InputGroup.Prefix** - Prefix container component
+- **InputGroup.Suffix** - Suffix container component
+
+#### InputGroup.Input Props
+
+InputGroup.Input inherits all props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | CSS classes for styling. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `type` | `string` | `'text'` | Input type (text, password, email, etc.). |
+| `value` | `string` | - | Current value (controlled). |
+| `defaultValue` | `string` | - | Default value (uncontrolled). |
+| `placeholder` | `string` | - | Placeholder text. |
+| `disabled` | `boolean` | - | Whether the input is disabled. |
+| `readOnly` | `boolean` | - | Whether the input is read-only. |
+
+#### InputGroup.TextArea Props
+
+InputGroup.TextArea inherits all props from React Aria's [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | CSS classes for styling. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the textarea. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `value` | `string` | - | Current value (controlled). |
+| `defaultValue` | `string` | - | Default value (uncontrolled). |
+| `placeholder` | `string` | - | Placeholder text. |
+| `rows` | `number` | - | Number of visible text lines. |
+| `disabled` | `boolean` | - | Whether the textarea is disabled. |
+| `readOnly` | `boolean` | - | Whether the textarea is read-only. |
+
+#### InputGroup.Prefix Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display in the prefix (icons, text, etc.). |
+| `className` | `string` | - | CSS classes for styling. |
+
+#### InputGroup.Suffix Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display in the suffix (icons, buttons, badges, etc.). |
+| `className` | `string` | - | CSS classes for styling. |
+
+### Usage Example
+
+```tsx
+import {InputGroup, TextField, Label, Button} from '@heroui/react';
+import {Icon} from '@iconify/react';
+
+function Example() {
+  return (
+    <TextField>
+      <Label>Email</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon icon="gravity-ui:envelope" />
+        </InputGroup.Prefix>
+        <InputGroup.Input placeholder="name@email.com" />
+        <InputGroup.Suffix>
+          <Button isIconOnly size="sm" variant="ghost">
+            <Icon icon="gravity-ui:check" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
+```
+
+### TextArea Usage Example
+
+```tsx
+import {Envelope} from "@gravity-ui/icons";
+import {Description, FieldError, InputGroup, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+function TextAreaExample() {
+  const [feedback, setFeedback] = useState("");
+
+  return (
+    <TextField fullWidth isInvalid={feedback.length > 500} name="feedback" onChange={setFeedback}>
+      <Label>Your Feedback</Label>
+      <InputGroup fullWidth>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.TextArea
+          className="resize-none"
+          placeholder="Share your thoughts, suggestions, or issues..."
+          rows={5}
+          value={feedback}
+        />
+      </InputGroup>
+      <Description className="flex w-full items-center justify-between px-1">
+        <span>Maximum 500 characters.</span>
+        <span className="ml-auto">{feedback.length}/500</span>
+      </Description>
+      <FieldError>Feedback must be less than 500 characters</FieldError>
+    </TextField>
+  );
+}
+```
+
diff --git a/apps/docs/content/docs/en/react/components/(forms)/input-otp.mdx b/apps/docs/content/docs/en/react/components/(forms)/input-otp.mdx
new file mode 100644
index 0000000..0cfc7c8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/input-otp.mdx
@@ -0,0 +1,289 @@
+---
+title: InputOTP
+description: A one-time password input component for verification codes and secure authentication
+links:
+  source: input-otp/input-otp.tsx
+  styles: input-otp.css
+  storybook: Components/Forms/InputOTP
+  figma: true
+---
+
+## Import
+
+```tsx
+import { InputOTP } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="input-otp-basic" />
+
+### Anatomy
+
+Import the InputOTP component and access all parts using dot notation.
+
+```tsx
+import { InputOTP } from '@heroui/react';
+
+export default () => (
+  <InputOTP maxLength={6}>
+    <InputOTP.Group>
+      <InputOTP.Slot index={0} />
+      <InputOTP.Slot index={1} />
+      {/* ...rest of the slots */}
+    </InputOTP.Group>
+    <InputOTP.Separator />
+    <InputOTP.Group>
+      <InputOTP.Slot index={3} />
+      {/* ...rest of the slots */}
+    </InputOTP.Group>
+  </InputOTP>
+)
+```
+
+> **InputOTP** is built on top of [input-otp](https://github.com/guilhermerodz/input-otp) by [@guilherme_rodz](https://twitter.com/guilherme_rodz), providing a flexible and accessible foundation for OTP input components.
+
+### Four Digits
+
+<ComponentPreview name="input-otp-four-digits" />
+
+### Disabled State
+
+<ComponentPreview name="input-otp-disabled" />
+
+### With Pattern
+
+Use the `pattern` prop to restrict input to specific characters. HeroUI exports common patterns like `REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS`.
+
+<ComponentPreview name="input-otp-with-pattern" />
+
+### Controlled
+
+Control the value to synchronize with state, clear the input, or implement custom validation.
+
+<ComponentPreview name="input-otp-controlled" />
+
+### With Validation
+
+Use `isInvalid` together with validation messages to surface errors.
+
+<ComponentPreview name="input-otp-with-validation" />
+
+### On Complete
+
+Use the `onComplete` callback to trigger actions when all slots are filled.
+
+<ComponentPreview name="input-otp-on-complete" />
+
+### Form Example
+
+A complete two-factor authentication form with validation and submission.
+
+<ComponentPreview name="input-otp-form-example" />
+
+### Variants
+
+The InputOTP component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="input-otp-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="input-otp-on-surface" />
+
+<RelatedComponents component="inputotp" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {InputOTP, Label} from '@heroui/react';
+
+function CustomInputOTP() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label className="text-sm font-semibold">Enter verification code</Label>
+      <InputOTP
+        className="gap-3"
+        containerClassName="gap-4"
+        maxLength={6}
+      >
+        <InputOTP.Group className="gap-3">
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={0}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={1}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={2}
+          />
+        </InputOTP.Group>
+        <InputOTP.Separator className="bg-border h-1 w-2 rounded-full" />
+        <InputOTP.Group className="gap-3">
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={3}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={4}
+          />
+          <InputOTP.Slot
+            className="size-12 rounded-lg border-2 text-lg font-bold"
+            index={5}
+          />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the InputOTP component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .input-otp {
+    @apply gap-3;
+  }
+
+  .input-otp__slot {
+    @apply size-12 rounded-xl border-2 font-bold;
+  }
+
+  .input-otp__slot[data-active="true"] {
+    @apply border-primary-500 ring-2 ring-primary-200;
+  }
+
+  .input-otp__separator {
+    @apply w-2 h-1 bg-border-strong rounded-full;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The InputOTP component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)):
+
+#### Base Classes
+- `.input-otp` - Base container
+- `.input-otp__container` - Inner container from input-otp library
+- `.input-otp__group` - Group of slots
+- `.input-otp__slot` - Individual input slot
+- `.input-otp__slot-value` - The character inside a slot
+- `.input-otp__caret` - Blinking caret indicator
+- `.input-otp__separator` - Visual separator between groups
+
+#### State Classes
+- `.input-otp__slot[data-active="true"]` - Currently active slot
+- `.input-otp__slot[data-filled="true"]` - Slot with a character
+- `.input-otp__slot[data-disabled="true"]` - Disabled slot
+- `.input-otp__slot[data-invalid="true"]` - Invalid slot
+- `.input-otp__container[data-disabled="true"]` - Disabled container
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on slot
+- **Active**: `[data-active="true"]` on slot (currently focused)
+- **Filled**: `[data-filled="true"]` on slot (contains a character)
+- **Disabled**: `[data-disabled="true"]` on container and slots
+- **Invalid**: `[data-invalid="true"]` on slots
+
+## API Reference
+
+### InputOTP Props
+
+InputOTP is built on top of the [input-otp](https://github.com/guilhermerodz/input-otp) library with additional features.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxLength` | `number` | - | **Required.** Number of input slots. |
+| `value` | `string` | - | Controlled value (uncontrolled if not provided). |
+| `onChange` | `(value: string) => void` | - | Handler called when the value changes. |
+| `onComplete` | `(value: string) => void` | - | Handler called when all slots are filled. |
+| `className` | `string` | - | Additional CSS classes for the container. |
+| `containerClassName` | `string` | - | CSS classes for the inner container. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `children` | `React.ReactNode` | - | InputOTP.Group, InputOTP.Slot, and InputOTP.Separator components. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | `false` | Whether the input is disabled. |
+| `isInvalid` | `boolean` | `false` | Whether the input is in an invalid state. |
+| `validationErrors` | `string[]` | - | Server-side or custom validation errors. |
+| `validationDetails` | `ValidityState` | - | HTML5 validation details. |
+
+#### Input Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `pattern` | `string` | - | Regex pattern for allowed characters (e.g., `REGEXP_ONLY_DIGITS`). |
+| `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment within slots. |
+| `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | Virtual keyboard type on mobile devices. |
+| `placeholder` | `string` | - | Placeholder text for empty slots. |
+| `pasteTransformer` | `(text: string) => string` | - | Transform pasted text (e.g., remove hyphens). |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name attribute for form submission. |
+| `autoFocus` | `boolean` | - | Whether to focus the first slot on mount. |
+
+### InputOTP.Group Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes for the group. |
+| `children` | `React.ReactNode` | - | InputOTP.Slot components. |
+
+### InputOTP.Slot Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `index` | `number` | - | **Required.** Zero-based index of the slot. |
+| `className` | `string` | - | Additional CSS classes for the slot. |
+
+### InputOTP.Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes for the separator. |
+
+### Exported Patterns
+
+HeroUI re-exports common regex patterns from input-otp for convenience:
+
+```tsx
+import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from '@heroui/react';
+
+// Use with pattern prop
+<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>
+  {/* ... */}
+</InputOTP>
+```
+
+- **REGEXP_ONLY_DIGITS** - Only numeric characters (0-9)
+- **REGEXP_ONLY_CHARS** - Only alphabetic characters (a-z, A-Z)
+- **REGEXP_ONLY_DIGITS_AND_CHARS** - Alphanumeric characters (0-9, a-z, A-Z)
diff --git a/apps/docs/content/docs/en/react/components/(forms)/input.mdx b/apps/docs/content/docs/en/react/components/(forms)/input.mdx
new file mode 100644
index 0000000..22e33e6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/input.mdx
@@ -0,0 +1,141 @@
+---
+title: Input
+description: Primitive single-line text input component that accepts standard HTML attributes
+links:
+  rac: Input
+  source: input/input.tsx
+  styles: input.css
+  storybook: Components/Forms/Input
+---
+
+## Import
+
+```tsx
+import { Input } from '@heroui/react';
+```
+
+<Callout>
+  For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**.
+</Callout>
+
+### Usage
+
+<ComponentPreview name="input-basic" />
+
+### Input Types
+
+<ComponentPreview name="input-types" />
+
+### Controlled
+
+<ComponentPreview name="input-controlled" />
+
+### Full Width
+
+<ComponentPreview name="input-full-width" />
+
+### Variants
+
+The Input component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="input-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="input-on-surface" />
+
+<RelatedComponents component="input" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Input, Label} from '@heroui/react';
+
+function CustomInput() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label htmlFor="custom-input">Project name</Label>
+      <Input
+        id="custom-input"
+        className="rounded-xl border border-border/70 bgsurface px-4 py-2 text-sm shadow-sm focus-visible:border-primary"
+        placeholder="New web app"
+      />
+    </div>
+  );
+}
+```
+
+### Customizing the component classes
+
+The base class `.input` powers every instance. Override it once with `@layer components`.
+
+```css
+@layer components {
+  .input {
+    @apply rounded-lg border border-border bgsurface px-4 py-2 text-sm shadow-sm transition-colors;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-surface-secondary border-border/80;
+    }
+
+    &:focus-visible,
+    &[data-focus-visible="true"] {
+      @apply border-primary ring-2 ring-primary/20;
+    }
+
+    &[data-invalid="true"] {
+      @apply border-danger bg-danger-50/10 text-danger;
+    }
+  }
+}
+```
+
+### CSS Classes
+
+- `.input` – Native input element styling
+
+### Interactive States
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+- **Read Only**: `[aria-readonly="true"]`
+
+## API Reference
+
+### Input Props
+
+Input accepts all standard HTML `<input>` attributes plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the component styles. |
+| `type` | `string` | `"text"` | Input type (text, email, password, number, etc.). |
+| `value` | `string` | - | Controlled value. |
+| `defaultValue` | `string` | - | Uncontrolled initial value. |
+| `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | Change handler. |
+| `placeholder` | `string` | - | Placeholder text. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+| `readOnly` | `boolean` | `false` | Makes the input read-only. |
+| `required` | `boolean` | `false` | Marks the input as required. |
+| `name` | `string` | - | Name for form submission. |
+| `autoComplete` | `string` | - | Autocomplete hint for the browser. |
+| `maxLength` | `number` | - | Maximum number of characters. |
+| `minLength` | `number` | - | Minimum number of characters. |
+| `pattern` | `string` | - | Regex pattern for validation. |
+| `min` | `number \| string` | - | Minimum value (for number/date inputs). |
+| `max` | `number \| string` | - | Maximum value (for number/date inputs). |
+| `step` | `number \| string` | - | Stepping interval (for number inputs). |
+| `fullWidth` | `boolean` | `false` | Whether the input should take full width of its container |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+> For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with Input as a child component.
diff --git a/apps/docs/content/docs/en/react/components/(forms)/label.mdx b/apps/docs/content/docs/en/react/components/(forms)/label.mdx
new file mode 100644
index 0000000..85927ba
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/label.mdx
@@ -0,0 +1,96 @@
+---
+title: Label
+description: Renders an accessible label associated with form controls
+links:
+  rac: TextField
+  source: label/label.tsx
+  styles: label.css
+---
+
+## Import
+
+```tsx
+import { Label } from '@heroui/react';
+```
+
+## Usage
+
+<ComponentPreview
+  name="label-basic"
+/>
+
+<RelatedComponents component="label" />
+
+## API
+
+### Label Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `htmlFor` | `string` | - | The id of the element the label is associated with |
+| `isRequired` | `boolean` | `false` | Whether to display a required indicator |
+| `isDisabled` | `boolean` | `false` | Whether the label is in a disabled state |
+| `isInvalid` | `boolean` | `false` | Whether the label is in an invalid state |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The content of the label |
+
+## Accessibility
+
+The Label component is built on the native HTML `<label>` element ([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)) and follows WAI-ARIA best practices:
+
+- Associates with form controls using the `htmlFor` attribute
+- Provides semantic HTML `<label>` element
+- Supports keyboard navigation when associated with form controls
+- Communicates required and invalid states to screen readers
+- Clicking the label focuses/activates the associated form control
+
+<RelatedComponents component="label" />
+
+## Styling
+
+### CSS Classes
+
+The Label component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)):
+
+#### Base Classes
+- `.label` - Base label styles with text styling
+
+#### State Modifier Classes
+- `.label--required` or `[data-required="true"] > .label` - Shows required asterisk indicator
+- `.label--disabled` or `[data-disabled="true"] .label` - Disabled state styling
+- `.label--invalid` or `[data-invalid="true"] .label` or `[aria-invalid="true"] .label` - Invalid state styling (danger/red text color)
+ 
+**Note**: The required asterisk is smartly applied using role and data-slot detection. It excludes:
+- Elements with `role="group"`, `role="radiogroup"`, or `role="checkboxgroup"`
+- Elements with `data-slot="radio"` or `data-slot="checkbox"`
+
+This prevents duplicate asterisks when using group components with required fields.
+
+## Examples
+
+### With Required Indicator
+
+```tsx
+<Label htmlFor="email" isRequired>
+  Email Address
+</Label>
+<Input id="email" type="email" />
+```
+
+### With Disabled State
+
+```tsx
+<Label htmlFor="username" isDisabled>
+  Username
+</Label>
+<Input id="username" isDisabled />
+```
+
+### With Invalid State
+
+```tsx
+<Label htmlFor="password" isInvalid>
+  Password
+</Label>
+<Input id="password" isInvalid />
+```
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(forms)/number-field.mdx b/apps/docs/content/docs/en/react/components/(forms)/number-field.mdx
new file mode 100644
index 0000000..5ee722d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/number-field.mdx
@@ -0,0 +1,364 @@
+---
+title: NumberField
+description: Number input fields with increment/decrement buttons, validation, and internationalized formatting
+links:
+  rac: NumberField
+  source: number-field/number-field.tsx
+  styles: number-field.css
+  storybook: Components/Forms/NumberField
+  figma: true
+---
+
+## Import
+
+```tsx
+import { NumberField } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="number-field-basic" />
+
+### Anatomy
+
+```tsx
+import {NumberField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <NumberField>
+    <Label />
+    <NumberField.Group>
+      <NumberField.DecrementButton />
+      <NumberField.Input />
+      <NumberField.IncrementButton />
+    </NumberField.Group>
+    <Description />
+    <FieldError />
+  </NumberField>
+)
+```
+
+> **NumberField** allows users to enter numeric values with optional increment/decrement buttons. It supports internationalized formatting, validation, and keyboard navigation.
+
+### With Description
+
+<ComponentPreview name="number-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="number-field-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="number-field-validation" />
+
+### Controlled
+
+Control the value to synchronize with other components or perform custom formatting.
+
+<ComponentPreview name="number-field-controlled" />
+
+### With Validation
+
+Implement custom validation logic with controlled values.
+
+<ComponentPreview name="number-field-with-validation" />
+
+### Step Values
+
+Configure increment/decrement step values for precise control.
+
+<ComponentPreview name="number-field-with-step" />
+
+### Format Options
+
+Format numbers as currency, percentages, decimals, or units with internationalization support.
+
+<ComponentPreview name="number-field-with-format-options" />
+
+### Custom Icons
+
+Customize the increment and decrement button icons.
+
+<ComponentPreview name="number-field-custom-icons" />
+
+### With Chevrons
+
+Use chevron icons in a vertical layout for a different visual style.
+
+<ComponentPreview name="number-field-with-chevrons" />
+
+### Disabled State
+
+<ComponentPreview name="number-field-disabled" />
+
+### Full Width
+
+<ComponentPreview name="number-field-full-width" />
+
+### Variants
+
+The NumberField component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="number-field-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="number-field-on-surface" />
+
+### Form Example
+
+Complete form integration with validation and submission handling.
+
+<ComponentPreview name="number-field-form-example" />
+
+<RelatedComponents component="numberfield" />
+
+<RelatedShowcases component="NumberField" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="number-field-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {NumberField, Label} from '@heroui/react';
+
+function CustomNumberField() {
+  return (
+    <NumberField className="gap-2">
+      <Label className="text-sm font-semibold">Quantity</Label>
+      <NumberField.Group className="rounded-xl border-2">
+        <NumberField.DecrementButton className="bg-gray-100" />
+        <NumberField.Input className="text-center font-bold" />
+        <NumberField.IncrementButton className="bg-gray-100" />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
+```
+
+### Customizing the component classes
+
+NumberField uses CSS classes that can be customized. Override the component classes to match your design system.
+
+```css
+@layer components {
+  .number-field {
+    @apply flex flex-col gap-1;
+  }
+
+  /* When invalid, the description is hidden automatically */
+  .number-field[data-invalid="true"] [data-slot="description"],
+  .number-field[aria-invalid="true"] [data-slot="description"] {
+    @apply hidden;
+  }
+
+  .number-field__group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
+  }
+
+  .number-field__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;
+  }
+
+  .number-field__increment-button,
+  .number-field__decrement-button {
+    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;
+  }
+}
+```
+
+### CSS Classes
+
+- `.number-field` – Root container with minimal styling (`flex flex-col gap-1`)
+- `.number-field__group` – Container for input and buttons with border and background styling
+- `.number-field__input` – The numeric input field
+- `.number-field__increment-button` – Button to increment the value
+- `.number-field__decrement-button` – Button to decrement the value
+- `.number-field--primary` – Primary variant with shadow (default)
+- `.number-field--secondary` – Secondary variant without shadow, suitable for use in surfaces
+
+> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options.
+
+### Interactive States
+
+NumberField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when the input or buttons are focused
+- **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)
+- **Hovered**: `[data-hovered="true"]` - Applied when hovering over buttons
+
+Additional attributes are available through render props (see NumberFieldRenderProps below).
+
+## API Reference
+
+### NumberField Props
+
+NumberField inherits all props from React Aria's [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode` | - | Child components (Label, Group, Input, etc.) or render function. |
+| `className` | `string \| (values: NumberFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the number field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | - | Current value (controlled). |
+| `defaultValue` | `number` | - | Default value (uncontrolled). |
+| `onChange` | `(value: number \| undefined) => void` | - | Handler called when the value changes. |
+
+#### Formatting Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formatOptions` | `Intl.NumberFormatOptions` | - | Options for formatting numbers (currency, percent, decimal, unit). |
+| `locale` | `string` | - | Locale for number formatting. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `validate` | `(value: number) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+| `validationErrors` | `string[]` | - | Server-side validation errors. |
+
+#### Range Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `minValue` | `number` | - | Minimum allowed value. |
+| `maxValue` | `number` | - | Maximum allowed value. |
+| `step` | `number` | `1` | Step value for increment/decrement operations. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+NumberField works with these separate components that should be imported and used directly:
+
+- **NumberField.Group** - Container for input and buttons
+- **NumberField.Input** - The numeric input field
+- **NumberField.IncrementButton** - Button to increment the value
+- **NumberField.DecrementButton** - Button to decrement the value
+- **Label** - Field label component from `@heroui/react`
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within NumberField for composition:
+
+```tsx
+<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>
+  <Label>Quantity</Label>
+  <NumberField.Group>
+    <NumberField.DecrementButton />
+    <NumberField.Input />
+    <NumberField.IncrementButton />
+  </NumberField.Group>
+  <Description>Enter a value between 0 and 100</Description>
+  <FieldError>Value must be between 0 and 100</FieldError>
+</NumberField>
+```
+
+#### NumberField.Group Props
+
+NumberField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (Input, Buttons) or render function. |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling. |
+
+#### NumberField.Input Props
+
+NumberField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | CSS classes for styling. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+#### NumberField.IncrementButton Props
+
+NumberField.IncrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | `<IconPlus />` | Icon or content for the button. Defaults to plus icon. |
+| `className` | `string` | - | CSS classes for styling. |
+| `slot` | `"increment"` | `"increment"` | Must be set to "increment" (automatically set). |
+
+#### NumberField.DecrementButton Props
+
+NumberField.DecrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | `<IconMinus />` | Icon or content for the button. Defaults to minus icon. |
+| `className` | `string` | - | CSS classes for styling. |
+| `slot` | `"decrement"` | `"decrement"` | Must be set to "decrement" (automatically set). |
+
+### NumberFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
+| `value` | `number \| undefined` | Current value. |
+| `minValue` | `number \| undefined` | Minimum allowed value. |
+| `maxValue` | `number \| undefined` | Maximum allowed value. |
+| `step` | `number` | Step value for increment/decrement. |
+
diff --git a/apps/docs/content/docs/en/react/components/(forms)/radio-group.mdx b/apps/docs/content/docs/en/react/components/(forms)/radio-group.mdx
new file mode 100644
index 0000000..dea43ed
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/radio-group.mdx
@@ -0,0 +1,283 @@
+---
+title: RadioGroup
+description: Radio group for selecting a single option from a list
+icon: updated
+links:
+  rac: RadioField
+  source: radio-group/radio-group.tsx
+  styles: radio-group.css
+  storybook: Components/Forms/RadioGroup
+---
+
+## Import
+
+```tsx
+import { RadioGroup, Radio } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+### Anatomy
+
+Import the RadioGroup component and access all parts using dot notation.
+
+```tsx
+import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <RadioGroup>
+    <Label />
+    <Description />
+    <Radio value="option1">
+      <Radio.Content> {/* The clickable area: control + label */}
+        <Radio.Control>
+          <Radio.Indicator>
+            <span>✓</span> {/* Custom indicator (optional) */}
+          </Radio.Indicator>
+        </Radio.Control>
+        Label {/* plain text — the clickable label */}
+      </Radio.Content>
+      <Description /> {/* Sibling — stays outside the button (announced via aria-describedby) */}
+      <FieldError /> {/* Optional — per-radio validation message */}
+    </Radio>
+    <FieldError /> {/* Optional — group-level validation */}
+  </RadioGroup>
+)
+```
+
+### Custom Indicator
+
+<ComponentPreview
+  name="radio-group-custom-indicator"
+/>
+
+### Horizontal Orientation
+
+<ComponentPreview
+  name="radio-group-horizontal"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="radio-group-controlled"
+/>
+
+### Uncontrolled
+
+Combine `defaultValue` with `onChange` when you only need to react to updates.
+
+<ComponentPreview
+  name="radio-group-uncontrolled"
+/>
+
+### Validation
+
+<ComponentPreview
+  name="radio-group-validation"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="radio-group-disabled"
+/>
+
+### Variants
+
+The RadioGroup component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with default background, suitable for most use cases
+- **`secondary`** - Lower emphasis variant, suitable for use in Surface components
+
+<ComponentPreview name="radio-group-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview
+  name="radio-group-on-surface"
+/>
+
+### Delivery & Payment
+
+<ComponentPreview
+  isBgSolid
+  align="start"
+  name="radio-group-delivery-and-payment"
+/>
+
+<RelatedShowcases component="RadioGroup" />
+
+<RelatedComponents component="radiogroup" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="radio-group-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { RadioGroup, Radio } from '@heroui/react';
+
+export default () => (
+  <RadioGroup defaultValue="premium" name="plan">
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-blue-300 data-[selected=true]:border-blue-500 data-[selected=true]:bg-blue-500/10"
+      value="basic"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-blue-400 group-data-[selected=true]:border-blue-500 group-data-[selected=true]:bg-blue-500" />
+      Basic Plan
+    </Radio>
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-purple-300 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500/10"
+      value="premium"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-purple-400 group-data-[selected=true]:border-purple-500 group-data-[selected=true]:bg-purple-500" />
+      Premium Plan
+    </Radio>
+    <Radio
+      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-emerald-300 data-[selected=true]:border-emerald-500 data-[selected=true]:bg-emerald-500/10"
+      value="business"
+    >
+      <Radio.Indicator className="border-border border-2 group-hover:border-emerald-400 group-data-[selected=true]:border-emerald-500 group-data-[selected=true]:bg-emerald-500" />
+      Business Plan
+    </Radio>
+  </RadioGroup>
+);
+```
+
+### Customizing the component classes
+
+To customize the RadioGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .radio-group {
+    @apply gap-2;
+  }
+
+  .radio {
+    @apply gap-4 rounded-lg border border-border p-3 hover:bg-surface-hovered;
+  }
+
+  .radio__control {
+    @apply border-2 border-primary;
+  }
+
+  .radio__indicator {
+    @apply bg-primary;
+  }
+
+  .radio__content {
+    @apply gap-1;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The RadioGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)):
+
+#### Base Classes
+- `.radio-group` - Base radio group container
+- `.radio` - Individual radio item
+- `.radio__content` - Radio button (RAC label wrapper for control + label text)
+- `.radio__control` - Radio control (circular button)
+- `.radio__indicator` - Radio indicator (inner dot)
+- `.radio__content` - Radio content wrapper
+
+#### Modifier Classes
+- `.radio--disabled` - Disabled radio state
+
+### Interactive States
+
+The radio supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Selected**: `[aria-checked="true"]` or `[data-selected="true"]` (indicator appears)
+- **Hover**: `:hover` or `[data-hovered="true"]` (border color changes)
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
+- **Pressed**: `:active` or `[data-pressed="true"]` (scale transform)
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (error border color)
+
+## API Reference
+
+### RadioGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | The current value (controlled) |
+| `defaultValue` | `string` | - | The default value (uncontrolled) |
+| `onChange` | `(value: string) => void` | - | Handler called when the value changes |
+| `isDisabled` | `boolean` | `false` | Whether the radio group is disabled |
+| `isRequired` | `boolean` | `false` | Whether the radio group is required |
+| `isReadOnly` | `boolean` | `false` | Whether the radio group is read only |
+| `isInvalid` | `boolean` | `false` | Whether the radio group is in an invalid state |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `name` | `string` | - | The name of the radio group, used when submitting an HTML form |
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the radio group |
+| `children` | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | - | Radio group content or render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioGroupRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Radio Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | The value of the radio button |
+| `isDisabled` | `boolean` | `false` | Whether the radio button is disabled |
+| `name` | `string` | - | The name of the radio button, used when submitting an HTML form |
+| `children` | `React.ReactNode \| (values: RadioFieldRenderProps) => React.ReactNode` | - | Radio content or field render prop |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Radio.Control Props
+
+Extends `React.HTMLAttributes<HTMLSpanElement>`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | The content to render inside the control wrapper (typically Radio.Indicator) |
+
+### Radio.Indicator Props
+
+Extends `React.HTMLAttributes<HTMLSpanElement>`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | Optional content or render prop that receives the current radio button state. |
+
+### Radio.Content Props
+
+The clickable area of the radio (the `<label>` wrapping the hidden input). Place `Radio.Control` and the `Label` inside it. `className` accepts a render function that receives `RadioButtonRenderProps`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | The clickable content (typically Radio.Control and Label) |
+
+### RadioFieldRenderProps
+
+When using a render prop on the root `Radio`, these field-level values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isSelected` | `boolean` | Whether the radio is currently selected |
+| `isDisabled` | `boolean` | Whether the radio is disabled |
+| `isReadOnly` | `boolean` | Whether the radio is read only |
+| `isInvalid` | `boolean` | Whether the radio is in an invalid state |
+| `isRequired` | `boolean` | Whether the radio is required |
+
+### RadioButtonRenderProps
+
+`Radio.Control` and `Radio.Indicator` use button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Radio.Control` children or to `Radio.Indicator` to access them.
diff --git a/apps/docs/content/docs/en/react/components/(forms)/search-field.mdx b/apps/docs/content/docs/en/react/components/(forms)/search-field.mdx
new file mode 100644
index 0000000..1be0dab
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/search-field.mdx
@@ -0,0 +1,349 @@
+---
+title: SearchField
+description: Search input field with clear button and search icon
+links:
+  rac: SearchField
+  source: search-field/search-field.tsx
+  styles: search-field.css
+  storybook: Components/Forms/SearchField
+  figma: true
+---
+
+## Import
+
+```tsx
+import { SearchField } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="search-field-basic" />
+
+### Anatomy
+
+```tsx
+import {SearchField, Label, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <SearchField>
+    <Label />
+    <SearchField.Group>
+      <SearchField.SearchIcon />
+      <SearchField.Input />
+      <SearchField.ClearButton />
+    </SearchField.Group>
+    <Description />
+    <FieldError />
+  </SearchField>
+)
+```
+
+> **SearchField** allows users to enter and clear a search query. It includes a search icon and an optional clear button for easy reset.
+
+### With Description
+
+<ComponentPreview name="search-field-with-description" />
+
+### Required Field
+
+<ComponentPreview name="search-field-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="search-field-validation" />
+
+### Disabled State
+
+<ComponentPreview name="search-field-disabled" />
+
+### Controlled
+
+Control the value to synchronize with other components or perform custom formatting.
+
+<ComponentPreview name="search-field-controlled" />
+
+### With Validation
+
+Implement custom validation logic with controlled values.
+
+<ComponentPreview name="search-field-with-validation" />
+
+### Custom Icons
+
+Customize the search icon and clear button icons.
+
+<ComponentPreview name="search-field-custom-icons" />
+
+### Full Width
+
+<ComponentPreview name="search-field-full-width" />
+
+### Variants
+
+The SearchField component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="search-field-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="search-field-on-surface" />
+
+### Form Example
+
+Complete form integration with validation and submission handling.
+
+<ComponentPreview name="search-field-form-example" />
+
+### With Keyboard Shortcut
+
+Add keyboard shortcuts to quickly focus the search field.
+
+<ComponentPreview name="search-field-with-keyboard-shortcut" />
+
+<RelatedComponents component="searchfield" />
+
+<RelatedShowcases component="SearchField" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="search-field-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {SearchField, Label} from '@heroui/react';
+
+function CustomSearchField() {
+  return (
+    <SearchField className="gap-2">
+      <Label className="text-sm font-semibold">Search</Label>
+      <SearchField.Group className="rounded-xl border-2">
+        <SearchField.SearchIcon className="text-blue-500" />
+        <SearchField.Input className="text-center font-bold" />
+        <SearchField.ClearButton className="text-red-500" />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
+```
+
+### Customizing the component classes
+
+SearchField uses CSS classes that can be customized. Override the component classes to match your design system.
+
+```css
+@layer components {
+  .search-field {
+    @apply flex flex-col gap-1;
+  }
+
+  /* When invalid, the description is hidden automatically */
+  .search-field[data-invalid],
+  .search-field[aria-invalid] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  .search-field__group {
+    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
+  }
+
+  .search-field__input {
+    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
+  }
+
+  .search-field__search-icon {
+    @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4;
+  }
+
+  .search-field__clear-button {
+    @apply mr-1 shrink-0;
+  }
+}
+```
+
+### CSS Classes
+
+- `.search-field` – Root container with minimal styling (`flex flex-col gap-1`)
+- `.search-field__group` – Container for search icon, input, and clear button with border and background styling
+- `.search-field__input` – The search input field
+- `.search-field__search-icon` – The search icon displayed on the left
+- `.search-field__clear-button` – Button to clear the search field
+- `.search-field--primary` – Primary variant with shadow (default)
+- `.search-field--secondary` – Secondary variant without shadow, suitable for use in surfaces
+
+> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options.
+
+### Interactive States
+
+SearchField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when the input is focused
+- **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)
+- **Hovered**: `[data-hovered="true"]` - Applied when hovering over the group
+- **Empty**: `[data-empty="true"]` - Applied when the field is empty (hides clear button)
+
+Additional attributes are available through render props (see SearchFieldRenderProps below).
+
+## API Reference
+
+### SearchField Props
+
+SearchField inherits all props from React Aria's [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode` | - | Child components (Label, Group, Input, etc.) or render function. |
+| `className` | `string \| (values: SearchFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the search field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | Current value (controlled). |
+| `defaultValue` | `string` | - | Default value (uncontrolled). |
+| `onChange` | `(value: string) => void` | - | Handler called when the value changes. |
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+| `validationErrors` | `string[]` | - | Server-side validation errors. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+
+#### Event Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSubmit` | `(value: string) => void` | - | Handler called when the user submits the search (Enter key). |
+| `onClear` | `() => void` | - | Handler called when the clear button is pressed. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+SearchField works with these separate components that should be imported and used directly:
+
+- **SearchField.Group** - Container for search icon, input, and clear button
+- **SearchField.Input** - The search input field
+- **SearchField.SearchIcon** - The search icon displayed on the left
+- **SearchField.ClearButton** - Button to clear the search field
+- **Label** - Field label component from `@heroui/react`
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within SearchField for composition:
+
+```tsx
+<SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}>
+  <Label>Search</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input placeholder="Search..." />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description>Enter keywords to search</Description>
+  <FieldError>Search query is required</FieldError>
+</SearchField>
+```
+
+#### SearchField.Group Props
+
+SearchField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (SearchIcon, Input, ClearButton) or render function. |
+| `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling. |
+
+#### SearchField.Input Props
+
+SearchField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | CSS classes for styling. |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `placeholder` | `string` | - | Placeholder text displayed when the input is empty. |
+| `type` | `string` | `"search"` | Input type (automatically set to "search"). |
+
+#### SearchField.SearchIcon Props
+
+SearchField.SearchIcon is a custom component that renders the search icon.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | `<IconSearch />` | Custom icon element. Defaults to search icon. |
+| `className` | `string` | - | CSS classes for styling. |
+
+#### SearchField.ClearButton Props
+
+SearchField.ClearButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | `<CloseButton icon />` | Icon or content for the button. Defaults to close icon. |
+| `className` | `string` | - | CSS classes for styling. |
+| `slot` | `"clear"` | `"clear"` | Must be set to "clear" (automatically set). |
+
+### SearchFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
+| `value` | `string` | Current value. |
+| `isEmpty` | `boolean` | Whether the field is empty. |
+
diff --git a/apps/docs/content/docs/en/react/components/(forms)/text-area.mdx b/apps/docs/content/docs/en/react/components/(forms)/text-area.mdx
new file mode 100644
index 0000000..3d7fbe3
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/text-area.mdx
@@ -0,0 +1,142 @@
+---
+title: TextArea
+description: Primitive multiline text input component that accepts standard HTML attributes
+links:
+  rac: TextArea
+  source: textarea/textarea.tsx
+  styles: textarea.css
+  storybook: Components/Forms/Textarea
+---
+
+## Import
+
+```tsx
+import { TextArea } from '@heroui/react';
+```
+
+<Callout>
+  For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**.
+</Callout>
+
+### Usage
+
+<ComponentPreview name="textarea-basic" />
+
+### Controlled
+
+<ComponentPreview name="textarea-controlled" />
+
+### Rows and Resizing
+
+<ComponentPreview name="textarea-rows" />
+
+### Full Width
+
+<ComponentPreview name="textarea-full-width" />
+
+### Variants
+
+The TextArea component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="textarea-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="textarea-on-surface" />
+
+<RelatedComponents component="textarea" />
+
+<RelatedShowcases component="TextArea" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Label, TextArea} from '@heroui/react';
+
+function CustomTextArea() {
+  return (
+    <div className="flex flex-col gap-2">
+      <Label htmlFor="custom-textarea">Message</Label>
+      <TextArea
+        id="custom-textarea"
+        className="rounded-xl border border-border/70 bgsurface px-4 py-3 text-sm leading-6 shadow-sm"
+        placeholder="Let us know how we can help..."
+        rows={5}
+        style={{resize: "vertical"}}
+      />
+    </div>
+  );
+}
+```
+
+### Customizing the component classes
+
+Override the shared `.textarea` class once with Tailwind's `@layer components`.
+
+```css
+@layer components {
+  .textarea {
+    @apply rounded-xl border border-border bgsurface px-4 py-3 text-sm leading-6 shadow-sm;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-surface-secondary border-border/80;
+    }
+
+    &:focus-visible,
+    &[data-focus-visible="true"] {
+      @apply border-primary ring-2 ring-primary/20;
+    }
+
+    &[data-invalid="true"] {
+      @apply border-danger bg-danger-50/10 text-danger;
+    }
+  }
+}
+```
+
+### CSS Classes
+
+- `.textarea` – Underlying `<textarea>` element styling
+
+### Interactive States
+
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Invalid**: `[data-invalid="true"]`
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+
+## API Reference
+
+### TextArea Props
+
+TextArea accepts all standard HTML `<textarea>` attributes plus the following:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Tailwind classes merged with the base styles. |
+| `rows` | `number` | `3` | Number of visible text lines. |
+| `cols` | `number` | - | Visible width of the text control. |
+| `value` | `string` | - | Controlled value for the textarea. |
+| `defaultValue` | `string` | - | Initial uncontrolled value. |
+| `onChange` | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | Change handler. |
+| `placeholder` | `string` | - | Placeholder text. |
+| `disabled` | `boolean` | `false` | Disables the textarea. |
+| `readOnly` | `boolean` | `false` | Makes the textarea read-only. |
+| `required` | `boolean` | `false` | Marks the textarea as required. |
+| `name` | `string` | - | Name for form submission. |
+| `autoComplete` | `string` | - | Autocomplete hint for the browser. |
+| `maxLength` | `number` | - | Maximum number of characters. |
+| `minLength` | `number` | - | Minimum number of characters. |
+| `wrap` | `'soft' \| 'hard'` | - | How text wraps when submitted. |
+| `fullWidth` | `boolean` | `false` | Whether the textarea should take full width of its container |
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+
+> For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with TextArea as a child component.
diff --git a/apps/docs/content/docs/en/react/components/(forms)/text-field.mdx b/apps/docs/content/docs/en/react/components/(forms)/text-field.mdx
new file mode 100644
index 0000000..31e0dae
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(forms)/text-field.mdx
@@ -0,0 +1,251 @@
+---
+title: TextField
+description: Composition-friendly text fields with labels, descriptions, and inline validation
+links:
+  rac: TextField
+  source: textfield/textfield.tsx
+  styles: textfield.css
+  storybook: Components/Forms/TextField
+  figma: true
+---
+
+## Import
+
+```tsx
+import { TextField } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="textfield-basic" />
+
+### Anatomy
+
+```tsx
+import {TextField, Label, Input, Description, FieldError} from '@heroui/react';
+
+export default () => (
+  <TextField>
+    <Label />
+    <Input />
+    <Description />
+    <FieldError />
+  </TextField>
+)
+```
+
+>  **TextField** combines label, input, description, and error into a single accessible component.
+For standalone inputs, use **[Input](/docs/components/input)** or **[TextArea](/docs/components/textarea)**.
+
+### With Description
+
+<ComponentPreview name="textfield-with-description" />
+
+### Required Field
+
+<ComponentPreview name="textfield-required" />
+
+### Validation
+
+Use `isInvalid` together with `FieldError` to surface validation messages.
+
+<ComponentPreview name="textfield-validation" />
+
+### Controlled
+
+Control the value to synchronize counters, previews, or formatting.
+
+<ComponentPreview name="textfield-controlled" />
+
+### Error Message
+
+<ComponentPreview name="textfield-with-error" />
+
+### Disabled State
+
+<ComponentPreview name="textfield-disabled" />
+
+### TextArea
+
+Use [TextArea](/docs/components/textarea) instead of [Input](/docs/components/input) for multiline content.
+
+<ComponentPreview name="textfield-textarea" />
+
+### Input Types
+
+<ComponentPreview name="textfield-input-types" />
+
+### Full Width
+
+<ComponentPreview name="textfield-full-width" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on Input or TextArea components to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="textfield-on-surface" />
+
+<RelatedComponents component="textfield" />
+
+<RelatedShowcases component="TextField" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="textfield-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {TextField, Label, Input, Description} from '@heroui/react';
+
+function CustomTextField() {
+  return (
+    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
+      <Label className="text-sm font-semibold text-default-700">
+        Project name
+      </Label>
+      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
+      <Description className="text-xs text-default-500">
+        Keep it short and memorable.
+      </Description>
+    </TextField>
+  );
+}
+```
+
+### Customizing the component classes
+
+TextField has minimal default styling. Override the `.textfield` class to customize the container styling.
+
+```css
+@layer components {
+  .textfield {
+    @apply flex flex-col gap-1;
+  }
+
+  /* When invalid, the description is hidden automatically */
+  .textfield[data-invalid="true"] [data-slot="description"],
+  .textfield[aria-invalid="true"] [data-slot="description"] {
+    @apply hidden;
+  }
+
+  /* Description has default padding */
+  .textfield [data-slot="description"] {
+    @apply px-1;
+  }
+}
+```
+
+### CSS Classes
+
+- `.textfield` – Root container with minimal styling (`flex flex-col gap-1`)
+
+> **Note:** Child components ([Label](/docs/components/label), [Input](/docs/components/input), [TextArea](/docs/components/textarea), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options.
+
+### Interactive States
+
+TextField automatically manages these data attributes based on its state:
+
+- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
+- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
+- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
+- **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)
+
+Additional attributes are available through render props (see TextFieldRenderProps below).
+
+## API Reference
+
+### TextField Props
+
+TextField inherits all props from React Aria's [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) component.
+
+#### Base Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode` | - | Child components (Label, Input, etc.) or render function. |
+| `className` | `string \| (values: TextFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
+| `style` | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
+| `fullWidth` | `boolean` | `false` | Whether the text field should take full width of its container |
+| `id` | `string` | - | The element's unique identifier. |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+#### Validation Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
+| `isInvalid` | `boolean` | - | Whether the value is invalid. |
+| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
+| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
+| `validationErrors` | `string[]` | - | Server-side validation errors. |
+
+#### Value Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | Current value (controlled). |
+| `defaultValue` | `string` | - | Default value (uncontrolled). |
+| `onChange` | `(value: string) => void` | - | Handler called when the value changes. |
+
+#### State Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | - | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
+
+#### Form Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Name of the input element, for HTML form submission. |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
+
+#### Accessibility Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
+| `aria-labelledby` | `string` | - | ID of elements that label this field. |
+| `aria-describedby` | `string` | - | ID of elements that describe this field. |
+| `aria-details` | `string` | - | ID of elements with additional details. |
+
+### Composition Components
+
+TextField works with these separate components that should be imported and used directly:
+
+- **Label** - Field label component from `@heroui/react`
+- **Input** - Single-line text input from `@heroui/react`
+- **TextArea** - Multi-line text input from `@heroui/react`
+- **Description** - Helper text component from `@heroui/react`
+- **FieldError** - Validation error message from `@heroui/react`
+
+Each of these components has its own props API. Use them directly within TextField for composition:
+
+```tsx
+<TextField isRequired isInvalid={hasError}>
+  <Label>Email Address</Label>
+  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+  <Description>We'll never share your email.</Description>
+  <FieldError>Please enter a valid email address.</FieldError>
+</TextField>
+```
+
+### TextFieldRenderProps
+
+When using render props with `className`, `style`, or `children`, these values are available:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isDisabled` | `boolean` | Whether the field is disabled. |
+| `isInvalid` | `boolean` | Whether the field is currently invalid. |
+| `isReadOnly` | `boolean` | Whether the field is read-only. |
+| `isRequired` | `boolean` | Whether the field is required. |
+| `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
+| `isFocusWithin` | `boolean` | Whether any child element is focused. |
+| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
diff --git a/apps/docs/content/docs/en/react/components/(layout)/card.mdx b/apps/docs/content/docs/en/react/components/(layout)/card.mdx
new file mode 100644
index 0000000..20eb16e
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(layout)/card.mdx
@@ -0,0 +1,193 @@
+---
+title: Card
+description: Flexible container component for grouping related content and actions
+links:
+  source: card/card.tsx
+  styles: card.css
+  storybook: Components/Layout/Card
+---
+
+## Import
+
+```tsx
+import { Card } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview
+  name="card-default"
+/>
+
+### Anatomy
+
+Import the Card component and access all parts using dot notation.
+
+```tsx
+import { Card } from "@heroui/react";
+
+export default () => (
+  <Card>
+    <Card.Header>
+      <Card.Title />
+      <Card.Description />
+    </Card.Header>
+    <Card.Content />
+    <Card.Footer />
+  </Card>
+);
+```
+
+### Variants
+
+Cards come in semantic variants that describe their prominence level rather than specific visual styles. This allows themes to interpret them differently:
+
+<ComponentPreview
+  name="card-variants"
+/>
+
+- **`transparent`** - Minimal prominence, transparent background (great for nested cards)
+- **`default`** - Standard card for most use cases (surface-secondary)
+- **`secondary`** - Medium prominence to draw moderate attention (surface-tertiary)
+- **`tertiary`** - Higher prominence for important content (surface-tertiary)
+
+### Horizontal Layout
+
+<ComponentPreview
+  name="card-horizontal"
+/>
+
+### With Avatar
+
+<ComponentPreview
+  name="card-with-avatar"
+/>
+
+### With Images
+
+<ComponentPreview
+  name="card-with-images"
+/>
+
+### With Form
+
+<ComponentPreview
+  name="card-with-form"
+/>
+
+## Accessibility
+
+```tsx
+import { Card } from '@heroui/react';
+import { cardVariants } from '@heroui/styles';
+
+// Semantic markup
+<Card role="article" aria-labelledby="card-title">
+  <Card.Header>
+    <Card.Title id="card-title">Article Title</Card.Title>
+  </Card.Header>
+</Card>
+
+// Interactive cards
+<a className={cardVariants().base()} href="/details" aria-label="View product details">
+  <Card.Title>Product Name</Card.Title>
+</a>
+```
+
+<RelatedComponents component="card" />
+
+## Styling
+
+### Component Customization
+
+```tsx
+<Card className="border-2 border-blue-500 bg-gradient-to-r from-blue-50 to-purple-50">
+  <Card.Header>
+    <Card.Title className="text-blue-900">Custom Styled Card</Card.Title>
+    <Card.Description className="text-blue-700">Custom colors applied</Card.Description>
+  </Card.Header>
+  <Card.Content>
+    <p className="text-blue-800">Content with custom styling</p>
+  </Card.Content>
+</Card>
+```
+
+### CSS Variable Overrides
+
+```css
+/* Override specific variants */
+.card--secondary {
+  @apply bg-gradient-to-br from-blue-50 to-purple-50;
+}
+
+/* Custom element styles */
+.card__title {
+  @apply text-xl font-bold;
+}
+```
+
+## CSS Classes
+
+Card uses [BEM](https://getbem.com/) naming for predictable styling, ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)):
+
+
+#### Base Classes
+
+- `.card` - Base container with padding and border
+- `.card__header` - Header section container
+- `.card__title` - Title with base font size and weight
+- `.card__description` - Muted description text
+- `.card__content` - Flexible content container
+- `.card__footer` - Footer with row layout
+
+#### Variant Classes
+
+- `.card--transparent` - Minimal prominence, transparent background (maps to `transparent` variant)
+- `.card--default` - Standard appearance with surface-secondary (default)
+- `.card--secondary` - Medium prominence with surface-tertiary (maps to `secondary` variant)
+- `.card--tertiary` - Higher prominence with surface-tertiary (maps to `tertiary` variant)
+
+## API Reference
+
+### Card
+
+| Prop        | Type                                                      | Default      | Description                |
+| ----------- | --------------------------------------------------------- | ------------ | -------------------------- |
+| `variant`   | `"transparent" \| "default" \| "secondary" \| "tertiary"`         | `"default"` | Semantic variant indicating prominence level |
+| `className` | `string`                          | -       | Additional CSS classes     |
+| `children`  | `React.ReactNode`                 | -       | Card content               |
+
+### Card.Header
+
+| Prop        | Type              | Default | Description               |
+| ----------- | ----------------- | ------- | ------------------------- |
+| `className` | `string`          | -       | Additional CSS classes    |
+| `children`  | `React.ReactNode` | -       | Header content            |
+
+### Card.Title
+
+| Prop        | Type              | Default | Description                      |
+| ----------- | ----------------- | ------- | -------------------------------- |
+| `className` | `string`          | -       | Additional CSS classes           |
+| `children`  | `React.ReactNode` | -       | Title content (renders as `h3`) |
+
+### Card.Description
+
+| Prop        | Type              | Default | Description                     |
+| ----------- | ----------------- | ------- | ------------------------------- |
+| `className` | `string`          | -       | Additional CSS classes          |
+| `children`  | `React.ReactNode` | -       | Description content (renders as `p`) |
+
+### Card.Content
+
+| Prop        | Type              | Default | Description               |
+| ----------- | ----------------- | ------- | ------------------------- |
+| `className` | `string`          | -       | Additional CSS classes    |
+| `children`  | `React.ReactNode` | -       | Main content              |
+
+### Card.Footer
+
+| Prop        | Type              | Default | Description               |
+| ----------- | ----------------- | ------- | ------------------------- |
+| `className` | `string`          | -       | Additional CSS classes    |
+| `children`  | `React.ReactNode` | -       | Footer content            |
diff --git a/apps/docs/content/docs/en/react/components/(layout)/separator.mdx b/apps/docs/content/docs/en/react/components/(layout)/separator.mdx
new file mode 100644
index 0000000..6f6d758
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(layout)/separator.mdx
@@ -0,0 +1,114 @@
+---
+title: Separator
+description: Visually divide content sections
+links:
+  rac: Separator
+  source: separator/separator.tsx
+  styles: separator.css
+  storybook: Components/Layout/Separator
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Separator } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="separator-basic"
+/>
+
+### Vertical
+
+<ComponentPreview
+  name="separator-vertical"
+/>
+
+### With Content
+
+<ComponentPreview
+  name="separator-with-content"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="separator-variants"
+/>
+
+### With Surface
+
+The Separator component adapts to different surface backgrounds for better visibility.
+
+<ComponentPreview
+  name="separator-with-surface"
+/>
+
+<RelatedComponents component="separator" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="separator-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Separator} from '@heroui/react';
+
+function CustomSeparator() {
+  return (
+    <Separator className="my-8 bg-linear-to-r from-transparent via-default-500 to-transparent" />
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Separator component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .separator {
+    @apply bg-accent h-[2px];
+  }
+
+  .separator--vertical {
+    @apply bg-accent w-[2px];
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Separator component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/separator.css)):
+
+#### Base & Orientation Classes
+- `.separator` - Base separator styles with default horizontal orientation
+- `.separator--horizontal` - Horizontal orientation (full width, 1px height)
+- `.separator--vertical` - Vertical orientation (full height, 1px width)
+
+#### Variant Classes
+- `.separator--default` - Default variant with standard contrast
+- `.separator--secondary` - Secondary variant with medium contrast
+- `.separator--tertiary` - Tertiary variant with subtle contrast
+
+## API Reference
+
+### Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the separator |
+| `variant` | `'default' \| 'secondary' \| 'tertiary'` | `'default'` | The visual variant of the separator |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function.|
diff --git a/apps/docs/content/docs/en/react/components/(layout)/surface.mdx b/apps/docs/content/docs/en/react/components/(layout)/surface.mdx
new file mode 100644
index 0000000..4e427e8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(layout)/surface.mdx
@@ -0,0 +1,129 @@
+---
+title: Surface
+description: Container component that provides surface-level styling and context for child components
+links:
+  source: surface/surface.tsx
+  styles: surface.css
+  storybook: surface
+---
+
+## Import
+
+```tsx
+import { Surface } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="surface-variants"
+/>
+
+## Overview
+
+The Surface component is a semantic container that provides different levels of visual prominence through variants.
+
+### Variants
+
+Surface comes in semantic variants that describe their prominence level:
+
+- **`default`** - Standard surface appearance (bg-surface)
+- **`secondary`** - Medium prominence (bg-surface-secondary)
+- **`tertiary`** - Higher prominence (bg-surface-tertiary)
+
+## Usage with Form Components
+
+When using form components inside a Surface, use the `variant="secondary"` prop to apply the lower emphasis variant suitable for surface backgrounds.
+
+```tsx
+import { Surface, Input, TextArea } from '@heroui/react';
+
+function App() {
+  return (
+    <Surface variant="default">
+      <Input placeholder="Input with secondary variant" variant="secondary" />
+      <TextArea placeholder="TextArea with secondary variant" variant="secondary" />
+    </Surface>
+  );
+}
+```
+
+<RelatedComponents component="surface" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Surface } from '@heroui/react';
+
+function CustomSurface() {
+  return (
+    <Surface
+      className="rounded-2xl p-8 shadow-lg"
+      variant="secondary"
+    >
+      <h2>Custom Styled Surface</h2>
+      <p>Content goes here</p>
+    </Surface>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Surface component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .surface {
+    @apply rounded-2xl border border-border;
+  }
+
+  .surface--secondary {
+    @apply bg-gradient-to-br from-blue-50 to-purple-50;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Surface component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)):
+
+#### Base Classes
+- `.surface` - Base surface container
+
+#### Variant Classes
+- `.surface--default` - Default surface variant (bg-surface)
+- `.surface--secondary` - Secondary surface variant (bg-surface-secondary)
+- `.surface--tertiary` - Tertiary surface variant (bg-surface-tertiary)
+
+## API Reference
+
+### Surface Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | The visual variant of the surface |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The surface content |
+
+## Context API
+
+### SurfaceContext
+
+Child components can access the Surface context to get the current variant:
+
+```tsx
+import { useContext } from 'react';
+import { SurfaceContext } from '@heroui/react';
+
+function MyComponent() {
+  const { variant } = useContext(SurfaceContext);
+  // variant will be "transparent" | "default" | "secondary" | "tertiary" | undefined
+}
+```
+
diff --git a/apps/docs/content/docs/en/react/components/(layout)/toolbar.mdx b/apps/docs/content/docs/en/react/components/(layout)/toolbar.mdx
new file mode 100644
index 0000000..35b4bd0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(layout)/toolbar.mdx
@@ -0,0 +1,107 @@
+---
+title: Toolbar
+description: A container for interactive controls with arrow key navigation.
+links:
+  rac: Toolbar
+  source: toolbar/toolbar.tsx
+  styles: toolbar.css
+  storybook: Components/Layout/Toolbar
+---
+
+## Import
+
+```tsx
+import { Toolbar } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="toolbar-basic"
+/>
+
+### Vertical
+
+<ComponentPreview
+  name="toolbar-vertical"
+/>
+
+### With ButtonGroup
+
+<ComponentPreview
+  name="toolbar-with-button-group"
+/>
+
+### Attached
+
+<ComponentPreview
+  name="toolbar-attached"
+/>
+
+<RelatedComponents component="toolbar" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Toolbar } from '@heroui/react';
+
+function CustomToolbar() {
+  return (
+    <Toolbar
+      aria-label="Actions"
+      className="rounded-xl border border-default bg-surface p-2"
+    >
+      {/* toolbar content */}
+    </Toolbar>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Toolbar component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toolbar {
+    @apply gap-4 rounded-lg bg-surface p-3;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Toolbar component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toolbar.css)):
+
+- `.toolbar` - Base container
+- `.toolbar--horizontal` - Horizontal orientation (default)
+- `.toolbar--vertical` - Vertical orientation
+- `.toolbar--attached` - Attached variant with surface background and full rounding
+
+## API Reference
+
+### Toolbar Props
+
+Inherits from [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isAttached` | `boolean` | `false` | Whether the toolbar has a surface background with full rounding |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the toolbar |
+| `aria-label` | `string` | - | An accessible label for the toolbar |
+| `aria-labelledby` | `string` | - | The id of an element that labels the toolbar |
+| `children` | `React.ReactNode \| (values: ToolbarRenderProps) => React.ReactNode` | - | Content or render prop |
+| `className` | `string \| (values: ToolbarRenderProps) => string` | - | Additional CSS classes |
+
+### ToolbarRenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | The current orientation of the toolbar |
diff --git a/apps/docs/content/docs/en/react/components/(media)/avatar.mdx b/apps/docs/content/docs/en/react/components/(media)/avatar.mdx
new file mode 100644
index 0000000..eb59987
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(media)/avatar.mdx
@@ -0,0 +1,154 @@
+---
+title: Avatar
+description: Display user profile images with customizable fallback content
+links:
+  radix: avatar
+  source: avatar/avatar.tsx
+  styles: avatar.css
+  storybook: Components/Media/Avatar
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Avatar } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview name="avatar-basic" />
+
+### Anatomy
+
+Import the Avatar component and access all parts using dot notation.
+
+```tsx
+import { Avatar } from '@heroui/react';
+
+export default () => (
+  <Avatar>
+    <Avatar.Image/>
+    <Avatar.Fallback/>
+  </Avatar>
+)
+```
+
+### Sizes
+
+<ComponentPreview name="avatar-sizes" />
+
+### Colors
+
+<ComponentPreview name="avatar-colors" />
+
+### Variants
+
+<ComponentPreview name="avatar-variants" />
+
+### Fallback Content
+
+<ComponentPreview name="avatar-fallback" />
+
+### Avatar Group
+
+<ComponentPreview name="avatar-group" />
+
+### Custom Styles
+
+<ComponentPreview name="avatar-custom-styles" />
+
+<RelatedComponents component="avatar" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Avatar } from '@heroui/react';
+
+function CustomAvatar() {
+  return (
+    <Avatar className="size-20">
+      <Avatar.Image src="..." alt="..." />
+      <Avatar.Fallback>XL</Avatar.Fallback>
+    </Avatar>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Avatar component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .avatar {
+    @apply size-16 border-2 border-primary;
+  }
+
+  .avatar__fallback {
+    @apply bg-gradient-to-br from-purple-500 to-pink-500;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Avatar component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)):
+
+#### Base Classes
+- `.avatar` - Base container with default size (size-10)
+- `.avatar__image` - Image element with aspect-square sizing
+- `.avatar__fallback` - Fallback container with centered content
+
+#### Size Modifiers
+- `.avatar--sm` - Small avatar (size-8)
+- `.avatar--md` - Medium avatar (default, no additional styles)
+- `.avatar--lg` - Large avatar (size-12)
+
+#### Variant Modifiers
+- `.avatar--soft` - Soft variant with lighter background
+
+#### Color Modifiers
+- `.avatar__fallback--default` - Default text color
+- `.avatar__fallback--accent` - Accent text color
+- `.avatar__fallback--success` - Success text color
+- `.avatar__fallback--warning` - Warning text color
+- `.avatar__fallback--danger` - Danger text color
+
+## API Reference
+
+### Avatar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback color theme |
+| `variant` | `'default' \| 'soft'` | `'default'` | Visual style variant |
+| `className` | `string` | - | Additional CSS classes |
+
+### Avatar.Image Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | Image source URL |
+| `srcSet` | `string` | - | The image `srcset` attribute for responsive images |
+| `sizes` | `string` | - | The image `sizes` attribute for responsive images |
+| `alt` | `string` | - | Alternative text for the image |
+| `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | Callback when the image loads successfully |
+| `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | Callback when there's an error loading the image |
+| `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | CORS setting for the image request |
+| `loading` | `'eager' \| 'lazy'` | - | Native lazy loading attribute |
+| `className` | `string` | - | Additional CSS classes |
+
+### Avatar.Fallback Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `delayMs` | `number` | - | Delay before showing fallback (prevents flash) |
+| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Override color from parent |
+| `className` | `string` | - | Additional CSS classes |
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/accordion.mdx b/apps/docs/content/docs/en/react/components/(navigation)/accordion.mdx
new file mode 100644
index 0000000..6daffac
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/accordion.mdx
@@ -0,0 +1,300 @@
+---
+title: Accordion
+description: A collapsible content panel for organizing information in a compact space
+links:
+  rac: Disclosure
+  source: accordion/accordion.tsx
+  styles: accordion.css
+  storybook: Components/Navigation/Accordion
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Accordion } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="accordion-basic"
+  minHeight="400px"
+/>
+
+
+### Anatomy
+
+Import the Accordion component and access all parts using dot notation.
+
+```tsx
+import { Accordion } from '@heroui/react';
+
+export default () => (
+  <Accordion>
+    <Accordion.Item>
+      <Accordion.Heading>
+        <Accordion.Trigger>
+          <Accordion.Indicator />
+        </Accordion.Trigger>
+      </Accordion.Heading>
+      <Accordion.Panel>
+        <Accordion.Body/>
+      </Accordion.Panel>
+    </Accordion.Item>
+  </Accordion>
+)
+```
+
+### Surface
+
+<ComponentPreview
+  name="accordion-surface"
+ minHeight="400px"
+/>
+
+### Multiple Expanded
+
+<ComponentPreview
+  name="accordion-multiple"
+   minHeight="524px"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="accordion-controlled"
+  minHeight="400px"
+/>
+
+### Custom Indicator
+
+<ComponentPreview
+  name="accordion-custom-indicator"
+   minHeight="320px"
+/>
+
+### Disabled State
+
+<ComponentPreview
+  name="accordion-disabled"
+   minHeight="524px"
+/>
+
+### FAQ Layout
+
+<ComponentPreview
+  name="accordion-faq"
+  minHeight="720px"
+/>
+
+### Custom Styles
+
+<ComponentPreview
+  name="accordion-custom-styles"
+  minHeight="420px"
+/>
+
+### Without Separator
+
+<ComponentPreview
+  name="accordion-without-separator"
+  minHeight="400px"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="accordion-custom-render-function"
+  minHeight="400px"
+/>
+
+<RelatedComponents component="accordion" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+<CollapsibleCode lang="tsx" code={`"use client";
+
+import { Accordion, cn } from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+const items = [
+  {
+    content:
+      "Stay informed about your account activity with real-time notifications. You'll receive instant alerts for important events like transactions, new messages, security updates, and system announcements. ",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    title: "Set Up Notifications",
+    subtitle: "Receive account activity updates",
+  },
+  {
+    content:
+      "Enhance your browsing experience by installing our official browser extension. The extension provides seamless integration with your account, allowing you to receive notifications directly in your browser, quickly access your dashboard, and interact with web3 applications securely. Compatible with Chrome, Firefox, Edge, and Brave browsers.",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    title: "Set up Browser Extension",
+    subtitle: "Connect you browser to your account",
+  },
+  {
+    content:
+      "Begin your journey into the world of digital collectibles by creating your first NFT. Our intuitive minting process guides you through uploading your artwork, setting metadata, choosing royalty percentages, and deploying to the blockchain. Whether you're an artist, creator, or collector, you'll find all the tools you need to bring your digital assets to life. Your collectibles are stored on IPFS for permanent decentralized storage.",
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    title: "Mint Collectible",
+    subtitle: "Create your first collectible",
+  },
+];
+
+export function CustomStyles() {
+  return (
+    <Accordion className="bg-surface-secondary w-full max-w-md rounded-2xl" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item
+          key={index}
+          className={cn(
+            "group/item",
+            "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top
+            "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom
+          )}
+        >
+          <Accordion.Heading>
+            <Accordion.Trigger className="hover:bg-surface-tertiary group flex items-center gap-2">
+              {item.iconUrl ? (
+                <img
+                  alt={item.title}
+                  className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg"
+                  src={item.iconUrl}
+                />
+              ) : null}
+              <div className="flex flex-col gap-0">
+                <span className="font-medium leading-5">{item.title}</span>
+                <span className="text-muted/80 font-normal leading-6">{item.subtitle}</span>
+              </div>
+              <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
+                <Icon icon="gravity-ui:chevron-down" />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}`} />
+
+### Customizing the component classes
+
+To customize the Accordion component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .accordion {
+    @apply rounded-xl bg-gray-50;
+  }
+
+  .accordion__trigger {
+    @apply font-semibold text-lg;
+  }
+
+  .accordion--outline {
+    @apply shadow-lg border-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Accordion component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)):
+
+#### Base Classes
+- `.accordion` - Base accordion container
+- `.accordion__body` - Content body container
+- `.accordion__heading` - Heading wrapper
+- `.accordion__indicator` - Expand/collapse indicator icon
+- `.accordion__item` - Individual accordion item
+- `.accordion__panel` - Collapsible panel container
+- `.accordion__trigger` - Clickable trigger button
+
+#### Variant Classes
+- `.accordion--outline` - Outline variant with border and background
+
+#### State Classes
+- `.accordion__trigger[aria-expanded="true"]` - Expanded state
+- `.accordion__panel[aria-hidden="false"]` - Panel visible state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger
+- **Expanded**: `[aria-expanded="true"]` on trigger
+
+## API Reference
+
+### Accordion Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `allowsMultipleExpanded` | `boolean` | `false` | Whether multiple items can be expanded at once |
+| `defaultExpandedKeys` | `Iterable<Key>` | - | The initial expanded keys |
+| `expandedKeys` | `Iterable<Key>` | - | The controlled expanded keys |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | Handler called when expanded keys change |
+| `isDisabled` | `boolean` | `false` | Whether the entire accordion is disabled |
+| `variant` | `"default" \| "surface"` | `"default"` | The visual variant of the accordion |
+| `hideSeparator` | `boolean` | `false` | Hide separator lines between accordion items |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The accordion items |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+
+### Accordion.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `Key` | - | Unique identifier for the item |
+| `isDisabled` | `boolean` | `false` | Whether this item is disabled |
+| `defaultExpanded` | `boolean` | `false` | Whether item is initially expanded |
+| `isExpanded` | `boolean` | - | Controlled expanded state |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | - | Handler for expanded state changes |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The item content |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Accordion.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function |
+| `onPress` | `() => void` | - | Additional press handler |
+| `isDisabled` | `boolean` | - | Whether trigger is disabled |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Accordion.Panel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Panel content |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Accordion.Indicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom indicator icon |
+
+### Accordion.Body Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Body content |
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/breadcrumbs.mdx b/apps/docs/content/docs/en/react/components/(navigation)/breadcrumbs.mdx
new file mode 100644
index 0000000..4d2e669
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/breadcrumbs.mdx
@@ -0,0 +1,160 @@
+---
+title: Breadcrumbs
+description: Navigation breadcrumbs showing the current page's location within a hierarchy
+links:
+  rac: Breadcrumbs
+  source: breadcrumbs/breadcrumbs.tsx
+  styles: breadcrumbs.css
+  storybook: Components/Navigation/Breadcrumbs
+---
+
+## Import
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="breadcrumbs-basic"
+/>
+
+### Anatomy
+
+Import the Breadcrumbs component and access all parts using dot notation.
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+
+export default () => (
+  <Breadcrumbs>
+    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+    <Breadcrumbs.Item>Current Page</Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+```
+
+### Navigation Levels
+
+<ComponentPreview
+  name="breadcrumbs-level-2"
+/>
+
+<ComponentPreview
+  name="breadcrumbs-level-3"
+/>
+
+### Custom Separator
+
+<ComponentPreview
+  name="breadcrumbs-custom-separator"
+/>
+
+### Disabled State
+
+<ComponentPreview
+  name="breadcrumbs-disabled"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="breadcrumbs-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Breadcrumbs } from '@heroui/react';
+
+function CustomBreadcrumbs() {
+  return (
+    <Breadcrumbs className="gap-2">
+      <Breadcrumbs.Item href="#" className="text-blue-600">
+        Home
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Breadcrumbs component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .breadcrumbs {
+    @apply gap-4 text-lg;
+  }
+
+  .breadcrumbs__link {
+    @apply font-semibold;
+  }
+
+  .breadcrumbs__separator {
+    @apply text-blue-500;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Breadcrumbs component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)):
+
+#### Base Classes
+- `.breadcrumbs` - Base breadcrumbs container
+- `.breadcrumbs__item` - Individual breadcrumb item wrapper
+- `.breadcrumbs__link` - Breadcrumb link element
+- `.breadcrumbs__separator` - Separator icon between items
+
+#### State Classes
+- `.breadcrumbs__link[data-current="true"]` - Current page indicator (not a link)
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Current**: `[data-current="true"]` on link (indicates current page)
+- **Hover**: Link elements support standard hover states
+- **Disabled**: `isDisabled` prop disables all links
+
+## API Reference
+
+### Breadcrumbs Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `separator` | `ReactNode` | chevron-right icon | Custom separator between breadcrumb items |
+| `isDisabled` | `boolean` | `false` | Whether all breadcrumb links are disabled |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The breadcrumb items |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function|
+
+### Breadcrumbs.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `string` | - | The URL to link to (omit for current page) |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | Item content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | Overrides the default DOM element with a custom render function|
+
+## Accessibility
+
+Breadcrumbs uses React Aria Components' Breadcrumbs primitive, which provides:
+
+- Proper ARIA attributes for navigation landmarks
+- Current page indication via `aria-current="page"`
+- Keyboard navigation support
+- Screen reader announcements for navigation context
+
+The last breadcrumb item (without `href`) automatically becomes the current page indicator.
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/disclosure-group.mdx b/apps/docs/content/docs/en/react/components/(navigation)/disclosure-group.mdx
new file mode 100644
index 0000000..2a5715a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/disclosure-group.mdx
@@ -0,0 +1,142 @@
+---
+title: DisclosureGroup
+description: Container that manages multiple Disclosure items with coordinated expanded states
+links:
+  rac: DisclosureGroup
+  source: disclosure-group/disclosure-group.tsx
+  styles: disclosure-group.css
+  storybook: Components/Navigation/DisclosureGroup
+---
+
+## Import
+
+```tsx
+import { DisclosureGroup } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="disclosure-group-basic"
+  minHeight="580px"
+/>
+
+
+### Anatomy
+
+Import all parts and piece them together.
+
+```tsx
+import {DisclosureGroup, Disclosure} from '@heroui/react';
+
+export default () => (
+  <DisclosureGroup>
+    <Disclosure id="item1">
+      <Disclosure.Heading>
+        <Disclosure.Trigger>
+          <Disclosure.Indicator />
+        </Disclosure.Trigger>
+      </Disclosure.Heading>
+      <Disclosure.Content />
+    </Disclosure>
+  </DisclosureGroup>
+)
+```
+
+### Controlled
+
+You can control which disclosures are expanded with external navigation controls using the `expandedKeys` and `onExpandedChange` props.
+
+<ComponentPreview
+  name="disclosure-group-controlled"
+  minHeight="580px"
+/>
+
+
+
+<RelatedShowcases component="DisclosureGroup" />
+
+<RelatedComponents component="disclosuregroup" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {
+  DisclosureGroup,
+  Disclosure,
+  DisclosureTrigger,
+  DisclosurePanel
+} from '@heroui/react';
+
+function CustomDisclosureGroup() {
+  return (
+    <DisclosureGroup className="border rounded-lg p-4 space-y-2">
+      <Disclosure id="first" className="border-b pb-2">
+        <DisclosureTrigger>Item 1</DisclosureTrigger>
+        <DisclosurePanel>Content 1</DisclosurePanel>
+      </Disclosure>
+      <Disclosure id="second">
+        <DisclosureTrigger>Item 2</DisclosureTrigger>
+        <DisclosurePanel>Content 2</DisclosurePanel>
+      </Disclosure>
+    </DisclosureGroup>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the DisclosureGroup component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .disclosure-group {
+    @apply w-full;
+
+    /* Performance optimization */
+    contain: layout style;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The DisclosureGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure-group.css)):
+
+#### Base Classes
+- `.disclosure-group` - Base container styles with layout containment
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` on entire group
+- **Expanded Management**: Automatically manages `[data-expanded]` states on child Disclosure items
+
+## API Reference
+
+### DisclosureGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `expandedKeys` | `Set<Key>` | - | The currently expanded items (controlled) |
+| `defaultExpandedKeys` | `Iterable<Key>` | - | The initially expanded items (uncontrolled) |
+| `onExpandedChange` | `(keys: Set<Key>) => void` | - | Handler called when expanded items change |
+| `allowsMultipleExpanded` | `boolean` | `false` | Whether multiple items can be expanded simultaneously |
+| `isDisabled` | `boolean` | `false` | Whether all disclosures in the group are disabled |
+| `children` | `ReactNode \| RenderFunction` | - | Disclosure items to render |
+| `className` | `string` | - | Additional CSS classes |
+
+### RenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `expandedKeys` | `Set<Key>` | Currently expanded item keys |
+| `isDisabled` | `boolean` | Whether the group is disabled |
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/disclosure.mdx b/apps/docs/content/docs/en/react/components/(navigation)/disclosure.mdx
new file mode 100644
index 0000000..32dbbff
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/disclosure.mdx
@@ -0,0 +1,164 @@
+---
+title: Disclosure
+description: A disclosure is a collapsible section with a header containing a heading and a trigger button, and a panel that wraps the content.
+links:
+  rac: Disclosure
+  source: disclosure/disclosure.tsx
+  styles: disclosure.css
+  storybook: Components/Navigation/Disclosure
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Disclosure } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="disclosure-basic"
+  minHeight="440px"
+/>
+
+### Anatomy
+
+Import the Disclosure component and access all parts using dot notation.
+
+```tsx
+import { Disclosure } from '@heroui/react';
+
+export default () => (
+  <Disclosure>
+    <Disclosure.Heading>
+      <Disclosure.Trigger>
+        <Disclosure.Indicator />
+      </Disclosure.Trigger>
+    </Disclosure.Heading>
+    <Disclosure.Content/>
+  </Disclosure>
+)
+```
+
+<RelatedShowcases component="Disclosure" />
+
+<RelatedComponents component="disclosure" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="disclosure-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Disclosure } from '@heroui/react';
+
+function CustomDisclosure() {
+  return (
+    <Disclosure className="border rounded-lg p-4">
+      <Disclosure.Heading>
+        <Disclosure.Trigger className="text-lg font-semibold">
+          Click to expand
+          <Disclosure.Indicator />
+        </Disclosure.Trigger>
+      </Disclosure.Heading>
+      <Disclosure.Content>
+        <Disclosure.Body className="mt-4 text-gray-600">
+          Hidden content
+        </Disclosure.Body>
+      </Disclosure.Content>
+    </Disclosure>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Disclosure component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .disclosure {
+    @apply relative;
+  }
+
+  .disclosure__trigger {
+    @apply cursor-pointer;
+  }
+
+  .disclosure__indicator {
+    @apply transition-transform duration-300;
+  }
+
+  .disclosure__content {
+    @apply overflow-hidden transition-all;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Disclosure component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)):
+
+#### Base Classes
+- `.disclosure` - Base container styles
+- `.disclosure__heading` - Heading wrapper
+- `.disclosure__trigger` - Trigger button styles
+- `.disclosure__indicator` - Chevron indicator styles
+- `.disclosure__content` - Content container with animations
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Expanded**: `[data-expanded="true"]` on indicator for rotation
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
+- **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger
+- **Hidden**: `[aria-hidden="false"]` on content for visibility
+
+
+## API Reference
+
+### Disclosure Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isExpanded` | `boolean` | `false` | Controls the expanded state |
+| `onExpandedChange` | `(isExpanded: boolean) => void` | - | Callback when expanded state changes |
+| `isDisabled` | `boolean` | `false` | Whether the disclosure is disabled |
+| `children` | `ReactNode \| RenderFunction` | - | Content to render |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### DisclosureTrigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode \| RenderFunction` | - | Trigger content |
+| `className` | `string` | - | Additional CSS classes |
+
+### DisclosureContent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content to show/hide |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+
+### RenderProps
+
+When using the render prop pattern, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isExpanded` | `boolean` | Current expanded state |
+| `isDisabled` | `boolean` | Whether disclosure is disabled |
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/link.mdx b/apps/docs/content/docs/en/react/components/(navigation)/link.mdx
new file mode 100644
index 0000000..e544391
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/link.mdx
@@ -0,0 +1,224 @@
+---
+title: Link
+description: A styled anchor component for navigation with built-in icon support
+links:
+  rac: Link
+  source: link/link.tsx
+  styles: link.css
+  storybook: Components/Navigation/Link
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Link } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="link-basic"
+/>
+
+### Anatomy
+
+Import the Link component and access all parts using dot notation.
+
+```tsx
+import { Link } from '@heroui/react';
+
+export default () => (
+  <Link href="#">
+    Call to action
+    <Link.Icon />
+  </Link>
+);
+```
+
+### Custom Icon
+
+<ComponentPreview
+  name="link-custom-icon"
+/>
+
+### Icon Placement
+
+<ComponentPreview
+  name="link-icon-placement"
+/>
+
+### Text Decoration with Tailwind CSS
+
+Link is underlined on hover by default. Use Tailwind CSS text-decoration utilities to make the underline always visible, remove it entirely, or customize its color, style, thickness, and offset.
+
+<ComponentPreview
+  name="link-underline-and-offset"
+/>
+
+**Text Decoration Line:**
+- `underline` - Always visible underline
+- `no-underline` - Remove underline
+- default `Link` styles - Underline appears on hover
+
+**Text Decoration Color:**
+- `decoration-primary`, `decoration-secondary`, etc. - Set underline color using theme colors
+- `decoration-muted/50` - Use opacity modifiers for semi-transparent underlines
+
+**Text Decoration Style:**
+- `decoration-solid` - Solid line (default)
+- `decoration-double` - Double line
+- `decoration-dotted` - Dotted line
+- `decoration-dashed` - Dashed line
+- `decoration-wavy` - Wavy line
+
+**Text Decoration Thickness:**
+- `decoration-1`, `decoration-2`, `decoration-4`, etc. - Control underline thickness
+
+**Underline Offset:**
+- `underline-offset-1`, `underline-offset-2`, `underline-offset-4`, etc. - Adjust spacing between text and underline
+
+For more details, see the Tailwind CSS documentation:
+- [text-decoration-line](https://tailwindcss.com/docs/text-decoration-line)
+- [text-decoration-color](https://tailwindcss.com/docs/text-decoration-color)
+- [text-decoration-style](https://tailwindcss.com/docs/text-decoration-style)
+- [text-decoration-thickness](https://tailwindcss.com/docs/text-decoration-thickness)
+- [text-underline-offset](https://tailwindcss.com/docs/text-underline-offset)
+
+
+Available BEM classes:
+- Base: `link`
+- Icon: `link__icon`
+
+<RelatedComponents component="link" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="link-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Link } from '@heroui/react';
+
+function CustomLink() {
+  return (
+    <Link
+      href="#"
+      className="text-lg font-bold text-accent hover:text-accent/80"
+    >
+      Custom styled link
+    </Link>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Link component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .link {
+    @apply font-semibold;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Link component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/link.css)):
+
+#### Base Classes
+- `.link` - Base link styles
+- `.link__icon` - Link icon styles
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Pressed**: `:active` or `[data-pressed="true"]`
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+
+## API Reference
+
+### Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `string` | - | Destination URL for the anchor |
+| `target` | `string` | `"_self"` | Controls where to open the linked document |
+| `rel` | `string` | - | Relationship between the current and linked documents |
+| `download` | `boolean \| string` | - | Prompts file download instead of navigation |
+| `isDisabled` | `boolean` | `false` | Disables pointer and keyboard interaction |
+| `className` | `string` | - | Custom classes merged with the default styles |
+| `children` | `React.ReactNode` | - | Content rendered inside the link |
+| `onPress` | `(e: PressEvent) => void` | - | Fired when the link is activated |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, LinkRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Link.Icon Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom icon element; defaults to the built-in arrow icon when omitted |
+| `className` | `string` | - | Additional CSS classes |
+
+
+
+### Using with Routing Libraries
+
+Use variant functions to style framework-specific links like Next.js:
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+export default function Demo() {
+  const slots = linkVariants();
+
+  return (
+    <NextLink className={slots.base()} href="/about">
+      About Page
+      <Link.Icon className={slots.icon()} />
+    </NextLink>
+  );
+}
+```
+
+### Direct Class Application
+
+Since HeroUI uses [BEM](https://getbem.com/) classes, you can apply Link styles directly to any link element:
+
+```tsx
+import NextLink from 'next/link';
+
+// Apply classes directly with Tailwind utilities
+export default function Demo() {
+  return (
+    <NextLink href="/about" className="link underline-offset-2">
+      About Page
+    </NextLink>
+  );
+}
+
+// Or with a native anchor
+export default function NativeLink() {
+  return (
+    <a href="/about" className="link underline decoration-primary underline-offset-4">
+      About Page
+      <Link.Icon className="link__icon" />
+    </a>
+  );
+}
+```
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/pagination.mdx b/apps/docs/content/docs/en/react/components/(navigation)/pagination.mdx
new file mode 100644
index 0000000..01131a0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/pagination.mdx
@@ -0,0 +1,253 @@
+---
+title: Pagination
+description: Page navigation with composable page links, previous/next buttons, and ellipsis indicators
+links:
+  source: pagination/pagination.tsx
+  styles: pagination.css
+  storybook: Components/Navigation/Pagination
+---
+
+## Import
+
+```tsx
+import { Pagination } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="pagination-basic"
+/>
+
+### Anatomy
+
+Import the Pagination component and access all parts using dot notation.
+
+```tsx
+import { Pagination } from '@heroui/react';
+
+export default () => (
+  <Pagination>
+    <Pagination.Summary>Showing 1-10 of 100 results</Pagination.Summary>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon />
+          <span>Previous</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Ellipsis />
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>10</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+```
+
+### Sizes
+
+<ComponentPreview
+  name="pagination-sizes"
+/>
+
+### With Ellipsis
+
+<ComponentPreview
+  name="pagination-with-ellipsis"
+/>
+
+### Simple (Previous / Next)
+
+<ComponentPreview
+  name="pagination-simple-prev-next"
+/>
+
+### With Summary
+
+<ComponentPreview
+  name="pagination-with-summary"
+/>
+
+### Custom Icons
+
+You can replace the default chevron icons by passing custom children to `PreviousIcon` and `NextIcon`.
+
+<ComponentPreview
+  name="pagination-custom-icons"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="pagination-controlled"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="pagination-disabled"
+/>
+
+<RelatedComponents component="pagination" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+You can customize individual Pagination parts:
+
+```tsx
+import { Pagination } from '@heroui/react';
+
+function CustomPagination() {
+  return (
+    <Pagination className="gap-8">
+      <Pagination.Content className="gap-2">
+        <Pagination.Item>
+          <Pagination.Link className="rounded-md" isActive>1</Pagination.Link>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Pagination component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .pagination {
+    @apply gap-8;
+  }
+
+  .pagination__link {
+    @apply rounded-md;
+  }
+
+  .pagination__summary {
+    @apply text-xs font-semibold;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Pagination component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)):
+
+#### Base & Layout Classes
+- `.pagination` - Root navigation container with flex layout
+- `.pagination__summary` - Left-side info text container
+- `.pagination__content` - Container for pagination items
+- `.pagination__item` - Individual item wrapper
+- `.pagination__link` - Page number button (ghost button style)
+- `.pagination__link--nav` - Navigation button modifier (Previous/Next)
+- `.pagination__ellipsis` - Ellipsis indicator
+
+#### Size Classes
+- `.pagination--sm` - Small size variant
+- `.pagination--md` - Medium size variant (default)
+- `.pagination--lg` - Large size variant
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Active page**: `[data-active="true"]` or `[aria-current="page"]`
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `:disabled` or `[aria-disabled="true"]`
+- **Pressed**: `:active` or `[data-pressed="true"]`
+
+## API Reference
+
+### Pagination Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the pagination items |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Pagination parts (Summary, Content) |
+
+### Pagination.Summary Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Summary content (e.g., "Showing 1-10 of 120") |
+
+### Pagination.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Pagination items |
+
+### Pagination.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Item content (Link, Previous, Next, or Ellipsis) |
+
+### Pagination.Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isActive` | `boolean` | `false` | Whether this is the current page |
+| `isDisabled` | `boolean` | `false` | Whether the link is disabled |
+| `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Page number content |
+
+### Pagination.Previous / Pagination.Next Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
+| `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Button content (compose with PreviousIcon/NextIcon) |
+
+### Pagination.PreviousIcon / Pagination.NextIcon Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | Default chevron SVG | Custom icon to replace the default chevron |
+
+### Pagination.Ellipsis Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+## Accessibility
+
+The Pagination component is built on [React Aria's Button](https://react-spectrum.adobe.com/react-aria/Button.html) primitive for all interactive elements, providing:
+
+- Semantic `<nav>` element with `aria-label="pagination"` and `role="navigation"`
+- Active page indicated via `aria-current="page"` on the current link
+- Keyboard navigation via Tab key through all interactive elements
+- Press events handled across mouse, touch, and keyboard interactions via React Aria
+- Focus ring on keyboard navigation via `:focus-visible`
+- Ellipsis marked with `aria-hidden="true"` to avoid screen reader confusion
+- Disabled states properly communicated to assistive technology via `isDisabled`
+
+> **Note:** Pagination buttons use `onPress` instead of `onClick`. The `onPress` handler from React Aria normalizes press behavior across pointer types and provides accessibility improvements out of the box.
diff --git a/apps/docs/content/docs/en/react/components/(navigation)/tabs.mdx b/apps/docs/content/docs/en/react/components/(navigation)/tabs.mdx
new file mode 100644
index 0000000..6053a53
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(navigation)/tabs.mdx
@@ -0,0 +1,230 @@
+---
+title: Tabs
+description: Tabs organize content into multiple sections and allow users to navigate between them.
+icon: new
+links:
+  rac: Tabs
+  source: tabs/tabs.tsx
+  styles: tabs.css
+  storybook: Components/Navigation/Tabs
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Tabs } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-basic"
+/>
+
+### Anatomy
+
+Import the Tabs component and access all parts using dot notation.
+
+```tsx
+import { Tabs } from '@heroui/react';
+
+export default () => (
+  <Tabs>
+    <Tabs.ListContainer>
+      <Tabs.List aria-label="Options">
+        <Tabs.Tab>
+          <Tabs.Separator /> {/* Optional */}
+          <Tabs.Indicator />
+        </Tabs.Tab>
+      </Tabs.List>
+    </Tabs.ListContainer>
+    <Tabs.Panel/>
+  </Tabs>
+)
+```
+
+### Vertical
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-vertical"
+/>
+
+### Overflow
+
+When the tab list exceeds the available space, `Tabs.ListContainer` automatically renders scroll chevrons and fading edges so users can navigate the hidden tabs. This works the same way for both horizontal and vertical orientations.
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-overflow"
+/>
+
+### Disabled Tab
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-disabled"
+/>
+
+### With Separator
+
+Add `<Tabs.Separator />` inside each `<Tabs.Tab>` (except the first) to display separator lines between tabs.
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-with-separator"
+/>
+
+### Custom Styles
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-custom-styles"
+/>
+
+### Secondary Variant
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-secondary"
+/>
+
+### Secondary Variant Vertical
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-secondary-vertical"
+/>
+
+<RelatedShowcases component="Tabs" />
+
+<RelatedComponents component="tabs" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="tabs-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+<CollapsibleCode lang="tsx" code={`
+import { Tabs } from '@heroui/react';
+
+function CustomTabs() {
+  return (
+    <Tabs className="w-full max-w-lg text-center">
+      <Tabs.ListContainer>
+        <Tabs.List
+          aria-label="Options"
+          className="*:data-[selected=true]:text-accent-foreground w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal"
+        >
+          <Tabs.Tab id="daily">Daily<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="weekly">Weekly<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="bi-weekly">Bi-Weekly<Tabs.Indicator /></Tabs.Tab>
+          <Tabs.Tab id="monthly">Monthly<Tabs.Indicator /></Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="daily">
+        <h3 className="mb-2 font-semibold">Daily</h3>
+        <p className="text-sm text-gray-600">Manage your daily tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="weekly">
+        <h3 className="mb-2 font-semibold">Weekly</h3>
+        <p className="text-sm text-gray-600">Manage your weekly tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="bi-weekly">
+        <h3 className="mb-2 font-semibold">Bi-Weekly</h3>
+        <p className="text-sm text-gray-600">Manage your bi-weekly tasks and goals.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="monthly">
+        <h3 className="mb-2 font-semibold">Monthly</h3>
+        <p className="text-sm text-gray-600">Manage your monthly tasks and goals.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+`} />
+
+### CSS Classes
+
+The Tabs component uses these CSS classes:
+
+#### Base Classes
+- `.tabs` - Base tabs container
+- `.tabs__list-container` - Tab list container wrapper
+- `.tabs__list-container__scroller` - Scrollable wrapper around the tab list (handles overflow and fading edges)
+- `.tabs__list-container__scroll-prev` - Scroll chevron button for the previous (left / up) direction
+- `.tabs__list-container__scroll-next` - Scroll chevron button for the next (right / down) direction
+- `.tabs__list` - Tab list container
+- `.tabs__tab` - Individual tab button
+- `.tabs__separator` - Separator between tabs
+- `.tabs__panel` - Tab panel content
+- `.tabs__indicator` - Tab indicator
+
+#### Orientation Attributes
+- `.tabs[data-orientation="horizontal"]` - Horizontal tab layout (default)
+- `.tabs[data-orientation="vertical"]` - Vertical tab layout
+
+#### Variant Classes
+- `.tabs--secondary` - Secondary variant with underline indicator
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes:
+
+- **Selected**: `[aria-selected="true"]`
+- **Hover**: `:hover` or `[data-hovered="true"]`
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+- **Disabled**: `[aria-disabled="true"]`
+
+
+
+## API Reference
+
+### Tabs Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual style variant. Primary uses a filled indicator, secondary uses an underline indicator |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Tab layout orientation |
+| `selectedKey` | `string` | - | Controlled selected tab key |
+| `defaultSelectedKey` | `string` | - | Default selected tab key |
+| `onSelectionChange` | `(key: Key) => void` | - | Selection change handler |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Tabs.List Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | - | Accessibility label for tab list |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Tabs.Tab Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Unique tab identifier |
+| `isDisabled` | `boolean` | `false` | Whether tab is disabled |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Tabs.Separator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+
+### Tabs.Panel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | - | Panel identifier matching tab id |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | Overrides the default DOM element with a custom render function.|
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/alert-dialog.mdx b/apps/docs/content/docs/en/react/components/(overlays)/alert-dialog.mdx
new file mode 100644
index 0000000..f78ebd8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/alert-dialog.mdx
@@ -0,0 +1,325 @@
+---
+title: AlertDialog
+description: Modal dialog for critical confirmations requiring user attention and explicit action
+links:
+  rac: AlertDialog
+  source: alert-dialog/alert-dialog.tsx
+  styles: alert-dialog.css
+  storybook: Components/Overlays/AlertDialog
+---
+
+## Import
+
+```tsx
+import { AlertDialog } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview name="alert-dialog-default" />
+
+### Anatomy
+
+Import the AlertDialog component and access all parts using dot notation.
+
+```tsx
+import {AlertDialog, Button} from "@heroui/react";
+
+export default () => (
+  <AlertDialog>
+    <Button>Open Alert Dialog</Button>
+    <AlertDialog.Backdrop>
+      <AlertDialog.Container>
+        <AlertDialog.Dialog>
+          <AlertDialog.CloseTrigger /> {/* Optional: Close button */}
+          <AlertDialog.Header>
+            <AlertDialog.Icon /> {/* Optional: Status icon */}
+            <AlertDialog.Heading />
+          </AlertDialog.Header>
+          <AlertDialog.Body />
+          <AlertDialog.Footer />
+        </AlertDialog.Dialog>
+      </AlertDialog.Container>
+    </AlertDialog.Backdrop>
+  </AlertDialog>
+);
+```
+
+### Statuses
+
+<ComponentPreview name="alert-dialog-statuses" />
+
+### Placements
+
+<ComponentPreview name="alert-dialog-placements" />
+
+### Backdrop Variants
+
+<ComponentPreview name="alert-dialog-backdrop-variants" />
+
+### Sizes
+
+<ComponentPreview name="alert-dialog-sizes" />
+
+### Custom Icon
+
+<ComponentPreview name="alert-dialog-custom-icon" />
+
+### Custom Backdrop
+
+<ComponentPreview name="alert-dialog-custom-backdrop" />
+
+### Dismiss Behavior
+
+<ComponentPreview name="alert-dialog-dismiss-behavior" />
+
+### Close Methods
+
+<ComponentPreview name="alert-dialog-close-methods" />
+
+### Controlled State
+
+<ComponentPreview name="alert-dialog-controlled" />
+
+### Custom Trigger
+
+<ComponentPreview name="alert-dialog-custom-trigger" />
+
+### Custom Animations
+
+<ComponentPreview name="alert-dialog-custom-animations" />
+
+### Custom Portal
+
+<ComponentPreview name="alert-dialog-custom-portal" />
+
+<RelatedComponents component="alert-dialog" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {AlertDialog, Button} from "@heroui/react";
+
+function CustomAlertDialog() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">Delete</Button>
+      <AlertDialog.Backdrop className="bg-red-950/90">
+        <AlertDialog.Container className="items-start pt-20">
+          <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger" />
+              <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>This alert dialog has custom styling applied via Tailwind classes</p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close" variant="danger">
+                Delete
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the AlertDialog component classes, you can use the `@layer components` directive.
+
+<br />
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .alert-dialog__backdrop {
+    @apply bg-gradient-to-br from-black/60 to-black/80;
+  }
+
+  .alert-dialog__dialog {
+    @apply rounded-2xl border border-red-500/20 shadow-2xl;
+  }
+
+  .alert-dialog__header {
+    @apply gap-4;
+  }
+
+  .alert-dialog__icon {
+    @apply size-16;
+  }
+
+  .alert-dialog__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The AlertDialog component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)):
+
+#### Base Classes
+
+- `.alert-dialog__trigger` - Trigger element that opens the alert dialog
+- `.alert-dialog__backdrop` - Overlay backdrop behind the dialog
+- `.alert-dialog__container` - Positioning wrapper with placement support
+- `.alert-dialog__dialog` - Dialog content container
+- `.alert-dialog__header` - Header section for icon and title
+- `.alert-dialog__heading` - Heading text styles
+- `.alert-dialog__body` - Main content area
+- `.alert-dialog__footer` - Footer section for actions
+- `.alert-dialog__icon` - Icon container with status colors
+- `.alert-dialog__close-trigger` - Close button element
+
+#### Backdrop Variants
+
+- `.alert-dialog__backdrop--opaque` - Opaque colored backdrop (default)
+- `.alert-dialog__backdrop--blur` - Blurred backdrop with glass effect
+- `.alert-dialog__backdrop--transparent` - Transparent backdrop (no overlay)
+
+#### Status Variants (Icon)
+
+- `.alert-dialog__icon--default` - Default gray status
+- `.alert-dialog__icon--accent` - Accent blue status
+- `.alert-dialog__icon--success` - Success green status
+- `.alert-dialog__icon--warning` - Warning orange status
+- `.alert-dialog__icon--danger` - Danger red status
+
+### Interactive States
+
+The component supports these interactive states:
+
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger, dialog, and close button
+- **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover
+- **Active**: `:active` or `[data-pressed="true"]` - Applied to close button when pressed
+- **Entering**: `[data-entering]` - Applied during dialog opening animation
+- **Exiting**: `[data-exiting]` - Applied during dialog closing animation
+- **Placement**: `[data-placement="*"]` - Applied based on dialog position (auto, top, center, bottom)
+
+## API Reference
+
+### AlertDialog
+
+| Prop       | Type        | Default | Description                    |
+| ---------- | ----------- | ------- | ------------------------------ |
+| `children` | `ReactNode` | -       | Trigger and container elements |
+
+### AlertDialog.Trigger
+
+| Prop        | Type        | Default | Description            |
+| ----------- | ----------- | ------- | ---------------------- |
+| `children`  | `ReactNode` | -       | Custom trigger content |
+| `className` | `string`    | -       | CSS classes            |
+
+### AlertDialog.Backdrop
+
+| Prop                        | Type                                      | Default    | Description               |
+| --------------------------- | ----------------------------------------- | ---------- | ------------------------- |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"`     | `"opaque"` | Backdrop overlay style    |
+| `isDismissable`             | `boolean`                                 | `false`    | Close on backdrop click   |
+| `isKeyboardDismissDisabled` | `boolean`                                 | `true`     | Disable ESC key to close  |
+| `isOpen`                    | `boolean`                                 | -          | Controlled open state     |
+| `onOpenChange`              | `(isOpen: boolean) => void`               | -          | Open state change handler |
+| `className`                 | `string \| (values) => string`            | -          | Backdrop CSS classes      |
+| `UNSTABLE_portalContainer`  | `HTMLElement`                             | -          | Custom portal container   |
+
+### AlertDialog.Container
+
+| Prop        | Type                                      | Default  | Description               |
+| ----------- | ----------------------------------------- | -------- | ------------------------- |
+| `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | Dialog position on screen |
+| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"`   | Alert Dialog size variant |
+| `className` | `string \| (values) => string`            | -        | Container CSS classes     |
+
+### AlertDialog.Dialog
+
+| Prop               | Type                                  | Default         | Description                |
+| ------------------ | ------------------------------------- | --------------- | -------------------------- |
+| `children`         | `ReactNode \| ({close}) => ReactNode` | -               | Content or render function |
+| `className`        | `string`                              | -               | CSS classes                |
+| `role`             | `string`                              | `"alertdialog"` | ARIA role                  |
+| `aria-label`       | `string`                              | -               | Accessibility label        |
+| `aria-labelledby`  | `string`                              | -               | ID of label element        |
+| `aria-describedby` | `string`                              | -               | ID of description element  |
+
+### AlertDialog.Header
+
+| Prop        | Type        | Default | Description                                 |
+| ----------- | ----------- | ------- | ------------------------------------------- |
+| `children`  | `ReactNode` | -       | Header content (typically Icon and Heading) |
+| `className` | `string`    | -       | CSS classes                                 |
+
+### AlertDialog.Heading
+
+| Prop        | Type        | Default | Description  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Heading text |
+| `className` | `string`    | -       | CSS classes  |
+
+### AlertDialog.Body
+
+| Prop        | Type        | Default | Description  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Body content |
+| `className` | `string`    | -       | CSS classes  |
+
+### AlertDialog.Footer
+
+| Prop        | Type        | Default | Description                               |
+| ----------- | ----------- | ------- | ----------------------------------------- |
+| `children`  | `ReactNode` | -       | Footer content (typically action buttons) |
+| `className` | `string`    | -       | CSS classes                               |
+
+### AlertDialog.Icon
+
+| Prop        | Type                                                          | Default    | Description          |
+| ----------- | ------------------------------------------------------------- | ---------- | -------------------- |
+| `children`  | `ReactNode`                                                   | -          | Custom icon element  |
+| `status`    | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"danger"` | Status color variant |
+| `className` | `string`                                                      | -          | CSS classes          |
+
+### AlertDialog.CloseTrigger
+
+| Prop        | Type                           | Default | Description         |
+| ----------- | ------------------------------ | ------- | ------------------- |
+| `children`  | `ReactNode`                    | -       | Custom close button |
+| `className` | `string \| (values) => string` | -       | CSS classes         |
+
+### useOverlayState Hook
+
+```tsx
+import {useOverlayState} from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // Current state
+state.open(); // Open dialog
+state.close(); // Close dialog
+state.toggle(); // Toggle state
+state.setOpen(); // Set state directly
+```
+
+## Accessibility
+
+Implements [WAI-ARIA AlertDialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/):
+
+- **Focus trap**: Focus locked within alert dialog
+- **Keyboard**: `ESC` closes (when enabled), `Tab` cycles elements
+- **Screen readers**: Proper ARIA attributes with `role="alertdialog"`
+- **Scroll lock**: Body scroll disabled when open
+- **Required action**: Defaults to requiring explicit user action (no backdrop/ESC dismiss)
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/drawer.mdx b/apps/docs/content/docs/en/react/components/(overlays)/drawer.mdx
new file mode 100644
index 0000000..a427671
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/drawer.mdx
@@ -0,0 +1,299 @@
+---
+title: Drawer
+description: Slide-out panel for supplementary content and actions
+links:
+  rac: Modal
+  source: drawer/drawer.tsx
+  styles: drawer.css
+  storybook: Components/Overlays/Drawer
+---
+
+## Import
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview name="drawer-basic" />
+
+### Anatomy
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+export default () => (
+  <Drawer>
+    <Button>Open Drawer</Button>
+    <Drawer.Backdrop>
+      <Drawer.Content>
+        <Drawer.Dialog>
+          <Drawer.Handle /> {/* Optional: Drag handle */}
+          <Drawer.CloseTrigger /> {/* Optional: Close button */}
+          <Drawer.Header>
+            <Drawer.Heading />
+          </Drawer.Header>
+          <Drawer.Body />
+          <Drawer.Footer />
+        </Drawer.Dialog>
+      </Drawer.Content>
+    </Drawer.Backdrop>
+  </Drawer>
+);
+```
+
+### Placement
+
+<ComponentPreview name="drawer-placements" />
+
+### Backdrop Variants
+
+<ComponentPreview name="drawer-backdrop-variants" />
+
+### Non-Dismissable
+
+Set `isDismissable={false}` on `Drawer.Backdrop` to prevent closing by clicking outside or dragging. The user must interact with the drawer's action buttons.
+
+<ComponentPreview name="drawer-non-dismissable" />
+
+### Scrollable Content
+
+The `Drawer.Body` automatically handles overflow with native scrolling. Drag-to-dismiss is excluded from the body area to avoid scroll conflicts.
+
+<ComponentPreview name="drawer-scrollable-content" />
+
+### Controlled State
+
+<ComponentPreview name="drawer-controlled" />
+
+### With Form
+
+<ComponentPreview name="drawer-with-form" />
+
+### Navigation Drawer
+
+<ComponentPreview name="drawer-navigation" />
+
+<RelatedComponents component="drawer" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+function CustomDrawer() {
+  return (
+    <Drawer>
+      <Button>Open Drawer</Button>
+      <Drawer.Backdrop className="bg-black/80">
+        <Drawer.Content>
+          <Drawer.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Custom Styled Drawer</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>This drawer has custom styling applied via Tailwind classes.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Drawer component classes, you can use the `@layer components` directive.
+
+<br />
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .drawer__backdrop {
+    @apply bg-gradient-to-br from-black/50 to-black/70;
+  }
+
+  .drawer__dialog {
+    @apply rounded-2xl border border-white/10 shadow-2xl;
+  }
+
+  .drawer__header {
+    @apply text-center;
+  }
+
+  .drawer__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Drawer component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/drawer.css)):
+
+#### Base Classes
+
+- `.drawer__trigger` - Trigger element that opens the drawer
+- `.drawer__backdrop` - Overlay backdrop behind the drawer
+- `.drawer__content` - Positioning wrapper for the drawer panel
+- `.drawer__dialog` - The drawer panel itself
+- `.drawer__header` - Header section for titles
+- `.drawer__heading` - Main title text
+- `.drawer__body` - Main scrollable content area
+- `.drawer__footer` - Footer section for actions
+- `.drawer__handle` - Visual drag handle indicator
+- `.drawer__close-trigger` - Close button element
+
+#### Backdrop Variants
+
+- `.drawer__backdrop--opaque` - Opaque colored backdrop (default)
+- `.drawer__backdrop--blur` - Blurred backdrop with glass effect
+- `.drawer__backdrop--transparent` - Transparent backdrop (no overlay)
+
+#### Placement Variants
+
+- `.drawer__content--bottom` - Slides up from the bottom edge (default)
+- `.drawer__content--top` - Slides down from the top edge
+- `.drawer__content--left` - Slides in from the left edge
+- `.drawer__content--right` - Slides in from the right edge
+
+#### Dialog Variants
+
+- `.drawer__dialog--top` - Slides down from the top edge
+- `.drawer__dialog--bottom` - Slides up from the bottom edge
+- `.drawer__dialog--left` - Slides in from the left edge
+- `.drawer__dialog--right` - Slides in from the right edge
+
+### Interactive States
+
+The component supports these interactive states:
+
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger and close button
+- **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover
+- **Active**: `:active` or `[data-pressed="true"]` - Applied to trigger and close button when pressed
+- **Entering**: `[data-entering]` - Applied during drawer opening animation
+- **Exiting**: `[data-exiting]` - Applied during drawer closing animation
+- **Placement**: `[data-placement="*"]` - Applied based on drawer position (top, bottom, left, right)
+
+## API Reference
+
+### Drawer
+
+| Prop       | Type                   | Default | Description                    |
+| ---------- | ---------------------- | ------- | ------------------------------ |
+| `children` | `ReactNode`            | -       | Trigger and backdrop elements  |
+| `state`    | `UseOverlayStateReturn` | -      | Controlled overlay state       |
+
+### Drawer.Trigger
+
+| Prop        | Type        | Default | Description            |
+| ----------- | ----------- | ------- | ---------------------- |
+| `children`  | `ReactNode` | -       | Custom trigger content |
+| `className` | `string`    | -       | CSS classes            |
+
+### Drawer.Backdrop
+
+| Prop                        | Type                                  | Default    | Description               |
+| --------------------------- | ------------------------------------- | ---------- | ------------------------- |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | Backdrop overlay style    |
+| `isDismissable`             | `boolean`                             | `true`     | Close on backdrop click   |
+| `isKeyboardDismissDisabled` | `boolean`                             | `false`    | Disable ESC key to close  |
+| `isOpen`                    | `boolean`                             | -          | Controlled open state     |
+| `onOpenChange`              | `(isOpen: boolean) => void`           | -          | Open state change handler |
+| `className`                 | `string \| (values) => string`        | -          | Backdrop CSS classes      |
+
+### Drawer.Content
+
+| Prop        | Type                                          | Default    | Description               |
+| ----------- | --------------------------------------------- | ---------- | ------------------------- |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"`      | `"bottom"` | Edge the drawer slides from |
+| `className` | `string \| (values) => string`                | -          | Content CSS classes       |
+
+### Drawer.Dialog
+
+| Prop               | Type                           | Default    | Description                |
+| ------------------ | ------------------------------ | ---------- | -------------------------- |
+| `children`         | `ReactNode`                    | -          | Dialog content             |
+| `className`        | `string`                       | -          | CSS classes                |
+| `role`             | `string`                       | `"dialog"` | ARIA role                  |
+| `aria-label`       | `string`                       | -          | Accessibility label        |
+| `aria-labelledby`  | `string`                       | -          | ID of label element        |
+
+### Drawer.Header
+
+| Prop        | Type        | Default | Description    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Header content |
+| `className` | `string`    | -       | CSS classes    |
+
+### Drawer.Heading
+
+| Prop        | Type        | Default | Description  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Title text   |
+| `className` | `string`    | -       | CSS classes  |
+
+### Drawer.Body
+
+| Prop        | Type        | Default | Description  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Body content |
+| `className` | `string`    | -       | CSS classes  |
+
+### Drawer.Footer
+
+| Prop        | Type        | Default | Description    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Footer content |
+| `className` | `string`    | -       | CSS classes    |
+
+### Drawer.Handle
+
+| Prop        | Type     | Default | Description          |
+| ----------- | -------- | ------- | -------------------- |
+| `className` | `string` | -       | CSS classes          |
+
+### Drawer.CloseTrigger
+
+| Prop        | Type                           | Default | Description         |
+| ----------- | ------------------------------ | ------- | ------------------- |
+| `children`  | `ReactNode`                    | -       | Custom close button |
+| `className` | `string \| (values) => string` | -       | CSS classes         |
+
+### useOverlayState Hook
+
+```tsx
+import { useOverlayState } from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // Current state
+state.open(); // Open drawer
+state.close(); // Close drawer
+state.toggle(); // Toggle state
+state.setOpen(); // Set state directly
+```
+
+## Accessibility
+
+Implements [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/):
+
+- **Focus trap**: Focus locked within drawer when open
+- **Keyboard**: `ESC` closes (when dismissable), `Tab` cycles elements
+- **Screen readers**: Proper ARIA attributes via React Aria
+- **Scroll lock**: Body scroll disabled when open
+- **Drag to dismiss**: Supports pointer-based drag gestures on handle, header, and footer areas
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/modal.mdx b/apps/docs/content/docs/en/react/components/(overlays)/modal.mdx
new file mode 100644
index 0000000..2a2916f
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/modal.mdx
@@ -0,0 +1,295 @@
+---
+title: Modal
+description: Dialog overlay for focused user interactions and important content
+links:
+  rac: Modal
+  source: modal/modal.tsx
+  styles: modal.css
+  storybook: modal
+---
+
+## Import
+
+```tsx
+import { Modal } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview name="modal-default" />
+
+### Anatomy
+
+Import the Modal component and access all parts using dot notation.
+
+```tsx
+import {Modal, Button} from "@heroui/react";
+
+export default () => (
+  <Modal>
+    <Button>Open Modal</Button>
+    <Modal.Backdrop>
+      <Modal.Container>
+        <Modal.Dialog>
+          <Modal.CloseTrigger /> {/* Optional: Close button */}
+          <Modal.Header>
+            <Modal.Icon /> {/* Optional: Icon */}
+            <Modal.Heading />
+          </Modal.Header>
+          <Modal.Body />
+          <Modal.Footer />
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  </Modal>
+);
+```
+
+### Placement
+
+<ComponentPreview name="modal-placements" />
+
+### Backdrop Variants
+
+<ComponentPreview name="modal-backdrop-variants" />
+
+### Sizes
+
+<ComponentPreview name="modal-sizes" />
+
+### Custom Backdrop
+
+<ComponentPreview name="modal-custom-backdrop" />
+
+### Dismiss Behavior
+
+<ComponentPreview name="modal-dismiss-behavior" />
+
+### Close Methods
+
+<ComponentPreview name="modal-close-methods" />
+
+### Scroll Behavior
+
+<ComponentPreview name="modal-scroll-comparison" />
+
+### Controlled State
+
+<ComponentPreview name="modal-controlled" />
+
+### With Form
+
+<ComponentPreview name="modal-with-form" />
+
+### Custom Trigger
+
+<ComponentPreview name="modal-custom-trigger" />
+
+### Custom Animations
+
+<ComponentPreview name="modal-custom-animations" />
+
+### Custom Portal
+
+<ComponentPreview name="modal-custom-portal" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Modal, Button} from "@heroui/react";
+
+function CustomModal() {
+  return (
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop className="bg-black/80">
+        <Modal.Container className="items-start pt-20">
+          <Modal.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Custom Styled Modal</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>This modal has custom styling applied via Tailwind classes</p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close">Close</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Modal component classes, you can use the `@layer components` directive.
+
+<br />
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .modal__backdrop {
+    @apply bg-gradient-to-br from-black/50 to-black/70;
+  }
+
+  .modal__dialog {
+    @apply rounded-2xl border border-white/10 shadow-2xl;
+  }
+
+  .modal__header {
+    @apply text-center;
+  }
+
+  .modal__close-trigger {
+    @apply rounded-full bg-white/10 hover:bg-white/20;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Modal component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/modal.css)):
+
+#### Base Classes
+
+- `.modal__trigger` - Trigger element that opens the modal
+- `.modal__backdrop` - Overlay backdrop behind the modal
+- `.modal__container` - Positioning wrapper with placement support
+- `.modal__dialog` - Modal content container
+- `.modal__header` - Header section for titles and icons
+- `.modal__body` - Main content area
+- `.modal__footer` - Footer section for actions
+- `.modal__close-trigger` - Close button element
+
+#### Backdrop Variants
+
+- `.modal__backdrop--opaque` - Opaque colored backdrop (default)
+- `.modal__backdrop--blur` - Blurred backdrop with glass effect
+- `.modal__backdrop--transparent` - Transparent backdrop (no overlay)
+
+#### Scroll Variants
+
+- `.modal__container--scroll-outside` - Enables scrolling the entire modal
+- `.modal__dialog--scroll-inside` - Constrains modal height for body scrolling
+- `.modal__body--scroll-inside` - Makes only the body scrollable
+- `.modal__body--scroll-outside` - Allows full-page scrolling
+
+### Interactive States
+
+The component supports these interactive states:
+
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger, dialog, and close button
+- **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover
+- **Active**: `:active` or `[data-pressed="true"]` - Applied to close button when pressed
+- **Entering**: `[data-entering]` - Applied during modal opening animation
+- **Exiting**: `[data-exiting]` - Applied during modal closing animation
+- **Placement**: `[data-placement="*"]` - Applied based on modal position (auto, top, center, bottom)
+
+## API Reference
+
+### Modal
+
+| Prop       | Type        | Default | Description                    |
+| ---------- | ----------- | ------- | ------------------------------ |
+| `children` | `ReactNode` | -       | Trigger and container elements |
+
+### Modal.Trigger
+
+| Prop        | Type        | Default | Description            |
+| ----------- | ----------- | ------- | ---------------------- |
+| `children`  | `ReactNode` | -       | Custom trigger content |
+| `className` | `string`    | -       | CSS classes            |
+
+### Modal.Backdrop
+
+| Prop                        | Type                                  | Default    | Description               |
+| --------------------------- | ------------------------------------- | ---------- | ------------------------- |
+| `variant`                   | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | Backdrop overlay style    |
+| `isDismissable`             | `boolean`                             | `true`     | Close on backdrop click   |
+| `isKeyboardDismissDisabled` | `boolean`                             | `false`    | Disable ESC key to close  |
+| `isOpen`                    | `boolean`                             | -          | Controlled open state     |
+| `onOpenChange`              | `(isOpen: boolean) => void`           | -          | Open state change handler |
+| `className`                 | `string \| (values) => string`        | -          | Backdrop CSS classes      |
+| `UNSTABLE_portalContainer`  | `HTMLElement`                         | -          | Custom portal container   |
+
+### Modal.Container
+
+| Prop        | Type                                      | Default    | Description               |
+| ----------- | ----------------------------------------- | ---------- | ------------------------- |
+| `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"`   | Modal position on screen  |
+| `scroll`    | `"inside" \| "outside"`                   | `"inside"` | Scroll behavior           |
+| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "cover" \| "full"` | `"md"` | Modal size variant        |
+| `className` | `string \| (values) => string`            | -          | Container CSS classes     |
+
+### Modal.Dialog
+
+| Prop               | Type                                  | Default    | Description                |
+| ------------------ | ------------------------------------- | ---------- | -------------------------- |
+| `children`         | `ReactNode \| ({close}) => ReactNode` | -          | Content or render function |
+| `className`        | `string \| (values) => string`        | -          | CSS classes                |
+| `role`             | `string`                              | `"dialog"` | ARIA role                  |
+| `aria-label`       | `string`                              | -          | Accessibility label        |
+| `aria-labelledby`  | `string`                              | -          | ID of label element        |
+| `aria-describedby` | `string`                              | -          | ID of description element  |
+
+### Modal.Header
+
+| Prop        | Type        | Default | Description    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Header content |
+| `className` | `string`    | -       | CSS classes    |
+
+### Modal.Body
+
+| Prop        | Type        | Default | Description  |
+| ----------- | ----------- | ------- | ------------ |
+| `children`  | `ReactNode` | -       | Body content |
+| `className` | `string`    | -       | CSS classes  |
+
+### Modal.Footer
+
+| Prop        | Type        | Default | Description    |
+| ----------- | ----------- | ------- | -------------- |
+| `children`  | `ReactNode` | -       | Footer content |
+| `className` | `string`    | -       | CSS classes    |
+
+### Modal.CloseTrigger
+
+| Prop        | Type                           | Default | Description         |
+| ----------- | ------------------------------ | ------- | ------------------- |
+| `children`  | `ReactNode`                    | -       | Custom close button |
+| `className` | `string \| (values) => string` | -       | CSS classes         |
+
+### useOverlayState Hook
+
+```tsx
+import {useOverlayState} from "@heroui/react";
+
+const state = useOverlayState({
+  defaultOpen: false,
+  onOpenChange: (isOpen) => console.log(isOpen),
+});
+
+state.isOpen; // Current state
+state.open(); // Open modal
+state.close(); // Close modal
+state.toggle(); // Toggle state
+state.setOpen(); // Set state directly
+```
+
+## Accessibility
+
+Implements [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/):
+
+- **Focus trap**: Focus locked within modal
+- **Keyboard**: `ESC` closes (when enabled), `Tab` cycles elements
+- **Screen readers**: Proper ARIA attributes
+- **Scroll lock**: Body scroll disabled when open
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/popover.mdx b/apps/docs/content/docs/en/react/components/(overlays)/popover.mdx
new file mode 100644
index 0000000..37ea0c7
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/popover.mdx
@@ -0,0 +1,178 @@
+---
+title: Popover
+description: Displays rich content in a portal triggered by a button or any custom element
+links:
+  rac: Popover
+  source: popover/popover.tsx
+  styles: popover.css
+  storybook: Components/Overlays/Popover
+---
+
+## Import
+
+```tsx
+import { Popover } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="popover-basic"
+/>
+
+### Anatomy
+
+Import the Popover component and access all parts using dot notation.
+
+```tsx
+import { Popover } from '@heroui/react';
+
+export default () => (
+  <Popover>
+    <Popover.Trigger/>
+    <Popover.Content>
+      <Popover.Arrow />
+      <Popover.Dialog>
+        <Popover.Heading/>
+        {/* content goes here */}
+      </Popover.Dialog>
+    </Popover.Content>
+  </Popover>
+)
+```
+
+### With Arrow
+
+<ComponentPreview
+  name="popover-with-arrow"
+/>
+
+### Placement
+
+<ComponentPreview
+  name="popover-placement"
+/>
+
+### Interactive Content
+
+<ComponentPreview
+  name="popover-interactive"
+/>
+
+<RelatedComponents component="popover" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="popover-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Popover, Button } from '@heroui/react';
+
+function CustomPopover() {
+  return (
+    <Popover>
+      <Popover.Trigger>
+        <Button>Open</Button>
+      </Popover.Trigger>
+      <Popover.Content className="bg-accent text-accent-foreground">
+        <Popover.Dialog>
+          <h3>Custom Styled</h3>
+          <p>This popover has custom styling</p>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Popover component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .popover {
+    @apply rounded-xl shadow-2xl;
+  }
+
+  .popover__dialog {
+    @apply p-4;
+  }
+
+  .popover__heading {
+    @apply text-lg font-bold;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Popover component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/popover.css)):
+
+#### Base Classes
+- `.popover` - Base popover container styles
+- `.popover__dialog` - Dialog content wrapper
+- `.popover__heading` - Heading text styles
+- `.popover__trigger` - Trigger element styles
+
+### Interactive States
+
+The component supports animation states:
+
+- **Entering**: `[data-entering]` - Applied during popover appearance
+- **Exiting**: `[data-exiting]` - Applied during popover disappearance
+- **Placement**: `[data-placement="*"]` - Applied based on popover position
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
+
+## API Reference
+
+### Popover Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Trigger and content elements |
+| `isOpen` | `boolean` | - | Controls popover visibility (controlled) |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Called when open state changes |
+
+### Popover.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display in the popover |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"bottom"` | Placement of the popover |
+| `offset` | `number` | `8` | Distance from the trigger element |
+| `shouldFlip` | `boolean` | `true` | Whether popover can change orientation to fit |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Popover.Dialog Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Dialog content |
+| `className` | `string` | - | Additional CSS classes |
+
+### Popover.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Element that triggers the popover |
+| `className` | `string` | - | Additional CSS classes |
+
+### Popover.Arrow Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom arrow element |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | Overrides the default DOM element with a custom render function.|
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/toast.mdx b/apps/docs/content/docs/en/react/components/(overlays)/toast.mdx
new file mode 100644
index 0000000..9882a67
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/toast.mdx
@@ -0,0 +1,332 @@
+---
+title: Toast
+description: Display temporary notifications and messages to users with automatic dismissal and customizable placement
+links:
+  rac: Toast
+  source: toast/toast.tsx
+  styles: toast.css
+  storybook: Components/Feedback/Toast
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Toast, toast } from '@heroui/react';
+```
+
+## Setup
+
+Render the provider in the root of your app.
+
+```tsx
+import { Toast, Button, toast } from '@heroui/react';
+
+function App() {
+  return (
+    <div>
+      <Toast.Provider />
+      <Button onPress={() => toast("Simple message")}>
+        Show toast
+      </Button>
+    </div>
+  );
+}
+```
+
+### Usage
+
+<ComponentPreview
+  name="toast-default"
+/>
+
+### Simple Toasts
+
+<ComponentPreview
+  name="toast-simple"
+/>
+
+### Variants
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+### Custom Indicators
+
+<ComponentPreview
+  name="toast-custom-indicator"
+/>
+
+### Promise & Loading
+
+<ComponentPreview
+  name="toast-promise"
+/>
+
+### Callbacks
+
+<ComponentPreview
+  name="toast-callbacks"
+/>
+
+### Placements
+
+<ComponentPreview
+  name="toast-placements"
+/>
+
+### Custom Toast Rendering
+
+<ComponentPreview
+  name="toast-custom-toast"
+/>
+
+### Custom Queues
+
+<ComponentPreview
+  name="toast-custom-queue"
+/>
+
+### Anatomy
+
+```tsx
+<Toast.Provider>
+  <Toast>
+    <Toast.Indicator />
+    <Toast.Content>
+      <Toast.Title />
+      <Toast.Description />
+    </Toast.Content>
+    <Toast.ActionButton />
+    <Toast.CloseButton />
+  </Toast>
+</Toast.Provider>
+```
+
+<RelatedComponents component="toast" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+<Toast.Provider className="bottom-8 right-8" placement="bottom end" />
+```
+
+### Customizing the component classes
+
+To customize the Toast component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .toast {
+    @apply rounded-xl shadow-lg;
+  }
+
+  .toast__content {
+    @apply gap-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Toast component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toast.css)):
+
+#### Base Classes
+- `.toast` - Base toast container
+- `.toast__region` - Toast region container
+- `.toast__content` - Content wrapper for title and description
+- `.toast__indicator` - Icon/indicator container
+- `.toast__title` - Toast title text
+- `.toast__description` - Toast description text
+- `.toast__action` - Action button container
+- `.toast__close` - Close button container
+
+#### Variant Classes
+- `.toast--default` - Default gray variant
+- `.toast--accent` - Accent blue variant
+- `.toast--success` - Success green variant
+- `.toast--warning` - Warning yellow/orange variant
+- `.toast--danger` - Danger red variant
+
+### Interactive States
+
+The component supports various states:
+
+- **Frontmost**: `[data-frontmost]` - Applied to the topmost visible toast
+- **Index**: `[data-index]` - Applied based on toast position in stack
+- **Placement**: `[data-placement="*"]` - Applied based on toast region placement
+
+## API Reference
+
+### Toast.Provider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `"top start" \| "top" \| "top end" \| "bottom start" \| "bottom" \| "bottom end"` | `"bottom"` | Placement of the toast region |
+| `gap` | `number` | `12` | The gap between toasts in pixels |
+| `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once |
+| `scaleFactor` | `number` | `0.05` | Scale factor for stacked toasts (0-1) |
+| `width` | `number \| string` | `460` | Width of the toast in pixels or CSS value |
+| `queue` | `ToastQueue<T>` | - | Custom toast queue instance |
+| `children` | `ReactNode \| ((props: {toast: QueuedToast<T>}) => ReactNode)` | - | Custom render function or children |
+| `className` | `string` | - | Additional CSS classes |
+
+### Toast Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `toast` | `QueuedToast<T>` | - | Toast data from queue (required) |
+| `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant of the toast |
+| `placement` | `ToastVariants["placement"]` | - | Placement (inherited from Provider) |
+| `scaleFactor` | `number` | - | Scale factor (inherited from Provider) |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Toast content (ToastContent, ToastIndicator, etc.) |
+
+### Toast.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content (typically ToastTitle and ToastDescription) |
+| `className` | `string` | - | Additional CSS classes |
+
+### Toast.Indicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `ToastVariants["variant"]` | - | Variant for default icon |
+| `children` | `ReactNode` | - | Custom indicator icon (defaults to variant icon) |
+| `className` | `string` | - | Additional CSS classes |
+
+### Toast.Title Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Title text |
+| `className` | `string` | - | Additional CSS classes |
+
+### Toast.Description Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Description text |
+| `className` | `string` | - | Additional CSS classes |
+
+### Toast.ActionButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Action button content |
+| `className` | `string` | - | Additional CSS classes |
+| All `Button` props | - | - | Accepts all Button component props |
+
+### Toast.CloseButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| All `CloseButton` props | - | - | Accepts all CloseButton component props |
+
+### ToastQueue
+
+A `ToastQueue` manages the state for a `<Toast.Provider>`. The state is stored outside React so you can trigger toasts from anywhere in your application.
+
+#### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once (visual only) |
+| `wrapUpdate` | `(fn: () => void) => void` | - | Function to wrap state updates (e.g., for view transitions) |
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `add` | `(content: T, options?: ToastOptions)` | `string` | Add a toast to the queue, returns toast key |
+| `close` | `(key: string)` | `void` | Close a toast by its key |
+| `pauseAll` | `()` | `void` | Pause all toast timers |
+| `resumeAll` | `()` | `void` | Resume all toast timers |
+| `clear` | `()` | `void` | Close all toasts |
+| `subscribe` | `(fn: () => void)` | `() => void` | Subscribe to queue changes, returns unsubscribe function |
+
+### toast Function
+
+The default `toast` function provides convenient methods for showing toasts:
+
+```tsx
+import { toast } from '@heroui/react';
+
+// Basic toast (auto-dismisses after 4 seconds by default)
+toast("Event has been created");
+
+// Variant methods (also auto-dismiss after 4 seconds by default)
+toast.success("File saved");
+toast.info("New update available");
+toast.warning("Please check your settings");
+toast.danger("Something went wrong");
+
+// With options
+toast("Event has been created", {
+  description: "Your event has been scheduled for tomorrow",
+  variant: "default",
+  timeout: 5000, // Custom timeout: 5 seconds
+  onClose: () => console.log("Closed"),
+  actionProps: {
+    children: "View",
+    onPress: () => {},
+  },
+  indicator: <CustomIcon />,
+});
+
+// Promise support (automatically shows loading spinner)
+toast.promise(
+  uploadFile(),
+  {
+    loading: "Uploading file...",
+    success: (data) => `File ${data.filename} uploaded`,
+    error: "Failed to upload file",
+  }
+);
+
+// Manual loading state (persistent toast - no auto-dismiss)
+const loadingId = toast("Creating event...", {
+  isLoading: true,
+  timeout: 0, // Persistent toast that doesn't auto-dismiss
+});
+
+// Later, close and show result
+toast.close(loadingId);
+toast.success("Event created");
+
+// Queue methods
+toast.close(key);
+toast.clear();
+toast.pauseAll();
+toast.resumeAll();
+```
+
+#### toast Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `ReactNode` | - | Toast title (first parameter for variant methods) |
+| `description` | `ReactNode` | - | Optional description text |
+| `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant |
+| `indicator` | `ReactNode` | - | Custom indicator icon (null to hide) |
+| `actionProps` | `ButtonProps` | - | Props for action button |
+| `isLoading` | `boolean` | `false` | Show loading spinner instead of indicator |
+| `timeout` | `number` | `4000` | Auto-dismiss timeout in milliseconds. Defaults to 4000ms (4 seconds). Set to `0` for persistent toasts that don't auto-dismiss |
+| `onClose` | `() => void` | - | Callback when toast is closed |
+
+#### toast.promise Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `loading` | `ReactNode` | - | Message shown while promise is pending |
+| `success` | `ReactNode \| ((data: T) => ReactNode)` | - | Message shown on success (can be function) |
+| `error` | `ReactNode \| ((error: Error) => ReactNode)` | - | Message shown on error (can be function) |
diff --git a/apps/docs/content/docs/en/react/components/(overlays)/tooltip.mdx b/apps/docs/content/docs/en/react/components/(overlays)/tooltip.mdx
new file mode 100644
index 0000000..3989ab8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(overlays)/tooltip.mdx
@@ -0,0 +1,186 @@
+---
+title: Tooltip
+description: Displays informative text when users hover over or focus on an element
+icon: updated
+links:
+  rac: Tooltip
+  source: tooltip/tooltip.tsx
+  styles: tooltip.css
+  storybook: Components/Overlays/Tooltip
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Tooltip } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="tooltip-basic"
+/>
+
+### Anatomy
+
+Import the Tooltip component and access all parts using dot notation.
+
+```tsx
+import { Tooltip, Button } from '@heroui/react';
+
+export default () => (
+  <Tooltip>
+    <Tooltip.Trigger>
+      <Button>Hover for tooltip</Button>
+    </Tooltip.Trigger>
+    <Tooltip.Content>
+      <Tooltip.Arrow />
+      Helpful information about this element
+    </Tooltip.Content>
+  </Tooltip>
+)
+```
+
+### With Arrow
+
+<ComponentPreview
+  name="tooltip-with-arrow"
+/>
+
+### Placement
+
+<ComponentPreview
+  name="tooltip-placement"
+/>
+
+### Custom Triggers
+
+<ComponentPreview
+  name="tooltip-custom-trigger"
+/>
+
+<RelatedComponents component="tooltip" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="tooltip-custom-render-function"
+/>
+
+## Styling
+
+### Global Delay Configuration
+
+You can set default show and hide delays for all Tooltip components in your application by defining CSS variables:
+
+```css
+/* In your global CSS file */
+:root {
+  --tooltip-delay: 1500ms;
+  --tooltip-close-delay: 500ms;
+}
+
+/* You can also set different values for light/dark themes */
+.light, [data-theme="light"] {
+  --tooltip-delay: 1200ms;
+}
+
+.dark, [data-theme="dark"] {
+  --tooltip-close-delay: 300ms;
+}
+```
+
+Values accept CSS time units such as `ms` and `s`. These global settings are overridden by the `delay` and `closeDelay` props when specified on individual tooltips.
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Tooltip, Button } from '@heroui/react';
+
+function CustomTooltip() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content className="bg-accent text-accent-foreground">
+        <p>Custom styled tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Tooltip component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .tooltip {
+    @apply rounded-xl shadow-lg;
+  }
+
+  .tooltip__trigger {
+    @apply cursor-help;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Tooltip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tooltip.css)):
+
+#### Base Classes
+- `.tooltip` - Base tooltip styles with animations
+- `.tooltip__trigger` - Trigger element styles
+
+### Interactive States
+
+The component supports animation states:
+
+- **Entering**: `[data-entering]` - Applied during tooltip appearance
+- **Exiting**: `[data-exiting]` - Applied during tooltip disappearance
+- **Placement**: `[data-placement="*"]` - Applied based on tooltip position
+
+## API Reference
+
+### Tooltip Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Trigger element and content |
+| `delay` | `number` | `1500` or CSS variable | Delay in milliseconds before showing the tooltip. Can be globally configured via `--tooltip-delay` |
+| `closeDelay` | `number` | `500` or CSS variable | Delay in milliseconds before hiding the tooltip. Can be globally configured via `--tooltip-close-delay` |
+| `trigger` | `"hover" \| "focus"` | `"hover"` | How the tooltip is triggered |
+| `isDisabled` | `boolean` | `false` | Whether the tooltip is disabled |
+
+### Tooltip.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content to display in the tooltip |
+| `showArrow` | `boolean` | `false` | Whether to show the arrow indicator |
+| `offset` | `number` | `3` (7 with arrow) | Distance from the trigger element |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"top"` | Placement of the tooltip |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Tooltip.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Element that triggers the tooltip |
+| `className` | `string` | - | Additional CSS classes |
+
+### Tooltip.Arrow Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Custom arrow element |
+| `className` | `string` | - | Additional CSS classes |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | Overrides the default DOM element with a custom render function.|
diff --git a/apps/docs/content/docs/en/react/components/(pickers)/autocomplete.mdx b/apps/docs/content/docs/en/react/components/(pickers)/autocomplete.mdx
new file mode 100644
index 0000000..a0b4aa7
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(pickers)/autocomplete.mdx
@@ -0,0 +1,401 @@
+---
+title: Autocomplete
+description: An autocomplete combines a select with filtering, allowing users to search and select from a list of options
+links:
+  rac: Select
+  source: autocomplete/autocomplete.tsx
+  styles: autocomplete.css
+  storybook: Components/Pickers/Autocomplete
+---
+
+## Import
+
+```tsx
+import { Autocomplete, useFilter } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview name="autocomplete-default" />
+
+### Anatomy
+
+Import the Autocomplete component and access all parts using dot notation.
+
+```tsx
+import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";
+
+export default () => (
+  <Autocomplete>
+    <Label />
+    <Autocomplete.Trigger>
+      <Autocomplete.Value />
+      <Autocomplete.ClearButton />
+      <Autocomplete.Indicator />
+    </Autocomplete.Trigger>
+    <Description />
+    <Autocomplete.Popover>
+      <Autocomplete.Filter>
+        <SearchField>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input />
+          </SearchField.Group>
+        </SearchField>
+        <ListBox>
+          <ListBox.Item>
+            <Label />
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Autocomplete.Filter>
+    </Autocomplete.Popover>
+  </Autocomplete>
+);
+```
+
+### With Description
+
+<ComponentPreview name="autocomplete-with-description" />
+
+### Multiple Select
+
+<ComponentPreview name="autocomplete-multiple-select" />
+
+### With Sections
+
+<ComponentPreview name="autocomplete-with-sections" />
+
+### With Disabled Options
+
+<ComponentPreview name="autocomplete-with-disabled-options" />
+
+### Allows Empty Collection
+
+The `allowsEmptyCollection` prop enables the autocomplete to function even when there are no items in the collection. This is useful for scenarios where the list might be empty initially or when all items are filtered out.
+
+<ComponentPreview name="autocomplete-allows-empty-collection" />
+
+### Custom Indicator
+
+<ComponentPreview name="autocomplete-custom-indicator" />
+
+### Required
+
+<ComponentPreview name="autocomplete-required" />
+
+### Full Width
+
+<ComponentPreview name="autocomplete-full-width" />
+
+### Variants
+
+The Autocomplete component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="autocomplete-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="autocomplete-full-width" />
+
+### Custom Value
+
+You can customize the displayed value using render props:
+
+<ComponentPreview name="autocomplete-user-selection" />
+
+### Controlled
+
+<ComponentPreview name="autocomplete-controlled" />
+
+### Controlled Multiple
+
+<ComponentPreview name="autocomplete-multiple-select" />
+
+### Controlled Open State
+
+<ComponentPreview name="autocomplete-controlled-open-state" />
+
+### Asynchronous Filtering
+
+<ComponentPreview name="autocomplete-asynchronous-filtering" />
+
+### Virtualization
+
+Autocomplete supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
+
+<ComponentPreview name="autocomplete-virtualization" />
+
+### Disabled
+
+<ComponentPreview name="autocomplete-disabled" />
+
+### Advanced Examples
+
+#### User Selection
+
+<ComponentPreview name="autocomplete-user-selection" />
+
+#### User Selection Multiple
+
+<ComponentPreview name="autocomplete-user-selection-multiple" />
+
+#### Location Search
+
+<ComponentPreview name="autocomplete-location-search" />
+
+#### Tag Group Selection
+
+<ComponentPreview name="autocomplete-tag-group-selection" />
+
+#### Email Recipients
+
+<ComponentPreview name="autocomplete-email-recipients" />
+
+<RelatedComponents component="autocomplete" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Autocomplete, SearchField, ListBox} from "@heroui/react";
+
+function CustomAutocomplete() {
+  return (
+    <Autocomplete className="w-full">
+      <Label>State</Label>
+      <Autocomplete.Trigger className="rounded-lg border bg-surface p-2">
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+              Item 1
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Autocomplete component classes, you can use the `@layer components` directive.
+
+<br />
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .autocomplete {
+    @apply flex flex-col gap-1;
+  }
+
+  .autocomplete__trigger {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .autocomplete__value {
+    @apply text-current;
+  }
+
+  .autocomplete__clear-button {
+    @apply text-muted hover:text-foreground;
+  }
+
+  .autocomplete__indicator {
+    @apply text-muted;
+  }
+
+  .autocomplete__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .autocomplete__popover-dialog {
+    @apply outline-none;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Autocomplete component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)):
+
+#### Base Classes
+
+- `.autocomplete` - Base autocomplete container
+- `.autocomplete__trigger` - The button that triggers the autocomplete
+- `.autocomplete__value` - The displayed value or placeholder
+- `.autocomplete__clear-button` - The clear button that removes the selected value
+- `.autocomplete__indicator` - The dropdown indicator icon
+- `.autocomplete__popover` - The popover container
+- `.autocomplete__popover-dialog` - Internal dialog wrapper inside the popover for focus management (matches [Popover](/docs/components/popover) behavior)
+- `.autocomplete__filter` - The filter wrapper
+
+#### Variant Classes
+
+- `.autocomplete--primary` - Primary variant with shadow (default)
+- `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces
+
+#### State Classes
+
+- `.autocomplete[data-invalid="true"]` - Invalid state
+- `.autocomplete__trigger[data-focus-visible="true"]` - Focused trigger state
+- `.autocomplete__trigger[data-disabled="true"]` - Disabled trigger state
+- `.autocomplete__value[data-placeholder="true"]` - Placeholder state
+- `.autocomplete__clear-button[data-empty="true"]` - Clear button hidden when no selection
+- `.autocomplete__indicator[data-open="true"]` - Open indicator state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on autocomplete
+- **Open**: `[data-open="true"]` on indicator
+
+## API Reference
+
+### Autocomplete Props
+
+| Prop            | Type                                    | Default            | Description                                              |
+| --------------- | --------------------------------------- | ------------------ | -------------------------------------------------------- |
+| `placeholder`   | `string`                                | `'Select an item'` | Temporary text that occupies the autocomplete when it is empty |
+| `selectionMode` | `"single" \| "multiple"`                | `"single"`         | Whether single or multiple selection is enabled          |
+| `allowsEmptyCollection` | `boolean`                        | `false`            | Whether the autocomplete allows an empty collection. When true, the autocomplete can function even with no items. |
+| `isOpen`        | `boolean`                               | -                  | Sets the open state of the popover (controlled)             |
+| `defaultOpen`   | `boolean`                               | -                  | Sets the default open state of the popover (uncontrolled)   |
+| `onOpenChange`  | `(isOpen: boolean) => void`             | -                  | Handler called when the open state changes               |
+| `disabledKeys`  | `Iterable<Key>`                         | -                  | Keys of disabled items                                   |
+| `isDisabled`    | `boolean`                               | -                  | Whether the autocomplete is disabled                           |
+| `value`         | `Key \| Key[] \| null`                  | -                  | Current value (controlled)                               |
+| `defaultValue`  | `Key \| Key[] \| null`                  | -                  | Default value (uncontrolled)                             |
+| `onChange`      | `(value: Key \| Key[] \| null) => void` | -                  | Handler called when the value changes                    |
+| `isRequired`    | `boolean`                               | -                  | Whether user input is required                           |
+| `isInvalid`     | `boolean`                               | -                  | Whether the autocomplete value is invalid                      |
+| `name`          | `string`                                | -                  | The name of the input, used when submitting an HTML form |
+| `fullWidth`     | `boolean`                               | `false`             | Whether the autocomplete should take full width of its container |
+| `variant`       | `"primary" \| "secondary"`             | `"primary"`         | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `className`     | `string`                                | -                  | Additional CSS classes                                   |
+| `children`      | `ReactNode \| RenderFunction`           | -                  | Autocomplete content or render function                        |
+
+### Autocomplete.Trigger Props
+
+| Prop        | Type                          | Default | Description                        |
+| ----------- | ----------------------------- | ------- | ---------------------------------- |
+| `className` | `string`                      | -       | Additional CSS classes             |
+| `children`  | `ReactNode \| RenderFunction` | -       | Trigger content or render function |
+
+### Autocomplete.Value Props
+
+| Prop        | Type                          | Default | Description                      |
+| ----------- | ----------------------------- | ------- | -------------------------------- |
+| `className` | `string`                      | -       | Additional CSS classes           |
+| `children`  | `ReactNode \| RenderFunction` | -       | Value content or render function |
+
+### Autocomplete.Indicator Props
+
+| Prop        | Type        | Default | Description              |
+| ----------- | ----------- | ------- | ------------------------ |
+| `className` | `string`    | -       | Additional CSS classes   |
+| `children`  | `ReactNode` | -       | Custom indicator content |
+
+### Autocomplete.ClearButton Props
+
+| Prop        | Type                          | Default | Description                      |
+| ----------- | ----------------------------- | ------- | -------------------------------- |
+| `className` | `string`                      | -       | Additional CSS classes           |
+| `onClick`   | `(e: MouseEvent) => void`     | -       | Handler called when button is clicked |
+| `ref`       | `RefObject<HTMLButtonElement>` | -       | Ref to the clear button element  |
+
+### Autocomplete.Popover Props
+
+| Prop        | Type                                                                                                                                                                                                                                                                                                                     | Default    | Description                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
+| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | Additional CSS classes                           |
+| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | Content children. Wrapped internally in a dialog element for focus management, styled with `.autocomplete__popover-dialog`. |
+
+### Autocomplete.Filter Props
+
+| Prop         | Type                                           | Default | Description                      |
+| ------------ | ---------------------------------------------- | ------- | -------------------------------- |
+| `filter`     | `(text: string, input: string) => boolean`     | -       | Custom filter function           |
+| `inputValue` | `string`                                       | -       | Controlled input value          |
+| `onInputChange` | `(value: string) => void`                  | -       | Handler called when input value changes |
+| `children`   | `ReactNode`                                    | -       | Filter content (SearchField and ListBox) |
+
+### useFilter Hook
+
+The `useFilter` hook from React Aria provides filtering functions for autocomplete functionality.
+
+```tsx
+import {useFilter} from "@heroui/react";
+
+const {contains} = useFilter({sensitivity: "base"});
+
+<Autocomplete.Filter filter={contains}>
+  <SearchField>...</SearchField>
+  <ListBox>...</ListBox>
+</Autocomplete.Filter>
+```
+
+**Options:**
+
+| Option        | Type                                                         | Default      | Description                     |
+| ------------- | ------------------------------------------------------------ | ------------ | ------------------------------- |
+| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"`                  | `"base"`     | Locale sensitivity for matching |
+
+**Returns:**
+
+| Function        | Type                                                | Description                     |
+| --------------- | --------------------------------------------------- | ------------------------------- |
+| `contains`      | `(string: string, substring: string) => boolean`          | Returns whether a string contains a given substring |
+| `startsWith`    | `(string: string, substring: string) => boolean`          | Returns whether a string starts with a given substring    |
+| `endsWith`      | `(string: string, substring: string) => boolean`          | Returns whether a string ends with a given substring     |
+
+### RenderProps
+
+When using render functions with Autocomplete.Value, these values are provided:
+
+| Prop              | Type          | Description                        |
+| ----------------- | ------------- | ---------------------------------- |
+| `defaultChildren` | `ReactNode`   | The default rendered value         |
+| `isPlaceholder`   | `boolean`     | Whether the value is a placeholder |
+| `state`           | `SelectState` | The state of the autocomplete      |
+| `selectedItems`   | `Node[]`      | The currently selected items       |
+
+## Accessibility
+
+The Autocomplete component implements the ARIA select pattern with filtering and provides:
+
+- Full keyboard navigation support
+- Screen reader announcements for selection changes
+- Focus management aligned with [Popover](/docs/components/popover): `Autocomplete.Popover` wraps its content in an internal dialog so touch interactions do not show a stray focus ring on the popover overlay
+- Support for disabled states
+- Search functionality with filtering
+- HTML form integration
+
+Use `autoFocus={false}` on `SearchField` when you want to avoid opening the mobile keyboard as soon as the popover appears. Filtering still works once the user focuses the search input.
+
+For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html).
diff --git a/apps/docs/content/docs/en/react/components/(pickers)/combo-box.mdx b/apps/docs/content/docs/en/react/components/(pickers)/combo-box.mdx
new file mode 100644
index 0000000..650a311
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(pickers)/combo-box.mdx
@@ -0,0 +1,827 @@
+---
+title: ComboBox
+description: A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query
+links:
+  rac: ComboBox
+  source: combo-box/combo-box.tsx
+  styles: combo-box.css
+  storybook: Components/Pickers/ComboBox
+---
+
+## Import
+
+```tsx
+import { ComboBox } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="combo-box-default"
+/>
+
+### Anatomy
+
+Import the ComboBox component and access all parts using dot notation.
+
+```tsx
+import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react';
+
+export default () => (
+  <ComboBox>
+    <Label />
+    <ComboBox.InputGroup>
+      <Input />
+      <ComboBox.Trigger />
+    </ComboBox.InputGroup>
+    <Description />
+    <ComboBox.Popover>
+      <ListBox>
+        <ListBox.Item>
+          <Label />
+          <Description />
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Section>
+          <Header />
+          <ListBox.Item>
+            <Label />
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </ComboBox.Popover>
+  </ComboBox>
+)
+```
+
+### With Description
+
+<ComponentPreview
+  name="combo-box-with-description"
+/>
+
+### With Sections
+
+<ComponentPreview
+  name="combo-box-with-sections"
+/>
+
+### With Disabled Options
+
+<ComponentPreview
+  name="combo-box-with-disabled-options"
+/>
+
+### Custom Indicator
+
+<ComponentPreview
+  name="combo-box-custom-indicator"
+/>
+
+### Required
+
+<ComponentPreview
+  name="combo-box-required"
+/>
+
+### Custom Value
+
+<ComponentPreview
+  name="combo-box-custom-value"
+/>
+
+### Controlled
+
+<ComponentPreview
+  name="combo-box-controlled"
+/>
+
+### Controlled Input Value
+
+<ComponentPreview
+  name="combo-box-controlled-input-value"
+/>
+
+### Asynchronous Loading
+
+<ComponentPreview
+  name="combo-box-asynchronous-loading"
+/>
+
+### Custom Filtering
+
+<ComponentPreview
+  name="combo-box-custom-filtering"
+/>
+
+### Allows Custom Value
+
+<ComponentPreview
+  name="combo-box-allows-custom-value"
+/>
+
+### Disabled
+
+<ComponentPreview
+  name="combo-box-disabled"
+/>
+
+### Default Selected Key
+
+<ComponentPreview
+  name="combo-box-default-selected-key"
+/>
+
+### Full Width
+
+<ComponentPreview
+  name="combo-box-full-width"
+/>
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview
+  name="combo-box-on-surface"
+/>
+
+### Menu Trigger
+
+Use the `menuTrigger` prop to control when the popover opens:
+
+- `focus` (default): popover opens when the user focuses the input
+- `input`: popover opens when the user edits the input text
+- `manual`: popover only opens when the user presses the trigger button or uses the arrow keys
+
+<ComponentPreview
+  name="combo-box-menu-trigger"
+/>
+
+### Custom Render Function
+
+<ComponentPreview
+  name="combo-box-custom-render-function"
+/>
+
+<RelatedComponents component="combo-box" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { ComboBox, Input } from '@heroui/react';
+
+function CustomComboBox() {
+  return (
+    <ComboBox className="w-full">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup className="border rounded-lg p-2 bg-surface">
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger className="text-muted" />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ComboBox component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .combo-box {
+    @apply flex flex-col gap-1;
+  }
+
+  .combo-box__input-group {
+    @apply relative inline-flex items-center;
+  }
+
+  .combo-box__trigger {
+    @apply absolute right-0 text-muted;
+  }
+
+  .combo-box__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ComboBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)):
+
+#### Base Classes
+- `.combo-box` - Base ComboBox container
+- `.combo-box__input-group` - Container for the input and trigger button
+- `.combo-box__trigger` - The button that triggers the popover
+- `.combo-box__popover` - The popover container
+
+#### State Classes
+- `.combo-box[data-invalid="true"]` - Invalid state
+- `.combo-box[data-disabled="true"]` - Disabled ComboBox state
+- `.combo-box__trigger[data-focus-visible="true"]` - Focused trigger state
+- `.combo-box__trigger[data-disabled="true"]` - Disabled trigger state
+- `.combo-box__trigger[data-open="true"]` - Open trigger state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on ComboBox
+- **Open**: `[data-open="true"]` on trigger
+
+## API Reference
+
+### ComboBox Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `inputValue` | `string` | - | Current input value (controlled) |
+| `defaultInputValue` | `string` | - | Default input value (uncontrolled) |
+| `onInputChange` | `(value: string) => void` | - | Handler called when the input value changes |
+| `selectedKey` | `Key \| null` | - | Current selected key (controlled) |
+| `defaultSelectedKey` | `Key \| null` | - | Default selected key (uncontrolled) |
+| `onSelectionChange` | `(key: Key \| null) => void` | - | Handler called when the selection changes |
+| `isOpen` | `boolean` | - | Sets the open state of the popover (controlled) |
+| `defaultOpen` | `boolean` | - | Sets the default open state of the popover (uncontrolled) |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes |
+| `items` | `Iterable<T>` | - | The items to display in the listbox |
+| `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items |
+| `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | Custom filter function for filtering items |
+| `isDisabled` | `boolean` | - | Whether the ComboBox is disabled |
+| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user |
+| `isRequired` | `boolean` | - | Whether user input is required |
+| `isInvalid` | `boolean` | - | Whether the ComboBox value is invalid |
+| `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead |
+| `validationBehavior` | `"native" \| "aria"` | `"native"` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA |
+| `name` | `string` | - | The name of the input, used when submitting an HTML form |
+| `form` | `string` | - | The id of a `<form>` element to associate the input with |
+| `formValue` | `"text" \| "key"` | `"key"` | Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted |
+| `autoComplete` | `string` | - | Describes the type of autocomplete functionality |
+| `autoFocus` | `boolean` | - | Whether the element should receive focus on render |
+| `allowsCustomValue` | `boolean` | - | Whether the ComboBox allows custom values not in the list |
+| `allowsEmptyCollection` | `boolean` | - | Whether the ComboBox allows an empty collection |
+| `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | The interaction required to display the ComboBox menu |
+| `shouldFocusWrap` | `boolean` | - | Whether keyboard navigation is circular |
+| `fullWidth` | `boolean` | `false` | Whether the ComboBox should take full width of its container |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode \| RenderFunction` | - | ComboBox content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### ComboBox.InputGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | InputGroup content |
+
+### ComboBox.Trigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom trigger content |
+
+### ComboBox.Popover Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Content children |
+
+### RenderProps
+
+When using render functions with ComboBox, these values are provided:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `state` | `ComboBoxState` | The state of the ComboBox |
+| `inputValue` | `string` | The current input value |
+| `selectedKey` | `Key \| null` | The currently selected key |
+| `selectedItem` | `Node \| null` | The currently selected item |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox className="w-[256px]">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### With Sections
+
+```tsx
+import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/react';
+
+<ComboBox className="w-[256px]">
+  <Label>Country</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search countries..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Section>
+        <Header>North America</Header>
+        <ListBox.Item id="usa" textValue="United States">
+          United States
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox.Section>
+      <Separator />
+      <ListBox.Section>
+        <Header>Europe</Header>
+        <ListBox.Item id="uk" textValue="United Kingdom">
+          United Kingdom
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox.Section>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### Controlled Selection
+
+```tsx
+import type { Key } from '@heroui/react';
+
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledComboBox() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>('cat');
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+    >
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### Controlled Input Value
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+import { useState } from 'react';
+
+function ControlledInputComboBox() {
+  const [inputValue, setInputValue] = useState('');
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      inputValue={inputValue}
+      onInputChange={setInputValue}
+    >
+      <Label>Search</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Type to search..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### Asynchronous Loading
+
+```tsx
+import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner } from '@heroui/react';
+import { useAsyncList } from '@react-stately/data';
+
+interface Character {
+  name: string;
+}
+
+function AsyncComboBox() {
+  const list = useAsyncList<Character>({
+    async load({cursor, filterText, signal}) {
+      const res = await fetch(
+        cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`,
+        { signal }
+      );
+      const json = await res.json();
+
+      return {
+        items: json.results,
+        cursor: json.next,
+      };
+    },
+  });
+
+  return (
+    <ComboBox
+      allowsEmptyCollection
+      className="w-[256px]"
+      inputValue={list.filterText}
+      onInputChange={list.setFilterText}
+    >
+      <Label>Pick a Character</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Star Wars characters..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox renderEmptyState={() => <EmptyState />}>
+          <Collection items={list.items}>
+            {(item) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="text-sm text-muted">Loading more...</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### Custom Filtering
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox
+  className="w-[256px]"
+  defaultFilter={(text, inputValue) => {
+    if (!inputValue) return true;
+    return text.toLowerCase().includes(inputValue.toLowerCase());
+  }}
+>
+  <Label>Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+### Menu Trigger
+
+Control when the popover opens using the `menuTrigger` prop:
+
+```tsx
+import { ComboBox, Description, Input, Label, ListBox } from '@heroui/react';
+
+// Opens on focus (default)
+<ComboBox className="w-[256px]" menuTrigger="focus">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover opens when the input is focused</Description>
+</ComboBox>
+
+// Opens when typing
+<ComboBox className="w-[256px]" menuTrigger="input">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover opens when the user edits the input text</Description>
+</ComboBox>
+
+// Opens only manually
+<ComboBox className="w-[256px]" menuTrigger="manual">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+  <Description>Popover only opens when the trigger button is pressed or arrow keys are used</Description>
+</ComboBox>
+```
+
+### Form Value
+
+Use the `formValue` prop to control whether the selected item's key or text is submitted in forms:
+
+```tsx
+import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react';
+
+function FormValueExample() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    console.log('Submitted value:', formData.get('animal')); // Will be "cat" (the key)
+  };
+
+  return (
+    <Form onSubmit={onSubmit}>
+      {/* Submits the key (default) */}
+      <ComboBox name="animal" formValue="key" isRequired>
+        <Label>Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Select an animal..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+
+      {/* Submits the text */}
+      <ComboBox name="animal-text" formValue="text" isRequired>
+        <Label>Animal (text)</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Select an animal..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+### Validation Behavior
+
+Control how validation is displayed using the `validationBehavior` prop:
+
+```tsx
+import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react';
+
+function ValidationExample() {
+  return (
+    <div className="space-y-8">
+      {/* Native validation (default) - blocks form submission */}
+      <Form>
+        <ComboBox name="animal" isRequired validationBehavior="native">
+          <Label>Animal (native validation)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Select an animal..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+
+      {/* ARIA validation - shows errors in realtime, doesn't block submission */}
+      <Form>
+        <ComboBox name="animal-aria" isRequired validationBehavior="aria">
+          <Label>Animal (ARIA validation)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Select an animal..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+    </div>
+  );
+}
+```
+
+### Custom Validation
+
+Use the `validate` prop to add custom validation logic:
+
+```tsx
+import { ComboBox, FieldError, Input, Label, ListBox } from '@heroui/react';
+
+function CustomValidationExample() {
+  return (
+    <ComboBox
+      className="w-[256px]"
+      isRequired
+      validate={(value) => {
+        if (!value || value.selectedKey === null) {
+          return 'Please select an animal';
+        }
+        if (value.selectedKey === 'snake') {
+          return 'Snakes are not allowed';
+        }
+        return true;
+      }}
+    >
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <FieldError />
+    </ComboBox>
+  );
+}
+```
+
+### Read Only
+
+Use the `isReadOnly` prop to make the comboBox read-only:
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from '@heroui/react';
+
+<ComboBox className="w-[256px]" isReadOnly defaultSelectedKey="cat">
+  <Label>Favorite Animal</Label>
+  <ComboBox.InputGroup>
+    <Input placeholder="Search animals..." />
+    <ComboBox.Trigger />
+  </ComboBox.InputGroup>
+  <ComboBox.Popover>
+    <ListBox>
+      <ListBox.Item id="cat" textValue="Cat">
+        Cat
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="dog" textValue="Dog">
+        Dog
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  </ComboBox.Popover>
+</ComboBox>
+```
+
+## Accessibility
+
+The ComboBox component implements the ARIA comboBox pattern and provides:
+
+- Full keyboard navigation support
+- Screen reader announcements for selection changes and input changes
+- Proper focus management
+- Support for disabled states
+- Typeahead search functionality
+- HTML form integration
+- Support for custom values
+
+For more information, see the [React Aria ComboBox documentation](https://react-spectrum.adobe.com/react-aria/ComboBox.html).
+
diff --git a/apps/docs/content/docs/en/react/components/(pickers)/select.mdx b/apps/docs/content/docs/en/react/components/(pickers)/select.mdx
new file mode 100644
index 0000000..631c39f
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(pickers)/select.mdx
@@ -0,0 +1,302 @@
+---
+title: Select
+description: A select displays a collapsible list of options and allows a user to select one of them
+links:
+  rac: Select
+  source: select/select.tsx
+  styles: select.css
+  storybook: Components/Pickers/Select
+---
+
+## Import
+
+```tsx
+import { Select } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview name="select-default" />
+
+### Anatomy
+
+Import the Select component and access all parts using dot notation.
+
+```tsx
+import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react";
+
+export default () => (
+  <Select>
+    <Label />
+    <Select.Trigger>
+      <Select.Value />
+      <Select.Indicator />
+    </Select.Trigger>
+    <Description />
+    <Select.Popover>
+      <ListBox>
+        <ListBox.Item>
+          <Label />
+          <Description />
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Section>
+          <Header />
+          <ListBox.Item>
+            <Label />
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Select.Popover>
+  </Select>
+);
+```
+
+### With Description
+
+<ComponentPreview name="select-with-description" />
+
+### Multiple Select
+
+<ComponentPreview name="select-multiple-select" />
+
+### With Sections
+
+<ComponentPreview name="select-with-sections" />
+
+### With Disabled Options
+
+<ComponentPreview name="select-with-disabled-options" />
+
+### Custom Indicator
+
+<ComponentPreview name="select-custom-indicator" />
+
+### Required
+
+<ComponentPreview name="select-required" />
+
+### Full Width
+
+<ComponentPreview name="select-full-width" />
+
+### Variants
+
+The Select component supports two visual variants:
+
+- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
+- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview name="select-variants" />
+
+### In Surface
+
+When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
+
+<ComponentPreview name="select-on-surface" />
+
+### Custom Value
+
+<ComponentPreview name="select-custom-value" />
+
+### Controlled
+
+<ComponentPreview name="select-controlled" />
+
+### Controlled Multiple
+
+<ComponentPreview name="select-controlled-multiple" />
+
+### Controlled Open State
+
+<ComponentPreview name="select-controlled-open-state" />
+
+### Asynchronous Loading
+
+<ComponentPreview name="select-asynchronous-loading" />
+
+### Disabled
+
+<ComponentPreview name="select-disabled" />
+
+<RelatedComponents component="select" />
+
+### Custom Render Function
+
+<ComponentPreview
+  name="select-custom-render-function"
+/>
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {Select} from "@heroui/react";
+
+function CustomSelect() {
+  return (
+    <Select className="w-full">
+      <Label>State</Label>
+      <Select.Trigger className="rounded-lg border bg-surface p-2">
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
+            Item 1
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Select component classes, you can use the `@layer components` directive.
+
+<br />
+[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .select {
+    @apply flex flex-col gap-1;
+  }
+
+  .select__trigger {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+
+  .select__value {
+    @apply text-current;
+  }
+
+  .select__indicator {
+    @apply text-muted;
+  }
+
+  .select__popover {
+    @apply rounded-lg border border-border bg-surface p-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Select component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/select.css)):
+
+#### Base Classes
+
+- `.select` - Base select container
+- `.select__trigger` - The button that triggers the select
+- `.select__value` - The displayed value or placeholder
+- `.select__indicator` - The dropdown indicator icon
+- `.select__popover` - The popover container
+
+#### Variant Classes
+
+- `.select--primary` - Primary variant with shadow (default)
+- `.select--secondary` - Secondary variant without shadow, suitable for use in surfaces
+
+#### State Classes
+
+- `.select[data-invalid="true"]` - Invalid state
+- `.select__trigger[data-focus-visible="true"]` - Focused trigger state
+- `.select__trigger[data-disabled="true"]` - Disabled trigger state
+- `.select__value[data-placeholder="true"]` - Placeholder state
+- `.select__indicator[data-open="true"]` - Open indicator state
+
+### Interactive States
+
+The component supports both CSS pseudo-classes and data attributes for flexibility:
+
+- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
+- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
+- **Disabled**: `:disabled` or `[data-disabled="true"]` on select
+- **Open**: `[data-open="true"]` on indicator
+
+## API Reference
+
+### Select Props
+
+| Prop            | Type                                    | Default            | Description                                              |
+| --------------- | --------------------------------------- | ------------------ | -------------------------------------------------------- |
+| `placeholder`   | `string`                                | `'Select an item'` | Temporary text that occupies the select when it is empty |
+| `selectionMode` | `"single" \| "multiple"`                | `"single"`         | Whether single or multiple selection is enabled          |
+| `isOpen`        | `boolean`                               | -                  | Sets the open state of the menu (controlled)             |
+| `defaultOpen`   | `boolean`                               | -                  | Sets the default open state of the menu (uncontrolled)   |
+| `onOpenChange`  | `(isOpen: boolean) => void`             | -                  | Handler called when the open state changes               |
+| `disabledKeys`  | `Iterable<Key>`                         | -                  | Keys of disabled items                                   |
+| `isDisabled`    | `boolean`                               | -                  | Whether the select is disabled                           |
+| `value`         | `Key \| Key[] \| null`                  | -                  | Current value (controlled)                               |
+| `defaultValue`  | `Key \| Key[] \| null`                  | -                  | Default value (uncontrolled)                             |
+| `onChange`      | `(value: Key \| Key[] \| null) => void` | -                  | Handler called when the value changes                    |
+| `isRequired`    | `boolean`                               | -                  | Whether user input is required                           |
+| `isInvalid`     | `boolean`                               | -                  | Whether the select value is invalid                      |
+| `name`          | `string`                                | -                  | The name of the input, used when submitting an HTML form |
+| `autoComplete`  | `string`                                | -                  | Describes the type of autocomplete functionality         |
+| `fullWidth`     | `boolean`                               | `false`             | Whether the select should take full width of its container |
+| `variant`       | `"primary" \| "secondary"`             | `"primary"`         | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
+| `className`     | `string`                                | -                  | Additional CSS classes                                   |
+| `children`      | `ReactNode \| RenderFunction`           | -                  | Select content or render function                        |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Select.Trigger Props
+
+| Prop        | Type                          | Default | Description                        |
+| ----------- | ----------------------------- | ------- | ---------------------------------- |
+| `className` | `string`                      | -       | Additional CSS classes             |
+| `children`  | `ReactNode \| RenderFunction` | -       | Trigger content or render function |
+
+### Select.Value Props
+
+| Prop        | Type                          | Default | Description                      |
+| ----------- | ----------------------------- | ------- | -------------------------------- |
+| `className` | `string`                      | -       | Additional CSS classes           |
+| `children`  | `ReactNode \| RenderFunction` | -       | Value content or render function |
+| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectValueRenderProps>` | - | Overrides the default DOM element with a custom render function.|
+
+### Select.Indicator Props
+
+| Prop        | Type        | Default | Description              |
+| ----------- | ----------- | ------- | ------------------------ |
+| `className` | `string`    | -       | Additional CSS classes   |
+| `children`  | `ReactNode` | -       | Custom indicator content |
+
+### Select.Popover Props
+
+| Prop        | Type                                                                                                                                                                                                                                                                                                                     | Default    | Description                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
+| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
+| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | Additional CSS classes                           |
+| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | Content children                                 |
+
+### RenderProps
+
+When using render functions with Select.Value, these values are provided:
+
+| Prop              | Type          | Description                        |
+| ----------------- | ------------- | ---------------------------------- |
+| `defaultChildren` | `ReactNode`   | The default rendered value         |
+| `isPlaceholder`   | `boolean`     | Whether the value is a placeholder |
+| `state`           | `SelectState` | The state of the select            |
+| `selectedItems`   | `Node[]`      | The currently selected items       |
+
+## Accessibility
+
+The Select component implements the ARIA listbox pattern and provides:
+
+- Full keyboard navigation support
+- Screen reader announcements for selection changes
+- Proper focus management
+- Support for disabled states
+- Typeahead search functionality
+- HTML form integration
+
+For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html).
diff --git a/apps/docs/content/docs/en/react/components/(typography)/kbd.mdx b/apps/docs/content/docs/en/react/components/(typography)/kbd.mdx
new file mode 100644
index 0000000..0231476
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(typography)/kbd.mdx
@@ -0,0 +1,157 @@
+---
+title: Kbd
+description: Display keyboard shortcuts and key combinations
+links:
+  source: kbd/kbd.tsx
+  styles: kbd.css
+  storybook: Components/Typography/Kbd
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Kbd } from "@heroui/react";
+```
+
+### Usage
+
+<ComponentPreview 
+  name="kbd-basic"
+/>
+
+### Anatomy
+
+Import the Kbd component and access all parts using dot notation.
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default () => (
+  <Kbd>
+    <Kbd.Abbr title="Command">⌘</Kbd.Abbr>
+    <Kbd.Content>K</Kbd.Content>
+  </Kbd>
+);
+```
+
+### Navigation Keys
+
+<ComponentPreview 
+  name="kbd-navigation-keys"
+/>
+
+### Inline Usage
+
+<ComponentPreview 
+  name="kbd-inline-usage"
+/>
+
+### Instructional Text
+
+<ComponentPreview 
+  name="kbd-instructional-text"
+/>
+
+### Special Keys
+
+<ComponentPreview 
+  name="kbd-special-keys"
+/>
+
+### Variants
+
+<ComponentPreview 
+  name="kbd-variants"
+/>
+
+<RelatedComponents component="kbd" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+function CustomKbd() {
+  return (
+    <Kbd className="bg-gray-100 dark:bg-gray-800">
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Kbd component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .kbd {
+    @apply bg-gray-100 dark:bg-gray-800 border-gray-300;
+  }
+
+  .kbd__abbr {
+    @apply font-bold;
+  }
+
+  .kbd__content {
+    @apply text-sm;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Kbd component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)):
+
+#### Base Classes
+
+- `.kbd` - Base keyboard key styles with background, border, and spacing
+- `.kbd__abbr` - Abbreviation element for modifier keys
+- `.kbd__content` - Content wrapper for key text
+
+## API Reference
+
+### Kbd Props
+
+| Prop        | Type              | Default | Description            |
+| ----------- | ----------------- | ------- | ---------------------- |
+| `children`  | `React.ReactNode` | -       | Content of the key     |
+| `variant`   | `"default" | "light"` | `default`       | Variant of the keyboard key |
+| `className` | `string`          | -       | Custom CSS classes     |
+
+### Kbd.Abbr Props
+
+| Prop        | Type     | Default | Description                                                                                                                               |
+| ----------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`     | `string` | -       | Title attribute for accessibility (e.g., "Command" for ⌘)                                                                               |
+| `children`  | `React.ReactNode` | -       | The symbol or text to display (e.g., ⌘, ⌥, ⇧)                                                                                          |
+| `className` | `string` | -       | Custom CSS classes                                                                                                                       |
+
+### Kbd.Key Props
+
+| Prop        | Type              | Default | Description                        |
+| ----------- | ----------------- | ------- | ---------------------------------- |
+| `children`  | `React.ReactNode` | -       | Text content of the key            |
+| `className` | `string`          | -       | Custom CSS classes                 |
+
+### Kbd.Content Type
+
+Available key values for the `keyValue` prop:
+
+| Modifier Keys | Special Keys | Navigation Keys | Function Keys |
+| ------------- | ------------ | --------------- | ------------- |
+| `command`     | `enter`      | `up`            | `fn`          |
+| `shift`       | `delete`     | `down`          |               |
+| `ctrl`        | `escape`     | `left`          |               |
+| `option`      | `tab`        | `right`         |               |
+| `alt`         | `space`      | `pageup`        |               |
+| `win`         | `capslock`   | `pagedown`      |               |
+|               | `help`       | `home`          |               |
+|               |              | `end`           |               |
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/components/(typography)/typography.mdx b/apps/docs/content/docs/en/react/components/(typography)/typography.mdx
new file mode 100644
index 0000000..6ae567b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(typography)/typography.mdx
@@ -0,0 +1,73 @@
+---
+title: Typography
+description: A semantic typography primitive for headings, body copy, and inline code built on React Aria Components Text.
+links:
+  source: typography/typography.tsx
+  styles: typography.css
+  storybook: Components/Typography
+---
+
+## Import
+
+```tsx
+import {Typography} from "@heroui/react";
+```
+
+## Usage
+
+<ComponentPreview name="typography-typography-scale" />
+
+`Typography` maps visual `type` values to semantic elements by default.
+
+## Primitives
+
+<ComponentPreview name="typography-primitives" />
+
+- `Typography.Heading` maps `level={1..6}` to `type="h1"` through `type="h6"`.
+- `Typography.Paragraph` maps `size="base" | "sm" | "xs"` to body text styles.
+- `Typography.Code` maps to the inline code style.
+- `Typography.Prose` styles rich content passed as regular HTML children.
+
+## Prose
+
+<ComponentPreview name="typography-prose" />
+
+## Render Prop
+
+<ComponentPreview name="typography-render-props" />
+
+Use the React Aria Components-style `render` prop when you need to customize the rendered element.
+
+## CSS Classes
+
+### Base Classes
+
+- `.typography` - Base typography primitive
+- `.typography-prose` - Rich prose container
+
+### Type Classes
+
+- `.typography--h1` through `.typography--h6`
+- `.typography--body`, `.typography--body-sm`, `.typography--body-xs`
+- `.typography--code`
+
+### Modifier Classes
+
+- `.typography--align-start`, `.typography--align-center`, `.typography--align-end`, `.typography--align-justify`
+- `.typography--color-default`, `.typography--color-muted`
+- `.typography--truncate`
+- `.typography--weight-normal`, `.typography--weight-medium`, `.typography--weight-semibold`, `.typography--weight-bold`
+
+## API Reference
+
+### Typography Props
+
+| Prop       | Type                                                                                           | Default     | Description                                    |
+| ---------- | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------- |
+| `type`     | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'`    | Semantic typography style.                     |
+| `align`    | `'start' \| 'center' \| 'end' \| 'justify'`                                                 | `'start'`   | Text alignment.                                |
+| `color`    | `'default' \| 'muted'`                                                                        | `'default'` | Text color.                                    |
+| `weight`   | `'normal' \| 'medium' \| 'semibold' \| 'bold'`                                              | -           | Font weight override.                          |
+| `truncate` | `boolean`                                                                                      | -           | Truncates the text to one line with ellipsis.  |
+| `render`   | `DOMRenderFunction`                                                                            | -           | Custom render function from React Aria.        |
+| `children` | `ReactNode`                                                                                    | -           | Text content.                                  |
diff --git a/apps/docs/content/docs/en/react/components/(utilities)/scroll-shadow.mdx b/apps/docs/content/docs/en/react/components/(utilities)/scroll-shadow.mdx
new file mode 100644
index 0000000..77d4c7b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/(utilities)/scroll-shadow.mdx
@@ -0,0 +1,139 @@
+---
+title: ScrollShadow
+description: Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position.
+links:
+  source: scroll-shadow/scroll-shadow.tsx
+  styles: scroll-shadow.css
+  storybook: Components/Utilities/ScrollShadow
+  figma: true
+---
+
+## Import
+
+```tsx
+import { ScrollShadow } from "@heroui/react";
+```
+
+## Usage
+
+<ComponentPreview name="scroll-shadow-default" />
+
+## Orientation
+
+<ComponentPreview name="scroll-shadow-orientation" />
+
+## Hide Scroll Bar
+
+<ComponentPreview name="scroll-shadow-hide-scroll-bar" />
+
+## Custom Shadow Size
+
+<ComponentPreview name="scroll-shadow-custom-size" />
+
+## Visibility Change
+
+<ComponentPreview name="scroll-shadow-visibility-change" />
+
+## With Card
+
+<ComponentPreview name="scroll-shadow-with-card" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import {ScrollShadow, Card} from "@heroui/react";
+
+function CustomScrollShadow() {
+  return (
+    <Card className="w-full p-0 sm:max-w-md">
+      <ScrollShadow className="max-h-[300px] p-6 bg-gradient-to-b from-purple-50 to-pink-50">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={idx}>
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+              risus hendrerit venenatis.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </Card>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the ScrollShadow component classes, you can use the `@layer components` directive.
+<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .scroll-shadow {
+    @apply rounded-xl border border-default-200;
+  }
+
+  .scroll-shadow--vertical {
+    @apply pr-2; /* Add padding for custom scrollbar styling */
+  }
+
+  .scroll-shadow--horizontal {
+    @apply pb-2;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The ScrollShadow component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/scroll-shadow.css)):
+
+#### Base Classes
+
+- `.scroll-shadow` - Root container element
+
+#### Orientation Variants
+
+- `.scroll-shadow--vertical` - Vertical scrolling (default)
+- `.scroll-shadow--horizontal` - Horizontal scrolling
+
+#### State Modifiers
+
+- `.scroll-shadow--hide-scrollbar` - Hides native scrollbar
+
+### CSS Variables
+
+The ScrollShadow component uses CSS variables to size the fade mask and reserve space for visible native scrollbars:
+
+| Variable                          | Default                                | Description                                                                                                      |
+| --------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--scroll-shadow-size`            | `40px`                                 | Controls the fade gradient size. This is set from the `size` prop.                                               |
+| `--scroll-shadow-scrollbar-size`  | `10px` (`0px` when `hideScrollBar`)    | Reserves a solid mask gutter for the native scrollbar so the fade does not cover it. Override for wider scrollbars. |
+
+### Data Attributes
+
+The component uses data attributes to control shadow visibility:
+
+- **Scroll States**: `[data-top-scroll]`, `[data-bottom-scroll]`, `[data-left-scroll]`, `[data-right-scroll]` - Applied when content can be scrolled in that direction
+- **Combined States**: `[data-top-bottom-scroll]`, `[data-left-right-scroll]` - Applied when content can be scrolled in both directions
+- **Orientation**: `[data-orientation="vertical"]` or `[data-orientation="horizontal"]` - Indicates scroll direction
+- **Size**: `[data-scroll-shadow-size]` - Contains the shadow gradient size value
+
+## API Reference
+
+### ScrollShadow
+
+| Prop                 | Type                                                                          | Default      | Description                                             |
+| -------------------- | ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
+| `orientation`        | `"vertical"` \| `"horizontal"`                                                | `"vertical"` | The scroll direction                                    |
+| `variant`            | `"fade"`                                                                      | `"fade"`     | The visual shadow effect style                          |
+| `size`               | `number`                                                                      | `40`         | The shadow gradient size in pixels                      |
+| `offset`             | `number`                                                                      | `0`          | The scroll offset before showing shadows (in pixels)    |
+| `hideScrollBar`      | `boolean`                                                                     | `false`      | Whether to hide the native scrollbar                    |
+| `isEnabled`          | `boolean`                                                                     | `true`       | Whether scroll shadow detection is enabled              |
+| `visibility`         | `"auto"` \| `"both"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"none"` | `"auto"`     | Controlled shadow visibility state                      |
+| `onVisibilityChange` | `(visibility: ScrollShadowVisibility) => void`                                | -            | Callback invoked when shadow visibility changes         |
+| `className`          | `string`                                                                      | -            | Additional CSS classes to apply to the root element     |
+| `children`           | `ReactNode`                                                                   | -            | The scrollable content                                  |
diff --git a/apps/docs/content/docs/en/react/components/index.mdx b/apps/docs/content/docs/en/react/components/index.mdx
new file mode 100644
index 0000000..107c895
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/index.mdx
@@ -0,0 +1,64 @@
+---
+title: All Components
+description: Explore the full list of components available in the library. More are on the way.
+---
+
+## Buttons
+
+<ComponentsCategory category="Buttons" />
+
+## Collections
+
+<ComponentsCategory category="Collections" />
+
+## Colors
+
+<ComponentsCategory category="Colors" />
+
+## Controls
+
+<ComponentsCategory category="Controls" />
+
+## Data Display
+
+<ComponentsCategory category="Data Display" />
+
+## Date and Time
+
+<ComponentsCategory category="Date and Time" />
+
+## Feedback
+
+<ComponentsCategory category="Feedback" />
+
+## Forms
+
+<ComponentsCategory category="Forms" />
+
+## Layout
+
+<ComponentsCategory category="Layout" />
+
+## Media
+
+<ComponentsCategory category="Media" />
+
+## Navigation
+
+<ComponentsCategory category="Navigation" />
+
+## Overlays
+
+<ComponentsCategory category="Overlays" />
+
+## Pickers
+
+<ComponentsCategory category="Pickers" />
+
+## Typography
+
+<ComponentsCategory category="Typography" />
+
+## Utilities
+
+<ComponentsCategory category="Utilities" />
diff --git a/apps/docs/content/docs/en/react/components/meta.json b/apps/docs/content/docs/en/react/components/meta.json
new file mode 100644
index 0000000..98a0613
--- /dev/null
+++ b/apps/docs/content/docs/en/react/components/meta.json
@@ -0,0 +1,82 @@
+{
+  "title": "Components",
+  "description": "HeroUI React components",
+  "root": true,
+  "icon": "circles-4-diamond",
+  "pages": [
+    "---Overview---",
+    "index",
+    "---Components---",
+    "(navigation)/accordion",
+    "(feedback)/alert",
+    "(overlays)/alert-dialog",
+    "(pickers)/autocomplete",
+    "(media)/avatar",
+    "(data-display)/badge",
+    "(navigation)/breadcrumbs",
+    "(buttons)/button",
+    "(buttons)/button-group",
+    "(date-and-time)/calendar",
+    "(layout)/card",
+    "(forms)/checkbox",
+    "(forms)/checkbox-group",
+    "(data-display)/chip",
+    "(buttons)/close-button",
+    "(colors)/color-area",
+    "(colors)/color-field",
+    "(colors)/color-slider",
+    "(colors)/color-swatch",
+    "(colors)/color-swatch-picker",
+    "(colors)/color-picker",
+    "(pickers)/combo-box",
+    "(date-and-time)/date-field",
+    "(date-and-time)/date-picker",
+    "(date-and-time)/date-range-picker",
+    "(forms)/description",
+    "(navigation)/disclosure",
+    "(navigation)/disclosure-group",
+    "(overlays)/drawer",
+    "(collections)/dropdown",
+    "(forms)/error-message",
+    "(forms)/field-error",
+    "(forms)/fieldset",
+    "(forms)/form",
+    "(forms)/input",
+    "(forms)/input-group",
+    "(forms)/input-otp",
+    "(typography)/kbd",
+    "(forms)/label",
+    "(navigation)/link",
+    "(collections)/list-box",
+    "(feedback)/meter",
+    "(overlays)/modal",
+    "(forms)/number-field",
+    "(navigation)/pagination",
+    "(overlays)/popover",
+    "(feedback)/progress-bar",
+    "(feedback)/progress-circle",
+    "(forms)/radio-group",
+    "(date-and-time)/range-calendar",
+    "(utilities)/scroll-shadow",
+    "(forms)/search-field",
+    "(pickers)/select",
+    "(layout)/separator",
+    "(feedback)/skeleton",
+    "(controls)/slider",
+    "(feedback)/spinner",
+    "(layout)/surface",
+    "(controls)/switch",
+    "(data-display)/table",
+    "(navigation)/tabs",
+    "(collections)/tag-group",
+    "(typography)/typography",
+    "(forms)/text-field",
+    "(forms)/text-area",
+    "(date-and-time)/time-field",
+    "(overlays)/toast",
+    "(layout)/toolbar",
+    "(buttons)/toggle-button",
+    "(buttons)/toggle-button-group",
+    "(overlays)/tooltip"
+  ]
+}
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/animation.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/animation.mdx
new file mode 100644
index 0000000..69678ec
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/animation.mdx
@@ -0,0 +1,248 @@
+---
+title: Animation
+description: Add smooth animations and transitions to HeroUI v3 components
+icon: copy-transparent
+---
+
+HeroUI components support multiple animation approaches: built-in CSS transitions, custom CSS animations, and JavaScript libraries like Framer Motion.
+
+## Built-in Animations
+
+HeroUI components use data attributes to expose their state for animation:
+
+```css
+/* Popover entrance/exit */
+.popover[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200;
+}
+
+.popover[data-exiting] {
+  @apply animate-out zoom-out-95 fade-out duration-150;
+}
+
+/* Button press effect */
+.button:active,
+.button[data-pressed="true"] {
+  transform: scale(0.97);
+}
+
+/* Accordion expansion */
+.accordion__panel[aria-hidden="false"] {
+  @apply h-[var(--panel-height)] opacity-100;
+}
+```
+
+**State attributes for styling:**
+- `[data-hovered="true"]` - Hover state
+- `[data-pressed="true"]` - Active/pressed state
+- `[data-focus-visible="true"]` - Keyboard focus
+- `[data-disabled="true"]` - Disabled state
+- `[data-entering]` / `[data-exiting]` - Transition states
+- `[aria-expanded="true"]` - Expanded state
+
+## CSS Animations
+
+**Using Tailwind utilities:**
+
+```tsx
+// Pulse on hover
+<Button className="hover:animate-pulse">
+  Hover me
+</Button>
+
+// Fade in entrance
+<Alert className="animate-fade-in">
+  Welcome message
+</Alert>
+
+// Staggered list
+<div className="space-y-2">
+  <Card className="animate-fade-in animate-delay-100">Item 1</Card>
+  <Card className="animate-fade-in animate-delay-200">Item 2</Card>
+</div>
+```
+
+**Custom transitions:**
+
+```css
+/* Slower accordion */
+.accordion__panel {
+  @apply transition-all duration-500;
+}
+
+/* Bouncy button */
+.button:active {
+  animation: bounce 0.3s;
+}
+
+@keyframes bounce {
+  50% { transform: scale(0.95); }
+}
+```
+
+## Framer Motion
+
+HeroUI components work seamlessly with Framer Motion for advanced animations.
+
+**Basic usage:**
+
+```tsx
+import { motion } from 'framer-motion';
+import { Button } from '@heroui/react';
+
+const MotionButton = motion(Button);
+
+<MotionButton
+  whileHover={{ scale: 1.05 }}
+  whileTap={{ scale: 0.95 }}
+>
+  Animated Button
+</MotionButton>
+```
+
+**Entrance animations:**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.5 }}
+>
+  <Alert>
+    <Alert.Title>Welcome!</Alert.Title>
+  </Alert>
+</motion.div>
+```
+
+**Layout animations:**
+
+```tsx
+import { AnimatePresence, motion } from 'framer-motion';
+
+function Tabs({ items, selected }) {
+  return (
+    <div className="flex gap-2">
+      {items.map((item, i) => (
+        <Button key={i} onPress={() => setSelected(i)}>
+          {item}
+          {selected === i && (
+            <motion.div
+              layoutId="active"
+              className="absolute inset-0 bg-accent"
+              transition={{ type: "spring", bounce: 0.2 }}
+            />
+          )}
+        </Button>
+      ))}
+    </div>
+  );
+}
+```
+
+## Render Props
+
+Apply dynamic animations based on component state:
+
+```tsx
+<Button>
+  {({ isPressed, isHovered }) => (
+    <motion.span
+      animate={{
+        scale: isPressed ? 0.95 : isHovered ? 1.05 : 1
+      }}
+    >
+      Interactive Button
+    </motion.span>
+  )}
+</Button>
+```
+
+## Accessibility
+
+**Respecting motion preferences:** HeroUI automatically respects user motion preferences using Tailwind's `motion-reduce:` utility. All built-in transitions and animations are disabled when users enable "reduce motion" in their system settings.
+
+HeroUI extends Tailwind's `motion-reduce:` variant to support both the native `prefers-reduced-motion` media query and the `data-reduce-motion` attribute.
+
+```css
+/* HeroUI pattern - uses Tailwind's motion-reduce: */
+.button {
+  @apply transition-colors motion-reduce:transition-none;
+}
+
+/* Expands to support both approaches: */
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: none;
+  }
+}
+
+[data-reduce-motion="true"] .button {
+  transition: none;
+}
+```
+
+With Framer Motion:
+
+```tsx
+import { useReducedMotion } from 'framer-motion';
+
+function AnimatedCard() {
+  const shouldReduceMotion = useReducedMotion();
+
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: shouldReduceMotion ? 0 : 0.5 }}
+    >
+      <Card>Content</Card>
+    </motion.div>
+  );
+}
+```
+
+**Disabling animations globally:** Add `data-reduce-motion="true"` to the `<html>` or `<body>` tag:
+
+```html
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations will be disabled -->
+</html>
+```
+
+HeroUI automatically detects the user's `prefers-reduced-motion: reduce` setting and disables animations accordingly.
+
+## Performance Tips
+
+**Use GPU-accelerated properties:** Prefer `transform` and `opacity` for smooth animations:
+
+```css
+/* Good - GPU accelerated */
+.slide-in {
+  transform: translateX(-100%);
+  transition: transform 0.3s;
+}
+
+/* Avoid - Triggers layout */
+.slide-in {
+  left: -100%;
+  transition: left 0.3s;
+}
+```
+
+**Will-change optimization:** Use `will-change` to optimize animations, but remove it when not animating:
+
+```css
+.button {
+  will-change: transform;
+}
+
+.button:not(:hover) {
+  will-change: auto;
+}
+```
+
+## Next Steps
+
+- Learn about [Styling](/docs/handbook/styling) approaches
+- Explore [Component](/docs/react/components) examples
+- View [Theming](/docs/handbook/theming) documentation
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/colors.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/colors.mdx
new file mode 100644
index 0000000..69f41b8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/colors.mdx
@@ -0,0 +1,516 @@
+---
+title: Colors
+description: Color palette and theming system for HeroUI v3
+icon: bucket-paint
+links:
+  themes: true
+  tailwind: theme
+---
+
+import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";
+
+HeroUI's color system is built around semantic intent, not visual abundance. Instead of exposing large raw palettes, the system defines a small, meaningful set of color roles that cover the majority of interface needs.
+
+Most colors in the system are derived automatically from a limited number of base values. This allows HeroUI to maintain consistent contrast, hierarchy, and theming behavior while keeping the system easy to reason about and modify.
+
+Colors should communicate purpose and state first. Visual variation comes from scale, emphasis, and context.
+
+<Callout type="info">
+  **Want to create your own theme?** Try the [Theme Builder](/themes) to visually customize colors, radius, fonts, and more — then export the CSS to use in your project.
+</Callout>
+
+## Accent
+
+The accent color represents the primary brand or product identity. It is used to draw attention to key actions, highlights, and moments of emphasis.
+
+Accent should be used intentionally and sparingly. Overuse reduces its impact and can harm visual hierarchy. In most cases, components derive multiple accent-related values (hover, subtle backgrounds, focus states) automatically from the base accent color.
+
+<ColorSectionSideBySide
+  name="Accent"
+  baseVariable="--accent"
+  baseTooltip={"--accent: oklch(0.6204 0.195 253.83)"}
+  hoverVariable="--accent"
+  hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
+  hoverTooltip={"--color-accent-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 90%,\n    var(--accent-foreground) 10%\n  )"}
+  foregroundVariable="--accent-foreground"
+  foregroundTooltip={"--accent-foreground: var(--snow)"}
+  soft={{
+    baseVariable: "--accent",
+    baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
+    baseTooltip: "--color-accent-soft:\n  color-mix(\n    in oklab,\n    var(--accent) 15%,\n    transparent\n  )",
+    hoverVariable: "--accent",
+    hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
+    hoverTooltip: "--color-accent-soft-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 20%,\n    transparent\n  )",
+    foregroundVariable: "--accent",
+    foregroundCssValue: "var(--accent)",
+    foregroundTooltip: "--color-accent-soft-foreground: var(--accent)",
+  }}
+/>
+
+## Default (neutrals)
+
+Default colors form the neutral backbone of the system. They are used for most non-emphasized UI elements.
+
+<ColorSectionSideBySide
+  name="Default"
+  baseVariable="--default"
+  baseTooltip={"--default: oklch(94% 0.001 286.375)"}
+  hoverVariable="--default"
+  hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
+  hoverTooltip={"--color-default-hover:\n  color-mix(\n    in oklab,\n    var(--default) 96%,\n    var(--default-foreground) 4%\n  )"}
+  foregroundVariable="--default-foreground"
+  foregroundTooltip={"--default-foreground: var(--eclipse)"}
+/>
+
+## Success
+
+Success colors communicate positive outcomes, confirmations, and completed states. They are typically used in feedback components, status indicators, and validation states.
+
+<ColorSectionSideBySide
+  name="Success"
+  baseVariable="--success"
+  baseTooltip={"--success: oklch(0.7329 0.1935 150.81)"}
+  hoverVariable="--success"
+  hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
+  hoverTooltip={"--color-success-hover:\n  color-mix(\n    in oklab,\n    var(--success) 90%,\n    var(--success-foreground) 10%\n  )"}
+  foregroundVariable="--success-foreground"
+  foregroundTooltip={"--success-foreground: var(--eclipse)"}
+  soft={{
+    baseVariable: "--success",
+    baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
+    baseTooltip: "--color-success-soft:\n  color-mix(\n    in oklab,\n    var(--success) 15%,\n    transparent\n  )",
+    hoverVariable: "--success",
+    hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
+    hoverTooltip: "--color-success-soft-hover:\n  color-mix(\n    in oklab,\n    var(--success) 20%,\n    transparent\n  )",
+    foregroundVariable: "--success",
+    foregroundCssValue: "var(--success)",
+    foregroundTooltip: "--color-success-soft-foreground: var(--success)",
+  }}
+/>
+
+## Warning
+
+Warning colors indicate caution, risk, or actions that require attention but are not destructive. They are commonly used for alerts, messages, and transitional states where the user should pause or review information.
+
+<ColorSectionSideBySide
+  name="Warning"
+  baseVariable="--warning"
+  baseTooltip={"--warning: oklch(0.7819 0.1585 72.33)"}
+  hoverVariable="--warning"
+  hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
+  hoverTooltip={"--color-warning-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 90%,\n    var(--warning-foreground) 10%\n  )"}
+  foregroundVariable="--warning-foreground"
+  foregroundTooltip={"--warning-foreground: var(--eclipse)"}
+  soft={{
+    baseVariable: "--warning",
+    baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
+    baseTooltip: "--color-warning-soft:\n  color-mix(\n    in oklab,\n    var(--warning) 15%,\n    transparent\n  )",
+    hoverVariable: "--warning",
+    hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
+    hoverTooltip: "--color-warning-soft-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 20%,\n    transparent\n  )",
+    foregroundVariable: "--warning",
+    foregroundCssValue: "var(--warning)",
+    foregroundTooltip: "--color-warning-soft-foreground: var(--warning)",
+  }}
+/>
+
+## Danger
+
+Danger colors represent destructive, irreversible, or critical actions and states. They should be immediately recognizable and used consistently for errors, destructive buttons, and critical alerts.
+
+<ColorSectionSideBySide
+  name="Danger"
+  baseVariable="--danger"
+  baseTooltip={"--danger: oklch(0.6532 0.2328 25.74)"}
+  hoverVariable="--danger"
+  hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
+  hoverTooltip={"--color-danger-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 90%,\n    var(--danger-foreground) 10%\n  )"}
+  foregroundVariable="--danger-foreground"
+  foregroundTooltip={"--danger-foreground: var(--snow)"}
+  soft={{
+    baseVariable: "--danger",
+    baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
+    baseTooltip: "--color-danger-soft:\n  color-mix(\n    in oklab,\n    var(--danger) 15%,\n    transparent\n  )",
+    hoverVariable: "--danger",
+    hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
+    hoverTooltip: "--color-danger-soft-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 20%,\n    transparent\n  )",
+    foregroundVariable: "--danger",
+    foregroundCssValue: "var(--danger)",
+    foregroundTooltip: "--color-danger-soft-foreground: var(--danger)",
+  }}
+/>
+
+## Foreground
+
+Foreground colors are used for primary content such as text and icons. These colors are optimized for readability and accessibility and adapt automatically to background and surface contexts. Foreground colors should never be hard-coded at the component level.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Foreground", variable: "--foreground", tooltip: "--foreground: var(--eclipse)" },
+    { label: "Muted", variable: "--muted", tooltip: "--muted: oklch(0.5517 0.0138 285.94)" },
+    { label: "Segment", variable: "--segment", tooltip: "--segment: var(--white)" },
+    { label: "Overlay", variable: "--overlay", tooltip: "--overlay: var(--white)" },
+    { label: "Link", variable: "--link", tooltip: "--link: var(--foreground)" },
+  ]}
+  darkColors={[
+    { label: "Foreground", variable: "--foreground", border: true, tooltip: "--foreground: var(--snow)" },
+    { label: "Muted", variable: "--muted", border: true, tooltip: "--muted: oklch(70.5% 0.015 286.067)" },
+    { label: "Segment", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
+    { label: "Overlay", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
+    { label: "Link", variable: "--link", border: true, tooltip: "--link: var(--foreground)" },
+  ]}
+/>
+
+## Background
+
+Background colors define the base canvas of the interface. They establish overall contrast and mood while staying visually quiet.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Background", variable: "--background", border: true, tooltip: "--background: oklch(0.9702 0 0)" },
+    { label: "Secondary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
+    { label: "Tertiary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
+    { label: "Inverse", variable: "--foreground", tooltip: "--color-background-inverse: var(--foreground)" },
+  ]}
+  darkColors={[
+    { label: "Background", variable: "--background", border: true, tooltip: "--background: oklch(12% 0.005 285.823)" },
+    { label: "Secondary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
+    { label: "Tertiary", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
+    { label: "Inverse", variable: "--foreground", border: true, tooltip: "--color-background-inverse: var(--foreground)" },
+  ]}
+/>
+
+## Surface
+
+Surface colors sit on top of backgrounds and are used for containers such as cards, panels, modals, and dropdown. Surfaces help create visual separation and hierarchy through elevation, contrast, and layering rather than strong color shifts.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Surface", variable: "--surface", border: true, tooltip: "--surface: var(--white)" },
+    { label: "Secondary", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.9524 0.0013 286.37)" },
+    { label: "Tertiary", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.9373 0.0013 286.37)" },
+  ]}
+  darkColors={[
+    { label: "Surface", variable: "--surface", border: true, tooltip: "--surface: oklch(0.2103 0.0059 285.89)" },
+    { label: "Secondary", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.257 0.0037 286.14)" },
+    { label: "Tertiary", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.2721 0.0024 247.91)" },
+  ]}
+/>
+
+## Form field
+
+Form field colors are specialized tokens used for inputs, controls, and interactive fields. They account for multiple states such as default, focus, and hover. Isolating them ensures form elements have a distinct visual language from buttons and the rest of the UI.
+
+<ColorSectionFormField
+  colors={{
+    bg: "--field-background",
+    bgTooltip: "--field-background: var(--white)",
+    bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
+    bgHoverTooltip: "--color-field-hover:\n  color-mix(\n    in oklab,\n    var(--field-background, var(--default)) 90%,\n    var(--field-foreground, var(--foreground)) 2%\n  )",
+    bgFocusTooltip: "--color-field-focus:\n  var(--field-background, var(--default))",
+    placeholder: "--field-placeholder",
+    placeholderTooltip: "--field-placeholder: var(--muted)",
+    foreground: "--field-foreground",
+    foregroundTooltip: "--field-foreground: oklch(0.2103 0.0059 285.89)",
+  }}
+/>
+
+## Separator
+
+Separator colors are used for dividers, outlines, and subtle boundaries. They exist to structure content and guide the eye without adding noise. Separator colors should remain low contrast and unobtrusive.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Separator", variable: "--separator", border: true, tooltip: "--separator: oklch(92% 0.004 286.32)" },
+    { label: "Secondary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
+    { label: "Tertiary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
+  ]}
+  darkColors={[
+    { label: "Separator", variable: "--separator", border: true, tooltip: "--separator: oklch(25% 0.006 286.033)" },
+    { label: "Secondary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
+    { label: "Tertiary", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
+  ]}
+/>
+
+## Other
+
+Other colors serve specific utility roles across the interface. They exist to structure content and guide the eye without adding noise.
+
+<ColorSectionStacked
+  lightColors={[
+    { label: "Border", variable: "--border", tooltip: "--border: oklch(90% 0.004 286.32)" },
+    { label: "Backdrop", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.5)" },
+    { label: "Overlay", variable: "--overlay", border: true, tooltip: "--overlay: var(--white)" },
+    { label: "Segment", variable: "--segment", border: true, tooltip: "--segment: var(--white)" },
+  ]}
+  darkColors={[
+    { label: "Border", variable: "--border", tooltip: "--border: oklch(28% 0.006 286.033)" },
+    { label: "Backdrop", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.6)" },
+    { label: "Overlay", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
+    { label: "Segment", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
+  ]}
+/>
+
+## Primitive
+
+Primitive colors are mode agnostic values used as foundations for semantic color tokens. They do not change between light and dark themes.
+
+<ColorSectionPrimitive
+  colors={[
+    { label: "White", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
+    { label: "Black", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
+    { label: "Snow", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
+    { label: "Eclipse", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
+  ]}
+/>
+
+## How to Use Colors
+
+**In your components:**
+```jsx
+<div className="bg-background text-foreground">
+  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
+    Click me
+  </button>
+</div>
+```
+
+**In CSS files:**
+
+```css title="global.css"
+/* Direct CSS variables */
+.my-component {
+  background: var(--accent);
+  color: var(--accent-foreground);
+  border: 1px solid var(--border);
+}
+
+/* With @apply and @layer */
+@layer components {
+  .button {
+    @apply bg-accent text-accent-foreground;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-accent-hover;
+    }
+
+    &:active,
+    &[data-pressed="true"] {
+      @apply bg-accent-hover;
+      transform: scale(0.97);
+    }
+  }
+}
+```
+
+## Default Theme
+
+The complete theme definition can be found in ([variables.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css)). This theme automatically switches between light and dark modes based on the `class="dark"` or `data-theme="dark"` attributes.
+
+<CollapsibleCode lang="css" code={`  @layer base {
+    /* HeroUI Default Theme */
+    :root {
+      color-scheme: light;
+
+      /* == Common Variables == */
+
+      /* Primitive Colors (Do not change between light and dark) */
+      --white: oklch(100% 0 0);
+      --black: oklch(0% 0 0);
+      --snow: oklch(0.9911 0 0);
+      --eclipse: oklch(0.2103 0.0059 285.89);
+
+      /* Spacing scale */
+      --spacing: 0.25rem;
+
+      /* Border */
+      --border-width: 1px;
+      --field-border-width: 0px;
+      --disabled-opacity: 0.5;
+
+      /* Ring offset - Used for focus ring */
+      --ring-offset-width: 2px;
+
+      /* Cursor */
+      --cursor-interactive: pointer;
+      --cursor-disabled: not-allowed;
+
+      /* Radius */
+      --radius: 0.5rem;
+      --field-radius: calc(var(--radius) * 1.5);
+
+      /* == Light Theme Variables == */
+
+      /* Base Colors */
+      --background: oklch(0.9702 0 0);
+      --foreground: var(--eclipse);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: var(--white);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
+      --overlay: var(--white);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(0.5517 0.0138 285.94);
+      --scrollbar: oklch(87.1% 0.006 286.286);
+
+      --default: oklch(94% 0.001 286.375);
+      --default-foreground: var(--eclipse);
+
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: var(--snow);
+
+      /* Form Field Defaults - Colors */
+      --field-background: var(--white);
+      --field-foreground: oklch(0.2103 0.0059 285.89);
+      --field-placeholder: var(--muted);
+      --field-border: transparent; /* no border by default on form fields */
+
+      /* Status Colors */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.7819 0.1585 72.33);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.6532 0.2328 25.74);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: var(--white);
+      --segment-foreground: var(--eclipse);
+
+      /* Misc Colors */
+      --border: oklch(92% 0.004 286.32);
+      --separator: oklch(92% 0.004 286.32);
+      --focus: var(--accent);
+      --link: var(--foreground);
+
+      /* Backdrop */
+      --backdrop: rgba(0, 0, 0, 0.5);
+
+      /* Shadows */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      /* Overlay shadow */
+      --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      /* Skeleton Default Global Animation */
+      --skeleton-animation: shimmer; /* shimmer, pulse, none */
+
+      /* Tooltip Default Delays */
+      --tooltip-delay: 1500ms;
+      --tooltip-close-delay: 500ms;
+    }
+
+    .dark,
+    [data-theme="dark"] {
+      color-scheme: dark;
+      /* == Dark Theme Variables == */
+
+      /* Base Colors */
+      --background: oklch(12% 0.005 285.823);
+      --foreground: var(--snow);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.2103 0.0059 285.89);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) - lighter for contrast */
+      --overlay: oklch(0.22 0.0059 285.89); /* A bit lighter than surface for visibility in dark mode */
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(70.5% 0.015 286.067);
+      --scrollbar: oklch(70.5% 0.015 286.067);
+
+      --default: oklch(27.4% 0.006 286.033);
+      --default-foreground: var(--snow);
+
+      /* Form Field Defaults - Colors (only the ones that are different from light theme) */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+
+      /* Status Colors */
+      --warning: oklch(0.8203 0.1388 76.34);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.594 0.1967 24.63);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: oklch(0.3964 0.01 285.93);
+      --segment-foreground: var(--foreground);
+
+      /* Misc Colors */
+      --border: oklch(22% 0.006 286.033);
+      --separator: oklch(22% 0.006 286.033);
+      --focus: var(--accent);
+      --link: var(--foreground);
+
+      /* Backdrop */
+      --backdrop: rgba(0, 0, 0, 0.6);
+
+      /* Shadows */
+      --surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+      --overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+      --field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+    }
+  }
+`}
+/>
+
+## Customizing Colors
+
+**Override existing colors:**
+
+```css
+:root {
+  /* Override default colors */
+  --accent: oklch(0.7 0.15 250);
+  --success: oklch(0.65 0.15 155);
+}
+
+[data-theme="dark"] {
+  /* Override dark theme colors */
+  --accent: oklch(0.8 0.12 250);
+  --success: oklch(0.75 0.12 155);
+}
+```
+
+**Tip:** Convert colors at [oklch.com](https://oklch.com)
+
+**Add your own colors:**
+
+```css
+:root,
+[data-theme="light"] {
+  --info: oklch(0.6 0.15 210);
+  --info-foreground: oklch(0.98 0 0);
+}
+
+.dark,
+[data-theme="dark"] {
+  --info: oklch(0.7 0.12 210);
+  --info-foreground: oklch(0.15 0 0);
+}
+
+/* Make the color available to Tailwind */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+Now you can use it:
+
+```tsx
+<div className="bg-info text-info-foreground">Info message</div>
+```
+
+> **Note**: To learn more about theme variables and how they work in Tailwind CSS v4, see the [Tailwind CSS Theme documentation](https://tailwindcss.com/docs/theme).
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/composition.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/composition.mdx
new file mode 100644
index 0000000..16fd584
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/composition.mdx
@@ -0,0 +1,476 @@
+---
+title: Composition
+description: Build flexible UI with component composition patterns
+icon: layers
+---
+
+HeroUI uses composition patterns to create flexible, customizable components. Change the rendered element, compose components together, and maintain full control over markup.
+
+## Framework-Agnostic Styles
+
+HeroUI's variant functions are available in the `@heroui/styles` package, which can be used independently of React. This enables Vue, Svelte, and other frameworks to use HeroUI's design system:
+
+```tsx
+// Import directly from @heroui/styles (framework-agnostic)
+import { buttonVariants } from '@heroui/styles';
+
+// Or import from @heroui/react (re-exports the same functions)
+import { buttonVariants } from '@heroui/react';
+```
+
+Both imports work identically. Use `@heroui/styles` when building for non-React frameworks or when you want to avoid pulling in React dependencies.
+
+## Polymorphic Styling
+
+Apply HeroUI styles to any element using variant functions or BEM classes. Extend component styles to framework components, native HTML elements, or custom components with full type safety.
+
+**Example: Styling a Link as a Button**
+
+You can use `buttonVariants` to style a Link component with button styles:
+
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+// Style a Next.js Link as a primary button
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  href="/about"
+>
+  About
+</Link>
+
+// Style a native anchor as a secondary button with custom size
+<a
+  className={buttonVariants({ variant: "secondary", size: "lg" })}
+  href="https://example.com"
+>
+  External Link
+</a>
+```
+
+**Using BEM classes directly:**
+
+```tsx
+import Link from 'next/link';
+
+// Apply button styles directly using BEM classes
+<Link className="button button--primary" href="/about">
+  About
+</Link>
+```
+
+**Working with Compound Components**
+
+When using a custom root element instead of HeroUI's Root component, child components cannot access context slots. You can manually pass `className` to child components using variant functions or BEM classes:
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+// With custom root - pass className manually
+const slots = linkVariants();
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+
+<NextLink className="link" href="/about">
+  About Page
+  <Link.Icon className="link__icon" />
+</NextLink>
+```
+
+This approach works because HeroUI's variant functions and BEM classes can be applied to any element, giving you complete flexibility to style framework components, native elements, or custom components with HeroUI's design system.
+
+## Direct Class Application
+
+The simplest way to style links or other elements is to apply HeroUI's [BEM](https://getbem.com/) classes directly. This approach is straightforward and works with any framework or vanilla HTML.
+
+**With Next.js Link:**
+```tsx
+import Link from 'next/link';
+
+<Link className="button button--tertiary" href="/">
+  Return Home
+</Link>
+```
+
+**With native anchor:**
+```tsx
+<a className="button button--primary" href="/dashboard">
+  Go to Dashboard
+</a>
+```
+
+**Available button classes:**
+- `.button` — Base button styles
+- `.button--primary`, `.button--secondary`, `.button--tertiary`, `.button--danger`, `.button--ghost` — Variants
+- `.button--sm`, `.button--md`, `.button--lg` — Sizes
+- `.button--icon-only` — Icon-only button
+
+This approach works because HeroUI uses [BEM](https://getbem.com/) classes that can be applied to any element. It's perfect when you don't need the component's interactive features (like `onPress` handlers) and just want the visual styling.
+
+## Using Variant Functions
+
+For more control and type safety, use variant functions to apply HeroUI styles to framework-specific components or custom elements. Variant functions are available from both `@heroui/styles` (framework-agnostic) and `@heroui/react` (re-exports).
+
+**With Next.js Link:**
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+const slots = linkVariants();
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+```
+
+**With Button styles:**
+
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+<Link
+  className={buttonVariants({ variant: "primary", size: "md" })}
+  href="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+**Available variant functions:** Each component exports its variant function (`buttonVariants`, `chipVariants`, `linkVariants`, `spinnerVariants`, and more) from `@heroui/styles`. Use them to apply HeroUI's design system to any element while maintaining type safety.
+
+## Compound Components
+
+HeroUI components are built as compound components—they export multiple parts that work together. Use them in three flexible ways:
+
+**Option 1: Compound pattern (recommended)** — Use the main component directly without `.Root` suffix:
+
+```tsx
+import { Alert } from '@heroui/react';
+
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+  <Alert.Close />
+</Alert>
+```
+
+**Option 2: Compound pattern with .Root** — Use the `.Root` suffix if you prefer explicit naming:
+
+```tsx
+import { Alert } from '@heroui/react';
+
+<Alert.Root>
+  <Alert.Icon />
+  <Alert.Content>
+    <Alert.Title>Success</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+  <Alert.Close />
+</Alert.Root>
+```
+
+**Option 3: Named exports** — Import each part separately:
+
+```tsx
+import {
+  AlertRoot,
+  AlertIcon,
+  AlertContent,
+  AlertTitle,
+  AlertDescription,
+  AlertClose
+} from '@heroui/react';
+
+<AlertRoot>
+  <AlertIcon />
+  <AlertContent>
+    <AlertTitle>Success</AlertTitle>
+    <AlertDescription>Your changes have been saved.</AlertDescription>
+  </AlertContent>
+  <AlertClose />
+</AlertRoot>
+```
+
+**Mixed syntax:** Mix compound and named exports in the same component:
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from '@heroui/react';
+
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>
+    <AlertTitle>Success</AlertTitle>
+    <AlertDescription>Your changes have been saved.</AlertDescription>
+  </Alert.Content>
+  <Alert.Close />
+</Alert>
+```
+
+**Simple components:** Simple components like `Button` work the same way—no `.Root` needed:
+
+```tsx
+import { Button } from '@heroui/react';
+
+// Recommended - no .Root needed
+<Button>Click me</Button>
+
+// Or with .Root
+<Button.Root>Click me</Button.Root>
+
+// Or named export
+import { ButtonRoot } from '@heroui/react';
+<ButtonRoot>Click me</ButtonRoot>
+```
+
+**Benefits:** All three patterns provide flexibility, customization, control, and consistency. Choose the pattern that fits your codebase.
+
+## Mixing Variant Functions
+
+You can combine variant functions from different components to create unique styles:
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants, buttonVariants } from '@heroui/styles';
+
+// Link styled with button variants
+const buttonStyles = buttonVariants({ variant: "tertiary", size: "md" });
+
+<Link
+  className={buttonStyles}
+  href="https://heroui.com"
+>
+  HeroUI
+</Link>
+```
+
+## Custom Components
+
+Create your own components by composing HeroUI primitives:
+
+```tsx
+import { Button, Tooltip } from '@heroui/react';
+import { buttonVariants } from '@heroui/styles';
+
+// Link button component using variant functions
+function LinkButton({ href, children, variant = "primary", ...props }) {
+  return (
+    <a
+      href={href}
+      className={buttonVariants({ variant, ...props })}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+}
+
+// Icon button with tooltip
+function IconButton({ icon, label, ...props }) {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button isIconOnly {...props}>
+          <Icon icon={icon} />
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>{label}</Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Custom Variants
+
+Create custom variants by extending the component's variant function:
+
+```tsx
+import type { ButtonRootProps } from "@heroui/react";
+import type { VariantProps } from "tailwind-variants";
+
+import { Button } from "@heroui/react";
+import { buttonVariants, tv } from "@heroui/styles";
+
+const myButtonVariants = tv({
+  extend: buttonVariants,
+  base: "text-md text-shadow-lg font-semibold shadow-md data-[pending=true]:opacity-40",
+  variants: {
+    radius: {
+      lg: "rounded-lg",
+      md: "rounded-md",
+      sm: "rounded-sm",
+      full: "rounded-full",
+    },
+    size: {
+      sm: "h-10 px-4",
+      md: "h-11 px-6",
+      lg: "h-12 px-8",
+      xl: "h-13 px-10",
+    },
+    variant: {
+      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
+    },
+  },
+  defaultVariants: {
+    radius: "full",
+    variant: "primary",
+  },
+});
+
+type MyButtonVariants = VariantProps<typeof myButtonVariants>;
+export type MyButtonProps = Omit<ButtonRootProps, "className"> &
+  MyButtonVariants & { className?: string };
+
+function CustomButton({ className, radius, variant, ...props }: MyButtonProps) {
+  return <Button className={myButtonVariants({ className, radius, variant })} {...props} />;
+}
+
+export function CustomVariants() {
+  return <CustomButton>Custom Button</CustomButton>;
+}
+```
+
+**Type references:** When working with component types, use named type imports or object-style syntax.
+
+**Recommended — Named type imports:**
+```tsx
+import type { ButtonRootProps, AvatarRootProps } from "@heroui/react";
+
+type MyButtonProps = ButtonRootProps;
+type MyAvatarProps = AvatarRootProps;
+```
+
+**Alternative — Object-style syntax:**
+```tsx
+import { Button, Avatar } from "@heroui/react";
+
+type MyButtonProps = Button["RootProps"];
+type MyAvatarProps = Avatar["RootProps"];
+```
+
+**Note:** The namespace syntax `Button.RootProps` is no longer supported. Use `Button["RootProps"]` or named imports instead.
+
+## Custom DOM Element
+
+Use the `render` prop on the following components to render a custom component in place of the default DOM element.
+
+For example, you can render a [Motion](https://motion.dev/) button and use the state to drive an animation.
+
+```tsx
+import {Button} from '@heroui/react';
+import {motion} from 'motion/react';
+
+<Button
+  render={(domProps, {isPressed}) => (
+    <motion.button
+      {...domProps}
+      animate={{scale: isPressed ? 0.9 : 1}} />
+  )}>
+  Press me
+</Button>
+```
+
+The `render` prop is also useful for rendering link components from client-side routers, or reusing existing presentational components.
+
+```tsx
+import {Link} from '@heroui/react';
+import NextLink from 'next/link';
+
+<Link
+  render={({ref, ...domProps}) => (
+    <NextLink {...domProps} ref={ref as React.Ref<HTMLAnchorElement>} href="/privacy-policy" />
+  )}
+>
+  Privacy Policy
+</Link>
+```
+
+Follow these rules to avoid breaking the behavior and accessibility of the component:
+- Always render the expected element type (e.g. if `<button>` is expected, do not render an `<a>`). You will see a warning in development if a mismatch is detected.
+- Only render a single root DOM element (no fragments).
+- Always pass the provided props the underlying DOM element, merging with your own props via `mergeProps` as needed.
+
+
+## Framework Integration
+
+**With Next.js:**
+
+Use variant functions for type-safe styling:
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import Link from 'next/link';
+
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  href="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+Or apply BEM classes directly (simplest):
+```tsx
+import Link from 'next/link';
+
+<Link className="button button--primary" href="/dashboard">
+  Dashboard
+</Link>
+```
+
+**With React Router:**
+
+Use variant functions:
+```tsx
+import { buttonVariants } from '@heroui/styles';
+import { Link } from 'react-router-dom';
+
+<Link
+  className={buttonVariants({ variant: "primary" })}
+  to="/dashboard"
+>
+  Dashboard
+</Link>
+```
+
+Or apply BEM classes directly (simplest):
+```tsx
+import { Link } from 'react-router-dom';
+
+<Link className="button button--primary" to="/dashboard">
+  Dashboard
+</Link>
+```
+
+**With Vue, Svelte, or Other Frameworks:**
+
+Since `@heroui/styles` has no React dependencies, you can use it directly in any framework:
+```vue
+<script setup>
+import { buttonVariants } from '@heroui/styles';
+
+const primaryButton = buttonVariants({ variant: "primary" });
+</script>
+
+<template>
+  <button :class="primaryButton">Click me</button>
+</template>
+```
+
+
+## Next Steps
+
+- Learn about [Styling](/docs/handbook/styling) components
+- Explore [Animation](/docs/handbook/animation) options
+- Browse [Components](/docs/react/components) for more examples
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/dark-mode.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/dark-mode.mdx
new file mode 100644
index 0000000..f418be6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/dark-mode.mdx
@@ -0,0 +1,244 @@
+---
+title: Dark Mode
+description: Add light, dark, and system theme switching to HeroUI v3
+icon: moon
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI dark mode is CSS-driven. Components read theme variables from the root element, so you do not need a HeroUI provider. Add the `dark` class or `data-theme="dark"` to `<html>` and HeroUI will apply the dark theme.
+
+```html
+<html class="dark" data-theme="dark">
+  <body class="bg-background text-foreground">
+    <!-- Your app -->
+  </body>
+</html>
+```
+
+Keep the `bg-background` and `text-foreground` classes on your app shell so the page canvas changes with the active theme.
+
+<Callout type="info">
+  HeroUI's built-in light and dark themes respond to both `.light` / `.dark` classes and `data-theme="light"` / `data-theme="dark"` attributes. If you set both manually, keep the values in sync.
+</Callout>
+
+## Next.js with next-themes
+
+Use [next-themes](https://github.com/pacocoursey/next-themes) when you need theme persistence, system preference support, and no flash before hydration in a Next.js app.
+
+### Install next-themes
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i next-themes
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add next-themes
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add next-themes
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add next-themes
+    ```
+  </Tab>
+</Tabs>
+
+### App Router
+
+Create a client provider for `next-themes`.
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import {ThemeProvider as NextThemesProvider} from "next-themes";
+
+export function Providers({children}: {children: React.ReactNode}) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}
+```
+
+Wrap your app with the provider from the root layout. Add `suppressHydrationWarning` to `<html>` because `next-themes` updates that element before hydration.
+
+```tsx
+// app/layout.tsx
+import "./globals.css";
+
+import {Providers} from "./providers";
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="bg-background text-foreground">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+### Theme switcher
+
+Use `useTheme` from `next-themes` inside a client component. Delay rendering until mount because the active theme is not known during SSR.
+
+```tsx
+// app/components/theme-switcher.tsx
+"use client";
+
+import {Button} from "@heroui/react";
+import {useTheme} from "next-themes";
+import {useEffect, useState} from "react";
+
+export function ThemeSwitcher() {
+  const [mounted, setMounted] = useState(false);
+  const {resolvedTheme, setTheme, theme} = useTheme();
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) return null;
+
+  const activeTheme = theme === "system" ? resolvedTheme : theme;
+
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        variant={activeTheme === "light" ? "primary" : "secondary"}
+        onPress={() => setTheme("light")}
+      >
+        Light
+      </Button>
+      <Button
+        variant={activeTheme === "dark" ? "primary" : "secondary"}
+        onPress={() => setTheme("dark")}
+      >
+        Dark
+      </Button>
+      <Button variant={theme === "system" ? "primary" : "secondary"} onPress={() => setTheme("system")}>
+        System
+      </Button>
+    </div>
+  );
+}
+```
+
+### Pages Router
+
+For `pages/`, wrap your application in `pages/_app.tsx`.
+
+```tsx
+// pages/_app.tsx
+import "@/styles/globals.css";
+
+import type {AppProps} from "next/app";
+import {ThemeProvider as NextThemesProvider} from "next-themes";
+
+export default function App({Component, pageProps}: AppProps) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      <Component {...pageProps} />
+    </NextThemesProvider>
+  );
+}
+```
+
+## Using custom theme names
+
+The `attribute="class"` setup works well for the built-in `light` and `dark` themes. If your custom theme CSS is written with `data-theme` selectors, configure `next-themes` to write `data-theme` instead.
+
+```tsx
+<NextThemesProvider
+  attribute="data-theme"
+  defaultTheme="system"
+  enableSystem
+  themes={["light", "dark", "ocean", "ocean-dark"]}
+>
+  {children}
+</NextThemesProvider>
+```
+
+When you pass a custom `themes` list, include `"light"` and `"dark"` if you still want the built-in themes available.
+
+## React with useTheme
+
+Use HeroUI's `useTheme` hook when you are building a plain React app, such as Vite or Create React App, and do not need `next-themes`.
+
+The hook is exported from `@heroui/react`. It stores the selected theme in `localStorage`, resolves `"system"` from the user's OS preference, and applies both the class and `data-theme` attribute to `<html>`.
+
+```tsx
+// src/components/theme-switcher.tsx
+import {Button, useTheme} from "@heroui/react";
+
+export function ThemeSwitcher() {
+  const {resolvedTheme, setTheme, theme} = useTheme("system");
+
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        variant={resolvedTheme === "light" ? "primary" : "secondary"}
+        onPress={() => setTheme("light")}
+      >
+        Light
+      </Button>
+      <Button
+        variant={resolvedTheme === "dark" ? "primary" : "secondary"}
+        onPress={() => setTheme("dark")}
+      >
+        Dark
+      </Button>
+      <Button variant={theme === "system" ? "primary" : "secondary"} onPress={() => setTheme("system")}>
+        System
+      </Button>
+    </div>
+  );
+}
+```
+
+<Callout type="warning">
+  Use one theme controller per app. In Next.js, prefer `next-themes` and its `useTheme` hook. In plain React apps, use `useTheme` from `@heroui/react`.
+</Callout>
+
+## Styling for both themes
+
+Theme-aware utilities work automatically because they read CSS variables:
+
+```tsx
+<main className="min-h-screen bg-background text-foreground">
+  <section className="bg-surface text-surface-foreground shadow-surface">
+    Theme-aware content
+  </section>
+</main>
+```
+
+Use the `dark:` variant for one-off changes that only apply in dark mode:
+
+```tsx
+<div className="bg-background text-foreground dark:border-default">
+  Custom dark-mode adjustment
+</div>
+```
+
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/styling.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/styling.mdx
new file mode 100644
index 0000000..38a751a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/styling.mdx
@@ -0,0 +1,304 @@
+---
+title: Styling
+description: Style HeroUI components with CSS, Tailwind, or CSS-in-JS
+icon: brush
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI components provide flexible styling options: Tailwind CSS utilities, CSS with [BEM](https://getbem.com/) classes or data attributes, CSS-in-JS libraries, and render props for dynamic styling.
+
+## Basic Styling
+
+**Using className:** All HeroUI components accept `className` props:
+
+```tsx
+<Button className="bg-purple-500 hover:bg-purple-600">
+  Custom Button
+</Button>
+
+<Accordion className="border-2 border-gray-200 rounded-xl">
+  {/* content */}
+</Accordion>
+```
+
+**Using style:** Components also accept inline styles:
+
+```tsx
+<Button style={{ backgroundColor: '#8B5CF6' }}>
+  Styled Button
+</Button>
+```
+
+## Scrollbars
+
+HeroUI scroll slots use `@apply scrollbar` in component CSS. For your own overflow containers, use the utilities from `@heroui/styles`:
+
+```tsx
+<div className="scrollbar h-64 overflow-y-auto">
+  {/* long content */}
+</div>
+```
+
+| Utility | Effect |
+|---------|--------|
+| `scrollbar` | HeroUI thumb (reads theme `--scrollbar-*` variables) |
+| `scrollbar-thin` | HeroUI themed thin scrollbar |
+| `scrollbar-default` | OS / browser scrollbars |
+| `scrollbar-none` | Hidden scrollbar |
+
+Global and per-subtree control uses `data-scrollbar` on an ancestor. See [Theming](/docs/handbook/theming#scrollbars) for tokens and modes.
+
+## State-Based Styling
+
+HeroUI components expose their state through data attributes, similar to CSS pseudo-classes:
+
+```css
+/* Target different states */
+.button[data-hovered="true"], .button:hover {
+  background: var(--accent-hover);
+}
+
+.button[data-pressed="true"], .button:active {
+  transform: scale(0.97);
+}
+
+.button[data-focus-visible="true"], .button:focus-visible {
+  outline: 2px solid var(--focus);
+}
+```
+
+## Render Props
+
+Apply dynamic styling based on component state:
+
+```tsx
+// Dynamic classes
+<Button
+  className={({ isPressed }) =>
+    isPressed ? 'bg-blue-600' : 'bg-blue-500'
+  }
+>
+  Press me
+</Button>
+
+// Dynamic content
+<Button>
+  {({ isHovered, isPressed }) => (
+    <>
+      <Icon
+        icon="gravity-ui:heart"
+        className={isPressed ? 'text-red-500' : 'text-neutral-400'}
+      />
+      <span className={isHovered ? 'underline' : ''}>
+        Like
+      </span>
+    </>
+  )}
+</Button>
+```
+
+## BEM Classes
+
+HeroUI uses [BEM methodology](https://getbem.com/) for consistent class naming:
+
+```css
+/* Block */
+.button { }
+.accordion { }
+
+/* Element */
+.accordion__trigger { }
+.accordion__panel { }
+
+/* Modifier */
+.button--primary { }
+.button--lg { }
+.accordion--outline { }
+```
+
+**Customizing components globally:**
+
+```css
+/* global.css */
+
+@layer components {
+  /* Override button styles */
+  .button {
+    @apply font-semibold uppercase;
+  }
+
+  .button--primary {
+    @apply bg-indigo-600 hover:bg-indigo-700;
+  }
+
+  /* Add custom variant */
+  .button--gradient {
+    @apply bg-gradient-to-r from-purple-500 to-pink-500;
+  }
+}
+```
+
+## Creating Wrapper Components
+
+Create reusable custom components using [tailwind-variants](https://tailwind-variants.org/)—a Tailwind CSS first-class variant API:
+
+```tsx
+import { Button as HeroButton, type ButtonProps } from '@heroui/react';
+import { buttonVariants, tv, type VariantProps } from '@heroui/styles';
+
+const customButtonVariants = tv({
+  extend: buttonVariants,
+  base: 'font-medium transition-all',
+  variants: {
+    intent: {
+      primary: 'bg-blue-500 hover:bg-blue-600 text-white',
+      secondary: 'bg-gray-200 hover:bg-gray-300',
+      danger: 'bg-red-500 hover:bg-red-600 text-white',
+    },
+    size: {
+      small: 'text-sm px-2 py-1',
+      medium: 'text-base px-4 py-2',
+      large: 'text-lg px-6 py-3',
+    },
+  },
+  defaultVariants: {
+    intent: 'primary',
+    size: 'medium',
+  },
+});
+
+type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
+interface CustomButtonProps
+  extends Omit<ButtonProps, 'className'>,
+  CustomButtonVariants {
+  className?: string;
+}
+
+export function CustomButton({ intent, size, className, ...props }: CustomButtonProps) {
+  return (
+    <HeroButton
+      className={customButtonVariants({ intent, size, className })}
+      {...props}
+    />
+  );
+}
+```
+
+## CSS-in-JS Integration
+
+**Styled Components:**
+
+```tsx
+import styled from 'styled-components';
+import { Button } from '@heroui/react';
+
+const StyledButton = styled(Button)`
+  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
+  border-radius: 8px;
+  color: white;
+  padding: 12px 24px;
+
+  &:hover {
+    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
+  }
+`;
+```
+
+**Emotion:**
+
+```tsx
+import { css } from '@emotion/css';
+import { Button } from '@heroui/react';
+
+const buttonStyles = css`
+  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
+  border-radius: 8px;
+  color: white;
+  padding: 12px 24px;
+
+  &:hover {
+    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
+  }
+`;
+
+<Button className={buttonStyles}>
+  Emotion Button
+</Button>
+```
+
+## Responsive Design
+
+**Using Tailwind utilities:**
+
+```tsx
+<Button className="text-sm md:text-base lg:text-lg px-3 md:px-4 lg:px-6">
+  Responsive Button
+</Button>
+```
+
+**Or with CSS:**
+
+```css
+.button {
+  font-size: 0.875rem;
+  padding: 0.5rem 1rem;
+}
+
+@media (min-width: 768px) {
+  .button {
+    font-size: 1rem;
+    padding: 0.75rem 1.5rem;
+  }
+}
+```
+
+## CSS Modules
+
+For scoped styles, use CSS Modules:
+
+```css
+/* Button.module.css */
+.button {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+}
+
+.button:hover {
+  transform: translateY(-2px);
+}
+
+.button--primary {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+}
+```
+
+```tsx
+import styles from './Button.module.css';
+import { Button } from '@heroui/react';
+
+<Button className={styles.button}>
+  Scoped Button
+</Button>
+```
+
+## Component Classes Reference
+
+**Button:** `.button`, `.button--{variant}`, `.button--{size}`, `.button--icon-only`
+**Accordion:** `.accordion`, `.accordion__item`, `.accordion__trigger`, `.accordion__panel`, `.accordion--outline`
+
+> **Note:** See component docs for complete class references: [Button](/docs/components/button#css-classes), [Accordion](/docs/components/accordion#css-classes)
+
+View all component classes in [@heroui/styles/components](https://github.com/heroui-inc/heroui/tree/main/packages/styles/components).
+
+## Next Steps
+
+- Learn about [Animation](/docs/handbook/animation) techniques
+- Explore [Theming](/docs/handbook/theming) system
+- Browse [Component](/docs/react/components) examples
diff --git a/apps/docs/content/docs/en/react/getting-started/(handbook)/theming.mdx b/apps/docs/content/docs/en/react/getting-started/(handbook)/theming.mdx
new file mode 100644
index 0000000..5e20093
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(handbook)/theming.mdx
@@ -0,0 +1,689 @@
+---
+title: Theming
+description: Customize HeroUI's design system with CSS variables and global styles
+icon: palette
+links:
+  themes: true
+  tailwind: theme
+---
+
+HeroUI uses CSS variables and [BEM](https://getbem.com/) classes for theming. Customize everything from colors to component styles using standard CSS.
+
+<Callout type="info">
+  **Want to create your own theme?** Try the [Theme Builder](/themes) to visually customize colors, radius, fonts, and more — then export the CSS to use in your project.
+</Callout>
+
+## How It Works
+
+HeroUI's theming system is built on top of [Tailwind CSS v4](https://tailwindcss.com/docs/theme)'s theme. When you import `@heroui/styles`, it uses Tailwind's built-in color palettes, maps them to semantic variables, automatically switches between light and dark themes, and uses CSS layers and the `@theme` directive for organization.
+
+**Naming pattern:**
+- Colors without a suffix are backgrounds (e.g., `--accent`)
+- Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)
+
+## Quick Start
+
+**Apply a theme:** Add a theme class to your HTML and apply colors to the body:
+
+```html
+<html class="light" data-theme="light">
+  <body class="bg-background text-foreground">
+    <!-- Your app -->
+  </body>
+</html>
+```
+
+**Switch themes:**
+```html
+<!-- Light theme -->
+<html class="light" data-theme="light">
+
+<!-- Dark theme -->
+<html class="dark" data-theme="dark">
+```
+
+**Switch themes programmatically with [next-themes](https://github.com/pacocoursey/next-themes) (For Next.js):**
+
+First, wrap your app with `ThemeProvider`:
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { ThemeProvider } from "next-themes";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="light">
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx
+import { Providers } from "./providers";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="bg-background text-foreground">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+Then use `useTheme` to toggle between themes:
+
+```tsx
+"use client";
+
+import { useTheme } from "next-themes";
+
+export function ThemeSwitch() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+      Toggle {theme === "dark" ? "Light" : "Dark"} Mode
+    </button>
+  );
+}
+```
+
+**Override colors:**
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+
+:root {
+  /* Override any color variable */
+  --accent: oklch(0.7 0.25 260);
+  --success: oklch(0.65 0.15 155);
+}
+```
+
+> **Note**: See [Colors](/docs/handbook/colors) for the complete color palette and visual reference.
+
+> **Dark mode**: For a complete setup guide with `next-themes` and HeroUI's `useTheme` hook, see [Dark Mode](/docs/handbook/dark-mode).
+
+**Create your own theme:**
+
+<CollapsibleCode lang="css" code={`/* src/themes/ocean.css */
+@layer base {
+    /* Ocean Light */
+    [data-theme="ocean"] {
+      color-scheme: light;
+
+      /* Primitive Colors (Do not change between light and dark) */
+      --white: oklch(100% 0 0);
+      --black: oklch(0% 0 0);
+      --snow: oklch(0.9911 0 0);
+      --eclipse: oklch(0.2103 0.0059 285.89);
+
+      /* Spacing & Layout */
+      --spacing: 0.25rem;
+      --border-width: 1px;
+      --field-border-width: 0px;
+      --disabled-opacity: 0.5;
+      --ring-offset-width: 2px;
+      --cursor-interactive: pointer;
+      --cursor-disabled: not-allowed;
+
+      /* Radius */
+      --radius: 0.75rem;
+      --field-radius: calc(var(--radius) * 1.5);
+
+      /* Base Colors */
+      --background: oklch(0.985 0.015 225);
+      --foreground: var(--eclipse);
+
+      /* Surface: Used for non-overlay components */
+      --surface: var(--white);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components */
+      --overlay: var(--white);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(0.5517 0.0138 285.94);
+
+      --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+      --scrollbar-track: transparent;
+      --scrollbar-gutter: auto;
+      --scrollbar-width: thin;
+      --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+      --scrollbar: var(--scrollbar-thumb);
+
+      --default: oklch(94% 0.001 286.375);
+      --default-foreground: var(--eclipse);
+
+      /* Ocean accent */
+      --accent: oklch(0.450 0.150 230);
+      --accent-foreground: var(--snow);
+
+      /* Form Field Defaults */
+      --field-background: var(--white);
+      --field-foreground: oklch(0.2103 0.0059 285.89);
+      --field-placeholder: var(--muted);
+      --field-border: transparent;
+
+      /* Status (kept compatible) */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.7819 0.1585 72.33);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.6532 0.2328 25.74);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: var(--white);
+      --segment-foreground: var(--foreground);
+
+      /* Misc */
+      --border: oklch(0.50 0.060 230 / 22%);
+      --separator: oklch(92% 0.004 286.32);
+      --focus: var(--accent);
+      --link: var(--accent);
+
+      /* Shadows */
+      --surface-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+      --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+      --field-shadow:
+        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+        0 0 1px 0 rgba(0, 0, 0, 0.06);
+
+      /* Skeleton Default Global Animation */
+      --skeleton-animation: shimmer; /* Possible values: shimmer, pulse, none */
+
+      /* Tooltip Default Delays */
+      --tooltip-delay: 1500ms;
+      --tooltip-close-delay: 500ms;
+    }
+
+    /* Ocean Dark */
+    [data-theme="ocean-dark"] {
+      color-scheme: dark;
+
+      /* Base Colors */
+      --background: oklch(0.140 0.020 230);
+      --foreground: var(--snow);
+
+      /* Surface: Used for non-overlay components */
+      --surface: oklch(0.2103 0.0059 285.89);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components */
+      --overlay: oklch(0.22 0.0059 285.89);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(70.5% 0.015 286.067);
+
+      --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+      --scrollbar-track: transparent;
+      --scrollbar-gutter: auto;
+      --scrollbar-width: thin;
+      --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+      --scrollbar: var(--scrollbar-thumb);
+
+      --default: oklch(27.4% 0.006 286.033);
+      --default-foreground: var(--snow);
+
+      /* Form Field Defaults */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+
+      /* Ocean accent */
+      --accent: oklch(0.860 0.080 230);
+      --accent-foreground: var(--eclipse);
+
+      /* Status */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.8203 0.1388 76.34);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.594 0.1967 24.63);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: oklch(0.3964 0.01 285.93);
+      --segment-foreground: var(--foreground);
+
+      /* Misc */
+      --border: oklch(22% 0.006 286.033);
+      --separator: oklch(22% 0.006 286.033);
+      --focus: var(--accent);
+      --link: var(--accent);
+
+      /* Shadows */
+      --surface-shadow: 0 0 0 0 transparent inset;
+      --overlay-shadow: 0 0 0 0 transparent inset;
+      --field-shadow: 0 0 0 0 transparent inset;
+    }
+}
+`}
+/>
+
+Use your theme:
+
+```css
+/* app/globals.css */
+@layer theme, base, components, utilities;
+
+@import "tailwindcss";
+@import "@heroui/styles";
+
+@import "./src/themes/ocean.css" layer(theme); /* [!code highlight]*/
+```
+
+Apply your theme:
+
+```html
+<!-- index.html -->
+
+<!-- Light ocean -->
+<html data-theme="ocean">
+
+<!-- Dark ocean -->
+<html data-theme="ocean-dark">
+```
+
+## Customize Components
+
+**Global component styles:** Override any component using BEM classes:
+
+```css
+@layer components {
+  /* Customize buttons */
+  .button {
+    @apply font-semibold tracking-wide;
+  }
+
+  .button--primary {
+    @apply bg-blue-600 hover:bg-blue-700;
+  }
+
+  /* Customize accordions */
+  .accordion__trigger {
+    @apply text-lg font-bold;
+  }
+}
+```
+
+> **Note**: See [Styling](/docs/handbook/styling) for the complete styling reference.
+
+**Find component classes:** Each component docs page lists all available classes (base classes, modifiers, elements, states). Example: [Button classes](/docs/components/button#css-classes)
+
+## Import Strategies
+
+**Full import (recommended):** Get everything with two lines:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+**Selective import:** Import only what you need:
+
+```css
+/* Define layers */
+@layer theme, base, components, utilities;
+
+/* Base requirements */
+@import "tailwindcss";
+@import "@heroui/styles/base" layer(base);
+/* OR specific base file */
+@import "@heroui/styles/base/base.css" layer(base);
+
+/* Theme variables */
+@import "@heroui/styles/themes/shared/theme.css" layer(theme);
+@import "@heroui/styles/themes/default" layer(theme);
+/* OR specific theme files */
+@import "@heroui/styles/themes/default/index.css" layer(theme);
+@import "@heroui/styles/themes/default/variables.css" layer(theme);
+
+/* Components (all components) */
+@import "@heroui/styles/components" layer(components);
+/* OR specific component files */
+@import "@heroui/styles/components/index.css" layer(components);
+@import "@heroui/styles/components/button.css" layer(components);
+@import "@heroui/styles/components/accordion.css" layer(components);
+
+/* Utilities (optional) */
+@import "@heroui/styles/utilities" layer(utilities);
+
+/* Variants (optional) */
+@import "@heroui/styles/variants" layer(utilities);
+```
+
+> **Note**: Directory imports (e.g., `@heroui/styles/components`) automatically resolve to their `index.css` file. Use explicit file paths (e.g., `@heroui/styles/components/button.css`) to import individual component styles.
+
+**Headless mode:** Build your own styles from scratch:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles/base/base.css";
+
+/* Your custom styles */
+.button {
+  /* Your button styles */
+}
+```
+
+## Adding Custom Colors
+
+Add your own semantic colors to the theme:
+
+```css
+/* Define in both light and dark themes */
+:root,
+[data-theme="light"] {
+  --info: oklch(0.6 0.15 210);
+  --info-foreground: oklch(0.98 0 0);
+}
+
+.dark,
+[data-theme="dark"] {
+  --info: oklch(0.7 0.12 210);
+  --info-foreground: oklch(0.15 0 0);
+}
+
+/* Make the color available to Tailwind */
+@theme inline {
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+```
+
+Now use it in your components:
+
+```tsx
+<div className="bg-info text-info-foreground">Info message</div>
+```
+
+## Variables Reference
+
+HeroUI defines three types of variables in [`variables.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css):
+
+1. **Base Variables** — Non-changing values like `--white`, `--black`, spacing, and typography
+2. **Theme Variables** — Colors that change between light/dark themes, plus scrollbar tokens (`--scrollbar-thumb`, `--scrollbar-width`, etc.)
+3. **Calculated Variables** — Hover states, soft variants, and border/separator levels (the **Calculated Colors** block in each light/dark theme, using `color-mix()`)
+
+For a complete reference, see: [Colors Documentation](/docs/handbook/colors), [Default Theme Variables](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css), [Shared Theme Utilities](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/shared/theme.css)
+
+**Tailwind theme bridge (`@theme inline`):**
+
+[`themes/shared/theme.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/shared/theme.css) maps semantic variables to Tailwind tokens (`--color-*`, `--radius-*`, `--ease-*`). Calculated colors reference underlying vars (e.g. `--surface-hover`, `--accent-soft`) from `variables.css` — they are not inlined with `color-mix()` in this file:
+<CollapsibleCode lang="css" code={`  @theme inline {
+    --color-background: var(--background);
+    --color-foreground: var(--foreground);
+
+    --color-surface: var(--surface);
+    --color-surface-foreground: var(--surface-foreground);
+    --color-surface-hover: var(--surface-hover);
+
+    --color-surface-secondary: var(--surface-secondary);
+    --color-surface-secondary-foreground: var(--surface-secondary-foreground);
+
+    --color-surface-tertiary: var(--surface-tertiary);
+    --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
+
+    --color-overlay: var(--overlay);
+    --color-overlay-foreground: var(--overlay-foreground);
+
+    --color-muted: var(--muted);
+
+    --color-accent: var(--accent);
+    --color-accent-foreground: var(--accent-foreground);
+
+    --color-segment: var(--segment);
+    --color-segment-foreground: var(--segment-foreground);
+
+    --color-border: var(--border);
+    --color-separator: var(--separator);
+    --color-focus: var(--focus);
+    --color-link: var(--link);
+
+    --color-default: var(--default);
+    --color-default-foreground: var(--default-foreground);
+
+    --color-success: var(--success);
+    --color-success-foreground: var(--success-foreground);
+
+    --color-warning: var(--warning);
+    --color-warning-foreground: var(--warning-foreground);
+
+    --color-danger: var(--danger);
+    --color-danger-foreground: var(--danger-foreground);
+
+    --color-backdrop: var(--backdrop);
+
+    --shadow-surface: var(--surface-shadow);
+    --shadow-overlay: var(--overlay-shadow);
+    --shadow-field: var(--field-shadow);
+
+    /* Form Field Tokens */
+    --color-field: var(--field-background, var(--default));
+    --color-field-hover: var(--field-hover);
+    --color-field-foreground: var(--field-foreground, var(--foreground));
+    --color-field-placeholder: var(--field-placeholder, var(--muted));
+    --color-field-border: var(--field-border, var(--border));
+    --radius-field: var(--field-radius, calc(var(--radius) * 1.5));
+    --border-width-field: var(--field-border-width, var(--border-width));
+
+    /* Color Tokens */
+    --color-background-secondary: var(--background-secondary);
+    --color-background-tertiary: var(--background-tertiary);
+    --color-background-inverse: var(--background-inverse);
+
+    --color-default-hover: var(--default-hover);
+    --color-accent-hover: var(--accent-hover);
+    --color-success-hover: var(--success-hover);
+    --color-warning-hover: var(--warning-hover);
+    --color-danger-hover: var(--danger-hover);
+
+    /* Form Field Colors */
+    --color-field-focus: var(--field-focus);
+    --color-field-border-hover: var(--field-border-hover);
+    --color-field-border-focus: var(--field-border-focus);
+
+    /* Soft Colors */
+    --color-default-soft: var(--default-soft);
+    --color-default-soft-foreground: var(--default-soft-foreground);
+    --color-default-soft-hover: var(--default-soft-hover);
+
+    --color-accent-soft: var(--accent-soft);
+    --color-accent-soft-foreground: var(--accent-soft-foreground);
+    --color-accent-soft-hover: var(--accent-soft-hover);
+
+    --color-danger-soft: var(--danger-soft);
+    --color-danger-soft-foreground: var(--danger-soft-foreground);
+    --color-danger-soft-hover: var(--danger-soft-hover);
+
+    --color-warning-soft: var(--warning-soft);
+    --color-warning-soft-foreground: var(--warning-soft-foreground);
+    --color-warning-soft-hover: var(--warning-soft-hover);
+
+    --color-success-soft: var(--success-soft);
+    --color-success-soft-foreground: var(--success-soft-foreground);
+    --color-success-soft-hover: var(--success-soft-hover);
+
+    /* Separator Colors - Levels */
+    --color-separator-secondary: var(--separator-secondary);
+    --color-separator-tertiary: var(--separator-tertiary);
+
+    /* Border Colors - Levels */
+    --color-border-secondary: var(--border-secondary);
+    --color-border-tertiary: var(--border-tertiary);
+
+    /* Radius and default sizes - defaults can change by just changing the --radius */
+    --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
+    --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
+    --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
+    --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
+    --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
+    --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
+    --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
+    --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
+
+    /* Transition Timing Functions  */
+    --ease-smooth: ease; /* same as transition: ease; */
+    /* These custom curves are made by https://twitter.com/bdc */
+
+    /* From smoother to faster */
+    --ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
+    --ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
+    --ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
+    --ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
+    --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+    --ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);
+    /* From slower to faster */
+    --ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+    --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
+    --ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
+    --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
+    --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+    --ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
+    /* Custom smooth-out curve: fast start, smooth stop - Apple style */
+    --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
+    /* From slower to faster */
+    --ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+    --ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
+    --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
+    --ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
+    --ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
+    --ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
+
+    /* Linear */
+    --ease-linear: linear;
+
+    /* Animations */
+    --animate-spin-fast: spin 0.75s linear infinite;
+    --animate-skeleton: skeleton 2s linear infinite;
+    --animate-caret-blink: caret-blink 1.2s ease-out infinite;
+
+    @keyframes skeleton {
+      100% {
+        transform: translateX(200%);
+      }
+    }
+
+    @keyframes caret-blink {
+      0%,
+      70%,
+      100% {
+        opacity: 1;
+      }
+      20%,
+      50% {
+        opacity: 0;
+      }
+    }
+  }
+`}
+/>
+
+Form controls rely on `--field-*` theme variables. Hover, focus, and border variants are defined under **Calculated Colors** in `variables.css` and mapped to Tailwind in `theme.css` (e.g. `--color-field-hover: var(--field-hover)`). Override `--field-background`, `--field-hover`, and related tokens in your theme to restyle inputs, checkboxes, radios, and OTP slots without affecting surfaces like buttons or cards.
+
+## Scrollbars
+
+HeroUI applies a shared scrollbar style to component scroll areas (tables, popovers, drawers, and similar). Scrollbars use standard CSS properties (`scrollbar-width`, `scrollbar-color`, `scrollbar-gutter`) — no `::-webkit-scrollbar` overrides.
+
+**Modes** — set `data-scrollbar` on `<html>`, a component root, or a scroll slot:
+
+| Mode | `data-scrollbar` | Behavior |
+|------|------------------|----------|
+| HeroUI thin | *(unset)* or `thin` | Thin thumb from theme tokens |
+| OS / browser | `default` | Native scrollbars (`auto`) |
+| Hidden | `none` | No visible scrollbar (`scrollbar-width: none`) |
+
+```html
+<!-- Native scrollbars everywhere -->
+<html data-scrollbar="default">
+
+<!-- Restore HeroUI scrollbars in one subtree -->
+<main data-scrollbar="thin">
+  ...
+</main>
+
+<!-- Hide scrollbars in one subtree (e.g. a popover) -->
+<div data-scrollbar="none">
+  ...
+</div>
+```
+
+**Theme variables** — defined in light and dark theme blocks in [`variables.css`](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css):
+
+| Variable | Description |
+|----------|-------------|
+| `--scrollbar-thumb` | Thumb color (default: 15% `--foreground` via `color-mix`) |
+| `--scrollbar-track` | Track color (default: `transparent`) |
+| `--scrollbar-gutter` | Gutter (default: `auto`) |
+| `--scrollbar-width` | `scrollbar-width` (default: `thin`) |
+| `--scrollbar-color` | `scrollbar-color` (default: thumb + track) |
+| `--scrollbar` | Legacy alias of `--scrollbar-thumb` |
+
+**Customize globally:**
+
+```css
+/* app/globals.css */
+:root {
+  --scrollbar-thumb: color-mix(in oklch, var(--accent) 30%, transparent);
+  --scrollbar-gutter: auto;
+}
+```
+
+**Per scroll slot** — pass `data-scrollbar` on a component or override tokens on a wrapper:
+
+```tsx
+<Table data-scrollbar="default">
+  ...
+</Table>
+
+<Drawer.Content data-scrollbar="thin" />
+
+<Calendar.YearPickerGrid data-scrollbar="none" />
+```
+
+**Custom overflow areas** — use the `scrollbar`, `scrollbar-thin`, `scrollbar-default`, or `scrollbar-none` utilities from `@heroui/styles` on your own elements. See [Styling](/docs/handbook/styling) for class-based overrides.
+
+> **Note**: Some components hide scrollbars by default (date picker popovers, color picker, secondary tabs). Nested scroll slots (e.g. the calendar year picker inside a date picker) keep HeroUI scrollbars because `scrollbar-none` only affects the element it is applied to, not descendants using `@apply scrollbar`.
+
+## Vibrant Palette
+
+By default, HeroUI uses accessible soft foreground colors that mix the semantic color with the foreground for better contrast. If you prefer more saturated, vibrant soft foreground colors, add the `data-vibrant-palette` attribute to your root element:
+
+```html
+<html data-vibrant-palette="true">
+```
+
+This switches all `*-soft-foreground` variables (accent, success, warning, danger) to use 92% of the semantic color with only 8% foreground mixed in — closer to the raw color but with a slight contrast boost.
+
+| Mode | Accessible (default) | Vibrant |
+|------|----------------------|---------|
+| Soft foreground | `color-mix(color 70-80%, foreground 30-40%)` | `color-mix(color 92%, foreground 8%)` |
+
+<Callout type="warn">
+  The vibrant palette prioritizes visual saturation over contrast. It may not meet WCAG accessibility guidelines for some color combinations, especially with lighter accent colors.
+</Callout>
+
+You can also enable vibrant palette in the [Theme Builder](/themes) via the "Vibrant palette" toggle in the theme popover.
+
+## Resources
+
+- [Colors Documentation](/docs/handbook/colors)
+- [Styling Guide](/docs/handbook/styling)
+- [Tailwind CSS v4 Theming](https://tailwindcss.com/docs/theme)
+- [BEM Methodology](https://getbem.com/)
+- [OKLCH Color Tool](https://oklch.com)
diff --git a/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx b/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx
new file mode 100644
index 0000000..44f45af
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(overview)/cli.mdx
@@ -0,0 +1,417 @@
+---
+title: CLI
+description: Use the CLI to manage HeroUI dependencies and initialize projects.
+icon: terminal
+---
+
+The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to `install`, `uninstall`, or `upgrade` individual components, assess the health of your project, download documentation for AI coding agents, and more.
+
+## Installation
+
+Requirements:
+
+- [Node.js version 22.22.0 or later](https://nodejs.org/en/)
+
+
+### Global Installation
+
+To install `heroui-cli` globally, execute one of the following commands in your terminal:
+
+
+```npm
+npm install heroui-cli@latest -g
+```
+
+### Without Installation
+
+Alternatively, you can use `heroui-cli` without a global installation by running one of the following:
+
+<Tabs items={["pnpm", "npm", "yarn", "bun"]}>
+  <Tab value="pnpm">
+    ```bash
+    pnpm dlx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="npm">
+    ```bash
+    npx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn dlx heroui-cli@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bunx heroui-cli@latest
+    ```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+Once `heroui-cli` is installed, run the following command to display available commands:
+
+```bash
+heroui
+```
+
+This will produce the following help output:
+
+```bash
+Usage: heroui [command]
+
+Options:
+  -v, --version                  Output the current version
+  --no-cache                     Disable cache, by default data will be cached for 30m after the first request
+  -d, --debug                    Debug mode will not install dependencies
+  -h --help                      Display help information for commands
+
+Commands:
+  init [options] [projectName]   Initializes a new project
+  install [options]              Installs @heroui/react and @heroui/styles to your project
+  upgrade [options]              Upgrades @heroui/react and @heroui/styles to the latest versions
+  uninstall [options]            Uninstall @heroui/react and @heroui/styles from the project
+  list [options]                 Lists installed HeroUI packages (@heroui/react, @heroui/styles)
+  env [options]                  Displays debugging information for the local environment
+  doctor [options]               Checks for issues in the project
+  agents-md [options]            Downloads HeroUI documentation for AI coding agents
+  help [command]                 Display help for command
+```
+
+### init
+
+Initialize a new HeroUI project using the `init` command. This sets up your project with the necessary configurations.
+
+```bash
+heroui init [options]
+```
+
+**Options:**
+
+- `-t --template [string]` The template to use for the new project e.g. app, pages, vite, react-router
+- `-p --package [string]` The package manager to use for the new project
+
+output:
+
+```bash
+HeroUI CLI <version>
+
+┌  Create a new project
+│
+◇  Select a template (Enter to select)
+│  ● App (A Next.js 16 with app directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ Pages (A Next.js 16 with pages directory template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ Vite (A Vite template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│  ○ React Router (A React Router template pre-configured with HeroUI (v3) and Tailwind CSS.)
+│
+◇  New project name (Enter to skip with default name)
+│  my-heroui-app
+│
+◇  Select a package manager (Enter to select)
+│  ● npm
+│  ○ yarn
+│  ○ pnpm
+│  ○ bun
+│
+◇  Template created successfully!
+│
+◇  Next steps ───────╮
+│                    │
+│  cd my-heroui-app  │
+│  npm install       │
+│                    │
+├────────────────────╯
+│
+└  🚀 Get started with npm run dev
+```
+
+
+Install the dependencies to start the local server:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    cd my-heroui-app && npm install
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    cd my-heroui-app && pnpm install
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    cd my-heroui-app && yarn install
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    cd my-heroui-app && bun install
+    ```
+  </Tab>
+</Tabs>
+
+Start the local server:
+
+```npm
+npm run dev
+```
+
+### Install
+
+Install `@heroui/react` and `@heroui/styles` to your project, along with their peer dependencies. If they are already installed, the command does nothing.
+
+```bash
+heroui install [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+
+**Output:**
+
+```bash
+HeroUI CLI <version>
+
+📦 Packages to be installed:
+╭─────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version        │   Status   │   Docs                 │
+│─────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0          │   stable   │   https://heroui.com   │
+│   @heroui/styles   │   3.0.0          │   stable   │   https://heroui.com   │
+╰─────────────────────────────────────────────────────────────────────────────╯
+
+╭─────────────── PeerDependencies ────────────────╮
+│  react@18.3.1                      latest       │
+│  react-dom@18.3.1                  latest       │
+│  tailwindcss@4.2.2                 latest       │
+╰─────────────────────────────────────────────────╯
+? Proceed with installation? › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ @heroui/react and @heroui/styles installed successfully
+```
+
+### upgrade
+
+
+Upgrade `@heroui/react` and `@heroui/styles` with their peer dependencies to the latest versions.
+
+```bash
+heroui upgrade [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+**Output:**
+
+```bash
+HeroUI CLI <version>
+
+╭──────────────────────────── Upgrade ────────────────────────────╮
+│  @heroui/react               ^3.0.0  ->  ^3.1.0                │
+│  @heroui/styles              ^3.0.0  ->  ^3.1.0                │
+╰─────────────────────────────────────────────────────────────────╯
+
+? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ Upgrade complete. All packages are up to date.
+```
+
+### uninstall
+
+Uninstall `@heroui/react` and `@heroui/styles` from your project. Peer dependencies will not be uninstalled.
+
+```bash
+heroui uninstall [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+**Output:**
+
+```bash
+HeroUI CLI <version>
+
+❗️ Packages slated for uninstallation:
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version   │   Status   │   Docs                               │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0     │   stable   │   https://heroui.com                 │
+│   @heroui/styles   │   3.0.0     │   stable   │   https://heroui.com                 │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+? Confirm uninstallation of these packages: › - Use arrow-keys. Return to submit.
+❯   Yes
+    No
+
+✅ Successfully uninstalled: @heroui/react, @heroui/styles
+```
+
+### list
+
+List the installed HeroUI packages (`@heroui/react`, `@heroui/styles`).
+
+```bash
+heroui list [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+**Output:**
+
+```bash
+HeroUI CLI <version>
+
+Current installed packages:
+
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version          │   Status   │   Docs                        │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+### doctor
+
+Check for issues in your project.
+- Check whether `@heroui/react` and `@heroui/styles` are installed
+- Check whether `required peer dependencies` are installed and matched minimal requirements in the project
+
+
+```bash
+heroui doctor [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+**Output:**
+
+If there is a problem in your project, the `doctor` command will display the problem information.
+
+```bash
+HeroUI CLI <version>
+
+HeroUI CLI: ❌ Your project has 1 issue that require attention
+
+❗️Issue 1: missingHeroUIPackages
+
+The following HeroUI packages are not installed:
+- @heroui/styles
+
+Run `heroui install` to install them.
+```
+
+Otherwise, the `doctor` command will display the following message.
+
+```bash
+HeroUI CLI <version>
+
+✅ Your project has no detected issues.
+```
+
+### env
+
+Display debug information about the local environment.
+
+```bash
+heroui env [options]
+```
+
+**Options:**
+
+- `-p --packagePath` [string] The path to the package.json file
+
+**Output:**
+
+```bash
+HeroUI CLI <version>
+
+Current installed packages:
+
+╭──────────────────────────────────────────────────────────────────────────────────────╮
+│   Package          │   Version          │   Status   │   Docs                        │
+│──────────────────────────────────────────────────────────────────────────────────────│
+│   @heroui/react    │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+│   @heroui/styles   │   3.0.0 🚀latest   │   stable   │   https://heroui.com          │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+
+Environment Info:
+  System:
+    OS: darwin
+    CPU: arm64
+  Binaries:
+    Node: v25.8.1
+```
+
+### agents-md
+
+Download HeroUI documentation for AI coding agents (Claude, Cursor, etc.). The command clones the latest docs from the HeroUI repository and injects a compact index into `AGENTS.md` or `CLAUDE.md` so assistants can reference your project's HeroUI setup.
+
+```bash
+heroui agents-md [options]
+```
+
+**Options:**
+
+- `--react` [boolean] Include React docs only (one library at a time)
+- `--native` [boolean] Include Native docs only
+- `--migration` [boolean] Include HeroUI v2 to v3 migration docs only
+- `--output <file>` [string] Target file path (e.g., `AGENTS.md`, `CLAUDE.md`)
+- `--ssh` [boolean] Use SSH instead of HTTPS for git clone
+
+**Examples:**
+
+Run without flags to enter interactive mode:
+
+```bash
+heroui agents-md
+```
+
+Download React docs to a specific file:
+
+```bash
+heroui agents-md --react --output AGENTS.md
+```
+
+Download Native or migration docs:
+
+```bash
+heroui agents-md --native --output CLAUDE.md
+heroui agents-md --migration --output AGENTS.md
+```
+
+**How it works:**
+
+1. Clones documentation from the `v3` branch using git sparse-checkout
+2. Generates a compact index of doc and demo files
+3. Injects the index into your markdown file between markers (`<!-- HEROUI-REACT-AGENTS-MD-START -->` / `<!-- HEROUI-REACT-AGENTS-MD-END -->`, and similar for Native and Migration)
+4. Adds `.heroui-docs/` to `.gitignore`
+
+Only one of `--react`, `--native`, or `--migration` can be selected at a time.
+
+For more details, see [AGENTS.md](/docs/react/getting-started/agents-md).
+
+<Callout>
+  The `agents-md` command collects anonymous usage data (selection, output file names, duration, success or error). Set `HEROUI_ANALYTICS_DISABLED=1` to opt out.
+</Callout>
+
+## Reporting issues
+
+If you found a bug, please report it in [heroui-cli Issues](https://github.com/heroui-inc/heroui-cli/issues).
+
diff --git a/apps/docs/content/docs/en/react/getting-started/(overview)/design-principles.mdx b/apps/docs/content/docs/en/react/getting-started/(overview)/design-principles.mdx
new file mode 100644
index 0000000..fa6d4b0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(overview)/design-principles.mdx
@@ -0,0 +1,290 @@
+---
+title: Design Principles
+description: Core principles that guide HeroUI v3's design and development
+icon: book
+---
+
+HeroUI v3 follows 10 core principles that prioritize clarity, accessibility, customization, and developer experience.
+
+## Core Principles
+
+### 1. Semantic Intent Over Visual Style
+
+Use semantic naming (primary, secondary, tertiary) instead of visual descriptions (solid, flat, bordered). Inspired by [Uber's Base design system](https://base.uber.com/6d2425e9f/p/756216-button), variants follow a clear hierarchy:
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/emphasis-dark.jpg"
+  alt="Semantic Intent Hierarchy"
+  className="object-contain"
+/>
+
+
+```tsx
+// ✅ Semantic variants communicate hierarchy
+<Button variant="primary">Save</Button>
+<Button variant="secondary">Edit</Button>
+<Button variant="tertiary">Cancel</Button>
+```
+
+| Variant | Purpose | Usage |
+|---------|---------|-------|
+| **Primary** | Main action to move forward | 1 per context |
+| **Secondary** | Alternative actions | Multiple allowed |
+| **Tertiary** | Dismissive actions (cancel, skip) | Sparingly |
+| **Danger** | Destructive actions | When needed |
+
+### 2. Accessibility as Foundation
+
+Built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/) for WCAG 2.1 AA compliance. Automatic ARIA attributes, keyboard navigation, and screen reader support included.
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from '@heroui/react';
+
+<Tabs defaultSelectedKey="profile">
+  <TabList aria-label="Settings">
+    <Tab id="profile">Profile</Tab>
+    <Tab id="security">Security</Tab>
+  </TabList>
+  <TabPanel id="profile">Content</TabPanel>
+  <TabPanel id="security">Content</TabPanel>
+</Tabs>
+```
+
+### 3. Composition Over Configuration
+
+Compound components let you rearrange, customize, or omit parts as needed. Use dot notation, named exports, or mix both.
+
+```tsx
+// Compose parts to build exactly what you need
+import {
+  Accordion,
+  AccordionItem,
+  AccordionHeading,
+  AccordionTrigger,
+  AccordionIndicator,
+  AccordionPanel,
+  AccordionBody
+} from '@heroui/react';
+
+<Accordion>
+  <AccordionItem id="1">
+    <AccordionHeading>
+      <AccordionTrigger>
+        Question Text
+        <AccordionIndicator />
+      </AccordionTrigger>
+    </AccordionHeading>
+    <AccordionPanel>
+      <AccordionBody>Answer content</AccordionBody>
+    </AccordionPanel>
+  </AccordionItem>
+</Accordion>
+```
+
+### 4. Progressive Disclosure
+
+Start simple, add complexity only when needed. Components work with minimal props and scale up as requirements grow.
+
+```tsx
+// Level 1: Minimal
+<Button>Click me</Button>
+
+// Level 2: Enhanced
+<Button variant="primary" size="lg">
+  <Icon icon="gravity-ui:check" className="mr-2" />
+  Submit
+</Button>
+
+// Level 3: Advanced
+<Button variant="primary" isDisabled={isLoading}>
+  {isLoading ? <><Spinner size="sm" className="mr-2" /> Loading...</> : 'Submit'}
+</Button>
+```
+
+### 5. Predictable Behavior
+
+Consistent patterns across all components: sizes (`sm`, `md`, `lg`), variants, className support, and data attributes. Same API, same behavior.
+
+```tsx
+// All components follow the same patterns
+<Button size="lg" variant="primary" className="custom" data-pressed="true" />
+<Chip size="lg" variant="success" className="custom" />
+<Avatar size="lg" className="custom" />
+
+// Compound components support both named exports and dot notation
+import { Alert, AlertIcon, CardHeader, AccordionTrigger } from '@heroui/react';
+
+// Named exports
+<Alert>
+  <AlertIcon />
+</Alert>
+
+// Dot notation
+<Alert>
+  <Alert.Icon />
+</Alert>
+```
+
+### 6. Type Safety First
+
+Full TypeScript support with IntelliSense, auto-completion, and compile-time error detection. Extend types for custom components.
+
+```tsx
+import type { ButtonProps } from '@heroui/react';
+
+// Type-safe props and event handlers
+<Button
+  variant="primary"  // Autocomplete: primary | secondary | tertiary | danger | ghost
+  size="md"          // Type checked: sm | md | lg
+  onPress={(e) => {  // e is properly typed as PressEvent
+    console.log(e.target);
+  }}
+/>
+
+// Extend types for custom components
+interface CustomButtonProps extends Omit<ButtonProps, 'variant'> {
+  intent: 'save' | 'cancel' | 'delete';
+}
+```
+
+### 7. Separation of Styles and Logic
+
+Styles (`@heroui/styles`) are separate from logic (`@heroui/react`), enabling use with any framework or vanilla HTML. See [Tailwind Play example](https://play.tailwindcss.com/vMYXzKPyUx).
+
+```html
+<!-- Use with plain HTML -->
+<button class="button button--primary">Click me</button>
+```
+
+or with React:
+
+```tsx
+// Apply styles to any component
+import { buttonVariants } from '@heroui/styles';
+
+<Link className={buttonVariants({ variant: "primary" })} href="/home">
+  Home
+</Link>
+```
+
+### 8. Developer Experience Excellence
+
+Clear APIs, descriptive errors, IntelliSense, AI-friendly markdown docs, and Storybook for visual testing.
+
+### 9. Complete Customization
+
+Beautiful defaults out-of-the-box. Transform the entire look with CSS variables or [BEM](https://getbem.com/) classes. Every slot is customizable.
+
+```css
+/* Theme-wide changes with variables */
+:root {
+  --accent: oklch(0.7 0.25 260);
+  --radius: 0.375rem;
+  --spacing: 0.5rem;
+}
+
+/* Component-specific customization */
+@layer components {
+  .button {
+    @apply uppercase tracking-wider;
+  }
+  .button--primary {
+    @apply bg-gradient-to-r from-purple-500 to-pink-500;
+  }
+}
+```
+
+### 10. Open and Extensible
+
+Wrap, extend, and customize components to match your needs. Use variant functions, direct BEM class application, or create custom wrappers.
+
+**Apply styles with variant functions:**
+
+```tsx
+import { Link } from '@heroui/react';
+import { linkVariants } from '@heroui/styles';
+import NextLink from 'next/link';
+
+// Use variant functions to style framework-specific components
+const slots = linkVariants({ underline: "hover" });
+
+<NextLink className={slots.base()} href="/about">
+  About Page
+  <Link.Icon className={slots.icon()} />
+</NextLink>
+```
+
+**Apply BEM classes directly:**
+
+```tsx
+import Link from 'next/link';
+
+// Apply HeroUI's BEM classes directly to any element
+<Link className="button button--primary" href="/dashboard">
+  Dashboard
+</Link>
+```
+
+**Create custom wrapper components:**
+
+```tsx
+// Custom wrapper component
+const CTAButton = ({
+  intent = 'primary-cta',
+  children,
+  ref,
+  ...props
+}: CTAButtonProps) => {
+  const variantMap = {
+    'primary-cta': 'primary',
+    'secondary-cta': 'secondary',
+    'minimal': 'ghost'
+  };
+
+  return (
+    <Button ref={ref} variant={variantMap[intent]} {...props}>
+      {children}
+    </Button>
+  );
+};
+```
+
+**Extend with Tailwind Variants:**
+
+```tsx
+import { Button } from '@heroui/react';
+import { buttonVariants, tv } from '@heroui/styles';
+
+// Extend button styles with custom variants
+const myButtonVariants = tv({
+  extend: buttonVariants,
+  variants: {
+    variant: {
+      'primary-cta': 'bg-gradient-to-r from-blue-500 to-purple-600 text-white shadow-lg',
+      'secondary-cta': 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50',
+    }
+  }
+});
+
+// Use the custom variants
+function CustomButton({ variant, className, ...props }) {
+  return <Button className={myButtonVariants({ variant, className })} {...props} />;
+}
+
+// Usage
+<CustomButton variant="primary-cta">Get Started</CustomButton>
+<CustomButton variant="secondary-cta">Learn More</CustomButton>
+```
+
+## Comparison with HeroUI v2
+
+| Aspect | HeroUI v2 | HeroUI v3 |
+|--------|-----------|-----------|
+| **Animations** | Framer Motion | CSS + GPU accelerated |
+| **Component Pattern** | Single components with many props | Compound components |
+| **Variants** | Visual-based (solid, bordered, flat) | Semantic (primary, secondary, tertiary) |
+| **Styling** | Tailwind v4 partially supported | Tailwind v4 fully supported |
+| **Accessibility** | Excellent (React Aria powered) | Excellent (React Aria powered) |
+| **Bundle Size** | Larger (Bundle) | Smaller (tree-shakeable) |
+| **Customization Difficulty** | Medium (Props-based) | Simple (Compound components + Native CSS) |
diff --git a/apps/docs/content/docs/en/react/getting-started/(overview)/frameworks.mdx b/apps/docs/content/docs/en/react/getting-started/(overview)/frameworks.mdx
new file mode 100644
index 0000000..0bada17
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(overview)/frameworks.mdx
@@ -0,0 +1,145 @@
+---
+title: Frameworks
+description: Integrate HeroUI with your framework
+icon: layers
+---
+
+## Next.js
+
+### 1. Create a Next.js project
+
+```bash
+npx heroui-cli@latest init
+```
+
+<Callout>
+  When prompted, select the **App** or **Pages** template. Then open your new folder and install dependencies (for example `pnpm install`).
+</Callout>
+
+### 2. Use your first HeroUI component
+
+<Tabs items={["App Router", "Pages Router"]}>
+  <Tab value="App Router">
+    Example: `app/page.tsx`
+
+    ```tsx
+    import {Button} from "@heroui/react";
+
+    export default function HomePage() {
+      return (
+        <main className="flex min-h-screen items-center justify-center">
+          <Button variant="tertiary">Hello HeroUI</Button>
+        </main>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="Pages Router">
+    Example: `pages/index.tsx`
+
+    ```tsx
+    import {Button} from "@heroui/react";
+
+    export default function HomePage() {
+      return (
+        <main className="flex min-h-screen items-center justify-center">
+          <Button variant="tertiary">Hello HeroUI</Button>
+        </main>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Callout>
+  HeroUI v3 does not require a provider. Components work directly after installation and style import.
+</Callout>
+
+### 3 Locale Setup (Optional)
+
+To integrate with Next.js, ensure the locale on the server matches the client.
+
+In your root layout, determine the user's preferred language and set the `lang` and `dir` attributes on the `<html>` element.
+
+```tsx
+// app/layout.tsx
+import {headers} from 'next/headers';
+import {isRTL} from '@heroui/react';
+import {ClientProviders} from './provider';
+
+export default async function RootLayout({children}) {
+  // Get the user's preferred language from the Accept-Language header.
+  // You could also get this from a database, URL param, etc.
+  const acceptLanguage = (await headers()).get('accept-language');
+  const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US';
+
+  return (
+    <html lang={lang} dir={isRTL(lang) ? 'rtl' : 'ltr'}>
+      <body>
+        <ClientProviders lang={lang}>
+          {children}
+        </ClientProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+Create `app/provider.tsx`. This should render an `I18nProvider` to set the locale used by React Aria.
+
+```tsx
+// app/provider.tsx
+"use client";
+
+import {I18nProvider} from '@heroui/react';
+
+export function ClientProviders({lang, children}) {
+  return (
+    <I18nProvider locale={lang}>
+      {children}
+    </I18nProvider>
+  );
+}
+```
+
+If you are using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP) with a nonce, add a `<meta property="csp-nonce">` tag to your document head, setting the content attribute to the generated nonce value. React Aria automatically reads the nonce from this tag.
+
+## Vite
+
+### 1. Create a Vite project
+
+```bash
+npx heroui-cli@latest init
+```
+
+<Callout>
+  When prompted, select the **Vite** template. Then open your new folder and install dependencies (for example `pnpm install`).
+</Callout>
+
+### 2. Use your first HeroUI component
+
+Example: `src/App.tsx`
+
+```tsx
+import {Button} from "@heroui/react";
+
+function App() {
+  return (
+    <main className="flex min-h-screen items-center justify-center">
+      <Button variant="tertiary">Hello HeroUI</Button>
+    </main>
+  );
+}
+
+export default App;
+```
+
+<Callout>
+  HeroUI v3 does not require a provider. Components work directly after installation and style import.
+</Callout>
+
+## Next steps
+
+- [Quick Start](/docs/react/getting-started/quick-start) for the fastest setup path
+- [Themes](/docs/react/getting-started/theming) to customize colors and tokens
+- [Components](/docs/react/components) to explore all available components
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/getting-started/(overview)/quick-start.mdx b/apps/docs/content/docs/en/react/getting-started/(overview)/quick-start.mdx
new file mode 100644
index 0000000..f68e95f
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(overview)/quick-start.mdx
@@ -0,0 +1,94 @@
+---
+title: Quick Start
+description: Get started with HeroUI v3 in minutes
+icon: rocket
+---
+
+## Requirements
+
+- [React 19+](https://reactjs.org/)
+- [Tailwind CSS v4](https://tailwindcss.com/docs/installation/framework-guides)
+
+## Quick Install
+
+<CopyPrompt
+  prompt={`Set up HeroUI in this React project.
+
+Use the HeroUI MCP server (@heroui/react-mcp) as the single source of truth for installation steps, peer dependencies, and component APIs. Start by retrieving the latest quick-start / installation guide from the MCP and follow it precisely — do not rely on memory for versions, package names, or setup steps.
+
+Before making any changes:
+
+1. Analyze the project. Detect the package manager (npm / pnpm / yarn / bun), framework (e.g. Next.js, Vite, Remix, Astro, etc.), TypeScript usage, and the location of the main CSS entry file (e.g. globals.css, app.css, index.css).
+2. Confirm the project meets the requirements: React 19+ and Tailwind CSS v4. If Tailwind CSS v4 is not installed, set it up following the official Tailwind v4 framework guide that matches the detected framework before adding HeroUI.
+3. Read package.json and only install what is missing. Pin to the exact versions listed in the MCP quick-start to avoid compatibility issues.
+
+Then apply the setup:
+
+- Install @heroui/react and @heroui/styles plus any missing mandatory peer dependencies.
+- In the main Tailwind CSS entry file, add \`@import "@heroui/styles";\` immediately after \`@import "tailwindcss";\`. Import order matters — tailwindcss must be imported first.
+- Make sure the CSS entry file is loaded by the app (e.g. imported in the root layout / entry file for Next.js, Vite, Remix, etc.). HeroUI v3 does not require a Provider, so no wrapper component is needed.
+- Add a small smoke test by rendering a \`<Button>\` from \`@heroui/react\` somewhere visible to confirm styles are applied.
+
+When done, summarize the changes you made and tell me how to start the dev server.`}
+>
+  **Prefer to let your AI assistant do it?** Install the [HeroUI MCP Server](/docs/react/getting-started/mcp-server) in your editor, then paste the prompt into your AI assistant — it will analyze your project and handle the entire setup for you.
+</CopyPrompt>
+
+Install HeroUI and required dependencies:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+## Import Styles
+
+Add to your main CSS file `globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles"; /* [!code highlight]*/
+```
+
+<Callout type="warning">
+  Import order matters. Always import `tailwindcss` first.
+</Callout>
+
+## Use Components
+
+```tsx
+import { Button } from '@heroui/react';
+
+function App() {
+  return (
+    <Button>
+      My Button
+    </Button>
+  );
+}
+```
+
+## What's Next?
+
+- [Themes](/themes) - Create and share your own themes
+- [Browse Components](/docs/react/components) - See all available components
+- [Learn Styling](/docs/handbook/styling) - Customize with Tailwind CSS
+- [Explore Patterns](/docs/handbook/composition) - Master compound components
diff --git a/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agent-skills.mdx b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..d1299d1
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agent-skills.mdx
@@ -0,0 +1,71 @@
+---
+title: Agent Skills
+description: Enable AI assistants to build UIs with HeroUI v3 components
+---
+
+HeroUI Skills give your AI assistant comprehensive knowledge of HeroUI v3 components, patterns, and best practices.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agent-skills-dark.jpg"
+  alt="HeroUI v3 MCP Server"
+/>
+
+### Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-react
+```
+
+Or using the skills package:
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+Support Claude Code, Cursor, OpenCode and more.
+</span>
+
+### Usage
+
+Skills are **automatically discovered** by your AI assistant, or call it directly using `/heroui-react` command.
+
+Simply ask your AI assistant to:
+- Build components using HeroUI v3
+- Create pages with HeroUI components
+- Customize themes and styles
+- Access component documentation
+
+<Callout>
+  For more complex use cases, use the [MCP Server](/docs/react/getting-started/mcp-server) which provides real-time access to component documentation and source code.
+</Callout>
+
+### What's Included
+
+- HeroUI v3 installation guide
+- All HeroUI v3 components with props, examples, and usage patterns
+- Theming and styling guidelines
+- Design principles and composition patterns
+
+### Structure
+
+```
+skills/heroui-react/
+├── SKILL.md              # Main skill documentation
+├── LICENSE.txt           # Apache License 2.0
+└── scripts/              # Utility scripts
+    ├── list_components.mjs
+    ├── get_component_docs.mjs
+    ├── get_source.mjs
+    ├── get_styles.mjs
+    ├── get_theme.mjs
+    └── get_docs.mjs
+```
+
+### Related Documentation
+
+- [Agent Skills Specification](https://agentskills.io/home) - Learn about the Agent Skills format
+- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - Claude's Skills documentation
+- [Cursor Skills](https://cursor.com/docs/context/skills) - Using Skills in Cursor
+- [OpenCode Skills](https://opencode.ai/docs/skills) - Using Skills in OpenCode
diff --git a/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agents-md.mdx b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..0a5339a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/agents-md.mdx
@@ -0,0 +1,54 @@
+---
+title: AGENTS.md
+description: Download HeroUI v3 React documentation for AI coding agents
+icon: preview
+---
+
+Download HeroUI v3 React documentation directly into your project for AI assistants to reference.
+
+<Callout>
+  **Note:** The `agents-md` command is specifically for HeroUI React v3. Other CLI commands (like `add`, `init`, `upgrade`, etc.) are for HeroUI v2 (for now).
+</Callout>
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/agents-md-dark.jpg"
+  alt="HeroUI React v3 AGENTS.md"
+/>
+
+### Usage
+
+```bash
+npx heroui-cli@latest agents-md --react
+```
+
+Or specify output file:
+
+```bash
+npx heroui-cli@latest agents-md --react --output AGENTS.md
+```
+
+### What It Does
+
+- Downloads latest HeroUI v3 React docs to `.heroui-docs/react/`
+- Generates an index in `AGENTS.md` or `CLAUDE.md`
+- Includes demo files for code examples
+- Adds `.heroui-docs/` to `.gitignore` automatically
+
+### Options
+
+- `--react` - Download React docs only
+- `--output <files...>` - Target file(s) (e.g., `AGENTS.md` or `AGENTS.md CLAUDE.md`)
+- `--ssh` - Use SSH for git clone
+
+### Requirements
+
+- Tailwind CSS >= v4
+- React >= 19.0.0
+- `@heroui/react >= 3.0.0` or `@latest`
+
+### Related Documentation
+
+- [AGENTS.md](https://agents.md/) - Learn about the AGENTS.md format for coding agents
+- [CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) - Claude equivalent of AGENTS.md
+- [AGENTS.md vs Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) - AGENTS.md performance
diff --git a/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/llms-txt.mdx b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/llms-txt.mdx
new file mode 100644
index 0000000..f4556d0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/llms-txt.mdx
@@ -0,0 +1,62 @@
+---
+title: LLMs.txt
+description: Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI v3
+---
+
+We provide [LLMs.txt](https://llmstxt.org/) files to make HeroUI v3 documentation accessible to AI coding assistants.
+
+## Available Files
+
+**Core documentation:**
+- [/react/llms.txt](/react/llms.txt) — Quick reference index for React documentation
+- [/react/llms-full.txt](/react/llms-full.txt) — Complete HeroUI React documentation
+
+**For limited context windows:**
+- [/react/llms-components.txt](/react/llms-components.txt) — Component documentation only
+- [/react/llms-patterns.txt](/react/llms-patterns.txt) — Common patterns and recipes
+
+**All platforms:**
+- [/llms.txt](/llms.txt) — Quick reference index (React + Native)
+- [/llms-full.txt](/llms-full.txt) — Complete documentation (React + Native)
+- [/llms-components.txt](/llms-components.txt) — All component documentation
+- [/llms-patterns.txt](/llms-patterns.txt) — All patterns and recipes
+
+## Integration
+
+**Claude Code:** Tell Claude to reference the documentation:
+```
+Use HeroUI React documentation from https://heroui.com/react/llms.txt
+```
+Or add to your project's `.claude` file for automatic loading.
+
+**Cursor:** Use the `@Docs` feature:
+```
+@Docs https://heroui.com/react/llms-full.txt
+```
+[Learn more](https://docs.cursor.com/context/@-symbols/@-docs)
+
+**Windsurf:** Add to your `.windsurfrules` file:
+```
+#docs https://heroui.com/react/llms-full.txt
+```
+[Learn more](https://docs.codeium.com/windsurf/memories#memories-and-rules)
+
+**Other AI tools:** Most AI assistants can reference documentation by URL. Simply provide:
+```
+https://heroui.com/react/llms.txt
+```
+
+**For component-specific documentation:**
+```
+https://heroui.com/react/llms-components.txt
+```
+
+**For patterns and best practices:**
+```
+https://heroui.com/react/llms-patterns.txt
+```
+
+
+## Contributing
+
+Found an issue with AI-generated code? Help us improve our LLMs.txt files on [GitHub](https://github.com/heroui-inc/heroui).
diff --git a/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/mcp-server.mdx b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..9689252
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/mcp-server.mdx
@@ -0,0 +1,221 @@
+---
+title: MCP Server
+description: Access HeroUI v3 documentation directly in your AI assistant
+---
+
+The HeroUI MCP Server gives AI assistants direct access to HeroUI v3 component documentation, making it easier to build with HeroUI in AI-powered development environments.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/hero-react-mcp-light-new-2.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/hero-react-mcp-dark-new.jpg"
+  alt="HeroUI v3 MCP Server"
+/>
+
+
+The MCP server currently supports **@heroui/react v3** only and [stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). Published at `@heroui/react-mcp` on npm. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp).
+
+<Callout>
+  As we add more components to HeroUI v3, they'll be available in the MCP server too.
+</Callout>
+
+## Quick Setup
+
+### Cursor
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span  >Install in Cursor</span>
+  </a>
+</div>
+
+Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+Alternatively, add the following to your `~/.cursor/mcp.json` file. To learn more, see the [Cursor documentation](https://cursor.com/docs/context/mcp).
+
+### Claude Code
+
+Run this command in your terminal:
+
+```bash
+claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
+```
+
+Or manually add to your project's `.mcp.json` file:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Code and run `/mcp` to see the HeroUI MCP server in the list. If you see **Connected**, you're ready to use it.
+
+See the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for more details.
+
+### Windsurf
+
+Add the HeroUI server to your project's `.windsurf/mcp.json` configuration file:
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Windsurf to activate the MCP server.
+
+See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more details.
+
+### Zed
+
+Add the HeroUI server to your `settings.json` configuration file. Open settings via Command Palette (`zed: open settings`) or use `Cmd-,` (Mac) / `Ctrl-,` (Linux):
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"],
+      "env": {}
+    }
+  }
+}
+```
+
+After adding the configuration, restart Zed and open the Agent Panel settings view. Check that the indicator dot next to the heroui server is green with "Server is active" tooltip.
+
+See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp) for more details.
+
+### VS Code
+
+To configure MCP in VS Code with GitHub Copilot, add the HeroUI server to your project's `.vscode/mcp.json` configuration file:
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-react": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-react server.
+
+See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
+
+### Codex
+
+Add the HeroUI server to your `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):
+
+```toml title="config.toml"
+[mcp_servers.heroui-react]
+command = "npx"
+args = ["-y", "@heroui/react-mcp@latest"]
+```
+
+After adding the configuration, restart Codex and run `/mcp` in the TUI to verify the server is active.
+
+See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
+
+### OpenCode
+
+Add the HeroUI server to your project's `opencode.json` configuration file:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-react": {
+      "type": "local",
+      "command": ["npx", "-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart OpenCode to activate the MCP server.
+
+See the [OpenCode MCP documentation](https://open-code.ai/docs/en/mcp-servers) for more details.
+
+## Usage
+
+Once configured, ask your AI assistant questions like:
+
+- "Help me install HeroUI v3 in my Next.js/Vite/Astro app"
+- "Show me all HeroUI components"
+- "What props does the Button component have?"
+- "Give me an example of using the Card component"
+- "Get the source code for the Button component"
+- "Show me the CSS styles for Card"
+- "What are the theme variables for dark mode?"
+
+### Automatic Updates
+
+The MCP server can help you upgrade to the latest HeroUI version:
+
+```bash
+"Hey Cursor, update HeroUI to the latest version"
+```
+
+Your AI assistant will automatically:
+- Compare your current version with the latest release
+- Review the changelog for breaking changes
+- Apply the necessary code updates to your project
+
+This works for any version upgrade, whether you're updating to the latest stable or pre-release version.
+
+## Available Tools
+
+The MCP server provides these tools to AI assistants:
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all available HeroUI v3 components |
+| `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns for one or more components |
+| `get_component_source_code` | Access the React/TypeScript source code (.tsx files) for components |
+| `get_component_source_styles` | View the CSS styles (.css files) for components |
+| `get_theme_variables` | Access theme variables for colors, typography, spacing with light/dark mode support |
+| `get_docs` | Browse the full HeroUI v3 documentation including guides and principles (use path `/docs/react/getting-started/quick-start` for installation instructions) |
+
+
+## Troubleshooting
+
+**Requirements:** Node.js 22 or higher. The package will be automatically downloaded when using `npx`.
+
+**Need help?** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord Community](https://discord.gg/heroui)
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@heroui/react-mcp)
+- [GitHub Repository](https://github.com/heroui-inc/heroui-mcp)
+- [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/getting-started/index.mdx b/apps/docs/content/docs/en/react/getting-started/index.mdx
new file mode 100644
index 0000000..b7b40d9
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/index.mdx
@@ -0,0 +1,87 @@
+---
+title: Introduction
+description: An open-source UI component library for building beautiful and accessible user interfaces.
+icon: book-open
+image: https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg
+---
+
+HeroUI is a React component library built on [Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/index.html). Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg"
+  alt="HeroUI v3 Introduction"
+/>
+
+## Why HeroUI?
+
+**Beautiful by default** — Professional look out of the box, no extra styling needed.
+
+**Accessible** — Built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html) with focus management, keyboard navigation, and screen reader support.
+
+**Flexible** — Each component is made of customizable parts. Change what you need, leave the rest.
+
+**Developer-friendly** — Fully typed APIs, predictable patterns, and excellent autocompletion.
+
+**Maintained** — We handle updates, bug fixes, and new features. Just update the package.
+
+**Lightweight** — Tree-shaken. Only what you use goes into your app.
+
+**Future-proof** — Built for [React 19](https://react.dev/blog/2024/12/05/react-19) and [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4), designed for AI-assisted development.
+
+## A Living Library, Not Copy-Paste
+
+Copy-paste code works until it breaks. You're left maintaining outdated dependencies that stop evolving.
+
+HeroUI is different. It's a living library that grows with you:
+- Automatic updates and fixes
+- New features without extra work
+- Components stay current with React, Tailwind, and browsers
+- Deep customization, not shallow theme tweaks
+- AI-friendly APIs for code generation
+
+HeroUI v3 is not a snapshot—it's a garden that keeps growing. 🌱
+
+## HeroUI Ecosystem
+
+- **🌐 HeroUI v3** (web) — You're here! React components with Tailwind CSS v4
+- **📱 [HeroUI Native](https://link.heroui.com/native)** (mobile) — Beautiful components for React Native
+- **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)** (text-to-app) — Create apps with natural language
+- **🧠 UI for LLMs** — New platform & MCPs coming soon
+
+**Why React Aria?** We chose React Aria for accessibility at scale. We've used it since HeroUI v2, and v3 keeps familiar API conventions like `isDisabled` and `onPress`. Thanks to [Devon Govett](https://x.com/devongovett) and the Adobe team.
+
+## FAQ
+
+**Is HeroUI free?**
+Yes, completely free and open source under the Apache License 2.0.
+
+**Is it production-ready?**
+Yes. HeroUI v3 is stable and ready for production use.
+
+**Can I customize the components?**
+Yes! Use Tailwind utilities, CSS variables, [BEM](https://getbem.com/) modifiers, or compose component parts differently. Every slot is customizable.
+
+**Does it work with TypeScript?**
+Fully typed with excellent IDE support and autocompletion.
+
+**What about accessibility?**
+Built on React Aria Components for WCAG compliance. Keyboard navigation, focus management, and screen reader support included.
+
+**Can I use the styles without React?**
+Yes, the CSS can be applied to plain HTML. See our [Tailwind Play example](https://play.tailwindcss.com/vMYXzKPyUx).
+
+**Is there a Figma file?**
+Yes! Access our design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429).
+
+## Get Involved
+
+Join the community, share feedback, or contribute:
+
+- [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
+- [Discord](https://discord.gg/9b6yyZKmH4)
+- [X/Twitter](https://x.com/hero_ui)
+- [Contributing Guidelines](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md)
+
+HeroUI is released under the [Apache License 2.0](https://github.com/heroui-inc/heroui/blob/main/LICENSE).
+
diff --git a/apps/docs/content/docs/en/react/getting-started/meta.json b/apps/docs/content/docs/en/react/getting-started/meta.json
new file mode 100644
index 0000000..fe14eae
--- /dev/null
+++ b/apps/docs/content/docs/en/react/getting-started/meta.json
@@ -0,0 +1,29 @@
+{
+  "title": "Getting Started",
+  "description": "Get started with HeroUI v3",
+  "root": true,
+  "icon": "book-open",
+  "pages": [
+    "---Overview---",
+    "index",
+    "(overview)/quick-start",
+    "(overview)/design-principles",
+    "(overview)/frameworks",
+    "(overview)/cli",
+    "[sparkles][Showcase](/showcase)",
+    "[route][Roadmap](https://herouiv3.featurebase.app/roadmap)",
+    "[figma][Figma](https://www.figma.com/community/file/1546526812159103429)",
+    "---Handbook---",
+    "(handbook)/colors",
+    "(handbook)/theming",
+    "(handbook)/dark-mode",
+    "(handbook)/styling",
+    "(handbook)/animation",
+    "(handbook)/composition",
+    "---UI for Agents---",
+    "(ui-for-agents)/llms-txt",
+    "(ui-for-agents)/mcp-server",
+    "(ui-for-agents)/agent-skills",
+    "(ui-for-agents)/agents-md"
+  ]
+}
diff --git a/apps/docs/content/docs/en/react/meta.json b/apps/docs/content/docs/en/react/meta.json
new file mode 100644
index 0000000..4ad0788
--- /dev/null
+++ b/apps/docs/content/docs/en/react/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "Documentation",
+  "description": "HeroUI v3 Documentation",
+  "pages": ["getting-started", "components", "releases", "migration"]
+}
diff --git a/apps/docs/content/docs/en/react/migration/(components)/accordion.mdx b/apps/docs/content/docs/en/react/migration/(components)/accordion.mdx
new file mode 100644
index 0000000..a55405c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/accordion.mdx
@@ -0,0 +1,382 @@
+---
+title: Accordion
+description: Migration guide for Accordion from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Accordion documentation](/docs/react/components/accordion) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `AccordionItem` was a self-contained component that accepted props for title, subtitle, content, and other elements:
+
+```tsx
+import { Accordion, AccordionItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Accordion>
+      <AccordionItem
+        key="1"
+        title="Accordion 1"
+      >
+        Content here
+      </AccordionItem>
+      <AccordionItem
+        key="2"
+        title="Accordion 2"
+      >
+        Content here
+      </AccordionItem>
+    </Accordion>
+  );
+}
+```
+
+In v3, Accordion uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Accordion } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Accordion>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Accordion 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Accordion 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `AccordionItem` component with props  
+**v3:** Compound components: `Accordion.Item`, `Accordion.Heading`, `Accordion.Trigger`, `Accordion.Panel`, `Accordion.Body`, `Accordion.Indicator`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `selectedKeys` | `Accordion` | Renamed to `expandedKeys`; type `Iterable<Key>` |
+| `defaultSelectedKeys` | `Accordion` | Renamed to `defaultExpandedKeys` |
+| `onSelectionChange` | `Accordion` | Renamed to `onExpandedChange`; `(keys: Set<Key>) => void` |
+| `selectionMode="multiple"` | `Accordion` | Use `allowsMultipleExpanded` (boolean) |
+| `isCompact` | - | Removed (use Tailwind CSS e.g. `text-sm`, `py-2`) |
+| `hideIndicator` | - | Omit `<Accordion.Indicator />` to hide |
+| `disableAnimation`, `disableIndicatorAnimation`, `motionProps` | - | Removed (animations not supported / use CSS) |
+| `showDivider`, `dividerProps` | - | Removed (add dividers manually or use `Divider`) |
+| `keepContentMounted` | - | Removed (content always mounted in v3) |
+| `selectionBehavior`, `disallowEmptySelection` | - | Removed (not applicable) |
+| `itemClasses` | - | Use `className` on items |
+| `startContent` | - | Place content in `<Accordion.Trigger>` |
+| `title`, `subtitle` | - | Place content in `<Accordion.Trigger>` |
+
+### 3. Variants
+
+**v2 Variants:** `light`, `shadow`, `bordered`, `splitted`  
+**v3 Variants:** `default`, `surface`
+
+The v3 variants are simplified. To achieve similar effects to v2 variants:
+
+- **v2 `light`** → v3 `default`
+- **v2 `shadow`** → v3 `surface`
+- **v2 `bordered`** → v3 `default` + add border classes
+- **v2 `splitted`** → v3 `default` + add background color and spacing/margin between items
+
+### 4. Item Identification
+
+**v2:** React's `key` was used for both list reconciliation and expanded state.  
+**v3:** Use `id` on `Accordion.Item` for expanded state; keep React's `key` on items in lists.
+
+## Migration Examples
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Accordion, AccordionItem } from "@heroui/react";
+
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Accordion 
+      selectedKeys={selectedKeys} 
+      onSelectionChange={setSelectedKeys}
+    >
+      <AccordionItem key="1" title="Item 1">
+        Content 1
+      </AccordionItem>
+      <AccordionItem key="2" title="Item 2">
+        Content 2
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Accordion } from "@heroui/react";
+    import type { Key } from "@heroui/react";
+
+    const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set(["1"]));
+
+    <Accordion 
+      expandedKeys={expandedKeys} 
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 1</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 2</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### With Subtitle and Start Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <AccordionItem 
+        key="1"
+        title="Accordion 1"
+        subtitle="Press to expand"
+        startContent={<Icon icon="gravity-ui:box" />}
+      >
+        Content here
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            <Icon icon="gravity-ui:box" className="mr-2" />
+            <div className="flex flex-col">
+              <span>Accordion 1</span>
+              <span className="text-sm text-muted">Press to expand</span>
+            </div>
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content here</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Indicator
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Accordion>
+      <AccordionItem 
+        key="1"
+        title="Item 1"
+        indicator={(props) => (
+          props.isOpen ? <Icon icon="mdi:minus" /> : <Icon icon="mdi:plus" />
+        )}
+      >
+        Content
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { useState } from "react";
+    import { Accordion } from "@heroui/react";
+    import type { Key } from "@heroui/react";
+
+    const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set());
+
+    <Accordion 
+      expandedKeys={expandedKeys}
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator>
+              {expandedKeys.has("1") ? (
+                <Icon icon="gravity-ui:minus" />
+              ) : (
+                <Icon icon="gravity-ui:plus" />
+              )}
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+### Disabled Items and Default Expanded Keys
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Accordion 
+      defaultExpandedKeys={["1"]}
+      disabledKeys={["2"]}
+    >
+      <AccordionItem key="1" title="Item 1">
+        Content 1
+      </AccordionItem>
+      <AccordionItem key="2" title="Item 2">
+        Content 2
+      </AccordionItem>
+    </Accordion>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Accordion defaultExpandedKeys={["1"]}>
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 1
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 1</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item id="2" isDisabled>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Item 2
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>Content 2</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<AccordionItem 
+  classNames={{
+    base: "custom-base",
+    title: "custom-title",
+    content: "custom-content"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Accordion.Item className="custom-base">
+  <Accordion.Heading>
+    <Accordion.Trigger className="custom-title">
+      Title
+      <Accordion.Indicator />
+    </Accordion.Trigger>
+  </Accordion.Heading>
+  <Accordion.Panel>
+    <Accordion.Body className="custom-content">
+      Content
+    </Accordion.Body>
+  </Accordion.Panel>
+</Accordion.Item>
+```
+
+## Component Anatomy
+
+The v3 Accordion follows this structure:
+
+```
+Accordion (Root)
+  └── Accordion.Item
+      ├── Accordion.Heading
+      │   └── Accordion.Trigger
+      │       ├── [Your content: title, subtitle, icons, etc.]
+      │       └── Accordion.Indicator (optional)
+      └── Accordion.Panel
+          └── Accordion.Body
+              └── [Your content]
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components instead of props
+2. **State Props**: `selectedKeys` → `expandedKeys`, `onSelectionChange` → `onExpandedChange`
+3. **Multiple Selection**: `selectionMode="multiple"` → `allowsMultipleExpanded={true}`
+4. **Item identity**: Use `id` for expanded state; keep React's `key` for list reconciliation
+5. **Variants**: Reduced from 4 to 2 variants
+6. **Removed Props**: Many convenience props removed; use Tailwind CSS classes instead
+7. **Content Structure**: Title, subtitle, and start content must be manually placed in `Trigger`
+8. **Indicator**: Must be explicitly rendered; no automatic indicator
diff --git a/apps/docs/content/docs/en/react/migration/(components)/alert.mdx b/apps/docs/content/docs/en/react/migration/(components)/alert.mdx
new file mode 100644
index 0000000..88ce2c5
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/alert.mdx
@@ -0,0 +1,263 @@
+---
+title: Alert
+description: Migration guide for Alert from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Alert documentation](/docs/react/components/alert) for complete API reference, styling guide, and advanced examples.  This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Alert` was a single component that accepted props for title, description, icon, and other elements:
+
+```tsx
+import { Alert } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Alert 
+      title="This is an alert"
+      description="Thanks for subscribing to our newsletter!"
+    />
+  );
+}
+```
+
+In v3, Alert uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Alert } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Alert>
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>This is an alert</Alert.Title>
+        <Alert.Description>
+          Thanks for subscribing to our newsletter!
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Alert` component with props  
+**v3:** Compound components: `Alert`, `Alert.Indicator`, `Alert.Content`, `Alert.Title`, `Alert.Description`
+
+### 2. Color/Status Props
+
+| v2 Color | v3 Status | Notes |
+|----------|----------|-------|
+| `default` | `default` | Same |
+| `primary` | `accent` | Renamed |
+| `secondary` | `default` | Use `default` status |
+| `success` | `success` | Same |
+| `warning` | `warning` | Same |
+| `danger` | `danger` | Same |
+
+### 3. Variants Removed
+
+**v2 Variants:** `solid`, `bordered`, `flat`, `faded`  
+**v3:** No variant prop - use Tailwind CSS classes to achieve similar effects
+
+To achieve v2 variant styles in v3:
+- **v2 `solid`** → v3 `status` + add background color classes
+- **v2 `bordered`** → v3 `status` + add `border` classes
+- **v2 `flat`** → v3 default (no additional classes needed)
+- **v2 `faded`** → v3 `status` + add opacity/background classes
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `variant` | - | Removed (use Tailwind CSS) |
+| `radius` | - | Removed (use Tailwind e.g. `rounded-lg`) |
+| `startContent` | - | Place content before `<Alert.Indicator />` |
+| `endContent` | - | Place content after `<Alert.Content />` |
+| `hideIcon` | - | Omit `<Alert.Indicator />` |
+| `hideIconWrapper` | - | Removed (no wrapper in v3) |
+| `icon` | `Alert.Indicator` | Render icon as child of `<Alert.Indicator />` |
+| `isVisible`, `isDefaultVisible`, `onVisibleChange` | - | Removed (handle with conditional rendering) |
+| `isClosable`, `onClose`, `closeButtonProps` | - | Removed (add `CloseButton` manually) |
+| `title` | `Alert.Title` | Use `<Alert.Title>` inside `<Alert.Content>` |
+| `description` | `Alert.Description` | Use `<Alert.Description>` inside `<Alert.Content>` |
+
+### 5. Icon Handling
+
+**v2:** Used `icon` prop or `hideIcon` prop  
+**v3:** Use `<Alert.Indicator />` with custom children or omit it entirely
+
+## Migration Examples
+
+### Icon Handling
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from '@iconify/react';
+
+    {/* With custom icon */}
+    <Alert 
+      icon={<Icon icon="gravity-ui:box" />}
+      title="Custom Icon Alert"
+    />
+    
+    {/* Without icon */}
+    <Alert hideIcon title="No Icon Alert" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from '@iconify/react';
+
+    {/* With custom icon */}
+    <Alert>
+      <Alert.Indicator>
+        <Icon icon="gravity-ui:box" />
+      </Alert.Indicator>
+      <Alert.Content>
+        <Alert.Title>Custom Icon Alert</Alert.Title>
+      </Alert.Content>
+    </Alert>
+    
+    {/* Without icon */}
+    <Alert>
+      <Alert.Content>
+        <Alert.Title>No Icon Alert</Alert.Title>
+      </Alert.Content>
+    </Alert>
+    ```
+  </Tab>
+</Tabs>
+
+### With Action Button (End Content)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Alert, Button } from "@heroui/react";
+
+    <Alert
+      title="You have no credits left"
+      description="Upgrade to a paid plan to continue"
+      endContent={
+        <Button color="warning" size="sm" variant="flat">
+          Upgrade
+        </Button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Alert, Button } from "@heroui/react";
+
+    <Alert status="warning">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>You have no credits left</Alert.Title>
+        <Alert.Description>
+          Upgrade to a paid plan to continue
+        </Alert.Description>
+        <Button className="mt-2" size="sm" variant="primary">
+          Upgrade
+        </Button>
+      </Alert.Content>
+    </Alert>
+    ```
+  </Tab>
+</Tabs>
+
+### Closable Alert
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Alert
+      title="Closable Alert"
+      isClosable
+      onClose={() => console.log("Closed")}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Alert, CloseButton } from "@heroui/react";
+    import { useState } from "react";
+
+    const [isVisible, setIsVisible] = useState(true);
+
+    {isVisible && (
+      <Alert>
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Closable Alert</Alert.Title>
+        </Alert.Content>
+        <CloseButton 
+          aria-label="Close"
+          onPress={() => setIsVisible(false)}
+        />
+      </Alert>
+    )}
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Alert 
+  classNames={{
+    base: "custom-base",
+    title: "custom-title",
+    description: "custom-description"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Alert className="custom-base">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title className="custom-title">Title</Alert.Title>
+    <Alert.Description className="custom-description">
+      Description
+    </Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+## Component Anatomy
+
+The v3 Alert follows this structure:
+
+```
+Alert (Root)
+  ├── Alert.Indicator (optional)
+  ├── Alert.Content (optional)
+  │   ├── Alert.Title (optional)
+  │   └── Alert.Description (optional)
+  └── [Additional content like buttons, close button, etc.] (optional)
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components instead of props
+2. **Color → Status**: `color` prop renamed to `status`, `primary` → `accent`, `secondary` → `default`
+3. **Variants Removed**: No `variant` prop; use Tailwind CSS classes
+4. **Radius Removed**: No `radius` prop; use Tailwind CSS classes
+5. **No Built-in Close Button**: Must add `CloseButton` manually
+6. **No Visibility Control**: Handle visibility with conditional rendering
+7. **No Start/End Content Props**: Place content directly in the component tree
+8. **Icon Handling**: Use `<Alert.Indicator />` with children or omit it
diff --git a/apps/docs/content/docs/en/react/migration/(components)/autocomplete.mdx b/apps/docs/content/docs/en/react/migration/(components)/autocomplete.mdx
new file mode 100644
index 0000000..9bb16fc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/autocomplete.mdx
@@ -0,0 +1,584 @@
+---
+title: Autocomplete
+description: Migration guide for Autocomplete from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  In v3, the v2 `Autocomplete` can be migrated to either the [v3 Autocomplete](/docs/react/components/autocomplete) or the [v3 ComboBox](/docs/react/components/combo-box), depending on your use case. See the section below on choosing the right component. This guide focuses on migrating from HeroUI v2.
+</Callout>
+
+## Choosing Between Autocomplete and ComboBox
+
+V3 provides two components that replace the v2 Autocomplete:
+
+| Component | Best For | Input Style | Built on |
+|-----------|----------|-------------|----------|
+| **Autocomplete** | Select-style picker with a search/filter field inside the popover | Button trigger that shows selected value; search input inside popover | React Aria `Select` + `Autocomplete` |
+| **ComboBox** | Text input that filters a dropdown list as you type | Inline text input with dropdown trigger | React Aria `ComboBox` |
+
+**Use Autocomplete** when the user picks from a predefined list and the search field should appear inside the dropdown (similar to a searchable select).
+
+**Use ComboBox** when the user types directly into a visible input field to filter or search options (similar to v2 behavior).
+
+## Structure Changes
+
+In v2, Autocomplete was a single component that wrapped Input internally:
+
+```tsx
+import { Autocomplete, AutocompleteItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Autocomplete label="Select an animal">
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+  );
+}
+```
+
+### Migrating to v3 ComboBox (closest to v2 behavior)
+
+ComboBox provides the most similar experience to the v2 Autocomplete, with an inline text input that filters options:
+
+```tsx
+import { ComboBox, Input, Label, ListBox } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ComboBox>
+      <Label>Select an animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
+```
+
+### Migrating to v3 Autocomplete (searchable select)
+
+Autocomplete provides a select-style trigger with a search/filter field inside the popover:
+
+```tsx
+import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+export default function App() {
+  const { contains } = useFilter({ sensitivity: "base" });
+
+  return (
+    <Autocomplete>
+      <Label>Select an animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Two Replacement Components
+
+**v2:** `Autocomplete` (single component)
+**v3:** `ComboBox` (inline input + dropdown) or `Autocomplete` (select-style with search in popover)
+
+### 2. Component Structure
+
+**v2:** Single component with internal Input
+**v3 ComboBox:** Compound components (`ComboBox.InputGroup`, `ComboBox.Trigger`, `ComboBox.Popover`)
+**v3 Autocomplete:** Compound components (`Autocomplete.Trigger`, `Autocomplete.Value`, `Autocomplete.ClearButton`, `Autocomplete.Indicator`, `Autocomplete.Popover`, `Autocomplete.Filter`)
+
+### 3. Item Components
+
+**v2:** `AutocompleteItem`, `AutocompleteSection`
+**v3:** `ListBox.Item`, `ListBox.Section` (from ListBox component)
+
+### 4. Item Identification
+
+**v2:** React's `key` was used for both list reconciliation and item identity (selection).
+**v3:** Use `id` and `textValue` on `ListBox.Item` (state and accessibility); keep React's `key` on items in lists.
+
+### 5. Autocomplete-Specific Subcomponents (v3)
+
+The v3 Autocomplete introduces several subcomponents not present in v2:
+
+| Subcomponent | Purpose |
+|--------------|---------|
+| `Autocomplete.Trigger` | The button group that opens the popover |
+| `Autocomplete.Value` | Displays the currently selected value or placeholder |
+| `Autocomplete.ClearButton` | Clears the current selection |
+| `Autocomplete.Indicator` | Dropdown chevron icon (rotates when open) |
+| `Autocomplete.Popover` | The dropdown popover container |
+| `Autocomplete.Filter` | Wraps `SearchField` and `ListBox` to enable filtering; accepts a `filter` function, `inputValue`, and `onInputChange` |
+
+### 6. SearchField Integration
+
+The v3 Autocomplete uses `SearchField` inside `Autocomplete.Filter` for the search input within the popover:
+
+```tsx
+<Autocomplete.Filter filter={contains}>
+  <SearchField>
+    <SearchField.Group>
+      <SearchField.SearchIcon />
+      <SearchField.Input placeholder="Search..." />
+    </SearchField.Group>
+  </SearchField>
+  <ListBox>...</ListBox>
+</Autocomplete.Filter>
+```
+
+`SearchField` has its own subcomponents: `SearchField.Group`, `SearchField.Input`, `SearchField.SearchIcon`, and `SearchField.ClearButton`.
+
+### 7. useFilter Hook
+
+The v3 Autocomplete uses the `useFilter` hook (from React Aria, re-exported by `@heroui/react`) to provide locale-aware filtering functions:
+
+```tsx
+import { useFilter } from "@heroui/react";
+
+const { contains } = useFilter({ sensitivity: "base" });
+
+// Pass to Autocomplete.Filter
+<Autocomplete.Filter filter={contains}>
+  ...
+</Autocomplete.Filter>
+```
+
+The hook returns `contains`, `startsWith`, and `endsWith` functions. The `sensitivity` option controls locale-aware matching (`"base"`, `"accent"`, `"case"`, `"variant"`).
+
+### 8. Prop Changes (ComboBox)
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| - | `id` (on ListBox.Item) | Item identifier for state |
+| - | `textValue` (on ListBox.Item) | For accessibility (type-ahead) |
+| `label` | `Label` | Use `Label` component |
+| `description` | `Description` | Use `Description` component |
+| `placeholder` | `Input` | `placeholder` on Input |
+| `selectedKey`, `onSelectionChange`, `inputValue`, `onInputChange` | `ComboBox` | Same |
+| `allowsCustomValue`, `allowsEmptyCollection`, `defaultFilter` | `ComboBox` | Same |
+| `disabledKeys`, `isDisabled`, `isRequired`, `isInvalid`, `name` | `ComboBox` | Same |
+| `menuTrigger` | `ComboBox` | `"focus"` (default), `"input"`, or `"manual"` |
+| `variant`, `color`, `size`, `radius` | - | Removed (use Tailwind CSS) |
+| `labelPlacement` | - | Removed (use Label positioning) |
+| `startContent`, `endContent` | - | Add to Input or InputGroup |
+| `selectorIcon`, `clearIcon` | - | Customize ComboBox.Trigger or implement manually |
+| `isClearable` | - | Implement manually |
+| `showScrollIndicators` | - | Removed |
+| `classNames` | - | Use `className` on parts |
+| `popoverProps`, `listboxProps`, `inputProps` | - | Configure components directly |
+| `scrollShadowProps`, `scrollRef` | - | Removed |
+| `selectorButtonProps`, `clearButtonProps`, `disableSelectorIconRotation` | - | Removed |
+| `isReadOnly` | `ComboBox` | `isReadOnly` prop on ComboBox |
+| `fullWidth` | `ComboBox` | `fullWidth` prop on ComboBox |
+| `isVirtualized`, `maxListboxHeight`, `itemHeight` | - | Removed |
+| `onClose`, `onClear` | - | Use other event handlers |
+| `validationBehavior`, `validate` | `ComboBox` | Props on ComboBox |
+
+### 9. Prop Changes (Autocomplete)
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| - | `id` (on ListBox.Item) | Item identifier for state |
+| - | `textValue` (on ListBox.Item) | For accessibility (type-ahead) |
+| `label` | `Label` | Use `Label` component |
+| `description` | `Description` | Use `Description` component |
+| `placeholder` | `Autocomplete` | `placeholder` prop on root |
+| `selectedKey` / `onSelectionChange` | `value` / `onChange` | Renamed props on Autocomplete |
+| `selectionMode` | `Autocomplete` | `"single"` (default) or `"multiple"` |
+| `inputValue`, `onInputChange` | `Autocomplete.Filter` | `inputValue` and `onInputChange` on Filter |
+| `disabledKeys`, `isDisabled`, `isRequired`, `isInvalid`, `name` | `Autocomplete` | Same |
+| `variant`, `color`, `size`, `radius` | - | Removed (use Tailwind CSS); `variant` supports `"primary"` / `"secondary"` |
+| `isClearable` | `Autocomplete.ClearButton` | Built-in subcomponent |
+| `selectorIcon` | `Autocomplete.Indicator` | Pass custom icon as children |
+| `onClear` | `Autocomplete` | `onClear` prop on root |
+| `fullWidth` | `Autocomplete` | `fullWidth` prop on root |
+| `classNames` | - | Use `className` on parts |
+| `popoverProps`, `listboxProps`, `inputProps` | - | Configure components directly |
+
+## Migration Examples
+
+### Controlled Selection (ComboBox)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selectedKey, setSelectedKey] = useState("cat");
+
+    <Autocomplete
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+      label="Animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+
+    const [selectedKey, setSelectedKey] = useState<Key | null>("cat");
+
+    <ComboBox
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+    >
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled Selection (Autocomplete)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selectedKey, setSelectedKey] = useState("cat");
+
+    <Autocomplete
+      selectedKey={selectedKey}
+      onSelectionChange={setSelectedKey}
+      label="Animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+    import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+    const [value, setValue] = useState<Key | Key[] | null>("cat");
+    const { contains } = useFilter({ sensitivity: "base" });
+
+    <Autocomplete value={value} onChange={setValue}>
+      <Label>Animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              <Label>Cat</Label>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              <Label>Dog</Label>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+    ```
+  </Tab>
+</Tabs>
+
+### With Sections
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Autocomplete label="Country">
+      <AutocompleteSection title="North America">
+        <AutocompleteItem key="usa">United States</AutocompleteItem>
+        <AutocompleteItem key="canada">Canada</AutocompleteItem>
+      </AutocompleteSection>
+      <AutocompleteSection title="Europe">
+        <AutocompleteItem key="uk">United Kingdom</AutocompleteItem>
+      </AutocompleteSection>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Separator } from "@heroui/react";
+
+    <ComboBox>
+      <Label>Country</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search countries..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+### With useFilter (Autocomplete)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 handled filtering internally */}
+    <Autocomplete label="Animal">
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+      <AutocompleteItem key="dog">Dog</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Autocomplete, Label, SearchField, ListBox, useFilter } from "@heroui/react";
+
+    function FilterExample() {
+      const { contains } = useFilter({ sensitivity: "base" });
+
+      return (
+        <Autocomplete>
+          <Label>Animal</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField>
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search..." />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox>
+                <ListBox.Item id="cat" textValue="Cat">
+                  <Label>Cat</Label>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="dog" textValue="Dog">
+                  <Label>Dog</Label>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Required field */}
+    <Autocomplete label="Animal" isRequired>
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+    </Autocomplete>
+
+    {/* With error message */}
+    <Autocomplete
+      label="Animal"
+      isInvalid
+      errorMessage="Please select an animal"
+    >
+      <AutocompleteItem key="cat">Cat</AutocompleteItem>
+    </Autocomplete>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { FieldError, Form } from "@heroui/react";
+
+    {/* Required field */}
+    <Form>
+      <ComboBox isRequired name="animal">
+        <Label>Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+    </Form>
+
+    {/* With error message */}
+    <ComboBox isInvalid>
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <FieldError>Please select an animal</FieldError>
+    </ComboBox>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+### ComboBox Anatomy
+
+```
+ComboBox (Root)
+  ├── Label
+  ├── ComboBox.InputGroup
+  │   ├── Input
+  │   └── ComboBox.Trigger
+  ├── Description (optional)
+  ├── ComboBox.Popover
+  │   └── ListBox
+  │       ├── ListBox.Item
+  │       │   ├── [Content]
+  │       │   └── ListBox.ItemIndicator (optional)
+  │       └── ListBox.Section (optional)
+  │           ├── Header
+  │           └── ListBox.Item
+  └── FieldError (optional)
+```
+
+### Autocomplete Anatomy
+
+```
+Autocomplete (Root)
+  ├── Label
+  ├── Autocomplete.Trigger
+  │   ├── Autocomplete.Value
+  │   ├── Autocomplete.ClearButton
+  │   └── Autocomplete.Indicator
+  ├── Description (optional)
+  ├── Autocomplete.Popover
+  │   └── Autocomplete.Filter
+  │       ├── SearchField
+  │       │   └── SearchField.Group
+  │       │       ├── SearchField.SearchIcon
+  │       │       └── SearchField.Input
+  │       └── ListBox
+  │           ├── ListBox.Item
+  │           │   ├── [Content]
+  │           │   └── ListBox.ItemIndicator (optional)
+  │           └── ListBox.Section (optional)
+  │               ├── Header
+  │               └── ListBox.Item
+  └── FieldError (optional)
+```
+
+## Summary
+
+1. **Two Replacement Components**: v2 `Autocomplete` can be migrated to v3 `ComboBox` (inline input) or v3 `Autocomplete` (searchable select with filter in popover)
+2. **Component Structure**: Single component with props becomes compound components with explicit subcomponents
+3. **Item Components**: `AutocompleteItem` becomes `ListBox.Item`; `AutocompleteSection` becomes `ListBox.Section`
+4. **Item Identity**: Use `id` and `textValue` on items; keep React's `key` for list reconciliation
+5. **Input**: v3 ComboBox requires explicit `Input`; v3 Autocomplete uses `SearchField` inside `Autocomplete.Filter`
+6. **Label/Description**: Props become separate `Label` and `Description` components
+7. **Filtering**: v3 Autocomplete uses `Autocomplete.Filter` with `useFilter` hook for locale-aware filtering; v3 ComboBox uses `defaultFilter` prop
+8. **Clear Button**: v3 Autocomplete has built-in `Autocomplete.ClearButton`; v3 ComboBox requires manual implementation
+9. **Selection Value Display**: v3 Autocomplete has `Autocomplete.Value` for displaying the selected value with render prop support
+10. **Styling Props Removed**: `color`, `size`, `radius` removed (use Tailwind CSS); `variant` now supports `"primary"` / `"secondary"`
+11. **ClassNames Object Removed**: Use `className` props on individual subcomponents
+12. **useFilter Hook**: New in v3, provides `contains`, `startsWith`, `endsWith` for locale-aware text matching
diff --git a/apps/docs/content/docs/en/react/migration/(components)/avatar.mdx b/apps/docs/content/docs/en/react/migration/(components)/avatar.mdx
new file mode 100644
index 0000000..055345c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/avatar.mdx
@@ -0,0 +1,357 @@
+---
+title: Avatar
+description: Migration guide for Avatar from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Avatar documentation](/docs/react/components/avatar) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Avatar` was a single component that accepted props for image source, name, fallback, and other elements:
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Avatar 
+      src="https://example.com/avatar.jpg"
+      name="John Doe"
+      showFallback
+    />
+  );
+}
+```
+
+In v3, Avatar uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Avatar>
+      <Avatar.Image src="https://example.com/avatar.jpg" alt="John Doe" />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Avatar` component with props  
+**v3:** Compound components: `Avatar`, `Avatar.Image`, `Avatar.Fallback`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `src` | `Avatar.Image` | Use `<Avatar.Image src="..." />` |
+| `name` | - | Generate initials and pass to `<Avatar.Fallback />` |
+| `showFallback` | - | Removed (fallback shown if image fails or not provided) |
+| `fallback`, `icon` | `Avatar.Fallback` | Place content in `<Avatar.Fallback />` |
+| `color` | `Avatar` | Same; `primary` → `accent`, `secondary` → `default` |
+| `variant` | `Avatar` | New in v3; `"default"` \| `"soft"` |
+| `size` | `Avatar` | Same |
+| `isBordered` | - | Removed (use Tailwind e.g. `ring-2 ring-background`) |
+| `radius` | - | Removed (use Tailwind e.g. `rounded-full`) |
+| `isDisabled`, `isFocusable` | - | Removed (use Tailwind / `asChild` if needed) |
+| `getInitials` | - | Generate initials manually |
+| `ImgComponent`, `imgProps` | - | Use `asChild` on `Avatar.Image` if needed |
+| `onError` | `Avatar.Image` | Use `onError` on `<Avatar.Image />` |
+| - | `Avatar.Image` | New: `srcSet`, `sizes`, `loading` for responsive images |
+| - | `Avatar.Fallback` | New: `delayMs` to delay fallback display (prevents flash) |
+| `classNames` | - | Use `className` on parts |
+| AvatarGroup | - | No v3 equivalent; create groups with CSS |
+
+### 3. Variant Prop (New in v3)
+
+**v2:** No `variant` prop; styling controlled only through `color`
+**v3:** New `variant` prop with `"default"` and `"soft"` options. The `"soft"` variant applies a lighter background style.
+
+```tsx
+<Avatar variant="soft" color="accent">
+  <Avatar.Image src="..." alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 4. Avatar.Image Responsive Attributes (New in v3)
+
+**v2:** Limited to `src` and `onError`
+**v3:** `Avatar.Image` now supports `srcSet`, `sizes`, and `loading` for responsive image handling
+
+```tsx
+<Avatar>
+  <Avatar.Image
+    src="avatar-400.jpg"
+    srcSet="avatar-200.jpg 200w, avatar-400.jpg 400w"
+    sizes="(max-width: 600px) 200px, 400px"
+    loading="lazy"
+    alt="User"
+  />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 5. Avatar.Fallback `delayMs` Prop (New in v3)
+
+**v2:** Fallback shown immediately or controlled via `showFallback`
+**v3:** `Avatar.Fallback` supports a `delayMs` prop to delay rendering, preventing flash of fallback content when images load quickly
+
+```tsx
+<Avatar>
+  <Avatar.Image src="..." alt="User" />
+  <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+</Avatar>
+```
+
+### 6. Image and Fallback Handling
+
+**v2:** Used `src`, `name`, `showFallback`, and `fallback` props  
+**v3:** Must explicitly render `<Avatar.Image />` and `<Avatar.Fallback />` components
+
+### 7. Color Props
+
+| v2 Color | v3 Color | Notes |
+|----------|---------|-------|
+| `default` | `default` | Same |
+| `primary` | `accent` | Renamed |
+| `secondary` | `default` | Use `default` color |
+| `success` | `success` | Same |
+| `warning` | `warning` | Same |
+| `danger` | `danger` | Same |
+
+### 8. AvatarGroup Removed
+
+**v2:** Had a dedicated `AvatarGroup` component  
+**v3:** No `AvatarGroup` component - create groups manually with CSS classes
+
+## Migration Examples
+
+### Sizes and Colors
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Avatar size="md" color="primary" src="..." name="John" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Avatar size="md" color="accent">
+      <Avatar.Image src="..." alt="John" />
+      <Avatar.Fallback>J</Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Fallback
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Avatar 
+      src="https://broken-url.com/image.jpg"
+      showFallback
+      fallback={<Icon icon="mdi:account" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Avatar>
+      <Avatar.Image 
+        src="https://broken-url.com/image.jpg" 
+        alt="User"
+      />
+      <Avatar.Fallback>
+        <Icon icon="mdi:account" />
+      </Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+### Avatar Group
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar, AvatarGroup } from "@heroui/react";
+
+    <AvatarGroup isBordered>
+      <Avatar src="https://example.com/1.jpg" />
+      <Avatar src="https://example.com/2.jpg" />
+      <Avatar src="https://example.com/3.jpg" />
+    </AvatarGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <div className="flex -space-x-2">
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/1.jpg" alt="User 1" />
+        <Avatar.Fallback>U1</Avatar.Fallback>
+      </Avatar>
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/2.jpg" alt="User 2" />
+        <Avatar.Fallback>U2</Avatar.Fallback>
+      </Avatar>
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Image src="https://example.com/3.jpg" alt="User 3" />
+        <Avatar.Fallback>U3</Avatar.Fallback>
+      </Avatar>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Avatar Group with Max Count
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar, AvatarGroup } from "@heroui/react";
+
+    <AvatarGroup max={3}>
+      <Avatar src="https://example.com/1.jpg" />
+      <Avatar src="https://example.com/2.jpg" />
+      <Avatar src="https://example.com/3.jpg" />
+      <Avatar src="https://example.com/4.jpg" />
+      <Avatar src="https://example.com/5.jpg" />
+    </AvatarGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    const users = [
+      { id: 1, src: "https://example.com/1.jpg", name: "User 1" },
+      { id: 2, src: "https://example.com/2.jpg", name: "User 2" },
+      { id: 3, src: "https://example.com/3.jpg", name: "User 3" },
+      { id: 4, src: "https://example.com/4.jpg", name: "User 4" },
+      { id: 5, src: "https://example.com/5.jpg", name: "User 5" },
+    ];
+
+    <div className="flex -space-x-2">
+      {users.slice(0, 3).map((user) => (
+        <Avatar key={user.id} className="ring-2 ring-background">
+          <Avatar.Image src={user.src} alt={user.name} />
+          <Avatar.Fallback>
+            {user.name.split(" ").map(n => n[0]).join("")}
+          </Avatar.Fallback>
+        </Avatar>
+      ))}
+      <Avatar className="ring-2 ring-background">
+        <Avatar.Fallback className="border-none">
+          +{users.length - 3}
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have variants, but uses color prop */}
+    <Avatar color="primary" name="John" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 has variant prop */}
+    <Avatar variant="soft" color="accent">
+      <Avatar.Fallback>J</Avatar.Fallback>
+    </Avatar>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Avatar 
+  classNames={{
+    base: "custom-base",
+    img: "custom-img",
+    fallback: "custom-fallback"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Avatar className="custom-base">
+  <Avatar.Image className="custom-img" src="..." alt="..." />
+  <Avatar.Fallback className="custom-fallback">
+    JD
+  </Avatar.Fallback>
+</Avatar>
+```
+
+## Component Anatomy
+
+The v3 Avatar follows this structure:
+
+```
+Avatar (Root)
+  ├── Avatar.Image (optional)
+  └── Avatar.Fallback (optional; shown when image fails or not provided)
+```
+
+## Helper Function for Initials
+
+Since v3 doesn't have a `name` prop, you'll need to generate initials manually:
+
+```tsx
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .map(n => n[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+// Usage
+<Avatar>
+  <Avatar.Fallback>{getInitials("John Doe")}</Avatar.Fallback>
+</Avatar>
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Avatar.Image`, `Avatar.Fallback`)
+2. **Name Prop Removed**: Generate initials manually
+3. **ShowFallback Removed**: Fallback always shows if image fails
+4. **Variant Prop Added**: New `variant` prop (`"default"` | `"soft"`) for visual style control
+5. **Responsive Image Support**: `Avatar.Image` now supports `srcSet`, `sizes`, and `loading` attributes
+6. **Fallback Delay**: `Avatar.Fallback` supports `delayMs` to prevent flash of fallback content
+7. **Color Mapping**: `primary` → `accent`, `secondary` → `default`
+8. **Bordered Removed**: Use Tailwind `ring-2 ring-background` classes
+9. **Radius Removed**: Use Tailwind `rounded-*` classes
+10. **Disabled Removed**: Use Tailwind `opacity-50` classes
+11. **AvatarGroup Removed**: Create groups manually with CSS
+12. **Icon Prop Removed**: Place icon content in `Avatar.Fallback`
+13. **ClassNames Removed**: Use `className` props on individual components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/badge.mdx b/apps/docs/content/docs/en/react/migration/(components)/badge.mdx
new file mode 100644
index 0000000..9a3e6fa
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/badge.mdx
@@ -0,0 +1,275 @@
+---
+title: Badge
+description: Migration guide for Badge from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Badge documentation](/docs/react/components/badge) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Badge` was a wrapper component that positioned content relative to its children:
+
+```tsx
+import { Badge, Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Badge content="5" color="primary">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+  );
+}
+```
+
+In v3, Badge uses a compound component pattern with `Badge.Anchor` for positioning:
+
+```tsx
+import { Badge, Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="accent">5</Badge>
+    </Badge.Anchor>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Badge` component wrapping children, with `content` prop for badge text
+**v3:** Compound components: `Badge.Anchor` (positioning wrapper), `Badge` (the badge itself), `Badge.Label` (text slot, auto-wrapped for strings)
+
+### 2. Variants
+
+**v2:** `solid`, `flat`, `faded`, `shadow`
+**v3:** `primary`, `secondary`, `soft`
+
+### 3. Colors
+
+**v2:** `default`, `primary`, `secondary`, `success`, `warning`, `danger`
+**v3:** `default`, `accent`, `success`, `warning`, `danger`
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `content` | `Badge` children | Content is now passed as children |
+| `children` | `Badge.Anchor` | The anchored element goes inside `Badge.Anchor` |
+| `variant` | `Badge` | Values changed (see variant mapping) |
+| `color` | `Badge` | `primary` → `accent`, `secondary` removed |
+| `size` | `Badge` | Same (`sm`, `md`, `lg`) |
+| `placement` | `Badge` | Same (`top-right`, `top-left`, `bottom-right`, `bottom-left`) |
+| `shape` | - | Removed (use Tailwind CSS) |
+| `showOutline` | - | Removed (use Tailwind CSS e.g. `border-2`) |
+| `disableOutline` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `isInvisible` | - | Removed (use conditional rendering) |
+| `isOneChar` | - | Removed (use Tailwind CSS) |
+| `isDot` | - | Omit children to render as dot |
+| `classNames` | - | Use `className` on individual components |
+
+### 5. Variant Mapping
+
+| v2 Variant | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| `solid` | `primary` | Filled background |
+| `flat` | `soft` | Light background |
+| `faded` | `secondary` | Border with background |
+| `shadow` | `primary` | Use Tailwind `shadow-*` classes |
+
+### 6. Color Mapping
+
+| v2 Color | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `default` | `default` | Same |
+| `primary` | `accent` | Renamed |
+| `secondary` | `default` or `accent` | Depends on context |
+| `success` | `success` | Same |
+| `warning` | `warning` | Same |
+| `danger` | `danger` | Same |
+
+## Migration Examples
+
+### Basic Badge
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Badge, Avatar } from "@heroui/react";
+
+    <Badge content="5" color="primary">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Badge, Avatar } from "@heroui/react";
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="accent">5</Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### Dot Badge
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Badge content="" isDot color="success">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="success" />
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### Placement
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Badge content="5" placement="bottom-right" color="danger">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge placement="bottom-right" color="danger">5</Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### Visibility Toggle
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [isInvisible, setIsInvisible] = useState(false);
+
+    <Badge content="5" isInvisible={isInvisible} color="danger">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [isVisible, setIsVisible] = useState(true);
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      {isVisible && <Badge color="danger">5</Badge>}
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icon Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Badge content={<Icon icon="gravity-ui:check" />} color="success">
+      <Avatar src="https://i.pravatar.cc/300" />
+    </Badge>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Badge.Anchor>
+      <Avatar>
+        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />
+        <Avatar.Fallback>U</Avatar.Fallback>
+      </Avatar>
+      <Badge color="success">
+        <Icon icon="gravity-ui:check" />
+      </Badge>
+    </Badge.Anchor>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Badge
+  classNames={{
+    base: "custom-base",
+    badge: "custom-badge"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Badge.Anchor className="custom-anchor">
+  <Avatar />
+  <Badge className="custom-badge">
+    <Badge.Label className="custom-label">5</Badge.Label>
+  </Badge>
+</Badge.Anchor>
+```
+
+## Component Anatomy
+
+The v3 Badge follows this structure:
+
+```
+Badge.Anchor (positioning wrapper)
+  ├── [Anchored element: Avatar, Button, etc.]
+  └── Badge (the badge indicator)
+      └── Badge.Label (auto-wrapped for string/number children)
+```
+
+## Summary
+
+1. **Component Structure**: `Badge` wrapping children → `Badge.Anchor` + `Badge` as siblings
+2. **Content Prop Removed**: `content` prop → pass content as `Badge` children
+3. **Dot Badge**: `isDot` prop → omit children
+4. **Visibility**: `isInvisible` prop → conditional rendering
+5. **Variants Reduced**: From 4 to 3 variants (`primary`, `secondary`, `soft`)
+6. **Color Changes**: `primary` → `accent`, `secondary` removed
+7. **Removed Props**: `shape`, `showOutline`, `disableAnimation`, `isOneChar` — use Tailwind CSS
+8. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/breadcrumbs.mdx b/apps/docs/content/docs/en/react/migration/(components)/breadcrumbs.mdx
new file mode 100644
index 0000000..7ad34f8
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/breadcrumbs.mdx
@@ -0,0 +1,142 @@
+---
+title: Breadcrumbs
+description: Migration guide for Breadcrumbs from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Breadcrumbs documentation](/docs/react/components/breadcrumbs) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Breadcrumbs` accepted an `items` prop or children:
+
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Breadcrumbs>
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem href="#">Products</BreadcrumbItem>
+      <BreadcrumbItem>Current Page</BreadcrumbItem>
+    </Breadcrumbs>
+  );
+}
+```
+
+In v3, Breadcrumbs uses a compound component pattern with `Breadcrumbs` and `BreadcrumbsItem`:
+
+```tsx
+import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Breadcrumbs>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
+      <BreadcrumbsItem>Current Page</BreadcrumbsItem>
+    </Breadcrumbs>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Name: `BreadcrumbItem` → `BreadcrumbsItem`
+
+**v2:** Used `BreadcrumbItem` (singular)  
+**v3:** Uses `BreadcrumbsItem` (plural)
+
+### 2. Separator Customization
+
+**v2:** Separator was customizable via props  
+**v3:** Separator is customizable via `separator` prop on `Breadcrumbs` root
+
+### 3. Built-in Link Component
+
+**v2:** Items could be links or text  
+**v3:** Items automatically use the `Link` component when `href` is provided
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `maxItems` | - | Removed (render all items or implement collapse manually) |
+| `itemsBeforeCollapse`, `itemsAfterCollapse`, `renderEllipsis` | - | Removed (collapse/ellipsis removed with maxItems) |
+| `items` (prop pattern) | - | Use children instead |
+| `onAction` | - | Use `onPress` on individual items if needed |
+| `isDisabled` | `isDisabled` on root | Now supported on root - disables all breadcrumb links at once |
+| `classNames`, `itemClasses` | - | Use `className` on Breadcrumbs and BreadcrumbsItem |
+
+### 5. `isDisabled` Prop on Root
+
+**v2:** `isDisabled` was not available on the root component
+**v3:** `isDisabled` is supported on the `Breadcrumbs` root, disabling all breadcrumb links at once
+
+### 6. Automatic `aria-current="page"` Behavior
+
+**v3:** The last breadcrumb item (the one without `href`) automatically receives `aria-current="page"`, indicating the current page to assistive technologies. No manual configuration is needed.
+
+### 7. React Aria Components Integration
+
+**v3:** Built on React Aria Components for better accessibility and keyboard navigation support
+
+## Migration Examples
+
+### Custom Separator
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Breadcrumbs separator="/">
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem>Current</BreadcrumbItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";
+
+    <Breadcrumbs separator={<Icon icon="gravity-ui:caret-right" />}>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem>Current</BreadcrumbsItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+</Tabs>
+
+### Disabled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not support isDisabled on the root */}
+    <Breadcrumbs>
+      <BreadcrumbItem href="#">Home</BreadcrumbItem>
+      <BreadcrumbItem>Current</BreadcrumbItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 supports isDisabled on root to disable all links */}
+    <Breadcrumbs isDisabled>
+      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+      <BreadcrumbsItem>Current</BreadcrumbsItem>
+    </Breadcrumbs>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+- Rename `BreadcrumbItem` to `BreadcrumbsItem`
+- Set `separator` on the root; it can be a string or a React element (e.g. an icon)
+- Items use the built-in Link when `href` is provided
+- `isDisabled` now supported on root to disable all breadcrumb links at once
+- The last item (without `href`) automatically gets `aria-current="page"` for accessibility
+- No `maxItems` / collapse in v3—show all items or implement yourself; use `className` instead of `classNames` / `itemClasses`
+- Built on React Aria Components for accessibility
diff --git a/apps/docs/content/docs/en/react/migration/(components)/button-group.mdx b/apps/docs/content/docs/en/react/migration/(components)/button-group.mdx
new file mode 100644
index 0000000..d79e594
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/button-group.mdx
@@ -0,0 +1,65 @@
+---
+title: ButtonGroup
+description: Migration guide for ButtonGroup from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 ButtonGroup documentation](/docs/react/components/button-group) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `ButtonGroup` grouped buttons together:
+
+```tsx
+import { ButtonGroup, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+In v3, `ButtonGroup` has the same basic structure but with enhanced prop inheritance:
+
+```tsx
+import { ButtonGroup, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Import Path
+
+**v2:** Imported from `@heroui/react`  
+**v3:** Imported from `@heroui/react` (same package, but unified import)
+
+### 2. Prop Inheritance
+
+**v2:** ButtonGroup passed `size`, `color`, `variant`, `radius`, `isIconOnly`, `isDisabled`, `disableAnimation`, `disableRipple`, and `fullWidth` to child buttons.
+
+**v3:** ButtonGroup passes `size`, `variant`, `isDisabled`, and `fullWidth` to child buttons. Props such as `color` and `radius` no longer exist on Button (replaced by `variant`); `disableAnimation` and `disableRipple` were removed from the design system.
+
+### 3. Hide Separator
+
+**v3:** New `hideSeparator` prop to hide visual separators between buttons.
+
+## Summary
+
+- Set `size`, `variant`, `isDisabled`, and `fullWidth` on ButtonGroup to apply to all child buttons (replace v2’s `color` + `variant` with v3’s single `variant`)
+- Use the new `hideSeparator` prop to hide separators between buttons
+- Structure stays the same; removed props (`radius`, `disableAnimation`, `disableRipple`) are no longer available on Button in v3
diff --git a/apps/docs/content/docs/en/react/migration/(components)/button.mdx b/apps/docs/content/docs/en/react/migration/(components)/button.mdx
new file mode 100644
index 0000000..3e86086
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/button.mdx
@@ -0,0 +1,356 @@
+---
+title: Button
+description: Migration guide for Button from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Button documentation](/docs/react/components/button) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Button` used a combination of `color` and `variant` props:
+
+```tsx
+import { Button } from "@heroui/react";
+
+export default function App() {
+  return <Button color="primary" variant="solid">Button</Button>;
+}
+```
+
+In v3, Button uses only the `variant` prop (no separate `color` prop):
+
+```tsx
+import { Button } from "@heroui/react";
+
+export default function App() {
+  return <Button variant="primary">Button</Button>;
+}
+```
+
+## Key Changes
+
+### 1. Variants and Colors
+
+**v2:** Used `color` + `variant` combination  
+**v3:** Uses `variant` only (no separate `color` prop)
+
+| v2 Color + Variant | v3 Variant | Notes |
+|-------------------|------------|-------|
+| `color="primary" variant="solid"` | `variant="primary"` | Default primary button |
+| `color="default" variant="solid"` | `variant="primary"` | Use primary variant |
+| `color="secondary" variant="solid"` | `variant="secondary"` | Same |
+| `color="success" variant="solid"` | `variant="primary"` | Use primary with custom styling if needed |
+| `color="warning" variant="solid"` | `variant="primary"` | Use primary with custom styling if needed |
+| `color="danger" variant="solid"` | `variant="danger"` | Danger variant available |
+| `color="primary" variant="bordered"` | `variant="secondary"` | Similar appearance |
+| `color="primary" variant="light"` | `variant="tertiary"` | Similar appearance |
+| `color="primary" variant="flat"` | `variant="tertiary"` | Similar appearance |
+| `color="primary" variant="faded"` | `variant="secondary"` | Similar appearance |
+| `color="primary" variant="ghost"` | `variant="ghost"` | Same |
+| `color="danger" variant="flat"` | `variant="danger-soft"` | New soft danger variant |
+
+**v2 Variants:** `solid`, `bordered`, `light`, `flat`, `faded`, `shadow`, `ghost`  
+**v3 Variants:** `primary`, `secondary`, `tertiary`, `outline`, `ghost`, `danger`, `danger-soft`
+
+### 2. Loading State: `isLoading` → `isPending`
+
+**v2:** Used `isLoading` prop  
+**v3:** Uses `isPending` prop
+
+### 3. Default Width Behavior
+
+**v2:** Buttons had minimum widths based on size (`min-w-16` for sm, `min-w-20` for md, `min-w-24` for lg)  
+**v3:** Buttons use `w-fit` by default (width fits content, no minimum width)
+
+This means v3 buttons will be narrower than v2 buttons when they have short text. To maintain v2's minimum width behavior, add Tailwind classes see the [Minimum Width](#minimum-width) example section.
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `isLoading` | `Button` | Renamed to `isPending` |
+| `isIconOnly` | `Button` | Still available in v3 — renders a square button with only an icon |
+| `color` | - | Removed (variants handle styling) |
+| `radius` | - | Removed (use Tailwind e.g. `rounded-lg`) |
+| `startContent`, `endContent` | - | Place icons as children |
+| `spinner`, `spinnerPlacement` | - | Handle loading manually with render props |
+| `disableRipple` | - | Removed (ripple removed in v3) |
+| `disableAnimation` | - | Removed (animations handled internally) |
+| `classNames` | - | Use `className` |
+
+### 5. ButtonGroup Available
+
+**v2:** Had a dedicated `ButtonGroup` component  
+**v3:** `ButtonGroup` continues to exist. See the [ButtonGroup migration guide](/docs/react/migration/button-group) for details.
+
+## Migration Examples
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button color="primary" variant="solid">Solid</Button>
+    <Button color="primary" variant="bordered">Bordered</Button>
+    <Button color="primary" variant="ghost">Ghost</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="ghost">Ghost</Button>
+    ```
+  </Tab>
+</Tabs>
+
+### Danger Soft Variant
+
+The `danger-soft` variant is new in v3. It replaces the v2 pattern of using a flat danger button.
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button color="danger" variant="flat">Delete</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Button variant="danger-soft">Delete</Button>
+    ```
+  </Tab>
+</Tabs>
+
+### Icon Only (`isIconOnly`)
+
+The `isIconOnly` prop is available in both v2 and v3. It renders a square button sized to fit a single icon. In v3, use `variant` instead of `color` for styling.
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button isIconOnly color="danger" variant="flat">
+      <HeartIcon />
+    </Button>
+    <Button isIconOnly color="primary" variant="bordered" size="sm">
+      <SearchIcon />
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button isIconOnly variant="danger-soft">
+      <Icon icon="gravity-ui:heart" />
+    </Button>
+    <Button isIconOnly variant="secondary" size="sm">
+      <Icon icon="gravity-ui:magnifier" />
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### Loading State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Simple loading */}
+    <Button isLoading color="primary">
+      Loading
+    </Button>
+    
+    {/* Loading with conditional content */}
+    <Button 
+      isLoading={isLoading}
+      spinnerPlacement="start"
+      color="primary"
+      onPress={() => setIsLoading(true)}
+    >
+      Upload File
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Spinner } from "@heroui/react";
+    import { Icon } from "@iconify/react";
+
+    const [isLoading, setIsLoading] = useState(false);
+
+    {/* Simple loading */}
+    <Button isPending={isLoading}>
+      {({isPending}) => (
+        <>
+          {isPending && <Spinner color="current" size="sm" />}
+          Loading
+        </>
+      )}
+    </Button>
+    
+    {/* Loading with conditional content */}
+    <Button 
+      isPending={isLoading}
+      onPress={() => setIsLoading(true)}
+    >
+      {({isPending}) => (
+        <>
+          {isPending ? (
+            <Spinner color="current" size="sm" />
+          ) : (
+            <Icon icon="gravity-ui:paperclip" />
+          )}
+          {isPending ? "Uploading..." : "Upload File"}
+        </>
+      )}
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button 
+      color="success" 
+      endContent={<Icon icon="gravity-ui:camera" />}
+    >
+      Take a photo
+    </Button>
+    <Button 
+      color="danger" 
+      startContent={<Icon icon="gravity-ui:trash-bin" />}
+      variant="bordered"
+    >
+      Delete user
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button variant="primary">
+      <Icon icon="gravity-ui:camera" />
+      Take a photo
+    </Button>
+    <Button variant="secondary">
+      <Icon icon="gravity-ui:trash-bin" />
+      Delete user
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### Icon Only Button
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Button isIconOnly color="danger">
+      <HeartIcon />
+    </Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Button isIconOnly variant="danger">
+      <Icon icon="gravity-ui:heart" />
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+### Button Group
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Button, ButtonGroup } from "@heroui/react";
+
+    <ButtonGroup size="sm" color="primary" variant="solid">
+      <Button>One</Button>
+      <Button>Two</Button>
+      <Button>Three</Button>
+    </ButtonGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, ButtonGroup } from "@heroui/react";
+
+    <ButtonGroup size="sm" variant="primary">
+      <Button>One</Button>
+      <Button>Two</Button>
+      <Button>Three</Button>
+    </ButtonGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Sizes and Minimum Width
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 automatically applies minimum widths */}
+    <Button size="md" color="primary">Save</Button>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* v3 uses w-fit by default - add min-width to match v2 */}
+    <Button size="md" variant="primary" className="min-w-20">
+      Save
+    </Button>
+    ```
+  </Tab>
+</Tabs>
+
+## Render Props Pattern
+
+v3 Button supports a render prop pattern that provides state information:
+
+```tsx
+<Button isPending={isLoading}>
+  {({isPending, isPressed, isHovered, isFocused, isFocusVisible, isDisabled}) => (
+    <>
+      {isPending && <Spinner size="sm" />}
+      {isPressed ? "Pressed!" : "Click me"}
+    </>
+  )}
+</Button>
+```
+
+Available render props:
+- `isPending` - Whether button is in loading state
+- `isPressed` - Whether button is currently pressed
+- `isHovered` - Whether button is hovered
+- `isFocused` - Whether button is focused
+- `isFocusVisible` - Whether button should show focus indicator
+- `isDisabled` - Whether button is disabled
+
+## Summary
+
+1. **Color Prop Removed**: Use `variant` prop instead of `color` + `variant`
+2. **Variants Changed**: New variant system (`primary`, `secondary`, `tertiary`, `outline`, `ghost`, `danger`, `danger-soft`)
+3. **`danger-soft` Variant**: New in v3, replaces v2's `color="danger" variant="flat"` pattern
+4. **isLoading → isPending**: Loading prop renamed
+5. **isIconOnly**: Still supported in v3 — renders a square button for icon-only use
+6. **Default Width Changed**: Buttons now use `w-fit` instead of minimum widths - add `min-w-*` classes to match v2 behavior
+7. **Icons**: `startContent`/`endContent` removed - place icons as children
+8. **Loading Spinner**: Must handle spinner manually with render props
+9. **Render Props**: v3 Button children can be a function receiving `isPending`, `isPressed`, `isHovered`, `isFocused`, `isFocusVisible`, and `isDisabled`
+10. **Radius Removed**: Use Tailwind CSS classes
+11. **Ripple Removed**: No ripple effect in v3
+12. **ButtonGroup Available**: See [ButtonGroup migration guide](/docs/react/migration/button-group)
+13. **ClassNames Removed**: Use `className` prop
diff --git a/apps/docs/content/docs/en/react/migration/(components)/calendar.mdx b/apps/docs/content/docs/en/react/migration/(components)/calendar.mdx
new file mode 100644
index 0000000..b867a5a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/calendar.mdx
@@ -0,0 +1,455 @@
+---
+title: Calendar
+description: Migration guide for Calendar from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Calendar documentation](/docs/react/components/calendar) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Calendar` was a single component configured entirely through props:
+
+```tsx
+import { Calendar } from "@heroui/react";
+
+export default function App() {
+  return <Calendar aria-label="Date" />;
+}
+```
+
+In v3, Calendar uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Calendar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Calendar aria-label="Date">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Calendar` component with all layout handled internally
+**v3:** Compound components: `Calendar.Header`, `Calendar.Heading`, `Calendar.NavButton`, `Calendar.Grid`, `Calendar.GridHeader`, `Calendar.GridBody`, `Calendar.HeaderCell`, `Calendar.Cell`, `Calendar.CellIndicator`
+
+### 2. Year Picker
+
+**v2:** Built-in month/year pickers via `showMonthAndYearPickers` prop
+**v3:** Dedicated compound components: `Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, `Calendar.YearPickerGridBody`, `Calendar.YearPickerCell`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `defaultValue` | `defaultValue` | Same |
+| `onChange` | `onChange` | Same |
+| `focusedValue` | `focusedValue` | Same |
+| `onFocusChange` | `onFocusChange` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isDateUnavailable` | `isDateUnavailable` | Same |
+| `isDisabled` | `isDisabled` | Same |
+| `isReadOnly` | `isReadOnly` | Same |
+| `isInvalid` | `isInvalid` | Same |
+| `visibleMonths` | `visibleDuration` | Changed to `{months: number}` object |
+| `showMonthAndYearPickers` | - | Use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid` |
+| `onHeaderExpandedChange` | `onYearPickerOpenChange` | Renamed |
+| `color` | - | Removed (use Tailwind CSS) |
+| `calendarWidth` | - | Removed (use `className` or Tailwind CSS) |
+| `weekdayStyle` | - | Removed |
+| `pageBehavior` | `pageBehavior` | Same |
+| `firstDayOfWeek` | - | Use `I18nProvider` locale instead |
+| `hideDisabledDates` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `topContent` | - | Place custom content inside `Calendar` before `Calendar.Grid` |
+| `bottomContent` | - | Place custom content inside `Calendar` after `Calendar.Grid` |
+| `classNames` | - | Use `className` on individual compound components |
+| `errorMessage` | - | Removed (handle validation externally) |
+
+### 4. Color Prop Removed
+
+**v2:** `color` prop with `default`, `primary`, `secondary`, `success`, `warning`, `danger`
+**v3:** No `color` prop — style cells using Tailwind CSS classes or customize via `calendar.css` overrides
+
+## Migration Examples
+
+### Basic Calendar
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Calendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <Calendar
+      aria-label="Date"
+      defaultValue={today(getLocalTimeZone())}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Calendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <Calendar
+      aria-label="Date"
+      defaultValue={today(getLocalTimeZone())}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Calendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <Calendar
+      aria-label="Date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Calendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <Calendar
+      aria-label="Date"
+      value={value}
+      onChange={setValue}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Month and Year Pickers
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {(year) => <Calendar.YearPickerCell date={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Multiple Months
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      visibleMonths={2}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date" visibleDuration={{months: 2}}>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <div className="flex gap-4">
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => <Calendar.Cell date={date} />}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+        <Calendar.Grid offset={{months: 1}}>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => <Calendar.Cell date={date} />}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+      </div>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Unavailable Dates
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <Calendar
+      aria-label="Date"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <Calendar
+      aria-label="Date"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+    >
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Top and Bottom Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Calendar
+      aria-label="Date"
+      topContent={<p>Select a date</p>}
+      bottomContent={
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>
+          Today
+        </button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar aria-label="Date">
+      <p>Select a date</p>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => <Calendar.Cell date={date} />}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+      <button onClick={() => setValue(today(getLocalTimeZone()))}>
+        Today
+      </button>
+    </Calendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Cell Indicators
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have a built-in cell indicator API */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>
+        {(date) => (
+          <Calendar.Cell date={date}>
+            {({formattedDate}) => (
+              <>
+                {formattedDate}
+                {hasEvent(date) && <Calendar.CellIndicator />}
+              </>
+            )}
+          </Calendar.Cell>
+        )}
+      </Calendar.GridBody>
+    </Calendar.Grid>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Calendar
+  classNames={{
+    base: "custom-base",
+    prevButton: "custom-prev",
+    nextButton: "custom-next",
+    title: "custom-title",
+    cell: "custom-cell",
+    cellButton: "custom-cell-button",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Calendar className="custom-base">
+  <Calendar.Header>
+    <Calendar.Heading className="custom-title" />
+    <Calendar.NavButton slot="previous" className="custom-prev" />
+    <Calendar.NavButton slot="next" className="custom-next" />
+  </Calendar.Header>
+  <Calendar.Grid>
+    <Calendar.GridHeader>
+      {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+    </Calendar.GridHeader>
+    <Calendar.GridBody>
+      {(date) => <Calendar.Cell date={date} className="custom-cell" />}
+    </Calendar.GridBody>
+  </Calendar.Grid>
+</Calendar>
+```
+
+## Component Anatomy
+
+The v3 Calendar follows this structure:
+
+```
+Calendar (Root)
+  ├── [Custom top content]
+  ├── Calendar.Header
+  │   ├── Calendar.Heading (or Calendar.YearPickerTrigger)
+  │   ├── Calendar.NavButton slot="previous"
+  │   └── Calendar.NavButton slot="next"
+  ├── Calendar.Grid (one per visible month)
+  │   ├── Calendar.GridHeader
+  │   │   └── Calendar.HeaderCell (render prop)
+  │   └── Calendar.GridBody
+  │       └── Calendar.Cell (render prop)
+  │           └── Calendar.CellIndicator (optional)
+  ├── Calendar.YearPickerGrid (optional)
+  │   └── Calendar.YearPickerGridBody
+  │       └── Calendar.YearPickerCell
+  └── [Custom bottom content]
+```
+
+## Summary
+
+1. **Component Structure**: Single component → compound components with explicit layout control
+2. **Year Picker**: `showMonthAndYearPickers` prop → dedicated `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid` components
+3. **Multiple Months**: `visibleMonths={n}` → `visibleDuration={{months: n}}` with multiple `Calendar.Grid` components using `offset`
+4. **Color Removed**: Use Tailwind CSS classes instead
+5. **Top/Bottom Content**: Props removed → place content directly as children inside `Calendar`
+6. **Cell Customization**: New `Calendar.CellIndicator` and render prop support on `Calendar.Cell`
+7. **Styling**: `classNames` prop → `className` on individual compound components
+8. **Removed Props**: `calendarWidth`, `weekdayStyle`, `hideDisabledDates`, `disableAnimation` — use Tailwind CSS or omit
diff --git a/apps/docs/content/docs/en/react/migration/(components)/card.mdx b/apps/docs/content/docs/en/react/migration/(components)/card.mdx
new file mode 100644
index 0000000..e896d59
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/card.mdx
@@ -0,0 +1,320 @@
+---
+title: Card
+description: Migration guide for Card from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Card documentation](/docs/react/components/card) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Card used separate components: `CardHeader`, `CardBody`, and `CardFooter`:
+
+```tsx
+import { Card, CardHeader, CardBody, CardFooter } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Card>
+      <CardHeader>Header</CardHeader>
+      <CardBody>Body</CardBody>
+      <CardFooter>Footer</CardFooter>
+    </Card>
+  );
+}
+```
+
+In v3, Card uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Card } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Card>
+      <Card.Header>
+        <Card.Title>Title</Card.Title>
+        <Card.Description>Description</Card.Description>
+      </Card.Header>
+      <Card.Content>Body content</Card.Content>
+      <Card.Footer>Footer</Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Separate components: `CardHeader`, `CardBody`, `CardFooter`  
+**v3:** Compound components: `Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, `Card.Footer`
+
+### 2. Component Name Changes
+
+| v2 Component | v3 Component | Notes |
+|-------------|--------------|-------|
+| `CardHeader` | `Card.Header` | Same functionality |
+| `CardBody` | `Card.Content` | Renamed |
+| `CardFooter` | `Card.Footer` | Same functionality |
+| - | `Card.Title` | New subcomponent for header titles |
+| - | `Card.Description` | New subcomponent for header descriptions |
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `shadow` | - | Removed (use Tailwind e.g. `shadow-sm`, `shadow-md`) |
+| `radius` | - | Removed (use Tailwind e.g. `rounded-lg`) |
+| `fullWidth` | - | Removed (use Tailwind `w-full`) |
+| `isHoverable` | - | Removed (use Tailwind hover classes) |
+| `isPressable` | - | Use button or link wrapper inside Card |
+| `isBlurred`, `isFooterBlurred` | - | Removed (use Tailwind `backdrop-blur-*`) |
+| `isDisabled` | - | Removed (handle with conditional rendering) |
+| `disableAnimation`, `disableRipple` | - | Removed |
+| `allowTextSelectionOnPress` | - | Removed (not applicable) |
+| `classNames` | - | Use `className` on parts |
+
+### 4. Variants
+
+**v2:** No variant prop (used shadow/radius for styling)  
+**v3:** Has `variant` prop: `transparent`, `default`, `secondary`, `tertiary`
+
+## Migration Examples
+
+### Card Structure
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Basic structure */}
+    <Card>
+      <CardHeader>Header</CardHeader>
+      <CardBody>Body content</CardBody>
+      <CardFooter>Footer</CardFooter>
+    </Card>
+    
+    {/* With title and description */}
+    <Card>
+      <CardHeader className="pb-0 pt-2 px-4 flex-col items-start">
+        <p className="text-tiny uppercase font-bold">Daily Mix</p>
+        <small className="text-default-500">12 Tracks</small>
+        <h4 className="font-bold text-large">Frontend Radio</h4>
+      </CardHeader>
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Basic structure */}
+    <Card>
+      <Card.Header>
+        <Card.Title>Header</Card.Title>
+      </Card.Header>
+      <Card.Content>Body content</Card.Content>
+      <Card.Footer>Footer</Card.Footer>
+    </Card>
+    
+    {/* With title and description */}
+    <Card>
+      <Card.Header>
+        <Card.Title>Frontend Radio</Card.Title>
+        <Card.Description>Daily Mix • 12 Tracks</Card.Description>
+      </Card.Header>
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Pressable Card
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card 
+      isPressable 
+      shadow="sm" 
+      onPress={() => console.log("pressed")}
+    >
+      <CardBody>Clickable card</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card className="shadow-sm">
+      <button
+        type="button"
+        className="w-full cursor-pointer text-left"
+        onClick={() => console.log("pressed")}
+      >
+        <Card.Content>Clickable card</Card.Content>
+      </button>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Card with Image
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card className="py-4">
+      <CardHeader className="pb-0 pt-2 px-4 flex-col items-start">
+        <h4 className="font-bold text-large">Frontend Radio</h4>
+      </CardHeader>
+      <CardBody className="overflow-visible py-2">
+        <Image
+          alt="Card background"
+          className="object-cover rounded-xl"
+          src="https://example.com/image.jpg"
+          width={270}
+        />
+      </CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card className="py-4">
+      <Card.Header>
+        <Card.Title>Frontend Radio</Card.Title>
+      </Card.Header>
+      <Card.Content className="overflow-visible py-2">
+        <img
+          alt="Card background"
+          className="object-cover rounded-xl w-full"
+          src="https://example.com/image.jpg"
+        />
+      </Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Blurred Footer Card
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Card, CardFooter, Image, Button } from "@heroui/react";
+
+    <Card isFooterBlurred className="border-none" radius="lg">
+      <Image
+        alt="Woman listing to music"
+        className="object-cover"
+        height={200}
+        src="https://example.com/image.jpg"
+        width={200}
+      />
+      <CardFooter className="justify-between before:bg-white/10 border-white/20 border-1 overflow-hidden py-1 absolute before:rounded-xl rounded-large bottom-1 w-[calc(100%_-_8px)] shadow-small ml-1 z-10">
+        <p className="text-tiny text-white/80">Available soon.</p>
+        <Button className="text-tiny text-white bg-black/20" size="sm">
+          Notify me
+        </Button>
+      </CardFooter>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Card, Button } from "@heroui/react";
+
+    <Card className="border-none rounded-lg relative overflow-hidden">
+      <img
+        alt="Woman listing to music"
+        className="object-cover w-full h-[200px]"
+        src="https://example.com/image.jpg"
+      />
+      <Card.Footer className="justify-between backdrop-blur-md bg-white/10 border-white/20 border overflow-hidden py-1 absolute rounded-lg bottom-1 w-[calc(100%_-_8px)] shadow-sm ml-1 z-10">
+        <p className="text-tiny text-white/80">Available soon.</p>
+        <Button className="text-tiny text-white bg-black/20" size="sm">
+          Notify me
+        </Button>
+      </Card.Footer>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Card Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have variants, uses shadow/radius */}
+    <Card shadow="md" radius="lg">
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Card variant="default">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    <Card variant="secondary">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Card 
+  classNames={{
+    base: "custom-base",
+    header: "custom-header",
+    body: "custom-body",
+    footer: "custom-footer"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Card className="custom-base">
+  <Card.Header className="custom-header">
+    <Card.Title>Title</Card.Title>
+  </Card.Header>
+  <Card.Content className="custom-body">
+    Content
+  </Card.Content>
+  <Card.Footer className="custom-footer">
+    Footer
+  </Card.Footer>
+</Card>
+```
+
+## Component Anatomy
+
+The v3 Card follows this structure:
+
+```
+Card (Root)
+  ├── Card.Header (optional)
+  │   ├── Card.Title (optional)
+  │   └── Card.Description (optional)
+  ├── Card.Content (optional)
+  └── Card.Footer (optional)
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components instead of separate components
+2. **CardBody → Card.Content**: Component renamed
+3. **New Subcomponents**: `Card.Title` and `Card.Description` for structured headers
+4. **Props Removed**: Many styling props removed; use Tailwind CSS classes
+5. **Pressable Cards**: Use a button or link inside Card instead of `isPressable`
+6. **Blur Effects**: Use Tailwind `backdrop-blur-*` classes instead of props
+7. **Variants**: New variant system for semantic prominence levels
+8. **ClassNames Removed**: Use `className` props on individual components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/checkbox-group.mdx b/apps/docs/content/docs/en/react/migration/(components)/checkbox-group.mdx
new file mode 100644
index 0000000..c7c9cb3
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/checkbox-group.mdx
@@ -0,0 +1,163 @@
+---
+title: CheckboxGroup
+description: Migration guide for CheckboxGroup from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 CheckboxGroup documentation](/docs/react/components/checkbox-group) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `CheckboxGroup` was a separate component with a `label` prop and simple `Checkbox` children:
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CheckboxGroup label="Select interests">
+      <Checkbox value="coding">Coding</Checkbox>
+      <Checkbox value="design">Design</Checkbox>
+      <Checkbox value="writing">Writing</Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+In v3, `CheckboxGroup` is still a separate component but uses `Label`/`Description` as children and the new compound Checkbox structure:
+
+```tsx
+import { CheckboxGroup, Checkbox, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CheckboxGroup name="interests">
+      <Label>Select interests</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Same Component Name
+
+**v2:** `CheckboxGroup` (separate import with `label` prop)  
+**v3:** `CheckboxGroup` (separate import; use `Label` component instead of `label` prop)
+
+### 2. Label Prop
+
+**v2:** Used `label` prop on `CheckboxGroup`  
+**v3:** Use `Label` component as a child of `CheckboxGroup`
+
+### 3. Checkbox Structure
+
+**v2:** Simple Checkbox components with children as labels  
+**v3:** Compound Checkbox components with `Checkbox.Content`, `Checkbox.Control`, and `Checkbox.Indicator`
+
+### 4. Event Handler
+
+**v2:** Used `onValueChange` prop  
+**v3:** Uses `onChange` prop (from React Aria Components)
+
+### 5. Variant Support
+
+**v3:** New `variant` prop for styling the group container
+
+## Migration Examples
+
+### Controlled CheckboxGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+    const [selected, setSelected] = useState(["coding"]);
+
+    <CheckboxGroup
+      value={selected}
+      onValueChange={setSelected}
+      label="Select interests"
+    >
+      <Checkbox value="coding">Coding</Checkbox>
+      <Checkbox value="design">Design</Checkbox>
+      <Checkbox value="writing">Writing</Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { CheckboxGroup, Checkbox, Label } from "@heroui/react";
+
+    const [selected, setSelected] = useState(["coding"]);
+
+    <CheckboxGroup
+      name="interests"
+      value={selected}
+      onChange={setSelected}
+    >
+      <Label>Select interests</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+- Keep using `CheckboxGroup`; replace `label` prop with `Label` component as a child
+- Update Checkbox children to use compound component structure (`Checkbox.Content`, `Checkbox.Control`, `Checkbox.Indicator`)
+- Change `onValueChange` to `onChange`
+- Add `name` prop for form integration
+- Built on React Aria Components for accessibility
diff --git a/apps/docs/content/docs/en/react/migration/(components)/checkbox.mdx b/apps/docs/content/docs/en/react/migration/(components)/checkbox.mdx
new file mode 100644
index 0000000..59202dc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/checkbox.mdx
@@ -0,0 +1,404 @@
+---
+title: Checkbox
+description: Migration guide for Checkbox from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Checkbox documentation](/docs/react/components/checkbox) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Checkbox` accepted children as the label:
+
+```tsx
+import { Checkbox } from "@heroui/react";
+
+export default function App() {
+  return <Checkbox defaultSelected>Option</Checkbox>;
+}
+```
+
+In v3, Checkbox uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Checkbox, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Checkbox defaultSelected id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple component with children as label  
+**v3:** Compound components: `Checkbox.Content`, `Checkbox.Control`, `Checkbox.Indicator`
+
+### 2. Label Handling
+
+**v2:** Label passed as children directly to `Checkbox`  
+**v3:** Label goes inside `Checkbox.Content` (the clickable label); `Description`/`FieldError` are siblings of `Checkbox.Content`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `onValueChange` | `Checkbox` | Use `onChange` |
+| `color` | - | Removed (use Tailwind on Checkbox.Control) |
+| `size` | - | Removed (use Tailwind e.g. `size-4`, `size-5`) |
+| `radius` | - | Removed (use Tailwind e.g. `rounded-sm`) |
+| `lineThrough` | - | Removed (use Tailwind `line-through` on label) |
+| `icon` | - | Use custom content in `Checkbox.Indicator` |
+| `classNames` | - | Use `className` on parts |
+| `disableAnimation` | - | Removed |
+| — | `variant` | New prop: `"primary"` (default) or `"secondary"` for lower emphasis styling |
+
+### 4. CheckboxGroup Changes
+
+**v2:** `CheckboxGroup` (separate component) with `label` prop and simple `Checkbox` children  
+**v3:** `CheckboxGroup` (separate component) with `Label`/`Description` as children and compound `Checkbox` structure
+
+For migrating checkbox groups, see the [CheckboxGroup migration guide](/docs/react/migration/checkbox-group).
+
+## Migration Examples
+
+### Controlled Checkbox
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(false);
+
+    <Checkbox isSelected={isSelected} onValueChange={setIsSelected}>
+      Subscribe
+    </Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Label } from "@heroui/react";
+
+    const [isSelected, setIsSelected] = useState(false);
+
+    <Checkbox id="subscribe" isSelected={isSelected} onChange={setIsSelected}>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Subscribe
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### Checkbox with Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have built-in description support */}
+    <Checkbox defaultSelected>
+      Option
+    </Checkbox>
+    <p className="text-sm text-default-500">Description text</p>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Checkbox, Label, Description } from "@heroui/react";
+
+    <Checkbox id="option" defaultSelected>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+      <Description>Description text</Description>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### CheckboxGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Checkbox, CheckboxGroup } from "@heroui/react";
+
+    <CheckboxGroup label="Select cities">
+      <Checkbox value="buenos-aires">Buenos Aires</Checkbox>
+      <Checkbox value="sydney">Sydney</Checkbox>
+      <Checkbox value="san-francisco">San Francisco</Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { CheckboxGroup, Checkbox, Label, Description } from "@heroui/react";
+
+    <CheckboxGroup name="cities">
+      <Label>Select cities</Label>
+      <Description>Choose all that apply</Description>
+      <Checkbox value="buenos-aires">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Buenos Aires
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="sydney">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Sydney
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="san-francisco">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          San Francisco
+        </Checkbox.Content>
+      </Checkbox>
+    </CheckboxGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Colors and Sizes
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Colors */}
+    <Checkbox defaultSelected color="primary">Primary</Checkbox>
+    
+    {/* Sizes */}
+    <Checkbox defaultSelected size="md">Medium</Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Colors - use Tailwind classes */}
+    <Checkbox defaultSelected id="primary">
+      <Checkbox.Content>
+        <Checkbox.Control className="data-[selected=true]:bg-primary data-[selected=true]:border-primary">
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Primary
+      </Checkbox.Content>
+    </Checkbox>
+    
+    {/* Sizes - use Tailwind classes */}
+    <Checkbox defaultSelected id="medium">
+      <Checkbox.Content>
+        <Checkbox.Control className="size-5">
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Medium
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Icon/Indicator
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Checkbox defaultSelected icon={<HeartIcon />}>
+      Option
+    </Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Checkbox defaultSelected id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator>
+            {({isSelected}) => isSelected ? <HeartIcon /> : null}
+          </Checkbox.Indicator>
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants
+
+v3 introduces a `variant` prop with `"primary"` (default) and `"secondary"` options:
+
+```tsx
+{/* Primary variant (default) */}
+<Checkbox variant="primary" id="primary-option">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Primary
+  </Checkbox.Content>
+</Checkbox>
+
+{/* Secondary variant - lower emphasis, suitable for Surface components */}
+<Checkbox variant="secondary" id="secondary-option">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Secondary
+  </Checkbox.Content>
+</Checkbox>
+```
+
+### Indeterminate State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Checkbox isIndeterminate>Option</Checkbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Checkbox isIndeterminate id="option">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Option
+      </Checkbox.Content>
+    </Checkbox>
+    ```
+  </Tab>
+</Tabs>
+
+## Render Props Pattern
+
+v3 Checkbox supports a render prop pattern that provides state information:
+
+```tsx
+<Checkbox id="terms">
+  {({isSelected, isIndeterminate, isHovered, isPressed, isFocused, isDisabled}) => (
+    <>
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        
+          {isSelected ? "Terms accepted" : "Accept terms"}
+        
+      </Checkbox.Content>
+    </>
+  )}
+</Checkbox>
+```
+
+`Checkbox.Indicator` also supports a render prop pattern, providing the same state values. This is useful for rendering custom indicator content based on the checkbox state:
+
+```tsx
+<Checkbox id="custom">
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator>
+        {({isSelected, isIndeterminate}) =>
+          isIndeterminate ? <MinusIcon /> : isSelected ? <CheckIcon /> : null
+        }
+      </Checkbox.Indicator>
+    </Checkbox.Control>
+    Custom indicator
+  </Checkbox.Content>
+</Checkbox>
+```
+
+Available render props:
+- `isSelected` - Whether checkbox is checked
+- `isIndeterminate` - Whether checkbox is in indeterminate state
+- `isHovered` - Whether checkbox is hovered
+- `isPressed` - Whether checkbox is currently pressed
+- `isFocused` - Whether checkbox is focused
+- `isFocusVisible` - Whether checkbox should show focus indicator
+- `isDisabled` - Whether checkbox is disabled
+- `isReadOnly` - Whether checkbox is read only
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Checkbox 
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    icon: "custom-icon",
+    label: "custom-label"
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Checkbox className="custom-base" id="option">
+  <Checkbox.Content>
+    <Checkbox.Control className="custom-control">
+      <Checkbox.Indicator className="custom-indicator" />
+    </Checkbox.Control>
+    
+      Option
+    
+  </Checkbox.Content>
+</Checkbox>
+```
+
+## Component Anatomy
+
+The v3 Checkbox follows this structure:
+
+```
+Checkbox (Root)
+  ├── Checkbox.Content (the clickable label)
+  │   ├── Checkbox.Control
+  │   │   └── Checkbox.Indicator
+  │   └── Label
+  ├── Description (optional, sibling)
+  └── FieldError (optional, sibling)
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Button`, `Control`, `Indicator`)
+2. **Label Handling**: Labels go inside `Checkbox.Content`
+3. **onValueChange → onChange**: Event handler prop renamed
+4. **Color Removed**: Use Tailwind CSS classes on `Checkbox.Control`
+5. **Size Removed**: Use Tailwind CSS classes on `Checkbox.Control`
+6. **Radius Removed**: Use Tailwind CSS classes on `Checkbox.Control`
+7. **LineThrough Removed**: Use Tailwind `line-through` class on label
+8. **Icon Prop Removed**: Use custom content in `Checkbox.Indicator`
+9. **CheckboxGroup**: Same component name; use `Label`/`Description` as children and compound `Checkbox` structure
+10. **ClassNames Removed**: Use `className` props on individual components
+11. **New `variant` Prop**: Supports `"primary"` (default) and `"secondary"` for lower emphasis styling
+12. **Indicator Render Props**: `Checkbox.Indicator` accepts a render function with state values (`isSelected`, `isIndeterminate`, etc.)
diff --git a/apps/docs/content/docs/en/react/migration/(components)/chip.mdx b/apps/docs/content/docs/en/react/migration/(components)/chip.mdx
new file mode 100644
index 0000000..de61d0e
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/chip.mdx
@@ -0,0 +1,309 @@
+---
+title: Chip
+description: Migration guide for Chip from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Chip documentation](/docs/react/components/chip) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Key Changes
+
+### 1. Variants
+
+**v2:** `solid`, `bordered`, `light`, `flat`, `faded`, `shadow`, `dot`  
+**v3:** `primary`, `secondary`, `tertiary`, `soft`
+
+### 2. Colors
+
+**v2:** `default`, `primary`, `secondary`, `success`, `warning`, `danger`  
+**v3:** `default`, `accent`, `success`, `warning`, `danger`
+
+### 3. Compound Component Pattern
+
+v3 introduces a compound component pattern with the `Chip.Label` subcomponent:
+
+- **`Chip.Label`** -- Renders the label text inside the chip. Plain-text children are automatically wrapped in `<Chip.Label>`, so explicit usage is optional but available for custom styling.
+
+```tsx
+{/* Implicit label -- plain text is auto-wrapped in Chip.Label */}
+<Chip>Badge</Chip>
+
+{/* Explicit label -- useful when you need a custom className */}
+<Chip>
+  <Chip.Label className="uppercase tracking-wide">Badge</Chip.Label>
+</Chip>
+```
+
+### 4. Size Variants
+
+**v2:** `sm`, `md`, `lg` (via the `size` prop)
+**v3:** `sm`, `md`, `lg` (via the `size` prop -- same API)
+
+The available sizes remain the same, but v3 applies them through BEM-style CSS classes (`chip--sm`, `chip--md`, `chip--lg`). The default size is `md`.
+
+```tsx
+<Chip size="sm">Small</Chip>
+<Chip size="md">Medium (default)</Chip>
+<Chip size="lg">Large</Chip>
+```
+
+### 5. Compound Variant Classes
+
+v3 supports combining variant and color classes for precise styling. These compound classes have default styles defined in the CSS:
+
+**Primary variant combinations:** `.chip--primary.chip--accent`, `.chip--primary.chip--success`, `.chip--primary.chip--warning`, `.chip--primary.chip--danger`
+
+**Soft variant combinations:** `.chip--accent.chip--soft`, `.chip--success.chip--soft`, `.chip--warning.chip--soft`, `.chip--danger.chip--soft`
+
+You can also target any other combination (e.g., `.chip--secondary.chip--accent`) via the `@layer components` directive in your CSS.
+
+### 6. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `radius` | - | Removed (use Tailwind e.g. `rounded-full`) |
+| `avatar` | - | Use children (e.g. `<Avatar />` as first child) |
+| `startContent`, `endContent` | - | Use children directly |
+| `onClose` | - | Implement close manually (e.g. `CloseButton`) |
+| `classNames` | - | Use `className` |
+| `isDisabled` | - | Use conditional rendering or Tailwind (e.g. `opacity-50`) |
+
+### 7. Variant Mapping
+
+| v2 Variant | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| `solid` | `primary` | Filled background |
+| `bordered` | `secondary` | Border with transparent background |
+| `light` | `soft` | Light background |
+| `flat` | `tertiary` | Transparent background |
+| `faded` | `secondary` | Similar appearance |
+| `shadow` | `primary` | Use Tailwind `shadow-*` classes |
+| `dot` | - | Not available, implement manually |
+
+### 8. Color Mapping
+
+| v2 Color | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `default` | `default` | Same |
+| `primary` | `accent` | Renamed |
+| `secondary` | `default` or `accent` | Depends on context |
+| `success` | `success` | Same |
+| `warning` | `warning` | Same |
+| `danger` | `danger` | Same |
+
+## Structure Changes
+
+In v2, `Chip` was a component that accepted various props for styling:
+
+```tsx
+import { Chip } from "@heroui/react";
+
+export default function App() {
+  return <Chip>Chip</Chip>;
+}
+```
+
+In v3, `Chip` has a simplified API with fewer variants:
+
+```tsx
+import { Chip } from "@heroui/react";
+
+export default function App() {
+  return <Chip>Chip</Chip>;
+}
+```
+
+## Migration Examples
+
+### Variants and Colors
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Variants */}
+    <Chip variant="solid">Solid</Chip>
+    <Chip variant="bordered">Bordered</Chip>
+    <Chip variant="light">Light</Chip>
+    
+    {/* Colors */}
+    <Chip color="primary">Primary</Chip>
+    <Chip color="success">Success</Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Variants */}
+    <Chip variant="primary">Primary</Chip>
+    <Chip variant="secondary">Secondary</Chip>
+    <Chip variant="soft">Soft</Chip>
+    
+    {/* Colors */}
+    <Chip color="accent">Accent</Chip>
+    <Chip color="success">Success</Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* Start content */}
+    <Chip startContent={<Icon icon="gravity-ui:check" />}>
+      Chip
+    </Chip>
+    
+    {/* End content */}
+    <Chip endContent={<Icon icon="gravity-ui:chevron-down" />}>
+      Chip
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* Start content */}
+    <Chip>
+      <Icon icon="gravity-ui:check" />
+      Chip
+    </Chip>
+    
+    {/* End content */}
+    <Chip>
+      Chip
+      <Icon icon="gravity-ui:chevron-down" />
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### With Avatar
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <Chip
+      avatar={<Avatar name="JW" src="https://example.com/avatar.jpg" />}
+      variant="flat"
+    >
+      Avatar
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Chip } from "@heroui/react";
+
+    <Chip variant="tertiary">
+      <Avatar size="sm">
+        <Avatar.Image src="https://example.com/avatar.jpg" alt="JW" />
+        <Avatar.Fallback>JW</Avatar.Fallback>
+      </Avatar>
+      Avatar
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### With Close Button
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Chip onClose={() => console.log("close")}>
+      Chip
+    </Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { CloseButton } from "@heroui/react";
+
+    <Chip>
+      Chip
+      <CloseButton 
+        aria-label="Close chip"
+        onPress={() => console.log("close")}
+      />
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+### Removed Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Dot variant */}
+    <Chip variant="dot">Dot</Chip>
+    
+    {/* Shadow variant */}
+    <Chip variant="shadow">Shadow</Chip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    {/* Dot variant - implement manually */}
+    <Chip>
+      <Icon icon="gravity-ui:circle-fill" width={6} />
+      Dot
+    </Chip>
+    
+    {/* Shadow variant - use Tailwind classes */}
+    <Chip variant="primary" className="shadow-md">
+      Shadow
+    </Chip>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Chip 
+  classNames={{
+    base: "custom-base",
+    content: "custom-content",
+    dot: "custom-dot",
+    avatar: "custom-avatar",
+    closeButton: "custom-close-button"
+  }}
+/>
+```
+
+### v3: Direct `className` Prop
+
+```tsx
+<Chip className="custom-base">
+  {/* Content with custom classes */}
+  <span className="custom-content">Chip</span>
+</Chip>
+```
+
+## Summary
+
+1. **Variants Reduced**: From 7 variants to 4 variants
+2. **Color Changes**: `primary` → `accent`, `secondary` removed
+3. **Compound Component**: `Chip.Label` subcomponent added; plain-text children are auto-wrapped
+4. **Size Variants**: `sm`, `md`, `lg` remain available via the `size` prop, now applied as BEM classes (`chip--sm`, `chip--md`, `chip--lg`)
+5. **Compound Variant Classes**: Variant + color combinations (e.g., `.chip--primary.chip--accent`, `.chip--soft.chip--success`) have built-in styles and are customizable via `@layer components`
+6. **Radius Removed**: Use Tailwind CSS classes instead
+7. **Avatar Prop Removed**: Use children directly
+8. **Start/End Content Removed**: Use children directly
+9. **Close Button Removed**: Implement manually with `CloseButton` component
+10. **Dot Variant Removed**: Implement manually with icon
+11. **Shadow Variant Removed**: Use Tailwind `shadow-*` classes
+12. **Disabled Prop Removed**: Use conditional rendering or CSS classes
+13. **ClassNames Removed**: Use `className` prop directly
diff --git a/apps/docs/content/docs/en/react/migration/(components)/circular-progress.mdx b/apps/docs/content/docs/en/react/migration/(components)/circular-progress.mdx
new file mode 100644
index 0000000..b6650bf
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/circular-progress.mdx
@@ -0,0 +1,228 @@
+---
+title: CircularProgress
+description: Migration guide for CircularProgress from HeroUI v2 to v3 (now ProgressCircle)
+---
+
+<Callout type="info">
+  Refer to the [v3 ProgressCircle documentation](/docs/react/components/progress-circle) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+<Callout type="warning">
+  Looking for the Progress (linear) migration? See the [Progress migration guide](/docs/react/migration/progress).
+</Callout>
+
+## Component Rename
+
+`CircularProgress` has been renamed to `ProgressCircle` in v3.
+
+## Structure Changes
+
+In v2, `CircularProgress` was a single component configured with props:
+
+```tsx
+import { CircularProgress } from "@heroui/react";
+
+export default function App() {
+  return (
+    <CircularProgress label="Loading..." value={60} />
+  );
+}
+```
+
+In v3, `ProgressCircle` uses a compound component pattern:
+
+```tsx
+import { ProgressCircle } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `CircularProgress` component with internal SVG rendering
+**v3:** Compound components: `ProgressCircle`, `ProgressCircle.Track` (SVG element), `ProgressCircle.TrackCircle` (background circle), `ProgressCircle.FillCircle` (progress arc)
+
+### 2. Colors
+
+**v2:** `default`, `primary`, `secondary`, `success`, `warning`, `danger`
+**v3:** `default`, `accent`, `success`, `warning`, `danger`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isIndeterminate` | `isIndeterminate` | Default changed: `true` in v2 → `false` in v3 |
+| `formatOptions` | `formatOptions` | Same |
+| `size` | `size` | Same (`sm`, `md`, `lg`) |
+| `color` | `color` | `primary` → `accent`, `secondary` removed |
+| `label` | - | Use `Label` component |
+| `valueLabel` | - | Use render prop pattern |
+| `showValueLabel` | - | Place value content inside `ProgressCircle` |
+| `strokeWidth` | - | Set `strokeWidth` directly on `ProgressCircle.TrackCircle` and `ProgressCircle.FillCircle` |
+| `isDisabled` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual compound components |
+
+## Migration Examples
+
+### Basic CircularProgress
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { CircularProgress } from "@heroui/react";
+
+    <CircularProgress aria-label="Loading..." value={60} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressCircle } from "@heroui/react";
+
+    <ProgressCircle aria-label="Loading..." value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    ```
+  </Tab>
+</Tabs>
+
+### Indeterminate
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress aria-label="Loading..." />
+    {/* isIndeterminate defaults to true in v2 */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressCircle isIndeterminate aria-label="Loading...">
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    {/* isIndeterminate defaults to false in v3, must be explicit */}
+    ```
+  </Tab>
+</Tabs>
+
+### With Label
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress
+      label="Loading..."
+      value={70}
+      showValueLabel
+      size="lg"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressCircle, Label } from "@heroui/react";
+
+    <div className="flex flex-col items-center gap-2">
+      <ProgressCircle aria-label="Loading" value={70} size="lg">
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <Label>Loading...</Label>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom SVG Props
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <CircularProgress
+      value={60}
+      strokeWidth={6}
+      aria-label="Loading"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle strokeWidth={6} />
+        <ProgressCircle.FillCircle strokeWidth={6} />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<CircularProgress
+  classNames={{
+    base: "custom-base",
+    svg: "custom-svg",
+    track: "custom-track",
+    indicator: "custom-fill",
+    label: "custom-label",
+    value: "custom-value",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<ProgressCircle className="custom-base" value={60}>
+  <ProgressCircle.Track className="custom-svg">
+    <ProgressCircle.TrackCircle className="custom-track" />
+    <ProgressCircle.FillCircle className="custom-fill" />
+  </ProgressCircle.Track>
+</ProgressCircle>
+```
+
+## Component Anatomy
+
+```
+ProgressCircle (Root)
+  └── ProgressCircle.Track (SVG element)
+      ├── ProgressCircle.TrackCircle (background circle)
+      └── ProgressCircle.FillCircle (progress arc)
+```
+
+## Summary
+
+1. **Renamed**: `CircularProgress` → `ProgressCircle`
+2. **Component Structure**: Single component → compound components (`ProgressCircle.Track`, `ProgressCircle.TrackCircle`, `ProgressCircle.FillCircle`)
+3. **Indeterminate Default Changed**: `isIndeterminate` defaults to `false` in v3 (was `true` in v2)
+4. **Label**: `label` prop → `Label` component
+5. **SVG Props**: `strokeWidth` on root → set directly on `TrackCircle` and `FillCircle`
+6. **Color Changes**: `primary` → `accent`, `secondary` removed
+7. **Removed Props**: `isDisabled`, `disableAnimation` → use Tailwind CSS
+8. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/code.mdx b/apps/docs/content/docs/en/react/migration/(components)/code.mdx
new file mode 100644
index 0000000..0d043fc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/code.mdx
@@ -0,0 +1,287 @@
+---
+title: Code
+description: Migration guide for Code from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The Code component has been **removed** in HeroUI v3. Use native HTML `<code>` element with Tailwind CSS classes instead.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<Code>` component from `@heroui/react`  
+**v3:** Native HTML `<code>` element with Tailwind classes
+
+### 2. Variants Mapping
+
+The v2 Code component had the following variants that need to be replaced:
+
+| v2 Variant | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| `color="default"` | `bg-default/40 text-default-700` | Use Tailwind opacity utilities |
+| `color="primary"` | `bg-accent/20 text-accent-600` | `primary` renamed to `accent` |
+| `color="secondary"` | `bg-default/40 text-default-700` | Similar to default |
+| `color="success"` | `bg-success/20 text-success-700` | Same color name |
+| `color="warning"` | `bg-warning/20 text-warning-700` | Same color name |
+| `color="danger"` | `bg-danger/20 text-danger-600` | Same color name |
+| `size="sm"` | `text-sm` | Tailwind text size |
+| `size="md"` | `text-base` | Tailwind text size |
+| `size="lg"` | `text-lg` | Tailwind text size |
+| `radius="none"` | `rounded-none` | Tailwind border radius |
+| `radius="sm"` | `rounded-sm` | Tailwind border radius |
+| `radius="md"` | `rounded-md` | Tailwind border radius |
+| `radius="lg"` | `rounded-lg` | Tailwind border radius |
+| `radius="full"` | `rounded-full` | Tailwind border radius |
+
+## Structure Changes
+
+In v2, `Code` was a component wrapper around the native `<code>` element:
+
+```tsx
+import { Code } from "@heroui/react";
+
+export default function App() {
+  return <Code>npm install @heroui/react</Code>;
+}
+```
+
+In v3, use the native `<code>` element directly with Tailwind CSS classes:
+
+```tsx
+export default function App() {
+  return (
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+      npm install @heroui/react
+    </code>
+  );
+}
+```
+
+## Migration Examples
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Colors */}
+    <Code color="primary">Primary code</Code>
+    <Code color="success">Success code</Code>
+    
+    {/* Sizes */}
+    <Code size="md">Medium code</Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Colors */}
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-accent/20 text-accent-600 text-sm">
+      Primary code
+    </code>
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-success/20 text-success-700 text-sm">
+      Success code
+    </code>
+    
+    {/* Sizes */}
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-base">
+      Medium code
+    </code>
+    ```
+  </Tab>
+</Tabs>
+
+### Combined Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Code color="primary" size="md" radius="lg">
+      npm install @heroui/react
+    </Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-lg bg-accent/20 text-accent-600 text-base">
+      npm install @heroui/react
+    </code>
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a Reusable Code Component (Optional)
+
+If you use inline code frequently, you can create a simple wrapper component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Code } from "@heroui/react";
+
+    <Code color="primary" size="md">Code snippet</Code>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    // components/Code.tsx
+    import { cn } from "@/lib/utils"; // or your cn utility
+
+    interface CodeProps extends React.HTMLAttributes<HTMLElement> {
+      color?: "default" | "accent" | "success" | "warning" | "danger";
+      size?: "sm" | "md" | "lg";
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+    }
+
+    const colorClasses = {
+      default: "bg-default/40 text-default-700",
+      accent: "bg-accent/20 text-accent-600",
+      success: "bg-success/20 text-success-700",
+      warning: "bg-warning/20 text-warning-700",
+      danger: "bg-danger/20 text-danger-600",
+    };
+
+    const sizeClasses = {
+      sm: "text-sm",
+      md: "text-base",
+      lg: "text-lg",
+    };
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    export function Code({
+      children,
+      className,
+      color = "default",
+      size = "sm",
+      radius = "sm",
+      ...props
+    }: CodeProps) {
+      return (
+        <code
+          className={cn(
+            "px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap",
+            colorClasses[color],
+            sizeClasses[size],
+            radiusClasses[radius],
+            className
+          )}
+          {...props}
+        >
+          {children}
+        </code>
+      );
+    }
+
+    // Usage
+    <Code color="accent" size="md">Code snippet</Code>
+    ```
+  </Tab>
+</Tabs>
+
+## Complete Example
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Code } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <p>
+            Install HeroUI with <Code>npm install @heroui/react</Code>
+          </p>
+          <div className="flex gap-2">
+            <Code color="primary">Primary</Code>
+            <Code color="success">Success</Code>
+            <Code color="warning">Warning</Code>
+            <Code color="danger">Danger</Code>
+          </div>
+          <div className="flex gap-2 items-center">
+            <Code size="sm">Small</Code>
+            <Code size="md">Medium</Code>
+            <Code size="lg">Large</Code>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <p>
+            Install HeroUI with{" "}
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+              npm install @heroui/react
+            </code>
+          </p>
+          <div className="flex gap-2">
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-accent/20 text-accent-600 text-sm">
+              Primary
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-success/20 text-success-700 text-sm">
+              Success
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-warning/20 text-warning-700 text-sm">
+              Warning
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-danger/20 text-danger-600 text-sm">
+              Danger
+            </code>
+          </div>
+          <div className="flex gap-2 items-center">
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-sm">
+              Small
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-base">
+              Medium
+            </code>
+            <code className="px-2 py-1 h-fit font-mono font-normal inline-block whitespace-nowrap rounded-sm bg-default/40 text-default-700 text-lg">
+              Large
+            </code>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Base Styles Reference
+
+The v2 Code component used these base styles that you should include:
+
+- `px-2` - Horizontal padding
+- `py-1` - Vertical padding
+- `h-fit` - Height fits content
+- `font-mono` - Monospace font family
+- `font-normal` - Normal font weight
+- `inline-block` - Inline block display
+- `whitespace-nowrap` - Prevent text wrapping
+
+## Summary
+
+1. **Component Removed**: `Code` component no longer exists in v3
+2. **Import Change**: Remove `import { Code } from "@heroui/react"`
+3. **Use Native Element**: Replace with native `<code>` HTML element
+4. **Styling**: Apply Tailwind CSS classes directly
+5. **Color Mapping**: `primary` → `accent` in v3
+
+## Migration Steps
+
+1. **Remove Import**: Remove `Code` from `@heroui/react` imports
+2. **Replace Component**: Replace all `<Code>` instances with `<code>` elements
+3. **Add Tailwind Classes**: Apply equivalent Tailwind classes for styling
+4. **Update Colors**: Change `color="primary"` to use `accent` color classes
+5. **Optional**: Create a reusable wrapper component if you use inline code frequently
diff --git a/apps/docs/content/docs/en/react/migration/(components)/date-picker.mdx b/apps/docs/content/docs/en/react/migration/(components)/date-picker.mdx
new file mode 100644
index 0000000..b7d33f5
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/date-picker.mdx
@@ -0,0 +1,457 @@
+---
+title: DatePicker
+description: Migration guide for DatePicker from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 DatePicker documentation](/docs/react/components/date-picker) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `DatePicker` was a single self-contained component with props for label, description, calendar, and time input:
+
+```tsx
+import { DatePicker } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DatePicker label="Birth date" />
+  );
+}
+```
+
+In v3, DatePicker uses a composition-first API where you compose `DateField` and `Calendar` explicitly:
+
+```tsx
+import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DatePicker>
+      <Label>Birth date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `DatePicker` component with all parts (input, calendar, label, popover) handled internally via props
+**v3:** Composition-based API with `DatePicker`, `DateField`, `Calendar`, and `Label` composed together. Each part is a separate component.
+
+### 2. Composition Parts
+
+| v3 Component | Description |
+|-----------|-------------|
+| `DatePicker` | Root container and state owner |
+| `DatePicker.Trigger` | Button that opens the calendar popover |
+| `DatePicker.TriggerIndicator` | Calendar icon (default) or custom indicator |
+| `DatePicker.Popover` | Popover wrapper for the calendar |
+| `DateField.Group` | Input group wrapper |
+| `DateField.Input` | Segmented date input |
+| `DateField.Segment` | Individual date segment (month, day, year) |
+| `DateField.Suffix` | Suffix slot for the trigger button |
+| `Calendar` | Full calendar component (see [Calendar migration](/docs/react/migration/calendar)) |
+| `Label` | External label component |
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `defaultValue` | `defaultValue` | Same |
+| `onChange` | `onChange` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isDateUnavailable` | `isDateUnavailable` | Same |
+| `isDisabled` | `isDisabled` | Same |
+| `isReadOnly` | `isReadOnly` | Same |
+| `isRequired` | `isRequired` | Same |
+| `isInvalid` | `isInvalid` | Same |
+| `granularity` | `granularity` | Same |
+| `hourCycle` | `hourCycle` | Same |
+| `hideTimeZone` | `hideTimeZone` | Same |
+| `shouldForceLeadingZeros` | `shouldForceLeadingZeros` | Same |
+| `pageBehavior` | - | Set on `Calendar` directly |
+| `label` | - | Use `Label` component |
+| `description` | - | Use `Description` component |
+| `errorMessage` | - | Use `FieldError` component |
+| `variant` | - | Use `DateField.Group` `variant` prop or Tailwind CSS |
+| `color` | - | Removed (use Tailwind CSS) |
+| `size` | - | Removed (use Tailwind CSS) |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `labelPlacement` | - | Control layout with Tailwind CSS |
+| `startContent` | - | Compose inside `DateField.Group` |
+| `endContent` | - | Compose inside `DateField.Group` |
+| `selectorIcon` | - | Pass children to `DatePicker.TriggerIndicator` |
+| `visibleMonths` | - | Use `Calendar` `visibleDuration` prop |
+| `showMonthAndYearPickers` | - | Use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid` |
+| `calendarProps` | - | Pass props directly to `Calendar` |
+| `popoverProps` | - | Pass props directly to `DatePicker.Popover` |
+| `selectorButtonProps` | - | Pass props directly to `DatePicker.Trigger` |
+| `timeInputProps` | - | Compose time input separately |
+| `CalendarBottomContent` | - | Place content inside `DatePicker.Popover` after `Calendar` |
+| `validate` | - | Handle validation externally |
+| `placeholderValue` | `placeholderValue` | Same |
+| `autoFocus` | `autoFocus` | Same |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual components |
+
+## Migration Examples
+
+### Basic DatePicker
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { DatePicker } from "@heroui/react";
+
+    <DatePicker label="Birth date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+
+    <DatePicker>
+      <Label>Birth date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { DatePicker } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <DatePicker
+      label="Date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState(parseDate("2024-03-07"));
+
+    <DatePicker value={value} onChange={setValue}>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.Heading />
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### With Description and Error Message
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DatePicker
+      label="Event date"
+      description="Choose a future date"
+      errorMessage="Date must be in the future"
+      isInvalid={isInvalid}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DatePicker, DateField, Calendar, Label, Description, FieldError } from "@heroui/react";
+
+    <DatePicker isInvalid={isInvalid}>
+      <Label>Event date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Choose a future date</Description>
+      <FieldError>Date must be in the future</FieldError>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          {/* Calendar compound components */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Selector Icon
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DatePicker
+      label="Date"
+      selectorIcon={<Icon icon="gravity-ui:calendar" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DatePicker>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator>
+              <Icon icon="gravity-ui:calendar" />
+            </DatePicker.TriggerIndicator>
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          {/* Calendar compound components */}
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### With Month/Year Pickers and Calendar Bottom Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DatePicker
+      label="Date"
+      showMonthAndYearPickers
+      CalendarBottomContent={
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>Today</button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DatePicker>
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Choose date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => <Calendar.Cell date={date} />}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {(year) => <Calendar.YearPickerCell date={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+        <button onClick={() => setValue(today(getLocalTimeZone()))}>Today</button>
+      </DatePicker.Popover>
+    </DatePicker>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<DatePicker
+  classNames={{
+    base: "custom-base",
+    selectorButton: "custom-trigger",
+    selectorIcon: "custom-icon",
+    popoverContent: "custom-popover",
+    calendar: "custom-calendar",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<DatePicker className="custom-base">
+  <Label>Date</Label>
+  <DateField.Group>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+    <DateField.Suffix>
+      <DatePicker.Trigger className="custom-trigger">
+        <DatePicker.TriggerIndicator className="custom-icon" />
+      </DatePicker.Trigger>
+    </DateField.Suffix>
+  </DateField.Group>
+  <DatePicker.Popover className="custom-popover">
+    <Calendar aria-label="Choose date" className="custom-calendar">
+      {/* Calendar compound components */}
+    </Calendar>
+  </DatePicker.Popover>
+</DatePicker>
+```
+
+## Component Anatomy
+
+The v3 DatePicker follows this structure:
+
+```
+DatePicker (Root)
+  ├── Label
+  ├── DateField.Group
+  │   ├── DateField.Input
+  │   │   └── DateField.Segment (render prop per segment)
+  │   └── DateField.Suffix
+  │       └── DatePicker.Trigger
+  │           └── DatePicker.TriggerIndicator
+  ├── Description (optional)
+  ├── FieldError (optional)
+  └── DatePicker.Popover
+      ├── Calendar (see Calendar migration guide)
+      └── [Custom bottom content]
+```
+
+## Summary
+
+1. **Component Structure**: Single component → composition of `DatePicker`, `DateField`, `Calendar`, and `Label`
+2. **Label**: `label` prop → `Label` component
+3. **Description/Error**: Props → `Description` and `FieldError` components
+4. **Calendar**: Built-in → compose `Calendar` with its own compound components inside `DatePicker.Popover`
+5. **Selector Icon**: `selectorIcon` prop → pass children to `DatePicker.TriggerIndicator`
+6. **Year Picker**: `showMonthAndYearPickers` prop → use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid`
+7. **Calendar Bottom Content**: `CalendarBottomContent` prop → place content inside `DatePicker.Popover` after `Calendar`
+8. **Styling Props Removed**: `variant`, `color`, `size`, `radius` → use Tailwind CSS or `DateField.Group` variant
+9. **ClassNames Removed**: Use `className` on individual compound components
+10. **Multiple Months**: `visibleMonths` prop → use `Calendar` `visibleDuration` prop
diff --git a/apps/docs/content/docs/en/react/migration/(components)/date-range-picker.mdx b/apps/docs/content/docs/en/react/migration/(components)/date-range-picker.mdx
new file mode 100644
index 0000000..46b87d6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/date-range-picker.mdx
@@ -0,0 +1,522 @@
+---
+title: DateRangePicker
+description: Migration guide for DateRangePicker from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 DateRangePicker documentation](/docs/react/components/date-range-picker) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `DateRangePicker` was a single self-contained component with props for label, inputs, calendar, and time fields:
+
+```tsx
+import { DateRangePicker } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateRangePicker label="Trip dates" />
+  );
+}
+```
+
+In v3, DateRangePicker uses a composition-first API where you compose `DateField` and `RangeCalendar` explicitly:
+
+```tsx
+import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `DateRangePicker` component with all parts (two inputs, separator, calendar, label, popover) handled internally via props
+**v3:** Composition-based API with `DateRangePicker`, `DateField`, `RangeCalendar`, and `Label` composed together. Two `DateField.Input` components with `slot="start"` and `slot="end"` represent the range inputs.
+
+### 2. Composition Parts
+
+| v3 Component | Description |
+|-----------|-------------|
+| `DateRangePicker` | Root container and state owner |
+| `DateRangePicker.Trigger` | Button that opens the calendar popover |
+| `DateRangePicker.TriggerIndicator` | Calendar icon (default) or custom indicator |
+| `DateRangePicker.RangeSeparator` | Separator between start and end date inputs (defaults to " - ") |
+| `DateRangePicker.Popover` | Popover wrapper for the range calendar |
+| `DateField.Group` | Input group wrapper |
+| `DateField.InputContainer` | Container for start/end inputs and separator |
+| `DateField.Input slot="start"` | Start date segmented input |
+| `DateField.Input slot="end"` | End date segmented input |
+| `DateField.Segment` | Individual date segment (month, day, year) |
+| `DateField.Suffix` | Suffix slot for the trigger button |
+| `RangeCalendar` | Full range calendar component (see [RangeCalendar migration](/docs/react/migration/range-calendar)) |
+| `Label` | External label component |
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `defaultValue` | `defaultValue` | Same |
+| `onChange` | `onChange` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isDisabled` | `isDisabled` | Same |
+| `isReadOnly` | `isReadOnly` | Same |
+| `isRequired` | `isRequired` | Same |
+| `isInvalid` | `isInvalid` | Same |
+| `isOpen` | `isOpen` | Same |
+| `defaultOpen` | `defaultOpen` | Same |
+| `onOpenChange` | `onOpenChange` | Same |
+| `granularity` | `granularity` | Same |
+| `hourCycle` | `hourCycle` | Same |
+| `hideTimeZone` | `hideTimeZone` | Same |
+| `shouldForceLeadingZeros` | `shouldForceLeadingZeros` | Same |
+| `allowsNonContiguousRanges` | - | Set on `RangeCalendar` directly |
+| `pageBehavior` | - | Set on `RangeCalendar` directly |
+| `label` | - | Use `Label` component |
+| `description` | - | Use `Description` component |
+| `errorMessage` | - | Use `FieldError` component |
+| `variant` | - | Use `DateField.Group` `variant` prop or Tailwind CSS |
+| `color` | - | Removed (use Tailwind CSS) |
+| `size` | - | Removed (use Tailwind CSS) |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `labelPlacement` | - | Control layout with Tailwind CSS |
+| `selectorIcon` | - | Pass children to `DateRangePicker.TriggerIndicator` |
+| `selectorButtonPlacement` | - | Compose trigger position via `DateField.Prefix` or `DateField.Suffix` |
+| `visibleMonths` | - | Use `RangeCalendar` `visibleDuration` prop |
+| `showMonthAndYearPickers` | - | Use `RangeCalendar.YearPickerTrigger` and `RangeCalendar.YearPickerGrid` |
+| `calendarProps` | - | Pass props directly to `RangeCalendar` |
+| `popoverProps` | - | Pass props directly to `DateRangePicker.Popover` |
+| `selectorButtonProps` | - | Pass props directly to `DateRangePicker.Trigger` |
+| `timeInputProps` | - | Compose time input separately |
+| `calendarWidth` | - | Removed (use Tailwind CSS) |
+| `validate` | - | Handle validation externally |
+| `placeholderValue` | `placeholderValue` | Same |
+| `autoFocus` | `autoFocus` | Same |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual components |
+
+## Migration Examples
+
+### Basic DateRangePicker
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { DateRangePicker } from "@heroui/react";
+
+    <DateRangePicker label="Trip dates" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { DateRangePicker } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-14"),
+    });
+
+    <DateRangePicker
+      label="Trip dates"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { DateField, DateRangePicker, Label, RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-14"),
+    });
+
+    <DateRangePicker value={value} onChange={setValue}>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.Heading />
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### With Description and Error Message
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateRangePicker
+      label="Trip dates"
+      description="Select your travel period"
+      errorMessage="End date must be after start date"
+      isInvalid={isInvalid}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { DateField, DateRangePicker, Label, Description, FieldError, RangeCalendar } from "@heroui/react";
+
+    <DateRangePicker isInvalid={isInvalid}>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Select your travel period</Description>
+      <FieldError>End date must be after start date</FieldError>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          {/* RangeCalendar compound components */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Selector Icon
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DateRangePicker
+      label="Trip dates"
+      selectorIcon={<Icon icon="gravity-ui:calendar" />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator>
+              <Icon icon="gravity-ui:calendar" />
+            </DateRangePicker.TriggerIndicator>
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates">
+          {/* RangeCalendar compound components */}
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+### With Visible Months and Year Picker
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateRangePicker
+      label="Trip dates"
+      visibleMonths={2}
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateRangePicker>
+      <Label>Trip dates</Label>
+      <DateField.Group>
+        <DateField.InputContainer>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+        </DateField.InputContainer>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Choose trip dates" visibleDuration={{months: 2}}>
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <div className="flex gap-4">
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.Grid offset={{months: 1}}>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+          </div>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {(year) => <RangeCalendar.YearPickerCell date={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<DateRangePicker
+  classNames={{
+    base: "custom-base",
+    label: "custom-label",
+    selectorButton: "custom-trigger",
+    selectorIcon: "custom-icon",
+    separator: "custom-separator",
+    popoverContent: "custom-popover",
+    calendar: "custom-calendar",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<DateRangePicker className="custom-base">
+  <Label className="custom-label">Trip dates</Label>
+  <DateField.Group>
+    <DateField.InputContainer>
+      <DateField.Input slot="start">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateRangePicker.RangeSeparator className="custom-separator" />
+      <DateField.Input slot="end">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+    </DateField.InputContainer>
+    <DateField.Suffix>
+      <DateRangePicker.Trigger className="custom-trigger">
+        <DateRangePicker.TriggerIndicator className="custom-icon" />
+      </DateRangePicker.Trigger>
+    </DateField.Suffix>
+  </DateField.Group>
+  <DateRangePicker.Popover className="custom-popover">
+    <RangeCalendar aria-label="Choose trip dates" className="custom-calendar">
+      {/* RangeCalendar compound components */}
+    </RangeCalendar>
+  </DateRangePicker.Popover>
+</DateRangePicker>
+```
+
+## Component Anatomy
+
+The v3 DateRangePicker follows this structure:
+
+```
+DateRangePicker (Root)
+  ├── Label
+  ├── DateField.Group
+  │   ├── DateField.InputContainer
+  │   │   ├── DateField.Input slot="start"
+  │   │   │   └── DateField.Segment (render prop per segment)
+  │   │   ├── DateRangePicker.RangeSeparator
+  │   │   └── DateField.Input slot="end"
+  │   │       └── DateField.Segment (render prop per segment)
+  │   └── DateField.Suffix
+  │       └── DateRangePicker.Trigger
+  │           └── DateRangePicker.TriggerIndicator
+  ├── Description (optional)
+  ├── FieldError (optional)
+  └── DateRangePicker.Popover
+      └── RangeCalendar (see RangeCalendar migration guide)
+```
+
+## Summary
+
+1. **Component Structure**: Single component → composition of `DateRangePicker`, `DateField`, `RangeCalendar`, and `Label`
+2. **Dual Inputs**: Built-in start/end inputs → two `DateField.Input` with `slot="start"` and `slot="end"`
+3. **Separator**: Built-in → `DateRangePicker.RangeSeparator` component
+4. **Label**: `label` prop → `Label` component
+5. **Description/Error**: Props → `Description` and `FieldError` components
+6. **Calendar**: Built-in → compose `RangeCalendar` with its own compound components inside `DateRangePicker.Popover`
+7. **Selector Icon**: `selectorIcon` prop → pass children to `DateRangePicker.TriggerIndicator`
+8. **Year Picker**: `showMonthAndYearPickers` prop → use `RangeCalendar.YearPickerTrigger` and `RangeCalendar.YearPickerGrid`
+9. **Styling Props Removed**: `variant`, `color`, `size`, `radius` → use Tailwind CSS or `DateField.Group` variant
+10. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/dateinput.mdx b/apps/docs/content/docs/en/react/migration/(components)/dateinput.mdx
new file mode 100644
index 0000000..cb56ac6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/dateinput.mdx
@@ -0,0 +1,342 @@
+---
+title: DateInput
+description: Migration guide for DateInput to DateField from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 DateField documentation](/docs/react/components/date-field) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, DateInput was a single component with props:
+
+```tsx
+import { DateInput } from "@heroui/react";
+
+export default function App() {
+  return <DateInput label="Date" name="date" />;
+}
+```
+
+In v3, DateField requires compound components with DateInputGroup and a render prop for segments:
+
+```tsx
+import { DateField, DateInputGroup, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Naming
+
+**v2:** `DateInput`  
+**v3:** `DateField`
+
+### 2. Component Structure
+
+**v2:** Single component with props  
+**v3:** Compound components: `DateField` (root) + `DateInputGroup` with `DateInputGroup.Input` (render prop) and `DateInputGroup.Segment`; optionally `DateInputGroup.Prefix` and `DateInputGroup.Suffix`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `label` | - | Removed (use `Label` component) |
+| `description` | - | Removed (use `Description` component) |
+| `errorMessage` | - | Removed (use `FieldError` component) |
+| `value`, `defaultValue`, `onChange` | `DateField` | Same (React Aria) |
+| `minValue`, `maxValue`, `granularity`, `placeholderValue` | `DateField` | Same |
+| `isRequired`, `isDisabled`, `isReadOnly`, `isInvalid`, `name` | `DateField` | Same |
+| `createCalendar`, `validationBehavior` | `DateField` | Same |
+| `variant` | `DateInputGroup` | Simplified to `primary` \| `secondary` only |
+| `fullWidth` | `DateField` or `DateInputGroup` | On root or group |
+| `color` | - | Removed (use Tailwind CSS) |
+| `size` | - | Removed (use Tailwind CSS) |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `labelPlacement` | - | Removed (handle with layout) |
+| `startContent` | `DateInputGroup.Prefix` | Use Prefix child |
+| `endContent` | `DateInputGroup.Suffix` | Use Suffix child |
+| `classNames` | - | Use `className` on `DateField` and `DateInputGroup` parts |
+| `groupProps` | - | Removed (use `className` or DOM props on `DateInputGroup`) |
+| `labelProps` | - | Removed (use `className` on `Label`) |
+| `fieldProps` | - | Removed (use `className` on `DateInputGroup`) |
+| `innerWrapperProps` | - | Removed (use `className` on group/input parts) |
+| `descriptionProps` | - | Removed (use `className` on `Description`) |
+| `errorMessageProps` | - | Removed (use `className` on `FieldError`) |
+| `inputRef` | - | Removed (ref is handled by `DateField` / React Aria) |
+
+## Migration Examples
+
+### Basic
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput label="Date" name="date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### With Description and Error
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput
+      description="Select your birth date"
+      label="Birth date"
+      name="birthdate"
+    />
+
+    <DateInput
+      errorMessage="Please enter a valid date"
+      isInvalid
+      label="Date"
+      name="date"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    <DateField className="w-[256px]" name="birthdate">
+      <Label>Birth date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <Description>Select your birth date</Description>
+    </DateField>
+
+    <DateField className="w-[256px]" isInvalid name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <FieldError>Please enter a valid date</FieldError>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### Required
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput isRequired label="Date" name="date" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" isRequired name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState(null);
+
+    <DateInput
+      label="Date"
+      name="date"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import type { DateValue } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState<DateValue | null>(null);
+
+    <DateField
+      className="w-[256px]"
+      name="date"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### Min/Max and Granularity
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+
+    <DateInput
+      granularity="day"
+      label="Date"
+      maxValue={parseDate("2025-12-31")}
+      minValue={parseDate("2020-01-01")}
+      name="date"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { parseDate } from "@internationalized/date";
+
+    <DateField
+      className="w-[256px]"
+      granularity="day"
+      maxValue={parseDate("2025-12-31")}
+      minValue={parseDate("2020-01-01")}
+      name="date"
+    >
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### Start/End Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput
+      endContent={<CalendarIcon />}
+      label="Date"
+      name="date"
+      startContent={<CalendarIcon />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup>
+        <DateInputGroup.Prefix>
+          <CalendarIcon />
+        </DateInputGroup.Prefix>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+        <DateInputGroup.Suffix>
+          <CalendarIcon />
+        </DateInputGroup.Suffix>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DateInput label="Date" name="date" variant="bordered" />
+    <DateInput color="primary" label="Date" name="date" size="lg" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup variant="primary">
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateInputGroup variant="secondary">
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </DateField>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 DateField follows this structure:
+
+```
+DateField (Root)
+  ├── Label (optional)
+  ├── DateInputGroup
+  │   ├── DateInputGroup.Prefix (optional)
+  │   ├── DateInputGroup.Input → (segment) => DateInputGroup.Segment
+  │   └── DateInputGroup.Suffix (optional)
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## Summary
+
+1. **Component Renamed**: `DateInput` → `DateField`
+2. **Component Structure**: Must use compound components: `DateField` (root) and `DateInputGroup` with `DateInputGroup.Input` (render prop) and `DateInputGroup.Segment`
+3. **Label/Description/Error**: Use separate components (`Label`, `Description`, `FieldError`)
+4. **Date Props Unchanged**: `value`, `defaultValue`, `onChange`, `minValue`, `maxValue`, `granularity`, `placeholderValue`, `isRequired`, `isDisabled`, `isInvalid`, `name`, `createCalendar` stay on `DateField`
+5. **Variant on DateInputGroup**: v3 supports only `variant="primary"` and `variant="secondary"` on `DateInputGroup`; `color`, `size`, `radius` removed — use Tailwind CSS
+6. **Start/End Content**: `startContent`/`endContent` → `DateInputGroup.Prefix` and `DateInputGroup.Suffix`
+7. **Label Placement Removed**: `labelPlacement` removed — handle with layout
+8. **DOM/Class Props**: `groupProps`, `labelProps`, `fieldProps`, `classNames` removed — use `className` (and standard DOM props) on the relevant parts
diff --git a/apps/docs/content/docs/en/react/migration/(components)/divider.mdx b/apps/docs/content/docs/en/react/migration/(components)/divider.mdx
new file mode 100644
index 0000000..3a272d6
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/divider.mdx
@@ -0,0 +1,99 @@
+---
+title: Divider
+description: Migration guide for Divider (renamed to Separator) from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Separator documentation](/docs/react/components/separator) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Component Rename
+
+**v2:** `Divider`  
+**v3:** `Separator`
+
+## Key Changes
+
+### 1. Component Name
+
+**v2:** `Divider`  
+**v3:** `Separator`
+
+### 2. Variant Prop
+
+**v3:** Separator has a `variant` prop: `default`, `secondary`, `tertiary` for different emphasis levels (v2 Divider had no variant).
+
+### 3. Props Comparison
+
+| Prop | v2 | v3 | Notes |
+|------|----|----|-------|
+| `orientation` | ✅ | ✅ | Same: `"horizontal"` \| `"vertical"` |
+| `className` | ✅ | ✅ | Same |
+| `variant` | ❌ | ✅ | New: `"default"` \| `"secondary"` \| `"tertiary"` |
+
+## Structure Changes
+
+In v2, the component was named `Divider`:
+
+```tsx
+import { Divider } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div>
+      <p>Content above</p>
+      <Divider />
+      <p>Content below</p>
+    </div>
+  );
+}
+```
+
+In v3, the component has been renamed to `Separator`:
+
+```tsx
+import { Separator } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div>
+      <p>Content above</p>
+      <Separator />
+      <p>Content below</p>
+    </div>
+  );
+}
+```
+
+## Migration Examples
+
+### With Variant
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 has no variant prop */}
+    <Divider />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Separator />
+    <Separator variant="secondary" />
+    <Separator variant="tertiary" />
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+1. **Component Renamed**: `Divider` → `Separator`
+2. **Import Change**: Update import from `Divider` to `Separator`
+3. **New in v3**: `variant` prop (`default`, `secondary`, `tertiary`) for emphasis levels
+
+## Migration Steps
+
+1. **Update Import**: Change `import { Divider }` to `import { Separator }`
+2. **Update Component**: Replace all `<Divider />` with `<Separator />`
+3. **Same Props**: `orientation` and `className` work the same
+4. **Optional**: Use `variant="secondary"` or `variant="tertiary"` for different emphasis
diff --git a/apps/docs/content/docs/en/react/migration/(components)/drawer.mdx b/apps/docs/content/docs/en/react/migration/(components)/drawer.mdx
new file mode 100644
index 0000000..0e2c7ef
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/drawer.mdx
@@ -0,0 +1,427 @@
+---
+title: Drawer
+description: Migration guide for Drawer from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Drawer documentation](/docs/react/components/drawer) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Drawer` shared the same API as `Modal`, using `DrawerContent`, `DrawerHeader`, `DrawerBody`, and `DrawerFooter` with a render callback pattern:
+
+```tsx
+import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Drawer</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="right">
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Drawer Title</DrawerHeader>
+              <DrawerBody>
+                <p>Drawer content goes here.</p>
+              </DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+  );
+}
+```
+
+In v3, Drawer uses a compound component pattern with explicit subcomponents and built-in trigger support:
+
+```tsx
+import { Drawer, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Drawer>
+      <Button>Open Drawer</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.Handle />
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Drawer Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>Drawer content goes here.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** `Drawer` wrapping `DrawerContent` with a render callback pattern; separate trigger via `useDisclosure`
+**v3:** Compound components: `Drawer`, `Drawer.Backdrop`, `Drawer.Content`, `Drawer.Dialog`, `Drawer.Header`, `Drawer.Heading`, `Drawer.Body`, `Drawer.Footer`, `Drawer.Handle`, `Drawer.CloseTrigger`. Trigger is the first child of `Drawer`.
+
+### 2. Trigger Pattern
+
+**v2:** External trigger using `useDisclosure` hook with `isOpen`/`onOpenChange`
+**v3:** Built-in trigger — first child of `Drawer` becomes the trigger automatically. Controlled state available via `useOverlayState` hook.
+
+### 3. New Features in v3
+
+- **Drag to dismiss**: Built-in pointer-based drag gestures on handle, header, and footer areas
+- **Drag handle**: `Drawer.Handle` component for visual drag indicator
+- **Built-in close trigger**: `Drawer.CloseTrigger` renders a close button
+- **Slot-based close**: Buttons with `slot="close"` automatically close the drawer
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `isOpen` | `Drawer.Backdrop` `isOpen` | Or use `useOverlayState` |
+| `onOpenChange` | `Drawer.Backdrop` `onOpenChange` | Or use `useOverlayState` |
+| `onClose` | - | Use `onOpenChange` or `slot="close"` on buttons |
+| `placement` | `Drawer.Content` `placement` | `"right"` → `"right"`, `"left"` → `"left"`, `"top"` → `"top"`, `"bottom"` → `"bottom"`. Default changed from `"right"` to `"bottom"` |
+| `size` | - | Removed (use Tailwind CSS on `Drawer.Dialog`) |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `backdrop` | `Drawer.Backdrop` `variant` | Same values: `"opaque"`, `"blur"`, `"transparent"` |
+| `isDismissable` | `Drawer.Backdrop` `isDismissable` | Same |
+| `isKeyboardDismissDisabled` | `Drawer.Backdrop` `isKeyboardDismissDisabled` | Same |
+| `shouldBlockScroll` | - | Always blocks scroll in v3 |
+| `hideCloseButton` | - | Omit `Drawer.CloseTrigger` to hide |
+| `closeButton` | - | Pass custom content to `Drawer.CloseTrigger` |
+| `motionProps` | - | Removed (CSS-based animations in v3) |
+| `disableAnimation` | - | Removed |
+| `portalContainer` | - | Removed |
+| `classNames` | - | Use `className` on individual compound components |
+
+### 5. Hook Changes
+
+**v2:** `useDisclosure` hook for open/close state
+**v3:** `useOverlayState` hook (replaces `useDisclosure`)
+
+```tsx
+// v2
+const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+// v3
+const state = useOverlayState();
+// state.isOpen, state.open(), state.close(), state.toggle()
+```
+
+## Migration Examples
+
+### Basic Drawer
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, Button, useDisclosure } from "@heroui/react";
+
+    const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+    <>
+      <Button onPress={onOpen}>Open</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Title</DrawerHeader>
+              <DrawerBody>Content</DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Drawer, Button } from "@heroui/react";
+
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Close</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### Placement
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="left">
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Left Drawer</DrawerHeader>
+            <DrawerBody>Content</DrawerBody>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="left">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Left Drawer</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### Backdrop Variant
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer isOpen={isOpen} onOpenChange={onOpenChange} backdrop="blur">
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Blurred Backdrop</DrawerHeader>
+            <DrawerBody>Content</DrawerBody>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop variant="blur">
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Blurred Backdrop</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Content</Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useDisclosure } from "@heroui/react";
+
+    const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+    <>
+      <Button onPress={onOpen}>Open</Button>
+      <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>
+        <DrawerContent>
+          {(onClose) => (
+            <>
+              <DrawerHeader>Controlled</DrawerHeader>
+              <DrawerBody>Content</DrawerBody>
+              <DrawerFooter>
+                <Button onPress={onClose}>Close</Button>
+              </DrawerFooter>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    const state = useOverlayState();
+
+    <>
+      <Button onPress={state.open}>Open</Button>
+      <Drawer state={state}>
+        <Drawer.Backdrop>
+          <Drawer.Content>
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>Controlled</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>Content</Drawer.Body>
+              <Drawer.Footer>
+                <Button onPress={state.close}>Close</Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </Drawer>
+    </>
+    ```
+  </Tab>
+</Tabs>
+
+### Non-Dismissable
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Drawer
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      isDismissable={false}
+      hideCloseButton
+    >
+      <DrawerContent>
+        {(onClose) => (
+          <>
+            <DrawerHeader>Confirm Action</DrawerHeader>
+            <DrawerBody>Are you sure?</DrawerBody>
+            <DrawerFooter>
+              <Button onPress={onClose}>Confirm</Button>
+            </DrawerFooter>
+          </>
+        )}
+      </DrawerContent>
+    </Drawer>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Drawer>
+      <Button>Open</Button>
+      <Drawer.Backdrop isDismissable={false}>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>Confirm Action</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>Are you sure?</Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close">Confirm</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Drawer
+  classNames={{
+    wrapper: "custom-wrapper",
+    base: "custom-base",
+    backdrop: "custom-backdrop",
+    header: "custom-header",
+    body: "custom-body",
+    footer: "custom-footer",
+    closeButton: "custom-close",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Drawer>
+  <Button>Open</Button>
+  <Drawer.Backdrop className="custom-backdrop">
+    <Drawer.Content>
+      <Drawer.Dialog className="custom-base">
+        <Drawer.CloseTrigger className="custom-close" />
+        <Drawer.Header className="custom-header">
+          <Drawer.Heading>Title</Drawer.Heading>
+        </Drawer.Header>
+        <Drawer.Body className="custom-body">Content</Drawer.Body>
+        <Drawer.Footer className="custom-footer">Actions</Drawer.Footer>
+      </Drawer.Dialog>
+    </Drawer.Content>
+  </Drawer.Backdrop>
+</Drawer>
+```
+
+## Component Anatomy
+
+The v3 Drawer follows this structure:
+
+```
+Drawer (Root)
+  ├── [Trigger element] (first child becomes trigger)
+  └── Drawer.Backdrop
+      └── Drawer.Content (placement)
+          └── Drawer.Dialog
+              ├── Drawer.Handle (optional, drag indicator)
+              ├── Drawer.CloseTrigger (optional, close button)
+              ├── Drawer.Header
+              │   └── Drawer.Heading
+              ├── Drawer.Body (scrollable)
+              └── Drawer.Footer
+```
+
+## Summary
+
+1. **Component Structure**: Render callback pattern → compound components with explicit subcomponents
+2. **Trigger Pattern**: External `useDisclosure` + `onPress` → built-in trigger (first child of `Drawer`)
+3. **State Hook**: `useDisclosure` → `useOverlayState` with `open()`, `close()`, `toggle()` methods
+4. **Placement**: Prop on `Drawer` → prop on `Drawer.Content`. Default changed from `"right"` to `"bottom"`
+5. **Backdrop**: `backdrop` prop → `Drawer.Backdrop` `variant` prop
+6. **Close Button**: `hideCloseButton`/`closeButton` props → omit or customize `Drawer.CloseTrigger`
+7. **Slot-Based Close**: Buttons with `slot="close"` automatically close the drawer
+8. **New Features**: Drag-to-dismiss with `Drawer.Handle`, velocity-based dismissal
+9. **Animations**: `motionProps` (Framer Motion) → CSS-based animations
+10. **Styling Props Removed**: `size`, `radius` → use Tailwind CSS
+11. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/dropdown.mdx b/apps/docs/content/docs/en/react/migration/(components)/dropdown.mdx
new file mode 100644
index 0000000..904ec16
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/dropdown.mdx
@@ -0,0 +1,466 @@
+---
+title: Dropdown
+description: Migration guide for Dropdown from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Dropdown documentation](/docs/react/components/dropdown) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Dropdown used separate components: `DropdownTrigger`, `DropdownMenu`, `DropdownItem`, `DropdownSection`:
+
+```tsx
+import { Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Dropdown>
+      <DropdownTrigger>
+        <Button>Open Menu</Button>
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem key="new">New file</DropdownItem>
+        <DropdownItem key="copy">Copy link</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+```
+
+In v3, Dropdown uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { Dropdown, Button, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Dropdown>
+      <Button>Open Menu</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="new" textValue="New file">
+            <Label>New file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy" textValue="Copy link">
+            <Label>Copy link</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Separate components: `DropdownTrigger`, `DropdownMenu`, `DropdownItem`, `DropdownSection`  
+**v3:** Compound components: `Dropdown.Trigger`, `Dropdown.Popover`, `Dropdown.Menu`, `Dropdown.Item`, `Dropdown.Section`
+
+### 2. Component Name Changes
+
+| v2 Component | v3 Component | Notes |
+|-------------|--------------|-------|
+| `DropdownTrigger` | `Dropdown.Trigger` | Same functionality |
+| `DropdownMenu` | `Dropdown.Menu` | Wrapped in `Dropdown.Popover` |
+| `DropdownItem` | `Dropdown.Item` | Use `id` and `textValue`; keep `key` on list items |
+| `DropdownSection` | `Dropdown.Section` | Same functionality |
+| - | `Dropdown.Popover` | New wrapper component (required) |
+
+### 3. Item Identification
+
+**v2:** Item content passed as children; React's `key` was used for both list reconciliation and item identity (selection, focus).  
+**v3:** Item content must use `Label` component for text. Give each item an `id` (for state/focus) and `textValue` (for accessibility when content isn't plain text). Keep React's `key` on items in lists.
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `variant`, `color` (on DropdownMenu) | - | Removed (no menu variants) |
+| `classNames`, `itemClasses` (on DropdownMenu) | - | Use `className` on Menu and items |
+| `color` (on DropdownItem) | `Dropdown.Item` | Use `variant="danger"` for danger |
+| `title` | - | Use `Label` component as child |
+| `description` | - | Use `Description` component as child |
+| `shortcut` | - | Use `Kbd` component as child |
+| `startContent`, `endContent` | - | Use icon/components as children |
+| `selectedIcon` | - | Use `Dropdown.ItemIndicator` |
+| `showDivider` | - | Use `Separator` between items |
+| `classNames` (on DropdownItem) | - | Use `className` on item |
+| `isSelected` | `Dropdown.Menu` | Use `selectedKeys` on Menu |
+| `isDisabled` | `Dropdown.Menu` | Use `disabledKeys` on Menu |
+| `trigger` (on Dropdown) | `Dropdown` | Still supported: `"press"` (default) or `"longPress"` |
+
+### 5. New Components
+
+- `Dropdown.Popover` - Required wrapper around `Dropdown.Menu`
+- `Dropdown.ItemIndicator` - For selection indicators (checkmark/dot)
+- `Dropdown.SubmenuTrigger` - For submenu functionality
+- `Dropdown.SubmenuIndicator` - For submenu chevron indicator
+
+## Migration Examples
+
+### With Action Handler
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownMenu onAction={(key) => alert(key)}>
+      <DropdownItem key="new">New file</DropdownItem>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown.Menu onAction={(key) => alert(key)}>
+      <Dropdown.Item id="new" textValue="New file">
+        <Label>New file</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### Item Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With icon */}
+    <DropdownItem
+      key="new"
+      startContent={<AddNoteIcon />}
+    >
+      New file
+    </DropdownItem>
+    
+    {/* With description */}
+    <DropdownItem
+      key="edit"
+      description="Edit the file"
+    >
+      Edit file
+    </DropdownItem>
+    
+    {/* With shortcut */}
+    <DropdownItem
+      key="copy"
+      shortcut="⌘C"
+    >
+      Copy
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+    import { Label, Description, Kbd } from "@heroui/react";
+
+    {/* With icon */}
+    <Dropdown.Item id="new" textValue="New file">
+      <Icon icon="gravity-ui:square-plus" />
+      <Label>New file</Label>
+    </Dropdown.Item>
+    
+    {/* With description */}
+    <Dropdown.Item id="edit" textValue="Edit file">
+      <Label>Edit file</Label>
+      <Description>Edit the file</Description>
+    </Dropdown.Item>
+    
+    {/* With shortcut */}
+    <Dropdown.Item id="copy" textValue="Copy">
+      <Label>Copy</Label>
+      <Kbd slot="keyboard" variant="light">
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+    </Dropdown.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### Danger Item
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownItem
+      key="delete"
+      className="text-danger"
+      color="danger"
+    >
+      Delete file
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown.Item id="delete" textValue="Delete file" variant="danger">
+      <Label>Delete file</Label>
+    </Dropdown.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### With Sections
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownMenu>
+      <DropdownSection showDivider title="Actions">
+        <DropdownItem key="new">New file</DropdownItem>
+        <DropdownItem key="edit">Edit file</DropdownItem>
+      </DropdownSection>
+      <DropdownSection title="Danger zone">
+        <DropdownItem key="delete" color="danger">Delete file</DropdownItem>
+      </DropdownSection>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Separator } from "@heroui/react";
+
+    <Dropdown.Menu>
+      <Dropdown.Section>
+        <Header>Actions</Header>
+        <Dropdown.Item id="new" textValue="New file">
+          <Label>New file</Label>
+        </Dropdown.Item>
+        <Dropdown.Item id="edit" textValue="Edit file">
+          <Label>Edit file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+      <Separator />
+      <Dropdown.Section>
+        <Header>Danger zone</Header>
+        <Dropdown.Item id="delete" textValue="Delete file" variant="danger">
+          <Label>Delete file</Label>
+        </Dropdown.Item>
+      </Dropdown.Section>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### Selection
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+    <DropdownMenu
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <DropdownItem key="text">Text</DropdownItem>
+      <DropdownItem key="number">Number</DropdownItem>
+    </DropdownMenu>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["bold"]));
+    <DropdownMenu
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <DropdownItem key="bold">Bold</DropdownItem>
+      <DropdownItem key="italic">Italic</DropdownItem>
+    </DropdownMenu>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+    <Dropdown.Menu
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <Dropdown.Item id="text" textValue="Text">
+        <Dropdown.ItemIndicator />
+        <Label>Text</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="number" textValue="Number">
+        <Dropdown.ItemIndicator />
+        <Label>Number</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["bold"]));
+    <Dropdown.Menu
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <Dropdown.Item id="bold" textValue="Bold">
+        <Dropdown.ItemIndicator />
+        <Label>Bold</Label>
+      </Dropdown.Item>
+      <Dropdown.Item id="italic" textValue="Italic">
+        <Dropdown.ItemIndicator />
+        <Label>Italic</Label>
+      </Dropdown.Item>
+    </Dropdown.Menu>
+    ```
+  </Tab>
+</Tabs>
+
+### With Keyboard Shortcuts
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <DropdownItem key="copy" shortcut="⌘C">
+      Copy
+    </DropdownItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Kbd } from "@heroui/react";
+
+    <Dropdown.Item id="copy" textValue="Copy">
+      <Label>Copy</Label>
+      <Kbd slot="keyboard" variant="light">
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+    </Dropdown.Item>
+    ```
+
+    The `slot="keyboard"` prop on `Kbd` positions the shortcut at the end of the menu item, replacing the v2 `shortcut` prop.
+  </Tab>
+</Tabs>
+
+### With Submenus
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have built-in submenu support */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label } from "@heroui/react";
+
+    <Dropdown.Menu>
+      <Dropdown.Item id="copy-link" textValue="Copy Link">
+        <Label>Copy Link</Label>
+      </Dropdown.Item>
+      <Dropdown.SubmenuTrigger>
+        <Dropdown.Item id="share" textValue="Share">
+          <Label>Share</Label>
+          <Dropdown.SubmenuIndicator />
+        </Dropdown.Item>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+              <Label>WhatsApp</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="telegram" textValue="Telegram">
+              <Label>Telegram</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown.SubmenuTrigger>
+    </Dropdown.Menu>
+    ```
+
+    Use `Dropdown.SubmenuTrigger` to wrap an item that opens a nested menu. Place `Dropdown.SubmenuIndicator` inside the item to render a chevron icon.
+  </Tab>
+</Tabs>
+
+### Long Press Trigger
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Dropdown>
+      <DropdownTrigger>
+        <Button>Long press me</Button>
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem key="cut">Cut</DropdownItem>
+        <DropdownItem key="copy">Copy</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Dropdown trigger="longPress">
+      <Button>Long press me</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="cut" textValue="Cut">
+            <Label>Cut</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy" textValue="Copy">
+            <Label>Copy</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+    ```
+
+    The `trigger` prop on `Dropdown` accepts `"press"` (default) or `"longPress"` to control how the menu is opened.
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Dropdown follows this structure:
+
+```
+Dropdown (Root) — accepts trigger="press" | "longPress"
+  ├── Dropdown.Trigger (optional, defaults to first child)
+  ├── Dropdown.Popover (required wrapper)
+  │   └── Dropdown.Menu
+  │       ├── Dropdown.Item
+  │       │   ├── Icon (optional, first child)
+  │       │   ├── Label (required for text)
+  │       │   ├── Description (optional)
+  │       │   ├── Kbd slot="keyboard" (optional, for shortcuts)
+  │       │   └── Dropdown.ItemIndicator (optional, for selection)
+  │       ├── Separator (for dividers)
+  │       ├── Dropdown.Section
+  │       │   ├── Header (optional)
+  │       │   └── Dropdown.Item
+  │       └── Dropdown.SubmenuTrigger
+  │           ├── Dropdown.Item
+  │           │   ├── Label
+  │           │   └── Dropdown.SubmenuIndicator (chevron icon)
+  │           └── Dropdown.Popover
+  │               └── Dropdown.Menu
+  │                   └── Dropdown.Item
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Dropdown.Trigger`, `Dropdown.Popover`, `Dropdown.Menu`, etc.)
+2. **Dropdown.Popover Required**: `Dropdown.Menu` must be wrapped in `Dropdown.Popover`
+3. **Label Component**: Item text must use `Label` component
+4. **Description Component**: Use `Description` component instead of `description` prop
+5. **Kbd Component**: Use `Kbd` with `slot="keyboard"` instead of the `shortcut` prop — the slot positions the shortcut at the end of the menu item
+6. **Icons as Children**: Icons go as first child, not `startContent` prop
+7. **Separator Component**: Use `Separator` instead of `showDivider` prop
+8. **ItemIndicator Component**: Use `Dropdown.ItemIndicator` for selection indicators
+9. **Variant Instead of Color**: Use `variant="danger"` instead of `color="danger"`
+10. **No Menu Variants**: `Dropdown.Menu` no longer supports `variant` or `color` props
+11. **ClassNames Removed**: Use `className` props on individual components
+12. **Submenu Support**: Use `Dropdown.SubmenuTrigger` to wrap an item that opens a nested menu, and `Dropdown.SubmenuIndicator` inside the item for a chevron icon
+13. **Trigger Prop**: Use `trigger="longPress"` on `Dropdown` root to open the menu on long press instead of the default press
diff --git a/apps/docs/content/docs/en/react/migration/(components)/form.mdx b/apps/docs/content/docs/en/react/migration/(components)/form.mdx
new file mode 100644
index 0000000..537440f
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/form.mdx
@@ -0,0 +1,116 @@
+---
+title: Form
+description: Migration guide for Form from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Form documentation](/docs/react/components/form) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Key Changes
+
+### 1. Form Component Props
+
+The Form component props remain the same between v2 and v3, with one addition:
+
+| Prop | v2 | v3 | Notes |
+|------|----|----|-------|
+| `validationBehavior` | ✅ | ✅ | Same: `"native"` \| `"aria"` |
+| `validationErrors` | ✅ | ✅ | Same: `Record<string, string \| string[]>` |
+| `onSubmit` | ✅ | ✅ | Same |
+| `onReset` | ✅ | ✅ | Same |
+| `action` | ✅ | ✅ | Same |
+| `method` | ✅ | ✅ | Same |
+| `encType` | ✅ | ✅ | Same |
+| `target` | ✅ | ✅ | Same |
+| `className` | ✅ | ✅ | Same |
+| `onInvalid` | ❌ | ✅ | New: Handler called when form validation fails |
+
+## Structure Changes
+
+In v2, Form component usage:
+
+```tsx
+import { Form, Button } from "@heroui/react";
+
+export default function App() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log("Form submitted");
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+In v3, Form component usage remains the same:
+
+```tsx
+import { Form, Button } from "@heroui/react";
+
+export default function App() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log("Form submitted");
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+## Migration Examples
+
+### Form with Invalid Handler (New in v3)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 doesn't have onInvalid prop */}
+    <Form onSubmit={onSubmit}>
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Form
+      onInvalid={(e) => {
+        e.preventDefault();
+        // Custom handling when form validation fails
+        console.log("Form validation failed");
+      }}
+      onSubmit={onSubmit}
+    >
+      {/* Form content */}
+      <Button type="submit">Submit</Button>
+    </Form>
+    ```
+  </Tab>
+</Tabs>
+
+The `onInvalid` handler is called when form validation fails. By default, the first invalid field will be focused. Use `e.preventDefault()` to customize this behavior.
+
+## Summary
+
+1. **Form Component**: No breaking changes - same props and behavior
+2. **New Prop**: `onInvalid` prop available for custom validation error handling
+
+## Migration Steps
+
+1. **No changes required**: The Form component works the same way in v3
+2. **Optional**: Use the new `onInvalid` prop if you need custom handling for validation failures
+
+## Note on Form Fields
+
+While the Form component itself is unchanged, form field components (like `Input`, `TextField`, etc.) have been updated in v3. Refer to their respective migration guides for details on migrating form fields within your forms.
diff --git a/apps/docs/content/docs/en/react/migration/(components)/image.mdx b/apps/docs/content/docs/en/react/migration/(components)/image.mdx
new file mode 100644
index 0000000..b420da0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/image.mdx
@@ -0,0 +1,522 @@
+---
+title: Image
+description: Migration guide for Image from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The Image component has been **removed** in HeroUI v3. Use native HTML `<img>` element or Next.js `Image` component with Tailwind CSS classes instead.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<Image>` component from `@heroui/react`  
+**v3:** Native HTML `<img>` element or Next.js `Image` component
+
+### 2. Features Mapping
+
+The v2 Image component had several features that need to be replaced:
+
+| v2 Feature | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| `radius` prop | `rounded-*` Tailwind classes | Use `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-full` |
+| `shadow` prop | `shadow-*` Tailwind classes | Use `shadow-sm`, `shadow-md`, `shadow-lg` |
+| `isBlurred` prop | Manual blur implementation | Use CSS `filter: blur()` or Tailwind `blur-*` utilities |
+| `isZoomed` prop | Manual hover zoom | Use `hover:scale-*` Tailwind classes |
+| `fallbackSrc` prop | Manual error handling | Use `onError` handler with state |
+| `disableSkeleton` / Loading skeleton | Manual loading state | Use React state + conditional rendering |
+| `removeWrapper` prop | Direct rendering | No wrapper needed, render `<img>` directly |
+
+## Structure Changes
+
+In v2, `Image` was a component wrapper around the native `<img>` element:
+
+```tsx
+import { Image } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example image"
+      width={300}
+      height={200}
+    />
+  );
+}
+```
+
+In v3, use the native `<img>` element directly with Tailwind CSS classes:
+
+```tsx
+export default function App() {
+  return (
+    <img
+      src="https://example.com/image.jpg"
+      alt="Example image"
+      width={300}
+      height={200}
+      className="rounded-lg"
+    />
+  );
+}
+```
+
+## Migration Examples
+
+### With Next.js Image (Recommended)
+
+If you're using Next.js, use the optimized `Image` component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    <Image
+      src="/image.jpg"
+      alt="Example"
+      width={300}
+      height={200}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import Image from "next/image";
+
+    <Image
+      src="/image.jpg"
+      alt="Example"
+      width={300}
+      height={200}
+      className="rounded-lg"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+### With Zoom Effect
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image isZoomed src="..." alt="..." />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative overflow-hidden rounded-lg">
+      <img
+        src="..."
+        alt="..."
+        className="object-cover transition-transform duration-300 hover:scale-125"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### With Blur Effect
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image isBlurred src="..." alt="..." />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative">
+      <img
+        src="..."
+        alt="..."
+        className="relative z-10"
+      />
+      <img
+        src="..."
+        alt=""
+        aria-hidden="true"
+        className="absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### With Fallback Image
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      fallbackSrc="/fallback.jpg"
+      alt="Example"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    function ImageWithFallback({ src, fallbackSrc, alt, ...props }) {
+      const [imgSrc, setImgSrc] = useState(src);
+
+      return (
+        <img
+          src={imgSrc}
+          alt={alt}
+          onError={() => setImgSrc(fallbackSrc)}
+          {...props}
+        />
+      );
+    }
+
+    <ImageWithFallback
+      src="https://example.com/image.jpg"
+      fallbackSrc="/fallback.jpg"
+      alt="Example"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+### With Loading Skeleton
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example"
+      disableSkeleton={false}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    function ImageWithSkeleton({ src, alt, ...props }) {
+      const [isLoading, setIsLoading] = useState(true);
+      const [hasError, setHasError] = useState(false);
+
+      return (
+        <div className="relative overflow-hidden rounded-lg bg-default-200">
+          {isLoading && (
+            <div className="absolute inset-0 animate-pulse bg-gradient-to-r from-transparent via-default-300 to-transparent" />
+          )}
+          <img
+            src={src}
+            alt={alt}
+            className={`transition-opacity duration-300 ${
+              isLoading ? "opacity-0" : "opacity-100"
+            }`}
+            onLoad={() => setIsLoading(false)}
+            onError={() => {
+              setIsLoading(false);
+              setHasError(true);
+            }}
+            {...props}
+          />
+        </div>
+      );
+    }
+
+    <ImageWithSkeleton src="https://example.com/image.jpg" alt="Example" />
+    ```
+  </Tab>
+</Tabs>
+
+### Combined Features
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Image
+      src="https://example.com/image.jpg"
+      alt="Example"
+      radius="lg"
+      shadow="md"
+      isZoomed
+      isBlurred
+      width={400}
+      height={300}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="relative overflow-hidden rounded-lg shadow-md">
+      <img
+        src="https://example.com/image.jpg"
+        alt="Example"
+        width={400}
+        height={300}
+        className="relative z-10 object-cover transition-transform duration-300 hover:scale-125"
+      />
+      <img
+        src="https://example.com/image.jpg"
+        alt=""
+        aria-hidden="true"
+        className="absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150"
+      />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a Reusable Image Component (Optional)
+
+If you frequently use images with similar features, you can create a reusable component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    <Image
+      src="..."
+      radius="lg"
+      shadow="md"
+      isZoomed
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { cn } from "@/lib/utils"; // or your cn utility
+
+    interface CustomImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+      shadow?: "none" | "sm" | "md" | "lg";
+      isZoomed?: boolean;
+      isBlurred?: boolean;
+      fallbackSrc?: string;
+    }
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    const shadowClasses = {
+      none: "shadow-none",
+      sm: "shadow-sm",
+      md: "shadow-md",
+      lg: "shadow-lg",
+    };
+
+    export function CustomImage({
+      src,
+      alt,
+      className,
+      radius = "lg",
+      shadow = "none",
+      isZoomed = false,
+      isBlurred = false,
+      fallbackSrc,
+      onError,
+      ...props
+    }: CustomImageProps) {
+      const [imgSrc, setImgSrc] = useState(src);
+      const [isLoading, setIsLoading] = useState(true);
+
+      const handleError = (e: React.SyntheticEvent<HTMLImageElement, Event>) => {
+        if (fallbackSrc && imgSrc !== fallbackSrc) {
+          setImgSrc(fallbackSrc);
+        }
+        onError?.(e);
+      };
+
+      const imageElement = (
+        <img
+          src={imgSrc}
+          alt={alt}
+          className={cn(
+            radiusClasses[radius],
+            shadowClasses[shadow],
+            isZoomed && "object-cover transition-transform duration-300 hover:scale-125",
+            isLoading && "opacity-0",
+            "transition-opacity duration-300",
+            className
+          )}
+          onLoad={() => setIsLoading(false)}
+          onError={handleError}
+          {...props}
+        />
+      );
+
+      if (isBlurred) {
+        return (
+          <div className={cn("relative", radiusClasses[radius], shadowClasses[shadow])}>
+            {imageElement}
+            <img
+              src={imgSrc}
+              alt=""
+              aria-hidden="true"
+              className={cn(
+                "absolute inset-0 z-0 h-full w-full scale-105 object-cover blur-lg opacity-30 saturate-150",
+                radiusClasses[radius]
+              )}
+            />
+          </div>
+        );
+      }
+
+      if (isZoomed || isLoading) {
+        return (
+          <div className={cn("relative overflow-hidden", radiusClasses[radius], shadowClasses[shadow])}>
+            {isLoading && (
+              <div className="absolute inset-0 animate-pulse bg-gradient-to-r from-transparent via-default-300 to-transparent" />
+            )}
+            {imageElement}
+          </div>
+        );
+      }
+
+      return imageElement;
+    }
+
+    // Usage
+    <CustomImage
+      src="..."
+      alt="Example"
+      radius="lg"
+      shadow="md"
+      isZoomed
+      isBlurred
+      fallbackSrc="/fallback.jpg"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+## Complete Example
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Image } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <Image
+            src="https://example.com/image1.jpg"
+            alt="Image 1"
+            width={300}
+            height={200}
+            radius="lg"
+            shadow="md"
+          />
+          <Image
+            src="https://example.com/image2.jpg"
+            alt="Image 2"
+            width={300}
+            height={200}
+            isZoomed
+            radius="lg"
+          />
+          <Image
+            src="https://example.com/image3.jpg"
+            alt="Image 3"
+            width={300}
+            height={200}
+            isBlurred
+            radius="full"
+          />
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    export default function App() {
+      return (
+        <div className="space-y-4">
+          <img
+            src="https://example.com/image1.jpg"
+            alt="Image 1"
+            width={300}
+            height={200}
+            className="rounded-lg shadow-md"
+          />
+          <div className="relative overflow-hidden rounded-lg">
+            <img
+              src="https://example.com/image2.jpg"
+              alt="Image 2"
+              width={300}
+              height={200}
+              className="object-cover transition-transform duration-300 hover:scale-125"
+            />
+          </div>
+          <div className="relative rounded-full">
+            <img
+              src="https://example.com/image3.jpg"
+              alt="Image 3"
+              width={300}
+              height={300}
+              className="relative z-10 rounded-full"
+            />
+            <img
+              src="https://example.com/image3.jpg"
+              alt=""
+              aria-hidden="true"
+              className="absolute inset-0 z-0 h-full w-full scale-105 object-cover rounded-full blur-lg opacity-30 saturate-150"
+            />
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+1. **Component Removed**: `Image` component no longer exists in v3
+2. **Import Change**: Remove `import { Image } from "@heroui/react"`
+3. **Use Native Element**: Replace with native `<img>` HTML element or Next.js `Image`
+4. **Features**: Implement blur, zoom, skeleton, and fallback manually
+5. **Styling**: Apply Tailwind CSS classes directly for radius, shadow, and effects
+
+## Migration Steps
+
+1. **Remove Import**: Remove `Image` from `@heroui/react` imports
+2. **Replace Component**: Replace all `<Image>` instances with `<img>` elements
+3. **Add Tailwind Classes**: Apply equivalent Tailwind classes for styling (radius, shadow)
+4. **Implement Features**: Add manual implementations for blur, zoom, skeleton, and fallback if needed
+5. **Use Next.js Image**: If using Next.js, consider using `next/image` for optimization
+6. **Optional**: Create reusable wrapper components for frequently used patterns
+
+## Next.js Image Component
+
+If you're using Next.js, the `Image` component from `next/image` provides:
+
+- Automatic image optimization
+- Lazy loading by default
+- Responsive images with `srcSet`
+- Placeholder blur support
+- Built-in loading states
+
+```tsx
+import Image from "next/image";
+
+<Image
+  src="/image.jpg"
+  alt="Example"
+  width={300}
+  height={200}
+  className="rounded-lg shadow-md"
+  placeholder="blur" // Optional: blur placeholder
+  blurDataURL="data:image/..." // Optional: base64 blur data
+/>
+```
diff --git a/apps/docs/content/docs/en/react/migration/(components)/input-otp.mdx b/apps/docs/content/docs/en/react/migration/(components)/input-otp.mdx
new file mode 100644
index 0000000..ce92b88
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/input-otp.mdx
@@ -0,0 +1,275 @@
+---
+title: InputOTP
+description: Migration guide for InputOTP from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 InputOTP documentation](/docs/react/components/input-otp) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, InputOtp automatically rendered segments based on the `length` prop:
+
+```tsx
+import { InputOtp } from "@heroui/react";
+
+export default function App() {
+  return <InputOtp length={4} />;
+}
+```
+
+In v3, InputOTP requires manual definition of slots using compound components:
+
+```tsx
+import { InputOTP } from "@heroui/react";
+
+export default function App() {
+  return (
+    <InputOTP maxLength={4}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single component with automatic segment rendering  
+**v3:** Compound components: `InputOTP.Group`, `InputOTP.Slot`, `InputOTP.Separator`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `length` | `InputOTP` | Renamed to `maxLength` |
+| `allowedKeys` | `InputOTP` | Renamed to `pattern` (regex) |
+| `onValueChange` | `InputOTP` | Use `onChange` |
+| `description`, `errorMessage` | - | Handle with Description / FieldError |
+| `variant` | `InputOTP` | Simplified to `primary` \| `secondary` only |
+| `color`, `size`, `radius` | - | Removed (use Tailwind CSS) |
+| `classNames` | - | Use `className` on parts |
+| - | `textAlign` | New prop: text alignment within slots (`'left'` \| `'center'` \| `'right'`) |
+| - | `inputMode` | New prop: virtual keyboard type on mobile (default `'numeric'`) |
+| - | `placeholder` | New prop: placeholder text for empty slots |
+| - | `pasteTransformer` | New prop: transform pasted text (e.g., remove hyphens) |
+
+## Migration Examples
+
+### Controlled InputOTP
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <InputOtp length={4} value={value} onValueChange={setValue} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <InputOTP maxLength={4} value={value} onChange={setValue}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+### With Allowed Keys / Pattern
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <InputOtp allowedKeys="^[a-z]*$" length={4} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { REGEXP_ONLY_CHARS } from "@heroui/react";
+
+    <InputOTP maxLength={4} pattern={REGEXP_ONLY_CHARS}>
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+        <InputOTP.Slot index={3} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <InputOtp description="Enter the code sent to your email" length={4} />
+    
+    {/* With error message */}
+    <InputOtp errorMessage="Invalid code" isInvalid length={4} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError } from "@heroui/react";
+
+    {/* With description */}
+    <div className="flex flex-col gap-2">
+      <InputOTP maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>Enter the code sent to your email</Description>
+    </div>
+    
+    {/* With error message */}
+    <div className="flex flex-col gap-2">
+      <InputOTP isInvalid maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+      <FieldError>Invalid code</FieldError>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### With onComplete Callback
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <InputOtp
+      length={6}
+      onComplete={(value) => console.log("Complete:", value)}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <InputOTP
+      maxLength={6}
+      onComplete={(value) => console.log("Complete:", value)}
+    >
+      <InputOTP.Group>
+        <InputOTP.Slot index={0} />
+        <InputOTP.Slot index={1} />
+        <InputOTP.Slot index={2} />
+      </InputOTP.Group>
+      <InputOTP.Separator />
+      <InputOTP.Group>
+        <InputOTP.Slot index={3} />
+        <InputOTP.Slot index={4} />
+        <InputOTP.Slot index={5} />
+      </InputOTP.Group>
+    </InputOTP>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 InputOTP follows this structure:
+
+```
+InputOTP (Root)
+  ├── InputOTP.Group
+  │   ├── InputOTP.Slot (index={0})
+  │   ├── InputOTP.Slot (index={1})
+  │   └── ...
+  ├── InputOTP.Separator (optional)
+  └── InputOTP.Group (optional, for grouping)
+      └── InputOTP.Slot (index={...})
+```
+
+## New Props in v3
+
+v3 introduces several new props not available in v2:
+
+- **`textAlign`**: Controls text alignment within slots (`'left'` | `'center'` | `'right'`, default `'left'`)
+- **`inputMode`**: Sets the virtual keyboard type on mobile devices (`'numeric'` | `'text'` | `'decimal'` | `'tel'` | `'search'` | `'email'` | `'url'`, default `'numeric'`)
+- **`placeholder`**: Sets placeholder text for empty slots
+- **`pasteTransformer`**: A function `(text: string) => string` to transform pasted text (e.g., removing hyphens from a pasted code)
+
+```tsx
+<InputOTP
+  maxLength={6}
+  inputMode="numeric"
+  textAlign="center"
+  placeholder="-"
+  pasteTransformer={(text) => text.replace(/-/g, "")}
+>
+  <InputOTP.Group>
+    <InputOTP.Slot index={0} />
+    <InputOTP.Slot index={1} />
+    <InputOTP.Slot index={2} />
+  </InputOTP.Group>
+  <InputOTP.Separator />
+  <InputOTP.Group>
+    <InputOTP.Slot index={3} />
+    <InputOTP.Slot index={4} />
+    <InputOTP.Slot index={5} />
+  </InputOTP.Group>
+</InputOTP>
+```
+
+## Exported Regex Patterns
+
+HeroUI re-exports common regex patterns from the input-otp library for convenience:
+
+```tsx
+import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from "@heroui/react";
+
+// Use with the pattern prop
+<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>
+  {/* ... */}
+</InputOTP>
+```
+
+- **`REGEXP_ONLY_DIGITS`** - Only numeric characters (0-9)
+- **`REGEXP_ONLY_CHARS`** - Only alphabetic characters (a-z, A-Z)
+- **`REGEXP_ONLY_DIGITS_AND_CHARS`** - Alphanumeric characters (0-9, a-z, A-Z)
+
+## Summary
+
+1. **Component Structure**: Must manually define slots using `InputOTP.Group` and `InputOTP.Slot`
+2. **length → maxLength**: Prop renamed
+3. **allowedKeys → pattern**: Prop renamed, uses regex pattern
+4. **onValueChange → onChange**: Event handler renamed
+5. **Description Removed**: Handle separately with `Description` component
+6. **Error Message Removed**: Handle separately with error display
+7. **Variant Simplified**: v3 supports only `variant="primary"` and `variant="secondary"`
+8. **Colors Removed**: Use Tailwind CSS classes for styling
+9. **Sizes Removed**: Use Tailwind CSS classes for styling
+10. **Radius Removed**: Use Tailwind CSS classes for styling
+11. **ClassNames Removed**: Use `className` props on individual components
+12. **New Props**: v3 adds `textAlign`, `inputMode`, `placeholder`, and `pasteTransformer` props
+13. **Exported Patterns**: Use `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_CHARS`, and `REGEXP_ONLY_DIGITS_AND_CHARS` for the `pattern` prop
diff --git a/apps/docs/content/docs/en/react/migration/(components)/input.mdx b/apps/docs/content/docs/en/react/migration/(components)/input.mdx
new file mode 100644
index 0000000..a4c55f3
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/input.mdx
@@ -0,0 +1,281 @@
+---
+title: Input
+description: Migration guide for Input from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Input documentation](/docs/react/components/input) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Key Change: Input → TextField
+
+**v2:** `Input` was a full-featured component with built-in label, description, error messages, validation, variants, colors, sizes, etc.
+
+**v3:** `Input` is now a primitive component (just the input element). For form fields, use `TextField` which wraps `Input` with `Label`, `Description`, and `FieldError` components. In v2 there was no separate TextField or InputGroup; the single Input component handled labels, descriptions, start/end content, and validation.
+
+## When to Use Input vs TextField
+
+### Use TextField (Most Cases)
+
+Use `TextField` when you need:
+- Labels
+- Descriptions
+- Error messages
+- Validation
+- Form integration
+
+### Use Input (Primitive Only)
+
+Use `Input` when you need:
+- Just a basic input element
+- Custom label/error handling
+- Integration with custom form components
+
+## Structure Changes
+
+In v2, `Input` was a full-featured component that accepted props for label, description, placeholder, and other elements:
+
+```tsx
+import { Input } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Input
+      label="Email"
+      placeholder="Enter your email"
+      type="email"
+    />
+  );
+}
+```
+
+In v3, `Input` is a primitive component. For form fields with labels and validation, use `TextField` which wraps `Input` with `Label`, `Description`, and `FieldError`:
+
+```tsx
+import { TextField, Label, Input, FieldError } from "@heroui/react";
+
+export default function App() {
+  return (
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input placeholder="Enter your email" />
+      <FieldError />
+    </TextField>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Split
+
+**v2:** Single `Input` component with all features  
+**v3:** Split into `Input` (primitive) and `TextField` (compound component)
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `label` | `Label` | Use `Label` component inside `TextField` |
+| `description` | `Description` | Use `Description` component inside `TextField` |
+| `errorMessage` | `FieldError` | Use `FieldError` component inside `TextField` |
+| `variant` | `Input` | Changed from multiple variants (flat, bordered, underlined, faded) to `"primary"` (default, with shadow) and `"secondary"` (lower emphasis, no shadow, for surfaces) |
+| `color`, `size`, `radius` | - | Removed (use Tailwind CSS) |
+| `fullWidth` | `Input` or `TextField` | Still supported on both `Input` and `TextField` (`fullWidth` boolean prop) |
+| `labelPlacement` | - | Use layout with `Label` |
+| `startContent` | `InputGroup.Prefix` | Use `InputGroup` with `InputGroup.Prefix` inside `TextField` |
+| `endContent` | `InputGroup.Suffix` | Use `InputGroup` with `InputGroup.Suffix` inside `TextField` |
+| `isClearable` | - | Implement manually with button |
+| `isRequired`, `isInvalid` | `TextField` | Use on `TextField` |
+| `validate` | `TextField` | Use `validate` on `TextField` |
+| `classNames` | - | Use `className` on individual components |
+| `onValueChange` | `Input` | Use `onChange` event handler |
+
+## Migration Examples
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <Input
+      description="We'll never share your email"
+      label="Email"
+      type="email"
+    />
+    
+    {/* With error message */}
+    <Input
+      errorMessage="Please enter a valid email"
+      isInvalid
+      label="Email"
+      type="email"
+    />
+    
+    {/* Required */}
+    <Input isRequired label="Email" type="email" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description } from "@heroui/react";
+
+    {/* With description */}
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input />
+      <Description>We'll never share your email</Description>
+      <FieldError />
+    </TextField>
+    
+    {/* With error message */}
+    <TextField
+      isInvalid
+      name="email"
+      type="email"
+      validate={(value) => {
+        if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+          return "Please enter a valid email";
+        }
+        return null;
+      }}
+    >
+      <Label>Email</Label>
+      <Input />
+      <FieldError />
+    </TextField>
+    
+    {/* Required */}
+    <TextField isRequired name="email" type="email">
+      <Label>Email</Label>
+      <Input />
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+### Input with Start/End Content
+
+For inputs with prefix or suffix content, use the **InputGroup** compound component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Input
+      label="Price"
+      startContent={<span>$</span>}
+      type="number"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { InputGroup } from "@heroui/react";
+
+    <TextField name="price" type="number">
+      <Label>Price</Label>
+      <InputGroup>
+        <InputGroup.Prefix>$</InputGroup.Prefix>
+        <InputGroup.Input />
+      </InputGroup>
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+**InputGroup** provides proper styling and layout for prefix/suffix content. Use:
+- `InputGroup.Prefix` for content before the input (replaces `startContent`)
+- `InputGroup.Suffix` for content after the input (replaces `endContent`)
+- `InputGroup.Input` for the input element itself
+
+### Input with Clear Button
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Input
+      isClearable
+      label="Email"
+      onClear={() => console.log("cleared")}
+      type="email"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { CloseButton } from "@heroui/react";
+
+    const [value, setValue] = useState("");
+
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <div className="flex items-center">
+        <Input value={value} onChange={(e) => setValue(e.target.value)} />
+        {value && (
+          <CloseButton
+            aria-label="Clear"
+            onPress={() => setValue("")}
+          />
+        )}
+      </div>
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled Input
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <Input
+      label="Email"
+      onValueChange={setValue}
+      type="email"
+      value={value}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState("");
+
+    <TextField name="email" type="email">
+      <Label>Email</Label>
+      <Input
+        onChange={(e) => setValue(e.target.value)}
+        value={value}
+      />
+      <FieldError />
+    </TextField>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+1. **Component Split**: `Input` → `TextField` for form fields, `Input` for primitive input
+2. **Label Required**: Must use `Label` component instead of `label` prop
+3. **Error Display**: Must use `FieldError` component instead of `errorMessage` prop
+4. **Description**: Must use `Description` component instead of `description` prop
+5. **Validation**: Move `validate` function from `Input` to `TextField`
+6. **Start/End Content**: Use `InputGroup` with `InputGroup.Prefix`/`InputGroup.Suffix` inside `TextField`
+7. **Clear Button**: Implement manually with `CloseButton`
+8. **Variants Simplified**: v2 had multiple variants (flat, bordered, underlined, faded); v3 has `"primary"` (default) and `"secondary"` (for surfaces)
+9. **Full Width**: `fullWidth` prop is still available on both `Input` and `TextField`
+10. **Colors Removed**: Use Tailwind CSS classes
+11. **Sizes Removed**: Use Tailwind CSS classes
+12. **Radius Removed**: Use Tailwind CSS classes
+12. **onValueChange Removed**: Use `onChange` event handler
+13. **ClassNames Removed**: Use `className` props on individual components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/kbd.mdx b/apps/docs/content/docs/en/react/migration/(components)/kbd.mdx
new file mode 100644
index 0000000..e124e43
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/kbd.mdx
@@ -0,0 +1,134 @@
+---
+title: Kbd
+description: Migration guide for Kbd from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Kbd documentation](/docs/react/components/kbd) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Kbd used a `keys` prop to automatically render keyboard keys:
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default function App() {
+  return <Kbd keys={["command"]}>K</Kbd>;
+}
+```
+
+In v3, Kbd requires manual definition of keys using compound components:
+
+```tsx
+import { Kbd } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Kbd>
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single component with `keys` prop
+**v3:** Compound components: `Kbd.Abbr`, `Kbd.Key`, `Kbd.Content`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `keys` | - | Removed (use `Kbd.Abbr` with `keyValue`) |
+| `classNames` | - | Use `className` |
+| - | `Kbd` | New `variant` prop (`default` \| `light`) |
+| - | `Kbd.Key` | New subcomponent for key text (alternative to `Kbd.Content`) |
+
+## Migration Examples
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Kbd keys={["command"]}>K</Kbd>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Kbd variant="default">
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+    <Kbd variant="light">
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+    ```
+  </Tab>
+</Tabs>
+
+## Kbd.Key vs Kbd.Content
+
+v3 provides two subcomponents for key text content:
+
+- **`Kbd.Key`**: Used for the text content of the key (e.g., a letter or number). Accepts `children` and `className` props.
+- **`Kbd.Content`**: An alias/alternative for wrapping content text. Accepts `children` and `className` props.
+
+Both can be used interchangeably for wrapping the non-modifier key text:
+
+```tsx
+{/* Using Kbd.Key */}
+<Kbd>
+  <Kbd.Abbr keyValue="command" />
+  <Kbd.Key>K</Kbd.Key>
+</Kbd>
+
+{/* Using Kbd.Content */}
+<Kbd>
+  <Kbd.Abbr keyValue="command" />
+  <Kbd.Content>K</Kbd.Content>
+</Kbd>
+```
+
+## Component Anatomy
+
+The v3 Kbd follows this structure:
+
+```
+Kbd (Root)
+  ├── Kbd.Abbr (keyValue="command")
+  ├── Kbd.Abbr (keyValue="shift") [optional, multiple]
+  └── Kbd.Key or Kbd.Content [optional, for text content]
+```
+
+## Available Key Values
+
+The `keyValue` prop accepts the same keyboard key types as v2:
+
+**Modifier Keys:**
+- `command`, `shift`, `ctrl`, `option`, `alt`, `win`
+
+**Special Keys:**
+- `enter`, `delete`, `escape`, `tab`, `space`, `capslock`, `help`
+
+**Navigation Keys:**
+- `up`, `down`, `left`, `right`, `pageup`, `pagedown`, `home`, `end`
+
+**Function Keys:**
+- `fn`
+
+## Summary
+
+1. **Component Structure**: Must manually define keys using `Kbd.Abbr` components
+2. **keys Prop Removed**: Use `Kbd.Abbr` with `keyValue` prop instead
+3. **Children Wrapping**: Wrap text content in `Kbd.Content` component
+4. **ClassNames Removed**: Use `className` props on individual components
+5. **New Variant Prop**: Added `variant` prop for styling (`default` \| `light`)
+6. **Kbd.Key Subcomponent**: New `Kbd.Key` subcomponent available as an alternative to `Kbd.Content` for key text
diff --git a/apps/docs/content/docs/en/react/migration/(components)/link.mdx b/apps/docs/content/docs/en/react/migration/(components)/link.mdx
new file mode 100644
index 0000000..d04febd
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/link.mdx
@@ -0,0 +1,186 @@
+---
+title: Link
+description: Migration guide for Link from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Link documentation](/docs/react/components/link) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single component with icon props  
+**v3:** Compound component: `Link.Icon` for icons
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `showAnchorIcon`, `anchorIcon` | - | Use `Link.Icon` component with children |
+| `isExternal` | - | Use `target="_blank"` and `rel="noopener noreferrer"` |
+| `size`, `color`, `isBlock` | - | Removed (use Tailwind CSS) |
+| `disableAnimation` | - | Removed |
+| `underline` | - | Removed (use Tailwind `underline`, etc.) |
+
+### 3. New Props
+
+- `onPress` - Event handler fired when the link is activated (via click or keyboard). Accepts a `(e: PressEvent) => void` callback.
+
+## Structure Changes
+
+In v2, Link component usage:
+
+```tsx
+import { Link } from "@heroui/react";
+
+export default function App() {
+  return <Link href="#">Default Link</Link>;
+}
+```
+
+In v3, Link component usage remains the same for basic cases:
+
+```tsx
+import { Link } from "@heroui/react";
+
+export default function App() {
+  return <Link href="#">Default Link</Link>;
+}
+```
+
+## Migration Examples
+
+### With Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Default icon */}
+    <Link showAnchorIcon href="#">
+      External Link
+    </Link>
+    
+    {/* Custom icon */}
+    <Link
+      showAnchorIcon
+      anchorIcon={<CustomIcon />}
+      href="#"
+    >
+      Custom Icon
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Default icon */}
+    <Link href="#">
+      External Link
+      <Link.Icon />
+    </Link>
+    
+    {/* Custom icon */}
+    <Link href="#">
+      Custom Icon
+      <Link.Icon>
+        <CustomIcon />
+      </Link.Icon>
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### External Link
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Link isExternal href="https://example.com">
+      External Link
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Link
+      href="https://example.com"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      External Link
+      <Link.Icon />
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### Underline and offset (v3: use Tailwind)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Link href="#" underline="hover">
+      Hover to underline
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Link href="#">
+      Hover to underline
+    </Link>
+    <Link href="#" className="underline underline-offset-2">
+      Underline with offset
+    </Link>
+    ```
+  </Tab>
+</Tabs>
+
+### With routing libraries
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import NextLink from "next/link";
+    import { Link } from "@heroui/react";
+
+    <Link as={NextLink} href="/about">
+      About
+    </Link>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import NextLink from "next/link";
+    import { Link } from "@heroui/react";
+
+    {/* Style your router link with the same classes as Link; add an icon if needed */}
+    <NextLink href="/about" className="link">
+      About
+    </NextLink>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Link follows this structure:
+
+```
+Link (Root)
+  ├── Link content (text)
+  └── Link.Icon (optional)
+```
+
+## Summary
+
+1. **Icon Handling**: `showAnchorIcon` and `anchorIcon` props replaced with `Link.Icon` component
+2. **External Links**: `isExternal` prop removed - handle manually with `target` and `rel`
+3. **Size Prop Removed**: Use Tailwind CSS classes (`text-sm`, `text-base`, `text-lg`)
+4. **Color Prop Removed**: Use Tailwind CSS classes (`text-primary`, `text-danger`, etc.)
+5. **Block Prop Removed**: Use Tailwind CSS classes (`block`, `hover:bg-surface`)
+6. **Underline**: No longer a prop; Link underlines on hover by default. Use Tailwind (`underline`, `no-underline`, `underline-offset-1`, etc.) to customize it.
+7. **Routing**: v3 Link does not support `as` or `asChild`; use your router's Link with Tailwind classes (e.g. `link`, `link__icon`) for consistent styling
+8. **Animation Removed**: `disableAnimation` prop removed
+9. **`onPress` Handler**: New `onPress` prop available for handling link activation events (click or keyboard)
diff --git a/apps/docs/content/docs/en/react/migration/(components)/listbox.mdx b/apps/docs/content/docs/en/react/migration/(components)/listbox.mdx
new file mode 100644
index 0000000..a9cdadb
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/listbox.mdx
@@ -0,0 +1,392 @@
+---
+title: Listbox
+description: Migration guide for Listbox (renamed to ListBox with a capital "B") from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 ListBox documentation](/docs/react/components/listbox) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+### v2: Separate Components
+
+In v2, Listbox used separate components:
+
+```tsx
+import { Listbox, ListboxItem, ListboxSection } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Listbox>
+      <ListboxItem key="1">Item 1</ListboxItem>
+    </Listbox>
+  );
+}
+```
+
+### v3: Compound Components
+
+In v3, ListBox uses compound components:
+
+```tsx
+import { ListBox, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ListBox>
+      <ListBox.Item id="1" textValue="Item 1">
+        <Label>Item 1</Label>
+      </ListBox.Item>
+    </ListBox>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Naming
+
+**v2:** `Listbox`, `ListboxItem`, `ListboxSection`  
+**v3:** `ListBox`, `ListBox.Item`, `ListBox.Section`
+
+### 2. Item Identification
+
+**v2:** React's `key` was used for both list reconciliation and item identity (selection, focus).  
+**v3:** Use `id` for state/focus and `textValue` for accessibility (when content isn't plain text); keep React's `key` on items in lists.
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `key` (for state) | `ListBox.Item` | Use `id` for item identity (state) |
+| - | `textValue` (on ListBox.Item) | For accessibility (type-ahead) |
+| `variant`, `color` | `variant` on `ListBox` or `ListBox.Item` | Simplified to `"default"` \| `"danger"` (no `color` prop) |
+| `onAction` | `ListBox` | Callback fired when an item is pressed (`(key: Key) => void`) |
+| `disabledKeys` | `ListBox` | Same — set of keys for items that should be non-interactive |
+| `startContent`, `endContent` | - | Place icons manually in item content |
+| `description` | `Description` | Use `Description` component |
+| `title` (on Section) | `Header` | Use `Header` component |
+| `topContent`, `bottomContent` | - | Removed (handle separately) |
+| `itemClasses`, `classNames` | - | Use `className` on parts |
+| `hideSelectedIcon` | - | Omit `ListBox.ItemIndicator` |
+| `disableAnimation` | - | Removed |
+| `isVirtualized`, `virtualization` | React Aria `Virtualizer` | Use React Aria's `<Virtualizer>` wrapper (see example below) |
+| `selectedKeys` | `ListBox` | Same (uses `Selection` type Set) |
+
+## Migration Examples
+
+### Selection
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState(new Set(["text"]));
+
+    <Listbox
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <ListboxItem key="text">Text</ListboxItem>
+      <ListboxItem key="number">Number</ListboxItem>
+    </Listbox>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState(new Set(["text"]));
+
+    <Listbox
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <ListboxItem key="text">Text</ListboxItem>
+      <ListboxItem key="number">Number</ListboxItem>
+    </Listbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Selection } from "@heroui/react";
+
+    {/* Single selection */}
+    const [singleSelected, setSingleSelected] = useState<Selection>(new Set(["text"]));
+
+    <ListBox
+      selectedKeys={singleSelected}
+      selectionMode="single"
+      onSelectionChange={setSingleSelected}
+    >
+      <ListBox.Item id="text" textValue="Text">
+        <Label>Text</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="number" textValue="Number">
+        <Label>Number</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+    
+    {/* Multiple selection */}
+    const [multiSelected, setMultiSelected] = useState<Selection>(new Set(["text"]));
+
+    <ListBox
+      selectedKeys={multiSelected}
+      selectionMode="multiple"
+      onSelectionChange={setMultiSelected}
+    >
+      <ListBox.Item id="text" textValue="Text">
+        <Label>Text</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="number" textValue="Number">
+        <Label>Number</Label>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+    ```
+  </Tab>
+</Tabs>
+
+### With Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="new"
+      description="Create a new file"
+    >
+      New file
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, Label } from "@heroui/react";
+
+    <ListBox.Item id="new" textValue="New file">
+      <Label>New file</Label>
+      <Description>Create a new file</Description>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="new"
+      startContent={<AddIcon />}
+    >
+      New file
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ListBox.Item id="new" textValue="New file">
+      <AddIcon />
+      <Label>New file</Label>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### With Sections
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Listbox>
+      <ListboxSection title="Actions">
+        <ListboxItem key="new">New file</ListboxItem>
+        <ListboxItem key="edit">Edit file</ListboxItem>
+      </ListboxSection>
+      <ListboxSection title="Danger zone">
+        <ListboxItem key="delete">Delete</ListboxItem>
+      </ListboxSection>
+    </Listbox>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Header, Label, Separator } from "@heroui/react";
+
+    <ListBox>
+      <ListBox.Section>
+        <Header>Actions</Header>
+        <ListBox.Item id="new" textValue="New file">
+          <Label>New file</Label>
+        </ListBox.Item>
+        <ListBox.Item id="edit" textValue="Edit file">
+          <Label>Edit file</Label>
+        </ListBox.Item>
+      </ListBox.Section>
+      <Separator />
+      <ListBox.Section>
+        <Header>Danger zone</Header>
+        <ListBox.Item id="delete" textValue="Delete" variant="danger">
+          <Label>Delete</Label>
+        </ListBox.Item>
+      </ListBox.Section>
+    </ListBox>
+    ```
+  </Tab>
+</Tabs>
+
+### With Custom Indicator
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ListboxItem
+      key="1"
+      selectedIcon={<CustomCheckIcon />}
+    >
+      Item 1
+    </ListboxItem>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ListBox.Item id="1" textValue="Item 1">
+      <Label>Item 1</Label>
+      <ListBox.ItemIndicator>
+        {({isSelected}) =>
+          isSelected ? <CustomCheckIcon /> : null
+        }
+      </ListBox.ItemIndicator>
+    </ListBox.Item>
+    ```
+  </Tab>
+</Tabs>
+
+### Variant Prop
+
+In v3, both `ListBox` and `ListBox.Item` accept a `variant` prop with values `"default"` (default) or `"danger"`. Setting `variant` on the root `ListBox` applies to all items; setting it on an individual `ListBox.Item` overrides the root value for that item.
+
+```tsx
+{/* Root-level variant — all items inherit "danger" styling */}
+<ListBox variant="danger">
+  <ListBox.Item id="delete" textValue="Delete">
+    <Label>Delete</Label>
+  </ListBox.Item>
+</ListBox>
+
+{/* Per-item variant */}
+<ListBox>
+  <ListBox.Item id="edit" textValue="Edit">
+    <Label>Edit</Label>
+  </ListBox.Item>
+  <ListBox.Item id="delete" textValue="Delete" variant="danger">
+    <Label>Delete</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### onAction Handler
+
+The `onAction` callback is fired when an item is pressed (click or Enter). It receives the item's `id` as a `Key`.
+
+```tsx
+<ListBox onAction={(key) => alert(`Action on ${key}`)}>
+  <ListBox.Item id="copy" textValue="Copy">
+    <Label>Copy</Label>
+  </ListBox.Item>
+  <ListBox.Item id="paste" textValue="Paste">
+    <Label>Paste</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### Disabled Keys
+
+Use `disabledKeys` to make specific items non-interactive:
+
+```tsx
+<ListBox disabledKeys={new Set(["paste"])}>
+  <ListBox.Item id="copy" textValue="Copy">
+    <Label>Copy</Label>
+  </ListBox.Item>
+  <ListBox.Item id="paste" textValue="Paste">
+    <Label>Paste</Label>
+  </ListBox.Item>
+</ListBox>
+```
+
+### Render Props on ListBox.Item
+
+`ListBox.Item` supports render props, giving you access to the current interaction state. The available render prop values are `isSelected`, `isFocused`, `isDisabled`, and `isPressed`:
+
+```tsx
+<ListBox selectionMode="single">
+  <ListBox.Item id="item1" textValue="Item 1">
+    {({isSelected, isFocused, isDisabled, isPressed}) => (
+      <>
+        <Label className={isSelected ? "font-bold" : ""}>Item 1</Label>
+        {isSelected && <ListBox.ItemIndicator />}
+      </>
+    )}
+  </ListBox.Item>
+</ListBox>
+```
+
+### Virtualization
+
+Virtualization is **still supported** in v3 via React Aria's `<Virtualizer>` component. Wrap your `ListBox` items with `Virtualizer` for efficient rendering of large lists:
+
+```tsx
+import {Virtualizer} from "react-aria-components";
+
+<ListBox
+  aria-label="Large list"
+  items={items}
+  selectionMode="multiple"
+>
+  <Virtualizer>
+    {(item) => (
+      <ListBox.Item id={item.id} textValue={item.name}>
+        <Label>{item.name}</Label>
+      </ListBox.Item>
+    )}
+  </Virtualizer>
+</ListBox>
+```
+
+## Component Anatomy
+
+The v3 ListBox follows this structure:
+
+```
+ListBox (Root)
+  ├── ListBox.Item
+  │   ├── Icon (optional, manual placement)
+  │   ├── Label (required)
+  │   ├── Description (optional)
+  │   └── ListBox.ItemIndicator (optional)
+  └── ListBox.Section (optional)
+      ├── Header (optional)
+      └── ListBox.Item
+```
+
+## Summary
+
+1. **Component Naming**: `Listbox` → `ListBox`, `ListboxItem` → `ListBox.Item`, `ListboxSection` → `ListBox.Section`
+2. **Item Structure**: Must use `Label`, `Description`, `ListBox.ItemIndicator` components
+3. **Icons**: Manual placement instead of `startContent`/`endContent` props
+4. **Sections**: Use `Header` component instead of `title` prop
+5. **Variant Prop**: `variant` and `color` replaced by a single `variant` prop (`"default"` | `"danger"`) on both `ListBox` and `ListBox.Item`
+6. **onAction**: New `onAction` callback on `ListBox` for item press handling
+7. **disabledKeys**: Supported on `ListBox` to disable specific items
+8. **Render Props**: `ListBox.Item` provides `isSelected`, `isFocused`, `isDisabled`, `isPressed` via render props
+9. **Content Props Removed**: `topContent`, `bottomContent` - handle separately
+10. **Virtualization**: Still supported via React Aria's `<Virtualizer>` component (replaces `isVirtualized` prop)
+11. **Selection Type**: Uses `Selection` type (Set) instead of arrays
diff --git a/apps/docs/content/docs/en/react/migration/(components)/modal.mdx b/apps/docs/content/docs/en/react/migration/(components)/modal.mdx
new file mode 100644
index 0000000..bde45c0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/modal.mdx
@@ -0,0 +1,492 @@
+---
+title: Modal
+description: Migration guide for Modal from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Modal documentation](/docs/react/components/modal) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Modal used separate components:
+
+```tsx
+import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Modal</Button>
+      <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+        <ModalContent>
+          <ModalHeader>Title</ModalHeader>
+          <ModalBody>Content</ModalBody>
+          <ModalFooter>Footer</ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+In v3, Modal uses compound components:
+
+```tsx
+import { Modal, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Title</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>Content</Modal.Body>
+            <Modal.Footer>Footer</Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Separate components (`Modal`, `ModalContent`, `ModalHeader`, `ModalBody`, `ModalFooter`)  
+**v3:** Compound components (`Modal.Backdrop`, `Modal.Container`, `Modal.Dialog`, `Modal.Header`, `Modal.Body`, `Modal.Footer`)
+
+### 2. Built-in Trigger with `Modal.Trigger`
+
+**v2:** Required `useDisclosure` hook and manual `onPress` wiring to open the modal
+**v3:** Provides `Modal.Trigger` as a built-in trigger component that automatically opens the modal when pressed — no state management needed
+
+<Tabs items={["v2", "v3 (Button trigger)", "v3 (Modal.Trigger)"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Modal, ModalContent, Button, useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    <Button onPress={onOpen}>Open Modal</Button>
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (Button trigger)">
+    ```tsx
+    import { Modal, Button } from "@heroui/react";
+
+    {/* A Button placed as a direct child of Modal automatically becomes the trigger */}
+    <Modal>
+      <Button>Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>{/* content */}</Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (Modal.Trigger)">
+    ```tsx
+    import { Modal } from "@heroui/react";
+
+    {/* Use Modal.Trigger for custom trigger elements (cards, links, etc.) */}
+    <Modal>
+      <Modal.Trigger className="flex items-center gap-3 rounded-2xl bg-surface p-4">
+        <p className="font-semibold">Settings</p>
+        <p className="text-xs text-muted">Manage your preferences</p>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>{/* content */}</Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+`Modal.Trigger` wraps any content in a pressable element that opens the modal. Use it when you need a custom trigger beyond a standard `Button`.
+
+### 3. State Management
+
+**v2:** Uses `useDisclosure` hook
+**v3:** Built-in trigger (no state needed), controlled with `isOpen`/`onOpenChange` on `Modal.Backdrop`, or use `useOverlayState` and pass `state` to the root
+
+#### `useOverlayState` replaces `useDisclosure`
+
+The `useOverlayState` hook is a direct replacement for v2's `useDisclosure`. It supports both controlled and uncontrolled modes:
+
+```tsx
+import { useOverlayState } from "@heroui/react";
+
+// Uncontrolled (manages its own state)
+const state = useOverlayState();
+
+// Uncontrolled with default open
+const state = useOverlayState({ defaultOpen: true });
+
+// With callback
+const state = useOverlayState({
+  onOpenChange: (isOpen) => console.log("Modal is now:", isOpen),
+});
+
+// Controlled (you manage the state)
+const [isOpen, setIsOpen] = useState(false);
+const state = useOverlayState({ isOpen, onOpenChange: setIsOpen });
+```
+
+**Hook API:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state.isOpen` | `boolean` | Whether the overlay is currently open |
+| `state.open()` | `() => void` | Opens the overlay |
+| `state.close()` | `() => void` | Closes the overlay |
+| `state.toggle()` | `() => void` | Toggles the overlay open/closed |
+| `state.setOpen(isOpen)` | `(isOpen: boolean) => void` | Sets the open state directly |
+
+Pass `state` to the `Modal` root to connect it:
+
+```tsx
+const state = useOverlayState();
+
+<Modal state={state}>
+  <Button onPress={state.open}>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>{/* content */}</Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+<Callout type="info">
+  For detailed migration from `useDisclosure` to `useOverlayState`, see the [Hooks Migration Guide](/docs/react/migration/hooks).
+</Callout>
+
+### 4. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `size` | `size` (on Container) | Simplified (xs, sm, md, lg, cover, full) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `shadow` | — | Removed (use Tailwind CSS) |
+| `backdrop` | `variant` (on **Backdrop**) | Renamed; values unchanged (`opaque`, `blur`, `transparent`) |
+| `scrollBehavior` | `scroll` (on Container) | Renamed (`normal` → `inside`) |
+| `placement` | `placement` (on Container) | Moved to Container |
+| `isDismissable` | `isDismissable` (on **Backdrop**) | Moved to `Modal.Backdrop` |
+| `isKeyboardDismissDisabled` | `isKeyboardDismissDisabled` (on **Backdrop**) | Moved to `Modal.Backdrop` |
+| `isOpen` | `isOpen` (on **Backdrop**) | Controlled state on `Modal.Backdrop` |
+| `onOpenChange` | `onOpenChange` (on **Backdrop**) | Same as above |
+| `onClose` | — | Use `close` from render prop |
+| `hideCloseButton` | — | Omit `Modal.CloseTrigger` instead |
+| `closeButton` | — | Use `Modal.CloseTrigger` with custom content |
+| `motionProps` | — | Removed (animations handled differently) |
+| `classNames` | — | Use `className` props on individual components |
+| `shouldBlockScroll` | — | Removed (handled automatically) |
+| `portalContainer` | — | Removed |
+
+## Migration Examples
+
+### Controlled Modal
+
+<Tabs items={["v2", "v3 (useState)", "v3 (useOverlayState)", "v3 (state prop)"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>
+        {(onClose) => (
+          <>
+            <ModalHeader>Title</ModalHeader>
+            <ModalBody>Content</ModalBody>
+          </>
+        )}
+      </ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (useState)">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Modal>
+      <Button onPress={() => setIsOpen(true)}>Open</Button>
+      <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (useOverlayState)">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    const state = useOverlayState();
+
+    <Modal>
+      <Button onPress={state.open}>Open</Button>
+      <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3 (state prop)">
+    ```tsx
+    import { useOverlayState } from "@heroui/react";
+
+    // Pass state directly to Modal root — no need to wire isOpen/onOpenChange manually
+    const state = useOverlayState();
+
+    <Modal state={state}>
+      <Button onPress={state.open}>Open</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            {({close}) => (
+              <>
+                <Modal.Header>
+                  <Modal.Heading>Title</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>Content</Modal.Body>
+              </>
+            )}
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  For detailed `useDisclosure` → `useOverlayState` migration guide, see the [Hooks Migration Guide](/docs/react/migration/hooks).
+</Callout>
+
+### Backdrop and Container Props
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Backdrop */}
+    <Modal backdrop="blur">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Placement */}
+    <Modal placement="top">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Scroll behavior */}
+    <Modal scrollBehavior="outside">
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Backdrop - use Modal.Backdrop with variant */}
+    <Modal.Backdrop variant="blur">
+      <Modal.Container>
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    
+    {/* Placement - on Container */}
+    <Modal.Backdrop>
+      <Modal.Container placement="top">
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    
+    {/* Scroll - on Container */}
+    <Modal.Backdrop>
+      <Modal.Container scroll="outside">
+        <Modal.Dialog>{/* content */}</Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+    ```
+  </Tab>
+</Tabs>
+
+### Close Button
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Without close button */}
+    <Modal hideCloseButton>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    
+    {/* Custom close button */}
+    <Modal closeButton={<CustomCloseIcon />}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Without close button - omit Modal.CloseTrigger */}
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.Header>
+          <Modal.Heading>Title</Modal.Heading>
+        </Modal.Header>
+      </Modal.Dialog>
+    </Modal.Container>
+    
+    {/* Custom close button */}
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.CloseTrigger>
+          <CustomCloseIcon />
+        </Modal.CloseTrigger>
+        {/* content */}
+      </Modal.Dialog>
+    </Modal.Container>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Trigger
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Modal, ModalContent, useDisclosure } from "@heroui/react";
+
+    const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+    {/* Any element needed manual onPress + useDisclosure */}
+    <div onClick={onOpen} className="cursor-pointer rounded-xl bg-surface p-4">
+      <p className="font-semibold">Settings</p>
+      <p className="text-xs text-muted">Manage your preferences</p>
+    </div>
+    <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+      <ModalContent>{/* content */}</ModalContent>
+    </Modal>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Modal } from "@heroui/react";
+
+    {/* Modal.Trigger handles press events and accessibility automatically */}
+    <Modal>
+      <Modal.Trigger className="rounded-xl bg-surface p-4">
+        <p className="font-semibold">Settings</p>
+        <p className="text-xs text-muted">Manage your preferences</p>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog>
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Heading>Settings</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>{/* content */}</Modal.Body>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icon and Heading
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ModalHeader className="flex flex-col gap-1">
+      <Icon />
+      Modal Title
+    </ModalHeader>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Modal.Header>
+      <Modal.Icon>
+        <Icon />
+      </Modal.Icon>
+      <Modal.Heading>Modal Title</Modal.Heading>
+    </Modal.Header>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Modal follows this structure:
+
+```
+Modal (Root)
+  ├── Trigger (e.g. Button or Modal.Trigger)
+  └── Modal.Backdrop (variant, isDismissable, isKeyboardDismissDisabled)
+      └── Modal.Container (placement, scroll, size)
+          └── Modal.Dialog
+              ├── Modal.CloseTrigger (optional)
+              ├── Modal.Header
+              │   ├── Modal.Icon (optional)
+              │   └── Modal.Heading
+              ├── Modal.Body
+              └── Modal.Footer
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Modal.Container`, `Modal.Dialog`, etc.)
+2. **Built-in Trigger**: Use `Modal.Trigger` for custom trigger elements or place a `Button` as a direct child of `Modal` -- no manual state wiring needed
+3. **State Management**: `useDisclosure` replaced by `useOverlayState` hook; supports controlled/uncontrolled modes and a `state` prop on `Modal` root
+4. **Props Moved**: Many props moved from `Modal` to `Modal.Backdrop` and `Modal.Container`
+5. **Close Handler**: `onClose` callback replaced with `close` render prop on `Modal.Dialog`
+6. **Close Button**: `hideCloseButton`/`closeButton` replaced with `Modal.CloseTrigger`
+7. **Size**: Use `size` on `Modal.Container` (xs, sm, md, lg, cover, full); `radius` and `shadow` removed -- use Tailwind
+8. **Backdrop**: `backdrop` → `variant` on `Modal.Backdrop` (values: `opaque`, `blur`, `transparent`)
+9. **Scroll Renamed**: `scrollBehavior` → `scroll` (`normal` → `inside`)
+10. **Motion Removed**: `motionProps` removed, animations handled differently
+11. **New Components**: `Modal.Trigger`, `Modal.Icon`, `Modal.Heading`, `Modal.CloseTrigger`
diff --git a/apps/docs/content/docs/en/react/migration/(components)/navbar.mdx b/apps/docs/content/docs/en/react/migration/(components)/navbar.mdx
new file mode 100644
index 0000000..8f91449
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/navbar.mdx
@@ -0,0 +1,645 @@
+---
+title: Navbar
+description: Migration guide for Navbar from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The Navbar component has been **removed** in HeroUI v3. Build navigation bars manually using native HTML elements and Tailwind CSS classes. This guide focuses on common patterns and simplifies complex features.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<Navbar>` and subcomponents (`NavbarBrand`, `NavbarContent`, `NavbarItem`, `NavbarMenu`, `NavbarMenuItem`, `NavbarMenuToggle`)  
+**v3:** Manual composition using native HTML elements
+
+### 2. Subcomponents Mapping
+
+| v2 Component | v3 Equivalent | Notes |
+|-------------|---------------|-------|
+| `Navbar` | `<nav>` element | Main container |
+| `NavbarBrand` | `<div>` or `<a>` | Logo/brand area |
+| `NavbarContent` | `<ul>` element | Navigation list |
+| `NavbarItem` | `<li>` element | Navigation item |
+| `NavbarMenu` | Mobile menu overlay | Custom implementation |
+| `NavbarMenuItem` | `<li>` in mobile menu | Mobile menu item |
+| `NavbarMenuToggle` | `<button>` | Mobile menu toggle |
+
+### 3. Features Removed
+
+- `shouldHideOnScroll` - Requires custom scroll detection
+- `isBlurred` - Use Tailwind `backdrop-blur` utilities
+- `isBordered` - Use Tailwind border classes
+- `position` variants - Use Tailwind `sticky`, `fixed` classes
+- `maxWidth` variants - Use Tailwind `max-w-*` classes
+- Mobile menu animations - Requires custom implementation
+- Scroll blocking - Requires custom implementation (see "Scroll Blocking" below)
+
+## Migration Examples
+
+### Basic Navbar
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Navbar, NavbarBrand, NavbarContent, NavbarItem, Link, Button } from "@heroui/react";
+
+    {/* Basic */}
+    <Navbar>
+      <NavbarBrand>
+        <Logo />
+        <p className="font-bold">ACME</p>
+      </NavbarBrand>
+      <NavbarContent>
+        <NavbarItem><Link href="#">Features</Link></NavbarItem>
+        <NavbarItem><Link href="#">Pricing</Link></NavbarItem>
+      </NavbarContent>
+    </Navbar>
+    
+    {/* With right-aligned content */}
+    <Navbar>
+      <NavbarBrand>Logo</NavbarBrand>
+      <NavbarContent justify="end">
+        <NavbarItem><Button>Sign Up</Button></NavbarItem>
+      </NavbarContent>
+    </Navbar>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Link, Button } from "@heroui/react";
+
+    {/* Basic */}
+    <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+      <header className="flex h-16 items-center justify-between px-6">
+        <div className="flex items-center gap-3">
+          <Logo />
+          <p className="font-bold">ACME</p>
+        </div>
+        <ul className="flex items-center gap-4">
+          <li><Link href="#">Features</Link></li>
+          <li><Link href="#">Pricing</Link></li>
+        </ul>
+      </header>
+    </nav>
+    
+    {/* With right-aligned content */}
+    <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+      <header className="flex h-16 items-center justify-between px-6">
+        <div>Logo</div>
+        <ul className="flex items-center gap-4">
+          <li><Button>Sign Up</Button></li>
+        </ul>
+      </header>
+    </nav>
+    ```
+  </Tab>
+</Tabs>
+
+### With Mobile Menu (Simplified)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import {
+      Navbar,
+      NavbarBrand,
+      NavbarContent,
+      NavbarItem,
+      NavbarMenu,
+      NavbarMenuItem,
+      NavbarMenuToggle,
+    } from "@heroui/react";
+
+    function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <Navbar onMenuOpenChange={setIsMenuOpen}>
+          <NavbarContent>
+            <NavbarMenuToggle className="sm:hidden" />
+            <NavbarBrand>Logo</NavbarBrand>
+          </NavbarContent>
+          <NavbarContent className="hidden md:flex">
+            <NavbarItem>Features</NavbarItem>
+            <NavbarItem>Pricing</NavbarItem>
+          </NavbarContent>
+          <NavbarMenu>
+            <NavbarMenuItem>Features</NavbarMenuItem>
+            <NavbarMenuItem>Pricing</NavbarMenuItem>
+          </NavbarMenu>
+        </Navbar>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Link, Button } from "@heroui/react";
+
+    function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+          <header className="flex h-16 items-center justify-between px-6">
+            <div className="flex items-center gap-4">
+              <button
+                className="md:hidden"
+                onClick={() => setIsMenuOpen(!isMenuOpen)}
+                aria-label="Toggle menu"
+              >
+                <span className="sr-only">Menu</span>
+                <svg
+                  className="h-6 w-6"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  {isMenuOpen ? (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M6 18L18 6M6 6l12 12"
+                    />
+                  ) : (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 6h16M4 12h16M4 18h16"
+                    />
+                  )}
+                </svg>
+              </button>
+              <div>Logo</div>
+            </div>
+            <ul className="hidden items-center gap-4 md:flex">
+              <li>
+                <Link href="#">Features</Link>
+              </li>
+              <li>
+                <Link href="#">Pricing</Link>
+              </li>
+            </ul>
+          </header>
+          {isMenuOpen && (
+            <div className="border-t border-separator md:hidden">
+              <ul className="flex flex-col gap-2 p-4">
+                <li>
+                  <Link href="#" className="block py-2">
+                    Features
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2">
+                    Pricing
+                  </Link>
+                </li>
+              </ul>
+            </div>
+          )}
+        </nav>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Complete Example
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import {
+      Navbar,
+      NavbarBrand,
+      NavbarContent,
+      NavbarItem,
+      NavbarMenu,
+      NavbarMenuItem,
+      NavbarMenuToggle,
+      Link,
+      Button,
+    } from "@heroui/react";
+
+    export default function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <Navbar position="sticky" maxWidth="lg" onMenuOpenChange={setIsMenuOpen}>
+          <NavbarContent>
+            <NavbarMenuToggle className="sm:hidden" />
+            <NavbarBrand>
+              <Logo />
+              <p className="font-bold">ACME</p>
+            </NavbarBrand>
+          </NavbarContent>
+          <NavbarContent className="hidden md:flex">
+            <NavbarItem>
+              <Link href="#">Features</Link>
+            </NavbarItem>
+            <NavbarItem isActive>
+              <Link href="#">Dashboard</Link>
+            </NavbarItem>
+            <NavbarItem>
+              <Link href="#">Pricing</Link>
+            </NavbarItem>
+          </NavbarContent>
+          <NavbarContent justify="end">
+            <NavbarItem>
+              <Link href="#">Login</Link>
+            </NavbarItem>
+            <NavbarItem>
+              <Button>Sign Up</Button>
+            </NavbarItem>
+          </NavbarContent>
+          <NavbarMenu>
+            <NavbarMenuItem>
+              <Link href="#">Features</Link>
+            </NavbarMenuItem>
+            <NavbarMenuItem>
+              <Link href="#">Dashboard</Link>
+            </NavbarMenuItem>
+            <NavbarMenuItem>
+              <Link href="#">Pricing</Link>
+            </NavbarMenuItem>
+          </NavbarMenu>
+        </Navbar>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Link, Button } from "@heroui/react";
+
+    export default function App() {
+      const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+      return (
+        <nav className="sticky top-0 z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg">
+          <header className="mx-auto flex h-16 max-w-5xl items-center justify-between px-6">
+            <div className="flex items-center gap-4">
+              <button
+                className="md:hidden"
+                onClick={() => setIsMenuOpen(!isMenuOpen)}
+                aria-label="Toggle menu"
+                aria-expanded={isMenuOpen}
+              >
+                <span className="sr-only">Menu</span>
+                <svg
+                  className="h-6 w-6"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  {isMenuOpen ? (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M6 18L18 6M6 6l12 12"
+                    />
+                  ) : (
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 6h16M4 12h16M4 18h16"
+                    />
+                  )}
+                </svg>
+              </button>
+              <div className="flex items-center gap-3">
+                <Logo />
+                <p className="font-bold">ACME</p>
+              </div>
+            </div>
+            <ul className="hidden items-center gap-4 md:flex">
+              <li>
+                <Link href="#">Features</Link>
+              </li>
+              <li>
+                <Link href="#" className="font-medium text-accent" aria-current="page">
+                  Dashboard
+                </Link>
+              </li>
+              <li>
+                <Link href="#">Pricing</Link>
+              </li>
+            </ul>
+            <div className="hidden items-center gap-4 md:flex">
+              <Link href="#">Login</Link>
+              <Button>Sign Up</Button>
+            </div>
+          </header>
+          {isMenuOpen && (
+            <div className="border-t border-separator md:hidden">
+              <ul className="flex flex-col gap-2 p-4">
+                <li>
+                  <Link href="#" className="block py-2">
+                    Features
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2 font-medium text-accent">
+                    Dashboard
+                  </Link>
+                </li>
+                <li>
+                  <Link href="#" className="block py-2">
+                    Pricing
+                  </Link>
+                </li>
+                <li className="mt-4 flex flex-col gap-2 border-t border-separator pt-4">
+                  <Link href="#" className="block py-2">
+                    Login
+                  </Link>
+                  <Button className="w-full">Sign Up</Button>
+                </li>
+              </ul>
+            </div>
+          )}
+        </nav>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a Reusable Navbar Component (Recommended)
+
+Since navbars are commonly needed, here's a simplified reusable component:
+
+```tsx
+import { useState, ReactNode } from "react";
+import { Link, Button } from "@heroui/react";
+import { cn } from "@/lib/utils"; // or your cn utility
+
+interface NavbarItem {
+  label: string;
+  href: string;
+  isActive?: boolean;
+}
+
+interface NavbarProps {
+  brand: ReactNode;
+  items: NavbarItem[];
+  rightContent?: ReactNode;
+  className?: string;
+  maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+  position?: "static" | "sticky" | "fixed";
+}
+
+const maxWidthClasses = {
+  sm: "max-w-[640px]",
+  md: "max-w-[768px]",
+  lg: "max-w-[1024px]",
+  xl: "max-w-[1280px]",
+  "2xl": "max-w-[1536px]",
+  full: "max-w-full",
+};
+
+export function Navbar({
+  brand,
+  items,
+  rightContent,
+  className,
+  maxWidth = "lg",
+  position = "sticky",
+}: NavbarProps) {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+
+  return (
+    <nav
+      className={cn(
+        "z-40 w-full border-b border-separator bg-background/70 backdrop-blur-lg",
+        position === "sticky" && "sticky top-0",
+        position === "fixed" && "fixed top-0",
+        className
+      )}
+    >
+      <header
+        className={cn(
+          "flex h-16 items-center justify-between px-6",
+          maxWidth !== "full" && maxWidthClasses[maxWidth],
+          "mx-auto"
+        )}
+      >
+        <div className="flex items-center gap-4">
+          <button
+            className="md:hidden"
+            onClick={() => setIsMenuOpen(!isMenuOpen)}
+            aria-label="Toggle menu"
+            aria-expanded={isMenuOpen}
+          >
+            <span className="sr-only">Menu</span>
+            <svg className="h-6 w-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              {isMenuOpen ? (
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M6 18L18 6M6 6l12 12"
+                />
+              ) : (
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M4 6h16M4 12h16M4 18h16"
+                />
+              )}
+            </svg>
+          </button>
+          {brand}
+        </div>
+        <ul className="hidden items-center gap-4 md:flex">
+          {items.map((item) => (
+            <li key={item.href}>
+              <Link
+                href={item.href}
+                className={cn(item.isActive && "font-medium text-accent")}
+                aria-current={item.isActive ? "page" : undefined}
+              >
+                {item.label}
+              </Link>
+            </li>
+          ))}
+        </ul>
+        {rightContent && <div className="hidden items-center gap-4 md:flex">{rightContent}</div>}
+      </header>
+      {isMenuOpen && (
+        <div className="border-t border-separator md:hidden">
+          <ul className="flex flex-col gap-2 p-4">
+            {items.map((item) => (
+              <li key={item.href}>
+                <Link
+                  href={item.href}
+                  className={cn(
+                    "block py-2",
+                    item.isActive && "font-medium text-accent"
+                  )}
+                >
+                  {item.label}
+                </Link>
+              </li>
+            ))}
+            {rightContent && (
+              <li className="mt-4 flex flex-col gap-2 border-t border-separator pt-4">
+                {rightContent}
+              </li>
+            )}
+          </ul>
+        </div>
+      )}
+    </nav>
+  );
+}
+
+// Usage
+<Navbar
+  brand={
+    <>
+      <Logo />
+      <p className="font-bold">ACME</p>
+    </>
+  }
+  items={[
+    { label: "Features", href: "#features" },
+    { label: "Dashboard", href: "#dashboard", isActive: true },
+    { label: "Pricing", href: "#pricing" },
+  ]}
+  rightContent={
+    <>
+      <Link href="#login">Login</Link>
+      <Button>Sign Up</Button>
+    </>
+  }
+/>
+```
+
+## Advanced Features (Custom Implementation Required)
+
+### Hide on Scroll
+
+The `shouldHideOnScroll` feature requires custom scroll detection:
+
+```tsx
+import { useState, useEffect } from "react";
+
+function useScrollDirection() {
+  const [isHidden, setIsHidden] = useState(false);
+  const [lastScrollY, setLastScrollY] = useState(0);
+
+  useEffect(() => {
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY;
+      setIsHidden(currentScrollY > lastScrollY && currentScrollY > 64);
+      setLastScrollY(currentScrollY);
+    };
+
+    window.addEventListener("scroll", handleScroll);
+    return () => window.removeEventListener("scroll", handleScroll);
+  }, [lastScrollY]);
+
+  return isHidden;
+}
+
+function NavbarWithHideOnScroll() {
+  const isHidden = useScrollDirection();
+
+  return (
+    <nav
+      className={cn(
+        "sticky top-0 z-40 w-full transition-transform duration-300",
+        isHidden && "-translate-y-full"
+      )}
+    >
+      {/* navbar content */}
+    </nav>
+  );
+}
+```
+
+### Scroll Blocking
+
+For blocking scroll when mobile menu is open:
+
+```tsx
+useEffect(() => {
+  if (isMenuOpen) {
+    document.body.style.overflow = "hidden";
+  } else {
+    document.body.style.overflow = "";
+  }
+  return () => {
+    document.body.style.overflow = "";
+  };
+}, [isMenuOpen]);
+```
+
+## Summary
+
+1. **Component Removed**: All Navbar components removed (`Navbar`, `NavbarBrand`, `NavbarContent`, `NavbarItem`, `NavbarMenu`, `NavbarMenuItem`, `NavbarMenuToggle`)
+2. **Import Change**: Remove all Navbar imports from `@heroui/react`
+3. **Manual Composition**: Build navbars using native HTML elements
+4. **Mobile Menu**: Implement mobile menu manually with state management
+5. **Styling**: Apply Tailwind CSS classes directly
+6. **Advanced Features**: Hide on scroll, animations require custom implementation
+
+## Migration Steps
+
+1. **Remove Imports**: Remove all Navbar-related imports
+2. **Replace Structure**: Replace `<Navbar>` with `<nav>` element
+3. **Replace Subcomponents**: Replace subcomponents with semantic HTML (`<header>`, `<ul>`, `<li>`)
+4. **Add Mobile Menu**: Implement mobile menu toggle and menu manually
+5. **Apply Styling**: Use Tailwind CSS classes for layout and styling
+6. **Handle State**: Manage mobile menu state with React `useState`
+7. **Optional**: Create reusable Navbar component for your application
+
+## Common Patterns
+
+### Simple Navigation
+
+```tsx
+<nav className="sticky top-0 z-40 w-full border-b border-separator bg-background">
+  <header className="flex h-16 items-center justify-between px-6">
+    <div>Logo</div>
+    <ul className="flex items-center gap-4">
+      <li><Link href="#">Home</Link></li>
+      <li><Link href="#">About</Link></li>
+      <li><Link href="#">Contact</Link></li>
+    </ul>
+  </header>
+</nav>
+```
+
+### With Dropdown (using v3 Dropdown)
+
+```tsx
+import { Dropdown, Button, Label } from "@heroui/react";
+
+<ul className="flex items-center gap-4">
+  <li>
+    <Dropdown>
+      <Button variant="ghost">Features</Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="feature1" textValue="Feature 1">
+            <Label>Feature 1</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="feature2" textValue="Feature 2">
+            <Label>Feature 2</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  </li>
+</ul>
+```
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/migration/(components)/numberinput.mdx b/apps/docs/content/docs/en/react/migration/(components)/numberinput.mdx
new file mode 100644
index 0000000..a2c8b31
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/numberinput.mdx
@@ -0,0 +1,272 @@
+---
+title: NumberInput
+description: Migration guide for NumberInput to NumberField from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 NumberField documentation](/docs/react/components/numberfield) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, NumberInput was a single component with props:
+
+```tsx
+import { NumberInput } from "@heroui/react";
+
+export default function App() {
+  return <NumberInput label="Amount" defaultValue={1024} />;
+}
+```
+
+In v3, NumberField requires compound components:
+
+```tsx
+import { NumberField, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <NumberField defaultValue={1024}>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Naming
+
+**v2:** `NumberInput`  
+**v3:** `NumberField`
+
+### 2. Component Structure
+
+**v2:** Single component with props  
+**v3:** Compound components: `NumberField.Group`, `NumberField.Input`, `NumberField.IncrementButton`, `NumberField.DecrementButton`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `onValueChange` | `onChange` | Renamed event handler |
+| `label` | — | Use `Label` component |
+| `description` | — | Use `Description` component |
+| `errorMessage` | — | Use `FieldError` component |
+| `variant` | `variant` (on NumberField) | Simplified to `primary` \| `secondary` only |
+| `color` | — | Removed (use Tailwind CSS) |
+| `size` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `startContent` | — | Place content manually in Group |
+| `endContent` | — | Place content manually in Group |
+| `labelPlacement` | — | Handle with layout classes |
+| `hideStepper` | — | Omit `NumberField.IncrementButton` and `NumberField.DecrementButton` |
+| `isClearable` | — | Handle clear functionality manually |
+| `classNames` | — | Use `className` props on individual components |
+| `isWheelDisabled` | — | Removed |
+
+## Migration Examples
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <NumberInput
+      description="Enter the amount"
+      label="Amount"
+    />
+    
+    {/* With error message */}
+    <NumberInput
+      errorMessage="Please enter a valid number"
+      isInvalid
+      label="Amount"
+    />
+    
+    {/* Required */}
+    <NumberInput isRequired label="Quantity" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    {/* With description */}
+    <NumberField>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+      <Description>Enter the amount</Description>
+    </NumberField>
+    
+    {/* With error message */}
+    <NumberField isInvalid>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+      <FieldError>Please enter a valid number</FieldError>
+    </NumberField>
+    
+    {/* Required */}
+    <NumberField isRequired>
+      <Label>Quantity</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState();
+
+    <NumberInput
+      value={value}
+      onValueChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState<number | undefined>();
+
+    <NumberField value={value} onChange={setValue}>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### Without Stepper Buttons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <NumberInput hideStepper label="Amount" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <NumberField>
+      <Label>Amount</Label>
+      <NumberField.Group>
+        <NumberField.Input />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+### Number Constraints
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Min/Max */}
+    <NumberInput
+      label="Quantity"
+      maxValue={100}
+      minValue={0}
+    />
+    
+    {/* Step */}
+    <NumberInput label="Percentage" step={0.1} />
+    
+    {/* Format options */}
+    <NumberInput
+      formatOptions={{style: "currency", currency: "USD"}}
+      label="Price"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Min/Max */}
+    <NumberField maxValue={100} minValue={0}>
+      <Label>Quantity</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    
+    {/* Step */}
+    <NumberField step={0.1}>
+      <Label>Percentage</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    
+    {/* Format options */}
+    <NumberField formatOptions={{style: "currency", currency: "USD"}}>
+      <Label>Price</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 NumberField follows this structure:
+
+```
+NumberField (Root)
+  ├── Label (optional)
+  ├── NumberField.Group
+  │   ├── NumberField.DecrementButton
+  │   ├── NumberField.Input
+  │   └── NumberField.IncrementButton
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## Summary
+
+1. **Component Renamed**: `NumberInput` → `NumberField`
+2. **Component Structure**: Must use compound components (`NumberField.Group`, `NumberField.Input`, etc.)
+3. **Label/Description/Error**: Use separate components (`Label`, `Description`, `FieldError`)
+4. **Stepper Buttons**: Must explicitly include `NumberField.IncrementButton` and `NumberField.DecrementButton`
+5. **Event Handler**: `onValueChange` → `onChange`
+6. **Variant Simplified**: v3 supports only `variant="primary"` and `variant="secondary"`; `color`, `size`, `radius` removed — use Tailwind CSS
+7. **Content Props Removed**: `startContent`, `endContent` - place manually
+8. **Clear Button Removed**: `isClearable` removed - handle manually
+9. **Stepper Control**: `hideStepper` removed - omit buttons instead
+10. **Label Placement Removed**: `labelPlacement` removed - handle with layout
diff --git a/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx b/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx
new file mode 100644
index 0000000..c4a56e5
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/pagination.mdx
@@ -0,0 +1,424 @@
+---
+title: Pagination
+description: Migration guide for Pagination from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Pagination documentation](/docs/react/components/pagination) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `Pagination` was a single component that handled all rendering internally via props:
+
+```tsx
+import { Pagination } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Pagination total={10} initialPage={1} showControls />
+  );
+}
+```
+
+In v3, Pagination uses a compound component pattern where you compose each part explicitly:
+
+```tsx
+import { Pagination } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous>
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link isActive>1</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>2</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>3</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Ellipsis />
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>10</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Pagination` component that auto-generates page items from `total` prop
+**v3:** Compound components: `Pagination`, `Pagination.Summary`, `Pagination.Content`, `Pagination.Item`, `Pagination.Link`, `Pagination.Previous`, `Pagination.PreviousIcon`, `Pagination.Next`, `Pagination.NextIcon`, `Pagination.Ellipsis`
+
+### 2. Page Generation
+
+**v2:** Pages auto-generated from `total`, `siblings`, `boundaries` props
+**v3:** You compose page items manually, giving full control over layout and behavior. Build your own pagination logic or use a pagination hook.
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `total` | - | Removed (compose items manually) |
+| `page` | - | Manage active state via `isActive` on `Pagination.Link` |
+| `initialPage` | - | Manage state externally |
+| `onChange` | - | Use `onPress` on individual `Pagination.Link` components |
+| `siblings` | - | Removed (compose items manually) |
+| `boundaries` | - | Removed (compose items manually) |
+| `dotsJump` | - | Removed (handle ellipsis click manually) |
+| `loop` | - | Removed (implement manually) |
+| `showControls` | - | Compose `Pagination.Previous` and `Pagination.Next` |
+| `isCompact` | - | Removed (style with Tailwind CSS) |
+| `showShadow` | - | Removed (use Tailwind `shadow-*` classes) |
+| `size` | `Pagination` `size` | Same (`sm`, `md`, `lg`) |
+| `variant` | - | Removed (use Tailwind CSS) |
+| `color` | - | Removed (use Tailwind CSS) |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `isDisabled` | `isDisabled` on `Pagination.Link`, `Pagination.Previous`, `Pagination.Next` | Per-item instead of global |
+| `disableCursorAnimation` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `renderItem` | - | Compose items directly |
+| `getItemAriaLabel` | - | Set `aria-label` on individual items |
+| `classNames` | - | Use `className` on individual compound components |
+
+### 4. Hook Changes
+
+**v2:** `usePagination` hook available for custom implementations
+**v3:** No built-in hook — compose pagination items directly or build your own pagination logic
+
+## Migration Examples
+
+### Basic Pagination
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Pagination } from "@heroui/react";
+
+    <Pagination total={10} initialPage={1} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Pagination } from "@heroui/react";
+
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### With Previous / Next Controls
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Pagination total={10} initialPage={1} showControls />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => Math.max(1, p - 1))}
+          >
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+          >
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### With Ellipsis
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Pagination total={20} initialPage={1} siblings={1} boundaries={1} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 20;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => Math.max(1, p - 1))}
+          >
+            <Pagination.PreviousIcon />
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link isActive={page === 1} onPress={() => setPage(1)}>
+            1
+          </Pagination.Link>
+        </Pagination.Item>
+        {page > 3 && (
+          <Pagination.Item>
+            <Pagination.Ellipsis />
+          </Pagination.Item>
+        )}
+        {[page - 1, page, page + 1]
+          .filter((p) => p > 1 && p < totalPages)
+          .map((p) => (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={page === p} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ))}
+        {page < totalPages - 2 && (
+          <Pagination.Item>
+            <Pagination.Ellipsis />
+          </Pagination.Item>
+        )}
+        <Pagination.Item>
+          <Pagination.Link
+            isActive={page === totalPages}
+            onPress={() => setPage(totalPages)}
+          >
+            {totalPages}
+          </Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+          >
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### Simple Previous / Next Only
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 didn't have a built-in simple prev/next pattern */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const totalPages = 10;
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => p - 1)}
+          >
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => p + 1)}
+          >
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### With Summary
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 didn't have a built-in summary slot */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [page, setPage] = useState(1);
+    const perPage = 10;
+    const total = 100;
+
+    <Pagination>
+      <Pagination.Summary>
+        Showing {(page - 1) * perPage + 1}-{Math.min(page * perPage, total)} of {total}
+      </Pagination.Summary>
+      <Pagination.Content>
+        {/* Pagination items */}
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 required renderItem for custom icons */}
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Icon } from "@iconify/react";
+
+    <Pagination>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon>
+              <Icon icon="gravity-ui:arrow-left" />
+            </Pagination.PreviousIcon>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {/* Page links */}
+        <Pagination.Item>
+          <Pagination.Next onPress={() => setPage((p) => p + 1)}>
+            <Pagination.NextIcon>
+              <Icon icon="gravity-ui:arrow-right" />
+            </Pagination.NextIcon>
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Pagination
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    prev: "custom-prev",
+    next: "custom-next",
+    item: "custom-item",
+    cursor: "custom-cursor",
+    ellipsis: "custom-ellipsis",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Pagination className="custom-base">
+  <Pagination.Content className="custom-wrapper">
+    <Pagination.Item className="custom-item">
+      <Pagination.Previous className="custom-prev">
+        <Pagination.PreviousIcon />
+      </Pagination.Previous>
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Link isActive className="custom-cursor">1</Pagination.Link>
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Ellipsis className="custom-ellipsis" />
+    </Pagination.Item>
+    <Pagination.Item>
+      <Pagination.Next className="custom-next">
+        <Pagination.NextIcon />
+      </Pagination.Next>
+    </Pagination.Item>
+  </Pagination.Content>
+</Pagination>
+```
+
+## Component Anatomy
+
+The v3 Pagination follows this structure:
+
+```
+Pagination (Root, nav element)
+  ├── Pagination.Summary (optional, info text)
+  └── Pagination.Content (ul container)
+      └── Pagination.Item (li wrapper, repeated)
+          ├── Pagination.Previous (with Pagination.PreviousIcon)
+          ├── Pagination.Link (page number, isActive for current)
+          ├── Pagination.Ellipsis
+          └── Pagination.Next (with Pagination.NextIcon)
+```
+
+## Summary
+
+1. **Component Structure**: Single auto-generating component → compound components with manual composition
+2. **Page Generation**: `total`/`siblings`/`boundaries` props → compose page items manually with your own pagination logic
+3. **Active Page**: `page`/`initialPage` props → `isActive` prop on individual `Pagination.Link`
+4. **Navigation Controls**: `showControls` prop → compose `Pagination.Previous` and `Pagination.Next` directly
+5. **Ellipsis**: Auto-generated → compose `Pagination.Ellipsis` manually where needed
+6. **Events**: Single `onChange` → individual `onPress` handlers on each `Pagination.Link`
+7. **New Features**: `Pagination.Summary` for showing result counts, custom icons via `PreviousIcon`/`NextIcon` children
+8. **Hook Removed**: `usePagination` → build your own pagination logic
+9. **Styling Props Removed**: `variant`, `color`, `radius`, `isCompact`, `showShadow` → use Tailwind CSS
+10. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/popover.mdx b/apps/docs/content/docs/en/react/migration/(components)/popover.mdx
new file mode 100644
index 0000000..1729311
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/popover.mdx
@@ -0,0 +1,279 @@
+---
+title: Popover
+description: Migration guide for Popover from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Popover documentation](/docs/react/components/popover) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Popover used separate components:
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Popover placement="right">
+      <PopoverTrigger>
+        <Button>Open</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div>Content</div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+In v3, Popover uses compound components:
+
+```tsx
+import { Popover, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <Popover.Heading>Title</Popover.Heading>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Separate components (`Popover`, `PopoverTrigger`, `PopoverContent`)  
+**v3:** Compound components (`Popover`, `Popover.Trigger`, `Popover.Content`, `Popover.Dialog`, `Popover.Heading`, `Popover.Arrow`)
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `placement` | `placement` (on Content) | Moved to `Popover.Content` |
+| `offset` | `offset` (on Content) | Moved to `Popover.Content` |
+| `shouldFlip` | `shouldFlip` (on Content) | Moved to `Popover.Content` |
+| `isOpen` / `defaultOpen` / `onOpenChange` | Same (on root) | Controlled state stays on root `Popover` |
+| `showArrow` | — | Use `Popover.Arrow` component |
+| `size` | — | Removed (use Tailwind CSS) |
+| `color` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `shadow` | — | Removed (use Tailwind CSS) |
+| `backdrop` | — | Removed |
+| `motionProps` | — | Removed (animations handled differently) |
+| `classNames` | — | Use `className` on each part |
+| `onClose` | — | Use `onOpenChange((open) => { if (!open) { ... } })` instead |
+
+## Migration Examples
+
+### Content Configuration
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With arrow */}
+    <Popover showArrow>
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    
+    {/* With placement */}
+    <Popover placement="top">
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    
+    {/* With offset */}
+    <Popover offset={10}>
+      <PopoverTrigger><Button>Open</Button></PopoverTrigger>
+      <PopoverContent><div>Content</div></PopoverContent>
+    </Popover>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With arrow - use component */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <Popover.Arrow />
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    
+    {/* With placement - moved to Content */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content placement="top">
+        <Popover.Dialog>
+          <Popover.Arrow />
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    
+    {/* With offset - moved to Content */}
+    <Popover>
+      <Button>Open</Button>
+      <Popover.Content offset={10}>
+        <Popover.Dialog>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    ```
+  </Tab>
+</Tabs>
+
+### With Heading
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <PopoverContent>
+      <div className="px-1 py-2">
+        <div className="text-small font-bold">Title</div>
+        <div className="text-tiny">Content</div>
+      </div>
+    </PopoverContent>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Popover.Content>
+      <Popover.Dialog>
+        <Popover.Heading>Title</Popover.Heading>
+        <p className="text-muted mt-2 text-sm">Content</p>
+      </Popover.Dialog>
+    </Popover.Content>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Popover isOpen={isOpen} onOpenChange={setIsOpen}>
+      <PopoverTrigger>
+        <Button>Open</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div>Content</div>
+      </PopoverContent>
+    </Popover>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Popover isOpen={isOpen} onOpenChange={setIsOpen}>
+      <Button>Open</Button>
+      <Popover.Content>
+        <Popover.Dialog>
+          <div>Content</div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Trigger
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <PopoverTrigger>
+      <CustomButton>Custom</CustomButton>
+    </PopoverTrigger>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Popover.Trigger>
+      <CustomButton>Custom</CustomButton>
+    </Popover.Trigger>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Popover follows this structure:
+
+```
+Popover (Root)
+  ├── Popover.Trigger (optional, or use Button directly)
+  └── Popover.Content
+      └── Popover.Dialog
+          ├── Popover.Arrow (optional)
+          ├── Popover.Heading (optional)
+          └── Content
+```
+
+## New Capabilities in v3
+
+### Popover.Arrow Component
+
+In v2, the arrow was controlled by the `showArrow` boolean prop on the root `Popover`. In v3, `Popover.Arrow` is a dedicated component placed inside `Popover.Content`, giving you full control over its rendering:
+
+```tsx
+<Popover>
+  <Button>Open</Button>
+  <Popover.Content>
+    <Popover.Arrow className="custom-arrow" />
+    <Popover.Dialog>
+      <div>Content</div>
+    </Popover.Dialog>
+  </Popover.Content>
+</Popover>
+```
+
+`Popover.Arrow` also accepts a `render` prop for fully custom arrow rendering.
+
+### Controlled Open State
+
+Controlled open state remains on the root `Popover` component, using the same prop names as v2:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | `boolean` | - | Controls popover visibility (controlled) |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Called when open state changes |
+
+### Custom Render Function
+
+`Popover.Content` and `Popover.Arrow` both support a `render` prop that allows you to override the default DOM element with a custom render function for advanced use cases.
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Popover.Content`, `Popover.Dialog`, etc.)
+2. **Trigger**: Can use `Popover.Trigger` or Button directly
+3. **Content Wrapper**: Content must be wrapped in `Popover.Dialog`
+4. **Arrow**: `showArrow` prop removed - use `Popover.Arrow` component
+5. **Heading**: Use `Popover.Heading` component for titles
+6. **Props Moved**: `placement`, `offset`, `shouldFlip` moved to `Popover.Content`
+7. **Styling Props Removed**: `size`, `color`, `radius`, `shadow` - use Tailwind CSS
+8. **Backdrop Removed**: `backdrop` prop removed
+9. **Motion Removed**: `motionProps` removed, animations handled differently
+10. **ClassNames Removed**: Use `className` props on individual components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/progress.mdx b/apps/docs/content/docs/en/react/migration/(components)/progress.mdx
new file mode 100644
index 0000000..2ef4fca
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/progress.mdx
@@ -0,0 +1,223 @@
+---
+title: Progress
+description: Migration guide for Progress from HeroUI v2 to v3 (now ProgressBar)
+---
+
+<Callout type="info">
+  Refer to the [v3 ProgressBar documentation](/docs/react/components/progress-bar) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+<Callout type="warning">
+  Looking for the CircularProgress migration? See the [CircularProgress migration guide](/docs/react/migration/circular-progress).
+</Callout>
+
+## Component Rename
+
+`Progress` has been renamed to `ProgressBar` in v3.
+
+## Structure Changes
+
+In v2, `Progress` was a single component configured with props:
+
+```tsx
+import { Progress } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Progress label="Loading..." value={60} />
+  );
+}
+```
+
+In v3, `ProgressBar` uses a compound component pattern:
+
+```tsx
+import { ProgressBar, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ProgressBar value={60}>
+      <Label>Loading...</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `Progress` component with all parts rendered internally
+**v3:** Compound components: `ProgressBar`, `ProgressBar.Output`, `ProgressBar.Track`, `ProgressBar.Fill`, plus external `Label`
+
+### 2. Colors
+
+**v2:** `default`, `primary`, `secondary`, `success`, `warning`, `danger`
+**v3:** `default`, `accent`, `success`, `warning`, `danger`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isIndeterminate` | `isIndeterminate` | Same |
+| `formatOptions` | `formatOptions` | Same |
+| `size` | `size` | Same (`sm`, `md`, `lg`) |
+| `color` | `color` | `primary` → `accent`, `secondary` removed |
+| `label` | - | Use `Label` component |
+| `valueLabel` | `valueLabel` | Same |
+| `showValueLabel` | - | Include or omit `ProgressBar.Output` |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `isStriped` | - | Removed (use Tailwind CSS on `ProgressBar.Fill`) |
+| `isDisabled` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual compound components |
+
+## Migration Examples
+
+### Basic Progress
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Progress } from "@heroui/react";
+
+    <Progress label="Loading..." value={60} color="primary" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { ProgressBar, Label } from "@heroui/react";
+
+    <ProgressBar value={60} color="accent">
+      <Label>Loading...</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### Indeterminate
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress isIndeterminate aria-label="Loading..." size="sm" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar isIndeterminate aria-label="Loading..." size="sm">
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### Without Label (Accessibility)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress aria-label="Loading..." value={70} />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar aria-label="Loading..." value={70}>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Formatting
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Progress
+      label="Budget"
+      formatOptions={{ style: "currency", currency: "USD" }}
+      maxValue={10000}
+      value={4000}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ProgressBar
+      formatOptions={{ style: "currency", currency: "USD" }}
+      maxValue={10000}
+      value={4000}
+    >
+      <Label>Budget</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Progress
+  classNames={{
+    base: "custom-base",
+    track: "custom-track",
+    indicator: "custom-fill",
+    label: "custom-label",
+    value: "custom-value",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<ProgressBar className="custom-base" value={60}>
+  <Label className="custom-label">Loading</Label>
+  <ProgressBar.Output className="custom-value" />
+  <ProgressBar.Track className="custom-track">
+    <ProgressBar.Fill className="custom-fill" />
+  </ProgressBar.Track>
+</ProgressBar>
+```
+
+## Component Anatomy
+
+```
+ProgressBar (Root)
+  ├── Label (optional)
+  ├── ProgressBar.Output (optional, formatted value display)
+  └── ProgressBar.Track
+      └── ProgressBar.Fill
+```
+
+## Summary
+
+1. **Renamed**: `Progress` → `ProgressBar`
+2. **Component Structure**: Single component → compound components (`ProgressBar.Output`, `ProgressBar.Track`, `ProgressBar.Fill`)
+3. **Label**: `label` prop → `Label` component
+4. **Value Display**: `showValueLabel` prop → include or omit `ProgressBar.Output`
+5. **Color Changes**: `primary` → `accent`, `secondary` removed
+6. **Removed Props**: `radius`, `isStriped`, `isDisabled`, `disableAnimation` → use Tailwind CSS
+7. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/radio-group.mdx b/apps/docs/content/docs/en/react/migration/(components)/radio-group.mdx
new file mode 100644
index 0000000..6e7263b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/radio-group.mdx
@@ -0,0 +1,270 @@
+---
+title: RadioGroup
+description: Migration guide for RadioGroup from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 RadioGroup documentation](/docs/react/components/radio-group) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `RadioGroup` used a `label` prop:
+
+```tsx
+import { RadioGroup, Radio } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo" description="Capital of Japan">Tokyo</Radio>
+      <Radio value="paris">Paris</Radio>
+    </RadioGroup>
+  );
+}
+```
+
+In v3, `RadioGroup` uses `Label` component and works with compound Radio structure:
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup name="city">
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+        <Description>Capital of Japan</Description>
+      </Radio>
+      <Radio value="paris">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Paris
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Label Prop → Label Component
+
+**v2:** Used `label` prop on `RadioGroup`  
+**v3:** Use `Label` component as a child of `RadioGroup`
+
+### 2. Radio Structure
+
+**v2:** Simple Radio components with children as labels  
+**v3:** Compound Radio components with `Radio.Content`, `Radio.Control`, and `Radio.Indicator`
+
+### 3. Description Handling
+
+**v2:** Used `description` prop on individual `Radio` components  
+**v3:** Use `Description` component as a sibling of `Radio.Content`
+
+### 4. Event Handler
+
+**v2:** Used `onValueChange` prop  
+**v3:** Uses `onChange` prop (from React Aria Components)
+
+### 5. Name Prop
+
+**v3:** `name` prop is required for form integration
+
+### 6. Variant Support
+
+**v3:** New `variant` prop: `"primary"` (default) or `"secondary"` for lower emphasis styling suitable for Surface components
+
+### 7. Read Only Support
+
+**v3:** New `isReadOnly` prop prevents value changes while keeping the group focusable
+
+## Migration Examples
+
+### RadioGroup with Descriptions
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RadioGroup label="Select plan">
+      <Radio value="basic" description="Basic features">Basic</Radio>
+      <Radio value="pro" description="All features">Pro</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+    <RadioGroup name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+        <Description>Basic features</Description>
+      </Radio>
+      <Radio value="pro">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Pro
+        </Radio.Content>
+        <Description>All features</Description>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have variant support */}
+    <RadioGroup label="Select plan">
+      <Radio value="basic">Basic</Radio>
+      <Radio value="pro">Pro</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RadioGroup, Radio, Label } from "@heroui/react";
+
+    {/* Primary variant (default) */}
+    <RadioGroup variant="primary" name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+
+    {/* Secondary variant - lower emphasis, suitable for Surface components */}
+    <RadioGroup variant="secondary" name="plan">
+      <Label>Select plan</Label>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Read Only
+
+```tsx
+import { RadioGroup, Radio, Label } from "@heroui/react";
+
+{/* Prevents value changes while keeping the group focusable */}
+<RadioGroup isReadOnly defaultValue="basic" name="plan">
+  <Label>Select plan</Label>
+  <Radio value="basic">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Basic
+    </Radio.Content>
+  </Radio>
+  <Radio value="pro">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Pro
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+### Controlled RadioGroup
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { RadioGroup, Radio } from "@heroui/react";
+
+    const [value, setValue] = useState("london");
+
+    <RadioGroup value={value} onValueChange={setValue} label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { RadioGroup, Radio, Label } from "@heroui/react";
+
+    const [value, setValue] = useState("london");
+
+    <RadioGroup name="city" value={value} onChange={setValue}>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+- Replace `label` prop with `Label` component as child
+- Update Radio children to use compound component structure
+- Replace `description` prop on Radio with `Description` component as a sibling of `Radio.Content`
+- Change `onValueChange` to `onChange`
+- Add `name` prop for form integration
+- New `variant` prop: `"primary"` (default) or `"secondary"` for lower emphasis styling
+- New `isReadOnly` prop: prevents value changes while keeping the group focusable
+- Better accessibility through React Aria Components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/radio.mdx b/apps/docs/content/docs/en/react/migration/(components)/radio.mdx
new file mode 100644
index 0000000..e681793
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/radio.mdx
@@ -0,0 +1,305 @@
+---
+title: Radio
+description: Migration guide for Radio from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Radio documentation](/docs/react/components/radio-group) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Radio used a simple structure with props:
+
+```tsx
+import { RadioGroup, Radio } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo" description="Capital of Japan">Tokyo</Radio>
+    </RadioGroup>
+  );
+}
+```
+
+In v3, Radio requires compound components:
+
+```tsx
+import { RadioGroup, Radio, Label, Description } from "@heroui/react";
+
+export default function App() {
+  return (
+    <RadioGroup>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+        <Description>Capital of Japan</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple Radio with children as label  
+**v3:** Compound components: `Radio.Content`, `Radio.Control`, `Radio.Indicator`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `onValueChange` | `onChange` | Renamed event handler |
+| `label` (on RadioGroup) | — | Use `Label` component |
+| `description` (on Radio) | — | Use `Description` component as a sibling of `Radio.Content` |
+| `size` | — | Removed (use Tailwind CSS) |
+| `color` | — | Removed (use Tailwind CSS) |
+| `classNames` | — | Use `className` props on individual components |
+| `disableAnimation` | — | Removed (animations handled differently) |
+| — | `variant` | New prop on `RadioGroup`: `"primary"` (default) or `"secondary"` for lower emphasis styling |
+| — | `isReadOnly` | New prop on `RadioGroup`: prevents value changes while keeping the group focusable |
+
+## Migration Examples
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <RadioGroup label="Select city">
+      <Radio value="london" description="Capital of England">
+        London
+      </Radio>
+    </RadioGroup>
+    
+    {/* With validation */}
+    <RadioGroup
+      isInvalid
+      errorMessage="Please select an option"
+      label="Select city"
+    >
+      <Radio value="london">London</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Description, FieldError } from "@heroui/react";
+
+    {/* With description */}
+    <RadioGroup>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+        <Description>Capital of England</Description>
+      </Radio>
+    </RadioGroup>
+    
+    {/* With validation */}
+    <RadioGroup isInvalid>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <FieldError>Please select an option</FieldError>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("london");
+
+    <RadioGroup
+      value={selected}
+      onValueChange={setSelected}
+    >
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("london");
+
+    <RadioGroup value={selected} onChange={setSelected}>
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Horizontal Orientation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RadioGroup orientation="horizontal" label="Select city">
+      <Radio value="london">London</Radio>
+      <Radio value="tokyo">Tokyo</Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RadioGroup orientation="horizontal">
+      <Label>Select city</Label>
+      <Radio value="london">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          London
+        </Radio.Content>
+      </Radio>
+      <Radio value="tokyo">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Tokyo
+        </Radio.Content>
+      </Radio>
+    </RadioGroup>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants
+
+v3 introduces a `variant` prop on `RadioGroup` with `"primary"` (default) and `"secondary"` options:
+
+```tsx
+{/* Primary variant (default) */}
+<RadioGroup variant="primary">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+
+{/* Secondary variant - lower emphasis, suitable for Surface components */}
+<RadioGroup variant="secondary">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+### Read Only
+
+v3 supports `isReadOnly` on `RadioGroup`, which prevents value changes while keeping the group focusable:
+
+```tsx
+<RadioGroup isReadOnly defaultValue="london">
+  <Label>Select city</Label>
+  <Radio value="london">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      London
+    </Radio.Content>
+  </Radio>
+  <Radio value="tokyo">
+    <Radio.Content>
+      <Radio.Control>
+        <Radio.Indicator />
+      </Radio.Control>
+      Tokyo
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+## Component Anatomy
+
+The v3 Radio follows this structure:
+
+```
+RadioGroup (Root)
+  ├── Label (optional)
+  ├── Radio
+  │   ├── Radio.Content (the clickable label)
+  │   │   ├── Radio.Control
+  │   │   │   └── Radio.Indicator
+  │   │   └── Label
+  │   └── Description (optional, sibling)
+  └── FieldError (optional)
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Radio.Content`, `Radio.Control`, `Radio.Indicator`)
+2. **Label Handling**: `label` prop removed - use `Label` component
+3. **Description Handling**: `description` prop removed - use `Description` component as a sibling of `Radio.Content`
+4. **Event Handler**: `onValueChange` → `onChange`
+5. **Styling Props Removed**: `size`, `color` - use Tailwind CSS
+6. **ClassNames Removed**: Use `className` props on individual components
+7. **Error Message**: Use `FieldError` component instead of `errorMessage` prop
+8. **New `variant` Prop**: `RadioGroup` supports `"primary"` (default) and `"secondary"` for lower emphasis styling
+9. **New `isReadOnly` Prop**: `RadioGroup` supports `isReadOnly` to prevent value changes while keeping the group focusable
diff --git a/apps/docs/content/docs/en/react/migration/(components)/range-calendar.mdx b/apps/docs/content/docs/en/react/migration/(components)/range-calendar.mdx
new file mode 100644
index 0000000..b337184
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/range-calendar.mdx
@@ -0,0 +1,446 @@
+---
+title: RangeCalendar
+description: Migration guide for RangeCalendar from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 RangeCalendar documentation](/docs/react/components/range-calendar) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `RangeCalendar` was a single component configured entirely through props:
+
+```tsx
+import { RangeCalendar } from "@heroui/react";
+import { today, getLocalTimeZone } from "@internationalized/date";
+
+export default function App() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    />
+  );
+}
+```
+
+In v3, RangeCalendar uses a compound component pattern with explicit subcomponents:
+
+```tsx
+import { RangeCalendar } from "@heroui/react";
+import { today, getLocalTimeZone } from "@internationalized/date";
+
+export default function App() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Single `RangeCalendar` component with all layout handled internally
+**v3:** Compound components: `RangeCalendar.Header`, `RangeCalendar.Heading`, `RangeCalendar.NavButton`, `RangeCalendar.Grid`, `RangeCalendar.GridHeader`, `RangeCalendar.GridBody`, `RangeCalendar.HeaderCell`, `RangeCalendar.Cell`, `RangeCalendar.CellIndicator`
+
+### 2. Year Picker
+
+**v2:** Built-in month/year pickers via `showMonthAndYearPickers` prop
+**v3:** Dedicated compound components: `RangeCalendar.YearPickerTrigger`, `RangeCalendar.YearPickerGrid`, `RangeCalendar.YearPickerGridBody`, `RangeCalendar.YearPickerCell`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `value` | `value` | Same |
+| `defaultValue` | `defaultValue` | Same |
+| `onChange` | `onChange` | Same |
+| `focusedValue` | `focusedValue` | Same |
+| `onFocusChange` | `onFocusChange` | Same |
+| `minValue` | `minValue` | Same |
+| `maxValue` | `maxValue` | Same |
+| `isDateUnavailable` | `isDateUnavailable` | Same |
+| `allowsNonContiguousRanges` | `allowsNonContiguousRanges` | Same |
+| `isDisabled` | `isDisabled` | Same |
+| `isReadOnly` | `isReadOnly` | Same |
+| `isInvalid` | `isInvalid` | Same |
+| `pageBehavior` | `pageBehavior` | Same |
+| `visibleMonths` | `visibleDuration` | Changed to `{months: number}` object |
+| `showMonthAndYearPickers` | - | Use `RangeCalendar.YearPickerTrigger` and `RangeCalendar.YearPickerGrid` |
+| `onHeaderExpandedChange` | `onYearPickerOpenChange` | Renamed |
+| `color` | - | Removed (use Tailwind CSS) |
+| `calendarWidth` | - | Removed (use `className` or Tailwind CSS) |
+| `weekdayStyle` | - | Removed |
+| `firstDayOfWeek` | - | Use `I18nProvider` locale instead |
+| `topContent` | - | Place custom content inside `RangeCalendar` before the grid |
+| `bottomContent` | - | Place custom content inside `RangeCalendar` after the grid |
+| `errorMessage` | - | Removed (handle validation externally) |
+| `showHelper` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual compound components |
+
+## Migration Examples
+
+### Basic Range Selection
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { RangeCalendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { RangeCalendar } from "@heroui/react";
+    import { today, getLocalTimeZone } from "@internationalized/date";
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{
+        start: today(getLocalTimeZone()),
+        end: today(getLocalTimeZone()).add({ weeks: 1 }),
+      }}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+    import { RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-07"),
+    });
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { RangeCalendar } from "@heroui/react";
+    import { parseDate } from "@internationalized/date";
+
+    const [value, setValue] = useState({
+      start: parseDate("2024-03-01"),
+      end: parseDate("2024-03-07"),
+    });
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      value={value}
+      onChange={setValue}
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Month and Year Pickers
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      showMonthAndYearPickers
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates">
+      <RangeCalendar.Header>
+        <RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.YearPickerTriggerHeading />
+          <RangeCalendar.YearPickerTriggerIndicator />
+        </RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <RangeCalendar.YearPickerGrid>
+        <RangeCalendar.YearPickerGridBody>
+          {(year) => <RangeCalendar.YearPickerCell date={year} />}
+        </RangeCalendar.YearPickerGridBody>
+      </RangeCalendar.YearPickerGrid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Multiple Months
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      visibleMonths={2}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates" visibleDuration={{months: 2}}>
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <div className="flex gap-4">
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+        <RangeCalendar.Grid offset={{months: 1}}>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </div>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Unavailable Dates with Non-Contiguous Ranges
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+      allowsNonContiguousRanges
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { isWeekend } from "@internationalized/date";
+    import { useLocale } from "@react-aria/i18n";
+
+    const { locale } = useLocale();
+
+    <RangeCalendar
+      aria-label="Trip dates"
+      isDateUnavailable={(date) => isWeekend(date, locale)}
+      allowsNonContiguousRanges
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+### Top and Bottom Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <RangeCalendar
+      aria-label="Trip dates"
+      topContent={<p>Select your travel dates</p>}
+      bottomContent={
+        <button onClick={handleReset}>Reset</button>
+      }
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <RangeCalendar aria-label="Trip dates">
+      <p>Select your travel dates</p>
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <button onClick={handleReset}>Reset</button>
+    </RangeCalendar>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<RangeCalendar
+  classNames={{
+    base: "custom-base",
+    prevButton: "custom-prev",
+    nextButton: "custom-next",
+    title: "custom-title",
+    cell: "custom-cell",
+    cellButton: "custom-cell-button",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<RangeCalendar className="custom-base">
+  <RangeCalendar.Header>
+    <RangeCalendar.Heading className="custom-title" />
+    <RangeCalendar.NavButton slot="previous" className="custom-prev" />
+    <RangeCalendar.NavButton slot="next" className="custom-next" />
+  </RangeCalendar.Header>
+  <RangeCalendar.Grid>
+    <RangeCalendar.GridHeader>
+      {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+    </RangeCalendar.GridHeader>
+    <RangeCalendar.GridBody>
+      {(date) => <RangeCalendar.Cell date={date} className="custom-cell" />}
+    </RangeCalendar.GridBody>
+  </RangeCalendar.Grid>
+</RangeCalendar>
+```
+
+## Component Anatomy
+
+The v3 RangeCalendar follows this structure:
+
+```
+RangeCalendar (Root)
+  ├── [Custom top content]
+  ├── RangeCalendar.Header
+  │   ├── RangeCalendar.Heading (or RangeCalendar.YearPickerTrigger)
+  │   ├── RangeCalendar.NavButton slot="previous"
+  │   └── RangeCalendar.NavButton slot="next"
+  ├── RangeCalendar.Grid (one per visible month)
+  │   ├── RangeCalendar.GridHeader
+  │   │   └── RangeCalendar.HeaderCell (render prop)
+  │   └── RangeCalendar.GridBody
+  │       └── RangeCalendar.Cell (render prop)
+  │           └── RangeCalendar.CellIndicator (optional)
+  ├── RangeCalendar.YearPickerGrid (optional)
+  │   └── RangeCalendar.YearPickerGridBody
+  │       └── RangeCalendar.YearPickerCell
+  └── [Custom bottom content]
+```
+
+## Summary
+
+1. **Component Structure**: Single component → compound components with explicit layout control
+2. **Year Picker**: `showMonthAndYearPickers` prop → dedicated `RangeCalendar.YearPickerTrigger` and `RangeCalendar.YearPickerGrid` components
+3. **Multiple Months**: `visibleMonths={n}` → `visibleDuration={{months: n}}` with multiple `RangeCalendar.Grid` components using `offset`
+4. **Color Removed**: Use Tailwind CSS classes instead
+5. **Top/Bottom Content**: Props removed → place content directly as children inside `RangeCalendar`
+6. **Cell Customization**: New `RangeCalendar.CellIndicator` and render prop support on `RangeCalendar.Cell`
+7. **Styling**: `classNames` prop → `className` on individual compound components
+8. **Removed Props**: `calendarWidth`, `weekdayStyle`, `showHelper`, `errorMessage`, `disableAnimation` — use Tailwind CSS or handle externally
diff --git a/apps/docs/content/docs/en/react/migration/(components)/scroll-shadow.mdx b/apps/docs/content/docs/en/react/migration/(components)/scroll-shadow.mdx
new file mode 100644
index 0000000..acc6f79
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/scroll-shadow.mdx
@@ -0,0 +1,148 @@
+---
+title: ScrollShadow
+description: Migration guide for ScrollShadow from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 ScrollShadow documentation](/docs/react/components/scroll-shadow) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, `ScrollShadow` was a wrapper component:
+
+```tsx
+import { ScrollShadow } from "@heroui/scroll-shadow";
+
+export default function App() {
+  return (
+    <ScrollShadow>
+      {/* scrollable content */}
+    </ScrollShadow>
+  );
+}
+```
+
+In v3, `ScrollShadow` has the same basic structure but with more configuration options:
+
+```tsx
+import { ScrollShadow } from "@heroui/react";
+
+export default function App() {
+  return (
+    <ScrollShadow>
+      {/* scrollable content */}
+    </ScrollShadow>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Import Path
+
+**v2:** Imported from `@heroui/scroll-shadow` package  
+**v3:** Imported from `@heroui/react` unified package
+
+### 2. Visibility Control
+
+**v2:** `visibility` prop controlled shadow placement  
+**v3:** Enhanced `visibility` prop with more options and `onVisibilityChange` callback
+
+### 3. Shadow Size Control
+
+**v2:** Shadow size was fixed or limited customization  
+**v3:** `size` prop allows custom shadow size in pixels
+
+### 4. Enhanced Props
+
+**v3:** New props available:
+- `size` - Shadow size in pixels (default: 40)
+- `offset` - Scroll offset before showing shadows (default: 0)
+- `isEnabled` - Enable/disable shadow detection (default: true)
+- `hideScrollBar` - Hide scrollbar while maintaining scroll functionality
+- `variant` - Shadow effect type (default: `fade`)
+- `onVisibilityChange` - Callback when shadow visibility changes
+
+## Migration Examples
+
+### Custom Shadow Size
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow>
+      {/* Shadow size was fixed */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ScrollShadow size={80} className="max-h-[400px]">
+      {/* Large shadow */}
+    </ScrollShadow>
+    ```
+  </Tab>
+</Tabs>
+
+### Enhanced Visibility Control
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow visibility="bottom">
+      {/* content */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { ScrollShadow } from "@heroui/react";
+
+    function App() {
+      const [visibility, setVisibility] = useState("none");
+
+      return (
+        <>
+          <p>Shadow state: {visibility}</p>
+          <ScrollShadow
+            onVisibilityChange={setVisibility}
+            className="max-h-[400px]"
+          >
+            {/* content */}
+          </ScrollShadow>
+        </>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Variant
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <ScrollShadow>
+      {/* v2 used theme variants (e.g. orientation, hideScrollBar) */}
+    </ScrollShadow>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <ScrollShadow variant="fade" className="max-h-[400px]">
+      {/* Shadow effect controlled by variant (default: fade) */}
+    </ScrollShadow>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+- Update import from `@heroui/scroll-shadow` to `@heroui/react`
+- Enhanced API with more configuration options
+- Better shadow detection and visibility control
+- Same orientation support (vertical / horizontal); import from `@heroui/react`
+- Customizable shadow size and variant (e.g. fade)
+- Improved performance and accessibility
diff --git a/apps/docs/content/docs/en/react/migration/(components)/select.mdx b/apps/docs/content/docs/en/react/migration/(components)/select.mdx
new file mode 100644
index 0000000..abc6b76
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/select.mdx
@@ -0,0 +1,543 @@
+---
+title: Select
+description: Migration guide for Select from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Select documentation](/docs/react/components/select) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Select used a simple structure with props:
+
+```tsx
+import { Select, SelectItem } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Select label="Select animal" placeholder="Choose one">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+  );
+}
+```
+
+In v3, Select requires compound components and uses `ListBox` for items:
+
+```tsx
+import { Select, Label, ListBox } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple Select with `SelectItem` children  
+**v3:** Compound components (`Select.Trigger`, `Select.Value`, `Select.Indicator`, `Select.Popover`) with `ListBox` for items
+
+### 2. Item Components
+
+**v2:** `SelectItem`, `SelectSection`
+**v3:** `ListBox.Item`, `ListBox.Section` (with `Header` for section titles and `Separator` between sections)
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `selectedKeys` | `value` | Changed from Set/array to single value or array |
+| `onSelectionChange` | `onChange` | Renamed event handler |
+| `defaultSelectedKeys` | `defaultValue` | Renamed prop |
+| `label` | — | Use `Label` component |
+| `description` | — | Use `Description` component |
+| `errorMessage` | — | Use `FieldError` component |
+| `variant` | `variant` | Simplified to `primary` \| `secondary` only |
+| `color` | — | Removed (use Tailwind CSS) |
+| `size` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `classNames` | — | Use `className` props on individual components |
+| `startContent` | — | Customize `Select.Trigger` directly |
+| `endContent` | — | Customize `Select.Trigger` directly |
+| `selectorIcon` | — | Customize `Select.Indicator` children |
+| `isClearable` | — | Implement clear button manually |
+| `renderValue` | — | Use `Select.Value` render prop |
+| `labelPlacement` | — | Labels are always outside |
+| `isRequired` | `isRequired` | Still exists |
+| `disabledKeys` | `disabledKeys` | Still exists |
+| `isOpen` | `isOpen` | New: controls the open state of the popover (controlled) |
+| `defaultOpen` | `defaultOpen` | New: sets the default open state of the popover (uncontrolled) |
+| `onOpenChange` | `onOpenChange` | New: handler called when the open state changes |
+| `selectionMode` | `selectionMode` | Still exists |
+| `disableAnimation` | — | Removed (animations handled differently) |
+| `popoverProps`, `listboxProps`, `scrollShadowProps` | — | Use props on `Select.Popover`, `ListBox`, etc. directly |
+
+## Migration Examples
+
+### Selection
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    {/* Single selection */}
+    const [singleValue, setSingleValue] = useState(new Set([]));
+    <Select
+      selectedKeys={singleValue}
+      onSelectionChange={setSingleValue}
+      label="Select animal"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    
+    {/* Multiple selection */}
+    const [multiValue, setMultiValue] = useState(new Set([]));
+    <Select
+      selectionMode="multiple"
+      selectedKeys={multiValue}
+      onSelectionChange={setMultiValue}
+      label="Select animals"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import type { Key } from "@heroui/react";
+
+    {/* Single selection */}
+    const [singleValue, setSingleValue] = useState<Key | null>(null);
+    <Select value={singleValue} onChange={setSingleValue} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    
+    {/* Multiple selection */}
+    const [multiValue, setMultiValue] = useState<Key[]>([]);
+    <Select
+      selectionMode="multiple"
+      value={multiValue}
+      onChange={setMultiValue}
+      placeholder="Choose multiple"
+    >
+      <Label>Select animals</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### Form Validation
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With description */}
+    <Select
+      label="Select animal"
+      description="Choose your favorite"
+      placeholder="Choose one"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    
+    {/* With validation */}
+    <Select
+      isInvalid
+      errorMessage="Please select an option"
+      label="Select animal"
+    >
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Label, Description, FieldError } from "@heroui/react";
+
+    {/* With description */}
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Description>Choose your favorite</Description>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    
+    {/* With validation */}
+    <Select isInvalid placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+      <FieldError>Please select an option</FieldError>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### With Sections
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem, SelectSection } from "@heroui/react";
+
+    <Select label="Select animal">
+      <SelectSection title="Mammals">
+        <SelectItem key="cat">Cat</SelectItem>
+        <SelectItem key="dog">Dog</SelectItem>
+      </SelectSection>
+      <SelectSection title="Birds">
+        <SelectItem key="eagle">Eagle</SelectItem>
+        <SelectItem key="parrot">Parrot</SelectItem>
+      </SelectSection>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox, Header, Separator } from "@heroui/react";
+
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>Mammals</Header>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Birds</Header>
+            <ListBox.Item id="eagle" textValue="Eagle">
+              Eagle
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="parrot" textValue="Parrot">
+              Parrot
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled Open State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* v2 did not have controlled open state */}
+    <Select label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Select isOpen={isOpen} onOpenChange={setIsOpen} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### Disabled Options
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem } from "@heroui/react";
+
+    <Select label="Select animal" disabledKeys={["dog"]}>
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+      <SelectItem key="parrot">Parrot</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    <Select disabledKeys={["dog"]} placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="parrot" textValue="Parrot">
+            Parrot
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### Required
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Select, SelectItem } from "@heroui/react";
+
+    <Select isRequired label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+      <SelectItem key="dog">Dog</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Select, Label, ListBox } from "@heroui/react";
+
+    <Select isRequired placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Indicator
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Select selectorIcon={<CustomIcon />} label="Select animal">
+      <SelectItem key="cat">Cat</SelectItem>
+    </Select>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Select placeholder="Choose one">
+      <Label>Select animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator>
+          <CustomIcon />
+        </Select.Indicator>
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Select follows this structure:
+
+```
+Select (Root)
+  ├── Label (optional)
+  ├── Select.Trigger
+  │   ├── Select.Value
+  │   └── Select.Indicator
+  ├── Description (optional)
+  ├── Select.Popover
+  │   └── ListBox
+  │       ├── ListBox.Item
+  │       │   ├── Label (optional)
+  │       │   ├── Description (optional)
+  │       │   └── ListBox.ItemIndicator
+  │       ├── ListBox.Section (optional)
+  │       │   ├── Header (section title)
+  │       │   └── ListBox.Item
+  │       └── Separator (optional, between sections)
+  └── FieldError (optional)
+```
+
+## Important Notes
+
+### Item Identification
+
+- **v2:** React's `key` was used for both list reconciliation and item identity for selection.
+- **v3:** Use `id` for state/focus and `textValue` for accessibility on `ListBox.Item`; keep React's `key` for list reconciliation.
+
+### Selection Value Types
+
+- **v2:** `selectedKeys` was a `Set<Key>` or array
+- **v3:** `value` is `Key | null` for single selection or `Key[]` for multiple selection
+
+### Clear Button
+
+The `isClearable` prop has been removed. To implement a clear button:
+
+```tsx
+<Select value={value} onChange={setValue}>
+  <Select.Trigger>
+    <Select.Value />
+    {value && (
+      <button onClick={() => setValue(null)}>Clear</button>
+    )}
+    <Select.Indicator />
+  </Select.Trigger>
+  {/* ... */}
+</Select>
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Select.Trigger`, `Select.Value`, `Select.Indicator`, `Select.Popover`)
+2. **Item Components**: `SelectItem` → `ListBox.Item`, `SelectSection` → `ListBox.Section` (use `Header` for section titles and `Separator` between sections)
+3. **Label/Description/Error**: Use separate components instead of props
+4. **Selection Props**: `selectedKeys`/`onSelectionChange` → `value`/`onChange`
+5. **Controlled Open State**: New `isOpen`, `defaultOpen`, and `onOpenChange` props for controlling the popover open state
+6. **Disabled Options**: `disabledKeys` prop still supported for disabling specific items
+7. **Required**: `isRequired` prop still supported for marking the field as required
+8. **Styling**: `variant` simplified to `primary` \| `secondary`; `color`, `size`, `radius` removed - use Tailwind for more
+9. **ClassNames Removed**: Use `className` props on individual components
+10. **Content Props Removed**: `startContent`, `endContent` - customize trigger directly
+11. **Clear Button**: `isClearable` removed - implement manually
+12. **Custom Value**: Use `Select.Value` render prop instead of `renderValue`
diff --git a/apps/docs/content/docs/en/react/migration/(components)/skeleton.mdx b/apps/docs/content/docs/en/react/migration/(components)/skeleton.mdx
new file mode 100644
index 0000000..a5009a4
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/skeleton.mdx
@@ -0,0 +1,245 @@
+---
+title: Skeleton
+description: Migration guide for Skeleton from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Skeleton documentation](/docs/react/components/skeleton) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Skeleton wrapped children and showed/hid them based on `isLoaded`:
+
+```tsx
+import { Skeleton } from "@heroui/react";
+
+export default function App() {
+  const isLoaded = false;
+  
+  return (
+    <Skeleton isLoaded={isLoaded}>
+      <div className="h-24 bg-secondary" />
+    </Skeleton>
+  );
+}
+```
+
+In v3, Skeleton is a standalone placeholder that you control visibility of manually:
+
+```tsx
+import { Skeleton } from "@heroui/react";
+
+export default function App() {
+  const isLoaded = false;
+  
+  return (
+    <>
+      {!isLoaded ? (
+        <Skeleton className="h-24 rounded-lg" />
+      ) : (
+        <div className="h-24 bg-secondary" />
+      )}
+    </>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Behavior
+
+**v2:** Wrapped children and showed/hid them based on `isLoaded`  
+**v3:** Standalone placeholder - you control visibility manually
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `isLoaded` | — | Control visibility manually with conditional rendering |
+| `disableAnimation` | `animationType` | Use `animationType="shimmer" \| "pulse" \| "none"` (use `"none"` to disable) |
+| `classNames` | — | Use `className` prop directly |
+| `children` | — | Skeleton no longer wraps content |
+
+### 3. New Props
+
+- `animationType` - Controls animation type: `"shimmer"` (default), `"pulse"`, or `"none"`
+
+## Migration Examples
+
+### With Loaded State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Skeleton className="rounded-lg" isLoaded={isLoaded}>
+      <div className="h-24 rounded-lg bg-secondary" />
+    </Skeleton>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    {!isLoaded ? (
+      <Skeleton className="h-24 rounded-lg" />
+    ) : (
+      <div className="h-24 rounded-lg bg-secondary" />
+    )}
+    ```
+  </Tab>
+</Tabs>
+
+### Standalone Skeleton
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div className="flex items-center gap-3">
+      <Skeleton className="flex rounded-full w-12 h-12" />
+      <div className="w-full flex flex-col gap-2">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+      </div>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div className="flex items-center gap-3">
+      <Skeleton className="h-12 w-12 shrink-0 rounded-lg" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-3 w-full rounded" />
+        <Skeleton className="h-3 w-4/5 rounded" />
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Animation Types
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Shimmer (default) */}
+    <Skeleton>
+      <div className="h-24 bg-default-300" />
+    </Skeleton>
+
+    {/* No animation */}
+    <Skeleton disableAnimation>
+      <div className="h-24 bg-default-300" />
+    </Skeleton>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Shimmer (default) */}
+    <Skeleton animationType="shimmer" className="h-24 rounded-lg" />
+
+    {/* Pulse */}
+    <Skeleton animationType="pulse" className="h-24 rounded-lg" />
+
+    {/* No animation */}
+    <Skeleton animationType="none" className="h-24 rounded-lg" />
+    ```
+  </Tab>
+</Tabs>
+
+### Complex Example: Card with Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Card className="w-[200px] space-y-5 p-4" radius="lg">
+      <Skeleton className="rounded-lg" isLoaded={isLoaded}>
+        <div className="h-24 rounded-lg bg-secondary" />
+      </Skeleton>
+      <div className="space-y-3">
+        <Skeleton className="w-3/5 rounded-lg" isLoaded={isLoaded}>
+          <div className="h-3 w-full rounded-lg bg-secondary" />
+        </Skeleton>
+        <Skeleton className="w-4/5 rounded-lg" isLoaded={isLoaded}>
+          <div className="h-3 w-full rounded-lg bg-secondary-300" />
+        </Skeleton>
+      </div>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    <Card className="w-[250px] space-y-5 rounded-lg p-4">
+      {!isLoaded ? (
+        <>
+          <Skeleton className="h-32 rounded-lg" />
+          <div className="space-y-3">
+            <Skeleton className="h-3 w-3/5 rounded-lg" />
+            <Skeleton className="h-3 w-4/5 rounded-lg" />
+          </div>
+        </>
+      ) : (
+        <>
+          <div className="h-32 rounded-lg bg-secondary" />
+          <div className="space-y-3">
+            <div className="h-3 w-3/5 rounded-lg bg-secondary" />
+            <div className="h-3 w-4/5 rounded-lg bg-secondary-300" />
+          </div>
+        </>
+      )}
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Synchronized Shimmer Effect
+
+In v3, you can create a synchronized shimmer that passes over all skeleton elements at once. Apply the `skeleton--shimmer` class to a parent container and set `animationType="none"` on each child Skeleton:
+
+```tsx
+{/* The parent container drives a single shimmer across all children */}
+<div className="skeleton--shimmer space-y-4 rounded-lg p-4">
+  <Skeleton animationType="none" className="h-32 rounded-lg" />
+  <div className="space-y-3">
+    <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" />
+    <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" />
+  </div>
+</div>
+```
+
+This is useful for card-like layouts where you want a single, unified shimmer sweep instead of each skeleton animating independently.
+
+## Global Animation Configuration
+
+In v3, you can set a default animation type globally using CSS variables:
+
+```css
+:root {
+  --skeleton-animation: pulse; /* shimmer, pulse, or none */
+}
+```
+
+This can be overridden by the `animationType` prop on individual components.
+
+## Summary
+
+1. **No Children Wrapping**: Skeleton no longer wraps children - it's a standalone placeholder
+2. **No `isLoaded` Prop**: Control visibility manually with conditional rendering
+3. **Animation Control**: `disableAnimation` → `animationType` (`"shimmer"`, `"pulse"`, `"none"`)
+4. **Styling**: `classNames` → `className` prop directly
+5. **Simplified API**: Much simpler component focused on being a placeholder
+6. **Synchronized Shimmer**: Use `skeleton--shimmer` class on a parent container with `animationType="none"` on children for a unified shimmer sweep
diff --git a/apps/docs/content/docs/en/react/migration/(components)/slider.mdx b/apps/docs/content/docs/en/react/migration/(components)/slider.mdx
new file mode 100644
index 0000000..b911144
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/slider.mdx
@@ -0,0 +1,253 @@
+---
+title: Slider
+description: Migration guide for Slider from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Slider documentation](/docs/react/components/slider) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Slider used a simple structure with props:
+
+```tsx
+import { Slider } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Slider
+      label="Volume"
+      defaultValue={30}
+      size="md"
+      color="primary"
+    />
+  );
+}
+```
+
+In v3, Slider requires compound components:
+
+```tsx
+import { Slider, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Slider defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple Slider with props  
+**v3:** Compound components: `Slider.Output`, `Slider.Track`, `Slider.Fill`, `Slider.Thumb`
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `label` | — | Use `Label` component |
+| `size` | — | Removed (use Tailwind CSS) |
+| `color` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `classNames` | — | Use `className` props on individual components |
+| `showSteps` | — | Not yet supported |
+| `showTooltip` | — | Not yet supported |
+| `marks` | — | Not yet supported (see `Slider.Marks`) |
+| `startContent` | — | Customize track wrapper directly |
+| `endContent` | — | Customize track wrapper directly |
+| `hideValue` | — | Omit `Slider.Output` |
+| `hideThumb` | — | Omit `Slider.Thumb` |
+| `showOutline` | — | Use Tailwind CSS |
+| `renderThumb` | — | Use `Slider.Thumb` render prop |
+| `renderLabel` | — | Use `Label` component |
+| `renderValue` | — | Use `Slider.Output` render prop |
+| `getValue` | — | Use `Slider.Output` render prop |
+| `getTooltipValue` | — | Use `Slider.Output` render prop |
+| `fillOffset` | — | Not yet supported |
+| `disableThumbScale` | — | Use Tailwind CSS |
+| `disableAnimation` | — | Removed |
+| `onChangeEnd` | `Slider` | Still supported — handler called when the user finishes dragging a thumb |
+
+## Migration Examples
+
+### Controlled Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState(25);
+
+    <Slider
+      value={value}
+      onChange={setValue}
+      label="Volume"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [value, setValue] = useState(25);
+
+    <Slider value={value} onChange={setValue}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### Range Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      defaultValue={[100, 500]}
+      formatOptions={{style: "currency", currency: "USD"}}
+      label="Price Range"
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider
+      defaultValue={[100, 500]}
+      formatOptions={{style: "currency", currency: "USD"}}
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    >
+      <Label>Price Range</Label>
+      <Slider.Output />
+      <Slider.Track>
+        {({state}) => (
+          <>
+            <Slider.Fill />
+            {state.values.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### Vertical Slider
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      defaultValue={30}
+      orientation="vertical"
+      label="Volume"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider defaultValue={30} orientation="vertical">
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Value Display
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Slider
+      renderValue={(props) => (
+        <output {...props}>Custom: {value}</output>
+      )}
+      label="Volume"
+      defaultValue={30}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Slider defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output>
+        {({state}) => `Custom: ${state.values[0]}`}
+      </Slider.Output>
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Slider follows this structure:
+
+```
+Slider (Root)
+  ├── Label (optional)
+  ├── Slider.Output (optional)
+  └── Slider.Track
+      ├── Slider.Fill
+      └── Slider.Thumb (or multiple for range)
+```
+
+For range sliders, use a render prop in `Slider.Track`:
+
+```tsx
+<Slider.Track>
+  {({state}) => (
+    <>
+      <Slider.Fill />
+      {state.values.map((_, i) => (
+        <Slider.Thumb key={i} index={i} />
+      ))}
+    </>
+  )}
+</Slider.Track>
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Slider.Output`, `Slider.Track`, `Slider.Fill`, `Slider.Thumb`)
+2. **Label Handling**: `label` prop removed - use `Label` component
+3. **Styling Props Removed**: `size`, `color`, `radius` - use Tailwind CSS
+4. **ClassNames Removed**: Use `className` props on individual components
+5. **Feature Props Removed**: `showSteps`, `showTooltip`, `marks`, `startContent`, `endContent` - not yet supported or customize manually
+6. **Render Props Removed**: `renderThumb`, `renderLabel`, `renderValue` - use render props on components
+7. **Visibility Props Removed**: `hideValue`, `hideThumb` - omit components instead
+8. **Range Sliders**: Must map over thumbs in `Slider.Track` render prop
+9. **onChangeEnd**: Still supported on `Slider` — fires when the user finishes dragging a thumb
diff --git a/apps/docs/content/docs/en/react/migration/(components)/snippet.mdx b/apps/docs/content/docs/en/react/migration/(components)/snippet.mdx
new file mode 100644
index 0000000..6aa0af7
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/snippet.mdx
@@ -0,0 +1,423 @@
+---
+title: Snippet
+description: Migration guide for Snippet from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The Snippet component has been **removed** in HeroUI v3. Use native HTML elements with Tailwind CSS classes and implement copy functionality manually using the Clipboard API.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<Snippet>` component from `@heroui/react`  
+**v3:** Native HTML elements (`<pre>`, `<code>`) with manual copy implementation
+
+### 2. Features Mapping
+
+The v2 Snippet component had the following features that need to be replaced:
+
+| v2 Feature | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| Copy button | Manual Button + Clipboard API | Use `navigator.clipboard.writeText()` |
+| Copy tooltip | Tooltip component | Use v3 Tooltip component |
+| Symbol prefix | Manual rendering | Add symbol as text content |
+| Multi-line support | Array mapping | Map over array of strings |
+| Variants (`flat`, `solid`, `bordered`, `shadow`) | Tailwind classes | Use background/border utilities |
+| Colors (`default`, `primary`, etc.) | Tailwind classes | Use color utilities |
+| Sizes (`sm`, `md`, `lg`) | Tailwind text sizes | Use `text-sm`, `text-base`, `text-lg` |
+| Radius | Tailwind border radius | Use `rounded-*` classes |
+
+## Structure Changes
+
+In v2, `Snippet` was a component wrapper with built-in copy functionality:
+
+```tsx
+import { Snippet } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Snippet symbol="$">
+      npm install @heroui/react
+    </Snippet>
+  );
+}
+```
+
+In v3, use native HTML elements with manual copy implementation:
+
+```tsx
+import { Button, Tooltip } from "@heroui/react";
+import { useState } from "react";
+
+export default function App() {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText("npm install @heroui/react");
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div className="flex items-center gap-2 rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        <span className="text-default-500">$ </span>
+        npm install @heroui/react
+      </pre>
+      <Tooltip>
+        <Button
+          isIconOnly
+          aria-label="Copy"
+          size="sm"
+          variant="ghost"
+          onPress={handleCopy}
+        >
+          {copied ? "✓" : "📋"}
+        </Button>
+        <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
+```
+
+## Migration Examples
+
+### Multi-line Snippet
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Snippet symbol="$">
+      {[
+        "npm install @heroui/react",
+        "yarn add @heroui/react",
+        "pnpm add @heroui/react"
+      ]}
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, Tooltip } from "@heroui/react";
+    import { useState } from "react";
+
+    function MultiLineSnippet() {
+      const [copied, setCopied] = useState(false);
+      const lines = [
+        "npm install @heroui/react",
+        "yarn add @heroui/react",
+        "pnpm add @heroui/react"
+      ];
+      const codeString = lines.join("\n");
+
+      const handleCopy = async () => {
+        await navigator.clipboard.writeText(codeString);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      };
+
+      return (
+        <div className="flex items-start gap-2 rounded-lg bg-default-100 p-3">
+          <div className="flex-1 space-y-1">
+            {lines.map((line, index) => (
+              <pre key={index} className="text-sm font-mono">
+                <span className="text-default-500">$ </span>
+                {line}
+              </pre>
+            ))}
+          </div>
+          <Tooltip>
+            <Button
+              isIconOnly
+              aria-label="Copy"
+              size="sm"
+              variant="ghost"
+              onPress={handleCopy}
+            >
+              {copied ? "✓" : "📋"}
+            </Button>
+            <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+          </Tooltip>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Styling Options
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With variants */}
+    <Snippet variant="bordered" color="primary">
+      npm install @heroui/react
+    </Snippet>
+    
+    {/* Without symbol */}
+    <Snippet hideSymbol>
+      npm install @heroui/react
+    </Snippet>
+    
+    {/* Without copy button */}
+    <Snippet hideCopyButton>
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With variants */}
+    <div className="flex items-center gap-2 rounded-lg border border-accent bg-transparent px-3 py-1.5">
+      <pre className="text-sm font-mono text-accent">
+        <span className="text-accent/60">$ </span>
+        npm install @heroui/react
+      </pre>
+      {/* Copy button */}
+    </div>
+    
+    {/* Without symbol */}
+    <div className="flex items-center gap-2 rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        npm install @heroui/react
+      </pre>
+      {/* Copy button */}
+    </div>
+    
+    {/* Without copy button */}
+    <div className="rounded-lg bg-default-100 px-3 py-1.5">
+      <pre className="text-sm font-mono">
+        <span className="text-default-500">$ </span>
+        npm install @heroui/react
+      </pre>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a Reusable Snippet Component (Recommended)
+
+Since Snippet functionality is commonly needed, here's a complete reusable component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Snippet } from "@heroui/react";
+
+    <Snippet
+      symbol="$"
+      variant="bordered"
+      color="primary"
+      size="md"
+    >
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button, Tooltip } from "@heroui/react";
+    import { useState, ReactNode } from "react";
+    import { cn } from "@/lib/utils"; // or your cn utility
+
+    interface SnippetProps {
+      children: string | string[];
+      symbol?: string | ReactNode;
+      variant?: "flat" | "solid" | "bordered" | "shadow";
+      color?: "default" | "primary" | "secondary" | "success" | "warning" | "danger";
+      size?: "sm" | "md" | "lg";
+      radius?: "none" | "sm" | "md" | "lg" | "full";
+      hideSymbol?: boolean;
+      hideCopyButton?: boolean;
+      disableCopy?: boolean;
+      disableTooltip?: boolean;
+      className?: string;
+      codeString?: string;
+      onCopy?: (value: string) => void;
+    }
+
+    const variantClasses = {
+      flat: "bg-default-100",
+      solid: "bg-default-200",
+      bordered: "border border-default-200 bg-transparent",
+      shadow: "bg-default-100 shadow-sm",
+    };
+
+    const colorClasses = {
+      default: "text-default-foreground",
+      primary: "text-accent",
+      secondary: "text-default-600",
+      success: "text-success",
+      warning: "text-warning",
+      danger: "text-danger",
+    };
+
+    const sizeClasses = {
+      sm: "px-1.5 py-0.5 text-xs",
+      md: "px-3 py-1.5 text-sm",
+      lg: "px-4 py-2 text-base",
+    };
+
+    const radiusClasses = {
+      none: "rounded-none",
+      sm: "rounded-sm",
+      md: "rounded-md",
+      lg: "rounded-lg",
+      full: "rounded-full",
+    };
+
+    export function Snippet({
+      children,
+      symbol = "$",
+      variant = "flat",
+      color = "default",
+      size = "md",
+      radius = "md",
+      hideSymbol = false,
+      hideCopyButton = false,
+      disableCopy = false,
+      disableTooltip = false,
+      className,
+      codeString,
+      onCopy,
+    }: SnippetProps) {
+      const [copied, setCopied] = useState(false);
+      const isMultiLine = Array.isArray(children);
+      const lines = isMultiLine ? children : [children];
+      const textToCopy = codeString || (isMultiLine ? lines.join("\n") : String(children));
+
+      const handleCopy = async () => {
+        if (disableCopy) return;
+
+        try {
+          await navigator.clipboard.writeText(textToCopy);
+          setCopied(true);
+          setTimeout(() => setCopied(false), 2000);
+          onCopy?.(textToCopy);
+        } catch (error) {
+          console.error("Failed to copy:", error);
+        }
+      };
+
+      const symbolElement = hideSymbol ? null : (
+        <span className={cn("text-default-500", colorClasses[color], "opacity-60")}>
+          {symbol}{typeof symbol === "string" ? " " : ""}
+        </span>
+      );
+
+      const copyButton = hideCopyButton ? null : (
+        <Tooltip isDisabled={disableTooltip || disableCopy}>
+          <Button
+            isIconOnly
+            aria-label="Copy"
+            size="sm"
+            variant="ghost"
+            onPress={handleCopy}
+            isDisabled={disableCopy}
+            className="shrink-0"
+          >
+            {copied ? (
+              <span className="text-success">✓</span>
+            ) : (
+              <span>📋</span>
+            )}
+          </Button>
+          <Tooltip.Content>{copied ? "Copied!" : "Copy to clipboard"}</Tooltip.Content>
+        </Tooltip>
+      );
+
+      return (
+        <div
+          className={cn(
+            "flex items-start gap-2 font-mono",
+            variantClasses[variant],
+            sizeClasses[size],
+            radiusClasses[radius],
+            className
+          )}
+        >
+          <div className="flex-1 min-w-0">
+            {isMultiLine ? (
+              <div className="space-y-1">
+                {lines.map((line, index) => (
+                  <pre key={index} className={cn("m-0", colorClasses[color])}>
+                    {symbolElement}
+                    {line}
+                  </pre>
+                ))}
+              </div>
+            ) : (
+              <pre className={cn("m-0", colorClasses[color])}>
+                {symbolElement}
+                {children}
+              </pre>
+            )}
+          </div>
+          {copyButton}
+        </div>
+      );
+    }
+
+    // Usage
+    <Snippet
+      symbol="$"
+      variant="bordered"
+      color="primary"
+      size="md"
+    >
+      npm install @heroui/react
+    </Snippet>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+1. **Component Removed**: `Snippet` component no longer exists in v3
+2. **Import Change**: Remove `import { Snippet } from "@heroui/react"`
+3. **Use Native Elements**: Replace with native `<pre>` and `<code>` elements
+4. **Manual Copy**: Implement copy functionality using Clipboard API
+5. **Styling**: Apply Tailwind CSS classes directly for variants, colors, sizes
+6. **Tooltip**: Use v3 Tooltip component for copy button tooltips
+7. **Button**: Use v3 Button component for copy button
+
+## Migration Steps
+
+1. **Remove Import**: Remove `Snippet` from `@heroui/react` imports
+2. **Replace Component**: Replace all `<Snippet>` instances with native HTML elements
+3. **Add Copy Functionality**: Implement copy using `navigator.clipboard.writeText()`
+4. **Add Copy Button**: Use v3 Button component with Tooltip
+5. **Apply Styling**: Use Tailwind CSS classes for variants, colors, sizes
+6. **Handle Multi-line**: Map over arrays if multi-line snippets are needed
+7. **Optional**: Create reusable Snippet component for your application
+
+## Clipboard API Notes
+
+The Clipboard API requires:
+- HTTPS (or localhost for development)
+- User interaction (can't be called automatically)
+- Browser support (modern browsers)
+
+For fallback support:
+
+```tsx
+const handleCopy = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch (error) {
+    // Fallback for older browsers
+    const textArea = document.createElement("textarea");
+    textArea.value = text;
+    textArea.style.position = "fixed";
+    textArea.style.opacity = "0";
+    document.body.appendChild(textArea);
+    textArea.select();
+    document.execCommand("copy");
+    document.body.removeChild(textArea);
+  }
+};
+```
diff --git a/apps/docs/content/docs/en/react/migration/(components)/spacer.mdx b/apps/docs/content/docs/en/react/migration/(components)/spacer.mdx
new file mode 100644
index 0000000..0833385
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/spacer.mdx
@@ -0,0 +1,284 @@
+---
+title: Spacer
+description: Migration guide for Spacer from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The Spacer component has been **removed** in HeroUI v3. Use Tailwind CSS margin utilities directly instead.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<Spacer>` component from `@heroui/react`  
+**v3:** Tailwind CSS margin utilities (`ml-*`, `mr-*`, `mt-*`, `mb-*`, `mx-*`, `my-*`)
+
+### 2. Props Mapping
+
+The v2 Spacer component had the following props that map to Tailwind utilities:
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `x={n}` | `ml-{n}` or `mx-{n}` | Horizontal margin (left or both sides) |
+| `y={n}` | `mt-{n}` or `my-{n}` | Vertical margin (top or both sides) |
+| `isInline` | `inline-block` or `block` | Display type |
+
+### 3. Spacing Scale
+
+The spacing values in v2 match Tailwind's spacing scale:
+- `x={1}` → `ml-1` (0.25rem / 4px)
+- `x={2}` → `ml-2` (0.5rem / 8px)
+- `x={4}` → `ml-4` (1rem / 16px)
+- `y={4}` → `mt-4` (1rem / 16px)
+- etc.
+
+## Migration Examples
+
+### Basic Spacing
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer } from "@heroui/react";
+
+    {/* Vertical spacing */}
+    <div>
+      <div>Item 1</div>
+      <Spacer y={4} />
+      <div>Item 2</div>
+    </div>
+    
+    {/* Horizontal spacing */}
+    <div className="flex">
+      <div>Item 1</div>
+      <Spacer x={4} isInline />
+      <div>Item 2</div>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Vertical spacing */}
+    <div>
+      <div>Item 1</div>
+      <div className="mt-4">Item 2</div>
+    </div>
+    
+    {/* Horizontal spacing */}
+    <div className="flex">
+      <div>Item 1</div>
+      <div className="ml-4">Item 2</div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Using Gap (Recommended)
+
+For flex and grid layouts, using `gap` is often better than Spacer:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer } from "@heroui/react";
+
+    {/* Horizontal layout */}
+    <div className="flex">
+      <div>Item 1</div>
+      <Spacer x={4} isInline />
+      <div>Item 2</div>
+    </div>
+    
+    {/* Vertical layout */}
+    <div className="flex flex-col">
+      <Button>Button 1</Button>
+      <Spacer y={2} />
+      <Button>Button 2</Button>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Horizontal layout */}
+    <div className="flex gap-4">
+      <div>Item 1</div>
+      <div>Item 2</div>
+    </div>
+    
+    {/* Vertical layout */}
+    <div className="flex flex-col gap-2">
+      <Button>Button 1</Button>
+      <Button>Button 2</Button>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+## Complete Example
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Spacer, Button } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div>
+          <h1>Title</h1>
+          <Spacer y={4} />
+          <p>Description text</p>
+          <Spacer y={8} />
+          <div className="flex">
+            <Button>Cancel</Button>
+            <Spacer x={4} isInline />
+            <Button>Submit</Button>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Button } from "@heroui/react";
+
+    export default function App() {
+      return (
+        <div>
+          <h1>Title</h1>
+          <p className="mt-4">Description text</p>
+          <div className="mt-8 flex gap-4">
+            <Button>Cancel</Button>
+            <Button>Submit</Button>
+          </div>
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Spacing Scale Reference
+
+Tailwind CSS spacing scale (matches v2 Spacer values):
+
+| Value | Size | Tailwind Class |
+|-------|------|----------------|
+| `0` | 0px | `m-0`, `ml-0`, `mt-0`, etc. |
+| `px` | 1px | `m-px`, `ml-px`, `mt-px`, etc. |
+| `0.5` | 0.125rem (2px) | `m-0.5`, `ml-0.5`, `mt-0.5`, etc. |
+| `1` | 0.25rem (4px) | `m-1`, `ml-1`, `mt-1`, etc. |
+| `2` | 0.5rem (8px) | `m-2`, `ml-2`, `mt-2`, etc. |
+| `3` | 0.75rem (12px) | `m-3`, `ml-3`, `mt-3`, etc. |
+| `4` | 1rem (16px) | `m-4`, `ml-4`, `mt-4`, etc. |
+| `5` | 1.25rem (20px) | `m-5`, `ml-5`, `mt-5`, etc. |
+| `6` | 1.5rem (24px) | `m-6`, `ml-6`, `mt-6`, etc. |
+| `8` | 2rem (32px) | `m-8`, `ml-8`, `mt-8`, etc. |
+| `10` | 2.5rem (40px) | `m-10`, `ml-10`, `mt-10`, etc. |
+| `12` | 3rem (48px) | `m-12`, `ml-12`, `mt-12`, etc. |
+| `16` | 4rem (64px) | `m-16`, `ml-16`, `mt-16`, etc. |
+| `20` | 5rem (80px) | `m-20`, `ml-20`, `mt-20`, etc. |
+
+## Best Practices
+
+### 1. Use Gap for Flex/Grid Layouts
+
+Instead of Spacer components, use `gap` utilities:
+
+```tsx
+// ✅ Recommended
+<div className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</div>
+
+// ❌ Not recommended
+<div className="flex">
+  <Button>Button 1</Button>
+  <div className="ml-4"><Button>Button 2</Button></div>
+</div>
+```
+
+### 2. Use Space Utilities for Vertical Lists
+
+```tsx
+// ✅ Recommended
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+
+// Alternative
+<div>
+  <div>Item 1</div>
+  <div className="mt-4">Item 2</div>
+  <div className="mt-4">Item 3</div>
+</div>
+```
+
+### 3. Use Margin Utilities Directly
+
+Apply margin directly to elements instead of using Spacer:
+
+```tsx
+// ✅ Recommended
+<div className="mt-4">Content</div>
+
+// ❌ Not recommended
+<>
+  <Spacer y={4} />
+  <div>Content</div>
+</>
+```
+
+## Summary
+
+1. **Component Removed**: `Spacer` component no longer exists in v3
+2. **Import Change**: Remove `import { Spacer } from "@heroui/react"`
+3. **Use Tailwind Utilities**: Replace with margin utilities (`ml-*`, `mt-*`, `mx-*`, `my-*`)
+4. **Use Gap**: Prefer `gap-*` utilities for flex/grid layouts
+5. **Use Space**: Prefer `space-y-*` and `space-x-*` for consistent spacing
+
+## Migration Steps
+
+1. **Remove Import**: Remove `Spacer` from `@heroui/react` imports
+2. **Replace Spacer**: Replace `<Spacer x={n} />` with `ml-{n}` or `mx-{n}` classes
+3. **Replace Spacer**: Replace `<Spacer y={n} />` with `mt-{n}` or `my-{n}` classes
+4. **Use Gap**: For flex/grid layouts, use `gap-{n}` instead of Spacer
+5. **Use Space**: For vertical/horizontal lists, use `space-y-{n}` or `space-x-{n}`
+
+## Common Patterns
+
+### Vertical Stack with Spacing
+
+```tsx
+// Using space-y utility
+<div className="space-y-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### Horizontal Row with Spacing
+
+```tsx
+// Using gap utility
+<div className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+  <Button>Button 3</Button>
+</div>
+```
+
+### Custom Spacing Between Specific Elements
+
+```tsx
+<div>
+  <div>Item 1</div>
+  <div className="mt-8">Item 2 (with custom spacing)</div>
+  <div className="mt-4">Item 3</div>
+</div>
+```
diff --git a/apps/docs/content/docs/en/react/migration/(components)/spinner.mdx b/apps/docs/content/docs/en/react/migration/(components)/spinner.mdx
new file mode 100644
index 0000000..9760cab
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/spinner.mdx
@@ -0,0 +1,184 @@
+---
+title: Spinner
+description: Migration guide for Spinner from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Spinner documentation](/docs/react/components/spinner) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Spinner supported multiple variants and labels:
+
+```tsx
+import { Spinner } from "@heroui/react";
+
+export default function App() {
+  return <Spinner variant="default" label="Loading..." color="primary" />;
+}
+```
+
+In v3, Spinner is simplified to a single circular variant:
+
+```tsx
+import { Spinner } from "@heroui/react";
+
+export default function App() {
+  return <Spinner color="accent" />;
+}
+```
+
+## Key Changes
+
+### 1. Component Behavior
+
+**v2:** Supported multiple variants (`default`, `simple`, `gradient`, `wave`, `dots`, `spinner`) and labels  
+**v3:** Single circular spinner variant, no label support
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `label` | — | Add label manually with separate element if needed |
+| `variant` | — | Only one spinner variant available |
+| `labelColor` | — | No label support |
+| `classNames` | — | Use `className` prop directly |
+| `size` | `size` | Changed: `"sm" \| "md" \| "lg"` → `"sm" \| "md" \| "lg" \| "xl"` |
+| `color` | `color` | Changed values (see below) |
+
+### 3. Changed Color Values
+
+- `"default"` → `"current"` (inherits current text color)
+- `"primary"` → `"accent"`
+- `"secondary"` → Removed (use `"current"` or `"accent"`)
+- `"success"`, `"warning"`, `"danger"` → Still available
+
+## Migration Examples
+
+### With Label
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Simple label */}
+    <Spinner label="Loading..." />
+    
+    {/* With label color and custom styling */}
+    <Spinner
+      label="Loading..."
+      labelColor="primary"
+      classNames={{
+        label: "text-foreground mt-4"
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Simple label */}
+    <div className="flex flex-col items-center gap-2">
+      <Spinner />
+      <span>Loading...</span>
+    </div>
+    
+    {/* With custom styling */}
+    <div className="flex flex-col items-center gap-2">
+      <Spinner />
+      <span className="text-foreground mt-4">Loading...</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Sizes and Colors
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+    </div>
+    
+    {/* Colors */}
+    <div className="flex gap-4">
+      <Spinner color="default" />
+      <Spinner color="primary" />
+      <Spinner color="secondary" />
+      <Spinner color="success" />
+      <Spinner color="warning" />
+      <Spinner color="danger" />
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+      <Spinner size="xl" />
+    </div>
+    
+    {/* Colors */}
+    <div className="flex gap-4">
+      <Spinner color="current" />
+      <Spinner color="accent" />
+      <Spinner color="success" />
+      <Spinner color="warning" />
+      <Spinner color="danger" />
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Variants (Removed)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div className="flex gap-4">
+      <Spinner variant="default" />
+      <Spinner variant="simple" />
+      <Spinner variant="gradient" />
+      <Spinner variant="wave" />
+      <Spinner variant="dots" />
+      <Spinner variant="spinner" />
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Only one variant available - circular spinner */}
+    <Spinner />
+    
+    {/* For other spinner styles, consider using CSS animations */}
+    ```
+  </Tab>
+</Tabs>
+
+## Color Mapping
+
+When migrating colors, use this mapping:
+
+| v2 Color | v3 Color | Notes |
+|----------|----------|-------|
+| `"default"` | `"current"` | Inherits current text color |
+| `"primary"` | `"accent"` | Use accent color |
+| `"secondary"` | `"current"` or `"accent"` | Use current or accent |
+| `"success"` | `"success"` | No change |
+| `"warning"` | `"warning"` | No change |
+| `"danger"` | `"danger"` | No change |
+
+## Summary
+
+1. **No Label Support**: `label` prop removed - add label manually if needed
+2. **No Variants**: `variant` prop removed - only one circular spinner available
+3. **No Label Color**: `labelColor` prop removed - style label manually
+4. **Color Values Changed**: `"default"` → `"current"`, `"primary"` → `"accent"`, `"secondary"` removed
+5. **Size Added**: New `"xl"` size option available
+6. **ClassNames Removed**: Use `className` prop directly
diff --git a/apps/docs/content/docs/en/react/migration/(components)/switch.mdx b/apps/docs/content/docs/en/react/migration/(components)/switch.mdx
new file mode 100644
index 0000000..5be26d5
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/switch.mdx
@@ -0,0 +1,379 @@
+---
+title: Switch
+description: Migration guide for Switch from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Switch documentation](/docs/react/components/switch) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Switch used a simple structure with children as label:
+
+```tsx
+import { Switch } from "@heroui/react";
+
+export default function App() {
+  return <Switch>Enable notifications</Switch>;
+}
+```
+
+In v3, Switch requires compound components:
+
+```tsx
+import { Switch, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple Switch with children as label
+**v3:** Compound components (`Switch.Content`, `Switch.Control`, `Switch.Thumb`) with `Label` component
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `onValueChange` | `onChange` | Renamed event handler |
+| `size` | `size` | Still exists on root (`sm` \| `md` \| `lg`) |
+| `label` | — | Use `Label` component |
+| `color` | — | Removed (use Tailwind CSS) |
+| `thumbIcon` | — | Use `Switch.Icon` inside `Switch.Thumb` |
+| `startContent` | — | Customize control directly |
+| `endContent` | — | Customize control directly |
+| `classNames` | — | Use `className` props on individual components |
+| `disableAnimation` | — | Removed (animations handled differently) |
+
+### 3. New Components
+
+- `SwitchGroup` - For grouping multiple switches
+- `Switch.Content` - The clickable label wrapping the control and `Label`
+- `Switch.Icon` - For icons inside the thumb
+
+## Migration Examples
+
+### Controlled Switch
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(true);
+
+    <Switch isSelected={isSelected} onValueChange={setIsSelected}>
+      Airplane mode
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isSelected, setIsSelected] = useState(true);
+
+    <Switch isSelected={isSelected} onChange={setIsSelected}>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Airplane mode
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### Without Label
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch defaultSelected aria-label="Automatic updates" />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch defaultSelected aria-label="Automatic updates">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### With Thumb Icon
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch thumbIcon={<CheckIcon />}>Enable notifications</Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb>
+            <Switch.Icon>
+              <CheckIcon />
+            </Switch.Icon>
+          </Switch.Thumb>
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### With Start/End Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch
+      startContent={<SunIcon />}
+      endContent={<MoonIcon />}
+    >
+      Dark mode
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="flex items-center gap-2">
+          <SunIcon />
+          <Switch.Thumb />
+          <MoonIcon />
+        </Switch.Control>
+        Dark mode
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### With Label and Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Switch description="You will receive notifications for all activity">
+      Enable notifications
+    </Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Switch, Label, Description } from "@heroui/react";
+
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+      <Description>You will receive notifications for all activity</Description>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### Sizes and Colors
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Switch size="sm">Small</Switch>
+      <Switch size="md">Medium</Switch>
+      <Switch size="lg">Large</Switch>
+    </div>
+    
+    {/* Colors */}
+    <Switch color="primary">Primary</Switch>
+    <Switch color="success">Success</Switch>
+    <Switch color="danger">Danger</Switch>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Sizes */}
+    <div className="flex gap-4">
+      <Switch size="sm">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Small
+        </Switch.Content>
+      </Switch>
+      <Switch size="md">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Medium
+        </Switch.Content>
+      </Switch>
+      <Switch size="lg">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Large
+        </Switch.Content>
+      </Switch>
+    </div>
+    
+    {/* Colors - Use Tailwind CSS classes */}
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-accent">
+          <Switch.Thumb />
+        </Switch.Control>
+        Primary
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-success">
+          <Switch.Thumb />
+        </Switch.Control>
+        Success
+      </Switch.Content>
+    </Switch>
+    <Switch>
+      <Switch.Content>
+        <Switch.Control className="data-[selected=true]:bg-danger">
+          <Switch.Thumb />
+        </Switch.Control>
+        Danger
+      </Switch.Content>
+    </Switch>
+    ```
+  </Tab>
+</Tabs>
+
+### Switch Group
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* No built-in group component in v2 */}
+    <div className="flex flex-col gap-2">
+      <Switch name="notifications">Allow Notifications</Switch>
+      <Switch name="marketing">Marketing emails</Switch>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { SwitchGroup } from "@heroui/react";
+
+    <SwitchGroup>
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Allow Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing emails
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Switch follows this structure:
+
+```
+Switch (Root)
+  ├── Switch.Content (the clickable label)
+  │   ├── Switch.Control
+  │   │   └── Switch.Thumb
+  │   │       └── Switch.Icon (optional)
+  │   └── Label
+  ├── Description (optional, sibling)
+  └── FieldError (optional, sibling)
+```
+
+For groups:
+
+```
+SwitchGroup
+  ├── Switch
+  │   ├── Switch.Content
+  │   │   ├── Switch.Control
+  │   │   │   └── Switch.Thumb
+  │   │   └── Label
+  │   └── Description (optional)
+  └── Switch
+      ├── Switch.Content
+      │   ├── Switch.Control
+      │   │   └── Switch.Thumb
+      │   └── Label
+      └── Description (optional)
+```
+
+## Important Notes
+
+### Event Handler
+
+- **v2:** `onValueChange` prop
+- **v3:** `onChange` prop (same signature: `(isSelected: boolean) => void`)
+
+### Label Handling
+
+- **v2:** Children were used as label
+- **v3:** Label goes inside `Switch.Content` (the clickable label); `Description`/`FieldError` are siblings of `Switch.Content`
+
+### Icons
+
+- **v2:** `thumbIcon` prop for icon inside thumb, `startContent`/`endContent` for icons outside
+- **v3:** Use `Switch.Icon` inside `Switch.Thumb` for thumb icon, customize `Switch.Control` for start/end content
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Switch.Content`, `Switch.Control`, `Switch.Thumb`)
+2. **Clickable Label**: Use `Switch.Content` to wrap `Switch.Control` and `Label`; place `Description`/`FieldError` as siblings of `Switch.Content`
+3. **Label Handling**: Children no longer used as label - use `Label` component inside `Switch.Content`
+4. **Event Handler**: `onValueChange` → `onChange`
+5. **Styling Props Removed**: `color` - use Tailwind CSS
+6. **Icon Props Removed**: `thumbIcon`, `startContent`, `endContent` - use components or customize directly
+7. **ClassNames Removed**: Use `className` props on individual components
+8. **New Components**: `SwitchGroup` for grouping switches, `Switch.Content` as the clickable label wrapping the control and `Label`
diff --git a/apps/docs/content/docs/en/react/migration/(components)/table.mdx b/apps/docs/content/docs/en/react/migration/(components)/table.mdx
new file mode 100644
index 0000000..fa4b440
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/table.mdx
@@ -0,0 +1,523 @@
+---
+title: Table
+description: Migration guide for Table from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Table documentation](/docs/react/components/table) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Table used separate named imports for each part:
+
+```tsx
+import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Table aria-label="Example table">
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate Moore</TableCell>
+          <TableCell>CEO</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+In v3, Table uses the compound component pattern with dot notation and adds `Table.ScrollContainer` and `Table.Content`:
+
+```tsx
+import { Table } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Example table">
+          <Table.Header>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Separate named imports (`Table`, `TableHeader`, `TableColumn`, `TableBody`, `TableRow`, `TableCell`)
+**v3:** Single import with dot notation: `Table`, `Table.ScrollContainer`, `Table.Content`, `Table.Header`, `Table.Column`, `Table.Body`, `Table.Row`, `Table.Cell`, `Table.Footer`
+
+### 2. New Wrapper Components
+
+- **`Table`** is now the root container (styling wrapper)
+- **`Table.ScrollContainer`** handles horizontal scrolling with custom scrollbar
+- **`Table.Content`** is the actual `<table>` element (where `aria-label`, `selectionMode`, `sortDescriptor` etc. go)
+- **`Table.Footer`** replaces `bottomContent` for pagination and other footer content
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Equivalent | Notes |
+|---------|---------------|-------|
+| `aria-label` | `Table.Content` `aria-label` | Moved to `Table.Content` |
+| `selectionMode` | `Table.Content` `selectionMode` | Moved to `Table.Content` |
+| `selectedKeys` | `Table.Content` `selectedKeys` | Moved to `Table.Content` |
+| `defaultSelectedKeys` | `Table.Content` `defaultSelectedKeys` | Moved to `Table.Content` |
+| `onSelectionChange` | `Table.Content` `onSelectionChange` | Moved to `Table.Content` |
+| `sortDescriptor` | `Table.Content` `sortDescriptor` | Moved to `Table.Content` |
+| `onSortChange` | `Table.Content` `onSortChange` | Moved to `Table.Content` |
+| `disabledKeys` | `Table.Content` `disabledKeys` | Moved to `Table.Content` |
+| `disallowEmptySelection` | `Table.Content` `disallowEmptySelection` | Moved to `Table.Content` |
+| `selectionBehavior` | `Table.Content` `selectionBehavior` | Moved to `Table.Content` |
+| `disabledBehavior` | `Table.Content` `disabledBehavior` | Moved to `Table.Content` |
+| `onRowAction` | `Table.Content` `onRowAction` | Moved to `Table.Content` |
+| `onCellAction` | `Table.Content` `onCellAction` | Moved to `Table.Content` |
+| `topContent` | - | Place content inside `Table` before `Table.ScrollContainer` |
+| `bottomContent` | - | Use `Table.Footer` |
+| `topContentPlacement` | - | Removed (compose layout directly) |
+| `bottomContentPlacement` | - | Removed (compose layout directly) |
+| `color` | - | Removed (use Tailwind CSS) |
+| `variant` | `Table` `variant` | Changed to `"primary"` (card-style, default) or `"secondary"` (flat) |
+| `layout` | - | Removed |
+| `radius` | - | Removed (use Tailwind CSS) |
+| `shadow` | - | Removed (use Tailwind CSS) |
+| `isStriped` | - | Removed (use Tailwind CSS) |
+| `isCompact` | - | Removed (use Tailwind CSS) |
+| `isHeaderSticky` | - | Removed (use Tailwind CSS `sticky top-0`) |
+| `fullWidth` | - | Removed (full width by default) |
+| `removeWrapper` | - | Removed (compose layout directly) |
+| `hideHeader` | - | Removed (omit `Table.Header` or use CSS) |
+| `isVirtualized` | - | Use React Aria `Virtualizer` wrapper |
+| `maxTableHeight` | - | Use CSS or Virtualizer |
+| `rowHeight` | - | Use `TableLayout` with Virtualizer |
+| `isKeyboardNavigationDisabled` | - | Removed |
+| `disableAnimation` | - | Removed |
+| `classNames` | - | Use `className` on individual compound components |
+
+### 4. Selection with Checkboxes
+
+**v2:** Checkboxes auto-rendered by the table when `selectionMode` is set
+**v3:** Use `Checkbox` with `slot="selection"` explicitly in columns and rows
+
+### 5. Loading and Empty States
+
+**v2:** `loadingState`, `loadingContent`, `emptyContent` props on `TableBody`
+**v3:** `renderEmptyState` prop on `Table.Body`; use `Table.LoadMore` for infinite scroll loading
+
+### 6. Pagination
+
+**v2:** `bottomContent` prop on `Table`
+**v3:** `Table.Footer` compound component
+
+### 7. Column Resizing
+
+**v2:** Not built-in
+**v3:** `Table.ResizableContainer` + `Table.ColumnResizer` compound components
+
+## Migration Examples
+
+### Basic Table
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@heroui/react";
+
+    <Table aria-label="Users">
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+        <TableColumn>Status</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate Moore</TableCell>
+          <TableCell>CEO</TableCell>
+          <TableCell>Active</TableCell>
+        </TableRow>
+        <TableRow key="2">
+          <TableCell>John Doe</TableCell>
+          <TableCell>Developer</TableCell>
+          <TableCell>Active</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Table } from "@heroui/react";
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          <Table.Header>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+            <Table.Column>Status</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row id="1">
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+            </Table.Row>
+            <Table.Row id="2">
+              <Table.Cell>John Doe</Table.Cell>
+              <Table.Cell>Developer</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### Dynamic Rows
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const columns = [
+      { key: "name", label: "Name" },
+      { key: "role", label: "Role" },
+    ];
+    const rows = [
+      { key: "1", name: "Kate", role: "CEO" },
+      { key: "2", name: "John", role: "Developer" },
+    ];
+
+    <Table aria-label="Users">
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const columns = [
+      { id: "name", label: "Name" },
+      { id: "role", label: "Role" },
+    ];
+    const rows = [
+      { id: "1", name: "Kate", role: "CEO" },
+      { id: "2", name: "John", role: "Developer" },
+    ];
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          <Table.Header columns={columns}>
+            {(column) => <Table.Column id={column.id}>{column.label}</Table.Column>}
+          </Table.Header>
+          <Table.Body items={rows}>
+            {(item) => (
+              <Table.Row id={item.id}>
+                <Table.Cell>{item.name}</Table.Cell>
+                <Table.Cell>{item.role}</Table.Cell>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### Selection
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Table
+      aria-label="Users"
+      selectionMode="multiple"
+      selectedKeys={selectedKeys}
+      onSelectionChange={setSelectedKeys}
+    >
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Role</TableColumn>
+      </TableHeader>
+      <TableBody>
+        <TableRow key="1">
+          <TableCell>Kate</TableCell>
+          <TableCell>CEO</TableCell>
+        </TableRow>
+        <TableRow key="2">
+          <TableCell>John</TableCell>
+          <TableCell>Developer</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Table, Checkbox } from "@heroui/react";
+
+    const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Users"
+          selectionMode="multiple"
+          selectedKeys={selectedKeys}
+          onSelectionChange={setSelectedKeys}
+        >
+          <Table.Header>
+            <Table.Column>
+              <Checkbox slot="selection" />
+            </Table.Column>
+            <Table.Column>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row id="1">
+              <Table.Cell>
+                <Checkbox slot="selection" />
+              </Table.Cell>
+              <Table.Cell>Kate</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+            </Table.Row>
+            <Table.Row id="2">
+              <Table.Cell>
+                <Checkbox slot="selection" />
+              </Table.Cell>
+              <Table.Cell>John</Table.Cell>
+              <Table.Cell>Developer</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### Sorting
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const [sortDescriptor, setSortDescriptor] = useState({
+      column: "name",
+      direction: "ascending",
+    });
+
+    <Table
+      aria-label="Users"
+      sortDescriptor={sortDescriptor}
+      onSortChange={setSortDescriptor}
+    >
+      <TableHeader>
+        <TableColumn key="name" allowsSorting>Name</TableColumn>
+        <TableColumn key="role" allowsSorting>Role</TableColumn>
+      </TableHeader>
+      <TableBody items={sortedItems}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    const [sortDescriptor, setSortDescriptor] = useState({
+      column: "name",
+      direction: "ascending",
+    });
+
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Users"
+          sortDescriptor={sortDescriptor}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column id="name" allowsSorting>Name</Table.Column>
+            <Table.Column id="role" allowsSorting>Role</Table.Column>
+          </Table.Header>
+          <Table.Body items={sortedItems}>
+            {(item) => (
+              <Table.Row id={item.id}>
+                <Table.Cell>{item.name}</Table.Cell>
+                <Table.Cell>{item.role}</Table.Cell>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### With Pagination (Bottom Content)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Table
+      aria-label="Users"
+      bottomContent={
+        <Pagination total={10} page={page} onChange={setPage} />
+      }
+      bottomContentPlacement="outside"
+    >
+      {/* ... */}
+    </Table>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Users">
+          {/* Header and Body */}
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        {/* Pagination component */}
+      </Table.Footer>
+    </Table>
+    ```
+  </Tab>
+</Tabs>
+
+### Empty State
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TableBody emptyContent="No rows to display.">
+      {[]}
+    </TableBody>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Table.Body
+      items={[]}
+      renderEmptyState={() => (
+        <p className="text-center py-4">No rows to display.</p>
+      )}
+    >
+      {[]}
+    </Table.Body>
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Changes
+
+### v2: `classNames` Prop
+
+```tsx
+<Table
+  classNames={{
+    base: "custom-base",
+    wrapper: "custom-wrapper",
+    table: "custom-table",
+    thead: "custom-header",
+    tbody: "custom-body",
+    tr: "custom-row",
+    th: "custom-column",
+    td: "custom-cell",
+  }}
+/>
+```
+
+### v3: Direct `className` Props
+
+```tsx
+<Table className="custom-base">
+  <Table.ScrollContainer className="custom-wrapper">
+    <Table.Content aria-label="Table" className="custom-table">
+      <Table.Header className="custom-header">
+        <Table.Column className="custom-column">Name</Table.Column>
+      </Table.Header>
+      <Table.Body className="custom-body">
+        <Table.Row className="custom-row">
+          <Table.Cell className="custom-cell">Value</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+## Component Anatomy
+
+The v3 Table follows this structure:
+
+```
+Table (Root container)
+  ├── Table.ScrollContainer (horizontal scroll)
+  │   └── Table.Content (<table> element, aria-label, selectionMode, etc.)
+  │       ├── Table.Header (<thead>)
+  │       │   └── Table.Column (<th>, allowsSorting, etc.)
+  │       │       └── Table.ColumnResizer (optional)
+  │       └── Table.Body (<tbody>, items, renderEmptyState)
+  │           ├── Table.Row (<tr>)
+  │           │   └── Table.Cell (<td>)
+  │           └── Table.LoadMore (optional, infinite scroll)
+  │               └── Table.LoadMoreContent
+  └── Table.Footer (optional, pagination, etc.)
+```
+
+## Item Identity
+
+**v2:** React's `key` was used for both list reconciliation and selection state.
+**v3:** Use `id` on `Table.Row` and `Table.Column` for selection/sort state; keep React's `key` for lists.
+
+## Summary
+
+1. **Imports**: Separate named imports → single `Table` import with dot notation
+2. **New Wrappers**: `Table.ScrollContainer` and `Table.Content` wrap the table structure
+3. **Props Moved**: `aria-label`, `selectionMode`, `sortDescriptor`, etc. moved from `Table` to `Table.Content`
+4. **Bottom Content**: `bottomContent` prop → `Table.Footer` compound component
+5. **Top Content**: `topContent` prop → place content inside `Table` before `Table.ScrollContainer`
+6. **Selection Checkboxes**: Auto-rendered → explicit `Checkbox` with `slot="selection"`
+7. **Empty State**: `emptyContent` prop → `renderEmptyState` on `Table.Body`
+8. **Loading**: `loadingState`/`loadingContent` → `Table.LoadMore` for infinite scroll
+9. **Column Resizing**: New `Table.ResizableContainer` and `Table.ColumnResizer`
+10. **Item Identity**: `key` → `id` on rows and columns
+11. **Styling Props Removed**: `color`, `radius`, `shadow`, `isStriped`, `isCompact` → use Tailwind CSS
+12. **ClassNames Removed**: Use `className` on individual compound components
diff --git a/apps/docs/content/docs/en/react/migration/(components)/tabs.mdx b/apps/docs/content/docs/en/react/migration/(components)/tabs.mdx
new file mode 100644
index 0000000..a41c5bc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/tabs.mdx
@@ -0,0 +1,211 @@
+---
+title: Tabs
+description: Migration guide for Tabs from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Tabs documentation](/docs/react/components/tabs) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Tabs used `Tab` component with `title` prop and children as panel content:
+
+```tsx
+import { Tabs, Tab } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tabs aria-label="Options">
+      <Tab key="photos" title="Photos">
+        <Card>Content here</Card>
+      </Tab>
+    </Tabs>
+  );
+}
+```
+
+In v3, Tabs requires compound components with separate tab and panel:
+
+```tsx
+import { Tabs } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tabs>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">
+        <Card>Content here</Card>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** `Tabs` with `Tab` children (title prop + children as panel)  
+**v3:** Compound components (`Tabs.ListContainer`, `Tabs.List`, `Tabs.Tab`, `Tabs.Indicator`, `Tabs.Separator`, `Tabs.Panel`)
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `key` (on Tab) | `id` (on Tab and Panel) | Changed prop name |
+| `title` (on Tab) | — | Content goes directly in `Tabs.Tab` |
+| `isVertical` | `orientation` | Changed to `"horizontal"` \| `"vertical"` |
+| `placement` | — | Use `orientation` and layout |
+| `variant` | `variant` | Simplified to `primary` \| `secondary` only |
+| `color` | — | Removed (use Tailwind CSS) |
+| `size` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `classNames` | — | Use `className` props on individual components |
+| `disableCursorAnimation` | — | Use `Tabs.Indicator` component |
+| `disableAnimation` | — | Removed (animations handled differently) |
+| `fullWidth` | — | Removed (use Tailwind CSS) |
+
+### 3. Component Changes
+
+- **Tab identification**: `key` → `id` (must match between `Tabs.Tab` and `Tabs.Panel`)
+- **Tab content**: `title` prop → direct children in `Tabs.Tab`
+- **Panel content**: Tab children → separate `Tabs.Panel` component
+- **Indicator**: Automatic cursor → explicit `Tabs.Indicator` component
+- **Separator**: New `Tabs.Separator` component to display separator lines between tabs
+
+## Migration Examples
+
+### Controlled Tabs
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("photos");
+
+    <Tabs selectedKey={selected} onSelectionChange={setSelected}>
+      <Tab key="photos" title="Photos">Content</Tab>
+      <Tab key="music" title="Music">Content</Tab>
+    </Tabs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [selected, setSelected] = useState("photos");
+
+    <Tabs selectedKey={selected} onSelectionChange={setSelected}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="music">
+            Music
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">Content</Tabs.Panel>
+      <Tabs.Panel id="music">Content</Tabs.Panel>
+    </Tabs>
+    ```
+  </Tab>
+</Tabs>
+
+### With Icons
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tabs aria-label="Options">
+      <Tab key="photos" title={<><PhotoIcon /> Photos</>}>
+        Content
+      </Tab>
+    </Tabs>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tabs>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="photos">
+            <PhotoIcon />
+            Photos
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel id="photos">Content</Tabs.Panel>
+    </Tabs>
+    ```
+  </Tab>
+</Tabs>
+
+### With Separator
+
+In v3, you can add `Tabs.Separator` inside each `Tabs.Tab` (except the first) to display separator lines between tabs. This is a new feature with no v2 equivalent.
+
+```tsx
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="photos">
+        Photos
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="music">
+        <Tabs.Separator />
+        Music
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="videos">
+        <Tabs.Separator />
+        Videos
+        <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="photos">Photos content</Tabs.Panel>
+  <Tabs.Panel id="music">Music content</Tabs.Panel>
+  <Tabs.Panel id="videos">Videos content</Tabs.Panel>
+</Tabs>
+```
+
+## Component Anatomy
+
+The v3 Tabs follows this structure:
+
+```
+Tabs (Root)
+  ├── Tabs.ListContainer
+  │   └── Tabs.List
+  │       └── Tabs.Tab
+  │           ├── Tabs.Separator (optional, omit on first tab)
+  │           └── Tabs.Indicator (optional)
+  └── Tabs.Panel (one per tab, matching id)
+```
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Tabs.ListContainer`, `Tabs.List`, `Tabs.Tab`, `Tabs.Indicator`, `Tabs.Separator`, `Tabs.Panel`)
+2. **Tab Identification**: `key` → `id` (must match between tab and panel)
+3. **Tab Content**: `title` prop removed - content goes directly in `Tabs.Tab`
+4. **Panel Separation**: Panel content moved to separate `Tabs.Panel` component
+5. **Indicator**: Must explicitly include `Tabs.Indicator` in each tab
+6. **Orientation**: `isVertical` → `orientation` prop
+7. **Styling**: `variant` simplified to `primary` \| `secondary`; `color`, `size`, `radius`, `placement` removed - use Tailwind for more
+8. **ClassNames Removed**: Use `className` props on individual components
+9. **Separator (New)**: Use `Tabs.Separator` inside `Tabs.Tab` to display separator lines between tabs (no v2 equivalent)
diff --git a/apps/docs/content/docs/en/react/migration/(components)/timeinput.mdx b/apps/docs/content/docs/en/react/migration/(components)/timeinput.mdx
new file mode 100644
index 0000000..dc25ade
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/timeinput.mdx
@@ -0,0 +1,266 @@
+---
+title: TimeInput
+description: Migration guide for TimeInput to TimeField from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 TimeField documentation](/docs/react/components/time-field) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, TimeInput was a single component with props:
+
+```tsx
+import { TimeInput } from "@heroui/react";
+
+export default function App() {
+  return <TimeInput label="Time" name="time" />;
+}
+```
+
+In v3, TimeField requires compound components with DateInputGroup and a render prop for segments:
+
+```tsx
+import { TimeField, DateInputGroup, Label } from "@heroui/react";
+
+export default function App() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Naming
+
+**v2:** `TimeInput`  
+**v3:** `TimeField`
+
+### 2. Component Structure
+
+**v2:** Single component with props  
+**v3:** Compound components: `TimeField` (root) + `DateInputGroup` with `DateInputGroup.Input` (render prop) and `DateInputGroup.Segment`; optionally `DateInputGroup.Prefix` and `DateInputGroup.Suffix`
+
+### 3. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `label` | — | Use `Label` component |
+| `description` | — | Use `Description` component |
+| `errorMessage` | — | Use `FieldError` component |
+| `value`, `defaultValue`, `onChange` | `TimeField` | Same (React Aria) |
+| `minValue`, `maxValue`, `granularity`, `placeholderValue` | `TimeField` | Same |
+| `isRequired`, `isDisabled`, `isReadOnly`, `isInvalid`, `name` | `TimeField` | Same |
+| `validationBehavior`, `shouldForceLeadingZeros` | `TimeField` | Same |
+| `variant` | `DateInputGroup` | Simplified to `primary` \| `secondary` only |
+| `fullWidth` | `TimeField` or `DateInputGroup` | On root or group |
+| `color` | — | Removed (use Tailwind CSS) |
+| `size` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `labelPlacement` | — | Handle with layout |
+| `startContent` | `DateInputGroup.Prefix` | Use Prefix child |
+| `endContent` | `DateInputGroup.Suffix` | Use Suffix child |
+| `classNames` | — | Use `className` on `TimeField` and `DateInputGroup` parts |
+| `groupProps` | — | Use `className` or DOM props on `DateInputGroup` |
+| `labelProps` | — | Use `className` on `Label` |
+| `fieldProps` | — | Use `className` on `DateInputGroup` |
+| `innerWrapperProps` | — | Use `className` on group/input parts |
+| `descriptionProps` | — | Use `className` on `Description` |
+| `errorMessageProps` | — | Use `className` on `FieldError` |
+| `inputRef` | — | Ref handled by `TimeField` / React Aria |
+
+## Migration Examples
+
+### With Description and Error
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TimeInput
+      description="Select start time"
+      label="Start time"
+      name="startTime"
+    />
+
+    <TimeInput
+      errorMessage="Please enter a valid time"
+      isInvalid
+      label="Time"
+      name="time"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Description, FieldError, Label } from "@heroui/react";
+
+    <TimeField className="w-[256px]" name="startTime">
+      <Label>Start time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <Description>Select start time</Description>
+    </TimeField>
+
+    <TimeField className="w-[256px]" isInvalid name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+      <FieldError>Please enter a valid time</FieldError>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState(null);
+
+    <TimeInput
+      label="Time"
+      name="time"
+      value={value}
+      onChange={setValue}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import type { TimeValue } from "@internationalized/date";
+    import { useState } from "react";
+
+    const [value, setValue] = useState<TimeValue | null>(null);
+
+    <TimeField
+      className="w-[256px]"
+      name="time"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### Min/Max and Granularity
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+
+    <TimeInput
+      granularity="minute"
+      label="Time"
+      maxValue={parseTime("18:00")}
+      minValue={parseTime("09:00")}
+      name="time"
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { parseTime } from "@internationalized/date";
+
+    <TimeField
+      className="w-[256px]"
+      granularity="minute"
+      maxValue={parseTime("18:00")}
+      minValue={parseTime("09:00")}
+      name="time"
+    >
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+### Start/End Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <TimeInput
+      endContent={<ClockIcon />}
+      label="Time"
+      name="time"
+      startContent={<ClockIcon />}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <DateInputGroup>
+        <DateInputGroup.Prefix>
+          <ClockIcon />
+        </DateInputGroup.Prefix>
+        <DateInputGroup.Input>
+          {(segment) => <DateInputGroup.Segment segment={segment} />}
+        </DateInputGroup.Input>
+        <DateInputGroup.Suffix>
+          <ClockIcon />
+        </DateInputGroup.Suffix>
+      </DateInputGroup>
+    </TimeField>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 TimeField follows this structure:
+
+```
+TimeField (Root)
+  ├── Label (optional)
+  ├── DateInputGroup
+  │   ├── DateInputGroup.Prefix (optional)
+  │   ├── DateInputGroup.Input → (segment) => DateInputGroup.Segment
+  │   └── DateInputGroup.Suffix (optional)
+  ├── Description (optional)
+  └── FieldError (optional)
+```
+
+## Summary
+
+1. **Component Renamed**: `TimeInput` → `TimeField`
+2. **Component Structure**: Must use compound components: `TimeField` (root) and `DateInputGroup` with `DateInputGroup.Input` (render prop) and `DateInputGroup.Segment`
+3. **Label/Description/Error**: Use separate components (`Label`, `Description`, `FieldError`)
+4. **Time Props Unchanged**: `value`, `defaultValue`, `onChange`, `minValue`, `maxValue`, `granularity`, `placeholderValue`, `isRequired`, `isDisabled`, `isInvalid`, `name`, `validationBehavior`, `shouldForceLeadingZeros` stay on `TimeField`
+5. **Variant on DateInputGroup**: v3 supports only `variant="primary"` and `variant="secondary"` on `DateInputGroup`; `color`, `size`, `radius` removed — use Tailwind CSS
+6. **Start/End Content**: `startContent`/`endContent` → `DateInputGroup.Prefix` and `DateInputGroup.Suffix`
+7. **Label Placement Removed**: `labelPlacement` removed — handle with layout
+8. **DOM/Class Props**: `groupProps`, `labelProps`, `fieldProps`, `classNames` removed — use `className` (and standard DOM props) on the relevant parts
diff --git a/apps/docs/content/docs/en/react/migration/(components)/toast.mdx b/apps/docs/content/docs/en/react/migration/(components)/toast.mdx
new file mode 100644
index 0000000..82427ae
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/toast.mdx
@@ -0,0 +1,220 @@
+---
+title: Toast
+description: Migration guide for Toast from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Toast documentation](/docs/react/components/toast) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Toast used a provider and hook pattern:
+
+```tsx
+import { ToastProvider, useToast } from "@heroui/react";
+
+function App() {
+  return (
+    <ToastProvider>
+      <MyComponent />
+    </ToastProvider>
+  );
+}
+
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <button onClick={() => toast.show("Hello!")}>
+      Show Toast
+    </button>
+  );
+}
+```
+
+In v3, Toast uses a provider component and a global `toast()` function:
+
+```tsx
+import { Toast } from "@heroui/react";
+
+function App() {
+  return (
+    <>
+      <Toast.Provider />
+      <MyComponent />
+    </>
+  );
+}
+
+function MyComponent() {
+  return (
+    <button onClick={() => toast("Hello!")}>
+      Show Toast
+    </button>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Provider Pattern
+
+**v2:** Required `ToastProvider` wrapper  
+**v3:** Uses `Toast.Provider` component (can be placed anywhere)
+
+### 2. Hook → Function
+
+**v2:** Used `useToast()` hook  
+**v3:** Uses `toast()` function directly
+
+### 3. API Changes
+
+**v2:** Used `toast.show()` method  
+**v3:** `toast()` is a function with helper methods (`toast.success()`, `toast.danger()`, etc.)
+
+### 4. Variant Names
+
+**v2:** Variants like `success`, `error`, `warning`, `info`  
+**v3:** Variants: `default`, `accent`, `success`, `warning`, `danger`
+
+### 5. Compound Component Structure
+
+**v3:** Toast uses compound components for custom rendering:
+- `Toast` - Main toast container
+- `Toast.Content` - Content wrapper
+- `Toast.Title` - Title text
+- `Toast.Description` - Description text
+- `Toast.Indicator` - Icon/indicator
+- `Toast.CloseButton` - Close button
+- `Toast.ActionButton` - Action button
+
+### 6. Promise Support
+
+**v3:** Built-in promise support with `toast.promise()` for handling async operations
+
+## Migration Examples
+
+### Toast with Title and Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({
+      title: "Success",
+      description: "Your changes have been saved",
+      variant: "success"
+    });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    toast.success("Success", {
+      description: "Your changes have been saved"
+    });
+    ```
+  </Tab>
+</Tabs>
+
+### Helper Methods for Variants
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({ variant: "success", title: "Success" });
+    toast.show({ variant: "error", title: "Error" });
+    toast.show({ variant: "warning", title: "Warning" });
+    toast.show({ variant: "info", title: "Info" });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    toast.success("Success");
+    toast.danger("Error");
+    toast.warning("Warning");
+    toast.info("Info");
+    ```
+  </Tab>
+</Tabs>
+
+### Promise Support
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    const handleAsync = async () => {
+      try {
+        await someAsyncOperation();
+        toast.show({ title: "Success", variant: "success" });
+      } catch {
+        toast.show({ title: "Error", variant: "error" });
+      }
+    };
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { toast } from "@heroui/react";
+
+    const handleAsync = async () => {
+      toast.promise(someAsyncOperation(), {
+        loading: "Processing...",
+        success: "Operation completed!",
+        error: "Operation failed"
+      });
+    };
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Toast Rendering
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    const { toast } = useToast();
+
+    toast.show({
+      title: "Custom",
+      render: (toast) => (
+        <div>Custom content</div>
+      )
+    });
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Toast, ToastContent, ToastTitle } from "@heroui/react";
+
+    <Toast.Provider>
+      {({ toast: toastItem }) => (
+        <Toast toast={toastItem}>
+          <ToastContent>
+            <ToastTitle>Custom content</ToastTitle>
+          </ToastContent>
+        </Toast>
+      )}
+    </Toast.Provider>
+    ```
+  </Tab>
+</Tabs>
+
+## Summary
+
+- Replace `ToastProvider` with `Toast.Provider`
+- Replace `useToast()` hook with `toast()` function
+- Update variant names (`error` → `danger`, `info` → `accent`)
+- Use helper methods: `toast.success()`, `toast.danger()`, etc.
+- Use `toast.promise()` for async operations
+- Compound component structure for custom rendering
+- Better TypeScript support and queue management
diff --git a/apps/docs/content/docs/en/react/migration/(components)/tooltip.mdx b/apps/docs/content/docs/en/react/migration/(components)/tooltip.mdx
new file mode 100644
index 0000000..e26ab12
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/tooltip.mdx
@@ -0,0 +1,353 @@
+---
+title: Tooltip
+description: Migration guide for Tooltip from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 Tooltip documentation](/docs/react/components/tooltip) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
+</Callout>
+
+## Structure Changes
+
+In v2, Tooltip used a `content` prop:
+
+```tsx
+import { Tooltip, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tooltip content="I am a tooltip">
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+In v3, Tooltip requires compound components:
+
+```tsx
+import { Tooltip, Button } from "@heroui/react";
+
+export default function App() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        I am a tooltip
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Key Changes
+
+### 1. Component Structure
+
+**v2:** Simple Tooltip with `content` prop and children as trigger  
+**v3:** Compound components (`Tooltip.Trigger`, `Tooltip.Content`, `Tooltip.Arrow`)
+
+### 2. Prop Changes
+
+| v2 Prop | v3 Location | Notes |
+|---------|-------------|-------|
+| `content` | — | Use `Tooltip.Content` children |
+| `showArrow` | `showArrow` (on Content) | Moved to `Tooltip.Content` |
+| `placement` | `placement` (on Content) | Moved to `Tooltip.Content` |
+| `offset` | `offset` (on Content) | Moved to `Tooltip.Content` |
+| `color` | — | Removed (use Tailwind CSS) |
+| `size` | — | Removed (use Tailwind CSS) |
+| `radius` | — | Removed (use Tailwind CSS) |
+| `shadow` | — | Removed (use Tailwind CSS) |
+| `classNames` | — | Use `className` props on individual components |
+| `motionProps` | — | Removed (animations handled differently) |
+| `trigger` | `trigger` (on root) | Still exists: `"hover"` \| `"focus"` (default `"hover"`) |
+| `isDisabled` | `isDisabled` (on root) | New in v3: disables the tooltip entirely |
+| `delay` | `delay` (on root) | Still exists (default changed from `0` to `700`) |
+| `closeDelay` | `closeDelay` (on root) | Still exists (default `0`) |
+| `portalContainer` | — | Not exposed |
+| `updatePositionDeps` | — | Not exposed |
+| `containerPadding`, `crossOffset` | — | Not exposed |
+| `shouldFlip` | — | Handled automatically |
+| `triggerScaleOnOpen` | — | Not available |
+| `isKeyboardDismissDisabled` | — | Not available |
+| `isDismissable` | — | Not available |
+| `shouldCloseOnBlur` | — | Not available |
+| `shouldCloseOnInteractOutside` | — | Not available |
+| `onClose` | — | Use `onOpenChange` instead |
+
+### 3. Props Moved to Tooltip.Content
+
+- `showArrow` - Now on `Tooltip.Content`
+- `placement` - Now on `Tooltip.Content`
+- `offset` - Now on `Tooltip.Content`
+
+## Migration Examples
+
+### Content Configuration
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    {/* With arrow */}
+    <Tooltip content="I am a tooltip" showArrow>
+      <Button>Hover me</Button>
+    </Tooltip>
+    
+    {/* With placement */}
+    <Tooltip content="Tooltip" placement="bottom">
+      <Button>Hover me</Button>
+    </Tooltip>
+    
+    {/* With offset */}
+    <Tooltip content="Tooltip" offset={12}>
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* With arrow */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content showArrow>
+        <Tooltip.Arrow />
+        <p>I am a tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    
+    {/* With placement */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content placement="bottom">
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    
+    {/* With offset */}
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content offset={12}>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### Controlled Tooltip
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Tooltip
+      content="I am a tooltip"
+      isOpen={isOpen}
+      onOpenChange={setIsOpen}
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { useState } from "react";
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    <Tooltip isOpen={isOpen} onOpenChange={setIsOpen} delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>I am a tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### With Delay
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip content="Tooltip" delay={500} closeDelay={200}>
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={500} closeDelay={200}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### Custom Content
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip
+      content={
+        <div>
+          <strong>Title</strong>
+          <p>Description</p>
+        </div>
+      }
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={0}>
+      <Tooltip.Trigger>
+        <Button>Hover me</Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <div>
+          <strong>Title</strong>
+          <p>Description</p>
+        </div>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+### With Custom Trigger
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Tooltip content="Tooltip">
+      <div className="custom-trigger">Custom trigger</div>
+    </Tooltip>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <Tooltip delay={0}>
+      <Tooltip.Trigger className="custom-trigger">
+        <div>Custom trigger</div>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <p>Tooltip</p>
+      </Tooltip.Content>
+    </Tooltip>
+    ```
+  </Tab>
+</Tabs>
+
+## Component Anatomy
+
+The v3 Tooltip follows this structure:
+
+```
+Tooltip (Root)
+  ├── Tooltip.Trigger
+  │   └── [Trigger element]
+  └── Tooltip.Content
+      ├── Tooltip.Arrow (optional)
+      └── [Tooltip content]
+```
+
+## New Props in v3
+
+### isDisabled
+
+The `isDisabled` prop allows you to completely disable the tooltip. When disabled, the tooltip will not appear on hover or focus:
+
+```tsx
+<Tooltip isDisabled>
+  <Tooltip.Trigger>
+    <Button>No tooltip</Button>
+  </Tooltip.Trigger>
+  <Tooltip.Content>
+    <p>This will not show</p>
+  </Tooltip.Content>
+</Tooltip>
+```
+
+### trigger
+
+The `trigger` prop controls how the tooltip is activated. It accepts `"hover"` (default) or `"focus"`:
+
+```tsx
+{/* Show tooltip only on focus */}
+<Tooltip trigger="focus">
+  <Tooltip.Trigger>
+    <Button>Focus me</Button>
+  </Tooltip.Trigger>
+  <Tooltip.Content>
+    <p>Shown on focus only</p>
+  </Tooltip.Content>
+</Tooltip>
+```
+
+### Custom Render Function
+
+`Tooltip.Content` and `Tooltip.Arrow` both support a `render` prop that allows you to override the default DOM element with a custom render function for advanced use cases.
+
+## Important Notes
+
+### Content Prop
+
+- **v2:** Used `content` prop for tooltip text/content
+- **v3:** Content goes as children of `Tooltip.Content` component
+
+### Arrow
+
+- **v2:** Controlled by `showArrow` prop on root
+- **v3:** Use `showArrow` prop on `Tooltip.Content` and include `Tooltip.Arrow` component
+
+### Placement and Offset
+
+- **v2:** `placement` and `offset` props on root
+- **v3:** `placement` and `offset` props moved to `Tooltip.Content`
+
+### Trigger Element
+
+- **v2:** Children were automatically used as trigger
+- **v3:** Must wrap trigger element in `Tooltip.Trigger` component
+
+### Default Delay
+
+- **v2:** `delay` default was `0`
+- **v3:** `delay` default is `700` (note: examples use `delay={0}` to match v2 behavior)
+
+## Summary
+
+1. **Component Structure**: Must use compound components (`Tooltip.Trigger`, `Tooltip.Content`, `Tooltip.Arrow`)
+2. **Content Prop Removed**: `content` prop removed - use `Tooltip.Content` children
+3. **Props Moved**: `showArrow`, `placement`, `offset` moved to `Tooltip.Content`
+4. **Styling Props Removed**: `color`, `size`, `radius`, `shadow` - use Tailwind CSS
+5. **ClassNames Removed**: Use `className` props on individual components
+6. **Motion Props Removed**: `motionProps` removed - animations handled differently
+7. **Advanced Props Removed**: Many positioning and behavior props removed
+8. **Default Delay Changed**: Default delay changed from `0` to `700`
+9. **isDisabled Prop**: New `isDisabled` prop to completely disable the tooltip
+10. **trigger Prop**: Accepts `"hover"` (default) or `"focus"` to control activation method
+11. **Render Props**: `Tooltip.Content` and `Tooltip.Arrow` support a `render` prop for custom DOM rendering
diff --git a/apps/docs/content/docs/en/react/migration/(components)/user.mdx b/apps/docs/content/docs/en/react/migration/(components)/user.mdx
new file mode 100644
index 0000000..697dee0
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(components)/user.mdx
@@ -0,0 +1,446 @@
+---
+title: User
+description: Migration guide for User from HeroUI v2 to v3
+---
+
+<Callout type="warning">
+  The User component has been **removed** in HeroUI v3. Compose user displays manually using Avatar and text elements with Tailwind CSS classes.
+</Callout>
+
+## Key Changes
+
+### 1. Component Removal
+
+**v2:** `<User>` component from `@heroui/react`  
+**v3:** Manual composition using `Avatar` + text elements
+
+### 2. Features Mapping
+
+The v2 User component had the following features that need to be replaced:
+
+| v2 Feature | v3 Equivalent | Notes |
+|-----------|---------------|-------|
+| `name` prop | Text element | Render name as text or heading |
+| `description` prop | Text element | Render description as text |
+| `avatarProps` prop | `Avatar` component | Use v3 Avatar component directly |
+| `isFocusable` prop | Manual focus handling | Add `tabIndex` and focus styles if needed |
+| `classNames` prop | Tailwind classes | Apply classes directly to elements |
+
+## Structure Changes
+
+### v2: User Component
+
+In v2, `User` was a convenience component combining Avatar with name:
+
+```tsx
+import { User } from "@heroui/react";
+
+export default function App() {
+  return (
+    <User
+      name="Junior Garcia"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+  );
+}
+```
+
+### v3: Manual Composition
+
+In v3, compose user displays manually using Avatar and text elements:
+
+```tsx
+import { Avatar } from "@heroui/react";
+
+export default function App() {
+  return (
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </div>
+  );
+}
+```
+
+## Migration Examples
+
+### With Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">Junior Garcia</span>
+        <span className="text-xs text-muted">Software Engineer</span>
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### With Default Avatar (Initials)
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      avatarProps={{
+        name: "Junior Garcia",
+        getInitials: (name) =>
+          name
+            .split(" ")
+            .map((n) => n[0])
+            .join(""),
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    function getInitials(name: string) {
+      return name
+        .split(" ")
+        .map((n) => n[0])
+        .join("");
+    }
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Fallback>{getInitials("Junior Garcia")}</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### With Link Description
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User, Link } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description={
+        <Link href="https://x.com/jrgarciadev" size="sm">
+          @jrgarciadev
+        </Link>
+      }
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Link } from "@heroui/react";
+
+    <div className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">Junior Garcia</span>
+        <Link href="https://x.com/jrgarciadev" className="text-xs">
+          @jrgarciadev
+        </Link>
+      </div>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Clickable User
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    {/* Focusable */}
+    <User
+      name="Junior Garcia"
+      isFocusable
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    
+    {/* As button */}
+    <User
+      as="button"
+      name="Junior Garcia"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar } from "@heroui/react";
+
+    {/* Focusable */}
+    <button
+      className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus"
+      tabIndex={0}
+    >
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </button>
+    
+    {/* As button */}
+    <button
+      className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus"
+    >
+      <Avatar>
+        <Avatar.Image
+          src="https://example.com/avatar.jpg"
+          alt="Junior Garcia"
+        />
+        <Avatar.Fallback>JG</Avatar.Fallback>
+      </Avatar>
+      <span className="text-sm">Junior Garcia</span>
+    </button>
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a Reusable User Component (Recommended)
+
+Since User displays are commonly needed, here's a reusable component:
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    import { User } from "@heroui/react";
+
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarProps={{
+        src: "https://example.com/avatar.jpg",
+      }}
+    />
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    import { Avatar, Link } from "@heroui/react";
+    import { ReactNode } from "react";
+    import { cn } from "@/lib/utils"; // or your cn utility
+
+    interface UserProps {
+      name: string | ReactNode;
+      description?: string | ReactNode;
+      avatarSrc?: string;
+      avatarAlt?: string;
+      avatarFallback?: string;
+      className?: string;
+      isFocusable?: boolean;
+      as?: "div" | "button" | "a";
+      href?: string;
+      onClick?: () => void;
+    }
+
+    function getInitials(name: string): string {
+      return name
+        .split(" ")
+        .map((n) => n[0])
+        .join("")
+        .toUpperCase()
+        .slice(0, 2);
+    }
+
+    export function User({
+      name,
+      description,
+      avatarSrc,
+      avatarAlt,
+      avatarFallback,
+      className,
+      isFocusable = false,
+      as = "div",
+      href,
+      onClick,
+    }: UserProps) {
+      const Component = as === "a" ? "a" : as === "button" ? "button" : "div";
+      const fallback = avatarFallback || (typeof name === "string" ? getInitials(name) : "?");
+
+      const content = (
+        <>
+          <Avatar>
+            {avatarSrc && (
+              <Avatar.Image
+                src={avatarSrc}
+                alt={avatarAlt || (typeof name === "string" ? name : "")}
+              />
+            )}
+            <Avatar.Fallback>{fallback}</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col items-start">
+            <span className="text-sm">{name}</span>
+            {description && (
+              <span className="text-xs text-muted">{description}</span>
+            )}
+          </div>
+        </>
+      );
+
+      const baseClasses = cn(
+        "inline-flex items-center gap-2 rounded-sm outline-none",
+        isFocusable && "focus-visible:ring-2 focus-visible:ring-focus",
+        className
+      );
+
+      if (Component === "button") {
+        return (
+          <button className={baseClasses} onClick={onClick} tabIndex={isFocusable ? 0 : -1}>
+            {content}
+          </button>
+        );
+      }
+
+      if (Component === "a") {
+        return (
+          <a href={href} className={baseClasses} tabIndex={isFocusable ? 0 : -1}>
+            {content}
+          </a>
+        );
+      }
+
+      return (
+        <div className={baseClasses} tabIndex={isFocusable ? 0 : -1}>
+          {content}
+        </div>
+      );
+    }
+
+    // Usage
+    <User
+      name="Junior Garcia"
+      description="Software Engineer"
+      avatarSrc="https://example.com/avatar.jpg"
+      avatarAlt="Junior Garcia"
+    />
+    ```
+  </Tab>
+</Tabs>
+
+## Styling Reference
+
+The v2 User component used these base styles that you should replicate:
+
+- **Base container**: `inline-flex items-center gap-2 rounded-sm`
+- **Wrapper (for name/description)**: `inline-flex flex-col items-start`
+- **Name**: `text-sm` (text-small)
+- **Description**: `text-xs text-muted` (text-tiny text-foreground-400)
+
+## Summary
+
+1. **Component Removed**: `User` component no longer exists in v3
+2. **Import Change**: Remove `import { User } from "@heroui/react"`
+3. **Manual Composition**: Compose using Avatar + text elements
+4. **Avatar Changes**: Use v3 Avatar compound component pattern
+5. **Styling**: Apply Tailwind CSS classes directly
+6. **Focus Handling**: Implement focus styles manually if needed
+
+## Migration Steps
+
+1. **Remove Import**: Remove `User` from `@heroui/react` imports
+2. **Replace Component**: Replace all `<User>` instances with manual composition
+3. **Use Avatar**: Use v3 Avatar component with compound pattern
+4. **Add Text Elements**: Add name and description as text elements
+5. **Apply Styling**: Use Tailwind CSS classes for layout and styling
+6. **Handle Focus**: Add focus styles if `isFocusable` was used
+7. **Optional**: Create reusable User component for your application
+
+## Common Patterns
+
+### User List
+
+```tsx
+<div className="space-y-2">
+  {users.map((user) => (
+    <div key={user.id} className="inline-flex items-center gap-2">
+      <Avatar>
+        <Avatar.Image src={user.avatar} alt={user.name} />
+        <Avatar.Fallback>{getInitials(user.name)}</Avatar.Fallback>
+      </Avatar>
+      <div className="flex flex-col items-start">
+        <span className="text-sm">{user.name}</span>
+        {user.role && (
+          <span className="text-xs text-muted">{user.role}</span>
+        )}
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+### Clickable User
+
+```tsx
+<button
+  className="inline-flex items-center gap-2 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-focus hover:bg-default-100"
+  onClick={() => handleUserClick(user)}
+>
+  <Avatar>
+    <Avatar.Image src={user.avatar} alt={user.name} />
+    <Avatar.Fallback>{getInitials(user.name)}</Avatar.Fallback>
+  </Avatar>
+  <div className="flex flex-col items-start">
+    <span className="text-sm">{user.name}</span>
+    <span className="text-xs text-muted">{user.email}</span>
+  </div>
+</button>
+```
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agent-skills.mdx b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agent-skills.mdx
new file mode 100644
index 0000000..3e9b3d9
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agent-skills.mdx
@@ -0,0 +1,60 @@
+---
+title: Agent Skills
+description: Enable AI assistants to migrate HeroUI v2 to v3
+---
+
+HeroUI Migration Skills give your AI assistant comprehensive knowledge of HeroUI v2 to v3 migration workflows, component guides, and best practices.
+
+### Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-migration
+```
+
+Or using the skills package:
+
+```bash
+npx skills add heroui-inc/heroui
+```
+
+<span className="text-sm text-muted">
+Support Claude Code, Cursor, OpenCode and more.
+</span>
+
+### Usage
+
+Skills are **automatically discovered** by your AI assistant, or call it directly using `/heroui-migration` command.
+
+Simply ask your AI assistant to:
+- Migrate components from HeroUI v2 to v3
+- Get the full or incremental migration workflow
+- Fetch component-specific migration guides
+- Access hooks and styling migration documentation
+
+### What's Included
+
+- Migration workflows (full and incremental)
+- Component-specific migration guides (39 components)
+- Hooks migration guide (useDisclosure → useOverlayState, etc.)
+- Styling migration guide (utility classes, color tokens, CSS variables)
+- Key API changes and compound component patterns
+
+### Structure
+
+```
+skills/heroui-migration/
+├── SKILL.md                    # Main skill documentation
+├── LICENSE.txt                 # Apache License 2.0
+└── scripts/                    # Utility scripts
+    ├── list_migration_guides.mjs
+    ├── get_migration_guide.mjs
+    ├── get_component_migration_guides.mjs
+    ├── get_styling_migration_guide.mjs
+    └── get_hooks_migration_guide.mjs
+```
+
+## Links
+
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [Discord Community](https://discord.gg/9b6yyZKmH4)
+- [Agent Skills](https://agentskills.io/) - Learn about the Agent Skills format
diff --git a/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agents-md.mdx b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agents-md.mdx
new file mode 100644
index 0000000..6419d69
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/agents-md.mdx
@@ -0,0 +1,51 @@
+---
+title: AGENTS.md
+description: Download HeroUI v2 to v3 migration docs for AI coding agents
+---
+
+Download HeroUI v2 to v3 migration documentation directly into your project for AI assistants to reference.
+
+<Callout>
+  **Note:** The `agents-md --migration` command downloads migration docs only. Use `--react` for component documentation. Only one library option is supported at a time.
+</Callout>
+
+### Usage
+
+```bash
+npx heroui-cli@latest agents-md --migration
+```
+
+Or specify output file:
+
+```bash
+npx heroui-cli@latest agents-md --migration --output AGENTS.md
+```
+
+### What It Does
+
+- Downloads migration docs to `.heroui-docs/migration/`
+- Generates an index in `AGENTS.md` or `CLAUDE.md` with migration-specific content
+- Includes workflow guides (full and incremental), component migration guides, hooks, and styling
+- Adds `.heroui-docs/` to `.gitignore` automatically
+
+### Options
+
+- `--migration` - Download migration docs only (v2 to v3)
+- `--output <files...>` - Target file(s) (e.g., `AGENTS.md` or `AGENTS.md CLAUDE.md`)
+- `--ssh` - Use SSH for git clone
+
+### Requirements
+
+Migration docs are useful for any project migrating from HeroUI v2 to v3. The target project needs:
+
+- Tailwind CSS >= v4
+- React >= 19.0.0 (for v3)
+- `@heroui/react` or `@heroui/styles` (after migration)
+
+## Links
+
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [Discord Community](https://discord.gg/9b6yyZKmH4)
+- [AGENTS.md](https://agents.md/) - Learn about the AGENTS.md format
+- [CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) - Claude equivalent of AGENTS.md
+- [AGENTS.md vs Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) - AGENTS.md performance
diff --git a/apps/docs/content/docs/en/react/migration/(migration-for-agents)/mcp-server.mdx b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/mcp-server.mdx
new file mode 100644
index 0000000..a258d54
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(migration-for-agents)/mcp-server.mdx
@@ -0,0 +1,175 @@
+---
+title: MCP Server
+description: Access HeroUI v2 to v3 migration guides in your AI assistant
+---
+
+The HeroUI Migration MCP Server gives AI assistants direct access to HeroUI v2 to v3 migration documentation.
+
+The Migration MCP server uses **Streamable HTTP transport** (URL-based) and is deployed at `https://migration-mcp.heroui.com`. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp/tree/main/apps/migration-mcp).
+
+<Callout>
+  The Migration MCP is for **migration only**. After completing migration, switch to the [HeroUI React MCP Server](/docs/react/getting-started/mcp-server) for v3 component development.
+</Callout>
+
+## Quick Setup
+
+### Cursor
+
+Add to **Cursor Settings** → **Tools** → **MCP Servers** or your project's `.cursor/mcp.json`:
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+To learn more, see the [Cursor documentation](https://cursor.com/docs/context/mcp).
+
+### Claude Code
+
+Add to your project's `.mcp.json` file:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "type": "http",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Code and run `/mcp` to see the HeroUI Migration MCP server in the list. If you see **Connected**, you're ready to use it.
+
+See the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for more details.
+
+### Windsurf
+
+Add the Migration MCP server to your project's `.windsurf/mcp.json` configuration file:
+
+```json title=".windsurf/mcp.json"
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+After adding the configuration, restart Windsurf to activate the MCP server.
+
+See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more details.
+
+### Zed
+
+Add the Migration MCP server to your `settings.json` configuration file. Open settings via Command Palette (`zed: open settings`) or use `Cmd-,` (Mac) / `Ctrl-,` (Linux):
+
+```json title="settings.json"
+{
+  "context_servers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp) for more details.
+
+### VS Code
+
+To configure MCP in VS Code with GitHub Copilot, add the Migration MCP server to your project's `.vscode/mcp.json` configuration file:
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "heroui-migration": {
+      "type": "http",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-migration server.
+
+See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
+
+### Codex
+
+Add the Migration MCP server to your `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):
+
+```toml title="config.toml"
+[mcp_servers.heroui-migration]
+url = "https://migration-mcp.heroui.com"
+```
+
+After adding the configuration, restart Codex and run `/mcp` in the TUI to verify the server is active.
+
+See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
+
+### OpenCode
+
+Add the Migration MCP server to your project's `opencode.json` configuration file:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "heroui-migration": {
+      "type": "remote",
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+After adding the configuration, restart OpenCode to activate the MCP server.
+
+See the [OpenCode MCP documentation](https://open-code.ai/docs/en/mcp-servers) for more details.
+
+## Usage
+
+Once configured, ask your AI assistant questions like:
+
+- "Help me migrate Button from HeroUI v2 to v3"
+- "Get the full migration workflow for my project"
+- "What are the Checkbox migration changes?"
+- "Show me the migration guide for Card and Modal"
+- "Get the styling migration guide"
+- "What hooks do I need to migrate?"
+
+## Available Tools
+
+The Migration MCP server provides these tools to AI assistants:
+
+| Tool | Description |
+|------|-------------|
+| `get_migration_workflow` | Get the comprehensive migration guide. Use `migrationType: "full"` (default) or `"incremental"` for full vs incremental migration approach |
+| `list_component_migration_guides` | List all 39 available component migration guides |
+| `get_component_migration_guides` | Get migration guides for specific components. Pass `components: ["button", "card"]` (kebab-case) |
+| `get_styling_migration_guide` | Get the styling migration guide (utility classes, color tokens, CSS variables) |
+| `get_hooks_migration_guide` | Get the hooks migration guide (useDisclosure → useOverlayState, etc.) |
+
+## Available Prompts
+
+The Migration MCP server provides guided prompts that can be used with slash commands in your agent chat:
+
+| Prompt | Description |
+|--------|-------------|
+| `analyze-and-plan` | Analyze the project to identify all HeroUI v2 components and create a migration plan. Use this as the first step in migration. Optional: `migrationType: "full"` (default) or `"incremental"` |
+| `implement-migration` | Implement component migrations phase by phase with checkpoints for user approval. Migrates components, switches dependencies, then guides through hooks and styling. Optional: `migrationType: "full"` (default) or `"incremental"` |
+
+**Workflow:** Run `analyze-and-plan` first to create your migration plan, then use `implement-migration` to execute it step by step.
+
+## Links
+
+- [GitHub Repository](https://github.com/heroui-inc/heroui-mcp/tree/main/apps/migration-mcp)
+- [Discord Community](https://discord.gg/9b6yyZKmH4)
+- [Model Context Protocol](https://modelcontextprotocol.io/) - Learn about MCP
diff --git a/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-full.mdx b/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-full.mdx
new file mode 100644
index 0000000..7b331be
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-full.mdx
@@ -0,0 +1,322 @@
+---
+title: Agent Migration Guide - Full Migration
+description: Full migration guide for AI assistants helping migrate HeroUI v2 to v3
+index: false
+---
+
+## Overview
+
+This guide is designed for AI assistants (agents) helping users migrate from HeroUI v2 to v3. It implements a **full migration approach** that analyzes the project first and migrates components in manageable batches rather than all at once.
+
+<Callout type="warning">
+  **Critical Constraint**: HeroUI v2 and v3 **should not coexist** in the same project. The project will be broken during migration. Always work in a feature branch and migrate all component code before switching dependencies.
+</Callout>
+
+## Key Principles
+
+1. **Full Migration**: Never migrate all components at once. Large projects require full migration.
+2. **Project Analysis First**: Always analyze the codebase to understand component usage before creating a migration plan.
+3. **Broken State Management**: **Critical**: The project will be broken during migration. Plan for this by:
+   - Migrating in a feature branch
+   - Preparing all code changes before switching dependencies
+   - Having a rollback plan
+   - Testing in isolated environment first
+4. **All-or-Nothing Dependency Switch**: Once dependencies are updated to v3, ALL components must be migrated. Plan component migrations before switching dependencies.
+
+## Major Changes in v3
+
+<include>../index.mdx#major-changes</include>
+
+## Detailed Migration Steps
+
+For detailed step-by-step instructions, see the [Full Migration Guide](/docs/react/migration/full-migration). The guide covers:
+
+- Dependency updates
+- Theming configuration changes
+- Removing HeroUIProvider
+- Component imports and migration
+- Hooks migration
+- Styling migration
+- Testing
+
+**Agent Note**: Dependency updates (React 19, Tailwind v4) can be done before switching HeroUI (won't break project). However, the HeroUI package switch should only happen AFTER all component code is migrated.
+
+## Hooks Migration
+
+HeroUI v2 provided component hooks (like `useSwitch`, `useInput`, `useCheckbox`, etc.) and utility hooks like `useDisclosure`. HeroUI v3 removes most component hooks in favor of compound components, and replaces `useDisclosure` with `useOverlayState`.
+
+**When to migrate hooks:**
+
+- **During component migration**: Replace component hooks (`useSwitch`, `useInput`, etc.) as you migrate each component to use compound components
+- **After component migration**: Migrate `useDisclosure` → `useOverlayState` for overlay state management before styling migration
+
+**Migration Strategy:**
+
+1. **Identify hook usage**: Search codebase for imports from `@heroui/react` that include hook names (`useSwitch`, `useInput`, `useCheckbox`, `useRadio`, `useDisclosure`, etc.)
+2. **Replace component hooks**: Use compound components instead of hooks with prop getters (done during component migration)
+3. **Replace useDisclosure**: Migrate to `useOverlayState` for overlay state management (use `get_hooks_migration_guide` MCP tool)
+4. **Reference guides**: Use `get_hooks_migration_guide` MCP tool for hooks migration, `get_component_migration_guides` for component-specific guides
+
+## Component Import Changes
+
+See the [Full Migration Guide](/docs/react/migration/full-migration#step-5-update-component-imports) for detailed component import changes.
+
+## Component Migration Reference
+
+<include>../index.mdx#step-6-component-migration-reference</include>
+
+<Callout type="info">
+  **Removed/In-Progress/Planned Components**: For components marked as ❌ Removed, 🔄 In Progress, or 📋 Planned, replace them with standard HTML elements during migration. You can migrate back to HeroUI components once they become available in v3.
+</Callout>
+
+Use the `get_component_migration_guides` MCP tool to fetch detailed guides for each component.
+
+## New Components in v3
+
+<include>../index.mdx#new-components-in-v3</include>
+
+## Custom Theme Overrides
+
+See the [Full Migration Guide](/docs/react/migration/full-migration#step-7-update-custom-theme-overrides) for custom theme override migration.
+
+## Styling Migration
+
+See the [Full Migration Guide](/docs/react/migration/full-migration#step-9-styling-migration) for detailed styling migration instructions.
+
+**Agent Note**: Use the `get_styling_migration_guide` MCP tool for comprehensive styling migration details.
+
+**Important**: Styling migration happens AFTER component migration and dependency switch.
+
+## Full Migration Workflow
+
+**IMPORTANT**: Since v2 and v3 cannot coexist, the migration happens in two main stages:
+
+1. **Preparation Stage**: Migrate all component code while still on v2 dependencies (code will be broken)
+2. **Switch Stage**: Update dependencies to v3 and fix any remaining issues
+
+**⚠️ CRITICAL: Don't build to check for errors during migration**
+
+- Use **typecheck** (e.g., `tsc --noEmit`) if available to check TypeScript errors
+- Use **lint** (e.g., `eslint`, `biome check`) if available to check code quality
+- **DO NOT** run build commands (e.g., `npm run build`, `next build`, `vite build`)
+- **DO NOT** attempt to start/run the project during migration
+
+### Phase 0: Setup and Analysis
+
+1. **Create migration branch**
+   - Create a feature branch for migration work
+   - Example: `git checkout -b migrate/heroui-v3`
+
+2. **Verify Migration MCP is configured**
+   - Check that Migration MCP server is connected
+   - Ensure `heroui-react` MCP is NOT connected (to avoid confusion)
+   - Verify MCP tools are available
+
+3. **Analyze the project and create a migration plan**
+   - Use `get_migration_workflow` to fetch this guide
+   - Scan for HeroUI v2 imports, identify all components and usage
+   - Map component dependencies
+   - Create a phased migration plan (e.g., 3-5 components per phase, by-dependency strategy)
+
+### Phase 1: Dependency Preparation (Before Code Changes)
+
+These steps can be done before switching HeroUI dependencies and won't break the project:
+
+1. **Update React to v19** (if not already)
+   - This can be done before switching HeroUI
+
+2. **Update Tailwind CSS to v4** (if not already)
+   - This can be done before switching HeroUI
+
+3. **🛑 CHECKPOINT: Stop and wait for user approval**
+   - **DO NOT proceed to next phase automatically**
+   - Explain configuration changes
+   - Wait for explicit user approval before continuing
+
+### Phase 2-N: Code Migration (v2 Dependencies Still Active)
+
+**Critical**: During this phase, code will reference v3 APIs but v2 dependencies are still installed. The project will be broken. This is expected and normal.
+
+For each component group in the migration plan:
+
+1. **Fetch component-specific guides**
+   - Use `get_component_migration_guides` MCP tool for each component
+   - Review API changes, prop migrations, structure changes
+
+2. **Apply code migrations**
+   - Migrate component code to v3 API patterns
+   - Update imports, props, component structure
+   - **Note**: Code will be broken until dependencies are switched
+
+3. **Handle dependencies**
+   - If components have dependencies, migrate dependencies first
+   - Check if dependencies are already migrated
+   - Migrate shared code as needed
+
+4. **🛑 CHECKPOINT: Stop and wait for user approval**
+   - **DO NOT proceed to next phase automatically**
+   - Summarize what was migrated in this phase
+   - Wait for explicit user approval before continuing
+
+5. **Document migration status**
+   - Track which components have been migrated
+   - Note any issues or concerns
+
+### Phase Final: Dependency Switch and Fixes
+
+**Critical**: Only proceed when ALL components have been migrated to v3 API patterns.
+
+1. **Update dependencies**
+   - Remove `@heroui/react` and `@heroui/theme` (v2)
+   - Install `@heroui/react` and `@heroui/styles` (v3)
+   - Remove `framer-motion` if present
+   - Update CSS imports (add `@import "@heroui/styles";`)
+   - Remove HeroUIProvider from app root
+   - Update Tailwind config (remove `heroui()` plugin)
+
+2. **Fix remaining issues**
+   - Run typecheck/lint if available (do NOT build)
+   - Fix any TypeScript errors reported by typecheck
+   - Fix any linting errors
+   - Note: Do not attempt to build or run the project during migration
+
+3. **🛑 CHECKPOINT: Stop and wait for user approval**
+   - **DO NOT proceed to styling automatically**
+   - Verify components work correctly
+   - Wait for explicit user approval before styling migration
+
+4. **Continue with styling migration**
+   - Use `get_styling_migration_guide` MCP tool to fetch styling guide
+   - Apply styling updates systematically
+
+5. **Apply styling updates**
+   - Use `get_styling_migration_guide` MCP tool
+   - Update utility classes, color tokens, CSS variables
+   - Test visual appearance
+
+6. **Final verification**
+   - Run typecheck/lint one final time (do NOT build)
+   - Verify all styling updated correctly
+   - Note: Full testing (visual, functionality, accessibility) should be done after migration is complete, not during migration
+
+## Migration Strategies
+
+### Strategy 1: By Dependency (Recommended)
+
+- Migrate foundational components first (Button, Input, Card, etc.)
+- Then migrate components that depend on them
+- Best for projects with complex component hierarchies
+- Ensures dependencies are ready before dependents
+
+**Example order**:
+1. Button, Input, Link (foundational)
+2. Card, Modal (use Button)
+3. Form, Dropdown (use Input, Button)
+4. Complex components (use multiple dependencies)
+
+### Strategy 2: By Feature
+
+- Migrate all components in a feature/module together
+- Good for feature-based code organization
+- Allows feature-by-feature testing
+- May require migrating dependencies first
+
+**Example**:
+- Feature: User Authentication
+  - Migrate: Input, Button, Form, Modal (all auth-related)
+- Feature: Dashboard
+  - Migrate: Card, Tabs, Select (all dashboard-related)
+
+### Strategy 3: By Frequency
+
+- Migrate most-used components first
+- Provides quick wins and early validation
+- Good for large codebases with clear usage patterns
+- Still need to handle dependencies
+
+**Example**:
+1. Button (used 150 times)
+2. Input (used 120 times)
+3. Card (used 80 times)
+4. ... (continue by usage count)
+
+## Best Practices for Agents
+
+1. **Warn about broken state**
+   - Always inform user that project will be broken during migration
+   - Recommend using a feature branch
+   - Set expectations about when project will work again
+
+2. **Migrate all code before switching dependencies**
+   - Complete all component code migrations first
+   - Only switch dependencies when ALL components are migrated
+   - This minimizes the broken state duration
+
+3. **Use MCP tools for each phase**
+   - Use `get_migration_workflow`, `get_component_migration_guides`, `get_styling_migration_guide` as needed
+   - **Critical**: Always stop at checkpoints and wait for user approval between phases
+
+4. **Work in a feature branch**
+   - Always recommend creating a migration branch
+   - Allow user to continue working on main branch
+   - Enable easy rollback if needed
+
+5. **Document migration status**
+   - Track which components have been migrated
+   - Note any issues or concerns
+   - Keep a checklist visible
+   - Update status after each phase
+
+6. **Handle errors gracefully**
+   - If a component migration fails, document why
+   - Continue with other components
+   - Return to failed components after dependency switch
+   - Some issues may resolve once dependencies are updated
+
+7. **Verify after dependency switch**
+   - Only after dependencies are updated to v3
+   - Run typecheck/lint (do NOT build)
+   - Fix type/lint errors as they arise
+   - Don't proceed to styling until typecheck/lint passes
+
+## Common Scenarios
+
+### Large Project (100+ components)
+
+- Use smaller batch sizes (3-5 components)
+- Prioritize by dependency or frequency
+- Allow for multiple sessions
+- Create checkpoints between phases
+- Use "by-dependency" strategy
+- Document progress clearly
+
+### Small Project (\<20 components)
+
+- Can use larger batches (5-10 components)
+- May complete in fewer phases
+- Still verify incrementally (full migration approach)
+- Can use any strategy
+- Still need to migrate all code before switching deps
+
+### Mixed v2/v3 Usage (Full Migration)
+
+- **Not possible in full migration**: v2 and v3 cannot coexist in full migration approach
+- Must migrate all components before switching dependencies
+- Use feature branch to maintain working main branch
+- Complete migration in one go
+
+## Next Steps
+
+After completing migration:
+
+1. Remove v2 dependencies (already done in dependency switch)
+2. Switch from Migration MCP to `heroui-react` MCP for v3 development
+3. Update documentation references
+4. Run final verification
+5. Merge migration branch to main
+
+---
+
+<Callout type="info">
+  This agent migration guide is designed to work with the Migration MCP server. Ensure the MCP server is properly configured and tools are available before starting migration.
+</Callout>
diff --git a/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-incremental.mdx b/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-incremental.mdx
new file mode 100644
index 0000000..7f3efb7
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(workflows)/agent-guide-incremental.mdx
@@ -0,0 +1,258 @@
+---
+title: Agent Migration Guide - Incremental Migration with Coexistence
+description: Incremental coexistence migration guide for AI assistants helping migrate HeroUI v2 to v3
+index: false
+---
+
+## Overview
+
+This guide is designed for AI assistants (agents) helping users migrate from HeroUI v2 to v3 using **incremental coexistence migration**. This approach allows v2 and v3 components to work side-by-side, enabling component-by-component migration while keeping the project functional.
+
+<Callout type="info">
+  **Key Difference**: Unlike full migration, incremental coexistence migration allows the project to remain functional during migration. Both v2 and v3 components can coexist temporarily.
+</Callout>
+
+## Key Principles
+
+1. **Incremental Component Migration**: Migrate one component at a time, testing each before proceeding
+2. **Project Remains Functional**: Unlike full migration, the project should remain working throughout
+3. **Strategy Identification**: Determine which coexistence strategy the project uses (A: pnpm aliases or B: component packages)
+4. **Component-by-Component Testing**: Test each migrated component before moving to the next
+5. **CSS Conflict Management**: Monitor and resolve styling conflicts between v2 and v3 during coexistence
+6. **Removed Components**: v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User) can be left in place during coexistence. Do not migrate them unless the user explicitly asks to replace them.
+
+## Major Changes in v3
+
+<include>../index.mdx#major-changes</include>
+
+## Incremental Migration Setup
+
+For detailed setup and migration instructions, see the [Incremental Migration Guide](/docs/react/migration/incremental-migration). The guide covers:
+
+- Strategy selection (A: pnpm aliases or B: component packages)
+- Detailed setup for each strategy
+- CSS configuration for coexistence
+- Component-by-component migration process
+- CSS conflict handling
+- Completing the migration
+
+## Strategy Identification
+
+For projects using incremental coexistence strategies, agents should:
+
+1. **Identify the strategy**: Check if project uses pnpm aliases (Strategy A) or component packages (Strategy B)
+   - **Strategy A**: Look for aliases like `"@heroui-v3/react": "npm:@heroui/react@latest"` in package.json
+   - **Strategy B**: Look for component-specific packages like `@heroui/button`, `@heroui/card` alongside `@heroui/react`
+
+2. **Verify setup**: Ensure the coexistence setup is correct:
+   - Strategy A: Both `@heroui/react` (v2) and `@heroui-v3/react` (v3 alias) are installed
+   - Strategy B: `@heroui/react` (v3) and component packages like `@heroui/button` (v2) are installed
+   - CSS is configured for both versions (see CSS Configuration section)
+
+## Component-by-Component Migration Guidance
+
+### For Strategy A (pnpm aliases):
+
+1. **Identify component to migrate**
+   - Review the component migration reference table
+   - Use `get_component_migration_guides` MCP tool to fetch component-specific guide
+
+2. **Update imports**
+   - Change imports from `@heroui/react` to `@heroui-v3/react`
+   - Example: `import {Button} from "@heroui/react"` → `import {Button} from "@heroui-v3/react"`
+
+3. **Update component code**
+   - Follow component migration guide from `get_component_migration_guides` tool
+   - Update props, component structure, and API calls
+   - Replace hooks with compound components if needed
+
+4. **Test the migrated component**
+   - Verify component renders correctly
+   - Test functionality and interactions
+   - Check for styling conflicts
+
+5. **Document migration**
+   - Track which components have been migrated
+   - Note any issues or concerns
+
+### For Strategy B (component packages):
+
+1. **Identify component to migrate**
+   - Review the component migration reference table
+   - Use `get_component_migration_guides` MCP tool to fetch component-specific guide
+
+2. **Remove component package**
+   - Remove the v2 component package from dependencies (e.g., `@heroui/button`)
+   - Update package.json
+
+3. **Update imports**
+   - Change imports from component package to `@heroui/react` (v3)
+   - Example: `import {Card} from "@heroui/card"` → `import {Card} from "@heroui/react"`
+
+4. **Update component code**
+   - Follow component migration guide from `get_component_migration_guides` tool
+   - Update props, component structure, and API calls
+   - Replace hooks with compound components if needed
+
+5. **Test the migrated component**
+   - Verify component renders correctly
+   - Test functionality and interactions
+   - Check for styling conflicts
+
+6. **Document migration**
+   - Track which components have been migrated
+   - Note any issues or concerns
+
+### Handling Removed Components (No v3 Counterpart)
+
+When encountering v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User):
+
+- **Leave them in place** — do not attempt to migrate them unless the user explicitly requests removal
+- **If the user wants to remove them**: Use `get_component_migration_guides` (where available) or the [Component Migration Reference](/docs/react/migration#component-migration-reference) to fetch guides and help replace with native HTML or manual implementations
+
+## CSS Conflict Handling
+
+During coexistence, both v2 and v3 CSS systems will be loaded. Agents should:
+
+1. **Monitor for conflicts**
+   - Watch for styling inconsistencies
+   - Check if v2 and v3 styles are conflicting
+   - Verify both CSS imports are present and in correct order
+
+2. **Guide conflict resolution**
+   - Ensure CSS import order: `tailwindcss` first, then `@heroui/styles`
+   - Check Tailwind config has v2 plugin configured
+   - Verify v3 CSS is imported correctly
+
+3. **Test styling after each migration**
+   - Verify migrated components look correct
+   - Check for unexpected style overrides
+   - Ensure v2 components still styled correctly
+
+## Component Migration Reference
+
+<include>../index.mdx#step-6-component-migration-reference</include>
+
+Use the `get_component_migration_guides` MCP tool to fetch detailed guides for each component.
+
+## New Components in v3
+
+<include>../index.mdx#new-components-in-v3</include>
+
+## Completion Steps
+
+Once all components are migrated:
+
+1. **Remove v2 dependencies**
+   - Strategy A: Remove `@heroui/react`, `@heroui/theme`, and aliases
+   - Strategy B: Remove all remaining `@heroui/*` component packages
+   - If the project contains v2 removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User), inform the user they may ask to remove them later using the provided guides.
+
+2. **Update all imports**
+   - Strategy A: Change `@heroui-v3/react` → `@heroui/react`
+   - Strategy B: All imports should already be `@heroui/react` (v3)
+
+3. **Update CSS configuration**
+   - Remove v2 Tailwind plugin from config
+   - Keep only `@import "@heroui/styles";`
+   - Remove v2 CSS imports
+
+4. **Complete styling migration**
+   - Follow the styling migration guide
+   - Use `get_styling_migration_guide` MCP tool
+   - Update utility classes, color tokens, etc.
+
+## Differences from Full Migration
+
+**Key Differences:**
+
+- **Project State**: Project remains functional during migration (no broken state)
+- **Migration Pace**: Can migrate over extended period, component by component
+- **Testing**: Can test v3 components alongside v2 before full migration
+- **Branch Strategy**: Feature branch less critical (though still recommended)
+- **Dependency Management**: Both versions coexist temporarily
+- **CSS Handling**: Both CSS systems loaded during coexistence period
+
+**When to Use Incremental Coexistence:**
+
+- Large codebases that need gradual migration
+- Projects that must remain functional during migration
+- Teams that want to test v3 components incrementally
+- Projects already using component-specific packages (Strategy B)
+
+**When to Use Full Migration:**
+
+- Smaller projects that can migrate quickly
+- Projects where temporary broken state is acceptable
+- Teams that prefer all-at-once migration
+- Projects using unified `@heroui/react` package (Strategy A can work but full migration may be simpler)
+
+## Best Practices for Agents
+
+1. **Verify project remains functional**
+   - After each component migration, ensure project still works
+   - Test both migrated and non-migrated components
+   - Report any issues immediately
+
+2. **Guide component-by-component migration**
+   - Help migrate one component at a time
+   - Use `get_component_migration_guides` MCP tool for each component
+   - Test thoroughly before proceeding
+
+3. **Monitor CSS conflicts**
+   - Watch for styling issues between v2 and v3
+   - Guide resolution of conflicts
+   - Ensure CSS configuration is correct
+
+4. **Track migration progress**
+   - Keep a checklist of migrated components
+   - Document any issues or concerns
+   - Note which strategy is being used
+
+5. **Guide completion steps**
+   - Once all components migrated, guide removal of v2 dependencies
+   - Help update all imports to v3-only
+   - Guide styling migration completion
+
+## Common Scenarios
+
+### Large Project (100+ components)
+
+- Migrate components incrementally over time
+- Test each component thoroughly
+- Monitor for CSS conflicts
+- Can take weeks or months to complete
+
+### Small Project (\<20 components)
+
+- Can migrate more quickly
+- Still test each component
+- Less CSS conflict risk
+- May complete in days
+
+### Mixed Strategy Projects
+
+- Some projects may use Strategy A for some components, Strategy B for others
+- Guide appropriate import updates for each component
+- Ensure consistent approach where possible
+
+### Project Uses v2 Navbar (or Other Removed Components)
+
+- Leave in place — v2 Navbar and other removed components (Code, Image, Ripple, Snippet, Spacer, User) will continue to work during coexistence
+- Inform the user they can optionally remove them later with agent assistance and the [Component Migration Reference](/docs/react/migration#component-migration-reference) guides
+
+## Next Steps
+
+After completing migration:
+
+1. Remove v2 dependencies (already done in completion steps)
+2. Switch from Migration MCP to `heroui-react` MCP for v3 development
+3. Update documentation references
+4. Run final verification
+5. Complete styling migration
+
+---
+
+<Callout type="info">
+  This agent migration guide is designed to work with the Migration MCP server. Ensure the MCP server is properly configured and tools are available before starting migration.
+</Callout>
diff --git a/apps/docs/content/docs/en/react/migration/(workflows)/full-migration.mdx b/apps/docs/content/docs/en/react/migration/(workflows)/full-migration.mdx
new file mode 100644
index 0000000..b05ccbe
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(workflows)/full-migration.mdx
@@ -0,0 +1,509 @@
+---
+title: Full Migration
+description: Step-by-step guide for migrating HeroUI v2 to v3 using full migration approach
+---
+
+## Overview
+
+Full migration is a structured approach to migrating from HeroUI v2 to v3. This method involves migrating all component code first, then switching dependencies, ensuring a clean transition.
+
+**Important:** Full migration means the project will be broken during migration (v2 and v3 cannot coexist). Work in a feature branch to maintain a working main branch.
+
+### AI Assistant Resources
+
+AI assistants can help with migration. Use the [Migration MCP Server](/docs/react/migration/mcp-server) for tools and prompts, [Migration Agent Skills](/docs/react/migration/agent-skills) for skill-based knowledge, or [AGENTS.md for Migration](/docs/react/migration/agents-md) to download migration docs into your project.
+
+## Migration Workflow
+
+**IMPORTANT**: Since v2 and v3 cannot coexist, the migration happens in two main stages:
+
+1. **Preparation Stage**: Migrate all component code while still on v2 dependencies (code will be broken)
+2. **Switch Stage**: Update dependencies to v3 and fix any remaining issues
+
+**⚠️ CRITICAL: Don't build to check for errors during migration**
+
+- Use **typecheck** (e.g., `tsc --noEmit`) if available to check TypeScript errors
+- Use **lint** (e.g., `eslint`, `biome check`) if available to check code quality
+- **DO NOT** run build commands (e.g., `npm run build`, `next build`, `vite build`)
+- **DO NOT** attempt to start/run the project during migration
+
+## Step-by-Step Migration Guide
+
+<section id="step-1-update-dependencies">
+
+### Step 1: Update Dependencies
+
+#### Update React
+
+v3 requires React 19+. Update your React version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add react@^19.0.0 react-dom@^19.0.0
+    ```
+  </Tab>
+</Tabs>
+
+**Note**: These dependency updates can be done before switching HeroUI (won't break project). However, the HeroUI package switch should only happen AFTER all component code is migrated.
+
+#### Update HeroUI Packages
+
+**Important**: Do this AFTER migrating all component code. Remove v2 packages and install v3:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm uninstall @heroui/react @heroui/theme
+    npm install @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm remove @heroui/react @heroui/theme
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn remove @heroui/react @heroui/theme
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun remove @heroui/react @heroui/theme
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+#### Remove Framer Motion
+
+v3 no longer requires Framer Motion:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm uninstall framer-motion
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm remove framer-motion
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn remove framer-motion
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun remove framer-motion
+    ```
+  </Tab>
+</Tabs>
+
+#### Update Tailwind CSS
+
+Ensure you're using Tailwind CSS v4:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add tailwindcss@^4.0.0
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add tailwindcss@^4.0.0
+    ```
+  </Tab>
+</Tabs>
+
+</section>
+
+<section id="step-2-update-theming-configuration">
+
+### Step 2: Update Theming Configuration
+
+#### Remove Tailwind Plugin Configuration
+
+**v2 Configuration:**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
+  ],
+  plugins: [heroui()],
+  // ... other config
+};
+```
+
+**v3 Configuration:**
+
+Remove the `heroui()` plugin from your Tailwind config. If you only used Tailwind for HeroUI and have no other customizations, you can remove `tailwind.config.js` entirely. Otherwise, keep the file but remove the HeroUI plugin configuration.
+
+#### Update CSS Imports
+
+**v2 CSS:**
+
+```css
+/* globals.css or main.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**v3 CSS:**
+
+```css
+/* globals.css or main.css */
+@import "tailwindcss";
+@import "@heroui/styles"; /* [!code highlight]*/
+```
+
+<Callout type="warning">
+  Import order matters! Always import `tailwindcss` before `@heroui/styles`.
+</Callout>
+
+#### Remove Theme Plugin File
+
+If you created a `hero.ts` file for v2, you can remove it:
+
+```bash
+rm hero.ts
+```
+
+</section>
+
+<section id="step-3-remove-herouiprovider">
+
+### Step 3: Remove HeroUIProvider
+
+v3 does not require a Provider component. Remove it from your application root.
+
+**v2 Code:**
+
+```tsx
+// app.tsx or App.tsx
+import {HeroUIProvider} from "@heroui/react";
+
+function App() {
+  return (
+    <HeroUIProvider>
+      <YourApplication />
+    </HeroUIProvider>
+  );
+}
+```
+
+**v3 Code:**
+
+```tsx
+// app.tsx or App.tsx
+function App() {
+  return <YourApplication />;
+}
+```
+
+**If you were using Provider props:**
+
+If you were using Provider props like `navigate`, `useHref`, `locale`, `disableAnimation`, etc., you'll need to handle these differently:
+
+- **Router integration**: Use React Router or your routing library directly
+- **Locale**: Use React Aria's `I18nProvider` directly if needed
+- **Animation**: See the Animation Changes section below
+
+#### Animation Changes
+
+v3 removes the Framer Motion dependency and handles animations differently:
+
+- **CSS-based animations**: v3 uses native CSS animations and transitions instead of JavaScript-based animations
+- **Better performance**: CSS animations provide better performance and smoother animations
+- **No global disable**: Unlike v2's Provider `disableAnimation` prop, there's no global animation toggle in v3
+- **Per-component control**: Control animations through CSS or component-specific props where available
+- **Custom animations**: Use standard CSS `@keyframes` and transition properties for custom animations
+
+</section>
+
+<section id="step-4-replace-removed-hooks">
+
+### Step 4: Replace Removed Hooks
+
+HeroUI v2 provided component hooks (like `useSwitch`, `useInput`, `useCheckbox`, etc.) and utility hooks like `useDisclosure`. HeroUI v3 removes most component hooks in favor of compound components, and replaces `useDisclosure` with `useOverlayState`.
+
+See the comprehensive [Hooks Migration Guide](/docs/react/migration/hooks) for:
+- Component hooks removal and migration to compound components
+- `useDisclosure` → `useOverlayState` migration
+- Migration strategies and examples
+
+</section>
+
+<section id="step-5-update-component-imports">
+
+### Step 5: Update Component Imports
+
+All components are now imported from a single package:
+
+**v2 Imports:**
+
+```tsx
+// Individual packages (if used)
+import {Button} from "@heroui/button";
+import {Card} from "@heroui/card";
+
+// Or from main package
+import {Button, Card} from "@heroui/react";
+```
+
+**v3 Imports:**
+
+```tsx
+// All components from single package
+import {Button, Card} from "@heroui/react";
+```
+
+#### TypeScript Considerations
+
+If you're using TypeScript, be aware of type changes in v3:
+
+```tsx
+// Import types alongside components
+import {Button, type ButtonProps} from "@heroui/react";
+
+// Compound component types are properly exported
+import {Checkbox, type CheckboxProps} from "@heroui/react";
+
+// Type names may have changed - check component documentation
+type MyButtonProps = ButtonProps & {
+  customProp?: string;
+};
+```
+
+**Common type changes:**
+- Component prop interfaces may have different names or properties
+- Compound component parts have their own type exports
+- Ref types updated to match React 19 patterns
+
+</section>
+
+<section id="step-6-component-migration">
+
+### Step 6: Component Migration
+
+Use the [Component Migration Reference](/docs/react/migration#component-migration-reference) table to find migration guides for each component. Migrate components according to their specific guides.
+
+**Key points:**
+- Review individual component migration guides as needed
+- Migrate component APIs, props, and structure
+- Update compound component patterns (Checkbox, Radio, Switch, Card, Modal, etc.)
+- Update group components (ButtonGroup, CheckboxGroup, RadioGroup)
+- Handle removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User) - replace with HTML elements
+- Handle in-progress/planned components - replace with HTML elements until v3 components are available
+
+</section>
+
+<section id="step-7-update-custom-theme-overrides">
+
+### Step 7: Update Custom Theme Overrides
+
+If you had custom theme overrides in v2, you'll need to update them for v3's CSS-based theming system.
+
+**v2 Theme Customization:**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [
+    heroui({
+      themes: {
+        light: {
+          colors: {
+            primary: {
+              // custom colors
+            },
+          },
+        },
+      },
+    }),
+  ],
+};
+```
+
+**v3 Theme Customization:**
+
+v3 uses CSS variables. Override them in your CSS:
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+
+:root {
+  --color-primary: /* your color */;
+  /* other CSS variables */
+}
+```
+
+Check the [Theming documentation](/docs/react/getting-started/handbook/theming) for available CSS variables.
+
+This is a good point to pause and verify component functionality before proceeding to styling migration.
+
+</section>
+
+<section id="step-8-hooks-migration">
+
+### Step 8: Hooks Migration
+
+After component migration is complete, ensure all hooks have been migrated:
+
+1. **Replace component hooks**: Replace hooks like `useSwitch`, `useInput`, `useCheckbox`, etc. with compound components
+2. **Migrate useDisclosure**: Replace `useDisclosure` with `useOverlayState` for overlay state management
+3. **Reference hooks guide**: See the [Hooks Migration Guide](/docs/react/migration/hooks) for detailed migration instructions and examples
+
+</section>
+
+<section id="step-9-styling-migration">
+
+### Step 9: Styling Migration
+
+After hooks migration is complete, proceed with styling changes. This is a separate step to ensure component functionality is verified before addressing visual changes.
+
+**Styling Migration Guide:**
+
+See the comprehensive [Styling Migration Guide](/docs/react/migration/styling) for:
+
+- Utility class changes (`text-tiny` → `text-xs`, `rounded-small` → `rounded-sm`, etc.)
+- Color token updates (`bg-primary` → `bg-accent`, `bg-content1` → `bg-surface`, etc.)
+- Component styling differences (sizes, spacing, border radius)
+- CSS variable changes
+- Visual differences and alignment changes
+
+**Key Styling Changes:**
+
+- **Utility Classes**: Custom utilities replaced with standard Tailwind classes
+- **Color Tokens**: `primary` → `accent`, `secondary` removed, `content1-4` → `surface`/`overlay`
+- **Numbered Scales**: Color scales like `primary-50`, `primary-100` removed
+- **Border Radius**: Default values changed (smaller in v3)
+- **Component Styles**: Updated default sizes, padding, and spacing
+
+**Migration Checklist:**
+
+- Review [Styling Migration Guide](/docs/react/migration/styling)
+- Update utility classes (`text-tiny` → `text-xs`, etc.)
+- Update color tokens (`bg-primary` → `bg-accent`, etc.)
+- Update content colors (`bg-content1` → `bg-surface` or `bg-overlay`)
+- Update numbered color scales (`bg-primary-50` → `bg-accent-soft`)
+- Review component styling changes (sizes, spacing, border radius)
+- Test visual appearance and adjust as needed
+
+</section>
+
+<section id="step-10-testing">
+
+### Step 10: Testing
+
+After migration, thoroughly test your application:
+
+1. **Visual Testing**: Check all components render correctly
+2. **Functionality**: Test all interactions and behaviors
+3. **Accessibility**: Verify keyboard navigation and screen reader support
+4. **Responsive Design**: Test on different screen sizes
+5. **Performance**: Check bundle size and runtime performance
+
+</section>
+
+## Migration Checklist
+
+Use this checklist to track your full migration progress:
+
+### Dependencies
+- Update React to v19+
+- Update HeroUI packages to v3 (after component migration)
+- Remove Framer Motion
+- Update Tailwind CSS to v4
+
+### Configuration
+- Remove `heroui()` plugin from Tailwind config
+- Update CSS imports
+- Remove `hero.ts` file (if exists)
+
+### Application Code - Component Migration
+- Remove `HeroUIProvider` wrapper
+- Handle Provider props migration (router, locale, animations)
+- Update all component imports to `@heroui/react`
+- Migrate renamed components (Divider → Separator, Autocomplete → Combobox, NumberInput → NumberField)
+- Update compound component patterns (Checkbox, Radio, Switch, Card, Modal, etc.)
+- Update group components (ButtonGroup, CheckboxGroup, RadioGroup)
+- Update TypeScript type references (if using component types)
+- Handle removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User) - replace with HTML elements
+- Handle in-progress/planned components - replace with HTML elements until v3 components are available
+- Consider using `asChild` prop for flexible composition
+- **Verify component functionality before proceeding to hooks migration**
+
+### Application Code - Hooks Migration
+- Review [Hooks Migration Guide](/docs/react/migration/hooks)
+- Replace component hooks (`useSwitch`, `useInput`, `useCheckbox`, etc.) with compound components
+- Replace `useDisclosure` with `useOverlayState` for overlay state management
+- Update all hook usages according to migration guide
+- **Verify hooks migration before proceeding to styling migration**
+
+### Application Code - Styling Migration
+- Review [Styling Migration Guide](/docs/react/migration/styling)
+- Update utility classes (`text-tiny` → `text-xs`, `rounded-small` → `rounded-sm`, etc.)
+- Update color tokens (`bg-primary` → `bg-accent`, `bg-secondary` → `bg-default`, etc.)
+- Update content colors (`bg-content1` → `bg-surface` or `bg-overlay`)
+- Update numbered color scales (`bg-primary-50` → `bg-accent-soft`, etc.)
+- Update transition utilities (`.transition-background` → `transition-colors`, etc.)
+- Review component styling changes (sizes, spacing, border radius)
+- Update custom theme overrides to CSS variables
+- Test visual appearance and adjust as needed
+
+### Testing
+- Visual regression testing
+- Functionality testing
+- Accessibility testing
+- Performance testing
+
+## Next Steps
+
+After completing the full migration:
+
+1. Review the [v3 component documentation](/docs/react/components)
+2. Explore new components available in v3
+3. Check out the [styling guide](/docs/react/getting-started/handbook/styling)
+4. Learn about [composition patterns](/docs/react/getting-started/handbook/composition)
diff --git a/apps/docs/content/docs/en/react/migration/(workflows)/incremental-migration.mdx b/apps/docs/content/docs/en/react/migration/(workflows)/incremental-migration.mdx
new file mode 100644
index 0000000..74b1613
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/(workflows)/incremental-migration.mdx
@@ -0,0 +1,292 @@
+---
+title: Incremental Migration
+description: Step-by-step guide for migrating HeroUI v2 to v3 incrementally while keeping both versions working side-by-side
+---
+
+## Overview
+
+Incremental migration with coexistence allows you to migrate from HeroUI v2 to v3 component-by-component while keeping your project functional throughout the migration process. This approach uses special setup strategies to allow both v2 and v3 components to work side-by-side.
+
+### AI Assistant Resources
+
+AI assistants can help with migration. Use the [Migration MCP Server](/docs/react/migration/mcp-server) for tools and prompts, [Migration Agent Skills](/docs/react/migration/agent-skills) for skill-based knowledge, or [AGENTS.md for Migration](/docs/react/migration/agents-md) to download migration docs into your project.
+
+### Limitations and Considerations
+
+Before choosing this approach, be aware of:
+
+- **Bundle Size**: Both versions will be included during migration, increasing bundle size
+- **Styling Conflicts**: v2 and v3 styles may conflict; test thoroughly
+- **Type Conflicts**: TypeScript may show conflicts if both versions are imported in the same file
+- **Provider**: v2 requires `HeroUIProvider`, v3 doesn't - you may need conditional provider wrapping
+- **React Version**: v3 requires React 19+, v2 supports React 18+ - ensure React 19 is installed
+- **Setup Complexity**: Requires more complex initial setup compared to full migration
+
+### Components Without v3 Counterparts
+
+Since v2 and v3 can coexist, v2 components that have no v3 counterpart can remain in your project. These components will continue to work during migration:
+
+- **Code**, **Image**, **Navbar**, **Ripple**, **Snippet**, **Spacer**, **User**
+
+You do not need to replace them to complete the migration. If you prefer to remove them and use native HTML or manual implementations instead, you may ask your agent to help using the [Component Migration Reference](/docs/react/migration#component-migration-reference) guides.
+
+## Strategy Selection
+
+Choose your strategy based on how you currently import v2 components:
+
+- **Using `@heroui/react`**: Use Strategy A (pnpm aliases)
+- **Using component packages** (`@heroui/button`, `@heroui/card`, etc.): Use Strategy B (component packages)
+
+## Strategy A: Using pnpm Aliases
+
+This strategy uses pnpm package aliases to install v3 packages under different names, allowing both versions to coexist.
+
+### Setup
+
+1. Install v3 packages with aliases:
+
+```json
+{
+  "dependencies": {
+    "@heroui/react": "2.8.6",
+    "@heroui/theme": "2.4.24",
+    "@heroui-v3/react": "npm:@heroui/react@latest",
+    "@heroui-v3/styles": "npm:@heroui/styles@latest"
+  }
+}
+```
+
+2. Import v2 components from `@heroui/react`:
+
+```tsx
+import {Button} from "@heroui/react"; // v2
+```
+
+3. Import v3 components from `@heroui-v3/react`:
+
+```tsx
+import {Button} from "@heroui-v3/react"; // v3
+```
+
+### Migration Process
+
+1. **Migrate one component at a time:**
+   - Update imports to use `@heroui-v3/react`
+   - Update component code to v3 API
+   - Test the migrated component
+   - Verify styling looks correct
+   - For v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User), leave them in place. They will continue to work during coexistence.
+
+2. **Continue until all components are migrated**
+   - Track which components have been migrated
+   - Test each migrated component thoroughly
+   - If you want to remove v2 removed components later, use the [Component Migration Reference](/docs/react/migration#component-migration-reference) guides and ask your agent to help replace them with native HTML or manual implementations.
+
+3. **Once all components are migrated, switch to v3-only:**
+   - Remove v2 dependencies (`@heroui/react`, `@heroui/theme`)
+   - Remove aliases
+   - Update all imports to `@heroui/react` (remove `-v3` suffix)
+   - Complete styling migration
+
+### Considerations
+
+- Both CSS systems will be loaded (v2 via Tailwind plugin, v3 via CSS import)
+- You'll need both Tailwind configs temporarily
+- Bundle size will be larger during migration
+- Some styling conflicts may occur
+
+## Strategy B: Using Component Packages
+
+This strategy uses v2's component-specific packages alongside v3's unified package.
+
+### Setup
+
+1. Install v3 main package and v2 component packages:
+
+```json
+{
+  "dependencies": {
+    "@heroui/react": "latest", // v3
+    "@heroui/styles": "latest", // v3
+    "@heroui/button": "2.8.6", // v2
+    "@heroui/card": "2.8.6", // v2
+    // ... other v2 component packages as needed
+  }
+}
+```
+
+2. Import v3 components from `@heroui/react`:
+
+```tsx
+import {Button} from "@heroui/react"; // v3
+```
+
+3. Import v2 components from component packages:
+
+```tsx
+import {Card} from "@heroui/card"; // v2
+```
+
+### Migration Process
+
+1. **Install v3 packages** (`@heroui/react`, `@heroui/styles`)
+2. **Install v2 component packages** for components not yet migrated
+3. **Migrate one component at a time:**
+   - Remove the v2 component package from dependencies
+   - Update imports to use `@heroui/react` (v3)
+   - Update component code to v3 API
+   - Test the migrated component
+   - For v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User), leave them in place. They will continue to work during coexistence.
+4. **Continue until all components are migrated**
+   - If you want to remove v2 removed components later, use the [Component Migration Reference](/docs/react/migration#component-migration-reference) guides and ask your agent to help replace them with native HTML or manual implementations.
+5. **Remove remaining v2 component packages**
+6. **Complete styling migration**
+
+### Considerations
+
+- Only works if your project uses component-specific packages
+- Requires managing multiple package dependencies
+- v3 doesn't have component packages, so this is a one-way migration path
+
+## CSS Configuration for Coexistence
+
+During coexistence, you'll need both CSS systems:
+
+```css
+/* globals.css */
+@import "tailwindcss";
+
+/* v2 styles via Tailwind plugin */
+/* (configured in tailwind.config.js) */
+
+/* v3 styles */
+@import "@heroui/styles";
+```
+
+<Callout type="warning">
+  **Important:** Import order matters. Import `tailwindcss` first, then `@heroui/styles`.
+</Callout>
+
+## Tailwind Configuration
+
+You'll need both Tailwind configs temporarily:
+
+**v2 Config (tailwind.config.js):**
+
+```js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [heroui()],
+  // ... other config
+};
+```
+
+**v3 Config:** No plugin needed, but ensure Tailwind v4 is installed.
+
+## Component Migration
+
+For each component you migrate:
+
+1. **Review the component migration guide**
+   - Use the [Component Migration Reference](/docs/react/migration#component-migration-reference) table
+   - Check component-specific migration guides
+
+2. **Update imports**
+   - Strategy A: Change `@heroui/react` → `@heroui-v3/react`
+   - Strategy B: Change component package → `@heroui/react`
+
+3. **Update component code**
+   - Follow component migration guide
+   - Update props, component structure, and API calls
+   - Replace hooks with compound components if needed
+
+4. **Test the migrated component**
+   - Verify component renders correctly
+   - Test functionality and interactions
+   - Check for styling conflicts
+   - Ensure v2 components still styled correctly
+
+5. **Document migration**
+   - Track which components have been migrated
+   - Note any issues or concerns
+
+## CSS Conflict Handling
+
+During coexistence, both v2 and v3 CSS systems will be loaded. Monitor for conflicts:
+
+1. **Watch for styling inconsistencies**
+   - Check if v2 and v3 styles are conflicting
+   - Verify both CSS imports are present and in correct order
+
+2. **Guide conflict resolution**
+   - Ensure CSS import order: `tailwindcss` first, then `@heroui/styles`
+   - Check Tailwind config has v2 plugin configured
+   - Verify v3 CSS is imported correctly
+
+3. **Test styling after each migration**
+   - Verify migrated components look correct
+   - Check for unexpected style overrides
+   - Ensure v2 components still styled correctly
+
+## Completing the Migration
+
+Once all components are migrated:
+
+1. **Remove v2 dependencies:**
+   - Remove `@heroui/react` and `@heroui/theme` (Strategy A)
+   - Remove all `@heroui/*` component packages (Strategy B)
+   - Remove aliases (Strategy A)
+   - If you left v2 removed components in place (Code, Image, Navbar, Ripple, Snippet, Spacer, User), you have two options: (1) Replace them per the migration guides before removing v2 dependencies, or (2) Keep v2 dependencies until you are ready to replace them. You may ask an agent to help remove them using the provided guides.
+
+2. **Update all imports:**
+   - Change `@heroui-v3/react` → `@heroui/react` (Strategy A)
+   - Change component package imports → `@heroui/react` (Strategy B)
+
+3. **Update CSS:**
+   - Remove v2 Tailwind plugin from config
+   - Keep only `@import "@heroui/styles";`
+
+4. **Complete styling migration:**
+   - Follow the [Styling Migration Guide](/docs/react/migration/styling)
+   - Update utility classes, color tokens, etc.
+
+## Migration Checklist for Coexistence
+
+Use this checklist to track your incremental migration progress:
+
+### Initial Setup
+- Choose strategy (A: aliases or B: component packages)
+- Install v3 packages (with aliases or directly)
+- Configure CSS for both versions
+- Ensure React 19+ is installed
+- Set up both Tailwind configs temporarily
+
+### Component Migration (Repeat for each component)
+- Review component migration guide
+- Update imports (Strategy A or B)
+- Update component code to v3 API
+- Test the migrated component
+- Check for styling conflicts
+- Document migration progress
+- Identify v2 removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User) — leave in place or replace per guides
+
+### Completion
+- Migrate all components
+- Optional: Replace removed components using migration guides before removing v2 deps, or remove v2 deps only after all removed components are replaced
+- Remove v2 dependencies
+- Remove aliases (Strategy A)
+- Update all imports to v3-only
+- Remove v2 Tailwind plugin
+- Update CSS to v3-only
+- Complete styling migration
+- Test entire application
+
+## Next Steps
+
+After completing the incremental migration:
+
+1. Review the [v3 component documentation](/docs/react/components)
+2. Explore new components available in v3
+3. Check out the [styling guide](/docs/react/getting-started/handbook/styling)
+4. Learn about [composition patterns](/docs/react/getting-started/handbook/composition)
diff --git a/apps/docs/content/docs/en/react/migration/agent-index.mdx b/apps/docs/content/docs/en/react/migration/agent-index.mdx
new file mode 100644
index 0000000..66aa34e
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/agent-index.mdx
@@ -0,0 +1,20 @@
+---
+title: Migration (for AI assistants)
+description: Entry point for AI assistants helping migrate HeroUI v2 to v3
+index: false
+---
+
+For AI assistants: use this as the entry point when helping migrate HeroUI v2 → v3.
+
+## Entry
+
+Choose a migration strategy:
+
+- **Full migration** (project will be broken during migration) → read `(workflows)/agent-guide-full.mdx`.
+- **Incremental** (v2 and v3 coexist) → read `(workflows)/agent-guide-incremental.mdx`.
+
+## Reference in this bundle
+
+- **Cross-cutting guides:** `hooks.mdx`, `styling.mdx`.
+- The workflow guides above already inline the "major changes", "key API changes", component reference table, and "new components" sections.
+- **Per-component guides:** `(components)/<component>.mdx` (e.g. `(components)/button.mdx`, `(components)/select.mdx`). Use the component reference table in the workflow guides to find the right file.
diff --git a/apps/docs/content/docs/en/react/migration/hooks.mdx b/apps/docs/content/docs/en/react/migration/hooks.mdx
new file mode 100644
index 0000000..3f90f81
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/hooks.mdx
@@ -0,0 +1,282 @@
+---
+title: Hooks
+description: Migration guide for HeroUI hooks from v2 to v3
+---
+
+<Callout type="info">
+  Refer to the [v3 component documentation](/docs/components-list) for complete API reference. This guide focuses on migrating hooks from HeroUI v2.
+</Callout>
+
+## Overview
+
+HeroUI v3 removes most component hooks that existed in v2, replacing them with compound components and a new hook for overlay state management. This guide covers:
+
+- Component hooks removal (useSwitch, useInput, useCheckbox, etc.)
+- useDisclosure → useOverlayState migration
+- Migration strategies and examples
+
+## Component Hooks Removal
+
+HeroUI v2 provided component hooks (like `useSwitch`, `useInput`, `useCheckbox`, etc.) that returned prop getters (`getBaseProps`, `getWrapperProps`, `getThumbProps`, etc.) to customize component structure when users couldn't directly modify inner child components. HeroUI v3 solves this with compound components, eliminating the need for hooks.
+
+### Why Hooks Existed in v2
+
+In v2, components had fixed internal structures. To customize these structures, users needed to use hooks that provided prop getters. For example, `useSwitch` returned `getBaseProps()`, `getWrapperProps()`, `getThumbProps()`, etc., which users could spread onto custom elements to build their own Switch structure.
+
+### v3 Solution: Compound Components
+
+v3 uses compound component patterns that give you direct access to component parts. Instead of using hooks with prop getters, you compose components directly using subcomponents like `Switch.Control`, `Switch.Thumb`, `Checkbox.Control`, `Checkbox.Indicator`, etc.
+
+### Migration Strategy
+
+1. **Identify hook usage**: Search your codebase for imports from `@heroui/react` that include hook names (`useSwitch`, `useInput`, `useCheckbox`, `useRadio`, etc.)
+2. **Replace with compound components**: Instead of using hooks with prop getters, use the compound component pattern
+3. **Preserve original structure**: When migrating, try to keep the same component structure you had with hooks. For example:
+   - If you used `useSwitch` to create a switch **without** a thumb, don't add `Switch.Thumb` in v3
+   - If you used `useCheckbox` to create a checkbox **without** an indicator, don't add `Checkbox.Indicator` in v3
+   - Only include the subcomponents that were actually used in your hook-based implementation
+4. **Reference component guides**: Check individual component migration guides for specific examples
+
+### Key Differences
+
+- **v2**: Hooks provided prop getters to customize fixed component structures
+- **v3**: Compound components allow direct composition of component parts
+
+### Preserving Structure Example
+
+**v2: Switch without thumb**
+```tsx
+import { useSwitch } from "@heroui/react";
+
+function CustomSwitch() {
+  const { getBaseProps } = useSwitch();
+  
+  return (
+    <div {...getBaseProps()}>
+      {/* No thumb element */}
+    </div>
+  );
+}
+```
+
+**v3: Equivalent structure**
+```tsx
+import { Switch } from "@heroui/react";
+
+function CustomSwitch() {
+  return (
+    <Switch.Control>
+      {/* No Switch.Thumb - preserving the original structure */}
+    </Switch.Control>
+  );
+}
+```
+
+For detailed migration examples for specific components, see the individual component migration guides.
+
+## useDisclosure → useOverlayState
+
+The `useDisclosure` hook from v2 has been replaced with `useOverlayState` in v3. This hook manages open/close state for modals, popovers, and other overlay components.
+
+### v2: useDisclosure
+
+**API:**
+```tsx
+const {isOpen, onOpen, onClose, onOpenChange, isControlled, getButtonProps, getDisclosureProps} = useDisclosure({
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onClose?(): void;
+  onOpen?(): void;
+  onChange?(isOpen: boolean | undefined): void;
+  id?: string;
+});
+```
+
+**Example:**
+```tsx
+import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@heroui/react";
+
+export default function App() {
+  const {isOpen, onOpen, onOpenChange} = useDisclosure();
+
+  return (
+    <>
+      <Button onPress={onOpen}>Open Modal</Button>
+      <Modal isOpen={isOpen} onOpenChange={onOpenChange}>
+        <ModalContent>
+          <ModalHeader>Title</ModalHeader>
+          <ModalBody>Content</ModalBody>
+          <ModalFooter>
+            <Button onPress={onOpenChange}>Close</Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+### v3: useOverlayState
+
+**API:**
+```tsx
+const state = useOverlayState({
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (isOpen: boolean) => void;
+});
+
+// Returns:
+// {
+//   isOpen: boolean;
+//   open(): void;
+//   close(): void;
+//   toggle(): void;
+//   setOpen(isOpen: boolean): void;
+// }
+```
+
+**Example:**
+```tsx
+import { Modal, Button, useOverlayState } from "@heroui/react";
+
+export default function App() {
+  const state = useOverlayState();
+
+  return (
+    <Modal>
+      <Button onPress={state.open}>Open Modal</Button>
+      <Modal.Container isOpen={state.isOpen} onOpenChange={state.setOpen}>
+        <Modal.Dialog>
+          {({close}) => (
+            <>
+              <Modal.Header>
+                <Modal.Heading>Title</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>Content</Modal.Body>
+              <Modal.Footer>
+                <Button onPress={close}>Close</Button>
+              </Modal.Footer>
+            </>
+          )}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal>
+  );
+}
+```
+
+### Migration Guide
+
+#### Basic Migration
+
+**v2:**
+```tsx
+const {isOpen, onOpen, onClose, onOpenChange} = useDisclosure();
+```
+
+**v3:**
+```tsx
+const state = useOverlayState();
+// Use state.open(), state.close(), state.toggle(), state.setOpen(boolean)
+```
+
+#### Controlled State
+
+**v2:**
+```tsx
+const {isOpen, onOpenChange} = useDisclosure({
+  isOpen: controlledIsOpen,
+  onChange: (isOpen) => setControlledIsOpen(isOpen)
+});
+```
+
+**v3:**
+```tsx
+const state = useOverlayState({
+  isOpen: controlledIsOpen,
+  onOpenChange: setControlledIsOpen
+});
+```
+
+#### Uncontrolled State
+
+**v2:**
+```tsx
+const {isOpen, onOpen, onClose} = useDisclosure({
+  defaultOpen: false
+});
+```
+
+**v3:**
+```tsx
+const state = useOverlayState({
+  defaultOpen: false
+});
+// Use state.open(), state.close(), state.toggle()
+```
+
+### API Differences
+
+| v2 (useDisclosure) | v3 (useOverlayState) | Notes |
+|-------------------|---------------------|-------|
+| `isOpen` | `isOpen` | Same |
+| `onOpen()` | `open()` | Renamed method |
+| `onClose()` | `close()` | Renamed method |
+| `onOpenChange()` | `toggle()` | New method for toggling |
+| `onOpenChange` (prop) | `setOpen(boolean)` | Different API |
+| `isControlled` | - | Removed (handled internally) |
+| `getButtonProps()` | - | Removed (use compound components) |
+| `getDisclosureProps()` | - | Removed (use compound components) |
+
+### Benefits of useOverlayState
+
+- **Cleaner API**: Dedicated methods (`open()`, `close()`, `toggle()`) instead of callbacks
+- **Simpler state management**: Works seamlessly with both controlled and uncontrolled patterns
+- **Better TypeScript support**: Improved type inference and autocomplete
+- **Consistent with React Aria**: Aligns with React Aria Components patterns
+
+### Alternative: useState
+
+For simple cases, you can also use React's `useState` directly:
+
+```tsx
+import { useState } from "react";
+import { Modal, Button } from "@heroui/react";
+
+export default function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Modal>
+      <Button onPress={() => setIsOpen(true)}>Open</Button>
+      <Modal.Container isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Modal.Dialog>
+          {/* content */}
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal>
+  );
+}
+```
+
+However, `useOverlayState` provides a cleaner API with dedicated methods for common operations.
+
+## Removed Hooks
+
+The following hooks from v2 have been removed in v3:
+
+- **useDraggable**: Removed
+- **useClipboard**: Removed
+- **usePagination**: Removed
+- **useToast**: Removed
+
+## Summary
+
+- **Component hooks** (`useSwitch`, `useInput`, etc.) → Use **compound components** instead
+- **useDisclosure** → Use **useOverlayState** for overlay state management
+- **useOverlayState** provides a cleaner API with `open()`, `close()`, `toggle()`, and `setOpen()` methods
+- **Removed hooks**: `useDraggable`, `useClipboard`, `usePagination`, `useToast` are no longer available
+- For simple cases, `useState` can be used directly, but `useOverlayState` offers better ergonomics
+
+For component-specific hook migration examples, refer to the individual component migration guides.
diff --git a/apps/docs/content/docs/en/react/migration/index.mdx b/apps/docs/content/docs/en/react/migration/index.mdx
new file mode 100644
index 0000000..f78b133
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/index.mdx
@@ -0,0 +1,198 @@
+---
+title: Migration
+description: Complete guide to migrate your HeroUI v2 application to v3
+index: true
+---
+
+## For AI Assistants
+
+Below are three approaches for AI assistants to access migration documentation. ***We recommend using the HeroUI Migration MCP server*** and leveraging its prompts and tools, but all options provide agents with the complete documentation.
+
+| Feature | MCP Server | Agent Skills | AGENTS.md |
+|---------|-----------|--------------|-----------|
+| **Data source** | Remote endpoints | Remote endpoints | Local files |
+| **Access method** | MCP tools | Script files | Local file reads |
+| **Setup** | MCP config | Install command | `heroui-cli` command |
+| **Updates** | Real-time | Real-time | Manual |
+| **Offline** | ❌ | ❌ | ✅ |
+| **Tools** | MCP tools + prompts | Scripts | ❌ |
+| **Guide** | [MCP Server →](/docs/react/migration/mcp-server) | [Agent Skills →](/docs/react/migration/agent-skills) | [AGENTS.md →](/docs/react/migration/agents-md) |
+
+## Major Changes
+
+<section id="major-changes">
+
+- **Dependencies**: Update React to v19+, HeroUI packages to v3, Tailwind CSS to v4, remove Framer Motion
+- **No Provider Required**: v3 removes the need for `HeroUIProvider`
+- **Component API Updates**: Many components use React Aria Components patterns
+- **Compound Components**: New compound component patterns for better customization. See individual component guides for details.
+- **Hooks Removed**: v2 component hooks like `useSwitch` or `useInput` are removed - use compound components instead. `useDisclosure` is replaced with `useOverlayState`. See the [Hooks Migration Guide](/docs/react/migration/hooks) for details.
+- **Configuration**: Remove `heroui()` plugin from Tailwind config, update CSS imports, remove `hero.ts` file
+- **Item identity**: Collection items (Dropdown, Listbox, Select, Accordion, etc.) now use `id` and `textValue` in v3; keep React's `key` for lists.
+
+</section>
+
+### Item identity and accessibility (key, id, textValue)
+
+In v2, collection components (Dropdown, Listbox, Select, Accordion, etc.) used **React's `key`** as the item identity. The same value drove both React's list reconciliation and the component's selection/expand state. In v3, which uses React Aria Components, those roles are split:
+
+- **`id`** — v3 uses an explicit **`id`** prop on each item for selection state, focus, and callbacks (e.g. `selectedKeys`, `expandedKeys`, `onSelectionChange`). Use the same (or equivalent) value you used for `key` in v2 so that state and callbacks continue to refer to the correct item.
+- **`textValue`** — v3 requires **`textValue`** on items when the visible content is not plain text (e.g. when using `Label`, icons, or `Description`). It is used for screen reader announcements and type-ahead.
+- **`key`** — **Keep using React's `key`** on list items. It is still required for React's reconciliation and is independent of `id`.
+
+When migrating: add `id` (and `textValue` where needed) for v3's API, but keep `key` for React.
+
+## Migration Strategies
+
+HeroUI v2 and v3 cannot coexist in the same project without special setup. You have two migration approaches to choose from:
+
+### Full Migration
+
+**Best for:** Projects that can dedicate focused time to complete migration in one go.
+
+**How it works:**
+- Migrate all component code first (project will be broken during this phase)
+- Switch dependencies to v3
+- Complete styling migration
+
+**Advantages:**
+- Simpler setup - no complex coexistence configuration
+- Cleaner transition - only one version active at a time
+- Supported by Migration MCP prompts
+
+**Disadvantages:**
+- Project is broken during migration
+- All components should be migrated before switching dependencies
+
+**Get started:** [Full Migration Guide](/docs/react/migration/full-migration)
+
+### Incremental Migration
+
+**Best for:** Projects that need to stay functional during migration, teams migrating gradually over time, large codebases migrating feature-by-feature.
+
+**How it works:**
+- Set up coexistence using pnpm aliases or component packages
+- Migrate components one-by-one while keeping project functional
+- Complete migration and remove v2 dependencies
+
+**Advantages:**
+- Project remains functional during migration
+- Can migrate gradually over time
+- Can test v3 components alongside v2
+
+**Disadvantages:**
+- More complex initial setup
+- Potential styling conflicts
+- Requires managing two versions simultaneously
+
+**Get started:** [Incremental Migration Guide](/docs/react/migration/incremental-migration)
+
+## Component Migration Reference
+
+<section id="step-6-component-migration-reference">
+
+Use the table below to quickly find migration guidance for each component. Use the link in the "Migration Guide" column to jump to detailed migration instructions.
+
+<Callout>
+  **Component Development Status**: Components marked with 🔄 In Progress or 📋 Planned are still being developed. Check the [Roadmap](https://herouiv3.featurebase.app/roadmap) for the task status. Guides for these components will be available once development is finished.
+</Callout>
+
+| v2 Component | v3 Component | Status | Migration Guide |
+|-------------|--------------|--------|-----------------|
+| Accordion | Accordion | ✅ Available | [View guide →](/docs/react/migration/accordion) |
+| Alert | Alert | ✅ Available | [View guide →](/docs/react/migration/alert) |
+| Autocomplete | ComboBox | ✅ Renamed | [View guide →](/docs/react/migration/autocomplete) |
+| Avatar | Avatar | ✅ Available | [View guide →](/docs/react/migration/avatar) |
+| Badge | Badge | ✅ Available | [View guide →](/docs/react/migration/badge) |
+| Breadcrumbs | Breadcrumbs | ✅ Available | [View guide →](/docs/react/migration/breadcrumbs) |
+| Button | Button | ✅ Available | [View guide →](/docs/react/migration/button) |
+| ButtonGroup | ButtonGroup | ✅ Available | [View guide →](/docs/react/migration/button-group) |
+| Calendar | Calendar | ✅ Available | [View guide →](/docs/react/migration/calendar) |
+| Card | Card | ✅ Available | [View guide →](/docs/react/migration/card) |
+| Checkbox | Checkbox | ✅ Available | [View guide →](/docs/react/migration/checkbox) |
+| CheckboxGroup | CheckboxGroup | ✅ Available | [View guide →](/docs/react/migration/checkbox-group) |
+| Chip | Chip | ✅ Available | [View guide →](/docs/react/migration/chip) |
+| Code | ❌ | ❌ Removed | [View guide →](/docs/react/migration/code) |
+| DateInput | DateField | ✅ Renamed | [View guide →](/docs/react/migration/dateinput) |
+| DatePicker | DatePicker | ✅ Available | [View guide →](/docs/react/migration/date-picker) |
+| DateRangePicker | DateRangePicker | ✅ Available | [View guide →](/docs/react/migration/date-range-picker) |
+| TimeInput | TimeField | ✅ Renamed | [View guide →](/docs/react/migration/timeinput) |
+| Divider | Separator | ✅ Renamed | [View guide →](/docs/react/migration/divider) |
+| Drawer | Drawer | ✅ Available | [View guide →](/docs/react/migration/drawer) |
+| Dropdown | Dropdown | ✅ Available | [View guide →](/docs/react/migration/dropdown) |
+| Form | Form | ✅ Available | [View guide →](/docs/react/migration/form) |
+| Image | ❌ | ❌ Removed | [View guide →](/docs/react/migration/image) |
+| Input | TextField, Input, InputGroup | ✅ Available | [View guide →](/docs/react/migration/input) |
+| InputOTP | InputOTP | ✅ Available | [View guide →](/docs/react/migration/input-otp) |
+| Kbd | Kbd | ✅ Available | [View guide →](/docs/react/migration/kbd) |
+| Link | Link | ✅ Available | [View guide →](/docs/react/migration/link) |
+| Listbox | ListBox | ✅ Available | [View guide →](/docs/react/migration/listbox) |
+| Modal | Modal | ✅ Available | [View guide →](/docs/react/migration/modal) |
+| Navbar | ❌ | ❌ Removed | [View guide →](/docs/react/migration/navbar) |
+| NumberInput | NumberField | ✅ Renamed | [View guide →](/docs/react/migration/numberinput) |
+| Pagination | Pagination | ✅ Available | [View guide →](/docs/react/migration/pagination) |
+| Popover | Popover | ✅ Available | [View guide →](/docs/react/migration/popover) |
+| Progress | ProgressBar | ✅ Renamed | [View guide →](/docs/react/migration/progress) |
+| CircularProgress | ProgressCircle | ✅ Renamed | [View guide →](/docs/react/migration/circular-progress) |
+| Radio | Radio | ✅ Available | [View guide →](/docs/react/migration/radio) |
+| RadioGroup | RadioGroup | ✅ Available | [View guide →](/docs/react/migration/radio-group) |
+| RangeCalendar | RangeCalendar | ✅ Available | [View guide →](/docs/react/migration/range-calendar) |
+| Ripple | ❌ | ❌ Removed | [See Button ripple →](/docs/react/components/button#adding-ripple-effect) |
+| ScrollShadow | ScrollShadow | ✅ Available | [View guide →](/docs/react/migration/scroll-shadow) |
+| Select | Select | ✅ Available | [View guide →](/docs/react/migration/select) |
+| Skeleton | Skeleton | ✅ Available | [View guide →](/docs/react/migration/skeleton) |
+| Slider | Slider | ✅ Available | [View guide →](/docs/react/migration/slider) |
+| Snippet | ❌ | ❌ Removed | [View guide →](/docs/react/migration/snippet) |
+| Spacer | ❌ | ❌ Removed | [View guide →](/docs/react/migration/spacer) |
+| Spinner | Spinner | ✅ Available | [View guide →](/docs/react/migration/spinner) |
+| Switch | Switch | ✅ Available | [View guide →](/docs/react/migration/switch) |
+| Table | Table | ✅ Available | [View guide →](/docs/react/migration/table) |
+| Tabs | Tabs | ✅ Available | [View guide →](/docs/react/migration/tabs) |
+| Toast | Toast | ✅ Available | [View guide →](/docs/react/migration/toast) |
+| Tooltip | Tooltip | ✅ Available | [View guide →](/docs/react/migration/tooltip) |
+| User | ❌ | ❌ Removed | [View guide →](/docs/react/migration/user) |
+
+</section>
+
+## New Components in v3
+
+<section id="new-components-in-v3">
+
+v3 introduces a number of new components not available in v2:
+
+| Component | Purpose | Documentation |
+|-----------|---------|---------------|
+| TextField | Enhanced text input with label and description support | [View docs →](/docs/react/components/text-field) |
+| TextArea | Multi-line text input component | [View docs →](/docs/react/components/text-area) |
+| AlertDialog | Modal dialog for confirmations and alerts | [View docs →](/docs/react/components/alert-dialog) |
+| Label | Accessible form label component | [View docs →](/docs/react/components/label) |
+| Description | Helper text for form fields | [View docs →](/docs/react/components/description) |
+| FieldError | Form field error message display | [View docs →](/docs/react/components/field-error) |
+| Fieldset | Group related form fields | [View docs →](/docs/react/components/fieldset) |
+| InputGroup | Compose multiple inputs together | [View docs →](/docs/react/components/input-group) |
+| Surface | Container component with elevation styles | [View docs →](/docs/react/components/surface) |
+| Disclosure | Expandable/collapsible content sections | [View docs →](/docs/react/components/disclosure) |
+| DisclosureGroup | Compound component for multiple disclosure sections | [View docs →](/docs/react/components/disclosure-group) |
+| SearchField | Search input with clear button and optional loading state | [View docs →](/docs/react/components/search-field) |
+| DateField | Date input with calendar picker | [View docs →](/docs/react/components/date-field) |
+| TimeField | Time input component | [View docs →](/docs/react/components/time-field) |
+| Tag, TagGroup | Tags and tag group for selection or display | [View docs →](/docs/react/components/tag-group) |
+| ColorPicker | Color selection (ColorArea, ColorField, ColorSlider, ColorSwatch, ColorSwatchPicker) | [View docs →](/docs/react/components/color-picker) |
+| CloseButton | Dismiss or close trigger button | [View docs →](/docs/react/components/close-button) |
+| ErrorMessage | Form field error display (React Aria integration) | [View docs →](/docs/react/components/error-message) |
+
+</section>
+
+## Additional Migration Guides
+
+- **[Hooks Migration Guide](/docs/react/migration/hooks)**: Detailed guide for migrating hooks from v2 to v3
+- **[Styling Migration Guide](/docs/react/migration/styling)**: Comprehensive guide for updating utility classes, color tokens, and component styling
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [v3 documentation](/docs/react)
+2. Review component-specific migration guides
+3. Check the [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
+4. Join the [Discord community](https://discord.gg/9b6yyZKmH4)
diff --git a/apps/docs/content/docs/en/react/migration/meta.json b/apps/docs/content/docs/en/react/migration/meta.json
new file mode 100644
index 0000000..29ed41d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/meta.json
@@ -0,0 +1,70 @@
+{
+  "title": "Migration",
+  "description": "Complete guide to migrate your HeroUI v2 application to v3",
+  "root": true,
+  "icon": "code-pull-request-arrow-right",
+  "pages": [
+    "---Overview---",
+    "index",
+    "---Migration for Agents---",
+    "(migration-for-agents)/mcp-server",
+    "(migration-for-agents)/agent-skills",
+    "(migration-for-agents)/agents-md",
+    "---Workflows---",
+    "(workflows)/full-migration",
+    "(workflows)/incremental-migration",
+    "---References---",
+    "hooks",
+    "styling",
+    "---Components---",
+    "(components)/accordion",
+    "(components)/alert",
+    "(components)/autocomplete",
+    "(components)/avatar",
+    "(components)/badge",
+    "(components)/breadcrumbs",
+    "(components)/calendar",
+    "(components)/button",
+    "(components)/button-group",
+    "(components)/card",
+    "(components)/checkbox",
+    "(components)/checkbox-group",
+    "(components)/chip",
+    "(components)/code",
+    "(components)/date-picker",
+    "(components)/date-range-picker",
+    "(components)/divider",
+    "(components)/drawer",
+    "(components)/dropdown",
+    "(components)/form",
+    "(components)/image",
+    "(components)/input",
+    "(components)/input-otp",
+    "(components)/kbd",
+    "(components)/link",
+    "(components)/listbox",
+    "(components)/modal",
+    "(components)/navbar",
+    "(components)/numberinput",
+    "(components)/pagination",
+    "(components)/popover",
+    "(components)/progress",
+    "(components)/circular-progress",
+    "(components)/radio",
+    "(components)/range-calendar",
+    "(components)/radio-group",
+    "(components)/scroll-shadow",
+    "(components)/select",
+    "(components)/skeleton",
+    "(components)/slider",
+    "(components)/snippet",
+    "(components)/spacer",
+    "(components)/spinner",
+    "(components)/switch",
+    "(components)/table",
+    "(components)/tabs",
+    "(components)/toast",
+    "(components)/tooltip",
+    "(components)/user"
+  ]
+}
diff --git a/apps/docs/content/docs/en/react/migration/styling.mdx b/apps/docs/content/docs/en/react/migration/styling.mdx
new file mode 100644
index 0000000..2b1dd9d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/migration/styling.mdx
@@ -0,0 +1,720 @@
+---
+title: Styling & Theming
+description: Complete guide to styling changes and theming system migration from HeroUI v2 to v3
+---
+
+<Callout type="info">
+  This guide covers all styling-related changes between HeroUI v2 and v3, including utility classes, component styles, theme system architecture, and visual differences. For component-specific API changes, see individual component migration guides.
+</Callout>
+
+**Note:** The `classNames` prop has been replaced with `className` prop in v3. All components now use the standard React `className` prop instead of the `classNames` object prop from v2.
+
+## Overview
+
+HeroUI v3 introduces significant changes to the styling system:
+
+- **CSS-First Architecture**: Replaces Tailwind plugin with pure CSS files
+- **Standard Tailwind Utilities**: Custom utilities replaced with standard Tailwind classes
+- **CSS Variables**: New CSS variable naming and structure
+- **Component Styles**: Updated default sizes, spacing, and visual appearance
+- **No Plugin Required**: Removed dependency on Tailwind plugin configuration
+- **Color System Overhaul**: Semantic colors reorganized (`primary` → `accent`, `secondary` removed, numbered scales removed)
+- **Content Colors Removed**: `content1-4` replaced with `surface` and `overlay` system
+
+## Quick Reference
+
+### Utility Classes Mapping
+
+| v2 Utility | v3 Equivalent | Notes |
+|-----------|--------------|-------|
+| `text-tiny` | `text-xs` | Font size: 0.75rem → 0.75rem (same) |
+| `text-small` | `text-sm` | Font size: 0.875rem → 0.875rem (same) |
+| `text-medium` | `text-base` | Font size: 1rem → 1rem (same) |
+| `text-large` | `text-lg` | Font size: 1.125rem → 1.125rem (same) |
+| `rounded-small` | `rounded-sm` | Border radius: 8px → 4px (different) |
+| `rounded-medium` | `rounded-md` | Border radius: 12px → 6px (different) |
+| `rounded-large` | `rounded-lg` | Border radius: 14px → 8px (different) |
+| `border-small` | `border` | Border width: 1px → 1px (use standard Tailwind) |
+| `border-medium` | `border-2` | Border width: 2px → 2px (use standard Tailwind) |
+| `border-large` | `border-[3px]` | Border width: 3px → 3px (use arbitrary value) |
+| `bg-content1` | `bg-surface` or `bg-overlay` | Content color removed, use surface/overlay |
+| `bg-content2` | `bg-surface-secondary` | Content color removed, use surface level |
+| `bg-primary` | `bg-accent` | Primary renamed to accent |
+| `bg-secondary` | `bg-default` | Secondary color removed, use default |
+| `bg-primary-50` | `bg-accent-soft` | Numbered scales removed |
+| `bg-primary-100` | `bg-accent-soft` | Numbered scales removed |
+| `text-primary-600` | `text-accent` | Numbered scales removed |
+| `.transition-background` | Standard CSS transitions | Removed utility |
+| `.transition-colors-opacity` | Standard CSS transitions | Removed utility |
+
+## Utility Classes Migration
+
+### Text Utilities
+
+HeroUI v2 provided custom text size utilities that mapped to CSS variables. v3 uses standard Tailwind text size classes.
+
+**v2 Text Utilities:**
+
+```tsx
+// v2 - Custom utilities with CSS variables
+<div className="text-tiny">Tiny text</div>
+<div className="text-small">Small text</div>
+<div className="text-medium">Medium text</div>
+<div className="text-large">Large text</div>
+```
+
+**v3 Text Utilities:**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="text-xs">Tiny text</div>
+<div className="text-sm">Small text</div>
+<div className="text-base">Medium text</div>
+<div className="text-lg">Large text</div>
+```
+
+**Mapping Details:**
+
+| v2 Class | Font Size | Line Height | v3 Class | Font Size | Line Height |
+|----------|-----------|-------------|----------|-----------|-------------|
+| `text-tiny` | 0.75rem (12px) | 1rem (16px) | `text-xs` | 0.75rem (12px) | 1rem (16px) |
+| `text-small` | 0.875rem (14px) | 1.25rem (20px) | `text-sm` | 0.875rem (14px) | 1.25rem (20px) |
+| `text-medium` | 1rem (16px) | 1.5rem (24px) | `text-base` | 1rem (16px) | 1.5rem (24px) |
+| `text-large` | 1.125rem (18px) | 1.75rem (28px) | `text-lg` | 1.125rem (18px) | 1.75rem (28px) |
+
+### Border Radius Utilities
+
+v2 used custom border radius utilities (`rounded-small`, `rounded-medium`, `rounded-large`) that mapped to CSS variables. v3 uses standard Tailwind border radius classes, but the actual values differ.
+
+**v2 Border Radius:**
+
+```tsx
+// v2 - Custom utilities
+<div className="rounded-small">Small radius</div>
+<div className="rounded-medium">Medium radius</div>
+<div className="rounded-large">Large radius</div>
+```
+
+**v3 Border Radius:**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="rounded-sm">Small radius</div>
+<div className="rounded-md">Medium radius</div>
+<div className="rounded-lg">Large radius</div>
+```
+
+**Value Comparison:**
+
+| v2 Class | v2 Value | v3 Class | v3 Value | Difference |
+|----------|----------|----------|----------|------------|
+| `rounded-small` | 8px (0.5rem) | `rounded-sm` | 4px (0.25rem) | Smaller |
+| `rounded-medium` | 12px (0.75rem) | `rounded-md` | 6px (0.375rem) | Smaller |
+| `rounded-large` | 14px (0.875rem) | `rounded-lg` | 8px (0.5rem) | Smaller |
+
+**Note:** v3 uses smaller default border radius values. If you need the exact v2 values, use arbitrary values:
+
+```tsx
+// Match v2 rounded-small (8px)
+<div className="rounded-[8px]">Custom radius</div>
+
+// Match v2 rounded-medium (12px)
+<div className="rounded-[12px]">Custom radius</div>
+
+// Match v2 rounded-large (14px)
+<div className="rounded-[14px]">Custom radius</div>
+```
+
+### Border Width Utilities
+
+v2 provided custom border width utilities (`border-small`, `border-medium`, `border-large`). v3 uses standard Tailwind border width classes.
+
+**v2 Border Width:**
+
+```tsx
+// v2 - Custom utilities
+<div className="border-small border-default">1px border</div>
+<div className="border-medium border-primary">2px border</div>
+<div className="border-large border-danger">3px border</div>
+```
+
+**v3 Border Width:**
+
+```tsx
+// v3 - Standard Tailwind classes
+<div className="border border-default">1px border</div>
+<div className="border-2 border-accent">2px border</div>
+<div className="border-[3px] border-danger">3px border</div>
+```
+
+**Mapping:**
+
+| v2 Class | Width | v3 Class | Width |
+|----------|-------|----------|-------|
+| `border-small` | 1px | `border` | 1px |
+| `border-medium` | 2px | `border-2` | 2px |
+| `border-large` | 3px | `border-[3px]` | 3px (arbitrary) |
+
+### Transition Utilities
+
+v2 provided custom transition utilities for common animation patterns with a default duration of 250ms. v3 removes these utilities in favor of standard Tailwind `transition-*` utilities, where you specify which properties to transition.
+
+**v2 Transition Utilities:**
+
+v2 provided custom transition utilities with a default duration of 250ms and `ease` timing function. The following table shows which CSS properties each utility transitions:
+
+| v2 Utility | Transition Properties |
+|-----------|----------------------|
+| `.transition-background` | `background` |
+| `.transition-colors-opacity` | `color, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
+| `.transition-width` | `width` |
+| `.transition-height` | `height` |
+| `.transition-size` | `width, height` |
+| `.transition-left` | `left` |
+| `.transition-transform-opacity` | `transform, scale, opacity rotate` |
+| `.transition-transform-background` | `transform, scale, background` |
+| `.transition-transform-colors` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke` |
+| `.transition-transform-colors-opacity` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
+
+**Note:** These utilities are no longer available in v3. Use Tailwind's standard `transition-*` utilities to specify which properties to transition.
+
+### Other Utilities
+
+**Scrollbar Utilities:**
+
+v2 provided `.scrollbar-hide` and `.scrollbar-default` utilities. v3 now exposes standards-only scrollbar utilities from `@heroui/styles`: `scrollbar`, `scrollbar-thin`, `scrollbar-default`, and `scrollbar-none`. Use `data-scrollbar="thin"`, `data-scrollbar="default"`, or `data-scrollbar="none"` on an ancestor for subtree-level control.
+
+**Animation Utilities:**
+
+v2 provided spinner animation utilities (`.spinner-bar-animation`, `.spinner-dot-animation`, etc.). These are handled internally by v3 components and are not exposed as utilities.
+
+**Custom Utilities:**
+
+v2 included utilities like:
+- `.leading-inherit` → Use `leading-[inherit]`
+- `.tap-highlight-transparent` → Use `[-webkit-tap-highlight-color:transparent]`
+- `.input-search-cancel-button-none` → Use custom CSS if needed
+
+## Theme System Architecture
+
+### v2: Plugin-Based System
+
+v2 used a Tailwind CSS plugin that:
+
+1. **Generated Utilities**: Created custom utility classes via JavaScript
+2. **CSS Variables**: Injected CSS variables through the plugin
+3. **Theme Configuration**: Required configuration in `tailwind.config.js`
+4. **Runtime Generation**: Utilities generated at build time
+
+**v2 Configuration:**
+
+```js
+// tailwind.config.js
+const {heroui} = require("@heroui/react");
+
+module.exports = {
+  plugins: [
+    heroui({
+      layout: {
+        fontSize: {
+          tiny: "0.75rem",
+          small: "0.875rem",
+          medium: "1rem",
+          large: "1.125rem",
+        },
+        radius: {
+          small: "8px",
+          medium: "12px",
+          large: "14px",
+        },
+      },
+      themes: {
+        light: {
+          colors: {
+            primary: {
+              // color definitions
+            },
+          },
+        },
+      },
+    }),
+  ],
+};
+```
+
+### v3: CSS-First System
+
+v3 uses a pure CSS approach:
+
+1. **CSS Files**: Styles defined in CSS files (`packages/styles/`)
+2. **CSS Variables**: Variables defined in CSS, not generated
+3. **No Plugin**: No Tailwind plugin required
+4. **Import-Based**: Styles imported via CSS imports
+
+**v3 Configuration:**
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+**No Tailwind Config Required:**
+
+If you only use HeroUI, you can remove `tailwind.config.js` entirely. If you have custom Tailwind config, keep it but remove the HeroUI plugin.
+
+### Architecture Comparison
+
+| Aspect | v2 | v3 |
+|--------|----|----|
+| **Styling Method** | Tailwind plugin (JavaScript) | CSS files |
+| **Utility Generation** | Runtime via plugin | Pre-defined CSS |
+| **CSS Variables** | Generated by plugin | Defined in CSS |
+| **Configuration** | `tailwind.config.js` | CSS imports |
+| **Customization** | Plugin config | CSS variable overrides |
+| **Build Dependency** | Requires plugin | No plugin needed |
+
+## CSS Variables & Design Tokens
+
+### Variable Naming Changes
+
+v2 used the pattern `--heroui-{property}-{scale}` while v3 uses `--{property}` or `--color-{property}`.
+
+**v2 CSS Variables:**
+
+```css
+--heroui-font-size-tiny: 0.75rem;
+--heroui-font-size-small: 0.875rem;
+--heroui-radius-small: 8px;
+--heroui-radius-medium: 12px;
+--heroui-border-width-medium: 2px;
+--heroui-disabled-opacity: 0.5;
+```
+
+**v3 CSS Variables:**
+
+```css
+/* Typography - handled by Tailwind */
+/* No custom font-size variables */
+
+/* Radius */
+--radius-xs: calc(var(--radius) * 0.25);
+--radius-sm: calc(var(--radius) * 0.5);
+--radius-md: calc(var(--radius) * 0.75);
+--radius-lg: calc(var(--radius) * 1);
+--radius-xl: calc(var(--radius) * 1.5);
+
+/* Colors */
+--color-background: var(--background);
+--color-foreground: var(--foreground);
+--color-accent: var(--accent);
+--color-muted: var(--muted);
+
+/* Opacity */
+--disabled-opacity: 0.5;
+```
+
+### Color System Changes
+
+**v2 Color Structure:**
+
+```css
+--heroui-primary: 210 100% 50%;
+--heroui-primary-50: 210 100% 95%;
+--heroui-primary-100: 210 100% 90%;
+/* ... more shades ... */
+```
+
+**v3 Color Structure:**
+
+```css
+--accent: oklch(0.6204 0.195 253.83);
+--accent-foreground: var(--snow);
+--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+```
+
+**Key Differences:**
+
+1. **Color Format**: v2 used HSL, v3 uses OKLCH
+2. **Naming**: v2 used numbered shades (50-900), v3 uses semantic names
+3. **Calculated Colors**: v3 uses `color-mix()` for hover states
+4. **Foreground Colors**: v3 explicitly defines foreground colors
+5. **Primary → Accent**: `primary` color renamed to `accent`
+6. **Secondary Color Removed**: `secondary` semantic color removed (was purple in v2)
+7. **Numbered Scales Removed**: Color scales like `primary-50`, `primary-100`, etc. no longer exist
+
+### Primary → Accent Rename
+
+v2 used `primary` as the main brand color. v3 renamed it to `accent` for better semantic clarity.
+
+**v2 Primary Color:**
+
+```tsx
+// v2 - Primary color with numbered scales
+<Button color="primary">Primary Button</Button>
+<div className="bg-primary">Primary background</div>
+<div className="bg-primary-50">Light primary</div>
+<div className="bg-primary-100">Lighter primary</div>
+<div className="text-primary-600">Primary text</div>
+```
+
+**v3 Accent Color:**
+
+```tsx
+// v3 - Accent color (no numbered scales)
+<Button variant="primary">Primary Button</Button>
+<div className="bg-accent">Accent background</div>
+<div className="bg-accent-soft">Soft accent</div>
+<div className="text-accent">Accent text</div>
+```
+
+**Migration:**
+
+| v2 Class | v3 Equivalent | Notes |
+|----------|---------------|-------|
+| `bg-primary` | `bg-accent` | Base accent color |
+| `text-primary` | `text-accent` | Accent text color |
+| `bg-primary-50` | `bg-accent-soft` | Light accent variant |
+| `bg-primary-100` | `bg-accent-soft` | Light accent variant |
+| `bg-primary-500` | `bg-accent` | Base accent color |
+| `text-primary-600` | `text-accent` | Accent text color |
+| `border-primary` | `border-accent` | Accent border |
+
+**Note:** v3 doesn't have numbered color scales (`-50`, `-100`, `-200`, etc.). Use semantic variants like `-soft`, `-hover`, or custom Tailwind classes.
+
+### Secondary Color Removed
+
+v2 provided a `secondary` semantic color (purple). This has been removed in v3. Component variants named "secondary" now use different colors.
+
+**v2 Secondary Color:**
+
+```tsx
+// v2 - Secondary as a semantic color (purple)
+<Button color="secondary">Secondary Button</Button>
+<div className="bg-secondary">Secondary background</div>
+<div className="bg-secondary-50">Light secondary</div>
+<div className="text-secondary-600">Secondary text</div>
+```
+
+**v3 Secondary Variant:**
+
+```tsx
+// v3 - Secondary is a variant, not a color
+<Button variant="secondary">Secondary Button</Button>
+<div className="bg-default">Default background (used by secondary variant)</div>
+<div className="text-accent">Accent text</div>
+```
+
+**Migration:**
+
+| v2 Class | v3 Equivalent | Notes |
+|----------|---------------|-------|
+| `bg-secondary` | `bg-default` | Secondary variant uses default color |
+| `text-secondary` | `text-accent` | Use accent for emphasis |
+| `bg-secondary-50` | `bg-default` | Use default color |
+| `border-secondary` | `border-accent` | Use accent border |
+
+**Note:** In v3, "secondary" refers to a component variant style (like `button--secondary`), not a color token. The secondary variant typically uses `bg-default` and `text-accent-soft-foreground`.
+
+### Numbered Color Scales Removed
+
+v2 provided numbered color scales (50-900) for all semantic colors. v3 removed these in favor of semantic variants and calculated colors.
+
+**v2 Numbered Scales:**
+
+```tsx
+// v2 - Numbered color scales
+<div className="bg-primary-50">Lightest</div>
+<div className="bg-primary-100">Lighter</div>
+<div className="bg-primary-200">Light</div>
+<div className="bg-primary-500">Base</div>
+<div className="bg-primary-600">Dark</div>
+<div className="bg-primary-900">Darkest</div>
+```
+
+**v3 Semantic Variants:**
+
+```tsx
+// v3 - Semantic variants and calculated colors
+<div className="bg-accent-soft">Soft variant</div>
+<div className="bg-accent">Base color</div>
+<div className="bg-accent-hover">Hover state</div>
+```
+
+**Migration:**
+
+- **Light shades** (`-50`, `-100`, `-200`): Use `-soft` variants or custom Tailwind opacity classes
+- **Base color** (`-500`): Use base color name (`bg-accent`, `bg-danger`, etc.)
+- **Dark shades** (`-600`, `-700`, `-800`, `-900`): Use hover variants or custom Tailwind classes
+
+### Content Colors Removed
+
+v2 provided `content1`, `content2`, `content3`, and `content4` colors for layered backgrounds. These have been removed in v3 and replaced with semantic surface colors.
+
+**v2 Content Colors:**
+
+```tsx
+// v2 - Content colors for layered backgrounds
+<div className="bg-content1">Base content</div>
+<div className="bg-content2">Secondary content</div>
+<div className="bg-content3">Tertiary content</div>
+<div className="bg-content4">Quaternary content</div>
+```
+
+**v3 Surface Colors:**
+
+```tsx
+// v3 - Surface colors for non-overlay components
+<div className="bg-surface">Base surface</div>
+<div className="bg-surface-secondary">Secondary surface</div>
+<div className="bg-surface-tertiary">Tertiary surface</div>
+<div className="bg-surface-quaternary">Quaternary surface</div>
+
+// v3 - Overlay colors for floating components
+<div className="bg-overlay">Overlay (tooltips, popovers, modals)</div>
+```
+
+**Migration Mapping:**
+
+| v2 Class | v3 Equivalent | Usage |
+|----------|---------------|-------|
+| `bg-content1` | `bg-surface` | Non-overlay components (cards, accordions) |
+| `bg-content1` | `bg-overlay` | Floating components (tooltips, popovers, modals) |
+| `bg-content2` | `bg-surface-secondary` | Secondary surface level |
+| `bg-content3` | `bg-surface-tertiary` | Tertiary surface level |
+| `bg-content4` | `bg-surface-quaternary` | Quaternary surface level |
+
+**Key Changes:**
+
+1. **Semantic Naming**: `content1-4` replaced with `surface` and `overlay` for clearer semantics
+2. **Component-Specific**: Use `bg-surface` for page-level components, `bg-overlay` for floating components
+3. **Auto-Calculated**: Surface levels (`secondary`, `tertiary`, `quaternary`) are automatically calculated from the base `surface` color using `color-mix()`
+
+### Spacing & Layout Tokens
+
+**v2 Layout Tokens:**
+
+```css
+--heroui-divider-weight: 1px;
+--heroui-disabled-opacity: 0.5;
+--heroui-hover-opacity: 0.8;
+```
+
+**v3 Layout Tokens:**
+
+```css
+--border-width: 0px;
+--field-border-width: var(--border-width);
+--disabled-opacity: 0.5;
+--cursor-interactive: pointer;
+--cursor-disabled: not-allowed;
+--radius: 0.5rem;
+--field-radius: calc(var(--radius) * 1.5);
+```
+
+### Shadow Tokens
+
+**v2 Shadows:**
+
+```css
+--heroui-box-shadow-small: 0px 0px 5px 0px rgb(0 0 0 / 0.02), ...;
+--heroui-box-shadow-medium: 0px 0px 15px 0px rgb(0 0 0 / 0.03), ...;
+--heroui-box-shadow-large: 0px 0px 30px 0px rgb(0 0 0 / 0.04), ...;
+```
+
+**v3 Shadows:**
+
+```css
+--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
+--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), ...;
+--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
+```
+
+**Key Changes:**
+
+1. **Semantic Naming**: v3 uses semantic names (`surface-shadow`, `overlay-shadow`) instead of size-based names
+2. **Component-Specific**: Shadows are tied to component types (surface, overlay, field)
+3. **Dark Mode**: Dark mode shadows are transparent in v3
+
+## Visual Differences
+
+### Alignment Changes
+
+**Button Alignment:**
+
+- v2: Icons and text aligned with `items-center justify-center`
+- v3: Same alignment, but with responsive height adjustments
+
+**Input Alignment:**
+
+- v2: Text aligned with `text-left`
+- v3: Same alignment, but padding adjustments may affect visual balance
+
+### Spacing Changes
+
+**Component Padding:**
+
+Most components have increased padding in v3:
+
+- **Card**: 12px → 16px
+- **Button**: Similar padding, but responsive heights
+- **Input**: Added vertical padding (`py-2`)
+
+**Gap Spacing:**
+
+v3 uses more consistent gap spacing:
+
+- **Card**: `gap-3` between header, content, footer
+- **Button**: `gap-2` between icon and text
+- **Chip**: `gap-1.5` between elements
+
+### Size Changes
+
+**Button Heights:**
+
+- **Small**: 32px → 36px (mobile) / 32px (desktop)
+- **Medium**: 40px → 40px (mobile) / 36px (desktop)
+- **Large**: 48px → 44px (mobile) / 40px (desktop)
+
+**Input Heights:**
+
+- **Medium**: 40px → 36px (default, only size available)
+
+### Border Radius Changes
+
+**Default Radius:**
+
+- v2: Components used `rounded-medium` (12px) by default
+- v3: Components use larger radius values:
+  - Button: `rounded-3xl` (24px)
+  - Card: `rounded-3xl` (24px)
+  - Chip: `rounded-2xl` (16px)
+  - Input: `rounded-field` (typically 12-16px)
+
+### Color Appearance Changes
+
+**Color System:**
+
+- v2: HSL color format
+- v3: OKLCH color format (more perceptually uniform)
+
+**Default Colors:**
+
+- v2: `primary`, `secondary`, `success`, `warning`, `danger`
+- v3: `accent` (replaces `primary`), `success`, `warning`, `danger`
+
+**Muted Colors:**
+
+- v2: `foreground-400`, `foreground-500` for muted text
+- v3: `muted` color token for muted text
+
+## Migration Examples
+
+### Utility Class Migration
+
+**Example: Text Utilities**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <div>
+      <h1 className="text-large font-bold">Title</h1>
+      <p className="text-small text-foreground-400">Description</p>
+      <span className="text-tiny text-foreground-500">Helper</span>
+    </div>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    <div>
+      <h1 className="text-lg font-bold">Title</h1>
+      <p className="text-sm text-muted">Description</p>
+      <span className="text-xs text-muted">Helper</span>
+    </div>
+    ```
+  </Tab>
+</Tabs>
+
+### Border Radius Migration
+
+**Example: Matching v2 Radius Values**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```tsx
+    <Card radius="md">
+      <CardBody>Content</CardBody>
+    </Card>
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```tsx
+    {/* Option 1: Use standard Tailwind (smaller radius) */}
+    <Card className="rounded-md">
+      <Card.Content>Content</Card.Content>
+    </Card>
+
+    {/* Option 2: Match exact v2 value (12px) */}
+    <Card className="rounded-[12px]">
+      <Card.Content>Content</Card.Content>
+    </Card>
+    ```
+  </Tab>
+</Tabs>
+
+### Theme Customization Migration
+
+**Example: Custom Colors**
+
+<Tabs items={["v2", "v3"]}>
+  <Tab value="v2">
+    ```js
+    // tailwind.config.js
+    const {heroui} = require("@heroui/react");
+
+    module.exports = {
+      plugins: [
+        heroui({
+          themes: {
+            light: {
+              colors: {
+                primary: {
+                  DEFAULT: "#006FEE",
+                  50: "#E6F1FE",
+                  // ... more shades
+                },
+              },
+            },
+          },
+        }),
+      ],
+    };
+    ```
+  </Tab>
+  <Tab value="v3">
+    ```css
+    /* globals.css */
+    @import "tailwindcss";
+    @import "@heroui/styles";
+
+    :root {
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: oklch(0.9911 0 0);
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+1. **Use Standard Tailwind**: Prefer standard Tailwind utilities over custom ones
+2. **Match v2 Values**: If exact v2 appearance is needed, use arbitrary values
+3. **Test Responsively**: v3 has responsive sizing - test on multiple screen sizes
+4. **Update CSS Variables**: If customizing, update CSS variables instead of Tailwind config
+5. **Check Component Docs**: Refer to individual component migration guides for API changes
+
+## Related Guides
+
+- [Main Migration Guide](/docs/react/migration)
+- [Theming Documentation](/docs/react/getting-started/handbook/theming)
+- [Styling Guide](/docs/react/getting-started/handbook/styling)
diff --git a/apps/docs/content/docs/en/react/releases/index.mdx b/apps/docs/content/docs/en/react/releases/index.mdx
new file mode 100644
index 0000000..ff6748a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/index.mdx
@@ -0,0 +1,355 @@
+---
+title: All Releases
+description: All updates and changes to HeroUI v3, including new features, fixes, and breaking changes.
+---
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## Latest Release
+
+### v3.2.2
+
+**June 19, 2026**
+
+Patch release: upgrades to React Aria `1.19.0` (`react-aria@3.50.0`), adds overflow scrolling to `Tabs.ListContainer`, fixes clear/close buttons accidentally submitting their surrounding form, and prevents visually hidden inputs in `Checkbox`, `Radio`, and `Switch` from causing overflow scroll.
+
+[Read full release notes →](/docs/react/releases/v3-2-2)
+
+---
+
+### v3.2.1
+
+**June 17, 2026**
+
+Patch release: `@heroui/react` no longer bundles its own copy of `react-aria`. The `react-aria` subpaths are externalized in the Rollup build, so consumers resolve to the single `react-aria` installed in their project instead of a vendored copy. Also fixes `SwitchGroup` horizontal layout.
+
+[Read full release notes →](/docs/react/releases/v3-2-1)
+
+---
+
+### v3.2.0
+
+**June 6, 2026**
+
+Calendar week and day views, a reworked year picker, and range demos on React Aria 1.18, plus tooltip delay theme variables and the patch fixes shipped with it. Breaking: `Radio`, `Checkbox`, and `Switch` move to an explicit `*.Content` composition (control nests inside `*.Content`; the label is plain text, no nested `<Label>`; help text becomes a sibling).
+
+[Read full release notes →](/docs/react/releases/v3-2-0)
+
+---
+
+### v3.1.0
+
+**May 25, 2026**
+
+Minor release: Chinese React docs and localized demos, accessible soft foreground tokens with a vibrant palette opt-in, a shared scrollbar system, fixes for `useTheme`, Toast, Fieldset, Link, overlays, and improved RTL support across Table, pickers, and MenuItem.
+
+[Read full release notes →](/docs/react/releases/v3-1-0)
+
+---
+
+### v3.0.5
+
+**May 15, 2026**
+
+Patch release: `Text` is renamed to `Typography` to resolve a `tailwind-merge` collision (⚠️ **breaking change**), derived color tokens are refactored into unprefixed source variables, Checkbox and Radio get aligned field-border styling, Calendar hover uses `accent-soft-foreground` for readability, and a new CLI docs page is added.
+
+[Read full release notes →](/docs/react/releases/v3-0-5)
+
+---
+
+### v3.0.4
+
+**May 2026**
+
+Patch release: new `Text` compound component ported from HeroUI Pro, docs theme selector, `min()`-capped border-radius tokens across 45+ component CSS files, reworked Table focus rings, and fixes for Checkbox, Autocomplete, Tooltip, and form field padding.
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-oss-3.0.4-4k.mp4"
+  muted
+/>
+
+[Read full release notes →](/docs/react/releases/v3-0-4)
+
+---
+
+### v3.0.3
+
+**April 17, 2026**
+
+Patch release: React Aria Components 1.17 (dependencies consolidation, faster installs, Table expandable rows), the `useTheme` hook for Vite and CRA, a DOM polymorphic render prop for lightweight components, and fixes for NumberField resets and nested Tabs styling.
+
+[Read full release notes →](/docs/react/releases/v3-0-3)
+
+### v3.0.2
+
+**April 3, 2026**
+
+Bug fixes, smoother Drawer transitions, new `--backdrop` theme variable, and style refinements for triggers, arrows, and tags. Autocomplete popover width tracking fixed, overlay triggers now `inline-block`, and Tag gets improved spacing + accessibility.
+
+[Read full release notes →](/docs/react/releases/v3-0-2)
+
+### v3.0.0
+
+**March 2026**
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-v3-release.mp4"
+  height={430}
+  muted
+/>
+
+A ground-up rewrite for React and React Native. 75+ web components, 37 native components, Tailwind CSS v4, React Aria, compound component architecture, CSS-first theming with OKLCH tokens, `data-reduce-motion` animation control, and built for AI-assisted development with MCP servers, agent skills, and LLMs.txt.
+
+[Read the full announcement →](/docs/react/releases/v3-0-0)
+
+---
+
+### HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+Premium components, templates, and AI tooling for React and React Native. Pre-sale pricing is live.
+
+[See plans and pricing at heroui.pro →](https://heroui.pro)
+
+---
+
+### v3.0.0-rc.1
+
+**March 14, 2026**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-dark@2x.jpg"
+  alt="HeroUI v3 RC 1"
+  href="/docs/react/releases/v3-0-0-rc-1"
+/>
+
+Seven new components ([Drawer](/docs/components/drawer), [ToggleButton](/docs/components/toggle-button), [ToggleButtonGroup](/docs/components/toggle-button-group), [Meter](/docs/components/meter), [ProgressBar](/docs/components/progress-bar), [ProgressCircle](/docs/components/progress-circle), [Toolbar](/docs/components/toolbar)), **virtualization** for [Table](/docs/components/table) and [ListBox](/docs/components/list-box), `ButtonGroup.Separator` + vertical orientation for [ButtonGroup](/docs/components/button-group), and React Aria Components bumped to v1.16.0.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-rc-1)
+
+---
+
+### v3.0.0-beta.8
+
+**March 2, 2026**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-dark@2x.jpg"
+  alt="HeroUI v3 Beta 8"
+  href="/docs/react/releases/v3-0-0-beta-8"
+/>
+
+This release adds three new components ([Badge](/docs/components/badge), [Pagination](/docs/components/pagination), [Table](/docs/components/table)) and new `InputContainer` composition APIs for [DateField](/docs/components/date-field) + [TimeField](/docs/components/time-field). ⚠️ **Breaking changes**: TextField CSS classes were renamed from `.text-field` to `.textfield`.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-8)
+
+---
+
+### v3.0.0-beta.7
+
+**February 18, 2026**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-dark@2x.jpg"
+  alt="HeroUI v3 Beta 7"
+  href="/docs/react/releases/v3-0-0-beta-7"
+/>
+
+This release introduces a comprehensive **Date & Time** system with four new components ([Calendar](/docs/components/calendar), [RangeCalendar](/docs/components/range-calendar), [DatePicker](/docs/components/date-picker), [DateRangePicker](/docs/components/date-range-picker)), new [Switch.Content](/docs/components/switch) sub-component, explicit [Tabs.Separator](/docs/components/tabs) for opt-in separator lines, and ⚠️ **breaking changes** removing `hideSeparator` from Tabs and consolidating `DateInputGroup`/`ColorInputGroup` under their respective field components.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-7)
+
+---
+
+### v3.0.0-beta.6
+
+**February 6, 2026**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-dark@2x.jpg"
+  alt="HeroUI v3 Beta 6"
+  href="/docs/react/releases/v3-0-0-beta-6"
+/>
+
+This release introduces a comprehensive **Color System** with six new components ([ColorPicker](/docs/components/color-picker), [ColorArea](/docs/components/color-area), [ColorSlider](/docs/components/color-slider), [ColorField](/docs/components/color-field), [ColorSwatch](/docs/components/color-swatch), [ColorSwatchPicker](/docs/components/color-swatch-picker)), major [Toast](/docs/components/toast) improvements with loading states and promise support, [Separator](/docs/components/separator) variants, and ⚠️ **breaking changes** renaming `Toast.Container` to `Toast.Provider` and updating CSS class names to hyphenated format.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-6)
+
+---
+### v3.0.0-beta.5
+
+- Fixed build issue
+
+### v3.0.0-beta.4
+
+**January 20, 2026**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-dark@2x.jpg"
+  alt="HeroUI v3 Beta 4"
+  href="/docs/react/releases/v3-0-0-beta-4"
+/>
+
+<Callout type="warning">
+  **Critical Build Issue Fixed**: This version (beta.4) had a critical build issue that has been fixed in **beta.5**. Please upgrade to `@heroui/styles@3.0.0-beta.5` and `@heroui/react@3.0.0-beta.5` to ensure proper TypeScript declaration generation and export resolution.
+</Callout>
+
+This release introduces the new [Theme Builder](/themes) for visual theme customization, three new components ([Autocomplete](/docs/components/autocomplete), [Breadcrumbs](/docs/components/breadcrumbs), [Toast](/docs/components/toast)), secondary variant for [Tabs](/docs/components/tabs), primary/secondary variants for [Input](/docs/components/input) and [InputGroup](/docs/components/input-group), and ⚠️ **breaking changes** removing Link's underline variants and `isInSurface` prop from form components.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-4)
+
+---
+
+### v3.0.0-beta.3
+
+**December 19, 2025**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-dark@2x.jpg"
+  alt="HeroUI v3 Beta 3"
+  href="/docs/react/releases/v3-0-0-beta-3"
+/>
+
+
+This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form and input components, introduces `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) for cleaner layouts, includes styling fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variant.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-3)
+
+---
+
+### v3.0.0-beta.2
+
+**November 20, 2025**
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-dark@2x.jpg"
+  alt="HeroUI v3 Beta 2"
+  href="/docs/react/releases/v3-0-0-beta-2"
+/>
+
+
+This release introduces six essential new components ([AlertDialog](/docs/components/alert-dialog), [ComboBox](/docs/components/combo-box), [Dropdown](/docs/components/dropdown), [InputGroup](/docs/components/input-group), [Modal](/docs/components/modal), [NumberField](/docs/components/number-field)), enhances theme compatibility and motion preferences, improves the [Select](/docs/components/select) component API with a ⚠️ **breaking change**, plus various refinements and bug fixes.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-2)
+
+---
+
+### v3.0.0-beta.1
+
+**November 6, 2025**
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1.mp4"
+  poster="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1-poster.png"
+  height={430}
+  muted
+/>
+
+This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components have been redesigned, 8 new components added ([Alert](/docs/compoenents/alert), [Checkbox](/docs/components/checkbox), [InputOTP](/docs/components/input-otp), [ListBox](/docs/components/listbox), [Select](/docs/components/select), [Slider](/docs/components/slider), [Surface](/docs/components/surface)), and the design system has been completely overhauled with better color tokens, shadows, and architecture. Includes breaking changes to design system variables, component APIs, and flexible component patterns.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-beta-1)
+
+---
+
+## Previous Releases
+
+### v3.0.0-alpha.35
+
+**October 21, 2025**
+
+#### React Server Components Support
+- Fixed critical issue where compound components didn't work in React Server Components (RSC)
+- Moved compound pattern logic from components to index files, resolving `"use client"` conflicts
+- **(⚠️ Breaking change)**: Main component now requires `.Root` suffix (e.g., `<Avatar>` → `<Avatar.Root>`)
+- Named exports remain unchanged and fully supported
+
+#### React 19 Improvements
+- Removed `forwardRef` (now native in [React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop))
+- Simplified Context usage (`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider))
+
+#### Switch Component Refactoring
+- **(⚠️ Breaking change)**: Split Switch and SwitchGroup into separate components
+- Cleaner API: `<SwitchGroup>` replaces `<Switch.Group>` and `<Switch.GroupItems>`
+- Matches Radio/RadioGroup pattern for consistency
+- Separate styles, types, and implementations
+
+#### Affected Components
+All compound components now require `.Root` suffix: `Accordion`, `Avatar`, `Card`, `Disclosure`, `Fieldset`, `Kbd`, `Link`, `Popover`, `Radio`, `Switch`, `Tabs`, `Tooltip`
+
+[Read full release notes →](/docs/react/releases/v3-0-0-alpha-35)
+
+### v3.0.0-alpha.34
+
+**October 15, 2025**
+
+- Added Form-based components: [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea).
+- Introduced form field tokens `--field-*`
+- Reorganized Storybook by category
+- **(Breaking change)**: Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton)
+- Aligned data-slot markers across components
+- Improved documentation
+
+
+[Read full release notes →](/docs/react/releases/v3-0-0-alpha-34)
+
+### v3.0.0-alpha.33
+
+**October 5, 2025**
+
+- Upgraded RAC with [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html)
+- Reordered [Tabs](/docs/components/tabs) Indicator (**Breaking change**)
+- Updated [Tabs](/docs/components/tabs) component to use React Aria's `SelectionIndicator`, now supports SSR
+- Updated [Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) components to use RAC CSS variables for the expand and collapse animations
+- Updated [Switch](/docs/components/switch) component styles and animations
+- Added `size` variants and added demo in [Switch](/docs/components/switch#sizes)
+- Added related showcases in [Button](/docs/components/button), [Tabs](/docs/components/tabs), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group)
+- Improved documentation
+
+
+[Read full release notes →](/docs/react/releases/v3-0-0-alpha-33)
+
+### v3.0.0-alpha.32
+
+**October 1, 2025**
+
+Card component redesigned with [new variants](/docs/components/card), added [CloseButton](/docs/components/close-button) component, [MCP Server](/docs/ui-for-agents/mcp-server) for AI coding assistants, and improved documentation.
+
+[Read full release notes →](/docs/react/releases/v3-0-0-alpha-32)
+
+### v3.0.0-alpha.31
+
+**September 22, 2025**
+
+- 🎨 **Showcases page** - Gallery of sites built with HeroUI
+- 🌀 **DisclosureGroup component** - Groups multiple disclosures together
+- 📇 **Card component** (preview) - First version of card component
+- 🔀 **Switch component** (preview) - Toggle switch for settings
+
+---
+
+## Release Schedule
+
+HeroUI v3 is now stable. Future releases follow a regular cycle:
+
+- **Patch releases**: Bug fixes and minor improvements as needed
+- **Minor releases**: New components and features, typically monthly
+- **Major releases**: Architectural changes with migration guides
+
+## Contributing
+
+Found an issue or want to contribute? Check out our [GitHub repository](https://github.com/heroui-inc/heroui).
diff --git a/apps/docs/content/docs/en/react/releases/meta.json b/apps/docs/content/docs/en/react/releases/meta.json
new file mode 100644
index 0000000..9e746ec
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/meta.json
@@ -0,0 +1,33 @@
+{
+  "title": "Releases",
+  "description": "HeroUI v3 Release Notes",
+  "icon": "rocket",
+  "root": true,
+  "pages": [
+    "---Overview---",
+    "index",
+    "---Releases---",
+    "v3-2-2",
+    "v3-2-1",
+    "v3-2-0",
+    "v3-1-0",
+    "v3-0-5",
+    "v3-0-4",
+    "v3-0-3",
+    "v3-0-2",
+    "v3-0-0",
+    "v3-0-0-rc-1",
+    "v3-0-0-beta-8",
+    "v3-0-0-beta-7",
+    "v3-0-0-beta-6",
+    "[v3.0.0-beta.5](/docs/react/releases#v300-beta5)",
+    "v3-0-0-beta-4",
+    "v3-0-0-beta-3",
+    "v3-0-0-beta-2",
+    "v3-0-0-beta-1",
+    "v3-0-0-alpha-35",
+    "v3-0-0-alpha-34",
+    "v3-0-0-alpha-33",
+    "v3-0-0-alpha-32"
+  ]
+}
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-32.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-32.mdx
new file mode 100644
index 0000000..4f03c6a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-32.mdx
@@ -0,0 +1,183 @@
+---
+title: v3.0.0-alpha.32
+description: Card component redesign, CloseButton, MCP Server for AI assistants
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">October 1, 2025</span>
+</div>
+
+This release adds AI development tools, updates the [Card component](/docs/components/card) API, and improves the developer experience.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+## What's New
+
+### MCP Server
+
+HeroUI now includes an [MCP server](/docs/ui-for-agents/mcp-server) that lets AI assistants like Cursor, Claude Code, and VS Code Copilot access HeroUI v3 documentation and component information directly.
+
+**Quick Setup:**
+
+### Cursor
+
+<div className="flex items-center gap-3 mb-4">
+  <a
+    href="https://link.heroui.com/mcp-cursor-install"
+    className="button button--tertiary button--sm no-underline bg-default/50 dark:bg-default/30"
+  >
+    <svg viewBox="0 0 466.73 532.09" className="w-5 h-5 fill-current">
+      <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+    </svg>
+    <span className="text-accent">Install in Cursor</span>
+  </a>
+</div>
+
+Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:
+
+```json
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Run this command in your terminal:
+
+```bash
+claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
+```
+
+[Learn more](/docs/ui-for-agents/mcp-server)
+
+### Card Component API Redesign
+
+The [Card component](/docs/components/card) has been updated with a new variant system that makes it more flexible.
+
+**Breaking Changes:**
+- Replaced `surface` prop with new `variant` system
+- Removed `Card.Image`, `Card.Details`, and `Card.CloseButton` (use composition instead)
+- New variants: `flat`, `outlined`, `elevated`, `filled`
+
+**Before:**
+```tsx
+<Card surface="1">
+  <Card.Image src="/image.jpg" />
+  <Card.Details>
+    <Card.Title>Old Card</Card.Title>
+  </Card.Details>
+</Card>
+```
+
+**After:**
+```tsx
+<Card variant="outlined">
+  <Card.Header>
+    <img src="/image.jpg" alt="Card image" />
+  </Card.Header>
+  <Card.Body>
+    <Card.Title>New Card</Card.Title>
+  </Card.Body>
+</Card>
+```
+
+**New Features:**
+- Horizontal layout support
+- Avatar integration
+- Background image support
+- Improved accessibility with semantic HTML
+
+[View Card documentation](/docs/components/card)
+
+### CloseButton Component
+
+Added a [CloseButton component](/docs/components/close-button) for closing dialogs, modals, and other dismissible elements.
+
+```tsx
+import {CloseButton} from "@heroui/react";
+
+// Basic usage
+<CloseButton onPress={() => console.log("Closed")} />
+
+// With custom icon
+<CloseButton>
+  <XMarkIcon className="size-4" />
+</CloseButton>
+```
+
+## Documentation Improvements
+
+### UI for Agents
+- **[MCP Server documentation](/docs/ui-for-agents/mcp-server)** for development with AI assistants
+- **[llms.txt](/docs/ui-for-agents/llms-txt)** file for LLM-friendly documentation
+- Setup guides for popular AI coding tools
+
+### Component Documentation
+- **[Card](/docs/components/card)**: Rewrote documentation with anatomy, variants, and more examples
+- **[Switch](/docs/components/switch)**: Added anatomy diagrams and better examples
+- **[CloseButton](/docs/components/close-button)**: New documentation with usage examples
+
+
+## Migration Guide
+
+### Card Component Migration
+
+1. **Update variant prop:**
+   - `surface="1"` → `variant="flat"`
+   - `surface="2"` → `variant="outlined"`
+   - `surface="3"` → `variant="elevated"`
+   - `surface="4"` → `variant="filled"`
+   - Custom surfaces → Use new variant system
+
+2. **Update component structure:**
+   - Replace `Card.Image` with `<img>` in `Card.Header`
+   - Replace `Card.Details` with `Card.Body`
+   - Move `Card.CloseButton` to use new `CloseButton` component
+
+3. **Update imports:**
+   ```tsx
+   // Add CloseButton if needed
+   import {Card, CloseButton} from "@heroui/react";
+   ```
+
+## Links
+
+- [GitHub PR #5747](https://github.com/heroui-inc/heroui/pull/5747)
+- [MCP Server Documentation](/docs/ui-for-agents/mcp-server)
+- [Card Component Guide](/docs/components/card)
+- [CloseButton Component](/docs/components/close-button)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-33.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-33.mdx
new file mode 100644
index 0000000..ef44130
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-33.mdx
@@ -0,0 +1,112 @@
+---
+title: v3.0.0-alpha.33
+description: RAC upgrade, Tabs indicator redesign, Switch size variant, Related showcase
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">October 5, 2025</span>
+</div>
+
+This release upgrades React Aria Components, redesigns the Tabs indicator, adds Switch sizes, and includes component showcases.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+## What's New
+
+### RAC Upgrade
+
+Upgraded React Aria Components to the [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html).
+
+This release includes:
+- CSS variables for animations
+- Better SSR support
+- Performance improvements for selection indicators
+
+### Disclosure and Disclosure Group Updates
+
+[Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) now use React Aria's CSS variables for animations. The components use `--disclosure-panel-width` and `--disclosure-panel-height` variables that track the panel's actual size during expand/collapse.
+
+### Tabs Indicator Redesign
+
+[Tabs](/docs/components/tabs) now uses React Aria's `SelectionIndicator` and supports SSR. This fixes layout shifts on initial render.
+
+**🚧 Breaking Changes:**
+
+- Moved `Tabs.Indicator` inside each `Tabs.Tab`
+
+**Before:**
+```diff tsx
+<Tabs>
+  <Tabs.ListWrapper>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab>
++       <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+-   <Tabs.Indicator />
+  </Tabs.ListWrapper>
+  <Tabs.Panel/>
+</Tabs>
+```
+
+### Switch Updates
+
+[Switch](/docs/components/switch) has updated styles and animations. Added `size` prop with options: `sm`, `md`, `lg`.
+
+<ComponentPreview name="switch-sizes" />
+
+### Related showcases
+
+Related showcases have been added in [Button](/docs/components/button), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group) and [Tabs](/docs/components/tabs). 
+
+## Documentation Improvements
+
+### Component Documentation
+- **[Tabs](/docs/components/tabs)**: Updated anatomy, revised examples with new indicator design and added related showcase
+- **[Switch](/docs/components/switch)**: Added size example and revised with-icon example
+- **[Button](/docs/components/button)**, **[Disclosure](/docs/components/disclosure)**, **[Disclosure Group](/docs/components/disclosure-group)**: Added related showcase
+
+## Migration Guide
+
+### Tabs Component Migration
+
+1. **Update component structure:**
+   - move `<Tabs.Indicator />` inside each `<Tabs.Tab />`
+
+## Links
+
+- [GitHub PR #5777](https://github.com/heroui-inc/heroui/pull/5777)
+- [Tabs Component](/docs/components/tabs)
+- [Switch Component](/docs/components/switch)
+- [Button Component](/docs/components/button)
+- [Disclosure Component](/docs/components/disclosure)
+- [Disclosure Group Component](/docs/components/disclosure-group)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-34.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-34.mdx
new file mode 100644
index 0000000..3ef6034
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-34.mdx
@@ -0,0 +1,166 @@
+---
+title: v3.0.0-alpha.34
+description: Essentials for building forms with a clean API Form, TextField, RadioGroup, Label, Input, Fieldset and more.
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">October 15, 2025</span>
+</div>
+
+This release introduces Form-based components, form field tokens, reorganizes Storybook, and aligns data-slot markers across components.
+
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Form-based Components
+
+We've introduced a comprehensive set of form-based components built on React Aria Components, providing accessible and composable building blocks for creating forms. These components include [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea).
+
+#### Description
+
+<ComponentPreview
+  name="description-basic"
+/>
+
+#### FieldError
+
+<ComponentPreview
+  name="field-error-basic"
+/>
+
+#### Fieldset
+
+<ComponentPreview
+  name="fieldset-basic"
+/>
+
+#### Form
+
+<ComponentPreview
+  name="form-basic"
+/>
+
+#### Input
+
+<ComponentPreview
+  name="input-basic"
+/>
+
+#### Label
+
+<ComponentPreview
+  name="label-basic"
+/>
+
+#### RadioGroup
+
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+#### TextField
+
+<ComponentPreview
+  name="text-field-basic"
+/>
+
+#### TextArea
+
+<ComponentPreview
+  name="textarea-basic"
+/>
+
+### Form Field Tokens
+
+Introduced form field tokens `--field-*` for consistent styling across form components. See [Theming](/docs/handbook/theming#calculated-variables-tailwind) for the `--field-*` variables.
+
+### Storybook Organization
+
+Reorganized Storybook by category for better navigation and component discovery.
+
+### Skeleton Animation Token
+
+**🚧 Breaking Changes:** Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton) for consistency with other component tokens.
+
+### Data-Slot Alignment
+
+Aligned data-slot markers across components for consistent styling and customization. This standardization makes it easier to target specific component parts with CSS selectors and improves the overall developer experience when customizing component styles.
+
+Components now use consistent `data-slot` attributes like:
+- `data-slot="base"` for the root element
+- `data-slot="label"` for label text
+- `data-slot="description"` for description text
+- `data-slot="error"` for error messages
+
+This allows for predictable CSS targeting across all form components:
+
+```css
+.radio {
+  [data-slot="label"] {
+    /* Styles apply to radio labels */
+  }
+}
+``` 
+
+## Documentation Improvements
+
+### Component Documentation
+- **[Link](/docs/components/link)**: Added Anatomy, and examples with Icon. Updated Link and Link.Icon props section.
+- **[Description](/docs/components/description)**, **[FieldError](/docs/components/field-error)**, **[Fieldset](/docs/components/fieldset)**, **[Form](/docs/components/form)**, **[Input](/docs/components/input)**, **[Label](/docs/components/label)**, **[RadioGroup](/docs/components/radio-group)**, **[TextField](/docs/components/text-field)**, and **[TextArea](/docs/components/textarea)**: New documentation with usage examples
+
+
+## Migration Guide
+
+### Skeleton Component Migration
+
+1. **Update animation token:**
+   - Replace `--skeleton-default-animation-type` with `--skeleton-animation`
+
+## Links
+
+- [GitHub PR #5780](https://github.com/heroui-inc/heroui/pull/5780)
+- [Description Component](/docs/components/description)
+- [FieldError Component](/docs/components/field-error)
+- [Fieldset Component](/docs/components/fieldset)
+- [Form Component](/docs/components/form)
+- [Input Component](/docs/components/input)
+- [Label Component](/docs/components/label)
+- [RadioGroup Component](/docs/components/radio-group)
+- [TextField Component](/docs/components/text-field)
+- [TextArea Component](/docs/components/textarea)
+- [Skeleton Component](/docs/components/skeleton)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-35.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-35.mdx
new file mode 100644
index 0000000..a85b3dd
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-alpha-35.mdx
@@ -0,0 +1,401 @@
+---
+title: v3.0.0-alpha.35
+description: React Server Components support for compound components, React 19 improvements, and critical bug fixes.
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">October 21, 2025</span>
+</div>
+
+This release fixes a critical issue where **compound components didn't work correctly in React Server Components (RSC)**. Additionally, this release adopts React 19 best practices by removing `forwardRef` and simplifying context usage. The Switch component has been refactored to match the Radio/RadioGroup pattern, providing a cleaner and more consistent API.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@alpha @heroui/react@alpha
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### React Server Components Support
+
+Compound components now work correctly in React Server Components. The previous implementation had the compound pattern logic inside components, which conflicted with the `"use client"` directive. This has been fixed by moving the pattern logic to component index files.
+
+### React 19 Improvements
+
+This release adopts React 19 best practices:
+
+1. **Removed `forwardRef`**: No longer needed in React 19, where `ref` is now a prop ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop))
+2. **Simplified Context**: `Context.Provider` replaced with just `Context` ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider))
+
+### Switch Component Architecture Improvement
+
+The Switch component has been refactored to follow the same clean separation pattern as Radio/RadioGroup:
+
+- **Separate Components**: Switch and SwitchGroup are now independent components (previously combined)
+- **Cleaner API**: `<SwitchGroup>` replaces the nested `<Switch.Group>` and `<Switch.GroupItems>` pattern
+- **Better Organization**: Separate styles, types, and implementations for each component
+- **Consistent Pattern**: Matches the Radio/RadioGroup architecture for a more predictable API
+
+**Before:**
+```tsx
+<Switch.Group>
+  <Switch.GroupItems>
+    <Switch.Root>...</Switch.Root>
+  </Switch.GroupItems>
+</Switch.Group>
+```
+
+**After:**
+```tsx
+<SwitchGroup>
+  <Switch.Root>...</Switch.Root>
+  <Switch.Root>...</Switch.Root>
+</SwitchGroup>
+```
+
+## ⚠️ Breaking Changes
+
+### Main Component Requires `.Root` Suffix
+
+To support React Server Components, the compound component pattern has been restructured. The main component now requires the `.Root` suffix when using the compound pattern.
+
+**Before:**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar>
+  <Avatar.Image src="/images/avatar.jpeg" alt="Junior Garcia" />
+  <Avatar.Fallback>JR</Avatar.Fallback>
+</Avatar>
+```
+
+**After:**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar.Root>
+  <Avatar.Image src="/images/avatar.jpeg" alt="Junior Garcia" />
+  <Avatar.Fallback>JR</Avatar.Fallback>
+</Avatar.Root>
+```
+
+**Note:** Named exports (e.g., `<Avatar>`, `<AvatarImage>`, `<AvatarFallback>`) remain unchanged and fully supported.
+
+### Switch Component API Changes
+
+The Switch component grouping API has been restructured to match the Radio/RadioGroup pattern:
+
+**Before:**
+```tsx
+import { Switch } from "@heroui/react"
+
+<Switch.Group orientation="horizontal">
+  <Switch.GroupItems>
+    <Switch.Root name="notifications">
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Notifications</Label>
+    </Switch.Root>
+    <Switch.Root name="marketing">
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Label>Marketing</Label>
+    </Switch.Root>
+  </Switch.GroupItems>
+</Switch.Group>
+```
+
+**After:**
+```tsx
+import { Switch, SwitchGroup } from "@heroui/react"
+
+<SwitchGroup orientation="horizontal">
+  <Switch.Root name="notifications">
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    <Label>Notifications</Label>
+  </Switch.Root>
+  <Switch.Root name="marketing">
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    <Label>Marketing</Label>
+  </Switch.Root>
+</SwitchGroup>
+```
+
+This change helps to:
+
+- **Separate Components**: Switch and SwitchGroup are now independent components (previously combined)
+- **Cleaner API**: `<SwitchGroup>` replaces the nested `<Switch.Group>` and `<Switch.GroupItems>` pattern
+- **Better Organization**: Separate styles, types, and implementations for each component
+- **Consistent Pattern**: Matches the Radio/RadioGroup architecture for a more predictable API
+
+
+**Migration Steps:**
+1. Import `SwitchGroup` separately: `import { Switch, SwitchGroup } from "@heroui/react"`
+2. Replace `<Switch.Group>` with `<SwitchGroup>`
+3. Remove the nested `<Switch.GroupItems>` wrapper
+4. Individual `Switch.Root` components remain unchanged
+
+#### Affected Components
+
+All compound components are affected:
+
+- `Accordion` → `Accordion.Root`
+- `Avatar` → `Avatar.Root`
+- `Card` → `Card.Root`
+- `Disclosure` → `Disclosure.Root`
+- `Fieldset` → `Fieldset.Root`
+- `Kbd` → `Kbd.Root`
+- `Link` → `Link.Root`
+- `Popover` → `Popover.Root`
+- `RadioGroup` → `RadioGroup.Root`
+- `Switch` → `Switch.Root`
+- `Tabs` → `Tabs.Root`
+- `Tooltip` → `Tooltip.Root`
+
+## Migration Guide
+
+You have two options for using HeroUI compound components:
+
+### Option 1: Update to Use `.Root` (Compound Pattern)
+
+If you're using the compound pattern (dot notation), update your code to use `.Root` for the main component:
+
+**Card Example:**
+```tsx
+import { Card } from "@heroui/react"
+
+<Card.Root>
+  <Card.Header>
+    <Card.Title>Card Title</Card.Title>
+    <Card.Description>Card description</Card.Description>
+  </Card.Header>
+  <Card.Content>
+    Card content
+  </Card.Content>
+  <Card.Footer>
+    Card footer
+  </Card.Footer>
+</Card.Root>
+```
+
+**Tabs Example:**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs.Root>
+  <Tabs.ListWrapper>
+    <Tabs.List>
+      <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListWrapper>
+  <Tabs.Panel id="tab1">Panel 1</Tabs.Panel>
+  <Tabs.Panel id="tab2">Panel 2</Tabs.Panel>
+</Tabs.Root>
+```
+
+[See more examples in the documentation](/docs/components/card)
+
+**Avatar Example:**
+```tsx
+import { Avatar } from "@heroui/react"
+
+<Avatar.Root>
+  <Avatar.Image alt="John Doe" src="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+```
+
+[See more examples in the documentation](/docs/components/avatar)
+
+### Option 2: Use Named Exports
+
+We added support for named exports for all compound components. You can use them like this:
+
+**Card Example:**
+```tsx
+import {
+  CardRoot,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from "@heroui/react"
+
+<CardRoot>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Card content
+  </CardContent>
+  <CardFooter>
+    Card footer
+  </CardFooter>
+</CardRoot>
+```
+
+**Tabs Example:**
+```tsx
+import { TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabPanel } from "@heroui/react"
+
+<TabsRoot>
+  <TabListContainer>
+    <TabList>
+      <Tab id="tab1">Tab 1<TabIndicator /></Tab>
+      <Tab id="tab2">Tab 2<TabIndicator /></Tab>
+    </TabList>
+  </TabListContainer>
+  <TabPanel id="tab1">Panel 1</TabPanel>
+  <TabPanel id="tab2">Panel 2</TabPanel>
+</TabsRoot>
+```
+
+**Avatar Example:**
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@heroui/react"
+
+<Avatar>
+  <AvatarImage alt="John Doe" src="..." />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+### Migration Steps
+
+If you're using the compound pattern, you only need to update the main component to use `.Root`:
+
+1. **Find all instances of compound components** (e.g., `<Avatar>` with `<Avatar.Image>` inside)
+
+2. **Add `.Root` to the main component**:
+   ```tsx
+   // Before
+   <Avatar>
+     <Avatar.Image ... />
+   </Avatar>
+
+   // After
+   <Avatar.Root>
+     <Avatar.Image ... />
+   </Avatar.Root>
+   ```
+
+3. **That's it!** All child components (e.g., `Avatar.Image`, `Avatar.Fallback`) remain unchanged.
+
+### Complete Migration Reference
+
+| Component | Named Export Pattern | Compound Pattern (with `.Root`) | Additional Changes |
+|-----------|---------------------|---------------------|---------------------|
+| **Accordion** | `<Accordion>` | `<Accordion.Root>` | - |
+| **Avatar** | `<Avatar>` | `<Avatar.Root>` | - |
+| **Card** | `<Card>` | `<Card.Root>` | - |
+| **Disclosure** | `<Disclosure>`  | `<Disclosure.Root>`  | - |
+| **Fieldset** | `<Fieldset>`  | `<Fieldset.Root>` | - |
+| **Kbd** | `<Kbd>` | `<Kbd.Root>`  | - |
+| **Link** | `<Link>` | `<Link.Root>` | - |
+| **Popover** | `<Popover>` | `<Popover.Root>` | - |
+| **Radio** |  `<Radio>` | `<Radio.Root>` | - |
+| **Switch** | `<Switch>`, `<SwitchControl>` | `<Switch.Root>`, `<Switch.Control>` | `<Switch.Group>` → `<SwitchGroup>` (separate component) |
+| **Tabs** | `<Tabs>`, `<TabList>` | `<Tabs.Root>`, `<Tabs.List>` | - |
+| **Tooltip** | `<Tooltip>`, `<TooltipTrigger>` | `<Tooltip.Root>`, `<Tooltip.Trigger>` | - |
+
+### Automated Migration
+
+For large codebases using the compound pattern, you can use find-and-replace:
+
+```bash
+# Example for Avatar component
+# Update the main component to use .Root
+sed -i 's/<Avatar>/<Avatar.Root>/g' **/*.tsx
+sed -i 's/<\/Avatar>/<\/Avatar.Root>/g' **/*.tsx
+
+# Switch component requires additional steps
+# First, ensure SwitchGroup is imported
+# Then replace Switch.Group with SwitchGroup
+sed -i 's/<Switch\.Group/<SwitchGroup/g' **/*.tsx
+sed -i 's/<\/Switch\.Group>/<\/SwitchGroup>/g' **/*.tsx
+
+# Remove Switch.GroupItems wrapper
+sed -i 's/<Switch\.GroupItems>//g' **/*.tsx
+sed -i 's/<\/Switch\.GroupItems>//g' **/*.tsx
+
+# Repeat for other compound components (Card, Tabs, etc.)
+# Note: This only affects files using the compound pattern
+```
+
+**Important:**
+- Be careful with automated replacements. Make sure you're only replacing compound pattern usage, not named exports.
+- For Switch migrations, verify that `SwitchGroup` is imported: `import { Switch, SwitchGroup } from "@heroui/react"`
+- Test your code after running automated migrations to ensure all changes are correct.
+
+## Why This Change?
+
+This change was necessary to fix React Server Components compatibility. The previous implementation had architectural limitations:
+
+1. **RSC Compatibility**: Compound pattern logic conflicted with `"use client"` directives
+2. **React 19 Readiness**: Removes deprecated patterns like `forwardRef` and `Context.Provider`
+3. **Cleaner Architecture**: Pattern logic is now in index files, not component files
+4. **Better Separation**: Server and client components can now work together seamlessly
+
+## Documentation Updates
+
+Component documentation will be updated to reflect the new patterns:
+
+- Examples will show the compound pattern with `.Root`
+- Named export examples remain valid and supported
+- Migration guides will help you transition smoothly
+- Both patterns are fully supported and work identically
+
+## Need Help?
+
+If you encounter any issues during migration:
+
+1. **Compound pattern users**: Update the main component to use `.Root` (e.g., `<Avatar>` → `<Avatar.Root>`)
+2. **Named export users**: No changes needed - your code continues to work as-is
+3. Check the component documentation for examples
+4. Report issues at: [GitHub Issues](https://github.com/heroui-inc/heroui/issues)
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [React Server Components](https://react.dev/reference/rsc/server-components)
+- [React 19 Release](https://react.dev/blog/2024/12/05/react-19)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+
+## Contributors
+
+Thanks to everyone who contributed to this release, improving React Server Components support and React 19 compatibility!
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-1.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-1.mdx
new file mode 100644
index 0000000..501d67a
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-1.mdx
@@ -0,0 +1,870 @@
+---
+title: v3.0.0-beta.1
+description: Major redesign with new design system, 8 new components, and improved developer experience.
+github:
+  pull: 5872
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">November 6, 2025</span>
+</div>
+
+This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components redesigned, 8 new components, and improved design system with better color tokens, shadows, and architecture.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### New Design System
+
+We've spent weeks crafting a new design system that merges the soul of HeroUI v2 with the simplicity of v3. Every component has been redesigned with attention to detail, smooth animations, and improved developer experience. The new design system is available in our [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3).
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1.mp4"
+  poster="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1-poster.png"
+  height={430}
+  muted
+/>
+
+The redesign brings:
+- New color system that brings v3's vision to life and stands out for its uniqueness
+- Refined shadow system for better depth perception
+- New variables and tokens for better customization
+- Automatic `isOnSurface` support for form-based components
+- Enhanced border and spacing tokens
+- Better contrast and accessibility
+- Consistent component patterns across web and native
+
+### New Components
+
+This release introduces **8 new** essential components:
+
+- **[Alert](#alert)**: Display important messages and notifications with status indicators.
+- **[Checkbox & CheckboxGroup](#checkbox-checkboxgroup)**: Select multiple items from a list.
+- **[InputOTP](#inputotp)**: One-time password input for authentication flows.
+- **[Listbox](#listbox)**: Display a list of options and allow single or multiple selection.
+- **[Select](#select)**: Dropdown selection component built on top of Listbox.
+- **[Slider](#slider)**: Select a value from a range with custom marks and labels.
+- **[Surface](#surface)**: Base surface component for creating elevated containers.
+
+<span id="alert"></span>
+### Alert
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+<span id="checkbox-checkboxgroup"></span>
+### Checkbox & CheckboxGroup
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+<ComponentPreview
+  name="checkbox-group-basic"
+/>
+
+<span id="inputotp"></span>
+### InputOTP
+
+<ComponentPreview
+  name="input-otp-basic"
+/>
+
+<span id="listbox"></span>
+### Listbox
+
+<ComponentPreview
+  name="list-box-default"
+/>
+
+<span id="select"></span>
+### Select
+
+<ComponentPreview
+  name="select-default"
+/>
+
+<span id="slider"></span>
+### Slider
+
+<ComponentPreview
+  name="slider-default"
+/>
+
+<span id="surface"></span>
+### Surface
+
+<ComponentPreview
+  name="surface-variants"
+/>
+
+### Improved Component APIs
+
+Several components have been refined with better APIs:
+
+- **Link**: Added `underline` and `underlineOffset` props for better customization
+
+<ComponentPreview
+  name="link-basic"
+/>
+
+- **Card**: Improved variants and styling system
+
+<ComponentPreview
+  name="card-with-images"
+/>
+
+- **Chip**: Enhanced with size variants and improved color system
+
+<ComponentPreview
+  name="chip-basic"
+/>
+
+- **Switch**: Redesigned from the ground up with improved visual design and animations
+
+<span id="switch"></span>
+<ComponentPreview
+  name="switch-basic"
+/>
+
+- **RadioGroup**: Redesigned from the ground up with better API and styling
+
+<span id="radiogroup"></span>
+<ComponentPreview
+  name="radio-group-basic"
+/>
+
+### Flexible Component Patterns
+
+HeroUI now supports flexible component syntax. Use compound patterns with or without `.Root`, or named exports - all three patterns work identically.
+
+**Available patterns:**
+
+```tsx
+import { Avatar } from "@heroui/react"
+
+// 1. Compound pattern (no .Root needed) - recommended
+<Avatar>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+
+// 2. Compound pattern with .Root - still supported
+<Avatar.Root>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+
+// 3. Named exports
+import { AvatarRoot, AvatarImage, AvatarFallback } from "@heroui/react"
+
+<AvatarRoot>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</AvatarRoot>
+```
+
+**Simple components** like Button work the same way:
+
+```tsx
+import { Button } from "@heroui/react"
+
+// No .Root needed
+<Button>Label</Button>
+
+// Or with .Root
+<Button.Root>Label</Button.Root>
+
+// Or named export
+import { ButtonRoot } from "@heroui/react"
+<ButtonRoot>Label</ButtonRoot>
+```
+
+**You can mix compound and named exports** in the same component:
+
+```tsx
+import { Avatar, AvatarFallback } from "@heroui/react"
+
+<Avatar>
+  <Avatar.Image src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+This provides:
+- **Simpler API**: Main components no longer require `.Root` suffix
+- **Flexibility**: Choose between compound pattern, compound with `.Root`, or named exports
+- **Backward Compatibility**: The `.Root` pattern still works
+- **Naming Consistency**: Standardized naming (e.g., "Container" instead of "Wrapper")
+
+### Global Animation Control
+
+HeroUI now supports easy global animation control through the `data-reduce-motion` attribute. Simply add `data-reduce-motion="true"` to your `<html>` or `<body>` tag to disable all animations across your application.
+
+```html
+<!DOCTYPE html>
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations will be disabled -->
+</html>
+```
+
+HeroUI automatically respects user motion preferences using the `prefers-reduced-motion` media query and extends Tailwind's `motion-reduce:` variant to support both system preferences and manual control via the data attribute. This provides flexible control over animations while maintaining accessibility best practices.
+
+Learn more about animations and motion preferences in the [Animation documentation](/docs/handbook/animation).
+
+## ⚠️ Breaking Changes
+
+### Design System Variables
+
+#### Panel → Surface & Overlay
+
+The `--panel` variable has been replaced with `--surface` and `--overlay` to better distinguish between non-overlay components (cards, accordions) and floating components (tooltips, popovers, modals).
+
+**Before:**
+```css
+--panel: var(--white);
+--panel-foreground: var(--foreground);
+--shadow-panel: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
+```
+
+**After:**
+```css
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+--overlay: var(--white);
+--overlay-foreground: var(--foreground);
+--shadow-surface: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+--shadow-overlay: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+```
+
+**Migration:**
+- Replace `bg-panel` with `bg-surface` for non-overlay components
+- Replace `bg-panel` with `bg-overlay` for floating components
+- Replace `shadow-panel` with `shadow-surface` or `shadow-overlay`
+- Replace `--color-panel` with `--color-surface` or `--color-overlay`
+
+#### Surface Levels Simplified
+
+The `--surface-1`, `--surface-2`, and `--surface-3` variables have been removed. Surface levels are now automatically calculated from `--surface` using `color-mix`, so you only need to declare the base surface color.
+
+**Before (manual declaration):**
+```css
+--surface-1: var(--background);
+--surface-2: var(--color-neutral-100);
+--surface-3: var(--color-neutral-200);
+```
+
+**After (auto-calculated):**
+```css
+/* You only declare the base surface */
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+
+/* HeroUI automatically calculates these using color-mix */
+--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
+```
+
+**Customization:**
+
+You can override the default calculations using Tailwind's `@theme` directive:
+
+```css
+@theme inline {
+  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
+  --color-surface-tertiary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+  --color-surface-quaternary: color-mix(in oklab, var(--surface) 90%, var(--surface-foreground) 10%);
+}
+```
+
+**Migration:**
+- Replace `bg-surface-1` with `bg-surface` (base surface)
+- Replace `bg-surface-2` with `bg-surface-secondary` (auto-calculated)
+- Replace `bg-surface-3` with `bg-surface-tertiary` (auto-calculated)
+
+The same auto-calculation pattern applies to:
+- **Background shades**: Calculated from `--background` → `background-secondary`, `background-tertiary`, `background-quaternary`
+- **Soft colors**: Calculated from status colors → `accent-soft`, `danger-soft`, `warning-soft`, `success-soft`
+
+#### Border Width Default Changed
+
+The default border width has changed from `1px` to `0px`. Borders are now opt-in rather than default.
+
+**Before:**
+```css
+--border-width: 1px;
+```
+
+**After:**
+```css
+--border-width: 0px; /* no border by default */
+```
+
+**Migration:**
+- If you rely on default borders, explicitly set `border-width` in your custom styles
+- Form fields now use `transparent` borders by default
+
+#### Border Color Default Changed
+
+The default border color opacity has changed from `15%` to `0%` (transparent).
+
+**Before:**
+```css
+--border: oklch(0 0 0 / 15%);
+```
+
+**After:**
+```css
+--border: oklch(0 0 0 / 0%);
+```
+
+**Field Border Default:**
+```css
+--field-border: transparent; /* no border by default on form fields */
+```
+
+#### Shadow System Updates
+
+The shadow system has been completely redesigned with separate shadows for surfaces and overlays.
+
+**Before:**
+```css
+--panel-shadow: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
+--field-shadow: 0 0 0 0 rgba(255, 255, 255, 0.1) inset, 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+```
+
+**After (Light):**
+```css
+--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+```
+
+**After (Dark):**
+```css
+--surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+--overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+--field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+```
+
+#### Accent Color Updates
+
+The accent color has been updated for better contrast and visual appeal.
+
+**Before:**
+```css
+--accent: var(--color-neutral-950);
+--accent-foreground: var(--snow);
+```
+
+**After:**
+```css
+--accent: oklch(0.6204 0.195 253.83);
+--accent-foreground: var(--snow);
+```
+
+#### Status Color Refinements
+
+Success, warning, and danger colors have been refined for better consistency and contrast.
+
+**Success:**
+- **Before:** `oklch(0.5503 0.1244 153.56)`
+- **After:** `oklch(0.7329 0.1935 150.81)`
+- Foreground changed from `var(--snow)` to `var(--eclipse)` in light mode
+
+**Warning:**
+- **Before:** `oklch(0.7186 0.1521 64.85)`
+- **After:** `oklch(0.7819 0.1585 72.33)` (light), `oklch(0.8203 0.1388 76.34)` (dark)
+
+**Danger:**
+- **Before:** `oklch(0.6259 0.1908 29.19)`
+- **After:** `oklch(0.6532 0.2328 25.74)` (light), `oklch(0.594 0.1967 24.63)` (dark)
+
+### Component API Changes
+
+#### Chip Component
+
+The Chip component's `type` prop has been renamed to `color`, and a new `size` prop has been added. A new `soft` variant has been introduced.
+
+**Before:**
+```tsx
+import { Chip } from "@heroui/react";
+
+<Chip type="danger" variant="secondary">Label</Chip>
+```
+
+**After:**
+```tsx
+import { Chip } from "@heroui/react";
+
+<Chip color="danger" variant="soft" size="md">Label</Chip>
+```
+
+**Migration:**
+- Replace `type` prop with `color` prop
+- Use `size` prop (`sm`, `md`, `lg`) to control chip size
+- The `soft` variant provides a subtle appearance for less prominent chips
+
+#### Link Component
+
+The Link component now supports `underline` and `underlineOffset` props, and includes `asChild` support.
+
+**Before:**
+```tsx
+import { Link } from "@heroui/react";
+
+<Link href="#">Link text</Link>
+```
+
+**After:**
+```tsx
+import { Link } from "@heroui/react";
+
+<Link href="#" underline="hover" underlineOffset={4}>Link text</Link>
+```
+
+**New Props:**
+- `underline`: `"none" | "hover" | "always"` - Controls underline visibility
+- `underlineOffset`: `number` - Controls underline offset from text
+
+#### Type Reference Syntax
+
+Due to the dual pattern implementation, type references through the namespace syntax are no longer supported. Use object-style syntax or named type imports instead.
+
+**Before (no longer works):**
+```tsx
+type AvatarProps = Avatar.RootProps
+```
+
+**After (Option 1 - Object-style syntax):**
+```tsx
+type AvatarProps = Avatar["RootProps"]
+```
+
+**After (Option 2 - Named type imports, recommended):**
+```tsx
+import type { AvatarRootProps } from "@heroui/react"
+
+type AvatarProps = AvatarRootProps
+```
+
+This change affects all compound components when accessing prop types.
+
+#### Tabs Component Renaming
+
+The Tabs component's wrapper element has been renamed for consistency:
+
+- **Compound property**: `Tabs.ListWrapper` → `Tabs.ListContainer`
+- **Named export**: `TabListWrapper` → `TabListContainer`
+- **CSS class**: `.tabs__list-wrapper` → `.tabs__list-container`
+- **Data attribute**: `data-slot="tabs-list-wrapper"` → `data-slot="tabs-list-container"`
+
+**Migration:**
+
+Find and replace all instances of `TabListWrapper` with `TabListContainer`:
+
+```bash
+# Component usage
+TabListWrapper → TabListContainer
+Tabs.ListWrapper → Tabs.ListContainer
+
+# CSS selectors (if using custom styles)
+.tabs__list-wrapper → .tabs__list-container
+[data-slot="tabs-list-wrapper"] → [data-slot="tabs-list-container"]
+```
+
+#### Removed Variables
+
+The following variables have been removed:
+- `--panel` → Use `--surface` or `--overlay`
+- `--panel-foreground` → Use `--surface-foreground` or `--overlay-foreground`
+- `--surface-1`, `--surface-2`, `--surface-3` → Use background shades or surface levels
+- `--accent-soft` → Use `--color-accent-soft` (now calculated)
+- `--radius-panel` and `--radius-panel-inner` → Use standard radius values
+
+## Design System Updates
+
+### New Color System
+
+#### Surface vs Overlay Concept
+
+The design system now distinguishes between two types of elevated components:
+
+- **Surface**: Used for non-overlay components like cards, accordions, and disclosure groups that sit on the page
+- **Overlay**: Used for floating components like tooltips, popovers, modals, and menus that appear above the page
+
+This distinction provides:
+- Better visual hierarchy
+- Appropriate shadow depths
+- Improved dark mode contrast
+- Clearer component semantics
+
+#### Auto-Calculated Color System
+
+HeroUI now automatically calculates shade levels and soft color variants using CSS `color-mix`. You only need to declare the base colors, and HeroUI handles the rest.
+
+**Background Shade Levels**
+
+Background shades are automatically calculated from `--background`:
+
+```css
+/* You only declare the base */
+--background: oklch(0.9702 0 0);
+--foreground: var(--eclipse);
+
+/* HeroUI automatically calculates these */
+--color-background-secondary: color-mix(in oklab, var(--color-background) 96%, var(--color-foreground) 4%);
+--color-background-tertiary: color-mix(in oklab, var(--color-background) 92%, var(--color-foreground) 8%);
+--color-background-quaternary: color-mix(in oklab, var(--color-background) 86%, var(--color-foreground) 14%);
+```
+
+**Surface Levels**
+
+Surface levels are automatically calculated from `--surface`:
+
+```css
+/* You only declare the base */
+--surface: var(--white);
+--surface-foreground: var(--foreground);
+
+/* HeroUI automatically calculates these */
+--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
+--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
+```
+
+**Soft Color Variants**
+
+Soft color variants are automatically calculated from status colors:
+
+```css
+/* You declare the base status colors */
+--accent: oklch(0.6204 0.195 253.83);
+--danger: oklch(0.6532 0.2328 25.74);
+--warning: oklch(0.7819 0.1585 72.33);
+--success: oklch(0.7329 0.1935 150.81);
+
+/* HeroUI automatically calculates these at 15% opacity */
+--color-accent-soft: color-mix(in oklab, var(--color-accent) 15%, transparent);
+--color-danger-soft: color-mix(in oklab, var(--color-danger) 15%, transparent);
+--color-warning-soft: color-mix(in oklab, var(--color-warning) 15%, transparent);
+--color-success-soft: color-mix(in oklab, var(--color-success) 15%, transparent);
+```
+
+Each soft variant includes hover states (20% opacity) and foreground colors for proper contrast.
+
+**Customization:**
+
+You can override any auto-calculated values using Tailwind's `@theme` directive:
+
+```css
+@theme inline {
+  /* Adjust surface levels */
+  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
+
+  /* Adjust soft colors */
+  --color-accent-soft: color-mix(in oklab, var(--color-accent) 20%, transparent);
+}
+```
+
+This auto-calculation system reduces the number of variables you need to manage while providing full customization when needed.
+
+### Shadow System
+
+The shadow system has been redesigned to provide:
+- Separate shadows for surfaces and overlays
+- Better depth perception
+- Dark mode support (transparent shadows)
+- Consistent field shadows
+
+Shadows automatically adapt to light and dark modes, providing appropriate depth cues for each theme.
+
+### Focus System
+
+The focus color now uses the accent color for consistency:
+
+```css
+--focus: var(--accent);
+```
+
+This ensures focus indicators align with your brand colors while maintaining accessibility.
+
+### Typography Tokens
+
+Several typography-related variables have been removed in favor of using Tailwind's typography utilities directly. The design system now focuses on color and spacing tokens, letting Tailwind handle typography.
+
+## Migration Guide
+
+### Step 1: Update Design System Variables
+
+Replace old panel variables with surface/overlay:
+
+```css
+/* Before */
+.my-card {
+  background: var(--panel);
+  box-shadow: var(--shadow-panel);
+}
+
+/* After */
+.my-card {
+  background: var(--surface);
+  box-shadow: var(--shadow-surface);
+}
+
+.my-tooltip {
+  background: var(--overlay);
+  box-shadow: var(--shadow-overlay);
+}
+```
+
+### Step 2: Update Surface Levels
+
+Surface levels are now automatically calculated from `--surface`, so you don't need to manually declare them. Simply use the new utility classes:
+
+```css
+/* Before */
+.bg-surface-1 → .bg-surface (base surface)
+.bg-surface-2 → .bg-surface-secondary (auto-calculated)
+.bg-surface-3 → .bg-surface-tertiary (auto-calculated)
+
+/* You can also use background shades */
+.bg-surface-2 → .bg-background-secondary (auto-calculated from --background)
+.bg-surface-3 → .bg-background-tertiary (auto-calculated from --background)
+```
+
+**Note:** Surface levels (`surface-secondary`, `surface-tertiary`, etc.) are automatically calculated based on your `--surface` color. No manual CSS variables needed unless you want to customize the calculations.
+
+### Step 3: Update Component Props
+
+Update Chip and Link components:
+
+```tsx
+// Chip: type → color, add size if needed
+<Chip type="danger" /> → <Chip color="danger" size="md" />
+
+// Link: Add underline props if customizing underlines
+<Link href="#">Text</Link> // Still works, underline props are optional
+```
+
+### Step 4: Simplify Component Patterns (Optional)
+
+If you adopted the `.Root` suffix from v3.0.0-alpha.35, you can now simplify your code by removing it:
+
+**Before (v3.0.0-alpha.35):**
+```tsx
+<Avatar.Root>
+  <Avatar.Image src="..." alt="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+```
+
+**After (simpler):**
+```tsx
+<Avatar>
+  <Avatar.Image src="..." alt="..." />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar>
+```
+
+**Note:** The `.Root` syntax still works if you prefer it.
+
+### Step 5: Update Type References
+
+If you're using namespace syntax for types, switch to object-style syntax or named imports:
+
+**Before:**
+```tsx
+type ButtonProps = Button.RootProps
+```
+
+**After (Option 1 - Object-style):**
+```tsx
+type ButtonProps = Button["RootProps"]
+```
+
+**After (Option 2 - Named imports, recommended):**
+```tsx
+import type { ButtonRootProps } from "@heroui/react"
+
+type ButtonProps = ButtonRootProps
+```
+
+### Step 6: Update Tabs Component
+
+Replace `TabListWrapper` with `TabListContainer`:
+
+**Before:**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs.Root>
+  <Tabs.ListWrapper>
+    <Tabs.List>
+      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListWrapper>
+  <Tabs.Panel id="home">Content</Tabs.Panel>
+</Tabs.Root>
+```
+
+**After:**
+```tsx
+import { Tabs } from "@heroui/react"
+
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List>
+      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="home">Content</Tabs.Panel>
+</Tabs>
+```
+
+### Step 7: Handle Border Changes
+
+If your custom styles rely on default borders:
+
+```css
+/* Add explicit borders where needed */
+.my-component {
+  border-width: 1px;
+  border-color: var(--color-border);
+}
+```
+
+### Step 8: Update Status Colors
+
+If you've customized status colors, review the new values and adjust your custom theme if needed:
+
+```css
+/* Check if your custom status colors need updates */
+--success: oklch(0.7329 0.1935 150.81); /* New value */
+--warning: oklch(0.7819 0.1585 72.33); /* New value */
+--danger: oklch(0.6532 0.2328 25.74); /* New value */
+```
+
+### Automated Migration
+
+For large codebases, you can use find-and-replace:
+
+```bash
+# Panel → Surface
+--panel → --surface
+bg-panel → bg-surface
+shadow-panel → shadow-surface
+
+# Panel → Overlay (for floating components)
+--panel → --overlay (where appropriate)
+bg-panel → bg-overlay (for tooltips, popovers, etc.)
+shadow-panel → shadow-overlay (for floating components)
+
+# Chip type prop
+type=" → color="
+
+# Surface levels
+bg-surface-1 → bg-surface
+bg-surface-2 → bg-surface-secondary
+bg-surface-3 → bg-surface-tertiary
+
+# Tabs component
+TabListWrapper → TabListContainer
+Tabs.ListWrapper → Tabs.ListContainer
+
+# Type references
+Component.RootProps → Component["RootProps"] or use named imports
+```
+
+## Component Updates
+
+### Card Component
+
+Card component has been refined with improved variants and better semantic structure. The component now uses the new surface system for consistent styling.
+
+### Accordion Component
+
+Accordion now uses the surface system for better visual consistency with other components.
+
+### Form Components
+
+Form components (Input, TextField, TextArea) have been updated to use the new field border system (transparent by default) for a cleaner look while maintaining accessibility.
+
+### Component Pattern Updates
+
+All components now support flexible patterns. Components that support the dual pattern include:
+
+- **Simple components**: Button, Link, Spinner, Chip, Kbd
+- **Compound components**: Accordion, Avatar, Card, Disclosure, Fieldset, Popover, RadioGroup, Switch, Tabs, Tooltip
+
+You can use any of the three patterns (compound without `.Root`, compound with `.Root`, or named exports) with all these components.
+
+## HeroUI Pro
+
+HeroUI Pro is being reshaped from the ground up on top of the new design system. The new Pro version will feature:
+- New components built on top of HeroUI v3
+- Tailwind CSS v4 native support
+- CSS native animations
+- Enhanced customization options
+
+We'll share more updates soon.
+
+## Roadmap
+
+We're working towards a stable release in **Q4** this year (2025). This beta release brings us significantly closer to that goal with:
+- Comprehensive component set
+- Refined design system
+- Improved developer experience
+- Better performance
+
+## Community
+
+The reception on the native side has been phenomenal. Thank you for supporting us as we build HeroUI v3! Your feedback helps us improve every day.
+
+See what the community is saying: [HeroUI Native Reception](https://x.com/hero_ui/status/1985721976220966926)
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [HeroUI Native](https://link.heroui.com/native)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5872](https://github.com/heroui-inc/heroui/pull/5872)
+
+## Contributors
+
+Thanks to everyone who contributed to this release, helping us create a design system that's both beautiful and practical!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-2.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-2.mdx
new file mode 100644
index 0000000..9be4c70
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-2.mdx
@@ -0,0 +1,307 @@
+---
+title: v3.0.0-beta.2
+description: Six new components (AlertDialog, ComboBox, Dropdown, InputGroup, Modal, NumberField), Select API improvements, and component refinements.
+github:
+  pull: 5885
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">November 20, 2025</span>
+</div>
+
+This release introduces six essential new components, improves the Select component API, and includes various refinements and bug fixes.
+
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-dark@2x.jpg"
+  alt="HeroUI v3 Beta 2"
+/>
+
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### New Components
+
+This release introduces **6 new** essential components:
+
+- **[AlertDialog](#alert-dialog)**: Modal dialog for important decisions that require user confirmation. ([Documentation](/docs/components/alert-dialog))
+- **[ComboBox](#combo-box)**: Combines a text input with a listbox, allowing users to filter a list of options. ([Documentation](/docs/components/combo-box))
+- **[Dropdown](#dropdown)**: Displays a list of actions or options that a user can choose. ([Documentation](/docs/components/dropdown))
+- **[InputGroup](#inputgroup)**: Group related input controls with prefix and suffix elements for enhanced form fields. ([Documentation](/docs/components/input-group))
+- **[Modal](#modal)**: Dialog overlay for focused user interactions and important content. ([Documentation](/docs/components/modal))
+- **[NumberField](#numberfield)**: Number input with increment/decrement buttons, validation, and internationalized formatting. ([Documentation](/docs/components/number-field))
+
+### AlertDialog
+
+<ComponentPreview
+  name="alert-dialog-default"
+/>
+
+### ComboBox
+
+<ComponentPreview
+  name="combo-box-default"
+/>
+
+### Dropdown
+
+<ComponentPreview
+  name="dropdown-default"
+/>
+
+
+### Modal
+
+<ComponentPreview
+  name="modal-default"
+/>
+
+### InputGroup
+
+<ComponentPreview
+  name="input-group-with-icon-prefix-and-text-suffix"
+/>
+
+### NumberField
+
+<ComponentPreview
+  name="number-field-basic"
+/>
+
+### Style Improvements
+
+#### Custom Variants and Theme Compatibility
+
+Enhanced CSS variants and theme system for better customization:
+
+**Motion Preferences**:
+- New `motion-safe` variant with `data-reduce-motion="true"` attribute matching
+- Enhanced `motion-reduce` now supports ancestor elements and pseudo-elements
+
+**Dark Mode**:
+- Class and `data-theme="dark"` attribute selectors now take precedence over `prefers-color-scheme`
+- Full support for pseudo-elements in dark mode
+
+**Theme Variables**:
+- Expanded light theme scope to support nested themes (`:root`, `.light`, `.default`, `[data-theme="light"]`, `[data-theme="default"]`)
+
+### Component Improvements
+
+#### Select Component API Update
+
+The Select component's API has been improved for better consistency with other components. The `Content` subcomponent has been renamed to `Popover`.
+
+**Before:**
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Content>
+    <ListBox>
+      {/* items */}
+    </ListBox>
+  </Select.Content>
+</Select>
+```
+
+**After:**
+```tsx
+<Select>
+  <Select.Trigger>
+    <Select.Value />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      {/* items */}
+    </ListBox>
+  </Select.Popover>
+</Select>
+```
+
+#### Chip Component Refinements
+
+Chip component sizes have been updated for better consistency:
+- **Small (`sm`)**: `px-1 py-0 text-xs`
+- **Medium (`md`)**: `text-xs` (now explicitly set)
+- **Large (`lg`)**: `px-3 py-1 text-sm font-medium`
+
+#### Separator Component Enhancement
+
+The Separator component now automatically detects when it's placed inside a surface component (one that uses `bg-surface`) and applies the appropriate divider color for better visibility. A new `isOnSurface` prop is also available for manual control.
+
+**New Calculated Variable:**
+- `--color-separator-on-surface`: A calculated variable (automatically generated using `color-mix`) that ensures the separator is visible when placed on a surface background. Like other calculated variables, it can be overridden in your theme.
+
+**Usage:**
+
+```tsx
+<div className="bg-surface">
+  <Separator isOnSurface />
+</div>
+```
+
+The `isOnSurface` prop is automatically applied when the Separator detects a `SurfaceContext` provider (used by components like Card, Alert, Popover, Modal, etc.).
+
+You can also use the calculated variable directly with Tailwind classes:
+
+```tsx
+<div className="bg-surface">
+  <div className="h-px w-full bg-separator-on-surface" />
+</div>
+```
+
+#### Animation Improvements
+
+- Loading state spinner color updated for better visibility
+- Select and Slider component styles adjusted for improved animations
+- Checkbox animation improved (faster transition)
+- Better support for `prefers-reduced-motion` with pseudo elements
+
+## ⚠️ Breaking Changes
+
+### Select Component
+
+The `Select.Content` subcomponent has been renamed to `Select.Popover` for consistency with other components like ComboBox and Dropdown.
+
+**Migration:**
+
+Replace all instances of `Select.Content` with `Select.Popover`:
+
+```tsx
+// Before
+<Select.Content>
+  <ListBox>...</ListBox>
+</Select.Content>
+
+// After
+<Select.Popover>
+  <ListBox>...</ListBox>
+</Select.Popover>
+```
+
+**Type imports:**
+
+```tsx
+// Before
+import type { SelectContentProps } from "@heroui/react"
+
+// After
+import type { SelectPopoverProps } from "@heroui/react"
+```
+
+**Named exports:**
+
+```tsx
+// Before
+import { SelectContent } from "@heroui/react"
+
+// After
+import { SelectPopover } from "@heroui/react"
+```
+
+### CSS Variables and Utilities: Divider → Separator
+
+All CSS variables and utility classes related to `divider` have been renamed to `separator` for consistency with the Separator component name.
+
+**CSS Variables:**
+
+```css
+/* Before */
+border-bottom: 1px solid var(--divider);
+
+/* After */
+border-bottom: 1px solid var(--separator);
+```
+
+**Tailwind Utility Classes:**
+
+```tsx
+// Before
+<div className="bg-divider" />
+<div className="border-divider" />
+
+// After
+<div className="bg-separator" />
+<div className="border-separator" />
+```
+
+**Theme Overrides:**
+
+If you have custom themes that override the divider variable, update them:
+
+```css
+/* Before */
+:root {
+  --divider: oklch(92% 0.004 286.32);
+}
+
+.dark {
+  --divider: oklch(22% 0.006 286.033);
+}
+
+/* After */
+:root {
+  --separator: oklch(92% 0.004 286.32);
+}
+
+.dark {
+  --separator: oklch(22% 0.006 286.033);
+}
+```
+
+## Bug Fixes
+
+- Fixed loading state spinner color for better visibility
+- Fixed bordered focus styles taking precedence over hover states
+- Fixed animation stuttering in documentation
+- Improved modal form styling
+- Enhanced motion reduce support for pseudo elements
+- Fixed mobile hover states sticking after touch interactions by wrapping hover styles in `@media (hover: hover)` media queries. Also simplified data attribute selectors by removing unnecessary `="true"` value checks.
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5885](https://github.com/heroui-inc/heroui/pull/5885)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-3.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-3.mdx
new file mode 100644
index 0000000..0698ce2
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-3.mdx
@@ -0,0 +1,285 @@
+---
+title: v3.0.0-beta.3
+description: Seven new components, fullWidth and hideSeparator support, style fixes, and breaking changes for AlertDialog/Modal backdrop variants and asChild prop removal.
+github:
+  pull: 5923
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">December 19, 2025</span>
+</div>
+
+This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form components and `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion), includes style fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variants.
+
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-dark@2x.jpg"
+  alt="HeroUI v3 Beta 3"
+  href="/docs/changelog/v3-0-0-beta-3"
+/>
+
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### New Components
+
+This release introduces **7 new** essential components:
+
+- **[ButtonGroup](#button-group)**: Groups related buttons with consistent styling and spacing. ([Documentation](/docs/components/button-group))
+- **[DateField](#date-field)**: Date input field with labels, descriptions, and validation built on React Aria DateField. ([Documentation](/docs/components/date-field))
+- **[ErrorMessage](#error-message)**: Low-level error message component for displaying errors in non-form components. ([Documentation](/docs/components/error-message))
+- **[ScrollShadow](#scroll-shadow)**: Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position. ([Documentation](/docs/components/scroll-shadow))
+- **[SearchField](#search-field)**: Search input field with built-in search icon and clear button. ([Documentation](/docs/components/search-field))
+- **[TagGroup](#tag-group)**: Focusable list of tags with support for keyboard navigation, selection, and removal. ([Documentation](/docs/components/tag-group))
+- **[TimeField](#time-field)**: Time input field with labels, descriptions, and validation built on React Aria TimeField. ([Documentation](/docs/components/time-field))
+
+### ButtonGroup
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### DateField
+
+<ComponentPreview
+  name="date-field-basic"
+/>
+
+### ErrorMessage
+
+<ComponentPreview
+  name="error-message-basic"
+/>
+
+### SearchField
+
+<ComponentPreview
+  name="search-field-basic"
+/>
+
+### ScrollShadow
+
+<ComponentPreview
+  name="scroll-shadow-orientation"
+/>
+
+### TagGroup
+
+<ComponentPreview
+  name="tag-group-basic"
+/>
+
+### TimeField
+
+<ComponentPreview
+  name="time-field-basic"
+/>
+
+
+### Full-Width Support
+
+Added `fullWidth` support to form and input components, allowing them to span the full width of their container. This is particularly useful for creating consistent form layouts and responsive designs.
+
+**Supported components:**
+- [ButtonGroup](/docs/components/button-group)
+- [Button](/docs/components/button)
+- [ComboBox](/docs/components/combo-box)
+- [DateField](/docs/components/date-field)
+- [DateInputGroup](/docs/components/date-input-group)
+- [InputGroup](/docs/components/input-group)
+- [Input](/docs/components/input)
+- [NumberField](/docs/components/number-field)
+- [SearchField](/docs/components/search-field)
+- [Select](/docs/components/select)
+- [TextField](/docs/components/text-field)
+- [TextArea](/docs/components/textarea)
+- [TimeField](/docs/components/time-field)
+
+## Component Improvements
+
+### Separator Control Enhancement
+
+Added `hideSeparator` prop to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) components, allowing you to hide separator lines between items for a cleaner, more minimal appearance.
+
+**Tabs:**
+```tsx
+<Tabs hideSeparator>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="analytics">Analytics<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+</Tabs>
+```
+
+**ButtonGroup:**
+```tsx
+<ButtonGroup hideSeparator>
+  <Button>First</Button>
+  <Button>Second</Button>
+  <Button>Third</Button>
+</ButtonGroup>
+```
+
+**Accordion:**
+```tsx
+<Accordion hideSeparator>
+  <Accordion.Item>
+    <Accordion.Heading>
+      <Accordion.Trigger>Item 1</Accordion.Trigger>
+    </Accordion.Heading>
+    <Accordion.Panel>
+      <Accordion.Body>Content</Accordion.Body>
+    </Accordion.Panel>
+  </Accordion.Item>
+</Accordion>
+```
+
+### Documentation Icons Integration
+
+Integrated [@gravity-ui/icons](https://github.com/gravity-ui/icons) into documentation components for consistent icon rendering with improved SSR support and better performance.
+
+## Dependencies
+
+### React Aria Components v1.14.0
+
+Upgraded [react-aria-components](https://react-aria.adobe.com/releases/v1-14-0) to v1.14.0. This release includes:
+
+**Enhancements:**
+- SearchField: Added `isReadOnly` and `isRequired` to render props
+- Tooltip: Added `shouldCloseOnPress` prop
+- Tabs: Support for animated transitions between tab panels
+- Miscellaneous: Support for `setState` callback in `useControlledState`
+
+**Fixes:**
+- ComboBox: Fixed VoiceOver announcement not respecting `aria-label` of ListBoxItem
+- Date and Time: Enhanced error handling for absolute date and date time strings
+- NumberField: Prevented incrementing/decrementing when scrolling on mobile
+- Overlays: Fixed overlay positioning and flipping when boundary container is set
+- Table: Fixed crash in drag and drop when keyboard navigating
+- Various other bug fixes and improvements
+
+For the complete list of changes, see the [React Aria Components v1.14.0 release notes](https://react-aria.adobe.com/releases/v1-14-0).
+
+### Other Dependency Upgrades
+
+- `@internationalized/date`: 3.10.0 → 3.10.1
+- `@radix-ui/react-avatar`: 1.1.10 → 1.1.11
+- `tailwind-merge`: 3.3.1 → 3.4.0
+- `tailwind-variants`: 3.1.1 → 3.2.2
+
+## Style Fixes
+
+### Form Component Disabled State
+
+Fixed disabled state styling for [Input](/docs/components/input) and [TextArea](/docs/components/textarea) components.
+
+### Style Optimizations
+
+- **Improved selector precision**: Enhanced CSS selector specificity for better style isolation and performance
+- **Enhanced animations**: Improved animation performance and smoothness across components
+- **Added no-highlight utility**: Added `no-highlight` utility class to prevent text selection on interactive elements for improved user experience
+- **Optimized will-change properties**: Updated `will-change` CSS properties across components for better animation performance
+- **Removed global scrollbar styling**: Removed global scrollbar styles to prevent conflicts with custom scrollbar implementations and fix modal/overlay interaction issues
+
+## ⚠️ Breaking Changes
+
+### AlertDialog & Modal Backdrop Variant
+
+Renamed `backdropVariant`/`variant` prop value from `"solid"` to `"opaque"` for better semantic clarity. The term "opaque" more accurately describes the backdrop's visual appearance.
+
+**Migration:**
+
+Update all instances of `backdropVariant="solid"` to `backdropVariant="opaque"` for AlertDialog, and `variant="solid"` to `variant="opaque"` for Modal:
+
+```tsx
+// Before
+<AlertDialog.Backdrop backdropVariant="solid">
+  <AlertDialog.Container>
+    {/* content */}
+  </AlertDialog.Container>
+</AlertDialog.Backdrop>
+
+<Modal.Backdrop variant="solid">
+  <Modal.Container>
+    {/* content */}
+  </Modal.Container>
+</Modal.Backdrop>
+
+// After
+<AlertDialog.Backdrop backdropVariant="opaque">
+  <AlertDialog.Container>
+    {/* content */}
+  </AlertDialog.Container>
+</AlertDialog.Backdrop>
+
+<Modal.Backdrop variant="opaque">
+  <Modal.Container>
+    {/* content */}
+  </Modal.Container>
+</Modal.Backdrop>
+```
+
+**Available backdrop variants:**
+- `"opaque"` - Dark backdrop that completely obscures the background (formerly `"solid"`)
+- `"blur"` - Blurred backdrop that softly obscures the background
+- `"transparent"` - Transparent backdrop that keeps the background visible
+
+### Removed `asChild` Prop
+
+Removed the `asChild` prop pattern from components for cleaner APIs, improved type safety, and simplified usage.
+
+For more details about component composition patterns, see the [Composition guide](/docs/handbook/composition).
+
+## Bug Fixes
+
+- Fixed `isInvalid` styles when components are used on surface backgrounds
+- Fixed AlertDialog and Modal re-rendering issues after close
+- Fixed overlay close issue that prevented proper cleanup when closing overlays
+- Fixed Storybook links and navigation issues
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #5923](https://github.com/heroui-inc/heroui/pull/5923)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-4.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-4.mdx
new file mode 100644
index 0000000..9fb3eb4
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-4.mdx
@@ -0,0 +1,328 @@
+---
+title: v3.0.0-beta.4
+description: New Theme Builder, three new components (Autocomplete, Breadcrumbs, Toast), Tabs secondary variant, Input/InputGroup variants, and various improvements.
+github:
+  pull: 6121
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">January 20, 2026</span>
+</div>
+
+<Callout type="warning">
+  **Critical Build Issue Fixed**: This version (beta.4) had a critical build issue that has been fixed in **beta.5**. Please upgrade to `@heroui/styles@3.0.0-beta.5` and `@heroui/react@3.0.0-beta.5` to ensure proper TypeScript declaration generation and export resolution.
+</Callout>
+
+This release introduces the new [Theme Builder](/themes) for visual theme customization, three new components ([Autocomplete](/docs/components/autocomplete), [Breadcrumbs](/docs/components/breadcrumbs), [Toast](/docs/components/toast)), adds secondary variant to [Tabs](/docs/components/tabs), primary/secondary variants to [Input](/docs/components/input) and [InputGroup](/docs/components/input-group), TextArea support for InputGroup, and ⚠️ **breaking changes** removing Link's underline variants and the `isInSurface` prop from form components.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-dark@2x.jpg"
+  alt="HeroUI v3 Beta 4"
+  href="/docs/changelog/v3-0-0-beta-4"
+/>
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Theme Builder
+
+We're excited to introduce the **[Theme Builder](/themes)** - a powerful visual tool for creating and customizing HeroUI themes. Build your perfect theme with real-time preview and export ready-to-use CSS.
+
+**Key features:**
+- **Visual Color Editing**: Adjust colors using OKLCH color pickers with intuitive sliders for lightness, chroma, and hue
+- **Real-time Preview**: See your changes instantly on live component previews
+- **Custom Accent Colors**: Define your brand colors and watch them propagate across all components
+- **Preset Themes**: Start from curated presets like Default, Airbnb, Coinbase, Discord, and more
+- **Export Ready**: Generate CSS variables ready to copy into your project
+- **Light & Dark Mode**: Customize both themes simultaneously with linked or independent values
+- **Keyboard Shortcuts**: Undo/redo support and quick actions for efficient workflow
+
+Try it now at [v3.heroui.com/themes](/themes).
+
+### New Components
+
+This release introduces **3 new** essential components:
+
+- **[Autocomplete](#autocomplete)**: Combines a select with filtering, allowing users to search and select from a list of options. ([Documentation](/docs/components/autocomplete))
+- **[Breadcrumbs](#breadcrumbs)**: Navigation breadcrumbs showing the current page's location within a hierarchy. ([Documentation](/docs/components/breadcrumbs))
+- **[Toast](#toast)**: Display temporary notifications and messages with automatic dismissal and customizable placement. ([Documentation](/docs/components/toast))
+
+### Autocomplete
+
+<ComponentPreview
+  name="autocomplete-default"
+/>
+
+### Breadcrumbs
+
+<ComponentPreview
+  name="breadcrumbs-basic"
+/>
+
+### Toast
+
+<Callout type="warning">
+  This  component is currently in preview and some features might not work as expected.
+</Callout>
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+## Component Improvements
+
+### Tabs Secondary Variant
+
+Added a new `secondary` variant to [Tabs](/docs/components/tabs) with an underline indicator style. The secondary variant supports both horizontal and vertical orientations.
+
+<ComponentPreview
+  name="tabs-secondary"
+/>
+
+**Usage:**
+
+```tsx
+<Tabs variant="secondary">
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="overview">
+        Overview
+        <Tabs.Indicator />
+      </Tabs.Tab>
+      <Tabs.Tab id="analytics">
+        Analytics
+        <Tabs.Indicator />
+      </Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="overview">Content</Tabs.Panel>
+  <Tabs.Panel id="analytics">Content</Tabs.Panel>
+</Tabs>
+```
+
+### Input Variants
+
+Added `primary` and `secondary` variants to the [Input](/docs/components/input) component:
+
+- **`primary`** (default): Standard styling with shadow, suitable for most use cases
+- **`secondary`**: Lower emphasis variant without shadow, suitable for use in Surface components
+
+<ComponentPreview
+  name="input-variants"
+/>
+
+### InputGroup Enhancements
+
+The [InputGroup](/docs/components/input-group) component received several improvements:
+
+**TextArea Support**: Use `InputGroup.TextArea` for multiline text inputs with prefix and suffix elements.
+
+<ComponentPreview
+  name="input-group-with-textarea"
+/>
+
+**Variants**: Added `primary` and `secondary` variants matching the Input component.
+
+<ComponentPreview
+  name="input-group-variants"
+/>
+
+### Button & ButtonGroup Outline Variants
+
+Added a new `outline` variant to both [Button](/docs/components/button) and [ButtonGroup](/docs/components/button-group) components for outlined styling.
+
+<ComponentPreview
+  name="button-outline-variant"
+/>
+
+### AlertDialog Size Support
+
+Added size support to [AlertDialog](/docs/components/alert-dialog) component, allowing you to control the dialog size.
+
+<ComponentPreview
+  name="alert-dialog-sizes"
+/>
+
+### Checkbox Animation Improvements
+
+Faster animation and increased stroke width for better feedback on [Checkbox](/docs/components/checkbox).
+
+<ComponentPreview
+  name="checkbox-basic"
+/>
+
+### Link Text Decoration
+
+The [Link](/docs/components/link) component now uses Tailwind CSS classes for text decoration instead of built-in variants. This provides more flexibility and follows Tailwind conventions.
+
+**Available Tailwind utilities:**
+- `underline` - Always visible underline
+- `no-underline` - Remove underline
+- `hover:underline` - Underline appears on hover
+- `decoration-primary`, `decoration-secondary`, etc. - Set underline color
+- `decoration-1`, `decoration-2`, `decoration-4` - Control thickness
+- `underline-offset-1`, `underline-offset-2`, etc. - Adjust spacing
+
+<ComponentPreview
+  name="link-underline-and-offset"
+/>
+
+## ⚠️ Breaking Changes
+
+### Link Component - Removed Underline Variants
+
+The Link component's built-in `underline` and `underlineOffset` props have been removed. Use Tailwind CSS classes instead for text decoration.
+
+**Before:**
+```tsx
+<Link href="#" underline="hover" underlineOffset={4}>
+  Link text
+</Link>
+```
+
+**After:**
+```tsx
+<Link href="#" className="hover:underline underline-offset-4">
+  Link text
+</Link>
+```
+
+**Available Tailwind classes:**
+- `underline`, `no-underline`, `hover:underline` - Decoration line
+- `decoration-primary`, `decoration-muted`, etc. - Decoration color
+- `decoration-solid`, `decoration-dashed`, `decoration-dotted` - Decoration style
+- `decoration-1`, `decoration-2`, `decoration-4` - Decoration thickness
+- `underline-offset-1`, `underline-offset-2`, `underline-offset-4` - Underline offset
+
+For more details, see the [Link documentation](/docs/components/link).
+
+### Form Components - Removed `isInSurface` Prop
+
+The `isInSurface` prop and automatic surface detection have been removed from form-based components. Instead, use the `variant="secondary"` prop when placing form components inside Surface, Card, or other surface-based containers.
+
+**Before:**
+```tsx
+<Surface>
+  {/* Input automatically detected surface context */}
+  <Input isInSurface />
+</Surface>
+```
+
+**After:**
+```tsx
+<Surface>
+  {/* Use variant="secondary" for surface backgrounds */}
+  <Input variant="secondary" />
+</Surface>
+```
+
+**Affected components:**
+- Input
+- InputGroup
+- TextField
+- TextArea
+- SearchField
+- NumberField
+- DateField
+- TimeField
+- Select
+- ComboBox
+- Autocomplete
+
+The `secondary` variant provides lower emphasis styling without shadow, which is appropriate for use on surface backgrounds.
+
+## Style Fixes
+
+- **Button**: Updated secondary button colors for improved visual consistency
+- **Checkbox**: Optimized animation speed and increased stroke width for better feedback (see [Checkbox Animation Improvements](#checkbox-animation-improvements))
+- **Link**: Updated decoration styles and transition timings
+- **Focus Visible**: Added `:not(:focus)` to focus-visible selectors to prevent conflicts with hover states
+- **Separator**: Fixed styles to only apply to horizontal separator
+
+## Bug Fixes
+
+- Fixed Link with Button variants styling
+- Fixed Fieldset flexbox quirk in Safari with BEM styles
+- Fixed SearchField empty state to properly disable clear button
+- Fixed ButtonGroup context to only apply to direct children
+- Fixed ButtonGroup `BUTTON_GROUP_CHILD` re-export for type declarations
+
+## Dependencies
+
+### Direct Exports from React Aria Components
+
+HeroUI now provides direct exports from react-aria-components for easier access to primitives and utilities. These exports are particularly useful for [React Aria Framework setup](https://react-aria.adobe.com/frameworks).
+
+**Providers:**
+- `RouterProvider` - Configure React Aria links to use your client-side router
+- `I18nProvider` - Set the locale used by React Aria components
+
+**Hooks and Utilities:**
+- `isRTL` - Check if a locale is right-to-left
+- `useLocale` - Access the current locale and direction
+- `useFilter` - Filter and sort collections
+
+**Components:**
+- `Collection` - Collection component for managing lists
+- `ListBoxLoadMoreItem` - ListBox item for loading more items
+
+**i18n Utilities:**
+- `getLocalizationScript` - Get localization script for server-side rendering (from `react-aria-components/i18n`)
+
+All of these can be imported directly from `@heroui/react`:
+
+```tsx
+import {
+  RouterProvider,
+  I18nProvider,
+  isRTL,
+  useLocale,
+  useFilter,
+  getLocalizationScript
+} from "@heroui/react";
+```
+
+## Links
+
+- [Theme Builder](/themes)
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6121](https://github.com/heroui-inc/heroui/pull/6121)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-6.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-6.mdx
new file mode 100644
index 0000000..f9f2871
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-6.mdx
@@ -0,0 +1,373 @@
+---
+title: v3.0.0-beta.6
+description: 6 new color components (ColorPicker, ColorArea, ColorSlider, ColorField, ColorSwatch, ColorSwatchPicker), toast improvements, and various style fixes.
+github:
+  pull: 6129
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 6, 2026</span>
+</div>
+
+This release introduces a comprehensive **Color System** with six new components for color selection and manipulation: [ColorPicker](/docs/components/color-picker), [ColorArea](/docs/components/color-area), [ColorSlider](/docs/components/color-slider), [ColorField](/docs/components/color-field), [ColorSwatch](/docs/components/color-swatch), and [ColorSwatchPicker](/docs/components/color-swatch-picker). Also includes [Separator](/docs/components/separator) variants and various style improvements.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-dark@2x.jpg"
+  alt="HeroUI v3 Beta 6"
+  href="/docs/changelog/v3-0-0-beta-6"
+/>
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Color System
+
+We're excited to introduce a comprehensive **Color System** - a complete suite of components for color selection, manipulation, and display. These components are built on React Aria's color primitives and work together seamlessly.
+
+**Key features:**
+- **Full Color Space Support**: Work with HSL, HSB, and RGB color spaces
+- **Channel-based Editing**: Manipulate individual color channels (hue, saturation, lightness, brightness, red, green, blue, alpha)
+- **Accessible by Default**: Full keyboard navigation and screen reader support
+- **Composable Design**: Mix and match components to build custom color pickers
+
+### New Components
+
+This release introduces **6 new** color components:
+
+- **[ColorPicker](#colorpicker)**: Complete color picker with trigger, popover, and composable internals. ([Documentation](/docs/components/color-picker))
+- **[ColorArea](#colorarea)**: 2D gradient area for selecting two color channels simultaneously. ([Documentation](/docs/components/color-area))
+- **[ColorSlider](#colorslider)**: Single-channel slider for precise color adjustments. ([Documentation](/docs/components/color-slider))
+- **[ColorField](#colorfield)**: Text input for entering and editing color values. ([Documentation](/docs/components/color-field))
+- **[ColorSwatch](#colorswatch)**: Visual color preview with support for transparency. ([Documentation](/docs/components/color-swatch))
+- **[ColorSwatchPicker](#colorswatchpicker)**: Grid of selectable color swatches for quick color selection. ([Documentation](/docs/components/color-swatch-picker))
+
+### ColorPicker
+
+The ColorPicker is a compound component that combines all color components into a complete color selection experience.
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### ColorArea
+
+A 2D gradient area for selecting two color channels at once, typically saturation and brightness.
+
+<ComponentPreview
+  name="color-area-basic"
+/>
+
+### ColorSlider
+
+A slider for adjusting individual color channels like hue, saturation, lightness, or alpha.
+
+<ComponentPreview
+  name="color-slider-basic"
+/>
+
+**With different channels:**
+
+<ComponentPreview
+  name="color-slider-channels"
+/>
+
+### ColorField
+
+A text input field for entering color values directly. Supports various color formats.
+
+<ComponentPreview
+  name="color-field-basic"
+/>
+
+### ColorSwatch
+
+A visual display of a color value with support for transparency patterns.
+
+<ComponentPreview
+  name="color-swatch-basic"
+/>
+
+### ColorSwatchPicker
+
+A grid of color swatches for quick color selection from a predefined palette.
+
+<ComponentPreview
+  name="color-swatch-picker-basic"
+/>
+
+## Component Improvements
+
+### Toast Enhancements
+
+The [Toast](/docs/components/toast) component has been significantly improved with new features and better stability (#6151):
+
+**New Features:**
+- **Loading State**: Added `isLoading` prop to show a spinner instead of the default indicator
+- **Default Timeout**: Toasts now auto-dismiss after 4 seconds by default (configurable via `timeout` prop)
+- **Width Control**: Added `width` prop to `Toast.Provider` for customizable toast width
+- **Adaptive Height**: Toasts now adapt their height based on content
+- **Better Stacking**: Fixed layout shifts when toasts stack using absolute positioning and height synchronization
+- **Improved Close Handling**: Deferred `onClose` callback to prevent toast transition deadlock
+- **Front-most Close Button**: Close button only appears on the front-most toast for cleaner UI
+- **Enhanced Promise Support**: Improved `toast.promise()` with better loading states and error handling
+
+**New Demos:**
+- Promise & Loading states
+- Callbacks and timeout handling
+
+<ComponentPreview
+  name="toast-variants"
+/>
+
+### Separator Variants
+
+Added variants to the [Separator](/docs/components/separator) component for different visual styles.
+
+### Chip Component - Label Slot
+
+The [Chip](/docs/components/chip) component now supports a `Chip.Label` subcomponent for better visual alignment. When removing start or end content (like icons), the label text was too close to the chip edges. Plain text children are automatically wrapped in `<Chip.Label>` for backward compatibility.
+
+**Usage:**
+
+```tsx
+import { Chip } from '@heroui/react';
+
+// Automatic wrapping (backward compatible)
+<Chip>Label text</Chip>
+
+// Explicit label with custom styling
+<Chip>
+  <Chip.Label className="font-bold">Custom Label</Chip.Label>
+</Chip>
+
+// Mixing icons and labels
+<Chip>
+  <Icon icon="gravity-ui:check" />
+  <Chip.Label>With Icon</Chip.Label>
+</Chip>
+```
+
+## Style Fixes
+
+- **Overlay Content**: Fixed blur effect on overlay content (#6136)
+- **Invalid Field**: Converted ring to outline for invalid field states (#6184)
+- **Link with Button**: Fixed styling for Link components using button variants (#6138)
+- **Toast Content**: Fixed vertical alignment of toast content (#6147)
+- **Safari SVG**: Fixed SVG shifting issue in Safari (#6149)
+- **Placeholder Color**: Aligned placeholder color with input text (#6139)
+- **Tooltip**: Removed cursor style from tooltip trigger component
+- **CSS Variables**: Made calculated variables depend only on root variables (#6154)
+
+## Bug Fixes
+
+- Fixed page interactivity during view transitions (#6128)
+- Fixed markdown URL formatting (#6162)
+- Fixed incorrect link to combo box page (#6164)
+- Fixed autocomplete styles import order in index.css
+- Fixed hyphenated format for CSS classes (#6191)
+
+## ⚠️ Breaking Changes
+
+### Toast Component - Container Renamed to Provider
+
+The `Toast.Container` component has been renamed to `Toast.Provider` for better semantic clarity (#6151).
+
+**Before:**
+```tsx
+<Toast.Container placement="bottom" />
+```
+
+**After:**
+```tsx
+<Toast.Provider placement="bottom" />
+```
+
+**Additional Changes:**
+- Default `gap` prop changed from `14` to `12` pixels
+- Default `timeout` is now `4000` (4 seconds) instead of requiring explicit timeout
+- `Toast.Action` has been renamed to `Toast.ActionButton` for consistency
+
+### CSS Class Naming Convention
+
+CSS classes have been renamed to use hyphenated format for consistency (#6141). This follows BEM conventions more closely and improves compatibility with Tailwind CSS.
+
+**Important Note**: The `textarea` class was initially renamed to `text-area` but was rolled back to `textarea` in PR #6191 due to conflicts with Tailwind's native `textarea` class. No changes are needed for TextArea component classes.
+
+#### Component Class Name Changes
+
+The following CSS class names have been updated. If you have custom CSS targeting these classes directly, update your selectors:
+
+| Component | Old Class Name | New Class Name | Notes |
+|-----------|---------------|----------------|-------|
+| **ComboBox** | `.combobox` | `.combo-box` | All related classes updated |
+| | `.combobox__input-group` | `.combo-box__input-group` | |
+| | `.combobox__trigger` | `.combo-box__trigger` | |
+| | `.combobox__popover` | `.combo-box__popover` | |
+| | `.combobox--full-width` | `.combo-box--full-width` | |
+| **ListBox** | `.listbox` | `.list-box` | All related classes updated |
+| **ListBoxItem** | `.listbox-item` | `.list-box-item` | All related classes updated |
+| | `.listbox-item__indicator` | `.list-box-item__indicator` | |
+| | `.listbox-item--default` | `.list-box-item--default` | |
+| | `.listbox-item--danger` | `.list-box-item--danger` | |
+| **ListBoxSection** | `.listbox-section` | `.list-box-section` | All related classes updated |
+| **TextArea** | `.textarea` | `.textarea` | **No change** - Rolled back to avoid Tailwind conflict |
+
+#### Migration Guide
+
+**Before:**
+```css
+/* Custom styles targeting old class names */
+.combobox {
+  /* styles */
+}
+
+.listbox-item {
+  /* styles */
+}
+```
+
+**After:**
+```css
+/* Update to new hyphenated class names */
+.combo-box {
+  /* styles */
+}
+
+.list-box-item {
+  /* styles */
+}
+```
+
+**JavaScript/TypeScript Updates:**
+
+If you're using these class names in JavaScript or TypeScript code:
+
+```tsx
+// Before
+<div className="combobox" />
+<ListBoxItem className="listbox-item" />
+
+// After
+<div className="combo-box" />
+<ListBoxItem className="list-box-item" />
+```
+
+**Note**: Component props and TypeScript types remain unchanged. Only CSS class names have been updated.
+
+### Removed CSS Variables
+
+Several CSS variables have been removed as part of the surface color refactoring (#6204). These variables were either replaced with direct variable references or removed entirely.
+
+#### Surface Color Variables
+
+The following calculated surface color variables have been removed and replaced with direct variable references:
+
+**Removed:**
+- `--color-surface-secondary` (was calculated via `color-mix`)
+- `--color-surface-tertiary` (was calculated via `color-mix`)
+
+**Replacement:**
+These variables now directly reference the base variables defined in `variables.css`:
+- `--color-surface-secondary` → Uses `var(--surface-secondary)` directly
+- `--color-surface-tertiary` → Uses `var(--surface-tertiary)` directly
+
+The base variables `--surface-secondary` and `--surface-tertiary` are now defined directly in `variables.css` instead of being calculated in `theme.css`.
+
+#### On Surface Color Variables
+
+All `--color-on-surface-*` variables have been removed entirely:
+
+**Removed:**
+- `--color-on-surface`
+- `--color-on-surface-foreground`
+- `--color-on-surface-hover`
+- `--color-on-surface-focus`
+- `--color-on-surface-secondary`
+- `--color-on-surface-secondary-foreground`
+- `--color-on-surface-secondary-hover`
+- `--color-on-surface-secondary-focus`
+- `--color-on-surface-tertiary`
+- `--color-on-surface-tertiary-foreground`
+- `--color-on-surface-tertiary-hover`
+- `--color-on-surface-tertiary-focus`
+
+**Migration:**
+
+If you were using these variables, update your code to use the appropriate surface variables directly:
+
+```css
+/* Before */
+.element {
+  background: var(--color-on-surface);
+  color: var(--color-on-surface-foreground);
+}
+
+.element:hover {
+  background: var(--color-on-surface-hover);
+}
+
+/* After */
+.element {
+  background: var(--surface-secondary);
+  color: var(--surface-secondary-foreground);
+}
+
+.element:hover {
+  background: color-mix(in oklab, var(--surface-secondary) 92%, var(--surface-secondary-foreground) 8%);
+}
+```
+
+Or use the Tailwind utilities:
+```tsx
+// Before
+<div className="bg-on-surface text-on-surface-foreground" />
+
+// After
+<div className="bg-surface-secondary text-surface-secondary-foreground" />
+```
+
+**Related PR:** [#6204](https://github.com/heroui-inc/heroui/pull/6204)
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6201](https://github.com/heroui-inc/heroui/pull/6201)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-7.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-7.mdx
new file mode 100644
index 0000000..de8d81b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-7.mdx
@@ -0,0 +1,324 @@
+---
+title: v3.0.0-beta.7
+description: 4 new components (Calendar, RangeCalendar, DatePicker, DateRangePicker) and APIs improvements.
+github:
+  pull: 6237
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">February 19, 2026</span>
+</div>
+
+This release adds 4 new components: [Calendar](/docs/components/calendar), [RangeCalendar](/docs/components/range-calendar), [DatePicker](/docs/components/date-picker), and [DateRangePicker](/docs/components/date-range-picker). Also new: [Switch.Content](#switchcontent) for grouping label and description, and [Tabs.Separator](#tabsseparator) for opt-in separator lines between tabs.
+
+⚠️ **Breaking changes**: `hideSeparator` removed from Tabs; `DateInputGroup` and `ColorInputGroup` moved under `DateField.Group`, `TimeField.Group`, and `ColorField.Group`.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-dark@2x.jpg"
+  alt="HeroUI v3 Beta 7"
+  href="/docs/changelog/v3-0-0-beta-7"
+/>
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Date & Time System
+
+**Date & Time** — Calendar, DatePicker, RangeCalendar, and DateRangePicker built on React Aria date primitives. Supports i18n, time zones, and full keyboard/ARIA accessibility.
+
+**Key features:**
+- **Calendar systems**: Gregorian, Buddhist, Persian, and others
+- **Year picker**: Overlay for quick year navigation
+- **Cell indicators**: Events, availability, or status dots on cells
+- **Range selection**: Date ranges with visual highlighting
+- **Accessible**: Keyboard nav, screen readers, ARIA
+
+All date values use [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`). Wrap with [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) to override locale; read it with [`useLocale`](https://react-aria.adobe.com/useLocale).
+
+### New Components
+
+- **[Calendar](#calendar)**: Single date selection, year picker, indicators, multi-month. ([Docs](/docs/components/calendar))
+- **[RangeCalendar](#rangecalendar)**: Date ranges with range highlighting and multi-month. ([Docs](/docs/components/range-calendar))
+- **[DatePicker](#datepicker)**: Date field + popover calendar. ([Docs](/docs/components/date-picker))
+- **[DateRangePicker](#daterangepicker)**: Two date fields + popover range calendar. ([Docs](/docs/components/date-range-picker))
+
+### Calendar
+
+Single-date calendar with year picker, cell indicators, multi-month view, and i18n calendars.
+
+<ComponentPreview
+  name="calendar-basic"
+/>
+
+**Year Picker:**
+
+<ComponentPreview
+  name="calendar-year-picker"
+/>
+
+
+**International Calendars:**
+
+<ComponentPreview
+  name="calendar-international-calendar"
+/>
+
+### RangeCalendar
+
+Date range selection with range highlighting and multi-month views.
+
+<ComponentPreview
+  name="range-calendar-basic"
+/>
+
+**Multiple Months:**
+
+<ComponentPreview
+  name="range-calendar-multiple-months"
+/>
+
+### DatePicker
+
+Date field + popover calendar. Format options, i18n, custom indicators, validation.
+
+<ComponentPreview
+  name="date-picker-basic"
+/>
+
+**Date and Time (with TimeField):**
+
+<ComponentPreview
+  name="date-picker-format-options"
+/>
+
+### DateRangePicker
+
+Two date fields + popover range calendar.
+
+<ComponentPreview
+  name="date-range-picker-basic"
+/>
+
+## API Improvements
+
+### Switch.Content
+
+`Switch.Content` groups label and description next to the switch control ([#6240](https://github.com/heroui-inc/heroui/pull/6240)).
+
+**Before:**
+```tsx
+import { Switch, Label, Description } from '@heroui/react';
+
+<Switch>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+  <Switch.Content>
+    <Label>Email notifications</Label>
+    <Description>Get notified when someone mentions you</Description>
+  </Switch.Content>
+</Switch>
+```
+
+### Tabs.Separator
+
+The [Tabs](/docs/components/tabs) component now includes an explicit `Tabs.Separator` sub-component for adding visual separator lines between tabs. This replaces the previous automatic CSS pseudo-element separator and the `hideSeparator` prop ([#6243](https://github.com/heroui-inc/heroui/pull/6243)).
+
+Separators are now **opt-in** — add `<Tabs.Separator />` inside each `<Tabs.Tab>` where you want a separator line.
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-with-separator"
+/>
+
+### Field Sub-Component Consolidation
+
+`DateField`, `TimeField`, and `ColorField` now expose their input group sub-components directly, removing the need to import `DateInputGroup` or `ColorInputGroup` separately. See [Breaking Changes](#-breaking-changes) for migration details.
+
+### Breadcrumbs Fix
+
+Props passed to `Breadcrumbs.Item` are now forwarded to the underlying `Link` ([#6233](https://github.com/heroui-inc/heroui/pull/6233)).
+
+## Style Fixes
+
+- **ListBox Item**: Adjusted hover background color from `bg-default-hover` to `bg-default` for consistency
+- **Date Input Group**: Changed segment text from `tabular-nums` to `text-nowrap` for better layout
+- **Date Input Group**: Improved focus-within styles to exclude date picker trigger from field focus highlighting
+
+## Dependencies
+
+- **React Aria Components**: Updated from `1.14.0` to `1.15.0` — adds a new [`render` prop](https://react-aria.adobe.com/customization#dom-elements) for customizing the DOM element rendered by any React Aria component (useful for router links, animation libraries like Motion, etc.)
+- **@react-aria/utils**: Updated from `3.32.0` to `3.33.0`
+- **@react-types/shared**: Updated from `3.32.1` to `3.33.0`
+- **@internationalized/date**: Updated from `3.10.1` to `3.11.0` — date fields now constrain on blur instead of as you type
+- Added `@react-aria/i18n` and `@react-stately/utils` for calendar i18n
+
+## ⚠️ Breaking Changes
+
+### Tabs — `hideSeparator` Prop Removed
+
+The `hideSeparator` prop has been removed from the Tabs component. Separators are now **opt-in** using the new `<Tabs.Separator />` sub-component instead of being automatically generated via CSS pseudo-elements ([#6243](https://github.com/heroui-inc/heroui/pull/6243)).
+
+**Before:**
+```tsx
+{/* Separators shown by default, hidden via prop */}
+<Tabs hideSeparator>
+  <Tabs.List>
+    <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
+    <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
+  </Tabs.List>
+</Tabs>
+```
+
+**After:**
+```tsx
+{/* No separators by default — explicitly add them where needed */}
+<Tabs>
+  <Tabs.List>
+    <Tabs.Tab id="tab1"><Tabs.Indicator />Tab 1</Tabs.Tab>
+    <Tabs.Tab id="tab2"><Tabs.Separator /><Tabs.Indicator />Tab 2</Tabs.Tab>
+  </Tabs.List>
+</Tabs>
+```
+
+**CSS Changes:**
+- Tab separator styles moved from pseudo-element (`.tabs__tab:not(:first-child):before`) to a dedicated `.tabs__separator` class
+- The `[data-hide-separator]` data attribute has been removed
+
+### Field Sub-Component API Changes
+
+`DateInputGroup` and `ColorInputGroup` are no longer exported directly from `@heroui/react`. Their sub-components have been consolidated under their respective field components (`DateField`, `TimeField`, `ColorField`).
+
+#### DateField Changes
+
+**Before:**
+```tsx
+import {DateField, Label, DateInputGroup, Description} from '@heroui/react';
+
+<DateField>
+  <Label>Date</Label>
+  <DateInputGroup>
+    <DateInputGroup.Prefix>...</DateInputGroup.Prefix>
+    <DateInputGroup.Input>
+      {(segment) => <DateInputGroup.Segment segment={segment} />}
+    </DateInputGroup.Input>
+    <DateInputGroup.Suffix>...</DateInputGroup.Suffix>
+  </DateInputGroup>
+  <Description>Pick a date</Description>
+</DateField>
+```
+
+**After:**
+```tsx
+import {DateField, Label, Description} from '@heroui/react';
+
+<DateField>
+  <Label>Date</Label>
+  <DateField.Group>
+    <DateField.Prefix>...</DateField.Prefix>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+    <DateField.Suffix>...</DateField.Suffix>
+  </DateField.Group>
+  <Description>Pick a date</Description>
+</DateField>
+```
+
+#### TimeField Changes
+
+Same pattern as DateField:
+
+| Before | After |
+|--------|-------|
+| `DateInputGroup` | `TimeField.Group` |
+| `DateInputGroup.Input` | `TimeField.Input` |
+| `DateInputGroup.Segment` | `TimeField.Segment` |
+| `DateInputGroup.Prefix` | `TimeField.Prefix` |
+| `DateInputGroup.Suffix` | `TimeField.Suffix` |
+
+#### ColorField Changes
+
+| Before | After |
+|--------|-------|
+| `ColorInputGroup` | `ColorField.Group` |
+| `ColorInputGroup.Input` | `ColorField.Input` |
+| `ColorInputGroup.Prefix` | `ColorField.Prefix` |
+| `ColorInputGroup.Suffix` | `ColorField.Suffix` |
+
+**Usage:**
+
+```tsx
+import {ColorField, Label, ColorInputGroup, ColorSwatch} from '@heroui/react';
+
+<ColorField>
+  <Label>Color</Label>
+  <ColorInputGroup>
+    <ColorInputGroup.Prefix>
+      <ColorSwatch color="#000" />
+    </ColorInputGroup.Prefix>
+    <ColorInputGroup.Input />
+  </ColorInputGroup>
+</ColorField>
+```
+
+**After:**
+```tsx
+import {ColorField, Label, ColorSwatch} from '@heroui/react';
+
+<ColorField>
+  <Label>Color</Label>
+  <ColorField.Group>
+    <ColorField.Prefix>
+      <ColorSwatch color="#000" />
+    </ColorField.Prefix>
+    <ColorField.Input />
+  </ColorField.Group>
+</ColorField>
+```
+
+> **Note:** The underlying CSS classes (`.date-input-group`, `.color-input-group`, etc.) remain unchanged. Only the JavaScript import paths and component names have changed.
+
+## Links
+
+- [Component Documentation](/docs/react/components)
+- [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6237](https://github.com/heroui-inc/heroui/pull/6237)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-beta-8.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-8.mdx
new file mode 100644
index 0000000..69642fc
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-beta-8.mdx
@@ -0,0 +1,174 @@
+---
+title: v3.0.0-beta.8
+description: 3 new components (Badge, Pagination, Table), DateField improvements, and key API/style fixes.
+github:
+  pull: 6270
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">March 2, 2026</span>
+</div>
+
+This release adds three new components: [Badge](/docs/components/badge), [Pagination](/docs/components/pagination), and [Table](/docs/components/table), plus new `InputContainer` composition APIs for [DateField](/docs/components/date-field) and [TimeField](/docs/components/time-field).
+
+⚠️ **Breaking changes**: TextField CSS classes were renamed from `.text-field` to `.textfield`.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-dark@2x.jpg"
+  alt="HeroUI v3 Beta 8"
+  href="/docs/changelog/v3-0-0-beta-8"
+/>
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@beta @heroui/react@beta
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### New Components
+
+- **[Badge](#badge)**: Compact status + count indicator with color, variant, placement, and size options. ([Docs](/docs/components/badge))
+- **[Pagination](#pagination)**: Compound pagination primitives with summary, ellipsis, and previous/next controls. ([Docs](/docs/components/pagination))
+- **[Table](#table)**: Data table primitives with sorting, selection, resizing, async loading, and footer composition. ([Docs](/docs/components/table))
+
+### Badge
+
+New badge primitives for counters, labels, and anchored overlays with `Badge.Anchor` and `Badge.Label`.
+
+<ComponentPreview
+  name="badge-basic"
+/>
+
+### Pagination
+
+New navigation component built with composable parts (`Root`, `Content`, `Item`, `Link`, `Previous`, `Next`, `Summary`, `Ellipsis`).
+
+<ComponentPreview
+  name="pagination-with-ellipsis"
+/>
+
+### Table
+
+Compound data table on React Aria with sortable columns, row selection, custom cells, load-more sentinel rows, and resizable columns.
+
+<ComponentPreview
+  name="table-basic"
+/>
+
+**Custom Cells:**
+
+<ComponentPreview
+  name="table-custom-cells"
+/>
+
+**Pagination:**
+
+<ComponentPreview
+  name="table-pagination"
+/>
+
+**Empty State:**
+
+<ComponentPreview
+  name="table-empty-state"
+/>
+
+## Component + API Improvements
+
+### DateField and TimeField Enhancements
+
+`DateField` and `TimeField` now expose `InputContainer` to wrap input segments between prefix and suffix content.
+
+**Before:**
+```tsx
+<DateField.Group>
+  <DateField.Prefix>...</DateField.Prefix>
+  <DateField.Input>
+    {(segment) => <DateField.Segment segment={segment} />}
+  </DateField.Input>
+  <DateField.Suffix>...</DateField.Suffix>
+</DateField.Group>
+```
+
+**After:**
+```tsx
+<DateField.Group>
+  <DateField.Prefix>...</DateField.Prefix>
+  <DateField.InputContainer>
+    <DateField.Input>
+      {(segment) => <DateField.Segment segment={segment} />}
+    </DateField.Input>
+  </DateField.InputContainer>
+  <DateField.Suffix>...</DateField.Suffix>
+</DateField.Group>
+```
+
+<ComponentPreview
+  name="date-range-picker-input-container"
+/>
+
+## ⚠️ Breaking Changes
+
+### TextField Class + Path Renames
+
+TextField style naming was normalized to avoid conflicts with Tailwind's `text-*` utility prefix.
+
+| Component | Old Class Name | New Class Name | Notes |
+|-----------|---------------|----------------|-------|
+| **TextField Root** | `.text-field` | `.textfield` | Root class renamed |
+| **TextField Full Width** | `.text-field--full-width` | `.textfield--full-width` | Modifier class renamed |
+
+Additional renames in the same change:
+- Style file: `text-field.css` -> `textfield.css`
+- Styles export path: `@heroui/styles/src/components/text-field` -> `@heroui/styles/src/components/textfield`
+
+## Style Fixes
+
+- **RangeCalendar**: Added rounded corners to calendar cells for range selection visuals ([#6270](https://github.com/heroui-inc/heroui/pull/6270))
+
+## Bug Fixes
+
+- Added required-state red asterisk behavior for **DatePicker** and **DateRangePicker** by propagating `data-required` from `isRequired` ([#6270](https://github.com/heroui-inc/heroui/pull/6270))
+- Fixed missing invalid trigger styling in **Autocomplete** and **Select** by scoping invalid styles to root state ([#6270](https://github.com/heroui-inc/heroui/pull/6270))
+- Updated TextField docs/demo references to the new `textfield-*` demo keys and source/style paths ([#6270](https://github.com/heroui-inc/heroui/pull/6270))
+
+## Links
+
+- [Component Documentation](/docs/components)
+- [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6270](https://github.com/heroui-inc/heroui/pull/6270)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0-rc-1.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0-rc-1.mdx
new file mode 100644
index 0000000..142661c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0-rc-1.mdx
@@ -0,0 +1,248 @@
+---
+title: v3.0.0-rc.1
+description: 7 new components (Drawer, ToggleButton, ToggleButtonGroup, Meter, ProgressBar, ProgressCircle, Toolbar), Table & ListBox virtualization, ButtonGroup improvements, and bug fixes.
+github:
+  pull: 6285
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">March 14, 2026</span>
+</div>
+
+Seven new components: [Drawer](/docs/components/drawer), [ToggleButton](/docs/components/toggle-button), [ToggleButtonGroup](/docs/components/toggle-button-group), [Meter](/docs/components/meter), [ProgressBar](/docs/components/progress-bar), [ProgressCircle](/docs/components/progress-circle), and [Toolbar](/docs/components/toolbar). Table and ListBox gain virtualization, ButtonGroup gets a `Separator` sub-component + vertical orientation, and React Aria Components is bumped to v1.16.0.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-light@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-dark@2x.jpg"
+  alt="HeroUI v3 RC 1"
+  href="/docs/changelog/v3-0-0-rc-1"
+/>
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@rc @heroui/react@rc
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### New Components
+
+- **[Drawer](#drawer)**: Slide-out panel with drag-to-dismiss, 4 placements, backdrop variants, scrollable body ([Docs](/docs/components/drawer))
+- **[ToggleButton](#toggle-button)**: Selected/unselected toggle with all button variants + icon-only mode ([Docs](/docs/components/toggle-button))
+- **[ToggleButtonGroup](#toggle-button-group)**: Single or multi-select toggle group, attached/detached layouts, orientation ([Docs](/docs/components/toggle-button-group))
+- **[Meter](#meter)**: Value within a known range — disk usage, password strength, quotas ([Docs](/docs/components/meter))
+- **[ProgressBar](#progress-bar)**: Linear progress, determinate + indeterminate, colors, custom formatting ([Docs](/docs/components/progress-bar))
+- **[ProgressCircle](#progress-circle)**: Circular SVG progress with customizable track + fill circles ([Docs](/docs/components/progress-circle))
+- **[Toolbar](#toolbar)**: Groups buttons, toggles, and separators with horizontal or vertical orientation ([Docs](/docs/components/toolbar))
+
+### Drawer
+
+Slide-out panel overlay with top/bottom/left/right placement, drag-to-dismiss gestures, and backdrop variants. Compound parts: `Trigger`, `Backdrop`, `Content`, `Dialog`, `Header`, `Heading`, `Body`, `Footer`, `Handle`, `CloseTrigger`.
+
+<ComponentPreview
+  name="drawer-basic"
+/>
+
+**Placements:**
+
+<ComponentPreview
+  name="drawer-placements"
+/>
+
+**With Form:**
+
+<ComponentPreview
+  name="drawer-with-form"
+/>
+
+### Toggle Button
+
+Stateful toggle between selected and unselected. All button variants and sizes, icon-only mode, controlled or uncontrolled.
+
+<ComponentPreview
+  name="toggle-button-basic"
+/>
+
+**Variants:**
+
+<ComponentPreview
+  name="toggle-button-variants"
+/>
+
+### Toggle Button Group
+
+Single or multi-select toggle group. Attached (connected) and detached layouts, vertical orientation, full-width, and a `Separator` sub-component.
+
+<ComponentPreview
+  name="toggle-button-group-basic"
+/>
+
+**Selection Mode:**
+
+<ComponentPreview
+  name="toggle-button-group-selection-mode"
+/>
+
+**Attached Mode:**
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### Meter
+
+Value within a known range — disk usage, password strength, quotas. Compound parts: `Root`, `Output`, `Track`, `Fill`.
+
+<ComponentPreview
+  name="meter-basic"
+/>
+
+**Colors:**
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+### Progress Bar
+
+Linear progress indicator with determinate + indeterminate states, color variants, sizes, and custom value display. Compound parts: `Root`, `Output`, `Track`, `Fill`.
+
+<ComponentPreview
+  name="progress-bar-basic"
+/>
+
+**Indeterminate:**
+
+<ComponentPreview
+  name="progress-bar-indeterminate"
+/>
+
+### Progress Circle
+
+Circular SVG progress with `TrackCircle` and `FillCircle` sub-components for direct SVG control. Determinate + indeterminate states.
+
+<ComponentPreview
+  name="progress-circle-basic"
+/>
+
+**Custom SVG:**
+
+<ComponentPreview
+  name="progress-circle-custom-svg"
+/>
+
+### Toolbar
+
+Groups buttons, toggle buttons, and separators into an accessible toolbar. Horizontal or vertical orientation, composes with `ButtonGroup` and `ToggleButtonGroup`.
+
+<ComponentPreview
+  name="toolbar-basic"
+/>
+
+**With Button Group:**
+
+<ComponentPreview
+  name="toolbar-with-button-group"
+/>
+
+## Component Improvements
+
+### ButtonGroup Enhancements
+
+New `ButtonGroup.Separator` sub-component adds an explicit visual divider between buttons. Works in both horizontal and vertical orientations.
+
+<ComponentPreview
+  name="button-group-basic"
+/>
+
+### Table & ListBox Virtualization
+
+Table and ListBox now support virtualization via React Aria's `Virtualizer` for large datasets. `Virtualizer`, `TableLayout`, and `ListLayout` are re-exported from `@heroui/react`.
+
+<ComponentPreview
+  name="table-virtualization"
+/>
+
+### ButtonGroup Orientation
+
+`ButtonGroup` accepts an `orientation` prop (`"horizontal"` | `"vertical"`) with correct border-radius handling and separator direction for both axes. The root element was upgraded from `<div>` to React Aria's `Group` for proper `role="group"` semantics.
+
+<ComponentPreview
+  name="button-group-orientation"
+/>
+
+### ButtonGroup Focus Ring
+
+Focus rings on grouped buttons now use `ring-inset` so they stay within button bounds instead of overlapping neighbors.
+
+### Granular Component Imports
+
+`@heroui/react` now supports per-component subpath entrypoints for more explicit imports ([#6301](https://github.com/heroui-inc/heroui/pull/6301)):
+
+```tsx
+// Before — root entrypoint
+import { Button } from "@heroui/react";
+
+// After — granular subpath import
+import { Button } from "@heroui/react/button";
+```
+
+## Dependencies
+
+Upgraded `react-aria-components` from v1.15.1 to v1.16.0 and related packages:
+
+| Package | Old | New |
+|---------|-----|-----|
+| `react-aria-components` | 1.15.1 | 1.16.0 |
+| `@react-aria/i18n` | 3.12.15 | 3.12.16 |
+| `@react-aria/utils` | 3.33.0 | 3.33.1 |
+| `@react-types/shared` | 3.33.0 | 3.33.1 |
+| `@react-types/color` | 3.1.3 | 3.1.4 |
+| `@internationalized/date` | 3.11.0 | 3.12.0 |
+| `@react-stately/data` | 3.15.1 | 3.15.2 |
+
+## Bug Fixes
+
+- **InputGroup**: Focus styles now trigger only when the actual input/textarea is focused (`:has([data-slot]:focus)`) instead of any focusable child via `:focus-within` ([#6274](https://github.com/heroui-inc/heroui/pull/6274))
+- **Avatar**: Fallback element inherits `border-radius` from the parent instead of hardcoding `rounded-full`, so `className` overrides apply correctly ([#6300](https://github.com/heroui-inc/heroui/pull/6300))
+- **Modal & AlertDialog**: Backdrop click events no longer propagate through portals to parent elements ([#6297](https://github.com/heroui-inc/heroui/pull/6297))
+- **Table**: Fixed header rounding and background color bleeding in Firefox ([#6298](https://github.com/heroui-inc/heroui/pull/6298))
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6285](https://github.com/heroui-inc/heroui/pull/6285)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-0.mdx b/apps/docs/content/docs/en/react/releases/v3-0-0.mdx
new file mode 100644
index 0000000..bb1b6fb
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-0.mdx
@@ -0,0 +1,686 @@
+---
+title: Introducing HeroUI v3
+description: A ground-up rewrite for React and React Native. 75+ web components, 37 native components, Tailwind CSS v4, React Aria, compound architecture, and built for AI-assisted development.
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">March 2026</span>
+</div>
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-v3-release.mp4"
+  height={430}
+  muted
+/>
+
+Every component rewritten. Every animation moved to CSS. Styles decoupled from implementation. A brand-new React Native library. And tooling that treats AI assistants as a primary development interface.
+
+## Overview
+
+### React (Web)
+
+75+ components. [React Aria Components](https://react-aria.adobe.com/) for accessibility. Tailwind CSS v4 + CSS variables for theming. Styles in a standalone package you can use with any framework.
+
+[Jump to details](#compound-components)
+
+### React Native
+
+37 components with shared design tokens, compound pattern, unified animation API, and adaptive presentation modes. Built native on each platform with [Uniwind](https://uniwind.dev/) for Tailwind CSS v4 support.
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  playMode="manual"
+  height={430}
+  muted
+/>
+
+[Jump to details](#heroui-native)
+
+### HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+Premium components, templates, and AI tooling for React and React Native. Command palette, Kanban, DataGrid, Dashboard templates, and more. Pre-sale pricing at [heroui.pro](https://heroui.pro).
+
+[Jump to details](#heroui-pro)
+
+## Design Principles
+
+**Composition over configuration:** v2 components were black boxes. v3 adopts compound components: every internal piece is a real element you can style, move, swap, or remove.
+
+**Styles separated from implementation:** `@heroui/styles` is standalone CSS. `@heroui/react` handles behavior. Use the styles with React, plain HTML + Tailwind, or any framework. BEM class names make every slot customizable globally. Swap themes to change not just variables, but how components look and feel.
+
+**Headless when you want it:** Remove the `@heroui/styles` import and you have a headless library. We maintain functionality and accessibility. You focus on your product.
+
+**Performance by default:** v2 used Framer Motion for every animation. v3 replaced it with native CSS transitions and keyframes. Lighter bundles, GPU-accelerated, no JS animation runtime.
+
+**Accessible from the start:** Migrated from React Aria hooks to [React Aria Components](https://react-aria.adobe.com/). Keyboard navigation, focus management, screen readers, and ARIA attributes are built in.
+
+## Compound Components
+
+Here's what the compound pattern looks like in practice:
+
+```tsx
+<Card>
+  <Card.Header>
+    <Card.Title>Product</Card.Title>
+    <Card.Description>Details about this product.</Card.Description>
+  </Card.Header>
+  <Card.Body>
+    <p>Card content goes here.</p>
+  </Card.Body>
+  <Card.Footer>
+    <Button variant="primary">Buy now</Button>
+  </Card.Footer>
+</Card>
+```
+
+More lines of code. But every piece is a real element you can style, move, or replace. The pattern runs through the entire library, from Accordion to Toast.
+
+<ComponentPreview
+  name="accordion-basic"
+/>
+
+Each compound component shares state through React context. The root component creates a style context, and every child consumes it. You never pass classNames down manually:
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+### Progressive Disclosure
+
+Components support both simple and compound usage. Start with the one-liner. Add structure when you need it:
+
+```tsx
+// One line
+<Button>Submit</Button>
+
+// With icon
+<Button>
+  <Icon icon="gravity-ui:check" />
+  Submit
+</Button>
+
+// Full control
+<Button variant="primary" size="lg" isDisabled={isLoading}>
+  {isLoading ? <Spinner size="sm" /> : <Icon icon="gravity-ui:check" />}
+  {isLoading ? "Saving..." : "Submit"}
+</Button>
+```
+
+<ComponentPreview
+  name="button-variants"
+/>
+
+## Tailwind CSS v4 + CSS Variables
+
+Theming runs on Tailwind CSS v4's native CSS variable layer with OKLCH colors. Every design token is a CSS variable:
+
+```css
+:root {
+  --background: oklch(0.9702 0 0);
+  --foreground: oklch(0.2103 0.0059 285.89);
+  --accent: oklch(0.6204 0.195 253.83);
+  --surface: oklch(100% 0 0);
+  --danger: oklch(0.6532 0.2328 25.74);
+  --radius: 0.5rem;
+}
+```
+
+Tailwind's `@theme` directive maps these tokens to utility classes. `bg-accent`, `text-foreground`, `rounded-lg` all resolve to CSS variables. Light and dark mode switch by swapping the values:
+
+```css
+.dark, [data-theme="dark"] {
+  --background: oklch(12% 0.005 285.823);
+  --foreground: oklch(0.9911 0 0);
+  --surface: oklch(0.2103 0.0059 285.89);
+}
+```
+
+No provider component. No JavaScript theme object. One CSS import, two lines:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+### BEM Classes
+
+Override any component globally through standard CSS:
+
+```css
+@layer components {
+  .button {
+    @apply font-semibold tracking-wide;
+  }
+
+  .button--primary {
+    @apply bg-blue-600 hover:bg-blue-700;
+  }
+}
+```
+
+No className threading. No style prop gymnastics. Your design system overrides happen in CSS, where they belong.
+
+### Custom Themes
+
+Create a theme by defining your own token set. Everything cascades from there:
+
+```css
+@layer base {
+  [data-theme="ocean"] {
+    --accent: oklch(0.450 0.150 230);
+    --background: oklch(0.985 0.015 225);
+    --radius: 0.75rem;
+    --border: oklch(0.50 0.060 230 / 22%);
+  }
+}
+```
+
+Apply it with a single data attribute:
+
+```html
+<html data-theme="ocean">
+```
+
+The [Theme Builder](/themes) generates these variables visually. Pick colors, adjust radius and spacing, export the CSS.
+
+### Selective Imports
+
+Import the full library or pick individual component styles:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles/base" layer(base);
+@import "@heroui/styles/themes/default" layer(theme);
+@import "@heroui/styles/components/button.css" layer(components);
+@import "@heroui/styles/components/card.css" layer(components);
+```
+
+Ship only the CSS you use. No unused component styles in production.
+
+## Animation That Respects Users
+
+All component animations use CSS transitions and keyframes tied to data attributes. Popovers fade in with `[data-entering]`. Buttons scale on `[data-pressed]`. Accordions expand with `[aria-hidden="false"]`.
+
+```css
+.popover[data-entering] {
+  @apply animate-in zoom-in-90 fade-in-0 duration-200;
+}
+
+.button:active,
+.button[data-pressed="true"] {
+  transform: scale(0.97);
+}
+```
+
+### Reduce Motion
+
+Some users need animations disabled. HeroUI extends Tailwind's `motion-reduce:` variant to support both the system preference and a data attribute:
+
+```css
+.button {
+  @apply transition-colors motion-reduce:transition-none;
+}
+```
+
+This responds to the native `prefers-reduced-motion: reduce` media query. It also responds to `data-reduce-motion="true"` on the HTML element, for app-level control:
+
+```html
+<html data-reduce-motion="true">
+  <!-- All HeroUI animations are disabled -->
+</html>
+```
+
+The data attribute overrides the system setting. Set `data-reduce-motion="false"` to force animations on, or remove the attribute to defer to the OS. Every animated component respects this. No opt-in required.
+
+### Bring Your Own Animation Library
+
+Framer Motion, Motion One, or any CSS animation library works alongside HeroUI's built-in transitions:
+
+```tsx
+import { motion } from "framer-motion";
+import { Button } from "@heroui/react";
+
+const MotionButton = motion(Button);
+
+<MotionButton whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}>
+  Animated
+</MotionButton>
+```
+
+## 75+ Components for React
+
+### Date & Time
+
+Six components: Calendar, RangeCalendar, DateField, DatePicker, DateRangePicker, and TimeField. Built on React Aria's internationalized date library with Gregorian, Buddhist, Persian, and other calendar systems by default. Keyboard navigation, screen reader labels, and locale-aware formatting come free.
+
+<ComponentPreview
+  name="date-picker-basic"
+/>
+
+<ComponentPreview
+  name="range-calendar-basic"
+/>
+
+### Color
+
+Six color components: ColorPicker, ColorArea, ColorSlider, ColorField, ColorSwatch, and ColorSwatchPicker. Pick from a 2D area, adjust hue and alpha sliders, enter hex values, or select from a swatch palette.
+
+<ComponentPreview
+  name="color-picker-basic"
+/>
+
+### Data
+
+Need a table with sorting, row selection, column resizing, async loading, and custom cells? Table does all of that. Large datasets get virtualization via React Aria's `Virtualizer`. ListBox shares the same virtualization support.
+
+<ComponentPreview
+  name="table-virtualization"
+/>
+
+### Forms
+
+Thirteen form components: TextField, Select, Autocomplete, ComboBox, Checkbox, CheckboxGroup, RadioGroup, Switch, InputOTP, NumberField, SearchField, Slider, and Fieldset. All integrate with React Aria's form validation. `isRequired`, `isInvalid`, and custom error messages through FieldError work across every one.
+
+<ComponentPreview
+  name="select-default"
+/>
+
+<ComponentPreview
+  name="input-otp-basic"
+/>
+
+### Overlays
+
+Seven overlay components. Drawer supports four placements with drag-to-dismiss gestures. Toast stacks notifications with auto-dismiss and promise support. Menu composes with submenus and sections. Plus Modal, AlertDialog, Popover, and Tooltip.
+
+<ComponentPreview
+  name="drawer-basic"
+/>
+
+<ComponentPreview
+  name="toast-default"
+/>
+
+### Navigation
+
+Tabs, Accordion, Breadcrumbs, Pagination, and Link. Tabs support horizontal and vertical orientation. Accordion supports single or multiple expanded panels.
+
+<ComponentPreview
+  name="tabs-basic"
+/>
+
+### Feedback
+
+ProgressBar and ProgressCircle handle determinate + indeterminate states. Meter maps values to semantic colors: green for safe, yellow for cautious, red for critical. Skeleton and Spinner round out the set.
+
+<ComponentPreview
+  name="meter-colors"
+/>
+
+<ComponentPreview
+  name="skeleton-basic"
+/>
+
+### Buttons & Toggles
+
+Button, ButtonGroup, ToggleButton, ToggleButtonGroup, CloseButton, and Toolbar. ButtonGroup connects buttons with shared borders and supports vertical orientation. Toolbar groups buttons, toggles, and separators into an accessible `role="toolbar"` container.
+
+<ComponentPreview
+  name="toggle-button-group-attached"
+/>
+
+### Granular Imports
+
+Import from the root or from per-component subpaths. Both work:
+
+```tsx
+// Root import
+import { Button, Card, Table } from "@heroui/react";
+
+// Subpath import
+import { Button } from "@heroui/react/button";
+import { Card } from "@heroui/react/card";
+import { Table } from "@heroui/react/table";
+```
+
+## UI for Agents
+
+More developers build by prompting than by reading API docs. HeroUI v3 accounts for that.
+
+### MCP Server
+
+The HeroUI MCP Server connects AI coding assistants (Cursor, Claude Code, VS Code Copilot, Windsurf, Zed) to component docs, props, source code, CSS styles, and theme variables. The AI reads the source of truth directly instead of guessing from training data.
+
+```json
+{
+  "mcpServers": {
+    "heroui-react": {
+      "command": "npx",
+      "args": ["-y", "@heroui/react-mcp@latest"]
+    }
+  }
+}
+```
+
+Ask your AI assistant "update HeroUI to the latest version" and it will compare versions, review the changelog for breaking changes, and apply the necessary code updates automatically.
+
+### Agent Skills
+
+Installable knowledge packs for Cursor and Claude Code. Component patterns, variant usage, theming instructions, and upgrade guides. Preloaded context so the AI writes correct HeroUI code on the first attempt.
+
+### LLMs.txt
+
+Structured documentation files optimized for AI context windows. Published at `/llms.txt` and `/llms-components.txt`, these give any LLM-powered tool a machine-readable summary of HeroUI's API surface.
+
+MCP server, agent skills, LLMs.txt. Three layers that give AI assistants the same access to HeroUI that human developers get from docs.
+
+## HeroUI Native
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-native-v1-release-.mp4"
+  height={430}
+  muted
+/>
+
+HeroUI Native is a brand-new library shipping alongside v3 for the web. Different rendering engine, same mental model. Where the platforms diverge, the APIs adapt to feel native on each.
+
+### Try It on Your Device
+
+Scan the QR code with your device's camera or [Expo Go](https://expo.dev/go) to explore all 37 components live:
+
+<div className="flex justify-center my-6">
+  <img
+    width="200"
+    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+    alt="Expo Go QR Code"
+  />
+</div>
+
+<div className="flex justify-center">
+  **[📱 Open Demo App in Expo Go](https://link.heroui.com/native-demo)**
+</div>
+
+<Callout type="info">
+  **Android users:** If scanning the QR code redirects to a browser and shows a 404 error, open Expo Go first and use its built-in QR scanner instead.
+</Callout>
+
+### 37 Components
+
+Forms, navigation, overlays, feedback, layout. From Button, Input, and Checkbox to Dialog, BottomSheet, Select, Toast, and InputOTP. Components follow the compound pattern:
+
+```tsx
+import { Dialog, Button } from "heroui-native";
+
+<Dialog>
+  <Dialog.Trigger asChild>
+    <Button variant="primary">Open</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Close />
+      <Dialog.Title>Confirm action</Dialog.Title>
+      <Dialog.Description>This cannot be undone.</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog>
+```
+
+### Familiar Across Platforms
+
+If you know HeroUI on the web, most of that knowledge carries over. Familiar component names, dot notation, and prop patterns wherever possible. Where the platforms diverge (layout primitives, gestures, navigation), the APIs adapt to feel native. The mental model stays the same:
+
+```tsx
+// React (web)
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+// React Native — similar API, native behavior
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Profile updated</Alert.Title>
+    <Alert.Description>Your changes have been saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+```
+
+Teams working on both web and mobile share knowledge and patterns. The learning curve between platforms is minimal, even where the components differ.
+
+### Shared Design Tokens
+
+Both platforms read from the same token set. Colors like `accent`, `surface`, `danger`, and `success` resolve identically across web and native. Your brand stays consistent without maintaining two separate systems.
+
+```tsx
+import { View, Text } from "react-native";
+
+<View className="bg-surface p-4 rounded-lg">
+  <Text className="text-foreground text-lg font-semibold">Card Title</Text>
+  <Text className="text-muted text-sm">Consistent on web and mobile.</Text>
+</View>
+```
+
+Tailwind CSS v4 on both platforms. [Uniwind](https://uniwind.dev/) on native, standard Tailwind on web.
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/native-v1-demo/v-1-demo-2.mp4"
+  height={430}
+  muted
+/>
+
+### Unified Animation API
+
+Every animated native component exposes a single `animation` prop. Values, timing, spring configs, enter/exit transitions controlled from one place. Reanimated powers the math, but you never touch it directly:
+
+```tsx
+import { Switch } from "heroui-native";
+
+<Switch
+  animation={{
+    scale: { value: [1, 0.9] },
+    backgroundColor: { value: ["#172554", "#eab308"] },
+  }}
+>
+  <Switch.Thumb />
+</Switch>
+```
+
+Disable animations at any level. Per-component, per-tree, or globally:
+
+```tsx
+// Single component
+<Switch.Thumb animation={false} />
+
+// Entire subtree
+<Card animation="disable-all">...</Card>
+
+// App-wide
+<HeroUINativeProvider config={{ animation: "disable-all" }}>
+  <App />
+</HeroUINativeProvider>
+```
+
+Reduce Motion is automatic. When a user enables it in system settings, all animations stop. No extra code.
+
+### Adaptive Presentation Modes
+
+Popover, Select, and Menu switch between popover, bottom-sheet, and dialog with a single prop. Same component, different presentation depending on context:
+
+```tsx
+<Select presentation="popover">...</Select>
+<Select presentation="bottom-sheet">...</Select>
+<Select presentation="dialog">...</Select>
+```
+
+No other React Native component library does this.
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/native-v1-demo/v-1-demo-3.mp4"
+  height={430}
+  muted
+/>
+
+### Granular Imports
+
+Each native component has its own entry point. Import only what you use:
+
+```tsx
+import { HeroUINativeProvider } from "heroui-native/provider";
+import { Button } from "heroui-native/button";
+import { Card } from "heroui-native/card";
+```
+
+### AI Tooling for Native
+
+HeroUI Native ships with its own MCP Server, agent skills, and LLMs.txt. Same tooling structure as the web library:
+
+```json
+{
+  "mcpServers": {
+    "heroui-native": {
+      "command": "npx",
+      "args": ["-y", "@heroui/native-mcp@latest"]
+    }
+  }
+}
+```
+
+## HeroUI Pro
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
+  alt="HeroUI Pro"
+  href="https://heroui.pro"
+/>
+
+Alongside v3, the pre-sale of [HeroUI Pro](https://heroui.pro) is live. Premium components, templates, and AI tooling for both React and React Native.
+
+### Pro Components
+
+Components beyond the core library: Command palette, Kanban board, Stats dashboard, Filters, Agenda, DataGrid, and more. Accessibility, animations, and platform edge cases are handled. Will be available for both Web and Native.
+
+### Templates
+
+Full-page, responsive starter templates: Dashboard, Mail, Chat, and Finances. Real layouts with real structure. Start from something that works and customize from there.
+
+### Advanced AI Tooling
+
+Pro licenses include premium MCP servers and agent skills with Pro component docs, usage patterns, and upgrade paths baked in.
+
+Pre-sale pricing is live. v2 Pro customers get an upgrade discount. Use the same email or contact support.
+
+[See plans and pricing at heroui.pro](https://heroui.pro)
+
+## Get Started
+
+### React (Web)
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles @heroui/react
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles @heroui/react
+    ```
+  </Tab>
+</Tabs>
+
+Add two lines to your CSS:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+```
+
+### React Native
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm install heroui-native
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add heroui-native
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add heroui-native
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add heroui-native
+    ```
+  </Tab>
+</Tabs>
+
+See the [React docs](/docs/react/getting-started/quick-start) and [React Native docs](/docs/native/getting-started/quick-start) for full setup guides (peer dependencies, Uniwind config, and provider setup).
+
+**Coming from HeroUI v2?** Follow the [Migration Guide](/docs/react/migration) for step-by-step upgrade instructions.
+
+## Figma Kit v3
+
+Every component in HeroUI v3 has a 1:1 match in Figma. Same variants, same naming, same structure. The kit uses auto layout throughout, Figma variables that map directly to code tokens (`--accent`, `--surface`, `--radius`), and Figma's new [slots](https://help.figma.com/hc/en-us/articles/38231200344599-Use-slots-to-build-flexible-components-in-Figma) for flexible component composition. Designers rearrange, swap, and customize parts the same way developers do in code.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cover-figma@2x.jpg"
+  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cover-figma-dark@2x.jpg"
+  alt="HeroUI Figma Kit v3"
+  href="https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3"
+/>
+
+[Get the Figma Kit](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+
+## Acknowledgments
+
+[React Aria](https://react-aria.adobe.com/) gave us the accessibility layer we couldn't build as well on our own. Tailwind CSS v4's native CSS variable approach shaped the entire theming system. The compound component pattern was refined by studying how [Radix](https://www.radix-ui.com/), [Ark UI](https://ark-ui.com/), and [Base UI](https://base-ui.com/) solved composition.
+
+Thanks to every community member who filed issues, tested betas, and gave feedback throughout the alpha and RC cycle. The library is better because of you.
+
+## Links
+
+- [React Docs](/docs/react/getting-started/quick-start)
+- [React Native Docs](/docs/native/getting-started/quick-start)
+- [Theme Builder](/themes)
+- [MCP Server](/docs/ui-for-agents/mcp-server)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-2.mdx b/apps/docs/content/docs/en/react/releases/v3-0-2.mdx
new file mode 100644
index 0000000..f81f79d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-2.mdx
@@ -0,0 +1,93 @@
+---
+title: v3.0.2
+description: Bug fixes, smoother Drawer transitions, new --backdrop theme variable, and style refinements for triggers, arrows, and tags.
+github:
+  pull: 6364
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">April 3, 2026</span>
+</div>
+
+Patch release with bug fixes, style refinements, and a new `--backdrop` theme variable. Drawer transitions are rewritten to native CSS for smoother animations. Overlay triggers now display as `inline-block`, and the default arrow shape for Tooltip + Popover is updated.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### `--backdrop` Theme Variable
+
+New `--backdrop` CSS variable for overlay backdrops ([#6375](https://github.com/heroui-inc/heroui/pull/6375)). Light theme defaults to `rgba(0, 0, 0, 0.5)`, dark to `rgba(0, 0, 0, 0.6)`. [Modal](/docs/components/modal), [AlertDialog](/docs/components/alert-dialog), and [Drawer](/docs/components/drawer) now reference this variable instead of hardcoded values.
+
+Override it globally:
+
+```css
+:root {
+  --backdrop: rgba(0, 0, 0, 0.7);
+}
+```
+
+Or use the utility class directly: `bg-backdrop`.
+
+## Style Improvements
+
+### Trigger `inline-block` Display
+
+Trigger elements across Popover, Tooltip, Dropdown, Modal, AlertDialog, Drawer, and Disclosure now apply `inline-block` to prevent layout collapse when the trigger wraps inline content ([#6373](https://github.com/heroui-inc/heroui/pull/6373)).
+
+### Tooltip & Popover Arrow
+
+Default arrow SVG path updated from a quadratic curve to a cubic bezier for a smoother, more natural shape ([#6372](https://github.com/heroui-inc/heroui/pull/6372)).
+
+### Tag Spacing
+
+Increased horizontal padding on `sm` (`px-1` to `px-2`) and `md` (`px-1.5` to `px-2`) Tag sizes for better readability ([#6315](https://github.com/heroui-inc/heroui/pull/6315)).
+
+## Bug Fixes
+
+- **Autocomplete**: `--trigger-width` CSS variable on the popover now tracks the trigger element's width via `useResizeObserver`, fixing misaligned dropdown widths ([#6374](https://github.com/heroui-inc/heroui/pull/6374))
+- **Drawer**: Panel transitions rewritten from Tailwind `animate-in`/`animate-out` to native CSS `translate` transitions for smoother open/close animations across all placements ([#6393](https://github.com/heroui-inc/heroui/pull/6393))
+- **InputGroup**: Secondary variant focus background now triggers only when the actual input or textarea is focused, not on any focusable child within the group ([#6362](https://github.com/heroui-inc/heroui/pull/6362))
+- **Tag**: `CloseButton` inside Tag now has an explicit `aria-label="Remove tag"` for screen readers ([#6341](https://github.com/heroui-inc/heroui/pull/6341))
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6364](https://github.com/heroui-inc/heroui/pull/6364)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-3.mdx b/apps/docs/content/docs/en/react/releases/v3-0-3.mdx
new file mode 100644
index 0000000..68f0afd
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-3.mdx
@@ -0,0 +1,127 @@
+---
+title: v3.0.3
+description: RAC 1.17 with 90% fewer deps, expandable Table rows, Apache 2.0 license, useTheme hook, DOM polymorphic render-prop API, and bug fixes.
+github:
+  pull: 6441
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">April 17, 2026</span>
+</div>
+
+Patch release: React Aria Components 1.17 with 90% fewer dependencies, expandable Table rows, Apache 2.0 license, the `useTheme` hook for Vite and CRA apps, a DOM polymorphic utility for render-prop element swaps, and bug fixes.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### React Aria Components 1.17
+
+This release upgrades React Aria Components to [v1.17.0](https://react-aria.adobe.com/releases/v1-17-0). The highlight: dependency consolidation drops **90% of RAC's transitive dependencies**, resulting in faster installs and builds. See the full [RAC 1.17 release notes](https://react-aria.adobe.com/releases/v1-17-0) for details.
+
+### Expandable Table rows
+
+Table now supports expandable rows for tree-style data. Set a `treeColumn` and render a chevron in those cells to expand and collapse child rows — perfect for file browsers, nested categories, and hierarchical data.
+
+<ComponentPreview
+  name="table-expandable-rows"
+/>
+
+### useTheme hook
+
+For plain React with Vite or Create React App (no Next.js theme provider), import `useTheme` from `@heroui/react`. It accepts any theme name (`"light"`, `"dark"`, `"brutalism-light"`, etc.). Pass `"system"` to follow the OS preference. It persists the value in `localStorage`, and sets both `data-theme` and `class` on `<html>` to the resolved theme name.
+
+```tsx
+"use client";
+
+import { Button, useTheme } from "@heroui/react";
+
+export function ThemeSwitch() {
+  const { theme, setTheme } = useTheme("light");
+
+  return (
+    <div className="flex gap-2">
+      <Button onPress={() => setTheme("light")}>
+        Light
+      </Button>
+      <Button onPress={() => setTheme("dark")}>
+        Dark
+      </Button>
+      <Button onPress={() => setTheme("system")}>
+        System
+      </Button>
+      <Button onPress={() => setTheme("brutalism-light")}>
+        Brutalism Light
+      </Button>
+      <span className="text-sm opacity-70">Current: {theme}</span>
+    </div>
+  );
+}
+```
+
+### DOM polymorphic utility
+
+The DOM polymorphic helper lets lightweight components that are not built on React Aria primitives change their host element through a render prop.
+
+**Example:** rendering a Card component as `<button />`
+
+```tsx
+<Card<"button"> render={(props) => <button {...props} />} />
+```
+
+### License change
+
+HeroUI is now licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), replacing the previous MIT license. Apache 2.0 provides the same permissive freedoms while adding an explicit patent grant for additional legal protection. No action is required from existing users.
+
+## Bug Fixes
+
+- **Tabs**: scope secondary-variant styles so nested tab groups no longer inherit the parent variant ([#6384](https://github.com/heroui-inc/heroui/pull/6384))
+
+## Dependencies
+
+- **React Aria Components**: Updated from `1.16.0` to [`1.17.0`](https://react-aria.adobe.com/releases/v1-17-0)
+- **@react-aria/utils**: Updated from `3.33.1` to `3.34.0`
+- **@react-types/shared**: Updated from `3.33.1` to `3.34.0`
+- **@internationalized/date**: Updated from `3.12.0` to `3.12.1`
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6441](https://github.com/heroui-inc/heroui/pull/6441)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-4.mdx b/apps/docs/content/docs/en/react/releases/v3-0-4.mdx
new file mode 100644
index 0000000..8240b4c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-4.mdx
@@ -0,0 +1,103 @@
+---
+title: v3.0.4
+description: New Typography component, docs theme selector, border-radius design tokens with min() capping, table focus ring rework, and bug fixes.
+github:
+  pull: 6483
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">May 2026</span>
+</div>
+
+Patch release: new `Typography` compound component ported from HeroUI Pro, a docs theme selector for previewing components in different themes, `min()`-capped border-radius tokens across 45+ component CSS files, reworked Table focus rings, and fixes for Checkbox, Autocomplete, Tooltip, and form field padding.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Typography Component
+
+New compound component for structured typography, ported from HeroUI Pro ([#6479](https://github.com/heroui-inc/heroui/pull/6479)). Renders the right HTML element automatically — `<h1>`–`<h6>`, `<p>`, or `<code>` — based on the sub-component or `type` prop.
+
+<ComponentPreview name="typography-typography-scale" />
+
+Sub-components: `Typography.Heading`, `Typography.Paragraph`, `Typography.Code`, `Typography.Prose`.
+
+Props on all sub-components: `align`, `color`, `weight`, `truncate`. `Typography.Heading` accepts `level` (1–6). `Typography.Paragraph` accepts `size` (`"base"`, `"sm"`, `"xs"`).
+
+Wrap mixed content in `Typography.Prose` for automatic prose spacing:
+
+```tsx
+<Typography.Prose>
+  <Typography.Heading level={3}>Getting Started</Typography.Heading>
+  <Typography.Paragraph>Install the package and import the component.</Typography.Paragraph>
+</Typography.Prose>
+```
+
+### Docs Theme Selector
+
+The documentation site now includes a theme selector that lets you preview every component in different themes — light, dark, brutalism, and more. Your choice is saved to `localStorage` so it persists across sessions ([#6471](https://github.com/heroui-inc/heroui/pull/6471)).
+
+<VideoPlayer
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-oss-3.0.4-4k.mp4"
+  muted
+/>
+
+### Border-Radius Design Tokens
+
+All `rounded-full` and hardcoded `border-radius` values across ~45 component CSS files now use `min()` to cap the computed radius ([#6465](https://github.com/heroui-inc/heroui/pull/6465)). Components no longer look broken when users set very large custom radius themes — the radius stops growing once it would exceed the element's dimensions.
+
+### Table Focus Ring Rework
+
+Table row focus indicators are split across individual cells using per-cell inset shadows instead of a single `box-shadow` on the row. The ring now looks continuous across all cells and works correctly with virtualized table wrappers.
+
+## Bug Fixes
+
+- **Checkbox**: removed hardcoded `accent-hover` background from selected/indeterminate indicator state ([#6487](https://github.com/heroui-inc/heroui/pull/6487))
+- **Autocomplete**: `isDisabled` now propagates from root to `Trigger` and `ClearButton` via context ([#6443](https://github.com/heroui-inc/heroui/pull/6443))
+- **Description**: removed unnecessary horizontal padding from description text in form fields (textfield, color-field, date-field, number-field, search-field, time-field) ([#6484](https://github.com/heroui-inc/heroui/pull/6484))
+- **Tooltip**: changed padding from `px-2 py-1` to `p-2` and switched border-radius to design token ([#6481](https://github.com/heroui-inc/heroui/pull/6481))
+- **Theme Builder**: fixed swapped `accent-foreground` values ([#6401](https://github.com/heroui-inc/heroui/pull/6401))
+- **Soft color contrast**: `accent-soft-foreground` now uses a darker shade for light accent themes (Sky, Lavender, Mint), fixing barely-visible text on secondary buttons, chips, and badges. The shared theme now reads from `--accent-soft-foreground` with a fallback to `--accent`
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6483](https://github.com/heroui-inc/heroui/pull/6483)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-0-5.mdx b/apps/docs/content/docs/en/react/releases/v3-0-5.mdx
new file mode 100644
index 0000000..8eedfe7
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-0-5.mdx
@@ -0,0 +1,197 @@
+---
+title: v3.0.5
+description: Text renamed to Typography (breaking), color tokens refactored to unprefixed source variables, Checkbox + Radio border fixes, and a new CLI docs page.
+github:
+  pull: 6503
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">May 15, 2026</span>
+</div>
+
+Patch release: `Text` is renamed to `Typography` to resolve a `tailwind-merge` collision that silently dropped variant classes. Derived color tokens (`hover`, `soft`, `border-secondary`, …) moved from `@theme inline` aliases into `variables.css` as unprefixed source tokens, so component CSS can reference them directly. Plus Checkbox and Radio border alignment fixes, an `accent-soft-foreground` hover refinement for Calendar, and a new CLI docs page.
+
+⚠️ **Breaking change**: `Text` → `Typography`. The BEM block changes from `text` to `typography` (e.g. `text--body-sm` → `typography--body-sm`).
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## ⚠️ Breaking Changes
+
+### `Text` → `Typography`
+
+The component shipped in [v3.0.4](/docs/react/releases/v3-0-4) used `text-*` BEM modifiers, which collide with Tailwind's `text-*` utility family. `tailwind-variants` runs `tailwind-merge` on every variant composition and dedupes `text--body-sm`, `text--color-muted`, `text--weight-normal` to a single class — silently dropping the others.
+
+Renaming the block to `typography` permanently fixes the collision ([#6505](https://github.com/heroui-inc/heroui/pull/6505), closes [#6497](https://github.com/heroui-inc/heroui/issues/6497)).
+
+**Before:**
+
+```tsx
+import {Text} from "@heroui/react";
+
+<Text type="body-sm" color="muted" weight="medium">
+  Hello world
+</Text>;
+```
+
+**After:**
+
+```tsx
+import {Typography} from "@heroui/react";
+
+<Typography type="body-sm" color="muted" weight="medium">
+  Hello world
+</Typography>;
+```
+
+Sub-components rename the same way:
+
+| Before              | After                     |
+| ------------------- | ------------------------- |
+| `Text`              | `Typography`              |
+| `Text.Heading`      | `Typography.Heading`      |
+| `Text.Paragraph`    | `Typography.Paragraph`    |
+| `Text.Code`         | `Typography.Code`         |
+| `Text.Prose`        | `Typography.Prose`        |
+
+CSS BEM classes change too: `.text` → `.typography`, `.text--body-sm` → `.typography--body-sm`, etc. See the [Typography docs](/docs/components/typography) for the full class reference.
+
+<ComponentPreview name="typography-typography-scale" />
+
+## Style Refactor
+
+### Unprefixed source color tokens
+
+All derived color tokens — `*-hover`, `*-soft`, `*-soft-foreground`, `border-secondary`, etc. — moved from `@theme inline` aliases in `theme.css` into `variables.css` as unprefixed source variables, and 24 component CSS files now reference source tokens directly ([#6499](https://github.com/heroui-inc/heroui/pull/6499)).
+
+**1. `color-mix` formulas moved from `theme.css` to `variables.css`**
+
+Before — the calculation lived inside the `@theme inline` block:
+
+```css
+/* packages/styles/themes/shared/theme.css */
+--color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+--color-accent-soft: var(--accent-soft, color-mix(in oklab, var(--accent) 15%, transparent));
+--color-accent-soft-foreground: var(--accent-soft-foreground, var(--accent));
+--color-border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+```
+
+After — `theme.css` is pure aliases; the formulas live in `variables.css`:
+
+```css
+/* packages/styles/themes/default/variables.css */
+--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+--accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
+--accent-soft-foreground: var(--accent);
+--border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+
+/* packages/styles/themes/shared/theme.css */
+--color-accent-hover: var(--accent-hover);
+--color-accent-soft: var(--accent-soft);
+--color-accent-soft-foreground: var(--accent-soft-foreground);
+--color-border-secondary: var(--border-secondary);
+```
+
+**2. Component CSS uses source tokens directly**
+
+Before — `var(--color-*)` references everywhere:
+
+```css
+/* packages/styles/components/button.css */
+.button--primary {
+  --button-bg: var(--color-accent);
+  --button-bg-hover: var(--color-accent-hover);
+  --button-fg: var(--color-accent-foreground);
+}
+
+.button--secondary {
+  --button-bg: var(--color-default);
+  --button-bg-hover: var(--color-default-hover);
+  --button-fg: var(--color-accent-soft-foreground);
+}
+```
+
+After — unprefixed source tokens:
+
+```css
+/* packages/styles/components/button.css */
+.button--primary {
+  --button-bg: var(--accent);
+  --button-bg-hover: var(--accent-hover);
+  --button-fg: var(--accent-foreground);
+}
+
+.button--secondary {
+  --button-bg: var(--default);
+  --button-bg-hover: var(--default-hover);
+  --button-fg: var(--accent-soft-foreground);
+}
+```
+
+The `@theme inline` block still exposes every `--color-*` Tailwind utility as an alias, so user-land class usage (`bg-accent`, `text-accent`, …) is unaffected.
+
+**3. Theme builder consolidated**
+
+Three derived-token helpers (`getAccentDerivedVariables`, `getSemanticDerivedVariables`, `getFieldDerivedVariables`) collapsed into a single `getDerivedColorVariables()` that emits the full unprefixed set, including the `darkenForSoftForeground` logic that keeps soft-foreground text readable on light accent themes.
+
+## Style Fixes
+
+- **Calendar / Range Calendar**: default day-cell hover now uses `accent-soft-foreground` instead of `accent`, so hovered cells stay legible on light accent themes. The docs search tag selected state was aligned the same way ([#6500](https://github.com/heroui-inc/heroui/pull/6500)).
+- **Checkbox**: `.checkbox__control` now carries the same `border`, `border-field-border`, and `[border-width:var(--border-width-field)]` base styling that `.radio__control` already used, with `border-color` added to the transition list ([#6521](https://github.com/heroui-inc/heroui/pull/6521)).
+- **Radio**: `.radio__control` default border now uses `border-field-border` instead of the generic Tailwind `border` color, matching Input, Select, TextArea, and NumberField ([#6522](https://github.com/heroui-inc/heroui/pull/6522)).
+
+## Docs
+
+### CLI page
+
+New [CLI docs page](/docs/react/getting-started/cli) covers installation, `init`, `install`, `upgrade`, `uninstall`, `list`, `doctor`, and `env` with example outputs ([#6498](https://github.com/heroui-inc/heroui/pull/6498)).
+
+## Dependencies
+
+Bumped across packages ([#6529](https://github.com/heroui-inc/heroui/pull/6529)):
+
+- **`react` / `react-dom`**: `19.2.3` → `19.2.6`
+- **`@types/react`**: `19.2.7` → `19.2.14`
+- **`next`** (docs): `16.1.1` → `16.2.6`
+- **CI actions**: `actions/checkout@v6`, `actions/setup-node@v6`, `actions/cache@v5`, `pnpm/action-setup@v6`
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6503](https://github.com/heroui-inc/heroui/pull/6503)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-1-0.mdx b/apps/docs/content/docs/en/react/releases/v3-1-0.mdx
new file mode 100644
index 0000000..d4612cd
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-1-0.mdx
@@ -0,0 +1,169 @@
+---
+title: v3.1.0
+description: Chinese React docs, accessible soft foreground tokens, shared scrollbar styling, useTheme SSR fixes, Toast cleanup, Link underline updates, and RTL layout refinements.
+github:
+  pull: 6576
+---
+
+import {HandPointUp} from "@gravity-ui/icons";
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">May 25, 2026</span>
+</div>
+
+Minor release: HeroUI React docs now ship with Chinese pages and localized demos, soft color tokens were expanded for better readability, scroll containers share a single themeable scrollbar system, and several runtime and layout fixes landed for `useTheme`, Toast, Link, Fieldset, overlays, and RTL layouts.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Chinese React Docs
+
+The documentation site now supports localized React docs, migration guides, release notes, and demos in Chinese ([#6533](https://github.com/heroui-inc/heroui/pull/6533)). The docs app was restructured around locale-aware content paths and localized demo registries, so React component pages, getting-started guides, and migration references can ship in both English and Chinese.
+
+<DocsImage
+  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oss-releases/cn-docs-showcase.png"
+  alt="Chinese React documentation pages in HeroUI"
+  wrapperClassName="aspect-[1922/1323]"
+/>
+
+### Accessible Soft Foreground Tokens
+
+Soft foreground colors now use dedicated theme tokens instead of raw semantic colors, improving contrast for soft badges, chips, alerts, toasts, avatars, and calendar range states ([#6548](https://github.com/heroui-inc/heroui/pull/6548)).
+
+New tokens include:
+
+- `--default-soft`
+- `--default-soft-foreground`
+- `--default-soft-hover`
+- updated `--accent-soft-foreground`, `--danger-soft-foreground`, `--warning-soft-foreground`, and `--success-soft-foreground`
+
+The default palette now uses soft foreground colors with accessibility-compliant contrast. Teams that prefer the previous, more saturated palette can opt into the vibrant palette with `data-vibrant-palette="true"`, but that palette has lower contrast. The theme builder and docs theme selector were updated to preserve this preference.
+
+<ComponentPreview name="chip-vibrant-palette" />
+
+### Shared Scrollbar System
+
+Scroll containers now use a shared, standards-based scrollbar system with theme variables and per-subtree control through `data-scrollbar` ([#6545](https://github.com/heroui-inc/heroui/pull/6545)). Instead of maintaining separate scrollbar CSS in each component, scroll slots now read the same `--scrollbar-*` variables and use the shared scrollbar utilities, so scroll areas look more consistent across light mode, dark mode, overlays, tables, and custom overflow regions.
+
+Supported modes:
+
+- HeroUI thin: leave `data-scrollbar` unset, or set `data-scrollbar="thin"` to force the themed thin scrollbar inside a subtree.
+- Browser default: set `data-scrollbar="default"` to use the OS/browser scrollbar.
+- Hidden: set `data-scrollbar="none"` to hide the visible scrollbar while keeping the content scrollable.
+
+```html
+<div data-scrollbar="thin">Uses the HeroUI themed scrollbar</div>
+<div data-scrollbar="default">Uses the browser scrollbar</div>
+<div data-scrollbar="none">Hides descendant HeroUI scrollbars</div>
+```
+
+<div className="not-prose mt-6 mb-4 flex items-center gap-2 text-sm font-medium text-muted">
+  <HandPointUp aria-hidden="true" className="size-5 shrink-0" />
+  <span>Scroll vertically</span>
+</div>
+
+<ComponentPreview name="list-box-scrollbar-modes" />
+
+Components such as Select, ComboBox, Autocomplete, Dropdown, DatePicker, DateRangePicker, ColorPicker, Table, Tabs, Modal, Drawer, and ScrollShadow now share the same scrollbar utilities instead of maintaining one-off scrollbar CSS.
+
+Use the `scrollbar` utility on any scrollable slot that should follow the active `data-scrollbar` mode. It reads `--scrollbar-width`, `--scrollbar-color`, and `--scrollbar-gutter`, so the same slot can render as HeroUI thin, browser default, or hidden depending on the nearest `data-scrollbar` ancestor.
+
+```css
+.alert-dialog__body {
+  @apply min-h-0 flex-1 scrollbar;
+}
+```
+
+The theme variables also moved from a single fixed `--scrollbar` color to a small scrollbar token set:
+
+```css
+/* before */
+--scrollbar: oklch(70.5% 0.015 286.067);
+
+/* after */
+--scrollbar: var(--scrollbar-thumb);
+--scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+--scrollbar-track: transparent;
+--scrollbar-gutter: auto;
+--scrollbar-width: thin;
+--scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+```
+
+`--scrollbar` now stays as a compatibility alias, while the new thumb, track, gutter, width, and color tokens control the rendered scrollbar.
+
+To return to normal browser scrollbars, set `data-scrollbar="default"` on the root `<html>`, your app `<main>`, or any nested container. The mode cascades through descendant HeroUI scroll slots and custom elements using the scrollbar utilities. If you set the root to browser defaults but want one area to use HeroUI styling again, add `data-scrollbar="thin"` on that nested element.
+
+```html
+<html data-scrollbar="default">
+  <main>
+    <section data-scrollbar="thin">
+      <!-- HeroUI themed scrollbars here -->
+    </section>
+  </main>
+</html>
+```
+
+## Component and Runtime Fixes
+
+- **Fieldset**: `disabled` now cascades through descendant field labels and explicitly disables React Aria `RadioGroup` and `Slider`, matching native fieldset behavior more closely ([#6547](https://github.com/heroui-inc/heroui/pull/6547)).
+- **Toast**: non-frontmost toasts are removed from keyboard tab order, and measured toast heights are cleaned up when toasts unmount so long-running sessions do not accumulate stale height entries ([#6510](https://github.com/heroui-inc/heroui/pull/6510), [#6512](https://github.com/heroui-inc/heroui/pull/6512)).
+- **`useTheme`**: the hook no longer reads browser-only APIs during SSR, derives `resolvedTheme` without circular state updates, and uses `useSyncExternalStore` to subscribe to system color-scheme changes ([#6561](https://github.com/heroui-inc/heroui/pull/6561)).
+- **Link**: the default underline is now hidden at rest, appears on hover with a 50% decoration color, and becomes full opacity on active or pressed states. The underline decoration color transition was removed for a crisper interaction ([#6570](https://github.com/heroui-inc/heroui/pull/6570), [#6571](https://github.com/heroui-inc/heroui/pull/6571)).
+
+## Layout, Overlay, and RTL Fixes
+
+- **Overlay positioning**: entering overlays now limit transition properties to `opacity` and `transform`, preventing React Aria placement values from animating and producing incorrect popover placement during open animations ([#6549](https://github.com/heroui-inc/heroui/pull/6549)).
+- **Dialog and Modal focus**: Modal and AlertDialog content now use clipping that prevents focus from programmatically scrolling the dialog, while body focus rings are no longer cut off by container overflow ([#6448](https://github.com/heroui-inc/heroui/pull/6448), [#6557](https://github.com/heroui-inc/heroui/pull/6557)).
+- **RTL table corners**: Table rounded corners now use logical border-radius properties so outer corners remain correct in right-to-left layouts ([#6568](https://github.com/heroui-inc/heroui/pull/6568)).
+- **RTL picker and menu indicators**: Select, ListBox.Item, Autocomplete, ComboBox, and MenuItem now use logical inline start/end utilities for chevrons, value text, checkmarks, triggers, and submenu indicators ([#6573](https://github.com/heroui-inc/heroui/pull/6573)).
+
+## Docs and Dependencies
+
+- Theme docs now match the current `theme.css` and `variables.css` token model, including soft foreground tokens and scrollbar variables.
+- Docs release and migration pages were synced with the Link behavior update.
+- Docs gained `@fumadocs/language` and upgraded `fumadocs-core` / `fumadocs-ui` to `16.9.0` for localized routing.
+- Tailwind tooling for docs and styles moved to `4.3.0`.
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [Theming Docs](/docs/react/getting-started/theming)
+- [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6576](https://github.com/heroui-inc/heroui/pull/6576)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-2-0.mdx b/apps/docs/content/docs/en/react/releases/v3-2-0.mdx
new file mode 100644
index 0000000..548b398
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-2-0.mdx
@@ -0,0 +1,278 @@
+---
+title: v3.2.0
+description: Calendar week/day views and year picker on React Aria 1.18, plus breaking Radio, Checkbox, and Switch composition changes.
+github:
+  pull: 6616
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">June 15, 2026</span>
+</div>
+
+Calendar gains week and day views, a reworked year picker, and range demos built on React Aria 1.18. [Autocomplete](/docs/components/autocomplete) adds a Virtualizer example for large option lists. [Tooltip](/docs/components/tooltip) adds theme variables for global show and hide delays. The toggles (`Radio`, `Checkbox`, `Switch`) move to React Aria's `*Field` + `*Button` composition. This release also rolls in patch fixes for virtualized lists, grouped-field autofill, toast and fieldset behavior, and scroll and RTL styles.
+
+⚠️ **Breaking changes**: `Radio`, `Checkbox`, and `Switch` move to an explicit `*.Content` composition — `*.Control` nests inside `*.Content`, the label is plain text inside `*.Content` (no nested `<Label>`), and `Description`/`FieldError` become siblings of `*.Content`. See [Breaking Changes](#%EF%B8%8F-breaking-changes).
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## What's New
+
+### Calendar
+
+`Calendar` and `RangeCalendar` gain week and day views, plus new React Aria 1.18 calendar props.
+
+- **Week / day views**: `visibleDuration` renders multi-week or single-day layouts
+- **Multiple selection**: select several dates in a single `Calendar`
+- **React Aria 1.18 props**: `weeksInMonth` and `isDateUnavailable(date, anchorDate)` for ranges
+- **Internals**: month labels use React Aria's `CalendarHeading`, and the year picker is rebuilt on React Aria calendar hooks
+
+**Week view:**
+
+<ComponentPreview name="calendar-week-view" />
+
+**Day view:**
+
+<ComponentPreview name="calendar-day-view" />
+
+**Multiple selection:**
+
+<ComponentPreview name="calendar-multiple-selection" />
+
+### Autocomplete
+
+Virtualizer support for large option lists, with docs, Storybook, and style fixes for popover sizing and listbox scroll height.
+
+- **Virtualization**: Wrap `ListBox` in React Aria's `<Virtualizer>` inside `Autocomplete.Popover` ([#6642](https://github.com/heroui-inc/heroui/pull/6642))
+- **Popover sizing**: Listbox caps at `320px` with internal scrolling; search field stays fixed above the list
+
+**Virtualization:**
+
+<ComponentPreview name="autocomplete-virtualization" />
+
+### Table.SortableColumnHeader
+
+`Table.SortableColumnHeader` renders a sortable column label with an optional ascending/descending indicator. Use it inside a `Table.Column` render prop and forward `sortDirection` ([#6588](https://github.com/heroui-inc/heroui/pull/6588)).
+
+```tsx
+<Table.Column allowsSorting>
+  {({sortDirection}) => (
+    <Table.SortableColumnHeader sortDirection={sortDirection}>
+      Name
+    </Table.SortableColumnHeader>
+  )}
+</Table.Column>
+```
+
+- **Default indicator**: Chevron appears when a sort direction exists
+- **Custom indicator**: Pass `indicator`, or hide it with `showIndicator={false}`
+- **Style slots**: `.table__sortable-column-header` + `.table__sortable-column-indicator`
+
+<ComponentPreview name="table-sorting" />
+
+### Tooltip delay theme variables
+
+[Tooltip](/docs/components/tooltip) reads default show and hide delays from theme CSS variables ([#6617](https://github.com/heroui-inc/heroui/pull/6617)):
+
+- `--tooltip-delay` — delay before showing a tooltip (default: `1500ms`)
+- `--tooltip-close-delay` — delay before hiding a tooltip (default: `500ms`)
+
+Override them globally:
+
+```css
+:root {
+  --tooltip-delay: 700ms;
+  --tooltip-close-delay: 0ms;
+}
+```
+
+Individual `delay` and `closeDelay` props still override these values on specific tooltips.
+
+<Callout type="warning">
+  **Behavior change:** With the default HeroUI theme, tooltip delays now default to `1500ms` / `500ms` instead of the previous React Aria defaults of `700ms` / `0ms`. Set the CSS variables or props explicitly to preserve the old timing.
+</Callout>
+
+## Component Fixes
+
+- **Toast**: ViewTransition updates are serialized in the toast queue, preventing skipped transitions and AbortError rejections when `toast.promise()` swaps the loading toast for success/error feedback ([#6511](https://github.com/heroui-inc/heroui/pull/6511)).
+- **Fieldset**: `disabled` propagates through React Aria Button, CheckboxGroup, Link, RadioGroup, Slider, ToggleButton, and ToggleButtonGroup contexts ([#6596](https://github.com/heroui-inc/heroui/pull/6596)).
+- **Autocomplete**: Popover content is wrapped in a React Aria `Dialog`, so opening the popover no longer leaves a stray focus ring on the listbox ([#6627](https://github.com/heroui-inc/heroui/pull/6627)).
+- **Tooltip**: The trigger uses the `useFocusable` hook instead of the `<Focusable>` wrapper, avoiding a false-positive "child must be focusable" warning when a tooltip is mounted inside an `inert` subtree (e.g. behind an open Drawer/Modal) ([#6628](https://github.com/heroui-inc/heroui/pull/6628)).
+
+## Style Fixes
+
+- **Modal / AlertDialog**: `scroll-inside` dialogs cap height with `max-h-full min-h-0` so the body scrolls instead of overflowing ([#6597](https://github.com/heroui-inc/heroui/pull/6597)).
+- **ScrollShadow**: Fade masks reserve space for visible native scrollbars via `--scroll-shadow-scrollbar-size` ([#6598](https://github.com/heroui-inc/heroui/pull/6598)).
+- **Table RTL**: Column separators and resize handles use logical `end-0` positioning in RTL ([#6606](https://github.com/heroui-inc/heroui/pull/6606)).
+- **Link**: Drops the hardcoded `text-sm` so links inherit font size from their parent, and `.link__icon` scales relative to text with `size-[0.75em]` instead of a fixed `size-2` ([#6621](https://github.com/heroui-inc/heroui/pull/6621)).
+- **DatePicker / DateRangePicker**: Calendar popovers use `min-w-(--trigger-width)` instead of `max-w-(--trigger-width)` so the calendar is at least as wide as the trigger and no longer clips horizontally ([#6622](https://github.com/heroui-inc/heroui/pull/6622)).
+- **Table**: Secondary header borders and rounded corners render correctly when the table is wrapped in React Aria's `<Virtualizer>` — column selectors no longer treat every virtualized column as both first and last child ([#6624](https://github.com/heroui-inc/heroui/pull/6624)).
+- **Autocomplete**: The popover is constrained to the trigger width and the listbox caps its height at `320px` with internal scrolling, so virtualized lists no longer overflow the popover ([#6642](https://github.com/heroui-inc/heroui/pull/6642)).
+- **ListBox**: Replaces `flex flex-col gap` with block flow + sibling margins so React Aria's Virtualizer content height is not collapsed by flex-shrink — fixes scrollbar thumb resizing during virtualized scroll ([#6636](https://github.com/heroui-inc/heroui/pull/6636)).
+- **InputGroup / NumberField / SearchField**: Browser autofill highlight lifts onto the group shell so prefix, suffix, and increment/decrement slots share the rounded highlight ([#6625](https://github.com/heroui-inc/heroui/pull/6625)).
+- **Spinner**: Uses `inline-flex` with `shrink-0` (instead of `relative`) so the spin animation renders correctly in non-flex layouts, and honors `motion-reduce` ([#6644](https://github.com/heroui-inc/heroui/pull/6644)).
+- **Toast**: Close button uses `-top-1 -right-1` on all breakpoints to align with container padding ([#6574](https://github.com/heroui-inc/heroui/pull/6574)).
+
+## Dependencies
+
+- **React Aria Components**: `1.17.0` → `1.18.0` ([#6586](https://github.com/heroui-inc/heroui/pull/6586)). 1.18 adds the `*Field` + `*Button` composition adopted by the toggles, `CalendarHeading`, and `isDateUnavailable(date, anchorDate)`.
+- **@internationalized/date**: `3.12.1` → `3.12.2`
+- **React Aria / Stately helpers**: `@react-aria/*`, `@react-stately/*`, and `@react-types/shared` patch updates
+
+## ⚠️ Breaking Changes
+
+### Radio, Checkbox & Switch: explicit `*.Content` composition
+
+These toggles now use React Aria's `*Field` + `*Button` composition under the hood. `X.Content` is now the **clickable label** (React Aria's `*Button`). Three things change:
+
+- **`X.Control` moves inside `X.Content`** — they used to be siblings.
+- **The label is plain text inside `X.Content`** — `X.Content` renders the `<label>` element, so don't nest a `<Label>` component (nested `<label>` elements are invalid HTML). For a standalone `Label`, place it **outside** and link it with `htmlFor` + the toggle `id`.
+- **`Description`/`FieldError` move out** as siblings of `X.Content`, so they're exposed via `aria-describedby` instead of being folded into the accessible name.
+
+**Checkbox**
+
+```tsx
+// v3.1
+<Checkbox>
+  <Checkbox.Control>
+    <Checkbox.Indicator />
+  </Checkbox.Control>
+  <Checkbox.Content>
+    <Label>Accept terms</Label>
+    <Description>You agree to our terms</Description>
+  </Checkbox.Content>
+</Checkbox>
+
+// v3.2
+<Checkbox>
+  <Checkbox.Content>
+    <Checkbox.Control>
+      <Checkbox.Indicator />
+    </Checkbox.Control>
+    Accept terms
+  </Checkbox.Content>
+  <Description>You agree to our terms</Description>
+</Checkbox>
+```
+
+**Radio**
+
+```tsx
+// v3.1
+<Radio value="a">
+  <Radio.Control>
+    <Radio.Indicator />
+  </Radio.Control>
+  <Radio.Content>
+    <Label>Option A</Label>
+  </Radio.Content>
+</Radio>
+
+// v3.2
+<Radio value="a">
+  <Radio.Content>
+    <Radio.Control>
+      <Radio.Indicator />
+    </Radio.Control>
+    Option A
+  </Radio.Content>
+</Radio>
+```
+
+**Switch**
+
+```tsx
+// v3.1
+<Switch>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+  <Switch.Content>
+    <Label>Enable notifications</Label>
+  </Switch.Content>
+</Switch>
+
+// v3.2
+<Switch>
+  <Switch.Content>
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+    Enable notifications
+  </Switch.Content>
+</Switch>
+```
+
+**Migration summary**
+
+| v3.1 | v3.2 |
+|------|------|
+| `X.Control` and `X.Content` are siblings | `X.Control` nests inside `X.Content` |
+| `X.Content` is a layout `<div>` wrapping `Label` + help text | `X.Content` is the clickable `<label>` wrapping `X.Control` + label text |
+| Label provided via `<Label>` inside `X.Content` | Label is **plain text** inside `X.Content` (no nested `<Label>`) |
+| `Description` / `FieldError` inside `X.Content` | `Description` / `FieldError` as siblings of `X.Content` |
+
+**External label** — to use a standalone `Label`, place it outside the toggle and link it with `htmlFor` + the toggle `id`:
+
+```tsx
+<div className="flex items-center gap-3">
+  <Checkbox id="terms">
+    <Checkbox.Content>
+      <Checkbox.Control>
+        <Checkbox.Indicator />
+      </Checkbox.Control>
+    </Checkbox.Content>
+  </Checkbox>
+  <Label htmlFor="terms">Accept terms</Label>
+</div>
+```
+
+**Control-only checkboxes and switches** (no label, e.g. table row selection or icon switches) still need `X.Content` as the clickable wrapper. Wrap `Checkbox.Control` / `Switch.Control` in `X.Content`, omit the label, and pass an `aria-label` on the root.
+
+Full per-component guides: [Checkbox](/docs/react/migration/checkbox), [Checkbox Group](/docs/react/migration/checkbox-group), [Radio](/docs/react/migration/radio), [Radio Group](/docs/react/migration/radio-group), and [Switch](/docs/react/migration/switch).
+
+## Links
+
+- [Calendar Docs](/docs/react/components/calendar)
+- [Autocomplete Docs](/docs/react/components/autocomplete)
+- [Tooltip Docs](/docs/react/components/tooltip)
+- [Checkbox Docs](/docs/react/components/checkbox)
+- [Radio Group Docs](/docs/react/components/radio-group)
+- [Switch Docs](/docs/react/components/switch)
+- [Component Docs](/docs/react/components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6616](https://github.com/heroui-inc/heroui/pull/6616)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-2-1.mdx b/apps/docs/content/docs/en/react/releases/v3-2-1.mdx
new file mode 100644
index 0000000..be58a5c
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-2-1.mdx
@@ -0,0 +1,60 @@
+---
+title: v3.2.1
+description: Patch release that externalizes react-aria from the @heroui/react bundle and fixes SwitchGroup horizontal layout.
+github:
+  pull: 6654
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">June 17, 2026</span>
+</div>
+
+Patch release: `@heroui/react` no longer bundles its own copy of `react-aria`. The `react-aria` subpaths are now externalized in the Rollup build, so they resolve to the version installed in your project — preventing a duplicated, vendored copy of `react-aria` from shipping inside `@heroui/react`. This release also fixes `SwitchGroup` horizontal layout by rendering the missing `switch-group__items` wrapper.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## Bug Fixes
+
+- **@heroui/react**: Externalize the `react-aria` subpaths in the Rollup build alongside the other `@react-*` and `react-aria-components` externals, so `@heroui/react` no longer vendors its own copy of `react-aria`. Consumers now resolve to the single `react-aria` installed in their project, avoiding duplicate-instance bugs and unnecessary bundle bloat ([#6653](https://github.com/heroui-inc/heroui/pull/6653)).
+- **SwitchGroup**: Render the missing `switch-group__items` wrapper so `orientation="horizontal"` lays out switches in a row instead of stacking vertically ([#6655](https://github.com/heroui-inc/heroui/pull/6655)).
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6654](https://github.com/heroui-inc/heroui/pull/6654)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/content/docs/en/react/releases/v3-2-2.mdx b/apps/docs/content/docs/en/react/releases/v3-2-2.mdx
new file mode 100644
index 0000000..14cd480
--- /dev/null
+++ b/apps/docs/content/docs/en/react/releases/v3-2-2.mdx
@@ -0,0 +1,87 @@
+---
+title: v3.2.2
+description: Patch release that upgrades React Aria to 1.19.0, adds overflow scrolling to Tabs.ListContainer, and fixes accidental form submission from clear/close buttons and overflow scroll from visually hidden inputs.
+github:
+  pull: 6660
+---
+
+<div className="flex items-center gap-3 mb-6">
+  <span className="text-sm text-muted">June 19, 2026</span>
+</div>
+
+Patch release: upgrades to React Aria `1.19.0` (`react-aria@3.50.0`), adds overflow scrolling to [Tabs](/docs/components/tabs) via `Tabs.ListContainer`, and fixes several regressions — clear and close buttons no longer submit their surrounding form, and visually hidden inputs in `Checkbox`, `Radio`, and `Switch` no longer cause overflow scroll.
+
+## Installation
+
+Update to the latest version:
+
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+  <Tab value="npm">
+    ```bash
+    npm i @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```bash
+    yarn add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add @heroui/styles@latest @heroui/react@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="info">
+  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
+</Callout>
+
+## Features
+
+### Tabs
+
+When the tab list exceeds the available space, `Tabs.ListContainer` automatically renders scroll chevrons and fading edges so users can navigate hidden tabs. This works for both horizontal and vertical orientations.
+
+- **Overflow scrolling**: Wrap `Tabs.List` in `Tabs.ListContainer` to get scroll chevrons and edge fade ([#6696](https://github.com/heroui-inc/heroui/pull/6696))
+
+<ComponentPreview
+  isBgSolid
+  name="tabs-overflow"
+/>
+
+## Bug Fixes
+
+- **Input fields**: Set `type="button"` on clear and close buttons so they no longer submit the surrounding form when clicked ([#6656](https://github.com/heroui-inc/heroui/pull/6656)).
+- **Checkbox / Radio / Switch**: Prevent the visually hidden inputs from causing overflow scroll ([#6657](https://github.com/heroui-inc/heroui/pull/6657)).
+- **Button / Dropdown / Menu**: Add `will-change-transform` to prevent icon or text shift during transforms ([#6661](https://github.com/heroui-inc/heroui/pull/6661)).
+- **Chip**: Set width to `w-fit` so chips size to their content instead of stretching to fill the container ([#6664](https://github.com/heroui-inc/heroui/pull/6664)).
+- **DatePicker / DateRangePicker**: Use `w-fit` instead of `min-w-(--trigger-width)` on the popover to prevent excess width ([#6665](https://github.com/heroui-inc/heroui/pull/6665)).
+- **Autocomplete**: Correct the right padding of virtualized list items so rows no longer overflow into the popover edge ([#6672](https://github.com/heroui-inc/heroui/pull/6672)).
+- **Toast**: Catch the ViewTransition `ready` rejection in the toast queue so superseded transitions no longer surface as unhandled promise rejections ([#6674](https://github.com/heroui-inc/heroui/pull/6674)).
+
+## Refactor
+
+- **React 19 APIs**: Replace `useContext` with the `use()` hook and pass `ref` as a normal prop; swap array-index keys for stable keys ([#6688](https://github.com/heroui-inc/heroui/pull/6688)).
+
+## Dependencies
+
+- **React Aria**: Upgrade to `react-aria-components@1.19.0` and `react-aria@3.50.0` ([#6658](https://github.com/heroui-inc/heroui/pull/6658)).
+- **React Aria**: Declare `react-aria` (`^3.50.0`) and `react-aria-components` (`^1.19.0`) as caret ranges so they dedupe with HeroUI Pro ([#6689](https://github.com/heroui-inc/heroui/pull/6689)).
+
+## Links
+
+- [Component Docs](/docs/react/components)
+- [GitHub Repository](https://github.com/heroui-inc/heroui)
+- [GitHub PR #6660](https://github.com/heroui-inc/heroui/pull/6660)
+
+## Contributors
+
+Thanks to everyone who contributed to this release!
+
+<PRContributors />
diff --git a/apps/docs/env.ts b/apps/docs/env.ts
new file mode 100644
index 0000000..3891622
--- /dev/null
+++ b/apps/docs/env.ts
@@ -0,0 +1,38 @@
+import {createEnv} from "@t3-oss/env-nextjs";
+import {z} from "zod";
+
+export const env = createEnv({
+  client: {
+    NEXT_PUBLIC_APP_ENV: z.enum(["production", "preview", "development"]).default("development"),
+    NEXT_PUBLIC_CDN_URL: z.url().min(1),
+    NEXT_PUBLIC_POSTHOG_HOST: z.url().min(1).optional(),
+    NEXT_PUBLIC_POSTHOG_KEY: z.string().min(1).optional(),
+    NEXT_PUBLIC_PRO_API_URL: z.url().min(1).optional(),
+    NEXT_PUBLIC_PRO_URL: z.url().min(1).optional(),
+    NEXT_PUBLIC_SHOW_PRE_SALE_BANNER: z
+      .enum(["true", "false"])
+      .default("false")
+      .transform((v) => v === "true"),
+  },
+  runtimeEnv: {
+    FEATUREBASE_API_ENDPOINT: process.env["FEATUREBASE_API_ENDPOINT"],
+    FEATUREBASE_API_KEY: process.env["FEATUREBASE_API_KEY"],
+    LOOPS_API_ENDPOINT: process.env["LOOPS_API_ENDPOINT"],
+    LOOPS_API_KEY: process.env["LOOPS_API_KEY"],
+    NEXT_PUBLIC_APP_ENV: process.env["NEXT_PUBLIC_APP_ENV"],
+    NEXT_PUBLIC_CDN_URL: process.env["NEXT_PUBLIC_CDN_URL"],
+    NEXT_PUBLIC_POSTHOG_HOST: process.env["NEXT_PUBLIC_POSTHOG_HOST"],
+    NEXT_PUBLIC_POSTHOG_KEY: process.env["NEXT_PUBLIC_POSTHOG_KEY"],
+    NEXT_PUBLIC_PRO_API_URL: process.env["NEXT_PUBLIC_PRO_API_URL"],
+    NEXT_PUBLIC_PRO_URL: process.env["NEXT_PUBLIC_PRO_URL"],
+    NEXT_PUBLIC_SHOW_PRE_SALE_BANNER: process.env["NEXT_PUBLIC_SHOW_PRE_SALE_BANNER"],
+    NODE_ENV: process.env["NODE_ENV"],
+  },
+  server: {
+    FEATUREBASE_API_ENDPOINT: z.string().min(1),
+    FEATUREBASE_API_KEY: z.string().min(1),
+    LOOPS_API_ENDPOINT: z.string().min(1),
+    LOOPS_API_KEY: z.string().min(1),
+    NODE_ENV: z.enum(["development", "production"]).default("development"),
+  },
+});
diff --git a/apps/docs/eslint.config.mjs b/apps/docs/eslint.config.mjs
new file mode 100644
index 0000000..ab82e2d
--- /dev/null
+++ b/apps/docs/eslint.config.mjs
@@ -0,0 +1,6 @@
+import baseReactConfig from "@heroui/standard/eslint/next.mjs";
+import {defineConfig} from "eslint/config";
+
+const config = defineConfig([...baseReactConfig]);
+
+export default config;
diff --git a/apps/docs/next-redirects.ts b/apps/docs/next-redirects.ts
new file mode 100644
index 0000000..dad11f8
--- /dev/null
+++ b/apps/docs/next-redirects.ts
@@ -0,0 +1,337 @@
+import {readdir, stat} from "fs/promises";
+import {join} from "path";
+
+type Redirect = {
+  source: string;
+  destination: string;
+  permanent: boolean;
+};
+
+/**
+ * Check if a directory name is a route group (starts with parentheses)
+ */
+function isRouteGroup(dirName: string): boolean {
+  return dirName.startsWith("(") && dirName.endsWith(")");
+}
+
+/**
+ * Get all MDX file names from a directory recursively (excluding meta.json and index.mdx)
+ * Route groups (folders starting with parentheses) are ignored in path construction
+ */
+async function getMdxFiles(dir: string, baseDir: string = dir): Promise<string[]> {
+  try {
+    const files = await readdir(dir);
+    const mdxFiles: string[] = [];
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      const stats = await stat(filePath);
+
+      if (stats.isFile() && file.endsWith(".mdx") && file !== "index.mdx") {
+        // Get relative path from base directory, removing route groups
+        const relativePath = filePath.replace(baseDir, "").replace(/\\/g, "/").replace(/^\//, ""); // Remove leading slash
+
+        // Split path and filter out route groups and empty parts
+        const pathParts = relativePath.split("/").filter((part) => part && !isRouteGroup(part));
+
+        // Remove the filename (last part) and extension
+        const filename = pathParts.pop()?.replace(".mdx", "") || "";
+
+        // Construct route path: if there are path parts, join them with filename, otherwise just filename
+        const routePath = pathParts.length > 0 ? `${pathParts.join("/")}/${filename}` : filename;
+
+        mdxFiles.push(routePath);
+      } else if (stats.isDirectory()) {
+        // Recursively scan subdirectories
+        const subFiles = await getMdxFiles(filePath, baseDir);
+
+        mdxFiles.push(...subFiles);
+      }
+    }
+
+    return mdxFiles.sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Produce locale-aware redirects for `/docs/...` sources.
+ *
+ * Every internal docs link in MDX is rewritten by `LocaleLink` to include
+ * the current locale prefix (`/cn/docs/...` for Chinese, `/docs/...` for
+ * the default `en` locale — Fumadocs strips the prefix for the default
+ * language). To make a single conceptual redirect work in every locale,
+ * we emit two Next.js rules per mapping:
+ *
+ *  1. A locale-prefixed source -> locale-prefixed destination (keeps the
+ *     user in the same locale, e.g. /cn/docs/handbook/colors ->
+ *     /cn/docs/react/getting-started/colors).
+ *  2. A bare source -> default-locale destination (covers external links
+ *     and crawlers landing on the un-prefixed URL).
+ *
+ * Both `source` and `destination` MUST start with `/docs/`.
+ */
+function localizedDocsRedirect(source: string, destination: string): Redirect[] {
+  if (!source.startsWith("/docs/") || !destination.startsWith("/docs/")) {
+    throw new Error(
+      `localizedDocsRedirect expects /docs/... source and destination, got ${source} -> ${destination}`,
+    );
+  }
+
+  return [
+    // Locale-prefixed (preserves the visitor's current language).
+    {
+      destination: `/:lang${destination}`,
+      permanent: true,
+      source: `/:lang(en|cn)${source}`,
+    },
+    // Bare path (no locale) -> default locale.
+    {
+      destination: `/en${destination}`,
+      permanent: true,
+      source,
+    },
+  ];
+}
+
+/**
+ * Convenience: turn a list of {source, destination} pairs into the full
+ * locale-aware redirect set.
+ */
+function localizedDocsRedirects(
+  pairs: ReadonlyArray<{source: string; destination: string}>,
+): Redirect[] {
+  return pairs.flatMap(({destination, source}) => localizedDocsRedirect(source, destination));
+}
+
+/**
+ * Generate redirects from `/docs/<prefix>/<route>` to
+ * `/docs/react/<prefix>/<route>` (i.e. promoting the framework-agnostic
+ * legacy URL to the `react` namespace), in both locale and non-locale form.
+ */
+function generateRedirects(routes: string[], prefix: string): Redirect[] {
+  return localizedDocsRedirects(
+    routes.map((route) => ({
+      destination: `/docs/react/${prefix ? `${prefix}/` : ""}${route}`,
+      source: `/docs/${prefix ? `${prefix}/` : ""}${route}`,
+    })),
+  );
+}
+
+/**
+ * Main function to generate all redirects
+ */
+export async function getRedirects(): Promise<Redirect[]> {
+  // Content lives under `content/docs/{en,cn}/react/...` because Fumadocs is
+  // configured with `parser: "dir"` for i18n. The English copy is the source
+  // of truth for the route list, so we enumerate redirects from there.
+  const rootDir = join(process.cwd(), "content/docs/en/react");
+  const redirects: Redirect[] = [];
+
+  // Theme builder redirect - redirect /theme to /themes
+  redirects.push({
+    destination: "/themes",
+    permanent: true,
+    source: "/theme",
+  });
+
+  // Blog moved under [lang] for i18n. Redirect legacy /blog and /blog/<slug>
+  // to the default-locale URL so old links keep working.
+  redirects.push(
+    {
+      destination: "/en/blog",
+      permanent: true,
+      source: "/blog",
+    },
+    {
+      destination: "/en/blog/:slug",
+      permanent: true,
+      source: "/blog/:slug",
+    },
+  );
+
+  // Showcase moved under [lang] for i18n. Redirect legacy /showcase and
+  // /showcase/<id> to the default-locale URL so old links keep working.
+  redirects.push(
+    {
+      destination: "/en/showcase",
+      permanent: true,
+      source: "/showcase",
+    },
+    {
+      destination: "/en/showcase/:id",
+      permanent: true,
+      source: "/showcase/:id",
+    },
+  );
+
+  // Framework root redirects - redirect /react, /web, and /native to their respective docs
+  redirects.push(
+    {
+      destination: "/docs/react/getting-started",
+      permanent: true,
+      source: "/react",
+    },
+    {
+      destination: "/docs/react/getting-started",
+      permanent: true,
+      source: "/web",
+    },
+    {
+      destination: "/docs/native/getting-started",
+      permanent: true,
+      source: "/native",
+    },
+  );
+
+  // Root redirects (bare /docs and locale-prefixed /en/docs, /cn/docs).
+  redirects.push(
+    {
+      destination: "/en/docs/react/getting-started",
+      permanent: true,
+      source: "/docs",
+    },
+    // Locale-prefixed root redirect (i18n)
+    // Without these, /en/docs and /cn/docs hit the catch-all route with no slug
+    // and 404 because there is no content/docs/{locale}/index.mdx.
+    {
+      destination: "/:lang/docs/react/getting-started",
+      permanent: true,
+      source: "/:lang(en|cn)/docs",
+    },
+  );
+
+  // Framework root redirects under /docs (parallel to /react and /native at
+  // the site root). Without these, links like /docs/react and /docs/native
+  // 404 because there is no content/docs/{react,native}/index.mdx.
+  redirects.push(
+    ...localizedDocsRedirects([
+      {destination: "/docs/react/getting-started", source: "/docs/react"},
+      {destination: "/docs/native/getting-started", source: "/docs/native"},
+    ]),
+  );
+
+  // Bare /docs/components -> the components index page
+  redirects.push(...localizedDocsRedirect("/docs/components", "/docs/react/components"));
+
+  // Redirect /docs/getting-started to /docs/react/getting-started
+  redirects.push(...localizedDocsRedirect("/docs/getting-started", "/docs/react/getting-started"));
+
+  // Getting Started pages - now includes (overview), (handbook), and (ui-for-agents) route groups
+  const gettingStartedDir = join(rootDir, "getting-started");
+  const gettingStartedPages = await getMdxFiles(gettingStartedDir);
+
+  redirects.push(...generateRedirects(gettingStartedPages, "getting-started"));
+
+  // Backward compatibility: redirect old get-started paths to new getting-started paths
+  redirects.push(
+    ...gettingStartedPages.flatMap((page) =>
+      localizedDocsRedirect(`/docs/get-started/${page}`, `/docs/react/getting-started/${page}`),
+    ),
+  );
+
+  // Backward compatibility: redirect old root paths to new getting-started paths
+  redirects.push(
+    ...localizedDocsRedirects([
+      {destination: "/docs/react/getting-started", source: "/docs/introduction"},
+      {destination: "/docs/react/getting-started/quick-start", source: "/docs/quick-start"},
+      {destination: "/docs/react/components", source: "/docs/components-list"},
+      {
+        destination: "/docs/react/getting-started/design-principles",
+        source: "/docs/react/design-principles",
+      },
+      {
+        destination: "/docs/react/getting-started/design-principles",
+        source: "/docs/design-principles",
+      },
+    ]),
+  );
+
+  // Releases (index and versions)
+  redirects.push(...localizedDocsRedirect("/docs/changelog", "/docs/react/releases"));
+
+  const releasesDir = join(rootDir, "releases");
+  const releasesVersions = await getMdxFiles(releasesDir);
+
+  redirects.push(...generateRedirects(releasesVersions, "releases"));
+
+  // Backward compatibility: redirect old changelog paths to new releases paths
+  redirects.push(...localizedDocsRedirect("/docs/react/changelog", "/docs/react/releases"));
+
+  // Generate backward compatibility redirects for all changelog version pages
+  releasesVersions.forEach((version) => {
+    redirects.push(
+      ...localizedDocsRedirect(
+        `/docs/react/changelog/${version}`,
+        `/docs/react/releases/${version}`,
+      ),
+      ...localizedDocsRedirect(`/docs/changelog/${version}`, `/docs/react/releases/${version}`),
+    );
+  });
+
+  // Components - now organized in categorized subdirectories with route groups
+  const componentsDir = join(rootDir, "components");
+  const components = await getMdxFiles(componentsDir);
+
+  redirects.push(...generateRedirects(components, "components"));
+
+  // Component name redirects - backward compatibility for renamed components
+  redirects.push(
+    ...localizedDocsRedirects([
+      {
+        destination: "/docs/react/components/typography",
+        source: "/docs/react/components/text",
+      },
+      {
+        destination: "/docs/react/components/text-area",
+        source: "/docs/react/components/textarea",
+      },
+      {
+        destination: "/docs/react/components/combo-box",
+        source: "/docs/react/components/combobox",
+      },
+      {
+        destination: "/docs/react/components/list-box",
+        source: "/docs/react/components/listbox",
+      },
+      {
+        destination: "/docs/react/components/number-field",
+        source: "/docs/react/components/numberfield",
+      },
+    ]),
+  );
+
+  // Handbook migration: redirect old handbook paths to new getting-started paths
+  // Handbook pages are now under getting-started/(handbook)/
+  const handbookPages = ["colors", "theming", "styling", "animation", "composition", "dark-mode"];
+
+  redirects.push(
+    ...handbookPages.flatMap((page) => [
+      ...localizedDocsRedirect(
+        `/docs/react/handbook/${page}`,
+        `/docs/react/getting-started/${page}`,
+      ),
+      ...localizedDocsRedirect(`/docs/handbook/${page}`, `/docs/react/getting-started/${page}`),
+    ]),
+  );
+
+  // UI for Agents migration: redirect old ui-for-agents paths to new getting-started paths
+  // UI for Agents pages are now under getting-started/(ui-for-agents)/
+  const uiForAgentsPages = ["llms-txt", "mcp-server"];
+
+  redirects.push(
+    ...uiForAgentsPages.flatMap((page) => [
+      ...localizedDocsRedirect(
+        `/docs/react/ui-for-agents/${page}`,
+        `/docs/react/getting-started/${page}`,
+      ),
+      ...localizedDocsRedirect(
+        `/docs/ui-for-agents/${page}`,
+        `/docs/react/getting-started/${page}`,
+      ),
+    ]),
+  );
+
+  return redirects;
+}
diff --git a/apps/docs/next-sitemap.config.js b/apps/docs/next-sitemap.config.js
new file mode 100644
index 0000000..9396399
--- /dev/null
+++ b/apps/docs/next-sitemap.config.js
@@ -0,0 +1,42 @@
+/* eslint-disable import/no-anonymous-default-export */
+const normalizeSiteUrl = (siteUrl) => {
+  const url = new URL(siteUrl);
+
+  if (url.hostname === "v3.heroui.com") {
+    url.hostname = "heroui.com";
+  }
+
+  return url.toString().replace(/\/$/, "");
+};
+
+const contentSignalDirective = "Content-Signal: ai-train=yes, search=yes, ai-input=yes";
+
+/** @type {import('next-sitemap').IConfig} */
+export default {
+  autoLastmod: true,
+  changefreq: "daily",
+  exclude: ["/api/*", "/llms.mdx/*", "/llms.txt", "/llms-full.txt", "/og/*"],
+  generateIndexSitemap: true,
+  generateRobotsTxt: true,
+  priority: 0.7,
+  robotsTxtOptions: {
+    additionalSitemaps: [],
+    policies: [
+      {
+        allow: "/",
+        userAgent: "*",
+      },
+    ],
+    transformRobotsTxt: async (_, robotsTxt) => {
+      if (robotsTxt.includes(contentSignalDirective)) {
+        return robotsTxt;
+      }
+
+      return robotsTxt.replace("Allow: /\n", `Allow: /\n${contentSignalDirective}\n`);
+    },
+  },
+  siteUrl: normalizeSiteUrl(
+    process.env.NEXT_PUBLIC_SITE_URL || process.env.SITE_URL || "https://heroui.com",
+  ),
+  sitemapSize: 5000,
+};
diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts
new file mode 100644
index 0000000..e1b26fd
--- /dev/null
+++ b/apps/docs/next.config.ts
@@ -0,0 +1,103 @@
+import type {NextConfig} from "next";
+
+import {createMDX} from "fumadocs-mdx/next";
+
+import {getRedirects} from "./next-redirects";
+
+// TODO: remove it for next typegen
+// validate environment variables
+// import "./env";
+
+const withMDX = createMDX();
+
+const config: NextConfig = {
+  compress: true,
+  experimental: {
+    optimizePackageImports: [
+      "@heroui/react",
+      "@gravity-ui/icons",
+      "@iconify/react",
+      "lucide-react",
+      "motion",
+      "fumadocs-ui",
+      "fumadocs-core",
+      "react-aria-components",
+    ],
+  },
+  async headers() {
+    return [
+      {
+        headers: [
+          {
+            key: "X-Robots-Tag",
+            value: "index, follow",
+          },
+        ],
+        source: "/:path*",
+      },
+      {
+        // Apple requires the AASA file to be served with `application/json`
+        // exactly — any other content type (the default `application/octet-stream`
+        // for extensionless files, or `text/plain`) causes silent rejection by
+        // iOS, which then refuses to handle Universal Links for the domain.
+        // The short cache window lets us roll out AASA changes without waiting
+        // hours for stale CDN/iOS caches to expire.
+        headers: [
+          {key: "Content-Type", value: "application/json"},
+          {key: "Cache-Control", value: "public, max-age=3600, must-revalidate"},
+        ],
+        source: "/.well-known/apple-app-site-association",
+      },
+    ];
+  },
+  images: {
+    dangerouslyAllowLocalIP: true,
+    remotePatterns: [
+      {
+        hostname: "heroui-assets.nyc3.cdn.digitaloceanspaces.com",
+        pathname: "/**",
+        protocol: "https",
+      },
+      {
+        hostname: "img.heroui.chat",
+        pathname: "/**",
+        protocol: "https",
+      },
+      {
+        hostname: "avatars.githubusercontent.com",
+        pathname: "/**",
+        protocol: "https",
+      },
+    ],
+  },
+  logging: {
+    fetches: {
+      fullUrl: true,
+    },
+  },
+  reactCompiler: true,
+  reactStrictMode: true,
+  async redirects() {
+    return getRedirects();
+  },
+  async rewrites() {
+    return [
+      {
+        destination: "/llms.mdx/:lang/:path*",
+        source: "/:lang(en|cn)/docs/:path*.mdx",
+      },
+      {
+        destination: "/llms.mdx/:path*",
+        source: "/docs/:path*.mdx",
+      },
+    ];
+  },
+  trailingSlash: false,
+  transpilePackages: ["@heroui/react", "@heroui/styles"],
+  typedRoutes: true,
+  typescript: {
+    ignoreBuildErrors: true,
+  },
+};
+
+export default withMDX(config);
diff --git a/apps/docs/package.json b/apps/docs/package.json
new file mode 100644
index 0000000..b5895ca
--- /dev/null
+++ b/apps/docs/package.json
@@ -0,0 +1,86 @@
+{
+  "name": "@heroui/docs",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "node scripts/build-skills.mjs && node scripts/build-theme-presets.mjs",
+    "dev": "next dev",
+    "prebuild": "node scripts/build-skills.mjs && node scripts/build-theme-presets.mjs",
+    "build": "next build",
+    "postbuild": "next-sitemap",
+    "start": "next start",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "typecheck": "tsc --noEmit",
+    "typegen": "next typegen",
+    "postinstall": "fumadocs-mdx",
+    "test:skills": "node test_skills_scripts.mjs",
+    "test:skills:dev": "node test_skills_scripts.mjs --env dev",
+    "test:skills:staging": "node test_skills_scripts.mjs --env staging",
+    "test:skills:prod": "node test_skills_scripts.mjs --env production"
+  },
+  "dependencies": {
+    "@fumadocs/language": "0.0.1",
+    "@gravity-ui/icons": "2.16.0",
+    "@heroui/react": "workspace:*",
+    "@iconify-json/gravity-ui": "1.2.10",
+    "@iconify/react": "6.0.2",
+    "@internationalized/date": "3.12.2",
+    "@lglab/react-qr-code": "1.7.0",
+    "@react-aria/overlays": "3.32.1",
+    "@react-stately/data": "3.16.1",
+    "@t3-oss/env-nextjs": "0.13.10",
+    "@tailwindcss/typography": "0.5.19",
+    "@tanstack/react-table": "8.21.3",
+    "@vercel/analytics": "1.6.1",
+    "@vercel/og": "0.8.6",
+    "calligraph": "1.3.0",
+    "clsx": "2.1.1",
+    "color-convert": "3.1.3",
+    "color2k": "2.0.3",
+    "culori": "4.0.2",
+    "feed": "5.1.0",
+    "fumadocs-core": "16.9.0",
+    "fumadocs-mdx": "14.2.2",
+    "fumadocs-typescript": "5.0.0",
+    "fumadocs-ui": "16.9.0",
+    "gray-matter": "4.0.3",
+    "lucide-react": "0.562.0",
+    "m3-ripple": "1.1.3",
+    "motion": "12.23.26",
+    "next": "16.2.6",
+    "next-mdx-remote": "6.0.0",
+    "next-sitemap": "4.2.3",
+    "next-themes": "0.4.6",
+    "nuqs": "2.8.6",
+    "posthog-node": "5.21.0",
+    "react": "19.2.6",
+    "react-aria-components": "1.19.0",
+    "react-dom": "19.2.6",
+    "remark": "15.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-mdx": "3.1.1",
+    "shiki": "3.20.0",
+    "tailwind-merge": "3.4.0",
+    "tailwind-variants": "3.2.2",
+    "ts-morph": "27.0.2",
+    "usehooks-ts": "3.1.1",
+    "zod": "4.2.1"
+  },
+  "devDependencies": {
+    "@heroui/standard": "workspace:*",
+    "@heroui/styles": "workspace:*",
+    "@tailwindcss/postcss": "4.3.0",
+    "@types/color-convert": "2.0.4",
+    "@types/culori": "4.0.1",
+    "@types/mdx": "2.0.13",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "babel-plugin-react-compiler": "1.0.0",
+    "postcss": "8.5.6",
+    "source-map-support": "0.5.21",
+    "tailwindcss": "4.3.0",
+    "tar": "7.5.7"
+  }
+}
diff --git a/apps/docs/postcss.config.mjs b/apps/docs/postcss.config.mjs
new file mode 100644
index 0000000..61e3684
--- /dev/null
+++ b/apps/docs/postcss.config.mjs
@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
diff --git a/apps/docs/public/.well-known/apple-app-site-association b/apps/docs/public/.well-known/apple-app-site-association
new file mode 100644
index 0000000..353ffdc
--- /dev/null
+++ b/apps/docs/public/.well-known/apple-app-site-association
@@ -0,0 +1,12 @@
+{
+  "applinks": {
+    "details": [
+      {
+        "appID": "8L5ZY5BBT6.com.herouinative.app",
+        "paths": [
+          "/docs/native-showcase/components/*"
+        ]
+      }
+    ]
+  }
+}
diff --git a/apps/docs/public/.well-known/assetlinks.json b/apps/docs/public/.well-known/assetlinks.json
new file mode 100644
index 0000000..d0762d1
--- /dev/null
+++ b/apps/docs/public/.well-known/assetlinks.json
@@ -0,0 +1,16 @@
+[
+  {
+    "relation": [
+      "delegate_permission/common.handle_all_urls",
+      "delegate_permission/common.get_login_creds"
+    ],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "com.herouinative.android",
+      "sha256_cert_fingerprints": [
+        "62:D8:E2:37:B2:F1:18:99:A5:08:6B:65:95:53:24:3F:5B:A2:A8:95:78:9E:AA:A3:D2:82:55:1F:83:74:7F:2E",
+        "77:AC:EE:FC:3F:03:A2:E7:5F:5F:08:B1:53:C9:F1:25:8C:31:0A:F1:D9:63:C9:DE:FE:F8:31:CE:F1:9A:37:9E"
+      ]
+    }
+  }
+]
diff --git a/apps/docs/public/assets/images/demo1.jpg b/apps/docs/public/assets/images/demo1.jpg
new file mode 100644
index 0000000..ab62a8b
Binary files /dev/null and b/apps/docs/public/assets/images/demo1.jpg differ
diff --git a/apps/docs/public/assets/images/demo2.jpg b/apps/docs/public/assets/images/demo2.jpg
new file mode 100644
index 0000000..bb7fe5e
Binary files /dev/null and b/apps/docs/public/assets/images/demo2.jpg differ
diff --git a/apps/docs/public/browserconfig.xml b/apps/docs/public/browserconfig.xml
new file mode 100644
index 0000000..3312355
--- /dev/null
+++ b/apps/docs/public/browserconfig.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/icons/mstile-150x150.png"/>
+            <TileColor>#000000</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>
diff --git a/apps/docs/public/fonts/Inter-Bold.ttf b/apps/docs/public/fonts/Inter-Bold.ttf
new file mode 100644
index 0000000..9fb9b75
Binary files /dev/null and b/apps/docs/public/fonts/Inter-Bold.ttf differ
diff --git a/apps/docs/public/fonts/Inter-Medium.ttf b/apps/docs/public/fonts/Inter-Medium.ttf
new file mode 100644
index 0000000..458cd06
Binary files /dev/null and b/apps/docs/public/fonts/Inter-Medium.ttf differ
diff --git a/apps/docs/public/fonts/Inter-Regular.ttf b/apps/docs/public/fonts/Inter-Regular.ttf
new file mode 100644
index 0000000..b7aaca8
Binary files /dev/null and b/apps/docs/public/fonts/Inter-Regular.ttf differ
diff --git a/apps/docs/public/icons/apple-touch-icon.png b/apps/docs/public/icons/apple-touch-icon.png
new file mode 100644
index 0000000..cf9d580
Binary files /dev/null and b/apps/docs/public/icons/apple-touch-icon.png differ
diff --git a/apps/docs/public/icons/favicon-dark.svg b/apps/docs/public/icons/favicon-dark.svg
new file mode 100644
index 0000000..8656bc1
--- /dev/null
+++ b/apps/docs/public/icons/favicon-dark.svg
@@ -0,0 +1,3 @@
+<svg width="144" height="144" viewBox="0 0 144 144" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M20 35.9116V78.9366C20 80.9702 21.0468 82.8599 22.7689 83.9354L52.1434 102.279C56.0579 104.723 61.1281 101.903 61.1281 97.2801V61.1142C61.1281 59.0335 62.2235 57.1071 64.0098 56.0467L81.9281 45.4096V138.101C81.9281 142.708 86.9678 145.531 90.8833 143.118L121.202 124.432C122.941 123.36 124 121.461 124 119.415V30.4047C124 25.8203 119.004 22.9935 115.088 25.3615L81.9281 45.4096V5.89883C81.9281 1.32685 76.9566 -1.50179 73.0394 0.841368L22.8649 30.8541C21.0882 31.9169 20 33.8378 20 35.9116Z" fill="#18181B"/>
+</svg>
diff --git a/apps/docs/public/icons/favicon-light.svg b/apps/docs/public/icons/favicon-light.svg
new file mode 100644
index 0000000..74a107c
--- /dev/null
+++ b/apps/docs/public/icons/favicon-light.svg
@@ -0,0 +1,3 @@
+<svg width="144" height="144" viewBox="0 0 144 144" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M20 35.9116V78.9366C20 80.9702 21.0468 82.8599 22.7689 83.9354L52.1434 102.279C56.0579 104.723 61.1281 101.903 61.1281 97.2801V61.1142C61.1281 59.0335 62.2235 57.1071 64.0098 56.0467L81.928 45.4096V138.101C81.928 142.708 86.9678 145.531 90.8833 143.118L121.202 124.432C122.941 123.36 124 121.461 124 119.415V30.4047C124 25.8203 119.004 22.9935 115.088 25.3615L81.928 45.4096V5.89883C81.928 1.32685 76.9566 -1.50179 73.0394 0.841368L22.8649 30.8541C21.0882 31.9169 20 33.8378 20 35.9116Z" fill="white"/>
+</svg>
diff --git a/apps/docs/public/icons/favicon.svg b/apps/docs/public/icons/favicon.svg
new file mode 100644
index 0000000..697d352
--- /dev/null
+++ b/apps/docs/public/icons/favicon.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="544" height="544" viewBox="0 0 544 544"><image width="544" height="544" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiAAAAIgCAYAAAC8idIcAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAABlZSURBVHgB7d0/f1NpdgfwA7vFdsu8ghXddni6dLG7dGHKVGvKVJhqS0yVpAK6dNhduoEqSYXmFeDp0vnuK8B0SeXoWL4gPLIsS/c+un++38/nsWRZBns+HvTzOed57oOgKZNbbh9dr/THhfs3P7bqsVV/H8DYVVs8Z/Hxi9n6snB/cS0+VgVbexCskkFgcr3q+39auP8o1g8MAAxLFd/CSN7+LeYB5Sy+BZWLYCkBZG4yW3vXt08W7gsWAGxjMZD8en2/ur4dtTEGkAwVT+Nb0NgLQQOAsupgkuuX+BZMRmMMASTDxf5s/X3Mg8ckAKB76kDyYbamMfD2zVADSIaOw9n6x5iHDwDom+lsnV7fVjEwQwogdaXjeQgdAAzLNOZh5CQGYggBJINHho6jMMsBwLBVMQ8jr6LnVZE+B5D92fpLzFstADA2J9HjINLHADKZrdcxHygFgLE7iR4GkYfRH9leyeBxHsIHANQOY/7a+C56tNPzd9EPL2frP8JwKQDcJs+1yl/Q8xf2X6Ljut6C2Y+eJToA6IBqtp7FfGC1k7ragqnbLR9D+ACA+5rE/DW0s7/Ed7EFsz9b/zlb/xAAwDbqtkxe5bdT15/pUgDJqse/zNa/h/M8AKAp9TXQ8va/oyO6MgMyCe0WAGhbNVsH0YEtu12YAcnDxD6F8AEAbZvE/DX3KHZs1y2YHDT919n6QwAAJeRrbj1nubPturtqwWQf6udwrgcA7NI05tt1qyhsFwFkEuY9AKArqtjBXEjpGZDcDiR8AEB3TGL+2rwXBZWsgNThwxZbAOiei5hXQoqcF1KqAlLvdBE+AKCb8jU6X6v/EgWU2AWT38hJAAB9kIeWVbP1a7So7QAifABA/7QeQtqcAcmZj08BAPTVj9HSTEhbMyD1wCkA0F+t7Y5powIyCVttAWAoqmjhnJCmA8gkhA8AGJoq5u2Yi2hI0y2YdyF8AMDQTGJ+CZXGNLkL5uVsHQYAMESTmJ8V8t/RgKYCyPOYX9UWABiuv4uGtuc2MQMyCaecAsBY5BxIzoNUsYUmAsh5mPsAgDGpYsuh1G1bMK9n6x8CABiT7Hr8IbaYB9mmAnIY810vAMA45fkg09jApgFkEs77AICxq2LDVsymLZhsvewHADBmG7diNqmA7IfrvAAA39y7FbNJALHrBQBYVM3W4/t8wn1bMHna6dMAAPgmWzFZ1Jiu+wn3qYBMwuApALBcDqI+jjUHUu9TATF4CgDc5g9xj4HUdSsgk5jPfgAArJJVkOquJz2M9bwMAIC7vV7nSetUQCah+gEArO/ObbnrVEBUPwCA+/jLXU+4qwIyCdUPAOD+fogVO2Lu2gWTfZy9AAC4n/+LFW2YuyogTj0FADax8lyQVTMghyF8AACbydNR92/74KoAcucACQDACs9v+8BtLZhJGD4FALa3dBj1tgrIfgAAbO9w2YO3BRDtFwCgCf+47MFlLZgcGvkcAADN+E0bZlkFZD8AAJqzf/OBZQFkaakEAGBD+zcfWBZAnHwKADTpN8WNmzMgk7D9FgBo3ndzIDcrIKofAEAbni6+czOA7AcAQPO+K3LcDCBPAgCged9ljJszIHn+x6MAAGhWzn/8UL+zWAHJ0ojwAQC0ITPGpH5nMYBMAgCgPV/nQB4uexAAoAWT+s5iADGACgC06WvWWAwg5j8AgDZ97bYs7oKxAwYAaNPXnTB1BeRRCB8AQLu+5o06gEwCAKB9k3yzWAEBAGjbJN/UAcQWXACghO9aMCogAEAJk3xjBgQAKOlP+ebh4jsAAC37bhsuAEAJ31VAJgEA0L6rudP6JNTLAABo39VpqAIIAFDag2zBTAIAoJxJBhBngAAARQkgAEBpE9twAYDiVEAAgNLMgAAA5QkgAEBpjwQQAKC0R4ZQAYDiVEAAgNK0YACA4v6oBQMAFCeAAADFZQD5UwAAlPODCggAUJoZEACgPAEEAChOAAEAihNAAIDSrg4imwQAQDmuBQMAlCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUNyD2boMAICCVEAAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQIBGPHr0KI6OjuLjx4/x+fPnuLy8/Lo+ffoU7969i/39/QBID2brMgA2lMHj+fPnV+Ej79+lqqr46aef4uzsLIBxu7Qsy9pkzSoal+fn55ebePnyZa++V8uyml0qIMC9TSaTRloqJycn8ezZswDG53ezdRwAa8gWy1//+ter4PDnP/85trW3t3d1+8svvwQwLiogwFqy2pFVj6x+NO3g4CCm02kA42EXDLBSBo7c2ZKrjfCRXr58GcC4CCDAUtluyWBwfn7e+vbZ/PNt0YVxEUCA33j69OnV2R3Hx8dRigAC4/L7ALjW1O6WTdQDqcA4qIAARdstt3ny5EkA46ECAiOX7ZbXr1+3NmAKsIwAAiO1y3YLgBYMjEwX2i0AKiAwIoeHh1ftlnUuGgfQJgEERiB3mGTwUPEAukILBgYsKx0ZPPJMD+ED6BIVEBgo7RagywQQGBjtFqAPtGBgILRbgD5RAYEB0G4B+kYAgR7TbgH6SgsGeki7Beg7FRDomefPn8fx8bF2C9BrAgj0RFY68gh1FQ9gCAQQ6Lj62i1HR0cBMBQCCHSYdgswVAIIdJB2CzB0Agh0iHYLMBYCCHSEdgswJgII7Jh2CzBGAgjsiHYLMGYCCOyAdgswdgIIFKTdAjAngEAB2i0A3xNAoGXaLQC/JYBAS7RbAG4ngEDDtFsA7iaAQIO0WwDWI4BAA7LN8vr169jb2wsA7iaAwBay0pHB4/DwMABY38MANpLtlvPzc+EDYAMqIHBP2i0A2xNAYE3aLQDN0YKBNWi3ADRLBQRW0G4BaIcKCCwxmUzi3bt38fHjR+EDoAUqIHBDfYqpw8QA2iOAwLVst2TVI6sf0AUZgrMClyvvX1xcRFVVcXZ2dnULfXdpWWNes8Bx+fPPP1+yW+fn5736uWlzzcLw5az9t/K/16dPny4PDw8vm/x7Lavw6tUXa1mNrlm75fLz58+X7J4AMg/DdwWPZf/dMrD06fu0rOvVqy/WshpZ+Q92/sNNd4w5gMzaK1uH4fz8Pn3PlhU9+2Ita6ul3dJdYw0gTYbho6OjXn3v1riXbbiMRu5umfXN4+nTpwG7lsPOszB8tdW7qcHnPLMmh6mhD+yCYfDsbqFr2tzqnT/rjx8/Dug6FRAGKwNH/nbZ5G+YsI0Mw3mk//HxcWvnzOTPuioffSCAMDj5D3vdblGOpgvyZ7Lpdssqee0i6DotGAZFu4WuyTDQZsVjmcWDy6CrVEAYBO0WuibDcFbh3rx5U/xY//z7/H9A1wkg9Jp2C12TP5NduJChAELXacHQW9otdM0u2i23cTFFuk4AoXfqgT4VD7oifxazEudnEtYngNAr9ayHqgddULcA80wP4H4EEHpD+KBLutRugT4SQOiNbLsIH+yadgs0QwChFw4PD3e6owC0W6BZAgi9kP/ww65kAM4LvWm3QHMEEDovS91aL+xCVt1cYRba4SAyOs+FtSgtKx0ZPBxwB+1RAaHznjx5ElBKBt484E67BdolgNB5XggoIdt8GTxUPKAMLRg6TwChTfXulvPzc+EDClIBAUYr2y0562HIGcoTQIDR0W6B3RNAgNHIdkseoZ6HiWntwW4JIMAoZLUjqx7aLdANAggwaNot0E0CCDBI2i3QbQIIMDjaLdB9zgEBBiMDx88//xwfP34UPqDjVECAQcjDxLRboD8EEKDXtFugn7RggF7SboF+E0CA3sndLZ8+fbo6Sh3oJy0YoDey3ZLXbtnb2wug3wQQoPNysDSDx+HhYQDDoAUDdFq2W87Pz4UPGBgVEKCTst2SW2sdoQ7DJIAAnZLtlvpMD2C4BBCgM7Ldcnx87DAxGAEBBNi56XQap6enVweKAeNgCBXYmYuLi3jx4kUcHBxchRBgPFRAgJ14+/btVbslQwgwPgIIUFRWOrLqcXZ2FsB4CSBAEXW75eTkJAAEEKB1r169ijdv3mi3AF8JIEBrst3y7NmzqKoqABYJIEDjMnBk8LCzBbiNAAI0JlssubtFuwW4iwACNEK7BbgPAQTYinYLsAkBBNiIdguwDQEEuLf3799fnemh3QJsSgAB1qbdAjTFxeiAO2WLJQ8Te/z4sfABNEIFBFgpj07Pdos5D6BJKiDAUlnpODg4uGq5CB9A01RAgO/U7Zbc3QLQFgEE+Cq31R4fH6t4AK0TQICrdktWPQyYAqUIIDBi2i3ArgggMFLaLcAu2QUDI5RVj6OjI+ED2BkBBEYmw0dWPgB2SQCBEclruAgfQBcIIDAieaIpQBcIIDASeaS6q9cCXSGAwEicnp4GQFcIIDACudvFIWNAlwggMAJnZ2cB0CUCCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnABC511cXAQAwyKA0Hm//vprADAsAgidd3Z2FgAMiwBC552cnAQAwyKA0Hk5AzKdTgOA4RBA6IVnz54ZRgUYEAGEXqiqKl69ehUADIMAQm+8efNGCAEYCAGEXjk+PhZCAAZAAKF3MoQ8fvz4qi0DQD8JIPRSho8MIaohAP0kgNBrdTXk9PQ0AOgPAYTey2rI4eHh1VZdbRmAfhBAGIw8MfXg4EA1BKAHBBAGpa6GGFIF6DYBhEEypArQbQIIg2ZIFaCbBBAGz5AqQPcIIIyGIVWA7hBAGBVDqgDdIIAwSoZUAXZLAGHUDKkC7IYAwugZUgUoTwCBa4ZUAcoRQGCBIVWAMgQQWGJxSPXi4iIAaJYAAivkkOqPP/6oLQPQMAEE7mBIFaB5AgisqR5Sffv2bQCwHQEE7iErIEdHR4ZUAbYkgMAGDKkCbEcAgS0YUgXYjAACWzKkCnB/Agg0xJAqwPoEEGiQIVWA9Qgg0AJDqgCrCSDQoq4MqarGAF0jgEDLujCk+uXLlwDoEgEECtnlkOrZ2VkAdIkAAgXtakh1Op0GQJcIILADJYdUP3z4YAYE6BwBBHaoxJBqVlwAukYAgR1rc0g1501UP4AuEkCgI5oeUs3BU9UPoKsEEOiQpoZUc+g0wwxAVwkg0EH1kOqLFy/uNaSaz83PyfDhBFagywQQ6LA3b958HVJdVRHJsJE7ajK05OcAdN3vA+i0ekg17e3txWQyubqtP5azHg4aA/pGAIEeqcPG+/fvA6DPtGAAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABGKCqqgK6TAABGKCLi4uALhNAAAYmw8fZ2VlAlwkgAAPz/v37gK4TQAAG5vT0NKDrBBCAAZlOp1cLuk4AARiInP149uxZQB8IIAADkeHD9lv6QgAB6Lm68mH4lD75fQDQWznvofJBH6mAAPRQVj1evHgRBwcHwge9pAIC0DNv376N4+Njp53SawIIQE/k6aZZ9bDNliEQQAA6LisdddUDhkIAAegwQ6YMlQAC0EEZODJ4aLcwVHbBAHTMq1ev4scffxQ+GDQVEICOyMCRQ6Y5bApDpwICsGOLZ3oIH4yFCgjADjnTg7ESQAB2wJApY6cFA1BQVjpyyPTx48fCB6OmAgJQiDM94BsBBKBl2i3wW1owAC3KIVNnesBvqYAAtMCZHrCaCghAg5zpAetRAQFoyMnJyVX4cKYH3E0AAdiSIVO4Py0YgA050wM2pwICsAFnesB2VEAA7iEDx08//XQ1ZCp8wOYEEIA11Wd6vH//PoDtaMEA3CHbLTnrYc4DmiOAANyiHjJ98+ZNAM0SQACWcKYHtEsAAVjgTA8oQwABOmHXlYb8+3PINNstqh7QvgezdRkAHfD58+d49OhRlOZMDyjPNlygM0pfvC0rHc70gN0QQIDO+PDhQ5SS7ZY8Qt2ZHrAbWjBAZ2T75fz8vNU2jDM9oBtUQIDOqAdB2/qzc1tttluED9g9FRCgU7L68enTp5hMJtGUbLPkkKndLdAdAgjQORk+MoRs24pxpgd0lxYM0DkZHPKib5vuTKmPUM8/Q/iA7rq0LMvq4ppVQi5PTk4u7+Pjx49Xn9en79OyRrp69cValjXCVQeRz58/Lw0d+XgGj/39/V59X5Y15mUGBOiVvb29qxmRej4kDy/LVo0BU+gXAQQAKM4QKgBQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxGUCqAAAop1IBAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoLgPIRQAAlFMJIABAcVowAEBxAggAUJwAAgAUZwYEACguA8iXAAAop9KCAQCKE0AAgOLMgAAApX0RQACA0i60YACA4lRAAIDSLgQQAKA0LRgAoLirAFIFAEA5KiAAQHkqIABAaSogAEBxFw+u71wGAEAZD+oKiK24AEAxAggAUFKVbwQQAKCkKt88XHwHAKCEOoB8CQCA9lX5RgUEACjpb/lGAAEASrqaOzWECgCUdJZvVEAAgJK+q4BUAQDQvirfLLZgtGEAgDZ9zRuLF6OrAgCgPWf1ncUA8msAALTn67ljiwHkLAAA2rO0AlIFAEB7lgYQFRAAoE1VfefBjQ98nq1HAQDQrNz98kP9zsMbH1QFAQDa8F3GuBlA7IQBANrwXcZQAQEASpguvnNzBiTnPz4HAECzHsfCEOrNCshF2I4LADQrOyzV4gMPlzzpQwAANOc3Ix7LAsg0AACa85vixoMlTzIHAgA0Kc//uFh8YFkFJJ8wDQCA7U3jRvhID295sjkQAKAJp8sefHDLk7VhAIAmfLf9tnZbBUQbBgDY1jRuOd7j4YpPehsAAJs7ve0DD1Z8UrZhzsPVcQGA+6ti3n5ZalUFJNswqiAAwCamqz64qgKSDKMCAJtYOnxaW1UBSVkFOQ0AgPWdxB3XlrurApL2Z+tjAACsZ2X1I91VAUnT2XofAAB3O4k7wkdapwKSJjHfEQMAsMqd1Y+0TgUkrv8gO2IAgFVOYo3wkdatgCTnggAAt6lm6yDWDCDrVkCSc0EAgNvkrtlq3SffpwJSyyrIJAAA5qpYcerpMvepgNSeBQDAN/fOBr+L+6tm64fZ+rsAAMbuJDYY0dikBZNyEPVTaMUAwJhVcY/B00WbtGBSDqRqxQDAuL2KDcJH2qQFU6tCKwYAxirbLv8aG9q0BVPTigGA8aninrtebtq0BVPLVszB9S0AMHz1a/9Wtg0gqZqtFwEAjMHGcx+LtpkBWXQW5kEAYOgyfGw897Fo2xmQmz7O1n4AAEMzjQZaL7WmA4ihVAAYnio2PO/jNk3MgCyqB1OqAACGoIoWXtubroDU9mLejnkUAEBf1YWFs2hYWwEkZQj5FABAX/0YLYSP1HQLZlF+wY5rB4B+ytfwVsJHamob7m3yC//bbD0NAKAvMnycRIvaDiBJCAGA/mg9fKQ2Z0BuMpgKAN3V2sDpMm3OgNyU35AtugDQPVUUDB+pZAWkNol5JWQSAMCuVbGDAkHJCkitivk3Og0AYJemMd9qW0VhJYZQl8k+02nMKzD7AQCU9na2/mm2/jd2YFcBpDadrS8xv4ruHwIAaFsWAf45Grqq7aZ2MQOyzCTMhQBA26royIaQXcyALFPN1uOYl4MAgObla+xO5j2W2XUL5qb/ivmhZXlmiPNCAGB71Wz9NFv/Hjua91imawEk5R7kD7P1Q8yDCACwmXrQ9H+iY7oyA3Kb/dl6F2ZDAOA+qpgfqT6NjupiBWRRFfP0lkFpEtoyALBK7nD5t5i3XKrosK4HkNo0tGUAYJX8hT2Dx39FD3S9BbPMZLaOZ+svAQC8n60X0bNrrfUxgNQmIYgAMF4nMT9VfBo91OcAUpvEPIj8fRhWBWDYcsYjWy1vru/31hACyKLDmFdE9gMAhmMa8+CRt70OHrWhBZDaJOYhRBgBoK+mMd+AcRIDCR2LhhpAFuXW3f3ZejpbT8IuGgC6qYp54JjGgCodtxlDALlpEvMQsh/fAonzRQAoKcNFnvz96/Xt+xh44LhpjAFkmQwhk+vbDCWPQjABYHsZKqr4Fjbq+3k7agLIahlAJvF9IPlTfNttMwk7bwDG6GJhVde3f1u4Xy3cZwkBpDmTmAeUumry6MaqH/vjjc+57c9a5+8DYL1qQh0WVj32ZeH9xY9Vt9yyhf8HN0L9g51rDFEAAAAASUVORK5CYII="></image><style>@media (prefers-color-scheme: light) { :root { filter: none; } }
+@media (prefers-color-scheme: dark) { :root { filter: invert(100%); } }
+</style></svg>
\ No newline at end of file
diff --git a/apps/docs/public/icons/mstile-150x150.png.png b/apps/docs/public/icons/mstile-150x150.png.png
new file mode 100644
index 0000000..e0c2d48
Binary files /dev/null and b/apps/docs/public/icons/mstile-150x150.png.png differ
diff --git a/apps/docs/public/icons/readme-logo.png b/apps/docs/public/icons/readme-logo.png
new file mode 100644
index 0000000..cc5386c
Binary files /dev/null and b/apps/docs/public/icons/readme-logo.png differ
diff --git a/apps/docs/public/icons/web-app-manifest-192x192.png b/apps/docs/public/icons/web-app-manifest-192x192.png
new file mode 100644
index 0000000..816f6e2
Binary files /dev/null and b/apps/docs/public/icons/web-app-manifest-192x192.png differ
diff --git a/apps/docs/public/icons/web-app-manifest-512x512.png b/apps/docs/public/icons/web-app-manifest-512x512.png
new file mode 100644
index 0000000..a0fe16c
Binary files /dev/null and b/apps/docs/public/icons/web-app-manifest-512x512.png differ
diff --git a/apps/docs/public/images/twitter-card-native.jpeg b/apps/docs/public/images/twitter-card-native.jpeg
new file mode 100644
index 0000000..15b26c8
Binary files /dev/null and b/apps/docs/public/images/twitter-card-native.jpeg differ
diff --git a/apps/docs/public/images/twitter-card.jpg b/apps/docs/public/images/twitter-card.jpg
new file mode 100644
index 0000000..757409b
Binary files /dev/null and b/apps/docs/public/images/twitter-card.jpg differ
diff --git a/apps/docs/public/robots.txt b/apps/docs/public/robots.txt
new file mode 100644
index 0000000..ae583d3
--- /dev/null
+++ b/apps/docs/public/robots.txt
@@ -0,0 +1,10 @@
+# *
+User-agent: *
+Allow: /
+Content-Signal: ai-train=yes, search=yes, ai-input=yes
+
+# Host
+Host: https://heroui.com
+
+# Sitemaps
+Sitemap: https://heroui.com/sitemap.xml
diff --git a/apps/docs/scripts/build-skills.mjs b/apps/docs/scripts/build-skills.mjs
new file mode 100644
index 0000000..c9159aa
--- /dev/null
+++ b/apps/docs/scripts/build-skills.mjs
@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+import {fileURLToPath} from "url";
+
+import * as tar from "tar";
+
+import {VALID_SKILLS} from "../src/lib/skills-constants.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Paths
+const repoRoot = path.join(__dirname, "../..");
+const skillsSourceDir = path.join(repoRoot, "..", "skills");
+const skillsOutputDir = path.join(__dirname, "../public/skills");
+
+/**
+ * Build tar.gz file for a skill
+ */
+async function buildSkillTarball(skillName) {
+  const skillDir = path.join(skillsSourceDir, skillName);
+  const outputFile = path.join(skillsOutputDir, `${skillName}.tar.gz`);
+
+  if (!fs.existsSync(skillDir)) {
+    throw new Error(`Skill directory not found: ${skillDir}`);
+  }
+
+  // Ensure output directory exists
+  fs.mkdirSync(skillsOutputDir, {recursive: true});
+
+  // Create tar.gz file
+  await tar.create(
+    {
+      cwd: skillDir,
+      file: outputFile,
+      gzip: true,
+    },
+    ["."],
+  );
+
+  const stats = fs.statSync(outputFile);
+
+  console.log(`✓ Built ${skillName}.tar.gz (${(stats.size / 1024).toFixed(1)}KB)`);
+}
+
+// Build all skills
+async function buildAllSkills() {
+  console.log("Building skill tarballs...");
+  console.log(`Source: ${skillsSourceDir}`);
+  console.log(`Output: ${skillsOutputDir}`);
+  console.log("");
+
+  if (!fs.existsSync(skillsSourceDir)) {
+    throw new Error(`Skills directory not found: ${skillsSourceDir}`);
+  }
+
+  for (const skillName of VALID_SKILLS) {
+    try {
+      await buildSkillTarball(skillName);
+    } catch (error) {
+      console.error(`✗ Failed to build ${skillName}:`, error.message);
+      process.exit(1);
+    }
+  }
+
+  console.log("");
+  console.log("✓ All skill tarballs built successfully");
+}
+
+buildAllSkills().catch((error) => {
+  console.error("Error building skills:", error);
+  process.exit(1);
+});
diff --git a/apps/docs/scripts/build-theme-presets.mjs b/apps/docs/scripts/build-theme-presets.mjs
new file mode 100644
index 0000000..cb4f0e8
--- /dev/null
+++ b/apps/docs/scripts/build-theme-presets.mjs
@@ -0,0 +1,494 @@
+/**
+ * Build script: generates docs theme-presets.css from the frontend's preset definitions.
+ *
+ * Usage: node apps/docs/scripts/build-theme-presets.mjs
+ * Output: apps/docs/src/styles/theme-presets.css
+ */
+
+import {writeFileSync} from "fs";
+import {dirname, resolve} from "path";
+import {fileURLToPath} from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUTPUT = resolve(__dirname, "../src/styles/theme-presets.css");
+
+// ---------------------------------------------------------------------------
+// Color math
+// ---------------------------------------------------------------------------
+
+function hexToOklch(hex) {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const toLinear = (v) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+
+  const lr = toLinear(r),
+    lg = toLinear(g),
+    lb = toLinear(b);
+
+  const x = 0.4124564 * lr + 0.3575761 * lg + 0.1804375 * lb;
+  const y = 0.2126729 * lr + 0.7151522 * lg + 0.072175 * lb;
+  const z = 0.0193339 * lr + 0.119192 * lg + 0.9503041 * lb;
+
+  const l_ = 0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z;
+  const m_ = 0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z;
+  const s_ = 0.0482003018 * x + 0.2643662691 * y + 0.633851707 * z;
+
+  const l3 = Math.cbrt(l_),
+    m3 = Math.cbrt(m_),
+    s3 = Math.cbrt(s_);
+
+  const okL = 0.2104542553 * l3 + 0.793617785 * m3 - 0.0040720468 * s3;
+  const okA = 1.9779984951 * l3 - 2.428592205 * m3 + 0.4505937099 * s3;
+  const okB = 0.0259040371 * l3 + 0.7827717662 * m3 - 0.808675766 * s3;
+
+  const c = Math.sqrt(okA * okA + okB * okB);
+  let h = (Math.atan2(okB, okA) * 180) / Math.PI;
+
+  if (h < 0) h += 360;
+
+  return {c, h, l: Math.max(0, Math.min(1, okL))};
+}
+
+function fmt(color) {
+  return `oklch(${(color.l * 100).toFixed(2)}% ${color.c.toFixed(4)} ${color.h.toFixed(2)})`;
+}
+
+function adjustHue(color, newHue) {
+  return {...color, h: newHue};
+}
+
+function adjustChroma(color, newChroma) {
+  return {...color, c: Math.max(0, newChroma)};
+}
+
+// ---------------------------------------------------------------------------
+// Default baseline neutral values (from generate-css-variables.ts)
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  dark: {
+    background: {c: 0.005, h: 285.823, l: 0.12},
+    border: {c: 0.006, h: 286.033, l: 0.28},
+    default: {c: 0.006, h: 286.033, l: 0.274},
+    foreground: {c: 0, h: 0, l: 0.9911},
+    muted: {c: 0.015, h: 286.067, l: 0.705},
+    overlay: {c: 0.0059, h: 285.89, l: 0.2103},
+    scrollbar: {c: 0.015, h: 286.067, l: 0.705},
+    segment: {c: 0.01, h: 285.93, l: 0.3964},
+    separator: {c: 0.006, h: 286.033, l: 0.25},
+    surface: {c: 0.0059, h: 285.89, l: 0.2103},
+    surfaceSecondary: {c: 0.0037, h: 286.14, l: 0.257},
+    surfaceTertiary: {c: 0.0024, h: 247.91, l: 0.2721},
+  },
+  light: {
+    background: {c: 0, h: 0, l: 0.9702},
+    border: {c: 0.004, h: 286.32, l: 0.9},
+    default: {c: 0.001, h: 286.375, l: 0.94},
+    foreground: {c: 0.0059, h: 285.89, l: 0.2103},
+    muted: {c: 0.0138, h: 285.94, l: 0.5517},
+    overlay: {c: 0, h: 0, l: 1},
+    scrollbar: {c: 0.006, h: 286.286, l: 0.871},
+    segment: {c: 0, h: 0, l: 1},
+    separator: {c: 0.004, h: 286.32, l: 0.92},
+    surface: {c: 0, h: 0, l: 1},
+    surfaceSecondary: {c: 0.0013, h: 286.37, l: 0.9524},
+    surfaceTertiary: {c: 0.0013, h: 286.37, l: 0.9373},
+  },
+};
+
+const SEMANTIC_HUE_BLEND = 0.12;
+const DEFAULT_ACCENT_HUE = 253.83;
+
+function semanticHue(semanticDefault, baseHue) {
+  let h = semanticDefault + (baseHue - DEFAULT_ACCENT_HUE) * SEMANTIC_HUE_BLEND;
+
+  while (h < 0) h += 360;
+  while (h >= 360) h -= 360;
+
+  return h;
+}
+
+// ---------------------------------------------------------------------------
+// Variable generators
+// ---------------------------------------------------------------------------
+
+function accentForeground(l, c, h) {
+  if (l > 0.65) {
+    return `oklch(15% ${Math.min(c * 0.2, 0.03).toFixed(4)} ${h.toFixed(2)})`;
+  }
+
+  return "oklch(99.11% 0 0)";
+}
+
+function genAccent(l, c, h, fgOverride) {
+  const accent = fmt({c, h, l});
+  const fg = fgOverride ?? accentForeground(l, c, h);
+
+  return {
+    "--accent": accent,
+    "--accent-foreground": fg,
+    "--focus": accent,
+  };
+}
+
+function genNeutrals(hue, grayChroma, mode) {
+  const defs = DEFAULTS[mode];
+  const f = (color, chromaMul) => fmt(adjustChroma(adjustHue(color, hue), grayChroma * chromaMul));
+
+  const bg = f(defs.background, 1);
+  const fg = f(defs.foreground, 1);
+  const muted = f(defs.muted, 2);
+  const surface = f(defs.surface, mode === "dark" ? 2 : 0.5);
+  const surfaceSec = f(defs.surfaceSecondary, 1.5);
+  const surfaceTer = f(defs.surfaceTertiary, 1.5);
+  const defaultBg = f(defs.default, 1);
+  const border = f(defs.border, 1);
+  const separator = f(defs.separator, 1);
+  const overlay = f(defs.overlay, mode === "dark" ? 2 : 0.3);
+  const scrollbar = f(defs.scrollbar, 1);
+  const segment = f(defs.segment, 1);
+  const fieldBg = surface;
+  const fieldFg = fg;
+
+  const defaultFg = mode === "dark" ? "oklch(99.11% 0 0)" : fmt({c: 0.0059, h: hue, l: 0.2103});
+
+  return {
+    "--background": bg,
+    "--border": border,
+    "--default": defaultBg,
+    "--default-foreground": defaultFg,
+    "--field-background": fieldBg,
+    "--field-border": border,
+    "--field-foreground": fieldFg,
+    "--field-placeholder": muted,
+    "--foreground": fg,
+    "--link": fg,
+    "--muted": muted,
+    "--overlay": overlay,
+    "--overlay-foreground": fg,
+    "--scrollbar": scrollbar,
+    "--segment": segment,
+    "--segment-foreground": fg,
+    "--separator": separator,
+    "--surface": surface,
+    "--surface-foreground": fg,
+    "--surface-secondary": surfaceSec,
+    "--surface-secondary-foreground": fg,
+    "--surface-tertiary": surfaceTer,
+    "--surface-tertiary-foreground": fg,
+  };
+}
+
+function genSemanticFromHex(name, hex, baseHue, grayChroma) {
+  const oklch = hexToOklch(hex);
+  const h = semanticHue(oklch.h, baseHue);
+  const boost = 1 + grayChroma * 2;
+  const c = Math.min(oklch.c * boost, 0.35);
+  const color = fmt({c, h, l: oklch.l});
+  const fg = oklch.l > 0.67 ? fmt({c: 0.0059, h, l: 0.2103}) : "oklch(99.11% 0 0)";
+
+  return {
+    [`--${name}`]: color,
+    [`--${name}-foreground`]: fg,
+  };
+}
+
+function genSemanticFromOklch(name, oklchStr, fgOverride) {
+  const lMatch = oklchStr.match(/oklch\(([\d.]+)/);
+  const l = lMatch?.[1] ? parseFloat(lMatch[1]) : 0.5;
+  let autoFg;
+
+  if (l > 0.65) {
+    const hMatch = oklchStr.match(/oklch\([\d.]+\s+[\d.]+\s+([\d.]+)/);
+    const h = hMatch?.[1] ? parseFloat(hMatch[1]) : 0;
+    const cMatch = oklchStr.match(/oklch\([\d.]+\s+([\d.]+)/);
+    const c = cMatch?.[1] ? parseFloat(cMatch[1]) : 0;
+
+    autoFg = `oklch(15% ${Math.min(c * 0.3, 0.05).toFixed(4)} ${h.toFixed(2)})`;
+  } else {
+    autoFg = "oklch(99.11% 0 0)";
+  }
+  const fg = fgOverride ?? autoFg;
+
+  return {
+    [`--${name}`]: oklchStr,
+    [`--${name}-foreground`]: fg,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Radius map
+// ---------------------------------------------------------------------------
+
+const RADIUS_MAP = {
+  "extra-large": "1rem",
+  "extra-small": "0.125rem",
+  large: "0.75rem",
+  medium: "0.5rem",
+  none: "0",
+  small: "0.25rem",
+};
+
+// ---------------------------------------------------------------------------
+// Preset definitions
+// ---------------------------------------------------------------------------
+
+const DEFAULT_SEMANTIC = {
+  dangerHex: "#FF383C",
+  successHex: "#17C964",
+  warningHex: "#F5A524",
+};
+
+const PRESETS = [
+  {
+    accentHex: "#7DD3FC",
+    base: 0.015,
+    formRadius: "large",
+    id: "sky",
+    radius: "medium",
+  },
+  {
+    accentHex: "#C084FC",
+    base: 0.015,
+    formRadius: "large",
+    id: "lavender",
+    radius: "medium",
+  },
+  {
+    accentHex: "#86EFAC",
+    base: 0.015,
+    formRadius: "large",
+    id: "mint",
+    radius: "medium",
+  },
+  {
+    accentHex: "#E50914",
+    base: 0.008,
+    formRadius: "extra-small",
+    id: "netflix",
+    radius: "extra-small",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.4964 0.1994 28.56)"},
+        success: {color: "oklch(0.7677 0.1899 148.1)"},
+        warning: {color: "oklch(0.8239 0.153 74.6)"},
+      },
+      light: {
+        danger: {color: "oklch(0.4823 0.1938 27.64)"},
+        success: {color: "oklch(0.5148 0.1337 146.82)"},
+        warning: {color: "oklch(0.561 0.116571 78.9352)"},
+      },
+    },
+  },
+  {
+    accentHex: "#000000",
+    base: 0.005,
+    darkAccent: {c: 0, h: 0, l: 0.9848},
+    darkAccentHex: "#FBFBFB",
+    formRadius: "small",
+    id: "uber",
+    radius: "small",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.7044 0.1872 23.19)"},
+        success: {color: "oklch(0.6514 0.1321 156.22)"},
+        warning: {color: "oklch(0.8803 0.1348 86.06)"},
+      },
+      light: {
+        danger: {color: "oklch(0.573 0.2249 21.97)"},
+        success: {color: "oklch(0.6277 0.1604 153.06)"},
+        warning: {color: "oklch(0.8446 0.1525 80.6)"},
+      },
+    },
+  },
+  {
+    accentHex: "#1ED760",
+    base: 0.002,
+    formRadius: "extra-small",
+    id: "spotify",
+    radius: "medium",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.5931 0.2338 25.42)"},
+        success: {color: "oklch(0.7697 0.2124 148.67)"},
+        warning: {color: "oklch(0.7921 0.1626 67.42)"},
+      },
+      light: {
+        danger: {color: "oklch(0.5509 0.2166 25.29)"},
+        success: {color: "oklch(0.6072 0.1647 149.02)"},
+        warning: {color: "oklch(0.6972 0.1687 54.22)"},
+      },
+    },
+  },
+  {
+    accentHex: "#4F44E0",
+    base: 0.002,
+    formRadius: "extra-small",
+    id: "coinbase",
+    radius: "medium",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.6545 0.2145 22.31)"},
+        success: {color: "oklch(0.7574 0.180554 156.931)"},
+        warning: {color: "oklch(0.8095 0.1119 61.69)"},
+      },
+      light: {
+        danger: {color: "oklch(0.5507 0.2062 24)"},
+        success: {color: "oklch(0.5438 0.1268 157.17)"},
+        warning: {color: "oklch(0.8095 0.1119 61.69)"},
+      },
+    },
+  },
+  {
+    accentHex: "#FF5A5F",
+    base: 0,
+    formRadius: "large",
+    id: "airbnb",
+    radius: "medium",
+    semanticOverrides: {
+      dark: {
+        accentForeground: "oklch(0.9911 0 0)",
+        danger: {color: "oklch(0.5392 0.1816 33.72)", foreground: "oklch(0.9911 0 0)"},
+        success: {color: "oklch(0.652 0.114864 185.0749)", foreground: "oklch(0.9911 0 0)"},
+        warning: {color: "oklch(0.8197 0.170602 78.4658)"},
+      },
+      light: {
+        accentForeground: "oklch(0.9911 0 0)",
+        danger: {color: "oklch(0.5392 0.1816 33.72)", foreground: "oklch(0.9911 0 0)"},
+        success: {color: "oklch(0.5573 0.0947 199.48)", foreground: "oklch(0.9911 0 0)"},
+        warning: {color: "oklch(0.6904 0.1972 38.75)", foreground: "oklch(0.9911 0 0)"},
+      },
+    },
+  },
+  {
+    accentHex: "#5865F2",
+    base: 0.01,
+    formRadius: "large",
+    id: "discord",
+    radius: "small",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.6318 0.2075 24.57)"},
+        success: {color: "oklch(0.8548 0.1967 150.16)"},
+        warning: {color: "oklch(0.9218 0.1571 99.87)"},
+      },
+      light: {
+        danger: {color: "oklch(0.5884 0.1993 24.39)"},
+        success: {color: "oklch(0.532 0.1238 151.57)"},
+        warning: {color: "oklch(0.9218 0.1571 99.87)"},
+      },
+    },
+  },
+  {
+    accentHex: "#FF6600",
+    base: 0.01,
+    formRadius: "extra-large",
+    id: "rabbit",
+    radius: "medium",
+    semanticOverrides: {
+      dark: {
+        danger: {color: "oklch(0.6291 0.2565 29.09)"},
+        success: {color: "oklch(0.7113 0.2043 140.81)"},
+      },
+      light: {
+        danger: {color: "oklch(0.6291 0.2565 29.09)"},
+        success: {color: "oklch(0.7113 0.2043 140.81)"},
+      },
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Generate CSS for a single preset
+// ---------------------------------------------------------------------------
+
+function generatePresetCss(preset) {
+  const lightAccent = hexToOklch(preset.accentHex);
+  const darkAccent = preset.darkAccentHex ? hexToOklch(preset.darkAccentHex) : lightAccent;
+  const hue = lightAccent.h;
+  const grayChroma = preset.base;
+  const so = preset.semanticOverrides;
+
+  function modeVars(mode) {
+    const accent = mode === "dark" ? darkAccent : lightAccent;
+    const modeAccent = preset[`${mode}Accent`] ?? accent;
+    const accentVars = genAccent(
+      modeAccent.l,
+      modeAccent.c,
+      modeAccent.h,
+      so?.[mode]?.accentForeground,
+    );
+    const neutrals = genNeutrals(hue, grayChroma, mode);
+
+    let semantics = {};
+
+    for (const name of ["success", "warning", "danger"]) {
+      if (so?.[mode]?.[name]) {
+        semantics = {
+          ...semantics,
+          ...genSemanticFromOklch(name, so[mode][name].color, so[mode][name].foreground),
+        };
+      } else {
+        semantics = {
+          ...semantics,
+          ...genSemanticFromHex(name, DEFAULT_SEMANTIC[`${name}Hex`], hue, grayChroma),
+        };
+      }
+    }
+
+    const radius = {};
+
+    if (preset.radius !== "medium") {
+      radius["--radius"] = RADIUS_MAP[preset.radius];
+    }
+    if (preset.formRadius !== "large") {
+      radius["--field-radius"] = RADIUS_MAP[preset.formRadius];
+    }
+
+    const charts = {
+      "--chart-1": "oklch(from var(--accent) calc(l - 0.24) c h)",
+      "--chart-2": "oklch(from var(--accent) calc(l - 0.12) c h)",
+      "--chart-3": "var(--accent)",
+      "--chart-4": "oklch(from var(--accent) calc(l + 0.12) c h)",
+      "--chart-5": "oklch(from var(--accent) calc(l + 0.24) c h)",
+    };
+
+    return {...neutrals, ...accentVars, ...semantics, ...radius, ...charts};
+  }
+
+  const light = modeVars("light");
+  const dark = modeVars("dark");
+
+  const renderVars = (vars) =>
+    Object.entries(vars)
+      .map(([k, v]) => `  ${k}: ${v};`)
+      .join("\n");
+
+  return `/* ${preset.id.charAt(0).toUpperCase() + preset.id.slice(1)} theme */
+[data-design-theme="${preset.id}"]:not(.dark):not([data-theme="dark"]) {
+${renderVars(light)}
+}
+
+[data-design-theme="${preset.id}"].dark,
+[data-design-theme="${preset.id}"][data-theme="dark"] {
+  color-scheme: dark;
+${renderVars(dark)}
+}`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const banner = `/* ============================================================================
+   Auto-generated theme presets for docs.
+   Run: node apps/docs/scripts/build-theme-presets.mjs
+   ============================================================================ */\n`;
+
+const body = PRESETS.map(generatePresetCss).join("\n\n");
+const css = `${banner}@layer base {\n${body}\n}\n`;
+
+writeFileSync(OUTPUT, css);
+console.log(`✓ Generated ${PRESETS.length} theme presets → ${OUTPUT}`);
diff --git a/apps/docs/skills/install.sh b/apps/docs/skills/install.sh
new file mode 100644
index 0000000..945add8
--- /dev/null
+++ b/apps/docs/skills/install.sh
@@ -0,0 +1,148 @@
+#!/bin/bash
+# HeroUI Skill Installer
+# Usage: curl -sSL https://heroui.com/install | bash -s [skill-name]
+# Default: heroui-react
+# Available skills: heroui-react, heroui-native, heroui-migration
+# https://heroui.com
+
+set -e
+
+# Skill selection (default: heroui-react)
+SKILL_NAME="${1:-heroui-react}"
+
+# URLs
+BASE_URL="${BASE_URL:-{{BASE_URL}}}"
+SKILL_URL="${BASE_URL}/skills/${SKILL_NAME}.tar.gz"
+
+# Codex CLI config home (override with CODEX_HOME)
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+
+INSTALLED=0
+
+echo "Installing HeroUI skill: ${SKILL_NAME}..."
+echo ""
+
+# Claude Code - Skill only (skills are auto-discovered, no command needed)
+if [ -d "$HOME/.claude" ]; then
+  mkdir -p "$HOME/.claude/skills/${SKILL_NAME}"
+  curl -sL "$SKILL_URL" | tar xz -C "$HOME/.claude/skills/${SKILL_NAME}"
+  echo "✓ Installed ${SKILL_NAME} skill for Claude Code"
+  INSTALLED=$((INSTALLED + 1))
+
+  # Cleanup old heroui skill (only when installing heroui-react)
+  if [ "$SKILL_NAME" = "heroui-react" ] && [ -d "$HOME/.claude/skills/heroui" ]; then
+    rm -rf "$HOME/.claude/skills/heroui"
+    echo "✓ Removed old heroui skill"
+  fi
+fi
+
+# Cursor - Install skill
+if [ -d "$HOME/.cursor" ]; then
+  mkdir -p "$HOME/.cursor/skills/${SKILL_NAME}"
+  curl -sL "$SKILL_URL" | tar xz -C "$HOME/.cursor/skills/${SKILL_NAME}"
+  echo "✓ Installed ${SKILL_NAME} skill for Cursor"
+  INSTALLED=$((INSTALLED + 1))
+
+  # Cleanup old heroui skill and command (only when installing heroui-react)
+  if [ "$SKILL_NAME" = "heroui-react" ]; then
+    OLD_SKILL_FOUND=0
+    if [ -d "$HOME/.cursor/skills/heroui" ]; then
+      rm -rf "$HOME/.cursor/skills/heroui"
+      echo "✓ Removed old heroui skill"
+      OLD_SKILL_FOUND=1
+    fi
+
+    if [ $OLD_SKILL_FOUND -eq 1 ] && [ -f "$HOME/.cursor/commands/heroui.md" ]; then
+      rm -f "$HOME/.cursor/commands/heroui.md"
+      echo "✓ Removed old /heroui command"
+    fi
+  fi
+fi
+
+# OpenCode - Install skill
+if command -v opencode &> /dev/null || [ -d "$HOME/.config/opencode" ]; then
+  mkdir -p "$HOME/.config/opencode/skill/${SKILL_NAME}"
+  curl -sL "$SKILL_URL" | tar xz -C "$HOME/.config/opencode/skill/${SKILL_NAME}"
+  echo "✓ Installed ${SKILL_NAME} skill for OpenCode"
+  INSTALLED=$((INSTALLED + 1))
+
+  # Cleanup old heroui skill and command (only when installing heroui-react)
+  if [ "$SKILL_NAME" = "heroui-react" ]; then
+    OLD_SKILL_FOUND=0
+    if [ -d "$HOME/.config/opencode/skill/heroui" ]; then
+      rm -rf "$HOME/.config/opencode/skill/heroui"
+      echo "✓ Removed old heroui skill"
+      OLD_SKILL_FOUND=1
+    fi
+
+    if [ $OLD_SKILL_FOUND -eq 1 ] && [ -f "$HOME/.config/opencode/command/heroui.md" ]; then
+      rm -f "$HOME/.config/opencode/command/heroui.md"
+      echo "✓ Removed old /heroui command"
+    fi
+  fi
+fi
+
+# Codex CLI - Install skill
+if command -v codex &> /dev/null || [ -d "$CODEX_HOME" ]; then
+  mkdir -p "$CODEX_HOME/skills/${SKILL_NAME}"
+  curl -sL "$SKILL_URL" | tar xz -C "$CODEX_HOME/skills/${SKILL_NAME}"
+  echo "✓ Installed ${SKILL_NAME} skill for Codex"
+  INSTALLED=$((INSTALLED + 1))
+
+  # Cleanup old heroui skill and command (only when installing heroui-react)
+  if [ "$SKILL_NAME" = "heroui-react" ]; then
+    OLD_SKILL_FOUND=0
+    if [ -d "$CODEX_HOME/skills/heroui" ]; then
+      rm -rf "$CODEX_HOME/skills/heroui"
+      echo "✓ Removed old heroui skill"
+      OLD_SKILL_FOUND=1
+    fi
+
+    if [ $OLD_SKILL_FOUND -eq 1 ] && [ -f "$CODEX_HOME/prompts/heroui.md" ]; then
+      rm -f "$CODEX_HOME/prompts/heroui.md"
+      echo "✓ Removed old /heroui command"
+    fi
+  fi
+fi
+
+# Antigravity (Gemini CLI) - Install skill
+if [ -d "$HOME/.gemini" ]; then
+  mkdir -p "$HOME/.gemini/antigravity/skills/${SKILL_NAME}"
+  curl -sL "$SKILL_URL" | tar xz -C "$HOME/.gemini/antigravity/skills/${SKILL_NAME}"
+  echo "✓ Installed ${SKILL_NAME} skill for Antigravity"
+  INSTALLED=$((INSTALLED + 1))
+
+  # Cleanup old heroui skill and command (only when installing heroui-react)
+  if [ "$SKILL_NAME" = "heroui-react" ]; then
+    OLD_SKILL_FOUND=0
+    if [ -d "$HOME/.gemini/antigravity/skills/heroui" ]; then
+      rm -rf "$HOME/.gemini/antigravity/skills/heroui"
+      echo "✓ Removed old heroui skill"
+      OLD_SKILL_FOUND=1
+    fi
+
+    if [ $OLD_SKILL_FOUND -eq 1 ] && [ -f "$HOME/.gemini/antigravity/global_workflows/heroui.md" ]; then
+      rm -f "$HOME/.gemini/antigravity/global_workflows/heroui.md"
+      echo "✓ Removed old /heroui command"
+    fi
+  fi
+fi
+
+echo ""
+
+if [ $INSTALLED -eq 0 ]; then
+  echo "No supported tools detected."
+  echo ""
+  echo "Install one of these first:"
+  echo "  • Claude Code: https://claude.ai/code"
+  echo "  • Cursor: https://cursor.com"
+  echo "  • OpenCode: https://opencode.ai"
+  echo "  • Codex: https://openai.com/codex"
+  echo "  • Antigravity: https://antigravity.google"
+  exit 1
+fi
+
+echo ""
+echo "Done! The ${SKILL_NAME} skill is now available."
+echo ""
+echo "Your AI agent will use it automatically when relevant."
diff --git a/apps/docs/source.config.ts b/apps/docs/source.config.ts
new file mode 100644
index 0000000..f93d9ef
--- /dev/null
+++ b/apps/docs/source.config.ts
@@ -0,0 +1,24 @@
+import {rehypeCodeDefaultOptions} from "fumadocs-core/mdx-plugins";
+import {defineConfig, defineDocs} from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs",
+});
+
+export default defineConfig({
+  mdxOptions: {
+    providerImportSource: "@/mdx-components",
+    rehypeCodeOptions: {
+      ...rehypeCodeDefaultOptions,
+      // Preserve meta strings in the output
+      // meta: true,
+    },
+    rehypePlugins: [],
+    remarkNpmOptions: {
+      persist: {
+        id: "package-manager",
+      },
+    },
+    remarkPlugins: [],
+  },
+});
diff --git a/apps/docs/src/app/.well-known/agent-skills/index.json/route.ts b/apps/docs/src/app/.well-known/agent-skills/index.json/route.ts
new file mode 100644
index 0000000..c646f94
--- /dev/null
+++ b/apps/docs/src/app/.well-known/agent-skills/index.json/route.ts
@@ -0,0 +1,52 @@
+import {createHash} from "node:crypto";
+import {readFile} from "node:fs/promises";
+import {join} from "node:path";
+
+import {
+  AGENT_SKILL_DESCRIPTIONS,
+  absoluteUrl,
+  getRequestOrigin,
+  jsonResponse,
+} from "@/lib/agent-discovery";
+import {VALID_SKILLS} from "@/lib/skills-constants.mjs";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+async function getSkillDigest(skillName: string): Promise<string> {
+  const skillPath = join(process.cwd(), "public", "skills", `${skillName}.tar.gz`);
+  const archive = await readFile(skillPath);
+  const digest = createHash("sha256").update(archive).digest("hex");
+
+  return `sha256:${digest}`;
+}
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+
+  try {
+    const skills = await Promise.all(
+      VALID_SKILLS.map(async (skillName) => ({
+        description:
+          AGENT_SKILL_DESCRIPTIONS[skillName] ?? `HeroUI skill archive for ${skillName}.`,
+        digest: await getSkillDigest(skillName),
+        name: skillName,
+        type: "archive",
+        url: absoluteUrl(origin, `/skills/${skillName}.tar.gz`),
+      })),
+    );
+
+    return jsonResponse({
+      $schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+      skills,
+    });
+  } catch (error) {
+    return jsonResponse(
+      {
+        error: "Failed to build agent skills index",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+      {status: 500},
+    );
+  }
+}
diff --git a/apps/docs/src/app/.well-known/api-catalog/route.ts b/apps/docs/src/app/.well-known/api-catalog/route.ts
new file mode 100644
index 0000000..4ddf798
--- /dev/null
+++ b/apps/docs/src/app/.well-known/api-catalog/route.ts
@@ -0,0 +1,95 @@
+import {
+  LINKSET_HEADERS,
+  NATIVE_MCP_API_URL,
+  REACT_MCP_API_URL,
+  absoluteUrl,
+  getAgentServiceBaseUrl,
+  getRequestOrigin,
+} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+  const agentApi = getAgentServiceBaseUrl(origin);
+
+  return new Response(
+    JSON.stringify(
+      {
+        linkset: [
+          {
+            anchor: agentApi,
+            "service-desc": [
+              {
+                href: absoluteUrl(origin, "/.well-known/openapi/heroui-agent-api.json"),
+                type: "application/vnd.oai.openapi+json",
+              },
+            ],
+            "service-doc": [
+              {
+                href: absoluteUrl(origin, "/docs/react/getting-started/llms-txt"),
+                type: "text/html",
+              },
+              {
+                href: absoluteUrl(origin, "/llms.txt"),
+                type: "text/plain",
+              },
+            ],
+            status: [
+              {
+                href: absoluteUrl(origin, "/api/agent/health"),
+                type: "application/json",
+              },
+            ],
+          },
+          {
+            anchor: REACT_MCP_API_URL,
+            "service-desc": [
+              {
+                href: absoluteUrl(origin, "/.well-known/openapi/heroui-react-mcp-api.json"),
+                type: "application/vnd.oai.openapi+json",
+              },
+            ],
+            "service-doc": [
+              {
+                href: absoluteUrl(origin, "/docs/react/getting-started/mcp-server"),
+                type: "text/html",
+              },
+            ],
+            status: [
+              {
+                href: `${REACT_MCP_API_URL}/health`,
+                type: "application/json",
+              },
+            ],
+          },
+          {
+            anchor: NATIVE_MCP_API_URL,
+            "service-desc": [
+              {
+                href: absoluteUrl(origin, "/.well-known/openapi/heroui-native-mcp-api.json"),
+                type: "application/vnd.oai.openapi+json",
+              },
+            ],
+            "service-doc": [
+              {
+                href: absoluteUrl(origin, "/docs/native/getting-started/mcp-server"),
+                type: "text/html",
+              },
+            ],
+            status: [
+              {
+                href: `${NATIVE_MCP_API_URL}/health`,
+                type: "application/json",
+              },
+            ],
+          },
+        ],
+      },
+      null,
+      2,
+    ),
+    {headers: LINKSET_HEADERS},
+  );
+}
diff --git a/apps/docs/src/app/.well-known/jwks.json/route.ts b/apps/docs/src/app/.well-known/jwks.json/route.ts
new file mode 100644
index 0000000..bbadfe8
--- /dev/null
+++ b/apps/docs/src/app/.well-known/jwks.json/route.ts
@@ -0,0 +1,8 @@
+import {jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET() {
+  return jsonResponse({keys: []});
+}
diff --git a/apps/docs/src/app/.well-known/mcp/server-card.json/route.ts b/apps/docs/src/app/.well-known/mcp/server-card.json/route.ts
new file mode 100644
index 0000000..f06d0e8
--- /dev/null
+++ b/apps/docs/src/app/.well-known/mcp/server-card.json/route.ts
@@ -0,0 +1,112 @@
+import {
+  MCP_PACKAGE_VERSION,
+  NATIVE_MCP_API_URL,
+  REACT_MCP_API_URL,
+  absoluteUrl,
+  getRequestOrigin,
+  jsonResponse,
+} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+
+  return jsonResponse({
+    $schema: "https://modelcontextprotocol.io/schemas/server-card/draft.json",
+    capabilities: {
+      prompts: false,
+      resources: false,
+      tools: true,
+    },
+    description:
+      "HeroUI MCP servers expose read-only HeroUI React and HeroUI Native documentation, component metadata, source references, styles, and theme variables to AI coding agents.",
+    endpoint: absoluteUrl(origin, "/.well-known/mcp/server-card.json"),
+    links: {
+      docs: [
+        absoluteUrl(origin, "/docs/react/getting-started/mcp-server"),
+        absoluteUrl(origin, "/docs/native/getting-started/mcp-server"),
+      ],
+      npm: [
+        "https://www.npmjs.com/package/@heroui/react-mcp",
+        "https://www.npmjs.com/package/@heroui/native-mcp",
+      ],
+      source: "https://github.com/heroui-inc/heroui-mcp",
+    },
+    notes:
+      "The supported MCP transport today is stdio through the published npm packages. The endpoint field identifies this server card for browser and catalog discovery; it is not a Streamable HTTP MCP endpoint.",
+    serverInfo: {
+      name: "HeroUI MCP",
+      version: MCP_PACKAGE_VERSION,
+    },
+    tools: [
+      {
+        description: "List all available HeroUI v3 React components.",
+        name: "list_components",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "Get complete React component documentation.",
+        name: "get_component_docs",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "Get React component TypeScript source code.",
+        name: "get_component_source_code",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "Get React component CSS source styles.",
+        name: "get_component_source_styles",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "Get HeroUI React theme variables.",
+        name: "get_theme_variables",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "Browse full HeroUI React documentation.",
+        name: "get_docs",
+        package: "@heroui/react-mcp",
+      },
+      {
+        description: "List all available HeroUI Native components.",
+        name: "list_components",
+        package: "@heroui/native-mcp",
+      },
+      {
+        description: "Get complete Native component documentation.",
+        name: "get_component_docs",
+        package: "@heroui/native-mcp",
+      },
+      {
+        description: "Get HeroUI Native theme variables.",
+        name: "get_theme_variables",
+        package: "@heroui/native-mcp",
+      },
+      {
+        description: "Browse full HeroUI Native documentation.",
+        name: "get_docs",
+        package: "@heroui/native-mcp",
+      },
+    ],
+    transports: [
+      {
+        args: ["-y", "@heroui/react-mcp@latest"],
+        command: "npx",
+        dataApi: REACT_MCP_API_URL,
+        package: "@heroui/react-mcp",
+        type: "stdio",
+      },
+      {
+        args: ["-y", "@heroui/native-mcp@latest"],
+        command: "npx",
+        dataApi: NATIVE_MCP_API_URL,
+        package: "@heroui/native-mcp",
+        type: "stdio",
+      },
+    ],
+  });
+}
diff --git a/apps/docs/src/app/.well-known/oauth-authorization-server/route.ts b/apps/docs/src/app/.well-known/oauth-authorization-server/route.ts
new file mode 100644
index 0000000..0e17ff8
--- /dev/null
+++ b/apps/docs/src/app/.well-known/oauth-authorization-server/route.ts
@@ -0,0 +1,22 @@
+import {absoluteUrl, getRequestOrigin, jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+
+  return jsonResponse({
+    authorization_endpoint: absoluteUrl(origin, "/.well-known/oauth/not-supported/authorize"),
+    authorization_response_iss_parameter_supported: false,
+    grant_types_supported: [],
+    heroui_public_api_authentication:
+      "HeroUI public documentation and MCP data APIs are currently unauthenticated and read-only; no OAuth grants are advertised for public access.",
+    issuer: origin,
+    jwks_uri: absoluteUrl(origin, "/.well-known/jwks.json"),
+    response_types_supported: [],
+    scopes_supported: [],
+    service_documentation: absoluteUrl(origin, "/.well-known/api-catalog"),
+    token_endpoint: absoluteUrl(origin, "/.well-known/oauth/not-supported/token"),
+  });
+}
diff --git a/apps/docs/src/app/.well-known/oauth-protected-resource/route.ts b/apps/docs/src/app/.well-known/oauth-protected-resource/route.ts
new file mode 100644
index 0000000..4605687
--- /dev/null
+++ b/apps/docs/src/app/.well-known/oauth-protected-resource/route.ts
@@ -0,0 +1,17 @@
+import {absoluteUrl, getRequestOrigin, jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+
+  return jsonResponse({
+    authorization_servers: [origin],
+    heroui_public_api_authentication:
+      "HeroUI public documentation and MCP data APIs are currently unauthenticated and read-only. This metadata exists so agents can discover that no OAuth scopes are required for public resources.",
+    resource: origin,
+    resource_documentation: absoluteUrl(origin, "/.well-known/api-catalog"),
+    scopes_supported: [],
+  });
+}
diff --git a/apps/docs/src/app/.well-known/openapi/[api]/route.ts b/apps/docs/src/app/.well-known/openapi/[api]/route.ts
new file mode 100644
index 0000000..578d589
--- /dev/null
+++ b/apps/docs/src/app/.well-known/openapi/[api]/route.ts
@@ -0,0 +1,234 @@
+import {
+  AGENT_API_VERSION,
+  NATIVE_MCP_API_URL,
+  OPENAPI_HEADERS,
+  REACT_MCP_API_URL,
+  absoluteUrl,
+  getAgentServiceBaseUrl,
+  getRequestOrigin,
+} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+type OpenAPIDocument = Record<string, unknown>;
+
+function baseDocument(
+  title: string,
+  version: string,
+  serverUrl: string,
+  description: string,
+): OpenAPIDocument {
+  return {
+    info: {
+      description,
+      title,
+      version,
+    },
+    openapi: "3.1.0",
+    servers: [{url: serverUrl}],
+  };
+}
+
+function agentApiDocument(origin: string): OpenAPIDocument {
+  return {
+    ...baseDocument(
+      "HeroUI Docs Agent API",
+      AGENT_API_VERSION,
+      getAgentServiceBaseUrl(origin),
+      "Read-only endpoints that help agents search HeroUI documentation and retrieve markdown page content.",
+    ),
+    paths: {
+      "/health": {
+        get: {
+          operationId: "getAgentApiHealth",
+          responses: {
+            "200": {
+              description: "Agent API health status",
+            },
+          },
+          summary: "Check service health",
+        },
+      },
+      "/page": {
+        get: {
+          operationId: "getHeroUIDocPageMarkdown",
+          parameters: [
+            {
+              description: "HeroUI docs page URL, for example /docs/react/components/button",
+              in: "query",
+              name: "url",
+              required: true,
+              schema: {type: "string"},
+            },
+          ],
+          responses: {
+            "200": {description: "Documentation page metadata and markdown"},
+            "404": {description: "Documentation page not found"},
+          },
+          summary: "Retrieve a documentation page as markdown",
+        },
+      },
+      "/search": {
+        get: {
+          operationId: "searchHeroUIDocs",
+          parameters: [
+            {in: "query", name: "q", required: true, schema: {type: "string"}},
+            {
+              in: "query",
+              name: "platform",
+              schema: {default: "all", enum: ["all", "react", "native"], type: "string"},
+            },
+            {
+              in: "query",
+              name: "limit",
+              schema: {default: 10, maximum: 20, minimum: 1, type: "integer"},
+            },
+          ],
+          responses: {
+            "200": {description: "Matching documentation pages"},
+            "400": {description: "Invalid request"},
+          },
+          summary: "Search HeroUI documentation",
+        },
+      },
+    },
+  };
+}
+
+function mcpApiDocument(kind: "react" | "native"): OpenAPIDocument {
+  const isReact = kind === "react";
+  const serverUrl = isReact ? REACT_MCP_API_URL : NATIVE_MCP_API_URL;
+  const title = isReact ? "HeroUI React MCP Data API" : "HeroUI Native MCP Data API";
+  const componentSourcePaths = isReact
+    ? {
+        "/v1/components/source": {
+          post: {
+            operationId: "getComponentSource",
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    properties: {components: {items: {type: "string"}, type: "array"}},
+                    type: "object",
+                  },
+                },
+              },
+            },
+            responses: {"200": {description: "Component source code"}},
+            summary: "Get component TypeScript source",
+          },
+        },
+        "/v1/components/styles": {
+          post: {
+            operationId: "getComponentStyles",
+            requestBody: {
+              content: {
+                "application/json": {
+                  schema: {
+                    properties: {components: {items: {type: "string"}, type: "array"}},
+                    type: "object",
+                  },
+                },
+              },
+            },
+            responses: {"200": {description: "Component CSS styles"}},
+            summary: "Get component styles",
+          },
+        },
+      }
+    : {};
+
+  return {
+    ...baseDocument(
+      title,
+      "1.1.0",
+      serverUrl,
+      `Read-only data API used by the ${isReact ? "@heroui/react-mcp" : "@heroui/native-mcp"} package and HeroUI agent skills.`,
+    ),
+    paths: {
+      "/health": {
+        get: {
+          operationId: "getHealth",
+          responses: {"200": {description: "Health status"}},
+          summary: "Check API health",
+        },
+      },
+      "/v1/components": {
+        get: {
+          operationId: "listComponents",
+          responses: {"200": {description: "Available components"}},
+          summary: "List available components",
+        },
+      },
+      "/v1/components/docs": {
+        post: {
+          operationId: "getComponentDocs",
+          requestBody: {
+            content: {
+              "application/json": {
+                schema: {
+                  properties: {components: {items: {type: "string"}, type: "array"}},
+                  type: "object",
+                },
+              },
+            },
+          },
+          responses: {"200": {description: "Component documentation"}},
+          summary: "Get component documentation",
+        },
+      },
+      ...componentSourcePaths,
+      "/v1/docs/{path}": {
+        get: {
+          operationId: "getDocs",
+          parameters: [{in: "path", name: "path", required: true, schema: {type: "string"}}],
+          responses: {"200": {description: "Documentation content"}},
+          summary: "Get documentation by path",
+        },
+      },
+      "/v1/themes/variables": {
+        get: {
+          operationId: "getThemeVariables",
+          parameters: [{in: "query", name: "theme", schema: {default: "default", type: "string"}}],
+          responses: {"200": {description: "Theme variables"}},
+          summary: "Get theme variables",
+        },
+      },
+    },
+  };
+}
+
+const OPENAPI_BUILDERS: Record<string, (origin: string) => OpenAPIDocument> = {
+  "heroui-agent-api.json": agentApiDocument,
+  "heroui-native-mcp-api.json": () => mcpApiDocument("native"),
+  "heroui-react-mcp-api.json": () => mcpApiDocument("react"),
+};
+
+export async function GET(request: Request, {params}: {params: Promise<{api: string}>}) {
+  const {api} = await params;
+  const builder = OPENAPI_BUILDERS[api];
+
+  if (!builder) {
+    return new Response(
+      JSON.stringify(
+        {available: Object.keys(OPENAPI_BUILDERS), error: "OpenAPI description not found"},
+        null,
+        2,
+      ),
+      {
+        headers: {"Content-Type": "application/json; charset=utf-8"},
+        status: 404,
+      },
+    );
+  }
+
+  const origin = getRequestOrigin(request);
+
+  return new Response(JSON.stringify(builder(origin), null, 2), {
+    headers: {
+      ...OPENAPI_HEADERS,
+      Link: `<${absoluteUrl(origin, "/.well-known/api-catalog")}>; rel="api-catalog"; type="application/linkset+json"`,
+    },
+  });
+}
diff --git a/apps/docs/src/app/.well-known/openid-configuration/route.ts b/apps/docs/src/app/.well-known/openid-configuration/route.ts
new file mode 100644
index 0000000..b114c67
--- /dev/null
+++ b/apps/docs/src/app/.well-known/openid-configuration/route.ts
@@ -0,0 +1,22 @@
+import {absoluteUrl, getRequestOrigin, jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: Request) {
+  const origin = getRequestOrigin(request);
+
+  return jsonResponse({
+    authorization_endpoint: absoluteUrl(origin, "/.well-known/oauth/not-supported/authorize"),
+    claims_supported: [],
+    grant_types_supported: [],
+    heroui_public_api_authentication:
+      "HeroUI public documentation and MCP data APIs are currently unauthenticated and read-only; no OpenID Connect sign-in flow is advertised for public API access.",
+    issuer: origin,
+    jwks_uri: absoluteUrl(origin, "/.well-known/jwks.json"),
+    response_types_supported: [],
+    scopes_supported: [],
+    subject_types_supported: [],
+    token_endpoint: absoluteUrl(origin, "/.well-known/oauth/not-supported/token"),
+  });
+}
diff --git a/apps/docs/src/app/[lang]/(home)/components/demo-showcase.tsx b/apps/docs/src/app/[lang]/(home)/components/demo-showcase.tsx
new file mode 100644
index 0000000..efc1381
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/demo-showcase.tsx
@@ -0,0 +1,313 @@
+"use client";
+
+import type {ThemeId} from "@/app/[lang]/themes/constants";
+import type {CSSProperties} from "react";
+import type {Color} from "react-aria-components";
+
+import {Palette} from "@gravity-ui/icons";
+import {ColorSwatchPicker, Spinner, Tabs, Tooltip, buttonVariants} from "@heroui/react";
+import {converter} from "culori";
+import LinkRoot from "fumadocs-core/link";
+import {useTheme} from "next-themes";
+import {useCallback, useEffect, useMemo, useRef, useState} from "react";
+
+import {HEROUI_PRO_URL, iframeTabs, themeValuesById} from "@/app/[lang]/themes/constants";
+import {computeThemeVars} from "@/app/[lang]/themes/hooks";
+import {
+  calculateAccentForeground,
+  getDerivedColorFormulas,
+} from "@/app/[lang]/themes/utils/generate-theme-colors";
+import {DemoComponents} from "@/components/demo";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+import {
+  DEFAULT_DESIGN_THEME,
+  DESIGN_THEME_CHANGE_EVENT,
+  DESIGN_THEME_STORAGE_KEY,
+  getStoredDesignTheme,
+  isDesignThemeId,
+} from "@/utils/design-theme";
+
+const tabs = [
+  {id: "components"},
+  {id: "dashboard"},
+  {id: "mail"},
+  {id: "chat"},
+  {id: "finances"},
+] as const;
+
+const colors = [
+  "#FF81B9", // pink
+  "#FF8289", // red
+  "#FF9A00", // orange
+  "#DCBE00", // yellow
+  "#72DB5A", // green
+  "#00D7FF", // soft teal
+  "#5DBFFF", // soft cyan
+  "#A8ABFF", // soft blue
+];
+
+const toOklch = converter("oklch");
+
+function getProUrl(utm: {campaign?: string; content?: string; medium: string}) {
+  const url = new URL(HEROUI_PRO_URL);
+
+  url.searchParams.set("utm_source", "heroui.com");
+  url.searchParams.set("utm_medium", utm.medium);
+  if (utm.campaign) url.searchParams.set("utm_campaign", utm.campaign);
+  if (utm.content) url.searchParams.set("utm_content", utm.content);
+
+  return url.toString();
+}
+
+function getAccentStyleVars(color: Color, theme: "light" | "dark"): Record<string, string> {
+  const oklch = toOklch(color.toString("css"));
+
+  if (!oklch) return {};
+
+  const l = oklch.l ?? 0;
+  const c = oklch.c ?? 0;
+  const h = oklch.h ?? 0;
+
+  const accent = `oklch(${(l * 100).toFixed(2)}% ${c.toFixed(4)} ${h.toFixed(2)})`;
+  const accentFg = calculateAccentForeground(l, c, h);
+
+  return {
+    "--accent": accent,
+    "--accent-foreground": accentFg,
+    "--focus": accent,
+    ...getDerivedColorFormulas(theme),
+  };
+}
+
+const LOADER_DURATION_MS = 250;
+
+export function DemoShowcase() {
+  const dict = useDictionary();
+  const demo = dict.home.demo;
+  const tabLabels = dict.themeBuilder.tabs;
+  const [selectedTab, setSelectedTab] = useState("components");
+  const [selectedColor, setSelectedColor] = useState<Color | null>(null);
+  const [activeDesignTheme, setActiveDesignTheme] = useState<ThemeId>(getStoredDesignTheme);
+  const [iframeLoading, setIframeLoading] = useState(true);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const {resolvedTheme} = useTheme();
+
+  const currentTheme = (resolvedTheme === "dark" ? "dark" : "light") as "light" | "dark";
+
+  const accentVars = useMemo(
+    () => (selectedColor ? getAccentStyleVars(selectedColor, currentTheme) : {}),
+    [selectedColor, currentTheme],
+  );
+
+  const computedDesignThemeVars = useMemo(
+    () => computeThemeVars(themeValuesById[activeDesignTheme]),
+    [activeDesignTheme],
+  );
+
+  const iframeThemeVars = useMemo(() => {
+    const modeVars =
+      resolvedTheme === "light"
+        ? computedDesignThemeVars.fullLightVars
+        : computedDesignThemeVars.fullDarkVars;
+
+    return Object.keys(accentVars).length > 0 ? {...modeVars, ...accentVars} : modeVars;
+  }, [accentVars, computedDesignThemeVars, resolvedTheme]);
+
+  const themeBuilderHref = useMemo(() => {
+    const params = new URLSearchParams();
+
+    if (selectedTab !== "components") {
+      params.set("template", selectedTab);
+    }
+    if (selectedColor) {
+      const oklch = toOklch(selectedColor.toString("css"));
+
+      if (oklch) {
+        params.set("lightness", String(oklch.l ?? 0));
+        params.set("chroma", String(oklch.c ?? 0));
+        params.set("hue", String(oklch.h ?? 0));
+      }
+    }
+    const qs = params.toString();
+
+    return qs ? `/themes?${qs}` : "/themes";
+  }, [selectedTab, selectedColor]);
+
+  const [prevSelectedTab, setPrevSelectedTab] = useState(selectedTab);
+
+  if (selectedTab !== prevSelectedTab) {
+    setPrevSelectedTab(selectedTab);
+    if (!iframeLoading) {
+      setIframeLoading(true);
+    }
+  }
+
+  useEffect(() => {
+    const timeoutId = window.setTimeout(() => {
+      setActiveDesignTheme(getStoredDesignTheme());
+    });
+
+    function handleDesignThemeChange(event: Event) {
+      const themeId = (event as CustomEvent<{themeId?: string}>).detail?.themeId;
+
+      if (isDesignThemeId(themeId)) {
+        setActiveDesignTheme(themeId);
+      }
+    }
+
+    function handleStorage(event: StorageEvent) {
+      if (event.key !== DESIGN_THEME_STORAGE_KEY) return;
+
+      setActiveDesignTheme(isDesignThemeId(event.newValue) ? event.newValue : DEFAULT_DESIGN_THEME);
+    }
+
+    window.addEventListener(DESIGN_THEME_CHANGE_EVENT, handleDesignThemeChange);
+    window.addEventListener("storage", handleStorage);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+      window.removeEventListener(DESIGN_THEME_CHANGE_EVENT, handleDesignThemeChange);
+      window.removeEventListener("storage", handleStorage);
+    };
+  }, []);
+
+  const sendMessageToIframe = useCallback(() => {
+    const iframe = iframeRef.current;
+
+    if (!iframe?.contentWindow) return;
+    iframe.contentWindow.postMessage({theme: resolvedTheme ?? "dark", type: "heroui-theme"}, "*");
+    iframe.contentWindow.postMessage({type: "heroui-accent", vars: iframeThemeVars}, "*");
+    iframe.contentWindow.postMessage(
+      {
+        cdnUrl: computedDesignThemeVars.fontMeta.cdnUrl,
+        family: computedDesignThemeVars.fontMeta.family,
+        type: "heroui-font",
+        variable: computedDesignThemeVars.fontMeta.variable,
+      },
+      "*",
+    );
+  }, [computedDesignThemeVars.fontMeta, iframeThemeVars, resolvedTheme]);
+
+  // Re-send whenever theme or accent changes
+  useEffect(() => {
+    sendMessageToIframe();
+  }, [sendMessageToIframe]);
+
+  // Listen for iframe requesting initial state
+  useEffect(() => {
+    function handleMessage(event: MessageEvent) {
+      if (event.data?.type === "heroui-ready") {
+        sendMessageToIframe();
+      }
+    }
+
+    window.addEventListener("message", handleMessage);
+
+    return () => window.removeEventListener("message", handleMessage);
+  }, [sendMessageToIframe]);
+
+  const handleIframeLoad = useCallback(() => {
+    sendMessageToIframe();
+    setTimeout(() => {
+      setIframeLoading(false);
+    }, LOADER_DURATION_MS);
+  }, [sendMessageToIframe]);
+
+  return (
+    <div className="flex min-h-0 w-full max-w-[1200px] flex-1 flex-col py-6 lg:py-10">
+      <div className="mb-4 hidden w-full flex-col justify-between gap-4 px-2 lg:flex lg:flex-row lg:items-center">
+        <Tabs selectedKey={selectedTab} onSelectionChange={(key) => setSelectedTab(key as string)}>
+          <Tabs.ListContainer>
+            <Tabs.List>
+              {tabs.map((tab) => (
+                <Tabs.Tab key={tab.id} className="whitespace-nowrap" id={tab.id}>
+                  {tabLabels[tab.id]}
+                  <Tabs.Indicator />
+                </Tabs.Tab>
+              ))}
+            </Tabs.List>
+          </Tabs.ListContainer>
+        </Tabs>
+        <div className="flex items-center gap-3">
+          <a
+            className={`text-[13px] font-medium text-muted transition-opacity duration-300 hover:text-foreground ${selectedTab !== "components" ? "opacity-100" : "pointer-events-none opacity-0"}`}
+            rel="noopener noreferrer"
+            target="_blank"
+            href={getProUrl({
+              campaign: "demo-showcase",
+              content: `template-${selectedTab}`,
+              medium: "homepage",
+            })}
+          >
+            {demo.proTemplate}
+          </a>
+          <div className="flex items-center gap-1">
+            <ColorSwatchPicker size="sm" onChange={setSelectedColor}>
+              {colors.map((color) => (
+                <ColorSwatchPicker.Item key={color} color={color}>
+                  <ColorSwatchPicker.Swatch />
+                  <ColorSwatchPicker.Indicator />
+                </ColorSwatchPicker.Item>
+              ))}
+            </ColorSwatchPicker>
+            <Tooltip delay={0}>
+              <Tooltip.Trigger>
+                <LinkRoot
+                  href={themeBuilderHref}
+                  className={buttonVariants({
+                    className: "text-muted",
+                    isIconOnly: true,
+                    size: "sm",
+                    variant: "ghost",
+                  })}
+                >
+                  <Palette className="size-4" />
+                </LinkRoot>
+              </Tooltip.Trigger>
+              <Tooltip.Content className="py-0">{demo.themeBuilder}</Tooltip.Content>
+            </Tooltip>
+          </div>
+        </div>
+      </div>
+      <div
+        className="flex min-h-[420px] max-w-[1200px] flex-1 flex-col"
+        style={accentVars as CSSProperties}
+      >
+        {/* Mobile: always show DemoComponents */}
+        <div className="flex w-full justify-center rounded-2xl bg-background py-8 lg:hidden">
+          <DemoComponents />
+        </div>
+        {/* Desktop: respect tab selection */}
+        <div className="relative hidden min-h-0 flex-1 lg:flex lg:flex-col">
+          <div
+            className={`flex flex-1 justify-center overflow-x-hidden overflow-y-auto rounded-2xl border border-border/50 bg-background py-8 ${selectedTab !== "components" ? "invisible" : ""}`}
+          >
+            <div className="my-auto">
+              <DemoComponents />
+            </div>
+          </div>
+          {selectedTab !== "components" && iframeTabs[selectedTab] != null && (
+            <div className="absolute inset-0">
+              <iframe
+                ref={iframeRef}
+                className="absolute inset-0 h-full w-full rounded-2xl border border-border/50"
+                src={iframeTabs[selectedTab]}
+                title={selectedTab}
+                onLoad={handleIframeLoad}
+              />
+              <div
+                className={cn(
+                  "pointer-events-none absolute inset-0 z-10 flex items-center justify-center rounded-2xl bg-background transition-opacity duration-300",
+                  iframeLoading ? "opacity-100" : "opacity-0",
+                )}
+              >
+                <Spinner />
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/components/floating-stars.tsx b/apps/docs/src/app/[lang]/(home)/components/floating-stars.tsx
new file mode 100644
index 0000000..e759eea
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/floating-stars.tsx
@@ -0,0 +1,1920 @@
+import type {ReactNode} from "react";
+
+function FloatingStarsForward() {
+  return (
+    <div className="absolute inset-[5.73%_3.6%_4.36%_3.18%] animate-[float-stars_12s_ease-in-out_infinite]">
+      <svg
+        className="absolute block size-full"
+        fill="none"
+        preserveAspectRatio="none"
+        viewBox="0 0 709.134 573.351"
+      >
+        <g id="Group" opacity="0.7">
+          <path
+            d="M175.054 442.166C175.529 441.858 175.664 441.223 175.356 440.748C175.048 440.273 174.413 440.138 173.938 440.447C173.463 440.755 173.328 441.39 173.636 441.865C173.945 442.34 174.579 442.475 175.054 442.166Z"
+            fill="var(--fill-0, white)"
+            id="Vector"
+            opacity="0.11"
+          />
+          <path
+            d="M180.908 445.081C181.264 444.85 181.365 444.374 181.134 444.018C180.903 443.661 180.427 443.56 180.071 443.791C179.715 444.022 179.613 444.498 179.844 444.855C180.075 445.211 180.551 445.312 180.908 445.081Z"
+            fill="var(--fill-0, white)"
+            id="Vector_2"
+          />
+          <path
+            d="M189.24 426.854C189.596 426.623 189.697 426.147 189.466 425.791C189.235 425.435 188.759 425.334 188.403 425.565C188.047 425.796 187.945 426.272 188.176 426.628C188.407 426.984 188.884 427.085 189.24 426.854Z"
+            fill="var(--fill-0, white)"
+            id="Vector_3"
+          />
+          <path
+            d="M152.15 449.698C152.506 449.467 152.607 448.991 152.376 448.635C152.145 448.279 151.669 448.177 151.313 448.408C150.957 448.64 150.855 449.116 151.087 449.472C151.318 449.828 151.794 449.929 152.15 449.698Z"
+            fill="var(--fill-0, white)"
+            id="Vector_4"
+          />
+          <path
+            d="M137.57 473.819C138.045 473.511 138.18 472.876 137.872 472.401C137.564 471.926 136.929 471.791 136.454 472.099C135.979 472.407 135.844 473.042 136.152 473.517C136.46 473.992 137.095 474.127 137.57 473.819Z"
+            fill="var(--fill-0, white)"
+            id="Vector_5"
+            opacity="0.11"
+          />
+          <path
+            d="M123.269 469.663C123.506 469.509 123.573 469.192 123.419 468.955C123.265 468.717 122.948 468.65 122.711 468.804C122.474 468.958 122.406 469.275 122.56 469.512C122.714 469.75 123.031 469.817 123.269 469.663Z"
+            fill="var(--fill-0, white)"
+            id="Vector_6"
+          />
+          <path
+            d="M184.636 459.765C184.873 459.611 184.941 459.294 184.787 459.056C184.633 458.819 184.315 458.752 184.078 458.906C183.841 459.06 183.773 459.377 183.927 459.614C184.081 459.851 184.398 459.919 184.636 459.765Z"
+            fill="var(--fill-0, white)"
+            id="Vector_7"
+          />
+          <path
+            d="M278.327 398.966C278.565 398.812 278.632 398.495 278.478 398.257C278.324 398.02 278.007 397.953 277.77 398.107C277.532 398.261 277.465 398.578 277.619 398.815C277.773 399.052 278.09 399.12 278.327 398.966Z"
+            fill="var(--fill-0, white)"
+            id="Vector_8"
+          />
+          <path
+            d="M310.108 345.359C310.346 345.205 310.413 344.887 310.259 344.65C310.105 344.413 309.788 344.345 309.551 344.499C309.314 344.653 309.246 344.97 309.4 345.208C309.554 345.445 309.871 345.513 310.108 345.359Z"
+            fill="var(--fill-0, white)"
+            id="Vector_9"
+          />
+          <path
+            d="M347.23 365.855C347.467 365.701 347.534 365.383 347.38 365.146C347.226 364.909 346.909 364.841 346.672 364.995C346.435 365.149 346.367 365.467 346.521 365.704C346.675 365.941 346.992 366.009 347.23 365.855Z"
+            fill="var(--fill-0, white)"
+            id="Vector_10"
+          />
+          <path
+            d="M34.5537 541.892C34.791 541.738 34.8585 541.421 34.7046 541.183C34.5506 540.946 34.2334 540.879 33.9961 541.033C33.7588 541.187 33.6913 541.504 33.8453 541.741C33.9993 541.978 34.3165 542.046 34.5537 541.892Z"
+            fill="var(--fill-0, white)"
+            id="Vector_11"
+          />
+          <path
+            d="M13.0498 522.866C13.2871 522.712 13.3546 522.395 13.2006 522.158C13.0467 521.921 12.7295 521.853 12.4922 522.007C12.2549 522.161 12.1874 522.478 12.3414 522.716C12.4954 522.953 12.8126 523.02 13.0498 522.866Z"
+            fill="var(--fill-0, white)"
+            id="Vector_12"
+            opacity="0.11"
+          />
+          <path
+            d="M0.987313 544.743C1.22459 544.589 1.29212 544.272 1.13814 544.035C0.984157 543.798 0.666993 543.73 0.429718 543.884C0.192444 544.038 0.12491 544.355 0.278892 544.593C0.432874 544.83 0.750038 544.897 0.987313 544.743Z"
+            fill="var(--fill-0, white)"
+            id="Vector_13"
+            opacity="0.11"
+          />
+          <path
+            d="M31.9014 561.325C32.1387 561.171 32.2062 560.854 32.0522 560.617C31.8982 560.38 31.5811 560.312 31.3438 560.466C31.1065 560.62 31.039 560.937 31.193 561.175C31.3469 561.412 31.6641 561.479 31.9014 561.325Z"
+            fill="var(--fill-0, white)"
+            id="Vector_14"
+            opacity="0.11"
+          />
+          <path
+            d="M123.022 477.759C123.26 477.605 123.327 477.288 123.173 477.05C123.019 476.813 122.702 476.746 122.465 476.9C122.228 477.054 122.16 477.371 122.314 477.608C122.468 477.845 122.785 477.913 123.022 477.759Z"
+            fill="var(--fill-0, white)"
+            id="Vector_15"
+            opacity="0.11"
+          />
+          <path
+            d="M193.823 475.794C194.061 475.64 194.128 475.323 193.974 475.086C193.82 474.848 193.503 474.781 193.266 474.935C193.028 475.089 192.961 475.406 193.115 475.643C193.269 475.881 193.586 475.948 193.823 475.794Z"
+            fill="var(--fill-0, white)"
+            id="Vector_16"
+            opacity="0.11"
+          />
+          <path
+            d="M273.542 417.948C273.779 417.794 273.847 417.477 273.693 417.24C273.539 417.003 273.222 416.935 272.984 417.089C272.747 417.243 272.68 417.56 272.834 417.798C272.988 418.035 273.305 418.102 273.542 417.948Z"
+            fill="var(--fill-0, white)"
+            id="Vector_17"
+            opacity="0.11"
+          />
+          <path
+            d="M47.3545 518.318C47.5918 518.164 47.6593 517.846 47.5053 517.609C47.3514 517.372 47.0342 517.304 46.7969 517.458C46.5596 517.612 46.4921 517.929 46.6461 518.167C46.8001 518.404 47.1172 518.472 47.3545 518.318Z"
+            fill="var(--fill-0, white)"
+            id="Vector_18"
+            opacity="0.3"
+          />
+          <path
+            d="M131.136 430.966C131.373 430.812 131.441 430.495 131.287 430.257C131.133 430.02 130.815 429.953 130.578 430.107C130.341 430.261 130.273 430.578 130.427 430.815C130.581 431.052 130.899 431.12 131.136 430.966Z"
+            fill="var(--fill-0, white)"
+            id="Vector_19"
+          />
+          <path
+            d="M196.761 387.157C196.998 387.003 197.066 386.686 196.912 386.449C196.758 386.212 196.44 386.144 196.203 386.298C195.966 386.452 195.898 386.769 196.052 387.007C196.206 387.244 196.524 387.311 196.761 387.157Z"
+            fill="var(--fill-0, white)"
+            id="Vector_20"
+          />
+          <path
+            d="M127.569 489.468C127.807 489.314 127.874 488.997 127.72 488.759C127.566 488.522 127.249 488.455 127.012 488.609C126.774 488.763 126.707 489.08 126.861 489.317C127.015 489.554 127.332 489.622 127.569 489.468Z"
+            fill="var(--fill-0, white)"
+            id="Vector_21"
+          />
+          <path
+            d="M97.4873 508.993C97.7246 508.839 97.7921 508.522 97.6381 508.285C97.4842 508.048 97.167 507.98 96.9297 508.134C96.6924 508.288 96.6249 508.605 96.7789 508.842C96.9329 509.08 97.25 509.147 97.4873 508.993Z"
+            fill="var(--fill-0, white)"
+            id="Vector_22"
+            opacity="0.3"
+          />
+          <path
+            d="M44.96 505.214C45.1973 505.06 45.2648 504.743 45.1108 504.506C44.9568 504.268 44.6396 504.201 44.4024 504.355C44.1651 504.509 44.0976 504.826 44.2516 505.063C44.4056 505.3 44.7227 505.368 44.96 505.214Z"
+            fill="var(--fill-0, white)"
+            id="Vector_23"
+            opacity="0.11"
+          />
+          <path
+            d="M145.569 436.259C145.807 436.105 145.874 435.788 145.72 435.55C145.566 435.313 145.249 435.246 145.012 435.4C144.774 435.554 144.707 435.871 144.861 436.108C145.015 436.345 145.332 436.413 145.569 436.259Z"
+            fill="var(--fill-0, white)"
+            id="Vector_24"
+            opacity="0.3"
+          />
+          <path
+            d="M140.179 492.892C140.416 492.738 140.484 492.421 140.33 492.183C140.176 491.946 139.858 491.878 139.621 492.032C139.384 492.186 139.316 492.504 139.47 492.741C139.624 492.978 139.941 493.046 140.179 492.892Z"
+            fill="var(--fill-0, white)"
+            id="Vector_25"
+            opacity="0.3"
+          />
+          <path
+            d="M90.9639 530.935C91.2011 530.781 91.2687 530.464 91.1147 530.226C90.9607 529.989 90.6435 529.922 90.4063 530.076C90.169 530.229 90.1015 530.547 90.2555 530.784C90.4094 531.021 90.7266 531.089 90.9639 530.935Z"
+            fill="var(--fill-0, white)"
+            id="Vector_26"
+            opacity="0.3"
+          />
+          <path
+            d="M59.8194 510.23C60.0566 510.076 60.1242 509.758 59.9702 509.521C59.8162 509.284 59.499 509.216 59.2617 509.37C59.0245 509.524 58.957 509.842 59.1109 510.079C59.2649 510.316 59.5821 510.384 59.8194 510.23Z"
+            fill="var(--fill-0, white)"
+            id="Vector_27"
+            opacity="0.3"
+          />
+          <path
+            d="M326.288 335.472C326.525 335.318 326.593 335.001 326.439 334.763C326.285 334.526 325.968 334.459 325.731 334.613C325.493 334.767 325.426 335.084 325.58 335.321C325.734 335.558 326.051 335.626 326.288 335.472Z"
+            fill="var(--fill-0, white)"
+            id="Vector_28"
+            opacity="0.3"
+          />
+          <path
+            d="M245.659 362.751C245.896 362.597 245.964 362.28 245.81 362.043C245.656 361.805 245.339 361.738 245.102 361.892C244.864 362.046 244.797 362.363 244.951 362.6C245.105 362.838 245.422 362.905 245.659 362.751Z"
+            fill="var(--fill-0, white)"
+            id="Vector_29"
+            opacity="0.11"
+          />
+          <path
+            d="M326.675 361.478C326.912 361.324 326.98 361.006 326.826 360.769C326.672 360.532 326.355 360.464 326.117 360.618C325.88 360.772 325.812 361.09 325.966 361.327C326.12 361.564 326.438 361.632 326.675 361.478Z"
+            fill="var(--fill-0, white)"
+            id="Vector_30"
+            opacity="0.11"
+          />
+          <path
+            d="M220.453 435.909C220.928 435.6 221.063 434.966 220.755 434.491C220.447 434.016 219.812 433.88 219.337 434.189C218.862 434.497 218.727 435.132 219.035 435.607C219.343 436.082 219.978 436.217 220.453 435.909Z"
+            fill="var(--fill-0, white)"
+            id="Vector_31"
+            opacity="0.3"
+          />
+          <path
+            d="M237.449 406.561C237.924 406.253 238.059 405.618 237.751 405.143C237.443 404.668 236.808 404.533 236.333 404.841C235.858 405.149 235.723 405.784 236.031 406.259C236.339 406.734 236.974 406.869 237.449 406.561Z"
+            fill="var(--fill-0, white)"
+            id="Vector_32"
+            opacity="0.11"
+          />
+          <path
+            d="M227.474 391.659C227.83 391.428 227.931 390.952 227.7 390.596C227.469 390.24 226.993 390.138 226.637 390.369C226.281 390.601 226.18 391.077 226.411 391.433C226.642 391.789 227.118 391.89 227.474 391.659Z"
+            fill="var(--fill-0, white)"
+            id="Vector_33"
+          />
+          <path
+            d="M227.107 456.026C227.463 455.795 227.564 455.319 227.333 454.963C227.102 454.607 226.626 454.505 226.27 454.737C225.914 454.968 225.812 455.444 226.044 455.8C226.275 456.156 226.751 456.257 227.107 456.026Z"
+            fill="var(--fill-0, white)"
+            id="Vector_34"
+          />
+          <path
+            d="M375.361 372.03C375.717 371.799 375.818 371.323 375.587 370.967C375.356 370.611 374.88 370.509 374.524 370.74C374.168 370.972 374.066 371.448 374.298 371.804C374.529 372.16 375.005 372.261 375.361 372.03Z"
+            fill="var(--fill-0, white)"
+            id="Vector_35"
+          />
+          <path
+            d="M91.7044 545.723C92.0605 545.492 92.1619 545.016 91.9308 544.66C91.6997 544.304 91.2237 544.203 90.8675 544.434C90.5114 544.665 90.4101 545.141 90.6412 545.497C90.8723 545.853 91.3483 545.955 91.7044 545.723Z"
+            fill="var(--fill-0, white)"
+            id="Vector_36"
+          />
+          <path
+            d="M28.1381 572.933C28.4942 572.701 28.5955 572.225 28.3644 571.869C28.1333 571.513 27.6573 571.412 27.3011 571.643C26.945 571.874 26.8437 572.35 27.0748 572.706C27.3059 573.062 27.7819 573.164 28.1381 572.933Z"
+            fill="var(--fill-0, white)"
+            id="Vector_37"
+          />
+          <path
+            d="M9.67712 560.483C10.0332 560.252 10.1346 559.776 9.90348 559.42C9.67238 559.064 9.19632 558.963 8.84021 559.194C8.48409 559.425 8.38277 559.901 8.61388 560.257C8.84498 560.613 9.32101 560.714 9.67712 560.483Z"
+            fill="var(--fill-0, white)"
+            id="Vector_38"
+          />
+          <path
+            d="M212.427 413.641C212.783 413.41 212.885 412.934 212.653 412.578C212.422 412.222 211.946 412.121 211.59 412.352C211.234 412.583 211.133 413.059 211.364 413.415C211.595 413.771 212.071 413.873 212.427 413.641Z"
+            fill="var(--fill-0, white)"
+            id="Vector_39"
+          />
+          <path
+            d="M158.283 493.97C158.639 493.738 158.74 493.262 158.509 492.906C158.278 492.55 157.802 492.449 157.446 492.68C157.09 492.911 156.988 493.387 157.219 493.743C157.45 494.099 157.926 494.201 158.283 493.97Z"
+            fill="var(--fill-0, white)"
+            id="Vector_40"
+          />
+          <path
+            d="M278.576 442.169C278.932 441.938 279.033 441.462 278.802 441.105C278.571 440.749 278.095 440.648 277.739 440.879C277.383 441.11 277.281 441.586 277.512 441.942C277.743 442.299 278.219 442.4 278.576 442.169Z"
+            fill="var(--fill-0, white)"
+            id="Vector_41"
+          />
+          <path
+            d="M373.494 339.038C373.85 338.807 373.951 338.331 373.72 337.975C373.489 337.619 373.013 337.517 372.657 337.748C372.301 337.979 372.199 338.455 372.43 338.812C372.661 339.168 373.137 339.269 373.494 339.038Z"
+            fill="var(--fill-0, white)"
+            id="Vector_42"
+          />
+          <path
+            d="M368.466 308.708C368.822 308.477 368.924 308.001 368.693 307.645C368.461 307.288 367.985 307.187 367.629 307.418C367.273 307.649 367.172 308.125 367.403 308.481C367.634 308.838 368.11 308.939 368.466 308.708Z"
+            fill="var(--fill-0, white)"
+            id="Vector_43"
+          />
+          <path
+            d="M263.207 369.079C263.682 368.77 263.817 368.135 263.509 367.661C263.2 367.186 262.566 367.05 262.091 367.359C261.616 367.667 261.48 368.302 261.789 368.777C262.097 369.252 262.732 369.387 263.207 369.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_44"
+            opacity="0.3"
+          />
+          <path
+            d="M243.406 338.569C243.881 338.261 244.016 337.626 243.708 337.151C243.4 336.676 242.765 336.541 242.29 336.849C241.815 337.157 241.68 337.792 241.988 338.267C242.296 338.742 242.931 338.877 243.406 338.569Z"
+            fill="var(--fill-0, white)"
+            id="Vector_45"
+          />
+          <path
+            d="M291.478 364.171C291.834 363.94 291.935 363.464 291.704 363.107C291.473 362.751 290.997 362.65 290.641 362.881C290.285 363.112 290.184 363.588 290.415 363.944C290.646 364.3 291.122 364.402 291.478 364.171Z"
+            fill="var(--fill-0, white)"
+            id="Vector_46"
+          />
+          <path
+            d="M301.445 333.885C301.92 333.577 302.055 332.942 301.747 332.467C301.439 331.992 300.804 331.857 300.329 332.165C299.854 332.474 299.719 333.108 300.027 333.583C300.335 334.058 300.97 334.193 301.445 333.885Z"
+            fill="var(--fill-0, white)"
+            id="Vector_47"
+            opacity="0.3"
+          />
+          <path
+            d="M363.793 336.788C364.268 336.479 364.403 335.844 364.095 335.37C363.786 334.895 363.152 334.759 362.677 335.068C362.202 335.376 362.066 336.011 362.375 336.486C362.683 336.961 363.318 337.096 363.793 336.788Z"
+            fill="var(--fill-0, white)"
+            id="Vector_48"
+            opacity="0.3"
+          />
+          <path
+            d="M314.062 370.276C314.537 369.968 314.672 369.333 314.364 368.858C314.056 368.383 313.421 368.248 312.946 368.556C312.471 368.864 312.336 369.499 312.644 369.974C312.952 370.449 313.587 370.584 314.062 370.276Z"
+            fill="var(--fill-0, white)"
+            id="Vector_49"
+            opacity="0.3"
+          />
+          <path
+            d="M72.1247 537.665C72.5996 537.356 72.7348 536.721 72.4266 536.247C72.1183 535.772 71.4835 535.636 71.0085 535.945C70.5336 536.253 70.3984 536.888 70.7066 537.363C71.0148 537.838 71.6497 537.973 72.1247 537.665Z"
+            fill="var(--fill-0, white)"
+            id="Vector_50"
+            opacity="0.3"
+          />
+          <path
+            d="M21.9723 536.622C22.4473 536.313 22.5825 535.679 22.2742 535.204C21.966 534.729 21.3311 534.593 20.8562 534.902C20.3812 535.21 20.246 535.845 20.5543 536.32C20.8625 536.795 21.4974 536.93 21.9723 536.622Z"
+            fill="var(--fill-0, white)"
+            id="Vector_51"
+            opacity="0.3"
+          />
+          <path
+            d="M337.801 335.329C338.276 335.02 338.411 334.386 338.102 333.911C337.794 333.436 337.159 333.3 336.684 333.609C336.209 333.917 336.074 334.552 336.382 335.027C336.691 335.502 337.326 335.637 337.801 335.329Z"
+            fill="var(--fill-0, white)"
+            id="Vector_52"
+            opacity="0.11"
+          />
+          <path
+            d="M73.9489 482.127C74.4239 481.819 74.559 481.184 74.2508 480.709C73.9426 480.234 73.3077 480.099 72.8327 480.407C72.3578 480.716 72.2226 481.351 72.5308 481.826C72.8391 482.3 73.474 482.436 73.9489 482.127Z"
+            fill="var(--fill-0, white)"
+            id="Vector_53"
+            opacity="0.3"
+          />
+          <path
+            d="M56.7653 481.063C57.2403 480.755 57.3754 480.12 57.0672 479.645C56.759 479.17 56.1241 479.035 55.6491 479.343C55.1742 479.651 55.039 480.286 55.3472 480.761C55.6555 481.236 56.2904 481.371 56.7653 481.063Z"
+            fill="var(--fill-0, white)"
+            id="Vector_54"
+            opacity="0.11"
+          />
+          <path
+            d="M71.1794 510.797C71.6543 510.489 71.7895 509.854 71.4813 509.379C71.173 508.904 70.5382 508.769 70.0632 509.077C69.5882 509.386 69.4531 510.02 69.7613 510.495C70.0695 510.97 70.7044 511.106 71.1794 510.797Z"
+            fill="var(--fill-0, white)"
+            id="Vector_55"
+            opacity="0.3"
+          />
+          <path
+            d="M97.7552 492.938C98.1114 492.707 98.2127 492.231 97.9816 491.875C97.7505 491.519 97.2744 491.418 96.9183 491.649C96.5622 491.88 96.4609 492.356 96.692 492.712C96.9231 493.068 97.3991 493.169 97.7552 492.938Z"
+            fill="var(--fill-0, white)"
+            id="Vector_56"
+          />
+          <path
+            d="M238.5 214.479C238.975 214.171 239.11 213.536 238.802 213.061C238.493 212.586 237.858 212.451 237.384 212.759C236.909 213.067 236.773 213.702 237.082 214.177C237.39 214.652 238.025 214.787 238.5 214.479Z"
+            fill="var(--fill-0, white)"
+            id="Vector_57"
+            opacity="0.11"
+          />
+          <path
+            d="M244.361 217.395C244.717 217.164 244.818 216.688 244.587 216.332C244.356 215.976 243.88 215.875 243.524 216.106C243.168 216.337 243.066 216.813 243.297 217.169C243.529 217.525 244.005 217.626 244.361 217.395Z"
+            fill="var(--fill-0, white)"
+            id="Vector_58"
+          />
+          <path
+            d="M252.689 199.169C253.045 198.938 253.146 198.462 252.915 198.105C252.684 197.749 252.208 197.648 251.852 197.879C251.496 198.11 251.395 198.586 251.626 198.942C251.857 199.299 252.333 199.4 252.689 199.169Z"
+            fill="var(--fill-0, white)"
+            id="Vector_59"
+          />
+          <path
+            d="M215.603 222.013C215.959 221.781 216.06 221.305 215.829 220.949C215.598 220.593 215.122 220.492 214.766 220.723C214.41 220.954 214.309 221.43 214.54 221.786C214.771 222.142 215.247 222.244 215.603 222.013Z"
+            fill="var(--fill-0, white)"
+            id="Vector_60"
+          />
+          <path
+            d="M201.019 246.133C201.494 245.825 201.629 245.19 201.321 244.715C201.013 244.24 200.378 244.105 199.903 244.413C199.428 244.722 199.293 245.356 199.601 245.831C199.909 246.306 200.544 246.442 201.019 246.133Z"
+            fill="var(--fill-0, white)"
+            id="Vector_61"
+            opacity="0.11"
+          />
+          <path
+            d="M186.722 241.976C186.959 241.822 187.027 241.505 186.873 241.267C186.719 241.03 186.401 240.962 186.164 241.116C185.927 241.27 185.859 241.588 186.013 241.825C186.167 242.062 186.484 242.13 186.722 241.976Z"
+            fill="var(--fill-0, white)"
+            id="Vector_62"
+          />
+          <path
+            d="M248.085 232.079C248.322 231.925 248.39 231.608 248.236 231.371C248.082 231.133 247.765 231.066 247.527 231.22C247.29 231.374 247.223 231.691 247.377 231.928C247.531 232.166 247.848 232.233 248.085 232.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_63"
+          />
+          <path
+            d="M341.776 171.28C342.014 171.126 342.081 170.809 341.927 170.572C341.773 170.335 341.456 170.267 341.219 170.421C340.982 170.575 340.914 170.892 341.068 171.13C341.222 171.367 341.539 171.434 341.776 171.28Z"
+            fill="var(--fill-0, white)"
+            id="Vector_64"
+          />
+          <path
+            d="M373.558 117.673C373.795 117.519 373.863 117.202 373.709 116.965C373.555 116.727 373.237 116.66 373 116.814C372.763 116.968 372.695 117.285 372.849 117.522C373.003 117.759 373.32 117.827 373.558 117.673Z"
+            fill="var(--fill-0, white)"
+            id="Vector_65"
+          />
+          <path
+            d="M410.683 138.169C410.92 138.015 410.988 137.698 410.834 137.461C410.68 137.223 410.362 137.156 410.125 137.31C409.888 137.464 409.82 137.781 409.974 138.018C410.128 138.256 410.445 138.323 410.683 138.169Z"
+            fill="var(--fill-0, white)"
+            id="Vector_66"
+          />
+          <path
+            d="M98.003 314.206C98.2402 314.052 98.3078 313.735 98.1538 313.498C97.9998 313.26 97.6826 313.193 97.4453 313.347C97.2081 313.501 97.1406 313.818 97.2945 314.055C97.4485 314.293 97.7657 314.36 98.003 314.206Z"
+            fill="var(--fill-0, white)"
+            id="Vector_67"
+          />
+          <path
+            d="M76.503 295.181C76.7402 295.027 76.8078 294.71 76.6538 294.472C76.4998 294.235 76.1826 294.168 75.9454 294.322C75.7081 294.475 75.6406 294.793 75.7945 295.03C75.9485 295.267 76.2657 295.335 76.503 295.181Z"
+            fill="var(--fill-0, white)"
+            id="Vector_68"
+            opacity="0.11"
+          />
+          <path
+            d="M64.4405 317.058C64.6777 316.904 64.7453 316.587 64.5913 316.349C64.4373 316.112 64.1201 316.044 63.8829 316.198C63.6456 316.352 63.5781 316.67 63.732 316.907C63.886 317.144 64.2032 317.212 64.4405 317.058Z"
+            fill="var(--fill-0, white)"
+            id="Vector_69"
+            opacity="0.11"
+          />
+          <path
+            d="M95.3545 333.64C95.5918 333.486 95.6593 333.169 95.5053 332.931C95.3514 332.694 95.0342 332.627 94.7969 332.78C94.5596 332.934 94.4921 333.252 94.6461 333.489C94.8001 333.726 95.1172 333.794 95.3545 333.64Z"
+            fill="var(--fill-0, white)"
+            id="Vector_70"
+            opacity="0.11"
+          />
+          <path
+            d="M186.476 250.073C186.713 249.919 186.78 249.602 186.626 249.365C186.472 249.128 186.155 249.06 185.918 249.214C185.681 249.368 185.613 249.685 185.767 249.923C185.921 250.16 186.238 250.227 186.476 250.073Z"
+            fill="var(--fill-0, white)"
+            id="Vector_71"
+            opacity="0.11"
+          />
+          <path
+            d="M257.273 248.107C257.51 247.953 257.577 247.635 257.423 247.398C257.269 247.161 256.952 247.093 256.715 247.247C256.478 247.401 256.41 247.718 256.564 247.956C256.718 248.193 257.035 248.261 257.273 248.107Z"
+            fill="var(--fill-0, white)"
+            id="Vector_72"
+            opacity="0.11"
+          />
+          <path
+            d="M336.995 190.261C337.232 190.107 337.3 189.79 337.146 189.552C336.992 189.315 336.675 189.248 336.438 189.402C336.2 189.556 336.133 189.873 336.287 190.11C336.441 190.347 336.758 190.415 336.995 190.261Z"
+            fill="var(--fill-0, white)"
+            id="Vector_73"
+            opacity="0.11"
+          />
+          <path
+            d="M110.804 290.632C111.041 290.478 111.109 290.161 110.955 289.923C110.801 289.686 110.483 289.619 110.246 289.773C110.009 289.927 109.941 290.244 110.095 290.481C110.249 290.718 110.566 290.786 110.804 290.632Z"
+            fill="var(--fill-0, white)"
+            id="Vector_74"
+            opacity="0.3"
+          />
+          <path
+            d="M194.585 203.278C194.822 203.124 194.89 202.807 194.736 202.57C194.582 202.333 194.265 202.265 194.027 202.419C193.79 202.573 193.723 202.89 193.877 203.128C194.031 203.365 194.348 203.432 194.585 203.278Z"
+            fill="var(--fill-0, white)"
+            id="Vector_75"
+          />
+          <path
+            d="M260.21 159.472C260.447 159.318 260.515 159.001 260.361 158.763C260.207 158.526 259.89 158.459 259.652 158.613C259.415 158.767 259.348 159.084 259.502 159.321C259.656 159.558 259.973 159.626 260.21 159.472Z"
+            fill="var(--fill-0, white)"
+            id="Vector_76"
+          />
+          <path
+            d="M191.023 261.782C191.26 261.628 191.327 261.311 191.173 261.074C191.019 260.837 190.702 260.769 190.465 260.923C190.228 261.077 190.16 261.394 190.314 261.632C190.468 261.869 190.785 261.936 191.023 261.782Z"
+            fill="var(--fill-0, white)"
+            id="Vector_77"
+          />
+          <path
+            d="M160.94 281.306C161.178 281.152 161.245 280.835 161.091 280.597C160.937 280.36 160.62 280.293 160.383 280.447C160.146 280.6 160.078 280.918 160.232 281.155C160.386 281.392 160.703 281.46 160.94 281.306Z"
+            fill="var(--fill-0, white)"
+            id="Vector_78"
+            opacity="0.3"
+          />
+          <path
+            d="M108.413 277.528C108.65 277.374 108.718 277.057 108.564 276.82C108.41 276.583 108.093 276.515 107.856 276.669C107.618 276.823 107.551 277.14 107.705 277.378C107.859 277.615 108.176 277.682 108.413 277.528Z"
+            fill="var(--fill-0, white)"
+            id="Vector_79"
+            opacity="0.11"
+          />
+          <path
+            d="M209.023 208.571C209.26 208.417 209.327 208.1 209.173 207.863C209.019 207.626 208.702 207.558 208.465 207.712C208.228 207.866 208.16 208.183 208.314 208.421C208.468 208.658 208.785 208.725 209.023 208.571Z"
+            fill="var(--fill-0, white)"
+            id="Vector_80"
+            opacity="0.3"
+          />
+          <path
+            d="M203.628 265.206C203.865 265.052 203.933 264.735 203.779 264.498C203.625 264.26 203.308 264.193 203.07 264.347C202.833 264.501 202.766 264.818 202.92 265.055C203.074 265.293 203.391 265.36 203.628 265.206Z"
+            fill="var(--fill-0, white)"
+            id="Vector_81"
+            opacity="0.3"
+          />
+          <path
+            d="M154.417 303.249C154.654 303.095 154.722 302.778 154.568 302.541C154.414 302.303 154.097 302.236 153.859 302.39C153.622 302.544 153.555 302.861 153.709 303.098C153.863 303.336 154.18 303.403 154.417 303.249Z"
+            fill="var(--fill-0, white)"
+            id="Vector_82"
+            opacity="0.3"
+          />
+          <path
+            d="M123.269 282.546C123.506 282.392 123.573 282.075 123.419 281.838C123.265 281.6 122.948 281.533 122.711 281.687C122.474 281.841 122.406 282.158 122.56 282.395C122.714 282.632 123.031 282.7 123.269 282.546Z"
+            fill="var(--fill-0, white)"
+            id="Vector_83"
+            opacity="0.3"
+          />
+          <path
+            d="M389.737 107.784C389.975 107.63 390.042 107.313 389.888 107.076C389.734 106.839 389.417 106.771 389.18 106.925C388.943 107.079 388.875 107.396 389.029 107.633C389.183 107.871 389.5 107.938 389.737 107.784Z"
+            fill="var(--fill-0, white)"
+            id="Vector_84"
+            opacity="0.3"
+          />
+          <path
+            d="M309.112 135.066C309.35 134.912 309.417 134.594 309.263 134.357C309.109 134.12 308.792 134.052 308.555 134.206C308.318 134.36 308.25 134.677 308.404 134.915C308.558 135.152 308.875 135.22 309.112 135.066Z"
+            fill="var(--fill-0, white)"
+            id="Vector_85"
+            opacity="0.11"
+          />
+          <path
+            d="M390.128 133.794C390.365 133.64 390.433 133.323 390.279 133.086C390.125 132.848 389.808 132.781 389.57 132.935C389.333 133.089 389.266 133.406 389.42 133.643C389.574 133.881 389.891 133.948 390.128 133.794Z"
+            fill="var(--fill-0, white)"
+            id="Vector_86"
+            opacity="0.11"
+          />
+          <path
+            d="M283.91 208.223C284.385 207.915 284.52 207.28 284.212 206.805C283.904 206.33 283.269 206.195 282.794 206.503C282.319 206.811 282.184 207.446 282.492 207.921C282.8 208.396 283.435 208.531 283.91 208.223Z"
+            fill="var(--fill-0, white)"
+            id="Vector_87"
+            opacity="0.3"
+          />
+          <path
+            d="M300.894 178.875C301.369 178.567 301.504 177.932 301.196 177.457C300.888 176.982 300.253 176.847 299.778 177.156C299.303 177.464 299.168 178.099 299.476 178.574C299.784 179.049 300.419 179.184 300.894 178.875Z"
+            fill="var(--fill-0, white)"
+            id="Vector_88"
+            opacity="0.11"
+          />
+          <path
+            d="M290.923 163.971C291.279 163.74 291.381 163.264 291.15 162.908C290.919 162.552 290.443 162.451 290.086 162.682C289.73 162.913 289.629 163.389 289.86 163.745C290.091 164.101 290.567 164.203 290.923 163.971Z"
+            fill="var(--fill-0, white)"
+            id="Vector_89"
+          />
+          <path
+            d="M290.556 228.341C290.912 228.11 291.014 227.633 290.782 227.277C290.551 226.921 290.075 226.82 289.719 227.051C289.363 227.282 289.262 227.758 289.493 228.114C289.724 228.47 290.2 228.572 290.556 228.341Z"
+            fill="var(--fill-0, white)"
+            id="Vector_90"
+          />
+          <path
+            d="M438.814 144.343C439.17 144.111 439.271 143.635 439.04 143.279C438.809 142.923 438.333 142.822 437.977 143.053C437.621 143.284 437.52 143.76 437.751 144.116C437.982 144.472 438.458 144.574 438.814 144.343Z"
+            fill="var(--fill-0, white)"
+            id="Vector_91"
+          />
+          <path
+            d="M155.158 318.038C155.514 317.807 155.615 317.331 155.384 316.975C155.153 316.619 154.677 316.517 154.321 316.748C153.965 316.979 153.863 317.455 154.094 317.812C154.325 318.168 154.801 318.269 155.158 318.038Z"
+            fill="var(--fill-0, white)"
+            id="Vector_92"
+          />
+          <path
+            d="M91.5873 345.245C91.9434 345.014 92.0447 344.538 91.8136 344.182C91.5825 343.826 91.1065 343.724 90.7504 343.955C90.3943 344.186 90.2929 344.662 90.524 345.019C90.7551 345.375 91.2312 345.476 91.5873 345.245Z"
+            fill="var(--fill-0, white)"
+            id="Vector_93"
+          />
+          <path
+            d="M73.1264 332.798C73.4825 332.567 73.5838 332.091 73.3527 331.734C73.1216 331.378 72.6456 331.277 72.2894 331.508C71.9333 331.739 71.832 332.215 72.0631 332.571C72.2942 332.927 72.7702 333.029 73.1264 332.798Z"
+            fill="var(--fill-0, white)"
+            id="Vector_94"
+          />
+          <path
+            d="M275.876 185.954C276.233 185.723 276.334 185.247 276.103 184.891C275.872 184.535 275.396 184.433 275.039 184.664C274.683 184.895 274.582 185.371 274.813 185.728C275.044 186.084 275.52 186.185 275.876 185.954Z"
+            fill="var(--fill-0, white)"
+            id="Vector_95"
+          />
+          <path
+            d="M221.736 266.282C222.092 266.051 222.193 265.575 221.962 265.219C221.731 264.863 221.255 264.761 220.899 264.992C220.543 265.224 220.441 265.7 220.672 266.056C220.904 266.412 221.38 266.513 221.736 266.282Z"
+            fill="var(--fill-0, white)"
+            id="Vector_96"
+          />
+          <path
+            d="M342.029 214.481C342.385 214.25 342.486 213.774 342.255 213.418C342.024 213.062 341.548 212.961 341.192 213.192C340.836 213.423 340.734 213.899 340.965 214.255C341.197 214.611 341.673 214.712 342.029 214.481Z"
+            fill="var(--fill-0, white)"
+            id="Vector_97"
+          />
+          <path
+            d="M436.947 111.352C437.303 111.121 437.404 110.645 437.173 110.289C436.942 109.933 436.466 109.832 436.11 110.063C435.754 110.294 435.652 110.77 435.883 111.126C436.115 111.482 436.591 111.583 436.947 111.352Z"
+            fill="var(--fill-0, white)"
+            id="Vector_98"
+          />
+          <path
+            d="M431.919 81.0242C432.275 80.7931 432.377 80.3171 432.146 79.961C431.915 79.6049 431.439 79.5035 431.082 79.7346C430.726 79.9657 430.625 80.4418 430.856 80.7979C431.087 81.154 431.563 81.2554 431.919 81.0242Z"
+            fill="var(--fill-0, white)"
+            id="Vector_99"
+          />
+          <path
+            d="M326.66 141.393C327.135 141.085 327.27 140.45 326.962 139.975C326.654 139.5 326.019 139.365 325.544 139.673C325.069 139.981 324.934 140.616 325.242 141.091C325.55 141.566 326.185 141.701 326.66 141.393Z"
+            fill="var(--fill-0, white)"
+            id="Vector_100"
+            opacity="0.3"
+          />
+          <path
+            d="M306.855 110.881C307.33 110.573 307.465 109.938 307.157 109.463C306.849 108.988 306.214 108.853 305.739 109.161C305.264 109.47 305.129 110.105 305.437 110.579C305.745 111.054 306.38 111.19 306.855 110.881Z"
+            fill="var(--fill-0, white)"
+            id="Vector_101"
+          />
+          <path
+            d="M354.927 136.485C355.283 136.254 355.385 135.778 355.154 135.422C354.922 135.066 354.446 134.964 354.09 135.196C353.734 135.427 353.633 135.903 353.864 136.259C354.095 136.615 354.571 136.716 354.927 136.485Z"
+            fill="var(--fill-0, white)"
+            id="Vector_102"
+          />
+          <path
+            d="M364.894 106.198C365.369 105.89 365.504 105.255 365.196 104.78C364.888 104.305 364.253 104.17 363.778 104.478C363.303 104.786 363.168 105.421 363.476 105.896C363.784 106.371 364.419 106.506 364.894 106.198Z"
+            fill="var(--fill-0, white)"
+            id="Vector_103"
+            opacity="0.3"
+          />
+          <path
+            d="M427.238 109.1C427.713 108.792 427.848 108.157 427.54 107.682C427.232 107.207 426.597 107.072 426.122 107.38C425.647 107.688 425.512 108.323 425.82 108.798C426.128 109.273 426.763 109.408 427.238 109.1Z"
+            fill="var(--fill-0, white)"
+            id="Vector_104"
+            opacity="0.3"
+          />
+          <path
+            d="M377.515 142.59C377.99 142.282 378.126 141.647 377.817 141.172C377.509 140.697 376.874 140.562 376.399 140.87C375.924 141.179 375.789 141.813 376.097 142.288C376.406 142.763 377.04 142.899 377.515 142.59Z"
+            fill="var(--fill-0, white)"
+            id="Vector_105"
+            opacity="0.3"
+          />
+          <path
+            d="M135.578 309.979C136.053 309.671 136.188 309.036 135.88 308.561C135.571 308.086 134.937 307.951 134.462 308.259C133.987 308.567 133.852 309.202 134.16 309.677C134.468 310.152 135.103 310.287 135.578 309.979Z"
+            fill="var(--fill-0, white)"
+            id="Vector_106"
+            opacity="0.3"
+          />
+          <path
+            d="M85.4216 308.934C85.8965 308.626 86.0317 307.991 85.7235 307.516C85.4152 307.041 84.7803 306.906 84.3054 307.214C83.8304 307.522 83.6953 308.157 84.0035 308.632C84.3117 309.107 84.9466 309.242 85.4216 308.934Z"
+            fill="var(--fill-0, white)"
+            id="Vector_107"
+            opacity="0.3"
+          />
+          <path
+            d="M401.254 107.641C401.729 107.333 401.864 106.698 401.556 106.223C401.247 105.748 400.612 105.613 400.138 105.921C399.663 106.229 399.527 106.864 399.836 107.339C400.144 107.814 400.779 107.949 401.254 107.641Z"
+            fill="var(--fill-0, white)"
+            id="Vector_108"
+            opacity="0.11"
+          />
+          <path
+            d="M137.394 254.442C137.869 254.134 138.004 253.499 137.696 253.024C137.388 252.549 136.753 252.414 136.278 252.722C135.803 253.03 135.668 253.665 135.976 254.14C136.284 254.615 136.919 254.75 137.394 254.442Z"
+            fill="var(--fill-0, white)"
+            id="Vector_109"
+            opacity="0.3"
+          />
+          <path
+            d="M120.215 253.375C120.69 253.067 120.825 252.432 120.516 251.957C120.208 251.482 119.573 251.347 119.098 251.656C118.623 251.964 118.488 252.599 118.796 253.074C119.105 253.549 119.74 253.684 120.215 253.375Z"
+            fill="var(--fill-0, white)"
+            id="Vector_110"
+            opacity="0.11"
+          />
+          <path
+            d="M134.633 283.112C135.107 282.804 135.243 282.169 134.934 281.694C134.626 281.219 133.991 281.084 133.516 281.392C133.041 281.7 132.906 282.335 133.214 282.81C133.523 283.285 134.158 283.42 134.633 283.112Z"
+            fill="var(--fill-0, white)"
+            id="Vector_111"
+            opacity="0.3"
+          />
+          <path
+            d="M161.208 265.251C161.564 265.02 161.666 264.544 161.435 264.187C161.204 263.831 160.728 263.73 160.371 263.961C160.015 264.192 159.914 264.668 160.145 265.024C160.376 265.381 160.852 265.482 161.208 265.251Z"
+            fill="var(--fill-0, white)"
+            id="Vector_112"
+          />
+          <path
+            d="M508.183 135.165C508.658 134.856 508.793 134.221 508.485 133.747C508.177 133.272 507.542 133.136 507.067 133.445C506.592 133.753 506.457 134.388 506.765 134.863C507.074 135.338 507.708 135.473 508.183 135.165Z"
+            fill="var(--fill-0, white)"
+            id="Vector_113"
+            opacity="0.11"
+          />
+          <path
+            d="M514.04 138.079C514.397 137.848 514.498 137.372 514.267 137.016C514.036 136.66 513.56 136.558 513.204 136.789C512.847 137.02 512.746 137.496 512.977 137.853C513.208 138.209 513.684 138.31 514.04 138.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_114"
+          />
+          <path
+            d="M522.369 119.852C522.725 119.621 522.826 119.145 522.595 118.789C522.364 118.433 521.888 118.332 521.532 118.563C521.176 118.794 521.074 119.27 521.305 119.626C521.536 119.982 522.012 120.083 522.369 119.852Z"
+            fill="var(--fill-0, white)"
+            id="Vector_115"
+          />
+          <path
+            d="M485.279 142.696C485.635 142.465 485.736 141.989 485.505 141.633C485.274 141.277 484.798 141.175 484.442 141.407C484.086 141.638 483.984 142.114 484.216 142.47C484.447 142.826 484.923 142.927 485.279 142.696Z"
+            fill="var(--fill-0, white)"
+            id="Vector_116"
+          />
+          <path
+            d="M470.699 166.817C471.174 166.509 471.309 165.874 471.001 165.399C470.693 164.924 470.058 164.789 469.583 165.097C469.108 165.405 468.973 166.04 469.281 166.515C469.589 166.99 470.224 167.125 470.699 166.817Z"
+            fill="var(--fill-0, white)"
+            id="Vector_117"
+            opacity="0.11"
+          />
+          <path
+            d="M456.398 162.659C456.635 162.505 456.702 162.188 456.548 161.951C456.394 161.714 456.077 161.646 455.84 161.8C455.603 161.954 455.535 162.271 455.689 162.508C455.843 162.746 456.16 162.813 456.398 162.659Z"
+            fill="var(--fill-0, white)"
+            id="Vector_118"
+          />
+          <path
+            d="M517.765 152.763C518.002 152.609 518.07 152.292 517.916 152.054C517.762 151.817 517.444 151.75 517.207 151.904C516.97 152.058 516.902 152.375 517.056 152.612C517.21 152.849 517.528 152.917 517.765 152.763Z"
+            fill="var(--fill-0, white)"
+            id="Vector_119"
+          />
+          <path
+            d="M611.456 91.964C611.693 91.81 611.761 91.4929 611.607 91.2556C611.453 91.0183 611.136 90.9508 610.899 91.1048C610.661 91.2588 610.594 91.5759 610.748 91.8132C610.902 92.0505 611.219 92.118 611.456 91.964Z"
+            fill="var(--fill-0, white)"
+            id="Vector_120"
+          />
+          <path
+            d="M643.234 38.3566C643.471 38.2026 643.538 37.8854 643.384 37.6481C643.23 37.4109 642.913 37.3434 642.676 37.4974C642.439 37.6513 642.371 37.9685 642.525 38.2058C642.679 38.443 642.996 38.5106 643.234 38.3566Z"
+            fill="var(--fill-0, white)"
+            id="Vector_121"
+          />
+          <path
+            d="M680.359 58.8527C680.596 58.6987 680.663 58.3815 680.509 58.1442C680.355 57.907 680.038 57.8394 679.801 57.9934C679.564 58.1474 679.496 58.4646 679.65 58.7019C679.804 58.9391 680.121 59.0066 680.359 58.8527Z"
+            fill="var(--fill-0, white)"
+            id="Vector_122"
+          />
+          <path
+            d="M367.683 234.89C367.92 234.736 367.987 234.419 367.834 234.181C367.68 233.944 367.362 233.877 367.125 234.031C366.888 234.184 366.82 234.502 366.974 234.739C367.128 234.976 367.445 235.044 367.683 234.89Z"
+            fill="var(--fill-0, white)"
+            id="Vector_123"
+          />
+          <path
+            d="M346.183 215.866C346.42 215.712 346.488 215.395 346.334 215.158C346.18 214.921 345.862 214.853 345.625 215.007C345.388 215.161 345.32 215.478 345.474 215.716C345.628 215.953 345.945 216.02 346.183 215.866Z"
+            fill="var(--fill-0, white)"
+            id="Vector_124"
+            opacity="0.11"
+          />
+          <path
+            d="M334.116 237.741C334.354 237.587 334.421 237.27 334.267 237.033C334.113 236.796 333.796 236.728 333.559 236.882C333.321 237.036 333.254 237.353 333.408 237.591C333.562 237.828 333.879 237.895 334.116 237.741Z"
+            fill="var(--fill-0, white)"
+            id="Vector_125"
+            opacity="0.11"
+          />
+          <path
+            d="M365.03 254.323C365.268 254.169 365.335 253.852 365.181 253.615C365.027 253.378 364.71 253.31 364.473 253.464C364.235 253.618 364.168 253.935 364.322 254.173C364.476 254.41 364.793 254.477 365.03 254.323Z"
+            fill="var(--fill-0, white)"
+            id="Vector_126"
+            opacity="0.11"
+          />
+          <path
+            d="M456.155 170.757C456.393 170.603 456.46 170.286 456.306 170.049C456.152 169.811 455.835 169.744 455.598 169.898C455.361 170.052 455.293 170.369 455.447 170.606C455.601 170.843 455.918 170.911 456.155 170.757Z"
+            fill="var(--fill-0, white)"
+            id="Vector_127"
+            opacity="0.11"
+          />
+          <path
+            d="M526.944 168.792C527.182 168.638 527.249 168.321 527.095 168.084C526.941 167.846 526.624 167.779 526.387 167.933C526.15 168.087 526.082 168.404 526.236 168.641C526.39 168.879 526.707 168.946 526.944 168.792Z"
+            fill="var(--fill-0, white)"
+            id="Vector_128"
+            opacity="0.11"
+          />
+          <path
+            d="M606.671 110.946C606.908 110.792 606.976 110.475 606.822 110.238C606.668 110.001 606.351 109.933 606.113 110.087C605.876 110.241 605.809 110.558 605.963 110.796C606.117 111.033 606.434 111.1 606.671 110.946Z"
+            fill="var(--fill-0, white)"
+            id="Vector_129"
+            opacity="0.11"
+          />
+          <path
+            d="M380.483 211.316C380.721 211.162 380.788 210.844 380.634 210.607C380.48 210.37 380.163 210.302 379.926 210.456C379.689 210.61 379.621 210.927 379.775 211.165C379.929 211.402 380.246 211.47 380.483 211.316Z"
+            fill="var(--fill-0, white)"
+            id="Vector_130"
+            opacity="0.3"
+          />
+          <path
+            d="M464.265 123.964C464.502 123.81 464.57 123.493 464.416 123.256C464.262 123.018 463.944 122.951 463.707 123.105C463.47 123.259 463.402 123.576 463.556 123.813C463.71 124.05 464.028 124.118 464.265 123.964Z"
+            fill="var(--fill-0, white)"
+            id="Vector_131"
+          />
+          <path
+            d="M529.89 80.1554C530.127 80.0014 530.195 79.6843 530.041 79.447C529.887 79.2097 529.569 79.1422 529.332 79.2962C529.095 79.4502 529.027 79.7673 529.181 80.0046C529.335 80.2419 529.652 80.3094 529.89 80.1554Z"
+            fill="var(--fill-0, white)"
+            id="Vector_132"
+          />
+          <path
+            d="M460.698 182.468C460.936 182.314 461.003 181.997 460.849 181.759C460.695 181.522 460.378 181.455 460.141 181.609C459.903 181.763 459.836 182.08 459.99 182.317C460.144 182.554 460.461 182.622 460.698 182.468Z"
+            fill="var(--fill-0, white)"
+            id="Vector_133"
+          />
+          <path
+            d="M430.616 201.991C430.854 201.837 430.921 201.52 430.767 201.283C430.613 201.046 430.296 200.978 430.059 201.132C429.821 201.286 429.754 201.603 429.908 201.841C430.062 202.078 430.379 202.145 430.616 201.991Z"
+            fill="var(--fill-0, white)"
+            id="Vector_134"
+            opacity="0.3"
+          />
+          <path
+            d="M378.089 198.212C378.326 198.058 378.394 197.741 378.24 197.504C378.086 197.266 377.769 197.199 377.531 197.353C377.294 197.507 377.227 197.824 377.381 198.061C377.534 198.298 377.852 198.366 378.089 198.212Z"
+            fill="var(--fill-0, white)"
+            id="Vector_135"
+            opacity="0.11"
+          />
+          <path
+            d="M478.698 129.257C478.936 129.103 479.003 128.786 478.849 128.549C478.695 128.311 478.378 128.244 478.141 128.398C477.903 128.552 477.836 128.869 477.99 129.106C478.144 129.343 478.461 129.411 478.698 129.257Z"
+            fill="var(--fill-0, white)"
+            id="Vector_136"
+            opacity="0.3"
+          />
+          <path
+            d="M473.308 185.892C473.545 185.738 473.613 185.421 473.459 185.183C473.305 184.946 472.987 184.879 472.75 185.032C472.513 185.186 472.445 185.504 472.599 185.741C472.753 185.978 473.07 186.046 473.308 185.892Z"
+            fill="var(--fill-0, white)"
+            id="Vector_137"
+            opacity="0.3"
+          />
+          <path
+            d="M424.093 223.933C424.33 223.779 424.398 223.462 424.244 223.224C424.09 222.987 423.773 222.919 423.535 223.073C423.298 223.227 423.23 223.545 423.384 223.782C423.538 224.019 423.856 224.087 424.093 223.933Z"
+            fill="var(--fill-0, white)"
+            id="Vector_138"
+            opacity="0.3"
+          />
+          <path
+            d="M392.948 203.23C393.186 203.076 393.253 202.758 393.099 202.521C392.945 202.284 392.628 202.216 392.391 202.37C392.153 202.524 392.086 202.842 392.24 203.079C392.394 203.316 392.711 203.384 392.948 203.23Z"
+            fill="var(--fill-0, white)"
+            id="Vector_139"
+            opacity="0.3"
+          />
+          <path
+            d="M659.417 28.4698C659.654 28.3159 659.722 27.9987 659.568 27.7614C659.414 27.5242 659.097 27.4566 658.86 27.6106C658.622 27.7646 658.555 28.0818 658.709 28.3191C658.863 28.5563 659.18 28.6238 659.417 28.4698Z"
+            fill="var(--fill-0, white)"
+            id="Vector_140"
+            opacity="0.3"
+          />
+          <path
+            d="M578.788 55.7511C579.025 55.5971 579.093 55.28 578.939 55.0427C578.785 54.8054 578.468 54.7379 578.231 54.8919C577.993 55.0459 577.926 55.363 578.08 55.6003C578.234 55.8376 578.551 55.9051 578.788 55.7511Z"
+            fill="var(--fill-0, white)"
+            id="Vector_141"
+            opacity="0.11"
+          />
+          <path
+            d="M659.804 54.4777C660.041 54.3237 660.109 54.0066 659.955 53.7693C659.801 53.532 659.483 53.4645 659.246 53.6184C659.009 53.7724 658.941 54.0896 659.095 54.3269C659.249 54.5641 659.567 54.6317 659.804 54.4777Z"
+            fill="var(--fill-0, white)"
+            id="Vector_142"
+            opacity="0.11"
+          />
+          <path
+            d="M553.586 128.909C554.061 128.6 554.196 127.966 553.888 127.491C553.579 127.016 552.945 126.88 552.47 127.189C551.995 127.497 551.859 128.132 552.168 128.607C552.476 129.082 553.111 129.217 553.586 128.909Z"
+            fill="var(--fill-0, white)"
+            id="Vector_143"
+            opacity="0.3"
+          />
+          <path
+            d="M570.578 99.5591C571.053 99.2509 571.188 98.616 570.88 98.141C570.572 97.6661 569.937 97.5309 569.462 97.8392C568.987 98.1474 568.852 98.7823 569.16 99.2572C569.468 99.7322 570.103 99.8673 570.578 99.5591Z"
+            fill="var(--fill-0, white)"
+            id="Vector_144"
+            opacity="0.11"
+          />
+          <path
+            d="M560.603 84.6571C560.959 84.426 561.06 83.9499 560.829 83.5938C560.598 83.2377 560.122 83.1364 559.766 83.3675C559.41 83.5986 559.309 84.0746 559.54 84.4307C559.771 84.7868 560.247 84.8882 560.603 84.6571Z"
+            fill="var(--fill-0, white)"
+            id="Vector_145"
+          />
+          <path
+            d="M560.236 149.024C560.592 148.793 560.693 148.317 560.462 147.961C560.231 147.605 559.755 147.504 559.399 147.735C559.043 147.966 558.941 148.442 559.173 148.798C559.404 149.154 559.88 149.255 560.236 149.024Z"
+            fill="var(--fill-0, white)"
+            id="Vector_146"
+          />
+          <path
+            d="M708.49 65.0282C708.846 64.7971 708.947 64.321 708.716 63.9649C708.485 63.6088 708.009 63.5075 707.653 63.7386C707.297 63.9697 707.195 64.4457 707.426 64.8018C707.658 65.1579 708.134 65.2593 708.49 65.0282Z"
+            fill="var(--fill-0, white)"
+            id="Vector_147"
+          />
+          <path
+            d="M424.833 238.723C425.19 238.492 425.291 238.016 425.06 237.66C424.829 237.304 424.353 237.203 423.997 237.434C423.64 237.665 423.539 238.141 423.77 238.497C424.001 238.853 424.477 238.955 424.833 238.723Z"
+            fill="var(--fill-0, white)"
+            id="Vector_148"
+          />
+          <path
+            d="M361.267 265.93C361.623 265.699 361.724 265.223 361.493 264.867C361.262 264.511 360.786 264.41 360.43 264.641C360.074 264.872 359.973 265.348 360.204 265.704C360.435 266.06 360.911 266.162 361.267 265.93Z"
+            fill="var(--fill-0, white)"
+            id="Vector_149"
+          />
+          <path
+            d="M342.806 253.481C343.162 253.25 343.264 252.774 343.032 252.418C342.801 252.062 342.325 251.961 341.969 252.192C341.613 252.423 341.512 252.899 341.743 253.255C341.974 253.611 342.45 253.712 342.806 253.481Z"
+            fill="var(--fill-0, white)"
+            id="Vector_150"
+          />
+          <path
+            d="M545.556 106.639C545.912 106.408 546.014 105.932 545.782 105.576C545.551 105.22 545.075 105.119 544.719 105.35C544.363 105.581 544.262 106.057 544.493 106.413C544.724 106.769 545.2 106.871 545.556 106.639Z"
+            fill="var(--fill-0, white)"
+            id="Vector_151"
+          />
+          <path
+            d="M491.412 186.968C491.768 186.737 491.869 186.26 491.638 185.904C491.407 185.548 490.931 185.447 490.575 185.678C490.219 185.909 490.117 186.385 490.348 186.741C490.579 187.097 491.055 187.199 491.412 186.968Z"
+            fill="var(--fill-0, white)"
+            id="Vector_152"
+          />
+          <path
+            d="M611.705 135.167C612.061 134.936 612.162 134.46 611.931 134.104C611.7 133.747 611.224 133.646 610.868 133.877C610.512 134.108 610.41 134.584 610.641 134.94C610.872 135.297 611.348 135.398 611.705 135.167Z"
+            fill="var(--fill-0, white)"
+            id="Vector_153"
+          />
+          <path
+            d="M706.622 32.036C706.979 31.8049 707.08 31.3289 706.849 30.9727C706.618 30.6166 706.142 30.5153 705.786 30.7464C705.429 30.9775 705.328 31.4535 705.559 31.8096C705.79 32.1657 706.266 32.2671 706.622 32.036Z"
+            fill="var(--fill-0, white)"
+            id="Vector_154"
+          />
+          <path
+            d="M701.599 1.70786C701.955 1.47676 702.057 1.00073 701.825 0.644619C701.594 0.288505 701.118 0.187156 700.762 0.41826C700.406 0.649364 700.305 1.12539 700.536 1.4815C700.767 1.83762 701.243 1.93897 701.599 1.70786Z"
+            fill="var(--fill-0, white)"
+            id="Vector_155"
+          />
+          <path
+            d="M596.332 62.0786C596.807 61.7704 596.942 61.1355 596.634 60.6605C596.326 60.1856 595.691 60.0504 595.216 60.3587C594.741 60.6669 594.606 61.3018 594.914 61.7767C595.222 62.2517 595.857 62.3868 596.332 62.0786Z"
+            fill="var(--fill-0, white)"
+            id="Vector_156"
+            opacity="0.3"
+          />
+          <path
+            d="M576.531 31.5669C577.006 31.2587 577.141 30.6238 576.833 30.1488C576.525 29.6739 575.89 29.5387 575.415 29.847C574.94 30.1552 574.805 30.7901 575.113 31.265C575.421 31.74 576.056 31.8751 576.531 31.5669Z"
+            fill="var(--fill-0, white)"
+            id="Vector_157"
+          />
+          <path
+            d="M624.607 57.1707C624.963 56.9396 625.064 56.4636 624.833 56.1075C624.602 55.7514 624.126 55.65 623.77 55.8811C623.414 56.1122 623.313 56.5883 623.544 56.9444C623.775 57.3005 624.251 57.4018 624.607 57.1707Z"
+            fill="var(--fill-0, white)"
+            id="Vector_158"
+          />
+          <path
+            d="M634.57 26.8833C635.045 26.5751 635.18 25.9402 634.872 25.4653C634.564 24.9903 633.929 24.8551 633.454 25.1634C632.979 25.4716 632.844 26.1065 633.152 26.5814C633.46 27.0564 634.095 27.1916 634.57 26.8833Z"
+            fill="var(--fill-0, white)"
+            id="Vector_159"
+            opacity="0.3"
+          />
+          <path
+            d="M696.922 29.7837C697.397 29.4755 697.532 28.8406 697.224 28.3657C696.915 27.8907 696.28 27.7555 695.805 28.0638C695.331 28.372 695.195 29.0069 695.504 29.4818C695.812 29.9568 696.447 30.092 696.922 29.7837Z"
+            fill="var(--fill-0, white)"
+            id="Vector_160"
+            opacity="0.3"
+          />
+          <path
+            d="M647.195 63.274C647.67 62.9657 647.805 62.3308 647.497 61.8559C647.189 61.3809 646.554 61.2458 646.079 61.554C645.604 61.8622 645.469 62.4971 645.777 62.9721C646.085 63.447 646.72 63.5822 647.195 63.274Z"
+            fill="var(--fill-0, white)"
+            id="Vector_161"
+            opacity="0.3"
+          />
+          <path
+            d="M405.254 230.663C405.729 230.354 405.864 229.719 405.556 229.245C405.247 228.77 404.612 228.634 404.137 228.943C403.663 229.251 403.527 229.886 403.836 230.361C404.144 230.836 404.779 230.971 405.254 230.663Z"
+            fill="var(--fill-0, white)"
+            id="Vector_162"
+            opacity="0.3"
+          />
+          <path
+            d="M355.101 229.62C355.576 229.311 355.711 228.676 355.403 228.202C355.095 227.727 354.46 227.591 353.985 227.9C353.51 228.208 353.375 228.843 353.683 229.318C353.991 229.793 354.626 229.928 355.101 229.62Z"
+            fill="var(--fill-0, white)"
+            id="Vector_163"
+            opacity="0.3"
+          />
+          <path
+            d="M670.933 28.3267C671.408 28.0185 671.543 27.3836 671.235 26.9086C670.927 26.4337 670.292 26.2985 669.817 26.6067C669.342 26.915 669.207 27.5499 669.515 28.0248C669.824 28.4998 670.458 28.6349 670.933 28.3267Z"
+            fill="var(--fill-0, white)"
+            id="Vector_164"
+            opacity="0.11"
+          />
+          <path
+            d="M407.074 175.125C407.549 174.817 407.684 174.182 407.376 173.707C407.068 173.232 406.433 173.097 405.958 173.406C405.483 173.714 405.348 174.349 405.656 174.824C405.964 175.299 406.599 175.434 407.074 175.125Z"
+            fill="var(--fill-0, white)"
+            id="Vector_165"
+            opacity="0.3"
+          />
+          <path
+            d="M389.894 174.061C390.369 173.753 390.504 173.118 390.196 172.643C389.888 172.168 389.253 172.033 388.778 172.341C388.303 172.649 388.168 173.284 388.476 173.759C388.784 174.234 389.419 174.369 389.894 174.061Z"
+            fill="var(--fill-0, white)"
+            id="Vector_166"
+            opacity="0.11"
+          />
+          <path
+            d="M404.308 203.795C404.783 203.487 404.918 202.852 404.61 202.377C404.302 201.902 403.667 201.767 403.192 202.075C402.717 202.384 402.582 203.019 402.89 203.494C403.198 203.968 403.833 204.104 404.308 203.795Z"
+            fill="var(--fill-0, white)"
+            id="Vector_167"
+            opacity="0.3"
+          />
+          <path
+            d="M430.884 185.934C431.24 185.703 431.342 185.227 431.111 184.871C430.879 184.515 430.403 184.414 430.047 184.645C429.691 184.876 429.59 185.352 429.821 185.708C430.052 186.064 430.528 186.165 430.884 185.934Z"
+            fill="var(--fill-0, white)"
+            id="Vector_168"
+          />
+        </g>
+      </svg>
+    </div>
+  );
+}
+
+function FloatingStarsReverse() {
+  return (
+    <div className="absolute inset-[5.73%_3.6%_4.36%_3.18%] animate-[float-stars-reverse_15s_ease-in-out_infinite]">
+      <svg
+        className="absolute block size-full"
+        fill="none"
+        preserveAspectRatio="none"
+        viewBox="0 0 709.134 573.351"
+      >
+        <g id="Group" opacity="0.7">
+          <path
+            d="M175.054 442.166C175.529 441.858 175.664 441.223 175.356 440.748C175.048 440.273 174.413 440.138 173.938 440.447C173.463 440.755 173.328 441.39 173.636 441.865C173.945 442.34 174.579 442.475 175.054 442.166Z"
+            fill="var(--fill-0, white)"
+            id="Vector"
+            opacity="0.11"
+          />
+          <path
+            d="M180.908 445.083C181.264 444.852 181.365 444.376 181.134 444.02C180.903 443.663 180.427 443.562 180.071 443.793C179.715 444.024 179.613 444.5 179.844 444.856C180.075 445.213 180.551 445.314 180.908 445.083Z"
+            fill="var(--fill-0, white)"
+            id="Vector_2"
+          />
+          <path
+            d="M189.24 426.854C189.596 426.623 189.697 426.147 189.466 425.791C189.235 425.435 188.759 425.334 188.403 425.565C188.047 425.796 187.945 426.272 188.176 426.628C188.407 426.984 188.884 427.085 189.24 426.854Z"
+            fill="var(--fill-0, white)"
+            id="Vector_3"
+          />
+          <path
+            d="M152.15 449.698C152.506 449.467 152.607 448.991 152.376 448.635C152.145 448.279 151.669 448.177 151.313 448.408C150.957 448.64 150.855 449.116 151.087 449.472C151.318 449.828 151.794 449.929 152.15 449.698Z"
+            fill="var(--fill-0, white)"
+            id="Vector_4"
+          />
+          <path
+            d="M137.566 473.819C138.041 473.511 138.176 472.876 137.868 472.401C137.56 471.926 136.925 471.791 136.45 472.099C135.975 472.407 135.84 473.042 136.148 473.517C136.456 473.992 137.091 474.127 137.566 473.819Z"
+            fill="var(--fill-0, white)"
+            id="Vector_5"
+            opacity="0.11"
+          />
+          <path
+            d="M123.269 469.663C123.506 469.509 123.573 469.192 123.419 468.955C123.265 468.717 122.948 468.65 122.711 468.804C122.474 468.958 122.406 469.275 122.56 469.512C122.714 469.75 123.031 469.817 123.269 469.663Z"
+            fill="var(--fill-0, white)"
+            id="Vector_6"
+          />
+          <path
+            d="M184.636 459.765C184.873 459.611 184.941 459.294 184.787 459.056C184.633 458.819 184.315 458.752 184.078 458.906C183.841 459.06 183.773 459.377 183.927 459.614C184.081 459.851 184.398 459.919 184.636 459.765Z"
+            fill="var(--fill-0, white)"
+            id="Vector_7"
+          />
+          <path
+            d="M278.327 398.966C278.565 398.812 278.632 398.495 278.478 398.257C278.324 398.02 278.007 397.953 277.77 398.107C277.532 398.261 277.465 398.578 277.619 398.815C277.773 399.052 278.09 399.12 278.327 398.966Z"
+            fill="var(--fill-0, white)"
+            id="Vector_8"
+          />
+          <path
+            d="M310.105 345.359C310.342 345.205 310.409 344.887 310.255 344.65C310.101 344.413 309.784 344.345 309.547 344.499C309.31 344.653 309.242 344.97 309.396 345.208C309.55 345.445 309.867 345.513 310.105 345.359Z"
+            fill="var(--fill-0, white)"
+            id="Vector_9"
+          />
+          <path
+            d="M347.23 365.855C347.467 365.701 347.534 365.383 347.38 365.146C347.226 364.909 346.909 364.841 346.672 364.995C346.435 365.149 346.367 365.467 346.521 365.704C346.675 365.941 346.992 366.009 347.23 365.855Z"
+            fill="var(--fill-0, white)"
+            id="Vector_10"
+          />
+          <path
+            d="M34.5537 541.892C34.791 541.738 34.8585 541.421 34.7046 541.183C34.5506 540.946 34.2334 540.879 33.9961 541.033C33.7588 541.187 33.6913 541.504 33.8453 541.741C33.9993 541.978 34.3165 542.046 34.5537 541.892Z"
+            fill="var(--fill-0, white)"
+            id="Vector_11"
+          />
+          <path
+            d="M13.0498 522.868C13.2871 522.714 13.3546 522.397 13.2006 522.16C13.0467 521.923 12.7295 521.855 12.4922 522.009C12.2549 522.163 12.1874 522.48 12.3414 522.718C12.4954 522.955 12.8126 523.022 13.0498 522.868Z"
+            fill="var(--fill-0, white)"
+            id="Vector_12"
+            opacity="0.11"
+          />
+          <path
+            d="M0.987313 544.745C1.22459 544.591 1.29212 544.274 1.13814 544.037C0.984157 543.8 0.666993 543.732 0.429718 543.886C0.192444 544.04 0.12491 544.357 0.278892 544.594C0.432874 544.832 0.750038 544.899 0.987313 544.745Z"
+            fill="var(--fill-0, white)"
+            id="Vector_13"
+            opacity="0.11"
+          />
+          <path
+            d="M31.9014 561.327C32.1387 561.173 32.2062 560.856 32.0522 560.619C31.8982 560.382 31.5811 560.314 31.3438 560.468C31.1065 560.622 31.039 560.939 31.193 561.176C31.3469 561.414 31.6641 561.481 31.9014 561.327Z"
+            fill="var(--fill-0, white)"
+            id="Vector_14"
+            opacity="0.11"
+          />
+          <path
+            d="M123.022 477.759C123.26 477.605 123.327 477.288 123.173 477.05C123.019 476.813 122.702 476.746 122.465 476.9C122.228 477.054 122.16 477.371 122.314 477.608C122.468 477.845 122.785 477.913 123.022 477.759Z"
+            fill="var(--fill-0, white)"
+            id="Vector_15"
+            opacity="0.11"
+          />
+          <path
+            d="M193.823 475.794C194.061 475.64 194.128 475.323 193.974 475.086C193.82 474.848 193.503 474.781 193.266 474.935C193.028 475.089 192.961 475.406 193.115 475.643C193.269 475.881 193.586 475.948 193.823 475.794Z"
+            fill="var(--fill-0, white)"
+            id="Vector_16"
+            opacity="0.11"
+          />
+          <path
+            d="M273.542 417.948C273.779 417.794 273.847 417.477 273.693 417.24C273.539 417.003 273.222 416.935 272.984 417.089C272.747 417.243 272.68 417.56 272.834 417.798C272.988 418.035 273.305 418.102 273.542 417.948Z"
+            fill="var(--fill-0, white)"
+            id="Vector_17"
+            opacity="0.11"
+          />
+          <path
+            d="M47.3506 518.32C47.5879 518.166 47.6554 517.848 47.5014 517.611C47.3475 517.374 47.0303 517.306 46.793 517.46C46.5557 517.614 46.4882 517.931 46.6422 518.169C46.7962 518.406 47.1133 518.474 47.3506 518.32Z"
+            fill="var(--fill-0, white)"
+            id="Vector_18"
+            opacity="0.3"
+          />
+          <path
+            d="M131.132 430.966C131.369 430.812 131.437 430.495 131.283 430.257C131.129 430.02 130.812 429.953 130.574 430.107C130.337 430.261 130.269 430.578 130.423 430.815C130.577 431.052 130.895 431.12 131.132 430.966Z"
+            fill="var(--fill-0, white)"
+            id="Vector_19"
+          />
+          <path
+            d="M196.757 387.159C196.994 387.005 197.062 386.688 196.908 386.451C196.754 386.214 196.437 386.146 196.199 386.3C195.962 386.454 195.894 386.771 196.048 387.008C196.202 387.246 196.52 387.313 196.757 387.159Z"
+            fill="var(--fill-0, white)"
+            id="Vector_20"
+          />
+          <path
+            d="M127.569 489.468C127.807 489.314 127.874 488.997 127.72 488.759C127.566 488.522 127.249 488.455 127.012 488.609C126.774 488.763 126.707 489.08 126.861 489.317C127.015 489.554 127.332 489.622 127.569 489.468Z"
+            fill="var(--fill-0, white)"
+            id="Vector_21"
+          />
+          <path
+            d="M97.4873 508.993C97.7246 508.839 97.7921 508.522 97.6381 508.285C97.4842 508.048 97.167 507.98 96.9297 508.134C96.6924 508.288 96.6249 508.605 96.7789 508.842C96.9329 509.08 97.25 509.147 97.4873 508.993Z"
+            fill="var(--fill-0, white)"
+            id="Vector_22"
+            opacity="0.3"
+          />
+          <path
+            d="M44.96 505.214C45.1973 505.06 45.2648 504.743 45.1108 504.506C44.9568 504.268 44.6396 504.201 44.4024 504.355C44.1651 504.509 44.0976 504.826 44.2516 505.063C44.4056 505.3 44.7227 505.368 44.96 505.214Z"
+            fill="var(--fill-0, white)"
+            id="Vector_23"
+            opacity="0.11"
+          />
+          <path
+            d="M145.569 436.261C145.807 436.107 145.874 435.79 145.72 435.552C145.566 435.315 145.249 435.248 145.012 435.402C144.774 435.556 144.707 435.873 144.861 436.11C145.015 436.347 145.332 436.415 145.569 436.261Z"
+            fill="var(--fill-0, white)"
+            id="Vector_24"
+            opacity="0.3"
+          />
+          <path
+            d="M140.179 492.894C140.416 492.74 140.484 492.422 140.33 492.185C140.176 491.948 139.858 491.88 139.621 492.034C139.384 492.188 139.316 492.506 139.47 492.743C139.624 492.98 139.941 493.048 140.179 492.894Z"
+            fill="var(--fill-0, white)"
+            id="Vector_25"
+            opacity="0.3"
+          />
+          <path
+            d="M90.9639 530.935C91.2011 530.781 91.2687 530.464 91.1147 530.226C90.9607 529.989 90.6435 529.922 90.4063 530.076C90.169 530.229 90.1015 530.547 90.2555 530.784C90.4094 531.021 90.7266 531.089 90.9639 530.935Z"
+            fill="var(--fill-0, white)"
+            id="Vector_26"
+            opacity="0.3"
+          />
+          <path
+            d="M59.8194 510.232C60.0566 510.078 60.1242 509.76 59.9702 509.523C59.8162 509.286 59.499 509.218 59.2617 509.372C59.0245 509.526 58.957 509.843 59.1109 510.081C59.2649 510.318 59.5821 510.386 59.8194 510.232Z"
+            fill="var(--fill-0, white)"
+            id="Vector_27"
+            opacity="0.3"
+          />
+          <path
+            d="M326.284 335.472C326.522 335.318 326.589 335.001 326.435 334.763C326.281 334.526 325.964 334.459 325.727 334.613C325.489 334.767 325.422 335.084 325.576 335.321C325.73 335.558 326.047 335.626 326.284 335.472Z"
+            fill="var(--fill-0, white)"
+            id="Vector_28"
+            opacity="0.3"
+          />
+          <path
+            d="M245.659 362.751C245.896 362.597 245.964 362.28 245.81 362.043C245.656 361.805 245.339 361.738 245.102 361.892C244.864 362.046 244.797 362.363 244.951 362.6C245.105 362.838 245.422 362.905 245.659 362.751Z"
+            fill="var(--fill-0, white)"
+            id="Vector_29"
+            opacity="0.11"
+          />
+          <path
+            d="M326.675 361.48C326.912 361.326 326.98 361.008 326.826 360.771C326.672 360.534 326.355 360.466 326.117 360.62C325.88 360.774 325.812 361.092 325.966 361.329C326.12 361.566 326.438 361.634 326.675 361.48Z"
+            fill="var(--fill-0, white)"
+            id="Vector_30"
+            opacity="0.11"
+          />
+          <path
+            d="M220.453 435.911C220.928 435.602 221.063 434.968 220.755 434.493C220.447 434.018 219.812 433.882 219.337 434.191C218.862 434.499 218.727 435.134 219.035 435.609C219.343 436.084 219.978 436.219 220.453 435.911Z"
+            fill="var(--fill-0, white)"
+            id="Vector_31"
+            opacity="0.3"
+          />
+          <path
+            d="M237.449 406.561C237.924 406.253 238.059 405.618 237.751 405.143C237.443 404.668 236.808 404.533 236.333 404.841C235.858 405.149 235.723 405.784 236.031 406.259C236.339 406.734 236.974 406.869 237.449 406.561Z"
+            fill="var(--fill-0, white)"
+            id="Vector_32"
+            opacity="0.11"
+          />
+          <path
+            d="M227.474 391.659C227.83 391.428 227.931 390.952 227.7 390.596C227.469 390.24 226.993 390.138 226.637 390.369C226.281 390.601 226.18 391.077 226.411 391.433C226.642 391.789 227.118 391.89 227.474 391.659Z"
+            fill="var(--fill-0, white)"
+            id="Vector_33"
+          />
+          <path
+            d="M227.103 456.026C227.459 455.795 227.56 455.319 227.329 454.963C227.098 454.607 226.622 454.505 226.266 454.737C225.91 454.968 225.809 455.444 226.04 455.8C226.271 456.156 226.747 456.257 227.103 456.026Z"
+            fill="var(--fill-0, white)"
+            id="Vector_34"
+          />
+          <path
+            d="M375.361 372.03C375.717 371.799 375.818 371.323 375.587 370.967C375.356 370.611 374.88 370.509 374.524 370.74C374.168 370.972 374.066 371.448 374.298 371.804C374.529 372.16 375.005 372.261 375.361 372.03Z"
+            fill="var(--fill-0, white)"
+            id="Vector_35"
+          />
+          <path
+            d="M91.7044 545.725C92.0605 545.494 92.1619 545.018 91.9308 544.662C91.6997 544.306 91.2237 544.205 90.8675 544.436C90.5114 544.667 90.4101 545.143 90.6412 545.499C90.8723 545.855 91.3483 545.957 91.7044 545.725Z"
+            fill="var(--fill-0, white)"
+            id="Vector_36"
+          />
+          <path
+            d="M28.1381 572.933C28.4942 572.701 28.5955 572.225 28.3644 571.869C28.1333 571.513 27.6573 571.412 27.3011 571.643C26.945 571.874 26.8437 572.35 27.0748 572.706C27.3059 573.062 27.7819 573.164 28.1381 572.933Z"
+            fill="var(--fill-0, white)"
+            id="Vector_37"
+          />
+          <path
+            d="M9.67322 560.483C10.0293 560.252 10.1307 559.776 9.89957 559.42C9.66847 559.064 9.19242 558.963 8.8363 559.194C8.48019 559.425 8.37887 559.901 8.60997 560.257C8.84108 560.613 9.3171 560.714 9.67322 560.483Z"
+            fill="var(--fill-0, white)"
+            id="Vector_38"
+          />
+          <path
+            d="M212.423 413.641C212.779 413.41 212.881 412.934 212.65 412.578C212.418 412.222 211.942 412.121 211.586 412.352C211.23 412.583 211.129 413.059 211.36 413.415C211.591 413.771 212.067 413.873 212.423 413.641Z"
+            fill="var(--fill-0, white)"
+            id="Vector_39"
+          />
+          <path
+            d="M158.283 493.971C158.639 493.74 158.74 493.264 158.509 492.908C158.278 492.552 157.802 492.451 157.446 492.682C157.09 492.913 156.988 493.389 157.219 493.745C157.45 494.101 157.926 494.203 158.283 493.971Z"
+            fill="var(--fill-0, white)"
+            id="Vector_40"
+          />
+          <path
+            d="M278.576 442.171C278.932 441.94 279.033 441.464 278.802 441.107C278.571 440.751 278.095 440.65 277.739 440.881C277.383 441.112 277.281 441.588 277.512 441.944C277.743 442.3 278.219 442.402 278.576 442.171Z"
+            fill="var(--fill-0, white)"
+            id="Vector_41"
+          />
+          <path
+            d="M373.494 339.038C373.85 338.807 373.951 338.331 373.72 337.975C373.489 337.619 373.013 337.517 372.657 337.748C372.301 337.979 372.199 338.455 372.43 338.812C372.661 339.168 373.137 339.269 373.494 339.038Z"
+            fill="var(--fill-0, white)"
+            id="Vector_42"
+          />
+          <path
+            d="M368.466 308.71C368.822 308.479 368.924 308.003 368.693 307.647C368.461 307.29 367.985 307.189 367.629 307.42C367.273 307.651 367.172 308.127 367.403 308.483C367.634 308.84 368.11 308.941 368.466 308.71Z"
+            fill="var(--fill-0, white)"
+            id="Vector_43"
+          />
+          <path
+            d="M263.207 369.079C263.682 368.77 263.817 368.135 263.509 367.661C263.2 367.186 262.566 367.05 262.091 367.359C261.616 367.667 261.48 368.302 261.789 368.777C262.097 369.252 262.732 369.387 263.207 369.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_44"
+            opacity="0.3"
+          />
+          <path
+            d="M243.406 338.569C243.881 338.261 244.016 337.626 243.708 337.151C243.4 336.676 242.765 336.541 242.29 336.849C241.815 337.157 241.68 337.792 241.988 338.267C242.296 338.742 242.931 338.877 243.406 338.569Z"
+            fill="var(--fill-0, white)"
+            id="Vector_45"
+          />
+          <path
+            d="M291.474 364.171C291.83 363.94 291.932 363.464 291.7 363.107C291.469 362.751 290.993 362.65 290.637 362.881C290.281 363.112 290.18 363.588 290.411 363.944C290.642 364.3 291.118 364.402 291.474 364.171Z"
+            fill="var(--fill-0, white)"
+            id="Vector_46"
+          />
+          <path
+            d="M301.445 333.885C301.92 333.577 302.055 332.942 301.747 332.467C301.439 331.992 300.804 331.857 300.329 332.165C299.854 332.474 299.719 333.108 300.027 333.583C300.335 334.058 300.97 334.193 301.445 333.885Z"
+            fill="var(--fill-0, white)"
+            id="Vector_47"
+            opacity="0.3"
+          />
+          <path
+            d="M363.789 336.788C364.264 336.479 364.399 335.844 364.091 335.37C363.782 334.895 363.148 334.759 362.673 335.068C362.198 335.376 362.063 336.011 362.371 336.486C362.679 336.961 363.314 337.096 363.789 336.788Z"
+            fill="var(--fill-0, white)"
+            id="Vector_48"
+            opacity="0.3"
+          />
+          <path
+            d="M314.062 370.276C314.537 369.968 314.672 369.333 314.364 368.858C314.056 368.383 313.421 368.248 312.946 368.556C312.471 368.864 312.336 369.499 312.644 369.974C312.952 370.449 313.587 370.584 314.062 370.276Z"
+            fill="var(--fill-0, white)"
+            id="Vector_49"
+            opacity="0.3"
+          />
+          <path
+            d="M72.1247 537.667C72.5996 537.358 72.7348 536.723 72.4266 536.248C72.1183 535.774 71.4835 535.638 71.0085 535.947C70.5336 536.255 70.3984 536.89 70.7066 537.365C71.0148 537.84 71.6497 537.975 72.1247 537.667Z"
+            fill="var(--fill-0, white)"
+            id="Vector_50"
+            opacity="0.3"
+          />
+          <path
+            d="M21.9723 536.622C22.4473 536.313 22.5825 535.679 22.2742 535.204C21.966 534.729 21.3311 534.593 20.8562 534.902C20.3812 535.21 20.246 535.845 20.5543 536.32C20.8625 536.795 21.4974 536.93 21.9723 536.622Z"
+            fill="var(--fill-0, white)"
+            id="Vector_51"
+            opacity="0.3"
+          />
+          <path
+            d="M337.801 335.329C338.276 335.02 338.411 334.386 338.102 333.911C337.794 333.436 337.159 333.3 336.684 333.609C336.209 333.917 336.074 334.552 336.382 335.027C336.691 335.502 337.326 335.637 337.801 335.329Z"
+            fill="var(--fill-0, white)"
+            id="Vector_52"
+            opacity="0.11"
+          />
+          <path
+            d="M73.945 482.127C74.42 481.819 74.5551 481.184 74.2469 480.709C73.9387 480.234 73.3038 480.099 72.8288 480.407C72.3539 480.716 72.2187 481.351 72.5269 481.826C72.8352 482.3 73.4701 482.436 73.945 482.127Z"
+            fill="var(--fill-0, white)"
+            id="Vector_53"
+            opacity="0.3"
+          />
+          <path
+            d="M56.7653 481.063C57.2403 480.755 57.3754 480.12 57.0672 479.645C56.759 479.17 56.1241 479.035 55.6491 479.343C55.1742 479.651 55.039 480.286 55.3472 480.761C55.6555 481.236 56.2904 481.371 56.7653 481.063Z"
+            fill="var(--fill-0, white)"
+            id="Vector_54"
+            opacity="0.11"
+          />
+          <path
+            d="M71.1755 510.797C71.6504 510.489 71.7856 509.854 71.4774 509.379C71.1691 508.904 70.5342 508.769 70.0593 509.077C69.5843 509.386 69.4492 510.02 69.7574 510.495C70.0656 510.97 70.7005 511.106 71.1755 510.797Z"
+            fill="var(--fill-0, white)"
+            id="Vector_55"
+            opacity="0.3"
+          />
+          <path
+            d="M97.7552 492.938C98.1114 492.707 98.2127 492.231 97.9816 491.875C97.7505 491.519 97.2744 491.418 96.9183 491.649C96.5622 491.88 96.4609 492.356 96.692 492.712C96.9231 493.068 97.3991 493.169 97.7552 492.938Z"
+            fill="var(--fill-0, white)"
+            id="Vector_56"
+          />
+          <path
+            d="M238.5 214.481C238.975 214.173 239.11 213.538 238.802 213.063C238.493 212.588 237.858 212.453 237.384 212.761C236.909 213.069 236.773 213.704 237.082 214.179C237.39 214.654 238.025 214.789 238.5 214.481Z"
+            fill="var(--fill-0, white)"
+            id="Vector_57"
+            opacity="0.11"
+          />
+          <path
+            d="M244.361 217.395C244.717 217.164 244.818 216.688 244.587 216.332C244.356 215.976 243.88 215.875 243.524 216.106C243.168 216.337 243.066 216.813 243.297 217.169C243.529 217.525 244.005 217.626 244.361 217.395Z"
+            fill="var(--fill-0, white)"
+            id="Vector_58"
+          />
+          <path
+            d="M252.689 199.169C253.045 198.938 253.146 198.462 252.915 198.105C252.684 197.749 252.208 197.648 251.852 197.879C251.496 198.11 251.395 198.586 251.626 198.942C251.857 199.299 252.333 199.4 252.689 199.169Z"
+            fill="var(--fill-0, white)"
+            id="Vector_59"
+          />
+          <path
+            d="M215.599 222.013C215.955 221.781 216.056 221.305 215.825 220.949C215.594 220.593 215.118 220.492 214.762 220.723C214.406 220.954 214.305 221.43 214.536 221.786C214.767 222.142 215.243 222.244 215.599 222.013Z"
+            fill="var(--fill-0, white)"
+            id="Vector_60"
+          />
+          <path
+            d="M201.019 246.133C201.494 245.825 201.629 245.19 201.321 244.715C201.013 244.24 200.378 244.105 199.903 244.413C199.428 244.722 199.293 245.356 199.601 245.831C199.909 246.306 200.544 246.442 201.019 246.133Z"
+            fill="var(--fill-0, white)"
+            id="Vector_61"
+            opacity="0.11"
+          />
+          <path
+            d="M186.718 241.978C186.955 241.824 187.023 241.506 186.869 241.269C186.715 241.032 186.397 240.964 186.16 241.118C185.923 241.272 185.855 241.59 186.009 241.827C186.163 242.064 186.481 242.132 186.718 241.978Z"
+            fill="var(--fill-0, white)"
+            id="Vector_62"
+          />
+          <path
+            d="M248.085 232.079C248.322 231.925 248.39 231.608 248.236 231.371C248.082 231.133 247.765 231.066 247.527 231.22C247.29 231.374 247.223 231.691 247.377 231.928C247.531 232.166 247.848 232.233 248.085 232.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_63"
+          />
+          <path
+            d="M341.776 171.28C342.014 171.126 342.081 170.809 341.927 170.572C341.773 170.335 341.456 170.267 341.219 170.421C340.982 170.575 340.914 170.892 341.068 171.13C341.222 171.367 341.539 171.434 341.776 171.28Z"
+            fill="var(--fill-0, white)"
+            id="Vector_64"
+          />
+          <path
+            d="M373.558 117.675C373.795 117.521 373.863 117.204 373.709 116.966C373.555 116.729 373.237 116.662 373 116.816C372.763 116.97 372.695 117.287 372.849 117.524C373.003 117.761 373.32 117.829 373.558 117.675Z"
+            fill="var(--fill-0, white)"
+            id="Vector_65"
+          />
+          <path
+            d="M410.679 138.169C410.916 138.015 410.984 137.698 410.83 137.461C410.676 137.223 410.358 137.156 410.121 137.31C409.884 137.464 409.816 137.781 409.97 138.018C410.124 138.256 410.442 138.323 410.679 138.169Z"
+            fill="var(--fill-0, white)"
+            id="Vector_66"
+          />
+          <path
+            d="M98.003 314.206C98.2402 314.052 98.3078 313.735 98.1538 313.498C97.9998 313.26 97.6826 313.193 97.4453 313.347C97.2081 313.501 97.1406 313.818 97.2945 314.055C97.4485 314.293 97.7657 314.36 98.003 314.206Z"
+            fill="var(--fill-0, white)"
+            id="Vector_67"
+          />
+          <path
+            d="M76.503 295.181C76.7402 295.027 76.8078 294.71 76.6538 294.472C76.4998 294.235 76.1826 294.168 75.9454 294.322C75.7081 294.475 75.6406 294.793 75.7945 295.03C75.9485 295.267 76.2657 295.335 76.503 295.181Z"
+            fill="var(--fill-0, white)"
+            id="Vector_68"
+            opacity="0.11"
+          />
+          <path
+            d="M64.4405 317.058C64.6777 316.904 64.7453 316.587 64.5913 316.349C64.4373 316.112 64.1201 316.044 63.8829 316.198C63.6456 316.352 63.5781 316.67 63.732 316.907C63.886 317.144 64.2032 317.212 64.4405 317.058Z"
+            fill="var(--fill-0, white)"
+            id="Vector_69"
+            opacity="0.11"
+          />
+          <path
+            d="M95.3545 333.64C95.5918 333.486 95.6593 333.169 95.5053 332.931C95.3514 332.694 95.0342 332.627 94.7969 332.78C94.5596 332.934 94.4921 333.252 94.6461 333.489C94.8001 333.726 95.1172 333.794 95.3545 333.64Z"
+            fill="var(--fill-0, white)"
+            id="Vector_70"
+            opacity="0.11"
+          />
+          <path
+            d="M186.472 250.073C186.709 249.919 186.777 249.602 186.623 249.365C186.469 249.128 186.151 249.06 185.914 249.214C185.677 249.368 185.609 249.685 185.763 249.923C185.917 250.16 186.234 250.227 186.472 250.073Z"
+            fill="var(--fill-0, white)"
+            id="Vector_71"
+            opacity="0.11"
+          />
+          <path
+            d="M257.273 248.108C257.51 247.954 257.577 247.637 257.423 247.4C257.269 247.163 256.952 247.095 256.715 247.249C256.478 247.403 256.41 247.72 256.564 247.958C256.718 248.195 257.035 248.262 257.273 248.108Z"
+            fill="var(--fill-0, white)"
+            id="Vector_72"
+            opacity="0.11"
+          />
+          <path
+            d="M336.991 190.261C337.229 190.107 337.296 189.79 337.142 189.552C336.988 189.315 336.671 189.248 336.434 189.402C336.196 189.556 336.129 189.873 336.283 190.11C336.437 190.347 336.754 190.415 336.991 190.261Z"
+            fill="var(--fill-0, white)"
+            id="Vector_73"
+            opacity="0.11"
+          />
+          <path
+            d="M110.804 290.632C111.041 290.478 111.109 290.161 110.955 289.923C110.801 289.686 110.483 289.619 110.246 289.773C110.009 289.927 109.941 290.244 110.095 290.481C110.249 290.718 110.566 290.786 110.804 290.632Z"
+            fill="var(--fill-0, white)"
+            id="Vector_74"
+            opacity="0.3"
+          />
+          <path
+            d="M194.585 203.28C194.822 203.126 194.89 202.809 194.736 202.572C194.582 202.335 194.265 202.267 194.027 202.421C193.79 202.575 193.723 202.892 193.877 203.13C194.031 203.367 194.348 203.434 194.585 203.28Z"
+            fill="var(--fill-0, white)"
+            id="Vector_75"
+          />
+          <path
+            d="M260.21 159.472C260.447 159.318 260.515 159.001 260.361 158.763C260.207 158.526 259.89 158.459 259.652 158.613C259.415 158.767 259.348 159.084 259.502 159.321C259.656 159.558 259.973 159.626 260.21 159.472Z"
+            fill="var(--fill-0, white)"
+            id="Vector_76"
+          />
+          <path
+            d="M191.023 261.782C191.26 261.628 191.327 261.311 191.173 261.074C191.019 260.837 190.702 260.769 190.465 260.923C190.228 261.077 190.16 261.394 190.314 261.632C190.468 261.869 190.785 261.936 191.023 261.782Z"
+            fill="var(--fill-0, white)"
+            id="Vector_77"
+          />
+          <path
+            d="M160.937 281.306C161.174 281.152 161.241 280.835 161.087 280.597C160.933 280.36 160.616 280.293 160.379 280.447C160.142 280.6 160.074 280.918 160.228 281.155C160.382 281.392 160.699 281.46 160.937 281.306Z"
+            fill="var(--fill-0, white)"
+            id="Vector_78"
+            opacity="0.3"
+          />
+          <path
+            d="M108.413 277.528C108.65 277.374 108.718 277.057 108.564 276.82C108.41 276.583 108.093 276.515 107.856 276.669C107.618 276.823 107.551 277.14 107.705 277.378C107.859 277.615 108.176 277.682 108.413 277.528Z"
+            fill="var(--fill-0, white)"
+            id="Vector_79"
+            opacity="0.11"
+          />
+          <path
+            d="M209.019 208.573C209.256 208.419 209.323 208.102 209.169 207.865C209.015 207.628 208.698 207.56 208.461 207.714C208.224 207.868 208.156 208.185 208.31 208.423C208.464 208.66 208.781 208.727 209.019 208.573Z"
+            fill="var(--fill-0, white)"
+            id="Vector_80"
+            opacity="0.3"
+          />
+          <path
+            d="M203.628 265.206C203.865 265.052 203.933 264.735 203.779 264.498C203.625 264.26 203.308 264.193 203.07 264.347C202.833 264.501 202.766 264.818 202.92 265.055C203.074 265.293 203.391 265.36 203.628 265.206Z"
+            fill="var(--fill-0, white)"
+            id="Vector_81"
+            opacity="0.3"
+          />
+          <path
+            d="M154.413 303.251C154.65 303.097 154.718 302.78 154.564 302.543C154.41 302.305 154.093 302.238 153.856 302.392C153.618 302.546 153.551 302.863 153.705 303.1C153.859 303.338 154.176 303.405 154.413 303.251Z"
+            fill="var(--fill-0, white)"
+            id="Vector_82"
+            opacity="0.3"
+          />
+          <path
+            d="M123.269 282.546C123.506 282.392 123.573 282.075 123.419 281.838C123.265 281.6 122.948 281.533 122.711 281.687C122.474 281.841 122.406 282.158 122.56 282.395C122.714 282.632 123.031 282.7 123.269 282.546Z"
+            fill="var(--fill-0, white)"
+            id="Vector_83"
+            opacity="0.3"
+          />
+          <path
+            d="M389.737 107.784C389.975 107.63 390.042 107.313 389.888 107.076C389.734 106.839 389.417 106.771 389.18 106.925C388.943 107.079 388.875 107.396 389.029 107.633C389.183 107.871 389.5 107.938 389.737 107.784Z"
+            fill="var(--fill-0, white)"
+            id="Vector_84"
+            opacity="0.3"
+          />
+          <path
+            d="M309.109 135.067C309.346 134.914 309.413 134.596 309.259 134.359C309.105 134.122 308.788 134.054 308.551 134.208C308.314 134.362 308.246 134.679 308.4 134.917C308.554 135.154 308.871 135.221 309.109 135.067Z"
+            fill="var(--fill-0, white)"
+            id="Vector_85"
+            opacity="0.11"
+          />
+          <path
+            d="M390.124 133.794C390.361 133.64 390.429 133.323 390.275 133.086C390.121 132.848 389.804 132.781 389.567 132.935C389.329 133.089 389.262 133.406 389.416 133.643C389.57 133.881 389.887 133.948 390.124 133.794Z"
+            fill="var(--fill-0, white)"
+            id="Vector_86"
+            opacity="0.11"
+          />
+          <path
+            d="M283.91 208.223C284.385 207.915 284.52 207.28 284.212 206.805C283.904 206.33 283.269 206.195 282.794 206.503C282.319 206.811 282.184 207.446 282.492 207.921C282.8 208.396 283.435 208.531 283.91 208.223Z"
+            fill="var(--fill-0, white)"
+            id="Vector_87"
+            opacity="0.3"
+          />
+          <path
+            d="M300.894 178.875C301.369 178.567 301.504 177.932 301.196 177.457C300.888 176.982 300.253 176.847 299.778 177.156C299.303 177.464 299.168 178.099 299.476 178.574C299.784 179.049 300.419 179.184 300.894 178.875Z"
+            fill="var(--fill-0, white)"
+            id="Vector_88"
+            opacity="0.11"
+          />
+          <path
+            d="M290.923 163.973C291.279 163.742 291.381 163.266 291.15 162.91C290.919 162.554 290.443 162.453 290.086 162.684C289.73 162.915 289.629 163.391 289.86 163.747C290.091 164.103 290.567 164.205 290.923 163.973Z"
+            fill="var(--fill-0, white)"
+            id="Vector_89"
+          />
+          <path
+            d="M290.556 228.341C290.912 228.11 291.014 227.633 290.782 227.277C290.551 226.921 290.075 226.82 289.719 227.051C289.363 227.282 289.262 227.758 289.493 228.114C289.724 228.47 290.2 228.572 290.556 228.341Z"
+            fill="var(--fill-0, white)"
+            id="Vector_90"
+          />
+          <path
+            d="M438.81 144.345C439.166 144.113 439.267 143.637 439.036 143.281C438.805 142.925 438.329 142.824 437.973 143.055C437.617 143.286 437.516 143.762 437.747 144.118C437.978 144.474 438.454 144.576 438.81 144.345Z"
+            fill="var(--fill-0, white)"
+            id="Vector_91"
+          />
+          <path
+            d="M155.154 318.038C155.51 317.807 155.611 317.331 155.38 316.975C155.149 316.619 154.673 316.517 154.317 316.748C153.961 316.979 153.859 317.455 154.09 317.812C154.322 318.168 154.798 318.269 155.154 318.038Z"
+            fill="var(--fill-0, white)"
+            id="Vector_92"
+          />
+          <path
+            d="M91.5873 345.247C91.9434 345.016 92.0447 344.54 91.8136 344.184C91.5825 343.827 91.1065 343.726 90.7504 343.957C90.3943 344.188 90.2929 344.664 90.524 345.02C90.7551 345.377 91.2312 345.478 91.5873 345.247Z"
+            fill="var(--fill-0, white)"
+            id="Vector_93"
+          />
+          <path
+            d="M73.1264 332.798C73.4825 332.567 73.5838 332.091 73.3527 331.734C73.1216 331.378 72.6456 331.277 72.2894 331.508C71.9333 331.739 71.832 332.215 72.0631 332.571C72.2942 332.927 72.7702 333.029 73.1264 332.798Z"
+            fill="var(--fill-0, white)"
+            id="Vector_94"
+          />
+          <path
+            d="M275.876 185.956C276.233 185.725 276.334 185.249 276.103 184.893C275.872 184.536 275.396 184.435 275.039 184.666C274.683 184.897 274.582 185.373 274.813 185.73C275.044 186.086 275.52 186.187 275.876 185.956Z"
+            fill="var(--fill-0, white)"
+            id="Vector_95"
+          />
+          <path
+            d="M221.736 266.282C222.092 266.051 222.193 265.575 221.962 265.219C221.731 264.863 221.255 264.761 220.899 264.992C220.543 265.224 220.441 265.7 220.672 266.056C220.904 266.412 221.38 266.513 221.736 266.282Z"
+            fill="var(--fill-0, white)"
+            id="Vector_96"
+          />
+          <path
+            d="M342.025 214.483C342.381 214.252 342.482 213.776 342.251 213.42C342.02 213.064 341.544 212.962 341.188 213.194C340.832 213.425 340.73 213.901 340.962 214.257C341.193 214.613 341.669 214.714 342.025 214.483Z"
+            fill="var(--fill-0, white)"
+            id="Vector_97"
+          />
+          <path
+            d="M436.943 111.352C437.299 111.121 437.4 110.645 437.169 110.289C436.938 109.933 436.462 109.832 436.106 110.063C435.75 110.294 435.648 110.77 435.88 111.126C436.111 111.482 436.587 111.583 436.943 111.352Z"
+            fill="var(--fill-0, white)"
+            id="Vector_98"
+          />
+          <path
+            d="M431.919 81.0242C432.275 80.7931 432.377 80.3171 432.146 79.961C431.915 79.6049 431.439 79.5035 431.082 79.7346C430.726 79.9657 430.625 80.4418 430.856 80.7979C431.087 81.154 431.563 81.2554 431.919 81.0242Z"
+            fill="var(--fill-0, white)"
+            id="Vector_99"
+          />
+          <path
+            d="M326.656 141.393C327.131 141.085 327.266 140.45 326.958 139.975C326.65 139.5 326.015 139.365 325.54 139.673C325.065 139.981 324.93 140.616 325.238 141.091C325.546 141.566 326.181 141.701 326.656 141.393Z"
+            fill="var(--fill-0, white)"
+            id="Vector_100"
+            opacity="0.3"
+          />
+          <path
+            d="M306.851 110.881C307.326 110.573 307.461 109.938 307.153 109.463C306.845 108.988 306.21 108.853 305.735 109.161C305.26 109.47 305.125 110.105 305.433 110.579C305.742 111.054 306.376 111.19 306.851 110.881Z"
+            fill="var(--fill-0, white)"
+            id="Vector_101"
+          />
+          <path
+            d="M354.927 136.485C355.283 136.254 355.385 135.778 355.154 135.422C354.922 135.066 354.446 134.964 354.09 135.196C353.734 135.427 353.633 135.903 353.864 136.259C354.095 136.615 354.571 136.716 354.927 136.485Z"
+            fill="var(--fill-0, white)"
+            id="Vector_102"
+          />
+          <path
+            d="M364.894 106.198C365.369 105.89 365.504 105.255 365.196 104.78C364.888 104.305 364.253 104.17 363.778 104.478C363.303 104.786 363.168 105.421 363.476 105.896C363.784 106.371 364.419 106.506 364.894 106.198Z"
+            fill="var(--fill-0, white)"
+            id="Vector_103"
+            opacity="0.3"
+          />
+          <path
+            d="M427.238 109.102C427.713 108.794 427.848 108.159 427.54 107.684C427.232 107.209 426.597 107.074 426.122 107.382C425.647 107.69 425.512 108.325 425.82 108.8C426.128 109.275 426.763 109.41 427.238 109.102Z"
+            fill="var(--fill-0, white)"
+            id="Vector_104"
+            opacity="0.3"
+          />
+          <path
+            d="M377.515 142.59C377.99 142.282 378.126 141.647 377.817 141.172C377.509 140.697 376.874 140.562 376.399 140.87C375.924 141.179 375.789 141.813 376.097 142.288C376.406 142.763 377.04 142.899 377.515 142.59Z"
+            fill="var(--fill-0, white)"
+            id="Vector_105"
+            opacity="0.3"
+          />
+          <path
+            d="M135.574 309.979C136.049 309.671 136.184 309.036 135.876 308.561C135.568 308.086 134.933 307.951 134.458 308.259C133.983 308.567 133.848 309.202 134.156 309.677C134.464 310.152 135.099 310.287 135.574 309.979Z"
+            fill="var(--fill-0, white)"
+            id="Vector_106"
+            opacity="0.3"
+          />
+          <path
+            d="M85.4216 308.936C85.8965 308.628 86.0317 307.993 85.7235 307.518C85.4152 307.043 84.7803 306.908 84.3054 307.216C83.8304 307.524 83.6953 308.159 84.0035 308.634C84.3117 309.109 84.9466 309.244 85.4216 308.936Z"
+            fill="var(--fill-0, white)"
+            id="Vector_107"
+            opacity="0.3"
+          />
+          <path
+            d="M401.254 107.643C401.729 107.335 401.864 106.7 401.556 106.225C401.247 105.75 400.612 105.615 400.138 105.923C399.663 106.231 399.527 106.866 399.836 107.341C400.144 107.816 400.779 107.951 401.254 107.643Z"
+            fill="var(--fill-0, white)"
+            id="Vector_108"
+            opacity="0.11"
+          />
+          <path
+            d="M137.394 254.442C137.869 254.134 138.004 253.499 137.696 253.024C137.388 252.549 136.753 252.414 136.278 252.722C135.803 253.03 135.668 253.665 135.976 254.14C136.284 254.615 136.919 254.75 137.394 254.442Z"
+            fill="var(--fill-0, white)"
+            id="Vector_109"
+            opacity="0.3"
+          />
+          <path
+            d="M120.215 253.375C120.69 253.067 120.825 252.432 120.516 251.957C120.208 251.482 119.573 251.347 119.098 251.656C118.623 251.964 118.488 252.599 118.796 253.074C119.105 253.549 119.74 253.684 120.215 253.375Z"
+            fill="var(--fill-0, white)"
+            id="Vector_110"
+            opacity="0.11"
+          />
+          <path
+            d="M134.629 283.112C135.104 282.804 135.239 282.169 134.931 281.694C134.622 281.219 133.987 281.084 133.512 281.392C133.037 281.7 132.902 282.335 133.211 282.81C133.519 283.285 134.154 283.42 134.629 283.112Z"
+            fill="var(--fill-0, white)"
+            id="Vector_111"
+            opacity="0.3"
+          />
+          <path
+            d="M161.208 265.251C161.564 265.02 161.666 264.544 161.435 264.187C161.204 263.831 160.728 263.73 160.371 263.961C160.015 264.192 159.914 264.668 160.145 265.024C160.376 265.381 160.852 265.482 161.208 265.251Z"
+            fill="var(--fill-0, white)"
+            id="Vector_112"
+          />
+          <path
+            d="M508.183 135.165C508.658 134.856 508.793 134.221 508.485 133.747C508.177 133.272 507.542 133.136 507.067 133.445C506.592 133.753 506.457 134.388 506.765 134.863C507.074 135.338 507.708 135.473 508.183 135.165Z"
+            fill="var(--fill-0, white)"
+            id="Vector_113"
+            opacity="0.11"
+          />
+          <path
+            d="M514.04 138.079C514.397 137.848 514.498 137.372 514.267 137.016C514.036 136.66 513.56 136.558 513.204 136.789C512.847 137.02 512.746 137.496 512.977 137.853C513.208 138.209 513.684 138.31 514.04 138.079Z"
+            fill="var(--fill-0, white)"
+            id="Vector_114"
+          />
+          <path
+            d="M522.369 119.852C522.725 119.621 522.826 119.145 522.595 118.789C522.364 118.433 521.888 118.332 521.532 118.563C521.176 118.794 521.074 119.27 521.305 119.626C521.536 119.982 522.012 120.083 522.369 119.852Z"
+            fill="var(--fill-0, white)"
+            id="Vector_115"
+          />
+          <path
+            d="M485.279 142.698C485.635 142.467 485.736 141.991 485.505 141.635C485.274 141.279 484.798 141.177 484.442 141.408C484.086 141.64 483.984 142.116 484.216 142.472C484.447 142.828 484.923 142.929 485.279 142.698Z"
+            fill="var(--fill-0, white)"
+            id="Vector_116"
+          />
+          <path
+            d="M470.699 166.817C471.174 166.509 471.309 165.874 471.001 165.399C470.693 164.924 470.058 164.789 469.583 165.097C469.108 165.405 468.973 166.04 469.281 166.515C469.589 166.99 470.224 167.125 470.699 166.817Z"
+            fill="var(--fill-0, white)"
+            id="Vector_117"
+            opacity="0.11"
+          />
+          <path
+            d="M456.398 162.661C456.635 162.507 456.702 162.19 456.548 161.953C456.394 161.716 456.077 161.648 455.84 161.802C455.603 161.956 455.535 162.273 455.689 162.51C455.843 162.748 456.16 162.815 456.398 162.661Z"
+            fill="var(--fill-0, white)"
+            id="Vector_118"
+          />
+          <path
+            d="M517.765 152.763C518.002 152.609 518.07 152.292 517.916 152.054C517.762 151.817 517.444 151.75 517.207 151.904C516.97 152.058 516.902 152.375 517.056 152.612C517.21 152.849 517.528 152.917 517.765 152.763Z"
+            fill="var(--fill-0, white)"
+            id="Vector_119"
+          />
+          <path
+            d="M611.456 91.964C611.693 91.81 611.761 91.4929 611.607 91.2556C611.453 91.0183 611.136 90.9508 610.899 91.1048C610.661 91.2588 610.594 91.5759 610.748 91.8132C610.902 92.0505 611.219 92.118 611.456 91.964Z"
+            fill="var(--fill-0, white)"
+            id="Vector_120"
+          />
+          <path
+            d="M643.234 38.3586C643.471 38.2046 643.538 37.8874 643.384 37.6501C643.23 37.4128 642.913 37.3453 642.676 37.4993C642.439 37.6533 642.371 37.9705 642.525 38.2077C642.679 38.445 642.996 38.5125 643.234 38.3586Z"
+            fill="var(--fill-0, white)"
+            id="Vector_121"
+          />
+          <path
+            d="M680.359 58.8527C680.596 58.6987 680.663 58.3815 680.509 58.1442C680.355 57.907 680.038 57.8394 679.801 57.9934C679.564 58.1474 679.496 58.4646 679.65 58.7019C679.804 58.9391 680.121 59.0066 680.359 58.8527Z"
+            fill="var(--fill-0, white)"
+            id="Vector_122"
+          />
+          <path
+            d="M367.683 234.89C367.92 234.736 367.987 234.419 367.834 234.181C367.68 233.944 367.362 233.877 367.125 234.031C366.888 234.184 366.82 234.502 366.974 234.739C367.128 234.976 367.445 235.044 367.683 234.89Z"
+            fill="var(--fill-0, white)"
+            id="Vector_123"
+          />
+          <path
+            d="M346.179 215.866C346.416 215.712 346.484 215.395 346.33 215.158C346.176 214.921 345.858 214.853 345.621 215.007C345.384 215.161 345.316 215.478 345.47 215.716C345.624 215.953 345.942 216.02 346.179 215.866Z"
+            fill="var(--fill-0, white)"
+            id="Vector_124"
+            opacity="0.11"
+          />
+          <path
+            d="M334.116 237.741C334.354 237.587 334.421 237.27 334.267 237.033C334.113 236.796 333.796 236.728 333.559 236.882C333.321 237.036 333.254 237.353 333.408 237.591C333.562 237.828 333.879 237.895 334.116 237.741Z"
+            fill="var(--fill-0, white)"
+            id="Vector_125"
+            opacity="0.11"
+          />
+          <path
+            d="M365.03 254.325C365.268 254.171 365.335 253.854 365.181 253.617C365.027 253.38 364.71 253.312 364.473 253.466C364.235 253.62 364.168 253.937 364.322 254.175C364.476 254.412 364.793 254.479 365.03 254.325Z"
+            fill="var(--fill-0, white)"
+            id="Vector_126"
+            opacity="0.11"
+          />
+          <path
+            d="M456.152 170.757C456.389 170.603 456.456 170.286 456.302 170.049C456.148 169.811 455.831 169.744 455.594 169.898C455.357 170.052 455.289 170.369 455.443 170.606C455.597 170.843 455.914 170.911 456.152 170.757Z"
+            fill="var(--fill-0, white)"
+            id="Vector_127"
+            opacity="0.11"
+          />
+          <path
+            d="M526.944 168.792C527.182 168.638 527.249 168.321 527.095 168.084C526.941 167.846 526.624 167.779 526.387 167.933C526.15 168.087 526.082 168.404 526.236 168.641C526.39 168.879 526.707 168.946 526.944 168.792Z"
+            fill="var(--fill-0, white)"
+            id="Vector_128"
+            opacity="0.11"
+          />
+          <path
+            d="M606.671 110.946C606.908 110.792 606.976 110.475 606.822 110.238C606.668 110.001 606.351 109.933 606.113 110.087C605.876 110.241 605.809 110.558 605.963 110.796C606.117 111.033 606.434 111.1 606.671 110.946Z"
+            fill="var(--fill-0, white)"
+            id="Vector_129"
+            opacity="0.11"
+          />
+          <path
+            d="M380.483 211.316C380.721 211.162 380.788 210.844 380.634 210.607C380.48 210.37 380.163 210.302 379.926 210.456C379.689 210.61 379.621 210.927 379.775 211.165C379.929 211.402 380.246 211.47 380.483 211.316Z"
+            fill="var(--fill-0, white)"
+            id="Vector_130"
+            opacity="0.3"
+          />
+          <path
+            d="M464.265 123.964C464.502 123.81 464.57 123.493 464.416 123.256C464.262 123.018 463.944 122.951 463.707 123.105C463.47 123.259 463.402 123.576 463.556 123.813C463.71 124.05 464.028 124.118 464.265 123.964Z"
+            fill="var(--fill-0, white)"
+            id="Vector_131"
+          />
+          <path
+            d="M529.89 80.1574C530.127 80.0034 530.195 79.6862 530.041 79.449C529.887 79.2117 529.569 79.1441 529.332 79.2981C529.095 79.4521 529.027 79.7693 529.181 80.0065C529.335 80.2438 529.652 80.3114 529.89 80.1574Z"
+            fill="var(--fill-0, white)"
+            id="Vector_132"
+          />
+          <path
+            d="M460.698 182.468C460.936 182.314 461.003 181.997 460.849 181.759C460.695 181.522 460.378 181.455 460.141 181.609C459.903 181.763 459.836 182.08 459.99 182.317C460.144 182.554 460.461 182.622 460.698 182.468Z"
+            fill="var(--fill-0, white)"
+            id="Vector_133"
+          />
+          <path
+            d="M430.616 201.991C430.854 201.837 430.921 201.52 430.767 201.283C430.613 201.046 430.296 200.978 430.059 201.132C429.821 201.286 429.754 201.603 429.908 201.841C430.062 202.078 430.379 202.145 430.616 201.991Z"
+            fill="var(--fill-0, white)"
+            id="Vector_134"
+            opacity="0.3"
+          />
+          <path
+            d="M378.089 198.212C378.326 198.058 378.394 197.741 378.24 197.504C378.086 197.266 377.769 197.199 377.531 197.353C377.294 197.507 377.227 197.824 377.381 198.061C377.534 198.298 377.852 198.366 378.089 198.212Z"
+            fill="var(--fill-0, white)"
+            id="Vector_135"
+            opacity="0.11"
+          />
+          <path
+            d="M478.698 129.257C478.936 129.103 479.003 128.786 478.849 128.549C478.695 128.311 478.378 128.244 478.141 128.398C477.903 128.552 477.836 128.869 477.99 129.106C478.144 129.343 478.461 129.411 478.698 129.257Z"
+            fill="var(--fill-0, white)"
+            id="Vector_136"
+            opacity="0.3"
+          />
+          <path
+            d="M473.308 185.892C473.545 185.738 473.613 185.421 473.459 185.183C473.305 184.946 472.987 184.879 472.75 185.032C472.513 185.186 472.445 185.504 472.599 185.741C472.753 185.978 473.07 186.046 473.308 185.892Z"
+            fill="var(--fill-0, white)"
+            id="Vector_137"
+            opacity="0.3"
+          />
+          <path
+            d="M424.093 223.935C424.33 223.781 424.398 223.464 424.244 223.226C424.09 222.989 423.773 222.921 423.535 223.075C423.298 223.229 423.23 223.547 423.384 223.784C423.538 224.021 423.856 224.089 424.093 223.935Z"
+            fill="var(--fill-0, white)"
+            id="Vector_138"
+            opacity="0.3"
+          />
+          <path
+            d="M392.948 203.23C393.186 203.076 393.253 202.758 393.099 202.521C392.945 202.284 392.628 202.216 392.391 202.37C392.153 202.524 392.086 202.842 392.24 203.079C392.394 203.316 392.711 203.384 392.948 203.23Z"
+            fill="var(--fill-0, white)"
+            id="Vector_139"
+            opacity="0.3"
+          />
+          <path
+            d="M659.413 28.4698C659.651 28.3159 659.718 27.9987 659.564 27.7614C659.41 27.5242 659.093 27.4566 658.856 27.6106C658.618 27.7646 658.551 28.0818 658.705 28.3191C658.859 28.5563 659.176 28.6238 659.413 28.4698Z"
+            fill="var(--fill-0, white)"
+            id="Vector_140"
+            opacity="0.3"
+          />
+          <path
+            d="M578.788 55.7511C579.025 55.5971 579.093 55.28 578.939 55.0427C578.785 54.8054 578.468 54.7379 578.231 54.8919C577.993 55.0459 577.926 55.363 578.08 55.6003C578.234 55.8376 578.551 55.9051 578.788 55.7511Z"
+            fill="var(--fill-0, white)"
+            id="Vector_141"
+            opacity="0.11"
+          />
+          <path
+            d="M659.804 54.4777C660.041 54.3237 660.109 54.0066 659.955 53.7693C659.801 53.532 659.483 53.4645 659.246 53.6184C659.009 53.7724 658.941 54.0896 659.095 54.3269C659.249 54.5641 659.567 54.6317 659.804 54.4777Z"
+            fill="var(--fill-0, white)"
+            id="Vector_142"
+            opacity="0.11"
+          />
+          <path
+            d="M553.582 128.909C554.057 128.6 554.192 127.966 553.884 127.491C553.576 127.016 552.941 126.88 552.466 127.189C551.991 127.497 551.856 128.132 552.164 128.607C552.472 129.082 553.107 129.217 553.582 128.909Z"
+            fill="var(--fill-0, white)"
+            id="Vector_143"
+            opacity="0.3"
+          />
+          <path
+            d="M570.578 99.5591C571.053 99.2509 571.188 98.616 570.88 98.141C570.572 97.6661 569.937 97.5309 569.462 97.8392C568.987 98.1474 568.852 98.7823 569.16 99.2572C569.468 99.7322 570.103 99.8673 570.578 99.5591Z"
+            fill="var(--fill-0, white)"
+            id="Vector_144"
+            opacity="0.11"
+          />
+          <path
+            d="M560.603 84.659C560.959 84.4279 561.06 83.9519 560.829 83.5958C560.598 83.2397 560.122 83.1383 559.766 83.3694C559.41 83.6005 559.309 84.0765 559.54 84.4327C559.771 84.7888 560.247 84.8901 560.603 84.659Z"
+            fill="var(--fill-0, white)"
+            id="Vector_145"
+          />
+          <path
+            d="M560.236 149.026C560.592 148.795 560.693 148.319 560.462 147.963C560.231 147.607 559.755 147.505 559.399 147.737C559.043 147.968 558.941 148.444 559.173 148.8C559.404 149.156 559.88 149.257 560.236 149.026Z"
+            fill="var(--fill-0, white)"
+            id="Vector_146"
+          />
+          <path
+            d="M708.49 65.0282C708.846 64.7971 708.947 64.321 708.716 63.9649C708.485 63.6088 708.009 63.5075 707.653 63.7386C707.297 63.9697 707.195 64.4457 707.426 64.8018C707.658 65.1579 708.134 65.2593 708.49 65.0282Z"
+            fill="var(--fill-0, white)"
+            id="Vector_147"
+          />
+          <path
+            d="M424.833 238.723C425.19 238.492 425.291 238.016 425.06 237.66C424.829 237.304 424.353 237.203 423.997 237.434C423.64 237.665 423.539 238.141 423.77 238.497C424.001 238.853 424.477 238.955 424.833 238.723Z"
+            fill="var(--fill-0, white)"
+            id="Vector_148"
+          />
+          <path
+            d="M361.267 265.93C361.623 265.699 361.724 265.223 361.493 264.867C361.262 264.511 360.786 264.41 360.43 264.641C360.074 264.872 359.973 265.348 360.204 265.704C360.435 266.06 360.911 266.162 361.267 265.93Z"
+            fill="var(--fill-0, white)"
+            id="Vector_149"
+          />
+          <path
+            d="M342.802 253.483C343.158 253.252 343.26 252.776 343.029 252.42C342.797 252.064 342.321 251.962 341.965 252.194C341.609 252.425 341.508 252.901 341.739 253.257C341.97 253.613 342.446 253.714 342.802 253.483Z"
+            fill="var(--fill-0, white)"
+            id="Vector_150"
+          />
+          <path
+            d="M545.552 106.639C545.908 106.408 546.01 105.932 545.779 105.576C545.547 105.22 545.071 105.119 544.715 105.35C544.359 105.581 544.258 106.057 544.489 106.413C544.72 106.769 545.196 106.871 545.552 106.639Z"
+            fill="var(--fill-0, white)"
+            id="Vector_151"
+          />
+          <path
+            d="M491.412 186.968C491.768 186.737 491.869 186.26 491.638 185.904C491.407 185.548 490.931 185.447 490.575 185.678C490.219 185.909 490.117 186.385 490.348 186.741C490.579 187.097 491.055 187.199 491.412 186.968Z"
+            fill="var(--fill-0, white)"
+            id="Vector_152"
+          />
+          <path
+            d="M611.705 135.167C612.061 134.936 612.162 134.46 611.931 134.104C611.7 133.747 611.224 133.646 610.868 133.877C610.512 134.108 610.41 134.584 610.641 134.94C610.872 135.297 611.348 135.398 611.705 135.167Z"
+            fill="var(--fill-0, white)"
+            id="Vector_153"
+          />
+          <path
+            d="M706.622 32.036C706.979 31.8049 707.08 31.3289 706.849 30.9727C706.618 30.6166 706.142 30.5153 705.786 30.7464C705.429 30.9775 705.328 31.4535 705.559 31.8096C705.79 32.1657 706.266 32.2671 706.622 32.036Z"
+            fill="var(--fill-0, white)"
+            id="Vector_154"
+          />
+          <path
+            d="M701.599 1.70786C701.955 1.47676 702.057 1.00073 701.825 0.644619C701.594 0.288505 701.118 0.187156 700.762 0.41826C700.406 0.649364 700.305 1.12539 700.536 1.4815C700.767 1.83762 701.243 1.93897 701.599 1.70786Z"
+            fill="var(--fill-0, white)"
+            id="Vector_155"
+          />
+          <path
+            d="M596.328 62.0786C596.803 61.7704 596.938 61.1355 596.63 60.6605C596.322 60.1856 595.687 60.0504 595.212 60.3587C594.737 60.6669 594.602 61.3018 594.91 61.7767C595.218 62.2517 595.853 62.3868 596.328 62.0786Z"
+            fill="var(--fill-0, white)"
+            id="Vector_156"
+            opacity="0.3"
+          />
+          <path
+            d="M576.527 31.5669C577.002 31.2587 577.137 30.6238 576.829 30.1488C576.521 29.6739 575.886 29.5387 575.411 29.847C574.936 30.1552 574.801 30.7901 575.109 31.265C575.417 31.74 576.052 31.8751 576.527 31.5669Z"
+            fill="var(--fill-0, white)"
+            id="Vector_157"
+          />
+          <path
+            d="M624.607 57.1707C624.963 56.9396 625.064 56.4636 624.833 56.1075C624.602 55.7514 624.126 55.65 623.77 55.8811C623.414 56.1122 623.313 56.5883 623.544 56.9444C623.775 57.3005 624.251 57.4018 624.607 57.1707Z"
+            fill="var(--fill-0, white)"
+            id="Vector_158"
+          />
+          <path
+            d="M634.57 26.8833C635.045 26.5751 635.18 25.9402 634.872 25.4653C634.564 24.9903 633.929 24.8551 633.454 25.1634C632.979 25.4716 632.844 26.1065 633.152 26.5814C633.46 27.0564 634.095 27.1916 634.57 26.8833Z"
+            fill="var(--fill-0, white)"
+            id="Vector_159"
+            opacity="0.3"
+          />
+          <path
+            d="M696.918 29.7857C697.393 29.4775 697.528 28.8426 697.22 28.3676C696.911 27.8927 696.277 27.7575 695.802 28.0657C695.327 28.3739 695.191 29.0088 695.5 29.4838C695.808 29.9587 696.443 30.0939 696.918 29.7857Z"
+            fill="var(--fill-0, white)"
+            id="Vector_160"
+            opacity="0.3"
+          />
+          <path
+            d="M647.195 63.274C647.67 62.9657 647.805 62.3308 647.497 61.8559C647.189 61.3809 646.554 61.2458 646.079 61.554C645.604 61.8622 645.469 62.4971 645.777 62.9721C646.085 63.447 646.72 63.5822 647.195 63.274Z"
+            fill="var(--fill-0, white)"
+            id="Vector_161"
+            opacity="0.3"
+          />
+          <path
+            d="M405.254 230.665C405.729 230.356 405.864 229.721 405.556 229.246C405.247 228.772 404.612 228.636 404.137 228.945C403.663 229.253 403.527 229.888 403.836 230.363C404.144 230.838 404.779 230.973 405.254 230.665Z"
+            fill="var(--fill-0, white)"
+            id="Vector_162"
+            opacity="0.3"
+          />
+          <path
+            d="M355.101 229.62C355.576 229.311 355.711 228.676 355.403 228.202C355.095 227.727 354.46 227.591 353.985 227.9C353.51 228.208 353.375 228.843 353.683 229.318C353.991 229.793 354.626 229.928 355.101 229.62Z"
+            fill="var(--fill-0, white)"
+            id="Vector_163"
+            opacity="0.3"
+          />
+          <path
+            d="M670.933 28.3287C671.408 28.0204 671.543 27.3855 671.235 26.9106C670.927 26.4356 670.292 26.3005 669.817 26.6087C669.342 26.9169 669.207 27.5518 669.515 28.0268C669.824 28.5017 670.458 28.6369 670.933 28.3287Z"
+            fill="var(--fill-0, white)"
+            id="Vector_164"
+            opacity="0.11"
+          />
+          <path
+            d="M407.074 175.127C407.549 174.819 407.684 174.184 407.376 173.709C407.068 173.234 406.433 173.099 405.958 173.407C405.483 173.716 405.348 174.351 405.656 174.826C405.964 175.301 406.599 175.436 407.074 175.127Z"
+            fill="var(--fill-0, white)"
+            id="Vector_165"
+            opacity="0.3"
+          />
+          <path
+            d="M389.894 174.061C390.369 173.753 390.504 173.118 390.196 172.643C389.888 172.168 389.253 172.033 388.778 172.341C388.303 172.649 388.168 173.284 388.476 173.759C388.784 174.234 389.419 174.369 389.894 174.061Z"
+            fill="var(--fill-0, white)"
+            id="Vector_166"
+            opacity="0.11"
+          />
+          <path
+            d="M404.304 203.795C404.779 203.487 404.915 202.852 404.606 202.377C404.298 201.902 403.663 201.767 403.188 202.075C402.713 202.384 402.578 203.019 402.886 203.494C403.195 203.968 403.829 204.104 404.304 203.795Z"
+            fill="var(--fill-0, white)"
+            id="Vector_167"
+            opacity="0.3"
+          />
+          <path
+            d="M430.884 185.936C431.24 185.705 431.342 185.229 431.111 184.873C430.879 184.517 430.403 184.416 430.047 184.647C429.691 184.878 429.59 185.354 429.821 185.71C430.052 186.066 430.528 186.167 430.884 185.936Z"
+            fill="var(--fill-0, white)"
+            id="Vector_168"
+          />
+        </g>
+      </svg>
+    </div>
+  );
+}
+
+// =============================================================================
+// FloatingStars - Combined star layers with proper positioning
+// =============================================================================
+
+function StarsLayerFrame({children}: {children: ReactNode}) {
+  return (
+    <div className="absolute top-0 left-1/2 h-[637.702px] w-[760.706px] -translate-x-1/2">
+      {children}
+    </div>
+  );
+}
+
+export function FloatingStars() {
+  return (
+    <div className="relative h-[637.702px] w-[760.706px] overflow-clip">
+      <StarsLayerFrame>
+        <FloatingStarsForward />
+      </StarsLayerFrame>
+      <div className="absolute top-[86.38px] left-[calc(50%-63.96px)] h-[637.702px] w-[760.706px] -translate-x-1/2 overflow-clip">
+        <StarsLayerFrame>
+          <FloatingStarsReverse />
+        </StarsLayerFrame>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/components/pro-badge.tsx b/apps/docs/src/app/[lang]/(home)/components/pro-badge.tsx
new file mode 100644
index 0000000..00b7cde
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/pro-badge.tsx
@@ -0,0 +1,60 @@
+import type {SVGProps} from "react";
+
+export const ProBadge = (props: SVGProps<SVGSVGElement>) => {
+  return (
+    <svg
+      fill="none"
+      height={16}
+      viewBox="0 0 16 16"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g filter="url(#a)">
+        <path
+          d="M6.668 1.436a2.667 2.667 0 0 1 2.667 0l3.684 2.127a2.667 2.667 0 0 1 1.333 2.31v4.254c0 .953-.508 1.833-1.333 2.31l-3.684 2.126a2.667 2.667 0 0 1-2.667 0l-3.684-2.127a2.667 2.667 0 0 1-1.334-2.31V5.874c0-.953.509-1.833 1.334-2.31l3.684-2.127Z"
+          fill="url(#b)"
+        />
+      </g>
+      <path
+        d="M8.384 7.063V5.237c.01-.045-.008-.152-.148-.218-.122-.057-.255.028-.295.082a72.22 72.22 0 0 0-1.788 3.12c-.057.13-.018.21.035.27.04.045.134.072.185.072h1.235l-.263 2.233c.003.052.046.163.188.197.141.034.239-.068.27-.123l2.019-3.417c.03-.045.09-.164.025-.27a.26.26 0 0 0-.233-.12h-1.23Z"
+        fill="#fff"
+      />
+      <defs>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="b"
+          x1={8.001}
+          x2={8.001}
+          y1={0.667}
+          y2={15.333}
+        >
+          <stop stopColor="#388EF8" />
+          <stop offset={1} stopColor="#90D7F6" />
+        </linearGradient>
+        <filter
+          colorInterpolationFilters="sRGB"
+          filterUnits="userSpaceOnUse"
+          height={13.841}
+          id="a"
+          width={12.699}
+          x={1.652}
+          y={1.079}
+        >
+          <feFlood floodOpacity={0} result="BackgroundImageFix" />
+          <feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape" />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset />
+          <feGaussianBlur stdDeviation={0.333} />
+          <feComposite in2="hardAlpha" k2={-1} k3={1} operator="arithmetic" />
+          <feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.3 0" />
+          <feBlend in2="shape" result="effect1_innerShadow_3573_58880" />
+        </filter>
+      </defs>
+    </svg>
+  );
+};
diff --git a/apps/docs/src/app/[lang]/(home)/components/pro-banner.tsx b/apps/docs/src/app/[lang]/(home)/components/pro-banner.tsx
new file mode 100644
index 0000000..ba9d404
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/pro-banner.tsx
@@ -0,0 +1,403 @@
+"use client";
+
+import {Button, CloseButton, buttonVariants} from "@heroui/react";
+import {Calligraph} from "calligraph";
+import {AnimatePresence, motion} from "motion/react";
+import {useEffect, useState, useSyncExternalStore} from "react";
+
+import {env} from "~env";
+
+import {FloatingStars} from "./floating-stars";
+import {PRO_URL, SHOW_BANNER} from "./pro-constants";
+import {ProTitle} from "./pro-title";
+
+interface DiscountData {
+  label: string;
+  percent: number;
+  endsAt: string;
+}
+
+const PRO_API_URL = env.NEXT_PUBLIC_PRO_API_URL;
+
+const DISCOUNT_CAMPAIGN = "launch_discount";
+const DEFAULT_CAMPAIGN = "pro_default";
+
+const getProHref = (medium: string, campaign: string) =>
+  `${PRO_URL}?utm_source=heroui.com&utm_medium=${medium}&utm_campaign=${campaign}`;
+
+const DEFAULT_PRO_COPY = {
+  cardDescription:
+    "Components, templates, and AI tooling for React and React Native. Made for teams that care about the details.",
+  cardTitle: "Build faster with HeroUI Pro",
+  cta: "Explore Pro",
+  headerDetail: "Components, templates & AI tooling",
+  headerTitle: "HeroUI Pro is live",
+  heroLabel: "Now available",
+};
+
+const DISCOUNT_PRO_COPY = {
+  cardDescription:
+    "More components, charts, advanced MCP & Skills, and a complete theme builder. Get your license now at a discounted price for a limited time.",
+  cardTitle: "HeroUI Pro launch discount is live!",
+  cta: "Get Pro deal",
+  headerTitle: "Launch discount is live!",
+};
+
+function useProDiscount() {
+  const [discount, setDiscount] = useState<DiscountData | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!PRO_API_URL) return;
+
+    fetch(`${PRO_API_URL}/api/prices`)
+      .then((res) => res.json())
+      .then((data) => {
+        if (!cancelled && data?.discount) {
+          setDiscount(data.discount);
+        }
+      })
+      .catch(() => {});
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return discount;
+}
+
+interface TimeRemaining {
+  days: string;
+  hours: string;
+  minutes: string;
+  seconds: string;
+}
+
+interface CountdownState {
+  endsAt: string;
+  time: TimeRemaining | null;
+}
+
+function getTimeRemaining(targetDate: Date): TimeRemaining | null {
+  const diff = Math.max(0, targetDate.getTime() - Date.now());
+
+  if (diff <= 0) return null;
+
+  const totalSeconds = Math.floor(diff / 1000);
+  const pad = (n: number) => String(n).padStart(2, "0");
+
+  return {
+    days: pad(Math.floor(totalSeconds / 86400)),
+    hours: pad(Math.floor((totalSeconds % 86400) / 3600)),
+    minutes: pad(Math.floor((totalSeconds % 3600) / 60)),
+    seconds: pad(totalSeconds % 60),
+  };
+}
+
+function useCountdown(endsAt: string | null) {
+  const [countdown, setCountdown] = useState<CountdownState | null>(null);
+
+  useEffect(() => {
+    if (!endsAt) return;
+
+    const endDate = new Date(endsAt);
+
+    if (Number.isNaN(endDate.getTime())) return;
+
+    const update = () => setCountdown({endsAt, time: getTimeRemaining(endDate)});
+
+    const frame = requestAnimationFrame(update);
+    const id = setInterval(update, 1000);
+
+    return () => {
+      cancelAnimationFrame(frame);
+      clearInterval(id);
+    };
+  }, [endsAt]);
+
+  if (!endsAt || countdown?.endsAt !== endsAt) return null;
+
+  return countdown.time;
+}
+
+export function HeaderBanner() {
+  const discount = useProDiscount();
+  const time = useCountdown(discount?.endsAt ?? null);
+
+  if (!SHOW_BANNER) return null;
+
+  const hasLiveDiscount = Boolean(discount && time);
+  const campaign = hasLiveDiscount ? DISCOUNT_CAMPAIGN : DEFAULT_CAMPAIGN;
+
+  return (
+    <a
+      className="flex h-8 w-full items-center justify-center gap-1.5 bg-surface-secondary transition-colors hover:bg-surface-secondary/80"
+      href={getProHref("banner", campaign)}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      <span className="shrink-0 rounded-full bg-accent px-2 py-0.5 text-xs leading-tight font-medium text-accent-foreground">
+        Pro
+      </span>
+      {hasLiveDiscount ? (
+        <>
+          <span className="hidden text-xs font-medium text-foreground sm:inline">
+            {DISCOUNT_PRO_COPY.headerTitle}
+          </span>
+          <span className="text-xs font-medium text-foreground">
+            <span className="tabular-nums">{discount?.percent}</span>% off
+            <span className="hidden sm:inline"> ends</span> in
+          </span>
+          <span className="shrink-0 rounded-[5px] border border-accent-soft-hover bg-linear-to-r from-accent/10 to-accent/7 px-1.5 py-0.5 text-xs leading-tight font-medium text-foreground tabular-nums">
+            <Calligraph animation="snappy" variant="number">
+              {time?.days}
+            </Calligraph>
+            d :{" "}
+            <Calligraph animation="snappy" variant="number">
+              {time?.hours}
+            </Calligraph>
+            h :{" "}
+            <Calligraph animation="snappy" variant="number">
+              {time?.minutes}
+            </Calligraph>
+            m :{" "}
+            <Calligraph animation="snappy" variant="number">
+              {time?.seconds}
+            </Calligraph>
+            s
+          </span>
+        </>
+      ) : (
+        <span className="text-xs font-medium text-foreground">
+          <span className="hidden sm:inline">{DEFAULT_PRO_COPY.headerTitle} - </span>
+          {DEFAULT_PRO_COPY.headerDetail}
+        </span>
+      )}
+    </a>
+  );
+}
+
+const PRO_BANNER_DISMISSED_KEY = "heroui-pro-banner-dismissed-session";
+
+const subscribeToDismissed = (callback: () => void) => {
+  window.addEventListener("storage", callback);
+
+  return () => window.removeEventListener("storage", callback);
+};
+const getDismissedSnapshot = () => sessionStorage.getItem(PRO_BANNER_DISMISSED_KEY) === "true";
+const getDismissedServerSnapshot = () => true;
+
+export function ProBanner() {
+  const wasPreviouslyDismissed = useSyncExternalStore(
+    subscribeToDismissed,
+    getDismissedSnapshot,
+    getDismissedServerSnapshot,
+  );
+  const [dismissed, setDismissed] = useState(false);
+  const discount = useProDiscount();
+  const time = useCountdown(discount?.endsAt ?? null);
+
+  const visible = SHOW_BANNER && !wasPreviouslyDismissed && !dismissed;
+  const hasLiveDiscount = Boolean(discount && time);
+  const campaign = hasLiveDiscount ? DISCOUNT_CAMPAIGN : DEFAULT_CAMPAIGN;
+  const copy = hasLiveDiscount ? DISCOUNT_PRO_COPY : DEFAULT_PRO_COPY;
+
+  const handleDismiss = () => {
+    setDismissed(true);
+    sessionStorage.setItem(PRO_BANNER_DISMISSED_KEY, "true");
+  };
+
+  return (
+    <AnimatePresence>
+      {visible ? (
+        <motion.div
+          animate={{opacity: 1, scale: 1, y: 0}}
+          className="fixed bottom-6 left-6 z-50 w-[288px] overflow-hidden rounded-[20px] border border-separator bg-surface shadow-xl"
+          exit={{opacity: 0, scale: 0.95, transition: {duration: 0.2, ease: "easeIn"}, y: 20}}
+          initial={{opacity: 0, scale: 0.95, y: 20}}
+          transition={{damping: 25, delay: 0.5, stiffness: 300, type: "spring"}}
+        >
+          {/* Top gradient section */}
+          <div className="relative flex h-[180px] flex-col items-center justify-center gap-2 overflow-hidden px-6 py-6">
+            <svg
+              className="absolute inset-0 size-full -scale-y-100"
+              fill="none"
+              preserveAspectRatio="none"
+              viewBox="0 0 406 328"
+            >
+              <g clipPath="url(#clip0_pro_banner)">
+                <g filter="url(#filter0_i_pro_banner)">
+                  <rect
+                    fill="url(#paint0_linear_pro_banner)"
+                    height="365"
+                    width="406"
+                    x="0"
+                    y="0"
+                  />
+                </g>
+                <g filter="url(#filter1_f_pro_banner)">
+                  <path
+                    d="M301.812 168C361.459 168 409.812 216.353 409.812 276C409.812 335.647 361.459 384 301.812 384C242.166 384 193.813 335.647 193.812 276C193.812 216.353 242.166 168 301.812 168Z"
+                    fill="url(#paint1_linear_pro_banner)"
+                  />
+                </g>
+              </g>
+              <defs>
+                <filter
+                  colorInterpolationFilters="sRGB"
+                  filterUnits="userSpaceOnUse"
+                  height="365"
+                  id="filter0_i_pro_banner"
+                  width="406"
+                  x="0"
+                  y="0"
+                >
+                  <feFlood floodOpacity="0" result="BackgroundImageFix" />
+                  <feBlend
+                    in="SourceGraphic"
+                    in2="BackgroundImageFix"
+                    mode="normal"
+                    result="shape"
+                  />
+                  <feColorMatrix
+                    in="SourceAlpha"
+                    result="hardAlpha"
+                    type="matrix"
+                    values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+                  />
+                  <feMorphology
+                    in="SourceAlpha"
+                    operator="erode"
+                    radius="12.8125"
+                    result="effect1_innerShadow_pro_banner"
+                  />
+                  <feOffset />
+                  <feGaussianBlur stdDeviation="80.0781" />
+                  <feComposite in2="hardAlpha" k2="-1" k3="1" operator="arithmetic" />
+                  <feColorMatrix
+                    type="matrix"
+                    values="0 0 0 0 0.728741 0 0 0 0 0.968353 0 0 0 0 1 0 0 0 0.8 0"
+                  />
+                  <feBlend in2="shape" mode="normal" result="effect1_innerShadow_pro_banner" />
+                </filter>
+                <filter
+                  colorInterpolationFilters="sRGB"
+                  filterUnits="userSpaceOnUse"
+                  height="344.125"
+                  id="filter1_f_pro_banner"
+                  width="344.125"
+                  x="129.75"
+                  y="103.938"
+                >
+                  <feFlood floodOpacity="0" result="BackgroundImageFix" />
+                  <feBlend
+                    in="SourceGraphic"
+                    in2="BackgroundImageFix"
+                    mode="normal"
+                    result="shape"
+                  />
+                  <feGaussianBlur
+                    result="effect1_foregroundBlur_pro_banner"
+                    stdDeviation="32.0312"
+                  />
+                </filter>
+                <linearGradient
+                  gradientUnits="userSpaceOnUse"
+                  id="paint0_linear_pro_banner"
+                  x1="203"
+                  x2="203"
+                  y1="0"
+                  y2="365"
+                >
+                  <stop stopColor="#E9E9FF" />
+                  <stop offset="1" stopColor="#CCE5F1" />
+                </linearGradient>
+                <linearGradient
+                  gradientUnits="userSpaceOnUse"
+                  id="paint1_linear_pro_banner"
+                  x1="235.242"
+                  x2="397.641"
+                  y1="219.359"
+                  y2="417.953"
+                >
+                  <stop stopColor="#5DD0E7" />
+                  <stop offset="1" stopColor="#7300FF" />
+                </linearGradient>
+                <clipPath id="clip0_pro_banner">
+                  <rect fill="white" height="328" width="406" />
+                </clipPath>
+              </defs>
+            </svg>
+            {/* Floating white particles */}
+            <div className="pointer-events-none absolute inset-0 overflow-hidden">
+              <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 scale-50">
+                <FloatingStars />
+              </div>
+            </div>
+            <div className="relative flex items-center gap-2">
+              <ProTitle />
+            </div>
+            {hasLiveDiscount ? (
+              <span className="relative text-xs text-[#4E75A5] tabular-nums">
+                Ends in{" "}
+                <Calligraph animation="snappy" variant="number">
+                  {time?.days}
+                </Calligraph>
+                d{" "}
+                <Calligraph animation="snappy" variant="number">
+                  {time?.hours}
+                </Calligraph>
+                h{" "}
+                <Calligraph animation="snappy" variant="number">
+                  {time?.minutes}
+                </Calligraph>
+                m{" "}
+                <Calligraph animation="snappy" variant="number">
+                  {time?.seconds}
+                </Calligraph>
+                s
+              </span>
+            ) : (
+              <span className="relative text-xs font-medium text-[#4E75A5]">
+                {DEFAULT_PRO_COPY.heroLabel}
+              </span>
+            )}
+          </div>
+
+          <CloseButton
+            className="absolute top-2 right-2 bg-transparent text-white/50 hover:bg-white/10 hover:text-white"
+            onPress={handleDismiss}
+          />
+
+          {/* Content section */}
+          <div className="flex flex-col gap-3 p-4">
+            <div className="flex flex-col gap-1.5">
+              <h3 className="text-base font-semibold text-foreground">{copy.cardTitle}</h3>
+              <p className="text-sm leading-relaxed text-muted">{copy.cardDescription}</p>
+            </div>
+            <div className="flex items-center gap-2 pt-1">
+              <Button size="md" variant="outline" onPress={handleDismiss}>
+                Close
+              </Button>
+              <a
+                href={getProHref("pro_banner", campaign)}
+                rel="noopener noreferrer"
+                target="_blank"
+                className={buttonVariants({
+                  className: "bg-black text-white dark:bg-white dark:text-black",
+                  fullWidth: true,
+                  size: "md",
+                  variant: "primary",
+                })}
+              >
+                {copy.cta}
+              </a>
+            </div>
+          </div>
+        </motion.div>
+      ) : null}
+    </AnimatePresence>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/components/pro-constants.ts b/apps/docs/src/app/[lang]/(home)/components/pro-constants.ts
new file mode 100644
index 0000000..b7f9db7
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/pro-constants.ts
@@ -0,0 +1,5 @@
+import {env} from "~env";
+
+export const SHOW_BANNER = env.NEXT_PUBLIC_SHOW_PRE_SALE_BANNER;
+
+export const PRO_URL = env.NEXT_PUBLIC_PRO_URL ?? "https://heroui.pro";
diff --git a/apps/docs/src/app/[lang]/(home)/components/pro-title.tsx b/apps/docs/src/app/[lang]/(home)/components/pro-title.tsx
new file mode 100644
index 0000000..5ff6da4
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/pro-title.tsx
@@ -0,0 +1,81 @@
+import type {SVGProps} from "react";
+
+export const ProTitle = (props: SVGProps<SVGSVGElement>) => {
+  return (
+    <svg
+      fill="none"
+      height={46}
+      viewBox="0 0 125 46"
+      width={125}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M0 11.3357V24.9169C0 25.5588 0.343128 26.1553 0.907647 26.4948L10.5365 32.285C11.8197 33.0566 13.4817 32.1662 13.4817 30.7071V19.2911C13.4817 18.6343 13.8408 18.0262 14.4263 17.6915L20.2998 14.3338V43.5925C20.2998 45.0467 21.9518 45.9379 23.2354 45.1761L33.1736 39.2777C33.7436 38.9394 34.0909 38.3398 34.0909 37.694V9.59744C34.0909 8.15035 32.4533 7.25804 31.1694 8.00553L20.2998 14.3338V1.862C20.2998 0.418827 18.6702 -0.47405 17.3862 0.265583L0.93911 9.7393C0.356694 10.0748 0 10.6811 0 11.3357Z"
+        fill="url(#pro-title-a)"
+      />
+      <path
+        d="M110.884 39.5982C103.06 39.5982 98.0859 34.4306 98.0859 26.6067C98.0859 18.7828 103.06 13.6152 110.884 13.6152C118.612 13.6152 123.586 18.7828 123.586 26.6067C123.586 34.4306 118.612 39.5982 110.884 39.5982ZM110.884 34.334C114.748 34.334 117.308 31.2914 117.308 26.6067C117.308 21.9221 114.748 18.8311 110.884 18.8311C106.972 18.8311 104.413 21.9221 104.413 26.6067C104.413 31.2914 106.972 34.334 110.884 34.334Z"
+        fill="url(#pro-title-b)"
+      />
+      <path
+        d="M82.875 20.5695C82.875 16.561 85.0483 14.3877 89.2017 14.3877H97.1222V19.6036H89.0568V38.8252H82.875V20.5695Z"
+        fill="url(#pro-title-c)"
+      />
+      <path
+        d="M53.0312 39.7722V7.5752H68.6931C75.3333 7.5752 79.5464 11.3928 79.5464 17.4643C79.5464 23.3977 75.5165 27.3993 68.6931 27.3993H59.2135V39.7722H53.0312ZM68.1435 21.9258C71.3491 21.9258 73.2725 20.27 73.2725 17.3723C73.2725 14.6585 71.3491 13.0487 68.1435 13.0487H59.2135V21.9258H68.1435Z"
+        fill="url(#pro-title-d)"
+      />
+      <defs>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="pro-title-a"
+          x1={28.5}
+          x2={1}
+          y1={-6.773}
+          y2={47.727}
+        >
+          <stop stopColor="#617BF8" />
+          <stop offset={0.702} stopColor="#6AC6F7" />
+          <stop offset={1} stopColor="#90CAF6" />
+        </linearGradient>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="pro-title-b"
+          x1={119.404}
+          x2={106.283}
+          y1={9.744}
+          y2={43.77}
+        >
+          <stop stopColor="#617BF8" />
+          <stop offset={0.702} stopColor="#6AC6F7" />
+          <stop offset={1} stopColor="#90CAF6" />
+        </linearGradient>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="pro-title-c"
+          x1={94.786}
+          x2={77.997}
+          y1={10.746}
+          y2={36.609}
+        >
+          <stop stopColor="#617BF8" />
+          <stop offset={0.702} stopColor="#6AC6F7" />
+          <stop offset={1} stopColor="#90CAF6" />
+        </linearGradient>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="pro-title-d"
+          x1={75.198}
+          x2={56.822}
+          y1={2.778}
+          y2={42.766}
+        >
+          <stop stopColor="#617BF8" />
+          <stop offset={0.702} stopColor="#6AC6F7" />
+          <stop offset={1} stopColor="#90CAF6" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
diff --git a/apps/docs/src/app/[lang]/(home)/components/release-badges.tsx b/apps/docs/src/app/[lang]/(home)/components/release-badges.tsx
new file mode 100644
index 0000000..2d4cbf6
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/components/release-badges.tsx
@@ -0,0 +1,124 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import LinkRoot from "fumadocs-core/link";
+import {AnimatePresence, animate, motion, useMotionValue, useReducedMotion} from "motion/react";
+import {useEffect, useMemo, useState} from "react";
+
+interface ReleaseBadge {
+  label: string;
+  href: string;
+  /** ISO date string (e.g. "2026-06-30") used to order badges newest-first. */
+  date?: string;
+}
+
+interface ReleaseBadgesProps {
+  badges: ReleaseBadge[];
+  /** Autoplay interval in milliseconds. */
+  intervalMs?: number;
+}
+
+// Soft, fluid settle for the badge slide (Apple-style spring, minimal bounce).
+const slideSpring = {bounce: 0.18, type: "spring", visualDuration: 0.4} as const;
+// Quick ease-out fade so opacity never lingers behind the movement.
+const fadeOut = {duration: 0.22, ease: [0.215, 0.61, 0.355, 1]} as const;
+
+function BadgePill({badge}: {badge: ReleaseBadge}) {
+  return (
+    <LinkRoot
+      className="flex items-center gap-1 rounded-full bg-accent-soft px-2 py-1 text-xs text-accent-soft-foreground transition-colors hover:bg-accent-soft-hover"
+      href={badge.href}
+    >
+      <Rocket className="size-3 shrink-0 text-accent-soft-foreground" />
+      <span className="max-w-60 truncate sm:max-w-full">{badge.label}</span>
+    </LinkRoot>
+  );
+}
+
+export function ReleaseBadges({badges, intervalMs = 5000}: ReleaseBadgesProps) {
+  const reduceMotion = useReducedMotion() ?? false;
+  const [index, setIndex] = useState(0);
+  const [paused, setPaused] = useState(false);
+  const progress = useMotionValue(0);
+
+  // Order badges newest-first so the latest release is shown first. Badges
+  // without a valid date sink to the bottom while preserving their relative
+  // order (stable sort).
+  const sortedBadges = useMemo(() => {
+    const toTime = (badge: ReleaseBadge): number => {
+      if (!badge.date) return Number.NEGATIVE_INFINITY;
+
+      const time = new Date(badge.date).getTime();
+
+      return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
+    };
+
+    return [...badges].sort((a, b) => toTime(b) - toTime(a));
+  }, [badges]);
+
+  const count = sortedBadges.length;
+
+  // Autoplay: drive a single progress value (transform-only fill) and advance
+  // on completion. Stopping retains the value, so hover/focus pause + resume
+  // and manual jumps stay in sync and interruptible.
+  useEffect(() => {
+    if (count <= 1 || paused) return;
+
+    if (reduceMotion) {
+      const id = setInterval(() => setIndex((i) => (i + 1) % count), intervalMs);
+
+      return () => clearInterval(id);
+    }
+
+    const remaining = (1 - progress.get()) * intervalMs;
+    const controls = animate(progress, 1, {
+      duration: remaining / 1000,
+      ease: "linear",
+      onComplete: () => {
+        progress.set(0);
+        setIndex((i) => (i + 1) % count);
+      },
+    });
+
+    return () => controls.stop();
+  }, [index, paused, reduceMotion, count, intervalMs, progress]);
+
+  if (count === 0) return null;
+
+  // Single highlight: render the plain badge (no carousel chrome).
+  if (count === 1) {
+    const [only] = sortedBadges;
+
+    return only ? <BadgePill badge={only} /> : null;
+  }
+
+  const activeIndex = index % count;
+  const active = sortedBadges[activeIndex];
+
+  if (!active) return null;
+
+  return (
+    <div
+      className="flex h-6 items-center justify-center"
+      onBlurCapture={() => setPaused(false)}
+      onFocusCapture={() => setPaused(true)}
+      onMouseEnter={() => setPaused(true)}
+      onMouseLeave={() => setPaused(false)}
+    >
+      <AnimatePresence initial={false} mode="popLayout">
+        <motion.div
+          key={activeIndex}
+          animate={{opacity: 1, y: 0}}
+          exit={reduceMotion ? {opacity: 0} : {opacity: 0, y: -10}}
+          initial={reduceMotion ? {opacity: 0} : {opacity: 0, y: 10}}
+          style={{willChange: "transform, opacity"}}
+          transition={
+            reduceMotion ? {duration: 0} : {default: slideSpring, opacity: fadeOut, y: slideSpring}
+          }
+        >
+          <BadgePill badge={active} />
+        </motion.div>
+      </AnimatePresence>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/home-content.tsx b/apps/docs/src/app/[lang]/(home)/home-content.tsx
new file mode 100644
index 0000000..a2e8fd2
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/home-content.tsx
@@ -0,0 +1,217 @@
+import type {LinkItemType} from "@/components/fumadocs/ui/link-item";
+import type {ReactNode} from "react";
+
+import {ExternalLink} from "@/components/external-link";
+import {Iconify} from "@/components/iconify";
+import {i18n} from "@/lib/i18n";
+
+export type HomeLocale = (typeof i18n)["languages"][number];
+
+export interface HomeContent {
+  releaseBadge: string;
+  title: ReactNode;
+  description: string;
+  getStarted: string;
+  viewComponents: string;
+  githubStarsPrefix: string;
+  githubStarsSuffix: string;
+  demo: {
+    proTemplate: string;
+    themeBuilder: string;
+  };
+  nav: {
+    documentation: string;
+    resources: string;
+    gettingStarted: string;
+    themes: string;
+    components: string;
+    reactNative: string;
+    reactNativeShort: string;
+    releases: string;
+    blog: string;
+    docs: string;
+    roadmap: string;
+  };
+}
+
+const content: Record<HomeLocale, HomeContent> = {
+  cn: {
+    demo: {
+      proTemplate: "Pro 中提供模板",
+      themeBuilder: "在主题构建器中打开",
+    },
+    description:
+      "HeroUI 是面向 Web 与移动端的现代 UI 库，助你快速迭代、保持一致，并打造令人愉悦的用户体验。",
+    getStarted: "快速开始",
+    githubStarsPrefix: "开源项目，已有",
+    githubStarsSuffix: "颗星",
+    nav: {
+      blog: "博客",
+      components: "组件",
+      docs: "文档",
+      documentation: "文档",
+      gettingStarted: "快速开始",
+      reactNative: "React Native",
+      reactNativeShort: "Native",
+      releases: "版本发布",
+      resources: "资源",
+      roadmap: "路线图",
+      themes: "主题",
+    },
+    releaseBadge: "HeroUI Native v1.0.5 — 补丁版本",
+    title: (
+      <>
+        开箱即美。<span className="text-muted/70">设计上随心可定。</span>
+      </>
+    ),
+    viewComponents: "查看组件",
+  },
+  en: {
+    demo: {
+      proTemplate: "Available in Pro as template",
+      themeBuilder: "Open in theme builder",
+    },
+    description:
+      "HeroUI is the modern UI library for web and mobile, built to help you move fast, stay consistent, and deliver delightful user experiences.",
+    getStarted: "Get started",
+    githubStarsPrefix: "Open source with",
+    githubStarsSuffix: "stars",
+    nav: {
+      blog: "Blog",
+      components: "Components",
+      docs: "Docs",
+      documentation: "Documentation",
+      gettingStarted: "Getting Started",
+      reactNative: "React Native",
+      reactNativeShort: "Native",
+      releases: "Releases",
+      resources: "Resources",
+      roadmap: "Roadmap",
+      themes: "Themes",
+    },
+    releaseBadge: "HeroUI Native v1.0.5 — patch release",
+    title: (
+      <>
+        Beautiful by default. <span className="text-muted/70">Customizable by design.</span>
+      </>
+    ),
+    viewComponents: "View components",
+  },
+};
+
+export function getHomeLocale(lang: string): HomeLocale {
+  return i18n.languages.includes(lang as HomeLocale) ? (lang as HomeLocale) : i18n.defaultLanguage;
+}
+
+export function getHomeContent(lang: string): HomeContent {
+  return content[getHomeLocale(lang)];
+}
+
+export function getHomeLayoutLinks(lang: string): LinkItemType[] {
+  const {nav} = getHomeContent(lang);
+  const blogUrl = `/${lang}/blog`;
+
+  return [
+    {
+      items: [
+        {
+          icon: <Iconify icon="book" />,
+          text: nav.gettingStarted,
+          url: "/docs/react/getting-started",
+        },
+        {
+          icon: <Iconify icon="palette" />,
+          text: nav.themes,
+          url: "/themes",
+        },
+        {
+          icon: <Iconify icon="circles-4-diamond" />,
+          text: nav.components,
+          url: "/docs/react/components",
+        },
+        {
+          icon: <Iconify icon="smartphone" />,
+          text: nav.reactNative,
+          url: "/docs/native/getting-started",
+        },
+        {
+          icon: <Iconify icon="rocket" />,
+          text: nav.releases,
+          url: "/docs/react/releases",
+        },
+      ],
+      on: "menu",
+      text: nav.documentation,
+      type: "menu",
+    },
+    {
+      items: [
+        {
+          icon: <Iconify icon="pen-line" />,
+          text: nav.blog,
+          url: blogUrl,
+        },
+        {
+          external: true,
+          icon: <Iconify icon="figma" />,
+          text: "Figma",
+          url: "https://www.figma.com/community/file/1546526812159103429",
+        },
+        {
+          external: true,
+          icon: <Iconify icon="route" />,
+          text: nav.roadmap,
+          url: "https://herouiv3.featurebase.app/roadmap",
+        },
+      ],
+      on: "menu",
+      text: nav.resources,
+      type: "menu",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.docs,
+      url: "/docs/react/getting-started",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.themes,
+      url: "/themes",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.components,
+      url: "/docs/react/components",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: (
+        <>
+          <span className="md:hidden">{nav.reactNativeShort}</span>
+          <span className="hidden md:inline">{nav.reactNative}</span>
+        </>
+      ),
+      url: "/docs/native/getting-started",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.blog,
+      url: blogUrl,
+    },
+    {
+      children: (
+        <ExternalLink href="https://herouiv3.featurebase.app/roadmap">{nav.roadmap}</ExternalLink>
+      ),
+      on: "nav",
+      type: "custom",
+    },
+  ];
+}
+
+/** @deprecated Use `getHomeLayoutLinks(locale)` for locale-aware navigation. */
+export const homeLayoutLinks = getHomeLayoutLinks("en");
diff --git a/apps/docs/src/app/[lang]/(home)/home-layout-links.tsx b/apps/docs/src/app/[lang]/(home)/home-layout-links.tsx
new file mode 100644
index 0000000..91d579a
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/home-layout-links.tsx
@@ -0,0 +1,111 @@
+import type {LinkItemType} from "@/components/fumadocs/ui/link-item";
+import type {Dictionary} from "@/lib/dictionaries";
+
+import {ExternalLink} from "@/components/external-link";
+import {Iconify} from "@/components/iconify";
+
+export function getHomeLayoutLinks(dict: Dictionary, lang: string = "en"): LinkItemType[] {
+  const nav = dict.nav;
+  const blogUrl = `/${lang}/blog`;
+
+  return [
+    {
+      items: [
+        {
+          icon: <Iconify icon="book" />,
+          text: nav.gettingStarted,
+          url: "/docs/react/getting-started",
+        },
+        {
+          icon: <Iconify icon="palette" />,
+          text: nav.themes,
+          url: "/themes",
+        },
+        {
+          icon: <Iconify icon="circles-4-diamond" />,
+          text: nav.components,
+          url: "/docs/react/components",
+        },
+        {
+          icon: <Iconify icon="smartphone" />,
+          text: nav.reactNative,
+          url: "/docs/native/getting-started",
+        },
+        {
+          icon: <Iconify icon="rocket" />,
+          text: nav.releases,
+          url: "/docs/react/releases",
+        },
+      ],
+      on: "menu",
+      text: nav.documentation,
+      type: "menu",
+    },
+    {
+      items: [
+        {
+          icon: <Iconify icon="pen-line" />,
+          text: nav.blog,
+          url: blogUrl,
+        },
+        {
+          external: true,
+          icon: <Iconify icon="figma" />,
+          text: "Figma",
+          url: "https://www.figma.com/community/file/1546526812159103429",
+        },
+        {
+          external: true,
+          icon: <Iconify icon="route" />,
+          text: nav.roadmap,
+          url: "https://herouiv3.featurebase.app/roadmap",
+        },
+      ],
+      on: "menu",
+      text: nav.resources,
+      type: "menu",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.docs,
+      url: "/docs/react/getting-started",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.themes,
+      url: "/themes",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.components,
+      url: "/docs/react/components",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: (
+        <>
+          <span className="md:hidden">{nav.reactNativeShort}</span>
+          <span className="hidden md:inline">{nav.reactNative}</span>
+        </>
+      ),
+      url: "/docs/native/getting-started",
+    },
+    {
+      active: "nested-url",
+      on: "nav",
+      text: nav.blog,
+      url: blogUrl,
+    },
+    {
+      children: (
+        <ExternalLink href="https://herouiv3.featurebase.app/roadmap">{nav.roadmap}</ExternalLink>
+      ),
+      on: "nav",
+      type: "custom",
+    },
+  ];
+}
diff --git a/apps/docs/src/app/[lang]/(home)/layout.tsx b/apps/docs/src/app/[lang]/(home)/layout.tsx
new file mode 100644
index 0000000..a2eff5e
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/layout.tsx
@@ -0,0 +1,74 @@
+import type {ReactNode} from "react";
+
+import {HomeLayout} from "fumadocs-ui/layouts/home";
+import {notFound} from "next/navigation";
+
+import {baseOptions} from "@/app/[lang]/layout.config";
+import {DesignThemeSelector} from "@/components/design-theme-selector";
+import {LanguageToggleSlot, LanguageToggleText} from "@/components/fumadocs/ui/language-toggle";
+import {SearchToggle} from "@/components/fumadocs/ui/search-toggle";
+import {GitHubLinkSmall} from "@/components/github-link";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+
+import {getHomeLayoutLinks} from "./home-layout-links";
+
+export default async function Layout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{lang: string}>;
+}) {
+  const {lang} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const dict = await getDictionary(lang);
+
+  return (
+    <HomeLayout
+      {...baseOptions}
+      links={[
+        ...getHomeLayoutLinks(dict, lang),
+        {
+          children: (
+            <div className="flex items-center gap-1.5">
+              <DesignThemeSelector />
+              <GitHubLinkSmall />
+            </div>
+          ),
+          on: "nav" as const,
+          secondary: true,
+          type: "custom" as const,
+        },
+        {
+          children: <GitHubLinkSmall />,
+          on: "menu" as const,
+          secondary: true,
+          type: "custom" as const,
+        },
+      ]}
+      searchToggle={{
+        components: {
+          sm: (
+            <>
+              <DesignThemeSelector triggerVariant="ghost" />
+              <SearchToggle hideIfDisabled className="p-2" />
+            </>
+          ),
+        },
+      }}
+      slots={{
+        languageSelect: {
+          root: LanguageToggleSlot,
+          text: LanguageToggleText,
+        },
+      }}
+      themeSwitch={{
+        mode: "light-dark-system",
+      }}
+    >
+      {children}
+    </HomeLayout>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/page.tsx b/apps/docs/src/app/[lang]/(home)/page.tsx
new file mode 100644
index 0000000..5557361
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/page.tsx
@@ -0,0 +1,72 @@
+import {buttonVariants} from "@heroui/react";
+import LinkRoot from "fumadocs-core/link";
+import {notFound} from "next/navigation";
+
+import {Footer} from "@/components/footer";
+import {StarsCount} from "@/components/github-link";
+import {GitHubIcon} from "@/icons/github";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+import {i18n} from "@/lib/i18n";
+
+import {DemoShowcase} from "./components/demo-showcase";
+import {ProBanner} from "./components/pro-banner";
+import {ReleaseBadges} from "./components/release-badges";
+
+export const dynamic = "force-static";
+export const revalidate = false;
+
+export function generateStaticParams() {
+  return i18n.languages.map((lang) => ({lang}));
+}
+
+export default async function HomePage({params}: {params: Promise<{lang: string}>}) {
+  const {lang} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const dict = await getDictionary(lang);
+  const {home} = dict;
+
+  return (
+    <main className="flex min-h-[calc(100vh-4rem)] flex-col">
+      <section className="z-10 flex min-h-0 flex-1 flex-col items-center px-4 pt-12 text-center">
+        <div className="mx-auto flex max-w-2xl flex-col items-center justify-center">
+          <ReleaseBadges badges={home.releaseBadges} />
+          <h1 className="mt-2 text-3xl font-bold tracking-tight text-foreground sm:text-4xl lg:mt-4 lg:text-5xl">
+            {home.titleMain} <div className="text-muted/70">{home.titleMuted}</div>
+          </h1>
+          <p className="text-balance text-muted md:text-lg">{home.description}</p>
+          <div className="mt-4 flex gap-3">
+            <LinkRoot
+              className={buttonVariants({variant: "primary"})}
+              href="/docs/react/getting-started"
+            >
+              {home.getStarted}
+            </LinkRoot>
+            <LinkRoot
+              className={buttonVariants({variant: "outline"})}
+              href="/docs/react/components"
+            >
+              {home.viewComponents}
+            </LinkRoot>
+          </div>
+          <a
+            className="mt-2 flex items-center justify-around gap-2 text-xs text-muted transition-colors hover:text-foreground lg:mt-4"
+            href="https://github.com/heroui-inc/heroui"
+            rel="noopener noreferrer"
+            target="_blank"
+          >
+            <GitHubIcon className="size-4" />
+            <span>
+              {home.githubStarsPrefix} <StarsCount className="p-0 font-normal" />{" "}
+              {home.githubStarsSuffix}
+            </span>
+          </a>
+        </div>
+        <DemoShowcase />
+      </section>
+      <Footer dict={dict.footer} />
+      <ProBanner />
+    </main>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/showcase/layout.tsx b/apps/docs/src/app/[lang]/(home)/showcase/layout.tsx
new file mode 100644
index 0000000..5d3f9e0
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/showcase/layout.tsx
@@ -0,0 +1,30 @@
+import type {ReactNode} from "react";
+
+import {notFound} from "next/navigation";
+
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+
+export default async function ShowcaseLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{lang: string}>;
+}) {
+  const {lang} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const dict = await getDictionary(lang);
+  const {showcase} = dict;
+
+  return (
+    <main className="container mx-auto px-6 py-12">
+      <div className="mx-auto max-w-[68rem]">
+        <h1 className="mb-2 text-4xl font-bold tracking-tight">{showcase.heading}</h1>
+        <p className="mb-12 text-lg font-light text-muted">{showcase.description}</p>
+        {children}
+      </div>
+    </main>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/(home)/showcase/page.tsx b/apps/docs/src/app/[lang]/(home)/showcase/page.tsx
new file mode 100644
index 0000000..e63e95c
--- /dev/null
+++ b/apps/docs/src/app/[lang]/(home)/showcase/page.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {useParams} from "next/navigation";
+
+import {ShowcaseItem} from "@/components/showcase-item";
+import {i18n} from "@/lib/i18n";
+import {getShowcaseCategories} from "@/showcases";
+
+export default function ShowcasePage() {
+  const params = useParams<{lang?: string}>();
+  const lang = params.lang ?? i18n.defaultLanguage;
+  const categories = getShowcaseCategories();
+
+  return (
+    <div className="space-y-12">
+      {categories.map((category) => (
+        <section key={category.name}>
+          <h2 className="text-md mb-4 rounded-full text-foreground">{category.name}</h2>
+          <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+            {category.items.map((item) => (
+              <ShowcaseItem key={item.name} href={`/${lang}/showcase/${item.name}`} item={item} />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/blog/[slug]/page.tsx b/apps/docs/src/app/[lang]/blog/[slug]/page.tsx
new file mode 100644
index 0000000..fc972b7
--- /dev/null
+++ b/apps/docs/src/app/[lang]/blog/[slug]/page.tsx
@@ -0,0 +1,197 @@
+import type {Metadata} from "next";
+
+import {ChevronLeft} from "@gravity-ui/icons";
+import {Chip} from "@heroui/react";
+import {rehypeCode, rehypeCodeDefaultOptions} from "fumadocs-core/mdx-plugins";
+import Link from "next/link";
+import {notFound} from "next/navigation";
+import {compileMDX} from "next-mdx-remote/rsc";
+import remarkGfm from "remark-gfm";
+
+import {ProBanner} from "@/app/[lang]/(home)/components/pro-banner";
+import {DocsImage} from "@/components/docs-image";
+import {siteConfig} from "@/config/site";
+import {getAllBlogPosts, getBlogPost, getRelatedPosts} from "@/lib/blog";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+import {i18n} from "@/lib/i18n";
+import {getTechArticleJsonLd} from "@/lib/json-ld";
+import {getMDXComponents} from "@/mdx-components";
+
+import {PostCard} from "../post-card";
+
+const DATE_LOCALES: Record<string, string> = {
+  cn: "zh-CN",
+  en: "en-US",
+};
+
+interface BlogPostPageProps {
+  params: Promise<{lang: string; slug: string}>;
+}
+
+export async function generateStaticParams() {
+  return i18n.languages.flatMap((lang) =>
+    getAllBlogPosts(lang).map((post) => ({lang, slug: post.slug})),
+  );
+}
+
+export async function generateMetadata({params}: BlogPostPageProps): Promise<Metadata> {
+  const {lang, slug} = await params;
+  const post = getBlogPost(slug, lang);
+
+  if (!post) return {};
+
+  const url = `/${lang}/blog/${slug}`;
+
+  return {
+    alternates: {
+      canonical: url,
+    },
+    description: post.description,
+    openGraph: {
+      authors: [post.author],
+      description: post.description,
+      publishedTime: post.date,
+      title: post.title,
+      type: "article",
+      url,
+      ...(post.image && {images: [post.image]}),
+    },
+    title: post.title,
+    twitter: {
+      card: "summary_large_image",
+      description: post.description,
+      title: post.title,
+      ...(post.image && {images: [post.image]}),
+    },
+  };
+}
+
+export default async function BlogPostPage({params}: BlogPostPageProps) {
+  const {lang, slug} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const post = getBlogPost(slug, lang);
+
+  if (!post) notFound();
+
+  const dict = await getDictionary(lang);
+  const {blog} = dict;
+
+  const {content} = await compileMDX({
+    components: getMDXComponents(),
+    options: {
+      mdxOptions: {
+        rehypePlugins: [[rehypeCode, {...rehypeCodeDefaultOptions}]],
+        remarkPlugins: [remarkGfm],
+      },
+      parseFrontmatter: false,
+    },
+    source: post.content,
+  });
+
+  const postUrl = new URL(`/${lang}/blog/${slug}`, siteConfig.siteUrl).toString();
+  const articleJsonLd = getTechArticleJsonLd({
+    authorName: post.author,
+    authorUrl: post.authorUrl,
+    dateModified: post.date,
+    datePublished: post.date,
+    description: post.description,
+    image: post.image ? new URL(post.image, siteConfig.siteUrl).toString() : undefined,
+    title: post.title,
+    url: postUrl,
+  });
+
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{__html: JSON.stringify(articleJsonLd)}}
+        type="application/ld+json"
+      />
+      <main className="mx-auto w-full max-w-3xl px-6 py-16 sm:px-8">
+        <Link
+          className="button button--tertiary mb-12 -ml-2 inline-flex items-center gap-1"
+          href={`/${lang}/blog`}
+        >
+          <ChevronLeft className="size-4" />
+          {blog.backToBlog}
+        </Link>
+
+        <article>
+          <header className="mb-10">
+            {!!post.draft && (
+              <Chip className="mb-3" color="warning" size="sm" variant="soft">
+                Draft
+              </Chip>
+            )}
+            <h1 className="text-3xl font-bold tracking-tight sm:text-4xl lg:text-5xl">
+              {post.title}
+            </h1>
+            <p className="text-fd-muted-foreground mt-4 text-lg leading-relaxed">
+              {post.description}
+            </p>
+          </header>
+
+          {!!post.image && post.image.startsWith("http") && (
+            <div className="mb-8">
+              <DocsImage alt={post.title} darkSrc={post.darkImage} src={post.image} />
+            </div>
+          )}
+
+          <div className="text-fd-muted-foreground mb-10 flex items-center gap-2 text-sm">
+            {post.authorUrl ? (
+              <a
+                className="group/author hover:text-fd-foreground flex items-center transition-colors"
+                href={post.authorUrl}
+                rel="noopener noreferrer"
+                target="_blank"
+              >
+                {post.authorAvatar ? (
+                  <img
+                    alt=""
+                    className="mr-0 size-0 rounded-full opacity-0 transition-all group-hover/author:mr-2 group-hover/author:size-6 group-hover/author:opacity-100"
+                    src={post.authorAvatar}
+                  />
+                ) : null}
+                <span>{post.author}</span>
+              </a>
+            ) : (
+              <span>{post.author}</span>
+            )}
+            <span>&middot;</span>
+            <time dateTime={post.date}>
+              {new Date(post.date).toLocaleDateString(DATE_LOCALES[lang] ?? "en-US", {
+                day: "numeric",
+                month: "long",
+                year: "numeric",
+              })}
+            </time>
+          </div>
+
+          <div className="prose prose-neutral dark:prose-invert max-w-none [&_pre]:overflow-x-auto [&_table]:overflow-x-auto">
+            {content}
+          </div>
+
+          <ProBanner />
+
+          {(() => {
+            const related = getRelatedPosts(slug, post.tags, 3, lang);
+
+            if (related.length === 0) return null;
+
+            return (
+              <nav aria-label={blog.relatedPosts} className="border-fd-border mt-12 border-t pt-10">
+                <h2 className="mb-6 text-lg font-semibold">{blog.relatedPosts}</h2>
+                <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+                  {related.map((r) => (
+                    <PostCard key={r.slug} compact lang={lang} post={r} />
+                  ))}
+                </div>
+              </nav>
+            );
+          })()}
+        </article>
+      </main>
+    </>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/blog/blog-content.tsx b/apps/docs/src/app/[lang]/blog/blog-content.tsx
new file mode 100644
index 0000000..ee69231
--- /dev/null
+++ b/apps/docs/src/app/[lang]/blog/blog-content.tsx
@@ -0,0 +1,100 @@
+"use client";
+
+import type {BlogPost} from "@/lib/blog";
+import type {Dictionary} from "@/lib/dictionaries";
+
+import {Tag, TagGroup} from "@heroui/react";
+import {parseAsStringLiteral, useQueryState} from "nuqs";
+import {useMemo} from "react";
+
+import {ProBanner} from "@/app/[lang]/(home)/components/pro-banner";
+
+import {PostCard} from "./post-card";
+
+const CATEGORY_VALUES = ["all", "tutorial", "comparison", "native", "ui-libraries"] as const;
+
+type CategoryValue = (typeof CATEGORY_VALUES)[number];
+
+interface BlogContentProps {
+  posts: BlogPost[];
+  lang: string;
+  dict: Dictionary["blog"];
+}
+
+export function BlogContent({dict, lang, posts}: BlogContentProps) {
+  const [activeCategory, setActiveCategory] = useQueryState(
+    "category",
+    parseAsStringLiteral(CATEGORY_VALUES).withDefault("all"),
+  );
+
+  const categories: {label: string; value: CategoryValue}[] = [
+    {label: dict.categories.all, value: "all"},
+    {label: dict.categories.tutorial, value: "tutorial"},
+    {label: dict.categories.comparison, value: "comparison"},
+    {label: dict.categories.native, value: "native"},
+    {label: dict.categories.uiLibraries, value: "ui-libraries"},
+  ];
+
+  const filteredPosts = useMemo(() => {
+    if (activeCategory === "all") return posts;
+
+    return posts.filter((post) => post.tags.includes(activeCategory));
+  }, [posts, activeCategory]);
+
+  const featuredPosts = filteredPosts.slice(0, 2);
+  const latestPosts = filteredPosts.slice(2);
+
+  return (
+    <main className="container mx-auto max-w-6xl px-4 py-16">
+      <div className="mb-10 flex flex-col gap-6 sm:flex-row sm:items-end sm:justify-between">
+        <h1 className="text-4xl font-bold tracking-tight md:text-5xl">{dict.heading}</h1>
+      </div>
+
+      <TagGroup
+        aria-label={dict.categoriesAriaLabel}
+        className="mb-10"
+        selectedKeys={new Set([activeCategory])}
+        selectionMode="single"
+        size="lg"
+        onSelectionChange={(keys) => {
+          const selected = [...keys][0];
+
+          if (selected) setActiveCategory(String(selected) as CategoryValue);
+        }}
+      >
+        <TagGroup.List>
+          {categories.map((cat) => (
+            <Tag key={cat.value} id={cat.value}>
+              {cat.label}
+            </Tag>
+          ))}
+        </TagGroup.List>
+      </TagGroup>
+
+      {featuredPosts.length > 0 && (
+        <div className="mb-14 grid gap-6 md:grid-cols-2">
+          {featuredPosts.map((post) => (
+            <PostCard key={post.slug} featured lang={lang} post={post} />
+          ))}
+        </div>
+      )}
+
+      <ProBanner />
+
+      {latestPosts.length > 0 && (
+        <>
+          <h2 className="mb-6 text-xl font-semibold">{dict.latestPosts}</h2>
+          <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+            {latestPosts.map((post) => (
+              <PostCard key={post.slug} lang={lang} post={post} />
+            ))}
+          </div>
+        </>
+      )}
+
+      {filteredPosts.length === 0 && (
+        <p className="text-fd-muted-foreground py-20 text-center text-lg">{dict.emptyState}</p>
+      )}
+    </main>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/blog/layout.tsx b/apps/docs/src/app/[lang]/blog/layout.tsx
new file mode 100644
index 0000000..3426c8d
--- /dev/null
+++ b/apps/docs/src/app/[lang]/blog/layout.tsx
@@ -0,0 +1,30 @@
+import type {ReactNode} from "react";
+
+import {HomeLayout} from "fumadocs-ui/layouts/home";
+
+import {getHomeLayoutLinks} from "@/app/[lang]/(home)/home-layout-links";
+import {baseOptions} from "@/app/[lang]/layout.config";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+
+export default async function BlogLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{lang: string}>;
+}) {
+  const {lang} = await params;
+  const dict = hasLocale(lang) ? await getDictionary(lang) : await getDictionary("en");
+
+  return (
+    <HomeLayout
+      {...baseOptions}
+      links={getHomeLayoutLinks(dict, lang)}
+      themeSwitch={{
+        mode: "light-dark-system",
+      }}
+    >
+      {children}
+    </HomeLayout>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/blog/page.tsx b/apps/docs/src/app/[lang]/blog/page.tsx
new file mode 100644
index 0000000..820befa
--- /dev/null
+++ b/apps/docs/src/app/[lang]/blog/page.tsx
@@ -0,0 +1,73 @@
+import type {Metadata} from "next";
+
+import {notFound} from "next/navigation";
+import {Suspense} from "react";
+
+import {siteConfig} from "@/config/site";
+import {getAllBlogPosts} from "@/lib/blog";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+import {i18n} from "@/lib/i18n";
+import {getBlogJsonLd} from "@/lib/json-ld";
+
+import {BlogContent} from "./blog-content";
+
+interface BlogPageProps {
+  params: Promise<{lang: string}>;
+}
+
+export function generateStaticParams() {
+  return i18n.languages.map((lang) => ({lang}));
+}
+
+export async function generateMetadata({params}: BlogPageProps): Promise<Metadata> {
+  const {lang} = await params;
+  const dict = hasLocale(lang) ? await getDictionary(lang) : await getDictionary("en");
+  const {blog} = dict;
+
+  return {
+    alternates: {
+      canonical: `/${lang}/blog`,
+    },
+    description: blog.metaDescription,
+    openGraph: {
+      description: blog.metaDescription,
+      title: blog.metaTitle,
+      url: `/${lang}/blog`,
+    },
+    title: blog.metaTitle,
+  };
+}
+
+export default async function BlogPage({params}: BlogPageProps) {
+  const {lang} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const dict = await getDictionary(lang);
+  const posts = getAllBlogPosts(lang);
+  const baseUrl = siteConfig.siteUrl;
+
+  const blogJsonLd = getBlogJsonLd({
+    description: dict.blog.metaDescription,
+    name: dict.blog.metaTitle,
+    posts: posts.map((post) => ({
+      datePublished: post.date,
+      description: post.description,
+      title: post.title,
+      url: new URL(`/${lang}/blog/${post.slug}`, baseUrl).toString(),
+    })),
+    url: new URL(`/${lang}/blog`, baseUrl).toString(),
+  });
+
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{__html: JSON.stringify(blogJsonLd)}}
+        type="application/ld+json"
+      />
+      <Suspense>
+        <BlogContent dict={dict.blog} lang={lang} posts={posts} />
+      </Suspense>
+    </>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/blog/post-card.tsx b/apps/docs/src/app/[lang]/blog/post-card.tsx
new file mode 100644
index 0000000..fc04261
--- /dev/null
+++ b/apps/docs/src/app/[lang]/blog/post-card.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import type {BlogPost} from "@/lib/blog";
+
+import {Chip} from "@heroui/react";
+import Link from "next/link";
+import {useState} from "react";
+
+const TAG_COLORS: Record<string, string> = {
+  admin: "from-slate-500 to-zinc-600",
+  comparison: "from-violet-500 to-fuchsia-500",
+  dashboards: "from-amber-500 to-orange-500",
+  "design-system": "from-pink-500 to-rose-500",
+  ecommerce: "from-yellow-500 to-amber-500",
+  heroui: "from-blue-600 to-violet-600",
+  "landing-page": "from-teal-500 to-cyan-500",
+  native: "from-fuchsia-500 to-pink-600",
+  react: "from-sky-500 to-blue-600",
+  saas: "from-indigo-500 to-blue-500",
+  templates: "from-orange-500 to-red-500",
+  tutorial: "from-emerald-500 to-teal-500",
+  "ui-libraries": "from-blue-500 to-cyan-500",
+};
+
+const DATE_LOCALES: Record<string, string> = {
+  cn: "zh-CN",
+  en: "en-US",
+};
+
+export function getPostGradient(tags: string[]): string {
+  for (const tag of tags) {
+    if (TAG_COLORS[tag]) return TAG_COLORS[tag];
+  }
+
+  return "from-zinc-600 to-zinc-800";
+}
+
+function formatDate(date: string, lang: string) {
+  return new Date(date).toLocaleDateString(DATE_LOCALES[lang] ?? "en-US", {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+  });
+}
+
+export interface PostCardProps {
+  post: BlogPost;
+  lang: string;
+  featured?: boolean;
+  /** Renders a denser version of the card. Use in narrow layouts (e.g. related posts). */
+  compact?: boolean;
+}
+
+export function PostCard({compact = false, featured = false, lang, post}: PostCardProps) {
+  const gradient = getPostGradient(post.tags);
+  const [imgFailed, setImgFailed] = useState(false);
+  const hasExternalImage = post.image && post.image.startsWith("http");
+  const showImage = hasExternalImage && !imgFailed;
+
+  const coverTitleClass = compact ? "px-4 text-xs sm:text-sm" : "px-6 text-lg sm:text-xl";
+
+  return (
+    <Link className="group flex flex-col" href={`/${lang}/blog/${post.slug}`}>
+      <div
+        className={`relative flex items-center justify-center overflow-hidden rounded-2xl ${featured ? "aspect-[2/1]" : "aspect-[16/9]"} ${showImage ? "bg-fd-muted" : `bg-gradient-to-br ${gradient}`}`}
+      >
+        {showImage ? (
+          <img
+            alt={post.title}
+            className="absolute inset-0 size-full object-cover transition-transform duration-300 group-hover:scale-105"
+            src={post.image}
+            onError={() => setImgFailed(true)}
+          />
+        ) : (
+          <span className={`text-center font-bold text-white/90 ${coverTitleClass}`}>
+            {post.title}
+          </span>
+        )}
+        <div className="pointer-events-none absolute inset-0 rounded-2xl ring-1 ring-black/10 ring-inset dark:ring-white/10" />
+        {!!post.draft && (
+          <Chip
+            className="absolute top-3 right-3 shadow-sm"
+            color="warning"
+            size="sm"
+            variant="soft"
+          >
+            Draft
+          </Chip>
+        )}
+      </div>
+      <div className="mt-4 flex flex-col gap-1.5">
+        <h3
+          className={`group-hover:text-fd-primary line-clamp-2 leading-snug font-semibold transition-colors ${featured ? "text-xl" : "text-base"}`}
+        >
+          {post.title}
+        </h3>
+        {!!featured && (
+          <p className="text-fd-muted-foreground line-clamp-2 text-sm">{post.description}</p>
+        )}
+        <div
+          className={`text-fd-muted-foreground mt-1 flex items-center gap-2 ${compact ? "text-xs" : "text-sm"}`}
+        >
+          <span>{post.author}</span>
+          <span>&middot;</span>
+          <time dateTime={post.date}>{formatDate(post.date, lang)}</time>
+        </div>
+      </div>
+    </Link>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/docs/[[...slug]]/layout.tsx b/apps/docs/src/app/[lang]/docs/[[...slug]]/layout.tsx
new file mode 100644
index 0000000..5d1445f
--- /dev/null
+++ b/apps/docs/src/app/[lang]/docs/[[...slug]]/layout.tsx
@@ -0,0 +1,104 @@
+import type {CSSProperties, ReactNode} from "react";
+
+import {Separator} from "@heroui/react";
+
+import {HeaderBanner, ProBanner} from "@/app/[lang]/(home)/components/pro-banner";
+import {SHOW_BANNER} from "@/app/[lang]/(home)/components/pro-constants";
+import {baseOptions} from "@/app/[lang]/layout.config";
+import {DesignThemeSelector} from "@/components/design-theme-selector";
+import {FrameworksTabs} from "@/components/frameworks-tabs";
+import {DocsLayout} from "@/components/fumadocs/layouts/notebook";
+import {ThemeToggle} from "@/components/fumadocs/ui/theme-toggle";
+import {GitHubLinkSmall} from "@/components/github-link";
+import {HeroUILogo} from "@/components/heroui-logo";
+import {VersionSelector} from "@/components/version-selector";
+import {source} from "@/lib/source";
+
+const DOCS_TOP_BANNER_HEIGHT = "2rem";
+
+export default async function Layout({
+  children,
+  params,
+}: {
+  params: Promise<{lang: string}>;
+  children: ReactNode;
+}) {
+  // The top banner is rendered in normal flow, so --fd-banner-height would incorrectly
+  // offset sticky docs elements after the banner scrolls away. Reduce only the docs
+  // viewport height to keep the sidebar scroll area inside the visible viewport.
+  const layoutStyle = SHOW_BANNER
+    ? ({"--fd-docs-height": `calc(100dvh - ${DOCS_TOP_BANNER_HEIGHT})`} as CSSProperties)
+    : undefined;
+
+  const {lang} = await params;
+
+  return (
+    <>
+      <HeaderBanner />
+      <DocsLayout
+        i18n
+        containerProps={{style: layoutStyle}}
+        tabMode="navbar"
+        tree={source.getPageTree(lang)}
+        sidebar={{
+          banner: () => (
+            <div className="flex flex-col items-start justify-center gap-4 px-4 pt-4 sm:hidden">
+              <div className="flex w-full items-center justify-between gap-4 pl-1">
+                <HeroUILogo />
+                <ThemeToggle mode="light-dark-system" />
+              </div>
+              <Separator />
+            </div>
+          ),
+          collapsible: false,
+          defaultOpenLevel: 0,
+          footer: () => (
+            <div className="px-4 pb-4 sm:hidden">
+              <FrameworksTabs />
+            </div>
+          ),
+          headerTabsProps: {
+            children: <FrameworksTabs className="hidden md:flex" />,
+            filterByPathname: true,
+          },
+          tabs: {
+            transform: (tab) => {
+              return {
+                ...tab,
+                title: (
+                  <div
+                    aria-label={typeof tab.title === "string" ? tab.title : ""}
+                    className="flex items-center gap-2"
+                  >
+                    {tab.icon}
+                    <span>{tab.title}</span>
+                  </div>
+                ),
+              };
+            },
+          },
+        }}
+        themeSwitch={{
+          mode: "light-dark-system",
+        }}
+        {...baseOptions}
+        nav={{
+          ...baseOptions.nav,
+          children: (
+            <div className="mr-2 flex items-center gap-3 md:mr-0" id="nd-nav-actions">
+              <DesignThemeSelector />
+              <GitHubLinkSmall />
+            </div>
+          ),
+          mode: "top",
+          title: <HeroUILogo />,
+          titleSuffix: <VersionSelector className="mt-1 hidden lg:flex" />,
+          titleSuffixGap: "gap-4",
+        }}
+      >
+        {children}
+      </DocsLayout>
+      <ProBanner />
+    </>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx
new file mode 100644
index 0000000..f092300
--- /dev/null
+++ b/apps/docs/src/app/[lang]/docs/[[...slug]]/page.tsx
@@ -0,0 +1,209 @@
+import type {StatusChipStatus} from "@/components/status-chip";
+import type {Metadata} from "next";
+
+import {readFile} from "node:fs/promises";
+import {join} from "node:path";
+
+import {createRelativeLink} from "fumadocs-ui/mdx";
+import {notFound} from "next/navigation";
+import {Suspense, cache} from "react";
+
+import {ViewOptions} from "@/components/ai/page-actions";
+import {ComponentLinks} from "@/components/component-links";
+import {ComponentPreview, ComponentPreviewFallback} from "@/components/component-preview";
+import {ComponentsCategory} from "@/components/components-category";
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from "@/components/fumadocs/layouts/notebook/page";
+import {LocaleLink} from "@/components/locale-link";
+import {ComponentsCategory as NativeComponentsCategory} from "@/components/native/components-category";
+import {NewsletterForm} from "@/components/newsletter-form";
+import {PRContributors, fetchPRContributors} from "@/components/pr-contributors";
+import StatusChip from "@/components/status-chip";
+import {siteConfig} from "@/config/site";
+import {getComponentCount, getExampleCount} from "@/demos";
+import {getBreadcrumbJsonLd, getTechArticleJsonLd} from "@/lib/json-ld";
+import {source} from "@/lib/source";
+import {getMDXComponents} from "@/mdx-components";
+import {
+  extractGithubFromMDX,
+  extractImageFromMDX,
+  extractLinksFromMDX,
+} from "@/utils/extract-links";
+// import { getGithubLastEdit } from "fumadocs-core/server";
+
+const componentStatusIcons = ["preview", "new", "updated"];
+
+const getRawMDXContent = cache(async (pagePath: string): Promise<string> => {
+  try {
+    // `page.path` already includes the locale prefix when using
+    // `parser: "dir"`, so we must not prepend the locale again.
+    const filePath = join(process.cwd(), "content/docs", pagePath);
+
+    return await readFile(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+});
+
+export default async function Page(props: {params: Promise<{lang: string; slug?: string[]}>}) {
+  const params = await props.params;
+
+  const page = source.getPage(params.slug, params.lang);
+
+  if (!page) notFound();
+
+  const MDXContent = page.data.body;
+  const isComponentStatusIcon = page.data.icon && componentStatusIcons.includes(page.data.icon);
+
+  // TODO: add github last edit
+  // const lastEditTime = await getGithubLastEdit({
+  //   owner: "heroui-inc",
+  //   repo: "heroui",
+  //   path: `apps/docs/content/docs/${page.path}`,
+  // });
+
+  // Read raw MDX content for frontmatter extraction
+  const rawContent = await getRawMDXContent(page.path);
+
+  // Extract links from MDX content
+  const links = extractLinksFromMDX(rawContent);
+
+  // Extract GitHub info from MDX content
+  const githubInfo = extractGithubFromMDX(rawContent);
+
+  // Fetch PR contributors if github info is available
+  const contributors = githubInfo?.pull ? await fetchPRContributors(githubInfo.pull) : undefined;
+
+  const slugParts = params.slug ?? [];
+  const pageUrl = `/docs/${slugParts.join("/")}`;
+
+  const breadcrumbItems = [
+    {name: "Home", url: "https://heroui.com"},
+    {name: "Docs", url: "https://heroui.com/docs"},
+    ...slugParts.map((segment, i) => ({
+      name: segment.charAt(0).toUpperCase() + segment.slice(1).replace(/-/g, " "),
+      url: `https://heroui.com/docs/${slugParts.slice(0, i + 1).join("/")}`,
+    })),
+  ];
+
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{__html: JSON.stringify(getBreadcrumbJsonLd(breadcrumbItems))}}
+        type="application/ld+json"
+      />
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: JSON.stringify(
+            getTechArticleJsonLd({
+              description: page.data.description ?? "",
+              title: page.data.title,
+              url: `https://heroui.com${pageUrl}`,
+            }),
+          ),
+        }}
+      />
+      <DocsPage
+        full={page.data.full}
+        toc={page.data.toc}
+        // TODO: add github last edit
+        // lastUpdate={lastEditTime}
+        tableOfContent={{
+          footer: <NewsletterForm />,
+          style: "normal",
+        }}
+      >
+        <section className="flex flex-col gap-2">
+          <div className="flex flex-wrap items-center justify-between gap-2">
+            <DocsTitle className="flex items-center gap-2">
+              {page.data.title}
+              {!!isComponentStatusIcon && (
+                <StatusChip className="w-fit" status={page.data.icon as StatusChipStatus} />
+              )}
+            </DocsTitle>
+            {page.data.toc.length > 0 && (
+              <div className="flex items-center gap-2">
+                <ViewOptions markdownUrl={`${page.url}.mdx`} />
+              </div>
+            )}
+          </div>
+          <DocsDescription className="text-md mt-2 mb-4">{page.data.description}</DocsDescription>
+          {!!links && <ComponentLinks links={links} />}
+        </section>
+        <DocsBody className="prose-sm">
+          <MDXContent
+            components={getMDXComponents({
+              ComponentCount: () => <>{getComponentCount(params.lang)}</>,
+              ComponentPreview: (props) => (
+                <Suspense fallback={<ComponentPreviewFallback />}>
+                  <ComponentPreview {...props} locale={params.lang} />
+                </Suspense>
+              ),
+              ComponentsCategory: (props) => <ComponentsCategory {...props} locale={params.lang} />,
+              ExampleCount: () => <>{getExampleCount(params.lang)}</>,
+              NativeComponentsCategory: (props) => (
+                <NativeComponentsCategory {...props} locale={params.lang} />
+              ),
+              PRContributors: () => (
+                <PRContributors contributors={contributors} github={githubInfo ?? undefined} />
+              ),
+
+              // this allows you to link to other pages with relative file paths
+              a: createRelativeLink(source, page, LocaleLink),
+            })}
+          />
+        </DocsBody>
+      </DocsPage>
+    </>
+  );
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{lang: string; slug?: string[]}>;
+}): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug, params.lang);
+
+  if (!page) notFound();
+
+  // Read raw MDX to extract image from frontmatter
+  const rawContent = await getRawMDXContent(page.path);
+  const frontmatterImage = extractImageFromMDX(rawContent);
+
+  // Determine image URL
+  const image = frontmatterImage || ["/og", ...(params.slug ?? []), "image.png"].join("/");
+
+  // Ensure absolute URL for Open Graph
+  const imageUrl = image.startsWith("http") ? image : new URL(image, siteConfig.siteUrl).toString();
+
+  const url = `/docs/${(params.slug ?? []).join("/")}`;
+
+  return {
+    alternates: {
+      canonical: url,
+    },
+    description: page.data.description,
+    openGraph: {
+      description: page.data.description,
+      images: imageUrl,
+      title: page.data.title,
+      url,
+    },
+    title: page.data.title,
+    twitter: {
+      card: "summary_large_image",
+      images: imageUrl,
+    },
+  };
+}
+
+export async function generateStaticParams() {
+  return source
+    .generateParams("slug", "lang")
+    .filter((param) => param.slug && param.slug.length > 0);
+}
diff --git a/apps/docs/src/app/[lang]/layout.config.tsx b/apps/docs/src/app/[lang]/layout.config.tsx
new file mode 100644
index 0000000..449876a
--- /dev/null
+++ b/apps/docs/src/app/[lang]/layout.config.tsx
@@ -0,0 +1,19 @@
+import type {BaseLayoutProps} from "fumadocs-ui/layouts/shared";
+
+import {HeroUILogo} from "@/components/heroui-logo";
+
+export {getHomeLayoutLinks} from "./(home)/home-layout-links";
+
+/**
+ * Shared layout configurations
+ *
+ * you can customise layouts individually from:
+ * Home Layout: app/(home)/layout.tsx
+ * Docs Layout: app/docs/layout.tsx
+ */
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: <HeroUILogo />,
+    transparentMode: "always",
+  },
+};
diff --git a/apps/docs/src/app/[lang]/layout.tsx b/apps/docs/src/app/[lang]/layout.tsx
new file mode 100644
index 0000000..1ca3d18
--- /dev/null
+++ b/apps/docs/src/app/[lang]/layout.tsx
@@ -0,0 +1,158 @@
+import type {Metadata, Viewport} from "next";
+import type {ReactNode} from "react";
+
+import {Analytics} from "@vercel/analytics/next";
+import {NextProvider} from "fumadocs-core/framework/next";
+import {TreeContextProvider} from "fumadocs-ui/contexts/tree";
+import {Inter} from "next/font/google";
+import {NuqsAdapter} from "nuqs/adapters/next/app";
+
+import {siteConfig} from "@/config/site";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+import {getOrganizationJsonLd, getSoftwareApplicationJsonLd, getWebSiteJsonLd} from "@/lib/json-ld";
+import {source} from "@/lib/source";
+import {__BASE_URL__} from "@/utils/env";
+
+import {CustomRootProvider} from "../custom-root-provider";
+
+import "../global.css";
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+});
+
+export default async function Layout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{lang: string}>;
+}) {
+  const {lang} = await params;
+  const dict = hasLocale(lang) ? await getDictionary(lang) : await getDictionary("en");
+
+  return (
+    <html suppressHydrationWarning className={inter.variable} lang={lang}>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{__html: JSON.stringify(getOrganizationJsonLd())}}
+          type="application/ld+json"
+        />
+        <script
+          dangerouslySetInnerHTML={{__html: JSON.stringify(getWebSiteJsonLd())}}
+          type="application/ld+json"
+        />
+        <script
+          dangerouslySetInnerHTML={{__html: JSON.stringify(getSoftwareApplicationJsonLd())}}
+          type="application/ld+json"
+        />
+      </head>
+      <body className="flex min-h-screen flex-col font-sans">
+        <NuqsAdapter>
+          <NextProvider>
+            <TreeContextProvider tree={source.getPageTree(lang)}>
+              <CustomRootProvider dict={dict} lang={lang}>
+                {children}
+              </CustomRootProvider>
+            </TreeContextProvider>
+          </NextProvider>
+        </NuqsAdapter>
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+
+export const metadata: Metadata = {
+  alternates: {
+    canonical: __BASE_URL__.toString(),
+    types: {
+      "application/rss+xml": [
+        {
+          title: "HeroUI RSS Feed",
+          url: "/rss.xml",
+        },
+      ],
+    },
+  },
+  authors: siteConfig.authors,
+  creator: siteConfig.creator,
+  description: siteConfig.description,
+  icons: [
+    {
+      rel: "icon",
+      type: "image/svg",
+      url: "/icons/favicon.svg",
+    },
+    {
+      rel: "apple-touch-icon",
+      type: "image/png",
+      url: "/icons/apple-touch-icon.png",
+    },
+  ],
+  keywords: [
+    "React",
+    "Next.js",
+    "NextUI",
+    "Tailwind CSS",
+    "HeroUI",
+    "React Aria",
+    "Server Components",
+    "React Components",
+    "UI Components",
+    "UI Kit",
+    "UI Library",
+    "UI Framework",
+    "UI Design System",
+    "React UI library",
+    "React component library",
+    "Tailwind CSS components",
+    "accessible React components",
+    "React design system",
+    "best React UI library",
+    "React UI kit",
+    "shadcn alternative",
+    "MUI alternative",
+    "Chakra UI alternative",
+  ],
+  metadataBase: __BASE_URL__,
+  openGraph: {
+    description: siteConfig.description,
+    images: [
+      {
+        alt: siteConfig.name,
+        url: siteConfig.ogImage,
+      },
+    ],
+    locale: "en_US",
+    siteName: siteConfig.fullName,
+    type: "website",
+    url: __BASE_URL__.toString(),
+  },
+  robots: {
+    follow: true,
+    index: true,
+  },
+  title: {
+    default: siteConfig.fullName,
+    template: `%s | ${siteConfig.name}`,
+  },
+  twitter: {
+    card: "summary_large_image",
+    creator: "@hero_ui",
+    description: siteConfig.description,
+    images: [siteConfig.ogImage],
+    title: siteConfig.fullName,
+  },
+};
+
+export const viewport: Viewport = {
+  initialScale: 1,
+  maximumScale: 5,
+  themeColor: [
+    {color: "#f4f4f5", media: "(prefers-color-scheme: light)"},
+    {color: "#111111", media: "(prefers-color-scheme: dark)"},
+  ],
+  width: "device-width",
+};
diff --git a/apps/docs/src/app/[lang]/not-found.tsx b/apps/docs/src/app/[lang]/not-found.tsx
new file mode 100644
index 0000000..44dc4ae
--- /dev/null
+++ b/apps/docs/src/app/[lang]/not-found.tsx
@@ -0,0 +1,55 @@
+import LinkRoot from "fumadocs-core/link";
+import {HomeLayout} from "fumadocs-ui/layouts/home";
+import Image from "next/image";
+
+import {Footer} from "@/components/footer";
+import {getDictionary, getRequestLocale} from "@/lib/dictionaries";
+
+import {getHomeLayoutLinks} from "./(home)/home-layout-links";
+import {baseOptions} from "./layout.config";
+
+export default async function NotFound() {
+  const locale = await getRequestLocale();
+  const dict = await getDictionary(locale);
+  const {notFound} = dict;
+
+  return (
+    <HomeLayout
+      {...baseOptions}
+      i18n
+      links={getHomeLayoutLinks(dict, locale)}
+      themeSwitch={{
+        mode: "light-dark-system",
+      }}
+    >
+      <div className="mt-12 flex h-full flex-col items-center justify-center text-center md:mt-24">
+        <div className="relative h-[275px] w-full max-w-[658px]">
+          <Image
+            priority
+            alt={notFound.imageAlt}
+            className="absolute inset-0 block h-full w-full object-cover dark:hidden"
+            height={275}
+            quality={100}
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/404_@2x.png"
+            width={658}
+          />
+          <Image
+            priority
+            alt={notFound.imageAlt}
+            className="absolute inset-0 hidden h-full w-full object-cover dark:block"
+            height={275}
+            quality={100}
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/404-dark_@2x.png"
+            width={658}
+          />
+        </div>
+        <h2 className="text-4xl font-bold">{notFound.title}</h2>
+        <p className="mt-2 max-w-sm text-balance text-muted">{notFound.description}</p>
+        <LinkRoot className="button button--tertiary mt-4" href={`/${locale}`}>
+          {notFound.returnHome}
+        </LinkRoot>
+      </div>
+      <Footer dict={dict.footer} />
+    </HomeLayout>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/page.tsx b/apps/docs/src/app/[lang]/showcase/[id]/page.tsx
new file mode 100644
index 0000000..25e3582
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/page.tsx
@@ -0,0 +1,97 @@
+import type {Metadata} from "next";
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {notFound} from "next/navigation";
+
+import {ShowcaseSource} from "@/components/showcase-source";
+import {hasLocale} from "@/lib/dictionaries";
+import {i18n} from "@/lib/i18n";
+import {getAllShowcases, getShowcase} from "@/showcases";
+
+import {ShowcaseCodePanel} from "./showcase-code-panel";
+import {ShowcaseDetailClient} from "./showcase-detail-client";
+import {ShowcaseWrapper} from "./showcase-wrapper";
+
+interface ShowcasePageProps {
+  params: Promise<{
+    lang: string;
+    id: string;
+  }>;
+}
+
+// Force static rendering for showcase pages
+export const dynamic = "force-static";
+
+export async function generateMetadata({params}: ShowcasePageProps): Promise<Metadata> {
+  const {id, lang} = await params;
+  const showcase = getShowcase(id);
+
+  if (!showcase) return {};
+
+  return {
+    alternates: {
+      canonical: `/${lang}/showcase/${id}`,
+    },
+    description: `Interactive demo of ${showcase.name} built with HeroUI components.`,
+    openGraph: {
+      description: `Interactive demo of ${showcase.name} built with HeroUI components.`,
+      title: `${showcase.name} - HeroUI Showcase`,
+      url: `/${lang}/showcase/${id}`,
+    },
+    title: `${showcase.name} - HeroUI Showcase`,
+  };
+}
+
+export async function generateStaticParams() {
+  const showcases = getAllShowcases();
+
+  return i18n.languages.flatMap((lang) =>
+    showcases.map((showcase) => ({
+      id: showcase.name,
+      lang,
+    })),
+  );
+}
+
+export default async function ShowcasePage({params}: ShowcasePageProps) {
+  const {id, lang} = await params;
+
+  if (!hasLocale(lang)) notFound();
+
+  const showcase = getShowcase(id);
+
+  if (!showcase) {
+    notFound();
+  }
+
+  // Get the source code for the showcase
+  let sourceCode = "";
+
+  if (showcase.file && showcase.category) {
+    try {
+      const category = showcase.category.toLowerCase();
+      const filePath = path.join(process.cwd(), "src", "showcases", category, showcase.file);
+
+      sourceCode = await fs.readFile(filePath, "utf-8");
+    } catch (error) {
+      console.error("Failed to read showcase file:", error);
+    }
+  }
+
+  const codePanel = (
+    <ShowcaseCodePanel fileName={`${id}.tsx`} sourceCode={sourceCode}>
+      <ShowcaseSource showLineNumbers allowCopy={false} language="tsx" name={id} />
+    </ShowcaseCodePanel>
+  );
+
+  return (
+    <ShowcaseWrapper
+      defaultTheme={showcase.defaultTheme}
+      supportsThemeSwitching={showcase.supportsThemeSwitching}
+    >
+      <ShowcaseDetailClient codePanel={codePanel} showcase={showcase} showcaseId={id} />
+    </ShowcaseWrapper>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-code-panel.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-code-panel.tsx
new file mode 100644
index 0000000..4cb9427
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-code-panel.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import type {ReactNode} from "react";
+
+import {CodePanel} from "@/components/code-panel";
+import {useCodePanel} from "@/hooks/use-code-panel";
+
+interface ShowcaseCodePanelProps {
+  children: ReactNode;
+  className?: string;
+  sourceCode?: string;
+  fileName?: string;
+}
+
+export function ShowcaseCodePanel({
+  children,
+  className,
+  fileName,
+  sourceCode,
+}: ShowcaseCodePanelProps) {
+  const {isCodeVisible, toggleCode} = useCodePanel();
+
+  return (
+    <CodePanel
+      className={className}
+      fileName={fileName}
+      isVisible={isCodeVisible}
+      sourceCode={sourceCode}
+      title="Source code"
+      onClose={toggleCode}
+    >
+      {children}
+    </CodePanel>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-detail-client.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-detail-client.tsx
new file mode 100644
index 0000000..f39737f
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-detail-client.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import type {ShowcaseItem as ShowcaseItemType} from "@/showcases";
+import type {UrlObject} from "url";
+
+import {chipVariants} from "@heroui/react";
+import LinkRoot from "next/link";
+import {useParams, useSearchParams} from "next/navigation";
+import {Suspense} from "react";
+import {tv} from "tailwind-variants";
+
+import {ShowcaseItem} from "@/components/showcase-item";
+import {ShowcasePreview} from "@/components/showcase-preview";
+import {i18n} from "@/lib/i18n";
+import {getAllShowcases} from "@/showcases";
+import {cn} from "@/utils/cn";
+
+import {ShowcaseHeader} from "./showcase-header";
+
+const dotBackground = tv({
+  base: [
+    "pointer-events-none absolute inset-0 z-[0] h-full w-full bg-transparent [background-size:16px_16px]",
+    // light
+    "bg-[radial-gradient(rgba(0,0,0,0.1)_1px,transparent_1px)] [mask-image:radial-gradient(ellipse_70%_60%_at_50%_50%,#ffffff_60%,transparent_100%)]",
+    // dark
+    "dark:bg-[radial-gradient(rgba(255,255,255,0.1)_1px,transparent_1px)] dark:[mask-image:radial-gradient(ellipse_100%_54%_at_50%_50%,#000_60%,transparent_100%)]",
+  ],
+});
+
+interface ShowcaseDetailClientProps {
+  showcaseId: string;
+  showcase: ShowcaseItemType & {category: string};
+  codePanel: React.ReactNode;
+}
+
+function ShowcasesList({showcaseId}: {showcaseId: string}) {
+  const params = useParams<{lang?: string}>();
+  const lang = params.lang ?? i18n.defaultLanguage;
+  const searchParams = useSearchParams();
+  const allShowcases = getAllShowcases();
+  const returnUrl = searchParams.get("returnUrl");
+  const queryString = returnUrl ? `?returnUrl=${encodeURIComponent(returnUrl)}` : "";
+
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-3 p-4">
+      {allShowcases.map((item) => (
+        <ShowcaseItem
+          key={item.name}
+          isMinimal
+          aria-label={item.title}
+          href={`/${lang}/showcase/${item.name}${queryString}`}
+          isSelected={item.name === showcaseId}
+          item={item}
+        />
+      ))}
+    </div>
+  );
+}
+
+export function ShowcaseDetailClient({codePanel, showcase, showcaseId}: ShowcaseDetailClientProps) {
+  return (
+    <section className="relative flex min-h-screen w-screen flex-col overflow-hidden bg-background text-foreground">
+      <div aria-hidden="true" className={dotBackground()} />
+
+      {/* Header */}
+      <Suspense fallback={null}>
+        <ShowcaseHeader />
+      </Suspense>
+
+      {/* Main content - horizontal layout */}
+      <main className="z-[1] flex flex-1 flex-col">
+        <div className="flex flex-1">
+          {/* Preview Section */}
+          <div className="flex flex-1 items-center justify-center px-4 py-8">
+            <div className="flex h-full max-h-full w-full max-w-5xl flex-col items-center justify-center">
+              <ShowcasePreview fullWidth name={showcaseId} />
+            </div>
+            {codePanel}
+          </div>
+
+          {/* Showcase List Section - Right Side */}
+          <div className="hidden w-24 md:block">
+            <Suspense fallback={null}>
+              <ShowcasesList showcaseId={showcaseId} />
+            </Suspense>
+          </div>
+        </div>
+
+        {/* Footer */}
+        <footer className="z-[1] bg-background/50 backdrop-blur-sm">
+          <div className="jutify-center mx-auto flex max-w-7xl flex-col flex-wrap items-center px-6 py-4 md:flex-row md:flex-nowrap md:justify-between">
+            {/* Left section - Author info */}
+            <div className="order-2 flex-1 md:order-1">
+              <p className="text-center text-sm text-muted/70 md:text-left">
+                By{" "}
+                {showcase.author?.link ? (
+                  <a
+                    className="transition-colors hover:text-muted"
+                    href={showcase.author?.link}
+                    rel="noopener noreferrer"
+                    target="_blank"
+                  >
+                    {showcase.author.name} <span>@{showcase.author.username}</span>
+                  </a>
+                ) : (
+                  <>
+                    {showcase.author?.name} <span>@{showcase.author?.username}</span>
+                  </>
+                )}
+              </p>
+            </div>
+
+            {/* Center - Show used components */}
+            <div className="order-1 my-2 flex flex-1 items-center justify-center gap-2 md:order-2 md:my-0">
+              {showcase.components.map((component) => (
+                <LinkRoot
+                  key={component}
+                  className={cn(
+                    chipVariants({
+                      class: "rounded-full text-muted hover:bg-default/50",
+                      variant: "tertiary",
+                    }),
+                  )}
+                  href={
+                    `/docs/react/components/${component.toLowerCase().replace(/group$/, "-group")}` as unknown as UrlObject
+                  }
+                >
+                  {component}
+                </LinkRoot>
+              ))}
+            </div>
+
+            <div className="order-3 flex-1 text-center md:text-right">
+              <p className="text-sm text-muted/70">{showcase.title}</p>
+            </div>
+          </div>
+        </footer>
+      </main>
+    </section>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-header.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-header.tsx
new file mode 100644
index 0000000..95bfc07
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-header.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import {
+  Button,
+  KbdContent,
+  KbdRoot,
+  TooltipArrow,
+  TooltipContent,
+  TooltipRoot,
+  TooltipTrigger,
+} from "@heroui/react";
+import {useParams, useRouter, useSearchParams} from "next/navigation";
+import {useEffect} from "react";
+
+import {HeroUILogo} from "@/components/heroui-logo";
+import {Iconify} from "@/components/iconify";
+import {useCodePanel} from "@/hooks/use-code-panel";
+import {i18n} from "@/lib/i18n";
+
+import {ShowcaseThemeSwitch} from "./showcase-theme-switch";
+
+export function ShowcaseHeader() {
+  const router = useRouter();
+  const params = useParams<{lang?: string}>();
+  const searchParams = useSearchParams();
+  const {isCodeVisible, toggleCode} = useCodePanel();
+  const lang = params.lang ?? i18n.defaultLanguage;
+
+  // Get the returnUrl parameter, default to the locale-aware showcase listing
+  const returnUrl = searchParams.get("returnUrl") || `/${lang}/showcase`;
+
+  const onClose = () => {
+    router.push(returnUrl as any);
+  };
+
+  useEffect(() => {
+    const handleEscKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        onClose();
+      }
+    };
+
+    document.addEventListener("keydown", handleEscKey);
+
+    return () => {
+      document.removeEventListener("keydown", handleEscKey);
+    };
+  }, [returnUrl]);
+
+  return (
+    <header className="z-[1] flex items-center justify-between bg-background/50 p-4 backdrop-blur-sm">
+      <div className="flex flex-1 justify-start">
+        <TooltipRoot delay={0}>
+          <TooltipTrigger>
+            <Button isIconOnly aria-label="Close" variant="secondary" onPress={onClose}>
+              <Iconify className="text-foreground/70" icon="xmark" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent className="px-2 py-0.5 text-xs text-muted" offset={7} placement="bottom">
+            <TooltipArrow />
+            Press{" "}
+            <KbdRoot>
+              <KbdContent className="text-xs">Esc</KbdContent>
+            </KbdRoot>{" "}
+            to close
+          </TooltipContent>
+        </TooltipRoot>
+      </div>
+      <div className="flex flex-1 items-center justify-center">
+        <HeroUILogo className="text-foreground/20" />
+      </div>
+      <div className="flex flex-1 items-center justify-end gap-2">
+        <ShowcaseThemeSwitch />
+        <TooltipRoot delay={1500}>
+          <TooltipTrigger>
+            <Button
+              isIconOnly
+              aria-label="Toggle showcase code"
+              variant={isCodeVisible ? "primary" : "secondary"}
+              onPress={toggleCode}
+            >
+              <Iconify className={isCodeVisible ? "" : "text-foreground/70"} icon="code" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent offset={7}>
+            <TooltipArrow />
+            <p className="text-xs text-muted">{isCodeVisible ? "Hide code" : "Show code"}</p>
+          </TooltipContent>
+        </TooltipRoot>
+        {/* TODO: Add this later */}
+        {/* <Button isIconOnly aria-label="Open showcase in new tab" variant="secondary">
+          <Iconify className="text-foreground/70" icon="arrow-up-right-from-square" />
+        </Button> */}
+      </div>
+    </header>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-switch.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-switch.tsx
new file mode 100644
index 0000000..82596e4
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-switch.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {Button, TooltipArrow, TooltipContent, TooltipRoot, TooltipTrigger} from "@heroui/react";
+import React from "react";
+
+import {Iconify} from "@/components/iconify";
+import {useIsMounted} from "@/hooks/use-is-mounted";
+import {cn} from "@/utils/cn";
+
+import {useShowcase} from "./showcase-wrapper";
+
+export function ShowcaseThemeSwitch() {
+  const {setShowcaseTheme, showcaseTheme, supportsThemeSwitching} = useShowcase();
+  const isMounted = useIsMounted();
+  const isDisabled = !supportsThemeSwitching;
+
+  if (!isMounted) {
+    return (
+      <Button
+        isIconOnly
+        aria-label="Toggle showcase theme"
+        className="border-none"
+        isDisabled={isDisabled}
+        variant="tertiary"
+      >
+        <div className="relative h-5 w-5">
+          <Iconify className="h-5 w-5 text-foreground/70" icon="sun" />
+        </div>
+      </Button>
+    );
+  }
+
+  const isDark = showcaseTheme === "dark";
+
+  const onPress = () => {
+    if (!isDisabled) {
+      setShowcaseTheme(isDark ? "light" : "dark");
+    }
+  };
+
+  // Determine the tooltip content based on whether switching is disabled
+  const tooltipContent = isDisabled
+    ? "Theme switching not supported for this showcase"
+    : "Toggle theme";
+
+  return (
+    <TooltipRoot delay={1500}>
+      <TooltipTrigger>
+        <Button
+          isIconOnly
+          aria-label="Toggle showcase theme"
+          className={cn("border-none", isDisabled && "cursor-not-allowed opacity-50")}
+          isDisabled={isDisabled}
+          variant="secondary"
+          onPress={onPress}
+        >
+          <Iconify className="m-0 text-foreground/70" icon={isDark ? "moon" : "sun"} />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent offset={7}>
+        <TooltipArrow />
+        <p className="text-xs text-muted">{tooltipContent}</p>
+      </TooltipContent>
+    </TooltipRoot>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-wrapper.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-wrapper.tsx
new file mode 100644
index 0000000..31623ba
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-theme-wrapper.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import type {Theme} from "@/showcases";
+
+import React, {createContext, useContext, useEffect, useState} from "react";
+
+interface ShowcaseThemeContextType {
+  showcaseTheme: Theme;
+  setShowcaseTheme: (theme: Theme) => void;
+  supportsThemeSwitching: boolean;
+}
+
+const ShowcaseThemeContext = createContext<ShowcaseThemeContextType | undefined>(undefined);
+
+export function useShowcaseTheme() {
+  const context = useContext(ShowcaseThemeContext);
+
+  if (!context) {
+    throw new Error("useShowcaseTheme must be used within ShowcaseThemeWrapper");
+  }
+
+  return context;
+}
+
+interface ShowcaseThemeWrapperProps {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  supportsThemeSwitching?: boolean;
+}
+
+export function ShowcaseThemeWrapper({
+  children,
+  defaultTheme = "light",
+  supportsThemeSwitching = true,
+}: ShowcaseThemeWrapperProps) {
+  const [showcaseTheme, setShowcaseTheme] = useState<Theme>(defaultTheme);
+
+  useEffect(() => {
+    // Set the showcase theme as a data attribute on the showcase container
+    const showcaseElement = document.querySelector("[data-showcase-theme]");
+
+    if (showcaseElement) {
+      showcaseElement.setAttribute("data-showcase-theme", showcaseTheme);
+    }
+  }, [showcaseTheme]);
+
+  return (
+    <ShowcaseThemeContext
+      value={{
+        setShowcaseTheme,
+        showcaseTheme,
+        supportsThemeSwitching,
+      }}
+    >
+      <div className={showcaseTheme} data-showcase-theme={showcaseTheme}>
+        {children}
+      </div>
+    </ShowcaseThemeContext>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/showcase/[id]/showcase-wrapper.tsx b/apps/docs/src/app/[lang]/showcase/[id]/showcase-wrapper.tsx
new file mode 100644
index 0000000..428d20c
--- /dev/null
+++ b/apps/docs/src/app/[lang]/showcase/[id]/showcase-wrapper.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Theme} from "@/showcases";
+
+import React, {createContext, useContext, useEffect, useMemo, useState} from "react";
+
+import {CodePanelProvider} from "@/hooks/use-code-panel";
+
+interface ShowcaseContextType {
+  showcaseTheme: Theme;
+  setShowcaseTheme: (theme: Theme) => void;
+  supportsThemeSwitching: boolean;
+}
+
+const ShowcaseContext = createContext<ShowcaseContextType | undefined>(undefined);
+
+export function useShowcase() {
+  const context = useContext(ShowcaseContext);
+
+  if (!context) {
+    throw new Error("useShowcase must be used within ShowcaseWrapper");
+  }
+
+  return context;
+}
+
+interface ShowcaseWrapperProps {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  supportsThemeSwitching?: boolean;
+}
+
+export function ShowcaseWrapper({
+  children,
+  defaultTheme = "light",
+  supportsThemeSwitching = true,
+}: ShowcaseWrapperProps) {
+  const [showcaseTheme, setShowcaseTheme] = useState<Theme>(defaultTheme);
+
+  useEffect(() => {
+    // Set the showcase theme as a data attribute on the showcase container
+    const showcaseElement = document.querySelector("[data-showcase-theme]");
+
+    if (showcaseElement) {
+      showcaseElement.setAttribute("data-showcase-theme", showcaseTheme);
+    }
+  }, [showcaseTheme]);
+
+  const value = useMemo(
+    () => ({
+      setShowcaseTheme,
+      showcaseTheme,
+      supportsThemeSwitching,
+    }),
+    [showcaseTheme, supportsThemeSwitching],
+  );
+
+  return (
+    <CodePanelProvider>
+      <ShowcaseContext value={value}>
+        <div className={showcaseTheme} data-showcase-theme={showcaseTheme}>
+          {children}
+        </div>
+      </ShowcaseContext>
+    </CodePanelProvider>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/accent-color-selector.tsx b/apps/docs/src/app/[lang]/themes/components/accent-color-selector.tsx
new file mode 100644
index 0000000..eb0c68c
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/accent-color-selector.tsx
@@ -0,0 +1,100 @@
+"use client";
+
+import type {Color} from "@/components/color-picker";
+
+import {Button, cn} from "@heroui/react";
+import {formatHsl} from "culori";
+import {useMemo} from "react";
+
+import ColorPicker, {ColorSlider} from "@/components/color-picker";
+import {getHueFromColor, getValuesFromOklch} from "@/components/color-picker/utils/color-format";
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {useVariablesState} from "../hooks/use-variables-state";
+
+import {LockableLabel} from "./lockable-label";
+
+export function AccentColorSelector() {
+  const [variables, setVariables] = useVariablesState();
+  const {chroma, hue, lightness} = variables;
+  const dict = useDictionary().themeBuilder.accentColor;
+  const oklchColor = `oklch(${lightness} ${chroma} ${hue})`;
+
+  const trackBackground = useMemo(() => {
+    // const displayChroma = Math.max(0.2, chroma);
+
+    // Build gradient with the current chroma level for accurate representation
+    const gradientStops = [
+      24, 48, 72, 96, 120, 144, 168, 192, 216, 240, 264, 288, 312, 336, 360, 24,
+    ]
+      .map((h) => `oklch(${lightness} ${chroma} ${h})`)
+      .join(", ");
+
+    return `linear-gradient(to right, ${gradientStops})`;
+  }, [lightness, chroma]);
+
+  const value = formatHsl(oklchColor) ?? "hsl(253.67, 100%, 61.99%)";
+
+  const handleHueSliderChange = (color: Color) => {
+    setVariables({
+      ...variables,
+      hue: getHueFromColor(color),
+    });
+  };
+
+  const handleColorChange = (color: Color) => {
+    const hsl = color.toString("hsl");
+    const {chroma, hue, lightness} = getValuesFromOklch(hsl);
+
+    setVariables({
+      ...variables,
+      chroma,
+      hue,
+      lightness,
+    });
+  };
+
+  return (
+    <div className="flex flex-col gap-1">
+      <LockableLabel label={dict.label} tooltip={dict.tooltip} variable="hue" />
+      <div className="flex flex-row items-center gap-2 overflow-visible">
+        <ColorSlider
+          channel="hue"
+          className="h-6 w-[128px] xl:w-[160px]"
+          thumbBackground={oklchColor}
+          trackBackground={trackBackground}
+          value={value}
+          onChange={handleHueSliderChange}
+        />
+        <ColorPicker
+          showSwatches
+          showAlpha={false}
+          value={value}
+          trigger={
+            <Button
+              isIconOnly
+              className="group relative flex size-6 min-h-0 min-w-0 items-center overflow-visible rounded-full p-0"
+              variant="ghost"
+            >
+              {/* Pastel gradient to indicate custom color picker */}
+              <div
+                className={cn("z-0 size-full rounded-full")}
+                style={{
+                  background:
+                    "conic-gradient(from 0deg, #F8AECF, #FBC7A3, #F7E8A4, #D7F5B0, #B5F3D2, #A3EAF7, #A8C9FF, #C9B8FF, #F8AECF)",
+                }}
+              />
+              <div
+                className={cn("absolute inset-0 z-10 rounded-full border-2 border-white/50")}
+                style={{
+                  background: "transparent",
+                }}
+              />
+            </Button>
+          }
+          onChange={handleColorChange}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/base-color-slider.tsx b/apps/docs/src/app/[lang]/themes/components/base-color-slider.tsx
new file mode 100644
index 0000000..b60b18b
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/base-color-slider.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {useVariablesState} from "../hooks/use-variables-state";
+
+import {ChromaSlider} from "./chroma-slider";
+import {LockableLabel} from "./lockable-label";
+
+export function BaseColorSlider() {
+  const [variables, setVariables] = useVariablesState();
+  const {base, hue} = variables;
+  const dict = useDictionary().themeBuilder.baseColor;
+
+  const handleBaseSliderChange = (value: number) => {
+    setVariables({
+      ...variables,
+      base: value,
+    });
+  };
+
+  return (
+    <div className="flex flex-col gap-1">
+      <LockableLabel label={dict.label} tooltip={dict.tooltip} variable="base" />
+      <ChromaSlider
+        className="h-6 w-[160px]"
+        hue={hue}
+        value={base}
+        onChange={handleBaseSliderChange}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/bottom-sheet.tsx b/apps/docs/src/app/[lang]/themes/components/bottom-sheet.tsx
new file mode 100644
index 0000000..53b913d
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/bottom-sheet.tsx
@@ -0,0 +1,87 @@
+"use client";
+
+import type {ReactNode} from "react";
+
+import {
+  AnimatePresence,
+  animate,
+  cubicBezier,
+  motion,
+  useMotionTemplate,
+  useMotionValue,
+  useTransform,
+} from "motion/react";
+import {Dialog, Modal, ModalOverlay} from "react-aria-components";
+
+const MotionModal = motion.create(Modal);
+const MotionModalOverlay = motion.create(ModalOverlay);
+
+const inertiaTransition = {
+  bounceDamping: 40,
+  bounceStiffness: 300,
+  timeConstant: 300,
+  type: "inertia" as const,
+};
+
+const staticTransition = {
+  duration: 0.5,
+  ease: cubicBezier(0.32, 0.72, 0, 1),
+};
+
+const SHEET_HEIGHT = 600; // Total height of the sheet
+const SNAP_HEIGHT = 320; // Height visible at snap position
+const SNAP_OFFSET = SHEET_HEIGHT - SNAP_HEIGHT; // Offset to show snap height
+
+interface BottomSheetProps {
+  children?: ReactNode;
+  id?: string;
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+}
+
+export function BottomSheet({children, id, isOpen, onOpenChange}: BottomSheetProps) {
+  const y = useMotionValue(SHEET_HEIGHT);
+  const bgOpacity = useTransform(y, [0, SHEET_HEIGHT], [0.4, 0]);
+  const bg = useMotionTemplate`rgba(0, 0, 0, ${bgOpacity})`;
+
+  return (
+    <AnimatePresence>
+      {isOpen ? (
+        <MotionModalOverlay
+          isDismissable
+          isOpen
+          className="fixed inset-0 z-100"
+          style={{backgroundColor: bg as unknown as string}}
+          onOpenChange={onOpenChange}
+        >
+          <MotionModal
+            animate={{y: SNAP_OFFSET}}
+            className="absolute bottom-0 w-full rounded-t-3xl bg-background shadow-lg will-change-transform"
+            drag="y"
+            dragConstraints={{top: SNAP_OFFSET}}
+            exit={{y: SHEET_HEIGHT}}
+            initial={{y: SHEET_HEIGHT}}
+            transition={staticTransition}
+            style={{
+              height: SHEET_HEIGHT,
+              y,
+            }}
+            onDragEnd={(_e, {offset, velocity}) => {
+              if (offset.y > SNAP_HEIGHT * 0.5 || velocity.y > 10) {
+                onOpenChange(false);
+              } else {
+                animate(y, SNAP_OFFSET, {...inertiaTransition, max: SNAP_OFFSET, min: SNAP_OFFSET});
+              }
+            }}
+          >
+            {/* Drag affordance */}
+            <div className="bg-default-400 mx-auto mt-2 h-1.5 w-12 rounded-full" />
+            <Dialog className="pb-5 outline-hidden" id={id}>
+              {children}
+            </Dialog>
+          </MotionModal>
+        </MotionModalOverlay>
+      ) : null}
+    </AnimatePresence>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/builder-header.tsx b/apps/docs/src/app/[lang]/themes/components/builder-header.tsx
new file mode 100644
index 0000000..4f28a4f
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/builder-header.tsx
@@ -0,0 +1,168 @@
+"use client";
+
+import type {TabLabel} from "../constants";
+
+import {
+  ArrowUturnCcwLeft,
+  ArrowUturnCwRight,
+  Code,
+  Link as LinkIcon,
+  NodesRight,
+} from "@gravity-ui/icons";
+import {Button, Kbd, Separator, Tabs, Tooltip, toast} from "@heroui/react";
+import Link from "next/link";
+import {useParams} from "next/navigation";
+
+import {HeroUILogo} from "@/components/heroui-logo";
+import {useCodePanel} from "@/hooks/use-code-panel";
+import {useDictionary} from "@/hooks/use-dictionary";
+import useKeyPress from "@/hooks/use-key-press";
+import {i18n} from "@/lib/i18n";
+
+import {tabs} from "../constants";
+import {usePreviewTab, useUndoRedo} from "../hooks";
+
+import {ResetButton} from "./reset-button";
+import {ShuffleButton} from "./shuffle-button";
+import {SwitchMode} from "./switch-mode";
+
+export function BuilderHeader() {
+  const {canRedo, canUndo, redo, undo} = useUndoRedo();
+  const {isCodeVisible, toggleCode} = useCodePanel();
+  const {selectedTab, setSelectedTab} = usePreviewTab();
+  const themeBuilderDict = useDictionary().themeBuilder;
+  const dict = themeBuilderDict.header;
+  const tabLabels = themeBuilderDict.tabs;
+  const params = useParams<{lang?: string}>();
+  const lang =
+    params?.lang && (i18n.languages as readonly string[]).includes(params.lang)
+      ? params.lang
+      : i18n.defaultLanguage;
+
+  const handleShare = () => {
+    navigator.clipboard.writeText(window.location.href);
+    toast(dict.linkCopied, {
+      description: dict.linkCopiedDescription,
+      indicator: <LinkIcon />,
+      variant: "success",
+    });
+  };
+
+  useKeyPress("ArrowLeft", () => undo(), {enabled: canUndo});
+  useKeyPress("ArrowRight", () => redo(), {enabled: canRedo});
+
+  return (
+    <div className="sticky top-0 z-50 mb-3 flex h-14 w-full items-center justify-center bg-background px-2 min-[1200px]:mb-4 min-[1200px]:px-0">
+      <div className="flex h-14 w-full max-w-[1400px] items-center justify-between min-[1200px]:h-14">
+        <div className="flex items-center gap-4">
+          <Link href={`/${lang}`}>
+            <HeroUILogo />
+          </Link>
+          <div className="flex items-center gap-3">
+            <Tooltip closeDelay={0} delay={100}>
+              <Tooltip.Trigger className="hidden min-[1200px]:inline-flex">
+                <Button
+                  isIconOnly
+                  isDisabled={!canUndo}
+                  size="md"
+                  variant="tertiary"
+                  onPress={() => undo()}
+                >
+                  <ArrowUturnCcwLeft />
+                </Button>
+              </Tooltip.Trigger>
+              <Tooltip.Content>
+                <Tooltip.Arrow />
+                <p>
+                  {dict.undo}{" "}
+                  <Kbd>
+                    <Kbd.Abbr keyValue="left" />
+                  </Kbd>
+                </p>
+              </Tooltip.Content>
+            </Tooltip>
+            <Tooltip closeDelay={0} delay={100}>
+              <Tooltip.Trigger className="hidden min-[1200px]:inline-flex">
+                <Button
+                  isIconOnly
+                  isDisabled={!canRedo}
+                  size="md"
+                  variant="tertiary"
+                  onPress={() => redo()}
+                >
+                  <ArrowUturnCwRight />
+                </Button>
+                <Tooltip.Content>
+                  <Tooltip.Arrow />
+                  <p>
+                    {dict.redo}{" "}
+                    <Kbd>
+                      <Kbd.Abbr keyValue="right" />
+                    </Kbd>
+                  </p>
+                </Tooltip.Content>
+              </Tooltip.Trigger>
+            </Tooltip>
+            <Separator
+              className="hidden h-6 self-center min-[1200px]:block"
+              orientation="vertical"
+            />
+            <ResetButton />
+            <div className="hidden sm:block">
+              <ShuffleButton />
+            </div>
+          </div>
+        </div>
+        <div className="relative hidden min-[1200px]:block">
+          <Tabs
+            selectedKey={selectedTab}
+            onSelectionChange={(key) => setSelectedTab(key as TabLabel)}
+          >
+            <Tabs.ListContainer>
+              <Tabs.List>
+                {tabs.map((tab) => (
+                  <Tabs.Tab key={tab.label} className="whitespace-nowrap" id={tab.label}>
+                    {tabLabels[tab.label]}
+                    <Tabs.Indicator />
+                  </Tabs.Tab>
+                ))}
+              </Tabs.List>
+            </Tabs.ListContainer>
+          </Tabs>
+        </div>
+        <div className="flex w-auto justify-end gap-3 min-[1200px]:w-[244px]">
+          <div className="flex h-auto items-center">
+            <SwitchMode />
+          </div>
+          <Tooltip closeDelay={0} delay={100}>
+            <Tooltip.Trigger>
+              <Button isIconOnly size="md" variant="tertiary" onPress={handleShare}>
+                <NodesRight />
+              </Button>
+            </Tooltip.Trigger>
+            <Tooltip.Content>
+              <Tooltip.Arrow />
+              <p>{dict.share}</p>
+            </Tooltip.Content>
+          </Tooltip>
+          <Tooltip closeDelay={0} delay={100}>
+            <Tooltip.Trigger className="hidden min-[1200px]:inline-flex">
+              <Button
+                isIconOnly
+                size="md"
+                variant={isCodeVisible ? "primary" : "tertiary"}
+                onPress={toggleCode}
+              >
+                <Code />
+              </Button>
+            </Tooltip.Trigger>
+            <Tooltip.Content>
+              <Tooltip.Arrow />
+              <p>{dict.viewCode}</p>
+            </Tooltip.Content>
+          </Tooltip>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/chroma-slider.tsx b/apps/docs/src/app/[lang]/themes/components/chroma-slider.tsx
new file mode 100644
index 0000000..5b313e4
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/chroma-slider.tsx
@@ -0,0 +1,143 @@
+"use client";
+
+import {useCallback, useRef} from "react";
+import {tv} from "tailwind-variants";
+
+import {cn} from "@/utils/cn";
+
+/* -------------------------------------------------------------------------------------------------
+ * Styles
+ * -----------------------------------------------------------------------------------------------*/
+
+const sliderTrackStyles = tv({
+  base: "relative h-8 w-full cursor-pointer touch-none rounded-full",
+});
+
+const sliderThumbStyles = tv({
+  base: [
+    "size-4 rounded-full border-[1.5px] border-white shadow-lg",
+    "absolute top-1/2 -translate-x-1/2 -translate-y-1/2",
+    "cursor-grab active:cursor-grabbing",
+    "outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2",
+    "transition-shadow",
+  ],
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * ChromaSlider - A slider for selecting chroma/saturation (0-0.2)
+ * Reference: https://codepen.io example uses 0-0.2 range with step 0.001
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ChromaSliderProps {
+  value: number;
+  hue: number;
+  onChange: (value: number) => void;
+  className?: string;
+}
+
+// Max chroma for subtle gray tinting - 0.02 keeps colors professional without high contrast
+const MAX_CHROMA = 0.02;
+
+export function ChromaSlider({className, hue, onChange, value}: ChromaSliderProps) {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+
+  const getValueFromPosition = useCallback(
+    (clientX: number) => {
+      if (!trackRef.current) return value;
+      const rect = trackRef.current.getBoundingClientRect();
+      const percentage = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+
+      // Round to 4 decimal places for finer control with smaller max
+      return Math.round(percentage * MAX_CHROMA * 10000) / 10000;
+    },
+    [value],
+  );
+
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      isDragging.current = true;
+      // Capture pointer to receive events even when pointer leaves the element
+      (e.target as HTMLElement).setPointerCapture(e.pointerId);
+      onChange(getValueFromPosition(e.clientX));
+
+      const handlePointerMove = (e: PointerEvent) => {
+        if (isDragging.current) {
+          onChange(getValueFromPosition(e.clientX));
+        }
+      };
+
+      const handlePointerUp = (e: PointerEvent) => {
+        isDragging.current = false;
+        (e.target as HTMLElement).releasePointerCapture(e.pointerId);
+        document.removeEventListener("pointermove", handlePointerMove);
+        document.removeEventListener("pointerup", handlePointerUp);
+      };
+
+      document.addEventListener("pointermove", handlePointerMove);
+      document.addEventListener("pointerup", handlePointerUp);
+    },
+    [getValueFromPosition, onChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      let newValue = value;
+      const step = e.shiftKey ? 0.002 : 0.0002;
+
+      switch (e.key) {
+        case "ArrowLeft":
+        case "ArrowDown":
+          newValue = Math.max(0, value - step);
+          break;
+        case "ArrowRight":
+        case "ArrowUp":
+          newValue = Math.min(MAX_CHROMA, value + step);
+          break;
+        case "Home":
+          newValue = 0;
+          break;
+        case "End":
+          newValue = MAX_CHROMA;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChange(Math.round(newValue * 10000) / 10000);
+    },
+    [value, onChange],
+  );
+
+  // Calculate thumb position (0-100%)
+  const thumbPosition = (value / MAX_CHROMA) * 100;
+
+  // Current color at this chroma level
+  const currentColor = `oklch(0.7 ${value} ${hue})`;
+
+  return (
+    <div
+      ref={trackRef}
+      aria-label="Amount of color in gray"
+      aria-valuemax={MAX_CHROMA}
+      aria-valuemin={0}
+      aria-valuenow={value}
+      className={cn(sliderTrackStyles(), className)}
+      role="slider"
+      tabIndex={0}
+      style={{
+        background: `linear-gradient(to right, oklch(0.7 0 ${hue}), oklch(0.7 ${MAX_CHROMA} ${hue}))`,
+      }}
+      onKeyDown={handleKeyDown}
+      onPointerDown={handlePointerDown}
+    >
+      <div
+        className={sliderThumbStyles()}
+        style={{
+          backgroundColor: currentColor,
+          left: `${thumbPosition}%`,
+        }}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/custom-fonts.tsx b/apps/docs/src/app/[lang]/themes/components/custom-fonts.tsx
new file mode 100644
index 0000000..cb5fd61
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/custom-fonts.tsx
@@ -0,0 +1,117 @@
+"use client";
+
+import {ArrowLeft, Globe} from "@gravity-ui/icons";
+import {Button, Description, FieldError, InputGroup, Label, Link, TextField} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {useCustomFonts, useVariableSetter} from "../hooks";
+import {extractFontFamilyFromUrl, isValidFontCdnUrl} from "../utils/font-utils";
+
+interface CustomFontsProps {
+  goToSuggested: () => void;
+}
+
+export function CustomFonts({goToSuggested}: CustomFontsProps) {
+  const [cdnUrl, setCdnUrl] = useState("");
+  const [hasBlurred, setHasBlurred] = useState(false);
+  const [importError, setImportError] = useState<string | null>(null);
+  const [isImporting, setIsImporting] = useState(false);
+  const {addCustomFont} = useCustomFonts();
+  const {setVariable} = useVariableSetter();
+  const dict = useDictionary().themeBuilder.customFonts;
+
+  const validationError = useMemo<string | null>(() => {
+    if (!cdnUrl.trim()) return null;
+
+    try {
+      const parsedUrl = new URL(cdnUrl);
+
+      if (parsedUrl.protocol !== "https:") return dict.errorHttps;
+      if (!isValidFontCdnUrl(cdnUrl)) return dict.errorSupportedCdn;
+
+      return null;
+    } catch {
+      return dict.errorInvalidUrl;
+    }
+  }, [cdnUrl, dict]);
+  const showValidationError = hasBlurred && validationError !== null;
+  const showError = showValidationError || importError !== null;
+  const errorMessage = importError ?? validationError;
+
+  const handleImport = () => {
+    if (validationError) return;
+
+    setIsImporting(true);
+    setImportError(null);
+
+    // Validate that we can extract a font family from the URL
+    const fontFamily = extractFontFamilyFromUrl(cdnUrl);
+
+    if (!fontFamily) {
+      setImportError(dict.errorCannotDetect);
+      setIsImporting(false);
+
+      return;
+    }
+
+    // Add to localStorage for the font picker list
+    const result = addCustomFont(cdnUrl);
+
+    if ("error" in result) {
+      const message =
+        result.error === "already-imported"
+          ? dict.errorAlreadyImported.replace("{name}", result.label)
+          : dict.errorCannotDetectFull;
+
+      setImportError(message);
+      setIsImporting(false);
+    } else {
+      // Store the URL directly in the query params (makes it shareable!)
+      setVariable("fontFamily", cdnUrl);
+      setCdnUrl("");
+      setHasBlurred(false);
+      setIsImporting(false);
+      goToSuggested();
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center justify-between">
+        <Link className="flex items-center gap-1 no-underline" onPress={goToSuggested}>
+          <ArrowLeft className="size-4" />
+          {dict.back}
+        </Link>
+      </div>
+      <TextField
+        isInvalid={showError}
+        value={cdnUrl}
+        onChange={(value) => {
+          setCdnUrl(value);
+          setImportError(null);
+        }}
+      >
+        <Label>{dict.fontUrl}</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Globe className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder={dict.placeholder} onBlur={() => setHasBlurred(true)} />
+        </InputGroup>
+        <Description>{dict.description}</Description>
+        {showError ? <FieldError>{errorMessage}</FieldError> : null}
+      </TextField>
+      <Button
+        className="w-full"
+        isDisabled={!cdnUrl.trim() || validationError !== null || isImporting}
+        size="sm"
+        variant="secondary"
+        onPress={handleImport}
+      >
+        {isImporting ? dict.importing : dict.importFont}
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/font-family-popover.tsx b/apps/docs/src/app/[lang]/themes/components/font-family-popover.tsx
new file mode 100644
index 0000000..8feb967
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/font-family-popover.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import {ChevronsExpandVertical, FontCase} from "@gravity-ui/icons";
+import {InputGroup, Popover} from "@heroui/react";
+import {useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {fonts} from "../constants";
+import {useCustomFonts, useVariableSetter} from "../hooks";
+import {extractFontFamilyFromUrl, isCustomFontUrl} from "../utils/font-utils";
+
+import {CustomFonts} from "./custom-fonts";
+import {LockableLabel} from "./lockable-label";
+import {SuggestedFonts} from "./suggested-fonts";
+
+export function FontFamilyPopover() {
+  const {variables} = useVariableSetter();
+  const {customFonts} = useCustomFonts();
+  const [mode, setMode] = useState<"suggested" | "custom">("suggested");
+  const dict = useDictionary().themeBuilder.fontFamily;
+
+  // Find current font label - check predefined fonts first, then URL-based custom fonts
+  const currentSuggestedFont = fonts.find((f) => f.id === variables.fontFamily);
+  const currentUrlFontLabel = isCustomFontUrl(variables.fontFamily)
+    ? extractFontFamilyFromUrl(variables.fontFamily)
+    : null;
+  const currentFontLabel = currentSuggestedFont?.label ?? currentUrlFontLabel ?? "Inter";
+
+  return (
+    <Popover>
+      <div className="flex flex-col gap-1">
+        <LockableLabel label={dict.label} variable="fontFamily" />
+        <Popover.Trigger>
+          <InputGroup className="w-40 cursor-pointer">
+            <InputGroup.Prefix className="w-10">
+              <FontCase />
+            </InputGroup.Prefix>
+            <InputGroup.Input
+              readOnly
+              className="max-w-20 cursor-pointer"
+              id="font-family"
+              name="font-family"
+              value={currentFontLabel}
+            />
+            <InputGroup.Suffix className="w-10">
+              <ChevronsExpandVertical className="size-3" />
+            </InputGroup.Suffix>
+          </InputGroup>
+        </Popover.Trigger>
+      </div>
+      <Popover.Content className="w-[325px] rounded-3xl" placement="top">
+        <Popover.Dialog className="p-3">
+          {mode === "suggested" ? (
+            <SuggestedFonts customFonts={customFonts} goToCustom={() => setMode("custom")} />
+          ) : (
+            <CustomFonts goToSuggested={() => setMode("suggested")} />
+          )}
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/index.ts b/apps/docs/src/app/[lang]/themes/components/index.ts
new file mode 100644
index 0000000..20d81c7
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/index.ts
@@ -0,0 +1,11 @@
+export {AccentColorSelector} from "./accent-color-selector";
+export {BaseColorSlider} from "./base-color-slider";
+export {BottomSheet} from "./bottom-sheet";
+export {BuilderHeader} from "./builder-header";
+export {FontFamilyPopover} from "./font-family-popover";
+export {PreviewContainer} from "./preview-container";
+export {RadiusPopover} from "./radius-popover";
+export {ShuffleButton} from "./shuffle-button";
+export {ThemeCodePanel} from "./theme-code-panel";
+export {ThemePopover} from "./theme-popover";
+export {ThemesList} from "./themes-list";
diff --git a/apps/docs/src/app/[lang]/themes/components/lockable-label.tsx b/apps/docs/src/app/[lang]/themes/components/lockable-label.tsx
new file mode 100644
index 0000000..4f8d6fd
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/lockable-label.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import type {LockableThemeVariableKey} from "../constants";
+
+import {CircleInfo, Lock, LockOpen} from "@gravity-ui/icons";
+import {Label, Tooltip, cn} from "@heroui/react";
+import {useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {useToggleLockedVariable} from "../hooks/use-toggle-locked-variable";
+
+interface LockableLabelProps {
+  label: string;
+  variable: LockableThemeVariableKey;
+  tooltip?: string;
+}
+
+export function LockableLabel({label, tooltip, variable}: LockableLabelProps) {
+  const [isLabelHovered, setLabelHovered] = useState(false);
+  const {isLocked, toggleLockedVariable} = useToggleLockedVariable(variable);
+  const dict = useDictionary().themeBuilder.lockableLabel;
+
+  return (
+    <div
+      className="flex h-6 items-center gap-1"
+      onMouseEnter={() => setLabelHovered(true)}
+      onMouseLeave={() => setLabelHovered(false)}
+    >
+      <Label>{label}</Label>
+      {tooltip ? (
+        <Tooltip closeDelay={0} delay={100}>
+          <Tooltip.Trigger className="hidden xl:block">
+            <CircleInfo className="size-4 text-muted" tabIndex={0} />
+          </Tooltip.Trigger>
+          <Tooltip.Content>
+            <Tooltip.Arrow />
+            <p>{tooltip}</p>
+          </Tooltip.Content>
+        </Tooltip>
+      ) : null}
+      <Tooltip closeDelay={0} delay={100}>
+        <Tooltip.Trigger>
+          <div
+            role="button"
+            tabIndex={0}
+            className={cn(
+              "button button--icon-only button--ghost hidden size-6 rounded-full hover:flex",
+              isLabelHovered && "flex",
+              isLocked && "flex",
+            )}
+            onClick={toggleLockedVariable}
+          >
+            {isLocked ? <Lock className="size-4" /> : <LockOpen className="size-4" />}
+          </div>
+        </Tooltip.Trigger>
+        <Tooltip.Content>
+          <Tooltip.Arrow />
+          <p>{isLocked ? dict.unlockValue : dict.lockValue}</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/mobile-footer.tsx b/apps/docs/src/app/[lang]/themes/components/mobile-footer.tsx
new file mode 100644
index 0000000..d40f9ab
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/mobile-footer.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {ScrollShadow} from "@heroui/react";
+import {useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {THEME_BUILDER_BOTTOM_SHEET_ID, formRadiusOptions, radiusOptions} from "../constants";
+
+import {AccentColorSelector} from "./accent-color-selector";
+import {BaseColorSlider} from "./base-color-slider";
+import {BottomSheet} from "./bottom-sheet";
+import {FontFamilyPopover} from "./font-family-popover";
+import {RadiusPopover} from "./radius-popover";
+import {ShuffleButton} from "./shuffle-button";
+import {ThemeInput} from "./theme-input";
+import {ThemesList} from "./themes-list";
+
+export function MobileFooter() {
+  const [isSheetOpen, setIsSheetOpen] = useState(false);
+  const radiusDict = useDictionary().themeBuilder.radius;
+
+  return (
+    <>
+      <div className="fixed right-0 bottom-0 left-0 z-50 flex w-full items-center justify-between gap-4 border-t border-separator bg-background px-6 pt-3 pb-4 sm:hidden">
+        <div className="w-full cursor-pointer" onClick={() => setIsSheetOpen(true)}>
+          <ThemeInput />
+        </div>
+        <ShuffleButton enableKeyboardShortcut={false} />
+      </div>
+      <BottomSheet
+        id={THEME_BUILDER_BOTTOM_SHEET_ID}
+        isOpen={isSheetOpen}
+        onOpenChange={setIsSheetOpen}
+      >
+        <div className="flex w-full flex-col items-start md:items-center">
+          <div className="mb-4 flex w-full justify-center pb-2">
+            <div className="h-1.5 w-9 rounded-sm bg-separator" />
+          </div>
+          <ThemesList />
+          <div className="h-6" />
+          <div className="flex w-full flex-wrap gap-4 gap-x-0 md:w-auto">
+            <div className="mb-4 flex items-center gap-4 pl-4">
+              <AccentColorSelector />
+              <BaseColorSlider />
+            </div>
+            <ScrollShadow
+              hideScrollBar
+              className="flex w-full items-center gap-4 px-4 pb-4 md:w-auto"
+              orientation="horizontal"
+              visibility="none"
+            >
+              <FontFamilyPopover />
+              <RadiusPopover
+                description={radiusDict.description}
+                label={radiusDict.label}
+                radiusOptions={radiusOptions}
+                variableKey="radius"
+              />
+              <RadiusPopover
+                description={radiusDict.formDescription}
+                label={radiusDict.formLabel}
+                radiusOptions={formRadiusOptions}
+                variableKey="formRadius"
+              />
+            </ScrollShadow>
+          </div>
+        </div>
+      </BottomSheet>
+    </>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/onboarding.tsx b/apps/docs/src/app/[lang]/themes/components/onboarding.tsx
new file mode 100644
index 0000000..a67955a
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/onboarding.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import type {MotionProps} from "motion/react";
+
+import {Button, Modal, cn, useOverlayState} from "@heroui/react";
+import {motion} from "motion/react";
+import {useEffect} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+// Keyframe values for each property (loops back to first value)
+const RADIUS_KEYFRAMES = [24, 8, 0, 12, 24];
+const BUTTON_BG_KEYFRAMES = ["#3b82f6", "#6366f1", "#10b981", "#f97316", "#3b82f6"];
+const BUTTON_INNER_BG_KEYFRAMES = ["#93c5fd", "#a5b4fc", "#6ee7b7", "#fdba74", "#93c5fd"];
+
+const TRANSITION: MotionProps["transition"] = {
+  duration: 4,
+  ease: "easeInOut",
+  repeat: Infinity,
+  times: [0, 0.25, 0.5, 0.75, 1] as const,
+};
+
+export function Onboarding() {
+  const {isOpen, open, setOpen} = useOverlayState();
+  const dict = useDictionary().themeBuilder.onboarding;
+
+  useEffect(() => {
+    const onboarding = localStorage.getItem("onboarding");
+
+    if (!onboarding) {
+      open();
+      localStorage.setItem("onboarding", "true");
+    }
+  }, []);
+
+  return (
+    <Modal isOpen={isOpen} onOpenChange={setOpen}>
+      <Modal.Backdrop>
+        <Modal.Container size="lg">
+          <Modal.Dialog className="max-w-[480px]">
+            <Modal.Header className="mb-4">
+              <div className="flex h-64 w-full items-center justify-center rounded-xl border border-border bg-background">
+                <AnimatedBlock />
+              </div>
+            </Modal.Header>
+            <Modal.Body>
+              <div className="flex flex-col gap-2">
+                <p className="text-base font-medium text-foreground">{dict.title}</p>
+                <p className="text-sm leading-5 text-muted">
+                  {dict.description}
+                  <br />
+                  <br />
+                  {dict.moreComing}
+                </p>
+              </div>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button className="w-full" slot="close">
+                {dict.continue}
+              </Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+
+function AnimatedBlock() {
+  return (
+    <motion.div
+      animate={{borderRadius: RADIUS_KEYFRAMES}}
+      transition={TRANSITION}
+      className={cn(
+        "h-[152px] w-[188px] bg-surface p-4",
+        "shadow-[0_2px_4px_0_rgba(0,0,0,0.04),0_1px_2px_0_rgba(0,0,0,0.06),0_0_1px_0_rgba(0,0,0,0.06)]",
+      )}
+    >
+      <motion.div
+        animate={{borderRadius: RADIUS_KEYFRAMES}}
+        className="mb-3 size-10 bg-surface-secondary"
+        transition={TRANSITION}
+      />
+      <motion.div
+        animate={{borderRadius: RADIUS_KEYFRAMES}}
+        className="mb-2 h-2 w-[93px] bg-surface-secondary"
+        transition={TRANSITION}
+      />
+      <motion.div
+        animate={{borderRadius: RADIUS_KEYFRAMES}}
+        className="mb-3 h-4 w-[139px] bg-surface-secondary"
+        transition={TRANSITION}
+      />
+      <motion.div
+        animate={{backgroundColor: BUTTON_BG_KEYFRAMES, borderRadius: RADIUS_KEYFRAMES}}
+        className="h-6 w-[104px] px-3 py-2"
+        transition={TRANSITION}
+      >
+        <motion.div
+          animate={{backgroundColor: BUTTON_INNER_BG_KEYFRAMES, borderRadius: RADIUS_KEYFRAMES}}
+          className="h-full w-full"
+          transition={TRANSITION}
+        />
+      </motion.div>
+    </motion.div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/preview-container.tsx b/apps/docs/src/app/[lang]/themes/components/preview-container.tsx
new file mode 100644
index 0000000..b950b58
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/preview-container.tsx
@@ -0,0 +1,144 @@
+"use client";
+
+import {Spinner} from "@heroui/react";
+import {UNSAFE_PortalProvider} from "@react-aria/overlays";
+import {useTheme} from "next-themes";
+import {useCallback, useEffect, useMemo, useRef, useState} from "react";
+
+import {DemoComponents} from "@/components/demo";
+import {cn} from "@/utils/cn";
+
+import {THEME_BUILDER_CONTENT_ID, iframeTabs} from "../constants";
+import {useComputedThemeVars, useCssSync, usePreviewTab} from "../hooks";
+
+const LOADER_DURATION_MS = 250;
+
+export function PreviewContainer() {
+  const [isMounted, setIsMounted] = useState(false);
+  const [iframeLoading, setIframeLoading] = useState(true);
+  const container = useRef(null);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const {selectedTab} = usePreviewTab();
+  const {resolvedTheme} = useTheme();
+  const {fontMeta, fullDarkVars, fullLightVars} = useComputedThemeVars();
+
+  const themeVars = useMemo(
+    () => (resolvedTheme === "light" ? fullLightVars : fullDarkVars),
+    [resolvedTheme, fullLightVars, fullDarkVars],
+  );
+
+  useCssSync();
+
+  useEffect(() => {
+    setTimeout(() => {
+      setIsMounted(true);
+    });
+  }, []);
+
+  const [prevSelectedTab, setPrevSelectedTab] = useState(selectedTab);
+
+  if (selectedTab !== prevSelectedTab) {
+    setPrevSelectedTab(selectedTab);
+    if (!iframeLoading) {
+      setIframeLoading(true);
+    }
+  }
+
+  const sendMessageToIframe = useCallback(() => {
+    const iframe = iframeRef.current;
+
+    if (!iframe?.contentWindow) return;
+    iframe.contentWindow.postMessage({theme: resolvedTheme ?? "dark", type: "heroui-theme"}, "*");
+    iframe.contentWindow.postMessage({type: "heroui-accent", vars: themeVars}, "*");
+    iframe.contentWindow.postMessage(
+      {
+        cdnUrl: fontMeta.cdnUrl,
+        family: fontMeta.family,
+        type: "heroui-font",
+        variable: fontMeta.variable,
+      },
+      "*",
+    );
+  }, [themeVars, resolvedTheme, fontMeta]);
+
+  useEffect(() => {
+    sendMessageToIframe();
+  }, [sendMessageToIframe]);
+
+  useEffect(() => {
+    function handleMessage(event: MessageEvent) {
+      if (event.data?.type === "heroui-ready") {
+        sendMessageToIframe();
+      }
+    }
+
+    window.addEventListener("message", handleMessage);
+
+    return () => window.removeEventListener("message", handleMessage);
+  }, [sendMessageToIframe]);
+
+  const handleIframeLoad = useCallback(() => {
+    sendMessageToIframe();
+    setTimeout(() => {
+      setIframeLoading(false);
+    }, LOADER_DURATION_MS);
+  }, [sendMessageToIframe]);
+
+  const isComponentsTab = selectedTab === "components";
+  const iframeSrc = iframeTabs[selectedTab];
+
+  return (
+    <UNSAFE_PortalProvider getContainer={() => container.current}>
+      <div
+        ref={container}
+        id={THEME_BUILDER_CONTENT_ID}
+        className={cn(
+          "flex w-full flex-1 bg-background font-sans",
+          isComponentsTab ? "min-h-full px-4 py-8" : "h-full items-center p-0",
+        )}
+      >
+        {/* Mobile: always show DemoComponents */}
+        <div className="flex w-full justify-center lg:hidden">
+          {isMounted ? <DemoComponents /> : null}
+        </div>
+        {/* Desktop: respect tab selection */}
+        <div
+          className={cn(
+            "hidden lg:flex lg:w-full lg:flex-1",
+            isComponentsTab ? "lg:flex-col" : "lg:h-full lg:min-h-0 lg:items-center",
+          )}
+        >
+          {isComponentsTab ? (
+            isMounted ? (
+              <div className="my-auto flex justify-center">
+                <DemoComponents />
+              </div>
+            ) : null
+          ) : iframeSrc ? (
+            <div className="relative h-full min-h-0 w-full flex-1">
+              <iframe
+                ref={iframeRef}
+                className="absolute inset-0 h-full w-full border-none"
+                src={iframeSrc}
+                title={selectedTab}
+                onLoad={handleIframeLoad}
+              />
+              <div
+                className={cn(
+                  "pointer-events-none absolute inset-0 z-10 flex items-center justify-center bg-background transition-opacity duration-300",
+                  iframeLoading ? "opacity-100" : "opacity-0",
+                )}
+              >
+                <Spinner />
+              </div>
+            </div>
+          ) : (
+            <div className="flex h-full w-full items-center justify-center text-muted">
+              Coming soon
+            </div>
+          )}
+        </div>
+      </div>
+    </UNSAFE_PortalProvider>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/radius-popover.tsx b/apps/docs/src/app/[lang]/themes/components/radius-popover.tsx
new file mode 100644
index 0000000..aff6a88
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/radius-popover.tsx
@@ -0,0 +1,117 @@
+"use client";
+
+import type {ThemeVariables, radiusIds} from "../constants";
+
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {InputGroup, ListBox, Popover} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+import {useVariableSetter} from "../hooks";
+
+import {LockableLabel} from "./lockable-label";
+
+type RadiusPopoverProps = {
+  label: string;
+  variableKey: keyof Pick<ThemeVariables, "radius" | "formRadius">;
+  description?: string;
+  radiusOptions: Array<{
+    cssValue: string;
+    description: string;
+    id: (typeof radiusIds)[number];
+    label: string;
+  }>;
+};
+
+const RADIUS_DESCRIPTION_KEYS: Record<
+  (typeof radiusIds)[number],
+  "none" | "extraSmall" | "small" | "medium" | "large" | "extraLarge"
+> = {
+  "extra-large": "extraLarge",
+  "extra-small": "extraSmall",
+  large: "large",
+  medium: "medium",
+  none: "none",
+  small: "small",
+};
+
+export function RadiusPopover({
+  description,
+  label,
+  radiusOptions,
+  variableKey,
+}: RadiusPopoverProps) {
+  const {setVariable, variables} = useVariableSetter();
+  const currentValue = variables[variableKey];
+  const currentOption = radiusOptions.find((r) => r.id === currentValue);
+  const optionDict = useDictionary().themeBuilder.radius.options;
+
+  const translateOption = (id: (typeof radiusIds)[number]) =>
+    optionDict[RADIUS_DESCRIPTION_KEYS[id]];
+
+  return (
+    <Popover>
+      <div className="flex flex-col gap-1">
+        <LockableLabel label={label} variable={variableKey} />
+        <Popover.Trigger>
+          <InputGroup className="w-40 cursor-pointer">
+            <InputGroup.Prefix className="w-10">
+              <span className="text-base font-semibold text-muted">{currentOption?.label}</span>
+            </InputGroup.Prefix>
+            <InputGroup.Input
+              readOnly
+              className="max-w-20 cursor-pointer capitalize"
+              id={variableKey}
+              name={variableKey}
+              value={currentOption ? translateOption(currentOption.id) : ""}
+            />
+            <InputGroup.Suffix className="w-10">
+              <ChevronsExpandVertical className="size-3" />
+            </InputGroup.Suffix>
+          </InputGroup>
+        </Popover.Trigger>
+      </div>
+      <Popover.Content className="w-[304px] rounded-3xl" placement="top">
+        <Popover.Dialog className="p-3">
+          <div className="mb-2 flex flex-col gap-0.5 pl-2">
+            <p className="text-xs font-medium capitalize">{label}</p>
+            <p className="text-xs text-muted">{description}</p>
+          </div>
+          <ListBox
+            disallowEmptySelection
+            aria-label={label}
+            className="grid grid-cols-3 gap-2 px-0"
+            items={radiusOptions}
+            layout="grid"
+            selectedKeys={new Set([currentValue])}
+            selectionMode="single"
+            onSelectionChange={(keys) => {
+              const selected = [...keys][0];
+
+              if (selected) {
+                setVariable(variableKey, String(selected));
+              }
+            }}
+          >
+            {(item) => (
+              <ListBox.Item
+                id={item.id}
+                textValue={item.id}
+                className={cn(
+                  "group border-separator-on-surface flex h-[83px] w-[88px] flex-col items-center justify-center gap-[5px] rounded-2xl border",
+                  "data-[selected=true]:border-foreground",
+                )}
+              >
+                <span className="text-xl font-semibold">{item.label}</span>
+                <p className="text-xs text-muted capitalize group-data-[selected=true]:text-foreground">
+                  {translateOption(item.id)}
+                </p>
+              </ListBox.Item>
+            )}
+          </ListBox>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/reset-button.tsx b/apps/docs/src/app/[lang]/themes/components/reset-button.tsx
new file mode 100644
index 0000000..f4fad74
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/reset-button.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {ArrowRotateLeft} from "@gravity-ui/icons";
+import {AlertDialog, Button, Kbd, Tooltip, useOverlayState} from "@heroui/react";
+import {useMemo} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import useKeyPress from "@/hooks/use-key-press";
+
+import {defaultThemeVariables} from "../constants";
+import {useResetVariables} from "../hooks";
+import {useVariablesState} from "../hooks/use-variables-state";
+
+export function ResetButton() {
+  const reset = useResetVariables();
+  const [variables] = useVariablesState();
+  const {isOpen, setOpen} = useOverlayState();
+  const dict = useDictionary().themeBuilder.resetButton;
+
+  const isDisabled = useMemo(() => {
+    return (
+      variables.chroma === defaultThemeVariables.chroma &&
+      variables.hue === defaultThemeVariables.hue &&
+      variables.lightness === defaultThemeVariables.lightness &&
+      variables.fontFamily === defaultThemeVariables.fontFamily &&
+      variables.formRadius === defaultThemeVariables.formRadius &&
+      variables.radius === defaultThemeVariables.radius &&
+      variables.base === defaultThemeVariables.base
+    );
+  }, [variables]);
+
+  useKeyPress("d", () => setOpen(true), {enabled: !isDisabled});
+
+  return (
+    <Tooltip closeDelay={0} delay={100}>
+      <Tooltip.Trigger>
+        <AlertDialog isOpen={isOpen} onOpenChange={setOpen}>
+          <Button isIconOnly isDisabled={isDisabled} size="md" variant="tertiary">
+            <ArrowRotateLeft />
+          </Button>
+          <AlertDialog.Backdrop isDismissable>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog>
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="default">
+                    <ArrowRotateLeft />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>{dict.dialogTitle}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>{dict.dialogBody}</AlertDialog.Body>
+                <AlertDialog.Footer className="flex-col sm:flex-row">
+                  <Button
+                    className="order-2 w-full sm:order-1 sm:w-auto"
+                    size="md"
+                    slot="close"
+                    variant="tertiary"
+                  >
+                    {dict.cancel}
+                  </Button>
+                  <Button
+                    className="order-1 w-full sm:order-2 sm:w-auto"
+                    size="md"
+                    slot="close"
+                    onPress={reset}
+                  >
+                    {dict.confirm}
+                  </Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        <p>
+          {dict.tooltip}{" "}
+          <Kbd>
+            <Kbd.Content>D</Kbd.Content>
+          </Kbd>
+        </p>
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/shuffle-button.tsx b/apps/docs/src/app/[lang]/themes/components/shuffle-button.tsx
new file mode 100644
index 0000000..9c39247
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/shuffle-button.tsx
@@ -0,0 +1,139 @@
+"use client";
+
+import {Shuffle} from "@gravity-ui/icons";
+import {AlertDialog, Button, Checkbox, Kbd, Label, Tooltip, useOverlayState} from "@heroui/react";
+import {useEffect, useRef, useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {useKeyPress} from "@/hooks/use-key-press";
+
+import {LOCAL_STORAGE_KEYS} from "../constants";
+import {useRandomizeVariables} from "../hooks";
+import {useVariablesState} from "../hooks/use-variables-state";
+import {compareThemeVariables} from "../utils/compare-theme-variables";
+
+interface ShuffleButtonProps {
+  enableKeyboardShortcut?: boolean;
+}
+
+export function ShuffleButton({enableKeyboardShortcut = true}: ShuffleButtonProps) {
+  const [isDontShowAgainChecked, setIsDontShowAgainChecked] = useState(false);
+  const modalState = useOverlayState();
+  const randomize = useRandomizeVariables();
+  const [variables] = useVariablesState();
+  const snapshotVariablesRef = useRef(variables);
+  const isRandomizingRef = useRef(false);
+  const dict = useDictionary().themeBuilder.shuffleButton;
+
+  const handleRandomize = () => {
+    isRandomizingRef.current = true;
+    randomize();
+    if (isDontShowAgainChecked) {
+      localStorage.setItem(LOCAL_STORAGE_KEYS.SHUFFLE_WARNING_SHOWN, JSON.stringify(true));
+    }
+    modalState.close();
+  };
+
+  const handleModalTrigger = () => {
+    const isDontShowAgainChecked = localStorage.getItem(LOCAL_STORAGE_KEYS.SHUFFLE_WARNING_SHOWN);
+    const isSame = compareThemeVariables(variables, snapshotVariablesRef.current);
+
+    if (isSame || isDontShowAgainChecked === "true") {
+      isRandomizingRef.current = true;
+
+      return randomize();
+    }
+
+    modalState.open();
+  };
+
+  useKeyPress("r", handleModalTrigger, {enabled: enableKeyboardShortcut});
+
+  const handleOpenChange = (isOpen: boolean) => {
+    setIsDontShowAgainChecked(false);
+    modalState.setOpen(isOpen);
+  };
+
+  const handleClose = () => {
+    setIsDontShowAgainChecked(false);
+    modalState.close();
+  };
+
+  // Update snapshot after randomize completes (when variables change due to randomization)
+  useEffect(() => {
+    if (isRandomizingRef.current) {
+      snapshotVariablesRef.current = variables;
+      isRandomizingRef.current = false;
+    }
+  }, [variables]);
+
+  return (
+    <div className="flex flex-col gap-1">
+      <Tooltip delay={0}>
+        <Tooltip.Trigger className="w-min">
+          <Button isIconOnly size="md" variant="tertiary" onPress={handleModalTrigger}>
+            <Shuffle />
+          </Button>
+        </Tooltip.Trigger>
+        <Tooltip.Content>
+          <p>
+            {dict.tooltip}{" "}
+            <Kbd>
+              <Kbd.Content>R</Kbd.Content>
+            </Kbd>
+          </p>
+        </Tooltip.Content>
+      </Tooltip>
+      <AlertDialog.Backdrop
+        isDismissable
+        isOpen={modalState.isOpen}
+        onOpenChange={handleOpenChange}
+      >
+        <AlertDialog.Container>
+          <AlertDialog.Dialog>
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="default">
+                <Shuffle />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>{dict.dialogTitle}</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>{dict.dialogBody}</AlertDialog.Body>
+            <AlertDialog.Footer className="flex-col sm:flex-row sm:items-center">
+              <Button
+                className="order-2 w-full sm:order-2 sm:w-auto"
+                size="md"
+                variant="tertiary"
+                onPress={handleClose}
+              >
+                {dict.cancel}
+              </Button>
+              <Button
+                className="order-1 w-full sm:order-3 sm:w-auto"
+                size="md"
+                onPress={handleRandomize}
+              >
+                {dict.confirm}
+              </Button>
+              <div className="order-3 flex flex-1 items-center gap-2 self-start sm:order-1 sm:self-center">
+                <Checkbox
+                  id="dont-show-again"
+                  isSelected={isDontShowAgainChecked}
+                  variant="secondary"
+                  onChange={setIsDontShowAgainChecked}
+                >
+                  <Checkbox.Content>
+                    <Checkbox.Control>
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                  </Checkbox.Content>
+                </Checkbox>
+                <Label htmlFor="dont-show-again">{dict.dontShowAgain}</Label>
+              </div>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/suggested-fonts.tsx b/apps/docs/src/app/[lang]/themes/components/suggested-fonts.tsx
new file mode 100644
index 0000000..92fd130
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/suggested-fonts.tsx
@@ -0,0 +1,149 @@
+"use client";
+
+import type {CustomFont} from "../hooks";
+
+import {Plus, TrashBin} from "@gravity-ui/icons";
+import {Button, ListBox, ScrollShadow, Tooltip} from "@heroui/react";
+import {useEffect} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+import {defaultThemeVariables, fonts} from "../constants";
+import {useCustomFonts, useVariableSetter} from "../hooks";
+import {injectFontLink, isCustomFontUrl} from "../utils/font-utils";
+
+interface SuggestedFontsProps {
+  customFonts: CustomFont[];
+  goToCustom: () => void;
+}
+
+export function SuggestedFonts({customFonts, goToCustom}: SuggestedFontsProps) {
+  const {setVariable, variables} = useVariableSetter();
+  const {removeCustomFont} = useCustomFonts();
+  const dict = useDictionary().themeBuilder.fontFamily;
+
+  // Inject font links for all suggested fonts so they can be previewed
+  useEffect(() => {
+    fonts.forEach((font) => {
+      injectFontLink(font.id, font.cdnUrl);
+    });
+  }, []);
+
+  // Inject font links for all custom fonts so they can be previewed
+  useEffect(() => {
+    customFonts.forEach((font) => {
+      injectFontLink(font.id, font.url);
+    });
+  }, [customFonts]);
+
+  // Also inject font link if current selection is a URL-based font
+  useEffect(() => {
+    if (isCustomFontUrl(variables.fontFamily)) {
+      injectFontLink("current-url-font", variables.fontFamily);
+    }
+  }, [variables.fontFamily]);
+
+  // Combine suggested fonts with custom fonts for the list
+  // For custom fonts, use the URL as the ID (for shareable links)
+  const allFonts = [
+    ...fonts.map((f) => ({...f, isCustom: false, url: f.cdnUrl})),
+    ...customFonts.map((f) => ({
+      cdnUrl: f.url,
+      id: f.url, // Use URL as ID so it's stored in the URL params
+      isCustom: true,
+      label: f.label,
+      url: f.url,
+      variable: f.variable,
+    })),
+  ];
+
+  // The selected key is the fontFamily value (either a font ID or a CDN URL)
+  const selectedKey = variables.fontFamily;
+
+  const handleDeleteCustomFont = (fontUrl: string) => {
+    // Find the font by URL and remove it
+    const font = customFonts.find((f) => f.url === fontUrl);
+
+    if (font) {
+      removeCustomFont(font.id);
+    }
+    // If the deleted font was selected, switch to Inter
+    if (variables.fontFamily === fontUrl) {
+      setVariable("fontFamily", defaultThemeVariables.fontFamily);
+    }
+  };
+
+  return (
+    <>
+      <div className="mb-2 flex items-center justify-between">
+        <p className="text-sm font-medium capitalize">
+          {customFonts.length > 0 ? dict.allFonts : dict.suggested}
+        </p>
+        <Button size="sm" variant="ghost" onPress={goToCustom}>
+          {dict.addFromCdn}
+          <Plus className="size-4" />
+        </Button>
+      </div>
+      <ScrollShadow hideScrollBar className="max-h-56 pb-3" size={15}>
+        <ListBox
+          disallowEmptySelection
+          aria-label={dict.label}
+          className="grid grid-cols-3 gap-2 p-0"
+          items={allFonts}
+          layout="grid"
+          selectedKeys={new Set([selectedKey])}
+          selectionMode="single"
+          onSelectionChange={(keys) => {
+            const selected = [...keys][0];
+
+            if (selected) {
+              setVariable("fontFamily", String(selected));
+            }
+          }}
+        >
+          {(item) => (
+            <ListBox.Item
+              id={item.id}
+              textValue={item.label}
+              className={cn(
+                "group border-separator-on-surface relative flex h-[83px] w-[95px] flex-col items-center justify-center gap-[5px] rounded-2xl border",
+                "data-[selected=true]:border-foreground",
+                "data-[hovered=true]:bg-default",
+              )}
+              style={{
+                fontFamily: `"${item.label}", sans-serif`,
+              }}
+            >
+              <span className="text-xl font-medium">Ag</span>
+              <p className="max-w-[80px] truncate text-[10px] text-muted group-data-[selected=true]:text-foreground">
+                {item.label}
+              </p>
+              {item.isCustom ? (
+                <Tooltip closeDelay={0} delay={100}>
+                  <Tooltip.Trigger className="absolute top-1 right-1">
+                    <Button
+                      isIconOnly
+                      className="size-5 min-h-0 min-w-0 p-0 opacity-0 group-data-[hovered=true]:opacity-100"
+                      size="sm"
+                      variant="ghost"
+                      onPress={() => {
+                        handleDeleteCustomFont(item.url);
+                      }}
+                    >
+                      <TrashBin className="size-3 text-danger" />
+                    </Button>
+                  </Tooltip.Trigger>
+                  <Tooltip.Content>
+                    <Tooltip.Arrow />
+                    <p>{dict.removeFont}</p>
+                  </Tooltip.Content>
+                </Tooltip>
+              ) : null}
+            </ListBox.Item>
+          )}
+        </ListBox>
+      </ScrollShadow>
+    </>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/switch-mode.tsx b/apps/docs/src/app/[lang]/themes/components/switch-mode.tsx
new file mode 100644
index 0000000..01bb311
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/switch-mode.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import {Kbd, Label, Tooltip, cn} from "@heroui/react";
+import {useTheme} from "next-themes";
+
+import {ThemeToggle} from "@/components/fumadocs/ui/theme-toggle";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {useKeyPress} from "@/hooks/use-key-press";
+
+export function SwitchMode({label}: {label?: string}) {
+  const {setTheme, theme} = useTheme();
+  const dict = useDictionary().themeBuilder.header;
+
+  const handleModeSwitch = () => {
+    setTheme(theme === "light" ? "dark" : "light");
+  };
+
+  useKeyPress("s", handleModeSwitch);
+
+  return (
+    <div className={cn("flex flex-col gap-1", !label && "h-9")}>
+      {label ? <Label>{label}</Label> : null}
+      <Tooltip>
+        <Tooltip.Trigger>
+          <ThemeToggle className="h-9" mode="light-dark" tabIndex={0} />
+        </Tooltip.Trigger>
+        <Tooltip.Content>
+          <p>
+            {dict.switchMode}{" "}
+            <Kbd>
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/theme-builder-content.tsx b/apps/docs/src/app/[lang]/themes/components/theme-builder-content.tsx
new file mode 100644
index 0000000..c12fd8d
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/theme-builder-content.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import {ScrollShadow} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+import {HEROUI_PRO_URL} from "../constants";
+import {usePreviewTab} from "../hooks";
+
+import {PreviewContainer} from "./preview-container";
+import {ThemeCodePanel} from "./theme-code-panel";
+
+function getProUrl(utm: {campaign?: string; content?: string; medium: string}) {
+  const url = new URL(HEROUI_PRO_URL);
+
+  url.searchParams.set("utm_source", "heroui.com");
+  url.searchParams.set("utm_medium", utm.medium);
+  if (utm.campaign) url.searchParams.set("utm_campaign", utm.campaign);
+  if (utm.content) url.searchParams.set("utm_content", utm.content);
+
+  return url.toString();
+}
+
+export const ThemeBuilderContent = () => {
+  const {selectedTab} = usePreviewTab();
+  const demo = useDictionary().home.demo;
+  const isComponentsTab = selectedTab === "components";
+
+  return (
+    <div className="mx-auto flex h-full min-h-0 w-full max-w-[1400px] flex-col">
+      <div
+        className={`flex shrink-0 justify-end px-2 pb-1 transition-opacity duration-300 ${!isComponentsTab ? "opacity-100" : "pointer-events-none opacity-0"}`}
+      >
+        <a
+          className="text-[13px] font-medium text-muted hover:text-foreground"
+          rel="noopener noreferrer"
+          target="_blank"
+          href={getProUrl({
+            campaign: "theme-builder",
+            content: `template-${selectedTab}`,
+            medium: "themes-page",
+          })}
+        >
+          {demo.proTemplate}
+        </a>
+      </div>
+      <ScrollShadow
+        hideScrollBar
+        visibility="none"
+        className={cn(
+          "flex min-h-0 w-full flex-1 flex-col rounded-2xl border border-border/50",
+          isComponentsTab ? "overflow-scroll" : "overflow-hidden",
+        )}
+      >
+        <div
+          className={cn(
+            "relative flex w-full",
+            isComponentsTab
+              ? "min-h-full items-start"
+              : "min-h-0 flex-1 items-center justify-center",
+          )}
+        >
+          <PreviewContainer />
+          <ThemeCodePanel />
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+};
diff --git a/apps/docs/src/app/[lang]/themes/components/theme-code-panel.tsx b/apps/docs/src/app/[lang]/themes/components/theme-code-panel.tsx
new file mode 100644
index 0000000..bae349c
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/theme-code-panel.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {useDeferredValue} from "react";
+
+import {CodePanel} from "@/components/code-panel";
+import {useCodePanel} from "@/hooks/use-code-panel";
+
+import {useVariablesState} from "../hooks/use-variables-state";
+import {getCustomFontInfoFromUrl, isCustomFontUrl} from "../utils/font-utils";
+import {generateMinimalCssVariables} from "../utils/generate-css-variables";
+
+export function ThemeCodePanel() {
+  const [variables] = useVariablesState();
+  const {isCodeVisible, toggleCode} = useCodePanel();
+
+  // Get custom font info if using a URL-based custom font
+  const customFontInfo = isCustomFontUrl(variables.fontFamily)
+    ? getCustomFontInfoFromUrl(variables.fontFamily)
+    : undefined;
+
+  const cssCode = generateMinimalCssVariables(variables, customFontInfo ?? undefined);
+
+  // Defer the CSS code value to prevent expensive syntax highlighting
+  // from blocking high-priority UI updates (like color sliders).
+  // This allows the theme preview to stay responsive while the code panel
+  // updates on a lower priority schedule.
+  // See: https://www.joshwcomeau.com/react/use-deferred-value/
+  const deferredCssCode = useDeferredValue(cssCode);
+
+  return (
+    <CodePanel
+      showLineNumbers
+      fileName="theme.css"
+      isVisible={isCodeVisible}
+      lang="css"
+      sourceCode={deferredCssCode}
+      title="globals.css"
+      onClose={toggleCode}
+    />
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/theme-input.tsx b/apps/docs/src/app/[lang]/themes/components/theme-input.tsx
new file mode 100644
index 0000000..e10c19f
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/theme-input.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {Avatar, InputGroup} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {findMatchingTheme, themes} from "../constants";
+import {useVariablesState} from "../hooks/use-variables-state";
+
+export function ThemeInput() {
+  const [variables] = useVariablesState();
+  const currentThemeId = findMatchingTheme(variables);
+  const currentTheme = currentThemeId ? themes.find((t) => t.id === currentThemeId) : undefined;
+  const dict = useDictionary().themes;
+
+  const accentColor = `oklch(${variables.lightness} ${variables.chroma} ${variables.hue})`;
+  const customThemeGradient = `radial-gradient(85.29% 80.57% at 40.28% 34.72%, rgba(0, 0, 0, 0.00) 0%, rgba(0, 0, 0, 0.02) 43.66%, rgba(0, 0, 0, 0.27) 72.4%, rgba(0, 0, 0, 0.30) 100%), ${accentColor}`;
+
+  return (
+    <InputGroup className="w-full cursor-pointer">
+      <InputGroup.Prefix className="w-10">
+        {currentTheme ? (
+          <Avatar className="size-4">
+            <Avatar.Fallback>{currentTheme.label[0]}</Avatar.Fallback>
+            <Avatar.Image
+              alt={currentTheme.label}
+              height={16}
+              src={currentTheme.image.src}
+              width={16}
+            />
+          </Avatar>
+        ) : (
+          <div className="size-4 rounded-full" style={{background: customThemeGradient}} />
+        )}
+      </InputGroup.Prefix>
+      <InputGroup.Input
+        readOnly
+        className="max-w-20 sm:max-w-none"
+        value={currentTheme?.label ?? dict.custom}
+      />
+      <InputGroup.Suffix className="flex w-10 flex-1 justify-end">
+        <ChevronsExpandVertical className="size-4" />
+      </InputGroup.Suffix>
+    </InputGroup>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/theme-popover.tsx b/apps/docs/src/app/[lang]/themes/components/theme-popover.tsx
new file mode 100644
index 0000000..3060ff2
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/theme-popover.tsx
@@ -0,0 +1,139 @@
+"use client";
+
+import type {ThemeId} from "../constants";
+
+import {BucketPaint, ChevronsExpandVertical} from "@gravity-ui/icons";
+import {Description, InputGroup, Kbd, Label, ListBox, Popover, Switch} from "@heroui/react";
+import Image from "next/image";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import useKeyPress from "@/hooks/use-key-press";
+import {cn} from "@/utils/cn";
+
+import {findMatchingTheme, themeValuesById, themes} from "../constants";
+import {useVariablesState} from "../hooks/use-variables-state";
+
+export function ThemePopover() {
+  const dict = useDictionary().themes;
+  const [pickRandomPrefix, pickRandomSuffix] = dict.pickRandomHint.split("{kbd}");
+
+  const [variables, setVariables] = useVariablesState();
+  const currentThemeId = findMatchingTheme(variables);
+  const currentTheme = currentThemeId ? themes.find((t) => t.id === currentThemeId) : undefined;
+
+  const applyTheme = (themeId: ThemeId) => {
+    const themeValues = themeValuesById[themeId];
+
+    setVariables({
+      base: themeValues.base,
+      chroma: themeValues.chroma,
+      fontFamily: themeValues.fontFamily,
+      formRadius: themeValues.formRadius,
+      hue: themeValues.hue,
+      lightness: themeValues.lightness,
+      radius: themeValues.radius,
+    });
+  };
+
+  const randomizeTheme = () => {
+    const randomTheme = themes[Math.floor(Math.random() * themes.length)];
+
+    if (randomTheme) {
+      applyTheme(randomTheme.id);
+    }
+  };
+
+  useKeyPress("t", randomizeTheme);
+
+  return (
+    <Popover>
+      <div className="flex flex-col gap-1">
+        <Label>{dict.theme}</Label>
+        <Popover.Trigger>
+          <InputGroup className="w-40 cursor-pointer">
+            <InputGroup.Prefix className="w-10">
+              <BucketPaint />
+            </InputGroup.Prefix>
+            <InputGroup.Input
+              readOnly
+              className="max-w-20 cursor-pointer capitalize"
+              id="theme"
+              name="theme"
+              value={currentTheme?.label ?? dict.custom}
+            />
+            <InputGroup.Suffix className="w-10">
+              <ChevronsExpandVertical className="size-3" />
+            </InputGroup.Suffix>
+          </InputGroup>
+        </Popover.Trigger>
+      </div>
+      <Popover.Content className="w-[228px] rounded-3xl" placement="top">
+        <Popover.Dialog className="p-4">
+          <ListBox
+            aria-label={dict.theme}
+            className="grid grid-cols-4 gap-3"
+            items={themes}
+            layout="grid"
+            selectedKeys={currentThemeId ? new Set([currentThemeId]) : new Set()}
+            selectionMode="single"
+            onSelectionChange={(keys) => {
+              const selected = [...keys][0];
+
+              if (selected) {
+                applyTheme(selected as ThemeId);
+              }
+            }}
+          >
+            {(item) => (
+              <ListBox.Item
+                id={item.id}
+                textValue={item.id}
+                className={cn(
+                  "group relative flex w-10 flex-col items-center justify-center gap-1.5 p-0",
+                  "hover:bg-transparent data-[hovered=true]:bg-transparent",
+                )}
+              >
+                <Image
+                  alt={item.label}
+                  height={36}
+                  src={item.image}
+                  width={36}
+                  className={cn(
+                    "size-9 rounded-full bg-surface",
+                    "group-data-[selected=true]:ring-2 group-data-[selected=true]:ring-accent group-data-[selected=true]:ring-offset-2 group-data-[selected=true]:ring-offset-surface",
+                  )}
+                />
+                <span className="text-[10px] font-medium text-muted capitalize group-data-[selected=true]:text-foreground">
+                  {item.label}
+                </span>
+              </ListBox.Item>
+            )}
+          </ListBox>
+          <div className="mt-4 border-t border-separator pt-4">
+            <div className="flex items-center justify-between">
+              <div className="flex flex-col gap-0.5">
+                <Label className="text-xs">{dict.vibrantPalette}</Label>
+                <Description className="text-[10px]">{dict.vibrantPaletteDescription}</Description>
+              </div>
+              <Switch
+                isSelected={variables.vibrantPalette ?? false}
+                onChange={(isSelected) => setVariables({vibrantPalette: isSelected})}
+              >
+                <Switch.Control>
+                  <Switch.Thumb />
+                </Switch.Control>
+              </Switch>
+            </div>
+          </div>
+          <p className="mt-4 text-xs text-muted">
+            {pickRandomPrefix}
+            <Kbd>
+              <Kbd.Content>T</Kbd.Content>
+            </Kbd>
+            {pickRandomSuffix}
+          </p>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/components/themes-list.tsx b/apps/docs/src/app/[lang]/themes/components/themes-list.tsx
new file mode 100644
index 0000000..939d805
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/components/themes-list.tsx
@@ -0,0 +1,81 @@
+"use client";
+
+import type {ThemeId} from "../constants";
+
+import {ListBox, ScrollShadow} from "@heroui/react";
+import Image from "next/image";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+import {findMatchingTheme, themeValuesById, themes} from "../constants";
+import {useVariablesState} from "../hooks/use-variables-state";
+
+export function ThemesList() {
+  const [variables, setVariables] = useVariablesState();
+  const currentThemeId = findMatchingTheme(variables);
+  const dict = useDictionary().themes;
+
+  const applyTheme = (themeId: ThemeId) => {
+    const themeValues = themeValuesById[themeId];
+
+    setVariables({
+      base: themeValues.base,
+      chroma: themeValues.chroma,
+      fontFamily: themeValues.fontFamily,
+      formRadius: themeValues.formRadius,
+      hue: themeValues.hue,
+      lightness: themeValues.lightness,
+      radius: themeValues.radius,
+    });
+  };
+
+  return (
+    <ScrollShadow
+      hideScrollBar
+      className="w-full px-4 md:w-auto"
+      orientation="horizontal"
+      visibility="none"
+    >
+      <ListBox
+        aria-label={dict.theme}
+        className="flex w-max flex-row flex-nowrap gap-5"
+        items={themes}
+        selectedKeys={currentThemeId ? new Set([currentThemeId]) : new Set()}
+        selectionMode="single"
+        onSelectionChange={(keys) => {
+          const selected = [...keys][0];
+
+          if (selected) {
+            applyTheme(selected as ThemeId);
+          }
+        }}
+      >
+        {(item) => (
+          <ListBox.Item
+            id={item.id}
+            textValue={item.id}
+            className={cn(
+              "group relative flex w-12 shrink-0 flex-col items-center justify-center gap-1.5 p-0",
+              "hover:bg-transparent data-[hovered=true]:bg-transparent",
+            )}
+          >
+            <Image
+              alt={item.label}
+              height={48}
+              src={item.image}
+              width={48}
+              className={cn(
+                "size-12 rounded-full bg-surface",
+                "group-data-[selected=true]:ring-2 group-data-[selected=true]:ring-accent group-data-[selected=true]:ring-offset-2 group-data-[selected=true]:ring-offset-surface",
+              )}
+            />
+            <span className="text-[10px] font-medium text-muted capitalize group-data-[selected=true]:text-foreground">
+              {item.label}
+            </span>
+          </ListBox.Item>
+        )}
+      </ListBox>
+    </ScrollShadow>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/constants.ts b/apps/docs/src/app/[lang]/themes/constants.ts
new file mode 100644
index 0000000..f2cf9d6
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/constants.ts
@@ -0,0 +1,273 @@
+import type {RadiusId, ThemeId} from "./theme-values";
+import type {StaticImageData} from "next/image";
+
+import {env} from "~env";
+
+import airbnbTheme from "@/assets/themes/airbnb.png";
+import blackTheme from "@/assets/themes/black.png";
+import coinbaseTheme from "@/assets/themes/coinbase.png";
+import defaultTheme from "@/assets/themes/default.png";
+import discordTheme from "@/assets/themes/discord.png";
+import lavenderTheme from "@/assets/themes/lavender.png";
+import mintTheme from "@/assets/themes/mint.png";
+import netflixTheme from "@/assets/themes/netflix.png";
+import rabbitTheme from "@/assets/themes/rabbit.png";
+import skyTheme from "@/assets/themes/sky.png";
+import spotifyTheme from "@/assets/themes/spotify.png";
+
+import {DEFAULT_BASE} from "./theme-values";
+
+export type {
+  RadiusId,
+  SemanticColorOverride,
+  ThemeId,
+  ThemeSemanticOverrides,
+  ThemeValues,
+} from "./theme-values";
+export {
+  DEFAULT_BASE,
+  findMatchingTheme,
+  radiusIds,
+  themeComparisonKeys,
+  themeIds,
+  themeValuesById,
+} from "./theme-values";
+
+export const tabLabels = ["components", "dashboard", "mail", "chat", "finances"] as const;
+
+export type TabLabel = (typeof tabLabels)[number];
+
+export const tabs = tabLabels.map((label) => ({disabled: false, label}));
+
+export const HEROUI_PRO_URL = env.NEXT_PUBLIC_PRO_URL ?? "https://heroui.pro";
+
+export const iframeTabs: Record<string, string> = {
+  chat: `${HEROUI_PRO_URL}/templates/chat`,
+  dashboard: `${HEROUI_PRO_URL}/templates/dashboard`,
+  finances: `${HEROUI_PRO_URL}/templates/finances`,
+  mail: `${HEROUI_PRO_URL}/templates/email`,
+};
+
+/**
+ * Adaptive colors that need different values in light vs dark modes.
+ * Maps a color ID to its light and dark mode variants.
+ */
+export const adaptiveColors: Record<string, {light: string; dark: string}> = {
+  "oklch(0 0 0)": {
+    dark: "oklch(0.9848 0 0)",
+    light: "oklch(0 0 0)",
+  },
+};
+
+export const fontIds = [
+  "inter",
+  "figtree",
+  "hanken-grotesk",
+  "geist",
+  "dm-sans",
+  "public-sans",
+  "google-sans",
+  "bricolage-grotesque",
+  "varela-round",
+  "fraunces",
+  "ibm-plex-mono",
+  "fredoka",
+  "jetbrains-mono",
+  "instrument-sans",
+] as const;
+
+export type FontConfig = {
+  id: (typeof fontIds)[number];
+  label: string;
+  variable: string;
+  /** Google Fonts CDN URL for on-demand loading */
+  cdnUrl: string;
+};
+
+export const fonts: FontConfig[] = [
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap",
+    id: "inter",
+    label: "Inter",
+    variable: "--font-inter",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Figtree:wght@300..900&display=swap",
+    id: "figtree",
+    label: "Figtree",
+    variable: "--font-figtree",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@100..900&display=swap",
+    id: "hanken-grotesk",
+    label: "Hanken Grotesk",
+    variable: "--font-hanken-grotesk",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap",
+    id: "geist",
+    label: "Geist",
+    variable: "--font-geist",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=DM+Sans:wght@100..900&display=swap",
+    id: "dm-sans",
+    label: "DM Sans",
+    variable: "--font-dm-sans",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Public+Sans:wght@100..900&display=swap",
+    id: "public-sans",
+    label: "Public Sans",
+    variable: "--font-public-sans",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Google+Sans:wght@100..900&display=swap",
+    id: "google-sans",
+    label: "Google Sans",
+    variable: "--font-google-sans",
+  },
+  {
+    cdnUrl:
+      "https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@200..800&display=swap",
+    id: "bricolage-grotesque",
+    label: "Bricolage Grotesque",
+    variable: "--font-bricolage-grotesque",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Varela+Round&display=swap",
+    id: "varela-round",
+    label: "Varela Round",
+    variable: "--font-varela-round",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Fraunces:wght@100..900&display=swap",
+    id: "fraunces",
+    label: "Fraunces",
+    variable: "--font-fraunces",
+  },
+  {
+    cdnUrl:
+      "https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap",
+    id: "ibm-plex-mono",
+    label: "IBM Plex Mono",
+    variable: "--font-ibm-plex-mono",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Fredoka:wght@300..700&display=swap",
+    id: "fredoka",
+    label: "Fredoka",
+    variable: "--font-fredoka",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@100..800&display=swap",
+    id: "jetbrains-mono",
+    label: "JetBrains Mono",
+    variable: "--font-jetbrains-mono",
+  },
+  {
+    cdnUrl: "https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400..700&display=swap",
+    id: "instrument-sans",
+    label: "Instrument Sans",
+    variable: "--font-instrument-sans",
+  },
+];
+
+/** Map font ID to font info for quick lookup */
+export const fontMap = Object.fromEntries(fonts.map((f) => [f.id, f])) as Record<
+  (typeof fontIds)[number],
+  FontConfig
+>;
+
+export const radiusOptions: Array<{
+  cssValue: string;
+  description: string;
+  id: RadiusId;
+  label: string;
+}> = [
+  {cssValue: "0", description: "none", id: "none", label: "-"},
+  {cssValue: "0.125rem", description: "extra small", id: "extra-small", label: "XS"},
+  {cssValue: "0.25rem", description: "small", id: "small", label: "S"},
+  {cssValue: "0.5rem", description: "medium", id: "medium", label: "M"},
+  {cssValue: "0.75rem", description: "large", id: "large", label: "L"},
+];
+export const formRadiusOptions: Array<{
+  cssValue: string;
+  description: string;
+  id: RadiusId;
+  label: string;
+}> = [
+  {cssValue: "0", description: "none", id: "none", label: "-"},
+  {cssValue: "0.125rem", description: "extra small", id: "extra-small", label: "XS"},
+  {cssValue: "0.25rem", description: "small", id: "small", label: "S"},
+  {cssValue: "0.5rem", description: "medium", id: "medium", label: "M"},
+  {cssValue: "0.75rem", description: "large", id: "large", label: "L"},
+  {cssValue: "1rem", description: "extra large", id: "extra-large", label: "XL"},
+];
+
+/** Map radius ID to CSS value for quick lookup */
+export const radiusCssMap = Object.fromEntries(
+  formRadiusOptions.map((r) => [r.id, r.cssValue]),
+) as Record<(typeof formRadiusOptions)[number]["id"], string>;
+
+export const themes: Array<{
+  id: ThemeId;
+  image: StaticImageData;
+  label: string;
+}> = [
+  {id: "default", image: defaultTheme, label: "Default"},
+  {id: "sky", image: skyTheme, label: "Sky"},
+  {id: "lavender", image: lavenderTheme, label: "Lavender"},
+  {id: "mint", image: mintTheme, label: "Mint"},
+  {id: "netflix", image: netflixTheme, label: "Netflix"},
+  {id: "uber", image: blackTheme, label: "Uber"},
+  {id: "spotify", image: spotifyTheme, label: "Spotify"},
+  {id: "coinbase", image: coinbaseTheme, label: "Coinbase"},
+  {id: "airbnb", image: airbnbTheme, label: "Airbnb"},
+  {id: "discord", image: discordTheme, label: "Discord"},
+  {id: "rabbit", image: rabbitTheme, label: "Rabbit"},
+];
+
+export type ThemeVariables = {
+  lightness: number;
+  chroma: number;
+  hue: number;
+  base: number;
+  /** Font family - can be a predefined fontId or a custom font ID (prefixed with "custom-") */
+  fontFamily: (typeof fontIds)[number] | string;
+  formRadius: RadiusId;
+  radius: RadiusId;
+  /** Use vibrant (more saturated) soft foreground colors instead of accessible defaults */
+  vibrantPalette?: boolean;
+};
+
+export const themeVariableKeys = [
+  "base",
+  "lightness",
+  "chroma",
+  "hue",
+  "fontFamily",
+  "formRadius",
+  "radius",
+] as const satisfies readonly (keyof ThemeVariables)[];
+
+/** Theme variable keys that can be locked (excludes booleans like `vibrantPalette`). */
+export type LockableThemeVariableKey = (typeof themeVariableKeys)[number];
+
+export const defaultThemeVariables: ThemeVariables = {
+  base: DEFAULT_BASE,
+  chroma: 0.195,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 253.83,
+  lightness: 0.6204,
+  radius: "medium",
+} as const;
+
+export const LOCAL_STORAGE_KEYS = {
+  SHUFFLE_WARNING_SHOWN: "shuffle-warning-shown",
+} as const;
+
+export const THEME_BUILDER_CONTENT_ID = "theme-builder-content";
+export const THEME_BUILDER_PAGE_ID = "theme-builder-page";
+export const THEME_BUILDER_BOTTOM_SHEET_ID = "theme-builder-bottom-sheet";
diff --git a/apps/docs/src/app/[lang]/themes/hooks/index.ts b/apps/docs/src/app/[lang]/themes/hooks/index.ts
new file mode 100644
index 0000000..803c6b3
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/index.ts
@@ -0,0 +1,10 @@
+export {computeThemeVars, useComputedThemeVars} from "./use-computed-theme-vars";
+export type {ComputedThemeVars, FontMeta} from "./use-computed-theme-vars";
+export {useCssSync} from "./use-css-sync";
+export {useCustomFonts} from "./use-custom-fonts";
+export type {CustomFont} from "./use-custom-fonts";
+export {usePreviewTab} from "./use-preview-tab";
+export {useRandomizeVariables} from "./use-randomize-variables";
+export {useResetVariables} from "./use-reset-variables";
+export {useVariableSetter} from "./use-variable-setter";
+export {useUndoRedo} from "./use-undo-redo";
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-computed-theme-vars.ts b/apps/docs/src/app/[lang]/themes/hooks/use-computed-theme-vars.ts
new file mode 100644
index 0000000..c8c97ef
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-computed-theme-vars.ts
@@ -0,0 +1,177 @@
+"use client";
+
+import type {ThemeValues} from "../constants";
+
+import {useMemo} from "react";
+
+import {
+  adaptiveColors,
+  findMatchingTheme,
+  fontMap,
+  radiusCssMap,
+  themeValuesById,
+} from "../constants";
+import {getCustomFontInfoFromUrl, isCustomFontUrl} from "../utils/font-utils";
+import {
+  calculateAccentForeground,
+  generateThemeColors,
+  getColorVariablesForElement,
+  getDerivedColorFormulas,
+  parseOklch,
+  radiusDerivedVariables,
+} from "../utils/generate-theme-colors";
+
+import {useVariablesState} from "./use-variables-state";
+
+export interface FontMeta {
+  cdnUrl: string;
+  variable: string;
+  family: string;
+}
+
+export interface ComputedThemeVars {
+  fullLightVars: Record<string, string>;
+  fullDarkVars: Record<string, string>;
+  fontMeta: FontMeta;
+}
+
+function getCommonVars(
+  radius: string,
+  fieldRadius: string,
+  fontVariable: string,
+): Record<string, string> {
+  return {
+    "--field-radius": fieldRadius,
+    "--font-sans": `var(${fontVariable})`,
+    "--radius": radius,
+    ...radiusDerivedVariables,
+  };
+}
+
+export function computeThemeVars(variables: ThemeValues): ComputedThemeVars {
+  const {base, chroma, hue, lightness} = variables;
+  const accentColor = `oklch(${lightness} ${chroma} ${hue})`;
+  const isAdaptive = accentColor in adaptiveColors;
+
+  const matchingThemeId = findMatchingTheme(variables);
+  const semanticOverrides = matchingThemeId
+    ? themeValuesById[matchingThemeId].semanticOverrides
+    : undefined;
+
+  // Resolve font variable and metadata
+  const fontFamily = variables.fontFamily;
+  let fontVariable: string;
+  let fontMeta: FontMeta;
+
+  if (isCustomFontUrl(fontFamily)) {
+    const customFontInfo = getCustomFontInfoFromUrl(fontFamily);
+
+    if (customFontInfo) {
+      fontVariable = customFontInfo.variable;
+      fontMeta = {
+        cdnUrl: customFontInfo.url,
+        family: customFontInfo.fontFamily,
+        variable: customFontInfo.variable,
+      };
+    } else {
+      const interFont = fontMap.inter;
+
+      fontVariable = interFont.variable;
+      fontMeta = {cdnUrl: interFont.cdnUrl, family: interFont.label, variable: interFont.variable};
+    }
+  } else {
+    const predefinedFont = fontMap[fontFamily as keyof typeof fontMap] ?? fontMap.inter;
+
+    fontVariable = predefinedFont.variable;
+    fontMeta = {
+      cdnUrl: predefinedFont.cdnUrl,
+      family: predefinedFont.label,
+      variable: predefinedFont.variable,
+    };
+  }
+
+  const commonVars = getCommonVars(
+    radiusCssMap[variables.radius],
+    radiusCssMap[variables.formRadius],
+    fontVariable,
+  );
+
+  const derivedOpts = {vibrant: variables.vibrantPalette ?? false};
+
+  if (isAdaptive) {
+    const adaptiveConfig = adaptiveColors[accentColor]!;
+    const lightAccent = parseOklch(adaptiveConfig.light);
+    const darkAccent = parseOklch(adaptiveConfig.dark);
+
+    const lightFg = lightAccent
+      ? calculateAccentForeground(lightAccent.l, lightAccent.c, lightAccent.h)
+      : calculateAccentForeground(0, 0, 0);
+    const darkFg = darkAccent
+      ? calculateAccentForeground(darkAccent.l, darkAccent.c, darkAccent.h)
+      : calculateAccentForeground(1, 0, 0);
+
+    const colors = generateThemeColors({chroma, hue, lightness, semanticOverrides});
+    const lightVars = getColorVariablesForElement(colors, "light");
+    const darkVars = getColorVariablesForElement(colors, "dark");
+
+    const lightAccentVars: Record<string, string> = {
+      "--accent": adaptiveConfig.light,
+      "--accent-foreground": lightFg,
+      "--accent-soft-foreground": adaptiveConfig.light,
+      "--focus": adaptiveConfig.light,
+    };
+    const darkAccentVars: Record<string, string> = {
+      "--accent": adaptiveConfig.dark,
+      "--accent-foreground": darkFg,
+      "--accent-soft-foreground": adaptiveConfig.dark,
+      "--focus": adaptiveConfig.dark,
+    };
+
+    const colorLightVars = {
+      ...lightVars,
+      ...getDerivedColorFormulas("light", derivedOpts),
+      ...lightAccentVars,
+    };
+    const colorDarkVars = {
+      ...darkVars,
+      ...getDerivedColorFormulas("dark", derivedOpts),
+      ...darkAccentVars,
+    };
+
+    return {
+      fontMeta,
+      fullDarkVars: {...commonVars, ...colorDarkVars},
+      fullLightVars: {...commonVars, ...colorLightVars},
+    };
+  }
+
+  // Standard (non-adaptive) colors
+  const colors = generateThemeColors({
+    chroma,
+    grayChroma: base,
+    hue,
+    lightness,
+    semanticOverrides,
+  });
+  const lightVars = getColorVariablesForElement(colors, "light");
+  const darkVars = getColorVariablesForElement(colors, "dark");
+
+  const colorLightVars = {...lightVars, ...getDerivedColorFormulas("light", derivedOpts)};
+  const colorDarkVars = {...darkVars, ...getDerivedColorFormulas("dark", derivedOpts)};
+
+  return {
+    fontMeta,
+    fullDarkVars: {...commonVars, ...colorDarkVars},
+    fullLightVars: {...commonVars, ...colorLightVars},
+  };
+}
+
+/**
+ * Computes the full set of CSS theme variables for both light and dark modes.
+ * Used by PreviewContainer to sync theme variables to iframes via postMessage.
+ */
+export function useComputedThemeVars(): ComputedThemeVars {
+  const [variables] = useVariablesState();
+
+  return useMemo(() => computeThemeVars(variables), [variables]);
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-css-sync.ts b/apps/docs/src/app/[lang]/themes/hooks/use-css-sync.ts
new file mode 100644
index 0000000..8076a4b
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-css-sync.ts
@@ -0,0 +1,402 @@
+"use client";
+
+import type {SemanticOverrides} from "../utils/generate-theme-colors";
+
+import {useEffect} from "react";
+
+import {
+  THEME_BUILDER_BOTTOM_SHEET_ID,
+  THEME_BUILDER_CONTENT_ID,
+  THEME_BUILDER_PAGE_ID,
+  adaptiveColors,
+  findMatchingTheme,
+  fontMap,
+  radiusCssMap,
+  themeValuesById,
+} from "../constants";
+import {getCustomFontInfoFromUrl, injectFontLink, isCustomFontUrl} from "../utils/font-utils";
+import {
+  calculateAccentForeground,
+  generateThemeColors,
+  getColorVariablesForElement,
+  getDerivedColorFormulas,
+  radiusDerivedVariables,
+} from "../utils/generate-theme-colors";
+
+import {useVariablesState} from "./use-variables-state";
+
+/**
+ * Style element ID for adaptive color CSS injection
+ */
+const ADAPTIVE_STYLE_ID = "theme-builder-adaptive-colors";
+
+/**
+ * Parse an oklch color string into its components
+ * @param oklchString - e.g. "oklch(0.5 0.2 250)" or "oklch(0 0 0)"
+ */
+function parseOklch(oklchString: string): {lightness: number; chroma: number; hue: number} | null {
+  const match = oklchString.match(/oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\)/);
+
+  if (!match || !match[1] || !match[2] || !match[3]) return null;
+
+  return {
+    chroma: parseFloat(match[2]),
+    hue: parseFloat(match[3]),
+    lightness: parseFloat(match[1]),
+  };
+}
+
+/**
+ * Style element ID for theme-aware color CSS injection
+ */
+const THEME_COLORS_STYLE_ID = "theme-builder-theme-colors";
+
+/**
+ * CSS selector for colors only (page level)
+ */
+const PAGE_SELECTORS = `#${THEME_BUILDER_PAGE_ID}`;
+
+/**
+ * CSS selector for full theme (colors + radius + fonts)
+ * Targets the content area and dialogs within it
+ */
+const CONTENT_SELECTORS = [
+  `#${THEME_BUILDER_BOTTOM_SHEET_ID}`,
+  `#${THEME_BUILDER_CONTENT_ID}`,
+  `#${THEME_BUILDER_CONTENT_ID} [role='dialog']`,
+].join(", ");
+
+/**
+ * Build CSS string from a variables record
+ */
+function buildVarsCSS(vars: Record<string, string>): string {
+  return Object.entries(vars)
+    .map(([prop, val]) => `${prop}: ${val};`)
+    .join("\n    ");
+}
+
+/**
+ * Get common variables (radius, font) that apply to both light and dark modes.
+ * Derived radius values must be re-declared on scoped elements because
+ * CSS custom properties resolve var() at the level they are defined.
+ */
+function getCommonVariables(
+  radius: string,
+  fieldRadius: string,
+  fontVariable: string,
+): Record<string, string> {
+  return {
+    "--field-radius": fieldRadius,
+    "--font-sans": `var(${fontVariable})`,
+    "--radius": radius,
+    ...radiusDerivedVariables,
+  };
+}
+
+/**
+ * Generates CSS for adaptive colors that need different values in light/dark modes.
+ * This injects CSS rules targeting both light and dark selectors within the scoped element.
+ */
+function getAdaptiveColorCSS(
+  accentColor: string,
+  chroma: number,
+  hue: number,
+  lightness: number,
+  commonVars: Record<string, string>,
+  semanticOverrides?: SemanticOverrides,
+  vibrant?: boolean,
+): string | null {
+  const adaptiveConfig = adaptiveColors[accentColor];
+
+  if (!adaptiveConfig) {
+    return null;
+  }
+
+  // Parse the actual oklch values from the adaptive config to calculate foreground colors
+  const lightAccent = parseOklch(adaptiveConfig.light);
+  const darkAccent = parseOklch(adaptiveConfig.dark);
+
+  // Calculate foreground colors based on the actual accent lightness values
+  const lightFg = lightAccent
+    ? calculateAccentForeground(lightAccent.lightness, lightAccent.chroma, lightAccent.hue)
+    : calculateAccentForeground(0, 0, 0); // Fallback
+  const darkFg = darkAccent
+    ? calculateAccentForeground(darkAccent.lightness, darkAccent.chroma, darkAccent.hue)
+    : calculateAccentForeground(1, 0, 0); // Fallback
+
+  // Generate full theme colors for both modes
+  const lightColors = generateThemeColors({chroma, hue, lightness, semanticOverrides});
+  const darkColors = generateThemeColors({chroma, hue, lightness, semanticOverrides});
+
+  // Get light and dark color variables
+  const lightVars = getColorVariablesForElement(lightColors, "light");
+  const darkVars = getColorVariablesForElement(darkColors, "dark");
+
+  const lightAccentVars: Record<string, string> = {
+    "--accent": adaptiveConfig.light,
+    "--accent-foreground": lightFg,
+    "--accent-soft-foreground": adaptiveConfig.light,
+    "--focus": adaptiveConfig.light,
+  };
+
+  const darkAccentVars: Record<string, string> = {
+    "--accent": adaptiveConfig.dark,
+    "--accent-foreground": darkFg,
+    "--accent-soft-foreground": adaptiveConfig.dark,
+    "--focus": adaptiveConfig.dark,
+  };
+
+  const derivedOpts = {vibrant};
+
+  const colorLightVars = {
+    ...lightVars,
+    ...getDerivedColorFormulas("light", derivedOpts),
+    ...lightAccentVars,
+  };
+  const colorDarkVars = {
+    ...darkVars,
+    ...getDerivedColorFormulas("dark", derivedOpts),
+    ...darkAccentVars,
+  };
+
+  // Content level: colors + radius + fonts
+  const fullLightVars = {...commonVars, ...colorLightVars};
+  const fullDarkVars = {...commonVars, ...colorDarkVars};
+
+  return `
+  /* Page level: colors only */
+  :is([data-theme="light"], .light) ${PAGE_SELECTORS},
+  ${PAGE_SELECTORS}:not(:is([data-theme="dark"] *, .dark *)) {
+    ${buildVarsCSS(colorLightVars)}
+  }
+
+  :is([data-theme="dark"], .dark) ${PAGE_SELECTORS} {
+    ${buildVarsCSS(colorDarkVars)}
+  }
+
+  /* Content level: colors + radius + fonts */
+  :is([data-theme="light"], .light) :is(${CONTENT_SELECTORS}),
+  :is(${CONTENT_SELECTORS}):not(:is([data-theme="dark"] *, .dark *)) {
+    ${buildVarsCSS(fullLightVars)}
+  }
+
+  :is([data-theme="dark"], .dark) :is(${CONTENT_SELECTORS}) {
+    ${buildVarsCSS(fullDarkVars)}
+  }
+  `;
+}
+
+/**
+ * Generates CSS for theme-aware colors (light/dark mode support).
+ * Derived vars must be re-declared on scoped elements because
+ * CSS custom properties resolve var() at the level they are defined.
+ */
+function getThemeColorsCSS(
+  chroma: number,
+  hue: number,
+  lightness: number,
+  grayChroma: number,
+  commonVars: Record<string, string>,
+  semanticOverrides?: SemanticOverrides,
+  vibrant?: boolean,
+): string {
+  const colors = generateThemeColors({chroma, grayChroma, hue, lightness, semanticOverrides});
+
+  const lightVars = getColorVariablesForElement(colors, "light");
+  const darkVars = getColorVariablesForElement(colors, "dark");
+
+  const derivedOpts = {vibrant};
+  const colorLightVars = {...lightVars, ...getDerivedColorFormulas("light", derivedOpts)};
+  const colorDarkVars = {...darkVars, ...getDerivedColorFormulas("dark", derivedOpts)};
+
+  // Content level: colors + radius + fonts
+  const fullLightVars = {...commonVars, ...colorLightVars};
+  const fullDarkVars = {...commonVars, ...colorDarkVars};
+
+  return `
+  /* Page level: colors only */
+  :is([data-theme="light"], .light) ${PAGE_SELECTORS},
+  ${PAGE_SELECTORS}:not(:is([data-theme="dark"] *, .dark *)) {
+    ${buildVarsCSS(colorLightVars)}
+  }
+
+  :is([data-theme="dark"], .dark) ${PAGE_SELECTORS} {
+    ${buildVarsCSS(colorDarkVars)}
+  }
+
+  /* Content level: colors + radius + fonts */
+  :is([data-theme="light"], .light) :is(${CONTENT_SELECTORS}),
+  :is(${CONTENT_SELECTORS}):not(:is([data-theme="dark"] *, .dark *)) {
+    ${buildVarsCSS(fullLightVars)}
+  }
+
+  :is([data-theme="dark"], .dark) :is(${CONTENT_SELECTORS}) {
+    ${buildVarsCSS(fullDarkVars)}
+  }
+  `;
+}
+
+/**
+ * Removes existing style elements and creates a fresh one
+ */
+function injectStyleElement(id: string, css: string): HTMLStyleElement {
+  // Remove any existing style element with this ID
+  const existingStyle = document.getElementById(id);
+
+  if (existingStyle) {
+    existingStyle.remove();
+  }
+
+  // Create and inject new style element
+  const styleElement = document.createElement("style");
+
+  styleElement.id = id;
+  styleElement.textContent = css;
+  document.head.appendChild(styleElement);
+
+  return styleElement;
+}
+
+/**
+ * Style element ID for font CSS variable definition
+ */
+const FONT_VAR_STYLE_ID = "theme-builder-font-var";
+
+/**
+ * Hook that syncs theme builder store values to CSS custom properties.
+ * Should be called at the root of the theme builder page.
+ *
+ * This generates all theme colors based on the selected hue, chroma, and lightness,
+ * applying them via CSS injection for proper light/dark mode support.
+ */
+export function useCssSync() {
+  const [variables] = useVariablesState();
+  const {base, chroma, hue, lightness} = variables;
+  const accentColor = `oklch(${lightness} ${chroma} ${hue})`;
+
+  useEffect(() => {
+    // Check if this is an adaptive color that needs special light/dark variants
+    const isAdaptive = accentColor in adaptiveColors;
+
+    // Find matching theme to get semantic overrides
+    const matchingThemeId = findMatchingTheme(variables);
+    const semanticOverrides = matchingThemeId
+      ? themeValuesById[matchingThemeId].semanticOverrides
+      : undefined;
+
+    // Determine font variable - handle predefined fonts and URL-based custom fonts
+    // All fonts are now loaded on-demand via CDN
+    const fontFamily = variables.fontFamily;
+    let fontVariable: string;
+    let fontFamilyName: string;
+
+    if (isCustomFontUrl(fontFamily)) {
+      // Custom font via URL - extract info and inject
+      const customFontInfo = getCustomFontInfoFromUrl(fontFamily);
+
+      if (customFontInfo) {
+        // Inject the font stylesheet from CDN
+        injectFontLink(customFontInfo.variable, fontFamily);
+        fontVariable = customFontInfo.variable;
+        fontFamilyName = customFontInfo.fontFamily;
+      } else {
+        // Fallback to Inter if we can't parse the URL
+        const interFont = fontMap.inter;
+
+        injectFontLink(interFont.variable, interFont.cdnUrl);
+        fontVariable = interFont.variable;
+        fontFamilyName = interFont.label;
+      }
+    } else {
+      // Predefined font by ID - load on-demand via CDN
+      const predefinedFont = fontMap[fontFamily as keyof typeof fontMap] ?? fontMap.inter;
+
+      // Inject the font stylesheet from CDN
+      injectFontLink(predefinedFont.variable, predefinedFont.cdnUrl);
+      fontVariable = predefinedFont.variable;
+      fontFamilyName = predefinedFont.label;
+    }
+
+    // Build common variables (radius, font) that apply to all selectors
+    const commonVars = getCommonVariables(
+      radiusCssMap[variables.radius],
+      radiusCssMap[variables.formRadius],
+      fontVariable,
+    );
+
+    // Inject the CSS variable definition for the font
+    // All fonts (predefined and custom) are loaded via CDN and need their variable defined
+    const fontVarCSS = `:root { ${fontVariable}: "${fontFamilyName}", sans-serif; }`;
+
+    injectStyleElement(FONT_VAR_STYLE_ID, fontVarCSS);
+
+    // Remove all existing injected color styles
+    const cleanupStyles = () => {
+      [ADAPTIVE_STYLE_ID, THEME_COLORS_STYLE_ID].forEach((id) => {
+        const existing = document.getElementById(id);
+
+        if (existing) existing.remove();
+      });
+    };
+
+    cleanupStyles();
+
+    const vibrant = variables.vibrantPalette ?? false;
+
+    if (vibrant) {
+      document.documentElement.setAttribute("data-vibrant-palette", "true");
+    } else {
+      document.documentElement.removeAttribute("data-vibrant-palette");
+    }
+
+    if (isAdaptive) {
+      // Inject CSS for adaptive colors (different accent values for light/dark)
+      const adaptiveCSS = getAdaptiveColorCSS(
+        accentColor,
+        chroma,
+        hue,
+        lightness,
+        commonVars,
+        semanticOverrides,
+        vibrant,
+      );
+
+      if (adaptiveCSS) {
+        injectStyleElement(ADAPTIVE_STYLE_ID, adaptiveCSS);
+      }
+    } else {
+      // Inject CSS for standard theme colors
+      const themeColorsCSS = getThemeColorsCSS(
+        chroma,
+        hue,
+        lightness,
+        base,
+        commonVars,
+        semanticOverrides,
+        vibrant,
+      );
+
+      injectStyleElement(THEME_COLORS_STYLE_ID, themeColorsCSS);
+    }
+
+    return () => {
+      cleanupStyles();
+      document.documentElement.removeAttribute("data-vibrant-palette");
+      const existingFontVar = document.getElementById(FONT_VAR_STYLE_ID);
+
+      if (existingFontVar) {
+        existingFontVar.remove();
+      }
+    };
+  }, [
+    accentColor,
+    chroma,
+    hue,
+    lightness,
+    variables.fontFamily,
+    variables.formRadius,
+    variables.radius,
+    variables.vibrantPalette,
+    base,
+  ]);
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-custom-fonts.ts b/apps/docs/src/app/[lang]/themes/hooks/use-custom-fonts.ts
new file mode 100644
index 0000000..e623e2b
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-custom-fonts.ts
@@ -0,0 +1,219 @@
+"use client";
+
+import {useCallback, useSyncExternalStore} from "react";
+
+import {extractFontFamilyFromUrl} from "../utils/font-utils";
+
+/**
+ * Represents a custom font imported via CDN
+ */
+export interface CustomFont {
+  /** Unique identifier for the font (e.g., "custom-roboto-mono") */
+  id: string;
+  /** Display label for the font */
+  label: string;
+  /** CDN URL for the font stylesheet */
+  url: string;
+  /** CSS variable name (e.g., "--font-custom-roboto-mono") */
+  variable: string;
+  /** Font family name to use in CSS */
+  fontFamily: string;
+}
+
+const CUSTOM_FONTS_STORAGE_KEY = "theme-builder-custom-fonts";
+
+// Module-level subscribers set - all hook instances subscribe to this
+const subscribers = new Set<() => void>();
+
+// Cached snapshot to avoid creating new arrays on every read
+let cachedSnapshot: CustomFont[] = [];
+
+// Stable empty array for server snapshot (avoids creating new reference each call)
+const EMPTY_FONTS: CustomFont[] = [];
+
+/**
+ * Notify all subscribers that the fonts have changed
+ */
+function notifySubscribers() {
+  subscribers.forEach((callback) => callback());
+}
+
+/**
+ * Reads custom fonts from localStorage and updates cache
+ */
+function getCustomFontsFromStorage(): CustomFont[] {
+  if (typeof window === "undefined") return [];
+
+  try {
+    const stored = localStorage.getItem(CUSTOM_FONTS_STORAGE_KEY);
+
+    if (stored) {
+      return JSON.parse(stored) as CustomFont[];
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return [];
+}
+
+/**
+ * Saves custom fonts to localStorage and notifies subscribers
+ */
+function saveCustomFontsToStorage(fonts: CustomFont[]) {
+  try {
+    localStorage.setItem(CUSTOM_FONTS_STORAGE_KEY, JSON.stringify(fonts));
+    cachedSnapshot = fonts;
+    notifySubscribers();
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Subscribe function for useSyncExternalStore
+ */
+function subscribe(callback: () => void): () => void {
+  subscribers.add(callback);
+
+  return () => {
+    subscribers.delete(callback);
+  };
+}
+
+/**
+ * Get snapshot function for useSyncExternalStore
+ * Returns a cached array to maintain referential equality when data hasn't changed
+ */
+function getSnapshot(): CustomFont[] {
+  const current = getCustomFontsFromStorage();
+
+  // Check if we need to update the cache
+  // Compare by JSON string since arrays are always new references
+  const currentJson = JSON.stringify(current);
+  const cachedJson = JSON.stringify(cachedSnapshot);
+
+  if (currentJson !== cachedJson) {
+    cachedSnapshot = current;
+  }
+
+  return cachedSnapshot;
+}
+
+/**
+ * Server snapshot - returns stable empty array to avoid hydration mismatches
+ */
+function getServerSnapshot(): CustomFont[] {
+  return EMPTY_FONTS;
+}
+
+/**
+ * Generates a unique ID for a custom font based on its family name
+ */
+function generateFontId(fontFamily: string, existingFonts: CustomFont[]): string {
+  const baseId = `custom-${fontFamily.toLowerCase().replace(/\s+/g, "-")}`;
+  const existingIds = new Set(existingFonts.map((f) => f.id));
+
+  if (!existingIds.has(baseId)) {
+    return baseId;
+  }
+
+  // Add a number suffix if the ID already exists
+  let counter = 2;
+
+  while (existingIds.has(`${baseId}-${counter}`)) {
+    counter++;
+  }
+
+  return `${baseId}-${counter}`;
+}
+
+/**
+ * Hook to manage custom fonts stored in localStorage
+ * Uses useSyncExternalStore for automatic UI updates across all components
+ */
+export function useCustomFonts() {
+  const customFonts = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  /**
+   * Adds a new custom font from a CDN URL
+   * @returns The new font if successful, or a typed error code if failed.
+   * Error codes are translated by the consumer via the dictionary.
+   */
+  const addCustomFont = useCallback(
+    (
+      url: string,
+      customLabel?: string,
+    ):
+      | {font: CustomFont}
+      | {error: "cannot-detect-family"}
+      | {error: "already-imported"; label: string} => {
+      const currentFonts = getCustomFontsFromStorage();
+
+      // Extract font family from URL
+      const extractedFamily = extractFontFamilyFromUrl(url);
+
+      if (!extractedFamily && !customLabel) {
+        return {error: "cannot-detect-family"};
+      }
+
+      const fontFamily = customLabel || extractedFamily || "Custom Font";
+
+      // Check if this URL is already added
+      const existingByUrl = currentFonts.find((f) => f.url === url);
+
+      if (existingByUrl) {
+        return {error: "already-imported", label: existingByUrl.label};
+      }
+
+      const id = generateFontId(fontFamily, currentFonts);
+      const variable = `--font-${id}`;
+
+      const newFont: CustomFont = {
+        fontFamily,
+        id,
+        label: fontFamily,
+        url,
+        variable,
+      };
+
+      // Save and notify all subscribers
+      saveCustomFontsToStorage([...currentFonts, newFont]);
+
+      return {font: newFont};
+    },
+    [],
+  );
+
+  /**
+   * Removes a custom font by ID
+   */
+  const removeCustomFont = useCallback((id: string) => {
+    const currentFonts = getCustomFontsFromStorage();
+
+    // Save and notify all subscribers
+    saveCustomFontsToStorage(currentFonts.filter((f) => f.id !== id));
+  }, []);
+
+  /**
+   * Gets a custom font by ID
+   */
+  const getCustomFont = useCallback((id: string): CustomFont | undefined => {
+    return getCustomFontsFromStorage().find((f) => f.id === id);
+  }, []);
+
+  /**
+   * Checks if a font ID is a custom font
+   */
+  const isCustomFont = useCallback((id: string): boolean => {
+    return getCustomFontsFromStorage().some((f) => f.id === id);
+  }, []);
+
+  return {
+    addCustomFont,
+    customFonts,
+    getCustomFont,
+    isCustomFont,
+    removeCustomFont,
+  };
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-preview-tab.tsx b/apps/docs/src/app/[lang]/themes/hooks/use-preview-tab.tsx
new file mode 100644
index 0000000..4edda44
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-preview-tab.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {parseAsStringLiteral, useQueryState} from "nuqs";
+
+import {tabLabels} from "../constants";
+
+export function usePreviewTab() {
+  const [selectedTab, setSelectedTab] = useQueryState(
+    "template",
+    parseAsStringLiteral(tabLabels).withDefault("components"),
+  );
+
+  return {selectedTab, setSelectedTab};
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-randomize-variables.ts b/apps/docs/src/app/[lang]/themes/hooks/use-randomize-variables.ts
new file mode 100644
index 0000000..2e47930
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-randomize-variables.ts
@@ -0,0 +1,36 @@
+"use client";
+
+import {fontIds, radiusIds, radiusOptions} from "../constants";
+
+import {useVariablesState} from "./use-variables-state";
+
+export function useRandomizeVariables() {
+  const [variables, setVariables] = useVariablesState();
+  const randomize = () => {
+    const randomPick = <T>(arr: T[]): T => arr[Math.floor(Math.random() * arr.length)] as T;
+    const truncate2 = (v: number) => Math.round(v * 100) / 100;
+    const randomInRange = (min: number, max: number) =>
+      truncate2(min + Math.random() * (max - min));
+    const lockedVariables = variables.lockedVariables;
+
+    setVariables({
+      base: lockedVariables.includes("base") ? variables.base : Math.random() * 0.02,
+      chroma: lockedVariables.includes("chroma") ? variables.chroma : randomInRange(0.1, 0.26),
+      fontFamily: lockedVariables.includes("fontFamily")
+        ? variables.fontFamily
+        : randomPick([...fontIds]),
+      formRadius: lockedVariables.includes("formRadius")
+        ? variables.formRadius
+        : randomPick([...radiusIds]),
+      hue: lockedVariables.includes("hue") ? variables.hue : Math.floor(Math.random() * 360),
+      lightness: lockedVariables.includes("lightness")
+        ? variables.lightness
+        : randomInRange(0.5, 0.85),
+      radius: lockedVariables.includes("radius")
+        ? variables.radius
+        : randomPick([...radiusOptions.map((r) => r.id)]),
+    });
+  };
+
+  return randomize;
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-reset-variables.ts b/apps/docs/src/app/[lang]/themes/hooks/use-reset-variables.ts
new file mode 100644
index 0000000..a8af1d7
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-reset-variables.ts
@@ -0,0 +1,17 @@
+"use client";
+
+import {defaultThemeVariables} from "../constants";
+
+import {useVariablesState} from "./use-variables-state";
+
+export function useResetVariables() {
+  const [, setVariables] = useVariablesState();
+  const resetThemeVariables = () => {
+    setVariables({
+      ...defaultThemeVariables,
+      lockedVariables: [],
+    });
+  };
+
+  return resetThemeVariables;
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-toggle-locked-variable.ts b/apps/docs/src/app/[lang]/themes/hooks/use-toggle-locked-variable.ts
new file mode 100644
index 0000000..20cc246
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-toggle-locked-variable.ts
@@ -0,0 +1,27 @@
+"use client";
+
+import type {LockableThemeVariableKey} from "../constants";
+
+import {useVariablesState} from "./use-variables-state";
+
+export function useToggleLockedVariable(key: LockableThemeVariableKey) {
+  const [variables, setVariables] = useVariablesState();
+  const isLocked = variables.lockedVariables.includes(key);
+  const toggleLockedVariable = () => {
+    const lockedVariables = variables.lockedVariables;
+
+    if (isLocked) {
+      setVariables({
+        ...variables,
+        lockedVariables: lockedVariables.filter((v) => v !== key),
+      });
+    } else {
+      setVariables({
+        ...variables,
+        lockedVariables: [...lockedVariables, key],
+      });
+    }
+  };
+
+  return {isLocked, toggleLockedVariable};
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-undo-redo.ts b/apps/docs/src/app/[lang]/themes/hooks/use-undo-redo.ts
new file mode 100644
index 0000000..2bb709d
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-undo-redo.ts
@@ -0,0 +1,85 @@
+"use client";
+
+import {useSearchParams} from "next/navigation";
+import {useCallback, useEffect, useRef, useState} from "react";
+
+export function useUndoRedo() {
+  const searchParams = useSearchParams();
+  const [canUndo, setCanUndo] = useState(false);
+  const [canRedo, setCanRedo] = useState(false);
+
+  // Track our own history stack since browser doesn't expose it
+  const historyStack = useRef<string[]>([]);
+  const currentIndex = useRef(-1);
+  const isNavigating = useRef(false);
+  const lastSearchParams = useRef<string | null>(null);
+
+  // Handle URL changes from nuqs or browser navigation
+  useEffect(() => {
+    const currentParams = searchParams.toString();
+
+    // Skip if params haven't actually changed
+    if (currentParams === lastSearchParams.current) {
+      return;
+    }
+
+    lastSearchParams.current = currentParams;
+
+    if (isNavigating.current) {
+      // This change was from our undo/redo navigation
+      isNavigating.current = false;
+
+      return;
+    }
+
+    // This is a new change from nuqs (user action)
+    // Truncate any forward history and add new entry
+    historyStack.current = historyStack.current.slice(0, currentIndex.current + 1);
+    historyStack.current.push(currentParams);
+    currentIndex.current = historyStack.current.length - 1;
+
+    setCanUndo(currentIndex.current > 0);
+    setCanRedo(false);
+  }, [searchParams]);
+
+  // Listen for browser back/forward buttons
+  useEffect(() => {
+    const handlePopState = () => {
+      const currentParams = window.location.search.slice(1); // Remove leading '?'
+      const newIndex = historyStack.current.indexOf(currentParams);
+
+      if (newIndex !== -1 && newIndex !== currentIndex.current) {
+        currentIndex.current = newIndex;
+        lastSearchParams.current = currentParams;
+        setCanUndo(newIndex > 0);
+        setCanRedo(newIndex < historyStack.current.length - 1);
+      }
+    };
+
+    window.addEventListener("popstate", handlePopState);
+
+    return () => window.removeEventListener("popstate", handlePopState);
+  }, []);
+
+  const undo = useCallback(() => {
+    if (currentIndex.current > 0) {
+      isNavigating.current = true;
+      currentIndex.current--;
+      setCanUndo(currentIndex.current > 0);
+      setCanRedo(true);
+      window.history.back();
+    }
+  }, []);
+
+  const redo = useCallback(() => {
+    if (currentIndex.current < historyStack.current.length - 1) {
+      isNavigating.current = true;
+      currentIndex.current++;
+      setCanUndo(true);
+      setCanRedo(currentIndex.current < historyStack.current.length - 1);
+      window.history.forward();
+    }
+  }, []);
+
+  return {canRedo, canUndo, redo, undo};
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-variable-setter.ts b/apps/docs/src/app/[lang]/themes/hooks/use-variable-setter.ts
new file mode 100644
index 0000000..823834c
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-variable-setter.ts
@@ -0,0 +1,17 @@
+"use client";
+
+import type {ThemeVariables} from "../constants";
+
+import {useVariablesState} from "./use-variables-state";
+
+export function useVariableSetter() {
+  const [variables, setVariables] = useVariablesState();
+  const setVariable = (variable: keyof ThemeVariables, value: string) => {
+    setVariables({
+      ...variables,
+      [variable]: value,
+    });
+  };
+
+  return {setVariable, variables};
+}
diff --git a/apps/docs/src/app/[lang]/themes/hooks/use-variables-state.ts b/apps/docs/src/app/[lang]/themes/hooks/use-variables-state.ts
new file mode 100644
index 0000000..a974689
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/hooks/use-variables-state.ts
@@ -0,0 +1,32 @@
+"use client";
+
+import {
+  parseAsArrayOf,
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsString,
+  parseAsStringLiteral,
+  useQueryStates,
+} from "nuqs";
+
+import {defaultThemeVariables, radiusIds, themeVariableKeys} from "../constants";
+
+export function useVariablesState() {
+  return useQueryStates(
+    {
+      base: parseAsFloat.withDefault(defaultThemeVariables.base),
+      chroma: parseAsFloat.withDefault(defaultThemeVariables.chroma),
+      // Use parseAsString for fontFamily to allow custom fonts (prefixed with "custom-")
+      fontFamily: parseAsString.withDefault(defaultThemeVariables.fontFamily),
+      formRadius: parseAsStringLiteral(radiusIds).withDefault(defaultThemeVariables.formRadius),
+      hue: parseAsFloat.withDefault(defaultThemeVariables.hue),
+      lightness: parseAsFloat.withDefault(defaultThemeVariables.lightness),
+      lockedVariables: parseAsArrayOf(parseAsStringLiteral(themeVariableKeys)).withDefault([]),
+      radius: parseAsStringLiteral(radiusIds).withDefault(defaultThemeVariables.radius),
+      vibrantPalette: parseAsBoolean.withDefault(false),
+    },
+    {
+      history: "push",
+    },
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/page.tsx b/apps/docs/src/app/[lang]/themes/page.tsx
new file mode 100644
index 0000000..2dbaa9b
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/page.tsx
@@ -0,0 +1,67 @@
+import {Suspense} from "react";
+
+import {ProBanner} from "@/app/[lang]/(home)/components/pro-banner";
+import {CodePanelProvider} from "@/hooks/use-code-panel";
+import {DictionaryProvider} from "@/hooks/use-dictionary";
+import {getDictionary, hasLocale} from "@/lib/dictionaries";
+
+import {
+  AccentColorSelector,
+  BaseColorSlider,
+  BuilderHeader,
+  FontFamilyPopover,
+  RadiusPopover,
+  ThemePopover,
+} from "./components";
+import {MobileFooter} from "./components/mobile-footer";
+import {Onboarding} from "./components/onboarding";
+import {ThemeBuilderContent} from "./components/theme-builder-content";
+import {THEME_BUILDER_PAGE_ID, formRadiusOptions, radiusOptions} from "./constants";
+
+export default async function ThemeBuilderPage({params}: {params: Promise<{lang: string}>}) {
+  const {lang} = await params;
+  const dict = hasLocale(lang) ? await getDictionary(lang) : await getDictionary("en");
+  const radiusDict = dict.themeBuilder.radius;
+
+  return (
+    <DictionaryProvider dict={dict}>
+      <CodePanelProvider>
+        <Suspense>
+          <div
+            className="grid h-dvh grid-rows-[auto_1fr_auto] bg-background px-4 sm:overflow-hidden sm:px-6"
+            id={THEME_BUILDER_PAGE_ID}
+          >
+            <BuilderHeader />
+            <ThemeBuilderContent />
+            <div className="mx-auto hidden items-center justify-between gap-4 py-6 max-[1200px]:flex-col sm:flex">
+              <div className="flex items-center gap-4">
+                <AccentColorSelector />
+                <BaseColorSlider />
+                <FontFamilyPopover />
+              </div>
+              <div className="flex items-center gap-4">
+                <RadiusPopover
+                  description={radiusDict.description}
+                  label={radiusDict.label}
+                  radiusOptions={radiusOptions}
+                  variableKey="radius"
+                />
+                <RadiusPopover
+                  description={radiusDict.formDescription}
+                  label={radiusDict.formLabel}
+                  radiusOptions={formRadiusOptions}
+                  variableKey="formRadius"
+                />
+                <ThemePopover />
+              </div>
+            </div>
+            <div className="h-20 w-full sm:hidden" />
+            <MobileFooter />
+          </div>
+          <Onboarding />
+          <ProBanner />
+        </Suspense>
+      </CodePanelProvider>
+    </DictionaryProvider>
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/theme-values.ts b/apps/docs/src/app/[lang]/themes/theme-values.ts
new file mode 100644
index 0000000..52f16be
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/theme-values.ts
@@ -0,0 +1,327 @@
+// Base constants for theme values
+export const DEFAULT_BASE = 0.0015 as const;
+const BASE_FULL_LEFT = 0 as const;
+const BASE_10P_LEFT = 0.002 as const;
+const BASE_50P = 0.01 as const;
+
+// Radius options - defined here to avoid circular dependency
+export const radiusIds = [
+  "none",
+  "extra-small",
+  "small",
+  "medium",
+  "large",
+  "extra-large",
+] as const;
+
+export type RadiusId = (typeof radiusIds)[number];
+
+/**
+ * Semantic color override for a single color (success, warning, or danger)
+ */
+export interface SemanticColorOverride {
+  /** OKLCH color string e.g. "oklch(0.5148 0.1337 146.82)" */
+  color: string;
+  /** Optional foreground color - if not provided, will be calculated automatically */
+  foreground?: string;
+}
+
+/**
+ * Semantic color overrides for light and dark modes.
+ * Allows themes to specify exact semantic colors instead of using calculated values.
+ */
+export interface ThemeSemanticOverrides {
+  light?: {
+    /** Override the accent foreground color (text on accent background) */
+    accentForeground?: string;
+    danger?: SemanticColorOverride;
+    success?: SemanticColorOverride;
+    warning?: SemanticColorOverride;
+  };
+  dark?: {
+    /** Override the accent foreground color (text on accent background) */
+    accentForeground?: string;
+    danger?: SemanticColorOverride;
+    success?: SemanticColorOverride;
+    warning?: SemanticColorOverride;
+  };
+}
+
+export type ThemeValues = {
+  base: number;
+  chroma: number;
+  fontFamily: string;
+  formRadius: RadiusId;
+  hue: number;
+  lightness: number;
+  radius: RadiusId;
+  /** Optional semantic color overrides for light/dark modes */
+  semanticOverrides?: ThemeSemanticOverrides;
+  /** Use vibrant (more saturated) soft foreground colors instead of accessible defaults */
+  vibrantPalette?: boolean;
+};
+
+export const defaultThemeValues: ThemeValues = {
+  base: DEFAULT_BASE,
+  chroma: 0.195,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 253.83,
+  lightness: 0.6204,
+  radius: "medium",
+} as const;
+
+export const skyThemeValues: ThemeValues = {
+  base: DEFAULT_BASE,
+  chroma: 0.16,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 225,
+  lightness: 0.78,
+  radius: "medium",
+} as const;
+
+export const lavenderThemeValues: ThemeValues = {
+  base: DEFAULT_BASE,
+  chroma: 0.13,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 305,
+  lightness: 0.77,
+  radius: "medium",
+} as const;
+
+export const mintThemeValues: ThemeValues = {
+  base: DEFAULT_BASE,
+  chroma: 0.12,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 155,
+  lightness: 0.82,
+  radius: "medium",
+} as const;
+
+export const netflixThemeValues: ThemeValues = {
+  base: BASE_FULL_LEFT,
+  chroma: 0.2349,
+  fontFamily: "inter",
+  formRadius: "extra-small",
+  hue: 27.99,
+  lightness: 0.5814,
+  radius: "extra-small",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.4964 0.1994 28.56)"}, // #B9090B
+      success: {color: "oklch(0.7677 0.1899 148.1)"}, // #46D369
+      warning: {color: "oklch(0.8239 0.153 74.6)"}, // #FFB53F
+    },
+    light: {
+      danger: {color: "oklch(0.4823 0.1938 27.64)"}, // #B20710
+      success: {color: "oklch(0.5148 0.1337 146.82)"}, // #237b35
+      warning: {color: "oklch(0.561 0.116571 78.9352)"}, // #996b00
+    },
+  },
+} as const;
+
+export const uberThemeValues: ThemeValues = {
+  base: BASE_FULL_LEFT,
+  chroma: 0,
+  fontFamily: "inter",
+  formRadius: "small",
+  hue: 0,
+  lightness: 0,
+  radius: "small",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.7044 0.1872 23.19)"}, // #FF6666
+      success: {color: "oklch(0.6514 0.1321 156.22)"}, // #3AA76D
+      warning: {color: "oklch(0.8803 0.1348 86.06)"}, // #FFD166
+    },
+    light: {
+      danger: {color: "oklch(0.573 0.2249 21.97)"}, // #DE1135
+      success: {color: "oklch(0.6277 0.1604 153.06)"}, // #05A357
+      warning: {color: "oklch(0.8446 0.1525 80.6)"}, // #FFC043
+    },
+  },
+} as const;
+
+export const spotifyThemeValues: ThemeValues = {
+  base: BASE_10P_LEFT,
+  chroma: 0.2124,
+  fontFamily: "inter",
+  formRadius: "extra-small",
+  hue: 148.67,
+  lightness: 0.7697,
+  radius: "medium",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.5931 0.2338 25.42)"}, // #E91429
+      success: {color: "oklch(0.7697 0.2124 148.67)"}, // #1ED760
+      warning: {color: "oklch(0.7921 0.1626 67.42)"}, // #FFA42B
+    },
+    light: {
+      danger: {color: "oklch(0.5509 0.2166 25.29)"}, // #D31225
+      success: {color: "oklch(0.6072 0.1647 149.02)"}, // #169C46
+      warning: {color: "oklch(0.6972 0.1687 54.22)"}, // #EB7B15
+    },
+  },
+} as const;
+
+export const coinbaseThemeValues: ThemeValues = {
+  base: BASE_10P_LEFT,
+  chroma: 0.2628,
+  fontFamily: "inter",
+  formRadius: "extra-small",
+  hue: 262.87,
+  lightness: 0.5282,
+  radius: "medium",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.6545 0.2145 22.31)"}, // #F84550
+      success: {color: "oklch(0.7574 0.180554 156.931)"}, // #00D180
+      warning: {color: "oklch(0.8095 0.1119 61.69)"}, // #F5B073
+    },
+    light: {
+      danger: {color: "oklch(0.5507 0.2062 24)"}, // #CF202F
+      success: {color: "oklch(0.5438 0.1268 157.17)"}, // #098551
+      warning: {color: "oklch(0.8095 0.1119 61.69)"}, // #F5B073
+    },
+  },
+} as const;
+
+export const airbnbThemeValues: ThemeValues = {
+  base: BASE_FULL_LEFT,
+  chroma: 0.2309,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 17.07,
+  lightness: 0.6579,
+  radius: "medium",
+  semanticOverrides: {
+    dark: {
+      accentForeground: "oklch(0.9911 0 0)", // white
+      danger: {color: "oklch(0.5392 0.1816 33.72)", foreground: "oklch(0.9911 0 0)"}, // #C13515, white fg
+      success: {color: "oklch(0.652 0.114864 185.0749)", foreground: "oklch(0.9911 0 0)"}, // #00A699, white fg
+      warning: {color: "oklch(0.8197 0.170602 78.4658)"}, // #FFB400
+    },
+    light: {
+      accentForeground: "oklch(0.9911 0 0)", // white
+      danger: {color: "oklch(0.5392 0.1816 33.72)", foreground: "oklch(0.9911 0 0)"}, // #C13515, white fg
+      success: {color: "oklch(0.5573 0.0947 199.48)", foreground: "oklch(0.9911 0 0)"}, // #008489, white fg
+      warning: {color: "oklch(0.6904 0.1972 38.75)", foreground: "oklch(0.9911 0 0)"}, // #FC642D, white fg
+    },
+  },
+} as const;
+
+export const discordThemeValues: ThemeValues = {
+  base: BASE_50P,
+  chroma: 0.2091,
+  fontFamily: "inter",
+  formRadius: "large",
+  hue: 273.85,
+  lightness: 0.5774,
+  radius: "small",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.6318 0.2075 24.57)"}, // #ED4245
+      success: {color: "oklch(0.8548 0.1967 150.16)"}, // #57F287
+      warning: {color: "oklch(0.9218 0.1571 99.87)"}, // #FEE75C
+    },
+    light: {
+      danger: {color: "oklch(0.5884 0.1993 24.39)"}, // #DA373C
+      success: {color: "oklch(0.532 0.1238 151.57)"}, // #248046
+      warning: {color: "oklch(0.9218 0.1571 99.87)"}, // #FEE75C
+    },
+  },
+} as const;
+
+export const rabbitThemeValues: ThemeValues = {
+  base: BASE_50P,
+  chroma: 0.2232,
+  fontFamily: "inter",
+  formRadius: "extra-large",
+  hue: 36.66,
+  lightness: 0.6678,
+  radius: "medium",
+  semanticOverrides: {
+    dark: {
+      danger: {color: "oklch(0.6291 0.2565 29.09)"}, // #FF0606
+      success: {color: "oklch(0.7113 0.2043 140.81)"}, // #4ABF34
+    },
+    light: {
+      danger: {color: "oklch(0.6291 0.2565 29.09)"}, // #FF0606
+      success: {color: "oklch(0.7113 0.2043 140.81)"}, // #4ABF34
+    },
+  },
+} as const;
+
+export const themeIds = [
+  "default",
+  "sky",
+  "lavender",
+  "mint",
+  "netflix",
+  "uber",
+  "spotify",
+  "coinbase",
+  "airbnb",
+  "discord",
+  "rabbit",
+] as const;
+
+export type ThemeId = (typeof themeIds)[number];
+
+export const themeValuesById: Record<ThemeId, ThemeValues> = {
+  airbnb: airbnbThemeValues,
+  coinbase: coinbaseThemeValues,
+  default: defaultThemeValues,
+  discord: discordThemeValues,
+  lavender: lavenderThemeValues,
+  mint: mintThemeValues,
+  netflix: netflixThemeValues,
+  rabbit: rabbitThemeValues,
+  sky: skyThemeValues,
+  spotify: spotifyThemeValues,
+  uber: uberThemeValues,
+} as const;
+
+/**
+ * Keys that define a theme's appearance.
+ * Used for comparing current values against predefined themes.
+ */
+export const themeComparisonKeys = [
+  "base",
+  "chroma",
+  "fontFamily",
+  "formRadius",
+  "hue",
+  "lightness",
+  "radius",
+] as const satisfies readonly (keyof ThemeValues)[];
+
+/**
+ * Find which predefined theme matches the current variable values.
+ * Returns undefined if no theme matches (i.e., it's a custom theme).
+ */
+export function findMatchingTheme(currentValues: ThemeValues): ThemeId | undefined {
+  for (const themeId of themeIds) {
+    const themeValues = themeValuesById[themeId];
+    const matches = themeComparisonKeys.every((key) => {
+      const current = currentValues[key];
+      const theme = themeValues[key];
+
+      // For numbers, use approximate comparison to handle floating point
+      if (typeof current === "number" && typeof theme === "number") {
+        return Math.abs(current - theme) < 0.0001;
+      }
+
+      return current === theme;
+    });
+
+    if (matches) {
+      return themeId;
+    }
+  }
+
+  return undefined;
+}
diff --git a/apps/docs/src/app/[lang]/themes/utils/calculate-foreground.ts b/apps/docs/src/app/[lang]/themes/utils/calculate-foreground.ts
new file mode 100644
index 0000000..00a90ae
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/utils/calculate-foreground.ts
@@ -0,0 +1,24 @@
+/**
+ * Calculates the foreground color for a given OKLCH string.
+ */
+export function calculateForeground(oklchString: string): string {
+  // Parse OKLCH - format: oklch(L C H) or oklch(L% C H), hue can be "none" for achromatic colors
+  const match = oklchString.match(/oklch\((\d+\.?\d*)%?\s+(\d+\.?\d*)\s+(\d+\.?\d*|none)/);
+
+  if (!match || !match[1] || !match[2] || !match[3]) return "var(--snow)"; // fallback
+
+  const l = parseFloat(match[1]);
+  const c = parseFloat(match[2]);
+  const h = match[3] === "none" ? 0 : parseFloat(match[3]);
+
+  // Normalize lightness if given as percentage (0-100) vs decimal (0-1)
+  const lightness = l > 1 ? l / 100 : l;
+
+  // OKLCH lightness is perceptually uniform, so 0.65 is a good threshold
+  const foreground =
+    lightness > 0.65
+      ? `oklch(0.15 ${Math.min(c * 0.3, 0.05)} ${h})`
+      : `oklch(0.98 ${Math.min(c * 0.1, 0.02)} ${h})`;
+
+  return foreground;
+}
diff --git a/apps/docs/src/app/[lang]/themes/utils/compare-theme-variables.ts b/apps/docs/src/app/[lang]/themes/utils/compare-theme-variables.ts
new file mode 100644
index 0000000..b657544
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/utils/compare-theme-variables.ts
@@ -0,0 +1,16 @@
+import type {ThemeVariables} from "../constants";
+
+export function compareThemeVariables(
+  variables: ThemeVariables,
+  snapshotVariables: ThemeVariables,
+) {
+  return (
+    variables.chroma === snapshotVariables.chroma &&
+    variables.hue === snapshotVariables.hue &&
+    variables.lightness === snapshotVariables.lightness &&
+    variables.fontFamily === snapshotVariables.fontFamily &&
+    variables.formRadius === snapshotVariables.formRadius &&
+    variables.radius === snapshotVariables.radius &&
+    variables.base === snapshotVariables.base
+  );
+}
diff --git a/apps/docs/src/app/[lang]/themes/utils/font-utils.ts b/apps/docs/src/app/[lang]/themes/utils/font-utils.ts
new file mode 100644
index 0000000..d7287c2
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/utils/font-utils.ts
@@ -0,0 +1,299 @@
+/**
+ * Utility functions for handling custom fonts
+ */
+
+/**
+ * List of allowed CDN hosts for font imports.
+ * Only fonts from these trusted sources will be loaded.
+ */
+const ALLOWED_FONT_CDN_HOSTS = [
+  "fonts.googleapis.com",
+  "fonts.gstatic.com",
+  "api.fontshare.com",
+  "cdnfonts.com", // Matches www.cdnfonts.com, fonts.cdnfonts.com, etc.
+];
+
+/**
+ * Allowed path prefixes for jsdelivr CDN (for Fontsource fonts only)
+ * This prevents loading arbitrary code from jsdelivr while allowing Fontsource fonts
+ */
+const JSDELIVR_ALLOWED_PATHS = [
+  "/fontsource/fonts/", // Fontsource direct path
+  "/npm/@fontsource/", // Fontsource npm package
+  "/npm/@fontsource-variable/", // Fontsource variable fonts
+];
+
+/**
+ * Validates if a URL is from an allowed font CDN host and uses HTTPS.
+ * This is a security check to prevent loading malicious resources.
+ */
+export function isValidFontCdnUrl(url: string): boolean {
+  try {
+    const parsedUrl = new URL(url);
+
+    // Must be HTTPS
+    if (parsedUrl.protocol !== "https:") {
+      return false;
+    }
+
+    // Special handling for jsdelivr - only allow Fontsource paths
+    if (parsedUrl.hostname === "cdn.jsdelivr.net") {
+      return JSDELIVR_ALLOWED_PATHS.some((prefix) => parsedUrl.pathname.startsWith(prefix));
+    }
+
+    // Must be from an allowed host
+    return ALLOWED_FONT_CDN_HOSTS.some(
+      (host) => parsedUrl.hostname === host || parsedUrl.hostname.endsWith(`.${host}`),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if a fontFamily value is a valid CDN URL (for custom fonts)
+ * Only returns true if it's a valid URL from an allowed CDN host
+ */
+export function isCustomFontUrl(fontFamily: string): boolean {
+  if (!fontFamily.startsWith("https://")) {
+    return false;
+  }
+
+  return isValidFontCdnUrl(fontFamily);
+}
+
+/**
+ * Extracts font family name from a font CDN URL
+ * Supports Google Fonts, Fontshare, Fontsource, CDNfonts, and similar CDNs
+ *
+ * Examples:
+ * - Google: https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400 -> "Roboto Mono"
+ * - Fontshare: https://api.fontshare.com/v2/css?f[]=chillax@400&display=swap -> "Chillax"
+ * - Fontsource: https://cdn.jsdelivr.net/npm/@fontsource/lato@latest/index.css -> "Lato"
+ * - Fontsource: https://cdn.jsdelivr.net/fontsource/fonts/lato@latest/latin-400-normal.woff2 -> "Lato"
+ * - CDNfonts: https://fonts.cdnfonts.com/css/stasiun -> "Stasiun"
+ */
+export function extractFontFamilyFromUrl(url: string): string | null {
+  try {
+    const parsedUrl = new URL(url);
+
+    // Google Fonts format: family=Font+Name or family=Font+Name:wght@...
+    const familyParam = parsedUrl.searchParams.get("family");
+
+    if (familyParam) {
+      // Handle multiple families (take the first one)
+      const firstFamily = familyParam.split("|")[0] ?? "";
+      // Remove weight/style specifiers (everything after :)
+      const familyName = firstFamily.split(":")[0] ?? "";
+
+      // Replace + with space
+      return familyName.replace(/\+/g, " ") || null;
+    }
+
+    // Fontshare format: f[]=fontname@weight (e.g., f[]=chillax@400)
+    const fontshareParam = parsedUrl.searchParams.get("f[]");
+
+    if (fontshareParam) {
+      // Extract font name before @ (e.g., "chillax@400" -> "chillax")
+      const fontName = fontshareParam.split("@")[0] ?? "";
+
+      if (fontName) {
+        // Capitalize first letter of each word
+        return fontName.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+      }
+    }
+
+    // Fontsource npm format: /npm/@fontsource/font-name@version/...
+    // or /npm/@fontsource-variable/font-name@version/...
+    const fontsourceNpmMatch = parsedUrl.pathname.match(
+      /\/npm\/@fontsource(?:-variable)?\/([^@/]+)/,
+    );
+
+    if (fontsourceNpmMatch?.[1]) {
+      return fontsourceNpmMatch[1].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+
+    // Fontsource direct format: /fontsource/fonts/font-name@version/... or /fontsource/fonts/font-name:vf@version/...
+    const fontsourceDirectMatch = parsedUrl.pathname.match(/\/fontsource\/fonts\/([^@/:]+)/);
+
+    if (fontsourceDirectMatch?.[1]) {
+      return fontsourceDirectMatch[1].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+
+    // CDNfonts page format: /font-name.font (e.g., https://www.cdnfonts.com/stasiun.font)
+    const cdnfontsPageMatch = parsedUrl.pathname.match(/\/([^/]+)\.font$/);
+
+    if (cdnfontsPageMatch?.[1]) {
+      return cdnfontsPageMatch[1].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+
+    // CDNfonts CSS format: /css/font-name (e.g., https://fonts.cdnfonts.com/css/stasiun)
+    const cdnfontsCssMatch = parsedUrl.pathname.match(/\/css\/([^/?]+)/);
+
+    if (cdnfontsCssMatch?.[1]) {
+      return cdnfontsCssMatch[1].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+
+    // Generic CSS file format: /path/font-name.css
+    const pathMatch = url.match(/\/([^/]+)\.css/);
+
+    if (pathMatch?.[1]) {
+      return pathMatch[1].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Font file extensions that require @font-face generation
+ */
+const FONT_FILE_EXTENSIONS = [".woff2", ".woff", ".ttf", ".otf", ".eot"];
+
+/**
+ * Checks if a URL points to a font file (vs a CSS stylesheet)
+ */
+export function isFontFileUrl(url: string): boolean {
+  try {
+    const pathname = new URL(url).pathname.toLowerCase();
+
+    return FONT_FILE_EXTENSIONS.some((ext) => pathname.endsWith(ext));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generates @font-face CSS for a font file URL
+ * Supports Fontsource variable fonts and static fonts
+ */
+function generateFontFaceCSS(fontFamily: string, url: string): string {
+  // Detect variable fonts by URL patterns
+  const isVariable = url.includes(":vf@") || url.includes("-wght-") || url.includes("-opsz-");
+
+  // Determine format based on file extension and variable font status
+  let format = "woff2";
+
+  if (url.endsWith(".woff")) {
+    format = "woff";
+  } else if (url.endsWith(".ttf")) {
+    format = "truetype";
+  } else if (url.endsWith(".otf")) {
+    format = "opentype";
+  } else if (isVariable && url.endsWith(".woff2")) {
+    format = "woff2-variations";
+  }
+
+  // Variable fonts support weight range, static fonts use 400
+  const fontWeight = isVariable ? "100 900" : "400";
+
+  return `
+@font-face {
+  font-family: '${fontFamily}';
+  font-style: normal;
+  font-display: swap;
+  font-weight: ${fontWeight};
+  src: url(${url}) format('${format}');
+}
+`.trim();
+}
+
+/**
+ * Injects a font into the document.
+ * - For CSS stylesheet URLs: injects a <link> element
+ * - For font file URLs: generates @font-face CSS and injects a <style> element
+ *
+ * @param id - Unique identifier for this font
+ * @param url - CDN URL for the font (stylesheet or font file)
+ * @param fontFamily - Font family name (required for font files)
+ * @returns The injected element
+ */
+export function injectFontLink(
+  id: string,
+  url: string,
+  fontFamily?: string,
+): HTMLLinkElement | HTMLStyleElement | null {
+  if (typeof document === "undefined") return null;
+
+  const elementId = `font-link-${id}`;
+  const existingElement = document.getElementById(elementId);
+
+  if (existingElement) {
+    return existingElement as HTMLLinkElement | HTMLStyleElement;
+  }
+
+  // Check if this is a font file URL that needs @font-face generation
+  if (isFontFileUrl(url)) {
+    // For font files, we need the font family name to generate @font-face
+    const family = fontFamily || extractFontFamilyFromUrl(url);
+
+    if (!family) {
+      console.warn("Could not determine font family for font file:", url);
+
+      return null;
+    }
+
+    const styleElement = document.createElement("style");
+
+    styleElement.id = elementId;
+    styleElement.textContent = generateFontFaceCSS(family, url);
+    document.head.appendChild(styleElement);
+
+    return styleElement;
+  }
+
+  // For CSS stylesheet URLs, use a <link> element
+  const linkElement = document.createElement("link");
+
+  linkElement.id = elementId;
+  linkElement.rel = "stylesheet";
+  linkElement.href = url;
+  document.head.appendChild(linkElement);
+
+  return linkElement;
+}
+
+/**
+ * Removes a font element by ID
+ */
+export function removeFontLink(id: string): void {
+  if (typeof document === "undefined") return;
+
+  const elementId = `font-link-${id}`;
+  const existingElement = document.getElementById(elementId);
+
+  if (existingElement) {
+    existingElement.remove();
+  }
+}
+
+/**
+ * Gets font info from a URL for CSS generation.
+ * Returns null if the URL is invalid or not from a trusted CDN.
+ */
+export function getCustomFontInfoFromUrl(url: string): {
+  fontFamily: string;
+  label: string;
+  url: string;
+  variable: string;
+} | null {
+  // Security: Validate URL is from a trusted CDN before processing
+  if (!isValidFontCdnUrl(url)) {
+    return null;
+  }
+
+  const fontFamily = extractFontFamilyFromUrl(url);
+
+  if (!fontFamily) return null;
+
+  const id = `custom-${fontFamily.toLowerCase().replace(/\s+/g, "-")}`;
+
+  return {
+    fontFamily,
+    label: fontFamily,
+    url,
+    variable: `--font-${id}`,
+  };
+}
diff --git a/apps/docs/src/app/[lang]/themes/utils/generate-css-variables.ts b/apps/docs/src/app/[lang]/themes/utils/generate-css-variables.ts
new file mode 100644
index 0000000..ff0a9f4
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/utils/generate-css-variables.ts
@@ -0,0 +1,190 @@
+import type {ThemeVariables} from "../constants";
+import type {GeneratedThemeColors, SemanticOverrides, ThemeColor} from "./generate-theme-colors";
+
+import {
+  adaptiveColors,
+  findMatchingTheme,
+  fontMap,
+  radiusCssMap,
+  themeValuesById,
+} from "../constants";
+
+/**
+ * Custom font info for generating CSS variables
+ */
+export interface CustomFontInfo {
+  label: string;
+  variable: string;
+  fontFamily: string;
+}
+
+import {calculateAccentForeground, generateThemeColors, parseOklch} from "./generate-theme-colors";
+
+/**
+ * Get only the authored CSS variables that users need to customize.
+ * Derived variables are provided by the default theme stylesheet.
+ */
+function getBaseColorVariables(
+  colors: GeneratedThemeColors,
+  theme: "light" | "dark",
+): Record<string, string> {
+  const isLight = theme === "light";
+  const getValue = (color: ThemeColor) => (isLight ? color.oklchLight : color.oklchDark);
+
+  return {
+    "--accent": getValue(colors.accent),
+    "--accent-foreground": getValue(colors.accentForeground),
+    "--background": getValue(colors.background),
+    "--border": getValue(colors.border),
+    "--danger": getValue(colors.danger),
+    "--danger-foreground": getValue(colors.dangerForeground),
+    "--default": getValue(colors.default),
+    "--default-foreground": getValue(colors.defaultForeground),
+    "--field-background": getValue(colors.fieldBackground),
+    "--field-border": "transparent",
+    "--field-foreground": getValue(colors.fieldForeground),
+    "--field-placeholder": getValue(colors.fieldPlaceholder),
+    "--focus": getValue(colors.focus),
+    "--foreground": getValue(colors.foreground),
+    "--muted": getValue(colors.muted),
+    "--overlay": getValue(colors.overlay),
+    "--overlay-foreground": getValue(colors.overlayForeground),
+    "--scrollbar": getValue(colors.scrollbar),
+    "--segment": getValue(colors.segment),
+    "--segment-foreground": getValue(colors.segmentForeground),
+    "--separator": getValue(colors.separator),
+    "--success": getValue(colors.success),
+    "--success-foreground": getValue(colors.successForeground),
+    "--surface": getValue(colors.surface),
+    "--surface-foreground": getValue(colors.surfaceForeground),
+    "--surface-secondary": getValue(colors.surfaceSecondary),
+    "--surface-secondary-foreground": getValue(colors.surfaceSecondaryForeground),
+    "--surface-tertiary": getValue(colors.surfaceTertiary),
+    "--surface-tertiary-foreground": getValue(colors.surfaceTertiaryForeground),
+    "--warning": getValue(colors.warning),
+    "--warning-foreground": getValue(colors.warningForeground),
+  };
+}
+
+/**
+ * Generates CSS output with only the variables users need to customize.
+ * Derived variables are automatically computed by the default theme stylesheet.
+ *
+ * @param variables - Theme variables from the builder
+ * @param customFont - Optional custom font info when using a CDN font
+ */
+export function generateMinimalCssVariables(
+  variables: ThemeVariables,
+  customFont?: CustomFontInfo,
+): string {
+  // Check if this is a predefined font
+  const fontId = variables.fontFamily;
+  const isPredefinedFont = fontId in fontMap;
+  const predefinedFont = isPredefinedFont ? fontMap[fontId as keyof typeof fontMap] : undefined;
+
+  const {base, chroma, hue, lightness} = variables;
+  const accentColor = `oklch(${lightness} ${chroma} ${hue})`;
+  const adaptiveConfig = adaptiveColors[accentColor];
+
+  // Find matching theme to get semantic overrides
+  const matchingThemeId = findMatchingTheme(variables);
+  const semanticOverrides: SemanticOverrides | undefined = matchingThemeId
+    ? themeValuesById[matchingThemeId].semanticOverrides
+    : undefined;
+
+  // Generate theme colors
+  const colors = generateThemeColors({chroma, grayChroma: base, hue, lightness, semanticOverrides});
+
+  // Get base variables for both themes
+  const lightVars = getBaseColorVariables(colors, "light");
+  const darkVars = getBaseColorVariables(colors, "dark");
+
+  // Override accent for adaptive colors (like black/white)
+  if (adaptiveConfig) {
+    const lightAccent = parseOklch(adaptiveConfig.light);
+    const darkAccent = parseOklch(adaptiveConfig.dark);
+
+    const lightFg = lightAccent
+      ? calculateAccentForeground(lightAccent.l, lightAccent.c, lightAccent.h)
+      : calculateAccentForeground(0, 0, 0);
+    const darkFg = darkAccent
+      ? calculateAccentForeground(darkAccent.l, darkAccent.c, darkAccent.h)
+      : calculateAccentForeground(1, 0, 0);
+
+    lightVars["--accent"] = adaptiveConfig.light;
+    lightVars["--accent-foreground"] = lightFg;
+    lightVars["--accent-soft-foreground"] = adaptiveConfig.light;
+    lightVars["--focus"] = adaptiveConfig.light;
+
+    darkVars["--accent"] = adaptiveConfig.dark;
+    darkVars["--accent-foreground"] = darkFg;
+    darkVars["--accent-soft-foreground"] = adaptiveConfig.dark;
+    darkVars["--focus"] = adaptiveConfig.dark;
+  }
+
+  // Build CSS strings
+  const lightVarsCSS = Object.entries(lightVars)
+    .map(([prop, val]) => `  ${prop}: ${val};`)
+    .join("\n");
+
+  const darkVarsCSS = Object.entries(darkVars)
+    .map(([prop, val]) => `  ${prop}: ${val};`)
+    .join("\n");
+
+  // Determine font values based on whether it's predefined or custom
+  let fontLabel: string;
+  let fontSansValue: string;
+
+  if (predefinedFont) {
+    fontLabel = predefinedFont.label;
+    fontSansValue = `var(${predefinedFont.variable})`;
+  } else if (customFont) {
+    fontLabel = customFont.label;
+    fontSansValue = `"${customFont.fontFamily}", sans-serif`;
+  } else {
+    // Fallback for unknown font
+    fontLabel = "your custom font";
+    fontSansValue = "var(--font-sans)";
+  }
+
+  const vibrantComment = variables.vibrantPalette
+    ? `
+/*
+ * Vibrant Palette: Add data-vibrant-palette="true" to your <html> element
+ * for more saturated soft foreground colors (less accessible contrast).
+ * Example: <html data-vibrant-palette="true">
+ */
+`
+    : "";
+
+  return `/*
+ * HeroUI Theme Customization
+ * Add this to your global.css after importing @heroui/styles
+ * Only includes variables users need to customize
+ * @see https://heroui.com/docs/react/getting-started/theming
+ */
+${vibrantComment}
+:root,
+.light,
+.default,
+[data-theme="light"],
+[data-theme="default"] {
+  /* Theme Colors (Light Mode) */
+${lightVarsCSS}
+
+  /* Border Radius */
+  --radius: ${radiusCssMap[variables.radius]};
+  --field-radius: ${radiusCssMap[variables.formRadius]};
+
+  /* Font Family */
+  /* Make sure to load ${fontLabel} font in your app */
+  --font-sans: ${fontSansValue};
+}
+
+.dark,
+[data-theme="dark"] {
+  color-scheme: dark;
+  /* Theme Colors (Dark Mode) */
+${darkVarsCSS}
+}`;
+}
diff --git a/apps/docs/src/app/[lang]/themes/utils/generate-theme-colors.ts b/apps/docs/src/app/[lang]/themes/utils/generate-theme-colors.ts
new file mode 100644
index 0000000..1ae0686
--- /dev/null
+++ b/apps/docs/src/app/[lang]/themes/utils/generate-theme-colors.ts
@@ -0,0 +1,858 @@
+/**
+ * Color generation utilities for the HeroUI Theme Builder
+ * Generates all theme colors based on hue, chroma, AND lightness adjustments
+ *
+ * Based on packages/storybook/.storybook/utils/apcach-colors.ts but extended
+ * to support lightness customization for accent colors.
+ */
+
+/* -------------------------------------------------------------------------------------------------
+ * Default Theme Values (from packages/styles/themes/default/variables.css)
+ * -----------------------------------------------------------------------------------------------*/
+
+// Default accent values from variables.css: oklch(0.6204 0.195 253.83)
+export const DEFAULT_ACCENT = {
+  chroma: 0.195,
+  hue: 253.83,
+  lightness: 0.6204,
+};
+
+const SEMANTIC_HUE_BLEND_FACTOR = 0.12; // 12% influence from base hue
+
+// Default theme values from variables.css - these are the baseline that will be adjusted
+const DEFAULT_THEME_VALUES = {
+  dark: {
+    background: {c: 0.005, h: 285.823, l: 0.12},
+    border: {c: 0.006, h: 286.033, l: 0.28},
+    default: {c: 0.006, h: 286.033, l: 0.274},
+
+    foreground: {c: 0, h: 0, l: 0.9911},
+
+    muted: {c: 0.015, h: 286.067, l: 0.705},
+
+    overlay: {c: 0.0059, h: 285.89, l: 0.2103},
+
+    scrollbar: {c: 0.015, h: 286.067, l: 0.705},
+
+    segment: {c: 0.01, h: 285.93, l: 0.3964},
+
+    separator: {c: 0.006, h: 286.033, l: 0.25},
+    // Snow
+    surface: {c: 0.0059, h: 285.89, l: 0.2103},
+    surfaceSecondary: {c: 0.0037, h: 286.14, l: 0.257},
+    surfaceTertiary: {c: 0.0024, h: 247.91, l: 0.2721},
+  },
+  light: {
+    background: {c: 0, h: 0, l: 0.9702},
+    border: {c: 0.004, h: 286.32, l: 0.9},
+
+    default: {c: 0.001, h: 286.375, l: 0.94},
+
+    foreground: {c: 0.0059, h: 285.89, l: 0.2103},
+
+    // Pure white
+    muted: {c: 0.0138, h: 285.94, l: 0.5517},
+    // Pure white
+    overlay: {c: 0, h: 0, l: 1},
+    scrollbar: {c: 0.006, h: 286.286, l: 0.871},
+    segment: {c: 0, h: 0, l: 1},
+    separator: {c: 0.004, h: 286.32, l: 0.92},
+    surface: {c: 0, h: 0, l: 1}, // Pure white
+    surfaceSecondary: {c: 0.0013, h: 286.37, l: 0.9524},
+    surfaceTertiary: {c: 0.0013, h: 286.37, l: 0.9373},
+  },
+};
+
+// Semantic color defaults (from variables.css)
+const SEMANTIC_COLORS = {
+  danger: {
+    chromaDark: 0.1967,
+    chromaLight: 0.2328,
+    hue: 25.74,
+    hueDark: 24.63,
+    lightnessDark: 0.594,
+    lightnessLight: 0.6532,
+  },
+  success: {
+    chromaDark: 0.1935,
+    chromaLight: 0.1935,
+    hue: 150.81,
+    lightnessDark: 0.7329,
+    lightnessLight: 0.7329,
+  },
+  warning: {
+    chromaDark: 0.1388,
+
+    // Warning hue for dark theme (different from light theme)
+    chromaLight: 0.1585,
+    hue: 72.33,
+    hueDark: 76.34,
+    lightnessDark: 0.8203,
+    lightnessLight: 0.7819,
+  },
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Types
+ * -----------------------------------------------------------------------------------------------*/
+
+export interface OklchColor {
+  l: number;
+  c: number;
+  h: number;
+}
+
+export interface ThemeColor {
+  name: string;
+  oklchLight: string;
+  oklchDark: string;
+}
+
+export interface GeneratedThemeColors {
+  // Core colors
+  background: ThemeColor;
+  foreground: ThemeColor;
+  accent: ThemeColor;
+  accentForeground: ThemeColor;
+  focus: ThemeColor;
+
+  // UI colors
+  muted: ThemeColor;
+  default: ThemeColor;
+  defaultForeground: ThemeColor;
+  surface: ThemeColor;
+  surfaceForeground: ThemeColor;
+  surfaceSecondary: ThemeColor;
+  surfaceSecondaryForeground: ThemeColor;
+  surfaceTertiary: ThemeColor;
+  surfaceTertiaryForeground: ThemeColor;
+  overlay: ThemeColor;
+  overlayForeground: ThemeColor;
+  scrollbar: ThemeColor;
+  segment: ThemeColor;
+  segmentForeground: ThemeColor;
+  border: ThemeColor;
+  separator: ThemeColor;
+
+  // Field colors
+  fieldBackground: ThemeColor;
+  fieldForeground: ThemeColor;
+  fieldPlaceholder: ThemeColor;
+
+  // Semantic colors
+  success: ThemeColor;
+  successForeground: ThemeColor;
+  warning: ThemeColor;
+  warningForeground: ThemeColor;
+  danger: ThemeColor;
+  dangerForeground: ThemeColor;
+}
+
+/**
+ * Semantic color override for a single color (success, warning, or danger)
+ */
+export interface SemanticColorOverride {
+  /** OKLCH color string e.g. "oklch(0.5148 0.1337 146.82)" */
+  color: string;
+  /** Optional foreground color - if not provided, will be calculated automatically */
+  foreground?: string;
+}
+
+/**
+ * Semantic color overrides for light and dark modes.
+ * Allows themes to specify exact semantic colors instead of using calculated values.
+ */
+export interface SemanticOverrides {
+  light?: {
+    /** Override the accent foreground color (text on accent background) */
+    accentForeground?: string;
+    danger?: SemanticColorOverride;
+    success?: SemanticColorOverride;
+    warning?: SemanticColorOverride;
+  };
+  dark?: {
+    /** Override the accent foreground color (text on accent background) */
+    accentForeground?: string;
+    danger?: SemanticColorOverride;
+    success?: SemanticColorOverride;
+    warning?: SemanticColorOverride;
+  };
+}
+
+export interface ColorGenerationParams {
+  /** Lightness value for accent color (0-1) */
+  lightness: number;
+  /** Chroma value for accent and gray tinting (0-0.4) */
+  chroma: number;
+  /** Hue value for all colors (0-360) */
+  hue: number;
+  /** Base chroma for gray/neutral colors (optional, defaults to subtle value) */
+  grayChroma?: number;
+  /** Optional semantic color overrides for light/dark modes */
+  semanticOverrides?: SemanticOverrides;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Utility Functions
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Adjust hue of a color object, keeping lightness and chroma
+ */
+function adjustHue(color: OklchColor, newHue: number): OklchColor {
+  return {...color, h: newHue};
+}
+
+/**
+ * Adjust chroma of a color object, keeping lightness and hue
+ */
+function adjustChroma(color: OklchColor, newChroma: number): OklchColor {
+  return {...color, c: Math.max(0, newChroma)};
+}
+
+/**
+ * Format a color object to OKLCH string
+ */
+export function formatOklch(color: OklchColor): string {
+  return `oklch(${(color.l * 100).toFixed(2)}% ${color.c.toFixed(4)} ${color.h.toFixed(2)})`;
+}
+
+/**
+ * Parse an OKLCH string to color object
+ */
+export function parseOklch(value: string): OklchColor | null {
+  // Handle CSS variable references
+  if (value.startsWith("var(")) {
+    return null;
+  }
+
+  // Parse OKLCH string - format: oklch(L C H) or oklch(L% C H)
+  const match = value.match(/oklch\(([0-9.]+)%?\s+([0-9.]+)\s+([0-9.]+|none)\)/);
+
+  if (match && match[1] && match[2] && match[3]) {
+    const l = match[1].includes("%") ? parseFloat(match[1]) / 100 : parseFloat(match[1]);
+    const c = parseFloat(match[2]);
+    const h = match[3] === "none" ? 0 : parseFloat(match[3]);
+
+    // Normalize lightness if given as percentage > 1
+    const normalizedL = l > 1 ? l / 100 : l;
+
+    return {c, h, l: normalizedL};
+  }
+
+  return null;
+}
+
+/**
+ * Calculate a blended hue for semantic colors based on the base hue
+ * This creates cohesion while maintaining semantic meaning
+ */
+function calculateSemanticHue(semanticDefaultHue: number, baseHue: number): number {
+  const hueOffset = (baseHue - DEFAULT_ACCENT.hue) * SEMANTIC_HUE_BLEND_FACTOR;
+  let newHue = semanticDefaultHue + hueOffset;
+
+  // Normalize to 0-360 range
+  while (newHue < 0) newHue += 360;
+  while (newHue >= 360) newHue -= 360;
+
+  return newHue;
+}
+
+/**
+ * Calculate foreground color based on background lightness
+ * Uses OKLCH perceptual uniformity for accurate contrast decisions
+ */
+export function calculateForeground(oklchString: string): string {
+  const color = parseOklch(oklchString);
+
+  if (!color) return "oklch(99.11% 0 0)"; // fallback to snow
+
+  const {c, h, l} = color;
+
+  // OKLCH lightness is perceptually uniform, 0.65 is a good threshold
+  if (l > 0.65) {
+    // Light background → dark foreground
+    return `oklch(15% ${Math.min(c * 0.3, 0.05).toFixed(4)} ${h.toFixed(2)})`;
+  } else {
+    // Dark background → light foreground
+    return `oklch(98% ${Math.min(c * 0.1, 0.02).toFixed(4)} ${h.toFixed(2)})`;
+  }
+}
+
+/**
+ * Calculate accent foreground color for solid accent backgrounds
+ * Optimized for button text on accent-colored backgrounds
+ */
+export function calculateAccentForeground(lightness: number, chroma: number, hue: number): string {
+  // For accent colors, we typically want high contrast
+  // If accent is light (> 0.65), use dark foreground
+  // If accent is dark (< 0.65), use light foreground
+  if (lightness > 0.65) {
+    return `oklch(15% ${Math.min(chroma * 0.2, 0.03).toFixed(4)} ${hue.toFixed(2)})`;
+  } else {
+    return `oklch(99.11% 0 0)`; // Snow white for dark accents
+  }
+}
+
+/**
+ * Generate a semantic color with appropriate foreground
+ */
+function generateSemanticColor(
+  name: string,
+  config: (typeof SEMANTIC_COLORS)["success"],
+  baseHue: number,
+  grayChroma: number,
+): {color: ThemeColor; foreground: ThemeColor} {
+  // Calculate blended hue
+  const adjustedHue = calculateSemanticHue(config.hue, baseHue);
+  const adjustedHueDark = calculateSemanticHue(
+    "hueDark" in config ? (config.hueDark as number) : config.hue,
+    baseHue,
+  );
+
+  // Scale chroma slightly based on gray chroma for visual harmony
+  const chromaBoost = 1 + grayChroma * 2;
+  const chromaLight = Math.min(config.chromaLight * chromaBoost, 0.35);
+  const chromaDark = Math.min(config.chromaDark * chromaBoost, 0.35);
+
+  const colorLight = formatOklch({c: chromaLight, h: adjustedHue, l: config.lightnessLight});
+  const colorDark = formatOklch({c: chromaDark, h: adjustedHueDark, l: config.lightnessDark});
+
+  // Determine foreground color based on semantic color lightness
+  // Threshold ~0.67: Success (0.73), Warning (0.78) → dark fg; Danger (0.65) → light fg
+  const LIGHTNESS_THRESHOLD = 0.67;
+
+  const fgLightTheme =
+    config.lightnessLight > LIGHTNESS_THRESHOLD
+      ? formatOklch({c: 0.0059, h: adjustedHue, l: 0.2103}) // Eclipse-like (dark)
+      : "oklch(99.11% 0 0)"; // Snow (white)
+
+  const fgDarkTheme =
+    config.lightnessDark > LIGHTNESS_THRESHOLD
+      ? formatOklch({c: 0.0059, h: adjustedHueDark, l: 0.2103}) // Eclipse-like (dark)
+      : "oklch(99.11% 0 0)"; // Snow (white)
+
+  return {
+    color: {
+      name: `--${name}`,
+      oklchDark: colorDark,
+      oklchLight: colorLight,
+    },
+    foreground: {
+      name: `--${name}-foreground`,
+      oklchDark: fgDarkTheme,
+      oklchLight: fgLightTheme,
+    },
+  };
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Main Color Generation Function
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Generate all theme colors based on lightness, chroma, and hue
+ *
+ * Unlike the storybook version, this supports:
+ * - Lightness customization for accent colors
+ * - Full theme color generation for both light and dark modes
+ * - Semantic color overrides for specific themes
+ */
+export function generateThemeColors(params: ColorGenerationParams): GeneratedThemeColors {
+  const {
+    lightness,
+    chroma,
+    hue,
+    grayChroma = Math.min(chroma * 0.05, 0.015),
+    semanticOverrides,
+  } = params;
+
+  // Get defaults
+  const defaultsLight = DEFAULT_THEME_VALUES.light;
+  const defaultsDark = DEFAULT_THEME_VALUES.dark;
+
+  // --accent: Apply all three parameters (lightness, chroma, hue)
+  const accentLight = formatOklch({c: chroma, h: hue, l: lightness});
+  const accentDark = formatOklch({c: chroma, h: hue, l: lightness}); // Same for both modes typically
+
+  const accent: ThemeColor = {
+    name: "--accent",
+    oklchDark: accentDark,
+    oklchLight: accentLight,
+  };
+
+  // --accent-foreground: Use override if provided, otherwise calculate based on accent lightness
+  const accentForeground: ThemeColor = {
+    name: "--accent-foreground",
+    oklchDark:
+      semanticOverrides?.dark?.accentForeground ??
+      calculateAccentForeground(lightness, chroma, hue),
+    oklchLight:
+      semanticOverrides?.light?.accentForeground ??
+      calculateAccentForeground(lightness, chroma, hue),
+  };
+
+  // --focus: Same as accent
+  const focus: ThemeColor = {
+    name: "--focus",
+    oklchDark: accentDark,
+    oklchLight: accentLight,
+  };
+
+  // --background: Apply hue and gray chroma adjustments
+  const background: ThemeColor = {
+    name: "--background",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.background, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.background, hue), grayChroma)),
+  };
+
+  // --foreground: Apply hue and chroma adjustments
+  const foreground: ThemeColor = {
+    name: "--foreground",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.foreground, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.foreground, hue), grayChroma)),
+  };
+
+  // --muted: Apply hue and gray chroma adjustments
+  const muted: ThemeColor = {
+    name: "--muted",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.muted, hue), grayChroma * 2)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.muted, hue), grayChroma * 2)),
+  };
+
+  // --default: Apply hue and gray chroma adjustments
+  const defaultColor: ThemeColor = {
+    name: "--default",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.default, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.default, hue), grayChroma)),
+  };
+
+  // --default-foreground: Eclipse with adjusted hue / Snow
+  const defaultForeground: ThemeColor = {
+    name: "--default-foreground",
+    oklchDark: "oklch(99.11% 0 0)",
+    oklchLight: formatOklch({c: 0.0059, h: hue, l: 0.2103}), // Snow
+  };
+
+  // --surface: Apply subtle hue and chroma
+  const surface: ThemeColor = {
+    name: "--surface",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.surface, hue), grayChroma * 2)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.surface, hue), grayChroma * 0.5)),
+  };
+
+  // --surface-foreground: Same as foreground
+  const surfaceForeground: ThemeColor = {
+    name: "--surface-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --surface-secondary: Apply hue and chroma adjustments
+  const surfaceSecondary: ThemeColor = {
+    name: "--surface-secondary",
+    oklchDark: formatOklch(
+      adjustChroma(adjustHue(defaultsDark.surfaceSecondary, hue), grayChroma * 1.5),
+    ),
+    oklchLight: formatOklch(
+      adjustChroma(adjustHue(defaultsLight.surfaceSecondary, hue), grayChroma * 0.8),
+    ),
+  };
+
+  // --surface-secondary-foreground: Uses foreground value
+  const surfaceSecondaryForeground: ThemeColor = {
+    name: "--surface-secondary-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --surface-tertiary: Apply hue and chroma adjustments
+  const surfaceTertiary: ThemeColor = {
+    name: "--surface-tertiary",
+    oklchDark: formatOklch(
+      adjustChroma(adjustHue(defaultsDark.surfaceTertiary, hue), grayChroma * 1.5),
+    ),
+    oklchLight: formatOklch(
+      adjustChroma(adjustHue(defaultsLight.surfaceTertiary, hue), grayChroma * 0.8),
+    ),
+  };
+
+  // --surface-tertiary-foreground: Uses foreground value
+  const surfaceTertiaryForeground: ThemeColor = {
+    name: "--surface-tertiary-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --overlay: Apply subtle hue and chroma
+  const overlay: ThemeColor = {
+    name: "--overlay",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.overlay, hue), grayChroma * 2)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.overlay, hue), grayChroma * 0.3)),
+  };
+
+  // --overlay-foreground: Same as foreground
+  const overlayForeground: ThemeColor = {
+    name: "--overlay-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --scrollbar: Apply hue and gray chroma
+  const scrollbar: ThemeColor = {
+    name: "--scrollbar",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.scrollbar, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.scrollbar, hue), grayChroma)),
+  };
+
+  // --segment: Apply hue and gray chroma
+  const segment: ThemeColor = {
+    name: "--segment",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.segment, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.segment, hue), grayChroma)),
+  };
+
+  // --segment-foreground: Same as foreground
+  const segmentForeground: ThemeColor = {
+    name: "--segment-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --border: Apply hue and gray chroma
+  const border: ThemeColor = {
+    name: "--border",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.border, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.border, hue), grayChroma)),
+  };
+
+  // --separator: Apply hue and gray chroma
+  const separator: ThemeColor = {
+    name: "--separator",
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.separator, hue), grayChroma)),
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.separator, hue), grayChroma)),
+  };
+
+  // --field-background: Same as surface (white in light, dark surface in dark)
+  const fieldBackground: ThemeColor = {
+    name: "--field-background",
+    oklchDark: surface.oklchDark,
+    oklchLight: surface.oklchLight,
+  };
+
+  // --field-foreground: Same as foreground
+  const fieldForeground: ThemeColor = {
+    name: "--field-foreground",
+    oklchDark: foreground.oklchDark,
+    oklchLight: foreground.oklchLight,
+  };
+
+  // --field-placeholder: Same as muted
+  const fieldPlaceholder: ThemeColor = {
+    name: "--field-placeholder",
+    oklchDark: muted.oklchDark,
+    oklchLight: muted.oklchLight,
+  };
+
+  // Generate semantic colors - use overrides if provided, otherwise calculate
+  let successColors: {color: ThemeColor; foreground: ThemeColor};
+  let warningColors: {color: ThemeColor; foreground: ThemeColor};
+  let dangerColors: {color: ThemeColor; foreground: ThemeColor};
+
+  // Check for success overrides
+  const lightSuccessOverride = semanticOverrides?.light?.success;
+  const darkSuccessOverride = semanticOverrides?.dark?.success;
+
+  if (lightSuccessOverride || darkSuccessOverride) {
+    // Use overrides where provided, fall back to calculated values
+    const calculated = generateSemanticColor("success", SEMANTIC_COLORS.success, hue, grayChroma);
+
+    successColors = {
+      color: {
+        name: "--success",
+        oklchDark: darkSuccessOverride?.color ?? calculated.color.oklchDark,
+        oklchLight: lightSuccessOverride?.color ?? calculated.color.oklchLight,
+      },
+      foreground: {
+        name: "--success-foreground",
+        oklchDark:
+          darkSuccessOverride?.foreground ??
+          calculateForeground(darkSuccessOverride?.color ?? calculated.color.oklchDark),
+        oklchLight:
+          lightSuccessOverride?.foreground ??
+          calculateForeground(lightSuccessOverride?.color ?? calculated.color.oklchLight),
+      },
+    };
+  } else {
+    successColors = generateSemanticColor("success", SEMANTIC_COLORS.success, hue, grayChroma);
+  }
+
+  // Check for warning overrides
+  const lightWarningOverride = semanticOverrides?.light?.warning;
+  const darkWarningOverride = semanticOverrides?.dark?.warning;
+
+  if (lightWarningOverride || darkWarningOverride) {
+    const calculated = generateSemanticColor("warning", SEMANTIC_COLORS.warning, hue, grayChroma);
+
+    warningColors = {
+      color: {
+        name: "--warning",
+        oklchDark: darkWarningOverride?.color ?? calculated.color.oklchDark,
+        oklchLight: lightWarningOverride?.color ?? calculated.color.oklchLight,
+      },
+      foreground: {
+        name: "--warning-foreground",
+        oklchDark:
+          darkWarningOverride?.foreground ??
+          calculateForeground(darkWarningOverride?.color ?? calculated.color.oklchDark),
+        oklchLight:
+          lightWarningOverride?.foreground ??
+          calculateForeground(lightWarningOverride?.color ?? calculated.color.oklchLight),
+      },
+    };
+  } else {
+    warningColors = generateSemanticColor("warning", SEMANTIC_COLORS.warning, hue, grayChroma);
+  }
+
+  // Check for danger overrides
+  const lightDangerOverride = semanticOverrides?.light?.danger;
+  const darkDangerOverride = semanticOverrides?.dark?.danger;
+
+  if (lightDangerOverride || darkDangerOverride) {
+    const calculated = generateSemanticColor("danger", SEMANTIC_COLORS.danger, hue, grayChroma);
+
+    dangerColors = {
+      color: {
+        name: "--danger",
+        oklchDark: darkDangerOverride?.color ?? calculated.color.oklchDark,
+        oklchLight: lightDangerOverride?.color ?? calculated.color.oklchLight,
+      },
+      foreground: {
+        name: "--danger-foreground",
+        oklchDark:
+          darkDangerOverride?.foreground ??
+          calculateForeground(darkDangerOverride?.color ?? calculated.color.oklchDark),
+        oklchLight:
+          lightDangerOverride?.foreground ??
+          calculateForeground(lightDangerOverride?.color ?? calculated.color.oklchLight),
+      },
+    };
+  } else {
+    dangerColors = generateSemanticColor("danger", SEMANTIC_COLORS.danger, hue, grayChroma);
+  }
+
+  return {
+    accent,
+    accentForeground,
+
+    // Core colors
+    background,
+    border,
+
+    danger: dangerColors.color,
+    dangerForeground: dangerColors.foreground,
+
+    default: defaultColor,
+    defaultForeground,
+
+    // Field colors
+    fieldBackground,
+    fieldForeground,
+    fieldPlaceholder,
+
+    focus,
+    foreground,
+
+    // UI colors
+    muted,
+    overlay,
+    overlayForeground,
+    scrollbar,
+    segment,
+    segmentForeground,
+    separator,
+
+    // Semantic colors
+    success: successColors.color,
+    successForeground: successColors.foreground,
+
+    surface,
+    surfaceForeground,
+    surfaceSecondary,
+    surfaceSecondaryForeground,
+    surfaceTertiary,
+    surfaceTertiaryForeground,
+
+    warning: warningColors.color,
+    warningForeground: warningColors.foreground,
+  };
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * CSS Variable Building
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Static var()-based formulas that mirror packages/styles/themes/default/variables.css.
+ * These must be re-declared on scoped elements because CSS custom properties
+ * resolve var() at the element where they are defined, not where inherited.
+ *
+ * Light and dark themes differ in soft percentages:
+ *   - Light: accent/warning/success soft 15%/20%, danger 15%/20%
+ *   - Dark:  accent/warning/success soft 12%/16%, danger 15%/20%
+ */
+export function getDerivedColorFormulas(
+  theme: "light" | "dark",
+  options?: {vibrant?: boolean},
+): Record<string, string> {
+  const isLight = theme === "light";
+  const vibrant = options?.vibrant ?? false;
+  const [softPct, softHoverPct] = isLight ? ["15%", "20%"] : ["12%", "16%"];
+
+  const vibrantSoftFg = "color-mix(in oklab, var(--VAR) 92%, var(--foreground) 8%)";
+  const sfFg = (colorVar: string, accessibleFormula: string) =>
+    vibrant ? vibrantSoftFg.replace("--VAR", colorVar) : accessibleFormula;
+
+  return {
+    "--accent-hover": "color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)",
+    "--accent-soft": `color-mix(in oklab, var(--accent) ${softPct}, transparent)`,
+    "--accent-soft-foreground": sfFg(
+      "accent",
+      isLight
+        ? "color-mix(in oklab, var(--accent) 70%, var(--foreground) 30%)"
+        : "color-mix(in oklab, var(--accent) 80%, var(--foreground) 30%)",
+    ),
+    "--accent-soft-hover": `color-mix(in oklab, var(--accent) ${softHoverPct}, transparent)`,
+    "--background-inverse": "var(--foreground)",
+    "--background-secondary": "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)",
+    "--background-tertiary": "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)",
+    "--border-secondary": "color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%)",
+    "--border-tertiary": "color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%)",
+    "--danger-hover": "color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)",
+    "--danger-soft": "color-mix(in oklab, var(--danger) 15%, transparent)",
+    "--danger-soft-foreground": sfFg(
+      "danger",
+      isLight
+        ? "color-mix(in oklab, var(--danger) 70%, var(--foreground) 40%)"
+        : "color-mix(in oklab, var(--danger) 80%, var(--foreground) 30%)",
+    ),
+    "--danger-soft-hover": "color-mix(in oklab, var(--danger) 20%, transparent)",
+    "--default-hover": "color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)",
+    "--default-soft": "color-mix(in oklab, var(--default) 50%, transparent)",
+    "--default-soft-foreground": "var(--default-foreground)",
+    "--default-soft-hover": "color-mix(in oklab, var(--default) 60%, transparent)",
+    "--field-border-focus":
+      "color-mix(in oklab, var(--field-border, var(--border)) 74%, var(--field-foreground, var(--foreground)) 22%)",
+    "--field-border-hover":
+      "color-mix(in oklab, var(--field-border, var(--border)) 88%, var(--field-foreground, var(--foreground)) 10%)",
+    "--field-focus": "var(--field-background, var(--default))",
+    "--field-hover":
+      "color-mix(in oklab, var(--field-background, var(--default)) 90%, var(--field-foreground, var(--foreground)) 2%)",
+    "--separator-secondary":
+      "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)",
+    "--separator-tertiary":
+      "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)",
+    "--success-hover": "color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)",
+    "--success-soft": `color-mix(in oklab, var(--success) ${softPct}, transparent)`,
+    "--success-soft-foreground": sfFg(
+      "success",
+      isLight
+        ? "color-mix(in oklab, var(--success) 80%, var(--foreground) 60%)"
+        : "color-mix(in oklab, var(--success) 80%, var(--foreground) 30%)",
+    ),
+    "--success-soft-hover": `color-mix(in oklab, var(--success) ${softHoverPct}, transparent)`,
+    "--surface-hover": "color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%)",
+    "--tw-ring-color": "var(--focus)",
+    "--warning-hover": "color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)",
+    "--warning-soft": `color-mix(in oklab, var(--warning) ${softPct}, transparent)`,
+    "--warning-soft-foreground": sfFg(
+      "warning",
+      isLight
+        ? "color-mix(in oklab, var(--warning) 80%, var(--foreground) 70%)"
+        : "color-mix(in oklab, var(--warning) 80%, var(--foreground) 30%)",
+    ),
+    "--warning-soft-hover": `color-mix(in oklab, var(--warning) ${softHoverPct}, transparent)`,
+  };
+}
+
+/**
+ * Radius-derived variables
+ */
+export const radiusDerivedVariables: Record<string, string> = {
+  "--radius-2xl": "calc(var(--radius) * 2)",
+  "--radius-3xl": "calc(var(--radius) * 3)",
+  "--radius-4xl": "calc(var(--radius) * 4)",
+  "--radius-field": "var(--field-radius, var(--radius-xl))",
+  "--radius-lg": "calc(var(--radius) * 1)",
+  "--radius-md": "calc(var(--radius) * 0.75)",
+  "--radius-sm": "calc(var(--radius) * 0.5)",
+  "--radius-xl": "calc(var(--radius) * 1.5)",
+  "--radius-xs": "calc(var(--radius) * 0.25)",
+};
+
+/**
+ * Get all color variables as a flat record for applying to an element
+ */
+export function getColorVariablesForElement(
+  colors: GeneratedThemeColors,
+  theme: "light" | "dark",
+): Record<string, string> {
+  const isLight = theme === "light";
+  const getValue = (color: ThemeColor) => (isLight ? color.oklchLight : color.oklchDark);
+
+  const vars: Record<string, string> = {};
+
+  // Core colors
+  vars["--background"] = getValue(colors.background);
+  vars["--foreground"] = getValue(colors.foreground);
+
+  // Accent
+  vars["--accent"] = getValue(colors.accent);
+  vars["--accent-foreground"] = getValue(colors.accentForeground);
+  vars["--focus"] = getValue(colors.focus);
+
+  // UI colors
+  vars["--muted"] = getValue(colors.muted);
+
+  vars["--default"] = getValue(colors.default);
+  vars["--default-foreground"] = getValue(colors.defaultForeground);
+
+  vars["--surface"] = getValue(colors.surface);
+  vars["--surface-foreground"] = getValue(colors.surfaceForeground);
+
+  vars["--surface-secondary"] = getValue(colors.surfaceSecondary);
+  vars["--surface-secondary-foreground"] = getValue(colors.surfaceSecondaryForeground);
+
+  vars["--surface-tertiary"] = getValue(colors.surfaceTertiary);
+  vars["--surface-tertiary-foreground"] = getValue(colors.surfaceTertiaryForeground);
+
+  vars["--overlay"] = getValue(colors.overlay);
+  vars["--overlay-foreground"] = getValue(colors.overlayForeground);
+
+  vars["--scrollbar"] = getValue(colors.scrollbar);
+
+  vars["--segment"] = getValue(colors.segment);
+  vars["--segment-foreground"] = getValue(colors.segmentForeground);
+
+  vars["--border"] = getValue(colors.border);
+
+  vars["--separator"] = getValue(colors.separator);
+
+  // Field colors
+  vars["--field-background"] = getValue(colors.fieldBackground);
+  vars["--field-border"] = "transparent";
+  vars["--field-foreground"] = getValue(colors.fieldForeground);
+  vars["--field-placeholder"] = getValue(colors.fieldPlaceholder);
+
+  // Semantic colors
+  vars["--success"] = getValue(colors.success);
+  vars["--success-foreground"] = getValue(colors.successForeground);
+
+  vars["--warning"] = getValue(colors.warning);
+  vars["--warning-foreground"] = getValue(colors.warningForeground);
+
+  vars["--danger"] = getValue(colors.danger);
+  vars["--danger-foreground"] = getValue(colors.dangerForeground);
+
+  return vars;
+}
diff --git a/apps/docs/src/app/agent-markdown/route.ts b/apps/docs/src/app/agent-markdown/route.ts
new file mode 100644
index 0000000..41cdd1b
--- /dev/null
+++ b/apps/docs/src/app/agent-markdown/route.ts
@@ -0,0 +1,74 @@
+import type {NextRequest} from "next/server";
+
+import {MARKDOWN_HEADERS, getHomepageLinkHeader, getRequestOrigin} from "@/lib/agent-discovery";
+import {
+  estimateMarkdownTokens,
+  getHomepageMarkdown,
+  resolveDocsPathToSlug,
+} from "@/lib/agent-markdown";
+import {getLLMText} from "@/lib/get-llm-text";
+import {source} from "@/lib/source";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+function markdownResponse(markdown: string, init: ResponseInit = {}): Response {
+  return new Response(markdown, {
+    ...init,
+    headers: {
+      ...MARKDOWN_HEADERS,
+      "x-markdown-tokens": String(estimateMarkdownTokens(markdown)),
+      ...init.headers,
+    },
+  });
+}
+
+async function getMarkdownForPath(request: NextRequest): Promise<Response> {
+  const origin = getRequestOrigin(request);
+  const pathname =
+    request.headers.get("x-heroui-markdown-path") ??
+    request.nextUrl.searchParams.get("path") ??
+    "/";
+
+  if (pathname === "/") {
+    return markdownResponse(getHomepageMarkdown(origin), {
+      headers: {
+        Link: getHomepageLinkHeader(),
+      },
+    });
+  }
+
+  const slug = resolveDocsPathToSlug(pathname);
+
+  if (!slug) {
+    return markdownResponse(
+      `# Not Found\n\nNo markdown representation is available for ${pathname}.\n`,
+      {
+        status: 404,
+      },
+    );
+  }
+
+  const page = source.getPage(slug);
+
+  if (!page) {
+    return markdownResponse(`# Not Found\n\nNo documentation page was found for ${pathname}.\n`, {
+      status: 404,
+    });
+  }
+
+  return markdownResponse(await getLLMText(page));
+}
+
+export async function GET(request: NextRequest) {
+  return getMarkdownForPath(request);
+}
+
+export async function HEAD(request: NextRequest) {
+  const response = await getMarkdownForPath(request);
+
+  return new Response(null, {
+    headers: response.headers,
+    status: response.status,
+  });
+}
diff --git a/apps/docs/src/app/api/agent/health/route.ts b/apps/docs/src/app/api/agent/health/route.ts
new file mode 100644
index 0000000..f66fb00
--- /dev/null
+++ b/apps/docs/src/app/api/agent/health/route.ts
@@ -0,0 +1,12 @@
+import {AGENT_API_VERSION, jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET() {
+  return jsonResponse({
+    service: "heroui-docs-agent-api",
+    status: "ok",
+    version: AGENT_API_VERSION,
+  });
+}
diff --git a/apps/docs/src/app/api/agent/page/route.ts b/apps/docs/src/app/api/agent/page/route.ts
new file mode 100644
index 0000000..8737c71
--- /dev/null
+++ b/apps/docs/src/app/api/agent/page/route.ts
@@ -0,0 +1,23 @@
+import type {NextRequest} from "next/server";
+
+import {getAgentDocPage} from "@/lib/agent-api";
+import {jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: NextRequest) {
+  const url = request.nextUrl.searchParams.get("url") ?? request.nextUrl.searchParams.get("path");
+
+  if (!url) {
+    return jsonResponse({error: "Missing required query parameter: url"}, {status: 400});
+  }
+
+  const page = await getAgentDocPage(url);
+
+  if (!page) {
+    return jsonResponse({error: "Documentation page not found", url}, {status: 404});
+  }
+
+  return jsonResponse(page);
+}
diff --git a/apps/docs/src/app/api/agent/search/route.ts b/apps/docs/src/app/api/agent/search/route.ts
new file mode 100644
index 0000000..94ccb8e
--- /dev/null
+++ b/apps/docs/src/app/api/agent/search/route.ts
@@ -0,0 +1,26 @@
+import type {NextRequest} from "next/server";
+
+import {parseAgentLimit, parseAgentSearchPlatform, searchAgentDocs} from "@/lib/agent-api";
+import {jsonResponse} from "@/lib/agent-discovery";
+
+export const dynamic = "force-dynamic";
+export const revalidate = false;
+
+export async function GET(request: NextRequest) {
+  const query = request.nextUrl.searchParams.get("q")?.trim() ?? "";
+
+  if (!query) {
+    return jsonResponse({error: "Missing required query parameter: q"}, {status: 400});
+  }
+
+  const platform = parseAgentSearchPlatform(request.nextUrl.searchParams.get("platform"));
+  const limit = parseAgentLimit(request.nextUrl.searchParams.get("limit"));
+  const results = searchAgentDocs(query, platform, limit);
+
+  return jsonResponse({
+    count: results.length,
+    platform,
+    query,
+    results,
+  });
+}
diff --git a/apps/docs/src/app/api/changelog/route.ts b/apps/docs/src/app/api/changelog/route.ts
new file mode 100644
index 0000000..dbd10a1
--- /dev/null
+++ b/apps/docs/src/app/api/changelog/route.ts
@@ -0,0 +1,41 @@
+import type {NextRequest} from "next/server";
+
+import {NextResponse} from "next/server";
+
+export async function POST(request: NextRequest) {
+  try {
+    const {email} = await request.json();
+
+    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      return NextResponse.json({error: "Please enter a valid email."}, {status: 400});
+    }
+
+    const apiKey = process.env["FEATUREBASE_API_KEY"];
+    const apiEndpoint = process.env["FEATUREBASE_API_ENDPOINT"] || "https://do.featurebase.app/v2";
+
+    if (!apiKey) {
+      console.error("FEATUREBASE_API_KEY is not configured");
+
+      return NextResponse.json({error: "Featurebase service is not configured."}, {status: 500});
+    }
+
+    const response = await fetch(`${apiEndpoint}/changelog/subscribers`, {
+      body: JSON.stringify({
+        emails: [email],
+      }),
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": `${apiKey}`,
+      },
+      method: "POST",
+    });
+
+    const res = await response.json();
+
+    return NextResponse.json({success: res.success});
+  } catch (error) {
+    console.error("Featurebase subscription error:", error);
+
+    return NextResponse.json({error: "Something went wrong. Please try again."}, {status: 500});
+  }
+}
diff --git a/apps/docs/src/app/api/newsletter/route.ts b/apps/docs/src/app/api/newsletter/route.ts
new file mode 100644
index 0000000..7160191
--- /dev/null
+++ b/apps/docs/src/app/api/newsletter/route.ts
@@ -0,0 +1,51 @@
+import type {NextRequest} from "next/server";
+
+import {NextResponse} from "next/server";
+
+export async function POST(request: NextRequest) {
+  try {
+    const {email, source} = await request.json();
+
+    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      return NextResponse.json({error: "Please enter a valid email."}, {status: 400});
+    }
+
+    const apiKey = process.env["LOOPS_API_KEY"];
+    const apiEndpoint = process.env["LOOPS_API_ENDPOINT"] || "https://app.loops.so/api/v1";
+
+    if (!apiKey) {
+      console.error("LOOPS_API_KEY is not configured");
+
+      return NextResponse.json({error: "Newsletter service is not configured."}, {status: 500});
+    }
+
+    const response = await fetch(`${apiEndpoint}/contacts/create`, {
+      body: JSON.stringify({
+        email,
+        source,
+      }),
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      // Contact already exists - treat as success
+      if (response.status === 409) {
+        return NextResponse.json({success: true});
+      }
+
+      throw new Error(data.message || "Failed to subscribe");
+    }
+
+    return NextResponse.json({success: true});
+  } catch (error) {
+    console.error("Newsletter subscription error:", error);
+
+    return NextResponse.json({error: "Something went wrong. Please try again."}, {status: 500});
+  }
+}
diff --git a/apps/docs/src/app/api/search/route.ts b/apps/docs/src/app/api/search/route.ts
new file mode 100644
index 0000000..5867824
--- /dev/null
+++ b/apps/docs/src/app/api/search/route.ts
@@ -0,0 +1,27 @@
+import {createI18nSearchAPI} from "fumadocs-core/search/server";
+
+import {i18n} from "@/lib/i18n";
+import {source} from "@/lib/source";
+
+export const {GET} = createI18nSearchAPI("advanced", {
+  i18n,
+  indexes: source.getLanguages().flatMap(({language, pages}) =>
+    pages.map((page) => ({
+      description: page.data.description,
+      id: page.url,
+      locale: language,
+      structuredData: page.data.structuredData,
+      // The framework lives in the first slug segment after the locale,
+      // e.g. `content/docs/<locale>/react/...` -> slugs[0] === "react".
+      tag: page.slugs[0] === "react" ? "web" : "native",
+      title: page.data.title,
+      url: page.url,
+    })),
+  ),
+  // `cn` is not a built-in Orama language; fall back to the English tokenizer
+  // so Chinese pages can still be indexed (latin terms still match).
+  localeMap: {
+    cn: "english",
+    en: "english",
+  },
+});
diff --git a/apps/docs/src/app/custom-root-provider.tsx b/apps/docs/src/app/custom-root-provider.tsx
new file mode 100644
index 0000000..10af3f1
--- /dev/null
+++ b/apps/docs/src/app/custom-root-provider.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import type {Dictionary} from "@/lib/dictionaries";
+import type {ReactNode} from "react";
+
+import {Toast} from "@heroui/react";
+import {i18nProvider} from "fumadocs-ui/i18n";
+import {RootProvider} from "fumadocs-ui/provider/next";
+import dynamic from "next/dynamic";
+
+import {WebMCPProvider} from "@/components/ai/webmcp-provider";
+import {LocaleLink} from "@/components/locale-link";
+import {DictionaryProvider} from "@/hooks/use-dictionary";
+import {translations} from "@/lib/layout.shared";
+
+const SearchDialog = dynamic(() => import("@/components/search-dialog"), {
+  ssr: false,
+});
+
+export function CustomRootProvider({
+  children,
+  dict,
+  lang,
+}: {
+  children: ReactNode;
+  dict: Dictionary;
+  lang: string;
+}) {
+  return (
+    <DictionaryProvider dict={dict}>
+      <RootProvider
+        components={{Link: LocaleLink}}
+        i18n={i18nProvider(translations, lang)}
+        search={{
+          SearchDialog,
+        }}
+      >
+        {children}
+        {/* Global toast provider for demos using the default toast() function */}
+        <Toast.Provider />
+
+        <WebMCPProvider />
+      </RootProvider>
+    </DictionaryProvider>
+  );
+}
diff --git a/apps/docs/src/app/docs/native-showcase/components/[[...slug]]/page.tsx b/apps/docs/src/app/docs/native-showcase/components/[[...slug]]/page.tsx
new file mode 100644
index 0000000..25dc433
--- /dev/null
+++ b/apps/docs/src/app/docs/native-showcase/components/[[...slug]]/page.tsx
@@ -0,0 +1,53 @@
+import type {Metadata} from "next";
+import type {FC} from "react";
+
+import {DownloadAppBanner} from "@/components/native";
+import {NATIVE_APP} from "@/config/native-app";
+
+/**
+ * Render the same static fallback shell for every component slug. Next.js
+ * will produce a single static HTML response that gets served for any unknown
+ * slug under `/docs/native-showcase/components/*`.
+ */
+export const dynamic = "force-static";
+
+/**
+ * Allow Next.js to render this route for slugs that weren't pre-rendered at
+ * build time. The page intentionally doesn't render slug-specific content -
+ * it's a generic "Download the app" banner - so accepting any slug at runtime
+ * is the desired behaviour.
+ */
+export const dynamicParams = true;
+
+/**
+ * Metadata for the web fallback. We mark the page `noindex` because the URL
+ * exists exclusively to serve Universal Links and is never meant to surface in
+ * search results. The description and title are still set so the page renders
+ * cleanly when shared (e.g. in a chat preview) before the native app picks
+ * the link up.
+ */
+export const metadata: Metadata = {
+  description: [
+    "Open this component in the ",
+    NATIVE_APP.NAME,
+    " app, or download the app from the App Store or Google Play.",
+  ].join(""),
+  robots: {follow: false, index: false},
+  title: [`Open in ${NATIVE_APP.NAME}`, "HeroUI"].join(" | "),
+};
+
+/**
+ * Web fallback rendered when a user navigates to
+ * `/docs/native-showcase/components/{slug}` without the HeroUI Native app
+ * installed (e.g. they scan the QR from a non-iOS/Android device, or iOS
+ * decides not to deep-link because the AASA glob didn't match).
+ *
+ * The native app's `+native-intent` redirect transforms matching URLs into
+ * in-app routes - so when the app IS installed, this page is never actually
+ * displayed, the OS intercepts the URL before the browser ever loads it.
+ */
+const NativeShowcaseComponentsFallbackPage: FC = () => {
+  return <DownloadAppBanner />;
+};
+
+export default NativeShowcaseComponentsFallbackPage;
diff --git a/apps/docs/src/app/docs/native-showcase/layout.tsx b/apps/docs/src/app/docs/native-showcase/layout.tsx
new file mode 100644
index 0000000..04daa10
--- /dev/null
+++ b/apps/docs/src/app/docs/native-showcase/layout.tsx
@@ -0,0 +1,18 @@
+import type {ReactNode} from "react";
+
+import {Inter} from "next/font/google";
+
+import "../../global.css";
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+});
+
+export default function NativeShowcaseLayout({children}: {children: ReactNode}) {
+  return (
+    <html suppressHydrationWarning className={inter.variable} lang="en">
+      <body className="flex min-h-screen flex-col font-sans">{children}</body>
+    </html>
+  );
+}
diff --git a/apps/docs/src/app/docs/native-showcase/privacy-policy/page.tsx b/apps/docs/src/app/docs/native-showcase/privacy-policy/page.tsx
new file mode 100644
index 0000000..85b55a8
--- /dev/null
+++ b/apps/docs/src/app/docs/native-showcase/privacy-policy/page.tsx
@@ -0,0 +1,101 @@
+import type {Metadata} from "next";
+import type {FC} from "react";
+
+import {NATIVE_APP} from "@/config/native-app";
+import {siteConfig} from "@/config/site";
+
+export const dynamic = "force-static";
+const EFFECTIVE_DATE = "May 21, 2026";
+const CONTACT_EMAIL: string = siteConfig.supportEmail;
+
+export const metadata: Metadata = {
+  description: [
+    "Privacy policy for the ",
+    NATIVE_APP.NAME,
+    " mobile app — how the app handles personal data, analytics, deep links, and authentication.",
+  ].join(""),
+  title: ["Privacy Policy", NATIVE_APP.NAME, "HeroUI"].join(" | "),
+};
+
+const PrivacyPolicyPage: FC = () => {
+  return (
+    <div className="prose mx-auto max-w-3xl px-4 py-24">
+      <h1>Privacy Policy</h1>
+      <p>Effective Date: {EFFECTIVE_DATE}</p>
+
+      <p>
+        {[
+          "The ",
+          NATIVE_APP.NAME,
+          " app (the “App”) is an interactive showcase that lets developers and designers preview, explore, and interact with the components, blocks, and patterns shipped by the HeroUI Native UI library. It is designed as a reference and evaluation tool to help teams adopt HeroUI Native in their own React Native applications.",
+        ].join("")}
+      </p>
+
+      <h2>1. Information We Collect</h2>
+      <p>
+        {[
+          "We do not collect, store, or share any personal data. The ",
+          NATIVE_APP.NAME,
+          " app does not require an account, does not track user behaviour, and does not send usage statistics, crash reports, or analytics data to HeroUI or any third party.",
+        ].join("")}
+      </p>
+
+      <h2>2. Authentication</h2>
+      <p>
+        No authentication mechanisms are currently implemented. If authentication is added in the
+        future, this Privacy Policy will be updated to reflect that change.
+      </p>
+
+      <h2>3. Deep Links and Universal Links</h2>
+      <p>
+        {[
+          "The ",
+          NATIVE_APP.NAME,
+          " app handles Universal Links and custom-scheme deep links that point at component previews on the HeroUI documentation site. When the App opens a deep link, the destination URL is resolved entirely on-device by the App’s native intent handler — the link target is never transmitted to a HeroUI-operated server or any third-party tracking service.",
+        ].join("")}
+      </p>
+
+      <h2>4. Data Usage and Sharing</h2>
+      <p>Since we do not collect any data, we do not share any data with third parties.</p>
+
+      <h2>5. Permissions</h2>
+      <p>
+        {[
+          "The ",
+          NATIVE_APP.NAME,
+          " app does not request access to the camera, microphone, contacts, location, photo library, or any other sensitive device capability. If a future component preview requires a specific permission, the operating system will prompt you at the moment that preview is opened, and you may decline without losing access to the rest of the App.",
+        ].join("")}
+      </p>
+
+      <h2>6. Children’s Privacy</h2>
+      <p>
+        {[
+          "The ",
+          NATIVE_APP.NAME,
+          " app is a developer tool intended for a general audience and is not directed at children under the age of 13. We do not knowingly collect any personal information from anyone, including children.",
+        ].join("")}
+      </p>
+
+      <h2>7. Changes to This Policy</h2>
+      <p>
+        {[
+          "We may update this Privacy Policy as the ",
+          NATIVE_APP.NAME,
+          " app evolves. When we do, we will revise the “Effective Date” at the top of this page. For significant changes, we may also surface additional notice within the App itself.",
+        ].join("")}
+      </p>
+
+      <h2>8. Contact</h2>
+      <p>
+        {[
+          "If you have any questions about this Privacy Policy or the ",
+          NATIVE_APP.NAME,
+          " app, please contact us at: ",
+        ].join("")}
+        <a href={["mailto:", CONTACT_EMAIL].join("")}>{CONTACT_EMAIL}</a>.
+      </p>
+    </div>
+  );
+};
+
+export default PrivacyPolicyPage;
diff --git a/apps/docs/src/app/global.css b/apps/docs/src/app/global.css
new file mode 100644
index 0000000..9fab141
--- /dev/null
+++ b/apps/docs/src/app/global.css
@@ -0,0 +1,744 @@
+/* ============================================================================
+   IMPORTS
+   ============================================================================ */
+
+@import "tailwindcss";
+@import "fumadocs-ui/css/black.css";
+@import "fumadocs-ui/css/preset.css";
+@import "@heroui/styles";
+@import "../styles/theme-presets.css";
+
+@keyframes float-stars {
+  0% {
+    transform: translateY(0px) translateX(0px);
+  }
+  50% {
+    transform: translateY(-40px) translateX(40px);
+  }
+  100% {
+    transform: translateY(0px) translateX(0px);
+  }
+}
+
+@keyframes float-stars-reverse {
+  0% {
+    transform: translateY(0px) translateX(0px);
+  }
+  50% {
+    transform: translateY(40px) translateX(-40px);
+  }
+  100% {
+    transform: translateY(0px) translateX(0px);
+  }
+}
+
+/* ============================================================================
+   CSS VARIABLES - ROOT & THEMES
+   ============================================================================ */
+
+:root {
+  /* Brand Accent Colors (Optional Overrides) */
+  /* --accent: oklch(0.7 0.25 260); */
+  /* --accent-foreground: oklch(0.98 0 0); */
+  /* --accent: var(--color-blue-600); */
+  /* --accent-soft: var(--color-blue-100); */
+
+  /* Fumadocs UI Variables */
+  --fd-layout-width: 1400px;
+  --color-fd-background: var(--background);
+  --color-fd-foreground: var(--foreground);
+  --color-fd-primary: oklch(0.14 0 0);
+  --color-fd-secondary: #f9f9f9;
+  --color-fd-card: #f9f9f9;
+  --spacing-fd-container: 1120px;
+  --color-fd-border: oklch(0 0 0 / 10%);
+  --color-fd-accent: #f9f9f9;
+  --color-fd-muted-foreground: var(--color-neutral-500);
+  --color-backdrop: rgba(255, 255, 255, 0.4);
+  /* Fumadocs UI Animations */
+  --animate-fd-fade-in: custom-fade-in 200ms ease-out forwards;
+  --animate-fd-fade-out: custom-fade-out 150ms ease-out forwards;
+
+  /* Default font - can be overridden by theme builder */
+  --font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+[data-theme="light"],
+.light {
+}
+
+/* Dark Theme Variables */
+[data-theme="dark"],
+.dark {
+  /* Custom Values (Optional) */
+  /* --radius: 0.5rem; */
+  /* --cursor: default; */
+
+  /* Fumadocs UI Dark Theme */
+  --color-fd-primary: oklch(0.99 0 0);
+  --color-fd-card: rgba(40, 40, 40, 0.4);
+  --color-fd-secondary: #18181b;
+  --color-fd-accent: #2c2c2c;
+  --color-fd-popover: #383435;
+  --color-fd-border: rgba(255, 255, 255, 0.1);
+  --color-backdrop: rgba(0, 0, 0, 0.4);
+}
+
+/* ============================================================================
+   HEROUI COMPONENT OVERRIDES
+   ============================================================================ */
+
+/* HeroUI Component Style Overrides */
+/* @utility button {
+  @apply rounded-sm;
+} */
+
+/* ============================================================================
+   FUMADOCS UI - NAVIGATION COMPONENTS
+   ============================================================================ */
+
+#nd-notebook-layout {
+  transition: none;
+}
+
+[data-theme-toggle] {
+  @apply border-none bg-default/80;
+}
+
+/* Home Layout Navigation */
+#nd-home-layout {
+  #nd-nav {
+    @apply bg-background blur-none backdrop-blur-none;
+
+    [data-theme-toggle] {
+      margin-left: 4px;
+    }
+
+    > div {
+      border: none;
+    }
+
+    nav {
+      @apply px-6;
+    }
+  }
+}
+
+.showcase-detail-page #nd-home-layout {
+  padding-top: 0;
+}
+
+/* Main Navigation */
+#nd-nav {
+  border: none;
+  background-color: transparent;
+
+  /* Only affects the Docs/Components ul, not the search/theme toggle */
+  nav > ul {
+    padding-top: 4px;
+    gap: 0;
+  }
+
+  nav > ul > li > a,
+  nav > ul:last-of-type > li > a:last-of-type {
+    @apply ml-0 rounded-none border-none p-2;
+  }
+
+  li > a {
+    color: var(--muted);
+  }
+
+  [data-search-full] {
+    @apply rounded-field border-none bg-default/80;
+
+    kbd {
+      @apply border-none bg-surface px-1 font-sans text-xs font-medium text-muted;
+    }
+  }
+
+  [aria-label="GitHub"] {
+    @apply w-0 opacity-0;
+  }
+}
+
+/* Sub Navigation */
+#nd-subnav {
+  @apply gap-0 bg-background md:gap-1;
+  backdrop-filter: none;
+
+  &:after {
+    content: "";
+    display: block;
+    position: absolute;
+    bottom: -1px;
+    left: 50%;
+    transform: translateX(-50%);
+    width: 100vw;
+    height: 1px;
+    z-index: 1;
+    background: var(--separator);
+  }
+
+  [data-header-body] {
+    @apply h-13 border-none md:h-14;
+  }
+
+  [data-header-tabs] {
+    @apply gap-1 border-none px-4 md:gap-3 md:px-6;
+
+    a {
+      @apply px-1 pb-2;
+    }
+
+    .border-fd-primary {
+      border-color: var(--color-accent);
+    }
+
+    [data-frameworks-tabs] {
+      @apply flex items-center;
+
+      .tabs__list-container {
+        @apply w-auto;
+      }
+
+      .tabs__list {
+        @apply w-auto;
+      }
+    }
+  }
+
+  [data-search-full] {
+    @apply rounded-field border-none bg-field shadow-field sm:max-w-[300px] md:max-w-[400px] lg:mr-12 dark:bg-field/80 dark:backdrop-blur-md;
+
+    kbd {
+      @apply border-none bg-default dark:bg-surface;
+    }
+  }
+}
+
+/* Sidebar */
+#nd-sidebar {
+  @apply items-start pt-4 pl-3 transition-none;
+
+  @media (min-width: 600px) {
+    --fd-sidebar-width: 220px;
+  }
+
+  & > div {
+    width: 100% !important;
+    max-width: var(--fd-sidebar-width);
+  }
+
+  & > :last-child {
+    border-top: none;
+  }
+
+  [data-radix-scroll-area-viewport] {
+    @apply px-1 pt-2;
+
+    p {
+      @apply font-medium;
+    }
+
+    p:not(:first-child) {
+      @apply mt-4;
+    }
+  }
+
+  [data-fd-if-empty] {
+    @apply hidden;
+  }
+}
+
+#nd-sidebar a {
+  @apply rounded-field;
+
+  transition: none;
+
+  &:hover {
+    background: rgba(0, 0, 0, 0.04);
+  }
+
+  &[data-active="true"] {
+    @apply bg-surface shadow-surface;
+  }
+}
+
+/* Nested items inside open groups */
+#nd-sidebar [data-state="open"] > [data-state="open"] {
+  padding: 4px 16px;
+
+  a {
+    padding-left: 14px;
+    &::before {
+      display: none;
+    }
+  }
+}
+
+/* External link icon for sidebar links */
+#nd-sidebar a[rel="noreferrer noopener"]::after {
+  content: "";
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  margin-left: -6px;
+  margin-bottom: 8px;
+  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="10" height="10"><path d="M6 18L18 6m0 0H9m9 0v9" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/></svg>');
+  background-size: contain;
+  background-repeat: no-repeat;
+  background-position: center;
+  vertical-align: middle;
+  opacity: 0.5;
+  transition: opacity 0.2s;
+}
+
+#nd-sidebar a[rel="noreferrer noopener"]:hover::after {
+  opacity: 1;
+}
+
+#nd-sidebar-mobile {
+  [data-radix-scroll-area-viewport] {
+    p {
+      @apply font-medium;
+    }
+  }
+}
+
+/* Keep CJK phrases together so they wrap as a whole word instead of breaking between characters. 
+   Safe for non-CJK locales since `keep-all` behaves like `normal` for non-CJK text. */
+#nd-sidebar a,
+#nd-sidebar p,
+#nd-sidebar-mobile a,
+#nd-sidebar-mobile p {
+  word-break: keep-all;
+  overflow-wrap: break-word;
+}
+
+/* ============================================================================
+   FUMADOCS UI - LAYOUT COMPONENTS
+   ============================================================================ */
+
+#nd-docs-layout {
+  position: relative;
+
+  @media (min-width: 48rem) {
+    --fd-sidebar-width: 220px;
+  }
+}
+
+#nd-notebook-layout {
+  @media (min-width: 48rem) {
+    --fd-sidebar-width: 220px;
+  }
+  grid-template:
+    ". header header header ."
+    ". sidebar toc-popover toc-popover ."
+    ". sidebar main toc ." 1fr / minmax(min-content, 1fr) var(--fd-sidebar-col) minmax(
+      0,
+      calc(var(--fd-layout-width, 97rem) - var(--fd-sidebar-col) - var(--fd-toc-width))
+    )
+    var(--fd-toc-width) minmax(min-content, 1fr) !important;
+}
+
+#nd-page {
+  @apply mt-4 gap-4 p-4 px-6 sm:px-4 md:px-6 md:pt-0 xl:px-12 xl:pt-8;
+
+  > article {
+    @apply p-8;
+
+    position: static;
+  }
+
+  @media (min-width: 80rem) {
+    margin-top: 0;
+  }
+
+  @media (max-width: 48rem) {
+    > article {
+      @apply p-2;
+    }
+  }
+
+  .component-preview-container {
+    /* Preview and code are now displayed vertically */
+
+    .code-section {
+      .code-block-wrapper {
+        @apply rounded-none rounded-b-xl;
+      }
+    }
+  }
+}
+
+/* ============================================================================
+   FUMADOCS UI - TABLE OF CONTENTS
+   ============================================================================ */
+
+#nd-toc {
+  @apply right-0 pt-6 pl-4 transition-none;
+  --fd-toc-width: 220px;
+  --color-fd-foreground: transparent;
+  /* Disables the active indicator */
+  [role="none"] {
+    display: none;
+    background: transparent;
+  }
+
+  /* Selects all links inside the toc (active and not active)*/
+  [data-active] {
+    @apply truncate pr-2 text-[13px];
+  }
+
+  @media (min-width: 600px) {
+    --fd-toc-width: 240px;
+  }
+}
+
+#nd-tocnav {
+  border-radius: 0rem;
+  top: calc(var(--fd-banner-height) + var(--fd-nav-height) - 12px) !important;
+  margin-right: 0rem;
+  margin-left: 0rem;
+  margin-top: 0px;
+  background: var(--background);
+  backdrop-filter: none !important;
+  border-left: none !important;
+  border-right: none !important;
+  border-top: 1px solid var(--border) !important;
+  border-bottom: 1px solid var(--separator) !important;
+
+  @media (min-width: 600px) {
+    margin-right: 1rem;
+    border-bottom: 0px solid var(--separator) !important;
+  }
+}
+
+[data-toc-popover] {
+  @apply top-[93px] z-2 md:top-[101px];
+  header {
+    @apply border-b border-separator md:border-b-0;
+    padding: 0 0.5rem;
+    background: var(--background) !important;
+    backdrop-filter: none !important;
+  }
+}
+
+/* ============================================================================
+   PROSE & CONTENT STYLES
+   ============================================================================ */
+
+.prose {
+  .shiki {
+    @apply border-none;
+    background: transparent;
+    box-shadow: none;
+
+    /* Code block wrapper */
+    figure {
+      padding: 0;
+    }
+
+    /* Copy button */
+    div:first-of-type {
+      border: none;
+      background: transparent;
+
+      button:hover {
+        background: transparent;
+      }
+    }
+
+    /* Scroll container */
+    .fd-scroll-container {
+      @apply border-none px-1;
+
+      background: rgba(0, 0, 0, 0.04);
+    }
+
+    li > code {
+      @apply bg-default;
+    }
+  }
+}
+
+.prose .shiki .fd-scroll-container {
+  max-height: fit-content;
+}
+
+[role="tabpanel"] .mdx-code-block {
+  padding: 0;
+}
+
+code {
+  @apply border-separator bg-transparent px-[3px];
+}
+
+/* Table styles for .prose-no-margin */
+.prose-no-margin {
+  table {
+    @apply border-none bg-transparent;
+    border-collapse: separate;
+    border-spacing: 0;
+
+    thead {
+      tr {
+        th {
+          @apply border-none bg-default dark:bg-default/50;
+
+          &:first-child {
+            @apply rounded-tl-xl rounded-bl-xl;
+          }
+
+          &:last-child {
+            @apply rounded-tr-xl rounded-br-xl;
+          }
+        }
+      }
+    }
+
+    tbody {
+      tr {
+        td {
+          @apply border-none;
+        }
+      }
+    }
+  }
+}
+
+/* ============================================================================
+   CODE BLOCK STYLES
+   ============================================================================ */
+
+.docs-code-block {
+  @apply m-0 rounded-none border-none pt-4 pr-2 pl-2;
+
+  .fd-scroll-container {
+    @apply rounded-none border-none bg-transparent! p-0;
+  }
+
+  .line {
+    @apply pl-0!;
+  }
+
+  [role="region"] {
+    max-height: 75vh;
+  }
+}
+
+/* Apply !important only for isolated code blocks (not code-block-wrapper) */
+.is-isolated .docs-code-block {
+  background: rgba(0, 0, 0, 0.04) !important;
+}
+
+.code-block-wrapper {
+  @apply rounded-xl;
+}
+
+.docs-code-block-line-numbers {
+  code {
+    counter-reset: step;
+    counter-increment: step 0;
+  }
+
+  code .line::before {
+    content: counter(step);
+    counter-increment: step;
+    width: 1rem;
+    margin-right: 1.5rem;
+    display: inline-block;
+    text-align: right;
+    color: rgba(115, 138, 148, 0.4);
+  }
+}
+
+.shiki:not(.not-fumadocs-codeblock *) code .highlighted {
+  border-radius: 4px;
+  background-color: #d6d8e3 !important;
+}
+
+.showcase-source-wrapper {
+  .code-block-wrapper {
+    background: transparent !important;
+  }
+
+  .fd-scroll-container {
+    max-height: 100%;
+    background: transparent;
+  }
+}
+
+/* ============================================================================
+   ANIMATIONS & KEYFRAMES
+   ============================================================================ */
+
+@keyframes shine {
+  0% {
+    translate: -100% 0;
+  }
+  100% {
+    translate: 100% 0;
+  }
+}
+
+@keyframes scrolling-banner {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(calc(-50% - var(--gap) / 2));
+  }
+}
+
+@keyframes scrolling-banner-vertical {
+  from {
+    transform: translateY(0);
+  }
+  to {
+    transform: translateY(calc(-50% - var(--gap) / 2));
+  }
+}
+
+@keyframes custom-fade-in {
+  from {
+    opacity: 0;
+    backdrop-filter: blur(0px) saturate(0%);
+    background-color: transparent;
+  }
+  to {
+    opacity: 1;
+    backdrop-filter: blur(8px) saturate(180%);
+    background-color: var(--color-backdrop);
+  }
+}
+
+@keyframes custom-fade-out {
+  from {
+    opacity: 1;
+    backdrop-filter: blur(8px);
+    -webkit-backdrop-filter: blur(8px);
+  }
+  to {
+    opacity: 0;
+    backdrop-filter: blur(0px);
+    -webkit-backdrop-filter: blur(0px);
+  }
+}
+
+/* ============================================================================
+   UTILITY CLASSES
+   ============================================================================ */
+
+.animate-scrolling-banner {
+  animation: scrolling-banner var(--duration) linear infinite;
+}
+
+.animate-scrolling-banner-vertical {
+  animation: scrolling-banner-vertical var(--duration) linear infinite;
+}
+
+@utility animate-shine {
+  overflow: hidden;
+
+  &::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    background: linear-gradient(
+      120deg,
+      transparent 10%,
+      rgba(255, 255, 255, 0.3) 45%,
+      rgba(255, 255, 255, 0.1) 55%,
+      transparent 90%
+    );
+    animation: shine 3s ease-in-out infinite;
+    pointer-events: none;
+  }
+
+  [data-theme="dark"] &::after,
+  .dark &::after {
+    background: linear-gradient(
+      120deg,
+      transparent 10%,
+      rgba(255, 255, 255, 0.1) 45%,
+      rgba(255, 255, 255, 0.04) 55%,
+      transparent 90%
+    );
+  }
+}
+
+@utility mask-to-t {
+  mask: linear-gradient(to top, rgba(0, 0, 0, 0) 0%, rgba(0, 0, 0, 0.8) 50%, rgba(0, 0, 0, 1) 100%);
+}
+
+@utility mask-to-bottom {
+  mask: linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, 1) 0%,
+    rgba(0, 0, 0, 1) 20%,
+    rgba(0, 0, 0, 0) 100%
+  );
+}
+
+/* ============================================================================
+   DARK THEME OVERRIDES
+   ============================================================================ */
+
+[data-theme="dark"],
+.dark {
+  /* Navigation Components */
+
+  #nd-sidebar a {
+    &:hover {
+      background: rgba(255, 255, 255, 0.04);
+    }
+
+    &[data-active="true"] {
+      background: rgba(255, 255, 255, 0.08);
+    }
+  }
+
+  #nd-sidebar a[rel="noreferrer noopener"]::after {
+    background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="10" height="10"><path d="M6 18L18 6m0 0H9m9 0v9" fill="none" stroke="white" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/></svg>');
+  }
+
+  /* Prose & Code Blocks */
+  .prose {
+    .shiki {
+      background: transparent;
+
+      figure {
+        padding: 0;
+      }
+
+      /* Scroll container */
+      .fd-scroll-container {
+        background: rgba(40, 40, 40, 0.4);
+      }
+    }
+  }
+
+  .docs-code-block {
+    background: rgba(40, 40, 40, 0.4);
+
+    .fd-scroll-container {
+      background: transparent !important;
+    }
+  }
+
+  /* Apply !important only for isolated code blocks (not code-block-wrapper) */
+  .is-isolated .docs-code-block {
+    background: rgba(40, 40, 40, 0.4) !important;
+  }
+
+  .shiki:not(.not-fumadocs-codeblock *) code .highlighted {
+    background-color: #2d2d2d !important;
+  }
+}
diff --git a/apps/docs/src/app/install/route.ts b/apps/docs/src/app/install/route.ts
new file mode 100644
index 0000000..20f4271
--- /dev/null
+++ b/apps/docs/src/app/install/route.ts
@@ -0,0 +1,41 @@
+import type {NextRequest} from "next/server";
+
+import fs from "fs";
+import path from "path";
+
+import {NextResponse} from "next/server";
+
+import {captureEvent} from "@/libs/posthog";
+
+export const revalidate = false;
+
+export async function GET(request: NextRequest) {
+  await captureEvent({
+    event: "heroui_skill_installed",
+    properties: {
+      city: request.headers.get("x-vercel-ip-city"),
+      country: request.headers.get("x-vercel-ip-country"),
+      ip: request.headers.get("x-forwarded-for"),
+      postalCode: request.headers.get("x-vercel-ip-postal-code"),
+      referer: request.headers.get("referer"),
+      region: request.headers.get("x-vercel-ip-region"),
+      url: request.url,
+      userAgent: request.headers.get("user-agent"),
+    },
+  });
+
+  const host = request.headers.get("host") || "v3.heroui.com";
+  const protocol = host.includes("localhost") ? "http" : "https";
+  const baseUrl = `${protocol}://${host}`;
+
+  const filePath = path.join(process.cwd(), "skills", "install.sh");
+  const installScript = fs.readFileSync(filePath, "utf-8");
+  const body = installScript.replace(/\{\{BASE_URL\}\}/g, baseUrl).trim() + "\n";
+
+  return new NextResponse(body, {
+    headers: {
+      "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
+      "Content-Type": "text/x-shellscript; charset=utf-8",
+    },
+  });
+}
diff --git a/apps/docs/src/app/llms-components.txt/route.ts b/apps/docs/src/app/llms-components.txt/route.ts
new file mode 100644
index 0000000..ed0bdfc
--- /dev/null
+++ b/apps/docs/src/app/llms-components.txt/route.ts
@@ -0,0 +1,35 @@
+import {getLLMText} from "@/lib/get-llm-text";
+import {LLMS_TEXT_HEADERS, filterExcludedPages, filterPagesByType} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const revalidate = false;
+
+export async function GET() {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+    const componentPages = filterPagesByType(pages, "components");
+
+    if (componentPages.length === 0) {
+      return new Response("No component documentation found", {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scan = componentPages.map(getLLMText);
+    const scanned = await Promise.all(scan);
+
+    const content = scanned.join("\n\n");
+
+    return new Response(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms-components.txt:", error);
+
+    return new Response("Error generating component documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/llms-full.txt/route.ts b/apps/docs/src/app/llms-full.txt/route.ts
new file mode 100644
index 0000000..6f6faeb
--- /dev/null
+++ b/apps/docs/src/app/llms-full.txt/route.ts
@@ -0,0 +1,34 @@
+import {getLLMText} from "@/lib/get-llm-text";
+import {LLMS_TEXT_HEADERS, filterExcludedPages} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const revalidate = false;
+
+export async function GET() {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+
+    if (pages.length === 0) {
+      return new Response("No content found", {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scan = pages.map(getLLMText);
+    const scanned = await Promise.all(scan);
+
+    const content = scanned.join("\n\n");
+
+    return new Response(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms-full.txt:", error);
+
+    return new Response("Error generating full documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/llms-patterns.txt/route.ts b/apps/docs/src/app/llms-patterns.txt/route.ts
new file mode 100644
index 0000000..9816371
--- /dev/null
+++ b/apps/docs/src/app/llms-patterns.txt/route.ts
@@ -0,0 +1,35 @@
+import {getLLMText} from "@/lib/get-llm-text";
+import {LLMS_TEXT_HEADERS, filterExcludedPages, filterPagesByType} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const revalidate = false;
+
+export async function GET() {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+    const patternPages = filterPagesByType(pages, "patterns");
+
+    if (patternPages.length === 0) {
+      return new Response("No pattern documentation found", {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scan = patternPages.map(getLLMText);
+    const scanned = await Promise.all(scan);
+
+    const content = scanned.join("\n\n");
+
+    return new Response(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms-patterns.txt:", error);
+
+    return new Response("Error generating pattern documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/llms-raw.mdx/[...slug]/route.ts b/apps/docs/src/app/llms-raw.mdx/[...slug]/route.ts
new file mode 100644
index 0000000..ca4c538
--- /dev/null
+++ b/apps/docs/src/app/llms-raw.mdx/[...slug]/route.ts
@@ -0,0 +1,46 @@
+import type {NextRequest} from "next/server";
+
+import {notFound} from "next/navigation";
+import {NextResponse} from "next/server";
+
+import {getLLMRawText} from "@/lib/get-llm-text";
+import {i18n} from "@/lib/i18n";
+import {LLMS_TEXT_HEADERS} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const dynamic = "force-static";
+export const revalidate = false;
+
+const SUPPORTED_LANGS = new Set<string>(i18n.languages);
+
+function extractLangFromSlug(slug: string[]): {slug: string[]; lang?: string} {
+  const first = slug[0];
+
+  if (first !== undefined && SUPPORTED_LANGS.has(first)) {
+    return {lang: first, slug: slug.slice(1)};
+  }
+
+  return {slug};
+}
+
+export async function GET(_req: NextRequest, {params}: {params: Promise<{slug: string[]}>}) {
+  const {lang, slug} = extractLangFromSlug((await params).slug);
+  const page = source.getPage(slug, lang);
+
+  if (!page) notFound();
+
+  try {
+    const content = await getLLMRawText(page);
+
+    return new NextResponse(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms-raw.mdx:", error);
+
+    return new NextResponse("Error generating raw documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/llms.mdx/[...slug]/route.ts b/apps/docs/src/app/llms.mdx/[...slug]/route.ts
new file mode 100644
index 0000000..57e2572
--- /dev/null
+++ b/apps/docs/src/app/llms.mdx/[...slug]/route.ts
@@ -0,0 +1,46 @@
+import type {NextRequest} from "next/server";
+
+import {notFound} from "next/navigation";
+import {NextResponse} from "next/server";
+
+import {getLLMText} from "@/lib/get-llm-text";
+import {i18n} from "@/lib/i18n";
+import {LLMS_TEXT_HEADERS} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const dynamic = "force-static";
+export const revalidate = false;
+
+const SUPPORTED_LANGS = new Set<string>(i18n.languages);
+
+function extractLangFromSlug(slug: string[]): {slug: string[]; lang?: string} {
+  const first = slug[0];
+
+  if (first !== undefined && SUPPORTED_LANGS.has(first)) {
+    return {lang: first, slug: slug.slice(1)};
+  }
+
+  return {slug};
+}
+
+export async function GET(_req: NextRequest, {params}: {params: Promise<{slug: string[]}>}) {
+  const {lang, slug} = extractLangFromSlug((await params).slug);
+  const page = source.getPage(slug, lang);
+
+  if (!page) notFound();
+
+  try {
+    const content = await getLLMText(page);
+
+    return new NextResponse(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms.mdx:", error);
+
+    return new NextResponse("Error generating documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/llms.txt/route.ts b/apps/docs/src/app/llms.txt/route.ts
new file mode 100644
index 0000000..e41927d
--- /dev/null
+++ b/apps/docs/src/app/llms.txt/route.ts
@@ -0,0 +1,82 @@
+import {siteConfig} from "@/config/site";
+import {LLMS_TEXT_HEADERS, filterExcludedPages, generateIndexHeader} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export const revalidate = false;
+
+function formatAbsoluteUrl(path: string): string {
+  if (!path) return "";
+
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+
+  const baseUrl = siteConfig.siteUrl.toString().replace(/\/$/, "");
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+  return `${baseUrl}${cleanPath}`;
+}
+
+export async function GET() {
+  try {
+    const scanned = generateIndexHeader();
+
+    const pages = filterExcludedPages(source.getPages());
+    const map = new Map<string, string[]>();
+
+    for (const page of pages) {
+      const dir = page.slugs[0] ?? "";
+      const list = map.get(dir) ?? [];
+      const absoluteUrl = formatAbsoluteUrl(page.url);
+
+      if (page.data.description) {
+        list.push(`- [${page.data.title}](${absoluteUrl}): ${page.data.description}`);
+      } else {
+        list.push(`- [${page.data.title}](${absoluteUrl})`);
+      }
+
+      map.set(dir, list);
+    }
+
+    const platformOrder = ["react", "native"];
+
+    for (const platform of platformOrder) {
+      const pages = map.get(platform);
+
+      if (pages && pages.length > 0) {
+        scanned.push(`### ${platform.charAt(0).toUpperCase() + platform.slice(1)}`);
+        scanned.push("");
+        scanned.push(pages.join("\n"));
+        scanned.push("");
+      }
+    }
+
+    const otherKeys = Array.from(map.keys()).filter((key) => !platformOrder.includes(key));
+
+    if (otherKeys.length > 0) {
+      for (const key of otherKeys) {
+        const value = map.get(key);
+
+        if (value) {
+          scanned.push(`### ${key}`);
+          scanned.push("");
+          scanned.push(value.join("\n"));
+          scanned.push("");
+        }
+      }
+    }
+
+    const content = scanned.join("\n");
+
+    return new Response(content, {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error("Error generating llms.txt:", error);
+
+    return new Response("Error generating documentation index", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
diff --git a/apps/docs/src/app/manifest.ts b/apps/docs/src/app/manifest.ts
new file mode 100644
index 0000000..06b7814
--- /dev/null
+++ b/apps/docs/src/app/manifest.ts
@@ -0,0 +1,29 @@
+import type {MetadataRoute} from "next";
+
+import {siteConfig} from "@/config/site";
+
+export default function manifest(): MetadataRoute.Manifest {
+  return {
+    background_color: "#ffffff",
+    description: siteConfig.description,
+    display: "standalone",
+    icons: [
+      {
+        purpose: "maskable",
+        sizes: "192x192",
+        src: "/icons/web-app-manifest-192x192.png",
+        type: "image/png",
+      },
+      {
+        purpose: "maskable",
+        sizes: "512x512",
+        src: "/icons/web-app-manifest-512x512.png",
+        type: "image/png",
+      },
+    ],
+    name: "HeroUI",
+    short_name: "HeroUI",
+    start_url: "/",
+    theme_color: "#000000",
+  };
+}
diff --git a/apps/docs/src/app/native/llms-components.txt/route.ts b/apps/docs/src/app/native/llms-components.txt/route.ts
new file mode 100644
index 0000000..157ce33
--- /dev/null
+++ b/apps/docs/src/app/native/llms-components.txt/route.ts
@@ -0,0 +1,8 @@
+import {
+  createPlatformRouteHandler,
+  getPlatformLlmsComponentsTxt,
+} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("native", getPlatformLlmsComponentsTxt);
diff --git a/apps/docs/src/app/native/llms-full.txt/route.ts b/apps/docs/src/app/native/llms-full.txt/route.ts
new file mode 100644
index 0000000..c4c3ceb
--- /dev/null
+++ b/apps/docs/src/app/native/llms-full.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsFullTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("native", getPlatformLlmsFullTxt);
diff --git a/apps/docs/src/app/native/llms-patterns.txt/route.ts b/apps/docs/src/app/native/llms-patterns.txt/route.ts
new file mode 100644
index 0000000..020d049
--- /dev/null
+++ b/apps/docs/src/app/native/llms-patterns.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsPatternsTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("native", getPlatformLlmsPatternsTxt);
diff --git a/apps/docs/src/app/native/llms.txt/route.ts b/apps/docs/src/app/native/llms.txt/route.ts
new file mode 100644
index 0000000..e76a6c9
--- /dev/null
+++ b/apps/docs/src/app/native/llms.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("native", getPlatformLlmsTxt);
diff --git a/apps/docs/src/app/og/[...slug]/route.tsx b/apps/docs/src/app/og/[...slug]/route.tsx
new file mode 100644
index 0000000..3b7ab01
--- /dev/null
+++ b/apps/docs/src/app/og/[...slug]/route.tsx
@@ -0,0 +1,116 @@
+import type {ImageResponseOptions} from "next/dist/compiled/@vercel/og/types";
+import type {ReactElement, ReactNode} from "react";
+
+import {promises} from "fs";
+import path from "path";
+
+import {notFound} from "next/navigation";
+import {ImageResponse} from "next/og";
+
+import {HeroUILogo} from "@/components/heroui-logo";
+import {source} from "@/lib/source";
+
+interface GenerateProps {
+  title: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  site?: ReactNode;
+}
+
+function generateOGImage(options: GenerateProps & ImageResponseOptions): ImageResponse {
+  const {description, icon, site, title, ...rest} = options;
+
+  return new ImageResponse(generate({description, icon, site, title}), {
+    height: 630,
+    width: 1200,
+    ...rest,
+  });
+}
+
+function generate({...props}: GenerateProps): ReactElement {
+  return (
+    <div
+      style={{
+        background: "#F5F5F5",
+        color: "#18181B",
+        display: "flex",
+        flexDirection: "column",
+        height: "100%",
+        padding: "4rem",
+        width: "100%",
+      }}
+    >
+      {/* Title */}
+      <p
+        style={{
+          fontSize: "82px",
+          fontWeight: 800,
+        }}
+      >
+        {props.title}
+      </p>
+
+      {/* Description */}
+      <p
+        style={{
+          WebkitBoxOrient: "vertical",
+          WebkitLineClamp: 3,
+          color: "#71717A",
+          display: "-webkit-box",
+          fontSize: "52px",
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {props.description}
+      </p>
+
+      {/* Logo & Title */}
+      <div
+        style={{
+          alignItems: "center",
+          display: "flex",
+          flexDirection: "row",
+          gap: "16px",
+          marginBottom: "12px",
+          marginTop: "auto",
+        }}
+      >
+        {props.icon}
+      </div>
+    </div>
+  );
+}
+
+const [interRegular, interBold] = await Promise.all([
+  promises.readFile(path.join(process.cwd(), "public/fonts/Inter-Regular.ttf")),
+  promises.readFile(path.join(process.cwd(), "public/fonts/Inter-Bold.ttf")),
+]);
+
+export const GET = async (_req: Request, {params}: {params: Promise<{slug: string[]}>}) => {
+  const {slug} = await params;
+  const page = source.getPage(slug.slice(0, -1));
+
+  if (!page) notFound();
+
+  return generateOGImage({
+    description: page.data.description,
+    fonts: [
+      {
+        data: interRegular,
+        name: "Inter",
+        weight: 400,
+      },
+      {
+        data: interBold,
+        name: "Inter",
+        weight: 600,
+      },
+    ],
+    icon: <HeroUILogo size={58} />,
+    title: page.data.title,
+  });
+};
+
+export const dynamic = "force-static";
+export const revalidate = false;
diff --git a/apps/docs/src/app/react/llms-components.txt/route.ts b/apps/docs/src/app/react/llms-components.txt/route.ts
new file mode 100644
index 0000000..6b4fc98
--- /dev/null
+++ b/apps/docs/src/app/react/llms-components.txt/route.ts
@@ -0,0 +1,8 @@
+import {
+  createPlatformRouteHandler,
+  getPlatformLlmsComponentsTxt,
+} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("react", getPlatformLlmsComponentsTxt);
diff --git a/apps/docs/src/app/react/llms-full.txt/route.ts b/apps/docs/src/app/react/llms-full.txt/route.ts
new file mode 100644
index 0000000..8be2d3e
--- /dev/null
+++ b/apps/docs/src/app/react/llms-full.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsFullTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("react", getPlatformLlmsFullTxt);
diff --git a/apps/docs/src/app/react/llms-patterns.txt/route.ts b/apps/docs/src/app/react/llms-patterns.txt/route.ts
new file mode 100644
index 0000000..6b1079c
--- /dev/null
+++ b/apps/docs/src/app/react/llms-patterns.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsPatternsTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("react", getPlatformLlmsPatternsTxt);
diff --git a/apps/docs/src/app/react/llms.txt/route.ts b/apps/docs/src/app/react/llms.txt/route.ts
new file mode 100644
index 0000000..c79cdf4
--- /dev/null
+++ b/apps/docs/src/app/react/llms.txt/route.ts
@@ -0,0 +1,5 @@
+import {createPlatformRouteHandler, getPlatformLlmsTxt} from "@/lib/llms-platform-handlers";
+
+export const revalidate = false;
+
+export const GET = createPlatformRouteHandler("react", getPlatformLlmsTxt);
diff --git a/apps/docs/src/app/rss.xml/route.ts b/apps/docs/src/app/rss.xml/route.ts
new file mode 100644
index 0000000..63b4de4
--- /dev/null
+++ b/apps/docs/src/app/rss.xml/route.ts
@@ -0,0 +1,13 @@
+import {getRSS} from "@/lib/rss";
+
+export const revalidate = false;
+
+export const GET = async () => {
+  const rss = await getRSS();
+
+  return new Response(rss, {
+    headers: {
+      "Content-Type": "application/xml",
+    },
+  });
+};
diff --git a/apps/docs/src/app/skills/[skill]/route.ts b/apps/docs/src/app/skills/[skill]/route.ts
new file mode 100644
index 0000000..06463b3
--- /dev/null
+++ b/apps/docs/src/app/skills/[skill]/route.ts
@@ -0,0 +1,70 @@
+import fs from "fs";
+import path from "path";
+
+import {NextResponse} from "next/server";
+
+import {VALID_SKILLS} from "@/lib/skills-constants.mjs";
+
+export async function GET(_: Request, {params}: {params: Promise<{skill: string}>}) {
+  try {
+    // Await params (Next.js 15+ requires params to be awaited)
+    const {skill} = await params;
+
+    // Extract skill name from parameter (handle .tar.gz suffix)
+    let skillName = skill.replace(/\.tar\.gz$/, "");
+
+    // Normalize skill names
+    if (skillName === "react") {
+      skillName = "heroui-react";
+    }
+
+    if (skillName === "native") {
+      skillName = "heroui-native";
+    }
+
+    // Validate skill name
+    if (!VALID_SKILLS.includes(skillName)) {
+      return NextResponse.json(
+        {
+          available: VALID_SKILLS,
+          error: `Invalid skill: ${skillName}`,
+        },
+        {status: 404},
+      );
+    }
+
+    // Serve pre-built tar.gz file from public directory
+    const tarFilePath = path.join(process.cwd(), "public", "skills", `${skillName}.tar.gz`);
+
+    if (!fs.existsSync(tarFilePath)) {
+      return NextResponse.json(
+        {
+          error: `Skill tarball not found: ${skillName}`,
+          message:
+            "The skill tarball may not have been built. Run 'pnpm dev' or 'pnpm build' to build skill files.",
+        },
+        {status: 404},
+      );
+    }
+
+    const tarBuffer = fs.readFileSync(tarFilePath);
+
+    return new NextResponse(tarBuffer, {
+      headers: {
+        "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
+        "Content-Disposition": `attachment; filename=${skillName}.tar.gz`,
+        "Content-Type": "application/gzip",
+      },
+    });
+  } catch (error) {
+    console.error("Error serving skill tarball:", error);
+
+    return NextResponse.json(
+      {
+        error: "Failed to serve skill tarball",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+      {status: 500},
+    );
+  }
+}
diff --git a/apps/docs/src/assets/themes/airbnb.png b/apps/docs/src/assets/themes/airbnb.png
new file mode 100644
index 0000000..ae458fe
Binary files /dev/null and b/apps/docs/src/assets/themes/airbnb.png differ
diff --git a/apps/docs/src/assets/themes/black.png b/apps/docs/src/assets/themes/black.png
new file mode 100644
index 0000000..c42f9bf
Binary files /dev/null and b/apps/docs/src/assets/themes/black.png differ
diff --git a/apps/docs/src/assets/themes/coinbase.png b/apps/docs/src/assets/themes/coinbase.png
new file mode 100644
index 0000000..0c5b71f
Binary files /dev/null and b/apps/docs/src/assets/themes/coinbase.png differ
diff --git a/apps/docs/src/assets/themes/default.png b/apps/docs/src/assets/themes/default.png
new file mode 100644
index 0000000..7f81af5
Binary files /dev/null and b/apps/docs/src/assets/themes/default.png differ
diff --git a/apps/docs/src/assets/themes/discord.png b/apps/docs/src/assets/themes/discord.png
new file mode 100644
index 0000000..99dd73a
Binary files /dev/null and b/apps/docs/src/assets/themes/discord.png differ
diff --git a/apps/docs/src/assets/themes/glass.png b/apps/docs/src/assets/themes/glass.png
new file mode 100644
index 0000000..647094a
Binary files /dev/null and b/apps/docs/src/assets/themes/glass.png differ
diff --git a/apps/docs/src/assets/themes/lavender.png b/apps/docs/src/assets/themes/lavender.png
new file mode 100644
index 0000000..987d556
Binary files /dev/null and b/apps/docs/src/assets/themes/lavender.png differ
diff --git a/apps/docs/src/assets/themes/mint.png b/apps/docs/src/assets/themes/mint.png
new file mode 100644
index 0000000..10a1328
Binary files /dev/null and b/apps/docs/src/assets/themes/mint.png differ
diff --git a/apps/docs/src/assets/themes/netflix.png b/apps/docs/src/assets/themes/netflix.png
new file mode 100644
index 0000000..6e32173
Binary files /dev/null and b/apps/docs/src/assets/themes/netflix.png differ
diff --git a/apps/docs/src/assets/themes/rabbit.png b/apps/docs/src/assets/themes/rabbit.png
new file mode 100644
index 0000000..1e6572d
Binary files /dev/null and b/apps/docs/src/assets/themes/rabbit.png differ
diff --git a/apps/docs/src/assets/themes/sky.png b/apps/docs/src/assets/themes/sky.png
new file mode 100644
index 0000000..2aeb801
Binary files /dev/null and b/apps/docs/src/assets/themes/sky.png differ
diff --git a/apps/docs/src/assets/themes/spotify.png b/apps/docs/src/assets/themes/spotify.png
new file mode 100644
index 0000000..4ff5906
Binary files /dev/null and b/apps/docs/src/assets/themes/spotify.png differ
diff --git a/apps/docs/src/components-registry.ts b/apps/docs/src/components-registry.ts
new file mode 100644
index 0000000..18217cd
--- /dev/null
+++ b/apps/docs/src/components-registry.ts
@@ -0,0 +1,825 @@
+export interface ComponentInfo {
+  name: string;
+  title: string;
+  description: string;
+  href: string;
+  category?: string;
+}
+
+const componentsMap: Record<string, ComponentInfo> = {
+  accordion: {
+    category: "layout",
+    description: "Collapsible content sections",
+    href: "/docs/components/accordion",
+    name: "accordion",
+    title: "Accordion",
+  },
+  alert: {
+    category: "display",
+    description: "Display important messages and notifications",
+    href: "/docs/components/alert",
+    name: "alert",
+    title: "Alert",
+  },
+  alertdialog: {
+    category: "layout",
+    description: "Critical confirmations requiring user attention",
+    href: "/docs/components/alert-dialog",
+    name: "alertdialog",
+    title: "AlertDialog",
+  },
+  autocomplete: {
+    category: "forms",
+    description: "Text input with searchable suggestions",
+    href: "/docs/components/autocomplete",
+    name: "autocomplete",
+    title: "Autocomplete",
+  },
+  avatar: {
+    category: "display",
+    description: "Display user profile images",
+    href: "/docs/components/avatar",
+    name: "avatar",
+    title: "Avatar",
+  },
+  badge: {
+    category: "display",
+    description: "Small indicator positioned relative to another element",
+    href: "/docs/components/badge",
+    name: "badge",
+    title: "Badge",
+  },
+  breadcrumbs: {
+    category: "navigation",
+    description: "Display the user's current location within a hierarchy",
+    href: "/docs/components/breadcrumbs",
+    name: "breadcrumbs",
+    title: "Breadcrumbs",
+  },
+  button: {
+    category: "forms",
+    description: "Allows a user to perform an action",
+    href: "/docs/components/button",
+    name: "button",
+    title: "Button",
+  },
+  buttongroup: {
+    category: "forms",
+    description: "Group related buttons together",
+    href: "/docs/components/button-group",
+    name: "buttongroup",
+    title: "ButtonGroup",
+  },
+  calendar: {
+    category: "date-time",
+    description: "Interactive month grid for selecting dates",
+    href: "/docs/components/calendar",
+    name: "calendar",
+    title: "Calendar",
+  },
+  card: {
+    category: "layout",
+    description: "Content container with header, body, and footer",
+    href: "/docs/components/card",
+    name: "card",
+    title: "Card",
+  },
+  checkbox: {
+    category: "forms",
+    description: "Binary choice input control",
+    href: "/docs/components/checkbox",
+    name: "checkbox",
+    title: "Checkbox",
+  },
+  checkboxgroup: {
+    category: "forms",
+    description: "Group of checkboxes with shared state",
+    href: "/docs/components/checkbox-group",
+    name: "checkboxgroup",
+    title: "CheckboxGroup",
+  },
+  chip: {
+    category: "display",
+    description: "Compact elements for tags and filters",
+    href: "/docs/components/chip",
+    name: "chip",
+    title: "Chip",
+  },
+  closebutton: {
+    category: "forms",
+    description: "Button for dismissing overlays",
+    href: "/docs/components/close-button",
+    name: "closebutton",
+    title: "CloseButton",
+  },
+  colorarea: {
+    category: "colors",
+    description: "2D color picker for selecting colors from a gradient area",
+    href: "/docs/components/color-area",
+    name: "colorarea",
+    title: "ColorArea",
+  },
+  colorfield: {
+    category: "colors",
+    description: "Input for entering color values with hex format",
+    href: "/docs/components/color-field",
+    name: "colorfield",
+    title: "ColorField",
+  },
+  colorpicker: {
+    category: "colors",
+    description: "Composable color picker with popover",
+    href: "/docs/components/color-picker",
+    name: "colorpicker",
+    title: "ColorPicker",
+  },
+  colorslider: {
+    category: "colors",
+    description: "Slider for adjusting individual color channel values",
+    href: "/docs/components/color-slider",
+    name: "colorslider",
+    title: "ColorSlider",
+  },
+  colorswatch: {
+    category: "colors",
+    description: "Visual preview of a color value",
+    href: "/docs/components/color-swatch",
+    name: "colorswatch",
+    title: "ColorSwatch",
+  },
+  colorswatchpicker: {
+    category: "colors",
+    description: "Color swatch selection from a list of colors",
+    href: "/docs/components/color-swatch-picker",
+    name: "colorswatchpicker",
+    title: "ColorSwatchPicker",
+  },
+  combobox: {
+    category: "forms",
+    description: "Text input with searchable dropdown list",
+    href: "/docs/components/combo-box",
+    name: "combobox",
+    title: "ComboBox",
+  },
+  datefield: {
+    category: "date-time",
+    description: "Date input field with labels, descriptions, and validation",
+    href: "/docs/components/date-field",
+    name: "datefield",
+    title: "DateField",
+  },
+  datepicker: {
+    category: "date-time",
+    description: "Composable date picker with date field trigger and calendar popover",
+    href: "/docs/components/date-picker",
+    name: "datepicker",
+    title: "DatePicker",
+  },
+  daterangepicker: {
+    category: "date-time",
+    description: "Composable date range picker with date field trigger and range calendar popover",
+    href: "/docs/components/date-range-picker",
+    name: "daterangepicker",
+    title: "DateRangePicker",
+  },
+  description: {
+    category: "forms",
+    description: "Helper text for form fields",
+    href: "/docs/components/description",
+    name: "description",
+    title: "Description",
+  },
+  disclosure: {
+    category: "layout",
+    description: "Single collapsible content section",
+    href: "/docs/components/disclosure",
+    name: "disclosure",
+    title: "Disclosure",
+  },
+  disclosuregroup: {
+    category: "layout",
+    description: "Group of collapsible panels",
+    href: "/docs/components/disclosure-group",
+    name: "disclosuregroup",
+    title: "DisclosureGroup",
+  },
+  drawer: {
+    category: "layout",
+    description: "Slide-out panel for supplementary content and actions",
+    href: "/docs/components/drawer",
+    name: "drawer",
+    title: "Drawer",
+  },
+  dropdown: {
+    category: "display",
+    description: "Context menu with actions and options",
+    href: "/docs/components/dropdown",
+    name: "dropdown",
+    title: "Dropdown",
+  },
+  errormessage: {
+    category: "forms",
+    description: "Displays validation error messages for components with validation support",
+    href: "/docs/components/error-message",
+    name: "errormessage",
+    title: "ErrorMessage",
+  },
+  fielderror: {
+    category: "forms",
+    description: "Inline validation messages for form fields",
+    href: "/docs/components/field-error",
+    name: "fielderror",
+    title: "FieldError",
+  },
+  fieldset: {
+    category: "forms",
+    description: "Group related form controls with legends",
+    href: "/docs/components/fieldset",
+    name: "fieldset",
+    title: "Fieldset",
+  },
+  form: {
+    category: "forms",
+    description: "Form validation and submission handling",
+    href: "/docs/components/form",
+    name: "form",
+    title: "Form",
+  },
+  input: {
+    category: "forms",
+    description: "Single-line text input built on React Aria",
+    href: "/docs/components/input",
+    name: "input",
+    title: "Input",
+  },
+  inputgroup: {
+    category: "forms",
+    description: "Group related input controls with prefix and suffix elements",
+    href: "/docs/components/input-group",
+    name: "inputgroup",
+    title: "InputGroup",
+  },
+  inputotp: {
+    category: "forms",
+    description: "One-time password input",
+    href: "/docs/components/input-otp",
+    name: "inputotp",
+    title: "InputOTP",
+  },
+  kbd: {
+    category: "display",
+    description: "Keyboard key display",
+    href: "/docs/components/kbd",
+    name: "kbd",
+    title: "Kbd",
+  },
+  label: {
+    category: "forms",
+    description: "Accessible label for form controls",
+    href: "/docs/components/label",
+    name: "label",
+    title: "Label",
+  },
+  link: {
+    category: "navigation",
+    description: "Styled anchor links",
+    href: "/docs/components/link",
+    name: "link",
+    title: "Link",
+  },
+  listbox: {
+    category: "display",
+    description: "Scrollable list of selectable items",
+    href: "/docs/components/list-box",
+    name: "list-box",
+    title: "Listbox",
+  },
+  meter: {
+    category: "feedback",
+    description: "A quantity indicator within a known range",
+    href: "/docs/components/meter",
+    name: "meter",
+    title: "Meter",
+  },
+  modal: {
+    category: "layout",
+    description: "Displays content in a modal overlay",
+    href: "/docs/components/modal",
+    name: "modal",
+    title: "Modal",
+  },
+  numberfield: {
+    category: "forms",
+    description: "Number input with increment/decrement buttons and validation",
+    href: "/docs/components/number-field",
+    name: "numberfield",
+    title: "NumberField",
+  },
+  pagination: {
+    category: "navigation",
+    description: "Page navigation with composable page links and controls",
+    href: "/docs/components/pagination",
+    name: "pagination",
+    title: "Pagination",
+  },
+  popover: {
+    category: "display",
+    description: "Displays content in context with a trigger",
+    href: "/docs/components/popover",
+    name: "popover",
+    title: "Popover",
+  },
+  progressbar: {
+    category: "feedback",
+    description: "Shows determinate or indeterminate progress of an operation",
+    href: "/docs/components/progress-bar",
+    name: "progressbar",
+    title: "ProgressBar",
+  },
+  progresscircle: {
+    category: "feedback",
+    description: "Circular progress indicator for operations",
+    href: "/docs/components/progress-circle",
+    name: "progresscircle",
+    title: "ProgressCircle",
+  },
+  radiogroup: {
+    category: "forms",
+    description: "Single selection from multiple options",
+    href: "/docs/components/radio-group",
+    name: "radiogroup",
+    title: "RadioGroup",
+  },
+  rangecalendar: {
+    category: "date-time",
+    description: "Interactive month grid for selecting date ranges",
+    href: "/docs/components/range-calendar",
+    name: "rangecalendar",
+    title: "RangeCalendar",
+  },
+  scrollshadow: {
+    category: "utilities",
+    description: "Visual shadows for scrollable content overflow",
+    href: "/docs/components/scroll-shadow",
+    name: "scrollshadow",
+    title: "ScrollShadow",
+  },
+  searchfield: {
+    category: "forms",
+    description: "Search input field with clear button and search icon",
+    href: "/docs/components/search-field",
+    name: "searchfield",
+    title: "SearchField",
+  },
+  select: {
+    category: "forms",
+    description: "Dropdown select control",
+    href: "/docs/components/select",
+    name: "select",
+    title: "Select",
+  },
+  separator: {
+    category: "layout",
+    description: "Visual divider between content",
+    href: "/docs/components/separator",
+    name: "separator",
+    title: "Separator",
+  },
+  skeleton: {
+    category: "display",
+    description: "Loading placeholder",
+    href: "/docs/components/skeleton",
+    name: "skeleton",
+    title: "Skeleton",
+  },
+  slider: {
+    category: "forms",
+    description: "Range selection slider",
+    href: "/docs/components/slider",
+    name: "slider",
+    title: "Slider",
+  },
+  spinner: {
+    category: "display",
+    description: "Loading indicator",
+    href: "/docs/components/spinner",
+    name: "spinner",
+    title: "Spinner",
+  },
+  surface: {
+    category: "layout",
+    description: "Base container surface",
+    href: "/docs/components/surface",
+    name: "surface",
+    title: "Surface",
+  },
+  switch: {
+    category: "controls",
+    description: "Toggle between two states",
+    href: "/docs/components/switch",
+    name: "switch",
+    title: "Switch",
+  },
+  table: {
+    category: "display",
+    description: "Structured data display in rows and columns",
+    href: "/docs/components/table",
+    name: "table",
+    title: "Table",
+  },
+  tabs: {
+    category: "layout",
+    description: "Organize content into tabbed views",
+    href: "/docs/components/tabs",
+    name: "tabs",
+    title: "Tabs",
+  },
+  taggroup: {
+    category: "display",
+    description: "Focusable list of tags with selection and removal support",
+    href: "/docs/components/tag-group",
+    name: "taggroup",
+    title: "TagGroup",
+  },
+  text: {
+    category: "display",
+    description: "Semantic typography primitive for headings, body copy, and inline code",
+    href: "/docs/components/text",
+    name: "text",
+    title: "Text",
+  },
+  textarea: {
+    category: "forms",
+    description: "Multiline text input with focus management",
+    href: "/docs/components/text-area",
+    name: "textarea",
+    title: "TextArea",
+  },
+  textfield: {
+    category: "forms",
+    description: "Composition-friendly fields with labels and validation",
+    href: "/docs/components/text-field",
+    name: "textfield",
+    title: "TextField",
+  },
+  timefield: {
+    category: "date-time",
+    description: "Time input field with labels, descriptions, and validation",
+    href: "/docs/components/time-field",
+    name: "timefield",
+    title: "TimeField",
+  },
+  toast: {
+    category: "display",
+    description:
+      "Display temporary notifications and messages to users with automatic dismissal and customizable placement",
+    href: "/docs/components/toast",
+    name: "toast",
+    title: "Toast",
+  },
+  togglebutton: {
+    category: "forms",
+    description: "Interactive toggle control for on/off states",
+    href: "/docs/components/toggle-button",
+    name: "togglebutton",
+    title: "ToggleButton",
+  },
+  togglebuttongroup: {
+    category: "forms",
+    description: "Group multiple toggle buttons into a unified control",
+    href: "/docs/components/toggle-button-group",
+    name: "togglebuttongroup",
+    title: "ToggleButtonGroup",
+  },
+  toolbar: {
+    category: "layout",
+    description: "Container for interactive controls with arrow key navigation",
+    href: "/docs/components/toolbar",
+    name: "toolbar",
+    title: "Toolbar",
+  },
+  tooltip: {
+    category: "display",
+    description: "Contextual information on hover or focus",
+    href: "/docs/components/tooltip",
+    name: "tooltip",
+    title: "Tooltip",
+  },
+  typography: {
+    category: "display",
+    description: "Semantic typography primitive for headings, body copy, and inline code",
+    href: "/docs/components/typography",
+    name: "typography",
+    title: "Typography",
+  },
+};
+
+// Define relationships between components
+const componentRelationships: Record<string, string[]> = {
+  accordion: ["disclosuregroup", "disclosure"],
+  alert: ["closebutton", "button", "spinner", "toast"],
+  alertdialog: ["button", "closebutton"],
+  autocomplete: [
+    "listbox",
+    "popover",
+    "input",
+    "label",
+    "fielderror",
+    "form",
+    "surface",
+    "description",
+    "avatar",
+    "button",
+  ],
+  avatar: ["separator", "badge"],
+  badge: ["avatar", "chip"],
+  breadcrumbs: ["link", "separator", "tabs"],
+  button: [
+    "popover",
+    "tooltip",
+    "form",
+    "alert",
+    "alertdialog",
+    "closebutton",
+    "dropdown",
+    "toast",
+  ],
+  buttongroup: ["button", "dropdown", "chip"],
+  calendar: ["rangecalendar", "datefield", "datepicker", "timefield", "inputgroup", "form"],
+  card: ["surface", "avatar", "form", "button", "link", "closebutton"],
+  checkbox: ["label", "checkboxgroup", "description", "button"],
+  checkboxgroup: [
+    "checkbox",
+    "label",
+    "fieldset",
+    "surface",
+    "description",
+    "form",
+    "button",
+    "fielderror",
+  ],
+  chip: ["avatar", "closebutton", "separator"],
+  closebutton: ["alert", "alertdialog", "chip", "modal"],
+  colorarea: ["colorswatch", "colorswatchpicker", "colorfield", "colorpicker"],
+  colorfield: [
+    "colorswatch",
+    "colorswatchpicker",
+    "colorpicker",
+    "form",
+    "label",
+    "description",
+    "fielderror",
+  ],
+  colorpicker: [
+    "colorarea",
+    "colorslider",
+    "colorswatch",
+    "colorswatchpicker",
+    "colorfield",
+    "popover",
+  ],
+  colorslider: ["colorswatch", "colorswatchpicker", "colorpicker", "slider"],
+  colorswatch: ["colorswatchpicker", "colorfield", "colorarea", "colorpicker"],
+  colorswatchpicker: ["colorswatch", "colorfield", "colorarea", "colorpicker"],
+  combobox: [
+    "listbox",
+    "popover",
+    "input",
+    "label",
+    "fielderror",
+    "form",
+    "surface",
+    "description",
+    "separator",
+    "avatar",
+    "spinner",
+    "button",
+  ],
+  datefield: ["datepicker", "calendar", "label", "fielderror", "description", "form", "surface"],
+  datepicker: [
+    "calendar",
+    "rangecalendar",
+    "datefield",
+    "daterangepicker",
+    "timefield",
+    "inputgroup",
+    "form",
+    "popover",
+  ],
+  daterangepicker: [
+    "rangecalendar",
+    "calendar",
+    "datefield",
+    "datepicker",
+    "timefield",
+    "inputgroup",
+    "form",
+    "popover",
+  ],
+  description: [
+    "textfield",
+    "input",
+    "textarea",
+    "checkbox",
+    "radiogroup",
+    "switch",
+    "checkboxgroup",
+    "slider",
+    "select",
+    "combobox",
+    "numberfield",
+    "datefield",
+  ],
+  disclosure: ["accordion", "disclosuregroup", "button"],
+  disclosuregroup: ["accordion", "disclosure", "button", "separator"],
+  drawer: ["modal", "button", "closebutton", "alertdialog"],
+  dropdown: ["button", "popover", "separator", "listbox"],
+  errormessage: ["taggroup"],
+  fielderror: [
+    "textfield",
+    "input",
+    "textarea",
+    "combobox",
+    "form",
+    "numberfield",
+    "datefield",
+    "datepicker",
+    "timefield",
+  ],
+  fieldset: ["textfield", "label", "checkboxgroup", "surface"],
+  form: [
+    "button",
+    "fieldset",
+    "textfield",
+    "input",
+    "textarea",
+    "label",
+    "fielderror",
+    "checkbox",
+    "checkboxgroup",
+    "radiogroup",
+    "switch",
+    "select",
+    "combobox",
+    "slider",
+    "inputotp",
+    "numberfield",
+    "datefield",
+    "datepicker",
+    "timefield",
+  ],
+  input: [
+    "textfield",
+    "textarea",
+    "label",
+    "fielderror",
+    "form",
+    "surface",
+    "description",
+    "combobox",
+  ],
+  inputgroup: [
+    "textfield",
+    "input",
+    "label",
+    "fielderror",
+    "form",
+    "surface",
+    "description",
+    "button",
+    "chip",
+    "kbd",
+    "spinner",
+  ],
+  inputotp: ["input", "form", "surface", "button", "link", "spinner"],
+  kbd: [],
+  label: [
+    "input",
+    "textarea",
+    "fieldset",
+    "checkbox",
+    "checkboxgroup",
+    "radiogroup",
+    "switch",
+    "slider",
+    "select",
+    "combobox",
+    "numberfield",
+    "datefield",
+    "timefield",
+  ],
+  link: ["breadcrumbs"],
+  listbox: ["select", "combobox", "avatar", "kbd", "separator", "surface", "dropdown"],
+  modal: ["button", "tooltip", "select", "avatar", "drawer"],
+  numberfield: ["label", "description", "fielderror", "form", "surface", "button"],
+  pagination: ["button", "link"],
+  popover: ["button", "tooltip", "select", "combobox", "avatar", "dropdown"],
+  radiogroup: ["fieldset", "surface", "description", "form", "button", "fielderror"],
+  rangecalendar: [
+    "calendar",
+    "datefield",
+    "datepicker",
+    "daterangepicker",
+    "timefield",
+    "inputgroup",
+    "form",
+  ],
+  scrollshadow: [],
+  searchfield: ["label", "description", "fielderror", "form", "surface", "input", "closebutton"],
+  select: [
+    "listbox",
+    "popover",
+    "label",
+    "fielderror",
+    "form",
+    "surface",
+    "description",
+    "spinner",
+    "button",
+    "separator",
+    "avatar",
+    "combobox",
+  ],
+  separator: [
+    "card",
+    "chip",
+    "avatar",
+    "disclosuregroup",
+    "listbox",
+    "select",
+    "combobox",
+    "dropdown",
+    "breadcrumbs",
+  ],
+  skeleton: ["card", "avatar"],
+  slider: ["label", "form", "description"],
+  spinner: [],
+  surface: [
+    "checkboxgroup",
+    "fieldset",
+    "inputotp",
+    "input",
+    "radiogroup",
+    "select",
+    "combobox",
+    "textfield",
+    "textarea",
+    "numberfield",
+    "datefield",
+    "datepicker",
+    "timefield",
+    "card",
+    "listbox",
+  ],
+  switch: ["label", "description", "button", "form"],
+  table: ["pagination", "checkbox", "chip", "avatar", "button", "spinner"],
+  tabs: ["breadcrumbs"],
+  taggroup: ["tag", "label", "description", "errormessage", "closebutton"],
+  textarea: ["textfield", "input", "label", "fielderror", "form", "surface", "description"],
+  textfield: [
+    "input",
+    "textarea",
+    "fieldset",
+    "label",
+    "fielderror",
+    "surface",
+    "description",
+    "numberfield",
+    "inputgroup",
+    "datefield",
+  ],
+  timefield: ["label", "fielderror", "description", "form", "surface"],
+  toast: ["button", "alert", "closebutton", "spinner"],
+  togglebutton: ["button", "switch", "checkbox", "togglebuttongroup"],
+  togglebuttongroup: ["togglebutton", "buttongroup", "button"],
+  toolbar: ["buttongroup", "togglebuttongroup", "separator", "button"],
+  tooltip: ["button", "popover"],
+};
+
+/**
+ * Get information about a specific component
+ */
+export function getComponentInfo(componentName: string): ComponentInfo | undefined {
+  const normalizedName = componentName.toLowerCase().replace(/[-_\s]/g, "");
+
+  return componentsMap[normalizedName];
+}
+
+/**
+ * Get related components for a given component
+ */
+export function getRelatedComponents(componentName: string): ComponentInfo[] {
+  const normalizedName = componentName.toLowerCase().replace(/[-_\s]/g, "");
+  const relatedNames = componentRelationships[normalizedName] || [];
+
+  return relatedNames
+    .map((name) => componentsMap[name])
+    .filter((name): name is ComponentInfo => name !== undefined);
+}
+
+/**
+ * Get all components in a specific category
+ */
+export function getComponentsByCategory(category: string): ComponentInfo[] {
+  return Object.values(componentsMap).filter((comp) => comp.category === category);
+}
diff --git a/apps/docs/src/components/ai/page-actions.tsx b/apps/docs/src/components/ai/page-actions.tsx
new file mode 100644
index 0000000..d5f7658
--- /dev/null
+++ b/apps/docs/src/components/ai/page-actions.tsx
@@ -0,0 +1,196 @@
+"use client";
+
+import {Button, ButtonGroup, Description, Dropdown, Label} from "@heroui/react";
+import {useCopyButton} from "fumadocs-ui/utils/use-copy-button";
+import {ChevronDown} from "lucide-react";
+import {useMemo, useState} from "react";
+import {cn} from "tailwind-variants";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {ClaudeIcon, CursorIcon, MarkdownIcon, OpenAIIcon, VSCodeIcon} from "@/icons/dev";
+import {__DEV__} from "@/utils/env";
+
+import {Iconify} from "../iconify";
+
+const MAX_CACHE_SIZE = 50;
+const cache = new Map<string, string>();
+
+function setCache(key: string, value: string) {
+  if (cache.size >= MAX_CACHE_SIZE) {
+    const firstKey = cache.keys().next().value;
+
+    if (firstKey) {
+      cache.delete(firstKey);
+    }
+  }
+
+  cache.set(key, value);
+}
+
+function parseMarkdownUrl(markdownUrl: string): {slug: string; lang?: string} {
+  const url = markdownUrl.replace(/\.mdx$/, "");
+  const match = url.match(/^\/(?:(en|cn)\/)?docs\/(.*)$/);
+
+  if (!match) return {slug: "index"};
+
+  const [, lang, rest] = match;
+
+  return {lang, slug: rest || "index"};
+}
+
+export function ViewOptions({markdownUrl}: {markdownUrl: string}) {
+  const dict = useDictionary().pageActions;
+  const items = useMemo(() => {
+    let fullMarkdownUrl = "";
+
+    if (typeof window !== "undefined") {
+      try {
+        fullMarkdownUrl = new URL(markdownUrl, window.location.origin).href;
+      } catch {
+        fullMarkdownUrl = `${window.location.origin}${markdownUrl}`;
+      }
+    }
+
+    const query = fullMarkdownUrl
+      ? dict.askWithUrl.replace("{url}", fullMarkdownUrl)
+      : dict.askFallback;
+
+    return [
+      {
+        description: dict.items.markdown.description,
+        href: fullMarkdownUrl,
+        icon: <MarkdownIcon size={18} />,
+        key: "markdown",
+        title: dict.items.markdown.title,
+      },
+      {
+        description: dict.items.cursor.description,
+        href: "cursor://anysphere.cursor-deeplink/mcp/install?name=heroui-react&config=eyJjb21tYW5kIjoibnB4IC15IEBoZXJvdWkvcmVhY3QtbWNwQGxhdGVzdCJ9",
+        icon: <CursorIcon size={18} />,
+        key: "cursor",
+        title: dict.items.cursor.title,
+      },
+      {
+        description: dict.items.vscode.description,
+        href: "vscode:mcp/install?%7B%22name%22%3A%22heroui-react%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40heroui%2Freact-mcp%40latest%22%5D%7D",
+        icon: <VSCodeIcon size={18} />,
+        key: "vscode",
+        title: dict.items.vscode.title,
+      },
+      {
+        description: dict.items.chatgpt.description,
+        href: `https://chatgpt.com/?${new URLSearchParams({hints: "search", q: query})}`,
+        icon: <OpenAIIcon size={16} />,
+        key: "chatgpt",
+        title: dict.items.chatgpt.title,
+      },
+      {
+        description: dict.items.claude.description,
+        href: `https://claude.ai/new?${new URLSearchParams({q: query})}`,
+        icon: <ClaudeIcon size={16} />,
+        key: "claude",
+        title: dict.items.claude.title,
+      },
+    ];
+  }, [markdownUrl, dict]);
+
+  const [isLoading, setLoading] = useState(false);
+
+  const [isOpen, setOpen] = useState(false);
+  const [checked, onClick] = useCopyButton(async () => {
+    if (!__DEV__) {
+      const cached = cache.get(markdownUrl);
+
+      if (cached) {
+        return navigator.clipboard.writeText(cached);
+      }
+    }
+
+    const {lang, slug} = parseMarkdownUrl(markdownUrl);
+    const slugArray = slug.split("/").filter(Boolean);
+    const apiUrl = `/llms-raw.mdx/${[lang, ...slugArray].filter(Boolean).join("/")}`;
+
+    setLoading(true);
+
+    try {
+      const res = await fetch(apiUrl);
+
+      if (!res.ok) {
+        throw new Error(`Failed to fetch content: ${res.statusText}`);
+      }
+
+      const content = await res.text();
+
+      if (!__DEV__) {
+        setCache(markdownUrl, content);
+      }
+
+      await navigator.clipboard.writeText(content);
+    } catch (error) {
+      console.error("Failed to copy markdown:", error);
+      throw error;
+    } finally {
+      setLoading(false);
+    }
+  });
+
+  return (
+    <ButtonGroup size="md" variant="tertiary">
+      <Button className={isLoading ? "animate-pulse" : ""} isDisabled={isLoading} onClick={onClick}>
+        {checked ? (
+          <>
+            <Iconify icon="check" />
+            {dict.copied}
+          </>
+        ) : (
+          <>
+            <Iconify icon="copy" />
+            {dict.copyMarkdown}
+          </>
+        )}
+      </Button>
+      <Dropdown isOpen={isOpen} onOpenChange={setOpen}>
+        <Button isIconOnly aria-label={dict.moreOptions} size="md" variant="tertiary">
+          <ButtonGroup.Separator />
+          <ChevronDown
+            className={cn(
+              "text-fd-muted-foreground size-3.5 transition-transform",
+              isOpen && "rotate-180",
+            )}
+          />
+        </Button>
+        <Dropdown.Popover placement="bottom end">
+          <Dropdown.Menu
+            onAction={(key) => {
+              const item = items.find((i) => i.key === key);
+
+              if (item?.href) {
+                window.open(item.href, "_blank", "noreferrer noopener");
+              }
+            }}
+          >
+            {items.map((item) => (
+              <Dropdown.Item
+                key={item.key}
+                href={item.href}
+                id={item.key}
+                rel="noreferrer noopener"
+                target="_blank"
+                textValue={item.title}
+              >
+                {item.icon}
+                <div className="flex w-full flex-col">
+                  <Label className="flex gap-0.5">{item.title}</Label>
+                  <Description>{item.description}</Description>
+                </div>
+                {(item.key === "chatgpt" || item.key === "claude") && (
+                  <Iconify className="text-foreground/70" icon="arrow-up-right-from-square" />
+                )}
+              </Dropdown.Item>
+            ))}
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    </ButtonGroup>
+  );
+}
diff --git a/apps/docs/src/components/ai/webmcp-provider.tsx b/apps/docs/src/components/ai/webmcp-provider.tsx
new file mode 100644
index 0000000..f050a80
--- /dev/null
+++ b/apps/docs/src/components/ai/webmcp-provider.tsx
@@ -0,0 +1,276 @@
+"use client";
+
+import {useEffect} from "react";
+
+type WebMCPInput = Record<string, unknown>;
+
+type WebMCPTool = {
+  description: string;
+  execute: (input: WebMCPInput) => Promise<unknown> | unknown;
+  inputSchema: Record<string, unknown>;
+  name: string;
+};
+
+type WebMCPModelContext = {
+  provideContext?: (
+    context: {tools: WebMCPTool[]},
+    options?: {signal?: AbortSignal},
+  ) => (() => void) | void;
+  provideTools?: (tools: WebMCPTool[], options?: {signal?: AbortSignal}) => (() => void) | void;
+  registerTool?: (tool: WebMCPTool) => void;
+  unregisterTool?: (name: string) => void;
+};
+
+declare global {
+  interface Navigator {
+    modelContext?: WebMCPModelContext;
+  }
+}
+
+function getString(input: WebMCPInput, key: string, fallback = ""): string {
+  const value = input[key];
+
+  return typeof value === "string" ? value : fallback;
+}
+
+function getInteger(input: WebMCPInput, key: string, fallback: number): number {
+  const value = input[key];
+  const parsed = typeof value === "number" ? value : Number(value);
+
+  if (!Number.isFinite(parsed)) return fallback;
+
+  return Math.trunc(parsed);
+}
+
+function getPlatform(input: WebMCPInput, fallback: "all" | "native" | "react" = "all") {
+  const platform = getString(input, "platform", fallback);
+
+  if (platform === "react" || platform === "native" || platform === "all") return platform;
+
+  return fallback;
+}
+
+async function fetchJson(path: string): Promise<unknown> {
+  const response = await fetch(path, {
+    headers: {
+      Accept: "application/json",
+    },
+  });
+  const data: unknown = await response.json();
+
+  if (!response.ok) {
+    const message =
+      typeof data === "object" && data !== null && "error" in data && typeof data.error === "string"
+        ? data.error
+        : "HeroUI WebMCP request failed";
+
+    throw new Error(message);
+  }
+
+  return data;
+}
+
+function resolveSameOriginPath(value: string): string | null {
+  try {
+    const url = new URL(value, window.location.origin);
+
+    if (url.origin !== window.location.origin) return null;
+    if (
+      url.pathname === "/" ||
+      url.pathname.startsWith("/docs/") ||
+      url.pathname.startsWith("/llms")
+    ) {
+      return `${url.pathname}${url.search}${url.hash}`;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+const tools: WebMCPTool[] = [
+  {
+    description:
+      "Search HeroUI React and Native documentation. Use this when an agent needs relevant HeroUI docs pages by keyword.",
+    execute(input) {
+      const query = getString(input, "query").trim();
+      const platform = getPlatform(input);
+      const limit = Math.min(Math.max(getInteger(input, "limit", 10), 1), 20);
+
+      if (!query) throw new Error("query is required");
+
+      return fetchJson(
+        `/api/agent/search?q=${encodeURIComponent(query)}&platform=${platform}&limit=${limit}`,
+      );
+    },
+    inputSchema: {
+      properties: {
+        limit: {default: 10, maximum: 20, minimum: 1, type: "integer"},
+        platform: {default: "all", enum: ["all", "react", "native"], type: "string"},
+        query: {
+          description: "Search query, such as button, theming, or native colors.",
+          type: "string",
+        },
+      },
+      required: ["query"],
+      type: "object",
+    },
+    name: "search_heroui_docs",
+  },
+  {
+    description: "Retrieve a HeroUI documentation page as markdown by same-origin docs URL.",
+    execute(input) {
+      const url = resolveSameOriginPath(getString(input, "url"));
+
+      if (!url || !url.startsWith("/docs/")) {
+        throw new Error("url must be a same-origin /docs/ path");
+      }
+
+      return fetchJson(`/api/agent/page?url=${encodeURIComponent(url)}`);
+    },
+    inputSchema: {
+      properties: {
+        url: {
+          description: "A HeroUI docs path, for example /docs/react/components/button.",
+          type: "string",
+        },
+      },
+      required: ["url"],
+      type: "object",
+    },
+    name: "get_heroui_doc",
+  },
+  {
+    description:
+      "Navigate the browser to a HeroUI same-origin page such as the homepage or a docs page.",
+    execute(input) {
+      const url = resolveSameOriginPath(getString(input, "url"));
+
+      if (!url) {
+        throw new Error("url must be a same-origin HeroUI homepage, docs, or llms path");
+      }
+
+      window.location.assign(url);
+
+      return `Navigating to ${url}`;
+    },
+    inputSchema: {
+      properties: {
+        url: {
+          description: "A same-origin HeroUI path, for example /docs/react/getting-started.",
+          type: "string",
+        },
+      },
+      required: ["url"],
+      type: "object",
+    },
+    name: "navigate_heroui",
+  },
+  {
+    description: "List HeroUI component documentation pages for React or Native.",
+    execute(input) {
+      const platform = getPlatform(input, "react") === "native" ? "native" : "react";
+      const limit = Math.min(Math.max(getInteger(input, "limit", 20), 1), 20);
+
+      return fetchJson(
+        `/api/agent/search?q=${encodeURIComponent("/components/")}&platform=${platform}&limit=${limit}`,
+      );
+    },
+    inputSchema: {
+      properties: {
+        limit: {default: 20, maximum: 20, minimum: 1, type: "integer"},
+        platform: {default: "react", enum: ["react", "native"], type: "string"},
+      },
+      type: "object",
+    },
+    name: "list_heroui_components",
+  },
+];
+
+const WEBMCP_REGISTRATION_RETRY_MS = 100;
+const WEBMCP_REGISTRATION_TIMEOUT_MS = 5000;
+
+export function WebMCPProvider() {
+  useEffect(() => {
+    const abortController = new AbortController();
+    const registeredTools: string[] = [];
+    let cleanup: (() => void) | void;
+    let didRegister = false;
+    let didWarn = false;
+    let intervalId: ReturnType<typeof setInterval> | undefined;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    const registerTools = (modelContext: WebMCPModelContext | undefined): boolean => {
+      if (!modelContext || didRegister) return didRegister;
+
+      try {
+        if (typeof modelContext.provideContext === "function") {
+          cleanup = modelContext.provideContext({tools}, {signal: abortController.signal});
+          didRegister = true;
+
+          return true;
+        }
+
+        if (typeof modelContext.provideTools === "function") {
+          cleanup = modelContext.provideTools(tools, {signal: abortController.signal});
+          didRegister = true;
+
+          return true;
+        }
+
+        if (typeof modelContext.registerTool === "function") {
+          for (const tool of tools) {
+            modelContext.registerTool(tool);
+            registeredTools.push(tool.name);
+          }
+
+          didRegister = true;
+
+          return true;
+        }
+      } catch (error) {
+        if (!didWarn) {
+          console.warn("Unable to register HeroUI WebMCP tools", error);
+          didWarn = true;
+        }
+      }
+
+      return false;
+    };
+
+    if (!registerTools(navigator.modelContext)) {
+      intervalId = setInterval(() => {
+        if (registerTools(navigator.modelContext) && intervalId) {
+          clearInterval(intervalId);
+          intervalId = undefined;
+        }
+      }, WEBMCP_REGISTRATION_RETRY_MS);
+
+      timeoutId = setTimeout(() => {
+        if (intervalId) {
+          clearInterval(intervalId);
+          intervalId = undefined;
+        }
+      }, WEBMCP_REGISTRATION_TIMEOUT_MS);
+    }
+
+    return () => {
+      abortController.abort();
+
+      if (intervalId) clearInterval(intervalId);
+      if (timeoutId) clearTimeout(timeoutId);
+      if (typeof cleanup === "function") cleanup();
+
+      const modelContext = navigator.modelContext;
+
+      if (typeof modelContext?.unregisterTool === "function") {
+        for (const toolName of registeredTools) {
+          modelContext.unregisterTool(toolName);
+        }
+      }
+    };
+  }, []);
+
+  return null;
+}
diff --git a/apps/docs/src/components/code-panel.tsx b/apps/docs/src/components/code-panel.tsx
new file mode 100644
index 0000000..151cc6d
--- /dev/null
+++ b/apps/docs/src/components/code-panel.tsx
@@ -0,0 +1,186 @@
+"use client";
+
+import type {ReactNode} from "react";
+
+import {Skeleton} from "@heroui/react";
+import {useCopyButton} from "fumadocs-ui/utils/use-copy-button";
+import {AnimatePresence, LazyMotion, domAnimation, m} from "motion/react";
+import dynamic from "next/dynamic";
+import {Suspense, useCallback} from "react";
+
+import {Iconify} from "@/components/iconify";
+import {cn} from "@/utils/cn";
+
+// Dynamically import the highlighted code component (client-side only, with shiki)
+const HighlightedCode = dynamic(
+  () => import("@/components/highlighted-code").then((mod) => mod.HighlightedCode),
+  {
+    loading: () => <CodeLoadingSkeleton />,
+    ssr: false,
+  },
+);
+
+function CodeLoadingSkeleton() {
+  return (
+    <div className="space-y-2.5 py-4">
+      <Skeleton className="h-4 w-3/4 rounded-md" />
+      <Skeleton className="h-4 w-1/2 rounded-md" />
+      <Skeleton className="h-4 w-5/6 rounded-md" />
+      <Skeleton className="h-4 w-2/3 rounded-md" />
+      <Skeleton className="h-4 w-4/5 rounded-md" />
+      <Skeleton className="h-4 w-1/3 rounded-md" />
+      <Skeleton className="h-4 w-3/5 rounded-md" />
+      <Skeleton className="h-4 w-2/5 rounded-md" />
+      <Skeleton className="h-4 w-1/5 rounded-md" />
+      <Skeleton className="h-4 w-4/5 rounded-md" />
+      <Skeleton className="h-4 w-3/5 rounded-md" />
+      <Skeleton className="h-4 w-2/5 rounded-md" />
+      <Skeleton className="h-4 w-1/5 rounded-md" />
+      <Skeleton className="h-4 w-4/5 rounded-md" />
+      <Skeleton className="h-4 w-3/5 rounded-md" />
+    </div>
+  );
+}
+
+interface CodePanelProps {
+  /** Pre-rendered children (takes precedence over code prop) */
+  children?: ReactNode;
+  className?: string;
+  /** Raw source code to highlight (used with lang prop) */
+  sourceCode?: string;
+  /** File name for download */
+  fileName?: string;
+  /** Language for syntax highlighting when using code prop */
+  lang?: string;
+  /** Panel title */
+  title?: string;
+  /** Whether to show line numbers */
+  showLineNumbers?: boolean;
+  isVisible: boolean;
+  onClose: () => void;
+}
+
+const PANEL_ANIMATION = {
+  animate: {opacity: 1, x: 0},
+  exit: {opacity: 0, x: "100%"},
+  initial: {opacity: 0, x: "100%"},
+  transition: {bounce: 0, duration: 0.4, type: "spring"} as const,
+};
+
+const BACKDROP_ANIMATION = {
+  animate: {opacity: 1},
+  exit: {opacity: 0},
+  initial: {opacity: 0},
+  transition: {duration: 0.3, ease: "easeOut"} as const,
+};
+
+export function CodePanel({
+  children,
+  className,
+  fileName,
+  isVisible,
+  lang = "tsx",
+  onClose,
+  showLineNumbers = true,
+  sourceCode,
+  title = "Source code",
+}: CodePanelProps) {
+  const [copied, onCopy] = useCopyButton(() => {
+    if (sourceCode) {
+      void navigator.clipboard.writeText(sourceCode);
+    }
+  });
+
+  const handleDownload = useCallback(() => {
+    if (!sourceCode || !fileName) return;
+
+    const blob = new Blob([sourceCode], {type: "text/plain"});
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+
+    link.href = url;
+    link.download = fileName;
+    link.click();
+
+    URL.revokeObjectURL(url);
+  }, [sourceCode, fileName]);
+
+  if (!isVisible) return null;
+
+  // Determine what to render: children take precedence, otherwise highlight sourceCode
+  const renderContent = () => {
+    if (children) {
+      return children;
+    }
+
+    if (sourceCode) {
+      return (
+        <Suspense fallback={<CodeLoadingSkeleton />}>
+          <HighlightedCode code={sourceCode} lang={lang} showLineNumbers={showLineNumbers} />
+        </Suspense>
+      );
+    }
+
+    return null;
+  };
+
+  return (
+    <LazyMotion strict features={domAnimation}>
+      <AnimatePresence>
+        {/* Backdrop overlay */}
+        <m.div
+          key="code-panel-backdrop"
+          aria-label="Close source code"
+          className="fixed inset-0 z-9999 bg-black/40 backdrop-blur-sm"
+          role="button"
+          tabIndex={0}
+          onClick={onClose}
+          onKeyDown={(e) => e.key === "Escape" && onClose()}
+          {...BACKDROP_ANIMATION}
+        />
+
+        {/* Code panel */}
+        <m.aside
+          key="code-panel"
+          aria-label={title}
+          className={cn(
+            "fixed top-1/2 right-6 z-9999 flex h-[88vh] w-[45%] -translate-y-1/2 flex-col overflow-hidden rounded-xl bg-surface/94 shadow-xl backdrop-blur-md",
+            className,
+          )}
+          {...PANEL_ANIMATION}
+        >
+          {/* Header */}
+          <header className="flex shrink-0 items-center justify-between border-b border-separator/50 px-6 py-3">
+            <h3 className="text-sm font-medium text-foreground/60">{title}</h3>
+            <div className="flex items-center gap-1">
+              {!!sourceCode && !!fileName && (
+                <button
+                  aria-label="Download code"
+                  className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-md text-foreground/40 transition-colors hover:bg-foreground/5 hover:text-foreground/60"
+                  type="button"
+                  onClick={handleDownload}
+                >
+                  <Iconify icon="arrow-down-to-line" width={16} />
+                </button>
+              )}
+              {!!sourceCode && (
+                <button
+                  aria-label={copied ? "Copied!" : "Copy code"}
+                  className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-md text-foreground/40 transition-colors hover:bg-foreground/5 hover:text-foreground/60 data-[copied=true]:text-green-500"
+                  data-copied={copied || undefined}
+                  type="button"
+                  onClick={onCopy}
+                >
+                  <Iconify icon={copied ? "check" : "copy"} width={16} />
+                </button>
+              )}
+            </div>
+          </header>
+
+          {/* Code content */}
+          <div className="flex-1 overflow-auto px-4 py-2">{renderContent()}</div>
+        </m.aside>
+      </AnimatePresence>
+    </LazyMotion>
+  );
+}
diff --git a/apps/docs/src/components/codeblock-client.tsx b/apps/docs/src/components/codeblock-client.tsx
new file mode 100644
index 0000000..9ea2be9
--- /dev/null
+++ b/apps/docs/src/components/codeblock-client.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import type {CodeBlockProps} from "fumadocs-ui/components/codeblock";
+
+import {Button} from "@heroui/react";
+import * as React from "react";
+
+import {FumadocsCustomCodeblock as BaseCodeBlock} from "@/mdx-components/fumadocs-custom-codeblock";
+import {cn} from "@/utils/cn";
+
+export function CodeBlock({
+  children,
+  className,
+  code,
+  collapsible,
+  isIsolated = false,
+  preview,
+  showLineNumbers,
+  title,
+  ...props
+}: {
+  isIsolated?: boolean;
+  lang?: string;
+  code?: string;
+  collapsible?: boolean;
+  showLineNumbers?: boolean;
+  title: string | undefined;
+  children: React.ReactNode | React.ReactElement;
+  preview?: React.ReactNode;
+} & CodeBlockProps) {
+  const [isCollapsed, setIsCollapsed] = React.useState(true);
+
+  if (!collapsible) {
+    return (
+      <BaseCodeBlock
+        code={code}
+        title={title}
+        className={cn(
+          "code-block-wrapper docs-code-block",
+          isIsolated && "is-isolated",
+          showLineNumbers && "docs-code-block-line-numbers",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </BaseCodeBlock>
+    );
+  }
+
+  return (
+    <div className="relative">
+      <div
+        className={cn(
+          "code-block-wrapper",
+          isIsolated && "is-isolated",
+          isCollapsed && "mask-to-bottom relative max-h-[150px] overflow-hidden",
+          !isCollapsed && "pb-10",
+        )}
+      >
+        <BaseCodeBlock
+          code={code}
+          title={title}
+          className={cn(
+            "docs-code-block shadow-none",
+            showLineNumbers && "docs-code-block-line-numbers",
+            className,
+          )}
+          {...props}
+        >
+          {isCollapsed && preview ? preview : children}
+        </BaseCodeBlock>
+      </div>
+      <Button
+        className="absolute right-1/2 bottom-2 translate-x-1/2 bg-surface text-xs shadow-sm shadow-black/5"
+        size="sm"
+        type="button"
+        variant="tertiary"
+        onPress={() => setIsCollapsed(!isCollapsed)}
+      >
+        {isCollapsed ? "Expand code" : "Collapse code"}
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/codeblock.tsx b/apps/docs/src/components/codeblock.tsx
new file mode 100644
index 0000000..70a16a2
--- /dev/null
+++ b/apps/docs/src/components/codeblock.tsx
@@ -0,0 +1,88 @@
+import type {CodeBlockProps} from "fumadocs-ui/components/codeblock";
+
+import {highlight} from "fumadocs-core/highlight";
+import * as Base from "fumadocs-ui/components/codeblock";
+import * as React from "react";
+
+import {CodeBlock as CodeBlockClient} from "./codeblock-client";
+
+export async function CodeBlock({
+  className,
+  code,
+  collapsible,
+  isIsolated = false,
+  lang,
+  showLineNumbers,
+  title,
+  ...props
+}: {
+  code: string;
+  lang: string;
+  // Means the code block is rendered directly in the MDX file using <CollapsibleCode>
+  isIsolated?: boolean;
+  showLineNumbers?: boolean;
+  title: string | undefined;
+  collapsible?: boolean;
+} & CodeBlockProps) {
+  let rendered;
+  let renderedPreview;
+
+  try {
+    // Trim the code to avoid issues with leading/trailing whitespace
+    const trimmedCode = code?.trim() || "";
+
+    // Skip highlighting for empty code blocks
+    if (!trimmedCode) {
+      rendered = (
+        <Base.Pre>
+          <code />
+        </Base.Pre>
+      );
+    } else {
+      const lines = trimmedCode.split("\n");
+
+      if (lines.length > 10) {
+        const previewCode = lines.slice(0, 5).join("\n");
+
+        renderedPreview = await highlight(previewCode, {
+          components: {
+            pre: (props) => <Base.Pre {...props} />,
+          },
+          lang: lang || "text",
+        });
+      }
+
+      rendered = await highlight(trimmedCode, {
+        components: {
+          pre: (props) => <Base.Pre {...props} />,
+        },
+        lang: lang || "text",
+        // other Shiki options
+      });
+    }
+  } catch (error) {
+    console.error("Syntax highlighting error:", error);
+    // Fallback to plain code block without syntax highlighting
+    rendered = (
+      <Base.Pre>
+        <code>{code}</code>
+      </Base.Pre>
+    );
+  }
+
+  return (
+    <CodeBlockClient
+      className={className}
+      code={code?.trim() || ""}
+      collapsible={collapsible}
+      isIsolated={isIsolated}
+      lang={lang}
+      preview={renderedPreview}
+      showLineNumbers={showLineNumbers}
+      title={title}
+      {...props}
+    >
+      {rendered}
+    </CodeBlockClient>
+  );
+}
diff --git a/apps/docs/src/components/collapsible-code.tsx b/apps/docs/src/components/collapsible-code.tsx
new file mode 100644
index 0000000..5209f27
--- /dev/null
+++ b/apps/docs/src/components/collapsible-code.tsx
@@ -0,0 +1,29 @@
+import {CodeBlock} from "./codeblock";
+
+export function CollapsibleCode({
+  className = "",
+  code,
+  collapsible = true,
+  lang = "tsx",
+  showLineNumbers = true,
+  title = "",
+}: {
+  code: string;
+  lang?: string;
+  showLineNumbers?: boolean;
+  title?: string;
+  className?: string;
+  collapsible?: boolean;
+}) {
+  return (
+    <CodeBlock
+      isIsolated
+      className={className}
+      code={code}
+      collapsible={collapsible}
+      lang={lang}
+      showLineNumbers={showLineNumbers}
+      title={title}
+    />
+  );
+}
diff --git a/apps/docs/src/components/color-picker/color-picker.tsx b/apps/docs/src/components/color-picker/color-picker.tsx
new file mode 100644
index 0000000..2bc4003
--- /dev/null
+++ b/apps/docs/src/components/color-picker/color-picker.tsx
@@ -0,0 +1,216 @@
+"use client";
+
+import type {ColorFormat, ColorPickerProps} from "./types";
+
+import {Shuffle} from "@gravity-ui/icons";
+import {Button, InputGroup, ListBox, Popover, Select, TextField} from "@heroui/react";
+import React, {useState} from "react";
+import {ColorPicker as AriaColorPicker, parseColor} from "react-aria-components";
+
+import {cn} from "@/utils/cn";
+
+import {ColorArea, ColorSlider, ColorSwatchesCarousel} from "./components";
+import {DEFAULT_COLOR, defaultSwatches} from "./constants";
+import {
+  detectColorFormat,
+  formatColor,
+  parseSafeDefaultValue,
+  safeParseColor,
+  validateColorInput,
+} from "./utils";
+
+export default function ColorPicker({
+  children,
+  defaultValue = DEFAULT_COLOR,
+  onChange,
+  popoverClassName,
+  showAlpha = false,
+  showColorField = true,
+  showShuffle = true,
+  showSwatches = true,
+  swatches = defaultSwatches,
+  trigger,
+  value: controlledValue,
+  ...props
+}: ColorPickerProps) {
+  const [currentColorFormat, setCurrentColorFormat] = useState<ColorFormat>("hex");
+  const [editingValue, setEditingValue] = useState<string | null>(null);
+  const [inputError, setInputError] = useState<boolean>(false);
+
+  // Safely parse default color value
+  const safeDefaultValue = React.useMemo(() => parseSafeDefaultValue(defaultValue), [defaultValue]);
+
+  // Internal color state for uncontrolled mode
+  const [internalColor, setInternalColor] = useState(safeDefaultValue);
+
+  // Use controlled value if provided, otherwise use internal state
+  const colorValue = controlledValue ? safeParseColor(controlledValue) : internalColor;
+
+  // Get initial color hex for swatches carousel
+  const initialColorHex =
+    (controlledValue as string | undefined)?.toLowerCase() ??
+    safeDefaultValue.toString("hex").toLowerCase();
+
+  const handleColorChange = (newColor: typeof colorValue) => {
+    setInternalColor(newColor);
+
+    onChange?.(newColor);
+  };
+
+  // Compute the displayed input value
+  const displayedInputValue = editingValue ?? formatColor(colorValue, currentColorFormat);
+
+  // Handle input change - validate on every change
+  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+
+    setEditingValue(newValue);
+
+    // Auto-detect and switch color format based on input
+    const detectedFormat = detectColorFormat(newValue);
+    const colorFormat = detectedFormat ?? currentColorFormat;
+
+    setCurrentColorFormat(colorFormat);
+    const validatedColor = validateColorInput(newValue, colorFormat);
+
+    if (validatedColor) {
+      handleColorChange(validatedColor);
+      setInputError(false);
+    } else {
+      setInputError(true);
+    }
+  };
+
+  // On blur, reset to the current valid color if there was an error
+  const handleInputBlur = () => {
+    if (inputError) {
+      setEditingValue(null);
+      setInputError(false);
+    } else {
+      setEditingValue(null);
+    }
+  };
+
+  const handleInputKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Escape") {
+      setEditingValue(null);
+      setInputError(false);
+      (e.target as HTMLInputElement).blur();
+    }
+  };
+
+  const handleInputFocus = () => {
+    setEditingValue(formatColor(colorValue, currentColorFormat));
+  };
+
+  const handleShuffle = () => {
+    const randomHue = Math.floor(Math.random() * 360);
+    const randomSaturation = 50 + Math.floor(Math.random() * 50);
+    const randomLightness = 40 + Math.floor(Math.random() * 30);
+    const randomColor = parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`);
+
+    handleColorChange(randomColor);
+  };
+
+  return (
+    <AriaColorPicker value={colorValue} onChange={handleColorChange} {...props}>
+      {() => (
+        <Popover>
+          <Popover.Trigger>{trigger}</Popover.Trigger>
+          <Popover.Content
+            className={cn("w-[248px] rounded-[20px]", popoverClassName)}
+            placement="top"
+          >
+            <Popover.Dialog className="flex flex-col gap-2 px-2 pt-4 pb-2">
+              {children ?? (
+                <>
+                  {/* Color Swatches Carousel */}
+                  {showSwatches ? (
+                    <ColorSwatchesCarousel initialColorHex={initialColorHex} swatches={swatches} />
+                  ) : null}
+
+                  {/* Color Area */}
+                  <ColorArea colorSpace="hsl" xChannel="saturation" yChannel="lightness" />
+
+                  {/* Hue Slider with Shuffle */}
+                  <div className="flex w-full items-center justify-between gap-2">
+                    <ColorSlider
+                      channel="hue"
+                      className="h-5 max-w-[184px] flex-1"
+                      colorSpace="hsl"
+                    />
+                    {showShuffle ? (
+                      <Button
+                        isIconOnly
+                        className="size-8 min-w-8 shrink-0 rounded-full"
+                        size="sm"
+                        variant="tertiary"
+                        onPress={handleShuffle}
+                      >
+                        <Shuffle className="size-4" />
+                      </Button>
+                    ) : null}
+                  </div>
+
+                  {/* Alpha Slider */}
+                  {showAlpha ? <ColorSlider channel="alpha" /> : null}
+
+                  {/* Color Field with Color Space Selector */}
+                  {showColorField ? (
+                    <TextField aria-labelledby="Accent color" isInvalid={inputError}>
+                      <InputGroup fullWidth className="rounded-xl" variant="secondary">
+                        <InputGroup.Input
+                          className="w-full flex-1 px-4 text-sm"
+                          value={displayedInputValue}
+                          onBlur={handleInputBlur}
+                          onChange={handleInputChange}
+                          onFocus={handleInputFocus}
+                          onKeyDown={handleInputKeyDown}
+                        />
+                        <InputGroup.Suffix className="border-l border-separator px-0">
+                          <Select
+                            aria-label="Color format"
+                            value={currentColorFormat}
+                            onChange={(key) => {
+                              if (key) {
+                                setCurrentColorFormat(key as ColorFormat);
+                              }
+                            }}
+                          >
+                            <Select.Trigger className="h-full min-w-22 rounded-none border-none bg-transparent px-3">
+                              <Select.Value />
+                              <Select.Indicator />
+                            </Select.Trigger>
+                            <Select.Popover>
+                              <ListBox>
+                                <ListBox.Item id="hex" textValue="HEX">
+                                  HEX
+                                </ListBox.Item>
+                                <ListBox.Item id="hsl" textValue="HSL">
+                                  HSL
+                                </ListBox.Item>
+                                <ListBox.Item id="rgb" textValue="RGB">
+                                  RGB
+                                </ListBox.Item>
+                                <ListBox.Item id="hsb" textValue="HSB">
+                                  HSB
+                                </ListBox.Item>
+                                <ListBox.Item id="oklch" textValue="OKLCH">
+                                  OKLCH
+                                </ListBox.Item>
+                              </ListBox>
+                            </Select.Popover>
+                          </Select>
+                        </InputGroup.Suffix>
+                      </InputGroup>
+                    </TextField>
+                  ) : null}
+                </>
+              )}
+            </Popover.Dialog>
+          </Popover.Content>
+        </Popover>
+      )}
+    </AriaColorPicker>
+  );
+}
diff --git a/apps/docs/src/components/color-picker/components/color-area.tsx b/apps/docs/src/components/color-picker/components/color-area.tsx
new file mode 100644
index 0000000..aa032b0
--- /dev/null
+++ b/apps/docs/src/components/color-picker/components/color-area.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import type {ColorAreaProps} from "../types";
+
+import {ColorArea as AriaColorArea, ColorThumb} from "react-aria-components";
+import {tv} from "tailwind-variants";
+
+import {composeTailwindRenderProps} from "@/utils/compose-tw-render";
+import {focusRing} from "@/utils/focus";
+
+const colorAreaStyles = tv({
+  base: "size-[232px] shrink-0 rounded-2xl border border-border forced-colors:bg-[GrayText]",
+});
+
+const colorThumbStyles = tv({
+  base: "size-6 rounded-full border-2 border-white shadow-lg forced-colors:bg-[Canvas]!",
+  extend: focusRing,
+});
+
+export function ColorArea({className, colorSpace = "hsb", xChannel, yChannel}: ColorAreaProps) {
+  return (
+    <AriaColorArea
+      className={composeTailwindRenderProps(className, colorAreaStyles())}
+      colorSpace={colorSpace}
+      xChannel={xChannel}
+      yChannel={yChannel}
+    >
+      <ColorThumb
+        className={colorThumbStyles}
+        style={({color}) => ({
+          background: color.toString("css"),
+        })}
+      />
+    </AriaColorArea>
+  );
+}
diff --git a/apps/docs/src/components/color-picker/components/color-slider.tsx b/apps/docs/src/components/color-picker/components/color-slider.tsx
new file mode 100644
index 0000000..4037eed
--- /dev/null
+++ b/apps/docs/src/components/color-picker/components/color-slider.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import type {ColorSliderProps} from "../types";
+
+import {ColorSlider as AriaColorSlider, ColorThumb, SliderTrack} from "react-aria-components";
+import {tv} from "tailwind-variants";
+
+import {cn} from "@/utils/cn";
+import {focusRing} from "@/utils/focus";
+
+const colorSliderTrackStyles = tv({
+  base: "h-8 w-full rounded-full forced-colors:bg-[GrayText]",
+  variants: {
+    orientation: {
+      horizontal: "h-8 w-full",
+      vertical: "ml-2 h-full w-8",
+    },
+  },
+});
+
+const colorThumbStyles = tv({
+  base: "size-4 cursor-grab rounded-full border-[1.5px] border-white shadow-lg data-[dragging=true]:cursor-grabbing",
+  extend: focusRing,
+});
+
+export function ColorSlider({
+  className,
+  orientation = "horizontal",
+  thumbBackground,
+  trackBackground,
+  ...props
+}: ColorSliderProps) {
+  return (
+    <AriaColorSlider
+      className={cn("group flex w-full flex-col gap-1", className)}
+      orientation={orientation}
+      {...props}
+    >
+      <SliderTrack
+        className={colorSliderTrackStyles({orientation})}
+        style={({defaultStyle}) => ({
+          background: trackBackground || `${defaultStyle.background}`,
+        })}
+      >
+        <ColorThumb
+          className={cn(colorThumbStyles(), orientation === "horizontal" ? "top-1/2" : "left-1/2")}
+          style={({color}) => ({
+            background: thumbBackground || color.toString("css"),
+          })}
+        />
+      </SliderTrack>
+    </AriaColorSlider>
+  );
+}
diff --git a/apps/docs/src/components/color-picker/components/color-swatches-carousel.tsx b/apps/docs/src/components/color-picker/components/color-swatches-carousel.tsx
new file mode 100644
index 0000000..0e0cdcf
--- /dev/null
+++ b/apps/docs/src/components/color-picker/components/color-swatches-carousel.tsx
@@ -0,0 +1,98 @@
+"use client";
+
+import type {ColorSwatchesCarouselProps} from "../types";
+
+import {ChevronLeft, ChevronRight} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+import React, {useState} from "react";
+import {
+  ColorSwatch as AriaColorSwatch,
+  ColorSwatchPicker,
+  ColorSwatchPickerItem,
+} from "react-aria-components";
+
+import {SWATCHES_PER_PAGE} from "../constants";
+import {chunkArray} from "../utils";
+
+export function ColorSwatchesCarousel({initialColorHex, swatches}: ColorSwatchesCarouselProps) {
+  // Chunk swatches into pages
+  const swatchPages = React.useMemo(() => chunkArray(swatches, SWATCHES_PER_PAGE), [swatches]);
+  const totalPages = swatchPages.length;
+
+  // Calculate initial swatch page based on current color
+  const [swatchPage, setSwatchPage] = useState(() => {
+    if (!initialColorHex) return 0;
+    const swatchIndex = swatches.findIndex(
+      (s) => s.toLowerCase() === initialColorHex.toLowerCase(),
+    );
+
+    return swatchIndex !== -1 ? Math.floor(swatchIndex / SWATCHES_PER_PAGE) : 0;
+  });
+
+  const navigateSwatches = (direction: "left" | "right") => {
+    setSwatchPage((prev) => {
+      if (direction === "left") {
+        return Math.max(0, prev - 1);
+      }
+
+      return Math.min(totalPages - 1, prev + 1);
+    });
+  };
+
+  const isFirstPage = swatchPage === 0;
+  const isLastPage = swatchPage === totalPages - 1;
+
+  if (totalPages === 0) return null;
+
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        isIconOnly
+        className="size-5 min-w-5 shrink-0 rounded-full"
+        isDisabled={isFirstPage}
+        size="sm"
+        variant="ghost"
+        onPress={() => navigateSwatches("left")}
+      >
+        <ChevronLeft className="size-4" />
+      </Button>
+      <div className="relative flex-1 overflow-hidden">
+        <div
+          className="flex transition-transform duration-300 ease-out"
+          style={{
+            transform: `translateX(-${swatchPage * 100}%)`,
+          }}
+        >
+          {swatchPages.map((pageSwatches, pageIndex) => (
+            <div key={pageIndex} className="flex h-[22px] w-full shrink-0 justify-center">
+              <ColorSwatchPicker className="flex items-center justify-start gap-1.5">
+                {pageSwatches.map((swatch) => (
+                  <ColorSwatchPickerItem
+                    key={swatch}
+                    className="size-4 rounded-full transition-all data-selected:ring-1 data-selected:ring-foreground data-selected:ring-offset-1"
+                    color={swatch}
+                  >
+                    <AriaColorSwatch
+                      className="size-full cursor-pointer rounded-full"
+                      style={{background: swatch}}
+                    />
+                  </ColorSwatchPickerItem>
+                ))}
+              </ColorSwatchPicker>
+            </div>
+          ))}
+        </div>
+      </div>
+      <Button
+        isIconOnly
+        className="size-5 min-w-5 shrink-0 rounded-full"
+        isDisabled={isLastPage}
+        size="sm"
+        variant="ghost"
+        onPress={() => navigateSwatches("right")}
+      >
+        <ChevronRight className="size-4" />
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/color-picker/components/index.ts b/apps/docs/src/components/color-picker/components/index.ts
new file mode 100644
index 0000000..d5aedfe
--- /dev/null
+++ b/apps/docs/src/components/color-picker/components/index.ts
@@ -0,0 +1,3 @@
+export {ColorArea} from "./color-area";
+export {ColorSlider} from "./color-slider";
+export {ColorSwatchesCarousel} from "./color-swatches-carousel";
diff --git a/apps/docs/src/components/color-picker/constants.ts b/apps/docs/src/components/color-picker/constants.ts
new file mode 100644
index 0000000..5443f52
--- /dev/null
+++ b/apps/docs/src/components/color-picker/constants.ts
@@ -0,0 +1,32 @@
+/* -------------------------------------------------------------------------------------------------
+ * Default Values
+ * -----------------------------------------------------------------------------------------------*/
+
+export const DEFAULT_COLOR = "#006FEE";
+export const DEFAULT_COLOR_OKLCH = "oklch(0.6199 0.194 253.67)";
+export const DEFAULT_COLOR_HSL = "hsl(253.67, 100%, 61.99%)";
+
+export const SWATCHES_PER_PAGE = 8;
+
+/* -------------------------------------------------------------------------------------------------
+ * Default Color Swatches
+ * -----------------------------------------------------------------------------------------------*/
+
+export const defaultSwatches = [
+  "hsla(338, 77%, 78%, 1)", // Pink
+  "hsla(309, 23%, 55%, 1)", // Muted purple
+  "hsla(355, 85%, 66%, 1)", // Coral/red
+  "hsla(16, 100%, 67%, 1)", // Orange
+  "hsla(47, 92%, 66%, 1)", // Yellow
+  "hsla(152, 80%, 56%, 1)", // Green
+  "hsla(197, 59%, 64%, 1)", // Blue
+  "hsla(220, 13%, 18%, 1)", // Dark slate (backgrounds)
+  "hsla(220, 70%, 50%, 1)", // Royal blue
+  "hsla(210, 100%, 56%, 1)", // Bright blue
+  "hsla(180, 100%, 25%, 1)", // Teal
+  "hsla(170, 50%, 65%, 1)", // Seafoam
+  "hsla(150, 60%, 75%, 1)", // Mint green
+  "hsla(280, 60%, 60%, 1)", // Violet
+  "hsla(270, 50%, 70%, 1)", // Lavender
+  "hsla(350, 100%, 88%, 1)", // Blush
+];
diff --git a/apps/docs/src/components/color-picker/index.ts b/apps/docs/src/components/color-picker/index.ts
new file mode 100644
index 0000000..4473937
--- /dev/null
+++ b/apps/docs/src/components/color-picker/index.ts
@@ -0,0 +1,31 @@
+// Main component
+export {default as ColorPicker, default} from "./color-picker";
+
+// Sub-components
+export {ColorArea, ColorSlider} from "./components";
+
+// Types
+export type {
+  Color,
+  ColorAreaProps,
+  ColorFormat,
+  ColorPickerProps,
+  ColorSliderProps,
+  ColorSpace,
+} from "./types";
+
+// Utils (for external use if needed)
+export {
+  detectColorFormat,
+  formatColor,
+  normalizeColorSyntax,
+  parseSafeDefaultValue,
+  safeParseColor,
+  validateColorInput,
+} from "./utils";
+
+// Constants (for external use if needed)
+export {DEFAULT_COLOR, SWATCHES_PER_PAGE, defaultSwatches} from "./constants";
+
+// Re-export parseColor from react-aria for convenience
+export {parseColor} from "react-aria-components";
diff --git a/apps/docs/src/components/color-picker/types.ts b/apps/docs/src/components/color-picker/types.ts
new file mode 100644
index 0000000..5802a4a
--- /dev/null
+++ b/apps/docs/src/components/color-picker/types.ts
@@ -0,0 +1,64 @@
+import type {
+  ColorPickerProps as AriaColorPickerProps,
+  ColorSliderProps as AriaColorSliderProps,
+  Color,
+  ColorSpace,
+} from "react-aria-components";
+
+/* -------------------------------------------------------------------------------------------------
+ * Color Format Types
+ * -----------------------------------------------------------------------------------------------*/
+
+export type ColorFormat = "hex" | "hsl" | "rgb" | "hsb" | "oklch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Component Props
+ * -----------------------------------------------------------------------------------------------*/
+
+export interface ColorAreaProps {
+  colorSpace?: ColorSpace;
+  xChannel?: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  yChannel?: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  className?: string;
+}
+
+export interface ColorSliderProps extends Omit<AriaColorSliderProps, "children"> {
+  trackBackground?: string;
+  thumbBackground?: string;
+}
+
+export interface ColorSwatchesCarouselProps {
+  /** Array of color swatches to display */
+  swatches: string[];
+  /** Initial color hex to determine starting page */
+  initialColorHex?: string;
+}
+
+export interface ColorPickerProps extends Omit<AriaColorPickerProps, "children" | "onChange"> {
+  /** Label for the trigger button */
+  label?: string;
+  /** Custom children for the popover content */
+  children?: React.ReactNode;
+  /** Show alpha slider */
+  showAlpha?: boolean;
+  /** Show hex/color field */
+  showColorField?: boolean;
+  /** Show color swatches */
+  showSwatches?: boolean;
+  /** Custom swatches array */
+  swatches?: string[];
+  /** Show shuffle/random button */
+  showShuffle?: boolean;
+  /** Custom trigger element */
+  trigger?: React.ReactNode;
+  /** Class name for popover content */
+  popoverClassName?: string;
+  /** Onchange callback */
+  onChange?: (color: Color) => void;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Re-export Color type for convenience
+ * -----------------------------------------------------------------------------------------------*/
+
+export type {Color, ColorSpace};
diff --git a/apps/docs/src/components/color-picker/utils/color-format.ts b/apps/docs/src/components/color-picker/utils/color-format.ts
new file mode 100644
index 0000000..82de6d3
--- /dev/null
+++ b/apps/docs/src/components/color-picker/utils/color-format.ts
@@ -0,0 +1,233 @@
+import type {ColorFormat} from "../types";
+import type {Color} from "react-aria-components";
+
+import {converter, formatCss, formatHsl, mapper, parse, parseOklch, round} from "culori";
+import {parseColor} from "react-aria-components";
+
+import {DEFAULT_COLOR_HSL} from "../constants";
+
+/* -------------------------------------------------------------------------------------------------
+ * Normalize Color Syntax
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Normalizes modern CSS color syntax (space-separated) to legacy syntax (comma-separated)
+ * that parseColor from react-aria expects.
+ *
+ * @example
+ * normalizeColorSyntax("hsl(220 70% 50%)") // → "hsl(220, 70%, 50%)"
+ * normalizeColorSyntax("hsl(220 70% 50% / 0.5)") // → "hsla(220, 70%, 50%, 0.5)"
+ * normalizeColorSyntax("rgb(255 128 0)") // → "rgb(255, 128, 0)"
+ * normalizeColorSyntax("rgb(255 128 0 / 0.5)") // → "rgba(255, 128, 0, 0.5)"
+ */
+export function normalizeColorSyntax(color: string): string {
+  const trimmed = color.trim();
+
+  // Match hsl/hsla with space-separated values
+  const hslMatch = trimmed.match(
+    /^(hsla?)\s*\(\s*([^\s,]+)\s+([^\s,]+)\s+([^\s,/]+)(?:\s*\/\s*([^\s)]+))?\s*\)$/i,
+  );
+
+  if (hslMatch) {
+    const [, func, h, s, l, a] = hslMatch;
+
+    if (a !== undefined) {
+      return `hsla(${h}, ${s}, ${l}, ${a})`;
+    }
+
+    return `${func}(${h}, ${s}, ${l})`;
+  }
+
+  // Match rgb/rgba with space-separated values
+  const rgbMatch = trimmed.match(
+    /^(rgba?)\s*\(\s*([^\s,]+)\s+([^\s,]+)\s+([^\s,/]+)(?:\s*\/\s*([^\s)]+))?\s*\)$/i,
+  );
+
+  if (rgbMatch) {
+    const [, func, r, g, b, a] = rgbMatch;
+
+    if (a !== undefined) {
+      return `rgba(${r}, ${g}, ${b}, ${a})`;
+    }
+
+    return `${func}(${r}, ${g}, ${b})`;
+  }
+
+  // Match hsb/hsba with space-separated values
+  const hsbMatch = trimmed.match(
+    /^(hsba?)\s*\(\s*([^\s,]+)\s+([^\s,]+)\s+([^\s,/]+)(?:\s*\/\s*([^\s)]+))?\s*\)$/i,
+  );
+
+  if (hsbMatch) {
+    const [, func, h, s, b, a] = hsbMatch;
+
+    if (a !== undefined) {
+      return `hsba(${h}, ${s}, ${b}, ${a})`;
+    }
+
+    return `${func}(${h}, ${s}, ${b})`;
+  }
+
+  return trimmed;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Detect Color Format
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Detects the color format from an input string.
+ * Returns null if the format cannot be determined.
+ */
+export function detectColorFormat(value: string): ColorFormat | null {
+  const trimmed = value.trim().toLowerCase();
+
+  if (trimmed.startsWith("oklch(")) return "oklch";
+  if (trimmed.startsWith("hsl(") || trimmed.startsWith("hsla(")) return "hsl";
+  if (trimmed.startsWith("rgb(") || trimmed.startsWith("rgba(")) return "rgb";
+  if (trimmed.startsWith("hsb(") || trimmed.startsWith("hsba(")) return "hsb";
+  // Detect hex format (with or without #)
+  if (/^#?[0-9a-f]{3,8}$/i.test(trimmed)) return "hex";
+
+  return null;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Format Color
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Formats a Color object to a string in the specified format.
+ * Handles OKLCH conversion using culori since react-aria doesn't support it natively.
+ */
+export function formatColor(color: Color, format: ColorFormat): string {
+  if (format !== "oklch") {
+    return color.toString(format);
+  }
+
+  const oklch = converter("oklch");
+  const roundTo4 = round(4);
+  const oklchColor = oklch(color.toString("css"));
+
+  if (!oklchColor) {
+    return color.toString("hex");
+  }
+
+  // Round each channel value
+  const roundedColor = mapper(roundTo4, "oklch")(oklchColor);
+
+  return formatCss(roundedColor);
+}
+
+export function getHueFromColor(color: Color): number {
+  const oklch = converter("oklch")(color.toString("hsl"));
+
+  if (!oklch || oklch.h === undefined) {
+    return 0;
+  }
+
+  return oklch.h;
+}
+
+export function formatFromOklchToColor(oklch: string): Color {
+  const oklchColor = parseOklch(oklch);
+
+  if (!oklchColor) {
+    return parseColor(DEFAULT_COLOR_HSL);
+  }
+
+  const hsl = formatHsl(oklchColor);
+
+  return parseColor(hsl);
+}
+
+export const getValuesFromOklch = (
+  hsl: string,
+): {lightness: number; chroma: number; hue: number} => {
+  const oklch = converter("oklch");
+  const oklchColor = oklch(hsl);
+
+  return {chroma: oklchColor?.c ?? 0, hue: oklchColor?.h ?? 0, lightness: oklchColor?.l ?? 0};
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Validate Color Input
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Validates if a string is a valid color for the given format.
+ * Returns the parsed Color if valid, null otherwise.
+ */
+export function validateColorInput(input: string, format: ColorFormat): Color | null {
+  const trimmed = input.trim();
+
+  if (!trimmed) return null;
+
+  try {
+    // Use culori to parse and validate the color
+    const parsed = parse(trimmed);
+
+    if (!parsed) return null;
+
+    // For format-specific validation
+    switch (format) {
+      case "hex":
+        // Accept hex colors (with or without #)
+        if (/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(trimmed)) {
+          const hexValue = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+
+          return parseColor(hexValue);
+        }
+
+        return null;
+
+      case "hsl":
+        // Accept hsl/hsla format (both comma and space-separated)
+        if (/^hsla?\s*\(/i.test(trimmed)) {
+          const normalized = normalizeColorSyntax(trimmed);
+
+          return parseColor(normalized);
+        }
+
+        return null;
+
+      case "rgb":
+        // Accept rgb/rgba format (both comma and space-separated)
+        if (/^rgba?\s*\(/i.test(trimmed)) {
+          const normalized = normalizeColorSyntax(trimmed);
+
+          return parseColor(normalized);
+        }
+
+        return null;
+
+      case "hsb":
+        // Accept hsb/hsba format (both comma and space-separated)
+        if (/^hsba?\s*\(/i.test(trimmed)) {
+          const normalized = normalizeColorSyntax(trimmed);
+
+          return parseColor(normalized);
+        }
+
+        return null;
+
+      case "oklch":
+        // Accept oklch format
+        if (/^oklch\s*\(/i.test(trimmed)) {
+          // Convert oklch to hsl for react-aria compatibility
+          const hsl = formatHsl(trimmed);
+
+          if (hsl) {
+            return parseColor(hsl);
+          }
+        }
+
+        return null;
+
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/docs/src/components/color-picker/utils/color-parser.ts b/apps/docs/src/components/color-picker/utils/color-parser.ts
new file mode 100644
index 0000000..4356fa7
--- /dev/null
+++ b/apps/docs/src/components/color-picker/utils/color-parser.ts
@@ -0,0 +1,61 @@
+import type {Color} from "react-aria-components";
+
+import {formatHsl} from "culori";
+import {parseColor} from "react-aria-components";
+
+import {DEFAULT_COLOR} from "../constants";
+
+/* -------------------------------------------------------------------------------------------------
+ * Safe Color Parser
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Safely parses a color string or Color object into a Color object.
+ * Handles OKLCH conversion since react-aria doesn't support it natively.
+ * Falls back to DEFAULT_COLOR if parsing fails.
+ */
+export function safeParseColor(color: string | Color): Color {
+  try {
+    if (typeof color === "string") {
+      if (color.startsWith("oklch")) {
+        const hsl = formatHsl(color);
+
+        if (!hsl) {
+          return parseColor(DEFAULT_COLOR);
+        }
+
+        return parseColor(hsl);
+      }
+
+      return parseColor(color);
+    }
+
+    return color;
+  } catch {
+    return parseColor(DEFAULT_COLOR);
+  }
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Safe Default Value Parser
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Safely parses a default value for the color picker.
+ * Handles unsupported color formats by falling back to DEFAULT_COLOR.
+ */
+export function parseSafeDefaultValue(defaultValue: string | Color | undefined): Color {
+  if (!defaultValue) return parseColor(DEFAULT_COLOR);
+
+  // If it's already a Color object, return as-is
+  if (typeof defaultValue !== "string") return defaultValue;
+
+  // Check for unsupported color formats (oklab, lab, lch, etc.)
+  const unsupportedFormats = ["oklab", "lab(", "lch(", "color("];
+
+  if (unsupportedFormats.some((format) => defaultValue.toLowerCase().startsWith(format))) {
+    return parseColor(DEFAULT_COLOR);
+  }
+
+  return safeParseColor(defaultValue);
+}
diff --git a/apps/docs/src/components/color-picker/utils/helpers.ts b/apps/docs/src/components/color-picker/utils/helpers.ts
new file mode 100644
index 0000000..974b7c7
--- /dev/null
+++ b/apps/docs/src/components/color-picker/utils/helpers.ts
@@ -0,0 +1,13 @@
+/**
+ * Chunks an array into smaller arrays of a specified size.
+ * Useful for pagination of swatches.
+ */
+export function chunkArray<T>(array: T[], chunkSize: number): T[][] {
+  const chunks: T[][] = [];
+
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize));
+  }
+
+  return chunks;
+}
diff --git a/apps/docs/src/components/color-picker/utils/index.ts b/apps/docs/src/components/color-picker/utils/index.ts
new file mode 100644
index 0000000..b92f952
--- /dev/null
+++ b/apps/docs/src/components/color-picker/utils/index.ts
@@ -0,0 +1,8 @@
+export {
+  detectColorFormat,
+  formatColor,
+  normalizeColorSyntax,
+  validateColorInput,
+} from "./color-format";
+export {parseSafeDefaultValue, safeParseColor} from "./color-parser";
+export {chunkArray} from "./helpers";
diff --git a/apps/docs/src/components/color-section.tsx b/apps/docs/src/components/color-section.tsx
new file mode 100644
index 0000000..83dbb44
--- /dev/null
+++ b/apps/docs/src/components/color-section.tsx
@@ -0,0 +1,536 @@
+"use client";
+
+import {Chip, Tooltip, toast} from "@heroui/react";
+import {converter, parse} from "culori";
+import * as React from "react";
+
+import {Iconify} from "@/components/iconify";
+import {cn} from "@/utils/cn";
+
+const contrastStyle = (bgVar: string): React.CSSProperties => ({
+  WebkitBackgroundClip: "text",
+  backgroundClip: "text",
+  backgroundColor: `var(${bgVar})`,
+  color: "transparent",
+  filter: "invert(1) grayscale(1) contrast(100)",
+});
+
+const getTokenName = (content: string | undefined, fallback: string) => {
+  if (!content) return fallback;
+
+  return content.split(":")[0]?.trim() || fallback;
+};
+
+const toOklch = converter("oklch");
+
+const formatNumber = (value: number | undefined) => {
+  if (typeof value !== "number") return "0";
+
+  return Number(value.toFixed(4)).toString();
+};
+
+const toOklchCss = (value: string) => {
+  const parsed = parse(value);
+
+  if (!parsed) return value;
+
+  const oklch = toOklch(parsed);
+
+  if (!oklch) return value;
+
+  if (typeof oklch.alpha === "number" && oklch.alpha < 1) {
+    return `oklch(${formatNumber(oklch.l)} ${formatNumber(oklch.c)} ${formatNumber(oklch.h)} / ${formatNumber(oklch.alpha)})`;
+  }
+
+  return `oklch(${formatNumber(oklch.l)} ${formatNumber(oklch.c)} ${formatNumber(oklch.h)})`;
+};
+
+const copyColorValue = async (
+  event: React.MouseEvent<HTMLElement>,
+  fallback: string | undefined,
+) => {
+  const computedValue = getComputedStyle(event.currentTarget).backgroundColor || fallback;
+  const value = computedValue ? toOklchCss(computedValue) : fallback || "";
+
+  if (!value) return;
+
+  await navigator.clipboard.writeText(value);
+  toast.success("Copied color value", {
+    description: value,
+  });
+};
+
+function ColorTooltip({
+  children,
+  className,
+  content,
+}: {
+  children: React.ReactNode;
+  content?: string;
+  className?: string;
+}) {
+  if (!content) {
+    return <div className={className}>{children}</div>;
+  }
+
+  return (
+    <Tooltip delay={0}>
+      <Tooltip.Trigger className={className}>{children}</Tooltip.Trigger>
+      <Tooltip.Content className="max-w-xs">
+        <pre className="font-mono text-xs leading-relaxed whitespace-pre-wrap">{content}</pre>
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+
+interface SideBySideProps {
+  name: string;
+  baseVariable: string;
+  baseTooltip?: string;
+  hoverVariable: string;
+  hoverCssValue?: string;
+  hoverTooltip?: string;
+  foregroundVariable: string;
+  foregroundTooltip?: string;
+  soft?: {
+    baseVariable: string;
+    baseCssValue?: string;
+    baseTooltip?: string;
+    hoverVariable: string;
+    hoverCssValue?: string;
+    hoverTooltip?: string;
+    foregroundVariable: string;
+    foregroundCssValue?: string;
+    foregroundTooltip?: string;
+  };
+}
+
+interface StackedColor {
+  label: string;
+  variable: string;
+  cssValue?: string;
+  border?: boolean;
+  tooltip?: string;
+}
+
+function ThemeChip({theme}: {theme: "Light" | "Dark"}) {
+  return (
+    <div>
+      <Chip size="sm">
+        <Iconify className="size-3.5" icon="gear" />
+        <Chip.Label>{theme}</Chip.Label>
+      </Chip>
+    </div>
+  );
+}
+
+function ColorHeader({
+  bgVariable,
+  name,
+  theme,
+  tooltip,
+}: {
+  name: string;
+  theme: "Light" | "Dark";
+  bgVariable: string;
+  tooltip?: string;
+}) {
+  const token = getTokenName(tooltip, bgVariable);
+
+  return (
+    <ColorTooltip content={tooltip}>
+      <div
+        className="flex cursor-pointer items-center justify-between rounded-xl px-4 py-3"
+        style={{backgroundColor: `var(${bgVariable})`}}
+        onClick={(event) => copyColorValue(event, bgVariable)}
+      >
+        <div className="flex flex-col">
+          <span className="text-lg font-medium tracking-tight" style={contrastStyle(bgVariable)}>
+            {name}
+          </span>
+          <span
+            className="font-mono text-[10px] leading-tight opacity-60 sm:hidden"
+            style={contrastStyle(bgVariable)}
+          >
+            {token}
+          </span>
+        </div>
+        <span className="text-xs font-medium" style={contrastStyle(bgVariable)}>
+          {theme}
+        </span>
+      </div>
+    </ColorTooltip>
+  );
+}
+
+function ColorBlock({
+  bgVariable,
+  cssValue,
+  hasBorder,
+  label,
+  tooltip,
+}: {
+  label: string;
+  bgVariable: string;
+  cssValue?: string;
+  hasBorder?: boolean;
+  tooltip?: string;
+}) {
+  const bgValue = cssValue || `var(${bgVariable})`;
+  const token = getTokenName(tooltip, bgVariable);
+
+  return (
+    <ColorTooltip className="block w-full" content={tooltip}>
+      <div
+        style={{backgroundColor: bgValue}}
+        className={cn(
+          "flex w-full cursor-pointer flex-col justify-center rounded-xl px-4 py-2.5",
+          hasBorder && "border border-black/12 dark:border-white/12",
+        )}
+        onClick={(event) => copyColorValue(event, cssValue || bgVariable)}
+      >
+        <span className="text-sm font-medium tracking-tight" style={contrastStyle(bgVariable)}>
+          {label}
+        </span>
+        <span
+          className="font-mono text-[10px] leading-tight opacity-60 sm:hidden"
+          style={contrastStyle(bgVariable)}
+        >
+          {token}
+        </span>
+      </div>
+    </ColorTooltip>
+  );
+}
+
+function ThemeColumn({
+  baseTooltip,
+  baseVariable,
+  foregroundTooltip,
+  foregroundVariable,
+  hoverCssValue,
+  hoverTooltip,
+  hoverVariable,
+  name,
+  soft,
+  theme,
+}: {
+  theme: "Light" | "Dark";
+  name: string;
+  baseVariable: string;
+  baseTooltip?: string;
+  hoverVariable: string;
+  hoverCssValue?: string;
+  hoverTooltip?: string;
+  foregroundVariable: string;
+  foregroundTooltip?: string;
+  soft?: SideBySideProps["soft"];
+}) {
+  return (
+    <div className="flex flex-1 flex-col gap-2" data-theme={theme.toLowerCase()}>
+      <ColorHeader bgVariable={baseVariable} name={name} theme={theme} tooltip={baseTooltip} />
+      <div className={cn("flex gap-2", soft ? "flex-col sm:flex-row" : "flex-col")}>
+        <div
+          className="flex flex-1 flex-col gap-1.5 rounded-xl p-3"
+          style={{backgroundColor: `var(${baseVariable})`}}
+        >
+          <span
+            className="text-base font-medium tracking-tight"
+            style={contrastStyle(baseVariable)}
+          >
+            {name}
+          </span>
+          <ColorBlock
+            bgVariable={hoverVariable}
+            cssValue={hoverCssValue}
+            label="Hover"
+            tooltip={hoverTooltip}
+          />
+          <ColorBlock
+            bgVariable={foregroundVariable}
+            label="Foreground"
+            tooltip={foregroundTooltip}
+          />
+        </div>
+        {!!soft && (
+          <div className="relative flex flex-1 flex-col gap-1.5 overflow-hidden rounded-xl p-3">
+            <div className="absolute inset-0" style={{backgroundColor: "var(--surface)"}} />
+            <div
+              className="absolute inset-0"
+              style={{backgroundColor: soft.baseCssValue || `var(${soft.baseVariable})`}}
+            />
+            <span className="relative text-base font-medium tracking-tight text-foreground">
+              {name} Soft
+            </span>
+            <div className="relative">
+              {(() => {
+                const token = getTokenName(soft.hoverTooltip, soft.hoverVariable);
+
+                return (
+                  <ColorTooltip className="block w-full" content={soft.hoverTooltip}>
+                    <div
+                      className="flex w-full cursor-pointer flex-col justify-center rounded-xl border border-black/12 px-4 py-2.5 dark:border-white/12"
+                      style={{backgroundColor: soft.hoverCssValue || `var(${soft.hoverVariable})`}}
+                      onClick={(event) =>
+                        copyColorValue(event, soft.hoverCssValue || soft.hoverVariable)
+                      }
+                    >
+                      <span className="text-sm font-medium tracking-tight text-foreground">
+                        Hover
+                      </span>
+                      <span className="font-mono text-[10px] leading-tight text-foreground opacity-60 sm:hidden">
+                        {token}
+                      </span>
+                    </div>
+                  </ColorTooltip>
+                );
+              })()}
+            </div>
+            <div className="relative">
+              <ColorBlock
+                bgVariable={soft.foregroundVariable}
+                cssValue={soft.foregroundCssValue}
+                label="Foreground"
+                tooltip={soft.foregroundTooltip}
+              />
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export function ColorSectionSideBySide({
+  baseTooltip,
+  baseVariable,
+  foregroundTooltip,
+  foregroundVariable,
+  hoverCssValue,
+  hoverTooltip,
+  hoverVariable,
+  name,
+  soft,
+}: SideBySideProps) {
+  return (
+    <div className="not-prose flex flex-col gap-4 sm:flex-row">
+      <ThemeColumn
+        baseTooltip={baseTooltip}
+        baseVariable={baseVariable}
+        foregroundTooltip={foregroundTooltip}
+        foregroundVariable={foregroundVariable}
+        hoverCssValue={hoverCssValue}
+        hoverTooltip={hoverTooltip}
+        hoverVariable={hoverVariable}
+        name={name}
+        soft={soft}
+        theme="Light"
+      />
+      <ThemeColumn
+        baseTooltip={baseTooltip}
+        baseVariable={baseVariable}
+        foregroundTooltip={foregroundTooltip}
+        foregroundVariable={foregroundVariable}
+        hoverCssValue={hoverCssValue}
+        hoverTooltip={hoverTooltip}
+        hoverVariable={hoverVariable}
+        name={name}
+        soft={soft}
+        theme="Dark"
+      />
+    </div>
+  );
+}
+
+function StackedSwatch({
+  border,
+  cssValue,
+  label,
+  tooltip,
+  variable,
+}: {
+  label: string;
+  variable: string;
+  cssValue?: string;
+  border?: boolean;
+  tooltip?: string;
+}) {
+  const bgValue = cssValue || `var(${variable})`;
+  const token = getTokenName(tooltip, variable);
+
+  return (
+    <ColorTooltip className="min-w-0 basis-full sm:flex-1 sm:basis-0" content={tooltip}>
+      <div
+        style={{backgroundColor: bgValue}}
+        className={cn(
+          "flex min-h-14 w-full cursor-pointer flex-col justify-center rounded-xl px-4 py-2",
+          border && "border border-border",
+        )}
+        onClick={(event) => copyColorValue(event, cssValue || variable)}
+      >
+        <span className="text-sm font-medium tracking-tight" style={contrastStyle(variable)}>
+          {label}
+        </span>
+        <span
+          className="truncate font-mono text-[10px] leading-tight opacity-60 sm:hidden"
+          style={contrastStyle(variable)}
+        >
+          {token}
+        </span>
+      </div>
+    </ColorTooltip>
+  );
+}
+
+export function ColorSectionStacked({
+  darkColors,
+  lightColors,
+}: {
+  lightColors: StackedColor[];
+  darkColors: StackedColor[];
+}) {
+  return (
+    <div className="not-prose flex flex-col gap-2">
+      <div data-theme="light">
+        <div className="flex flex-col gap-2">
+          <ThemeChip theme="Light" />
+          <div className="flex flex-wrap gap-2 sm:flex-nowrap">
+            {lightColors.map((color) => (
+              <StackedSwatch
+                key={color.variable + color.label}
+                border={color.border}
+                cssValue={color.cssValue}
+                label={color.label}
+                tooltip={color.tooltip}
+                variable={color.variable}
+              />
+            ))}
+          </div>
+        </div>
+      </div>
+      <div data-theme="dark">
+        <div className="flex flex-col gap-2">
+          <ThemeChip theme="Dark" />
+          <div className="flex flex-wrap gap-2 sm:flex-nowrap">
+            {darkColors.map((color) => (
+              <StackedSwatch
+                key={color.variable + color.label}
+                border={color.border}
+                cssValue={color.cssValue}
+                label={color.label}
+                tooltip={color.tooltip}
+                variable={color.variable}
+              />
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function ColorSectionPrimitive({colors}: {colors: StackedColor[]}) {
+  return (
+    <div className="not-prose flex flex-wrap gap-2 sm:flex-nowrap">
+      {colors.map((color) => (
+        <StackedSwatch
+          key={color.variable + color.label}
+          border={color.border}
+          cssValue={color.cssValue}
+          label={color.label}
+          tooltip={color.tooltip}
+          variable={color.variable}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface FormFieldColors {
+  bg: string;
+  bgTooltip?: string;
+  bgHover: string;
+  bgHoverTooltip?: string;
+  bgFocusTooltip?: string;
+  placeholder: string;
+  placeholderTooltip?: string;
+  foreground: string;
+  foregroundTooltip?: string;
+}
+
+function FormFieldThemeBlock({colors, theme}: {colors: FormFieldColors; theme: "light" | "dark"}) {
+  return (
+    <div data-theme={theme}>
+      <div className="flex flex-col gap-2">
+        <ThemeChip theme={theme === "light" ? "Light" : "Dark"} />
+        <div className="flex flex-col gap-2 sm:flex-row">
+          <div
+            className="flex flex-1 flex-col gap-1.5 rounded-xl border border-black/12 p-3"
+            style={{backgroundColor: `var(${colors.bg})`}}
+          >
+            <ColorTooltip content={colors.bgTooltip}>
+              <span
+                className="cursor-default text-base font-medium tracking-tight"
+                style={contrastStyle(colors.bg)}
+              >
+                Bg
+              </span>
+            </ColorTooltip>
+            <ColorBlock
+              hasBorder
+              bgVariable={colors.bg}
+              cssValue={colors.bgHover}
+              label="Hover"
+              tooltip={colors.bgHoverTooltip}
+            />
+            <ColorBlock
+              hasBorder
+              bgVariable={colors.bg}
+              label="Focus"
+              tooltip={colors.bgFocusTooltip}
+            />
+          </div>
+          <div className="flex min-w-0 flex-row gap-2 sm:w-40 sm:flex-col">
+            <ColorTooltip className="min-w-0 flex-1" content={colors.placeholderTooltip}>
+              <div
+                className="flex h-full cursor-pointer items-center rounded-xl border border-border px-4 py-3"
+                style={{backgroundColor: `var(${colors.placeholder})`}}
+                onClick={(event) => copyColorValue(event, colors.placeholder)}
+              >
+                <span
+                  className="text-sm font-medium tracking-tight"
+                  style={contrastStyle(colors.placeholder)}
+                >
+                  Placeholder
+                </span>
+              </div>
+            </ColorTooltip>
+            <ColorTooltip className="min-w-0 flex-1" content={colors.foregroundTooltip}>
+              <div
+                className="flex h-full cursor-pointer items-center rounded-xl px-4 py-3"
+                style={{backgroundColor: `var(${colors.foreground})`}}
+                onClick={(event) => copyColorValue(event, colors.foreground)}
+              >
+                <span
+                  className="text-sm font-medium tracking-tight"
+                  style={contrastStyle(colors.foreground)}
+                >
+                  Foreground
+                </span>
+              </div>
+            </ColorTooltip>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function ColorSectionFormField({colors}: {colors: FormFieldColors}) {
+  return (
+    <div className="not-prose flex flex-col gap-2">
+      <FormFieldThemeBlock colors={colors} theme="light" />
+      <FormFieldThemeBlock colors={colors} theme="dark" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/color-swatch-picker.tsx b/apps/docs/src/components/color-swatch-picker.tsx
new file mode 100644
index 0000000..956b670
--- /dev/null
+++ b/apps/docs/src/components/color-swatch-picker.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import type {ColorSwatchPickerItemProps, ColorSwatchPickerProps} from "react-aria-components";
+
+import React from "react";
+import {
+  ColorSwatchPicker as AriaColorSwatchPicker,
+  ColorSwatchPickerItem as AriaColorSwatchPickerItem,
+  ColorSwatch,
+} from "react-aria-components";
+import {tv} from "tailwind-variants";
+
+import {composeTailwindRenderProps} from "@/utils/compose-tw-render";
+
+const itemStyles = tv({
+  base: "relative rounded-xs",
+});
+
+const focusIndicator = tv({
+  base: "absolute top-0 left-0 h-full w-full scale-[0.5] rounded-full border-2 border-black opacity-0 outline-2 -outline-offset-4 outline-white transition-all forced-color-adjust-none dark:border-white dark:outline-black",
+  variants: {
+    isSelected: {
+      true: "scale-100 opacity-100",
+    },
+  },
+});
+
+export function ColorSwatchPickerItem({
+  className,
+  outlineColor,
+  outlineOffsetColor,
+  ...props
+}: Omit<ColorSwatchPickerItemProps, "className"> & {
+  className?: string;
+  outlineColor?: string;
+  outlineOffsetColor?: string;
+}) {
+  return (
+    <AriaColorSwatchPickerItem {...props} className={itemStyles}>
+      {({isSelected}) => (
+        <>
+          <ColorSwatch className={className} />
+          <div
+            className={focusIndicator({isSelected})}
+            data-selected={isSelected}
+            style={{
+              borderColor: outlineColor,
+              outlineColor: outlineOffsetColor,
+            }}
+          />
+        </>
+      )}
+    </AriaColorSwatchPickerItem>
+  );
+}
+
+export function ColorSwatchPicker({
+  children,
+  ...props
+}: Omit<ColorSwatchPickerProps, "layout" | "className"> & {className?: string}) {
+  return (
+    <AriaColorSwatchPicker
+      {...props}
+      className={composeTailwindRenderProps(props.className, "flex gap-1")}
+    >
+      {children}
+    </AriaColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/components/color-swatch.tsx b/apps/docs/src/components/color-swatch.tsx
new file mode 100644
index 0000000..c3ddaeb
--- /dev/null
+++ b/apps/docs/src/components/color-swatch.tsx
@@ -0,0 +1,146 @@
+"use client";
+
+import type {LAB} from "color-convert";
+
+import colorConvert from "color-convert";
+import {useCopyButton} from "fumadocs-ui/utils/use-copy-button";
+import * as React from "react";
+
+import {Iconify} from "@/components/iconify";
+import {cn} from "@/utils/cn";
+
+interface ColorSwatchProps {
+  name: string;
+  variable: string;
+  value?: string;
+  className?: string;
+  foreground?: string;
+}
+
+const getLabValue = (value: string): LAB | null => {
+  const match = value.match(/-?\d*\.?\d+/g);
+
+  if (match && match.length >= 3) {
+    return [Number(match[0]), Number(match[1]), Number(match[2])];
+  }
+
+  return null;
+};
+
+export function ColorSwatch({className, foreground, name, value, variable}: ColorSwatchProps) {
+  const [hexValue, setHexValue] = React.useState<string>("");
+  const [checked, onClick] = useCopyButton(async () => {
+    // Copy the hex value to clipboard
+    if (hexValue) {
+      await navigator.clipboard.writeText(hexValue);
+    }
+  });
+
+  React.useEffect(() => {
+    // Recursively resolve CSS variable references
+    const resolveVariable = (varName: string, depth = 0): string => {
+      if (depth > 5) return ""; // Max recursion depth
+
+      const value = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+
+      if (!value) return "";
+
+      // Check if the value is another CSS variable reference
+      if (value.startsWith("var(")) {
+        // Extract the variable name from var(--variable-name)
+        const match = value.match(/var\((--[^)]+)\)/);
+
+        if (match && match[1]) {
+          return resolveVariable(match[1], depth + 1);
+        }
+      }
+
+      return value;
+    };
+
+    const computedValue = resolveVariable(variable);
+
+    // Convert to hex using the browser's native color conversion
+    if (computedValue) {
+      try {
+        if (computedValue.startsWith("lab")) {
+          const labValue = getLabValue(computedValue);
+
+          if (labValue) {
+            setHexValue(`#${colorConvert.lab.hex(labValue)}`);
+          } else {
+            throw new Error("Invalid lab value");
+          }
+        } else {
+          setHexValue(computedValue);
+        }
+      } catch (e) {
+        console.warn(`Failed to convert color for ${variable}:`, e);
+      }
+    }
+  }, [variable, value]);
+
+  return (
+    <div className={cn("flex flex-col items-center gap-2", className)}>
+      <button
+        className="group relative size-10 rounded-full shadow-surface transition-all hover:scale-105 hover:shadow-md focus:ring-2 focus:ring-accent focus:ring-offset-2 focus:outline-none"
+        type="button"
+        style={{
+          backgroundColor: `var(${variable})`,
+        }}
+        onClick={onClick}
+      >
+        <span className="sr-only">Copy {name} color</span>
+        <div className="absolute inset-0 flex items-center justify-center rounded-lg">
+          <Iconify
+            className="size-5 opacity-0 transition-all group-hover:opacity-100 data-[checked=true]:opacity-100"
+            data-checked={checked}
+            icon={checked ? "check" : "copy"}
+            style={
+              foreground
+                ? {
+                    color: `var(${foreground})`,
+                  }
+                : {
+                    filter:
+                      "contrast(200%) brightness(0)  invert(1) drop-shadow(0 1px 1px rgba(0,0,0,0.5))",
+                    mixBlendMode: "difference",
+                  }
+            }
+          />
+        </div>
+      </button>
+      <div className="text-center">
+        <div className="text-xs font-medium">{variable}</div>
+      </div>
+    </div>
+  );
+}
+
+interface ColorPaletteProps {
+  colors: Array<{
+    name: string;
+    variable: string;
+    value?: string;
+    foreground?: string;
+  }>;
+  className?: string;
+}
+
+export function ColorPalette({className, colors}: ColorPaletteProps) {
+  return (
+    <div className={cn("mb-6", className)}>
+      <div className="my-5 flex flex-wrap gap-4 sm:gap-6">
+        {colors.map((color) => (
+          <ColorSwatch
+            key={color.variable}
+            foreground={color.foreground}
+            name={color.name}
+            value={color.value}
+            variable={color.variable}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/component-item.tsx b/apps/docs/src/components/component-item.tsx
new file mode 100644
index 0000000..ef52907
--- /dev/null
+++ b/apps/docs/src/components/component-item.tsx
@@ -0,0 +1,128 @@
+"use client";
+
+import type {ComponentInfo} from "../components-registry";
+import type {StatusChipStatus} from "./status-chip";
+
+import {Link} from "@heroui/react";
+import LinkRoot from "fumadocs-core/link";
+import Image from "next/image";
+
+import {cn} from "@/utils/cn";
+import {CDN_URL} from "@/utils/constants";
+
+import StatusChip from "./status-chip";
+
+function ComponentImagePair({
+  alt,
+  darkSrc,
+  height = 594,
+  lightSrc,
+  width = 874,
+}: {
+  alt: string;
+  darkSrc: string;
+  height?: number;
+  lightSrc: string;
+  width?: number;
+}) {
+  return (
+    <>
+      <Image
+        alt={alt}
+        className="absolute inset-0 block h-full w-full object-cover dark:hidden"
+        height={height}
+        src={lightSrc}
+        width={width}
+      />
+      <Image
+        alt={alt}
+        className="absolute inset-0 hidden h-full w-full object-cover dark:block"
+        height={height}
+        src={darkSrc}
+        width={width}
+      />
+    </>
+  );
+}
+
+function ComponentTitleContent({status, title}: {status?: StatusChipStatus; title: string}) {
+  return (
+    <div className="flex items-center gap-2">
+      {title}
+      {status ? <StatusChip className="w-fit" status={status} /> : null}
+    </div>
+  );
+}
+
+function ConditionalLink({
+  children,
+  className,
+  href,
+  openInNewTab,
+}: {
+  children: React.ReactNode;
+  className?: string;
+  href: string;
+  openInNewTab: boolean;
+}) {
+  const linkProps = openInNewTab
+    ? {rel: "noopener noreferrer" as const, target: "_blank" as const}
+    : {};
+
+  if (openInNewTab) {
+    return (
+      <Link className={cn(className, "no-underline")} href={href} {...linkProps}>
+        {children}
+      </Link>
+    );
+  }
+
+  return (
+    <LinkRoot className={className} href={href}>
+      {children}
+    </LinkRoot>
+  );
+}
+
+interface ComponentItemProps extends React.ComponentProps<"div"> {
+  component: ComponentInfo;
+  className?: string;
+  status?: StatusChipStatus;
+  openInNewTab?: boolean;
+}
+
+export function ComponentItem({
+  className,
+  component,
+  openInNewTab = false,
+  status,
+}: ComponentItemProps) {
+  const {href, title} = component;
+  // to cater chinese component title: <English> <Chinese>
+  const imageName = title.toLowerCase().split(" ")[0];
+  const lightSrc = `${CDN_URL}/docs/related-components/light-${imageName}.png`;
+  const darkSrc = `${CDN_URL}/docs/related-components/dark-${imageName}.png`;
+
+  return (
+    <div className={cn("flex flex-col gap-[9px]", className)}>
+      {/* Title first on mobile, image first on desktop */}
+      <div className="order-1 sm:order-2">
+        {openInNewTab ? (
+          <Link className="no-underline" href={href} rel="noopener noreferrer" target="_blank">
+            <ComponentTitleContent status={status} title={title} />
+            <Link.Icon />
+          </Link>
+        ) : (
+          <ConditionalLink className="link no-underline" href={href} openInNewTab={openInNewTab}>
+            <ComponentTitleContent status={status} title={title} />
+          </ConditionalLink>
+        )}
+      </div>
+      <div className="relative order-2 h-[198px] overflow-hidden rounded-xl border border-separator sm:order-1">
+        <ConditionalLink className="h-full w-full" href={href} openInNewTab={openInNewTab}>
+          <ComponentImagePair alt={title} darkSrc={darkSrc} lightSrc={lightSrc} />
+        </ConditionalLink>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/component-links.tsx b/apps/docs/src/components/component-links.tsx
new file mode 100644
index 0000000..41805a4
--- /dev/null
+++ b/apps/docs/src/components/component-links.tsx
@@ -0,0 +1,115 @@
+"use client";
+
+import type {ComponentLinksType} from "@/utils/extract-links";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {
+  FigmaIcon,
+  GithubIcon,
+  RadixUIIcon,
+  ReactAriaIcon,
+  StorybookIcon,
+  TailwindIcon,
+} from "@/icons/dev";
+import {generateComponentLinks} from "@/utils/extract-links";
+import {docsButtonVariants} from "@/utils/variants";
+
+export interface ComponentLinksProps {
+  links?: ComponentLinksType;
+}
+
+const ButtonLink = ({
+  children,
+  href,
+  startContent,
+  ...props
+}: React.HTMLProps<HTMLAnchorElement> & {
+  startContent?: React.ReactNode;
+}) => {
+  return (
+    <a
+      className={docsButtonVariants()}
+      href={href}
+      rel="noopener noreferrer"
+      target="_blank"
+      {...props}
+    >
+      {startContent}
+      {children}
+    </a>
+  );
+};
+
+export const ComponentLinks = ({links}: ComponentLinksProps) => {
+  const dict = useDictionary().componentLinks;
+  const componentLinks = generateComponentLinks(links || null);
+
+  if (!componentLinks) {
+    return null;
+  }
+
+  return (
+    <div className="mb-4 flex flex-wrap gap-2">
+      {/* Only the node-id is needed */}
+      {componentLinks.figma ? (
+        <ButtonLink href={componentLinks.figma} startContent={<FigmaIcon className="text-lg" />}>
+          Figma
+        </ButtonLink>
+      ) : null}
+      {componentLinks.storybook ? (
+        <ButtonLink
+          href={`${componentLinks.storybook}--docs`}
+          startContent={<StorybookIcon className="text-lg text-[#ff4785]" />}
+        >
+          Storybook
+        </ButtonLink>
+      ) : null}
+      {componentLinks.rac ? (
+        <ButtonLink
+          href={componentLinks.rac}
+          startContent={<ReactAriaIcon className="text-lg text-[#6733FF]" />}
+        >
+          React Aria
+        </ButtonLink>
+      ) : null}
+      {componentLinks.radix ? (
+        <ButtonLink href={componentLinks.radix} startContent={<RadixUIIcon className="text-lg" />}>
+          Radix UI
+        </ButtonLink>
+      ) : null}
+      {componentLinks.source ? (
+        <ButtonLink href={componentLinks.source} startContent={<GithubIcon size={20} />}>
+          {dict.source}
+        </ButtonLink>
+      ) : null}
+      {componentLinks.source_native ? (
+        <ButtonLink href={componentLinks.source_native} startContent={<GithubIcon size={20} />}>
+          {dict.source}
+        </ButtonLink>
+      ) : null}
+      {componentLinks.styles ? (
+        <ButtonLink href={componentLinks.styles} startContent={<GithubIcon size={20} />}>
+          {dict.stylesSource}
+        </ButtonLink>
+      ) : null}
+      {componentLinks.styles_native ? (
+        <ButtonLink href={componentLinks.styles_native} startContent={<GithubIcon size={20} />}>
+          {dict.stylesSource}
+        </ButtonLink>
+      ) : null}
+      {componentLinks.themes ? (
+        <ButtonLink href={componentLinks.themes} startContent={<GithubIcon size={20} />}>
+          {dict.themeSource}
+        </ButtonLink>
+      ) : null}
+      {componentLinks.tailwind ? (
+        <ButtonLink
+          href={componentLinks.tailwind}
+          startContent={<TailwindIcon className="text-lg text-[#38bdf8]" />}
+        >
+          Tailwind CSS
+        </ButtonLink>
+      ) : null}
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/component-preview-container.tsx b/apps/docs/src/components/component-preview-container.tsx
new file mode 100644
index 0000000..ff2af96
--- /dev/null
+++ b/apps/docs/src/components/component-preview-container.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import React from "react";
+
+import {cn} from "@/utils/cn";
+
+interface ComponentPreviewContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  align?: "center" | "start" | "end";
+  minHeight?: string;
+  isBgSolid?: boolean;
+  description?: string;
+  hideCode?: boolean;
+  name: string;
+}
+
+export function ComponentPreviewContainer({
+  align = "center",
+  children,
+  className,
+  description,
+  hideCode = false,
+  isBgSolid = false,
+  minHeight,
+  name,
+  style,
+  ...props
+}: React.PropsWithChildren<ComponentPreviewContainerProps>) {
+  const [Component, Code] = React.Children.toArray(children) as React.ReactElement[];
+
+  const alignmentClasses = {
+    center: "items-center justify-center",
+    end: "items-end justify-end",
+    start: "items-start justify-start",
+  };
+
+  return (
+    <div
+      className={cn("component-preview-container group relative my-4 w-full", className)}
+      data-name={name}
+      style={{...style, contain: style?.contain ?? "content"}}
+      {...props}
+    >
+      {!!description && <p className="text-muted-foreground mb-2 text-sm">{description}</p>}
+
+      {/* Preview Section */}
+      <div
+        data-name={name}
+        className={cn(
+          "preview not-prose relative min-h-[350px] w-full overflow-hidden rounded-t-xl border-t border-r border-l border-separator p-4 sm:p-10",
+          isBgSolid && "bg-background",
+          alignmentClasses[align],
+          "flex",
+        )}
+      >
+        <div className="flex w-full items-center justify-center" style={{minHeight}}>
+          {Component}
+        </div>
+      </div>
+
+      {/* Code Section */}
+      {!hideCode && !!Code && (
+        <div className="code-section relative rounded-b-xl border border-separator bg-transparent">
+          <div className="code-block-wrapper">{Code}</div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/component-preview.tsx b/apps/docs/src/components/component-preview.tsx
new file mode 100644
index 0000000..30794ff
--- /dev/null
+++ b/apps/docs/src/components/component-preview.tsx
@@ -0,0 +1,77 @@
+// import {Pre} from "fumadocs-ui/components/codeblock";
+import * as React from "react";
+
+import {getDemo} from "@/demos";
+import {cn} from "@/utils/cn";
+
+import {ComponentPreviewContainer} from "./component-preview-container";
+import {ComponentSource} from "./component-source";
+
+interface ComponentPreviewProps extends React.HTMLAttributes<HTMLDivElement> {
+  name: string;
+  align?: "center" | "start" | "end";
+  isBgSolid?: boolean;
+  description?: string;
+  hideCode?: boolean;
+  minHeight?: string;
+  /**
+   * Locale used to resolve which demo registry to read from. Falls back to the
+   * default locale (en) if the requested translation is missing. Usually
+   * injected by the page route via `getMDXComponents` overrides.
+   */
+  locale?: string;
+}
+
+export function ComponentPreviewFallback() {
+  return (
+    <div
+      aria-hidden="true"
+      className="component-preview-container my-4 h-[200px] animate-pulse rounded-lg border bg-muted/30"
+    />
+  );
+}
+
+export async function ComponentPreview({
+  align = "center",
+  className,
+  description,
+  hideCode = false,
+  isBgSolid = false,
+  locale,
+  minHeight,
+  name,
+  ...props
+}: ComponentPreviewProps) {
+  const demo = getDemo(name, locale);
+
+  if (!demo) {
+    return (
+      <div className={cn("my-4 rounded-md border border-red-200 bg-red-50 p-4", className)}>
+        <p className="text-sm text-red-600">
+          Component demo &quot;{name}&quot; not found. Make sure the demo is registered in the demos
+          index.
+        </p>
+      </div>
+    );
+  }
+
+  const Component = await demo.loader();
+
+  return (
+    <ComponentPreviewContainer
+      align={align}
+      className={className}
+      description={description}
+      hideCode={hideCode}
+      isBgSolid={isBgSolid}
+      minHeight={minHeight}
+      name={name}
+      {...props}
+    >
+      <Component />
+      {!hideCode && !!demo.file && (
+        <ComponentSource language="tsx" locale={locale} name={name} title={name} />
+      )}
+    </ComponentPreviewContainer>
+  );
+}
diff --git a/apps/docs/src/components/component-source.tsx b/apps/docs/src/components/component-source.tsx
new file mode 100644
index 0000000..92cfd67
--- /dev/null
+++ b/apps/docs/src/components/component-source.tsx
@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import * as React from "react";
+
+import {getDemo} from "@/demos";
+import {cn} from "@/utils/cn";
+
+import {CodeBlock} from "./codeblock";
+
+export async function ComponentSource({
+  className,
+  // TODO: Disclosure is not ready yet, so we need to use collapsible for now
+  collapsible = true,
+  language,
+  locale,
+  name,
+  showCodeTitle = false,
+  showLineNumbers = true,
+  title,
+}: React.ComponentProps<"div"> & {
+  name?: string;
+  title?: string;
+  language?: string;
+  /** Locale forwarded by `ComponentPreview` to pick the right demo registry. */
+  locale?: string;
+  showCodeTitle?: boolean;
+  showLineNumbers?: boolean;
+  collapsible?: boolean;
+}) {
+  if (!name) {
+    return null;
+  }
+
+  let src: string | undefined;
+  let code: string | undefined;
+
+  if (name) {
+    const item = await getDemo(name, locale);
+
+    src = item?.file;
+  }
+
+  if (src) {
+    try {
+      const file = await fs.readFile(path.join(process.cwd(), "src", "demos", src), "utf-8");
+
+      code = file;
+    } catch (error) {
+      // Failed to read demo file
+
+      return null;
+    }
+  }
+
+  if (!code) {
+    return null;
+  }
+
+  const lang = language ?? title?.split(".").pop() ?? "tsx";
+
+  return (
+    <div className={cn("relative", className)}>
+      <CodeBlock
+        code={code}
+        collapsible={collapsible}
+        lang={lang}
+        showLineNumbers={showLineNumbers}
+        title={showCodeTitle ? title : undefined}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/components-category.tsx b/apps/docs/src/components/components-category.tsx
new file mode 100644
index 0000000..5cd3ae4
--- /dev/null
+++ b/apps/docs/src/components/components-category.tsx
@@ -0,0 +1,215 @@
+import type {StatusChipStatus} from "./status-chip";
+
+import {cn} from "@/utils/cn";
+
+import {source} from "../lib/source";
+
+import {ComponentItem} from "./component-item";
+
+// Component groups matching meta.json structure
+const COMPONENT_GROUPS = [
+  {
+    category: "Buttons",
+    components: [
+      "(buttons)/button",
+      "(buttons)/button-group",
+      "(buttons)/close-button",
+      "(buttons)/toggle-button",
+      "(buttons)/toggle-button-group",
+    ],
+  },
+  {
+    category: "Forms",
+    components: [
+      "(forms)/checkbox",
+      "(forms)/checkbox-group",
+      "(forms)/description",
+      "(forms)/error-message",
+      "(forms)/field-error",
+      "(forms)/fieldset",
+      "(forms)/form",
+      "(forms)/input",
+      "(forms)/input-group",
+      "(forms)/input-otp",
+      "(forms)/label",
+      "(forms)/number-field",
+      "(forms)/radio-group",
+      "(forms)/search-field",
+      "(forms)/text-field",
+      "(forms)/text-area",
+    ],
+  },
+  {
+    category: "Date and Time",
+    components: [
+      "(date-and-time)/calendar",
+      "(date-and-time)/date-field",
+      "(date-and-time)/date-picker",
+      "(date-and-time)/date-range-picker",
+      "(date-and-time)/range-calendar",
+      "(date-and-time)/time-field",
+    ],
+  },
+  {
+    category: "Navigation",
+    components: [
+      "(navigation)/accordion",
+      "(navigation)/breadcrumbs",
+      "(navigation)/disclosure",
+      "(navigation)/disclosure-group",
+      "(navigation)/link",
+      "(navigation)/pagination",
+      "(navigation)/tabs",
+    ],
+  },
+  {
+    category: "Overlays",
+    components: [
+      "(overlays)/alert-dialog",
+      "(overlays)/drawer",
+      "(overlays)/modal",
+      "(overlays)/popover",
+      "(overlays)/toast",
+      "(overlays)/tooltip",
+    ],
+  },
+  {
+    category: "Collections",
+    components: ["(collections)/dropdown", "(collections)/list-box", "(collections)/tag-group"],
+  },
+  {
+    category: "Controls",
+    components: ["(controls)/slider", "(controls)/switch"],
+  },
+  {
+    category: "Feedback",
+    components: [
+      "(feedback)/alert",
+      "(feedback)/meter",
+      "(feedback)/progress-bar",
+      "(feedback)/progress-circle",
+      "(feedback)/skeleton",
+      "(feedback)/spinner",
+    ],
+  },
+  {
+    category: "Layout",
+    components: ["(layout)/card", "(layout)/separator", "(layout)/surface", "(layout)/toolbar"],
+  },
+  {
+    category: "Media",
+    components: ["(media)/avatar"],
+  },
+  {
+    category: "Pickers",
+    components: ["(pickers)/autocomplete", "(pickers)/combo-box", "(pickers)/select"],
+  },
+  {
+    category: "Typography",
+    components: ["(typography)/kbd", "(typography)/typography"],
+  },
+  {
+    category: "Data Display",
+    components: ["(data-display)/badge", "(data-display)/chip", "(data-display)/table"],
+  },
+  {
+    category: "Colors",
+    components: [
+      "(colors)/color-area",
+      "(colors)/color-field",
+      "(colors)/color-picker",
+      "(colors)/color-slider",
+      "(colors)/color-swatch",
+      "(colors)/color-swatch-picker",
+    ],
+  },
+  {
+    category: "Utilities",
+    components: ["(utilities)/scroll-shadow"],
+  },
+] as const;
+
+const componentStatusIcons = ["preview", "new", "updated", "new-dot"];
+
+interface ComponentWithStatus {
+  component: {
+    name: string;
+    title: string;
+    description: string;
+    href: string;
+    category?: string;
+  };
+  status?: StatusChipStatus;
+}
+
+interface ComponentCategory {
+  category: string;
+  locale: string;
+}
+
+function isRouteGroup(part: string): boolean {
+  return part.startsWith("(") && part.endsWith(")");
+}
+
+function getComponentNameFromPath(path: string): string {
+  return path.split("/").pop() || path;
+}
+
+function getComponentWithStatus(path: string, locale: string): ComponentWithStatus | null {
+  const pathWithoutRouteGroups = path
+    .split("/")
+    .filter((part) => !isRouteGroup(part))
+    .join("/");
+
+  const pagePath = ["react", "components", ...pathWithoutRouteGroups.split("/")].filter(Boolean);
+  const page = source.getPage(pagePath, locale);
+
+  if (!page) return null;
+
+  const title = page.data.title || "";
+  const description = page.data.description || "";
+  const componentName = getComponentNameFromPath(path);
+  const icon = page.data.icon;
+  const status: StatusChipStatus | undefined =
+    icon && componentStatusIcons.includes(icon) ? (icon as StatusChipStatus) : undefined;
+
+  return {
+    component: {
+      category: undefined,
+      description,
+      href: page.url,
+      name: componentName,
+      title,
+    },
+    status,
+  };
+}
+
+export function ComponentsCategory({category, locale}: ComponentCategory) {
+  const group = COMPONENT_GROUPS.find((group) => group.category === category);
+
+  if (!group) return null;
+
+  const components = group.components
+    .map((path) => getComponentWithStatus(path, locale))
+    .filter((item): item is ComponentWithStatus => item !== null);
+
+  if (components.length === 0) return null;
+
+  return (
+    <div className={cn("not-prose flex flex-col gap-12")}>
+      <div key={group.category} className="flex flex-col gap-6">
+        <div className={cn("grid grid-cols-1 gap-x-4 gap-y-10 sm:grid-cols-2 lg:grid-cols-3")}>
+          {components.map(({component, status}) => (
+            <ComponentItem
+              key={component.name}
+              component={component}
+              openInNewTab={false}
+              status={status}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/copy-prompt.tsx b/apps/docs/src/components/copy-prompt.tsx
new file mode 100644
index 0000000..20e817b
--- /dev/null
+++ b/apps/docs/src/components/copy-prompt.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {Button} from "@heroui/react";
+import {useCopyButton} from "fumadocs-ui/utils/use-copy-button";
+
+import {Iconify} from "@/components/iconify";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+/**
+ * Props for the {@link CopyPrompt} MDX component.
+ */
+export interface CopyPromptProps {
+  /**
+   * The prompt text written to the clipboard when the user clicks the button.
+   * Multi-line strings are supported.
+   */
+  prompt: string;
+  /**
+   * Inline description rendered next to the icon. Accepts MDX / JSX so bold
+   * text, links, and other inline formatting are supported.
+   */
+  children: React.ReactNode;
+  /**
+   * Iconify icon name shown on the left. Defaults to `"sparkles"`.
+   */
+  icon?: string;
+  /**
+   * Optional additional class names applied to the outer container.
+   */
+  className?: string;
+}
+
+/**
+ * CopyPrompt
+ *
+ * A compact horizontal card consisting of an icon on the left, an inline
+ * description in the middle, and a "Copy prompt" button on the right.
+ * The prompt itself is intentionally hidden — clicking the button copies
+ * it to the user's clipboard so they can paste it into their AI assistant.
+ *
+ * This is a client component because clipboard access and the "Copied"
+ * toggle state from `useCopyButton` must run in the browser.
+ */
+export function CopyPrompt({children, className, icon = "sparkles-fill", prompt}: CopyPromptProps) {
+  const dict = useDictionary().copyPrompt;
+  const [checked, onClick] = useCopyButton(() => {
+    void navigator.clipboard.writeText(prompt);
+  });
+
+  return (
+    <div
+      className={cn(
+        "flex gap-2 rounded-xl border border-border bg-surface py-3 pr-3 pl-1 text-sm text-surface-foreground shadow-surface",
+        className,
+      )}
+    >
+      <div className="flex gap-2">
+        <div className="w-0.5 self-stretch rounded-sm bg-accent/50" role="none" />
+        <Iconify className="mt-1 size-4 shrink-0 text-accent" icon={icon} />
+      </div>
+      <div className="prose-no-margin min-w-0 flex-1 leading-relaxed">{children}</div>
+      <Button
+        aria-label={checked ? dict.ariaLabelCopied : dict.ariaLabelCopy}
+        className="shrink-0"
+        isDisabled={checked}
+        size="sm"
+        type="button"
+        variant="tertiary"
+        onClick={onClick}
+      >
+        {checked ? (
+          <>
+            <Iconify icon="check" />
+            {dict.copied}
+          </>
+        ) : (
+          <>
+            <Iconify icon="copy" />
+            {dict.copy}
+          </>
+        )}
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/alert-demo.tsx b/apps/docs/src/components/demo/alert-demo.tsx
new file mode 100644
index 0000000..19b2443
--- /dev/null
+++ b/apps/docs/src/components/demo/alert-demo.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Alert, Button} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function AlertDemo() {
+  const {demos} = useDictionary();
+  const t = demos.alert;
+
+  return (
+    <Alert className="w-full items-center xl:w-[400px]">
+      <Alert.Indicator />
+      <Alert.Content className="text-left">
+        <Alert.Title className="leading-5">{t.title}</Alert.Title>
+        <Alert.Description className="text-xs">{t.description}</Alert.Description>
+      </Alert.Content>
+      <Button variant="tertiary">{t.action}</Button>
+    </Alert>
+  );
+}
diff --git a/apps/docs/src/components/demo/alert-dialog-demo.tsx b/apps/docs/src/components/demo/alert-dialog-demo.tsx
new file mode 100644
index 0000000..f78777f
--- /dev/null
+++ b/apps/docs/src/components/demo/alert-dialog-demo.tsx
@@ -0,0 +1,32 @@
+"use client";
+
+import {Avatar, Button, Card, CloseButton} from "@heroui/react";
+
+import {Iconify} from "@/components/iconify";
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function AlertDialogDemo() {
+  const {demos} = useDictionary();
+  const t = demos.alertDialog;
+
+  return (
+    <Card className="h-[208px] w-full items-start justify-center p-5 min-[1200px]:w-[340px]">
+      <Card.Header className="flex w-full items-start justify-center gap-2 px-1">
+        <Avatar color="warning" variant="soft">
+          <Avatar.Fallback>
+            <Iconify className="text-lg" icon="gravity-ui:floppy-disk" />
+          </Avatar.Fallback>
+        </Avatar>
+        <Card.Title>{t.title}</Card.Title>
+        <Card.Description>{t.description}</Card.Description>
+        <CloseButton className="absolute top-3 right-3" />
+      </Card.Header>
+      <Card.Footer className="flex w-full items-center gap-2 px-0.5 pt-3">
+        <Button className="w-full" variant="tertiary">
+          {t.discard}
+        </Button>
+        <Button className="w-full">{t.save}</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/components/demo/allow-notifications-demo.tsx b/apps/docs/src/components/demo/allow-notifications-demo.tsx
new file mode 100644
index 0000000..fa441b5
--- /dev/null
+++ b/apps/docs/src/components/demo/allow-notifications-demo.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {Description, Label, Switch} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function AllowNotificationsDemo() {
+  const {demos} = useDictionary();
+  const t = demos.allowNotifications;
+
+  return (
+    <div className="flex w-full justify-center">
+      <Switch defaultSelected>
+        <div className="flex gap-8 p-4">
+          <div className="-mt-0.5 flex flex-col justify-start gap-1">
+            <Label className="w-fit text-sm font-medium">{t.label}</Label>
+            <Description>{t.description}</Description>
+          </div>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </div>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/avatar-group-demo.tsx b/apps/docs/src/components/demo/avatar-group-demo.tsx
new file mode 100644
index 0000000..d73857f
--- /dev/null
+++ b/apps/docs/src/components/demo/avatar-group-demo.tsx
@@ -0,0 +1,57 @@
+import {Avatar} from "@heroui/react";
+
+const avatars = [
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Blue",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "Green",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "Purple",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "Orange",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "red",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Blue",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+    name: "Black",
+  },
+];
+
+export function AvatarGroupDemo() {
+  return (
+    <div className="flex w-full justify-center">
+      <div className="flex -space-x-2">
+        {avatars.slice(0, 5).map((item, index) => (
+          <Avatar key={`${item.name}-${index}`} className="ring-2 ring-background">
+            <Avatar.Image alt={item.name} src={item.image} />
+            <Avatar.Fallback>
+              {item.name
+                .split(" ")
+                .map((n) => n[0])
+                .join("")}
+            </Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="bg-surface text-xs font-medium text-muted">
+            +{avatars.length - 2}
+          </Avatar.Fallback>
+        </Avatar>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/buttons-demo.tsx b/apps/docs/src/components/demo/buttons-demo.tsx
new file mode 100644
index 0000000..cfdde9b
--- /dev/null
+++ b/apps/docs/src/components/demo/buttons-demo.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {Button} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export const ButtonsDemo = () => {
+  const {demos} = useDictionary();
+  const label = demos.buttons.clickMe;
+
+  return (
+    <div className="grid grid-cols-3 gap-x-3 gap-y-2">
+      <Button size="sm">{label}</Button>
+      <Button size="sm" variant="secondary">
+        {label}
+      </Button>
+      <Button size="sm" variant="tertiary">
+        {label}
+      </Button>
+      <Button size="sm" variant="danger">
+        {label}
+      </Button>
+      <Button size="sm" variant="danger-soft">
+        {label}
+      </Button>
+      <Button size="sm" variant="ghost">
+        {label}
+      </Button>
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/demo/index.tsx b/apps/docs/src/components/demo/index.tsx
new file mode 100644
index 0000000..9bde67d
--- /dev/null
+++ b/apps/docs/src/components/demo/index.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {AlertDemo} from "./alert-demo";
+import {AlertDialogDemo} from "./alert-dialog-demo";
+import {AllowNotificationsDemo} from "./allow-notifications-demo";
+import {AvatarGroupDemo} from "./avatar-group-demo";
+import {ButtonsDemo} from "./buttons-demo";
+import {InputOTPDemo} from "./input-otp-demo";
+import {ListBoxDemo} from "./list-box-demo";
+import {LoginDemo} from "./login-demo";
+import {SelectDemo} from "./select-demo";
+import {SliderDemo} from "./slider-demo";
+import {SubtleCardsDemo} from "./subtle-cards-demo";
+import {TabsDemo1} from "./tabs-1-demo";
+import {TabsDemo2} from "./tabs-2-demo";
+import {TextfieldDemo} from "./textfield-demo";
+import {UIComponentsDemo} from "./ui-components-demo";
+import {XProfileDemo} from "./x-profile-demo";
+
+export function DemoComponents() {
+  return (
+    <div className="mx-auto grid w-fit grid-cols-1 gap-8 md:grid-cols-2 lg:grid-cols-[auto_auto_auto]">
+      {/* Left */}
+      <div className="order-2 flex max-w-[360px] flex-col items-center gap-10 md:order-1">
+        <TextfieldDemo />
+        <SelectDemo />
+        <UIComponentsDemo />
+        <SliderDemo />
+        <TabsDemo1 />
+        <TabsDemo2 />
+        <ListBoxDemo />
+      </div>
+      {/* Center */}
+      <div className="order-1 flex max-w-[360px] flex-col items-center gap-10 md:order-2">
+        <AvatarGroupDemo />
+        <InputOTPDemo />
+        <ButtonsDemo />
+        <XProfileDemo />
+        <AlertDemo />
+        <AllowNotificationsDemo />
+      </div>
+      {/* Right */}
+      <div className="order-3 col-span-1 grid grid-cols-1 grid-rows-2 justify-items-center gap-5 self-start md:col-span-2 md:grid-cols-2 md:grid-rows-[auto_auto] lg:col-span-1 lg:max-w-[360px] lg:grid-cols-1">
+        <div className="row-span-2">
+          <LoginDemo />
+        </div>
+        <div className="align-self-start w-full">
+          <SubtleCardsDemo />
+        </div>
+        <AlertDialogDemo />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/input-otp-demo.tsx b/apps/docs/src/components/demo/input-otp-demo.tsx
new file mode 100644
index 0000000..adc6802
--- /dev/null
+++ b/apps/docs/src/components/demo/input-otp-demo.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {InputOTP, Label, Link} from "@heroui/react";
+import {useState} from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function InputOTPDemo() {
+  const {demos} = useDictionary();
+  const t = demos.inputOtp;
+  // HERO - 4320 - easter egg
+  const [value, setValue] = useState("4320");
+
+  return (
+    <div className="flex w-full justify-center">
+      <div className="flex w-[280px] flex-col items-start justify-center gap-2">
+        <div className="flex flex-col items-start gap-1">
+          <Label>{t.label}</Label>
+          <p className="text-sm text-muted">{t.description}</p>
+        </div>
+        <InputOTP maxLength={6} value={value} onChange={setValue}>
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <div className="flex items-center gap-[5px] px-1 pt-1">
+          <p className="text-sm text-muted">{t.didntReceive}</p>
+          <Link className="text-foreground">{t.resend}</Link>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/list-box-demo.tsx b/apps/docs/src/components/demo/list-box-demo.tsx
new file mode 100644
index 0000000..b9484d4
--- /dev/null
+++ b/apps/docs/src/components/demo/list-box-demo.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+
+import {Iconify} from "@/components/iconify";
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function ListBoxDemo() {
+  const {demos} = useDictionary();
+  const t = demos.listBox;
+
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label={t.ariaLabel} className="w-full p-2" selectionMode="none">
+        <ListBox.Section>
+          <Header>{t.actions}</Header>
+          <ListBox.Item id="new-file" textValue={t.newFile}>
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Iconify className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+            </div>
+            <div className="flex flex-col">
+              <Label>{t.newFile}</Label>
+              <Description>{t.newFileDescription}</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue={t.editFile}>
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Iconify className="size-4 shrink-0 text-muted" icon="gravity-ui:pencil" />
+            </div>
+            <div className="flex flex-col">
+              <Label>{t.editFile}</Label>
+              <Description>{t.editFileDescription}</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>{t.dangerZone}</Header>
+          <ListBox.Item id="delete-file" textValue={t.deleteFile} variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Iconify className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+            </div>
+            <div className="flex flex-col">
+              <Label>{t.deleteFile}</Label>
+              <Description>{t.deleteFileDescription}</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/components/demo/login-demo.tsx b/apps/docs/src/components/demo/login-demo.tsx
new file mode 100644
index 0000000..44010e8
--- /dev/null
+++ b/apps/docs/src/components/demo/login-demo.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {Avatar, Button, Card, CloseButton, Separator} from "@heroui/react";
+
+import {Iconify} from "@/components/iconify";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {AppleIcon} from "@/icons/apple";
+import {GoogleIcon} from "@/icons/google";
+
+export function LoginDemo() {
+  const {demos} = useDictionary();
+  const t = demos.login;
+
+  return (
+    <Card className="w-[320px] max-w-full items-start justify-center p-5">
+      <Card.Header className="flex w-full items-center justify-center gap-2">
+        <Avatar>
+          <Avatar.Fallback>
+            <Iconify icon="gravity-ui:person" />
+          </Avatar.Fallback>
+        </Avatar>
+        <Card.Title>{t.title}</Card.Title>
+        <CloseButton className="absolute top-3 right-3" />
+      </Card.Header>
+      <Card.Content className="w-full gap-2">
+        <p className="text-center text-sm font-medium text-balance text-muted">{t.trialNote}</p>
+        <Button className="w-full">{t.getStarted}</Button>
+        <div className="flex w-full items-center gap-2 py-2">
+          <Separator className="flex-1" />
+          <p className="text-center text-xs font-medium text-muted uppercase">{t.or}</p>
+          <Separator className="flex-1" />
+        </div>
+        <Button className="w-full" variant="tertiary">
+          <GoogleIcon />
+          {t.continueWithGoogle}
+        </Button>
+        <Button className="w-full" variant="tertiary">
+          <AppleIcon />
+          {t.continueWithApple}
+        </Button>
+      </Card.Content>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/components/demo/select-demo.tsx b/apps/docs/src/components/demo/select-demo.tsx
new file mode 100644
index 0000000..b0f9811
--- /dev/null
+++ b/apps/docs/src/components/demo/select-demo.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {Label, ListBox, Select} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function SelectDemo() {
+  const {demos} = useDictionary();
+  const t = demos.select;
+  const options = t.options;
+
+  return (
+    <Select isRequired className="w-[256px]" placeholder={t.placeholder}>
+      <Label>{t.label}</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue={options.florida}>
+            {options.florida}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue={options.delaware}>
+            {options.delaware}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue={options.california}>
+            {options.california}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue={options.texas}>
+            {options.texas}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue={options.newYork}>
+            {options.newYork}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue={options.washington}>
+            {options.washington}
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/components/demo/slider-demo.tsx b/apps/docs/src/components/demo/slider-demo.tsx
new file mode 100644
index 0000000..6c0bf1e
--- /dev/null
+++ b/apps/docs/src/components/demo/slider-demo.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Label, Slider} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function SliderDemo() {
+  const {demos} = useDictionary();
+
+  return (
+    <div className="w-[256px] px-1">
+      <Slider
+        className="w-full max-w-xs"
+        defaultValue={250}
+        formatOptions={{currency: "USD", style: "currency"}}
+        maxValue={500}
+        minValue={0}
+        step={10}
+      >
+        <Label>{demos.slider.label}</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/subtle-cards-demo.tsx b/apps/docs/src/components/demo/subtle-cards-demo.tsx
new file mode 100644
index 0000000..55855f9
--- /dev/null
+++ b/apps/docs/src/components/demo/subtle-cards-demo.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import {Avatar, Card} from "@heroui/react";
+import {tv} from "tailwind-variants";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+const cardStyles = tv({
+  slots: {
+    avatar: "size-[56px] rounded-xl",
+    card: "w-full flex-1",
+    cardContent: "items-start",
+    footer: "items-center gap-2",
+    footerAvatar: "size-4",
+  },
+});
+
+export function SubtleCardsDemo() {
+  const {avatar, card, cardContent, footer, footerAvatar} = cardStyles();
+  const {demos} = useDictionary();
+  const t = demos.subtleCards;
+
+  return (
+    <div className="flex w-full flex-row flex-wrap justify-between gap-4">
+      <Card className={card()}>
+        <Card.Header>
+          <Avatar className={avatar()}>
+            <Avatar.Image
+              alt={t.indieTitle}
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+            />
+            <Avatar.Fallback>JK</Avatar.Fallback>
+          </Avatar>
+        </Card.Header>
+        <Card.Content className={cardContent()}>
+          <p className="text-sm font-medium">{t.indieTitle}</p>
+          <p className="text-sm text-muted">{t.indieMembers}</p>
+        </Card.Content>
+        <Card.Footer className={footer()}>
+          <Avatar className={footerAvatar()}>
+            <Avatar.Image
+              alt="John"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+            />
+            <Avatar.Fallback>JK</Avatar.Fallback>
+          </Avatar>
+          <p className="text-xs text-muted">{t.indieBy}</p>
+        </Card.Footer>
+      </Card>
+      <Card className={card()}>
+        <Card.Header>
+          <Avatar className={avatar()}>
+            <Avatar.Image
+              alt={t.aiTitle}
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+            />
+            <Avatar.Fallback>J</Avatar.Fallback>
+          </Avatar>
+        </Card.Header>
+        <Card.Content className={cardContent()}>
+          <p className="text-sm font-medium">{t.aiTitle}</p>
+          <p className="text-sm text-muted">{t.aiMembers}</p>
+        </Card.Content>
+        <Card.Footer className={footer()}>
+          <Avatar className={footerAvatar()}>
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <p className="text-xs text-muted">{t.aiBy}</p>
+        </Card.Footer>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/tabs-1-demo.tsx b/apps/docs/src/components/demo/tabs-1-demo.tsx
new file mode 100644
index 0000000..a671720
--- /dev/null
+++ b/apps/docs/src/components/demo/tabs-1-demo.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Tabs} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function TabsDemo1() {
+  const {demos} = useDictionary();
+  const t = demos.tabs1;
+
+  return (
+    <Tabs className="w-[256px]">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label={t.ariaLabel}>
+          <Tabs.Tab id="1d">
+            1D
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="7d">
+            7D
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="1m">
+            1M
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="1y">
+            1Y
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="all">
+            {t.all}
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/components/demo/tabs-2-demo.tsx b/apps/docs/src/components/demo/tabs-2-demo.tsx
new file mode 100644
index 0000000..2a38d45
--- /dev/null
+++ b/apps/docs/src/components/demo/tabs-2-demo.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Tabs} from "@heroui/react";
+
+import {Iconify} from "@/components/iconify";
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function TabsDemo2() {
+  const {demos} = useDictionary();
+  const t = demos.tabs2;
+
+  return (
+    <Tabs className="w-[256px]">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label={t.ariaLabel}>
+          <Tabs.Tab className="gap-1.5" id="chats">
+            <Iconify icon="gravity-ui:comment" />
+            <span>{t.chats}</span>
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab className="gap-1.5" id="emails">
+            <Iconify icon="gravity-ui:envelope" />
+            <span>{t.emails}</span>
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/components/demo/textfield-demo.tsx b/apps/docs/src/components/demo/textfield-demo.tsx
new file mode 100644
index 0000000..e4ac206
--- /dev/null
+++ b/apps/docs/src/components/demo/textfield-demo.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Description, FieldError, Input, Label, TextField} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function TextfieldDemo() {
+  const {demos} = useDictionary();
+  const t = demos.textfield;
+
+  return (
+    <div>
+      <TextField isRequired className="items-start" name="name">
+        <Label>{t.label}</Label>
+        <Input className="w-[256px]" placeholder={t.placeholder} />
+        <Description className="mt-0.5">{t.description}</Description>
+        <FieldError>{t.error}</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/ui-components-demo.tsx b/apps/docs/src/components/demo/ui-components-demo.tsx
new file mode 100644
index 0000000..7332fc1
--- /dev/null
+++ b/apps/docs/src/components/demo/ui-components-demo.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import {Checkbox, Radio, RadioGroup, Spinner, Switch} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function UIComponentsDemo() {
+  const {demos} = useDictionary();
+  const t = demos.uiComponents;
+
+  return (
+    <div className="flex w-full items-center justify-center gap-8">
+      {/* Checkbox - Selected State */}
+      <Checkbox defaultSelected aria-label={t.checkboxAriaLabel}>
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+
+      {/* Switch - On State */}
+      <Switch defaultSelected aria-label={t.switchAriaLabel}>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </Switch.Content>
+      </Switch>
+
+      {/* Radio Buttons - Unselected and Selected */}
+      <RadioGroup
+        aria-label={t.radioAriaLabel}
+        className="gap-8"
+        defaultValue="option2"
+        name="demo"
+        orientation="horizontal"
+      >
+        <Radio value="option1">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+          </Radio.Content>
+        </Radio>
+        <Radio value="option2">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+          </Radio.Content>
+        </Radio>
+      </RadioGroup>
+
+      {/* Spinner */}
+      <Spinner />
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/demo/x-profile-demo.tsx b/apps/docs/src/components/demo/x-profile-demo.tsx
new file mode 100644
index 0000000..9496ccd
--- /dev/null
+++ b/apps/docs/src/components/demo/x-profile-demo.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {Avatar, Card} from "@heroui/react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {VerifiedBadgeIcon} from "@/icons/verified-badge";
+
+export function XProfileDemo() {
+  const {demos} = useDictionary();
+  const t = demos.xProfile;
+
+  return (
+    <Card className="w-full items-start justify-center xl:w-[400px]">
+      <Card.Header className="items-top w-full flex-row justify-between">
+        <div className="flex items-center gap-3">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="HeroUI"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui_isotipo.png"
+            />
+            <Avatar.Fallback>H</Avatar.Fallback>
+          </Avatar>
+          <div className="flex h-full flex-col items-start justify-center">
+            <div className="flex items-center gap-0.5">
+              <span className="text-sm leading-4 font-semibold">HeroUI</span>
+              <VerifiedBadgeIcon height={18} width={18} />
+            </div>
+            <span className="text-sm tracking-tight text-muted">@hero_ui</span>
+          </div>
+        </div>
+      </Card.Header>
+      <Card.Content className="flex-row text-left">
+        <p className="pl-px text-sm font-medium">
+          {t.bio}&nbsp;
+          <br />
+          <span aria-label={t.confettiLabel} role="img">
+            🚀
+          </span>
+          &nbsp;{t.bioSuffix}&nbsp;
+        </p>
+      </Card.Content>
+      <Card.Footer className="gap-2">
+        <div className="flex gap-1">
+          <p className="text-sm font-semibold">4</p>
+          <p className="text-sm text-muted">{t.following}</p>
+        </div>
+        <div className="flex gap-1">
+          <p className="text-sm font-semibold">97.1K</p>
+          <p className="text-sm text-muted">{t.followers}</p>
+        </div>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/components/design-theme-selector.tsx b/apps/docs/src/components/design-theme-selector.tsx
new file mode 100644
index 0000000..d6d7518
--- /dev/null
+++ b/apps/docs/src/components/design-theme-selector.tsx
@@ -0,0 +1,258 @@
+"use client";
+
+import type {ThemeId} from "@/app/[lang]/themes/constants";
+import type {ButtonProps} from "@heroui/react";
+import type {StaticImageData} from "next/image";
+
+import {BucketPaint, Palette} from "@gravity-ui/icons";
+import {Button, Description, Label, ListBox, Popover, Switch, buttonVariants} from "@heroui/react";
+import LinkRoot from "fumadocs-core/link";
+import Image from "next/image";
+import {useCallback, useEffect, useMemo, useState} from "react";
+
+import {themeValuesById} from "@/app/[lang]/themes/constants";
+import airbnbTheme from "@/assets/themes/airbnb.png";
+import blackTheme from "@/assets/themes/black.png";
+import coinbaseTheme from "@/assets/themes/coinbase.png";
+import defaultTheme from "@/assets/themes/default.png";
+import discordTheme from "@/assets/themes/discord.png";
+import lavenderTheme from "@/assets/themes/lavender.png";
+import mintTheme from "@/assets/themes/mint.png";
+import netflixTheme from "@/assets/themes/netflix.png";
+import rabbitTheme from "@/assets/themes/rabbit.png";
+import skyTheme from "@/assets/themes/sky.png";
+import spotifyTheme from "@/assets/themes/spotify.png";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+import {
+  DESIGN_THEME_STORAGE_KEY,
+  VIBRANT_STORAGE_KEY,
+  getStoredDesignTheme,
+  isDesignThemeId,
+  notifyDesignThemeChange,
+} from "@/utils/design-theme";
+
+interface ThemeOption {
+  id: ThemeId;
+  label: string;
+  image: StaticImageData;
+}
+
+const THEMES: ThemeOption[] = [
+  {id: "default", image: defaultTheme, label: "Default"},
+  {id: "sky", image: skyTheme, label: "Sky"},
+  {id: "lavender", image: lavenderTheme, label: "Lavender"},
+  {id: "mint", image: mintTheme, label: "Mint"},
+  {id: "netflix", image: netflixTheme, label: "Netflix"},
+  {id: "uber", image: blackTheme, label: "Uber"},
+  {id: "spotify", image: spotifyTheme, label: "Spotify"},
+  {id: "coinbase", image: coinbaseTheme, label: "Coinbase"},
+  {id: "airbnb", image: airbnbTheme, label: "Airbnb"},
+  {id: "discord", image: discordTheme, label: "Discord"},
+  {id: "rabbit", image: rabbitTheme, label: "Rabbit"},
+];
+
+function removeThemeCssLink() {
+  document.getElementById("design-theme-css-link")?.remove();
+}
+
+function applyTheme(themeId: ThemeId) {
+  const root = document.documentElement;
+  const isDefault = themeId === "default";
+
+  if (isDefault) {
+    root.removeAttribute("data-design-theme");
+  } else {
+    root.setAttribute("data-design-theme", themeId);
+  }
+
+  removeThemeCssLink();
+}
+
+export function DesignThemeSelector({
+  triggerVariant = "tertiary",
+}: {
+  triggerVariant?: ButtonProps["variant"];
+}) {
+  const dict = useDictionary().themes;
+  const [active, setActive] = useState<ThemeId>("default");
+  const [mounted, setMounted] = useState(false);
+  const [vibrant, setVibrant] = useState(false);
+
+  /* eslint-disable react-hooks/set-state-in-effect */
+  useEffect(() => setMounted(true), []);
+
+  useEffect(() => {
+    const stored = getStoredDesignTheme();
+
+    if (stored !== "default") {
+      setActive(stored);
+      applyTheme(stored);
+    }
+
+    const storedVibrant = localStorage.getItem(VIBRANT_STORAGE_KEY);
+
+    if (storedVibrant === "true") {
+      setVibrant(true);
+      document.documentElement.setAttribute("data-vibrant-palette", "true");
+    }
+  }, []);
+  /* eslint-enable react-hooks/set-state-in-effect */
+
+  const handleSelect = useCallback((keys: "all" | Set<React.Key>) => {
+    if (keys === "all") return;
+    const selected = [...keys][0];
+
+    if (typeof selected !== "string" || !isDesignThemeId(selected)) return;
+    setActive(selected);
+    localStorage.setItem(DESIGN_THEME_STORAGE_KEY, selected);
+    applyTheme(selected);
+    notifyDesignThemeChange(selected);
+  }, []);
+
+  const handleVibrantToggle = useCallback((isSelected: boolean) => {
+    setVibrant(isSelected);
+    localStorage.setItem(VIBRANT_STORAGE_KEY, String(isSelected));
+
+    if (isSelected) {
+      document.documentElement.setAttribute("data-vibrant-palette", "true");
+    } else {
+      document.documentElement.removeAttribute("data-vibrant-palette");
+    }
+  }, []);
+
+  const current = THEMES.find((t) => t.id === active);
+  const showAvatar = mounted && active !== "default" && current;
+
+  const themeBuilderHref = useMemo(() => {
+    const values = themeValuesById[active];
+
+    if (!values) {
+      return "/themes";
+    }
+
+    const params = new URLSearchParams();
+
+    params.set("lightness", String(values.lightness));
+    params.set("chroma", String(values.chroma));
+    params.set("hue", String(values.hue));
+
+    return `/themes?${params.toString()}`;
+  }, [active]);
+
+  return (
+    <>
+      {/* Preload all theme images so they're cached before the popover opens */}
+      <div aria-hidden className="pointer-events-none fixed size-0 overflow-hidden opacity-0">
+        {THEMES.map((t) => (
+          <Image
+            key={t.id}
+            priority
+            alt=""
+            height={36}
+            placeholder="blur"
+            src={t.image}
+            width={36}
+          />
+        ))}
+      </div>
+      <Popover>
+        <Popover.Trigger>
+          <Button
+            aria-label={dict.designTheme}
+            size="sm"
+            variant={triggerVariant}
+            className={cn(
+              "text-xs text-muted",
+              showAvatar &&
+                "max-sm:min-w-0 max-sm:border-0 max-sm:bg-transparent max-sm:px-0 sm:gap-1.5 sm:pr-2.5 sm:pl-2",
+            )}
+          >
+            {showAvatar ? (
+              <Image
+                alt={current.label}
+                className="size-5 shrink-0 rounded-full sm:size-3.5"
+                height={20}
+                placeholder="blur"
+                src={current.image}
+                width={20}
+              />
+            ) : (
+              <BucketPaint className="size-3.5 text-foreground" />
+            )}
+            <span className="hidden sm:inline">{showAvatar ? current.label : dict.theme}</span>
+          </Button>
+        </Popover.Trigger>
+        <Popover.Content className="w-[248px] rounded-3xl" placement="bottom">
+          <Popover.Dialog className="p-4">
+            <ListBox
+              aria-label={dict.designTheme}
+              className="grid grid-cols-4 gap-3"
+              items={THEMES}
+              layout="grid"
+              selectedKeys={new Set([active])}
+              selectionMode="single"
+              onSelectionChange={handleSelect}
+            >
+              {(item) => (
+                <ListBox.Item
+                  key={item.id}
+                  id={item.id}
+                  textValue={item.label}
+                  className={cn(
+                    "group relative flex w-10 flex-col items-center justify-center gap-1.5 p-0",
+                    "hover:bg-transparent data-[hovered=true]:bg-transparent",
+                  )}
+                >
+                  <Image
+                    alt={item.label}
+                    height={36}
+                    placeholder="blur"
+                    src={item.image}
+                    width={36}
+                    className={cn(
+                      "size-9 rounded-full bg-surface",
+                      "group-data-[selected=true]:ring-2 group-data-[selected=true]:ring-accent group-data-[selected=true]:ring-offset-2 group-data-[selected=true]:ring-offset-surface",
+                    )}
+                  />
+                  <span className="text-[10px] font-medium text-muted capitalize group-data-[selected=true]:text-foreground">
+                    {item.label}
+                  </span>
+                </ListBox.Item>
+              )}
+            </ListBox>
+            <div className="mt-4 border-t border-separator pt-4">
+              <div className="flex items-center justify-between">
+                <div className="flex flex-col gap-0.5">
+                  <Label className="text-xs">{dict.vibrantPalette}</Label>
+                  <Description className="text-[10px]">
+                    {dict.vibrantPaletteDescription}
+                  </Description>
+                </div>
+                <Switch isSelected={vibrant} onChange={handleVibrantToggle}>
+                  <Switch.Content>
+                    <Switch.Control>
+                      <Switch.Thumb />
+                    </Switch.Control>
+                  </Switch.Content>
+                </Switch>
+              </div>
+            </div>
+            <LinkRoot
+              href={themeBuilderHref}
+              className={buttonVariants({
+                className: "mt-3 rounded-full text-[13px] text-muted",
+                fullWidth: true,
+                size: "sm",
+                variant: "outline",
+              })}
+            >
+              <Palette className="size-4" />
+              {dict.editTheme}
+            </LinkRoot>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </>
+  );
+}
diff --git a/apps/docs/src/components/docs-image.tsx b/apps/docs/src/components/docs-image.tsx
new file mode 100644
index 0000000..18f7779
--- /dev/null
+++ b/apps/docs/src/components/docs-image.tsx
@@ -0,0 +1,75 @@
+import type {UrlObject} from "url";
+
+import Image from "next/image";
+import Link from "next/link";
+
+import {cn} from "@/utils/cn";
+
+interface DocsImageProps {
+  src: string;
+  darkSrc?: string;
+  alt: string;
+  className?: string;
+  width?: number;
+  wrapperClassName?: string;
+  height?: number;
+  priority?: boolean;
+  href?: string;
+}
+
+export function DocsImage({
+  alt,
+  className,
+  darkSrc,
+  height = 1000,
+  href,
+  priority = true,
+  src,
+  width = 1000,
+  wrapperClassName,
+}: DocsImageProps) {
+  const wrapperClasses = cn(
+    "not-prose relative block aspect-18/9 w-full overflow-hidden rounded-xl border border-separator",
+    wrapperClassName,
+  );
+
+  const imageContent = darkSrc ? (
+    <>
+      <Image
+        alt={alt}
+        className={cn("absolute inset-0 block h-full w-full object-cover dark:hidden", className)}
+        height={height}
+        priority={priority}
+        src={src}
+        width={width}
+      />
+      <Image
+        alt={alt}
+        className={cn("absolute inset-0 hidden h-full w-full object-cover dark:block", className)}
+        height={height}
+        priority={priority}
+        src={darkSrc}
+        width={width}
+      />
+    </>
+  ) : (
+    <Image
+      alt={alt}
+      className={cn("absolute inset-0 h-full w-full object-contain", className)}
+      height={height}
+      priority={priority}
+      src={src}
+      width={width}
+    />
+  );
+
+  if (href) {
+    return (
+      <Link className={wrapperClasses} href={href as unknown as UrlObject}>
+        {imageContent}
+      </Link>
+    );
+  }
+
+  return <div className={wrapperClasses}>{imageContent}</div>;
+}
diff --git a/apps/docs/src/components/external-link.tsx b/apps/docs/src/components/external-link.tsx
new file mode 100644
index 0000000..7e103b6
--- /dev/null
+++ b/apps/docs/src/components/external-link.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import type {LinkProps} from "fumadocs-core/link";
+
+import Link from "fumadocs-core/link";
+import React from "react";
+
+import {LinkIcon} from "@/icons/link";
+
+export interface ExternalLinkProps extends LinkProps {
+  children: React.ReactNode;
+}
+
+export const ExternalLink = React.forwardRef<HTMLAnchorElement, ExternalLinkProps>(
+  ({children, className = "", ...props}, ref) => {
+    return (
+      <Link
+        ref={ref}
+        external
+        className={`hover:text-fd-accent-foreground data-[active=true]:text-fd-primary relative inline-flex items-center gap-1 p-2 text-sm text-muted transition-colors ${className}`}
+        {...props}
+      >
+        {children}
+        <LinkIcon className="absolute top-[8px] right-[-1px] outline-transparent transition-transform outline-solid group-data-[hover=true]:translate-y-0.5 [&>path]:stroke-[2.5px]" />
+      </Link>
+    );
+  },
+);
+
+ExternalLink.displayName = "ExternalLink";
diff --git a/apps/docs/src/components/footer.tsx b/apps/docs/src/components/footer.tsx
new file mode 100644
index 0000000..6f49ca0
--- /dev/null
+++ b/apps/docs/src/components/footer.tsx
@@ -0,0 +1,14 @@
+import type {Dictionary} from "@/lib/dictionaries";
+
+import {SocialLinks} from "@/components/social-links";
+
+export function Footer({dict}: {dict: Dictionary["footer"]}) {
+  return (
+    <footer className="mt-auto flex w-full flex-row flex-wrap items-center justify-center gap-2 py-3 text-muted">
+      <p className="text-sm">
+        &copy; {new Date().getFullYear()} NextUI Inc. {dict.allRightsReserved}
+      </p>
+      <SocialLinks />
+    </footer>
+  );
+}
diff --git a/apps/docs/src/components/framework-chip.tsx b/apps/docs/src/components/framework-chip.tsx
new file mode 100644
index 0000000..3cb013a
--- /dev/null
+++ b/apps/docs/src/components/framework-chip.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Globe, Smartphone} from "@gravity-ui/icons";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+export function FrameworkChip({
+  className,
+  framework = "web",
+}: {
+  className?: string;
+  framework: "web" | "native";
+}) {
+  const dict = useDictionary().frameworksTabs;
+  const isWeb = framework === "web";
+  const Icon = isWeb ? Globe : Smartphone;
+  const frameworkName = isWeb ? dict.web : dict.native;
+  const colorClass = isWeb ? "text-sky-400" : "text-indigo-500";
+
+  return (
+    <span className={cn("flex items-center gap-1", className)}>
+      <Icon className={cn("size-3", colorClass)} />
+      <span className="sr-only">{frameworkName}</span>
+    </span>
+  );
+}
diff --git a/apps/docs/src/components/frameworks-tabs.tsx b/apps/docs/src/components/frameworks-tabs.tsx
new file mode 100644
index 0000000..5a8230d
--- /dev/null
+++ b/apps/docs/src/components/frameworks-tabs.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import type {Framework} from "@/hooks/use-current-framework";
+import type {Key} from "@heroui/react";
+
+import {Globe, Smartphone} from "@gravity-ui/icons";
+import {Tabs} from "@heroui/react";
+import {usePathname, useRouter} from "next/navigation";
+import {useCallback, useEffect, useRef, useState} from "react";
+
+import {getDefaultRoute, useCurrentFramework} from "@/hooks/use-current-framework";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {cn} from "@/utils/cn";
+
+export function FrameworksTabs({className}: {className?: string}) {
+  const dict = useDictionary().frameworksTabs;
+  const pathname = usePathname();
+  const router = useRouter();
+  const isNavigatingRef = useRef(false);
+  const previousPathnameRef = useRef(pathname);
+  const currentFramework = useCurrentFramework();
+
+  const [selectedKey, setSelectedKey] = useState<Framework>(() => {
+    // Initialize based on current pathname
+    return currentFramework;
+  });
+
+  const handleTabChange = useCallback(
+    (key: Key) => {
+      // Convert Key (string | number) to string
+      const keyString = String(key);
+
+      if (keyString !== "web" && keyString !== "native") {
+        return;
+      }
+
+      const targetFramework = keyString as Framework;
+
+      // Don't navigate if already on the target framework
+      if (targetFramework === currentFramework) {
+        return;
+      }
+
+      // Update local state first to trigger animation
+      setSelectedKey(targetFramework);
+      isNavigatingRef.current = true;
+
+      // Navigate to default route for target framework after a short delay to allow animation to play
+      setTimeout(() => {
+        router.push(getDefaultRoute(targetFramework, pathname) as any);
+      }, 150); // Small delay to let animation start
+    },
+    [currentFramework, pathname, router],
+  );
+
+  // Sync selectedKey with pathname changes (e.g., browser back/forward)
+  // Only sync if navigation wasn't initiated by us (to avoid overriding animation)
+  useEffect(() => {
+    // Only update if pathname changed
+    if (previousPathnameRef.current !== pathname) {
+      // If we were navigating, reset the flag now that navigation completed
+      if (isNavigatingRef.current) {
+        isNavigatingRef.current = false;
+      }
+
+      if (currentFramework !== selectedKey) {
+        // eslint-disable-next-line react-hooks/set-state-in-effect
+        setSelectedKey(currentFramework);
+      }
+
+      previousPathnameRef.current = pathname;
+    }
+  }, [pathname, currentFramework, selectedKey]);
+
+  // Spacing lives on the wrapper: since @heroui/styles 3.2.2 the ListContainer
+  // is the visible pill (bg + radius), so padding on it distorts the pill.
+  return (
+    <div className={cn("ml-auto pb-1.5", className)}>
+      <Tabs selectedKey={selectedKey} onSelectionChange={handleTabChange}>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label={dict.ariaLabel}>
+            <Tabs.Tab
+              className="whitespace-nowrap sm:h-6 data-[selected=true]:[&>svg]:text-sky-400"
+              id="web"
+            >
+              <Globe className="mr-1 size-4 shrink-0" />
+              {dict.web}
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab
+              className="whitespace-nowrap sm:h-6 data-[selected=true]:[&>svg]:text-indigo-500"
+              id="native"
+            >
+              <Smartphone className="mr-1 size-4 shrink-0" />
+              {dict.native}
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+      </Tabs>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/client.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/client.tsx
new file mode 100644
index 0000000..1bfba19
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/client.tsx
@@ -0,0 +1,343 @@
+"use client";
+
+import type {LinkItemType, MenuItemType} from "@/components/fumadocs/ui/link-item";
+import type {SidebarTabWithProps} from "fumadocs-ui/components/sidebar/tabs/dropdown";
+import type {ComponentProps, HTMLAttributes, PointerEvent, ReactNode} from "react";
+
+import {ChevronDown} from "@gravity-ui/icons";
+import {usePathname} from "fumadocs-core/framework";
+import Link from "fumadocs-core/link";
+import {useSidebar} from "fumadocs-ui/components/sidebar/base";
+import {SidebarTabsDropdown, isTabActive} from "fumadocs-ui/components/sidebar/tabs/dropdown";
+import {Popover, PopoverContent, PopoverTrigger} from "fumadocs-ui/components/ui/popover";
+import {useIsScrollTop} from "fumadocs-ui/utils/use-is-scroll-top";
+import {Fragment, createContext, useContext, useMemo, useRef, useState} from "react";
+
+import {LinkItem} from "@/components/fumadocs/ui/link-item";
+import {cn} from "@/utils/cn";
+
+export const LayoutContext = createContext<
+  | (LayoutInfo & {
+      isNavTransparent: boolean;
+    })
+  | null
+>(null);
+
+export interface LayoutInfo {
+  tabMode: "sidebar" | "navbar";
+  navMode: "top" | "auto";
+}
+
+export function LayoutContextProvider({
+  children,
+  navMode,
+  navTransparentMode = "none",
+  tabMode,
+}: LayoutInfo & {
+  navTransparentMode?: "always" | "top" | "none";
+  children: ReactNode;
+}) {
+  const isTop = useIsScrollTop({enabled: navTransparentMode === "top"}) ?? true;
+  const isNavTransparent = navTransparentMode === "top" ? isTop : navTransparentMode === "always";
+
+  return (
+    <LayoutContext
+      value={useMemo(
+        () => ({
+          isNavTransparent,
+          navMode,
+          tabMode,
+        }),
+        [isNavTransparent, navMode, tabMode],
+      )}
+    >
+      {children}
+    </LayoutContext>
+  );
+}
+
+export function LayoutHeader(props: ComponentProps<"header">) {
+  const {open} = useSidebar();
+  const context = useContext(LayoutContext);
+  const isNavTransparent = context?.isNavTransparent ?? !open;
+
+  return (
+    <header data-transparent={isNavTransparent} {...props}>
+      {props.children}
+    </header>
+  );
+}
+
+export function LayoutBody({children, className, style, ...props}: ComponentProps<"div">) {
+  const context = useContext(LayoutContext);
+  const navMode = context?.navMode ?? "auto";
+  const {collapsed} = useSidebar();
+
+  const pageCol =
+    "calc(var(--fd-layout-width,97rem) - var(--fd-sidebar-col) - var(--fd-toc-width))";
+
+  return (
+    <div
+      id="nd-notebook-layout"
+      className={cn(
+        "grid min-h-(--fd-docs-height) auto-cols-auto auto-rows-auto overflow-x-clip transition-[grid-template-columns] [--fd-docs-height:100dvh] [--fd-header-height:0px] [--fd-sidebar-width:0px] [--fd-toc-popover-height:0px] [--fd-toc-width:0px]",
+        className,
+      )}
+      style={
+        {
+          "--fd-docs-row-1": "var(--fd-banner-height, 0px)",
+          "--fd-docs-row-2": "calc(var(--fd-docs-row-1) + var(--fd-header-height))",
+          "--fd-docs-row-3": "calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height))",
+          "--fd-sidebar-col": collapsed ? "0px" : "var(--fd-sidebar-width)",
+          gridTemplate:
+            navMode === "top"
+              ? `". header header header ."
+        "sidebar sidebar toc-popover toc-popover ."
+        "sidebar sidebar main toc ." 1fr / minmax(min-content, 1fr) var(--fd-sidebar-col) minmax(0, ${pageCol}) var(--fd-toc-width) minmax(min-content, 1fr)`
+              : `"sidebar sidebar header header ."
+        "sidebar sidebar toc-popover toc-popover ."
+        "sidebar sidebar main toc ." 1fr / minmax(min-content, 1fr) var(--fd-sidebar-col) minmax(0, ${pageCol}) var(--fd-toc-width) minmax(min-content, 1fr)`,
+          ...style,
+        } as React.CSSProperties
+      }
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export type LayoutHeaderTabsProps = ComponentProps<"div"> & {
+  options?: SidebarTabWithProps[];
+  filterByPathname?: boolean;
+};
+
+/**
+ * Path prefix through the docs framework segment.
+ * e.g. "/en/docs/react/getting-started" -> ["en", "docs", "react"]
+ *      "/docs/native/components" -> ["docs", "native"]
+ */
+function getDocsFrameworkPrefix(pathname: string): string[] | null {
+  const segments = pathname.split("/").filter(Boolean);
+  const docsIndex = segments.indexOf("docs");
+
+  if (docsIndex === -1 || segments.length <= docsIndex + 1) {
+    return null;
+  }
+
+  return segments.slice(0, docsIndex + 2);
+}
+
+function prefixesEqual(a: string[], b: string[]): boolean {
+  return a.length === b.length && a.every((segment, index) => segment === b[index]);
+}
+
+/**
+ * Filter tabs to the current docs framework (react vs native).
+ * With i18n, URLs are /{lang}/docs/{framework}/... — comparing only the first two
+ * segments would match every framework tab under the same locale.
+ */
+export function filterTabsByPathname(
+  tabs: SidebarTabWithProps[],
+  pathname: string,
+): SidebarTabWithProps[] {
+  const currentPrefix = getDocsFrameworkPrefix(pathname);
+
+  if (!currentPrefix) {
+    return tabs;
+  }
+
+  return tabs.filter((tab) => {
+    if (!tab.url) {
+      return true;
+    }
+
+    const tabPrefix = getDocsFrameworkPrefix(tab.url);
+
+    if (!tabPrefix) {
+      return true;
+    }
+
+    return prefixesEqual(currentPrefix, tabPrefix);
+  });
+}
+
+/**
+ * Client wrapper for SidebarTabsDropdown that filters tabs based on current pathname
+ */
+export function FilteredSidebarTabsDropdown({
+  filterByPathname = false,
+  options,
+  ...props
+}: ComponentProps<typeof SidebarTabsDropdown> & {filterByPathname?: boolean}) {
+  const pathname = usePathname();
+  const filteredOptions = useMemo(() => {
+    if (!options) return undefined;
+
+    if (!filterByPathname) {
+      return options;
+    }
+
+    return filterTabsByPathname(options, pathname);
+  }, [options, pathname, filterByPathname]);
+
+  if (!filteredOptions || filteredOptions.length === 0) {
+    return null;
+  }
+
+  return <SidebarTabsDropdown {...props} options={filteredOptions} />;
+}
+
+export function LayoutHeaderTabs({
+  children,
+  className,
+  filterByPathname = false,
+  options,
+  ...props
+}: LayoutHeaderTabsProps) {
+  const pathname = usePathname();
+  const filteredOptions = useMemo(() => {
+    if (!options) return undefined;
+
+    if (!filterByPathname) {
+      return options;
+    }
+
+    return filterTabsByPathname(options, pathname);
+  }, [options, pathname, filterByPathname]);
+
+  const selectedIdx = useMemo(() => {
+    return filteredOptions?.findLastIndex((option) => isTabActive(option, pathname));
+  }, [filteredOptions, pathname]);
+
+  return (
+    <div className={cn("flex flex-row items-end gap-6", className)} {...props}>
+      {filteredOptions?.map((option, i) => {
+        const {props: {className, ...rest} = {}, title, unlisted, url} = option;
+        const isSelected = selectedIdx === i;
+
+        return (
+          <Link
+            key={i}
+            href={url}
+            className={cn(
+              "text-fd-muted-foreground hover:text-fd-accent-foreground inline-flex items-center gap-2 border-b-2 border-transparent pb-1.5 text-sm font-medium text-nowrap transition-colors",
+              unlisted && !isSelected && "hidden",
+              isSelected && "border-fd-primary text-fd-primary",
+              className,
+            )}
+            {...rest}
+          >
+            {title}
+          </Link>
+        );
+      })}
+      {children}
+    </div>
+  );
+}
+
+export function NavbarLinkItem({
+  className,
+  item,
+  ...props
+}: {item: LinkItemType} & HTMLAttributes<HTMLElement>) {
+  if (item.type === "custom") return item.children;
+
+  if (item.type === "menu") {
+    return <NavbarLinkItemMenu className={className} item={item} {...props} />;
+  }
+
+  return (
+    <LinkItem
+      item={item}
+      className={cn(
+        "text-fd-muted-foreground hover:text-fd-accent-foreground data-[active=true]:text-fd-foreground text-sm transition-colors",
+        className,
+      )}
+      {...props}
+    >
+      {item.text}
+    </LinkItem>
+  );
+}
+
+function NavbarLinkItemMenu({
+  className,
+  hoverDelay = 50,
+  item,
+  ...props
+}: {item: MenuItemType; hoverDelay?: number} & HTMLAttributes<HTMLElement>) {
+  const [open, setOpen] = useState(false);
+  const timeoutRef = useRef<number>(null);
+  const freezeUntil = useRef<number>(null);
+
+  const delaySetOpen = (value: boolean) => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    timeoutRef.current = window.setTimeout(() => {
+      setOpen(value);
+      freezeUntil.current = Date.now() + 300;
+    }, hoverDelay);
+  };
+  const onPointerEnter = (e: PointerEvent) => {
+    if (e.pointerType === "touch") return;
+    delaySetOpen(true);
+  };
+  const onPointerLeave = (e: PointerEvent) => {
+    if (e.pointerType === "touch") return;
+    delaySetOpen(false);
+  };
+
+  function isTouchDevice() {
+    return "ontouchstart" in window || navigator.maxTouchPoints > 0;
+  }
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(value) => {
+        if (freezeUntil.current === null || Date.now() >= freezeUntil.current) setOpen(value);
+      }}
+    >
+      <PopoverTrigger
+        className={cn(
+          "text-fd-muted-foreground has-data-[active=true]:text-fd-primary data-[state=open]:text-fd-accent-foreground inline-flex items-center gap-1.5 p-1 text-sm transition-colors focus-visible:outline-none",
+          className,
+        )}
+        onPointerEnter={onPointerEnter}
+        onPointerLeave={onPointerLeave}
+        {...props}
+      >
+        {item.url ? <LinkItem item={item as {url: string}}>{item.text}</LinkItem> : item.text}
+        <ChevronDown className="size-3" />
+      </PopoverTrigger>
+      <PopoverContent
+        className="text-fd-muted-foreground flex flex-col p-1 text-start"
+        onPointerEnter={onPointerEnter}
+        onPointerLeave={onPointerLeave}
+      >
+        {item.items.map((child, i) => {
+          if (child.type === "custom") return <Fragment key={i}>{child.children}</Fragment>;
+
+          return (
+            <LinkItem
+              key={i}
+              className="hover:bg-fd-accent hover:text-fd-accent-foreground data-[active=true]:text-fd-primary inline-flex items-center gap-2 rounded-md p-2 transition-colors [&_svg]:size-4"
+              item={child}
+              onClick={() => {
+                if (isTouchDevice()) setOpen(false);
+              }}
+            >
+              {child.icon}
+              {child.text}
+            </LinkItem>
+          );
+        })}
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/index.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/index.tsx
new file mode 100644
index 0000000..583defe
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/index.tsx
@@ -0,0 +1,482 @@
+import type {LayoutHeaderTabsProps} from "./client";
+import type {LinkItemType} from "@/components/fumadocs/ui/link-item";
+import type * as PageTree from "fumadocs-core/page-tree";
+import type {SidebarPageTreeComponents} from "fumadocs-ui/components/sidebar/page-tree";
+import type {GetSidebarTabsOptions} from "fumadocs-ui/components/sidebar/tabs";
+import type {SidebarTabWithProps} from "fumadocs-ui/components/sidebar/tabs/dropdown";
+import type {BaseLayoutProps} from "fumadocs-ui/layouts/shared";
+import type {ComponentProps, FC, HTMLAttributes, ReactNode} from "react";
+
+import Link from "fumadocs-core/link";
+import {getSidebarTabs} from "fumadocs-ui/components/sidebar/tabs";
+import {buttonVariants} from "fumadocs-ui/components/ui/button";
+import {TreeContextProvider} from "fumadocs-ui/contexts/tree";
+import {resolveLinkItems} from "fumadocs-ui/layouts/shared";
+import {useMemo} from "react";
+
+import {Languages, Sidebar as SidebarIcon, X} from "@/components/fumadocs/ui/icons";
+import {LanguageToggle} from "@/components/fumadocs/ui/language-toggle";
+import {LinkItem} from "@/components/fumadocs/ui/link-item";
+import {LargeSearchToggle, SearchToggle} from "@/components/fumadocs/ui/search-toggle";
+import {ThemeToggle} from "@/components/fumadocs/ui/theme-toggle";
+import {cn} from "@/utils/cn";
+
+import {
+  FilteredSidebarTabsDropdown,
+  LayoutBody,
+  LayoutContextProvider,
+  LayoutHeader,
+  LayoutHeaderTabs,
+  NavbarLinkItem,
+} from "./client";
+import {
+  Sidebar,
+  SidebarCollapseTrigger,
+  SidebarContent,
+  SidebarDrawer,
+  SidebarLinkItem,
+  SidebarPageTree,
+  SidebarTrigger,
+  SidebarViewport,
+} from "./sidebar";
+
+export interface DocsLayoutProps extends BaseLayoutProps {
+  tree: PageTree.Root;
+  tabMode?: "sidebar" | "navbar";
+
+  nav?: BaseLayoutProps["nav"] & {
+    mode?: "top" | "auto";
+    titleSuffix?: ReactNode;
+    titleSuffixGap?: string;
+  };
+
+  sidebar?: SidebarOptions;
+
+  containerProps?: HTMLAttributes<HTMLDivElement>;
+}
+
+interface SidebarOptions
+  extends
+    ComponentProps<"aside">,
+    Pick<ComponentProps<typeof Sidebar>, "defaultOpenLevel" | "prefetch"> {
+  components?: Partial<SidebarPageTreeComponents>;
+
+  /**
+   * Root Toggle options
+   */
+  tabs?: SidebarTabWithProps[] | GetSidebarTabsOptions | false;
+
+  headerTabsProps?: LayoutHeaderTabsProps;
+
+  banner?: ReactNode | FC<ComponentProps<"div">>;
+  footer?: ReactNode | FC<ComponentProps<"div">>;
+
+  /**
+   * Support collapsing the sidebar on desktop mode
+   *
+   * @defaultValue true
+   */
+  collapsible?: boolean;
+}
+
+export function DocsLayout(props: DocsLayoutProps) {
+  const {
+    i18n = false,
+    nav = {},
+    sidebar: {defaultOpenLevel, headerTabsProps, prefetch, tabs: tabOptions, ...sidebarProps} = {},
+    tabMode = "sidebar",
+    themeSwitch = {},
+    tree,
+  } = props;
+
+  const navMode = nav.mode ?? "auto";
+  const links = resolveLinkItems(props);
+  const tabs = useMemo(() => {
+    if (Array.isArray(tabOptions)) {
+      return tabOptions;
+    }
+
+    if (typeof tabOptions === "object") {
+      return getSidebarTabs(tree, tabOptions);
+    }
+
+    if (tabOptions !== false) {
+      return getSidebarTabs(tree);
+    }
+
+    return [];
+  }, [tabOptions, tree]);
+
+  function sidebar() {
+    const {banner, collapsible = true, components, footer, ...rest} = sidebarProps;
+
+    const iconLinks = links.filter((item) => item.type === "icon");
+    const Header =
+      typeof banner === "function"
+        ? banner
+        : ({className, ...props}: ComponentProps<"div">) => (
+            <div className={cn("flex flex-col gap-3 p-4 pb-2 empty:hidden", className)} {...props}>
+              {props.children}
+              {banner}
+            </div>
+          );
+    const Footer =
+      typeof footer === "function"
+        ? footer
+        : ({className, ...props}: ComponentProps<"div">) => (
+            <div
+              className={cn(
+                "text-fd-muted-foreground hidden flex-row items-center border-t p-4 pt-2",
+                iconLinks.length > 0 && "max-lg:flex",
+                className,
+              )}
+              {...props}
+            >
+              {props.children}
+              {footer}
+            </div>
+          );
+
+    // Normalize nav.title to ReactNode
+    const titleNode: ReactNode =
+      typeof nav.title === "function"
+        ? (nav.title({} as ComponentProps<"a">) as ReactNode)
+        : nav.title;
+    const viewport = (
+      <SidebarViewport>
+        {links
+          .filter((item) => item.type !== "icon")
+          .map((item, i, arr) => (
+            <SidebarLinkItem
+              key={i}
+              className={cn("lg:hidden", i === arr.length - 1 && "mb-4")}
+              item={item}
+            />
+          ))}
+
+        <SidebarPageTree {...components} />
+      </SidebarViewport>
+    );
+
+    return (
+      <>
+        <SidebarContent {...rest}>
+          <Header>
+            {navMode === "auto" && (
+              <div className="flex justify-between">
+                {nav.titleSuffix ? (
+                  <div className={cn("flex items-center", nav.titleSuffixGap ?? "gap-4")}>
+                    <Link
+                      className="inline-flex items-center gap-2.5 font-medium"
+                      href={nav.url ?? "/"}
+                    >
+                      {titleNode}
+                    </Link>
+                    {nav.titleSuffix}
+                  </div>
+                ) : (
+                  <Link
+                    className="inline-flex items-center gap-2.5 font-medium"
+                    href={nav.url ?? "/"}
+                  >
+                    {titleNode}
+                  </Link>
+                )}
+                {!!collapsible && (
+                  <SidebarCollapseTrigger
+                    className={cn(
+                      buttonVariants({
+                        className: "text-fd-muted-foreground mt-px mb-auto",
+                        color: "ghost",
+                        size: "icon-sm",
+                      }),
+                    )}
+                  >
+                    <SidebarIcon />
+                  </SidebarCollapseTrigger>
+                )}
+              </div>
+            )}
+            {nav.children}
+            {tabs.length > 0 && (
+              <FilteredSidebarTabsDropdown
+                className={cn(tabMode === "navbar" && "lg:hidden")}
+                filterByPathname={headerTabsProps?.filterByPathname}
+                options={tabs}
+              />
+            )}
+          </Header>
+          {viewport}
+          <Footer>
+            {iconLinks.map((item, i) => (
+              <LinkItem
+                key={i}
+                aria-label={item.label}
+                item={item}
+                className={cn(
+                  buttonVariants({
+                    className: "lg:hidden",
+                    color: "ghost",
+                    size: "icon-sm",
+                  }),
+                )}
+              >
+                {item.icon}
+              </LinkItem>
+            ))}
+          </Footer>
+        </SidebarContent>
+        <SidebarDrawer {...rest}>
+          <Header>
+            <SidebarTrigger
+              className={cn(
+                buttonVariants({
+                  className: "text-fd-muted-foreground ms-auto",
+                  color: "ghost",
+                  size: "icon-sm",
+                }),
+              )}
+            >
+              <X />
+            </SidebarTrigger>
+            {tabs.length > 0 && (
+              <FilteredSidebarTabsDropdown
+                filterByPathname={headerTabsProps?.filterByPathname}
+                options={tabs}
+              />
+            )}
+          </Header>
+          {viewport}
+          <Footer
+            className={cn(
+              "hidden flex-row items-center justify-end",
+              (i18n || themeSwitch.enabled !== false) && "flex",
+              iconLinks.length > 0 && "max-lg:flex",
+            )}
+          >
+            {iconLinks.map((item, i) => (
+              <LinkItem
+                key={i}
+                aria-label={item.label}
+                item={item}
+                className={cn(
+                  buttonVariants({
+                    color: "ghost",
+                    size: "icon-sm",
+                  }),
+                  "text-fd-muted-foreground lg:hidden",
+                  i === iconLinks.length - 1 && "me-auto",
+                )}
+              >
+                {item.icon}
+              </LinkItem>
+            ))}
+            {!!i18n && (
+              <LanguageToggle>
+                <Languages className="text-fd-muted-foreground size-4" />
+              </LanguageToggle>
+            )}
+            {themeSwitch.enabled !== false &&
+              (themeSwitch.component ?? (
+                <ThemeToggle mode={themeSwitch.mode ?? "light-dark-system"} />
+              ))}
+          </Footer>
+        </SidebarDrawer>
+      </>
+    );
+  }
+
+  return (
+    <TreeContextProvider tree={tree}>
+      <LayoutContextProvider
+        navMode={nav.mode ?? "auto"}
+        navTransparentMode={nav.transparentMode}
+        tabMode={tabMode}
+      >
+        <Sidebar defaultOpenLevel={defaultOpenLevel} prefetch={prefetch}>
+          <LayoutBody {...props.containerProps}>
+            {sidebar()}
+            <DocsNavbar {...props} headerTabsProps={headerTabsProps} links={links} tabs={tabs} />
+            {props.children}
+          </LayoutBody>
+        </Sidebar>
+      </LayoutContextProvider>
+    </TreeContextProvider>
+  );
+}
+
+function DocsNavbar({
+  headerTabsProps,
+  i18n,
+  links,
+  nav = {},
+  searchToggle = {},
+  sidebar: {collapsible: sidebarCollapsible = true} = {},
+  tabMode = "sidebar",
+  tabs,
+  themeSwitch = {},
+}: DocsLayoutProps & {
+  headerTabsProps?: LayoutHeaderTabsProps;
+  links: LinkItemType[];
+  tabs: SidebarTabWithProps[];
+}) {
+  const navMode = nav.mode ?? "auto";
+  const showLayoutTabs = tabMode === "navbar" && tabs.length > 0;
+
+  // Normalize nav.title to ReactNode
+  const titleNode: ReactNode =
+    typeof nav.title === "function"
+      ? (nav.title({} as ComponentProps<"a">) as ReactNode)
+      : nav.title;
+
+  return (
+    <LayoutHeader
+      id="nd-subnav"
+      className={cn(
+        "data-[transparent=false]:bg-fd-background/80 layout:[--fd-header-height:--spacing(23)] sticky top-(--fd-docs-row-1) z-10 flex flex-col backdrop-blur-sm transition-colors [grid-area:header]",
+        showLayoutTabs && "md:layout:[--fd-header-height:--spacing(25)]",
+      )}
+    >
+      <div className="flex h-14 gap-2 border-b px-4 md:px-6" data-header-body="">
+        <div
+          className={cn(
+            "items-center",
+            navMode === "top" && "flex flex-1",
+            navMode === "auto" && "hidden max-md:flex has-data-[collapsed=true]:md:flex",
+          )}
+        >
+          {!!sidebarCollapsible && navMode === "auto" && (
+            <SidebarCollapseTrigger
+              className={cn(
+                buttonVariants({
+                  color: "ghost",
+                  size: "icon-sm",
+                }),
+                "text-fd-muted-foreground data-[collapsed=false]:hidden max-md:hidden",
+              )}
+            >
+              <SidebarIcon />
+            </SidebarCollapseTrigger>
+          )}
+          {nav.titleSuffix ? (
+            <div className={cn("flex items-center", nav.titleSuffixGap ?? "gap-4")}>
+              <Link
+                href={nav.url ?? "/"}
+                className={cn(
+                  "inline-flex items-center gap-2.5 font-semibold",
+                  navMode === "auto" && "md:hidden",
+                )}
+              >
+                {titleNode}
+              </Link>
+              {nav.titleSuffix}
+            </div>
+          ) : (
+            <Link
+              href={nav.url ?? "/"}
+              className={cn(
+                "inline-flex items-center gap-2.5 font-semibold",
+                navMode === "auto" && "md:hidden",
+              )}
+            >
+              {titleNode}
+            </Link>
+          )}
+        </div>
+        {searchToggle.enabled !== false &&
+          (searchToggle.components?.lg ? (
+            <div
+              className={cn(
+                "my-auto w-full max-md:hidden",
+                navMode === "top" ? "max-w-sm rounded-xl" : "max-w-[240px]",
+              )}
+            >
+              {searchToggle.components.lg}
+            </div>
+          ) : (
+            <LargeSearchToggle
+              hideIfDisabled
+              className={cn(
+                "my-auto w-full max-md:hidden",
+                navMode === "top" ? "max-w-sm rounded-xl ps-2.5" : "max-w-[240px]",
+              )}
+            />
+          ))}
+        <div className="flex flex-1 items-center justify-end md:gap-2">
+          <div className="flex items-center gap-6 empty:hidden max-lg:hidden">
+            {links
+              .filter((item) => item.type !== "icon")
+              .map((item, i) => (
+                <NavbarLinkItem key={i} item={item} />
+              ))}
+          </div>
+          {nav.children}
+          {links
+            .filter((item) => item.type === "icon")
+            .map((item, i) => (
+              <LinkItem
+                key={i}
+                aria-label={item.label}
+                item={item}
+                className={cn(
+                  buttonVariants({color: "ghost", size: "icon-sm"}),
+                  "text-fd-muted-foreground max-lg:hidden",
+                )}
+              >
+                {item.icon}
+              </LinkItem>
+            ))}
+
+          <div className="flex items-center md:hidden">
+            {searchToggle.enabled !== false &&
+              (searchToggle.components?.sm ?? <SearchToggle hideIfDisabled className="p-2" />)}
+            <SidebarTrigger
+              className={cn(
+                buttonVariants({
+                  className: "-me-1.5 p-2",
+                  color: "ghost",
+                  size: "icon-sm",
+                }),
+              )}
+            >
+              <SidebarIcon />
+            </SidebarTrigger>
+          </div>
+
+          <div className="flex items-center gap-2 max-md:hidden">
+            {!!i18n && (
+              <LanguageToggle>
+                <Languages className="text-fd-muted-foreground size-4" />
+              </LanguageToggle>
+            )}
+            {themeSwitch.enabled !== false &&
+              (themeSwitch.component ?? (
+                <ThemeToggle mode={themeSwitch.mode ?? "light-dark-system"} />
+              ))}
+            {!!sidebarCollapsible && navMode === "top" && (
+              <SidebarCollapseTrigger
+                className={cn(
+                  buttonVariants({
+                    color: "secondary",
+                    size: "icon-sm",
+                  }),
+                  "text-fd-muted-foreground -me-1.5 rounded-full",
+                )}
+              >
+                <SidebarIcon />
+              </SidebarCollapseTrigger>
+            )}
+          </div>
+        </div>
+      </div>
+      {!!showLayoutTabs && (
+        <LayoutHeaderTabs
+          className={cn("h-10 overflow-x-auto border-b px-6", headerTabsProps?.className)}
+          data-header-tabs=""
+          {...headerTabsProps}
+          options={tabs}
+        />
+      )}
+    </LayoutHeader>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/page/client.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/page/client.tsx
new file mode 100644
index 0000000..e6e32db
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/page/client.tsx
@@ -0,0 +1,351 @@
+"use client";
+
+import type {BreadcrumbOptions} from "fumadocs-core/breadcrumb";
+import type * as PageTree from "fumadocs-core/page-tree";
+import type {ComponentProps} from "react";
+
+import {ChevronDown, ChevronLeft, ChevronRight} from "@gravity-ui/icons";
+import {getBreadcrumbItemsFromPath} from "fumadocs-core/breadcrumb";
+import {usePathname} from "fumadocs-core/framework";
+import Link from "fumadocs-core/link";
+import {useActiveAnchor} from "fumadocs-core/toc";
+import {useTOCItems} from "fumadocs-ui/components/toc";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "fumadocs-ui/components/ui/collapsible";
+import {useI18n} from "fumadocs-ui/contexts/i18n";
+import {useTreeContext, useTreePath} from "fumadocs-ui/contexts/tree";
+import {useFooterItems} from "fumadocs-ui/utils/use-footer-items";
+import {
+  Fragment,
+  createContext,
+  use,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import {isActive} from "@/components/fumadocs/utils/urls";
+import {cn} from "@/utils/cn";
+
+import {LayoutContext} from "../client";
+
+const TocPopoverContext = createContext<{
+  open: boolean;
+  setOpen: (open: boolean) => void;
+} | null>(null);
+
+export function PageTOCPopover({children, className, ...rest}: ComponentProps<"div">) {
+  const ref = useRef<HTMLElement>(null);
+  const [open, setOpen] = useState(false);
+  const {isNavTransparent} = use(LayoutContext)!;
+
+  const onClick = useEffectEvent((e: Event) => {
+    if (!open) return;
+
+    if (ref.current && !ref.current.contains(e.target as HTMLElement)) setOpen(false);
+  });
+
+  useEffect(() => {
+    window.addEventListener("click", onClick);
+
+    return () => {
+      window.removeEventListener("click", onClick);
+    };
+  }, []);
+
+  return (
+    <TocPopoverContext
+      value={useMemo(
+        () => ({
+          open,
+          setOpen,
+        }),
+        [setOpen, open],
+      )}
+    >
+      <Collapsible
+        data-toc-popover=""
+        open={open}
+        className={cn(
+          "max-xl:layout:[--fd-toc-popover-height:--spacing(10)] sticky top-(--fd-docs-row-2) z-10 h-(--fd-toc-popover-height) [grid-area:toc-popover] xl:hidden",
+          className,
+        )}
+        onOpenChange={setOpen}
+        {...rest}
+      >
+        <header
+          ref={ref}
+          className={cn(
+            "border-b backdrop-blur-sm transition-colors",
+            (!isNavTransparent || open) && "bg-fd-background/80",
+            open && "shadow-lg",
+          )}
+        >
+          {children}
+        </header>
+      </Collapsible>
+    </TocPopoverContext>
+  );
+}
+
+export function PageTOCPopoverTrigger({className, ...props}: ComponentProps<"button">) {
+  const {text} = useI18n();
+  const {open} = use(TocPopoverContext)!;
+  const items = useTOCItems();
+  const active = useActiveAnchor();
+  const selected = useMemo(
+    () => items.findIndex((item) => active === item.url.slice(1)),
+    [items, active],
+  );
+  const path = useTreePath().at(-1);
+  const showItem = selected !== -1 && !open;
+
+  return (
+    <CollapsibleTrigger
+      data-toc-popover-trigger=""
+      className={cn(
+        "text-fd-muted-foreground flex h-10 w-full items-center gap-2.5 px-4 py-2.5 text-start text-sm focus-visible:outline-none md:px-6 [&_svg]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      <ProgressCircle
+        className={cn("shrink-0", open && "text-fd-primary")}
+        max={1}
+        value={(selected + 1) / Math.max(1, items.length)}
+      />
+      <span className="grid flex-1 *:col-start-1 *:row-start-1 *:my-auto">
+        <span
+          className={cn(
+            "truncate transition-all",
+            open && "text-fd-foreground",
+            showItem && "pointer-events-none -translate-y-full opacity-0",
+          )}
+        >
+          {path?.name ?? text.toc}
+        </span>
+        <span
+          className={cn(
+            "truncate transition-all",
+            !showItem && "pointer-events-none translate-y-full opacity-0",
+          )}
+        >
+          {items[selected]?.title}
+        </span>
+      </span>
+      <ChevronDown className={cn("mx-0.5 shrink-0 transition-transform", open && "rotate-180")} />
+    </CollapsibleTrigger>
+  );
+}
+
+interface ProgressCircleProps extends Omit<React.ComponentProps<"svg">, "strokeWidth"> {
+  value: number;
+  strokeWidth?: number;
+  size?: number;
+  min?: number;
+  max?: number;
+}
+
+function clamp(input: number, min: number, max: number): number {
+  if (input < min) return min;
+  if (input > max) return max;
+
+  return input;
+}
+
+function ProgressCircle({
+  max = 100,
+  min = 0,
+  size = 24,
+  strokeWidth = 2,
+  value,
+  ...restSvgProps
+}: ProgressCircleProps) {
+  const normalizedValue = clamp(value, min, max);
+  const radius = (size - strokeWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const progress = (normalizedValue / max) * circumference;
+  const circleProps = {
+    cx: size / 2,
+    cy: size / 2,
+    fill: "none",
+    r: radius,
+    strokeWidth,
+  };
+
+  return (
+    <svg
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={normalizedValue}
+      role="progressbar"
+      viewBox={`0 0 ${size} ${size}`}
+      {...restSvgProps}
+    >
+      <circle {...circleProps} className="stroke-current/25" />
+      <circle
+        {...circleProps}
+        className="transition-all"
+        stroke="currentColor"
+        strokeDasharray={circumference}
+        strokeDashoffset={circumference - progress}
+        strokeLinecap="round"
+        transform={`rotate(-90 ${size / 2} ${size / 2})`}
+      />
+    </svg>
+  );
+}
+
+export function PageTOCPopoverContent(props: ComponentProps<"div">) {
+  return (
+    <CollapsibleContent
+      data-toc-popover-content=""
+      {...props}
+      className={cn("flex max-h-[50vh] flex-col px-4 md:px-6", props.className)}
+    >
+      {props.children}
+    </CollapsibleContent>
+  );
+}
+
+export function PageLastUpdate({
+  date: value,
+  ...props
+}: Omit<ComponentProps<"p">, "children"> & {date: Date}) {
+  const {text} = useI18n();
+  const [date, setDate] = useState("");
+
+  useEffect(() => {
+    // to the timezone of client
+    setDate(value.toLocaleDateString());
+  }, [value]);
+
+  return (
+    <p {...props} className={cn("text-fd-muted-foreground text-sm", props.className)}>
+      {text.lastUpdate} {date}
+    </p>
+  );
+}
+
+type Item = Pick<PageTree.Item, "name" | "description" | "url">;
+export interface FooterProps extends ComponentProps<"div"> {
+  /**
+   * Items including information for the next and previous page
+   */
+  items?: {
+    previous?: Item;
+    next?: Item;
+  };
+}
+
+export function PageFooter({items, ...props}: FooterProps) {
+  const footerList = useFooterItems();
+  const pathname = usePathname();
+  const {next, previous} = useMemo(() => {
+    if (items) return items;
+
+    const idx = footerList.findIndex((item) => isActive(item.url, pathname, false));
+
+    if (idx === -1) return {};
+
+    return {
+      next: footerList[idx + 1],
+      previous: footerList[idx - 1],
+    };
+  }, [footerList, items, pathname]);
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        "@container my-8 grid gap-4",
+        previous && next ? "grid-cols-2" : "grid-cols-1",
+        props.className,
+      )}
+    >
+      {previous ? <FooterItem index={0} item={previous} /> : null}
+      {next ? <FooterItem index={1} item={next} /> : null}
+    </div>
+  );
+}
+
+function FooterItem({index, item}: {item: Item; index: 0 | 1}) {
+  const {text} = useI18n();
+  const Icon = index === 0 ? ChevronLeft : ChevronRight;
+
+  return (
+    <Link
+      href={item.url}
+      className={cn(
+        "hover:text-fd-accent-foreground flex flex-col gap-2 rounded-2xl p-4 text-sm transition-none hover:bg-surface-secondary @max-lg:col-span-full",
+        index === 1 && "text-end",
+      )}
+    >
+      <div
+        className={cn(
+          "inline-flex items-center gap-1.5 font-medium",
+          index === 1 && "flex-row-reverse",
+        )}
+      >
+        <Icon className="-mx-1 size-4 shrink-0 rtl:rotate-180" />
+        <p>{item.name}</p>
+      </div>
+      <p className="text-fd-muted-foreground truncate">
+        {item.description ?? (index === 0 ? text.previousPage : text.nextPage)}
+      </p>
+    </Link>
+  );
+}
+
+export type BreadcrumbProps = BreadcrumbOptions & ComponentProps<"div">;
+
+export function PageBreadcrumb({
+  includePage,
+  includeRoot,
+  includeSeparator,
+  ...props
+}: BreadcrumbProps) {
+  const path = useTreePath();
+  const {root} = useTreeContext();
+  const items = useMemo(() => {
+    return getBreadcrumbItemsFromPath(root, path, {
+      includePage,
+      includeRoot,
+      includeSeparator,
+    });
+  }, [includePage, includeRoot, includeSeparator, path, root]);
+
+  if (items.length === 0) return null;
+
+  return (
+    <div
+      {...props}
+      className={cn("text-fd-muted-foreground flex items-center gap-1.5 text-sm", props.className)}
+    >
+      {items.map((item, i) => {
+        const className = cn("truncate", i === items.length - 1 && "text-fd-primary font-medium");
+
+        return (
+          <Fragment key={i}>
+            {i !== 0 && <ChevronRight className="size-3.5 shrink-0" />}
+            {item.url ? (
+              <Link
+                className={cn(className, "transition-opacity hover:opacity-80")}
+                href={item.url}
+              >
+                {item.name}
+              </Link>
+            ) : (
+              <span className={className}>{item.name}</span>
+            )}
+          </Fragment>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/page/index.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/page/index.tsx
new file mode 100644
index 0000000..936de8f
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/page/index.tsx
@@ -0,0 +1,216 @@
+import type {BreadcrumbProps, FooterProps} from "./client";
+import type {AnchorProviderProps, TOCItemType} from "fumadocs-core/toc";
+import type {ComponentProps, ReactNode} from "react";
+
+import {TOCProvider, TOCScrollArea} from "fumadocs-ui/components/toc";
+import {buttonVariants} from "fumadocs-ui/components/ui/button";
+import {I18nLabel} from "fumadocs-ui/contexts/i18n";
+
+import {Edit, Text} from "@/components/fumadocs/ui/icons";
+import {cn} from "@/utils/cn";
+
+import {
+  PageBreadcrumb,
+  PageFooter,
+  PageTOCPopover,
+  PageTOCPopoverContent,
+  PageTOCPopoverTrigger,
+} from "./client";
+import {TOCItems} from "./toc-items";
+
+interface BreadcrumbOptions extends BreadcrumbProps {
+  enabled: boolean;
+  component: ReactNode;
+}
+
+interface FooterOptions extends FooterProps {
+  enabled: boolean;
+  component: ReactNode;
+}
+
+export interface DocsPageProps {
+  toc?: TOCItemType[];
+  tableOfContent?: Partial<TableOfContentOptions>;
+  tableOfContentPopover?: Partial<TableOfContentPopoverOptions>;
+
+  /**
+   * Extend the page to fill all available space
+   *
+   * @defaultValue false
+   */
+  full?: boolean;
+
+  /**
+   * Replace or disable breadcrumb
+   */
+  breadcrumb?: Partial<BreadcrumbOptions>;
+
+  /**
+   * Footer navigation, you can disable it by passing `false`
+   */
+  footer?: Partial<FooterOptions>;
+
+  children?: ReactNode;
+}
+
+type TableOfContentOptions = Pick<AnchorProviderProps, "single"> & {
+  /**
+   * Custom content in TOC container, before the main TOC
+   */
+  header?: ReactNode;
+
+  /**
+   * Custom content in TOC container, after the main TOC
+   */
+  footer?: ReactNode;
+
+  enabled: boolean;
+  component: ReactNode;
+
+  /**
+   * @defaultValue 'normal'
+   */
+  style?: "normal" | "clerk";
+};
+
+type TableOfContentPopoverOptions = Omit<TableOfContentOptions, "single">;
+
+export function DocsPage({
+  breadcrumb: {component: breadcrumb, enabled: breadcrumbEnabled = true, ...breadcrumbProps} = {},
+  children,
+  footer = {},
+  full = false,
+  tableOfContent: {component: tocReplace, enabled: tocEnabled, ...tocOptions} = {},
+  tableOfContentPopover: {
+    component: tocPopover,
+    enabled: tocPopoverEnabled,
+    ...tocPopoverOptions
+  } = {},
+  toc = [],
+}: DocsPageProps) {
+  // disable TOC on full mode, you can still enable it with `enabled` option.
+  tocEnabled ??=
+    !full && (toc.length > 0 || tocOptions.footer !== undefined || tocOptions.header !== undefined);
+
+  tocPopoverEnabled ??=
+    toc.length > 0 ||
+    tocPopoverOptions.header !== undefined ||
+    tocPopoverOptions.footer !== undefined;
+
+  let wrapper = (children: ReactNode) => children;
+
+  if (tocEnabled || tocPopoverEnabled) {
+    wrapper = (children) => (
+      <TOCProvider single={tocOptions.single} toc={toc}>
+        {children}
+      </TOCProvider>
+    );
+  }
+
+  return wrapper(
+    <>
+      {!!tocPopoverEnabled &&
+        (tocPopover ?? (
+          <PageTOCPopover>
+            <PageTOCPopoverTrigger />
+            <PageTOCPopoverContent>
+              {tocPopoverOptions.header}
+              <TOCScrollArea>
+                <TOCItems />
+              </TOCScrollArea>
+              {tocPopoverOptions.footer}
+            </PageTOCPopoverContent>
+          </PageTOCPopover>
+        ))}
+      <article
+        data-full={full}
+        id="nd-page"
+        className={cn(
+          "flex flex-col gap-4 px-4 py-6 [grid-area:main] *:max-w-[900px] md:px-6 md:pt-8 xl:px-8 xl:pt-14",
+          full && "*:max-w-[1285px]",
+        )}
+      >
+        {!!breadcrumbEnabled && (breadcrumb ?? <PageBreadcrumb {...breadcrumbProps} />)}
+        {children}
+        {footer.enabled !== false && (footer.component ?? <PageFooter items={footer.items} />)}
+      </article>
+      {!!tocEnabled &&
+        (tocReplace ?? (
+          <div
+            className="xl:layout:[--fd-toc-width:268px] sticky top-(--fd-docs-row-3) flex h-[calc(var(--fd-docs-height)-var(--fd-docs-row-3))] w-(--fd-toc-width) flex-col pe-4 pt-12 pb-2 [grid-area:toc] max-xl:hidden"
+            id="nd-toc"
+          >
+            {tocOptions.header}
+            <h3
+              className="text-fd-muted-foreground inline-flex items-center gap-1.5 text-sm"
+              id="toc-title"
+            >
+              <Text className="size-4" />
+              <I18nLabel label="toc" />
+            </h3>
+            <TOCScrollArea>
+              <TOCItems />
+            </TOCScrollArea>
+            {tocOptions.footer}
+          </div>
+        ))}
+    </>,
+  );
+}
+
+export function EditOnGitHub(props: ComponentProps<"a">) {
+  return (
+    <a
+      rel="noreferrer noopener"
+      target="_blank"
+      {...props}
+      className={cn(
+        buttonVariants({
+          className: "not-prose gap-1.5",
+          color: "secondary",
+          size: "sm",
+        }),
+        props.className,
+      )}
+    >
+      {props.children ?? (
+        <>
+          <Edit className="size-3.5" />
+          <I18nLabel label="editOnGithub" />
+        </>
+      )}
+    </a>
+  );
+}
+
+/**
+ * Add typography styles
+ */
+export function DocsBody({children, className, ...props}: ComponentProps<"div">) {
+  return (
+    <div {...props} className={cn("prose flex-1", className)}>
+      {children}
+    </div>
+  );
+}
+
+export function DocsDescription({children, className, ...props}: ComponentProps<"p">) {
+  // Don't render if no description provided
+  if (children === undefined) return null;
+
+  return (
+    <p {...props} className={cn("text-fd-muted-foreground mb-8 text-lg", className)}>
+      {children}
+    </p>
+  );
+}
+
+export function DocsTitle({children, className, ...props}: ComponentProps<"h1">) {
+  return (
+    <h1 {...props} className={cn("text-[1.75em] font-semibold", className)}>
+      {children}
+    </h1>
+  );
+}
+
+export {PageLastUpdate, PageBreadcrumb} from "./client";
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/page/toc-items.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/page/toc-items.tsx
new file mode 100644
index 0000000..8eb8512
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/page/toc-items.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import type {TOCItemType} from "fumadocs-core/toc";
+import type {ComponentProps, RefObject} from "react";
+
+import * as Primitive from "fumadocs-core/toc";
+import {useTOCItems} from "fumadocs-ui/components/toc";
+import {useCallback, useEffect, useRef} from "react";
+
+import {mergeRefs} from "@/components/fumadocs/utils/merge-refs";
+import {cn} from "@/utils/cn";
+
+function calc(container: HTMLElement, active: string[]): [number, number] {
+  if (active.length === 0 || container.clientHeight === 0) return [0, 0];
+
+  let upper = Number.MAX_VALUE;
+  let lower = 0;
+
+  for (const id of active) {
+    const element =
+      container.querySelector<HTMLElement>(`a[href="#${id}"]`) ??
+      container.querySelector<HTMLElement>(`a[href="#${encodeURIComponent(id)}"]`);
+
+    if (!element) continue;
+
+    const styles = getComputedStyle(element);
+
+    upper = Math.min(upper, element.offsetTop + parseFloat(styles.paddingTop));
+    lower = Math.max(
+      lower,
+      element.offsetTop + element.clientHeight - parseFloat(styles.paddingBottom),
+    );
+  }
+
+  if (upper === Number.MAX_VALUE) return [0, 0];
+
+  return [upper, lower - upper];
+}
+
+function TocThumb({containerRef}: {containerRef: RefObject<HTMLDivElement | null>}) {
+  const thumbRef = useRef<HTMLDivElement>(null);
+  const active = Primitive.useActiveAnchors();
+
+  const update = useCallback(() => {
+    const thumb = thumbRef.current;
+    const container = containerRef.current;
+
+    if (!thumb || !container) return;
+
+    const [top, height] = calc(container, active);
+
+    thumb.style.setProperty("--fd-top", `${top}px`);
+    thumb.style.setProperty("--fd-height", `${height}px`);
+  }, [active, containerRef]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+
+    if (!container) return;
+
+    const observer = new ResizeObserver(update);
+
+    observer.observe(container);
+    update();
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [update, containerRef]);
+
+  return (
+    <div
+      ref={thumbRef}
+      className="bg-fd-primary absolute inset-s-0 top-(--fd-top) h-(--fd-height) w-px transition-[top,height] ease-linear data-[hidden=true]:opacity-0"
+      data-hidden={active.length === 0}
+    />
+  );
+}
+
+function TOCItem({item}: {item: TOCItemType}) {
+  return (
+    <Primitive.TOCItem
+      href={item.url}
+      className={cn(
+        "prose text-fd-muted-foreground hover:text-fd-accent-foreground data-[active=true]:text-fd-primary scroll-m-4 py-1.5 text-sm wrap-anywhere transition-colors first:pt-0 last:pb-0",
+        item.depth <= 2 && "ps-3",
+        item.depth === 3 && "ps-6",
+        item.depth >= 4 && "ps-8",
+      )}
+    >
+      {item.title}
+    </Primitive.TOCItem>
+  );
+}
+
+export type TOCItemsProps = ComponentProps<"div">;
+
+export function TOCItems({className, ref, ...props}: TOCItemsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const items = useTOCItems();
+
+  if (items.length === 0) return null;
+
+  return (
+    <div className="relative">
+      <TocThumb containerRef={containerRef} />
+      <div
+        ref={mergeRefs(ref, containerRef)}
+        className={cn("border-fd-foreground/10 flex flex-col border-s", className)}
+        {...props}
+      >
+        {items.map((item) => (
+          <TOCItem key={item.url} item={item} />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/layouts/notebook/sidebar.tsx b/apps/docs/src/components/fumadocs/layouts/notebook/sidebar.tsx
new file mode 100644
index 0000000..9e14b8c
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/layouts/notebook/sidebar.tsx
@@ -0,0 +1,238 @@
+"use client";
+
+import type {ComponentProps} from "react";
+
+import * as Base from "fumadocs-ui/components/sidebar/base";
+import {createLinkItemRenderer} from "fumadocs-ui/components/sidebar/link-item";
+import {createPageTreeRenderer} from "fumadocs-ui/components/sidebar/page-tree";
+import {useContext, useRef} from "react";
+import {tv} from "tailwind-variants";
+
+import {mergeRefs} from "@/components/fumadocs/utils/merge-refs";
+import {cn} from "@/utils/cn";
+
+import {LayoutContext} from "./client";
+
+const itemVariants = tv({
+  base: "text-fd-muted-foreground relative flex flex-row items-center gap-2 rounded-lg p-2 text-start [&_svg]:size-4 [&_svg]:shrink-0",
+  variants: {
+    highlight: {
+      true: "data-[active=true]:before:bg-fd-primary data-[active=true]:before:absolute data-[active=true]:before:inset-y-2.5 data-[active=true]:before:start-2.5 data-[active=true]:before:w-px data-[active=true]:before:content-['']",
+    },
+    variant: {
+      button:
+        "hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 transition-colors hover:transition-none",
+      link: "hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 data-[active=true]:bg-fd-primary/10 data-[active=true]:text-fd-primary transition-colors hover:transition-none data-[active=true]:hover:transition-colors",
+    },
+  },
+});
+
+function getItemOffset(depth: number) {
+  return `calc(${2 + 3 * depth} * var(--spacing))`;
+}
+
+export const {
+  SidebarCollapseTrigger,
+  SidebarFolder,
+  SidebarProvider: Sidebar,
+  SidebarTrigger,
+  SidebarViewport,
+} = Base;
+
+export function SidebarContent({
+  children,
+  className,
+  ref: refProp,
+  ...props
+}: ComponentProps<"aside">) {
+  const context = useContext(LayoutContext);
+  const navMode = context?.navMode ?? "auto";
+
+  const ref = useRef<HTMLElement>(null);
+
+  return (
+    <Base.SidebarContent>
+      {({collapsed, hovered, ref: asideRef, ...rest}) => (
+        <div
+          data-sidebar-placeholder=""
+          className={cn(
+            "md:layout:[--fd-sidebar-width:268px] pointer-events-none sticky z-20 [grid-area:sidebar] *:pointer-events-auto max-md:hidden",
+            navMode === "auto"
+              ? "top-(--fd-docs-row-1) h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))]"
+              : "top-(--fd-docs-row-2) h-[calc(var(--fd-docs-height)-var(--fd-docs-row-2))]",
+          )}
+        >
+          {!!collapsed && <div className="absolute inset-y-0 start-0 w-4" {...rest} />}
+          <aside
+            ref={mergeRefs(ref, refProp, asideRef)}
+            data-collapsed={collapsed}
+            data-hovered={!!collapsed && hovered}
+            id="nd-sidebar"
+            className={cn(
+              "absolute inset-y-0 start-0 flex w-full flex-col items-end text-sm duration-250 *:w-(--fd-sidebar-width)",
+              navMode === "auto" && "bg-fd-card border-e",
+              collapsed && [
+                "bg-fd-card inset-y-2 w-(--fd-sidebar-width) rounded-xl border transition-transform",
+                hovered
+                  ? "translate-x-2 shadow-lg rtl:-translate-x-2"
+                  : "-translate-x-(--fd-sidebar-width) rtl:translate-x-full",
+              ],
+              ref.current &&
+                (ref.current.getAttribute("data-collapsed") === "true") !== collapsed &&
+                "transition-[width,inset-block,translate,background-color]",
+              className,
+            )}
+            {...props}
+            {...rest}
+          >
+            {children}
+          </aside>
+        </div>
+      )}
+    </Base.SidebarContent>
+  );
+}
+
+export function SidebarDrawer({
+  children,
+  className,
+  ...props
+}: ComponentProps<typeof Base.SidebarDrawerContent>) {
+  return (
+    <>
+      <Base.SidebarDrawerOverlay className="data-[state=open]:animate-fd-fade-in data-[state=closed]:animate-fd-fade-out fixed inset-0 z-40 backdrop-blur-xs" />
+      <Base.SidebarDrawerContent
+        className={cn(
+          "bg-fd-background data-[state=open]:animate-fd-sidebar-in data-[state=closed]:animate-fd-sidebar-out fixed inset-y-0 end-0 z-40 flex w-[85%] max-w-[380px] flex-col text-[0.9375rem] shadow-lg",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </Base.SidebarDrawerContent>
+    </>
+  );
+}
+
+export function SidebarSeparator({children, className, style, ...props}: ComponentProps<"p">) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarSeparator
+      className={cn("[&_svg]:size-4 [&_svg]:shrink-0", className)}
+      style={{
+        paddingInlineStart: getItemOffset(depth),
+        ...style,
+      }}
+      {...props}
+    >
+      {children}
+    </Base.SidebarSeparator>
+  );
+}
+
+export function SidebarItem({
+  children,
+  className,
+  style,
+  ...props
+}: ComponentProps<typeof Base.SidebarItem>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarItem
+      className={cn(itemVariants({highlight: depth >= 1, variant: "link"}), className)}
+      style={{
+        paddingInlineStart: getItemOffset(depth),
+        ...style,
+      }}
+      {...props}
+    >
+      {children}
+    </Base.SidebarItem>
+  );
+}
+
+export function SidebarFolderTrigger({
+  className,
+  style,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderTrigger>) {
+  const {collapsible, depth} = Base.useFolder()!;
+
+  return (
+    <Base.SidebarFolderTrigger
+      className={itemVariants({
+        class: `w-full ${className}`,
+        variant: collapsible ? "button" : undefined,
+      })}
+      style={{
+        paddingInlineStart: getItemOffset(depth - 1),
+        ...style,
+      }}
+      {...props}
+    >
+      {props.children}
+    </Base.SidebarFolderTrigger>
+  );
+}
+
+export function SidebarFolderLink({
+  className,
+  style,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderLink>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarFolderLink
+      className={cn(itemVariants({highlight: depth > 1, variant: "link"}), "w-full", className)}
+      style={{
+        paddingInlineStart: getItemOffset(depth - 1),
+        ...style,
+      }}
+      {...props}
+    >
+      {props.children}
+    </Base.SidebarFolderLink>
+  );
+}
+
+export function SidebarFolderContent({
+  children,
+  className,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderContent>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarFolderContent
+      className={cn(
+        itemVariants({
+          class: "relative",
+          highlight: depth === 1,
+        }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Base.SidebarFolderContent>
+  );
+}
+export const SidebarPageTree = createPageTreeRenderer({
+  SidebarFolder,
+  SidebarFolderContent,
+  SidebarFolderLink,
+  SidebarFolderTrigger,
+  SidebarItem,
+  SidebarSeparator,
+});
+
+export const SidebarLinkItem = createLinkItemRenderer({
+  SidebarFolder,
+  SidebarFolderContent,
+  SidebarFolderLink,
+  SidebarFolderTrigger,
+  SidebarItem,
+});
diff --git a/apps/docs/src/components/fumadocs/ui/icons.tsx b/apps/docs/src/components/fumadocs/ui/icons.tsx
new file mode 100644
index 0000000..6614d83
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/ui/icons.tsx
@@ -0,0 +1,337 @@
+/**
+ * @license lucide-react - ISC
+ *
+ * All copyright belongs to https://github.com/lucide-icons/lucide, we bundle it as part of library to avoid upstream issues.
+ */
+import type {ComponentProps} from "react";
+
+import {createElement, forwardRef} from "react";
+
+const defaultAttributes: LucideProps = {
+  fill: "none",
+  height: 24,
+  stroke: "currentColor",
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  strokeWidth: 2,
+  viewBox: "0 0 24 24",
+  width: 24,
+  xmlns: "http://www.w3.org/2000/svg",
+};
+
+type SVGElementType =
+  | "circle"
+  | "ellipse"
+  | "g"
+  | "line"
+  | "path"
+  | "polygon"
+  | "polyline"
+  | "rect";
+
+export interface LucideProps extends ComponentProps<"svg"> {
+  size?: string | number;
+}
+
+export type IconNode = [elementName: SVGElementType, attrs: Record<string, string>][];
+
+const createLucideIcon = (iconName: string, iconNode: IconNode) => {
+  const Component = forwardRef<SVGSVGElement, LucideProps>(
+    ({children, color = "currentColor", size = 24, ...props}, ref) => {
+      return (
+        <svg ref={ref} {...defaultAttributes} height={size} stroke={color} width={size} {...props}>
+          {iconNode.map(([tag, attr]) => createElement(tag, attr))}
+          {children}
+        </svg>
+      );
+    },
+  );
+
+  Component.displayName = iconName;
+
+  return Component;
+};
+
+export const ChevronDown = createLucideIcon("chevron-down", [
+  ["path", {d: "m6 9 6 6 6-6", key: "qrunsl"}],
+]);
+
+export const Languages = createLucideIcon("languages", [
+  ["path", {d: "m5 8 6 6", key: "1wu5hv"}],
+  ["path", {d: "m4 14 6-6 2-3", key: "1k1g8d"}],
+  ["path", {d: "M2 5h12", key: "or177f"}],
+  ["path", {d: "M7 2h1", key: "1t2jsx"}],
+  ["path", {d: "m22 22-5-10-5 10", key: "don7ne"}],
+  ["path", {d: "M14 18h6", key: "1m8k6r"}],
+]);
+
+export const Sidebar = createLucideIcon("panel-left", [
+  ["rect", {height: "18", key: "afitv7", rx: "2", width: "18", x: "3", y: "3"}],
+  ["path", {d: "M9 3v18", key: "fh3hqa"}],
+]);
+
+export const ChevronsUpDown = createLucideIcon("chevrons-up-down", [
+  ["path", {d: "m7 15 5 5 5-5", key: "1hf1tw"}],
+  ["path", {d: "m7 9 5-5 5 5", key: "sgt6xg"}],
+]);
+
+export const Search = createLucideIcon("search", [
+  ["circle", {cx: "11", cy: "11", key: "4ej97u", r: "8"}],
+  ["path", {d: "m21 21-4.3-4.3", key: "1qie3q"}],
+]);
+
+export const ExternalLink = createLucideIcon("external-link", [
+  ["path", {d: "M15 3h6v6", key: "1q9fwt"}],
+  ["path", {d: "M10 14 21 3", key: "gplh6r"}],
+  [
+    "path",
+    {
+      d: "M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6",
+      key: "a6xqqp",
+    },
+  ],
+]);
+
+export const Moon = createLucideIcon("moon", [
+  ["path", {d: "M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z", key: "a7tn18"}],
+]);
+
+export const Sun = createLucideIcon("sun", [
+  ["circle", {cx: "12", cy: "12", key: "4exip2", r: "4"}],
+  ["path", {d: "M12 2v2", key: "tus03m"}],
+  ["path", {d: "M12 20v2", key: "1lh1kg"}],
+  ["path", {d: "m4.93 4.93 1.41 1.41", key: "149t6j"}],
+  ["path", {d: "m17.66 17.66 1.41 1.41", key: "ptbguv"}],
+  ["path", {d: "M2 12h2", key: "1t8f8n"}],
+  ["path", {d: "M20 12h2", key: "1q8mjw"}],
+  ["path", {d: "m6.34 17.66-1.41 1.41", key: "1m8zz5"}],
+  ["path", {d: "m19.07 4.93-1.41 1.41", key: "1shlcs"}],
+]);
+
+export const Airplay = createLucideIcon("airplay", [
+  [
+    "path",
+    {
+      d: "M5 17H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2h-1",
+      key: "ns4c3b",
+    },
+  ],
+  ["path", {d: "m12 15 5 6H7Z", key: "14qnn2"}],
+]);
+
+export const Menu = createLucideIcon("menu", [
+  ["line", {key: "1e0a9i", x1: "4", x2: "20", y1: "12", y2: "12"}],
+  ["line", {key: "1owob3", x1: "4", x2: "20", y1: "6", y2: "6"}],
+  ["line", {key: "yk5zj1", x1: "4", x2: "20", y1: "18", y2: "18"}],
+]);
+
+export const X = createLucideIcon("x", [
+  ["path", {d: "M18 6 6 18", key: "1bl5f8"}],
+  ["path", {d: "m6 6 12 12", key: "d8bk6v"}],
+]);
+
+export const LoaderCircle = createLucideIcon("loader-circle", [
+  ["path", {d: "M21 12a9 9 0 1 1-6.219-8.56", key: "13zald"}],
+]);
+
+export const CircleCheck = createLucideIcon("circle-check", [
+  ["circle", {cx: "12", cy: "12", key: "1mglay", r: "10"}],
+  ["path", {d: "m9 12 2 2 4-4", key: "dzmm74"}],
+]);
+
+export const CircleX = createLucideIcon("circle-x", [
+  ["circle", {cx: "12", cy: "12", key: "1mglay", r: "10"}],
+  ["path", {d: "m15 9-6 6", key: "1uzhvr"}],
+  ["path", {d: "m9 9 6 6", key: "z0biqf"}],
+]);
+
+export const Check = createLucideIcon("check", [["path", {d: "M20 6 9 17l-5-5", key: "1gmf2c"}]]);
+
+export const TriangleAlert = createLucideIcon("triangle-alert", [
+  [
+    "path",
+    {
+      d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3",
+      key: "wmoenq",
+    },
+  ],
+  ["path", {d: "M12 9v4", key: "juzpu7"}],
+  ["path", {d: "M12 17h.01", key: "p32p05"}],
+]);
+
+export const Info = createLucideIcon("info", [
+  ["circle", {cx: "12", cy: "12", key: "1mglay", r: "10"}],
+  ["path", {d: "M12 16v-4", key: "1dtifu"}],
+  ["path", {d: "M12 8h.01", key: "e9boi3"}],
+]);
+
+export const Copy = createLucideIcon("copy", [
+  [
+    "rect",
+    {
+      height: "14",
+      key: "17jyea",
+      rx: "2",
+      ry: "2",
+      width: "14",
+      x: "8",
+      y: "8",
+    },
+  ],
+  [
+    "path",
+    {
+      d: "M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2",
+      key: "zix9uf",
+    },
+  ],
+]);
+
+export const Clipboard = createLucideIcon("clipboard", [
+  [
+    "rect",
+    {
+      height: "4",
+      key: "1",
+      rx: "1",
+      ry: "1",
+      width: "8",
+      x: "8",
+      y: "2",
+    },
+  ],
+  [
+    "path",
+    {
+      d: "M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2",
+      key: "2",
+    },
+  ],
+]);
+
+export const FileText = createLucideIcon("file-text", [
+  [
+    "path",
+    {
+      d: "M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z",
+      key: "1rqfz7",
+    },
+  ],
+  ["path", {d: "M14 2v4a2 2 0 0 0 2 2h4", key: "tnqrlb"}],
+  ["path", {d: "M10 9H8", key: "b1mrlr"}],
+  ["path", {d: "M16 13H8", key: "t4e002"}],
+  ["path", {d: "M16 17H8", key: "z1uh3a"}],
+]);
+
+export const Hash = createLucideIcon("hash", [
+  ["line", {key: "4lhtct", x1: "4", x2: "20", y1: "9", y2: "9"}],
+  ["line", {key: "vyu0kd", x1: "4", x2: "20", y1: "15", y2: "15"}],
+  ["line", {key: "1ggp8o", x1: "10", x2: "8", y1: "3", y2: "21"}],
+  ["line", {key: "weycgp", x1: "16", x2: "14", y1: "3", y2: "21"}],
+]);
+
+export const Text = createLucideIcon("text", [
+  ["path", {d: "M15 18H3", key: "olowqp"}],
+  ["path", {d: "M17 6H3", key: "16j9eg"}],
+  ["path", {d: "M21 12H3", key: "2avoz0"}],
+]);
+
+export const File = createLucideIcon("file", [
+  [
+    "path",
+    {
+      d: "M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z",
+      key: "1rqfz7",
+    },
+  ],
+  ["path", {d: "M14 2v4a2 2 0 0 0 2 2h4", key: "tnqrlb"}],
+]);
+
+export const Folder = createLucideIcon("folder", [
+  [
+    "path",
+    {
+      d: "M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z",
+      key: "1kt360",
+    },
+  ],
+]);
+
+export const FolderOpen = createLucideIcon("folder-open", [
+  [
+    "path",
+    {
+      d: "m6 14 1.5-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.54 6a2 2 0 0 1-1.95 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H18a2 2 0 0 1 2 2v2",
+      key: "usdka0",
+    },
+  ],
+]);
+
+export const Star = createLucideIcon("star", [
+  [
+    "path",
+    {
+      d: "M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z",
+      key: "r04s7s",
+    },
+  ],
+]);
+
+export const Link = createLucideIcon("link", [
+  [
+    "path",
+    {
+      d: "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71",
+      key: "1cjeqo",
+    },
+  ],
+  [
+    "path",
+    {
+      d: "M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71",
+      key: "19qd67",
+    },
+  ],
+]);
+
+export const Edit = createLucideIcon("square-pen", [
+  [
+    "path",
+    {
+      d: "M12 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7",
+      key: "1m0v6g",
+    },
+  ],
+  [
+    "path",
+    {
+      d: "M18.375 2.625a1 1 0 0 1 3 3l-9.013 9.014a2 2 0 0 1-.853.505l-2.873.84a.5.5 0 0 1-.62-.62l.84-2.873a2 2 0 0 1 .506-.852z",
+      key: "ohrbg2",
+    },
+  ],
+]);
+
+export const ChevronRight = createLucideIcon("chevron-right", [
+  ["path", {d: "m9 18 6-6-6-6", key: "mthhwq"}],
+]);
+
+export const ChevronLeft = createLucideIcon("chevron-left", [
+  ["path", {d: "m15 18-6-6 6-6", key: "1wnfg3"}],
+]);
+
+export const Plus = createLucideIcon("plus", [
+  ["path", {d: "M5 12h14", key: "1ays0h"}],
+  ["path", {d: "M12 5v14", key: "s699le"}],
+]);
+
+export const Trash2 = createLucideIcon("trash-2", [
+  ["path", {d: "M3 6h18", key: "d0wm0j"}],
+  ["path", {d: "M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6", key: "4alrt4"}],
+  ["path", {d: "M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2", key: "v07s0e"}],
+  ["line", {key: "1uufr5", x1: "10", x2: "10", y1: "11", y2: "17"}],
+  ["line", {key: "xtxkd", x1: "14", x2: "14", y1: "11", y2: "17"}],
+]);
+
+export const ChevronUp = createLucideIcon("chevron-up", [
+  ["path", {d: "m18 15-6-6-6 6", key: "153udz"}],
+]);
diff --git a/apps/docs/src/components/fumadocs/ui/language-toggle.tsx b/apps/docs/src/components/fumadocs/ui/language-toggle.tsx
new file mode 100644
index 0000000..459fda2
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/ui/language-toggle.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import type {ComponentProps} from "react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useI18n} from "fumadocs-ui/contexts/i18n";
+
+import {Languages} from "@/components/fumadocs/ui/icons";
+
+export type LanguageSelectProps = ComponentProps<typeof Button>;
+
+export function LanguageToggle(props: LanguageSelectProps): React.ReactElement {
+  const context = useI18n();
+
+  if (!context.locales) throw new Error("Missing `<I18nProvider />`");
+
+  return (
+    <Dropdown>
+      <Button
+        isIconOnly
+        aria-label={context.text.chooseLanguage}
+        size="sm"
+        variant="tertiary"
+        {...props}
+      >
+        {props.children}
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu
+          selectedKeys={context.locale ? new Set([context.locale]) : new Set<string>()}
+          selectionMode="single"
+          onSelectionChange={(keys) => {
+            if (keys === "all") return;
+            const next = keys.values().next().value;
+
+            if (typeof next === "string" && next !== context.locale) {
+              context.onChange?.(next);
+            }
+          }}
+        >
+          <Dropdown.Section>
+            <Header>{context.text.chooseLanguage}</Header>
+            {context.locales.map((item) => (
+              <Dropdown.Item key={item.locale} id={item.locale} textValue={item.name}>
+                <Dropdown.ItemIndicator />
+                <Label>{item.name}</Label>
+              </Dropdown.Item>
+            ))}
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
+
+export function LanguageToggleText(props: ComponentProps<"span">) {
+  const context = useI18n();
+  const text = context.locales?.find((item) => item.locale === context.locale)?.name;
+
+  return <span {...props}>{text}</span>;
+}
+
+// Adapter for use as a fumadocs `slots.languageSelect.root` slot (e.g. in HomeLayout).
+// Render the same LanguageToggle component across pages
+export function LanguageToggleSlot(_props: ComponentProps<"button">) {
+  return (
+    <LanguageToggle>
+      <Languages className="text-fd-muted-foreground size-4" />
+    </LanguageToggle>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/ui/link-item.tsx b/apps/docs/src/components/fumadocs/ui/link-item.tsx
new file mode 100644
index 0000000..5381c9b
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/ui/link-item.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import type {ComponentProps, ReactNode} from "react";
+
+import {usePathname} from "fumadocs-core/framework";
+import Link from "fumadocs-core/link";
+
+import {isActive} from "../utils/urls";
+
+interface Filterable {
+  /**
+   * Restrict where the item is displayed
+   *
+   * @defaultValue 'all'
+   */
+  on?: "menu" | "nav" | "all";
+}
+
+interface WithHref {
+  url: string;
+  /**
+   * When the item is marked as active
+   *
+   * @defaultValue 'url'
+   */
+  active?: "url" | "nested-url" | "none";
+  external?: boolean;
+}
+
+export interface MainItemType extends WithHref, Filterable {
+  type?: "main";
+  icon?: ReactNode;
+  text: ReactNode;
+  description?: ReactNode;
+}
+
+export interface IconItemType extends WithHref, Filterable {
+  type: "icon";
+  /**
+   * `aria-label` of icon button
+   */
+  label?: string;
+  icon: ReactNode;
+  text: ReactNode;
+  /**
+   * @defaultValue true
+   */
+  secondary?: boolean;
+}
+
+export interface ButtonItemType extends WithHref, Filterable {
+  type: "button";
+  icon?: ReactNode;
+  text: ReactNode;
+  /**
+   * @defaultValue false
+   */
+  secondary?: boolean;
+}
+
+export interface MenuItemType extends Partial<WithHref>, Filterable {
+  type: "menu";
+  icon?: ReactNode;
+  text: ReactNode;
+
+  items: (
+    | (MainItemType & {
+        /**
+         * Options when displayed on navigation menu
+         */
+        menu?: ComponentProps<"a"> & {
+          banner?: ReactNode;
+        };
+      })
+    | CustomItemType
+  )[];
+
+  /**
+   * @defaultValue false
+   */
+  secondary?: boolean;
+}
+
+export interface CustomItemType extends Filterable {
+  type: "custom";
+  /**
+   * @defaultValue false
+   */
+  secondary?: boolean;
+  children: ReactNode;
+}
+
+export type LinkItemType =
+  | MainItemType
+  | IconItemType
+  | ButtonItemType
+  | MenuItemType
+  | CustomItemType;
+
+export function LinkItem({
+  item,
+  ref,
+  ...props
+}: Omit<ComponentProps<"a">, "href"> & {item: WithHref}) {
+  const pathname = usePathname();
+  const activeType = item.active ?? "url";
+  const active = activeType !== "none" && isActive(item.url, pathname, activeType === "nested-url");
+
+  return (
+    <Link ref={ref} external={item.external} href={item.url} {...props} data-active={active}>
+      {props.children}
+    </Link>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/ui/search-toggle.tsx b/apps/docs/src/components/fumadocs/ui/search-toggle.tsx
new file mode 100644
index 0000000..3acb8d2
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/ui/search-toggle.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import type {ButtonProps} from "fumadocs-ui/components/ui/button";
+import type {ComponentProps} from "react";
+
+import {buttonVariants} from "fumadocs-ui/components/ui/button";
+import {useI18n} from "fumadocs-ui/contexts/i18n";
+import {useSearchContext} from "fumadocs-ui/contexts/search";
+
+import {Search} from "@/components/fumadocs/ui/icons";
+import {cn} from "@/utils/cn";
+
+interface SearchToggleProps extends Omit<ComponentProps<"button">, "color">, ButtonProps {
+  hideIfDisabled?: boolean;
+}
+
+export function SearchToggle({
+  color = "ghost",
+  hideIfDisabled,
+  size = "icon-sm",
+  ...props
+}: SearchToggleProps) {
+  const {enabled, setOpenSearch} = useSearchContext();
+
+  if (hideIfDisabled && !enabled) return null;
+
+  return (
+    <button
+      aria-label="Open Search"
+      data-search=""
+      type="button"
+      className={cn(
+        buttonVariants({
+          color,
+          size,
+        }),
+        props.className,
+      )}
+      onClick={() => {
+        setOpenSearch(true);
+      }}
+    >
+      <Search />
+    </button>
+  );
+}
+
+export function LargeSearchToggle({
+  hideIfDisabled,
+  ...props
+}: ComponentProps<"button"> & {
+  hideIfDisabled?: boolean;
+}) {
+  const {enabled, hotKey, setOpenSearch} = useSearchContext();
+  const {text} = useI18n();
+
+  if (hideIfDisabled && !enabled) return null;
+
+  return (
+    <button
+      data-search-full=""
+      type="button"
+      {...props}
+      className={cn(
+        "bg-fd-secondary/50 text-fd-muted-foreground hover:bg-fd-accent hover:text-fd-accent-foreground inline-flex items-center gap-2 rounded-lg border p-1.5 ps-2 text-sm transition-colors",
+        props.className,
+      )}
+      onClick={() => {
+        setOpenSearch(true);
+      }}
+    >
+      <Search className="size-4" />
+      {text.search}
+      <div className="ms-auto inline-flex gap-0.5">
+        {hotKey.map((k, i) => (
+          <kbd key={i} className="bg-fd-background rounded-md border px-1.5">
+            {k.display}
+          </kbd>
+        ))}
+      </div>
+    </button>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/ui/theme-toggle.tsx b/apps/docs/src/components/fumadocs/ui/theme-toggle.tsx
new file mode 100644
index 0000000..e63ac39
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/ui/theme-toggle.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {ComponentProps} from "react";
+
+import {useTheme} from "next-themes";
+import {tv} from "tailwind-variants";
+
+import {Airplay, Moon, Sun} from "@/components/fumadocs/ui/icons";
+import {useIsMounted} from "@/hooks/use-is-mounted";
+import {cn} from "@/utils/cn";
+
+const itemVariants = tv({
+  base: "text-fd-muted-foreground size-6.5 rounded-full p-1.5",
+  variants: {
+    active: {
+      false: "text-fd-muted-foreground",
+      true: "bg-fd-accent text-fd-accent-foreground",
+    },
+  },
+});
+
+const full = [["light", Sun] as const, ["dark", Moon] as const, ["system", Airplay] as const];
+
+export function ThemeToggle({
+  className,
+  mode = "light-dark",
+  ...props
+}: ComponentProps<"div"> & {
+  mode?: "light-dark" | "light-dark-system";
+}) {
+  const {resolvedTheme, setTheme, theme} = useTheme();
+  const mounted = useIsMounted();
+
+  const container = cn(
+    "inline-flex cursor-(--cursor-interactive) items-center rounded-full border p-1",
+    className,
+  );
+
+  if (mode === "light-dark") {
+    const value = mounted ? resolvedTheme : null;
+
+    return (
+      <button
+        aria-label="Toggle Theme"
+        className={container}
+        data-theme-toggle=""
+        onClick={() => setTheme(value === "light" ? "dark" : "light")}
+      >
+        {full.map(([key, Icon]) => {
+          if (key === "system") return;
+
+          return (
+            <Icon
+              key={key}
+              className={cn(itemVariants({active: value === key}))}
+              fill="currentColor"
+            />
+          );
+        })}
+      </button>
+    );
+  }
+
+  const value = mounted ? theme : null;
+
+  return (
+    <div className={container} data-theme-toggle="" {...props}>
+      {full.map(([key, Icon]) => (
+        <button
+          key={key}
+          aria-label={key}
+          className={cn(itemVariants({active: value === key}))}
+          onClick={() => setTheme(key)}
+        >
+          <Icon className="size-full" fill="currentColor" />
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/fumadocs/utils/merge-refs.ts b/apps/docs/src/components/fumadocs/utils/merge-refs.ts
new file mode 100644
index 0000000..60f4d0b
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/utils/merge-refs.ts
@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+export function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T> {
+  return (value) => {
+    refs.forEach((ref) => {
+      if (typeof ref === "function") {
+        ref(value);
+      } else if (ref) {
+        ref.current = value;
+      }
+    });
+  };
+}
diff --git a/apps/docs/src/components/fumadocs/utils/urls.ts b/apps/docs/src/components/fumadocs/utils/urls.ts
new file mode 100644
index 0000000..2876df7
--- /dev/null
+++ b/apps/docs/src/components/fumadocs/utils/urls.ts
@@ -0,0 +1,15 @@
+export function normalize(urlOrPath: string) {
+  if (urlOrPath.length > 1 && urlOrPath.endsWith("/")) return urlOrPath.slice(0, -1);
+
+  return urlOrPath;
+}
+
+/**
+ * @returns if `href` is matching the given pathname
+ */
+export function isActive(href: string, pathname: string, nested = true): boolean {
+  href = normalize(href);
+  pathname = normalize(pathname);
+
+  return href === pathname || (nested && pathname.startsWith(`${href}/`));
+}
diff --git a/apps/docs/src/components/github-link.tsx b/apps/docs/src/components/github-link.tsx
new file mode 100644
index 0000000..d0e5e5c
--- /dev/null
+++ b/apps/docs/src/components/github-link.tsx
@@ -0,0 +1,216 @@
+"use client";
+
+import {buttonVariants} from "@heroui/react";
+import {useEffect, useRef, useState} from "react";
+
+import {useCurrentFramework} from "@/hooks/use-current-framework";
+import {GitHubIcon} from "@/icons/github";
+import {cn} from "@/utils/cn";
+import {GITHUB_API_URL, REPO_NAME, REPO_NAME_NATIVE} from "@/utils/constants";
+
+const CACHE_DURATION = 86400000; // 1 day in milliseconds
+const CACHE_KEY_PREFIX = "github-stars-";
+const STATIC_STARS = {
+  native: 2300,
+  web: 27700,
+};
+
+interface CachedStarsData {
+  timestamp: number;
+  data: any;
+}
+
+function getCachedStars(repo: string): any | null {
+  try {
+    const cacheKey = `${CACHE_KEY_PREFIX}${repo}`;
+    const cached = localStorage.getItem(cacheKey);
+
+    if (!cached) {
+      return null;
+    }
+
+    const parsed: CachedStarsData = JSON.parse(cached);
+    const now = Date.now();
+    const age = now - parsed.timestamp;
+
+    if (age > CACHE_DURATION) {
+      // Cache expired, remove it
+      localStorage.removeItem(cacheKey);
+
+      return null;
+    }
+
+    return parsed.data;
+  } catch {
+    // If localStorage is unavailable or corrupted, return null
+    return null;
+  }
+}
+
+function setCachedStars(repo: string, data: any): void {
+  try {
+    const cacheKey = `${CACHE_KEY_PREFIX}${repo}`;
+    const cacheValue: CachedStarsData = {
+      data,
+      timestamp: Date.now(),
+    };
+
+    localStorage.setItem(cacheKey, JSON.stringify(cacheValue));
+  } catch {
+    // If localStorage is unavailable, silently fail
+    // Component will still work, just won't cache
+  }
+}
+
+function getGitHubRepo(framework: "web" | "native"): string {
+  return framework === "native" ? REPO_NAME_NATIVE : REPO_NAME;
+}
+
+function getGitHubUrl(framework: "web" | "native"): string {
+  const repo = getGitHubRepo(framework);
+
+  return `https://github.com/${repo}`;
+}
+
+function formatStarsCount(count: number): string {
+  return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : count.toLocaleString();
+}
+
+export function GitHubLink({
+  children,
+  className,
+}: {
+  className?: string;
+  children?: React.ReactNode;
+}) {
+  const framework = useCurrentFramework();
+  const githubUrl = getGitHubUrl(framework);
+
+  return (
+    <a
+      href={githubUrl}
+      rel="noreferrer"
+      target="_blank"
+      className={buttonVariants({
+        className: cn("bg-surface-tertiary", className),
+        variant: "tertiary",
+      })}
+    >
+      <GitHubIcon />
+      {children}
+      <StarsCount />
+    </a>
+  );
+}
+
+export function GitHubLinkSmall({className}: {className?: string}) {
+  const framework = useCurrentFramework();
+  const githubUrl = getGitHubUrl(framework);
+
+  return (
+    <a
+      href={githubUrl}
+      rel="noreferrer"
+      target="_blank"
+      className={buttonVariants({
+        className: cn("h-[34px] border-none bg-default/80", className),
+        size: "sm",
+        variant: "tertiary",
+      })}
+    >
+      <GitHubIcon />
+      <StarsCount />
+    </a>
+  );
+}
+
+function StarsCountInner({
+  className,
+  framework,
+}: {
+  framework: "web" | "native";
+  className?: string;
+}) {
+  const repo = getGitHubRepo(framework);
+  const [mounted, setMounted] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [json, setJson] = useState<any>(null);
+  const prevRepoRef = useRef<string>(repo);
+
+  // Mark as mounted after hydration to ensure server/client match
+  useEffect(() => {
+    const rafId = requestAnimationFrame(() => {
+      setMounted(true);
+    });
+
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, []);
+
+  useEffect(() => {
+    const currentRepo = getGitHubRepo(framework);
+
+    // Update ref for next comparison
+    prevRepoRef.current = currentRepo;
+
+    const cached = getCachedStars(currentRepo);
+
+    // If we have valid cached data, use it (handles framework changes)
+    if (cached) {
+      // Use requestAnimationFrame to avoid synchronous setState warning
+      const rafId = requestAnimationFrame(() => {
+        setJson(cached);
+        setIsLoading(false);
+      });
+
+      return () => {
+        cancelAnimationFrame(rafId);
+      };
+    }
+
+    // No cache, fetch from API
+    let cancelled = false;
+
+    fetch(`${GITHUB_API_URL}/repos/${currentRepo}`)
+      .then((response) => response.json())
+      .then((data) => {
+        if (!cancelled) {
+          setJson(data);
+          setIsLoading(false);
+          // Cache the fetched data
+          setCachedStars(currentRepo, data);
+        }
+      })
+      .catch((error) => {
+        if (!cancelled) {
+          console.error("Error fetching stars count:", error);
+          setIsLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [framework]);
+
+  // Use static values during SSR and initial client render to prevent CLS
+  const staticStars = STATIC_STARS[framework];
+  const displayCount = !mounted || isLoading ? staticStars : json?.stargazers_count;
+
+  if (!displayCount) {
+    return null;
+  }
+
+  return (
+    <span className={cn("pt-px text-xs font-medium text-muted tabular-nums", className)}>
+      {formatStarsCount(displayCount)}
+    </span>
+  );
+}
+
+export function StarsCount({className}: {className?: string}) {
+  const framework = useCurrentFramework();
+
+  return <StarsCountInner className={className} framework={framework} />;
+}
diff --git a/apps/docs/src/components/heroui-logo.tsx b/apps/docs/src/components/heroui-logo.tsx
new file mode 100644
index 0000000..8d2d378
--- /dev/null
+++ b/apps/docs/src/components/heroui-logo.tsx
@@ -0,0 +1,64 @@
+interface HeroUILogoProps {
+  className?: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+
+export function HeroUILogo({className, height, size = 26, width}: HeroUILogoProps) {
+  // Calculate dimensions based on original aspect ratio (140:44)
+  const aspectRatio = 140 / 44;
+  const svgHeight = height || size;
+  const svgWidth = width || Math.round(svgHeight * aspectRatio);
+
+  return (
+    <>
+      <svg
+        aria-hidden="true"
+        className={className}
+        fill="none"
+        height={svgHeight}
+        viewBox="0 0 140 44"
+        width={svgWidth}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M0.677734 11.3847V24.0405C0.677734 24.6387 0.985209 25.1946 1.49107 25.5109L10.1195 30.9067C11.2693 31.6257 12.7586 30.796 12.7586 29.4363V18.7981C12.7586 18.186 13.0803 17.6194 13.605 17.3074L18.8683 14.1785V41.4437C18.8683 42.7988 20.3486 43.6293 21.4988 42.9195L30.4044 37.4229C30.9152 37.1076 31.2264 36.549 31.2264 35.9471V9.76484C31.2264 8.41634 29.759 7.58483 28.6085 8.28139L18.8683 14.1785V2.55643C18.8683 1.21158 17.408 0.379537 16.2574 1.06878L1.51927 9.89703C0.997365 10.2097 0.677734 10.7747 0.677734 11.3847Z"
+          fill="currentColor"
+        />
+        <path
+          d="M63.8763 24.0707C63.8763 20.4817 62.4078 18.8253 59.4709 18.8253C56.1076 18.8253 53.7391 21.0799 53.7391 26.1412V37.7363H47.6756V5.52769H53.7391V17.3069C55.2075 14.9142 57.6234 13.7179 60.9394 13.7179C66.5764 13.7179 69.8924 17.1688 69.8924 22.9664V37.7363H63.8763V24.0707Z"
+          fill="currentColor"
+        />
+        <path
+          d="M84.8996 38.4725C77.3677 38.4725 72.5832 33.5952 72.5832 26.0952C72.5832 18.6872 77.3203 13.7179 84.8996 13.7179C93.0947 13.7179 97.5475 19.5154 96.3158 27.6596H78.6467C78.9783 31.5247 81.252 33.7333 84.8996 33.7333C87.8839 33.7333 89.684 32.2149 90.1577 30.6964H96.1737C95.2263 35.2057 91.0577 38.4725 84.8996 38.4725ZM78.7888 23.6566H90.4419C90.3945 20.4817 88.3102 18.3191 84.7574 18.3191C81.5836 18.3191 79.3572 20.1596 78.7888 23.6566Z"
+          fill="currentColor"
+        />
+        <path
+          d="M99.6225 20.3437C99.6225 16.5246 101.754 14.4541 105.828 14.4541H113.597V19.4234H105.686V37.7363H99.6225V20.3437Z"
+          fill="currentColor"
+        />
+        <path
+          d="M126.863 38.4725C119.189 38.4725 114.31 33.5492 114.31 26.0952C114.31 18.6412 119.189 13.7179 126.863 13.7179C134.442 13.7179 139.322 18.6412 139.322 26.0952C139.322 33.5492 134.442 38.4725 126.863 38.4725ZM126.863 33.4572C130.653 33.4572 133.163 30.5584 133.163 26.0952C133.163 21.632 130.653 18.6872 126.863 18.6872C123.026 18.6872 120.515 21.632 120.515 26.0952C120.515 30.5584 123.026 33.4572 126.863 33.4572Z"
+          fill="currentColor"
+        />
+      </svg>
+      <span
+        className="sr-only"
+        style={{
+          borderWidth: 0,
+          clip: "rect(0, 0, 0, 0)",
+          height: "1px",
+          margin: "-1px",
+          overflow: "hidden",
+          padding: "0",
+          position: "absolute",
+          whiteSpace: "nowrap",
+          width: "1px",
+        }}
+      >
+        HeroUI
+      </span>
+    </>
+  );
+}
diff --git a/apps/docs/src/components/heroui-plain-logo.tsx b/apps/docs/src/components/heroui-plain-logo.tsx
new file mode 100644
index 0000000..317b323
--- /dev/null
+++ b/apps/docs/src/components/heroui-plain-logo.tsx
@@ -0,0 +1,48 @@
+interface HeroUIPlainProps {
+  className?: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+
+export function HeroUIPlainLogo({className, height, size = 26, width}: HeroUIPlainProps) {
+  // Calculate dimensions based on original aspect ratio (140:44)
+  const aspectRatio = 114 / 158;
+  const svgHeight = height || size;
+  const svgWidth = width || Math.round(svgHeight * aspectRatio);
+
+  return (
+    <>
+      <svg
+        aria-hidden="true"
+        className={className}
+        fill="none"
+        height={svgHeight}
+        viewBox="0 0 114 158"
+        width={svgWidth}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M0 39.403v47.208a6.467 6.467 0 0 0 3.035 5.485l32.2 20.127c4.29 2.682 9.848-.413 9.848-5.485V67.056c0-2.283 1.2-4.397 3.159-5.56l19.64-11.672v101.703c0 5.055 5.525 8.153 9.817 5.505l33.234-20.503a6.467 6.467 0 0 0 3.067-5.505V33.361c0-5.03-5.476-8.132-9.769-5.534L67.883 49.824V6.473c0-5.016-5.45-8.12-9.744-5.549L3.14 33.853A6.467 6.467 0 0 0 0 39.404Z"
+          fill="currentColor"
+        />
+      </svg>
+      <span
+        className="sr-only"
+        style={{
+          borderWidth: 0,
+          clip: "rect(0, 0, 0, 0)",
+          height: "1px",
+          margin: "-1px",
+          overflow: "hidden",
+          padding: "0",
+          position: "absolute",
+          whiteSpace: "nowrap",
+          width: "1px",
+        }}
+      >
+        HeroUI Logo
+      </span>
+    </>
+  );
+}
diff --git a/apps/docs/src/components/highlighted-code.tsx b/apps/docs/src/components/highlighted-code.tsx
new file mode 100644
index 0000000..69190dc
--- /dev/null
+++ b/apps/docs/src/components/highlighted-code.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import type {BundledLanguage, BundledTheme, HighlighterGeneric} from "shiki";
+
+import {useTheme} from "next-themes";
+import {memo, use, useMemo} from "react";
+
+import {cn} from "@/utils/cn";
+
+type Highlighter = HighlighterGeneric<BundledLanguage, BundledTheme>;
+
+// Singleton highlighter promise
+let highlighterPromise: Promise<Highlighter> | null = null;
+
+function getHighlighterPromise(): Promise<Highlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = import("shiki").then(({createHighlighter}) =>
+      createHighlighter({
+        langs: ["tsx", "typescript", "javascript", "jsx", "css", "html", "json", "bash", "shell"],
+        themes: ["github-dark", "github-light"],
+      }),
+    );
+  }
+
+  return highlighterPromise;
+}
+
+interface HighlightedCodeProps {
+  code: string;
+  lang?: string;
+  showLineNumbers?: boolean;
+  className?: string;
+}
+
+/**
+ * HighlightedCode component for syntax highlighting using Shiki.
+ *
+ * This component is memoized with React.memo() to work effectively with
+ * useDeferredValue for performance optimization. When parent components
+ * use useDeferredValue on the code prop, memoization ensures this expensive
+ * syntax highlighting only re-runs when the deferred value actually changes.
+ */
+export const HighlightedCode = memo(function HighlightedCode({
+  className,
+  code,
+  lang = "tsx",
+  showLineNumbers = true,
+}: HighlightedCodeProps) {
+  const {resolvedTheme} = useTheme();
+  const theme = resolvedTheme === "dark" ? "dark" : "light";
+
+  // Use React's `use` hook to suspend while loading the highlighter
+  const highlighter = use(getHighlighterPromise());
+
+  const highlightedHtml = useMemo(() => {
+    const trimmedCode = code.trim();
+
+    if (!trimmedCode) return "";
+
+    const loadedLangs = highlighter.getLoadedLanguages();
+    const langToUse = loadedLangs.includes(lang as BundledLanguage) ? lang : "text";
+
+    return highlighter.codeToHtml(trimmedCode, {
+      lang: langToUse,
+      theme: theme === "dark" ? "github-dark" : "github-light",
+    });
+  }, [code, lang, theme, highlighter]);
+
+  if (!highlightedHtml) {
+    return null;
+  }
+
+  return (
+    <div
+      dangerouslySetInnerHTML={{__html: highlightedHtml}}
+      className={cn(
+        "docs-code-block overflow-auto text-sm [&_.shiki]:bg-transparent! [&_pre]:bg-transparent!",
+        showLineNumbers && "docs-code-block-line-numbers",
+        "[&>pre]:m-0 [&>pre]:p-4",
+        "[&>pre>code]:block [&>pre>code]:font-mono [&>pre>code]:leading-relaxed",
+        className,
+      )}
+    />
+  );
+});
diff --git a/apps/docs/src/components/home-color-swatch-picker.tsx b/apps/docs/src/components/home-color-swatch-picker.tsx
new file mode 100644
index 0000000..db1788f
--- /dev/null
+++ b/apps/docs/src/components/home-color-swatch-picker.tsx
@@ -0,0 +1,48 @@
+import type {ColorSwatchPickerProps} from "react-aria-components";
+
+import {cn} from "@/utils/cn";
+
+import {ColorSwatchPicker, ColorSwatchPickerItem} from "./color-swatch-picker";
+
+const colors = [
+  "#0A0A0A", // black
+  "#006FEE", // blue (keep)
+  "#F31260", // red
+  "#17C964", // green
+  "#F59E0B", // amber/orange
+  "#3F3F46", // soft gray
+  "#4a8f87", // soft green
+];
+
+export function HomeColorSwatchPicker({
+  className,
+  onValueChange,
+  value,
+  ...props
+}: ColorSwatchPickerProps & {
+  className?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+}) {
+  return (
+    <ColorSwatchPicker
+      value={value}
+      className={cn(
+        className,
+        "flex h-13 items-center gap-2 rounded-full bg-[#D7CDD0] px-3 shadow-[inset_0_0_0_1px_rgba(255,255,255,0.5),0_1px_4px_rgba(0,0,0,0.15)] backdrop-blur-md dark:bg-[#383435]/30 dark:shadow-[inset_0_0_0_1px_rgba(255,255,255,0.08),0px_1px_4px_0px_rgba(0,0,0,0.15)]",
+      )}
+      onChange={(color) => onValueChange?.(color.toString())}
+      {...props}
+    >
+      {colors.map((color) => (
+        <ColorSwatchPickerItem
+          key={color}
+          className="shadow-[inset_0px_2px_1px_0px_rgba(0,0,0,0.25)]"
+          color={color}
+          outlineColor={color}
+          outlineOffsetColor="#D7CDD0"
+        />
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/components/home-components.tsx b/apps/docs/src/components/home-components.tsx
new file mode 100644
index 0000000..e69de29
diff --git a/apps/docs/src/components/home-theme-customizer.tsx b/apps/docs/src/components/home-theme-customizer.tsx
new file mode 100644
index 0000000..40a6653
--- /dev/null
+++ b/apps/docs/src/components/home-theme-customizer.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {HomeColorSwatchPicker} from "./home-color-swatch-picker";
+import {HomeThemeSwitch} from "./home-theme-switch";
+import HorizontalScrollingBanner from "./horizontal-scrolling-banner";
+
+export function HomeThemeCustomizer() {
+  return (
+    <>
+      <div className="mt-8 flex flex-col gap-3 text-muted">
+        <p>Customize theme (preview)</p>
+        <div className="flex items-center gap-3">
+          <HomeColorSwatchPicker />
+          <HomeThemeSwitch />
+        </div>
+      </div>
+
+      {/* Demo Image Section */}
+      <div className="max-w-8xl mt-12 w-full px-4">
+        <HorizontalScrollingBanner showShadow duration={160} gap="1.5rem" shadowSize="80px">
+          {[1, 2, 3, 4, 5, 6, 7, 8].map((item) => (
+            <div
+              key={item}
+              className="flex h-[320px] w-[250px] items-center justify-center rounded-lg bg-default text-2xl font-bold"
+            >
+              {item}
+            </div>
+          ))}
+        </HorizontalScrollingBanner>
+      </div>
+    </>
+  );
+}
diff --git a/apps/docs/src/components/home-theme-switch.tsx b/apps/docs/src/components/home-theme-switch.tsx
new file mode 100644
index 0000000..efc53ff
--- /dev/null
+++ b/apps/docs/src/components/home-theme-switch.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import type {SwitchProps as AriaSwitchProps} from "react-aria-components";
+
+import {useTheme} from "next-themes";
+import React from "react";
+import {Switch as AriaSwitch} from "react-aria-components";
+import {tv} from "tailwind-variants";
+
+import {useIsMounted} from "@/hooks/use-is-mounted";
+import {composeTailwindRenderProps} from "@/utils/compose-tw-render";
+
+import {Iconify} from "./iconify";
+
+export interface SwitchProps extends Omit<AriaSwitchProps, "children"> {
+  children: React.ReactNode;
+}
+
+const wrapper = tv({
+  base: [
+    "group relative flex h-13 w-[84px] items-center gap-3 rounded-full bg-[#C6BCBB]/50",
+    "px-4 shadow-[inset_0_0_0_1px_rgba(255,255,255,0.5),0_1px_4px_rgba(0,0,0,0.15)]",
+    "backdrop-blur-[54.3px] dark:bg-[#383435]/30 dark:shadow-[inset_0_0_0_1px_rgba(255,255,255,0.08),0px_1px_4px_0px_rgba(0,0,0,0.15)]",
+  ],
+});
+
+const icon = tv({
+  base: "z-20 text-xl text-foreground",
+});
+
+const thumb = tv({
+  base: [
+    "absolute top-1/2 left-2.5 z-10 h-8 w-8 bg-[#FFFFFF]/70 backdrop-blur-md",
+    "-translate-y-1/2 rounded-full shadow-[0px_2px_8px_0px_rgba(0,0,0,0.16)]",
+    "dark:bg-[#383435]/30 dark:shadow-[inset_0_0_0_1px_rgba(255,255,255,0.08),0px_1px_4px_0px_rgba(0,0,0,0.15)]",
+    "transition-all duration-300",
+  ],
+  compoundVariants: [
+    {
+      class: "w-10",
+      isPressed: true,
+      isSelected: false,
+    },
+    {
+      class: "ml-6 w-10",
+      isPressed: true,
+      isSelected: true,
+    },
+  ],
+  variants: {
+    isFocusVisible: {
+      true: "ring-2 ring-offset-2 ring-offset-white",
+    },
+    isSelected: {
+      false: "",
+      true: "ml-8",
+    },
+  },
+});
+
+export function HomeThemeSwitch({...props}: Omit<SwitchProps, "children">) {
+  const {setTheme, theme} = useTheme();
+  const isMounted = useIsMounted();
+
+  if (!isMounted) {
+    // Render placeholder to avoid layout shift
+    return <div className="h-13 w-[84px] rounded-full bg-[#C6BCBB]/50 backdrop-blur-[54.3px]" />;
+  }
+
+  const isSelected = theme === "dark";
+
+  const handleChange = (isSelected: boolean) => {
+    setTheme(isSelected ? "dark" : "light");
+  };
+
+  return (
+    <AriaSwitch
+      {...props}
+      aria-label="Theme switch"
+      className={composeTailwindRenderProps(props.className, wrapper())}
+      isSelected={isSelected}
+      onChange={handleChange}
+    >
+      {(renderProps) => (
+        <>
+          <div className={thumb(renderProps)} />
+          <Iconify className={icon()} icon="gravity-ui:sun" />
+          <Iconify className={icon()} icon="gravity-ui:moon" />
+        </>
+      )}
+    </AriaSwitch>
+  );
+}
diff --git a/apps/docs/src/components/horizontal-scrolling-banner.tsx b/apps/docs/src/components/horizontal-scrolling-banner.tsx
new file mode 100644
index 0000000..c9e40ab
--- /dev/null
+++ b/apps/docs/src/components/horizontal-scrolling-banner.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import React from "react";
+
+import {cn} from "@/utils/cn";
+
+interface HorizontalScrollingBannerProps {
+  children: React.ReactNode;
+  className?: string;
+  duration?: number; // in seconds
+  gap?: string;
+  isReverse?: boolean;
+  shouldPauseOnHover?: boolean;
+  showShadow?: boolean;
+  shadowSize?: string;
+}
+
+const HorizontalScrollingBanner = React.forwardRef<HTMLDivElement, HorizontalScrollingBannerProps>(
+  (
+    {
+      children,
+      className,
+      duration = 40,
+      gap = "1rem",
+      isReverse = false,
+      shadowSize = "60px",
+      shouldPauseOnHover = true,
+      showShadow = true,
+    },
+    ref,
+  ) => {
+    const maskImage = showShadow
+      ? `linear-gradient(to right, transparent, #000 ${shadowSize}, #000 calc(100% - ${shadowSize}), transparent)`
+      : undefined;
+
+    return (
+      <div
+        ref={ref}
+        className={cn("flex w-full overflow-x-hidden", className)}
+        style={
+          {
+            "--duration": `${duration}s`,
+            "--gap": gap,
+            WebkitMaskImage: maskImage,
+            maskImage,
+          } as React.CSSProperties
+        }
+      >
+        <div
+          className="flex w-max items-stretch"
+          style={{
+            animation: `scrolling-banner var(--duration) linear infinite`,
+            animationDirection: isReverse ? "reverse" : "normal",
+            gap: `var(--gap)`,
+          }}
+          onMouseEnter={(e) => {
+            if (shouldPauseOnHover) {
+              e.currentTarget.style.animationPlayState = "paused";
+            }
+          }}
+          onMouseLeave={(e) => {
+            if (shouldPauseOnHover) {
+              e.currentTarget.style.animationPlayState = "running";
+            }
+          }}
+        >
+          {/* Clone children and duplicate for seamless loop */}
+          {React.Children.map(children, (child, index) => (
+            <div key={`original-${index}`} className="shrink-0">
+              {React.cloneElement(child as React.ReactElement)}
+            </div>
+          ))}
+          {React.Children.map(children, (child, index) => (
+            <div key={`duplicate-${index}`} className="shrink-0">
+              {React.cloneElement(child as React.ReactElement)}
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+);
+
+HorizontalScrollingBanner.displayName = "HorizontalScrollingBanner";
+
+export default HorizontalScrollingBanner;
diff --git a/apps/docs/src/components/iconify.tsx b/apps/docs/src/components/iconify.tsx
new file mode 100644
index 0000000..3c7847d
--- /dev/null
+++ b/apps/docs/src/components/iconify.tsx
@@ -0,0 +1,128 @@
+import type {IconProps} from "@iconify/react";
+
+import {Icon} from "@iconify/react";
+import gravityIcons from "@iconify-json/gravity-ui/icons.json";
+import {forwardRef, useId, useMemo} from "react";
+
+export type IconifyProps = IconProps & {
+  icon?: IconProps["icon"] | string;
+};
+
+// Helper component to render SVG directly from icon data
+// This ensures consistent rendering between SSR and client
+// React 19 supports passing refs through props directly
+function SVGFromIconData({
+  iconData,
+  ref,
+  ...props
+}: {
+  iconData: {body: string; width?: number; height?: number};
+  ref?: React.Ref<SVGSVGElement>;
+} & Omit<IconProps, "icon">) {
+  const {className, height = "1em", style, width = "1em", ...restProps} = props;
+
+  const viewBox =
+    iconData.width && iconData.height ? `0 0 ${iconData.width} ${iconData.height}` : "0 0 16 16";
+
+  const uniqueId = useId().replace(/:/g, "");
+
+  const processedBody = useMemo(() => {
+    const {body} = iconData;
+
+    if (!body.includes("id=")) {
+      return body;
+    }
+
+    const regex = /\bid=["']([^"']+)["']|url\(#([^)]+)\)|(?:href|xlink:href)=["']#([^"']+)["']/g;
+
+    return body.replace(regex, (match, g1, g2, g3) => {
+      const id = g1 || g2 || g3;
+
+      if (!id) return match;
+
+      const newId = `${id}-${uniqueId}`;
+
+      if (g1) return `id="${newId}"`;
+      if (g2) return `url(#${newId})`;
+      if (g3) return `href="#${newId}"`;
+
+      return match;
+    });
+  }, [iconData.body, uniqueId]);
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={className}
+      height={height}
+      role="img"
+      style={style}
+      viewBox={viewBox}
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      xmlnsXlink="http://www.w3.org/1999/xlink"
+      {...restProps}
+      dangerouslySetInnerHTML={{__html: processedBody}}
+    />
+  );
+}
+
+const customIcons = {
+  "bulb-off": {
+    body: '<path fill-rule="evenodd" clip-rule="evenodd" d="M6.26 15.1091C6.8026 15.3712 7.39741 15.5073 8 15.5073C8.6026 15.5073 9.19741 15.3712 9.74 15.1091L9.87 15.0461C10.2085 14.8825 10.494 14.627 10.6939 14.3086C10.8937 13.9902 10.9998 13.622 11 13.2461V12.7781C11 11.4261 11.776 10.2211 12.54 9.10507C13.105 8.27879 13.4339 7.31397 13.491 6.3146C13.5482 5.31524 13.3315 4.31922 12.8644 3.43389C12.3973 2.54857 11.6974 1.80751 10.8402 1.29059C9.98302 0.77367 9.001 0.500488 8 0.500488C6.999 0.500488 6.01698 0.77367 5.15978 1.29059C4.30258 1.80751 3.6027 2.54857 3.13558 3.43389C2.66846 4.31922 2.45181 5.31524 2.50898 6.3146C2.56615 7.31397 2.89497 8.27879 3.46 9.10507C4.224 10.2211 5 11.4261 5 12.7791V13.2461C4.99998 13.6221 5.10598 13.9906 5.30586 14.3092C5.50573 14.6277 5.79137 14.8835 6.13 15.0471L6.26 15.1091ZM9.088 13.7591L9.218 13.6951C9.30253 13.6541 9.37381 13.5902 9.42368 13.5106C9.47356 13.431 9.50001 13.339 9.5 13.2451V12.7781C9.5 12.6081 9.50833 12.4414 9.525 12.2781C8.53004 12.5752 7.46996 12.5752 6.475 12.2781C6.491 12.4414 6.49933 12.6081 6.5 12.7781V13.2451C6.5 13.339 6.52645 13.431 6.57632 13.5106C6.62619 13.5902 6.69748 13.6541 6.782 13.6951L6.912 13.7581C7.25126 13.9221 7.62319 14.0072 8 14.0072C8.37681 14.0072 8.74875 13.9231 9.088 13.7591ZM4.698 8.25707C5.092 8.83307 5.589 9.55907 5.961 10.4051C6.57004 10.7938 7.27749 11.0003 8 11.0003C8.72251 11.0003 9.42996 10.7938 10.039 10.4051C10.411 9.55907 10.908 8.83307 11.303 8.25707C11.7137 7.6561 11.9526 6.95445 11.994 6.22773C12.0354 5.50101 11.8778 4.77677 11.538 4.13304C11.1982 3.48931 10.6892 2.95049 10.0659 2.57465C9.4425 2.19881 8.7284 2.00019 8.0005 2.00019C7.2726 2.00019 6.5585 2.19881 5.93514 2.57465C5.31178 2.95049 4.8028 3.48931 4.46302 4.13304C4.12325 4.77677 3.96557 5.50101 4.00698 6.22773C4.04839 6.95445 4.28731 7.6561 4.698 8.25707Z" fill="currentColor"/>',
+  },
+  figma: {
+    body: '<path d="M3.75 4.5C3.75 3.70435 4.06607 2.94129 4.62868 2.37868C5.19129 1.81607 5.95435 1.5 6.75 1.5H11.25C11.8594 1.49996 12.4543 1.6855 12.9557 2.03193C13.457 2.37835 13.8409 2.86924 14.0564 3.43925C14.2719 4.00927 14.3086 4.63139 14.1618 5.22281C14.015 5.81424 13.6915 6.34693 13.2345 6.75C13.7935 7.24186 14.1496 7.92403 14.2336 8.66387C14.3176 9.40371 14.1235 10.1484 13.6889 10.753C13.2544 11.3577 12.6106 11.7791 11.8826 11.9354C11.1546 12.0917 10.3944 11.9717 9.75 11.5988V13.5C9.74997 14.0013 9.62433 14.4946 9.38455 14.9348C9.14477 15.375 8.7985 15.7482 8.37738 16.0201C7.95626 16.292 7.4737 16.4541 6.97381 16.4915C6.47392 16.5289 5.97262 16.4404 5.51573 16.2342C5.05883 16.0279 4.6609 15.7105 4.35829 15.3108C4.05567 14.9112 3.85803 14.4421 3.78342 13.9464C3.7088 13.4507 3.7596 12.9442 3.93115 12.4731C4.10271 12.0021 4.38956 11.5816 4.7655 11.25C4.44631 10.9685 4.19069 10.6222 4.0156 10.2343C3.84052 9.84636 3.74998 9.42561 3.75 9C3.74998 8.57439 3.84052 8.15364 4.0156 7.76571C4.19069 7.37778 4.44631 7.03154 4.7655 6.75C4.44631 6.46846 4.19069 6.12222 4.0156 5.73429C3.84052 5.34636 3.74998 4.92561 3.75 4.5ZM8.25 7.5H6.75C6.35218 7.5 5.97065 7.65804 5.68934 7.93934C5.40804 8.22064 5.25 8.60218 5.25 9C5.25 9.39782 5.40804 9.77936 5.68934 10.0607C5.97065 10.342 6.35218 10.5 6.75 10.5H8.25V7.5ZM9.75 9C9.75 9.39782 9.90804 9.77936 10.1893 10.0607C10.4706 10.342 10.8522 10.5 11.25 10.5C11.6478 10.5 12.0294 10.342 12.3107 10.0607C12.592 9.77936 12.75 9.39782 12.75 9C12.75 8.60218 12.592 8.22064 12.3107 7.93934C12.0294 7.65804 11.6478 7.5 11.25 7.5C10.8522 7.5 10.4706 7.65804 10.1893 7.93934C9.90804 8.22064 9.75 8.60218 9.75 9ZM11.25 6C11.6478 6 12.0294 5.84196 12.3107 5.56066C12.592 5.27936 12.75 4.89782 12.75 4.5C12.75 4.10218 12.592 3.72064 12.3107 3.43934C12.0294 3.15804 11.6478 3 11.25 3H9.75V6H11.25ZM6.75 3C6.35218 3 5.97065 3.15804 5.68934 3.43934C5.40804 3.72064 5.25 4.10218 5.25 4.5C5.25 4.89782 5.40804 5.27936 5.68934 5.56066C5.97065 5.84196 6.35218 6 6.75 6H8.25V3H6.75ZM8.25 12H6.75C6.45333 12 6.16332 12.088 5.91665 12.2528C5.66997 12.4176 5.47771 12.6519 5.36418 12.926C5.25065 13.2001 5.22094 13.5017 5.27882 13.7926C5.3367 14.0836 5.47956 14.3509 5.68934 14.5607C5.89912 14.7704 6.16639 14.9133 6.45737 14.9712C6.74834 15.0291 7.04994 14.9994 7.32403 14.8858C7.59811 14.7723 7.83238 14.58 7.99721 14.3334C8.16203 14.0867 8.25 13.7967 8.25 13.5V12Z" fill="currentColor"/>',
+  },
+  "layout-header-cursor": {
+    body: '<path d="M3 2H11C11.8284 2 12.5 2.67157 12.5 3.5V7.25C12.5 7.66421 12.8358 8 13.25 8C13.6642 8 14 7.66421 14 7.25V3.5C14 1.84315 12.6569 0.5 11 0.5H3C1.34315 0.5 0 1.84315 0 3.5V9C0 10.6569 1.34315 12 3 12H5.75C6.16421 12 6.5 11.6642 6.5 11.25C6.5 10.8358 6.16421 10.5 5.75 10.5H3C2.17157 10.5 1.5 9.82843 1.5 9V3.5C1.5 2.67157 2.17157 2 3 2Z" fill="currentColor"/><path d="M9.22766 7.17179C9.00375 6.98682 8.69317 6.94775 8.43043 7.0715C8.16768 7.19525 8 7.45958 8 7.75001V13.2935C8 13.6119 8.201 13.8955 8.50136 14.0011C8.80172 14.1066 9.13598 14.011 9.33514 13.7627L10.2726 12.5606L11.0792 14.3354C11.2644 14.7059 11.7149 14.8561 12.0854 14.6708C12.4559 14.4856 12.6061 14.0351 12.4208 13.6646L11.594 12.0109H13C13.3164 12.0109 13.5987 11.8124 13.7058 11.5147C13.8128 11.217 13.7216 10.8841 13.4777 10.6827L9.22766 7.17179Z" fill="currentColor"/>',
+  },
+  "layout-selector-cursor": {
+    body: '<path fill-rule="evenodd" clip-rule="evenodd" d="M6.82025 1.72753C6.82025 1.53458 6.7436 1.34953 6.60716 1.21309C6.47072 1.07665 6.28567 1 6.09272 1C5.89976 1 5.71471 1.07665 5.57828 1.21309C5.44184 1.34953 5.36519 1.53458 5.36519 1.72753V3.18259C5.36519 3.37555 5.44184 3.5606 5.57828 3.69704C5.71471 3.83347 5.89976 3.91012 6.09272 3.91012C6.28567 3.91012 6.47072 3.83347 6.60716 3.69704C6.7436 3.5606 6.82025 3.37555 6.82025 3.18259V1.72753ZM3.52017 2.49144C3.45306 2.42195 3.37278 2.36653 3.28401 2.3284C3.19525 2.29027 3.09979 2.2702 3.00319 2.26936C2.90658 2.26852 2.81078 2.28693 2.72137 2.32351C2.63196 2.36009 2.55073 2.41411 2.48242 2.48242C2.41411 2.55073 2.36009 2.63196 2.32351 2.72137C2.28693 2.81078 2.26852 2.90658 2.26936 3.00319C2.2702 3.09979 2.29027 3.19525 2.3284 3.28401C2.36653 3.37278 2.42195 3.45306 2.49144 3.52017L3.52017 4.55035C3.58781 4.61799 3.66811 4.67165 3.75649 4.70826C3.84487 4.74487 3.9396 4.76371 4.03526 4.76371C4.13092 4.76371 4.22565 4.74487 4.31403 4.70826C4.40241 4.67165 4.48271 4.61799 4.55035 4.55035C4.61799 4.48271 4.67165 4.40241 4.70826 4.31403C4.74487 4.22565 4.76371 4.13092 4.76371 4.03526C4.76371 3.9396 4.74487 3.84487 4.70826 3.75649C4.67165 3.66811 4.61799 3.58781 4.55035 3.52017L3.52017 2.49144ZM6.66747 5.51797C5.95667 5.28079 5.28079 5.95667 5.51797 6.66747L8.08761 14.3778C8.34734 15.1578 9.42627 15.2203 9.77403 14.4753L11.2698 11.2698L14.4753 9.77475C15.2203 9.42699 15.1578 8.34734 14.3778 8.08761L6.66747 5.51797ZM9.03485 12.6187L7.24294 7.24294L12.6194 9.03485L10.4746 10.0352C10.2811 10.1255 10.1255 10.2811 10.0352 10.4746L9.03485 12.6187ZM9.694 2.49144C9.83039 2.62787 9.90701 2.81289 9.90701 3.0058C9.90701 3.19872 9.83039 3.38374 9.694 3.52017L8.66527 4.55035C8.59767 4.61795 8.51743 4.67157 8.42911 4.70815C8.34079 4.74473 8.24613 4.76356 8.15054 4.76356C8.05495 4.76356 7.96029 4.74473 7.87197 4.70815C7.78365 4.67157 7.70341 4.61795 7.63581 4.55035C7.56822 4.48276 7.5146 4.40251 7.47802 4.31419C7.44143 4.22588 7.4226 4.13122 7.4226 4.03562C7.4226 3.94003 7.44143 3.84537 7.47802 3.75705C7.5146 3.66874 7.56822 3.58849 7.63581 3.5209L8.66527 2.49217C8.8017 2.35578 8.98672 2.27916 9.17963 2.27916C9.37255 2.27916 9.55756 2.35505 9.694 2.49144ZM1 6.09272C1 5.89976 1.07665 5.71471 1.21309 5.57828C1.34953 5.44184 1.53458 5.36519 1.72753 5.36519H3.18259C3.37555 5.36519 3.5606 5.44184 3.69704 5.57828C3.83347 5.71471 3.91012 5.89976 3.91012 6.09272C3.91012 6.28567 3.83347 6.47072 3.69704 6.60716C3.5606 6.7436 3.37555 6.82025 3.18259 6.82025H1.72753C1.53458 6.82025 1.34953 6.7436 1.21309 6.60716C1.07665 6.47072 1 6.28567 1 6.09272ZM4.54962 8.66527C4.61722 8.59772 4.67085 8.51752 4.70745 8.42925C4.74405 8.34097 4.7629 8.24636 4.76294 8.1508C4.76297 8.05524 4.74418 7.96061 4.70765 7.87231C4.67111 7.78401 4.61754 7.70377 4.54999 7.63618C4.48244 7.56858 4.40224 7.51495 4.31397 7.47835C4.22569 7.44175 4.13108 7.4229 4.03552 7.42286C3.93996 7.42283 3.84533 7.44162 3.75703 7.47815C3.66873 7.51469 3.58849 7.56826 3.5209 7.63581L2.49144 8.666C2.35502 8.80251 2.27842 8.98762 2.27849 9.18062C2.27856 9.37361 2.35529 9.55867 2.4918 9.69509C2.62832 9.83151 2.81343 9.90811 3.00642 9.90804C3.19942 9.90797 3.38448 9.83124 3.5209 9.69472L4.54962 8.66527Z"/>',
+  },
+  openai: {
+    body: '<path fill="currentColor" d="M14.949 6.547a3.94 3.94 0 0 0-.348-3.273a4.11 4.11 0 0 0-4.4-1.934A4.1 4.1 0 0 0 8.423.2A4.15 4.15 0 0 0 6.305.086a4.1 4.1 0 0 0-1.891.948a4.04 4.04 0 0 0-1.158 1.753a4.1 4.1 0 0 0-1.563.679A4 4 0 0 0 .554 4.72a3.99 3.99 0 0 0 .502 4.731a3.94 3.94 0 0 0 .346 3.274a4.11 4.11 0 0 0 4.402 1.933c.382.425.852.764 1.377.995c.526.231 1.095.35 1.67.346c1.78.002 3.358-1.132 3.901-2.804a4.1 4.1 0 0 0 1.563-.68a4 4 0 0 0 1.14-1.253a3.99 3.99 0 0 0-.506-4.716m-6.097 8.406a3.05 3.05 0 0 1-1.945-.694l.096-.054l3.23-1.838a.53.53 0 0 0 .265-.455v-4.49l1.366.778q.02.011.025.035v3.722c-.003 1.653-1.361 2.992-3.037 2.996m-6.53-2.75a2.95 2.95 0 0 1-.36-2.01l.095.057L5.29 12.09a.53.53 0 0 0 .527 0l3.949-2.246v1.555a.05.05 0 0 1-.022.041L6.473 13.3c-1.454.826-3.311.335-4.15-1.098m-.85-6.94A3.02 3.02 0 0 1 3.07 3.949v3.785a.51.51 0 0 0 .262.451l3.93 2.237l-1.366.779a.05.05 0 0 1-.048 0L2.585 9.342a2.98 2.98 0 0 1-1.113-4.094zm11.216 2.571L8.747 5.576l1.362-.776a.05.05 0 0 1 .048 0l3.265 1.86a3 3 0 0 1 1.173 1.207a2.96 2.96 0 0 1-.27 3.2a3.05 3.05 0 0 1-1.36.997V8.279a.52.52 0 0 0-.276-.445m1.36-2.015l-.097-.057l-3.226-1.855a.53.53 0 0 0-.53 0L6.249 6.153V4.598a.04.04 0 0 1 .019-.04L9.533 2.7a3.07 3.07 0 0 1 3.257.139c.474.325.843.778 1.066 1.303c.223.526.289 1.103.191 1.664zM5.503 8.575L4.139 7.8a.05.05 0 0 1-.026-.037V4.049c0-.57.166-1.127.476-1.607s.752-.864 1.275-1.105a3.08 3.08 0 0 1 3.234.41l-.096.054l-3.23 1.838a.53.53 0 0 0-.265.455zm.742-1.577l1.758-1l1.762 1v2l-1.755 1l-1.762-1z"/>',
+  },
+  windows: {
+    body: '<path fill="currentColor" fill-rule="evenodd" d="m11.788 2.974l-3.038.434V7.25h4.75V4.459a1.5 1.5 0 0 0-1.712-1.485M13.5 8.75H8.75v3.842l3.038.434A1.5 1.5 0 0 0 13.5 11.54zm-6.25-1.5V3.622l-3.462.495A1.5 1.5 0 0 0 2.5 5.602V7.25zM2.5 8.75h4.75v3.628l-3.462-.495A1.5 1.5 0 0 1 2.5 10.398zm1.076-6.118A3 3 0 0 0 1 5.602v4.796a3 3 0 0 0 2.576 2.97l8 1.143A3 3 0 0 0 15 11.54V4.459a3 3 0 0 0-3.424-2.97z"/>',
+  },
+};
+
+const icons = {
+  ...gravityIcons.icons,
+  ...customIcons,
+};
+
+const Iconify = forwardRef<SVGSVGElement, IconifyProps>(({icon: iconProp, ...props}, ref) => {
+  // Check if it's a gravity-ui icon (no prefix or explicitly in gravity icons)
+  const isGravityIcon =
+    typeof iconProp === "string" && (iconProp in icons || iconProp.startsWith("gravity-ui:"));
+
+  // For gravity-ui icons, render SVG directly from icon data
+  // This ensures consistent rendering between SSR and client, avoiding hydration mismatch
+  if (isGravityIcon && typeof iconProp === "string") {
+    // Remove "gravity-ui:" prefix if present
+    const iconName = iconProp.replace(/^gravity-ui:/, "");
+    const gravityIconData = icons[iconName as keyof typeof icons];
+
+    if (gravityIconData) {
+      return <SVGFromIconData ref={ref} iconData={gravityIconData} {...props} />;
+    }
+  }
+
+  // Use online version for other icon sets (like simple-icons:vite, lineicons:nextjs)
+  // Icon component supports SSR, so this works consistently on both server and client
+  return (
+    <Icon
+      {...props}
+      ref={ref}
+      fallback={<SVGFromIconData iconData={icons["square"]} />}
+      icon={iconProp}
+    />
+  );
+});
+
+Iconify.displayName = "HeroUI.Iconify";
+
+export {Iconify};
diff --git a/apps/docs/src/components/locale-link.tsx b/apps/docs/src/components/locale-link.tsx
new file mode 100644
index 0000000..8e33613
--- /dev/null
+++ b/apps/docs/src/components/locale-link.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {LinkProps} from "fumadocs-core/link";
+import type {UrlObject} from "url";
+
+import {useParams} from "fumadocs-core/framework";
+import NextLink from "next/link";
+import {forwardRef, useMemo} from "react";
+
+import {i18n} from "@/lib/i18n";
+
+const LOCALE_PREFIX = /^\/(en|cn)(\/|$)/;
+
+/**
+ * Prefixes internal docs paths with `/[lang]` for dynamic resolution.
+ * Paths already localized or external are left unchanged.
+ */
+export function localizeHref(href?: string): string | undefined {
+  if (!href) return href;
+
+  if (
+    href.startsWith("http") ||
+    href.startsWith("mailto:") ||
+    href.startsWith("#") ||
+    href.startsWith("/[lang]")
+  ) {
+    return href;
+  }
+
+  if (LOCALE_PREFIX.test(href)) return href;
+  if (href.startsWith("/docs")) return `/[lang]${href}`;
+  if (href === "/themes" || href.startsWith("/themes/") || href.startsWith("/themes?")) {
+    return `/[lang]${href}`;
+  }
+  if (href === "/showcase" || href.startsWith("/showcase/") || href.startsWith("/showcase?")) {
+    return `/[lang]${href}`;
+  }
+
+  return href;
+}
+
+function resolveLocaleHref(
+  href: string | undefined,
+  params: Record<string, string | string[] | undefined>,
+): string | undefined {
+  const localized = localizeHref(href);
+
+  if (!localized) return localized;
+
+  return localized.replace(/\[(.*?)\]/g, (_, key: string) => {
+    const value = params[key];
+
+    if (!value) return i18n.defaultLanguage;
+
+    return typeof value === "string" ? value : value.join("/");
+  });
+}
+
+export const LocaleLink = forwardRef<HTMLAnchorElement, LinkProps>(function LocaleLink(
+  {children, external: externalProp, href = "#", prefetch, ...props},
+  ref,
+) {
+  const params = useParams();
+  const url = useMemo(() => resolveLocaleHref(href, params), [href, params]);
+  const external = externalProp ?? Boolean(url?.match(/^\w+:/) || url?.startsWith("//"));
+
+  if (external) {
+    return (
+      <a ref={ref} href={url} rel="noreferrer noopener" target="_blank" {...props}>
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <NextLink ref={ref} href={(url ?? "#") as unknown as UrlObject} prefetch={prefetch} {...props}>
+      {children}
+    </NextLink>
+  );
+});
diff --git a/apps/docs/src/components/native/component-item.tsx b/apps/docs/src/components/native/component-item.tsx
new file mode 100644
index 0000000..228e4bb
--- /dev/null
+++ b/apps/docs/src/components/native/component-item.tsx
@@ -0,0 +1,147 @@
+"use client";
+
+import type {StatusChipStatus} from "../status-chip";
+
+import {Link as LocalLinkIcon} from "@gravity-ui/icons";
+import {Link} from "@heroui/react";
+import LinkRoot from "fumadocs-core/link";
+
+import {useIsMobileDevice} from "@/hooks/use-is-mobile-device";
+import {cn} from "@/utils/cn";
+
+import StatusChip from "../status-chip";
+
+import {VideoPlayerView} from "./video-player-view";
+
+/**
+ * Title + optional status-chip pair, factored out so it can render inside
+ * both the in-page `NextLink` and the external `Link` variants without
+ * duplicating layout markup.
+ */
+function ComponentTitleContent({status, title}: {status?: StatusChipStatus; title: string}) {
+  return (
+    <div className="flex items-center gap-2">
+      {title}
+      {status ? <StatusChip className="w-fit" status={status} /> : null}
+    </div>
+  );
+}
+
+/**
+ * Helper that picks between Next.js client routing (`NextLink`) and the
+ * HeroUI `<Link>` based on whether the destination should open in a new tab.
+ */
+function ConditionalLink({
+  children,
+  className,
+  href,
+  openInNewTab,
+}: {
+  children: React.ReactNode;
+  className?: string;
+  href: string;
+  openInNewTab: boolean;
+}) {
+  const linkProps = openInNewTab
+    ? {rel: "noopener noreferrer" as const, target: "_blank" as const}
+    : {};
+
+  if (openInNewTab) {
+    return (
+      <Link className={cn(className, "no-underline")} href={href} {...linkProps}>
+        {children}
+      </Link>
+    );
+  }
+
+  return (
+    <LinkRoot className={className} href={href}>
+      {children}
+    </LinkRoot>
+  );
+}
+
+interface NativeComponentInfo {
+  name: string;
+  title: string;
+  description: string;
+  href: string;
+  category?: string;
+}
+
+interface ComponentItemProps extends React.ComponentProps<"div"> {
+  component: NativeComponentInfo;
+  srcLight: string;
+  srcDark: string;
+  className?: string;
+  status?: StatusChipStatus;
+  openInNewTab?: boolean;
+}
+
+/**
+ * ComponentItem renders a single native-component preview tile: a video
+ * (theme-aware) and the component's title with optional status chip. Used by
+ * {@link ComponentsCategory} to lay out the components-overview index.
+ *
+ * `target="auto"` on the inner VideoPlayerView is safe here because this
+ * component is only rendered from index pages that don't show the QR popover
+ * (`showQRCode={false}`) — the `target` is required by the type but never
+ * actually consumed.
+ */
+export function ComponentItem({
+  className,
+  component,
+  openInNewTab = false,
+  srcDark,
+  srcLight,
+  status,
+}: ComponentItemProps) {
+  const {href, title} = component;
+  const isMobile = useIsMobileDevice();
+
+  return (
+    <div className={cn("flex flex-col gap-[9px]", className)}>
+      {/* Title first on mobile, video first on desktop */}
+      <div className="order-1 sm:order-2">
+        {openInNewTab ? (
+          <Link className="no-underline" href={href} rel="noopener noreferrer" target="_blank">
+            <ComponentTitleContent status={status} title={title} />
+            <Link.Icon />
+          </Link>
+        ) : (
+          <ConditionalLink className="link no-underline" href={href} openInNewTab={openInNewTab}>
+            <ComponentTitleContent status={status} title={title} />
+            <LocalLinkIcon className="ml-1 size-3.5 text-muted" />
+          </ConditionalLink>
+        )}
+      </div>
+      <div className="relative order-2 overflow-hidden rounded-xl sm:order-1">
+        {isMobile ? (
+          <VideoPlayerView
+            autoPlay
+            className="w-full"
+            height={300}
+            playMode="auto"
+            showQRCode={false}
+            srcDark={srcDark}
+            srcLight={srcLight}
+            target="auto"
+          />
+        ) : (
+          <ConditionalLink className="block" href={href} openInNewTab={openInNewTab}>
+            <VideoPlayerView
+              autoPlay
+              className="w-full"
+              height={300}
+              playMode="auto"
+              showQRCode={false}
+              srcDark={srcDark}
+              srcLight={srcLight}
+              target="auto"
+            />
+          </ConditionalLink>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/native/components-category.tsx b/apps/docs/src/components/native/components-category.tsx
new file mode 100644
index 0000000..e47e5aa
--- /dev/null
+++ b/apps/docs/src/components/native/components-category.tsx
@@ -0,0 +1,220 @@
+import type {StatusChipStatus} from "../status-chip";
+
+import {cn} from "@/utils/cn";
+
+import {source} from "../../lib/source";
+
+import {ComponentItem} from "./component-item";
+
+/**
+ * Catalogue of every native component, grouped by category. This list mirrors
+ * the structure of `meta.json` under `content/docs/native/components` —
+ * keeping it in code (rather than auto-deriving from the filesystem) gives
+ * the docs team explicit control over category ordering and lets new
+ * components show up only after they're intentionally added here.
+ */
+const COMPONENT_GROUPS = [
+  {
+    category: "Buttons",
+    components: ["(buttons)/button", "(buttons)/close-button", "(buttons)/link-button"],
+  },
+  {
+    category: "Collections",
+    components: ["(collections)/menu", "(collections)/tag-group"],
+  },
+  {
+    category: "Controls",
+    components: ["(controls)/slider", "(controls)/switch"],
+  },
+  {
+    category: "Forms",
+    components: [
+      "(forms)/checkbox",
+      "(forms)/control-field",
+      "(forms)/description",
+      "(forms)/field-error",
+      "(forms)/input",
+      "(forms)/input-group",
+      "(forms)/input-otp",
+      "(forms)/label",
+      "(forms)/radio-group",
+      "(forms)/search-field",
+      "(forms)/select",
+      "(forms)/text-area",
+      "(forms)/text-field",
+    ],
+  },
+  {
+    category: "Navigation",
+    components: ["(navigation)/accordion", "(navigation)/list-group", "(navigation)/tabs"],
+  },
+  {
+    category: "Overlays",
+    components: [
+      "(overlays)/bottom-sheet",
+      "(overlays)/dialog",
+      "(overlays)/popover",
+      "(overlays)/toast",
+    ],
+  },
+  {
+    category: "Feedback",
+    components: [
+      "(feedback)/alert",
+      "(feedback)/skeleton",
+      "(feedback)/skeleton-group",
+      "(feedback)/spinner",
+    ],
+  },
+  {
+    category: "Layout",
+    components: ["(layout)/card", "(layout)/separator", "(layout)/surface"],
+  },
+  {
+    category: "Media",
+    components: ["(media)/avatar"],
+  },
+  {
+    category: "Data Display",
+    components: ["(data-display)/chip"],
+  },
+  {
+    category: "Typography",
+    components: ["(typography)/text"],
+  },
+  {
+    category: "Utilities",
+    components: ["(utilities)/pressable-feedback", "(utilities)/scroll-shadow"],
+  },
+] as const;
+
+const componentStatusIcons = ["preview", "new", "updated", "new-dot"];
+
+const VIDEO_BASE_URL =
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos";
+
+interface ComponentWithStatus {
+  component: {
+    name: string;
+    title: string;
+    description: string;
+    href: string;
+    category?: string;
+  };
+  srcLight: string;
+  srcDark: string;
+  status?: StatusChipStatus;
+}
+
+interface ComponentCategory {
+  category: string;
+  locale: string;
+}
+
+function getComponentNameFromPath(path: string): string {
+  return path.split("/").pop() || path;
+}
+
+/**
+ * Overrides for components whose preview video filename doesn't match the
+ * component name 1:1. Right now only `skeleton-group` reuses the `skeleton`
+ * video — the rest fall through to the default name-based pattern.
+ */
+const VIDEO_NAME_OVERRIDES: Record<string, string> = {
+  "skeleton-group": "skeleton",
+};
+
+function constructVideoUrls(componentName: string): {srcLight: string; srcDark: string} {
+  const videoName = VIDEO_NAME_OVERRIDES[componentName.toLowerCase()] || componentName;
+  const baseName = videoName.toLowerCase();
+
+  return {
+    srcDark: `${VIDEO_BASE_URL}/${baseName}-docs-dark.mp4`,
+    srcLight: `${VIDEO_BASE_URL}/${baseName}-docs-light.mp4`,
+  };
+}
+
+function isRouteGroup(part: string): boolean {
+  return part.startsWith("(") && part.endsWith(")");
+}
+
+/**
+ * Pull metadata for a single component out of Fumadocs' page tree. Returns
+ * `null` when the page isn't found so the caller can `.filter()` missing
+ * entries away without throwing.
+ */
+function getComponentWithStatus(path: string, locale: string): ComponentWithStatus | null {
+  // Route groups (parentheses) are part of the file path but filtered out
+  // in URL paths. So `(buttons)/button` becomes `button` in the URL.
+  const pathWithoutRouteGroups = path
+    .split("/")
+    .filter((part) => !isRouteGroup(part))
+    .join("/");
+
+  const pagePath = ["native", "components", ...pathWithoutRouteGroups.split("/")].filter(Boolean);
+  const page = source.getPage(pagePath, locale);
+
+  if (!page) return null;
+
+  const title = page.data.title || "";
+  const description = page.data.description || "";
+  const componentName = getComponentNameFromPath(path);
+
+  const icon = page.data.icon;
+  const status: StatusChipStatus | undefined =
+    icon && componentStatusIcons.includes(icon) ? (icon as StatusChipStatus) : undefined;
+
+  const {srcDark, srcLight} = constructVideoUrls(componentName);
+
+  return {
+    component: {
+      category: undefined,
+      description,
+      href: page.url,
+      name: componentName,
+      title,
+    },
+    srcDark,
+    srcLight,
+    status,
+  };
+}
+
+/**
+ * Render a single category section of the components overview, used in
+ * MDX as `<ComponentsCategory category="Forms" />`.
+ *
+ * Renders nothing when the category name isn't recognised or when every
+ * component in the category fails to resolve to a page — this keeps the MDX
+ * surface forgiving while a category is being built out.
+ */
+export function ComponentsCategory({category, locale}: ComponentCategory) {
+  const group = COMPONENT_GROUPS.find((group) => group.category === category);
+
+  if (!group) return null;
+
+  const components = group.components
+    .map((path) => getComponentWithStatus(path, locale))
+    .filter((item): item is ComponentWithStatus => item !== null);
+
+  if (components.length === 0) return null;
+
+  return (
+    <div className={cn("not-prose flex flex-col gap-12")}>
+      <div key={group.category} className="flex flex-col gap-6">
+        <div className={cn("grid grid-cols-1 gap-x-4 gap-y-10 sm:grid-cols-2")}>
+          {components.map(({component, srcDark, srcLight, status}) => (
+            <ComponentItem
+              key={component.name}
+              component={component}
+              openInNewTab={false}
+              srcDark={srcDark}
+              srcLight={srcLight}
+              status={status}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/native/deep-link-qr-code.tsx b/apps/docs/src/components/native/deep-link-qr-code.tsx
new file mode 100644
index 0000000..cc74f77
--- /dev/null
+++ b/apps/docs/src/components/native/deep-link-qr-code.tsx
@@ -0,0 +1,131 @@
+"use client";
+
+import {Link} from "@heroui/react";
+import {ReactQRCode} from "@lglab/react-qr-code";
+
+import {NATIVE_APP} from "@/config/native-app";
+import {useIsMobileDevice} from "@/hooks/use-is-mobile-device";
+
+import {HeroUIPlainLogo} from "../heroui-plain-logo";
+
+/**
+ * In-app route segment that hosts component screens. This matches the
+ * `app/components/[slug].tsx` Expo Router file in the native app — it is part
+ * of the deep-linking contract between the docs site and the native app.
+ *
+ * The native app's `+native-intent.ts` only rewrites `https:` URLs (those
+ * coming via Universal Links / App Links). For our custom-scheme URLs it
+ * returns the path unchanged and Expo Router routes it natively, which means
+ * the URL must already encode the in-app route — i.e.
+ * `herouinative://components/{slug}` becomes `/components/{slug}` and
+ * `herouinative://` opens the initial route.
+ */
+const IN_APP_COMPONENT_PATH = "components";
+
+/**
+ * Convert the canonical Universal Link URL into the matching custom-scheme
+ * URL that Expo Router can navigate without going through `+native-intent`.
+ *
+ * Examples:
+ *  - `https://heroui.com/docs/native-showcase/components/button` ->
+ *    `herouinative://components/button`
+ *  - `https://heroui.com/docs/native-showcase/components/`       ->
+ *    `herouinative://`  (open at the app's initial route)
+ *  - `""` (origin not yet resolved on the client) -> `""`
+ */
+function toCustomSchemeUrl(universalLinkUrl: string): string {
+  if (!universalLinkUrl) return "";
+
+  const prefixIdx = universalLinkUrl.indexOf(NATIVE_APP.SHOWCASE_PATH_PREFIX);
+
+  if (prefixIdx === -1) return `${NATIVE_APP.SCHEME}://`;
+
+  const remainder = universalLinkUrl.slice(prefixIdx + NATIVE_APP.SHOWCASE_PATH_PREFIX.length);
+  const slug = remainder.replace(/^\//, "").split("/")[0] ?? "";
+
+  return slug
+    ? `${NATIVE_APP.SCHEME}://${IN_APP_COMPONENT_PATH}/${slug}`
+    : `${NATIVE_APP.SCHEME}://`;
+}
+
+interface DeepLinkQRCodeProps {
+  /**
+   * The Universal Link URL to encode into the QR code (desktop) or display as
+   * a tap-to-open link (mobile). When empty, both renderings collapse to a
+   * harmless placeholder so the component can render before the client-side
+   * `window.location.origin` resolves (avoids hydration mismatches).
+   */
+  url: string;
+  /**
+   * QR code edge length, in CSS pixels. The container is always sized to a
+   * perfect square so the QR has consistent surroundings regardless of
+   * `level`/error-correction settings.
+   * @default 160
+   */
+  size?: number;
+}
+
+/**
+ * Render a styled QR code on desktop or a tap-to-open link card on mobile.
+ *
+ * This primitive is shared between the popover (small, inside a dialog) and
+ * the full-width "Try on Device" section (large, embedded in MDX). It owns
+ * the desktop/mobile branching so call sites don't have to repeat
+ * `useIsMobileDevice()` checks.
+ */
+export const DeepLinkQRCode = ({size = 160, url}: DeepLinkQRCodeProps) => {
+  const isMobile = useIsMobileDevice();
+
+  if (isMobile) {
+    // Tapping a Universal Link from inside Safari to the same domain does NOT
+    // trigger iOS's app handoff — Safari treats it as an in-page navigation.
+    // So on mobile we fire the custom URL scheme directly, encoded in the
+    // shape Expo Router's deep-link handler expects:
+    // `herouinative://components/{slug}` (or `herouinative://` for home).
+    // The native app's `+native-intent.ts` deliberately only rewrites
+    // `https:` URLs and returns custom-scheme paths unchanged, so the URL
+    // itself must already be in the in-app route format.
+    const mobileUrl = toCustomSchemeUrl(url);
+
+    return (
+      <Link
+        className="mt-1 mb-3 flex w-full flex-col items-center justify-center gap-3 border border-dashed border-border px-2 py-4 no-underline"
+        href={mobileUrl || "#"}
+      >
+        <div className="grid size-10 shrink-0 place-items-center rounded-xl bg-foreground text-background">
+          <HeroUIPlainLogo size={18} />
+        </div>
+        <div className="flex flex-1 flex-col items-center justify-center">
+          <span className="truncate text-sm font-semibold text-foreground">{NATIVE_APP.NAME}</span>
+          <span className="truncate text-xs text-muted">Tap to launch the app</span>
+        </div>
+      </Link>
+    );
+  }
+
+  return (
+    <div className="flex items-center justify-center" style={{height: size, width: size}}>
+      {!!url && (
+        <ReactQRCode
+          background="transparent"
+          level="M"
+          size={size}
+          value={url}
+          dataModulesSettings={{
+            color: "var(--foreground)",
+            randomSize: true,
+            style: "circle",
+          }}
+          finderPatternInnerSettings={{
+            color: "var(--foreground)",
+            style: "square",
+          }}
+          finderPatternOuterSettings={{
+            color: "var(--foreground)",
+            style: "rounded",
+          }}
+        />
+      )}
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/native/download-app-banner.tsx b/apps/docs/src/components/native/download-app-banner.tsx
new file mode 100644
index 0000000..099a58c
--- /dev/null
+++ b/apps/docs/src/components/native/download-app-banner.tsx
@@ -0,0 +1,40 @@
+import type {FC} from "react";
+
+import {NATIVE_APP} from "@/config/native-app";
+
+import {HeroUILogo} from "../heroui-logo";
+
+import {StoreButtons} from "./store-buttons";
+
+/**
+ * Full-screen "Download the App" fallback rendered at
+ * `/docs/native-showcase/components/{slug}` when the visitor doesn't have
+ * the HeroUI Native app installed.
+ *
+ * The native app's Associated Domains + `+native-intent` redirect intercept
+ * matching URLs before this page is ever loaded; this component is only what
+ * the user actually sees when:
+ *  - they scan the QR code from a desktop browser, or
+ *  - the app is not installed on their iOS/Android device.
+ *
+ * Server-rendered: no client hooks are used so the page is fully static and
+ * shows up instantly with no client JS dependency.
+ */
+export const DownloadAppBanner: FC = () => {
+  return (
+    <main className="flex min-h-svh flex-col items-center justify-center gap-8 p-6">
+      <HeroUILogo />
+      <div className="flex max-w-md flex-col items-center gap-4 text-center">
+        <h1 className="font-heading text-3xl font-semibold tracking-tight">Download the App</h1>
+        <p className="text-sm leading-relaxed text-muted">
+          {[
+            "This content is available inside the ",
+            NATIVE_APP.NAME,
+            " app. Install it from the App Store or Google Play to preview this component live on your device.",
+          ].join("")}
+        </p>
+      </div>
+      <StoreButtons className="flex w-full max-w-xs flex-col items-stretch gap-3" size="md" />
+    </main>
+  );
+};
diff --git a/apps/docs/src/components/native/image-hero-view.tsx b/apps/docs/src/components/native/image-hero-view.tsx
new file mode 100644
index 0000000..805a8e3
--- /dev/null
+++ b/apps/docs/src/components/native/image-hero-view.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {NativeQRPreviewTarget} from "./qr-preview-popover/target";
+
+import {DocsImage} from "../docs-image";
+
+import {QRPreviewPopover} from "./qr-preview-popover";
+import {pickNativeQRTarget} from "./qr-preview-popover/target";
+
+/**
+ * Props for {@link ImageHeroView}. The QR popover's `target` discriminator
+ * is required at the call site so it has to make an explicit decision about
+ * which app screen the QR should deep-link into.
+ *
+ * The hero only renders a single image so it has no additional props beyond
+ * the QR target — `ImageHeroViewProps` is simply a type alias for the
+ * discriminator.
+ */
+export type ImageHeroViewProps = NativeQRPreviewTarget;
+
+/**
+ * ImageHeroView pairs the HeroUI Native OG hero image with the QR popover.
+ * Used by the docs landing page to introduce the library while letting
+ * desktop visitors jump straight into the app from the same surface.
+ */
+export const ImageHeroView = (props: ImageHeroViewProps) => {
+  return (
+    <div className="flex flex-col items-end gap-4">
+      <QRPreviewPopover {...pickNativeQRTarget(props)} />
+      <DocsImage
+        alt="HeroUI Native Introduction"
+        darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp"
+        src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp"
+      />
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/native/index.ts b/apps/docs/src/components/native/index.ts
new file mode 100644
index 0000000..6588873
--- /dev/null
+++ b/apps/docs/src/components/native/index.ts
@@ -0,0 +1,11 @@
+export {ComponentItem} from "./component-item";
+export {ComponentsCategory} from "./components-category";
+export {DeepLinkQRCode} from "./deep-link-qr-code";
+export {DownloadAppBanner} from "./download-app-banner";
+export {ImageHeroView} from "./image-hero-view";
+export {QRPreviewPopover, pickNativeQRTarget} from "./qr-preview-popover";
+export type {NativeQRPreviewTarget} from "./qr-preview-popover";
+export {StoreButtonsLocalized} from "./store-buttons-localized";
+export {StoreButtons, StoreButtonsView} from "./store-buttons";
+export {TryOnDevice} from "./try-on-device";
+export {VideoPlayerView} from "./video-player-view";
diff --git a/apps/docs/src/components/native/qr-preview-popover/index.ts b/apps/docs/src/components/native/qr-preview-popover/index.ts
new file mode 100644
index 0000000..4312713
--- /dev/null
+++ b/apps/docs/src/components/native/qr-preview-popover/index.ts
@@ -0,0 +1,3 @@
+export {QRPreviewPopover} from "./qr-preview-popover";
+export {pickNativeQRTarget} from "./target";
+export type {NativeQRPreviewTarget} from "./target";
diff --git a/apps/docs/src/components/native/qr-preview-popover/qr-preview-popover.tsx b/apps/docs/src/components/native/qr-preview-popover/qr-preview-popover.tsx
new file mode 100644
index 0000000..4a2c535
--- /dev/null
+++ b/apps/docs/src/components/native/qr-preview-popover/qr-preview-popover.tsx
@@ -0,0 +1,140 @@
+"use client";
+
+import type {NativeQRPreviewTarget} from "./target";
+
+import {Button, Popover} from "@heroui/react";
+import {usePathname} from "next/navigation";
+import {useState} from "react";
+
+import {NATIVE_APP} from "@/config/native-app";
+import {useDictionary} from "@/hooks/use-dictionary";
+import {useIsMobileDevice} from "@/hooks/use-is-mobile-device";
+import {i18n} from "@/lib/i18n";
+
+import {Iconify} from "../../iconify";
+import {DeepLinkQRCode} from "../deep-link-qr-code";
+import {StoreButtonsLocalized} from "../store-buttons-localized";
+
+/**
+ * Read `window.location.origin` synchronously when running in the browser.
+ * Returns the empty string on the server so SSR markup is deterministic and
+ * hydrates cleanly. Used as a `useState` lazy initialiser to keep the call
+ * site free of `useEffect` + `setState` (which triggers React's
+ * cascading-render lint warning).
+ */
+function readOrigin(): string {
+  if (typeof window === "undefined") {
+    return "";
+  }
+
+  return window.location.origin;
+}
+
+/**
+ * Regex matching the docs-app pathname for an individual Native component
+ * page. Group 1 captures the slug. `usePathname()` returns the full browser
+ * pathname (the docs site does NOT set a Next.js `basePath` — the leading
+ * `/{lang}/docs` is a real route segment from the `[lang]` route param), so
+ * the regex must include both the locale prefix and `/docs`. The locale
+ * alternation is built from {@link i18n.languages} so the two stay in sync
+ * automatically when a new language is added. Fumadocs route groups like
+ * `(buttons)` are stripped from the URL, but the optional non-capturing
+ * group keeps the regex defensive against any future inclusion.
+ */
+const COMPONENT_PATHNAME = new RegExp(
+  `^/(?:${i18n.languages.join("|")})/docs/native/components/(?:\\([^)]+\\)/)?([^/]+)$`,
+);
+
+/**
+ * Resolve which native-app screen the QR should deep-link into based on the
+ * popover's `target` discriminator and the current page's pathname.
+ *
+ * The function deliberately returns `""` for the home target (rather than a
+ * literal sentinel like `"home"`) because the empty slug is what makes
+ * `buildDeepLinkUrl` produce `<prefix>/` — the canonical home URL.
+ */
+function resolveSlug(target: NativeQRPreviewTarget, pathname: string): string {
+  if (target.target === "component") {
+    return target.slug;
+  }
+
+  if (target.target === "home") {
+    return "";
+  }
+
+  const match = COMPONENT_PATHNAME.exec(pathname);
+
+  if (match?.[1]) {
+    return match[1];
+  }
+
+  // We only escalate to a thrown error in the browser during development.
+  // Throwing during SSR would break the build; throwing in production would
+  // crash a live doc page just because the MDX author forgot to set the
+  // target. The console message + graceful fallback to home is the safer
+  // production behaviour.
+  if (process.env["NODE_ENV"] !== "production" && typeof window !== "undefined") {
+    throw new Error(
+      [
+        `QRPreviewPopover: target="auto" used on a non-component page `,
+        `(pathname="${pathname}"). Pass target="home" for the app home screen, `,
+        `or target="component" with a slug to deep-link to a specific component.`,
+      ].join(""),
+    );
+  }
+
+  return "";
+}
+
+/**
+ * Construct the Universal Link URL the QR code (or mobile tap link) encodes.
+ * `origin` is supplied at runtime so the URL always reflects the current
+ * environment (`localhost:3000` in dev, `heroui.com` in prod, preview URLs in
+ * Vercel previews, etc.) without hard-coding the host.
+ */
+function buildDeepLinkUrl(origin: string, slug: string): string {
+  const base = `${origin}${NATIVE_APP.SHOWCASE_PATH_PREFIX}`;
+
+  return slug ? `${base}/${slug}` : `${base}/`;
+}
+
+/**
+ * QRPreviewPopover renders a "Scan to preview" button on each Native component
+ * doc page. On desktop, clicking it opens a popover with a QR code. On mobile,
+ * the popover shows a tap-to-open link card instead.
+ *
+ * The required `target` prop forces the call site to decide whether the QR
+ * should deep-link to the current page's component (`"auto"`), the app's
+ * home screen (`"home"`), or an explicit component (`"component"` + slug).
+ */
+export const QRPreviewPopover = (props: NativeQRPreviewTarget) => {
+  const dict = useDictionary().qrPreviewPopover;
+  const isMobile = useIsMobileDevice();
+  const pathname = usePathname();
+
+  // Lazy initializer reads `window.location.origin` once during mount on the
+  // client; on the server it returns "" so the markup is identical between
+  // SSR and the first client render (no hydration mismatch).
+  const [origin] = useState<string>(readOrigin);
+
+  const slug = resolveSlug(props, pathname);
+  const deepLinkUrl = origin ? buildDeepLinkUrl(origin, slug) : "";
+  const triggerLabel = isMobile ? dict.tapToPreview : dict.scanToPreview;
+  const downloadPrompt = dict.downloadPrompt.replace("{name}", NATIVE_APP.NAME);
+
+  return (
+    <Popover>
+      <Button aria-label={triggerLabel} className="bg-default/70" size="sm" variant="tertiary">
+        {!isMobile && <Iconify icon="gravity-ui:qr-code" width={16} />}
+        {triggerLabel}
+      </Button>
+      <Popover.Content className="max-w-[240px] rounded-2xl" offset={6} placement="bottom end">
+        <Popover.Dialog className="flex flex-col items-center gap-4 px-5 pb-6">
+          <DeepLinkQRCode size={160} url={deepLinkUrl} />
+          <span className="mb-2 text-center text-xs text-foreground">{downloadPrompt}</span>
+          <StoreButtonsLocalized />
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+};
diff --git a/apps/docs/src/components/native/qr-preview-popover/target.ts b/apps/docs/src/components/native/qr-preview-popover/target.ts
new file mode 100644
index 0000000..45f69b3
--- /dev/null
+++ b/apps/docs/src/components/native/qr-preview-popover/target.ts
@@ -0,0 +1,44 @@
+/**
+ * Discriminated union describing which screen the QR code should deep-link
+ * into when the native HeroUI app intercepts the URL.
+ *
+ * - `target: "auto"` derives the slug from `usePathname()` inside the
+ *   popover. Only valid on pages whose URL matches `/native/components/{slug}`.
+ *   Using it elsewhere throws in development to surface the bug at edit time;
+ *   in production it silently falls back to the home target so a missed MDX
+ *   edit never breaks a live page.
+ * - `target: "home"` opens the app's home screen. Encoded as
+ *   `${origin}${SHOWCASE_PATH_PREFIX}/` (trailing slash), which is matched
+ *   by Apple's `*` glob in apple-app-site-association.
+ * - `target: "component"` deep-links to an explicit component, even when the
+ *   surrounding page is NOT a component page (e.g. release notes that demo
+ *   `area-chart`).
+ *
+ * Required at every level - both the `QRPreviewPopover` itself and the
+ * wrapper components (`VideoPlayerView`, `ImageHeroView`). There is no
+ * default value. The whole point is to force every call site to make a
+ * deliberate choice so the deep-link can never silently encode the wrong
+ * screen.
+ */
+export type NativeQRPreviewTarget =
+  | {target: "auto"}
+  | {target: "home"}
+  | {target: "component"; slug: string};
+
+/**
+ * Narrow a larger props object (e.g. wrapper-component props that also carry
+ * video URLs, CSS classes, etc.) down to the popover's `NativeQRPreviewTarget`
+ * shape. Reconstructs the discriminator so the popover receives ONLY the
+ * fields it expects - no leaked `srcLight`, `showQRCode`, etc.
+ *
+ * @param props - Any object that satisfies {@link NativeQRPreviewTarget}.
+ * @returns A clean {@link NativeQRPreviewTarget} ready to spread onto the
+ *   popover.
+ */
+export function pickNativeQRTarget(props: NativeQRPreviewTarget): NativeQRPreviewTarget {
+  if (props.target === "component") {
+    return {slug: props.slug, target: "component"};
+  }
+
+  return {target: props.target};
+}
diff --git a/apps/docs/src/components/native/store-buttons-localized.tsx b/apps/docs/src/components/native/store-buttons-localized.tsx
new file mode 100644
index 0000000..e3ccd96
--- /dev/null
+++ b/apps/docs/src/components/native/store-buttons-localized.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+import {StoreButtonsView} from "./store-buttons";
+
+interface StoreButtonsLocalizedProps {
+  /**
+   * Button size variant. Controls padding and the icon's pixel size so the
+   * buttons can sit either inside a small popover (`"sm"`) or as the
+   * full-page CTA on the download banner (`"md"`).
+   * @default "sm"
+   */
+  size?: "sm" | "md";
+  /**
+   * Additional CSS class for the wrapping `<div>`. Lets the parent control
+   * width and spacing without StoreButtons baking in a max-width.
+   */
+  className?: string;
+}
+
+/**
+ * Localized App Store / Play Store buttons for docs content.
+ *
+ * Reads its copy from the active `DictionaryProvider` via {@link useDictionary},
+ * so it MUST be rendered inside the `[lang]` provider tree (e.g. the QR preview
+ * popover and the "try on device" section). For the locale-less Universal Links
+ * fallback page, use the static `StoreButtons` instead.
+ */
+export const StoreButtonsLocalized = ({className, size = "sm"}: StoreButtonsLocalizedProps) => {
+  const labels = useDictionary().storeButtons;
+
+  return <StoreButtonsView className={className} labels={labels} size={size} />;
+};
diff --git a/apps/docs/src/components/native/store-buttons.tsx b/apps/docs/src/components/native/store-buttons.tsx
new file mode 100644
index 0000000..f92d3e4
--- /dev/null
+++ b/apps/docs/src/components/native/store-buttons.tsx
@@ -0,0 +1,138 @@
+import type {Dictionary} from "@/lib/dictionaries";
+
+import {NATIVE_APP} from "@/config/native-app";
+
+import {Iconify} from "../iconify";
+
+/**
+ * Shape of the localized strings consumed by the store buttons. Mirrors the
+ * `storeButtons` slice of the docs dictionary so the localized and static
+ * variants share a single, type-safe contract.
+ */
+export type StoreButtonsLabels = Dictionary["storeButtons"];
+
+/**
+ * English fallback strings used by the static {@link StoreButtons} variant,
+ * which renders on the locale-less Universal Links page at
+ * `/docs/native-showcase/components/{slug}` where no `DictionaryProvider` is
+ * mounted.
+ */
+const DEFAULT_STORE_BUTTONS: StoreButtonsLabels = {
+  androidComingSoon: "Android · Coming soon",
+  androidComingSoonLabel: "Android version coming soon",
+  appStore: "Download on App Store",
+  appStoreLabel: "Download {name} on the App Store",
+  playStore: "Download on Play Store",
+  playStoreLabel: "Download {name} on Google Play",
+};
+
+interface StoreButtonsViewProps {
+  /**
+   * Localized strings to render. Supplied by the static variant (English
+   * defaults) or the localized variant (dictionary-backed).
+   */
+  labels: StoreButtonsLabels;
+  /**
+   * Button size variant. Controls padding and the icon's pixel size so the
+   * buttons can sit either inside a small popover (`"sm"`) or as the
+   * full-page CTA on the download banner (`"md"`).
+   * @default "sm"
+   */
+  size?: "sm" | "md";
+  /**
+   * Additional CSS class for the wrapping `<div>`. Lets the parent control
+   * width and spacing without StoreButtons baking in a max-width.
+   */
+  className?: string;
+}
+
+/**
+ * Presentational App Store / Play Store buttons.
+ *
+ * This component holds the shared markup for both the static and localized
+ * variants and receives its copy via the `labels` prop. It has no hooks, so it
+ * renders in both server and client contexts.
+ *
+ * When `NATIVE_APP.PLAY_STORE_URL` is `null` (Android build not yet
+ * published), the Play Store button is automatically replaced with a disabled
+ * "Coming soon" placeholder that preserves layout. Setting the URL in the
+ * config flips both this surface and the in-popover variant simultaneously —
+ * no other code changes are required.
+ */
+export const StoreButtonsView = ({className, labels, size = "sm"}: StoreButtonsViewProps) => {
+  // The button system uses BEM modifiers — only `--sm` exists; `--md` is the
+  // default and produced by omitting the modifier.
+  const sizeClass = size === "sm" ? "button--sm" : "";
+  const iconSize = size === "sm" ? 18 : 20;
+
+  const appStoreLabel = labels.appStoreLabel.replace("{name}", NATIVE_APP.NAME);
+  const playStoreLabel = labels.playStoreLabel.replace("{name}", NATIVE_APP.NAME);
+
+  return (
+    <div className={className ?? "flex w-full flex-col items-stretch gap-2"}>
+      <a
+        aria-label={appStoreLabel}
+        className={["button button--primary w-full justify-center", sizeClass].join(" ")}
+        href={NATIVE_APP.APP_STORE_URL}
+        rel="noopener noreferrer"
+        target="_blank"
+      >
+        <Iconify icon="tabler:brand-apple-filled" width={iconSize} />
+        {labels.appStore}
+      </a>
+      {NATIVE_APP.PLAY_STORE_URL ? (
+        <a
+          aria-label={playStoreLabel}
+          className={["button button--tertiary w-full justify-center", sizeClass].join(" ")}
+          href={NATIVE_APP.PLAY_STORE_URL}
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          <Iconify icon="simple-icons:googleplay" width={iconSize} />
+          {labels.playStore}
+        </a>
+      ) : (
+        // `role="link"` + `aria-disabled` keeps the placeholder semantically
+        // a "disabled link" rather than a button — matching how iOS surfaces
+        // unavailable App Store entries.
+        <span
+          aria-disabled="true"
+          aria-label={labels.androidComingSoonLabel}
+          role="link"
+          className={[
+            "button button--tertiary w-full cursor-not-allowed justify-center opacity-50",
+            sizeClass,
+          ].join(" ")}
+        >
+          <Iconify icon="simple-icons:googleplay" width={iconSize} />
+          {labels.androidComingSoon}
+        </span>
+      )}
+    </div>
+  );
+};
+
+interface StoreButtonsProps {
+  /**
+   * Button size variant. @see StoreButtonsViewProps.size
+   * @default "sm"
+   */
+  size?: "sm" | "md";
+  /**
+   * Additional CSS class for the wrapping `<div>`.
+   * @see StoreButtonsViewProps.className
+   */
+  className?: string;
+}
+
+/**
+ * Static, English-only store buttons for the locale-less Universal Links
+ * fallback page (`/docs/native-showcase/components/{slug}`).
+ *
+ * This variant has no client hooks and does NOT depend on a
+ * `DictionaryProvider`, so the surrounding page renders fully statically. For
+ * localized docs content, use `StoreButtonsLocalized` instead.
+ */
+export const StoreButtons = ({className, size = "sm"}: StoreButtonsProps) => (
+  <StoreButtonsView className={className} labels={DEFAULT_STORE_BUTTONS} size={size} />
+);
diff --git a/apps/docs/src/components/native/try-on-device.tsx b/apps/docs/src/components/native/try-on-device.tsx
new file mode 100644
index 0000000..c745dac
--- /dev/null
+++ b/apps/docs/src/components/native/try-on-device.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import {useState} from "react";
+
+import {NATIVE_APP} from "@/config/native-app";
+
+import {DeepLinkQRCode} from "./deep-link-qr-code";
+import {StoreButtonsLocalized} from "./store-buttons-localized";
+
+/**
+ * Read `window.location.origin` synchronously when running in the browser.
+ * Returns the empty string on the server so the first render produces a
+ * deterministic markup that hydrates cleanly once React picks up the client
+ * state. We avoid `useEffect` + `setState` to sidestep the cascading-render
+ * warning emitted by `react-hooks/set-state-in-effect`.
+ */
+function readOrigin(): string {
+  if (typeof window === "undefined") {
+    return "";
+  }
+
+  return window.location.origin;
+}
+
+/**
+ * TryOnDevice
+ *
+ * Drop-in MDX section for release notes pages. Renders a QR code (desktop) or
+ * a tap-to-open link (mobile) that deep-links into the HeroUI Native app's
+ * home screen via Universal Links.
+ *
+ * Below the QR code, App Store and Play Store buttons are shown so users
+ * without the app installed can grab it directly from the same surface.
+ *
+ * `NATIVE_APP.SHOWCASE_PATH_PREFIX` + `/` (trailing slash) is the canonical
+ * "home" target — it matches Apple's AASA paths glob
+ * (`/docs/native-showcase/components/*`) and is recognised by the native
+ * app's `+native-intent` redirect as the app-root entrypoint.
+ */
+export const TryOnDevice = () => {
+  // Lazy initializer reads `window.location.origin` once during mount on the
+  // client; on the server it returns "" so the markup is identical between
+  // SSR and the first client render (no hydration warning).
+  const [origin] = useState<string>(readOrigin);
+
+  const deepLinkUrl = origin ? `${origin}${NATIVE_APP.SHOWCASE_PATH_PREFIX}/` : "";
+
+  return (
+    <div className="not-prose my-8 w-full overflow-hidden rounded-xl border border-separator">
+      <div className="flex flex-col items-center gap-6 px-6 py-10">
+        <DeepLinkQRCode size={200} url={deepLinkUrl} />
+        <span className="mb-2 text-center text-xs text-foreground">
+          {["Don't have the ", NATIVE_APP.NAME, " app yet? Download it below."].join("")}
+        </span>
+        <StoreButtonsLocalized className="flex w-full max-w-xs flex-col items-stretch gap-2" />
+      </div>
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/native/video-player-view.tsx b/apps/docs/src/components/native/video-player-view.tsx
new file mode 100644
index 0000000..9b71d44
--- /dev/null
+++ b/apps/docs/src/components/native/video-player-view.tsx
@@ -0,0 +1,116 @@
+"use client";
+
+import type {NativeQRPreviewTarget} from "./qr-preview-popover/target";
+
+import {cn} from "@heroui/react";
+import {useTheme} from "next-themes";
+
+import {VideoPlayer} from "../video-player";
+
+import {QRPreviewPopover} from "./qr-preview-popover";
+import {pickNativeQRTarget} from "./qr-preview-popover/target";
+
+interface VideoPlayerViewBaseProps {
+  /**
+   * Video source URL used while the page is in light theme.
+   */
+  srcLight: string;
+  /**
+   * Video source URL used while the page is in dark theme.
+   */
+  srcDark: string;
+  /**
+   * Optional poster image URL. Forwarded verbatim to the underlying
+   * VideoPlayer.
+   */
+  poster?: string;
+  /**
+   * Height of the video player in CSS pixels. Default matches the standard
+   * docs grid row height so the QR button sits above the video at a
+   * consistent offset.
+   * @default 300
+   */
+  height?: number;
+  /**
+   * Width of the video player in CSS pixels. Defaults to the container width.
+   */
+  width?: number;
+  /**
+   * Either "auto" (play whenever the viewport intersects) or "manual"
+   * (user-triggered). Forwarded to VideoPlayer.
+   */
+  playMode?: "auto" | "manual";
+  /**
+   * Whether to start playing as soon as the video is in view. Forwarded to
+   * VideoPlayer.
+   */
+  autoPlay?: boolean;
+  /**
+   * Whether to show native HTML video controls. Forwarded to VideoPlayer.
+   */
+  controls?: boolean;
+  /**
+   * Whether to show the QR code preview button.
+   *
+   * Even when `false`, the wrapper still requires `target` (the type is
+   * unconditionally required at every level to prevent accidental
+   * misconfiguration). `target` is simply ignored at runtime when the popover
+   * is not rendered.
+   *
+   * @default true
+   */
+  showQRCode?: boolean;
+  /**
+   * Optional extra class names applied to the outer wrapper.
+   */
+  className?: string;
+}
+
+/**
+ * Props for {@link VideoPlayerView}. The QR popover's `target` discriminator
+ * is required at the wrapper level so every call site has to make a deliberate
+ * choice between `"auto"`, `"home"`, and `"component"`.
+ */
+export type VideoPlayerViewProps = VideoPlayerViewBaseProps & NativeQRPreviewTarget;
+
+/**
+ * VideoPlayerView wraps the docs VideoPlayer with a "Scan to preview" popover
+ * button anchored to the top-right corner. Used on every Native component
+ * doc page and in release-notes demos.
+ */
+export const VideoPlayerView = (props: VideoPlayerViewProps) => {
+  const {
+    autoPlay,
+    className,
+    controls,
+    height = 300,
+    playMode,
+    poster,
+    showQRCode = true,
+    srcDark,
+    srcLight,
+    width,
+  } = props;
+  const {resolvedTheme} = useTheme();
+
+  // Default to the light video during SSR (resolvedTheme is undefined until
+  // mounted). The mismatch is acceptable because the video tag re-renders
+  // immediately after hydration with the correct src.
+  const videoSrc = resolvedTheme === "dark" ? srcDark : srcLight;
+
+  return (
+    <div className={cn("flex flex-col items-end gap-4", className)}>
+      {!!showQRCode && <QRPreviewPopover {...pickNativeQRTarget(props)} />}
+
+      <VideoPlayer
+        autoPlay={autoPlay}
+        controls={controls}
+        height={height}
+        playMode={playMode}
+        poster={poster}
+        src={videoSrc}
+        width={width}
+      />
+    </div>
+  );
+};
diff --git a/apps/docs/src/components/newsletter-form.tsx b/apps/docs/src/components/newsletter-form.tsx
new file mode 100644
index 0000000..84904d6
--- /dev/null
+++ b/apps/docs/src/components/newsletter-form.tsx
@@ -0,0 +1,164 @@
+"use client";
+
+import {Button, FieldError, Form, Input, Label, Spinner, TextField} from "@heroui/react";
+import {AnimatePresence, LazyMotion, domAnimation} from "motion/react";
+import * as m from "motion/react-m";
+import React from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export function NewsletterForm() {
+  const dict = useDictionary().newsletter;
+  const [email, setEmail] = React.useState("");
+  const [status, setStatus] = React.useState<"idle" | "loading" | "success" | "error">("idle");
+  const [apiErrorMessage, setApiErrorMessage] = React.useState<string | null>(null);
+
+  const circleCheckIcon = (
+    <svg fill="none" height="16" viewBox="0 0 17 16" width="17" xmlns="http://www.w3.org/2000/svg">
+      <path
+        clipRule="evenodd"
+        d="M8.5 15C12.366 15 15.5 11.866 15.5 8C15.5 4.13401 12.366 1 8.5 1C4.63401 1 1.5 4.13401 1.5 8C1.5 11.866 4.63401 15 8.5 15ZM11.6 6.45C11.8485 6.11863 11.7814 5.64853 11.45 5.4C11.1186 5.15147 10.6485 5.21863 10.4 5.55L7.91885 8.85819L6.53033 7.46967C6.23744 7.17678 5.76256 7.17678 5.46967 7.46967C5.17678 7.76256 5.17678 8.23744 5.46967 8.53033L7.46967 10.5303C7.62341 10.6841 7.8363 10.7635 8.05317 10.7481C8.27004 10.7327 8.46955 10.6239 8.6 10.45L11.6 6.45Z"
+        fill="#24864E"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+
+  const subscribeButton = {
+    error: dict.subscribe,
+    idle: dict.subscribe,
+    loading: (
+      <div className="flex w-full items-center justify-center">
+        <Spinner color="current" size="sm" />
+      </div>
+    ),
+    success: circleCheckIcon,
+  };
+
+  const getButtonContentKey = (status: "idle" | "loading" | "success" | "error") => {
+    if (status === "idle" || status === "error")
+      return status === "idle" || status === "error" ? "subscribe" : status;
+  };
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+
+    const formData = new FormData(e.currentTarget);
+    const emailValue = formData.get("email") as string;
+
+    if (!emailValue) {
+      return;
+    }
+
+    setStatus("loading");
+    setApiErrorMessage(null);
+
+    try {
+      // Loops - newsletter
+      const newsletterResponse = await fetch("/api/newsletter", {
+        body: JSON.stringify({
+          email: emailValue,
+          source: "Subscribe from HeroUI Docs",
+        }),
+        headers: {
+          "Content-Type": "application/json",
+        },
+        method: "POST",
+      });
+
+      const newsletterResData = await newsletterResponse.json();
+
+      if (!newsletterResData.success) {
+        throw new Error(newsletterResData.error || dict.apiError);
+      }
+
+      // Temporarily disable changelog subscription
+      // Featurebase - changelog
+      // const changelogResponse = await fetch("/api/changelog", {
+      //   body: JSON.stringify({
+      //     email: emailValue,
+      //   }),
+      //   headers: {
+      //     "Content-Type": "application/json",
+      //   },
+      //   method: "POST",
+      // });
+
+      // const changelogResData = await changelogResponse.json();
+
+      // if (!changelogResData.success) {
+      //   throw new Error(changelogResData.error || "Failed to subscribe changelog");
+      // }
+
+      setStatus("success");
+      setEmail("");
+      setTimeout(() => setStatus("idle"), 3000);
+    } catch (error) {
+      setStatus("error");
+      setApiErrorMessage(error instanceof Error ? error.message : dict.genericError);
+      setTimeout(() => setStatus("idle"), 3000);
+    }
+  };
+
+  return (
+    <div className="relative w-full py-3">
+      <div className="relative h-[172px] w-full">
+        <Form className="flex flex-col gap-2" onSubmit={handleSubmit}>
+          <TextField
+            isRequired
+            className="flex w-full flex-col gap-1"
+            isDisabled={status === "loading"}
+            name="email"
+            type="email"
+            value={email}
+            validate={(value) => {
+              if (!value) {
+                return dict.emailRequired;
+              }
+
+              if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+                return dict.emailInvalid;
+              }
+
+              return null;
+            }}
+            onChange={setEmail}
+          >
+            <Label className="pb-1 text-sm font-medium tracking-[-0.07px] after:hidden">
+              {dict.label}
+            </Label>
+            <Input placeholder={dict.placeholder} value={email} />
+            <FieldError className="mt-1 px-1 text-xs" />
+            {apiErrorMessage && status === "error" ? (
+              <p className="mt-1 px-1 text-xs text-danger">{apiErrorMessage}</p>
+            ) : null}
+          </TextField>
+          <Button
+            className="w-full"
+            isPending={status === "loading" || status === "success"}
+            type="submit"
+            variant="tertiary"
+            style={{
+              // @ts-expect-error --disabled-opacity is a css variable
+              "--disabled-opacity": 100,
+            }}
+          >
+            <LazyMotion features={domAnimation}>
+              <AnimatePresence initial={false} mode="popLayout">
+                <m.span
+                  key={getButtonContentKey(status)}
+                  animate={{opacity: 1, y: 0}}
+                  exit={{opacity: 0, y: 25}}
+                  initial={{opacity: 0, y: -25}}
+                  transition={{bounce: 0, duration: 0.3, type: "spring"}}
+                >
+                  {subscribeButton[status]}
+                </m.span>
+              </AnimatePresence>
+            </LazyMotion>
+          </Button>
+        </Form>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/pr-contributors.tsx b/apps/docs/src/components/pr-contributors.tsx
new file mode 100644
index 0000000..ef8f5ea
--- /dev/null
+++ b/apps/docs/src/components/pr-contributors.tsx
@@ -0,0 +1,224 @@
+import {Avatar, Link} from "@heroui/react";
+import * as React from "react";
+
+import {siteConfig} from "@/config/site";
+import {GITHUB_API_URL} from "@/utils/constants";
+
+/* -------------------------------------------------------------------------------------------------
+ * Types
+ * -----------------------------------------------------------------------------------------------*/
+
+interface GitHubUser {
+  login: string;
+  avatar_url: string;
+  html_url: string;
+  type?: "User" | "Bot";
+}
+
+interface GitHubCommit {
+  author: GitHubUser | null;
+  committer: GitHubUser | null;
+  commit?: {
+    author?: {name?: string; email?: string};
+    committer?: {name?: string; email?: string};
+  };
+}
+
+interface GitHubPR {
+  user?: GitHubUser;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Constants
+ * -----------------------------------------------------------------------------------------------*/
+
+const CACHE_CONFIG = {
+  cache: "force-cache" as RequestCache,
+  next: {revalidate: 3600}, // Revalidate every hour
+};
+
+const COMMITS_PER_PAGE = 100;
+
+const BOT_LOGINS = new Set(["web-flow", "ghost", "cursoragent"]);
+
+/* -------------------------------------------------------------------------------------------------
+ * Utilities
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Checks if a GitHub user is a bot or automated account
+ */
+function isBot(user: GitHubUser | null | undefined): boolean {
+  if (!user?.login) return false;
+
+  return (
+    user.type === "Bot" ||
+    user.login.endsWith("[bot]") ||
+    user.login.endsWith("-bot") ||
+    BOT_LOGINS.has(user.login)
+  );
+}
+
+/**
+ * Adds a user to the contributors map if valid and not already present
+ */
+function addContributor(
+  contributors: Map<string, GitHubUser>,
+  user: GitHubUser | null | undefined,
+): void {
+  if (!user?.login || isBot(user) || contributors.has(user.login)) return;
+
+  contributors.set(user.login, user);
+}
+
+/**
+ * Extracts unique contributors from commits
+ */
+function extractContributorsFromCommits(commits: GitHubCommit[]): Map<string, GitHubUser> {
+  const contributors = new Map<string, GitHubUser>();
+
+  for (const commit of commits) {
+    addContributor(contributors, commit.author);
+    addContributor(contributors, commit.committer);
+  }
+
+  return contributors;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * API Functions
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Fetches all commits from a PR with pagination support
+ */
+async function fetchAllCommits(prNumber: number): Promise<GitHubCommit[]> {
+  const allCommits: GitHubCommit[] = [];
+  let page = 1;
+
+  while (true) {
+    const url = `${GITHUB_API_URL}/repos/${siteConfig.githubRepo}/pulls/${prNumber}/commits?page=${page}&per_page=${COMMITS_PER_PAGE}`;
+    const response = await fetch(url, CACHE_CONFIG);
+
+    if (!response.ok) break;
+
+    const commits: GitHubCommit[] = await response.json();
+
+    if (commits.length === 0) break;
+
+    allCommits.push(...commits);
+
+    // Reached the last page if we got fewer commits than requested
+    if (commits.length < COMMITS_PER_PAGE) break;
+
+    page++;
+  }
+
+  return allCommits;
+}
+
+/**
+ * Fetches PR details including creator information
+ */
+async function fetchPRDetails(prNumber: number): Promise<GitHubPR | null> {
+  try {
+    const url = `${GITHUB_API_URL}/repos/${siteConfig.githubRepo}/pulls/${prNumber}`;
+    const response = await fetch(url, CACHE_CONFIG);
+
+    if (!response.ok) return null;
+
+    return (await response.json()) as GitHubPR;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetches all unique contributors from a GitHub Pull Request
+ * Includes commits authors/committers and PR creator
+ * Filters out bots and automated accounts
+ */
+export async function fetchPRContributors(prNumber: number): Promise<GitHubUser[]> {
+  try {
+    // Fetch PR details and commits in parallel for better performance
+    const [commits, prData] = await Promise.all([
+      fetchAllCommits(prNumber),
+      fetchPRDetails(prNumber),
+    ]);
+
+    // Extract contributors from commits
+    const contributors = extractContributorsFromCommits(commits);
+
+    // Add PR creator if available
+    if (prData?.user) {
+      addContributor(contributors, prData.user);
+    }
+
+    return Array.from(contributors.values());
+  } catch {
+    return [];
+  }
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Components
+ * -----------------------------------------------------------------------------------------------*/
+
+interface PRContributorsProps {
+  contributors?: GitHubUser[];
+  github?: {pull?: number};
+}
+
+/**
+ * Renders a single contributor avatar and link
+ */
+function ContributorItem({contributor}: {contributor: GitHubUser}) {
+  return (
+    <Link.Root
+      className="group flex items-center justify-start gap-1 no-underline! hover:no-underline!"
+      href={contributor.html_url}
+      rel="noreferrer"
+      target="_blank"
+    >
+      <Avatar.Root size="sm">
+        <Avatar.Image alt={contributor.login} className="m-0!" src={contributor.avatar_url} />
+        <Avatar.Fallback>{contributor.login[0]?.toUpperCase()}</Avatar.Fallback>
+        <span className="sr-only">{contributor.login}</span>
+      </Avatar.Root>
+      <span className="text-sm">@{contributor.login}</span>
+    </Link.Root>
+  );
+}
+
+/**
+ * Synchronous component that renders PR contributors list
+ */
+export function PRContributors({contributors, github}: PRContributorsProps) {
+  if (!contributors || contributors.length === 0) {
+    // Fallback for dev mode compatibility
+    if (!github?.pull) return null;
+
+    return null;
+  }
+
+  return (
+    <div className="mt-0! mb-2 flex flex-wrap gap-4">
+      {contributors.map((contributor) => (
+        <ContributorItem key={contributor.login} contributor={contributor} />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Async version for backward compatibility (dev mode)
+ */
+export async function PRContributorsAsync(props: {github?: {pull?: number}}) {
+  if (!props.github?.pull) return null;
+
+  const contributors = await fetchPRContributors(props.github.pull);
+
+  if (contributors.length === 0) return null;
+
+  return <PRContributors contributors={contributors} />;
+}
diff --git a/apps/docs/src/components/related-components.tsx b/apps/docs/src/components/related-components.tsx
new file mode 100644
index 0000000..390490a
--- /dev/null
+++ b/apps/docs/src/components/related-components.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {ComponentItem} from "@/components/component-item";
+import {getRelatedComponents} from "@/components-registry";
+import {cn} from "@/utils/cn";
+
+interface RelatedComponentsProps {
+  component: string;
+  className?: string;
+}
+
+export function RelatedComponents({className, component}: RelatedComponentsProps) {
+  const relatedComponents = getRelatedComponents(component)?.slice(0, 3);
+
+  if (!relatedComponents || relatedComponents.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn("my-8", className)}>
+      <h2 className="mb-4 text-xl font-semibold">Related Components</h2>
+      <div className="not-prose grid grid-cols-1 gap-x-4 gap-y-8 sm:grid-cols-2 lg:grid-cols-3">
+        {relatedComponents.map((relatedComponent) => (
+          <ComponentItem key={relatedComponent.name} component={relatedComponent} />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/related-showcases.tsx b/apps/docs/src/components/related-showcases.tsx
new file mode 100644
index 0000000..d894827
--- /dev/null
+++ b/apps/docs/src/components/related-showcases.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {useParams, usePathname} from "next/navigation";
+
+import {ShowcaseItem} from "@/components/showcase-item";
+import {i18n} from "@/lib/i18n";
+import {getShowcasesByComponent} from "@/showcases";
+import {cn} from "@/utils/cn";
+
+interface RelatedShowcasesProps {
+  component: string;
+  className?: string;
+}
+
+export function RelatedShowcases({className, component}: RelatedShowcasesProps) {
+  const pathname = usePathname();
+  const params = useParams<{lang?: string}>();
+  const lang = params.lang ?? i18n.defaultLanguage;
+  const showcases = getShowcasesByComponent(component);
+
+  if (!showcases || showcases.length === 0) {
+    return null;
+  }
+
+  // Encode the current pathname to use as the returnUrl parameter
+  const returnUrl = encodeURIComponent(pathname);
+
+  return (
+    <div className={cn(className)}>
+      <h2 className="m-0 text-xl font-semibold">Related Showcases</h2>
+      <div className="not-prose -mx-2 grid grid-cols-1 gap-4 overflow-x-auto p-2 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
+        {showcases.map((showcase) => (
+          <ShowcaseItem
+            key={showcase.name}
+            className="aspect-video h-[180px] max-w-[250px] shrink-0"
+            href={`/${lang}/showcase/${showcase.name}?returnUrl=${returnUrl}`}
+            item={showcase}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/search-dialog.tsx b/apps/docs/src/components/search-dialog.tsx
new file mode 100644
index 0000000..0b6bd16
--- /dev/null
+++ b/apps/docs/src/components/search-dialog.tsx
@@ -0,0 +1,394 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+import type {Item, Node} from "fumadocs-core/page-tree";
+import type {SearchItemType, SharedProps} from "fumadocs-ui/components/dialog/search";
+import type {ComponentProps} from "react";
+
+import {Chip, Kbd, Tag, TagGroup} from "@heroui/react";
+import {useDocsSearch} from "fumadocs-core/search/client";
+import {
+  SearchDialog,
+  SearchDialogContent,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogList,
+  SearchDialogOverlay,
+  useSearch,
+} from "fumadocs-ui/components/dialog/search";
+import {useI18n} from "fumadocs-ui/contexts/i18n";
+import {useTreeContext} from "fumadocs-ui/contexts/tree";
+import {ArrowRight} from "lucide-react";
+import {usePathname, useRouter} from "next/navigation";
+import {useCallback, useEffect, useMemo, useRef, useState} from "react";
+import {tv} from "tailwind-variants";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+// Default suggested pages for each tag
+const DEFAULT_SUGGESTIONS: Record<"native" | "web", string[]> = {
+  native: [
+    "/docs/native/getting-started",
+    "/docs/native/getting-started/quick-start",
+    "/docs/native/getting-started/design-principles",
+    "/docs/native/getting-started/provider",
+    "/docs/native/getting-started/colors",
+    "/docs/native/getting-started/theming",
+  ],
+  web: [
+    "/docs/react/getting-started",
+    "/docs/react/getting-started/quick-start",
+    "/docs/react/getting-started/design-principles",
+    "/docs/react/getting-started/colors",
+    "/docs/react/getting-started/theming",
+  ],
+};
+
+const PRO_URL = process.env["NEXT_PUBLIC_PRO_URL"] ?? "https://heroui.pro";
+const PRO_SEARCH_DEBOUNCE_MS = 150;
+
+interface ProComponent {
+  title: string;
+  description: string;
+  slug: string;
+  category: string;
+}
+
+function useProSearch(query: string, tag: "web" | "native") {
+  const [results, setResults] = useState<ProComponent[]>([]);
+  const abortRef = useRef<AbortController | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const fetchResults = useCallback(
+    (q: string) => {
+      abortRef.current?.abort();
+
+      if (!q) {
+        setResults([]);
+
+        return;
+      }
+
+      const controller = new AbortController();
+
+      abortRef.current = controller;
+
+      fetch(`${PRO_URL}/docs/api/pro-components/search?q=${encodeURIComponent(q)}&tag=${tag}`, {
+        signal: controller.signal,
+      })
+        .then((res) => (res.ok ? res.json() : {results: []}))
+        .then((data: {results: ProComponent[]}) => {
+          if (!controller.signal.aborted) {
+            setResults(data.results);
+          }
+        })
+        .catch(() => {
+          // aborted or network error — ignore
+        });
+    },
+    [tag],
+  );
+
+  useEffect(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+
+    timerRef.current = setTimeout(() => fetchResults(query), PRO_SEARCH_DEBOUNCE_MS);
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [query, fetchResults]);
+
+  useEffect(() => {
+    return () => abortRef.current?.abort();
+  }, []);
+
+  return results;
+}
+
+const tagStyles = tv({
+  base: "bg-default/80 px-2 data-[selected=true]:bg-accent-soft data-[selected=true]:text-accent-soft-foreground",
+});
+
+export default function CustomSearchDialog(props: SharedProps) {
+  const dict = useDictionary();
+  const pathname = usePathname();
+  const previousPathnameRef = useRef(pathname);
+
+  const getDefaultTag = (path: string): "web" | "native" => {
+    if (path.startsWith("/docs/native/")) return "native";
+    if (path.startsWith("/docs/react/")) return "web";
+
+    return "web";
+  };
+
+  const [selected, setSelected] = useState<Iterable<Key>>(() => new Set([getDefaultTag(pathname)]));
+
+  useEffect(() => {
+    // Only update if pathname actually changed
+    if (previousPathnameRef.current !== pathname) {
+      const defaultTag = getDefaultTag(pathname);
+
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setSelected(new Set([defaultTag]));
+      previousPathnameRef.current = pathname;
+    }
+  }, [pathname]);
+
+  const selectedTag = useMemo(() => {
+    return Array.from(selected).includes("web") ? "web" : "native";
+  }, [selected]);
+
+  const {locale} = useI18n();
+
+  const {query, search, setSearch} = useDocsSearch({
+    locale,
+    tag: selectedTag,
+    type: "fetch",
+  });
+  const {onOpenChange, ...restProps} = props;
+  const handleOpenChange = (isOpen: boolean) => {
+    onOpenChange?.(isOpen);
+    if (!isOpen) {
+      setSearch("");
+    }
+  };
+  const {full} = useTreeContext();
+  const router = useRouter();
+
+  // Collect all pages from the tree
+  const allPages = useMemo(() => {
+    const pages: Item[] = [];
+
+    function onNode(node: Node) {
+      if (node.type === "page") {
+        pages.push(node);
+      } else if (node.type === "folder") {
+        if (node.index) onNode(node.index);
+        for (const item of node.children) onNode(item);
+      }
+    }
+
+    for (const item of full.children) onNode(item);
+
+    return pages;
+  }, [full]);
+
+  // Strip the locale prefix from a page tree URL so comparisons can be done
+  // against locale-agnostic paths like `/docs/react/...`.
+  const stripLocale = useCallback(
+    (url: string | undefined) => {
+      if (!url) return "";
+      if (locale && url.startsWith(`/${locale}/`)) {
+        return url.slice(locale.length + 1);
+      }
+
+      return url;
+    },
+    [locale],
+  );
+
+  // Filter pages by tag and create a map
+  const searchMap = useMemo(() => {
+    const map = new Map<string, Item>();
+    const tagPrefix = selectedTag === "web" ? "/docs/react/" : "/docs/native/";
+    const releasePrefix =
+      selectedTag === "web" ? "/docs/react/releases/" : "/docs/native/releases/";
+    const migrationPrefix = "/docs/react/migration";
+
+    for (const page of allPages) {
+      const path = stripLocale(page.url);
+      const isMigrationSubPage = path.startsWith(migrationPrefix) && path !== migrationPrefix;
+
+      if (
+        path.startsWith(tagPrefix) &&
+        !path.startsWith(releasePrefix) &&
+        !isMigrationSubPage &&
+        typeof page.name === "string"
+      ) {
+        map.set(page.name.toLowerCase(), page);
+      }
+    }
+
+    return map;
+  }, [allPages, selectedTag, stripLocale]);
+
+  // Get default suggestions for the current tag
+  const defaultSuggestions = useMemo(() => {
+    if (search.length > 0) return [];
+
+    const suggestionUrls = DEFAULT_SUGGESTIONS[selectedTag];
+    const suggestions: SearchItemType[] = [];
+
+    for (const url of suggestionUrls) {
+      const page = allPages.find((p) => stripLocale(p.url) === url);
+
+      if (page && page.name) {
+        suggestions.push({
+          id: `suggestion-${url}`,
+          node: (
+            <div className="inline-flex items-center gap-2">
+              {page.icon}
+              <span>{page.name}</span>
+            </div>
+          ),
+          onSelect: () => router.push((page.url ?? url) as any),
+          type: "action",
+        });
+      }
+    }
+
+    return suggestions;
+  }, [allPages, selectedTag, search, router, stripLocale]);
+
+  let pageTreeAction: SearchItemType | undefined;
+
+  if (search.length > 0) {
+    const normalized = search.toLowerCase();
+
+    for (const [k, page] of searchMap) {
+      if (!k.startsWith(normalized)) continue;
+
+      pageTreeAction = {
+        id: "quick-action",
+        node: (
+          <div className="text-fd-muted-foreground inline-flex items-center gap-2">
+            <ArrowRight className="size-4" />
+            <p>
+              {dict.searchDialog.jumpTo}{" "}
+              <span className="text-fd-foreground font-medium">{page.name}</span>
+            </p>
+          </div>
+        ),
+        onSelect: () => router.push(page.url as any),
+        type: "action",
+      };
+      break;
+    }
+  }
+
+  const proComponents = useProSearch(search, selectedTag);
+
+  const proResults: SearchItemType[] = useMemo(() => {
+    if (search.length === 0) return [];
+
+    return proComponents.map((comp) => ({
+      id: `pro-${comp.slug}`,
+      node: (
+        <div className="inline-flex w-full items-center gap-2">
+          <ArrowRight className="text-fd-muted-foreground size-4" />
+          <p className="truncate">{comp.title}</p>
+          <Chip className="ml-auto shrink-0" color="accent" size="sm" variant="soft">
+            PRO
+          </Chip>
+        </div>
+      ),
+      onSelect: () =>
+        window.open(
+          `${PRO_URL}${comp.slug}?utm_source=heroui_docs&utm_medium=search&utm_campaign=pro_components`,
+          "_blank",
+        ),
+      type: "action" as const,
+    }));
+  }, [proComponents, search]);
+
+  const releasesPath = useMemo(() => {
+    return `/docs/${selectedTag === "web" ? "react" : "native"}/releases`;
+  }, [selectedTag]);
+
+  const migrationPath = "/docs/react/migration";
+
+  const queryData = useMemo(() => {
+    if (!query.data || query.data === "empty") return null;
+
+    return query.data.filter((item) => {
+      const path = stripLocale(item.url);
+
+      if (path.startsWith(releasesPath)) return false;
+      if (path.startsWith(migrationPath) && path !== migrationPath) {
+        return false;
+      }
+
+      return true;
+    });
+  }, [query.data, releasesPath, migrationPath, stripLocale]);
+
+  return (
+    <SearchDialog
+      isLoading={query.isLoading}
+      search={search}
+      onOpenChange={handleOpenChange}
+      onSearchChange={setSearch}
+      {...restProps}
+    >
+      <SearchDialogOverlay />
+      <SearchDialogContent className="border-none bg-surface">
+        <div className="border-none px-2 pt-2">
+          <TagGroup
+            disallowEmptySelection
+            aria-label={dict.frameworksTabs.ariaLabel}
+            selectedKeys={selected}
+            selectionMode="single"
+            onSelectionChange={(keys) => setSelected(keys)}
+          >
+            <TagGroup.List className="gap-1">
+              <Tag className={tagStyles()} id="web">
+                {dict.frameworksTabs.web}
+              </Tag>
+              <Tag className={tagStyles()} id="native">
+                {dict.frameworksTabs.native}
+              </Tag>
+            </TagGroup.List>
+          </TagGroup>
+        </div>
+        <SearchDialogHeader className="border-b border-separator">
+          <SearchDialogIcon />
+          <SearchDialogInput placeholder={dict.searchDialog.placeholder} />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        <SearchDialogList
+          className="**:aria-selected:bg-default **:aria-selected:text-foreground"
+          items={
+            search.length === 0
+              ? defaultSuggestions.length > 0
+                ? defaultSuggestions
+                : null
+              : queryData || pageTreeAction || proResults.length > 0
+                ? [
+                    ...(pageTreeAction ? [pageTreeAction] : []),
+                    ...proResults,
+                    ...(Array.isArray(queryData) ? queryData : []),
+                  ]
+                : null
+          }
+        />
+      </SearchDialogContent>
+    </SearchDialog>
+  );
+}
+
+function SearchDialogInput(props: ComponentProps<"input">) {
+  const {text} = useI18n();
+  const {onSearchChange, search} = useSearch();
+
+  return (
+    <input
+      {...props}
+      autoFocus
+      className="placeholder:text-fd-muted-foreground w-0 flex-1 bg-transparent text-lg focus-visible:outline-none"
+      placeholder={props.placeholder || text.search}
+      value={search}
+      onChange={(e) => onSearchChange(e.target.value)}
+    />
+  );
+}
+
+function SearchDialogClose({children = "ESC", className, ...props}: ComponentProps<"kbd">) {
+  const {onOpenChange} = useSearch();
+
+  return (
+    <Kbd className={className} onClick={() => onOpenChange(false)} {...props}>
+      <Kbd.Content>{children}</Kbd.Content>
+    </Kbd>
+  );
+}
diff --git a/apps/docs/src/components/showcase-item.tsx b/apps/docs/src/components/showcase-item.tsx
new file mode 100644
index 0000000..151c3f1
--- /dev/null
+++ b/apps/docs/src/components/showcase-item.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import type {ShowcaseItem as ShowcaseItemType} from "@/showcases";
+import type {ReactNode} from "react";
+import type {UrlObject} from "url";
+
+import {chipVariants} from "@heroui/react";
+import Link from "next/link";
+
+import {cn} from "@/utils/cn";
+
+interface ShowcaseItemProps extends React.ComponentProps<"div"> {
+  item: ShowcaseItemType;
+  href: string;
+  children?: ReactNode;
+  isSelected?: boolean;
+  isMinimal?: boolean;
+  className?: string;
+}
+
+export function ShowcaseItem({
+  className,
+  href,
+  isMinimal = false,
+  isSelected = false,
+  item,
+  ...props
+}: ShowcaseItemProps) {
+  const {posterUrl, status, title, videoUrl} = item;
+
+  return (
+    <Link href={href as unknown as UrlObject}>
+      <div
+        className={cn(
+          "group relative flex h-[250px] flex-col items-center justify-center",
+          {
+            "h-[44px] w-[60px]": isMinimal,
+          },
+          className,
+        )}
+        {...props}
+      >
+        {/* Status chip */}
+        {!!status && !isMinimal && (
+          <div className="absolute top-1.5 right-2 z-10">
+            <span
+              className={cn(
+                chipVariants({
+                  className: cn(
+                    "h-6 rounded-full border border-white/10 bg-black/30 px-1.5 text-[11px] text-white/80 shadow-sm saturate-200 backdrop-blur-md",
+                  ),
+                }),
+                "font-medium capitalize shadow-sm",
+                {"bg-white/10": item.defaultTheme === "dark" && !item.supportsThemeSwitching},
+              )}
+            >
+              {status}
+            </span>
+          </div>
+        )}
+        <div
+          className={cn(
+            "shadow-panel h-full w-full overflow-hidden rounded-xl border border-transparent object-cover transition-all duration-[250ms] ease-out-quad will-change-transform group-hover:scale-[1.02] group-hover:drop-shadow-xl group-hover:drop-shadow-black/15",
+            {
+              "aspect-video h-full w-full rounded-lg": isMinimal,
+              "border-foreground/60": isSelected,
+            },
+          )}
+        >
+          <video
+            autoPlay
+            loop
+            muted
+            playsInline
+            className={isMinimal ? "h-full w-full" : ""}
+            poster={posterUrl}
+            preload="none"
+          >
+            <source src={videoUrl} />
+            Your browser does not support the video tag.
+          </video>
+        </div>
+        {!isMinimal && (
+          <div className="mt-3 flex w-full items-start justify-between px-1">
+            <span className="text-sm text-foreground/50 transition-[color] duration-[250ms] ease-out-quad group-hover:text-foreground/80">
+              {title}
+            </span>
+          </div>
+        )}
+      </div>
+    </Link>
+  );
+}
diff --git a/apps/docs/src/components/showcase-preview.tsx b/apps/docs/src/components/showcase-preview.tsx
new file mode 100644
index 0000000..df1ad38
--- /dev/null
+++ b/apps/docs/src/components/showcase-preview.tsx
@@ -0,0 +1,47 @@
+import * as React from "react";
+
+import {getShowcase} from "@/showcases";
+import {cn} from "@/utils/cn";
+
+interface ShowcasePreviewProps extends React.HTMLAttributes<HTMLDivElement> {
+  name: string;
+  fullWidth?: boolean;
+}
+
+export function ShowcasePreview({
+  className,
+  fullWidth = false,
+  name,
+  ...props
+}: ShowcasePreviewProps) {
+  const showcase = getShowcase(name);
+
+  if (!showcase) {
+    return (
+      <div className={cn("my-4 rounded-md border border-red-200 bg-red-50 p-4", className)}>
+        <p className="text-sm text-red-600">
+          Showcase &quot;{name}&quot; not found. Make sure the showcase is registered in the
+          showcases index.
+        </p>
+      </div>
+    );
+  }
+
+  const Component = showcase.component;
+
+  return (
+    <div
+      data-name={name}
+      className={cn(
+        "showcase-preview group relative w-full",
+        !fullWidth && "mx-auto max-w-7xl",
+        className,
+      )}
+      {...props}
+    >
+      <div className={cn("not-prose relative w-full overflow-hidden")}>
+        <Component />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/showcase-source.tsx b/apps/docs/src/components/showcase-source.tsx
new file mode 100644
index 0000000..426558b
--- /dev/null
+++ b/apps/docs/src/components/showcase-source.tsx
@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import * as React from "react";
+
+import {getShowcase} from "@/showcases";
+import {cn} from "@/utils/cn";
+
+import {CodeBlock} from "./codeblock";
+
+export async function ShowcaseSource({
+  allowCopy = true,
+  className,
+  collapsible = false,
+  language,
+  name,
+  showCodeTitle = false,
+  showLineNumbers = true,
+  title,
+}: React.ComponentProps<"div"> & {
+  name?: string;
+  title?: string;
+  language?: string;
+  showCodeTitle?: boolean;
+  showLineNumbers?: boolean;
+  collapsible?: boolean;
+  allowCopy?: boolean;
+}) {
+  if (!name) {
+    return null;
+  }
+
+  const item = getShowcase(name);
+  const src = item?.file;
+  let code: string | undefined;
+
+  if (src && item?.category) {
+    try {
+      // Extract category from the showcase data
+      const category = item.category.toLowerCase();
+      const file = await fs.readFile(
+        path.join(process.cwd(), "src", "showcases", category, src),
+        "utf-8",
+      );
+
+      code = file;
+    } catch (error) {
+      // Failed to read showcase file
+      return null;
+    }
+  }
+
+  if (!code) {
+    return null;
+  }
+
+  const lang = language ?? title?.split(".").pop() ?? "tsx";
+
+  return (
+    <div className={cn("relative", className)}>
+      <CodeBlock
+        allowCopy={allowCopy}
+        code={code}
+        collapsible={collapsible}
+        lang={lang}
+        showLineNumbers={showLineNumbers}
+        title={showCodeTitle ? title : undefined}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/social-links.tsx b/apps/docs/src/components/social-links.tsx
new file mode 100644
index 0000000..5682683
--- /dev/null
+++ b/apps/docs/src/components/social-links.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {cn} from "tailwind-variants";
+
+import {siteConfig} from "@/config/site";
+import {DiscordIcon} from "@/icons/discord";
+import {GitHubIcon} from "@/icons/github";
+import {TwitterIcon} from "@/icons/twitter";
+
+export interface SocialLinksProps {
+  className?: string;
+  iconSize?: number;
+}
+
+export function SocialLinks(props: SocialLinksProps) {
+  const {className, iconSize = 18} = props;
+
+  return (
+    <div className={cn("flex items-center justify-center gap-2", className)}>
+      <a
+        className="-mr-1 text-inherit"
+        href={siteConfig.links.twitter}
+        rel="noreferrer"
+        target="_blank"
+      >
+        <TwitterIcon height={iconSize - 4} width={iconSize} />
+        <span className="sr-only">Twitter</span>
+      </a>
+      <a className="text-inherit" href={siteConfig.links.discord} rel="noreferrer" target="_blank">
+        <DiscordIcon height={iconSize} width={iconSize} />
+        <span className="sr-only">Discord</span>
+      </a>
+      <a className="text-inherit" href={siteConfig.links.github} rel="noreferrer" target="_blank">
+        <GitHubIcon height={iconSize} width={iconSize} />
+        <span className="sr-only">GitHub</span>
+      </a>
+    </div>
+  );
+}
diff --git a/apps/docs/src/components/status-chip.tsx b/apps/docs/src/components/status-chip.tsx
new file mode 100644
index 0000000..91e220d
--- /dev/null
+++ b/apps/docs/src/components/status-chip.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {Chip} from "@heroui/react";
+import * as React from "react";
+
+import {useDictionary} from "@/hooks/use-dictionary";
+
+export type StatusChipStatus = "new" | "new-dot" | "preview" | "updated";
+
+interface StatusChipProps {
+  status: StatusChipStatus;
+  className?: string;
+}
+
+export function StatusChip({className, status}: StatusChipProps) {
+  const dict = useDictionary().statusChip;
+
+  if (status === "new") {
+    return (
+      <Chip
+        className={`h-5 rounded-full bg-pink-400/8 px-1.5 text-[10px] font-semibold text-pink-400/90 ${className || ""}`}
+        variant="primary"
+      >
+        {dict.new}
+      </Chip>
+    );
+  }
+
+  if (status === "preview") {
+    return (
+      <Chip
+        className={`h-5 rounded-full border border-foreground/10 px-1.5 text-[10px] text-foreground/60 ${className || ""}`}
+        variant="tertiary"
+      >
+        {dict.preview}
+      </Chip>
+    );
+  }
+
+  if (status === "updated") {
+    return (
+      <Chip
+        className={`h-5 rounded-full bg-black/3 px-1.5 text-[10px] text-muted/90 dark:bg-white/8 ${className || ""}`}
+        variant="primary"
+      >
+        {dict.updated}
+      </Chip>
+    );
+  }
+
+  return null;
+}
+
+export default StatusChip;
diff --git a/apps/docs/src/components/theme-background.tsx b/apps/docs/src/components/theme-background.tsx
new file mode 100644
index 0000000..0497f2f
--- /dev/null
+++ b/apps/docs/src/components/theme-background.tsx
@@ -0,0 +1,31 @@
+import Image from "next/image";
+
+import {siteConfig} from "@/config/site";
+
+export function ThemeBackground() {
+  const lightBg = `${siteConfig.cdnUrl}/backgrounds/docs-light-bg.jpg`;
+  const darkBg = `${siteConfig.cdnUrl}/backgrounds/docs-dark-bg.jpg`;
+
+  return (
+    <>
+      {/* Light theme background */}
+      <Image
+        fill
+        priority
+        alt=""
+        className="fixed inset-0 z-0 object-cover object-center dark:hidden"
+        quality={100}
+        src={lightBg}
+      />
+      {/* Dark theme background */}
+      <Image
+        fill
+        priority
+        alt=""
+        className="fixed inset-0 z-0 hidden object-cover object-center dark:block"
+        quality={100}
+        src={darkBg}
+      />
+    </>
+  );
+}
diff --git a/apps/docs/src/components/version-selector.tsx b/apps/docs/src/components/version-selector.tsx
new file mode 100644
index 0000000..dd7e835
--- /dev/null
+++ b/apps/docs/src/components/version-selector.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Popover, Separator} from "@heroui/react";
+import Link from "next/link";
+import {useState} from "react";
+
+import {useCurrentFramework} from "@/hooks/use-current-framework";
+import {cn} from "@/utils/cn";
+import {currentVersion} from "@/utils/version";
+
+import {Iconify} from "./iconify";
+
+export function VersionSelector({className}: {className?: string}) {
+  const [open, setOpen] = useState(false);
+  const currentFramework = useCurrentFramework();
+
+  if (currentFramework === "native") {
+    return null;
+  }
+
+  return (
+    <Popover isOpen={open} onOpenChange={setOpen}>
+      <Popover.Trigger
+        className={cn(
+          "flex items-center gap-1.5 py-1 text-left text-xs font-medium text-muted transition-opacity hover:opacity-80 sm:text-sm",
+          className,
+        )}
+      >
+        <span className="max-w-[100px] overflow-hidden text-ellipsis whitespace-nowrap">
+          v{currentVersion}
+        </span>
+        <Iconify icon="chevron-down" />
+      </Popover.Trigger>
+      <Popover.Content className="min-w-[180px] p-0" placement="bottom end">
+        <Popover.Dialog className="px-1 py-1">
+          <div className="flex flex-col gap-0">
+            <div className="bg-primary/10 text-primary hover:bg-primary/20 flex items-center justify-between rounded-md px-3 py-2 text-sm font-medium">
+              <span>v3</span>
+              <span className="ml-2 text-xs font-semibold text-muted">{currentVersion}</span>
+            </div>
+            <div className="my-0.5 px-2">
+              <Separator />
+            </div>
+            <Link
+              className="flex items-center justify-between rounded-3xl px-3 py-2 text-sm text-muted hover:bg-default-hover hover:text-foreground"
+              href="https://v2.heroui.com?utm_source=v3.heroui.com"
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              <span>v2</span>
+              <span className="ml-2 text-xs font-semibold text-muted">2.8.x</span>
+            </Link>
+          </div>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  );
+}
diff --git a/apps/docs/src/components/video-player.tsx b/apps/docs/src/components/video-player.tsx
new file mode 100644
index 0000000..8487682
--- /dev/null
+++ b/apps/docs/src/components/video-player.tsx
@@ -0,0 +1,231 @@
+"use client";
+
+import type {FC} from "react";
+
+import {ArrowRotateLeft, VolumeFill, VolumeSlashFill} from "@gravity-ui/icons";
+import {Button, Spinner, Tooltip, cn} from "@heroui/react";
+import {useCallback, useEffect, useRef, useState} from "react";
+import {useIntersectionObserver} from "usehooks-ts";
+
+import {useIsMobileDevice} from "@/hooks/use-is-mobile-device";
+
+import {Iconify} from "./iconify";
+
+interface VideoPlayerProps {
+  src: string;
+  playMode?: "auto" | "manual";
+  autoPlay?: boolean;
+  muted?: boolean;
+  poster?: string;
+  width?: number;
+  height?: number;
+  controls?: boolean;
+  className?: string;
+  onPlayingChange?: (isPlaying: boolean) => void;
+}
+
+export const VideoPlayer: FC<VideoPlayerProps> = ({
+  autoPlay = true,
+  className,
+  controls = false,
+  height,
+  muted = false,
+  onPlayingChange,
+  playMode = "auto",
+  poster,
+  src,
+  width,
+}) => {
+  const [isLoading, setIsLoading] = useState(true);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [isMuted, setIsMuted] = useState(muted);
+  const isMobile = useIsMobileDevice();
+
+  const videoRef = useRef<HTMLVideoElement>(null);
+
+  const {isIntersecting: isVisible, ref: intersectionRef} = useIntersectionObserver({
+    threshold: 0.5,
+  });
+
+  // Merge refs: videoRef for video operations and intersectionRef for intersection observer
+  // Use ref callback to avoid mutating hook return value
+  const setVideoRef = useCallback(
+    (element: HTMLVideoElement | null) => {
+      videoRef.current = element;
+      if (element) {
+        if (element.readyState >= 3) {
+          setIsLoading(false);
+        }
+        if (typeof intersectionRef === "function") {
+          intersectionRef(element);
+        }
+      } else {
+        if (typeof intersectionRef === "function") {
+          intersectionRef(null);
+        }
+      }
+    },
+    [intersectionRef],
+  );
+
+  // Determine effective play mode: force manual on mobile devices
+  const effectivePlayMode = isMobile ? "manual" : playMode;
+
+  // play video when it is visible and playMode is auto (only on non-mobile devices)
+  useEffect(() => {
+    if (effectivePlayMode !== "auto" || !videoRef.current) {
+      return;
+    }
+
+    if (isVisible) {
+      videoRef.current.play().catch(() => {
+        if (videoRef.current) {
+          videoRef.current.muted = true;
+          setIsMuted(true);
+          videoRef.current.play().catch(() => {});
+        }
+      });
+    } else {
+      videoRef.current.pause();
+    }
+  }, [isVisible, effectivePlayMode]);
+
+  const handleCanPlay = useCallback(() => {
+    setIsLoading(false);
+  }, []);
+
+  const handlePlay = useCallback(() => {
+    setIsPlaying(true);
+    onPlayingChange?.(true);
+  }, [onPlayingChange]);
+
+  const handlePause = useCallback(() => {
+    setIsPlaying(false);
+    onPlayingChange?.(false);
+  }, [onPlayingChange]);
+
+  const onTogglePlay = useCallback(() => {
+    if (videoRef.current) {
+      if (!isPlaying) {
+        videoRef.current.play();
+      } else {
+        videoRef.current.pause();
+      }
+
+      setIsPlaying((v) => !v);
+    }
+  }, [isPlaying]);
+
+  const onToggleMute = useCallback(() => {
+    if (videoRef.current) {
+      videoRef.current.muted = !isMuted;
+      setIsMuted((v) => !v);
+    }
+  }, [isMuted]);
+
+  const onRestart = useCallback(() => {
+    if (videoRef.current) {
+      videoRef.current.currentTime = 0;
+      videoRef.current.play();
+    }
+  }, []);
+
+  const handleVideoClick = useCallback(() => {
+    if (videoRef.current) {
+      if (!isPlaying) {
+        videoRef.current.play();
+      } else {
+        videoRef.current.pause();
+      }
+    }
+  }, [isPlaying]);
+
+  return (
+    <div
+      className="not-prose relative z-1 overflow-hidden rounded-xl border border-separator"
+      data-playing={isPlaying}
+    >
+      {isLoading ? (
+        <Spinner
+          className="absolute top-1/2 left-1/2 z-2 -translate-x-1/2 -translate-y-1/2"
+          color="accent"
+          size="md"
+        />
+      ) : null}
+
+      <div className="absolute right-3 bottom-3 z-2 flex items-center gap-1">
+        <Tooltip delay={500}>
+          <Tooltip.Trigger>
+            <Button
+              isIconOnly
+              className="bg-transparent before:absolute before:inset-0 before:z-[-1] before:block before:rounded-lg before:bg-black/10 before:backdrop-blur-md before:backdrop-saturate-150 before:content-['']"
+              size="sm"
+              variant="tertiary"
+              onPress={onTogglePlay}
+            >
+              {isPlaying ? (
+                <Iconify className="text-white" icon="gravity-ui:pause-fill" width={16} />
+              ) : (
+                <Iconify className="text-white" icon="gravity-ui:play-fill" width={16} />
+              )}
+            </Button>
+          </Tooltip.Trigger>
+          <Tooltip.Content>{isPlaying ? "Pause" : "Play"}</Tooltip.Content>
+        </Tooltip>
+
+        <Tooltip delay={500}>
+          <Tooltip.Trigger>
+            <Button
+              isIconOnly
+              className="bg-transparent before:absolute before:inset-0 before:z-[-1] before:block before:rounded-lg before:bg-black/10 before:backdrop-blur-md before:backdrop-saturate-150 before:content-['']"
+              size="sm"
+              variant="tertiary"
+              onPress={onToggleMute}
+            >
+              {isMuted ? (
+                <VolumeSlashFill className="size-4 text-white" />
+              ) : (
+                <VolumeFill className="size-4 text-white" />
+              )}
+            </Button>
+          </Tooltip.Trigger>
+          <Tooltip.Content>{isMuted ? "Unmute" : "Mute"}</Tooltip.Content>
+        </Tooltip>
+
+        <Tooltip delay={500}>
+          <Tooltip.Trigger>
+            <Button
+              isIconOnly
+              className="bg-transparent before:absolute before:inset-0 before:z-[-1] before:block before:rounded-lg before:bg-black/10 before:backdrop-blur-md before:backdrop-saturate-150 before:content-['']"
+              size="sm"
+              variant="tertiary"
+              onPress={onRestart}
+            >
+              <ArrowRotateLeft className="size-4 text-white" />
+            </Button>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Restart</Tooltip.Content>
+        </Tooltip>
+      </div>
+
+      <div className="absolute inset-0 z-1 cursor-pointer" onClick={handleVideoClick} />
+
+      <video
+        ref={setVideoRef}
+        loop
+        playsInline
+        autoPlay={!!autoPlay && effectivePlayMode === "auto"}
+        className={cn("aspect-video w-full object-cover", className)}
+        controls={controls}
+        height={height}
+        muted={isMuted}
+        poster={poster}
+        src={src}
+        width={width}
+        onCanPlay={handleCanPlay}
+        onPause={handlePause}
+        onPlay={handlePlay}
+      />
+    </div>
+  );
+};
diff --git a/apps/docs/src/config/native-app.ts b/apps/docs/src/config/native-app.ts
new file mode 100644
index 0000000..dc731f8
--- /dev/null
+++ b/apps/docs/src/config/native-app.ts
@@ -0,0 +1,66 @@
+/**
+ * Centralised configuration for the HeroUI Native mobile app surfaces in the
+ * docs site. Used by:
+ *  - the QR popover that appears next to every component preview
+ *  - the "Try on Device" MDX section in release notes
+ *  - the "Download the App" web fallback rendered when a user opens a
+ *    Universal Link without the native app installed
+ *
+ * Centralising these values keeps every entry point in sync — when the Android
+ * build is ready we only flip one constant here instead of hunting through
+ * components and MDX pages.
+ */
+export const NATIVE_APP = {
+  /**
+   * App Store listing for the HeroUI Native iOS app. Always defined because
+   * iOS is the canonical Universal-Links target and the App Store badge is
+   * always shown in the download UI.
+   */
+  APP_STORE_URL: "https://apps.apple.com/app/id6757860059",
+  /**
+   * Human-readable product name used in copy ("Open in HeroUI Native",
+   * "Download HeroUI Native on the App Store", etc.). Kept here so it tracks
+   * any future rebranding from a single source of truth.
+   */
+  NAME: "HeroUI Native",
+  /**
+   * Set to `null` while the Android build isn't published yet. Both the QR
+   * popover and the DownloadAppBanner render a disabled "Coming soon" state
+   * automatically when this is `null`. When the Play Store listing goes live,
+   * paste its URL here and both surfaces re-enable with no other code changes.
+   */
+  PLAY_STORE_URL: "https://play.google.com/store/apps/details?id=com.herouinative.android",
+  /**
+   * Custom URL scheme registered by the native app. Used by the in-page
+   * "Open in app" tap link on mobile to bypass iOS's same-domain Safari
+   * limitation (Universal Links don't fire when tapping a link to the same
+   * domain you're already on in Safari — see
+   * https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html).
+   * The scheme path mirrors the Universal Link path so the native app's
+   * `+native-intent` handler can route both transparently.
+   */
+  SCHEME: "herouinative",
+  /**
+   * URL path prefix used by the docs app to serve the web fallback for
+   * `/docs/native-showcase/components/{slug}` Universal Links. The same prefix
+   * is encoded into the QR code on every component page so that:
+   *  - On-device, the AASA glob (`/docs/native-showcase/components/*`)
+   *    redirects the link into the installed HeroUI Native app.
+   *  - Off-device (or when the app isn't installed), the browser falls back
+   *    to the route handler at `apps/docs/src/app/native-showcase/...`.
+   */
+  SHOWCASE_PATH_PREFIX: "/docs/native-showcase/components",
+} as const satisfies {
+  APP_STORE_URL: string;
+  NAME: string;
+  PLAY_STORE_URL: string | null;
+  SCHEME: string;
+  SHOWCASE_PATH_PREFIX: string;
+};
+
+/**
+ * Type alias for the immutable native-app config object. Useful when threading
+ * config through helpers that need to accept any future replacement of this
+ * object shape.
+ */
+export type NativeAppConfig = typeof NATIVE_APP;
diff --git a/apps/docs/src/config/site.ts b/apps/docs/src/config/site.ts
new file mode 100644
index 0000000..fde4908
--- /dev/null
+++ b/apps/docs/src/config/site.ts
@@ -0,0 +1,32 @@
+import {__BASE_URL__, __CDN_URL__} from "@/utils/env";
+
+export const siteConfig = {
+  authors: [
+    {
+      name: "HeroUI",
+      url: "https://x.com/hero_ui",
+    },
+  ],
+  cdnUrl: __CDN_URL__,
+  creator: "heroui-inc",
+  description:
+    "Beautiful, accessible React UI components built on React Aria and Tailwind CSS v4. The modern alternative to MUI, Chakra UI, and shadcn/ui for building production-ready applications.",
+  figmaCommunityFile: "https://www.figma.com/community/file/1546526812159103429",
+  fullName: "HeroUI v3 (Previously NextUI) - Beautiful by default, customizable by design.",
+  githubRawUrl:
+    "https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs",
+  githubRepo: "heroui-inc/heroui",
+  githubUrl: "https://github.com/heroui-inc/heroui",
+  links: {
+    discord: "https://discord.gg/9b6yyZKmH4",
+    github: "https://github.com/heroui-inc",
+    twitter: "https://x.com/hero_ui",
+  },
+  name: "HeroUI",
+  ogImage: `/images/twitter-card.jpg`,
+  ogImageNative: `/images/twitter-card-native.jpeg`,
+  siteUrl: __BASE_URL__,
+  supportEmail: "support@heroui.com",
+};
+
+export type SiteConfig = typeof siteConfig;
diff --git a/apps/docs/src/demos/cn/accordion/basic.tsx b/apps/docs/src/demos/cn/accordion/basic.tsx
new file mode 100644
index 0000000..b056438
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/basic.tsx
@@ -0,0 +1,68 @@
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。",
+    icon: <ShoppingBag />,
+    title: "如何下单？",
+  },
+  {
+    content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。",
+    icon: <Receipt />,
+    title: "可以修改或取消订单吗？",
+  },
+  {
+    content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。",
+    icon: <CreditCard />,
+    title: "支持哪些支付方式？",
+  },
+  {
+    content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。",
+    icon: <Box />,
+    title: "运费如何计算？",
+  },
+  {
+    content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。",
+    icon: <PlanetEarth />,
+    title: "是否提供国际配送？",
+  },
+  {
+    content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。",
+    icon: <ArrowsRotateLeft />,
+    title: "如何申请退款？",
+  },
+];
+
+export function Basic() {
+  return (
+    <Accordion className="w-full max-w-md">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/controlled.tsx b/apps/docs/src/demos/cn/accordion/controlled.tsx
new file mode 100644
index 0000000..6a957f2
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/controlled.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import {ChevronDown, ChevronUp} from "@gravity-ui/icons";
+import {Accordion, Button, useDisclosureGroupNavigation} from "@heroui/react";
+import React from "react";
+
+const items = [
+  {
+    content:
+      "了解 HeroUI 的基础知识，以及如何将其集成到你的 React 项目中。本节涵盖安装、配置和你的第一个组件。",
+    id: "getting-started",
+    title: "快速开始",
+  },
+  {
+    content:
+      "理解 HeroUI 背后的核心概念，包括复合组件模式、使用 Tailwind CSS 进行样式设计，以及无障碍特性。",
+    id: "core-concepts",
+    title: "核心概念",
+  },
+  {
+    content: "探索高级特性，例如自定义变体、主题定制，以及与 React 生态中其他库的集成。",
+    id: "advanced-usage",
+    title: "高级用法",
+  },
+];
+
+export function Controlled() {
+  const [expandedKeys, setExpandedKeys] = React.useState(
+    new Set<string | number>(["getting-started"]),
+  );
+  const itemIds = items.map((item) => item.id);
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="mb-4 flex items-center justify-between">
+        <p className="text-sm text-muted">
+          已展开：<strong>{[...expandedKeys].join("、") || "无"}</strong>
+        </p>
+        <div className="flex gap-2">
+          <Button
+            aria-label="上一项"
+            isDisabled={isPrevDisabled}
+            size="sm"
+            variant="secondary"
+            onPress={onPrevious}
+          >
+            <ChevronUp className="size-4" />
+          </Button>
+          <Button
+            aria-label="下一项"
+            isDisabled={isNextDisabled}
+            size="sm"
+            variant="secondary"
+            onPress={onNext}
+          >
+            <ChevronDown className="size-4" />
+          </Button>
+        </div>
+      </div>
+      <Accordion expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+        {items.map((item) => (
+          <Accordion.Item key={item.id} id={item.id}>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                {item.title}
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>{item.content}</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        ))}
+      </Accordion>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/custom-indicator.tsx b/apps/docs/src/demos/cn/accordion/custom-indicator.tsx
new file mode 100644
index 0000000..de7a1a7
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/custom-indicator.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {ChevronsDown, CircleChevronDown, Minus, Plus} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+import React from "react";
+
+export function CustomIndicator() {
+  const [expandedKeys, setExpandedKeys] = React.useState<Set<Key>>(new Set([""]));
+
+  return (
+    <Accordion
+      className="w-full max-w-md"
+      expandedKeys={expandedKeys}
+      variant="surface"
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            使用加号/减号图标
+            <Accordion.Indicator>
+              {expandedKeys.has("1") ? <Minus /> : <Plus />}
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>折叠时显示加号图标，展开时切换为减号图标。</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            使用圆形箭头图标
+            <Accordion.Indicator>
+              <CircleChevronDown />
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>此项使用圆形内的箭头作为指示器，旋转动画会自动应用。</Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item id="3">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            使用双箭头图标
+            <Accordion.Indicator>
+              <ChevronsDown />
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            此项使用双箭头图标。传入任意图标后，在条目展开时都会获得旋转动画。
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/custom-render-function.tsx b/apps/docs/src/demos/cn/accordion/custom-render-function.tsx
new file mode 100644
index 0000000..7dd9f8b
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/custom-render-function.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。",
+    icon: <ShoppingBag />,
+    title: "如何下单？",
+  },
+  {
+    content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。",
+    icon: <Receipt />,
+    title: "可以修改或取消订单吗？",
+  },
+  {
+    content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。",
+    icon: <CreditCard />,
+    title: "支持哪些支付方式？",
+  },
+  {
+    content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。",
+    icon: <Box />,
+    title: "运费如何计算？",
+  },
+  {
+    content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。",
+    icon: <PlanetEarth />,
+    title: "是否提供国际配送？",
+  },
+  {
+    content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。",
+    icon: <ArrowsRotateLeft />,
+    title: "如何申请退款？",
+  },
+];
+
+export function CustomRenderFunction() {
+  return (
+    <Accordion
+      className="w-full max-w-md"
+      render={(props) => <div data-custom="accordion" {...props} />}
+    >
+      {items.map((item, index) => (
+        <Accordion.Item key={index} render={(props) => <div data-custom="item" {...props} />}>
+          <Accordion.Heading render={(props) => <div data-custom="heading" {...props} />}>
+            <Accordion.Trigger render={(props) => <button data-custom="trigger" {...props} />}>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel render={(props) => <div data-custom="panel" {...props} />}>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/custom-styles.tsx b/apps/docs/src/demos/cn/accordion/custom-styles.tsx
new file mode 100644
index 0000000..e79b71e
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/custom-styles.tsx
@@ -0,0 +1,63 @@
+import {ChevronDown} from "@gravity-ui/icons";
+import {Accordion, cn} from "@heroui/react";
+
+const items = [
+  {
+    content: "通过实时通知及时了解账户动态。",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    subtitle: "接收账户活动更新",
+    title: "开启通知",
+  },
+  {
+    content: "安装我们的官方浏览器扩展，获得更顺畅的浏览体验。",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    subtitle: "将浏览器连接到你的账户",
+    title: "安装浏览器扩展",
+  },
+  {
+    content: "创建你的第一件数字藏品，开启数字收藏之旅。",
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    subtitle: "创建你的第一件收藏品",
+    title: "铸造收藏品",
+  },
+];
+
+export function CustomStyles() {
+  return (
+    <Accordion className="bg-surface-1/10 w-full max-w-md rounded-2xl" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item
+          key={index}
+          className={cn(
+            "group/item",
+            "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top
+            "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom
+          )}
+        >
+          <Accordion.Heading>
+            <Accordion.Trigger className="hover:bgsurface group flex items-center gap-2 transition-none">
+              {item.iconUrl ? (
+                <img
+                  alt={item.title}
+                  className="h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:scale-120 group-hover/item:-rotate-10 group-hover/item:drop-shadow-lg"
+                  src={item.iconUrl}
+                />
+              ) : null}
+              <div className="flex flex-col gap-0">
+                <span className="leading-5 font-medium">{item.title}</span>
+                <span className="leading-6 font-normal text-muted/80">{item.subtitle}</span>
+              </div>
+              <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/disabled.tsx b/apps/docs/src/demos/cn/accordion/disabled.tsx
new file mode 100644
index 0000000..708c211
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/disabled.tsx
@@ -0,0 +1,77 @@
+import {Accordion} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-full flex-col items-center gap-8">
+      <div className="w-full max-w-md space-y-2">
+        <h3 className="text-sm font-medium text-muted">整个手风琴禁用</h3>
+        <Accordion isDisabled className="w-full max-w-md">
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                禁用项 1
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>手风琴禁用时无法查看此内容。</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                禁用项 2
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>手风琴禁用时无法查看此内容。</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </div>
+
+      <div className="w-full max-w-md space-y-2">
+        <h3 className="text-sm font-medium text-muted">单独禁用条目</h3>
+        <Accordion className="w-full max-w-md">
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                可用项
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>此项可用，可正常展开与折叠。</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item isDisabled>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                禁用项
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>条目禁用时无法查看此内容。</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                另一可用项
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>此项同样可用，可正常切换。</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/faq.tsx b/apps/docs/src/demos/cn/accordion/faq.tsx
new file mode 100644
index 0000000..3dbb9b0
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/faq.tsx
@@ -0,0 +1,75 @@
+import {ChevronDown} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+export function FAQ() {
+  const categories = [
+    {
+      items: [
+        {
+          content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。",
+          title: "如何下单？",
+        },
+        {
+          content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。",
+          title: "可以修改或取消订单吗？",
+        },
+      ],
+      title: "常规",
+    },
+    {
+      items: [
+        {
+          content: "你可以直接在官网购买许可证，选择适合的许可证类型后前往结账即可。",
+          title: "如何购买许可证？",
+        },
+        {
+          content: "标准版适用于个人或小项目；专业版包含商业使用授权与优先支持。",
+          title: "标准版与专业版有什么区别？",
+        },
+      ],
+      title: "许可",
+    },
+    {
+      items: [
+        {
+          content: "可通过网站上的联系表单联系支持团队，或直接发送邮件至 support@example.com。",
+          title: "如何获取支持？",
+        },
+      ],
+      title: "支持",
+    },
+  ];
+
+  return (
+    <div className="flex w-full flex-col gap-6">
+      <div className="flex flex-col gap-1">
+        <h2 className="text-2xl font-bold">常见问题</h2>
+        <p className="mb-4 text-lg font-medium text-muted">
+          关于许可与使用，你需要了解的内容都在这里。
+        </p>
+      </div>
+      {categories.map((category) => (
+        <div key={category.title}>
+          <p className="text-md mb-2 font-medium text-muted">{category.title}</p>
+          <Accordion className="w-full" variant="surface">
+            {category.items.map((item, index) => (
+              <Accordion.Item key={index}>
+                <Accordion.Heading>
+                  <Accordion.Trigger>
+                    {item.title}
+                    <Accordion.Indicator>
+                      <ChevronDown />
+                    </Accordion.Indicator>
+                  </Accordion.Trigger>
+                </Accordion.Heading>
+                <Accordion.Panel>
+                  <Accordion.Body>{item.content}</Accordion.Body>
+                </Accordion.Panel>
+              </Accordion.Item>
+            ))}
+          </Accordion>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/index.ts b/apps/docs/src/demos/cn/accordion/index.ts
new file mode 100644
index 0000000..06e302a
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FAQ} from "./faq";
+export {Multiple} from "./multiple";
+export {Surface} from "./surface";
+export {CustomStyles} from "./custom-styles";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/cn/accordion/multiple.tsx b/apps/docs/src/demos/cn/accordion/multiple.tsx
new file mode 100644
index 0000000..4c3ae5b
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/multiple.tsx
@@ -0,0 +1,65 @@
+import {Accordion} from "@heroui/react";
+
+export function Multiple() {
+  return (
+    <Accordion allowsMultipleExpanded className="w-full max-w-md">
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            快速开始
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            了解 HeroUI 的基础知识，以及如何将其集成到你的 React
+            项目中。本节涵盖安装、配置和你的第一个组件。
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            核心概念
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            理解 HeroUI 背后的核心概念，包括复合组件模式、使用 Tailwind CSS
+            进行样式设计，以及无障碍特性。
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            高级用法
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            探索高级特性，例如自定义变体、主题定制，以及与 React 生态中其他库的集成。
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            最佳实践
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            遵循我们建议的最佳实践，使用 HeroUI 构建高性能、无障碍且易于维护的应用。
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/surface.tsx b/apps/docs/src/demos/cn/accordion/surface.tsx
new file mode 100644
index 0000000..0c0bc64
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/surface.tsx
@@ -0,0 +1,68 @@
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。",
+    icon: <ShoppingBag />,
+    title: "如何下单？",
+  },
+  {
+    content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。",
+    icon: <Receipt />,
+    title: "可以修改或取消订单吗？",
+  },
+  {
+    content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。",
+    icon: <CreditCard />,
+    title: "支持哪些支付方式？",
+  },
+  {
+    content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。",
+    icon: <Box />,
+    title: "运费如何计算？",
+  },
+  {
+    content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。",
+    icon: <PlanetEarth />,
+    title: "是否提供国际配送？",
+  },
+  {
+    content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。",
+    icon: <ArrowsRotateLeft />,
+    title: "如何申请退款？",
+  },
+];
+
+export function Surface() {
+  return (
+    <Accordion className="w-full max-w-md" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/accordion/without-separator.tsx b/apps/docs/src/demos/cn/accordion/without-separator.tsx
new file mode 100644
index 0000000..4e39b8b
--- /dev/null
+++ b/apps/docs/src/demos/cn/accordion/without-separator.tsx
@@ -0,0 +1,45 @@
+import {ChevronDown, CreditCard, Receipt, ShoppingBag} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。",
+    icon: <ShoppingBag />,
+    title: "如何下单？",
+  },
+  {
+    content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。",
+    icon: <Receipt />,
+    title: "可以修改或取消订单吗？",
+  },
+  {
+    content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。",
+    icon: <CreditCard />,
+    title: "支持哪些支付方式？",
+  },
+];
+
+export function WithoutSeparator() {
+  return (
+    <Accordion hideSeparator className="w-full max-w-md">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/backdrop-variants.tsx b/apps/docs/src/demos/cn/alert-dialog/backdrop-variants.tsx
new file mode 100644
index 0000000..9e645f9
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/backdrop-variants.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+const VARIANT_LABELS = {
+  blur: "模糊",
+  opaque: "不透明",
+  transparent: "透明",
+} as const;
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <AlertDialog key={variant}>
+          <Button variant="secondary">{VARIANT_LABELS[variant]}</Button>
+          <AlertDialog.Backdrop variant={variant}>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>背景：{VARIANT_LABELS[variant]}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {variant === "opaque"
+                      ? "不透明的深色背景会完全遮挡背后内容，让用户把注意力集中在对话框上。"
+                      : variant === "blur"
+                        ? "模糊背景会柔和地虚化背后内容，同时保留一定的环境上下文。"
+                        : "透明背景会完整保留背后内容，适合重要性较低的确认场景。"}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/close-methods.tsx b/apps/docs/src/demos/cn/alert-dialog/close-methods.tsx
new file mode 100644
index 0000000..7b893e3
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/close-methods.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CloseMethods() {
+  return (
+    <div className="flex max-w-2xl flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">
+          使用 <code className="text-sm">slot=&quot;close&quot;</code>
+        </h3>
+        <p className="text-sm text-muted">
+          最简单的关闭方式：在对话框内的任意 <code>Button</code> 上添加{" "}
+          <code>slot=&quot;close&quot;</code>，点击后会自动关闭对话框。
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">打开对话框</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    使用 <code className="text-sm">slot=&quot;close&quot;</code>
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    点击下方任一按钮——它们都带有 <code>slot=&quot;close&quot;</code>
+                    ，点击后会自动关闭对话框。
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">使用 Dialog 的 render props</h3>
+        <p className="text-sm text-muted">
+          通过 Dialog 的 render props 获取 <code>close</code>{" "}
+          方法，从而完全控制关闭时机与方式，便于在关闭前加入校验等自定义逻辑。
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">打开对话框</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                {(renderProps) => (
+                  <>
+                    <AlertDialog.Header>
+                      <AlertDialog.Icon status="success" />
+                      <AlertDialog.Heading>使用 Dialog render props</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p>
+                        下方按钮使用 render props 提供的 <code>close</code> 方法。你可以在调用{" "}
+                        <code>renderProps.close()</code> 之前加入校验或其他逻辑。
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer>
+                      <Button variant="tertiary" onPress={() => renderProps.close()}>
+                        取消
+                      </Button>
+                      <Button onPress={() => renderProps.close()}>确认</Button>
+                    </AlertDialog.Footer>
+                  </>
+                )}
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/controlled.tsx b/apps/docs/src/demos/cn/alert-dialog/controlled.tsx
new file mode 100644
index 0000000..59e08fe
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/controlled.tsx
@@ -0,0 +1,115 @@
+"use client";
+
+import {AlertDialog, Button, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 React 的 <code className="text-foreground">useState</code>{" "}
+          管理对话框开关，适合简单场景。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              打开对话框
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="accent" />
+                <AlertDialog.Heading>由 useState() 控制</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  该警告对话框由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "}
+                  <code>onOpenChange</code> 传入即可在外部管理状态。
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  取消
+                </Button>
+                <Button slot="close">确认</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "}
+          <code>open()</code>、<code>close()</code>、<code>toggle()</code> 等方法。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              打开对话框
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="success" />
+                <AlertDialog.Heading>由 useOverlayState() 控制</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "}
+                  <code>state.open()</code>、<code>state.close()</code> 或{" "}
+                  <code>state.toggle()</code> 即可。
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  取消
+                </Button>
+                <Button slot="close">确认</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/custom-animations.tsx b/apps/docs/src/demos/cn/alert-dialog/custom-animations.tsx
new file mode 100644
index 0000000..4bac7cf
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/custom-animations.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+import React from "react";
+
+const iconMap: Record<string, React.ComponentType<{className?: string}>> = {
+  "gravity-ui:arrow-up-from-line": ArrowUpFromLine,
+  "gravity-ui:sparkles": Sparkles,
+};
+
+export function CustomAnimations() {
+  const animations = [
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+      description:
+        "基于物理感的弹性缩放，模拟高阻尼弹簧：瞬态响应快、回落时间长，适合警告框与模态框。",
+      icon: "gravity-ui:sparkles",
+      name: "运动学缩放",
+    },
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+      description:
+        "模拟在介质中运动并受流体阻力影响，避免机械式线性，更自然、更贴地，适合底部抽屉或 Toast。",
+      icon: "gravity-ui:arrow-up-from-line",
+      name: "流体滑入",
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => {
+        const IconComponent = iconMap[icon];
+
+        return (
+          <AlertDialog key={name}>
+            <Button variant="secondary">{name}</Button>
+            <AlertDialog.Backdrop className={classNames.backdrop}>
+              <AlertDialog.Container className={classNames.container}>
+                <AlertDialog.Dialog className="sm:max-w-[400px]">
+                  <AlertDialog.CloseTrigger />
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="accent">
+                      {!!IconComponent && <IconComponent className="size-5" />}
+                    </AlertDialog.Icon>
+                    <AlertDialog.Heading>{name} 动画</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p className="mt-1">{description}</p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button slot="close" variant="tertiary">
+                      关闭
+                    </Button>
+                    <Button slot="close">再试一次</Button>
+                  </AlertDialog.Footer>
+                </AlertDialog.Dialog>
+              </AlertDialog.Container>
+            </AlertDialog.Backdrop>
+          </AlertDialog>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/custom-backdrop.tsx b/apps/docs/src/demos/cn/alert-dialog/custom-backdrop.tsx
new file mode 100644
index 0000000..cfc016d
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/custom-backdrop.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {TriangleExclamation} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomBackdrop() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">删除账户</Button>
+      <AlertDialog.Backdrop
+        className="bg-linear-to-t from-red-950/90 via-red-950/50 to-transparent dark:from-red-950/95 dark:via-red-950/60"
+        variant="blur"
+      >
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[420px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header className="items-center text-center">
+              <AlertDialog.Icon status="danger">
+                <TriangleExclamation className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>要永久删除账户吗？</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                此操作无法撤销。你的数据、设置与内容将从服务器永久清除。醒目的红色背景用于强调该决定的严重性与不可逆性。
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer className="flex-col-reverse">
+              <Button className="w-full" slot="close">
+                保留账户
+              </Button>
+              <Button className="w-full" slot="close" variant="danger">
+                永久删除
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/custom-icon.tsx b/apps/docs/src/demos/cn/alert-dialog/custom-icon.tsx
new file mode 100644
index 0000000..9744c96
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/custom-icon.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {LockOpen} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomIcon() {
+  return (
+    <AlertDialog>
+      <Button variant="secondary">重置密码</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="warning">
+                <LockOpen className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>要重置密码吗？</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>我们会向你的邮箱发送重置链接。你需要设置新密码以恢复账户访问。</p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                取消
+              </Button>
+              <Button slot="close">发送重置链接</Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/custom-portal.tsx b/apps/docs/src/demos/cn/alert-dialog/custom-portal.tsx
new file mode 100644
index 0000000..5c96cc0
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/custom-portal.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+export function CustomPortal() {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          将警告对话框渲染到自定义容器，而不是 <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          为容器应用 <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code>{" "}
+          可创建新的层叠上下文。
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <AlertDialog>
+            <Button>打开警告对话框</Button>
+            <AlertDialog.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <AlertDialog.Container className="h-full max-h-full">
+                <AlertDialog.Dialog className="h-full max-h-full sm:max-w-md">
+                  <AlertDialog.CloseTrigger />
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="accent" />
+                    <AlertDialog.Heading>自定义传送门</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p className="text-sm text-muted">
+                      此段为示例占位文案，用于演示在自定义容器内渲染对话框时的滚动与排版效果。实际项目中请替换为真实说明内容。
+                    </p>
+                    <p className="text-sm text-muted">
+                      通过将浮层挂载到局部容器，可以配合裁剪、缩放或卡片布局，避免遮挡整个页面，同时仍保持焦点管理与无障碍行为。
+                    </p>
+                    <p className="text-sm text-muted">
+                      若容器存在 <code>transform</code> 或 <code>filter</code>{" "}
+                      等属性，请注意浏览器会为其创建新的包含块，从而影响定位与层级关系。
+                    </p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button slot="close" variant="tertiary">
+                      取消
+                    </Button>
+                    <Button slot="close">确认</Button>
+                  </AlertDialog.Footer>
+                </AlertDialog.Dialog>
+              </AlertDialog.Container>
+            </AlertDialog.Backdrop>
+          </AlertDialog>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/custom-trigger.tsx b/apps/docs/src/demos/cn/alert-dialog/custom-trigger.tsx
new file mode 100644
index 0000000..6f2ae2d
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/custom-trigger.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import {TrashBin} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <AlertDialog>
+      <AlertDialog.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+        <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger-soft-foreground">
+          <TrashBin className="size-6" />
+        </div>
+        <div className="flex flex-1 flex-col gap-0.5">
+          <p className="text-sm font-semibold">删除条目</p>
+          <p className="text-xs text-muted">永久移除此条目</p>
+        </div>
+      </AlertDialog.Trigger>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger">
+                <TrashBin className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>要删除此条目吗？</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                使用 <code>AlertDialog.Trigger</code>{" "}
+                可在标准按钮之外自定义触发区域。此示例展示带图标与说明文字的卡片式触发器。
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                取消
+              </Button>
+              <Button slot="close" variant="danger">
+                删除条目
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/default.tsx b/apps/docs/src/demos/cn/alert-dialog/default.tsx
new file mode 100644
index 0000000..dac7b3e
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/default.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Default() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">删除项目</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger" />
+              <AlertDialog.Heading>要永久删除项目吗？</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                此操作将永久删除 <strong>我的精彩项目</strong> 及其全部数据，且无法撤销。
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                取消
+              </Button>
+              <Button slot="close" variant="danger">
+                删除项目
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/dismiss-behavior.tsx b/apps/docs/src/demos/cn/alert-dialog/dismiss-behavior.tsx
new file mode 100644
index 0000000..9775810
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/dismiss-behavior.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function DismissBehavior() {
+  return (
+    <div className="flex max-w-sm flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isDismissable</h3>
+        <p className="text-sm text-muted">
+          控制是否允许通过点击遮罩关闭对话框。警告框通常需要明确操作，因此默认为 <code>false</code>
+          。对重要性较低的确认，可设为 <code>true</code>。
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">打开警告对话框</Button>
+          <AlertDialog.Backdrop isDismissable={false}>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="danger">
+                    <CircleInfo className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>isDismissable = false</AlertDialog.Heading>
+                  <p className="text-sm leading-5 text-muted">点击遮罩不会关闭此对话框</p>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>尝试点击遮罩区域——对话框不会关闭，必须通过底部操作按钮关闭。</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+        <p className="text-sm text-muted">
+          控制是否允许通过 ESC 关闭。警告框通常需要明确操作，因此默认为 <code>true</code>（禁用
+          ESC）。设为 <code>false</code> 时将允许 ESC 关闭。
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">打开警告对话框</Button>
+          <AlertDialog.Backdrop isKeyboardDismissDisabled>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent">
+                    <CircleInfo className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>isKeyboardDismissDisabled = true</AlertDialog.Heading>
+                  <p className="text-sm leading-5 text-muted">已禁用 ESC 关闭</p>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>按下 ESC 不会有任何反应，必须通过操作按钮关闭此对话框。</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/index.ts b/apps/docs/src/demos/cn/alert-dialog/index.ts
new file mode 100644
index 0000000..d5bb4ee
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/index.ts
@@ -0,0 +1,14 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {CloseMethods} from "./close-methods";
+export {Controlled} from "./controlled";
+export {CustomAnimations} from "./custom-animations";
+export {CustomBackdrop} from "./custom-backdrop";
+export {CustomIcon} from "./custom-icon";
+export {CustomPortal} from "./custom-portal";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {DismissBehavior} from "./dismiss-behavior";
+export {Placements} from "./placements";
+export {Sizes} from "./sizes";
+export {Statuses} from "./statuses";
+export {WithCloseButton} from "./with-close-button";
diff --git a/apps/docs/src/demos/cn/alert-dialog/placements.tsx b/apps/docs/src/demos/cn/alert-dialog/placements.tsx
new file mode 100644
index 0000000..b95b89e
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/placements.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+const PLACEMENT_LABELS = {
+  auto: "自动",
+  bottom: "底部",
+  center: "居中",
+  top: "顶部",
+} as const;
+
+export function Placements() {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <AlertDialog key={placement}>
+          <Button variant="secondary">{PLACEMENT_LABELS[placement]}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container placement={placement}>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    {placement === "auto" ? "自动定位" : `${PLACEMENT_LABELS[placement]}位置`}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {placement === "auto"
+                      ? "在移动端默认靠近底部，在桌面端居中，以获得更合适的阅读与操作体验。"
+                      : `对话框将锚定在视口的「${PLACEMENT_LABELS[placement]}」区域。重要确认通常使用居中 placement 以吸引最多注意。`}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/sizes.tsx b/apps/docs/src/demos/cn/alert-dialog/sizes.tsx
new file mode 100644
index 0000000..53ed91e
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/sizes.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+const SIZE_LABELS = {
+  cover: "通栏",
+  lg: "大",
+  md: "中",
+  sm: "小",
+  xs: "超小",
+} as const;
+
+export function Sizes() {
+  const sizes = ["xs", "sm", "md", "lg", "cover"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <AlertDialog key={size}>
+          <Button variant="secondary">{SIZE_LABELS[size]}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container size={size}>
+              <AlertDialog.Dialog>
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>尺寸：{SIZE_LABELS[size]}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        此警告框使用 <code>cover</code> 尺寸：在移动端与桌面端保留边距（移动端约
+                        16px、桌面端约
+                        40px）铺满可视区域，仍保持圆角与标准内边距，适合需要最大宽度又保留对话框气质的关键确认。
+                      </>
+                    ) : (
+                      <>
+                        此警告框使用 <code>{size}</code>{" "}
+                        尺寸。在移动端各尺寸都会接近全宽以便阅读；在桌面端则对应不同的最大宽度，以适配不同信息量。
+                      </>
+                    )}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/statuses.tsx b/apps/docs/src/demos/cn/alert-dialog/statuses.tsx
new file mode 100644
index 0000000..9066eb7
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/statuses.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Statuses() {
+  const examples = [
+    {
+      actions: {
+        cancel: "保持登录",
+        confirm: "退出登录",
+      },
+      body: "退出后需要重新登录才能访问账户，未保存的更改将丢失。",
+      classNames: "bg-accent-soft text-accent-soft-foreground",
+      header: "要退出当前账户吗？",
+      status: "accent",
+      trigger: "退出登录",
+    },
+    {
+      actions: {
+        cancel: "稍后再说",
+        confirm: "标记完成",
+      },
+      body: "将把该任务标记为完成并通知所有成员，任务会移入已完成列表。",
+      classNames: "bg-success-soft text-success-soft-foreground",
+      header: "要完成此任务吗？",
+      status: "success",
+      trigger: "完成任务",
+    },
+    {
+      actions: {
+        cancel: "继续编辑",
+        confirm: "放弃更改",
+      },
+      body: "你有未保存的更改，放弃后将永久丢失。确定要放弃吗？",
+      classNames: "bg-warning-soft text-warning-soft-foreground",
+      header: "要放弃未保存的更改吗？",
+      status: "warning",
+      trigger: "放弃更改",
+    },
+    {
+      actions: {
+        cancel: "取消",
+        confirm: "删除账户",
+      },
+      body: "将永久删除你的账户并从服务器移除全部数据，此操作不可恢复。",
+      classNames: "bg-danger-soft text-danger-soft-foreground",
+      header: "要删除账户吗？",
+      status: "danger",
+      trigger: "删除账户",
+    },
+  ] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {examples.map(({actions, body, classNames, header, status, trigger}) => (
+        <AlertDialog key={status}>
+          <Button className={classNames}>{trigger}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status={status} />
+                  <AlertDialog.Heading>{header}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>{body}</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    {actions.cancel}
+                  </Button>
+                  <Button slot="close" variant={status === "danger" ? "danger" : "primary"}>
+                    {actions.confirm}
+                  </Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert-dialog/with-close-button.tsx b/apps/docs/src/demos/cn/alert-dialog/with-close-button.tsx
new file mode 100644
index 0000000..b99b760
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert-dialog/with-close-button.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function WithCloseButton() {
+  return (
+    <AlertDialog>
+      <Button variant="secondary">查看信息</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="accent" />
+              <AlertDialog.Heading>次要信息</AlertDialog.Heading>
+              <p className="text-sm leading-relaxed text-muted">已启用关闭按钮与点击遮罩关闭</p>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                对于重要性较低的确认，可同时启用关闭按钮与点击遮罩关闭，为用户提供多种退出方式。
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                取消
+              </Button>
+              <Button slot="close">确认</Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert/basic.tsx b/apps/docs/src/demos/cn/alert/basic.tsx
new file mode 100644
index 0000000..4c7de98
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert/basic.tsx
@@ -0,0 +1,90 @@
+import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
+import React from "react";
+
+export function Basic() {
+  return (
+    <div className="grid w-full max-w-xl gap-4">
+      {/* 默认 — 一般信息 */}
+      <Alert>
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>新功能已上线</Alert.Title>
+          <Alert.Description>
+            查看我们的最新更新，包括深色模式支持与改进的无障碍体验。
+          </Alert.Description>
+        </Alert.Content>
+      </Alert>
+
+      {/* 强调 — 重要信息含操作 */}
+      <Alert status="accent">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>有可用更新</Alert.Title>
+          <Alert.Description>
+            应用有新版本可用。请刷新页面以获取最新功能与问题修复。
+          </Alert.Description>
+          <Button className="mt-2 sm:hidden" size="sm" variant="primary">
+            刷新
+          </Button>
+        </Alert.Content>
+        <Button className="hidden sm:block" size="sm" variant="primary">
+          刷新
+        </Button>
+      </Alert>
+
+      {/* 危险 — 错误与排查步骤 */}
+      <Alert status="danger">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>无法连接到服务器</Alert.Title>
+          <Alert.Description>
+            当前遇到连接问题，请尝试以下操作：
+            <ul className="mt-2 list-inside list-disc space-y-1 text-sm">
+              <li>检查网络连接</li>
+              <li>刷新页面</li>
+              <li>清除浏览器缓存</li>
+            </ul>
+          </Alert.Description>
+          <Button className="mt-2 sm:hidden" size="sm" variant="danger">
+            重试
+          </Button>
+        </Alert.Content>
+        <Button className="hidden sm:block" size="sm" variant="danger">
+          重试
+        </Button>
+      </Alert>
+
+      {/* 无描述 */}
+      <Alert status="success">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>个人资料已更新</Alert.Title>
+        </Alert.Content>
+        <CloseButton />
+      </Alert>
+
+      {/* 自定义指示器 — 加载中 */}
+      <Alert status="accent">
+        <Alert.Indicator>
+          <Spinner size="sm" />
+        </Alert.Indicator>
+        <Alert.Content>
+          <Alert.Title>正在处理你的请求</Alert.Title>
+          <Alert.Description>正在同步你的数据，请稍候，这可能需要一点时间。</Alert.Description>
+        </Alert.Content>
+      </Alert>
+
+      {/* 无关闭按钮 */}
+      <Alert status="warning">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>计划维护</Alert.Title>
+          <Alert.Description>
+            我们将于 UTC 时间 3 月 15 日（周日）凌晨 2:00 至上午 6:00
+            进行计划维护，期间服务将暂时不可用。
+          </Alert.Description>
+        </Alert.Content>
+      </Alert>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/alert/index.ts b/apps/docs/src/demos/cn/alert/index.ts
new file mode 100644
index 0000000..2294750
--- /dev/null
+++ b/apps/docs/src/demos/cn/alert/index.ts
@@ -0,0 +1 @@
+export {Basic} from "./basic";
diff --git a/apps/docs/src/demos/cn/autocomplete/allows-empty-collection.tsx b/apps/docs/src/demos/cn/autocomplete/allows-empty-collection.tsx
new file mode 100644
index 0000000..55cc378
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/allows-empty-collection.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+
+export function AllowsEmptyCollection() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[256px]"
+      placeholder="请选择一项"
+      selectionMode="single"
+    >
+      <Label>州</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索州名…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>} />
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/asynchronous-filtering.tsx b/apps/docs/src/demos/cn/autocomplete/asynchronous-filtering.tsx
new file mode 100644
index 0000000..92345d4
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/asynchronous-filtering.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, Spinner} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+import {cn} from "tailwind-variants";
+
+interface Character {
+  name: string;
+}
+
+export function AsynchronousFiltering() {
+  const list = useAsyncList<Character>({
+    async load({filterText, signal}) {
+      const res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, {
+        signal,
+      });
+
+      const json = await res.json();
+
+      return {
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[256px]"
+      placeholder="搜索…"
+      selectionMode="single"
+    >
+      <Label>搜索《星球大战》角色</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter inputValue={list.filterText} onInputChange={list.setFilterText}>
+          <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索角色…" />
+              <Spinner
+                size="sm"
+                className={cn("absolute top-1/2 right-2 -translate-y-1/2", {
+                  "pointer-events-none opacity-0": !list.isLoading,
+                })}
+              />
+              <SearchField.ClearButton
+                className={cn({"pointer-events-none opacity-0": !!list.isLoading})}
+              />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox
+            className="max-h-[420px] overflow-y-auto"
+            items={list.items}
+            renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}
+          >
+            {(item: Character) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/controlled-open-state.tsx b/apps/docs/src/demos/cn/autocomplete/controlled-open-state.tsx
new file mode 100644
index 0000000..5456397
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/controlled-open-state.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {
+  Autocomplete,
+  Button,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [isOpen, setIsOpen] = useState(false);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <div className="space-y-4">
+      <Autocomplete
+        className="w-[256px]"
+        isOpen={isOpen}
+        placeholder="请选择一项"
+        selectionMode="single"
+        onOpenChange={setIsOpen}
+      >
+        <Label>州</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索州名…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "关闭" : "打开"} 自动完成</Button>
+      <p className="text-sm text-muted">自动完成处于{isOpen ? "打开" : "关闭"}状态</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/controlled.tsx b/apps/docs/src/demos/cn/autocomplete/controlled.tsx
new file mode 100644
index 0000000..2e75721
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/controlled.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const states = [
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "florida", name: "Florida"},
+    {id: "new-york", name: "New York"},
+    {id: "illinois", name: "Illinois"},
+    {id: "pennsylvania", name: "Pennsylvania"},
+  ];
+
+  const [state, setState] = useState<Key | null>("california");
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const selectedState = states.find((s) => s.id === state);
+
+  return (
+    <div className="space-y-2">
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="选择一个州"
+        selectionMode="single"
+        value={state}
+        onChange={setState}
+      >
+        <Label>州（受控）</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索州名…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {states.map((state) => (
+                <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                  {state.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <p className="text-sm text-muted">已选：{selectedState?.name || "无"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/custom-indicator.tsx b/apps/docs/src/demos/cn/autocomplete/custom-indicator.tsx
new file mode 100644
index 0000000..7c68bb4
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/custom-indicator.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function CustomIndicator() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="请选择一项"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>州</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator className="size-3">
+          <Icon icon="gravity-ui:chevrons-expand-vertical" />
+        </Autocomplete.Indicator>
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索州名…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/default.tsx b/apps/docs/src/demos/cn/autocomplete/default.tsx
new file mode 100644
index 0000000..a11a6d5
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/default.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export default function Default() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择州/省"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys: Key | Key[] | null) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>计划前往的州</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}: any) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item: any) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey: Key) => {
+                    const item = items.find((s) => s.id === selectedItemKey);
+
+                    if (!item) return null;
+
+                    return (
+                      <Tag key={item.id} id={item.id}>
+                        {item.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/disabled.tsx b/apps/docs/src/demos/cn/autocomplete/disabled.tsx
new file mode 100644
index 0000000..06d1a3b
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/disabled.tsx
@@ -0,0 +1,96 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+
+export function Disabled() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const countries = [
+    {id: "argentina", name: "Argentina"},
+    {id: "venezuela", name: "Venezuela"},
+    {id: "japan", name: "Japan"},
+    {id: "france", name: "France"},
+    {id: "italy", name: "Italy"},
+    {id: "spain", name: "Spain"},
+  ];
+
+  return (
+    <div className="flex flex-col gap-4">
+      <Autocomplete
+        isDisabled
+        className="w-[256px]"
+        defaultValue="california"
+        placeholder="请选择一项"
+        selectionMode="single"
+      >
+        <Label>州</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索州名…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <Autocomplete
+        isDisabled
+        className="w-[256px]"
+        defaultValue={["argentina", "japan", "france"]}
+        placeholder="选择国家"
+        selectionMode="multiple"
+      >
+        <Label>计划前往的国家</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索国家…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {countries.map((country) => (
+                <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                  {country.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/email-recipients.tsx b/apps/docs/src/demos/cn/autocomplete/email-recipients.tsx
new file mode 100644
index 0000000..2f2875c
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/email-recipients.tsx
@@ -0,0 +1,98 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function EmailRecipients() {
+  const emails = [
+    {email: "alice@example.com", id: "alice@example.com", name: "Alice Johnson"},
+    {email: "bob@example.com", id: "bob@example.com", name: "Bob Smith"},
+    {email: "charlie@example.com", id: "charlie@example.com", name: "Charlie Brown"},
+    {email: "diana@example.com", id: "diana@example.com", name: "Diana Prince"},
+    {email: "eve@example.com", id: "eve@example.com", name: "Eve Wilson"},
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="添加收件人"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>收件人</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const email = emails.find((e) => e.id === selectedItemKey);
+
+                    if (!email) return null;
+
+                    return (
+                      <Tag key={email.id} id={email.id}>
+                        {email.email}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索邮箱…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到收件人</EmptyState>}>
+            {emails.map((email) => (
+              <ListBox.Item key={email.id} id={email.id} textValue={email.email}>
+                <div className="flex flex-col">
+                  <Label>{email.name}</Label>
+                  <Description>{email.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/full-width.tsx b/apps/docs/src/demos/cn/autocomplete/full-width.tsx
new file mode 100644
index 0000000..f2dbd03
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/full-width.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Surface,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function FullWidth() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Surface className="w-[380px] space-y-4 rounded-3xl p-6">
+      <Autocomplete
+        fullWidth
+        placeholder="请选择一项"
+        selectionMode="single"
+        value={selectedKey}
+        variant="secondary"
+        onChange={setSelectedKey}
+      >
+        <Label>州</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索州名…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/index.ts b/apps/docs/src/demos/cn/autocomplete/index.ts
new file mode 100644
index 0000000..16f5774
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/index.ts
@@ -0,0 +1,22 @@
+// Autocomplete demos
+export {AllowsEmptyCollection} from "./allows-empty-collection";
+export {AsynchronousFiltering} from "./asynchronous-filtering";
+export {Controlled} from "./controlled";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomIndicator} from "./custom-indicator";
+export {default as Default} from "./default";
+export {Disabled} from "./disabled";
+export {EmailRecipients} from "./email-recipients";
+export {FullWidth} from "./full-width";
+export {LocationSearch} from "./location-search";
+export {MultipleSelect} from "./multiple-select";
+export {Required} from "./required";
+export {default as SingleSelect} from "./single-select";
+export {TagGroupSelection} from "./tag-group-selection";
+export {UserSelection} from "./user-selection";
+export {UserSelectionMultiple} from "./user-selection-multiple";
+export {Variants} from "./variants";
+export {Virtualization} from "./virtualization";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/cn/autocomplete/location-search.tsx b/apps/docs/src/demos/cn/autocomplete/location-search.tsx
new file mode 100644
index 0000000..905c8d6
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/location-search.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+interface City {
+  name: string;
+  country: string;
+}
+
+export function LocationSearch() {
+  const allCities: City[] = [
+    {country: "美国", name: "纽约"},
+    {country: "美国", name: "洛杉矶"},
+    {country: "美国", name: "芝加哥"},
+    {country: "英国", name: "伦敦"},
+    {country: "法国", name: "巴黎"},
+    {country: "日本", name: "东京"},
+    {country: "澳大利亚", name: "悉尼"},
+    {country: "加拿大", name: "多伦多"},
+    {country: "德国", name: "柏林"},
+    {country: "西班牙", name: "马德里"},
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  // Simulate async filtering
+  const customFilter = (text: string, inputValue: string) => {
+    if (!inputValue) return true;
+    setIsLoading(true);
+    setTimeout(() => setIsLoading(false), 300);
+
+    return contains(text, inputValue);
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="搜索城市"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>城市</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={customFilter}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索城市…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox
+            renderEmptyState={() => <EmptyState>{isLoading ? "搜索中…" : "未找到城市"}</EmptyState>}
+          >
+            {allCities.map((city) => (
+              <ListBox.Item
+                key={city.name}
+                id={city.name}
+                textValue={`${city.name} ${city.country}`}
+              >
+                <div className="flex flex-col">
+                  <Label>{city.name}</Label>
+                  <Description>{city.country}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/multiple-select.tsx b/apps/docs/src/demos/cn/autocomplete/multiple-select.tsx
new file mode 100644
index 0000000..8247993
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/multiple-select.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function MultipleSelect() {
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "florida", name: "Florida"},
+    {id: "new-york", name: "New York"},
+    {id: "illinois", name: "Illinois"},
+    {id: "pennsylvania", name: "Pennsylvania"},
+  ];
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择州/省"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>州</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const item = items.find((s) => s.id === selectedItemKey);
+
+                    if (!item) return null;
+
+                    return (
+                      <Tag key={item.id} id={item.id}>
+                        {item.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/required.tsx b/apps/docs/src/demos/cn/autocomplete/required.tsx
new file mode 100644
index 0000000..12f654b
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/required.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import {
+  Autocomplete,
+  Button,
+  EmptyState,
+  FieldError,
+  Form,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const states = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const countries = [
+    {id: "usa", name: "United States"},
+    {id: "canada", name: "Canada"},
+    {id: "mexico", name: "Mexico"},
+    {id: "uk", name: "United Kingdom"},
+    {id: "france", name: "France"},
+    {id: "germany", name: "Germany"},
+  ];
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <Autocomplete
+        isRequired
+        className="w-full"
+        name="state"
+        placeholder="请选择一项"
+        selectionMode="single"
+      >
+        <Label>州</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索州名…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {states.map((state) => (
+                <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                  {state.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+        <FieldError />
+      </Autocomplete>
+      <Autocomplete
+        isRequired
+        className="w-full"
+        name="country"
+        placeholder="选择一个国家"
+        selectionMode="single"
+      >
+        <Label>国家</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="搜索国家…" />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+              {countries.map((country) => (
+                <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                  {country.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+        <FieldError />
+      </Autocomplete>
+      <Button type="submit">提交</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/single-select.tsx b/apps/docs/src/demos/cn/autocomplete/single-select.tsx
new file mode 100644
index 0000000..9bbd0be
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/single-select.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export default function SingleSelect() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+
+  const items = [
+    {id: "cat", name: "猫"},
+    {id: "dog", name: "狗"},
+    {id: "elephant", name: "象"},
+    {id: "lion", name: "狮子"},
+    {id: "tiger", name: "老虎"},
+    {id: "giraffe", name: "长颈鹿"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择一种动物"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>最喜欢的动物</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索动物…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/tag-group-selection.tsx b/apps/docs/src/demos/cn/autocomplete/tag-group-selection.tsx
new file mode 100644
index 0000000..e2c3b9d
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/tag-group-selection.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupSelection() {
+  const tags = [
+    {id: "react", name: "React"},
+    {id: "typescript", name: "TypeScript"},
+    {id: "javascript", name: "JavaScript"},
+    {id: "nodejs", name: "Node.js"},
+    {id: "python", name: "Python"},
+    {id: "vue", name: "Vue"},
+    {id: "angular", name: "Angular"},
+    {id: "nextjs", name: "Next.js"},
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择标签"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>标签</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const tag = tags.find((t) => t.id === selectedItemKey);
+
+                    if (!tag) return null;
+
+                    return (
+                      <Tag key={tag.id} id={tag.id}>
+                        {tag.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索标签…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到标签</EmptyState>}>
+            {tags.map((tag) => (
+              <ListBox.Item key={tag.id} id={tag.id} textValue={tag.name}>
+                {tag.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/user-selection-multiple.tsx b/apps/docs/src/demos/cn/autocomplete/user-selection-multiple.tsx
new file mode 100644
index 0000000..50a0bad
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/user-selection-multiple.tsx
@@ -0,0 +1,142 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function UserSelectionMultiple() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      defaultValue={["1", "2"]}
+      placeholder="选择队友"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>用户</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+                    if (!selectedItem) {
+                      return null;
+                    }
+
+                    return (
+                      <Tag key={selectedItem.id} id={selectedItem.id}>
+                        <Avatar className="size-4" size="sm">
+                          <AvatarImage src={selectedItem.avatarUrl} />
+                          <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                        </Avatar>
+                        <span>{selectedItem.name}</span>
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索用户…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/user-selection.tsx b/apps/docs/src/demos/cn/autocomplete/user-selection.tsx
new file mode 100644
index 0000000..18698a5
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/user-selection.tsx
@@ -0,0 +1,131 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function UserSelection() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择用户"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>用户</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItems = state.selectedItems;
+
+            if (selectedItems.length > 1) {
+              return `已选择 ${selectedItems.length} 位用户`;
+            }
+
+            const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
+
+            if (!selectedItem) {
+              return defaultChildren;
+            }
+
+            return (
+              <div className="flex items-center gap-2">
+                <Avatar className="size-4" size="sm">
+                  <AvatarImage src={selectedItem.avatarUrl} />
+                  <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                </Avatar>
+                <span>{selectedItem.name}</span>
+              </div>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索用户…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/variants.tsx b/apps/docs/src/demos/cn/autocomplete/variants.tsx
new file mode 100644
index 0000000..c5704c3
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/variants.tsx
@@ -0,0 +1,241 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function Variants() {
+  const [selectedKey1, setSelectedKey1] = useState<Key | null>(null);
+  const [selectedKey2, setSelectedKey2] = useState<Key | null>(null);
+  const [selectedKeys1, setSelectedKeys1] = useState<Key[]>([]);
+  const [selectedKeys2, setSelectedKeys2] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "option1", name: "选项 1"},
+    {id: "option2", name: "选项 2"},
+    {id: "option3", name: "选项 3"},
+    {id: "option4", name: "选项 4"},
+  ];
+
+  const onRemoveTags1 = (keys: Set<Key>) => {
+    setSelectedKeys1((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  const onRemoveTags2 = (keys: Set<Key>) => {
+    setSelectedKeys2((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-4">
+        <h3 className="text-lg font-semibold">单选变体</h3>
+        <div className="flex flex-col gap-4">
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="请选择一项"
+            selectionMode="single"
+            value={selectedKey1}
+            variant="primary"
+            onChange={setSelectedKey1}
+          >
+            <Label>主色（primary）变体</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value />
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="搜索…" />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="请选择一项"
+            selectionMode="single"
+            value={selectedKey2}
+            variant="secondary"
+            onChange={setSelectedKey2}
+          >
+            <Label>次色（secondary）变体</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value />
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="搜索…" />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+        </div>
+      </div>
+      <div className="flex flex-col gap-4">
+        <h3 className="text-lg font-semibold">多选变体</h3>
+        <div className="flex flex-col gap-4">
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="选择多项"
+            selectionMode="multiple"
+            value={selectedKeys1}
+            variant="primary"
+            onChange={(keys) => setSelectedKeys1(keys as Key[])}
+          >
+            <Label>主色（primary）变体</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value>
+                {({defaultChildren, isPlaceholder, state}) => {
+                  if (isPlaceholder || state.selectedItems.length === 0) {
+                    return defaultChildren;
+                  }
+
+                  const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                  return (
+                    <TagGroup size="sm" onRemove={onRemoveTags1}>
+                      <TagGroup.List>
+                        {selectedItemsKeys.map((selectedItemKey) => {
+                          const item = items.find((s) => s.id === selectedItemKey);
+
+                          if (!item) return null;
+
+                          return (
+                            <Tag key={item.id} id={item.id}>
+                              {item.name}
+                            </Tag>
+                          );
+                        })}
+                      </TagGroup.List>
+                    </TagGroup>
+                  );
+                }}
+              </Autocomplete.Value>
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="搜索…" />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="选择多项"
+            selectionMode="multiple"
+            value={selectedKeys2}
+            variant="secondary"
+            onChange={(keys) => setSelectedKeys2(keys as Key[])}
+          >
+            <Label>次色（secondary）变体</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value>
+                {({defaultChildren, isPlaceholder, state}) => {
+                  if (isPlaceholder || state.selectedItems.length === 0) {
+                    return defaultChildren;
+                  }
+
+                  const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                  return (
+                    <TagGroup size="sm" variant="surface" onRemove={onRemoveTags2}>
+                      <TagGroup.List>
+                        {selectedItemsKeys.map((selectedItemKey) => {
+                          const item = items.find((s) => s.id === selectedItemKey);
+
+                          if (!item) return null;
+
+                          return (
+                            <Tag key={item.id} id={item.id}>
+                              {item.name}
+                            </Tag>
+                          );
+                        })}
+                      </TagGroup.List>
+                    </TagGroup>
+                  );
+                }}
+              </Autocomplete.Value>
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="搜索…" />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/virtualization.tsx b/apps/docs/src/demos/cn/autocomplete/virtualization.tsx
new file mode 100644
index 0000000..d22e4bd
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/virtualization.tsx
@@ -0,0 +1,145 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  ListLayout,
+  SearchField,
+  Virtualizer,
+  useFilter,
+} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  email: string;
+  id: number;
+  name: string;
+}
+
+function generateUsers(n: number): User[] {
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+  const users: User[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const firstName = firstNames[i % firstNames.length]!;
+    const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!;
+    const name = `${firstName} ${lastName}`;
+
+    users.push({
+      email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
+      id: i + 1,
+      name,
+    });
+  }
+
+  return users;
+}
+
+export function Virtualization() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const [searchQuery, setSearchQuery] = useState("");
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const allUsers = useMemo(() => generateUsers(1000), []);
+
+  const filteredUsers = useMemo(() => {
+    if (!searchQuery) return allUsers;
+
+    return allUsers.filter(
+      (user) => contains(user.name, searchQuery) || contains(user.email, searchQuery),
+    );
+  }, [allUsers, contains, searchQuery]);
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[300px]"
+      placeholder="选择用户"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>用户</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter inputValue={searchQuery} onInputChange={setSearchQuery}>
+          <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索用户…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+            <ListBox
+              items={filteredUsers}
+              renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}
+            >
+              {(user) => (
+                <ListBox.Item id={user.id} textValue={user.name}>
+                  <div className="flex flex-col">
+                    <Label>{user.name}</Label>
+                    <Description>{user.email}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              )}
+            </ListBox>
+          </Virtualizer>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/with-description.tsx b/apps/docs/src/demos/cn/autocomplete/with-description.tsx
new file mode 100644
index 0000000..96aaa9f
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/with-description.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function WithDescription() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="请选择一项"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>州</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索州名…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+      <Description>请选择你的居住州</Description>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/with-disabled-options.tsx b/apps/docs/src/demos/cn/autocomplete/with-disabled-options.tsx
new file mode 100644
index 0000000..52e21dc
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/with-disabled-options.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export function WithDisabledOptions() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      disabledKeys={["cat", "kangaroo"]}
+      placeholder="选择一种动物"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>动物</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索动物…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            <ListBox.Item id="dog" textValue="狗">
+              狗
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="猫">
+              猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="bird" textValue="鸟">
+              鸟
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="袋鼠">
+              袋鼠
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="elephant" textValue="象">
+              象
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="tiger" textValue="老虎">
+              老虎
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/autocomplete/with-sections.tsx b/apps/docs/src/demos/cn/autocomplete/with-sections.tsx
new file mode 100644
index 0000000..012b1a0
--- /dev/null
+++ b/apps/docs/src/demos/cn/autocomplete/with-sections.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Header,
+  Label,
+  ListBox,
+  SearchField,
+  Separator,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSections() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="选择一个国家"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>国家</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="搜索国家…" />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}>
+            <ListBox.Section>
+              <Header>北美洲</Header>
+              <ListBox.Item id="usa" textValue="美国">
+                美国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="加拿大">
+                加拿大
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="mexico" textValue="墨西哥">
+                墨西哥
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+            <Separator />
+            <ListBox.Section>
+              <Header>欧洲</Header>
+              <ListBox.Item id="uk" textValue="英国">
+                英国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="france" textValue="法国">
+                法国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="德国">
+                德国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="spain" textValue="西班牙">
+                西班牙
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="italy" textValue="意大利">
+                意大利
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+            <Separator />
+            <ListBox.Section>
+              <Header>亚洲</Header>
+              <ListBox.Item id="japan" textValue="日本">
+                日本
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="china" textValue="中国">
+                中国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="india" textValue="印度">
+                印度
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="south-korea" textValue="韩国">
+                韩国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/basic.tsx b/apps/docs/src/demos/cn/avatar/basic.tsx
new file mode 100644
index 0000000..ecd024b
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/basic.tsx
@@ -0,0 +1,22 @@
+import {Avatar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar>
+        <Avatar.Image alt="约翰·多伊" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar>
+      <Avatar>
+        <Avatar.Image
+          alt="蓝色头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>B</Avatar.Fallback>
+      </Avatar>
+      <Avatar>
+        <Avatar.Fallback>JR</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/colors.tsx b/apps/docs/src/demos/cn/avatar/colors.tsx
new file mode 100644
index 0000000..9ca40a8
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/colors.tsx
@@ -0,0 +1,23 @@
+import {Avatar} from "@heroui/react";
+
+export function Colors() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar color="default">
+        <Avatar.Fallback>DF</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="accent">
+        <Avatar.Fallback>AC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="success">
+        <Avatar.Fallback>SC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="warning">
+        <Avatar.Fallback>WR</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="danger">
+        <Avatar.Fallback>DG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/custom-styles.tsx b/apps/docs/src/demos/cn/avatar/custom-styles.tsx
new file mode 100644
index 0000000..d1e61a3
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/custom-styles.tsx
@@ -0,0 +1,49 @@
+import {Avatar} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <div className="flex items-center gap-4">
+      {/* 使用 Tailwind 自定义尺寸 */}
+      <Avatar className="size-16">
+        <Avatar.Image
+          alt="超大头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>XL</Avatar.Fallback>
+      </Avatar>
+
+      {/* 方形头像 */}
+      <Avatar className="rounded-lg">
+        <Avatar.Image
+          alt="方形头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+        />
+        <Avatar.Fallback className="rounded-lg">SQ</Avatar.Fallback>
+      </Avatar>
+
+      {/* 渐变描边 */}
+      <Avatar className="bg-gradient-to-tr from-pink-500 to-yellow-500 p-0.5">
+        <div className="size-full rounded-full bg-background p-0.5">
+          <Avatar.Image
+            alt="渐变描边头像"
+            className="rounded-full"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+          />
+          <Avatar.Fallback className="border-none">GB</Avatar.Fallback>
+        </div>
+      </Avatar>
+
+      {/* 在线状态指示 */}
+      <div className="relative">
+        <Avatar>
+          <Avatar.Image
+            alt="在线用户"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+          />
+          <Avatar.Fallback>ON</Avatar.Fallback>
+        </Avatar>
+        <span className="absolute right-0 bottom-0 size-3 rounded-full bg-green-500 ring-2 ring-background" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/fallback.tsx b/apps/docs/src/demos/cn/avatar/fallback.tsx
new file mode 100644
index 0000000..7503f2c
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/fallback.tsx
@@ -0,0 +1,33 @@
+import {Person} from "@gravity-ui/icons";
+import {Avatar} from "@heroui/react";
+
+export function Fallback() {
+  return (
+    <div className="flex items-center gap-4">
+      {/* 文字回退 */}
+      <Avatar>
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar>
+
+      {/* 图标回退 */}
+      <Avatar>
+        <Avatar.Fallback>
+          <Person />
+        </Avatar.Fallback>
+      </Avatar>
+
+      {/* 延迟显示回退 */}
+      <Avatar>
+        <Avatar.Image alt="延迟加载头像" src="https://invalid-url-to-show-fallback.com/image.jpg" />
+        <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+      </Avatar>
+
+      {/* 自定义样式回退 */}
+      <Avatar>
+        <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white">
+          GB
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/group.tsx b/apps/docs/src/demos/cn/avatar/group.tsx
new file mode 100644
index 0000000..a7e1b4c
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/group.tsx
@@ -0,0 +1,68 @@
+import {Avatar} from "@heroui/react";
+
+const users = [
+  {
+    id: 1,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "张明",
+  },
+  {
+    id: 2,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "李华",
+  },
+  {
+    id: 3,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "王芳",
+  },
+  {
+    id: 4,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "刘洋",
+  },
+  {
+    id: 5,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "陈静",
+  },
+];
+
+function initialsFromName(name: string) {
+  const parts = name.split(/\s+/).filter(Boolean);
+
+  if (parts.length >= 2) {
+    return parts.map((n) => n[0]).join("");
+  }
+
+  return name.slice(0, 2);
+}
+
+export function Group() {
+  return (
+    <div className="flex flex-col gap-6">
+      {/* 基础头像组 */}
+      <div className="flex -space-x-2">
+        {users.slice(0, 4).map((user) => (
+          <Avatar key={user.id} className="ring-2 ring-background">
+            <Avatar.Image alt={`${user.name} 的头像`} src={user.image} />
+            <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback>
+          </Avatar>
+        ))}
+      </div>
+
+      {/* 带头像数量提示的组合 */}
+      <div className="flex -space-x-2">
+        {users.slice(0, 3).map((user) => (
+          <Avatar key={user.id} className="ring-2 ring-background">
+            <Avatar.Image alt={`${user.name} 的头像`} src={user.image} />
+            <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="text-xs">+{users.length - 3}</Avatar.Fallback>
+        </Avatar>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/index.ts b/apps/docs/src/demos/cn/avatar/index.ts
new file mode 100644
index 0000000..7e10954
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomStyles} from "./custom-styles";
+export {Fallback} from "./fallback";
+export {Group} from "./group";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/avatar/sizes.tsx b/apps/docs/src/demos/cn/avatar/sizes.tsx
new file mode 100644
index 0000000..db4bdc2
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/sizes.tsx
@@ -0,0 +1,29 @@
+import {Avatar} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar size="sm">
+        <Avatar.Image
+          alt="小尺寸头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>SM</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="md">
+        <Avatar.Image
+          alt="中尺寸头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+        />
+        <Avatar.Fallback>MD</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="lg">
+        <Avatar.Image
+          alt="大尺寸头像"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+        />
+        <Avatar.Fallback>LG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/avatar/variants.tsx b/apps/docs/src/demos/cn/avatar/variants.tsx
new file mode 100644
index 0000000..1f541e8
--- /dev/null
+++ b/apps/docs/src/demos/cn/avatar/variants.tsx
@@ -0,0 +1,72 @@
+import {Person} from "@gravity-ui/icons";
+import {Avatar, Separator} from "@heroui/react";
+
+const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+const variants = [
+  {content: "AG", label: "字母", type: "letter"},
+  {content: "AG", label: "柔和字母", type: "letter-soft"},
+  {content: <Person />, label: "图标", type: "icon"},
+  {content: <Person />, label: "柔和图标", type: "icon-soft"},
+  {
+    content: [
+      "https://img.heroui.chat/image/avatar?w=400&h=400&u=3",
+      "https://img.heroui.chat/image/avatar?w=400&h=400&u=4",
+      "https://img.heroui.chat/image/avatar?w=400&h=400&u=5",
+      "https://img.heroui.chat/image/avatar?w=400&h=400&u=8",
+      "https://img.heroui.chat/image/avatar?w=400&h=400&u=16",
+    ],
+    label: "图片",
+    type: "img",
+  },
+] as const;
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      {/* 颜色列标题 */}
+      <div className="flex items-center gap-3">
+        <div className="w-24 shrink-0" />
+        {colors.map((color) => (
+          <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+            <span className="text-xs text-muted">{COLOR_LABELS[color]}</span>
+          </div>
+        ))}
+      </div>
+
+      <Separator />
+
+      {/* 变体行 */}
+      {variants.map((variant) => (
+        <div key={variant.label} className="flex items-center gap-3">
+          <div className="w-24 shrink-0 text-sm text-muted">{variant.label}</div>
+          {colors.map((color, colorIndex) => (
+            <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+              <Avatar color={color} variant={variant.type.includes("soft") ? "soft" : undefined}>
+                {variant.type === "img" ? (
+                  <>
+                    <Avatar.Image
+                      alt={`${COLOR_LABELS[color]} 头像`}
+                      src={Array.isArray(variant.content) ? variant.content[colorIndex] : ""}
+                    />
+                    <Avatar.Fallback>{COLOR_LABELS[color].charAt(0)}</Avatar.Fallback>
+                  </>
+                ) : (
+                  <Avatar.Fallback>{variant.content}</Avatar.Fallback>
+                )}
+              </Avatar>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/basic.tsx b/apps/docs/src/demos/cn/badge/basic.tsx
new file mode 100644
index 0000000..2a040a7
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/basic.tsx
@@ -0,0 +1,40 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const GREEN_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+const ORANGE_AVATAR_URL =
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg";
+const BLUE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg";
+
+export function BadgeBasic() {
+  return (
+    <div className="flex items-center gap-6">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={GREEN_AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          5
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={ORANGE_AVATAR_URL} />
+          <Avatar.Fallback>AB</Avatar.Fallback>
+        </Avatar>
+        <Badge color="accent" size="sm">
+          新
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={BLUE_AVATAR_URL} />
+          <Avatar.Fallback>CD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="success" placement="bottom-right" size="sm" />
+      </Badge.Anchor>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/colors.tsx b/apps/docs/src/demos/cn/badge/colors.tsx
new file mode 100644
index 0000000..a5c11b3
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/colors.tsx
@@ -0,0 +1,21 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeColors() {
+  const colors = ["default", "accent", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {colors.map((color) => (
+        <Badge.Anchor key={color}>
+          <Avatar>
+            <Avatar.Image alt="头像" src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color={color} size="sm" />
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/dot.tsx b/apps/docs/src/demos/cn/badge/dot.tsx
new file mode 100644
index 0000000..ab1ae7b
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/dot.tsx
@@ -0,0 +1,21 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeDot() {
+  const colors = ["accent", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {colors.map((color) => (
+        <Badge.Anchor key={color}>
+          <Avatar>
+            <Avatar.Image alt="头像" src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color={color} placement="bottom-right" size="sm" />
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/index.ts b/apps/docs/src/demos/cn/badge/index.ts
new file mode 100644
index 0000000..5b791ac
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/index.ts
@@ -0,0 +1,7 @@
+export {BadgeBasic as Basic} from "./basic";
+export {BadgeColors as Colors} from "./colors";
+export {BadgeDot as Dot} from "./dot";
+export {BadgePlacements as Placements} from "./placements";
+export {BadgeSizes as Sizes} from "./sizes";
+export {BadgeVariants as Variants} from "./variants";
+export {BadgeWithContent as WithContent} from "./with-content";
diff --git a/apps/docs/src/demos/cn/badge/placements.tsx b/apps/docs/src/demos/cn/badge/placements.tsx
new file mode 100644
index 0000000..b6a86f2
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/placements.tsx
@@ -0,0 +1,31 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
+
+const PLACEMENT_LABELS: Record<(typeof placements)[number], string> = {
+  "bottom-left": "左下",
+  "bottom-right": "右下",
+  "top-left": "左上",
+  "top-right": "右上",
+};
+
+export function BadgePlacements() {
+  return (
+    <div className="flex items-center gap-8">
+      {placements.map((placement) => (
+        <div key={placement} className="flex flex-col items-center gap-2">
+          <Badge.Anchor>
+            <Avatar>
+              <Avatar.Image alt="头像" src={AVATAR_URL} />
+              <Avatar.Fallback>JD</Avatar.Fallback>
+            </Avatar>
+            <Badge color="accent" placement={placement} size="sm" />
+          </Badge.Anchor>
+          <span className="text-xs text-muted">{PLACEMENT_LABELS[placement]}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/sizes.tsx b/apps/docs/src/demos/cn/badge/sizes.tsx
new file mode 100644
index 0000000..5771c1f
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/sizes.tsx
@@ -0,0 +1,23 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeSizes() {
+  const sizes = ["sm", "md", "lg"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {sizes.map((size) => (
+        <Badge.Anchor key={size}>
+          <Avatar size={size}>
+            <Avatar.Image alt="头像" src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color="danger" size={size}>
+            5
+          </Badge>
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/variants.tsx b/apps/docs/src/demos/cn/badge/variants.tsx
new file mode 100644
index 0000000..f22dfea
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/variants.tsx
@@ -0,0 +1,42 @@
+import {Avatar, Badge, Separator} from "@heroui/react";
+import React from "react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+const variants = ["primary", "secondary", "soft"] as const;
+
+const VARIANT_LABELS: Record<(typeof variants)[number], string> = {
+  primary: "主色",
+  secondary: "次色",
+  soft: "柔和",
+};
+
+const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+export function BadgeVariants() {
+  return (
+    <div className="flex flex-col gap-8">
+      {variants.map((variant, index) => (
+        <React.Fragment key={variant}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted">{VARIANT_LABELS[variant]}</h3>
+            <div className="flex items-center gap-6">
+              {colors.map((color) => (
+                <Badge.Anchor key={color}>
+                  <Avatar>
+                    <Avatar.Image alt="头像" src={AVATAR_URL} />
+                    <Avatar.Fallback>JD</Avatar.Fallback>
+                  </Avatar>
+                  <Badge color={color} size="sm" variant={variant}>
+                    5
+                  </Badge>
+                </Badge.Anchor>
+              ))}
+            </div>
+          </div>
+          {index < variants.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/badge/with-content.tsx b/apps/docs/src/demos/cn/badge/with-content.tsx
new file mode 100644
index 0000000..ef50b5f
--- /dev/null
+++ b/apps/docs/src/demos/cn/badge/with-content.tsx
@@ -0,0 +1,50 @@
+import {Bell} from "@gravity-ui/icons";
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeWithContent() {
+  return (
+    <div className="flex items-center gap-6">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          5
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          新
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          99+
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image alt="头像" src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="accent" size="sm">
+          <Bell className="size-2.5" />
+        </Badge>
+      </Badge.Anchor>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/basic.tsx b/apps/docs/src/demos/cn/breadcrumbs/basic.tsx
new file mode 100644
index 0000000..cc4e6e5
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsBasic() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/custom-render-function.tsx b/apps/docs/src/demos/cn/breadcrumbs/custom-render-function.tsx
new file mode 100644
index 0000000..7f9ae98
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/custom-render-function.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Breadcrumbs render={(props) => <ol {...props} data-custom="foo" />}>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        首页
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        产品
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        电子产品
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        笔记本电脑
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/custom-separator.tsx b/apps/docs/src/demos/cn/breadcrumbs/custom-separator.tsx
new file mode 100644
index 0000000..25ba8ad
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/custom-separator.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsCustomSeparator() {
+  return (
+    <Breadcrumbs
+      separator={
+        <svg viewBox="0 0 256 512" xmlns="http://www.w3.org/2000/svg">
+          <path d="M249.3 235.8c10.2 12.6 9.5 31.1-2.2 42.8l-128 128c-9.2 9.2-22.9 11.9-34.9 6.9S64.5 396.9 64.5 384l0-256c0-12.9 7.8-24.6 19.8-29.6s25.7-2.2 34.9 6.9l128 128 2.2 2.4z" />
+        </svg>
+      }
+    >
+      <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/disabled.tsx b/apps/docs/src/demos/cn/breadcrumbs/disabled.tsx
new file mode 100644
index 0000000..8c295fe
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/disabled.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsDisabled() {
+  return (
+    <Breadcrumbs isDisabled>
+      <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item>
+      <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/index.ts b/apps/docs/src/demos/cn/breadcrumbs/index.ts
new file mode 100644
index 0000000..545483b
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/index.ts
@@ -0,0 +1,6 @@
+export {default as BreadcrumbsBasic} from "./basic";
+export {default as BreadcrumbsLevel2} from "./level-2";
+export {default as BreadcrumbsLevel3} from "./level-3";
+export {default as BreadcrumbsCustomSeparator} from "./custom-separator";
+export {default as BreadcrumbsDisabled} from "./disabled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/breadcrumbs/level-2.tsx b/apps/docs/src/demos/cn/breadcrumbs/level-2.tsx
new file mode 100644
index 0000000..62fc4c0
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/level-2.tsx
@@ -0,0 +1,12 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsLevel2() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item>
+      <Breadcrumbs.Item>当前页面</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/breadcrumbs/level-3.tsx b/apps/docs/src/demos/cn/breadcrumbs/level-3.tsx
new file mode 100644
index 0000000..32126ec
--- /dev/null
+++ b/apps/docs/src/demos/cn/breadcrumbs/level-3.tsx
@@ -0,0 +1,13 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsLevel3() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">分类</Breadcrumbs.Item>
+      <Breadcrumbs.Item>当前页面</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/basic.tsx b/apps/docs/src/demos/cn/button-group/basic.tsx
new file mode 100644
index 0000000..c1f8f1f
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/basic.tsx
@@ -0,0 +1,196 @@
+import {
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  CodeFork,
+  Ellipsis,
+  Picture,
+  Pin,
+  QrCode,
+  Star,
+  TextAlignCenter,
+  TextAlignJustify,
+  TextAlignLeft,
+  TextAlignRight,
+  ThumbsDown,
+  ThumbsUp,
+  Video,
+} from "@gravity-ui/icons";
+import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col items-start gap-6">
+      {/* 单个按钮与下拉菜单 */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup>
+          <Button>合并拉取请求</Button>
+          <Dropdown>
+            <Button isIconOnly aria-label="更多选项">
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+            <Dropdown.Popover className="max-w-[290px]" placement="bottom end">
+              <Dropdown.Menu>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="merge"
+                  textValue="创建合并提交"
+                >
+                  <Label>创建合并提交</Label>
+                  <Description>此分支上的所有提交都将加入基础分支</Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="squash-and-merge"
+                  textValue="压缩并合并"
+                >
+                  <Label>压缩并合并</Label>
+                  <Description>此分支上的 14 个提交将合并为一次提交并加入基础分支</Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="rebase-and-merge"
+                  textValue="变基并合并"
+                >
+                  <Label>变基并合并</Label>
+                  <Description>此分支上的 14 个提交将变基后加入基础分支</Description>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown>
+        </ButtonGroup>
+      </div>
+
+      {/* 独立按钮 */}
+      <div className="flex flex-col gap-2">
+        <div className="flex flex-wrap gap-x-2 gap-y-4">
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <CodeFork className="size-3.5" />
+              复刻
+              <Chip color="accent" size="sm" variant="soft">
+                24
+              </Chip>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button isIconOnly>
+              <QrCode />
+            </Button>
+            <Button>
+              <ButtonGroup.Separator />
+              扫码支付
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <ThumbsUp />
+              <span className="text-xs font-semibold">2.4K</span>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ThumbsDown />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Star className="size-3.5" />
+              星标
+            </Button>
+            <Button className="px-2">
+              <ButtonGroup.Separator />
+              <Chip color="accent" size="sm" variant="soft">
+                104
+              </Chip>
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Pin />
+              已置顶
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* 上一页 / 下一页 */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <ChevronLeft />
+            上一页
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            下一页
+            <ChevronRight />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* 内容类型选择 */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <Picture />
+            照片
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Video />
+            视频
+          </Button>
+          <Button isIconOnly aria-label="更多选项">
+            <ButtonGroup.Separator />
+            <Ellipsis />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* 文本对齐 */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>左对齐</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            居中
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            右对齐
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* 仅图标：对齐 */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/disabled.tsx b/apps/docs/src/demos/cn/button-group/disabled.tsx
new file mode 100644
index 0000000..30ed78c
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/disabled.tsx
@@ -0,0 +1,36 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">全部禁用</p>
+        <ButtonGroup isDisabled>
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">组已禁用，但单个按钮可覆盖</p>
+        <ButtonGroup isDisabled>
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button isDisabled={false}>
+            <ButtonGroup.Separator />
+            第三项（可用）
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/full-width.tsx b/apps/docs/src/demos/cn/button-group/full-width.tsx
new file mode 100644
index 0000000..afa3b47
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/full-width.tsx
@@ -0,0 +1,33 @@
+import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <ButtonGroup fullWidth>
+        <Button>第一项</Button>
+        <Button>
+          <ButtonGroup.Separator />
+          第二项
+        </Button>
+        <Button>
+          <ButtonGroup.Separator />
+          第三项
+        </Button>
+      </ButtonGroup>
+      <ButtonGroup fullWidth>
+        <Button isIconOnly>
+          <TextAlignLeft />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <TextAlignCenter />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <TextAlignRight />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/index.ts b/apps/docs/src/demos/cn/button-group/index.ts
new file mode 100644
index 0000000..38d3b03
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/index.ts
@@ -0,0 +1,8 @@
+export {Basic} from "./basic";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Orientation} from "./orientation";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
+export {WithIcons} from "./with-icons";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/cn/button-group/orientation.tsx b/apps/docs/src/demos/cn/button-group/orientation.tsx
new file mode 100644
index 0000000..27b73c1
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/orientation.tsx
@@ -0,0 +1,49 @@
+import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Orientation() {
+  return (
+    <div className="flex items-start gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">横向</span>
+        <ButtonGroup orientation="horizontal" variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">纵向</span>
+        <ButtonGroup orientation="vertical" variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/sizes.tsx b/apps/docs/src/demos/cn/button-group/sizes.tsx
new file mode 100644
index 0000000..e3bd905
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/sizes.tsx
@@ -0,0 +1,50 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">小</p>
+        <ButtonGroup size="sm" variant="secondary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">中（默认）</p>
+        <ButtonGroup size="md" variant="secondary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">大</p>
+        <ButtonGroup size="lg" variant="secondary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/variants.tsx b/apps/docs/src/demos/cn/button-group/variants.tsx
new file mode 100644
index 0000000..044c19e
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/variants.tsx
@@ -0,0 +1,92 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">主要</p>
+        <ButtonGroup variant="primary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">次要</p>
+        <ButtonGroup variant="secondary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">第三</p>
+        <ButtonGroup variant="tertiary">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">线框</p>
+        <ButtonGroup variant="outline">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">幽灵</p>
+        <ButtonGroup variant="ghost">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">危险</p>
+        <ButtonGroup variant="danger">
+          <Button>第一项</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第二项
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            第三项
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/with-icons.tsx b/apps/docs/src/demos/cn/button-group/with-icons.tsx
new file mode 100644
index 0000000..6e5bc7c
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/with-icons.tsx
@@ -0,0 +1,44 @@
+import {Globe, Plus, TrashBin} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">带图标</p>
+        <ButtonGroup variant="secondary">
+          <Button>
+            <Globe />
+            搜索
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Plus />
+            添加
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <TrashBin />
+            删除
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">仅图标按钮</p>
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <Globe />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Plus />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TrashBin />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button-group/without-separator.tsx b/apps/docs/src/demos/cn/button-group/without-separator.tsx
new file mode 100644
index 0000000..b2e4888
--- /dev/null
+++ b/apps/docs/src/demos/cn/button-group/without-separator.tsx
@@ -0,0 +1,11 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function WithoutSeparator() {
+  return (
+    <ButtonGroup>
+      <Button>第一项</Button>
+      <Button>第二项</Button>
+      <Button>第三项</Button>
+    </ButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/basic.tsx b/apps/docs/src/demos/cn/button/basic.tsx
new file mode 100644
index 0000000..61cd9ae
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/basic.tsx
@@ -0,0 +1,7 @@
+"use client";
+
+import {Button} from "@heroui/react";
+
+export function Basic() {
+  return <Button onPress={() => console.log("按钮已按下")}>点我</Button>;
+}
diff --git a/apps/docs/src/demos/cn/button/custom-render-function.tsx b/apps/docs/src/demos/cn/button/custom-render-function.tsx
new file mode 100644
index 0000000..4f18fdd
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/custom-render-function.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {Button} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Button
+      render={(props, {isPressed}) => (
+        <button {...props} data-custom={isPressed ? "pressed" : "bar"} />
+      )}
+    >
+      点按
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/custom-variants.tsx b/apps/docs/src/demos/cn/button/custom-variants.tsx
new file mode 100644
index 0000000..2879895
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/custom-variants.tsx
@@ -0,0 +1,43 @@
+import type {ButtonProps} from "@heroui/react";
+import type {VariantProps} from "tailwind-variants";
+
+import {Button, buttonVariants} from "@heroui/react";
+import {tv} from "tailwind-variants";
+
+const myButtonVariants = tv({
+  base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
+  defaultVariants: {
+    radius: "full",
+    variant: "primary",
+  },
+  extend: buttonVariants,
+  variants: {
+    radius: {
+      full: "rounded-full",
+      lg: "rounded-lg",
+      md: "rounded-md",
+      sm: "rounded-sm",
+    },
+    size: {
+      lg: "h-12 px-8",
+      md: "h-11 px-6",
+      sm: "h-10 px-4",
+      xl: "h-13 px-10",
+    },
+    variant: {
+      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
+    },
+  },
+});
+
+type MyButtonVariants = VariantProps<typeof myButtonVariants>;
+export type MyButtonProps = Omit<ButtonProps, "className"> &
+  MyButtonVariants & {className?: string};
+
+function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
+  return <Button className={myButtonVariants({className, radius, variant})} {...props} />;
+}
+
+export function CustomVariants() {
+  return <CustomButton>自定义按钮</CustomButton>;
+}
diff --git a/apps/docs/src/demos/cn/button/disabled.tsx b/apps/docs/src/demos/cn/button/disabled.tsx
new file mode 100644
index 0000000..95ef38d
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/disabled.tsx
@@ -0,0 +1,24 @@
+import {Button} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button isDisabled>主要</Button>
+      <Button isDisabled variant="secondary">
+        次要
+      </Button>
+      <Button isDisabled variant="tertiary">
+        第三
+      </Button>
+      <Button isDisabled variant="outline">
+        线框
+      </Button>
+      <Button isDisabled variant="ghost">
+        幽灵
+      </Button>
+      <Button isDisabled variant="danger">
+        危险
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/full-width.tsx b/apps/docs/src/demos/cn/button/full-width.tsx
new file mode 100644
index 0000000..a250169
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/full-width.tsx
@@ -0,0 +1,14 @@
+import {Plus} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <Button fullWidth>主要按钮</Button>
+      <Button fullWidth>
+        <Plus />
+        带图标
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/icon-only.tsx b/apps/docs/src/demos/cn/button/icon-only.tsx
new file mode 100644
index 0000000..e564ad9
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/icon-only.tsx
@@ -0,0 +1,18 @@
+import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function IconOnly() {
+  return (
+    <div className="flex gap-3">
+      <Button isIconOnly variant="tertiary">
+        <Ellipsis />
+      </Button>
+      <Button isIconOnly variant="secondary">
+        <Gear />
+      </Button>
+      <Button isIconOnly variant="danger">
+        <TrashBin />
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/index.ts b/apps/docs/src/demos/cn/button/index.ts
new file mode 100644
index 0000000..882d2b4
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/index.ts
@@ -0,0 +1,15 @@
+// Button demos
+export {Basic} from "./basic";
+export {CustomVariants} from "./custom-variants";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {IconOnly} from "./icon-only";
+export {Loading} from "./loading";
+export {LoadingState} from "./loading-state";
+export {OutlineVariant} from "./outline-variant";
+export {Sizes} from "./sizes";
+export {Social} from "./social";
+export {Variants} from "./variants";
+export {WithIcons} from "./with-icons";
+export {RippleEffect} from "./ripple-effect";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/button/loading-state.tsx b/apps/docs/src/demos/cn/button/loading-state.tsx
new file mode 100644
index 0000000..03be487
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/loading-state.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Paperclip} from "@gravity-ui/icons";
+import {Button, Spinner} from "@heroui/react";
+import React, {useState} from "react";
+
+export function LoadingState() {
+  const [isLoading, setLoading] = useState(false);
+
+  const handlePress = () => {
+    setLoading(true);
+    setTimeout(() => setLoading(false), 2000);
+  };
+
+  return (
+    <Button isPending={isLoading} onPress={handlePress}>
+      {({isPending}) => (
+        <>
+          {isPending ? <Spinner color="current" size="sm" /> : <Paperclip />}
+          {isPending ? "上传中…" : "上传文件"}
+        </>
+      )}
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/loading.tsx b/apps/docs/src/demos/cn/button/loading.tsx
new file mode 100644
index 0000000..4c8346b
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/loading.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Button, Spinner} from "@heroui/react";
+import React from "react";
+
+export function Loading() {
+  return (
+    <Button isPending>
+      {({isPending}) => (
+        <>
+          {isPending ? <Spinner color="current" size="sm" /> : null}
+          上传中…
+        </>
+      )}
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/outline-variant.tsx b/apps/docs/src/demos/cn/button/outline-variant.tsx
new file mode 100644
index 0000000..082c973
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/outline-variant.tsx
@@ -0,0 +1,22 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function OutlineVariant() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">按钮</p>
+        <div className="flex flex-wrap gap-3">
+          <Button variant="outline">线框</Button>
+        </div>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">按钮组</p>
+        <ButtonGroup variant="outline">
+          <Button>第一项</Button>
+          <Button>第二项</Button>
+          <Button>第三项</Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/ripple-effect.tsx b/apps/docs/src/demos/cn/button/ripple-effect.tsx
new file mode 100644
index 0000000..82a455b
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/ripple-effect.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {Button} from "@heroui/react";
+import {Ripple} from "m3-ripple";
+
+import "m3-ripple/ripple.css";
+
+export function RippleEffect() {
+  return (
+    <Button variant="secondary">
+      <Ripple />
+      点我
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/sizes.tsx b/apps/docs/src/demos/cn/button/sizes.tsx
new file mode 100644
index 0000000..d54d94a
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/sizes.tsx
@@ -0,0 +1,11 @@
+import {Button} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-3">
+      <Button size="sm">小</Button>
+      <Button size="md">中</Button>
+      <Button size="lg">大</Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/social.tsx b/apps/docs/src/demos/cn/button/social.tsx
new file mode 100644
index 0000000..c7d798b
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/social.tsx
@@ -0,0 +1,21 @@
+import {Button} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function Social() {
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-3">
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="devicon:google" />
+        使用 Google 登录
+      </Button>
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="mdi:github" />
+        使用 GitHub 登录
+      </Button>
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="ion:logo-apple" />
+        使用 Apple 登录
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/variants.tsx b/apps/docs/src/demos/cn/button/variants.tsx
new file mode 100644
index 0000000..bc238de
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/variants.tsx
@@ -0,0 +1,15 @@
+import {Button} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button>主要</Button>
+      <Button variant="secondary">次要</Button>
+      <Button variant="tertiary">第三</Button>
+      <Button variant="outline">线框</Button>
+      <Button variant="ghost">幽灵</Button>
+      <Button variant="danger">危险</Button>
+      <Button variant="danger-soft">柔和危险</Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/button/with-icons.tsx b/apps/docs/src/demos/cn/button/with-icons.tsx
new file mode 100644
index 0000000..0d17db2
--- /dev/null
+++ b/apps/docs/src/demos/cn/button/with-icons.tsx
@@ -0,0 +1,25 @@
+import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button>
+        <Globe />
+        搜索
+      </Button>
+      <Button variant="secondary">
+        <Plus />
+        添加成员
+      </Button>
+      <Button variant="tertiary">
+        <Envelope />
+        邮件
+      </Button>
+      <Button variant="danger">
+        <TrashBin />
+        删除
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/basic.tsx b/apps/docs/src/demos/cn/calendar/basic.tsx
new file mode 100644
index 0000000..d3f9376
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/basic.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Calendar aria-label="活动日期">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/booking-calendar.tsx b/apps/docs/src/demos/cn/calendar/booking-calendar.tsx
new file mode 100644
index 0000000..0179c84
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/booking-calendar.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import type {CalendarDate, DateValue} from "@internationalized/date";
+
+import {Button, Calendar} from "@heroui/react";
+import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+export function BookingCalendar() {
+  const [selectedDate, setSelectedDate] = useState<CalendarDate | null>(null);
+  const {locale} = useLocale();
+
+  const bookedDates = [5, 6, 12, 13, 14, 20];
+
+  const isDateUnavailable = (date: DateValue) => {
+    return isWeekend(date, locale) || bookedDates.includes(date.day);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar
+        aria-label="预订日期"
+        isDateUnavailable={isDateUnavailable}
+        minValue={today(getLocalTimeZone())}
+        value={selectedDate}
+        onChange={setSelectedDate}
+      >
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => (
+              <Calendar.Cell date={date}>
+                {({formattedDate, isUnavailable}) => (
+                  <>
+                    {formattedDate}
+                    {!isUnavailable &&
+                      !isWeekend(date, locale) &&
+                      bookedDates.includes(date.day) && <Calendar.CellIndicator />}
+                  </>
+                )}
+              </Calendar.Cell>
+            )}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <div className="flex flex-col gap-2 text-center">
+        <div className="flex items-center justify-center gap-4 text-xs text-muted">
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-muted" /> 已有预订
+          </span>
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-default" /> 周末/不可用
+          </span>
+        </div>
+        {selectedDate ? (
+          <Button size="sm" variant="primary">
+            预订 {selectedDate.toString()}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/controlled.tsx b/apps/docs/src/demos/cn/calendar/controlled.tsx
new file mode 100644
index 0000000..901741b
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/controlled.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import type {CalendarDate} from "@internationalized/date";
+
+import {Button, ButtonGroup, Calendar, Description} from "@heroui/react";
+import {
+  getLocalTimeZone,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+export function Controlled() {
+  const [value, setValue] = useState<CalendarDate | null>(null);
+  const [focusedDate, setFocusedDate] = useState<CalendarDate>(parseDate("2025-12-25"));
+  const {locale} = useLocale();
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <ButtonGroup fullWidth size="sm" variant="tertiary">
+        <Button
+          onPress={() => {
+            const todayDate = today(getLocalTimeZone());
+
+            setValue(todayDate);
+            setFocusedDate(todayDate);
+          }}
+        >
+          今天
+        </Button>
+        <Button
+          onPress={() => {
+            const nextWeekStart = startOfWeek(today(getLocalTimeZone()), locale);
+
+            setValue(nextWeekStart);
+            setFocusedDate(nextWeekStart);
+          }}
+        >
+          本周
+        </Button>
+        <Button
+          onPress={() => {
+            const nextMonthStart = startOfMonth(today(getLocalTimeZone()));
+
+            setValue(nextMonthStart);
+            setFocusedDate(nextMonthStart);
+          }}
+        >
+          本月
+        </Button>
+      </ButtonGroup>
+
+      <Calendar
+        aria-label="活动日期"
+        focusedValue={focusedDate}
+        value={value}
+        onChange={setValue}
+        onFocusChange={setFocusedDate}
+      >
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <Description className="text-center">
+        已选日期：{value ? value.toString() : "（未选）"}
+      </Description>
+
+      <div className="flex gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const todayDate = today(getLocalTimeZone());
+
+            setValue(todayDate);
+            setFocusedDate(todayDate);
+          }}
+        >
+          设为今天
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const christmasDate = parseDate("2025-12-25");
+
+            setValue(christmasDate);
+            setFocusedDate(christmasDate);
+          }}
+        >
+          设为圣诞节
+        </Button>
+        <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/custom-icons.tsx b/apps/docs/src/demos/cn/calendar/custom-icons.tsx
new file mode 100644
index 0000000..b0c317d
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/custom-icons.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <Calendar aria-label="活动日期">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+        <Calendar.NavButton slot="next">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/custom-styles.tsx b/apps/docs/src/demos/cn/calendar/custom-styles.tsx
new file mode 100644
index 0000000..fce9679
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/custom-styles.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Calendar aria-label="自定义样式日历">
+      <Calendar.Header>
+        <Calendar.NavButton className="text-foreground" slot="previous" />
+        <Calendar.YearPickerTrigger className="w-full justify-center">
+          <Calendar.YearPickerTriggerHeading className="text-foreground" />
+          <Calendar.YearPickerTriggerIndicator className="text-foreground" />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton className="text-foreground" slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({year}) => <Calendar.YearPickerCell year={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/day-view.tsx b/apps/docs/src/demos/cn/calendar/day-view.tsx
new file mode 100644
index 0000000..2d9a4e8
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/day-view.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+const dayOptions = [
+  {id: "1", name: "1 天"},
+  {id: "5", name: "5 天"},
+  {id: "7", name: "7 天"},
+  {id: "8", name: "8 天"},
+  {id: "10", name: "10 天"},
+  {id: "14", name: "14 天"},
+  {id: "21", name: "21 天"},
+] as const;
+
+export function DayView() {
+  const [days, setDays] = useState(5);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(days)}
+        onChange={(value) => value && setDays(Number(value))}
+      >
+        <Label>可见天数</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {dayOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <Calendar aria-label="日视图" visibleDuration={{days}}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/default-value.tsx b/apps/docs/src/demos/cn/calendar/default-value.tsx
new file mode 100644
index 0000000..8e3d94e
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/default-value.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+
+export function DefaultValue() {
+  return (
+    <Calendar aria-label="活动日期" defaultValue={parseDate("2025-02-14")}>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/disabled.tsx b/apps/docs/src/demos/cn/calendar/disabled.tsx
new file mode 100644
index 0000000..649d248
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/disabled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar isDisabled aria-label="活动日期" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">日历已禁用</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/focused-value.tsx b/apps/docs/src/demos/cn/calendar/focused-value.tsx
new file mode 100644
index 0000000..921e094
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/focused-value.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Calendar, Description} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+import {useState} from "react";
+
+export function FocusedValue() {
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="活动日期" focusedValue={focusedDate} onFocusChange={setFocusedDate}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <Description className="text-center">聚焦：{focusedDate.toString()}</Description>
+
+      <div className="flex flex-wrap justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+        >
+          跳转到一月
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+        >
+          跳转到六月
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+        >
+          跳转到圣诞节
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/index.ts b/apps/docs/src/demos/cn/calendar/index.ts
new file mode 100644
index 0000000..d816877
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/index.ts
@@ -0,0 +1,19 @@
+export {Basic} from "./basic";
+export {BookingCalendar} from "./booking-calendar";
+export {Controlled} from "./controlled";
+export {CustomStyles} from "./custom-styles";
+export {CustomIcons} from "./custom-icons";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {FocusedValue} from "./focused-value";
+export {InternationalCalendar} from "./international-calendar";
+export {MinMaxDates} from "./min-max-dates";
+export {MultipleSelection} from "./multiple-selection";
+export {MultipleMonths} from "./multiple-months";
+export {WeeksInMonth} from "./weeks-in-month";
+export {WeekView} from "./week-view";
+export {DayView} from "./day-view";
+export {ReadOnly} from "./read-only";
+export {UnavailableDates} from "./unavailable-dates";
+export {WithIndicators} from "./with-indicators";
+export {YearPicker} from "./year-picker";
diff --git a/apps/docs/src/demos/cn/calendar/international-calendar.tsx b/apps/docs/src/demos/cn/calendar/international-calendar.tsx
new file mode 100644
index 0000000..c070dc9
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/international-calendar.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <Calendar aria-label="活动日期" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.YearPickerTrigger>
+            <Calendar.YearPickerTriggerHeading />
+            <Calendar.YearPickerTriggerIndicator />
+          </Calendar.YearPickerTrigger>
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+        <Calendar.YearPickerGrid>
+          <Calendar.YearPickerGridBody>
+            {({year}) => <Calendar.YearPickerCell year={year} />}
+          </Calendar.YearPickerGridBody>
+        </Calendar.YearPickerGrid>
+      </Calendar>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/min-max-dates.tsx b/apps/docs/src/demos/cn/calendar/min-max-dates.tsx
new file mode 100644
index 0000000..2b50ded
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/min-max-dates.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function MinMaxDates() {
+  const now = today(getLocalTimeZone());
+  const minDate = now;
+  const maxDate = now.add({months: 3});
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="预约日期" maxValue={maxDate} minValue={minDate}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">
+        请在今天与 {maxDate.toString()} 之间选择日期。
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/multiple-months.tsx b/apps/docs/src/demos/cn/calendar/multiple-months.tsx
new file mode 100644
index 0000000..87b31fe
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/multiple-months.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function MultipleMonths() {
+  return (
+    <Calendar
+      aria-label="行程日期"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+        <div className="w-64">
+          <Calendar.Header>
+            <div className="size-6" />
+            <Calendar.Heading className="flex-none" offset={{months: 1}} />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid offset={{months: 1}}>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+      </div>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/multiple-selection.tsx b/apps/docs/src/demos/cn/calendar/multiple-selection.tsx
new file mode 100644
index 0000000..fefa806
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/multiple-selection.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, Description} from "@heroui/react";
+import {useState} from "react";
+
+export function MultipleSelection() {
+  const [value, setValue] = useState<readonly DateValue[]>([]);
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="活动日期" selectionMode="multiple" value={value} onChange={setValue}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">
+        {value?.length ? `已选择 ${value.length} 个日期` : "可选择多个日期"}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/read-only.tsx b/apps/docs/src/demos/cn/calendar/read-only.tsx
new file mode 100644
index 0000000..2f66089
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/read-only.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function ReadOnly() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar isReadOnly aria-label="活动日期" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">日历为只读</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/unavailable-dates.tsx b/apps/docs/src/demos/cn/calendar/unavailable-dates.tsx
new file mode 100644
index 0000000..df52831
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/unavailable-dates.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, Description} from "@heroui/react";
+import {isWeekend} from "@internationalized/date";
+import {useLocale} from "react-aria-components";
+
+export function UnavailableDates() {
+  const {locale} = useLocale();
+  const isDateUnavailable = (date: DateValue) => isWeekend(date, locale);
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="预约日期" isDateUnavailable={isDateUnavailable}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">周末不可选</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/week-view.tsx b/apps/docs/src/demos/cn/calendar/week-view.tsx
new file mode 100644
index 0000000..f39d143
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/week-view.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+const weekOptions = [
+  {id: "1", name: "1 周"},
+  {id: "2", name: "2 周"},
+  {id: "3", name: "3 周"},
+  {id: "4", name: "4 周"},
+  {id: "5", name: "5 周"},
+  {id: "6", name: "6 周"},
+  {id: "8", name: "8 周"},
+] as const;
+
+export function WeekView() {
+  const [weeks, setWeeks] = useState(1);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(weeks)}
+        onChange={(value) => value && setWeeks(Number(value))}
+      >
+        <Label>可见周数</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {weekOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <Calendar aria-label="周视图" visibleDuration={{weeks}}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/weeks-in-month.tsx b/apps/docs/src/demos/cn/calendar/weeks-in-month.tsx
new file mode 100644
index 0000000..3fff019
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/weeks-in-month.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+
+export function WeeksInMonth() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="活动日期" weeksInMonth={6}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">每月固定显示 6 周，切换月份时避免布局跳动</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/with-indicators.tsx b/apps/docs/src/demos/cn/calendar/with-indicators.tsx
new file mode 100644
index 0000000..8fd7af7
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/with-indicators.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {getLocalTimeZone, isToday} from "@internationalized/date";
+
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export function WithIndicators() {
+  return (
+    <Calendar aria-label="活动日期">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => (
+            <Calendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <Calendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </Calendar.Cell>
+          )}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/calendar/year-picker.tsx b/apps/docs/src/demos/cn/calendar/year-picker.tsx
new file mode 100644
index 0000000..aac17bb
--- /dev/null
+++ b/apps/docs/src/demos/cn/calendar/year-picker.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function YearPicker() {
+  return (
+    <Calendar aria-label="活动日期">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({year}) => <Calendar.YearPickerCell year={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/default.tsx b/apps/docs/src/demos/cn/card/default.tsx
new file mode 100644
index 0000000..75e88b5
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/default.tsx
@@ -0,0 +1,27 @@
+import {CircleDollar} from "@gravity-ui/icons";
+import {Card, Link} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Card className="w-[400px]">
+      <CircleDollar aria-label="美元图标" className="text-primary size-6" role="img" />
+      <Card.Header>
+        <Card.Title>成为 Acme 创作者！</Card.Title>
+        <Card.Description>
+          前往 Acme 创作者中心立即注册，开始从粉丝与支持者处获得积分奖励。
+        </Card.Description>
+      </Card.Header>
+      <Card.Footer>
+        <Link
+          aria-label="前往 Acme 创作者中心（在新标签页打开）"
+          href="https://heroui.com"
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          创作者中心
+          <Link.Icon aria-hidden="true" />
+        </Link>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/horizontal.tsx b/apps/docs/src/demos/cn/card/horizontal.tsx
new file mode 100644
index 0000000..1bace85
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/horizontal.tsx
@@ -0,0 +1,32 @@
+import {Button, Card, CloseButton} from "@heroui/react";
+
+export function Horizontal() {
+  return (
+    <Card className="w-full items-stretch md:flex-row">
+      <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+        <img
+          alt="樱桃"
+          className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+        />
+      </div>
+      <div className="flex flex-1 flex-col gap-3">
+        <Card.Header className="gap-1">
+          <Card.Title className="pr-8">成为 ACME 创作者！</Card.Title>
+          <Card.Description>
+            这是一段占位说明文字，用于展示横向卡片布局、配图与右上角关闭按钮的排版效果。
+          </Card.Description>
+          <CloseButton aria-label="关闭横幅" className="absolute top-3 right-3" />
+        </Card.Header>
+        <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div className="flex flex-col">
+            <span className="text-sm font-medium text-foreground">仅剩 10 个名额</span>
+            <span className="text-xs text-muted">报名截止：10 月 10 日</span>
+          </div>
+          <Button className="w-full sm:w-auto">立即申请</Button>
+        </Card.Footer>
+      </div>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/index.ts b/apps/docs/src/demos/cn/card/index.ts
new file mode 100644
index 0000000..0679368
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/index.ts
@@ -0,0 +1,7 @@
+// Card demos
+export {Default} from "./default";
+export {Horizontal} from "./horizontal";
+export {Variants} from "./variants";
+export {WithAvatar} from "./with-avatar";
+export {WithForm} from "./with-form";
+export {WithImages} from "./with-images";
diff --git a/apps/docs/src/demos/cn/card/variants.tsx b/apps/docs/src/demos/cn/card/variants.tsx
new file mode 100644
index 0000000..f1b5177
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/variants.tsx
@@ -0,0 +1,47 @@
+import {Card} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Card className="w-[320px]" variant="transparent">
+        <Card.Header>
+          <Card.Title>透明</Card.Title>
+          <Card.Description>背景透明，视觉层级较低（transparent）</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>适合次要内容或嵌套在其它容器中的卡片</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="default">
+        <Card.Header>
+          <Card.Title>默认</Card.Title>
+          <Card.Description>标准外观（bg-surface）</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>大多数场景的默认卡片变体</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="secondary">
+        <Card.Header>
+          <Card.Title>次要</Card.Title>
+          <Card.Description>中等强调（bg-surface-secondary）</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>用于需要适度吸引注意力的内容</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="tertiary">
+        <Card.Header>
+          <Card.Title>第三</Card.Title>
+          <Card.Description>更高强调（bg-surface-tertiary）</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>适合主要内容或需要突出的展示位</p>
+        </Card.Content>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/with-avatar.tsx b/apps/docs/src/demos/cn/card/with-avatar.tsx
new file mode 100644
index 0000000..39579fe
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/with-avatar.tsx
@@ -0,0 +1,53 @@
+import {Avatar, Card} from "@heroui/react";
+
+export function WithAvatar() {
+  return (
+    <div className="flex flex-wrap gap-4">
+      <Card className="w-[200px] gap-2">
+        <img
+          alt="独立创客社区"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+        />
+        <Card.Header>
+          <Card.Title>Indie Hackers</Card.Title>
+          <Card.Description>148 位成员</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="玛莎的头像" className="size-5">
+            <Avatar.Image
+              alt="玛莎的头像"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+            />
+            <Avatar.Fallback className="text-xs">IH</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">创建者：玛莎</span>
+        </Card.Footer>
+      </Card>
+
+      <Card className="w-[200px] gap-2">
+        <img
+          alt="AI 开发者社区"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+        />
+        <Card.Header>
+          <Card.Title>AI Builders</Card.Title>
+          <Card.Description>362 位成员</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="约翰的头像" className="size-5">
+            <Avatar.Image
+              alt="约翰的头像"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback className="text-xs">B</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">创建者：约翰</span>
+        </Card.Footer>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/with-form.tsx b/apps/docs/src/demos/cn/card/with-form.tsx
new file mode 100644
index 0000000..75bd3b2
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/with-form.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {Button, Card, Form, Input, Label, Link, TextField} from "@heroui/react";
+
+export function WithForm() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Header>
+        <Card.Title>登录</Card.Title>
+        <Card.Description>输入账号信息以访问您的账户</Card.Description>
+      </Card.Header>
+      <Form onSubmit={onSubmit}>
+        <Card.Content>
+          <div className="flex flex-col gap-4">
+            <TextField name="email" type="email">
+              <Label>邮箱</Label>
+              <Input placeholder="email@example.com" variant="secondary" />
+            </TextField>
+            <TextField name="password" type="password">
+              <Label>密码</Label>
+              <Input placeholder="••••••••" variant="secondary" />
+            </TextField>
+          </div>
+        </Card.Content>
+        <Card.Footer className="mt-4 flex flex-col gap-2">
+          <Button className="w-full" type="submit">
+            登录
+          </Button>
+          <Link className="text-center text-sm" href="#">
+            忘记密码？
+          </Link>
+        </Card.Footer>
+      </Form>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/cn/card/with-images.tsx b/apps/docs/src/demos/cn/card/with-images.tsx
new file mode 100644
index 0000000..56e8fc5
--- /dev/null
+++ b/apps/docs/src/demos/cn/card/with-images.tsx
@@ -0,0 +1,225 @@
+import {CircleDollar} from "@gravity-ui/icons";
+import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react";
+
+export function WithImages() {
+  return (
+    <div className="flex w-full items-center justify-center">
+      <div className="grid w-full max-w-2xl grid-cols-12 gap-4 p-4">
+        {/* 第 1 行：大图商品卡 */}
+        <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row">
+          <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+            <img
+              alt="樱桃"
+              className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+              loading="lazy"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+            />
+          </div>
+          <div className="flex flex-1 flex-col gap-3">
+            <Card.Header className="gap-1">
+              <Card.Title className="pr-8">成为 ACME 创作者！</Card.Title>
+              <Card.Description>
+                这是一段占位说明文字，用于展示横向卡片布局、配图与右上角关闭按钮的排版效果。
+              </Card.Description>
+              <CloseButton aria-label="关闭横幅" className="absolute top-3 right-3" />
+            </Card.Header>
+            <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
+              <div className="flex flex-col">
+                <span className="text-sm font-medium text-foreground">仅剩 10 个名额</span>
+                <span className="text-xs text-muted">报名截止：10 月 10 日</span>
+              </div>
+              <Button className="w-full sm:w-auto">立即申请</Button>
+            </Card.Footer>
+          </div>
+        </Card>
+
+        {/* 第 2 行 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* 左栏 */}
+          <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6">
+            {/* 上方卡片 */}
+            <Card className="col-span-12">
+              <div className="absolute top-3 right-3 z-10">
+                <CloseButton aria-label="关闭通知" />
+              </div>
+              <Card.Header className="gap-3">
+                <CircleDollar
+                  aria-label="美元图标"
+                  className="text-primary size-8 shrink-0"
+                  role="img"
+                />
+                <div className="flex flex-col gap-1">
+                  <span className="text-xs font-medium text-muted uppercase">支付</span>
+                  <Card.Title className="pr-8 text-sm sm:text-base">
+                    现已支持加密货币提现
+                  </Card.Title>
+                  <Card.Description className="text-xs sm:text-sm">
+                    在设置中添加钱包即可提现
+                  </Card.Description>
+                </div>
+              </Card.Header>
+              <Card.Footer>
+                <Link aria-label="前往设置" href="#" rel="noopener noreferrer">
+                  前往设置
+                  <Link.Icon aria-hidden="true" />
+                </Link>
+              </Card.Footer>
+            </Card>
+            {/* 下方小卡 */}
+            <div className="col-span-12 grid grid-cols-12 gap-4">
+              {/* 左卡 */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="演示图片 1"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">Indie Hackers</p>
+                  <p className="text-xs text-muted">148 位成员</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="约翰"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">创建者：约翰</p>
+                </Card.Footer>
+              </Card>
+              {/* 右卡 */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="演示图片 2"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+                    />
+                    <Avatar.Fallback>AB</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">AI Builders</p>
+                  <p className="text-xs text-muted">362 位成员</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="玛莎"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+                    />
+                    <Avatar.Fallback>M</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">创建者：玛莎</p>
+                </Card.Footer>
+              </Card>
+            </div>
+          </div>
+          {/* 右栏 */}
+          <Card className="col-span-12 min-h-[200px] overflow-hidden rounded-3xl lg:col-span-6">
+            {/* 背景图 */}
+            <img
+              alt="NEO 家用机器人"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg"
+            />
+
+            {/* 标题区 */}
+            <Card.Header className="z-10 text-white">
+              <Card.Title className="text-xs font-semibold tracking-wide text-black/70">
+                NEO
+              </Card.Title>
+              <Card.Description className="text-sm leading-5 font-medium text-black/50">
+                家用机器人
+              </Card.Description>
+            </Card.Header>
+
+            {/* 底部 */}
+            <Card.Footer className="z-10 mt-auto flex items-center justify-between">
+              <div>
+                <div className="text-sm font-medium text-black">即将推出</div>
+                <div className="text-xs text-black/60">接收上架通知</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                通知我
+              </Button>
+            </Card.Footer>
+          </Card>
+        </div>
+
+        {/* 第 3 行 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* 左：大图卡 */}
+          <Card className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]">
+            <img
+              alt="NEO 家用机器人"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo1.jpeg"
+            />
+
+            <Card.Footer className="z-10 mt-auto flex items-end justify-between">
+              <div>
+                <div className="text-base font-medium text-black sm:text-lg">NEO</div>
+                <div className="text-xs font-medium text-black/50 sm:text-sm">$499/月</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                立即购买
+              </Button>
+            </Card.Footer>
+          </Card>
+
+          {/* 右：堆叠小卡 */}
+          <div className="col-span-12 flex flex-col gap-2 md:col-span-4 md:justify-between md:gap-0 md:py-2">
+            {/* 1 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="未来感机器人"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">连接未来</Card.Title>
+                <Card.Description className="text-xs">今天 18:30</Card.Description>
+              </div>
+            </Card>
+            {/* 2 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="牛油果"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">牛油果黑客松</Card.Title>
+                <Card.Description className="text-xs">周三 16:30</Card.Description>
+              </div>
+            </Card>
+            {/* 3 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Sound Electro 活动"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Sound Electro｜超越艺术</Card.Title>
+                <Card.Description className="text-xs">周五 20:00</Card.Description>
+              </div>
+            </Card>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/basic.tsx b/apps/docs/src/demos/cn/checkbox-group/basic.tsx
new file mode 100644
index 0000000..24da18c
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/basic.tsx
@@ -0,0 +1,37 @@
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <CheckboxGroup name="interests">
+      <Label>选择你的兴趣</Label>
+      <Description>可多选</Description>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          编程
+        </Checkbox.Content>
+        <Description>热爱构建软件</Description>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          设计
+        </Checkbox.Content>
+        <Description>喜欢打造精美界面</Description>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          写作
+        </Checkbox.Content>
+        <Description>热衷于内容创作</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/controlled.tsx b/apps/docs/src/demos/cn/checkbox-group/controlled.tsx
new file mode 100644
index 0000000..4954591
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/controlled.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState(["coding", "design"]);
+
+  return (
+    <CheckboxGroup className="min-w-[320px]" name="skills" value={selected} onChange={setSelected}>
+      <Label>你的技能</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          编程
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          设计
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          写作
+        </Checkbox.Content>
+      </Checkbox>
+      <Label className="my-4 text-sm text-muted">已选：{selected.join(", ") || "无"}</Label>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/custom-render-function.tsx b/apps/docs/src/demos/cn/checkbox-group/custom-render-function.tsx
new file mode 100644
index 0000000..20f88a1
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/custom-render-function.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <CheckboxGroup name="interests" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>选择你的兴趣</Label>
+      <Description>可多选</Description>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          编程
+        </Checkbox.Content>
+        <Description>热爱构建软件</Description>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          设计
+        </Checkbox.Content>
+        <Description>喜欢打造精美界面</Description>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          写作
+        </Checkbox.Content>
+        <Description>热衷于内容创作</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/disabled.tsx b/apps/docs/src/demos/cn/checkbox-group/disabled.tsx
new file mode 100644
index 0000000..70533f3
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/disabled.tsx
@@ -0,0 +1,28 @@
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <CheckboxGroup isDisabled name="disabled-features">
+      <Label>功能</Label>
+      <Description>功能选择暂时不可用</Description>
+      <Checkbox value="feature1">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          功能一
+        </Checkbox.Content>
+        <Description>该功能即将推出</Description>
+      </Checkbox>
+      <Checkbox value="feature2">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          功能二
+        </Checkbox.Content>
+        <Description>该功能即将推出</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/features-and-addons.tsx b/apps/docs/src/demos/cn/checkbox-group/features-and-addons.tsx
new file mode 100644
index 0000000..82c54e2
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/features-and-addons.tsx
@@ -0,0 +1,58 @@
+import {Bell, Comment, Envelope} from "@gravity-ui/icons";
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+import clsx from "clsx";
+
+export function FeaturesAndAddOns() {
+  const addOns = [
+    {
+      description: "通过邮件接收更新",
+      icon: Envelope,
+      title: "邮件通知",
+      value: "email",
+    },
+    {
+      description: "即时短信通知",
+      icon: Comment,
+      title: "短信提醒",
+      value: "sms",
+    },
+    {
+      description: "浏览器与移动端推送提醒",
+      icon: Bell,
+      title: "推送通知",
+      value: "push",
+    },
+  ];
+
+  return (
+    <div className="flex w-full flex-col items-center gap-10 px-4 py-8">
+      <section className="flex w-full min-w-[320px] flex-col gap-4">
+        <CheckboxGroup name="notification-preferences">
+          <Label>通知偏好</Label>
+          <Description>选择接收更新的方式</Description>
+          <div className="flex flex-col gap-2">
+            {addOns.map((addon) => (
+              <Checkbox key={addon.value} value={addon.value} variant="secondary">
+                <Checkbox.Content
+                  className={clsx(
+                    "group relative flex w-full flex-row items-start justify-start gap-4 rounded-3xl bg-surface px-5 py-4 transition-all",
+                    "data-[selected=true]:bg-accent/10",
+                  )}
+                >
+                  <Checkbox.Control className="absolute top-3 right-4 size-5 rounded-full before:rounded-full">
+                    <Checkbox.Indicator />
+                  </Checkbox.Control>
+                  <addon.icon className="size-5 text-accent-soft-foreground" />
+                  <div className="flex flex-col gap-1">
+                    <span>{addon.title}</span>
+                    <Description>{addon.description}</Description>
+                  </div>
+                </Checkbox.Content>
+              </Checkbox>
+            ))}
+          </div>
+        </CheckboxGroup>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/indeterminate.tsx b/apps/docs/src/demos/cn/checkbox-group/indeterminate.tsx
new file mode 100644
index 0000000..0afaa79
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/indeterminate.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import {Checkbox, CheckboxGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function Indeterminate() {
+  const [selected, setSelected] = useState(["coding"]);
+  const allOptions = ["coding", "design", "writing"];
+
+  return (
+    <div>
+      <Checkbox
+        isIndeterminate={selected.length > 0 && selected.length < allOptions.length}
+        isSelected={selected.length === allOptions.length}
+        name="select-all"
+        onChange={(isSelected: boolean) => {
+          setSelected(isSelected ? allOptions : []);
+        }}
+      >
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          全选
+        </Checkbox.Content>
+      </Checkbox>
+      <div className="ml-6 flex flex-col gap-2">
+        <CheckboxGroup value={selected} onChange={setSelected}>
+          <Checkbox value="coding">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              编程
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="design">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              设计
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="writing">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              写作
+            </Checkbox.Content>
+          </Checkbox>
+        </CheckboxGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/index.ts b/apps/docs/src/demos/cn/checkbox-group/index.ts
new file mode 100644
index 0000000..63102b1
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FeaturesAndAddOns} from "./features-and-addons";
+export {Indeterminate} from "./indeterminate";
+export {OnSurface} from "./on-surface";
+export {Validation} from "./validation";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/checkbox-group/on-surface.tsx b/apps/docs/src/demos/cn/checkbox-group/on-surface.tsx
new file mode 100644
index 0000000..6b82f72
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/on-surface.tsx
@@ -0,0 +1,39 @@
+import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <CheckboxGroup name="interests" variant="secondary">
+        <Label>选择你的兴趣</Label>
+        <Description>可多选</Description>
+        <Checkbox value="coding">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            编程
+          </Checkbox.Content>
+          <Description>热爱构建软件</Description>
+        </Checkbox>
+        <Checkbox value="design">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            设计
+          </Checkbox.Content>
+          <Description>喜欢打造精美界面</Description>
+        </Checkbox>
+        <Checkbox value="writing">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            写作
+          </Checkbox.Content>
+          <Description>热衷于内容创作</Description>
+        </Checkbox>
+      </CheckboxGroup>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/validation.tsx b/apps/docs/src/demos/cn/checkbox-group/validation.tsx
new file mode 100644
index 0000000..8c3466c
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/validation.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <Form
+      className="flex flex-col gap-4 px-4"
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        const formData = new FormData(e.currentTarget);
+        const values = formData.getAll("preferences");
+
+        alert(`已选偏好：${values.join(", ")}`);
+      }}
+    >
+      <CheckboxGroup isRequired name="preferences">
+        <Label>偏好设置</Label>
+        <Checkbox value="email">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            邮件通知
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="sms">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            短信通知
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="push">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            推送通知
+          </Checkbox.Content>
+        </Checkbox>
+        <FieldError>请至少选择一种通知方式。</FieldError>
+      </CheckboxGroup>
+      <Button type="submit">提交</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox-group/with-custom-indicator.tsx b/apps/docs/src/demos/cn/checkbox-group/with-custom-indicator.tsx
new file mode 100644
index 0000000..42e5404
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox-group/with-custom-indicator.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function WithCustomIndicator() {
+  return (
+    <CheckboxGroup name="features">
+      <Label>功能</Label>
+      <Description>选择你需要的功能</Description>
+      <Checkbox value="notifications">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          邮件通知
+        </Checkbox.Content>
+        <Description>通过邮件接收更新</Description>
+      </Checkbox>
+      <Checkbox value="newsletter">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          邮件通讯
+        </Checkbox.Content>
+        <Description>每周接收邮件简报</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/basic.tsx b/apps/docs/src/demos/cn/checkbox/basic.tsx
new file mode 100644
index 0000000..eeda3ef
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/basic.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Checkbox name="basic-terms">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        接受条款与条件
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/controlled.tsx b/apps/docs/src/demos/cn/checkbox/controlled.tsx
new file mode 100644
index 0000000..5fcc26d
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/controlled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Checkbox} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = useState(true);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <Checkbox id="email-notifications" isSelected={isSelected} onChange={setIsSelected}>
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          邮件通知
+        </Checkbox.Content>
+      </Checkbox>
+      <p className="text-sm text-muted">
+        状态：<span className="font-medium">{isSelected ? "已勾选" : "未勾选"}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/custom-indicator.tsx b/apps/docs/src/demos/cn/checkbox/custom-indicator.tsx
new file mode 100644
index 0000000..576cb09
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/custom-indicator.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import {Checkbox} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <div className="flex gap-4">
+      <Checkbox defaultSelected name="heart">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg fill="currentColor" viewBox="0 0 24 24">
+                    <path
+                      d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z"
+                      fill="currentColor"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          心形
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox defaultSelected name="plus">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg fill="none" viewBox="0 0 24 24">
+                    <path
+                      d="M6 12H18"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                    <path
+                      d="M12 18V6"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          加号
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox isIndeterminate name="indeterminate">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isIndeterminate}) =>
+                isIndeterminate ? (
+                  <svg stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24">
+                    <line x1="21" x2="3" y1="12" y2="12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          部分选中
+        </Checkbox.Content>
+      </Checkbox>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/custom-render-function.tsx b/apps/docs/src/demos/cn/checkbox/custom-render-function.tsx
new file mode 100644
index 0000000..58eb471
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Checkbox, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-3">
+      <Checkbox id="basic-terms" render={(props) => <div {...props} data-custom="bar" />}>
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+      <Label htmlFor="basic-terms">接受条款与条件</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/custom-styles.tsx b/apps/docs/src/demos/cn/checkbox/custom-styles.tsx
new file mode 100644
index 0000000..ef58aca
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/custom-styles.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Checkbox id="custom">
+      <Checkbox.Content>
+        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500">
+          <Checkbox.Indicator className="text-white" />
+        </Checkbox.Control>
+        自定义样式复选框
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/default-selected.tsx b/apps/docs/src/demos/cn/checkbox/default-selected.tsx
new file mode 100644
index 0000000..2cb7d74
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/default-selected.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function DefaultSelected() {
+  return (
+    <Checkbox defaultSelected id="default-notifications">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        启用邮件通知
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/disabled.tsx b/apps/docs/src/demos/cn/checkbox/disabled.tsx
new file mode 100644
index 0000000..6e6e2a3
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/disabled.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Checkbox isDisabled id="feature">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        高级功能
+      </Checkbox.Content>
+      <Description>该功能即将推出</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/external-label.tsx b/apps/docs/src/demos/cn/checkbox/external-label.tsx
new file mode 100644
index 0000000..6b51b44
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/external-label.tsx
@@ -0,0 +1,16 @@
+import {Checkbox, Label} from "@heroui/react";
+
+export function ExternalLabel() {
+  return (
+    <div className="flex items-center gap-3">
+      <Checkbox id="label-marketing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+      <Label htmlFor="label-marketing">给我发送营销邮件</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/form.tsx b/apps/docs/src/demos/cn/checkbox/form.tsx
new file mode 100644
index 0000000..7511ad6
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/form.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Button, Checkbox} from "@heroui/react";
+import React from "react";
+
+export function Form() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+
+    alert(
+      `表单提交数据：\n${Array.from(formData.entries())
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n")}`,
+    );
+  };
+
+  return (
+    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="notifications" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            启用通知
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox defaultSelected name="newsletter" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            订阅新闻通讯
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox name="marketing" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            接收营销更新
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <Button className="mt-4" size="sm" type="submit" variant="primary">
+        提交
+      </Button>
+    </form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/full-rounded.tsx b/apps/docs/src/demos/cn/checkbox/full-rounded.tsx
new file mode 100644
index 0000000..315aa14
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/full-rounded.tsx
@@ -0,0 +1,55 @@
+import {Checkbox, Label} from "@heroui/react";
+
+export function FullRounded() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-3">
+        <Label className="text-muted">圆角复选框</Label>
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-2"
+          name="small-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-3 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            小尺寸
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="default-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-4 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            默认尺寸
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="large-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-5 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            大尺寸
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-4"
+          name="xl-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-6 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            特大尺寸
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/indeterminate.tsx b/apps/docs/src/demos/cn/checkbox/indeterminate.tsx
new file mode 100644
index 0000000..9da7cf9
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/indeterminate.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Checkbox, Description} from "@heroui/react";
+import {useState} from "react";
+
+export function Indeterminate() {
+  const [isIndeterminate, setIsIndeterminate] = useState(true);
+  const [isSelected, setIsSelected] = useState(false);
+
+  return (
+    <Checkbox
+      id="select-all"
+      isIndeterminate={isIndeterminate}
+      isSelected={isSelected}
+      onChange={(selected: boolean) => {
+        setIsSelected(selected);
+        setIsIndeterminate(false);
+      }}
+    >
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        全选
+      </Checkbox.Content>
+      <Description>展示部分选中状态（短横线图标）</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/index.ts b/apps/docs/src/demos/cn/checkbox/index.ts
new file mode 100644
index 0000000..9f23fcc
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/index.ts
@@ -0,0 +1,15 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomStyles} from "./custom-styles";
+export {DefaultSelected} from "./default-selected";
+export {Disabled} from "./disabled";
+export {Form} from "./form";
+export {FullRounded} from "./full-rounded";
+export {Indeterminate} from "./indeterminate";
+export {Invalid} from "./invalid";
+export {RenderProps} from "./render-props";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {ExternalLabel} from "./external-label";
diff --git a/apps/docs/src/demos/cn/checkbox/invalid.tsx b/apps/docs/src/demos/cn/checkbox/invalid.tsx
new file mode 100644
index 0000000..362bce1
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/invalid.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, FieldError} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <Checkbox isInvalid isRequired name="agreement">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        我同意条款
+      </Checkbox.Content>
+      <FieldError>您必须接受条款才能继续</FieldError>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/render-props.tsx b/apps/docs/src/demos/cn/checkbox/render-props.tsx
new file mode 100644
index 0000000..7afe3b7
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/render-props.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Checkbox, Description} from "@heroui/react";
+
+export function RenderProps() {
+  return (
+    <Checkbox id="render-props-terms">
+      {({isSelected}) => (
+        <>
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            {isSelected ? "已同意条款" : "接受条款"}
+          </Checkbox.Content>
+          <Description>{isSelected ? "感谢您的确认" : "请先阅读并接受条款"}</Description>
+        </>
+      )}
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/variants.tsx b/apps/docs/src/demos/cn/checkbox/variants.tsx
new file mode 100644
index 0000000..98774a1
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/variants.tsx
@@ -0,0 +1,32 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">主要变体</p>
+        <Checkbox id="primary" name="primary" variant="primary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            主要复选框
+          </Checkbox.Content>
+          <Description>默认背景的标准样式</Description>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">次要变体</p>
+        <Checkbox id="secondary" name="secondary" variant="secondary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            次要复选框
+          </Checkbox.Content>
+          <Description>用于表面容器的低强调样式</Description>
+        </Checkbox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/checkbox/with-description.tsx b/apps/docs/src/demos/cn/checkbox/with-description.tsx
new file mode 100644
index 0000000..184acd7
--- /dev/null
+++ b/apps/docs/src/demos/cn/checkbox/with-description.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <Checkbox name="description-notifications">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        邮件通知
+      </Checkbox.Content>
+      <Description>当有人在评论中提及您时收到通知</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/chip/basic.tsx b/apps/docs/src/demos/cn/chip/basic.tsx
new file mode 100644
index 0000000..b08aa27
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/basic.tsx
@@ -0,0 +1,13 @@
+import {Chip} from "@heroui/react";
+
+export function ChipBasic() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Chip>默认</Chip>
+      <Chip color="accent">强调</Chip>
+      <Chip color="success">成功</Chip>
+      <Chip color="warning">警告</Chip>
+      <Chip color="danger">危险</Chip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/chip/index.ts b/apps/docs/src/demos/cn/chip/index.ts
new file mode 100644
index 0000000..d12f4c0
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/index.ts
@@ -0,0 +1,5 @@
+export {ChipBasic as Basic} from "./basic";
+export {ChipVariants as Variants} from "./variants";
+export {ChipWithIcon as WithIcon} from "./with-icon";
+export {ChipStatuses as Statuses} from "./statuses";
+export {ChipVibrantPalette as VibrantPalette} from "./vibrant-palette";
diff --git a/apps/docs/src/demos/cn/chip/statuses.tsx b/apps/docs/src/demos/cn/chip/statuses.tsx
new file mode 100644
index 0000000..e0f322e
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/statuses.tsx
@@ -0,0 +1,46 @@
+import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons";
+import {Chip} from "@heroui/react";
+
+export function ChipStatuses() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <Chip variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>默认</Chip.Label>
+        </Chip>
+        <Chip color="success" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>活跃</Chip.Label>
+        </Chip>
+        <Chip color="warning" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>待处理</Chip.Label>
+        </Chip>
+        <Chip color="danger" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>未激活</Chip.Label>
+        </Chip>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-3">
+        <Chip>
+          <CircleInfo width={12} />
+          <Chip.Label>新功能</Chip.Label>
+        </Chip>
+        <Chip color="success">
+          <Check width={12} />
+          <Chip.Label>可用</Chip.Label>
+        </Chip>
+        <Chip color="warning">
+          <TriangleExclamation width={12} />
+          <Chip.Label>测试版</Chip.Label>
+        </Chip>
+        <Chip color="danger">
+          <Ban width={12} />
+          <Chip.Label>已弃用</Chip.Label>
+        </Chip>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/chip/variants.tsx b/apps/docs/src/demos/cn/chip/variants.tsx
new file mode 100644
index 0000000..124fccc
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/variants.tsx
@@ -0,0 +1,77 @@
+import {CircleDashed} from "@gravity-ui/icons";
+import {Chip, Separator} from "@heroui/react";
+import React from "react";
+
+const sizes = ["lg", "md", "sm"] as const;
+
+const SIZE_LABELS: Record<(typeof sizes)[number], string> = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+};
+
+const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+
+const VARIANT_LABELS: Record<(typeof variants)[number], string> = {
+  primary: "主要",
+  secondary: "次要",
+  soft: "柔和",
+  tertiary: "第三",
+};
+
+const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+export function ChipVariants() {
+  return (
+    <div className="flex flex-col gap-8 overflow-x-auto">
+      {sizes.map((size, index) => (
+        <React.Fragment key={size}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted">{SIZE_LABELS[size]}</h3>
+            <div className="flex items-center gap-3">
+              <div className="w-24 shrink-0" />
+              {colors.map((color) => (
+                <div
+                  key={color}
+                  className="flex shrink-0 items-center justify-center"
+                  style={{width: "130px"}}
+                >
+                  <span className="text-xs text-muted">{COLOR_LABELS[color]}</span>
+                </div>
+              ))}
+            </div>
+            <div className="flex flex-col gap-3">
+              {variants.map((variant) => (
+                <div key={variant} className="flex items-center gap-3">
+                  <div className="w-24 shrink-0 text-sm text-muted">{VARIANT_LABELS[variant]}</div>
+                  {colors.map((color) => (
+                    <div
+                      key={color}
+                      className="flex shrink-0 items-center justify-center"
+                      style={{width: "130px"}}
+                    >
+                      <Chip color={color} size={size} variant={variant}>
+                        <CircleDashed />
+                        <Chip.Label>标签</Chip.Label>
+                        <CircleDashed />
+                      </Chip>
+                    </div>
+                  ))}
+                </div>
+              ))}
+            </div>
+          </div>
+          {index < sizes.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/chip/vibrant-palette.tsx b/apps/docs/src/demos/cn/chip/vibrant-palette.tsx
new file mode 100644
index 0000000..30d96d8
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/vibrant-palette.tsx
@@ -0,0 +1,67 @@
+import {Chip, Separator} from "@heroui/react";
+
+const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+const VARIANT_LABELS: Record<(typeof variants)[number], string> = {
+  primary: "主要",
+  secondary: "次要",
+  soft: "柔和",
+  tertiary: "第三",
+};
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+function ChipMatrix({isVibrant, title}: {isVibrant?: boolean; title: string}) {
+  return (
+    <div className="flex flex-col gap-4" data-vibrant-palette={isVibrant ? "true" : undefined}>
+      <h3 className="text-sm font-semibold text-muted">{title}</h3>
+      <div className="flex items-center gap-3">
+        <div className="w-24 shrink-0" />
+        {colors.map((color) => (
+          <div
+            key={color}
+            className="flex shrink-0 items-center justify-center"
+            style={{width: "130px"}}
+          >
+            <span className="text-xs text-muted">{COLOR_LABELS[color]}</span>
+          </div>
+        ))}
+      </div>
+      <div className="flex flex-col gap-3">
+        {variants.map((variant) => (
+          <div key={variant} className="flex items-center gap-3">
+            <div className="w-24 shrink-0 text-sm text-muted">{VARIANT_LABELS[variant]}</div>
+            {colors.map((color) => (
+              <div
+                key={color}
+                className="flex shrink-0 items-center justify-center"
+                style={{width: "130px"}}
+              >
+                <Chip color={color} size="md" variant={variant}>
+                  <Chip.Label>{COLOR_LABELS[color]}</Chip.Label>
+                </Chip>
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function ChipVibrantPalette() {
+  return (
+    <div className="flex w-full flex-col gap-8 overflow-x-auto">
+      <ChipMatrix title="默认调色板" />
+      <Separator />
+      <ChipMatrix isVibrant title="Vibrant 调色板" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/chip/with-icon.tsx b/apps/docs/src/demos/cn/chip/with-icon.tsx
new file mode 100644
index 0000000..2a07827
--- /dev/null
+++ b/apps/docs/src/demos/cn/chip/with-icon.tsx
@@ -0,0 +1,29 @@
+import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons";
+import {Chip} from "@heroui/react";
+
+export function ChipWithIcon() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Chip>
+        <CircleFill width={6} />
+        <Chip.Label>信息</Chip.Label>
+      </Chip>
+      <Chip color="success">
+        <CircleCheckFill width={12} />
+        <Chip.Label>已完成</Chip.Label>
+      </Chip>
+      <Chip color="warning">
+        <Clock width={12} />
+        <Chip.Label>待处理</Chip.Label>
+      </Chip>
+      <Chip color="danger">
+        <Xmark width={12} />
+        <Chip.Label>失败</Chip.Label>
+      </Chip>
+      <Chip color="accent">
+        <Chip.Label>标签</Chip.Label>
+        <ChevronDown width={12} />
+      </Chip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/close-button/default.tsx b/apps/docs/src/demos/cn/close-button/default.tsx
new file mode 100644
index 0000000..ce6d6e5
--- /dev/null
+++ b/apps/docs/src/demos/cn/close-button/default.tsx
@@ -0,0 +1,5 @@
+import {CloseButton} from "@heroui/react";
+
+export function Default() {
+  return <CloseButton />;
+}
diff --git a/apps/docs/src/demos/cn/close-button/index.ts b/apps/docs/src/demos/cn/close-button/index.ts
new file mode 100644
index 0000000..72e71f2
--- /dev/null
+++ b/apps/docs/src/demos/cn/close-button/index.ts
@@ -0,0 +1,3 @@
+export {Default} from "./default";
+export {WithCustomIcon} from "./with-custom-icon";
+export {Interactive} from "./interactive";
diff --git a/apps/docs/src/demos/cn/close-button/interactive.tsx b/apps/docs/src/demos/cn/close-button/interactive.tsx
new file mode 100644
index 0000000..9ab1dd8
--- /dev/null
+++ b/apps/docs/src/demos/cn/close-button/interactive.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {CloseButton} from "@heroui/react";
+import {useState} from "react";
+
+export function Interactive() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4">
+      <CloseButton aria-label={`关闭（已点击 ${count} 次）`} onPress={() => setCount(count + 1)} />
+      <span className="text-sm text-muted">已点击：{count} 次</span>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/close-button/variants.tsx b/apps/docs/src/demos/cn/close-button/variants.tsx
new file mode 100644
index 0000000..9d7956e
--- /dev/null
+++ b/apps/docs/src/demos/cn/close-button/variants.tsx
@@ -0,0 +1,12 @@
+import {CloseButton} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton />
+        <span className="text-xs text-muted">默认</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/close-button/with-custom-icon.tsx b/apps/docs/src/demos/cn/close-button/with-custom-icon.tsx
new file mode 100644
index 0000000..675dab9
--- /dev/null
+++ b/apps/docs/src/demos/cn/close-button/with-custom-icon.tsx
@@ -0,0 +1,21 @@
+import {CircleXmark, Xmark} from "@gravity-ui/icons";
+import {CloseButton} from "@heroui/react";
+
+export function WithCustomIcon() {
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton>
+          <CircleXmark />
+        </CloseButton>
+        <span className="text-xs text-muted">自定义图标</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton>
+          <Xmark />
+        </CloseButton>
+        <span className="text-xs text-muted">备选图标</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/basic.tsx b/apps/docs/src/demos/cn/color-area/basic.tsx
new file mode 100644
index 0000000..9748d4a
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/basic.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaBasic() {
+  return (
+    <ColorArea defaultValue="rgb(116, 52, 255)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/controlled.tsx b/apps/docs/src/demos/cn/color-area/controlled.tsx
new file mode 100644
index 0000000..d5f9276
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/controlled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function ColorAreaControlled() {
+  const [color, setColor] = useState<Color>(parseColor("#9B80FF"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorArea colorSpace="rgb" value={color} xChannel="red" yChannel="green" onChange={setColor}>
+        <ColorArea.Thumb />
+      </ColorArea>
+      <div className="flex w-[300px] items-center gap-3">
+        <ColorSwatch color={color} size="md" />
+        <p className="text-sm text-muted">
+          Current color:{" "}
+          <span className="font-medium">{color ? color.toString("hex") : "(empty)"}</span>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/custom-render-function.tsx b/apps/docs/src/demos/cn/color-area/custom-render-function.tsx
new file mode 100644
index 0000000..1af6332
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/custom-render-function.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {ColorArea} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ColorArea
+      defaultValue="rgb(116, 52, 255)"
+      render={(props) => <div {...props} data-custom="slider" />}
+    >
+      <ColorArea.Thumb render={(props) => <div {...props} data-custom="thumb" />} />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/disabled.tsx b/apps/docs/src/demos/cn/color-area/disabled.tsx
new file mode 100644
index 0000000..dcbd089
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/disabled.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaDisabled() {
+  return (
+    <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/index.ts b/apps/docs/src/demos/cn/color-area/index.ts
new file mode 100644
index 0000000..641ef59
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/index.ts
@@ -0,0 +1,6 @@
+export {ColorAreaBasic as Basic} from "./basic";
+export {ColorAreaWithDots as WithDots} from "./with-dots";
+export {ColorAreaSpaceAndChannels as SpaceAndChannels} from "./space-and-channels";
+export {ColorAreaControlled as Controlled} from "./controlled";
+export {ColorAreaDisabled as Disabled} from "./disabled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/color-area/space-and-channels.tsx b/apps/docs/src/demos/cn/color-area/space-and-channels.tsx
new file mode 100644
index 0000000..c36a02a
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/space-and-channels.tsx
@@ -0,0 +1,165 @@
+"use client";
+
+import type {ColorSpace, Key} from "@heroui/react";
+
+import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue";
+
+interface ChannelOption {
+  id: ColorChannel;
+  name: string;
+}
+
+const colorSpaces: Array<{id: ColorSpace; name: string}> = [
+  {id: "rgb", name: "RGB"},
+  {id: "hsl", name: "HSL"},
+  {id: "hsb", name: "HSB"},
+];
+
+const channelsBySpace: Record<ColorSpace, ChannelOption[]> = {
+  hsb: [
+    {id: "hue", name: "Hue"},
+    {id: "saturation", name: "Saturation"},
+    {id: "brightness", name: "Brightness"},
+  ],
+  hsl: [
+    {id: "hue", name: "Hue"},
+    {id: "saturation", name: "Saturation"},
+    {id: "lightness", name: "Lightness"},
+  ],
+  rgb: [
+    {id: "red", name: "Red"},
+    {id: "green", name: "Green"},
+    {id: "blue", name: "Blue"},
+  ],
+};
+
+export function ColorAreaSpaceAndChannels() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsb");
+  const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));
+
+  const channels = channelsBySpace[colorSpace];
+  const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
+  const defaultY =
+    colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";
+
+  const [xChannel, setXChannel] = useState<ColorChannel>(defaultX);
+  const [yChannel, setYChannel] = useState<ColorChannel>(defaultY);
+
+  const handleColorSpaceChange = (newSpace: Key | null) => {
+    if (!newSpace) return;
+    const space = newSpace as ColorSpace;
+
+    setColorSpace(space);
+    // Reset channels to appropriate defaults for the new color space
+    if (space === "rgb") {
+      setXChannel("blue");
+      setYChannel("green");
+    } else if (space === "hsl") {
+      setXChannel("saturation");
+      setYChannel("lightness");
+    } else {
+      setXChannel("saturation");
+      setYChannel("brightness");
+    }
+  };
+
+  // Filter out the other channel from options (can't have same channel on both axes)
+  const xChannelOptions = channels.filter((c) => c.id !== yChannel);
+  const yChannelOptions = channels.filter((c) => c.id !== xChannel);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      {/* Controls */}
+      <div className="flex gap-4">
+        {/* Color Space Select */}
+        <Select className="w-32" value={colorSpace} onChange={handleColorSpaceChange}>
+          <Label>Color Space</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {colorSpaces.map((space) => (
+                <ListBox.Item key={space.id} id={space.id} textValue={space.name}>
+                  {space.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        {/* X Channel Select */}
+        <Select
+          className="w-36"
+          value={xChannel}
+          onChange={(value) => value && setXChannel(value as ColorChannel)}
+        >
+          <Label>X Axis</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {xChannelOptions.map((channel) => (
+                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
+                  {channel.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        {/* Y Channel Select */}
+        <Select
+          className="w-36"
+          value={yChannel}
+          onChange={(value) => value && setYChannel(value as ColorChannel)}
+        >
+          <Label>Y Axis</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {yChannelOptions.map((channel) => (
+                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
+                  {channel.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+      {/* Color Area */}
+      <ColorArea
+        colorSpace={colorSpace}
+        value={color}
+        xChannel={xChannel}
+        yChannel={yChannel}
+        onChange={setColor}
+      >
+        <ColorArea.Thumb />
+      </ColorArea>
+
+      {/* Color Value Display */}
+      <div className="flex items-center gap-3">
+        <div
+          className="size-8 rounded-md border border-default"
+          style={{backgroundColor: color.toString("css")}}
+        />
+        <code className="rounded bg-default/50 px-2 py-1 text-sm">
+          {color.toString(colorSpace)}
+        </code>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-area/with-dots.tsx b/apps/docs/src/demos/cn/color-area/with-dots.tsx
new file mode 100644
index 0000000..e3ea2ec
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-area/with-dots.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaWithDots() {
+  return (
+    <ColorArea showDots defaultValue="hsl(200, 100%, 50%)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/basic.tsx b/apps/docs/src/demos/cn/color-field/basic.tsx
new file mode 100644
index 0000000..29ff620
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/basic.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function Basic() {
+  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <ColorField className="w-[280px]" name="color" value={color} onChange={setColor}>
+      <Label>颜色</Label>
+      <ColorField.Group>
+        <ColorField.Prefix>
+          <ColorSwatch color={color ?? undefined} size="xs" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+    </ColorField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/channel-editing.tsx b/apps/docs/src/demos/cn/color-field/channel-editing.tsx
new file mode 100644
index 0000000..885055e
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/channel-editing.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function ChannelEditing() {
+  const [color, setColor] = useState<Color | null>(parseColor("#7F007F"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-sm text-muted">分别编辑 HSL 通道：</p>
+      <div className="flex gap-4">
+        <ColorField
+          channel="hue"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="hue"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>色相</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+          </ColorField.Group>
+        </ColorField>
+        <ColorField
+          channel="saturation"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="saturation"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>饱和度</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+            <ColorField.Suffix>
+              <span className="text-sm text-muted">%</span>
+            </ColorField.Suffix>
+          </ColorField.Group>
+        </ColorField>
+        <ColorField
+          channel="lightness"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="lightness"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>明度</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+            <ColorField.Suffix>
+              <span className="text-sm text-muted">%</span>
+            </ColorField.Suffix>
+          </ColorField.Group>
+        </ColorField>
+      </div>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color ?? undefined} size="md" />
+        <span className="text-sm">当前：{color ? color.toString("hex") : "（空）"}</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/controlled.tsx b/apps/docs/src/demos/cn/color-field/controlled.tsx
new file mode 100644
index 0000000..90d0e45
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/controlled.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}>
+        <Label>颜色</Label>
+        <ColorField.Group>
+          <ColorField.Prefix>
+            <ColorSwatch color={value ?? undefined} size="xs" />
+          </ColorField.Prefix>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>当前值：{value ? value.toString("hex") : "（空）"}</Description>
+      </ColorField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(parseColor("#EF4444"))}>
+          设为红色
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(parseColor("#10B981"))}>
+          设为绿色
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/custom-render-function.tsx b/apps/docs/src/demos/cn/color-field/custom-render-function.tsx
new file mode 100644
index 0000000..ddbf7cc
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/custom-render-function.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function CustomRenderFunction() {
+  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <ColorField
+      className="w-[280px]"
+      name="color"
+      render={(props) => <div {...props} data-custom="foo" />}
+      value={color}
+      onChange={setColor}
+    >
+      <Label>颜色</Label>
+      <ColorField.Group render={(props) => <div {...props} data-custom="foo" />}>
+        <ColorField.Prefix>
+          <ColorSwatch color={color ?? undefined} size="xs" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+    </ColorField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/disabled.tsx b/apps/docs/src/demos/cn/color-field/disabled.tsx
new file mode 100644
index 0000000..5d8c562
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/disabled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isDisabled className="w-[280px]" defaultValue="#0485F7" name="color">
+        <Label>颜色</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>该颜色字段已禁用</Description>
+      </ColorField>
+      <ColorField isDisabled className="w-[280px]" name="color-empty">
+        <Label>颜色</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>该颜色字段已禁用</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/form-example.tsx b/apps/docs/src/demos/cn/color-field/form-example.tsx
new file mode 100644
index 0000000..1b93442
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/form-example.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<Color | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("已提交颜色：", {color: value.toString("hex")});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <ColorField
+        fullWidth
+        isRequired
+        className="w-full"
+        name="brand-color"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>品牌色</Label>
+        <ColorField.Group>
+          <ColorField.Prefix>
+            <ColorSwatch color={value ?? undefined} size="xs" />
+          </ColorField.Prefix>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>选择品牌主色</Description>
+      </ColorField>
+      <Button
+        className="w-full"
+        isDisabled={!value}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "保存中…" : "保存颜色"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/full-width.tsx b/apps/docs/src/demos/cn/color-field/full-width.tsx
new file mode 100644
index 0000000..68a82ca
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/full-width.tsx
@@ -0,0 +1,20 @@
+import {ColorField, Label} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <ColorField fullWidth defaultValue="#10B981" name="color">
+        <Label>品牌色</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField fullWidth defaultValue="#8B5CF6" name="color-with-suffix">
+        <Label>主题色</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/index.ts b/apps/docs/src/demos/cn/color-field/index.ts
new file mode 100644
index 0000000..79c90ff
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {ChannelEditing} from "./channel-editing";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
diff --git a/apps/docs/src/demos/cn/color-field/invalid.tsx b/apps/docs/src/demos/cn/color-field/invalid.tsx
new file mode 100644
index 0000000..6f93cbd
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/invalid.tsx
@@ -0,0 +1,22 @@
+import {ColorField, FieldError, Label} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isInvalid isRequired className="w-[280px]" name="color">
+        <Label>颜色</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <FieldError>请输入有效的十六进制颜色</FieldError>
+      </ColorField>
+      <ColorField isInvalid className="w-[280px]" name="invalid-color">
+        <Label>背景色</Label>
+        <ColorField.Group>
+          <ColorField.Input defaultValue="not-a-color" />
+        </ColorField.Group>
+        <FieldError>颜色格式无效，请使用十六进制（例如 #FF5733）</FieldError>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/on-surface.tsx b/apps/docs/src/demos/cn/color-field/on-surface.tsx
new file mode 100644
index 0000000..7c389c2
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/on-surface.tsx
@@ -0,0 +1,15 @@
+import {ColorField, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-[320px] p-4">
+      <ColorField defaultValue="#3B82F6" name="color">
+        <Label>主题色</Label>
+        <ColorField.Group variant="secondary">
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>选择你的主题色</Description>
+      </ColorField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/required.tsx b/apps/docs/src/demos/cn/color-field/required.tsx
new file mode 100644
index 0000000..28d7d77
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/required.tsx
@@ -0,0 +1,21 @@
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isRequired className="w-[280px]" name="color">
+        <Label>品牌色</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField isRequired className="w-[280px]" name="theme-color">
+        <Label>主题色</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>必填项</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/variants.tsx b/apps/docs/src/demos/cn/color-field/variants.tsx
new file mode 100644
index 0000000..8a4553b
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/variants.tsx
@@ -0,0 +1,20 @@
+import {ColorField, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue="#0485F7" name="primary-color">
+        <Label>主要变体</Label>
+        <ColorField.Group variant="primary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue="#F43F5E" name="secondary-color">
+        <Label>次要变体</Label>
+        <ColorField.Group variant="secondary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-field/with-description.tsx b/apps/docs/src/demos/cn/color-field/with-description.tsx
new file mode 100644
index 0000000..bd35539
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-field/with-description.tsx
@@ -0,0 +1,22 @@
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue="#3B82F6" name="color">
+        <Label>主色</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>输入品牌主色</Description>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue="#F59E0B" name="accent-color">
+        <Label>强调色</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>用于高亮与行动按钮</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-picker/basic.tsx b/apps/docs/src/demos/cn/color-picker/basic.tsx
new file mode 100644
index 0000000..eef68cd
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/basic.tsx
@@ -0,0 +1,30 @@
+import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ColorPicker defaultValue="#0485F7">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>选择颜色</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover>
+        <ColorArea
+          aria-label="取色区域"
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>色相</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-picker/controlled.tsx b/apps/docs/src/demos/cn/color-picker/controlled.tsx
new file mode 100644
index 0000000..3f44e6d
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/controlled.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import {
+  Button,
+  ColorArea,
+  ColorField,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  ColorSwatchPicker,
+  Label,
+  parseColor,
+} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [color, setColor] = useState(parseColor("#325578"));
+
+  const colorPresets = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+    "#f43f5e",
+  ];
+
+  const shuffleColor = () => {
+    const randomHue = Math.floor(Math.random() * 360);
+    const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
+    const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
+
+    setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorPicker value={color} onChange={setColor}>
+        <ColorPicker.Trigger>
+          <ColorSwatch size="lg" />
+          <Label>选择颜色</Label>
+        </ColorPicker.Trigger>
+        <ColorPicker.Popover className="gap-2">
+          <ColorSwatchPicker className="justify-center pt-2" size="xs">
+            {colorPresets.map((preset) => (
+              <ColorSwatchPicker.Item key={preset} color={preset}>
+                <ColorSwatchPicker.Swatch />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+          <ColorArea
+            aria-label="取色区域"
+            className="max-w-full"
+            colorSpace="hsb"
+            xChannel="saturation"
+            yChannel="brightness"
+          >
+            <ColorArea.Thumb />
+          </ColorArea>
+          <div className="flex items-center gap-2 px-1">
+            <ColorSlider aria-label="色相滑块" channel="hue" className="flex-1" colorSpace="hsb">
+              <ColorSlider.Track>
+                <ColorSlider.Thumb />
+              </ColorSlider.Track>
+            </ColorSlider>
+            <Button
+              isIconOnly
+              aria-label="随机颜色"
+              size="sm"
+              variant="tertiary"
+              onPress={shuffleColor}
+            >
+              <Icon className="size-4" icon="gravity-ui:shuffle" />
+            </Button>
+          </div>
+          <ColorField aria-label="颜色">
+            <ColorField.Group variant="secondary">
+              <ColorField.Prefix>
+                <ColorSwatch size="xs" />
+              </ColorField.Prefix>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+        </ColorPicker.Popover>
+      </ColorPicker>
+      <p className="w-60 text-sm text-muted">
+        已选：<span className="font-medium">{color.toString("hex")}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-picker/index.ts b/apps/docs/src/demos/cn/color-picker/index.ts
new file mode 100644
index 0000000..f49dfbc
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/index.ts
@@ -0,0 +1,5 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {WithSwatches} from "./with-swatches";
+export {WithFields} from "./with-fields";
+export {WithSliders} from "./with-sliders";
diff --git a/apps/docs/src/demos/cn/color-picker/with-fields.tsx b/apps/docs/src/demos/cn/color-picker/with-fields.tsx
new file mode 100644
index 0000000..780504f
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/with-fields.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import type {ColorChannel, ColorSpace} from "@heroui/react";
+
+import {
+  ColorArea,
+  ColorField,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+import {useState} from "react";
+
+const CHANNEL_LABELS: Record<ColorChannel, string> = {
+  alpha: "透明度",
+  blue: "蓝",
+  brightness: "亮度",
+  green: "绿",
+  hue: "色相",
+  lightness: "明度",
+  red: "红",
+  saturation: "饱和度",
+};
+
+export function WithFields() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");
+
+  const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+    hsb: ["hue", "saturation", "brightness"],
+    hsl: ["hue", "saturation", "lightness"],
+    rgb: ["red", "green", "blue"],
+  };
+
+  return (
+    <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>选择颜色</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="max-w-62 gap-2">
+        <ColorArea
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>色相</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <Select
+          aria-label="色彩空间"
+          value={colorSpace}
+          variant="secondary"
+          onChange={(value) => setColorSpace(value as ColorSpace)}
+        >
+          <Select.Trigger>
+            <Select.Value className="uppercase" />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {Object.keys(colorChannelsByColorSpace).map((space) => (
+                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
+                  {space}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <div className="grid w-full grid-cols-3 items-center gap-2">
+          {colorChannelsByColorSpace[colorSpace].map((channel) => (
+            <ColorField
+              key={channel}
+              aria-label={CHANNEL_LABELS[channel]}
+              channel={channel}
+              colorSpace={colorSpace}
+            >
+              <ColorField.Group variant="secondary">
+                <ColorField.Input />
+              </ColorField.Group>
+            </ColorField>
+          ))}
+        </div>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-picker/with-sliders.tsx b/apps/docs/src/demos/cn/color-picker/with-sliders.tsx
new file mode 100644
index 0000000..665527f
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/with-sliders.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import type {ColorChannel, ColorSpace} from "@heroui/react";
+
+import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+const CHANNEL_LABELS: Record<ColorChannel, string> = {
+  alpha: "透明度",
+  blue: "蓝",
+  brightness: "亮度",
+  green: "绿",
+  hue: "色相",
+  lightness: "明度",
+  red: "红",
+  saturation: "饱和度",
+};
+
+export function WithSliders() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");
+
+  const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+    hsb: ["hue", "saturation", "brightness", "alpha"],
+    hsl: ["hue", "saturation", "lightness", "alpha"],
+    rgb: ["red", "green", "blue", "alpha"],
+  };
+
+  return (
+    <ColorPicker defaultValue="hsl(219, 58%, 93%)">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>选择颜色</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="max-w-62 gap-2 px-2 py-3">
+        <Select
+          aria-label="色彩空间"
+          value={colorSpace}
+          variant="secondary"
+          onChange={(value) => setColorSpace(value as ColorSpace)}
+        >
+          <Select.Trigger>
+            <Select.Value className="uppercase" />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {Object.keys(colorChannelsByColorSpace).map((space) => (
+                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
+                  {space}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <div className="flex flex-col gap-2">
+          {colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
+            // @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
+            <ColorSlider
+              key={channel}
+              aria-label={CHANNEL_LABELS[channel]}
+              channel={channel}
+              className="gap-1 px-1"
+              colorSpace={colorSpace}
+            >
+              <Label>{CHANNEL_LABELS[channel]}</Label>
+              <ColorSlider.Output className="text-muted" />
+              <ColorSlider.Track>
+                <ColorSlider.Thumb />
+              </ColorSlider.Track>
+            </ColorSlider>
+          ))}
+        </div>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-picker/with-swatches.tsx b/apps/docs/src/demos/cn/color-picker/with-swatches.tsx
new file mode 100644
index 0000000..4ffd8f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-picker/with-swatches.tsx
@@ -0,0 +1,56 @@
+import {
+  ColorArea,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  ColorSwatchPicker,
+  Label,
+} from "@heroui/react";
+
+export function WithSwatches() {
+  const presets = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+    "#f43f5e",
+  ];
+
+  return (
+    <ColorPicker defaultValue="#F43F5E">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>品牌色</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover>
+        <ColorArea
+          aria-label="取色区域"
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider aria-label="色相滑块" channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>色相</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSwatchPicker className="justify-center px-1" size="xs">
+          {presets.map((preset) => (
+            <ColorSwatchPicker.Item key={preset} color={preset}>
+              <ColorSwatchPicker.Swatch />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/alpha-channel.tsx b/apps/docs/src/demos/cn/color-slider/alpha-channel.tsx
new file mode 100644
index 0000000..9fd08a0
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/alpha-channel.tsx
@@ -0,0 +1,13 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function AlphaChannel() {
+  return (
+    <ColorSlider channel="alpha" className="w-full max-w-xs" defaultValue="hsla(0, 100%, 50%, 0.5)">
+      <Label>透明度</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/basic.tsx b/apps/docs/src/demos/cn/color-slider/basic.tsx
new file mode 100644
index 0000000..c26bd60
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/basic.tsx
@@ -0,0 +1,13 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ColorSlider channel="hue" className="w-full max-w-xs" defaultValue="hsl(0, 100%, 50%)">
+      <Label>色相</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/channels.tsx b/apps/docs/src/demos/cn/color-slider/channels.tsx
new file mode 100644
index 0000000..ff42110
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/channels.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function Channels() {
+  const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="hue" value={color} onChange={setColor}>
+        <Label>色相</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="saturation" value={color} onChange={setColor}>
+        <Label>饱和度</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="lightness" value={color} onChange={setColor}>
+        <Label>明度</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          当前颜色：<code className="font-mono">{color.toString("hsl")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/controlled.tsx b/apps/docs/src/demos/cn/color-slider/controlled.tsx
new file mode 100644
index 0000000..322e6f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/controlled.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function Controlled() {
+  const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="hue" value={color} onChange={setColor}>
+        <Label>色相</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          当前颜色：<code className="font-mono">{color.toString("hsl")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/custom-render-function.tsx b/apps/docs/src/demos/cn/color-slider/custom-render-function.tsx
new file mode 100644
index 0000000..f57a18a
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {ColorSlider, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ColorSlider
+      channel="hue"
+      className="w-full max-w-xs"
+      defaultValue="hsl(0, 100%, 50%)"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>色相</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/disabled.tsx b/apps/docs/src/demos/cn/color-slider/disabled.tsx
new file mode 100644
index 0000000..0edfca8
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/disabled.tsx
@@ -0,0 +1,18 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <ColorSlider
+      isDisabled
+      channel="hue"
+      className="w-full max-w-xs"
+      defaultValue="hsl(200, 100%, 50%)"
+    >
+      <Label>色相</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/index.ts b/apps/docs/src/demos/cn/color-slider/index.ts
new file mode 100644
index 0000000..83c5a7e
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/index.ts
@@ -0,0 +1,9 @@
+// ColorSlider demos
+export {Basic} from "./basic";
+export {Channels} from "./channels";
+export {AlphaChannel} from "./alpha-channel";
+export {RGBChannels} from "./rgb-channels";
+export {Vertical} from "./vertical";
+export {Disabled} from "./disabled";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/color-slider/rgb-channels.tsx b/apps/docs/src/demos/cn/color-slider/rgb-channels.tsx
new file mode 100644
index 0000000..1392733
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/rgb-channels.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function RGBChannels() {
+  const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="red" value={color} onChange={setColor}>
+        <Label>红</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="green" value={color} onChange={setColor}>
+        <Label>绿</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="blue" value={color} onChange={setColor}>
+        <Label>蓝</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          当前颜色：<code className="font-mono">{color.toString("rgb")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-slider/vertical.tsx b/apps/docs/src/demos/cn/color-slider/vertical.tsx
new file mode 100644
index 0000000..c08e479
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-slider/vertical.tsx
@@ -0,0 +1,38 @@
+import {ColorSlider} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="flex h-48 gap-4">
+      <ColorSlider
+        aria-label="色相"
+        channel="hue"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider
+        aria-label="饱和度"
+        channel="saturation"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider
+        aria-label="明度"
+        channel="lightness"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/basic.tsx b/apps/docs/src/demos/cn/color-swatch-picker/basic.tsx
new file mode 100644
index 0000000..076bcfb
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/basic.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Basic() {
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/controlled.tsx b/apps/docs/src/demos/cn/color-swatch-picker/controlled.tsx
new file mode 100644
index 0000000..5c7a6da
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/controlled.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {ColorSwatchPicker, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Controlled() {
+  const [value, setValue] = useState(parseColor("#F43F5E"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorSwatchPicker value={value} onChange={setValue}>
+        {colors.map((color) => (
+          <ColorSwatchPicker.Item key={color} color={color}>
+            <ColorSwatchPicker.Swatch />
+            <ColorSwatchPicker.Indicator />
+          </ColorSwatchPicker.Item>
+        ))}
+      </ColorSwatchPicker>
+      <p className="text-sm text-muted">
+        已选：<span className="font-medium">{value.toString("hex")}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/custom-indicator.tsx b/apps/docs/src/demos/cn/color-swatch-picker/custom-indicator.tsx
new file mode 100644
index 0000000..8b41379
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/custom-indicator.tsx
@@ -0,0 +1,19 @@
+import {HeartFill} from "@gravity-ui/icons";
+import {ColorSwatchPicker} from "@heroui/react";
+
+export function CustomIndicator() {
+  const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator>
+            <HeartFill />
+          </ColorSwatchPicker.Indicator>
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/custom-render-function.tsx b/apps/docs/src/demos/cn/color-swatch-picker/custom-render-function.tsx
new file mode 100644
index 0000000..89c87ed
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function CustomRenderFunction() {
+  return (
+    <ColorSwatchPicker render={(props) => <div {...props} data-custom="foo" />}>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/default-value.tsx b/apps/docs/src/demos/cn/color-swatch-picker/default-value.tsx
new file mode 100644
index 0000000..33fbac6
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/default-value.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function DefaultValue() {
+  return (
+    <ColorSwatchPicker defaultValue="#8B5CF6">
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/disabled.tsx b/apps/docs/src/demos/cn/color-swatch-picker/disabled.tsx
new file mode 100644
index 0000000..ca08b5d
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/disabled.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Disabled() {
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} isDisabled color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/index.ts b/apps/docs/src/demos/cn/color-swatch-picker/index.ts
new file mode 100644
index 0000000..2cf7794
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {Sizes} from "./sizes";
+export {StackLayout} from "./stack-layout";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/sizes.tsx b/apps/docs/src/demos/cn/color-swatch-picker/sizes.tsx
new file mode 100644
index 0000000..fbab429
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/sizes.tsx
@@ -0,0 +1,33 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+
+const SIZE_LABELS: Record<(typeof sizes)[number], string> = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+  xl: "特大",
+  xs: "特小",
+};
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      {sizes.map((size) => (
+        <div key={size} className="flex items-center gap-4">
+          <span className="w-8 text-sm text-muted">{SIZE_LABELS[size]}</span>
+          <ColorSwatchPicker size={size}>
+            {colors.map((color) => (
+              <ColorSwatchPicker.Item key={color} color={color}>
+                <ColorSwatchPicker.Swatch />
+                <ColorSwatchPicker.Indicator />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/stack-layout.tsx b/apps/docs/src/demos/cn/color-swatch-picker/stack-layout.tsx
new file mode 100644
index 0000000..403838b
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/stack-layout.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function StackLayout() {
+  return (
+    <ColorSwatchPicker layout="stack">
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch-picker/variants.tsx b/apps/docs/src/demos/cn/color-swatch-picker/variants.tsx
new file mode 100644
index 0000000..15e7320
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch-picker/variants.tsx
@@ -0,0 +1,32 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">圆形（默认）</span>
+        <ColorSwatchPicker variant="circle">
+          {colors.map((color) => (
+            <ColorSwatchPicker.Item key={color} color={color}>
+              <ColorSwatchPicker.Swatch />
+              <ColorSwatchPicker.Indicator />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">方形</span>
+        <ColorSwatchPicker variant="square">
+          {colors.map((color) => (
+            <ColorSwatchPicker.Item key={color} color={color}>
+              <ColorSwatchPicker.Swatch />
+              <ColorSwatchPicker.Indicator />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/accessibility.tsx b/apps/docs/src/demos/cn/color-swatch/accessibility.tsx
new file mode 100644
index 0000000..306ae6e
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/accessibility.tsx
@@ -0,0 +1,11 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchAccessibility() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="主品牌色" color="#0485F7" colorName="海洋蓝" />
+      <ColorSwatch aria-label="错误状态色" color="#EF4444" colorName="珊瑚红" />
+      <ColorSwatch aria-label="警告色" color="#F59E0B" colorName="落日橙" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/basic.tsx b/apps/docs/src/demos/cn/color-swatch/basic.tsx
new file mode 100644
index 0000000..e19228b
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/basic.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchBasic() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="蓝色" color="#0485F7" />
+      <ColorSwatch aria-label="红色" color="#EF4444" />
+      <ColorSwatch aria-label="琥珀色" color="#F59E0B" />
+      <ColorSwatch aria-label="绿色" color="#10B981" />
+      <ColorSwatch aria-label="品红" color="#D946EF" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/custom-render-function.tsx b/apps/docs/src/demos/cn/color-swatch/custom-render-function.tsx
new file mode 100644
index 0000000..f7b869f
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/custom-render-function.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {ColorSwatch} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch
+        aria-label="蓝色"
+        color="#0485F7"
+        render={(props) => <div {...props} data-custom="blue" />}
+      />
+      <ColorSwatch
+        aria-label="红色"
+        color="#EF4444"
+        render={(props) => <div {...props} data-custom="red" />}
+      />
+      <ColorSwatch
+        aria-label="琥珀色"
+        color="#F59E0B"
+        render={(props) => <div {...props} data-custom="amber" />}
+      />
+      <ColorSwatch
+        aria-label="绿色"
+        color="#10B981"
+        render={(props) => <div {...props} data-custom="green" />}
+      />
+      <ColorSwatch
+        aria-label="品红"
+        color="#D946EF"
+        render={(props) => <div {...props} data-custom="fuchsia" />}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/custom-styles.tsx b/apps/docs/src/demos/cn/color-swatch/custom-styles.tsx
new file mode 100644
index 0000000..aab76b9
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/custom-styles.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchCustomStyles() {
+  const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
+
+  return (
+    <div className="flex flex-col gap-8">
+      {/* 发光效果 */}
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">发光效果</span>
+        <div className="flex items-center gap-4">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="xl"
+              style={() => ({
+                boxShadow: `0 0 20px 2px ${color}`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* 渐变色块 */}
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">渐变</span>
+        <div className="flex items-center gap-4">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="xl"
+              style={({color: c}) => ({
+                background: `linear-gradient(135deg, ${c.toString("css")}, white)`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/index.ts b/apps/docs/src/demos/cn/color-swatch/index.ts
new file mode 100644
index 0000000..25db5d0
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/index.ts
@@ -0,0 +1,7 @@
+export {ColorSwatchBasic as Basic} from "./basic";
+export {ColorSwatchSizes as Sizes} from "./sizes";
+export {ColorSwatchShapes as Shapes} from "./shapes";
+export {ColorSwatchTransparency as Transparency} from "./transparency";
+export {ColorSwatchCustomStyles as CustomStyles} from "./custom-styles";
+export {ColorSwatchAccessibility as Accessibility} from "./accessibility";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/color-swatch/shapes.tsx b/apps/docs/src/demos/cn/color-swatch/shapes.tsx
new file mode 100644
index 0000000..8f3da77
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/shapes.tsx
@@ -0,0 +1,10 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchShapes() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch color="#0485F7" shape="circle" />
+      <ColorSwatch color="#0485F7" shape="square" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/sizes.tsx b/apps/docs/src/demos/cn/color-swatch/sizes.tsx
new file mode 100644
index 0000000..a076279
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/sizes.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchSizes() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch color="#0485F7" size="xs" />
+      <ColorSwatch color="#EF4444" size="sm" />
+      <ColorSwatch color="#F59E0B" size="md" />
+      <ColorSwatch color="#10B981" size="lg" />
+      <ColorSwatch color="#D946EF" size="xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/color-swatch/transparency.tsx b/apps/docs/src/demos/cn/color-swatch/transparency.tsx
new file mode 100644
index 0000000..3fd6e74
--- /dev/null
+++ b/apps/docs/src/demos/cn/color-swatch/transparency.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchTransparency() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="100% 不透明度" color="rgba(4, 133, 247, 1)" />
+      <ColorSwatch aria-label="75% 不透明度" color="rgba(4, 133, 247, 0.75)" />
+      <ColorSwatch aria-label="50% 不透明度" color="rgba(4, 133, 247, 0.5)" />
+      <ColorSwatch aria-label="25% 不透明度" color="rgba(4, 133, 247, 0.25)" />
+      <ColorSwatch aria-label="0% 不透明度" color="rgba(4, 133, 247, 0)" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/allows-custom-value.tsx b/apps/docs/src/demos/cn/combo-box/allows-custom-value.tsx
new file mode 100644
index 0000000..d2e44e0
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/allows-custom-value.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function AllowsCustomValue() {
+  return (
+    <ComboBox allowsCustomValue className="w-[256px]">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索或输入动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>可输入任意动物名称，即使不在列表中</Description>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/asynchronous-loading.tsx b/apps/docs/src/demos/cn/combo-box/asynchronous-loading.tsx
new file mode 100644
index 0000000..6abe8c7
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/asynchronous-loading.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import {
+  Collection,
+  ComboBox,
+  EmptyState,
+  Input,
+  Label,
+  ListBox,
+  ListBoxLoadMoreItem,
+  Spinner,
+} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+
+interface Character {
+  name: string;
+}
+
+export function AsynchronousLoading() {
+  const list = useAsyncList<Character>({
+    async load({cursor, filterText, signal}) {
+      if (cursor) {
+        cursor = cursor.replace(/^http:\/\//i, "https://");
+      }
+
+      const res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, {
+        signal,
+      });
+      const json = await res.json();
+
+      return {
+        cursor: json.next,
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <ComboBox
+      allowsEmptyCollection
+      className="w-[256px]"
+      inputValue={list.filterText}
+      onInputChange={list.setFilterText}
+    >
+      <Label>选择角色</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="星球大战角色…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox renderEmptyState={() => <EmptyState />}>
+          <Collection items={list.items}>
+            {(item) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="muted text-sm">加载更多…</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/controlled-input-value.tsx b/apps/docs/src/demos/cn/combo-box/controlled-input-value.tsx
new file mode 100644
index 0000000..bd8bcd1
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/controlled-input-value.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledInputValue() {
+  const [inputValue, setInputValue] = useState("");
+
+  return (
+    <div className="space-y-2">
+      <ComboBox className="w-[256px]" inputValue={inputValue} onInputChange={setInputValue}>
+        <Label>搜索（受控输入）</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="输入以搜索…" />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="土豚">
+              土豚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="猫">
+              猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="狗">
+              狗
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="袋鼠">
+              袋鼠
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="panda" textValue="熊猫">
+              熊猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="snake" textValue="蛇">
+              蛇
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+      <p className="text-sm text-muted">输入值：{inputValue || "（空）"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/controlled.tsx b/apps/docs/src/demos/cn/combo-box/controlled.tsx
new file mode 100644
index 0000000..7c28570
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/controlled.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const animals = [
+    {
+      id: "cat",
+      name: "猫",
+    },
+    {
+      id: "dog",
+      name: "狗",
+    },
+    {
+      id: "bird",
+      name: "鸟",
+    },
+    {
+      id: "fish",
+      name: "鱼",
+    },
+    {
+      id: "hamster",
+      name: "仓鼠",
+    },
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>("cat");
+
+  const selectedAnimal = animals.find((a) => a.id === selectedKey);
+
+  return (
+    <div className="space-y-2">
+      <ComboBox
+        className="w-[256px]"
+        selectedKey={selectedKey}
+        onSelectionChange={(key) => setSelectedKey(key)}
+      >
+        <Label>动物（受控）</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="搜索动物…" />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            {animals.map((animal) => (
+              <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+                {animal.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+      <p className="text-sm text-muted">已选：{selectedAnimal?.name || "无"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/custom-filtering.tsx b/apps/docs/src/demos/cn/combo-box/custom-filtering.tsx
new file mode 100644
index 0000000..4d6015a
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/custom-filtering.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomFiltering() {
+  const animals = [
+    {id: "cat", name: "猫"},
+    {id: "dog", name: "狗"},
+    {id: "bird", name: "鸟"},
+    {id: "fish", name: "鱼"},
+    {id: "hamster", name: "仓鼠"},
+  ];
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      defaultFilter={(text, inputValue) => {
+        if (!inputValue) return true;
+
+        return text.toLowerCase().includes(inputValue.toLowerCase());
+      }}
+    >
+      <Label>动物（自定义筛选）</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          {animals.map((animal) => (
+            <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+              {animal.name}
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/custom-indicator.tsx b/apps/docs/src/demos/cn/combo-box/custom-indicator.tsx
new file mode 100644
index 0000000..32995eb
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/custom-indicator.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger className="size-3">
+          <ChevronsExpandVertical />
+        </ComboBox.Trigger>
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/custom-render-function.tsx b/apps/docs/src/demos/cn/combo-box/custom-render-function.tsx
new file mode 100644
index 0000000..c8f0547
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/custom-render-function.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ComboBox className="w-[256px]" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/custom-value.tsx b/apps/docs/src/demos/cn/combo-box/custom-value.tsx
new file mode 100644
index 0000000..b61307e
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/custom-value.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  ComboBox,
+  Description,
+  Input,
+  Label,
+  ListBox,
+} from "@heroui/react";
+
+export function CustomValue() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>用户</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索用户…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/default-selected-key.tsx b/apps/docs/src/demos/cn/combo-box/default-selected-key.tsx
new file mode 100644
index 0000000..0e1981a
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/default-selected-key.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function DefaultSelectedKey() {
+  return (
+    <ComboBox className="w-[256px]" defaultSelectedKey="cat">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/default.tsx b/apps/docs/src/demos/cn/combo-box/default.tsx
new file mode 100644
index 0000000..fcc8f4b
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/default.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function Default() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/disabled.tsx b/apps/docs/src/demos/cn/combo-box/disabled.tsx
new file mode 100644
index 0000000..6d40702
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/disabled.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <ComboBox isDisabled className="w-[256px]" defaultSelectedKey="cat">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/full-width.tsx b/apps/docs/src/demos/cn/combo-box/full-width.tsx
new file mode 100644
index 0000000..e5ed563
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/full-width.tsx
@@ -0,0 +1,31 @@
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <ComboBox fullWidth>
+        <Label>最喜欢的动物</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="搜索动物…" />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="土豚">
+              土豚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="猫">
+              猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="狗">
+              狗
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/index.ts b/apps/docs/src/demos/cn/combo-box/index.ts
new file mode 100644
index 0000000..160d052
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/index.ts
@@ -0,0 +1,19 @@
+// ComboBox demos
+export {AllowsCustomValue} from "./allows-custom-value";
+export {AsynchronousLoading} from "./asynchronous-loading";
+export {Controlled} from "./controlled";
+export {ControlledInputValue} from "./controlled-input-value";
+export {CustomFiltering} from "./custom-filtering";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomValue} from "./custom-value";
+export {Default} from "./default";
+export {DefaultSelectedKey} from "./default-selected-key";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {MenuTrigger} from "./menu-trigger";
+export {Required} from "./required";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/cn/combo-box/menu-trigger.tsx b/apps/docs/src/demos/cn/combo-box/menu-trigger.tsx
new file mode 100644
index 0000000..3837b49
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/menu-trigger.tsx
@@ -0,0 +1,129 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function MenuTrigger() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">聚焦（默认）</p>
+        <ComboBox className="w-[256px]" menuTrigger="focus">
+          <Label>最喜欢的动物</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="搜索动物…" />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="土豚">
+                土豚
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="猫">
+                猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="狗">
+                狗
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="袋鼠">
+                袋鼠
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="熊猫">
+                熊猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="蛇">
+                蛇
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>输入框获得焦点时打开弹出层</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">输入</p>
+        <ComboBox className="w-[256px]" menuTrigger="input">
+          <Label>最喜欢的动物</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="搜索动物…" />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="土豚">
+                土豚
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="猫">
+                猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="狗">
+                狗
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="袋鼠">
+                袋鼠
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="熊猫">
+                熊猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="蛇">
+                蛇
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>用户编辑输入文本时打开弹出层</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">手动</p>
+        <ComboBox className="w-[256px]" menuTrigger="manual">
+          <Label>最喜欢的动物</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="搜索动物…" />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="土豚">
+                土豚
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="猫">
+                猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="狗">
+                狗
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="袋鼠">
+                袋鼠
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="熊猫">
+                熊猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="蛇">
+                蛇
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>仅在按下触发按钮或使用方向键时打开弹出层</Description>
+        </ComboBox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/on-surface.tsx b/apps/docs/src/demos/cn/combo-box/on-surface.tsx
new file mode 100644
index 0000000..6ff8762
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/on-surface.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Button, ComboBox, FieldError, Form, Input, Label, ListBox, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Surface className="w-[320px] rounded-3xl p-6">
+      <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}>
+        <ComboBox isRequired className="w-full" name="animal" variant="secondary">
+          <Label>最喜欢的动物</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="搜索动物…" />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="土豚">
+                土豚
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="猫">
+                猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="狗">
+                狗
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="袋鼠">
+                袋鼠
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="熊猫">
+                熊猫
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="蛇">
+                蛇
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">提交</Button>
+      </Form>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/required.tsx b/apps/docs/src/demos/cn/combo-box/required.tsx
new file mode 100644
index 0000000..47128e0
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/required.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <ComboBox isRequired className="w-full" name="animal">
+        <Label>最喜欢的动物</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="搜索动物…" />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="土豚">
+              土豚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="猫">
+              猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="狗">
+              狗
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="袋鼠">
+              袋鼠
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="panda" textValue="熊猫">
+              熊猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="snake" textValue="蛇">
+              蛇
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+      <Button type="submit">提交</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/with-description.tsx b/apps/docs/src/demos/cn/combo-box/with-description.tsx
new file mode 100644
index 0000000..9f83bff
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/with-description.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>最喜欢的动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="土豚">
+            土豚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="熊猫">
+            熊猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="蛇">
+            蛇
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>搜索并选择你最喜欢的动物</Description>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/with-disabled-options.tsx b/apps/docs/src/demos/cn/combo-box/with-disabled-options.tsx
new file mode 100644
index 0000000..51ffddb
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/with-disabled-options.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function WithDisabledOptions() {
+  return (
+    <ComboBox className="w-[256px]" disabledKeys={["cat", "kangaroo"]}>
+      <Label>动物</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索动物…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="鸟">
+            鸟
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="象">
+            象
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="老虎">
+            老虎
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/combo-box/with-sections.tsx b/apps/docs/src/demos/cn/combo-box/with-sections.tsx
new file mode 100644
index 0000000..1dee7e3
--- /dev/null
+++ b/apps/docs/src/demos/cn/combo-box/with-sections.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import {ComboBox, Header, Input, Label, ListBox, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>国家</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="搜索国家…" />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>北美洲</Header>
+            <ListBox.Item id="usa" textValue="美国">
+              美国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="加拿大">
+              加拿大
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="墨西哥">
+              墨西哥
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>欧洲</Header>
+            <ListBox.Item id="uk" textValue="英国">
+              英国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="法国">
+              法国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="德国">
+              德国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="西班牙">
+              西班牙
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="意大利">
+              意大利
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>亚洲</Header>
+            <ListBox.Item id="japan" textValue="日本">
+              日本
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="中国">
+              中国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="印度">
+              印度
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="韩国">
+              韩国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/basic.tsx b/apps/docs/src/demos/cn/date-field/basic.tsx
new file mode 100644
index 0000000..146a0a4
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>日期</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/controlled.tsx b/apps/docs/src/demos/cn/date-field/controlled.tsx
new file mode 100644
index 0000000..4ccbd36
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/controlled.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, DateField, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<DateValue | null>(null);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="date" value={value} onChange={setValue}>
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>当前值：{value ? value.toString() : "（空）"}</Description>
+      </DateField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
+          设为今天
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/custom-render-function.tsx b/apps/docs/src/demos/cn/date-field/custom-render-function.tsx
new file mode 100644
index 0000000..e2a255c
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DateField
+      className="w-[256px]"
+      name="date"
+      render={(props) => <div {...props} data-custom="date-field" />}
+    >
+      <Label render={(props) => <span {...props} data-custom="date-field-label" />}>日期</Label>
+      <DateField.Group render={(props) => <div {...props} data-custom="date-field-group" />}>
+        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/disabled.tsx b/apps/docs/src/demos/cn/date-field/disabled.tsx
new file mode 100644
index 0000000..12828bc
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/disabled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isDisabled className="w-[256px]" name="date" value={today(getLocalTimeZone())}>
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>该日期字段已禁用</Description>
+      </DateField>
+      <DateField isDisabled className="w-[256px]" name="date-empty">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>该日期字段已禁用</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/form-example.tsx b/apps/docs/src/demos/cn/date-field/form-example.tsx
new file mode 100644
index 0000000..e1a7984
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/form-example.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar} from "@gravity-ui/icons";
+import {Button, DateField, Description, FieldError, Form, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const todayDate = today(getLocalTimeZone());
+  const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("已提交日期：", {date: value});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <DateField
+        isRequired
+        className="w-full"
+        isInvalid={isInvalid}
+        minValue={todayDate}
+        name="date"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>预约日期</Label>
+        <DateField.Group>
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>日期须为今天或将来</FieldError>
+        ) : (
+          <Description>输入日期 from today onwards</Description>
+        )}
+      </DateField>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "提交中…" : "Submit"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/full-width.tsx b/apps/docs/src/demos/cn/date-field/full-width.tsx
new file mode 100644
index 0000000..16e4e38
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/full-width.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar, ChevronDown} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <DateField fullWidth name="date">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField fullWidth name="date-icons">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <ChevronDown className="size-4 text-muted" />
+          </DateField.Suffix>
+        </DateField.Group>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/granularity.tsx b/apps/docs/src/demos/cn/date-field/granularity.tsx
new file mode 100644
index 0000000..0cf0f0a
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/granularity.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {CircleQuestion} from "@gravity-ui/icons";
+import {DateField, Label, ListBox, Select, Tooltip} from "@heroui/react";
+import {parseDate, parseZonedDateTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function Granularity() {
+  const granularityOptions = [
+    {id: "day", label: "日"},
+    {id: "hour", label: "时"},
+    {id: "minute", label: "分"},
+    {id: "second", label: "秒"},
+  ] as const;
+
+  const [granularity, setGranularity] = useState<"day" | "hour" | "minute" | "second">("day");
+
+  // Determine appropriate default value based on granularity
+  let defaultValue: DateValue;
+
+  if (granularity === "day") {
+    defaultValue = parseDate("2025-02-03");
+  } else {
+    // hour, minute, second
+    defaultValue = parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]");
+  }
+
+  return (
+    <div className="flex gap-4">
+      <DateField
+        className="w-[256px]"
+        defaultValue={defaultValue}
+        granularity={granularity}
+        name="granularity-date"
+      >
+        <Label>预约日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-2">
+          <Label>粒度</Label>
+          <Tooltip delay={0}>
+            <Tooltip.Trigger aria-label="粒度说明">
+              <CircleQuestion className="size-4 text-muted" />
+            </Tooltip.Trigger>
+            <Tooltip.Content placement="bottom start">
+              <p>决定日期选择器显示的最小单位。默认情况下，日期为「日」，时间为「分」。</p>
+            </Tooltip.Content>
+          </Tooltip>
+        </div>
+        <Select
+          className="w-[110px]"
+          placeholder="选择粒度"
+          value={granularity}
+          variant="secondary"
+          onChange={(value) => setGranularity(value as typeof granularity)}
+        >
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {granularityOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.label}>
+                  {option.label}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/index.ts b/apps/docs/src/demos/cn/date-field/index.ts
new file mode 100644
index 0000000..417bb1c
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/index.ts
@@ -0,0 +1,16 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Granularity} from "./granularity";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/cn/date-field/invalid.tsx b/apps/docs/src/demos/cn/date-field/invalid.tsx
new file mode 100644
index 0000000..02d6dbc
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/invalid.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {DateField, FieldError, Label} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isInvalid isRequired className="w-[256px]" name="date">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>请输入有效日期</FieldError>
+      </DateField>
+      <DateField isInvalid className="w-[256px]" name="invalid-date">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>日期须为将来</FieldError>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/on-surface.tsx b/apps/docs/src/demos/cn/date-field/on-surface.tsx
new file mode 100644
index 0000000..8b6dba9
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/on-surface.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <DateField className="w-full" name="date">
+        <Label>日期</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>输入日期</Description>
+      </DateField>
+      <DateField className="w-full" name="date-2">
+        <Label>预约日期</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>输入预约日期</Description>
+      </DateField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/required.tsx b/apps/docs/src/demos/cn/date-field/required.tsx
new file mode 100644
index 0000000..b902f92
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/required.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isRequired className="w-[256px]" name="date">
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField isRequired className="w-[256px]" name="start-date">
+        <Label>开始日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>必填项</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/variants.tsx b/apps/docs/src/demos/cn/date-field/variants.tsx
new file mode 100644
index 0000000..0d3e5b3
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/variants.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="primary-date">
+        <Label>主要变体</Label>
+        <DateField.Group variant="primary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField className="w-[256px]" name="secondary-date">
+        <Label>次要变体</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/with-description.tsx b/apps/docs/src/demos/cn/date-field/with-description.tsx
new file mode 100644
index 0000000..151d3d4
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/with-description.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="date">
+        <Label>出生日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>输入出生日期</Description>
+      </DateField>
+      <DateField className="w-[256px]" name="appointment-date">
+        <Label>预约日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>输入预约日期</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/with-prefix-and-suffix.tsx b/apps/docs/src/demos/cn/date-field/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..f8bf93a
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/with-prefix-and-suffix.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Calendar, ChevronDown} from "@gravity-ui/icons";
+import {DateField, Description, Label} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>日期</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <ChevronDown className="size-4 text-muted" />
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>输入日期</Description>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/with-prefix-icon.tsx b/apps/docs/src/demos/cn/date-field/with-prefix-icon.tsx
new file mode 100644
index 0000000..655c03d
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/with-prefix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>日期</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/with-suffix-icon.tsx b/apps/docs/src/demos/cn/date-field/with-suffix-icon.tsx
new file mode 100644
index 0000000..6008ca1
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/with-suffix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>日期</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Suffix>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-field/with-validation.tsx b/apps/docs/src/demos/cn/date-field/with-validation.tsx
new file mode 100644
index 0000000..417d9be
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-field/with-validation.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {DateField, Description, FieldError, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const todayDate = today(getLocalTimeZone());
+  const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField
+        isRequired
+        className="w-[256px]"
+        isInvalid={isInvalid}
+        minValue={todayDate}
+        name="date"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>日期</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>日期须为今天或将来</FieldError>
+        ) : (
+          <Description>输入日期 from today onwards</Description>
+        )}
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/basic.tsx b/apps/docs/src/demos/cn/date-picker/basic.tsx
new file mode 100644
index 0000000..ff6a454
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/basic.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DatePicker className="w-72" name="date">
+      <Label>日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="活动日期">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/controlled.tsx b/apps/docs/src/demos/cn/date-picker/controlled.tsx
new file mode 100644
index 0000000..6291976
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/controlled.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<DateValue | null>(today(getLocalTimeZone()));
+
+  return (
+    <div className="flex w-72 flex-col gap-4">
+      <DatePicker name="date" value={value} onChange={setValue}>
+        <Label>日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <Calendar aria-label="活动日期">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+      <Description>当前值：{value ? value.toString() : "（空）"}</Description>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
+          设为今天
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/custom-render-function.tsx b/apps/docs/src/demos/cn/date-picker/custom-render-function.tsx
new file mode 100644
index 0000000..856914e
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/custom-render-function.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DatePicker
+      className="w-72"
+      name="date"
+      render={(props) => <div {...props} data-custom="date-picker" />}
+    >
+      <Label render={(props) => <span {...props} data-custom="date-picker-label" />}>日期</Label>
+      <DateField.Group
+        fullWidth
+        render={(props) => <div {...props} data-custom="date-field-group" />}
+      >
+        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
+          {(segment) => (
+            <DateField.Segment
+              render={(props) => <span {...props} data-custom="date-field-segment" />}
+              segment={segment}
+            />
+          )}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger
+            render={(props) => <button {...props} data-custom="date-picker-trigger" />}
+          >
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="活动日期">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/disabled.tsx b/apps/docs/src/demos/cn/date-picker/disabled.tsx
new file mode 100644
index 0000000..81f8926
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/disabled.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <DatePicker isDisabled className="w-72" name="date" value={today(getLocalTimeZone())}>
+      <Label>日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>该日期选择器已禁用。</Description>
+      <DatePicker.Popover>
+        <Calendar aria-label="活动日期">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/form-example.tsx b/apps/docs/src/demos/cn/date-picker/form-example.tsx
new file mode 100644
index 0000000..81adcec
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/form-example.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Button,
+  Calendar,
+  DateField,
+  DatePicker,
+  Description,
+  FieldError,
+  Form,
+  Label,
+} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid = value != null && value.compare(currentDate) < 0;
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1200);
+  };
+
+  return (
+    <Form className="flex w-72 flex-col gap-3" onSubmit={handleSubmit}>
+      <DatePicker
+        isRequired
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        name="appointmentDate"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>预约日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>日期须为今天或将来。</FieldError>
+        ) : (
+          <Description>请选择有效的预约日期。</Description>
+        )}
+        <DatePicker.Popover>
+          <Calendar aria-label="活动日期">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+      >
+        {isSubmitting ? "提交中…" : "提交"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/format-options-no-ssr.tsx b/apps/docs/src/demos/cn/date-picker/format-options-no-ssr.tsx
new file mode 100644
index 0000000..b07dd4c
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/format-options-no-ssr.tsx
@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+export const FormatOptions = dynamic(
+  () => import("./format-options").then((mod) => mod.FormatOptions),
+  {
+    ssr: false,
+  },
+);
diff --git a/apps/docs/src/demos/cn/date-picker/format-options.tsx b/apps/docs/src/demos/cn/date-picker/format-options.tsx
new file mode 100644
index 0000000..d56c0b0
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/format-options.tsx
@@ -0,0 +1,194 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Calendar,
+  DateField,
+  DatePicker,
+  Label,
+  ListBox,
+  Select,
+  Switch,
+  TimeField,
+} from "@heroui/react";
+import {getLocalTimeZone, parseDate, parseZonedDateTime} from "@internationalized/date";
+import {useMemo, useState} from "react";
+
+type Granularity = "day" | "hour" | "minute" | "second";
+type HourCycle = 12 | 24;
+const granularityOptions: {label: string; value: Granularity}[] = [
+  {label: "日", value: "day"},
+  {label: "时", value: "hour"},
+  {label: "分", value: "minute"},
+  {label: "秒", value: "second"},
+];
+const hourCycleOptions: {label: string; value: HourCycle}[] = [
+  {label: "12 小时制", value: 12},
+  {label: "24 小时制", value: 24},
+];
+
+export function FormatOptions() {
+  const [granularity, setGranularity] = useState<Granularity>("minute");
+  const [hourCycle, setHourCycle] = useState<HourCycle>(12);
+  const [hideTimeZone, setHideTimeZone] = useState(false);
+  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);
+  const timeGranularity = granularity !== "day" ? granularity : undefined;
+  const showTimeField = !!timeGranularity;
+  const defaultValue = useMemo<DateValue>(() => {
+    const localTimeZone = getLocalTimeZone();
+
+    if (granularity === "day") {
+      return parseDate("2026-02-03");
+    }
+
+    return parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`);
+  }, [granularity]);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DatePicker
+        key={granularity}
+        className="w-fit min-w-72"
+        defaultValue={defaultValue}
+        granularity={granularity}
+        hideTimeZone={hideTimeZone}
+        hourCycle={hourCycle}
+        name="date"
+        shouldForceLeadingZeros={shouldForceLeadingZeros}
+      >
+        {({state}) => (
+          <>
+            <Label>日期和时间</Label>
+            <DateField.Group fullWidth>
+              <DateField.Input>
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+              <DateField.Suffix>
+                <DatePicker.Trigger>
+                  <DatePicker.TriggerIndicator />
+                </DatePicker.Trigger>
+              </DateField.Suffix>
+            </DateField.Group>
+            <DatePicker.Popover className="flex flex-col gap-3">
+              <Calendar aria-label="活动日期">
+                <Calendar.Header>
+                  <Calendar.YearPickerTrigger>
+                    <Calendar.YearPickerTriggerHeading />
+                    <Calendar.YearPickerTriggerIndicator />
+                  </Calendar.YearPickerTrigger>
+                  <Calendar.NavButton slot="previous" />
+                  <Calendar.NavButton slot="next" />
+                </Calendar.Header>
+                <Calendar.Grid>
+                  <Calendar.GridHeader>
+                    {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+                  </Calendar.GridHeader>
+                  <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+                </Calendar.Grid>
+                <Calendar.YearPickerGrid>
+                  <Calendar.YearPickerGridBody>
+                    {({year}) => <Calendar.YearPickerCell year={year} />}
+                  </Calendar.YearPickerGridBody>
+                </Calendar.YearPickerGrid>
+              </Calendar>
+              {!!showTimeField && (
+                <div className="flex items-center justify-between">
+                  <Label>时间</Label>
+                  <TimeField
+                    aria-label="时间"
+                    granularity={timeGranularity}
+                    hideTimeZone={hideTimeZone}
+                    hourCycle={hourCycle}
+                    name="time"
+                    shouldForceLeadingZeros={shouldForceLeadingZeros}
+                    value={state.timeValue}
+                    onChange={(v) => state.setTimeValue(v as TimeValue)}
+                  >
+                    <TimeField.Group variant="secondary">
+                      <TimeField.Input>
+                        {(segment) => <TimeField.Segment segment={segment} />}
+                      </TimeField.Input>
+                    </TimeField.Group>
+                  </TimeField>
+                </div>
+              )}
+            </DatePicker.Popover>
+          </>
+        )}
+      </DatePicker>
+
+      <div className="flex flex-wrap gap-4">
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={granularity}
+            variant="secondary"
+            onChange={(value) => setGranularity(value as Granularity)}
+          >
+            <Label>粒度</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {granularityOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={hourCycle}
+            variant="secondary"
+            onChange={(value) => setHourCycle(Number(value) as HourCycle)}
+          >
+            <Label>小时制</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {hourCycleOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+      </div>
+
+      <div className="flex min-w-80 flex-col gap-2">
+        <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            隐藏时区
+          </Switch.Content>
+        </Switch>
+        <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            强制前导零
+          </Switch.Content>
+        </Switch>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/index.ts b/apps/docs/src/demos/cn/date-picker/index.ts
new file mode 100644
index 0000000..6136ef5
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormatOptions} from "./format-options-no-ssr";
+export {FormExample} from "./form-example";
+export {InternationalCalendar} from "./international-calendar";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {WithValidation} from "./with-validation";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/date-picker/international-calendar.tsx b/apps/docs/src/demos/cn/date-picker/international-calendar.tsx
new file mode 100644
index 0000000..df3530c
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/international-calendar.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <DatePicker
+        className="w-72"
+        defaultValue={today(getLocalTimeZone())}
+        name="international-date"
+      >
+        <Label>活动日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <Calendar aria-label="活动日期">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/with-custom-indicator.tsx b/apps/docs/src/demos/cn/date-picker/with-custom-indicator.tsx
new file mode 100644
index 0000000..717e1b5
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/with-custom-indicator.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function WithCustomIndicator() {
+  return (
+    <DatePicker className="w-72" name="date">
+      <Label>日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DatePicker.TriggerIndicator>
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>通过传入自定义子元素替换默认日历图标。</Description>
+      <DatePicker.Popover>
+        <Calendar aria-label="活动日期">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-picker/with-validation.tsx b/apps/docs/src/demos/cn/date-picker/with-validation.tsx
new file mode 100644
index 0000000..3648adb
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-picker/with-validation.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, DateField, DatePicker, FieldError, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid = value != null && value.compare(currentDate) < 0;
+
+  return (
+    <DatePicker
+      isRequired
+      className="w-72"
+      isInvalid={isInvalid}
+      minValue={currentDate}
+      name="date"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>预约日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <FieldError>日期须为今天或将来。</FieldError>
+      <DatePicker.Popover>
+        <Calendar aria-label="活动日期">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/basic.tsx b/apps/docs/src/demos/cn/date-range-picker/basic.tsx
new file mode 100644
index 0000000..9902114
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/basic.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DateRangePicker className="w-80" endName="endDate" startName="startDate">
+      <Label>出行日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="出行日期">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/controlled.tsx b/apps/docs/src/demos/cn/date-range-picker/controlled.tsx
new file mode 100644
index 0000000..abe5089
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/controlled.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Controlled() {
+  const start = today(getLocalTimeZone());
+  const [value, setValue] = useState<DateRange | null>({end: start.add({days: 4}), start});
+
+  return (
+    <div className="flex w-80 flex-col gap-4">
+      <DateRangePicker endName="endDate" startName="startDate" value={value} onChange={setValue}>
+        <Label>出行日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="出行日期">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+      <Description>
+        当前值：{value ? `${value.start.toString()} 至 ${value.end.toString()}` : "（空）"}
+      </Description>
+      <div className="flex gap-2">
+        <Button
+          variant="tertiary"
+          onPress={() => {
+            const nextStart = today(getLocalTimeZone());
+
+            setValue({end: nextStart.add({days: 6}), start: nextStart});
+          }}
+        >
+          设为一周
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/custom-render-function.tsx b/apps/docs/src/demos/cn/date-range-picker/custom-render-function.tsx
new file mode 100644
index 0000000..46afb65
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/custom-render-function.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DateRangePicker
+      className="w-80"
+      endName="endDate"
+      render={(props) => <div data-custom="foo" {...props} />}
+      startName="startDate"
+    >
+      <Label>出行日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="出行日期">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/disabled.tsx b/apps/docs/src/demos/cn/date-range-picker/disabled.tsx
new file mode 100644
index 0000000..d9fc4e9
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/disabled.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  const start = today(getLocalTimeZone());
+
+  return (
+    <DateRangePicker
+      isDisabled
+      className="w-80"
+      endName="endDate"
+      startName="startDate"
+      value={{end: start.add({days: 4}), start}}
+    >
+      <Label>出行日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>该日期范围选择器已禁用。</Description>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="出行日期">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/form-example.tsx b/apps/docs/src/demos/cn/date-range-picker/form-example.tsx
new file mode 100644
index 0000000..58ed112
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/form-example.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Button,
+  DateField,
+  DateRangePicker,
+  Description,
+  FieldError,
+  Form,
+  Label,
+  RangeCalendar,
+} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function FormExample() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid =
+    value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault();
+
+    if (!value || isInvalid) return;
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1200);
+  };
+
+  return (
+    <Form className="flex w-80 flex-col gap-3" onSubmit={handleSubmit}>
+      <DateRangePicker
+        isRequired
+        endName="tripEndDate"
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        startName="tripStartDate"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>出行日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>请选择从今天起的有效日期范围。</FieldError>
+        ) : (
+          <Description>选择入住与退房日期。</Description>
+        )}
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="出行日期">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+      >
+        {isSubmitting ? "提交中…" : "提交"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/format-options-no-ssr.tsx b/apps/docs/src/demos/cn/date-range-picker/format-options-no-ssr.tsx
new file mode 100644
index 0000000..b07dd4c
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/format-options-no-ssr.tsx
@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+export const FormatOptions = dynamic(
+  () => import("./format-options").then((mod) => mod.FormatOptions),
+  {
+    ssr: false,
+  },
+);
diff --git a/apps/docs/src/demos/cn/date-range-picker/format-options.tsx b/apps/docs/src/demos/cn/date-range-picker/format-options.tsx
new file mode 100644
index 0000000..3e67bea
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/format-options.tsx
@@ -0,0 +1,280 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+import type {DateValue} from "@internationalized/date";
+
+import {
+  DateField,
+  DateRangePicker,
+  Label,
+  ListBox,
+  RangeCalendar,
+  Select,
+  Separator,
+  Switch,
+  TimeField,
+  useLocale,
+} from "@heroui/react";
+import {
+  DateFormatter,
+  getLocalTimeZone,
+  parseDate,
+  parseZonedDateTime,
+} from "@internationalized/date";
+import {useMemo, useState} from "react";
+
+type Granularity = "day" | "hour" | "minute" | "second";
+type HourCycle = 12 | 24;
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+const granularityOptions: {label: string; value: Granularity}[] = [
+  {label: "日", value: "day"},
+  {label: "时", value: "hour"},
+  {label: "分", value: "minute"},
+  {label: "秒", value: "second"},
+];
+
+const hourCycleOptions: {label: string; value: HourCycle}[] = [
+  {label: "12 小时制", value: 12},
+  {label: "24 小时制", value: 24},
+];
+
+export function FormatOptions() {
+  const [granularity, setGranularity] = useState<Granularity>("minute");
+  const [hourCycle, setHourCycle] = useState<HourCycle>(12);
+  const [hideTimeZone, setHideTimeZone] = useState(false);
+  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);
+  const {locale} = useLocale();
+  const dateFormatter = new DateFormatter(locale, {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+  });
+
+  const formatDate = (date: DateRange) => {
+    const localTimeZone = getLocalTimeZone();
+    const start = date.start.toDate(localTimeZone);
+    const end = date.end.toDate(localTimeZone);
+
+    return dateFormatter.formatRange(start, end);
+  };
+
+  const defaultValue = useMemo<DateRange>(() => {
+    const localTimeZone = getLocalTimeZone();
+
+    if (granularity === "day") {
+      return {
+        end: parseDate("2025-02-10"),
+        start: parseDate("2025-02-03"),
+      };
+    }
+
+    return {
+      end: parseZonedDateTime(`2026-02-10T18:45:00[${localTimeZone}]`),
+      start: parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`),
+    };
+  }, [granularity]);
+
+  const timeGranularity = granularity !== "day" ? granularity : undefined;
+  const showTimeField = !!timeGranularity;
+
+  return (
+    <div className="flex w-full flex-col gap-4">
+      <DateRangePicker
+        key={granularity}
+        className="w-max min-w-80"
+        defaultValue={defaultValue}
+        endName="endDate"
+        granularity={granularity}
+        hideTimeZone={hideTimeZone}
+        hourCycle={hourCycle}
+        shouldForceLeadingZeros={shouldForceLeadingZeros}
+        startName="startDate"
+      >
+        {({state}) => (
+          <>
+            <Label>日期范围</Label>
+            <DateField.Group>
+              <DateField.InputContainer>
+                <DateField.Input slot="start">
+                  {(segment) => <DateField.Segment segment={segment} />}
+                </DateField.Input>
+                <DateRangePicker.RangeSeparator />
+                <DateField.Input slot="end">
+                  {(segment) => <DateField.Segment segment={segment} />}
+                </DateField.Input>
+              </DateField.InputContainer>
+              <DateField.Suffix>
+                <DateRangePicker.Trigger>
+                  <DateRangePicker.TriggerIndicator />
+                </DateRangePicker.Trigger>
+              </DateField.Suffix>
+            </DateField.Group>
+            <DateRangePicker.Popover className="flex w-full flex-col gap-3">
+              <RangeCalendar aria-label="出行日期" className="w-full">
+                <RangeCalendar.Header>
+                  <RangeCalendar.YearPickerTrigger>
+                    <RangeCalendar.YearPickerTriggerHeading />
+                    <RangeCalendar.YearPickerTriggerIndicator />
+                  </RangeCalendar.YearPickerTrigger>
+                  <RangeCalendar.NavButton slot="previous" />
+                  <RangeCalendar.NavButton slot="next" />
+                </RangeCalendar.Header>
+                <RangeCalendar.Grid>
+                  <RangeCalendar.GridHeader>
+                    {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+                  </RangeCalendar.GridHeader>
+                  <RangeCalendar.GridBody>
+                    {(date) => <RangeCalendar.Cell date={date} />}
+                  </RangeCalendar.GridBody>
+                </RangeCalendar.Grid>
+                <RangeCalendar.YearPickerGrid>
+                  <RangeCalendar.YearPickerGridBody>
+                    {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+                  </RangeCalendar.YearPickerGridBody>
+                </RangeCalendar.YearPickerGrid>
+              </RangeCalendar>
+              {!!showTimeField && (
+                <div className="flex flex-col gap-3">
+                  <div className="flex items-center justify-between">
+                    <Label>开始时间</Label>
+                    <TimeField
+                      aria-label="开始时间"
+                      granularity={timeGranularity}
+                      hideTimeZone={hideTimeZone}
+                      hourCycle={hourCycle}
+                      name="startTime"
+                      shouldForceLeadingZeros={shouldForceLeadingZeros}
+                      value={state.timeRange?.start ?? null}
+                      onChange={(v) =>
+                        state.setTimeRange({
+                          end: state.timeRange?.end as TimeValue,
+                          start: v as TimeValue,
+                        })
+                      }
+                    >
+                      <TimeField.Group variant="secondary">
+                        <TimeField.Input>
+                          {(segment) => <TimeField.Segment segment={segment} />}
+                        </TimeField.Input>
+                      </TimeField.Group>
+                    </TimeField>
+                  </div>
+                  <div className="flex items-center justify-between">
+                    <Label>结束时间</Label>
+                    <TimeField
+                      aria-label="结束时间"
+                      granularity={timeGranularity}
+                      hideTimeZone={hideTimeZone}
+                      hourCycle={hourCycle}
+                      name="endTime"
+                      shouldForceLeadingZeros={shouldForceLeadingZeros}
+                      value={state.timeRange?.end ?? null}
+                      onChange={(v) =>
+                        state.setTimeRange({
+                          end: v as TimeValue,
+                          start: state.timeRange?.start as TimeValue,
+                        })
+                      }
+                    >
+                      <TimeField.Group variant="secondary">
+                        <TimeField.Input>
+                          {(segment) => <TimeField.Segment segment={segment} />}
+                        </TimeField.Input>
+                      </TimeField.Group>
+                    </TimeField>
+                  </div>
+                </div>
+              )}
+              <span className="mt-1 text-xs text-muted">
+                已选：{" "}
+                {state.value && state.value.start && state.value.end
+                  ? formatDate({end: state.value.end, start: state.value.start})
+                  : "未选择日期"}
+              </span>
+            </DateRangePicker.Popover>
+          </>
+        )}
+      </DateRangePicker>
+
+      <Separator className="my-5" />
+
+      <Label className="text-xs font-medium text-muted">格式选项</Label>
+
+      <div className="flex flex-wrap gap-4">
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            name="granularity"
+            value={granularity}
+            variant="secondary"
+            onChange={(value) => setGranularity(value as Granularity)}
+          >
+            <Label>粒度</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {granularityOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={hourCycle}
+            variant="secondary"
+            onChange={(value) => setHourCycle(Number(value) as HourCycle)}
+          >
+            <Label>小时制</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {hourCycleOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+      </div>
+
+      <div className="flex min-w-[529px] flex-col gap-2">
+        <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            隐藏时区
+          </Switch.Content>
+        </Switch>
+        <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            强制前导零
+          </Switch.Content>
+        </Switch>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/index.ts b/apps/docs/src/demos/cn/date-range-picker/index.ts
new file mode 100644
index 0000000..598deeb
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormatOptions} from "./format-options-no-ssr";
+export {FormExample} from "./form-example";
+export {InternationalCalendar} from "./international-calendar";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {WithValidation} from "./with-validation";
+export {CustomRenderFunction} from "./custom-render-function";
+export {InputContainer} from "./input-container";
diff --git a/apps/docs/src/demos/cn/date-range-picker/input-container.tsx b/apps/docs/src/demos/cn/date-range-picker/input-container.tsx
new file mode 100644
index 0000000..1456d8b
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/input-container.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+
+import {DateField, DateRangePicker, Label, RangeCalendar, TimeField} from "@heroui/react";
+import {getLocalTimeZone, parseZonedDateTime} from "@internationalized/date";
+
+export function InputContainer() {
+  const localTimeZone = getLocalTimeZone();
+
+  const defaultValue = {
+    end: parseZonedDateTime(`2026-02-10T18:45:00[${localTimeZone}]`),
+    start: parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`),
+  };
+
+  return (
+    <DateRangePicker
+      shouldForceLeadingZeros
+      className="w-full max-w-2xs min-w-80"
+      defaultValue={defaultValue}
+      granularity="second"
+      hourCycle={12}
+    >
+      {({state}) => (
+        <>
+          <Label>日期范围</Label>
+          <DateField.Group>
+            <DateField.InputContainer>
+              <DateField.Input slot="start">
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+              <DateRangePicker.RangeSeparator />
+              <DateField.Input slot="end">
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+            </DateField.InputContainer>
+            <DateField.Suffix>
+              <DateRangePicker.Trigger>
+                <DateRangePicker.TriggerIndicator />
+              </DateRangePicker.Trigger>
+            </DateField.Suffix>
+          </DateField.Group>
+          <DateRangePicker.Popover className="flex w-full flex-col gap-3">
+            <RangeCalendar aria-label="出行日期">
+              <RangeCalendar.Header>
+                <RangeCalendar.YearPickerTrigger>
+                  <RangeCalendar.YearPickerTriggerHeading />
+                  <RangeCalendar.YearPickerTriggerIndicator />
+                </RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.NavButton slot="previous" />
+                <RangeCalendar.NavButton slot="next" />
+              </RangeCalendar.Header>
+              <RangeCalendar.Grid>
+                <RangeCalendar.GridHeader>
+                  {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+                </RangeCalendar.GridHeader>
+                <RangeCalendar.GridBody>
+                  {(date) => <RangeCalendar.Cell date={date} />}
+                </RangeCalendar.GridBody>
+              </RangeCalendar.Grid>
+              <RangeCalendar.YearPickerGrid>
+                <RangeCalendar.YearPickerGridBody>
+                  {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+                </RangeCalendar.YearPickerGridBody>
+              </RangeCalendar.YearPickerGrid>
+            </RangeCalendar>
+            <div className="flex flex-col gap-3">
+              <div className="flex items-center justify-between">
+                <Label>开始时间</Label>
+                <TimeField
+                  shouldForceLeadingZeros
+                  aria-label="开始时间"
+                  granularity="second"
+                  hourCycle={12}
+                  value={state.timeRange?.start ?? null}
+                  onChange={(v) =>
+                    state.setTimeRange({
+                      end: state.timeRange?.end as TimeValue,
+                      start: v as TimeValue,
+                    })
+                  }
+                >
+                  <TimeField.Group variant="secondary">
+                    <TimeField.Input>
+                      {(segment) => <TimeField.Segment segment={segment} />}
+                    </TimeField.Input>
+                  </TimeField.Group>
+                </TimeField>
+              </div>
+              <div className="flex items-center justify-between">
+                <Label>结束时间</Label>
+                <TimeField
+                  shouldForceLeadingZeros
+                  aria-label="结束时间"
+                  granularity="second"
+                  hourCycle={12}
+                  value={state.timeRange?.end ?? null}
+                  onChange={(v) =>
+                    state.setTimeRange({
+                      end: v as TimeValue,
+                      start: state.timeRange?.start as TimeValue,
+                    })
+                  }
+                >
+                  <TimeField.Group variant="secondary">
+                    <TimeField.Input>
+                      {(segment) => <TimeField.Segment segment={segment} />}
+                    </TimeField.Input>
+                  </TimeField.Group>
+                </TimeField>
+              </div>
+            </div>
+          </DateRangePicker.Popover>
+        </>
+      )}
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/international-calendar.tsx b/apps/docs/src/demos/cn/date-range-picker/international-calendar.tsx
new file mode 100644
index 0000000..8425684
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/international-calendar.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  const start = today(getLocalTimeZone());
+
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <DateRangePicker
+        className="w-80"
+        defaultValue={{end: start.add({days: 7}), start}}
+        endName="endDate"
+        startName="startDate"
+      >
+        <Label>出行日期</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="出行日期">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/with-custom-indicator.tsx b/apps/docs/src/demos/cn/date-range-picker/with-custom-indicator.tsx
new file mode 100644
index 0000000..f5d662f
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/with-custom-indicator.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function WithCustomIndicator() {
+  return (
+    <DateRangePicker className="w-80" endName="endDate" startName="startDate">
+      <Label>出行日期</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DateRangePicker.TriggerIndicator>
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>通过传入自定义子元素替换默认日历图标。</Description>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="出行日期">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/date-range-picker/with-validation.tsx b/apps/docs/src/demos/cn/date-range-picker/with-validation.tsx
new file mode 100644
index 0000000..e1c88dd
--- /dev/null
+++ b/apps/docs/src/demos/cn/date-range-picker/with-validation.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {DateField, DateRangePicker, FieldError, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid =
+    value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+  return (
+    <DateRangePicker
+      isRequired
+      className="w-80"
+      endName="endDate"
+      isInvalid={isInvalid}
+      minValue={currentDate}
+      startName="startDate"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>预订时段</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <FieldError>请选择从今天起的有效日期范围。</FieldError>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="预订时段">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/cn/description/basic.tsx b/apps/docs/src/demos/cn/description/basic.tsx
new file mode 100644
index 0000000..37f049c
--- /dev/null
+++ b/apps/docs/src/demos/cn/description/basic.tsx
@@ -0,0 +1,17 @@
+import {Description, Input, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor="email">邮箱</Label>
+      <Input
+        aria-describedby="email-description"
+        className="w-64"
+        id="email"
+        placeholder="you@example.com"
+        type="email"
+      />
+      <Description id="email-description">我们不会将你的邮箱分享给任何人。</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/description/index.ts b/apps/docs/src/demos/cn/description/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/cn/description/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/cn/disclosure-group/basic.tsx b/apps/docs/src/demos/cn/disclosure-group/basic.tsx
new file mode 100644
index 0000000..cb1ff60
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure-group/basic.tsx
@@ -0,0 +1,88 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure, DisclosureGroup, Separator} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+export function Basic() {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 bg-transparent p-4">
+        <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="预览 HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <QrCode />
+                  预览 HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。
+                </p>
+                <img
+                  alt="Expo Go 二维码"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">设备需已安装 Expo。</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" /> 在
+                  Expo Go 预览
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="下载 HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  下载应用
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  下载 HeroUI Native 应用，即可在设备上直接体验我们的移动端组件。
+                </p>
+                <img
+                  alt="App Store 二维码"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">支持 iOS 和 Android 设备。</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/disclosure-group/controlled.tsx b/apps/docs/src/demos/cn/disclosure-group/controlled.tsx
new file mode 100644
index 0000000..ef71e3c
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure-group/controlled.tsx
@@ -0,0 +1,124 @@
+"use client";
+
+import {ChevronDown, ChevronUp, QrCode} from "@gravity-ui/icons";
+import {
+  Button,
+  Disclosure,
+  DisclosureGroup,
+  Separator,
+  useDisclosureGroupNavigation,
+} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+export function Controlled() {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+  const itemIds = ["preview", "download"]; // Track our disclosure items
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 rounded-3xl p-4">
+        <div className="mb-2 flex items-center justify-between">
+          <h3 className="text-lg font-semibold">HeroUI Native</h3>
+          <div className="flex gap-2">
+            <Button
+              aria-label="上一个折叠项"
+              isDisabled={isPrevDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onPrevious}
+            >
+              <ChevronUp className="size-4" />
+            </Button>
+            <Button
+              aria-label="下一个折叠项"
+              isDisabled={isNextDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onNext}
+            >
+              <ChevronDown className="size-4" />
+            </Button>
+          </div>
+        </div>
+        <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="预览 HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <QrCode />
+                  预览 HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。
+                </p>
+                <img
+                  alt="Expo Go 二维码"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">设备需已安装 Expo。</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />在 Expo
+                  Go 预览
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="下载 HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  下载 HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。
+                </p>
+                <img
+                  alt="Expo Go 二维码"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">设备需已安装 Expo。</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" />在 App Store 下载
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/disclosure-group/index.ts b/apps/docs/src/demos/cn/disclosure-group/index.ts
new file mode 100644
index 0000000..3c16102
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure-group/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
diff --git a/apps/docs/src/demos/cn/disclosure/basic.tsx b/apps/docs/src/demos/cn/disclosure/basic.tsx
new file mode 100644
index 0000000..baecede
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure/basic.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+
+export function Basic() {
+  const [isExpanded, setIsExpanded] = React.useState(true);
+
+  return (
+    <div className="w-full max-w-md text-center">
+      <Disclosure isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
+        <Disclosure.Heading>
+          <Button slot="trigger" variant="secondary">
+            <QrCode />
+            预览 HeroUI Native
+            <Disclosure.Indicator />
+          </Button>
+        </Disclosure.Heading>
+        <Disclosure.Content>
+          <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center">
+            <p className="text-sm text-muted">
+              使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。
+            </p>
+            <img
+              alt="Expo Go 二维码"
+              className="aspect-square w-full max-w-54 object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+            />
+            <p className="text-sm text-muted">设备需已安装 Expo。</p>
+            <Button className="mt-4" variant="primary">
+              <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载
+            </Button>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/disclosure/custom-render-function.tsx b/apps/docs/src/demos/cn/disclosure/custom-render-function.tsx
new file mode 100644
index 0000000..5de98d0
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure/custom-render-function.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+
+export function CustomRenderFunction() {
+  const [isExpanded, setIsExpanded] = React.useState(true);
+
+  return (
+    <div className="w-full max-w-md text-center">
+      <Disclosure
+        isExpanded={isExpanded}
+        render={(props) => <div {...props} data-custom="foo" />}
+        onExpandedChange={setIsExpanded}
+      >
+        <Disclosure.Heading>
+          <Button slot="trigger" variant="secondary">
+            <QrCode />
+            预览 HeroUI Native
+            <Disclosure.Indicator />
+          </Button>
+        </Disclosure.Heading>
+        <Disclosure.Content render={(props) => <div data-custom="bar" {...props} />}>
+          <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center">
+            <p className="text-sm text-muted">
+              使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。
+            </p>
+            <img
+              alt="Expo Go 二维码"
+              className="aspect-square w-full max-w-54 object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+            />
+            <p className="text-sm text-muted">设备需已安装 Expo。</p>
+            <Button className="mt-4" variant="primary">
+              <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载
+            </Button>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/disclosure/index.ts b/apps/docs/src/demos/cn/disclosure/index.ts
new file mode 100644
index 0000000..9b0b4e7
--- /dev/null
+++ b/apps/docs/src/demos/cn/disclosure/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/drawer/backdrop-variants.tsx b/apps/docs/src/demos/cn/drawer/backdrop-variants.tsx
new file mode 100644
index 0000000..e5d4c2c
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/backdrop-variants.tsx
@@ -0,0 +1,42 @@
+import {Button, Drawer} from "@heroui/react";
+
+const VARIANT_LABELS = {
+  blur: "模糊",
+  opaque: "不透明",
+  transparent: "透明",
+} as const;
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Drawer key={variant}>
+          <Button variant="secondary">{VARIANT_LABELS[variant]}</Button>
+          <Drawer.Backdrop variant={variant}>
+            <Drawer.Content>
+              <Drawer.Dialog>
+                <Drawer.Handle />
+                <Drawer.CloseTrigger />
+                <Drawer.Header>
+                  <Drawer.Heading>背景：{VARIANT_LABELS[variant]}</Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    此抽屉使用 <code>{variant}</code> 背景变体。
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button className="w-full" slot="close">
+                    关闭
+                  </Button>
+                </Drawer.Footer>
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/basic.tsx b/apps/docs/src/demos/cn/drawer/basic.tsx
new file mode 100644
index 0000000..4b1a31f
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/basic.tsx
@@ -0,0 +1,30 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Drawer>
+      <Button variant="secondary">打开抽屉</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>抽屉标题</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>
+                这是一个基于 React Aria Modal 组件构建的抽屉。它会从屏幕边缘滑入，并通过流畅的 CSS
+                过渡呈现动画效果。
+              </p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                取消
+              </Button>
+              <Button slot="close">确认</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/controlled.tsx b/apps/docs/src/demos/cn/drawer/controlled.tsx
new file mode 100644
index 0000000..ff46042
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/controlled.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import {Button, Drawer, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 React 的 <code className="text-foreground">useState</code>{" "}
+          管理抽屉开关，适合简单场景。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              打开抽屉
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <Drawer.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Drawer.Content placement="right">
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>由 useState() 控制</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>
+                <p>
+                  该抽屉由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "}
+                  <code>onOpenChange</code> 传入即可在外部管理状态。
+                </p>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Button slot="close" variant="secondary">
+                  关闭
+                </Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "}
+          <code>open()</code>、<code>close()</code>、<code>toggle()</code> 等方法。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              打开抽屉
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <Drawer.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <Drawer.Content placement="right">
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>由 useOverlayState() 控制</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>
+                <p>
+                  <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "}
+                  <code>state.open()</code>、<code>state.close()</code> 或{" "}
+                  <code>state.toggle()</code> 即可。
+                </p>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Button slot="close" variant="secondary">
+                  关闭
+                </Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/index.ts b/apps/docs/src/demos/cn/drawer/index.ts
new file mode 100644
index 0000000..be7de18
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/index.ts
@@ -0,0 +1,8 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Navigation} from "./navigation";
+export {NonDismissable} from "./non-dismissable";
+export {Placements} from "./placements";
+export {ScrollableContent} from "./scrollable-content";
+export {WithForm} from "./with-form";
diff --git a/apps/docs/src/demos/cn/drawer/navigation.tsx b/apps/docs/src/demos/cn/drawer/navigation.tsx
new file mode 100644
index 0000000..0603577
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/navigation.tsx
@@ -0,0 +1,48 @@
+import type {ComponentType, SVGProps} from "react";
+
+import {Bars, Bell, Envelope, Gear, House, Magnifier, Person} from "@gravity-ui/icons";
+import {Button, Drawer} from "@heroui/react";
+
+export function Navigation() {
+  const navItems: {icon: ComponentType<SVGProps<SVGSVGElement>>; label: string}[] = [
+    {icon: House, label: "首页"},
+    {icon: Magnifier, label: "搜索"},
+    {icon: Bell, label: "通知"},
+    {icon: Envelope, label: "消息"},
+    {icon: Person, label: "个人资料"},
+    {icon: Gear, label: "设置"},
+  ];
+
+  return (
+    <Drawer>
+      <Button variant="secondary">
+        <Bars />
+        菜单
+      </Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="left">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>导航</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <nav className="flex flex-col gap-1">
+                {navItems.map((item) => (
+                  <button
+                    key={item.label}
+                    className="flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm text-foreground transition-colors hover:bg-default"
+                    type="button"
+                  >
+                    <item.icon className="size-5 text-muted" />
+                    {item.label}
+                  </button>
+                ))}
+              </nav>
+            </Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/non-dismissable.tsx b/apps/docs/src/demos/cn/drawer/non-dismissable.tsx
new file mode 100644
index 0000000..da5c772
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/non-dismissable.tsx
@@ -0,0 +1,27 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function NonDismissable() {
+  return (
+    <Drawer>
+      <Button variant="secondary">重要操作</Button>
+      <Drawer.Backdrop isDismissable={false}>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>确认操作</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>此抽屉无法通过点击外部或拖拽关闭。你必须使用下方按钮之一来完成操作。</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                取消
+              </Button>
+              <Button slot="close">确认</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/placements.tsx b/apps/docs/src/demos/cn/drawer/placements.tsx
new file mode 100644
index 0000000..1a753c7
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/placements.tsx
@@ -0,0 +1,45 @@
+import {Button, Drawer} from "@heroui/react";
+
+const PLACEMENT_LABELS = {
+  bottom: "底部",
+  left: "左侧",
+  right: "右侧",
+  top: "顶部",
+} as const;
+
+export function Placements() {
+  const placements = ["bottom", "top", "left", "right"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Drawer key={placement}>
+          <Button variant="secondary">{PLACEMENT_LABELS[placement]}</Button>
+          <Drawer.Backdrop>
+            <Drawer.Content placement={placement}>
+              <Drawer.Dialog>
+                <Drawer.CloseTrigger />
+                {placement === "bottom" && <Drawer.Handle />}
+                <Drawer.Header>
+                  <Drawer.Heading>{PLACEMENT_LABELS[placement]}抽屉</Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    此抽屉从屏幕<strong>{PLACEMENT_LABELS[placement]}</strong>边缘滑入。
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button slot="close" variant="secondary">
+                    取消
+                  </Button>
+                  <Button slot="close">完成</Button>
+                </Drawer.Footer>
+                {placement === "top" && <Drawer.Handle />}
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/scrollable-content.tsx b/apps/docs/src/demos/cn/drawer/scrollable-content.tsx
new file mode 100644
index 0000000..67e40ad
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/scrollable-content.tsx
@@ -0,0 +1,35 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function ScrollableContent() {
+  return (
+    <Drawer>
+      <Button variant="secondary">条款与条件</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Handle />
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>条款与条件</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              {Array.from({length: 20}).map((_, i) => (
+                <p key={i} className="mb-3">
+                  段落 {i + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                  pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit
+                  risus, sed porttitor quam.
+                </p>
+              ))}
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                拒绝
+              </Button>
+              <Button slot="close">接受</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/drawer/with-form.tsx b/apps/docs/src/demos/cn/drawer/with-form.tsx
new file mode 100644
index 0000000..78a6486
--- /dev/null
+++ b/apps/docs/src/demos/cn/drawer/with-form.tsx
@@ -0,0 +1,41 @@
+import {Button, Drawer, Input, Label, TextField} from "@heroui/react";
+
+export function WithForm() {
+  return (
+    <Drawer>
+      <Button variant="secondary">编辑资料</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>编辑资料</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <form className="flex flex-col gap-4">
+                <TextField className="w-full" name="name" type="text">
+                  <Label>姓名</Label>
+                  <Input placeholder="输入你的姓名" variant="secondary" />
+                </TextField>
+                <TextField className="w-full" name="email" type="email">
+                  <Label>邮箱</Label>
+                  <Input placeholder="输入你的邮箱" variant="secondary" />
+                </TextField>
+                <TextField className="w-full" name="bio">
+                  <Label>简介</Label>
+                  <Input placeholder="介绍一下你自己" variant="secondary" />
+                </TextField>
+              </form>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                取消
+              </Button>
+              <Button slot="close">保存更改</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/controlled-open-state.tsx b/apps/docs/src/demos/cn/dropdown/controlled-open-state.tsx
new file mode 100644
index 0000000..0f00151
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/controlled-open-state.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
+      <p className="text-sm text-muted">
+        下拉菜单：<strong>{open ? "打开" : "关闭"}</strong>
+      </p>
+      <Dropdown isOpen={open} onOpenChange={setOpen}>
+        <Button aria-label="菜单" variant="secondary">
+          操作
+        </Button>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="new-file" textValue="新建文件">
+              <Label>新建文件</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="open-file" textValue="打开文件">
+              <Label>打开文件</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="save-file" textValue="保存文件">
+              <Label>保存文件</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+              <Label>删除文件</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/controlled.tsx b/apps/docs/src/demos/cn/dropdown/controlled.tsx
new file mode 100644
index 0000000..23aafab
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/controlled.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState<Selection>(new Set(["bold"]));
+
+  const selectedItems = Array.from(selected);
+
+  return (
+    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
+      <p className="text-sm text-muted">
+        已选：{selectedItems.length > 0 ? selectedItems.join("、") : "无"}
+      </p>
+      <Dropdown>
+        <Button aria-label="菜单" variant="secondary">
+          操作
+        </Button>
+        <Dropdown.Popover>
+          <Dropdown.Menu
+            selectedKeys={selected}
+            selectionMode="multiple"
+            onSelectionChange={setSelected}
+          >
+            <Dropdown.Item id="bold" textValue="粗体">
+              <Label>粗体</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+            <Dropdown.Item id="italic" textValue="斜体">
+              <Label>斜体</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+            <Dropdown.Item id="underline" textValue="下划线">
+              <Label>下划线</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/custom-trigger.tsx b/apps/docs/src/demos/cn/dropdown/custom-trigger.tsx
new file mode 100644
index 0000000..3cbe195
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/custom-trigger.tsx
@@ -0,0 +1,61 @@
+import {ArrowRightFromSquare, Gear, Persons} from "@gravity-ui/icons";
+import {Avatar, Dropdown, Label} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger className="rounded-full">
+        <Avatar>
+          <Avatar.Image
+            alt="Junior Garcia"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+          />
+          <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+        </Avatar>
+      </Dropdown.Trigger>
+      <Dropdown.Popover>
+        <div className="px-3 pt-3 pb-1">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Jane"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+              />
+              <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col gap-0">
+              <p className="text-sm leading-5 font-medium">Jane Doe</p>
+              <p className="text-xs leading-none text-muted">jane@example.com</p>
+            </div>
+          </div>
+        </div>
+        <Dropdown.Menu>
+          <Dropdown.Item id="dashboard" textValue="仪表盘">
+            <Label>仪表盘</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="profile" textValue="个人资料">
+            <Label>个人资料</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="settings" textValue="设置">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>设置</Label>
+              <Gear className="size-3.5 text-muted" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="new-project" textValue="新建项目">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>创建团队</Label>
+              <Persons className="size-3.5 text-muted" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="logout" textValue="退出登录" variant="danger">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>退出登录</Label>
+              <ArrowRightFromSquare className="size-3.5 text-danger" />
+            </div>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/default.tsx b/apps/docs/src/demos/cn/dropdown/default.tsx
new file mode 100644
index 0000000..e3cf98d
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/default.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        操作
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="新建文件">
+            <Label>新建文件</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy-link" textValue="复制链接">
+            <Label>复制链接</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="edit-file" textValue="编辑文件">
+            <Label>编辑文件</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+            <Label>删除文件</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/index.ts b/apps/docs/src/demos/cn/dropdown/index.ts
new file mode 100644
index 0000000..da609a1
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/index.ts
@@ -0,0 +1,17 @@
+// Dropdown demos
+export {Controlled} from "./controlled";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {LongPressTrigger} from "./long-press-trigger";
+export {SingleWithCustomIndicator} from "./single-with-custom-indicator";
+export {WithDescriptions} from "./with-descriptions";
+export {WithDisabledItems} from "./with-disabled-items";
+export {WithIcons} from "./with-icons";
+export {WithKeyboardShortcuts} from "./with-keyboard-shortcuts";
+export {WithMultipleSelection} from "./with-multiple-selection";
+export {WithSectionLevelSelection} from "./with-section-level-selection";
+export {WithSections} from "./with-sections";
+export {WithSingleSelection} from "./with-single-selection";
+export {WithSubmenus} from "./with-submenus";
+export {WithCustomSubmenuIndicator} from "./with-custom-submenu-indicator";
diff --git a/apps/docs/src/demos/cn/dropdown/long-press-trigger.tsx b/apps/docs/src/demos/cn/dropdown/long-press-trigger.tsx
new file mode 100644
index 0000000..9e3e96e
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/long-press-trigger.tsx
@@ -0,0 +1,27 @@
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function LongPressTrigger() {
+  return (
+    <Dropdown trigger="longPress">
+      <Button aria-label="菜单" variant="secondary">
+        长按
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="new-file" textValue="新建文件">
+            <Label>新建文件</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="打开文件">
+            <Label>打开文件</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="保存文件">
+            <Label>保存文件</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+            <Label>删除文件</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/single-with-custom-indicator.tsx b/apps/docs/src/demos/cn/dropdown/single-with-custom-indicator.tsx
new file mode 100644
index 0000000..46027a8
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/single-with-custom-indicator.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function SingleWithCustomIndicator() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  const CustomCheckmarkIcon = (
+    <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+      <path
+        className="text-accent"
+        clipRule="evenodd"
+        d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m3.1-8.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        水果
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="single"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>选择水果</Header>
+            <Dropdown.Item id="apple" textValue="苹果">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>苹果</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="香蕉">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>香蕉</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="樱桃">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>樱桃</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="橙子">
+            <Dropdown.ItemIndicator>
+              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+            </Dropdown.ItemIndicator>
+            <Label>橙子</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="梨">
+            <Dropdown.ItemIndicator>
+              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+            </Dropdown.ItemIndicator>
+            <Label>梨</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-custom-submenu-indicator.tsx b/apps/docs/src/demos/cn/dropdown/with-custom-submenu-indicator.tsx
new file mode 100644
index 0000000..707fb00
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-custom-submenu-indicator.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {ArrowRight} from "@gravity-ui/icons";
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function WithCustomSubmenuIndicator() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        分享
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="复制链接">
+            <Label>复制链接</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="分享">
+              <Label>更多选项</Label>
+              <Dropdown.SubmenuIndicator>
+                <ArrowRight className="size-3.5 text-muted" />
+              </Dropdown.SubmenuIndicator>
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="邮件">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator>
+                      <svg
+                        className="size-3.5 text-muted"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth="2"
+                        viewBox="0 0 24 24"
+                      >
+                        <path d="M9 18l6-6-6-6" />
+                      </svg>
+                    </Dropdown.SubmenuIndicator>
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="工作邮箱">
+                        <Label>工作邮箱</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="个人邮箱">
+                        <Label>个人邮箱</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="other" textValue="其他">
+              <Label>其他（默认指示器）</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="sms" textValue="SMS">
+                  <Label>SMS</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-descriptions.tsx b/apps/docs/src/demos/cn/dropdown/with-descriptions.tsx
new file mode 100644
index 0000000..5ca5b09
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-descriptions.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithDescriptions() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        操作
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="新建文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>新建文件</Label>
+              <Description>创建新文件</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="打开文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <FolderOpen className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>打开文件</Label>
+              <Description>打开已有文件</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="保存文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <FloppyDisk className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>保存文件</Label>
+              <Description>保存当前文件</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>删除文件</Label>
+              <Description>移至废纸篓</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-disabled-items.tsx b/apps/docs/src/demos/cn/dropdown/with-disabled-items.tsx
new file mode 100644
index 0000000..65a3ad5
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-disabled-items.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Bars, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+
+export function WithDisabledItems() {
+  return (
+    <Dropdown>
+      <Button isIconOnly aria-label="菜单" variant="secondary">
+        <Bars className="outline-none" />
+      </Button>
+      <Dropdown.Popover className="min-w-[220px]">
+        <Dropdown.Menu
+          disabledKeys={["delete-file"]}
+          onAction={(key) => console.log(`Selected: ${key}`)}
+        >
+          <Dropdown.Section>
+            <Header>操作</Header>
+            <Dropdown.Item id="new-file" textValue="新建文件">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <SquarePlus className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>新建文件</Label>
+                <Description>创建新文件</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="编辑文件">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Pencil className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>编辑文件</Label>
+                <Description>进行修改</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>危险区域</Header>
+            <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <TrashBin className="size-4 shrink-0 text-danger" />
+              </div>
+              <div className="flex flex-col">
+                <Label>删除文件</Label>
+                <Description>移至废纸篓</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-icons.tsx b/apps/docs/src/demos/cn/dropdown/with-icons.tsx
new file mode 100644
index 0000000..7817903
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-icons.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        操作
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="新建文件">
+            <SquarePlus className="size-4 shrink-0 text-muted" />
+            <Label>新建文件</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="打开文件">
+            <FolderOpen className="size-4 shrink-0 text-muted" />
+            <Label>打开文件</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="保存文件">
+            <FloppyDisk className="size-4 shrink-0 text-muted" />
+            <Label>保存文件</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+            <TrashBin className="size-4 shrink-0 text-danger" />
+            <Label>删除文件</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-keyboard-shortcuts.tsx b/apps/docs/src/demos/cn/dropdown/with-keyboard-shortcuts.tsx
new file mode 100644
index 0000000..2df4c70
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-keyboard-shortcuts.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Button, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithKeyboardShortcuts() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        操作
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new" textValue="新建">
+            <Label>新建</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open" textValue="打开">
+            <Label>打开</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save" textValue="保存">
+            <Label>保存</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete" textValue="删除" variant="danger">
+            <Label>删除</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-multiple-selection.tsx b/apps/docs/src/demos/cn/dropdown/with-multiple-selection.tsx
new file mode 100644
index 0000000..45813ff
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-multiple-selection.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function WithMultipleSelection() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        喜爱的水果
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>选择水果</Header>
+            <Dropdown.Item id="apple" textValue="苹果">
+              <Dropdown.ItemIndicator />
+              <Label>苹果</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="香蕉">
+              <Dropdown.ItemIndicator />
+              <Label>香蕉</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="樱桃">
+              <Dropdown.ItemIndicator />
+              <Label>樱桃</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="橙子">
+            <Dropdown.ItemIndicator />
+            <Label>橙子</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="梨">
+            <Dropdown.ItemIndicator />
+            <Label>梨</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-section-level-selection.tsx b/apps/docs/src/demos/cn/dropdown/with-section-level-selection.tsx
new file mode 100644
index 0000000..96a6a56
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-section-level-selection.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSectionLevelSelection() {
+  const [textStyles, setTextStyles] = useState<Selection>(new Set(["bold", "italic"]));
+  const [textAlignment, setTextAlignment] = useState<Selection>(new Set(["left"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        样式
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu>
+          <Dropdown.Section>
+            <Header>操作</Header>
+            <Dropdown.Item id="cut" textValue="剪切">
+              <Label>剪切</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>X</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="copy" textValue="复制">
+              <Label>复制</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>C</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="paste" textValue="粘贴">
+              <Label>粘贴</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>U</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section
+            selectedKeys={textStyles}
+            selectionMode="multiple"
+            onSelectionChange={setTextStyles}
+          >
+            <Header>文本样式</Header>
+            <Dropdown.Item id="bold" textValue="粗体">
+              <Dropdown.ItemIndicator />
+              <Label>粗体</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>B</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="italic" textValue="斜体">
+              <Dropdown.ItemIndicator />
+              <Label>斜体</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>I</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="underline" textValue="下划线">
+              <Dropdown.ItemIndicator />
+              <Label>下划线</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>U</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section
+            selectedKeys={textAlignment}
+            selectionMode="single"
+            onSelectionChange={setTextAlignment}
+          >
+            <Header>文本对齐</Header>
+            <Dropdown.Item id="left" textValue="左对齐">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>左对齐</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>A</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="center" textValue="居中">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>居中</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>H</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="right" textValue="右对齐">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>右对齐</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-sections.tsx b/apps/docs/src/demos/cn/dropdown/with-sections.tsx
new file mode 100644
index 0000000..4e275b7
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-sections.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import {EllipsisVertical, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Dropdown>
+      <Button isIconOnly aria-label="菜单" variant="secondary">
+        <EllipsisVertical className="outline-none" />
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Section>
+            <Header>操作</Header>
+            <Dropdown.Item id="new-file" textValue="新建文件">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <SquarePlus className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>新建文件</Label>
+                <Description>创建新文件</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="编辑文件">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Pencil className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>编辑文件</Label>
+                <Description>进行修改</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>危险区域</Header>
+            <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <TrashBin className="size-4 shrink-0 text-danger" />
+              </div>
+              <div className="flex flex-col">
+                <Label>删除文件</Label>
+                <Description>移至废纸篓</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-single-selection.tsx b/apps/docs/src/demos/cn/dropdown/with-single-selection.tsx
new file mode 100644
index 0000000..7678dde
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-single-selection.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSingleSelection() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        水果
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="single"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>选择水果</Header>
+            <Dropdown.Item id="apple" textValue="苹果">
+              <Dropdown.ItemIndicator />
+              <Label>苹果</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="香蕉">
+              <Dropdown.ItemIndicator />
+              <Label>香蕉</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="樱桃">
+              <Dropdown.ItemIndicator />
+              <Label>樱桃</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="橙子">
+            <Dropdown.ItemIndicator />
+            <Label>橙子</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="梨">
+            <Dropdown.ItemIndicator />
+            <Label>梨</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/dropdown/with-submenus.tsx b/apps/docs/src/demos/cn/dropdown/with-submenus.tsx
new file mode 100644
index 0000000..5c321b3
--- /dev/null
+++ b/apps/docs/src/demos/cn/dropdown/with-submenus.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function WithSubmenus() {
+  return (
+    <Dropdown>
+      <Button aria-label="菜单" variant="secondary">
+        分享
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="复制链接">
+            <Label>复制链接</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="twitter" textValue="Twitter">
+            <Label>X / Twitter</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="分享">
+              <Label>其他</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="邮件">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator />
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="工作邮箱">
+                        <Label>工作邮箱</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="个人邮箱">
+                        <Label>个人邮箱</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/cn/error-message/basic.tsx b/apps/docs/src/demos/cn/error-message/basic.tsx
new file mode 100644
index 0000000..0b6392c
--- /dev/null
+++ b/apps/docs/src/demos/cn/error-message/basic.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function ErrorMessageBasic() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>必选分类</Label>
+      <TagGroup.List>
+        <Tag id="news">新闻</Tag>
+        <Tag id="travel">旅游</Tag>
+        <Tag id="gaming">游戏</Tag>
+        <Tag id="shopping">购物</Tag>
+      </TagGroup.List>
+      <Description>请至少选择一个分类</Description>
+      <ErrorMessage>{!!isInvalid && <>请至少选择一个分类</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/error-message/index.ts b/apps/docs/src/demos/cn/error-message/index.ts
new file mode 100644
index 0000000..3229bf4
--- /dev/null
+++ b/apps/docs/src/demos/cn/error-message/index.ts
@@ -0,0 +1,2 @@
+export {ErrorMessageBasic as Basic} from "./basic";
+export {ErrorMessageWithTagGroup as WithTagGroup} from "./with-tag-group";
diff --git a/apps/docs/src/demos/cn/error-message/with-tag-group.tsx b/apps/docs/src/demos/cn/error-message/with-tag-group.tsx
new file mode 100644
index 0000000..3aa142c
--- /dev/null
+++ b/apps/docs/src/demos/cn/error-message/with-tag-group.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function ErrorMessageWithTagGroup() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>必选分类</Label>
+      <TagGroup.List>
+        <Tag id="news">新闻</Tag>
+        <Tag id="travel">旅游</Tag>
+        <Tag id="gaming">游戏</Tag>
+        <Tag id="shopping">购物</Tag>
+      </TagGroup.List>
+      <Description>请至少选择一个分类</Description>
+      <ErrorMessage>{!!isInvalid && <>请至少选择一个分类</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/field-error/basic.tsx b/apps/docs/src/demos/cn/field-error/basic.tsx
new file mode 100644
index 0000000..b0eb2ae
--- /dev/null
+++ b/apps/docs/src/demos/cn/field-error/basic.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+export function Basic() {
+  const [value, setValue] = useState("jr");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <TextField className="w-64" isInvalid={isInvalid}>
+      <Label htmlFor="username">用户名</Label>
+      <Input
+        id="username"
+        placeholder="输入用户名"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <FieldError>用户名至少需要 3 个字符</FieldError>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/field-error/index.ts b/apps/docs/src/demos/cn/field-error/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/cn/field-error/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/cn/fieldset/basic.tsx b/apps/docs/src/demos/cn/fieldset/basic.tsx
new file mode 100644
index 0000000..f787cdd
--- /dev/null
+++ b/apps/docs/src/demos/cn/fieldset/basic.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {FloppyDisk} from "@gravity-ui/icons";
+import {
+  Button,
+  Description,
+  FieldError,
+  FieldGroup,
+  Fieldset,
+  Form,
+  Input,
+  Label,
+  TextArea,
+  TextField,
+} from "@heroui/react";
+
+export function Basic() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Form className="w-full max-w-96" onSubmit={onSubmit}>
+      <Fieldset>
+        <Fieldset.Legend>个人资料设置</Fieldset.Legend>
+        <Description>更新你的个人资料信息。</Description>
+        <FieldGroup>
+          <TextField
+            isRequired
+            name="name"
+            validate={(value) => {
+              if (value.length < 3) {
+                return "姓名至少需要 3 个字符";
+              }
+
+              return null;
+            }}
+          >
+            <Label>姓名</Label>
+            <Input placeholder="John Doe" />
+            <FieldError />
+          </TextField>
+          <TextField isRequired name="email" type="email">
+            <Label>邮箱</Label>
+            <Input placeholder="john@example.com" />
+            <FieldError />
+          </TextField>
+          <TextField
+            isRequired
+            name="bio"
+            validate={(value) => {
+              if (value.length < 10) {
+                return "简介至少需要 10 个字符";
+              }
+
+              return null;
+            }}
+          >
+            <Label>简介</Label>
+            <TextArea placeholder="介绍一下你自己…" />
+            <Description>至少 10 个字符</Description>
+            <FieldError />
+          </TextField>
+        </FieldGroup>
+        <Fieldset.Actions>
+          <Button type="submit">
+            <FloppyDisk />
+            保存更改
+          </Button>
+          <Button type="reset" variant="secondary">
+            取消
+          </Button>
+        </Fieldset.Actions>
+      </Fieldset>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/fieldset/index.ts b/apps/docs/src/demos/cn/fieldset/index.ts
new file mode 100644
index 0000000..f7305ac
--- /dev/null
+++ b/apps/docs/src/demos/cn/fieldset/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {OnSurface} from "./on-surface";
diff --git a/apps/docs/src/demos/cn/fieldset/on-surface.tsx b/apps/docs/src/demos/cn/fieldset/on-surface.tsx
new file mode 100644
index 0000000..12552c8
--- /dev/null
+++ b/apps/docs/src/demos/cn/fieldset/on-surface.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import {FloppyDisk} from "@gravity-ui/icons";
+import {
+  Button,
+  Description,
+  FieldError,
+  Fieldset,
+  Form,
+  Input,
+  Label,
+  Surface,
+  TextArea,
+  TextField,
+} from "@heroui/react";
+import React from "react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <div className="flex items-center justify-center rounded-3xl bg-surface p-6">
+      <Surface className="w-full min-w-[380px]">
+        <Form onSubmit={onSubmit}>
+          <Fieldset className="w-full">
+            <Fieldset.Legend>个人资料设置</Fieldset.Legend>
+            <Description>更新你的个人资料信息。</Description>
+            <Fieldset.Group>
+              <TextField
+                isRequired
+                name="name"
+                validate={(value) => {
+                  if (value.length < 3) {
+                    return "姓名至少需要 3 个字符";
+                  }
+
+                  return null;
+                }}
+              >
+                <Label>姓名</Label>
+                <Input placeholder="John Doe" variant="secondary" />
+                <FieldError />
+              </TextField>
+              <TextField isRequired name="email" type="email">
+                <Label>邮箱</Label>
+                <Input placeholder="john@example.com" variant="secondary" />
+                <FieldError />
+              </TextField>
+              <TextField
+                isRequired
+                name="bio"
+                validate={(value) => {
+                  if (value.length < 10) {
+                    return "简介至少需要 10 个字符";
+                  }
+
+                  return null;
+                }}
+              >
+                <Label>简介</Label>
+                <TextArea placeholder="介绍一下你自己…" variant="secondary" />
+                <Description>至少 10 个字符</Description>
+                <FieldError />
+              </TextField>
+            </Fieldset.Group>
+            <Fieldset.Actions>
+              <Button type="submit">
+                <FloppyDisk />
+                保存更改
+              </Button>
+              <Button type="reset" variant="tertiary">
+                取消
+              </Button>
+            </Fieldset.Actions>
+          </Fieldset>
+        </Form>
+      </Surface>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/form/basic.tsx b/apps/docs/src/demos/cn/form/basic.tsx
new file mode 100644
index 0000000..4d77f02
--- /dev/null
+++ b/apps/docs/src/demos/cn/form/basic.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";
+
+export function Basic() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert(`表单提交数据：${JSON.stringify(data, null, 2)}`);
+  };
+
+  return (
+    <Form className="flex w-96 flex-col gap-4" onSubmit={onSubmit}>
+      <TextField
+        isRequired
+        name="email"
+        type="email"
+        validate={(value) => {
+          if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+            return "请输入有效的邮箱地址";
+          }
+
+          return null;
+        }}
+      >
+        <Label>邮箱</Label>
+        <Input placeholder="john@example.com" />
+        <FieldError />
+      </TextField>
+
+      <TextField
+        isRequired
+        minLength={8}
+        name="password"
+        type="password"
+        validate={(value) => {
+          if (value.length < 8) {
+            return "密码至少需要 8 个字符";
+          }
+          if (!/[A-Z]/.test(value)) {
+            return "密码至少需要包含一个大写字母";
+          }
+          if (!/[0-9]/.test(value)) {
+            return "密码至少需要包含一个数字";
+          }
+
+          return null;
+        }}
+      >
+        <Label>密码</Label>
+        <Input placeholder="输入密码" />
+        <Description>至少 8 个字符，且包含 1 个大写字母和 1 个数字</Description>
+        <FieldError />
+      </TextField>
+
+      <div className="flex gap-2">
+        <Button type="submit">
+          <Check />
+          提交
+        </Button>
+        <Button type="reset" variant="secondary">
+          重置
+        </Button>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/form/custom-render-function.tsx b/apps/docs/src/demos/cn/form/custom-render-function.tsx
new file mode 100644
index 0000000..166e6f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/form/custom-render-function.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert(`表单提交数据：${JSON.stringify(data, null, 2)}`);
+  };
+
+  return (
+    <Form
+      className="flex w-96 flex-col gap-4"
+      render={(props) => <form {...props} data-custom="foo" />}
+      onSubmit={onSubmit}
+    >
+      <TextField
+        isRequired
+        name="email"
+        type="email"
+        validate={(value) => {
+          if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+            return "请输入有效的邮箱地址";
+          }
+
+          return null;
+        }}
+      >
+        <Label>邮箱</Label>
+        <Input placeholder="john@example.com" />
+        <FieldError />
+      </TextField>
+
+      <TextField
+        isRequired
+        minLength={8}
+        name="password"
+        type="password"
+        validate={(value) => {
+          if (value.length < 8) {
+            return "密码至少需要 8 个字符";
+          }
+          if (!/[A-Z]/.test(value)) {
+            return "密码至少需要包含一个大写字母";
+          }
+          if (!/[0-9]/.test(value)) {
+            return "密码至少需要包含一个数字";
+          }
+
+          return null;
+        }}
+      >
+        <Label>密码</Label>
+        <Input placeholder="输入密码" />
+        <Description>至少 8 个字符，且包含 1 个大写字母和 1 个数字</Description>
+        <FieldError />
+      </TextField>
+
+      <div className="flex gap-2">
+        <Button type="submit">
+          <Check />
+          提交
+        </Button>
+        <Button type="reset" variant="secondary">
+          重置
+        </Button>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/form/index.ts b/apps/docs/src/demos/cn/form/index.ts
new file mode 100644
index 0000000..9b0b4e7
--- /dev/null
+++ b/apps/docs/src/demos/cn/form/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/index.ts b/apps/docs/src/demos/cn/index.ts
new file mode 100644
index 0000000..4f32d7c
--- /dev/null
+++ b/apps/docs/src/demos/cn/index.ts
@@ -0,0 +1,2541 @@
+/* eslint-disable sort-keys, sort-keys-fix/sort-keys-fix */
+import type {DemoItem} from "@/demos";
+
+// Registry mapping demo names to their components
+export const demos: Record<string, DemoItem> = {
+  // Accordion demos
+  "accordion-basic": {
+    loader: () => import("./accordion/basic").then((m) => m.Basic),
+    file: "cn/accordion/basic.tsx",
+  },
+  "accordion-surface": {
+    loader: () => import("./accordion/surface").then((m) => m.Surface),
+    file: "cn/accordion/surface.tsx",
+  },
+  "accordion-multiple": {
+    loader: () => import("./accordion/multiple").then((m) => m.Multiple),
+    file: "cn/accordion/multiple.tsx",
+  },
+  "accordion-disabled": {
+    loader: () => import("./accordion/disabled").then((m) => m.Disabled),
+    file: "cn/accordion/disabled.tsx",
+  },
+  "accordion-custom-indicator": {
+    loader: () => import("./accordion/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/accordion/custom-indicator.tsx",
+  },
+  "accordion-faq": {
+    loader: () => import("./accordion/faq").then((m) => m.FAQ),
+    file: "cn/accordion/faq.tsx",
+  },
+  "accordion-custom-styles": {
+    loader: () => import("./accordion/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/accordion/custom-styles.tsx",
+  },
+  "accordion-without-separator": {
+    loader: () => import("./accordion/without-separator").then((m) => m.WithoutSeparator),
+    file: "cn/accordion/without-separator.tsx",
+  },
+  "accordion-custom-render-function": {
+    loader: () => import("./accordion/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/accordion/custom-render-function.tsx",
+  },
+  "accordion-controlled": {
+    loader: () => import("./accordion/controlled").then((m) => m.Controlled),
+    file: "cn/accordion/controlled.tsx",
+  },
+  // Alert demos
+  "alert-basic": {
+    loader: () => import("./alert/basic").then((m) => m.Basic),
+    file: "cn/alert/basic.tsx",
+  },
+  // AlertDialog demos
+  "alert-dialog-default": {
+    loader: () => import("./alert-dialog/default").then((m) => m.Default),
+    file: "cn/alert-dialog/default.tsx",
+  },
+  "alert-dialog-statuses": {
+    loader: () => import("./alert-dialog/statuses").then((m) => m.Statuses),
+    file: "cn/alert-dialog/statuses.tsx",
+  },
+  "alert-dialog-placements": {
+    loader: () => import("./alert-dialog/placements").then((m) => m.Placements),
+    file: "cn/alert-dialog/placements.tsx",
+  },
+  "alert-dialog-backdrop-variants": {
+    loader: () => import("./alert-dialog/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "cn/alert-dialog/backdrop-variants.tsx",
+  },
+  "alert-dialog-sizes": {
+    loader: () => import("./alert-dialog/sizes").then((m) => m.Sizes),
+    file: "cn/alert-dialog/sizes.tsx",
+  },
+  "alert-dialog-controlled": {
+    loader: () => import("./alert-dialog/controlled").then((m) => m.Controlled),
+    file: "cn/alert-dialog/controlled.tsx",
+  },
+  "alert-dialog-dismiss-behavior": {
+    loader: () => import("./alert-dialog/dismiss-behavior").then((m) => m.DismissBehavior),
+    file: "cn/alert-dialog/dismiss-behavior.tsx",
+  },
+  "alert-dialog-custom-icon": {
+    loader: () => import("./alert-dialog/custom-icon").then((m) => m.CustomIcon),
+    file: "cn/alert-dialog/custom-icon.tsx",
+  },
+  "alert-dialog-custom-backdrop": {
+    loader: () => import("./alert-dialog/custom-backdrop").then((m) => m.CustomBackdrop),
+    file: "cn/alert-dialog/custom-backdrop.tsx",
+  },
+  "alert-dialog-custom-trigger": {
+    loader: () => import("./alert-dialog/custom-trigger").then((m) => m.CustomTrigger),
+    file: "cn/alert-dialog/custom-trigger.tsx",
+  },
+  "alert-dialog-with-close-button": {
+    loader: () => import("./alert-dialog/with-close-button").then((m) => m.WithCloseButton),
+    file: "cn/alert-dialog/with-close-button.tsx",
+  },
+  "alert-dialog-custom-animations": {
+    loader: () => import("./alert-dialog/custom-animations").then((m) => m.CustomAnimations),
+    file: "cn/alert-dialog/custom-animations.tsx",
+  },
+  "alert-dialog-close-methods": {
+    loader: () => import("./alert-dialog/close-methods").then((m) => m.CloseMethods),
+    file: "cn/alert-dialog/close-methods.tsx",
+  },
+  "alert-dialog-custom-portal": {
+    loader: () => import("./alert-dialog/custom-portal").then((m) => m.CustomPortal),
+    file: "cn/alert-dialog/custom-portal.tsx",
+  },
+  // Avatar demos
+  "avatar-basic": {
+    loader: () => import("./avatar/basic").then((m) => m.Basic),
+    file: "cn/avatar/basic.tsx",
+  },
+  "avatar-sizes": {
+    loader: () => import("./avatar/sizes").then((m) => m.Sizes),
+    file: "cn/avatar/sizes.tsx",
+  },
+  "avatar-colors": {
+    loader: () => import("./avatar/colors").then((m) => m.Colors),
+    file: "cn/avatar/colors.tsx",
+  },
+  "avatar-variants": {
+    loader: () => import("./avatar/variants").then((m) => m.Variants),
+    file: "cn/avatar/variants.tsx",
+  },
+  "avatar-fallback": {
+    loader: () => import("./avatar/fallback").then((m) => m.Fallback),
+    file: "cn/avatar/fallback.tsx",
+  },
+  "avatar-group": {
+    loader: () => import("./avatar/group").then((m) => m.Group),
+    file: "cn/avatar/group.tsx",
+  },
+  "avatar-custom-styles": {
+    loader: () => import("./avatar/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/avatar/custom-styles.tsx",
+  },
+  // Badge demos
+  "badge-basic": {
+    loader: () => import("./badge/basic").then((m) => m.BadgeBasic),
+    file: "cn/badge/basic.tsx",
+  },
+  "badge-colors": {
+    loader: () => import("./badge/colors").then((m) => m.BadgeColors),
+    file: "cn/badge/colors.tsx",
+  },
+  "badge-sizes": {
+    loader: () => import("./badge/sizes").then((m) => m.BadgeSizes),
+    file: "cn/badge/sizes.tsx",
+  },
+  "badge-variants": {
+    loader: () => import("./badge/variants").then((m) => m.BadgeVariants),
+    file: "cn/badge/variants.tsx",
+  },
+  "badge-placements": {
+    loader: () => import("./badge/placements").then((m) => m.BadgePlacements),
+    file: "cn/badge/placements.tsx",
+  },
+  "badge-with-content": {
+    loader: () => import("./badge/with-content").then((m) => m.BadgeWithContent),
+    file: "cn/badge/with-content.tsx",
+  },
+  "badge-dot": {
+    loader: () => import("./badge/dot").then((m) => m.BadgeDot),
+    file: "cn/badge/dot.tsx",
+  },
+  // Breadcrumbs demos
+  "breadcrumbs-basic": {
+    loader: () => import("./breadcrumbs/basic").then((m) => m.default),
+    file: "cn/breadcrumbs/basic.tsx",
+  },
+  "breadcrumbs-level-2": {
+    loader: () => import("./breadcrumbs/level-2").then((m) => m.default),
+    file: "cn/breadcrumbs/level-2.tsx",
+  },
+  "breadcrumbs-level-3": {
+    loader: () => import("./breadcrumbs/level-3").then((m) => m.default),
+    file: "cn/breadcrumbs/level-3.tsx",
+  },
+  "breadcrumbs-custom-separator": {
+    loader: () => import("./breadcrumbs/custom-separator").then((m) => m.default),
+    file: "cn/breadcrumbs/custom-separator.tsx",
+  },
+  "breadcrumbs-disabled": {
+    loader: () => import("./breadcrumbs/disabled").then((m) => m.default),
+    file: "cn/breadcrumbs/disabled.tsx",
+  },
+  "breadcrumbs-custom-render-function": {
+    loader: () =>
+      import("./breadcrumbs/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/breadcrumbs/custom-render-function.tsx",
+  },
+  // Button demos
+  "button-basic": {
+    loader: () => import("./button/basic").then((m) => m.Basic),
+    file: "cn/button/basic.tsx",
+  },
+  "button-custom-variants": {
+    loader: () => import("./button/custom-variants").then((m) => m.CustomVariants),
+    file: "cn/button/custom-variants.tsx",
+  },
+  "button-disabled": {
+    loader: () => import("./button/disabled").then((m) => m.Disabled),
+    file: "cn/button/disabled.tsx",
+  },
+  "button-icon-only": {
+    loader: () => import("./button/icon-only").then((m) => m.IconOnly),
+    file: "cn/button/icon-only.tsx",
+  },
+  "button-loading": {
+    loader: () => import("./button/loading").then((m) => m.Loading),
+    file: "cn/button/loading.tsx",
+  },
+  "button-loading-state": {
+    loader: () => import("./button/loading-state").then((m) => m.LoadingState),
+    file: "cn/button/loading-state.tsx",
+  },
+  "button-sizes": {
+    loader: () => import("./button/sizes").then((m) => m.Sizes),
+    file: "cn/button/sizes.tsx",
+  },
+  "button-full-width": {
+    loader: () => import("./button/full-width").then((m) => m.FullWidth),
+    file: "cn/button/full-width.tsx",
+  },
+  "button-social": {
+    loader: () => import("./button/social").then((m) => m.Social),
+    file: "cn/button/social.tsx",
+  },
+  "button-ripple-effect": {
+    loader: () => import("./button/ripple-effect").then((m) => m.RippleEffect),
+    file: "cn/button/ripple-effect.tsx",
+  },
+  "button-variants": {
+    loader: () => import("./button/variants").then((m) => m.Variants),
+    file: "cn/button/variants.tsx",
+  },
+  "button-outline-variant": {
+    loader: () => import("./button/outline-variant").then((m) => m.OutlineVariant),
+    file: "cn/button/outline-variant.tsx",
+  },
+  "button-with-icons": {
+    loader: () => import("./button/with-icons").then((m) => m.WithIcons),
+    file: "cn/button/with-icons.tsx",
+  },
+  "button-custom-render-function": {
+    loader: () => import("./button/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/button/custom-render-function.tsx",
+  },
+  // ButtonGroup demos
+  "button-group-basic": {
+    loader: () => import("./button-group/basic").then((m) => m.Basic),
+    file: "cn/button-group/basic.tsx",
+  },
+  "button-group-disabled": {
+    loader: () => import("./button-group/disabled").then((m) => m.Disabled),
+    file: "cn/button-group/disabled.tsx",
+  },
+  "button-group-sizes": {
+    loader: () => import("./button-group/sizes").then((m) => m.Sizes),
+    file: "cn/button-group/sizes.tsx",
+  },
+  "button-group-full-width": {
+    loader: () => import("./button-group/full-width").then((m) => m.FullWidth),
+    file: "cn/button-group/full-width.tsx",
+  },
+  "button-group-variants": {
+    loader: () => import("./button-group/variants").then((m) => m.Variants),
+    file: "cn/button-group/variants.tsx",
+  },
+  "button-group-with-icons": {
+    loader: () => import("./button-group/with-icons").then((m) => m.WithIcons),
+    file: "cn/button-group/with-icons.tsx",
+  },
+  "button-group-orientation": {
+    loader: () => import("./button-group/orientation").then((m) => m.Orientation),
+    file: "cn/button-group/orientation.tsx",
+  },
+  "button-group-without-separator": {
+    loader: () => import("./button-group/without-separator").then((m) => m.WithoutSeparator),
+    file: "cn/button-group/without-separator.tsx",
+  },
+  // Card demos
+  "card-default": {
+    loader: () => import("./card/default").then((m) => m.Default),
+    file: "cn/card/default.tsx",
+  },
+  "card-horizontal": {
+    loader: () => import("./card/horizontal").then((m) => m.Horizontal),
+    file: "cn/card/horizontal.tsx",
+  },
+  "card-variants": {
+    loader: () => import("./card/variants").then((m) => m.Variants),
+    file: "cn/card/variants.tsx",
+  },
+  "card-with-avatar": {
+    loader: () => import("./card/with-avatar").then((m) => m.WithAvatar),
+    file: "cn/card/with-avatar.tsx",
+  },
+  "card-with-form": {
+    loader: () => import("./card/with-form").then((m) => m.WithForm),
+    file: "cn/card/with-form.tsx",
+  },
+  "card-with-images": {
+    loader: () => import("./card/with-images").then((m) => m.WithImages),
+    file: "cn/card/with-images.tsx",
+  },
+  // Calendar demos
+  "calendar-basic": {
+    loader: () => import("./calendar/basic").then((m) => m.Basic),
+    file: "cn/calendar/basic.tsx",
+  },
+  "calendar-custom-styles": {
+    loader: () => import("./calendar/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/calendar/custom-styles.tsx",
+  },
+  "calendar-default-value": {
+    loader: () => import("./calendar/default-value").then((m) => m.DefaultValue),
+    file: "cn/calendar/default-value.tsx",
+  },
+  "calendar-controlled": {
+    loader: () => import("./calendar/controlled").then((m) => m.Controlled),
+    file: "cn/calendar/controlled.tsx",
+  },
+  "calendar-min-max-dates": {
+    loader: () => import("./calendar/min-max-dates").then((m) => m.MinMaxDates),
+    file: "cn/calendar/min-max-dates.tsx",
+  },
+  "calendar-unavailable-dates": {
+    loader: () => import("./calendar/unavailable-dates").then((m) => m.UnavailableDates),
+    file: "cn/calendar/unavailable-dates.tsx",
+  },
+  "calendar-weeks-in-month": {
+    loader: () => import("./calendar/weeks-in-month").then((m) => m.WeeksInMonth),
+    file: "cn/calendar/weeks-in-month.tsx",
+  },
+  "calendar-week-view": {
+    loader: () => import("./calendar/week-view").then((m) => m.WeekView),
+    file: "cn/calendar/week-view.tsx",
+  },
+  "calendar-day-view": {
+    loader: () => import("./calendar/day-view").then((m) => m.DayView),
+    file: "cn/calendar/day-view.tsx",
+  },
+  "calendar-multiple-selection": {
+    loader: () => import("./calendar/multiple-selection").then((m) => m.MultipleSelection),
+    file: "cn/calendar/multiple-selection.tsx",
+  },
+  "calendar-disabled": {
+    loader: () => import("./calendar/disabled").then((m) => m.Disabled),
+    file: "cn/calendar/disabled.tsx",
+  },
+  "calendar-read-only": {
+    loader: () => import("./calendar/read-only").then((m) => m.ReadOnly),
+    file: "cn/calendar/read-only.tsx",
+  },
+  "calendar-focused-value": {
+    loader: () => import("./calendar/focused-value").then((m) => m.FocusedValue),
+    file: "cn/calendar/focused-value.tsx",
+  },
+  "calendar-with-indicators": {
+    loader: () => import("./calendar/with-indicators").then((m) => m.WithIndicators),
+    file: "cn/calendar/with-indicators.tsx",
+  },
+  "calendar-multiple-months": {
+    loader: () => import("./calendar/multiple-months").then((m) => m.MultipleMonths),
+    file: "cn/calendar/multiple-months.tsx",
+  },
+  "calendar-year-picker": {
+    loader: () => import("./calendar/year-picker").then((m) => m.YearPicker),
+    file: "cn/calendar/year-picker.tsx",
+  },
+  "calendar-international-calendar": {
+    loader: () => import("./calendar/international-calendar").then((m) => m.InternationalCalendar),
+    file: "cn/calendar/international-calendar.tsx",
+  },
+  "calendar-booking-calendar": {
+    loader: () => import("./calendar/booking-calendar").then((m) => m.BookingCalendar),
+    file: "cn/calendar/booking-calendar.tsx",
+  },
+  "calendar-custom-icons": {
+    loader: () => import("./calendar/custom-icons").then((m) => m.CustomIcons),
+    file: "cn/calendar/custom-icons.tsx",
+  },
+  // RangeCalendar demos
+  "range-calendar-basic": {
+    loader: () => import("./range-calendar/basic").then((m) => m.Basic),
+    file: "cn/range-calendar/basic.tsx",
+  },
+  "range-calendar-year-picker": {
+    loader: () => import("./range-calendar/year-picker").then((m) => m.YearPicker),
+    file: "cn/range-calendar/year-picker.tsx",
+  },
+  "range-calendar-default-value": {
+    loader: () => import("./range-calendar/default-value").then((m) => m.DefaultValue),
+    file: "cn/range-calendar/default-value.tsx",
+  },
+  "range-calendar-controlled": {
+    loader: () => import("./range-calendar/controlled").then((m) => m.Controlled),
+    file: "cn/range-calendar/controlled.tsx",
+  },
+  "range-calendar-min-max-dates": {
+    loader: () => import("./range-calendar/min-max-dates").then((m) => m.MinMaxDates),
+    file: "cn/range-calendar/min-max-dates.tsx",
+  },
+  "range-calendar-unavailable-dates": {
+    loader: () => import("./range-calendar/unavailable-dates").then((m) => m.UnavailableDates),
+    file: "cn/range-calendar/unavailable-dates.tsx",
+  },
+  "range-calendar-anchor-unavailable-dates": {
+    loader: () =>
+      import("./range-calendar/anchor-unavailable-dates").then((m) => m.AnchorUnavailableDates),
+    file: "cn/range-calendar/anchor-unavailable-dates.tsx",
+  },
+  "range-calendar-weeks-in-month": {
+    loader: () => import("./range-calendar/weeks-in-month").then((m) => m.WeeksInMonth),
+    file: "cn/range-calendar/weeks-in-month.tsx",
+  },
+  "range-calendar-week-view": {
+    loader: () => import("./range-calendar/week-view").then((m) => m.WeekView),
+    file: "cn/range-calendar/week-view.tsx",
+  },
+  "range-calendar-day-view": {
+    loader: () => import("./range-calendar/day-view").then((m) => m.DayView),
+    file: "cn/range-calendar/day-view.tsx",
+  },
+  "range-calendar-allows-non-contiguous-ranges": {
+    loader: () =>
+      import("./range-calendar/allows-non-contiguous-ranges").then(
+        (m) => m.AllowsNonContiguousRanges,
+      ),
+    file: "cn/range-calendar/allows-non-contiguous-ranges.tsx",
+  },
+  "range-calendar-disabled": {
+    loader: () => import("./range-calendar/disabled").then((m) => m.Disabled),
+    file: "cn/range-calendar/disabled.tsx",
+  },
+  "range-calendar-read-only": {
+    loader: () => import("./range-calendar/read-only").then((m) => m.ReadOnly),
+    file: "cn/range-calendar/read-only.tsx",
+  },
+  "range-calendar-invalid": {
+    loader: () => import("./range-calendar/invalid").then((m) => m.Invalid),
+    file: "cn/range-calendar/invalid.tsx",
+  },
+  "range-calendar-focused-value": {
+    loader: () => import("./range-calendar/focused-value").then((m) => m.FocusedValue),
+    file: "cn/range-calendar/focused-value.tsx",
+  },
+  "range-calendar-with-indicators": {
+    loader: () => import("./range-calendar/with-indicators").then((m) => m.WithIndicators),
+    file: "cn/range-calendar/with-indicators.tsx",
+  },
+  "range-calendar-multiple-months": {
+    loader: () => import("./range-calendar/multiple-months").then((m) => m.MultipleMonths),
+    file: "cn/range-calendar/multiple-months.tsx",
+  },
+  "range-calendar-three-months": {
+    loader: () => import("./range-calendar/three-months").then((m) => m.ThreeMonths),
+    file: "cn/range-calendar/three-months.tsx",
+  },
+  "range-calendar-international-calendar": {
+    loader: () =>
+      import("./range-calendar/international-calendar").then((m) => m.InternationalCalendar),
+    file: "cn/range-calendar/international-calendar.tsx",
+  },
+  "range-calendar-booking-calendar": {
+    loader: () => import("./range-calendar/booking-calendar").then((m) => m.BookingCalendar),
+    file: "cn/range-calendar/booking-calendar.tsx",
+  },
+  // Checkbox demos
+  "checkbox-basic": {
+    loader: () => import("./checkbox/basic").then((m) => m.Basic),
+    file: "cn/checkbox/basic.tsx",
+  },
+  "checkbox-disabled": {
+    loader: () => import("./checkbox/disabled").then((m) => m.Disabled),
+    file: "cn/checkbox/disabled.tsx",
+  },
+  "checkbox-default-selected": {
+    loader: () => import("./checkbox/default-selected").then((m) => m.DefaultSelected),
+    file: "cn/checkbox/default-selected.tsx",
+  },
+  "checkbox-controlled": {
+    loader: () => import("./checkbox/controlled").then((m) => m.Controlled),
+    file: "cn/checkbox/controlled.tsx",
+  },
+  "checkbox-indeterminate": {
+    loader: () => import("./checkbox/indeterminate").then((m) => m.Indeterminate),
+    file: "cn/checkbox/indeterminate.tsx",
+  },
+  "checkbox-external-label": {
+    loader: () => import("./checkbox/external-label").then((m) => m.ExternalLabel),
+    file: "cn/checkbox/external-label.tsx",
+  },
+  "checkbox-with-description": {
+    loader: () => import("./checkbox/with-description").then((m) => m.WithDescription),
+    file: "cn/checkbox/with-description.tsx",
+  },
+  "checkbox-render-props": {
+    loader: () => import("./checkbox/render-props").then((m) => m.RenderProps),
+    file: "cn/checkbox/render-props.tsx",
+  },
+  "checkbox-form": {
+    loader: () => import("./checkbox/form").then((m) => m.Form),
+    file: "cn/checkbox/form.tsx",
+  },
+  "checkbox-custom-styles": {
+    loader: () => import("./checkbox/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/checkbox/custom-styles.tsx",
+  },
+  "checkbox-invalid": {
+    loader: () => import("./checkbox/invalid").then((m) => m.Invalid),
+    file: "cn/checkbox/invalid.tsx",
+  },
+  "checkbox-custom-indicator": {
+    loader: () => import("./checkbox/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/checkbox/custom-indicator.tsx",
+  },
+  "checkbox-full-rounded": {
+    loader: () => import("./checkbox/full-rounded").then((m) => m.FullRounded),
+    file: "cn/checkbox/full-rounded.tsx",
+  },
+  "checkbox-variants": {
+    loader: () => import("./checkbox/variants").then((m) => m.Variants),
+    file: "cn/checkbox/variants.tsx",
+  },
+  "checkbox-custom-render-function": {
+    loader: () => import("./checkbox/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/checkbox/custom-render-function.tsx",
+  },
+  // CheckboxGroup demos
+  "checkbox-group-basic": {
+    loader: () => import("./checkbox-group/basic").then((m) => m.Basic),
+    file: "cn/checkbox-group/basic.tsx",
+  },
+  "checkbox-group-on-surface": {
+    loader: () => import("./checkbox-group/on-surface").then((m) => m.OnSurface),
+    file: "cn/checkbox-group/on-surface.tsx",
+  },
+  "checkbox-group-with-custom-indicator": {
+    loader: () =>
+      import("./checkbox-group/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "cn/checkbox-group/with-custom-indicator.tsx",
+  },
+  "checkbox-group-indeterminate": {
+    loader: () => import("./checkbox-group/indeterminate").then((m) => m.Indeterminate),
+    file: "cn/checkbox-group/indeterminate.tsx",
+  },
+  "checkbox-group-validation": {
+    loader: () => import("./checkbox-group/validation").then((m) => m.Validation),
+    file: "cn/checkbox-group/validation.tsx",
+  },
+  "checkbox-group-controlled": {
+    loader: () => import("./checkbox-group/controlled").then((m) => m.Controlled),
+    file: "cn/checkbox-group/controlled.tsx",
+  },
+  "checkbox-group-disabled": {
+    loader: () => import("./checkbox-group/disabled").then((m) => m.Disabled),
+    file: "cn/checkbox-group/disabled.tsx",
+  },
+  "checkbox-group-features-and-addons": {
+    loader: () => import("./checkbox-group/features-and-addons").then((m) => m.FeaturesAndAddOns),
+    file: "cn/checkbox-group/features-and-addons.tsx",
+  },
+  "checkbox-group-custom-render-function": {
+    loader: () =>
+      import("./checkbox-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/checkbox-group/custom-render-function.tsx",
+  },
+  // Chip demos
+  "chip-basic": {
+    loader: () => import("./chip/basic").then((m) => m.ChipBasic),
+    file: "cn/chip/basic.tsx",
+  },
+  "chip-variants": {
+    loader: () => import("./chip/variants").then((m) => m.ChipVariants),
+    file: "cn/chip/variants.tsx",
+  },
+  "chip-with-icon": {
+    loader: () => import("./chip/with-icon").then((m) => m.ChipWithIcon),
+    file: "cn/chip/with-icon.tsx",
+  },
+  "chip-statuses": {
+    loader: () => import("./chip/statuses").then((m) => m.ChipStatuses),
+    file: "cn/chip/statuses.tsx",
+  },
+  "chip-vibrant-palette": {
+    loader: () => import("./chip/vibrant-palette").then((m) => m.ChipVibrantPalette),
+    file: "cn/chip/vibrant-palette.tsx",
+  },
+  // ColorField demos
+  "color-field-basic": {
+    loader: () => import("./color-field/basic").then((m) => m.Basic),
+    file: "cn/color-field/basic.tsx",
+  },
+  "color-field-channel-editing": {
+    loader: () => import("./color-field/channel-editing").then((m) => m.ChannelEditing),
+    file: "cn/color-field/channel-editing.tsx",
+  },
+  "color-field-controlled": {
+    loader: () => import("./color-field/controlled").then((m) => m.Controlled),
+    file: "cn/color-field/controlled.tsx",
+  },
+  "color-field-disabled": {
+    loader: () => import("./color-field/disabled").then((m) => m.Disabled),
+    file: "cn/color-field/disabled.tsx",
+  },
+  "color-field-form-example": {
+    loader: () => import("./color-field/form-example").then((m) => m.FormExample),
+    file: "cn/color-field/form-example.tsx",
+  },
+  "color-field-full-width": {
+    loader: () => import("./color-field/full-width").then((m) => m.FullWidth),
+    file: "cn/color-field/full-width.tsx",
+  },
+  "color-field-invalid": {
+    loader: () => import("./color-field/invalid").then((m) => m.Invalid),
+    file: "cn/color-field/invalid.tsx",
+  },
+  "color-field-on-surface": {
+    loader: () => import("./color-field/on-surface").then((m) => m.OnSurface),
+    file: "cn/color-field/on-surface.tsx",
+  },
+  "color-field-required": {
+    loader: () => import("./color-field/required").then((m) => m.Required),
+    file: "cn/color-field/required.tsx",
+  },
+  "color-field-variants": {
+    loader: () => import("./color-field/variants").then((m) => m.Variants),
+    file: "cn/color-field/variants.tsx",
+  },
+  "color-field-with-description": {
+    loader: () => import("./color-field/with-description").then((m) => m.WithDescription),
+    file: "cn/color-field/with-description.tsx",
+  },
+  "color-field-custom-render-function": {
+    loader: () =>
+      import("./color-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/color-field/custom-render-function.tsx",
+  },
+  // ColorPicker demos
+  "color-picker-basic": {
+    loader: () => import("./color-picker/basic").then((m) => m.Basic),
+    file: "cn/color-picker/basic.tsx",
+  },
+  "color-picker-controlled": {
+    loader: () => import("./color-picker/controlled").then((m) => m.Controlled),
+    file: "cn/color-picker/controlled.tsx",
+  },
+  "color-picker-with-swatches": {
+    loader: () => import("./color-picker/with-swatches").then((m) => m.WithSwatches),
+    file: "cn/color-picker/with-swatches.tsx",
+  },
+  "color-picker-with-fields": {
+    loader: () => import("./color-picker/with-fields").then((m) => m.WithFields),
+    file: "cn/color-picker/with-fields.tsx",
+  },
+  "color-picker-with-sliders": {
+    loader: () => import("./color-picker/with-sliders").then((m) => m.WithSliders),
+    file: "cn/color-picker/with-sliders.tsx",
+  },
+  // ColorArea demos
+  "color-area-basic": {
+    loader: () => import("./color-area/basic").then((m) => m.ColorAreaBasic),
+    file: "cn/color-area/basic.tsx",
+  },
+  "color-area-with-dots": {
+    loader: () => import("./color-area/with-dots").then((m) => m.ColorAreaWithDots),
+    file: "cn/color-area/with-dots.tsx",
+  },
+  "color-area-space-and-channels": {
+    loader: () =>
+      import("./color-area/space-and-channels").then((m) => m.ColorAreaSpaceAndChannels),
+    file: "cn/color-area/space-and-channels.tsx",
+  },
+  "color-area-controlled": {
+    loader: () => import("./color-area/controlled").then((m) => m.ColorAreaControlled),
+    file: "cn/color-area/controlled.tsx",
+  },
+  "color-area-disabled": {
+    loader: () => import("./color-area/disabled").then((m) => m.ColorAreaDisabled),
+    file: "cn/color-area/disabled.tsx",
+  },
+  "color-area-custom-render-function": {
+    loader: () => import("./color-area/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/color-area/custom-render-function.tsx",
+  },
+  // ColorSwatch demos
+  "color-swatch-basic": {
+    loader: () => import("./color-swatch/basic").then((m) => m.ColorSwatchBasic),
+    file: "cn/color-swatch/basic.tsx",
+  },
+  "color-swatch-sizes": {
+    loader: () => import("./color-swatch/sizes").then((m) => m.ColorSwatchSizes),
+    file: "cn/color-swatch/sizes.tsx",
+  },
+  "color-swatch-shapes": {
+    loader: () => import("./color-swatch/shapes").then((m) => m.ColorSwatchShapes),
+    file: "cn/color-swatch/shapes.tsx",
+  },
+  "color-swatch-transparency": {
+    loader: () => import("./color-swatch/transparency").then((m) => m.ColorSwatchTransparency),
+    file: "cn/color-swatch/transparency.tsx",
+  },
+  "color-swatch-custom-styles": {
+    loader: () => import("./color-swatch/custom-styles").then((m) => m.ColorSwatchCustomStyles),
+    file: "cn/color-swatch/custom-styles.tsx",
+  },
+  "color-swatch-accessibility": {
+    loader: () => import("./color-swatch/accessibility").then((m) => m.ColorSwatchAccessibility),
+    file: "cn/color-swatch/accessibility.tsx",
+  },
+  "color-swatch-custom-render-function": {
+    loader: () =>
+      import("./color-swatch/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/color-swatch/custom-render-function.tsx",
+  },
+  // ColorSlider demos
+  "color-slider-basic": {
+    loader: () => import("./color-slider/basic").then((m) => m.Basic),
+    file: "cn/color-slider/basic.tsx",
+  },
+  "color-slider-channels": {
+    loader: () => import("./color-slider/channels").then((m) => m.Channels),
+    file: "cn/color-slider/channels.tsx",
+  },
+  "color-slider-alpha-channel": {
+    loader: () => import("./color-slider/alpha-channel").then((m) => m.AlphaChannel),
+    file: "cn/color-slider/alpha-channel.tsx",
+  },
+  "color-slider-rgb-channels": {
+    loader: () => import("./color-slider/rgb-channels").then((m) => m.RGBChannels),
+    file: "cn/color-slider/rgb-channels.tsx",
+  },
+  "color-slider-vertical": {
+    loader: () => import("./color-slider/vertical").then((m) => m.Vertical),
+    file: "cn/color-slider/vertical.tsx",
+  },
+  "color-slider-disabled": {
+    loader: () => import("./color-slider/disabled").then((m) => m.Disabled),
+    file: "cn/color-slider/disabled.tsx",
+  },
+  "color-slider-controlled": {
+    loader: () => import("./color-slider/controlled").then((m) => m.Controlled),
+    file: "cn/color-slider/controlled.tsx",
+  },
+  "color-slider-custom-render-function": {
+    loader: () =>
+      import("./color-slider/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/color-slider/custom-render-function.tsx",
+  },
+  // CloseButton demos
+  "close-button-default": {
+    loader: () => import("./close-button/default").then((m) => m.Default),
+    file: "cn/close-button/default.tsx",
+  },
+  "close-button-with-custom-icon": {
+    loader: () => import("./close-button/with-custom-icon").then((m) => m.WithCustomIcon),
+    file: "cn/close-button/with-custom-icon.tsx",
+  },
+  "close-button-interactive": {
+    loader: () => import("./close-button/interactive").then((m) => m.Interactive),
+    file: "cn/close-button/interactive.tsx",
+  },
+  // ColorSwatchPicker demos
+  "color-swatch-picker-basic": {
+    loader: () => import("./color-swatch-picker/basic").then((m) => m.Basic),
+    file: "cn/color-swatch-picker/basic.tsx",
+  },
+  "color-swatch-picker-sizes": {
+    loader: () => import("./color-swatch-picker/sizes").then((m) => m.Sizes),
+    file: "cn/color-swatch-picker/sizes.tsx",
+  },
+  "color-swatch-picker-variants": {
+    loader: () => import("./color-swatch-picker/variants").then((m) => m.Variants),
+    file: "cn/color-swatch-picker/variants.tsx",
+  },
+  "color-swatch-picker-stack-layout": {
+    loader: () => import("./color-swatch-picker/stack-layout").then((m) => m.StackLayout),
+    file: "cn/color-swatch-picker/stack-layout.tsx",
+  },
+  "color-swatch-picker-controlled": {
+    loader: () => import("./color-swatch-picker/controlled").then((m) => m.Controlled),
+    file: "cn/color-swatch-picker/controlled.tsx",
+  },
+  "color-swatch-picker-disabled": {
+    loader: () => import("./color-swatch-picker/disabled").then((m) => m.Disabled),
+    file: "cn/color-swatch-picker/disabled.tsx",
+  },
+  "color-swatch-picker-default-value": {
+    loader: () => import("./color-swatch-picker/default-value").then((m) => m.DefaultValue),
+    file: "cn/color-swatch-picker/default-value.tsx",
+  },
+  "color-swatch-picker-custom-indicator": {
+    loader: () => import("./color-swatch-picker/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/color-swatch-picker/custom-indicator.tsx",
+  },
+  "color-swatch-picker-custom-render-function": {
+    loader: () =>
+      import("./color-swatch-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/color-swatch-picker/custom-render-function.tsx",
+  },
+  // Autocomplete demos
+  "autocomplete-default": {
+    loader: () => import("./autocomplete/default").then((m) => m.default),
+    file: "cn/autocomplete/default.tsx",
+  },
+  "autocomplete-single-select": {
+    loader: () => import("./autocomplete/single-select").then((m) => m.default),
+    file: "cn/autocomplete/single-select.tsx",
+  },
+  "autocomplete-variants": {
+    loader: () => import("./autocomplete/variants").then((m) => m.Variants),
+    file: "cn/autocomplete/variants.tsx",
+  },
+  "autocomplete-multiple-select": {
+    loader: () => import("./autocomplete/multiple-select").then((m) => m.MultipleSelect),
+    file: "cn/autocomplete/multiple-select.tsx",
+  },
+  "autocomplete-full-width": {
+    loader: () => import("./autocomplete/full-width").then((m) => m.FullWidth),
+    file: "cn/autocomplete/full-width.tsx",
+  },
+  "autocomplete-with-description": {
+    loader: () => import("./autocomplete/with-description").then((m) => m.WithDescription),
+    file: "cn/autocomplete/with-description.tsx",
+  },
+  "autocomplete-with-sections": {
+    loader: () => import("./autocomplete/with-sections").then((m) => m.WithSections),
+    file: "cn/autocomplete/with-sections.tsx",
+  },
+  "autocomplete-with-disabled-options": {
+    loader: () => import("./autocomplete/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "cn/autocomplete/with-disabled-options.tsx",
+  },
+  "autocomplete-allows-empty-collection": {
+    loader: () =>
+      import("./autocomplete/allows-empty-collection").then((m) => m.AllowsEmptyCollection),
+    file: "cn/autocomplete/allows-empty-collection.tsx",
+  },
+  "autocomplete-custom-indicator": {
+    loader: () => import("./autocomplete/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/autocomplete/custom-indicator.tsx",
+  },
+  "autocomplete-required": {
+    loader: () => import("./autocomplete/required").then((m) => m.Required),
+    file: "cn/autocomplete/required.tsx",
+  },
+  "autocomplete-controlled": {
+    loader: () => import("./autocomplete/controlled").then((m) => m.Controlled),
+    file: "cn/autocomplete/controlled.tsx",
+  },
+  "autocomplete-controlled-open-state": {
+    loader: () => import("./autocomplete/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "cn/autocomplete/controlled-open-state.tsx",
+  },
+  "autocomplete-asynchronous-filtering": {
+    loader: () =>
+      import("./autocomplete/asynchronous-filtering").then((m) => m.AsynchronousFiltering),
+    file: "cn/autocomplete/asynchronous-filtering.tsx",
+  },
+  "autocomplete-virtualization": {
+    loader: () => import("./autocomplete/virtualization").then((m) => m.Virtualization),
+    file: "cn/autocomplete/virtualization.tsx",
+  },
+  "autocomplete-disabled": {
+    loader: () => import("./autocomplete/disabled").then((m) => m.Disabled),
+    file: "cn/autocomplete/disabled.tsx",
+  },
+  "autocomplete-user-selection": {
+    loader: () => import("./autocomplete/user-selection").then((m) => m.UserSelection),
+    file: "cn/autocomplete/user-selection.tsx",
+  },
+  "autocomplete-user-selection-multiple": {
+    loader: () =>
+      import("./autocomplete/user-selection-multiple").then((m) => m.UserSelectionMultiple),
+    file: "cn/autocomplete/user-selection-multiple.tsx",
+  },
+  "autocomplete-location-search": {
+    loader: () => import("./autocomplete/location-search").then((m) => m.LocationSearch),
+    file: "cn/autocomplete/location-search.tsx",
+  },
+  "autocomplete-tag-group-selection": {
+    loader: () => import("./autocomplete/tag-group-selection").then((m) => m.TagGroupSelection),
+    file: "cn/autocomplete/tag-group-selection.tsx",
+  },
+  "autocomplete-email-recipients": {
+    loader: () => import("./autocomplete/email-recipients").then((m) => m.EmailRecipients),
+    file: "cn/autocomplete/email-recipients.tsx",
+  },
+  // ComboBox demos
+  "combo-box-default": {
+    loader: () => import("./combo-box/default").then((m) => m.Default),
+    file: "cn/combo-box/default.tsx",
+  },
+  "combo-box-default-selected-key": {
+    loader: () => import("./combo-box/default-selected-key").then((m) => m.DefaultSelectedKey),
+    file: "cn/combo-box/default-selected-key.tsx",
+  },
+  "combo-box-with-description": {
+    loader: () => import("./combo-box/with-description").then((m) => m.WithDescription),
+    file: "cn/combo-box/with-description.tsx",
+  },
+  "combo-box-with-sections": {
+    loader: () => import("./combo-box/with-sections").then((m) => m.WithSections),
+    file: "cn/combo-box/with-sections.tsx",
+  },
+  "combo-box-with-disabled-options": {
+    loader: () => import("./combo-box/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "cn/combo-box/with-disabled-options.tsx",
+  },
+  "combo-box-custom-indicator": {
+    loader: () => import("./combo-box/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/combo-box/custom-indicator.tsx",
+  },
+  "combo-box-required": {
+    loader: () => import("./combo-box/required").then((m) => m.Required),
+    file: "cn/combo-box/required.tsx",
+  },
+  "combo-box-full-width": {
+    loader: () => import("./combo-box/full-width").then((m) => m.FullWidth),
+    file: "cn/combo-box/full-width.tsx",
+  },
+  "combo-box-custom-value": {
+    loader: () => import("./combo-box/custom-value").then((m) => m.CustomValue),
+    file: "cn/combo-box/custom-value.tsx",
+  },
+  "combo-box-controlled": {
+    loader: () => import("./combo-box/controlled").then((m) => m.Controlled),
+    file: "cn/combo-box/controlled.tsx",
+  },
+  "combo-box-controlled-input-value": {
+    loader: () => import("./combo-box/controlled-input-value").then((m) => m.ControlledInputValue),
+    file: "cn/combo-box/controlled-input-value.tsx",
+  },
+  "combo-box-asynchronous-loading": {
+    loader: () => import("./combo-box/asynchronous-loading").then((m) => m.AsynchronousLoading),
+    file: "cn/combo-box/asynchronous-loading.tsx",
+  },
+  "combo-box-custom-filtering": {
+    loader: () => import("./combo-box/custom-filtering").then((m) => m.CustomFiltering),
+    file: "cn/combo-box/custom-filtering.tsx",
+  },
+  "combo-box-allows-custom-value": {
+    loader: () => import("./combo-box/allows-custom-value").then((m) => m.AllowsCustomValue),
+    file: "cn/combo-box/allows-custom-value.tsx",
+  },
+  "combo-box-disabled": {
+    loader: () => import("./combo-box/disabled").then((m) => m.Disabled),
+    file: "cn/combo-box/disabled.tsx",
+  },
+  "combo-box-on-surface": {
+    loader: () => import("./combo-box/on-surface").then((m) => m.OnSurface),
+    file: "cn/combo-box/on-surface.tsx",
+  },
+  "combo-box-menu-trigger": {
+    loader: () => import("./combo-box/menu-trigger").then((m) => m.MenuTrigger),
+    file: "cn/combo-box/menu-trigger.tsx",
+  },
+  "combo-box-custom-render-function": {
+    loader: () => import("./combo-box/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/combo-box/custom-render-function.tsx",
+  },
+  // Drawer demos
+  "drawer-basic": {
+    loader: () => import("./drawer/basic").then((m) => m.Basic),
+    file: "cn/drawer/basic.tsx",
+  },
+  "drawer-placements": {
+    loader: () => import("./drawer/placements").then((m) => m.Placements),
+    file: "cn/drawer/placements.tsx",
+  },
+  "drawer-backdrop-variants": {
+    loader: () => import("./drawer/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "cn/drawer/backdrop-variants.tsx",
+  },
+  "drawer-with-form": {
+    loader: () => import("./drawer/with-form").then((m) => m.WithForm),
+    file: "cn/drawer/with-form.tsx",
+  },
+  "drawer-scrollable-content": {
+    loader: () => import("./drawer/scrollable-content").then((m) => m.ScrollableContent),
+    file: "cn/drawer/scrollable-content.tsx",
+  },
+  "drawer-navigation": {
+    loader: () => import("./drawer/navigation").then((m) => m.Navigation),
+    file: "cn/drawer/navigation.tsx",
+  },
+  "drawer-non-dismissable": {
+    loader: () => import("./drawer/non-dismissable").then((m) => m.NonDismissable),
+    file: "cn/drawer/non-dismissable.tsx",
+  },
+  "drawer-controlled": {
+    loader: () => import("./drawer/controlled").then((m) => m.Controlled),
+    file: "cn/drawer/controlled.tsx",
+  },
+  // Disclosure demos
+  "disclosure-basic": {
+    loader: () => import("./disclosure/basic").then((m) => m.Basic),
+    file: "cn/disclosure/basic.tsx",
+  },
+  "disclosure-custom-render-function": {
+    loader: () => import("./disclosure/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/disclosure/custom-render-function.tsx",
+  },
+  // DisclosureGroup demos
+  "disclosure-group-basic": {
+    loader: () => import("./disclosure-group/basic").then((m) => m.Basic),
+    file: "cn/disclosure-group/basic.tsx",
+  },
+  "disclosure-group-controlled": {
+    loader: () => import("./disclosure-group/controlled").then((m) => m.Controlled),
+    file: "cn/disclosure-group/controlled.tsx",
+  },
+  // Dropdown demos
+  "dropdown-default": {
+    loader: () => import("./dropdown/default").then((m) => m.Default),
+    file: "cn/dropdown/default.tsx",
+  },
+  "dropdown-with-single-selection": {
+    loader: () => import("./dropdown/with-single-selection").then((m) => m.WithSingleSelection),
+    file: "cn/dropdown/with-single-selection.tsx",
+  },
+  "dropdown-single-with-custom-indicator": {
+    loader: () =>
+      import("./dropdown/single-with-custom-indicator").then((m) => m.SingleWithCustomIndicator),
+    file: "cn/dropdown/single-with-custom-indicator.tsx",
+  },
+  "dropdown-with-multiple-selection": {
+    loader: () => import("./dropdown/with-multiple-selection").then((m) => m.WithMultipleSelection),
+    file: "cn/dropdown/with-multiple-selection.tsx",
+  },
+  "dropdown-with-section-level-selection": {
+    loader: () =>
+      import("./dropdown/with-section-level-selection").then((m) => m.WithSectionLevelSelection),
+    file: "cn/dropdown/with-section-level-selection.tsx",
+  },
+  "dropdown-with-keyboard-shortcuts": {
+    loader: () => import("./dropdown/with-keyboard-shortcuts").then((m) => m.WithKeyboardShortcuts),
+    file: "cn/dropdown/with-keyboard-shortcuts.tsx",
+  },
+  "dropdown-with-icons": {
+    loader: () => import("./dropdown/with-icons").then((m) => m.WithIcons),
+    file: "cn/dropdown/with-icons.tsx",
+  },
+  "dropdown-long-press-trigger": {
+    loader: () => import("./dropdown/long-press-trigger").then((m) => m.LongPressTrigger),
+    file: "cn/dropdown/long-press-trigger.tsx",
+  },
+  "dropdown-with-descriptions": {
+    loader: () => import("./dropdown/with-descriptions").then((m) => m.WithDescriptions),
+    file: "cn/dropdown/with-descriptions.tsx",
+  },
+  "dropdown-with-sections": {
+    loader: () => import("./dropdown/with-sections").then((m) => m.WithSections),
+    file: "cn/dropdown/with-sections.tsx",
+  },
+  "dropdown-with-disabled-items": {
+    loader: () => import("./dropdown/with-disabled-items").then((m) => m.WithDisabledItems),
+    file: "cn/dropdown/with-disabled-items.tsx",
+  },
+  "dropdown-with-submenus": {
+    loader: () => import("./dropdown/with-submenus").then((m) => m.WithSubmenus),
+    file: "cn/dropdown/with-submenus.tsx",
+  },
+  "dropdown-with-custom-submenu-indicator": {
+    loader: () =>
+      import("./dropdown/with-custom-submenu-indicator").then((m) => m.WithCustomSubmenuIndicator),
+    file: "cn/dropdown/with-custom-submenu-indicator.tsx",
+  },
+  "dropdown-controlled": {
+    loader: () => import("./dropdown/controlled").then((m) => m.Controlled),
+    file: "cn/dropdown/controlled.tsx",
+  },
+  "dropdown-controlled-open-state": {
+    loader: () => import("./dropdown/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "cn/dropdown/controlled-open-state.tsx",
+  },
+  "dropdown-custom-trigger": {
+    loader: () => import("./dropdown/custom-trigger").then((m) => m.CustomTrigger),
+    file: "cn/dropdown/custom-trigger.tsx",
+  },
+  // ErrorMessage demos
+  "error-message-basic": {
+    loader: () => import("./error-message/basic").then((m) => m.ErrorMessageBasic),
+    file: "cn/error-message/basic.tsx",
+  },
+  "error-message-with-tag-group": {
+    loader: () => import("./error-message/with-tag-group").then((m) => m.ErrorMessageWithTagGroup),
+    file: "cn/error-message/with-tag-group.tsx",
+  },
+  // Form demos
+  "form-basic": {
+    loader: () => import("./form/basic").then((m) => m.Basic),
+    file: "cn/form/basic.tsx",
+  },
+  "form-custom-render-function": {
+    loader: () => import("./form/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/form/custom-render-function.tsx",
+  },
+  // Fieldset demos
+  "fieldset-basic": {
+    loader: () => import("./fieldset/basic").then((m) => m.Basic),
+    file: "cn/fieldset/basic.tsx",
+  },
+  "fieldset-on-surface": {
+    loader: () => import("./fieldset/on-surface").then((m) => m.OnSurface),
+    file: "cn/fieldset/on-surface.tsx",
+  },
+  // Input demos
+  "input-basic": {
+    loader: () => import("./input/basic").then((m) => m.Basic),
+    file: "cn/input/basic.tsx",
+  },
+  "input-full-width": {
+    loader: () => import("./input/full-width").then((m) => m.FullWidth),
+    file: "cn/input/full-width.tsx",
+  },
+  "input-types": {
+    loader: () => import("./input/types").then((m) => m.Types),
+    file: "cn/input/types.tsx",
+  },
+  "input-controlled": {
+    loader: () => import("./input/controlled").then((m) => m.Controlled),
+    file: "cn/input/controlled.tsx",
+  },
+  "input-on-surface": {
+    loader: () => import("./input/on-surface").then((m) => m.OnSurface),
+    file: "cn/input/on-surface.tsx",
+  },
+  "input-variants": {
+    loader: () => import("./input/variants").then((m) => m.Variants),
+    file: "cn/input/variants.tsx",
+  },
+  // DateField demos
+  "date-field-basic": {
+    loader: () => import("./date-field/basic").then((m) => m.Basic),
+    file: "cn/date-field/basic.tsx",
+  },
+  "date-field-controlled": {
+    loader: () => import("./date-field/controlled").then((m) => m.Controlled),
+    file: "cn/date-field/controlled.tsx",
+  },
+  "date-field-disabled": {
+    loader: () => import("./date-field/disabled").then((m) => m.Disabled),
+    file: "cn/date-field/disabled.tsx",
+  },
+  "date-field-form-example": {
+    loader: () => import("./date-field/form-example").then((m) => m.FormExample),
+    file: "cn/date-field/form-example.tsx",
+  },
+  "date-field-invalid": {
+    loader: () => import("./date-field/invalid").then((m) => m.Invalid),
+    file: "cn/date-field/invalid.tsx",
+  },
+  "date-field-on-surface": {
+    loader: () => import("./date-field/on-surface").then((m) => m.OnSurface),
+    file: "cn/date-field/on-surface.tsx",
+  },
+  "date-field-required": {
+    loader: () => import("./date-field/required").then((m) => m.Required),
+    file: "cn/date-field/required.tsx",
+  },
+  "date-field-with-description": {
+    loader: () => import("./date-field/with-description").then((m) => m.WithDescription),
+    file: "cn/date-field/with-description.tsx",
+  },
+  "date-field-with-prefix-and-suffix": {
+    loader: () => import("./date-field/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "cn/date-field/with-prefix-and-suffix.tsx",
+  },
+  "date-field-with-prefix-icon": {
+    loader: () => import("./date-field/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "cn/date-field/with-prefix-icon.tsx",
+  },
+  "date-field-with-suffix-icon": {
+    loader: () => import("./date-field/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "cn/date-field/with-suffix-icon.tsx",
+  },
+  "date-field-full-width": {
+    loader: () => import("./date-field/full-width").then((m) => m.FullWidth),
+    file: "cn/date-field/full-width.tsx",
+  },
+  "date-field-granularity": {
+    loader: () => import("./date-field/granularity").then((m) => m.Granularity),
+    file: "cn/date-field/granularity.tsx",
+  },
+  "date-field-with-validation": {
+    loader: () => import("./date-field/with-validation").then((m) => m.WithValidation),
+    file: "cn/date-field/with-validation.tsx",
+  },
+  "date-field-variants": {
+    loader: () => import("./date-field/variants").then((m) => m.Variants),
+    file: "cn/date-field/variants.tsx",
+  },
+  "date-field-custom-render-function": {
+    loader: () => import("./date-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/date-field/custom-render-function.tsx",
+  },
+  // DatePicker demos
+  "date-picker-basic": {
+    loader: () => import("./date-picker/basic").then((m) => m.Basic),
+    file: "cn/date-picker/basic.tsx",
+  },
+  "date-picker-controlled": {
+    loader: () => import("./date-picker/controlled").then((m) => m.Controlled),
+    file: "cn/date-picker/controlled.tsx",
+  },
+  "date-picker-disabled": {
+    loader: () => import("./date-picker/disabled").then((m) => m.Disabled),
+    file: "cn/date-picker/disabled.tsx",
+  },
+  "date-picker-format-options": {
+    loader: () => import("./date-picker/format-options-no-ssr").then((m) => m.FormatOptions),
+    file: "cn/date-picker/format-options.tsx",
+  },
+  "date-picker-form-example": {
+    loader: () => import("./date-picker/form-example").then((m) => m.FormExample),
+    file: "cn/date-picker/form-example.tsx",
+  },
+  "date-picker-with-custom-indicator": {
+    loader: () => import("./date-picker/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "cn/date-picker/with-custom-indicator.tsx",
+  },
+  "date-picker-with-validation": {
+    loader: () => import("./date-picker/with-validation").then((m) => m.WithValidation),
+    file: "cn/date-picker/with-validation.tsx",
+  },
+  "date-picker-international-calendar": {
+    loader: () =>
+      import("./date-picker/international-calendar").then((m) => m.InternationalCalendar),
+    file: "cn/date-picker/international-calendar.tsx",
+  },
+  "date-picker-custom-render-function": {
+    loader: () =>
+      import("./date-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/date-picker/custom-render-function.tsx",
+  },
+  // DateRangePicker demos
+  "date-range-picker-basic": {
+    loader: () => import("./date-range-picker/basic").then((m) => m.Basic),
+    file: "cn/date-range-picker/basic.tsx",
+  },
+  "date-range-picker-controlled": {
+    loader: () => import("./date-range-picker/controlled").then((m) => m.Controlled),
+    file: "cn/date-range-picker/controlled.tsx",
+  },
+  "date-range-picker-disabled": {
+    loader: () => import("./date-range-picker/disabled").then((m) => m.Disabled),
+    file: "cn/date-range-picker/disabled.tsx",
+  },
+  "date-range-picker-format-options": {
+    loader: () => import("./date-range-picker/format-options-no-ssr").then((m) => m.FormatOptions),
+    file: "cn/date-range-picker/format-options.tsx",
+  },
+  "date-range-picker-form-example": {
+    loader: () => import("./date-range-picker/form-example").then((m) => m.FormExample),
+    file: "cn/date-range-picker/form-example.tsx",
+  },
+  "date-range-picker-with-custom-indicator": {
+    loader: () =>
+      import("./date-range-picker/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "cn/date-range-picker/with-custom-indicator.tsx",
+  },
+  "date-range-picker-with-validation": {
+    loader: () => import("./date-range-picker/with-validation").then((m) => m.WithValidation),
+    file: "cn/date-range-picker/with-validation.tsx",
+  },
+  "date-range-picker-international-calendar": {
+    loader: () =>
+      import("./date-range-picker/international-calendar").then((m) => m.InternationalCalendar),
+    file: "cn/date-range-picker/international-calendar.tsx",
+  },
+  "date-range-picker-custom-render-function": {
+    loader: () =>
+      import("./date-range-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/date-range-picker/custom-render-function.tsx",
+  },
+  "date-range-picker-input-container": {
+    loader: () => import("./date-range-picker/input-container").then((m) => m.InputContainer),
+    file: "cn/date-range-picker/input-container.tsx",
+  },
+  // InputOTP demos
+  "input-otp-basic": {
+    loader: () => import("./input-otp/basic").then((m) => m.Basic),
+    file: "cn/input-otp/basic.tsx",
+  },
+  "input-otp-four-digits": {
+    loader: () => import("./input-otp/four-digits").then((m) => m.FourDigits),
+    file: "cn/input-otp/four-digits.tsx",
+  },
+  "input-otp-disabled": {
+    loader: () => import("./input-otp/disabled").then((m) => m.Disabled),
+    file: "cn/input-otp/disabled.tsx",
+  },
+  "input-otp-with-pattern": {
+    loader: () => import("./input-otp/with-pattern").then((m) => m.WithPattern),
+    file: "cn/input-otp/with-pattern.tsx",
+  },
+  "input-otp-controlled": {
+    loader: () => import("./input-otp/controlled").then((m) => m.Controlled),
+    file: "cn/input-otp/controlled.tsx",
+  },
+  "input-otp-with-validation": {
+    loader: () => import("./input-otp/with-validation").then((m) => m.WithValidation),
+    file: "cn/input-otp/with-validation.tsx",
+  },
+  "input-otp-on-complete": {
+    loader: () => import("./input-otp/on-complete").then((m) => m.OnComplete),
+    file: "cn/input-otp/on-complete.tsx",
+  },
+  "input-otp-form-example": {
+    loader: () => import("./input-otp/form-example").then((m) => m.FormExample),
+    file: "cn/input-otp/form-example.tsx",
+  },
+  "input-otp-on-surface": {
+    loader: () => import("./input-otp/on-surface").then((m) => m.OnSurface),
+    file: "cn/input-otp/on-surface.tsx",
+  },
+  "input-otp-variants": {
+    loader: () => import("./input-otp/variants").then((m) => m.Variants),
+    file: "cn/input-otp/variants.tsx",
+  },
+  // InputGroup demos
+  "input-group-default": {
+    loader: () => import("./input-group/default").then((m) => m.Default),
+    file: "cn/input-group/default.tsx",
+  },
+  "input-group-full-width": {
+    loader: () => import("./input-group/full-width").then((m) => m.FullWidth),
+    file: "cn/input-group/full-width.tsx",
+  },
+  "input-group-with-prefix-icon": {
+    loader: () => import("./input-group/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "cn/input-group/with-prefix-icon.tsx",
+  },
+  "input-group-with-suffix-icon": {
+    loader: () => import("./input-group/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "cn/input-group/with-suffix-icon.tsx",
+  },
+  "input-group-with-prefix-and-suffix": {
+    loader: () => import("./input-group/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "cn/input-group/with-prefix-and-suffix.tsx",
+  },
+  "input-group-with-text-prefix": {
+    loader: () => import("./input-group/with-text-prefix").then((m) => m.WithTextPrefix),
+    file: "cn/input-group/with-text-prefix.tsx",
+  },
+  "input-group-with-text-suffix": {
+    loader: () => import("./input-group/with-text-suffix").then((m) => m.WithTextSuffix),
+    file: "cn/input-group/with-text-suffix.tsx",
+  },
+  "input-group-with-icon-prefix-and-text-suffix": {
+    loader: () =>
+      import("./input-group/with-icon-prefix-and-text-suffix").then(
+        (m) => m.WithIconPrefixAndTextSuffix,
+      ),
+    file: "cn/input-group/with-icon-prefix-and-text-suffix.tsx",
+  },
+  "input-group-with-copy-suffix": {
+    loader: () => import("./input-group/with-copy-suffix").then((m) => m.WithCopySuffix),
+    file: "cn/input-group/with-copy-suffix.tsx",
+  },
+  "input-group-with-icon-prefix-and-copy-suffix": {
+    loader: () =>
+      import("./input-group/with-icon-prefix-and-copy-suffix").then(
+        (m) => m.WithIconPrefixAndCopySuffix,
+      ),
+    file: "cn/input-group/with-icon-prefix-and-copy-suffix.tsx",
+  },
+  "input-group-password-with-toggle": {
+    loader: () => import("./input-group/password-with-toggle").then((m) => m.PasswordWithToggle),
+    file: "cn/input-group/password-with-toggle.tsx",
+  },
+  "input-group-with-loading-suffix": {
+    loader: () => import("./input-group/with-loading-suffix").then((m) => m.WithLoadingSuffix),
+    file: "cn/input-group/with-loading-suffix.tsx",
+  },
+  "input-group-with-keyboard-shortcut": {
+    loader: () =>
+      import("./input-group/with-keyboard-shortcut").then((m) => m.WithKeyboardShortcut),
+    file: "cn/input-group/with-keyboard-shortcut.tsx",
+  },
+  "input-group-with-badge-suffix": {
+    loader: () => import("./input-group/with-badge-suffix").then((m) => m.WithBadgeSuffix),
+    file: "cn/input-group/with-badge-suffix.tsx",
+  },
+  "input-group-required": {
+    loader: () => import("./input-group/required").then((m) => m.Required),
+    file: "cn/input-group/required.tsx",
+  },
+  "input-group-invalid": {
+    loader: () => import("./input-group/invalid").then((m) => m.Invalid),
+    file: "cn/input-group/invalid.tsx",
+  },
+  "input-group-disabled": {
+    loader: () => import("./input-group/disabled").then((m) => m.Disabled),
+    file: "cn/input-group/disabled.tsx",
+  },
+  "input-group-on-surface": {
+    loader: () => import("./input-group/on-surface").then((m) => m.OnSurface),
+    file: "cn/input-group/on-surface.tsx",
+  },
+  "input-group-with-textarea": {
+    loader: () => import("./input-group/with-textarea").then((m) => m.WithTextArea),
+    file: "cn/input-group/with-textarea.tsx",
+  },
+  "input-group-variants": {
+    loader: () => import("./input-group/variants").then((m) => m.Variants),
+    file: "cn/input-group/variants.tsx",
+  },
+  // Kbd demos
+  "kbd-basic": {
+    loader: () => import("./kbd/basic").then((m) => m.Basic),
+    file: "cn/kbd/basic.tsx",
+  },
+  "kbd-navigation-keys": {
+    loader: () => import("./kbd/navigation").then((m) => m.NavigationKeys),
+    file: "cn/kbd/navigation.tsx",
+  },
+  "kbd-inline-usage": {
+    loader: () => import("./kbd/inline").then((m) => m.InlineUsage),
+    file: "cn/kbd/inline.tsx",
+  },
+  "kbd-instructional-text": {
+    loader: () => import("./kbd/instructional").then((m) => m.InstructionalText),
+    file: "cn/kbd/instructional.tsx",
+  },
+  "kbd-special-keys": {
+    loader: () => import("./kbd/special").then((m) => m.SpecialKeys),
+    file: "cn/kbd/special.tsx",
+  },
+  "kbd-variants": {
+    loader: () => import("./kbd/variants").then((m) => m.Variants),
+    file: "cn/kbd/variants.tsx",
+  },
+  // Link demos
+  "link-basic": {
+    loader: () => import("./link/basic").then((m) => m.LinkBasic),
+    file: "cn/link/basic.tsx",
+  },
+  "link-custom-icon": {
+    loader: () => import("./link/custom-icon").then((m) => m.LinkCustomIcon),
+    file: "cn/link/custom-icon.tsx",
+  },
+  "link-icon-placement": {
+    loader: () => import("./link/icon-placement").then((m) => m.LinkIconPlacement),
+    file: "cn/link/icon-placement.tsx",
+  },
+  "link-underline-and-offset": {
+    loader: () => import("./link/underline-and-offset").then((m) => m.LinkUnderlineAndOffset),
+    file: "cn/link/underline-and-offset.tsx",
+  },
+  "link-custom-render-function": {
+    loader: () => import("./link/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/link/custom-render-function.tsx",
+  },
+  // RadioGroup demos
+  "radio-group-basic": {
+    loader: () => import("./radio-group/basic").then((m) => m.Basic),
+    file: "cn/radio-group/basic.tsx",
+  },
+  "radio-group-controlled": {
+    loader: () => import("./radio-group/controlled").then((m) => m.Controlled),
+    file: "cn/radio-group/controlled.tsx",
+  },
+  "radio-group-custom-indicator": {
+    loader: () => import("./radio-group/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/radio-group/custom-indicator.tsx",
+  },
+  "radio-group-delivery-and-payment": {
+    loader: () => import("./radio-group/delivery-and-payment").then((m) => m.DeliveryAndPayment),
+    file: "cn/radio-group/delivery-and-payment.tsx",
+  },
+  "radio-group-disabled": {
+    loader: () => import("./radio-group/disabled").then((m) => m.Disabled),
+    file: "cn/radio-group/disabled.tsx",
+  },
+  "radio-group-horizontal": {
+    loader: () => import("./radio-group/horizontal").then((m) => m.Horizontal),
+    file: "cn/radio-group/horizontal.tsx",
+  },
+  "radio-group-uncontrolled": {
+    loader: () => import("./radio-group/uncontrolled").then((m) => m.Uncontrolled),
+    file: "cn/radio-group/uncontrolled.tsx",
+  },
+  "radio-group-validation": {
+    loader: () => import("./radio-group/validation").then((m) => m.Validation),
+    file: "cn/radio-group/validation.tsx",
+  },
+  "radio-group-on-surface": {
+    loader: () => import("./radio-group/on-surface").then((m) => m.OnSurface),
+    file: "cn/radio-group/on-surface.tsx",
+  },
+  "radio-group-variants": {
+    loader: () => import("./radio-group/variants").then((m) => m.Variants),
+    file: "cn/radio-group/variants.tsx",
+  },
+  "radio-group-custom-render-function": {
+    loader: () =>
+      import("./radio-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/radio-group/custom-render-function.tsx",
+  },
+  // Skeleton demos
+  "skeleton-basic": {
+    loader: () => import("./skeleton/basic").then((m) => m.Basic),
+    file: "cn/skeleton/basic.tsx",
+  },
+  "skeleton-text-content": {
+    loader: () => import("./skeleton/text-content").then((m) => m.TextContent),
+    file: "cn/skeleton/text-content.tsx",
+  },
+  "skeleton-user-profile": {
+    loader: () => import("./skeleton/user-profile").then((m) => m.UserProfile),
+    file: "cn/skeleton/user-profile.tsx",
+  },
+  "skeleton-list": {
+    loader: () => import("./skeleton/list").then((m) => m.List),
+    file: "cn/skeleton/list.tsx",
+  },
+  "skeleton-animation-types": {
+    loader: () => import("./skeleton/animation-types").then((m) => m.AnimationTypes),
+    file: "cn/skeleton/animation-types.tsx",
+  },
+  "skeleton-grid": {
+    loader: () => import("./skeleton/grid").then((m) => m.Grid),
+    file: "cn/skeleton/grid.tsx",
+  },
+  "skeleton-single-shimmer": {
+    loader: () => import("./skeleton/single-shimmer").then((m) => m.SingleShimmer),
+    file: "cn/skeleton/single-shimmer.tsx",
+  },
+  // Separator demos
+  "separator-basic": {
+    loader: () => import("./separator/basic").then((m) => m.Basic),
+    file: "cn/separator/basic.tsx",
+  },
+  "separator-vertical": {
+    loader: () => import("./separator/vertical").then((m) => m.Vertical),
+    file: "cn/separator/vertical.tsx",
+  },
+  "separator-with-content": {
+    loader: () => import("./separator/with-content").then((m) => m.WithContent),
+    file: "cn/separator/with-content.tsx",
+  },
+  "separator-variants": {
+    loader: () => import("./separator/variants").then((m) => m.Variants),
+    file: "cn/separator/variants.tsx",
+  },
+  "separator-with-surface": {
+    loader: () => import("./separator/with-surface").then((m) => m.WithSurface),
+    file: "cn/separator/with-surface.tsx",
+  },
+  "separator-manual-variant-override": {
+    loader: () =>
+      import("./separator/manual-variant-override").then((m) => m.ManualVariantOverride),
+    file: "cn/separator/manual-variant-override.tsx",
+  },
+  "separator-custom-render-function": {
+    loader: () => import("./separator/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/separator/custom-render-function.tsx",
+  },
+  // Spinner demos
+  "spinner-basic": {
+    loader: () => import("./spinner/basic").then((m) => m.SpinnerBasic),
+    file: "cn/spinner/basic.tsx",
+  },
+  "spinner-colors": {
+    loader: () => import("./spinner/colors").then((m) => m.SpinnerColors),
+    file: "cn/spinner/colors.tsx",
+  },
+  "spinner-sizes": {
+    loader: () => import("./spinner/sizes").then((m) => m.SpinnerSizes),
+    file: "cn/spinner/sizes.tsx",
+  },
+  // Surface demos
+  "surface-variants": {
+    loader: () => import("./surface/variants").then((m) => m.Variants),
+    file: "cn/surface/variants.tsx",
+  },
+  // Switch demos
+  "switch-basic": {
+    loader: () => import("./switch/basic").then((m) => m.Basic),
+    file: "cn/switch/basic.tsx",
+  },
+  "switch-disabled": {
+    loader: () => import("./switch/disabled").then((m) => m.Disabled),
+    file: "cn/switch/disabled.tsx",
+  },
+  "switch-default-selected": {
+    loader: () => import("./switch/default-selected").then((m) => m.DefaultSelected),
+    file: "cn/switch/default-selected.tsx",
+  },
+  "switch-controlled": {
+    loader: () => import("./switch/controlled").then((m) => m.Controlled),
+    file: "cn/switch/controlled.tsx",
+  },
+  "switch-without-label": {
+    loader: () => import("./switch/without-label").then((m) => m.WithoutLabel),
+    file: "cn/switch/without-label.tsx",
+  },
+  "switch-sizes": {
+    loader: () => import("./switch/sizes").then((m) => m.Sizes),
+    file: "cn/switch/sizes.tsx",
+  },
+  "switch-label-position": {
+    loader: () => import("./switch/label-position").then((m) => m.LabelPosition),
+    file: "cn/switch/label-position.tsx",
+  },
+  "switch-with-icons": {
+    loader: () => import("./switch/with-icons").then((m) => m.WithIcons),
+    file: "cn/switch/with-icons.tsx",
+  },
+  "switch-with-description": {
+    loader: () => import("./switch/with-description").then((m) => m.WithDescription),
+    file: "cn/switch/with-description.tsx",
+  },
+  "switch-group": {
+    loader: () => import("./switch/group").then((m) => m.Group),
+    file: "cn/switch/group.tsx",
+  },
+  "switch-group-horizontal": {
+    loader: () => import("./switch/group-horizontal").then((m) => m.GroupHorizontal),
+    file: "cn/switch/group-horizontal.tsx",
+  },
+  "switch-render-props": {
+    loader: () => import("./switch/render-props").then((m) => m.RenderProps),
+    file: "cn/switch/render-props.tsx",
+  },
+  "switch-form": {
+    loader: () => import("./switch/form").then((m) => m.Form),
+    file: "cn/switch/form.tsx",
+  },
+  "switch-custom-styles": {
+    loader: () => import("./switch/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/switch/custom-styles.tsx",
+  },
+  "switch-custom-render-function": {
+    loader: () => import("./switch/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/switch/custom-render-function.tsx",
+  },
+  // Tabs demos
+  "tabs-basic": {
+    loader: () => import("./tabs/basic").then((m) => m.Basic),
+    file: "cn/tabs/basic.tsx",
+  },
+  "tabs-vertical": {
+    loader: () => import("./tabs/vertical").then((m) => m.Vertical),
+    file: "cn/tabs/vertical.tsx",
+  },
+  "tabs-overflow": {
+    loader: () => import("./tabs/overflow").then((m) => m.Overflow),
+    file: "cn/tabs/overflow.tsx",
+  },
+  "tabs-disabled": {
+    loader: () => import("./tabs/disabled").then((m) => m.Disabled),
+    file: "cn/tabs/disabled.tsx",
+  },
+  "tabs-custom-styles": {
+    loader: () => import("./tabs/custom-styles").then((m) => m.CustomStyles),
+    file: "cn/tabs/custom-styles.tsx",
+  },
+  "tabs-with-separator": {
+    loader: () => import("./tabs/with-separator").then((m) => m.WithSeparator),
+    file: "cn/tabs/with-separator.tsx",
+  },
+  "tabs-secondary": {
+    loader: () => import("./tabs/secondary").then((m) => m.Secondary),
+    file: "cn/tabs/secondary.tsx",
+  },
+  "tabs-secondary-vertical": {
+    loader: () => import("./tabs/secondary-vertical").then((m) => m.SecondaryVertical),
+    file: "cn/tabs/secondary-vertical.tsx",
+  },
+  "tabs-custom-render-function": {
+    loader: () => import("./tabs/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/tabs/custom-render-function.tsx",
+  },
+  // TagGroup demos
+  "tag-group-basic": {
+    loader: () => import("./tag-group/basic").then((m) => m.TagGroupBasic),
+    file: "cn/tag-group/basic.tsx",
+  },
+  "tag-group-sizes": {
+    loader: () => import("./tag-group/sizes").then((m) => m.TagGroupSizes),
+    file: "cn/tag-group/sizes.tsx",
+  },
+  "tag-group-variants": {
+    loader: () => import("./tag-group/variants").then((m) => m.TagGroupVariants),
+    file: "cn/tag-group/variants.tsx",
+  },
+  "tag-group-disabled": {
+    loader: () => import("./tag-group/disabled").then((m) => m.TagGroupDisabled),
+    file: "cn/tag-group/disabled.tsx",
+  },
+  "tag-group-selection-modes": {
+    loader: () => import("./tag-group/selection-modes").then((m) => m.TagGroupSelectionModes),
+    file: "cn/tag-group/selection-modes.tsx",
+  },
+  "tag-group-controlled": {
+    loader: () => import("./tag-group/controlled").then((m) => m.TagGroupControlled),
+    file: "cn/tag-group/controlled.tsx",
+  },
+  "tag-group-with-error-message": {
+    loader: () => import("./tag-group/with-error-message").then((m) => m.TagGroupWithErrorMessage),
+    file: "cn/tag-group/with-error-message.tsx",
+  },
+  "tag-group-with-prefix": {
+    loader: () => import("./tag-group/with-prefix").then((m) => m.TagGroupWithPrefix),
+    file: "cn/tag-group/with-prefix.tsx",
+  },
+  "tag-group-with-remove-button": {
+    loader: () => import("./tag-group/with-remove-button").then((m) => m.TagGroupWithRemoveButton),
+    file: "cn/tag-group/with-remove-button.tsx",
+  },
+  "tag-group-with-list-data": {
+    loader: () => import("./tag-group/with-list-data").then((m) => m.TagGroupWithListData),
+    file: "cn/tag-group/with-list-data.tsx",
+  },
+  "tag-group-custom-render-function": {
+    loader: () => import("./tag-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/tag-group/custom-render-function.tsx",
+  },
+  // Table demos
+  "table-basic": {
+    loader: () => import("./table/basic").then((m) => m.Basic),
+    file: "cn/table/basic.tsx",
+  },
+  "table-secondary-variant": {
+    loader: () => import("./table/secondary-variant").then((m) => m.SecondaryVariant),
+    file: "cn/table/secondary-variant.tsx",
+  },
+  "table-sorting": {
+    loader: () => import("./table/sorting").then((m) => m.Sorting),
+    file: "cn/table/sorting.tsx",
+  },
+  "table-selection": {
+    loader: () => import("./table/selection").then((m) => m.SelectionDemo),
+    file: "cn/table/selection.tsx",
+  },
+  "table-custom-cells": {
+    loader: () => import("./table/custom-cells").then((m) => m.CustomCells),
+    file: "cn/table/custom-cells.tsx",
+  },
+  "table-expandable-rows": {
+    loader: () => import("./table/expandable-rows").then((m) => m.ExpandableRows),
+    file: "cn/table/expandable-rows.tsx",
+  },
+  "table-pagination": {
+    loader: () => import("./table/pagination").then((m) => m.PaginationDemo),
+    file: "cn/table/pagination.tsx",
+  },
+  "table-column-resizing": {
+    loader: () => import("./table/column-resizing").then((m) => m.ColumnResizing),
+    file: "cn/table/column-resizing.tsx",
+  },
+  "table-empty-state": {
+    loader: () => import("./table/empty-state").then((m) => m.EmptyStateDemo),
+    file: "cn/table/empty-state.tsx",
+  },
+  "table-async-loading": {
+    loader: () => import("./table/async-loading").then((m) => m.AsyncLoading),
+    file: "cn/table/async-loading.tsx",
+  },
+  "table-virtualization": {
+    loader: () => import("./table/virtualization").then((m) => m.Virtualization),
+    file: "cn/table/virtualization.tsx",
+  },
+  "table-tanstack-table": {
+    loader: () => import("./table/tanstack-table").then((m) => m.TanstackTable),
+    file: "cn/table/tanstack-table.tsx",
+  },
+  // TextArea demos
+  "textarea-basic": {
+    loader: () => import("./textarea/basic").then((m) => m.Basic),
+    file: "cn/textarea/basic.tsx",
+  },
+  "textarea-full-width": {
+    loader: () => import("./textarea/full-width").then((m) => m.FullWidth),
+    file: "cn/textarea/full-width.tsx",
+  },
+  "textarea-rows": {
+    loader: () => import("./textarea/rows").then((m) => m.Rows),
+    file: "cn/textarea/rows.tsx",
+  },
+  "textarea-controlled": {
+    loader: () => import("./textarea/controlled").then((m) => m.Controlled),
+    file: "cn/textarea/controlled.tsx",
+  },
+  "textarea-on-surface": {
+    loader: () => import("./textarea/on-surface").then((m) => m.OnSurface),
+    file: "cn/textarea/on-surface.tsx",
+  },
+  "textarea-variants": {
+    loader: () => import("./textarea/variants").then((m) => m.Variants),
+    file: "cn/textarea/variants.tsx",
+  },
+  // Typography demos
+  "typography-default": {
+    loader: () => import("./typography/default").then((m) => m.Default),
+    file: "cn/typography/default.tsx",
+  },
+  "typography-primitives": {
+    loader: () => import("./typography/primitives").then((m) => m.Primitives),
+    file: "cn/typography/primitives.tsx",
+  },
+  "typography-prose": {
+    loader: () => import("./typography/prose").then((m) => m.Prose),
+    file: "cn/typography/prose.tsx",
+  },
+  "typography-render-props": {
+    loader: () => import("./typography/render-props").then((m) => m.RenderProps),
+    file: "cn/typography/render-props.tsx",
+  },
+  "typography-typography-scale": {
+    loader: () => import("./typography/typography-scale").then((m) => m.TypographyScale),
+    file: "cn/typography/typography-scale.tsx",
+  },
+  // TextField demos
+  "textfield-basic": {
+    loader: () => import("./textfield/basic").then((m) => m.Basic),
+    file: "cn/textfield/basic.tsx",
+  },
+  "textfield-with-description": {
+    loader: () => import("./textfield/with-description").then((m) => m.WithDescription),
+    file: "cn/textfield/with-description.tsx",
+  },
+  "textfield-required": {
+    loader: () => import("./textfield/required").then((m) => m.Required),
+    file: "cn/textfield/required.tsx",
+  },
+  "textfield-with-error": {
+    loader: () => import("./textfield/with-error").then((m) => m.WithError),
+    file: "cn/textfield/with-error.tsx",
+  },
+  "textfield-disabled": {
+    loader: () => import("./textfield/disabled").then((m) => m.Disabled),
+    file: "cn/textfield/disabled.tsx",
+  },
+  "textfield-textarea": {
+    loader: () => import("./textfield/textarea").then((m) => m.TextAreaExample),
+    file: "cn/textfield/textarea.tsx",
+  },
+  "textfield-input-types": {
+    loader: () => import("./textfield/input-types").then((m) => m.InputTypes),
+    file: "cn/textfield/input-types.tsx",
+  },
+  "textfield-full-width": {
+    loader: () => import("./textfield/full-width").then((m) => m.FullWidth),
+    file: "cn/textfield/full-width.tsx",
+  },
+  "textfield-controlled": {
+    loader: () => import("./textfield/controlled").then((m) => m.Controlled),
+    file: "cn/textfield/controlled.tsx",
+  },
+  "textfield-validation": {
+    loader: () => import("./textfield/validation").then((m) => m.Validation),
+    file: "cn/textfield/validation.tsx",
+  },
+  "textfield-on-surface": {
+    loader: () => import("./textfield/on-surface").then((m) => m.OnSurface),
+    file: "cn/textfield/on-surface.tsx",
+  },
+  "textfield-custom-render-function": {
+    loader: () => import("./textfield/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/textfield/custom-render-function.tsx",
+  },
+  // TimeField demos
+  "time-field-basic": {
+    loader: () => import("./time-field/basic").then((m) => m.Basic),
+    file: "cn/time-field/basic.tsx",
+  },
+  "time-field-controlled": {
+    loader: () => import("./time-field/controlled").then((m) => m.Controlled),
+    file: "cn/time-field/controlled.tsx",
+  },
+  "time-field-disabled": {
+    loader: () => import("./time-field/disabled").then((m) => m.Disabled),
+    file: "cn/time-field/disabled.tsx",
+  },
+  "time-field-form-example": {
+    loader: () => import("./time-field/form-example").then((m) => m.FormExample),
+    file: "cn/time-field/form-example.tsx",
+  },
+  "time-field-invalid": {
+    loader: () => import("./time-field/invalid").then((m) => m.Invalid),
+    file: "cn/time-field/invalid.tsx",
+  },
+  "time-field-on-surface": {
+    loader: () => import("./time-field/on-surface").then((m) => m.OnSurface),
+    file: "cn/time-field/on-surface.tsx",
+  },
+  "time-field-required": {
+    loader: () => import("./time-field/required").then((m) => m.Required),
+    file: "cn/time-field/required.tsx",
+  },
+  "time-field-with-description": {
+    loader: () => import("./time-field/with-description").then((m) => m.WithDescription),
+    file: "cn/time-field/with-description.tsx",
+  },
+  "time-field-with-prefix-and-suffix": {
+    loader: () => import("./time-field/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "cn/time-field/with-prefix-and-suffix.tsx",
+  },
+  "time-field-with-prefix-icon": {
+    loader: () => import("./time-field/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "cn/time-field/with-prefix-icon.tsx",
+  },
+  "time-field-with-suffix-icon": {
+    loader: () => import("./time-field/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "cn/time-field/with-suffix-icon.tsx",
+  },
+  "time-field-full-width": {
+    loader: () => import("./time-field/full-width").then((m) => m.FullWidth),
+    file: "cn/time-field/full-width.tsx",
+  },
+  "time-field-with-validation": {
+    loader: () => import("./time-field/with-validation").then((m) => m.WithValidation),
+    file: "cn/time-field/with-validation.tsx",
+  },
+  "time-field-custom-render-function": {
+    loader: () => import("./time-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/time-field/custom-render-function.tsx",
+  },
+  // Toast demos
+  "toast-default": {
+    loader: () => import("./toast/default").then((m) => m.Default),
+    file: "cn/toast/default.tsx",
+  },
+  "toast-simple": {
+    loader: () => import("./toast/simple").then((m) => m.Simple),
+    file: "cn/toast/simple.tsx",
+  },
+  "toast-variants": {
+    loader: () => import("./toast/variants").then((m) => m.Variants),
+    file: "cn/toast/variants.tsx",
+  },
+  "toast-custom-indicator": {
+    loader: () => import("./toast/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/toast/custom-indicator.tsx",
+  },
+  "toast-promise": {
+    loader: () => import("./toast/promise").then((m) => m.PromiseDemo),
+    file: "cn/toast/promise.tsx",
+  },
+  "toast-callbacks": {
+    loader: () => import("./toast/callbacks").then((m) => m.Callbacks),
+    file: "cn/toast/callbacks.tsx",
+  },
+  "toast-placements": {
+    loader: () => import("./toast/placements").then((m) => m.Placements),
+    file: "cn/toast/placements.tsx",
+  },
+  "toast-custom-toast": {
+    loader: () => import("./toast/custom-toast").then((m) => m.CustomToast),
+    file: "cn/toast/custom-toast.tsx",
+  },
+  "toast-custom-queue": {
+    loader: () => import("./toast/custom-queue").then((m) => m.CustomQueue),
+    file: "cn/toast/custom-queue.tsx",
+  },
+  // ToggleButton demos
+  "toggle-button-basic": {
+    loader: () => import("./toggle-button/basic").then((m) => m.Basic),
+    file: "cn/toggle-button/basic.tsx",
+  },
+  "toggle-button-variants": {
+    loader: () => import("./toggle-button/variants").then((m) => m.Variants),
+    file: "cn/toggle-button/variants.tsx",
+  },
+  "toggle-button-sizes": {
+    loader: () => import("./toggle-button/sizes").then((m) => m.Sizes),
+    file: "cn/toggle-button/sizes.tsx",
+  },
+  "toggle-button-icon-only": {
+    loader: () => import("./toggle-button/icon-only").then((m) => m.IconOnly),
+    file: "cn/toggle-button/icon-only.tsx",
+  },
+  "toggle-button-controlled": {
+    loader: () => import("./toggle-button/controlled").then((m) => m.Controlled),
+    file: "cn/toggle-button/controlled.tsx",
+  },
+  "toggle-button-disabled": {
+    loader: () => import("./toggle-button/disabled").then((m) => m.Disabled),
+    file: "cn/toggle-button/disabled.tsx",
+  },
+  // ToggleButtonGroup demos
+  "toggle-button-group-basic": {
+    loader: () => import("./toggle-button-group/basic").then((m) => m.Basic),
+    file: "cn/toggle-button-group/basic.tsx",
+  },
+  "toggle-button-group-sizes": {
+    loader: () => import("./toggle-button-group/sizes").then((m) => m.Sizes),
+    file: "cn/toggle-button-group/sizes.tsx",
+  },
+  "toggle-button-group-orientation": {
+    loader: () => import("./toggle-button-group/orientation").then((m) => m.Orientation),
+    file: "cn/toggle-button-group/orientation.tsx",
+  },
+  "toggle-button-group-attached": {
+    loader: () => import("./toggle-button-group/attached").then((m) => m.Attached),
+    file: "cn/toggle-button-group/attached.tsx",
+  },
+  "toggle-button-group-full-width": {
+    loader: () => import("./toggle-button-group/full-width").then((m) => m.FullWidth),
+    file: "cn/toggle-button-group/full-width.tsx",
+  },
+  "toggle-button-group-selection-mode": {
+    loader: () => import("./toggle-button-group/selection-mode").then((m) => m.SelectionMode),
+    file: "cn/toggle-button-group/selection-mode.tsx",
+  },
+  "toggle-button-group-controlled": {
+    loader: () => import("./toggle-button-group/controlled").then((m) => m.Controlled),
+    file: "cn/toggle-button-group/controlled.tsx",
+  },
+  "toggle-button-group-disabled": {
+    loader: () => import("./toggle-button-group/disabled").then((m) => m.Disabled),
+    file: "cn/toggle-button-group/disabled.tsx",
+  },
+  "toggle-button-group-without-separator": {
+    loader: () => import("./toggle-button-group/without-separator").then((m) => m.WithoutSeparator),
+    file: "cn/toggle-button-group/without-separator.tsx",
+  },
+  // Toolbar demos
+  "toolbar-basic": {
+    loader: () => import("./toolbar/basic").then((m) => m.Basic),
+    file: "cn/toolbar/basic.tsx",
+  },
+  "toolbar-vertical": {
+    loader: () => import("./toolbar/vertical").then((m) => m.Vertical),
+    file: "cn/toolbar/vertical.tsx",
+  },
+  "toolbar-with-button-group": {
+    loader: () => import("./toolbar/with-button-group").then((m) => m.WithButtonGroup),
+    file: "cn/toolbar/with-button-group.tsx",
+  },
+  "toolbar-attached": {
+    loader: () => import("./toolbar/custom-styles").then((m) => m.Attached),
+    file: "cn/toolbar/custom-styles.tsx",
+  },
+  // Tooltip demos
+  "tooltip-basic": {
+    loader: () => import("./tooltip/basic").then((m) => m.TooltipBasic),
+    file: "cn/tooltip/basic.tsx",
+  },
+  "tooltip-with-arrow": {
+    loader: () => import("./tooltip/with-arrow").then((m) => m.TooltipWithArrow),
+    file: "cn/tooltip/with-arrow.tsx",
+  },
+  "tooltip-placement": {
+    loader: () => import("./tooltip/placement").then((m) => m.TooltipPlacement),
+    file: "cn/tooltip/placement.tsx",
+  },
+  "tooltip-custom-trigger": {
+    loader: () => import("./tooltip/custom-trigger").then((m) => m.TooltipCustomTrigger),
+    file: "cn/tooltip/custom-trigger.tsx",
+  },
+  "tooltip-custom-render-function": {
+    loader: () => import("./tooltip/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/tooltip/custom-render-function.tsx",
+  },
+  // Popover demos
+  "popover-basic": {
+    loader: () => import("./popover/basic").then((m) => m.PopoverBasic),
+    file: "cn/popover/basic.tsx",
+  },
+  "popover-with-arrow": {
+    loader: () => import("./popover/with-arrow").then((m) => m.PopoverWithArrow),
+    file: "cn/popover/with-arrow.tsx",
+  },
+  "popover-placement": {
+    loader: () => import("./popover/placement").then((m) => m.PopoverPlacement),
+    file: "cn/popover/placement.tsx",
+  },
+  "popover-interactive": {
+    loader: () => import("./popover/interactive").then((m) => m.PopoverInteractive),
+    file: "cn/popover/interactive.tsx",
+  },
+  "popover-custom-render-function": {
+    loader: () => import("./popover/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/popover/custom-render-function.tsx",
+  },
+  // Label demos
+  "label-basic": {
+    loader: () => import("./label/basic").then((m) => m.Basic),
+    file: "cn/label/basic.tsx",
+  },
+  // ListBox demos
+  "list-box-controlled": {
+    loader: () => import("./list-box/controlled").then((m) => m.Controlled),
+    file: "cn/list-box/controlled.tsx",
+  },
+  "list-box-custom-check-icon": {
+    loader: () => import("./list-box/custom-check-icon").then((m) => m.CustomCheckIcon),
+    file: "cn/list-box/custom-check-icon.tsx",
+  },
+  "list-box-default": {
+    loader: () => import("./list-box/default").then((m) => m.Default),
+    file: "cn/list-box/default.tsx",
+  },
+  "list-box-multi-select": {
+    loader: () => import("./list-box/multi-select").then((m) => m.MultiSelect),
+    file: "cn/list-box/multi-select.tsx",
+  },
+  "list-box-scrollbar-modes": {
+    loader: () => import("./list-box/scrollbar-modes").then((m) => m.ScrollbarModes),
+    file: "cn/list-box/scrollbar-modes.tsx",
+  },
+  "list-box-with-disabled-items": {
+    loader: () => import("./list-box/with-disabled-items").then((m) => m.WithDisabledItems),
+    file: "cn/list-box/with-disabled-items.tsx",
+  },
+  "list-box-with-sections": {
+    loader: () => import("./list-box/with-sections").then((m) => m.WithSections),
+    file: "cn/list-box/with-sections.tsx",
+  },
+  "list-box-custom-render-function": {
+    loader: () => import("./list-box/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/list-box/custom-render-function.tsx",
+  },
+  "list-box-virtualization": {
+    loader: () => import("./list-box/virtualization").then((m) => m.Virtualization),
+    file: "cn/list-box/virtualization.tsx",
+  },
+  // Meter demos
+  "meter-basic": {
+    loader: () => import("./meter/basic").then((m) => m.Basic),
+    file: "cn/meter/basic.tsx",
+  },
+  "meter-sizes": {
+    loader: () => import("./meter/sizes").then((m) => m.Sizes),
+    file: "cn/meter/sizes.tsx",
+  },
+  "meter-colors": {
+    loader: () => import("./meter/colors").then((m) => m.Colors),
+    file: "cn/meter/colors.tsx",
+  },
+  "meter-custom-value": {
+    loader: () => import("./meter/custom-value").then((m) => m.CustomValue),
+    file: "cn/meter/custom-value.tsx",
+  },
+  "meter-without-label": {
+    loader: () => import("./meter/without-label").then((m) => m.WithoutLabel),
+    file: "cn/meter/without-label.tsx",
+  },
+  // ProgressBar demos
+  "progress-bar-basic": {
+    loader: () => import("./progress-bar/basic").then((m) => m.Basic),
+    file: "cn/progress-bar/basic.tsx",
+  },
+  "progress-bar-sizes": {
+    loader: () => import("./progress-bar/sizes").then((m) => m.Sizes),
+    file: "cn/progress-bar/sizes.tsx",
+  },
+  "progress-bar-colors": {
+    loader: () => import("./progress-bar/colors").then((m) => m.Colors),
+    file: "cn/progress-bar/colors.tsx",
+  },
+  "progress-bar-indeterminate": {
+    loader: () => import("./progress-bar/indeterminate").then((m) => m.Indeterminate),
+    file: "cn/progress-bar/indeterminate.tsx",
+  },
+  "progress-bar-custom-value": {
+    loader: () => import("./progress-bar/custom-value").then((m) => m.CustomValue),
+    file: "cn/progress-bar/custom-value.tsx",
+  },
+  "progress-bar-without-label": {
+    loader: () => import("./progress-bar/without-label").then((m) => m.WithoutLabel),
+    file: "cn/progress-bar/without-label.tsx",
+  },
+  // ProgressCircle demos
+  "progress-circle-basic": {
+    loader: () => import("./progress-circle/basic").then((m) => m.Basic),
+    file: "cn/progress-circle/basic.tsx",
+  },
+  "progress-circle-sizes": {
+    loader: () => import("./progress-circle/sizes").then((m) => m.Sizes),
+    file: "cn/progress-circle/sizes.tsx",
+  },
+  "progress-circle-colors": {
+    loader: () => import("./progress-circle/colors").then((m) => m.Colors),
+    file: "cn/progress-circle/colors.tsx",
+  },
+  "progress-circle-indeterminate": {
+    loader: () => import("./progress-circle/indeterminate").then((m) => m.Indeterminate),
+    file: "cn/progress-circle/indeterminate.tsx",
+  },
+  "progress-circle-with-label": {
+    loader: () => import("./progress-circle/with-label").then((m) => m.WithLabel),
+    file: "cn/progress-circle/with-label.tsx",
+  },
+  "progress-circle-custom-svg": {
+    loader: () => import("./progress-circle/custom-svg").then((m) => m.CustomSvg),
+    file: "cn/progress-circle/custom-svg.tsx",
+  },
+  // Modal demos
+  "modal-default": {
+    loader: () => import("./modal/default").then((m) => m.Default),
+    file: "cn/modal/default.tsx",
+  },
+  "modal-placements": {
+    loader: () => import("./modal/placements").then((m) => m.Placements),
+    file: "cn/modal/placements.tsx",
+  },
+  "modal-backdrop-variants": {
+    loader: () => import("./modal/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "cn/modal/backdrop-variants.tsx",
+  },
+  "modal-scroll-comparison": {
+    loader: () => import("./modal/scroll-comparison").then((m) => m.ScrollComparison),
+    file: "cn/modal/scroll-comparison.tsx",
+  },
+  "modal-dismiss-behavior": {
+    loader: () => import("./modal/dismiss-behavior").then((m) => m.DismissBehavior),
+    file: "cn/modal/dismiss-behavior.tsx",
+  },
+  "modal-with-form": {
+    loader: () => import("./modal/with-form").then((m) => m.WithForm),
+    file: "cn/modal/with-form.tsx",
+  },
+  "modal-controlled": {
+    loader: () => import("./modal/controlled").then((m) => m.Controlled),
+    file: "cn/modal/controlled.tsx",
+  },
+  "modal-custom-trigger": {
+    loader: () => import("./modal/custom-trigger").then((m) => m.CustomTrigger),
+    file: "cn/modal/custom-trigger.tsx",
+  },
+  "modal-custom-backdrop": {
+    loader: () => import("./modal/custom-backdrop").then((m) => m.CustomBackdrop),
+    file: "cn/modal/custom-backdrop.tsx",
+  },
+  "modal-custom-animations": {
+    loader: () => import("./modal/custom-animations").then((m) => m.CustomAnimations),
+    file: "cn/modal/custom-animations.tsx",
+  },
+  "modal-sizes": {
+    loader: () => import("./modal/sizes").then((m) => m.Sizes),
+    file: "cn/modal/sizes.tsx",
+  },
+  "modal-close-methods": {
+    loader: () => import("./modal/close-methods").then((m) => m.CloseMethods),
+    file: "cn/modal/close-methods.tsx",
+  },
+  "modal-custom-portal": {
+    loader: () => import("./modal/custom-portal").then((m) => m.CustomPortal),
+    file: "cn/modal/custom-portal.tsx",
+  },
+  // NumberField demos
+  "number-field-basic": {
+    loader: () => import("./number-field/basic").then((m) => m.Basic),
+    file: "cn/number-field/basic.tsx",
+  },
+  "number-field-with-description": {
+    loader: () => import("./number-field/with-description").then((m) => m.WithDescription),
+    file: "cn/number-field/with-description.tsx",
+  },
+  "number-field-required": {
+    loader: () => import("./number-field/required").then((m) => m.Required),
+    file: "cn/number-field/required.tsx",
+  },
+  "number-field-validation": {
+    loader: () => import("./number-field/validation").then((m) => m.Validation),
+    file: "cn/number-field/validation.tsx",
+  },
+  "number-field-disabled": {
+    loader: () => import("./number-field/disabled").then((m) => m.Disabled),
+    file: "cn/number-field/disabled.tsx",
+  },
+  "number-field-full-width": {
+    loader: () => import("./number-field/full-width").then((m) => m.FullWidth),
+    file: "cn/number-field/full-width.tsx",
+  },
+  "number-field-controlled": {
+    loader: () => import("./number-field/controlled").then((m) => m.Controlled),
+    file: "cn/number-field/controlled.tsx",
+  },
+  "number-field-with-validation": {
+    loader: () => import("./number-field/with-validation").then((m) => m.WithValidation),
+    file: "cn/number-field/with-validation.tsx",
+  },
+  "number-field-with-step": {
+    loader: () => import("./number-field/with-step").then((m) => m.WithStep),
+    file: "cn/number-field/with-step.tsx",
+  },
+  "number-field-with-format-options": {
+    loader: () => import("./number-field/with-format-options").then((m) => m.WithFormatOptions),
+    file: "cn/number-field/with-format-options.tsx",
+  },
+  "number-field-custom-icons": {
+    loader: () => import("./number-field/custom-icons").then((m) => m.CustomIcons),
+    file: "cn/number-field/custom-icons.tsx",
+  },
+  "number-field-on-surface": {
+    loader: () => import("./number-field/on-surface").then((m) => m.OnSurface),
+    file: "cn/number-field/on-surface.tsx",
+  },
+  "number-field-with-chevrons": {
+    loader: () => import("./number-field/with-chevrons").then((m) => m.WithChevrons),
+    file: "cn/number-field/with-chevrons.tsx",
+  },
+  "number-field-form-example": {
+    loader: () => import("./number-field/form-example").then((m) => m.FormExample),
+    file: "cn/number-field/form-example.tsx",
+  },
+  "number-field-variants": {
+    loader: () => import("./number-field/variants").then((m) => m.Variants),
+    file: "cn/number-field/variants.tsx",
+  },
+  "number-field-custom-render-function": {
+    loader: () =>
+      import("./number-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/number-field/custom-render-function.tsx",
+  },
+  // Pagination demos
+  "pagination-basic": {
+    loader: () => import("./pagination/basic").then((m) => m.PaginationBasic),
+    file: "cn/pagination/basic.tsx",
+  },
+  "pagination-sizes": {
+    loader: () => import("./pagination/sizes").then((m) => m.PaginationSizes),
+    file: "cn/pagination/sizes.tsx",
+  },
+  "pagination-with-ellipsis": {
+    loader: () => import("./pagination/with-ellipsis").then((m) => m.PaginationWithEllipsis),
+    file: "cn/pagination/with-ellipsis.tsx",
+  },
+  "pagination-simple-prev-next": {
+    loader: () => import("./pagination/simple-prev-next").then((m) => m.PaginationSimplePrevNext),
+    file: "cn/pagination/simple-prev-next.tsx",
+  },
+  "pagination-with-summary": {
+    loader: () => import("./pagination/with-summary").then((m) => m.PaginationWithSummary),
+    file: "cn/pagination/with-summary.tsx",
+  },
+  "pagination-custom-icons": {
+    loader: () => import("./pagination/custom-icons").then((m) => m.PaginationCustomIcons),
+    file: "cn/pagination/custom-icons.tsx",
+  },
+  "pagination-controlled": {
+    loader: () => import("./pagination/controlled").then((m) => m.PaginationControlled),
+    file: "cn/pagination/controlled.tsx",
+  },
+  "pagination-disabled": {
+    loader: () => import("./pagination/disabled").then((m) => m.PaginationDisabled),
+    file: "cn/pagination/disabled.tsx",
+  },
+  // Select demos
+  "select-default": {
+    loader: () => import("./select/default").then((m) => m.Default),
+    file: "cn/select/default.tsx",
+  },
+  "select-with-description": {
+    loader: () => import("./select/with-description").then((m) => m.WithDescription),
+    file: "cn/select/with-description.tsx",
+  },
+  "select-multiple-select": {
+    loader: () => import("./select/multiple-select").then((m) => m.MultipleSelect),
+    file: "cn/select/multiple-select.tsx",
+  },
+  "select-with-sections": {
+    loader: () => import("./select/with-sections").then((m) => m.WithSections),
+    file: "cn/select/with-sections.tsx",
+  },
+  "select-with-disabled-options": {
+    loader: () => import("./select/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "cn/select/with-disabled-options.tsx",
+  },
+  "select-custom-indicator": {
+    loader: () => import("./select/custom-indicator").then((m) => m.CustomIndicator),
+    file: "cn/select/custom-indicator.tsx",
+  },
+  "select-required": {
+    loader: () => import("./select/required").then((m) => m.Required),
+    file: "cn/select/required.tsx",
+  },
+  "select-full-width": {
+    loader: () => import("./select/full-width").then((m) => m.FullWidth),
+    file: "cn/select/full-width.tsx",
+  },
+  "select-on-surface": {
+    loader: () => import("./select/on-surface").then((m) => m.OnSurface),
+    file: "cn/select/on-surface.tsx",
+  },
+  "select-custom-value": {
+    loader: () => import("./select/custom-value").then((m) => m.CustomValue),
+    file: "cn/select/custom-value.tsx",
+  },
+  "select-custom-value-multiple": {
+    loader: () => import("./select/custom-value-multiple").then((m) => m.CustomValueMultiple),
+    file: "cn/select/custom-value-multiple.tsx",
+  },
+  "select-controlled": {
+    loader: () => import("./select/controlled").then((m) => m.Controlled),
+    file: "cn/select/controlled.tsx",
+  },
+  "select-controlled-multiple": {
+    loader: () => import("./select/controlled-multiple").then((m) => m.ControlledMultiple),
+    file: "cn/select/controlled-multiple.tsx",
+  },
+  "select-controlled-open-state": {
+    loader: () => import("./select/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "cn/select/controlled-open-state.tsx",
+  },
+  "select-asynchronous-loading": {
+    loader: () => import("./select/asynchronous-loading").then((m) => m.AsynchronousLoading),
+    file: "cn/select/asynchronous-loading.tsx",
+  },
+  "select-disabled": {
+    loader: () => import("./select/disabled").then((m) => m.Disabled),
+    file: "cn/select/disabled.tsx",
+  },
+  "select-variants": {
+    loader: () => import("./select/variants").then((m) => m.Variants),
+    file: "cn/select/variants.tsx",
+  },
+  "select-custom-render-function": {
+    loader: () => import("./select/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/select/custom-render-function.tsx",
+  },
+  // SearchField demos
+  "search-field-basic": {
+    loader: () => import("./search-field/basic").then((m) => m.Basic),
+    file: "cn/search-field/basic.tsx",
+  },
+  "search-field-with-description": {
+    loader: () => import("./search-field/with-description").then((m) => m.WithDescription),
+    file: "cn/search-field/with-description.tsx",
+  },
+  "search-field-required": {
+    loader: () => import("./search-field/required").then((m) => m.Required),
+    file: "cn/search-field/required.tsx",
+  },
+  "search-field-validation": {
+    loader: () => import("./search-field/validation").then((m) => m.Validation),
+    file: "cn/search-field/validation.tsx",
+  },
+  "search-field-disabled": {
+    loader: () => import("./search-field/disabled").then((m) => m.Disabled),
+    file: "cn/search-field/disabled.tsx",
+  },
+  "search-field-full-width": {
+    loader: () => import("./search-field/full-width").then((m) => m.FullWidth),
+    file: "cn/search-field/full-width.tsx",
+  },
+  "search-field-controlled": {
+    loader: () => import("./search-field/controlled").then((m) => m.Controlled),
+    file: "cn/search-field/controlled.tsx",
+  },
+  "search-field-with-validation": {
+    loader: () => import("./search-field/with-validation").then((m) => m.WithValidation),
+    file: "cn/search-field/with-validation.tsx",
+  },
+  "search-field-custom-icons": {
+    loader: () => import("./search-field/custom-icons").then((m) => m.CustomIcons),
+    file: "cn/search-field/custom-icons.tsx",
+  },
+  "search-field-on-surface": {
+    loader: () => import("./search-field/on-surface").then((m) => m.OnSurface),
+    file: "cn/search-field/on-surface.tsx",
+  },
+  "search-field-form-example": {
+    loader: () => import("./search-field/form-example").then((m) => m.FormExample),
+    file: "cn/search-field/form-example.tsx",
+  },
+  "search-field-with-keyboard-shortcut": {
+    loader: () =>
+      import("./search-field/with-keyboard-shortcut").then((m) => m.WithKeyboardShortcut),
+    file: "cn/search-field/with-keyboard-shortcut.tsx",
+  },
+  "search-field-variants": {
+    loader: () => import("./search-field/variants").then((m) => m.Variants),
+    file: "cn/search-field/variants.tsx",
+  },
+  "search-field-custom-render-function": {
+    loader: () =>
+      import("./search-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/search-field/custom-render-function.tsx",
+  },
+  // ScrollShadow demos
+  "scroll-shadow-default": {
+    loader: () => import("./scroll-shadow/default").then((m) => m.default),
+    file: "cn/scroll-shadow/default.tsx",
+  },
+  "scroll-shadow-orientation": {
+    loader: () => import("./scroll-shadow/orientation").then((m) => m.default),
+    file: "cn/scroll-shadow/orientation.tsx",
+  },
+  "scroll-shadow-hide-scroll-bar": {
+    loader: () => import("./scroll-shadow/hide-scroll-bar").then((m) => m.default),
+    file: "cn/scroll-shadow/hide-scroll-bar.tsx",
+  },
+  "scroll-shadow-custom-size": {
+    loader: () => import("./scroll-shadow/custom-size").then((m) => m.default),
+    file: "cn/scroll-shadow/custom-size.tsx",
+  },
+  "scroll-shadow-visibility-change": {
+    loader: () => import("./scroll-shadow/visibility-change").then((m) => m.default),
+    file: "cn/scroll-shadow/visibility-change.tsx",
+  },
+  "scroll-shadow-with-card": {
+    loader: () => import("./scroll-shadow/with-card").then((m) => m.default),
+    file: "cn/scroll-shadow/with-card.tsx",
+  },
+  // Slider demos
+  "slider-default": {
+    loader: () => import("./slider/default").then((m) => m.Default),
+    file: "cn/slider/default.tsx",
+  },
+  "slider-vertical": {
+    loader: () => import("./slider/vertical").then((m) => m.Vertical),
+    file: "cn/slider/vertical.tsx",
+  },
+  "slider-range": {
+    loader: () => import("./slider/range").then((m) => m.Range),
+    file: "cn/slider/range.tsx",
+  },
+  "slider-disabled": {
+    loader: () => import("./slider/disabled").then((m) => m.Disabled),
+    file: "cn/slider/disabled.tsx",
+  },
+  "slider-custom-render-function": {
+    loader: () => import("./slider/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "cn/slider/custom-render-function.tsx",
+  },
+  // Description demos
+  "description-basic": {
+    loader: () => import("./description/basic").then((m) => m.Basic),
+    file: "cn/description/basic.tsx",
+  },
+  // FieldError demos
+  "field-error-basic": {
+    loader: () => import("./field-error/basic").then((m) => m.Basic),
+    file: "cn/field-error/basic.tsx",
+  },
+};
+
+export function getDemo(name: string): DemoItem | undefined {
+  return demos[name];
+}
diff --git a/apps/docs/src/demos/cn/input-group/default.tsx b/apps/docs/src/demos/cn/input-group/default.tsx
new file mode 100644
index 0000000..a3c4186
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/default.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Default() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>邮箱地址</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/disabled.tsx b/apps/docs/src/demos/cn/input-group/disabled.tsx
new file mode 100644
index 0000000..69cb586
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/disabled.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField
+        isDisabled
+        className="w-full max-w-[280px]"
+        defaultValue="name@email.com"
+        name="email"
+      >
+        <Label>邮箱地址</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" />
+        </InputGroup>
+      </TextField>
+      <TextField isDisabled className="w-full max-w-[280px]" defaultValue="10" name="price">
+        <Label>设置价格</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/full-width.tsx b/apps/docs/src/demos/cn/input-group/full-width.tsx
new file mode 100644
index 0000000..2af8181
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/full-width.tsx
@@ -0,0 +1,27 @@
+import {Envelope, Eye} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="email">
+        <Label>邮箱地址</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField fullWidth name="password">
+        <Label>密码</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Input placeholder="输入密码" type="password" />
+          <InputGroup.Suffix>
+            <Eye className="size-4 text-muted" />
+          </InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/index.ts b/apps/docs/src/demos/cn/input-group/index.ts
new file mode 100644
index 0000000..a273f05
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/index.ts
@@ -0,0 +1,20 @@
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {PasswordWithToggle} from "./password-with-toggle";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithBadgeSuffix} from "./with-badge-suffix";
+export {WithCopySuffix} from "./with-copy-suffix";
+export {WithIconPrefixAndCopySuffix} from "./with-icon-prefix-and-copy-suffix";
+export {WithIconPrefixAndTextSuffix} from "./with-icon-prefix-and-text-suffix";
+export {WithKeyboardShortcut} from "./with-keyboard-shortcut";
+export {WithLoadingSuffix} from "./with-loading-suffix";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithTextPrefix} from "./with-text-prefix";
+export {WithTextSuffix} from "./with-text-suffix";
+export {WithTextArea} from "./with-textarea";
diff --git a/apps/docs/src/demos/cn/input-group/invalid.tsx b/apps/docs/src/demos/cn/input-group/invalid.tsx
new file mode 100644
index 0000000..c25199c
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/invalid.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {FieldError, InputGroup, Label, TextField} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="email">
+        <Label>邮箱地址</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+        <FieldError>请输入有效的邮箱地址</FieldError>
+      </TextField>
+      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="price">
+        <Label>设置价格</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <FieldError>价格必须大于 0</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/on-surface.tsx b/apps/docs/src/demos/cn/input-group/on-surface.tsx
new file mode 100644
index 0000000..9a5fc75
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/on-surface.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, Surface, TextField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="rounded-2xl p-6">
+      <TextField className="w-full max-w-[280px]" name="email">
+        <Label>邮箱地址</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+        <Description>我们不会将此邮箱分享给任何人</Description>
+      </TextField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/password-with-toggle.tsx b/apps/docs/src/demos/cn/input-group/password-with-toggle.tsx
new file mode 100644
index 0000000..aa3e38e
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/password-with-toggle.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Eye, EyeSlash} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+export function PasswordWithToggle() {
+  const [isVisible, setIsVisible] = useState(false);
+
+  return (
+    <TextField className="w-full max-w-[280px]" name="password">
+      <Label>密码</Label>
+      <InputGroup>
+        <InputGroup.Input
+          className="w-full max-w-[280px]"
+          type={isVisible ? "text" : "password"}
+          value={isVisible ? "87$2h.3diua" : "••••••••"}
+        />
+        <InputGroup.Suffix className="pr-0">
+          <Button
+            isIconOnly
+            aria-label={isVisible ? "隐藏密码" : "显示密码"}
+            size="sm"
+            variant="ghost"
+            onPress={() => setIsVisible(!isVisible)}
+          >
+            {isVisible ? <Eye className="size-4" /> : <EyeSlash className="size-4" />}
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/required.tsx b/apps/docs/src/demos/cn/input-group/required.tsx
new file mode 100644
index 0000000..b9010cc
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/required.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField isRequired className="w-full max-w-[280px]" name="email">
+        <Label>邮箱地址</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField isRequired className="w-full max-w-[280px]" name="price">
+        <Label>设置价格</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <Description>客户将支付的价格</Description>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/variants.tsx b/apps/docs/src/demos/cn/input-group/variants.tsx
new file mode 100644
index 0000000..9d17c43
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/variants.tsx
@@ -0,0 +1,27 @@
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField className="w-[280px]" name="primary">
+        <Label>主要变体</Label>
+        <InputGroup variant="primary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField className="w-[280px]" name="secondary">
+        <Label>次要变体</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-badge-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-badge-suffix.tsx
new file mode 100644
index 0000000..974f978
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-badge-suffix.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Chip, InputGroup, TextField} from "@heroui/react";
+
+export function WithBadgeSuffix() {
+  return (
+    <TextField aria-label="邮箱地址" className="w-full max-w-[280px]" name="email">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="邮箱地址" />
+        <InputGroup.Suffix className="pr-2">
+          <Chip color="accent" size="md" variant="soft">
+            Pro
+          </Chip>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-copy-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-copy-suffix.tsx
new file mode 100644
index 0000000..89958b2
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-copy-suffix.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Copy} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithCopySuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>网站</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="复制" size="sm" variant="ghost">
+            <Copy className="size-4" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-copy-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-copy-suffix.tsx
new file mode 100644
index 0000000..24419df
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-copy-suffix.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Copy, Globe} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithIconPrefixAndCopySuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>网站</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Globe className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="复制" size="sm" variant="ghost">
+            <Copy className="size-4" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-text-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-text-suffix.tsx
new file mode 100644
index 0000000..45aebab
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-icon-prefix-and-text-suffix.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Globe} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithIconPrefixAndTextSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
+      <Label>网站</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Globe className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-keyboard-shortcut.tsx b/apps/docs/src/demos/cn/input-group/with-keyboard-shortcut.tsx
new file mode 100644
index 0000000..30bd004
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-keyboard-shortcut.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {InputGroup, Kbd, TextField} from "@heroui/react";
+
+export function WithKeyboardShortcut() {
+  return (
+    <TextField aria-label="命令" className="w-full max-w-[280px]" name="command">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="命令" />
+        <InputGroup.Suffix className="pr-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="command" />
+            <Kbd.Content>K</Kbd.Content>
+          </Kbd>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-loading-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-loading-suffix.tsx
new file mode 100644
index 0000000..1dd49a1
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-loading-suffix.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {InputGroup, Spinner, TextField} from "@heroui/react";
+
+export function WithLoadingSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="发送中…" name="status">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>
+          <Spinner className="size-4" />
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-prefix-and-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..a2ea41e
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-prefix-and-suffix.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="10" name="price">
+      <Label>设置价格</Label>
+      <InputGroup>
+        <InputGroup.Prefix>$</InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[200px]" type="number" />
+        <InputGroup.Suffix>USD</InputGroup.Suffix>
+      </InputGroup>
+      <Description>客户将支付的价格</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-prefix-icon.tsx b/apps/docs/src/demos/cn/input-group/with-prefix-icon.tsx
new file mode 100644
index 0000000..0c2b91f
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-prefix-icon.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>邮箱地址</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+      <Description>我们不会将此邮箱分享给任何人</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-suffix-icon.tsx b/apps/docs/src/demos/cn/input-group/with-suffix-icon.tsx
new file mode 100644
index 0000000..7df138c
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-suffix-icon.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>邮箱地址</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        <InputGroup.Suffix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Suffix>
+      </InputGroup>
+      <Description>我们不会发送垃圾邮件</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-text-prefix.tsx b/apps/docs/src/demos/cn/input-group/with-text-prefix.tsx
new file mode 100644
index 0000000..9b07952
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-text-prefix.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithTextPrefix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>网站</Label>
+      <InputGroup>
+        <InputGroup.Prefix>https://</InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-text-suffix.tsx b/apps/docs/src/demos/cn/input-group/with-text-suffix.tsx
new file mode 100644
index 0000000..edfb486
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-text-suffix.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithTextSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
+      <Label>网站</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-group/with-textarea.tsx b/apps/docs/src/demos/cn/input-group/with-textarea.tsx
new file mode 100644
index 0000000..6e70044
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-group/with-textarea.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons";
+import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react";
+import {useState} from "react";
+
+export function WithTextArea() {
+  const [value, setValue] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = () => {
+    if (!value.trim()) return;
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setIsSubmitting(false);
+      setValue("");
+    }, 1000);
+  };
+
+  return (
+    <TextField fullWidth aria-label="提示输入" className="flex w-sm flex-col sm:w-lg" name="prompt">
+      <InputGroup fullWidth className="flex flex-col gap-2 rounded-3xl py-2">
+        <InputGroup.Prefix className="px-3 py-0">
+          <Button aria-label="添加上下文" size="sm" variant="outline">
+            <At />
+            添加上下文
+          </Button>
+        </InputGroup.Prefix>
+        <InputGroup.TextArea
+          className="w-full resize-none px-3.5 py-0"
+          placeholder="分配任务或提问…"
+          rows={5}
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+        />
+        <InputGroup.Suffix className="flex w-full items-center gap-1.5 px-3 py-0">
+          <Tooltip delay={0}>
+            <Button isIconOnly aria-label="附加文件" size="sm" variant="tertiary">
+              <Plus />
+            </Button>
+            <Tooltip.Content>
+              <p className="text-xs">添加文件等</p>
+            </Tooltip.Content>
+          </Tooltip>
+          <Tooltip delay={0}>
+            <Button isIconOnly aria-label="连接应用" size="sm" variant="tertiary">
+              <PlugConnection />
+            </Button>
+            <Tooltip.Content>
+              <p className="text-xs">连接应用</p>
+            </Tooltip.Content>
+          </Tooltip>
+          <div className="ml-auto flex items-center gap-1.5">
+            <Tooltip delay={0}>
+              <Button isIconOnly aria-label="语音输入" size="sm" variant="ghost">
+                <Microphone />
+              </Button>
+              <Tooltip.Content>
+                <p className="text-xs">语音输入</p>
+              </Tooltip.Content>
+            </Tooltip>
+            <Tooltip delay={0}>
+              <Button
+                isIconOnly
+                aria-label="发送提示"
+                isDisabled={!value.trim()}
+                isPending={isSubmitting}
+                onPress={handleSubmit}
+              >
+                {({isPending}) => (isPending ? <Spinner color="current" size="sm" /> : <ArrowUp />)}
+              </Button>
+              <Tooltip.Content className="flex items-center gap-1">
+                <p className="text-xs">发送</p>
+                <Kbd className="h-4 rounded-sm px-1">
+                  <Kbd.Abbr keyValue="enter" />
+                </Kbd>
+              </Tooltip.Content>
+            </Tooltip>
+          </div>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/basic.tsx b/apps/docs/src/demos/cn/input-otp/basic.tsx
new file mode 100644
index 0000000..176721e
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/basic.tsx
@@ -0,0 +1,31 @@
+import {InputOTP, Label, Link} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <div className="flex flex-col gap-1">
+        <Label>验证账户</Label>
+        <p className="text-sm text-muted">我们已向 a****@gmail.com 发送验证码</p>
+      </div>
+      <InputOTP maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <div className="flex items-center gap-[5px] px-1 pt-1">
+        <p className="text-sm text-muted">没有收到验证码？</p>
+        <Link className="text-foreground underline" href="#">
+          重新发送
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/controlled.tsx b/apps/docs/src/demos/cn/input-otp/controlled.tsx
new file mode 100644
index 0000000..66f0c2f
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/controlled.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Description, InputOTP, Label} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>验证账户</Label>
+      <InputOTP maxLength={6} value={value} onChange={setValue}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>
+        {value.length > 0 ? (
+          <>
+            值：{value} ({value.length}/6) •{" "}
+            <button className="font-medium text-foreground underline" onClick={() => setValue("")}>
+              Clear
+            </button>
+          </>
+        ) : (
+          "请输入 6 位验证码"
+        )}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/disabled.tsx b/apps/docs/src/demos/cn/input-otp/disabled.tsx
new file mode 100644
index 0000000..7054c3d
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/disabled.tsx
@@ -0,0 +1,23 @@
+import {Description, InputOTP, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label isDisabled>验证账户</Label>
+      <Description>验证码校验当前已禁用</Description>
+      <InputOTP isDisabled maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/form-example.tsx b/apps/docs/src/demos/cn/input-otp/form-example.tsx
new file mode 100644
index 0000000..f08a7e1
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/form-example.tsx
@@ -0,0 +1,89 @@
+"use client";
+
+import {Button, Description, Form, InputOTP, Label, Link, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState("");
+  const [error, setError] = React.useState("");
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    setError("");
+
+    if (value.length !== 6) {
+      setError("请输入全部 6 位数字");
+
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      if (value === "123456") {
+        console.log("Code verified successfully!");
+        setValue("");
+      } else {
+        setError("验证码无效，请重试。");
+      }
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <div className="flex flex-col gap-2">
+        <Label>双重身份验证</Label>
+        <Description>请输入身份验证器应用中的 6 位验证码</Description>
+        <InputOTP
+          isInvalid={!!error}
+          maxLength={6}
+          value={value}
+          onChange={(val) => {
+            setValue(val);
+            setError("");
+          }}
+        >
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <span className="field-error" data-visible={!!error} id="code-error">
+          {error}
+        </span>
+      </div>
+      <Button
+        className="w-full"
+        isDisabled={value.length !== 6}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            验证中…
+          </>
+        ) : (
+          "验证"
+        )}
+      </Button>
+      <div className="flex items-center justify-center gap-1">
+        <p className="text-sm text-muted">遇到问题？</p>
+        <Link className="text-sm text-foreground underline" href="#">
+          使用备用码
+        </Link>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/four-digits.tsx b/apps/docs/src/demos/cn/input-otp/four-digits.tsx
new file mode 100644
index 0000000..24ca9a1
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/four-digits.tsx
@@ -0,0 +1,17 @@
+import {InputOTP, Label} from "@heroui/react";
+
+export function FourDigits() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>输入 PIN</Label>
+      <InputOTP maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/index.ts b/apps/docs/src/demos/cn/input-otp/index.ts
new file mode 100644
index 0000000..b38ddaf
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FourDigits} from "./four-digits";
+export {OnComplete} from "./on-complete";
+export {OnSurface} from "./on-surface";
+export {Variants} from "./variants";
+export {WithPattern} from "./with-pattern";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/cn/input-otp/on-complete.tsx b/apps/docs/src/demos/cn/input-otp/on-complete.tsx
new file mode 100644
index 0000000..0bbee48
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/on-complete.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import {Button, Form, InputOTP, Label, Spinner} from "@heroui/react";
+import React from "react";
+
+export function OnComplete() {
+  const [value, setValue] = React.useState("");
+  const [isComplete, setIsComplete] = React.useState(false);
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+  const handleComplete = (code: string) => {
+    setIsComplete(true);
+
+    console.log("Code complete:", code);
+  };
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+
+    setIsSubmitting(true);
+    // Simulate API call
+    setTimeout(() => {
+      setIsSubmitting(false);
+      setValue("");
+      setIsComplete(false);
+    }, 2000);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-2" onSubmit={handleSubmit}>
+      <Label>验证账户</Label>
+      <InputOTP
+        maxLength={6}
+        value={value}
+        onComplete={handleComplete}
+        onChange={(val) => {
+          setValue(val);
+          setIsComplete(false);
+        }}
+      >
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Button
+        className="mt-2 w-full"
+        isDisabled={!isComplete}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            验证中…
+          </>
+        ) : (
+          "验证验证码"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/on-surface.tsx b/apps/docs/src/demos/cn/input-otp/on-surface.tsx
new file mode 100644
index 0000000..bf53f7a
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/on-surface.tsx
@@ -0,0 +1,31 @@
+import {InputOTP, Label, Link, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full flex-col gap-2 rounded-3xl p-6">
+      <div className="flex flex-col gap-1">
+        <Label>验证账户</Label>
+        <p className="text-sm text-muted">我们已向 a****@gmail.com 发送验证码</p>
+      </div>
+      <InputOTP maxLength={6} variant="secondary">
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <div className="flex items-center gap-[5px] px-1 pt-1">
+        <p className="text-sm text-muted">没有收到验证码？</p>
+        <Link className="text-foreground underline" href="#">
+          重新发送
+        </Link>
+      </div>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/variants.tsx b/apps/docs/src/demos/cn/input-otp/variants.tsx
new file mode 100644
index 0000000..a6a3442
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/variants.tsx
@@ -0,0 +1,40 @@
+import {InputOTP, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <Label>主要变体</Label>
+        <InputOTP maxLength={6} variant="primary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label>次要变体</Label>
+        <InputOTP maxLength={6} variant="secondary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/with-pattern.tsx b/apps/docs/src/demos/cn/input-otp/with-pattern.tsx
new file mode 100644
index 0000000..bba3f82
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/with-pattern.tsx
@@ -0,0 +1,23 @@
+import {Description, InputOTP, Label, REGEXP_ONLY_CHARS} from "@heroui/react";
+
+export function WithPattern() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>输入验证码（仅字母）</Label>
+      <Description>仅允许输入字母</Description>
+      <InputOTP maxLength={6} pattern={REGEXP_ONLY_CHARS}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input-otp/with-validation.tsx b/apps/docs/src/demos/cn/input-otp/with-validation.tsx
new file mode 100644
index 0000000..5c48815
--- /dev/null
+++ b/apps/docs/src/demos/cn/input-otp/with-validation.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {Button, Description, Form, InputOTP, Label} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState("");
+  const [isInvalid, setIsInvalid] = React.useState(false);
+
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const code = formData.get("code");
+
+    if (code !== "123456") {
+      setIsInvalid(true);
+
+      return;
+    }
+
+    setIsInvalid(false);
+    setValue("");
+
+    alert("验证码校验成功！");
+  };
+
+  const handleChange = (val: string) => {
+    setValue(val);
+    setIsInvalid(false);
+  };
+
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Form className="flex flex-col gap-2" onSubmit={onSubmit}>
+        <Label>验证账户</Label>
+        <Description>提示：验证码为 123456</Description>
+        <InputOTP
+          aria-describedby={isInvalid ? "code-error" : undefined}
+          isInvalid={isInvalid}
+          maxLength={6}
+          name="code"
+          value={value}
+          onChange={handleChange}
+        >
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <span className="field-error" data-visible={isInvalid} id="code-error">
+          验证码无效，请重试。
+        </span>
+        <Button isDisabled={value.length !== 6} type="submit">
+          提交
+        </Button>
+      </Form>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input/basic.tsx b/apps/docs/src/demos/cn/input/basic.tsx
new file mode 100644
index 0000000..cd5494c
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/basic.tsx
@@ -0,0 +1,5 @@
+import {Input} from "@heroui/react";
+
+export function Basic() {
+  return <Input aria-label="姓名" className="w-64" placeholder="输入你的姓名" />;
+}
diff --git a/apps/docs/src/demos/cn/input/controlled.tsx b/apps/docs/src/demos/cn/input/controlled.tsx
new file mode 100644
index 0000000..b548815
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/controlled.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Input} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("heroui.com");
+
+  return (
+    <div className="flex w-80 flex-col gap-2">
+      <Input
+        aria-label="域名"
+        placeholder="域名"
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+      <span className="px-1 text-sm text-muted">https://{value || "你的域名"}</span>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input/full-width.tsx b/apps/docs/src/demos/cn/input/full-width.tsx
new file mode 100644
index 0000000..8c7c7f0
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/full-width.tsx
@@ -0,0 +1,9 @@
+import {Input} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <Input fullWidth placeholder="全宽输入框" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input/index.ts b/apps/docs/src/demos/cn/input/index.ts
new file mode 100644
index 0000000..e9ddd94
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Types} from "./types";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/input/on-surface.tsx b/apps/docs/src/demos/cn/input/on-surface.tsx
new file mode 100644
index 0000000..cbd00a5
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/on-surface.tsx
@@ -0,0 +1,9 @@
+import {Input, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex h-[180px] w-[280px] items-center justify-center rounded-3xl bg-surface p-4">
+      <Input className="w-full" placeholder="你的姓名" variant="secondary" />
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input/types.tsx b/apps/docs/src/demos/cn/input/types.tsx
new file mode 100644
index 0000000..dae3311
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/types.tsx
@@ -0,0 +1,20 @@
+import {Input, Label} from "@heroui/react";
+
+export function Types() {
+  return (
+    <div className="flex w-80 flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-email">邮箱</Label>
+        <Input id="input-type-email" placeholder="jane@example.com" type="email" />
+      </div>
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-number">年龄</Label>
+        <Input id="input-type-number" min={0} placeholder="30" type="number" />
+      </div>
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-password">密码</Label>
+        <Input id="input-type-password" placeholder="••••••••" type="password" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/input/variants.tsx b/apps/docs/src/demos/cn/input/variants.tsx
new file mode 100644
index 0000000..69cf46f
--- /dev/null
+++ b/apps/docs/src/demos/cn/input/variants.tsx
@@ -0,0 +1,10 @@
+import {Input} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex w-[240px] flex-col gap-2">
+      <Input fullWidth placeholder="主要输入框" variant="primary" />
+      <Input fullWidth placeholder="次要输入框" variant="secondary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/basic.tsx b/apps/docs/src/demos/cn/kbd/basic.tsx
new file mode 100644
index 0000000..aea9422
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/basic.tsx
@@ -0,0 +1,24 @@
+import {Kbd} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Kbd>
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>K</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="shift" />
+        <Kbd.Content>P</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="ctrl" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="option" />
+        <Kbd.Content>D</Kbd.Content>
+      </Kbd>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/index.ts b/apps/docs/src/demos/cn/kbd/index.ts
new file mode 100644
index 0000000..968a638
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {NavigationKeys} from "./navigation";
+export {InlineUsage} from "./inline";
+export {SpecialKeys} from "./special";
+export {InstructionalText} from "./instructional";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/kbd/inline.tsx b/apps/docs/src/demos/cn/kbd/inline.tsx
new file mode 100644
index 0000000..76a9dab
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/inline.tsx
@@ -0,0 +1,42 @@
+import {Kbd} from "@heroui/react";
+
+export function InlineUsage() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm">
+        按{" "}
+        <Kbd>
+          <Kbd.Content>Esc</Kbd.Content>
+        </Kbd>{" "}
+        关闭对话框。
+      </p>
+      <p className="text-sm">
+        使用{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>K</Kbd.Content>
+        </Kbd>{" "}
+        打开命令面板。
+      </p>
+      <p className="text-sm">
+        使用{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="up" />
+        </Kbd>{" "}
+        和{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="down" />
+        </Kbd>{" "}
+        方向键进行导航。
+      </p>
+      <p className="text-sm">
+        使用{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>S</Kbd.Content>
+        </Kbd>{" "}
+        定期保存你的工作。
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/instructional.tsx b/apps/docs/src/demos/cn/kbd/instructional.tsx
new file mode 100644
index 0000000..5380b90
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/instructional.tsx
@@ -0,0 +1,41 @@
+import {Kbd} from "@heroui/react";
+
+export function InstructionalText() {
+  return (
+    <div className="space-y-3">
+      <div className="rounded-lg bg-surface p-4">
+        <h4 className="mb-2 text-sm font-semibold">快捷操作</h4>
+        <ul className="space-y-2 text-sm">
+          <li>
+            • 打开搜索：{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>K</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • 切换侧边栏：{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>B</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • 新建文件：{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • 快速保存：{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </li>
+        </ul>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/navigation.tsx b/apps/docs/src/demos/cn/kbd/navigation.tsx
new file mode 100644
index 0000000..463da6f
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/navigation.tsx
@@ -0,0 +1,42 @@
+import {Kbd} from "@heroui/react";
+
+export function NavigationKeys() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span className="text-sm text-muted">方向键：</span>
+        <div className="flex items-center gap-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="up" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="down" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="left" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="right" />
+          </Kbd>
+        </div>
+      </div>
+      <div className="flex items-center gap-2">
+        <span className="text-sm text-muted">页面导航：</span>
+        <div className="flex items-center gap-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="pageup" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="pagedown" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="home" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="end" />
+          </Kbd>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/special.tsx b/apps/docs/src/demos/cn/kbd/special.tsx
new file mode 100644
index 0000000..c051909
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/special.tsx
@@ -0,0 +1,38 @@
+import {Kbd} from "@heroui/react";
+
+export function SpecialKeys() {
+  return (
+    <div className="space-y-3">
+      <p className="text-sm">
+        按{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="enter" />
+        </Kbd>{" "}
+        确认，或按{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="escape" />
+        </Kbd>{" "}
+        取消。
+      </p>
+      <p className="text-sm">
+        使用{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="tab" />
+        </Kbd>{" "}
+        在表单字段间切换，使用{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Abbr keyValue="tab" />
+        </Kbd>{" "}
+        返回上一项。
+      </p>
+      <p className="text-sm">
+        按住{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="space" />
+        </Kbd>{" "}
+        可临时启用平移模式。
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/kbd/variants.tsx b/apps/docs/src/demos/cn/kbd/variants.tsx
new file mode 100644
index 0000000..cc152d3
--- /dev/null
+++ b/apps/docs/src/demos/cn/kbd/variants.tsx
@@ -0,0 +1,65 @@
+import {Kbd} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>复制：</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>粘贴：</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>剪切：</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>撤销：</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>重做：</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/label/basic.tsx b/apps/docs/src/demos/cn/label/basic.tsx
new file mode 100644
index 0000000..96e4677
--- /dev/null
+++ b/apps/docs/src/demos/cn/label/basic.tsx
@@ -0,0 +1,10 @@
+import {Input, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor="name">姓名</Label>
+      <Input className="w-64" id="name" placeholder="输入你的姓名" type="text" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/label/index.ts b/apps/docs/src/demos/cn/label/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/cn/label/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/cn/link/basic.tsx b/apps/docs/src/demos/cn/link/basic.tsx
new file mode 100644
index 0000000..3b19ca7
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/basic.tsx
@@ -0,0 +1,10 @@
+import {Link} from "@heroui/react";
+
+export function LinkBasic() {
+  return (
+    <Link href="#">
+      立即行动
+      <Link.Icon />
+    </Link>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/custom-icon.tsx b/apps/docs/src/demos/cn/link/custom-icon.tsx
new file mode 100644
index 0000000..295e405
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/custom-icon.tsx
@@ -0,0 +1,21 @@
+import {ArrowUpRightFromSquare, Link as LinkIcon} from "@gravity-ui/icons";
+import {Link} from "@heroui/react";
+
+export function LinkCustomIcon() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Link href="#">
+        外部链接
+        <Link.Icon className="ml-1.5 size-3">
+          <ArrowUpRightFromSquare />
+        </Link.Icon>
+      </Link>
+      <Link className="gap-1" href="#">
+        前往页面
+        <Link.Icon className="size-3">
+          <LinkIcon />
+        </Link.Icon>
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/custom-render-function.tsx b/apps/docs/src/demos/cn/link/custom-render-function.tsx
new file mode 100644
index 0000000..19c16bd
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/custom-render-function.tsx
@@ -0,0 +1,12 @@
+"use client";
+
+import {Link} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Link href="#" render={(props) => <span {...props} data-custom="foo" />}>
+      立即行动
+      <Link.Icon />
+    </Link>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/icon-placement.tsx b/apps/docs/src/demos/cn/link/icon-placement.tsx
new file mode 100644
index 0000000..571c905
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/icon-placement.tsx
@@ -0,0 +1,16 @@
+import {Link} from "@heroui/react";
+
+export function LinkIconPlacement() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Link href="#">
+        图标在末尾（默认）
+        <Link.Icon />
+      </Link>
+      <Link className="gap-1" href="#">
+        <Link.Icon />
+        图标在开头
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/index.ts b/apps/docs/src/demos/cn/link/index.ts
new file mode 100644
index 0000000..ba4b1d9
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/index.ts
@@ -0,0 +1,5 @@
+export {LinkBasic as Basic} from "./basic";
+export {LinkCustomIcon as CustomIcon} from "./custom-icon";
+export {LinkIconPlacement as IconPlacement} from "./icon-placement";
+export {LinkUnderlineAndOffset as UnderlineAndOffset} from "./underline-and-offset";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/link/underline-and-offset.tsx b/apps/docs/src/demos/cn/link/underline-and-offset.tsx
new file mode 100644
index 0000000..88e3613
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/underline-and-offset.tsx
@@ -0,0 +1,53 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineAndOffset() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">默认悬浮下划线</p>
+        <Link href="#">
+          悬浮以查看下划线
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">始终显示下划线</p>
+        <Link className="underline" href="#">
+          下划线始终可见
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">无下划线</p>
+        <Link className="no-underline" href="#">
+          不带任何下划线的链接
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">调整下划线偏移</p>
+        <div className="flex flex-col gap-3">
+          <Link className="underline-offset-1" href="#">
+            偏移 1（1px 间距）
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-2" href="#">
+            偏移 2（2px 间距）
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-3" href="#">
+            偏移 3（3px 间距）
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-4" href="#">
+            偏移 4（4px 间距）
+            <Link.Icon />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/underline-offset.tsx b/apps/docs/src/demos/cn/link/underline-offset.tsx
new file mode 100644
index 0000000..4c60256
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/underline-offset.tsx
@@ -0,0 +1,20 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineOffset() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Link className="underline-offset-1" href="#">
+        偏移 1
+        <Link.Icon />
+      </Link>
+      <Link className="underline-offset-2" href="#">
+        偏移 2
+        <Link.Icon />
+      </Link>
+      <Link className="underline-offset-3" href="#">
+        偏移 3
+        <Link.Icon />
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/link/underline-variants.tsx b/apps/docs/src/demos/cn/link/underline-variants.tsx
new file mode 100644
index 0000000..f8fac66
--- /dev/null
+++ b/apps/docs/src/demos/cn/link/underline-variants.tsx
@@ -0,0 +1,31 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineVariants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">默认悬浮下划线</p>
+        <Link href="#">
+          悬浮以查看下划线
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">始终显示下划线</p>
+        <Link className="underline" href="#">
+          下划线始终可见
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">无下划线</p>
+        <Link className="no-underline" href="#">
+          无下划线的链接
+          <Link.Icon />
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/controlled.tsx b/apps/docs/src/demos/cn/list-box/controlled.tsx
new file mode 100644
index 0000000..2a8cdbc
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/controlled.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Check} from "@gravity-ui/icons";
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState<Selection>(new Set(["1"]));
+
+  const selectedItems = Array.from(selected);
+
+  return (
+    <div className="space-y-4">
+      <Surface className="w-[256px] rounded-3xl shadow-surface">
+        <ListBox
+          aria-label="用户"
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <ListBox.Item id="1" textValue="Bob">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Bob"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+              />
+              <Avatar.Fallback>B</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Bob</Label>
+              <Description>bob@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+          <ListBox.Item id="2" textValue="Fred">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Fred"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+              />
+              <Avatar.Fallback>F</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Fred</Label>
+              <Description>fred@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+          <ListBox.Item id="3" textValue="Martha">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Martha"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+              />
+              <Avatar.Fallback>M</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Martha</Label>
+              <Description>martha@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+        </ListBox>
+      </Surface>
+      <p className="text-sm text-muted">
+        已选：{selectedItems.length > 0 ? selectedItems.join("、") : "无"}
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/custom-check-icon.tsx b/apps/docs/src/demos/cn/list-box/custom-check-icon.tsx
new file mode 100644
index 0000000..3267828
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/custom-check-icon.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+
+export function CustomCheckIcon() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="用户" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Bob"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>B</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Fred"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+            />
+            <Avatar.Fallback>F</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/custom-render-function.tsx b/apps/docs/src/demos/cn/list-box/custom-render-function.tsx
new file mode 100644
index 0000000..6c147d4
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/custom-render-function.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {Avatar, Description, Label, ListBox} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ListBox
+      aria-label="用户"
+      className="w-[220px]"
+      render={(props) => <div {...props} data-custom="true" />}
+      selectionMode="single"
+    >
+      <ListBox.Item
+        id="1"
+        render={(props) => <span {...props} data-custom="foo" />}
+        textValue="Bob"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Bob"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+          />
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Bob</Label>
+          <Description>bob@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item
+        id="2"
+        render={(props) => <span {...props} data-custom="bar" />}
+        textValue="Fred"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Fred"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+          />
+          <Avatar.Fallback>F</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Fred</Label>
+          <Description>fred@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item
+        id="3"
+        render={(props) => <span {...props} data-custom="baz" />}
+        textValue="Martha"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Martha"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+          />
+          <Avatar.Fallback>M</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Martha</Label>
+          <Description>martha@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/default.tsx b/apps/docs/src/demos/cn/list-box/default.tsx
new file mode 100644
index 0000000..36883c2
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/default.tsx
@@ -0,0 +1,50 @@
+import {Avatar, Description, Label, ListBox} from "@heroui/react";
+
+export function Default() {
+  return (
+    <ListBox aria-label="用户" className="w-[220px]" selectionMode="single">
+      <ListBox.Item id="1" textValue="Bob">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Bob"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+          />
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Bob</Label>
+          <Description>bob@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="2" textValue="Fred">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Fred"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+          />
+          <Avatar.Fallback>F</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Fred</Label>
+          <Description>fred@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="3" textValue="Martha">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Martha"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+          />
+          <Avatar.Fallback>M</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Martha</Label>
+          <Description>martha@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/index.ts b/apps/docs/src/demos/cn/list-box/index.ts
new file mode 100644
index 0000000..e47aa11
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/index.ts
@@ -0,0 +1,10 @@
+// ListBox demos
+export {Controlled} from "./controlled";
+export {CustomCheckIcon} from "./custom-check-icon";
+export {Default} from "./default";
+export {MultiSelect} from "./multi-select";
+export {ScrollbarModes} from "./scrollbar-modes";
+export {Virtualization} from "./virtualization";
+export {WithDisabledItems} from "./with-disabled-items";
+export {WithSections} from "./with-sections";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/list-box/multi-select.tsx b/apps/docs/src/demos/cn/list-box/multi-select.tsx
new file mode 100644
index 0000000..2c1cde1
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/multi-select.tsx
@@ -0,0 +1,52 @@
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+
+export function MultiSelect() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="用户" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Bob"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>B</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Fred"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+            />
+            <Avatar.Fallback>F</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/scrollbar-modes.tsx b/apps/docs/src/demos/cn/list-box/scrollbar-modes.tsx
new file mode 100644
index 0000000..06220a8
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/scrollbar-modes.tsx
@@ -0,0 +1,84 @@
+import {ListBox, Surface} from "@heroui/react";
+
+type ScrollbarMode = {
+  id: string;
+  label: string;
+  scrollbar?: "thin" | "default" | "none";
+};
+
+const modes: ScrollbarMode[] = [
+  {
+    id: "heroui",
+    label: "HeroUI 纤细",
+    scrollbar: "thin",
+  },
+  {
+    id: "browser",
+    label: "浏览器默认",
+    scrollbar: "default",
+  },
+  {
+    id: "hidden",
+    label: "隐藏",
+    scrollbar: "none",
+  },
+];
+
+const animals = [
+  {id: "aardvark", name: "土豚"},
+  {id: "alpaca", name: "羊驼"},
+  {id: "antelope", name: "羚羊"},
+  {id: "bear", name: "熊"},
+  {id: "cat", name: "猫"},
+  {id: "dog", name: "狗"},
+  {id: "fox", name: "狐狸"},
+  {id: "giraffe", name: "长颈鹿"},
+  {id: "kangaroo", name: "袋鼠"},
+  {id: "koala", name: "考拉"},
+  {id: "lemur", name: "狐猴"},
+  {id: "otter", name: "水獭"},
+  {id: "panda", name: "熊猫"},
+  {id: "penguin", name: "企鹅"},
+  {id: "rabbit", name: "兔子"},
+  {id: "snake", name: "蛇"},
+  {id: "turtle", name: "海龟"},
+  {id: "wombat", name: "袋熊"},
+  {id: "zebra", name: "斑马"},
+];
+
+function ScrollbarListBox({mode}: {mode: ScrollbarMode}) {
+  return (
+    <div className="flex w-[260px] flex-col gap-2">
+      <h3 className="px-1 text-sm font-semibold text-muted">{mode.label}</h3>
+      <Surface
+        className="overflow-hidden rounded-3xl shadow-surface"
+        data-scrollbar={mode.scrollbar}
+      >
+        <div className="h-52 scrollbar overflow-y-auto p-1">
+          <ListBox aria-label={`${mode.label}动物列表`} selectionMode="single">
+            {animals.map((animal) => (
+              <ListBox.Item
+                key={`${mode.id}-${animal.id}`}
+                className="text-sm leading-5 font-medium"
+                id={`${mode.id}-${animal.id}`}
+                textValue={animal.name}
+              >
+                {animal.name}
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </div>
+      </Surface>
+    </div>
+  );
+}
+
+export function ScrollbarModes() {
+  return (
+    <div className="flex w-full flex-wrap justify-center gap-4">
+      {modes.map((mode) => (
+        <ScrollbarListBox key={mode.id} mode={mode} />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/virtualization.tsx b/apps/docs/src/demos/cn/list-box/virtualization.tsx
new file mode 100644
index 0000000..ef1d7f1
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/virtualization.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import {Description, Label, ListBox, ListLayout, Virtualizer} from "@heroui/react";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+export function Virtualization() {
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+
+  function generateUsers(n: number): User[] {
+    const users: User[] = [];
+
+    for (let i = 0; i < n; i++) {
+      const firstName = firstNames[i % firstNames.length];
+      const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+      const name = `${firstName} ${lastName}`;
+
+      users.push({
+        email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`,
+        id: i + 1,
+        name,
+      });
+    }
+
+    return users;
+  }
+
+  const users = generateUsers(1000);
+
+  return (
+    <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+      <ListBox
+        aria-label="包含 1000 项的虚拟化列表"
+        className="h-[400px] w-[300px] overflow-y-auto"
+        items={users}
+      >
+        {(user) => (
+          <ListBox.Item id={user.id} textValue={user.name}>
+            <div className="flex flex-col">
+              <Label>{user.name}</Label>
+              <Description>{user.email}</Description>
+            </div>
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        )}
+      </ListBox>
+    </Virtualizer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/with-disabled-items.tsx b/apps/docs/src/demos/cn/list-box/with-disabled-items.tsx
new file mode 100644
index 0000000..c0252ab
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/with-disabled-items.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+
+export function WithDisabledItems() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="文件操作"
+        className="w-full p-2"
+        disabledKeys={["delete-file"]}
+        selectionMode="none"
+        onAction={(key) => alert(`已选项目：${key}`)}
+      >
+        <ListBox.Section>
+          <Header>操作</Header>
+          <ListBox.Item id="new-file" textValue="新建文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>新建文件</Label>
+              <Description>创建新文件</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="编辑文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Pencil className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>编辑文件</Label>
+              <Description>进行修改</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>危险区域</Header>
+          <ListBox.Item id="delete-file" textValue="删除文件" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>删除文件</Label>
+              <Description>移至废纸篓</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/list-box/with-sections.tsx b/apps/docs/src/demos/cn/list-box/with-sections.tsx
new file mode 100644
index 0000000..0b492e8
--- /dev/null
+++ b/apps/docs/src/demos/cn/list-box/with-sections.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="文件操作"
+        className="w-full p-2"
+        selectionMode="none"
+        onAction={(key) => alert(`已选项目：${key}`)}
+      >
+        <ListBox.Section>
+          <Header>操作</Header>
+          <ListBox.Item id="new-file" textValue="新建文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>新建文件</Label>
+              <Description>创建新文件</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="编辑文件">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Pencil className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>编辑文件</Label>
+              <Description>进行修改</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>危险区域</Header>
+          <ListBox.Item id="delete-file" textValue="删除文件" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>删除文件</Label>
+              <Description>移至废纸篓</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/meter/basic.tsx b/apps/docs/src/demos/cn/meter/basic.tsx
new file mode 100644
index 0000000..7ad65f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/basic.tsx
@@ -0,0 +1,13 @@
+import {Label, Meter} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Meter aria-label="存储空间" className="w-64" value={60}>
+      <Label>存储空间</Label>
+      <Meter.Output />
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/cn/meter/colors.tsx b/apps/docs/src/demos/cn/meter/colors.tsx
new file mode 100644
index 0000000..e3d9141
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/colors.tsx
@@ -0,0 +1,27 @@
+import {Label, Meter} from "@heroui/react";
+
+const colors = ["default", "accent", "success", "warning", "danger"] as const;
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+export function Colors() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      {colors.map((color) => (
+        <Meter key={color} color={color} value={50}>
+          <Label>{COLOR_LABELS[color]}</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/meter/custom-value.tsx b/apps/docs/src/demos/cn/meter/custom-value.tsx
new file mode 100644
index 0000000..df0b83e
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/custom-value.tsx
@@ -0,0 +1,19 @@
+import {Label, Meter} from "@heroui/react";
+
+export function CustomValue() {
+  return (
+    <Meter
+      className="w-64"
+      formatOptions={{currency: "USD", style: "currency"}}
+      maxValue={1000}
+      minValue={0}
+      value={750}
+    >
+      <Label>收入</Label>
+      <Meter.Output />
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/cn/meter/index.ts b/apps/docs/src/demos/cn/meter/index.ts
new file mode 100644
index 0000000..dc420dd
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/index.ts
@@ -0,0 +1,5 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomValue} from "./custom-value";
+export {Sizes} from "./sizes";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/cn/meter/sizes.tsx b/apps/docs/src/demos/cn/meter/sizes.tsx
new file mode 100644
index 0000000..3d59210
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/sizes.tsx
@@ -0,0 +1,35 @@
+import {Label, Meter} from "@heroui/react";
+
+const SIZE_LABELS = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+} as const;
+
+export function Sizes() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <Meter color="success" size="sm" value={40}>
+        <Label>{SIZE_LABELS.sm}</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="accent" size="md" value={60}>
+        <Label>{SIZE_LABELS.md}</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="warning" size="lg" value={80}>
+        <Label>{SIZE_LABELS.lg}</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/meter/without-label.tsx b/apps/docs/src/demos/cn/meter/without-label.tsx
new file mode 100644
index 0000000..43a5b93
--- /dev/null
+++ b/apps/docs/src/demos/cn/meter/without-label.tsx
@@ -0,0 +1,11 @@
+import {Meter} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <Meter aria-label="存储空间用量" className="w-64" value={45}>
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/backdrop-variants.tsx b/apps/docs/src/demos/cn/modal/backdrop-variants.tsx
new file mode 100644
index 0000000..5f18314
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/backdrop-variants.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+const VARIANT_LABELS = {
+  blur: "模糊",
+  opaque: "不透明",
+  transparent: "透明",
+} as const;
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Modal key={variant}>
+          <Button variant="secondary">{VARIANT_LABELS[variant]}</Button>
+          <Modal.Backdrop variant={variant}>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>背景：{VARIANT_LABELS[variant]}</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    {variant === "opaque"
+                      ? "不透明背景会完全遮挡背后内容，让用户把注意力集中在模态框上。"
+                      : variant === "blur"
+                        ? "模糊背景会柔和地虚化背后内容，同时保留一定的环境上下文。"
+                        : "透明背景会完整保留背后内容，适合重要性较低的交互场景。"}
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    继续
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/close-methods.tsx b/apps/docs/src/demos/cn/modal/close-methods.tsx
new file mode 100644
index 0000000..58523b7
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/close-methods.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import {CircleCheck, CircleInfo} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CloseMethods() {
+  return (
+    <div className="flex max-w-2xl flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">使用 slot="close"</h3>
+        <p className="text-sm text-muted">
+          关闭模态框的最简方式：为模态框内任意 Button 添加 <code>slot="close"</code>
+          ，点击即可自动关闭。
+        </p>
+        <Modal>
+          <Button variant="secondary">打开模态框</Button>
+          <Modal.Backdrop>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.Header>
+                  <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>使用 slot="close"</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    点击下方任一按钮——它们都带有 <code>slot="close"</code>，会自动关闭模态框。
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="secondary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">使用 Dialog 渲染属性</h3>
+        <p className="text-sm text-muted">
+          通过 Dialog 的渲染属性访问 <code>close</code>{" "}
+          方法，可完全控制关闭时机与方式，并在关闭前加入自定义逻辑。
+        </p>
+        <Modal>
+          <Button variant="secondary">打开模态框</Button>
+          <Modal.Backdrop>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                {(renderProps) => (
+                  <>
+                    <Modal.Header>
+                      <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                        <CircleCheck className="size-5" />
+                      </Modal.Icon>
+                      <Modal.Heading>使用 Dialog 渲染属性</Modal.Heading>
+                    </Modal.Header>
+                    <Modal.Body>
+                      <p>
+                        下方按钮使用渲染属性中的 <code>close</code> 方法。可在调用{" "}
+                        <code>renderProps.close()</code> 前进行校验或其他逻辑。
+                      </p>
+                    </Modal.Body>
+                    <Modal.Footer>
+                      <Button variant="secondary" onPress={() => renderProps.close()}>
+                        取消
+                      </Button>
+                      <Button onPress={() => renderProps.close()}>确认</Button>
+                    </Modal.Footer>
+                  </>
+                )}
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/controlled.tsx b/apps/docs/src/demos/cn/modal/controlled.tsx
new file mode 100644
index 0000000..42d702d
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/controlled.tsx
@@ -0,0 +1,120 @@
+"use client";
+
+import {CircleCheck} from "@gravity-ui/icons";
+import {Button, Modal, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 React 的 <code className="text-foreground">useState</code>{" "}
+          管理模态框开关，适合简单场景。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              打开模态框
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                  <CircleCheck className="size-5" />
+                </Modal.Icon>
+                <Modal.Heading>由 useState() 控制</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  该模态框由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "}
+                  <code>onOpenChange</code> 传入即可在外部管理状态。
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  取消
+                </Button>
+                <Button slot="close">确认</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">配合 useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "}
+          <code>open()</code>、<code>close()</code>、<code>toggle()</code> 等方法。
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              状态：{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "打开" : "关闭"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              打开模态框
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              切换
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                  <CircleCheck className="size-5" />
+                </Modal.Icon>
+                <Modal.Heading>由 useOverlayState() 控制</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "}
+                  <code>state.open()</code>、<code>state.close()</code> 或{" "}
+                  <code>state.toggle()</code> 即可。
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  取消
+                </Button>
+                <Button slot="close">确认</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/custom-animations.tsx b/apps/docs/src/demos/cn/modal/custom-animations.tsx
new file mode 100644
index 0000000..aebd827
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/custom-animations.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+import React from "react";
+
+const iconMap: Record<string, React.ComponentType<{className?: string}>> = {
+  "gravity-ui:arrow-up-from-line": ArrowUpFromLine,
+  "gravity-ui:sparkles": Sparkles,
+};
+
+export function CustomAnimations() {
+  const animations = [
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+      description:
+        "基于物理的弹性缩放，模拟高阻尼弹簧系统：快速瞬态响应与较长 settling 时间。适用于模态框与弹出层。",
+      icon: "gravity-ui:sparkles",
+      name: "运动缩放",
+    },
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+      description:
+        "模拟流体阻力中的运动，摆脱机械式线性动画，呈现更自然、沉稳的质感。适用于底部抽屉或 Toast。",
+      icon: "gravity-ui:arrow-up-from-line",
+      name: "流体滑入",
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => {
+        const IconComponent = iconMap[icon];
+
+        return (
+          <Modal key={name}>
+            <Button variant="secondary">{name}</Button>
+            <Modal.Backdrop className={classNames.backdrop}>
+              <Modal.Container className={classNames.container}>
+                <Modal.Dialog className="sm:max-w-[360px]">
+                  <Modal.CloseTrigger />
+                  <Modal.Header>
+                    <Modal.Icon className="bg-default text-foreground">
+                      {!!IconComponent && <IconComponent className="size-5" />}
+                    </Modal.Icon>
+                    <Modal.Heading>{name} 动画</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p className="mt-1">{description}</p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button slot="close" variant="tertiary">
+                      关闭
+                    </Button>
+                    <Button slot="close">再试一次</Button>
+                  </Modal.Footer>
+                </Modal.Dialog>
+              </Modal.Container>
+            </Modal.Backdrop>
+          </Modal>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/custom-backdrop.tsx b/apps/docs/src/demos/cn/modal/custom-backdrop.tsx
new file mode 100644
index 0000000..03ce6f1
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/custom-backdrop.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {Sparkles} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CustomBackdrop() {
+  return (
+    <Modal>
+      <Button variant="secondary">自定义背景</Button>
+      <Modal.Backdrop
+        className="bg-linear-to-t from-black/80 via-black/40 to-transparent dark:from-zinc-800/80 dark:via-zinc-800/40"
+        variant="blur"
+      >
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.Header className="items-center text-center">
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Sparkles className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>高级背景</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                此背景采用从底部深色过渡到顶部完全透明的精致渐变，并配合柔和的模糊效果。渐变会在浅色与深色模式下自动调整强度，以获得最佳对比度。
+              </p>
+            </Modal.Body>
+            <Modal.Footer className="flex-col-reverse">
+              <Button className="w-full" slot="close">
+                Amazing!
+              </Button>
+              <Button className="w-full" slot="close" variant="secondary">
+                关闭
+              </Button>
+            </Modal.Footer>
+            <Modal.CloseTrigger />
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/custom-portal.tsx b/apps/docs/src/demos/cn/modal/custom-portal.tsx
new file mode 100644
index 0000000..5d41a76
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/custom-portal.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Button, Modal} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+export function CustomPortal() {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          在自定义容器内渲染模态框，而非 <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          为容器应用 <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code>{" "}
+          以创建新的层叠上下文。
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <Modal>
+            <Button>打开模态框</Button>
+            <Modal.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <Modal.Container className="h-full max-h-full">
+                <Modal.Dialog className="h-full max-h-full sm:max-w-md">
+                  <Modal.CloseTrigger />
+                  <Modal.Header>
+                    <Modal.Heading>自定义 Portal</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button slot="close" variant="secondary">
+                      关闭
+                    </Button>
+                  </Modal.Footer>
+                </Modal.Dialog>
+              </Modal.Container>
+            </Modal.Backdrop>
+          </Modal>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/custom-trigger.tsx b/apps/docs/src/demos/cn/modal/custom-trigger.tsx
new file mode 100644
index 0000000..bc0e2d9
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/custom-trigger.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {Gear} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <Modal>
+      <Modal.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+        <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-accent-soft text-accent-soft-foreground">
+          <Gear className="size-6" />
+        </div>
+        <div className="flex flex-1 flex-col gap-0.5">
+          <p className="text-sm font-semibold">设置</p>
+          <p className="text-xs text-muted">管理你的偏好设置</p>
+        </div>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Gear className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>设置</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                使用 <code>Modal.Trigger</code>{" "}
+                可在标准按钮之外创建自定义触发器。此示例展示带图标与说明文字的卡片式触发器。
+              </p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close" variant="secondary">
+                取消
+              </Button>
+              <Button slot="close">保存</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/default.tsx b/apps/docs/src/demos/cn/modal/default.tsx
new file mode 100644
index 0000000..2e38aed
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/default.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Modal>
+      <Button variant="secondary">打开模态框</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-default text-foreground">
+                <Rocket className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>欢迎使用 HeroUI</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>一套美观、快速、现代的 React UI 库，可轻松构建无障碍且高度可定制的 Web 应用。</p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button className="w-full" slot="close">
+                继续
+              </Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/dismiss-behavior.tsx b/apps/docs/src/demos/cn/modal/dismiss-behavior.tsx
new file mode 100644
index 0000000..e5a4c88
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/dismiss-behavior.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function DismissBehavior() {
+  return (
+    <div className="flex max-w-sm flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isDismissable</h3>
+        <p className="text-sm text-muted">
+          控制是否允许通过点击遮罩关闭模态框。默认为 <code>true</code>。设为 <code>false</code>{" "}
+          时需通过明确操作关闭。
+        </p>
+        <Modal>
+          <Button variant="secondary">打开模态框</Button>
+          <Modal.Backdrop isDismissable={false}>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>isDismissable = false</Modal.Heading>
+                  <p className="text-sm leading-5 text-muted">点击遮罩不会关闭此模态框</p>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>尝试点击遮罩区域——模态框不会关闭，必须使用关闭按钮或按 ESC 键关闭。</p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    关闭
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+        <p className="text-sm text-muted">
+          控制是否允许通过 ESC 关闭模态框。设为 <code>true</code> 时将禁用
+          ESC，用户须通过明确操作关闭。
+        </p>
+        <Modal>
+          <Button variant="secondary">打开模态框</Button>
+          <Modal.Backdrop isKeyboardDismissDisabled>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>isKeyboardDismissDisabled = true</Modal.Heading>
+                  <p className="text-sm leading-5 text-muted">已禁用 ESC 键</p>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>按 ESC 无反应。必须使用关闭按钮或点击遮罩才能关闭此模态框。</p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    关闭
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/index.ts b/apps/docs/src/demos/cn/modal/index.ts
new file mode 100644
index 0000000..d3f71d8
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/index.ts
@@ -0,0 +1,13 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {CloseMethods} from "./close-methods";
+export {Controlled} from "./controlled";
+export {CustomAnimations} from "./custom-animations";
+export {CustomBackdrop} from "./custom-backdrop";
+export {CustomPortal} from "./custom-portal";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {DismissBehavior} from "./dismiss-behavior";
+export {Placements} from "./placements";
+export {ScrollComparison} from "./scroll-comparison";
+export {Sizes} from "./sizes";
+export {WithForm} from "./with-form";
diff --git a/apps/docs/src/demos/cn/modal/placements.tsx b/apps/docs/src/demos/cn/modal/placements.tsx
new file mode 100644
index 0000000..6d7d9c4
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/placements.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+const PLACEMENT_LABELS = {
+  auto: "自动",
+  bottom: "底部",
+  center: "居中",
+  top: "顶部",
+} as const;
+
+export function Placements() {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Modal key={placement}>
+          <Button variant="secondary">{PLACEMENT_LABELS[placement]}</Button>
+          <Modal.Backdrop>
+            <Modal.Container placement={placement}>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    {placement === "auto" ? "自动定位" : `${PLACEMENT_LABELS[placement]}位置`}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    {placement === "auto"
+                      ? "在移动端默认靠近底部，在桌面端居中，以获得更合适的阅读与操作体验。"
+                      : `模态框将锚定在视口的「${PLACEMENT_LABELS[placement]}」区域。可尝试不同 placement 查看屏幕上的定位效果。`}
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    继续
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/scroll-comparison.tsx b/apps/docs/src/demos/cn/modal/scroll-comparison.tsx
new file mode 100644
index 0000000..d341853
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/scroll-comparison.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {Button, Modal, Radio, RadioGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function ScrollComparison() {
+  const [scroll, setScroll] = useState<"inside" | "outside">("inside");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup
+        orientation="horizontal"
+        value={scroll}
+        onChange={(value) => setScroll(value as "inside" | "outside")}
+      >
+        <Radio value="inside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            内部
+          </Radio.Content>
+        </Radio>
+        <Radio value="outside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            外部
+          </Radio.Content>
+        </Radio>
+      </RadioGroup>
+
+      <Modal>
+        <Button variant="secondary">
+          打开模态框（{scroll.charAt(0).toUpperCase() + scroll.slice(1)})
+        </Button>
+        <Modal.Backdrop>
+          <Modal.Container scroll={scroll}>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.Header>
+                <Modal.Heading>{scroll === "inside" ? "滚动：内部" : "滚动：外部"}</Modal.Heading>
+                <p className="text-sm leading-5 text-muted">
+                  对比滚动行为——内部在模态框内滚动内容，外部允许页面滚动
+                </p>
+              </Modal.Header>
+              <Modal.Body>
+                {Array.from({length: 30}).map((_, i) => (
+                  <p key={i} className="mb-3">
+                    段落 {i + 1}： Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                    pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit
+                    risus, sed porttitor quam.
+                  </p>
+                ))}
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  取消
+                </Button>
+                <Button slot="close">确认</Button>
+              </Modal.Footer>
+              <Modal.CloseTrigger />
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/sizes.tsx b/apps/docs/src/demos/cn/modal/sizes.tsx
new file mode 100644
index 0000000..e73ae66
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/sizes.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+const SIZE_LABELS = {
+  cover: "通栏",
+  full: "全屏",
+  lg: "大",
+  md: "中",
+  sm: "小",
+  xs: "超小",
+} as const;
+
+export function Sizes() {
+  const sizes = ["xs", "sm", "md", "lg", "cover", "full"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <Modal key={size}>
+          <Button variant="secondary">{SIZE_LABELS[size]}</Button>
+          <Modal.Backdrop>
+            <Modal.Container size={size}>
+              <Modal.Dialog>
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>尺寸：{SIZE_LABELS[size]}</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        此模态框使用 <code>cover</code> 尺寸：在移动端与桌面端保留边距（移动端约
+                        16px、桌面端约
+                        40px）铺满可视区域，仍保持圆角与标准内边距，适合需要最大宽度又保留模态框气质的内容展示。
+                      </>
+                    ) : size === "full" ? (
+                      <>
+                        此模态框使用 <code>full</code>{" "}
+                        尺寸，占满整个视口，无边距、圆角或阴影，提供真正的全屏体验，适合沉浸式内容或全页交互。
+                      </>
+                    ) : (
+                      <>
+                        此模态框使用 <code>{size}</code>{" "}
+                        尺寸。在移动端各尺寸都会接近全宽以便阅读；在桌面端则对应不同的最大宽度，以适配不同信息量。
+                      </>
+                    )}
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="secondary">
+                    取消
+                  </Button>
+                  <Button slot="close">确认</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/modal/with-form.tsx b/apps/docs/src/demos/cn/modal/with-form.tsx
new file mode 100644
index 0000000..4e57b57
--- /dev/null
+++ b/apps/docs/src/demos/cn/modal/with-form.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Button, Input, Label, Modal, Surface, TextField} from "@heroui/react";
+
+export function WithForm() {
+  return (
+    <Modal>
+      <Button variant="secondary">打开联系表单</Button>
+      <Modal.Backdrop>
+        <Modal.Container placement="auto">
+          <Modal.Dialog className="sm:max-w-md">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Envelope className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>联系我们</Modal.Heading>
+              <p className="mt-1.5 text-sm leading-5 text-muted">
+                填写下方表单，我们会尽快回复。在移动端弹出键盘时，模态框会自动适配。
+              </p>
+            </Modal.Header>
+            <Modal.Body className="p-6">
+              <Surface variant="default">
+                <form className="flex flex-col gap-4">
+                  <TextField className="w-full" name="name" type="text">
+                    <Label>姓名</Label>
+                    <Input placeholder="输入你的姓名" />
+                  </TextField>
+                  <TextField className="w-full" name="email" type="email">
+                    <Label>邮箱</Label>
+                    <Input placeholder="输入你的邮箱" />
+                  </TextField>
+                  <TextField className="w-full" name="phone" type="tel">
+                    <Label>电话</Label>
+                    <Input placeholder="输入你的电话号码" />
+                  </TextField>
+                  <TextField className="w-full" name="company">
+                    <Label>公司</Label>
+                    <Input placeholder="输入公司名称" />
+                  </TextField>
+                  <TextField className="w-full" name="message">
+                    <Label>留言</Label>
+                    <Input placeholder="输入留言内容" />
+                  </TextField>
+                </form>
+              </Surface>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close" variant="secondary">
+                取消
+              </Button>
+              <Button slot="close">发送消息</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/basic.tsx b/apps/docs/src/demos/cn/number-field/basic.tsx
new file mode 100644
index 0000000..05d1977
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/basic.tsx
@@ -0,0 +1,14 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width">
+      <Label>宽度</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input className="w-[120px]" />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/controlled.tsx b/apps/docs/src/demos/cn/number-field/controlled.tsx
new file mode 100644
index 0000000..61ce54a
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/controlled.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Button, Description, Label, NumberField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState(1024);
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField minValue={0} name="width" value={value} onChange={setValue}>
+        <Label>宽度</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>当前值：{value}</Description>
+      </NumberField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(0)}>
+          重置为 0
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(2048)}>
+          设为 2048
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/custom-icons.tsx b/apps/docs/src/demos/cn/number-field/custom-icons.tsx
new file mode 100644
index 0000000..f832e94
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/custom-icons.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>宽度（自定义图标）</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+        </NumberField.Group>
+        <Description>自定义图标子元素</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/custom-render-function.tsx b/apps/docs/src/demos/cn/number-field/custom-render-function.tsx
new file mode 100644
index 0000000..6345499
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/custom-render-function.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Label, NumberField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <NumberField
+      className="w-full max-w-64"
+      defaultValue={1024}
+      minValue={0}
+      name="width"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>宽度</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input className="w-[120px]" />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/disabled.tsx b/apps/docs/src/demos/cn/number-field/disabled.tsx
new file mode 100644
index 0000000..934821e
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/disabled.tsx
@@ -0,0 +1,34 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isDisabled defaultValue={1024} minValue={0} name="width">
+        <Label>宽度</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>以像素为单位输入宽度</Description>
+      </NumberField>
+      <NumberField
+        isDisabled
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>取值须在 0 到 100 之间</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/form-example.tsx b/apps/docs/src/demos/cn/number-field/form-example.tsx
new file mode 100644
index 0000000..20544de
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/form-example.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, NumberField, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState<number | undefined>(undefined);
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const STOCK_AVAILABLE = 3;
+  const isOutOfStock = value !== undefined && value > STOCK_AVAILABLE;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (value === undefined || value === null || value < 1 || value > STOCK_AVAILABLE) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Order submitted:", {quantity: value});
+      setValue(undefined);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <NumberField
+        isRequired
+        isInvalid={isOutOfStock}
+        maxValue={5}
+        minValue={1}
+        name="quantity"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>订购数量</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        {isOutOfStock ? (
+          <FieldError>仅剩 {STOCK_AVAILABLE} 件库存</FieldError>
+        ) : (
+          <Description>仅剩 {STOCK_AVAILABLE} 件可购</Description>
+        )}
+      </NumberField>
+      <Button
+        className="w-full"
+        isDisabled={value === undefined || value < 1 || value > STOCK_AVAILABLE}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            处理中…
+          </>
+        ) : (
+          "下单"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/full-width.tsx b/apps/docs/src/demos/cn/number-field/full-width.tsx
new file mode 100644
index 0000000..dcc63a9
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/full-width.tsx
@@ -0,0 +1,16 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <NumberField fullWidth defaultValue={1024} minValue={0} name="width">
+        <Label>宽度</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/index.ts b/apps/docs/src/demos/cn/number-field/index.ts
new file mode 100644
index 0000000..81cd9bd
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/index.ts
@@ -0,0 +1,16 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIcons} from "./custom-icons";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
+export {WithChevrons} from "./with-chevrons";
+export {WithDescription} from "./with-description";
+export {WithFormatOptions} from "./with-format-options";
+export {WithStep} from "./with-step";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/cn/number-field/on-surface.tsx b/apps/docs/src/demos/cn/number-field/on-surface.tsx
new file mode 100644
index 0000000..855d0cd
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/on-surface.tsx
@@ -0,0 +1,34 @@
+import {Description, Label, NumberField, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-[280px] flex-col gap-4 rounded-3xl p-6">
+      <NumberField defaultValue={1024} minValue={0} name="width" variant="secondary">
+        <Label>宽度</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-full" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>以像素为单位输入宽度</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        variant="secondary"
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-full" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>取值须在 0 到 100 之间</Description>
+      </NumberField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/required.tsx b/apps/docs/src/demos/cn/number-field/required.tsx
new file mode 100644
index 0000000..0bd2705
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/required.tsx
@@ -0,0 +1,25 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isRequired minValue={0} name="quantity">
+        <Label>数量</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField isRequired defaultValue={1} maxValue={10} minValue={1} name="rating">
+        <Label>评分</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>评分范围 1 到 10</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/validation.tsx b/apps/docs/src/demos/cn/number-field/validation.tsx
new file mode 100644
index 0000000..94016cb
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/validation.tsx
@@ -0,0 +1,34 @@
+import {FieldError, Label, NumberField} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isInvalid isRequired minValue={0} name="quantity" value={-5}>
+        <Label>数量</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>数量必须大于或等于 0</FieldError>
+      </NumberField>
+      <NumberField
+        isInvalid
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        value={1.5}
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>百分比必须在 0 到 100 之间</FieldError>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/variants.tsx b/apps/docs/src/demos/cn/number-field/variants.tsx
new file mode 100644
index 0000000..10c2715
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/variants.tsx
@@ -0,0 +1,24 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={100} minValue={0} name="primary-width" variant="primary">
+        <Label>主要变体</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField defaultValue={100} minValue={0} name="secondary-width" variant="secondary">
+        <Label>次要变体</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/with-chevrons.tsx b/apps/docs/src/demos/cn/number-field/with-chevrons.tsx
new file mode 100644
index 0000000..64b3313
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/with-chevrons.tsx
@@ -0,0 +1,56 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function WithChevrons() {
+  return (
+    <NumberField
+      className="w-full max-w-64"
+      defaultValue={99}
+      minValue={0}
+      name="amount"
+      formatOptions={{
+        currency: "EUR",
+        currencySign: "accounting",
+        style: "currency",
+      }}
+    >
+      <Label>带 Chevron 的数字输入框</Label>
+      <NumberField.Group className="flex">
+        <NumberField.Input className="flex-1" />
+        <div className="flex h-full flex-col border-l border-field-placeholder/15">
+          <NumberField.IncrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pt-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+          <NumberField.DecrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pb-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+        </div>
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/with-description.tsx b/apps/docs/src/demos/cn/number-field/with-description.tsx
new file mode 100644
index 0000000..9aa4950
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/with-description.tsx
@@ -0,0 +1,33 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>宽度</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>以像素为单位输入宽度</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>取值须在 0 到 100 之间</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/with-format-options.tsx b/apps/docs/src/demos/cn/number-field/with-format-options.tsx
new file mode 100644
index 0000000..235aaa8
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/with-format-options.tsx
@@ -0,0 +1,95 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithFormatOptions() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField
+        defaultValue={99}
+        minValue={0}
+        name="currency-eur"
+        formatOptions={{
+          currency: "EUR",
+          currencySign: "accounting",
+          style: "currency",
+        }}
+      >
+        <Label>货币（EUR - 会计格式）</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>欧元会计记账格式</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={99.99}
+        minValue={0}
+        name="currency-usd"
+        formatOptions={{
+          currency: "USD",
+          style: "currency",
+        }}
+      >
+        <Label>货币（USD）</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>标准美元货币格式</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.01}
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>百分比格式（0–1，0.5 表示 50%）</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1234.56}
+        minValue={0}
+        name="decimal"
+        formatOptions={{
+          maximumFractionDigits: 2,
+          minimumFractionDigits: 2,
+          style: "decimal",
+        }}
+      >
+        <Label>小数（保留 2 位）</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>保留 2 位小数格式</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1000}
+        minValue={0}
+        name="unit"
+        formatOptions={{
+          style: "unit",
+          unit: "kilogram",
+          unitDisplay: "short",
+        }}
+      >
+        <Label>单位（千克）</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>千克单位格式</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/with-step.tsx b/apps/docs/src/demos/cn/number-field/with-step.tsx
new file mode 100644
index 0000000..8b7e7a7
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/with-step.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithStep() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step1" step={1}>
+        <Label>步长：1</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>每次增减 1</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}>
+        <Label>步长：5</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>每次增减 5</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}>
+        <Label>步长：10</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>每次增减 10</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/number-field/with-validation.tsx b/apps/docs/src/demos/cn/number-field/with-validation.tsx
new file mode 100644
index 0000000..5926646
--- /dev/null
+++ b/apps/docs/src/demos/cn/number-field/with-validation.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Description, FieldError, Label, NumberField} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState<number | undefined>(undefined);
+  const isInvalid = value !== undefined && (value < 0 || value > 100);
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField
+        isRequired
+        formatOptions={{style: "percent"}}
+        isInvalid={isInvalid}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        value={value}
+        onChange={setValue}
+      >
+        <Label>百分比</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        {isInvalid ? (
+          <FieldError>百分比必须在 0 到 100 之间</FieldError>
+        ) : (
+          <Description>请输入 0 到 100 之间的值</Description>
+        )}
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/basic.tsx b/apps/docs/src/demos/cn/pagination/basic.tsx
new file mode 100644
index 0000000..8e9c7d5
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/basic.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationBasic() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>上一页</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>下一页</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/controlled.tsx b/apps/docs/src/demos/cn/pagination/controlled.tsx
new file mode 100644
index 0000000..c9d577d
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/controlled.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationControlled() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+  const itemsPerPage = 10;
+  const totalItems = 120;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    if (totalPages <= 7) {
+      for (let i = 1; i <= totalPages; i++) {
+        pages.push(i);
+      }
+    } else {
+      pages.push(1);
+
+      if (page > 3) {
+        pages.push("ellipsis");
+      }
+
+      const start = Math.max(2, page - 1);
+      const end = Math.min(totalPages - 1, page + 1);
+
+      for (let i = start; i <= end; i++) {
+        pages.push(i);
+      }
+
+      if (page < totalPages - 2) {
+        pages.push("ellipsis");
+      }
+
+      pages.push(totalPages);
+    }
+
+    return pages;
+  };
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination>
+      <Pagination.Summary>
+        显示第 {startItem}–{endItem} 条，共 {totalItems} 条结果
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>上一页</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {getPageNumbers().map((p, i) =>
+          p === "ellipsis" ? (
+            <Pagination.Item key={`ellipsis-${i}`}>
+              <Pagination.Ellipsis />
+            </Pagination.Item>
+          ) : (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ),
+        )}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>下一页</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/custom-icons.tsx b/apps/docs/src/demos/cn/pagination/custom-icons.tsx
new file mode 100644
index 0000000..3bfe8f3
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/custom-icons.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function PaginationCustomIcons() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon>
+              <Icon icon="gravity-ui:arrow-left" />
+            </Pagination.PreviousIcon>
+            <span>返回</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>前进</span>
+            <Pagination.NextIcon>
+              <Icon icon="gravity-ui:arrow-right" />
+            </Pagination.NextIcon>
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/disabled.tsx b/apps/docs/src/demos/cn/pagination/disabled.tsx
new file mode 100644
index 0000000..5cce654
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/disabled.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationDisabled() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>上一页</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled onPress={() => setPage((p) => p + 1)}>
+            <span>下一页</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/index.ts b/apps/docs/src/demos/cn/pagination/index.ts
new file mode 100644
index 0000000..13688be
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/index.ts
@@ -0,0 +1,8 @@
+export {PaginationBasic as Basic} from "./basic";
+export {PaginationSizes as Sizes} from "./sizes";
+export {PaginationWithEllipsis as WithEllipsis} from "./with-ellipsis";
+export {PaginationSimplePrevNext as SimplePrevNext} from "./simple-prev-next";
+export {PaginationWithSummary as WithSummary} from "./with-summary";
+export {PaginationCustomIcons as CustomIcons} from "./custom-icons";
+export {PaginationControlled as Controlled} from "./controlled";
+export {PaginationDisabled as Disabled} from "./disabled";
diff --git a/apps/docs/src/demos/cn/pagination/simple-prev-next.tsx b/apps/docs/src/demos/cn/pagination/simple-prev-next.tsx
new file mode 100644
index 0000000..d666311
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/simple-prev-next.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationSimplePrevNext() {
+  const [page, setPage] = useState(1);
+  const totalPages = 10;
+  const itemsPerPage = 5;
+  const totalItems = 50;
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination className="w-full">
+      <Pagination.Summary>
+        第 {startItem}–{endItem} 条，共 {totalItems} 张发票
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>上一页</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>下一页</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/sizes.tsx b/apps/docs/src/demos/cn/pagination/sizes.tsx
new file mode 100644
index 0000000..bcfb226
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/sizes.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+const SIZE_LABELS = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+} as const;
+
+function SizePagination({size}: {size: "sm" | "md" | "lg"}) {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <span className="text-xs font-medium text-muted">{SIZE_LABELS[size]}</span>
+      <Pagination className="justify-center" size={size}>
+        <Pagination.Content>
+          <Pagination.Item>
+            <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+              <Pagination.PreviousIcon />
+              <span>上一页</span>
+            </Pagination.Previous>
+          </Pagination.Item>
+          {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ))}
+          <Pagination.Item>
+            <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+              <span>下一页</span>
+              <Pagination.NextIcon />
+            </Pagination.Next>
+          </Pagination.Item>
+        </Pagination.Content>
+      </Pagination>
+    </div>
+  );
+}
+
+export function PaginationSizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      {(["sm", "md", "lg"] as const).map((size) => (
+        <SizePagination key={size} size={size} />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/with-ellipsis.tsx b/apps/docs/src/demos/cn/pagination/with-ellipsis.tsx
new file mode 100644
index 0000000..3b081ce
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/with-ellipsis.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationWithEllipsis() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    pages.push(1);
+
+    if (page > 3) {
+      pages.push("ellipsis");
+    }
+
+    const start = Math.max(2, page - 1);
+    const end = Math.min(totalPages - 1, page + 1);
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+
+    if (page < totalPages - 2) {
+      pages.push("ellipsis");
+    }
+
+    pages.push(totalPages);
+
+    return pages;
+  };
+
+  return (
+    <div className="w-full max-w-2xs overflow-x-auto sm:max-w-full">
+      <Pagination className="justify-center">
+        <Pagination.Content>
+          <Pagination.Item>
+            <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+              <Pagination.PreviousIcon />
+              <span>上一页</span>
+            </Pagination.Previous>
+          </Pagination.Item>
+          {getPageNumbers().map((p, i) =>
+            p === "ellipsis" ? (
+              <Pagination.Item key={`ellipsis-${i}`}>
+                <Pagination.Ellipsis />
+              </Pagination.Item>
+            ) : (
+              <Pagination.Item key={p}>
+                <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ),
+          )}
+          <Pagination.Item>
+            <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+              <span>下一页</span>
+              <Pagination.NextIcon />
+            </Pagination.Next>
+          </Pagination.Item>
+        </Pagination.Content>
+      </Pagination>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/pagination/with-summary.tsx b/apps/docs/src/demos/cn/pagination/with-summary.tsx
new file mode 100644
index 0000000..c4e060d
--- /dev/null
+++ b/apps/docs/src/demos/cn/pagination/with-summary.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationWithSummary() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+  const itemsPerPage = 10;
+  const totalItems = 120;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    pages.push(1);
+
+    if (page > 3) {
+      pages.push("ellipsis");
+    }
+
+    const start = Math.max(2, page - 1);
+    const end = Math.min(totalPages - 1, page + 1);
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+
+    if (page < totalPages - 2) {
+      pages.push("ellipsis");
+    }
+
+    pages.push(totalPages);
+
+    return pages;
+  };
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination className="w-full">
+      <Pagination.Summary>
+        显示第 {startItem}–{endItem} 条，共 {totalItems} 条结果
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>上一页</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {getPageNumbers().map((p, i) =>
+          p === "ellipsis" ? (
+            <Pagination.Item key={`ellipsis-${i}`}>
+              <Pagination.Ellipsis />
+            </Pagination.Item>
+          ) : (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ),
+        )}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>下一页</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/cn/popover/basic.tsx b/apps/docs/src/demos/cn/popover/basic.tsx
new file mode 100644
index 0000000..07c1323
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/basic.tsx
@@ -0,0 +1,17 @@
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button>点击我</Button>
+        <Popover.Content className="max-w-64">
+          <Popover.Dialog>
+            <Popover.Heading>弹出层标题</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">这是弹出层内容，你可以在这里放置任何内容。</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/popover/custom-render-function.tsx b/apps/docs/src/demos/cn/popover/custom-render-function.tsx
new file mode 100644
index 0000000..2f377d2
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/custom-render-function.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Button, Popover} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button>点击我</Button>
+        <Popover.Content
+          className="max-w-64"
+          render={(props) => <div {...props} data-custom="foo" />}
+        >
+          <Popover.Dialog>
+            <Popover.Heading>弹出层标题</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">这是弹出层内容，你可以在这里放置任何内容。</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/popover/index.ts b/apps/docs/src/demos/cn/popover/index.ts
new file mode 100644
index 0000000..dcd9cb2
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/index.ts
@@ -0,0 +1,5 @@
+export {PopoverBasic as Basic} from "./basic";
+export {PopoverWithArrow as WithArrow} from "./with-arrow";
+export {PopoverPlacement as Placement} from "./placement";
+export {PopoverInteractive as Interactive} from "./interactive";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/popover/interactive.tsx b/apps/docs/src/demos/cn/popover/interactive.tsx
new file mode 100644
index 0000000..8a65da2
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/interactive.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import {Avatar, Button, Popover} from "@heroui/react";
+import {useState} from "react";
+
+export function PopoverInteractive() {
+  const [isFollowing, setIsFollowing] = useState(false);
+
+  return (
+    <div className="flex items-center gap-6">
+      <Popover>
+        <Popover.Trigger aria-label="用户资料">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Sarah Johnson"
+                src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1"
+              />
+              <Avatar.Fallback>SJ</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <p className="text-sm font-medium">Sarah Johnson</p>
+              <p className="text-xs text-muted">@sarahj</p>
+            </div>
+          </div>
+        </Popover.Trigger>
+        <Popover.Content className="w-[320px]">
+          <Popover.Dialog>
+            <Popover.Heading>
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                  <Avatar size="md">
+                    <Avatar.Image
+                      alt="Sarah Johnson"
+                      src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1"
+                    />
+                    <Avatar.Fallback>SJ</Avatar.Fallback>
+                  </Avatar>
+                  <div>
+                    <p className="font-semibold">Sarah Johnson</p>
+                    <p className="text-sm text-muted">@sarahj</p>
+                  </div>
+                </div>
+                <Button
+                  className="rounded-full"
+                  size="sm"
+                  variant={isFollowing ? "tertiary" : "primary"}
+                  onPress={() => setIsFollowing(!isFollowing)}
+                >
+                  {isFollowing ? "已关注" : "关注"}
+                </Button>
+              </div>
+            </Popover.Heading>
+            <p className="mt-3 text-sm text-muted">产品设计师兼创意总监，打造有意义的美好体验。</p>
+            <div className="mt-3 flex gap-4">
+              <div>
+                <span className="font-semibold">892</span>
+                <span className="ml-1 text-sm text-muted">关注中</span>
+              </div>
+              <div>
+                <span className="font-semibold">12.5K</span>
+                <span className="ml-1 text-sm text-muted">粉丝</span>
+              </div>
+            </div>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/popover/placement.tsx b/apps/docs/src/demos/cn/popover/placement.tsx
new file mode 100644
index 0000000..8004900
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/placement.tsx
@@ -0,0 +1,63 @@
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverPlacement() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <div />
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Top
+        </Button>
+        <Popover.Content placement="top">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">顶部位置</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+      <div />
+
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Left
+        </Button>
+        <Popover.Content placement="left">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">左侧位置</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <div className="flex items-center justify-center">
+        <span className="text-sm text-muted">点击按钮</span>
+      </div>
+
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Right
+        </Button>
+        <Popover.Content placement="right">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">右侧位置</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <div />
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Bottom
+        </Button>
+        <Popover.Content placement="bottom">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">底部位置</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+      <div />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/popover/with-arrow.tsx b/apps/docs/src/demos/cn/popover/with-arrow.tsx
new file mode 100644
index 0000000..7f762e5
--- /dev/null
+++ b/apps/docs/src/demos/cn/popover/with-arrow.tsx
@@ -0,0 +1,32 @@
+import {Ellipsis} from "@gravity-ui/icons";
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverWithArrow() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button variant="secondary">带箭头</Button>
+        <Popover.Content className="max-w-64">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <Popover.Heading>带箭头的弹出层</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">箭头指向触发弹出层的元素。</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <Popover>
+        <Button isIconOnly variant="tertiary">
+          <Ellipsis />
+        </Button>
+        <Popover.Content className="max-w-64" offset={10}>
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <Popover.Heading>带箭头的弹出层</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">箭头指向触发弹出层的元素。</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/basic.tsx b/apps/docs/src/demos/cn/progress-bar/basic.tsx
new file mode 100644
index 0000000..7f0cf19
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/basic.tsx
@@ -0,0 +1,13 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ProgressBar aria-label="加载中" className="w-64" value={60}>
+      <Label>加载中</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/colors.tsx b/apps/docs/src/demos/cn/progress-bar/colors.tsx
new file mode 100644
index 0000000..f0e2f11
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/colors.tsx
@@ -0,0 +1,27 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+const colors = ["default", "accent", "success", "warning", "danger"] as const;
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+export function Colors() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      {colors.map((color) => (
+        <ProgressBar key={color} aria-label={COLOR_LABELS[color]} color={color} value={50}>
+          <Label>{COLOR_LABELS[color]}</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/custom-value.tsx b/apps/docs/src/demos/cn/progress-bar/custom-value.tsx
new file mode 100644
index 0000000..1bea0fd
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/custom-value.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import {Label, ListBox, NumberField, ProgressBar, Select, Separator} from "@heroui/react";
+import {useState} from "react";
+
+const formatStyleOptions: {label: string; value: string}[] = [
+  {label: "货币", value: "currency"},
+  {label: "百分比", value: "percent"},
+  {label: "小数", value: "decimal"},
+  {label: "单位", value: "unit"},
+];
+
+const formatOptionsMap: Record<string, Intl.NumberFormatOptions> = {
+  currency: {currency: "USD", style: "currency"},
+  decimal: {style: "decimal"},
+  percent: {style: "percent"},
+  unit: {style: "unit", unit: "mile"},
+};
+
+export function CustomValue() {
+  const [value, setValue] = useState(750);
+  const [minValue, setMinValue] = useState(0);
+  const [maxValue, setMaxValue] = useState(1000);
+  const [format, setFormat] = useState<string>("percent");
+
+  return (
+    <div className="flex w-full flex-col gap-6 md:flex-row md:items-center md:gap-10">
+      <div className="flex w-full max-w-md flex-1 justify-center">
+        <ProgressBar
+          aria-label="收入"
+          className="w-full max-w-52"
+          formatOptions={formatOptionsMap[format]}
+          maxValue={maxValue}
+          minValue={minValue}
+          value={value}
+        >
+          <Label>进度</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+      </div>
+
+      <Separator className="md:hidden" />
+      <Separator className="hidden md:block" orientation="vertical" />
+
+      <div className="flex max-w-52 flex-col gap-3">
+        <Label className="text-xs font-medium text-muted">选项</Label>
+
+        <NumberField
+          maxValue={maxValue}
+          minValue={minValue}
+          value={value}
+          variant="secondary"
+          onChange={(v) => setValue(v)}
+        >
+          <Label>值</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <NumberField
+          maxValue={maxValue - 1}
+          minValue={0}
+          value={minValue}
+          variant="secondary"
+          onChange={(v) => {
+            setMinValue(v);
+            if (value < v) setValue(v);
+          }}
+        >
+          <Label>最小值</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <NumberField
+          maxValue={2000}
+          minValue={minValue + 1}
+          value={maxValue}
+          variant="secondary"
+          onChange={(v) => {
+            setMaxValue(v);
+            if (value > v) setValue(v);
+          }}
+        >
+          <Label>最大值</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <Select value={format} variant="secondary" onChange={(key) => setFormat(key as string)}>
+          <Label>格式</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {formatStyleOptions.map((option) => (
+                <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                  {option.label}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/indeterminate.tsx b/apps/docs/src/demos/cn/progress-bar/indeterminate.tsx
new file mode 100644
index 0000000..37dfca6
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/indeterminate.tsx
@@ -0,0 +1,12 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Indeterminate() {
+  return (
+    <ProgressBar isIndeterminate aria-label="加载中" className="w-64">
+      <Label>加载中…</Label>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/index.ts b/apps/docs/src/demos/cn/progress-bar/index.ts
new file mode 100644
index 0000000..0032f81
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomValue} from "./custom-value";
+export {Indeterminate} from "./indeterminate";
+export {Sizes} from "./sizes";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/cn/progress-bar/sizes.tsx b/apps/docs/src/demos/cn/progress-bar/sizes.tsx
new file mode 100644
index 0000000..6540dde
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/sizes.tsx
@@ -0,0 +1,35 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+const SIZE_LABELS = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+} as const;
+
+export function Sizes() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <ProgressBar aria-label={SIZE_LABELS.sm} size="sm" value={40}>
+        <Label>{SIZE_LABELS.sm}</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label={SIZE_LABELS.md} size="md" value={60}>
+        <Label>{SIZE_LABELS.md}</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label={SIZE_LABELS.lg} size="lg" value={80}>
+        <Label>{SIZE_LABELS.lg}</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-bar/without-label.tsx b/apps/docs/src/demos/cn/progress-bar/without-label.tsx
new file mode 100644
index 0000000..452c93f
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-bar/without-label.tsx
@@ -0,0 +1,11 @@
+import {ProgressBar} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <ProgressBar aria-label="加载进度" className="w-64" value={45}>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/basic.tsx b/apps/docs/src/demos/cn/progress-circle/basic.tsx
new file mode 100644
index 0000000..0e3cbb2
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/basic.tsx
@@ -0,0 +1,12 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ProgressCircle aria-label="加载中" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/colors.tsx b/apps/docs/src/demos/cn/progress-circle/colors.tsx
new file mode 100644
index 0000000..783109e
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/colors.tsx
@@ -0,0 +1,26 @@
+import {ProgressCircle} from "@heroui/react";
+
+const colors = ["default", "accent", "success", "warning", "danger"] as const;
+
+const COLOR_LABELS: Record<(typeof colors)[number], string> = {
+  accent: "强调",
+  danger: "危险",
+  default: "默认",
+  success: "成功",
+  warning: "警告",
+};
+
+export function Colors() {
+  return (
+    <div className="flex items-center gap-6">
+      {colors.map((color) => (
+        <ProgressCircle key={color} aria-label={COLOR_LABELS[color]} color={color} value={60}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/custom-svg.tsx b/apps/docs/src/demos/cn/progress-circle/custom-svg.tsx
new file mode 100644
index 0000000..86cd1e5
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/custom-svg.tsx
@@ -0,0 +1,28 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function CustomSvg() {
+  return (
+    <div className="flex items-end gap-6">
+      <ProgressCircle aria-label="细圆环" value={60}>
+        <ProgressCircle.Track strokeWidth={2} viewBox="0 0 36 36">
+          <ProgressCircle.TrackCircle cx={18} cy={18} r={17} strokeWidth={2} />
+          <ProgressCircle.FillCircle cx={18} cy={18} r={17} strokeWidth={2} />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+
+      <ProgressCircle aria-label="默认圆环" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+
+      <ProgressCircle aria-label="粗圆环" value={60}>
+        <ProgressCircle.Track strokeWidth={6} viewBox="0 0 36 36">
+          <ProgressCircle.TrackCircle cx={18} cy={18} r={15} strokeWidth={6} />
+          <ProgressCircle.FillCircle cx={18} cy={18} r={15} strokeWidth={6} />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/indeterminate.tsx b/apps/docs/src/demos/cn/progress-circle/indeterminate.tsx
new file mode 100644
index 0000000..0208643
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/indeterminate.tsx
@@ -0,0 +1,12 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Indeterminate() {
+  return (
+    <ProgressCircle isIndeterminate aria-label="加载中">
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/index.ts b/apps/docs/src/demos/cn/progress-circle/index.ts
new file mode 100644
index 0000000..7efa906
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomSvg} from "./custom-svg";
+export {Indeterminate} from "./indeterminate";
+export {Sizes} from "./sizes";
+export {WithLabel} from "./with-label";
diff --git a/apps/docs/src/demos/cn/progress-circle/sizes.tsx b/apps/docs/src/demos/cn/progress-circle/sizes.tsx
new file mode 100644
index 0000000..d8e5258
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/sizes.tsx
@@ -0,0 +1,32 @@
+import {ProgressCircle} from "@heroui/react";
+
+const SIZE_LABELS = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+} as const;
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-6">
+      <ProgressCircle aria-label={SIZE_LABELS.sm} size="sm" value={40}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label={SIZE_LABELS.md} size="md" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label={SIZE_LABELS.lg} size="lg" value={80}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/progress-circle/with-label.tsx b/apps/docs/src/demos/cn/progress-circle/with-label.tsx
new file mode 100644
index 0000000..1f6efb1
--- /dev/null
+++ b/apps/docs/src/demos/cn/progress-circle/with-label.tsx
@@ -0,0 +1,15 @@
+import {Label, ProgressCircle} from "@heroui/react";
+
+export function WithLabel() {
+  return (
+    <div className="flex items-center gap-3">
+      <ProgressCircle aria-label="加载中" value={75}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <Label>已完成 75%</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/basic.tsx b/apps/docs/src/demos/cn/radio-group/basic.tsx
new file mode 100644
index 0000000..30b1a62
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/basic.tsx
@@ -0,0 +1,37 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <RadioGroup defaultValue="premium" name="plan">
+      <Label>选择套餐</Label>
+      <Description>选择最适合你的套餐</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          基础版
+        </Radio.Content>
+        <Description>每月包含 100 条消息</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          高级版
+        </Radio.Content>
+        <Description>每月包含 200 条消息</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          商业版
+        </Radio.Content>
+        <Description>无限消息</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/controlled.tsx b/apps/docs/src/demos/cn/radio-group/controlled.tsx
new file mode 100644
index 0000000..aba8eb6
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/controlled.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("pro");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup name="plan-controlled" value={value} onChange={setValue}>
+        <Label>订阅套餐</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            入门版
+          </Radio.Content>
+          <Description>适合副项目和小型团队</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            专业版
+          </Radio.Content>
+          <Description>高级报表与分析</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            团队版
+          </Radio.Content>
+          <Description>最多可与 10 名队友共享访问权限</Description>
+        </Radio>
+      </RadioGroup>
+      <p className="text-sm text-muted">
+        已选套餐： <span className="font-medium">{value}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/custom-indicator.tsx b/apps/docs/src/demos/cn/radio-group/custom-indicator.tsx
new file mode 100644
index 0000000..719c1f4
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/custom-indicator.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <RadioGroup defaultValue="premium" name="plan-custom-indicator">
+      <Label>选择套餐</Label>
+      <Description>选择最适合你的套餐</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          基础版
+        </Radio.Content>
+        <Description>每月包含 100 条消息</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          高级版
+        </Radio.Content>
+        <Description>每月包含 200 条消息</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          商业版
+        </Radio.Content>
+        <Description>无限消息</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/custom-render-function.tsx b/apps/docs/src/demos/cn/radio-group/custom-render-function.tsx
new file mode 100644
index 0000000..cb2f77c
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/custom-render-function.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <RadioGroup
+      defaultValue="premium"
+      name="plan-custom-render"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>选择套餐</Label>
+      <Description>选择最适合你的套餐</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          基础版
+        </Radio.Content>
+        <Description>每月包含 100 条消息</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          高级版
+        </Radio.Content>
+        <Description>每月包含 200 条消息</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          商业版
+        </Radio.Content>
+        <Description>无限消息</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/delivery-and-payment.tsx b/apps/docs/src/demos/cn/radio-group/delivery-and-payment.tsx
new file mode 100644
index 0000000..217c4e5
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/delivery-and-payment.tsx
@@ -0,0 +1,117 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import clsx from "clsx";
+
+export function DeliveryAndPayment() {
+  const deliveryOptions = [
+    {
+      description: "4–10 个工作日",
+      price: "$5.00",
+      title: "标准",
+      value: "standard",
+    },
+    {
+      description: "2–5 个工作日",
+      price: "$16.00",
+      title: "快递",
+      value: "express",
+    },
+    {
+      description: "1 个工作日",
+      price: "$25.00",
+      title: "极速",
+      value: "super-fast",
+    },
+  ];
+
+  const paymentOptions = [
+    {
+      description: "有效期至 2026/01",
+      icon: "uim:master-card",
+      title: "**** 8304",
+      value: "mastercard",
+    },
+    {
+      description: "有效期至 2026/01",
+      icon: "streamline-logos:visa-logo-solid",
+      title: "**** 0123",
+      value: "visa",
+    },
+    {
+      description: "使用 PayPal 支付",
+      icon: "ic:baseline-paypal",
+      title: "PayPal",
+      value: "paypal",
+    },
+  ];
+
+  return (
+    <div
+      className="flex w-full flex-col items-center gap-10"
+      style={{
+        // @ts-expect-error - Overrides default variables
+        "--accent": "#006FEE",
+        "--accent-foreground": "#fff",
+        "--accent-hover": "#006FEE",
+        "--border-width": "2px",
+        "--border-width-field": "2px",
+        "--focus": "#006FEE",
+      }}
+    >
+      <section className="flex w-full max-w-lg flex-col gap-4">
+        <RadioGroup defaultValue="express" name="delivery" variant="secondary">
+          <Label>配送方式</Label>
+          <div className="grid gap-x-4 md:grid-cols-3">
+            {deliveryOptions.map((option) => (
+              <Radio key={option.value} value={option.value}>
+                <Radio.Content
+                  className={clsx(
+                    "group relative flex w-full flex-col gap-6 rounded-xl border border-transparent bg-surface px-5 py-4 transition-all data-[selected=true]:border-accent data-[selected=true]:bg-accent/10",
+                    "data-[focus-visible=true]:border-accent data-[focus-visible=true]:bg-accent/10",
+                  )}
+                >
+                  <Radio.Control className="absolute top-3 right-4 size-5">
+                    <Radio.Indicator />
+                  </Radio.Control>
+                  <div className="flex flex-col gap-1">
+                    <span>{option.title}</span>
+                    <Description>{option.description}</Description>
+                  </div>
+                  <span className="text-sm font-semibold">{option.price}</span>
+                </Radio.Content>
+              </Radio>
+            ))}
+          </div>
+        </RadioGroup>
+      </section>
+      <section className="flex w-full max-w-lg flex-col gap-4">
+        <RadioGroup defaultValue="visa" name="payment" variant="secondary">
+          <div className="flex flex-wrap items-center justify-between gap-4">
+            <Label>支付方式</Label>
+          </div>
+          <div className="grid gap-x-4 md:grid-cols-2">
+            {paymentOptions.map((option) => (
+              <Radio key={option.value} value={option.value}>
+                <Radio.Content
+                  className={clsx(
+                    "group relative flex w-full flex-row items-start justify-start gap-4 rounded-xl border border-transparent bg-surface px-5 py-4 transition-all",
+                    "data-[selected=true]:border-accent data-[selected=true]:bg-accent/10",
+                  )}
+                >
+                  <Radio.Control className="absolute top-3 right-4 size-5">
+                    <Radio.Indicator />
+                  </Radio.Control>
+                  <Icon className="size-6" icon={option.icon} />
+                  <div className="flex flex-col gap-1">
+                    <span>{option.title}</span>
+                    <Description>{option.description}</Description>
+                  </div>
+                </Radio.Content>
+              </Radio>
+            ))}
+          </div>
+        </RadioGroup>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/disabled.tsx b/apps/docs/src/demos/cn/radio-group/disabled.tsx
new file mode 100644
index 0000000..4f71e84
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/disabled.tsx
@@ -0,0 +1,37 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <RadioGroup isDisabled defaultValue="pro" name="plan-disabled">
+      <Label>订阅套餐</Label>
+      <Description>我们正在发布更新，暂时无法更改套餐。</Description>
+      <Radio value="starter">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          入门版
+        </Radio.Content>
+        <Description>适合副项目和小型团队</Description>
+      </Radio>
+      <Radio value="pro">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          专业版
+        </Radio.Content>
+        <Description>高级报表与分析</Description>
+      </Radio>
+      <Radio value="teams">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          团队版
+        </Radio.Content>
+        <Description>最多可与 10 名队友共享访问权限</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/horizontal.tsx b/apps/docs/src/demos/cn/radio-group/horizontal.tsx
new file mode 100644
index 0000000..0621231
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/horizontal.tsx
@@ -0,0 +1,38 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Horizontal() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Label>订阅套餐</Label>
+      <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal">
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            入门版
+          </Radio.Content>
+          <Description>适合副项目</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            专业版
+          </Radio.Content>
+          <Description>高级报表</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            团队版
+          </Radio.Content>
+          <Description>最多 10 名队友</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/index.ts b/apps/docs/src/demos/cn/radio-group/index.ts
new file mode 100644
index 0000000..0f552d5
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/index.ts
@@ -0,0 +1,11 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DeliveryAndPayment} from "./delivery-and-payment";
+export {Disabled} from "./disabled";
+export {Horizontal} from "./horizontal";
+export {OnSurface} from "./on-surface";
+export {Uncontrolled} from "./uncontrolled";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/radio-group/on-surface.tsx b/apps/docs/src/demos/cn/radio-group/on-surface.tsx
new file mode 100644
index 0000000..ec29a02
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/on-surface.tsx
@@ -0,0 +1,39 @@
+import {Description, Label, Radio, RadioGroup, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <RadioGroup defaultValue="premium" name="plan-on-surface" variant="secondary">
+        <Label>选择套餐</Label>
+        <Description>选择最适合你的套餐</Description>
+        <Radio value="basic">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            基础版
+          </Radio.Content>
+          <Description>每月包含 100 条消息</Description>
+        </Radio>
+        <Radio value="premium">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            高级版
+          </Radio.Content>
+          <Description>每月包含 200 条消息</Description>
+        </Radio>
+        <Radio value="business">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            商业版
+          </Radio.Content>
+          <Description>无限消息</Description>
+        </Radio>
+      </RadioGroup>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/uncontrolled.tsx b/apps/docs/src/demos/cn/radio-group/uncontrolled.tsx
new file mode 100644
index 0000000..3e402e8
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/uncontrolled.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Uncontrolled() {
+  const [selection, setSelection] = React.useState("pro");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup
+        defaultValue="pro"
+        name="plan-uncontrolled"
+        onChange={(nextValue) => setSelection(nextValue)}
+      >
+        <Label>订阅套餐</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            入门版
+          </Radio.Content>
+          <Description>适合副项目和小型团队</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            专业版
+          </Radio.Content>
+          <Description>高级报表与分析</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            团队版
+          </Radio.Content>
+          <Description>最多可与 10 名队友共享访问权限</Description>
+        </Radio>
+      </RadioGroup>
+      <p className="text-sm text-muted">
+        上次选择的套餐： <span className="font-medium">{selection}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/validation.tsx b/apps/docs/src/demos/cn/radio-group/validation.tsx
new file mode 100644
index 0000000..4e867bb
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/validation.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Validation() {
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  return (
+    <Form
+      className="flex flex-col gap-4"
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        const formData = new FormData(e.currentTarget);
+        const value = formData.get("plan-validation");
+
+        setMessage(`你选择的套餐是： ${value}`);
+      }}
+    >
+      <RadioGroup isRequired name="plan-validation">
+        <Label>订阅套餐</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            入门版
+          </Radio.Content>
+          <Description>适合副项目和小型团队</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            专业版
+          </Radio.Content>
+          <Description>高级报表与分析</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            团队版
+          </Radio.Content>
+          <Description>最多可与 10 名队友共享访问权限</Description>
+        </Radio>
+        <FieldError>请先选择订阅套餐再继续。</FieldError>
+      </RadioGroup>
+      <Button className="mt-2 w-fit" type="submit">
+        Submit
+      </Button>
+      {!!message && <p className="text-sm text-muted">{message}</p>}
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/radio-group/variants.tsx b/apps/docs/src/demos/cn/radio-group/variants.tsx
new file mode 100644
index 0000000..cfb1967
--- /dev/null
+++ b/apps/docs/src/demos/cn/radio-group/variants.tsx
@@ -0,0 +1,54 @@
+import {Description, Radio, RadioGroup} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">主要变体</p>
+        <RadioGroup defaultValue="option1" name="primary-plan" variant="primary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              选项 1
+            </Radio.Content>
+            <Description>默认背景的标准样式</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              选项 2
+            </Radio.Content>
+            <Description>另一种主要样式选项</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">次要变体</p>
+        <RadioGroup defaultValue="option1" name="secondary-plan" variant="secondary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              选项 1
+            </Radio.Content>
+            <Description>用于表面上的低强调变体</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              选项 2
+            </Radio.Content>
+            <Description>另一种次要样式选项</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/allows-non-contiguous-ranges.tsx b/apps/docs/src/demos/cn/range-calendar/allows-non-contiguous-ranges.tsx
new file mode 100644
index 0000000..1fe4d16
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/allows-non-contiguous-ranges.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function AllowsNonContiguousRanges() {
+  const now = today(getLocalTimeZone());
+  const blockedRanges = [
+    [now.add({days: 2}), now.add({days: 5})],
+    [now.add({days: 12}), now.add({days: 13})],
+  ] as const;
+
+  const isDateUnavailable = (date: DateValue) => {
+    return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        allowsNonContiguousRanges
+        aria-label="行程日期"
+        defaultValue={{end: now.add({days: 9}), start: now.add({days: 1})}}
+        firstDayOfWeek="mon"
+        isDateUnavailable={isDateUnavailable}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">允许跨不可选日期选择非连续区间</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/anchor-unavailable-dates.tsx b/apps/docs/src/demos/cn/range-calendar/anchor-unavailable-dates.tsx
new file mode 100644
index 0000000..2a05940
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/anchor-unavailable-dates.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import type {CalendarDate, DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function AnchorUnavailableDates() {
+  const now = today(getLocalTimeZone());
+
+  const isDateUnavailable = (date: DateValue, anchorDate: CalendarDate | null) => {
+    return anchorDate != null && Math.abs(date.compare(anchorDate)) > 7;
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="行程日期" isDateUnavailable={isDateUnavailable} minValue={now}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">选择开始日期后，仅前后 7 天内的日期可选</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/basic.tsx b/apps/docs/src/demos/cn/range-calendar/basic.tsx
new file mode 100644
index 0000000..847d7ad
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/basic.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <RangeCalendar aria-label="行程日期" firstDayOfWeek="mon">
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/booking-calendar.tsx b/apps/docs/src/demos/cn/range-calendar/booking-calendar.tsx
new file mode 100644
index 0000000..7ecd759
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/booking-calendar.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function BookingCalendar() {
+  const [selectedRange, setSelectedRange] = useState<DateRange | null>(null);
+  const {locale} = useLocale();
+  const blockedDates = [5, 6, 12, 13, 14, 20];
+
+  const isDateUnavailable = (date: DateValue) => {
+    return isWeekend(date, locale) || blockedDates.includes(date.day);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="预订区间"
+        isDateUnavailable={isDateUnavailable}
+        minValue={today(getLocalTimeZone())}
+        value={selectedRange}
+        onChange={setSelectedRange}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => (
+              <RangeCalendar.Cell date={date}>
+                {({formattedDate, isUnavailable}) => (
+                  <>
+                    {formattedDate}
+                    {!isUnavailable &&
+                      !isWeekend(date, locale) &&
+                      blockedDates.includes(date.day) && <RangeCalendar.CellIndicator />}
+                  </>
+                )}
+              </RangeCalendar.Cell>
+            )}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <div className="flex flex-col gap-2 text-center">
+        <div className="flex items-center justify-center gap-4 text-xs text-muted">
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-muted" /> 不可订日期
+          </span>
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-default" /> 周末/不可用
+          </span>
+        </div>
+        {selectedRange ? (
+          <Button size="sm" variant="primary">
+            预订 {selectedRange.start.toString()} → {selectedRange.end.toString()}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/controlled.tsx b/apps/docs/src/demos/cn/range-calendar/controlled.tsx
new file mode 100644
index 0000000..6de4b12
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/controlled.tsx
@@ -0,0 +1,116 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, ButtonGroup, Description, RangeCalendar} from "@heroui/react";
+import {
+  getLocalTimeZone,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Controlled() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25"));
+  const {locale} = useLocale();
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <ButtonGroup variant="tertiary">
+        <Button
+          onPress={() => {
+            const start = today(getLocalTimeZone());
+
+            setFocusedDate(start);
+          }}
+        >
+          本周
+        </Button>
+        <Button
+          onPress={() => {
+            const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale);
+
+            setFocusedDate(nextWeekStart);
+          }}
+        >
+          下周
+        </Button>
+        <Button
+          onPress={() => {
+            const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1}));
+
+            setFocusedDate(nextMonthStart);
+          }}
+        >
+          下月
+        </Button>
+      </ButtonGroup>
+
+      <RangeCalendar
+        aria-label="行程日期"
+        firstDayOfWeek="mon"
+        focusedValue={focusedDate}
+        value={value}
+        onChange={setValue}
+        onFocusChange={setFocusedDate}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+
+      <Description className="text-center">
+        已选区间： {value ? `${value.start.toString()} -> ${value.end.toString()}` : "（无）"}
+      </Description>
+
+      <div className="flex gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const start = today(getLocalTimeZone());
+
+            setValue({end: start.add({days: 6}), start});
+            setFocusedDate(start);
+          }}
+        >
+          设为 1 周
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const start = parseDate("2025-12-20");
+
+            setValue({end: parseDate("2025-12-31"), start});
+            setFocusedDate(start);
+          }}
+        >
+          设为节假日
+        </Button>
+        <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/day-view.tsx b/apps/docs/src/demos/cn/range-calendar/day-view.tsx
new file mode 100644
index 0000000..397efd0
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/day-view.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Label, ListBox, RangeCalendar, Select} from "@heroui/react";
+import {useState} from "react";
+
+const dayOptions = [
+  {id: "1", name: "1 天"},
+  {id: "5", name: "5 天"},
+  {id: "7", name: "7 天"},
+  {id: "8", name: "8 天"},
+  {id: "10", name: "10 天"},
+  {id: "14", name: "14 天"},
+  {id: "21", name: "21 天"},
+] as const;
+
+export function DayView() {
+  const [days, setDays] = useState(5);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(days)}
+        onChange={(value) => value && setDays(Number(value))}
+      >
+        <Label>可见天数</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {dayOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <RangeCalendar key={days} aria-label="行程日期" visibleDuration={{days}}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/default-value.tsx b/apps/docs/src/demos/cn/range-calendar/default-value.tsx
new file mode 100644
index 0000000..d7e42f1
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/default-value.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+
+export function DefaultValue() {
+  return (
+    <RangeCalendar
+      aria-label="行程日期"
+      defaultValue={{end: parseDate("2025-02-12"), start: parseDate("2025-02-03")}}
+      firstDayOfWeek="mon"
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/disabled.tsx b/apps/docs/src/demos/cn/range-calendar/disabled.tsx
new file mode 100644
index 0000000..4e0920d
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/disabled.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar isDisabled aria-label="行程日期">
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">区间日历已禁用</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/focused-value.tsx b/apps/docs/src/demos/cn/range-calendar/focused-value.tsx
new file mode 100644
index 0000000..fa2540d
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/focused-value.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Description, RangeCalendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+import {useState} from "react";
+
+export function FocusedValue() {
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="行程日期"
+        firstDayOfWeek="mon"
+        focusedValue={focusedDate}
+        onFocusChange={setFocusedDate}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">聚焦： {focusedDate.toString()}</Description>
+      <div className="flex flex-wrap justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+        >
+          跳转到一月
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+        >
+          跳转到六月
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+        >
+          跳转到圣诞节
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/index.ts b/apps/docs/src/demos/cn/range-calendar/index.ts
new file mode 100644
index 0000000..b2b1aab
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/index.ts
@@ -0,0 +1,20 @@
+export {AllowsNonContiguousRanges} from "./allows-non-contiguous-ranges";
+export {AnchorUnavailableDates} from "./anchor-unavailable-dates";
+export {Basic} from "./basic";
+export {BookingCalendar} from "./booking-calendar";
+export {Controlled} from "./controlled";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {FocusedValue} from "./focused-value";
+export {InternationalCalendar} from "./international-calendar";
+export {Invalid} from "./invalid";
+export {MinMaxDates} from "./min-max-dates";
+export {MultipleMonths} from "./multiple-months";
+export {ReadOnly} from "./read-only";
+export {ThreeMonths} from "./three-months";
+export {UnavailableDates} from "./unavailable-dates";
+export {DayView} from "./day-view";
+export {WeekView} from "./week-view";
+export {WeeksInMonth} from "./weeks-in-month";
+export {WithIndicators} from "./with-indicators";
+export {YearPicker} from "./year-picker";
diff --git a/apps/docs/src/demos/cn/range-calendar/international-calendar.tsx b/apps/docs/src/demos/cn/range-calendar/international-calendar.tsx
new file mode 100644
index 0000000..fb8ee4a
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/international-calendar.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <RangeCalendar aria-label="行程日期">
+        <RangeCalendar.Header>
+          <RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.YearPickerTriggerHeading />
+            <RangeCalendar.YearPickerTriggerIndicator />
+          </RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+        <RangeCalendar.YearPickerGrid>
+          <RangeCalendar.YearPickerGridBody>
+            {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+          </RangeCalendar.YearPickerGridBody>
+        </RangeCalendar.YearPickerGrid>
+      </RangeCalendar>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/invalid.tsx b/apps/docs/src/demos/cn/range-calendar/invalid.tsx
new file mode 100644
index 0000000..6420f50
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/invalid.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Invalid() {
+  const now = today(getLocalTimeZone());
+  const [value, setValue] = useState<DateRange>({
+    end: now.add({days: 14}),
+    start: now.add({days: 6}),
+  });
+  const isInvalid = value.end.compare(value.start) > 7;
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="行程日期"
+        firstDayOfWeek="mon"
+        isInvalid={isInvalid}
+        value={value}
+        onChange={setValue}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      {isInvalid ? (
+        <p className="text-sm text-danger">最长入住时间为 1 周</p>
+      ) : (
+        <Description className="text-center">请选择最多 7 天的入住区间</Description>
+      )}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/min-max-dates.tsx b/apps/docs/src/demos/cn/range-calendar/min-max-dates.tsx
new file mode 100644
index 0000000..a541233
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/min-max-dates.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function MinMaxDates() {
+  const now = today(getLocalTimeZone());
+  const minDate = now;
+  const maxDate = now.add({months: 3});
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="行程日期" maxValue={maxDate} minValue={minDate}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">
+        请在今天与 {maxDate.toString()} 之间选择日期。
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/multiple-months.tsx b/apps/docs/src/demos/cn/range-calendar/multiple-months.tsx
new file mode 100644
index 0000000..2d378cb
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/multiple-months.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function MultipleMonths() {
+  return (
+    <RangeCalendar
+      aria-label="行程日期"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 1}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/read-only.tsx b/apps/docs/src/demos/cn/range-calendar/read-only.tsx
new file mode 100644
index 0000000..40e678d
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/read-only.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function ReadOnly() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        isReadOnly
+        aria-label="行程日期"
+        defaultValue={{
+          end: today(getLocalTimeZone()).add({days: 4}),
+          start: today(getLocalTimeZone()),
+        }}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">区间日历为只读</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/three-months.tsx b/apps/docs/src/demos/cn/range-calendar/three-months.tsx
new file mode 100644
index 0000000..bce9530
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/three-months.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function ThreeMonths() {
+  return (
+    <RangeCalendar
+      aria-label="假期规划"
+      className="@container-normal w-auto overflow-x-auto"
+      visibleDuration={{months: 3}}
+    >
+      <div className="flex w-max gap-7">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 1}} />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 2}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 2}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/unavailable-dates.tsx b/apps/docs/src/demos/cn/range-calendar/unavailable-dates.tsx
new file mode 100644
index 0000000..05f8c02
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/unavailable-dates.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function UnavailableDates() {
+  const now = today(getLocalTimeZone());
+  const blockedRanges = [
+    [now.add({days: 2}), now.add({days: 5})],
+    [now.add({days: 12}), now.add({days: 13})],
+  ] as const;
+
+  const isDateUnavailable = (date: DateValue) => {
+    return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="行程日期"
+        defaultValue={{end: now.add({days: 9}), start: now.add({days: 6})}}
+        firstDayOfWeek="mon"
+        isDateUnavailable={isDateUnavailable}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">部分日期不可选</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/week-view.tsx b/apps/docs/src/demos/cn/range-calendar/week-view.tsx
new file mode 100644
index 0000000..6c7cde7
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/week-view.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Label, ListBox, RangeCalendar, Select} from "@heroui/react";
+import {useState} from "react";
+
+const weekOptions = [
+  {id: "1", name: "1 周"},
+  {id: "2", name: "2 周"},
+  {id: "3", name: "3 周"},
+  {id: "4", name: "4 周"},
+  {id: "5", name: "5 周"},
+  {id: "6", name: "6 周"},
+  {id: "8", name: "8 周"},
+] as const;
+
+export function WeekView() {
+  const [weeks, setWeeks] = useState(1);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(weeks)}
+        onChange={(value) => value && setWeeks(Number(value))}
+      >
+        <Label>可见周数</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {weekOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <RangeCalendar key={weeks} aria-label="行程日期" visibleDuration={{weeks}}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/weeks-in-month.tsx b/apps/docs/src/demos/cn/range-calendar/weeks-in-month.tsx
new file mode 100644
index 0000000..29428c6
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/weeks-in-month.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+
+export function WeeksInMonth() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="行程日期" weeksInMonth={6}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">每月固定显示 6 周，切换月份时避免布局跳动</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/with-indicators.tsx b/apps/docs/src/demos/cn/range-calendar/with-indicators.tsx
new file mode 100644
index 0000000..ea65c97
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/with-indicators.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, isToday} from "@internationalized/date";
+
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export function WithIndicators() {
+  return (
+    <RangeCalendar aria-label="行程日期">
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => (
+            <RangeCalendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <RangeCalendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </RangeCalendar.Cell>
+          )}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/range-calendar/year-picker.tsx b/apps/docs/src/demos/cn/range-calendar/year-picker.tsx
new file mode 100644
index 0000000..f634713
--- /dev/null
+++ b/apps/docs/src/demos/cn/range-calendar/year-picker.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function YearPicker() {
+  return (
+    <RangeCalendar aria-label="行程日期">
+      <RangeCalendar.Header>
+        <RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.YearPickerTriggerHeading />
+          <RangeCalendar.YearPickerTriggerIndicator />
+        </RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <RangeCalendar.YearPickerGrid>
+        <RangeCalendar.YearPickerGridBody>
+          {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+        </RangeCalendar.YearPickerGridBody>
+      </RangeCalendar.YearPickerGrid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/custom-size.tsx b/apps/docs/src/demos/cn/scroll-shadow/custom-size.tsx
new file mode 100644
index 0000000..fe0e66c
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/custom-size.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function CustomSize() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow className="max-h-[240px] p-4" size={80}>
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+              pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus,
+              sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/default.tsx b/apps/docs/src/demos/cn/scroll-shadow/default.tsx
new file mode 100644
index 0000000..180977d
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/default.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function Default() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow className="max-h-[240px] p-4">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+              pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus,
+              sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/hide-scroll-bar.tsx b/apps/docs/src/demos/cn/scroll-shadow/hide-scroll-bar.tsx
new file mode 100644
index 0000000..1fbe6af
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/hide-scroll-bar.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function HideScrollBar() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow hideScrollBar className="max-h-[240px] p-4">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+              pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus,
+              sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/index.ts b/apps/docs/src/demos/cn/scroll-shadow/index.ts
new file mode 100644
index 0000000..a814c6e
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/index.ts
@@ -0,0 +1,6 @@
+export {default as Default} from "./default";
+export {default as Orientation} from "./orientation";
+export {default as HideScrollBar} from "./hide-scroll-bar";
+export {default as CustomSize} from "./custom-size";
+export {default as VisibilityChange} from "./visibility-change";
+export {default as WithCard} from "./with-card";
diff --git a/apps/docs/src/demos/cn/scroll-shadow/orientation.tsx b/apps/docs/src/demos/cn/scroll-shadow/orientation.tsx
new file mode 100644
index 0000000..935f452
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/orientation.tsx
@@ -0,0 +1,62 @@
+import {Card, ScrollShadow} from "@heroui/react";
+
+const images = [
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
+];
+
+export default function Orientation() {
+  const getRandomImage = (idx: number) => {
+    return images[idx % images.length];
+  };
+
+  return (
+    <div className="w-full sm:max-w-sm">
+      <div className="mb-8 w-full">
+        <h4 className="mb-2 text-sm font-semibold">垂直</h4>
+        <Card className="w-full p-0">
+          <ScrollShadow className="max-h-[240px] p-4" orientation="vertical">
+            <div className="space-y-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <p key={`scroll-shadow-lorem-content-${idx}`}>
+                  段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                  pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit
+                  risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+                </p>
+              ))}
+            </div>
+          </ScrollShadow>
+        </Card>
+      </div>
+
+      <div className="w-full">
+        <h4 className="mb-2 text-sm font-semibold">水平</h4>
+        <Card className="w-full p-0">
+          <ScrollShadow className="p-4" orientation="horizontal">
+            <div className="flex flex-row gap-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <Card
+                  key={`scroll-shadow-lorem-cards-${idx}`}
+                  className="flex min-w-[200px] flex-row gap-3 p-1"
+                  variant="transparent"
+                >
+                  <img
+                    alt="示例卡片"
+                    className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                    loading="lazy"
+                    src={getRandomImage(idx)}
+                  />
+                  <div className="flex flex-1 flex-col justify-center gap-1">
+                    <Card.Title className="text-sm">连接未来</Card.Title>
+                    <Card.Description className="text-xs">今天 18:30</Card.Description>
+                  </div>
+                </Card>
+              ))}
+            </div>
+          </ScrollShadow>
+        </Card>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/visibility-change.tsx b/apps/docs/src/demos/cn/scroll-shadow/visibility-change.tsx
new file mode 100644
index 0000000..85e3a86
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/visibility-change.tsx
@@ -0,0 +1,94 @@
+"use client";
+
+import type {ScrollShadowVisibility} from "@heroui/react";
+
+import {Card, ScrollShadow} from "@heroui/react";
+import {useState} from "react";
+
+const images = [
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
+];
+
+const VISIBILITY_LABELS: Record<ScrollShadowVisibility, string> = {
+  auto: "自动",
+  both: "两侧",
+  bottom: "底部",
+  left: "左侧",
+  none: "无",
+  right: "右侧",
+  top: "顶部",
+};
+
+export default function VisibilityChange() {
+  const [verticalState, setVerticalState] = useState<ScrollShadowVisibility>("none");
+  const [horizontalState, setHorizontalState] = useState<ScrollShadowVisibility>("none");
+
+  const getRandomImage = (idx: number) => {
+    return images[idx % images.length];
+  };
+
+  return (
+    <div className="w-full sm:max-w-sm">
+      <div className="mb-8 flex flex-col gap-2">
+        <div className="rounded bg-default p-4">
+          <p className="text-sm font-semibold">垂直阴影状态：{VISIBILITY_LABELS[verticalState]}</p>
+        </div>
+        <div className="w-full">
+          <ScrollShadow
+            className="max-h-[240px] p-4"
+            orientation="vertical"
+            onVisibilityChange={(visibility) => setVerticalState(visibility)}
+          >
+            <div className="space-y-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <p key={`scroll-shadow-lorem-content-${idx}`}>
+                  段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                  pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit
+                  risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+                </p>
+              ))}
+            </div>
+          </ScrollShadow>
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="rounded bg-default p-4">
+          <p className="text-sm font-semibold">
+            水平阴影状态：{VISIBILITY_LABELS[horizontalState]}
+          </p>
+        </div>
+        <div className="w-full">
+          <ScrollShadow
+            className="p-4"
+            orientation="horizontal"
+            onVisibilityChange={(visibility) => setHorizontalState(visibility)}
+          >
+            <div className="flex flex-row gap-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <Card
+                  key={`scroll-shadow-lorem-cards-${idx}`}
+                  className="flex min-w-[200px] flex-row gap-3 p-1"
+                  variant="transparent"
+                >
+                  <img
+                    alt="示例卡片"
+                    className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                    loading="lazy"
+                    src={getRandomImage(idx)}
+                  />
+                  <div className="flex flex-1 flex-col justify-center gap-1">
+                    <Card.Title className="text-sm">连接未来</Card.Title>
+                    <Card.Description className="text-xs">今天 18:30</Card.Description>
+                  </div>
+                </Card>
+              ))}
+            </div>
+          </ScrollShadow>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/scroll-shadow/with-card.tsx b/apps/docs/src/demos/cn/scroll-shadow/with-card.tsx
new file mode 100644
index 0000000..92ef2e6
--- /dev/null
+++ b/apps/docs/src/demos/cn/scroll-shadow/with-card.tsx
@@ -0,0 +1,31 @@
+import {Button, Card, ScrollShadow} from "@heroui/react";
+
+export default function WithCard() {
+  return (
+    <Card className="max-w-[400px]">
+      <Card.Header>
+        <Card.Title>条款与条件</Card.Title>
+        <Card.Description>继续前请先阅读</Card.Description>
+      </Card.Header>
+      <Card.Content className="p-0">
+        <ScrollShadow className="h-[300px] px-4" size={80}>
+          <div className="space-y-4">
+            {Array.from({length: 10}).map((_, idx) => (
+              <p key={`scroll-shadow-lorem-content-${idx}`}>
+                段落 {idx + 1}：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus,
+                sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.
+              </p>
+            ))}
+          </div>
+        </ScrollShadow>
+      </Card.Content>
+      <Card.Footer className="mt-4 flex flex-row gap-2">
+        <Button className="w-full" variant="secondary">
+          Cancel
+        </Button>
+        <Button className="w-full">接受</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/basic.tsx b/apps/docs/src/demos/cn/search-field/basic.tsx
new file mode 100644
index 0000000..95945bc
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/basic.tsx
@@ -0,0 +1,14 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <SearchField name="search">
+      <Label>搜索</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/controlled.tsx b/apps/docs/src/demos/cn/search-field/controlled.tsx
new file mode 100644
index 0000000..587b282
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/controlled.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Button, Description, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search" value={value} onChange={setValue}>
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>当前值： {value || "（空）"}</Description>
+      </SearchField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue("")}>
+          Clear
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue("示例查询")}>
+          设置示例
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/custom-icons.tsx b/apps/docs/src/demos/cn/search-field/custom-icons.tsx
new file mode 100644
index 0000000..01ea5f0
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/custom-icons.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search-custom">
+        <Label>搜索（自定义图标）</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.SearchIcon>
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.ClearButton>
+        </SearchField.Group>
+        <Description>自定义图标子元素</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/custom-render-function.tsx b/apps/docs/src/demos/cn/search-field/custom-render-function.tsx
new file mode 100644
index 0000000..fe24bfb
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/custom-render-function.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Label, SearchField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <SearchField name="search" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>搜索</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/disabled.tsx b/apps/docs/src/demos/cn/search-field/disabled.tsx
new file mode 100644
index 0000000..4cf183a
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/disabled.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isDisabled name="search" value="已禁用的搜索">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>此搜索框已禁用</Description>
+      </SearchField>
+      <SearchField isDisabled name="search-empty">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>此搜索框已禁用</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/form-example.tsx b/apps/docs/src/demos/cn/search-field/form-example.tsx
new file mode 100644
index 0000000..080ade8
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/form-example.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, SearchField, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState("");
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const MIN_LENGTH = 3;
+  const isInvalid = value.length > 0 && value.length < MIN_LENGTH;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (value.length < MIN_LENGTH) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Search submitted:", {query: value});
+      setValue("");
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
+        <Label>搜索产品</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="搜索产品…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        {isInvalid ? (
+          <FieldError>搜索内容至少需要 {MIN_LENGTH} 个字符</FieldError>
+        ) : (
+          <Description>请输入至少 {MIN_LENGTH} 个字符后再搜索</Description>
+        )}
+      </SearchField>
+      <Button
+        className="w-full"
+        isDisabled={value.length < MIN_LENGTH}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            搜索中…
+          </>
+        ) : (
+          "搜索"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/full-width.tsx b/apps/docs/src/demos/cn/search-field/full-width.tsx
new file mode 100644
index 0000000..285538c
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/full-width.tsx
@@ -0,0 +1,16 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <SearchField fullWidth name="search">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/index.ts b/apps/docs/src/demos/cn/search-field/index.ts
new file mode 100644
index 0000000..fd9642e
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/index.ts
@@ -0,0 +1,14 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIcons} from "./custom-icons";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithKeyboardShortcut} from "./with-keyboard-shortcut";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/cn/search-field/on-surface.tsx b/apps/docs/src/demos/cn/search-field/on-surface.tsx
new file mode 100644
index 0000000..aff85c9
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/on-surface.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <SearchField name="search" variant="secondary">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>输入关键词进行搜索</Description>
+      </SearchField>
+      <SearchField name="search-2" variant="secondary">
+        <Label>高级搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="高级搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>使用筛选条件细化搜索</Description>
+      </SearchField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/required.tsx b/apps/docs/src/demos/cn/search-field/required.tsx
new file mode 100644
index 0000000..f633d5a
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/required.tsx
@@ -0,0 +1,25 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isRequired name="search">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField isRequired name="search-query">
+        <Label>搜索内容</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="输入搜索内容…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>至少需要 3 个字符</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/validation.tsx b/apps/docs/src/demos/cn/search-field/validation.tsx
new file mode 100644
index 0000000..d3edb3e
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/validation.tsx
@@ -0,0 +1,26 @@
+import {FieldError, Label, SearchField} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isInvalid isRequired name="search" value="ab">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>搜索内容至少需要 3 个字符</FieldError>
+      </SearchField>
+      <SearchField isInvalid name="search-invalid">
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" value="invalid@query" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>搜索内容包含无效字符</FieldError>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/variants.tsx b/apps/docs/src/demos/cn/search-field/variants.tsx
new file mode 100644
index 0000000..af94ecc
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/variants.tsx
@@ -0,0 +1,24 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="primary-search" variant="primary">
+        <Label>主要变体</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField name="secondary-search" variant="secondary">
+        <Label>次要变体</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/with-description.tsx b/apps/docs/src/demos/cn/search-field/with-description.tsx
new file mode 100644
index 0000000..a97fc9b
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/with-description.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search">
+        <Label>搜索产品</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索产品…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>输入关键词进行搜索 for products</Description>
+      </SearchField>
+      <SearchField name="search-users">
+        <Label>搜索用户</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索用户…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>按姓名、邮箱或用户名搜索</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/with-keyboard-shortcut.tsx b/apps/docs/src/demos/cn/search-field/with-keyboard-shortcut.tsx
new file mode 100644
index 0000000..2765c77
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/with-keyboard-shortcut.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import {Description, Kbd, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function WithKeyboardShortcut() {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const [value, setValue] = React.useState("");
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Check for Shift+S
+      if (e.shiftKey && e.key === "S" && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        e.preventDefault();
+        inputRef.current?.focus();
+      }
+      // Check for ESC key to blur the input
+      if (e.key === "Escape" && document.activeElement === inputRef.current) {
+        inputRef.current?.blur();
+      }
+    };
+
+    // Add global event listener
+    window.addEventListener("keydown", handleKeyDown);
+
+    // Cleanup on unmount
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <SearchField name="search" value={value} onChange={setValue}>
+          <Label>搜索</Label>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="搜索…" />
+            <SearchField.ClearButton />
+          </SearchField.Group>
+          <Description>使用键盘快捷键快速聚焦此输入框</Description>
+        </SearchField>
+      </div>
+      <div className="text-default-500 flex items-center gap-2 text-sm">
+        <span>按</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>S</Kbd.Content>
+        </Kbd>
+        <span>聚焦搜索框</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/search-field/with-validation.tsx b/apps/docs/src/demos/cn/search-field/with-validation.tsx
new file mode 100644
index 0000000..079d6d9
--- /dev/null
+++ b/apps/docs/src/demos/cn/search-field/with-validation.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Description, FieldError, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState("");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
+        <Label>搜索</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="搜索…" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        {isInvalid ? (
+          <FieldError>搜索内容至少需要 3 个字符</FieldError>
+        ) : (
+          <Description>请输入至少 3 个字符后再搜索</Description>
+        )}
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/asynchronous-loading.tsx b/apps/docs/src/demos/cn/select/asynchronous-loading.tsx
new file mode 100644
index 0000000..5a4b9bd
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/asynchronous-loading.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {Label, ListBox, Select, Spinner} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+import {Collection, ListBoxLoadMoreItem} from "react-aria-components";
+
+interface Pokemon {
+  name: string;
+}
+
+export function AsynchronousLoading() {
+  const list = useAsyncList<Pokemon>({
+    async load({cursor, signal}) {
+      const res = await fetch(cursor || `https://pokeapi.co/api/v2/pokemon`, {signal});
+      const json = await res.json();
+
+      return {
+        cursor: json.next,
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <Select className="w-[256px]" placeholder="请选择宝可梦">
+      <Label>选择宝可梦</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <Collection items={list.items}>
+            {(item: Pokemon) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="text-sm text-muted">加载更多…</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/controlled-multiple.tsx b/apps/docs/src/demos/cn/select/controlled-multiple.tsx
new file mode 100644
index 0000000..ab384ab
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/controlled-multiple.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Label, ListBox, Select} from "@heroui/react";
+import React from "react";
+
+export function ControlledMultiple() {
+  const [selected, setSelected] = React.useState<Key[]>(["california", "texas"]);
+
+  return (
+    <div className="space-y-4">
+      <Select
+        className="w-[256px]"
+        placeholder="请选择州"
+        selectionMode="multiple"
+        value={selected}
+        onChange={(keys) => setSelected(keys as Key[])}
+      >
+        <Label>州（受控多选）</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox selectionMode="multiple">
+            <ListBox.Item id="california" textValue="加利福尼亚">
+              加利福尼亚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="德克萨斯">
+              德克萨斯
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="florida" textValue="佛罗里达">
+              佛罗里达
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="纽约">
+              纽约
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="illinois" textValue="伊利诺伊">
+              伊利诺伊
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="pennsylvania" textValue="宾夕法尼亚">
+              宾夕法尼亚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <p className="text-sm text-muted">已选：{selected.length > 0 ? selected.join(", ") : "无"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/controlled-open-state.tsx b/apps/docs/src/demos/cn/select/controlled-open-state.tsx
new file mode 100644
index 0000000..dbdc9a8
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/controlled-open-state.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {Button, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <Select className="w-[256px]" isOpen={isOpen} placeholder="请选择" onOpenChange={setIsOpen}>
+        <Label>州</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="佛罗里达">
+              佛罗里达
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="特拉华">
+              特拉华
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="加利福尼亚">
+              加利福尼亚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="德克萨斯">
+              德克萨斯
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="纽约">
+              纽约
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="华盛顿">
+              华盛顿
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "关闭" : "打开"}选择框</Button>
+      <p className="text-sm text-muted">选择框{isOpen ? "已打开" : "已关闭"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/controlled.tsx b/apps/docs/src/demos/cn/select/controlled.tsx
new file mode 100644
index 0000000..f9bd6da
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/controlled.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const states = [
+    {
+      id: "california",
+      name: "加利福尼亚",
+    },
+    {
+      id: "texas",
+      name: "德克萨斯",
+    },
+    {
+      id: "florida",
+      name: "佛罗里达",
+    },
+    {
+      id: "new-york",
+      name: "纽约",
+    },
+    {
+      id: "illinois",
+      name: "伊利诺伊",
+    },
+    {
+      id: "pennsylvania",
+      name: "宾夕法尼亚",
+    },
+  ];
+
+  const [state, setState] = useState<Key | null>("california");
+
+  const selectedState = states.find((s) => s.id === state);
+
+  return (
+    <div className="space-y-2">
+      <Select
+        className="w-[256px]"
+        placeholder="请选择州"
+        value={state}
+        onChange={(value) => setState(value)}
+      >
+        <Label>州（受控）</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {states.map((state) => (
+              <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                {state.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <p className="text-sm text-muted">已选：{selectedState?.name || "无"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/custom-indicator.tsx b/apps/docs/src/demos/cn/select/custom-indicator.tsx
new file mode 100644
index 0000000..0d13f06
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/custom-indicator.tsx
@@ -0,0 +1,44 @@
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <Select className="w-[256px]" placeholder="请选择">
+      <Label>州</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator className="size-3">
+          <ChevronsExpandVertical />
+        </Select.Indicator>
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="佛罗里达">
+            佛罗里达
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="特拉华">
+            特拉华
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="加利福尼亚">
+            加利福尼亚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="德克萨斯">
+            德克萨斯
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="纽约">
+            纽约
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="华盛顿">
+            华盛顿
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/custom-render-function.tsx b/apps/docs/src/demos/cn/select/custom-render-function.tsx
new file mode 100644
index 0000000..db2cd9d
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/custom-render-function.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Select
+      className="w-[256px]"
+      placeholder="请选择"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>州</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="佛罗里达">
+            佛罗里达
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="特拉华">
+            特拉华
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="加利福尼亚">
+            加利福尼亚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="德克萨斯">
+            德克萨斯
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="纽约">
+            纽约
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="华盛顿">
+            华盛顿
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/custom-value-multiple.tsx b/apps/docs/src/demos/cn/select/custom-value-multiple.tsx
new file mode 100644
index 0000000..e245d3c
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/custom-value-multiple.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Chip,
+  Description,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+
+export function CustomValueMultiple() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <Select
+      className="w-[256px]"
+      defaultValue={["1", "2"]}
+      placeholder="请选择队友"
+      selectionMode="multiple"
+    >
+      <Label>用户</Label>
+      <Select.Trigger>
+        <Select.Value className="no-truncate flex flex-wrap gap-2">
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return selectedItemsKeys.map((selectedItemKey) => {
+              const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+              if (!selectedItem) {
+                return null;
+              }
+
+              return (
+                <Chip key={selectedItemKey} variant="soft">
+                  <Avatar className="size-4" size="sm">
+                    <AvatarImage src={selectedItem.avatarUrl} />
+                    <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                  </Avatar>
+                  <Chip.Label>{selectedItem.name}</Chip.Label>
+                </Chip>
+              );
+            });
+          }}
+        </Select.Value>
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/custom-value.tsx b/apps/docs/src/demos/cn/select/custom-value.tsx
new file mode 100644
index 0000000..bb3104c
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/custom-value.tsx
@@ -0,0 +1,106 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+
+export function CustomValue() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <Select className="w-[256px]" placeholder="请选择用户">
+      <Label>用户</Label>
+      <Select.Trigger>
+        <Select.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItems = state.selectedItems;
+
+            if (selectedItems.length > 1) {
+              return `${selectedItems.length} 位用户已选`;
+            }
+
+            const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
+
+            if (!selectedItem) {
+              return defaultChildren;
+            }
+
+            return (
+              <div className="flex items-center gap-2">
+                <Avatar className="size-4" size="sm">
+                  <AvatarImage src={selectedItem.avatarUrl} />
+                  <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                </Avatar>
+                <span>{selectedItem.name}</span>
+              </div>
+            );
+          }}
+        </Select.Value>
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/default.tsx b/apps/docs/src/demos/cn/select/default.tsx
new file mode 100644
index 0000000..fe3d56e
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/default.tsx
@@ -0,0 +1,41 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Select className="w-[256px]" placeholder="请选择">
+      <Label>州</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="佛罗里达">
+            佛罗里达
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="特拉华">
+            特拉华
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="加利福尼亚">
+            加利福尼亚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="德克萨斯">
+            德克萨斯
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="纽约">
+            纽约
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="华盛顿">
+            华盛顿
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/disabled.tsx b/apps/docs/src/demos/cn/select/disabled.tsx
new file mode 100644
index 0000000..ce0c31d
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/disabled.tsx
@@ -0,0 +1,84 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Select isDisabled className="w-[256px]" defaultValue="california" placeholder="请选择">
+        <Label>州</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="佛罗里达">
+              佛罗里达
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="特拉华">
+              特拉华
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="加利福尼亚">
+              加利福尼亚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="德克萨斯">
+              德克萨斯
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="纽约">
+              纽约
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="华盛顿">
+              华盛顿
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select
+        isDisabled
+        className="w-[256px]"
+        defaultValue={["argentina", "japan", "france"]}
+        placeholder="请选择国家"
+        selectionMode="multiple"
+      >
+        <Label>拟访问国家</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="argentina" textValue="阿根廷">
+              阿根廷
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="venezuela" textValue="委内瑞拉">
+              委内瑞拉
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="japan" textValue="日本">
+              日本
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="法国">
+              法国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="意大利">
+              意大利
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="西班牙">
+              西班牙
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/full-width.tsx b/apps/docs/src/demos/cn/select/full-width.tsx
new file mode 100644
index 0000000..06cfcbf
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/full-width.tsx
@@ -0,0 +1,31 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <Select fullWidth placeholder="请选择">
+        <Label>喜爱的动物</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="猫">
+              猫
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="狗">
+              狗
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="bird" textValue="鸟">
+              鸟
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/index.ts b/apps/docs/src/demos/cn/select/index.ts
new file mode 100644
index 0000000..564c223
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/index.ts
@@ -0,0 +1,19 @@
+// Select demos
+export {AsynchronousLoading} from "./asynchronous-loading";
+export {Controlled} from "./controlled";
+export {ControlledMultiple} from "./controlled-multiple";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomValue} from "./custom-value";
+export {CustomValueMultiple} from "./custom-value-multiple";
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {MultipleSelect} from "./multiple-select";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/cn/select/multiple-select.tsx b/apps/docs/src/demos/cn/select/multiple-select.tsx
new file mode 100644
index 0000000..1689431
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/multiple-select.tsx
@@ -0,0 +1,53 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function MultipleSelect() {
+  return (
+    <Select className="w-[256px]" placeholder="请选择国家" selectionMode="multiple">
+      <Label>拟访问国家</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox selectionMode="multiple">
+          <ListBox.Item id="argentina" textValue="阿根廷">
+            阿根廷
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="venezuela" textValue="委内瑞拉">
+            委内瑞拉
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="japan" textValue="日本">
+            日本
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="france" textValue="法国">
+            法国
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="italy" textValue="意大利">
+            意大利
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="spain" textValue="西班牙">
+            西班牙
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="thailand" textValue="泰国">
+            泰国
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-zealand" textValue="新西兰">
+            新西兰
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="iceland" textValue="冰岛">
+            冰岛
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/on-surface.tsx b/apps/docs/src/demos/cn/select/on-surface.tsx
new file mode 100644
index 0000000..45d3fe1
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/on-surface.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import {Button, FieldError, Form, Label, ListBox, Select, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Surface className="w-[320px] rounded-3xl p-6">
+      <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}>
+        <Select isRequired className="w-full" name="state" placeholder="请选择" variant="secondary">
+          <Label>州</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="florida" textValue="佛罗里达">
+                佛罗里达
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="delaware" textValue="特拉华">
+                特拉华
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="california" textValue="加利福尼亚">
+                加利福尼亚
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="texas" textValue="德克萨斯">
+                德克萨斯
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="new-york" textValue="纽约">
+                纽约
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="washington" textValue="华盛顿">
+                华盛顿
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Select
+          isRequired
+          className="w-full"
+          name="country"
+          placeholder="请选择国家"
+          variant="secondary"
+        >
+          <Label>国家</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="usa" textValue="美国">
+                美国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="加拿大">
+                加拿大
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="mexico" textValue="墨西哥">
+                墨西哥
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="uk" textValue="英国">
+                英国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="france" textValue="法国">
+                法国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="德国">
+                德国
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Button type="submit">提交</Button>
+      </Form>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/required.tsx b/apps/docs/src/demos/cn/select/required.tsx
new file mode 100644
index 0000000..30ae71b
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/required.tsx
@@ -0,0 +1,96 @@
+"use client";
+
+import {Button, FieldError, Form, Label, ListBox, Select} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("表单提交成功！");
+  };
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <Select isRequired className="w-full" name="state" placeholder="请选择">
+        <Label>州</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="佛罗里达">
+              佛罗里达
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="特拉华">
+              特拉华
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="加利福尼亚">
+              加利福尼亚
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="德克萨斯">
+              德克萨斯
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="纽约">
+              纽约
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="华盛顿">
+              华盛顿
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+        <FieldError />
+      </Select>
+      <Select isRequired className="w-full" name="country" placeholder="请选择国家">
+        <Label>国家</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="usa" textValue="美国">
+              美国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="加拿大">
+              加拿大
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="墨西哥">
+              墨西哥
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="uk" textValue="英国">
+              英国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="法国">
+              法国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="德国">
+              德国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+        <FieldError />
+      </Select>
+      <Button type="submit">提交</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/variants.tsx b/apps/docs/src/demos/cn/select/variants.tsx
new file mode 100644
index 0000000..878756a
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/variants.tsx
@@ -0,0 +1,46 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Select className="w-[256px]" placeholder="请选择" variant="primary">
+        <Label>主要变体</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="选项 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="选项 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select className="w-[256px]" placeholder="请选择" variant="secondary">
+        <Label>次要变体</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="选项 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="选项 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/with-description.tsx b/apps/docs/src/demos/cn/select/with-description.tsx
new file mode 100644
index 0000000..5077402
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/with-description.tsx
@@ -0,0 +1,42 @@
+import {Description, Label, ListBox, Select} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <Select className="w-[256px]" placeholder="请选择">
+      <Label>州</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="佛罗里达">
+            佛罗里达
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="特拉华">
+            特拉华
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="加利福尼亚">
+            加利福尼亚
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="德克萨斯">
+            德克萨斯
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="纽约">
+            纽约
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="华盛顿">
+            华盛顿
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+      <Description>请选择居住州</Description>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/with-disabled-options.tsx b/apps/docs/src/demos/cn/select/with-disabled-options.tsx
new file mode 100644
index 0000000..8896c08
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/with-disabled-options.tsx
@@ -0,0 +1,41 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function WithDisabledOptions() {
+  return (
+    <Select className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="请选择动物">
+      <Label>动物</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="狗">
+            狗
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="猫">
+            猫
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="鸟">
+            鸟
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="袋鼠">
+            袋鼠
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="大象">
+            大象
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="老虎">
+            老虎
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/select/with-sections.tsx b/apps/docs/src/demos/cn/select/with-sections.tsx
new file mode 100644
index 0000000..41ea7c2
--- /dev/null
+++ b/apps/docs/src/demos/cn/select/with-sections.tsx
@@ -0,0 +1,76 @@
+import {Header, Label, ListBox, Select, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Select className="w-[256px]" placeholder="请选择国家">
+      <Label>国家</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>北美洲</Header>
+            <ListBox.Item id="usa" textValue="美国">
+              美国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="加拿大">
+              加拿大
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="墨西哥">
+              墨西哥
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>欧洲</Header>
+            <ListBox.Item id="uk" textValue="英国">
+              英国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="法国">
+              法国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="德国">
+              德国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="西班牙">
+              西班牙
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="意大利">
+              意大利
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>亚洲</Header>
+            <ListBox.Item id="japan" textValue="日本">
+              日本
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="中国">
+              中国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="印度">
+              印度
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="韩国">
+              韩国
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/basic.tsx b/apps/docs/src/demos/cn/separator/basic.tsx
new file mode 100644
index 0000000..4d471e2
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/basic.tsx
@@ -0,0 +1,20 @@
+import {Separator} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="max-w-md">
+      <div className="space-y-1">
+        <h4 className="text-medium font-medium">HeroUI v3 组件</h4>
+        <p className="text-small text-default-400">美观、快速、现代的 React UI 库。</p>
+      </div>
+      <Separator className="my-4" />
+      <div className="text-small flex h-5 items-center space-x-4">
+        <div>博客</div>
+        <Separator orientation="vertical" />
+        <div>文档</div>
+        <Separator orientation="vertical" />
+        <div>源码</div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/custom-render-function.tsx b/apps/docs/src/demos/cn/separator/custom-render-function.tsx
new file mode 100644
index 0000000..542fb9e
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/custom-render-function.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Separator} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="max-w-md">
+      <div className="space-y-1">
+        <h4 className="text-medium font-medium">HeroUI v3 组件</h4>
+        <p className="text-small text-default-400">美观、快速、现代的 React UI 库。</p>
+      </div>
+      <Separator className="my-4" render={(props) => <div {...props} data-custom="foo" />} />
+      <div className="text-small flex h-5 items-center space-x-4">
+        <div>博客</div>
+        <Separator
+          orientation="vertical"
+          render={(props) => <div {...props} data-custom="foo" />}
+        />
+        <div>文档</div>
+        <Separator
+          orientation="vertical"
+          render={(props) => <div {...props} data-custom="foo" />}
+        />
+        <div>源码</div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/index.ts b/apps/docs/src/demos/cn/separator/index.ts
new file mode 100644
index 0000000..88742b9
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {ManualVariantOverride} from "./manual-variant-override";
+export {WithSurface} from "./with-surface";
+export {Vertical} from "./vertical";
+export {WithContent} from "./with-content";
+export {Variants} from "./variants";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/separator/manual-variant-override.tsx b/apps/docs/src/demos/cn/separator/manual-variant-override.tsx
new file mode 100644
index 0000000..9ff5423
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/manual-variant-override.tsx
@@ -0,0 +1,25 @@
+import {Separator, Surface} from "@heroui/react";
+
+export function ManualVariantOverride() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">默认表面上的分隔线</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <Separator />
+          <p className="text-sm text-muted">分隔线会适应表面背景。</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">次要表面上的分隔线</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <Separator />
+          <p className="text-sm text-muted">分隔线会适应表面背景。</p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/variants.tsx b/apps/docs/src/demos/cn/separator/variants.tsx
new file mode 100644
index 0000000..d0fe4f2
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/variants.tsx
@@ -0,0 +1,14 @@
+import {Separator} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex max-w-md flex-col items-center gap-3">
+      <div>默认变体</div>
+      <Separator variant="default" />
+      <div>次要变体</div>
+      <Separator variant="secondary" />
+      <div>第三变体</div>
+      <Separator variant="tertiary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/vertical.tsx b/apps/docs/src/demos/cn/separator/vertical.tsx
new file mode 100644
index 0000000..ac61fc6
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/vertical.tsx
@@ -0,0 +1,13 @@
+import {Separator} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="text-small flex h-5 items-center space-x-4">
+      <div>博客</div>
+      <Separator orientation="vertical" />
+      <div>文档</div>
+      <Separator orientation="vertical" />
+      <div>源码</div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/with-content.tsx b/apps/docs/src/demos/cn/separator/with-content.tsx
new file mode 100644
index 0000000..3aad652
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/with-content.tsx
@@ -0,0 +1,39 @@
+import {Separator} from "@heroui/react";
+
+const items = [
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    subtitle: "接收账户活动更新",
+    title: "设置通知",
+  },
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    subtitle: "将浏览器连接到你的账户",
+    title: "设置浏览器扩展",
+  },
+  {
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    subtitle: "创建你的第一件收藏品",
+    title: "铸造收藏品",
+  },
+];
+
+export function WithContent() {
+  return (
+    <div className="max-w-md space-y-4">
+      {items.map((item, index) => (
+        <div key={index}>
+          <div className="flex items-center gap-3">
+            <img alt={item.title} className="size-12" src={item.iconUrl} />
+            <div className="flex-1 space-y-0">
+              <h4 className="text-small font-medium">{item.title}</h4>
+              <p className="text-sm text-muted">{item.subtitle}</p>
+            </div>
+          </div>
+          {index < items.length - 1 && <Separator className="my-4" />}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/separator/with-surface.tsx b/apps/docs/src/demos/cn/separator/with-surface.tsx
new file mode 100644
index 0000000..8ece962
--- /dev/null
+++ b/apps/docs/src/demos/cn/separator/with-surface.tsx
@@ -0,0 +1,42 @@
+import {Separator, Surface} from "@heroui/react";
+
+export function WithSurface() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">默认表面</h3>
+          <Separator />
+          <p className="text-sm text-muted">表面内容</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">次要表面</h3>
+          <Separator variant="secondary" />
+          <p className="text-sm text-muted">表面内容</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <h3 className="text-base font-semibold text-foreground">第三表面</h3>
+          <Separator variant="tertiary" />
+          <p className="text-sm text-muted">表面内容</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <h3 className="text-base font-semibold text-foreground">透明表面</h3>
+          <Separator />
+          <p className="text-sm text-muted">表面内容</p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/animation-types.tsx b/apps/docs/src/demos/cn/skeleton/animation-types.tsx
new file mode 100644
index 0000000..d0c6628
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/animation-types.tsx
@@ -0,0 +1,34 @@
+import {Skeleton} from "@heroui/react";
+
+export function AnimationTypes() {
+  return (
+    <div className="grid w-full max-w-xl grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">微光</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="shimmer" className="h-20 rounded-lg" />
+          <Skeleton animationType="shimmer" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="shimmer" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">脉冲</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="pulse" className="h-20 rounded-lg" />
+          <Skeleton animationType="pulse" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="pulse" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">无</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="none" className="h-20 rounded-lg" />
+          <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/basic.tsx b/apps/docs/src/demos/cn/skeleton/basic.tsx
new file mode 100644
index 0000000..cebdc71
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/basic.tsx
@@ -0,0 +1,14 @@
+import {Skeleton} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="shadow-panel w-[250px] space-y-5 rounded-lg bg-transparent p-4">
+      <Skeleton className="h-32 rounded-lg" />
+      <div className="space-y-3">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+        <Skeleton className="h-3 w-2/5 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/card.tsx b/apps/docs/src/demos/cn/skeleton/card.tsx
new file mode 100644
index 0000000..3d67932
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/card.tsx
@@ -0,0 +1,14 @@
+import {Skeleton} from "@heroui/react";
+
+export function Card() {
+  return (
+    <div className="bg-surface-1 shadow-panel w-[250px] space-y-5 rounded-lg p-4">
+      <Skeleton className="h-32 rounded-lg" />
+      <div className="space-y-3">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+        <Skeleton className="h-3 w-2/5 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/grid.tsx b/apps/docs/src/demos/cn/skeleton/grid.tsx
new file mode 100644
index 0000000..53bce71
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/grid.tsx
@@ -0,0 +1,11 @@
+import {Skeleton} from "@heroui/react";
+
+export function Grid() {
+  return (
+    <div className="grid w-full max-w-xl grid-cols-3 gap-4">
+      <Skeleton className="h-24 rounded-xl" />
+      <Skeleton className="h-24 rounded-xl" />
+      <Skeleton className="h-24 rounded-xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/index.ts b/apps/docs/src/demos/cn/skeleton/index.ts
new file mode 100644
index 0000000..94b1293
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {TextContent} from "./text-content";
+export {UserProfile} from "./user-profile";
+export {List} from "./list";
+export {AnimationTypes} from "./animation-types";
+export {Grid} from "./grid";
+export {SingleShimmer} from "./single-shimmer";
diff --git a/apps/docs/src/demos/cn/skeleton/list.tsx b/apps/docs/src/demos/cn/skeleton/list.tsx
new file mode 100644
index 0000000..e6872b1
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/list.tsx
@@ -0,0 +1,17 @@
+import {Skeleton} from "@heroui/react";
+
+export function List() {
+  return (
+    <div className="w-full max-w-sm space-y-4">
+      {Array.from({length: 3}).map((_, index) => (
+        <div key={index} className="flex items-center gap-3">
+          <Skeleton className="h-10 w-10 shrink-0 rounded-lg" />
+          <div className="flex-1 space-y-2">
+            <Skeleton className="h-3 w-full rounded" />
+            <Skeleton className="h-3 w-4/5 rounded" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/single-shimmer.tsx b/apps/docs/src/demos/cn/skeleton/single-shimmer.tsx
new file mode 100644
index 0000000..1fa7317
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/single-shimmer.tsx
@@ -0,0 +1,11 @@
+import {Skeleton} from "@heroui/react";
+
+export function SingleShimmer() {
+  return (
+    <div className="skeleton--shimmer relative grid w-full max-w-xl grid-cols-3 gap-4 overflow-hidden rounded-xl">
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/text-content.tsx b/apps/docs/src/demos/cn/skeleton/text-content.tsx
new file mode 100644
index 0000000..67c05ab
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/text-content.tsx
@@ -0,0 +1,13 @@
+import {Skeleton} from "@heroui/react";
+
+export function TextContent() {
+  return (
+    <div className="w-full max-w-md space-y-3">
+      <Skeleton className="h-4 w-full rounded" />
+      <Skeleton className="h-4 w-5/6 rounded" />
+      <Skeleton className="h-4 w-4/6 rounded" />
+      <Skeleton className="h-4 w-full rounded" />
+      <Skeleton className="h-4 w-3/6 rounded" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/skeleton/user-profile.tsx b/apps/docs/src/demos/cn/skeleton/user-profile.tsx
new file mode 100644
index 0000000..7d465d7
--- /dev/null
+++ b/apps/docs/src/demos/cn/skeleton/user-profile.tsx
@@ -0,0 +1,13 @@
+import {Skeleton} from "@heroui/react";
+
+export function UserProfile() {
+  return (
+    <div className="flex items-center gap-3">
+      <Skeleton className="h-10 w-10 shrink-0 rounded-full" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-3 w-36 rounded-lg" />
+        <Skeleton className="h-3 w-24 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/slider/custom-render-function.tsx b/apps/docs/src/demos/cn/slider/custom-render-function.tsx
new file mode 100644
index 0000000..eef01c6
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Label, Slider} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Slider
+      className="w-full max-w-xs"
+      defaultValue={30}
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>音量</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/slider/default.tsx b/apps/docs/src/demos/cn/slider/default.tsx
new file mode 100644
index 0000000..672ea5e
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/default.tsx
@@ -0,0 +1,14 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Slider className="w-full max-w-xs" defaultValue={30}>
+      <Label>音量</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/slider/disabled.tsx b/apps/docs/src/demos/cn/slider/disabled.tsx
new file mode 100644
index 0000000..5d15b59
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/disabled.tsx
@@ -0,0 +1,14 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Slider isDisabled className="w-full max-w-xs" defaultValue={30}>
+      <Label>音量</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/slider/index.ts b/apps/docs/src/demos/cn/slider/index.ts
new file mode 100644
index 0000000..15c42a7
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/index.ts
@@ -0,0 +1,6 @@
+// Slider demos
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {Range} from "./range";
+export {Vertical} from "./vertical";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/slider/range.tsx b/apps/docs/src/demos/cn/slider/range.tsx
new file mode 100644
index 0000000..0221b19
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/range.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Label, Slider} from "@heroui/react";
+
+export function Range() {
+  return (
+    <Slider
+      className="w-full max-w-xs"
+      defaultValue={[100, 500]}
+      formatOptions={{currency: "USD", style: "currency"}}
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    >
+      <Label>价格区间</Label>
+      <Slider.Output />
+      <Slider.Track>
+        {({state}) => (
+          <>
+            <Slider.Fill />
+            {state.values.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/cn/slider/vertical.tsx b/apps/docs/src/demos/cn/slider/vertical.tsx
new file mode 100644
index 0000000..3c7053a
--- /dev/null
+++ b/apps/docs/src/demos/cn/slider/vertical.tsx
@@ -0,0 +1,16 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="flex h-64 items-center justify-center">
+      <Slider className="h-full" defaultValue={30} orientation="vertical">
+        <Label>音量</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/spinner/basic.tsx b/apps/docs/src/demos/cn/spinner/basic.tsx
new file mode 100644
index 0000000..824479e
--- /dev/null
+++ b/apps/docs/src/demos/cn/spinner/basic.tsx
@@ -0,0 +1,9 @@
+import {Spinner} from "@heroui/react";
+
+export function SpinnerBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Spinner />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/spinner/colors.tsx b/apps/docs/src/demos/cn/spinner/colors.tsx
new file mode 100644
index 0000000..2180f35
--- /dev/null
+++ b/apps/docs/src/demos/cn/spinner/colors.tsx
@@ -0,0 +1,24 @@
+import {Spinner} from "@heroui/react";
+
+const COLOR_LABELS = {
+  accent: "强调",
+  current: "当前",
+  danger: "危险",
+  success: "成功",
+  warning: "警告",
+} as const;
+
+const colors = ["current", "accent", "success", "warning", "danger"] as const;
+
+export function SpinnerColors() {
+  return (
+    <div className="flex items-center gap-8">
+      {colors.map((color) => (
+        <div key={color} className="flex flex-col items-center gap-2">
+          <Spinner color={color} />
+          <span className="text-xs text-muted">{COLOR_LABELS[color]}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/spinner/index.ts b/apps/docs/src/demos/cn/spinner/index.ts
new file mode 100644
index 0000000..3dfa394
--- /dev/null
+++ b/apps/docs/src/demos/cn/spinner/index.ts
@@ -0,0 +1,3 @@
+export {SpinnerBasic as Basic} from "./basic";
+export {SpinnerColors as Colors} from "./colors";
+export {SpinnerSizes as Sizes} from "./sizes";
diff --git a/apps/docs/src/demos/cn/spinner/sizes.tsx b/apps/docs/src/demos/cn/spinner/sizes.tsx
new file mode 100644
index 0000000..148ce41
--- /dev/null
+++ b/apps/docs/src/demos/cn/spinner/sizes.tsx
@@ -0,0 +1,23 @@
+import {Spinner} from "@heroui/react";
+
+const SIZE_LABELS = {
+  lg: "大",
+  md: "中",
+  sm: "小",
+  xl: "特大",
+} as const;
+
+const sizes = ["sm", "md", "lg", "xl"] as const;
+
+export function SpinnerSizes() {
+  return (
+    <div className="flex items-center gap-8">
+      {sizes.map((size) => (
+        <div key={size} className="flex flex-col items-center gap-2">
+          <Spinner size={size} />
+          <span className="text-xs text-muted">{SIZE_LABELS[size]}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/surface/index.ts b/apps/docs/src/demos/cn/surface/index.ts
new file mode 100644
index 0000000..6dcf15e
--- /dev/null
+++ b/apps/docs/src/demos/cn/surface/index.ts
@@ -0,0 +1 @@
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/surface/variants.tsx b/apps/docs/src/demos/cn/surface/variants.tsx
new file mode 100644
index 0000000..d81de87
--- /dev/null
+++ b/apps/docs/src/demos/cn/surface/variants.tsx
@@ -0,0 +1,44 @@
+import {Surface} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">默认</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <p className="text-sm text-muted">这是默认表面变体，使用 bg-surface 样式。</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">次要</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <p className="text-sm text-muted">这是次要表面变体，使用 bg-surface-secondary 样式。</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">第三</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <p className="text-sm text-muted">这是第三表面变体，使用 bg-surface-tertiary 样式。</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">透明</p>
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <h3 className="text-base font-semibold text-foreground">表面内容</h3>
+          <p className="text-sm text-muted">
+            这是透明表面变体，无背景，适用于遮罩层和自定义背景的卡片。
+          </p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/basic.tsx b/apps/docs/src/demos/cn/switch/basic.tsx
new file mode 100644
index 0000000..b153945
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/basic.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        启用通知
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/controlled.tsx b/apps/docs/src/demos/cn/switch/controlled.tsx
new file mode 100644
index 0000000..4d0bb0a
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/controlled.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = React.useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <Switch isSelected={isSelected} onChange={setIsSelected}>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          启用通知
+        </Switch.Content>
+      </Switch>
+      <p className="text-sm text-muted">开关{isSelected ? "已打开" : "已关闭"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/custom-render-function.tsx b/apps/docs/src/demos/cn/switch/custom-render-function.tsx
new file mode 100644
index 0000000..6fd626c
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/custom-render-function.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Switch render={(props) => <div {...props} data-custom="foo" />}>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        启用通知
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/custom-styles.tsx b/apps/docs/src/demos/cn/switch/custom-styles.tsx
new file mode 100644
index 0000000..fddab3b
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/custom-styles.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Check, Power} from "@gravity-ui/icons";
+import {Switch} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Switch aria-label="Power">
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control
+            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
+          >
+            <Switch.Thumb
+              className={`size-[27px] bg-white shadow-sm ${isSelected ? "ms-[22px] shadow-lg" : ""}`}
+            >
+              <Switch.Icon>
+                {isSelected ? (
+                  <Check className="size-4 text-cyan-600" />
+                ) : (
+                  <Power className="size-4 text-blue-600" />
+                )}
+              </Switch.Icon>
+            </Switch.Thumb>
+          </Switch.Control>
+        </Switch.Content>
+      )}
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/default-selected.tsx b/apps/docs/src/demos/cn/switch/default-selected.tsx
new file mode 100644
index 0000000..76838f1
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/default-selected.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function DefaultSelected() {
+  return (
+    <Switch defaultSelected>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        启用通知
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/disabled.tsx b/apps/docs/src/demos/cn/switch/disabled.tsx
new file mode 100644
index 0000000..7e37ce1
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/disabled.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Switch isDisabled>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        启用通知
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/form.tsx b/apps/docs/src/demos/cn/switch/form.tsx
new file mode 100644
index 0000000..ca4b6e3
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/form.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Button, Switch, SwitchGroup} from "@heroui/react";
+import React from "react";
+
+export function Form() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+
+    alert(
+      `表单提交内容：\n${Array.from(formData.entries())
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n")}`,
+    );
+  };
+
+  return (
+    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+      <SwitchGroup>
+        <Switch name="notifications" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            启用通知
+          </Switch.Content>
+        </Switch>
+        <Switch defaultSelected name="newsletter" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            订阅新闻简报
+          </Switch.Content>
+        </Switch>
+        <Switch name="marketing" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            接收营销更新
+          </Switch.Content>
+        </Switch>
+      </SwitchGroup>
+      <Button className="mt-4" size="sm" type="submit" variant="primary">
+        Submit
+      </Button>
+    </form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/group-horizontal.tsx b/apps/docs/src/demos/cn/switch/group-horizontal.tsx
new file mode 100644
index 0000000..70e9b96
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/group-horizontal.tsx
@@ -0,0 +1,32 @@
+import {Switch, SwitchGroup} from "@heroui/react";
+
+export function GroupHorizontal() {
+  return (
+    <SwitchGroup className="overflow-x-auto" orientation="horizontal">
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          通知
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          营销
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          社交
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/group.tsx b/apps/docs/src/demos/cn/switch/group.tsx
new file mode 100644
index 0000000..872d775
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/group.tsx
@@ -0,0 +1,32 @@
+import {Switch, SwitchGroup} from "@heroui/react";
+
+export function Group() {
+  return (
+    <SwitchGroup>
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          允许通知
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          营销邮件
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          社交媒体更新
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/index.ts b/apps/docs/src/demos/cn/switch/index.ts
new file mode 100644
index 0000000..3381efe
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/index.ts
@@ -0,0 +1,15 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomStyles} from "./custom-styles";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DefaultSelected} from "./default-selected";
+export {Disabled} from "./disabled";
+export {Form} from "./form";
+export {Group} from "./group";
+export {GroupHorizontal} from "./group-horizontal";
+export {LabelPosition} from "./label-position";
+export {RenderProps} from "./render-props";
+export {Sizes} from "./sizes";
+export {WithDescription} from "./with-description";
+export {WithIcons} from "./with-icons";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/cn/switch/label-position.tsx b/apps/docs/src/demos/cn/switch/label-position.tsx
new file mode 100644
index 0000000..0c73f8c
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/label-position.tsx
@@ -0,0 +1,24 @@
+import {Switch} from "@heroui/react";
+
+export function LabelPosition() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          标签在后
+        </Switch.Content>
+      </Switch>
+      <Switch>
+        <Switch.Content>
+          标签在前
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </Switch.Content>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/render-props.tsx b/apps/docs/src/demos/cn/switch/render-props.tsx
new file mode 100644
index 0000000..87c3bc2
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/render-props.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+
+export function RenderProps() {
+  return (
+    <Switch>
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          {isSelected ? "已开启" : "已关闭"}
+        </Switch.Content>
+      )}
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/sizes.tsx b/apps/docs/src/demos/cn/switch/sizes.tsx
new file mode 100644
index 0000000..2d6a895
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/sizes.tsx
@@ -0,0 +1,32 @@
+import {Switch} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex gap-6">
+      <Switch size="sm">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          小
+        </Switch.Content>
+      </Switch>
+      <Switch size="md">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          中
+        </Switch.Content>
+      </Switch>
+      <Switch size="lg">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          大
+        </Switch.Content>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/with-description.tsx b/apps/docs/src/demos/cn/switch/with-description.tsx
new file mode 100644
index 0000000..3c8525e
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/with-description.tsx
@@ -0,0 +1,17 @@
+import {Description, Switch} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="max-w-sm">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          公开资料
+        </Switch.Content>
+        <Description>允许他人查看你的资料信息</Description>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/with-icons.tsx b/apps/docs/src/demos/cn/switch/with-icons.tsx
new file mode 100644
index 0000000..1174bfb
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/with-icons.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {
+  BellFill,
+  BellSlash,
+  Check,
+  Microphone,
+  MicrophoneSlash,
+  Moon,
+  Power,
+  Sun,
+  VolumeFill,
+  VolumeSlashFill,
+} from "@gravity-ui/icons";
+import {Switch} from "@heroui/react";
+
+export function WithIcons() {
+  const icons = {
+    check: {
+      off: Power,
+      on: Check,
+      selectedControlClass: "bg-green-500/80",
+    },
+    darkMode: {
+      off: Moon,
+      on: Sun,
+      selectedControlClass: "",
+    },
+    microphone: {
+      off: Microphone,
+      on: MicrophoneSlash,
+      selectedControlClass: "bg-red-500/80",
+    },
+    notification: {
+      off: BellSlash,
+      on: BellFill,
+      selectedControlClass: "bg-purple-500/80",
+    },
+    volume: {
+      off: VolumeFill,
+      on: VolumeSlashFill,
+      selectedControlClass: "bg-blue-500/80",
+    },
+  };
+
+  return (
+    <div className="flex gap-3">
+      {Object.entries(icons).map(([key, value]) => (
+        <Switch key={key} defaultSelected aria-label={key} size="lg">
+          {({isSelected}) => (
+            <Switch.Content>
+              <Switch.Control className={isSelected ? value.selectedControlClass : ""}>
+                <Switch.Thumb>
+                  <Switch.Icon>
+                    {isSelected ? (
+                      <value.on className="size-3 text-inherit opacity-100" />
+                    ) : (
+                      <value.off className="size-3 text-inherit opacity-70" />
+                    )}
+                  </Switch.Icon>
+                </Switch.Thumb>
+              </Switch.Control>
+            </Switch.Content>
+          )}
+        </Switch>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/switch/without-label.tsx b/apps/docs/src/demos/cn/switch/without-label.tsx
new file mode 100644
index 0000000..b04a319
--- /dev/null
+++ b/apps/docs/src/demos/cn/switch/without-label.tsx
@@ -0,0 +1,13 @@
+import {Switch} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <Switch aria-label="启用通知">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/async-loading.tsx b/apps/docs/src/demos/cn/table/async-loading.tsx
new file mode 100644
index 0000000..e983522
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/async-loading.tsx
@@ -0,0 +1,161 @@
+"use client";
+
+import {Chip, Spinner, Table} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: string;
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  休假: "warning",
+  在职: "success",
+  未激活: "danger",
+};
+
+const allUsers: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "产品经理",
+    status: "未激活",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "前端工程师",
+    status: "在职",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "后端工程师",
+    status: "在职",
+  },
+  {
+    email: "sophia@acme.com",
+    id: 9,
+    name: "Sophia Anderson",
+    role: "测试工程师",
+    status: "休假",
+  },
+  {email: "liam@acme.com", id: 10, name: "Liam Thomas", role: "DevOps 工程师", status: "在职"},
+  {
+    email: "lucas@acme.com",
+    id: 11,
+    name: "Lucas Martinez",
+    role: "产品经理",
+    status: "在职",
+  },
+  {
+    email: "emma@acme.com",
+    id: 12,
+    name: "Emma Johnson",
+    role: "前端工程师",
+    status: "在职",
+  },
+  {email: "noah@acme.com", id: 13, name: "Noah Davis", role: "后端工程师", status: "在职"},
+  {email: "ava@acme.com", id: 14, name: "Ava Wilson", role: "首席设计师", status: "在职"},
+  {
+    email: "oliver@acme.com",
+    id: 15,
+    name: "Oliver Martinez",
+    role: "前端工程师",
+    status: "在职",
+  },
+  {
+    email: "isabella@acme.com",
+    id: 16,
+    name: "Isabella Johnson",
+    role: "后端工程师",
+    status: "在职",
+  },
+  {email: "mia@acme.com", id: 17, name: "Mia Davis", role: "首席设计师", status: "在职"},
+  {
+    email: "william@acme.com",
+    id: 18,
+    name: "William Wilson",
+    role: "前端工程师",
+    status: "在职",
+  },
+];
+
+const ITEMS_PER_PAGE = 6;
+
+const columns = [
+  {id: "name", name: "姓名"},
+  {id: "role", name: "角色"},
+  {id: "status", name: "状态"},
+  {id: "email", name: "邮箱"},
+];
+
+export function AsyncLoading() {
+  const [items, setItems] = useState<User[]>(() => allUsers.slice(0, ITEMS_PER_PAGE));
+  const [isLoading, setIsLoading] = useState(false);
+  const isLoadingRef = useRef(false);
+  const hasMore = items.length < allUsers.length;
+
+  const loadMore = useCallback(() => {
+    if (!hasMore || isLoadingRef.current) return;
+    isLoadingRef.current = true;
+    setIsLoading(true);
+    setTimeout(() => {
+      setItems((prev) => allUsers.slice(0, prev.length + ITEMS_PER_PAGE));
+      setIsLoading(false);
+      requestAnimationFrame(() => {
+        isLoadingRef.current = false;
+      });
+    }, 1500);
+  }, [hasMore]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer className="h-[280px] overflow-y-auto">
+        <Table.Content aria-label="异步加载表格" className="min-w-[600px]">
+          <Table.Header className="sticky top-0 z-10 bg-surface-secondary">
+            {columns.map((col) => (
+              <Table.Column key={col.id} id={col.id} isRowHeader={col.id === "name"}>
+                {col.name}
+              </Table.Column>
+            ))}
+          </Table.Header>
+          <Table.Body>
+            <Table.Collection items={items}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>
+                    <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                      {user.status}
+                    </Chip>
+                  </Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              )}
+            </Table.Collection>
+            {!!hasMore && (
+              <Table.LoadMore isLoading={isLoading} scrollOffset={0} onLoadMore={loadMore}>
+                <Table.LoadMoreContent>
+                  <Spinner size="md" />
+                </Table.LoadMoreContent>
+              </Table.LoadMore>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/basic.tsx b/apps/docs/src/demos/cn/table/basic.tsx
new file mode 100644
index 0000000..c5c89ba
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/basic.tsx
@@ -0,0 +1,44 @@
+import {Table} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="团队成员" className="min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>姓名</Table.Column>
+            <Table.Column>角色</Table.Column>
+            <Table.Column>状态</Table.Column>
+            <Table.Column>邮箱</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>首席执行官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>首席技术官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>首席营销官</Table.Cell>
+              <Table.Cell>休假</Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>首席财务官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/column-resizing.tsx b/apps/docs/src/demos/cn/table/column-resizing.tsx
new file mode 100644
index 0000000..f34e15d
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/column-resizing.tsx
@@ -0,0 +1,81 @@
+import {Chip, Table} from "@heroui/react";
+
+export function ColumnResizing() {
+  return (
+    <Table>
+      <Table.ResizableContainer>
+        <Table.Content aria-label="可调整列宽的表格" className="min-w-[700px]">
+          <Table.Header>
+            <Table.Column isRowHeader defaultWidth="1fr" id="name" minWidth={160}>
+              姓名
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="role" minWidth={220}>
+              角色
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="status" minWidth={100}>
+              状态
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="email" minWidth={200}>
+              邮箱
+            </Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>首席执行官</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>首席技术官</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>首席营销官</Table.Cell>
+              <Table.Cell>
+                <Chip color="warning" size="sm" variant="soft">
+                  On Leave
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>首席财务官</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Emily Davis</Table.Cell>
+              <Table.Cell>产品经理</Table.Cell>
+              <Table.Cell>
+                <Chip color="danger" size="sm" variant="soft">
+                  Inactive
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>emily@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ResizableContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/custom-cells.tsx b/apps/docs/src/demos/cn/table/custom-cells.tsx
new file mode 100644
index 0000000..6f7b224
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/custom-cells.tsx
@@ -0,0 +1,204 @@
+"use client";
+
+import type {Selection, SortDescriptor} from "@heroui/react";
+
+import {Avatar, Button, Checkbox, Chip, Table} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  image_url: string;
+  role: string;
+  status: "在职" | "未激活" | "休假";
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  休假: "warning",
+  在职: "success",
+  未激活: "danger",
+};
+
+const users: User[] = [
+  {
+    email: "kate@acme.com",
+    id: 4586932,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "Kate Moore",
+    role: "首席执行官",
+    status: "在职",
+  },
+  {
+    email: "john@acme.com",
+    id: 5273849,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "John Smith",
+    role: "首席技术官",
+    status: "在职",
+  },
+  {
+    email: "sara@acme.com",
+    id: 7492836,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Sara Johnson",
+    role: "首席营销官",
+    status: "休假",
+  },
+  {
+    email: "michael@acme.com",
+    id: 8293746,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "Michael Brown",
+    role: "首席财务官",
+    status: "在职",
+  },
+  {
+    email: "emily@acme.com",
+    id: 1234567,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "Emily Davis",
+    role: "产品经理",
+    status: "未激活",
+  },
+];
+
+export function CustomCells() {
+  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+  const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const sortedUsers = useMemo(() => {
+    return [...users].sort((a, b) => {
+      const col = sortDescriptor.column as keyof User;
+      const first = String(a[col]);
+      const second = String(b[col]);
+      let cmp = first.localeCompare(second);
+
+      if (sortDescriptor.direction === "descending") {
+        cmp *= -1;
+      }
+
+      return cmp;
+    });
+  }, [sortDescriptor]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="自定义单元格表格"
+          className="min-w-[800px]"
+          selectedKeys={selectedKeys}
+          selectionMode="multiple"
+          sortDescriptor={sortDescriptor}
+          onSelectionChange={setSelectedKeys}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column className="pr-0">
+              <Checkbox aria-label="全选" slot="selection">
+                <Checkbox.Content>
+                  <Checkbox.Control>
+                    <Checkbox.Indicator />
+                  </Checkbox.Control>
+                </Checkbox.Content>
+              </Checkbox>
+            </Table.Column>
+            <Table.Column allowsSorting isRowHeader className="after:hidden" id="id">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  员工 ID
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="name">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  成员
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="role">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  角色
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="status">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  状态
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column className="text-end">操作</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            {sortedUsers.map((user) => (
+              <Table.Row key={user.id} id={user.id}>
+                <Table.Cell className="pr-0">
+                  <Checkbox aria-label={`选择 ${user.name}`} slot="selection" variant="secondary">
+                    <Checkbox.Content>
+                      <Checkbox.Control>
+                        <Checkbox.Indicator />
+                      </Checkbox.Control>
+                    </Checkbox.Content>
+                  </Checkbox>
+                </Table.Cell>
+                <Table.Cell className="font-medium">
+                  <div className="flex items-center gap-2">
+                    #{user.id.toString()}{" "}
+                    <Button isIconOnly size="sm" variant="ghost">
+                      <Icon className="size-4 text-muted" icon="gravity-ui:copy" />
+                    </Button>
+                  </div>
+                </Table.Cell>
+                <Table.Cell>
+                  <div className="flex items-center gap-3">
+                    <Avatar size="sm">
+                      <Avatar.Image src={user.image_url} />
+                      <Avatar.Fallback>
+                        {user.name
+                          .split(" ")
+                          .map((n) => n[0])
+                          .join("")}
+                      </Avatar.Fallback>
+                    </Avatar>
+                    <div className="flex flex-col">
+                      <span className="text-xs">{user.name}</span>
+                      <span className="text-xs text-muted">{user.email}</span>
+                    </div>
+                  </div>
+                </Table.Cell>
+                <Table.Cell className="min-w-52">{user.role}</Table.Cell>
+                <Table.Cell className="min-w-25">
+                  <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                    {user.status}
+                  </Chip>
+                </Table.Cell>
+                <Table.Cell>
+                  <div className="flex items-center gap-1">
+                    <Button isIconOnly size="sm" variant="tertiary">
+                      <Icon className="size-4" icon="gravity-ui:eye" />
+                    </Button>
+                    <Button isIconOnly size="sm" variant="tertiary">
+                      <Icon className="size-4" icon="gravity-ui:pencil" />
+                    </Button>
+                    <Button isIconOnly size="sm" variant="danger-soft">
+                      <Icon className="size-4" icon="gravity-ui:trash-bin" />
+                    </Button>
+                  </div>
+                </Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/empty-state.tsx b/apps/docs/src/demos/cn/table/empty-state.tsx
new file mode 100644
index 0000000..213d89c
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/empty-state.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {EmptyState, Table} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function EmptyStateDemo() {
+  return (
+    <Table className="min-h-[200px]">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="空表格" className="h-full min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>姓名</Table.Column>
+            <Table.Column>角色</Table.Column>
+            <Table.Column>状态</Table.Column>
+            <Table.Column>邮箱</Table.Column>
+          </Table.Header>
+          <Table.Body
+            renderEmptyState={() => (
+              <EmptyState className="flex h-full w-full flex-col items-center justify-center gap-4 text-center">
+                <Icon className="size-6 text-muted" icon="gravity-ui:tray" />
+                <span className="text-sm text-muted">未找到结果</span>
+              </EmptyState>
+            )}
+          >
+            {[]}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/expandable-rows.tsx b/apps/docs/src/demos/cn/table/expandable-rows.tsx
new file mode 100644
index 0000000..e8a74c0
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/expandable-rows.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Table, cn} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function ExpandableRows() {
+  type Row = {
+    children: Row[];
+    date: string;
+    id: string;
+    title: string;
+    type: string;
+  };
+
+  const data: Row[] = [
+    {
+      children: [
+        {
+          children: [
+            {children: [], date: "7/10/2025", id: "3", title: "周报", type: "文件"},
+            {children: [], date: "8/20/2025", id: "4", title: "预算", type: "文件"},
+          ],
+          date: "8/2/2025",
+          id: "2",
+          title: "项目",
+          type: "文件夹",
+        },
+      ],
+      date: "10/20/2025",
+      id: "1",
+      title: "文档",
+      type: "文件夹",
+    },
+    {
+      children: [
+        {children: [], date: "1/23/2026", id: "6", title: "图片 1", type: "文件"},
+        {children: [], date: "2/3/2026", id: "7", title: "图片 2", type: "文件"},
+      ],
+      date: "2/3/2026",
+      id: "5",
+      title: "照片",
+      type: "文件夹",
+    },
+  ];
+
+  const [expandedKeys, setExpandedKeys] = useState<Selection>(() => new Set(["1"]));
+
+  const renderExpandableRow = (item: Row) => {
+    return (
+      <Table.Row id={item.id} textValue={item.title}>
+        <Table.Cell textValue={item.title}>
+          {({hasChildItems, isDisabled, isExpanded, isTreeColumn}) => (
+            <span className="flex items-center gap-1">
+              {hasChildItems && isTreeColumn ? (
+                <Button
+                  isIconOnly
+                  aria-label="切换行"
+                  isDisabled={isDisabled}
+                  size="sm"
+                  slot="chevron"
+                  variant="ghost"
+                >
+                  <Icon
+                    aria-hidden
+                    icon="gravity-ui:chevron-right"
+                    className={cn(
+                      "size-4 text-muted transition-transform duration-150",
+                      isExpanded ? "rotate-90" : "",
+                    )}
+                  />
+                </Button>
+              ) : null}
+              <span>{item.title}</span>
+            </span>
+          )}
+        </Table.Cell>
+        <Table.Cell>{item.type}</Table.Cell>
+        <Table.Cell>{item.date}</Table.Cell>
+        <Table.Collection items={item.children}>{renderExpandableRow}</Table.Collection>
+      </Table.Row>
+    );
+  };
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="文件"
+          className="min-w-[520px]"
+          expandedKeys={expandedKeys}
+          treeColumn="name"
+          onExpandedChange={setExpandedKeys}
+        >
+          <Table.Header>
+            <Table.Column isRowHeader id="name">
+              姓名
+            </Table.Column>
+            <Table.Column id="type">类型</Table.Column>
+            <Table.Column id="date">修改日期</Table.Column>
+          </Table.Header>
+          <Table.Body items={data}>{renderExpandableRow}</Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/index.ts b/apps/docs/src/demos/cn/table/index.ts
new file mode 100644
index 0000000..35f7fd3
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {SecondaryVariant} from "./secondary-variant";
+export {Sorting} from "./sorting";
+export {SelectionDemo} from "./selection";
+export {EmptyStateDemo} from "./empty-state";
+export {ColumnResizing} from "./column-resizing";
+export {AsyncLoading} from "./async-loading";
+export {CustomCells} from "./custom-cells";
+export {ExpandableRows} from "./expandable-rows";
+export {PaginationDemo} from "./pagination";
+export {Virtualization} from "./virtualization";
+export {TanstackTable} from "./tanstack-table";
diff --git a/apps/docs/src/demos/cn/table/pagination.tsx b/apps/docs/src/demos/cn/table/pagination.tsx
new file mode 100644
index 0000000..a0b9d84
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/pagination.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import {Pagination, Table} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+const columns = [
+  {id: "name", name: "姓名"},
+  {id: "role", name: "角色"},
+  {id: "status", name: "状态"},
+  {id: "email", name: "邮箱"},
+];
+
+const users = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "产品经理",
+    status: "未激活",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "前端工程师",
+    status: "在职",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "后端工程师",
+    status: "在职",
+  },
+];
+
+const ROWS_PER_PAGE = 4;
+
+export function PaginationDemo() {
+  const [page, setPage] = useState(1);
+  const totalPages = Math.ceil(users.length / ROWS_PER_PAGE);
+  const pages = Array.from({length: totalPages}, (_, i) => i + 1);
+
+  const paginatedItems = useMemo(() => {
+    const start = (page - 1) * ROWS_PER_PAGE;
+
+    return users.slice(start, start + ROWS_PER_PAGE);
+  }, [page]);
+
+  const start = (page - 1) * ROWS_PER_PAGE + 1;
+  const end = Math.min(page * ROWS_PER_PAGE, users.length);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="带分页的表格" className="min-w-[600px]">
+          <Table.Header columns={columns}>
+            {(column) => (
+              <Table.Column isRowHeader={column.id === "name"}>{column.name}</Table.Column>
+            )}
+          </Table.Header>
+          <Table.Body items={paginatedItems}>
+            {(user) => (
+              <Table.Row>
+                <Table.Collection items={columns}>
+                  {(column) => <Table.Cell>{user[column.id as keyof typeof user]}</Table.Cell>}
+                </Table.Collection>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        <Pagination size="sm">
+          <Pagination.Summary>
+            {start}–{end} / 共 {users.length} 条
+          </Pagination.Summary>
+          <Pagination.Content>
+            <Pagination.Item>
+              <Pagination.Previous
+                isDisabled={page === 1}
+                onPress={() => setPage((p) => Math.max(1, p - 1))}
+              >
+                <Pagination.PreviousIcon />
+                上一页
+              </Pagination.Previous>
+            </Pagination.Item>
+            {pages.map((p) => (
+              <Pagination.Item key={p}>
+                <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ))}
+            <Pagination.Item>
+              <Pagination.Next
+                isDisabled={page === totalPages}
+                onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+              >
+                下一页
+                <Pagination.NextIcon />
+              </Pagination.Next>
+            </Pagination.Item>
+          </Pagination.Content>
+        </Pagination>
+      </Table.Footer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/secondary-variant.tsx b/apps/docs/src/demos/cn/table/secondary-variant.tsx
new file mode 100644
index 0000000..0571ba7
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/secondary-variant.tsx
@@ -0,0 +1,44 @@
+import {Table} from "@heroui/react";
+
+export function SecondaryVariant() {
+  return (
+    <Table variant="secondary">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="团队成员" className="min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>姓名</Table.Column>
+            <Table.Column>角色</Table.Column>
+            <Table.Column>状态</Table.Column>
+            <Table.Column>邮箱</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>首席执行官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>首席技术官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>首席营销官</Table.Cell>
+              <Table.Cell>休假</Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>首席财务官</Table.Cell>
+              <Table.Cell>在职</Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/selection.tsx b/apps/docs/src/demos/cn/table/selection.tsx
new file mode 100644
index 0000000..5cdc5c6
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/selection.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Checkbox, Table} from "@heroui/react";
+import {useState} from "react";
+
+const users = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"},
+];
+
+export function SelectionDemo() {
+  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+
+  return (
+    <div className="flex flex-col gap-3">
+      <Table>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="带选择的表格"
+            className="min-w-[600px]"
+            selectedKeys={selectedKeys}
+            selectionMode="multiple"
+            onSelectionChange={setSelectedKeys}
+          >
+            <Table.Header>
+              <Table.Column className="pr-0">
+                <Checkbox aria-label="全选" slot="selection">
+                  <Checkbox.Content>
+                    <Checkbox.Control>
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                  </Checkbox.Content>
+                </Checkbox>
+              </Table.Column>
+              <Table.Column isRowHeader>姓名</Table.Column>
+              <Table.Column>角色</Table.Column>
+              <Table.Column>状态</Table.Column>
+              <Table.Column>邮箱</Table.Column>
+            </Table.Header>
+            <Table.Body>
+              {users.map((user) => (
+                <Table.Row key={user.id} id={user.id}>
+                  <Table.Cell className="pr-0">
+                    <Checkbox aria-label={`选择 ${user.name}`} slot="selection" variant="secondary">
+                      <Checkbox.Content>
+                        <Checkbox.Control>
+                          <Checkbox.Indicator />
+                        </Checkbox.Control>
+                      </Checkbox.Content>
+                    </Checkbox>
+                  </Table.Cell>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>{user.status}</Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              ))}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+      </Table>
+      <p className="text-sm text-muted">
+        已选：{" "}
+        <span className="font-medium">
+          {selectedKeys === "all"
+            ? "全部"
+            : selectedKeys.size > 0
+              ? Array.from(selectedKeys).join(", ")
+              : "无"}
+        </span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/sorting.tsx b/apps/docs/src/demos/cn/table/sorting.tsx
new file mode 100644
index 0000000..b854462
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/sorting.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import type {SortDescriptor} from "@heroui/react";
+
+import {Table} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: string;
+  email: string;
+}
+
+const users: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "产品经理",
+    status: "未激活",
+  },
+];
+
+export function Sorting() {
+  const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const sortedUsers = useMemo(() => {
+    return [...users].sort((a, b) => {
+      const col = sortDescriptor.column as keyof User;
+      const first = String(a[col]);
+      const second = String(b[col]);
+      let cmp = first.localeCompare(second);
+
+      if (sortDescriptor.direction === "descending") {
+        cmp *= -1;
+      }
+
+      return cmp;
+    });
+  }, [sortDescriptor]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="可排序表格"
+          className="min-w-[600px]"
+          sortDescriptor={sortDescriptor}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column allowsSorting isRowHeader id="name">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  姓名
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="role">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  角色
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="status">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  状态
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="email">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  邮箱
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+          </Table.Header>
+          <Table.Body>
+            {sortedUsers.map((user) => (
+              <Table.Row key={user.id} id={user.id}>
+                <Table.Cell>{user.name}</Table.Cell>
+                <Table.Cell>{user.role}</Table.Cell>
+                <Table.Cell>{user.status}</Table.Cell>
+                <Table.Cell>{user.email}</Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/tanstack-table.tsx b/apps/docs/src/demos/cn/table/tanstack-table.tsx
new file mode 100644
index 0000000..d4955ea
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/tanstack-table.tsx
@@ -0,0 +1,199 @@
+"use client";
+
+import type {SortDescriptor} from "@heroui/react";
+import type {SortingState} from "@tanstack/react-table";
+
+import {Chip, Pagination, Table} from "@heroui/react";
+import {
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import {useMemo, useState} from "react";
+
+// --- Data -----------------------------------------------------------------
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: "在职" | "未激活" | "休假";
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  休假: "warning",
+  在职: "success",
+  未激活: "danger",
+};
+
+const users: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "产品经理",
+    status: "未激活",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "前端工程师",
+    status: "在职",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "后端工程师",
+    status: "在职",
+  },
+];
+
+// --- TanStack Column Definitions ------------------------------------------
+const columnHelper = createColumnHelper<User>();
+
+const columns = [
+  columnHelper.accessor("name", {header: "姓名"}),
+  columnHelper.accessor("role", {header: "角色"}),
+  columnHelper.accessor("status", {
+    cell: (info) => (
+      <Chip color={statusColorMap[info.getValue()]} size="sm" variant="soft">
+        {info.getValue()}
+      </Chip>
+    ),
+    header: "状态",
+  }),
+  columnHelper.accessor("email", {header: "邮箱"}),
+];
+
+// --- Sorting Bridge -------------------------------------------------------
+// Convert TanStack SortingState → React Aria SortDescriptor
+function toSortDescriptor(sorting: SortingState): SortDescriptor | undefined {
+  const first = sorting[0];
+
+  if (!first) return undefined;
+
+  return {
+    column: first.id,
+    direction: first.desc ? "descending" : "ascending",
+  };
+}
+
+// Convert React Aria SortDescriptor → TanStack SortingState
+function toSortingState(descriptor: SortDescriptor): SortingState {
+  return [{desc: descriptor.direction === "descending", id: descriptor.column as string}];
+}
+
+// --- Component ------------------------------------------------------------
+const PAGE_SIZE = 4;
+
+export function TanstackTable() {
+  const [sorting, setSorting] = useState<SortingState>([]);
+
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const table = useReactTable({
+    columns,
+    data: users,
+    getCoreRowModel: getCoreRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    initialState: {pagination: {pageSize: PAGE_SIZE}},
+    onSortingChange: setSorting,
+    state: {sorting},
+  });
+
+  const sortDescriptor = useMemo(() => toSortDescriptor(sorting), [sorting]);
+
+  const {pageIndex} = table.getState().pagination;
+  const pageCount = table.getPageCount();
+  const pages = Array.from({length: pageCount}, (_, i) => i + 1);
+  const start = pageIndex * PAGE_SIZE + 1;
+  const end = Math.min((pageIndex + 1) * PAGE_SIZE, users.length);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="TanStack 表格示例"
+          className="min-w-[600px]"
+          sortDescriptor={sortDescriptor}
+          onSortChange={(d) => setSorting(toSortingState(d))}
+        >
+          <Table.Header>
+            {table.getHeaderGroups()[0]!.headers.map((header) => (
+              <Table.Column
+                key={header.id}
+                allowsSorting={header.column.getCanSort()}
+                id={header.id}
+                isRowHeader={header.id === "name"}
+              >
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    {flexRender(header.column.columnDef.header, header.getContext())}
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+            ))}
+          </Table.Header>
+          <Table.Body>
+            {table.getRowModel().rows.map((row) => (
+              <Table.Row key={row.id} id={row.id}>
+                {row.getVisibleCells().map((cell) => (
+                  <Table.Cell key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </Table.Cell>
+                ))}
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        <Pagination size="sm">
+          <Pagination.Summary>
+            {start}–{end} / 共 {users.length} 条
+          </Pagination.Summary>
+          <Pagination.Content>
+            <Pagination.Item>
+              <Pagination.Previous
+                isDisabled={!table.getCanPreviousPage()}
+                onPress={() => table.previousPage()}
+              >
+                <Pagination.PreviousIcon />
+                上一页
+              </Pagination.Previous>
+            </Pagination.Item>
+            {pages.map((p) => (
+              <Pagination.Item key={p}>
+                <Pagination.Link
+                  isActive={p === pageIndex + 1}
+                  onPress={() => table.setPageIndex(p - 1)}
+                >
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ))}
+            <Pagination.Item>
+              <Pagination.Next
+                isDisabled={!table.getCanNextPage()}
+                onPress={() => table.nextPage()}
+              >
+                下一页
+                <Pagination.NextIcon />
+              </Pagination.Next>
+            </Pagination.Item>
+          </Pagination.Content>
+        </Pagination>
+      </Table.Footer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/cn/table/virtualization.tsx b/apps/docs/src/demos/cn/table/virtualization.tsx
new file mode 100644
index 0000000..76b5ad6
--- /dev/null
+++ b/apps/docs/src/demos/cn/table/virtualization.tsx
@@ -0,0 +1,132 @@
+"use client";
+
+import {Table, TableLayout, Virtualizer} from "@heroui/react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  email: string;
+}
+
+export function Virtualization() {
+  const roles = [
+    "软件工程师",
+    "高级工程师",
+    "资深工程师",
+    "产品经理",
+    "设计师",
+    "数据分析师",
+    "测试工程师",
+    "DevOps 工程师",
+    "营销经理",
+    "销售代表",
+  ];
+
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+
+  function generateUsers(count: number): User[] {
+    const users: User[] = [];
+
+    for (let i = 0; i < count; i++) {
+      const firstName = firstNames[i % firstNames.length];
+      const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+      const name = `${firstName} ${lastName}`;
+
+      users.push({
+        email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`,
+        id: i + 1,
+        name,
+        role: roles[i % roles.length] || "",
+      });
+    }
+
+    return users;
+  }
+
+  const virtualizedUsers = generateUsers(1000);
+
+  return (
+    <Virtualizer
+      layout={TableLayout}
+      layoutOptions={{
+        headingHeight: 42,
+        rowHeight: 42,
+      }}
+    >
+      <Table>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="1000 行虚拟化表格"
+            className="h-[300px] min-w-[700px] overflow-auto"
+          >
+            <Table.Header className="h-full w-full">
+              <Table.Column isRowHeader id="name" minWidth={160}>
+                姓名
+              </Table.Column>
+              <Table.Column id="role" minWidth={220}>
+                角色
+              </Table.Column>
+              <Table.Column id="email" minWidth={240}>
+                邮箱
+              </Table.Column>
+            </Table.Header>
+            <Table.Body items={virtualizedUsers}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              )}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+      </Table>
+    </Virtualizer>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/basic.tsx b/apps/docs/src/demos/cn/tabs/basic.tsx
new file mode 100644
index 0000000..4a2c076
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/basic.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="选项">
+          <Tabs.Tab id="overview">
+            概览
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            分析
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            报告
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>查看项目概览与近期活动。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>跟踪指标并分析性能数据。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>生成并下载详细报告。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/custom-render-function.tsx b/apps/docs/src/demos/cn/tabs/custom-render-function.tsx
new file mode 100644
index 0000000..42e832a
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/custom-render-function.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import {Tabs} from "@heroui/react";
+import Link from "next/link";
+
+export function CustomRenderFunction() {
+  return (
+    <Tabs className="w-full max-w-md" render={(props) => <div {...props} data-custom="foo" />}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="选项">
+          <Tabs.Tab
+            href="/docs/react/getting-started"
+            id="getting-started"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            快速入门
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab
+            href="/docs/react/components"
+            id="components"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            组件
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab
+            href="/docs/react/releases"
+            id="releases"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            发布说明
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>查看项目概览与近期活动。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>跟踪指标并分析性能数据。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>生成并下载详细报告。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/custom-styles.tsx b/apps/docs/src/demos/cn/tabs/custom-styles.tsx
new file mode 100644
index 0000000..6467bfd
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/custom-styles.tsx
@@ -0,0 +1,31 @@
+import {Tabs} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Tabs className="w-full max-w-lg text-center">
+      <Tabs.ListContainer>
+        <Tabs.List
+          aria-label="选项"
+          className="w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal *:data-[selected=true]:text-accent-foreground"
+        >
+          <Tabs.Tab id="daily">
+            每日
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="weekly">
+            每周
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="bi-weekly">
+            每两周
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="monthly">
+            每月
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/disabled.tsx b/apps/docs/src/demos/cn/tabs/disabled.tsx
new file mode 100644
index 0000000..23e407e
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/disabled.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="含禁用项的标签页">
+          <Tabs.Tab id="active">
+            启用
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab isDisabled id="disabled">
+            已禁用
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="available">
+            可用
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="active">
+        <p>此标签页已启用，可以选择。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="disabled">
+        <p>无法访问此内容。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="available">
+        <p>此标签页也可以选择。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/index.ts b/apps/docs/src/demos/cn/tabs/index.ts
new file mode 100644
index 0000000..45b7196
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Vertical} from "./vertical";
+export {Overflow} from "./overflow";
+export {Disabled} from "./disabled";
+export {CustomStyles} from "./custom-styles";
+export {WithSeparator} from "./with-separator";
+export {Secondary} from "./secondary";
+export {SecondaryVertical} from "./secondary-vertical";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/tabs/overflow.tsx b/apps/docs/src/demos/cn/tabs/overflow.tsx
new file mode 100644
index 0000000..3902ffa
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/overflow.tsx
@@ -0,0 +1,37 @@
+import {Tabs} from "@heroui/react";
+
+const items = [
+  {id: "overview", label: "概览"},
+  {id: "analytics", label: "分析"},
+  {id: "reports", label: "报告"},
+  {id: "performance", label: "性能"},
+  {id: "engagement", label: "互动"},
+  {id: "audience", label: "受众"},
+  {id: "acquisition", label: "获取"},
+  {id: "retention", label: "留存"},
+  {id: "settings", label: "设置"},
+];
+
+export function Overflow() {
+  return (
+    <div className="w-[400px]">
+      <Tabs>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="溢出选项">
+            {items.map((item) => (
+              <Tabs.Tab key={item.id} id={item.id}>
+                {item.label}
+                <Tabs.Indicator />
+              </Tabs.Tab>
+            ))}
+          </Tabs.List>
+        </Tabs.ListContainer>
+        {items.map((item) => (
+          <Tabs.Panel key={item.id} className="pt-4" id={item.id}>
+            <p>{item.label} 面板内容。</p>
+          </Tabs.Panel>
+        ))}
+      </Tabs>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/secondary-vertical.tsx b/apps/docs/src/demos/cn/tabs/secondary-vertical.tsx
new file mode 100644
index 0000000..ce41f45
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/secondary-vertical.tsx
@@ -0,0 +1,44 @@
+import {Tabs} from "@heroui/react";
+
+export function SecondaryVertical() {
+  return (
+    <Tabs className="w-full max-w-lg" orientation="vertical" variant="secondary">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="垂直标签页">
+          <Tabs.Tab id="account">
+            账户
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="security">
+            安全
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="notifications">
+            通知
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="billing">
+            账单
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="account">
+        <h3 className="mb-2 font-semibold">账户 Settings</h3>
+        <p className="text-sm text-muted">管理你的账户信息与偏好设置。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="security">
+        <h3 className="mb-2 font-semibold">安全 Settings</h3>
+        <p className="text-sm text-muted">配置双重认证与密码设置。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="notifications">
+        <h3 className="mb-2 font-semibold">通知偏好</h3>
+        <p className="text-sm text-muted">选择接收通知的方式与时间。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="billing">
+        <h3 className="mb-2 font-semibold">账单 Information</h3>
+        <p className="text-sm text-muted">查看并管理订阅与支付方式。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/secondary.tsx b/apps/docs/src/demos/cn/tabs/secondary.tsx
new file mode 100644
index 0000000..04bc716
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/secondary.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Secondary() {
+  return (
+    <Tabs className="w-full max-w-md" variant="secondary">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="选项">
+          <Tabs.Tab id="overview">
+            概览
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            分析
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            报告
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>查看项目概览与近期活动。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>跟踪指标并分析性能数据。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>生成并下载详细报告。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/vertical.tsx b/apps/docs/src/demos/cn/tabs/vertical.tsx
new file mode 100644
index 0000000..9fcebc9
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/vertical.tsx
@@ -0,0 +1,44 @@
+import {Tabs} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <Tabs className="w-full max-w-lg" orientation="vertical">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="垂直标签页">
+          <Tabs.Tab id="account">
+            账户
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="security">
+            安全
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="notifications">
+            通知
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="billing">
+            账单
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="account">
+        <h3 className="mb-2 font-semibold">账户 Settings</h3>
+        <p className="text-sm text-muted">管理你的账户信息与偏好设置。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="security">
+        <h3 className="mb-2 font-semibold">安全 Settings</h3>
+        <p className="text-sm text-muted">配置双重认证与密码设置。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="notifications">
+        <h3 className="mb-2 font-semibold">通知偏好</h3>
+        <p className="text-sm text-muted">选择接收通知的方式与时间。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="billing">
+        <h3 className="mb-2 font-semibold">账单 Information</h3>
+        <p className="text-sm text-muted">查看并管理订阅与支付方式。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tabs/with-separator.tsx b/apps/docs/src/demos/cn/tabs/with-separator.tsx
new file mode 100644
index 0000000..5d8da93
--- /dev/null
+++ b/apps/docs/src/demos/cn/tabs/with-separator.tsx
@@ -0,0 +1,35 @@
+import {Tabs} from "@heroui/react";
+
+export function WithSeparator() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="选项">
+          <Tabs.Tab id="overview">
+            概览
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            <Tabs.Separator />
+            分析
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            <Tabs.Separator />
+            报告
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>查看项目概览与近期活动。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>跟踪指标并分析性能数据。</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>生成并下载详细报告。</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/basic.tsx b/apps/docs/src/demos/cn/tag-group/basic.tsx
new file mode 100644
index 0000000..5f6dc2e
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/basic.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupBasic() {
+  return (
+    <TagGroup aria-label="标签" selectionMode="single">
+      <TagGroup.List>
+        <Tag id="default-news">
+          <SquareArticle />
+          资讯
+        </Tag>
+        <Tag id="default-travel">
+          <PlanetEarth />
+          旅行
+        </Tag>
+        <Tag id="default-gaming">
+          <Rocket />
+          游戏
+        </Tag>
+        <Tag id="default-shopping">
+          <ShoppingBag />
+          购物
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/controlled.tsx b/apps/docs/src/demos/cn/tag-group/controlled.tsx
new file mode 100644
index 0000000..c674656
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/controlled.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupControlled() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set(["news", "travel"]));
+
+  return (
+    <div className="flex flex-col gap-3">
+      <TagGroup
+        selectedKeys={selected}
+        selectionMode="multiple"
+        onSelectionChange={(keys) => setSelected(keys)}
+      >
+        <Label>分类（受控）</Label>
+        <TagGroup.List>
+          <Tag id="news">资讯</Tag>
+          <Tag id="travel">旅行</Tag>
+          <Tag id="gaming">游戏</Tag>
+          <Tag id="shopping">购物</Tag>
+        </TagGroup.List>
+        <Description>
+          已选：{Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "无"}
+        </Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/custom-render-function.tsx b/apps/docs/src/demos/cn/tag-group/custom-render-function.tsx
new file mode 100644
index 0000000..6a355a4
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/custom-render-function.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Tag, TagGroup} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TagGroup
+      aria-label="标签"
+      render={(props) => <div {...props} data-custom="foo" />}
+      selectionMode="single"
+    >
+      <TagGroup.List>
+        <Tag id="default-news">
+          <SquareArticle />
+          资讯
+        </Tag>
+        <Tag id="default-travel">
+          <PlanetEarth />
+          旅行
+        </Tag>
+        <Tag id="default-gaming">
+          <Rocket />
+          游戏
+        </Tag>
+        <Tag id="default-shopping">
+          <ShoppingBag />
+          购物
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/disabled.tsx b/apps/docs/src/demos/cn/tag-group/disabled.tsx
new file mode 100644
index 0000000..dac91d4
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/disabled.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupDisabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TagGroup selectionMode="single">
+        <Label>已禁用的标签</Label>
+        <TagGroup.List>
+          <Tag isDisabled>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag isDisabled>游戏</Tag>
+        </TagGroup.List>
+        <Description>部分标签已禁用</Description>
+      </TagGroup>
+
+      <TagGroup disabledKeys={["travel"]} selectionMode="single">
+        <Label>禁用的键</Label>
+        <TagGroup.List>
+          <Tag id="news">资讯</Tag>
+          <Tag id="travel">旅行</Tag>
+          <Tag id="gaming">游戏</Tag>
+        </TagGroup.List>
+        <Description>通过 disabledKeys 属性禁用的标签</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/index.ts b/apps/docs/src/demos/cn/tag-group/index.ts
new file mode 100644
index 0000000..4473c63
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/index.ts
@@ -0,0 +1,11 @@
+export {TagGroupBasic as Basic} from "./basic";
+export {TagGroupDisabled as Disabled} from "./disabled";
+export {TagGroupSelectionModes as SelectionModes} from "./selection-modes";
+export {TagGroupSizes as Sizes} from "./sizes";
+export {TagGroupVariants as Variants} from "./variants";
+export {TagGroupControlled as Controlled} from "./controlled";
+export {TagGroupWithErrorMessage as WithErrorMessage} from "./with-error-message";
+export {TagGroupWithPrefix as WithPrefix} from "./with-prefix";
+export {TagGroupWithRemoveButton as WithRemoveButton} from "./with-remove-button";
+export {TagGroupWithListData as WithListData} from "./with-list-data";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/tag-group/selection-modes.tsx b/apps/docs/src/demos/cn/tag-group/selection-modes.tsx
new file mode 100644
index 0000000..90fe6d9
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/selection-modes.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupSelectionModes() {
+  const [singleSelected, setSingleSelected] = useState<Iterable<Key>>(new Set(["news"]));
+  const [multipleSelected, setMultipleSelected] = useState<Iterable<Key>>(
+    new Set(["news", "travel"]),
+  );
+
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup
+        selectedKeys={singleSelected}
+        selectionMode="single"
+        onSelectionChange={(keys) => setSingleSelected(keys)}
+      >
+        <Label>单选</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+          <Tag>购物</Tag>
+        </TagGroup.List>
+        <Description>选择一个分类</Description>
+      </TagGroup>
+
+      <TagGroup
+        selectedKeys={multipleSelected}
+        selectionMode="multiple"
+        onSelectionChange={(keys) => setMultipleSelected(keys)}
+      >
+        <Label>多选</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+          <Tag>购物</Tag>
+        </TagGroup.List>
+        <Description>选择多个分类</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/sizes.tsx b/apps/docs/src/demos/cn/tag-group/sizes.tsx
new file mode 100644
index 0000000..1fe2856
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/sizes.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupSizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <TagGroup selectionMode="single" size="sm">
+        <Label>小</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="md">
+        <Label>中</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="lg">
+        <Label>大</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+        </TagGroup.List>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/variants.tsx b/apps/docs/src/demos/cn/tag-group/variants.tsx
new file mode 100644
index 0000000..35dad3c
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/variants.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupVariants() {
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup selectionMode="single" variant="default">
+        <Label>默认</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+        </TagGroup.List>
+      </TagGroup>
+
+      <TagGroup selectionMode="single" variant="surface">
+        <Label>表面</Label>
+        <TagGroup.List>
+          <Tag>资讯</Tag>
+          <Tag>旅行</Tag>
+          <Tag>游戏</Tag>
+        </TagGroup.List>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/with-error-message.tsx b/apps/docs/src/demos/cn/tag-group/with-error-message.tsx
new file mode 100644
index 0000000..96413ea
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/with-error-message.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function TagGroupWithErrorMessage() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>设施</Label>
+      <TagGroup.List>
+        <Tag id="laundry">洗衣</Tag>
+        <Tag id="fitness">健身中心</Tag>
+        <Tag id="parking">停车</Tag>
+        <Tag id="pool">游泳池</Tag>
+        <Tag id="breakfast">早餐</Tag>
+      </TagGroup.List>
+      <Description>
+        {isInvalid ? "请至少选择一个分类" : "已选：" + Array.from(selected).join(", ")}
+      </Description>
+      <ErrorMessage>{!!isInvalid && <>请至少选择一个分类</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/with-list-data.tsx b/apps/docs/src/demos/cn/tag-group/with-list-data.tsx
new file mode 100644
index 0000000..d5c9f6a
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/with-list-data.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Avatar, Description, EmptyState, Label, Tag, TagGroup, useListData} from "@heroui/react";
+
+export function TagGroupWithListData() {
+  type User = {
+    id: string;
+    name: string;
+    avatar: string;
+    fallback: string;
+  };
+
+  const list = useListData<User>({
+    getKey: (item) => item.id,
+    initialItems: [
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "F",
+        id: "fred",
+        name: "Fred",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "M",
+        id: "michael",
+        name: "Michael",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "J",
+        id: "jane",
+        name: "Jane",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "A",
+        id: "alice",
+        name: "Alice",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "B",
+        id: "bob",
+        name: "Bob",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+        fallback: "C",
+        id: "charlie",
+        name: "Charlie",
+      },
+    ],
+    initialSelectedKeys: new Set(["fred", "michael"]),
+  });
+
+  const onRemove = (keys: Set<Key>) => {
+    list.remove(...keys);
+  };
+
+  return (
+    <div className="w-sm">
+      <TagGroup
+        selectedKeys={list.selectedKeys}
+        selectionMode="multiple"
+        onRemove={onRemove}
+        onSelectionChange={(keys) => list.setSelectedKeys(keys)}
+      >
+        <Label>团队成员</Label>
+        <TagGroup.List
+          items={list.items}
+          renderEmptyState={() => <EmptyState className="p-1">暂无团队成员</EmptyState>}
+        >
+          {(user) => (
+            <Tag key={user.id} id={user.id} textValue={user.name}>
+              <Avatar className="size-4" size="sm">
+                <Avatar.Image src={user.avatar} />
+                <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+              </Avatar>
+              {user.name}
+            </Tag>
+          )}
+        </TagGroup.List>
+        <Description>为项目选择团队成员</Description>
+      </TagGroup>
+      {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
+        <div className="mt-4 flex flex-col gap-2">
+          <p className="text-sm font-medium text-muted">已选：</p>
+          <div className="flex flex-wrap gap-2">
+            {Array.from(list.selectedKeys).map((key) => {
+              const user = list.getItem(key);
+
+              if (!user) return null;
+
+              return (
+                <div
+                  key={`${user.id}-selected`}
+                  className="flex items-center gap-2 rounded-lg bg-surface-tertiary px-2 py-1"
+                >
+                  <Avatar className="size-4" size="sm">
+                    <Avatar.Image src={user.avatar} />
+                    <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+                  </Avatar>
+                  <span className="text-sm">{user.name}</span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/with-prefix.tsx b/apps/docs/src/demos/cn/tag-group/with-prefix.tsx
new file mode 100644
index 0000000..12397fe
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/with-prefix.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Avatar, Description, Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupWithPrefix() {
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup selectionMode="single">
+        <Label>带图标</Label>
+        <TagGroup.List>
+          <Tag>
+            <SquareArticle />
+            News
+          </Tag>
+          <Tag>
+            <PlanetEarth />
+            Travel
+          </Tag>
+          <Tag>
+            <Rocket />
+            Gaming
+          </Tag>
+          <Tag>
+            <ShoppingBag />
+            Shopping
+          </Tag>
+        </TagGroup.List>
+        <Description>带图标的标签</Description>
+      </TagGroup>
+
+      <TagGroup selectionMode="single">
+        <Label>带头像</Label>
+        <TagGroup.List>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+              <Avatar.Fallback>F</Avatar.Fallback>
+            </Avatar>
+            Fred
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+              <Avatar.Fallback>M</Avatar.Fallback>
+            </Avatar>
+            Michael
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+              <Avatar.Fallback>J</Avatar.Fallback>
+            </Avatar>
+            Jane
+          </Tag>
+        </TagGroup.List>
+        <Description>带头像的标签</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tag-group/with-remove-button.tsx b/apps/docs/src/demos/cn/tag-group/with-remove-button.tsx
new file mode 100644
index 0000000..ed056ac
--- /dev/null
+++ b/apps/docs/src/demos/cn/tag-group/with-remove-button.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {CircleXmarkFill} from "@gravity-ui/icons";
+import {Description, EmptyState, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupWithRemoveButton() {
+  type TagItem = {id: string; name: string};
+
+  const [tags, setTags] = useState<TagItem[]>([
+    {id: "news", name: "资讯"},
+    {id: "travel", name: "旅行"},
+    {id: "gaming", name: "游戏"},
+    {id: "shopping", name: "购物"},
+  ]);
+
+  const [frameworks, setFrameworks] = useState<TagItem[]>([
+    {id: "react", name: "React"},
+    {id: "vue", name: "Vue"},
+    {id: "angular", name: "Angular"},
+    {id: "svelte", name: "Svelte"},
+  ]);
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setTags(tags.filter((tag) => !keys.has(tag.id)));
+  };
+
+  const onRemoveFrameworks = (keys: Set<Key>) => {
+    setFrameworks(frameworks.filter((framework) => !keys.has(framework.id)));
+  };
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="w-sm">
+        <TagGroup selectionMode="single" onRemove={onRemoveTags}>
+          <Label>默认移除按钮</Label>
+          <TagGroup.List
+            items={tags}
+            renderEmptyState={() => <EmptyState className="p-1">未找到分类</EmptyState>}
+          >
+            {(tag) => (
+              <Tag key={tag.name} id={tag.id} textValue={tag.name}>
+                {tag.name}
+              </Tag>
+            )}
+          </TagGroup.List>
+          <Description>点击 × 移除标签</Description>
+        </TagGroup>
+      </div>
+
+      <div className="w-md">
+        <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}>
+          <Label>自定义移除按钮</Label>
+          <TagGroup.List
+            items={frameworks}
+            renderEmptyState={() => <EmptyState className="p-1">未找到框架</EmptyState>}
+          >
+            {(tag) => (
+              <Tag key={tag.id} id={tag.id} textValue={tag.name}>
+                {(renderProps) => (
+                  <>
+                    {tag.name}
+                    {!!renderProps.allowsRemoving && (
+                      <Tag.RemoveButton>
+                        <CircleXmarkFill />
+                      </Tag.RemoveButton>
+                    )}
+                  </>
+                )}
+              </Tag>
+            )}
+          </TagGroup.List>
+          <Description>带图标的自定义移除按钮</Description>
+        </TagGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/basic.tsx b/apps/docs/src/demos/cn/textarea/basic.tsx
new file mode 100644
index 0000000..e9c64e2
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/basic.tsx
@@ -0,0 +1,11 @@
+import {TextArea} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TextArea
+      aria-label="快速项目更新"
+      className="h-32 w-96"
+      placeholder="分享一条简短的项目更新…"
+    />
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/controlled.tsx b/apps/docs/src/demos/cn/textarea/controlled.tsx
new file mode 100644
index 0000000..ce5ef27
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/controlled.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Description, TextArea} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex w-96 flex-col gap-2">
+      <TextArea
+        aria-describedby="textarea-controlled-description"
+        aria-label="公告"
+        placeholder="撰写公告…"
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+      <Description id="textarea-controlled-description">字符数： {value.length} / 280</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/full-width.tsx b/apps/docs/src/demos/cn/textarea/full-width.tsx
new file mode 100644
index 0000000..5ba9f40
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/full-width.tsx
@@ -0,0 +1,9 @@
+import {TextArea} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <TextArea fullWidth placeholder="全宽文本域" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/index.ts b/apps/docs/src/demos/cn/textarea/index.ts
new file mode 100644
index 0000000..8d4f1f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Rows} from "./rows";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/textarea/on-surface.tsx b/apps/docs/src/demos/cn/textarea/on-surface.tsx
new file mode 100644
index 0000000..26a52bf
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/on-surface.tsx
@@ -0,0 +1,9 @@
+import {Surface, TextArea} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <TextArea className="w-full min-w-[280px]" placeholder="描述你的产品" variant="secondary" />
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/rows.tsx b/apps/docs/src/demos/cn/textarea/rows.tsx
new file mode 100644
index 0000000..db7ae39
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/rows.tsx
@@ -0,0 +1,22 @@
+import {Label, TextArea} from "@heroui/react";
+
+export function Rows() {
+  return (
+    <div className="flex w-96 flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="textarea-rows-3">简短反馈</Label>
+        <TextArea aria-label="简短反馈" id="textarea-rows-3" placeholder="本周亮点…" rows={3} />
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="textarea-rows-6">详细笔记</Label>
+        <TextArea
+          aria-label="详细笔记"
+          id="textarea-rows-6"
+          placeholder="写下完整的会议记录…"
+          rows={6}
+          style={{resize: "vertical"}}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textarea/variants.tsx b/apps/docs/src/demos/cn/textarea/variants.tsx
new file mode 100644
index 0000000..5fa3df6
--- /dev/null
+++ b/apps/docs/src/demos/cn/textarea/variants.tsx
@@ -0,0 +1,10 @@
+import {TextArea} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <TextArea fullWidth placeholder="主要文本域" variant="primary" />
+      <TextArea fullWidth placeholder="次要文本域" variant="secondary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/basic.tsx b/apps/docs/src/demos/cn/textfield/basic.tsx
new file mode 100644
index 0000000..cec2484
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/basic.tsx
@@ -0,0 +1,10 @@
+import {Input, Label, TextField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TextField className="w-full max-w-64" name="email" type="email">
+      <Label>邮箱</Label>
+      <Input placeholder="输入你的邮箱" />
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/controlled.tsx b/apps/docs/src/demos/cn/textfield/controlled.tsx
new file mode 100644
index 0000000..a2c27f5
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/controlled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Description, Input, Label, TextArea, TextField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [name, setName] = React.useState("");
+  const [bio, setBio] = React.useState("");
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField name="name" value={name} onChange={setName}>
+        <Label>显示名称</Label>
+        <Input placeholder="Jane" />
+        <Description>字符数： {name.length}</Description>
+      </TextField>
+      <TextField name="bio" value={bio} onChange={setBio}>
+        <Label>个人简介</Label>
+        <TextArea placeholder="介绍一下你自己…" />
+        <Description>字符数： {bio.length} / 200</Description>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/custom-render-function.tsx b/apps/docs/src/demos/cn/textfield/custom-render-function.tsx
new file mode 100644
index 0000000..8f2e02f
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/custom-render-function.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Input, Label, TextField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TextField
+      className="w-full max-w-64"
+      name="email"
+      render={(props) => <div {...props} data-custom="foo" />}
+      type="email"
+    >
+      <Label>邮箱</Label>
+      <Input placeholder="输入你的邮箱" />
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/disabled.tsx b/apps/docs/src/demos/cn/textfield/disabled.tsx
new file mode 100644
index 0000000..d4638ab
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/disabled.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <TextField isDisabled className="w-full max-w-64" name="accountId" value="USR-12345">
+      <Label>账户 ID</Label>
+      <Input placeholder="自动生成" />
+      <Description>此字段不可编辑</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/full-width.tsx b/apps/docs/src/demos/cn/textfield/full-width.tsx
new file mode 100644
index 0000000..c6d6ff8
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/full-width.tsx
@@ -0,0 +1,17 @@
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="name">
+        <Label>你的姓名</Label>
+        <Input placeholder="John" />
+      </TextField>
+      <TextField fullWidth isInvalid isRequired name="password" type="password">
+        <Label>密码</Label>
+        <Input />
+        <FieldError>密码长度必须超过 8 个字符</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/index.ts b/apps/docs/src/demos/cn/textfield/index.ts
new file mode 100644
index 0000000..22b02db
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {InputTypes} from "./input-types";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {TextAreaExample as TextArea} from "./textarea";
+export {Validation} from "./validation";
+export {WithDescription} from "./with-description";
+export {WithError} from "./with-error";
diff --git a/apps/docs/src/demos/cn/textfield/input-types.tsx b/apps/docs/src/demos/cn/textfield/input-types.tsx
new file mode 100644
index 0000000..8ba9ea5
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/input-types.tsx
@@ -0,0 +1,32 @@
+import {Input, Label, TextField} from "@heroui/react";
+
+export function InputTypes() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField name="password" type="password">
+        <Label>密码</Label>
+        <Input placeholder="••••••••" />
+      </TextField>
+
+      <TextField name="age" type="number">
+        <Label>年龄</Label>
+        <Input max="150" min="0" placeholder="21" />
+      </TextField>
+
+      <TextField name="email" type="email">
+        <Label>邮箱</Label>
+        <Input placeholder="user@example.com" />
+      </TextField>
+
+      <TextField name="website" type="url">
+        <Label>网站</Label>
+        <Input placeholder="https://example.com" />
+      </TextField>
+
+      <TextField name="phone" type="tel">
+        <Label>电话</Label>
+        <Input placeholder="+1 (555) 000-0000" />
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/on-surface.tsx b/apps/docs/src/demos/cn/textfield/on-surface.tsx
new file mode 100644
index 0000000..c7198c4
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/on-surface.tsx
@@ -0,0 +1,22 @@
+import {Description, Input, Label, Surface, TextArea, TextField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full min-w-[340px] flex-col gap-4 rounded-3xl p-6">
+      <TextField name="name" variant="secondary">
+        <Label>你的姓名</Label>
+        <Input className="w-full" placeholder="John" />
+        <Description>我们绝不会与他人分享此信息</Description>
+      </TextField>
+      <TextField name="email" type="email" variant="secondary">
+        <Label>邮箱</Label>
+        <Input className="w-full" placeholder="john@example.com" />
+      </TextField>
+      <TextField name="bio" variant="secondary">
+        <Label>个人简介</Label>
+        <TextArea className="w-full" placeholder="介绍一下你自己…" rows={4} />
+        <Description>至少 4 行</Description>
+      </TextField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/required.tsx b/apps/docs/src/demos/cn/textfield/required.tsx
new file mode 100644
index 0000000..a2d4b9b
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/required.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <TextField isRequired className="w-full max-w-64" name="fullName">
+      <Label>全名</Label>
+      <Input placeholder="John Doe" />
+      <Description>此字段为必填项</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/textarea.tsx b/apps/docs/src/demos/cn/textfield/textarea.tsx
new file mode 100644
index 0000000..cde0668
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/textarea.tsx
@@ -0,0 +1,11 @@
+import {Description, Label, TextArea, TextField} from "@heroui/react";
+
+export function TextAreaExample() {
+  return (
+    <TextField className="w-full max-w-64" name="message">
+      <Label>消息</Label>
+      <TextArea placeholder="在此输入你的消息…" rows={4} />
+      <Description>最多 500 个字符</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/validation.tsx b/apps/docs/src/demos/cn/textfield/validation.tsx
new file mode 100644
index 0000000..2f076cd
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/validation.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Description, FieldError, Input, Label, TextArea, TextField} from "@heroui/react";
+import React from "react";
+
+export function Validation() {
+  const [username, setUsername] = React.useState("");
+  const [bio, setBio] = React.useState("");
+
+  const isUsernameInvalid = username.length > 0 && username.length < 3;
+  const isBioInvalid = bio.length > 0 && bio.length < 20;
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField
+        isRequired
+        isInvalid={isUsernameInvalid}
+        name="username"
+        value={username}
+        onChange={setUsername}
+      >
+        <Label>用户名</Label>
+        <Input placeholder="jane_doe" />
+        {isUsernameInvalid ? (
+          <FieldError>用户名至少需要 3 个字符。</FieldError>
+        ) : (
+          <Description>为你的资料选择一个唯一的用户名。</Description>
+        )}
+      </TextField>
+
+      <TextField isRequired isInvalid={isBioInvalid} name="bio" value={bio} onChange={setBio}>
+        <Label>个人简介</Label>
+        <TextArea placeholder="介绍一下你自己…" />
+        {isBioInvalid ? (
+          <FieldError>个人简介至少需要 20 个字符。</FieldError>
+        ) : (
+          <Description>至少 20 个字符 ({bio.length}/20).</Description>
+        )}
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/with-description.tsx b/apps/docs/src/demos/cn/textfield/with-description.tsx
new file mode 100644
index 0000000..03c05fd
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/with-description.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <TextField className="w-full max-w-64" name="username">
+      <Label>用户名</Label>
+      <Input placeholder="输入用户名" />
+      <Description>为你的账户选择一个唯一的用户名</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/textfield/with-error.tsx b/apps/docs/src/demos/cn/textfield/with-error.tsx
new file mode 100644
index 0000000..34543e1
--- /dev/null
+++ b/apps/docs/src/demos/cn/textfield/with-error.tsx
@@ -0,0 +1,11 @@
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+
+export function WithError() {
+  return (
+    <TextField isInvalid className="w-full max-w-64" name="email" type="email">
+      <Label>邮箱</Label>
+      <Input placeholder="user@example.com" />
+      <FieldError>请输入有效的邮箱地址</FieldError>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/basic.tsx b/apps/docs/src/demos/cn/time-field/basic.tsx
new file mode 100644
index 0000000..831ca2e
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Label, TimeField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>时间</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/controlled.tsx b/apps/docs/src/demos/cn/time-field/controlled.tsx
new file mode 100644
index 0000000..b3861f6
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/controlled.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+
+import {Button, Description, Label, TimeField} from "@heroui/react";
+import {Time, getLocalTimeZone, now} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<TimeValue | null>(null);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField className="w-[256px]" name="time" value={value} onChange={setValue}>
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>当前值：{value ? value.toString() : "（空）"}</Description>
+      </TimeField>
+      <div className="flex gap-2">
+        <Button
+          variant="tertiary"
+          onPress={() => {
+            const currentTime = now(getLocalTimeZone());
+
+            setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second));
+          }}
+        >
+          设为当前时间
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          清空
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/custom-render-function.tsx b/apps/docs/src/demos/cn/time-field/custom-render-function.tsx
new file mode 100644
index 0000000..8b84757
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Label, TimeField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TimeField
+      className="w-[256px]"
+      name="time"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>时间</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/disabled.tsx b/apps/docs/src/demos/cn/time-field/disabled.tsx
new file mode 100644
index 0000000..3efe10b
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/disabled.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+import {Time, getLocalTimeZone, now} from "@internationalized/date";
+
+export function Disabled() {
+  const currentTime = now(getLocalTimeZone());
+  const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isDisabled className="w-[256px]" name="time" value={timeValue}>
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>此时间字段已禁用</Description>
+      </TimeField>
+      <TimeField isDisabled className="w-[256px]" name="time-empty">
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>此时间字段已禁用</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/form-example.tsx b/apps/docs/src/demos/cn/time-field/form-example.tsx
new file mode 100644
index 0000000..1a596e9
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/form-example.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import type {Time} from "@internationalized/date";
+
+import {Clock} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Label, TimeField} from "@heroui/react";
+import {parseTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<Time | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const minTime = parseTime("09:00");
+  const maxTime = parseTime("17:00");
+  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Time submitted:", {time: value});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <TimeField
+        isRequired
+        className="w-full"
+        isInvalid={isInvalid}
+        maxValue={maxTime}
+        minValue={minTime}
+        name="time"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>预约时间</Label>
+        <TimeField.Group>
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        {isInvalid ? (
+          <FieldError>时间须在上午 9:00 至下午 5:00 之间</FieldError>
+        ) : (
+          <Description>输入上午 9:00 至下午 5:00 之间的时间</Description>
+        )}
+      </TimeField>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "提交中…" : "提交"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/full-width.tsx b/apps/docs/src/demos/cn/time-field/full-width.tsx
new file mode 100644
index 0000000..dc156d9
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/full-width.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {ChevronDown, Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TimeField fullWidth name="time">
+        <Label>时间</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField fullWidth name="time-icons">
+        <Label>时间</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+          <TimeField.Suffix>
+            <ChevronDown className="size-4 text-muted" />
+          </TimeField.Suffix>
+        </TimeField.Group>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/index.ts b/apps/docs/src/demos/cn/time-field/index.ts
new file mode 100644
index 0000000..0898841
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/index.ts
@@ -0,0 +1,14 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {WithDescription} from "./with-description";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/cn/time-field/invalid.tsx b/apps/docs/src/demos/cn/time-field/invalid.tsx
new file mode 100644
index 0000000..17d5324
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/invalid.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {FieldError, Label, TimeField} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isInvalid isRequired className="w-[256px]" name="time">
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>请输入有效时间</FieldError>
+      </TimeField>
+      <TimeField isInvalid className="w-[256px]" name="invalid-time">
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>时间须在工作时间内</FieldError>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/on-surface.tsx b/apps/docs/src/demos/cn/time-field/on-surface.tsx
new file mode 100644
index 0000000..a9b70e0
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/on-surface.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Description, Label, Surface, TimeField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <TimeField className="w-full" name="time">
+        <Label>时间</Label>
+        <TimeField.Group variant="secondary">
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>输入时间</Description>
+      </TimeField>
+      <TimeField className="w-full" name="time-2">
+        <Label>预约时间</Label>
+        <TimeField.Group variant="secondary">
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>输入预约时间</Description>
+      </TimeField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/required.tsx b/apps/docs/src/demos/cn/time-field/required.tsx
new file mode 100644
index 0000000..e531d79
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/required.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isRequired className="w-[256px]" name="time">
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField isRequired className="w-[256px]" name="appointment-time">
+        <Label>预约时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>必填项</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/with-description.tsx b/apps/docs/src/demos/cn/time-field/with-description.tsx
new file mode 100644
index 0000000..2aa3e4c
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/with-description.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField className="w-[256px]" name="time">
+        <Label>开始时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>输入开始时间</Description>
+      </TimeField>
+      <TimeField className="w-[256px]" name="end-time">
+        <Label>结束时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>输入结束时间</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/with-prefix-and-suffix.tsx b/apps/docs/src/demos/cn/time-field/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..302ff69
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/with-prefix-and-suffix.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {ChevronDown, Clock} from "@gravity-ui/icons";
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>时间</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <ChevronDown className="size-4 text-muted" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+      <Description>输入时间</Description>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/with-prefix-icon.tsx b/apps/docs/src/demos/cn/time-field/with-prefix-icon.tsx
new file mode 100644
index 0000000..915543a
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/with-prefix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>时间</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/with-suffix-icon.tsx b/apps/docs/src/demos/cn/time-field/with-suffix-icon.tsx
new file mode 100644
index 0000000..9877d0f
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/with-suffix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>时间</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/cn/time-field/with-validation.tsx b/apps/docs/src/demos/cn/time-field/with-validation.tsx
new file mode 100644
index 0000000..d9c2aa4
--- /dev/null
+++ b/apps/docs/src/demos/cn/time-field/with-validation.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import type {Time} from "@internationalized/date";
+
+import {Description, FieldError, Label, TimeField} from "@heroui/react";
+import {parseTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<Time | null>(null);
+  const minTime = parseTime("09:00");
+  const maxTime = parseTime("17:00");
+  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField
+        isRequired
+        className="w-[256px]"
+        isInvalid={isInvalid}
+        maxValue={maxTime}
+        minValue={minTime}
+        name="time"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>时间</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        {isInvalid ? (
+          <FieldError>时间须在上午 9:00 至下午 5:00 之间</FieldError>
+        ) : (
+          <Description>输入上午 9:00 至下午 5:00 之间的时间</Description>
+        )}
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/callbacks.tsx b/apps/docs/src/demos/cn/toast/callbacks.tsx
new file mode 100644
index 0000000..c7b9dfc
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/callbacks.tsx
@@ -0,0 +1,128 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+import React from "react";
+
+export function Callbacks() {
+  const [closedHistory, setClosedHistory] = React.useState<Array<{message: string; time: string}>>(
+    [],
+  );
+
+  const addToHistory = (message: string) => {
+    const time = new Date().toLocaleTimeString();
+
+    setClosedHistory((prev) => [{message, time}, ...prev].slice(0, 5));
+  };
+
+  return (
+    <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-6">
+      {/* Toast Buttons */}
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("文件已保存", {
+              onClose: () => {
+                addToHistory("文件已保存（3 秒后关闭）");
+              },
+              timeout: 3000,
+            })
+          }
+        >
+          自定义超时（3 秒）
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("更改已保存", {
+              onClose: () => {
+                addToHistory("更改已保存（10 秒后关闭）");
+              },
+              timeout: 10000,
+            })
+          }
+        >
+          自定义超时（10 秒）
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.success("活动已创建", {
+              onClose: () => {
+                addToHistory("活动已创建（默认超时后关闭）");
+              },
+            })
+          }
+        >
+          使用 onClose 回调
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("重要通知", {
+              description: "此 Toast 将保持显示直至关闭",
+              onClose: () => {
+                addToHistory("重要通知（手动关闭）");
+              },
+              timeout: 0,
+            })
+          }
+        >
+          持久显示 Toast
+        </Button>
+      </div>
+
+      {/* 关闭历史 Panel */}
+      <div className="w-full space-y-2">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium">关闭历史</h3>
+          {closedHistory.length > 0 && (
+            <Button
+              className="h-6 text-xs"
+              size="sm"
+              variant="tertiary"
+              onPress={() => setClosedHistory([])}
+            >
+              清空
+            </Button>
+          )}
+        </div>
+        <div className="min-h-[120px] space-y-2 rounded-lg border border-border bg-surface p-4">
+          {closedHistory.length === 0 ? (
+            <p className="text-sm text-muted">尚无已关闭的 Toast。请尝试关闭上方的 Toast！</p>
+          ) : (
+            closedHistory.map((item, index) => (
+              <div
+                key={`${item.time}-${index}`}
+                className="flex animate-in items-start justify-between gap-3 rounded-md border border-border bg-default px-3 py-2 text-sm duration-200 fade-in slide-in-from-top-2"
+                style={{
+                  animationDelay: `${index * 50}ms`,
+                }}
+              >
+                <div className="flex-1">
+                  <span className="font-medium">{item.message}</span>
+                  <span className="ml-2 text-xs text-muted">({item.time})</span>
+                </div>
+                <div className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-success/10 text-success">
+                  <svg
+                    className="size-3"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" />
+                  </svg>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/custom-indicator.tsx b/apps/docs/src/demos/cn/toast/custom-indicator.tsx
new file mode 100644
index 0000000..0d63ded
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/custom-indicator.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Star} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() =>
+          toast("自定义图标指示器", {
+            indicator: <Star />,
+          })
+        }
+      >
+        自定义指示器
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/custom-queue.tsx b/apps/docs/src/demos/cn/toast/custom-queue.tsx
new file mode 100644
index 0000000..a1d118f
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/custom-queue.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Button, Toast, ToastQueue} from "@heroui/react";
+
+export function CustomQueue() {
+  const notificationQueue = new ToastQueue({maxVisibleToasts: 2});
+  const errorQueue = new ToastQueue({maxVisibleToasts: 3});
+  const successQueue = new ToastQueue({maxVisibleToasts: 1});
+
+  return (
+    <div className="flex h-full max-w-4xl items-center justify-center gap-4">
+      {/* Notification Queue */}
+      <Toast.Provider placement="bottom" queue={notificationQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            notificationQueue.add({
+              description: "您有一条新消息",
+              title: "新通知",
+              variant: "default",
+            });
+          }}
+        >
+          添加通知（最多 2 条）
+        </Button>
+      </div>
+
+      {/* Error Queue */}
+      <Toast.Provider placement="bottom start" queue={errorQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() => {
+            errorQueue.add({
+              description: "保存更改失败",
+              title: "发生错误",
+              variant: "danger",
+            });
+          }}
+        >
+          添加错误（最多 3 条）
+        </Button>
+      </div>
+
+      {/* Success Queue */}
+      <Toast.Provider placement="bottom end" queue={successQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          className="text-success"
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            successQueue.add({
+              description: `操作 ${Date.now()}`,
+              title: "成功！",
+              variant: "success",
+            });
+          }}
+        >
+          添加成功（最多 1 条）
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/custom-toast.tsx b/apps/docs/src/demos/cn/toast/custom-toast.tsx
new file mode 100644
index 0000000..a21e199
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/custom-toast.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import type {ToastContentValue} from "@heroui/react";
+
+import {
+  Button,
+  Toast,
+  ToastContent,
+  ToastDescription,
+  ToastIndicator,
+  ToastQueue,
+  ToastTitle,
+} from "@heroui/react";
+
+export function CustomToast() {
+  const customQueue = new ToastQueue();
+
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" queue={customQueue}>
+        {({toast: toastItem}) => {
+          const content = toastItem.content as ToastContentValue;
+
+          return (
+            <Toast
+              className="rounded-xl border border-border"
+              toast={toastItem}
+              variant={content.variant}
+            >
+              <ToastContent>
+                <div className="flex items-center gap-2">
+                  <ToastIndicator className="text-accent" variant={content.variant} />
+                  <div className="flex flex-col pr-6">
+                    {content.title ? (
+                      <ToastTitle className="text-accent">{content.title}</ToastTitle>
+                    ) : null}
+                    {content.description ? (
+                      <ToastDescription>{content.description}</ToastDescription>
+                    ) : null}
+                  </div>
+                </div>
+              </ToastContent>
+              <Toast.CloseButton className="absolute top-1/2 right-2 -translate-y-1/2 border-none bg-transparent opacity-100 [&>svg]:size-4" />
+            </Toast>
+          );
+        }}
+      </Toast.Provider>
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() => {
+          customQueue.add({
+            description: "使用自定义渲染函数",
+            title: "自定义布局 Toast",
+            variant: "default",
+          });
+        }}
+      >
+        自定义 Toast
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/default.tsx b/apps/docs/src/demos/cn/toast/default.tsx
new file mode 100644
index 0000000..7f55602
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/default.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Persons} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+export function Default() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() => {
+          toast("您已被邀请加入团队", {
+            actionProps: {
+              children: "忽略",
+              onPress: () => toast.clear(),
+              variant: "tertiary",
+            },
+            description: "Bob 邀请您加入 HeroUI 团队",
+            indicator: <Persons />,
+            variant: "default",
+          });
+        }}
+      >
+        显示 Toast
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/index.ts b/apps/docs/src/demos/cn/toast/index.ts
new file mode 100644
index 0000000..07f9118
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/index.ts
@@ -0,0 +1,9 @@
+export {Callbacks} from "./callbacks";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomQueue} from "./custom-queue";
+export {CustomToast} from "./custom-toast";
+export {Default} from "./default";
+export {Placements} from "./placements";
+export {PromiseDemo as Promise} from "./promise";
+export {Simple} from "./simple";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/toast/placements.tsx b/apps/docs/src/demos/cn/toast/placements.tsx
new file mode 100644
index 0000000..e37973c
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/placements.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {ToastVariants} from "@heroui/react";
+
+import {Button, Toast, ToastQueue} from "@heroui/react";
+
+type Placement = NonNullable<ToastVariants["placement"]>;
+
+const placements = ["top start", "top", "top end", "bottom start", "bottom", "bottom end"] as const;
+
+// Create a separate queue for each placement
+const placementQueues = Object.fromEntries(
+  placements.map((p) => [p, new ToastQueue({maxVisibleToasts: 3})]),
+) as Record<Placement, ToastQueue>;
+
+export function Placements() {
+  const showToast = (placement: Placement) => {
+    placementQueues[placement].add({
+      description: "活动已创建",
+      title: "活动已创建",
+      variant: "default",
+    });
+  };
+
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-6">
+      {/* Render a ToastProvider for each placement */}
+      {placements.map((p) => (
+        <Toast.Provider key={p} placement={p} queue={placementQueues[p]} />
+      ))}
+      <div className="flex max-w-xs flex-wrap justify-center gap-2">
+        {placements.map((p) => (
+          <Button key={p} size="sm" variant="secondary" onPress={() => showToast(p)}>
+            {p}
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/promise.tsx b/apps/docs/src/demos/cn/toast/promise.tsx
new file mode 100644
index 0000000..c13da86
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/promise.tsx
@@ -0,0 +1,169 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+
+const uploadFile = (): Promise<{filename: string; size: number}> => {
+  return new Promise<{filename: string; size: number}>((resolve) => {
+    setTimeout(() => resolve({filename: "document.pdf", size: 1024}), 2000);
+  });
+};
+
+const createEvent = (): Promise<never> => {
+  return new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error("网络错误，请重试。")), 2000);
+  });
+};
+
+const saveData = (): Promise<{count: number}> => {
+  return new Promise<{count: number}>((resolve, reject) => {
+    setTimeout(() => {
+      if (Math.random() > 0.5) {
+        resolve({count: 42});
+      } else {
+        reject(new Error("保存数据失败"));
+      }
+    }, 2000);
+  });
+};
+
+const fetchUser = (): Promise<{name: string; email: string}> => {
+  return new Promise<{name: string; email: string}>((resolve) => {
+    setTimeout(() => resolve({email: "john@example.com", name: "John Doe"}), 2000);
+  });
+};
+
+export function PromiseDemo() {
+  return (
+    <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-8">
+      {/* Promise API Section */}
+      <div className="w-full space-y-3">
+        <div className="text-center">
+          <h3 className="text-sm font-medium">使用 toast.promise()</h3>
+          <p className="text-xs text-muted">自动处理加载、成功和错误状态</p>
+        </div>
+        <div className="flex w-full flex-wrap items-center justify-center gap-4">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(uploadFile(), {
+                error: "上传文件失败",
+                loading: "正在上传文件…",
+                success: (data) => `文件 ${data.filename} 已上传（${data.size}KB）`,
+              });
+            }}
+          >
+            上传文件
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(createEvent(), {
+                error: (err) => err.message,
+                loading: "正在创建活动…",
+                success: "活动已创建",
+              });
+            }}
+          >
+            创建活动（错误）
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(saveData(), {
+                error: (err) => err.message,
+                loading: "正在保存更改…",
+                success: (data) => `已保存 ${data.count} 项`,
+              });
+            }}
+          >
+            保存数据（随机）
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(fetchUser(), {
+                error: "获取用户失败",
+                loading: "正在加载用户…",
+                success: (data) => `欢迎回来，${data.name}！`,
+              });
+            }}
+          >
+            获取用户
+          </Button>
+        </div>
+      </div>
+
+      {/* Manual Loading Section */}
+      <div className="w-full space-y-3">
+        <div className="text-center">
+          <h3 className="text-sm font-medium">手动加载状态</h3>
+          <p className="text-xs text-muted">使用 isLoading 属性手动控制加载状态</p>
+        </div>
+        <div className="flex w-full flex-wrap items-center justify-center gap-4">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("正在上传文件…", {
+                description: "请稍候，正在上传您的文件",
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.success("文件已上传", {
+                  description: "您的文件已成功上传",
+                });
+              }, 3000);
+            }}
+          >
+            上传（含加载）
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("正在处理付款…", {
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.success("付款已处理", {
+                  description: "您的付款已成功处理",
+                });
+              }, 2500);
+            }}
+          >
+            付款处理
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("正在保存更改…", {
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.danger("保存失败", {
+                  description: "请重试",
+                });
+              }, 2000);
+            }}
+          >
+            加载后显示错误
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/simple.tsx b/apps/docs/src/demos/cn/toast/simple.tsx
new file mode 100644
index 0000000..772231a
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/simple.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+
+export function Simple() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button size="sm" variant="secondary" onPress={() => toast("简单消息")}>
+          默认
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.success("操作已完成")}>
+          成功
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.info("有新更新可用")}>
+          信息
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.warning("请检查您的设置")}>
+          警告
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.danger("出了点问题")}>
+          错误
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toast/variants.tsx b/apps/docs/src/demos/cn/toast/variants.tsx
new file mode 100644
index 0000000..2cb338a
--- /dev/null
+++ b/apps/docs/src/demos/cn/toast/variants.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import {HardDrive, Persons} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+const noop = () => {};
+
+export function Variants() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="tertiary"
+          onPress={() => {
+            toast("您已被邀请加入团队", {
+              actionProps: {
+                children: "忽略",
+                onPress: () => toast.clear(),
+                variant: "tertiary",
+              },
+              description: "Bob 邀请您加入 HeroUI 团队",
+              indicator: <Persons />,
+              variant: "default",
+            });
+          }}
+        >
+          默认 Toast
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.info("您还剩 2 个积分", {
+              actionProps: {children: "升级", onPress: noop},
+              description: "升级付费方案以获取更多积分",
+            })
+          }
+        >
+          强调 Toast
+        </Button>
+        <Button
+          className="text-success"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.success("您已升级方案", {
+              actionProps: {
+                children: "账单",
+                className: "bg-success text-success-foreground",
+                onPress: noop,
+              },
+              description: "您可以继续使用 HeroUI Chat",
+            })
+          }
+        >
+          成功 Toast
+        </Button>
+        <Button
+          className="text-warning"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.warning("您的积分已用完", {
+              actionProps: {
+                children: "升级",
+                className: "bg-warning text-warning-foreground",
+                onPress: noop,
+              },
+              description: "升级付费方案以继续使用",
+            })
+          }
+        >
+          警告 Toast
+        </Button>
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() =>
+            toast.danger("存储空间已满", {
+              actionProps: {children: "删除", onPress: noop, variant: "danger"},
+              description: "删除文件以释放空间。此处增加更多文字以演示较长内容的显示效果",
+              indicator: <HardDrive />,
+            })
+          }
+        >
+          危险 Toast
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/attached.tsx b/apps/docs/src/demos/cn/toggle-button-group/attached.tsx
new file mode 100644
index 0000000..fbffea6
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/attached.tsx
@@ -0,0 +1,46 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Attached() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">附着（默认）</span>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">分离</span>
+        <ToggleButtonGroup isDetached selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/basic.tsx b/apps/docs/src/demos/cn/toggle-button-group/basic.tsx
new file mode 100644
index 0000000..dd10a5c
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/basic.tsx
@@ -0,0 +1,24 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="粗体" id="bold">
+        <Bold />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="斜体" id="italic">
+        <ToggleButtonGroup.Separator />
+        <Italic />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="下划线" id="underline">
+        <ToggleButtonGroup.Separator />
+        <Underline />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+        <ToggleButtonGroup.Separator />
+        <Strikethrough />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/controlled.tsx b/apps/docs/src/demos/cn/toggle-button-group/controlled.tsx
new file mode 100644
index 0000000..9076ad4
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/controlled.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selectedKeys, setSelectedKeys] = useState(new Set<Key>(["bold"]));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ToggleButtonGroup
+        selectedKeys={selectedKeys}
+        selectionMode="multiple"
+        onSelectionChange={setSelectedKeys}
+      >
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+          <ToggleButtonGroup.Separator />
+          <Strikethrough />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <p className="text-sm text-muted">
+        已选：
+        <span className="font-medium">
+          {selectedKeys.size > 0 ? [...selectedKeys].join(", ") : "无"}
+        </span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/disabled.tsx b/apps/docs/src/demos/cn/toggle-button-group/disabled.tsx
new file mode 100644
index 0000000..1d05660
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/disabled.tsx
@@ -0,0 +1,41 @@
+import {Bold, Italic, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">全部按钮已禁用</span>
+        <ToggleButtonGroup isDisabled selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">单个按钮已禁用</span>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isDisabled isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/full-width.tsx b/apps/docs/src/demos/cn/toggle-button-group/full-width.tsx
new file mode 100644
index 0000000..309bc9a
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/full-width.tsx
@@ -0,0 +1,50 @@
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-full max-w-md space-y-3">
+      <ToggleButtonGroup fullWidth selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+          <ToggleButtonGroup.Separator />
+          <Strikethrough />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <ToggleButtonGroup fullWidth selectionMode="single">
+        <ToggleButton id="left">
+          <TextAlignLeft />
+          左对齐
+        </ToggleButton>
+        <ToggleButton id="center">
+          <ToggleButtonGroup.Separator />
+          <TextAlignCenter />
+          居中
+        </ToggleButton>
+        <ToggleButton id="right">
+          <ToggleButtonGroup.Separator />
+          <TextAlignRight />
+          右对齐
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/index.ts b/apps/docs/src/demos/cn/toggle-button-group/index.ts
new file mode 100644
index 0000000..fb204e2
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/index.ts
@@ -0,0 +1,9 @@
+export {Attached} from "./attached";
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Orientation} from "./orientation";
+export {SelectionMode} from "./selection-mode";
+export {Sizes} from "./sizes";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/cn/toggle-button-group/orientation.tsx b/apps/docs/src/demos/cn/toggle-button-group/orientation.tsx
new file mode 100644
index 0000000..745ff95
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/orientation.tsx
@@ -0,0 +1,41 @@
+import {Bold, Italic, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Orientation() {
+  return (
+    <div className="flex items-start gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">水平</span>
+        <ToggleButtonGroup orientation="horizontal" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">垂直</span>
+        <ToggleButtonGroup orientation="vertical" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/selection-mode.tsx b/apps/docs/src/demos/cn/toggle-button-group/selection-mode.tsx
new file mode 100644
index 0000000..ac7617f
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/selection-mode.tsx
@@ -0,0 +1,56 @@
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function SelectionMode() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">单选</span>
+        <ToggleButtonGroup defaultSelectedKeys={["center"]} selectionMode="single">
+          <ToggleButton id="left">
+            <TextAlignLeft />
+            左对齐
+          </ToggleButton>
+          <ToggleButton id="center">
+            <ToggleButtonGroup.Separator />
+            <TextAlignCenter />
+            居中
+          </ToggleButton>
+          <ToggleButton id="right">
+            <ToggleButtonGroup.Separator />
+            <TextAlignRight />
+            右对齐
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">多选</span>
+        <ToggleButtonGroup defaultSelectedKeys={["bold", "underline"]} selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/sizes.tsx b/apps/docs/src/demos/cn/toggle-button-group/sizes.tsx
new file mode 100644
index 0000000..b73e34e
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/sizes.tsx
@@ -0,0 +1,69 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">小</span>
+        <ToggleButtonGroup selectionMode="multiple" size="sm">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">中（默认）</span>
+        <ToggleButtonGroup selectionMode="multiple" size="md">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">大</span>
+        <ToggleButtonGroup selectionMode="multiple" size="lg">
+          <ToggleButton isIconOnly aria-label="粗体" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="斜体" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="下划线" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button-group/without-separator.tsx b/apps/docs/src/demos/cn/toggle-button-group/without-separator.tsx
new file mode 100644
index 0000000..2d53661
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button-group/without-separator.tsx
@@ -0,0 +1,21 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function WithoutSeparator() {
+  return (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="粗体" id="bold">
+        <Bold />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="斜体" id="italic">
+        <Italic />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="下划线" id="underline">
+        <Underline />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="删除线" id="strikethrough">
+        <Strikethrough />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/basic.tsx b/apps/docs/src/demos/cn/toggle-button/basic.tsx
new file mode 100644
index 0000000..c7b8196
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/basic.tsx
@@ -0,0 +1,11 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ToggleButton>
+      <Heart />
+      点赞
+    </ToggleButton>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/controlled.tsx b/apps/docs/src/demos/cn/toggle-button/controlled.tsx
new file mode 100644
index 0000000..2bfb01c
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/controlled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Heart, HeartFill} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ToggleButton isSelected={isSelected} onChange={setIsSelected}>
+        {({isSelected: selected}) => (
+          <>
+            {selected ? <HeartFill /> : <Heart />}
+            {selected ? "已点赞" : "点赞"}
+          </>
+        )}
+      </ToggleButton>
+      <p className="text-sm text-muted">
+        状态：<span className="font-medium">{isSelected ? "已选" : "未选"}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/disabled.tsx b/apps/docs/src/demos/cn/toggle-button/disabled.tsx
new file mode 100644
index 0000000..0ec78b1
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/disabled.tsx
@@ -0,0 +1,17 @@
+import {Heart, HeartFill} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton isDisabled>
+        <Heart />
+        点赞
+      </ToggleButton>
+      <ToggleButton defaultSelected isDisabled>
+        <HeartFill />
+        点赞
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/icon-only.tsx b/apps/docs/src/demos/cn/toggle-button/icon-only.tsx
new file mode 100644
index 0000000..476ad90
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/icon-only.tsx
@@ -0,0 +1,15 @@
+import {Bookmark, Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function IconOnly() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton isIconOnly aria-label="点赞">
+        <Heart />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="收藏" variant="ghost">
+        <Bookmark />
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/index.ts b/apps/docs/src/demos/cn/toggle-button/index.ts
new file mode 100644
index 0000000..bde862d
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {IconOnly} from "./icon-only";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/cn/toggle-button/sizes.tsx b/apps/docs/src/demos/cn/toggle-button/sizes.tsx
new file mode 100644
index 0000000..885dc92
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/sizes.tsx
@@ -0,0 +1,31 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center gap-3">
+        <ToggleButton size="sm">
+          <Heart />小
+        </ToggleButton>
+        <ToggleButton size="md">
+          <Heart />中
+        </ToggleButton>
+        <ToggleButton size="lg">
+          <Heart />大
+        </ToggleButton>
+      </div>
+      <div className="flex items-center gap-3">
+        <ToggleButton isIconOnly aria-label="点赞" size="sm">
+          <Heart />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="点赞" size="md">
+          <Heart />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="点赞" size="lg">
+          <Heart />
+        </ToggleButton>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toggle-button/variants.tsx b/apps/docs/src/demos/cn/toggle-button/variants.tsx
new file mode 100644
index 0000000..8971ee4
--- /dev/null
+++ b/apps/docs/src/demos/cn/toggle-button/variants.tsx
@@ -0,0 +1,17 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton>
+        <Heart />
+        默认
+      </ToggleButton>
+      <ToggleButton variant="ghost">
+        <Heart />
+        幽灵
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toolbar/basic.tsx b/apps/docs/src/demos/cn/toolbar/basic.tsx
new file mode 100644
index 0000000..9f729d4
--- /dev/null
+++ b/apps/docs/src/demos/cn/toolbar/basic.tsx
@@ -0,0 +1,39 @@
+import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Toolbar aria-label="文本格式">
+      <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="复制">
+          <Copy />
+        </Button>
+        <Button isIconOnly aria-label="剪切">
+          <ButtonGroup.Separator />
+          <Scissors />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toolbar/custom-styles.tsx b/apps/docs/src/demos/cn/toolbar/custom-styles.tsx
new file mode 100644
index 0000000..8b64fcb
--- /dev/null
+++ b/apps/docs/src/demos/cn/toolbar/custom-styles.tsx
@@ -0,0 +1,39 @@
+import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Attached() {
+  return (
+    <Toolbar isAttached aria-label="文本格式">
+      <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="复制">
+          <Copy />
+        </Button>
+        <Button isIconOnly aria-label="剪切">
+          <ButtonGroup.Separator />
+          <Scissors />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toolbar/index.ts b/apps/docs/src/demos/cn/toolbar/index.ts
new file mode 100644
index 0000000..6bc9e8c
--- /dev/null
+++ b/apps/docs/src/demos/cn/toolbar/index.ts
@@ -0,0 +1,4 @@
+export {Basic} from "./basic";
+export {Vertical} from "./vertical";
+export {WithButtonGroup} from "./with-button-group";
+export {Attached} from "./custom-styles";
diff --git a/apps/docs/src/demos/cn/toolbar/vertical.tsx b/apps/docs/src/demos/cn/toolbar/vertical.tsx
new file mode 100644
index 0000000..696ccea
--- /dev/null
+++ b/apps/docs/src/demos/cn/toolbar/vertical.tsx
@@ -0,0 +1,39 @@
+import {ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <Toolbar aria-label="工具" orientation="vertical">
+      <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="撤销">
+          <ArrowUturnCcwLeft />
+        </Button>
+        <Button isIconOnly aria-label="重做">
+          <ButtonGroup.Separator />
+          <ArrowUturnCwRight />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/toolbar/with-button-group.tsx b/apps/docs/src/demos/cn/toolbar/with-button-group.tsx
new file mode 100644
index 0000000..7834dcd
--- /dev/null
+++ b/apps/docs/src/demos/cn/toolbar/with-button-group.tsx
@@ -0,0 +1,64 @@
+import {
+  ArrowUturnCcwLeft,
+  ArrowUturnCwRight,
+  Bold,
+  Italic,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function WithButtonGroup() {
+  return (
+    <Toolbar aria-label="编辑器工具栏">
+      <ButtonGroup variant="tertiary">
+        <Button>
+          <ArrowUturnCcwLeft />
+          撤销
+        </Button>
+        <Button>
+          <ButtonGroup.Separator />
+          <ArrowUturnCwRight />
+          重做
+        </Button>
+      </ButtonGroup>
+      <Separator />
+      <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="粗体" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="斜体" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="下划线" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="左对齐">
+          <TextAlignLeft />
+        </Button>
+        <Button isIconOnly aria-label="居中">
+          <ButtonGroup.Separator />
+          <TextAlignCenter />
+        </Button>
+        <Button isIconOnly aria-label="右对齐">
+          <ButtonGroup.Separator />
+          <TextAlignRight />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tooltip/basic.tsx b/apps/docs/src/demos/cn/tooltip/basic.tsx
new file mode 100644
index 0000000..9b7281c
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/basic.tsx
@@ -0,0 +1,24 @@
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">悬停查看</Button>
+        <Tooltip.Content>
+          <p>这是一个工具提示</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button isIconOnly variant="tertiary">
+          <CircleInfo />
+        </Button>
+        <Tooltip.Content>
+          <p>更多信息</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tooltip/custom-render-function.tsx b/apps/docs/src/demos/cn/tooltip/custom-render-function.tsx
new file mode 100644
index 0000000..177bef5
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/custom-render-function.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Tooltip} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">悬停查看</Button>
+        <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}>
+          <p>这是一个工具提示</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button isIconOnly variant="tertiary">
+          <CircleInfo />
+        </Button>
+        <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}>
+          <p>更多信息</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tooltip/custom-trigger.tsx b/apps/docs/src/demos/cn/tooltip/custom-trigger.tsx
new file mode 100644
index 0000000..7c80682
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/custom-trigger.tsx
@@ -0,0 +1,58 @@
+import {CircleCheckFill, CircleQuestion} from "@gravity-ui/icons";
+import {Avatar, Chip, Tooltip} from "@heroui/react";
+
+export function TooltipCustomTrigger() {
+  return (
+    <div className="flex items-center gap-6">
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="用户头像">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Jane Doe"
+              src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
+            />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+        </Tooltip.Trigger>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <div className="flex flex-col gap-0 py-1">
+            <p className="font-semibold">Jane Doe</p>
+            <p className="text-xs text-muted">jane@example.com</p>
+          </div>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="状态标签">
+          <Chip color="success">
+            <CircleCheckFill width={12} />
+            <Chip.Label>活跃</Chip.Label>
+          </Chip>
+        </Tooltip.Trigger>
+        <Tooltip.Content className="flex items-center gap-1.5">
+          <span className="relative flex size-2">
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-success opacity-75" />
+            <span className="relative inline-flex size-2 rounded-full bg-success" />
+          </span>
+          <p>Jane 当前在线</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="信息图标">
+          <div className="rounded-full bg-accent-soft p-2">
+            <CircleQuestion className="text-accent" />
+          </div>
+        </Tooltip.Trigger>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <div className="max-w-xs px-1 py-1.5">
+            <p className="mb-1 font-semibold">帮助信息</p>
+            <p className="text-sm text-muted">这是包含有关此功能更详细信息的实用工具提示。</p>
+          </div>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tooltip/index.ts b/apps/docs/src/demos/cn/tooltip/index.ts
new file mode 100644
index 0000000..abbc34b
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/index.ts
@@ -0,0 +1,5 @@
+export {TooltipBasic as Basic} from "./basic";
+export {TooltipWithArrow as WithArrow} from "./with-arrow";
+export {TooltipPlacement as Placement} from "./placement";
+export {TooltipCustomTrigger as CustomTrigger} from "./custom-trigger";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/cn/tooltip/placement.tsx b/apps/docs/src/demos/cn/tooltip/placement.tsx
new file mode 100644
index 0000000..942dc7a
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/placement.tsx
@@ -0,0 +1,55 @@
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipPlacement() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <div />
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Top
+        </Button>
+        <Tooltip.Content showArrow placement="top">
+          <Tooltip.Arrow />
+          <p>顶部位置</p>
+        </Tooltip.Content>
+      </Tooltip>
+      <div />
+
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Left
+        </Button>
+        <Tooltip.Content showArrow placement="left">
+          <Tooltip.Arrow />
+          <p>左侧位置</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <div className="flex items-center justify-center">
+        <span className="text-sm text-muted">悬停按钮</span>
+      </div>
+
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Right
+        </Button>
+        <Tooltip.Content showArrow placement="right">
+          <Tooltip.Arrow />
+          <p>右侧位置</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <div />
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Bottom
+        </Button>
+        <Tooltip.Content showArrow placement="bottom">
+          <Tooltip.Arrow />
+          <p>底部位置</p>
+        </Tooltip.Content>
+      </Tooltip>
+      <div />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/tooltip/with-arrow.tsx b/apps/docs/src/demos/cn/tooltip/with-arrow.tsx
new file mode 100644
index 0000000..5d4aad5
--- /dev/null
+++ b/apps/docs/src/demos/cn/tooltip/with-arrow.tsx
@@ -0,0 +1,23 @@
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipWithArrow() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">带箭头</Button>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <p>带箭头指示器的工具提示</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button variant="primary">自定义偏移</Button>
+        <Tooltip.Content showArrow offset={12}>
+          <Tooltip.Arrow />
+          <p>与触发器的自定义偏移</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/cn/typography/default.tsx b/apps/docs/src/demos/cn/typography/default.tsx
new file mode 100644
index 0000000..27f3125
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/default.tsx
@@ -0,0 +1,20 @@
+import {Typography} from "@heroui/react";
+
+export const Default = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography type="h1">打造更出色的界面</Typography>
+      <Typography type="h2">保持语义化的排版</Typography>
+      <Typography type="h3">默认可组合</Typography>
+      <Typography type="h4">小标题</Typography>
+      <Typography>
+        HeroUI Typography 以 React Aria Components Text 为原语，提供语义化排版类型与 render prop
+        多态。
+      </Typography>
+      <Typography color="muted" type="body-sm">
+        用于次要说明的较小弱化正文。
+      </Typography>
+      <Typography type="code">pnpm add @heroui/react</Typography>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/cn/typography/index.ts b/apps/docs/src/demos/cn/typography/index.ts
new file mode 100644
index 0000000..f5c1316
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/index.ts
@@ -0,0 +1,5 @@
+export {Default} from "./default";
+export {Primitives} from "./primitives";
+export {Prose} from "./prose";
+export {RenderProps} from "./render-props";
+export {TypographyScale} from "./typography-scale";
diff --git a/apps/docs/src/demos/cn/typography/primitives.tsx b/apps/docs/src/demos/cn/typography/primitives.tsx
new file mode 100644
index 0000000..8fa4dd6
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/primitives.tsx
@@ -0,0 +1,16 @@
+import {Typography} from "@heroui/react";
+
+export const Primitives = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography.Heading level={1}>仪表盘</Typography.Heading>
+      <Typography.Paragraph>
+        便捷原语是 Typography 的薄封装，可在不学习第二套样式系统的情况下选择显式组合。
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" size="sm">
+        Paragraph 支持 base、sm 和 xs 尺寸。
+      </Typography.Paragraph>
+      <Typography.Code>Typography.Code</Typography.Code>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/cn/typography/prose.tsx b/apps/docs/src/demos/cn/typography/prose.tsx
new file mode 100644
index 0000000..69dfcb1
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/prose.tsx
@@ -0,0 +1,14 @@
+import {Typography} from "@heroui/react";
+
+export const Prose = () => {
+  return (
+    <Typography.Prose className="flex max-w-xl flex-col gap-3">
+      <h1>正文标题</h1>
+      <p>Prose 适用于标记已是语义化、由 HeroUI 应用默认排版节奏的写作型内容。</p>
+      <h2>章节标题</h2>
+      <p>
+        行内代码如 <code>render</code> 与 Typography 原语获得相同的代码样式处理。
+      </p>
+    </Typography.Prose>
+  );
+};
diff --git a/apps/docs/src/demos/cn/typography/render-props.tsx b/apps/docs/src/demos/cn/typography/render-props.tsx
new file mode 100644
index 0000000..155f988
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/render-props.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Typography} from "@heroui/react";
+
+export const RenderProps = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography render={({children, ...domProps}) => <h2 {...domProps}>{children}</h2>} type="h1">
+        H1 视觉样式，h2 语义元素
+      </Typography>
+      <Typography render={({children, ...domProps}) => <span {...domProps}>{children}</span>}>
+        render prop 可更换底层元素，同时保留 HeroUI 的 props 与样式。
+      </Typography>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/cn/typography/typography-scale.tsx b/apps/docs/src/demos/cn/typography/typography-scale.tsx
new file mode 100644
index 0000000..eabb358
--- /dev/null
+++ b/apps/docs/src/demos/cn/typography/typography-scale.tsx
@@ -0,0 +1,80 @@
+import {Typography} from "@heroui/react";
+
+const scale = [
+  {
+    label: "h1",
+    meta: "36px / 600 / 1.11 / tight",
+    sample: "打造更出色的界面",
+    type: "h1" as const,
+  },
+  {
+    label: "h2",
+    meta: "30px / 600 / 1.17 / tight",
+    sample: "为智能时代而生",
+    type: "h2" as const,
+  },
+  {
+    label: "h3",
+    meta: "24px / 600 / 1.25 / tight",
+    sample: "按您的条件定价",
+    type: "h3" as const,
+  },
+  {
+    label: "h4",
+    meta: "20px / 600 / 1.33 / tight",
+    sample: "申请创业计划",
+    type: "h4" as const,
+  },
+  {
+    label: "h5",
+    meta: "18px / 600 / 1.39 / tight",
+    sample: "卡片标题",
+    type: "h5" as const,
+  },
+  {
+    label: "h6",
+    meta: "16px / 600 / 1.50 / tight",
+    sample: "较小的功能标题",
+    type: "h6" as const,
+  },
+  {
+    label: "body",
+    meta: "16px / 400 / 1.75",
+    sample: "用于文档、营销文案与描述的主要正文。",
+    type: "body" as const,
+  },
+  {
+    label: "body-sm",
+    meta: "14px / 400 / 1.50",
+    sample: "次要正文、表格单元格、导航与侧边栏项。",
+    type: "body-sm" as const,
+  },
+  {
+    label: "body-xs",
+    meta: "12px / 400 / 1.25",
+    sample: "说明文字、徽章、辅助文本与细则。",
+    type: "body-xs" as const,
+  },
+  {
+    label: "code",
+    meta: "14px / mono",
+    sample: "pnpm add @heroui/react",
+    type: "code" as const,
+  },
+] as const;
+
+export const TypographyScale = () => {
+  return (
+    <div className="flex w-full flex-col divide-y divide-border">
+      {scale.map((row) => (
+        <div key={row.label} className="grid grid-cols-[160px_1fr] items-center gap-8 py-5">
+          <div className="flex shrink-0 flex-col gap-0.5">
+            <span className="text-sm font-semibold text-foreground">{row.label}</span>
+            <span className="text-xs whitespace-nowrap text-muted">{row.meta}</span>
+          </div>
+          <Typography type={row.type}>{row.sample}</Typography>
+        </div>
+      ))}
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/en/accordion/basic.tsx b/apps/docs/src/demos/en/accordion/basic.tsx
new file mode 100644
index 0000000..681f729
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/basic.tsx
@@ -0,0 +1,73 @@
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content:
+      "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+    icon: <ShoppingBag />,
+    title: "How do I place an order?",
+  },
+  {
+    content:
+      "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+    icon: <Receipt />,
+    title: "Can I modify or cancel my order?",
+  },
+  {
+    content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
+    icon: <CreditCard />,
+    title: "What payment methods do you accept?",
+  },
+  {
+    content:
+      "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.",
+    icon: <Box />,
+    title: "How much does shipping cost?",
+  },
+  {
+    content:
+      "Yes, we ship to most countries. Please check our shipping rates and policies for more information.",
+    icon: <PlanetEarth />,
+    title: "Do you ship internationally?",
+  },
+  {
+    content:
+      "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.",
+    icon: <ArrowsRotateLeft />,
+    title: "How do I request a refund?",
+  },
+];
+
+export function Basic() {
+  return (
+    <Accordion className="w-full max-w-md">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/controlled.tsx b/apps/docs/src/demos/en/accordion/controlled.tsx
new file mode 100644
index 0000000..dfd700c
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/controlled.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import {ChevronDown, ChevronUp} from "@gravity-ui/icons";
+import {Accordion, Button, useDisclosureGroupNavigation} from "@heroui/react";
+import React from "react";
+
+const items = [
+  {
+    content:
+      "Learn the basics of HeroUI and how to integrate it into your React project. This section covers installation, setup, and your first component.",
+    id: "getting-started",
+    title: "Getting Started",
+  },
+  {
+    content:
+      "Understand the fundamental concepts behind HeroUI, including the compound component pattern, styling with Tailwind CSS, and accessibility features.",
+    id: "core-concepts",
+    title: "Core Concepts",
+  },
+  {
+    content:
+      "Explore advanced features like custom variants, theme customization, and integration with other libraries in your React ecosystem.",
+    id: "advanced-usage",
+    title: "Advanced Usage",
+  },
+];
+
+export function Controlled() {
+  const [expandedKeys, setExpandedKeys] = React.useState(
+    new Set<string | number>(["getting-started"]),
+  );
+  const itemIds = items.map((item) => item.id);
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="mb-4 flex items-center justify-between">
+        <p className="text-sm text-muted">
+          Expanded: <strong>{[...expandedKeys].join(", ") || "none"}</strong>
+        </p>
+        <div className="flex gap-2">
+          <Button
+            aria-label="Previous item"
+            isDisabled={isPrevDisabled}
+            size="sm"
+            variant="secondary"
+            onPress={onPrevious}
+          >
+            <ChevronUp className="size-4" />
+          </Button>
+          <Button
+            aria-label="Next item"
+            isDisabled={isNextDisabled}
+            size="sm"
+            variant="secondary"
+            onPress={onNext}
+          >
+            <ChevronDown className="size-4" />
+          </Button>
+        </div>
+      </div>
+      <Accordion expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+        {items.map((item) => (
+          <Accordion.Item key={item.id} id={item.id}>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                {item.title}
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>{item.content}</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        ))}
+      </Accordion>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/custom-indicator.tsx b/apps/docs/src/demos/en/accordion/custom-indicator.tsx
new file mode 100644
index 0000000..1f5ee9f
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/custom-indicator.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {ChevronsDown, CircleChevronDown, Minus, Plus} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+import React from "react";
+
+export function CustomIndicator() {
+  const [expandedKeys, setExpandedKeys] = React.useState<Set<Key>>(new Set([""]));
+
+  return (
+    <Accordion
+      className="w-full max-w-md"
+      expandedKeys={expandedKeys}
+      variant="surface"
+      onExpandedChange={setExpandedKeys}
+    >
+      <Accordion.Item id="1">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Using Plus/Minus Icon
+            <Accordion.Indicator>
+              {expandedKeys.has("1") ? <Minus /> : <Plus />}
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            This accordion uses a plus icon that transforms when expanded. The icon automatically
+            rotates 45 degrees to form an X.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item id="2">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Using Caret Icon
+            <Accordion.Indicator>
+              <CircleChevronDown />
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            This item uses a caret icon for the indicator. The rotation animation is applied
+            automatically.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item id="3">
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Using Arrow Icon
+            <Accordion.Indicator>
+              <ChevronsDown />
+            </Accordion.Indicator>
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            This item uses an arrow icon. Any icon you pass will receive the rotation animation when
+            the item expands.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/custom-render-function.tsx b/apps/docs/src/demos/en/accordion/custom-render-function.tsx
new file mode 100644
index 0000000..4428419
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/custom-render-function.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content:
+      "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+    icon: <ShoppingBag />,
+    title: "How do I place an order?",
+  },
+  {
+    content:
+      "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+    icon: <Receipt />,
+    title: "Can I modify or cancel my order?",
+  },
+  {
+    content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
+    icon: <CreditCard />,
+    title: "What payment methods do you accept?",
+  },
+  {
+    content:
+      "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.",
+    icon: <Box />,
+    title: "How much does shipping cost?",
+  },
+  {
+    content:
+      "Yes, we ship to most countries. Please check our shipping rates and policies for more information.",
+    icon: <PlanetEarth />,
+    title: "Do you ship internationally?",
+  },
+  {
+    content:
+      "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.",
+    icon: <ArrowsRotateLeft />,
+    title: "How do I request a refund?",
+  },
+];
+
+export function CustomRenderFunction() {
+  return (
+    <Accordion
+      className="w-full max-w-md"
+      render={(props) => <div data-custom="accordion" {...props} />}
+    >
+      {items.map((item, index) => (
+        <Accordion.Item key={index} render={(props) => <div data-custom="item" {...props} />}>
+          <Accordion.Heading render={(props) => <div data-custom="heading" {...props} />}>
+            <Accordion.Trigger render={(props) => <button data-custom="trigger" {...props} />}>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel render={(props) => <div data-custom="panel" {...props} />}>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/custom-styles.tsx b/apps/docs/src/demos/en/accordion/custom-styles.tsx
new file mode 100644
index 0000000..37a2224
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/custom-styles.tsx
@@ -0,0 +1,64 @@
+import {ChevronDown} from "@gravity-ui/icons";
+import {Accordion, cn} from "@heroui/react";
+
+const items = [
+  {
+    content: "Stay informed about your account activity with real-time notifications. ",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    subtitle: "Receive account activity updates",
+    title: "Set Up Notifications",
+  },
+  {
+    content: "Enhance your browsing experience by installing our official browser extension",
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    subtitle: "Connect you browser to your account",
+    title: "Set up Browser Extension",
+  },
+  {
+    content:
+      "Begin your journey into the world of digital collectibles by creating your first NFT. ",
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    subtitle: "Create your first collectible",
+    title: "Mint Collectible",
+  },
+];
+
+export function CustomStyles() {
+  return (
+    <Accordion className="bg-surface-1/10 w-full max-w-md rounded-2xl" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item
+          key={index}
+          className={cn(
+            "group/item",
+            "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top
+            "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom
+          )}
+        >
+          <Accordion.Heading>
+            <Accordion.Trigger className="hover:bgsurface group flex items-center gap-2 transition-none">
+              {item.iconUrl ? (
+                <img
+                  alt={item.title}
+                  className="h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:scale-120 group-hover/item:-rotate-10 group-hover/item:drop-shadow-lg"
+                  src={item.iconUrl}
+                />
+              ) : null}
+              <div className="flex flex-col gap-0">
+                <span className="leading-5 font-medium">{item.title}</span>
+                <span className="leading-6 font-normal text-muted/80">{item.subtitle}</span>
+              </div>
+              <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/disabled.tsx b/apps/docs/src/demos/en/accordion/disabled.tsx
new file mode 100644
index 0000000..c9dec59
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/disabled.tsx
@@ -0,0 +1,83 @@
+import {Accordion} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-full flex-col items-center gap-8">
+      <div className="w-full max-w-md space-y-2">
+        <h3 className="text-sm font-medium text-muted">Entire accordion disabled</h3>
+        <Accordion isDisabled className="w-full max-w-md">
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                Disabled Item 1
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>
+                This content cannot be accessed when the accordion is disabled.
+              </Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                Disabled Item 2
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>
+                This content cannot be accessed when the accordion is disabled.
+              </Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </div>
+
+      <div className="w-full max-w-md space-y-2">
+        <h3 className="text-sm font-medium text-muted">Individual items disabled</h3>
+        <Accordion className="w-full max-w-md">
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                Active Item
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>This item is active and can be toggled normally.</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item isDisabled>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                Disabled Item
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>
+                This content cannot be accessed when the item is disabled.
+              </Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item>
+            <Accordion.Heading>
+              <Accordion.Trigger>
+                Another Active Item
+                <Accordion.Indicator />
+              </Accordion.Trigger>
+            </Accordion.Heading>
+            <Accordion.Panel>
+              <Accordion.Body>This item is also active and can be toggled.</Accordion.Body>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/faq.tsx b/apps/docs/src/demos/en/accordion/faq.tsx
new file mode 100644
index 0000000..8c48594
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/faq.tsx
@@ -0,0 +1,80 @@
+import {ChevronDown} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+export function FAQ() {
+  const categories = [
+    {
+      items: [
+        {
+          content:
+            "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+          title: "How do I place an order?",
+        },
+        {
+          content:
+            "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+          title: "Can I modify or cancel my order?",
+        },
+      ],
+      title: "General",
+    },
+    {
+      items: [
+        {
+          content:
+            "You can purchase a license directly from our website. Select the license type that fits your needs and proceed to checkout.",
+          title: "How do I purchase a license?",
+        },
+        {
+          content:
+            "A standard license is for personal use or small projects, while a pro license includes commercial use rights and priority support.",
+          title: "What is the difference between a standard and a pro license?",
+        },
+      ],
+      title: "Licensing",
+    },
+    {
+      items: [
+        {
+          content:
+            "You can reach our support team through the contact form on our website, or email us directly at support@example.com.",
+          title: "How do I get support?",
+        },
+      ],
+      title: "Support",
+    },
+  ];
+
+  return (
+    <div className="flex w-full flex-col gap-6">
+      <div className="flex flex-col gap-1">
+        <h2 className="text-2xl font-bold">Frequently Asked Questions</h2>
+        <p className="mb-4 text-lg font-medium text-muted">
+          Everything you need to know about licensing and usage.
+        </p>
+      </div>
+      {categories.map((category) => (
+        <div key={category.title}>
+          <p className="text-md mb-2 font-medium text-muted">{category.title}</p>
+          <Accordion className="w-full" variant="surface">
+            {category.items.map((item, index) => (
+              <Accordion.Item key={index}>
+                <Accordion.Heading>
+                  <Accordion.Trigger>
+                    {item.title}
+                    <Accordion.Indicator>
+                      <ChevronDown />
+                    </Accordion.Indicator>
+                  </Accordion.Trigger>
+                </Accordion.Heading>
+                <Accordion.Panel>
+                  <Accordion.Body>{item.content}</Accordion.Body>
+                </Accordion.Panel>
+              </Accordion.Item>
+            ))}
+          </Accordion>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/index.ts b/apps/docs/src/demos/en/accordion/index.ts
new file mode 100644
index 0000000..06e302a
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FAQ} from "./faq";
+export {Multiple} from "./multiple";
+export {Surface} from "./surface";
+export {CustomStyles} from "./custom-styles";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/en/accordion/multiple.tsx b/apps/docs/src/demos/en/accordion/multiple.tsx
new file mode 100644
index 0000000..c12de2c
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/multiple.tsx
@@ -0,0 +1,67 @@
+import {Accordion} from "@heroui/react";
+
+export function Multiple() {
+  return (
+    <Accordion allowsMultipleExpanded className="w-full max-w-md">
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Getting Started
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            Learn the basics of HeroUI and how to integrate it into your React project. This section
+            covers installation, setup, and your first component.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Core Concepts
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            Understand the fundamental concepts behind HeroUI, including the compound component
+            pattern, styling with Tailwind CSS, and accessibility features.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Advanced Usage
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            Explore advanced features like custom variants, theme customization, and integration
+            with other libraries in your React ecosystem.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+
+      <Accordion.Item>
+        <Accordion.Heading>
+          <Accordion.Trigger>
+            Best Practices
+            <Accordion.Indicator />
+          </Accordion.Trigger>
+        </Accordion.Heading>
+        <Accordion.Panel>
+          <Accordion.Body>
+            Follow our recommended best practices for building performant, accessible, and
+            maintainable applications with HeroUI components.
+          </Accordion.Body>
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/surface.tsx b/apps/docs/src/demos/en/accordion/surface.tsx
new file mode 100644
index 0000000..56af6f8
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/surface.tsx
@@ -0,0 +1,73 @@
+import {
+  ArrowsRotateLeft,
+  Box,
+  ChevronDown,
+  CreditCard,
+  PlanetEarth,
+  Receipt,
+  ShoppingBag,
+} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content:
+      "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+    icon: <ShoppingBag />,
+    title: "How do I place an order?",
+  },
+  {
+    content:
+      "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+    icon: <Receipt />,
+    title: "Can I modify or cancel my order?",
+  },
+  {
+    content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
+    icon: <CreditCard />,
+    title: "What payment methods do you accept?",
+  },
+  {
+    content:
+      "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.",
+    icon: <Box />,
+    title: "How much does shipping cost?",
+  },
+  {
+    content:
+      "Yes, we ship to most countries. Please check our shipping rates and policies for more information.",
+    icon: <PlanetEarth />,
+    title: "Do you ship internationally?",
+  },
+  {
+    content:
+      "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.",
+    icon: <ArrowsRotateLeft />,
+    title: "How do I request a refund?",
+  },
+];
+
+export function Surface() {
+  return (
+    <Accordion className="w-full max-w-md" variant="surface">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/accordion/without-separator.tsx b/apps/docs/src/demos/en/accordion/without-separator.tsx
new file mode 100644
index 0000000..058d999
--- /dev/null
+++ b/apps/docs/src/demos/en/accordion/without-separator.tsx
@@ -0,0 +1,47 @@
+import {ChevronDown, CreditCard, Receipt, ShoppingBag} from "@gravity-ui/icons";
+import {Accordion} from "@heroui/react";
+
+const items = [
+  {
+    content:
+      "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+    icon: <ShoppingBag />,
+    title: "How do I place an order?",
+  },
+  {
+    content:
+      "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+    icon: <Receipt />,
+    title: "Can I modify or cancel my order?",
+  },
+  {
+    content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
+    icon: <CreditCard />,
+    title: "What payment methods do you accept?",
+  },
+];
+
+export function WithoutSeparator() {
+  return (
+    <Accordion hideSeparator className="w-full max-w-md">
+      {items.map((item, index) => (
+        <Accordion.Item key={index}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span>
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <ChevronDown />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/backdrop-variants.tsx b/apps/docs/src/demos/en/alert-dialog/backdrop-variants.tsx
new file mode 100644
index 0000000..ce022cf
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/backdrop-variants.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <AlertDialog key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <AlertDialog.Backdrop variant={variant}>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {variant === "opaque"
+                      ? "An opaque dark backdrop that completely obscures the background, providing maximum focus on the dialog."
+                      : variant === "blur"
+                        ? "A blurred backdrop that softly obscures the background while maintaining visual context."
+                        : "A transparent backdrop that keeps the background fully visible, useful for less critical confirmations."}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/close-methods.tsx b/apps/docs/src/demos/en/alert-dialog/close-methods.tsx
new file mode 100644
index 0000000..ea5cfb4
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/close-methods.tsx
@@ -0,0 +1,81 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CloseMethods() {
+  return (
+    <div className="flex max-w-2xl flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">Using slot="close"</h3>
+        <p className="text-sm text-muted">
+          The simplest way to close a dialog. Add <code>slot="close"</code> to any Button component
+          within the dialog. When clicked, it will automatically close the dialog.
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">Open Dialog</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>Using slot="close"</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    Click either button below - both have <code>slot="close"</code> and will close
+                    the dialog automatically.
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">Using Dialog render props</h3>
+        <p className="text-sm text-muted">
+          Access the <code>close</code> method from the Dialog's render props. This gives you full
+          control over when and how to close the dialog, allowing you to add custom logic before
+          closing.
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">Open Dialog</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                {(renderProps) => (
+                  <>
+                    <AlertDialog.Header>
+                      <AlertDialog.Icon status="success" />
+                      <AlertDialog.Heading>Using Dialog render props</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p>
+                        The buttons below use the <code>close</code> method from render props. You
+                        can add validation or other logic before calling{" "}
+                        <code>renderProps.close()</code>.
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer>
+                      <Button variant="tertiary" onPress={() => renderProps.close()}>
+                        Cancel
+                      </Button>
+                      <Button onPress={() => renderProps.close()}>Confirm</Button>
+                    </AlertDialog.Footer>
+                  </>
+                )}
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/controlled.tsx b/apps/docs/src/demos/en/alert-dialog/controlled.tsx
new file mode 100644
index 0000000..46e03f0
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/controlled.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import {AlertDialog, Button, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Control the alert dialog using React's <code className="text-foreground">useState</code>{" "}
+          hook for simple state management. Perfect for basic use cases.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              Open Dialog
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="accent" />
+                <AlertDialog.Heading>Controlled with useState()</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  This alert dialog is controlled by React's <code>useState</code> hook. Pass{" "}
+                  <code>isOpen</code> and <code>onOpenChange</code> props to manage the dialog state
+                  externally.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API
+          with convenient methods like <code>open()</code>, <code>close()</code>, and{" "}
+          <code>toggle()</code>.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              Open Dialog
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="success" />
+                <AlertDialog.Heading>Controlled with useOverlayState()</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  The <code>useOverlayState</code> hook provides dedicated methods for common
+                  operations. No need to manually create callbacks—just use{" "}
+                  <code>state.open()</code>, <code>state.close()</code>, or{" "}
+                  <code>state.toggle()</code>.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/custom-animations.tsx b/apps/docs/src/demos/en/alert-dialog/custom-animations.tsx
new file mode 100644
index 0000000..bcdf2d2
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/custom-animations.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+import React from "react";
+
+const iconMap: Record<string, React.ComponentType<{className?: string}>> = {
+  "gravity-ui:arrow-up-from-line": ArrowUpFromLine,
+  "gravity-ui:sparkles": Sparkles,
+};
+
+export function CustomAnimations() {
+  const animations = [
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+      description:
+        "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Alert Dialogs and Modals.",
+      icon: "gravity-ui:sparkles",
+      name: "Kinematic Scale",
+    },
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+      description:
+        "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.",
+      icon: "gravity-ui:arrow-up-from-line",
+      name: "Fluid Slide",
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => {
+        const IconComponent = iconMap[icon];
+
+        return (
+          <AlertDialog key={name}>
+            <Button variant="secondary">{name}</Button>
+            <AlertDialog.Backdrop className={classNames.backdrop}>
+              <AlertDialog.Container className={classNames.container}>
+                <AlertDialog.Dialog className="sm:max-w-[400px]">
+                  <AlertDialog.CloseTrigger />
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="accent">
+                      {!!IconComponent && <IconComponent className="size-5" />}
+                    </AlertDialog.Icon>
+                    <AlertDialog.Heading>{name} Animation</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p className="mt-1">{description}</p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button slot="close" variant="tertiary">
+                      Close
+                    </Button>
+                    <Button slot="close">Try Again</Button>
+                  </AlertDialog.Footer>
+                </AlertDialog.Dialog>
+              </AlertDialog.Container>
+            </AlertDialog.Backdrop>
+          </AlertDialog>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/custom-backdrop.tsx b/apps/docs/src/demos/en/alert-dialog/custom-backdrop.tsx
new file mode 100644
index 0000000..0198953
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/custom-backdrop.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {TriangleExclamation} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomBackdrop() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">Delete Account</Button>
+      <AlertDialog.Backdrop
+        className="bg-linear-to-t from-red-950/90 via-red-950/50 to-transparent dark:from-red-950/95 dark:via-red-950/60"
+        variant="blur"
+      >
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[420px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header className="items-center text-center">
+              <AlertDialog.Icon status="danger">
+                <TriangleExclamation className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>Permanently delete your account?</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                This action cannot be undone. All your data, settings, and content will be
+                permanently removed from our servers. The dramatic red backdrop emphasizes the
+                severity and irreversibility of this decision.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer className="flex-col-reverse">
+              <Button className="w-full" slot="close">
+                Keep Account
+              </Button>
+              <Button className="w-full" slot="close" variant="danger">
+                Delete Forever
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/custom-icon.tsx b/apps/docs/src/demos/en/alert-dialog/custom-icon.tsx
new file mode 100644
index 0000000..0f25d08
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/custom-icon.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {LockOpen} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomIcon() {
+  return (
+    <AlertDialog>
+      <Button variant="secondary">Reset Password</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="warning">
+                <LockOpen className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>Reset your password?</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                We'll send a password reset link to your email address. You'll need to create a new
+                password to regain access to your account.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close">Send Reset Link</Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/custom-portal.tsx b/apps/docs/src/demos/en/alert-dialog/custom-portal.tsx
new file mode 100644
index 0000000..a2e8e40
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/custom-portal.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+export function CustomPortal() {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          Render alert dialogs inside a custom container instead of <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the
+          container to create a new stacking context.
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <AlertDialog>
+            <Button>Open Alert Dialog</Button>
+            <AlertDialog.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <AlertDialog.Container className="h-full max-h-full">
+                <AlertDialog.Dialog className="h-full max-h-full sm:max-w-md">
+                  <AlertDialog.CloseTrigger />
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="accent" />
+                    <AlertDialog.Heading>Custom Portal</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button slot="close" variant="tertiary">
+                      Cancel
+                    </Button>
+                    <Button slot="close">Confirm</Button>
+                  </AlertDialog.Footer>
+                </AlertDialog.Dialog>
+              </AlertDialog.Container>
+            </AlertDialog.Backdrop>
+          </AlertDialog>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/custom-trigger.tsx b/apps/docs/src/demos/en/alert-dialog/custom-trigger.tsx
new file mode 100644
index 0000000..a253915
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/custom-trigger.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import {TrashBin} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <AlertDialog>
+      <AlertDialog.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+        <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger-soft-foreground">
+          <TrashBin className="size-6" />
+        </div>
+        <div className="flex flex-1 flex-col gap-0.5">
+          <p className="text-sm font-semibold">Delete Item</p>
+          <p className="text-xs text-muted">Permanently remove this item</p>
+        </div>
+      </AlertDialog.Trigger>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger">
+                <TrashBin className="size-5" />
+              </AlertDialog.Icon>
+              <AlertDialog.Heading>Delete this item?</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                Use <code>AlertDialog.Trigger</code> to create custom trigger elements beyond
+                standard buttons. This example shows a card-style trigger with icons and descriptive
+                text.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close" variant="danger">
+                Delete Item
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/default.tsx b/apps/docs/src/demos/en/alert-dialog/default.tsx
new file mode 100644
index 0000000..003396a
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/default.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Default() {
+  return (
+    <AlertDialog>
+      <Button variant="danger">Delete Project</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger" />
+              <AlertDialog.Heading>Delete project permanently?</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                This will permanently delete <strong>My Awesome Project</strong> and all of its
+                data. This action cannot be undone.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close" variant="danger">
+                Delete Project
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/dismiss-behavior.tsx b/apps/docs/src/demos/en/alert-dialog/dismiss-behavior.tsx
new file mode 100644
index 0000000..fa6e808
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/dismiss-behavior.tsx
@@ -0,0 +1,88 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function DismissBehavior() {
+  return (
+    <div className="flex max-w-sm flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isDismissable</h3>
+        <p className="text-sm text-muted">
+          Controls whether the alert dialog can be dismissed by clicking the overlay backdrop. Alert
+          dialogs typically require explicit action, so this defaults to <code>false</code>. Set to{" "}
+          <code>true</code> for less critical confirmations.
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">Open Alert Dialog</Button>
+          <AlertDialog.Backdrop isDismissable={false}>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="danger">
+                    <CircleInfo className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>isDismissable = false</AlertDialog.Heading>
+                  <p className="text-sm leading-5 text-muted">
+                    Clicking the backdrop won't close this alert dialog
+                  </p>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    Try clicking outside this alert dialog on the overlay - it won't close. You must
+                    use the action buttons to dismiss it.
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+        <p className="text-sm text-muted">
+          Controls whether the ESC key can dismiss the alert dialog. Alert dialogs typically require
+          explicit action, so this defaults to <code>true</code>. When set to <code>false</code>,
+          the ESC key will be enabled.
+        </p>
+        <AlertDialog>
+          <Button variant="secondary">Open Alert Dialog</Button>
+          <AlertDialog.Backdrop isKeyboardDismissDisabled>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent">
+                    <CircleInfo className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>isKeyboardDismissDisabled = true</AlertDialog.Heading>
+                  <p className="text-sm leading-5 text-muted">ESC key is disabled</p>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    Press ESC - nothing happens. You must use the action buttons to dismiss this
+                    alert dialog.
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/index.ts b/apps/docs/src/demos/en/alert-dialog/index.ts
new file mode 100644
index 0000000..d5bb4ee
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/index.ts
@@ -0,0 +1,14 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {CloseMethods} from "./close-methods";
+export {Controlled} from "./controlled";
+export {CustomAnimations} from "./custom-animations";
+export {CustomBackdrop} from "./custom-backdrop";
+export {CustomIcon} from "./custom-icon";
+export {CustomPortal} from "./custom-portal";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {DismissBehavior} from "./dismiss-behavior";
+export {Placements} from "./placements";
+export {Sizes} from "./sizes";
+export {Statuses} from "./statuses";
+export {WithCloseButton} from "./with-close-button";
diff --git a/apps/docs/src/demos/en/alert-dialog/placements.tsx b/apps/docs/src/demos/en/alert-dialog/placements.tsx
new file mode 100644
index 0000000..4bf2e9b
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/placements.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Placements() {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <AlertDialog key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container placement={placement}>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    {placement === "auto"
+                      ? "Auto Placement"
+                      : `${placement.charAt(0).toUpperCase() + placement.slice(1)} Position`}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {placement === "auto"
+                      ? "Automatically positions at the bottom on mobile and center on desktop for optimal user experience."
+                      : `This dialog is positioned at the ${placement} of the viewport. Critical confirmations are typically centered for maximum attention.`}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/sizes.tsx b/apps/docs/src/demos/en/alert-dialog/sizes.tsx
new file mode 100644
index 0000000..d1a3739
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/sizes.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Sizes() {
+  const sizes = ["xs", "sm", "md", "lg", "cover"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <AlertDialog key={size}>
+          <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container size={size}>
+              <AlertDialog.Dialog>
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>
+                    Size: {size.charAt(0).toUpperCase() + size.slice(1)}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        This alert dialog uses the <code>cover</code> size variant. It spans the
+                        full screen with margins: 16px on mobile and 40px on desktop. Maintains
+                        rounded corners and standard padding. Perfect for critical confirmations
+                        that need maximum width while preserving alert dialog aesthetics.
+                      </>
+                    ) : (
+                      <>
+                        This alert dialog uses the <code>{size}</code> size variant. On mobile
+                        devices, all sizes adapt to near full-width for optimal viewing. On desktop,
+                        each size provides a different maximum width to suit various content needs.
+                      </>
+                    )}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/statuses.tsx b/apps/docs/src/demos/en/alert-dialog/statuses.tsx
new file mode 100644
index 0000000..ecd0903
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/statuses.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function Statuses() {
+  const examples = [
+    {
+      actions: {
+        cancel: "Stay Signed In",
+        confirm: "Sign Out",
+      },
+      body: "You'll need to sign in again to access your account. Any unsaved changes will be lost.",
+      classNames: "bg-accent-soft text-accent-soft-foreground",
+      header: "Sign out of your account?",
+      status: "accent",
+      trigger: "Sign Out",
+    },
+    {
+      actions: {
+        cancel: "Not Yet",
+        confirm: "Mark Complete",
+      },
+      body: "This will mark the task as complete and notify all team members. The task will be moved to your completed list.",
+      classNames: "bg-success-soft text-success-soft-foreground",
+      header: "Complete this task?",
+      status: "success",
+      trigger: "Complete Task",
+    },
+    {
+      actions: {
+        cancel: "Keep Editing",
+        confirm: "Discard",
+      },
+      body: "You have unsaved changes that will be permanently lost. Are you sure you want to discard them?",
+      classNames: "bg-warning-soft text-warning-soft-foreground",
+      header: "Discard unsaved changes?",
+      status: "warning",
+      trigger: "Discard Changes",
+    },
+    {
+      actions: {
+        cancel: "Cancel",
+        confirm: "Delete Account",
+      },
+      body: "This will permanently delete your account and remove all your data from our servers. This action is irreversible.",
+      classNames: "bg-danger-soft text-danger-soft-foreground",
+      header: "Delete your account?",
+      status: "danger",
+      trigger: "Delete Account",
+    },
+  ] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {examples.map(({actions, body, classNames, header, status, trigger}) => (
+        <AlertDialog key={status}>
+          <Button className={classNames}>{trigger}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status={status} />
+                  <AlertDialog.Heading>{header}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>{body}</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    {actions.cancel}
+                  </Button>
+                  <Button slot="close" variant={status === "danger" ? "danger" : "primary"}>
+                    {actions.confirm}
+                  </Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert-dialog/with-close-button.tsx b/apps/docs/src/demos/en/alert-dialog/with-close-button.tsx
new file mode 100644
index 0000000..7676f76
--- /dev/null
+++ b/apps/docs/src/demos/en/alert-dialog/with-close-button.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {AlertDialog, Button} from "@heroui/react";
+
+export function WithCloseButton() {
+  return (
+    <AlertDialog>
+      <Button variant="secondary">Show Information</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="accent" />
+              <AlertDialog.Heading>Less critical information</AlertDialog.Heading>
+              <p className="text-sm leading-relaxed text-muted">
+                Close button and backdrop dismiss are enabled
+              </p>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                For less critical confirmations, you can enable both the close button and backdrop
+                dismissal. This provides users with multiple ways to exit the dialog.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close">Confirm</Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert/basic.tsx b/apps/docs/src/demos/en/alert/basic.tsx
new file mode 100644
index 0000000..d76cc7d
--- /dev/null
+++ b/apps/docs/src/demos/en/alert/basic.tsx
@@ -0,0 +1,94 @@
+import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
+import React from "react";
+
+export function Basic() {
+  return (
+    <div className="grid w-full max-w-xl gap-4">
+      {/* Default - General information */}
+      <Alert>
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>New features available</Alert.Title>
+          <Alert.Description>
+            Check out our latest updates including dark mode support and improved accessibility
+            features.
+          </Alert.Description>
+        </Alert.Content>
+      </Alert>
+
+      {/* Accent - Important information with action */}
+      <Alert status="accent">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Update available</Alert.Title>
+          <Alert.Description>
+            A new version of the application is available. Please refresh to get the latest features
+            and bug fixes.
+          </Alert.Description>
+          <Button className="mt-2 sm:hidden" size="sm" variant="primary">
+            Refresh
+          </Button>
+        </Alert.Content>
+        <Button className="hidden sm:block" size="sm" variant="primary">
+          Refresh
+        </Button>
+      </Alert>
+
+      {/* Danger - Error with detailed steps */}
+      <Alert status="danger">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Unable to connect to server</Alert.Title>
+          <Alert.Description>
+            We're experiencing connection issues. Please try the following:
+            <ul className="mt-2 list-inside list-disc space-y-1 text-sm">
+              <li>Check your internet connection</li>
+              <li>Refresh the page</li>
+              <li>Clear your browser cache</li>
+            </ul>
+          </Alert.Description>
+          <Button className="mt-2 sm:hidden" size="sm" variant="danger">
+            Retry
+          </Button>
+        </Alert.Content>
+        <Button className="hidden sm:block" size="sm" variant="danger">
+          Retry
+        </Button>
+      </Alert>
+
+      {/* Without description */}
+      <Alert status="success">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Profile updated successfully</Alert.Title>
+        </Alert.Content>
+        <CloseButton />
+      </Alert>
+
+      {/* Custom indicator - Loading state */}
+      <Alert status="accent">
+        <Alert.Indicator>
+          <Spinner size="sm" />
+        </Alert.Indicator>
+        <Alert.Content>
+          <Alert.Title>Processing your request</Alert.Title>
+          <Alert.Description>
+            Please wait while we sync your data. This may take a few moments.
+          </Alert.Description>
+        </Alert.Content>
+      </Alert>
+
+      {/* Without close button */}
+      <Alert status="warning">
+        <Alert.Indicator />
+        <Alert.Content>
+          <Alert.Title>Scheduled maintenance</Alert.Title>
+          <Alert.Description>
+            Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for
+            scheduled maintenance.
+          </Alert.Description>
+        </Alert.Content>
+      </Alert>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/alert/index.ts b/apps/docs/src/demos/en/alert/index.ts
new file mode 100644
index 0000000..2294750
--- /dev/null
+++ b/apps/docs/src/demos/en/alert/index.ts
@@ -0,0 +1 @@
+export {Basic} from "./basic";
diff --git a/apps/docs/src/demos/en/autocomplete/allows-empty-collection.tsx b/apps/docs/src/demos/en/autocomplete/allows-empty-collection.tsx
new file mode 100644
index 0000000..1eccf51
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/allows-empty-collection.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+
+export function AllowsEmptyCollection() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[256px]"
+      placeholder="Select one"
+      selectionMode="single"
+    >
+      <Label>State</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search states..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>} />
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/asynchronous-filtering.tsx b/apps/docs/src/demos/en/autocomplete/asynchronous-filtering.tsx
new file mode 100644
index 0000000..b388283
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/asynchronous-filtering.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, Spinner} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+import {cn} from "tailwind-variants";
+
+interface Character {
+  name: string;
+}
+
+export function AsynchronousFiltering() {
+  const list = useAsyncList<Character>({
+    async load({filterText, signal}) {
+      const res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, {
+        signal,
+      });
+
+      const json = await res.json();
+
+      return {
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[256px]"
+      placeholder="Search..."
+      selectionMode="single"
+    >
+      <Label>Search a Star Wars characters</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter inputValue={list.filterText} onInputChange={list.setFilterText}>
+          <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search characters..." />
+              <Spinner
+                size="sm"
+                className={cn("absolute top-1/2 right-2 -translate-y-1/2", {
+                  "pointer-events-none opacity-0": !list.isLoading,
+                })}
+              />
+              <SearchField.ClearButton
+                className={cn({"pointer-events-none opacity-0": !!list.isLoading})}
+              />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox
+            className="max-h-[420px] overflow-y-auto"
+            items={list.items}
+            renderEmptyState={() => <EmptyState>No results found</EmptyState>}
+          >
+            {(item: Character) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/controlled-open-state.tsx b/apps/docs/src/demos/en/autocomplete/controlled-open-state.tsx
new file mode 100644
index 0000000..44694e7
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/controlled-open-state.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {
+  Autocomplete,
+  Button,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [isOpen, setIsOpen] = useState(false);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <div className="space-y-4">
+      <Autocomplete
+        className="w-[256px]"
+        isOpen={isOpen}
+        placeholder="Select one"
+        selectionMode="single"
+        onOpenChange={setIsOpen}
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Autocomplete</Button>
+      <p className="text-sm text-muted">Autocomplete is {isOpen ? "open" : "closed"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/controlled.tsx b/apps/docs/src/demos/en/autocomplete/controlled.tsx
new file mode 100644
index 0000000..990d573
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/controlled.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const states = [
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "florida", name: "Florida"},
+    {id: "new-york", name: "New York"},
+    {id: "illinois", name: "Illinois"},
+    {id: "pennsylvania", name: "Pennsylvania"},
+  ];
+
+  const [state, setState] = useState<Key | null>("california");
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const selectedState = states.find((s) => s.id === state);
+
+  return (
+    <div className="space-y-2">
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select a state"
+        selectionMode="single"
+        value={state}
+        onChange={setState}
+      >
+        <Label>State (controlled)</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {states.map((state) => (
+                <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                  {state.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/custom-indicator.tsx b/apps/docs/src/demos/en/autocomplete/custom-indicator.tsx
new file mode 100644
index 0000000..ca3a003
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/custom-indicator.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function CustomIndicator() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select one"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>State</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator className="size-3">
+          <Icon icon="gravity-ui:chevrons-expand-vertical" />
+        </Autocomplete.Indicator>
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search states..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/default.tsx b/apps/docs/src/demos/en/autocomplete/default.tsx
new file mode 100644
index 0000000..043fa26
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/default.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export default function Default() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select states"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys: Key | Key[] | null) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>States to Visit</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}: any) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item: any) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey: Key) => {
+                    const item = items.find((s) => s.id === selectedItemKey);
+
+                    if (!item) return null;
+
+                    return (
+                      <Tag key={item.id} id={item.id}>
+                        {item.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/disabled.tsx b/apps/docs/src/demos/en/autocomplete/disabled.tsx
new file mode 100644
index 0000000..c8a783c
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/disabled.tsx
@@ -0,0 +1,96 @@
+"use client";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+
+export function Disabled() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const countries = [
+    {id: "argentina", name: "Argentina"},
+    {id: "venezuela", name: "Venezuela"},
+    {id: "japan", name: "Japan"},
+    {id: "france", name: "France"},
+    {id: "italy", name: "Italy"},
+    {id: "spain", name: "Spain"},
+  ];
+
+  return (
+    <div className="flex flex-col gap-4">
+      <Autocomplete
+        isDisabled
+        className="w-[256px]"
+        defaultValue="california"
+        placeholder="Select one"
+        selectionMode="single"
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+      <Autocomplete
+        isDisabled
+        className="w-[256px]"
+        defaultValue={["argentina", "japan", "france"]}
+        placeholder="Select countries"
+        selectionMode="multiple"
+      >
+        <Label>Countries to Visit</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search countries..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {countries.map((country) => (
+                <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                  {country.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/email-recipients.tsx b/apps/docs/src/demos/en/autocomplete/email-recipients.tsx
new file mode 100644
index 0000000..ea289f9
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/email-recipients.tsx
@@ -0,0 +1,98 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function EmailRecipients() {
+  const emails = [
+    {email: "alice@example.com", id: "alice@example.com", name: "Alice Johnson"},
+    {email: "bob@example.com", id: "bob@example.com", name: "Bob Smith"},
+    {email: "charlie@example.com", id: "charlie@example.com", name: "Charlie Brown"},
+    {email: "diana@example.com", id: "diana@example.com", name: "Diana Prince"},
+    {email: "eve@example.com", id: "eve@example.com", name: "Eve Wilson"},
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Add recipients"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>To</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const email = emails.find((e) => e.id === selectedItemKey);
+
+                    if (!email) return null;
+
+                    return (
+                      <Tag key={email.id} id={email.id}>
+                        {email.email}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search emails..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No recipients found</EmptyState>}>
+            {emails.map((email) => (
+              <ListBox.Item key={email.id} id={email.id} textValue={email.email}>
+                <div className="flex flex-col">
+                  <Label>{email.name}</Label>
+                  <Description>{email.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/full-width.tsx b/apps/docs/src/demos/en/autocomplete/full-width.tsx
new file mode 100644
index 0000000..194cef5
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/full-width.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Surface,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function FullWidth() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Surface className="w-[380px] space-y-4 rounded-3xl p-6">
+      <Autocomplete
+        fullWidth
+        placeholder="Select one"
+        selectionMode="single"
+        value={selectedKey}
+        variant="secondary"
+        onChange={setSelectedKey}
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/index.ts b/apps/docs/src/demos/en/autocomplete/index.ts
new file mode 100644
index 0000000..16f5774
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/index.ts
@@ -0,0 +1,22 @@
+// Autocomplete demos
+export {AllowsEmptyCollection} from "./allows-empty-collection";
+export {AsynchronousFiltering} from "./asynchronous-filtering";
+export {Controlled} from "./controlled";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomIndicator} from "./custom-indicator";
+export {default as Default} from "./default";
+export {Disabled} from "./disabled";
+export {EmailRecipients} from "./email-recipients";
+export {FullWidth} from "./full-width";
+export {LocationSearch} from "./location-search";
+export {MultipleSelect} from "./multiple-select";
+export {Required} from "./required";
+export {default as SingleSelect} from "./single-select";
+export {TagGroupSelection} from "./tag-group-selection";
+export {UserSelection} from "./user-selection";
+export {UserSelectionMultiple} from "./user-selection-multiple";
+export {Variants} from "./variants";
+export {Virtualization} from "./virtualization";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/en/autocomplete/location-search.tsx b/apps/docs/src/demos/en/autocomplete/location-search.tsx
new file mode 100644
index 0000000..df0930b
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/location-search.tsx
@@ -0,0 +1,90 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+interface City {
+  name: string;
+  country: string;
+}
+
+export function LocationSearch() {
+  const allCities: City[] = [
+    {country: "USA", name: "New York"},
+    {country: "USA", name: "Los Angeles"},
+    {country: "USA", name: "Chicago"},
+    {country: "UK", name: "London"},
+    {country: "France", name: "Paris"},
+    {country: "Japan", name: "Tokyo"},
+    {country: "Australia", name: "Sydney"},
+    {country: "Canada", name: "Toronto"},
+    {country: "Germany", name: "Berlin"},
+    {country: "Spain", name: "Madrid"},
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  // Simulate async filtering
+  const customFilter = (text: string, inputValue: string) => {
+    if (!inputValue) return true;
+    setIsLoading(true);
+    setTimeout(() => setIsLoading(false), 300);
+
+    return contains(text, inputValue);
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Search for a city"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>City</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={customFilter}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search cities..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox
+            renderEmptyState={() => (
+              <EmptyState>{isLoading ? "Searching..." : "No cities found"}</EmptyState>
+            )}
+          >
+            {allCities.map((city) => (
+              <ListBox.Item key={city.name} id={city.name} textValue={city.name}>
+                <div className="flex flex-col">
+                  <Label>{city.name}</Label>
+                  <Description>{city.country}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/multiple-select.tsx b/apps/docs/src/demos/en/autocomplete/multiple-select.tsx
new file mode 100644
index 0000000..465523d
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/multiple-select.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function MultipleSelect() {
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "florida", name: "Florida"},
+    {id: "new-york", name: "New York"},
+    {id: "illinois", name: "Illinois"},
+    {id: "pennsylvania", name: "Pennsylvania"},
+  ];
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select states"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>States</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const item = items.find((s) => s.id === selectedItemKey);
+
+                    if (!item) return null;
+
+                    return (
+                      <Tag key={item.id} id={item.id}>
+                        {item.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/required.tsx b/apps/docs/src/demos/en/autocomplete/required.tsx
new file mode 100644
index 0000000..73ae616
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/required.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import {
+  Autocomplete,
+  Button,
+  EmptyState,
+  FieldError,
+  Form,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const states = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  const countries = [
+    {id: "usa", name: "United States"},
+    {id: "canada", name: "Canada"},
+    {id: "mexico", name: "Mexico"},
+    {id: "uk", name: "United Kingdom"},
+    {id: "france", name: "France"},
+    {id: "germany", name: "Germany"},
+  ];
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <Autocomplete
+        isRequired
+        className="w-full"
+        name="state"
+        placeholder="Select one"
+        selectionMode="single"
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {states.map((state) => (
+                <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                  {state.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+        <FieldError />
+      </Autocomplete>
+      <Autocomplete
+        isRequired
+        className="w-full"
+        name="country"
+        placeholder="Select a country"
+        selectionMode="single"
+      >
+        <Label>Country</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search countries..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {countries.map((country) => (
+                <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                  {country.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+        <FieldError />
+      </Autocomplete>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/single-select.tsx b/apps/docs/src/demos/en/autocomplete/single-select.tsx
new file mode 100644
index 0000000..487e4fd
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/single-select.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export default function SingleSelect() {
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+
+  const items = [
+    {id: "cat", name: "Cat"},
+    {id: "dog", name: "Dog"},
+    {id: "elephant", name: "Elephant"},
+    {id: "lion", name: "Lion"},
+    {id: "tiger", name: "Tiger"},
+    {id: "giraffe", name: "Giraffe"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select an animal"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>Favorite Animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search animals..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/tag-group-selection.tsx b/apps/docs/src/demos/en/autocomplete/tag-group-selection.tsx
new file mode 100644
index 0000000..dca0537
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/tag-group-selection.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupSelection() {
+  const tags = [
+    {id: "react", name: "React"},
+    {id: "typescript", name: "TypeScript"},
+    {id: "javascript", name: "JavaScript"},
+    {id: "nodejs", name: "Node.js"},
+    {id: "python", name: "Python"},
+    {id: "vue", name: "Vue"},
+    {id: "angular", name: "Angular"},
+    {id: "nextjs", name: "Next.js"},
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select tags"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>Tags</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const tag = tags.find((t) => t.id === selectedItemKey);
+
+                    if (!tag) return null;
+
+                    return (
+                      <Tag key={tag.id} id={tag.id}>
+                        {tag.name}
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search tags..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No tags found</EmptyState>}>
+            {tags.map((tag) => (
+              <ListBox.Item key={tag.id} id={tag.id} textValue={tag.name}>
+                {tag.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/user-selection-multiple.tsx b/apps/docs/src/demos/en/autocomplete/user-selection-multiple.tsx
new file mode 100644
index 0000000..8fa4d7c
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/user-selection-multiple.tsx
@@ -0,0 +1,142 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function UserSelectionMultiple() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      defaultValue={["1", "2"]}
+      placeholder="Select your teammates"
+      selectionMode="multiple"
+      value={selectedKeys}
+      onChange={(keys) => setSelectedKeys(keys as Key[])}
+    >
+      <Label>Users</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return (
+              <TagGroup size="sm" onRemove={onRemoveTags}>
+                <TagGroup.List>
+                  {selectedItemsKeys.map((selectedItemKey) => {
+                    const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+                    if (!selectedItem) {
+                      return null;
+                    }
+
+                    return (
+                      <Tag key={selectedItem.id} id={selectedItem.id}>
+                        <Avatar className="size-4" size="sm">
+                          <AvatarImage src={selectedItem.avatarUrl} />
+                          <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                        </Avatar>
+                        <span>{selectedItem.name}</span>
+                      </Tag>
+                    );
+                  })}
+                </TagGroup.List>
+              </TagGroup>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search users..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/user-selection.tsx b/apps/docs/src/demos/en/autocomplete/user-selection.tsx
new file mode 100644
index 0000000..54f7015
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/user-selection.tsx
@@ -0,0 +1,131 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function UserSelection() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select a user"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>User</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItems = state.selectedItems;
+
+            if (selectedItems.length > 1) {
+              return `${selectedItems.length} users selected`;
+            }
+
+            const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
+
+            if (!selectedItem) {
+              return defaultChildren;
+            }
+
+            return (
+              <div className="flex items-center gap-2">
+                <Avatar className="size-4" size="sm">
+                  <AvatarImage src={selectedItem.avatarUrl} />
+                  <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                </Avatar>
+                <span>{selectedItem.name}</span>
+              </div>
+            );
+          }}
+        </Autocomplete.Value>
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search users..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/variants.tsx b/apps/docs/src/demos/en/autocomplete/variants.tsx
new file mode 100644
index 0000000..1193215
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/variants.tsx
@@ -0,0 +1,241 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  Tag,
+  TagGroup,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function Variants() {
+  const [selectedKey1, setSelectedKey1] = useState<Key | null>(null);
+  const [selectedKey2, setSelectedKey2] = useState<Key | null>(null);
+  const [selectedKeys1, setSelectedKeys1] = useState<Key[]>([]);
+  const [selectedKeys2, setSelectedKeys2] = useState<Key[]>([]);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "option1", name: "Option 1"},
+    {id: "option2", name: "Option 2"},
+    {id: "option3", name: "Option 3"},
+    {id: "option4", name: "Option 4"},
+  ];
+
+  const onRemoveTags1 = (keys: Set<Key>) => {
+    setSelectedKeys1((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  const onRemoveTags2 = (keys: Set<Key>) => {
+    setSelectedKeys2((prev) => prev.filter((key) => !keys.has(key)));
+  };
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-4">
+        <h3 className="text-lg font-semibold">Single Select Variants</h3>
+        <div className="flex flex-col gap-4">
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="Select one"
+            selectionMode="single"
+            value={selectedKey1}
+            variant="primary"
+            onChange={setSelectedKey1}
+          >
+            <Label>Primary variant</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value />
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="Search..." />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="Select one"
+            selectionMode="single"
+            value={selectedKey2}
+            variant="secondary"
+            onChange={setSelectedKey2}
+          >
+            <Label>Secondary variant</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value />
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="Search..." />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+        </div>
+      </div>
+      <div className="flex flex-col gap-4">
+        <h3 className="text-lg font-semibold">Multiple Select Variants</h3>
+        <div className="flex flex-col gap-4">
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="Select multiple"
+            selectionMode="multiple"
+            value={selectedKeys1}
+            variant="primary"
+            onChange={(keys) => setSelectedKeys1(keys as Key[])}
+          >
+            <Label>Primary variant</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value>
+                {({defaultChildren, isPlaceholder, state}) => {
+                  if (isPlaceholder || state.selectedItems.length === 0) {
+                    return defaultChildren;
+                  }
+
+                  const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                  return (
+                    <TagGroup size="sm" onRemove={onRemoveTags1}>
+                      <TagGroup.List>
+                        {selectedItemsKeys.map((selectedItemKey) => {
+                          const item = items.find((s) => s.id === selectedItemKey);
+
+                          if (!item) return null;
+
+                          return (
+                            <Tag key={item.id} id={item.id}>
+                              {item.name}
+                            </Tag>
+                          );
+                        })}
+                      </TagGroup.List>
+                    </TagGroup>
+                  );
+                }}
+              </Autocomplete.Value>
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="Search..." />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+          <Autocomplete
+            className="w-[256px]"
+            placeholder="Select multiple"
+            selectionMode="multiple"
+            value={selectedKeys2}
+            variant="secondary"
+            onChange={(keys) => setSelectedKeys2(keys as Key[])}
+          >
+            <Label>Secondary variant</Label>
+            <Autocomplete.Trigger>
+              <Autocomplete.Value>
+                {({defaultChildren, isPlaceholder, state}) => {
+                  if (isPlaceholder || state.selectedItems.length === 0) {
+                    return defaultChildren;
+                  }
+
+                  const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                  return (
+                    <TagGroup size="sm" variant="surface" onRemove={onRemoveTags2}>
+                      <TagGroup.List>
+                        {selectedItemsKeys.map((selectedItemKey) => {
+                          const item = items.find((s) => s.id === selectedItemKey);
+
+                          if (!item) return null;
+
+                          return (
+                            <Tag key={item.id} id={item.id}>
+                              {item.name}
+                            </Tag>
+                          );
+                        })}
+                      </TagGroup.List>
+                    </TagGroup>
+                  );
+                }}
+              </Autocomplete.Value>
+              <Autocomplete.ClearButton />
+              <Autocomplete.Indicator />
+            </Autocomplete.Trigger>
+            <Autocomplete.Popover>
+              <Autocomplete.Filter filter={contains}>
+                <SearchField autoFocus name="search" variant="secondary">
+                  <SearchField.Group>
+                    <SearchField.SearchIcon />
+                    <SearchField.Input placeholder="Search..." />
+                    <SearchField.ClearButton />
+                  </SearchField.Group>
+                </SearchField>
+                <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                  {items.map((item) => (
+                    <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                      {item.name}
+                      <ListBox.ItemIndicator />
+                    </ListBox.Item>
+                  ))}
+                </ListBox>
+              </Autocomplete.Filter>
+            </Autocomplete.Popover>
+          </Autocomplete>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/virtualization.tsx b/apps/docs/src/demos/en/autocomplete/virtualization.tsx
new file mode 100644
index 0000000..81e54d1
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/virtualization.tsx
@@ -0,0 +1,145 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  ListLayout,
+  SearchField,
+  Virtualizer,
+  useFilter,
+} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  email: string;
+  id: number;
+  name: string;
+}
+
+function generateUsers(n: number): User[] {
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+  const users: User[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const firstName = firstNames[i % firstNames.length]!;
+    const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!;
+    const name = `${firstName} ${lastName}`;
+
+    users.push({
+      email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
+      id: i + 1,
+      name,
+    });
+  }
+
+  return users;
+}
+
+export function Virtualization() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const [searchQuery, setSearchQuery] = useState("");
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const allUsers = useMemo(() => generateUsers(1000), []);
+
+  const filteredUsers = useMemo(() => {
+    if (!searchQuery) return allUsers;
+
+    return allUsers.filter(
+      (user) => contains(user.name, searchQuery) || contains(user.email, searchQuery),
+    );
+  }, [allUsers, contains, searchQuery]);
+
+  return (
+    <Autocomplete
+      allowsEmptyCollection
+      className="w-[300px]"
+      placeholder="Select a user"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>User</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter inputValue={searchQuery} onInputChange={setSearchQuery}>
+          <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search users..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+            <ListBox
+              items={filteredUsers}
+              renderEmptyState={() => <EmptyState>No results found</EmptyState>}
+            >
+              {(user) => (
+                <ListBox.Item id={user.id} textValue={user.name}>
+                  <div className="flex flex-col">
+                    <Label>{user.name}</Label>
+                    <Description>{user.email}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              )}
+            </ListBox>
+          </Virtualizer>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/with-description.tsx b/apps/docs/src/demos/en/autocomplete/with-description.tsx
new file mode 100644
index 0000000..0bd6016
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/with-description.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  Description,
+  EmptyState,
+  Label,
+  ListBox,
+  SearchField,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function WithDescription() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  const items = [
+    {id: "florida", name: "Florida"},
+    {id: "delaware", name: "Delaware"},
+    {id: "california", name: "California"},
+    {id: "texas", name: "Texas"},
+    {id: "new-york", name: "New York"},
+    {id: "washington", name: "Washington"},
+  ];
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select one"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>State</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search states..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            {items.map((item) => (
+              <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+      <Description>Select your state of residence</Description>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/with-disabled-options.tsx b/apps/docs/src/demos/en/autocomplete/with-disabled-options.tsx
new file mode 100644
index 0000000..ff37536
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/with-disabled-options.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react";
+import {useState} from "react";
+
+export function WithDisabledOptions() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      disabledKeys={["cat", "kangaroo"]}
+      placeholder="Select an animal"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>Animal</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search animals..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="bird" textValue="Bird">
+              Bird
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="Kangaroo">
+              Kangaroo
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="elephant" textValue="Elephant">
+              Elephant
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="tiger" textValue="Tiger">
+              Tiger
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/autocomplete/with-sections.tsx b/apps/docs/src/demos/en/autocomplete/with-sections.tsx
new file mode 100644
index 0000000..75fa59b
--- /dev/null
+++ b/apps/docs/src/demos/en/autocomplete/with-sections.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {
+  Autocomplete,
+  EmptyState,
+  Header,
+  Label,
+  ListBox,
+  SearchField,
+  Separator,
+  useFilter,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSections() {
+  const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+  const {contains} = useFilter({sensitivity: "base"});
+
+  return (
+    <Autocomplete
+      className="w-[256px]"
+      placeholder="Select a country"
+      selectionMode="single"
+      value={selectedKey}
+      onChange={setSelectedKey}
+    >
+      <Label>Country</Label>
+      <Autocomplete.Trigger>
+        <Autocomplete.Value />
+        <Autocomplete.ClearButton />
+        <Autocomplete.Indicator />
+      </Autocomplete.Trigger>
+      <Autocomplete.Popover>
+        <Autocomplete.Filter filter={contains}>
+          <SearchField autoFocus name="search" variant="secondary">
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input placeholder="Search countries..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+          </SearchField>
+          <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+            <ListBox.Section>
+              <Header>North America</Header>
+              <ListBox.Item id="usa" textValue="United States">
+                United States
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="Canada">
+                Canada
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="mexico" textValue="Mexico">
+                Mexico
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+            <Separator />
+            <ListBox.Section>
+              <Header>Europe</Header>
+              <ListBox.Item id="uk" textValue="United Kingdom">
+                United Kingdom
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="france" textValue="France">
+                France
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="Germany">
+                Germany
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="spain" textValue="Spain">
+                Spain
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="italy" textValue="Italy">
+                Italy
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+            <Separator />
+            <ListBox.Section>
+              <Header>Asia</Header>
+              <ListBox.Item id="japan" textValue="Japan">
+                Japan
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="china" textValue="China">
+                China
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="india" textValue="India">
+                India
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="south-korea" textValue="South Korea">
+                South Korea
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox.Section>
+          </ListBox>
+        </Autocomplete.Filter>
+      </Autocomplete.Popover>
+    </Autocomplete>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/basic.tsx b/apps/docs/src/demos/en/avatar/basic.tsx
new file mode 100644
index 0000000..3a3f39e
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/basic.tsx
@@ -0,0 +1,22 @@
+import {Avatar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar>
+        <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar>
+      <Avatar>
+        <Avatar.Image
+          alt="Blue"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>B</Avatar.Fallback>
+      </Avatar>
+      <Avatar>
+        <Avatar.Fallback>JR</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/colors.tsx b/apps/docs/src/demos/en/avatar/colors.tsx
new file mode 100644
index 0000000..9ca40a8
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/colors.tsx
@@ -0,0 +1,23 @@
+import {Avatar} from "@heroui/react";
+
+export function Colors() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar color="default">
+        <Avatar.Fallback>DF</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="accent">
+        <Avatar.Fallback>AC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="success">
+        <Avatar.Fallback>SC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="warning">
+        <Avatar.Fallback>WR</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="danger">
+        <Avatar.Fallback>DG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/custom-styles.tsx b/apps/docs/src/demos/en/avatar/custom-styles.tsx
new file mode 100644
index 0000000..33c14d7
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/custom-styles.tsx
@@ -0,0 +1,49 @@
+import {Avatar} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <div className="flex items-center gap-4">
+      {/* Custom size with Tailwind classes */}
+      <Avatar className="size-16">
+        <Avatar.Image
+          alt="Extra Large"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>XL</Avatar.Fallback>
+      </Avatar>
+
+      {/* Square avatar */}
+      <Avatar className="rounded-lg">
+        <Avatar.Image
+          alt="Square Avatar"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+        />
+        <Avatar.Fallback className="rounded-lg">SQ</Avatar.Fallback>
+      </Avatar>
+
+      {/* Gradient border */}
+      <Avatar className="bg-gradient-to-tr from-pink-500 to-yellow-500 p-0.5">
+        <div className="size-full rounded-full bg-background p-0.5">
+          <Avatar.Image
+            alt="Gradient Border"
+            className="rounded-full"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+          />
+          <Avatar.Fallback className="border-none">GB</Avatar.Fallback>
+        </div>
+      </Avatar>
+
+      {/* Status indicator */}
+      <div className="relative">
+        <Avatar>
+          <Avatar.Image
+            alt="Online User"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+          />
+          <Avatar.Fallback>ON</Avatar.Fallback>
+        </Avatar>
+        <span className="absolute right-0 bottom-0 size-3 rounded-full bg-green-500 ring-2 ring-background" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/fallback.tsx b/apps/docs/src/demos/en/avatar/fallback.tsx
new file mode 100644
index 0000000..5e8b468
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/fallback.tsx
@@ -0,0 +1,36 @@
+import {Person} from "@gravity-ui/icons";
+import {Avatar} from "@heroui/react";
+
+export function Fallback() {
+  return (
+    <div className="flex items-center gap-4">
+      {/* Text fallback */}
+      <Avatar>
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar>
+
+      {/* Icon fallback */}
+      <Avatar>
+        <Avatar.Fallback>
+          <Person />
+        </Avatar.Fallback>
+      </Avatar>
+
+      {/* Fallback with delay */}
+      <Avatar>
+        <Avatar.Image
+          alt="Delayed Avatar"
+          src="https://invalid-url-to-show-fallback.com/image.jpg"
+        />
+        <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+      </Avatar>
+
+      {/* Custom styled fallback */}
+      <Avatar>
+        <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white">
+          GB
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/group.tsx b/apps/docs/src/demos/en/avatar/group.tsx
new file mode 100644
index 0000000..3e27138
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/group.tsx
@@ -0,0 +1,68 @@
+import {Avatar} from "@heroui/react";
+
+const users = [
+  {
+    id: 1,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "John Doe",
+  },
+  {
+    id: 2,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "Kate Wilson",
+  },
+  {
+    id: 3,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "Emily Chen",
+  },
+  {
+    id: 4,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "Michael Brown",
+  },
+  {
+    id: 5,
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "Olivia Davis",
+  },
+];
+
+export function Group() {
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Basic avatar group */}
+      <div className="flex -space-x-2">
+        {users.slice(0, 4).map((user) => (
+          <Avatar key={user.id} className="ring-2 ring-background">
+            <Avatar.Image alt={user.name} src={user.image} />
+            <Avatar.Fallback>
+              {user.name
+                .split(" ")
+                .map((n) => n[0])
+                .join("")}
+            </Avatar.Fallback>
+          </Avatar>
+        ))}
+      </div>
+
+      {/* Avatar group with counter */}
+      <div className="flex -space-x-2">
+        {users.slice(0, 3).map((user) => (
+          <Avatar key={user.id} className="ring-2 ring-background">
+            <Avatar.Image alt={user.name} src={user.image} />
+            <Avatar.Fallback>
+              {user.name
+                .split(" ")
+                .map((n) => n[0])
+                .join("")}
+            </Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="text-xs">+{users.length - 3}</Avatar.Fallback>
+        </Avatar>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/index.ts b/apps/docs/src/demos/en/avatar/index.ts
new file mode 100644
index 0000000..7e10954
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomStyles} from "./custom-styles";
+export {Fallback} from "./fallback";
+export {Group} from "./group";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/avatar/sizes.tsx b/apps/docs/src/demos/en/avatar/sizes.tsx
new file mode 100644
index 0000000..5f853cc
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/sizes.tsx
@@ -0,0 +1,29 @@
+import {Avatar} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar size="sm">
+        <Avatar.Image
+          alt="Small Avatar"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+        />
+        <Avatar.Fallback>SM</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="md">
+        <Avatar.Image
+          alt="Medium Avatar"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+        />
+        <Avatar.Fallback>MD</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="lg">
+        <Avatar.Image
+          alt="Large Avatar"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+        />
+        <Avatar.Fallback>LG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/avatar/variants.tsx b/apps/docs/src/demos/en/avatar/variants.tsx
new file mode 100644
index 0000000..a241935
--- /dev/null
+++ b/apps/docs/src/demos/en/avatar/variants.tsx
@@ -0,0 +1,63 @@
+import {Person} from "@gravity-ui/icons";
+import {Avatar, Separator} from "@heroui/react";
+
+export function Variants() {
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+  const variants = [
+    {content: "AG", label: "letter", type: "letter"},
+    {content: "AG", label: "letter soft", type: "letter-soft"},
+    {content: <Person />, label: "icon", type: "icon"},
+    {content: <Person />, label: "icon soft", type: "icon-soft"},
+    {
+      content: [
+        "https://img.heroui.chat/image/avatar?w=400&h=400&u=3",
+        "https://img.heroui.chat/image/avatar?w=400&h=400&u=4",
+        "https://img.heroui.chat/image/avatar?w=400&h=400&u=5",
+        "https://img.heroui.chat/image/avatar?w=400&h=400&u=8",
+        "https://img.heroui.chat/image/avatar?w=400&h=400&u=16",
+      ],
+      label: "img",
+      type: "img",
+    },
+  ] as const;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Color labels header */}
+      <div className="flex items-center gap-3">
+        <div className="w-24 shrink-0" />
+        {colors.map((color) => (
+          <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+            <span className="text-xs text-muted capitalize">{color}</span>
+          </div>
+        ))}
+      </div>
+
+      <Separator />
+
+      {/* Variant rows */}
+      {variants.map((variant) => (
+        <div key={variant.label} className="flex items-center gap-3">
+          <div className="w-24 shrink-0 text-sm text-muted">{variant.label}</div>
+          {colors.map((color, colorIndex) => (
+            <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+              <Avatar color={color} variant={variant.type.includes("soft") ? "soft" : undefined}>
+                {variant.type === "img" ? (
+                  <>
+                    <Avatar.Image
+                      alt={`Avatar ${color}`}
+                      src={Array.isArray(variant.content) ? variant.content[colorIndex] : ""}
+                    />
+                    <Avatar.Fallback>{color.charAt(0).toUpperCase()}</Avatar.Fallback>
+                  </>
+                ) : (
+                  <Avatar.Fallback>{variant.content}</Avatar.Fallback>
+                )}
+              </Avatar>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/basic.tsx b/apps/docs/src/demos/en/badge/basic.tsx
new file mode 100644
index 0000000..08c751d
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/basic.tsx
@@ -0,0 +1,40 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const GREEN_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+const ORANGE_AVATAR_URL =
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg";
+const BLUE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg";
+
+export function BadgeBasic() {
+  return (
+    <div className="flex items-center gap-6">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={GREEN_AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          5
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={ORANGE_AVATAR_URL} />
+          <Avatar.Fallback>AB</Avatar.Fallback>
+        </Avatar>
+        <Badge color="accent" size="sm">
+          New
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={BLUE_AVATAR_URL} />
+          <Avatar.Fallback>CD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="success" placement="bottom-right" size="sm" />
+      </Badge.Anchor>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/colors.tsx b/apps/docs/src/demos/en/badge/colors.tsx
new file mode 100644
index 0000000..d914deb
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/colors.tsx
@@ -0,0 +1,21 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeColors() {
+  const colors = ["default", "accent", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {colors.map((color) => (
+        <Badge.Anchor key={color}>
+          <Avatar>
+            <Avatar.Image src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color={color} size="sm" />
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/dot.tsx b/apps/docs/src/demos/en/badge/dot.tsx
new file mode 100644
index 0000000..24f7297
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/dot.tsx
@@ -0,0 +1,21 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeDot() {
+  const colors = ["accent", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {colors.map((color) => (
+        <Badge.Anchor key={color}>
+          <Avatar>
+            <Avatar.Image src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color={color} placement="bottom-right" size="sm" />
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/index.ts b/apps/docs/src/demos/en/badge/index.ts
new file mode 100644
index 0000000..5b791ac
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/index.ts
@@ -0,0 +1,7 @@
+export {BadgeBasic as Basic} from "./basic";
+export {BadgeColors as Colors} from "./colors";
+export {BadgeDot as Dot} from "./dot";
+export {BadgePlacements as Placements} from "./placements";
+export {BadgeSizes as Sizes} from "./sizes";
+export {BadgeVariants as Variants} from "./variants";
+export {BadgeWithContent as WithContent} from "./with-content";
diff --git a/apps/docs/src/demos/en/badge/placements.tsx b/apps/docs/src/demos/en/badge/placements.tsx
new file mode 100644
index 0000000..686c397
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/placements.tsx
@@ -0,0 +1,24 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgePlacements() {
+  const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
+
+  return (
+    <div className="flex items-center gap-8">
+      {placements.map((placement) => (
+        <div key={placement} className="flex flex-col items-center gap-2">
+          <Badge.Anchor>
+            <Avatar>
+              <Avatar.Image src={AVATAR_URL} />
+              <Avatar.Fallback>JD</Avatar.Fallback>
+            </Avatar>
+            <Badge color="accent" placement={placement} size="sm" />
+          </Badge.Anchor>
+          <span className="text-xs text-muted">{placement}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/sizes.tsx b/apps/docs/src/demos/en/badge/sizes.tsx
new file mode 100644
index 0000000..62e09e7
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/sizes.tsx
@@ -0,0 +1,23 @@
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeSizes() {
+  const sizes = ["sm", "md", "lg"] as const;
+
+  return (
+    <div className="flex items-center gap-6">
+      {sizes.map((size) => (
+        <Badge.Anchor key={size}>
+          <Avatar size={size}>
+            <Avatar.Image src={AVATAR_URL} />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+          <Badge color="danger" size={size}>
+            5
+          </Badge>
+        </Badge.Anchor>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/variants.tsx b/apps/docs/src/demos/en/badge/variants.tsx
new file mode 100644
index 0000000..7576e2a
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/variants.tsx
@@ -0,0 +1,35 @@
+import {Avatar, Badge, Separator} from "@heroui/react";
+import React from "react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeVariants() {
+  const variants = ["primary", "secondary", "soft"] as const;
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {variants.map((variant, index) => (
+        <React.Fragment key={variant}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted capitalize">{variant}</h3>
+            <div className="flex items-center gap-6">
+              {colors.map((color) => (
+                <Badge.Anchor key={color}>
+                  <Avatar>
+                    <Avatar.Image src={AVATAR_URL} />
+                    <Avatar.Fallback>JD</Avatar.Fallback>
+                  </Avatar>
+                  <Badge color={color} size="sm" variant={variant}>
+                    5
+                  </Badge>
+                </Badge.Anchor>
+              ))}
+            </div>
+          </div>
+          {index < variants.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/badge/with-content.tsx b/apps/docs/src/demos/en/badge/with-content.tsx
new file mode 100644
index 0000000..74dc882
--- /dev/null
+++ b/apps/docs/src/demos/en/badge/with-content.tsx
@@ -0,0 +1,50 @@
+import {Bell} from "@gravity-ui/icons";
+import {Avatar, Badge} from "@heroui/react";
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+export function BadgeWithContent() {
+  return (
+    <div className="flex items-center gap-6">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          5
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          New
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="danger" size="sm">
+          99+
+        </Badge>
+      </Badge.Anchor>
+
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar>
+        <Badge color="accent" size="sm">
+          <Bell className="size-2.5" />
+        </Badge>
+      </Badge.Anchor>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/basic.tsx b/apps/docs/src/demos/en/breadcrumbs/basic.tsx
new file mode 100644
index 0000000..620d901
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsBasic() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Laptop</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/custom-render-function.tsx b/apps/docs/src/demos/en/breadcrumbs/custom-render-function.tsx
new file mode 100644
index 0000000..7d36e62
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/custom-render-function.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Breadcrumbs render={(props) => <ol {...props} data-custom="foo" />}>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        Home
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        Products
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        Electronics
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}>
+        Laptop
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/custom-separator.tsx b/apps/docs/src/demos/en/breadcrumbs/custom-separator.tsx
new file mode 100644
index 0000000..991ee32
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/custom-separator.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsCustomSeparator() {
+  return (
+    <Breadcrumbs
+      separator={
+        <svg viewBox="0 0 256 512" xmlns="http://www.w3.org/2000/svg">
+          <path d="M249.3 235.8c10.2 12.6 9.5 31.1-2.2 42.8l-128 128c-9.2 9.2-22.9 11.9-34.9 6.9S64.5 396.9 64.5 384l0-256c0-12.9 7.8-24.6 19.8-29.6s25.7-2.2 34.9 6.9l128 128 2.2 2.4z" />
+        </svg>
+      }
+    >
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Laptop</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/disabled.tsx b/apps/docs/src/demos/en/breadcrumbs/disabled.tsx
new file mode 100644
index 0000000..15a23df
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/disabled.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsDisabled() {
+  return (
+    <Breadcrumbs isDisabled>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Laptop</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/index.ts b/apps/docs/src/demos/en/breadcrumbs/index.ts
new file mode 100644
index 0000000..545483b
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/index.ts
@@ -0,0 +1,6 @@
+export {default as BreadcrumbsBasic} from "./basic";
+export {default as BreadcrumbsLevel2} from "./level-2";
+export {default as BreadcrumbsLevel3} from "./level-3";
+export {default as BreadcrumbsCustomSeparator} from "./custom-separator";
+export {default as BreadcrumbsDisabled} from "./disabled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/breadcrumbs/level-2.tsx b/apps/docs/src/demos/en/breadcrumbs/level-2.tsx
new file mode 100644
index 0000000..3a89a0b
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/level-2.tsx
@@ -0,0 +1,12 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsLevel2() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Current Page</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/breadcrumbs/level-3.tsx b/apps/docs/src/demos/en/breadcrumbs/level-3.tsx
new file mode 100644
index 0000000..48b3be4
--- /dev/null
+++ b/apps/docs/src/demos/en/breadcrumbs/level-3.tsx
@@ -0,0 +1,13 @@
+"use client";
+
+import {Breadcrumbs} from "@heroui/react";
+
+export default function BreadcrumbsLevel3() {
+  return (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Current Page</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/basic.tsx b/apps/docs/src/demos/en/button-group/basic.tsx
new file mode 100644
index 0000000..a3f23bf
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/basic.tsx
@@ -0,0 +1,203 @@
+import {
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  CodeFork,
+  Ellipsis,
+  Picture,
+  Pin,
+  QrCode,
+  Star,
+  TextAlignCenter,
+  TextAlignJustify,
+  TextAlignLeft,
+  TextAlignRight,
+  ThumbsDown,
+  ThumbsUp,
+  Video,
+} from "@gravity-ui/icons";
+import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col items-start gap-6">
+      {/* Single button with dropdown */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup>
+          <Button>Merge pull request</Button>
+          <Dropdown>
+            <Button isIconOnly aria-label="More options">
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+            <Dropdown.Popover className="max-w-[290px]" placement="bottom end">
+              <Dropdown.Menu>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="merge"
+                  textValue="Create a merge commit"
+                >
+                  <Label>Create a merge commit</Label>
+                  <Description>
+                    All commits from this branch will be added to the base branch
+                  </Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="squash-and-merge"
+                  textValue="Squash and merge"
+                >
+                  <Label>Squash and merge</Label>
+                  <Description>
+                    The 14 commits from this branch will be combined into one commit in the base
+                    branch
+                  </Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="rebase-and-merge"
+                  textValue="Rebase and merge"
+                >
+                  <Label>Rebase and merge</Label>
+                  <Description>
+                    The 14 commits from this branch will be rebased and added to the base branch
+                  </Description>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown>
+        </ButtonGroup>
+      </div>
+
+      {/* Individual buttons */}
+      <div className="flex flex-col gap-2">
+        <div className="flex flex-wrap gap-x-2 gap-y-4">
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <CodeFork className="size-3.5" />
+              Fork
+              <Chip color="accent" size="sm" variant="soft">
+                24
+              </Chip>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button isIconOnly>
+              <QrCode />
+            </Button>
+            <Button>
+              <ButtonGroup.Separator />
+              Scan to pay
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <ThumbsUp />
+              <span className="text-xs font-semibold">2.4K</span>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ThumbsDown />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Star className="size-3.5" />
+              Star
+            </Button>
+            <Button className="px-2">
+              <ButtonGroup.Separator />
+              <Chip color="accent" size="sm" variant="soft">
+                104
+              </Chip>
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Pin />
+              Pinned
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <ChevronDown />
+            </Button>
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* Previous/Next Button Group */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <ChevronLeft />
+            Previous
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Next
+            <ChevronRight />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Content Selection Button Group */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <Picture />
+            Photos
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Video />
+            Videos
+          </Button>
+          <Button isIconOnly aria-label="More options">
+            <ButtonGroup.Separator />
+            <Ellipsis />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Text Alignment Button Group */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button>Left</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Center
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Right
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Icon-Only Alignment Button Group */}
+      <div className="flex flex-col gap-2">
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/disabled.tsx b/apps/docs/src/demos/en/button-group/disabled.tsx
new file mode 100644
index 0000000..559a127
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/disabled.tsx
@@ -0,0 +1,36 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">All buttons disabled</p>
+        <ButtonGroup isDisabled>
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">Group disabled, but one button overrides</p>
+        <ButtonGroup isDisabled>
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button isDisabled={false}>
+            <ButtonGroup.Separator />
+            Third (enabled)
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/full-width.tsx b/apps/docs/src/demos/en/button-group/full-width.tsx
new file mode 100644
index 0000000..4a1b9eb
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/full-width.tsx
@@ -0,0 +1,33 @@
+import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <ButtonGroup fullWidth>
+        <Button>First</Button>
+        <Button>
+          <ButtonGroup.Separator />
+          Second
+        </Button>
+        <Button>
+          <ButtonGroup.Separator />
+          Third
+        </Button>
+      </ButtonGroup>
+      <ButtonGroup fullWidth>
+        <Button isIconOnly>
+          <TextAlignLeft />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <TextAlignCenter />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <TextAlignRight />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/index.ts b/apps/docs/src/demos/en/button-group/index.ts
new file mode 100644
index 0000000..38d3b03
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/index.ts
@@ -0,0 +1,8 @@
+export {Basic} from "./basic";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Orientation} from "./orientation";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
+export {WithIcons} from "./with-icons";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/en/button-group/orientation.tsx b/apps/docs/src/demos/en/button-group/orientation.tsx
new file mode 100644
index 0000000..877cfa6
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/orientation.tsx
@@ -0,0 +1,49 @@
+import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Orientation() {
+  return (
+    <div className="flex items-start gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Horizontal</span>
+        <ButtonGroup orientation="horizontal" variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Vertical</span>
+        <ButtonGroup orientation="vertical" variant="tertiary">
+          <Button isIconOnly>
+            <TextAlignLeft />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignCenter />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignRight />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TextAlignJustify />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/sizes.tsx b/apps/docs/src/demos/en/button-group/sizes.tsx
new file mode 100644
index 0000000..1da0616
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/sizes.tsx
@@ -0,0 +1,50 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">Small</p>
+        <ButtonGroup size="sm" variant="secondary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">Medium (default)</p>
+        <ButtonGroup size="md" variant="secondary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">Large</p>
+        <ButtonGroup size="lg" variant="secondary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/variants.tsx b/apps/docs/src/demos/en/button-group/variants.tsx
new file mode 100644
index 0000000..9a0e87b
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/variants.tsx
@@ -0,0 +1,92 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Primary</p>
+        <ButtonGroup variant="primary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Secondary</p>
+        <ButtonGroup variant="secondary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Tertiary</p>
+        <ButtonGroup variant="tertiary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Outline</p>
+        <ButtonGroup variant="outline">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Ghost</p>
+        <ButtonGroup variant="ghost">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Danger</p>
+        <ButtonGroup variant="danger">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/with-icons.tsx b/apps/docs/src/demos/en/button-group/with-icons.tsx
new file mode 100644
index 0000000..8774315
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/with-icons.tsx
@@ -0,0 +1,44 @@
+import {Globe, Plus, TrashBin} from "@gravity-ui/icons";
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">With icons</p>
+        <ButtonGroup variant="secondary">
+          <Button>
+            <Globe />
+            Search
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Plus />
+            Add
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <TrashBin />
+            Delete
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col items-start gap-2">
+        <p className="text-sm text-muted">Icon only buttons</p>
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <Globe />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Plus />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <TrashBin />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button-group/without-separator.tsx b/apps/docs/src/demos/en/button-group/without-separator.tsx
new file mode 100644
index 0000000..35f88f8
--- /dev/null
+++ b/apps/docs/src/demos/en/button-group/without-separator.tsx
@@ -0,0 +1,11 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function WithoutSeparator() {
+  return (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/basic.tsx b/apps/docs/src/demos/en/button/basic.tsx
new file mode 100644
index 0000000..a4d4c3f
--- /dev/null
+++ b/apps/docs/src/demos/en/button/basic.tsx
@@ -0,0 +1,7 @@
+"use client";
+
+import {Button} from "@heroui/react";
+
+export function Basic() {
+  return <Button onPress={() => console.log("Button pressed")}>Click me</Button>;
+}
diff --git a/apps/docs/src/demos/en/button/custom-render-function.tsx b/apps/docs/src/demos/en/button/custom-render-function.tsx
new file mode 100644
index 0000000..5d13701
--- /dev/null
+++ b/apps/docs/src/demos/en/button/custom-render-function.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {Button} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Button
+      render={(props, {isPressed}) => (
+        <button {...props} data-custom={isPressed ? "pressed" : "bar"} />
+      )}
+    >
+      Press me
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/custom-variants.tsx b/apps/docs/src/demos/en/button/custom-variants.tsx
new file mode 100644
index 0000000..0ddabcd
--- /dev/null
+++ b/apps/docs/src/demos/en/button/custom-variants.tsx
@@ -0,0 +1,43 @@
+import type {ButtonProps} from "@heroui/react";
+import type {VariantProps} from "tailwind-variants";
+
+import {Button, buttonVariants} from "@heroui/react";
+import {tv} from "tailwind-variants";
+
+const myButtonVariants = tv({
+  base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
+  defaultVariants: {
+    radius: "full",
+    variant: "primary",
+  },
+  extend: buttonVariants,
+  variants: {
+    radius: {
+      full: "rounded-full",
+      lg: "rounded-lg",
+      md: "rounded-md",
+      sm: "rounded-sm",
+    },
+    size: {
+      lg: "h-12 px-8",
+      md: "h-11 px-6",
+      sm: "h-10 px-4",
+      xl: "h-13 px-10",
+    },
+    variant: {
+      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
+    },
+  },
+});
+
+type MyButtonVariants = VariantProps<typeof myButtonVariants>;
+export type MyButtonProps = Omit<ButtonProps, "className"> &
+  MyButtonVariants & {className?: string};
+
+function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
+  return <Button className={myButtonVariants({className, radius, variant})} {...props} />;
+}
+
+export function CustomVariants() {
+  return <CustomButton>Custom Button</CustomButton>;
+}
diff --git a/apps/docs/src/demos/en/button/disabled.tsx b/apps/docs/src/demos/en/button/disabled.tsx
new file mode 100644
index 0000000..6594ebb
--- /dev/null
+++ b/apps/docs/src/demos/en/button/disabled.tsx
@@ -0,0 +1,24 @@
+import {Button} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button isDisabled>Primary</Button>
+      <Button isDisabled variant="secondary">
+        Secondary
+      </Button>
+      <Button isDisabled variant="tertiary">
+        Tertiary
+      </Button>
+      <Button isDisabled variant="outline">
+        Outline
+      </Button>
+      <Button isDisabled variant="ghost">
+        Ghost
+      </Button>
+      <Button isDisabled variant="danger">
+        Danger
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/full-width.tsx b/apps/docs/src/demos/en/button/full-width.tsx
new file mode 100644
index 0000000..f99a517
--- /dev/null
+++ b/apps/docs/src/demos/en/button/full-width.tsx
@@ -0,0 +1,14 @@
+import {Plus} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <Button fullWidth>Primary Button</Button>
+      <Button fullWidth>
+        <Plus />
+        With Icon
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/icon-only.tsx b/apps/docs/src/demos/en/button/icon-only.tsx
new file mode 100644
index 0000000..e564ad9
--- /dev/null
+++ b/apps/docs/src/demos/en/button/icon-only.tsx
@@ -0,0 +1,18 @@
+import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function IconOnly() {
+  return (
+    <div className="flex gap-3">
+      <Button isIconOnly variant="tertiary">
+        <Ellipsis />
+      </Button>
+      <Button isIconOnly variant="secondary">
+        <Gear />
+      </Button>
+      <Button isIconOnly variant="danger">
+        <TrashBin />
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/index.ts b/apps/docs/src/demos/en/button/index.ts
new file mode 100644
index 0000000..882d2b4
--- /dev/null
+++ b/apps/docs/src/demos/en/button/index.ts
@@ -0,0 +1,15 @@
+// Button demos
+export {Basic} from "./basic";
+export {CustomVariants} from "./custom-variants";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {IconOnly} from "./icon-only";
+export {Loading} from "./loading";
+export {LoadingState} from "./loading-state";
+export {OutlineVariant} from "./outline-variant";
+export {Sizes} from "./sizes";
+export {Social} from "./social";
+export {Variants} from "./variants";
+export {WithIcons} from "./with-icons";
+export {RippleEffect} from "./ripple-effect";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/button/loading-state.tsx b/apps/docs/src/demos/en/button/loading-state.tsx
new file mode 100644
index 0000000..dcf88eb
--- /dev/null
+++ b/apps/docs/src/demos/en/button/loading-state.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Paperclip} from "@gravity-ui/icons";
+import {Button, Spinner} from "@heroui/react";
+import React, {useState} from "react";
+
+export function LoadingState() {
+  const [isLoading, setLoading] = useState(false);
+
+  const handlePress = () => {
+    setLoading(true);
+    setTimeout(() => setLoading(false), 2000);
+  };
+
+  return (
+    <Button isPending={isLoading} onPress={handlePress}>
+      {({isPending}) => (
+        <>
+          {isPending ? <Spinner color="current" size="sm" /> : <Paperclip />}
+          {isPending ? "Uploading..." : "Upload File"}
+        </>
+      )}
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/loading.tsx b/apps/docs/src/demos/en/button/loading.tsx
new file mode 100644
index 0000000..f0a8f65
--- /dev/null
+++ b/apps/docs/src/demos/en/button/loading.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Button, Spinner} from "@heroui/react";
+import React from "react";
+
+export function Loading() {
+  return (
+    <Button isPending>
+      {({isPending}) => (
+        <>
+          {isPending ? <Spinner color="current" size="sm" /> : null}
+          Uploading...
+        </>
+      )}
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/outline-variant.tsx b/apps/docs/src/demos/en/button/outline-variant.tsx
new file mode 100644
index 0000000..d5ea900
--- /dev/null
+++ b/apps/docs/src/demos/en/button/outline-variant.tsx
@@ -0,0 +1,22 @@
+import {Button, ButtonGroup} from "@heroui/react";
+
+export function OutlineVariant() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Button</p>
+        <div className="flex flex-wrap gap-3">
+          <Button variant="outline">Outline</Button>
+        </div>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">ButtonGroup</p>
+        <ButtonGroup variant="outline">
+          <Button>First</Button>
+          <Button>Second</Button>
+          <Button>Third</Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/ripple-effect.tsx b/apps/docs/src/demos/en/button/ripple-effect.tsx
new file mode 100644
index 0000000..7b1e739
--- /dev/null
+++ b/apps/docs/src/demos/en/button/ripple-effect.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {Button} from "@heroui/react";
+import {Ripple} from "m3-ripple";
+
+import "m3-ripple/ripple.css";
+
+export function RippleEffect() {
+  return (
+    <Button variant="secondary">
+      <Ripple />
+      Click me
+    </Button>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/sizes.tsx b/apps/docs/src/demos/en/button/sizes.tsx
new file mode 100644
index 0000000..8c5cd25
--- /dev/null
+++ b/apps/docs/src/demos/en/button/sizes.tsx
@@ -0,0 +1,11 @@
+import {Button} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-3">
+      <Button size="sm">Small</Button>
+      <Button size="md">Medium</Button>
+      <Button size="lg">Large</Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/social.tsx b/apps/docs/src/demos/en/button/social.tsx
new file mode 100644
index 0000000..5689a31
--- /dev/null
+++ b/apps/docs/src/demos/en/button/social.tsx
@@ -0,0 +1,21 @@
+import {Button} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function Social() {
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-3">
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="devicon:google" />
+        Sign in with Google
+      </Button>
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="mdi:github" />
+        Sign in with GitHub
+      </Button>
+      <Button className="w-full" variant="tertiary">
+        <Icon icon="ion:logo-apple" />
+        Sign in with Apple
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/variants.tsx b/apps/docs/src/demos/en/button/variants.tsx
new file mode 100644
index 0000000..d71814f
--- /dev/null
+++ b/apps/docs/src/demos/en/button/variants.tsx
@@ -0,0 +1,15 @@
+import {Button} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button>Primary</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="tertiary">Tertiary</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="danger">Danger</Button>
+      <Button variant="danger-soft">Danger Soft</Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/button/with-icons.tsx b/apps/docs/src/demos/en/button/with-icons.tsx
new file mode 100644
index 0000000..782753f
--- /dev/null
+++ b/apps/docs/src/demos/en/button/with-icons.tsx
@@ -0,0 +1,25 @@
+import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
+import {Button} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button>
+        <Globe />
+        Search
+      </Button>
+      <Button variant="secondary">
+        <Plus />
+        Add Member
+      </Button>
+      <Button variant="tertiary">
+        <Envelope />
+        Email
+      </Button>
+      <Button variant="danger">
+        <TrashBin />
+        Delete
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/basic.tsx b/apps/docs/src/demos/en/calendar/basic.tsx
new file mode 100644
index 0000000..87a4f4f
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/basic.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Calendar aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/booking-calendar.tsx b/apps/docs/src/demos/en/calendar/booking-calendar.tsx
new file mode 100644
index 0000000..dd9dec6
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/booking-calendar.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import type {CalendarDate, DateValue} from "@internationalized/date";
+
+import {Button, Calendar} from "@heroui/react";
+import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+export function BookingCalendar() {
+  const [selectedDate, setSelectedDate] = useState<CalendarDate | null>(null);
+  const {locale} = useLocale();
+
+  const bookedDates = [5, 6, 12, 13, 14, 20];
+
+  const isDateUnavailable = (date: DateValue) => {
+    return isWeekend(date, locale) || bookedDates.includes(date.day);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar
+        aria-label="Booking date"
+        isDateUnavailable={isDateUnavailable}
+        minValue={today(getLocalTimeZone())}
+        value={selectedDate}
+        onChange={setSelectedDate}
+      >
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>
+            {(date) => (
+              <Calendar.Cell date={date}>
+                {({formattedDate, isUnavailable}) => (
+                  <>
+                    {formattedDate}
+                    {!isUnavailable &&
+                      !isWeekend(date, locale) &&
+                      bookedDates.includes(date.day) && <Calendar.CellIndicator />}
+                  </>
+                )}
+              </Calendar.Cell>
+            )}
+          </Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <div className="flex flex-col gap-2 text-center">
+        <div className="flex items-center justify-center gap-4 text-xs text-muted">
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-muted" /> Has bookings
+          </span>
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-default" /> Weekend/Unavailable
+          </span>
+        </div>
+        {selectedDate ? (
+          <Button size="sm" variant="primary">
+            Book {selectedDate.toString()}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/controlled.tsx b/apps/docs/src/demos/en/calendar/controlled.tsx
new file mode 100644
index 0000000..725b286
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/controlled.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import type {CalendarDate} from "@internationalized/date";
+
+import {Button, ButtonGroup, Calendar, Description} from "@heroui/react";
+import {
+  getLocalTimeZone,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+export function Controlled() {
+  const [value, setValue] = useState<CalendarDate | null>(null);
+  const [focusedDate, setFocusedDate] = useState<CalendarDate>(parseDate("2025-12-25"));
+  const {locale} = useLocale();
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <ButtonGroup fullWidth size="sm" variant="tertiary">
+        <Button
+          onPress={() => {
+            const todayDate = today(getLocalTimeZone());
+
+            setValue(todayDate);
+            setFocusedDate(todayDate);
+          }}
+        >
+          Today
+        </Button>
+        <Button
+          onPress={() => {
+            const nextWeekStart = startOfWeek(today(getLocalTimeZone()), locale);
+
+            setValue(nextWeekStart);
+            setFocusedDate(nextWeekStart);
+          }}
+        >
+          Week
+        </Button>
+        <Button
+          onPress={() => {
+            const nextMonthStart = startOfMonth(today(getLocalTimeZone()));
+
+            setValue(nextMonthStart);
+            setFocusedDate(nextMonthStart);
+          }}
+        >
+          Month
+        </Button>
+      </ButtonGroup>
+
+      <Calendar
+        aria-label="Event date"
+        focusedValue={focusedDate}
+        value={value}
+        onChange={setValue}
+        onFocusChange={setFocusedDate}
+      >
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <Description className="text-center">
+        Selected date: {value ? value.toString() : "(none)"}
+      </Description>
+
+      <div className="flex gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const todayDate = today(getLocalTimeZone());
+
+            setValue(todayDate);
+            setFocusedDate(todayDate);
+          }}
+        >
+          Set Today
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const christmasDate = parseDate("2025-12-25");
+
+            setValue(christmasDate);
+            setFocusedDate(christmasDate);
+          }}
+        >
+          Set Christmas
+        </Button>
+        <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/custom-icons.tsx b/apps/docs/src/demos/en/calendar/custom-icons.tsx
new file mode 100644
index 0000000..94742e7
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/custom-icons.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <Calendar aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+        <Calendar.NavButton slot="next">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/custom-styles.tsx b/apps/docs/src/demos/en/calendar/custom-styles.tsx
new file mode 100644
index 0000000..155e3b8
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/custom-styles.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Calendar aria-label="Custom styled calendar">
+      <Calendar.Header>
+        <Calendar.NavButton className="text-foreground" slot="previous" />
+        <Calendar.YearPickerTrigger className="w-full justify-center">
+          <Calendar.YearPickerTriggerHeading className="text-foreground" />
+          <Calendar.YearPickerTriggerIndicator className="text-foreground" />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton className="text-foreground" slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({year}) => <Calendar.YearPickerCell year={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/day-view.tsx b/apps/docs/src/demos/en/calendar/day-view.tsx
new file mode 100644
index 0000000..91bd25e
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/day-view.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+const dayOptions = [
+  {id: "1", name: "1 day"},
+  {id: "5", name: "5 days"},
+  {id: "7", name: "7 days"},
+  {id: "8", name: "8 days"},
+  {id: "10", name: "10 days"},
+  {id: "14", name: "14 days"},
+  {id: "21", name: "21 days"},
+] as const;
+
+export function DayView() {
+  const [days, setDays] = useState(5);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(days)}
+        onChange={(value) => value && setDays(Number(value))}
+      >
+        <Label>Visible days</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {dayOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <Calendar aria-label="Day view" visibleDuration={{days}}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/default-value.tsx b/apps/docs/src/demos/en/calendar/default-value.tsx
new file mode 100644
index 0000000..4e15f7d
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/default-value.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+
+export function DefaultValue() {
+  return (
+    <Calendar aria-label="Event date" defaultValue={parseDate("2025-02-14")}>
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/disabled.tsx b/apps/docs/src/demos/en/calendar/disabled.tsx
new file mode 100644
index 0000000..4cbedf3
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/disabled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar isDisabled aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">Calendar is disabled</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/focused-value.tsx b/apps/docs/src/demos/en/calendar/focused-value.tsx
new file mode 100644
index 0000000..478c4c8
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/focused-value.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Calendar, Description} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+import {useState} from "react";
+
+export function FocusedValue() {
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="Event date" focusedValue={focusedDate} onFocusChange={setFocusedDate}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+
+      <Description className="text-center">Focused: {focusedDate.toString()}</Description>
+
+      <div className="flex flex-wrap justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+        >
+          Go to Jan
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+        >
+          Go to Jun
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+        >
+          Go to Christmas
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/index.ts b/apps/docs/src/demos/en/calendar/index.ts
new file mode 100644
index 0000000..d816877
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/index.ts
@@ -0,0 +1,19 @@
+export {Basic} from "./basic";
+export {BookingCalendar} from "./booking-calendar";
+export {Controlled} from "./controlled";
+export {CustomStyles} from "./custom-styles";
+export {CustomIcons} from "./custom-icons";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {FocusedValue} from "./focused-value";
+export {InternationalCalendar} from "./international-calendar";
+export {MinMaxDates} from "./min-max-dates";
+export {MultipleSelection} from "./multiple-selection";
+export {MultipleMonths} from "./multiple-months";
+export {WeeksInMonth} from "./weeks-in-month";
+export {WeekView} from "./week-view";
+export {DayView} from "./day-view";
+export {ReadOnly} from "./read-only";
+export {UnavailableDates} from "./unavailable-dates";
+export {WithIndicators} from "./with-indicators";
+export {YearPicker} from "./year-picker";
diff --git a/apps/docs/src/demos/en/calendar/international-calendar.tsx b/apps/docs/src/demos/en/calendar/international-calendar.tsx
new file mode 100644
index 0000000..9a4f519
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/international-calendar.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <Calendar aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.YearPickerTrigger>
+            <Calendar.YearPickerTriggerHeading />
+            <Calendar.YearPickerTriggerIndicator />
+          </Calendar.YearPickerTrigger>
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+        <Calendar.YearPickerGrid>
+          <Calendar.YearPickerGridBody>
+            {({year}) => <Calendar.YearPickerCell year={year} />}
+          </Calendar.YearPickerGridBody>
+        </Calendar.YearPickerGrid>
+      </Calendar>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/min-max-dates.tsx b/apps/docs/src/demos/en/calendar/min-max-dates.tsx
new file mode 100644
index 0000000..886e030
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/min-max-dates.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function MinMaxDates() {
+  const now = today(getLocalTimeZone());
+  const minDate = now;
+  const maxDate = now.add({months: 3});
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="Appointment date" maxValue={maxDate} minValue={minDate}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">
+        Select a date between today and {maxDate.toString()}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/multiple-months.tsx b/apps/docs/src/demos/en/calendar/multiple-months.tsx
new file mode 100644
index 0000000..9248eeb
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/multiple-months.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function MultipleMonths() {
+  return (
+    <Calendar
+      aria-label="Trip dates"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+        <div className="w-64">
+          <Calendar.Header>
+            <div className="size-6" />
+            <Calendar.Heading className="flex-none" offset={{months: 1}} />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid offset={{months: 1}}>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+      </div>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/multiple-selection.tsx b/apps/docs/src/demos/en/calendar/multiple-selection.tsx
new file mode 100644
index 0000000..f50030e
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/multiple-selection.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, Description} from "@heroui/react";
+import {useState} from "react";
+
+export function MultipleSelection() {
+  const [value, setValue] = useState<readonly DateValue[]>([]);
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="Event dates" selectionMode="multiple" value={value} onChange={setValue}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">
+        {value?.length ? `${value.length} date(s) selected` : "Select multiple dates"}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/read-only.tsx b/apps/docs/src/demos/en/calendar/read-only.tsx
new file mode 100644
index 0000000..da189e0
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/read-only.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function ReadOnly() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar isReadOnly aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">Calendar is read-only</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/unavailable-dates.tsx b/apps/docs/src/demos/en/calendar/unavailable-dates.tsx
new file mode 100644
index 0000000..bcc2184
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/unavailable-dates.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, Description} from "@heroui/react";
+import {isWeekend} from "@internationalized/date";
+import {useLocale} from "react-aria-components";
+
+export function UnavailableDates() {
+  const {locale} = useLocale();
+  const isDateUnavailable = (date: DateValue) => isWeekend(date, locale);
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="Appointment date" isDateUnavailable={isDateUnavailable}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">Weekends are unavailable</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/week-view.tsx b/apps/docs/src/demos/en/calendar/week-view.tsx
new file mode 100644
index 0000000..d237b34
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/week-view.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+const weekOptions = [
+  {id: "1", name: "1 week"},
+  {id: "2", name: "2 weeks"},
+  {id: "3", name: "3 weeks"},
+  {id: "4", name: "4 weeks"},
+  {id: "5", name: "5 weeks"},
+  {id: "6", name: "6 weeks"},
+  {id: "8", name: "8 weeks"},
+] as const;
+
+export function WeekView() {
+  const [weeks, setWeeks] = useState(1);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(weeks)}
+        onChange={(value) => value && setWeeks(Number(value))}
+      >
+        <Label>Visible weeks</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {weekOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <Calendar aria-label="Week view" visibleDuration={{weeks}}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/weeks-in-month.tsx b/apps/docs/src/demos/en/calendar/weeks-in-month.tsx
new file mode 100644
index 0000000..a4576a7
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/weeks-in-month.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {Calendar, Description} from "@heroui/react";
+
+export function WeeksInMonth() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <Calendar aria-label="Event date" weeksInMonth={6}>
+        <Calendar.Header>
+          <Calendar.Heading />
+          <Calendar.NavButton slot="previous" />
+          <Calendar.NavButton slot="next" />
+        </Calendar.Header>
+        <Calendar.Grid>
+          <Calendar.GridHeader>
+            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+          </Calendar.GridHeader>
+          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+        </Calendar.Grid>
+      </Calendar>
+      <Description className="text-center">
+        Always shows 6 weeks per month to avoid layout shift when navigating
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/with-indicators.tsx b/apps/docs/src/demos/en/calendar/with-indicators.tsx
new file mode 100644
index 0000000..037399d
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/with-indicators.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+import {getLocalTimeZone, isToday} from "@internationalized/date";
+
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export function WithIndicators() {
+  return (
+    <Calendar aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => (
+            <Calendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <Calendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </Calendar.Cell>
+          )}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/calendar/year-picker.tsx b/apps/docs/src/demos/en/calendar/year-picker.tsx
new file mode 100644
index 0000000..c62a81c
--- /dev/null
+++ b/apps/docs/src/demos/en/calendar/year-picker.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar} from "@heroui/react";
+
+export function YearPicker() {
+  return (
+    <Calendar aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({year}) => <Calendar.YearPickerCell year={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/default.tsx b/apps/docs/src/demos/en/card/default.tsx
new file mode 100644
index 0000000..edb01ac
--- /dev/null
+++ b/apps/docs/src/demos/en/card/default.tsx
@@ -0,0 +1,28 @@
+import {CircleDollar} from "@gravity-ui/icons";
+import {Card, Link} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Card className="w-[400px]">
+      <CircleDollar aria-label="Dollar sign icon" className="text-primary size-6" role="img" />
+      <Card.Header>
+        <Card.Title>Become an Acme Creator!</Card.Title>
+        <Card.Description>
+          Visit the Acme Creator Hub to sign up today and start earning credits from your fans and
+          followers.
+        </Card.Description>
+      </Card.Header>
+      <Card.Footer>
+        <Link
+          aria-label="Go to Acme Creator Hub (opens in new tab)"
+          href="https://heroui.com"
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          Creator Hub
+          <Link.Icon aria-hidden="true" />
+        </Link>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/horizontal.tsx b/apps/docs/src/demos/en/card/horizontal.tsx
new file mode 100644
index 0000000..3cfbf2b
--- /dev/null
+++ b/apps/docs/src/demos/en/card/horizontal.tsx
@@ -0,0 +1,33 @@
+import {Button, Card, CloseButton} from "@heroui/react";
+
+export function Horizontal() {
+  return (
+    <Card className="w-full items-stretch md:flex-row">
+      <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+        <img
+          alt="Cherries"
+          className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+        />
+      </div>
+      <div className="flex flex-1 flex-col gap-3">
+        <Card.Header className="gap-1">
+          <Card.Title className="pr-8">Become an ACME Creator!</Card.Title>
+          <Card.Description>
+            Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
+            faucibus etiam.
+          </Card.Description>
+          <CloseButton aria-label="Close banner" className="absolute top-3 right-3" />
+        </Card.Header>
+        <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div className="flex flex-col">
+            <span className="text-sm font-medium text-foreground">Only 10 spots</span>
+            <span className="text-xs text-muted">Submission ends Oct 10.</span>
+          </div>
+          <Button className="w-full sm:w-auto">Apply Now</Button>
+        </Card.Footer>
+      </div>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/index.ts b/apps/docs/src/demos/en/card/index.ts
new file mode 100644
index 0000000..0679368
--- /dev/null
+++ b/apps/docs/src/demos/en/card/index.ts
@@ -0,0 +1,7 @@
+// Card demos
+export {Default} from "./default";
+export {Horizontal} from "./horizontal";
+export {Variants} from "./variants";
+export {WithAvatar} from "./with-avatar";
+export {WithForm} from "./with-form";
+export {WithImages} from "./with-images";
diff --git a/apps/docs/src/demos/en/card/variants.tsx b/apps/docs/src/demos/en/card/variants.tsx
new file mode 100644
index 0000000..cff2cfc
--- /dev/null
+++ b/apps/docs/src/demos/en/card/variants.tsx
@@ -0,0 +1,47 @@
+import {Card} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Card className="w-[320px]" variant="transparent">
+        <Card.Header>
+          <Card.Title>Transparent</Card.Title>
+          <Card.Description>Minimal prominence with transparent background</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use for less important content or nested cards</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="default">
+        <Card.Header>
+          <Card.Title>Default</Card.Title>
+          <Card.Description>Standard card appearance (bg-surface)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>The default card variant for most use cases</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="secondary">
+        <Card.Header>
+          <Card.Title>Secondary</Card.Title>
+          <Card.Description>Medium prominence (bg-surface-secondary)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use to draw moderate attention</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="tertiary">
+        <Card.Header>
+          <Card.Title>Tertiary</Card.Title>
+          <Card.Description>Higher prominence (bg-surface-tertiary)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use for primary or featured content</p>
+        </Card.Content>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/with-avatar.tsx b/apps/docs/src/demos/en/card/with-avatar.tsx
new file mode 100644
index 0000000..99b83af
--- /dev/null
+++ b/apps/docs/src/demos/en/card/with-avatar.tsx
@@ -0,0 +1,53 @@
+import {Avatar, Card} from "@heroui/react";
+
+export function WithAvatar() {
+  return (
+    <div className="flex flex-wrap gap-4">
+      <Card className="w-[200px] gap-2">
+        <img
+          alt="Indie Hackers community"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+        />
+        <Card.Header>
+          <Card.Title>Indie Hackers</Card.Title>
+          <Card.Description>148 members</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="Martha's profile picture" className="size-5">
+            <Avatar.Image
+              alt="Martha's avatar"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+            />
+            <Avatar.Fallback className="text-xs">IH</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">By Martha</span>
+        </Card.Footer>
+      </Card>
+
+      <Card className="w-[200px] gap-2">
+        <img
+          alt="AI Builders community"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+        />
+        <Card.Header>
+          <Card.Title>AI Builders</Card.Title>
+          <Card.Description>362 members</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="John's profile picture" className="size-5">
+            <Avatar.Image
+              alt="John's avatar - blue themed"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback className="text-xs">B</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">By John</span>
+        </Card.Footer>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/with-form.tsx b/apps/docs/src/demos/en/card/with-form.tsx
new file mode 100644
index 0000000..23cb8b3
--- /dev/null
+++ b/apps/docs/src/demos/en/card/with-form.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {Button, Card, Form, Input, Label, Link, TextField} from "@heroui/react";
+
+export function WithForm() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Header>
+        <Card.Title>Login</Card.Title>
+        <Card.Description>Enter your credentials to access your account</Card.Description>
+      </Card.Header>
+      <Form onSubmit={onSubmit}>
+        <Card.Content>
+          <div className="flex flex-col gap-4">
+            <TextField name="email" type="email">
+              <Label>Email</Label>
+              <Input placeholder="email@example.com" variant="secondary" />
+            </TextField>
+            <TextField name="password" type="password">
+              <Label>Password</Label>
+              <Input placeholder="••••••••" variant="secondary" />
+            </TextField>
+          </div>
+        </Card.Content>
+        <Card.Footer className="mt-4 flex flex-col gap-2">
+          <Button className="w-full" type="submit">
+            Sign In
+          </Button>
+          <Link className="text-center text-sm" href="#">
+            Forgot password?
+          </Link>
+        </Card.Footer>
+      </Form>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/en/card/with-images.tsx b/apps/docs/src/demos/en/card/with-images.tsx
new file mode 100644
index 0000000..d324fb1
--- /dev/null
+++ b/apps/docs/src/demos/en/card/with-images.tsx
@@ -0,0 +1,226 @@
+import {CircleDollar} from "@gravity-ui/icons";
+import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react";
+
+export function WithImages() {
+  return (
+    <div className="flex w-full items-center justify-center">
+      <div className="grid w-full max-w-2xl grid-cols-12 gap-4 p-4">
+        {/* Row 1: Large Product Card - Available Soon */}
+        <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row">
+          <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+            <img
+              alt="Cherries"
+              className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+              loading="lazy"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+            />
+          </div>
+          <div className="flex flex-1 flex-col gap-3">
+            <Card.Header className="gap-1">
+              <Card.Title className="pr-8">Become an ACME Creator!</Card.Title>
+              <Card.Description>
+                Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
+                faucibus etiam.
+              </Card.Description>
+              <CloseButton aria-label="Close banner" className="absolute top-3 right-3" />
+            </Card.Header>
+            <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
+              <div className="flex flex-col">
+                <span className="text-sm font-medium text-foreground">Only 10 spots</span>
+                <span className="text-xs text-muted">Submission ends Oct 10.</span>
+              </div>
+              <Button className="w-full sm:w-auto">Apply Now</Button>
+            </Card.Footer>
+          </div>
+        </Card>
+
+        {/* Row 2 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* Left Column */}
+          <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6">
+            {/* Top Card */}
+            <Card className="col-span-12">
+              <div className="absolute top-3 right-3 z-10">
+                <CloseButton aria-label="Close notification" />
+              </div>
+              <Card.Header className="gap-3">
+                <CircleDollar
+                  aria-label="Dollar sign icon"
+                  className="text-primary size-8 shrink-0"
+                  role="img"
+                />
+                <div className="flex flex-col gap-1">
+                  <span className="text-xs font-medium text-muted uppercase">PAYMENT</span>
+                  <Card.Title className="pr-8 text-sm sm:text-base">
+                    You can now withdraw on crypto
+                  </Card.Title>
+                  <Card.Description className="text-xs sm:text-sm">
+                    Add your wallet in settings to withdraw
+                  </Card.Description>
+                </div>
+              </Card.Header>
+              <Card.Footer>
+                <Link aria-label="Go to settings" href="#" rel="noopener noreferrer">
+                  Go to settings
+                  <Link.Icon aria-hidden="true" />
+                </Link>
+              </Card.Footer>
+            </Card>
+            {/* Bottom cards */}
+            <div className="col-span-12 grid grid-cols-12 gap-4">
+              {/* Left Card */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="Demo 1"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">Indie Hackers</p>
+                  <p className="text-xs text-muted">148 members</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="John"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">By John</p>
+                </Card.Footer>
+              </Card>
+              {/* Right Card */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="Demo 2"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+                    />
+                    <Avatar.Fallback>AB</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">AI Builders</p>
+                  <p className="text-xs text-muted">362 members</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="John"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+                    />
+                    <Avatar.Fallback>M</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">By Martha</p>
+                </Card.Footer>
+              </Card>
+            </div>
+          </div>
+          {/* Right Column */}
+          <Card className="col-span-12 min-h-[200px] overflow-hidden rounded-3xl lg:col-span-6">
+            {/* Background image */}
+            <img
+              alt="NEO Home Robot"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg"
+            />
+
+            {/* Header */}
+            <Card.Header className="z-10 text-white">
+              <Card.Title className="text-xs font-semibold tracking-wide text-black/70">
+                NEO
+              </Card.Title>
+              <Card.Description className="text-sm leading-5 font-medium text-black/50">
+                Home Robot
+              </Card.Description>
+            </Card.Header>
+
+            {/* Footer */}
+            <Card.Footer className="z-10 mt-auto flex items-center justify-between">
+              <div>
+                <div className="text-sm font-medium text-black">Available soon</div>
+                <div className="text-xs text-black/60">Get notified</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                Notify me
+              </Button>
+            </Card.Footer>
+          </Card>
+        </div>
+
+        {/* Row 3 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* Left Column: Card */}
+          <Card className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]">
+            <img
+              alt="NEO Home Robot"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo1.jpeg"
+            />
+
+            <Card.Footer className="z-10 mt-auto flex items-end justify-between">
+              <div>
+                <div className="text-base font-medium text-black sm:text-lg">NEO</div>
+                <div className="text-xs font-medium text-black/50 sm:text-sm">$499/m</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                Get now
+              </Button>
+            </Card.Footer>
+          </Card>
+
+          {/* Right Column: Cards Stack */}
+          <div className="col-span-12 flex flex-col gap-2 md:col-span-4 md:justify-between md:gap-0 md:py-2">
+            {/* 1 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Futuristic Robot"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Bridging the Future</Card.Title>
+                <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
+              </div>
+            </Card>
+            {/* 2 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Avocado"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Avocado Hackathon</Card.Title>
+                <Card.Description className="text-xs">Wed, 4:30 PM</Card.Description>
+              </div>
+            </Card>
+            {/* 3 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Sound Electro event"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Sound Electro | Beyond art</Card.Title>
+                <Card.Description className="text-xs">Fri, 8:00 PM</Card.Description>
+              </div>
+            </Card>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/basic.tsx b/apps/docs/src/demos/en/checkbox-group/basic.tsx
new file mode 100644
index 0000000..6d5b667
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/basic.tsx
@@ -0,0 +1,37 @@
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <CheckboxGroup name="interests">
+      <Label>Select your interests</Label>
+      <Description>Choose all that apply</Description>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+        <Description>Love building software</Description>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+        <Description>Enjoy creating beautiful interfaces</Description>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+        <Description>Passionate about content creation</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/controlled.tsx b/apps/docs/src/demos/en/checkbox-group/controlled.tsx
new file mode 100644
index 0000000..db54b6a
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/controlled.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState(["coding", "design"]);
+
+  return (
+    <CheckboxGroup className="min-w-[320px]" name="skills" value={selected} onChange={setSelected}>
+      <Label>Your skills</Label>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+      </Checkbox>
+      <Label className="my-4 text-sm text-muted">Selected: {selected.join(", ") || "None"}</Label>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/custom-render-function.tsx b/apps/docs/src/demos/en/checkbox-group/custom-render-function.tsx
new file mode 100644
index 0000000..018ce8a
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/custom-render-function.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <CheckboxGroup name="interests" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>Select your interests</Label>
+      <Description>Choose all that apply</Description>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+        <Description>Love building software</Description>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+        <Description>Enjoy creating beautiful interfaces</Description>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+        <Description>Passionate about content creation</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/disabled.tsx b/apps/docs/src/demos/en/checkbox-group/disabled.tsx
new file mode 100644
index 0000000..8ee0b37
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/disabled.tsx
@@ -0,0 +1,28 @@
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <CheckboxGroup isDisabled name="disabled-features">
+      <Label>Features</Label>
+      <Description>Feature selection is temporarily disabled</Description>
+      <Checkbox value="feature1">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Feature 1
+        </Checkbox.Content>
+        <Description>This feature is coming soon</Description>
+      </Checkbox>
+      <Checkbox value="feature2">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Feature 2
+        </Checkbox.Content>
+        <Description>This feature is coming soon</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/features-and-addons.tsx b/apps/docs/src/demos/en/checkbox-group/features-and-addons.tsx
new file mode 100644
index 0000000..939d8e0
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/features-and-addons.tsx
@@ -0,0 +1,58 @@
+import {Bell, Comment, Envelope} from "@gravity-ui/icons";
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+import clsx from "clsx";
+
+export function FeaturesAndAddOns() {
+  const addOns = [
+    {
+      description: "Receive updates via email",
+      icon: Envelope,
+      title: "Email Notifications",
+      value: "email",
+    },
+    {
+      description: "Get instant SMS notifications",
+      icon: Comment,
+      title: "SMS Alerts",
+      value: "sms",
+    },
+    {
+      description: "Browser and mobile push alerts",
+      icon: Bell,
+      title: "Push Notifications",
+      value: "push",
+    },
+  ];
+
+  return (
+    <div className="flex w-full flex-col items-center gap-10 px-4 py-8">
+      <section className="flex w-full min-w-[320px] flex-col gap-4">
+        <CheckboxGroup name="notification-preferences">
+          <Label>Notification preferences</Label>
+          <Description>Choose how you want to receive updates</Description>
+          <div className="flex flex-col gap-2">
+            {addOns.map((addon) => (
+              <Checkbox key={addon.value} value={addon.value} variant="secondary">
+                <Checkbox.Content
+                  className={clsx(
+                    "group relative flex w-full flex-row items-start justify-start gap-4 rounded-3xl bg-surface px-5 py-4 transition-all",
+                    "data-[selected=true]:bg-accent/10",
+                  )}
+                >
+                  <Checkbox.Control className="absolute top-3 right-4 size-5 rounded-full before:rounded-full">
+                    <Checkbox.Indicator />
+                  </Checkbox.Control>
+                  <addon.icon className="size-5 text-accent-soft-foreground" />
+                  <div className="flex flex-col gap-1">
+                    <span>{addon.title}</span>
+                    <Description>{addon.description}</Description>
+                  </div>
+                </Checkbox.Content>
+              </Checkbox>
+            ))}
+          </div>
+        </CheckboxGroup>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/indeterminate.tsx b/apps/docs/src/demos/en/checkbox-group/indeterminate.tsx
new file mode 100644
index 0000000..1d84154
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/indeterminate.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import {Checkbox, CheckboxGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function Indeterminate() {
+  const [selected, setSelected] = useState(["coding"]);
+  const allOptions = ["coding", "design", "writing"];
+
+  return (
+    <div>
+      <Checkbox
+        isIndeterminate={selected.length > 0 && selected.length < allOptions.length}
+        isSelected={selected.length === allOptions.length}
+        name="select-all"
+        onChange={(isSelected: boolean) => {
+          setSelected(isSelected ? allOptions : []);
+        }}
+      >
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Select all
+        </Checkbox.Content>
+      </Checkbox>
+      <div className="ml-6 flex flex-col gap-2">
+        <CheckboxGroup value={selected} onChange={setSelected}>
+          <Checkbox value="coding">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              Coding
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="design">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              Design
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="writing">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              Writing
+            </Checkbox.Content>
+          </Checkbox>
+        </CheckboxGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/index.ts b/apps/docs/src/demos/en/checkbox-group/index.ts
new file mode 100644
index 0000000..63102b1
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FeaturesAndAddOns} from "./features-and-addons";
+export {Indeterminate} from "./indeterminate";
+export {OnSurface} from "./on-surface";
+export {Validation} from "./validation";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/checkbox-group/on-surface.tsx b/apps/docs/src/demos/en/checkbox-group/on-surface.tsx
new file mode 100644
index 0000000..7b8f784
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/on-surface.tsx
@@ -0,0 +1,39 @@
+import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <CheckboxGroup name="interests" variant="secondary">
+        <Label>Select your interests</Label>
+        <Description>Choose all that apply</Description>
+        <Checkbox value="coding">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Coding
+          </Checkbox.Content>
+          <Description>Love building software</Description>
+        </Checkbox>
+        <Checkbox value="design">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Design
+          </Checkbox.Content>
+          <Description>Enjoy creating beautiful interfaces</Description>
+        </Checkbox>
+        <Checkbox value="writing">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Writing
+          </Checkbox.Content>
+          <Description>Passionate about content creation</Description>
+        </Checkbox>
+      </CheckboxGroup>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/validation.tsx b/apps/docs/src/demos/en/checkbox-group/validation.tsx
new file mode 100644
index 0000000..84177cc
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/validation.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <Form
+      className="flex flex-col gap-4 px-4"
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        const formData = new FormData(e.currentTarget);
+        const values = formData.getAll("preferences");
+
+        alert(`Selected preferences: ${values.join(", ")}`);
+      }}
+    >
+      <CheckboxGroup isRequired name="preferences">
+        <Label>Preferences</Label>
+        <Checkbox value="email">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Email notifications
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="sms">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            SMS notifications
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="push">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Push notifications
+          </Checkbox.Content>
+        </Checkbox>
+        <FieldError>Please select at least one notification method.</FieldError>
+      </CheckboxGroup>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox-group/with-custom-indicator.tsx b/apps/docs/src/demos/en/checkbox-group/with-custom-indicator.tsx
new file mode 100644
index 0000000..080566c
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox-group/with-custom-indicator.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
+
+export function WithCustomIndicator() {
+  return (
+    <CheckboxGroup name="features">
+      <Label>Features</Label>
+      <Description>Select the features you want</Description>
+      <Checkbox value="notifications">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Email notifications
+        </Checkbox.Content>
+        <Description>Receive updates via email</Description>
+      </Checkbox>
+      <Checkbox value="newsletter">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Newsletter
+        </Checkbox.Content>
+        <Description>Get weekly newsletters</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/basic.tsx b/apps/docs/src/demos/en/checkbox/basic.tsx
new file mode 100644
index 0000000..62a6c75
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/basic.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Checkbox name="basic-terms">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Accept terms and conditions
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/controlled.tsx b/apps/docs/src/demos/en/checkbox/controlled.tsx
new file mode 100644
index 0000000..a50a55a
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/controlled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Checkbox} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = useState(true);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <Checkbox id="email-notifications" isSelected={isSelected} onChange={setIsSelected}>
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Email notifications
+        </Checkbox.Content>
+      </Checkbox>
+      <p className="text-sm text-muted">
+        Status: <span className="font-medium">{isSelected ? "Enabled" : "Disabled"}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/custom-indicator.tsx b/apps/docs/src/demos/en/checkbox/custom-indicator.tsx
new file mode 100644
index 0000000..96de00b
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/custom-indicator.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import {Checkbox} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <div className="flex gap-4">
+      <Checkbox defaultSelected name="heart">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg fill="currentColor" viewBox="0 0 24 24">
+                    <path
+                      d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z"
+                      fill="currentColor"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Heart
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox defaultSelected name="plus">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg fill="none" viewBox="0 0 24 24">
+                    <path
+                      d="M6 12H18"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                    <path
+                      d="M12 18V6"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Plus
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox isIndeterminate name="indeterminate">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isIndeterminate}) =>
+                isIndeterminate ? (
+                  <svg stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24">
+                    <line x1="21" x2="3" y1="12" y2="12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Indeterminate
+        </Checkbox.Content>
+      </Checkbox>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/custom-render-function.tsx b/apps/docs/src/demos/en/checkbox/custom-render-function.tsx
new file mode 100644
index 0000000..07f036d
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Checkbox, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-3">
+      <Checkbox id="basic-terms" render={(props) => <div {...props} data-custom="bar" />}>
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+      <Label htmlFor="basic-terms">Accept terms and conditions</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/custom-styles.tsx b/apps/docs/src/demos/en/checkbox/custom-styles.tsx
new file mode 100644
index 0000000..38778c0
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/custom-styles.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Checkbox id="custom">
+      <Checkbox.Content>
+        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500">
+          <Checkbox.Indicator className="text-white" />
+        </Checkbox.Control>
+        Custom styled checkbox
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/default-selected.tsx b/apps/docs/src/demos/en/checkbox/default-selected.tsx
new file mode 100644
index 0000000..2f33a60
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/default-selected.tsx
@@ -0,0 +1,14 @@
+import {Checkbox} from "@heroui/react";
+
+export function DefaultSelected() {
+  return (
+    <Checkbox defaultSelected id="default-notifications">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Enable email notifications
+      </Checkbox.Content>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/disabled.tsx b/apps/docs/src/demos/en/checkbox/disabled.tsx
new file mode 100644
index 0000000..03c1c5c
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/disabled.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Checkbox isDisabled id="feature">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Premium Feature
+      </Checkbox.Content>
+      <Description>This feature is coming soon</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/external-label.tsx b/apps/docs/src/demos/en/checkbox/external-label.tsx
new file mode 100644
index 0000000..e833567
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/external-label.tsx
@@ -0,0 +1,16 @@
+import {Checkbox, Label} from "@heroui/react";
+
+export function ExternalLabel() {
+  return (
+    <div className="flex items-center gap-3">
+      <Checkbox id="label-marketing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+      <Label htmlFor="label-marketing">Send me marketing emails</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/form.tsx b/apps/docs/src/demos/en/checkbox/form.tsx
new file mode 100644
index 0000000..6882ba0
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/form.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Button, Checkbox} from "@heroui/react";
+import React from "react";
+
+export function Form() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+
+    alert(
+      `Form submitted with:\n${Array.from(formData.entries())
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n")}`,
+    );
+  };
+
+  return (
+    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="notifications" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Enable notifications
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox defaultSelected name="newsletter" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Subscribe to newsletter
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox name="marketing" value="on">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Receive marketing updates
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <Button className="mt-4" size="sm" type="submit" variant="primary">
+        Submit
+      </Button>
+    </form>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/full-rounded.tsx b/apps/docs/src/demos/en/checkbox/full-rounded.tsx
new file mode 100644
index 0000000..95c6539
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/full-rounded.tsx
@@ -0,0 +1,55 @@
+import {Checkbox, Label} from "@heroui/react";
+
+export function FullRounded() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-3">
+        <Label className="text-muted">Rounded checkboxes</Label>
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-2"
+          name="small-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-3 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Small size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="default-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-4 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Default size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox name="large-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-5 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Large size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-4"
+          name="xl-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-6 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Extra large size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/indeterminate.tsx b/apps/docs/src/demos/en/checkbox/indeterminate.tsx
new file mode 100644
index 0000000..ed9c3b1
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/indeterminate.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Checkbox, Description} from "@heroui/react";
+import {useState} from "react";
+
+export function Indeterminate() {
+  const [isIndeterminate, setIsIndeterminate] = useState(true);
+  const [isSelected, setIsSelected] = useState(false);
+
+  return (
+    <Checkbox
+      id="select-all"
+      isIndeterminate={isIndeterminate}
+      isSelected={isSelected}
+      onChange={(selected: boolean) => {
+        setIsSelected(selected);
+        setIsIndeterminate(false);
+      }}
+    >
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Select all
+      </Checkbox.Content>
+      <Description>Shows indeterminate state (dash icon)</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/index.ts b/apps/docs/src/demos/en/checkbox/index.ts
new file mode 100644
index 0000000..9f23fcc
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/index.ts
@@ -0,0 +1,15 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomStyles} from "./custom-styles";
+export {DefaultSelected} from "./default-selected";
+export {Disabled} from "./disabled";
+export {Form} from "./form";
+export {FullRounded} from "./full-rounded";
+export {Indeterminate} from "./indeterminate";
+export {Invalid} from "./invalid";
+export {RenderProps} from "./render-props";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {ExternalLabel} from "./external-label";
diff --git a/apps/docs/src/demos/en/checkbox/invalid.tsx b/apps/docs/src/demos/en/checkbox/invalid.tsx
new file mode 100644
index 0000000..b5c44f2
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/invalid.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, FieldError} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <Checkbox isInvalid isRequired name="agreement">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        I agree to the terms
+      </Checkbox.Content>
+      <FieldError>You must accept the terms to continue</FieldError>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/render-props.tsx b/apps/docs/src/demos/en/checkbox/render-props.tsx
new file mode 100644
index 0000000..77d715f
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/render-props.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Checkbox, Description} from "@heroui/react";
+
+export function RenderProps() {
+  return (
+    <Checkbox id="render-props-terms">
+      {({isSelected}) => (
+        <>
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            {isSelected ? "Terms accepted" : "Accept terms"}
+          </Checkbox.Content>
+          <Description>
+            {isSelected ? "Thank you for accepting" : "Please read and accept the terms"}
+          </Description>
+        </>
+      )}
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/variants.tsx b/apps/docs/src/demos/en/checkbox/variants.tsx
new file mode 100644
index 0000000..5596de9
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/variants.tsx
@@ -0,0 +1,32 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Primary variant</p>
+        <Checkbox id="primary" name="primary" variant="primary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Primary checkbox
+          </Checkbox.Content>
+          <Description>Standard styling with default background</Description>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary variant</p>
+        <Checkbox id="secondary" name="secondary" variant="secondary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Secondary checkbox
+          </Checkbox.Content>
+          <Description>Lower emphasis variant for use in surfaces</Description>
+        </Checkbox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/checkbox/with-description.tsx b/apps/docs/src/demos/en/checkbox/with-description.tsx
new file mode 100644
index 0000000..f796ccf
--- /dev/null
+++ b/apps/docs/src/demos/en/checkbox/with-description.tsx
@@ -0,0 +1,15 @@
+import {Checkbox, Description} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <Checkbox name="description-notifications">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Email notifications
+      </Checkbox.Content>
+      <Description>Get notified when someone mentions you in a comment</Description>
+    </Checkbox>
+  );
+}
diff --git a/apps/docs/src/demos/en/chip/basic.tsx b/apps/docs/src/demos/en/chip/basic.tsx
new file mode 100644
index 0000000..80156b8
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/basic.tsx
@@ -0,0 +1,13 @@
+import {Chip} from "@heroui/react";
+
+export function ChipBasic() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Chip>Default</Chip>
+      <Chip color="accent">Accent</Chip>
+      <Chip color="success">Success</Chip>
+      <Chip color="warning">Warning</Chip>
+      <Chip color="danger">Danger</Chip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/chip/index.ts b/apps/docs/src/demos/en/chip/index.ts
new file mode 100644
index 0000000..d12f4c0
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/index.ts
@@ -0,0 +1,5 @@
+export {ChipBasic as Basic} from "./basic";
+export {ChipVariants as Variants} from "./variants";
+export {ChipWithIcon as WithIcon} from "./with-icon";
+export {ChipStatuses as Statuses} from "./statuses";
+export {ChipVibrantPalette as VibrantPalette} from "./vibrant-palette";
diff --git a/apps/docs/src/demos/en/chip/statuses.tsx b/apps/docs/src/demos/en/chip/statuses.tsx
new file mode 100644
index 0000000..c749b53
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/statuses.tsx
@@ -0,0 +1,46 @@
+import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons";
+import {Chip} from "@heroui/react";
+
+export function ChipStatuses() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <Chip variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>Default</Chip.Label>
+        </Chip>
+        <Chip color="success" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>Active</Chip.Label>
+        </Chip>
+        <Chip color="warning" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>Pending</Chip.Label>
+        </Chip>
+        <Chip color="danger" variant="primary">
+          <CircleFill width={6} />
+          <Chip.Label>Inactive</Chip.Label>
+        </Chip>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-3">
+        <Chip>
+          <CircleInfo width={12} />
+          <Chip.Label>New Feature</Chip.Label>
+        </Chip>
+        <Chip color="success">
+          <Check width={12} />
+          <Chip.Label>Available</Chip.Label>
+        </Chip>
+        <Chip color="warning">
+          <TriangleExclamation width={12} />
+          <Chip.Label>Beta</Chip.Label>
+        </Chip>
+        <Chip color="danger">
+          <Ban width={12} />
+          <Chip.Label>Deprecated</Chip.Label>
+        </Chip>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/chip/variants.tsx b/apps/docs/src/demos/en/chip/variants.tsx
new file mode 100644
index 0000000..20477ca
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/variants.tsx
@@ -0,0 +1,55 @@
+import {CircleDashed} from "@gravity-ui/icons";
+import {Chip, Separator} from "@heroui/react";
+import React from "react";
+
+export function ChipVariants() {
+  const sizes = ["lg", "md", "sm"] as const;
+  const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex flex-col gap-8 overflow-x-auto">
+      {sizes.map((size, index) => (
+        <React.Fragment key={size}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted capitalize">{size}</h3>
+            {/* Color labels header */}
+            <div className="flex items-center gap-3">
+              <div className="w-24 shrink-0" />
+              {colors.map((color) => (
+                <div
+                  key={color}
+                  className="flex shrink-0 items-center justify-center"
+                  style={{width: "130px"}}
+                >
+                  <span className="text-xs text-muted capitalize">{color}</span>
+                </div>
+              ))}
+            </div>
+            <div className="flex flex-col gap-3">
+              {variants.map((variant) => (
+                <div key={variant} className="flex items-center gap-3">
+                  <div className="w-24 shrink-0 text-sm text-muted capitalize">{variant}</div>
+                  {colors.map((color) => (
+                    <div
+                      key={color}
+                      className="flex shrink-0 items-center justify-center"
+                      style={{width: "130px"}}
+                    >
+                      <Chip color={color} size={size} variant={variant}>
+                        <CircleDashed />
+                        <Chip.Label>Label</Chip.Label>
+                        <CircleDashed />
+                      </Chip>
+                    </div>
+                  ))}
+                </div>
+              ))}
+            </div>
+          </div>
+          {index < sizes.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/chip/vibrant-palette.tsx b/apps/docs/src/demos/en/chip/vibrant-palette.tsx
new file mode 100644
index 0000000..78f903a
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/vibrant-palette.tsx
@@ -0,0 +1,52 @@
+import {Chip, Separator} from "@heroui/react";
+
+const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+function ChipMatrix({isVibrant, title}: {isVibrant?: boolean; title: string}) {
+  return (
+    <div className="flex flex-col gap-4" data-vibrant-palette={isVibrant ? "true" : undefined}>
+      <h3 className="text-sm font-semibold text-muted">{title}</h3>
+      <div className="flex items-center gap-3">
+        <div className="w-24 shrink-0" />
+        {colors.map((color) => (
+          <div
+            key={color}
+            className="flex shrink-0 items-center justify-center"
+            style={{width: "130px"}}
+          >
+            <span className="text-xs text-muted capitalize">{color}</span>
+          </div>
+        ))}
+      </div>
+      <div className="flex flex-col gap-3">
+        {variants.map((variant) => (
+          <div key={variant} className="flex items-center gap-3">
+            <div className="w-24 shrink-0 text-sm text-muted capitalize">{variant}</div>
+            {colors.map((color) => (
+              <div
+                key={color}
+                className="flex shrink-0 items-center justify-center"
+                style={{width: "130px"}}
+              >
+                <Chip color={color} size="md" variant={variant}>
+                  <Chip.Label className="capitalize">{color}</Chip.Label>
+                </Chip>
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function ChipVibrantPalette() {
+  return (
+    <div className="flex w-full flex-col gap-8 overflow-x-auto">
+      <ChipMatrix title="Default palette" />
+      <Separator />
+      <ChipMatrix isVibrant title="Vibrant palette" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/chip/with-icon.tsx b/apps/docs/src/demos/en/chip/with-icon.tsx
new file mode 100644
index 0000000..1259d64
--- /dev/null
+++ b/apps/docs/src/demos/en/chip/with-icon.tsx
@@ -0,0 +1,29 @@
+import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons";
+import {Chip} from "@heroui/react";
+
+export function ChipWithIcon() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Chip>
+        <CircleFill width={6} />
+        <Chip.Label>Information</Chip.Label>
+      </Chip>
+      <Chip color="success">
+        <CircleCheckFill width={12} />
+        <Chip.Label>Completed</Chip.Label>
+      </Chip>
+      <Chip color="warning">
+        <Clock width={12} />
+        <Chip.Label>Pending</Chip.Label>
+      </Chip>
+      <Chip color="danger">
+        <Xmark width={12} />
+        <Chip.Label>Failed</Chip.Label>
+      </Chip>
+      <Chip color="accent">
+        <Chip.Label>Label</Chip.Label>
+        <ChevronDown width={12} />
+      </Chip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/close-button/default.tsx b/apps/docs/src/demos/en/close-button/default.tsx
new file mode 100644
index 0000000..ce6d6e5
--- /dev/null
+++ b/apps/docs/src/demos/en/close-button/default.tsx
@@ -0,0 +1,5 @@
+import {CloseButton} from "@heroui/react";
+
+export function Default() {
+  return <CloseButton />;
+}
diff --git a/apps/docs/src/demos/en/close-button/index.ts b/apps/docs/src/demos/en/close-button/index.ts
new file mode 100644
index 0000000..72e71f2
--- /dev/null
+++ b/apps/docs/src/demos/en/close-button/index.ts
@@ -0,0 +1,3 @@
+export {Default} from "./default";
+export {WithCustomIcon} from "./with-custom-icon";
+export {Interactive} from "./interactive";
diff --git a/apps/docs/src/demos/en/close-button/interactive.tsx b/apps/docs/src/demos/en/close-button/interactive.tsx
new file mode 100644
index 0000000..c9394f6
--- /dev/null
+++ b/apps/docs/src/demos/en/close-button/interactive.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {CloseButton} from "@heroui/react";
+import {useState} from "react";
+
+export function Interactive() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4">
+      <CloseButton
+        aria-label={`Close (clicked ${count} times)`}
+        onPress={() => setCount(count + 1)}
+      />
+      <span className="text-sm text-muted">Clicked: {count} times</span>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/close-button/variants.tsx b/apps/docs/src/demos/en/close-button/variants.tsx
new file mode 100644
index 0000000..bec19be
--- /dev/null
+++ b/apps/docs/src/demos/en/close-button/variants.tsx
@@ -0,0 +1,12 @@
+import {CloseButton} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton />
+        <span className="text-xs text-muted">Default</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/close-button/with-custom-icon.tsx b/apps/docs/src/demos/en/close-button/with-custom-icon.tsx
new file mode 100644
index 0000000..106483d
--- /dev/null
+++ b/apps/docs/src/demos/en/close-button/with-custom-icon.tsx
@@ -0,0 +1,21 @@
+import {CircleXmark, Xmark} from "@gravity-ui/icons";
+import {CloseButton} from "@heroui/react";
+
+export function WithCustomIcon() {
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton>
+          <CircleXmark />
+        </CloseButton>
+        <span className="text-xs text-muted">Custom Icon</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <CloseButton>
+          <Xmark />
+        </CloseButton>
+        <span className="text-xs text-muted">Alternative Icon</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/basic.tsx b/apps/docs/src/demos/en/color-area/basic.tsx
new file mode 100644
index 0000000..9748d4a
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/basic.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaBasic() {
+  return (
+    <ColorArea defaultValue="rgb(116, 52, 255)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/controlled.tsx b/apps/docs/src/demos/en/color-area/controlled.tsx
new file mode 100644
index 0000000..d5f9276
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/controlled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function ColorAreaControlled() {
+  const [color, setColor] = useState<Color>(parseColor("#9B80FF"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorArea colorSpace="rgb" value={color} xChannel="red" yChannel="green" onChange={setColor}>
+        <ColorArea.Thumb />
+      </ColorArea>
+      <div className="flex w-[300px] items-center gap-3">
+        <ColorSwatch color={color} size="md" />
+        <p className="text-sm text-muted">
+          Current color:{" "}
+          <span className="font-medium">{color ? color.toString("hex") : "(empty)"}</span>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/custom-render-function.tsx b/apps/docs/src/demos/en/color-area/custom-render-function.tsx
new file mode 100644
index 0000000..1af6332
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/custom-render-function.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {ColorArea} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ColorArea
+      defaultValue="rgb(116, 52, 255)"
+      render={(props) => <div {...props} data-custom="slider" />}
+    >
+      <ColorArea.Thumb render={(props) => <div {...props} data-custom="thumb" />} />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/disabled.tsx b/apps/docs/src/demos/en/color-area/disabled.tsx
new file mode 100644
index 0000000..dcbd089
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/disabled.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaDisabled() {
+  return (
+    <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/index.ts b/apps/docs/src/demos/en/color-area/index.ts
new file mode 100644
index 0000000..641ef59
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/index.ts
@@ -0,0 +1,6 @@
+export {ColorAreaBasic as Basic} from "./basic";
+export {ColorAreaWithDots as WithDots} from "./with-dots";
+export {ColorAreaSpaceAndChannels as SpaceAndChannels} from "./space-and-channels";
+export {ColorAreaControlled as Controlled} from "./controlled";
+export {ColorAreaDisabled as Disabled} from "./disabled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/color-area/space-and-channels.tsx b/apps/docs/src/demos/en/color-area/space-and-channels.tsx
new file mode 100644
index 0000000..c36a02a
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/space-and-channels.tsx
@@ -0,0 +1,165 @@
+"use client";
+
+import type {ColorSpace, Key} from "@heroui/react";
+
+import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue";
+
+interface ChannelOption {
+  id: ColorChannel;
+  name: string;
+}
+
+const colorSpaces: Array<{id: ColorSpace; name: string}> = [
+  {id: "rgb", name: "RGB"},
+  {id: "hsl", name: "HSL"},
+  {id: "hsb", name: "HSB"},
+];
+
+const channelsBySpace: Record<ColorSpace, ChannelOption[]> = {
+  hsb: [
+    {id: "hue", name: "Hue"},
+    {id: "saturation", name: "Saturation"},
+    {id: "brightness", name: "Brightness"},
+  ],
+  hsl: [
+    {id: "hue", name: "Hue"},
+    {id: "saturation", name: "Saturation"},
+    {id: "lightness", name: "Lightness"},
+  ],
+  rgb: [
+    {id: "red", name: "Red"},
+    {id: "green", name: "Green"},
+    {id: "blue", name: "Blue"},
+  ],
+};
+
+export function ColorAreaSpaceAndChannels() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsb");
+  const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));
+
+  const channels = channelsBySpace[colorSpace];
+  const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
+  const defaultY =
+    colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";
+
+  const [xChannel, setXChannel] = useState<ColorChannel>(defaultX);
+  const [yChannel, setYChannel] = useState<ColorChannel>(defaultY);
+
+  const handleColorSpaceChange = (newSpace: Key | null) => {
+    if (!newSpace) return;
+    const space = newSpace as ColorSpace;
+
+    setColorSpace(space);
+    // Reset channels to appropriate defaults for the new color space
+    if (space === "rgb") {
+      setXChannel("blue");
+      setYChannel("green");
+    } else if (space === "hsl") {
+      setXChannel("saturation");
+      setYChannel("lightness");
+    } else {
+      setXChannel("saturation");
+      setYChannel("brightness");
+    }
+  };
+
+  // Filter out the other channel from options (can't have same channel on both axes)
+  const xChannelOptions = channels.filter((c) => c.id !== yChannel);
+  const yChannelOptions = channels.filter((c) => c.id !== xChannel);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      {/* Controls */}
+      <div className="flex gap-4">
+        {/* Color Space Select */}
+        <Select className="w-32" value={colorSpace} onChange={handleColorSpaceChange}>
+          <Label>Color Space</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {colorSpaces.map((space) => (
+                <ListBox.Item key={space.id} id={space.id} textValue={space.name}>
+                  {space.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        {/* X Channel Select */}
+        <Select
+          className="w-36"
+          value={xChannel}
+          onChange={(value) => value && setXChannel(value as ColorChannel)}
+        >
+          <Label>X Axis</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {xChannelOptions.map((channel) => (
+                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
+                  {channel.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        {/* Y Channel Select */}
+        <Select
+          className="w-36"
+          value={yChannel}
+          onChange={(value) => value && setYChannel(value as ColorChannel)}
+        >
+          <Label>Y Axis</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {yChannelOptions.map((channel) => (
+                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
+                  {channel.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+      {/* Color Area */}
+      <ColorArea
+        colorSpace={colorSpace}
+        value={color}
+        xChannel={xChannel}
+        yChannel={yChannel}
+        onChange={setColor}
+      >
+        <ColorArea.Thumb />
+      </ColorArea>
+
+      {/* Color Value Display */}
+      <div className="flex items-center gap-3">
+        <div
+          className="size-8 rounded-md border border-default"
+          style={{backgroundColor: color.toString("css")}}
+        />
+        <code className="rounded bg-default/50 px-2 py-1 text-sm">
+          {color.toString(colorSpace)}
+        </code>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-area/with-dots.tsx b/apps/docs/src/demos/en/color-area/with-dots.tsx
new file mode 100644
index 0000000..e3ea2ec
--- /dev/null
+++ b/apps/docs/src/demos/en/color-area/with-dots.tsx
@@ -0,0 +1,9 @@
+import {ColorArea} from "@heroui/react";
+
+export function ColorAreaWithDots() {
+  return (
+    <ColorArea showDots defaultValue="hsl(200, 100%, 50%)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/basic.tsx b/apps/docs/src/demos/en/color-field/basic.tsx
new file mode 100644
index 0000000..eca98a0
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/basic.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function Basic() {
+  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <ColorField className="w-[280px]" name="color" value={color} onChange={setColor}>
+      <Label>Color</Label>
+      <ColorField.Group>
+        <ColorField.Prefix>
+          <ColorSwatch color={color ?? undefined} size="xs" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+    </ColorField>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/channel-editing.tsx b/apps/docs/src/demos/en/color-field/channel-editing.tsx
new file mode 100644
index 0000000..d7215ca
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/channel-editing.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function ChannelEditing() {
+  const [color, setColor] = useState<Color | null>(parseColor("#7F007F"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-sm text-muted">Edit individual HSL channels:</p>
+      <div className="flex gap-4">
+        <ColorField
+          channel="hue"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="hue"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>Hue</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+          </ColorField.Group>
+        </ColorField>
+        <ColorField
+          channel="saturation"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="saturation"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>Saturation</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+            <ColorField.Suffix>
+              <span className="text-sm text-muted">%</span>
+            </ColorField.Suffix>
+          </ColorField.Group>
+        </ColorField>
+        <ColorField
+          channel="lightness"
+          className="w-[100px]"
+          colorSpace="hsl"
+          name="lightness"
+          value={color}
+          onChange={setColor}
+        >
+          <Label>Lightness</Label>
+          <ColorField.Group>
+            <ColorField.Input />
+            <ColorField.Suffix>
+              <span className="text-sm text-muted">%</span>
+            </ColorField.Suffix>
+          </ColorField.Group>
+        </ColorField>
+      </div>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color ?? undefined} size="md" />
+        <span className="text-sm">Current: {color ? color.toString("hex") : "(empty)"}</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/controlled.tsx b/apps/docs/src/demos/en/color-field/controlled.tsx
new file mode 100644
index 0000000..bec3ccb
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/controlled.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}>
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Prefix>
+            <ColorSwatch color={value ?? undefined} size="xs" />
+          </ColorField.Prefix>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Current value: {value ? value.toString("hex") : "(empty)"}</Description>
+      </ColorField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(parseColor("#EF4444"))}>
+          Set Red
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(parseColor("#10B981"))}>
+          Set Green
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/custom-render-function.tsx b/apps/docs/src/demos/en/color-field/custom-render-function.tsx
new file mode 100644
index 0000000..f2eaf06
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/custom-render-function.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+export function CustomRenderFunction() {
+  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));
+
+  return (
+    <ColorField
+      className="w-[280px]"
+      name="color"
+      render={(props) => <div {...props} data-custom="foo" />}
+      value={color}
+      onChange={setColor}
+    >
+      <Label>Color</Label>
+      <ColorField.Group render={(props) => <div {...props} data-custom="foo" />}>
+        <ColorField.Prefix>
+          <ColorSwatch color={color ?? undefined} size="xs" />
+        </ColorField.Prefix>
+        <ColorField.Input />
+      </ColorField.Group>
+    </ColorField>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/disabled.tsx b/apps/docs/src/demos/en/color-field/disabled.tsx
new file mode 100644
index 0000000..cf6eba9
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/disabled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isDisabled className="w-[280px]" defaultValue="#0485F7" name="color">
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>This color field is disabled</Description>
+      </ColorField>
+      <ColorField isDisabled className="w-[280px]" name="color-empty">
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>This color field is disabled</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/form-example.tsx b/apps/docs/src/demos/en/color-field/form-example.tsx
new file mode 100644
index 0000000..249e065
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/form-example.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {Color} from "@heroui/react";
+
+import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<Color | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Color submitted:", {color: value.toString("hex")});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <ColorField
+        fullWidth
+        isRequired
+        className="w-full"
+        name="brand-color"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Brand Color</Label>
+        <ColorField.Group>
+          <ColorField.Prefix>
+            <ColorSwatch color={value ?? undefined} size="xs" />
+          </ColorField.Prefix>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>Choose your brand's primary color</Description>
+      </ColorField>
+      <Button
+        className="w-full"
+        isDisabled={!value}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "Saving..." : "Save Color"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/full-width.tsx b/apps/docs/src/demos/en/color-field/full-width.tsx
new file mode 100644
index 0000000..0ded6d1
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/full-width.tsx
@@ -0,0 +1,20 @@
+import {ColorField, Label} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <ColorField fullWidth defaultValue="#10B981" name="color">
+        <Label>Brand Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField fullWidth defaultValue="#8B5CF6" name="color-with-suffix">
+        <Label>Theme Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/index.ts b/apps/docs/src/demos/en/color-field/index.ts
new file mode 100644
index 0000000..79c90ff
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {ChannelEditing} from "./channel-editing";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
diff --git a/apps/docs/src/demos/en/color-field/invalid.tsx b/apps/docs/src/demos/en/color-field/invalid.tsx
new file mode 100644
index 0000000..77993a9
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/invalid.tsx
@@ -0,0 +1,22 @@
+import {ColorField, FieldError, Label} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isInvalid isRequired className="w-[280px]" name="color">
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <FieldError>Please enter a valid hex color</FieldError>
+      </ColorField>
+      <ColorField isInvalid className="w-[280px]" name="invalid-color">
+        <Label>Background Color</Label>
+        <ColorField.Group>
+          <ColorField.Input defaultValue="not-a-color" />
+        </ColorField.Group>
+        <FieldError>Invalid color format. Use hex (e.g., #FF5733)</FieldError>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/on-surface.tsx b/apps/docs/src/demos/en/color-field/on-surface.tsx
new file mode 100644
index 0000000..c9a9a9a
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/on-surface.tsx
@@ -0,0 +1,15 @@
+import {ColorField, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-[320px] p-4">
+      <ColorField defaultValue="#3B82F6" name="color">
+        <Label>Theme Color</Label>
+        <ColorField.Group variant="secondary">
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Select your theme color</Description>
+      </ColorField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/required.tsx b/apps/docs/src/demos/en/color-field/required.tsx
new file mode 100644
index 0000000..ee729ca
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/required.tsx
@@ -0,0 +1,21 @@
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField isRequired className="w-[280px]" name="color">
+        <Label>Brand Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField isRequired className="w-[280px]" name="theme-color">
+        <Label>Theme Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>Required field</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/variants.tsx b/apps/docs/src/demos/en/color-field/variants.tsx
new file mode 100644
index 0000000..6c9ca82
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/variants.tsx
@@ -0,0 +1,20 @@
+import {ColorField, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue="#0485F7" name="primary-color">
+        <Label>Primary variant</Label>
+        <ColorField.Group variant="primary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue="#F43F5E" name="secondary-color">
+        <Label>Secondary variant</Label>
+        <ColorField.Group variant="secondary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-field/with-description.tsx b/apps/docs/src/demos/en/color-field/with-description.tsx
new file mode 100644
index 0000000..04964b7
--- /dev/null
+++ b/apps/docs/src/demos/en/color-field/with-description.tsx
@@ -0,0 +1,22 @@
+import {ColorField, Description, Label} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue="#3B82F6" name="color">
+        <Label>Primary Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Enter your brand's primary color</Description>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue="#F59E0B" name="accent-color">
+        <Label>Accent Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Used for highlights and CTAs</Description>
+      </ColorField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-picker/basic.tsx b/apps/docs/src/demos/en/color-picker/basic.tsx
new file mode 100644
index 0000000..8d8b08a
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/basic.tsx
@@ -0,0 +1,30 @@
+import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ColorPicker defaultValue="#0485F7">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover>
+        <ColorArea
+          aria-label="Color area"
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>Hue</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-picker/controlled.tsx b/apps/docs/src/demos/en/color-picker/controlled.tsx
new file mode 100644
index 0000000..fe7db6d
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/controlled.tsx
@@ -0,0 +1,95 @@
+"use client";
+
+import {
+  Button,
+  ColorArea,
+  ColorField,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  ColorSwatchPicker,
+  Label,
+  parseColor,
+} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [color, setColor] = useState(parseColor("#325578"));
+
+  const colorPresets = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+    "#f43f5e",
+  ];
+
+  const shuffleColor = () => {
+    const randomHue = Math.floor(Math.random() * 360);
+    const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
+    const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
+
+    setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorPicker value={color} onChange={setColor}>
+        <ColorPicker.Trigger>
+          <ColorSwatch size="lg" />
+          <Label>Pick a color</Label>
+        </ColorPicker.Trigger>
+        <ColorPicker.Popover className="gap-2">
+          <ColorSwatchPicker className="justify-center pt-2" size="xs">
+            {colorPresets.map((preset) => (
+              <ColorSwatchPicker.Item key={preset} color={preset}>
+                <ColorSwatchPicker.Swatch />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+          <ColorArea
+            aria-label="Color area"
+            className="max-w-full"
+            colorSpace="hsb"
+            xChannel="saturation"
+            yChannel="brightness"
+          >
+            <ColorArea.Thumb />
+          </ColorArea>
+          <div className="flex items-center gap-2 px-1">
+            <ColorSlider aria-label="Hue slider" channel="hue" className="flex-1" colorSpace="hsb">
+              <ColorSlider.Track>
+                <ColorSlider.Thumb />
+              </ColorSlider.Track>
+            </ColorSlider>
+            <Button
+              isIconOnly
+              aria-label="Shuffle color"
+              size="sm"
+              variant="tertiary"
+              onPress={shuffleColor}
+            >
+              <Icon className="size-4" icon="gravity-ui:shuffle" />
+            </Button>
+          </div>
+          <ColorField aria-label="Color field">
+            <ColorField.Group variant="secondary">
+              <ColorField.Prefix>
+                <ColorSwatch size="xs" />
+              </ColorField.Prefix>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+        </ColorPicker.Popover>
+      </ColorPicker>
+      <p className="w-60 text-sm text-muted">
+        Selected: <span className="font-medium">{color.toString("hex")}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-picker/index.ts b/apps/docs/src/demos/en/color-picker/index.ts
new file mode 100644
index 0000000..f49dfbc
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/index.ts
@@ -0,0 +1,5 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {WithSwatches} from "./with-swatches";
+export {WithFields} from "./with-fields";
+export {WithSliders} from "./with-sliders";
diff --git a/apps/docs/src/demos/en/color-picker/with-fields.tsx b/apps/docs/src/demos/en/color-picker/with-fields.tsx
new file mode 100644
index 0000000..b261b66
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/with-fields.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import type {ColorChannel, ColorSpace} from "@heroui/react";
+
+import {
+  ColorArea,
+  ColorField,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+import {useState} from "react";
+
+export function WithFields() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");
+
+  const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+    hsb: ["hue", "saturation", "brightness"],
+    hsl: ["hue", "saturation", "lightness"],
+    rgb: ["red", "green", "blue"],
+  };
+
+  return (
+    <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="max-w-62 gap-2">
+        <ColorArea
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>Hue</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <Select
+          aria-label="Color space"
+          value={colorSpace}
+          variant="secondary"
+          onChange={(value) => setColorSpace(value as ColorSpace)}
+        >
+          <Select.Trigger>
+            <Select.Value className="uppercase" />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {Object.keys(colorChannelsByColorSpace).map((space) => (
+                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
+                  {space}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <div className="grid w-full grid-cols-3 items-center gap-2">
+          {colorChannelsByColorSpace[colorSpace].map((channel) => (
+            <ColorField
+              key={channel}
+              aria-label={channel}
+              channel={channel}
+              colorSpace={colorSpace}
+            >
+              <ColorField.Group variant="secondary">
+                <ColorField.Input />
+              </ColorField.Group>
+            </ColorField>
+          ))}
+        </div>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-picker/with-sliders.tsx b/apps/docs/src/demos/en/color-picker/with-sliders.tsx
new file mode 100644
index 0000000..6c83f87
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/with-sliders.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import type {ColorChannel, ColorSpace} from "@heroui/react";
+
+import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSliders() {
+  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");
+
+  const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+    hsb: ["hue", "saturation", "brightness", "alpha"],
+    hsl: ["hue", "saturation", "lightness", "alpha"],
+    rgb: ["red", "green", "blue", "alpha"],
+  };
+
+  return (
+    <ColorPicker defaultValue="hsl(219, 58%, 93%)">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover className="max-w-62 gap-2 px-2 py-3">
+        <Select
+          aria-label="Color space"
+          value={colorSpace}
+          variant="secondary"
+          onChange={(value) => setColorSpace(value as ColorSpace)}
+        >
+          <Select.Trigger>
+            <Select.Value className="uppercase" />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {Object.keys(colorChannelsByColorSpace).map((space) => (
+                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
+                  {space}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <div className="flex flex-col gap-2">
+          {colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
+            // @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
+            <ColorSlider
+              key={channel}
+              aria-label={channel}
+              channel={channel}
+              className="gap-1 px-1"
+              colorSpace={colorSpace}
+            >
+              <Label className="capitalize">{channel}</Label>
+              <ColorSlider.Output className="text-muted" />
+              <ColorSlider.Track>
+                <ColorSlider.Thumb />
+              </ColorSlider.Track>
+            </ColorSlider>
+          ))}
+        </div>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-picker/with-swatches.tsx b/apps/docs/src/demos/en/color-picker/with-swatches.tsx
new file mode 100644
index 0000000..b55b3f5
--- /dev/null
+++ b/apps/docs/src/demos/en/color-picker/with-swatches.tsx
@@ -0,0 +1,56 @@
+import {
+  ColorArea,
+  ColorPicker,
+  ColorSlider,
+  ColorSwatch,
+  ColorSwatchPicker,
+  Label,
+} from "@heroui/react";
+
+export function WithSwatches() {
+  const presets = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+    "#f43f5e",
+  ];
+
+  return (
+    <ColorPicker defaultValue="#F43F5E">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>Brand Color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover>
+        <ColorArea
+          aria-label="Color area"
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider aria-label="Hue slider" channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>Hue</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSwatchPicker className="justify-center px-1" size="xs">
+          {presets.map((preset) => (
+            <ColorSwatchPicker.Item key={preset} color={preset}>
+              <ColorSwatchPicker.Swatch />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/alpha-channel.tsx b/apps/docs/src/demos/en/color-slider/alpha-channel.tsx
new file mode 100644
index 0000000..4b6f749
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/alpha-channel.tsx
@@ -0,0 +1,13 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function AlphaChannel() {
+  return (
+    <ColorSlider channel="alpha" className="w-full max-w-xs" defaultValue="hsla(0, 100%, 50%, 0.5)">
+      <Label>Alpha</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/basic.tsx b/apps/docs/src/demos/en/color-slider/basic.tsx
new file mode 100644
index 0000000..64649b8
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/basic.tsx
@@ -0,0 +1,13 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ColorSlider channel="hue" className="w-full max-w-xs" defaultValue="hsl(0, 100%, 50%)">
+      <Label>Hue</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/channels.tsx b/apps/docs/src/demos/en/color-slider/channels.tsx
new file mode 100644
index 0000000..f941bc1
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/channels.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function Channels() {
+  const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="hue" value={color} onChange={setColor}>
+        <Label>Hue</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="saturation" value={color} onChange={setColor}>
+        <Label>Saturation</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="lightness" value={color} onChange={setColor}>
+        <Label>Lightness</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          Current color: <code className="font-mono">{color.toString("hsl")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/controlled.tsx b/apps/docs/src/demos/en/color-slider/controlled.tsx
new file mode 100644
index 0000000..5d516e0
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/controlled.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function Controlled() {
+  const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="hue" value={color} onChange={setColor}>
+        <Label>Hue</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          Current color: <code className="font-mono">{color.toString("hsl")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/custom-render-function.tsx b/apps/docs/src/demos/en/color-slider/custom-render-function.tsx
new file mode 100644
index 0000000..d3be5b9
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {ColorSlider, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ColorSlider
+      channel="hue"
+      className="w-full max-w-xs"
+      defaultValue="hsl(0, 100%, 50%)"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>Hue</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/disabled.tsx b/apps/docs/src/demos/en/color-slider/disabled.tsx
new file mode 100644
index 0000000..aa110e0
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/disabled.tsx
@@ -0,0 +1,18 @@
+import {ColorSlider, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <ColorSlider
+      isDisabled
+      channel="hue"
+      className="w-full max-w-xs"
+      defaultValue="hsl(200, 100%, 50%)"
+    >
+      <Label>Hue</Label>
+      <ColorSlider.Output />
+      <ColorSlider.Track>
+        <ColorSlider.Thumb />
+      </ColorSlider.Track>
+    </ColorSlider>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/index.ts b/apps/docs/src/demos/en/color-slider/index.ts
new file mode 100644
index 0000000..83c5a7e
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/index.ts
@@ -0,0 +1,9 @@
+// ColorSlider demos
+export {Basic} from "./basic";
+export {Channels} from "./channels";
+export {AlphaChannel} from "./alpha-channel";
+export {RGBChannels} from "./rgb-channels";
+export {Vertical} from "./vertical";
+export {Disabled} from "./disabled";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/color-slider/rgb-channels.tsx b/apps/docs/src/demos/en/color-slider/rgb-channels.tsx
new file mode 100644
index 0000000..c56181b
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/rgb-channels.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
+import {useState} from "react";
+import {parseColor} from "react-aria-components";
+
+export function RGBChannels() {
+  const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));
+
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-4">
+      <ColorSlider channel="red" value={color} onChange={setColor}>
+        <Label>Red</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="green" value={color} onChange={setColor}>
+        <Label>Green</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider channel="blue" value={color} onChange={setColor}>
+        <Label>Blue</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <div className="flex items-center gap-2">
+        <ColorSwatch color={color} size="sm" />
+        <p className="text-sm text-muted">
+          Current color: <code className="font-mono">{color.toString("rgb")}</code>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-slider/vertical.tsx b/apps/docs/src/demos/en/color-slider/vertical.tsx
new file mode 100644
index 0000000..9dbba82
--- /dev/null
+++ b/apps/docs/src/demos/en/color-slider/vertical.tsx
@@ -0,0 +1,38 @@
+import {ColorSlider} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="flex h-48 gap-4">
+      <ColorSlider
+        aria-label="Hue"
+        channel="hue"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider
+        aria-label="Saturation"
+        channel="saturation"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+      <ColorSlider
+        aria-label="Lightness"
+        channel="lightness"
+        defaultValue="hsl(0, 100%, 50%)"
+        orientation="vertical"
+      >
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/basic.tsx b/apps/docs/src/demos/en/color-swatch-picker/basic.tsx
new file mode 100644
index 0000000..076bcfb
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/basic.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Basic() {
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/controlled.tsx b/apps/docs/src/demos/en/color-swatch-picker/controlled.tsx
new file mode 100644
index 0000000..81aa6a4
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/controlled.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {ColorSwatchPicker, parseColor} from "@heroui/react";
+import {useState} from "react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Controlled() {
+  const [value, setValue] = useState(parseColor("#F43F5E"));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ColorSwatchPicker value={value} onChange={setValue}>
+        {colors.map((color) => (
+          <ColorSwatchPicker.Item key={color} color={color}>
+            <ColorSwatchPicker.Swatch />
+            <ColorSwatchPicker.Indicator />
+          </ColorSwatchPicker.Item>
+        ))}
+      </ColorSwatchPicker>
+      <p className="text-sm text-muted">
+        Selected: <span className="font-medium">{value.toString("hex")}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/custom-indicator.tsx b/apps/docs/src/demos/en/color-swatch-picker/custom-indicator.tsx
new file mode 100644
index 0000000..8b41379
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/custom-indicator.tsx
@@ -0,0 +1,19 @@
+import {HeartFill} from "@gravity-ui/icons";
+import {ColorSwatchPicker} from "@heroui/react";
+
+export function CustomIndicator() {
+  const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator>
+            <HeartFill />
+          </ColorSwatchPicker.Indicator>
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/custom-render-function.tsx b/apps/docs/src/demos/en/color-swatch-picker/custom-render-function.tsx
new file mode 100644
index 0000000..89c87ed
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function CustomRenderFunction() {
+  return (
+    <ColorSwatchPicker render={(props) => <div {...props} data-custom="foo" />}>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/default-value.tsx b/apps/docs/src/demos/en/color-swatch-picker/default-value.tsx
new file mode 100644
index 0000000..33fbac6
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/default-value.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function DefaultValue() {
+  return (
+    <ColorSwatchPicker defaultValue="#8B5CF6">
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/disabled.tsx b/apps/docs/src/demos/en/color-swatch-picker/disabled.tsx
new file mode 100644
index 0000000..ca08b5d
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/disabled.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Disabled() {
+  return (
+    <ColorSwatchPicker>
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} isDisabled color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/index.ts b/apps/docs/src/demos/en/color-swatch-picker/index.ts
new file mode 100644
index 0000000..2cf7794
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {Sizes} from "./sizes";
+export {StackLayout} from "./stack-layout";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/color-swatch-picker/sizes.tsx b/apps/docs/src/demos/en/color-swatch-picker/sizes.tsx
new file mode 100644
index 0000000..86f8197
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/sizes.tsx
@@ -0,0 +1,25 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      {sizes.map((size) => (
+        <div key={size} className="flex items-center gap-4">
+          <span className="w-8 text-sm text-muted">{size}</span>
+          <ColorSwatchPicker size={size}>
+            {colors.map((color) => (
+              <ColorSwatchPicker.Item key={color} color={color}>
+                <ColorSwatchPicker.Swatch />
+                <ColorSwatchPicker.Indicator />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/stack-layout.tsx b/apps/docs/src/demos/en/color-swatch-picker/stack-layout.tsx
new file mode 100644
index 0000000..403838b
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/stack-layout.tsx
@@ -0,0 +1,16 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function StackLayout() {
+  return (
+    <ColorSwatchPicker layout="stack">
+      {colors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch-picker/variants.tsx b/apps/docs/src/demos/en/color-swatch-picker/variants.tsx
new file mode 100644
index 0000000..6c5bec3
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch-picker/variants.tsx
@@ -0,0 +1,32 @@
+import {ColorSwatchPicker} from "@heroui/react";
+
+const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Circle (default)</span>
+        <ColorSwatchPicker variant="circle">
+          {colors.map((color) => (
+            <ColorSwatchPicker.Item key={color} color={color}>
+              <ColorSwatchPicker.Swatch />
+              <ColorSwatchPicker.Indicator />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Square</span>
+        <ColorSwatchPicker variant="square">
+          {colors.map((color) => (
+            <ColorSwatchPicker.Item key={color} color={color}>
+              <ColorSwatchPicker.Swatch />
+              <ColorSwatchPicker.Indicator />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/accessibility.tsx b/apps/docs/src/demos/en/color-swatch/accessibility.tsx
new file mode 100644
index 0000000..10e9eb3
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/accessibility.tsx
@@ -0,0 +1,11 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchAccessibility() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="Primary brand color" color="#0485F7" colorName="Ocean Blue" />
+      <ColorSwatch aria-label="Error state color" color="#EF4444" colorName="Coral Red" />
+      <ColorSwatch aria-label="Warning color" color="#F59E0B" colorName="Sunset Orange" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/basic.tsx b/apps/docs/src/demos/en/color-swatch/basic.tsx
new file mode 100644
index 0000000..83e53ac
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/basic.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchBasic() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="Blue" color="#0485F7" />
+      <ColorSwatch aria-label="Red" color="#EF4444" />
+      <ColorSwatch aria-label="Amber" color="#F59E0B" />
+      <ColorSwatch aria-label="Green" color="#10B981" />
+      <ColorSwatch aria-label="Fuchsia" color="#D946EF" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/custom-render-function.tsx b/apps/docs/src/demos/en/color-swatch/custom-render-function.tsx
new file mode 100644
index 0000000..bd7d064
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/custom-render-function.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {ColorSwatch} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch
+        aria-label="Blue"
+        color="#0485F7"
+        render={(props) => <div {...props} data-custom="blue" />}
+      />
+      <ColorSwatch
+        aria-label="Red"
+        color="#EF4444"
+        render={(props) => <div {...props} data-custom="red" />}
+      />
+      <ColorSwatch
+        aria-label="Amber"
+        color="#F59E0B"
+        render={(props) => <div {...props} data-custom="amber" />}
+      />
+      <ColorSwatch
+        aria-label="Green"
+        color="#10B981"
+        render={(props) => <div {...props} data-custom="green" />}
+      />
+      <ColorSwatch
+        aria-label="Fuchsia"
+        color="#D946EF"
+        render={(props) => <div {...props} data-custom="fuchsia" />}
+      />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/custom-styles.tsx b/apps/docs/src/demos/en/color-swatch/custom-styles.tsx
new file mode 100644
index 0000000..e38b81f
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/custom-styles.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchCustomStyles() {
+  const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
+
+  return (
+    <div className="flex flex-col gap-8">
+      {/* Glow effect */}
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Glow Effect</span>
+        <div className="flex items-center gap-4">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="xl"
+              style={() => ({
+                boxShadow: `0 0 20px 2px ${color}`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Gradient swatch */}
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Gradient</span>
+        <div className="flex items-center gap-4">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="xl"
+              style={({color: c}) => ({
+                background: `linear-gradient(135deg, ${c.toString("css")}, white)`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/index.ts b/apps/docs/src/demos/en/color-swatch/index.ts
new file mode 100644
index 0000000..25db5d0
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/index.ts
@@ -0,0 +1,7 @@
+export {ColorSwatchBasic as Basic} from "./basic";
+export {ColorSwatchSizes as Sizes} from "./sizes";
+export {ColorSwatchShapes as Shapes} from "./shapes";
+export {ColorSwatchTransparency as Transparency} from "./transparency";
+export {ColorSwatchCustomStyles as CustomStyles} from "./custom-styles";
+export {ColorSwatchAccessibility as Accessibility} from "./accessibility";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/color-swatch/shapes.tsx b/apps/docs/src/demos/en/color-swatch/shapes.tsx
new file mode 100644
index 0000000..8f3da77
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/shapes.tsx
@@ -0,0 +1,10 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchShapes() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch color="#0485F7" shape="circle" />
+      <ColorSwatch color="#0485F7" shape="square" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/sizes.tsx b/apps/docs/src/demos/en/color-swatch/sizes.tsx
new file mode 100644
index 0000000..a076279
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/sizes.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchSizes() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch color="#0485F7" size="xs" />
+      <ColorSwatch color="#EF4444" size="sm" />
+      <ColorSwatch color="#F59E0B" size="md" />
+      <ColorSwatch color="#10B981" size="lg" />
+      <ColorSwatch color="#D946EF" size="xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/color-swatch/transparency.tsx b/apps/docs/src/demos/en/color-swatch/transparency.tsx
new file mode 100644
index 0000000..9b874ee
--- /dev/null
+++ b/apps/docs/src/demos/en/color-swatch/transparency.tsx
@@ -0,0 +1,13 @@
+import {ColorSwatch} from "@heroui/react";
+
+export function ColorSwatchTransparency() {
+  return (
+    <div className="flex items-center gap-3">
+      <ColorSwatch aria-label="100% opacity" color="rgba(4, 133, 247, 1)" />
+      <ColorSwatch aria-label="75% opacity" color="rgba(4, 133, 247, 0.75)" />
+      <ColorSwatch aria-label="50% opacity" color="rgba(4, 133, 247, 0.5)" />
+      <ColorSwatch aria-label="25% opacity" color="rgba(4, 133, 247, 0.25)" />
+      <ColorSwatch aria-label="0% opacity" color="rgba(4, 133, 247, 0)" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/allows-custom-value.tsx b/apps/docs/src/demos/en/combo-box/allows-custom-value.tsx
new file mode 100644
index 0000000..c0ed39f
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/allows-custom-value.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function AllowsCustomValue() {
+  return (
+    <ComboBox allowsCustomValue className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search or type an animal..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>You can type any animal name, even if it's not in the list</Description>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/asynchronous-loading.tsx b/apps/docs/src/demos/en/combo-box/asynchronous-loading.tsx
new file mode 100644
index 0000000..458f4d3
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/asynchronous-loading.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import {
+  Collection,
+  ComboBox,
+  EmptyState,
+  Input,
+  Label,
+  ListBox,
+  ListBoxLoadMoreItem,
+  Spinner,
+} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+
+interface Character {
+  name: string;
+}
+
+export function AsynchronousLoading() {
+  const list = useAsyncList<Character>({
+    async load({cursor, filterText, signal}) {
+      if (cursor) {
+        cursor = cursor.replace(/^http:\/\//i, "https://");
+      }
+
+      const res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, {
+        signal,
+      });
+      const json = await res.json();
+
+      return {
+        cursor: json.next,
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <ComboBox
+      allowsEmptyCollection
+      className="w-[256px]"
+      inputValue={list.filterText}
+      onInputChange={list.setFilterText}
+    >
+      <Label>Pick a Character</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Star Wars characters..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox renderEmptyState={() => <EmptyState />}>
+          <Collection items={list.items}>
+            {(item) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="muted text-sm">Loading more...</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/controlled-input-value.tsx b/apps/docs/src/demos/en/combo-box/controlled-input-value.tsx
new file mode 100644
index 0000000..511ca10
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/controlled-input-value.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledInputValue() {
+  const [inputValue, setInputValue] = useState("");
+
+  return (
+    <div className="space-y-2">
+      <ComboBox className="w-[256px]" inputValue={inputValue} onInputChange={setInputValue}>
+        <Label>Search (controlled input)</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Type to search..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="Aardvark">
+              Aardvark
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="Kangaroo">
+              Kangaroo
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="panda" textValue="Panda">
+              Panda
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="snake" textValue="Snake">
+              Snake
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+      <p className="text-sm text-muted">Input value: {inputValue || "(empty)"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/controlled.tsx b/apps/docs/src/demos/en/combo-box/controlled.tsx
new file mode 100644
index 0000000..70f0efd
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/controlled.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const animals = [
+    {
+      id: "cat",
+      name: "Cat",
+    },
+    {
+      id: "dog",
+      name: "Dog",
+    },
+    {
+      id: "bird",
+      name: "Bird",
+    },
+    {
+      id: "fish",
+      name: "Fish",
+    },
+    {
+      id: "hamster",
+      name: "Hamster",
+    },
+  ];
+
+  const [selectedKey, setSelectedKey] = useState<Key | null>("cat");
+
+  const selectedAnimal = animals.find((a) => a.id === selectedKey);
+
+  return (
+    <div className="space-y-2">
+      <ComboBox
+        className="w-[256px]"
+        selectedKey={selectedKey}
+        onSelectionChange={(key) => setSelectedKey(key)}
+      >
+        <Label>Animal (controlled)</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            {animals.map((animal) => (
+              <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+                {animal.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+      <p className="text-sm text-muted">Selected: {selectedAnimal?.name || "None"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/custom-filtering.tsx b/apps/docs/src/demos/en/combo-box/custom-filtering.tsx
new file mode 100644
index 0000000..4f9fc1d
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/custom-filtering.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomFiltering() {
+  const animals = [
+    {id: "cat", name: "Cat"},
+    {id: "dog", name: "Dog"},
+    {id: "bird", name: "Bird"},
+    {id: "fish", name: "Fish"},
+    {id: "hamster", name: "Hamster"},
+  ];
+
+  return (
+    <ComboBox
+      className="w-[256px]"
+      defaultFilter={(text, inputValue) => {
+        if (!inputValue) return true;
+
+        return text.toLowerCase().includes(inputValue.toLowerCase());
+      }}
+    >
+      <Label>Animal (custom filter)</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          {animals.map((animal) => (
+            <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+              {animal.name}
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/custom-indicator.tsx b/apps/docs/src/demos/en/combo-box/custom-indicator.tsx
new file mode 100644
index 0000000..1f48b57
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/custom-indicator.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger className="size-3">
+          <ChevronsExpandVertical />
+        </ComboBox.Trigger>
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/custom-render-function.tsx b/apps/docs/src/demos/en/combo-box/custom-render-function.tsx
new file mode 100644
index 0000000..2820fc3
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/custom-render-function.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ComboBox className="w-[256px]" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/custom-value.tsx b/apps/docs/src/demos/en/combo-box/custom-value.tsx
new file mode 100644
index 0000000..12fa61f
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/custom-value.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  ComboBox,
+  Description,
+  Input,
+  Label,
+  ListBox,
+} from "@heroui/react";
+
+export function CustomValue() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>User</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search users..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/default-selected-key.tsx b/apps/docs/src/demos/en/combo-box/default-selected-key.tsx
new file mode 100644
index 0000000..ba8b2d1
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/default-selected-key.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function DefaultSelectedKey() {
+  return (
+    <ComboBox className="w-[256px]" defaultSelectedKey="cat">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/default.tsx b/apps/docs/src/demos/en/combo-box/default.tsx
new file mode 100644
index 0000000..b52ce8c
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/default.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function Default() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/disabled.tsx b/apps/docs/src/demos/en/combo-box/disabled.tsx
new file mode 100644
index 0000000..892dffe
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/disabled.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <ComboBox isDisabled className="w-[256px]" defaultSelectedKey="cat">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/full-width.tsx b/apps/docs/src/demos/en/combo-box/full-width.tsx
new file mode 100644
index 0000000..a45130b
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/full-width.tsx
@@ -0,0 +1,31 @@
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <ComboBox fullWidth>
+        <Label>Favorite Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="Aardvark">
+              Aardvark
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/index.ts b/apps/docs/src/demos/en/combo-box/index.ts
new file mode 100644
index 0000000..160d052
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/index.ts
@@ -0,0 +1,19 @@
+// ComboBox demos
+export {AllowsCustomValue} from "./allows-custom-value";
+export {AsynchronousLoading} from "./asynchronous-loading";
+export {Controlled} from "./controlled";
+export {ControlledInputValue} from "./controlled-input-value";
+export {CustomFiltering} from "./custom-filtering";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomValue} from "./custom-value";
+export {Default} from "./default";
+export {DefaultSelectedKey} from "./default-selected-key";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {MenuTrigger} from "./menu-trigger";
+export {Required} from "./required";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/en/combo-box/menu-trigger.tsx b/apps/docs/src/demos/en/combo-box/menu-trigger.tsx
new file mode 100644
index 0000000..c19522d
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/menu-trigger.tsx
@@ -0,0 +1,131 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function MenuTrigger() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Focus (default)</p>
+        <ComboBox className="w-[256px]" menuTrigger="focus">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>Popover opens when the input is focused</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Input</p>
+        <ComboBox className="w-[256px]" menuTrigger="input">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>Popover opens when the user edits the input text</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Manual</p>
+        <ComboBox className="w-[256px]" menuTrigger="manual">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>
+            Popover only opens when the trigger button is pressed or arrow keys are used
+          </Description>
+        </ComboBox>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/on-surface.tsx b/apps/docs/src/demos/en/combo-box/on-surface.tsx
new file mode 100644
index 0000000..80f1825
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/on-surface.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Button, ComboBox, FieldError, Form, Input, Label, ListBox, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Surface className="w-[320px] rounded-3xl p-6">
+      <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}>
+        <ComboBox isRequired className="w-full" name="animal" variant="secondary">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/required.tsx b/apps/docs/src/demos/en/combo-box/required.tsx
new file mode 100644
index 0000000..37087d8
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/required.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <ComboBox isRequired className="w-full" name="animal">
+        <Label>Favorite Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="Aardvark">
+              Aardvark
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="kangaroo" textValue="Kangaroo">
+              Kangaroo
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="panda" textValue="Panda">
+              Panda
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="snake" textValue="Snake">
+              Snake
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/with-description.tsx b/apps/docs/src/demos/en/combo-box/with-description.tsx
new file mode 100644
index 0000000..5da7a3f
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/with-description.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>Search and select your favorite animal</Description>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/with-disabled-options.tsx b/apps/docs/src/demos/en/combo-box/with-disabled-options.tsx
new file mode 100644
index 0000000..085e365
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/with-disabled-options.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {ComboBox, Input, Label, ListBox} from "@heroui/react";
+
+export function WithDisabledOptions() {
+  return (
+    <ComboBox className="w-[256px]" disabledKeys={["cat", "kangaroo"]}>
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="Bird">
+            Bird
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="Elephant">
+            Elephant
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="Tiger">
+            Tiger
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/combo-box/with-sections.tsx b/apps/docs/src/demos/en/combo-box/with-sections.tsx
new file mode 100644
index 0000000..203535e
--- /dev/null
+++ b/apps/docs/src/demos/en/combo-box/with-sections.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import {ComboBox, Header, Input, Label, ListBox, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <ComboBox className="w-[256px]">
+      <Label>Country</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search countries..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="Mexico">
+              Mexico
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="Germany">
+              Germany
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Asia</Header>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="China">
+              China
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="India">
+              India
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="South Korea">
+              South Korea
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/basic.tsx b/apps/docs/src/demos/en/date-field/basic.tsx
new file mode 100644
index 0000000..aa3e7b3
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/controlled.tsx b/apps/docs/src/demos/en/date-field/controlled.tsx
new file mode 100644
index 0000000..28f9afd
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/controlled.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, DateField, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<DateValue | null>(null);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="date" value={value} onChange={setValue}>
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+      </DateField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
+          Set today
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/custom-render-function.tsx b/apps/docs/src/demos/en/date-field/custom-render-function.tsx
new file mode 100644
index 0000000..78b2359
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DateField
+      className="w-[256px]"
+      name="date"
+      render={(props) => <div {...props} data-custom="date-field" />}
+    >
+      <Label render={(props) => <span {...props} data-custom="date-field-label" />}>Date</Label>
+      <DateField.Group render={(props) => <div {...props} data-custom="date-field-group" />}>
+        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/disabled.tsx b/apps/docs/src/demos/en/date-field/disabled.tsx
new file mode 100644
index 0000000..05200fb
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/disabled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isDisabled className="w-[256px]" name="date" value={today(getLocalTimeZone())}>
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>This date field is disabled</Description>
+      </DateField>
+      <DateField isDisabled className="w-[256px]" name="date-empty">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>This date field is disabled</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/form-example.tsx b/apps/docs/src/demos/en/date-field/form-example.tsx
new file mode 100644
index 0000000..e7258c4
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/form-example.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar} from "@gravity-ui/icons";
+import {Button, DateField, Description, FieldError, Form, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const todayDate = today(getLocalTimeZone());
+  const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Date submitted:", {date: value});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <DateField
+        isRequired
+        className="w-full"
+        isInvalid={isInvalid}
+        minValue={todayDate}
+        name="date"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Appointment date</Label>
+        <DateField.Group>
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Date must be today or in the future</FieldError>
+        ) : (
+          <Description>Enter a date from today onwards</Description>
+        )}
+      </DateField>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/full-width.tsx b/apps/docs/src/demos/en/date-field/full-width.tsx
new file mode 100644
index 0000000..80694cd
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/full-width.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Calendar, ChevronDown} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <DateField fullWidth name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField fullWidth name="date-icons">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <ChevronDown className="size-4 text-muted" />
+          </DateField.Suffix>
+        </DateField.Group>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/granularity.tsx b/apps/docs/src/demos/en/date-field/granularity.tsx
new file mode 100644
index 0000000..381a58b
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/granularity.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {CircleQuestion} from "@gravity-ui/icons";
+import {DateField, Label, ListBox, Select, Tooltip} from "@heroui/react";
+import {parseDate, parseZonedDateTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function Granularity() {
+  const granularityOptions = [
+    {id: "day", label: "Day"},
+    {id: "hour", label: "Hour"},
+    {id: "minute", label: "Minute"},
+    {id: "second", label: "Second"},
+  ] as const;
+
+  const [granularity, setGranularity] = useState<"day" | "hour" | "minute" | "second">("day");
+
+  // Determine appropriate default value based on granularity
+  let defaultValue: DateValue;
+
+  if (granularity === "day") {
+    defaultValue = parseDate("2025-02-03");
+  } else {
+    // hour, minute, second
+    defaultValue = parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]");
+  }
+
+  return (
+    <div className="flex gap-4">
+      <DateField
+        className="w-[256px]"
+        defaultValue={defaultValue}
+        granularity={granularity}
+        name="granularity-date"
+      >
+        <Label>Appointment Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-2">
+          <Label>Granularity</Label>
+          <Tooltip delay={0}>
+            <Tooltip.Trigger aria-label="Granularity information">
+              <CircleQuestion className="size-4 text-muted" />
+            </Tooltip.Trigger>
+            <Tooltip.Content placement="bottom start">
+              <p>
+                Determines the smallest unit displayed in the date picker. By default, this is "day"
+                for dates, and "minute" for times.
+              </p>
+            </Tooltip.Content>
+          </Tooltip>
+        </div>
+        <Select
+          className="w-[110px]"
+          placeholder="Select granularity"
+          value={granularity}
+          variant="secondary"
+          onChange={(value) => setGranularity(value as typeof granularity)}
+        >
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {granularityOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.label}>
+                  {option.label}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/index.ts b/apps/docs/src/demos/en/date-field/index.ts
new file mode 100644
index 0000000..417bb1c
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/index.ts
@@ -0,0 +1,16 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Granularity} from "./granularity";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/en/date-field/invalid.tsx b/apps/docs/src/demos/en/date-field/invalid.tsx
new file mode 100644
index 0000000..ad65148
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/invalid.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {DateField, FieldError, Label} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isInvalid isRequired className="w-[256px]" name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>Please enter a valid date</FieldError>
+      </DateField>
+      <DateField isInvalid className="w-[256px]" name="invalid-date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>Date must be in the future</FieldError>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/on-surface.tsx b/apps/docs/src/demos/en/date-field/on-surface.tsx
new file mode 100644
index 0000000..29e5546
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/on-surface.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Description, Label, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <DateField className="w-full" name="date">
+        <Label>Date</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter a date</Description>
+      </DateField>
+      <DateField className="w-full" name="date-2">
+        <Label>Appointment date</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Prefix>
+            <Calendar className="size-4 text-muted" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter a date for your appointment</Description>
+      </DateField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/required.tsx b/apps/docs/src/demos/en/date-field/required.tsx
new file mode 100644
index 0000000..690dc03
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/required.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField isRequired className="w-[256px]" name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField isRequired className="w-[256px]" name="start-date">
+        <Label>Start date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Required field</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/variants.tsx b/apps/docs/src/demos/en/date-field/variants.tsx
new file mode 100644
index 0000000..a954d7f
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/variants.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {DateField, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="primary-date">
+        <Label>Primary variant</Label>
+        <DateField.Group variant="primary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField className="w-[256px]" name="secondary-date">
+        <Label>Secondary variant</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/with-description.tsx b/apps/docs/src/demos/en/date-field/with-description.tsx
new file mode 100644
index 0000000..663a904
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/with-description.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {DateField, Description, Label} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="date">
+        <Label>Birth date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter your date of birth</Description>
+      </DateField>
+      <DateField className="w-[256px]" name="appointment-date">
+        <Label>Appointment date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter a date for your appointment</Description>
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/with-prefix-and-suffix.tsx b/apps/docs/src/demos/en/date-field/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..e021912
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/with-prefix-and-suffix.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Calendar, ChevronDown} from "@gravity-ui/icons";
+import {DateField, Description, Label} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <ChevronDown className="size-4 text-muted" />
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Enter a date</Description>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/with-prefix-icon.tsx b/apps/docs/src/demos/en/date-field/with-prefix-icon.tsx
new file mode 100644
index 0000000..10a17de
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/with-prefix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/with-suffix-icon.tsx b/apps/docs/src/demos/en/date-field/with-suffix-icon.tsx
new file mode 100644
index 0000000..b7bd2a5
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/with-suffix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Calendar} from "@gravity-ui/icons";
+import {DateField, Label} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <Calendar className="size-4 text-muted" />
+        </DateField.Suffix>
+      </DateField.Group>
+    </DateField>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-field/with-validation.tsx b/apps/docs/src/demos/en/date-field/with-validation.tsx
new file mode 100644
index 0000000..2f6d3a1
--- /dev/null
+++ b/apps/docs/src/demos/en/date-field/with-validation.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {DateField, Description, FieldError, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const todayDate = today(getLocalTimeZone());
+  const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DateField
+        isRequired
+        className="w-[256px]"
+        isInvalid={isInvalid}
+        minValue={todayDate}
+        name="date"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Date must be today or in the future</FieldError>
+        ) : (
+          <Description>Enter a date from today onwards</Description>
+        )}
+      </DateField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/basic.tsx b/apps/docs/src/demos/en/date-picker/basic.tsx
new file mode 100644
index 0000000..64cd098
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/basic.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DatePicker className="w-72" name="date">
+      <Label>Date</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Event date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/controlled.tsx b/apps/docs/src/demos/en/date-picker/controlled.tsx
new file mode 100644
index 0000000..4af9852
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/controlled.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<DateValue | null>(today(getLocalTimeZone()));
+
+  return (
+    <div className="flex w-72 flex-col gap-4">
+      <DatePicker name="date" value={value} onChange={setValue}>
+        <Label>Date</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <Calendar aria-label="Event date">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+      <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
+          Set today
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/custom-render-function.tsx b/apps/docs/src/demos/en/date-picker/custom-render-function.tsx
new file mode 100644
index 0000000..43132a6
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/custom-render-function.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DatePicker
+      className="w-72"
+      name="date"
+      render={(props) => <div {...props} data-custom="date-picker" />}
+    >
+      <Label render={(props) => <span {...props} data-custom="date-picker-label" />}>Date</Label>
+      <DateField.Group
+        fullWidth
+        render={(props) => <div {...props} data-custom="date-field-group" />}
+      >
+        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
+          {(segment) => (
+            <DateField.Segment
+              render={(props) => <span {...props} data-custom="date-field-segment" />}
+              segment={segment}
+            />
+          )}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger
+            render={(props) => <button {...props} data-custom="date-picker-trigger" />}
+          >
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DatePicker.Popover>
+        <Calendar aria-label="Event date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/disabled.tsx b/apps/docs/src/demos/en/date-picker/disabled.tsx
new file mode 100644
index 0000000..0f5b193
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/disabled.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  return (
+    <DatePicker isDisabled className="w-72" name="date" value={today(getLocalTimeZone())}>
+      <Label>Date</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>This date picker is disabled.</Description>
+      <DatePicker.Popover>
+        <Calendar aria-label="Event date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/form-example.tsx b/apps/docs/src/demos/en/date-picker/form-example.tsx
new file mode 100644
index 0000000..65a400f
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/form-example.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Button,
+  Calendar,
+  DateField,
+  DatePicker,
+  Description,
+  FieldError,
+  Form,
+  Label,
+} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid = value != null && value.compare(currentDate) < 0;
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1200);
+  };
+
+  return (
+    <Form className="flex w-72 flex-col gap-3" onSubmit={handleSubmit}>
+      <DatePicker
+        isRequired
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        name="appointmentDate"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Appointment date</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Date must be today or in the future.</FieldError>
+        ) : (
+          <Description>Choose a valid appointment date.</Description>
+        )}
+        <DatePicker.Popover>
+          <Calendar aria-label="Event date">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+      >
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/format-options-no-ssr.tsx b/apps/docs/src/demos/en/date-picker/format-options-no-ssr.tsx
new file mode 100644
index 0000000..b07dd4c
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/format-options-no-ssr.tsx
@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+export const FormatOptions = dynamic(
+  () => import("./format-options").then((mod) => mod.FormatOptions),
+  {
+    ssr: false,
+  },
+);
diff --git a/apps/docs/src/demos/en/date-picker/format-options.tsx b/apps/docs/src/demos/en/date-picker/format-options.tsx
new file mode 100644
index 0000000..b0cb1e0
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/format-options.tsx
@@ -0,0 +1,194 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Calendar,
+  DateField,
+  DatePicker,
+  Label,
+  ListBox,
+  Select,
+  Switch,
+  TimeField,
+} from "@heroui/react";
+import {getLocalTimeZone, parseDate, parseZonedDateTime} from "@internationalized/date";
+import {useMemo, useState} from "react";
+
+type Granularity = "day" | "hour" | "minute" | "second";
+type HourCycle = 12 | 24;
+const granularityOptions: {label: string; value: Granularity}[] = [
+  {label: "Day", value: "day"},
+  {label: "Hour", value: "hour"},
+  {label: "Minute", value: "minute"},
+  {label: "Second", value: "second"},
+];
+const hourCycleOptions: {label: string; value: HourCycle}[] = [
+  {label: "12-hour", value: 12},
+  {label: "24-hour", value: 24},
+];
+
+export function FormatOptions() {
+  const [granularity, setGranularity] = useState<Granularity>("minute");
+  const [hourCycle, setHourCycle] = useState<HourCycle>(12);
+  const [hideTimeZone, setHideTimeZone] = useState(false);
+  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);
+  const timeGranularity = granularity !== "day" ? granularity : undefined;
+  const showTimeField = !!timeGranularity;
+  const defaultValue = useMemo<DateValue>(() => {
+    const localTimeZone = getLocalTimeZone();
+
+    if (granularity === "day") {
+      return parseDate("2026-02-03");
+    }
+
+    return parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`);
+  }, [granularity]);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <DatePicker
+        key={granularity}
+        className="w-fit min-w-72"
+        defaultValue={defaultValue}
+        granularity={granularity}
+        hideTimeZone={hideTimeZone}
+        hourCycle={hourCycle}
+        name="date"
+        shouldForceLeadingZeros={shouldForceLeadingZeros}
+      >
+        {({state}) => (
+          <>
+            <Label>Date and time</Label>
+            <DateField.Group fullWidth>
+              <DateField.Input>
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+              <DateField.Suffix>
+                <DatePicker.Trigger>
+                  <DatePicker.TriggerIndicator />
+                </DatePicker.Trigger>
+              </DateField.Suffix>
+            </DateField.Group>
+            <DatePicker.Popover className="flex flex-col gap-3">
+              <Calendar aria-label="Event date">
+                <Calendar.Header>
+                  <Calendar.YearPickerTrigger>
+                    <Calendar.YearPickerTriggerHeading />
+                    <Calendar.YearPickerTriggerIndicator />
+                  </Calendar.YearPickerTrigger>
+                  <Calendar.NavButton slot="previous" />
+                  <Calendar.NavButton slot="next" />
+                </Calendar.Header>
+                <Calendar.Grid>
+                  <Calendar.GridHeader>
+                    {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+                  </Calendar.GridHeader>
+                  <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+                </Calendar.Grid>
+                <Calendar.YearPickerGrid>
+                  <Calendar.YearPickerGridBody>
+                    {({year}) => <Calendar.YearPickerCell year={year} />}
+                  </Calendar.YearPickerGridBody>
+                </Calendar.YearPickerGrid>
+              </Calendar>
+              {!!showTimeField && (
+                <div className="flex items-center justify-between">
+                  <Label>Time</Label>
+                  <TimeField
+                    aria-label="Time"
+                    granularity={timeGranularity}
+                    hideTimeZone={hideTimeZone}
+                    hourCycle={hourCycle}
+                    name="time"
+                    shouldForceLeadingZeros={shouldForceLeadingZeros}
+                    value={state.timeValue}
+                    onChange={(v) => state.setTimeValue(v as TimeValue)}
+                  >
+                    <TimeField.Group variant="secondary">
+                      <TimeField.Input>
+                        {(segment) => <TimeField.Segment segment={segment} />}
+                      </TimeField.Input>
+                    </TimeField.Group>
+                  </TimeField>
+                </div>
+              )}
+            </DatePicker.Popover>
+          </>
+        )}
+      </DatePicker>
+
+      <div className="flex flex-wrap gap-4">
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={granularity}
+            variant="secondary"
+            onChange={(value) => setGranularity(value as Granularity)}
+          >
+            <Label>Granularity</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {granularityOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={hourCycle}
+            variant="secondary"
+            onChange={(value) => setHourCycle(Number(value) as HourCycle)}
+          >
+            <Label>Hour cycle</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {hourCycleOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+      </div>
+
+      <div className="flex min-w-80 flex-col gap-2">
+        <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Hide timezone
+          </Switch.Content>
+        </Switch>
+        <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Force leading zeros
+          </Switch.Content>
+        </Switch>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/index.ts b/apps/docs/src/demos/en/date-picker/index.ts
new file mode 100644
index 0000000..6136ef5
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormatOptions} from "./format-options-no-ssr";
+export {FormExample} from "./form-example";
+export {InternationalCalendar} from "./international-calendar";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {WithValidation} from "./with-validation";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/date-picker/international-calendar.tsx b/apps/docs/src/demos/en/date-picker/international-calendar.tsx
new file mode 100644
index 0000000..dcee37f
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/international-calendar.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <DatePicker
+        className="w-72"
+        defaultValue={today(getLocalTimeZone())}
+        name="international-date"
+      >
+        <Label>Event date</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DatePicker.Popover>
+          <Calendar aria-label="Event date">
+            <Calendar.Header>
+              <Calendar.YearPickerTrigger>
+                <Calendar.YearPickerTriggerHeading />
+                <Calendar.YearPickerTriggerIndicator />
+              </Calendar.YearPickerTrigger>
+              <Calendar.NavButton slot="previous" />
+              <Calendar.NavButton slot="next" />
+            </Calendar.Header>
+            <Calendar.Grid>
+              <Calendar.GridHeader>
+                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+              </Calendar.GridHeader>
+              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+            </Calendar.Grid>
+            <Calendar.YearPickerGrid>
+              <Calendar.YearPickerGridBody>
+                {({year}) => <Calendar.YearPickerCell year={year} />}
+              </Calendar.YearPickerGridBody>
+            </Calendar.YearPickerGrid>
+          </Calendar>
+        </DatePicker.Popover>
+      </DatePicker>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/with-custom-indicator.tsx b/apps/docs/src/demos/en/date-picker/with-custom-indicator.tsx
new file mode 100644
index 0000000..a66b123
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/with-custom-indicator.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function WithCustomIndicator() {
+  return (
+    <DatePicker className="w-72" name="date">
+      <Label>Date</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DatePicker.TriggerIndicator>
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Replace the default calendar icon by passing custom children.</Description>
+      <DatePicker.Popover>
+        <Calendar aria-label="Event date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-picker/with-validation.tsx b/apps/docs/src/demos/en/date-picker/with-validation.tsx
new file mode 100644
index 0000000..3056ecd
--- /dev/null
+++ b/apps/docs/src/demos/en/date-picker/with-validation.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Calendar, DateField, DatePicker, FieldError, Label} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateValue | null>(null);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid = value != null && value.compare(currentDate) < 0;
+
+  return (
+    <DatePicker
+      isRequired
+      className="w-72"
+      isInvalid={isInvalid}
+      minValue={currentDate}
+      name="date"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Appointment date</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator />
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <FieldError>Date must be today or in the future.</FieldError>
+      <DatePicker.Popover>
+        <Calendar aria-label="Event date">
+          <Calendar.Header>
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+      </DatePicker.Popover>
+    </DatePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/basic.tsx b/apps/docs/src/demos/en/date-range-picker/basic.tsx
new file mode 100644
index 0000000..d32fc25
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/basic.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <DateRangePicker className="w-80" endName="endDate" startName="startDate">
+      <Label>Trip dates</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/controlled.tsx b/apps/docs/src/demos/en/date-range-picker/controlled.tsx
new file mode 100644
index 0000000..c3e53ec
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/controlled.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Controlled() {
+  const start = today(getLocalTimeZone());
+  const [value, setValue] = useState<DateRange | null>({end: start.add({days: 4}), start});
+
+  return (
+    <div className="flex w-80 flex-col gap-4">
+      <DateRangePicker endName="endDate" startName="startDate" value={value} onChange={setValue}>
+        <Label>Trip dates</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="Trip dates">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+      <Description>
+        Current value: {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(empty)"}
+      </Description>
+      <div className="flex gap-2">
+        <Button
+          variant="tertiary"
+          onPress={() => {
+            const nextStart = today(getLocalTimeZone());
+
+            setValue({end: nextStart.add({days: 6}), start: nextStart});
+          }}
+        >
+          Set week
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/custom-render-function.tsx b/apps/docs/src/demos/en/date-range-picker/custom-render-function.tsx
new file mode 100644
index 0000000..8cd8276
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/custom-render-function.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <DateRangePicker
+      className="w-80"
+      endName="endDate"
+      render={(props) => <div data-custom="foo" {...props} />}
+      startName="startDate"
+    >
+      <Label>Trip dates</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/disabled.tsx b/apps/docs/src/demos/en/date-range-picker/disabled.tsx
new file mode 100644
index 0000000..e1bab1f
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/disabled.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function Disabled() {
+  const start = today(getLocalTimeZone());
+
+  return (
+    <DateRangePicker
+      isDisabled
+      className="w-80"
+      endName="endDate"
+      startName="startDate"
+      value={{end: start.add({days: 4}), start}}
+    >
+      <Label>Trip dates</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>This date range picker is disabled.</Description>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/form-example.tsx b/apps/docs/src/demos/en/date-range-picker/form-example.tsx
new file mode 100644
index 0000000..ccb1106
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/form-example.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {
+  Button,
+  DateField,
+  DateRangePicker,
+  Description,
+  FieldError,
+  Form,
+  Label,
+  RangeCalendar,
+} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function FormExample() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid =
+    value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault();
+
+    if (!value || isInvalid) return;
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1200);
+  };
+
+  return (
+    <Form className="flex w-80 flex-col gap-3" onSubmit={handleSubmit}>
+      <DateRangePicker
+        isRequired
+        endName="tripEndDate"
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        startName="tripStartDate"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Trip dates</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Please choose a valid range in the future.</FieldError>
+        ) : (
+          <Description>Select your check-in and check-out dates.</Description>
+        )}
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="Trip dates">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+      >
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/format-options-no-ssr.tsx b/apps/docs/src/demos/en/date-range-picker/format-options-no-ssr.tsx
new file mode 100644
index 0000000..b07dd4c
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/format-options-no-ssr.tsx
@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+export const FormatOptions = dynamic(
+  () => import("./format-options").then((mod) => mod.FormatOptions),
+  {
+    ssr: false,
+  },
+);
diff --git a/apps/docs/src/demos/en/date-range-picker/format-options.tsx b/apps/docs/src/demos/en/date-range-picker/format-options.tsx
new file mode 100644
index 0000000..375fbec
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/format-options.tsx
@@ -0,0 +1,280 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+import type {DateValue} from "@internationalized/date";
+
+import {
+  DateField,
+  DateRangePicker,
+  Label,
+  ListBox,
+  RangeCalendar,
+  Select,
+  Separator,
+  Switch,
+  TimeField,
+  useLocale,
+} from "@heroui/react";
+import {
+  DateFormatter,
+  getLocalTimeZone,
+  parseDate,
+  parseZonedDateTime,
+} from "@internationalized/date";
+import {useMemo, useState} from "react";
+
+type Granularity = "day" | "hour" | "minute" | "second";
+type HourCycle = 12 | 24;
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+const granularityOptions: {label: string; value: Granularity}[] = [
+  {label: "Day", value: "day"},
+  {label: "Hour", value: "hour"},
+  {label: "Minute", value: "minute"},
+  {label: "Second", value: "second"},
+];
+
+const hourCycleOptions: {label: string; value: HourCycle}[] = [
+  {label: "12-hour", value: 12},
+  {label: "24-hour", value: 24},
+];
+
+export function FormatOptions() {
+  const [granularity, setGranularity] = useState<Granularity>("minute");
+  const [hourCycle, setHourCycle] = useState<HourCycle>(12);
+  const [hideTimeZone, setHideTimeZone] = useState(false);
+  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);
+  const {locale} = useLocale();
+  const dateFormatter = new DateFormatter(locale, {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+  });
+
+  const formatDate = (date: DateRange) => {
+    const localTimeZone = getLocalTimeZone();
+    const start = date.start.toDate(localTimeZone);
+    const end = date.end.toDate(localTimeZone);
+
+    return dateFormatter.formatRange(start, end);
+  };
+
+  const defaultValue = useMemo<DateRange>(() => {
+    const localTimeZone = getLocalTimeZone();
+
+    if (granularity === "day") {
+      return {
+        end: parseDate("2025-02-10"),
+        start: parseDate("2025-02-03"),
+      };
+    }
+
+    return {
+      end: parseZonedDateTime(`2026-02-10T18:45:00[${localTimeZone}]`),
+      start: parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`),
+    };
+  }, [granularity]);
+
+  const timeGranularity = granularity !== "day" ? granularity : undefined;
+  const showTimeField = !!timeGranularity;
+
+  return (
+    <div className="flex w-full flex-col gap-4">
+      <DateRangePicker
+        key={granularity}
+        className="w-max min-w-80"
+        defaultValue={defaultValue}
+        endName="endDate"
+        granularity={granularity}
+        hideTimeZone={hideTimeZone}
+        hourCycle={hourCycle}
+        shouldForceLeadingZeros={shouldForceLeadingZeros}
+        startName="startDate"
+      >
+        {({state}) => (
+          <>
+            <Label>Date range</Label>
+            <DateField.Group>
+              <DateField.InputContainer>
+                <DateField.Input slot="start">
+                  {(segment) => <DateField.Segment segment={segment} />}
+                </DateField.Input>
+                <DateRangePicker.RangeSeparator />
+                <DateField.Input slot="end">
+                  {(segment) => <DateField.Segment segment={segment} />}
+                </DateField.Input>
+              </DateField.InputContainer>
+              <DateField.Suffix>
+                <DateRangePicker.Trigger>
+                  <DateRangePicker.TriggerIndicator />
+                </DateRangePicker.Trigger>
+              </DateField.Suffix>
+            </DateField.Group>
+            <DateRangePicker.Popover className="flex w-full max-w-63 flex-col gap-3">
+              <RangeCalendar aria-label="Trip dates" className="w-full">
+                <RangeCalendar.Header>
+                  <RangeCalendar.YearPickerTrigger>
+                    <RangeCalendar.YearPickerTriggerHeading />
+                    <RangeCalendar.YearPickerTriggerIndicator />
+                  </RangeCalendar.YearPickerTrigger>
+                  <RangeCalendar.NavButton slot="previous" />
+                  <RangeCalendar.NavButton slot="next" />
+                </RangeCalendar.Header>
+                <RangeCalendar.Grid>
+                  <RangeCalendar.GridHeader>
+                    {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+                  </RangeCalendar.GridHeader>
+                  <RangeCalendar.GridBody>
+                    {(date) => <RangeCalendar.Cell date={date} />}
+                  </RangeCalendar.GridBody>
+                </RangeCalendar.Grid>
+                <RangeCalendar.YearPickerGrid>
+                  <RangeCalendar.YearPickerGridBody>
+                    {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+                  </RangeCalendar.YearPickerGridBody>
+                </RangeCalendar.YearPickerGrid>
+              </RangeCalendar>
+              {!!showTimeField && (
+                <div className="flex flex-col gap-3">
+                  <div className="flex items-center justify-between">
+                    <Label>Start Time</Label>
+                    <TimeField
+                      aria-label="Start Time"
+                      granularity={timeGranularity}
+                      hideTimeZone={hideTimeZone}
+                      hourCycle={hourCycle}
+                      name="startTime"
+                      shouldForceLeadingZeros={shouldForceLeadingZeros}
+                      value={state.timeRange?.start ?? null}
+                      onChange={(v) =>
+                        state.setTimeRange({
+                          end: state.timeRange?.end as TimeValue,
+                          start: v as TimeValue,
+                        })
+                      }
+                    >
+                      <TimeField.Group variant="secondary">
+                        <TimeField.Input>
+                          {(segment) => <TimeField.Segment segment={segment} />}
+                        </TimeField.Input>
+                      </TimeField.Group>
+                    </TimeField>
+                  </div>
+                  <div className="flex items-center justify-between">
+                    <Label>End Time</Label>
+                    <TimeField
+                      aria-label="End Time"
+                      granularity={timeGranularity}
+                      hideTimeZone={hideTimeZone}
+                      hourCycle={hourCycle}
+                      name="endTime"
+                      shouldForceLeadingZeros={shouldForceLeadingZeros}
+                      value={state.timeRange?.end ?? null}
+                      onChange={(v) =>
+                        state.setTimeRange({
+                          end: v as TimeValue,
+                          start: state.timeRange?.start as TimeValue,
+                        })
+                      }
+                    >
+                      <TimeField.Group variant="secondary">
+                        <TimeField.Input>
+                          {(segment) => <TimeField.Segment segment={segment} />}
+                        </TimeField.Input>
+                      </TimeField.Group>
+                    </TimeField>
+                  </div>
+                </div>
+              )}
+              <span className="mt-1 text-xs text-muted">
+                Selected:{" "}
+                {state.value && state.value.start && state.value.end
+                  ? formatDate({end: state.value.end, start: state.value.start})
+                  : "No date selected"}
+              </span>
+            </DateRangePicker.Popover>
+          </>
+        )}
+      </DateRangePicker>
+
+      <Separator className="my-5" />
+
+      <Label className="text-xs font-medium text-muted">Format Options</Label>
+
+      <div className="flex flex-wrap gap-4">
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            name="granularity"
+            value={granularity}
+            variant="secondary"
+            onChange={(value) => setGranularity(value as Granularity)}
+          >
+            <Label>Granularity</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {granularityOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <Select
+            className="w-[120px]"
+            value={hourCycle}
+            variant="secondary"
+            onChange={(value) => setHourCycle(Number(value) as HourCycle)}
+          >
+            <Label>Hour cycle</Label>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {hourCycleOptions.map((option) => (
+                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+      </div>
+
+      <div className="flex min-w-[529px] flex-col gap-2">
+        <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Hide timezone
+          </Switch.Content>
+        </Switch>
+        <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Force leading zeros
+          </Switch.Content>
+        </Switch>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/index.ts b/apps/docs/src/demos/en/date-range-picker/index.ts
new file mode 100644
index 0000000..598deeb
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormatOptions} from "./format-options-no-ssr";
+export {FormExample} from "./form-example";
+export {InternationalCalendar} from "./international-calendar";
+export {WithCustomIndicator} from "./with-custom-indicator";
+export {WithValidation} from "./with-validation";
+export {CustomRenderFunction} from "./custom-render-function";
+export {InputContainer} from "./input-container";
diff --git a/apps/docs/src/demos/en/date-range-picker/input-container.tsx b/apps/docs/src/demos/en/date-range-picker/input-container.tsx
new file mode 100644
index 0000000..5039c60
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/input-container.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+
+import {DateField, DateRangePicker, Label, RangeCalendar, TimeField} from "@heroui/react";
+import {getLocalTimeZone, parseZonedDateTime} from "@internationalized/date";
+
+export function InputContainer() {
+  const localTimeZone = getLocalTimeZone();
+
+  const defaultValue = {
+    end: parseZonedDateTime(`2026-02-10T18:45:00[${localTimeZone}]`),
+    start: parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`),
+  };
+
+  return (
+    <DateRangePicker
+      shouldForceLeadingZeros
+      className="w-full max-w-2xs min-w-80"
+      defaultValue={defaultValue}
+      granularity="second"
+      hourCycle={12}
+    >
+      {({state}) => (
+        <>
+          <Label>Date range</Label>
+          <DateField.Group>
+            <DateField.InputContainer>
+              <DateField.Input slot="start">
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+              <DateRangePicker.RangeSeparator />
+              <DateField.Input slot="end">
+                {(segment) => <DateField.Segment segment={segment} />}
+              </DateField.Input>
+            </DateField.InputContainer>
+            <DateField.Suffix>
+              <DateRangePicker.Trigger>
+                <DateRangePicker.TriggerIndicator />
+              </DateRangePicker.Trigger>
+            </DateField.Suffix>
+          </DateField.Group>
+          <DateRangePicker.Popover className="flex w-full flex-col gap-3">
+            <RangeCalendar aria-label="Trip dates">
+              <RangeCalendar.Header>
+                <RangeCalendar.YearPickerTrigger>
+                  <RangeCalendar.YearPickerTriggerHeading />
+                  <RangeCalendar.YearPickerTriggerIndicator />
+                </RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.NavButton slot="previous" />
+                <RangeCalendar.NavButton slot="next" />
+              </RangeCalendar.Header>
+              <RangeCalendar.Grid>
+                <RangeCalendar.GridHeader>
+                  {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+                </RangeCalendar.GridHeader>
+                <RangeCalendar.GridBody>
+                  {(date) => <RangeCalendar.Cell date={date} />}
+                </RangeCalendar.GridBody>
+              </RangeCalendar.Grid>
+              <RangeCalendar.YearPickerGrid>
+                <RangeCalendar.YearPickerGridBody>
+                  {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+                </RangeCalendar.YearPickerGridBody>
+              </RangeCalendar.YearPickerGrid>
+            </RangeCalendar>
+            <div className="flex flex-col gap-3">
+              <div className="flex items-center justify-between">
+                <Label>Start Time</Label>
+                <TimeField
+                  shouldForceLeadingZeros
+                  aria-label="Start Time"
+                  granularity="second"
+                  hourCycle={12}
+                  value={state.timeRange?.start ?? null}
+                  onChange={(v) =>
+                    state.setTimeRange({
+                      end: state.timeRange?.end as TimeValue,
+                      start: v as TimeValue,
+                    })
+                  }
+                >
+                  <TimeField.Group variant="secondary">
+                    <TimeField.Input>
+                      {(segment) => <TimeField.Segment segment={segment} />}
+                    </TimeField.Input>
+                  </TimeField.Group>
+                </TimeField>
+              </div>
+              <div className="flex items-center justify-between">
+                <Label>End Time</Label>
+                <TimeField
+                  shouldForceLeadingZeros
+                  aria-label="End Time"
+                  granularity="second"
+                  hourCycle={12}
+                  value={state.timeRange?.end ?? null}
+                  onChange={(v) =>
+                    state.setTimeRange({
+                      end: v as TimeValue,
+                      start: state.timeRange?.start as TimeValue,
+                    })
+                  }
+                >
+                  <TimeField.Group variant="secondary">
+                    <TimeField.Input>
+                      {(segment) => <TimeField.Segment segment={segment} />}
+                    </TimeField.Input>
+                  </TimeField.Group>
+                </TimeField>
+              </div>
+            </div>
+          </DateRangePicker.Popover>
+        </>
+      )}
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/international-calendar.tsx b/apps/docs/src/demos/en/date-range-picker/international-calendar.tsx
new file mode 100644
index 0000000..bc1da7a
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/international-calendar.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  const start = today(getLocalTimeZone());
+
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <DateRangePicker
+        className="w-80"
+        defaultValue={{end: start.add({days: 7}), start}}
+        endName="endDate"
+        startName="startDate"
+      >
+        <Label>Trip dates</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        <DateRangePicker.Popover>
+          <RangeCalendar aria-label="Trip dates">
+            <RangeCalendar.Header>
+              <RangeCalendar.YearPickerTrigger>
+                <RangeCalendar.YearPickerTriggerHeading />
+                <RangeCalendar.YearPickerTriggerIndicator />
+              </RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.NavButton slot="previous" />
+              <RangeCalendar.NavButton slot="next" />
+            </RangeCalendar.Header>
+            <RangeCalendar.Grid>
+              <RangeCalendar.GridHeader>
+                {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+              </RangeCalendar.GridHeader>
+              <RangeCalendar.GridBody>
+                {(date) => <RangeCalendar.Cell date={date} />}
+              </RangeCalendar.GridBody>
+            </RangeCalendar.Grid>
+            <RangeCalendar.YearPickerGrid>
+              <RangeCalendar.YearPickerGridBody>
+                {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+              </RangeCalendar.YearPickerGridBody>
+            </RangeCalendar.YearPickerGrid>
+          </RangeCalendar>
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/with-custom-indicator.tsx b/apps/docs/src/demos/en/date-range-picker/with-custom-indicator.tsx
new file mode 100644
index 0000000..6b0769b
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/with-custom-indicator.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function WithCustomIndicator() {
+  return (
+    <DateRangePicker className="w-80" endName="endDate" startName="startDate">
+      <Label>Trip dates</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DateRangePicker.TriggerIndicator>
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Replace the default calendar icon by passing custom children.</Description>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Trip dates">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/date-range-picker/with-validation.tsx b/apps/docs/src/demos/en/date-range-picker/with-validation.tsx
new file mode 100644
index 0000000..8f64598
--- /dev/null
+++ b/apps/docs/src/demos/en/date-range-picker/with-validation.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {DateField, DateRangePicker, FieldError, Label, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function WithValidation() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const currentDate = today(getLocalTimeZone());
+  const isInvalid =
+    value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+  return (
+    <DateRangePicker
+      isRequired
+      className="w-80"
+      endName="endDate"
+      isInvalid={isInvalid}
+      minValue={currentDate}
+      startName="startDate"
+      value={value}
+      onChange={setValue}
+    >
+      <Label>Booking period</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator />
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <FieldError>Select a valid range starting today or later.</FieldError>
+      <DateRangePicker.Popover>
+        <RangeCalendar aria-label="Booking period">
+          <RangeCalendar.Header>
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  );
+}
diff --git a/apps/docs/src/demos/en/description/basic.tsx b/apps/docs/src/demos/en/description/basic.tsx
new file mode 100644
index 0000000..9567bd2
--- /dev/null
+++ b/apps/docs/src/demos/en/description/basic.tsx
@@ -0,0 +1,19 @@
+import {Description, Input, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor="email">Email</Label>
+      <Input
+        aria-describedby="email-description"
+        className="w-64"
+        id="email"
+        placeholder="you@example.com"
+        type="email"
+      />
+      <Description id="email-description">
+        We'll never share your email with anyone else.
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/description/index.ts b/apps/docs/src/demos/en/description/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/en/description/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/en/disclosure-group/basic.tsx b/apps/docs/src/demos/en/disclosure-group/basic.tsx
new file mode 100644
index 0000000..d16eb31
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure-group/basic.tsx
@@ -0,0 +1,90 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure, DisclosureGroup, Separator} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+export function Basic() {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 bg-transparent p-4">
+        <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="Preview HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <QrCode />
+                  Preview HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />
+                  Preview on Expo Go
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="Download HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download App
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Download the HeroUI native app to explore our mobile components directly on your
+                  device.
+                </p>
+                <img
+                  alt="App Store QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Available on iOS and Android devices.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download on App Store
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/disclosure-group/controlled.tsx b/apps/docs/src/demos/en/disclosure-group/controlled.tsx
new file mode 100644
index 0000000..98f0e1d
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure-group/controlled.tsx
@@ -0,0 +1,125 @@
+"use client";
+
+import {ChevronDown, ChevronUp, QrCode} from "@gravity-ui/icons";
+import {
+  Button,
+  Disclosure,
+  DisclosureGroup,
+  Separator,
+  useDisclosureGroupNavigation,
+} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+export function Controlled() {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+  const itemIds = ["preview", "download"]; // Track our disclosure items
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 rounded-3xl p-4">
+        <div className="mb-2 flex items-center justify-between">
+          <h3 className="text-lg font-semibold">HeroUI Native</h3>
+          <div className="flex gap-2">
+            <Button
+              aria-label="Previous disclosure"
+              isDisabled={isPrevDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onPrevious}
+            >
+              <ChevronUp className="size-4" />
+            </Button>
+            <Button
+              aria-label="Next disclosure"
+              isDisabled={isNextDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onNext}
+            >
+              <ChevronDown className="size-4" />
+            </Button>
+          </div>
+        </div>
+        <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="Preview HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <QrCode />
+                  Preview HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />
+                  Preview on Expo Go
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="Download HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download on App Store
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/disclosure-group/index.ts b/apps/docs/src/demos/en/disclosure-group/index.ts
new file mode 100644
index 0000000..3c16102
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure-group/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
diff --git a/apps/docs/src/demos/en/disclosure/basic.tsx b/apps/docs/src/demos/en/disclosure/basic.tsx
new file mode 100644
index 0000000..6240951
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure/basic.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+
+export function Basic() {
+  const [isExpanded, setIsExpanded] = React.useState(true);
+
+  return (
+    <div className="w-full max-w-md text-center">
+      <Disclosure isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
+        <Disclosure.Heading>
+          <Button slot="trigger" variant="secondary">
+            <QrCode />
+            Preview HeroUI Native
+            <Disclosure.Indicator />
+          </Button>
+        </Disclosure.Heading>
+        <Disclosure.Content>
+          <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center">
+            <p className="text-sm text-muted">
+              Scan this QR code with your camera app to preview the HeroUI native components.
+            </p>
+            <img
+              alt="Expo Go QR Code"
+              className="aspect-square w-full max-w-54 object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+            />
+            <p className="text-sm text-muted">Expo must be installed on your device.</p>
+            <Button className="mt-4" variant="primary">
+              <Icon icon="tabler:brand-apple-filled" />
+              Download on App Store
+            </Button>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/disclosure/custom-render-function.tsx b/apps/docs/src/demos/en/disclosure/custom-render-function.tsx
new file mode 100644
index 0000000..f2c09ce
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure/custom-render-function.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {QrCode} from "@gravity-ui/icons";
+import {Button, Disclosure} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+
+export function CustomRenderFunction() {
+  const [isExpanded, setIsExpanded] = React.useState(true);
+
+  return (
+    <div className="w-full max-w-md text-center">
+      <Disclosure
+        isExpanded={isExpanded}
+        render={(props) => <div {...props} data-custom="foo" />}
+        onExpandedChange={setIsExpanded}
+      >
+        <Disclosure.Heading>
+          <Button slot="trigger" variant="secondary">
+            <QrCode />
+            Preview HeroUI Native
+            <Disclosure.Indicator />
+          </Button>
+        </Disclosure.Heading>
+        <Disclosure.Content render={(props) => <div data-custom="bar" {...props} />}>
+          <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center">
+            <p className="text-sm text-muted">
+              Scan this QR code with your camera app to preview the HeroUI native components.
+            </p>
+            <img
+              alt="Expo Go QR Code"
+              className="aspect-square w-full max-w-54 object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+            />
+            <p className="text-sm text-muted">Expo must be installed on your device.</p>
+            <Button className="mt-4" variant="primary">
+              <Icon icon="tabler:brand-apple-filled" />
+              Download on App Store
+            </Button>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/disclosure/index.ts b/apps/docs/src/demos/en/disclosure/index.ts
new file mode 100644
index 0000000..9b0b4e7
--- /dev/null
+++ b/apps/docs/src/demos/en/disclosure/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/drawer/backdrop-variants.tsx b/apps/docs/src/demos/en/drawer/backdrop-variants.tsx
new file mode 100644
index 0000000..0abe019
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/backdrop-variants.tsx
@@ -0,0 +1,38 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Drawer key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <Drawer.Backdrop variant={variant}>
+            <Drawer.Content>
+              <Drawer.Dialog>
+                <Drawer.Handle />
+                <Drawer.CloseTrigger />
+                <Drawer.Header>
+                  <Drawer.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    This drawer uses the <code>{variant}</code> backdrop variant.
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button className="w-full" slot="close">
+                    Close
+                  </Button>
+                </Drawer.Footer>
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/basic.tsx b/apps/docs/src/demos/en/drawer/basic.tsx
new file mode 100644
index 0000000..aad96a8
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/basic.tsx
@@ -0,0 +1,30 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Drawer>
+      <Button variant="secondary">Open Drawer</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>Drawer Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>
+                This is a bottom drawer built with React Aria's Modal component. It slides up from
+                the bottom of the screen with a smooth CSS transition.
+              </p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Confirm</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/controlled.tsx b/apps/docs/src/demos/en/drawer/controlled.tsx
new file mode 100644
index 0000000..8a290a3
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/controlled.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import {Button, Drawer, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Control the drawer using React's <code className="text-foreground">useState</code> hook
+          for simple state management.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              Open Drawer
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Drawer.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Drawer.Content placement="right">
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>Controlled with useState()</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>
+                <p>
+                  This drawer is controlled by React's <code>useState</code> hook. Pass{" "}
+                  <code>isOpen</code> and <code>onOpenChange</code> props to manage the drawer state
+                  externally.
+                </p>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Button slot="close" variant="secondary">
+                  Close
+                </Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API
+          with convenient methods like <code>open()</code>, <code>close()</code>, and{" "}
+          <code>toggle()</code>.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              Open Drawer
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Drawer.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <Drawer.Content placement="right">
+            <Drawer.Dialog>
+              <Drawer.CloseTrigger />
+              <Drawer.Header>
+                <Drawer.Heading>Controlled with useOverlayState()</Drawer.Heading>
+              </Drawer.Header>
+              <Drawer.Body>
+                <p>
+                  The <code>useOverlayState</code> hook provides dedicated methods for common
+                  operations. No need to manually create callbacks—just use{" "}
+                  <code>state.open()</code>, <code>state.close()</code>, or{" "}
+                  <code>state.toggle()</code>.
+                </p>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Button slot="close" variant="secondary">
+                  Close
+                </Button>
+              </Drawer.Footer>
+            </Drawer.Dialog>
+          </Drawer.Content>
+        </Drawer.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/index.ts b/apps/docs/src/demos/en/drawer/index.ts
new file mode 100644
index 0000000..be7de18
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/index.ts
@@ -0,0 +1,8 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Navigation} from "./navigation";
+export {NonDismissable} from "./non-dismissable";
+export {Placements} from "./placements";
+export {ScrollableContent} from "./scrollable-content";
+export {WithForm} from "./with-form";
diff --git a/apps/docs/src/demos/en/drawer/navigation.tsx b/apps/docs/src/demos/en/drawer/navigation.tsx
new file mode 100644
index 0000000..b428ff0
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/navigation.tsx
@@ -0,0 +1,48 @@
+import type {ComponentType, SVGProps} from "react";
+
+import {Bars, Bell, Envelope, Gear, House, Magnifier, Person} from "@gravity-ui/icons";
+import {Button, Drawer} from "@heroui/react";
+
+export function Navigation() {
+  const navItems: {icon: ComponentType<SVGProps<SVGSVGElement>>; label: string}[] = [
+    {icon: House, label: "Home"},
+    {icon: Magnifier, label: "Search"},
+    {icon: Bell, label: "Notifications"},
+    {icon: Envelope, label: "Messages"},
+    {icon: Person, label: "Profile"},
+    {icon: Gear, label: "Settings"},
+  ];
+
+  return (
+    <Drawer>
+      <Button variant="secondary">
+        <Bars />
+        Menu
+      </Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="left">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Navigation</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <nav className="flex flex-col gap-1">
+                {navItems.map((item) => (
+                  <button
+                    key={item.label}
+                    className="flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm text-foreground transition-colors hover:bg-default"
+                    type="button"
+                  >
+                    <item.icon className="size-5 text-muted" />
+                    {item.label}
+                  </button>
+                ))}
+              </nav>
+            </Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/non-dismissable.tsx b/apps/docs/src/demos/en/drawer/non-dismissable.tsx
new file mode 100644
index 0000000..d9d10ea
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/non-dismissable.tsx
@@ -0,0 +1,30 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function NonDismissable() {
+  return (
+    <Drawer>
+      <Button variant="secondary">Important Action</Button>
+      <Drawer.Backdrop isDismissable={false}>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Header>
+              <Drawer.Heading>Confirm Action</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>
+                This drawer cannot be dismissed by clicking outside or dragging. You must use one of
+                the buttons below.
+              </p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Confirm</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/placements.tsx b/apps/docs/src/demos/en/drawer/placements.tsx
new file mode 100644
index 0000000..6463722
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/placements.tsx
@@ -0,0 +1,42 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function Placements() {
+  const placements = ["bottom", "top", "left", "right"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Drawer key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <Drawer.Backdrop>
+            <Drawer.Content placement={placement}>
+              <Drawer.Dialog>
+                <Drawer.CloseTrigger />
+                {placement === "bottom" && <Drawer.Handle />}
+                <Drawer.Header>
+                  <Drawer.Heading>
+                    {placement.charAt(0).toUpperCase() + placement.slice(1)} Drawer
+                  </Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    This drawer slides in from the <strong>{placement}</strong> edge of the screen.
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button slot="close" variant="secondary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Done</Button>
+                </Drawer.Footer>
+                {placement === "top" && <Drawer.Handle />}
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/scrollable-content.tsx b/apps/docs/src/demos/en/drawer/scrollable-content.tsx
new file mode 100644
index 0000000..f7a5043
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/scrollable-content.tsx
@@ -0,0 +1,35 @@
+import {Button, Drawer} from "@heroui/react";
+
+export function ScrollableContent() {
+  return (
+    <Drawer>
+      <Button variant="secondary">Terms & Conditions</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Handle />
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Terms & Conditions</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              {Array.from({length: 20}).map((_, i) => (
+                <p key={i} className="mb-3">
+                  Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                  pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit
+                  risus, sed porttitor quam.
+                </p>
+              ))}
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Decline
+              </Button>
+              <Button slot="close">Accept</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/en/drawer/with-form.tsx b/apps/docs/src/demos/en/drawer/with-form.tsx
new file mode 100644
index 0000000..ce3b84e
--- /dev/null
+++ b/apps/docs/src/demos/en/drawer/with-form.tsx
@@ -0,0 +1,41 @@
+import {Button, Drawer, Input, Label, TextField} from "@heroui/react";
+
+export function WithForm() {
+  return (
+    <Drawer>
+      <Button variant="secondary">Edit Profile</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Edit Profile</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <form className="flex flex-col gap-4">
+                <TextField className="w-full" name="name" type="text">
+                  <Label>Name</Label>
+                  <Input placeholder="Enter your name" variant="secondary" />
+                </TextField>
+                <TextField className="w-full" name="email" type="email">
+                  <Label>Email</Label>
+                  <Input placeholder="Enter your email" variant="secondary" />
+                </TextField>
+                <TextField className="w-full" name="bio">
+                  <Label>Bio</Label>
+                  <Input placeholder="Tell us about yourself" variant="secondary" />
+                </TextField>
+              </form>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Save Changes</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/controlled-open-state.tsx b/apps/docs/src/demos/en/dropdown/controlled-open-state.tsx
new file mode 100644
index 0000000..1732992
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/controlled-open-state.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
+      <p className="text-sm text-muted">
+        Dropdown is: <strong>{open ? "open" : "closed"}</strong>
+      </p>
+      <Dropdown isOpen={open} onOpenChange={setOpen}>
+        <Button aria-label="Menu" variant="secondary">
+          Actions
+        </Button>
+        <Dropdown.Popover>
+          <Dropdown.Menu>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <Label>New file</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="open-file" textValue="Open file">
+              <Label>Open file</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="save-file" textValue="Save file">
+              <Label>Save file</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <Label>Delete file</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/controlled.tsx b/apps/docs/src/demos/en/dropdown/controlled.tsx
new file mode 100644
index 0000000..b6feadd
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/controlled.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState<Selection>(new Set(["bold"]));
+
+  const selectedItems = Array.from(selected);
+
+  return (
+    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
+      <p className="text-sm text-muted">
+        Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
+      </p>
+      <Dropdown>
+        <Button aria-label="Menu" variant="secondary">
+          Actions
+        </Button>
+        <Dropdown.Popover>
+          <Dropdown.Menu
+            selectedKeys={selected}
+            selectionMode="multiple"
+            onSelectionChange={setSelected}
+          >
+            <Dropdown.Item id="bold" textValue="Bold">
+              <Label>Bold</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+            <Dropdown.Item id="italic" textValue="Italic">
+              <Label>Italic</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+            <Dropdown.Item id="underline" textValue="Underline">
+              <Label>Underline</Label>
+              <Dropdown.ItemIndicator />
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/custom-trigger.tsx b/apps/docs/src/demos/en/dropdown/custom-trigger.tsx
new file mode 100644
index 0000000..e5c94e2
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/custom-trigger.tsx
@@ -0,0 +1,61 @@
+import {ArrowRightFromSquare, Gear, Persons} from "@gravity-ui/icons";
+import {Avatar, Dropdown, Label} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger className="rounded-full">
+        <Avatar>
+          <Avatar.Image
+            alt="Junior Garcia"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+          />
+          <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+        </Avatar>
+      </Dropdown.Trigger>
+      <Dropdown.Popover>
+        <div className="px-3 pt-3 pb-1">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Jane"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+              />
+              <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col gap-0">
+              <p className="text-sm leading-5 font-medium">Jane Doe</p>
+              <p className="text-xs leading-none text-muted">jane@example.com</p>
+            </div>
+          </div>
+        </div>
+        <Dropdown.Menu>
+          <Dropdown.Item id="dashboard" textValue="Dashboard">
+            <Label>Dashboard</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="profile" textValue="Profile">
+            <Label>Profile</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="settings" textValue="Settings">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Settings</Label>
+              <Gear className="size-3.5 text-muted" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="new-project" textValue="New project">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Create Team</Label>
+              <Persons className="size-3.5 text-muted" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="logout" textValue="Logout" variant="danger">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Log Out</Label>
+              <ArrowRightFromSquare className="size-3.5 text-danger" />
+            </div>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/default.tsx b/apps/docs/src/demos/en/dropdown/default.tsx
new file mode 100644
index 0000000..358fef8
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/default.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <Label>New file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="copy-link" textValue="Copy link">
+            <Label>Copy link</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="edit-file" textValue="Edit file">
+            <Label>Edit file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <Label>Delete file</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/index.ts b/apps/docs/src/demos/en/dropdown/index.ts
new file mode 100644
index 0000000..da609a1
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/index.ts
@@ -0,0 +1,17 @@
+// Dropdown demos
+export {Controlled} from "./controlled";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {LongPressTrigger} from "./long-press-trigger";
+export {SingleWithCustomIndicator} from "./single-with-custom-indicator";
+export {WithDescriptions} from "./with-descriptions";
+export {WithDisabledItems} from "./with-disabled-items";
+export {WithIcons} from "./with-icons";
+export {WithKeyboardShortcuts} from "./with-keyboard-shortcuts";
+export {WithMultipleSelection} from "./with-multiple-selection";
+export {WithSectionLevelSelection} from "./with-section-level-selection";
+export {WithSections} from "./with-sections";
+export {WithSingleSelection} from "./with-single-selection";
+export {WithSubmenus} from "./with-submenus";
+export {WithCustomSubmenuIndicator} from "./with-custom-submenu-indicator";
diff --git a/apps/docs/src/demos/en/dropdown/long-press-trigger.tsx b/apps/docs/src/demos/en/dropdown/long-press-trigger.tsx
new file mode 100644
index 0000000..4b509ea
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/long-press-trigger.tsx
@@ -0,0 +1,27 @@
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function LongPressTrigger() {
+  return (
+    <Dropdown trigger="longPress">
+      <Button aria-label="Menu" variant="secondary">
+        Long Press
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <Label>New file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <Label>Open file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <Label>Save file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <Label>Delete file</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/single-with-custom-indicator.tsx b/apps/docs/src/demos/en/dropdown/single-with-custom-indicator.tsx
new file mode 100644
index 0000000..f5477fd
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/single-with-custom-indicator.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function SingleWithCustomIndicator() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  const CustomCheckmarkIcon = (
+    <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+      <path
+        className="text-accent-soft-foreground"
+        clipRule="evenodd"
+        d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m3.1-8.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Fruits
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="single"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>Select a fruit</Header>
+            <Dropdown.Item id="apple" textValue="Apple">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>Apple</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="Banana">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>Banana</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="Cherry">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>Cherry</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="Orange">
+            <Dropdown.ItemIndicator>
+              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+            </Dropdown.ItemIndicator>
+            <Label>Orange</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="Pear">
+            <Dropdown.ItemIndicator>
+              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+            </Dropdown.ItemIndicator>
+            <Label>Pear</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-custom-submenu-indicator.tsx b/apps/docs/src/demos/en/dropdown/with-custom-submenu-indicator.tsx
new file mode 100644
index 0000000..763cd80
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-custom-submenu-indicator.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {ArrowRight} from "@gravity-ui/icons";
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function WithCustomSubmenuIndicator() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Share
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="Copy Link">
+            <Label>Copy Link</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="Share">
+              <Label>More options</Label>
+              <Dropdown.SubmenuIndicator>
+                <ArrowRight className="size-3.5 text-muted" />
+              </Dropdown.SubmenuIndicator>
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="Email">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator>
+                      <svg
+                        className="size-3.5 text-muted"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth="2"
+                        viewBox="0 0 24 24"
+                      >
+                        <path d="M9 18l6-6-6-6" />
+                      </svg>
+                    </Dropdown.SubmenuIndicator>
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="Work email">
+                        <Label>Work email</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="Personal email">
+                        <Label>Personal email</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="other" textValue="Other">
+              <Label>Other (default indicator)</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="sms" textValue="SMS">
+                  <Label>SMS</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-descriptions.tsx b/apps/docs/src/demos/en/dropdown/with-descriptions.tsx
new file mode 100644
index 0000000..c676ff9
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-descriptions.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithDescriptions() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <FolderOpen className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Open file</Label>
+              <Description>Open an existing file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <FloppyDisk className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Save file</Label>
+              <Description>Save the current file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-disabled-items.tsx b/apps/docs/src/demos/en/dropdown/with-disabled-items.tsx
new file mode 100644
index 0000000..b56eb92
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-disabled-items.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Bars, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+
+export function WithDisabledItems() {
+  return (
+    <Dropdown>
+      <Button isIconOnly aria-label="Menu" variant="secondary">
+        <Bars className="outline-none" />
+      </Button>
+      <Dropdown.Popover className="min-w-[220px]">
+        <Dropdown.Menu
+          disabledKeys={["delete-file"]}
+          onAction={(key) => console.log(`Selected: ${key}`)}
+        >
+          <Dropdown.Section>
+            <Header>Actions</Header>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <SquarePlus className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>New file</Label>
+                <Description>Create a new file</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="Edit file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Pencil className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Edit file</Label>
+                <Description>Make changes</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>Danger zone</Header>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <TrashBin className="size-4 shrink-0 text-danger" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Delete file</Label>
+                <Description>Move to trash</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-icons.tsx b/apps/docs/src/demos/en/dropdown/with-icons.tsx
new file mode 100644
index 0000000..8bc821b
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-icons.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithIcons() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <SquarePlus className="size-4 shrink-0 text-muted" />
+            <Label>New file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <FolderOpen className="size-4 shrink-0 text-muted" />
+            <Label>Open file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <FloppyDisk className="size-4 shrink-0 text-muted" />
+            <Label>Save file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <TrashBin className="size-4 shrink-0 text-danger" />
+            <Label>Delete file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-keyboard-shortcuts.tsx b/apps/docs/src/demos/en/dropdown/with-keyboard-shortcuts.tsx
new file mode 100644
index 0000000..28e6bbb
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-keyboard-shortcuts.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Button, Dropdown, Kbd, Label} from "@heroui/react";
+
+export function WithKeyboardShortcuts() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="new" textValue="New">
+            <Label>New</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open" textValue="Open">
+            <Label>Open</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save" textValue="Save">
+            <Label>Save</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete" textValue="Delete" variant="danger">
+            <Label>Delete</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-multiple-selection.tsx b/apps/docs/src/demos/en/dropdown/with-multiple-selection.tsx
new file mode 100644
index 0000000..95c31c7
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-multiple-selection.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function WithMultipleSelection() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Preferred Fruits
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>Select a fruit</Header>
+            <Dropdown.Item id="apple" textValue="Apple">
+              <Dropdown.ItemIndicator />
+              <Label>Apple</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="Banana">
+              <Dropdown.ItemIndicator />
+              <Label>Banana</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="Cherry">
+              <Dropdown.ItemIndicator />
+              <Label>Cherry</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="Orange">
+            <Dropdown.ItemIndicator />
+            <Label>Orange</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="Pear">
+            <Dropdown.ItemIndicator />
+            <Label>Pear</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-section-level-selection.tsx b/apps/docs/src/demos/en/dropdown/with-section-level-selection.tsx
new file mode 100644
index 0000000..7151251
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-section-level-selection.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSectionLevelSelection() {
+  const [textStyles, setTextStyles] = useState<Selection>(new Set(["bold", "italic"]));
+  const [textAlignment, setTextAlignment] = useState<Selection>(new Set(["left"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Styles
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu>
+          <Dropdown.Section>
+            <Header>Actions</Header>
+            <Dropdown.Item id="cut" textValue="Cut">
+              <Label>Cut</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>X</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="copy" textValue="Copy">
+              <Label>Copy</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>C</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="paste" textValue="Paste">
+              <Label>Paste</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>U</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section
+            selectedKeys={textStyles}
+            selectionMode="multiple"
+            onSelectionChange={setTextStyles}
+          >
+            <Header>Text Style</Header>
+            <Dropdown.Item id="bold" textValue="Bold">
+              <Dropdown.ItemIndicator />
+              <Label>Bold</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>B</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="italic" textValue="Italic">
+              <Dropdown.ItemIndicator />
+              <Label>Italic</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>I</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="underline" textValue="Underline">
+              <Dropdown.ItemIndicator />
+              <Label>Underline</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>U</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section
+            selectedKeys={textAlignment}
+            selectionMode="single"
+            onSelectionChange={setTextAlignment}
+          >
+            <Header>Text Alignment</Header>
+            <Dropdown.Item id="left" textValue="Left">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>Left</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>A</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="center" textValue="Center">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>Center</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>H</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="right" textValue="Right">
+              <Dropdown.ItemIndicator type="dot" />
+              <Label>Right</Label>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="alt" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-sections.tsx b/apps/docs/src/demos/en/dropdown/with-sections.tsx
new file mode 100644
index 0000000..6cd9365
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-sections.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import {EllipsisVertical, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Dropdown>
+      <Button isIconOnly aria-label="Menu" variant="secondary">
+        <EllipsisVertical className="outline-none" />
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Section>
+            <Header>Actions</Header>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <SquarePlus className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>New file</Label>
+                <Description>Create a new file</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="Edit file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Pencil className="size-4 shrink-0 text-muted" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Edit file</Label>
+                <Description>Make changes</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>Danger zone</Header>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <TrashBin className="size-4 shrink-0 text-danger" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Delete file</Label>
+                <Description>Move to trash</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-single-selection.tsx b/apps/docs/src/demos/en/dropdown/with-single-selection.tsx
new file mode 100644
index 0000000..ab05da7
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-single-selection.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Dropdown, Header, Label} from "@heroui/react";
+import {useState} from "react";
+
+export function WithSingleSelection() {
+  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));
+
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Fruit
+      </Button>
+      <Dropdown.Popover className="min-w-[256px]">
+        <Dropdown.Menu
+          selectedKeys={selected}
+          selectionMode="single"
+          onSelectionChange={setSelected}
+        >
+          <Dropdown.Section>
+            <Header>Select a fruit</Header>
+            <Dropdown.Item id="apple" textValue="Apple">
+              <Dropdown.ItemIndicator />
+              <Label>Apple</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="banana" textValue="Banana">
+              <Dropdown.ItemIndicator />
+              <Label>Banana</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="cherry" textValue="Cherry">
+              <Dropdown.ItemIndicator />
+              <Label>Cherry</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Dropdown.Item id="orange" textValue="Orange">
+            <Dropdown.ItemIndicator />
+            <Label>Orange</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="pear" textValue="Pear">
+            <Dropdown.ItemIndicator />
+            <Label>Pear</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/dropdown/with-submenus.tsx b/apps/docs/src/demos/en/dropdown/with-submenus.tsx
new file mode 100644
index 0000000..b5548af
--- /dev/null
+++ b/apps/docs/src/demos/en/dropdown/with-submenus.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Button, Dropdown, Label} from "@heroui/react";
+
+export function WithSubmenus() {
+  return (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Share
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="Copy Link">
+            <Label>Copy Link</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="twitter" textValue="Twitter">
+            <Label>X / Twitter</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="Share">
+              <Label>Other</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="Email">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator />
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="Work email">
+                        <Label>Work email</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="Personal email">
+                        <Label>Personal email</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  );
+}
diff --git a/apps/docs/src/demos/en/error-message/basic.tsx b/apps/docs/src/demos/en/error-message/basic.tsx
new file mode 100644
index 0000000..c659bd3
--- /dev/null
+++ b/apps/docs/src/demos/en/error-message/basic.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function ErrorMessageBasic() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>Required Categories</Label>
+      <TagGroup.List>
+        <Tag id="news">News</Tag>
+        <Tag id="travel">Travel</Tag>
+        <Tag id="gaming">Gaming</Tag>
+        <Tag id="shopping">Shopping</Tag>
+      </TagGroup.List>
+      <Description>Select at least one category</Description>
+      <ErrorMessage>{!!isInvalid && <>Please select at least one category</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/error-message/index.ts b/apps/docs/src/demos/en/error-message/index.ts
new file mode 100644
index 0000000..3229bf4
--- /dev/null
+++ b/apps/docs/src/demos/en/error-message/index.ts
@@ -0,0 +1,2 @@
+export {ErrorMessageBasic as Basic} from "./basic";
+export {ErrorMessageWithTagGroup as WithTagGroup} from "./with-tag-group";
diff --git a/apps/docs/src/demos/en/error-message/with-tag-group.tsx b/apps/docs/src/demos/en/error-message/with-tag-group.tsx
new file mode 100644
index 0000000..96583ce
--- /dev/null
+++ b/apps/docs/src/demos/en/error-message/with-tag-group.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function ErrorMessageWithTagGroup() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>Required Categories</Label>
+      <TagGroup.List>
+        <Tag id="news">News</Tag>
+        <Tag id="travel">Travel</Tag>
+        <Tag id="gaming">Gaming</Tag>
+        <Tag id="shopping">Shopping</Tag>
+      </TagGroup.List>
+      <Description>Select at least one category</Description>
+      <ErrorMessage>{!!isInvalid && <>Please select at least one category</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/field-error/basic.tsx b/apps/docs/src/demos/en/field-error/basic.tsx
new file mode 100644
index 0000000..c461f2e
--- /dev/null
+++ b/apps/docs/src/demos/en/field-error/basic.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+export function Basic() {
+  const [value, setValue] = useState("jr");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <TextField className="w-64" isInvalid={isInvalid}>
+      <Label htmlFor="username">Username</Label>
+      <Input
+        id="username"
+        placeholder="Enter username"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <FieldError>Username must be at least 3 characters</FieldError>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/field-error/index.ts b/apps/docs/src/demos/en/field-error/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/en/field-error/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/en/fieldset/basic.tsx b/apps/docs/src/demos/en/fieldset/basic.tsx
new file mode 100644
index 0000000..bf857d2
--- /dev/null
+++ b/apps/docs/src/demos/en/fieldset/basic.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {FloppyDisk} from "@gravity-ui/icons";
+import {
+  Button,
+  Description,
+  FieldError,
+  FieldGroup,
+  Fieldset,
+  Form,
+  Input,
+  Label,
+  TextArea,
+  TextField,
+} from "@heroui/react";
+
+export function Basic() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Form className="w-full max-w-96" onSubmit={onSubmit}>
+      <Fieldset>
+        <Fieldset.Legend>Profile Settings</Fieldset.Legend>
+        <Description>Update your profile information.</Description>
+        <FieldGroup>
+          <TextField
+            isRequired
+            name="name"
+            validate={(value) => {
+              if (value.length < 3) {
+                return "Name must be at least 3 characters";
+              }
+
+              return null;
+            }}
+          >
+            <Label>Name</Label>
+            <Input placeholder="John Doe" />
+            <FieldError />
+          </TextField>
+          <TextField isRequired name="email" type="email">
+            <Label>Email</Label>
+            <Input placeholder="john@example.com" />
+            <FieldError />
+          </TextField>
+          <TextField
+            isRequired
+            name="bio"
+            validate={(value) => {
+              if (value.length < 10) {
+                return "Bio must be at least 10 characters";
+              }
+
+              return null;
+            }}
+          >
+            <Label>Bio</Label>
+            <TextArea placeholder="Tell us about yourself..." />
+            <Description>Minimum 10 characters</Description>
+            <FieldError />
+          </TextField>
+        </FieldGroup>
+        <Fieldset.Actions>
+          <Button type="submit">
+            <FloppyDisk />
+            Save changes
+          </Button>
+          <Button type="reset" variant="secondary">
+            Cancel
+          </Button>
+        </Fieldset.Actions>
+      </Fieldset>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/fieldset/index.ts b/apps/docs/src/demos/en/fieldset/index.ts
new file mode 100644
index 0000000..f7305ac
--- /dev/null
+++ b/apps/docs/src/demos/en/fieldset/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {OnSurface} from "./on-surface";
diff --git a/apps/docs/src/demos/en/fieldset/on-surface.tsx b/apps/docs/src/demos/en/fieldset/on-surface.tsx
new file mode 100644
index 0000000..b6fee17
--- /dev/null
+++ b/apps/docs/src/demos/en/fieldset/on-surface.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import {FloppyDisk} from "@gravity-ui/icons";
+import {
+  Button,
+  Description,
+  FieldError,
+  Fieldset,
+  Form,
+  Input,
+  Label,
+  Surface,
+  TextArea,
+  TextField,
+} from "@heroui/react";
+import React from "react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <div className="flex items-center justify-center rounded-3xl bg-surface p-6">
+      <Surface className="w-full min-w-[380px]">
+        <Form onSubmit={onSubmit}>
+          <Fieldset className="w-full">
+            <Fieldset.Legend>Profile Settings</Fieldset.Legend>
+            <Description>Update your profile information.</Description>
+            <Fieldset.Group>
+              <TextField
+                isRequired
+                name="name"
+                validate={(value) => {
+                  if (value.length < 3) {
+                    return "Name must be at least 3 characters";
+                  }
+
+                  return null;
+                }}
+              >
+                <Label>Name</Label>
+                <Input placeholder="John Doe" variant="secondary" />
+                <FieldError />
+              </TextField>
+              <TextField isRequired name="email" type="email">
+                <Label>Email</Label>
+                <Input placeholder="john@example.com" variant="secondary" />
+                <FieldError />
+              </TextField>
+              <TextField
+                isRequired
+                name="bio"
+                validate={(value) => {
+                  if (value.length < 10) {
+                    return "Bio must be at least 10 characters";
+                  }
+
+                  return null;
+                }}
+              >
+                <Label>Bio</Label>
+                <TextArea placeholder="Tell us about yourself..." variant="secondary" />
+                <Description>Minimum 10 characters</Description>
+                <FieldError />
+              </TextField>
+            </Fieldset.Group>
+            <Fieldset.Actions>
+              <Button type="submit">
+                <FloppyDisk />
+                Save changes
+              </Button>
+              <Button type="reset" variant="tertiary">
+                Cancel
+              </Button>
+            </Fieldset.Actions>
+          </Fieldset>
+        </Form>
+      </Surface>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/form/basic.tsx b/apps/docs/src/demos/en/form/basic.tsx
new file mode 100644
index 0000000..23cbc9c
--- /dev/null
+++ b/apps/docs/src/demos/en/form/basic.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";
+
+export function Basic() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);
+  };
+
+  return (
+    <Form className="flex w-96 flex-col gap-4" onSubmit={onSubmit}>
+      <TextField
+        isRequired
+        name="email"
+        type="email"
+        validate={(value) => {
+          if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+            return "Please enter a valid email address";
+          }
+
+          return null;
+        }}
+      >
+        <Label>Email</Label>
+        <Input placeholder="john@example.com" />
+        <FieldError />
+      </TextField>
+
+      <TextField
+        isRequired
+        minLength={8}
+        name="password"
+        type="password"
+        validate={(value) => {
+          if (value.length < 8) {
+            return "Password must be at least 8 characters";
+          }
+          if (!/[A-Z]/.test(value)) {
+            return "Password must contain at least one uppercase letter";
+          }
+          if (!/[0-9]/.test(value)) {
+            return "Password must contain at least one number";
+          }
+
+          return null;
+        }}
+      >
+        <Label>Password</Label>
+        <Input placeholder="Enter your password" />
+        <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description>
+        <FieldError />
+      </TextField>
+
+      <div className="flex gap-2">
+        <Button type="submit">
+          <Check />
+          Submit
+        </Button>
+        <Button type="reset" variant="secondary">
+          Reset
+        </Button>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/form/custom-render-function.tsx b/apps/docs/src/demos/en/form/custom-render-function.tsx
new file mode 100644
index 0000000..b7ca636
--- /dev/null
+++ b/apps/docs/src/demos/en/form/custom-render-function.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);
+  };
+
+  return (
+    <Form
+      className="flex w-96 flex-col gap-4"
+      render={(props) => <form {...props} data-custom="foo" />}
+      onSubmit={onSubmit}
+    >
+      <TextField
+        isRequired
+        name="email"
+        type="email"
+        validate={(value) => {
+          if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
+            return "Please enter a valid email address";
+          }
+
+          return null;
+        }}
+      >
+        <Label>Email</Label>
+        <Input placeholder="john@example.com" />
+        <FieldError />
+      </TextField>
+
+      <TextField
+        isRequired
+        minLength={8}
+        name="password"
+        type="password"
+        validate={(value) => {
+          if (value.length < 8) {
+            return "Password must be at least 8 characters";
+          }
+          if (!/[A-Z]/.test(value)) {
+            return "Password must contain at least one uppercase letter";
+          }
+          if (!/[0-9]/.test(value)) {
+            return "Password must contain at least one number";
+          }
+
+          return null;
+        }}
+      >
+        <Label>Password</Label>
+        <Input placeholder="Enter your password" />
+        <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description>
+        <FieldError />
+      </TextField>
+
+      <div className="flex gap-2">
+        <Button type="submit">
+          <Check />
+          Submit
+        </Button>
+        <Button type="reset" variant="secondary">
+          Reset
+        </Button>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/form/index.ts b/apps/docs/src/demos/en/form/index.ts
new file mode 100644
index 0000000..9b0b4e7
--- /dev/null
+++ b/apps/docs/src/demos/en/form/index.ts
@@ -0,0 +1,2 @@
+export {Basic} from "./basic";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/index.ts b/apps/docs/src/demos/en/index.ts
new file mode 100644
index 0000000..2fe07c3
--- /dev/null
+++ b/apps/docs/src/demos/en/index.ts
@@ -0,0 +1,2536 @@
+/* eslint-disable sort-keys, sort-keys-fix/sort-keys-fix */
+import type {DemoItem} from "@/demos";
+
+export const demos: Record<string, DemoItem> = {
+  // Accordion demos
+  "accordion-basic": {
+    loader: () => import("./accordion/basic").then((m) => m.Basic),
+    file: "en/accordion/basic.tsx",
+  },
+  "accordion-surface": {
+    loader: () => import("./accordion/surface").then((m) => m.Surface),
+    file: "en/accordion/surface.tsx",
+  },
+  "accordion-multiple": {
+    loader: () => import("./accordion/multiple").then((m) => m.Multiple),
+    file: "en/accordion/multiple.tsx",
+  },
+  "accordion-disabled": {
+    loader: () => import("./accordion/disabled").then((m) => m.Disabled),
+    file: "en/accordion/disabled.tsx",
+  },
+  "accordion-custom-indicator": {
+    loader: () => import("./accordion/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/accordion/custom-indicator.tsx",
+  },
+  "accordion-faq": {
+    loader: () => import("./accordion/faq").then((m) => m.FAQ),
+    file: "en/accordion/faq.tsx",
+  },
+  "accordion-custom-styles": {
+    loader: () => import("./accordion/custom-styles").then((m) => m.CustomStyles),
+    file: "en/accordion/custom-styles.tsx",
+  },
+  "accordion-without-separator": {
+    loader: () => import("./accordion/without-separator").then((m) => m.WithoutSeparator),
+    file: "en/accordion/without-separator.tsx",
+  },
+  "accordion-custom-render-function": {
+    loader: () => import("./accordion/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/accordion/custom-render-function.tsx",
+  },
+  "accordion-controlled": {
+    loader: () => import("./accordion/controlled").then((m) => m.Controlled),
+    file: "en/accordion/controlled.tsx",
+  },
+  // Alert demos
+  "alert-basic": {
+    loader: () => import("./alert/basic").then((m) => m.Basic),
+    file: "en/alert/basic.tsx",
+  },
+  // AlertDialog demos
+  "alert-dialog-default": {
+    loader: () => import("./alert-dialog/default").then((m) => m.Default),
+    file: "en/alert-dialog/default.tsx",
+  },
+  "alert-dialog-statuses": {
+    loader: () => import("./alert-dialog/statuses").then((m) => m.Statuses),
+    file: "en/alert-dialog/statuses.tsx",
+  },
+  "alert-dialog-placements": {
+    loader: () => import("./alert-dialog/placements").then((m) => m.Placements),
+    file: "en/alert-dialog/placements.tsx",
+  },
+  "alert-dialog-backdrop-variants": {
+    loader: () => import("./alert-dialog/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "en/alert-dialog/backdrop-variants.tsx",
+  },
+  "alert-dialog-sizes": {
+    loader: () => import("./alert-dialog/sizes").then((m) => m.Sizes),
+    file: "en/alert-dialog/sizes.tsx",
+  },
+  "alert-dialog-controlled": {
+    loader: () => import("./alert-dialog/controlled").then((m) => m.Controlled),
+    file: "en/alert-dialog/controlled.tsx",
+  },
+  "alert-dialog-dismiss-behavior": {
+    loader: () => import("./alert-dialog/dismiss-behavior").then((m) => m.DismissBehavior),
+    file: "en/alert-dialog/dismiss-behavior.tsx",
+  },
+  "alert-dialog-custom-icon": {
+    loader: () => import("./alert-dialog/custom-icon").then((m) => m.CustomIcon),
+    file: "en/alert-dialog/custom-icon.tsx",
+  },
+  "alert-dialog-custom-backdrop": {
+    loader: () => import("./alert-dialog/custom-backdrop").then((m) => m.CustomBackdrop),
+    file: "en/alert-dialog/custom-backdrop.tsx",
+  },
+  "alert-dialog-custom-trigger": {
+    loader: () => import("./alert-dialog/custom-trigger").then((m) => m.CustomTrigger),
+    file: "en/alert-dialog/custom-trigger.tsx",
+  },
+  "alert-dialog-with-close-button": {
+    loader: () => import("./alert-dialog/with-close-button").then((m) => m.WithCloseButton),
+    file: "en/alert-dialog/with-close-button.tsx",
+  },
+  "alert-dialog-custom-animations": {
+    loader: () => import("./alert-dialog/custom-animations").then((m) => m.CustomAnimations),
+    file: "en/alert-dialog/custom-animations.tsx",
+  },
+  "alert-dialog-close-methods": {
+    loader: () => import("./alert-dialog/close-methods").then((m) => m.CloseMethods),
+    file: "en/alert-dialog/close-methods.tsx",
+  },
+  "alert-dialog-custom-portal": {
+    loader: () => import("./alert-dialog/custom-portal").then((m) => m.CustomPortal),
+    file: "en/alert-dialog/custom-portal.tsx",
+  },
+  // Avatar demos
+  "avatar-basic": {
+    loader: () => import("./avatar/basic").then((m) => m.Basic),
+    file: "en/avatar/basic.tsx",
+  },
+  "avatar-sizes": {
+    loader: () => import("./avatar/sizes").then((m) => m.Sizes),
+    file: "en/avatar/sizes.tsx",
+  },
+  "avatar-colors": {
+    loader: () => import("./avatar/colors").then((m) => m.Colors),
+    file: "en/avatar/colors.tsx",
+  },
+  "avatar-variants": {
+    loader: () => import("./avatar/variants").then((m) => m.Variants),
+    file: "en/avatar/variants.tsx",
+  },
+  "avatar-fallback": {
+    loader: () => import("./avatar/fallback").then((m) => m.Fallback),
+    file: "en/avatar/fallback.tsx",
+  },
+  "avatar-group": {
+    loader: () => import("./avatar/group").then((m) => m.Group),
+    file: "en/avatar/group.tsx",
+  },
+  "avatar-custom-styles": {
+    loader: () => import("./avatar/custom-styles").then((m) => m.CustomStyles),
+    file: "en/avatar/custom-styles.tsx",
+  },
+  // Badge demos
+  "badge-basic": {
+    loader: () => import("./badge/basic").then((m) => m.BadgeBasic),
+    file: "en/badge/basic.tsx",
+  },
+  "badge-colors": {
+    loader: () => import("./badge/colors").then((m) => m.BadgeColors),
+    file: "en/badge/colors.tsx",
+  },
+  "badge-sizes": {
+    loader: () => import("./badge/sizes").then((m) => m.BadgeSizes),
+    file: "en/badge/sizes.tsx",
+  },
+  "badge-variants": {
+    loader: () => import("./badge/variants").then((m) => m.BadgeVariants),
+    file: "en/badge/variants.tsx",
+  },
+  "badge-placements": {
+    loader: () => import("./badge/placements").then((m) => m.BadgePlacements),
+    file: "en/badge/placements.tsx",
+  },
+  "badge-with-content": {
+    loader: () => import("./badge/with-content").then((m) => m.BadgeWithContent),
+    file: "en/badge/with-content.tsx",
+  },
+  "badge-dot": {
+    loader: () => import("./badge/dot").then((m) => m.BadgeDot),
+    file: "en/badge/dot.tsx",
+  },
+  // Breadcrumbs demos
+  "breadcrumbs-basic": {
+    loader: () => import("./breadcrumbs/basic").then((m) => m.default),
+    file: "en/breadcrumbs/basic.tsx",
+  },
+  "breadcrumbs-level-2": {
+    loader: () => import("./breadcrumbs/level-2").then((m) => m.default),
+    file: "en/breadcrumbs/level-2.tsx",
+  },
+  "breadcrumbs-level-3": {
+    loader: () => import("./breadcrumbs/level-3").then((m) => m.default),
+    file: "en/breadcrumbs/level-3.tsx",
+  },
+  "breadcrumbs-custom-separator": {
+    loader: () => import("./breadcrumbs/custom-separator").then((m) => m.default),
+    file: "en/breadcrumbs/custom-separator.tsx",
+  },
+  "breadcrumbs-disabled": {
+    loader: () => import("./breadcrumbs/disabled").then((m) => m.default),
+    file: "en/breadcrumbs/disabled.tsx",
+  },
+  "breadcrumbs-custom-render-function": {
+    loader: () =>
+      import("./breadcrumbs/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/breadcrumbs/custom-render-function.tsx",
+  },
+  // Button demos
+  "button-basic": {
+    loader: () => import("./button/basic").then((m) => m.Basic),
+    file: "en/button/basic.tsx",
+  },
+  "button-custom-variants": {
+    loader: () => import("./button/custom-variants").then((m) => m.CustomVariants),
+    file: "en/button/custom-variants.tsx",
+  },
+  "button-disabled": {
+    loader: () => import("./button/disabled").then((m) => m.Disabled),
+    file: "en/button/disabled.tsx",
+  },
+  "button-icon-only": {
+    loader: () => import("./button/icon-only").then((m) => m.IconOnly),
+    file: "en/button/icon-only.tsx",
+  },
+  "button-loading": {
+    loader: () => import("./button/loading").then((m) => m.Loading),
+    file: "en/button/loading.tsx",
+  },
+  "button-loading-state": {
+    loader: () => import("./button/loading-state").then((m) => m.LoadingState),
+    file: "en/button/loading-state.tsx",
+  },
+  "button-sizes": {
+    loader: () => import("./button/sizes").then((m) => m.Sizes),
+    file: "en/button/sizes.tsx",
+  },
+  "button-full-width": {
+    loader: () => import("./button/full-width").then((m) => m.FullWidth),
+    file: "en/button/full-width.tsx",
+  },
+  "button-social": {
+    loader: () => import("./button/social").then((m) => m.Social),
+    file: "en/button/social.tsx",
+  },
+  "button-ripple-effect": {
+    loader: () => import("./button/ripple-effect").then((m) => m.RippleEffect),
+    file: "en/button/ripple-effect.tsx",
+  },
+  "button-variants": {
+    loader: () => import("./button/variants").then((m) => m.Variants),
+    file: "en/button/variants.tsx",
+  },
+  "button-outline-variant": {
+    loader: () => import("./button/outline-variant").then((m) => m.OutlineVariant),
+    file: "en/button/outline-variant.tsx",
+  },
+  "button-with-icons": {
+    loader: () => import("./button/with-icons").then((m) => m.WithIcons),
+    file: "en/button/with-icons.tsx",
+  },
+  "button-custom-render-function": {
+    loader: () => import("./button/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/button/custom-render-function.tsx",
+  },
+  // ButtonGroup demos
+  "button-group-basic": {
+    loader: () => import("./button-group/basic").then((m) => m.Basic),
+    file: "en/button-group/basic.tsx",
+  },
+  "button-group-disabled": {
+    loader: () => import("./button-group/disabled").then((m) => m.Disabled),
+    file: "en/button-group/disabled.tsx",
+  },
+  "button-group-sizes": {
+    loader: () => import("./button-group/sizes").then((m) => m.Sizes),
+    file: "en/button-group/sizes.tsx",
+  },
+  "button-group-full-width": {
+    loader: () => import("./button-group/full-width").then((m) => m.FullWidth),
+    file: "en/button-group/full-width.tsx",
+  },
+  "button-group-variants": {
+    loader: () => import("./button-group/variants").then((m) => m.Variants),
+    file: "en/button-group/variants.tsx",
+  },
+  "button-group-with-icons": {
+    loader: () => import("./button-group/with-icons").then((m) => m.WithIcons),
+    file: "en/button-group/with-icons.tsx",
+  },
+  "button-group-orientation": {
+    loader: () => import("./button-group/orientation").then((m) => m.Orientation),
+    file: "en/button-group/orientation.tsx",
+  },
+  "button-group-without-separator": {
+    loader: () => import("./button-group/without-separator").then((m) => m.WithoutSeparator),
+    file: "en/button-group/without-separator.tsx",
+  },
+  // Card demos
+  "card-default": {
+    loader: () => import("./card/default").then((m) => m.Default),
+    file: "en/card/default.tsx",
+  },
+  "card-horizontal": {
+    loader: () => import("./card/horizontal").then((m) => m.Horizontal),
+    file: "en/card/horizontal.tsx",
+  },
+  "card-variants": {
+    loader: () => import("./card/variants").then((m) => m.Variants),
+    file: "en/card/variants.tsx",
+  },
+  "card-with-avatar": {
+    loader: () => import("./card/with-avatar").then((m) => m.WithAvatar),
+    file: "en/card/with-avatar.tsx",
+  },
+  "card-with-form": {
+    loader: () => import("./card/with-form").then((m) => m.WithForm),
+    file: "en/card/with-form.tsx",
+  },
+  "card-with-images": {
+    loader: () => import("./card/with-images").then((m) => m.WithImages),
+    file: "en/card/with-images.tsx",
+  },
+  // Calendar demos
+  "calendar-basic": {
+    loader: () => import("./calendar/basic").then((m) => m.Basic),
+    file: "en/calendar/basic.tsx",
+  },
+  "calendar-custom-styles": {
+    loader: () => import("./calendar/custom-styles").then((m) => m.CustomStyles),
+    file: "en/calendar/custom-styles.tsx",
+  },
+  "calendar-default-value": {
+    loader: () => import("./calendar/default-value").then((m) => m.DefaultValue),
+    file: "en/calendar/default-value.tsx",
+  },
+  "calendar-controlled": {
+    loader: () => import("./calendar/controlled").then((m) => m.Controlled),
+    file: "en/calendar/controlled.tsx",
+  },
+  "calendar-min-max-dates": {
+    loader: () => import("./calendar/min-max-dates").then((m) => m.MinMaxDates),
+    file: "en/calendar/min-max-dates.tsx",
+  },
+  "calendar-unavailable-dates": {
+    loader: () => import("./calendar/unavailable-dates").then((m) => m.UnavailableDates),
+    file: "en/calendar/unavailable-dates.tsx",
+  },
+  "calendar-weeks-in-month": {
+    loader: () => import("./calendar/weeks-in-month").then((m) => m.WeeksInMonth),
+    file: "en/calendar/weeks-in-month.tsx",
+  },
+  "calendar-week-view": {
+    loader: () => import("./calendar/week-view").then((m) => m.WeekView),
+    file: "en/calendar/week-view.tsx",
+  },
+  "calendar-day-view": {
+    loader: () => import("./calendar/day-view").then((m) => m.DayView),
+    file: "en/calendar/day-view.tsx",
+  },
+  "calendar-multiple-selection": {
+    loader: () => import("./calendar/multiple-selection").then((m) => m.MultipleSelection),
+    file: "en/calendar/multiple-selection.tsx",
+  },
+  "calendar-disabled": {
+    loader: () => import("./calendar/disabled").then((m) => m.Disabled),
+    file: "en/calendar/disabled.tsx",
+  },
+  "calendar-read-only": {
+    loader: () => import("./calendar/read-only").then((m) => m.ReadOnly),
+    file: "en/calendar/read-only.tsx",
+  },
+  "calendar-focused-value": {
+    loader: () => import("./calendar/focused-value").then((m) => m.FocusedValue),
+    file: "en/calendar/focused-value.tsx",
+  },
+  "calendar-with-indicators": {
+    loader: () => import("./calendar/with-indicators").then((m) => m.WithIndicators),
+    file: "en/calendar/with-indicators.tsx",
+  },
+  "calendar-multiple-months": {
+    loader: () => import("./calendar/multiple-months").then((m) => m.MultipleMonths),
+    file: "en/calendar/multiple-months.tsx",
+  },
+  "calendar-year-picker": {
+    loader: () => import("./calendar/year-picker").then((m) => m.YearPicker),
+    file: "en/calendar/year-picker.tsx",
+  },
+  "calendar-international-calendar": {
+    loader: () => import("./calendar/international-calendar").then((m) => m.InternationalCalendar),
+    file: "en/calendar/international-calendar.tsx",
+  },
+  "calendar-booking-calendar": {
+    loader: () => import("./calendar/booking-calendar").then((m) => m.BookingCalendar),
+    file: "en/calendar/booking-calendar.tsx",
+  },
+  "calendar-custom-icons": {
+    loader: () => import("./calendar/custom-icons").then((m) => m.CustomIcons),
+    file: "en/calendar/custom-icons.tsx",
+  },
+  // RangeCalendar demos
+  "range-calendar-basic": {
+    loader: () => import("./range-calendar/basic").then((m) => m.Basic),
+    file: "en/range-calendar/basic.tsx",
+  },
+  "range-calendar-year-picker": {
+    loader: () => import("./range-calendar/year-picker").then((m) => m.YearPicker),
+    file: "en/range-calendar/year-picker.tsx",
+  },
+  "range-calendar-default-value": {
+    loader: () => import("./range-calendar/default-value").then((m) => m.DefaultValue),
+    file: "en/range-calendar/default-value.tsx",
+  },
+  "range-calendar-controlled": {
+    loader: () => import("./range-calendar/controlled").then((m) => m.Controlled),
+    file: "en/range-calendar/controlled.tsx",
+  },
+  "range-calendar-min-max-dates": {
+    loader: () => import("./range-calendar/min-max-dates").then((m) => m.MinMaxDates),
+    file: "en/range-calendar/min-max-dates.tsx",
+  },
+  "range-calendar-unavailable-dates": {
+    loader: () => import("./range-calendar/unavailable-dates").then((m) => m.UnavailableDates),
+    file: "en/range-calendar/unavailable-dates.tsx",
+  },
+  "range-calendar-anchor-unavailable-dates": {
+    loader: () =>
+      import("./range-calendar/anchor-unavailable-dates").then((m) => m.AnchorUnavailableDates),
+    file: "en/range-calendar/anchor-unavailable-dates.tsx",
+  },
+  "range-calendar-weeks-in-month": {
+    loader: () => import("./range-calendar/weeks-in-month").then((m) => m.WeeksInMonth),
+    file: "en/range-calendar/weeks-in-month.tsx",
+  },
+  "range-calendar-week-view": {
+    loader: () => import("./range-calendar/week-view").then((m) => m.WeekView),
+    file: "en/range-calendar/week-view.tsx",
+  },
+  "range-calendar-day-view": {
+    loader: () => import("./range-calendar/day-view").then((m) => m.DayView),
+    file: "en/range-calendar/day-view.tsx",
+  },
+  "range-calendar-allows-non-contiguous-ranges": {
+    loader: () =>
+      import("./range-calendar/allows-non-contiguous-ranges").then(
+        (m) => m.AllowsNonContiguousRanges,
+      ),
+    file: "en/range-calendar/allows-non-contiguous-ranges.tsx",
+  },
+  "range-calendar-disabled": {
+    loader: () => import("./range-calendar/disabled").then((m) => m.Disabled),
+    file: "en/range-calendar/disabled.tsx",
+  },
+  "range-calendar-read-only": {
+    loader: () => import("./range-calendar/read-only").then((m) => m.ReadOnly),
+    file: "en/range-calendar/read-only.tsx",
+  },
+  "range-calendar-invalid": {
+    loader: () => import("./range-calendar/invalid").then((m) => m.Invalid),
+    file: "en/range-calendar/invalid.tsx",
+  },
+  "range-calendar-focused-value": {
+    loader: () => import("./range-calendar/focused-value").then((m) => m.FocusedValue),
+    file: "en/range-calendar/focused-value.tsx",
+  },
+  "range-calendar-with-indicators": {
+    loader: () => import("./range-calendar/with-indicators").then((m) => m.WithIndicators),
+    file: "en/range-calendar/with-indicators.tsx",
+  },
+  "range-calendar-multiple-months": {
+    loader: () => import("./range-calendar/multiple-months").then((m) => m.MultipleMonths),
+    file: "en/range-calendar/multiple-months.tsx",
+  },
+  "range-calendar-three-months": {
+    loader: () => import("./range-calendar/three-months").then((m) => m.ThreeMonths),
+    file: "en/range-calendar/three-months.tsx",
+  },
+  "range-calendar-international-calendar": {
+    loader: () =>
+      import("./range-calendar/international-calendar").then((m) => m.InternationalCalendar),
+    file: "en/range-calendar/international-calendar.tsx",
+  },
+  "range-calendar-booking-calendar": {
+    loader: () => import("./range-calendar/booking-calendar").then((m) => m.BookingCalendar),
+    file: "en/range-calendar/booking-calendar.tsx",
+  },
+  // Checkbox demos
+  "checkbox-basic": {
+    loader: () => import("./checkbox/basic").then((m) => m.Basic),
+    file: "en/checkbox/basic.tsx",
+  },
+  "checkbox-disabled": {
+    loader: () => import("./checkbox/disabled").then((m) => m.Disabled),
+    file: "en/checkbox/disabled.tsx",
+  },
+  "checkbox-default-selected": {
+    loader: () => import("./checkbox/default-selected").then((m) => m.DefaultSelected),
+    file: "en/checkbox/default-selected.tsx",
+  },
+  "checkbox-controlled": {
+    loader: () => import("./checkbox/controlled").then((m) => m.Controlled),
+    file: "en/checkbox/controlled.tsx",
+  },
+  "checkbox-indeterminate": {
+    loader: () => import("./checkbox/indeterminate").then((m) => m.Indeterminate),
+    file: "en/checkbox/indeterminate.tsx",
+  },
+  "checkbox-external-label": {
+    loader: () => import("./checkbox/external-label").then((m) => m.ExternalLabel),
+    file: "en/checkbox/external-label.tsx",
+  },
+  "checkbox-with-description": {
+    loader: () => import("./checkbox/with-description").then((m) => m.WithDescription),
+    file: "en/checkbox/with-description.tsx",
+  },
+  "checkbox-render-props": {
+    loader: () => import("./checkbox/render-props").then((m) => m.RenderProps),
+    file: "en/checkbox/render-props.tsx",
+  },
+  "checkbox-form": {
+    loader: () => import("./checkbox/form").then((m) => m.Form),
+    file: "en/checkbox/form.tsx",
+  },
+  "checkbox-custom-styles": {
+    loader: () => import("./checkbox/custom-styles").then((m) => m.CustomStyles),
+    file: "en/checkbox/custom-styles.tsx",
+  },
+  "checkbox-invalid": {
+    loader: () => import("./checkbox/invalid").then((m) => m.Invalid),
+    file: "en/checkbox/invalid.tsx",
+  },
+  "checkbox-custom-indicator": {
+    loader: () => import("./checkbox/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/checkbox/custom-indicator.tsx",
+  },
+  "checkbox-full-rounded": {
+    loader: () => import("./checkbox/full-rounded").then((m) => m.FullRounded),
+    file: "en/checkbox/full-rounded.tsx",
+  },
+  "checkbox-variants": {
+    loader: () => import("./checkbox/variants").then((m) => m.Variants),
+    file: "en/checkbox/variants.tsx",
+  },
+  "checkbox-custom-render-function": {
+    loader: () => import("./checkbox/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/checkbox/custom-render-function.tsx",
+  },
+  // CheckboxGroup demos
+  "checkbox-group-basic": {
+    loader: () => import("./checkbox-group/basic").then((m) => m.Basic),
+    file: "en/checkbox-group/basic.tsx",
+  },
+  "checkbox-group-on-surface": {
+    loader: () => import("./checkbox-group/on-surface").then((m) => m.OnSurface),
+    file: "en/checkbox-group/on-surface.tsx",
+  },
+  "checkbox-group-with-custom-indicator": {
+    loader: () =>
+      import("./checkbox-group/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "en/checkbox-group/with-custom-indicator.tsx",
+  },
+  "checkbox-group-indeterminate": {
+    loader: () => import("./checkbox-group/indeterminate").then((m) => m.Indeterminate),
+    file: "en/checkbox-group/indeterminate.tsx",
+  },
+  "checkbox-group-validation": {
+    loader: () => import("./checkbox-group/validation").then((m) => m.Validation),
+    file: "en/checkbox-group/validation.tsx",
+  },
+  "checkbox-group-controlled": {
+    loader: () => import("./checkbox-group/controlled").then((m) => m.Controlled),
+    file: "en/checkbox-group/controlled.tsx",
+  },
+  "checkbox-group-disabled": {
+    loader: () => import("./checkbox-group/disabled").then((m) => m.Disabled),
+    file: "en/checkbox-group/disabled.tsx",
+  },
+  "checkbox-group-features-and-addons": {
+    loader: () => import("./checkbox-group/features-and-addons").then((m) => m.FeaturesAndAddOns),
+    file: "en/checkbox-group/features-and-addons.tsx",
+  },
+  "checkbox-group-custom-render-function": {
+    loader: () =>
+      import("./checkbox-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/checkbox-group/custom-render-function.tsx",
+  },
+  // Chip demos
+  "chip-basic": {
+    loader: () => import("./chip/basic").then((m) => m.ChipBasic),
+    file: "en/chip/basic.tsx",
+  },
+  "chip-variants": {
+    loader: () => import("./chip/variants").then((m) => m.ChipVariants),
+    file: "en/chip/variants.tsx",
+  },
+  "chip-with-icon": {
+    loader: () => import("./chip/with-icon").then((m) => m.ChipWithIcon),
+    file: "en/chip/with-icon.tsx",
+  },
+  "chip-statuses": {
+    loader: () => import("./chip/statuses").then((m) => m.ChipStatuses),
+    file: "en/chip/statuses.tsx",
+  },
+  "chip-vibrant-palette": {
+    loader: () => import("./chip/vibrant-palette").then((m) => m.ChipVibrantPalette),
+    file: "en/chip/vibrant-palette.tsx",
+  },
+  // ColorField demos
+  "color-field-basic": {
+    loader: () => import("./color-field/basic").then((m) => m.Basic),
+    file: "en/color-field/basic.tsx",
+  },
+  "color-field-channel-editing": {
+    loader: () => import("./color-field/channel-editing").then((m) => m.ChannelEditing),
+    file: "en/color-field/channel-editing.tsx",
+  },
+  "color-field-controlled": {
+    loader: () => import("./color-field/controlled").then((m) => m.Controlled),
+    file: "en/color-field/controlled.tsx",
+  },
+  "color-field-disabled": {
+    loader: () => import("./color-field/disabled").then((m) => m.Disabled),
+    file: "en/color-field/disabled.tsx",
+  },
+  "color-field-form-example": {
+    loader: () => import("./color-field/form-example").then((m) => m.FormExample),
+    file: "en/color-field/form-example.tsx",
+  },
+  "color-field-full-width": {
+    loader: () => import("./color-field/full-width").then((m) => m.FullWidth),
+    file: "en/color-field/full-width.tsx",
+  },
+  "color-field-invalid": {
+    loader: () => import("./color-field/invalid").then((m) => m.Invalid),
+    file: "en/color-field/invalid.tsx",
+  },
+  "color-field-on-surface": {
+    loader: () => import("./color-field/on-surface").then((m) => m.OnSurface),
+    file: "en/color-field/on-surface.tsx",
+  },
+  "color-field-required": {
+    loader: () => import("./color-field/required").then((m) => m.Required),
+    file: "en/color-field/required.tsx",
+  },
+  "color-field-variants": {
+    loader: () => import("./color-field/variants").then((m) => m.Variants),
+    file: "en/color-field/variants.tsx",
+  },
+  "color-field-with-description": {
+    loader: () => import("./color-field/with-description").then((m) => m.WithDescription),
+    file: "en/color-field/with-description.tsx",
+  },
+  "color-field-custom-render-function": {
+    loader: () =>
+      import("./color-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/color-field/custom-render-function.tsx",
+  },
+  // ColorPicker demos
+  "color-picker-basic": {
+    loader: () => import("./color-picker/basic").then((m) => m.Basic),
+    file: "en/color-picker/basic.tsx",
+  },
+  "color-picker-controlled": {
+    loader: () => import("./color-picker/controlled").then((m) => m.Controlled),
+    file: "en/color-picker/controlled.tsx",
+  },
+  "color-picker-with-swatches": {
+    loader: () => import("./color-picker/with-swatches").then((m) => m.WithSwatches),
+    file: "en/color-picker/with-swatches.tsx",
+  },
+  "color-picker-with-fields": {
+    loader: () => import("./color-picker/with-fields").then((m) => m.WithFields),
+    file: "en/color-picker/with-fields.tsx",
+  },
+  "color-picker-with-sliders": {
+    loader: () => import("./color-picker/with-sliders").then((m) => m.WithSliders),
+    file: "en/color-picker/with-sliders.tsx",
+  },
+  // ColorArea demos
+  "color-area-basic": {
+    loader: () => import("./color-area/basic").then((m) => m.ColorAreaBasic),
+    file: "en/color-area/basic.tsx",
+  },
+  "color-area-with-dots": {
+    loader: () => import("./color-area/with-dots").then((m) => m.ColorAreaWithDots),
+    file: "en/color-area/with-dots.tsx",
+  },
+  "color-area-space-and-channels": {
+    loader: () =>
+      import("./color-area/space-and-channels").then((m) => m.ColorAreaSpaceAndChannels),
+    file: "en/color-area/space-and-channels.tsx",
+  },
+  "color-area-controlled": {
+    loader: () => import("./color-area/controlled").then((m) => m.ColorAreaControlled),
+    file: "en/color-area/controlled.tsx",
+  },
+  "color-area-disabled": {
+    loader: () => import("./color-area/disabled").then((m) => m.ColorAreaDisabled),
+    file: "en/color-area/disabled.tsx",
+  },
+  "color-area-custom-render-function": {
+    loader: () => import("./color-area/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/color-area/custom-render-function.tsx",
+  },
+  // ColorSwatch demos
+  "color-swatch-basic": {
+    loader: () => import("./color-swatch/basic").then((m) => m.ColorSwatchBasic),
+    file: "en/color-swatch/basic.tsx",
+  },
+  "color-swatch-sizes": {
+    loader: () => import("./color-swatch/sizes").then((m) => m.ColorSwatchSizes),
+    file: "en/color-swatch/sizes.tsx",
+  },
+  "color-swatch-shapes": {
+    loader: () => import("./color-swatch/shapes").then((m) => m.ColorSwatchShapes),
+    file: "en/color-swatch/shapes.tsx",
+  },
+  "color-swatch-transparency": {
+    loader: () => import("./color-swatch/transparency").then((m) => m.ColorSwatchTransparency),
+    file: "en/color-swatch/transparency.tsx",
+  },
+  "color-swatch-custom-styles": {
+    loader: () => import("./color-swatch/custom-styles").then((m) => m.ColorSwatchCustomStyles),
+    file: "en/color-swatch/custom-styles.tsx",
+  },
+  "color-swatch-accessibility": {
+    loader: () => import("./color-swatch/accessibility").then((m) => m.ColorSwatchAccessibility),
+    file: "en/color-swatch/accessibility.tsx",
+  },
+  "color-swatch-custom-render-function": {
+    loader: () =>
+      import("./color-swatch/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/color-swatch/custom-render-function.tsx",
+  },
+  // ColorSlider demos
+  "color-slider-basic": {
+    loader: () => import("./color-slider/basic").then((m) => m.Basic),
+    file: "en/color-slider/basic.tsx",
+  },
+  "color-slider-channels": {
+    loader: () => import("./color-slider/channels").then((m) => m.Channels),
+    file: "en/color-slider/channels.tsx",
+  },
+  "color-slider-alpha-channel": {
+    loader: () => import("./color-slider/alpha-channel").then((m) => m.AlphaChannel),
+    file: "en/color-slider/alpha-channel.tsx",
+  },
+  "color-slider-rgb-channels": {
+    loader: () => import("./color-slider/rgb-channels").then((m) => m.RGBChannels),
+    file: "en/color-slider/rgb-channels.tsx",
+  },
+  "color-slider-vertical": {
+    loader: () => import("./color-slider/vertical").then((m) => m.Vertical),
+    file: "en/color-slider/vertical.tsx",
+  },
+  "color-slider-disabled": {
+    loader: () => import("./color-slider/disabled").then((m) => m.Disabled),
+    file: "en/color-slider/disabled.tsx",
+  },
+  "color-slider-controlled": {
+    loader: () => import("./color-slider/controlled").then((m) => m.Controlled),
+    file: "en/color-slider/controlled.tsx",
+  },
+  "color-slider-custom-render-function": {
+    loader: () =>
+      import("./color-slider/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/color-slider/custom-render-function.tsx",
+  },
+  // CloseButton demos
+  "close-button-default": {
+    loader: () => import("./close-button/default").then((m) => m.Default),
+    file: "en/close-button/default.tsx",
+  },
+  "close-button-with-custom-icon": {
+    loader: () => import("./close-button/with-custom-icon").then((m) => m.WithCustomIcon),
+    file: "en/close-button/with-custom-icon.tsx",
+  },
+  "close-button-interactive": {
+    loader: () => import("./close-button/interactive").then((m) => m.Interactive),
+    file: "en/close-button/interactive.tsx",
+  },
+  // ColorSwatchPicker demos
+  "color-swatch-picker-basic": {
+    loader: () => import("./color-swatch-picker/basic").then((m) => m.Basic),
+    file: "en/color-swatch-picker/basic.tsx",
+  },
+  "color-swatch-picker-sizes": {
+    loader: () => import("./color-swatch-picker/sizes").then((m) => m.Sizes),
+    file: "en/color-swatch-picker/sizes.tsx",
+  },
+  "color-swatch-picker-variants": {
+    loader: () => import("./color-swatch-picker/variants").then((m) => m.Variants),
+    file: "en/color-swatch-picker/variants.tsx",
+  },
+  "color-swatch-picker-stack-layout": {
+    loader: () => import("./color-swatch-picker/stack-layout").then((m) => m.StackLayout),
+    file: "en/color-swatch-picker/stack-layout.tsx",
+  },
+  "color-swatch-picker-controlled": {
+    loader: () => import("./color-swatch-picker/controlled").then((m) => m.Controlled),
+    file: "en/color-swatch-picker/controlled.tsx",
+  },
+  "color-swatch-picker-disabled": {
+    loader: () => import("./color-swatch-picker/disabled").then((m) => m.Disabled),
+    file: "en/color-swatch-picker/disabled.tsx",
+  },
+  "color-swatch-picker-default-value": {
+    loader: () => import("./color-swatch-picker/default-value").then((m) => m.DefaultValue),
+    file: "en/color-swatch-picker/default-value.tsx",
+  },
+  "color-swatch-picker-custom-indicator": {
+    loader: () => import("./color-swatch-picker/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/color-swatch-picker/custom-indicator.tsx",
+  },
+  "color-swatch-picker-custom-render-function": {
+    loader: () =>
+      import("./color-swatch-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/color-swatch-picker/custom-render-function.tsx",
+  },
+  // Autocomplete demos
+  "autocomplete-default": {
+    loader: () => import("./autocomplete/default").then((m) => m.default),
+    file: "en/autocomplete/default.tsx",
+  },
+  "autocomplete-single-select": {
+    loader: () => import("./autocomplete/single-select").then((m) => m.default),
+    file: "en/autocomplete/single-select.tsx",
+  },
+  "autocomplete-variants": {
+    loader: () => import("./autocomplete/variants").then((m) => m.Variants),
+    file: "en/autocomplete/variants.tsx",
+  },
+  "autocomplete-multiple-select": {
+    loader: () => import("./autocomplete/multiple-select").then((m) => m.MultipleSelect),
+    file: "en/autocomplete/multiple-select.tsx",
+  },
+  "autocomplete-full-width": {
+    loader: () => import("./autocomplete/full-width").then((m) => m.FullWidth),
+    file: "en/autocomplete/full-width.tsx",
+  },
+  "autocomplete-with-description": {
+    loader: () => import("./autocomplete/with-description").then((m) => m.WithDescription),
+    file: "en/autocomplete/with-description.tsx",
+  },
+  "autocomplete-with-sections": {
+    loader: () => import("./autocomplete/with-sections").then((m) => m.WithSections),
+    file: "en/autocomplete/with-sections.tsx",
+  },
+  "autocomplete-with-disabled-options": {
+    loader: () => import("./autocomplete/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "en/autocomplete/with-disabled-options.tsx",
+  },
+  "autocomplete-allows-empty-collection": {
+    loader: () =>
+      import("./autocomplete/allows-empty-collection").then((m) => m.AllowsEmptyCollection),
+    file: "en/autocomplete/allows-empty-collection.tsx",
+  },
+  "autocomplete-custom-indicator": {
+    loader: () => import("./autocomplete/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/autocomplete/custom-indicator.tsx",
+  },
+  "autocomplete-required": {
+    loader: () => import("./autocomplete/required").then((m) => m.Required),
+    file: "en/autocomplete/required.tsx",
+  },
+  "autocomplete-controlled": {
+    loader: () => import("./autocomplete/controlled").then((m) => m.Controlled),
+    file: "en/autocomplete/controlled.tsx",
+  },
+  "autocomplete-controlled-open-state": {
+    loader: () => import("./autocomplete/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "en/autocomplete/controlled-open-state.tsx",
+  },
+  "autocomplete-asynchronous-filtering": {
+    loader: () =>
+      import("./autocomplete/asynchronous-filtering").then((m) => m.AsynchronousFiltering),
+    file: "en/autocomplete/asynchronous-filtering.tsx",
+  },
+  "autocomplete-virtualization": {
+    loader: () => import("./autocomplete/virtualization").then((m) => m.Virtualization),
+    file: "en/autocomplete/virtualization.tsx",
+  },
+  "autocomplete-disabled": {
+    loader: () => import("./autocomplete/disabled").then((m) => m.Disabled),
+    file: "en/autocomplete/disabled.tsx",
+  },
+  "autocomplete-user-selection": {
+    loader: () => import("./autocomplete/user-selection").then((m) => m.UserSelection),
+    file: "en/autocomplete/user-selection.tsx",
+  },
+  "autocomplete-user-selection-multiple": {
+    loader: () =>
+      import("./autocomplete/user-selection-multiple").then((m) => m.UserSelectionMultiple),
+    file: "en/autocomplete/user-selection-multiple.tsx",
+  },
+  "autocomplete-location-search": {
+    loader: () => import("./autocomplete/location-search").then((m) => m.LocationSearch),
+    file: "en/autocomplete/location-search.tsx",
+  },
+  "autocomplete-tag-group-selection": {
+    loader: () => import("./autocomplete/tag-group-selection").then((m) => m.TagGroupSelection),
+    file: "en/autocomplete/tag-group-selection.tsx",
+  },
+  "autocomplete-email-recipients": {
+    loader: () => import("./autocomplete/email-recipients").then((m) => m.EmailRecipients),
+    file: "en/autocomplete/email-recipients.tsx",
+  },
+  // ComboBox demos
+  "combo-box-default": {
+    loader: () => import("./combo-box/default").then((m) => m.Default),
+    file: "en/combo-box/default.tsx",
+  },
+  "combo-box-default-selected-key": {
+    loader: () => import("./combo-box/default-selected-key").then((m) => m.DefaultSelectedKey),
+    file: "en/combo-box/default-selected-key.tsx",
+  },
+  "combo-box-with-description": {
+    loader: () => import("./combo-box/with-description").then((m) => m.WithDescription),
+    file: "en/combo-box/with-description.tsx",
+  },
+  "combo-box-with-sections": {
+    loader: () => import("./combo-box/with-sections").then((m) => m.WithSections),
+    file: "en/combo-box/with-sections.tsx",
+  },
+  "combo-box-with-disabled-options": {
+    loader: () => import("./combo-box/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "en/combo-box/with-disabled-options.tsx",
+  },
+  "combo-box-custom-indicator": {
+    loader: () => import("./combo-box/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/combo-box/custom-indicator.tsx",
+  },
+  "combo-box-required": {
+    loader: () => import("./combo-box/required").then((m) => m.Required),
+    file: "en/combo-box/required.tsx",
+  },
+  "combo-box-full-width": {
+    loader: () => import("./combo-box/full-width").then((m) => m.FullWidth),
+    file: "en/combo-box/full-width.tsx",
+  },
+  "combo-box-custom-value": {
+    loader: () => import("./combo-box/custom-value").then((m) => m.CustomValue),
+    file: "en/combo-box/custom-value.tsx",
+  },
+  "combo-box-controlled": {
+    loader: () => import("./combo-box/controlled").then((m) => m.Controlled),
+    file: "en/combo-box/controlled.tsx",
+  },
+  "combo-box-controlled-input-value": {
+    loader: () => import("./combo-box/controlled-input-value").then((m) => m.ControlledInputValue),
+    file: "en/combo-box/controlled-input-value.tsx",
+  },
+  "combo-box-asynchronous-loading": {
+    loader: () => import("./combo-box/asynchronous-loading").then((m) => m.AsynchronousLoading),
+    file: "en/combo-box/asynchronous-loading.tsx",
+  },
+  "combo-box-custom-filtering": {
+    loader: () => import("./combo-box/custom-filtering").then((m) => m.CustomFiltering),
+    file: "en/combo-box/custom-filtering.tsx",
+  },
+  "combo-box-allows-custom-value": {
+    loader: () => import("./combo-box/allows-custom-value").then((m) => m.AllowsCustomValue),
+    file: "en/combo-box/allows-custom-value.tsx",
+  },
+  "combo-box-disabled": {
+    loader: () => import("./combo-box/disabled").then((m) => m.Disabled),
+    file: "en/combo-box/disabled.tsx",
+  },
+  "combo-box-on-surface": {
+    loader: () => import("./combo-box/on-surface").then((m) => m.OnSurface),
+    file: "en/combo-box/on-surface.tsx",
+  },
+  "combo-box-menu-trigger": {
+    loader: () => import("./combo-box/menu-trigger").then((m) => m.MenuTrigger),
+    file: "en/combo-box/menu-trigger.tsx",
+  },
+  "combo-box-custom-render-function": {
+    loader: () => import("./combo-box/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/combo-box/custom-render-function.tsx",
+  },
+  // Drawer demos
+  "drawer-basic": {
+    loader: () => import("./drawer/basic").then((m) => m.Basic),
+    file: "en/drawer/basic.tsx",
+  },
+  "drawer-placements": {
+    loader: () => import("./drawer/placements").then((m) => m.Placements),
+    file: "en/drawer/placements.tsx",
+  },
+  "drawer-backdrop-variants": {
+    loader: () => import("./drawer/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "en/drawer/backdrop-variants.tsx",
+  },
+  "drawer-with-form": {
+    loader: () => import("./drawer/with-form").then((m) => m.WithForm),
+    file: "en/drawer/with-form.tsx",
+  },
+  "drawer-scrollable-content": {
+    loader: () => import("./drawer/scrollable-content").then((m) => m.ScrollableContent),
+    file: "en/drawer/scrollable-content.tsx",
+  },
+  "drawer-navigation": {
+    loader: () => import("./drawer/navigation").then((m) => m.Navigation),
+    file: "en/drawer/navigation.tsx",
+  },
+  "drawer-non-dismissable": {
+    loader: () => import("./drawer/non-dismissable").then((m) => m.NonDismissable),
+    file: "en/drawer/non-dismissable.tsx",
+  },
+  "drawer-controlled": {
+    loader: () => import("./drawer/controlled").then((m) => m.Controlled),
+    file: "en/drawer/controlled.tsx",
+  },
+  // Disclosure demos
+  "disclosure-basic": {
+    loader: () => import("./disclosure/basic").then((m) => m.Basic),
+    file: "en/disclosure/basic.tsx",
+  },
+  "disclosure-custom-render-function": {
+    loader: () => import("./disclosure/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/disclosure/custom-render-function.tsx",
+  },
+  // DisclosureGroup demos
+  "disclosure-group-basic": {
+    loader: () => import("./disclosure-group/basic").then((m) => m.Basic),
+    file: "en/disclosure-group/basic.tsx",
+  },
+  "disclosure-group-controlled": {
+    loader: () => import("./disclosure-group/controlled").then((m) => m.Controlled),
+    file: "en/disclosure-group/controlled.tsx",
+  },
+  // Dropdown demos
+  "dropdown-default": {
+    loader: () => import("./dropdown/default").then((m) => m.Default),
+    file: "en/dropdown/default.tsx",
+  },
+  "dropdown-with-single-selection": {
+    loader: () => import("./dropdown/with-single-selection").then((m) => m.WithSingleSelection),
+    file: "en/dropdown/with-single-selection.tsx",
+  },
+  "dropdown-single-with-custom-indicator": {
+    loader: () =>
+      import("./dropdown/single-with-custom-indicator").then((m) => m.SingleWithCustomIndicator),
+    file: "en/dropdown/single-with-custom-indicator.tsx",
+  },
+  "dropdown-with-multiple-selection": {
+    loader: () => import("./dropdown/with-multiple-selection").then((m) => m.WithMultipleSelection),
+    file: "en/dropdown/with-multiple-selection.tsx",
+  },
+  "dropdown-with-section-level-selection": {
+    loader: () =>
+      import("./dropdown/with-section-level-selection").then((m) => m.WithSectionLevelSelection),
+    file: "en/dropdown/with-section-level-selection.tsx",
+  },
+  "dropdown-with-keyboard-shortcuts": {
+    loader: () => import("./dropdown/with-keyboard-shortcuts").then((m) => m.WithKeyboardShortcuts),
+    file: "en/dropdown/with-keyboard-shortcuts.tsx",
+  },
+  "dropdown-with-icons": {
+    loader: () => import("./dropdown/with-icons").then((m) => m.WithIcons),
+    file: "en/dropdown/with-icons.tsx",
+  },
+  "dropdown-long-press-trigger": {
+    loader: () => import("./dropdown/long-press-trigger").then((m) => m.LongPressTrigger),
+    file: "en/dropdown/long-press-trigger.tsx",
+  },
+  "dropdown-with-descriptions": {
+    loader: () => import("./dropdown/with-descriptions").then((m) => m.WithDescriptions),
+    file: "en/dropdown/with-descriptions.tsx",
+  },
+  "dropdown-with-sections": {
+    loader: () => import("./dropdown/with-sections").then((m) => m.WithSections),
+    file: "en/dropdown/with-sections.tsx",
+  },
+  "dropdown-with-disabled-items": {
+    loader: () => import("./dropdown/with-disabled-items").then((m) => m.WithDisabledItems),
+    file: "en/dropdown/with-disabled-items.tsx",
+  },
+  "dropdown-with-submenus": {
+    loader: () => import("./dropdown/with-submenus").then((m) => m.WithSubmenus),
+    file: "en/dropdown/with-submenus.tsx",
+  },
+  "dropdown-with-custom-submenu-indicator": {
+    loader: () =>
+      import("./dropdown/with-custom-submenu-indicator").then((m) => m.WithCustomSubmenuIndicator),
+    file: "en/dropdown/with-custom-submenu-indicator.tsx",
+  },
+  "dropdown-controlled": {
+    loader: () => import("./dropdown/controlled").then((m) => m.Controlled),
+    file: "en/dropdown/controlled.tsx",
+  },
+  "dropdown-controlled-open-state": {
+    loader: () => import("./dropdown/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "en/dropdown/controlled-open-state.tsx",
+  },
+  "dropdown-custom-trigger": {
+    loader: () => import("./dropdown/custom-trigger").then((m) => m.CustomTrigger),
+    file: "en/dropdown/custom-trigger.tsx",
+  },
+  // ErrorMessage demos
+  "error-message-basic": {
+    loader: () => import("./error-message/basic").then((m) => m.ErrorMessageBasic),
+    file: "en/error-message/basic.tsx",
+  },
+  "error-message-with-tag-group": {
+    loader: () => import("./error-message/with-tag-group").then((m) => m.ErrorMessageWithTagGroup),
+    file: "en/error-message/with-tag-group.tsx",
+  },
+  // Form demos
+  "form-basic": {
+    loader: () => import("./form/basic").then((m) => m.Basic),
+    file: "en/form/basic.tsx",
+  },
+  "form-custom-render-function": {
+    loader: () => import("./form/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/form/custom-render-function.tsx",
+  },
+  // Fieldset demos
+  "fieldset-basic": {
+    loader: () => import("./fieldset/basic").then((m) => m.Basic),
+    file: "en/fieldset/basic.tsx",
+  },
+  "fieldset-on-surface": {
+    loader: () => import("./fieldset/on-surface").then((m) => m.OnSurface),
+    file: "en/fieldset/on-surface.tsx",
+  },
+  // Input demos
+  "input-basic": {
+    loader: () => import("./input/basic").then((m) => m.Basic),
+    file: "en/input/basic.tsx",
+  },
+  "input-full-width": {
+    loader: () => import("./input/full-width").then((m) => m.FullWidth),
+    file: "en/input/full-width.tsx",
+  },
+  "input-types": {
+    loader: () => import("./input/types").then((m) => m.Types),
+    file: "en/input/types.tsx",
+  },
+  "input-controlled": {
+    loader: () => import("./input/controlled").then((m) => m.Controlled),
+    file: "en/input/controlled.tsx",
+  },
+  "input-on-surface": {
+    loader: () => import("./input/on-surface").then((m) => m.OnSurface),
+    file: "en/input/on-surface.tsx",
+  },
+  "input-variants": {
+    loader: () => import("./input/variants").then((m) => m.Variants),
+    file: "en/input/variants.tsx",
+  },
+  // DateField demos
+  "date-field-basic": {
+    loader: () => import("./date-field/basic").then((m) => m.Basic),
+    file: "en/date-field/basic.tsx",
+  },
+  "date-field-controlled": {
+    loader: () => import("./date-field/controlled").then((m) => m.Controlled),
+    file: "en/date-field/controlled.tsx",
+  },
+  "date-field-disabled": {
+    loader: () => import("./date-field/disabled").then((m) => m.Disabled),
+    file: "en/date-field/disabled.tsx",
+  },
+  "date-field-form-example": {
+    loader: () => import("./date-field/form-example").then((m) => m.FormExample),
+    file: "en/date-field/form-example.tsx",
+  },
+  "date-field-invalid": {
+    loader: () => import("./date-field/invalid").then((m) => m.Invalid),
+    file: "en/date-field/invalid.tsx",
+  },
+  "date-field-on-surface": {
+    loader: () => import("./date-field/on-surface").then((m) => m.OnSurface),
+    file: "en/date-field/on-surface.tsx",
+  },
+  "date-field-required": {
+    loader: () => import("./date-field/required").then((m) => m.Required),
+    file: "en/date-field/required.tsx",
+  },
+  "date-field-with-description": {
+    loader: () => import("./date-field/with-description").then((m) => m.WithDescription),
+    file: "en/date-field/with-description.tsx",
+  },
+  "date-field-with-prefix-and-suffix": {
+    loader: () => import("./date-field/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "en/date-field/with-prefix-and-suffix.tsx",
+  },
+  "date-field-with-prefix-icon": {
+    loader: () => import("./date-field/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "en/date-field/with-prefix-icon.tsx",
+  },
+  "date-field-with-suffix-icon": {
+    loader: () => import("./date-field/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "en/date-field/with-suffix-icon.tsx",
+  },
+  "date-field-full-width": {
+    loader: () => import("./date-field/full-width").then((m) => m.FullWidth),
+    file: "en/date-field/full-width.tsx",
+  },
+  "date-field-granularity": {
+    loader: () => import("./date-field/granularity").then((m) => m.Granularity),
+    file: "en/date-field/granularity.tsx",
+  },
+  "date-field-with-validation": {
+    loader: () => import("./date-field/with-validation").then((m) => m.WithValidation),
+    file: "en/date-field/with-validation.tsx",
+  },
+  "date-field-variants": {
+    loader: () => import("./date-field/variants").then((m) => m.Variants),
+    file: "en/date-field/variants.tsx",
+  },
+  "date-field-custom-render-function": {
+    loader: () => import("./date-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/date-field/custom-render-function.tsx",
+  },
+  // DatePicker demos
+  "date-picker-basic": {
+    loader: () => import("./date-picker/basic").then((m) => m.Basic),
+    file: "en/date-picker/basic.tsx",
+  },
+  "date-picker-controlled": {
+    loader: () => import("./date-picker/controlled").then((m) => m.Controlled),
+    file: "en/date-picker/controlled.tsx",
+  },
+  "date-picker-disabled": {
+    loader: () => import("./date-picker/disabled").then((m) => m.Disabled),
+    file: "en/date-picker/disabled.tsx",
+  },
+  "date-picker-format-options": {
+    loader: () => import("./date-picker/format-options-no-ssr").then((m) => m.FormatOptions),
+    file: "en/date-picker/format-options.tsx",
+  },
+  "date-picker-form-example": {
+    loader: () => import("./date-picker/form-example").then((m) => m.FormExample),
+    file: "en/date-picker/form-example.tsx",
+  },
+  "date-picker-with-custom-indicator": {
+    loader: () => import("./date-picker/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "en/date-picker/with-custom-indicator.tsx",
+  },
+  "date-picker-with-validation": {
+    loader: () => import("./date-picker/with-validation").then((m) => m.WithValidation),
+    file: "en/date-picker/with-validation.tsx",
+  },
+  "date-picker-international-calendar": {
+    loader: () =>
+      import("./date-picker/international-calendar").then((m) => m.InternationalCalendar),
+    file: "en/date-picker/international-calendar.tsx",
+  },
+  "date-picker-custom-render-function": {
+    loader: () =>
+      import("./date-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/date-picker/custom-render-function.tsx",
+  },
+  // DateRangePicker demos
+  "date-range-picker-basic": {
+    loader: () => import("./date-range-picker/basic").then((m) => m.Basic),
+    file: "en/date-range-picker/basic.tsx",
+  },
+  "date-range-picker-controlled": {
+    loader: () => import("./date-range-picker/controlled").then((m) => m.Controlled),
+    file: "en/date-range-picker/controlled.tsx",
+  },
+  "date-range-picker-disabled": {
+    loader: () => import("./date-range-picker/disabled").then((m) => m.Disabled),
+    file: "en/date-range-picker/disabled.tsx",
+  },
+  "date-range-picker-format-options": {
+    loader: () => import("./date-range-picker/format-options-no-ssr").then((m) => m.FormatOptions),
+    file: "en/date-range-picker/format-options.tsx",
+  },
+  "date-range-picker-form-example": {
+    loader: () => import("./date-range-picker/form-example").then((m) => m.FormExample),
+    file: "en/date-range-picker/form-example.tsx",
+  },
+  "date-range-picker-with-custom-indicator": {
+    loader: () =>
+      import("./date-range-picker/with-custom-indicator").then((m) => m.WithCustomIndicator),
+    file: "en/date-range-picker/with-custom-indicator.tsx",
+  },
+  "date-range-picker-with-validation": {
+    loader: () => import("./date-range-picker/with-validation").then((m) => m.WithValidation),
+    file: "en/date-range-picker/with-validation.tsx",
+  },
+  "date-range-picker-international-calendar": {
+    loader: () =>
+      import("./date-range-picker/international-calendar").then((m) => m.InternationalCalendar),
+    file: "en/date-range-picker/international-calendar.tsx",
+  },
+  "date-range-picker-custom-render-function": {
+    loader: () =>
+      import("./date-range-picker/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/date-range-picker/custom-render-function.tsx",
+  },
+  "date-range-picker-input-container": {
+    loader: () => import("./date-range-picker/input-container").then((m) => m.InputContainer),
+    file: "en/date-range-picker/input-container.tsx",
+  },
+  // InputOTP demos
+  "input-otp-basic": {
+    loader: () => import("./input-otp/basic").then((m) => m.Basic),
+    file: "en/input-otp/basic.tsx",
+  },
+  "input-otp-four-digits": {
+    loader: () => import("./input-otp/four-digits").then((m) => m.FourDigits),
+    file: "en/input-otp/four-digits.tsx",
+  },
+  "input-otp-disabled": {
+    loader: () => import("./input-otp/disabled").then((m) => m.Disabled),
+    file: "en/input-otp/disabled.tsx",
+  },
+  "input-otp-with-pattern": {
+    loader: () => import("./input-otp/with-pattern").then((m) => m.WithPattern),
+    file: "en/input-otp/with-pattern.tsx",
+  },
+  "input-otp-controlled": {
+    loader: () => import("./input-otp/controlled").then((m) => m.Controlled),
+    file: "en/input-otp/controlled.tsx",
+  },
+  "input-otp-with-validation": {
+    loader: () => import("./input-otp/with-validation").then((m) => m.WithValidation),
+    file: "en/input-otp/with-validation.tsx",
+  },
+  "input-otp-on-complete": {
+    loader: () => import("./input-otp/on-complete").then((m) => m.OnComplete),
+    file: "en/input-otp/on-complete.tsx",
+  },
+  "input-otp-form-example": {
+    loader: () => import("./input-otp/form-example").then((m) => m.FormExample),
+    file: "en/input-otp/form-example.tsx",
+  },
+  "input-otp-on-surface": {
+    loader: () => import("./input-otp/on-surface").then((m) => m.OnSurface),
+    file: "en/input-otp/on-surface.tsx",
+  },
+  "input-otp-variants": {
+    loader: () => import("./input-otp/variants").then((m) => m.Variants),
+    file: "en/input-otp/variants.tsx",
+  },
+  // InputGroup demos
+  "input-group-default": {
+    loader: () => import("./input-group/default").then((m) => m.Default),
+    file: "en/input-group/default.tsx",
+  },
+  "input-group-full-width": {
+    loader: () => import("./input-group/full-width").then((m) => m.FullWidth),
+    file: "en/input-group/full-width.tsx",
+  },
+  "input-group-with-prefix-icon": {
+    loader: () => import("./input-group/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "en/input-group/with-prefix-icon.tsx",
+  },
+  "input-group-with-suffix-icon": {
+    loader: () => import("./input-group/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "en/input-group/with-suffix-icon.tsx",
+  },
+  "input-group-with-prefix-and-suffix": {
+    loader: () => import("./input-group/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "en/input-group/with-prefix-and-suffix.tsx",
+  },
+  "input-group-with-text-prefix": {
+    loader: () => import("./input-group/with-text-prefix").then((m) => m.WithTextPrefix),
+    file: "en/input-group/with-text-prefix.tsx",
+  },
+  "input-group-with-text-suffix": {
+    loader: () => import("./input-group/with-text-suffix").then((m) => m.WithTextSuffix),
+    file: "en/input-group/with-text-suffix.tsx",
+  },
+  "input-group-with-icon-prefix-and-text-suffix": {
+    loader: () =>
+      import("./input-group/with-icon-prefix-and-text-suffix").then(
+        (m) => m.WithIconPrefixAndTextSuffix,
+      ),
+    file: "en/input-group/with-icon-prefix-and-text-suffix.tsx",
+  },
+  "input-group-with-copy-suffix": {
+    loader: () => import("./input-group/with-copy-suffix").then((m) => m.WithCopySuffix),
+    file: "en/input-group/with-copy-suffix.tsx",
+  },
+  "input-group-with-icon-prefix-and-copy-suffix": {
+    loader: () =>
+      import("./input-group/with-icon-prefix-and-copy-suffix").then(
+        (m) => m.WithIconPrefixAndCopySuffix,
+      ),
+    file: "en/input-group/with-icon-prefix-and-copy-suffix.tsx",
+  },
+  "input-group-password-with-toggle": {
+    loader: () => import("./input-group/password-with-toggle").then((m) => m.PasswordWithToggle),
+    file: "en/input-group/password-with-toggle.tsx",
+  },
+  "input-group-with-loading-suffix": {
+    loader: () => import("./input-group/with-loading-suffix").then((m) => m.WithLoadingSuffix),
+    file: "en/input-group/with-loading-suffix.tsx",
+  },
+  "input-group-with-keyboard-shortcut": {
+    loader: () =>
+      import("./input-group/with-keyboard-shortcut").then((m) => m.WithKeyboardShortcut),
+    file: "en/input-group/with-keyboard-shortcut.tsx",
+  },
+  "input-group-with-badge-suffix": {
+    loader: () => import("./input-group/with-badge-suffix").then((m) => m.WithBadgeSuffix),
+    file: "en/input-group/with-badge-suffix.tsx",
+  },
+  "input-group-required": {
+    loader: () => import("./input-group/required").then((m) => m.Required),
+    file: "en/input-group/required.tsx",
+  },
+  "input-group-invalid": {
+    loader: () => import("./input-group/invalid").then((m) => m.Invalid),
+    file: "en/input-group/invalid.tsx",
+  },
+  "input-group-disabled": {
+    loader: () => import("./input-group/disabled").then((m) => m.Disabled),
+    file: "en/input-group/disabled.tsx",
+  },
+  "input-group-on-surface": {
+    loader: () => import("./input-group/on-surface").then((m) => m.OnSurface),
+    file: "en/input-group/on-surface.tsx",
+  },
+  "input-group-with-textarea": {
+    loader: () => import("./input-group/with-textarea").then((m) => m.WithTextArea),
+    file: "en/input-group/with-textarea.tsx",
+  },
+  "input-group-variants": {
+    loader: () => import("./input-group/variants").then((m) => m.Variants),
+    file: "en/input-group/variants.tsx",
+  },
+  // Kbd demos
+  "kbd-basic": {
+    loader: () => import("./kbd/basic").then((m) => m.Basic),
+    file: "en/kbd/basic.tsx",
+  },
+  "kbd-navigation-keys": {
+    loader: () => import("./kbd/navigation").then((m) => m.NavigationKeys),
+    file: "en/kbd/navigation.tsx",
+  },
+  "kbd-inline-usage": {
+    loader: () => import("./kbd/inline").then((m) => m.InlineUsage),
+    file: "en/kbd/inline.tsx",
+  },
+  "kbd-instructional-text": {
+    loader: () => import("./kbd/instructional").then((m) => m.InstructionalText),
+    file: "en/kbd/instructional.tsx",
+  },
+  "kbd-special-keys": {
+    loader: () => import("./kbd/special").then((m) => m.SpecialKeys),
+    file: "en/kbd/special.tsx",
+  },
+  "kbd-variants": {
+    loader: () => import("./kbd/variants").then((m) => m.Variants),
+    file: "en/kbd/variants.tsx",
+  },
+  // Link demos
+  "link-basic": {
+    loader: () => import("./link/basic").then((m) => m.LinkBasic),
+    file: "en/link/basic.tsx",
+  },
+  "link-custom-icon": {
+    loader: () => import("./link/custom-icon").then((m) => m.LinkCustomIcon),
+    file: "en/link/custom-icon.tsx",
+  },
+  "link-icon-placement": {
+    loader: () => import("./link/icon-placement").then((m) => m.LinkIconPlacement),
+    file: "en/link/icon-placement.tsx",
+  },
+  "link-underline-and-offset": {
+    loader: () => import("./link/underline-and-offset").then((m) => m.LinkUnderlineAndOffset),
+    file: "en/link/underline-and-offset.tsx",
+  },
+  "link-custom-render-function": {
+    loader: () => import("./link/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/link/custom-render-function.tsx",
+  },
+  // RadioGroup demos
+  "radio-group-basic": {
+    loader: () => import("./radio-group/basic").then((m) => m.Basic),
+    file: "en/radio-group/basic.tsx",
+  },
+  "radio-group-controlled": {
+    loader: () => import("./radio-group/controlled").then((m) => m.Controlled),
+    file: "en/radio-group/controlled.tsx",
+  },
+  "radio-group-custom-indicator": {
+    loader: () => import("./radio-group/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/radio-group/custom-indicator.tsx",
+  },
+  "radio-group-delivery-and-payment": {
+    loader: () => import("./radio-group/delivery-and-payment").then((m) => m.DeliveryAndPayment),
+    file: "en/radio-group/delivery-and-payment.tsx",
+  },
+  "radio-group-disabled": {
+    loader: () => import("./radio-group/disabled").then((m) => m.Disabled),
+    file: "en/radio-group/disabled.tsx",
+  },
+  "radio-group-horizontal": {
+    loader: () => import("./radio-group/horizontal").then((m) => m.Horizontal),
+    file: "en/radio-group/horizontal.tsx",
+  },
+  "radio-group-uncontrolled": {
+    loader: () => import("./radio-group/uncontrolled").then((m) => m.Uncontrolled),
+    file: "en/radio-group/uncontrolled.tsx",
+  },
+  "radio-group-validation": {
+    loader: () => import("./radio-group/validation").then((m) => m.Validation),
+    file: "en/radio-group/validation.tsx",
+  },
+  "radio-group-on-surface": {
+    loader: () => import("./radio-group/on-surface").then((m) => m.OnSurface),
+    file: "en/radio-group/on-surface.tsx",
+  },
+  "radio-group-variants": {
+    loader: () => import("./radio-group/variants").then((m) => m.Variants),
+    file: "en/radio-group/variants.tsx",
+  },
+  "radio-group-custom-render-function": {
+    loader: () =>
+      import("./radio-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/radio-group/custom-render-function.tsx",
+  },
+  // Skeleton demos
+  "skeleton-basic": {
+    loader: () => import("./skeleton/basic").then((m) => m.Basic),
+    file: "en/skeleton/basic.tsx",
+  },
+  "skeleton-text-content": {
+    loader: () => import("./skeleton/text-content").then((m) => m.TextContent),
+    file: "en/skeleton/text-content.tsx",
+  },
+  "skeleton-user-profile": {
+    loader: () => import("./skeleton/user-profile").then((m) => m.UserProfile),
+    file: "en/skeleton/user-profile.tsx",
+  },
+  "skeleton-list": {
+    loader: () => import("./skeleton/list").then((m) => m.List),
+    file: "en/skeleton/list.tsx",
+  },
+  "skeleton-animation-types": {
+    loader: () => import("./skeleton/animation-types").then((m) => m.AnimationTypes),
+    file: "en/skeleton/animation-types.tsx",
+  },
+  "skeleton-grid": {
+    loader: () => import("./skeleton/grid").then((m) => m.Grid),
+    file: "en/skeleton/grid.tsx",
+  },
+  "skeleton-single-shimmer": {
+    loader: () => import("./skeleton/single-shimmer").then((m) => m.SingleShimmer),
+    file: "en/skeleton/single-shimmer.tsx",
+  },
+  // Separator demos
+  "separator-basic": {
+    loader: () => import("./separator/basic").then((m) => m.Basic),
+    file: "en/separator/basic.tsx",
+  },
+  "separator-vertical": {
+    loader: () => import("./separator/vertical").then((m) => m.Vertical),
+    file: "en/separator/vertical.tsx",
+  },
+  "separator-with-content": {
+    loader: () => import("./separator/with-content").then((m) => m.WithContent),
+    file: "en/separator/with-content.tsx",
+  },
+  "separator-variants": {
+    loader: () => import("./separator/variants").then((m) => m.Variants),
+    file: "en/separator/variants.tsx",
+  },
+  "separator-with-surface": {
+    loader: () => import("./separator/with-surface").then((m) => m.WithSurface),
+    file: "en/separator/with-surface.tsx",
+  },
+  "separator-manual-variant-override": {
+    loader: () =>
+      import("./separator/manual-variant-override").then((m) => m.ManualVariantOverride),
+    file: "en/separator/manual-variant-override.tsx",
+  },
+  "separator-custom-render-function": {
+    loader: () => import("./separator/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/separator/custom-render-function.tsx",
+  },
+  // Spinner demos
+  "spinner-basic": {
+    loader: () => import("./spinner/basic").then((m) => m.SpinnerBasic),
+    file: "en/spinner/basic.tsx",
+  },
+  "spinner-colors": {
+    loader: () => import("./spinner/colors").then((m) => m.SpinnerColors),
+    file: "en/spinner/colors.tsx",
+  },
+  "spinner-sizes": {
+    loader: () => import("./spinner/sizes").then((m) => m.SpinnerSizes),
+    file: "en/spinner/sizes.tsx",
+  },
+  // Surface demos
+  "surface-variants": {
+    loader: () => import("./surface/variants").then((m) => m.Variants),
+    file: "en/surface/variants.tsx",
+  },
+  // Switch demos
+  "switch-basic": {
+    loader: () => import("./switch/basic").then((m) => m.Basic),
+    file: "en/switch/basic.tsx",
+  },
+  "switch-disabled": {
+    loader: () => import("./switch/disabled").then((m) => m.Disabled),
+    file: "en/switch/disabled.tsx",
+  },
+  "switch-default-selected": {
+    loader: () => import("./switch/default-selected").then((m) => m.DefaultSelected),
+    file: "en/switch/default-selected.tsx",
+  },
+  "switch-controlled": {
+    loader: () => import("./switch/controlled").then((m) => m.Controlled),
+    file: "en/switch/controlled.tsx",
+  },
+  "switch-without-label": {
+    loader: () => import("./switch/without-label").then((m) => m.WithoutLabel),
+    file: "en/switch/without-label.tsx",
+  },
+  "switch-sizes": {
+    loader: () => import("./switch/sizes").then((m) => m.Sizes),
+    file: "en/switch/sizes.tsx",
+  },
+  "switch-label-position": {
+    loader: () => import("./switch/label-position").then((m) => m.LabelPosition),
+    file: "en/switch/label-position.tsx",
+  },
+  "switch-with-icons": {
+    loader: () => import("./switch/with-icons").then((m) => m.WithIcons),
+    file: "en/switch/with-icons.tsx",
+  },
+  "switch-with-description": {
+    loader: () => import("./switch/with-description").then((m) => m.WithDescription),
+    file: "en/switch/with-description.tsx",
+  },
+  "switch-group": {
+    loader: () => import("./switch/group").then((m) => m.Group),
+    file: "en/switch/group.tsx",
+  },
+  "switch-group-horizontal": {
+    loader: () => import("./switch/group-horizontal").then((m) => m.GroupHorizontal),
+    file: "en/switch/group-horizontal.tsx",
+  },
+  "switch-render-props": {
+    loader: () => import("./switch/render-props").then((m) => m.RenderProps),
+    file: "en/switch/render-props.tsx",
+  },
+  "switch-form": {
+    loader: () => import("./switch/form").then((m) => m.Form),
+    file: "en/switch/form.tsx",
+  },
+  "switch-custom-styles": {
+    loader: () => import("./switch/custom-styles").then((m) => m.CustomStyles),
+    file: "en/switch/custom-styles.tsx",
+  },
+  "switch-custom-render-function": {
+    loader: () => import("./switch/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/switch/custom-render-function.tsx",
+  },
+  // Tabs demos
+  "tabs-basic": {
+    loader: () => import("./tabs/basic").then((m) => m.Basic),
+    file: "en/tabs/basic.tsx",
+  },
+  "tabs-vertical": {
+    loader: () => import("./tabs/vertical").then((m) => m.Vertical),
+    file: "en/tabs/vertical.tsx",
+  },
+  "tabs-overflow": {
+    loader: () => import("./tabs/overflow").then((m) => m.Overflow),
+    file: "en/tabs/overflow.tsx",
+  },
+  "tabs-disabled": {
+    loader: () => import("./tabs/disabled").then((m) => m.Disabled),
+    file: "en/tabs/disabled.tsx",
+  },
+  "tabs-custom-styles": {
+    loader: () => import("./tabs/custom-styles").then((m) => m.CustomStyles),
+    file: "en/tabs/custom-styles.tsx",
+  },
+  "tabs-with-separator": {
+    loader: () => import("./tabs/with-separator").then((m) => m.WithSeparator),
+    file: "en/tabs/with-separator.tsx",
+  },
+  "tabs-secondary": {
+    loader: () => import("./tabs/secondary").then((m) => m.Secondary),
+    file: "en/tabs/secondary.tsx",
+  },
+  "tabs-secondary-vertical": {
+    loader: () => import("./tabs/secondary-vertical").then((m) => m.SecondaryVertical),
+    file: "en/tabs/secondary-vertical.tsx",
+  },
+  "tabs-custom-render-function": {
+    loader: () => import("./tabs/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/tabs/custom-render-function.tsx",
+  },
+  // TagGroup demos
+  "tag-group-basic": {
+    loader: () => import("./tag-group/basic").then((m) => m.TagGroupBasic),
+    file: "en/tag-group/basic.tsx",
+  },
+  "tag-group-sizes": {
+    loader: () => import("./tag-group/sizes").then((m) => m.TagGroupSizes),
+    file: "en/tag-group/sizes.tsx",
+  },
+  "tag-group-variants": {
+    loader: () => import("./tag-group/variants").then((m) => m.TagGroupVariants),
+    file: "en/tag-group/variants.tsx",
+  },
+  "tag-group-disabled": {
+    loader: () => import("./tag-group/disabled").then((m) => m.TagGroupDisabled),
+    file: "en/tag-group/disabled.tsx",
+  },
+  "tag-group-selection-modes": {
+    loader: () => import("./tag-group/selection-modes").then((m) => m.TagGroupSelectionModes),
+    file: "en/tag-group/selection-modes.tsx",
+  },
+  "tag-group-controlled": {
+    loader: () => import("./tag-group/controlled").then((m) => m.TagGroupControlled),
+    file: "en/tag-group/controlled.tsx",
+  },
+  "tag-group-with-error-message": {
+    loader: () => import("./tag-group/with-error-message").then((m) => m.TagGroupWithErrorMessage),
+    file: "en/tag-group/with-error-message.tsx",
+  },
+  "tag-group-with-prefix": {
+    loader: () => import("./tag-group/with-prefix").then((m) => m.TagGroupWithPrefix),
+    file: "en/tag-group/with-prefix.tsx",
+  },
+  "tag-group-with-remove-button": {
+    loader: () => import("./tag-group/with-remove-button").then((m) => m.TagGroupWithRemoveButton),
+    file: "en/tag-group/with-remove-button.tsx",
+  },
+  "tag-group-with-list-data": {
+    loader: () => import("./tag-group/with-list-data").then((m) => m.TagGroupWithListData),
+    file: "en/tag-group/with-list-data.tsx",
+  },
+  "tag-group-custom-render-function": {
+    loader: () => import("./tag-group/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/tag-group/custom-render-function.tsx",
+  },
+  // Table demos
+  "table-basic": {
+    loader: () => import("./table/basic").then((m) => m.Basic),
+    file: "en/table/basic.tsx",
+  },
+  "table-secondary-variant": {
+    loader: () => import("./table/secondary-variant").then((m) => m.SecondaryVariant),
+    file: "en/table/secondary-variant.tsx",
+  },
+  "table-sorting": {
+    loader: () => import("./table/sorting").then((m) => m.Sorting),
+    file: "en/table/sorting.tsx",
+  },
+  "table-selection": {
+    loader: () => import("./table/selection").then((m) => m.SelectionDemo),
+    file: "en/table/selection.tsx",
+  },
+  "table-custom-cells": {
+    loader: () => import("./table/custom-cells").then((m) => m.CustomCells),
+    file: "en/table/custom-cells.tsx",
+  },
+  "table-expandable-rows": {
+    loader: () => import("./table/expandable-rows").then((m) => m.ExpandableRows),
+    file: "en/table/expandable-rows.tsx",
+  },
+  "table-pagination": {
+    loader: () => import("./table/pagination").then((m) => m.PaginationDemo),
+    file: "en/table/pagination.tsx",
+  },
+  "table-column-resizing": {
+    loader: () => import("./table/column-resizing").then((m) => m.ColumnResizing),
+    file: "en/table/column-resizing.tsx",
+  },
+  "table-empty-state": {
+    loader: () => import("./table/empty-state").then((m) => m.EmptyStateDemo),
+    file: "en/table/empty-state.tsx",
+  },
+  "table-async-loading": {
+    loader: () => import("./table/async-loading").then((m) => m.AsyncLoading),
+    file: "en/table/async-loading.tsx",
+  },
+  "table-virtualization": {
+    loader: () => import("./table/virtualization").then((m) => m.Virtualization),
+    file: "en/table/virtualization.tsx",
+  },
+  "table-tanstack-table": {
+    loader: () => import("./table/tanstack-table").then((m) => m.TanstackTable),
+    file: "en/table/tanstack-table.tsx",
+  },
+  // TextArea demos
+  "textarea-basic": {
+    loader: () => import("./textarea/basic").then((m) => m.Basic),
+    file: "en/textarea/basic.tsx",
+  },
+  "textarea-full-width": {
+    loader: () => import("./textarea/full-width").then((m) => m.FullWidth),
+    file: "en/textarea/full-width.tsx",
+  },
+  "textarea-rows": {
+    loader: () => import("./textarea/rows").then((m) => m.Rows),
+    file: "en/textarea/rows.tsx",
+  },
+  "textarea-controlled": {
+    loader: () => import("./textarea/controlled").then((m) => m.Controlled),
+    file: "en/textarea/controlled.tsx",
+  },
+  "textarea-on-surface": {
+    loader: () => import("./textarea/on-surface").then((m) => m.OnSurface),
+    file: "en/textarea/on-surface.tsx",
+  },
+  "textarea-variants": {
+    loader: () => import("./textarea/variants").then((m) => m.Variants),
+    file: "en/textarea/variants.tsx",
+  },
+  // Typography demos
+  "typography-default": {
+    loader: () => import("./typography/default").then((m) => m.Default),
+    file: "en/typography/default.tsx",
+  },
+  "typography-primitives": {
+    loader: () => import("./typography/primitives").then((m) => m.Primitives),
+    file: "en/typography/primitives.tsx",
+  },
+  "typography-prose": {
+    loader: () => import("./typography/prose").then((m) => m.Prose),
+    file: "en/typography/prose.tsx",
+  },
+  "typography-render-props": {
+    loader: () => import("./typography/render-props").then((m) => m.RenderProps),
+    file: "en/typography/render-props.tsx",
+  },
+  "typography-typography-scale": {
+    loader: () => import("./typography/typography-scale").then((m) => m.TypographyScale),
+    file: "en/typography/typography-scale.tsx",
+  },
+  // TextField demos
+  "textfield-basic": {
+    loader: () => import("./textfield/basic").then((m) => m.Basic),
+    file: "en/textfield/basic.tsx",
+  },
+  "textfield-with-description": {
+    loader: () => import("./textfield/with-description").then((m) => m.WithDescription),
+    file: "en/textfield/with-description.tsx",
+  },
+  "textfield-required": {
+    loader: () => import("./textfield/required").then((m) => m.Required),
+    file: "en/textfield/required.tsx",
+  },
+  "textfield-with-error": {
+    loader: () => import("./textfield/with-error").then((m) => m.WithError),
+    file: "en/textfield/with-error.tsx",
+  },
+  "textfield-disabled": {
+    loader: () => import("./textfield/disabled").then((m) => m.Disabled),
+    file: "en/textfield/disabled.tsx",
+  },
+  "textfield-textarea": {
+    loader: () => import("./textfield/textarea").then((m) => m.TextAreaExample),
+    file: "en/textfield/textarea.tsx",
+  },
+  "textfield-input-types": {
+    loader: () => import("./textfield/input-types").then((m) => m.InputTypes),
+    file: "en/textfield/input-types.tsx",
+  },
+  "textfield-full-width": {
+    loader: () => import("./textfield/full-width").then((m) => m.FullWidth),
+    file: "en/textfield/full-width.tsx",
+  },
+  "textfield-controlled": {
+    loader: () => import("./textfield/controlled").then((m) => m.Controlled),
+    file: "en/textfield/controlled.tsx",
+  },
+  "textfield-validation": {
+    loader: () => import("./textfield/validation").then((m) => m.Validation),
+    file: "en/textfield/validation.tsx",
+  },
+  "textfield-on-surface": {
+    loader: () => import("./textfield/on-surface").then((m) => m.OnSurface),
+    file: "en/textfield/on-surface.tsx",
+  },
+  "textfield-custom-render-function": {
+    loader: () => import("./textfield/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/textfield/custom-render-function.tsx",
+  },
+  // TimeField demos
+  "time-field-basic": {
+    loader: () => import("./time-field/basic").then((m) => m.Basic),
+    file: "en/time-field/basic.tsx",
+  },
+  "time-field-controlled": {
+    loader: () => import("./time-field/controlled").then((m) => m.Controlled),
+    file: "en/time-field/controlled.tsx",
+  },
+  "time-field-disabled": {
+    loader: () => import("./time-field/disabled").then((m) => m.Disabled),
+    file: "en/time-field/disabled.tsx",
+  },
+  "time-field-form-example": {
+    loader: () => import("./time-field/form-example").then((m) => m.FormExample),
+    file: "en/time-field/form-example.tsx",
+  },
+  "time-field-invalid": {
+    loader: () => import("./time-field/invalid").then((m) => m.Invalid),
+    file: "en/time-field/invalid.tsx",
+  },
+  "time-field-on-surface": {
+    loader: () => import("./time-field/on-surface").then((m) => m.OnSurface),
+    file: "en/time-field/on-surface.tsx",
+  },
+  "time-field-required": {
+    loader: () => import("./time-field/required").then((m) => m.Required),
+    file: "en/time-field/required.tsx",
+  },
+  "time-field-with-description": {
+    loader: () => import("./time-field/with-description").then((m) => m.WithDescription),
+    file: "en/time-field/with-description.tsx",
+  },
+  "time-field-with-prefix-and-suffix": {
+    loader: () => import("./time-field/with-prefix-and-suffix").then((m) => m.WithPrefixAndSuffix),
+    file: "en/time-field/with-prefix-and-suffix.tsx",
+  },
+  "time-field-with-prefix-icon": {
+    loader: () => import("./time-field/with-prefix-icon").then((m) => m.WithPrefixIcon),
+    file: "en/time-field/with-prefix-icon.tsx",
+  },
+  "time-field-with-suffix-icon": {
+    loader: () => import("./time-field/with-suffix-icon").then((m) => m.WithSuffixIcon),
+    file: "en/time-field/with-suffix-icon.tsx",
+  },
+  "time-field-full-width": {
+    loader: () => import("./time-field/full-width").then((m) => m.FullWidth),
+    file: "en/time-field/full-width.tsx",
+  },
+  "time-field-with-validation": {
+    loader: () => import("./time-field/with-validation").then((m) => m.WithValidation),
+    file: "en/time-field/with-validation.tsx",
+  },
+  "time-field-custom-render-function": {
+    loader: () => import("./time-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/time-field/custom-render-function.tsx",
+  },
+  // Toast demos
+  "toast-default": {
+    loader: () => import("./toast/default").then((m) => m.Default),
+    file: "en/toast/default.tsx",
+  },
+  "toast-simple": {
+    loader: () => import("./toast/simple").then((m) => m.Simple),
+    file: "en/toast/simple.tsx",
+  },
+  "toast-variants": {
+    loader: () => import("./toast/variants").then((m) => m.Variants),
+    file: "en/toast/variants.tsx",
+  },
+  "toast-custom-indicator": {
+    loader: () => import("./toast/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/toast/custom-indicator.tsx",
+  },
+  "toast-promise": {
+    loader: () => import("./toast/promise").then((m) => m.PromiseDemo),
+    file: "en/toast/promise.tsx",
+  },
+  "toast-callbacks": {
+    loader: () => import("./toast/callbacks").then((m) => m.Callbacks),
+    file: "en/toast/callbacks.tsx",
+  },
+  "toast-placements": {
+    loader: () => import("./toast/placements").then((m) => m.Placements),
+    file: "en/toast/placements.tsx",
+  },
+  "toast-custom-toast": {
+    loader: () => import("./toast/custom-toast").then((m) => m.CustomToast),
+    file: "en/toast/custom-toast.tsx",
+  },
+  "toast-custom-queue": {
+    loader: () => import("./toast/custom-queue").then((m) => m.CustomQueue),
+    file: "en/toast/custom-queue.tsx",
+  },
+  // ToggleButton demos
+  "toggle-button-basic": {
+    loader: () => import("./toggle-button/basic").then((m) => m.Basic),
+    file: "en/toggle-button/basic.tsx",
+  },
+  "toggle-button-variants": {
+    loader: () => import("./toggle-button/variants").then((m) => m.Variants),
+    file: "en/toggle-button/variants.tsx",
+  },
+  "toggle-button-sizes": {
+    loader: () => import("./toggle-button/sizes").then((m) => m.Sizes),
+    file: "en/toggle-button/sizes.tsx",
+  },
+  "toggle-button-icon-only": {
+    loader: () => import("./toggle-button/icon-only").then((m) => m.IconOnly),
+    file: "en/toggle-button/icon-only.tsx",
+  },
+  "toggle-button-controlled": {
+    loader: () => import("./toggle-button/controlled").then((m) => m.Controlled),
+    file: "en/toggle-button/controlled.tsx",
+  },
+  "toggle-button-disabled": {
+    loader: () => import("./toggle-button/disabled").then((m) => m.Disabled),
+    file: "en/toggle-button/disabled.tsx",
+  },
+  // ToggleButtonGroup demos
+  "toggle-button-group-basic": {
+    loader: () => import("./toggle-button-group/basic").then((m) => m.Basic),
+    file: "en/toggle-button-group/basic.tsx",
+  },
+  "toggle-button-group-sizes": {
+    loader: () => import("./toggle-button-group/sizes").then((m) => m.Sizes),
+    file: "en/toggle-button-group/sizes.tsx",
+  },
+  "toggle-button-group-orientation": {
+    loader: () => import("./toggle-button-group/orientation").then((m) => m.Orientation),
+    file: "en/toggle-button-group/orientation.tsx",
+  },
+  "toggle-button-group-attached": {
+    loader: () => import("./toggle-button-group/attached").then((m) => m.Attached),
+    file: "en/toggle-button-group/attached.tsx",
+  },
+  "toggle-button-group-full-width": {
+    loader: () => import("./toggle-button-group/full-width").then((m) => m.FullWidth),
+    file: "en/toggle-button-group/full-width.tsx",
+  },
+  "toggle-button-group-selection-mode": {
+    loader: () => import("./toggle-button-group/selection-mode").then((m) => m.SelectionMode),
+    file: "en/toggle-button-group/selection-mode.tsx",
+  },
+  "toggle-button-group-controlled": {
+    loader: () => import("./toggle-button-group/controlled").then((m) => m.Controlled),
+    file: "en/toggle-button-group/controlled.tsx",
+  },
+  "toggle-button-group-disabled": {
+    loader: () => import("./toggle-button-group/disabled").then((m) => m.Disabled),
+    file: "en/toggle-button-group/disabled.tsx",
+  },
+  "toggle-button-group-without-separator": {
+    loader: () => import("./toggle-button-group/without-separator").then((m) => m.WithoutSeparator),
+    file: "en/toggle-button-group/without-separator.tsx",
+  },
+  // Toolbar demos
+  "toolbar-basic": {
+    loader: () => import("./toolbar/basic").then((m) => m.Basic),
+    file: "en/toolbar/basic.tsx",
+  },
+  "toolbar-vertical": {
+    loader: () => import("./toolbar/vertical").then((m) => m.Vertical),
+    file: "en/toolbar/vertical.tsx",
+  },
+  "toolbar-with-button-group": {
+    loader: () => import("./toolbar/with-button-group").then((m) => m.WithButtonGroup),
+    file: "en/toolbar/with-button-group.tsx",
+  },
+  "toolbar-attached": {
+    loader: () => import("./toolbar/custom-styles").then((m) => m.Attached),
+    file: "en/toolbar/custom-styles.tsx",
+  },
+  // Tooltip demos
+  "tooltip-basic": {
+    loader: () => import("./tooltip/basic").then((m) => m.TooltipBasic),
+    file: "en/tooltip/basic.tsx",
+  },
+  "tooltip-with-arrow": {
+    loader: () => import("./tooltip/with-arrow").then((m) => m.TooltipWithArrow),
+    file: "en/tooltip/with-arrow.tsx",
+  },
+  "tooltip-placement": {
+    loader: () => import("./tooltip/placement").then((m) => m.TooltipPlacement),
+    file: "en/tooltip/placement.tsx",
+  },
+  "tooltip-custom-trigger": {
+    loader: () => import("./tooltip/custom-trigger").then((m) => m.TooltipCustomTrigger),
+    file: "en/tooltip/custom-trigger.tsx",
+  },
+  "tooltip-custom-render-function": {
+    loader: () => import("./tooltip/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/tooltip/custom-render-function.tsx",
+  },
+  // Popover demos
+  "popover-basic": {
+    loader: () => import("./popover/basic").then((m) => m.PopoverBasic),
+    file: "en/popover/basic.tsx",
+  },
+  "popover-with-arrow": {
+    loader: () => import("./popover/with-arrow").then((m) => m.PopoverWithArrow),
+    file: "en/popover/with-arrow.tsx",
+  },
+  "popover-placement": {
+    loader: () => import("./popover/placement").then((m) => m.PopoverPlacement),
+    file: "en/popover/placement.tsx",
+  },
+  "popover-interactive": {
+    loader: () => import("./popover/interactive").then((m) => m.PopoverInteractive),
+    file: "en/popover/interactive.tsx",
+  },
+  "popover-custom-render-function": {
+    loader: () => import("./popover/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/popover/custom-render-function.tsx",
+  },
+  // Label demos
+  "label-basic": {
+    loader: () => import("./label/basic").then((m) => m.Basic),
+    file: "en/label/basic.tsx",
+  },
+  // ListBox demos
+  "list-box-controlled": {
+    loader: () => import("./list-box/controlled").then((m) => m.Controlled),
+    file: "en/list-box/controlled.tsx",
+  },
+  "list-box-custom-check-icon": {
+    loader: () => import("./list-box/custom-check-icon").then((m) => m.CustomCheckIcon),
+    file: "en/list-box/custom-check-icon.tsx",
+  },
+  "list-box-default": {
+    loader: () => import("./list-box/default").then((m) => m.Default),
+    file: "en/list-box/default.tsx",
+  },
+  "list-box-multi-select": {
+    loader: () => import("./list-box/multi-select").then((m) => m.MultiSelect),
+    file: "en/list-box/multi-select.tsx",
+  },
+  "list-box-scrollbar-modes": {
+    loader: () => import("./list-box/scrollbar-modes").then((m) => m.ScrollbarModes),
+    file: "en/list-box/scrollbar-modes.tsx",
+  },
+  "list-box-with-disabled-items": {
+    loader: () => import("./list-box/with-disabled-items").then((m) => m.WithDisabledItems),
+    file: "en/list-box/with-disabled-items.tsx",
+  },
+  "list-box-with-sections": {
+    loader: () => import("./list-box/with-sections").then((m) => m.WithSections),
+    file: "en/list-box/with-sections.tsx",
+  },
+  "list-box-custom-render-function": {
+    loader: () => import("./list-box/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/list-box/custom-render-function.tsx",
+  },
+  "list-box-virtualization": {
+    loader: () => import("./list-box/virtualization").then((m) => m.Virtualization),
+    file: "en/list-box/virtualization.tsx",
+  },
+  // Meter demos
+  "meter-basic": {
+    loader: () => import("./meter/basic").then((m) => m.Basic),
+    file: "en/meter/basic.tsx",
+  },
+  "meter-sizes": {
+    loader: () => import("./meter/sizes").then((m) => m.Sizes),
+    file: "en/meter/sizes.tsx",
+  },
+  "meter-colors": {
+    loader: () => import("./meter/colors").then((m) => m.Colors),
+    file: "en/meter/colors.tsx",
+  },
+  "meter-custom-value": {
+    loader: () => import("./meter/custom-value").then((m) => m.CustomValue),
+    file: "en/meter/custom-value.tsx",
+  },
+  "meter-without-label": {
+    loader: () => import("./meter/without-label").then((m) => m.WithoutLabel),
+    file: "en/meter/without-label.tsx",
+  },
+  // ProgressBar demos
+  "progress-bar-basic": {
+    loader: () => import("./progress-bar/basic").then((m) => m.Basic),
+    file: "en/progress-bar/basic.tsx",
+  },
+  "progress-bar-sizes": {
+    loader: () => import("./progress-bar/sizes").then((m) => m.Sizes),
+    file: "en/progress-bar/sizes.tsx",
+  },
+  "progress-bar-colors": {
+    loader: () => import("./progress-bar/colors").then((m) => m.Colors),
+    file: "en/progress-bar/colors.tsx",
+  },
+  "progress-bar-indeterminate": {
+    loader: () => import("./progress-bar/indeterminate").then((m) => m.Indeterminate),
+    file: "en/progress-bar/indeterminate.tsx",
+  },
+  "progress-bar-custom-value": {
+    loader: () => import("./progress-bar/custom-value").then((m) => m.CustomValue),
+    file: "en/progress-bar/custom-value.tsx",
+  },
+  "progress-bar-without-label": {
+    loader: () => import("./progress-bar/without-label").then((m) => m.WithoutLabel),
+    file: "en/progress-bar/without-label.tsx",
+  },
+  // ProgressCircle demos
+  "progress-circle-basic": {
+    loader: () => import("./progress-circle/basic").then((m) => m.Basic),
+    file: "en/progress-circle/basic.tsx",
+  },
+  "progress-circle-sizes": {
+    loader: () => import("./progress-circle/sizes").then((m) => m.Sizes),
+    file: "en/progress-circle/sizes.tsx",
+  },
+  "progress-circle-colors": {
+    loader: () => import("./progress-circle/colors").then((m) => m.Colors),
+    file: "en/progress-circle/colors.tsx",
+  },
+  "progress-circle-indeterminate": {
+    loader: () => import("./progress-circle/indeterminate").then((m) => m.Indeterminate),
+    file: "en/progress-circle/indeterminate.tsx",
+  },
+  "progress-circle-with-label": {
+    loader: () => import("./progress-circle/with-label").then((m) => m.WithLabel),
+    file: "en/progress-circle/with-label.tsx",
+  },
+  "progress-circle-custom-svg": {
+    loader: () => import("./progress-circle/custom-svg").then((m) => m.CustomSvg),
+    file: "en/progress-circle/custom-svg.tsx",
+  },
+  // Modal demos
+  "modal-default": {
+    loader: () => import("./modal/default").then((m) => m.Default),
+    file: "en/modal/default.tsx",
+  },
+  "modal-placements": {
+    loader: () => import("./modal/placements").then((m) => m.Placements),
+    file: "en/modal/placements.tsx",
+  },
+  "modal-backdrop-variants": {
+    loader: () => import("./modal/backdrop-variants").then((m) => m.BackdropVariants),
+    file: "en/modal/backdrop-variants.tsx",
+  },
+  "modal-scroll-comparison": {
+    loader: () => import("./modal/scroll-comparison").then((m) => m.ScrollComparison),
+    file: "en/modal/scroll-comparison.tsx",
+  },
+  "modal-dismiss-behavior": {
+    loader: () => import("./modal/dismiss-behavior").then((m) => m.DismissBehavior),
+    file: "en/modal/dismiss-behavior.tsx",
+  },
+  "modal-with-form": {
+    loader: () => import("./modal/with-form").then((m) => m.WithForm),
+    file: "en/modal/with-form.tsx",
+  },
+  "modal-controlled": {
+    loader: () => import("./modal/controlled").then((m) => m.Controlled),
+    file: "en/modal/controlled.tsx",
+  },
+  "modal-custom-trigger": {
+    loader: () => import("./modal/custom-trigger").then((m) => m.CustomTrigger),
+    file: "en/modal/custom-trigger.tsx",
+  },
+  "modal-custom-backdrop": {
+    loader: () => import("./modal/custom-backdrop").then((m) => m.CustomBackdrop),
+    file: "en/modal/custom-backdrop.tsx",
+  },
+  "modal-custom-animations": {
+    loader: () => import("./modal/custom-animations").then((m) => m.CustomAnimations),
+    file: "en/modal/custom-animations.tsx",
+  },
+  "modal-sizes": {
+    loader: () => import("./modal/sizes").then((m) => m.Sizes),
+    file: "en/modal/sizes.tsx",
+  },
+  "modal-close-methods": {
+    loader: () => import("./modal/close-methods").then((m) => m.CloseMethods),
+    file: "en/modal/close-methods.tsx",
+  },
+  "modal-custom-portal": {
+    loader: () => import("./modal/custom-portal").then((m) => m.CustomPortal),
+    file: "en/modal/custom-portal.tsx",
+  },
+  // NumberField demos
+  "number-field-basic": {
+    loader: () => import("./number-field/basic").then((m) => m.Basic),
+    file: "en/number-field/basic.tsx",
+  },
+  "number-field-with-description": {
+    loader: () => import("./number-field/with-description").then((m) => m.WithDescription),
+    file: "en/number-field/with-description.tsx",
+  },
+  "number-field-required": {
+    loader: () => import("./number-field/required").then((m) => m.Required),
+    file: "en/number-field/required.tsx",
+  },
+  "number-field-validation": {
+    loader: () => import("./number-field/validation").then((m) => m.Validation),
+    file: "en/number-field/validation.tsx",
+  },
+  "number-field-disabled": {
+    loader: () => import("./number-field/disabled").then((m) => m.Disabled),
+    file: "en/number-field/disabled.tsx",
+  },
+  "number-field-full-width": {
+    loader: () => import("./number-field/full-width").then((m) => m.FullWidth),
+    file: "en/number-field/full-width.tsx",
+  },
+  "number-field-controlled": {
+    loader: () => import("./number-field/controlled").then((m) => m.Controlled),
+    file: "en/number-field/controlled.tsx",
+  },
+  "number-field-with-validation": {
+    loader: () => import("./number-field/with-validation").then((m) => m.WithValidation),
+    file: "en/number-field/with-validation.tsx",
+  },
+  "number-field-with-step": {
+    loader: () => import("./number-field/with-step").then((m) => m.WithStep),
+    file: "en/number-field/with-step.tsx",
+  },
+  "number-field-with-format-options": {
+    loader: () => import("./number-field/with-format-options").then((m) => m.WithFormatOptions),
+    file: "en/number-field/with-format-options.tsx",
+  },
+  "number-field-custom-icons": {
+    loader: () => import("./number-field/custom-icons").then((m) => m.CustomIcons),
+    file: "en/number-field/custom-icons.tsx",
+  },
+  "number-field-on-surface": {
+    loader: () => import("./number-field/on-surface").then((m) => m.OnSurface),
+    file: "en/number-field/on-surface.tsx",
+  },
+  "number-field-with-chevrons": {
+    loader: () => import("./number-field/with-chevrons").then((m) => m.WithChevrons),
+    file: "en/number-field/with-chevrons.tsx",
+  },
+  "number-field-form-example": {
+    loader: () => import("./number-field/form-example").then((m) => m.FormExample),
+    file: "en/number-field/form-example.tsx",
+  },
+  "number-field-variants": {
+    loader: () => import("./number-field/variants").then((m) => m.Variants),
+    file: "en/number-field/variants.tsx",
+  },
+  "number-field-custom-render-function": {
+    loader: () =>
+      import("./number-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/number-field/custom-render-function.tsx",
+  },
+  // Pagination demos
+  "pagination-basic": {
+    loader: () => import("./pagination/basic").then((m) => m.PaginationBasic),
+    file: "en/pagination/basic.tsx",
+  },
+  "pagination-sizes": {
+    loader: () => import("./pagination/sizes").then((m) => m.PaginationSizes),
+    file: "en/pagination/sizes.tsx",
+  },
+  "pagination-with-ellipsis": {
+    loader: () => import("./pagination/with-ellipsis").then((m) => m.PaginationWithEllipsis),
+    file: "en/pagination/with-ellipsis.tsx",
+  },
+  "pagination-simple-prev-next": {
+    loader: () => import("./pagination/simple-prev-next").then((m) => m.PaginationSimplePrevNext),
+    file: "en/pagination/simple-prev-next.tsx",
+  },
+  "pagination-with-summary": {
+    loader: () => import("./pagination/with-summary").then((m) => m.PaginationWithSummary),
+    file: "en/pagination/with-summary.tsx",
+  },
+  "pagination-custom-icons": {
+    loader: () => import("./pagination/custom-icons").then((m) => m.PaginationCustomIcons),
+    file: "en/pagination/custom-icons.tsx",
+  },
+  "pagination-controlled": {
+    loader: () => import("./pagination/controlled").then((m) => m.PaginationControlled),
+    file: "en/pagination/controlled.tsx",
+  },
+  "pagination-disabled": {
+    loader: () => import("./pagination/disabled").then((m) => m.PaginationDisabled),
+    file: "en/pagination/disabled.tsx",
+  },
+  // Select demos
+  "select-default": {
+    loader: () => import("./select/default").then((m) => m.Default),
+    file: "en/select/default.tsx",
+  },
+  "select-with-description": {
+    loader: () => import("./select/with-description").then((m) => m.WithDescription),
+    file: "en/select/with-description.tsx",
+  },
+  "select-multiple-select": {
+    loader: () => import("./select/multiple-select").then((m) => m.MultipleSelect),
+    file: "en/select/multiple-select.tsx",
+  },
+  "select-with-sections": {
+    loader: () => import("./select/with-sections").then((m) => m.WithSections),
+    file: "en/select/with-sections.tsx",
+  },
+  "select-with-disabled-options": {
+    loader: () => import("./select/with-disabled-options").then((m) => m.WithDisabledOptions),
+    file: "en/select/with-disabled-options.tsx",
+  },
+  "select-custom-indicator": {
+    loader: () => import("./select/custom-indicator").then((m) => m.CustomIndicator),
+    file: "en/select/custom-indicator.tsx",
+  },
+  "select-required": {
+    loader: () => import("./select/required").then((m) => m.Required),
+    file: "en/select/required.tsx",
+  },
+  "select-full-width": {
+    loader: () => import("./select/full-width").then((m) => m.FullWidth),
+    file: "en/select/full-width.tsx",
+  },
+  "select-on-surface": {
+    loader: () => import("./select/on-surface").then((m) => m.OnSurface),
+    file: "en/select/on-surface.tsx",
+  },
+  "select-custom-value": {
+    loader: () => import("./select/custom-value").then((m) => m.CustomValue),
+    file: "en/select/custom-value.tsx",
+  },
+  "select-custom-value-multiple": {
+    loader: () => import("./select/custom-value-multiple").then((m) => m.CustomValueMultiple),
+    file: "en/select/custom-value-multiple.tsx",
+  },
+  "select-controlled": {
+    loader: () => import("./select/controlled").then((m) => m.Controlled),
+    file: "en/select/controlled.tsx",
+  },
+  "select-controlled-multiple": {
+    loader: () => import("./select/controlled-multiple").then((m) => m.ControlledMultiple),
+    file: "en/select/controlled-multiple.tsx",
+  },
+  "select-controlled-open-state": {
+    loader: () => import("./select/controlled-open-state").then((m) => m.ControlledOpenState),
+    file: "en/select/controlled-open-state.tsx",
+  },
+  "select-asynchronous-loading": {
+    loader: () => import("./select/asynchronous-loading").then((m) => m.AsynchronousLoading),
+    file: "en/select/asynchronous-loading.tsx",
+  },
+  "select-disabled": {
+    loader: () => import("./select/disabled").then((m) => m.Disabled),
+    file: "en/select/disabled.tsx",
+  },
+  "select-variants": {
+    loader: () => import("./select/variants").then((m) => m.Variants),
+    file: "en/select/variants.tsx",
+  },
+  "select-custom-render-function": {
+    loader: () => import("./select/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/select/custom-render-function.tsx",
+  },
+  // SearchField demos
+  "search-field-basic": {
+    loader: () => import("./search-field/basic").then((m) => m.Basic),
+    file: "en/search-field/basic.tsx",
+  },
+  "search-field-with-description": {
+    loader: () => import("./search-field/with-description").then((m) => m.WithDescription),
+    file: "en/search-field/with-description.tsx",
+  },
+  "search-field-required": {
+    loader: () => import("./search-field/required").then((m) => m.Required),
+    file: "en/search-field/required.tsx",
+  },
+  "search-field-validation": {
+    loader: () => import("./search-field/validation").then((m) => m.Validation),
+    file: "en/search-field/validation.tsx",
+  },
+  "search-field-disabled": {
+    loader: () => import("./search-field/disabled").then((m) => m.Disabled),
+    file: "en/search-field/disabled.tsx",
+  },
+  "search-field-full-width": {
+    loader: () => import("./search-field/full-width").then((m) => m.FullWidth),
+    file: "en/search-field/full-width.tsx",
+  },
+  "search-field-controlled": {
+    loader: () => import("./search-field/controlled").then((m) => m.Controlled),
+    file: "en/search-field/controlled.tsx",
+  },
+  "search-field-with-validation": {
+    loader: () => import("./search-field/with-validation").then((m) => m.WithValidation),
+    file: "en/search-field/with-validation.tsx",
+  },
+  "search-field-custom-icons": {
+    loader: () => import("./search-field/custom-icons").then((m) => m.CustomIcons),
+    file: "en/search-field/custom-icons.tsx",
+  },
+  "search-field-on-surface": {
+    loader: () => import("./search-field/on-surface").then((m) => m.OnSurface),
+    file: "en/search-field/on-surface.tsx",
+  },
+  "search-field-form-example": {
+    loader: () => import("./search-field/form-example").then((m) => m.FormExample),
+    file: "en/search-field/form-example.tsx",
+  },
+  "search-field-with-keyboard-shortcut": {
+    loader: () =>
+      import("./search-field/with-keyboard-shortcut").then((m) => m.WithKeyboardShortcut),
+    file: "en/search-field/with-keyboard-shortcut.tsx",
+  },
+  "search-field-variants": {
+    loader: () => import("./search-field/variants").then((m) => m.Variants),
+    file: "en/search-field/variants.tsx",
+  },
+  "search-field-custom-render-function": {
+    loader: () =>
+      import("./search-field/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/search-field/custom-render-function.tsx",
+  },
+  // ScrollShadow demos
+  "scroll-shadow-default": {
+    loader: () => import("./scroll-shadow/default").then((m) => m.default),
+    file: "en/scroll-shadow/default.tsx",
+  },
+  "scroll-shadow-orientation": {
+    loader: () => import("./scroll-shadow/orientation").then((m) => m.default),
+    file: "en/scroll-shadow/orientation.tsx",
+  },
+  "scroll-shadow-hide-scroll-bar": {
+    loader: () => import("./scroll-shadow/hide-scroll-bar").then((m) => m.default),
+    file: "en/scroll-shadow/hide-scroll-bar.tsx",
+  },
+  "scroll-shadow-custom-size": {
+    loader: () => import("./scroll-shadow/custom-size").then((m) => m.default),
+    file: "en/scroll-shadow/custom-size.tsx",
+  },
+  "scroll-shadow-visibility-change": {
+    loader: () => import("./scroll-shadow/visibility-change").then((m) => m.default),
+    file: "en/scroll-shadow/visibility-change.tsx",
+  },
+  "scroll-shadow-with-card": {
+    loader: () => import("./scroll-shadow/with-card").then((m) => m.default),
+    file: "en/scroll-shadow/with-card.tsx",
+  },
+  // Slider demos
+  "slider-default": {
+    loader: () => import("./slider/default").then((m) => m.Default),
+    file: "en/slider/default.tsx",
+  },
+  "slider-vertical": {
+    loader: () => import("./slider/vertical").then((m) => m.Vertical),
+    file: "en/slider/vertical.tsx",
+  },
+  "slider-range": {
+    loader: () => import("./slider/range").then((m) => m.Range),
+    file: "en/slider/range.tsx",
+  },
+  "slider-disabled": {
+    loader: () => import("./slider/disabled").then((m) => m.Disabled),
+    file: "en/slider/disabled.tsx",
+  },
+  "slider-custom-render-function": {
+    loader: () => import("./slider/custom-render-function").then((m) => m.CustomRenderFunction),
+    file: "en/slider/custom-render-function.tsx",
+  },
+  // Description demos
+  "description-basic": {
+    loader: () => import("./description/basic").then((m) => m.Basic),
+    file: "en/description/basic.tsx",
+  },
+  // FieldError demos
+  "field-error-basic": {
+    loader: () => import("./field-error/basic").then((m) => m.Basic),
+    file: "en/field-error/basic.tsx",
+  },
+};
diff --git a/apps/docs/src/demos/en/input-group/default.tsx b/apps/docs/src/demos/en/input-group/default.tsx
new file mode 100644
index 0000000..89e0476
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/default.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Default() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/disabled.tsx b/apps/docs/src/demos/en/input-group/disabled.tsx
new file mode 100644
index 0000000..2cdb0c5
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/disabled.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField
+        isDisabled
+        className="w-full max-w-[280px]"
+        defaultValue="name@email.com"
+        name="email"
+      >
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" />
+        </InputGroup>
+      </TextField>
+      <TextField isDisabled className="w-full max-w-[280px]" defaultValue="10" name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/full-width.tsx b/apps/docs/src/demos/en/input-group/full-width.tsx
new file mode 100644
index 0000000..1b7c6fe
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/full-width.tsx
@@ -0,0 +1,27 @@
+import {Envelope, Eye} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="email">
+        <Label>Email address</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField fullWidth name="password">
+        <Label>Password</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Input placeholder="Enter password" type="password" />
+          <InputGroup.Suffix>
+            <Eye className="size-4 text-muted" />
+          </InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/index.ts b/apps/docs/src/demos/en/input-group/index.ts
new file mode 100644
index 0000000..a273f05
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/index.ts
@@ -0,0 +1,20 @@
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {PasswordWithToggle} from "./password-with-toggle";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithBadgeSuffix} from "./with-badge-suffix";
+export {WithCopySuffix} from "./with-copy-suffix";
+export {WithIconPrefixAndCopySuffix} from "./with-icon-prefix-and-copy-suffix";
+export {WithIconPrefixAndTextSuffix} from "./with-icon-prefix-and-text-suffix";
+export {WithKeyboardShortcut} from "./with-keyboard-shortcut";
+export {WithLoadingSuffix} from "./with-loading-suffix";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithTextPrefix} from "./with-text-prefix";
+export {WithTextSuffix} from "./with-text-suffix";
+export {WithTextArea} from "./with-textarea";
diff --git a/apps/docs/src/demos/en/input-group/invalid.tsx b/apps/docs/src/demos/en/input-group/invalid.tsx
new file mode 100644
index 0000000..5396ce6
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/invalid.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {FieldError, InputGroup, Label, TextField} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="email">
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+        <FieldError>Please enter a valid email address</FieldError>
+      </TextField>
+      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <FieldError>Price must be greater than 0</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/on-surface.tsx b/apps/docs/src/demos/en/input-group/on-surface.tsx
new file mode 100644
index 0000000..b8f904c
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/on-surface.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, Surface, TextField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="rounded-2xl p-6">
+      <TextField className="w-full max-w-[280px]" name="email">
+        <Label>Email address</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+        <Description>We'll never share this with anyone else</Description>
+      </TextField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/password-with-toggle.tsx b/apps/docs/src/demos/en/input-group/password-with-toggle.tsx
new file mode 100644
index 0000000..4ebdf76
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/password-with-toggle.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Eye, EyeSlash} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+import {useState} from "react";
+
+export function PasswordWithToggle() {
+  const [isVisible, setIsVisible] = useState(false);
+
+  return (
+    <TextField className="w-full max-w-[280px]" name="password">
+      <Label>Password</Label>
+      <InputGroup>
+        <InputGroup.Input
+          className="w-full max-w-[280px]"
+          type={isVisible ? "text" : "password"}
+          value={isVisible ? "87$2h.3diua" : "••••••••"}
+        />
+        <InputGroup.Suffix className="pr-0">
+          <Button
+            isIconOnly
+            aria-label={isVisible ? "Hide password" : "Show password"}
+            size="sm"
+            variant="ghost"
+            onPress={() => setIsVisible(!isVisible)}
+          >
+            {isVisible ? <Eye className="size-4" /> : <EyeSlash className="size-4" />}
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/required.tsx b/apps/docs/src/demos/en/input-group/required.tsx
new file mode 100644
index 0000000..f2a36a4
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/required.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField isRequired className="w-full max-w-[280px]" name="email">
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField isRequired className="w-full max-w-[280px]" name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <Description>What customers would pay</Description>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/variants.tsx b/apps/docs/src/demos/en/input-group/variants.tsx
new file mode 100644
index 0000000..6147e09
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/variants.tsx
@@ -0,0 +1,27 @@
+import {Envelope} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextField className="w-[280px]" name="primary">
+        <Label>Primary variant</Label>
+        <InputGroup variant="primary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField className="w-[280px]" name="secondary">
+        <Label>Secondary variant</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Envelope className="size-4 text-muted" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-badge-suffix.tsx b/apps/docs/src/demos/en/input-group/with-badge-suffix.tsx
new file mode 100644
index 0000000..051524d
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-badge-suffix.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Chip, InputGroup, TextField} from "@heroui/react";
+
+export function WithBadgeSuffix() {
+  return (
+    <TextField aria-label="Email address" className="w-full max-w-[280px]" name="email">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="Email address" />
+        <InputGroup.Suffix className="pr-2">
+          <Chip color="accent" size="md" variant="soft">
+            Pro
+          </Chip>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-copy-suffix.tsx b/apps/docs/src/demos/en/input-group/with-copy-suffix.tsx
new file mode 100644
index 0000000..13311b4
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-copy-suffix.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Copy} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithCopySuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
+            <Copy className="size-4" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-icon-prefix-and-copy-suffix.tsx b/apps/docs/src/demos/en/input-group/with-icon-prefix-and-copy-suffix.tsx
new file mode 100644
index 0000000..4e02091
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-icon-prefix-and-copy-suffix.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Copy, Globe} from "@gravity-ui/icons";
+import {Button, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithIconPrefixAndCopySuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Globe className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
+            <Copy className="size-4" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-icon-prefix-and-text-suffix.tsx b/apps/docs/src/demos/en/input-group/with-icon-prefix-and-text-suffix.tsx
new file mode 100644
index 0000000..29c204e
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-icon-prefix-and-text-suffix.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Globe} from "@gravity-ui/icons";
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithIconPrefixAndTextSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Globe className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-keyboard-shortcut.tsx b/apps/docs/src/demos/en/input-group/with-keyboard-shortcut.tsx
new file mode 100644
index 0000000..518660d
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-keyboard-shortcut.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {InputGroup, Kbd, TextField} from "@heroui/react";
+
+export function WithKeyboardShortcut() {
+  return (
+    <TextField aria-label="Command" className="w-full max-w-[280px]" name="command">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="Command" />
+        <InputGroup.Suffix className="pr-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="command" />
+            <Kbd.Content>K</Kbd.Content>
+          </Kbd>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-loading-suffix.tsx b/apps/docs/src/demos/en/input-group/with-loading-suffix.tsx
new file mode 100644
index 0000000..9459974
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-loading-suffix.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {InputGroup, Spinner, TextField} from "@heroui/react";
+
+export function WithLoadingSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="Sending..." name="status">
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>
+          <Spinner className="size-4" />
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-prefix-and-suffix.tsx b/apps/docs/src/demos/en/input-group/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..999cd5e
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-prefix-and-suffix.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="10" name="price">
+      <Label>Set a price</Label>
+      <InputGroup>
+        <InputGroup.Prefix>$</InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[200px]" type="number" />
+        <InputGroup.Suffix>USD</InputGroup.Suffix>
+      </InputGroup>
+      <Description>What customers would pay</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-prefix-icon.tsx b/apps/docs/src/demos/en/input-group/with-prefix-icon.tsx
new file mode 100644
index 0000000..62cdf49
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-prefix-icon.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+      <Description>We'll never share this with anyone else</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-suffix-icon.tsx b/apps/docs/src/demos/en/input-group/with-suffix-icon.tsx
new file mode 100644
index 0000000..047d048
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-suffix-icon.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Description, InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <TextField className="w-full max-w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
+        <InputGroup.Suffix>
+          <Envelope className="size-4 text-muted" />
+        </InputGroup.Suffix>
+      </InputGroup>
+      <Description>We don't send spam</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-text-prefix.tsx b/apps/docs/src/demos/en/input-group/with-text-prefix.tsx
new file mode 100644
index 0000000..daaf266
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-text-prefix.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithTextPrefix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>https://</InputGroup.Prefix>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-text-suffix.tsx b/apps/docs/src/demos/en/input-group/with-text-suffix.tsx
new file mode 100644
index 0000000..73c9782
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-text-suffix.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import {InputGroup, Label, TextField} from "@heroui/react";
+
+export function WithTextSuffix() {
+  return (
+    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-full max-w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-group/with-textarea.tsx b/apps/docs/src/demos/en/input-group/with-textarea.tsx
new file mode 100644
index 0000000..dd5d179
--- /dev/null
+++ b/apps/docs/src/demos/en/input-group/with-textarea.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons";
+import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react";
+import {useState} from "react";
+
+export function WithTextArea() {
+  const [value, setValue] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = () => {
+    if (!value.trim()) return;
+
+    setIsSubmitting(true);
+
+    setTimeout(() => {
+      setIsSubmitting(false);
+      setValue("");
+    }, 1000);
+  };
+
+  return (
+    <TextField
+      fullWidth
+      aria-label="Prompt input"
+      className="flex w-sm flex-col sm:w-lg"
+      name="prompt"
+    >
+      <InputGroup fullWidth className="flex flex-col gap-2 rounded-3xl py-2">
+        <InputGroup.Prefix className="px-3 py-0">
+          <Button aria-label="Add context" size="sm" variant="outline">
+            <At />
+            Add Context
+          </Button>
+        </InputGroup.Prefix>
+        <InputGroup.TextArea
+          className="w-full resize-none px-3.5 py-0"
+          placeholder="Assign tasks or ask anything..."
+          rows={5}
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+        />
+        <InputGroup.Suffix className="flex w-full items-center gap-1.5 px-3 py-0">
+          <Tooltip delay={0}>
+            <Button isIconOnly aria-label="Attach file" size="sm" variant="tertiary">
+              <Plus />
+            </Button>
+            <Tooltip.Content>
+              <p className="text-xs">Add a files and more</p>
+            </Tooltip.Content>
+          </Tooltip>
+          <Tooltip delay={0}>
+            <Button isIconOnly aria-label="Connect Apps" size="sm" variant="tertiary">
+              <PlugConnection />
+            </Button>
+            <Tooltip.Content>
+              <p className="text-xs">Connect apps</p>
+            </Tooltip.Content>
+          </Tooltip>
+          <div className="ml-auto flex items-center gap-1.5">
+            <Tooltip delay={0}>
+              <Button isIconOnly aria-label="Voice input" size="sm" variant="ghost">
+                <Microphone />
+              </Button>
+              <Tooltip.Content>
+                <p className="text-xs">Voice input</p>
+              </Tooltip.Content>
+            </Tooltip>
+            <Tooltip delay={0}>
+              <Button
+                isIconOnly
+                aria-label="Send prompt"
+                isDisabled={!value.trim()}
+                isPending={isSubmitting}
+                onPress={handleSubmit}
+              >
+                {({isPending}) => (isPending ? <Spinner color="current" size="sm" /> : <ArrowUp />)}
+              </Button>
+              <Tooltip.Content className="flex items-center gap-1">
+                <p className="text-xs">Send</p>
+                <Kbd className="h-4 rounded-sm px-1">
+                  <Kbd.Abbr keyValue="enter" />
+                </Kbd>
+              </Tooltip.Content>
+            </Tooltip>
+          </div>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/basic.tsx b/apps/docs/src/demos/en/input-otp/basic.tsx
new file mode 100644
index 0000000..4e3f59e
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/basic.tsx
@@ -0,0 +1,31 @@
+import {InputOTP, Label, Link} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <div className="flex flex-col gap-1">
+        <Label>Verify account</Label>
+        <p className="text-sm text-muted">We&apos;ve sent a code to a****@gmail.com</p>
+      </div>
+      <InputOTP maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <div className="flex items-center gap-[5px] px-1 pt-1">
+        <p className="text-sm text-muted">Didn&apos;t receive a code?</p>
+        <Link className="text-foreground underline" href="#">
+          Resend
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/controlled.tsx b/apps/docs/src/demos/en/input-otp/controlled.tsx
new file mode 100644
index 0000000..76df3d4
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/controlled.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import {Description, InputOTP, Label} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>Verify account</Label>
+      <InputOTP maxLength={6} value={value} onChange={setValue}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Description>
+        {value.length > 0 ? (
+          <>
+            Value: {value} ({value.length}/6) •{" "}
+            <button className="font-medium text-foreground underline" onClick={() => setValue("")}>
+              Clear
+            </button>
+          </>
+        ) : (
+          "Enter a 6-digit code"
+        )}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/disabled.tsx b/apps/docs/src/demos/en/input-otp/disabled.tsx
new file mode 100644
index 0000000..6ec780c
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/disabled.tsx
@@ -0,0 +1,23 @@
+import {Description, InputOTP, Label} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label isDisabled>Verify account</Label>
+      <Description>Code verification is currently disabled</Description>
+      <InputOTP isDisabled maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/form-example.tsx b/apps/docs/src/demos/en/input-otp/form-example.tsx
new file mode 100644
index 0000000..a9cfb60
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/form-example.tsx
@@ -0,0 +1,89 @@
+"use client";
+
+import {Button, Description, Form, InputOTP, Label, Link, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState("");
+  const [error, setError] = React.useState("");
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    setError("");
+
+    if (value.length !== 6) {
+      setError("Please enter all 6 digits");
+
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      if (value === "123456") {
+        console.log("Code verified successfully!");
+        setValue("");
+      } else {
+        setError("Invalid code. Please try again.");
+      }
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <div className="flex flex-col gap-2">
+        <Label>Two-factor authentication</Label>
+        <Description>Enter the 6-digit code from your authenticator app</Description>
+        <InputOTP
+          isInvalid={!!error}
+          maxLength={6}
+          value={value}
+          onChange={(val) => {
+            setValue(val);
+            setError("");
+          }}
+        >
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <span className="field-error" data-visible={!!error} id="code-error">
+          {error}
+        </span>
+      </div>
+      <Button
+        className="w-full"
+        isDisabled={value.length !== 6}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            Verifying...
+          </>
+        ) : (
+          "Verify"
+        )}
+      </Button>
+      <div className="flex items-center justify-center gap-1">
+        <p className="text-sm text-muted">Having trouble?</p>
+        <Link className="text-sm text-foreground underline" href="#">
+          Use backup code
+        </Link>
+      </div>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/four-digits.tsx b/apps/docs/src/demos/en/input-otp/four-digits.tsx
new file mode 100644
index 0000000..2c74fe1
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/four-digits.tsx
@@ -0,0 +1,17 @@
+import {InputOTP, Label} from "@heroui/react";
+
+export function FourDigits() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>Enter PIN</Label>
+      <InputOTP maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/index.ts b/apps/docs/src/demos/en/input-otp/index.ts
new file mode 100644
index 0000000..b38ddaf
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/index.ts
@@ -0,0 +1,10 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FourDigits} from "./four-digits";
+export {OnComplete} from "./on-complete";
+export {OnSurface} from "./on-surface";
+export {Variants} from "./variants";
+export {WithPattern} from "./with-pattern";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/en/input-otp/on-complete.tsx b/apps/docs/src/demos/en/input-otp/on-complete.tsx
new file mode 100644
index 0000000..36d7d95
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/on-complete.tsx
@@ -0,0 +1,71 @@
+"use client";
+
+import {Button, Form, InputOTP, Label, Spinner} from "@heroui/react";
+import React from "react";
+
+export function OnComplete() {
+  const [value, setValue] = React.useState("");
+  const [isComplete, setIsComplete] = React.useState(false);
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+  const handleComplete = (code: string) => {
+    setIsComplete(true);
+
+    console.log("Code complete:", code);
+  };
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+
+    setIsSubmitting(true);
+    // Simulate API call
+    setTimeout(() => {
+      setIsSubmitting(false);
+      setValue("");
+      setIsComplete(false);
+    }, 2000);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-2" onSubmit={handleSubmit}>
+      <Label>Verify account</Label>
+      <InputOTP
+        maxLength={6}
+        value={value}
+        onComplete={handleComplete}
+        onChange={(val) => {
+          setValue(val);
+          setIsComplete(false);
+        }}
+      >
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <Button
+        className="mt-2 w-full"
+        isDisabled={!isComplete}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            Verifying...
+          </>
+        ) : (
+          "Verify Code"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/on-surface.tsx b/apps/docs/src/demos/en/input-otp/on-surface.tsx
new file mode 100644
index 0000000..5292bd9
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/on-surface.tsx
@@ -0,0 +1,31 @@
+import {InputOTP, Label, Link, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full flex-col gap-2 rounded-3xl p-6">
+      <div className="flex flex-col gap-1">
+        <Label>Verify account</Label>
+        <p className="text-sm text-muted">We&apos;ve sent a code to a****@gmail.com</p>
+      </div>
+      <InputOTP maxLength={6} variant="secondary">
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <div className="flex items-center gap-[5px] px-1 pt-1">
+        <p className="text-sm text-muted">Didn&apos;t receive a code?</p>
+        <Link className="text-foreground underline" href="#">
+          Resend
+        </Link>
+      </div>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/variants.tsx b/apps/docs/src/demos/en/input-otp/variants.tsx
new file mode 100644
index 0000000..9b8c578
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/variants.tsx
@@ -0,0 +1,40 @@
+import {InputOTP, Label} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <Label>Primary variant</Label>
+        <InputOTP maxLength={6} variant="primary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label>Secondary variant</Label>
+        <InputOTP maxLength={6} variant="secondary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/with-pattern.tsx b/apps/docs/src/demos/en/input-otp/with-pattern.tsx
new file mode 100644
index 0000000..62b2ae7
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/with-pattern.tsx
@@ -0,0 +1,23 @@
+import {Description, InputOTP, Label, REGEXP_ONLY_CHARS} from "@heroui/react";
+
+export function WithPattern() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>Enter code (letters only)</Label>
+      <Description>Only alphabetic characters are allowed</Description>
+      <InputOTP maxLength={6} pattern={REGEXP_ONLY_CHARS}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input-otp/with-validation.tsx b/apps/docs/src/demos/en/input-otp/with-validation.tsx
new file mode 100644
index 0000000..068bc49
--- /dev/null
+++ b/apps/docs/src/demos/en/input-otp/with-validation.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {Button, Description, Form, InputOTP, Label} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState("");
+  const [isInvalid, setIsInvalid] = React.useState(false);
+
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const code = formData.get("code");
+
+    if (code !== "123456") {
+      setIsInvalid(true);
+
+      return;
+    }
+
+    setIsInvalid(false);
+    setValue("");
+
+    alert("Code verified successfully!");
+  };
+
+  const handleChange = (val: string) => {
+    setValue(val);
+    setIsInvalid(false);
+  };
+
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Form className="flex flex-col gap-2" onSubmit={onSubmit}>
+        <Label>Verify account</Label>
+        <Description>Hint: The code is 123456</Description>
+        <InputOTP
+          aria-describedby={isInvalid ? "code-error" : undefined}
+          isInvalid={isInvalid}
+          maxLength={6}
+          name="code"
+          value={value}
+          onChange={handleChange}
+        >
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <span className="field-error" data-visible={isInvalid} id="code-error">
+          Invalid code. Please try again.
+        </span>
+        <Button isDisabled={value.length !== 6} type="submit">
+          Submit
+        </Button>
+      </Form>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input/basic.tsx b/apps/docs/src/demos/en/input/basic.tsx
new file mode 100644
index 0000000..5afe2c5
--- /dev/null
+++ b/apps/docs/src/demos/en/input/basic.tsx
@@ -0,0 +1,5 @@
+import {Input} from "@heroui/react";
+
+export function Basic() {
+  return <Input aria-label="Name" className="w-64" placeholder="Enter your name" />;
+}
diff --git a/apps/docs/src/demos/en/input/controlled.tsx b/apps/docs/src/demos/en/input/controlled.tsx
new file mode 100644
index 0000000..69aa3db
--- /dev/null
+++ b/apps/docs/src/demos/en/input/controlled.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Input} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("heroui.com");
+
+  return (
+    <div className="flex w-80 flex-col gap-2">
+      <Input
+        aria-label="Domain"
+        placeholder="domain"
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+      <span className="px-1 text-sm text-muted">https://{value || "your-domain"}</span>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input/full-width.tsx b/apps/docs/src/demos/en/input/full-width.tsx
new file mode 100644
index 0000000..7595b5f
--- /dev/null
+++ b/apps/docs/src/demos/en/input/full-width.tsx
@@ -0,0 +1,9 @@
+import {Input} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <Input fullWidth placeholder="Full width input" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input/index.ts b/apps/docs/src/demos/en/input/index.ts
new file mode 100644
index 0000000..e9ddd94
--- /dev/null
+++ b/apps/docs/src/demos/en/input/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Types} from "./types";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/input/on-surface.tsx b/apps/docs/src/demos/en/input/on-surface.tsx
new file mode 100644
index 0000000..362e2bf
--- /dev/null
+++ b/apps/docs/src/demos/en/input/on-surface.tsx
@@ -0,0 +1,9 @@
+import {Input, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex h-[180px] w-[280px] items-center justify-center rounded-3xl bg-surface p-4">
+      <Input className="w-full" placeholder="Your name" variant="secondary" />
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/input/types.tsx b/apps/docs/src/demos/en/input/types.tsx
new file mode 100644
index 0000000..e59e14b
--- /dev/null
+++ b/apps/docs/src/demos/en/input/types.tsx
@@ -0,0 +1,20 @@
+import {Input, Label} from "@heroui/react";
+
+export function Types() {
+  return (
+    <div className="flex w-80 flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-email">Email</Label>
+        <Input id="input-type-email" placeholder="jane@example.com" type="email" />
+      </div>
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-number">Age</Label>
+        <Input id="input-type-number" min={0} placeholder="30" type="number" />
+      </div>
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="input-type-password">Password</Label>
+        <Input id="input-type-password" placeholder="••••••••" type="password" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/input/variants.tsx b/apps/docs/src/demos/en/input/variants.tsx
new file mode 100644
index 0000000..7cf6a27
--- /dev/null
+++ b/apps/docs/src/demos/en/input/variants.tsx
@@ -0,0 +1,10 @@
+import {Input} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex w-[240px] flex-col gap-2">
+      <Input fullWidth placeholder="Primary input" variant="primary" />
+      <Input fullWidth placeholder="Secondary input" variant="secondary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/basic.tsx b/apps/docs/src/demos/en/kbd/basic.tsx
new file mode 100644
index 0000000..aea9422
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/basic.tsx
@@ -0,0 +1,24 @@
+import {Kbd} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Kbd>
+        <Kbd.Abbr keyValue="command" />
+        <Kbd.Content>K</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="shift" />
+        <Kbd.Content>P</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="ctrl" />
+        <Kbd.Content>C</Kbd.Content>
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="option" />
+        <Kbd.Content>D</Kbd.Content>
+      </Kbd>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/index.ts b/apps/docs/src/demos/en/kbd/index.ts
new file mode 100644
index 0000000..968a638
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {NavigationKeys} from "./navigation";
+export {InlineUsage} from "./inline";
+export {SpecialKeys} from "./special";
+export {InstructionalText} from "./instructional";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/kbd/inline.tsx b/apps/docs/src/demos/en/kbd/inline.tsx
new file mode 100644
index 0000000..1a307dc
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/inline.tsx
@@ -0,0 +1,42 @@
+import {Kbd} from "@heroui/react";
+
+export function InlineUsage() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm">
+        Press{" "}
+        <Kbd>
+          <Kbd.Content>Esc</Kbd.Content>
+        </Kbd>{" "}
+        to close the dialog.
+      </p>
+      <p className="text-sm">
+        Use{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>K</Kbd.Content>
+        </Kbd>{" "}
+        to open the command palette.
+      </p>
+      <p className="text-sm">
+        Navigate with{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="up" />
+        </Kbd>{" "}
+        and{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="down" />
+        </Kbd>{" "}
+        arrow keys.
+      </p>
+      <p className="text-sm">
+        Save your work with{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>S</Kbd.Content>
+        </Kbd>{" "}
+        regularly.
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/instructional.tsx b/apps/docs/src/demos/en/kbd/instructional.tsx
new file mode 100644
index 0000000..6441361
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/instructional.tsx
@@ -0,0 +1,41 @@
+import {Kbd} from "@heroui/react";
+
+export function InstructionalText() {
+  return (
+    <div className="space-y-3">
+      <div className="rounded-lg bg-surface p-4">
+        <h4 className="mb-2 text-sm font-semibold">Quick Actions</h4>
+        <ul className="space-y-2 text-sm">
+          <li>
+            • Open search:{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>K</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • Toggle sidebar:{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>B</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • New file:{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </li>
+          <li>
+            • Quick save:{" "}
+            <Kbd>
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </li>
+        </ul>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/navigation.tsx b/apps/docs/src/demos/en/kbd/navigation.tsx
new file mode 100644
index 0000000..3635094
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/navigation.tsx
@@ -0,0 +1,42 @@
+import {Kbd} from "@heroui/react";
+
+export function NavigationKeys() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span className="text-sm text-muted">Arrow Keys:</span>
+        <div className="flex items-center gap-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="up" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="down" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="left" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="right" />
+          </Kbd>
+        </div>
+      </div>
+      <div className="flex items-center gap-2">
+        <span className="text-sm text-muted">Page Navigation:</span>
+        <div className="flex items-center gap-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="pageup" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="pagedown" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="home" />
+          </Kbd>
+          <Kbd>
+            <Kbd.Abbr keyValue="end" />
+          </Kbd>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/special.tsx b/apps/docs/src/demos/en/kbd/special.tsx
new file mode 100644
index 0000000..4d5ba16
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/special.tsx
@@ -0,0 +1,38 @@
+import {Kbd} from "@heroui/react";
+
+export function SpecialKeys() {
+  return (
+    <div className="space-y-3">
+      <p className="text-sm">
+        Press{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="enter" />
+        </Kbd>{" "}
+        to confirm or{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="escape" />
+        </Kbd>{" "}
+        to cancel.
+      </p>
+      <p className="text-sm">
+        Use{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="tab" />
+        </Kbd>{" "}
+        to navigate between form fields and{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Abbr keyValue="tab" />
+        </Kbd>{" "}
+        to go back.
+      </p>
+      <p className="text-sm">
+        Hold{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="space" />
+        </Kbd>{" "}
+        to temporarily enable panning mode.
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/kbd/variants.tsx b/apps/docs/src/demos/en/kbd/variants.tsx
new file mode 100644
index 0000000..7b0a8f1
--- /dev/null
+++ b/apps/docs/src/demos/en/kbd/variants.tsx
@@ -0,0 +1,65 @@
+import {Kbd} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>Copy:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Paste:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Cut:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Undo:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Redo:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/label/basic.tsx b/apps/docs/src/demos/en/label/basic.tsx
new file mode 100644
index 0000000..6c4f79c
--- /dev/null
+++ b/apps/docs/src/demos/en/label/basic.tsx
@@ -0,0 +1,10 @@
+import {Input, Label} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor="name">Name</Label>
+      <Input className="w-64" id="name" placeholder="Enter your name" type="text" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/label/index.ts b/apps/docs/src/demos/en/label/index.ts
new file mode 100644
index 0000000..c54b5e1
--- /dev/null
+++ b/apps/docs/src/demos/en/label/index.ts
@@ -0,0 +1 @@
+export * from "./basic";
diff --git a/apps/docs/src/demos/en/link/basic.tsx b/apps/docs/src/demos/en/link/basic.tsx
new file mode 100644
index 0000000..9cf2dd8
--- /dev/null
+++ b/apps/docs/src/demos/en/link/basic.tsx
@@ -0,0 +1,10 @@
+import {Link} from "@heroui/react";
+
+export function LinkBasic() {
+  return (
+    <Link href="#">
+      Call to action
+      <Link.Icon />
+    </Link>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/custom-icon.tsx b/apps/docs/src/demos/en/link/custom-icon.tsx
new file mode 100644
index 0000000..c31c27f
--- /dev/null
+++ b/apps/docs/src/demos/en/link/custom-icon.tsx
@@ -0,0 +1,21 @@
+import {ArrowUpRightFromSquare, Link as LinkIcon} from "@gravity-ui/icons";
+import {Link} from "@heroui/react";
+
+export function LinkCustomIcon() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Link href="#">
+        External link
+        <Link.Icon className="ml-1.5 size-3">
+          <ArrowUpRightFromSquare />
+        </Link.Icon>
+      </Link>
+      <Link className="gap-1" href="#">
+        Go to page
+        <Link.Icon className="size-3">
+          <LinkIcon />
+        </Link.Icon>
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/custom-render-function.tsx b/apps/docs/src/demos/en/link/custom-render-function.tsx
new file mode 100644
index 0000000..1c99e37
--- /dev/null
+++ b/apps/docs/src/demos/en/link/custom-render-function.tsx
@@ -0,0 +1,12 @@
+"use client";
+
+import {Link} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Link href="#" render={(props) => <span {...props} data-custom="foo" />}>
+      Call to action
+      <Link.Icon />
+    </Link>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/icon-placement.tsx b/apps/docs/src/demos/en/link/icon-placement.tsx
new file mode 100644
index 0000000..860e383
--- /dev/null
+++ b/apps/docs/src/demos/en/link/icon-placement.tsx
@@ -0,0 +1,16 @@
+import {Link} from "@heroui/react";
+
+export function LinkIconPlacement() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Link href="#">
+        Icon at end (default)
+        <Link.Icon />
+      </Link>
+      <Link className="gap-1" href="#">
+        <Link.Icon />
+        Icon at start
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/index.ts b/apps/docs/src/demos/en/link/index.ts
new file mode 100644
index 0000000..ba4b1d9
--- /dev/null
+++ b/apps/docs/src/demos/en/link/index.ts
@@ -0,0 +1,5 @@
+export {LinkBasic as Basic} from "./basic";
+export {LinkCustomIcon as CustomIcon} from "./custom-icon";
+export {LinkIconPlacement as IconPlacement} from "./icon-placement";
+export {LinkUnderlineAndOffset as UnderlineAndOffset} from "./underline-and-offset";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/link/underline-and-offset.tsx b/apps/docs/src/demos/en/link/underline-and-offset.tsx
new file mode 100644
index 0000000..e2f786b
--- /dev/null
+++ b/apps/docs/src/demos/en/link/underline-and-offset.tsx
@@ -0,0 +1,53 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineAndOffset() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Default hover underline</p>
+        <Link href="#">
+          Hover to see the underline
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Always visible underline</p>
+        <Link className="underline" href="#">
+          Underline always visible
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">No underline</p>
+        <Link className="no-underline" href="#">
+          Link without any underline
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Changing the underline offset</p>
+        <div className="flex flex-col gap-3">
+          <Link className="underline-offset-1" href="#">
+            Offset 1 (1px space)
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-2" href="#">
+            Offset 2 (2px space)
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-3" href="#">
+            Offset 3 (3px space)
+            <Link.Icon />
+          </Link>
+          <Link className="underline-offset-4" href="#">
+            Offset 4 (4px space)
+            <Link.Icon />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/underline-offset.tsx b/apps/docs/src/demos/en/link/underline-offset.tsx
new file mode 100644
index 0000000..fad8efe
--- /dev/null
+++ b/apps/docs/src/demos/en/link/underline-offset.tsx
@@ -0,0 +1,20 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineOffset() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Link className="underline-offset-1" href="#">
+        Offset 1
+        <Link.Icon />
+      </Link>
+      <Link className="underline-offset-2" href="#">
+        Offset 2
+        <Link.Icon />
+      </Link>
+      <Link className="underline-offset-3" href="#">
+        Offset 3
+        <Link.Icon />
+      </Link>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/link/underline-variants.tsx b/apps/docs/src/demos/en/link/underline-variants.tsx
new file mode 100644
index 0000000..b763758
--- /dev/null
+++ b/apps/docs/src/demos/en/link/underline-variants.tsx
@@ -0,0 +1,31 @@
+import {Link} from "@heroui/react";
+
+export function LinkUnderlineVariants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Default hover underline</p>
+        <Link href="#">
+          Hover to see the underline
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Always visible underline</p>
+        <Link className="underline" href="#">
+          Underline always visible
+          <Link.Icon />
+        </Link>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">No underline</p>
+        <Link className="no-underline" href="#">
+          Link without any underline
+          <Link.Icon />
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/controlled.tsx b/apps/docs/src/demos/en/list-box/controlled.tsx
new file mode 100644
index 0000000..6b1fca9
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/controlled.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Check} from "@gravity-ui/icons";
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selected, setSelected] = useState<Selection>(new Set(["1"]));
+
+  const selectedItems = Array.from(selected);
+
+  return (
+    <div className="space-y-4">
+      <Surface className="w-[256px] rounded-3xl shadow-surface">
+        <ListBox
+          aria-label="Users"
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={setSelected}
+        >
+          <ListBox.Item id="1" textValue="Bob">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Bob"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+              />
+              <Avatar.Fallback>B</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Bob</Label>
+              <Description>bob@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) =>
+                isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+              }
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+          <ListBox.Item id="2" textValue="Fred">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Fred"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+              />
+              <Avatar.Fallback>F</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Fred</Label>
+              <Description>fred@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) =>
+                isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+              }
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+          <ListBox.Item id="3" textValue="Martha">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Martha"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+              />
+              <Avatar.Fallback>M</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <Label>Martha</Label>
+              <Description>martha@heroui.com</Description>
+            </div>
+            <ListBox.ItemIndicator>
+              {({isSelected}) =>
+                isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+              }
+            </ListBox.ItemIndicator>
+          </ListBox.Item>
+        </ListBox>
+      </Surface>
+      <p className="text-sm text-muted">
+        Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/custom-check-icon.tsx b/apps/docs/src/demos/en/list-box/custom-check-icon.tsx
new file mode 100644
index 0000000..79fc343
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/custom-check-icon.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import {Check} from "@gravity-ui/icons";
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+
+export function CustomCheckIcon() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="Users" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Bob"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>B</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Fred"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+            />
+            <Avatar.Fallback>F</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Check className="size-4 text-accent-soft-foreground" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/custom-render-function.tsx b/apps/docs/src/demos/en/list-box/custom-render-function.tsx
new file mode 100644
index 0000000..d37491e
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/custom-render-function.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {Avatar, Description, Label, ListBox} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <ListBox
+      aria-label="Users"
+      className="w-[220px]"
+      render={(props) => <div {...props} data-custom="true" />}
+      selectionMode="single"
+    >
+      <ListBox.Item
+        id="1"
+        render={(props) => <span {...props} data-custom="foo" />}
+        textValue="Bob"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Bob"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+          />
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Bob</Label>
+          <Description>bob@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item
+        id="2"
+        render={(props) => <span {...props} data-custom="bar" />}
+        textValue="Fred"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Fred"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+          />
+          <Avatar.Fallback>F</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Fred</Label>
+          <Description>fred@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item
+        id="3"
+        render={(props) => <span {...props} data-custom="baz" />}
+        textValue="Martha"
+      >
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Martha"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+          />
+          <Avatar.Fallback>M</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Martha</Label>
+          <Description>martha@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/default.tsx b/apps/docs/src/demos/en/list-box/default.tsx
new file mode 100644
index 0000000..4da51f2
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/default.tsx
@@ -0,0 +1,50 @@
+import {Avatar, Description, Label, ListBox} from "@heroui/react";
+
+export function Default() {
+  return (
+    <ListBox aria-label="Users" className="w-[220px]" selectionMode="single">
+      <ListBox.Item id="1" textValue="Bob">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Bob"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+          />
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Bob</Label>
+          <Description>bob@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="2" textValue="Fred">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Fred"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+          />
+          <Avatar.Fallback>F</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Fred</Label>
+          <Description>fred@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="3" textValue="Martha">
+        <Avatar size="sm">
+          <Avatar.Image
+            alt="Martha"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+          />
+          <Avatar.Fallback>M</Avatar.Fallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Martha</Label>
+          <Description>martha@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/index.ts b/apps/docs/src/demos/en/list-box/index.ts
new file mode 100644
index 0000000..e47aa11
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/index.ts
@@ -0,0 +1,10 @@
+// ListBox demos
+export {Controlled} from "./controlled";
+export {CustomCheckIcon} from "./custom-check-icon";
+export {Default} from "./default";
+export {MultiSelect} from "./multi-select";
+export {ScrollbarModes} from "./scrollbar-modes";
+export {Virtualization} from "./virtualization";
+export {WithDisabledItems} from "./with-disabled-items";
+export {WithSections} from "./with-sections";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/list-box/multi-select.tsx b/apps/docs/src/demos/en/list-box/multi-select.tsx
new file mode 100644
index 0000000..ffdab1f
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/multi-select.tsx
@@ -0,0 +1,52 @@
+import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
+
+export function MultiSelect() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="Users" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Bob"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>B</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Fred"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+            />
+            <Avatar.Fallback>F</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/scrollbar-modes.tsx b/apps/docs/src/demos/en/list-box/scrollbar-modes.tsx
new file mode 100644
index 0000000..d23991c
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/scrollbar-modes.tsx
@@ -0,0 +1,84 @@
+import {ListBox, Surface} from "@heroui/react";
+
+type ScrollbarMode = {
+  id: string;
+  label: string;
+  scrollbar?: "thin" | "default" | "none";
+};
+
+const modes: ScrollbarMode[] = [
+  {
+    id: "heroui",
+    label: "HeroUI thin",
+    scrollbar: "thin",
+  },
+  {
+    id: "browser",
+    label: "Browser default",
+    scrollbar: "default",
+  },
+  {
+    id: "hidden",
+    label: "Hidden",
+    scrollbar: "none",
+  },
+];
+
+const animals = [
+  {id: "aardvark", name: "Aardvark"},
+  {id: "alpaca", name: "Alpaca"},
+  {id: "antelope", name: "Antelope"},
+  {id: "bear", name: "Bear"},
+  {id: "cat", name: "Cat"},
+  {id: "dog", name: "Dog"},
+  {id: "fox", name: "Fox"},
+  {id: "giraffe", name: "Giraffe"},
+  {id: "kangaroo", name: "Kangaroo"},
+  {id: "koala", name: "Koala"},
+  {id: "lemur", name: "Lemur"},
+  {id: "otter", name: "Otter"},
+  {id: "panda", name: "Panda"},
+  {id: "penguin", name: "Penguin"},
+  {id: "rabbit", name: "Rabbit"},
+  {id: "snake", name: "Snake"},
+  {id: "turtle", name: "Turtle"},
+  {id: "wombat", name: "Wombat"},
+  {id: "zebra", name: "Zebra"},
+];
+
+function ScrollbarListBox({mode}: {mode: ScrollbarMode}) {
+  return (
+    <div className="flex w-[260px] flex-col gap-2">
+      <h3 className="px-1 text-sm font-semibold text-muted">{mode.label}</h3>
+      <Surface
+        className="overflow-hidden rounded-3xl shadow-surface"
+        data-scrollbar={mode.scrollbar}
+      >
+        <div className="h-52 scrollbar overflow-y-auto p-1">
+          <ListBox aria-label={`${mode.label} animals`} selectionMode="single">
+            {animals.map((animal) => (
+              <ListBox.Item
+                key={`${mode.id}-${animal.id}`}
+                className="text-sm leading-5 font-medium"
+                id={`${mode.id}-${animal.id}`}
+                textValue={animal.name}
+              >
+                {animal.name}
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </div>
+      </Surface>
+    </div>
+  );
+}
+
+export function ScrollbarModes() {
+  return (
+    <div className="flex w-full flex-wrap justify-center gap-4">
+      {modes.map((mode) => (
+        <ScrollbarListBox key={mode.id} mode={mode} />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/virtualization.tsx b/apps/docs/src/demos/en/list-box/virtualization.tsx
new file mode 100644
index 0000000..f4b87f5
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/virtualization.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import {Description, Label, ListBox, ListLayout, Virtualizer} from "@heroui/react";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+export function Virtualization() {
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+
+  function generateUsers(n: number): User[] {
+    const users: User[] = [];
+
+    for (let i = 0; i < n; i++) {
+      const firstName = firstNames[i % firstNames.length];
+      const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+      const name = `${firstName} ${lastName}`;
+
+      users.push({
+        email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`,
+        id: i + 1,
+        name,
+      });
+    }
+
+    return users;
+  }
+
+  const users = generateUsers(1000);
+
+  return (
+    <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+      <ListBox
+        aria-label="Virtualized list with 1000 items"
+        className="h-[400px] w-[300px] overflow-y-auto"
+        items={users}
+      >
+        {(user) => (
+          <ListBox.Item id={user.id} textValue={user.name}>
+            <div className="flex flex-col">
+              <Label>{user.name}</Label>
+              <Description>{user.email}</Description>
+            </div>
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        )}
+      </ListBox>
+    </Virtualizer>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/with-disabled-items.tsx b/apps/docs/src/demos/en/list-box/with-disabled-items.tsx
new file mode 100644
index 0000000..0eceaa9
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/with-disabled-items.tsx
@@ -0,0 +1,66 @@
+"use client";
+
+import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+
+export function WithDisabledItems() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="File actions"
+        className="w-full p-2"
+        disabledKeys={["delete-file"]}
+        selectionMode="none"
+        onAction={(key) => alert(`Selected item: ${key}`)}
+      >
+        <ListBox.Section>
+          <Header>Actions</Header>
+          <ListBox.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="Edit file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Pencil className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Edit file</Label>
+              <Description>Make changes</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>Danger zone</Header>
+          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/list-box/with-sections.tsx b/apps/docs/src/demos/en/list-box/with-sections.tsx
new file mode 100644
index 0000000..e45e4f1
--- /dev/null
+++ b/apps/docs/src/demos/en/list-box/with-sections.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="File actions"
+        className="w-full p-2"
+        selectionMode="none"
+        onAction={(key) => alert(`Selected item: ${key}`)}
+      >
+        <ListBox.Section>
+          <Header>Actions</Header>
+          <ListBox.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="Edit file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Pencil className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Edit file</Label>
+              <Description>Make changes</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>Danger zone</Header>
+          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/meter/basic.tsx b/apps/docs/src/demos/en/meter/basic.tsx
new file mode 100644
index 0000000..2220c47
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/basic.tsx
@@ -0,0 +1,13 @@
+import {Label, Meter} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Meter aria-label="Storage" className="w-64" value={60}>
+      <Label>Storage</Label>
+      <Meter.Output />
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/en/meter/colors.tsx b/apps/docs/src/demos/en/meter/colors.tsx
new file mode 100644
index 0000000..a9b0f88
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/colors.tsx
@@ -0,0 +1,43 @@
+import {Label, Meter} from "@heroui/react";
+
+export function Colors() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <Meter color="default" value={50}>
+        <Label>Default</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="accent" value={50}>
+        <Label>Accent</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="success" value={50}>
+        <Label>Success</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="warning" value={50}>
+        <Label>Warning</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="danger" value={50}>
+        <Label>Danger</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/meter/custom-value.tsx b/apps/docs/src/demos/en/meter/custom-value.tsx
new file mode 100644
index 0000000..643d33c
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/custom-value.tsx
@@ -0,0 +1,19 @@
+import {Label, Meter} from "@heroui/react";
+
+export function CustomValue() {
+  return (
+    <Meter
+      className="w-64"
+      formatOptions={{currency: "USD", style: "currency"}}
+      maxValue={1000}
+      minValue={0}
+      value={750}
+    >
+      <Label>Revenue</Label>
+      <Meter.Output />
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/en/meter/index.ts b/apps/docs/src/demos/en/meter/index.ts
new file mode 100644
index 0000000..dc420dd
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/index.ts
@@ -0,0 +1,5 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomValue} from "./custom-value";
+export {Sizes} from "./sizes";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/en/meter/sizes.tsx b/apps/docs/src/demos/en/meter/sizes.tsx
new file mode 100644
index 0000000..25106bc
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/sizes.tsx
@@ -0,0 +1,29 @@
+import {Label, Meter} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <Meter color="success" size="sm" value={40}>
+        <Label>Small</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="accent" size="md" value={60}>
+        <Label>Medium</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+      <Meter color="warning" size="lg" value={80}>
+        <Label>Large</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/meter/without-label.tsx b/apps/docs/src/demos/en/meter/without-label.tsx
new file mode 100644
index 0000000..d1c75c7
--- /dev/null
+++ b/apps/docs/src/demos/en/meter/without-label.tsx
@@ -0,0 +1,11 @@
+import {Meter} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <Meter aria-label="Storage usage" className="w-64" value={45}>
+      <Meter.Track>
+        <Meter.Fill />
+      </Meter.Track>
+    </Meter>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/backdrop-variants.tsx b/apps/docs/src/demos/en/modal/backdrop-variants.tsx
new file mode 100644
index 0000000..e003574
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/backdrop-variants.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function BackdropVariants() {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Modal key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <Modal.Backdrop variant={variant}>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    This modal uses the <code>{variant}</code> backdrop variant. Compare the
+                    different visual effects: opaque provides full opacity, blur adds a backdrop
+                    filter, and transparent removes the background.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Continue
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/close-methods.tsx b/apps/docs/src/demos/en/modal/close-methods.tsx
new file mode 100644
index 0000000..ce14055
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/close-methods.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import {CircleCheck, CircleInfo} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CloseMethods() {
+  return (
+    <div className="flex max-w-2xl flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">Using slot="close"</h3>
+        <p className="text-sm text-muted">
+          The simplest way to close a modal. Add <code>slot="close"</code> to any Button component
+          within the modal. When clicked, it will automatically close the modal.
+        </p>
+        <Modal>
+          <Button variant="secondary">Open Modal</Button>
+          <Modal.Backdrop>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.Header>
+                  <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>Using slot="close"</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    Click either button below - both have <code>slot="close"</code> and will close
+                    the modal automatically.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="secondary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">Using Dialog render props</h3>
+        <p className="text-sm text-muted">
+          Access the <code>close</code> method from the Dialog's render props. This gives you full
+          control over when and how to close the modal, allowing you to add custom logic before
+          closing.
+        </p>
+        <Modal>
+          <Button variant="secondary">Open Modal</Button>
+          <Modal.Backdrop>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                {(renderProps) => (
+                  <>
+                    <Modal.Header>
+                      <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                        <CircleCheck className="size-5" />
+                      </Modal.Icon>
+                      <Modal.Heading>Using Dialog render props</Modal.Heading>
+                    </Modal.Header>
+                    <Modal.Body>
+                      <p>
+                        The buttons below use the <code>close</code> method from render props. You
+                        can add validation or other logic before calling{" "}
+                        <code>renderProps.close()</code>.
+                      </p>
+                    </Modal.Body>
+                    <Modal.Footer>
+                      <Button variant="secondary" onPress={() => renderProps.close()}>
+                        Cancel
+                      </Button>
+                      <Button onPress={() => renderProps.close()}>Confirm</Button>
+                    </Modal.Footer>
+                  </>
+                )}
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/controlled.tsx b/apps/docs/src/demos/en/modal/controlled.tsx
new file mode 100644
index 0000000..7a22963
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/controlled.tsx
@@ -0,0 +1,123 @@
+"use client";
+
+import {CircleCheck} from "@gravity-ui/icons";
+import {Button, Modal, useOverlayState} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Control the modal using React's <code className="text-foreground">useState</code> hook for
+          simple state management. Perfect for basic use cases.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              Open Modal
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                  <CircleCheck className="size-5" />
+                </Modal.Icon>
+                <Modal.Heading>Controlled with useState()</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  This modal is controlled by React's <code>useState</code> hook. Pass{" "}
+                  <code>isOpen</code> and <code>onOpenChange</code> props to manage the modal state
+                  externally.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API
+          with convenient methods like <code>open()</code>, <code>close()</code>, and{" "}
+          <code>toggle()</code>.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              Open Modal
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                  <CircleCheck className="size-5" />
+                </Modal.Icon>
+                <Modal.Heading>Controlled with useOverlayState()</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  The <code>useOverlayState</code> hook provides dedicated methods for common
+                  operations. No need to manually create callbacks—just use{" "}
+                  <code>state.open()</code>, <code>state.close()</code>, or{" "}
+                  <code>state.toggle()</code>.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/custom-animations.tsx b/apps/docs/src/demos/en/modal/custom-animations.tsx
new file mode 100644
index 0000000..9c3d740
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/custom-animations.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+import React from "react";
+
+const iconMap: Record<string, React.ComponentType<{className?: string}>> = {
+  "gravity-ui:arrow-up-from-line": ArrowUpFromLine,
+  "gravity-ui:sparkles": Sparkles,
+};
+
+export function CustomAnimations() {
+  const animations = [
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+      description:
+        "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Modals and Popovers.",
+      icon: "gravity-ui:sparkles",
+      name: "Kinematic Scale",
+    },
+    {
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+      description:
+        "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.",
+      icon: "gravity-ui:arrow-up-from-line",
+      name: "Fluid Slide",
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => {
+        const IconComponent = iconMap[icon];
+
+        return (
+          <Modal key={name}>
+            <Button variant="secondary">{name}</Button>
+            <Modal.Backdrop className={classNames.backdrop}>
+              <Modal.Container className={classNames.container}>
+                <Modal.Dialog className="sm:max-w-[360px]">
+                  <Modal.CloseTrigger />
+                  <Modal.Header>
+                    <Modal.Icon className="bg-default text-foreground">
+                      {!!IconComponent && <IconComponent className="size-5" />}
+                    </Modal.Icon>
+                    <Modal.Heading>{name} Animation</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p className="mt-1">{description}</p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button slot="close" variant="tertiary">
+                      Close
+                    </Button>
+                    <Button slot="close">Try Again</Button>
+                  </Modal.Footer>
+                </Modal.Dialog>
+              </Modal.Container>
+            </Modal.Backdrop>
+          </Modal>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/custom-backdrop.tsx b/apps/docs/src/demos/en/modal/custom-backdrop.tsx
new file mode 100644
index 0000000..ff7bc9d
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/custom-backdrop.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import {Sparkles} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CustomBackdrop() {
+  return (
+    <Modal>
+      <Button variant="secondary">Custom Backdrop</Button>
+      <Modal.Backdrop
+        className="bg-linear-to-t from-black/80 via-black/40 to-transparent dark:from-zinc-800/80 dark:via-zinc-800/40"
+        variant="blur"
+      >
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.Header className="items-center text-center">
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Sparkles className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>Premium Backdrop</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                This backdrop features a sophisticated gradient that transitions from a dark color
+                at the bottom to complete transparency at the top, combined with a smooth blur
+                effect. The gradient automatically adapts its intensity for optimal contrast in both
+                light and dark modes.
+              </p>
+            </Modal.Body>
+            <Modal.Footer className="flex-col-reverse">
+              <Button className="w-full" slot="close">
+                Amazing!
+              </Button>
+              <Button className="w-full" slot="close" variant="secondary">
+                Close
+              </Button>
+            </Modal.Footer>
+            <Modal.CloseTrigger />
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/custom-portal.tsx b/apps/docs/src/demos/en/modal/custom-portal.tsx
new file mode 100644
index 0000000..2b5dca1
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/custom-portal.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Button, Modal} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+export function CustomPortal() {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          Render modals inside a custom container instead of <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the
+          container to create a new stacking context.
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <Modal>
+            <Button>Open Modal</Button>
+            <Modal.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <Modal.Container className="h-full max-h-full">
+                <Modal.Dialog className="h-full max-h-full sm:max-w-md">
+                  <Modal.CloseTrigger />
+                  <Modal.Header>
+                    <Modal.Heading>Custom Portal</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button slot="close" variant="secondary">
+                      Close
+                    </Button>
+                  </Modal.Footer>
+                </Modal.Dialog>
+              </Modal.Container>
+            </Modal.Backdrop>
+          </Modal>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/custom-trigger.tsx b/apps/docs/src/demos/en/modal/custom-trigger.tsx
new file mode 100644
index 0000000..6fe93ef
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/custom-trigger.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import {Gear} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function CustomTrigger() {
+  return (
+    <Modal>
+      <Modal.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+        <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-accent-soft text-accent-soft-foreground">
+          <Gear className="size-6" />
+        </div>
+        <div className="flex flex-1 flex-col gap-0.5">
+          <p className="text-sm font-semibold">Settings</p>
+          <p className="text-xs text-muted">Manage your preferences</p>
+        </div>
+      </Modal.Trigger>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Gear className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>Settings</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                Use <code>Modal.Trigger</code> to create custom trigger elements beyond standard
+                buttons. This example shows a card-style trigger with icons and descriptive text.
+              </p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Save</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/default.tsx b/apps/docs/src/demos/en/modal/default.tsx
new file mode 100644
index 0000000..83409bd
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/default.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Modal>
+      <Button variant="secondary">Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-default text-foreground">
+                <Rocket className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>Welcome to HeroUI</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                A beautiful, fast, and modern React UI library for building accessible and
+                customizable web applications with ease.
+              </p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button className="w-full" slot="close">
+                Continue
+              </Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/dismiss-behavior.tsx b/apps/docs/src/demos/en/modal/dismiss-behavior.tsx
new file mode 100644
index 0000000..9630704
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/dismiss-behavior.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function DismissBehavior() {
+  return (
+    <div className="flex max-w-sm flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isDismissable</h3>
+        <p className="text-sm text-muted">
+          Controls whether the modal can be dismissed by clicking the overlay backdrop. Defaults to{" "}
+          <code>true</code>. Set to <code>false</code> to require explicit close action.
+        </p>
+        <Modal>
+          <Button variant="secondary">Open Modal</Button>
+          <Modal.Backdrop isDismissable={false}>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>isDismissable = false</Modal.Heading>
+                  <p className="text-sm leading-5 text-muted">
+                    Clicking the backdrop won't close this modal
+                  </p>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    Try clicking outside this modal on the overlay - it won't close. You must use
+                    the close button or press ESC to dismiss it.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Close
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+        <p className="text-sm text-muted">
+          Controls whether the ESC key can dismiss the modal. When set to <code>true</code>, the ESC
+          key will be disabled and users must use explicit close actions.
+        </p>
+        <Modal>
+          <Button variant="secondary">Open Modal</Button>
+          <Modal.Backdrop isKeyboardDismissDisabled>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <CircleInfo className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>isKeyboardDismissDisabled = true</Modal.Heading>
+                  <p className="text-sm leading-5 text-muted">ESC key is disabled</p>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    Press ESC - nothing happens. You must use the close button or click the overlay
+                    backdrop to dismiss this modal.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Close
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/index.ts b/apps/docs/src/demos/en/modal/index.ts
new file mode 100644
index 0000000..d3f71d8
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/index.ts
@@ -0,0 +1,13 @@
+export {BackdropVariants} from "./backdrop-variants";
+export {CloseMethods} from "./close-methods";
+export {Controlled} from "./controlled";
+export {CustomAnimations} from "./custom-animations";
+export {CustomBackdrop} from "./custom-backdrop";
+export {CustomPortal} from "./custom-portal";
+export {CustomTrigger} from "./custom-trigger";
+export {Default} from "./default";
+export {DismissBehavior} from "./dismiss-behavior";
+export {Placements} from "./placements";
+export {ScrollComparison} from "./scroll-comparison";
+export {Sizes} from "./sizes";
+export {WithForm} from "./with-form";
diff --git a/apps/docs/src/demos/en/modal/placements.tsx b/apps/docs/src/demos/en/modal/placements.tsx
new file mode 100644
index 0000000..6c6bedd
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/placements.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function Placements() {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Modal key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <Modal.Backdrop>
+            <Modal.Container placement={placement}>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Placement: {placement.charAt(0).toUpperCase() + placement.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    This modal uses the <code>{placement}</code> placement option. Try different
+                    placements to see how the modal positions itself on the screen.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Continue
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/scroll-comparison.tsx b/apps/docs/src/demos/en/modal/scroll-comparison.tsx
new file mode 100644
index 0000000..fa1208b
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/scroll-comparison.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Button, Modal, Radio, RadioGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function ScrollComparison() {
+  const [scroll, setScroll] = useState<"inside" | "outside">("inside");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup
+        orientation="horizontal"
+        value={scroll}
+        onChange={(value) => setScroll(value as "inside" | "outside")}
+      >
+        <Radio value="inside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Inside
+          </Radio.Content>
+        </Radio>
+        <Radio value="outside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Outside
+          </Radio.Content>
+        </Radio>
+      </RadioGroup>
+
+      <Modal>
+        <Button variant="secondary">
+          Open Modal ({scroll.charAt(0).toUpperCase() + scroll.slice(1)})
+        </Button>
+        <Modal.Backdrop>
+          <Modal.Container scroll={scroll}>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.Header>
+                <Modal.Heading>
+                  Scroll: {scroll.charAt(0).toUpperCase() + scroll.slice(1)}
+                </Modal.Heading>
+                <p className="text-sm leading-5 text-muted">
+                  Compare scroll behaviors - inside keeps content scrollable within the modal,
+                  outside allows page scrolling
+                </p>
+              </Modal.Header>
+              <Modal.Body>
+                {Array.from({length: 30}).map((_, i) => (
+                  <p key={i} className="mb-3">
+                    Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                    Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet
+                    hendrerit risus, sed porttitor quam.
+                  </p>
+                ))}
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+              <Modal.CloseTrigger />
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/sizes.tsx b/apps/docs/src/demos/en/modal/sizes.tsx
new file mode 100644
index 0000000..bababa0
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/sizes.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import {Rocket} from "@gravity-ui/icons";
+import {Button, Modal} from "@heroui/react";
+
+export function Sizes() {
+  const sizes = ["xs", "sm", "md", "lg", "cover", "full"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <Modal key={size}>
+          <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button>
+          <Modal.Backdrop>
+            <Modal.Container size={size}>
+              <Modal.Dialog>
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Rocket className="size-5" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Size: {size.charAt(0).toUpperCase() + size.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        This modal uses the <code>cover</code> size variant. It spans the full
+                        screen with margins: 16px on mobile and 40px on desktop. Maintains rounded
+                        corners and standard padding. Perfect for cover-style content that needs
+                        maximum width while preserving modal aesthetics.
+                      </>
+                    ) : size === "full" ? (
+                      <>
+                        This modal uses the <code>full</code> size variant. It occupies the entire
+                        viewport without any margins, rounded corners, or shadows, creating a true
+                        fullscreen experience. Ideal for immersive content or full-page
+                        interactions.
+                      </>
+                    ) : (
+                      <>
+                        This modal uses the <code>{size}</code> size variant. On mobile devices, all
+                        sizes adapt to near full-width for optimal viewing. On desktop, each size
+                        provides a different maximum width to suit various content needs.
+                      </>
+                    )}
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="secondary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/modal/with-form.tsx b/apps/docs/src/demos/en/modal/with-form.tsx
new file mode 100644
index 0000000..2e332b4
--- /dev/null
+++ b/apps/docs/src/demos/en/modal/with-form.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {Envelope} from "@gravity-ui/icons";
+import {Button, Input, Label, Modal, Surface, TextField} from "@heroui/react";
+
+export function WithForm() {
+  return (
+    <Modal>
+      <Button variant="secondary">Open Contact Form</Button>
+      <Modal.Backdrop>
+        <Modal.Container placement="auto">
+          <Modal.Dialog className="sm:max-w-md">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                <Envelope className="size-5" />
+              </Modal.Icon>
+              <Modal.Heading>Contact Us</Modal.Heading>
+              <p className="mt-1.5 text-sm leading-5 text-muted">
+                Fill out the form below and we'll get back to you. The modal adapts automatically
+                when the keyboard appears on mobile.
+              </p>
+            </Modal.Header>
+            <Modal.Body className="p-6">
+              <Surface variant="default">
+                <form className="flex flex-col gap-4">
+                  <TextField className="w-full" name="name" type="text" variant="secondary">
+                    <Label>Name</Label>
+                    <Input placeholder="Enter your name" />
+                  </TextField>
+                  <TextField className="w-full" name="email" type="email" variant="secondary">
+                    <Label>Email</Label>
+                    <Input placeholder="Enter your email" />
+                  </TextField>
+                  <TextField className="w-full" name="phone" type="tel" variant="secondary">
+                    <Label>Phone</Label>
+                    <Input placeholder="Enter your phone number" />
+                  </TextField>
+                  <TextField className="w-full" name="company" variant="secondary">
+                    <Label>Company</Label>
+                    <Input placeholder="Enter your company name" />
+                  </TextField>
+                  <TextField className="w-full" name="message" variant="secondary">
+                    <Label>Message</Label>
+                    <Input placeholder="Enter your message" />
+                  </TextField>
+                </form>
+              </Surface>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Send Message</Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/basic.tsx b/apps/docs/src/demos/en/number-field/basic.tsx
new file mode 100644
index 0000000..96e91c8
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/basic.tsx
@@ -0,0 +1,14 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width">
+      <Label>Width</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input className="w-[120px]" />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/controlled.tsx b/apps/docs/src/demos/en/number-field/controlled.tsx
new file mode 100644
index 0000000..e986982
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/controlled.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Button, Description, Label, NumberField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState(1024);
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField minValue={0} name="width" value={value} onChange={setValue}>
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Current value: {value}</Description>
+      </NumberField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue(0)}>
+          Reset to 0
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(2048)}>
+          Set to 2048
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/custom-icons.tsx b/apps/docs/src/demos/en/number-field/custom-icons.tsx
new file mode 100644
index 0000000..70e2d4b
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/custom-icons.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>Width (Custom Icons)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+        </NumberField.Group>
+        <Description>Custom icon children</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/custom-render-function.tsx b/apps/docs/src/demos/en/number-field/custom-render-function.tsx
new file mode 100644
index 0000000..1bf3621
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/custom-render-function.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Label, NumberField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <NumberField
+      className="w-full max-w-64"
+      defaultValue={1024}
+      minValue={0}
+      name="width"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>Width</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input className="w-[120px]" />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/disabled.tsx b/apps/docs/src/demos/en/number-field/disabled.tsx
new file mode 100644
index 0000000..4809ab3
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/disabled.tsx
@@ -0,0 +1,34 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isDisabled defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Enter the width in pixels</Description>
+      </NumberField>
+      <NumberField
+        isDisabled
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Value must be between 0 and 100</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/form-example.tsx b/apps/docs/src/demos/en/number-field/form-example.tsx
new file mode 100644
index 0000000..9315c45
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/form-example.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, NumberField, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState<number | undefined>(undefined);
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const STOCK_AVAILABLE = 3;
+  const isOutOfStock = value !== undefined && value > STOCK_AVAILABLE;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (value === undefined || value === null || value < 1 || value > STOCK_AVAILABLE) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Order submitted:", {quantity: value});
+      setValue(undefined);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <NumberField
+        isRequired
+        isInvalid={isOutOfStock}
+        maxValue={5}
+        minValue={1}
+        name="quantity"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Order quantity</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        {isOutOfStock ? (
+          <FieldError>Only {STOCK_AVAILABLE} items left in stock</FieldError>
+        ) : (
+          <Description>Only {STOCK_AVAILABLE} items available</Description>
+        )}
+      </NumberField>
+      <Button
+        className="w-full"
+        isDisabled={value === undefined || value < 1 || value > STOCK_AVAILABLE}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            Processing...
+          </>
+        ) : (
+          "Place Order"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/full-width.tsx b/apps/docs/src/demos/en/number-field/full-width.tsx
new file mode 100644
index 0000000..062d5b9
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/full-width.tsx
@@ -0,0 +1,16 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <NumberField fullWidth defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/index.ts b/apps/docs/src/demos/en/number-field/index.ts
new file mode 100644
index 0000000..81cd9bd
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/index.ts
@@ -0,0 +1,16 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIcons} from "./custom-icons";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
+export {WithChevrons} from "./with-chevrons";
+export {WithDescription} from "./with-description";
+export {WithFormatOptions} from "./with-format-options";
+export {WithStep} from "./with-step";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/en/number-field/on-surface.tsx b/apps/docs/src/demos/en/number-field/on-surface.tsx
new file mode 100644
index 0000000..d1383e0
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/on-surface.tsx
@@ -0,0 +1,34 @@
+import {Description, Label, NumberField, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-[280px] flex-col gap-4 rounded-3xl p-6">
+      <NumberField defaultValue={1024} minValue={0} name="width" variant="secondary">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-full" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Enter the width in pixels</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        variant="secondary"
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-full" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Value must be between 0 and 100</Description>
+      </NumberField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/required.tsx b/apps/docs/src/demos/en/number-field/required.tsx
new file mode 100644
index 0000000..1faaa12
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/required.tsx
@@ -0,0 +1,25 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isRequired minValue={0} name="quantity">
+        <Label>Quantity</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField isRequired defaultValue={1} maxValue={10} minValue={1} name="rating">
+        <Label>Rating</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Rate from 1 to 10</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/validation.tsx b/apps/docs/src/demos/en/number-field/validation.tsx
new file mode 100644
index 0000000..11c2c0a
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/validation.tsx
@@ -0,0 +1,34 @@
+import {FieldError, Label, NumberField} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField isInvalid isRequired minValue={0} name="quantity" value={-5}>
+        <Label>Quantity</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>Quantity must be greater than or equal to 0</FieldError>
+      </NumberField>
+      <NumberField
+        isInvalid
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        value={1.5}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>Percentage must be between 0 and 100</FieldError>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/variants.tsx b/apps/docs/src/demos/en/number-field/variants.tsx
new file mode 100644
index 0000000..08a3006
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/variants.tsx
@@ -0,0 +1,24 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={100} minValue={0} name="primary-width" variant="primary">
+        <Label>Primary variant</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField defaultValue={100} minValue={0} name="secondary-width" variant="secondary">
+        <Label>Secondary variant</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/with-chevrons.tsx b/apps/docs/src/demos/en/number-field/with-chevrons.tsx
new file mode 100644
index 0000000..557bdd2
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/with-chevrons.tsx
@@ -0,0 +1,56 @@
+import {Label, NumberField} from "@heroui/react";
+
+export function WithChevrons() {
+  return (
+    <NumberField
+      className="w-full max-w-64"
+      defaultValue={99}
+      minValue={0}
+      name="amount"
+      formatOptions={{
+        currency: "EUR",
+        currencySign: "accounting",
+        style: "currency",
+      }}
+    >
+      <Label>Number field with chevrons</Label>
+      <NumberField.Group className="flex">
+        <NumberField.Input className="flex-1" />
+        <div className="flex h-full flex-col border-l border-field-placeholder/15">
+          <NumberField.IncrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pt-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+          <NumberField.DecrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pb-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+        </div>
+      </NumberField.Group>
+    </NumberField>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/with-description.tsx b/apps/docs/src/demos/en/number-field/with-description.tsx
new file mode 100644
index 0000000..67344db
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/with-description.tsx
@@ -0,0 +1,33 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Enter the width in pixels</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Value must be between 0 and 100</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/with-format-options.tsx b/apps/docs/src/demos/en/number-field/with-format-options.tsx
new file mode 100644
index 0000000..15e36ca
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/with-format-options.tsx
@@ -0,0 +1,95 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithFormatOptions() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField
+        defaultValue={99}
+        minValue={0}
+        name="currency-eur"
+        formatOptions={{
+          currency: "EUR",
+          currencySign: "accounting",
+          style: "currency",
+        }}
+      >
+        <Label>Currency (EUR - Accounting)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Accounting format with EUR currency</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={99.99}
+        minValue={0}
+        name="currency-usd"
+        formatOptions={{
+          currency: "USD",
+          style: "currency",
+        }}
+      >
+        <Label>Currency (USD)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Standard USD currency format</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.01}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Percentage format (0-1, where 0.5 = 50%)</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1234.56}
+        minValue={0}
+        name="decimal"
+        formatOptions={{
+          maximumFractionDigits: 2,
+          minimumFractionDigits: 2,
+          style: "decimal",
+        }}
+      >
+        <Label>Decimal (2 decimal places)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Decimal format with 2 decimal places</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1000}
+        minValue={0}
+        name="unit"
+        formatOptions={{
+          style: "unit",
+          unit: "kilogram",
+          unitDisplay: "short",
+        }}
+      >
+        <Label>Unit (Kilograms)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Unit format with kilograms</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/with-step.tsx b/apps/docs/src/demos/en/number-field/with-step.tsx
new file mode 100644
index 0000000..fce1522
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/with-step.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, NumberField} from "@heroui/react";
+
+export function WithStep() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step1" step={1}>
+        <Label>Step: 1</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 1</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}>
+        <Label>Step: 5</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 5</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}>
+        <Label>Step: 10</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 10</Description>
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/number-field/with-validation.tsx b/apps/docs/src/demos/en/number-field/with-validation.tsx
new file mode 100644
index 0000000..4fa9867
--- /dev/null
+++ b/apps/docs/src/demos/en/number-field/with-validation.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {Description, FieldError, Label, NumberField} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState<number | undefined>(undefined);
+  const isInvalid = value !== undefined && (value < 0 || value > 100);
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <NumberField
+        isRequired
+        formatOptions={{style: "percent"}}
+        isInvalid={isInvalid}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        {isInvalid ? (
+          <FieldError>Percentage must be between 0 and 100</FieldError>
+        ) : (
+          <Description>Enter a value between 0 and 100</Description>
+        )}
+      </NumberField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/basic.tsx b/apps/docs/src/demos/en/pagination/basic.tsx
new file mode 100644
index 0000000..e13a0f1
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/basic.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationBasic() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/controlled.tsx b/apps/docs/src/demos/en/pagination/controlled.tsx
new file mode 100644
index 0000000..35bd8d8
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/controlled.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationControlled() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+  const itemsPerPage = 10;
+  const totalItems = 120;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    if (totalPages <= 7) {
+      for (let i = 1; i <= totalPages; i++) {
+        pages.push(i);
+      }
+    } else {
+      pages.push(1);
+
+      if (page > 3) {
+        pages.push("ellipsis");
+      }
+
+      const start = Math.max(2, page - 1);
+      const end = Math.min(totalPages - 1, page + 1);
+
+      for (let i = start; i <= end; i++) {
+        pages.push(i);
+      }
+
+      if (page < totalPages - 2) {
+        pages.push("ellipsis");
+      }
+
+      pages.push(totalPages);
+    }
+
+    return pages;
+  };
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination>
+      <Pagination.Summary>
+        Showing {startItem}-{endItem} of {totalItems} results
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {getPageNumbers().map((p, i) =>
+          p === "ellipsis" ? (
+            <Pagination.Item key={`ellipsis-${i}`}>
+              <Pagination.Ellipsis />
+            </Pagination.Item>
+          ) : (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ),
+        )}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/custom-icons.tsx b/apps/docs/src/demos/en/pagination/custom-icons.tsx
new file mode 100644
index 0000000..1418ce1
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/custom-icons.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function PaginationCustomIcons() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon>
+              <Icon icon="gravity-ui:arrow-left" />
+            </Pagination.PreviousIcon>
+            <span>Back</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>Forward</span>
+            <Pagination.NextIcon>
+              <Icon icon="gravity-ui:arrow-right" />
+            </Pagination.NextIcon>
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/disabled.tsx b/apps/docs/src/demos/en/pagination/disabled.tsx
new file mode 100644
index 0000000..3f00488
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/disabled.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationDisabled() {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <Pagination className="justify-center">
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next isDisabled onPress={() => setPage((p) => p + 1)}>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/index.ts b/apps/docs/src/demos/en/pagination/index.ts
new file mode 100644
index 0000000..13688be
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/index.ts
@@ -0,0 +1,8 @@
+export {PaginationBasic as Basic} from "./basic";
+export {PaginationSizes as Sizes} from "./sizes";
+export {PaginationWithEllipsis as WithEllipsis} from "./with-ellipsis";
+export {PaginationSimplePrevNext as SimplePrevNext} from "./simple-prev-next";
+export {PaginationWithSummary as WithSummary} from "./with-summary";
+export {PaginationCustomIcons as CustomIcons} from "./custom-icons";
+export {PaginationControlled as Controlled} from "./controlled";
+export {PaginationDisabled as Disabled} from "./disabled";
diff --git a/apps/docs/src/demos/en/pagination/simple-prev-next.tsx b/apps/docs/src/demos/en/pagination/simple-prev-next.tsx
new file mode 100644
index 0000000..5dbbe29
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/simple-prev-next.tsx
@@ -0,0 +1,36 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationSimplePrevNext() {
+  const [page, setPage] = useState(1);
+  const totalPages = 10;
+  const itemsPerPage = 5;
+  const totalItems = 50;
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination className="w-full">
+      <Pagination.Summary>
+        {startItem} to {endItem} of {totalItems} invoices
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>Prev</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/sizes.tsx b/apps/docs/src/demos/en/pagination/sizes.tsx
new file mode 100644
index 0000000..e62ec05
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/sizes.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+function SizePagination({size}: {size: "sm" | "md" | "lg"}) {
+  const [page, setPage] = useState(1);
+  const totalPages = 3;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <span className="text-xs font-medium text-muted capitalize">{size}</span>
+      <Pagination className="justify-center" size={size}>
+        <Pagination.Content>
+          <Pagination.Item>
+            <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+              <Pagination.PreviousIcon />
+              <span>Previous</span>
+            </Pagination.Previous>
+          </Pagination.Item>
+          {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ))}
+          <Pagination.Item>
+            <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+              <span>Next</span>
+              <Pagination.NextIcon />
+            </Pagination.Next>
+          </Pagination.Item>
+        </Pagination.Content>
+      </Pagination>
+    </div>
+  );
+}
+
+export function PaginationSizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      {(["sm", "md", "lg"] as const).map((size) => (
+        <SizePagination key={size} size={size} />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/with-ellipsis.tsx b/apps/docs/src/demos/en/pagination/with-ellipsis.tsx
new file mode 100644
index 0000000..a8ba0d6
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/with-ellipsis.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationWithEllipsis() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    pages.push(1);
+
+    if (page > 3) {
+      pages.push("ellipsis");
+    }
+
+    const start = Math.max(2, page - 1);
+    const end = Math.min(totalPages - 1, page + 1);
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+
+    if (page < totalPages - 2) {
+      pages.push("ellipsis");
+    }
+
+    pages.push(totalPages);
+
+    return pages;
+  };
+
+  return (
+    <div className="w-full max-w-2xs overflow-x-auto sm:max-w-full">
+      <Pagination className="justify-center">
+        <Pagination.Content>
+          <Pagination.Item>
+            <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+              <Pagination.PreviousIcon />
+              <span>Previous</span>
+            </Pagination.Previous>
+          </Pagination.Item>
+          {getPageNumbers().map((p, i) =>
+            p === "ellipsis" ? (
+              <Pagination.Item key={`ellipsis-${i}`}>
+                <Pagination.Ellipsis />
+              </Pagination.Item>
+            ) : (
+              <Pagination.Item key={p}>
+                <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ),
+          )}
+          <Pagination.Item>
+            <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+              <span>Next</span>
+              <Pagination.NextIcon />
+            </Pagination.Next>
+          </Pagination.Item>
+        </Pagination.Content>
+      </Pagination>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/pagination/with-summary.tsx b/apps/docs/src/demos/en/pagination/with-summary.tsx
new file mode 100644
index 0000000..e5d4935
--- /dev/null
+++ b/apps/docs/src/demos/en/pagination/with-summary.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import {Pagination} from "@heroui/react";
+import {useState} from "react";
+
+export function PaginationWithSummary() {
+  const [page, setPage] = useState(1);
+  const totalPages = 12;
+  const itemsPerPage = 10;
+  const totalItems = 120;
+
+  const getPageNumbers = () => {
+    const pages: (number | "ellipsis")[] = [];
+
+    pages.push(1);
+
+    if (page > 3) {
+      pages.push("ellipsis");
+    }
+
+    const start = Math.max(2, page - 1);
+    const end = Math.min(totalPages - 1, page + 1);
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+
+    if (page < totalPages - 2) {
+      pages.push("ellipsis");
+    }
+
+    pages.push(totalPages);
+
+    return pages;
+  };
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <Pagination className="w-full">
+      <Pagination.Summary>
+        Showing {startItem}-{endItem} of {totalItems} results
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        {getPageNumbers().map((p, i) =>
+          p === "ellipsis" ? (
+            <Pagination.Item key={`ellipsis-${i}`}>
+              <Pagination.Ellipsis />
+            </Pagination.Item>
+          ) : (
+            <Pagination.Item key={p}>
+              <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                {p}
+              </Pagination.Link>
+            </Pagination.Item>
+          ),
+        )}
+        <Pagination.Item>
+          <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
diff --git a/apps/docs/src/demos/en/popover/basic.tsx b/apps/docs/src/demos/en/popover/basic.tsx
new file mode 100644
index 0000000..73c19b6
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/basic.tsx
@@ -0,0 +1,19 @@
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button>Click me</Button>
+        <Popover.Content className="max-w-64">
+          <Popover.Dialog>
+            <Popover.Heading>Popover Title</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">
+              This is the popover content. You can put any content here.
+            </p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/popover/custom-render-function.tsx b/apps/docs/src/demos/en/popover/custom-render-function.tsx
new file mode 100644
index 0000000..56c760d
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/custom-render-function.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Button, Popover} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button>Click me</Button>
+        <Popover.Content
+          className="max-w-64"
+          render={(props) => <div {...props} data-custom="foo" />}
+        >
+          <Popover.Dialog>
+            <Popover.Heading>Popover Title</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">
+              This is the popover content. You can put any content here.
+            </p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/popover/index.ts b/apps/docs/src/demos/en/popover/index.ts
new file mode 100644
index 0000000..dcd9cb2
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/index.ts
@@ -0,0 +1,5 @@
+export {PopoverBasic as Basic} from "./basic";
+export {PopoverWithArrow as WithArrow} from "./with-arrow";
+export {PopoverPlacement as Placement} from "./placement";
+export {PopoverInteractive as Interactive} from "./interactive";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/popover/interactive.tsx b/apps/docs/src/demos/en/popover/interactive.tsx
new file mode 100644
index 0000000..5c59efc
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/interactive.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import {Avatar, Button, Popover} from "@heroui/react";
+import {useState} from "react";
+
+export function PopoverInteractive() {
+  const [isFollowing, setIsFollowing] = useState(false);
+
+  return (
+    <div className="flex items-center gap-6">
+      <Popover>
+        <Popover.Trigger aria-label="User profile">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Sarah Johnson"
+                src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1"
+              />
+              <Avatar.Fallback>SJ</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col">
+              <p className="text-sm font-medium">Sarah Johnson</p>
+              <p className="text-xs text-muted">@sarahj</p>
+            </div>
+          </div>
+        </Popover.Trigger>
+        <Popover.Content className="w-[320px]">
+          <Popover.Dialog>
+            <Popover.Heading>
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                  <Avatar size="md">
+                    <Avatar.Image
+                      alt="Sarah Johnson"
+                      src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1"
+                    />
+                    <Avatar.Fallback>SJ</Avatar.Fallback>
+                  </Avatar>
+                  <div>
+                    <p className="font-semibold">Sarah Johnson</p>
+                    <p className="text-sm text-muted">@sarahj</p>
+                  </div>
+                </div>
+                <Button
+                  className="rounded-full"
+                  size="sm"
+                  variant={isFollowing ? "tertiary" : "primary"}
+                  onPress={() => setIsFollowing(!isFollowing)}
+                >
+                  {isFollowing ? "Following" : "Follow"}
+                </Button>
+              </div>
+            </Popover.Heading>
+            <p className="mt-3 text-sm text-muted">
+              Product designer and creative director. Building beautiful experiences that matter.
+            </p>
+            <div className="mt-3 flex gap-4">
+              <div>
+                <span className="font-semibold">892</span>
+                <span className="ml-1 text-sm text-muted">Following</span>
+              </div>
+              <div>
+                <span className="font-semibold">12.5K</span>
+                <span className="ml-1 text-sm text-muted">Followers</span>
+              </div>
+            </div>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/popover/placement.tsx b/apps/docs/src/demos/en/popover/placement.tsx
new file mode 100644
index 0000000..c02b084
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/placement.tsx
@@ -0,0 +1,63 @@
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverPlacement() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <div />
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Top
+        </Button>
+        <Popover.Content placement="top">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">Top placement</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+      <div />
+
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Left
+        </Button>
+        <Popover.Content placement="left">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">Left placement</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <div className="flex items-center justify-center">
+        <span className="text-sm text-muted">Click buttons</span>
+      </div>
+
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Right
+        </Button>
+        <Popover.Content placement="right">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">Right placement</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <div />
+      <Popover>
+        <Button className="w-full" variant="tertiary">
+          Bottom
+        </Button>
+        <Popover.Content placement="bottom">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <p className="text-sm">Bottom placement</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+      <div />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/popover/with-arrow.tsx b/apps/docs/src/demos/en/popover/with-arrow.tsx
new file mode 100644
index 0000000..be2ebc7
--- /dev/null
+++ b/apps/docs/src/demos/en/popover/with-arrow.tsx
@@ -0,0 +1,36 @@
+import {Ellipsis} from "@gravity-ui/icons";
+import {Button, Popover} from "@heroui/react";
+
+export function PopoverWithArrow() {
+  return (
+    <div className="flex items-center gap-4">
+      <Popover>
+        <Button variant="secondary">With Arrow</Button>
+        <Popover.Content className="max-w-64">
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <Popover.Heading>Popover with Arrow</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">
+              The arrow shows which element triggered the popover.
+            </p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+
+      <Popover>
+        <Button isIconOnly variant="tertiary">
+          <Ellipsis />
+        </Button>
+        <Popover.Content className="max-w-64" offset={10}>
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <Popover.Heading>Popover with Arrow</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">
+              The arrow shows which element triggered the popover.
+            </p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/basic.tsx b/apps/docs/src/demos/en/progress-bar/basic.tsx
new file mode 100644
index 0000000..42df049
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/basic.tsx
@@ -0,0 +1,13 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ProgressBar aria-label="Loading" className="w-64" value={60}>
+      <Label>Loading</Label>
+      <ProgressBar.Output />
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/colors.tsx b/apps/docs/src/demos/en/progress-bar/colors.tsx
new file mode 100644
index 0000000..de769eb
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/colors.tsx
@@ -0,0 +1,43 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Colors() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <ProgressBar aria-label="Default" color="default" value={50}>
+        <Label>Default</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Accent" color="accent" value={50}>
+        <Label>Accent</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Success" color="success" value={50}>
+        <Label>Success</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Warning" color="warning" value={50}>
+        <Label>Warning</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Danger" color="danger" value={50}>
+        <Label>Danger</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/custom-value.tsx b/apps/docs/src/demos/en/progress-bar/custom-value.tsx
new file mode 100644
index 0000000..99f8f79
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/custom-value.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import {Label, ListBox, NumberField, ProgressBar, Select, Separator} from "@heroui/react";
+import {useState} from "react";
+
+const formatStyleOptions: {label: string; value: string}[] = [
+  {label: "Currency", value: "currency"},
+  {label: "Percent", value: "percent"},
+  {label: "Decimal", value: "decimal"},
+  {label: "Unit", value: "unit"},
+];
+
+const formatOptionsMap: Record<string, Intl.NumberFormatOptions> = {
+  currency: {currency: "USD", style: "currency"},
+  decimal: {style: "decimal"},
+  percent: {style: "percent"},
+  unit: {style: "unit", unit: "mile"},
+};
+
+export function CustomValue() {
+  const [value, setValue] = useState(750);
+  const [minValue, setMinValue] = useState(0);
+  const [maxValue, setMaxValue] = useState(1000);
+  const [format, setFormat] = useState<string>("percent");
+
+  return (
+    <div className="flex w-full flex-col gap-6 md:flex-row md:items-center md:gap-10">
+      <div className="flex w-full max-w-md flex-1 justify-center">
+        <ProgressBar
+          aria-label="Revenue"
+          className="w-full max-w-52"
+          formatOptions={formatOptionsMap[format]}
+          maxValue={maxValue}
+          minValue={minValue}
+          value={value}
+        >
+          <Label>Progress</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+      </div>
+
+      <Separator className="md:hidden" />
+      <Separator className="hidden md:block" orientation="vertical" />
+
+      <div className="flex max-w-52 flex-col gap-3">
+        <Label className="text-xs font-medium text-muted">Options</Label>
+
+        <NumberField
+          maxValue={maxValue}
+          minValue={minValue}
+          value={value}
+          variant="secondary"
+          onChange={(v) => setValue(v)}
+        >
+          <Label>Value</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <NumberField
+          maxValue={maxValue - 1}
+          minValue={0}
+          value={minValue}
+          variant="secondary"
+          onChange={(v) => {
+            setMinValue(v);
+            if (value < v) setValue(v);
+          }}
+        >
+          <Label>Min Value</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <NumberField
+          maxValue={2000}
+          minValue={minValue + 1}
+          value={maxValue}
+          variant="secondary"
+          onChange={(v) => {
+            setMaxValue(v);
+            if (value > v) setValue(v);
+          }}
+        >
+          <Label>Max Value</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+        </NumberField>
+
+        <Select value={format} variant="secondary" onChange={(key) => setFormat(key as string)}>
+          <Label>Format</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {formatStyleOptions.map((option) => (
+                <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
+                  {option.label}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/indeterminate.tsx b/apps/docs/src/demos/en/progress-bar/indeterminate.tsx
new file mode 100644
index 0000000..c1f1bf4
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/indeterminate.tsx
@@ -0,0 +1,12 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Indeterminate() {
+  return (
+    <ProgressBar isIndeterminate aria-label="Loading" className="w-64">
+      <Label>Loading...</Label>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/index.ts b/apps/docs/src/demos/en/progress-bar/index.ts
new file mode 100644
index 0000000..0032f81
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomValue} from "./custom-value";
+export {Indeterminate} from "./indeterminate";
+export {Sizes} from "./sizes";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/en/progress-bar/sizes.tsx b/apps/docs/src/demos/en/progress-bar/sizes.tsx
new file mode 100644
index 0000000..bc3b89a
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/sizes.tsx
@@ -0,0 +1,29 @@
+import {Label, ProgressBar} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex w-64 flex-col gap-6">
+      <ProgressBar aria-label="Small" size="sm" value={40}>
+        <Label>Small</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Medium" size="md" value={60}>
+        <Label>Medium</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+      <ProgressBar aria-label="Large" size="lg" value={80}>
+        <Label>Large</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-bar/without-label.tsx b/apps/docs/src/demos/en/progress-bar/without-label.tsx
new file mode 100644
index 0000000..31feab8
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-bar/without-label.tsx
@@ -0,0 +1,11 @@
+import {ProgressBar} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <ProgressBar aria-label="Loading progress" className="w-64" value={45}>
+      <ProgressBar.Track>
+        <ProgressBar.Fill />
+      </ProgressBar.Track>
+    </ProgressBar>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/basic.tsx b/apps/docs/src/demos/en/progress-circle/basic.tsx
new file mode 100644
index 0000000..078a799
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/basic.tsx
@@ -0,0 +1,12 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ProgressCircle aria-label="Loading" value={60}>
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/colors.tsx b/apps/docs/src/demos/en/progress-circle/colors.tsx
new file mode 100644
index 0000000..3bfedaa
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/colors.tsx
@@ -0,0 +1,38 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Colors() {
+  return (
+    <div className="flex items-center gap-6">
+      <ProgressCircle aria-label="Default" color="default" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Accent" color="accent" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Success" color="success" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Warning" color="warning" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Danger" color="danger" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/custom-svg.tsx b/apps/docs/src/demos/en/progress-circle/custom-svg.tsx
new file mode 100644
index 0000000..64b23c5
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/custom-svg.tsx
@@ -0,0 +1,28 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function CustomSvg() {
+  return (
+    <div className="flex items-end gap-6">
+      <ProgressCircle aria-label="Thin circle" value={60}>
+        <ProgressCircle.Track strokeWidth={2} viewBox="0 0 36 36">
+          <ProgressCircle.TrackCircle cx={18} cy={18} r={17} strokeWidth={2} />
+          <ProgressCircle.FillCircle cx={18} cy={18} r={17} strokeWidth={2} />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+
+      <ProgressCircle aria-label="Default circle" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+
+      <ProgressCircle aria-label="Thick circle" value={60}>
+        <ProgressCircle.Track strokeWidth={6} viewBox="0 0 36 36">
+          <ProgressCircle.TrackCircle cx={18} cy={18} r={15} strokeWidth={6} />
+          <ProgressCircle.FillCircle cx={18} cy={18} r={15} strokeWidth={6} />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/indeterminate.tsx b/apps/docs/src/demos/en/progress-circle/indeterminate.tsx
new file mode 100644
index 0000000..b0deb62
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/indeterminate.tsx
@@ -0,0 +1,12 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Indeterminate() {
+  return (
+    <ProgressCircle isIndeterminate aria-label="Loading">
+      <ProgressCircle.Track>
+        <ProgressCircle.TrackCircle />
+        <ProgressCircle.FillCircle />
+      </ProgressCircle.Track>
+    </ProgressCircle>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/index.ts b/apps/docs/src/demos/en/progress-circle/index.ts
new file mode 100644
index 0000000..7efa906
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Colors} from "./colors";
+export {CustomSvg} from "./custom-svg";
+export {Indeterminate} from "./indeterminate";
+export {Sizes} from "./sizes";
+export {WithLabel} from "./with-label";
diff --git a/apps/docs/src/demos/en/progress-circle/sizes.tsx b/apps/docs/src/demos/en/progress-circle/sizes.tsx
new file mode 100644
index 0000000..e6c7ab4
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/sizes.tsx
@@ -0,0 +1,26 @@
+import {ProgressCircle} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex items-center gap-6">
+      <ProgressCircle aria-label="Loading" size="sm" value={40}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Loading" size="md" value={60}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <ProgressCircle aria-label="Loading" size="lg" value={80}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/progress-circle/with-label.tsx b/apps/docs/src/demos/en/progress-circle/with-label.tsx
new file mode 100644
index 0000000..8aed7d2
--- /dev/null
+++ b/apps/docs/src/demos/en/progress-circle/with-label.tsx
@@ -0,0 +1,15 @@
+import {Label, ProgressCircle} from "@heroui/react";
+
+export function WithLabel() {
+  return (
+    <div className="flex items-center gap-3">
+      <ProgressCircle aria-label="Loading" value={75}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+      <Label>75% Complete</Label>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/basic.tsx b/apps/docs/src/demos/en/radio-group/basic.tsx
new file mode 100644
index 0000000..3e2d1a9
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/basic.tsx
@@ -0,0 +1,37 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <RadioGroup defaultValue="premium" name="plan">
+      <Label>Plan selection</Label>
+      <Description>Choose the plan that suits you best</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic Plan
+        </Radio.Content>
+        <Description>Includes 100 messages per month</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Premium Plan
+        </Radio.Content>
+        <Description>Includes 200 messages per month</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Business Plan
+        </Radio.Content>
+        <Description>Unlimited messages</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/controlled.tsx b/apps/docs/src/demos/en/radio-group/controlled.tsx
new file mode 100644
index 0000000..91b1f29
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/controlled.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("pro");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup name="plan-controlled" value={value} onChange={setValue}>
+        <Label>Subscription plan</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects and small teams</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting and analytics</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Share access with up to 10 teammates</Description>
+        </Radio>
+      </RadioGroup>
+      <p className="text-sm text-muted">
+        Selected plan: <span className="font-medium">{value}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/custom-indicator.tsx b/apps/docs/src/demos/en/radio-group/custom-indicator.tsx
new file mode 100644
index 0000000..1a66f6f
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/custom-indicator.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <RadioGroup defaultValue="premium" name="plan-custom-indicator">
+      <Label>Plan selection</Label>
+      <Description>Choose the plan that suits you best</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          Basic Plan
+        </Radio.Content>
+        <Description>Includes 100 messages per month</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          Premium Plan
+        </Radio.Content>
+        <Description>Includes 200 messages per month</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator>
+              {({isSelected}) =>
+                isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
+              }
+            </Radio.Indicator>
+          </Radio.Control>
+          Business Plan
+        </Radio.Content>
+        <Description>Unlimited messages</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/custom-render-function.tsx b/apps/docs/src/demos/en/radio-group/custom-render-function.tsx
new file mode 100644
index 0000000..ae3291c
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/custom-render-function.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <RadioGroup
+      defaultValue="premium"
+      name="plan-custom-render"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>Plan selection</Label>
+      <Description>Choose the plan that suits you best</Description>
+      <Radio value="basic">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Basic Plan
+        </Radio.Content>
+        <Description>Includes 100 messages per month</Description>
+      </Radio>
+      <Radio value="premium">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Premium Plan
+        </Radio.Content>
+        <Description>Includes 200 messages per month</Description>
+      </Radio>
+      <Radio value="business">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Business Plan
+        </Radio.Content>
+        <Description>Unlimited messages</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/delivery-and-payment.tsx b/apps/docs/src/demos/en/radio-group/delivery-and-payment.tsx
new file mode 100644
index 0000000..708b447
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/delivery-and-payment.tsx
@@ -0,0 +1,117 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import clsx from "clsx";
+
+export function DeliveryAndPayment() {
+  const deliveryOptions = [
+    {
+      description: "4-10 business days",
+      price: "$5.00",
+      title: "Standard",
+      value: "standard",
+    },
+    {
+      description: "2-5 business days",
+      price: "$16.00",
+      title: "Express",
+      value: "express",
+    },
+    {
+      description: "1 business day",
+      price: "$25.00",
+      title: "Super Fast",
+      value: "super-fast",
+    },
+  ];
+
+  const paymentOptions = [
+    {
+      description: "Exp. on 01/2026",
+      icon: "uim:master-card",
+      title: "**** 8304",
+      value: "mastercard",
+    },
+    {
+      description: "Exp. on 01/2026",
+      icon: "streamline-logos:visa-logo-solid",
+      title: "**** 0123",
+      value: "visa",
+    },
+    {
+      description: "Pay with PayPal",
+      icon: "ic:baseline-paypal",
+      title: "PayPal",
+      value: "paypal",
+    },
+  ];
+
+  return (
+    <div
+      className="flex w-full flex-col items-center gap-10"
+      style={{
+        // @ts-expect-error - Overrides default variables
+        "--accent": "#006FEE",
+        "--accent-foreground": "#fff",
+        "--accent-hover": "#006FEE",
+        "--border-width": "2px",
+        "--border-width-field": "2px",
+        "--focus": "#006FEE",
+      }}
+    >
+      <section className="flex w-full max-w-lg flex-col gap-4">
+        <RadioGroup defaultValue="express" name="delivery" variant="secondary">
+          <Label>Delivery method</Label>
+          <div className="grid gap-x-4 md:grid-cols-3">
+            {deliveryOptions.map((option) => (
+              <Radio key={option.value} value={option.value}>
+                <Radio.Content
+                  className={clsx(
+                    "group relative flex w-full flex-col gap-6 rounded-xl border border-transparent bg-surface px-5 py-4 transition-all data-[selected=true]:border-accent data-[selected=true]:bg-accent/10",
+                    "data-[focus-visible=true]:border-accent data-[focus-visible=true]:bg-accent/10",
+                  )}
+                >
+                  <Radio.Control className="absolute top-3 right-4 size-5">
+                    <Radio.Indicator />
+                  </Radio.Control>
+                  <div className="flex flex-col gap-1">
+                    <span>{option.title}</span>
+                    <Description>{option.description}</Description>
+                  </div>
+                  <span className="text-sm font-semibold">{option.price}</span>
+                </Radio.Content>
+              </Radio>
+            ))}
+          </div>
+        </RadioGroup>
+      </section>
+      <section className="flex w-full max-w-lg flex-col gap-4">
+        <RadioGroup defaultValue="visa" name="payment" variant="secondary">
+          <div className="flex flex-wrap items-center justify-between gap-4">
+            <Label>Payment method</Label>
+          </div>
+          <div className="grid gap-x-4 md:grid-cols-2">
+            {paymentOptions.map((option) => (
+              <Radio key={option.value} value={option.value}>
+                <Radio.Content
+                  className={clsx(
+                    "group relative flex w-full flex-row items-start justify-start gap-4 rounded-xl border border-transparent bg-surface px-5 py-4 transition-all",
+                    "data-[selected=true]:border-accent data-[selected=true]:bg-accent/10",
+                  )}
+                >
+                  <Radio.Control className="absolute top-3 right-4 size-5">
+                    <Radio.Indicator />
+                  </Radio.Control>
+                  <Icon className="size-6" icon={option.icon} />
+                  <div className="flex flex-col gap-1">
+                    <span>{option.title}</span>
+                    <Description>{option.description}</Description>
+                  </div>
+                </Radio.Content>
+              </Radio>
+            ))}
+          </div>
+        </RadioGroup>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/disabled.tsx b/apps/docs/src/demos/en/radio-group/disabled.tsx
new file mode 100644
index 0000000..4c082de
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/disabled.tsx
@@ -0,0 +1,37 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <RadioGroup isDisabled defaultValue="pro" name="plan-disabled">
+      <Label>Subscription plan</Label>
+      <Description>Plan changes are temporarily paused while we roll out updates.</Description>
+      <Radio value="starter">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Starter
+        </Radio.Content>
+        <Description>For side projects and small teams</Description>
+      </Radio>
+      <Radio value="pro">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Pro
+        </Radio.Content>
+        <Description>Advanced reporting and analytics</Description>
+      </Radio>
+      <Radio value="teams">
+        <Radio.Content>
+          <Radio.Control>
+            <Radio.Indicator />
+          </Radio.Control>
+          Teams
+        </Radio.Content>
+        <Description>Share access with up to 10 teammates</Description>
+      </Radio>
+    </RadioGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/horizontal.tsx b/apps/docs/src/demos/en/radio-group/horizontal.tsx
new file mode 100644
index 0000000..096849a
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/horizontal.tsx
@@ -0,0 +1,38 @@
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+
+export function Horizontal() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Label>Subscription plan</Label>
+      <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal">
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Up to 10 teammates</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/index.ts b/apps/docs/src/demos/en/radio-group/index.ts
new file mode 100644
index 0000000..0f552d5
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/index.ts
@@ -0,0 +1,11 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DeliveryAndPayment} from "./delivery-and-payment";
+export {Disabled} from "./disabled";
+export {Horizontal} from "./horizontal";
+export {OnSurface} from "./on-surface";
+export {Uncontrolled} from "./uncontrolled";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/radio-group/on-surface.tsx b/apps/docs/src/demos/en/radio-group/on-surface.tsx
new file mode 100644
index 0000000..f4a93fd
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/on-surface.tsx
@@ -0,0 +1,39 @@
+import {Description, Label, Radio, RadioGroup, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <RadioGroup defaultValue="premium" name="plan-on-surface" variant="secondary">
+        <Label>Plan selection</Label>
+        <Description>Choose the plan that suits you best</Description>
+        <Radio value="basic">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Basic Plan
+          </Radio.Content>
+          <Description>Includes 100 messages per month</Description>
+        </Radio>
+        <Radio value="premium">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Premium Plan
+          </Radio.Content>
+          <Description>Includes 200 messages per month</Description>
+        </Radio>
+        <Radio value="business">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Business Plan
+          </Radio.Content>
+          <Description>Unlimited messages</Description>
+        </Radio>
+      </RadioGroup>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/uncontrolled.tsx b/apps/docs/src/demos/en/radio-group/uncontrolled.tsx
new file mode 100644
index 0000000..db9dbfd
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/uncontrolled.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import {Description, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Uncontrolled() {
+  const [selection, setSelection] = React.useState("pro");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup
+        defaultValue="pro"
+        name="plan-uncontrolled"
+        onChange={(nextValue) => setSelection(nextValue)}
+      >
+        <Label>Subscription plan</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects and small teams</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting and analytics</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Share access with up to 10 teammates</Description>
+        </Radio>
+      </RadioGroup>
+      <p className="text-sm text-muted">
+        Last chosen plan: <span className="font-medium">{selection}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/validation.tsx b/apps/docs/src/demos/en/radio-group/validation.tsx
new file mode 100644
index 0000000..fc5142e
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/validation.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, Radio, RadioGroup} from "@heroui/react";
+import React from "react";
+
+export function Validation() {
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  return (
+    <Form
+      className="flex flex-col gap-4"
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        const formData = new FormData(e.currentTarget);
+        const value = formData.get("plan-validation");
+
+        setMessage(`Your chosen plan is: ${value}`);
+      }}
+    >
+      <RadioGroup isRequired name="plan-validation">
+        <Label>Subscription plan</Label>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects and small teams</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting and analytics</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Share access with up to 10 teammates</Description>
+        </Radio>
+        <FieldError>Choose a subscription before continuing.</FieldError>
+      </RadioGroup>
+      <Button className="mt-2 w-fit" type="submit">
+        Submit
+      </Button>
+      {!!message && <p className="text-sm text-muted">{message}</p>}
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/radio-group/variants.tsx b/apps/docs/src/demos/en/radio-group/variants.tsx
new file mode 100644
index 0000000..1b2954b
--- /dev/null
+++ b/apps/docs/src/demos/en/radio-group/variants.tsx
@@ -0,0 +1,54 @@
+import {Description, Radio, RadioGroup} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Primary variant</p>
+        <RadioGroup defaultValue="option1" name="primary-plan" variant="primary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 1
+            </Radio.Content>
+            <Description>Standard styling with default background</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 2
+            </Radio.Content>
+            <Description>Another option with primary styling</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary variant</p>
+        <RadioGroup defaultValue="option1" name="secondary-plan" variant="secondary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 1
+            </Radio.Content>
+            <Description>Lower emphasis variant for use in surfaces</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 2
+            </Radio.Content>
+            <Description>Another option with secondary styling</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/allows-non-contiguous-ranges.tsx b/apps/docs/src/demos/en/range-calendar/allows-non-contiguous-ranges.tsx
new file mode 100644
index 0000000..b1961ef
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/allows-non-contiguous-ranges.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function AllowsNonContiguousRanges() {
+  const now = today(getLocalTimeZone());
+  const blockedRanges = [
+    [now.add({days: 2}), now.add({days: 5})],
+    [now.add({days: 12}), now.add({days: 13})],
+  ] as const;
+
+  const isDateUnavailable = (date: DateValue) => {
+    return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        allowsNonContiguousRanges
+        aria-label="Trip dates"
+        defaultValue={{end: now.add({days: 9}), start: now.add({days: 1})}}
+        firstDayOfWeek="mon"
+        isDateUnavailable={isDateUnavailable}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">
+        Non-contiguous ranges are allowed across unavailable dates
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/anchor-unavailable-dates.tsx b/apps/docs/src/demos/en/range-calendar/anchor-unavailable-dates.tsx
new file mode 100644
index 0000000..27fc7f9
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/anchor-unavailable-dates.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {CalendarDate, DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function AnchorUnavailableDates() {
+  const now = today(getLocalTimeZone());
+
+  const isDateUnavailable = (date: DateValue, anchorDate: CalendarDate | null) => {
+    return anchorDate != null && Math.abs(date.compare(anchorDate)) > 7;
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="Trip dates" isDateUnavailable={isDateUnavailable} minValue={now}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">
+        After selecting a start date, only dates within 7 days are available
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/basic.tsx b/apps/docs/src/demos/en/range-calendar/basic.tsx
new file mode 100644
index 0000000..7df4cdd
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/basic.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <RangeCalendar aria-label="Trip dates" firstDayOfWeek="mon">
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/booking-calendar.tsx b/apps/docs/src/demos/en/range-calendar/booking-calendar.tsx
new file mode 100644
index 0000000..8eca247
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/booking-calendar.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function BookingCalendar() {
+  const [selectedRange, setSelectedRange] = useState<DateRange | null>(null);
+  const {locale} = useLocale();
+  const blockedDates = [5, 6, 12, 13, 14, 20];
+
+  const isDateUnavailable = (date: DateValue) => {
+    return isWeekend(date, locale) || blockedDates.includes(date.day);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="Booking range"
+        isDateUnavailable={isDateUnavailable}
+        minValue={today(getLocalTimeZone())}
+        value={selectedRange}
+        onChange={setSelectedRange}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => (
+              <RangeCalendar.Cell date={date}>
+                {({formattedDate, isUnavailable}) => (
+                  <>
+                    {formattedDate}
+                    {!isUnavailable &&
+                      !isWeekend(date, locale) &&
+                      blockedDates.includes(date.day) && <RangeCalendar.CellIndicator />}
+                  </>
+                )}
+              </RangeCalendar.Cell>
+            )}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <div className="flex flex-col gap-2 text-center">
+        <div className="flex items-center justify-center gap-4 text-xs text-muted">
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-muted" /> Blocked dates
+          </span>
+          <span className="flex items-center gap-1">
+            <span className="size-2 rounded-full bg-default" /> Weekend/Unavailable
+          </span>
+        </div>
+        {selectedRange ? (
+          <Button size="sm" variant="primary">
+            Book {selectedRange.start.toString()} -&gt; {selectedRange.end.toString()}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/controlled.tsx b/apps/docs/src/demos/en/range-calendar/controlled.tsx
new file mode 100644
index 0000000..73fdb12
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/controlled.tsx
@@ -0,0 +1,116 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, ButtonGroup, Description, RangeCalendar} from "@heroui/react";
+import {
+  getLocalTimeZone,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import {useState} from "react";
+import {useLocale} from "react-aria-components";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Controlled() {
+  const [value, setValue] = useState<DateRange | null>(null);
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25"));
+  const {locale} = useLocale();
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <ButtonGroup variant="tertiary">
+        <Button
+          onPress={() => {
+            const start = today(getLocalTimeZone());
+
+            setFocusedDate(start);
+          }}
+        >
+          This week
+        </Button>
+        <Button
+          onPress={() => {
+            const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale);
+
+            setFocusedDate(nextWeekStart);
+          }}
+        >
+          Next week
+        </Button>
+        <Button
+          onPress={() => {
+            const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1}));
+
+            setFocusedDate(nextMonthStart);
+          }}
+        >
+          Next month
+        </Button>
+      </ButtonGroup>
+
+      <RangeCalendar
+        aria-label="Trip dates"
+        firstDayOfWeek="mon"
+        focusedValue={focusedDate}
+        value={value}
+        onChange={setValue}
+        onFocusChange={setFocusedDate}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+
+      <Description className="text-center">
+        Selected range: {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(none)"}
+      </Description>
+
+      <div className="flex gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const start = today(getLocalTimeZone());
+
+            setValue({end: start.add({days: 6}), start});
+            setFocusedDate(start);
+          }}
+        >
+          Set 1 week
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const start = parseDate("2025-12-20");
+
+            setValue({end: parseDate("2025-12-31"), start});
+            setFocusedDate(start);
+          }}
+        >
+          Set Holidays
+        </Button>
+        <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/day-view.tsx b/apps/docs/src/demos/en/range-calendar/day-view.tsx
new file mode 100644
index 0000000..35a4a47
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/day-view.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Label, ListBox, RangeCalendar, Select} from "@heroui/react";
+import {useState} from "react";
+
+const dayOptions = [
+  {id: "1", name: "1 day"},
+  {id: "5", name: "5 days"},
+  {id: "7", name: "7 days"},
+  {id: "8", name: "8 days"},
+  {id: "10", name: "10 days"},
+  {id: "14", name: "14 days"},
+  {id: "21", name: "21 days"},
+] as const;
+
+export function DayView() {
+  const [days, setDays] = useState(5);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(days)}
+        onChange={(value) => value && setDays(Number(value))}
+      >
+        <Label>Visible days</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {dayOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <RangeCalendar key={days} aria-label="Trip dates" visibleDuration={{days}}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/default-value.tsx b/apps/docs/src/demos/en/range-calendar/default-value.tsx
new file mode 100644
index 0000000..4318a22
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/default-value.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+
+export function DefaultValue() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      defaultValue={{end: parseDate("2025-02-12"), start: parseDate("2025-02-03")}}
+      firstDayOfWeek="mon"
+    >
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/disabled.tsx b/apps/docs/src/demos/en/range-calendar/disabled.tsx
new file mode 100644
index 0000000..0b7b979
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/disabled.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar isDisabled aria-label="Trip dates">
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">Range calendar is disabled</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/focused-value.tsx b/apps/docs/src/demos/en/range-calendar/focused-value.tsx
new file mode 100644
index 0000000..851fad8
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/focused-value.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Button, Description, RangeCalendar} from "@heroui/react";
+import {parseDate} from "@internationalized/date";
+import {useState} from "react";
+
+export function FocusedValue() {
+  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="Trip dates"
+        firstDayOfWeek="mon"
+        focusedValue={focusedDate}
+        onFocusChange={setFocusedDate}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">Focused: {focusedDate.toString()}</Description>
+      <div className="flex flex-wrap justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+        >
+          Go to Jan
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+        >
+          Go to Jun
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+        >
+          Go to Christmas
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/index.ts b/apps/docs/src/demos/en/range-calendar/index.ts
new file mode 100644
index 0000000..b2b1aab
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/index.ts
@@ -0,0 +1,20 @@
+export {AllowsNonContiguousRanges} from "./allows-non-contiguous-ranges";
+export {AnchorUnavailableDates} from "./anchor-unavailable-dates";
+export {Basic} from "./basic";
+export {BookingCalendar} from "./booking-calendar";
+export {Controlled} from "./controlled";
+export {DefaultValue} from "./default-value";
+export {Disabled} from "./disabled";
+export {FocusedValue} from "./focused-value";
+export {InternationalCalendar} from "./international-calendar";
+export {Invalid} from "./invalid";
+export {MinMaxDates} from "./min-max-dates";
+export {MultipleMonths} from "./multiple-months";
+export {ReadOnly} from "./read-only";
+export {ThreeMonths} from "./three-months";
+export {UnavailableDates} from "./unavailable-dates";
+export {DayView} from "./day-view";
+export {WeekView} from "./week-view";
+export {WeeksInMonth} from "./weeks-in-month";
+export {WithIndicators} from "./with-indicators";
+export {YearPicker} from "./year-picker";
diff --git a/apps/docs/src/demos/en/range-calendar/international-calendar.tsx b/apps/docs/src/demos/en/range-calendar/international-calendar.tsx
new file mode 100644
index 0000000..656e509
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/international-calendar.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {I18nProvider} from "react-aria-components";
+
+export function InternationalCalendar() {
+  return (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <RangeCalendar aria-label="Trip dates">
+        <RangeCalendar.Header>
+          <RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.YearPickerTriggerHeading />
+            <RangeCalendar.YearPickerTriggerIndicator />
+          </RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+        <RangeCalendar.YearPickerGrid>
+          <RangeCalendar.YearPickerGridBody>
+            {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+          </RangeCalendar.YearPickerGridBody>
+        </RangeCalendar.YearPickerGrid>
+      </RangeCalendar>
+    </I18nProvider>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/invalid.tsx b/apps/docs/src/demos/en/range-calendar/invalid.tsx
new file mode 100644
index 0000000..3c50392
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/invalid.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import {useState} from "react";
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+export function Invalid() {
+  const now = today(getLocalTimeZone());
+  const [value, setValue] = useState<DateRange>({
+    end: now.add({days: 14}),
+    start: now.add({days: 6}),
+  });
+  const isInvalid = value.end.compare(value.start) > 7;
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="Trip dates"
+        firstDayOfWeek="mon"
+        isInvalid={isInvalid}
+        value={value}
+        onChange={setValue}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      {isInvalid ? (
+        <p className="text-sm text-danger">Maximum stay duration is 1 week</p>
+      ) : (
+        <Description className="text-center">Select a stay of up to 7 days</Description>
+      )}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/min-max-dates.tsx b/apps/docs/src/demos/en/range-calendar/min-max-dates.tsx
new file mode 100644
index 0000000..c1022ae
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/min-max-dates.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function MinMaxDates() {
+  const now = today(getLocalTimeZone());
+  const minDate = now;
+  const maxDate = now.add({months: 3});
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="Trip dates" maxValue={maxDate} minValue={minDate}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">
+        Select dates between today and {maxDate.toString()}
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/multiple-months.tsx b/apps/docs/src/demos/en/range-calendar/multiple-months.tsx
new file mode 100644
index 0000000..41d15d2
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/multiple-months.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function MultipleMonths() {
+  return (
+    <RangeCalendar
+      aria-label="Trip dates"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 1}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/read-only.tsx b/apps/docs/src/demos/en/range-calendar/read-only.tsx
new file mode 100644
index 0000000..2d7bbfa
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/read-only.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function ReadOnly() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        isReadOnly
+        aria-label="Trip dates"
+        defaultValue={{
+          end: today(getLocalTimeZone()).add({days: 4}),
+          start: today(getLocalTimeZone()),
+        }}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">Range calendar is read-only</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/three-months.tsx b/apps/docs/src/demos/en/range-calendar/three-months.tsx
new file mode 100644
index 0000000..336c5e4
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/three-months.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function ThreeMonths() {
+  return (
+    <RangeCalendar
+      aria-label="Vacation planning"
+      className="@container-normal w-auto overflow-x-auto"
+      visibleDuration={{months: 3}}
+    >
+      <div className="flex w-max gap-7">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 1}} />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 2}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 2}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/unavailable-dates.tsx b/apps/docs/src/demos/en/range-calendar/unavailable-dates.tsx
new file mode 100644
index 0000000..b84fafd
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/unavailable-dates.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+
+import {Description, RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+
+export function UnavailableDates() {
+  const now = today(getLocalTimeZone());
+  const blockedRanges = [
+    [now.add({days: 2}), now.add({days: 5})],
+    [now.add({days: 12}), now.add({days: 13})],
+  ] as const;
+
+  const isDateUnavailable = (date: DateValue) => {
+    return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0);
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar
+        aria-label="Trip dates"
+        defaultValue={{end: now.add({days: 9}), start: now.add({days: 6})}}
+        firstDayOfWeek="mon"
+        isDateUnavailable={isDateUnavailable}
+      >
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">Some days are unavailable</Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/week-view.tsx b/apps/docs/src/demos/en/range-calendar/week-view.tsx
new file mode 100644
index 0000000..1e52705
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/week-view.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import {Label, ListBox, RangeCalendar, Select} from "@heroui/react";
+import {useState} from "react";
+
+const weekOptions = [
+  {id: "1", name: "1 week"},
+  {id: "2", name: "2 weeks"},
+  {id: "3", name: "3 weeks"},
+  {id: "4", name: "4 weeks"},
+  {id: "5", name: "5 weeks"},
+  {id: "6", name: "6 weeks"},
+  {id: "8", name: "8 weeks"},
+] as const;
+
+export function WeekView() {
+  const [weeks, setWeeks] = useState(1);
+
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <Select
+        className="w-40"
+        value={String(weeks)}
+        onChange={(value) => value && setWeeks(Number(value))}
+      >
+        <Label>Visible weeks</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {weekOptions.map((option) => (
+              <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                {option.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+
+      <RangeCalendar key={weeks} aria-label="Trip dates" visibleDuration={{weeks}}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/weeks-in-month.tsx b/apps/docs/src/demos/en/range-calendar/weeks-in-month.tsx
new file mode 100644
index 0000000..0b4a160
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/weeks-in-month.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Description, RangeCalendar} from "@heroui/react";
+
+export function WeeksInMonth() {
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendar aria-label="Trip dates" weeksInMonth={6}>
+        <RangeCalendar.Header>
+          <RangeCalendar.Heading />
+          <RangeCalendar.NavButton slot="previous" />
+          <RangeCalendar.NavButton slot="next" />
+        </RangeCalendar.Header>
+        <RangeCalendar.Grid>
+          <RangeCalendar.GridHeader>
+            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+          </RangeCalendar.GridHeader>
+          <RangeCalendar.GridBody>
+            {(date) => <RangeCalendar.Cell date={date} />}
+          </RangeCalendar.GridBody>
+        </RangeCalendar.Grid>
+      </RangeCalendar>
+      <Description className="text-center">
+        Always shows 6 weeks per month to avoid layout shift when navigating
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/with-indicators.tsx b/apps/docs/src/demos/en/range-calendar/with-indicators.tsx
new file mode 100644
index 0000000..cd4827e
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/with-indicators.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+import {getLocalTimeZone, isToday} from "@internationalized/date";
+
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export function WithIndicators() {
+  return (
+    <RangeCalendar aria-label="Trip dates">
+      <RangeCalendar.Header>
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => (
+            <RangeCalendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <RangeCalendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </RangeCalendar.Cell>
+          )}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/range-calendar/year-picker.tsx b/apps/docs/src/demos/en/range-calendar/year-picker.tsx
new file mode 100644
index 0000000..2cbbed8
--- /dev/null
+++ b/apps/docs/src/demos/en/range-calendar/year-picker.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {RangeCalendar} from "@heroui/react";
+
+export function YearPicker() {
+  return (
+    <RangeCalendar aria-label="Trip dates">
+      <RangeCalendar.Header>
+        <RangeCalendar.YearPickerTrigger>
+          <RangeCalendar.YearPickerTriggerHeading />
+          <RangeCalendar.YearPickerTriggerIndicator />
+        </RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => <RangeCalendar.Cell date={date} />}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+      <RangeCalendar.YearPickerGrid>
+        <RangeCalendar.YearPickerGridBody>
+          {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+        </RangeCalendar.YearPickerGridBody>
+      </RangeCalendar.YearPickerGrid>
+    </RangeCalendar>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/custom-size.tsx b/apps/docs/src/demos/en/scroll-shadow/custom-size.tsx
new file mode 100644
index 0000000..07fd005
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/custom-size.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function CustomSize() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow className="max-h-[240px] p-4" size={80}>
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.
+              Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/default.tsx b/apps/docs/src/demos/en/scroll-shadow/default.tsx
new file mode 100644
index 0000000..a596627
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/default.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function Default() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow className="max-h-[240px] p-4">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.
+              Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/hide-scroll-bar.tsx b/apps/docs/src/demos/en/scroll-shadow/hide-scroll-bar.tsx
new file mode 100644
index 0000000..827e365
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/hide-scroll-bar.tsx
@@ -0,0 +1,19 @@
+import {ScrollShadow} from "@heroui/react";
+
+export default function HideScrollBar() {
+  return (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow hideScrollBar className="max-h-[240px] p-4">
+        <div className="space-y-4">
+          {Array.from({length: 10}).map((_, idx) => (
+            <p key={`scroll-shadow-lorem-content-${idx}`}>
+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+              risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam.
+              Morbi accumsan cursus enim, sed ultricies sapien.
+            </p>
+          ))}
+        </div>
+      </ScrollShadow>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/index.ts b/apps/docs/src/demos/en/scroll-shadow/index.ts
new file mode 100644
index 0000000..a814c6e
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/index.ts
@@ -0,0 +1,6 @@
+export {default as Default} from "./default";
+export {default as Orientation} from "./orientation";
+export {default as HideScrollBar} from "./hide-scroll-bar";
+export {default as CustomSize} from "./custom-size";
+export {default as VisibilityChange} from "./visibility-change";
+export {default as WithCard} from "./with-card";
diff --git a/apps/docs/src/demos/en/scroll-shadow/orientation.tsx b/apps/docs/src/demos/en/scroll-shadow/orientation.tsx
new file mode 100644
index 0000000..1297f13
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/orientation.tsx
@@ -0,0 +1,62 @@
+import {Card, ScrollShadow} from "@heroui/react";
+
+const images = [
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
+];
+
+export default function Orientation() {
+  const getRandomImage = (idx: number) => {
+    return images[idx % images.length];
+  };
+
+  return (
+    <div className="w-full sm:max-w-sm">
+      <div className="mb-8 w-full">
+        <h4 className="mb-2 text-sm font-semibold">Vertical</h4>
+        <Card className="w-full p-0">
+          <ScrollShadow className="max-h-[240px] p-4" orientation="vertical">
+            <div className="space-y-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <p key={`scroll-shadow-lorem-content-${idx}`}>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
+                  quam. Morbi accumsan cursus enim, sed ultricies sapien.
+                </p>
+              ))}
+            </div>
+          </ScrollShadow>
+        </Card>
+      </div>
+
+      <div className="w-full">
+        <h4 className="mb-2 text-sm font-semibold">Horizontal</h4>
+        <Card className="w-full p-0">
+          <ScrollShadow className="p-4" orientation="horizontal">
+            <div className="flex flex-row gap-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <Card
+                  key={`scroll-shadow-lorem-cards-${idx}`}
+                  className="flex min-w-[200px] flex-row gap-3 p-1"
+                  variant="transparent"
+                >
+                  <img
+                    alt="Lorem Card"
+                    className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                    loading="lazy"
+                    src={getRandomImage(idx)}
+                  />
+                  <div className="flex flex-1 flex-col justify-center gap-1">
+                    <Card.Title className="text-sm">Bridging the Future</Card.Title>
+                    <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
+                  </div>
+                </Card>
+              ))}
+            </div>
+          </ScrollShadow>
+        </Card>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/visibility-change.tsx b/apps/docs/src/demos/en/scroll-shadow/visibility-change.tsx
new file mode 100644
index 0000000..6b86266
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/visibility-change.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import type {ScrollShadowVisibility} from "@heroui/react";
+
+import {Card, ScrollShadow} from "@heroui/react";
+import {useState} from "react";
+
+const images = [
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
+  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
+];
+
+export default function VisibilityChange() {
+  const [verticalState, setVerticalState] = useState<ScrollShadowVisibility>("none");
+  const [horizontalState, setHorizontalState] = useState<ScrollShadowVisibility>("none");
+
+  const getRandomImage = (idx: number) => {
+    return images[idx % images.length];
+  };
+
+  return (
+    <div className="w-full sm:max-w-sm">
+      <div className="mb-8 flex flex-col gap-2">
+        <div className="rounded bg-default p-4">
+          <p className="text-sm font-semibold">Vertical Shadow State: {verticalState}</p>
+        </div>
+        <div className="w-full">
+          <ScrollShadow
+            className="max-h-[240px] p-4"
+            orientation="vertical"
+            onVisibilityChange={(visibility) => setVerticalState(visibility)}
+          >
+            <div className="space-y-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <p key={`scroll-shadow-lorem-content-${idx}`}>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
+                  quam. Morbi accumsan cursus enim, sed ultricies sapien.
+                </p>
+              ))}
+            </div>
+          </ScrollShadow>
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="rounded bg-default p-4">
+          <p className="text-sm font-semibold">Horizontal Shadow State: {horizontalState}</p>
+        </div>
+        <div className="w-full">
+          <ScrollShadow
+            className="p-4"
+            orientation="horizontal"
+            onVisibilityChange={(visibility) => setHorizontalState(visibility)}
+          >
+            <div className="flex flex-row gap-4">
+              {Array.from({length: 10}).map((_, idx) => (
+                <Card
+                  key={`scroll-shadow-lorem-cards-${idx}`}
+                  className="flex min-w-[200px] flex-row gap-3 p-1"
+                  variant="transparent"
+                >
+                  <img
+                    alt="Lorem Card"
+                    className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                    loading="lazy"
+                    src={getRandomImage(idx)}
+                  />
+                  <div className="flex flex-1 flex-col justify-center gap-1">
+                    <Card.Title className="text-sm">Bridging the Future</Card.Title>
+                    <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
+                  </div>
+                </Card>
+              ))}
+            </div>
+          </ScrollShadow>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/scroll-shadow/with-card.tsx b/apps/docs/src/demos/en/scroll-shadow/with-card.tsx
new file mode 100644
index 0000000..35e9e0e
--- /dev/null
+++ b/apps/docs/src/demos/en/scroll-shadow/with-card.tsx
@@ -0,0 +1,31 @@
+import {Button, Card, ScrollShadow} from "@heroui/react";
+
+export default function WithCard() {
+  return (
+    <Card className="max-w-[400px]">
+      <Card.Header>
+        <Card.Title>Terms and Conditions</Card.Title>
+        <Card.Description>Please review before proceeding</Card.Description>
+      </Card.Header>
+      <Card.Content className="p-0">
+        <ScrollShadow className="h-[300px] px-4" size={80}>
+          <div className="space-y-4">
+            {Array.from({length: 10}).map((_, idx) => (
+              <p key={`scroll-shadow-lorem-content-${idx}`}>
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
+                risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
+                quam. Morbi accumsan cursus enim, sed ultricies sapien.
+              </p>
+            ))}
+          </div>
+        </ScrollShadow>
+      </Card.Content>
+      <Card.Footer className="mt-4 flex flex-row gap-2">
+        <Button className="w-full" variant="secondary">
+          Cancel
+        </Button>
+        <Button className="w-full">Accept</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/basic.tsx b/apps/docs/src/demos/en/search-field/basic.tsx
new file mode 100644
index 0000000..deded94
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/basic.tsx
@@ -0,0 +1,14 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <SearchField name="search">
+      <Label>Search</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input className="w-[280px]" placeholder="Search..." />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/controlled.tsx b/apps/docs/src/demos/en/search-field/controlled.tsx
new file mode 100644
index 0000000..b02a874
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/controlled.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Button, Description, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search" value={value} onChange={setValue}>
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Current value: {value || "(empty)"}</Description>
+      </SearchField>
+      <div className="flex gap-2">
+        <Button variant="tertiary" onPress={() => setValue("")}>
+          Clear
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue("example query")}>
+          Set example
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/custom-icons.tsx b/apps/docs/src/demos/en/search-field/custom-icons.tsx
new file mode 100644
index 0000000..f7c5a6f
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/custom-icons.tsx
@@ -0,0 +1,35 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function CustomIcons() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search-custom">
+        <Label>Search (Custom Icons)</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.SearchIcon>
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.ClearButton>
+        </SearchField.Group>
+        <Description>Custom icon children</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/custom-render-function.tsx b/apps/docs/src/demos/en/search-field/custom-render-function.tsx
new file mode 100644
index 0000000..2fd4179
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/custom-render-function.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Label, SearchField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <SearchField name="search" render={(props) => <div {...props} data-custom="foo" />}>
+      <Label>Search</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input className="w-[280px]" placeholder="Search..." />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/disabled.tsx b/apps/docs/src/demos/en/search-field/disabled.tsx
new file mode 100644
index 0000000..63c6c4b
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/disabled.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isDisabled name="search" value="Disabled search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>This search field is disabled</Description>
+      </SearchField>
+      <SearchField isDisabled name="search-empty">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>This search field is disabled</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/form-example.tsx b/apps/docs/src/demos/en/search-field/form-example.tsx
new file mode 100644
index 0000000..300cc47
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/form-example.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import {Button, Description, FieldError, Form, Label, SearchField, Spinner} from "@heroui/react";
+import React from "react";
+
+export function FormExample() {
+  const [value, setValue] = React.useState("");
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const MIN_LENGTH = 3;
+  const isInvalid = value.length > 0 && value.length < MIN_LENGTH;
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (value.length < MIN_LENGTH) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Search submitted:", {query: value});
+      setValue("");
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
+        <Label>Search products</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="Search products..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        {isInvalid ? (
+          <FieldError>Search query must be at least {MIN_LENGTH} characters</FieldError>
+        ) : (
+          <Description>Enter at least {MIN_LENGTH} characters to search</Description>
+        )}
+      </SearchField>
+      <Button
+        className="w-full"
+        isDisabled={value.length < MIN_LENGTH}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? (
+          <>
+            <Spinner color="current" size="sm" />
+            Searching...
+          </>
+        ) : (
+          "Search"
+        )}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/full-width.tsx b/apps/docs/src/demos/en/search-field/full-width.tsx
new file mode 100644
index 0000000..2d9d2b0
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/full-width.tsx
@@ -0,0 +1,16 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <SearchField fullWidth name="search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/index.ts b/apps/docs/src/demos/en/search-field/index.ts
new file mode 100644
index 0000000..fd9642e
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/index.ts
@@ -0,0 +1,14 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomIcons} from "./custom-icons";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Validation} from "./validation";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithKeyboardShortcut} from "./with-keyboard-shortcut";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/en/search-field/on-surface.tsx b/apps/docs/src/demos/en/search-field/on-surface.tsx
new file mode 100644
index 0000000..a4144c7
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/on-surface.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <SearchField name="search" variant="secondary">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Enter keywords to search</Description>
+      </SearchField>
+      <SearchField name="search-2" variant="secondary">
+        <Label>Advanced search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-full" placeholder="Advanced search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Use filters to refine your search</Description>
+      </SearchField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/required.tsx b/apps/docs/src/demos/en/search-field/required.tsx
new file mode 100644
index 0000000..80279d5
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/required.tsx
@@ -0,0 +1,25 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isRequired name="search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField isRequired name="search-query">
+        <Label>Search query</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Enter search query..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Minimum 3 characters required</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/validation.tsx b/apps/docs/src/demos/en/search-field/validation.tsx
new file mode 100644
index 0000000..ae14365
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/validation.tsx
@@ -0,0 +1,26 @@
+import {FieldError, Label, SearchField} from "@heroui/react";
+
+export function Validation() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isInvalid isRequired name="search" value="ab">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>Search query must be at least 3 characters</FieldError>
+      </SearchField>
+      <SearchField isInvalid name="search-invalid">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." value="invalid@query" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>Invalid characters in search query</FieldError>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/variants.tsx b/apps/docs/src/demos/en/search-field/variants.tsx
new file mode 100644
index 0000000..9891410
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/variants.tsx
@@ -0,0 +1,24 @@
+import {Label, SearchField} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="primary-search" variant="primary">
+        <Label>Primary variant</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField name="secondary-search" variant="secondary">
+        <Label>Secondary variant</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/with-description.tsx b/apps/docs/src/demos/en/search-field/with-description.tsx
new file mode 100644
index 0000000..c8b8f6f
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/with-description.tsx
@@ -0,0 +1,26 @@
+import {Description, Label, SearchField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search">
+        <Label>Search products</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search products..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Enter keywords to search for products</Description>
+      </SearchField>
+      <SearchField name="search-users">
+        <Label>Search users</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search users..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Search by name, email, or username</Description>
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/with-keyboard-shortcut.tsx b/apps/docs/src/demos/en/search-field/with-keyboard-shortcut.tsx
new file mode 100644
index 0000000..29b73ef
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/with-keyboard-shortcut.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import {Description, Kbd, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function WithKeyboardShortcut() {
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const [value, setValue] = React.useState("");
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Check for Shift+S
+      if (e.shiftKey && e.key === "S" && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        e.preventDefault();
+        inputRef.current?.focus();
+      }
+      // Check for ESC key to blur the input
+      if (e.key === "Escape" && document.activeElement === inputRef.current) {
+        inputRef.current?.blur();
+      }
+    };
+
+    // Add global event listener
+    window.addEventListener("keydown", handleKeyDown);
+
+    // Cleanup on unmount
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <SearchField name="search" value={value} onChange={setValue}>
+          <Label>Search</Label>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="Search..." />
+            <SearchField.ClearButton />
+          </SearchField.Group>
+          <Description>Use keyboard shortcut to quickly focus this field</Description>
+        </SearchField>
+      </div>
+      <div className="text-default-500 flex items-center gap-2 text-sm">
+        <span>Press</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>S</Kbd.Content>
+        </Kbd>
+        <span>to focus the search field</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/search-field/with-validation.tsx b/apps/docs/src/demos/en/search-field/with-validation.tsx
new file mode 100644
index 0000000..99c2f06
--- /dev/null
+++ b/apps/docs/src/demos/en/search-field/with-validation.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Description, FieldError, Label, SearchField} from "@heroui/react";
+import React from "react";
+
+export function WithValidation() {
+  const [value, setValue] = React.useState("");
+  const isInvalid = value.length > 0 && value.length < 3;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        {isInvalid ? (
+          <FieldError>Search query must be at least 3 characters</FieldError>
+        ) : (
+          <Description>Enter at least 3 characters to search</Description>
+        )}
+      </SearchField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/asynchronous-loading.tsx b/apps/docs/src/demos/en/select/asynchronous-loading.tsx
new file mode 100644
index 0000000..52fe888
--- /dev/null
+++ b/apps/docs/src/demos/en/select/asynchronous-loading.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import {Label, ListBox, Select, Spinner} from "@heroui/react";
+import {useAsyncList} from "@react-stately/data";
+import {Collection, ListBoxLoadMoreItem} from "react-aria-components";
+
+interface Pokemon {
+  name: string;
+}
+
+export function AsynchronousLoading() {
+  const list = useAsyncList<Pokemon>({
+    async load({cursor, signal}) {
+      const res = await fetch(cursor || `https://pokeapi.co/api/v2/pokemon`, {signal});
+      const json = await res.json();
+
+      return {
+        cursor: json.next,
+        items: json.results,
+      };
+    },
+  });
+
+  return (
+    <Select className="w-[256px]" placeholder="Select a Pokemon">
+      <Label>Pick a Pokemon</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <Collection items={list.items}>
+            {(item: Pokemon) => (
+              <ListBox.Item id={item.name} textValue={item.name}>
+                {item.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            )}
+          </Collection>
+          <ListBoxLoadMoreItem
+            isLoading={list.loadingState === "loadingMore"}
+            onLoadMore={list.loadMore}
+          >
+            <div className="flex items-center justify-center gap-2 py-2">
+              <Spinner size="sm" />
+              <span className="text-sm text-muted">Loading more...</span>
+            </div>
+          </ListBoxLoadMoreItem>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/controlled-multiple.tsx b/apps/docs/src/demos/en/select/controlled-multiple.tsx
new file mode 100644
index 0000000..679888c
--- /dev/null
+++ b/apps/docs/src/demos/en/select/controlled-multiple.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Label, ListBox, Select} from "@heroui/react";
+import React from "react";
+
+export function ControlledMultiple() {
+  const [selected, setSelected] = React.useState<Key[]>(["california", "texas"]);
+
+  return (
+    <div className="space-y-4">
+      <Select
+        className="w-[256px]"
+        placeholder="Select states"
+        selectionMode="multiple"
+        value={selected}
+        onChange={(keys) => setSelected(keys as Key[])}
+      >
+        <Label>States (controlled multiple)</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox selectionMode="multiple">
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="Texas">
+              Texas
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="New York">
+              New York
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="illinois" textValue="Illinois">
+              Illinois
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="pennsylvania" textValue="Pennsylvania">
+              Pennsylvania
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <p className="text-sm text-muted">
+        Selected: {selected.length > 0 ? selected.join(", ") : "None"}
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/controlled-open-state.tsx b/apps/docs/src/demos/en/select/controlled-open-state.tsx
new file mode 100644
index 0000000..346782f
--- /dev/null
+++ b/apps/docs/src/demos/en/select/controlled-open-state.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import {Button, Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+export function ControlledOpenState() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <Select
+        className="w-[256px]"
+        isOpen={isOpen}
+        placeholder="Select one"
+        onOpenChange={setIsOpen}
+      >
+        <Label>State</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="Delaware">
+              Delaware
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="Texas">
+              Texas
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="New York">
+              New York
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="Washington">
+              Washington
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Select</Button>
+      <p className="text-sm text-muted">Select is {isOpen ? "open" : "closed"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/controlled.tsx b/apps/docs/src/demos/en/select/controlled.tsx
new file mode 100644
index 0000000..9e35b8d
--- /dev/null
+++ b/apps/docs/src/demos/en/select/controlled.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Label, ListBox, Select} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const states = [
+    {
+      id: "california",
+      name: "California",
+    },
+    {
+      id: "texas",
+      name: "Texas",
+    },
+    {
+      id: "florida",
+      name: "Florida",
+    },
+    {
+      id: "new-york",
+      name: "New York",
+    },
+    {
+      id: "illinois",
+      name: "Illinois",
+    },
+    {
+      id: "pennsylvania",
+      name: "Pennsylvania",
+    },
+  ];
+
+  const [state, setState] = useState<Key | null>("california");
+
+  const selectedState = states.find((s) => s.id === state);
+
+  return (
+    <div className="space-y-2">
+      <Select
+        className="w-[256px]"
+        placeholder="Select a state"
+        value={state}
+        onChange={(value) => setState(value)}
+      >
+        <Label>State (controlled)</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {states.map((state) => (
+              <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                {state.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/custom-indicator.tsx b/apps/docs/src/demos/en/select/custom-indicator.tsx
new file mode 100644
index 0000000..bcfa19e
--- /dev/null
+++ b/apps/docs/src/demos/en/select/custom-indicator.tsx
@@ -0,0 +1,44 @@
+import {ChevronsExpandVertical} from "@gravity-ui/icons";
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator className="size-3">
+          <ChevronsExpandVertical />
+        </Select.Indicator>
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/custom-render-function.tsx b/apps/docs/src/demos/en/select/custom-render-function.tsx
new file mode 100644
index 0000000..29d271e
--- /dev/null
+++ b/apps/docs/src/demos/en/select/custom-render-function.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Select
+      className="w-[256px]"
+      placeholder="Select one"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/custom-value-multiple.tsx b/apps/docs/src/demos/en/select/custom-value-multiple.tsx
new file mode 100644
index 0000000..fd06b58
--- /dev/null
+++ b/apps/docs/src/demos/en/select/custom-value-multiple.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Chip,
+  Description,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+
+export function CustomValueMultiple() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <Select
+      className="w-[256px]"
+      defaultValue={["1", "2"]}
+      placeholder="Select your teammates"
+      selectionMode="multiple"
+    >
+      <Label>Users</Label>
+      <Select.Trigger>
+        <Select.Value className="no-truncate flex flex-wrap gap-2">
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+            return selectedItemsKeys.map((selectedItemKey) => {
+              const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+              if (!selectedItem) {
+                return null;
+              }
+
+              return (
+                <Chip key={selectedItemKey} variant="soft">
+                  <Avatar className="size-4" size="sm">
+                    <AvatarImage src={selectedItem.avatarUrl} />
+                    <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                  </Avatar>
+                  <Chip.Label>{selectedItem.name}</Chip.Label>
+                </Chip>
+              );
+            });
+          }}
+        </Select.Value>
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/custom-value.tsx b/apps/docs/src/demos/en/select/custom-value.tsx
new file mode 100644
index 0000000..acc1de3
--- /dev/null
+++ b/apps/docs/src/demos/en/select/custom-value.tsx
@@ -0,0 +1,106 @@
+"use client";
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Description,
+  Label,
+  ListBox,
+  Select,
+} from "@heroui/react";
+
+export function CustomValue() {
+  const users = [
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+      email: "bob@heroui.com",
+      fallback: "B",
+      id: "1",
+      name: "Bob",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+      email: "fred@heroui.com",
+      fallback: "F",
+      id: "2",
+      name: "Fred",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+      email: "martha@heroui.com",
+      fallback: "M",
+      id: "3",
+      name: "Martha",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      email: "john@heroui.com",
+      fallback: "J",
+      id: "4",
+      name: "John",
+    },
+    {
+      avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+      email: "jane@heroui.com",
+      fallback: "J",
+      id: "5",
+      name: "Jane",
+    },
+  ];
+
+  return (
+    <Select className="w-[256px]" placeholder="Select a user">
+      <Label>User</Label>
+      <Select.Trigger>
+        <Select.Value>
+          {({defaultChildren, isPlaceholder, state}) => {
+            if (isPlaceholder || state.selectedItems.length === 0) {
+              return defaultChildren;
+            }
+
+            const selectedItems = state.selectedItems;
+
+            if (selectedItems.length > 1) {
+              return `${selectedItems.length} users selected`;
+            }
+
+            const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
+
+            if (!selectedItem) {
+              return defaultChildren;
+            }
+
+            return (
+              <div className="flex items-center gap-2">
+                <Avatar className="size-4" size="sm">
+                  <AvatarImage src={selectedItem.avatarUrl} />
+                  <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                </Avatar>
+                <span>{selectedItem.name}</span>
+              </div>
+            );
+          }}
+        </Select.Value>
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          {users.map((user) => (
+            <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+              <Avatar size="sm">
+                <AvatarImage src={user.avatarUrl} />
+                <AvatarFallback>{user.fallback}</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          ))}
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/default.tsx b/apps/docs/src/demos/en/select/default.tsx
new file mode 100644
index 0000000..fc945fb
--- /dev/null
+++ b/apps/docs/src/demos/en/select/default.tsx
@@ -0,0 +1,41 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/disabled.tsx b/apps/docs/src/demos/en/select/disabled.tsx
new file mode 100644
index 0000000..fc2c6fc
--- /dev/null
+++ b/apps/docs/src/demos/en/select/disabled.tsx
@@ -0,0 +1,84 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Select isDisabled className="w-[256px]" defaultValue="california" placeholder="Select one">
+        <Label>State</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="Delaware">
+              Delaware
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="Texas">
+              Texas
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="New York">
+              New York
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="Washington">
+              Washington
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select
+        isDisabled
+        className="w-[256px]"
+        defaultValue={["argentina", "japan", "france"]}
+        placeholder="Select countries"
+        selectionMode="multiple"
+      >
+        <Label>Countries to Visit</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="argentina" textValue="Argentina">
+              Argentina
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="venezuela" textValue="Venezuela">
+              Venezuela
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/full-width.tsx b/apps/docs/src/demos/en/select/full-width.tsx
new file mode 100644
index 0000000..4605295
--- /dev/null
+++ b/apps/docs/src/demos/en/select/full-width.tsx
@@ -0,0 +1,31 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <Select fullWidth placeholder="Select one">
+        <Label>Favorite Animal</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="bird" textValue="Bird">
+              Bird
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/index.ts b/apps/docs/src/demos/en/select/index.ts
new file mode 100644
index 0000000..564c223
--- /dev/null
+++ b/apps/docs/src/demos/en/select/index.ts
@@ -0,0 +1,19 @@
+// Select demos
+export {AsynchronousLoading} from "./asynchronous-loading";
+export {Controlled} from "./controlled";
+export {ControlledMultiple} from "./controlled-multiple";
+export {ControlledOpenState} from "./controlled-open-state";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomRenderFunction} from "./custom-render-function";
+export {CustomValue} from "./custom-value";
+export {CustomValueMultiple} from "./custom-value-multiple";
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {MultipleSelect} from "./multiple-select";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {Variants} from "./variants";
+export {WithDescription} from "./with-description";
+export {WithDisabledOptions} from "./with-disabled-options";
+export {WithSections} from "./with-sections";
diff --git a/apps/docs/src/demos/en/select/multiple-select.tsx b/apps/docs/src/demos/en/select/multiple-select.tsx
new file mode 100644
index 0000000..b73cca0
--- /dev/null
+++ b/apps/docs/src/demos/en/select/multiple-select.tsx
@@ -0,0 +1,53 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function MultipleSelect() {
+  return (
+    <Select className="w-[256px]" placeholder="Select countries" selectionMode="multiple">
+      <Label>Countries to Visit</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox selectionMode="multiple">
+          <ListBox.Item id="argentina" textValue="Argentina">
+            Argentina
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="venezuela" textValue="Venezuela">
+            Venezuela
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="japan" textValue="Japan">
+            Japan
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="france" textValue="France">
+            France
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="italy" textValue="Italy">
+            Italy
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="spain" textValue="Spain">
+            Spain
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="thailand" textValue="Thailand">
+            Thailand
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-zealand" textValue="New Zealand">
+            New Zealand
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="iceland" textValue="Iceland">
+            Iceland
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/on-surface.tsx b/apps/docs/src/demos/en/select/on-surface.tsx
new file mode 100644
index 0000000..54f8ae7
--- /dev/null
+++ b/apps/docs/src/demos/en/select/on-surface.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import {Button, FieldError, Form, Label, ListBox, Select, Surface} from "@heroui/react";
+
+export function OnSurface() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Surface className="w-[320px] rounded-3xl p-6">
+      <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}>
+        <Select
+          isRequired
+          className="w-full"
+          name="state"
+          placeholder="Select one"
+          variant="secondary"
+        >
+          <Label>State</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="florida" textValue="Florida">
+                Florida
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="delaware" textValue="Delaware">
+                Delaware
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="california" textValue="California">
+                California
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="texas" textValue="Texas">
+                Texas
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="new-york" textValue="New York">
+                New York
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="washington" textValue="Washington">
+                Washington
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Select
+          isRequired
+          className="w-full"
+          name="country"
+          placeholder="Select a country"
+          variant="secondary"
+        >
+          <Label>Country</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="usa" textValue="United States">
+                United States
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="Canada">
+                Canada
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="mexico" textValue="Mexico">
+                Mexico
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="uk" textValue="United Kingdom">
+                United Kingdom
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="france" textValue="France">
+                France
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="Germany">
+                Germany
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Button type="submit">Submit</Button>
+      </Form>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/required.tsx b/apps/docs/src/demos/en/select/required.tsx
new file mode 100644
index 0000000..5a68580
--- /dev/null
+++ b/apps/docs/src/demos/en/select/required.tsx
@@ -0,0 +1,96 @@
+"use client";
+
+import {Button, FieldError, Form, Label, ListBox, Select} from "@heroui/react";
+
+export function Required() {
+  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const data: Record<string, string> = {};
+
+    // Convert FormData to plain object
+    formData.forEach((value, key) => {
+      data[key] = value.toString();
+    });
+
+    alert("Form submitted successfully!");
+  };
+
+  return (
+    <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+      <Select isRequired className="w-full" name="state" placeholder="Select one">
+        <Label>State</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="Delaware">
+              Delaware
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="Texas">
+              Texas
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="New York">
+              New York
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="Washington">
+              Washington
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+        <FieldError />
+      </Select>
+      <Select isRequired className="w-full" name="country" placeholder="Select a country">
+        <Label>Country</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="Mexico">
+              Mexico
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="Germany">
+              Germany
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+        <FieldError />
+      </Select>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/variants.tsx b/apps/docs/src/demos/en/select/variants.tsx
new file mode 100644
index 0000000..7924206
--- /dev/null
+++ b/apps/docs/src/demos/en/select/variants.tsx
@@ -0,0 +1,46 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Select className="w-[256px]" placeholder="Select one" variant="primary">
+        <Label>Primary variant</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="Option 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="Option 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select className="w-[256px]" placeholder="Select one" variant="secondary">
+        <Label>Secondary variant</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="Option 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="Option 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/with-description.tsx b/apps/docs/src/demos/en/select/with-description.tsx
new file mode 100644
index 0000000..b43125e
--- /dev/null
+++ b/apps/docs/src/demos/en/select/with-description.tsx
@@ -0,0 +1,42 @@
+import {Description, Label, ListBox, Select} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+      <Description>Select your state of residence</Description>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/with-disabled-options.tsx b/apps/docs/src/demos/en/select/with-disabled-options.tsx
new file mode 100644
index 0000000..751ad3c
--- /dev/null
+++ b/apps/docs/src/demos/en/select/with-disabled-options.tsx
@@ -0,0 +1,41 @@
+import {Label, ListBox, Select} from "@heroui/react";
+
+export function WithDisabledOptions() {
+  return (
+    <Select className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="Select an animal">
+      <Label>Animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="Bird">
+            Bird
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="Elephant">
+            Elephant
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="Tiger">
+            Tiger
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/select/with-sections.tsx b/apps/docs/src/demos/en/select/with-sections.tsx
new file mode 100644
index 0000000..aaebb8e
--- /dev/null
+++ b/apps/docs/src/demos/en/select/with-sections.tsx
@@ -0,0 +1,76 @@
+import {Header, Label, ListBox, Select, Separator} from "@heroui/react";
+
+export function WithSections() {
+  return (
+    <Select className="w-[256px]" placeholder="Select a country">
+      <Label>Country</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="Mexico">
+              Mexico
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="Germany">
+              Germany
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Asia</Header>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="China">
+              China
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="India">
+              India
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="South Korea">
+              South Korea
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/basic.tsx b/apps/docs/src/demos/en/separator/basic.tsx
new file mode 100644
index 0000000..c03376b
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/basic.tsx
@@ -0,0 +1,20 @@
+import {Separator} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="max-w-md">
+      <div className="space-y-1">
+        <h4 className="text-medium font-medium">HeroUI v3 Components</h4>
+        <p className="text-small text-default-400">Beautiful, fast and modern React UI library.</p>
+      </div>
+      <Separator className="my-4" />
+      <div className="text-small flex h-5 items-center space-x-4">
+        <div>Blog</div>
+        <Separator orientation="vertical" />
+        <div>Docs</div>
+        <Separator orientation="vertical" />
+        <div>Source</div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/custom-render-function.tsx b/apps/docs/src/demos/en/separator/custom-render-function.tsx
new file mode 100644
index 0000000..04d0e0d
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/custom-render-function.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Separator} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="max-w-md">
+      <div className="space-y-1">
+        <h4 className="text-medium font-medium">HeroUI v3 Components</h4>
+        <p className="text-small text-default-400">Beautiful, fast and modern React UI library.</p>
+      </div>
+      <Separator className="my-4" render={(props) => <div {...props} data-custom="foo" />} />
+      <div className="text-small flex h-5 items-center space-x-4">
+        <div>Blog</div>
+        <Separator
+          orientation="vertical"
+          render={(props) => <div {...props} data-custom="foo" />}
+        />
+        <div>Docs</div>
+        <Separator
+          orientation="vertical"
+          render={(props) => <div {...props} data-custom="foo" />}
+        />
+        <div>Source</div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/index.ts b/apps/docs/src/demos/en/separator/index.ts
new file mode 100644
index 0000000..88742b9
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {ManualVariantOverride} from "./manual-variant-override";
+export {WithSurface} from "./with-surface";
+export {Vertical} from "./vertical";
+export {WithContent} from "./with-content";
+export {Variants} from "./variants";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/separator/manual-variant-override.tsx b/apps/docs/src/demos/en/separator/manual-variant-override.tsx
new file mode 100644
index 0000000..658b3ba
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/manual-variant-override.tsx
@@ -0,0 +1,25 @@
+import {Separator, Surface} from "@heroui/react";
+
+export function ManualVariantOverride() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Separator on default surface</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <Separator />
+          <p className="text-sm text-muted">The separator adapts to the surface background.</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Separator on secondary surface</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <Separator />
+          <p className="text-sm text-muted">The separator adapts to the surface background.</p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/variants.tsx b/apps/docs/src/demos/en/separator/variants.tsx
new file mode 100644
index 0000000..c15aa51
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/variants.tsx
@@ -0,0 +1,14 @@
+import {Separator} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex max-w-md flex-col items-center gap-3">
+      <div>Default Variant</div>
+      <Separator variant="default" />
+      <div>Secondary Variant</div>
+      <Separator variant="secondary" />
+      <div>Tertiary Variant</div>
+      <Separator variant="tertiary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/vertical.tsx b/apps/docs/src/demos/en/separator/vertical.tsx
new file mode 100644
index 0000000..ed327c0
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/vertical.tsx
@@ -0,0 +1,13 @@
+import {Separator} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="text-small flex h-5 items-center space-x-4">
+      <div>Blog</div>
+      <Separator orientation="vertical" />
+      <div>Docs</div>
+      <Separator orientation="vertical" />
+      <div>Source</div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/with-content.tsx b/apps/docs/src/demos/en/separator/with-content.tsx
new file mode 100644
index 0000000..af1ed77
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/with-content.tsx
@@ -0,0 +1,39 @@
+import {Separator} from "@heroui/react";
+
+const items = [
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    subtitle: "Receive account activity updates",
+    title: "Set Up Notifications",
+  },
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    subtitle: "Connect your browser to your account",
+    title: "Set up Browser Extension",
+  },
+  {
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    subtitle: "Create your first collectible",
+    title: "Mint Collectible",
+  },
+];
+
+export function WithContent() {
+  return (
+    <div className="max-w-md space-y-4">
+      {items.map((item, index) => (
+        <div key={index}>
+          <div className="flex items-center gap-3">
+            <img alt={item.title} className="size-12" src={item.iconUrl} />
+            <div className="flex-1 space-y-0">
+              <h4 className="text-small font-medium">{item.title}</h4>
+              <p className="text-sm text-muted">{item.subtitle}</p>
+            </div>
+          </div>
+          {index < items.length - 1 && <Separator className="my-4" />}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/separator/with-surface.tsx b/apps/docs/src/demos/en/separator/with-surface.tsx
new file mode 100644
index 0000000..35bf8af
--- /dev/null
+++ b/apps/docs/src/demos/en/separator/with-surface.tsx
@@ -0,0 +1,42 @@
+import {Separator, Surface} from "@heroui/react";
+
+export function WithSurface() {
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">Default Surface</h3>
+          <Separator />
+          <p className="text-sm text-muted">Surface Content</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">Secondary Surface</h3>
+          <Separator variant="secondary" />
+          <p className="text-sm text-muted">Surface Content</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <h3 className="text-base font-semibold text-foreground">Tertiary Surface</h3>
+          <Separator variant="tertiary" />
+          <p className="text-sm text-muted">Surface Content</p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <h3 className="text-base font-semibold text-foreground">Transparent Surface</h3>
+          <Separator />
+          <p className="text-sm text-muted">Surface Content</p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/animation-types.tsx b/apps/docs/src/demos/en/skeleton/animation-types.tsx
new file mode 100644
index 0000000..1f5f08b
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/animation-types.tsx
@@ -0,0 +1,34 @@
+import {Skeleton} from "@heroui/react";
+
+export function AnimationTypes() {
+  return (
+    <div className="grid w-full max-w-xl grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">Shimmer</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="shimmer" className="h-20 rounded-lg" />
+          <Skeleton animationType="shimmer" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="shimmer" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">Pulse</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="pulse" className="h-20 rounded-lg" />
+          <Skeleton animationType="pulse" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="pulse" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        <p className="truncate text-xs text-muted">None</p>
+        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
+          <Skeleton animationType="none" className="h-20 rounded-lg" />
+          <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" />
+          <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/basic.tsx b/apps/docs/src/demos/en/skeleton/basic.tsx
new file mode 100644
index 0000000..cebdc71
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/basic.tsx
@@ -0,0 +1,14 @@
+import {Skeleton} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <div className="shadow-panel w-[250px] space-y-5 rounded-lg bg-transparent p-4">
+      <Skeleton className="h-32 rounded-lg" />
+      <div className="space-y-3">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+        <Skeleton className="h-3 w-2/5 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/card.tsx b/apps/docs/src/demos/en/skeleton/card.tsx
new file mode 100644
index 0000000..3d67932
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/card.tsx
@@ -0,0 +1,14 @@
+import {Skeleton} from "@heroui/react";
+
+export function Card() {
+  return (
+    <div className="bg-surface-1 shadow-panel w-[250px] space-y-5 rounded-lg p-4">
+      <Skeleton className="h-32 rounded-lg" />
+      <div className="space-y-3">
+        <Skeleton className="h-3 w-3/5 rounded-lg" />
+        <Skeleton className="h-3 w-4/5 rounded-lg" />
+        <Skeleton className="h-3 w-2/5 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/grid.tsx b/apps/docs/src/demos/en/skeleton/grid.tsx
new file mode 100644
index 0000000..53bce71
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/grid.tsx
@@ -0,0 +1,11 @@
+import {Skeleton} from "@heroui/react";
+
+export function Grid() {
+  return (
+    <div className="grid w-full max-w-xl grid-cols-3 gap-4">
+      <Skeleton className="h-24 rounded-xl" />
+      <Skeleton className="h-24 rounded-xl" />
+      <Skeleton className="h-24 rounded-xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/index.ts b/apps/docs/src/demos/en/skeleton/index.ts
new file mode 100644
index 0000000..94b1293
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/index.ts
@@ -0,0 +1,7 @@
+export {Basic} from "./basic";
+export {TextContent} from "./text-content";
+export {UserProfile} from "./user-profile";
+export {List} from "./list";
+export {AnimationTypes} from "./animation-types";
+export {Grid} from "./grid";
+export {SingleShimmer} from "./single-shimmer";
diff --git a/apps/docs/src/demos/en/skeleton/list.tsx b/apps/docs/src/demos/en/skeleton/list.tsx
new file mode 100644
index 0000000..e6872b1
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/list.tsx
@@ -0,0 +1,17 @@
+import {Skeleton} from "@heroui/react";
+
+export function List() {
+  return (
+    <div className="w-full max-w-sm space-y-4">
+      {Array.from({length: 3}).map((_, index) => (
+        <div key={index} className="flex items-center gap-3">
+          <Skeleton className="h-10 w-10 shrink-0 rounded-lg" />
+          <div className="flex-1 space-y-2">
+            <Skeleton className="h-3 w-full rounded" />
+            <Skeleton className="h-3 w-4/5 rounded" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/single-shimmer.tsx b/apps/docs/src/demos/en/skeleton/single-shimmer.tsx
new file mode 100644
index 0000000..1fa7317
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/single-shimmer.tsx
@@ -0,0 +1,11 @@
+import {Skeleton} from "@heroui/react";
+
+export function SingleShimmer() {
+  return (
+    <div className="skeleton--shimmer relative grid w-full max-w-xl grid-cols-3 gap-4 overflow-hidden rounded-xl">
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+      <Skeleton animationType="none" className="h-24 rounded-xl" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/text-content.tsx b/apps/docs/src/demos/en/skeleton/text-content.tsx
new file mode 100644
index 0000000..67c05ab
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/text-content.tsx
@@ -0,0 +1,13 @@
+import {Skeleton} from "@heroui/react";
+
+export function TextContent() {
+  return (
+    <div className="w-full max-w-md space-y-3">
+      <Skeleton className="h-4 w-full rounded" />
+      <Skeleton className="h-4 w-5/6 rounded" />
+      <Skeleton className="h-4 w-4/6 rounded" />
+      <Skeleton className="h-4 w-full rounded" />
+      <Skeleton className="h-4 w-3/6 rounded" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/skeleton/user-profile.tsx b/apps/docs/src/demos/en/skeleton/user-profile.tsx
new file mode 100644
index 0000000..7d465d7
--- /dev/null
+++ b/apps/docs/src/demos/en/skeleton/user-profile.tsx
@@ -0,0 +1,13 @@
+import {Skeleton} from "@heroui/react";
+
+export function UserProfile() {
+  return (
+    <div className="flex items-center gap-3">
+      <Skeleton className="h-10 w-10 shrink-0 rounded-full" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-3 w-36 rounded-lg" />
+        <Skeleton className="h-3 w-24 rounded-lg" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/slider/custom-render-function.tsx b/apps/docs/src/demos/en/slider/custom-render-function.tsx
new file mode 100644
index 0000000..526e004
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/custom-render-function.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+import {Label, Slider} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Slider
+      className="w-full max-w-xs"
+      defaultValue={30}
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/en/slider/default.tsx b/apps/docs/src/demos/en/slider/default.tsx
new file mode 100644
index 0000000..bf91f0a
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/default.tsx
@@ -0,0 +1,14 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Default() {
+  return (
+    <Slider className="w-full max-w-xs" defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/en/slider/disabled.tsx b/apps/docs/src/demos/en/slider/disabled.tsx
new file mode 100644
index 0000000..c060c31
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/disabled.tsx
@@ -0,0 +1,14 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Slider isDisabled className="w-full max-w-xs" defaultValue={30}>
+      <Label>Volume</Label>
+      <Slider.Output />
+      <Slider.Track>
+        <Slider.Fill />
+        <Slider.Thumb />
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/en/slider/index.ts b/apps/docs/src/demos/en/slider/index.ts
new file mode 100644
index 0000000..15c42a7
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/index.ts
@@ -0,0 +1,6 @@
+// Slider demos
+export {Default} from "./default";
+export {Disabled} from "./disabled";
+export {Range} from "./range";
+export {Vertical} from "./vertical";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/slider/range.tsx b/apps/docs/src/demos/en/slider/range.tsx
new file mode 100644
index 0000000..c3baf03
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/range.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Label, Slider} from "@heroui/react";
+
+export function Range() {
+  return (
+    <Slider
+      className="w-full max-w-xs"
+      defaultValue={[100, 500]}
+      formatOptions={{currency: "USD", style: "currency"}}
+      maxValue={1000}
+      minValue={0}
+      step={50}
+    >
+      <Label>Price Range</Label>
+      <Slider.Output />
+      <Slider.Track>
+        {({state}) => (
+          <>
+            <Slider.Fill />
+            {state.values.map((_, i) => (
+              <Slider.Thumb key={i} index={i} />
+            ))}
+          </>
+        )}
+      </Slider.Track>
+    </Slider>
+  );
+}
diff --git a/apps/docs/src/demos/en/slider/vertical.tsx b/apps/docs/src/demos/en/slider/vertical.tsx
new file mode 100644
index 0000000..4730d63
--- /dev/null
+++ b/apps/docs/src/demos/en/slider/vertical.tsx
@@ -0,0 +1,16 @@
+import {Label, Slider} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <div className="flex h-64 items-center justify-center">
+      <Slider className="h-full" defaultValue={30} orientation="vertical">
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/spinner/basic.tsx b/apps/docs/src/demos/en/spinner/basic.tsx
new file mode 100644
index 0000000..824479e
--- /dev/null
+++ b/apps/docs/src/demos/en/spinner/basic.tsx
@@ -0,0 +1,9 @@
+import {Spinner} from "@heroui/react";
+
+export function SpinnerBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Spinner />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/spinner/colors.tsx b/apps/docs/src/demos/en/spinner/colors.tsx
new file mode 100644
index 0000000..780f510
--- /dev/null
+++ b/apps/docs/src/demos/en/spinner/colors.tsx
@@ -0,0 +1,28 @@
+import {Spinner} from "@heroui/react";
+
+export function SpinnerColors() {
+  return (
+    <div className="flex items-center gap-8">
+      <div className="flex flex-col items-center gap-2">
+        <Spinner color="current" />
+        <span className="text-xs text-muted">Current</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner color="accent" />
+        <span className="text-xs text-muted">Accent</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner color="success" />
+        <span className="text-xs text-muted">Success</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner color="warning" />
+        <span className="text-xs text-muted">Warning</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner color="danger" />
+        <span className="text-xs text-muted">Danger</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/spinner/index.ts b/apps/docs/src/demos/en/spinner/index.ts
new file mode 100644
index 0000000..3dfa394
--- /dev/null
+++ b/apps/docs/src/demos/en/spinner/index.ts
@@ -0,0 +1,3 @@
+export {SpinnerBasic as Basic} from "./basic";
+export {SpinnerColors as Colors} from "./colors";
+export {SpinnerSizes as Sizes} from "./sizes";
diff --git a/apps/docs/src/demos/en/spinner/sizes.tsx b/apps/docs/src/demos/en/spinner/sizes.tsx
new file mode 100644
index 0000000..297a482
--- /dev/null
+++ b/apps/docs/src/demos/en/spinner/sizes.tsx
@@ -0,0 +1,24 @@
+import {Spinner} from "@heroui/react";
+
+export function SpinnerSizes() {
+  return (
+    <div className="flex items-center gap-8">
+      <div className="flex flex-col items-center gap-2">
+        <Spinner size="sm" />
+        <span className="text-xs text-muted">Small</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner size="md" />
+        <span className="text-xs text-muted">Medium</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner size="lg" />
+        <span className="text-xs text-muted">Large</span>
+      </div>
+      <div className="flex flex-col items-center gap-2">
+        <Spinner size="xl" />
+        <span className="text-xs text-muted">Extra Large</span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/surface/index.ts b/apps/docs/src/demos/en/surface/index.ts
new file mode 100644
index 0000000..6dcf15e
--- /dev/null
+++ b/apps/docs/src/demos/en/surface/index.ts
@@ -0,0 +1 @@
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/surface/variants.tsx b/apps/docs/src/demos/en/surface/variants.tsx
new file mode 100644
index 0000000..f5dd6d6
--- /dev/null
+++ b/apps/docs/src/demos/en/surface/variants.tsx
@@ -0,0 +1,51 @@
+import {Surface} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Default</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <p className="text-sm text-muted">
+            This is a default surface variant. It uses bg-surface styling.
+          </p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <p className="text-sm text-muted">
+            This is a secondary surface variant. It uses bg-surface-secondary styling.
+          </p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Tertiary</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <p className="text-sm text-muted">
+            This is a tertiary surface variant. It uses bg-surface-tertiary styling.
+          </p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Transparent</p>
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <p className="text-sm text-muted">
+            This is a transparent surface variant. It has no background, suitable for overlays and
+            cards with custom backgrounds.
+          </p>
+        </Surface>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/basic.tsx b/apps/docs/src/demos/en/switch/basic.tsx
new file mode 100644
index 0000000..da8da68
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/basic.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/controlled.tsx b/apps/docs/src/demos/en/switch/controlled.tsx
new file mode 100644
index 0000000..4a44795
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/controlled.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = React.useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <Switch isSelected={isSelected} onChange={setIsSelected}>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Enable notifications
+        </Switch.Content>
+      </Switch>
+      <p className="text-sm text-muted">Switch is {isSelected ? "on" : "off"}</p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/custom-render-function.tsx b/apps/docs/src/demos/en/switch/custom-render-function.tsx
new file mode 100644
index 0000000..263ed80
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/custom-render-function.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <Switch render={(props) => <div {...props} data-custom="foo" />}>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/custom-styles.tsx b/apps/docs/src/demos/en/switch/custom-styles.tsx
new file mode 100644
index 0000000..fddab3b
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/custom-styles.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import {Check, Power} from "@gravity-ui/icons";
+import {Switch} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Switch aria-label="Power">
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control
+            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
+          >
+            <Switch.Thumb
+              className={`size-[27px] bg-white shadow-sm ${isSelected ? "ms-[22px] shadow-lg" : ""}`}
+            >
+              <Switch.Icon>
+                {isSelected ? (
+                  <Check className="size-4 text-cyan-600" />
+                ) : (
+                  <Power className="size-4 text-blue-600" />
+                )}
+              </Switch.Icon>
+            </Switch.Thumb>
+          </Switch.Control>
+        </Switch.Content>
+      )}
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/default-selected.tsx b/apps/docs/src/demos/en/switch/default-selected.tsx
new file mode 100644
index 0000000..2731e98
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/default-selected.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function DefaultSelected() {
+  return (
+    <Switch defaultSelected>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/disabled.tsx b/apps/docs/src/demos/en/switch/disabled.tsx
new file mode 100644
index 0000000..5dc2aee
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/disabled.tsx
@@ -0,0 +1,14 @@
+import {Switch} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Switch isDisabled>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/form.tsx b/apps/docs/src/demos/en/switch/form.tsx
new file mode 100644
index 0000000..b2c6d23
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/form.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import {Button, Switch, SwitchGroup} from "@heroui/react";
+import React from "react";
+
+export function Form() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+
+    alert(
+      `Form submitted with:\n${Array.from(formData.entries())
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n")}`,
+    );
+  };
+
+  return (
+    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+      <SwitchGroup>
+        <Switch name="notifications" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Enable notifications
+          </Switch.Content>
+        </Switch>
+        <Switch defaultSelected name="newsletter" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Subscribe to newsletter
+          </Switch.Content>
+        </Switch>
+        <Switch name="marketing" value="on">
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Receive marketing updates
+          </Switch.Content>
+        </Switch>
+      </SwitchGroup>
+      <Button className="mt-4" size="sm" type="submit" variant="primary">
+        Submit
+      </Button>
+    </form>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/group-horizontal.tsx b/apps/docs/src/demos/en/switch/group-horizontal.tsx
new file mode 100644
index 0000000..b1df7fb
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/group-horizontal.tsx
@@ -0,0 +1,32 @@
+import {Switch, SwitchGroup} from "@heroui/react";
+
+export function GroupHorizontal() {
+  return (
+    <SwitchGroup className="overflow-x-auto" orientation="horizontal">
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Social
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/group.tsx b/apps/docs/src/demos/en/switch/group.tsx
new file mode 100644
index 0000000..2f4ffb7
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/group.tsx
@@ -0,0 +1,32 @@
+import {Switch, SwitchGroup} from "@heroui/react";
+
+export function Group() {
+  return (
+    <SwitchGroup>
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Allow Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing emails
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Social media updates
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/index.ts b/apps/docs/src/demos/en/switch/index.ts
new file mode 100644
index 0000000..3381efe
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/index.ts
@@ -0,0 +1,15 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomStyles} from "./custom-styles";
+export {CustomRenderFunction} from "./custom-render-function";
+export {DefaultSelected} from "./default-selected";
+export {Disabled} from "./disabled";
+export {Form} from "./form";
+export {Group} from "./group";
+export {GroupHorizontal} from "./group-horizontal";
+export {LabelPosition} from "./label-position";
+export {RenderProps} from "./render-props";
+export {Sizes} from "./sizes";
+export {WithDescription} from "./with-description";
+export {WithIcons} from "./with-icons";
+export {WithoutLabel} from "./without-label";
diff --git a/apps/docs/src/demos/en/switch/label-position.tsx b/apps/docs/src/demos/en/switch/label-position.tsx
new file mode 100644
index 0000000..a03a2ec
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/label-position.tsx
@@ -0,0 +1,24 @@
+import {Switch} from "@heroui/react";
+
+export function LabelPosition() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Label after
+        </Switch.Content>
+      </Switch>
+      <Switch>
+        <Switch.Content>
+          Label before
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </Switch.Content>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/render-props.tsx b/apps/docs/src/demos/en/switch/render-props.tsx
new file mode 100644
index 0000000..a71a889
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/render-props.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Switch} from "@heroui/react";
+
+export function RenderProps() {
+  return (
+    <Switch>
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          {isSelected ? "Enabled" : "Disabled"}
+        </Switch.Content>
+      )}
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/sizes.tsx b/apps/docs/src/demos/en/switch/sizes.tsx
new file mode 100644
index 0000000..efb6678
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/sizes.tsx
@@ -0,0 +1,32 @@
+import {Switch} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex gap-6">
+      <Switch size="sm">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Small
+        </Switch.Content>
+      </Switch>
+      <Switch size="md">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Medium
+        </Switch.Content>
+      </Switch>
+      <Switch size="lg">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Large
+        </Switch.Content>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/with-description.tsx b/apps/docs/src/demos/en/switch/with-description.tsx
new file mode 100644
index 0000000..79f59ce
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/with-description.tsx
@@ -0,0 +1,17 @@
+import {Description, Switch} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="max-w-sm">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Public profile
+        </Switch.Content>
+        <Description>Allow others to see your profile information</Description>
+      </Switch>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/with-icons.tsx b/apps/docs/src/demos/en/switch/with-icons.tsx
new file mode 100644
index 0000000..1174bfb
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/with-icons.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import {
+  BellFill,
+  BellSlash,
+  Check,
+  Microphone,
+  MicrophoneSlash,
+  Moon,
+  Power,
+  Sun,
+  VolumeFill,
+  VolumeSlashFill,
+} from "@gravity-ui/icons";
+import {Switch} from "@heroui/react";
+
+export function WithIcons() {
+  const icons = {
+    check: {
+      off: Power,
+      on: Check,
+      selectedControlClass: "bg-green-500/80",
+    },
+    darkMode: {
+      off: Moon,
+      on: Sun,
+      selectedControlClass: "",
+    },
+    microphone: {
+      off: Microphone,
+      on: MicrophoneSlash,
+      selectedControlClass: "bg-red-500/80",
+    },
+    notification: {
+      off: BellSlash,
+      on: BellFill,
+      selectedControlClass: "bg-purple-500/80",
+    },
+    volume: {
+      off: VolumeFill,
+      on: VolumeSlashFill,
+      selectedControlClass: "bg-blue-500/80",
+    },
+  };
+
+  return (
+    <div className="flex gap-3">
+      {Object.entries(icons).map(([key, value]) => (
+        <Switch key={key} defaultSelected aria-label={key} size="lg">
+          {({isSelected}) => (
+            <Switch.Content>
+              <Switch.Control className={isSelected ? value.selectedControlClass : ""}>
+                <Switch.Thumb>
+                  <Switch.Icon>
+                    {isSelected ? (
+                      <value.on className="size-3 text-inherit opacity-100" />
+                    ) : (
+                      <value.off className="size-3 text-inherit opacity-70" />
+                    )}
+                  </Switch.Icon>
+                </Switch.Thumb>
+              </Switch.Control>
+            </Switch.Content>
+          )}
+        </Switch>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/switch/without-label.tsx b/apps/docs/src/demos/en/switch/without-label.tsx
new file mode 100644
index 0000000..5228ef5
--- /dev/null
+++ b/apps/docs/src/demos/en/switch/without-label.tsx
@@ -0,0 +1,13 @@
+import {Switch} from "@heroui/react";
+
+export function WithoutLabel() {
+  return (
+    <Switch aria-label="Enable notifications">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/async-loading.tsx b/apps/docs/src/demos/en/table/async-loading.tsx
new file mode 100644
index 0000000..fa6fb1e
--- /dev/null
+++ b/apps/docs/src/demos/en/table/async-loading.tsx
@@ -0,0 +1,161 @@
+"use client";
+
+import {Chip, Spinner, Table} from "@heroui/react";
+import {useCallback, useRef, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: string;
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  Active: "success",
+  Inactive: "danger",
+  "On Leave": "warning",
+};
+
+const allUsers: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "CEO", status: "Active"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "CTO", status: "Active"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "CMO", status: "On Leave"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "CFO", status: "Active"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "Lead Designer", status: "Active"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "Backend Engineer",
+    status: "Active",
+  },
+  {
+    email: "sophia@acme.com",
+    id: 9,
+    name: "Sophia Anderson",
+    role: "QA Engineer",
+    status: "On Leave",
+  },
+  {email: "liam@acme.com", id: 10, name: "Liam Thomas", role: "DevOps Engineer", status: "Active"},
+  {
+    email: "lucas@acme.com",
+    id: 11,
+    name: "Lucas Martinez",
+    role: "Product Manager",
+    status: "Active",
+  },
+  {
+    email: "emma@acme.com",
+    id: 12,
+    name: "Emma Johnson",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {email: "noah@acme.com", id: 13, name: "Noah Davis", role: "Backend Engineer", status: "Active"},
+  {email: "ava@acme.com", id: 14, name: "Ava Wilson", role: "Lead Designer", status: "Active"},
+  {
+    email: "oliver@acme.com",
+    id: 15,
+    name: "Oliver Martinez",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {
+    email: "isabella@acme.com",
+    id: 16,
+    name: "Isabella Johnson",
+    role: "Backend Engineer",
+    status: "Active",
+  },
+  {email: "mia@acme.com", id: 17, name: "Mia Davis", role: "Lead Designer", status: "Active"},
+  {
+    email: "william@acme.com",
+    id: 18,
+    name: "William Wilson",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+];
+
+const ITEMS_PER_PAGE = 6;
+
+const columns = [
+  {id: "name", name: "Name"},
+  {id: "role", name: "Role"},
+  {id: "status", name: "Status"},
+  {id: "email", name: "Email"},
+];
+
+export function AsyncLoading() {
+  const [items, setItems] = useState<User[]>(() => allUsers.slice(0, ITEMS_PER_PAGE));
+  const [isLoading, setIsLoading] = useState(false);
+  const isLoadingRef = useRef(false);
+  const hasMore = items.length < allUsers.length;
+
+  const loadMore = useCallback(() => {
+    if (!hasMore || isLoadingRef.current) return;
+    isLoadingRef.current = true;
+    setIsLoading(true);
+    setTimeout(() => {
+      setItems((prev) => allUsers.slice(0, prev.length + ITEMS_PER_PAGE));
+      setIsLoading(false);
+      requestAnimationFrame(() => {
+        isLoadingRef.current = false;
+      });
+    }, 1500);
+  }, [hasMore]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer className="h-[280px] overflow-y-auto">
+        <Table.Content aria-label="Async loading table" className="min-w-[600px]">
+          <Table.Header className="sticky top-0 z-10 bg-surface-secondary">
+            {columns.map((col) => (
+              <Table.Column key={col.id} id={col.id} isRowHeader={col.id === "name"}>
+                {col.name}
+              </Table.Column>
+            ))}
+          </Table.Header>
+          <Table.Body>
+            <Table.Collection items={items}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>
+                    <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                      {user.status}
+                    </Chip>
+                  </Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              )}
+            </Table.Collection>
+            {!!hasMore && (
+              <Table.LoadMore isLoading={isLoading} scrollOffset={0} onLoadMore={loadMore}>
+                <Table.LoadMoreContent>
+                  <Spinner size="md" />
+                </Table.LoadMoreContent>
+              </Table.LoadMore>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/basic.tsx b/apps/docs/src/demos/en/table/basic.tsx
new file mode 100644
index 0000000..edc8f89
--- /dev/null
+++ b/apps/docs/src/demos/en/table/basic.tsx
@@ -0,0 +1,44 @@
+import {Table} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Team members" className="min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+            <Table.Column>Status</Table.Column>
+            <Table.Column>Email</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>CTO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>CMO</Table.Cell>
+              <Table.Cell>On Leave</Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>CFO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/column-resizing.tsx b/apps/docs/src/demos/en/table/column-resizing.tsx
new file mode 100644
index 0000000..76774d2
--- /dev/null
+++ b/apps/docs/src/demos/en/table/column-resizing.tsx
@@ -0,0 +1,81 @@
+import {Chip, Table} from "@heroui/react";
+
+export function ColumnResizing() {
+  return (
+    <Table>
+      <Table.ResizableContainer>
+        <Table.Content aria-label="Table with resizable columns" className="min-w-[700px]">
+          <Table.Header>
+            <Table.Column isRowHeader defaultWidth="1fr" id="name" minWidth={160}>
+              Name
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="role" minWidth={220}>
+              Role
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="status" minWidth={100}>
+              Status
+              <Table.ColumnResizer />
+            </Table.Column>
+            <Table.Column defaultWidth="1fr" id="email" minWidth={200}>
+              Email
+            </Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>CTO</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>CMO</Table.Cell>
+              <Table.Cell>
+                <Chip color="warning" size="sm" variant="soft">
+                  On Leave
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>CFO</Table.Cell>
+              <Table.Cell>
+                <Chip color="success" size="sm" variant="soft">
+                  Active
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Emily Davis</Table.Cell>
+              <Table.Cell>Product Manager</Table.Cell>
+              <Table.Cell>
+                <Chip color="danger" size="sm" variant="soft">
+                  Inactive
+                </Chip>
+              </Table.Cell>
+              <Table.Cell>emily@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ResizableContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/custom-cells.tsx b/apps/docs/src/demos/en/table/custom-cells.tsx
new file mode 100644
index 0000000..0e2eeb5
--- /dev/null
+++ b/apps/docs/src/demos/en/table/custom-cells.tsx
@@ -0,0 +1,204 @@
+"use client";
+
+import type {Selection, SortDescriptor} from "@heroui/react";
+
+import {Avatar, Button, Checkbox, Chip, Table} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  image_url: string;
+  role: string;
+  status: "Active" | "Inactive" | "On Leave";
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  Active: "success",
+  Inactive: "danger",
+  "On Leave": "warning",
+};
+
+const users: User[] = [
+  {
+    email: "kate@acme.com",
+    id: 4586932,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "Kate Moore",
+    role: "Chief Executive Officer",
+    status: "Active",
+  },
+  {
+    email: "john@acme.com",
+    id: 5273849,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "John Smith",
+    role: "Chief Technology Officer",
+    status: "Active",
+  },
+  {
+    email: "sara@acme.com",
+    id: 7492836,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Sara Johnson",
+    role: "Chief Marketing Officer",
+    status: "On Leave",
+  },
+  {
+    email: "michael@acme.com",
+    id: 8293746,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "Michael Brown",
+    role: "Chief Financial Officer",
+    status: "Active",
+  },
+  {
+    email: "emily@acme.com",
+    id: 1234567,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+];
+
+export function CustomCells() {
+  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+  const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const sortedUsers = useMemo(() => {
+    return [...users].sort((a, b) => {
+      const col = sortDescriptor.column as keyof User;
+      const first = String(a[col]);
+      const second = String(b[col]);
+      let cmp = first.localeCompare(second);
+
+      if (sortDescriptor.direction === "descending") {
+        cmp *= -1;
+      }
+
+      return cmp;
+    });
+  }, [sortDescriptor]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Table with custom cells"
+          className="min-w-[800px]"
+          selectedKeys={selectedKeys}
+          selectionMode="multiple"
+          sortDescriptor={sortDescriptor}
+          onSelectionChange={setSelectedKeys}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column className="pr-0">
+              <Checkbox aria-label="Select all" slot="selection">
+                <Checkbox.Content>
+                  <Checkbox.Control>
+                    <Checkbox.Indicator />
+                  </Checkbox.Control>
+                </Checkbox.Content>
+              </Checkbox>
+            </Table.Column>
+            <Table.Column allowsSorting isRowHeader className="after:hidden" id="id">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Worker ID
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="name">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Member
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="role">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Role
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="status">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Status
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column className="text-end">Actions</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            {sortedUsers.map((user) => (
+              <Table.Row key={user.id} id={user.id}>
+                <Table.Cell className="pr-0">
+                  <Checkbox aria-label={`Select ${user.name}`} slot="selection" variant="secondary">
+                    <Checkbox.Content>
+                      <Checkbox.Control>
+                        <Checkbox.Indicator />
+                      </Checkbox.Control>
+                    </Checkbox.Content>
+                  </Checkbox>
+                </Table.Cell>
+                <Table.Cell className="font-medium">
+                  <div className="flex items-center gap-2">
+                    #{user.id.toString()}{" "}
+                    <Button isIconOnly size="sm" variant="ghost">
+                      <Icon className="size-4 text-muted" icon="gravity-ui:copy" />
+                    </Button>
+                  </div>
+                </Table.Cell>
+                <Table.Cell>
+                  <div className="flex items-center gap-3">
+                    <Avatar size="sm">
+                      <Avatar.Image src={user.image_url} />
+                      <Avatar.Fallback>
+                        {user.name
+                          .split(" ")
+                          .map((n) => n[0])
+                          .join("")}
+                      </Avatar.Fallback>
+                    </Avatar>
+                    <div className="flex flex-col">
+                      <span className="text-xs">{user.name}</span>
+                      <span className="text-xs text-muted">{user.email}</span>
+                    </div>
+                  </div>
+                </Table.Cell>
+                <Table.Cell className="min-w-52">{user.role}</Table.Cell>
+                <Table.Cell className="min-w-25">
+                  <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                    {user.status}
+                  </Chip>
+                </Table.Cell>
+                <Table.Cell>
+                  <div className="flex items-center gap-1">
+                    <Button isIconOnly size="sm" variant="tertiary">
+                      <Icon className="size-4" icon="gravity-ui:eye" />
+                    </Button>
+                    <Button isIconOnly size="sm" variant="tertiary">
+                      <Icon className="size-4" icon="gravity-ui:pencil" />
+                    </Button>
+                    <Button isIconOnly size="sm" variant="danger-soft">
+                      <Icon className="size-4" icon="gravity-ui:trash-bin" />
+                    </Button>
+                  </div>
+                </Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/empty-state.tsx b/apps/docs/src/demos/en/table/empty-state.tsx
new file mode 100644
index 0000000..9e24df8
--- /dev/null
+++ b/apps/docs/src/demos/en/table/empty-state.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {EmptyState, Table} from "@heroui/react";
+import {Icon} from "@iconify/react";
+
+export function EmptyStateDemo() {
+  return (
+    <Table className="min-h-[200px]">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Empty table" className="h-full min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+            <Table.Column>Status</Table.Column>
+            <Table.Column>Email</Table.Column>
+          </Table.Header>
+          <Table.Body
+            renderEmptyState={() => (
+              <EmptyState className="flex h-full w-full flex-col items-center justify-center gap-4 text-center">
+                <Icon className="size-6 text-muted" icon="gravity-ui:tray" />
+                <span className="text-sm text-muted">No results found</span>
+              </EmptyState>
+            )}
+          >
+            {[]}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/expandable-rows.tsx b/apps/docs/src/demos/en/table/expandable-rows.tsx
new file mode 100644
index 0000000..f98889b
--- /dev/null
+++ b/apps/docs/src/demos/en/table/expandable-rows.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Button, Table, cn} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import {useState} from "react";
+
+export function ExpandableRows() {
+  type Row = {
+    children: Row[];
+    date: string;
+    id: string;
+    title: string;
+    type: string;
+  };
+
+  const data: Row[] = [
+    {
+      children: [
+        {
+          children: [
+            {children: [], date: "7/10/2025", id: "3", title: "Weekly Report", type: "File"},
+            {children: [], date: "8/20/2025", id: "4", title: "Budget", type: "File"},
+          ],
+          date: "8/2/2025",
+          id: "2",
+          title: "Project",
+          type: "Directory",
+        },
+      ],
+      date: "10/20/2025",
+      id: "1",
+      title: "Documents",
+      type: "Directory",
+    },
+    {
+      children: [
+        {children: [], date: "1/23/2026", id: "6", title: "Image 1", type: "File"},
+        {children: [], date: "2/3/2026", id: "7", title: "Image 2", type: "File"},
+      ],
+      date: "2/3/2026",
+      id: "5",
+      title: "Photos",
+      type: "Directory",
+    },
+  ];
+
+  const [expandedKeys, setExpandedKeys] = useState<Selection>(() => new Set(["1"]));
+
+  const renderExpandableRow = (item: Row) => {
+    return (
+      <Table.Row id={item.id} textValue={item.title}>
+        <Table.Cell textValue={item.title}>
+          {({hasChildItems, isDisabled, isExpanded, isTreeColumn}) => (
+            <span className="flex items-center gap-1">
+              {hasChildItems && isTreeColumn ? (
+                <Button
+                  isIconOnly
+                  aria-label="Toggle row"
+                  isDisabled={isDisabled}
+                  size="sm"
+                  slot="chevron"
+                  variant="ghost"
+                >
+                  <Icon
+                    aria-hidden
+                    icon="gravity-ui:chevron-right"
+                    className={cn(
+                      "size-4 text-muted transition-transform duration-150",
+                      isExpanded ? "rotate-90" : "",
+                    )}
+                  />
+                </Button>
+              ) : null}
+              <span>{item.title}</span>
+            </span>
+          )}
+        </Table.Cell>
+        <Table.Cell>{item.type}</Table.Cell>
+        <Table.Cell>{item.date}</Table.Cell>
+        <Table.Collection items={item.children}>{renderExpandableRow}</Table.Collection>
+      </Table.Row>
+    );
+  };
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Files"
+          className="min-w-[520px]"
+          expandedKeys={expandedKeys}
+          treeColumn="name"
+          onExpandedChange={setExpandedKeys}
+        >
+          <Table.Header>
+            <Table.Column isRowHeader id="name">
+              Name
+            </Table.Column>
+            <Table.Column id="type">Type</Table.Column>
+            <Table.Column id="date">Date Modified</Table.Column>
+          </Table.Header>
+          <Table.Body items={data}>{renderExpandableRow}</Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/index.ts b/apps/docs/src/demos/en/table/index.ts
new file mode 100644
index 0000000..35f7fd3
--- /dev/null
+++ b/apps/docs/src/demos/en/table/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {SecondaryVariant} from "./secondary-variant";
+export {Sorting} from "./sorting";
+export {SelectionDemo} from "./selection";
+export {EmptyStateDemo} from "./empty-state";
+export {ColumnResizing} from "./column-resizing";
+export {AsyncLoading} from "./async-loading";
+export {CustomCells} from "./custom-cells";
+export {ExpandableRows} from "./expandable-rows";
+export {PaginationDemo} from "./pagination";
+export {Virtualization} from "./virtualization";
+export {TanstackTable} from "./tanstack-table";
diff --git a/apps/docs/src/demos/en/table/pagination.tsx b/apps/docs/src/demos/en/table/pagination.tsx
new file mode 100644
index 0000000..cfd7c85
--- /dev/null
+++ b/apps/docs/src/demos/en/table/pagination.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import {Pagination, Table} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+const columns = [
+  {id: "name", name: "Name"},
+  {id: "role", name: "Role"},
+  {id: "status", name: "Status"},
+  {id: "email", name: "Email"},
+];
+
+const users = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "CEO", status: "Active"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "CTO", status: "Active"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "CMO", status: "On Leave"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "CFO", status: "Active"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "Lead Designer", status: "Active"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "Backend Engineer",
+    status: "Active",
+  },
+];
+
+const ROWS_PER_PAGE = 4;
+
+export function PaginationDemo() {
+  const [page, setPage] = useState(1);
+  const totalPages = Math.ceil(users.length / ROWS_PER_PAGE);
+  const pages = Array.from({length: totalPages}, (_, i) => i + 1);
+
+  const paginatedItems = useMemo(() => {
+    const start = (page - 1) * ROWS_PER_PAGE;
+
+    return users.slice(start, start + ROWS_PER_PAGE);
+  }, [page]);
+
+  const start = (page - 1) * ROWS_PER_PAGE + 1;
+  const end = Math.min(page * ROWS_PER_PAGE, users.length);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Table with pagination" className="min-w-[600px]">
+          <Table.Header columns={columns}>
+            {(column) => (
+              <Table.Column isRowHeader={column.id === "name"}>{column.name}</Table.Column>
+            )}
+          </Table.Header>
+          <Table.Body items={paginatedItems}>
+            {(user) => (
+              <Table.Row>
+                <Table.Collection items={columns}>
+                  {(column) => <Table.Cell>{user[column.id as keyof typeof user]}</Table.Cell>}
+                </Table.Collection>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        <Pagination size="sm">
+          <Pagination.Summary>
+            {start} to {end} of {users.length} results
+          </Pagination.Summary>
+          <Pagination.Content>
+            <Pagination.Item>
+              <Pagination.Previous
+                isDisabled={page === 1}
+                onPress={() => setPage((p) => Math.max(1, p - 1))}
+              >
+                <Pagination.PreviousIcon />
+                Prev
+              </Pagination.Previous>
+            </Pagination.Item>
+            {pages.map((p) => (
+              <Pagination.Item key={p}>
+                <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ))}
+            <Pagination.Item>
+              <Pagination.Next
+                isDisabled={page === totalPages}
+                onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+              >
+                Next
+                <Pagination.NextIcon />
+              </Pagination.Next>
+            </Pagination.Item>
+          </Pagination.Content>
+        </Pagination>
+      </Table.Footer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/secondary-variant.tsx b/apps/docs/src/demos/en/table/secondary-variant.tsx
new file mode 100644
index 0000000..ffe44a0
--- /dev/null
+++ b/apps/docs/src/demos/en/table/secondary-variant.tsx
@@ -0,0 +1,44 @@
+import {Table} from "@heroui/react";
+
+export function SecondaryVariant() {
+  return (
+    <Table variant="secondary">
+      <Table.ScrollContainer>
+        <Table.Content aria-label="Team members" className="min-w-[600px]">
+          <Table.Header>
+            <Table.Column isRowHeader>Name</Table.Column>
+            <Table.Column>Role</Table.Column>
+            <Table.Column>Status</Table.Column>
+            <Table.Column>Email</Table.Column>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Kate Moore</Table.Cell>
+              <Table.Cell>CEO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>kate@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>John Smith</Table.Cell>
+              <Table.Cell>CTO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>john@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Sara Johnson</Table.Cell>
+              <Table.Cell>CMO</Table.Cell>
+              <Table.Cell>On Leave</Table.Cell>
+              <Table.Cell>sara@acme.com</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Michael Brown</Table.Cell>
+              <Table.Cell>CFO</Table.Cell>
+              <Table.Cell>Active</Table.Cell>
+              <Table.Cell>michael@acme.com</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/selection.tsx b/apps/docs/src/demos/en/table/selection.tsx
new file mode 100644
index 0000000..d4cf55e
--- /dev/null
+++ b/apps/docs/src/demos/en/table/selection.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import type {Selection} from "@heroui/react";
+
+import {Checkbox, Table} from "@heroui/react";
+import {useState} from "react";
+
+const users = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "CEO", status: "Active"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "CTO", status: "Active"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "CMO", status: "On Leave"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "CFO", status: "Active"},
+];
+
+export function SelectionDemo() {
+  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+
+  return (
+    <div className="flex flex-col gap-3">
+      <Table>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="Table with selection"
+            className="min-w-[600px]"
+            selectedKeys={selectedKeys}
+            selectionMode="multiple"
+            onSelectionChange={setSelectedKeys}
+          >
+            <Table.Header>
+              <Table.Column className="pr-0">
+                <Checkbox aria-label="Select all" slot="selection">
+                  <Checkbox.Content>
+                    <Checkbox.Control>
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                  </Checkbox.Content>
+                </Checkbox>
+              </Table.Column>
+              <Table.Column isRowHeader>Name</Table.Column>
+              <Table.Column>Role</Table.Column>
+              <Table.Column>Status</Table.Column>
+              <Table.Column>Email</Table.Column>
+            </Table.Header>
+            <Table.Body>
+              {users.map((user) => (
+                <Table.Row key={user.id} id={user.id}>
+                  <Table.Cell className="pr-0">
+                    <Checkbox
+                      aria-label={`Select ${user.name}`}
+                      slot="selection"
+                      variant="secondary"
+                    >
+                      <Checkbox.Content>
+                        <Checkbox.Control>
+                          <Checkbox.Indicator />
+                        </Checkbox.Control>
+                      </Checkbox.Content>
+                    </Checkbox>
+                  </Table.Cell>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>{user.status}</Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              ))}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+      </Table>
+      <p className="text-sm text-muted">
+        Selected:{" "}
+        <span className="font-medium">
+          {selectedKeys === "all"
+            ? "All"
+            : selectedKeys.size > 0
+              ? Array.from(selectedKeys).join(", ")
+              : "None"}
+        </span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/sorting.tsx b/apps/docs/src/demos/en/table/sorting.tsx
new file mode 100644
index 0000000..dbf61c8
--- /dev/null
+++ b/apps/docs/src/demos/en/table/sorting.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import type {SortDescriptor} from "@heroui/react";
+
+import {Table} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: string;
+  email: string;
+}
+
+const users: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "CEO", status: "Active"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "CTO", status: "Active"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "CMO", status: "On Leave"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "CFO", status: "Active"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+];
+
+export function Sorting() {
+  const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const sortedUsers = useMemo(() => {
+    return [...users].sort((a, b) => {
+      const col = sortDescriptor.column as keyof User;
+      const first = String(a[col]);
+      const second = String(b[col]);
+      let cmp = first.localeCompare(second);
+
+      if (sortDescriptor.direction === "descending") {
+        cmp *= -1;
+      }
+
+      return cmp;
+    });
+  }, [sortDescriptor]);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="Sortable table"
+          className="min-w-[600px]"
+          sortDescriptor={sortDescriptor}
+          onSortChange={setSortDescriptor}
+        >
+          <Table.Header>
+            <Table.Column allowsSorting isRowHeader id="name">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Name
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="role">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Role
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="status">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Status
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+            <Table.Column allowsSorting id="email">
+              {({sortDirection}) => (
+                <Table.SortableColumnHeader sortDirection={sortDirection}>
+                  Email
+                </Table.SortableColumnHeader>
+              )}
+            </Table.Column>
+          </Table.Header>
+          <Table.Body>
+            {sortedUsers.map((user) => (
+              <Table.Row key={user.id} id={user.id}>
+                <Table.Cell>{user.name}</Table.Cell>
+                <Table.Cell>{user.role}</Table.Cell>
+                <Table.Cell>{user.status}</Table.Cell>
+                <Table.Cell>{user.email}</Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/tanstack-table.tsx b/apps/docs/src/demos/en/table/tanstack-table.tsx
new file mode 100644
index 0000000..7ad2bec
--- /dev/null
+++ b/apps/docs/src/demos/en/table/tanstack-table.tsx
@@ -0,0 +1,199 @@
+"use client";
+
+import type {SortDescriptor} from "@heroui/react";
+import type {SortingState} from "@tanstack/react-table";
+
+import {Chip, Pagination, Table} from "@heroui/react";
+import {
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import {useMemo, useState} from "react";
+
+// --- Data -----------------------------------------------------------------
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  status: "Active" | "Inactive" | "On Leave";
+  email: string;
+}
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  Active: "success",
+  Inactive: "danger",
+  "On Leave": "warning",
+};
+
+const users: User[] = [
+  {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "CEO", status: "Active"},
+  {email: "john@acme.com", id: 2, name: "John Smith", role: "CTO", status: "Active"},
+  {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "CMO", status: "On Leave"},
+  {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "CFO", status: "Active"},
+  {
+    email: "emily@acme.com",
+    id: 5,
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+  {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "Lead Designer", status: "Active"},
+  {
+    email: "olivia@acme.com",
+    id: 7,
+    name: "Olivia Martinez",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {
+    email: "james@acme.com",
+    id: 8,
+    name: "James Taylor",
+    role: "Backend Engineer",
+    status: "Active",
+  },
+];
+
+// --- TanStack Column Definitions ------------------------------------------
+const columnHelper = createColumnHelper<User>();
+
+const columns = [
+  columnHelper.accessor("name", {header: "Name"}),
+  columnHelper.accessor("role", {header: "Role"}),
+  columnHelper.accessor("status", {
+    cell: (info) => (
+      <Chip color={statusColorMap[info.getValue()]} size="sm" variant="soft">
+        {info.getValue()}
+      </Chip>
+    ),
+    header: "Status",
+  }),
+  columnHelper.accessor("email", {header: "Email"}),
+];
+
+// --- Sorting Bridge -------------------------------------------------------
+// Convert TanStack SortingState → React Aria SortDescriptor
+function toSortDescriptor(sorting: SortingState): SortDescriptor | undefined {
+  const first = sorting[0];
+
+  if (!first) return undefined;
+
+  return {
+    column: first.id,
+    direction: first.desc ? "descending" : "ascending",
+  };
+}
+
+// Convert React Aria SortDescriptor → TanStack SortingState
+function toSortingState(descriptor: SortDescriptor): SortingState {
+  return [{desc: descriptor.direction === "descending", id: descriptor.column as string}];
+}
+
+// --- Component ------------------------------------------------------------
+const PAGE_SIZE = 4;
+
+export function TanstackTable() {
+  const [sorting, setSorting] = useState<SortingState>([]);
+
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const table = useReactTable({
+    columns,
+    data: users,
+    getCoreRowModel: getCoreRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    initialState: {pagination: {pageSize: PAGE_SIZE}},
+    onSortingChange: setSorting,
+    state: {sorting},
+  });
+
+  const sortDescriptor = useMemo(() => toSortDescriptor(sorting), [sorting]);
+
+  const {pageIndex} = table.getState().pagination;
+  const pageCount = table.getPageCount();
+  const pages = Array.from({length: pageCount}, (_, i) => i + 1);
+  const start = pageIndex * PAGE_SIZE + 1;
+  const end = Math.min((pageIndex + 1) * PAGE_SIZE, users.length);
+
+  return (
+    <Table>
+      <Table.ScrollContainer>
+        <Table.Content
+          aria-label="TanStack Table example"
+          className="min-w-[600px]"
+          sortDescriptor={sortDescriptor}
+          onSortChange={(d) => setSorting(toSortingState(d))}
+        >
+          <Table.Header>
+            {table.getHeaderGroups()[0]!.headers.map((header) => (
+              <Table.Column
+                key={header.id}
+                allowsSorting={header.column.getCanSort()}
+                id={header.id}
+                isRowHeader={header.id === "name"}
+              >
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    {flexRender(header.column.columnDef.header, header.getContext())}
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+            ))}
+          </Table.Header>
+          <Table.Body>
+            {table.getRowModel().rows.map((row) => (
+              <Table.Row key={row.id} id={row.id}>
+                {row.getVisibleCells().map((cell) => (
+                  <Table.Cell key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </Table.Cell>
+                ))}
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Content>
+      </Table.ScrollContainer>
+      <Table.Footer>
+        <Pagination size="sm">
+          <Pagination.Summary>
+            {start} to {end} of {users.length} results
+          </Pagination.Summary>
+          <Pagination.Content>
+            <Pagination.Item>
+              <Pagination.Previous
+                isDisabled={!table.getCanPreviousPage()}
+                onPress={() => table.previousPage()}
+              >
+                <Pagination.PreviousIcon />
+                Prev
+              </Pagination.Previous>
+            </Pagination.Item>
+            {pages.map((p) => (
+              <Pagination.Item key={p}>
+                <Pagination.Link
+                  isActive={p === pageIndex + 1}
+                  onPress={() => table.setPageIndex(p - 1)}
+                >
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ))}
+            <Pagination.Item>
+              <Pagination.Next
+                isDisabled={!table.getCanNextPage()}
+                onPress={() => table.nextPage()}
+              >
+                Next
+                <Pagination.NextIcon />
+              </Pagination.Next>
+            </Pagination.Item>
+          </Pagination.Content>
+        </Pagination>
+      </Table.Footer>
+    </Table>
+  );
+}
diff --git a/apps/docs/src/demos/en/table/virtualization.tsx b/apps/docs/src/demos/en/table/virtualization.tsx
new file mode 100644
index 0000000..74c9a8e
--- /dev/null
+++ b/apps/docs/src/demos/en/table/virtualization.tsx
@@ -0,0 +1,132 @@
+"use client";
+
+import {Table, TableLayout, Virtualizer} from "@heroui/react";
+
+interface User {
+  id: number;
+  name: string;
+  role: string;
+  email: string;
+}
+
+export function Virtualization() {
+  const roles = [
+    "Software Engineer",
+    "Senior Engineer",
+    "Staff Engineer",
+    "Product Manager",
+    "Designer",
+    "Data Analyst",
+    "QA Engineer",
+    "DevOps Engineer",
+    "Marketing Manager",
+    "Sales Representative",
+  ];
+
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+
+  function generateUsers(count: number): User[] {
+    const users: User[] = [];
+
+    for (let i = 0; i < count; i++) {
+      const firstName = firstNames[i % firstNames.length];
+      const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+      const name = `${firstName} ${lastName}`;
+
+      users.push({
+        email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`,
+        id: i + 1,
+        name,
+        role: roles[i % roles.length] || "",
+      });
+    }
+
+    return users;
+  }
+
+  const virtualizedUsers = generateUsers(1000);
+
+  return (
+    <Virtualizer
+      layout={TableLayout}
+      layoutOptions={{
+        headingHeight: 42,
+        rowHeight: 42,
+      }}
+    >
+      <Table>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="Virtualized table with 1000 rows"
+            className="h-[300px] min-w-[700px] overflow-auto"
+          >
+            <Table.Header className="h-full w-full">
+              <Table.Column isRowHeader id="name" minWidth={160}>
+                Name
+              </Table.Column>
+              <Table.Column id="role" minWidth={220}>
+                Role
+              </Table.Column>
+              <Table.Column id="email" minWidth={240}>
+                Email
+              </Table.Column>
+            </Table.Header>
+            <Table.Body items={virtualizedUsers}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              )}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+      </Table>
+    </Virtualizer>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/basic.tsx b/apps/docs/src/demos/en/tabs/basic.tsx
new file mode 100644
index 0000000..80c8fc5
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/basic.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="overview">
+            Overview
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            Analytics
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            Reports
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>View your project overview and recent activity.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>Track your metrics and analyze performance data.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>Generate and download detailed reports.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/custom-render-function.tsx b/apps/docs/src/demos/en/tabs/custom-render-function.tsx
new file mode 100644
index 0000000..7823572
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/custom-render-function.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import {Tabs} from "@heroui/react";
+import Link from "next/link";
+
+export function CustomRenderFunction() {
+  return (
+    <Tabs className="w-full max-w-md" render={(props) => <div {...props} data-custom="foo" />}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab
+            href="/docs/react/getting-started"
+            id="getting-started"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            Getting Started
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab
+            href="/docs/react/components"
+            id="components"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            Components
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab
+            href="/docs/react/releases"
+            id="releases"
+            render={(domProps: any) => <Link {...domProps} />}
+          >
+            Releases
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>View your project overview and recent activity.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>Track your metrics and analyze performance data.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>Generate and download detailed reports.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/custom-styles.tsx b/apps/docs/src/demos/en/tabs/custom-styles.tsx
new file mode 100644
index 0000000..6315229
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/custom-styles.tsx
@@ -0,0 +1,31 @@
+import {Tabs} from "@heroui/react";
+
+export function CustomStyles() {
+  return (
+    <Tabs className="w-full max-w-lg text-center">
+      <Tabs.ListContainer>
+        <Tabs.List
+          aria-label="Options"
+          className="w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal *:data-[selected=true]:text-accent-foreground"
+        >
+          <Tabs.Tab id="daily">
+            Daily
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="weekly">
+            Weekly
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="bi-weekly">
+            Bi-Weekly
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+          <Tabs.Tab id="monthly">
+            Monthly
+            <Tabs.Indicator className="bg-accent" />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/disabled.tsx b/apps/docs/src/demos/en/tabs/disabled.tsx
new file mode 100644
index 0000000..8219cea
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/disabled.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Tabs with disabled">
+          <Tabs.Tab id="active">
+            Active
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab isDisabled id="disabled">
+            Disabled
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="available">
+            Available
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="active">
+        <p>This tab is active and can be selected.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="disabled">
+        <p>This content cannot be accessed.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="available">
+        <p>This tab is also available for selection.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/index.ts b/apps/docs/src/demos/en/tabs/index.ts
new file mode 100644
index 0000000..45b7196
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/index.ts
@@ -0,0 +1,9 @@
+export {Basic} from "./basic";
+export {Vertical} from "./vertical";
+export {Overflow} from "./overflow";
+export {Disabled} from "./disabled";
+export {CustomStyles} from "./custom-styles";
+export {WithSeparator} from "./with-separator";
+export {Secondary} from "./secondary";
+export {SecondaryVertical} from "./secondary-vertical";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/tabs/overflow.tsx b/apps/docs/src/demos/en/tabs/overflow.tsx
new file mode 100644
index 0000000..46fef9e
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/overflow.tsx
@@ -0,0 +1,37 @@
+import {Tabs} from "@heroui/react";
+
+const items = [
+  {id: "overview", label: "Overview"},
+  {id: "analytics", label: "Analytics"},
+  {id: "reports", label: "Reports"},
+  {id: "performance", label: "Performance"},
+  {id: "engagement", label: "Engagement"},
+  {id: "audience", label: "Audience"},
+  {id: "acquisition", label: "Acquisition"},
+  {id: "retention", label: "Retention"},
+  {id: "settings", label: "Settings"},
+];
+
+export function Overflow() {
+  return (
+    <div className="w-[400px]">
+      <Tabs>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Overflow options">
+            {items.map((item) => (
+              <Tabs.Tab key={item.id} id={item.id}>
+                {item.label}
+                <Tabs.Indicator />
+              </Tabs.Tab>
+            ))}
+          </Tabs.List>
+        </Tabs.ListContainer>
+        {items.map((item) => (
+          <Tabs.Panel key={item.id} className="pt-4" id={item.id}>
+            <p>{item.label} panel content.</p>
+          </Tabs.Panel>
+        ))}
+      </Tabs>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/secondary-vertical.tsx b/apps/docs/src/demos/en/tabs/secondary-vertical.tsx
new file mode 100644
index 0000000..02b49ee
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/secondary-vertical.tsx
@@ -0,0 +1,46 @@
+import {Tabs} from "@heroui/react";
+
+export function SecondaryVertical() {
+  return (
+    <Tabs className="w-full max-w-lg" orientation="vertical" variant="secondary">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Vertical tabs">
+          <Tabs.Tab id="account">
+            Account
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="security">
+            Security
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="notifications">
+            Notifications
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="billing">
+            Billing
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="account">
+        <h3 className="mb-2 font-semibold">Account Settings</h3>
+        <p className="text-sm text-muted">Manage your account information and preferences.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="security">
+        <h3 className="mb-2 font-semibold">Security Settings</h3>
+        <p className="text-sm text-muted">
+          Configure two-factor authentication and password settings.
+        </p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="notifications">
+        <h3 className="mb-2 font-semibold">Notification Preferences</h3>
+        <p className="text-sm text-muted">Choose how and when you want to receive notifications.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="billing">
+        <h3 className="mb-2 font-semibold">Billing Information</h3>
+        <p className="text-sm text-muted">View and manage your subscription and payment methods.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/secondary.tsx b/apps/docs/src/demos/en/tabs/secondary.tsx
new file mode 100644
index 0000000..10e5e33
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/secondary.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+
+export function Secondary() {
+  return (
+    <Tabs className="w-full max-w-md" variant="secondary">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="overview">
+            Overview
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            Analytics
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            Reports
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>View your project overview and recent activity.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>Track your metrics and analyze performance data.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>Generate and download detailed reports.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/vertical.tsx b/apps/docs/src/demos/en/tabs/vertical.tsx
new file mode 100644
index 0000000..91436d6
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/vertical.tsx
@@ -0,0 +1,46 @@
+import {Tabs} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <Tabs className="w-full max-w-lg" orientation="vertical">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Vertical tabs">
+          <Tabs.Tab id="account">
+            Account
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="security">
+            Security
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="notifications">
+            Notifications
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="billing">
+            Billing
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="px-4" id="account">
+        <h3 className="mb-2 font-semibold">Account Settings</h3>
+        <p className="text-sm text-muted">Manage your account information and preferences.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="security">
+        <h3 className="mb-2 font-semibold">Security Settings</h3>
+        <p className="text-sm text-muted">
+          Configure two-factor authentication and password settings.
+        </p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="notifications">
+        <h3 className="mb-2 font-semibold">Notification Preferences</h3>
+        <p className="text-sm text-muted">Choose how and when you want to receive notifications.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="px-4" id="billing">
+        <h3 className="mb-2 font-semibold">Billing Information</h3>
+        <p className="text-sm text-muted">View and manage your subscription and payment methods.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tabs/with-separator.tsx b/apps/docs/src/demos/en/tabs/with-separator.tsx
new file mode 100644
index 0000000..3f5835d
--- /dev/null
+++ b/apps/docs/src/demos/en/tabs/with-separator.tsx
@@ -0,0 +1,35 @@
+import {Tabs} from "@heroui/react";
+
+export function WithSeparator() {
+  return (
+    <Tabs className="w-full max-w-md">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="overview">
+            Overview
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="analytics">
+            <Tabs.Separator />
+            Analytics
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="reports">
+            <Tabs.Separator />
+            Reports
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="overview">
+        <p>View your project overview and recent activity.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="analytics">
+        <p>Track your metrics and analyze performance data.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="reports">
+        <p>Generate and download detailed reports.</p>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/basic.tsx b/apps/docs/src/demos/en/tag-group/basic.tsx
new file mode 100644
index 0000000..accf17d
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/basic.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupBasic() {
+  return (
+    <TagGroup aria-label="Tags" selectionMode="single">
+      <TagGroup.List>
+        <Tag id="default-news">
+          <SquareArticle />
+          News
+        </Tag>
+        <Tag id="default-travel">
+          <PlanetEarth />
+          Travel
+        </Tag>
+        <Tag id="default-gaming">
+          <Rocket />
+          Gaming
+        </Tag>
+        <Tag id="default-shopping">
+          <ShoppingBag />
+          Shopping
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/controlled.tsx b/apps/docs/src/demos/en/tag-group/controlled.tsx
new file mode 100644
index 0000000..acf3908
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/controlled.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupControlled() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set(["news", "travel"]));
+
+  return (
+    <div className="flex flex-col gap-3">
+      <TagGroup
+        selectedKeys={selected}
+        selectionMode="multiple"
+        onSelectionChange={(keys) => setSelected(keys)}
+      >
+        <Label>Categories (controlled)</Label>
+        <TagGroup.List>
+          <Tag id="news">News</Tag>
+          <Tag id="travel">Travel</Tag>
+          <Tag id="gaming">Gaming</Tag>
+          <Tag id="shopping">Shopping</Tag>
+        </TagGroup.List>
+        <Description>
+          Selected: {Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "None"}
+        </Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/custom-render-function.tsx b/apps/docs/src/demos/en/tag-group/custom-render-function.tsx
new file mode 100644
index 0000000..2fe37e8
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/custom-render-function.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Tag, TagGroup} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TagGroup
+      aria-label="Tags"
+      render={(props) => <div {...props} data-custom="foo" />}
+      selectionMode="single"
+    >
+      <TagGroup.List>
+        <Tag id="default-news">
+          <SquareArticle />
+          News
+        </Tag>
+        <Tag id="default-travel">
+          <PlanetEarth />
+          Travel
+        </Tag>
+        <Tag id="default-gaming">
+          <Rocket />
+          Gaming
+        </Tag>
+        <Tag id="default-shopping">
+          <ShoppingBag />
+          Shopping
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/disabled.tsx b/apps/docs/src/demos/en/tag-group/disabled.tsx
new file mode 100644
index 0000000..8275794
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/disabled.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupDisabled() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TagGroup selectionMode="single">
+        <Label>Disabled Tags</Label>
+        <TagGroup.List>
+          <Tag isDisabled>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag isDisabled>Gaming</Tag>
+        </TagGroup.List>
+        <Description>Some tags are disabled</Description>
+      </TagGroup>
+
+      <TagGroup disabledKeys={["travel"]} selectionMode="single">
+        <Label>Disabled Keys</Label>
+        <TagGroup.List>
+          <Tag id="news">News</Tag>
+          <Tag id="travel">Travel</Tag>
+          <Tag id="gaming">Gaming</Tag>
+        </TagGroup.List>
+        <Description>Tags disabled via disabledKeys prop</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/index.ts b/apps/docs/src/demos/en/tag-group/index.ts
new file mode 100644
index 0000000..4473c63
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/index.ts
@@ -0,0 +1,11 @@
+export {TagGroupBasic as Basic} from "./basic";
+export {TagGroupDisabled as Disabled} from "./disabled";
+export {TagGroupSelectionModes as SelectionModes} from "./selection-modes";
+export {TagGroupSizes as Sizes} from "./sizes";
+export {TagGroupVariants as Variants} from "./variants";
+export {TagGroupControlled as Controlled} from "./controlled";
+export {TagGroupWithErrorMessage as WithErrorMessage} from "./with-error-message";
+export {TagGroupWithPrefix as WithPrefix} from "./with-prefix";
+export {TagGroupWithRemoveButton as WithRemoveButton} from "./with-remove-button";
+export {TagGroupWithListData as WithListData} from "./with-list-data";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/tag-group/selection-modes.tsx b/apps/docs/src/demos/en/tag-group/selection-modes.tsx
new file mode 100644
index 0000000..cd2d9a4
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/selection-modes.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupSelectionModes() {
+  const [singleSelected, setSingleSelected] = useState<Iterable<Key>>(new Set(["news"]));
+  const [multipleSelected, setMultipleSelected] = useState<Iterable<Key>>(
+    new Set(["news", "travel"]),
+  );
+
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup
+        selectedKeys={singleSelected}
+        selectionMode="single"
+        onSelectionChange={(keys) => setSingleSelected(keys)}
+      >
+        <Label>Single Selection</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+          <Tag>Shopping</Tag>
+        </TagGroup.List>
+        <Description>Choose one category</Description>
+      </TagGroup>
+
+      <TagGroup
+        selectedKeys={multipleSelected}
+        selectionMode="multiple"
+        onSelectionChange={(keys) => setMultipleSelected(keys)}
+      >
+        <Label>Multiple Selection</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+          <Tag>Shopping</Tag>
+        </TagGroup.List>
+        <Description>Choose multiple categories</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/sizes.tsx b/apps/docs/src/demos/en/tag-group/sizes.tsx
new file mode 100644
index 0000000..b17c984
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/sizes.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import {Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupSizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <TagGroup selectionMode="single" size="sm">
+        <Label>Small</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="md">
+        <Label>Medium</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="lg">
+        <Label>Large</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/variants.tsx b/apps/docs/src/demos/en/tag-group/variants.tsx
new file mode 100644
index 0000000..9e5a59c
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/variants.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import {Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupVariants() {
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup selectionMode="single" variant="default">
+        <Label>Default</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+
+      <TagGroup selectionMode="single" variant="surface">
+        <Label>Surface</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/with-error-message.tsx b/apps/docs/src/demos/en/tag-group/with-error-message.tsx
new file mode 100644
index 0000000..8719e25
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/with-error-message.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
+import {useMemo, useState} from "react";
+
+export function TagGroupWithErrorMessage() {
+  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+
+  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+  return (
+    <TagGroup
+      selectedKeys={selected}
+      selectionMode="multiple"
+      onSelectionChange={(keys) => setSelected(keys)}
+    >
+      <Label>Amenities</Label>
+      <TagGroup.List>
+        <Tag id="laundry">Laundry</Tag>
+        <Tag id="fitness">Fitness center</Tag>
+        <Tag id="parking">Parking</Tag>
+        <Tag id="pool">Swimming pool</Tag>
+        <Tag id="breakfast">Breakfast</Tag>
+      </TagGroup.List>
+      <Description>
+        {isInvalid
+          ? "Select at least one category"
+          : "Selected: " + Array.from(selected).join(", ")}
+      </Description>
+      <ErrorMessage>{!!isInvalid && <>Please select at least one category</>}</ErrorMessage>
+    </TagGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/with-list-data.tsx b/apps/docs/src/demos/en/tag-group/with-list-data.tsx
new file mode 100644
index 0000000..6fc4f0e
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/with-list-data.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Avatar, Description, EmptyState, Label, Tag, TagGroup, useListData} from "@heroui/react";
+
+export function TagGroupWithListData() {
+  type User = {
+    id: string;
+    name: string;
+    avatar: string;
+    fallback: string;
+  };
+
+  const list = useListData<User>({
+    getKey: (item) => item.id,
+    initialItems: [
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "F",
+        id: "fred",
+        name: "Fred",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "M",
+        id: "michael",
+        name: "Michael",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "J",
+        id: "jane",
+        name: "Jane",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "A",
+        id: "alice",
+        name: "Alice",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "B",
+        id: "bob",
+        name: "Bob",
+      },
+      {
+        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+        fallback: "C",
+        id: "charlie",
+        name: "Charlie",
+      },
+    ],
+    initialSelectedKeys: new Set(["fred", "michael"]),
+  });
+
+  const onRemove = (keys: Set<Key>) => {
+    list.remove(...keys);
+  };
+
+  return (
+    <div className="w-sm">
+      <TagGroup
+        selectedKeys={list.selectedKeys}
+        selectionMode="multiple"
+        onRemove={onRemove}
+        onSelectionChange={(keys) => list.setSelectedKeys(keys)}
+      >
+        <Label>Team Members</Label>
+        <TagGroup.List
+          items={list.items}
+          renderEmptyState={() => <EmptyState className="p-1">No team members</EmptyState>}
+        >
+          {(user) => (
+            <Tag key={user.id} id={user.id} textValue={user.name}>
+              <Avatar className="size-4" size="sm">
+                <Avatar.Image src={user.avatar} />
+                <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+              </Avatar>
+              {user.name}
+            </Tag>
+          )}
+        </TagGroup.List>
+        <Description>Select team members for your project</Description>
+      </TagGroup>
+      {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
+        <div className="mt-4 flex flex-col gap-2">
+          <p className="text-sm font-medium text-muted">Selected:</p>
+          <div className="flex flex-wrap gap-2">
+            {Array.from(list.selectedKeys).map((key) => {
+              const user = list.getItem(key);
+
+              if (!user) return null;
+
+              return (
+                <div
+                  key={`${user.id}-selected`}
+                  className="flex items-center gap-2 rounded-lg bg-surface-tertiary px-2 py-1"
+                >
+                  <Avatar className="size-4" size="sm">
+                    <Avatar.Image src={user.avatar} />
+                    <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+                  </Avatar>
+                  <span className="text-sm">{user.name}</span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/with-prefix.tsx b/apps/docs/src/demos/en/tag-group/with-prefix.tsx
new file mode 100644
index 0000000..c63de5d
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/with-prefix.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
+import {Avatar, Description, Label, Tag, TagGroup} from "@heroui/react";
+
+export function TagGroupWithPrefix() {
+  return (
+    <div className="flex flex-col gap-8">
+      <TagGroup selectionMode="single">
+        <Label>With Icons</Label>
+        <TagGroup.List>
+          <Tag>
+            <SquareArticle />
+            News
+          </Tag>
+          <Tag>
+            <PlanetEarth />
+            Travel
+          </Tag>
+          <Tag>
+            <Rocket />
+            Gaming
+          </Tag>
+          <Tag>
+            <ShoppingBag />
+            Shopping
+          </Tag>
+        </TagGroup.List>
+        <Description>Tags with icons</Description>
+      </TagGroup>
+
+      <TagGroup selectionMode="single">
+        <Label>With Avatars</Label>
+        <TagGroup.List>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+              <Avatar.Fallback>F</Avatar.Fallback>
+            </Avatar>
+            Fred
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+              <Avatar.Fallback>M</Avatar.Fallback>
+            </Avatar>
+            Michael
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+              <Avatar.Fallback>J</Avatar.Fallback>
+            </Avatar>
+            Jane
+          </Tag>
+        </TagGroup.List>
+        <Description>Tags with avatars</Description>
+      </TagGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tag-group/with-remove-button.tsx b/apps/docs/src/demos/en/tag-group/with-remove-button.tsx
new file mode 100644
index 0000000..1242953
--- /dev/null
+++ b/apps/docs/src/demos/en/tag-group/with-remove-button.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {CircleXmarkFill} from "@gravity-ui/icons";
+import {Description, EmptyState, Label, Tag, TagGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function TagGroupWithRemoveButton() {
+  type TagItem = {id: string; name: string};
+
+  const [tags, setTags] = useState<TagItem[]>([
+    {id: "news", name: "News"},
+    {id: "travel", name: "Travel"},
+    {id: "gaming", name: "Gaming"},
+    {id: "shopping", name: "Shopping"},
+  ]);
+
+  const [frameworks, setFrameworks] = useState<TagItem[]>([
+    {id: "react", name: "React"},
+    {id: "vue", name: "Vue"},
+    {id: "angular", name: "Angular"},
+    {id: "svelte", name: "Svelte"},
+  ]);
+
+  const onRemoveTags = (keys: Set<Key>) => {
+    setTags(tags.filter((tag) => !keys.has(tag.id)));
+  };
+
+  const onRemoveFrameworks = (keys: Set<Key>) => {
+    setFrameworks(frameworks.filter((framework) => !keys.has(framework.id)));
+  };
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="w-sm">
+        <TagGroup selectionMode="single" onRemove={onRemoveTags}>
+          <Label>Default Remove Button</Label>
+          <TagGroup.List
+            items={tags}
+            renderEmptyState={() => <EmptyState className="p-1">No categories found</EmptyState>}
+          >
+            {(tag) => (
+              <Tag key={tag.name} id={tag.id} textValue={tag.name}>
+                {tag.name}
+              </Tag>
+            )}
+          </TagGroup.List>
+          <Description>Click the X to remove tags</Description>
+        </TagGroup>
+      </div>
+
+      <div className="w-md">
+        <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}>
+          <Label>Custom Remove Button</Label>
+          <TagGroup.List
+            items={frameworks}
+            renderEmptyState={() => <EmptyState className="p-1">No frameworks found</EmptyState>}
+          >
+            {(tag) => (
+              <Tag key={tag.id} id={tag.id} textValue={tag.name}>
+                {(renderProps) => (
+                  <>
+                    {tag.name}
+                    {!!renderProps.allowsRemoving && (
+                      <Tag.RemoveButton>
+                        <CircleXmarkFill />
+                      </Tag.RemoveButton>
+                    )}
+                  </>
+                )}
+              </Tag>
+            )}
+          </TagGroup.List>
+          <Description>Custom remove button with icon</Description>
+        </TagGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/basic.tsx b/apps/docs/src/demos/en/textarea/basic.tsx
new file mode 100644
index 0000000..60f6420
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/basic.tsx
@@ -0,0 +1,11 @@
+import {TextArea} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TextArea
+      aria-label="Quick project update"
+      className="h-32 w-96"
+      placeholder="Share a quick project update..."
+    />
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/controlled.tsx b/apps/docs/src/demos/en/textarea/controlled.tsx
new file mode 100644
index 0000000..c708482
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/controlled.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Description, TextArea} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [value, setValue] = React.useState("");
+
+  return (
+    <div className="flex w-96 flex-col gap-2">
+      <TextArea
+        aria-describedby="textarea-controlled-description"
+        aria-label="Announcement"
+        placeholder="Compose an announcement..."
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+      <Description id="textarea-controlled-description">
+        Characters: {value.length} / 280
+      </Description>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/full-width.tsx b/apps/docs/src/demos/en/textarea/full-width.tsx
new file mode 100644
index 0000000..aad6679
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/full-width.tsx
@@ -0,0 +1,9 @@
+import {TextArea} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-3">
+      <TextArea fullWidth placeholder="Full width textarea" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/index.ts b/apps/docs/src/demos/en/textarea/index.ts
new file mode 100644
index 0000000..8d4f1f6
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {FullWidth} from "./full-width";
+export {OnSurface} from "./on-surface";
+export {Rows} from "./rows";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/textarea/on-surface.tsx b/apps/docs/src/demos/en/textarea/on-surface.tsx
new file mode 100644
index 0000000..afcbf86
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/on-surface.tsx
@@ -0,0 +1,13 @@
+import {Surface, TextArea} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="w-full rounded-3xl p-6">
+      <TextArea
+        className="w-full min-w-[280px]"
+        placeholder="Describe your product"
+        variant="secondary"
+      />
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/rows.tsx b/apps/docs/src/demos/en/textarea/rows.tsx
new file mode 100644
index 0000000..a378bc7
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/rows.tsx
@@ -0,0 +1,27 @@
+import {Label, TextArea} from "@heroui/react";
+
+export function Rows() {
+  return (
+    <div className="flex w-96 flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="textarea-rows-3">Short feedback</Label>
+        <TextArea
+          aria-label="Short feedback"
+          id="textarea-rows-3"
+          placeholder="This week's highlights..."
+          rows={3}
+        />
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="textarea-rows-6">Detailed notes</Label>
+        <TextArea
+          aria-label="Detailed notes"
+          id="textarea-rows-6"
+          placeholder="Write out the full meeting notes..."
+          rows={6}
+          style={{resize: "vertical"}}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textarea/variants.tsx b/apps/docs/src/demos/en/textarea/variants.tsx
new file mode 100644
index 0000000..7cd8024
--- /dev/null
+++ b/apps/docs/src/demos/en/textarea/variants.tsx
@@ -0,0 +1,10 @@
+import {TextArea} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex w-[280px] flex-col gap-2">
+      <TextArea fullWidth placeholder="Primary textarea" variant="primary" />
+      <TextArea fullWidth placeholder="Secondary textarea" variant="secondary" />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/basic.tsx b/apps/docs/src/demos/en/textfield/basic.tsx
new file mode 100644
index 0000000..0399212
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/basic.tsx
@@ -0,0 +1,10 @@
+import {Input, Label, TextField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TextField className="w-full max-w-64" name="email" type="email">
+      <Label>Email</Label>
+      <Input placeholder="Enter your email" />
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/controlled.tsx b/apps/docs/src/demos/en/textfield/controlled.tsx
new file mode 100644
index 0000000..3f4f51a
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/controlled.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Description, Input, Label, TextArea, TextField} from "@heroui/react";
+import React from "react";
+
+export function Controlled() {
+  const [name, setName] = React.useState("");
+  const [bio, setBio] = React.useState("");
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField name="name" value={name} onChange={setName}>
+        <Label>Display name</Label>
+        <Input placeholder="Jane" />
+        <Description>Characters: {name.length}</Description>
+      </TextField>
+      <TextField name="bio" value={bio} onChange={setBio}>
+        <Label>Bio</Label>
+        <TextArea placeholder="Tell us about yourself..." />
+        <Description>Characters: {bio.length} / 200</Description>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/custom-render-function.tsx b/apps/docs/src/demos/en/textfield/custom-render-function.tsx
new file mode 100644
index 0000000..38691da
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/custom-render-function.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import {Input, Label, TextField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TextField
+      className="w-full max-w-64"
+      name="email"
+      render={(props) => <div {...props} data-custom="foo" />}
+      type="email"
+    >
+      <Label>Email</Label>
+      <Input placeholder="Enter your email" />
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/disabled.tsx b/apps/docs/src/demos/en/textfield/disabled.tsx
new file mode 100644
index 0000000..066f91f
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/disabled.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <TextField isDisabled className="w-full max-w-64" name="accountId" value="USR-12345">
+      <Label>Account ID</Label>
+      <Input placeholder="Auto-generated" />
+      <Description>This field cannot be edited</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/full-width.tsx b/apps/docs/src/demos/en/textfield/full-width.tsx
new file mode 100644
index 0000000..0fc9a9b
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/full-width.tsx
@@ -0,0 +1,17 @@
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="name">
+        <Label>Your name</Label>
+        <Input placeholder="John" />
+      </TextField>
+      <TextField fullWidth isInvalid isRequired name="password" type="password">
+        <Label>Password</Label>
+        <Input />
+        <FieldError>Password must be longer than 8 characters</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/index.ts b/apps/docs/src/demos/en/textfield/index.ts
new file mode 100644
index 0000000..22b02db
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/index.ts
@@ -0,0 +1,12 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {InputTypes} from "./input-types";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {TextAreaExample as TextArea} from "./textarea";
+export {Validation} from "./validation";
+export {WithDescription} from "./with-description";
+export {WithError} from "./with-error";
diff --git a/apps/docs/src/demos/en/textfield/input-types.tsx b/apps/docs/src/demos/en/textfield/input-types.tsx
new file mode 100644
index 0000000..6c1736f
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/input-types.tsx
@@ -0,0 +1,32 @@
+import {Input, Label, TextField} from "@heroui/react";
+
+export function InputTypes() {
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField name="password" type="password">
+        <Label>Password</Label>
+        <Input placeholder="••••••••" />
+      </TextField>
+
+      <TextField name="age" type="number">
+        <Label>Age</Label>
+        <Input max="150" min="0" placeholder="21" />
+      </TextField>
+
+      <TextField name="email" type="email">
+        <Label>Email</Label>
+        <Input placeholder="user@example.com" />
+      </TextField>
+
+      <TextField name="website" type="url">
+        <Label>Website</Label>
+        <Input placeholder="https://example.com" />
+      </TextField>
+
+      <TextField name="phone" type="tel">
+        <Label>Phone</Label>
+        <Input placeholder="+1 (555) 000-0000" />
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/on-surface.tsx b/apps/docs/src/demos/en/textfield/on-surface.tsx
new file mode 100644
index 0000000..9bb1911
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/on-surface.tsx
@@ -0,0 +1,22 @@
+import {Description, Input, Label, Surface, TextArea, TextField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full min-w-[340px] flex-col gap-4 rounded-3xl p-6">
+      <TextField name="name" variant="secondary">
+        <Label>Your name</Label>
+        <Input className="w-full" placeholder="John" />
+        <Description>We'll never share this with anyone else</Description>
+      </TextField>
+      <TextField name="email" type="email" variant="secondary">
+        <Label>Email</Label>
+        <Input className="w-full" placeholder="john@example.com" />
+      </TextField>
+      <TextField name="bio" variant="secondary">
+        <Label>Bio</Label>
+        <TextArea className="w-full" placeholder="Tell us about yourself..." rows={4} />
+        <Description>Minimum 4 rows</Description>
+      </TextField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/required.tsx b/apps/docs/src/demos/en/textfield/required.tsx
new file mode 100644
index 0000000..796f262
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/required.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <TextField isRequired className="w-full max-w-64" name="fullName">
+      <Label>Full Name</Label>
+      <Input placeholder="John Doe" />
+      <Description>This field is required</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/textarea.tsx b/apps/docs/src/demos/en/textfield/textarea.tsx
new file mode 100644
index 0000000..1a38a78
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/textarea.tsx
@@ -0,0 +1,11 @@
+import {Description, Label, TextArea, TextField} from "@heroui/react";
+
+export function TextAreaExample() {
+  return (
+    <TextField className="w-full max-w-64" name="message">
+      <Label>Message</Label>
+      <TextArea placeholder="Write your message here..." rows={4} />
+      <Description>Maximum 500 characters</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/validation.tsx b/apps/docs/src/demos/en/textfield/validation.tsx
new file mode 100644
index 0000000..03b921c
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/validation.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import {Description, FieldError, Input, Label, TextArea, TextField} from "@heroui/react";
+import React from "react";
+
+export function Validation() {
+  const [username, setUsername] = React.useState("");
+  const [bio, setBio] = React.useState("");
+
+  const isUsernameInvalid = username.length > 0 && username.length < 3;
+  const isBioInvalid = bio.length > 0 && bio.length < 20;
+
+  return (
+    <div className="flex w-full max-w-64 flex-col gap-4">
+      <TextField
+        isRequired
+        isInvalid={isUsernameInvalid}
+        name="username"
+        value={username}
+        onChange={setUsername}
+      >
+        <Label>Username</Label>
+        <Input placeholder="jane_doe" />
+        {isUsernameInvalid ? (
+          <FieldError>Username must be at least 3 characters.</FieldError>
+        ) : (
+          <Description>Choose a unique username for your profile.</Description>
+        )}
+      </TextField>
+
+      <TextField isRequired isInvalid={isBioInvalid} name="bio" value={bio} onChange={setBio}>
+        <Label>Bio</Label>
+        <TextArea placeholder="Tell us about yourself..." />
+        {isBioInvalid ? (
+          <FieldError>Bio must contain at least 20 characters.</FieldError>
+        ) : (
+          <Description>Minimum 20 characters ({bio.length}/20).</Description>
+        )}
+      </TextField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/with-description.tsx b/apps/docs/src/demos/en/textfield/with-description.tsx
new file mode 100644
index 0000000..b4e65df
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/with-description.tsx
@@ -0,0 +1,11 @@
+import {Description, Input, Label, TextField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <TextField className="w-full max-w-64" name="username">
+      <Label>Username</Label>
+      <Input placeholder="Enter username" />
+      <Description>Choose a unique username for your account</Description>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/textfield/with-error.tsx b/apps/docs/src/demos/en/textfield/with-error.tsx
new file mode 100644
index 0000000..f22085a
--- /dev/null
+++ b/apps/docs/src/demos/en/textfield/with-error.tsx
@@ -0,0 +1,11 @@
+import {FieldError, Input, Label, TextField} from "@heroui/react";
+
+export function WithError() {
+  return (
+    <TextField isInvalid className="w-full max-w-64" name="email" type="email">
+      <Label>Email</Label>
+      <Input placeholder="user@example.com" />
+      <FieldError>Please enter a valid email address</FieldError>
+    </TextField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/basic.tsx b/apps/docs/src/demos/en/time-field/basic.tsx
new file mode 100644
index 0000000..b96898c
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/basic.tsx
@@ -0,0 +1,14 @@
+"use client";
+
+import {Label, TimeField} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/controlled.tsx b/apps/docs/src/demos/en/time-field/controlled.tsx
new file mode 100644
index 0000000..51680cb
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/controlled.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import type {TimeValue} from "@heroui/react";
+
+import {Button, Description, Label, TimeField} from "@heroui/react";
+import {Time, getLocalTimeZone, now} from "@internationalized/date";
+import {useState} from "react";
+
+export function Controlled() {
+  const [value, setValue] = useState<TimeValue | null>(null);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField className="w-[256px]" name="time" value={value} onChange={setValue}>
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+      </TimeField>
+      <div className="flex gap-2">
+        <Button
+          variant="tertiary"
+          onPress={() => {
+            const currentTime = now(getLocalTimeZone());
+
+            setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second));
+          }}
+        >
+          Set now
+        </Button>
+        <Button variant="tertiary" onPress={() => setValue(null)}>
+          Clear
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/custom-render-function.tsx b/apps/docs/src/demos/en/time-field/custom-render-function.tsx
new file mode 100644
index 0000000..2e77304
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/custom-render-function.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Label, TimeField} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <TimeField
+      className="w-[256px]"
+      name="time"
+      render={(props) => <div {...props} data-custom="foo" />}
+    >
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/disabled.tsx b/apps/docs/src/demos/en/time-field/disabled.tsx
new file mode 100644
index 0000000..c85b3ec
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/disabled.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+import {Time, getLocalTimeZone, now} from "@internationalized/date";
+
+export function Disabled() {
+  const currentTime = now(getLocalTimeZone());
+  const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isDisabled className="w-[256px]" name="time" value={timeValue}>
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>This time field is disabled</Description>
+      </TimeField>
+      <TimeField isDisabled className="w-[256px]" name="time-empty">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>This time field is disabled</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/form-example.tsx b/apps/docs/src/demos/en/time-field/form-example.tsx
new file mode 100644
index 0000000..18278c0
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/form-example.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import type {Time} from "@internationalized/date";
+
+import {Clock} from "@gravity-ui/icons";
+import {Button, Description, FieldError, Form, Label, TimeField} from "@heroui/react";
+import {parseTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function FormExample() {
+  const [value, setValue] = useState<Time | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const minTime = parseTime("09:00");
+  const maxTime = parseTime("17:00");
+  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!value || isInvalid) {
+      return;
+    }
+
+    setIsSubmitting(true);
+
+    // Simulate API call
+    setTimeout(() => {
+      console.log("Time submitted:", {time: value});
+      setValue(null);
+      setIsSubmitting(false);
+    }, 1500);
+  };
+
+  return (
+    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+      <TimeField
+        isRequired
+        className="w-full"
+        isInvalid={isInvalid}
+        maxValue={maxTime}
+        minValue={minTime}
+        name="time"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Appointment time</Label>
+        <TimeField.Group>
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        {isInvalid ? (
+          <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
+        ) : (
+          <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
+        )}
+      </TimeField>
+      <Button
+        className="w-full"
+        isDisabled={!value || isInvalid}
+        isPending={isSubmitting}
+        type="submit"
+        variant="primary"
+      >
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </Button>
+    </Form>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/full-width.tsx b/apps/docs/src/demos/en/time-field/full-width.tsx
new file mode 100644
index 0000000..3736a47
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/full-width.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {ChevronDown, Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-[400px] space-y-4">
+      <TimeField fullWidth name="time">
+        <Label>Time</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField fullWidth name="time-icons">
+        <Label>Time</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+          <TimeField.Suffix>
+            <ChevronDown className="size-4 text-muted" />
+          </TimeField.Suffix>
+        </TimeField.Group>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/index.ts b/apps/docs/src/demos/en/time-field/index.ts
new file mode 100644
index 0000000..0898841
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/index.ts
@@ -0,0 +1,14 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {CustomRenderFunction} from "./custom-render-function";
+export {Disabled} from "./disabled";
+export {FormExample} from "./form-example";
+export {FullWidth} from "./full-width";
+export {Invalid} from "./invalid";
+export {OnSurface} from "./on-surface";
+export {Required} from "./required";
+export {WithDescription} from "./with-description";
+export {WithPrefixAndSuffix} from "./with-prefix-and-suffix";
+export {WithPrefixIcon} from "./with-prefix-icon";
+export {WithSuffixIcon} from "./with-suffix-icon";
+export {WithValidation} from "./with-validation";
diff --git a/apps/docs/src/demos/en/time-field/invalid.tsx b/apps/docs/src/demos/en/time-field/invalid.tsx
new file mode 100644
index 0000000..64cc988
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/invalid.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {FieldError, Label, TimeField} from "@heroui/react";
+
+export function Invalid() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isInvalid isRequired className="w-[256px]" name="time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>Please enter a valid time</FieldError>
+      </TimeField>
+      <TimeField isInvalid className="w-[256px]" name="invalid-time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>Time must be within business hours</FieldError>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/on-surface.tsx b/apps/docs/src/demos/en/time-field/on-surface.tsx
new file mode 100644
index 0000000..b48ef2b
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/on-surface.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Description, Label, Surface, TimeField} from "@heroui/react";
+
+export function OnSurface() {
+  return (
+    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
+      <TimeField className="w-full" name="time">
+        <Label>Time</Label>
+        <TimeField.Group variant="secondary">
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter a time</Description>
+      </TimeField>
+      <TimeField className="w-full" name="time-2">
+        <Label>Appointment time</Label>
+        <TimeField.Group variant="secondary">
+          <TimeField.Prefix>
+            <Clock className="size-4 text-muted" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter a time for your appointment</Description>
+      </TimeField>
+    </Surface>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/required.tsx b/apps/docs/src/demos/en/time-field/required.tsx
new file mode 100644
index 0000000..a951380
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/required.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function Required() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField isRequired className="w-[256px]" name="time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField isRequired className="w-[256px]" name="appointment-time">
+        <Label>Appointment time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Required field</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/with-description.tsx b/apps/docs/src/demos/en/time-field/with-description.tsx
new file mode 100644
index 0000000..c142b0f
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/with-description.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function WithDescription() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField className="w-[256px]" name="time">
+        <Label>Start time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter the start time</Description>
+      </TimeField>
+      <TimeField className="w-[256px]" name="end-time">
+        <Label>End time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter the end time</Description>
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/with-prefix-and-suffix.tsx b/apps/docs/src/demos/en/time-field/with-prefix-and-suffix.tsx
new file mode 100644
index 0000000..9ccf03e
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/with-prefix-and-suffix.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {ChevronDown, Clock} from "@gravity-ui/icons";
+import {Description, Label, TimeField} from "@heroui/react";
+
+export function WithPrefixAndSuffix() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <ChevronDown className="size-4 text-muted" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+      <Description>Enter a time</Description>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/with-prefix-icon.tsx b/apps/docs/src/demos/en/time-field/with-prefix-icon.tsx
new file mode 100644
index 0000000..e2b6fb7
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/with-prefix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function WithPrefixIcon() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/with-suffix-icon.tsx b/apps/docs/src/demos/en/time-field/with-suffix-icon.tsx
new file mode 100644
index 0000000..0cb33b8
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/with-suffix-icon.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import {Clock} from "@gravity-ui/icons";
+import {Label, TimeField} from "@heroui/react";
+
+export function WithSuffixIcon() {
+  return (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <Clock className="size-4 text-muted" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+    </TimeField>
+  );
+}
diff --git a/apps/docs/src/demos/en/time-field/with-validation.tsx b/apps/docs/src/demos/en/time-field/with-validation.tsx
new file mode 100644
index 0000000..1aa59f8
--- /dev/null
+++ b/apps/docs/src/demos/en/time-field/with-validation.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import type {Time} from "@internationalized/date";
+
+import {Description, FieldError, Label, TimeField} from "@heroui/react";
+import {parseTime} from "@internationalized/date";
+import {useState} from "react";
+
+export function WithValidation() {
+  const [value, setValue] = useState<Time | null>(null);
+  const minTime = parseTime("09:00");
+  const maxTime = parseTime("17:00");
+  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <TimeField
+        isRequired
+        className="w-[256px]"
+        isInvalid={isInvalid}
+        maxValue={maxTime}
+        minValue={minTime}
+        name="time"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        {isInvalid ? (
+          <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
+        ) : (
+          <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
+        )}
+      </TimeField>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/callbacks.tsx b/apps/docs/src/demos/en/toast/callbacks.tsx
new file mode 100644
index 0000000..66ffbe3
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/callbacks.tsx
@@ -0,0 +1,128 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+import React from "react";
+
+export function Callbacks() {
+  const [closedHistory, setClosedHistory] = React.useState<Array<{message: string; time: string}>>(
+    [],
+  );
+
+  const addToHistory = (message: string) => {
+    const time = new Date().toLocaleTimeString();
+
+    setClosedHistory((prev) => [{message, time}, ...prev].slice(0, 5));
+  };
+
+  return (
+    <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-6">
+      {/* Toast Buttons */}
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("File saved", {
+              onClose: () => {
+                addToHistory("File saved (closed after 3 seconds)");
+              },
+              timeout: 3000,
+            })
+          }
+        >
+          Custom timeout (3s)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("Changes saved", {
+              onClose: () => {
+                addToHistory("Changes saved (closed after 10 seconds)");
+              },
+              timeout: 10000,
+            })
+          }
+        >
+          Custom timeout (10s)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.success("Event created", {
+              onClose: () => {
+                addToHistory("Event created (closed after default timeout)");
+              },
+            })
+          }
+        >
+          With onClose callback
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("Important notification", {
+              description: "This toast will stay until dismissed",
+              onClose: () => {
+                addToHistory("Important notification (manually closed)");
+              },
+              timeout: 0,
+            })
+          }
+        >
+          Persistent toast
+        </Button>
+      </div>
+
+      {/* Closed History Panel */}
+      <div className="w-full space-y-2">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium">Closed History</h3>
+          {closedHistory.length > 0 && (
+            <Button
+              className="h-6 text-xs"
+              size="sm"
+              variant="tertiary"
+              onPress={() => setClosedHistory([])}
+            >
+              Clear
+            </Button>
+          )}
+        </div>
+        <div className="min-h-[120px] space-y-2 rounded-lg border border-border bg-surface p-4">
+          {closedHistory.length === 0 ? (
+            <p className="text-sm text-muted">No toasts closed yet. Try closing one above!</p>
+          ) : (
+            closedHistory.map((item, index) => (
+              <div
+                key={`${item.time}-${index}`}
+                className="flex animate-in items-start justify-between gap-3 rounded-md border border-border bg-default px-3 py-2 text-sm duration-200 fade-in slide-in-from-top-2"
+                style={{
+                  animationDelay: `${index * 50}ms`,
+                }}
+              >
+                <div className="flex-1">
+                  <span className="font-medium">{item.message}</span>
+                  <span className="ml-2 text-xs text-muted">({item.time})</span>
+                </div>
+                <div className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-success/10 text-success-soft-foreground">
+                  <svg
+                    className="size-3"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" />
+                  </svg>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/custom-indicator.tsx b/apps/docs/src/demos/en/toast/custom-indicator.tsx
new file mode 100644
index 0000000..4f531cc
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/custom-indicator.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import {Star} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+export function CustomIndicator() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() =>
+          toast("Custom icon indicator", {
+            indicator: <Star />,
+          })
+        }
+      >
+        Custom indicator
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/custom-queue.tsx b/apps/docs/src/demos/en/toast/custom-queue.tsx
new file mode 100644
index 0000000..07bcc31
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/custom-queue.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import {Button, Toast, ToastQueue} from "@heroui/react";
+
+export function CustomQueue() {
+  const notificationQueue = new ToastQueue({maxVisibleToasts: 2});
+  const errorQueue = new ToastQueue({maxVisibleToasts: 3});
+  const successQueue = new ToastQueue({maxVisibleToasts: 1});
+
+  return (
+    <div className="flex h-full max-w-4xl items-center justify-center gap-4">
+      {/* Notification Queue */}
+      <Toast.Provider placement="bottom" queue={notificationQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            notificationQueue.add({
+              description: "You have a new message",
+              title: "New notification",
+              variant: "default",
+            });
+          }}
+        >
+          Add notification (max 2)
+        </Button>
+      </div>
+
+      {/* Error Queue */}
+      <Toast.Provider placement="bottom start" queue={errorQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() => {
+            errorQueue.add({
+              description: "Failed to save changes",
+              title: "Error occurred",
+              variant: "danger",
+            });
+          }}
+        >
+          Add error (max 3)
+        </Button>
+      </div>
+
+      {/* Success Queue */}
+      <Toast.Provider placement="bottom end" queue={successQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          className="text-success-soft-foreground"
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            successQueue.add({
+              description: `Operation ${Date.now()}`,
+              title: "Success!",
+              variant: "success",
+            });
+          }}
+        >
+          Add success (max 1)
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/custom-toast.tsx b/apps/docs/src/demos/en/toast/custom-toast.tsx
new file mode 100644
index 0000000..ddd66b4
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/custom-toast.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import type {ToastContentValue} from "@heroui/react";
+
+import {
+  Button,
+  Toast,
+  ToastContent,
+  ToastDescription,
+  ToastIndicator,
+  ToastQueue,
+  ToastTitle,
+} from "@heroui/react";
+
+export function CustomToast() {
+  const customQueue = new ToastQueue();
+
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" queue={customQueue}>
+        {({toast: toastItem}) => {
+          const content = toastItem.content as ToastContentValue;
+
+          return (
+            <Toast
+              className="rounded-xl border border-border"
+              toast={toastItem}
+              variant={content.variant}
+            >
+              <ToastContent>
+                <div className="flex items-center gap-2">
+                  <ToastIndicator
+                    className="text-accent-soft-foreground"
+                    variant={content.variant}
+                  />
+                  <div className="flex flex-col pr-6">
+                    {content.title ? (
+                      <ToastTitle className="text-accent-soft-foreground">
+                        {content.title}
+                      </ToastTitle>
+                    ) : null}
+                    {content.description ? (
+                      <ToastDescription>{content.description}</ToastDescription>
+                    ) : null}
+                  </div>
+                </div>
+              </ToastContent>
+              <Toast.CloseButton className="absolute top-1/2 right-2 -translate-y-1/2 border-none bg-transparent opacity-100 [&>svg]:size-4" />
+            </Toast>
+          );
+        }}
+      </Toast.Provider>
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() => {
+          customQueue.add({
+            description: "This uses a custom render function",
+            title: "Custom layout toast",
+            variant: "default",
+          });
+        }}
+      >
+        Custom toast
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/default.tsx b/apps/docs/src/demos/en/toast/default.tsx
new file mode 100644
index 0000000..9a3033f
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/default.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import {Persons} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+export function Default() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() => {
+          toast("You have been invited to join a team", {
+            actionProps: {
+              children: "Dismiss",
+              onPress: () => toast.clear(),
+              variant: "tertiary",
+            },
+            description: "Bob sent you an invitation to join HeroUI team",
+            indicator: <Persons />,
+            variant: "default",
+          });
+        }}
+      >
+        Show toast
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/index.ts b/apps/docs/src/demos/en/toast/index.ts
new file mode 100644
index 0000000..07f9118
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/index.ts
@@ -0,0 +1,9 @@
+export {Callbacks} from "./callbacks";
+export {CustomIndicator} from "./custom-indicator";
+export {CustomQueue} from "./custom-queue";
+export {CustomToast} from "./custom-toast";
+export {Default} from "./default";
+export {Placements} from "./placements";
+export {PromiseDemo as Promise} from "./promise";
+export {Simple} from "./simple";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/toast/placements.tsx b/apps/docs/src/demos/en/toast/placements.tsx
new file mode 100644
index 0000000..5fe7b7e
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/placements.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {ToastVariants} from "@heroui/react";
+
+import {Button, Toast, ToastQueue} from "@heroui/react";
+
+type Placement = NonNullable<ToastVariants["placement"]>;
+
+const placements = ["top start", "top", "top end", "bottom start", "bottom", "bottom end"] as const;
+
+// Create a separate queue for each placement
+const placementQueues = Object.fromEntries(
+  placements.map((p) => [p, new ToastQueue({maxVisibleToasts: 3})]),
+) as Record<Placement, ToastQueue>;
+
+export function Placements() {
+  const showToast = (placement: Placement) => {
+    placementQueues[placement].add({
+      description: "Event has been created",
+      title: "Event created",
+      variant: "default",
+    });
+  };
+
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-6">
+      {/* Render a ToastProvider for each placement */}
+      {placements.map((p) => (
+        <Toast.Provider key={p} placement={p} queue={placementQueues[p]} />
+      ))}
+      <div className="flex max-w-xs flex-wrap justify-center gap-2">
+        {placements.map((p) => (
+          <Button key={p} size="sm" variant="secondary" onPress={() => showToast(p)}>
+            {p}
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/promise.tsx b/apps/docs/src/demos/en/toast/promise.tsx
new file mode 100644
index 0000000..b76c1a7
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/promise.tsx
@@ -0,0 +1,171 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+
+const uploadFile = (): Promise<{filename: string; size: number}> => {
+  return new Promise<{filename: string; size: number}>((resolve) => {
+    setTimeout(() => resolve({filename: "document.pdf", size: 1024}), 2000);
+  });
+};
+
+const createEvent = (): Promise<never> => {
+  return new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error("Network error. Please try again.")), 2000);
+  });
+};
+
+const saveData = (): Promise<{count: number}> => {
+  return new Promise<{count: number}>((resolve, reject) => {
+    setTimeout(() => {
+      if (Math.random() > 0.5) {
+        resolve({count: 42});
+      } else {
+        reject(new Error("Failed to save data"));
+      }
+    }, 2000);
+  });
+};
+
+const fetchUser = (): Promise<{name: string; email: string}> => {
+  return new Promise<{name: string; email: string}>((resolve) => {
+    setTimeout(() => resolve({email: "john@example.com", name: "John Doe"}), 2000);
+  });
+};
+
+export function PromiseDemo() {
+  return (
+    <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-8">
+      {/* Promise API Section */}
+      <div className="w-full space-y-3">
+        <div className="text-center">
+          <h3 className="text-sm font-medium">Using toast.promise()</h3>
+          <p className="text-xs text-muted">
+            Automatically handles loading, success, and error states
+          </p>
+        </div>
+        <div className="flex w-full flex-wrap items-center justify-center gap-4">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(uploadFile(), {
+                error: "Failed to upload file",
+                loading: "Uploading file...",
+                success: (data) => `File ${data.filename} uploaded (${data.size}KB)`,
+              });
+            }}
+          >
+            Upload file
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(createEvent(), {
+                error: (err) => err.message,
+                loading: "Creating event...",
+                success: "Event created",
+              });
+            }}
+          >
+            Create event (error)
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(saveData(), {
+                error: (err) => err.message,
+                loading: "Saving changes...",
+                success: (data) => `Saved ${data.count} items`,
+              });
+            }}
+          >
+            Save data (random)
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              toast.promise(fetchUser(), {
+                error: "Failed to fetch user",
+                loading: "Loading user...",
+                success: (data) => `Welcome back, ${data.name}!`,
+              });
+            }}
+          >
+            Fetch user
+          </Button>
+        </div>
+      </div>
+
+      {/* Manual Loading Section */}
+      <div className="w-full space-y-3">
+        <div className="text-center">
+          <h3 className="text-sm font-medium">Manual Loading State</h3>
+          <p className="text-xs text-muted">Manually control loading state with isLoading prop</p>
+        </div>
+        <div className="flex w-full flex-wrap items-center justify-center gap-4">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("Uploading file...", {
+                description: "Please wait while we upload your file",
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.success("File uploaded", {
+                  description: "Your file has been uploaded successfully",
+                });
+              }, 3000);
+            }}
+          >
+            Upload with loading
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("Processing payment...", {
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.success("Payment processed", {
+                  description: "Your payment has been processed successfully",
+                });
+              }, 2500);
+            }}
+          >
+            Payment processing
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const loadingId = toast("Saving changes...", {
+                isLoading: true,
+                timeout: 0,
+              });
+
+              setTimeout(() => {
+                toast.close(loadingId);
+                toast.danger("Failed to save", {
+                  description: "Please try again",
+                });
+              }, 2000);
+            }}
+          >
+            Loading to error
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/simple.tsx b/apps/docs/src/demos/en/toast/simple.tsx
new file mode 100644
index 0000000..3a3f05c
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/simple.tsx
@@ -0,0 +1,31 @@
+"use client";
+
+import {Button, toast} from "@heroui/react";
+
+export function Simple() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button size="sm" variant="secondary" onPress={() => toast("Simple message")}>
+          Default
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.success("Operation completed")}>
+          Success
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.info("New update available")}>
+          Info
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => toast.warning("Please check your settings")}
+        >
+          Warning
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.danger("Something went wrong")}>
+          Error
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toast/variants.tsx b/apps/docs/src/demos/en/toast/variants.tsx
new file mode 100644
index 0000000..66835fa
--- /dev/null
+++ b/apps/docs/src/demos/en/toast/variants.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import {HardDrive, Persons} from "@gravity-ui/icons";
+import {Button, toast} from "@heroui/react";
+
+const noop = () => {};
+
+export function Variants() {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="tertiary"
+          onPress={() => {
+            toast("You have been invited to join a team", {
+              actionProps: {
+                children: "Dismiss",
+                onPress: () => toast.clear(),
+                variant: "tertiary",
+              },
+              description: "Bob sent you an invitation to join HeroUI team",
+              indicator: <Persons />,
+              variant: "default",
+            });
+          }}
+        >
+          Default toast
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.info("You have 2 credits left", {
+              actionProps: {children: "Upgrade", onPress: noop},
+              description: "Get a paid plan for more credits",
+            })
+          }
+        >
+          Accent toast
+        </Button>
+        <Button
+          className="text-success-soft-foreground"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.success("You have upgraded your plan", {
+              actionProps: {
+                children: "Billing",
+                className: "bg-success text-success-foreground",
+                onPress: noop,
+              },
+              description: "You can continue using HeroUI Chat",
+            })
+          }
+        >
+          Success toast
+        </Button>
+        <Button
+          className="text-warning-soft-foreground"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.warning("You have no credits left", {
+              actionProps: {
+                children: "Upgrade",
+                className: "bg-warning text-warning-foreground",
+                onPress: noop,
+              },
+              description: "Upgrade to a paid plan to continue",
+            })
+          }
+        >
+          Warning toast
+        </Button>
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() =>
+            toast.danger("Storage is full", {
+              actionProps: {children: "Remove", onPress: noop, variant: "danger"},
+              description:
+                "Remove files to release space. Adding more text to demonstrate longer content display",
+              indicator: <HardDrive />,
+            })
+          }
+        >
+          Danger toast
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/attached.tsx b/apps/docs/src/demos/en/toggle-button-group/attached.tsx
new file mode 100644
index 0000000..1580d6d
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/attached.tsx
@@ -0,0 +1,46 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Attached() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Attached (default)</span>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Detached</span>
+        <ToggleButtonGroup isDetached selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/basic.tsx b/apps/docs/src/demos/en/toggle-button-group/basic.tsx
new file mode 100644
index 0000000..98bc685
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/basic.tsx
@@ -0,0 +1,24 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="Bold" id="bold">
+        <Bold />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Italic" id="italic">
+        <ToggleButtonGroup.Separator />
+        <Italic />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Underline" id="underline">
+        <ToggleButtonGroup.Separator />
+        <Underline />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+        <ToggleButtonGroup.Separator />
+        <Strikethrough />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/controlled.tsx b/apps/docs/src/demos/en/toggle-button-group/controlled.tsx
new file mode 100644
index 0000000..eedca54
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/controlled.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import type {Key} from "@heroui/react";
+
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [selectedKeys, setSelectedKeys] = useState(new Set<Key>(["bold"]));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ToggleButtonGroup
+        selectedKeys={selectedKeys}
+        selectionMode="multiple"
+        onSelectionChange={setSelectedKeys}
+      >
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+          <ToggleButtonGroup.Separator />
+          <Strikethrough />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <p className="text-sm text-muted">
+        Selected:{" "}
+        <span className="font-medium">
+          {selectedKeys.size > 0 ? [...selectedKeys].join(", ") : "None"}
+        </span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/disabled.tsx b/apps/docs/src/demos/en/toggle-button-group/disabled.tsx
new file mode 100644
index 0000000..c563a48
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/disabled.tsx
@@ -0,0 +1,41 @@
+import {Bold, Italic, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">All buttons disabled</span>
+        <ToggleButtonGroup isDisabled selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Individual button disabled</span>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isDisabled isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/full-width.tsx b/apps/docs/src/demos/en/toggle-button-group/full-width.tsx
new file mode 100644
index 0000000..0e19f9b
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/full-width.tsx
@@ -0,0 +1,50 @@
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function FullWidth() {
+  return (
+    <div className="w-full max-w-md space-y-3">
+      <ToggleButtonGroup fullWidth selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+          <ToggleButtonGroup.Separator />
+          <Strikethrough />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <ToggleButtonGroup fullWidth selectionMode="single">
+        <ToggleButton id="left">
+          <TextAlignLeft />
+          Left
+        </ToggleButton>
+        <ToggleButton id="center">
+          <ToggleButtonGroup.Separator />
+          <TextAlignCenter />
+          Center
+        </ToggleButton>
+        <ToggleButton id="right">
+          <ToggleButtonGroup.Separator />
+          <TextAlignRight />
+          Right
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/index.ts b/apps/docs/src/demos/en/toggle-button-group/index.ts
new file mode 100644
index 0000000..fb204e2
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/index.ts
@@ -0,0 +1,9 @@
+export {Attached} from "./attached";
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {FullWidth} from "./full-width";
+export {Orientation} from "./orientation";
+export {SelectionMode} from "./selection-mode";
+export {Sizes} from "./sizes";
+export {WithoutSeparator} from "./without-separator";
diff --git a/apps/docs/src/demos/en/toggle-button-group/orientation.tsx b/apps/docs/src/demos/en/toggle-button-group/orientation.tsx
new file mode 100644
index 0000000..232f0f7
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/orientation.tsx
@@ -0,0 +1,41 @@
+import {Bold, Italic, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Orientation() {
+  return (
+    <div className="flex items-start gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Horizontal</span>
+        <ToggleButtonGroup orientation="horizontal" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Vertical</span>
+        <ToggleButtonGroup orientation="vertical" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/selection-mode.tsx b/apps/docs/src/demos/en/toggle-button-group/selection-mode.tsx
new file mode 100644
index 0000000..c7d8d58
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/selection-mode.tsx
@@ -0,0 +1,56 @@
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function SelectionMode() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Single selection</span>
+        <ToggleButtonGroup defaultSelectedKeys={["center"]} selectionMode="single">
+          <ToggleButton id="left">
+            <TextAlignLeft />
+            Left
+          </ToggleButton>
+          <ToggleButton id="center">
+            <ToggleButtonGroup.Separator />
+            <TextAlignCenter />
+            Center
+          </ToggleButton>
+          <ToggleButton id="right">
+            <ToggleButtonGroup.Separator />
+            <TextAlignRight />
+            Right
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Multiple selection</span>
+        <ToggleButtonGroup defaultSelectedKeys={["bold", "underline"]} selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/sizes.tsx b/apps/docs/src/demos/en/toggle-button-group/sizes.tsx
new file mode 100644
index 0000000..679bcc0
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/sizes.tsx
@@ -0,0 +1,69 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Small</span>
+        <ToggleButtonGroup selectionMode="multiple" size="sm">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Medium (default)</span>
+        <ToggleButtonGroup selectionMode="multiple" size="md">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-muted">Large</span>
+        <ToggleButtonGroup selectionMode="multiple" size="lg">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Bold />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Italic />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Underline />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Strikethrough />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button-group/without-separator.tsx b/apps/docs/src/demos/en/toggle-button-group/without-separator.tsx
new file mode 100644
index 0000000..a6e5e06
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button-group/without-separator.tsx
@@ -0,0 +1,21 @@
+import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
+import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
+
+export function WithoutSeparator() {
+  return (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="Bold" id="bold">
+        <Bold />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Italic" id="italic">
+        <Italic />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Underline" id="underline">
+        <Underline />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+        <Strikethrough />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/basic.tsx b/apps/docs/src/demos/en/toggle-button/basic.tsx
new file mode 100644
index 0000000..a0d1eaf
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/basic.tsx
@@ -0,0 +1,11 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <ToggleButton>
+      <Heart />
+      Like
+    </ToggleButton>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/controlled.tsx b/apps/docs/src/demos/en/toggle-button/controlled.tsx
new file mode 100644
index 0000000..b0f94c3
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/controlled.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import {Heart, HeartFill} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+import {useState} from "react";
+
+export function Controlled() {
+  const [isSelected, setIsSelected] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <ToggleButton isSelected={isSelected} onChange={setIsSelected}>
+        {({isSelected: selected}) => (
+          <>
+            {selected ? <HeartFill /> : <Heart />}
+            {selected ? "Liked" : "Like"}
+          </>
+        )}
+      </ToggleButton>
+      <p className="text-sm text-muted">
+        Status: <span className="font-medium">{isSelected ? "Selected" : "Not selected"}</span>
+      </p>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/disabled.tsx b/apps/docs/src/demos/en/toggle-button/disabled.tsx
new file mode 100644
index 0000000..ca6ea36
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/disabled.tsx
@@ -0,0 +1,17 @@
+import {Heart, HeartFill} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Disabled() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton isDisabled>
+        <Heart />
+        Like
+      </ToggleButton>
+      <ToggleButton defaultSelected isDisabled>
+        <HeartFill />
+        Like
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/icon-only.tsx b/apps/docs/src/demos/en/toggle-button/icon-only.tsx
new file mode 100644
index 0000000..bf95022
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/icon-only.tsx
@@ -0,0 +1,15 @@
+import {Bookmark, Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function IconOnly() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton isIconOnly aria-label="Like">
+        <Heart />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Bookmark" variant="ghost">
+        <Bookmark />
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/index.ts b/apps/docs/src/demos/en/toggle-button/index.ts
new file mode 100644
index 0000000..bde862d
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/index.ts
@@ -0,0 +1,6 @@
+export {Basic} from "./basic";
+export {Controlled} from "./controlled";
+export {Disabled} from "./disabled";
+export {IconOnly} from "./icon-only";
+export {Sizes} from "./sizes";
+export {Variants} from "./variants";
diff --git a/apps/docs/src/demos/en/toggle-button/sizes.tsx b/apps/docs/src/demos/en/toggle-button/sizes.tsx
new file mode 100644
index 0000000..cfcea82
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/sizes.tsx
@@ -0,0 +1,34 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Sizes() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center gap-3">
+        <ToggleButton size="sm">
+          <Heart />
+          Small
+        </ToggleButton>
+        <ToggleButton size="md">
+          <Heart />
+          Medium
+        </ToggleButton>
+        <ToggleButton size="lg">
+          <Heart />
+          Large
+        </ToggleButton>
+      </div>
+      <div className="flex items-center gap-3">
+        <ToggleButton isIconOnly aria-label="Like" size="sm">
+          <Heart />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Like" size="md">
+          <Heart />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Like" size="lg">
+          <Heart />
+        </ToggleButton>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toggle-button/variants.tsx b/apps/docs/src/demos/en/toggle-button/variants.tsx
new file mode 100644
index 0000000..1aa76ad
--- /dev/null
+++ b/apps/docs/src/demos/en/toggle-button/variants.tsx
@@ -0,0 +1,17 @@
+import {Heart} from "@gravity-ui/icons";
+import {ToggleButton} from "@heroui/react";
+
+export function Variants() {
+  return (
+    <div className="flex items-center gap-3">
+      <ToggleButton>
+        <Heart />
+        Default
+      </ToggleButton>
+      <ToggleButton variant="ghost">
+        <Heart />
+        Ghost
+      </ToggleButton>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/toolbar/basic.tsx b/apps/docs/src/demos/en/toolbar/basic.tsx
new file mode 100644
index 0000000..e3b6b2f
--- /dev/null
+++ b/apps/docs/src/demos/en/toolbar/basic.tsx
@@ -0,0 +1,39 @@
+import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Basic() {
+  return (
+    <Toolbar aria-label="Text formatting">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="Copy">
+          <Copy />
+        </Button>
+        <Button isIconOnly aria-label="Cut">
+          <ButtonGroup.Separator />
+          <Scissors />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/en/toolbar/custom-styles.tsx b/apps/docs/src/demos/en/toolbar/custom-styles.tsx
new file mode 100644
index 0000000..a9b4e75
--- /dev/null
+++ b/apps/docs/src/demos/en/toolbar/custom-styles.tsx
@@ -0,0 +1,39 @@
+import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Attached() {
+  return (
+    <Toolbar isAttached aria-label="Text formatting">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="Copy">
+          <Copy />
+        </Button>
+        <Button isIconOnly aria-label="Cut">
+          <ButtonGroup.Separator />
+          <Scissors />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/en/toolbar/index.ts b/apps/docs/src/demos/en/toolbar/index.ts
new file mode 100644
index 0000000..6bc9e8c
--- /dev/null
+++ b/apps/docs/src/demos/en/toolbar/index.ts
@@ -0,0 +1,4 @@
+export {Basic} from "./basic";
+export {Vertical} from "./vertical";
+export {WithButtonGroup} from "./with-button-group";
+export {Attached} from "./custom-styles";
diff --git a/apps/docs/src/demos/en/toolbar/vertical.tsx b/apps/docs/src/demos/en/toolbar/vertical.tsx
new file mode 100644
index 0000000..0526ec9
--- /dev/null
+++ b/apps/docs/src/demos/en/toolbar/vertical.tsx
@@ -0,0 +1,39 @@
+import {ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, Underline} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function Vertical() {
+  return (
+    <Toolbar aria-label="Tools" orientation="vertical">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="Undo">
+          <ArrowUturnCcwLeft />
+        </Button>
+        <Button isIconOnly aria-label="Redo">
+          <ButtonGroup.Separator />
+          <ArrowUturnCwRight />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/en/toolbar/with-button-group.tsx b/apps/docs/src/demos/en/toolbar/with-button-group.tsx
new file mode 100644
index 0000000..e45de67
--- /dev/null
+++ b/apps/docs/src/demos/en/toolbar/with-button-group.tsx
@@ -0,0 +1,64 @@
+import {
+  ArrowUturnCcwLeft,
+  ArrowUturnCwRight,
+  Bold,
+  Italic,
+  TextAlignCenter,
+  TextAlignLeft,
+  TextAlignRight,
+  Underline,
+} from "@gravity-ui/icons";
+import {
+  Button,
+  ButtonGroup,
+  Separator,
+  ToggleButton,
+  ToggleButtonGroup,
+  Toolbar,
+} from "@heroui/react";
+
+export function WithButtonGroup() {
+  return (
+    <Toolbar aria-label="Editor toolbar">
+      <ButtonGroup variant="tertiary">
+        <Button>
+          <ArrowUturnCcwLeft />
+          Undo
+        </Button>
+        <Button>
+          <ButtonGroup.Separator />
+          <ArrowUturnCwRight />
+          Redo
+        </Button>
+      </ButtonGroup>
+      <Separator />
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Bold />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Italic />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Underline />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup variant="tertiary">
+        <Button isIconOnly aria-label="Align left">
+          <TextAlignLeft />
+        </Button>
+        <Button isIconOnly aria-label="Align center">
+          <ButtonGroup.Separator />
+          <TextAlignCenter />
+        </Button>
+        <Button isIconOnly aria-label="Align right">
+          <ButtonGroup.Separator />
+          <TextAlignRight />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  );
+}
diff --git a/apps/docs/src/demos/en/tooltip/basic.tsx b/apps/docs/src/demos/en/tooltip/basic.tsx
new file mode 100644
index 0000000..83ea1b2
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/basic.tsx
@@ -0,0 +1,24 @@
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipBasic() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">Hover me</Button>
+        <Tooltip.Content>
+          <p>This is a tooltip</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button isIconOnly variant="tertiary">
+          <CircleInfo />
+        </Button>
+        <Tooltip.Content>
+          <p>More information</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tooltip/custom-render-function.tsx b/apps/docs/src/demos/en/tooltip/custom-render-function.tsx
new file mode 100644
index 0000000..2e19c65
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/custom-render-function.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import {CircleInfo} from "@gravity-ui/icons";
+import {Button, Tooltip} from "@heroui/react";
+
+export function CustomRenderFunction() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">Hover me</Button>
+        <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}>
+          <p>This is a tooltip</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button isIconOnly variant="tertiary">
+          <CircleInfo />
+        </Button>
+        <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}>
+          <p>More information</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tooltip/custom-trigger.tsx b/apps/docs/src/demos/en/tooltip/custom-trigger.tsx
new file mode 100644
index 0000000..1a9d332
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/custom-trigger.tsx
@@ -0,0 +1,60 @@
+import {CircleCheckFill, CircleQuestion} from "@gravity-ui/icons";
+import {Avatar, Chip, Tooltip} from "@heroui/react";
+
+export function TooltipCustomTrigger() {
+  return (
+    <div className="flex items-center gap-6">
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="User avatar">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="Jane Doe"
+              src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
+            />
+            <Avatar.Fallback>JD</Avatar.Fallback>
+          </Avatar>
+        </Tooltip.Trigger>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <div className="flex flex-col gap-0 py-1">
+            <p className="font-semibold">Jane Doe</p>
+            <p className="text-xs text-muted">jane@example.com</p>
+          </div>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="Status chip">
+          <Chip color="success">
+            <CircleCheckFill width={12} />
+            <Chip.Label>Active</Chip.Label>
+          </Chip>
+        </Tooltip.Trigger>
+        <Tooltip.Content className="flex items-center gap-1.5">
+          <span className="relative flex size-2">
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-success opacity-75" />
+            <span className="relative inline-flex size-2 rounded-full bg-success" />
+          </span>
+          <p>Jane is currently online</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="Info icon">
+          <div className="rounded-full bg-accent-soft p-2">
+            <CircleQuestion className="text-accent-soft-foreground" />
+          </div>
+        </Tooltip.Trigger>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <div className="max-w-xs px-1 py-1.5">
+            <p className="mb-1 font-semibold">Help Information</p>
+            <p className="text-sm text-muted">
+              This is a helpful tooltip with more detailed information about this feature.
+            </p>
+          </div>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tooltip/index.ts b/apps/docs/src/demos/en/tooltip/index.ts
new file mode 100644
index 0000000..abbc34b
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/index.ts
@@ -0,0 +1,5 @@
+export {TooltipBasic as Basic} from "./basic";
+export {TooltipWithArrow as WithArrow} from "./with-arrow";
+export {TooltipPlacement as Placement} from "./placement";
+export {TooltipCustomTrigger as CustomTrigger} from "./custom-trigger";
+export {CustomRenderFunction} from "./custom-render-function";
diff --git a/apps/docs/src/demos/en/tooltip/placement.tsx b/apps/docs/src/demos/en/tooltip/placement.tsx
new file mode 100644
index 0000000..af45216
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/placement.tsx
@@ -0,0 +1,55 @@
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipPlacement() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <div />
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Top
+        </Button>
+        <Tooltip.Content showArrow placement="top">
+          <Tooltip.Arrow />
+          <p>Top placement</p>
+        </Tooltip.Content>
+      </Tooltip>
+      <div />
+
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Left
+        </Button>
+        <Tooltip.Content showArrow placement="left">
+          <Tooltip.Arrow />
+          <p>Left placement</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <div className="flex items-center justify-center">
+        <span className="text-sm text-muted">Hover buttons</span>
+      </div>
+
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Right
+        </Button>
+        <Tooltip.Content showArrow placement="right">
+          <Tooltip.Arrow />
+          <p>Right placement</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <div />
+      <Tooltip delay={0}>
+        <Button className="w-full" variant="tertiary">
+          Bottom
+        </Button>
+        <Tooltip.Content showArrow placement="bottom">
+          <Tooltip.Arrow />
+          <p>Bottom placement</p>
+        </Tooltip.Content>
+      </Tooltip>
+      <div />
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/tooltip/with-arrow.tsx b/apps/docs/src/demos/en/tooltip/with-arrow.tsx
new file mode 100644
index 0000000..57a6c2a
--- /dev/null
+++ b/apps/docs/src/demos/en/tooltip/with-arrow.tsx
@@ -0,0 +1,23 @@
+import {Button, Tooltip} from "@heroui/react";
+
+export function TooltipWithArrow() {
+  return (
+    <div className="flex items-center gap-4">
+      <Tooltip delay={0}>
+        <Button variant="secondary">With Arrow</Button>
+        <Tooltip.Content showArrow>
+          <Tooltip.Arrow />
+          <p>Tooltip with arrow indicator</p>
+        </Tooltip.Content>
+      </Tooltip>
+
+      <Tooltip delay={0}>
+        <Button variant="primary">Custom Offset</Button>
+        <Tooltip.Content showArrow offset={12}>
+          <Tooltip.Arrow />
+          <p>Custom offset from trigger</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
diff --git a/apps/docs/src/demos/en/typography/default.tsx b/apps/docs/src/demos/en/typography/default.tsx
new file mode 100644
index 0000000..db2b118
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/default.tsx
@@ -0,0 +1,20 @@
+import {Typography} from "@heroui/react";
+
+export const Default = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography type="h1">Build better interfaces</Typography>
+      <Typography type="h2">Typography that stays semantic</Typography>
+      <Typography type="h3">Composable by default</Typography>
+      <Typography type="h4">Small heading</Typography>
+      <Typography>
+        HeroUI Typography uses React Aria Components Text as the primitive, with semantic typography
+        types and render-prop polymorphism.
+      </Typography>
+      <Typography color="muted" type="body-sm">
+        Smaller muted body copy for secondary descriptions.
+      </Typography>
+      <Typography type="code">pnpm add @heroui/react</Typography>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/en/typography/index.ts b/apps/docs/src/demos/en/typography/index.ts
new file mode 100644
index 0000000..f5c1316
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/index.ts
@@ -0,0 +1,5 @@
+export {Default} from "./default";
+export {Primitives} from "./primitives";
+export {Prose} from "./prose";
+export {RenderProps} from "./render-props";
+export {TypographyScale} from "./typography-scale";
diff --git a/apps/docs/src/demos/en/typography/primitives.tsx b/apps/docs/src/demos/en/typography/primitives.tsx
new file mode 100644
index 0000000..a9c8883
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/primitives.tsx
@@ -0,0 +1,17 @@
+import {Typography} from "@heroui/react";
+
+export const Primitives = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography.Heading level={1}>Dashboard</Typography.Heading>
+      <Typography.Paragraph>
+        Convenience primitives are thin wrappers over Typography, so you can choose explicit
+        composition without learning a second styling system.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" size="sm">
+        Paragraph supports base, sm, and xs sizes.
+      </Typography.Paragraph>
+      <Typography.Code>Typography.Code</Typography.Code>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/en/typography/prose.tsx b/apps/docs/src/demos/en/typography/prose.tsx
new file mode 100644
index 0000000..d9913ca
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/prose.tsx
@@ -0,0 +1,18 @@
+import {Typography} from "@heroui/react";
+
+export const Prose = () => {
+  return (
+    <Typography.Prose className="flex max-w-xl flex-col gap-3">
+      <h1>Prose title</h1>
+      <p>
+        Prose is for authored content where the markup is already semantic and HeroUI applies the
+        default typography rhythm.
+      </p>
+      <h2>Section title</h2>
+      <p>
+        Inline code like <code>render</code> receives the same code treatment as the Typography
+        primitive.
+      </p>
+    </Typography.Prose>
+  );
+};
diff --git a/apps/docs/src/demos/en/typography/render-props.tsx b/apps/docs/src/demos/en/typography/render-props.tsx
new file mode 100644
index 0000000..7dfc01c
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/render-props.tsx
@@ -0,0 +1,16 @@
+"use client";
+
+import {Typography} from "@heroui/react";
+
+export const RenderProps = () => {
+  return (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography render={({children, ...domProps}) => <h2 {...domProps}>{children}</h2>} type="h1">
+        H1 visual style, h2 semantic element
+      </Typography>
+      <Typography render={({children, ...domProps}) => <span {...domProps}>{children}</span>}>
+        The render prop can swap the underlying element while preserving HeroUI props and styles.
+      </Typography>
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/en/typography/typography-scale.tsx b/apps/docs/src/demos/en/typography/typography-scale.tsx
new file mode 100644
index 0000000..c9c8b34
--- /dev/null
+++ b/apps/docs/src/demos/en/typography/typography-scale.tsx
@@ -0,0 +1,80 @@
+import {Typography} from "@heroui/react";
+
+const scale = [
+  {
+    label: "h1",
+    meta: "36px / 600 / 1.11 / tight",
+    sample: "Build better interfaces",
+    type: "h1" as const,
+  },
+  {
+    label: "h2",
+    meta: "30px / 600 / 1.17 / tight",
+    sample: "Built for the intelligence age",
+    type: "h2" as const,
+  },
+  {
+    label: "h3",
+    meta: "24px / 600 / 1.25 / tight",
+    sample: "Pricing on your terms",
+    type: "h3" as const,
+  },
+  {
+    label: "h4",
+    meta: "20px / 600 / 1.33 / tight",
+    sample: "Apply to the startup program",
+    type: "h4" as const,
+  },
+  {
+    label: "h5",
+    meta: "18px / 600 / 1.39 / tight",
+    sample: "Card titles",
+    type: "h5" as const,
+  },
+  {
+    label: "h6",
+    meta: "16px / 600 / 1.50 / tight",
+    sample: "Smaller feature headers",
+    type: "h6" as const,
+  },
+  {
+    label: "body",
+    meta: "16px / 400 / 1.75",
+    sample: "Primary body text used across documentation, marketing copy, and descriptions.",
+    type: "body" as const,
+  },
+  {
+    label: "body-sm",
+    meta: "14px / 400 / 1.50",
+    sample: "Secondary body, table cells, navigation, and sidebar items.",
+    type: "body-sm" as const,
+  },
+  {
+    label: "body-xs",
+    meta: "12px / 400 / 1.25",
+    sample: "Captions, badges, helper text, and fine print.",
+    type: "body-xs" as const,
+  },
+  {
+    label: "code",
+    meta: "14px / mono",
+    sample: "pnpm add @heroui/react",
+    type: "code" as const,
+  },
+] as const;
+
+export const TypographyScale = () => {
+  return (
+    <div className="flex w-full flex-col divide-y divide-border">
+      {scale.map((row) => (
+        <div key={row.label} className="grid grid-cols-[160px_1fr] items-center gap-8 py-5">
+          <div className="flex shrink-0 flex-col gap-0.5">
+            <span className="text-sm font-semibold text-foreground">{row.label}</span>
+            <span className="text-xs whitespace-nowrap text-muted">{row.meta}</span>
+          </div>
+          <Typography type={row.type}>{row.sample}</Typography>
+        </div>
+      ))}
+    </div>
+  );
+};
diff --git a/apps/docs/src/demos/index.ts b/apps/docs/src/demos/index.ts
new file mode 100644
index 0000000..c2c13f9
--- /dev/null
+++ b/apps/docs/src/demos/index.ts
@@ -0,0 +1,59 @@
+import type {ComponentType} from "react";
+
+import {demos as cnDemos} from "./cn";
+import {demos as enDemos} from "./en";
+
+export type Lang = "en" | "cn";
+
+export const DEFAULT_LANG: Lang = "en";
+
+export interface DemoItem {
+  loader: () => Promise<ComponentType>;
+  /**
+   * Source file path relative to `src/demos`, used by `ComponentSource` to
+   * load the raw code from disk. Always lang-prefixed, e.g.
+   * `en/accordion/basic.tsx` or `cn/accordion/basic.tsx`.
+   */
+  file: string;
+}
+
+const registries: Record<Lang, Record<string, DemoItem>> = {
+  cn: cnDemos,
+  en: enDemos,
+};
+
+function isLang(value: string | undefined): value is Lang {
+  return value === "en" || value === "cn";
+}
+
+function resolveLang(lang?: string): Lang {
+  return isLang(lang) ? lang : DEFAULT_LANG;
+}
+
+/**
+ * Look up a demo by registry key. If a translation does not exist for the
+ * requested `lang`, falls back to the {@link DEFAULT_LANG} registry so we can
+ * translate demos incrementally without breaking pages.
+ */
+export function getDemo(name: string, lang?: string): DemoItem | undefined {
+  const resolved = resolveLang(lang);
+
+  return registries[resolved]?.[name] ?? registries[DEFAULT_LANG][name];
+}
+
+/** Number of unique components covered by demos in `lang`. */
+export function getComponentCount(lang?: string): number {
+  const resolved = resolveLang(lang);
+  const uniqueComponents = new Set(
+    Object.values(registries[resolved]).map((demo) => demo.file.match(/^[^/]+\/([^/]+)\//)?.[1]),
+  );
+
+  return uniqueComponents.size;
+}
+
+/** Total number of demo examples registered for `lang`. */
+export function getExampleCount(lang?: string): number {
+  const resolved = resolveLang(lang);
+
+  return Object.keys(registries[resolved]).length;
+}
diff --git a/apps/docs/src/hooks/use-code-panel.tsx b/apps/docs/src/hooks/use-code-panel.tsx
new file mode 100644
index 0000000..abf9db1
--- /dev/null
+++ b/apps/docs/src/hooks/use-code-panel.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import type {ReactElement, ReactNode} from "react";
+
+import {createContext, useCallback, useContext, useMemo, useState} from "react";
+
+interface CodePanelContextType {
+  isCodeVisible: boolean;
+  setIsCodeVisible: (visible: boolean) => void;
+  toggleCode: () => void;
+}
+
+const CodePanelContext = createContext<CodePanelContextType | undefined>(undefined);
+
+export function useCodePanel(): CodePanelContextType {
+  const context = useContext(CodePanelContext);
+
+  if (!context) {
+    throw new Error("useCodePanel must be used within CodePanelProvider");
+  }
+
+  return context;
+}
+
+interface CodePanelProviderProps {
+  children: ReactNode;
+}
+
+export function CodePanelProvider({children}: CodePanelProviderProps): ReactElement {
+  const [isCodeVisible, setIsCodeVisible] = useState(false);
+
+  const toggleCode = useCallback(() => {
+    setIsCodeVisible((prev) => !prev);
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      isCodeVisible,
+      setIsCodeVisible,
+      toggleCode,
+    }),
+    [isCodeVisible, toggleCode],
+  );
+
+  return <CodePanelContext value={value}>{children}</CodePanelContext>;
+}
diff --git a/apps/docs/src/hooks/use-current-framework.ts b/apps/docs/src/hooks/use-current-framework.ts
new file mode 100644
index 0000000..7d7a6ae
--- /dev/null
+++ b/apps/docs/src/hooks/use-current-framework.ts
@@ -0,0 +1,41 @@
+"use client";
+
+import {usePathname} from "next/navigation";
+
+import {i18n} from "@/lib/i18n";
+
+export type Framework = "web" | "native";
+
+// Default routes for each framework (without locale prefix)
+export const defaultRoutes = {
+  native: "/docs/native/getting-started",
+  web: "/docs/react/getting-started",
+} as const;
+
+const NATIVE_DOCS_PATH = /\/docs\/native(?:\/|$)/;
+
+export function isNativeDocsPath(pathname: string): boolean {
+  return NATIVE_DOCS_PATH.test(pathname);
+}
+
+export function getLocaleFromPathname(pathname: string): (typeof i18n)["languages"][number] {
+  const segment = pathname.split("/").filter(Boolean)[0];
+
+  return i18n.languages.includes(segment as (typeof i18n)["languages"][number])
+    ? (segment as (typeof i18n)["languages"][number])
+    : i18n.defaultLanguage;
+}
+
+export function getDefaultRoute(framework: Framework, pathname: string): string {
+  return `/${getLocaleFromPathname(pathname)}${defaultRoutes[framework]}`;
+}
+
+/**
+ * Hook to detect the current framework based on the pathname
+ * @returns "native" if pathname includes "/docs/native", otherwise "web"
+ */
+export function useCurrentFramework(): Framework {
+  const pathname = usePathname();
+
+  return isNativeDocsPath(pathname) ? "native" : "web";
+}
diff --git a/apps/docs/src/hooks/use-dictionary.tsx b/apps/docs/src/hooks/use-dictionary.tsx
new file mode 100644
index 0000000..6948d5c
--- /dev/null
+++ b/apps/docs/src/hooks/use-dictionary.tsx
@@ -0,0 +1,27 @@
+"use client";
+
+import type {Dictionary} from "@/lib/dictionaries";
+import type {ReactElement, ReactNode} from "react";
+
+import {createContext, useContext} from "react";
+
+const DictionaryContext = createContext<Dictionary | undefined>(undefined);
+
+export function useDictionary(): Dictionary {
+  const context = useContext(DictionaryContext);
+
+  if (!context) {
+    throw new Error("useDictionary must be used within DictionaryProvider");
+  }
+
+  return context;
+}
+
+interface DictionaryProviderProps {
+  dict: Dictionary;
+  children: ReactNode;
+}
+
+export function DictionaryProvider({children, dict}: DictionaryProviderProps): ReactElement {
+  return <DictionaryContext value={dict}>{children}</DictionaryContext>;
+}
diff --git a/apps/docs/src/hooks/use-global-intersection-observer.ts b/apps/docs/src/hooks/use-global-intersection-observer.ts
new file mode 100644
index 0000000..cc98cda
--- /dev/null
+++ b/apps/docs/src/hooks/use-global-intersection-observer.ts
@@ -0,0 +1,152 @@
+"use client";
+
+import {useEffect, useRef, useState} from "react";
+
+type ObserverCallback = (isIntersecting: boolean) => void;
+
+interface ObserverConfig {
+  rootMargin?: string;
+  threshold?: number | number[];
+}
+
+/**
+ * Global IntersectionObserver Manager
+ * Single observer instance manages all component visibility detection with RAF throttling
+ */
+class GlobalIntersectionObserverManager {
+  private observers: Map<string, IntersectionObserver> = new Map();
+  private callbacks: Map<Element, ObserverCallback> = new Map();
+  private pendingUpdates: Map<Element, boolean> = new Map();
+  private rafId: number | null = null;
+
+  // Cache config keys to avoid repeated string concatenation
+  private getConfigKey(config: ObserverConfig): string {
+    return `${config.rootMargin || "0px"}-${String(config.threshold || 0)}`;
+  }
+
+  private getObserver(config: ObserverConfig): IntersectionObserver {
+    const key = this.getConfigKey(config);
+
+    if (!this.observers.has(key)) {
+      const observer = new IntersectionObserver(
+        (entries) => {
+          // Batch collect all changes
+          for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i]!;
+
+            this.pendingUpdates.set(entry.target, entry.isIntersecting);
+          }
+          this.scheduleUpdate();
+        },
+        {
+          rootMargin: config.rootMargin,
+          threshold: config.threshold,
+        },
+      );
+
+      this.observers.set(key, observer);
+    }
+
+    return this.observers.get(key)!;
+  }
+
+  // RAF throttling for batch updates
+  private scheduleUpdate() {
+    if (this.rafId !== null) return;
+
+    this.rafId = requestAnimationFrame(() => {
+      this.rafId = null;
+
+      // Process all pending updates in a single batch
+      this.pendingUpdates.forEach((isIntersecting, element) => {
+        const callback = this.callbacks.get(element);
+
+        if (callback) {
+          callback(isIntersecting);
+        }
+      });
+
+      this.pendingUpdates.clear();
+    });
+  }
+
+  observe(element: Element, callback: ObserverCallback, config: ObserverConfig = {}) {
+    const observer = this.getObserver(config);
+
+    this.callbacks.set(element, callback);
+    observer.observe(element);
+  }
+
+  unobserve(element: Element, config: ObserverConfig = {}) {
+    const observer = this.getObserver(config);
+
+    observer.unobserve(element);
+    this.callbacks.delete(element);
+    this.pendingUpdates.delete(element);
+  }
+
+  cleanup() {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+
+    this.observers.forEach((observer) => observer.disconnect());
+    this.observers.clear();
+    this.callbacks.clear();
+    this.pendingUpdates.clear();
+  }
+}
+
+// Global singleton instance
+const globalObserverManager = new GlobalIntersectionObserverManager();
+
+/**
+ * useGlobalIntersectionObserver Hook
+ * Uses global observer manager for efficient element visibility detection
+ *
+ * @example
+ * const [ref, isVisible] = useGlobalIntersectionObserver({
+ *   rootMargin: "100px 0px",
+ *   threshold: 0.1,
+ *   initialIsIntersecting: false
+ * });
+ */
+export function useGlobalIntersectionObserver<T extends Element = HTMLDivElement>(
+  config: {
+    initialIsIntersecting?: boolean;
+    rootMargin?: string;
+    threshold?: number | number[];
+  } = {},
+) {
+  const {initialIsIntersecting = true, rootMargin = "0px", threshold = 0} = config;
+
+  const [isIntersecting, setIsIntersecting] = useState(initialIsIntersecting);
+  const elementRef = useRef<T | null>(null);
+
+  // Stable callback reference to prevent unnecessary effect re-runs
+  const callbackRef = useRef<ObserverCallback>((visible: boolean) => {
+    setIsIntersecting(visible);
+  });
+
+  useEffect(() => {
+    const element = elementRef.current;
+
+    if (!element || !callbackRef.current) return;
+
+    globalObserverManager.observe(element, callbackRef.current, {rootMargin, threshold});
+
+    return () => {
+      if (element) {
+        globalObserverManager.unobserve(element, {rootMargin, threshold});
+      }
+    };
+  }, [rootMargin, threshold]);
+
+  return [elementRef, isIntersecting] as const;
+}
+
+// Cleanup utility (rarely needed)
+export function cleanupGlobalObserver() {
+  globalObserverManager.cleanup();
+}
diff --git a/apps/docs/src/hooks/use-is-mobile-device.ts b/apps/docs/src/hooks/use-is-mobile-device.ts
new file mode 100644
index 0000000..0aa4eb1
--- /dev/null
+++ b/apps/docs/src/hooks/use-is-mobile-device.ts
@@ -0,0 +1,18 @@
+import {useState} from "react";
+
+/**
+ * Hook to detect if the current device is a mobile device (iOS/Android)
+ * @returns boolean indicating if the device is mobile
+ */
+export function useIsMobileDevice(): boolean {
+  // Initialize state synchronously if possible, avoiding setState in effect
+  const [isMobile] = useState(() => {
+    if (typeof window === "undefined") {
+      return false;
+    }
+
+    return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+  });
+
+  return isMobile;
+}
diff --git a/apps/docs/src/hooks/use-is-mounted.ts b/apps/docs/src/hooks/use-is-mounted.ts
new file mode 100644
index 0000000..7e1be68
--- /dev/null
+++ b/apps/docs/src/hooks/use-is-mounted.ts
@@ -0,0 +1,12 @@
+import {useSyncExternalStore} from "react";
+
+const emptySubscribe = () => () => {};
+const getSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+export function useIsMounted(): boolean {
+  // Initialize as true since component is mounted when hook is called
+  const isMounted = useSyncExternalStore(emptySubscribe, getSnapshot, getServerSnapshot);
+
+  return isMounted;
+}
diff --git a/apps/docs/src/hooks/use-key-press.tsx b/apps/docs/src/hooks/use-key-press.tsx
new file mode 100644
index 0000000..144e90e
--- /dev/null
+++ b/apps/docs/src/hooks/use-key-press.tsx
@@ -0,0 +1,56 @@
+import {useEffect} from "react";
+
+interface UseKeyPressOptions {
+  alt?: boolean;
+  ctrl?: boolean;
+  shift?: boolean;
+  enabled?: boolean;
+}
+
+export function useKeyPress(
+  key: string,
+  callback: (event: KeyboardEvent) => void,
+  options: UseKeyPressOptions = {},
+) {
+  const {alt = false, ctrl = false, enabled = true, shift = false} = options;
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleKeyPress = (event: KeyboardEvent) => {
+      // Ignore key presses when typing in form elements or editable content
+      const target = event.target as HTMLElement;
+      const isEditableElement =
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.tagName === "SELECT" ||
+        target.isContentEditable;
+
+      if (isEditableElement) return;
+
+      const isTargetKey = event.key.toLowerCase() === key.toLowerCase();
+
+      // Check if modifiers match EXACTLY
+      const modifiersMatch =
+        (event.ctrlKey || event.metaKey) === ctrl &&
+        event.shiftKey === shift &&
+        event.altKey === alt;
+
+      if (isTargetKey && modifiersMatch) {
+        // Auto-prevent default if using any modifiers
+        if (ctrl || shift || alt) {
+          event.preventDefault();
+        }
+        callback(event);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyPress);
+
+    return () => {
+      window.removeEventListener("keydown", handleKeyPress);
+    };
+  }, [key, callback, ctrl, shift, alt, enabled]);
+}
+
+export default useKeyPress;
diff --git a/apps/docs/src/icons/apple.tsx b/apps/docs/src/icons/apple.tsx
new file mode 100644
index 0000000..152feeb
--- /dev/null
+++ b/apps/docs/src/icons/apple.tsx
@@ -0,0 +1,31 @@
+import type {Ref, SVGProps} from "react";
+
+import {forwardRef, memo} from "react";
+import {cn} from "tailwind-variants";
+
+const IconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-foreground", className)}
+      fill="none"
+      focusable="false"
+      height={16}
+      role="presentation"
+      viewBox="0 0 16 16"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M11.367 13.52c-.654.633-1.367.533-2.054.233-.726-.306-1.393-.32-2.16 0-.96.414-1.466.294-2.04-.233-3.253-3.353-2.773-8.46.92-8.647.9.047 1.527.494 2.054.534.786-.16 1.54-.62 2.38-.56 1.006.08 1.766.48 2.266 1.2-2.08 1.246-1.586 3.986.32 4.753-.38 1-.873 1.993-1.693 2.727l.007-.007ZM8.02 4.833C7.92 3.347 9.127 2.12 10.513 2c.194 1.72-1.56 3-2.493 2.833Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export const AppleIcon = memo(forwardRef(IconRender));
diff --git a/apps/docs/src/icons/dev.tsx b/apps/docs/src/icons/dev.tsx
new file mode 100644
index 0000000..a336a7d
--- /dev/null
+++ b/apps/docs/src/icons/dev.tsx
@@ -0,0 +1,661 @@
+import type {SVGProps} from "react";
+
+export type IconSvgProps = SVGProps<SVGSVGElement> & {
+  size?: number;
+};
+
+import React from "react";
+
+const GithubIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg height={size || height} viewBox="0 0 24 24" width={size || width} {...props}>
+      <path
+        clipRule="evenodd"
+        d="M12.026 2c-5.509 0-9.974 4.465-9.974 9.974 0 4.406 2.857 8.145 6.821 9.465.499.09.679-.217.679-.481 0-.237-.008-.865-.011-1.696-2.775.602-3.361-1.338-3.361-1.338-.452-1.152-1.107-1.459-1.107-1.459-.905-.619.069-.605.069-.605 1.002.07 1.527 1.028 1.527 1.028.89 1.524 2.336 1.084 2.902.829.091-.645.351-1.085.635-1.334-2.214-.251-4.542-1.107-4.542-4.93 0-1.087.389-1.979 1.024-2.675-.101-.253-.446-1.268.099-2.64 0 0 .837-.269 2.742 1.021a9.582 9.582 0 0 1 2.496-.336 9.554 9.554 0 0 1 2.496.336c1.906-1.291 2.742-1.021 2.742-1.021.545 1.372.203 2.387.099 2.64.64.696 1.024 1.587 1.024 2.675 0 3.833-2.33 4.675-4.552 4.922.355.308.675.916.675 1.846 0 1.334-.012 2.41-.012 2.737 0 .267.178.577.687.479C19.146 20.115 22 16.379 22 11.974 22 6.465 17.535 2 12.026 2z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+const NextJsIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      height={size || height}
+      viewBox="0 0 256 256"
+      width={size || width}
+      {...props}
+    >
+      <path
+        d="M119.617.069c-.55.05-2.302.225-3.879.35-36.36 3.278-70.419 22.894-91.99 53.044-12.012 16.764-19.694 35.78-22.597 55.922C.125 116.415 0 118.492 0 128.025c0 9.533.125 11.61 1.151 18.64 6.957 48.065 41.165 88.449 87.56 103.411 8.309 2.678 17.067 4.504 27.027 5.605 3.879.425 20.645.425 24.524 0 17.192-1.902 31.756-6.155 46.12-13.486 2.202-1.126 2.628-1.426 2.327-1.677-.2-.15-9.584-12.735-20.845-27.948l-20.47-27.648-25.65-37.956c-14.114-20.868-25.725-37.932-25.825-37.932-.1-.025-.2 16.84-.25 37.431-.076 36.055-.1 37.506-.551 38.357-.65 1.226-1.151 1.727-2.202 2.277-.801.4-1.502.475-5.28.475h-4.33l-1.15-.725a4.679 4.679 0 0 1-1.677-1.827l-.526-1.126.05-50.166.075-50.192.776-.976c.4-.525 1.251-1.2 1.852-1.526 1.026-.5 1.426-.55 5.755-.55 5.105 0 5.956.2 7.282 1.651.376.4 14.264 21.318 30.88 46.514 16.617 25.195 39.34 59.599 50.5 76.488l20.27 30.7 1.026-.675c9.084-5.905 18.693-14.312 26.3-23.07 16.191-18.59 26.626-41.258 30.13-65.428 1.026-7.031 1.151-9.108 1.151-18.64 0-9.534-.125-11.61-1.151-18.641-6.957-48.065-41.165-88.449-87.56-103.411-8.184-2.652-16.892-4.479-26.652-5.58-2.402-.25-18.943-.525-21.02-.325zm52.401 77.414c1.201.6 2.177 1.752 2.527 2.953.2.65.25 14.562.2 45.913l-.074 44.987-7.933-12.16-7.958-12.16v-32.702c0-21.143.1-33.028.25-33.603.4-1.401 1.277-2.502 2.478-3.153 1.026-.525 1.401-.575 5.33-.575 3.704 0 4.354.05 5.18.5z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+const NpmIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="currentColor"
+      focusable="false"
+      height={height}
+      stroke="currentColor"
+      strokeWidth="0"
+      viewBox="0 0 576 512"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M288 288h-32v-64h32v64zm288-128v192H288v32H160v-32H0V160h576zm-416 32H32v128h64v-96h32v96h32V192zm160 0H192v160h64v-32h64V192zm224 0H352v128h64v-96h32v96h32v-96h32v96h32V192z" />
+    </svg>
+  );
+};
+
+const CLIBoldIcon = ({...props}: IconSvgProps) => (
+  <svg
+    aria-hidden="true"
+    fill="none"
+    focusable="false"
+    height="1em"
+    role="presentation"
+    viewBox="0 0 24 24"
+    width="1em"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M3.464 3.464C2 4.93 2 7.286 2 12c0 4.714 0 7.071 1.464 8.535C4.93 22 7.286 22 12 22c4.714 0 7.071 0 8.535-1.465C22 19.072 22 16.714 22 12s0-7.071-1.465-8.536C19.072 2 16.714 2 12 2S4.929 2 3.464 3.464m2.96 6.056a.75.75 0 0 1 1.056-.096l.277.23c.605.504 1.12.933 1.476 1.328c.379.42.674.901.674 1.518s-.295 1.099-.674 1.518c-.356.395-.871.824-1.476 1.328l-.277.23a.75.75 0 1 1-.96-1.152l.234-.195c.659-.55 1.09-.91 1.366-1.216c.262-.29.287-.427.287-.513c0-.086-.025-.222-.287-.513c-.277-.306-.707-.667-1.366-1.216l-.234-.195a.75.75 0 0 1-.096-1.056M17.75 15a.75.75 0 0 1-.75.75h-5a.75.75 0 0 1 0-1.5h5a.75.75 0 0 1 .75.75"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+const NpmSmallIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      focusable="false"
+      height={height}
+      stroke="currentColor"
+      strokeWidth="0"
+      viewBox="0 0 16 16"
+      width={width}
+      {...props}
+    >
+      <path d="M0 0v16h16v-16h-16zM13 13h-2v-8h-3v8h-5v-10h10v10z" />
+    </svg>
+  );
+};
+
+// #E1251B
+export const AdobeIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      aria-label="Adobe"
+      fill="currentColor"
+      focusable="false"
+      height={height}
+      viewBox="0 0 30 26"
+      width={width}
+      {...props}
+    >
+      <polygon points="19,0 30,0 30,26" />
+      <polygon points="11.1,0 0,0 0,26" />
+      <polygon points="15,9.6 22.1,26 17.5,26 15.4,20.8 10.2,20.8" />
+    </svg>
+  );
+};
+
+const FigmaIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="none"
+      height={size || height}
+      viewBox="0 0 38 57"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M19 28.5a9.5 9.5 0 1 1 19 0 9.5 9.5 0 0 1-19 0Z" fill="#1ABCFE" />
+      <path d="M0 47.5A9.5 9.5 0 0 1 9.5 38H19v9.5a9.5 9.5 0 1 1-19 0Z" fill="#0ACF83" />
+      <path d="M19 0v19h9.5a9.5 9.5 0 1 0 0-19H19Z" fill="#FF7262" />
+      <path d="M0 9.5A9.5 9.5 0 0 0 9.5 19H19V0H9.5A9.5 9.5 0 0 0 0 9.5Z" fill="#F24E1E" />
+      <path d="M0 28.5A9.5 9.5 0 0 0 9.5 38H19V19H9.5A9.5 9.5 0 0 0 0 28.5Z" fill="#A259FF" />
+    </svg>
+  );
+};
+
+const YarnIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="currentColor"
+      focusable="false"
+      height={height}
+      stroke="currentColor"
+      strokeWidth="0"
+      viewBox="0 0 496 512"
+      width={width}
+      {...props}
+    >
+      <path d="M393.9 345.2c-39 9.3-48.4 32.1-104 47.4 0 0-2.7 4-10.4 5.8-13.4 3.3-63.9 6-68.5 6.1-12.4.1-19.9-3.2-22-8.2-6.4-15.3 9.2-22 9.2-22-8.1-5-9-9.9-9.8-8.1-2.4 5.8-3.6 20.1-10.1 26.5-8.8 8.9-25.5 5.9-35.3.8-10.8-5.7.8-19.2.8-19.2s-5.8 3.4-10.5-3.6c-6-9.3-17.1-37.3 11.5-62-1.3-10.1-4.6-53.7 40.6-85.6 0 0-20.6-22.8-12.9-43.3 5-13.4 7-13.3 8.6-13.9 5.7-2.2 11.3-4.6 15.4-9.1 20.6-22.2 46.8-18 46.8-18s12.4-37.8 23.9-30.4c3.5 2.3 16.3 30.6 16.3 30.6s13.6-7.9 15.1-5c8.2 16 9.2 46.5 5.6 65.1-6.1 30.6-21.4 47.1-27.6 57.5-1.4 2.4 16.5 10 27.8 41.3 10.4 28.6 1.1 52.7 2.8 55.3.8 1.4 13.7.8 36.4-13.2 12.8-7.9 28.1-16.9 45.4-17 16.7-.5 17.6 19.2 4.9 22.2zM496 256c0 136.9-111.1 248-248 248S0 392.9 0 256 111.1 8 248 8s248 111.1 248 248zm-79.3 75.2c-1.7-13.6-13.2-23-28-22.8-22 .3-40.5 11.7-52.8 19.2-4.8 3-8.9 5.2-12.4 6.8 3.1-44.5-22.5-73.1-28.7-79.4 7.8-11.3 18.4-27.8 23.4-53.2 4.3-21.7 3-55.5-6.9-74.5-1.6-3.1-7.4-11.2-21-7.4-9.7-20-13-22.1-15.6-23.8-1.1-.7-23.6-16.4-41.4 28-12.2.9-31.3 5.3-47.5 22.8-2 2.2-5.9 3.8-10.1 5.4h.1c-8.4 3-12.3 9.9-16.9 22.3-6.5 17.4.2 34.6 6.8 45.7-17.8 15.9-37 39.8-35.7 82.5-34 36-11.8 73-5.6 79.6-1.6 11.1 3.7 19.4 12 23.8 12.6 6.7 30.3 9.6 43.9 2.8 4.9 5.2 13.8 10.1 30 10.1 6.8 0 58-2.9 72.6-6.5 6.8-1.6 11.5-4.5 14.6-7.1 9.8-3.1 36.8-12.3 62.2-28.7 18-11.7 24.2-14.2 37.6-17.4 12.9-3.2 21-15.1 19.4-28.2z" />
+    </svg>
+  );
+};
+
+const PnpmIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="currentColor"
+      focusable="false"
+      height={height}
+      role="img"
+      stroke="currentColor"
+      strokeWidth="0"
+      viewBox="0 0 24 24"
+      width={width}
+      {...props}
+    >
+      <title />
+      <path d="M0 0v7.5h7.5V0zm8.25 0v7.5h7.498V0zm8.25 0v7.5H24V0zM8.25 8.25v7.5h7.498v-7.5zm8.25 0v7.5H24v-7.5zM0 16.5V24h7.5v-7.5zm8.25 0V24h7.498v-7.5zm8.25 0V24H24v-7.5z" />
+    </svg>
+  );
+};
+
+const AstroIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg aria-hidden="true" fill="none" focusable="false" height={height} width={width} {...props}>
+      <path
+        clipRule="evenodd"
+        d="M16.986 23.22c-3.498 0-6.986 1.694-6.986 1.694s5.924-16.1 5.937-16.131c.181-.476.457-.783.844-.783h7.11c.386 0 .673.307.843.783l5.936 16.131s-2.843-1.695-6.985-1.695l-2.637-8.14c-.1-.395-.387-.662-.713-.662-.325 0-.614.268-.712.661l-2.637 8.141zm-.572 6.477h.001-.001zM15.3 24.378c-.532 1.751-.16 4.168 1.115 5.319l.017-.061a1.42 1.42 0 00.03-.116c.16-.73.762-1.195 1.524-1.173.741.021 1.135.392 1.25 1.22.042.307.046.62.05.933l.001.098c.01.707.195 1.361.585 1.952a3.4 3.4 0 001.515 1.279l-.018-.06a4.332 4.332 0 00-.03-.1c-.488-1.476-.137-2.49 1.16-3.356l.398-.261c.293-.19.585-.38.867-.586 1.022-.747 1.665-1.732 1.817-3.007a3.404 3.404 0 00-.162-1.547c-.076.045-.148.09-.218.134-.15.094-.29.182-.437.253-1.897.921-3.902 1.035-5.944.73-1.322-.197-2.599-.547-3.52-1.651z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+const BunIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg aria-hidden="true" height={height} viewBox="0 0 32 32" width={width} {...props}>
+      <path
+        d="M29 17c0 5.65-5.82 10.23-13 10.23S3 22.61 3 17c0-3.5 2.24-6.6 5.66-8.44S14.21 4.81 16 4.81s3.32 1.54 7.34 3.71C26.76 10.36 29 13.46 29 17"
+        fill="#fbf0df"
+      />
+      <path
+        d="M16 27.65c7.32 0 13.46-4.65 13.46-10.65c0-3.72-2.37-7-5.89-8.85c-1.39-.75-2.46-1.41-3.37-2l-1.13-.69A6.14 6.14 0 0 0 16 4.35a6.88 6.88 0 0 0-3.3 1.23c-.42.24-.86.51-1.32.8c-.87.54-1.83 1.13-3 1.73C4.91 10 2.54 13.24 2.54 17c0 6 6.14 10.65 13.46 10.65Z"
+        fill="none"
+        stroke="#000"
+      />
+      <ellipse cx="21.65" cy="18.62" fill="#febbd0" rx="2.17" ry="1.28" />
+      <ellipse cx="10.41" cy="18.62" fill="#febbd0" rx="2.17" ry="1.28" />
+      <path
+        d="M11.43 18.11a2 2 0 1 0-2-2.05a2.05 2.05 0 0 0 2 2.05m9.2 0a2 2 0 1 0-2-2.05a2 2 0 0 0 2 2.05"
+        fillRule="evenodd"
+      />
+      <path
+        d="M10.79 16.19a.77.77 0 1 0-.76-.77a.76.76 0 0 0 .76.77m9.2 0a.77.77 0 1 0 0-1.53a.77.77 0 0 0 0 1.53"
+        fill="#fff"
+        fillRule="evenodd"
+      />
+      <path
+        d="M18.62 19.67a3.3 3.3 0 0 1-1.09 1.75a2.48 2.48 0 0 1-1.5.69a2.53 2.53 0 0 1-1.5-.69a3.28 3.28 0 0 1-1.08-1.75a.26.26 0 0 1 .29-.3h4.58a.27.27 0 0 1 .3.3Z"
+        fill="#b71422"
+        stroke="#000"
+        strokeWidth=".75"
+      />
+      <path
+        d="M14.93 5.75a6.09 6.09 0 0 1-2.09 4.62c-.1.09 0 .27.11.22c1.25-.49 2.94-1.94 2.23-4.88c-.03-.15-.25-.11-.25.04m.85 0a6 6 0 0 1 .57 5c0 .13.12.24.21.13c.83-1 1.54-3.11-.59-5.31c-.1-.11-.27.04-.19.17Zm1-.06a6.09 6.09 0 0 1 2.53 4.38c0 .14.21.17.24 0c.34-1.3.15-3.51-2.66-4.66c-.12-.02-.21.18-.09.27ZM9.94 9.55a6.27 6.27 0 0 0 3.89-3.33c.07-.13.28-.08.25.07c-.64 3-2.79 3.59-4.13 3.51c-.14-.01-.14-.21-.01-.25"
+        fill="#ccbea7"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+const NewNextJSIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg aria-hidden="true" fill="none" focusable="false" height={height} width={width} {...props}>
+      <mask
+        height="26"
+        id="nextjs-white_svg__a"
+        maskUnits="userSpaceOnUse"
+        width="26"
+        x="7"
+        y="7"
+        style={{
+          maskType: "alpha",
+        }}
+      >
+        <path
+          d="M20 33c7.18 0 13-5.82 13-13S27.18 7 20 7 7 12.82 7 20s5.82 13 13 13z"
+          fill="#000"
+        />
+      </mask>
+      <g mask="url(#nextjs-white_svg__a)">
+        <path
+          d="M20 32.567c6.94 0 12.567-5.627 12.567-12.567S26.94 7.433 20 7.433 7.433 13.06 7.433 20 13.06 32.567 20 32.567z"
+          fill="#000"
+          stroke="#fff"
+          strokeWidth="0.867"
+        />
+        <path
+          d="M28.596 29.753L16.987 14.8H14.8v10.396h1.75v-8.174l10.672 13.789c.482-.322.94-.676 1.374-1.058z"
+          fill="url(#nextjs-white_svg__b)"
+        />
+        <path d="M25.344 14.8h-1.733v10.4h1.733V14.8z" fill="url(#nextjs-white_svg__c)" />
+      </g>
+      <defs>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="nextjs-white_svg__b"
+          x1="22.744"
+          x2="27.872"
+          y1="23.828"
+          y2="30.183"
+        >
+          <stop stopColor="#fff" />
+          <stop offset="1" stopColor="#fff" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="nextjs-white_svg__c"
+          x1="24.478"
+          x2="24.449"
+          y1="14.8"
+          y2="22.438"
+        >
+          <stop stopColor="#fff" />
+          <stop offset="1" stopColor="#fff" stopOpacity="0" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
+
+const RemixIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="none"
+      focusable="false"
+      height={height}
+      viewBox="0 0 40 40"
+      width={width}
+      {...props}
+    >
+      <path
+        d="M29.397 26.388c.213 2.733.213 4.014.213 5.412h-6.322c0-.305.005-.583.01-.866.018-.878.036-1.794-.107-3.643-.188-2.708-1.354-3.31-3.497-3.31H9.75v-4.926h10.244c2.708 0 4.063-.823 4.063-3.005 0-1.917-1.355-3.08-4.063-3.08H9.75V8.15h11.373c6.13 0 9.177 2.896 9.177 7.521 0 3.46-2.144 5.716-5.04 6.092 2.445.489 3.874 1.88 4.137 4.625z"
+        fill="currentColor"
+      />
+      <path
+        d="M9.75 31.8v-3.672h6.685c1.116 0 1.359.828 1.359 1.322v2.35H9.75z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+const ViteIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="none"
+      focusable="false"
+      height={height}
+      viewBox="0 0 40 40"
+      width={width}
+      {...props}
+    >
+      <path
+        d="M31.881 11.61L20.886 31.563a.593.593 0 01-1.04.004L8.633 11.611c-.251-.446.125-.987.624-.897l11.007 1.997a.59.59 0 00.212 0l10.777-1.994c.497-.092.875.445.628.893z"
+        fill="url(#vite_svg__paint0_linear_41_6732)"
+      />
+      <path
+        d="M25.506 8.096l-8.137 1.618a.302.302 0 00-.241.28l-.5 8.578a.3.3 0 00.365.314l2.265-.531c.212-.05.404.14.36.356l-.673 3.345a.3.3 0 00.38.35l1.399-.43a.3.3 0 01.38.35l-1.07 5.255c-.067.328.364.507.543.226l.12-.189 6.63-13.428c.111-.225-.08-.481-.323-.433l-2.332.456a.301.301 0 01-.344-.381l1.522-5.355a.301.301 0 00-.345-.381z"
+        fill="url(#vite_svg__paint1_linear_41_6732)"
+      />
+      <defs>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="vite_svg__paint0_linear_41_6732"
+          x1="8.359"
+          x2="22.306"
+          y1="10.001"
+          y2="28.665"
+        >
+          <stop stopColor="#41D1FF" />
+          <stop offset="1" stopColor="#BD34FE" />
+        </linearGradient>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id="vite_svg__paint1_linear_41_6732"
+          x1="19.631"
+          x2="22.178"
+          y1="8.535"
+          y2="25.757"
+        >
+          <stop stopColor="#FFEA83" />
+          <stop offset="0.083" stopColor="#FFDD35" />
+          <stop offset="1" stopColor="#FFA800" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
+
+const StorybookIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="none"
+      focusable="false"
+      height={height}
+      viewBox="0 0 512 512"
+      width={width}
+      {...props}
+    >
+      <g>
+        <path
+          d="M356.5,5.2L353.9,63c-0.1,3.2,3.7,5.2,6.3,3.2l22.6-17.1L401.9,64c2.5,1.7,5.8,0,6-3l-2.2-58.8l28.4-2.2   c14.7-1,27.3,10.8,27.3,25.6v460.8c0,14.7-12.3,26.3-26.9,25.6L91.1,496.6c-13.3-0.6-24.1-11.3-24.5-24.7l-16-422.3   c-0.8-14.2,9.9-26.3,24.1-27.1L356.2,4.7L356.5,5.2z M291,198.4c0,10,67.4,5.1,76.6-1.7c0-68.2-36.7-104.3-103.6-104.3   c-67.2,0-104.5,36.8-104.5,91.6c0,94.9,128,96.6,128,148.4c0,15-6.8,23.5-22.4,23.5c-20.5,0-28.8-10.4-27.7-46.1   c0-7.7-77.8-10.3-80.4,0c-5.7,86,47.6,110.9,108.7,110.9c59.6,0,106.1-31.7,106.1-89.1c0-101.7-130.1-99-130.1-149.3   c0-20.7,15.4-23.4,24.1-23.4c9.7,0,26.7,1.5,25.4,39.8L291,198.4z"
+          fill="currentColor"
+        />
+      </g>
+    </svg>
+  );
+};
+
+const CodeSandboxIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      fill="none"
+      height={height}
+      viewBox="0 0 18 18"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M3.24284 5.11427L8.63639 2.17808C8.92945 2.01854 9.28432 2.02264 9.57361 2.18889L14.7726 5.17673C15.011 5.3137 15.1579 5.56762 15.1579 5.84251V12.1884C15.1579 12.4639 15.0103 12.7183 14.7711 12.8551L9.38463 15.9346C9.1466 16.0707 8.85406 16.0696 8.61711 15.9316L3.22361 12.7912C2.9874 12.6537 2.8421 12.4009 2.8421 12.1276V5.7887C2.8421 5.50747 2.99584 5.24873 3.24284 5.11427Z" />
+      <path
+        clipRule="evenodd"
+        d="M8.99649 9.06298V15.1165C9.10189 15.1165 9.17115 15.0936 9.26577 15.0396L14.113 12.2698C14.3044 12.1601 14.3824 11.9902 14.3824 11.7696V6.15302C14.3824 6.04235 14.3591 5.97615 14.3053 5.88373L9.15154 8.79576C9.05567 8.85054 8.99649 8.95253 8.99649 9.06298ZM11.6894 12.539C11.6894 12.6929 11.6317 12.7698 11.497 12.8468L9.88129 13.7701C9.76591 13.847 9.61201 13.8086 9.61201 13.6546V9.53835C9.61201 9.42824 9.7089 9.28555 9.80434 9.2306L13.4975 7.11477C13.6001 7.05573 13.6898 7.15029 13.6898 7.26865V9.46146C13.6898 9.5751 13.6362 9.67725 13.5359 9.73074L11.8817 10.6155C11.7814 10.669 11.6894 10.7711 11.6894 10.8848V12.539Z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+      <path
+        clipRule="evenodd"
+        d="M3.61069 11.7696V6.15297C3.61069 5.93209 3.72667 5.72398 3.91845 5.61439L8.61177 2.95996C8.71289 2.90638 8.88105 2.88303 8.99648 2.88303C9.11191 2.88303 9.28993 2.91161 9.38119 2.95997L14.036 5.61439C14.1281 5.66881 14.2533 5.79415 14.3053 5.88368L9.15033 8.8074C9.05447 8.86219 8.99648 8.96624 8.99648 9.07668V15.1165C8.89108 15.1165 8.78334 15.0936 8.68872 15.0395L3.95692 12.3082C3.76514 12.1985 3.61069 11.9904 3.61069 11.7696ZM4.30315 7.26859V9.46139C4.30315 9.61524 4.34162 9.6922 4.4955 9.76915L6.11123 10.6924C6.26511 10.7694 6.30358 10.8848 6.30358 11.0002V12.539C6.30358 12.6928 6.34205 12.7698 6.49593 12.8467L8.11167 13.77C8.26553 13.847 8.38096 13.8085 8.38096 13.6546V9.53835C8.38096 9.42292 8.34249 9.30749 8.18863 9.23059L4.57243 7.15319C4.45703 7.07625 4.30315 7.11472 4.30315 7.26859ZM10.6122 4.65264L9.18881 5.46051C9.07343 5.53745 8.91953 5.53745 8.80415 5.46051L7.38074 4.65264C7.28705 4.59968 7.16683 4.59995 7.07298 4.65264L5.30337 5.65286C5.14949 5.7298 5.14949 5.88368 5.30337 5.96062L8.84257 7.99953C8.9373 8.05375 9.05566 8.05375 9.15033 7.99953L12.6896 5.96062C12.805 5.88368 12.8435 5.7298 12.6896 5.65286L10.92 4.65264C10.8261 4.59995 10.7059 4.59968 10.6122 4.65264Z"
+        fill="currentColor"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+const StackblitzIcon: React.FC<IconSvgProps> = ({...props}) => {
+  return (
+    <svg
+      height={16}
+      viewBox="0 0 1024 1024"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M848 359.3H627.7L825.8 109c4.1-5.3.4-13-6.3-13H436c-2.8 0-5.5 1.5-6.9 4L170 547.5c-3.1 5.3.7 12 6.9 12h174.4l-89.4 357.6c-1.9 7.8 7.5 13.3 13.3 7.7L853.5 373c5.2-4.9 1.7-13.7-5.5-13.7M378.2 732.5l60.3-241H281.1l189.6-327.4h224.6L487 427.4h211z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+const JavascriptIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={height}
+      viewBox="0 0 24 24"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M3,3H21V21H3V3M7.73,18.04C8.13,18.89 8.92,19.59 10.27,19.59C11.77,19.59 12.8,18.79 12.8,17.04V11.26H11.1V17C11.1,17.86 10.75,18.08 10.2,18.08C9.62,18.08 9.38,17.68 9.11,17.21L7.73,18.04M13.71,17.86C14.21,18.84 15.22,19.59 16.8,19.59C18.4,19.59 19.6,18.76 19.6,17.23C19.6,15.82 18.79,15.19 17.35,14.57L16.93,14.39C16.2,14.08 15.89,13.87 15.89,13.37C15.89,12.96 16.2,12.64 16.7,12.64C17.18,12.64 17.5,12.85 17.79,13.37L19.1,12.5C18.55,11.54 17.77,11.17 16.7,11.17C15.19,11.17 14.22,12.13 14.22,13.4C14.22,14.78 15.03,15.43 16.25,15.95L16.67,16.13C17.45,16.47 17.91,16.68 17.91,17.26C17.91,17.74 17.46,18.09 16.76,18.09C15.93,18.09 15.45,17.66 15.09,17.06L13.71,17.86Z" />
+    </svg>
+  );
+};
+
+const TypescriptIcon: React.FC<IconSvgProps> = ({height = "1em", width = "1em", ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={height}
+      viewBox="0 0 24 24"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M3,3H21V21H3V3M13.71,17.86C14.21,18.84 15.22,19.59 16.8,19.59C18.4,19.59 19.6,18.76 19.6,17.23C19.6,15.82 18.79,15.19 17.35,14.57L16.93,14.39C16.2,14.08 15.89,13.87 15.89,13.37C15.89,12.96 16.2,12.64 16.7,12.64C17.18,12.64 17.5,12.85 17.79,13.37L19.1,12.5C18.55,11.54 17.77,11.17 16.7,11.17C15.19,11.17 14.22,12.13 14.22,13.4C14.22,14.78 15.03,15.43 16.25,15.95L16.67,16.13C17.45,16.47 17.91,16.68 17.91,17.26C17.91,17.74 17.46,18.09 16.76,18.09C15.93,18.09 15.45,17.66 15.09,17.06L13.71,17.86M13,11.25H8V12.75H9.5V20H11.25V12.75H13V11.25Z" />
+    </svg>
+  );
+};
+
+const OpenAIIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 24 24"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <title>OpenAI</title>
+      <path d="M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z" />
+    </svg>
+  );
+};
+
+const AnthropicIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 24 24"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <title>Anthropic</title>
+      <path d="M17.3041 3.541h-3.6718l6.696 16.918H24Zm-10.6082 0L0 20.459h3.7442l1.3693-3.5527h7.0052l1.3693 3.5528h3.7442L10.5363 3.5409Zm-.3712 10.2232 2.2914-5.9456 2.2914 5.9456Z" />
+    </svg>
+  );
+};
+
+const RadixUIIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      viewBox="4 0 17 25"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M12 25a8 8 0 1 1 0-16v16zM12 0H4v8h8V0zM17 8a4 4 0 1 0 0-8 4 4 0 0 0 0 8z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+const TailwindIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      viewBox="0 0 54 33"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g clipPath="url(#tailwindcss__a)">
+        <path
+          clipRule="evenodd"
+          d="M27 0c-7.2 0-11.7 3.6-13.5 10.8 2.7-3.6 5.85-4.95 9.45-4.05 2.054.513 3.522 2.004 5.147 3.653C30.744 13.09 33.808 16.2 40.5 16.2c7.2 0 11.7-3.6 13.5-10.8-2.7 3.6-5.85 4.95-9.45 4.05-2.054-.513-3.522-2.004-5.147-3.653C36.756 3.11 33.692 0 27 0zM13.5 16.2C6.3 16.2 1.8 19.8 0 27c2.7-3.6 5.85-4.95 9.45-4.05 2.054.514 3.522 2.004 5.147 3.653C17.244 29.29 20.308 32.4 27 32.4c7.2 0 11.7-3.6 13.5-10.8-2.7 3.6-5.85 4.95-9.45 4.05-2.054-.513-3.522-2.004-5.147-3.653C23.256 19.31 20.192 16.2 13.5 16.2z"
+          fill="#38bdf8"
+          fillRule="evenodd"
+        />
+      </g>
+      <defs>
+        <clipPath id="tailwindcss__a">
+          <path d="M0 0h54v32.4H0z" fill="#fff" />
+        </clipPath>
+      </defs>
+    </svg>
+  );
+};
+
+const ReactAriaIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      viewBox="200 206 800 790"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M720.67 205.995C867.583 205.995 986.679 325.091 986.68 472.003C986.68 590.753 908.865 691.325 801.446 725.521L979.312 948.055C994.438 966.98 980.963 995 956.736 995H795.612C778.743 995 762.715 987.629 751.734 974.823L697.365 911.421L493.126 653.39C457.134 607.918 489.518 540.979 547.511 540.977L720.67 540.971C758.758 540.971 789.635 510.091 789.635 472.003C789.634 433.915 758.758 403.038 720.67 403.038H429.939C404.955 403.038 388.623 391.886 373.994 373.623L277.349 252.966C262.194 234.045 275.664 205.996 299.905 205.995H720.67Z M396.605 720.706C407.798 705.406 430.443 704.843 442.381 719.568L503.816 797.018H502.786L535.569 838.934C548.074 854.358 549.943 877.191 538.047 893.09L476.638 972.545C465.692 986.707 448.803 995 430.903 995H242.276C218.18 995 204.665 967.248 219.523 948.278L337.992 797.018H337.923L396.605 720.706Z" />
+    </svg>
+  );
+};
+
+const VSCodeIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 16 16"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g clipPath="url(#clip0_15214_16392)">
+        <path d="M10.8631 13.919C10.7633 13.9676 10.6546 13.9949 10.5437 13.9992C10.4328 14.0035 10.3223 13.9847 10.2191 13.944C10.1142 13.9033 10.0192 13.8409 9.94007 13.761L4.81607 9.06299L2.58407 10.766C2.48347 10.8425 2.35922 10.8813 2.23295 10.8756C2.10669 10.87 1.98641 10.8202 1.89307 10.735L1.17707 10.08C1.12127 10.0288 1.07671 9.96665 1.04622 9.89736C1.01574 9.82806 1 9.75319 1 9.67749C1 9.60179 1.01574 9.52692 1.04622 9.45763C1.07671 9.38834 1.12127 9.32614 1.17707 9.27499L3.11207 7.49999L1.17707 5.72499C1.12127 5.67384 1.07671 5.61165 1.04622 5.54236C1.01574 5.47306 1 5.39819 1 5.32249C1 5.24679 1.01574 5.17192 1.04622 5.10263C1.07671 5.03334 1.12127 4.97114 1.17707 4.91999L1.89307 4.26499C1.98641 4.17977 2.10669 4.13 2.23295 4.12433C2.35922 4.11867 2.48347 4.15747 2.58407 4.23399L4.81607 5.93699L9.94007 1.23899C10.0581 1.11952 10.2106 1.03995 10.3761 1.01144C10.5416 0.98293 10.7119 1.0069 10.8631 1.07999L13.5401 2.37499C13.8211 2.51099 14.0001 2.79699 14.0001 3.11099V7.99999H10.7521V4.53399L6.86407 7.49999L10.7521 10.466V7.99999H14.0001V11.889C14.0001 12.203 13.8211 12.489 13.5401 12.625L10.8631 13.919Z" />
+      </g>
+      <defs>
+        <clipPath id="clip0_15214_16392">
+          <rect fill="white" height="16" width="16" />
+        </clipPath>
+      </defs>
+    </svg>
+  );
+};
+
+const CursorIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 16 16"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g clipPath="url(#clip0_15214_16401)">
+        <path
+          clipRule="evenodd"
+          d="M8 15L14 5V12L8 15ZM2 5L8 1L14 5H2ZM2 5L8 8V15L2 12V5Z"
+          fillRule="evenodd"
+        />
+      </g>
+      <defs>
+        <clipPath id="clip0_15214_16401">
+          <rect fill="white" height="16" width="16" />
+        </clipPath>
+      </defs>
+    </svg>
+  );
+};
+
+const MarkdownIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 16 16"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        clipRule="evenodd"
+        d="M3.44314 4.69872C3.22071 4.26947 2.77757 4 2.29412 4C1.5794 4 1 4.5794 1 5.29412V11.25C1 11.6642 1.33579 12 1.75 12C2.16421 12 2.5 11.6642 2.5 11.25V6.13892L4.33409 9.67839C4.463 9.92716 4.71982 10.0833 5 10.0833C5.28018 10.0833 5.537 9.92716 5.66591 9.67839L7.5 6.13892V11.25C7.5 11.6642 7.83579 12 8.25 12C8.66421 12 9 11.6642 9 11.25V5.29412C9 4.5794 8.4206 4 7.70588 4C7.22243 4 6.77929 4.26947 6.55686 4.69872L5 7.70319L3.44314 4.69872ZM13.25 4.75C13.25 4.33579 12.9142 4 12.5 4C12.0858 4 11.75 4.33579 11.75 4.75V9.43934L11.2803 8.96967C10.9874 8.67678 10.5126 8.67678 10.2197 8.96967C9.92678 9.26256 9.92678 9.73744 10.2197 10.0303L11.9697 11.7803C12.2626 12.0732 12.7374 12.0732 13.0303 11.7803L14.7803 10.0303C15.0732 9.73744 15.0732 9.26256 14.7803 8.96967C14.4874 8.67678 14.0126 8.67678 13.7197 8.96967L13.25 9.43934V4.75Z"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+const ClaudeIcon: React.FC<IconSvgProps> = ({height, size = 24, width, ...props}) => {
+  return (
+    <svg
+      fill="currentColor"
+      height={size || height}
+      role="img"
+      viewBox="0 0 16 16"
+      width={size || width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M3.74677 10.3076L6.50057 8.76276L6.54712 8.62846L6.50057 8.55386H6.36705L5.90589 8.52577L4.33266 8.48364L2.96762 8.42658L1.64563 8.35636L1.31183 8.28527L1 7.87448L1.03162 7.66909L1.31271 7.48125L1.71239 7.51636L2.5987 7.57693L3.92772 7.66909L4.89133 7.72527L6.31961 7.87448H6.54712L6.57874 7.78232L6.50057 7.72527L6.44083 7.66909L5.06525 6.73693L3.57636 5.75298L2.79721 5.18596L2.37558 4.89893L2.16213 4.63034L2.07077 4.04226L2.45288 3.62094L2.96675 3.65605L3.09851 3.69116L3.6194 4.09141L4.73234 4.95248L6.18522 6.02157L6.39779 6.19887L6.483 6.13918L6.49354 6.09618L6.39779 5.9373L5.60723 4.51009L4.76396 3.05743L4.388 2.4553L4.28874 2.09455C4.25153 1.95591 4.23147 1.81323 4.22901 1.66972L4.6647 1.07812L4.90538 1L5.48689 1.07812L5.73196 1.29053L6.09299 2.11561L6.678 3.41467L7.58539 5.18245L7.85067 5.70646L7.99297 6.19185L8.04568 6.34107H8.13791V6.25592L8.21257 5.26056L8.35048 4.03875L8.48576 2.46583L8.53144 2.02345L8.75104 1.49241L9.1876 1.20539L9.52754 1.36865L9.80776 1.7689L9.76823 2.02696L9.60133 3.10658L9.27632 4.80063L9.06287 5.93292H9.1876L9.32903 5.79248L9.9035 5.0306L10.8671 3.82633L11.2923 3.34796L11.7886 2.82044L12.1074 2.56853H12.71L13.1536 3.22771L12.9551 3.90796L12.334 4.69354L11.8202 5.35975L11.0832 6.3516L10.6229 7.14508L10.6651 7.20828L10.7749 7.19774L12.4412 6.84401L13.3407 6.68075L14.415 6.49643L14.9007 6.72288L14.9534 6.95373L14.762 7.4242L13.6139 7.70771L12.2673 7.97718L10.261 8.45116L10.2364 8.46871L10.2645 8.50382L11.1684 8.58984L11.5549 8.61091H12.5009L14.2621 8.74257L14.7233 9.04627L15 9.41843L14.9534 9.70194L14.2446 10.0627L11.0551 9.3052L10.2891 9.11386H10.1837V9.17793L10.8214 9.80113L11.9906 10.8562L13.4549 12.2167L13.5287 12.5529L13.3407 12.8179L13.1422 12.7898L11.8562 11.8234L11.3599 11.3872L10.2355 10.4419H10.1618V10.5411L10.4209 10.9203L11.7886 12.9742L11.8588 13.6044L11.7604 13.8098L11.4056 13.9335L11.0156 13.8633L10.2153 12.7398L9.38964 11.4759L8.72293 10.3427L8.64124 10.3892L8.24771 14.6208L8.06325 14.8367L7.6381 15L7.2841 14.7305L7.09612 14.2952L7.2841 13.435L7.51073 12.3115L7.69519 11.4197L7.86209 10.3111L7.96047 9.94244L7.95344 9.91787L7.87263 9.9284L7.03551 11.0756L5.76358 12.7934L4.75693 13.8703L4.51625 13.966L4.09725 13.7492L4.13678 13.363L4.37044 13.0207L5.76358 11.2494L6.60334 10.1522L7.14531 9.51762L7.1418 9.42545H7.11018L3.41034 11.827L2.75154 11.9112L2.46693 11.6461L2.50207 11.2108L2.63734 11.0686L3.75028 10.3041L3.74677 10.3076Z"
+        fill="#71717A"
+      />
+    </svg>
+  );
+};
+
+export {
+  GithubIcon,
+  NextJsIcon,
+  NpmIcon,
+  CLIBoldIcon,
+  NpmSmallIcon,
+  PnpmIcon,
+  YarnIcon,
+  AstroIcon,
+  RemixIcon,
+  ViteIcon,
+  NewNextJSIcon,
+  StorybookIcon,
+  CodeSandboxIcon,
+  StackblitzIcon,
+  JavascriptIcon,
+  TypescriptIcon,
+  BunIcon,
+  OpenAIIcon,
+  AnthropicIcon,
+  RadixUIIcon,
+  TailwindIcon,
+  FigmaIcon,
+  ReactAriaIcon,
+  VSCodeIcon,
+  CursorIcon,
+  MarkdownIcon,
+  ClaudeIcon,
+};
diff --git a/apps/docs/src/icons/discord.tsx b/apps/docs/src/icons/discord.tsx
new file mode 100644
index 0000000..31bcdcc
--- /dev/null
+++ b/apps/docs/src/icons/discord.tsx
@@ -0,0 +1,31 @@
+import type {Ref, SVGProps} from "react";
+
+import {forwardRef, memo} from "react";
+import {cn} from "tailwind-variants";
+
+const IconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M19.7701 5.33C18.4401 4.71 17.0001 4.26 15.5001 4C15.4737 4.00038 15.4486 4.01116 15.4301 4.03C15.2501 4.36 15.0401 4.79 14.9001 5.12C13.3091 4.88015 11.6911 4.88015 10.1001 5.12C9.96012 4.78 9.75012 4.36 9.56012 4.03C9.55012 4.01 9.52012 4 9.49012 4C7.99012 4.26 6.56012 4.71 5.22012 5.33C5.21012 5.33 5.20012 5.34 5.19012 5.35C2.47012 9.42 1.72012 13.38 2.09012 17.3C2.09012 17.32 2.10012 17.34 2.12012 17.35C3.92012 18.67 5.65012 19.47 7.36012 20C7.39012 20.01 7.42012 20 7.43012 19.98C7.83012 19.43 8.19012 18.85 8.50012 18.24C8.52012 18.2 8.50012 18.16 8.46012 18.15C7.89012 17.93 7.35012 17.67 6.82012 17.37C6.78012 17.35 6.78012 17.29 6.81012 17.26C6.92012 17.18 7.03012 17.09 7.14012 17.01C7.16012 16.99 7.19012 16.99 7.21012 17C10.6501 18.57 14.3601 18.57 17.7601 17C17.7801 16.99 17.8101 16.99 17.8301 17.01C17.9401 17.1 18.0501 17.18 18.1601 17.27C18.2001 17.3 18.2001 17.36 18.1501 17.38C17.6301 17.69 17.0801 17.94 16.5101 18.16C16.4701 18.17 16.4601 18.22 16.4701 18.25C16.7901 18.86 17.1501 19.44 17.5401 19.99C17.5701 20 17.6001 20.01 17.6301 20C19.3501 19.47 21.0801 18.67 22.8801 17.35C22.9001 17.34 22.9101 17.32 22.9101 17.3C23.3501 12.77 22.1801 8.84 19.8101 5.35C19.8001 5.34 19.7901 5.33 19.7701 5.33ZM9.02012 14.91C7.99012 14.91 7.13012 13.96 7.13012 12.79C7.13012 11.62 7.97012 10.67 9.02012 10.67C10.0801 10.67 10.9201 11.63 10.9101 12.79C10.9101 13.96 10.0701 14.91 9.02012 14.91ZM15.9901 14.91C14.9601 14.91 14.1001 13.96 14.1001 12.79C14.1001 11.62 14.9401 10.67 15.9901 10.67C17.0501 10.67 17.8901 11.63 17.8801 12.79C17.8801 13.96 17.0501 14.91 15.9901 14.91Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export const DiscordIcon = memo(forwardRef(IconRender));
diff --git a/apps/docs/src/icons/github.tsx b/apps/docs/src/icons/github.tsx
new file mode 100644
index 0000000..2587a58
--- /dev/null
+++ b/apps/docs/src/icons/github.tsx
@@ -0,0 +1,31 @@
+import type {Ref, SVGProps} from "react";
+
+import {forwardRef, memo} from "react";
+import {cn} from "tailwind-variants";
+
+const IconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M12 2.5a10 10 0 0 0-10 10c0 4.42 2.87 8.17 6.84 9.5.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34C5.68 17.31 5.03 17 5.03 17c-.91-.62.07-.6.07-.6 1 .07 1.53 1.03 1.53 1.03.87 1.52 2.34 1.07 2.91.83.09-.65.35-1.09.63-1.34-2.22-.25-4.55-1.11-4.55-4.92 0-1.11.38-2 1.03-2.71-.1-.25-.45-1.29.1-2.64 0 0 .84-.27 2.75 1.02.79-.22 1.65-.33 2.5-.33.85 0 1.71.11 2.5.33 1.91-1.29 2.75-1.02 2.75-1.02.55 1.35.2 2.39.1 2.64.65.71 1.03 1.6 1.03 2.71 0 3.82-2.34 4.66-4.57 4.91.36.31.69.92.69 1.85v2.74c0 .27.16.59.67.5 3.97-1.34 6.83-5.08 6.83-9.5a10 10 0 0 0-10-10Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export const GitHubIcon = memo(forwardRef(IconRender));
diff --git a/apps/docs/src/icons/google.tsx b/apps/docs/src/icons/google.tsx
new file mode 100644
index 0000000..6a383e5
--- /dev/null
+++ b/apps/docs/src/icons/google.tsx
@@ -0,0 +1,47 @@
+import type {Ref, SVGProps} from "react";
+
+import {forwardRef, memo} from "react";
+import {cn} from "tailwind-variants";
+
+const IconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn(className)}
+      fill="none"
+      focusable="false"
+      height={16}
+      role="presentation"
+      viewBox="0 0 16 16"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M5.877 1.46a6.921 6.921 0 0 0 .474 13.224c1.159.3 2.373.312 3.539.038a6.248 6.248 0 0 0 2.833-1.472 6.28 6.28 0 0 0 1.75-2.872 8.125 8.125 0 0 0 .176-3.673h-6.51v2.7h3.77a3.25 3.25 0 0 1-1.385 2.136c-.46.304-.98.509-1.523.601a4.517 4.517 0 0 1-1.652 0 4.068 4.068 0 0 1-1.537-.67 4.299 4.299 0 0 1-1.586-2.124 4.189 4.189 0 0 1 0-2.694c.208-.613.551-1.17 1.005-1.631a4.066 4.066 0 0 1 4.096-1.07c.558.172 1.07.471 1.492.875.425-.423.849-.847 1.273-1.272.218-.228.457-.446.672-.68a6.693 6.693 0 0 0-2.227-1.374 7 7 0 0 0-4.66-.042Z"
+        fill="#fff"
+      />
+      <path
+        d="M5.877 1.46a7 7 0 0 1 4.66.04c.826.31 1.582.78 2.226 1.381-.219.234-.45.453-.672.68l-1.272 1.267a3.752 3.752 0 0 0-1.492-.875 4.066 4.066 0 0 0-4.098 1.065A4.293 4.293 0 0 0 4.225 6.65L1.958 4.894A6.949 6.949 0 0 1 5.877 1.46Z"
+        fill="#E33629"
+      />
+      <path
+        d="M1.356 6.633a6.89 6.89 0 0 1 .602-1.74l2.267 1.76a4.19 4.19 0 0 0 0 2.694c-.755.584-1.511 1.17-2.267 1.76a6.927 6.927 0 0 1-.602-4.474Z"
+        fill="#F8BD00"
+      />
+      <path
+        d="M8.139 6.704h6.51a8.127 8.127 0 0 1-.176 3.673 6.283 6.283 0 0 1-1.75 2.872c-.732-.571-1.467-1.138-2.199-1.709a3.25 3.25 0 0 0 1.385-2.137h-3.77v-2.7Z"
+        fill="#587DBD"
+      />
+      <path
+        d="M1.957 11.106a539.69 539.69 0 0 0 2.267-1.759 4.298 4.298 0 0 0 1.588 2.125c.462.326.987.552 1.54.665a4.517 4.517 0 0 0 1.652 0 3.96 3.96 0 0 0 1.524-.602c.731.57 1.466 1.137 2.198 1.708a6.25 6.25 0 0 1-2.833 1.474 7.394 7.394 0 0 1-3.54-.039 6.967 6.967 0 0 1-4.397-3.572Z"
+        fill="#319F43"
+      />
+    </svg>
+  );
+};
+
+export const GoogleIcon = memo(forwardRef(IconRender));
diff --git a/apps/docs/src/icons/link.tsx b/apps/docs/src/icons/link.tsx
new file mode 100644
index 0000000..83fa4c1
--- /dev/null
+++ b/apps/docs/src/icons/link.tsx
@@ -0,0 +1,25 @@
+import type {SVGProps} from "react";
+
+export function LinkIcon({className, height = 10, width = 10, ...props}: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      aria-hidden="true"
+      className={className}
+      height={height}
+      role="img"
+      viewBox="0 0 24 24"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M6 18L18 6m0 0H9m9 0v9"
+        fill="none"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.5"
+      />
+    </svg>
+  );
+}
diff --git a/apps/docs/src/icons/twitter.tsx b/apps/docs/src/icons/twitter.tsx
new file mode 100644
index 0000000..673a7e2
--- /dev/null
+++ b/apps/docs/src/icons/twitter.tsx
@@ -0,0 +1,31 @@
+import type {Ref, SVGProps} from "react";
+
+import {forwardRef, memo} from "react";
+import {cn} from "tailwind-variants";
+
+const IconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M13.795 11.033 20.68 2.5h-3.073l-5.255 6.517L7.69 2.5H1l7.806 10.91L1.47 22.5h3.074l5.705-7.07 5.061 7.07H22l-8.205-11.467Zm-2.38 2.95L9.97 11.964 4.36 4.127h2.31l4.528 6.317 1.443 2.02 6.018 8.409h-2.31l-4.934-6.89Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export const TwitterIcon = memo(forwardRef(IconRender));
diff --git a/apps/docs/src/icons/verified-badge.tsx b/apps/docs/src/icons/verified-badge.tsx
new file mode 100644
index 0000000..3e02030
--- /dev/null
+++ b/apps/docs/src/icons/verified-badge.tsx
@@ -0,0 +1,257 @@
+import type {Ref, SVGProps} from "react";
+
+import React, {forwardRef, memo, useId} from "react";
+import {cn} from "tailwind-variants";
+
+const AppleIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="currentColor"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 256 315"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path d="M213.803 167.03c.442 47.58 41.74 63.413 42.197 63.615c-.35 1.116-6.599 22.563-21.757 44.716c-13.104 19.153-26.705 38.235-48.13 38.63c-21.05.388-27.82-12.483-51.888-12.483c-24.061 0-31.582 12.088-51.51 12.871c-20.68.783-36.428-20.71-49.64-39.793c-27-39.033-47.633-110.3-19.928-158.406c13.763-23.89 38.36-39.017 65.056-39.405c20.307-.387 39.475 13.662 51.889 13.662c12.406 0 35.699-16.895 60.186-14.414c10.25.427 39.026 4.14 57.503 31.186c-1.49.923-34.335 20.044-33.978 59.822M174.24 50.199c10.98-13.29 18.369-31.79 16.353-50.199c-15.826.636-34.962 10.546-46.314 23.828c-10.173 11.763-19.082 30.589-16.678 48.633c17.64 1.365 35.66-8.964 46.64-22.262" />
+    </svg>
+  );
+};
+
+export const AppleIcon = memo(forwardRef(AppleIconRender));
+
+const GoogleIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 256 262"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M255.878 133.451c0-10.734-.871-18.567-2.756-26.69H130.55v48.448h71.947c-1.45 12.04-9.283 30.172-26.69 42.356l-.244 1.622l38.755 30.023l2.685.268c24.659-22.774 38.875-56.282 38.875-96.027"
+        fill="#4285f4"
+      />
+      <path
+        d="M130.55 261.1c35.248 0 64.839-11.605 86.453-31.622l-41.196-31.913c-11.024 7.688-25.82 13.055-45.257 13.055c-34.523 0-63.824-22.773-74.269-54.25l-1.531.13l-40.298 31.187l-.527 1.465C35.393 231.798 79.49 261.1 130.55 261.1"
+        fill="#34a853"
+      />
+      <path
+        d="M56.281 156.37c-2.756-8.123-4.351-16.827-4.351-25.82c0-8.994 1.595-17.697 4.206-25.82l-.073-1.73L15.26 71.312l-1.335.635C5.077 89.644 0 109.517 0 130.55s5.077 40.905 13.925 58.602z"
+        fill="#fbbc05"
+      />
+      <path
+        d="M130.55 50.479c24.514 0 41.05 10.589 50.479 19.438l36.844-35.974C195.245 12.91 165.798 0 130.55 0C79.49 0 35.393 29.301 13.925 71.947l42.211 32.783c10.59-31.477 39.891-54.251 74.414-54.251"
+        fill="#eb4335"
+      />
+    </svg>
+  );
+};
+
+export const GoogleIcon = memo(forwardRef(GoogleIconRender));
+
+const VerifiedBadgeIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  const uid = useId();
+  const filterId = `verified-badge-filter-${uid}`;
+  const gradientId = `verified-badge-gradient-${uid}`;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M13.9844 3.40625L14.2471 3.65625L14.6055 3.60645L18.0098 3.13281L18.5977 6.48145L18.6611 6.84375L18.9873 7.01562L22.0059 8.60156L20.4941 11.6963L20.332 12.0283L20.4961 12.3594L22.002 15.3994L18.9873 16.9844L18.6611 17.1562L18.5977 17.5186L18.0098 20.8662L14.6055 20.3936L14.2471 20.3438L13.9844 20.5938L11.5 22.9629L9.01562 20.5938L8.75293 20.3438L8.39453 20.3936L4.98926 20.8662L4.40234 17.5186L4.33887 17.1562L4.0127 16.9844L0.99707 15.3994L2.50391 12.3594L2.66797 12.0283L2.50586 11.6963L0.993164 8.60156L4.0127 7.01562L4.33887 6.84375L4.40234 6.48145L4.98926 3.13281L8.39453 3.60645L8.75293 3.65625L9.01562 3.40625L11.5 1.03613L13.9844 3.40625Z"
+        fill={`url(#${gradientId})`}
+      />
+      <path
+        d="M13.9844 3.40625L14.2471 3.65625L14.6055 3.60645L18.0098 3.13281L18.5977 6.48145L18.6611 6.84375L18.9873 7.01562L22.0059 8.60156L20.4941 11.6963L20.332 12.0283L20.4961 12.3594L22.002 15.3994L18.9873 16.9844L18.6611 17.1562L18.5977 17.5186L18.0098 20.8662L14.6055 20.3936L14.2471 20.3438L13.9844 20.5938L11.5 22.9629L9.01562 20.5938L8.75293 20.3438L8.39453 20.3936L4.98926 20.8662L4.40234 17.5186L4.33887 17.1562L4.0127 16.9844L0.99707 15.3994L2.50391 12.3594L2.66797 12.0283L2.50586 11.6963L0.993164 8.60156L4.0127 7.01562L4.33887 6.84375L4.40234 6.48145L4.98926 3.13281L8.39453 3.60645L8.75293 3.65625L9.01562 3.40625L11.5 1.03613L13.9844 3.40625Z"
+        stroke="#D4D4D8"
+        strokeWidth="1.5"
+        style={{mixBlendMode: "overlay" as const}}
+      />
+      <g filter={`url(#${filterId})`}>
+        <path
+          d="M6 12.3279L9.76623 16L16 9.35519L14.5281 8L9.67965 13.1585L7.42857 10.929L6 12.3279Z"
+          fill="#F4F4F5"
+        />
+      </g>
+      <defs>
+        <filter
+          colorInterpolationFilters="sRGB"
+          filterUnits="userSpaceOnUse"
+          height="10.1"
+          id={filterId}
+          width="10"
+          x="6"
+          y="8"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.3" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.785986 0 0 0 0 0.532335 0 0 0 0 0.21662 0 0 0 1 0"
+          />
+          <feBlend in2="BackgroundImageFix" mode="normal" result="effect1_dropShadow_1_1856" />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.6" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect1_dropShadow_1_1856"
+            mode="normal"
+            result="effect2_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.9" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect2_dropShadow_1_1856"
+            mode="normal"
+            result="effect3_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.2" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect3_dropShadow_1_1856"
+            mode="normal"
+            result="effect4_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.5" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect4_dropShadow_1_1856"
+            mode="normal"
+            result="effect5_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.8" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect5_dropShadow_1_1856"
+            mode="normal"
+            result="effect6_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="2.1" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect6_dropShadow_1_1856"
+            mode="normal"
+            result="effect7_dropShadow_1_1856"
+          />
+          <feBlend
+            in="SourceGraphic"
+            in2="effect7_dropShadow_1_1856"
+            mode="normal"
+            result="shape"
+          />
+        </filter>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id={gradientId}
+          x1="6"
+          x2="16.5"
+          y1="1"
+          y2="25"
+        >
+          <stop stopColor="#F1DF76" />
+          <stop offset="0.0001" stopColor="#FFEF8F" />
+          <stop offset="0.479167" stopColor="#EECA37" />
+          <stop offset="1" stopColor="#DEB200" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
+
+export const VerifiedBadgeIcon = memo(forwardRef(VerifiedBadgeIconRender));
diff --git a/apps/docs/src/lib/agent-api.ts b/apps/docs/src/lib/agent-api.ts
new file mode 100644
index 0000000..88dd201
--- /dev/null
+++ b/apps/docs/src/lib/agent-api.ts
@@ -0,0 +1,142 @@
+import type {Page} from "@/lib/source";
+
+import {getLLMText} from "@/lib/get-llm-text";
+import {
+  filterExcludedPages,
+  filterPagesByPlatform,
+  getPlatformFromPage,
+  isComponentPage,
+  validatePlatform,
+} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+export type AgentSearchPlatform = "react" | "native" | "all";
+
+export type AgentSearchResult = {
+  description: string;
+  platform: AgentSearchPlatform;
+  title: string;
+  url: string;
+};
+
+export type AgentPageResult = {
+  description: string;
+  markdown: string;
+  title: string;
+  url: string;
+};
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 20;
+
+export function parseAgentSearchPlatform(value: string | null): AgentSearchPlatform {
+  const platform = validatePlatform(value ?? undefined);
+
+  return platform ?? "all";
+}
+
+export function parseAgentLimit(value: string | null): number {
+  const parsed = Number(value);
+
+  if (!Number.isFinite(parsed)) return DEFAULT_LIMIT;
+
+  return Math.min(Math.max(Math.trunc(parsed), 1), MAX_LIMIT);
+}
+
+function normalizeSearchText(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function pageToSearchResult(page: Page): AgentSearchResult {
+  return {
+    description: page.data.description ?? "",
+    platform: getPlatformFromPage(page),
+    title: page.data.title,
+    url: page.url,
+  };
+}
+
+export function searchAgentDocs(
+  query: string,
+  platform: AgentSearchPlatform = "all",
+  limit = DEFAULT_LIMIT,
+): AgentSearchResult[] {
+  const normalizedQuery = normalizeSearchText(query);
+
+  if (!normalizedQuery) return [];
+
+  const pages = filterPagesByPlatform(filterExcludedPages(source.getPages()), platform);
+
+  return pages
+    .filter((page) => {
+      const haystack = [
+        page.data.title,
+        page.data.description ?? "",
+        page.url,
+        page.slugs.join(" "),
+      ]
+        .join(" ")
+        .toLowerCase();
+
+      return haystack.includes(normalizedQuery);
+    })
+    .slice(0, limit)
+    .map(pageToSearchResult);
+}
+
+export function listAgentComponents(
+  platform: Exclude<AgentSearchPlatform, "all"> = "react",
+  limit = MAX_LIMIT,
+): AgentSearchResult[] {
+  return filterPagesByPlatform(filterExcludedPages(source.getPages()), platform)
+    .filter(isComponentPage)
+    .slice(0, limit)
+    .map(pageToSearchResult);
+}
+
+export function normalizeDocsUrl(value: string): string | null {
+  if (!value) return null;
+
+  let pathname = value.trim();
+
+  try {
+    if (pathname.startsWith("http://") || pathname.startsWith("https://")) {
+      pathname = new URL(pathname).pathname;
+    }
+  } catch {
+    return null;
+  }
+
+  if (!pathname.startsWith("/")) {
+    pathname = `/${pathname}`;
+  }
+
+  pathname = pathname.replace(/\/$/, "");
+
+  if (!pathname.startsWith("/docs/")) return null;
+
+  return pathname;
+}
+
+export async function getAgentDocPage(value: string): Promise<AgentPageResult | null> {
+  const pathname = normalizeDocsUrl(value);
+
+  if (!pathname) return null;
+
+  const slug = pathname
+    .replace(/^\/docs\//, "")
+    .split("/")
+    .filter(Boolean);
+  const page = source.getPage(slug);
+
+  if (!page) return null;
+
+  const markdown = await getLLMText(page);
+
+  return {
+    description: page.data.description ?? "",
+    markdown,
+    title: page.data.title,
+    url: page.url,
+  };
+}
diff --git a/apps/docs/src/lib/agent-discovery.ts b/apps/docs/src/lib/agent-discovery.ts
new file mode 100644
index 0000000..2af569d
--- /dev/null
+++ b/apps/docs/src/lib/agent-discovery.ts
@@ -0,0 +1,92 @@
+export const AGENT_DISCOVERY_CACHE_HEADERS = {
+  "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
+} as const;
+
+export const JSON_HEADERS = {
+  ...AGENT_DISCOVERY_CACHE_HEADERS,
+  "Content-Type": "application/json; charset=utf-8",
+} as const;
+
+export const LINKSET_HEADERS = {
+  ...AGENT_DISCOVERY_CACHE_HEADERS,
+  "Content-Type": "application/linkset+json; charset=utf-8",
+} as const;
+
+export const MARKDOWN_HEADERS = {
+  ...AGENT_DISCOVERY_CACHE_HEADERS,
+  "Content-Type": "text/markdown; charset=utf-8",
+} as const;
+
+export const OPENAPI_HEADERS = {
+  ...AGENT_DISCOVERY_CACHE_HEADERS,
+  "Content-Type": "application/vnd.oai.openapi+json; charset=utf-8",
+} as const;
+
+export const AGENT_API_VERSION = "3.0.5";
+export const MCP_PACKAGE_VERSION = "1.1.0";
+
+export const REACT_MCP_API_URL = "https://mcp-api.heroui.com";
+export const NATIVE_MCP_API_URL = "https://native-mcp-api.heroui.com";
+
+export const AGENT_SKILL_DESCRIPTIONS: Record<string, string> = {
+  "heroui-migration":
+    "Migrate projects from HeroUI v2 and NextUI patterns to HeroUI v3 with current guides and examples.",
+  "heroui-native":
+    "Build React Native applications with HeroUI Native components, theme variables, and documentation lookup.",
+  "heroui-react":
+    "Build React applications with HeroUI v3 components, theming, styling, and documentation lookup.",
+};
+
+export function normalizeOrigin(origin: string): string {
+  return origin.replace(/\/$/, "");
+}
+
+export function getRequestOrigin(request: Request): string {
+  const headers = request.headers;
+  const forwardedHost = headers.get("x-forwarded-host");
+  const host = forwardedHost ?? headers.get("host");
+
+  if (host) {
+    const forwardedProto = headers.get("x-forwarded-proto");
+    const protocol = forwardedProto ?? (host.includes("localhost") ? "http" : "https");
+
+    return normalizeOrigin(`${protocol}://${host}`);
+  }
+
+  return normalizeOrigin(new URL(request.url).origin);
+}
+
+export function absoluteUrl(origin: string, path: string): string {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+  return `${normalizeOrigin(origin)}${cleanPath}`;
+}
+
+export function getHomepageLinkHeader(): string {
+  return [
+    '</.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"',
+    '</.well-known/agent-skills/index.json>; rel="describedby"; type="application/json"',
+    '</.well-known/mcp/server-card.json>; rel="service-desc"; type="application/json"',
+    '</.well-known/oauth-protected-resource>; rel="oauth-protected-resource"; type="application/json"',
+    '</llms.txt>; rel="service-doc"; type="text/plain"',
+    '</llms-full.txt>; rel="describedby"; type="text/plain"',
+  ].join(", ");
+}
+
+export function jsonResponse(data: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(data, null, 2), {
+    ...init,
+    headers: {
+      ...JSON_HEADERS,
+      ...init.headers,
+    },
+  });
+}
+
+export function getAgentServiceBaseUrl(origin: string): string {
+  return absoluteUrl(origin, "/api/agent");
+}
diff --git a/apps/docs/src/lib/agent-markdown.ts b/apps/docs/src/lib/agent-markdown.ts
new file mode 100644
index 0000000..d7f2cce
--- /dev/null
+++ b/apps/docs/src/lib/agent-markdown.ts
@@ -0,0 +1,107 @@
+type AcceptEntry = {
+  mediaType: string;
+  q: number;
+};
+
+function parseAcceptHeader(accept: string): AcceptEntry[] {
+  return accept
+    .split(",")
+    .map((entry) => {
+      const [mediaType = "", ...params] = entry.split(";").map((part) => part.trim());
+      const qParam = params.find((param) => param.startsWith("q="));
+      const q = qParam ? Number(qParam.slice(2)) : 1;
+
+      return {
+        mediaType: mediaType.toLowerCase(),
+        q: Number.isFinite(q) ? q : 1,
+      };
+    })
+    .filter((entry) => entry.mediaType.length > 0 && entry.q > 0)
+    .sort((a, b) => b.q - a.q);
+}
+
+function getQuality(entries: AcceptEntry[], mediaType: string): number {
+  const exact = entries.find((entry) => entry.mediaType === mediaType);
+
+  if (exact) return exact.q;
+
+  const [type] = mediaType.split("/");
+  const typeWildcard = entries.find((entry) => entry.mediaType === `${type}/*`);
+
+  if (typeWildcard) return typeWildcard.q;
+
+  const allWildcard = entries.find((entry) => entry.mediaType === "*/*");
+
+  return allWildcard?.q ?? 0;
+}
+
+export function acceptsMarkdown(request: Request): boolean {
+  const accept = request.headers.get("accept");
+
+  if (!accept) return false;
+
+  const entries = parseAcceptHeader(accept);
+  const explicitMarkdown = entries.find((entry) => entry.mediaType === "text/markdown");
+
+  if (!explicitMarkdown) return false;
+
+  const htmlQuality = getQuality(entries, "text/html");
+
+  return explicitMarkdown.q >= htmlQuality;
+}
+
+export function estimateMarkdownTokens(markdown: string): number {
+  const trimmed = markdown.trim();
+
+  if (!trimmed) return 0;
+
+  return Math.max(trimmed.split(/\s+/).length, Math.ceil(trimmed.length / 4));
+}
+
+export function getHomepageMarkdown(origin: string): string {
+  const baseUrl = origin.replace(/\/$/, "");
+
+  return `# HeroUI
+
+Beautiful, accessible React UI components built on React Aria and Tailwind CSS v4. The modern alternative to MUI, Chakra UI, and shadcn/ui for building production-ready applications.
+
+HeroUI is the modern UI library for web and mobile, built to help teams move fast, stay consistent, and deliver delightful user experiences.
+
+## Start here
+
+- [Get started](${baseUrl}/docs/react/getting-started)
+- [React components](${baseUrl}/docs/react/components)
+- [Native components](${baseUrl}/docs/native/components)
+- [GitHub repository](https://github.com/heroui-inc/heroui)
+
+## Agent resources
+
+- [LLMs quick index](${baseUrl}/llms.txt)
+- [Full LLM documentation](${baseUrl}/llms-full.txt)
+- [React LLM documentation](${baseUrl}/react/llms-full.txt)
+- [Native LLM documentation](${baseUrl}/native/llms-full.txt)
+- [API catalog](${baseUrl}/.well-known/api-catalog)
+- [MCP server card](${baseUrl}/.well-known/mcp/server-card.json)
+- [Agent skills index](${baseUrl}/.well-known/agent-skills/index.json)
+
+## MCP and skills
+
+- [HeroUI React MCP server](${baseUrl}/docs/react/getting-started/mcp-server)
+- [HeroUI Native MCP server](${baseUrl}/docs/native/getting-started/mcp-server)
+- [HeroUI React Agent Skills](${baseUrl}/docs/react/getting-started/agent-skills)
+- [HeroUI Native Agent Skills](${baseUrl}/docs/native/getting-started/agent-skills)
+`;
+}
+
+export function resolveDocsPathToSlug(pathname: string): string[] | null {
+  const normalized = pathname.replace(/\/$/, "");
+
+  if (!normalized.startsWith("/docs/")) return null;
+
+  const slug = normalized
+    .replace(/^\/docs\//, "")
+    .split("/")
+    .filter(Boolean);
+
+  return slug.length > 0 ? slug : null;
+}
diff --git a/apps/docs/src/lib/blog.ts b/apps/docs/src/lib/blog.ts
new file mode 100644
index 0000000..0d7cb15
--- /dev/null
+++ b/apps/docs/src/lib/blog.ts
@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import matter from "gray-matter";
+
+import {i18n} from "@/lib/i18n";
+
+export interface BlogPost {
+  slug: string;
+  locale: string;
+  title: string;
+  description: string;
+  date: string;
+  author: string;
+  authorAvatar?: string;
+  authorHandle?: string;
+  authorUrl?: string;
+  tags: string[];
+  image?: string;
+  darkImage?: string;
+  draft?: boolean;
+  content: string;
+}
+
+const BLOG_DIR = path.join(process.cwd(), "content/blog");
+const DEFAULT_LOCALE = i18n.defaultLanguage;
+
+// Drafts are visible in development/preview but hidden in production builds.
+const HIDE_DRAFTS = process.env.NODE_ENV === "production";
+
+function getLocaleDir(locale: string): string {
+  return path.join(BLOG_DIR, locale);
+}
+
+function parsePost(slug: string, locale: string, rawContent: string): BlogPost {
+  const {content, data} = matter(rawContent);
+
+  return {
+    author: data["author"] || "HeroUI Team",
+    authorAvatar: data["authorAvatar"],
+    authorHandle: data["authorHandle"],
+    authorUrl: data["authorUrl"],
+    content,
+    darkImage: data["darkImage"],
+    date: data["date"],
+    description: data["description"],
+    draft: Boolean(data["draft"]),
+    image: data["image"],
+    locale,
+    slug,
+    tags: data["tags"] || [],
+    title: data["title"],
+  };
+}
+
+function readPostsFromDir(locale: string): BlogPost[] {
+  const dir = getLocaleDir(locale);
+
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".mdx"));
+
+  return files.map((file) => {
+    const slug = file.replace(/\.mdx$/, "");
+    const rawContent = fs.readFileSync(path.join(dir, file), "utf-8");
+
+    return parsePost(slug, locale, rawContent);
+  });
+}
+
+/**
+ * Returns all blog posts for the given locale.
+ * Posts only available in the default locale are surfaced as fallbacks
+ * so non-default locales never appear empty before their content is translated.
+ */
+export function getAllBlogPosts(locale: string = DEFAULT_LOCALE): BlogPost[] {
+  const localePosts = readPostsFromDir(locale);
+
+  let posts = localePosts;
+
+  if (locale !== DEFAULT_LOCALE) {
+    const seen = new Set(localePosts.map((p) => p.slug));
+    const fallbackPosts = readPostsFromDir(DEFAULT_LOCALE).filter((p) => !seen.has(p.slug));
+
+    posts = [...localePosts, ...fallbackPosts];
+  }
+
+  const visible = HIDE_DRAFTS ? posts.filter((post) => !post.draft) : posts;
+
+  return visible.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+export function getBlogPost(slug: string, locale: string = DEFAULT_LOCALE): BlogPost | undefined {
+  const candidates = locale === DEFAULT_LOCALE ? [DEFAULT_LOCALE] : [locale, DEFAULT_LOCALE];
+
+  for (const candidateLocale of candidates) {
+    const filePath = path.join(getLocaleDir(candidateLocale), `${slug}.mdx`);
+
+    if (!fs.existsSync(filePath)) continue;
+
+    const rawContent = fs.readFileSync(filePath, "utf-8");
+    const post = parsePost(slug, candidateLocale, rawContent);
+
+    if (HIDE_DRAFTS && post.draft) return undefined;
+
+    return post;
+  }
+
+  return undefined;
+}
+
+export function getAllBlogTags(locale: string = DEFAULT_LOCALE): string[] {
+  const posts = getAllBlogPosts(locale);
+  const tags = new Set<string>();
+
+  posts.forEach((post) => post.tags.forEach((tag) => tags.add(tag)));
+
+  return Array.from(tags).sort();
+}
+
+export function getRelatedPosts(
+  slug: string,
+  tags: string[],
+  limit = 3,
+  locale: string = DEFAULT_LOCALE,
+): BlogPost[] {
+  const allPosts = getAllBlogPosts(locale).filter((p) => p.slug !== slug);
+
+  const scored = allPosts.map((post) => {
+    const sharedTags = post.tags.filter((t) => tags.includes(t)).length;
+
+    return {post, score: sharedTags};
+  });
+
+  scored.sort(
+    (a, b) =>
+      new Date(b.post.date).getTime() - new Date(a.post.date).getTime() || b.score - a.score,
+  );
+
+  return scored.slice(0, limit).map((s) => s.post);
+}
diff --git a/apps/docs/src/lib/dictionaries.ts b/apps/docs/src/lib/dictionaries.ts
new file mode 100644
index 0000000..c743828
--- /dev/null
+++ b/apps/docs/src/lib/dictionaries.ts
@@ -0,0 +1,52 @@
+import "server-only";
+
+import {headers} from "next/headers";
+
+import {i18n} from "@/lib/i18n";
+
+const dictionaries = {
+  cn: () => import("./dictionaries/cn.json").then((module) => module.default),
+  en: () => import("./dictionaries/en.json").then((module) => module.default),
+};
+
+export type Locale = keyof typeof dictionaries;
+
+export const hasLocale = (locale: string): locale is Locale => locale in dictionaries;
+
+export const getDictionary = async (locale: Locale) => dictionaries[locale]();
+
+export type Dictionary = Awaited<ReturnType<typeof getDictionary>>;
+
+function getFirstPathSegment(pathOrUrl: string): string | undefined {
+  try {
+    const pathname = pathOrUrl.startsWith("/") ? pathOrUrl : new URL(pathOrUrl).pathname;
+
+    return pathname.split("/").filter(Boolean)[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolves locale for error boundaries (e.g. not-found) that do not receive route params.
+ * Checks request URL headers first, then referer, then falls back to the default locale.
+ */
+export async function getRequestLocale(): Promise<Locale> {
+  const headersList = await headers();
+  const candidates = [
+    headersList.get("x-url"),
+    headersList.get("next-url"),
+    headersList.get("x-invoke-path"),
+    headersList.get("referer"),
+  ];
+
+  for (const value of candidates) {
+    if (!value) continue;
+
+    const segment = getFirstPathSegment(value);
+
+    if (segment && hasLocale(segment)) return segment;
+  }
+
+  return i18n.defaultLanguage as Locale;
+}
diff --git a/apps/docs/src/lib/dictionaries/cn.json b/apps/docs/src/lib/dictionaries/cn.json
new file mode 100644
index 0000000..fc8d3a4
--- /dev/null
+++ b/apps/docs/src/lib/dictionaries/cn.json
@@ -0,0 +1,336 @@
+{
+  "home": {
+    "releaseBadges": [
+      {
+        "label": "HeroUI React v3.2.2 — 补丁版本",
+        "href": "/docs/react/releases/v3-2-2",
+        "date": "2026-07-06"
+      },
+      {
+        "label": "HeroUI Native v1.0.5 — 补丁版本",
+        "href": "/docs/native/releases/v1-0-5",
+        "date": "2026-07-02"
+      }
+    ],
+    "titleMain": "开箱即用",
+    "titleMuted": "设计灵活可定制",
+    "description": "HeroUI 是面向网页与移动端的现代 UI 库，助你快速迭代、保持一致，并打造令人愉悦的用户体验。",
+    "getStarted": "快速开始",
+    "viewComponents": "查看组件",
+    "githubStarsPrefix": "开源项目，已有",
+    "githubStarsSuffix": "颗星",
+    "demo": {
+      "proTemplate": "Pro 模板可用",
+      "themeBuilder": "在主题编辑器中打开"
+    }
+  },
+  "nav": {
+    "documentation": "文档",
+    "resources": "资源",
+    "gettingStarted": "快速开始",
+    "themes": "主题",
+    "components": "组件",
+    "reactNative": "React Native",
+    "reactNativeShort": "Native",
+    "releases": "版本发布",
+    "blog": "博客",
+    "docs": "文档",
+    "roadmap": "路线图"
+  },
+  "notFound": {
+    "imageAlt": "404 未找到",
+    "title": "404",
+    "description": "抱歉，找不到您要访问的页面。",
+    "returnHome": "返回首页"
+  },
+  "blog": {
+    "heading": "博客",
+    "metaTitle": "博客 | HeroUI",
+    "metaDescription": "面向现代 React 应用的指南、教程与资源。包含对比、最佳实践等内容。",
+    "categoriesAriaLabel": "博客分类",
+    "categories": {
+      "all": "全部",
+      "tutorial": "教程",
+      "comparison": "对比",
+      "native": "Native",
+      "uiLibraries": "资源"
+    },
+    "latestPosts": "最新文章",
+    "emptyState": "该分类下暂无文章。",
+    "backToBlog": "返回博客",
+    "relatedPosts": "相关文章"
+  },
+  "showcase": {
+    "heading": "展示",
+    "description": "探索展示 HeroUI 组件在真实场景中应用的互动示例。"
+  },
+  "footer": {
+    "allRightsReserved": "保留所有权利。"
+  },
+  "newsletter": {
+    "label": "Hero 新闻通讯",
+    "placeholder": "name@email.com",
+    "subscribe": "订阅",
+    "emailRequired": "请输入邮箱地址",
+    "emailInvalid": "请输入有效的邮箱地址。",
+    "apiError": "订阅失败，请稍后再试",
+    "genericError": "出现错误，请稍后再试。"
+  },
+  "statusChip": {
+    "new": "新",
+    "preview": "预览",
+    "updated": "更新"
+  },
+  "frameworksTabs": {
+    "ariaLabel": "文档框架",
+    "web": "网页",
+    "native": "移动端"
+  },
+  "searchDialog": {
+    "placeholder": "你想搜索什么？",
+    "jumpTo": "跳转到"
+  },
+  "componentLinks": {
+    "source": "源代码",
+    "stylesSource": "样式源代码",
+    "themeSource": "主题源代码"
+  },
+  "copyPrompt": {
+    "copy": "复制提示词",
+    "copied": "已复制",
+    "ariaLabelCopy": "复制提示词到剪贴板",
+    "ariaLabelCopied": "提示词已复制到剪贴板"
+  },
+  "qrPreviewPopover": {
+    "tapToPreview": "点击预览",
+    "scanToPreview": "扫码预览",
+    "downloadPrompt": "还没有安装 {name} 应用？请在下方下载。"
+  },
+  "storeButtons": {
+    "appStoreLabel": "在 App Store 下载 {name}",
+    "appStore": "在 App Store 下载",
+    "playStoreLabel": "在 Google Play 下载 {name}",
+    "playStore": "在 Play Store 下载",
+    "androidComingSoonLabel": "Android 版本即将推出",
+    "androidComingSoon": "Android · 即将推出"
+  },
+  "themes": {
+    "theme": "主题",
+    "custom": "自定义",
+    "designTheme": "设计主题",
+    "editTheme": "编辑主题",
+    "vibrantPalette": "鲜艳调色板",
+    "vibrantPaletteDescription": "更饱和，对比更低",
+    "pickRandomHint": "按 {kbd} 随机选择"
+  },
+  "themeBuilder": {
+    "onboarding": {
+      "title": "为你的品牌定制 HeroUI v3",
+      "description": "使用令牌系统自定义颜色、圆角与字体，让每个组件保持一致并可直接投入生产。",
+      "moreComing": "更多功能与主题即将推出。",
+      "continue": "继续"
+    },
+    "header": {
+      "undo": "撤销上一步",
+      "redo": "重做上一步",
+      "share": "分享主题链接",
+      "viewCode": "查看代码",
+      "linkCopied": "链接已复制",
+      "linkCopiedDescription": "你的主题链接已复制到剪贴板。",
+      "switchMode": "切换模式"
+    },
+    "resetButton": {
+      "tooltip": "恢复默认",
+      "dialogTitle": "恢复为默认主题？",
+      "dialogBody": "这将把所有主题数值恢复为默认设置。",
+      "cancel": "取消",
+      "confirm": "确认"
+    },
+    "shuffleButton": {
+      "tooltip": "随机生成",
+      "dialogTitle": "确定要随机生成吗？",
+      "dialogBody": "这将覆盖你当前的主题设置。",
+      "cancel": "取消",
+      "confirm": "确认",
+      "dontShowAgain": "不再显示"
+    },
+    "fontFamily": {
+      "label": "字体",
+      "suggested": "推荐",
+      "allFonts": "全部字体",
+      "addFromCdn": "从 CDN 添加",
+      "removeFont": "移除字体"
+    },
+    "customFonts": {
+      "back": "返回",
+      "fontUrl": "字体 URL",
+      "placeholder": "粘贴字体 URL...",
+      "description": "支持 G Fonts、Fontsource 与 Fontshare",
+      "importing": "导入中...",
+      "importFont": "导入字体",
+      "errorHttps": "URL 必须使用 https 协议",
+      "errorSupportedCdn": "URL 必须来自受支持的 CDN（Google Fonts、Fontsource、Bunny Fonts 等）",
+      "errorInvalidUrl": "请输入有效的 URL",
+      "errorCannotDetect": "无法从 URL 中识别字体，请检查 URL 格式。",
+      "errorCannotDetectFull": "无法从 URL 中识别字体，请确保 URL 是有效的字体样式表。",
+      "errorAlreadyImported": "该字体已作为 \"{name}\" 导入"
+    },
+    "accentColor": {
+      "label": "强调色",
+      "tooltip": "用于品牌与高亮的主要颜色"
+    },
+    "baseColor": {
+      "label": "基础色",
+      "tooltip": "控制背景与表面等中性色中灰度的比例"
+    },
+    "radius": {
+      "label": "圆角",
+      "description": "影响整体 UI，例如菜单与弹窗",
+      "formLabel": "表单圆角",
+      "formDescription": "影响表单元素，例如输入框与选择器",
+      "options": {
+        "none": "无",
+        "extraSmall": "超小",
+        "small": "小",
+        "medium": "中",
+        "large": "大",
+        "extraLarge": "超大"
+      }
+    },
+    "lockableLabel": {
+      "lockValue": "锁定数值",
+      "unlockValue": "解锁数值"
+    },
+    "tabs": {
+      "components": "组件",
+      "dashboard": "仪表盘",
+      "mail": "邮件",
+      "chat": "聊天",
+      "finances": "财务"
+    }
+  },
+  "demos": {
+    "alert": {
+      "title": "您还剩 2 次额度",
+      "description": "升级到付费计划获取更多额度",
+      "action": "升级"
+    },
+    "alertDialog": {
+      "title": "未保存的更改",
+      "description": "您要保存还是放弃更改？",
+      "discard": "放弃",
+      "save": "保存更改"
+    },
+    "allowNotifications": {
+      "label": "允许通知",
+      "description": "接收来自 HeroUI 的推送通知"
+    },
+    "buttons": {
+      "clickMe": "点击我"
+    },
+    "inputOtp": {
+      "label": "验证账户",
+      "description": "我们已向 a****@gmail.com 发送验证码",
+      "didntReceive": "没有收到验证码？",
+      "resend": "重新发送"
+    },
+    "listBox": {
+      "ariaLabel": "文件操作",
+      "actions": "操作",
+      "newFile": "新建文件",
+      "newFileDescription": "创建一个新文件",
+      "editFile": "编辑文件",
+      "editFileDescription": "修改内容",
+      "dangerZone": "危险操作",
+      "deleteFile": "删除文件",
+      "deleteFileDescription": "移到回收站"
+    },
+    "login": {
+      "title": "创建账户",
+      "trialNote": "开始 7 天免费试用，无需信用卡。",
+      "getStarted": "立即开始",
+      "or": "或",
+      "continueWithGoogle": "使用 Google 继续",
+      "continueWithApple": "使用 Apple 继续"
+    },
+    "select": {
+      "placeholder": "请选择",
+      "label": "州",
+      "options": {
+        "florida": "佛罗里达",
+        "delaware": "特拉华",
+        "california": "加利福尼亚",
+        "texas": "得克萨斯",
+        "newYork": "纽约",
+        "washington": "华盛顿"
+      }
+    },
+    "slider": {
+      "label": "价格"
+    },
+    "subtleCards": {
+      "indieTitle": "Indie Hackers",
+      "indieMembers": "148 位成员",
+      "indieBy": "由 John 创建",
+      "aiTitle": "AI Builders",
+      "aiMembers": "362 位成员",
+      "aiBy": "由 Martha 创建"
+    },
+    "tabs1": {
+      "ariaLabel": "选项",
+      "all": "全部"
+    },
+    "tabs2": {
+      "ariaLabel": "选项",
+      "chats": "聊天",
+      "emails": "邮件"
+    },
+    "textfield": {
+      "label": "您的邮箱",
+      "placeholder": "john@email.com",
+      "description": "我们不会分享您的邮箱",
+      "error": "邮箱无效"
+    },
+    "uiComponents": {
+      "checkboxAriaLabel": "复选框指示器示例",
+      "switchAriaLabel": "开关启用状态示例",
+      "radioAriaLabel": "单选按钮示例"
+    },
+    "xProfile": {
+      "bio": "构建网页与移动端 UI 的未来。",
+      "bioSuffix": "(YC S24)",
+      "confettiLabel": "彩带",
+      "following": "正在关注",
+      "followers": "关注者"
+    }
+  },
+  "pageActions": {
+    "copyMarkdown": "复制 Markdown",
+    "copied": "已复制",
+    "moreOptions": "更多选项",
+    "askWithUrl": "请阅读 {url}，我想就此进行提问。",
+    "askFallback": "我想就这份文档进行提问。",
+    "items": {
+      "markdown": {
+        "title": "查看 Markdown",
+        "description": "以 Markdown 格式查看页面"
+      },
+      "cursor": {
+        "title": "添加到 Cursor",
+        "description": "在 Cursor 中安装 MCP 服务器"
+      },
+      "vscode": {
+        "title": "添加到 VS Code",
+        "description": "在 VS Code 中安装 MCP 服务器"
+      },
+      "chatgpt": {
+        "title": "在 ChatGPT 中打开",
+        "description": "就此页面进行提问"
+      },
+      "claude": {
+        "title": "在 Claude 中打开",
+        "description": "就此页面进行提问"
+      }
+    }
+  }
+}
diff --git a/apps/docs/src/lib/dictionaries/en.json b/apps/docs/src/lib/dictionaries/en.json
new file mode 100644
index 0000000..543bf72
--- /dev/null
+++ b/apps/docs/src/lib/dictionaries/en.json
@@ -0,0 +1,336 @@
+{
+  "home": {
+    "releaseBadges": [
+      {
+        "label": "HeroUI React v3.2.2 — patch release",
+        "href": "/docs/react/releases/v3-2-2",
+        "date": "2026-07-06"
+      },
+      {
+        "label": "HeroUI Native v1.0.5 — patch release",
+        "href": "/docs/native/releases/v1-0-5",
+        "date": "2026-07-02"
+      }
+    ],
+    "titleMain": "Beautiful by default.",
+    "titleMuted": "Customizable by design.",
+    "description": "HeroUI is the modern UI library for web and mobile, built to help you move fast, stay consistent, and deliver delightful user experiences.",
+    "getStarted": "Get started",
+    "viewComponents": "View components",
+    "githubStarsPrefix": "Open source with",
+    "githubStarsSuffix": "stars",
+    "demo": {
+      "proTemplate": "Available in Pro as template",
+      "themeBuilder": "Open in theme builder"
+    }
+  },
+  "nav": {
+    "documentation": "Documentation",
+    "resources": "Resources",
+    "gettingStarted": "Getting Started",
+    "themes": "Themes",
+    "components": "Components",
+    "reactNative": "React Native",
+    "reactNativeShort": "Native",
+    "releases": "Releases",
+    "blog": "Blog",
+    "docs": "Docs",
+    "roadmap": "Roadmap"
+  },
+  "notFound": {
+    "imageAlt": "404 Not Found",
+    "title": "404",
+    "description": "Sorry, the page you're looking for could not be found.",
+    "returnHome": "Return Home"
+  },
+  "blog": {
+    "heading": "Blog",
+    "metaTitle": "Blog | HeroUI",
+    "metaDescription": "Guides, tutorials, and resources for building modern React applications with HeroUI. Comparisons, best practices, and more.",
+    "categoriesAriaLabel": "Blog categories",
+    "categories": {
+      "all": "All",
+      "tutorial": "Guides",
+      "comparison": "Comparisons",
+      "native": "Native",
+      "uiLibraries": "Resources"
+    },
+    "latestPosts": "Latest Posts",
+    "emptyState": "No posts found for this category.",
+    "backToBlog": "Back to Blog",
+    "relatedPosts": "Related Posts"
+  },
+  "showcase": {
+    "heading": "Showcase",
+    "description": "Explore interactive examples showcasing HeroUI components in real-world scenarios."
+  },
+  "footer": {
+    "allRightsReserved": "All rights reserved."
+  },
+  "newsletter": {
+    "label": "Hero Newsletter",
+    "placeholder": "name@email.com",
+    "subscribe": "Subscribe",
+    "emailRequired": "Email is required",
+    "emailInvalid": "Please enter a valid email.",
+    "apiError": "Failed to subscribe newsletter",
+    "genericError": "Something went wrong. Please try again."
+  },
+  "statusChip": {
+    "new": "New",
+    "preview": "Preview",
+    "updated": "Updated"
+  },
+  "frameworksTabs": {
+    "ariaLabel": "Documentation framework",
+    "web": "Web",
+    "native": "Native"
+  },
+  "searchDialog": {
+    "placeholder": "What are you searching for?",
+    "jumpTo": "Jump to"
+  },
+  "componentLinks": {
+    "source": "Source",
+    "stylesSource": "Styles source",
+    "themeSource": "Theme source"
+  },
+  "copyPrompt": {
+    "copy": "Copy prompt",
+    "copied": "Copied",
+    "ariaLabelCopy": "Copy prompt to clipboard",
+    "ariaLabelCopied": "Prompt copied to clipboard"
+  },
+  "qrPreviewPopover": {
+    "tapToPreview": "Tap to preview",
+    "scanToPreview": "Scan to preview",
+    "downloadPrompt": "Don't have the {name} app yet? Download it below."
+  },
+  "storeButtons": {
+    "appStoreLabel": "Download {name} on the App Store",
+    "appStore": "Download on App Store",
+    "playStoreLabel": "Download {name} on Google Play",
+    "playStore": "Download on Play Store",
+    "androidComingSoonLabel": "Android version coming soon",
+    "androidComingSoon": "Android · Coming soon"
+  },
+  "themes": {
+    "theme": "Theme",
+    "custom": "Custom",
+    "designTheme": "Design theme",
+    "editTheme": "Edit theme",
+    "vibrantPalette": "Vibrant palette",
+    "vibrantPaletteDescription": "More saturated, less contrast",
+    "pickRandomHint": "Press {kbd} to pick random"
+  },
+  "themeBuilder": {
+    "onboarding": {
+      "title": "Adapt HeroUI v3 to your brand",
+      "description": "Customize colors, radius, and typography using a token system that keeps every component consistent and production-ready.",
+      "moreComing": "More features and themes coming soon.",
+      "continue": "Continue"
+    },
+    "header": {
+      "undo": "Undo last change",
+      "redo": "Redo last change",
+      "share": "Share theme link",
+      "viewCode": "View code",
+      "linkCopied": "Link copied",
+      "linkCopiedDescription": "Your theme link is copied to the clipboard.",
+      "switchMode": "Switch mode"
+    },
+    "resetButton": {
+      "tooltip": "Reset to defaults",
+      "dialogTitle": "Reset theme to default?",
+      "dialogBody": "This will restore all theme values to their default settings.",
+      "cancel": "Cancel",
+      "confirm": "Confirm"
+    },
+    "shuffleButton": {
+      "tooltip": "Randomize",
+      "dialogTitle": "Are you sure you want to randomize?",
+      "dialogBody": "This will overwrite your current theme settings.",
+      "cancel": "Cancel",
+      "confirm": "Confirm",
+      "dontShowAgain": "Don't show again"
+    },
+    "fontFamily": {
+      "label": "Font Family",
+      "suggested": "Suggested",
+      "allFonts": "All Fonts",
+      "addFromCdn": "Add from CDN",
+      "removeFont": "Remove font"
+    },
+    "customFonts": {
+      "back": "Back",
+      "fontUrl": "Font URL",
+      "placeholder": "Paste font URL...",
+      "description": "Supports G Fonts, Fontsource and Fontshare",
+      "importing": "Importing...",
+      "importFont": "Import font",
+      "errorHttps": "URL must use https protocol",
+      "errorSupportedCdn": "URL must be from a supported CDN (Google Fonts, Fontsource, Bunny Fonts, etc.)",
+      "errorInvalidUrl": "Please enter a valid URL",
+      "errorCannotDetect": "Could not detect font family from URL. Please check the URL format.",
+      "errorCannotDetectFull": "Could not detect font family from URL. Please ensure the URL is a valid font stylesheet.",
+      "errorAlreadyImported": "This font is already imported as \"{name}\""
+    },
+    "accentColor": {
+      "label": "Accent",
+      "tooltip": "Main color used for branding and highlights"
+    },
+    "baseColor": {
+      "label": "Base",
+      "tooltip": "Controls how much gray is used in neutrals like backgrounds and surfaces"
+    },
+    "radius": {
+      "label": "Radius",
+      "description": "Affects the overall UI, like menus and modals",
+      "formLabel": "Radius Form",
+      "formDescription": "Affects form elements, like inputs and selects",
+      "options": {
+        "none": "none",
+        "extraSmall": "extra small",
+        "small": "small",
+        "medium": "medium",
+        "large": "large",
+        "extraLarge": "extra large"
+      }
+    },
+    "lockableLabel": {
+      "lockValue": "Lock value",
+      "unlockValue": "Unlock value"
+    },
+    "tabs": {
+      "components": "Components",
+      "dashboard": "Dashboard",
+      "mail": "Mail",
+      "chat": "Chat",
+      "finances": "Finances"
+    }
+  },
+  "demos": {
+    "alert": {
+      "title": "You have 2 credits left",
+      "description": "Get a paid plan for more credits",
+      "action": "Upgrade"
+    },
+    "alertDialog": {
+      "title": "Unsaved changes",
+      "description": "Do you want to save or discard changes?",
+      "discard": "Discard",
+      "save": "Save changes"
+    },
+    "allowNotifications": {
+      "label": "Allow notifications",
+      "description": "Receive push notifications from HeroUI"
+    },
+    "buttons": {
+      "clickMe": "Click me"
+    },
+    "inputOtp": {
+      "label": "Verify account",
+      "description": "We've sent a code to a****@gmail.com",
+      "didntReceive": "Didn't receive a code?",
+      "resend": "Resend"
+    },
+    "listBox": {
+      "ariaLabel": "File actions",
+      "actions": "Actions",
+      "newFile": "New file",
+      "newFileDescription": "Create a new file",
+      "editFile": "Edit file",
+      "editFileDescription": "Make changes",
+      "dangerZone": "Danger zone",
+      "deleteFile": "Delete file",
+      "deleteFileDescription": "Move to trash"
+    },
+    "login": {
+      "title": "Create an account",
+      "trialNote": "Start your free 7-day trial. No credit card required.",
+      "getStarted": "Get Started",
+      "or": "Or",
+      "continueWithGoogle": "Continue with Google",
+      "continueWithApple": "Continue with Apple"
+    },
+    "select": {
+      "placeholder": "Select one",
+      "label": "State",
+      "options": {
+        "florida": "Florida",
+        "delaware": "Delaware",
+        "california": "California",
+        "texas": "Texas",
+        "newYork": "New York",
+        "washington": "Washington"
+      }
+    },
+    "slider": {
+      "label": "Price"
+    },
+    "subtleCards": {
+      "indieTitle": "Indie Hackers",
+      "indieMembers": "148 members",
+      "indieBy": "By John",
+      "aiTitle": "AI Builders",
+      "aiMembers": "362 members",
+      "aiBy": "By Martha"
+    },
+    "tabs1": {
+      "ariaLabel": "Options",
+      "all": "All"
+    },
+    "tabs2": {
+      "ariaLabel": "Options",
+      "chats": "Chats",
+      "emails": "Emails"
+    },
+    "textfield": {
+      "label": "Your email",
+      "placeholder": "john@email.com",
+      "description": "We won't share your email",
+      "error": "The email is invalid"
+    },
+    "uiComponents": {
+      "checkboxAriaLabel": "Checkbox Indicator Example",
+      "switchAriaLabel": "Switch On State Example",
+      "radioAriaLabel": "Radio Buttons Example"
+    },
+    "xProfile": {
+      "bio": "Building the future of UI for web & mobile.",
+      "bioSuffix": "(YC S24)",
+      "confettiLabel": "confetti",
+      "following": "Following",
+      "followers": "Followers"
+    }
+  },
+  "pageActions": {
+    "copyMarkdown": "Copy Markdown",
+    "copied": "Copied",
+    "moreOptions": "More options",
+    "askWithUrl": "Read {url}, I want to ask questions about it.",
+    "askFallback": "I want to ask questions about this documentation.",
+    "items": {
+      "markdown": {
+        "title": "View as Markdown",
+        "description": "View page as Markdown format"
+      },
+      "cursor": {
+        "title": "Add to Cursor",
+        "description": "Install MCP Server on Cursor"
+      },
+      "vscode": {
+        "title": "Add to VS Code",
+        "description": "Install MCP Server on VS Code"
+      },
+      "chatgpt": {
+        "title": "Open in ChatGPT",
+        "description": "Ask questions about this page"
+      },
+      "claude": {
+        "title": "Open in Claude",
+        "description": "Ask questions about this page"
+      }
+    }
+  }
+}
diff --git a/apps/docs/src/lib/get-llm-text.ts b/apps/docs/src/lib/get-llm-text.ts
new file mode 100644
index 0000000..3fe14ba
--- /dev/null
+++ b/apps/docs/src/lib/get-llm-text.ts
@@ -0,0 +1,323 @@
+import type {Page} from "@/lib/source";
+
+import {readFile} from "node:fs/promises";
+import {join} from "node:path";
+
+import {remarkNpm} from "fumadocs-core/mdx-plugins";
+import {remarkInclude} from "fumadocs-mdx/config";
+import {remarkAutoTypeTable} from "fumadocs-typescript";
+import {remark} from "remark";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+
+import {getRelatedComponents} from "@/components-registry";
+import {siteConfig} from "@/config/site";
+import {getDemo} from "@/demos";
+
+const processor = remark()
+  .use(remarkMdx)
+  .use(remarkInclude)
+  .use(remarkGfm)
+  .use(remarkAutoTypeTable)
+  .use(remarkNpm);
+
+const CONTENT_DIR = "content/docs";
+const DEMOS_DIR = "src/demos";
+const DEFAULT_CATEGORY = "docs";
+const DEFAULT_TITLE = "Untitled";
+const MAX_RELATED_COMPONENTS = 3;
+
+function normalizePagePath(pagePath: string): string {
+  return pagePath.endsWith(".mdx") ? pagePath : `${pagePath}.mdx`;
+}
+
+async function getRawMDXContent(pagePath: string): Promise<string> {
+  try {
+    const normalizedPath = normalizePagePath(pagePath);
+    // `page.path` already includes the locale prefix when using `parser: "dir"`
+    // (e.g. `en/react/components/(navigation)/accordion.mdx`), so we must not
+    // prepend the locale again here.
+    const filePath = join(process.cwd(), CONTENT_DIR, normalizedPath);
+
+    const content = await readFile(filePath, "utf-8");
+
+    if (!content.trim()) {
+      console.warn(`MDX file is empty: ${filePath}`);
+
+      return "";
+    }
+
+    return content;
+  } catch (error) {
+    console.error(`Failed to read MDX file: ${pagePath}`, error);
+
+    return "";
+  }
+}
+
+function formatAbsoluteUrl(path: string): string {
+  if (!path) return "";
+
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+
+  const baseUrl = siteConfig.siteUrl.toString().replace(/\/$/, "");
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+  return `${baseUrl}${cleanPath}`;
+}
+
+function formatLLMHeader(
+  category: string,
+  title: string,
+  url: string,
+  sourcePath: string,
+  description: string,
+): string {
+  const descriptionBlock = description ? `\n> ${description}\n` : "\n";
+  const absoluteUrl = formatAbsoluteUrl(url);
+
+  return `# ${title}
+
+**Category**: ${category}
+**URL**: ${absoluteUrl}
+**Source**: ${siteConfig.githubRawUrl}/${sourcePath}${descriptionBlock}`;
+}
+
+export async function getLLMText(page: Page) {
+  const category = page.slugs[0] || DEFAULT_CATEGORY;
+  const title = page.data.title || DEFAULT_TITLE;
+  const description = page.data.description || "";
+  const url = page.url || "";
+  const normalizedPath = normalizePagePath(page.path);
+
+  const rawContent = await getRawMDXContent(page.path);
+  const header = formatLLMHeader(category, title, url, normalizedPath, description);
+
+  if (!rawContent) {
+    return `<page url="${url}">
+${header}
+
+*Content unavailable*
+</page>`;
+  }
+
+  // First, process MDX content to replace ComponentPreview, CollapsibleCode, etc.
+  const processedContent = await processMDXContent(rawContent, page.locale);
+
+  // Then process with remark to convert MDX to markdown
+  const processed = await processor.process({
+    path: join(process.cwd(), CONTENT_DIR, normalizedPath),
+    value: processedContent,
+  });
+
+  // Clean up any remaining component tags that remark might have preserved
+  const finalContent = processed.value
+    .toString()
+    .replace(
+      /<(ComponentPreview|CollapsibleCode|RelatedComponents|RelatedShowcases|DocsImage|NativeVideoPlayerView|NativeTryOnDevice)[^>]*\/?>/g,
+      "",
+    );
+
+  return `<page url="${url}">
+${header}
+
+${finalContent}
+</page>`;
+}
+
+const COMPONENT_PREVIEW_REGEX = /<ComponentPreview\s+name\s*=\s*["']([^"']+)["'][^/>]*\/>/g;
+const REGEX_ESCAPE = /[.*+?^${}()|[\]\\]/g;
+
+async function replaceComponentPreview(content: string, lang?: string): Promise<string> {
+  const matches = Array.from(content.matchAll(COMPONENT_PREVIEW_REGEX));
+
+  if (matches.length === 0) return content;
+
+  const replacements = await Promise.all(
+    matches.map(async (match) => {
+      const fullMatch = match[0];
+      const demoName = match[1];
+
+      if (!demoName) {
+        return {match: fullMatch, replacement: fullMatch};
+      }
+
+      const demo = getDemo(demoName, lang);
+
+      if (!demo?.file) {
+        return {match: fullMatch, replacement: fullMatch};
+      }
+
+      try {
+        const filePath = join(process.cwd(), DEMOS_DIR, demo.file);
+        const code = await readFile(filePath, "utf-8");
+
+        return {
+          match: fullMatch,
+          replacement: `\`\`\`tsx\n${code}\n\`\`\``,
+        };
+      } catch {
+        return {match: fullMatch, replacement: fullMatch};
+      }
+    }),
+  );
+
+  let result = content;
+  const processedMatches = new Set<string>();
+
+  for (const {match, replacement} of replacements) {
+    if (processedMatches.has(match)) continue;
+
+    processedMatches.add(match);
+    const escapedMatch = match.replace(REGEX_ESCAPE, "\\$&");
+    const regex = new RegExp(escapedMatch, "g");
+
+    result = result.replace(regex, replacement);
+  }
+
+  return result;
+}
+
+const COLLAPSIBLE_CODE_REGEX =
+  /<CollapsibleCode\s+lang\s*=\s*["']([^"']+)["']\s+code\s*=\s*{?`([\s\S]*?)`}?\s*\/>/g;
+
+function replaceCollapsibleCode(content: string): string {
+  return content.replace(COLLAPSIBLE_CODE_REGEX, (_match, lang, code) => {
+    return `\`\`\`${lang || "tsx"}\n${code}\n\`\`\``;
+  });
+}
+
+const RELATED_COMPONENTS_REGEX = /<RelatedComponents\s+component\s*=\s*["']([^"']+)["']\s*\/>/g;
+
+function replaceRelatedComponents(content: string): string {
+  return content.replace(RELATED_COMPONENTS_REGEX, (_match, componentName) => {
+    const relatedComponents =
+      getRelatedComponents(componentName)?.slice(0, MAX_RELATED_COMPONENTS) || [];
+
+    if (relatedComponents.length === 0) {
+      return "";
+    }
+
+    const componentList = relatedComponents
+      .map(
+        (comp) =>
+          `- **${comp.title || "Untitled Component"}**: ${comp.description || "A related component"}`,
+      )
+      .join("\n");
+
+    return `\n## Related Components\n\n${componentList}\n`;
+  });
+}
+
+const USELESS_COMPONENT_TAGS =
+  /<(ComponentCard|ComponentGrid|ComponentsCategory|ComponentPreview|CollapsibleCode|RelatedComponents|RelatedShowcases|DocsImage|NativeComponentsCategory|NativeVideoPlayerView|NativeTryOnDevice)[^>]*\/?>/g;
+const BR_TAG = /<br\s*\/>/g;
+const CODE_BLOCK_BEFORE = /([^\n`])\n(```[\w]*\n)/g;
+const CODE_BLOCK_AFTER = /(```[\s\S]*?```)\n([^\n`])/g;
+const EXCESSIVE_NEWLINES = /\n{3,}/g;
+const FRONTMATTER_SPACING = /^(---\s*\n[\s\S]*?\n---\s*\n)([^\n])/m;
+const FRONTMATTER_CONTENT = /^---\s*\n[\s\S]*?\n---\s*\n/m;
+const YAML_FRONTMATTER_LINES = /^(title|description|icon|links|image|darkSrc|src):\s*.*$/gm;
+const SEPARATOR_LINE = /^-{3,}$/gm;
+
+function cleanContentForLLM(content: string): string {
+  let processed = content.replace(USELESS_COMPONENT_TAGS, "").replace(BR_TAG, "\n");
+
+  // Process headings outside code blocks
+  // Split by code blocks to avoid matching headings inside code
+  const codeBlockRegex = /```[\s\S]*?```/g;
+  const parts: Array<{isCode: boolean; text: string}> = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = codeBlockRegex.exec(content)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push({isCode: false, text: content.slice(lastIndex, match.index)});
+    }
+    parts.push({isCode: true, text: match[0]});
+    lastIndex = codeBlockRegex.lastIndex;
+  }
+
+  if (lastIndex < content.length) {
+    parts.push({isCode: false, text: content.slice(lastIndex)});
+  }
+
+  if (parts.length > 0) {
+    processed = parts
+      .map((part) => {
+        if (part.isCode) {
+          return part.text;
+        }
+
+        return part.text.replace(/\n(#{1,6}\s+[^\n]+)\n/g, "\n\n$1\n\n");
+      })
+      .join("");
+  } else {
+    processed = processed.replace(/\n(#{1,6}\s+[^\n]+)\n/g, "\n\n$1\n\n");
+  }
+
+  processed = processed
+    .replace(CODE_BLOCK_BEFORE, "$1\n\n$2")
+    .replace(CODE_BLOCK_AFTER, "$1\n\n$2")
+    .replace(EXCESSIVE_NEWLINES, "\n\n")
+    .replace(FRONTMATTER_SPACING, "$1\n$2")
+    .replace(FRONTMATTER_CONTENT, "")
+    .replace(YAML_FRONTMATTER_LINES, "")
+    .replace(SEPARATOR_LINE, "")
+    .trim();
+
+  return processed;
+}
+
+async function processMDXContent(content: string, lang?: string): Promise<string> {
+  let processed = replaceCollapsibleCode(content);
+
+  processed = await replaceComponentPreview(processed, lang);
+  processed = replaceRelatedComponents(processed);
+  processed = cleanContentForLLM(processed);
+
+  return processed;
+}
+
+export async function getLLMRawText(page: Page) {
+  const category = page.slugs[0] || DEFAULT_CATEGORY;
+  const title = page.data.title || DEFAULT_TITLE;
+  const description = page.data.description || "";
+  const url = page.url || "";
+  const normalizedPath = normalizePagePath(page.path);
+  const header = formatLLMHeader(category, title, url, normalizedPath, description);
+
+  const rawContent = await getRawMDXContent(page.path);
+
+  if (!rawContent) {
+    return `<page url="${url}">
+${header}
+
+***
+
+*Content unavailable*
+</page>`;
+  }
+
+  const processedContent = await processMDXContent(rawContent, page.locale);
+
+  if (!processedContent.trim()) {
+    return `<page url="${url}">
+${header}
+
+***
+
+*Content processed but empty*
+</page>`;
+  }
+
+  return `<page url="${url}">
+${header}
+
+***
+
+${processedContent}
+</page>`;
+}
diff --git a/apps/docs/src/lib/i18n.ts b/apps/docs/src/lib/i18n.ts
new file mode 100644
index 0000000..53f4b85
--- /dev/null
+++ b/apps/docs/src/lib/i18n.ts
@@ -0,0 +1,8 @@
+import {defineI18n} from "fumadocs-core/i18n";
+
+export const i18n = defineI18n({
+  defaultLanguage: "en",
+  languages: ["en", "cn"],
+  // content/docs/{locale}/react/...
+  parser: "dir",
+});
diff --git a/apps/docs/src/lib/json-ld.ts b/apps/docs/src/lib/json-ld.ts
new file mode 100644
index 0000000..5a65e9b
--- /dev/null
+++ b/apps/docs/src/lib/json-ld.ts
@@ -0,0 +1,133 @@
+import {siteConfig} from "@/config/site";
+
+export function getOrganizationJsonLd() {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    logo: "https://heroui.com/icons/favicon.svg",
+    name: "HeroUI",
+    sameAs: [siteConfig.links.github, siteConfig.links.twitter, siteConfig.links.discord],
+    url: "https://heroui.com",
+  };
+}
+
+export function getWebSiteJsonLd() {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    description: siteConfig.description,
+    name: "HeroUI",
+    publisher: {
+      "@type": "Organization",
+      name: "HeroUI",
+    },
+    url: "https://heroui.com",
+  };
+}
+
+export function getSoftwareApplicationJsonLd() {
+  return {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    applicationCategory: "DeveloperApplication",
+    description: siteConfig.description,
+    downloadUrl: "https://www.npmjs.com/package/@heroui/react",
+    name: "HeroUI",
+    offers: {
+      "@type": "Offer",
+      price: "0",
+      priceCurrency: "USD",
+    },
+    operatingSystem: "Any",
+    url: "https://heroui.com",
+  };
+}
+
+export function getBreadcrumbJsonLd(items: {name: string; url: string}[]) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      item: item.url,
+      name: item.name,
+      position: index + 1,
+    })),
+  };
+}
+
+export function getTechArticleJsonLd(params: {
+  title: string;
+  description: string;
+  url: string;
+  datePublished?: string;
+  dateModified?: string;
+  authorName?: string;
+  authorUrl?: string;
+  image?: string;
+}) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    author: params.authorName
+      ? {
+          "@type": "Person",
+          name: params.authorName,
+          ...(params.authorUrl && {url: params.authorUrl}),
+        }
+      : {
+          "@type": "Organization",
+          name: "HeroUI",
+        },
+    description: params.description,
+    headline: params.title,
+    mainEntityOfPage: {
+      "@id": params.url,
+      "@type": "WebPage",
+    },
+    publisher: {
+      "@type": "Organization",
+      logo: {
+        "@type": "ImageObject",
+        url: "https://heroui.com/icons/favicon.svg",
+      },
+      name: "HeroUI",
+    },
+    url: params.url,
+    ...(params.datePublished && {datePublished: params.datePublished}),
+    ...(params.dateModified && {dateModified: params.dateModified || params.datePublished}),
+    ...(params.image && {image: params.image}),
+  };
+}
+
+export function getBlogJsonLd(params: {
+  url: string;
+  posts: {title: string; url: string; datePublished: string; description: string}[];
+  description?: string;
+  name?: string;
+}) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Blog",
+    blogPost: params.posts.map((post) => ({
+      "@type": "BlogPosting",
+      datePublished: post.datePublished,
+      description: post.description,
+      headline: post.title,
+      url: post.url,
+    })),
+    description:
+      params.description ??
+      "Guides, tutorials, and resources for building modern React applications with HeroUI.",
+    name: params.name ?? "HeroUI Blog",
+    publisher: {
+      "@type": "Organization",
+      logo: {
+        "@type": "ImageObject",
+        url: "https://heroui.com/icons/favicon.svg",
+      },
+      name: "HeroUI",
+    },
+    url: params.url,
+  };
+}
diff --git a/apps/docs/src/lib/layout.shared.tsx b/apps/docs/src/lib/layout.shared.tsx
new file mode 100644
index 0000000..a53fa38
--- /dev/null
+++ b/apps/docs/src/lib/layout.shared.tsx
@@ -0,0 +1,6 @@
+import {zhCN} from "@fumadocs/language/zh-cn";
+import {uiTranslations} from "fumadocs-ui/i18n";
+
+import {i18n} from "@/lib/i18n";
+
+export const translations = i18n.translations().extend(uiTranslations()).preset("cn", zhCN());
diff --git a/apps/docs/src/lib/llms-platform-handlers.ts b/apps/docs/src/lib/llms-platform-handlers.ts
new file mode 100644
index 0000000..ea5852d
--- /dev/null
+++ b/apps/docs/src/lib/llms-platform-handlers.ts
@@ -0,0 +1,174 @@
+import type {Platform} from "@/lib/llms-utils";
+import type {NextRequest} from "next/server";
+
+import {siteConfig} from "@/config/site";
+import {getLLMText} from "@/lib/get-llm-text";
+import {
+  LLMS_TEXT_HEADERS,
+  filterExcludedPages,
+  filterPagesByPlatform,
+  filterPagesByType,
+  generatePlatformIndexHeader,
+} from "@/lib/llms-utils";
+import {source} from "@/lib/source";
+
+function formatAbsoluteUrl(path: string): string {
+  if (!path) return "";
+
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+
+  const baseUrl = siteConfig.siteUrl.toString().replace(/\/$/, "");
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+  return `${baseUrl}${cleanPath}`;
+}
+
+export async function getPlatformLlmsTxt(platform: Platform) {
+  try {
+    const scanned = generatePlatformIndexHeader(platform);
+
+    const pages = filterExcludedPages(source.getPages());
+    const filteredPages = filterPagesByPlatform(pages, platform);
+
+    if (filteredPages.length === 0) {
+      return new Response(`No ${platform} documentation found`, {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const map = new Map<string, string[]>();
+
+    for (const page of filteredPages) {
+      const category = page.slugs[1] ?? "general";
+      const list = map.get(category) ?? [];
+      const absoluteUrl = formatAbsoluteUrl(page.url);
+
+      if (page.data.description) {
+        list.push(`- [${page.data.title}](${absoluteUrl}): ${page.data.description}`);
+      } else {
+        list.push(`- [${page.data.title}](${absoluteUrl})`);
+      }
+
+      map.set(category, list);
+    }
+
+    const sortedCategories = Array.from(map.keys()).sort();
+
+    for (const category of sortedCategories) {
+      const pages = map.get(category);
+
+      if (pages && pages.length > 0) {
+        scanned.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+        scanned.push("");
+        scanned.push(pages.join("\n"));
+        scanned.push("");
+      }
+    }
+
+    return new Response(scanned.join("\n"), {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error(`Error generating ${platform}/llms.txt:`, error);
+
+    return new Response("Error generating documentation index", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
+
+export async function getPlatformLlmsComponentsTxt(platform: Platform) {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+    const platformPages = filterPagesByPlatform(pages, platform);
+    const componentPages = filterPagesByType(platformPages, "components");
+
+    if (componentPages.length === 0) {
+      return new Response(`No ${platform} component documentation found`, {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scanned = await Promise.all(componentPages.map(getLLMText));
+
+    return new Response(scanned.join("\n\n"), {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error(`Error generating ${platform}/llms-components.txt:`, error);
+
+    return new Response("Error generating component documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
+
+export async function getPlatformLlmsFullTxt(platform: Platform) {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+    const filteredPages = filterPagesByPlatform(pages, platform);
+
+    if (filteredPages.length === 0) {
+      return new Response(`No ${platform} documentation found`, {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scanned = await Promise.all(filteredPages.map(getLLMText));
+
+    return new Response(scanned.join("\n\n"), {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error(`Error generating ${platform}/llms-full.txt:`, error);
+
+    return new Response("Error generating full documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
+
+export async function getPlatformLlmsPatternsTxt(platform: Platform) {
+  try {
+    const pages = filterExcludedPages(source.getPages());
+    const platformPages = filterPagesByPlatform(pages, platform);
+    const patternPages = filterPagesByType(platformPages, "patterns");
+
+    if (patternPages.length === 0) {
+      return new Response(`No ${platform} pattern documentation found`, {
+        headers: LLMS_TEXT_HEADERS,
+        status: 404,
+      });
+    }
+
+    const scanned = await Promise.all(patternPages.map(getLLMText));
+
+    return new Response(scanned.join("\n\n"), {
+      headers: LLMS_TEXT_HEADERS,
+    });
+  } catch (error) {
+    console.error(`Error generating ${platform}/llms-patterns.txt:`, error);
+
+    return new Response("Error generating pattern documentation", {
+      headers: LLMS_TEXT_HEADERS,
+      status: 500,
+    });
+  }
+}
+
+export function createPlatformRouteHandler(
+  platform: Platform,
+  handler: (platform: Platform) => Promise<Response>,
+) {
+  return async function GET(_req: NextRequest) {
+    return handler(platform);
+  };
+}
diff --git a/apps/docs/src/lib/llms-utils.ts b/apps/docs/src/lib/llms-utils.ts
new file mode 100644
index 0000000..ac49f2d
--- /dev/null
+++ b/apps/docs/src/lib/llms-utils.ts
@@ -0,0 +1,138 @@
+import type {Page} from "@/lib/source";
+
+import {siteConfig} from "@/config/site";
+
+export type Platform = "react" | "native" | "all";
+
+export type ContentType = "all" | "components" | "patterns";
+
+export const LLMS_TEXT_HEADERS = {
+  "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
+  "Content-Type": "text/plain; charset=utf-8",
+} as const;
+
+export function getPlatformFromPage(page: Page): Platform {
+  const firstSlug = page.slugs[0];
+
+  if (firstSlug === "react") return "react";
+  if (firstSlug === "native") return "native";
+
+  return "all";
+}
+
+export function validatePlatform(platform: string | undefined): Platform | null {
+  if (!platform) return "all";
+  if (platform === "react" || platform === "native") return platform;
+
+  return null;
+}
+
+export function filterPagesByPlatform(pages: Page[], platform: Platform): Page[] {
+  if (platform === "all") return pages;
+
+  return pages.filter((page) => {
+    const pagePlatform = getPlatformFromPage(page);
+
+    return pagePlatform === platform;
+  });
+}
+
+export function isComponentPage(page: Page): boolean {
+  return page.url.includes("/components/");
+}
+
+export function isPatternPage(page: Page): boolean {
+  return page.url.includes("/getting-started/") || page.url.includes("/handbook/");
+}
+
+export function filterPagesByType(pages: Page[], type: ContentType): Page[] {
+  if (type === "all") return pages;
+
+  return pages.filter((page) => {
+    if (type === "components") return isComponentPage(page);
+    if (type === "patterns") return isPatternPage(page);
+
+    return false;
+  });
+}
+
+export function filterExcludedPages(pages: Page[]): Page[] {
+  return pages.filter((page) => page.slugs[0] !== "openapi");
+}
+
+function formatAbsoluteUrl(path: string): string {
+  if (!path) return "";
+
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+
+  const baseUrl = siteConfig.siteUrl.toString().replace(/\/$/, "");
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+
+  return `${baseUrl}${cleanPath}`;
+}
+
+export function generateIndexHeader(): string[] {
+  const reactUrl = "/react/llms.txt";
+  const nativeUrl = "/native/llms.txt";
+  const reactAbsoluteUrl = formatAbsoluteUrl(reactUrl);
+  const nativeAbsoluteUrl = formatAbsoluteUrl(nativeUrl);
+
+  return [
+    "# HeroUI v3 Documentation",
+    "",
+    "> A set of beautiful, customizable React and React Native components that stay maintained and up to date.",
+    "",
+    "HeroUI v3 is an open-source UI component library for building modern web and mobile applications. Built on [Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/), HeroUI provides accessible, customizable components with smooth animations and polished details.",
+    "",
+    "**Key Features:**",
+    "",
+    "- Beautiful by default - Professional look out of the box, no extra styling needed",
+    "- Accessible - Built with accessibility in mind, following WAI-ARIA guidelines",
+    "- Flexible - Each component is made of customizable parts",
+    "- Developer-friendly - Fully typed APIs, predictable patterns, and excellent autocompletion",
+    "- Maintained - Regular updates, bug fixes, and new features",
+    "",
+    "**Technology Stack:**",
+    "",
+    "- React 19+ for web components",
+    "- React Native for mobile components",
+    "- Tailwind CSS v4 for styling",
+    "- TypeScript for type safety",
+    "",
+    "## Available Platforms",
+    "",
+    `- **React (Web)**: [${reactUrl}](${reactAbsoluteUrl}) - React component library for web applications`,
+    `- **React Native**: [${nativeUrl}](${nativeAbsoluteUrl}) - React Native component library for mobile applications`,
+    "",
+    "## Documentation Index",
+    "",
+  ];
+}
+
+export function generatePlatformIndexHeader(platform: Platform): string[] {
+  const platformName = platform.charAt(0).toUpperCase() + platform.slice(1);
+  const isReact = platform === "react";
+  const techStack = isReact
+    ? "[Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/)"
+    : "[Tailwind v4](https://tailwindcss.com/) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies";
+
+  return [
+    `# HeroUI v3 ${platformName} Documentation`,
+    "",
+    `> Documentation for HeroUI ${platformName} component library.`,
+    "",
+    `HeroUI ${platformName} is a component library built on ${techStack}. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.`,
+    "",
+    "**Key Features:**",
+    "",
+    "- Beautiful by default - Professional look out of the box",
+    "- Accessible - Built with accessibility best practices",
+    "- Flexible - Customizable components with predictable patterns",
+    "- Developer-friendly - Fully typed APIs and excellent autocompletion",
+    "",
+    "## Documentation Index",
+    "",
+  ];
+}
diff --git a/apps/docs/src/lib/meta-icon.tsx b/apps/docs/src/lib/meta-icon.tsx
new file mode 100644
index 0000000..7305760
--- /dev/null
+++ b/apps/docs/src/lib/meta-icon.tsx
@@ -0,0 +1,21 @@
+import {Iconify} from "@/components/iconify";
+import StatusChip from "@/components/status-chip";
+
+export function createMetaIcon(iconName: string | undefined) {
+  if (!iconName) return undefined;
+
+  //  FIXME: Hacky way to show a new badge
+  if (
+    iconName === "new" ||
+    iconName === "new-dot" ||
+    iconName === "preview" ||
+    iconName === "updated"
+  ) {
+    // Stable key based on iconName — fumadocs renders the icon as an array
+    // child (e.g. `[node.icon, node.name]`), so a key is required to silence
+    // React's "unique key" warning while remaining hydration-safe.
+    return <StatusChip key={`status-${iconName}`} className="order-last" status={iconName} />;
+  }
+
+  return <Iconify key={`icon-${iconName}`} icon={iconName} />;
+}
diff --git a/apps/docs/src/lib/rss.ts b/apps/docs/src/lib/rss.ts
new file mode 100644
index 0000000..d87e7b0
--- /dev/null
+++ b/apps/docs/src/lib/rss.ts
@@ -0,0 +1,83 @@
+import {stat} from "node:fs/promises";
+import {join} from "node:path";
+
+import {Feed} from "feed";
+
+import {siteConfig} from "@/config/site";
+import {getAllBlogPosts} from "@/lib/blog";
+import {i18n} from "@/lib/i18n";
+import {source} from "@/lib/source";
+
+async function getFileLastModified(pagePath: string, locale: string): Promise<Date> {
+  try {
+    const normalizedPath = pagePath.endsWith(".mdx") ? pagePath : `${pagePath}.mdx`;
+    const filePath = join(process.cwd(), "content/docs", locale, normalizedPath);
+    const stats = await stat(filePath);
+
+    return stats.mtime;
+  } catch {
+    return new Date();
+  }
+}
+
+export const getRSS = async (): Promise<string> => {
+  const currentYear = new Date().getFullYear();
+  const baseUrl = siteConfig.siteUrl;
+
+  const feed = new Feed({
+    copyright: `${currentYear} HeroUI Inc. All rights reserved.`,
+    description: siteConfig.description,
+    favicon: new URL("/favicon-dark.svg", baseUrl).toString(),
+    id: baseUrl.toString(),
+    image: new URL(siteConfig.ogImage, baseUrl).toString(),
+    language: "en-US",
+    link: baseUrl.toString(),
+    title: siteConfig.fullName,
+  });
+
+  const seenBlogIds = new Set<string>();
+
+  for (const locale of i18n.languages) {
+    for (const post of getAllBlogPosts(locale)) {
+      // Only emit each post once for its source locale, so fallback posts
+      // are not duplicated across the feed.
+      if (post.locale !== locale) continue;
+
+      const itemId = `/${locale}/blog/${post.slug}`;
+
+      if (seenBlogIds.has(itemId)) continue;
+      seenBlogIds.add(itemId);
+
+      const postUrl = new URL(itemId, baseUrl);
+
+      feed.addItem({
+        author: [{name: post.author}],
+        date: new Date(post.date),
+        description: post.description,
+        id: itemId,
+        link: postUrl.toString(),
+        title: post.title,
+      });
+    }
+  }
+
+  for (const page of source.getPages()) {
+    const pageUrl = new URL(page.url, baseUrl);
+    const lastModified = await getFileLastModified(page.path, page.locale ?? i18n.defaultLanguage);
+
+    feed.addItem({
+      author: [
+        {
+          name: siteConfig.creator,
+        },
+      ],
+      date: lastModified,
+      description: page.data.description || "HeroUI documentation page",
+      id: page.url,
+      link: pageUrl.toString(),
+      title: page.data.title,
+    });
+  }
+
+  return feed.rss2();
+};
diff --git a/apps/docs/src/lib/skills-constants.mjs b/apps/docs/src/lib/skills-constants.mjs
new file mode 100644
index 0000000..64f2622
--- /dev/null
+++ b/apps/docs/src/lib/skills-constants.mjs
@@ -0,0 +1,4 @@
+/**
+ * Valid skill names that can be installed
+ */
+export const VALID_SKILLS = ["heroui-react", "heroui-native", "heroui-migration"];
diff --git a/apps/docs/src/lib/source.ts b/apps/docs/src/lib/source.ts
new file mode 100644
index 0000000..3a06470
--- /dev/null
+++ b/apps/docs/src/lib/source.ts
@@ -0,0 +1,23 @@
+import type {InferMetaType, InferPageType} from "fumadocs-core/source";
+
+import {loader} from "fumadocs-core/source";
+
+import {i18n} from "@/lib/i18n";
+
+import {createMetaIcon} from "./meta-icon";
+
+import {docs} from "@/.source";
+
+// `loader()` also assign a URL to your pages
+// See https://fumadocs.vercel.app/docs/headless/source-api for more info
+export const source = loader({
+  baseUrl: "/docs",
+  i18n,
+  icon(icon) {
+    return createMetaIcon(icon);
+  },
+  source: docs.toFumadocsSource(),
+});
+
+export type Page = InferPageType<typeof source>;
+export type Meta = InferMetaType<typeof source>;
diff --git a/apps/docs/src/libs/posthog.ts b/apps/docs/src/libs/posthog.ts
new file mode 100644
index 0000000..d64fbb1
--- /dev/null
+++ b/apps/docs/src/libs/posthog.ts
@@ -0,0 +1,34 @@
+import {PostHog} from "posthog-node";
+
+import {env} from "~env";
+
+export const getPostHogClient = () => {
+  if (!env.NEXT_PUBLIC_POSTHOG_KEY) {
+    return null;
+  }
+
+  const posthogClient = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
+    flushAt: 1,
+    flushInterval: 0,
+    host: env.NEXT_PUBLIC_POSTHOG_HOST,
+  });
+
+  return posthogClient;
+};
+
+export const captureEvent = async (eventMessage: Omit<EventMessage, "distinctId">) => {
+  const posthog = getPostHogClient();
+
+  if (!posthog || env.NEXT_PUBLIC_APP_ENV !== "production") {
+    return;
+  }
+
+  posthog.capture({
+    distinctId: "unknown",
+    ...eventMessage,
+  });
+
+  await posthog.shutdown();
+};
+
+type EventMessage = Parameters<PostHog["capture"]>[0];
diff --git a/apps/docs/src/mdx-components.tsx b/apps/docs/src/mdx-components.tsx
new file mode 100644
index 0000000..1bd0f2a
--- /dev/null
+++ b/apps/docs/src/mdx-components.tsx
@@ -0,0 +1,197 @@
+import type {MDXComponents} from "mdx/types";
+
+import {Callout as FDCallout} from "fumadocs-ui/components/callout";
+import {Card, Cards} from "fumadocs-ui/components/card";
+import {Pre} from "fumadocs-ui/components/codeblock";
+import * as TabsComponents from "fumadocs-ui/components/tabs";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import {Suspense} from "react";
+
+import {CollapsibleCode} from "./components/collapsible-code";
+import {ComponentPreview, ComponentPreviewFallback} from "./components/component-preview";
+import {ComponentsCategory} from "./components/components-category";
+import {CopyPrompt} from "./components/copy-prompt";
+import {DocsImage} from "./components/docs-image";
+import {Iconify} from "./components/iconify";
+import {LocaleLink} from "./components/locale-link";
+import {
+  ComponentsCategory as NativeComponentsCategory,
+  ImageHeroView as NativeImageHeroView,
+  QRPreviewPopover as NativeQRPreviewPopover,
+  TryOnDevice as NativeTryOnDevice,
+  VideoPlayerView as NativeVideoPlayerView,
+} from "./components/native";
+import {NewsletterForm} from "./components/newsletter-form";
+import {RelatedComponents as RelatedComponentsComponent} from "./components/related-components";
+import {RelatedShowcases as RelatedShowcasesComponent} from "./components/related-showcases";
+import {VideoPlayer} from "./components/video-player";
+import {getComponentCount, getExampleCount} from "./demos";
+import {FumadocsCustomCodeblock as CodeBlock} from "./mdx-components/fumadocs-custom-codeblock";
+import {PackageManagers} from "./mdx-components/package-managers";
+import {cn} from "./utils/cn";
+
+// Create icon components using gravity-ui icons
+const AlertTriangle = (props: any) => <Iconify {...props} icon="circle-exclamation-fill" />;
+const CheckCircle = (props: any) => <Iconify {...props} icon="circle-check-fill" />;
+const XCircle = (props: any) => <Iconify {...props} icon="circle-xmark-fill" />;
+const Info = (props: any) => <Iconify {...props} icon="circle-info-fill" />;
+const X = (props: any) => <Iconify {...props} icon="xmark" />;
+const Star = (props: any) => <Iconify {...props} icon="star-fill" />;
+
+const Icon = (props: any) => <Iconify {...props} />;
+
+function ComponentCount({locale}: {locale?: string} = {}) {
+  return <>{getComponentCount(locale)}</>;
+}
+
+function ExampleCount({locale}: {locale?: string} = {}) {
+  return <>{getExampleCount(locale)}</>;
+}
+
+const MAX_LINES_FOR_LINE_NUMBERS = 20;
+
+function Preview({children}: {children: React.ReactNode}) {
+  return (
+    <div className="my-6 flex items-center justify-center rounded-lg border bg-background p-6">
+      {children}
+    </div>
+  );
+}
+
+function ComponentGrid({children}: {children: React.ReactNode}) {
+  return <div className="my-6 grid grid-cols-1 gap-4 md:grid-cols-2">{children}</div>;
+}
+
+function ComponentCard({
+  description,
+  href,
+  name,
+}: {
+  name: string;
+  description: string;
+  href: string;
+}) {
+  return (
+    <LocaleLink
+      className="block rounded-lg border p-4 transition-colors hover:bg-muted/50"
+      href={href}
+    >
+      <h3 className="mb-2 font-semibold">{name}</h3>
+      <p className="text-sm text-muted">{description}</p>
+    </LocaleLink>
+  );
+}
+
+// Wrapper component for RelatedShowcases with Suspense
+function RelatedShowcases(props: any) {
+  return (
+    <Suspense fallback={null}>
+      <RelatedShowcasesComponent {...props} />
+    </Suspense>
+  );
+}
+
+// Wrapper component for RelatedComponents with Suspense
+function RelatedComponents(props: any) {
+  return (
+    <Suspense fallback={null}>
+      <RelatedComponentsComponent {...props} />
+    </Suspense>
+  );
+}
+
+function ComponentPreviewWithSuspense(props: React.ComponentProps<typeof ComponentPreview>) {
+  return (
+    <Suspense fallback={<ComponentPreviewFallback />}>
+      <ComponentPreview {...props} />
+    </Suspense>
+  );
+}
+
+function Callout({className, ...props}: React.ComponentProps<typeof FDCallout>) {
+  return (
+    <FDCallout
+      {...props}
+      className={cn("bg-surface text-surface-foreground shadow-surface", className)}
+    />
+  );
+}
+
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+  return {
+    ...defaultMdxComponents,
+    ...TabsComponents,
+    AlertTriangle,
+    Callout,
+    Card,
+    Cards,
+    CheckCircle,
+    CodeBlock,
+    CollapsibleCode,
+    ComponentCard,
+    ComponentCount,
+    ComponentGrid,
+    ComponentPreview: ComponentPreviewWithSuspense,
+    ComponentsCategory,
+    CopyPrompt,
+    DocsImage,
+    ExampleCount,
+    Icon,
+    Info,
+    Link: LocaleLink,
+    NativeComponentsCategory,
+    NativeImageHeroView,
+    NativeQRPreviewPopover,
+    NativeTryOnDevice,
+    NativeVideoPlayerView,
+    NewsletterForm,
+    PackageManagers,
+    Pre,
+    Preview,
+    RelatedComponents,
+    RelatedShowcases,
+    Star,
+    VideoPlayer,
+    X,
+    XCircle,
+    // HTML `ref` attribute conflicts with `forwardRef`
+    pre: ({children, ref: _ref, ...props}) => {
+      // Check if the code has more than 5 lines
+      let lineCount = 1;
+
+      // Extract the text content to count lines
+      const extractText = (node: any): string => {
+        if (typeof node === "string") return node;
+        if (node?.props?.children) {
+          if (Array.isArray(node.props.children)) {
+            return node.props.children.map(extractText).join("");
+          }
+
+          return extractText(node.props.children);
+        }
+
+        return "";
+      };
+
+      const codeContent = extractText(children);
+
+      lineCount = codeContent.split("\n").length;
+
+      // Only add line numbers class if more than 5 lines
+      const classes = cn(
+        "mdx-code-block",
+        lineCount > MAX_LINES_FOR_LINE_NUMBERS ? "docs-code-block-line-numbers" : undefined,
+        props.className,
+      );
+
+      return (
+        <CodeBlock {...props} className={classes}>
+          <Pre>{children}</Pre>
+        </CodeBlock>
+      );
+    },
+    ...components,
+  };
+}
+
+export const useMDXComponents = getMDXComponents;
diff --git a/apps/docs/src/mdx-components/fumadocs-custom-codeblock.tsx b/apps/docs/src/mdx-components/fumadocs-custom-codeblock.tsx
new file mode 100644
index 0000000..2f6092a
--- /dev/null
+++ b/apps/docs/src/mdx-components/fumadocs-custom-codeblock.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import type {CodeBlockProps} from "fumadocs-ui/components/codeblock";
+import type {ComponentProps, RefObject} from "react";
+
+import {buttonVariants} from "@heroui/react";
+import {CodeBlock} from "fumadocs-ui/components/codeblock";
+import {useCopyButton} from "fumadocs-ui/utils/use-copy-button";
+import {useRef} from "react";
+
+import {Iconify} from "@/components/iconify";
+import {cn} from "@/utils/cn";
+
+export function FumadocsCustomCodeblock({
+  allowCopy = true,
+  children,
+  code,
+  ...props
+}: {children: React.ReactNode; code?: string} & CodeBlockProps) {
+  const areaRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <CodeBlock
+      {...props}
+      allowCopy={allowCopy}
+      // @ts-expect-error - TODO: fumadocs-ui error
+      viewportProps={{ref: areaRef}}
+      Actions={(actionsProps) => (
+        <div {...actionsProps} className={cn("z-1! empty:hidden", actionsProps.className)}>
+          {!!allowCopy && <CopyButton code={code} containerRef={areaRef} />}
+        </div>
+      )}
+    >
+      {children}
+    </CodeBlock>
+  );
+}
+
+function CopyButton({
+  className,
+  code,
+  containerRef,
+  ...props
+}: ComponentProps<"button"> & {
+  code?: string;
+  containerRef: RefObject<HTMLElement | null>;
+}) {
+  const [checked, onClick] = useCopyButton(() => {
+    if (code) {
+      void navigator.clipboard.writeText(code);
+
+      return;
+    }
+
+    const pre = containerRef.current?.getElementsByTagName("pre").item(0);
+
+    if (!pre) return;
+
+    const clone = pre.cloneNode(true) as HTMLElement;
+
+    clone.querySelectorAll(".nd-copy-ignore").forEach((node) => {
+      node.replaceWith("\n");
+    });
+
+    void navigator.clipboard.writeText(clone.textContent ?? "");
+  });
+
+  return (
+    <button
+      aria-label={checked ? "Copied Text" : "Copy Text"}
+      data-checked={checked || undefined}
+      type="button"
+      className={buttonVariants({
+        class: cn("-mt-0.5 bg-transparent text-muted", className),
+        isIconOnly: true,
+        size: "sm",
+        variant: "ghost",
+      })}
+      onClick={onClick}
+      {...props}
+    >
+      {checked ? <Iconify icon="check" /> : <Iconify icon="copy" />}
+    </button>
+  );
+}
diff --git a/apps/docs/src/mdx-components/package-managers.tsx b/apps/docs/src/mdx-components/package-managers.tsx
new file mode 100644
index 0000000..fb0eaa0
--- /dev/null
+++ b/apps/docs/src/mdx-components/package-managers.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import {CodeBlock, Pre} from "fumadocs-ui/components/codeblock";
+import * as TabsComponents from "fumadocs-ui/components/tabs";
+
+import {BunIcon, CLIBoldIcon, NpmSmallIcon, PnpmIcon, YarnIcon} from "@/icons/dev";
+
+const {Tabs, TabsContent, TabsList, TabsTrigger} = TabsComponents;
+
+type PackageManagerName = "cli" | "npm" | "yarn" | "pnpm" | "bun";
+
+type PackageManager = {
+  icon: React.ReactNode;
+  name: PackageManagerName;
+  label?: string;
+};
+
+const packageManagers: PackageManager[] = [
+  {
+    icon: <CLIBoldIcon className="text-lg text-foreground" />,
+    label: "CLI",
+    name: "cli",
+  },
+  {
+    icon: <PnpmIcon className="text-foreground" />,
+    name: "pnpm",
+  },
+  {
+    icon: <NpmSmallIcon className="text-foreground" />,
+    name: "npm",
+  },
+  {
+    icon: <YarnIcon className="text-foreground" />,
+    name: "yarn",
+  },
+  {
+    icon: <BunIcon className="text-foreground" />,
+    name: "bun",
+  },
+];
+
+export interface PackageManagersProps {
+  commands: Partial<Record<PackageManagerName, string>>;
+}
+
+export const PackageManagers = ({commands}: PackageManagersProps) => {
+  // Get the first available command as default
+  const availableManagers = packageManagers.filter((pm) => commands[pm.name]);
+  const defaultValue = availableManagers[0]?.name || "npm";
+
+  return (
+    <>
+      <Tabs
+        className="mt-4 w-full min-w-[300px] border-none bg-transparent"
+        defaultValue={defaultValue}
+      >
+        <TabsList className="mb-1 h-10 overflow-x-auto">
+          {packageManagers.map(({label, name}) => {
+            if (!commands[name]) return null;
+
+            return (
+              <TabsTrigger key={name} className="flex items-center gap-2" value={name}>
+                <span>{label || name}</span>
+              </TabsTrigger>
+            );
+          })}
+        </TabsList>
+        {packageManagers.map(({name}) => {
+          if (!commands[name]) return null;
+
+          return (
+            <TabsContent key={name} className="bg-transparent" value={name}>
+              <CodeBlock lang="bash">
+                <Pre className="px-3">{commands[name]}</Pre>
+              </CodeBlock>
+            </TabsContent>
+          );
+        })}
+      </Tabs>
+    </>
+  );
+};
diff --git a/apps/docs/src/proxy.ts b/apps/docs/src/proxy.ts
new file mode 100644
index 0000000..6ccfa54
--- /dev/null
+++ b/apps/docs/src/proxy.ts
@@ -0,0 +1,137 @@
+import type {NextRequest} from "next/server";
+
+import {NextResponse} from "next/server";
+
+import {getHomepageLinkHeader} from "@/lib/agent-discovery";
+import {acceptsMarkdown} from "@/lib/agent-markdown";
+import {i18n} from "@/lib/i18n";
+
+const MARKDOWN_EXCLUDED_PREFIXES = [
+  "/agent-markdown",
+  "/_next",
+  "/api",
+  "/.well-known",
+  "/assets",
+  "/fonts",
+  "/icons",
+  "/images",
+  "/og",
+  "/skills",
+];
+
+const MARKDOWN_EXCLUDED_PATHS = new Set([
+  "/browserconfig.xml",
+  "/favicon.ico",
+  "/manifest.webmanifest",
+  "/robots.txt",
+  "/rss.xml",
+  "/sitemap.xml",
+]);
+
+const PUBLIC_FILE_PATTERN = /\.[a-z0-9]+$/i;
+
+// Routes that live outside `app/[lang]` and must never receive a locale prefix.
+const LOCALE_REDIRECT_EXCLUDED_PREFIXES = [
+  ...MARKDOWN_EXCLUDED_PREFIXES,
+  "/install",
+  "/native",
+  "/react",
+  "/docs/native-showcase",
+];
+
+const SUPPORTED_LOCALES = new Set<string>(i18n.languages);
+const DEFAULT_LOCALE = i18n.defaultLanguage;
+
+function isHomepage(pathname: string): boolean {
+  return pathname === "/";
+}
+
+function getLocaleFromPath(pathname: string): string | undefined {
+  const firstSegment = pathname.split("/").filter(Boolean)[0];
+
+  return firstSegment && SUPPORTED_LOCALES.has(firstSegment) ? firstSegment : undefined;
+}
+
+function shouldSkipLocaleRedirect(pathname: string): boolean {
+  if (MARKDOWN_EXCLUDED_PATHS.has(pathname)) return true;
+  if (LOCALE_REDIRECT_EXCLUDED_PREFIXES.some((prefix) => pathname.startsWith(prefix))) return true;
+  if (pathname.startsWith("/llms")) return true;
+  // Files with extensions (e.g. .mdx) are handled by next.config.ts rewrites.
+  if (PUBLIC_FILE_PATTERN.test(pathname)) return true;
+
+  return false;
+}
+
+function shouldSkipMarkdownRewrite(pathname: string): boolean {
+  if (MARKDOWN_EXCLUDED_PATHS.has(pathname)) return true;
+  if (MARKDOWN_EXCLUDED_PREFIXES.some((prefix) => pathname.startsWith(prefix))) return true;
+  if (pathname.startsWith("/llms")) return true;
+  if (/^\/(react|native)\/llms/.test(pathname)) return true;
+
+  return PUBLIC_FILE_PATTERN.test(pathname) && !pathname.startsWith("/docs/");
+}
+
+function addHomepageDiscoveryHeaders(response: NextResponse, pathname: string): NextResponse {
+  if (isHomepage(pathname)) {
+    response.headers.set("Link", getHomepageLinkHeader());
+  }
+
+  return response;
+}
+
+export function proxy(request: NextRequest) {
+  const {pathname} = request.nextUrl;
+
+  // Markdown handler runs first so agent requests are served regardless of locale.
+  if (
+    (request.method === "GET" || request.method === "HEAD") &&
+    !shouldSkipMarkdownRewrite(pathname) &&
+    acceptsMarkdown(request)
+  ) {
+    const url = request.nextUrl.clone();
+
+    url.pathname = "/agent-markdown";
+    url.search = "";
+    url.searchParams.set("path", pathname);
+
+    const requestHeaders = new Headers(request.headers);
+
+    requestHeaders.set("x-heroui-markdown-path", pathname);
+
+    return addHomepageDiscoveryHeaders(
+      NextResponse.rewrite(url, {
+        request: {
+          headers: requestHeaders,
+        },
+      }),
+      pathname,
+    );
+  }
+
+  // Routes under `app/[lang]` require a locale prefix. When none is provided:
+  //   - the homepage (`/`) is internally rewritten to the default locale so the
+  //     visible URL stays clean.
+  //   - all other localized paths (e.g. `/docs/...`, `/blog/...`, `/themes`) are
+  //     redirected to include the default locale prefix.
+  if (!getLocaleFromPath(pathname) && !shouldSkipLocaleRedirect(pathname)) {
+    const url = request.nextUrl.clone();
+
+    if (pathname === "/") {
+      url.pathname = `/${DEFAULT_LOCALE}`;
+
+      return addHomepageDiscoveryHeaders(NextResponse.rewrite(url), pathname);
+    }
+
+    url.pathname = `/${DEFAULT_LOCALE}${pathname}`;
+
+    return NextResponse.redirect(url);
+  }
+
+  return addHomepageDiscoveryHeaders(NextResponse.next(), pathname);
+}
+
+export const config = {
+  // Matcher ignoring `/_next/` and `/api/`
+  // You may need to adjust it to ignore static assets in `/public` folder
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+};
diff --git a/apps/docs/src/showcases/authors.ts b/apps/docs/src/showcases/authors.ts
new file mode 100644
index 0000000..2bb304b
--- /dev/null
+++ b/apps/docs/src/showcases/authors.ts
@@ -0,0 +1,23 @@
+import type {ShowcaseAuthor} from "./types";
+
+export const CORE_TEAM_AUTHORS: Record<string, ShowcaseAuthor> = {
+  jrgarciadev: {
+    link: "https://x.com/jrgarciadev",
+    name: "Junior Garcia",
+    username: "jrgarciadev",
+  },
+};
+
+export const COMMUNITY_AUTHORS: Record<string, ShowcaseAuthor> = {
+  // Community contributors will be added here
+  // example: {
+  //   link: "https://github.com/username",
+  //   name: "Full Name",
+  //   username: "username",
+  // },
+};
+
+export const ALL_AUTHORS = {
+  ...CORE_TEAM_AUTHORS,
+  ...COMMUNITY_AUTHORS,
+};
diff --git a/apps/docs/src/showcases/index.ts b/apps/docs/src/showcases/index.ts
new file mode 100644
index 0000000..8a7f0a8
--- /dev/null
+++ b/apps/docs/src/showcases/index.ts
@@ -0,0 +1,39 @@
+export type {ShowcaseAuthor, Theme, ShowcaseItem, ShowcaseCategory} from "./types";
+
+import type {ShowcaseCategory, ShowcaseItem} from "./types";
+
+import {showcaseCategories} from "./registry";
+
+const showcasesMap: Record<string, ShowcaseItem & {category: string}> = {};
+
+showcaseCategories.forEach((category) => {
+  category.items.forEach((item) => {
+    showcasesMap[item.name] = {...item, category: category.name};
+  });
+});
+
+export function getShowcase(name: string): (ShowcaseItem & {category: string}) | undefined {
+  return showcasesMap[name];
+}
+
+export function getAllShowcases(): ShowcaseItem[] {
+  return showcaseCategories.flatMap((category) => category.items);
+}
+
+export function getShowcaseCategories(): ShowcaseCategory[] {
+  return showcaseCategories;
+}
+
+export function getShowcasesByCategory(categoryName: string): ShowcaseItem[] {
+  const category = showcaseCategories.find((cat) => cat.name === categoryName);
+
+  return category ? category.items : [];
+}
+
+export function getShowcasesByComponent(componentName: string): ShowcaseItem[] {
+  return showcaseCategories.flatMap((category) =>
+    category.items.filter((item) =>
+      item.components.some((comp) => comp.toLowerCase() === componentName.toLowerCase()),
+    ),
+  );
+}
diff --git a/apps/docs/src/showcases/navigation/apple-iphone-camera-zoom.tsx b/apps/docs/src/showcases/navigation/apple-iphone-camera-zoom.tsx
new file mode 100644
index 0000000..4f09701
--- /dev/null
+++ b/apps/docs/src/showcases/navigation/apple-iphone-camera-zoom.tsx
@@ -0,0 +1,100 @@
+"use client";
+
+import type {Key} from "react-aria-components";
+
+import {Tabs} from "@heroui/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+const DEFAULT_ZOOM = 200;
+
+const zoomLevels = [200, 100, 48, 35, 28, 24, 13, "macro"] as const;
+
+const zoomXMap: Record<number | "macro", string> = {
+  [100]: "4x",
+  [13]: "0.5x",
+  [200]: "8x",
+  [24]: "1x",
+  [28]: "1.2x",
+  [35]: "1.5x",
+  [48]: "2x",
+  ["macro"]: "0.2x",
+};
+
+const zoomImgMap: Record<number | "macro", string> = {
+  [100]:
+    "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/100mm__cykxcenbhvue_large_2x.jpg",
+  [13]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/13mm__dzafu9h1kaye_large_2x.jpg",
+  [200]:
+    "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/200mm__c8kya18imsqe_large_2x.jpg",
+  [24]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/24mm__e54cxtdkdrwy_large_2x.jpg",
+  [28]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/28mm__fylmxo06jq6i_large_2x.jpg",
+  [35]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/35mm__k375wbkrjp2e_large_2x.jpg",
+  [48]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/48mm__bmrwps1q6w76_large_2x.jpg",
+  ["macro"]:
+    "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/macro__bb7oud7ri2o2_large_2x.jpg",
+};
+
+export default function AppleIPhoneCameraZoom() {
+  const [selectedZoom, setSelectedZoom] = React.useState<Key>(DEFAULT_ZOOM);
+
+  return (
+    <div className="w-full">
+      <div className="flex flex-col items-center">
+        <div className="relative aspect-[7/5] w-full max-w-[840px] sm:h-[400px] md:h-[500px] lg:h-[540px]">
+          {Object.keys(zoomImgMap).map((key) => (
+            <img
+              key={key}
+              alt={`iPhone camera at ${key}${key === "macro" ? "" : "mm"} zoom`}
+              aria-hidden={selectedZoom !== key}
+              className="absolute inset-0 h-full w-full object-cover opacity-0 transition-opacity delay-200 duration-[800ms] ease-in-out data-[selected=true]:opacity-100 data-[selected=true]:delay-0"
+              data-selected={selectedZoom === key}
+              src={zoomImgMap[key as keyof typeof zoomImgMap]}
+            />
+          ))}
+        </div>
+        <Tabs defaultSelectedKey={DEFAULT_ZOOM} onSelectionChange={setSelectedZoom}>
+          <Tabs.ListContainer className="scrollbar-hide my-4 w-full max-w-full overflow-x-auto sm:my-6">
+            <Tabs.List
+              aria-label="Camera zoom options"
+              className="w-fit min-w-min rounded-full bg-surface-secondary *:h-8 *:w-fit *:px-3 *:text-xs *:font-normal *:text-muted *:opacity-80 *:hover:opacity-100 *:data-[selected=true]:text-black sm:*:h-9 sm:*:px-4 sm:*:text-sm"
+            >
+              {zoomLevels.map((zoom) => (
+                <Tabs.Tab
+                  key={zoom}
+                  className={zoom === "macro" ? "capitalize" : ""}
+                  id={zoom.toString()}
+                >
+                  {zoom} {zoom === "macro" ? "" : "mm"}
+                  <Tabs.Indicator className="rounded-full bg-white shadow-none duration-[320ms]" />
+                </Tabs.Tab>
+              ))}
+            </Tabs.List>
+          </Tabs.ListContainer>
+        </Tabs>
+        <div className="relative h-10 w-10">
+          {Object.keys(zoomXMap).map((key) => (
+            <p
+              key={key}
+              aria-hidden={selectedZoom !== key}
+              data-selected={selectedZoom === key}
+              className={cn(
+                "absolute top-1/2 left-1/2 origin-center -translate-x-1/2 -translate-y-1/2 scale-75 text-[21px] font-medium text-foreground opacity-0 transition-[scale,opacity] duration-[300ms] ease-[cubic-bezier(0.33,1,0.68,1)] ease-in-out-quad data-[selected=true]:scale-100 data-[selected=true]:opacity-100 data-[selected=true]:delay-200",
+                {
+                  "sr-only": selectedZoom !== key,
+                },
+              )}
+            >
+              {zoomXMap[key as keyof typeof zoomXMap]}
+            </p>
+          ))}
+        </div>
+        <footer className="mt-4 w-full px-4 text-center text-xs text-muted/50 sm:text-sm dark:text-muted/40">
+          <a href="https://www.apple.com/iphone-17-pro/" rel="noopener noreferrer" target="_blank">
+            Showcase based on Apple&apos;s iPhone 17 Pro camera zoom showcase
+          </a>
+        </footer>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/src/showcases/navigation/apple-iphone-disclosure.tsx b/apps/docs/src/showcases/navigation/apple-iphone-disclosure.tsx
new file mode 100644
index 0000000..7b4892f
--- /dev/null
+++ b/apps/docs/src/showcases/navigation/apple-iphone-disclosure.tsx
@@ -0,0 +1,237 @@
+"use client";
+
+import type {ButtonProps} from "@heroui/react";
+import type {SVGProps} from "react";
+
+import {Button, Disclosure, DisclosureGroup, useDisclosureGroupNavigation} from "@heroui/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+function AppleShowcaseButton({
+  children,
+  className,
+  isSelected,
+  ...props
+}: ButtonProps & {isSelected: boolean}) {
+  return (
+    <Button
+      className={cn(
+        "h-14 rounded-full bg-[#1e1e20] text-[17px] text-[#f5f5f7] duration-[400ms] ease-in-out-quad hover:bg-[#272729]",
+        isSelected && "bg-[#272729]",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Button>
+  );
+}
+
+function SelectedIphoneColorSwatch({color, name}: {color: string; name: string}) {
+  return (
+    <span
+      className="group relative size-6 rounded-lg shadow-[inset_0px_-1px_0px_0px_rgba(255,255,255,.5)]"
+      style={{
+        backgroundColor: `${color}`,
+      }}
+    >
+      <span className="sr-only">Copy {name} color</span>
+    </span>
+  );
+}
+
+function PlusIcon({className, height = 24, width = 24, ...props}: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      className={cn("size-6 flex-none", className)}
+      height={height}
+      viewBox="0 0 24 24"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <circle cx="12" cy="12" fill="none" r="11.3" stroke="currentColor" />
+      <g fill="currentColor" stroke="none" transform="translate(7 7)">
+        <path d="m9 4h-3v-3c0-0.553-0.447-1-1-1s-1 0.447-1 1v3h-3c-0.553 0-1 0.447-1 1s0.447 1 1 1h3v3c0 0.553 0.447 1 1 1s1-0.447 1-1v-3h3c0.553 0 1-0.447 1-1s-0.447-1-1-1" />
+      </g>
+    </svg>
+  );
+}
+
+const showcaseItems = [
+  {
+    content: "Choose from three bold finishes. iPhone 17 Pro shown in Cosmic Orange.",
+    id: "colors",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/colors_orange__f2ug4x6ry8uq_large_2x.jpg",
+    label: "Colors",
+  },
+  {
+    content:
+      "Optimized for performance and battery. Aluminum alloy is remarkably light and has exceptional thermal conductivity.",
+    id: "aluminum",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_aluminum_endframe__fypyvk9kkg2m_large_2x.jpg",
+    label: "Aluminum unibody",
+  },
+  {
+    content:
+      "Deionized water sealed inside moves heat away from the A19 Pro chip, allowing for even higher sustained performance.",
+    id: "vapor-chamber",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_vapor_chamber_endframe__dst8qkmuys4m_large_2x.jpg",
+    label: "Vapor chamber",
+  },
+  {
+    content:
+      "Protects the back of iPhone 17 Pro, making it 4x more resistant to cracks. New Ceramic Shield 2 on the front has 3x better scratch resistance.",
+    id: "ceramic-shield",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/ceramic_shield__de0653vp43cm_large_2x.jpg",
+    label: "Ceramic shield",
+  },
+  {
+    content:
+      "Our best‑ever 6.3‑inch and 6.9‑inch Super Retina XDR displays.5 Brighter. Better anti‑reflection. ProMotion up to 120Hz.",
+    id: "immersive-pro-display",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/pro_display__c0jmzc5emcae_large_2x.jpg",
+    label: "Immersive pro display",
+  },
+  {
+    content:
+      "Instantly take a photo, record video, adjust settings, and more. So you never miss a moment.",
+    id: "camera-control",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/camera_control__cy5kilwa0kwi_large_2x.jpg",
+    label: "Camera control",
+  },
+  {
+    content:
+      " A customizable fast track to your favorite feature. Long press to launch the action you want — Silent mode, Translation, Shortcuts, and more.",
+    id: "action-button",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_action_button_startframe__bb2coc4lpj2a_large_2x.jpg",
+    label: "Action button",
+  },
+];
+
+export default function AppleIPhoneDisclosure() {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["colors"]));
+  const itemIds = showcaseItems.map((item) => item.id);
+  const isAnyItemExpanded = expandedKeys.size > 0;
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <section className="w-full overflow-hidden">
+      <div className="flex w-full items-center gap-8 px-8 py-8">
+        <div
+          data-expanded={isAnyItemExpanded}
+          className={cn(
+            "z-[1] hidden flex-col gap-5 opacity-0 sm:flex",
+            "transition-all duration-300 ease-out-quad data-[expanded=true]:duration-400",
+            "translate-y-[120px] data-[expanded=true]:translate-y-0 data-[expanded=true]:opacity-100",
+            "scale-50 data-[expanded=true]:scale-100",
+          )}
+        >
+          <Button
+            isIconOnly
+            aria-label="Previous disclosure"
+            className="rounded-full transition-all duration-250 ease-smooth"
+            isDisabled={isPrevDisabled}
+            variant="secondary"
+            onPress={onPrevious}
+          >
+            <svg className="size-8 fill-foreground" viewBox="0 0 36 36">
+              <path d="m11 20c0-.3838.1465-.7676.4395-1.0605l5.5-5.5c.5854-.5859 1.5356-.5859 2.1211 0l5.5 5.5c.5859.5859.5859 1.5352 0 2.1211-.5854.5859-1.5356.5859-2.1211 0l-4.4395-4.4395-4.4395 4.4395c-.5854.5859-1.5356.5859-2.1211 0-.293-.293-.4395-.6768-.4395-1.0605z" />
+            </svg>
+          </Button>
+          <Button
+            isIconOnly
+            aria-label="Next disclosure"
+            className="rounded-full transition-all duration-250 ease-smooth"
+            isDisabled={isNextDisabled}
+            variant="secondary"
+            onPress={onNext}
+          >
+            <svg className="size-8 fill-foreground" viewBox="0 0 36 36">
+              <path d="m19.0625 22.5597 5.5-5.5076c.5854-.5854.5825-1.5323-.0039-2.1157-.5869-.5835-1.5366-.5815-2.1211.0039l-4.4375 4.4438-4.4375-4.4438c-.5845-.5854-1.5342-.5874-2.1211-.0039-.2944.2922-.4414.676-.4414 1.0598 0 .3818.1455.7637.4375 1.0559l5.5 5.5076c.2813.2815.6636.4403 1.0625.4403s.7812-.1588 1.0625-.4403z" />
+            </svg>
+          </Button>
+        </div>
+        <div className="z-[1] w-full max-w-md">
+          <DisclosureGroup
+            className="flex flex-col gap-y-3"
+            expandedKeys={expandedKeys}
+            onExpandedChange={setExpandedKeys}
+          >
+            {showcaseItems.map((item) => (
+              <Disclosure key={item.id} aria-label={item.label} id={item.id}>
+                <Disclosure.Heading>
+                  <AppleShowcaseButton isSelected={expandedKeys.has(item.id)} slot="trigger">
+                    <div className="flex w-full items-center justify-start gap-3">
+                      {item.id === "colors" ? (
+                        <SelectedIphoneColorSwatch color="#f77314" name="Cosmic Orange" />
+                      ) : (
+                        <PlusIcon />
+                      )}
+                      {item.label}
+                    </div>
+                  </AppleShowcaseButton>
+                </Disclosure.Heading>
+                <Disclosure.Content className="duration-[420ms] ease-[cubic-bezier(0.95,0.05,0.795,0.035)] ease-out-quad">
+                  <Disclosure.Body
+                    data-expanded={expandedKeys.has(item.id)}
+                    className={cn(
+                      "mt-3 flex max-w-sm flex-col items-center gap-2 rounded-2xl bg-[rgba(42,42,45,0.72)] p-7 text-left backdrop-blur-[20px]",
+                    )}
+                  >
+                    <p
+                      data-expanded={expandedKeys.has(item.id)}
+                      className={cn(
+                        "text-[17px] font-light text-[#F5F5F7]",
+                        "translate-y-[20px] opacity-0",
+                        "data-[expanded=true]:translate-y-0 data-[expanded=true]:opacity-100",
+                      )}
+                      style={{
+                        transition: expandedKeys.has(item.id)
+                          ? "opacity 1200ms ease-out, translate 800ms cubic-bezier(0.18,0.89,0.32,1.27)"
+                          : " ",
+                        willChange: "opacity, translate",
+                      }}
+                    >
+                      <strong className="font-medium">{item.label}</strong>.&nbsp;{item.content}
+                    </p>
+                  </Disclosure.Body>
+                </Disclosure.Content>
+              </Disclosure>
+            ))}
+          </DisclosureGroup>
+        </div>
+      </div>
+      {showcaseItems.map((item) => (
+        <img
+          key={item.id}
+          alt={item.label}
+          data-selected={expandedKeys.has(item.id)}
+          src={item.imgSrc}
+          className={cn(
+            "pointer-events-none absolute top-1/2 right-[10%] z-[0] hidden w-full max-w-6xl -translate-y-1/2 scale-[1.5] opacity-0 lg:block",
+            "translate-x-[10%] data-[selected=true]:translate-x-0 data-[selected=true]:opacity-100",
+          )}
+          style={{
+            transition: expandedKeys.has(item.id)
+              ? "opacity 1000ms ease-out, translate 900ms var(--ease-out-quad)"
+              : " ",
+            willChange: "opacity, translate",
+          }}
+        />
+      ))}
+    </section>
+  );
+}
diff --git a/apps/docs/src/showcases/registry/index.ts b/apps/docs/src/showcases/registry/index.ts
new file mode 100644
index 0000000..6c4ef69
--- /dev/null
+++ b/apps/docs/src/showcases/registry/index.ts
@@ -0,0 +1,17 @@
+import type {ShowcaseCategory} from "../types";
+
+import {navigationShowcases} from "./navigation";
+
+// Register all showcase categories here
+// This is the central place to add new category imports
+export const showcaseCategories: ShowcaseCategory[] = [
+  {
+    items: navigationShowcases,
+    name: "Navigation",
+  },
+  // Add more categories as needed, e.g.:
+  // {
+  //   items: cardShowcases,
+  //   name: "Cards",
+  // },
+];
diff --git a/apps/docs/src/showcases/registry/navigation.ts b/apps/docs/src/showcases/registry/navigation.ts
new file mode 100644
index 0000000..2a7dbae
--- /dev/null
+++ b/apps/docs/src/showcases/registry/navigation.ts
@@ -0,0 +1,38 @@
+import type {ShowcaseItem} from "../types";
+
+import {CORE_TEAM_AUTHORS} from "../authors";
+import AppleIPhoneCameraZoom from "../navigation/apple-iphone-camera-zoom";
+import AppleIPhoneDisclosure from "../navigation/apple-iphone-disclosure";
+
+const SHOWCASE_CDN_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/showcases";
+
+export const navigationShowcases: ShowcaseItem[] = [
+  {
+    author: CORE_TEAM_AUTHORS["jrgarciadev"],
+    component: AppleIPhoneDisclosure,
+    components: ["DisclosureGroup", "Disclosure", "Button"],
+    defaultTheme: "dark",
+    description: "Product feature showcase with disclosure groups inspired by Apple",
+    file: "apple-iphone-disclosure.tsx",
+    name: "apple-iphone-disclosure",
+    posterUrl: `${SHOWCASE_CDN_URL}/1.jpg`,
+    status: "new",
+    supportsThemeSwitching: false,
+    title: "Apple iPhone 17 Pro Disclosure",
+    videoUrl: `${SHOWCASE_CDN_URL}/1.mp4`,
+  },
+  {
+    author: CORE_TEAM_AUTHORS["jrgarciadev"],
+    component: AppleIPhoneCameraZoom,
+    components: ["Tabs"],
+    defaultTheme: "dark",
+    description: "Interactive camera zoom showcase inspired by Apple's iPhone 17 Pro",
+    file: "apple-iphone-camera-zoom.tsx",
+    name: "apple-iphone-camera-zoom",
+    posterUrl: `${SHOWCASE_CDN_URL}/2.jpg`,
+    status: "new",
+    supportsThemeSwitching: false,
+    title: "Apple iPhone 17 Pro Camera Zoom",
+    videoUrl: `${SHOWCASE_CDN_URL}/2.mp4`,
+  },
+];
diff --git a/apps/docs/src/showcases/types.ts b/apps/docs/src/showcases/types.ts
new file mode 100644
index 0000000..061db9d
--- /dev/null
+++ b/apps/docs/src/showcases/types.ts
@@ -0,0 +1,27 @@
+export interface ShowcaseAuthor {
+  name: string;
+  username: string;
+  link?: string;
+}
+
+export type Theme = "light" | "dark";
+
+export interface ShowcaseItem {
+  name: string;
+  title: string;
+  description: string;
+  component: React.ComponentType;
+  file: string;
+  components: string[]; // Components used in the showcase
+  supportsThemeSwitching?: boolean; // If false or undefined, theme switcher is disabled
+  defaultTheme?: Theme; // Default theme for showcases that don't support switching
+  author?: ShowcaseAuthor;
+  status?: "new" | "updated"; // Status badge for showcase - undefined means no badge
+  videoUrl?: string; // Optional video URL for showcase preview
+  posterUrl?: string; // Optional poster image URL for video
+}
+
+export interface ShowcaseCategory {
+  name: string;
+  items: ShowcaseItem[];
+}
diff --git a/apps/docs/src/styles/theme-presets.css b/apps/docs/src/styles/theme-presets.css
new file mode 100644
index 0000000..f5a5625
--- /dev/null
+++ b/apps/docs/src/styles/theme-presets.css
@@ -0,0 +1,851 @@
+/* ============================================================================
+   Auto-generated theme presets for docs.
+   Run: node apps/docs/scripts/build-theme-presets.mjs
+   ============================================================================ */
+@layer base {
+  /* Sky theme */
+  [data-design-theme="sky"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.015 230.34);
+    --border: oklch(90% 0.015 230.34);
+    --default: oklch(94% 0.015 230.34);
+    --default-foreground: oklch(21.03% 0.0059 230.34);
+    --field-background: oklch(100% 0.0075 230.34);
+    --field-border: oklch(90% 0.015 230.34);
+    --field-foreground: oklch(21.03% 0.015 230.34);
+    --field-placeholder: oklch(55.17% 0.03 230.34);
+    --foreground: oklch(21.03% 0.015 230.34);
+    --link: oklch(21.03% 0.015 230.34);
+    --muted: oklch(55.17% 0.03 230.34);
+    --overlay: oklch(100% 0.0045 230.34);
+    --overlay-foreground: oklch(21.03% 0.015 230.34);
+    --scrollbar: oklch(87.1% 0.015 230.34);
+    --segment: oklch(100% 0.015 230.34);
+    --segment-foreground: oklch(21.03% 0.015 230.34);
+    --separator: oklch(92% 0.015 230.34);
+    --surface: oklch(100% 0.0075 230.34);
+    --surface-foreground: oklch(21.03% 0.015 230.34);
+    --surface-secondary: oklch(95.24% 0.0225 230.34);
+    --surface-secondary-foreground: oklch(21.03% 0.015 230.34);
+    --surface-tertiary: oklch(93.73% 0.0225 230.34);
+    --surface-tertiary-foreground: oklch(21.03% 0.015 230.34);
+    --accent: oklch(82.76% 0.1013 230.34);
+    --accent-foreground: oklch(15% 0.0203 230.34);
+    --focus: oklch(82.76% 0.1013 230.34);
+    --success: oklch(73.29% 0.1992 148.02);
+    --success-foreground: oklch(21.03% 0.0059 148.02);
+    --warning: oklch(78.19% 0.1631 69.51);
+    --warning-foreground: oklch(21.03% 0.0059 69.51);
+    --danger: oklch(65.32% 0.2398 22.91);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="sky"].dark,
+  [data-design-theme="sky"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.015 230.34);
+    --border: oklch(28% 0.015 230.34);
+    --default: oklch(27.4% 0.015 230.34);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.03 230.34);
+    --field-border: oklch(28% 0.015 230.34);
+    --field-foreground: oklch(99.11% 0.015 230.34);
+    --field-placeholder: oklch(70.5% 0.03 230.34);
+    --foreground: oklch(99.11% 0.015 230.34);
+    --link: oklch(99.11% 0.015 230.34);
+    --muted: oklch(70.5% 0.03 230.34);
+    --overlay: oklch(21.03% 0.03 230.34);
+    --overlay-foreground: oklch(99.11% 0.015 230.34);
+    --scrollbar: oklch(70.5% 0.015 230.34);
+    --segment: oklch(39.64% 0.015 230.34);
+    --segment-foreground: oklch(99.11% 0.015 230.34);
+    --separator: oklch(25% 0.015 230.34);
+    --surface: oklch(21.03% 0.03 230.34);
+    --surface-foreground: oklch(99.11% 0.015 230.34);
+    --surface-secondary: oklch(25.7% 0.0225 230.34);
+    --surface-secondary-foreground: oklch(99.11% 0.015 230.34);
+    --surface-tertiary: oklch(27.21% 0.0225 230.34);
+    --surface-tertiary-foreground: oklch(99.11% 0.015 230.34);
+    --accent: oklch(82.76% 0.1013 230.34);
+    --accent-foreground: oklch(15% 0.0203 230.34);
+    --focus: oklch(82.76% 0.1013 230.34);
+    --success: oklch(73.29% 0.1992 148.02);
+    --success-foreground: oklch(21.03% 0.0059 148.02);
+    --warning: oklch(78.19% 0.1631 69.51);
+    --warning-foreground: oklch(21.03% 0.0059 69.51);
+    --danger: oklch(65.32% 0.2398 22.91);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Lavender theme */
+  [data-design-theme="lavender"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.015 305.49);
+    --border: oklch(90% 0.015 305.49);
+    --default: oklch(94% 0.015 305.49);
+    --default-foreground: oklch(21.03% 0.0059 305.49);
+    --field-background: oklch(100% 0.0075 305.49);
+    --field-border: oklch(90% 0.015 305.49);
+    --field-foreground: oklch(21.03% 0.015 305.49);
+    --field-placeholder: oklch(55.17% 0.03 305.49);
+    --foreground: oklch(21.03% 0.015 305.49);
+    --link: oklch(21.03% 0.015 305.49);
+    --muted: oklch(55.17% 0.03 305.49);
+    --overlay: oklch(100% 0.0045 305.49);
+    --overlay-foreground: oklch(21.03% 0.015 305.49);
+    --scrollbar: oklch(87.1% 0.015 305.49);
+    --segment: oklch(100% 0.015 305.49);
+    --segment-foreground: oklch(21.03% 0.015 305.49);
+    --separator: oklch(92% 0.015 305.49);
+    --surface: oklch(100% 0.0075 305.49);
+    --surface-foreground: oklch(21.03% 0.015 305.49);
+    --surface-secondary: oklch(95.24% 0.0225 305.49);
+    --surface-secondary-foreground: oklch(21.03% 0.015 305.49);
+    --surface-tertiary: oklch(93.73% 0.0225 305.49);
+    --surface-tertiary-foreground: oklch(21.03% 0.015 305.49);
+    --accent: oklch(72.17% 0.1768 305.49);
+    --accent-foreground: oklch(15% 0.03 305.49);
+    --focus: oklch(72.17% 0.1768 305.49);
+    --success: oklch(73.29% 0.1992 157.03);
+    --success-foreground: oklch(21.03% 0.0059 157.03);
+    --warning: oklch(78.19% 0.1631 78.52);
+    --warning-foreground: oklch(21.03% 0.0059 78.52);
+    --danger: oklch(65.32% 0.2398 31.93);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="lavender"].dark,
+  [data-design-theme="lavender"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.015 305.49);
+    --border: oklch(28% 0.015 305.49);
+    --default: oklch(27.4% 0.015 305.49);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.03 305.49);
+    --field-border: oklch(28% 0.015 305.49);
+    --field-foreground: oklch(99.11% 0.015 305.49);
+    --field-placeholder: oklch(70.5% 0.03 305.49);
+    --foreground: oklch(99.11% 0.015 305.49);
+    --link: oklch(99.11% 0.015 305.49);
+    --muted: oklch(70.5% 0.03 305.49);
+    --overlay: oklch(21.03% 0.03 305.49);
+    --overlay-foreground: oklch(99.11% 0.015 305.49);
+    --scrollbar: oklch(70.5% 0.015 305.49);
+    --segment: oklch(39.64% 0.015 305.49);
+    --segment-foreground: oklch(99.11% 0.015 305.49);
+    --separator: oklch(25% 0.015 305.49);
+    --surface: oklch(21.03% 0.03 305.49);
+    --surface-foreground: oklch(99.11% 0.015 305.49);
+    --surface-secondary: oklch(25.7% 0.0225 305.49);
+    --surface-secondary-foreground: oklch(99.11% 0.015 305.49);
+    --surface-tertiary: oklch(27.21% 0.0225 305.49);
+    --surface-tertiary-foreground: oklch(99.11% 0.015 305.49);
+    --accent: oklch(72.17% 0.1768 305.49);
+    --accent-foreground: oklch(15% 0.03 305.49);
+    --focus: oklch(72.17% 0.1768 305.49);
+    --success: oklch(73.29% 0.1992 157.03);
+    --success-foreground: oklch(21.03% 0.0059 157.03);
+    --warning: oklch(78.19% 0.1631 78.52);
+    --warning-foreground: oklch(21.03% 0.0059 78.52);
+    --danger: oklch(65.32% 0.2398 31.93);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Mint theme */
+  [data-design-theme="mint"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.015 154.48);
+    --border: oklch(90% 0.015 154.48);
+    --default: oklch(94% 0.015 154.48);
+    --default-foreground: oklch(21.03% 0.0059 154.48);
+    --field-background: oklch(100% 0.0075 154.48);
+    --field-border: oklch(90% 0.015 154.48);
+    --field-foreground: oklch(21.03% 0.015 154.48);
+    --field-placeholder: oklch(55.17% 0.03 154.48);
+    --foreground: oklch(21.03% 0.015 154.48);
+    --link: oklch(21.03% 0.015 154.48);
+    --muted: oklch(55.17% 0.03 154.48);
+    --overlay: oklch(100% 0.0045 154.48);
+    --overlay-foreground: oklch(21.03% 0.015 154.48);
+    --scrollbar: oklch(87.1% 0.015 154.48);
+    --segment: oklch(100% 0.015 154.48);
+    --segment-foreground: oklch(21.03% 0.015 154.48);
+    --separator: oklch(92% 0.015 154.48);
+    --surface: oklch(100% 0.0075 154.48);
+    --surface-foreground: oklch(21.03% 0.015 154.48);
+    --surface-secondary: oklch(95.24% 0.0225 154.48);
+    --surface-secondary-foreground: oklch(21.03% 0.015 154.48);
+    --surface-tertiary: oklch(93.73% 0.0225 154.48);
+    --surface-tertiary-foreground: oklch(21.03% 0.015 154.48);
+    --accent: oklch(87.12% 0.1363 154.48);
+    --accent-foreground: oklch(15% 0.0273 154.48);
+    --focus: oklch(87.12% 0.1363 154.48);
+    --success: oklch(73.29% 0.1992 138.91);
+    --success-foreground: oklch(21.03% 0.0059 138.91);
+    --warning: oklch(78.19% 0.1631 60.4);
+    --warning-foreground: oklch(21.03% 0.0059 60.4);
+    --danger: oklch(65.32% 0.2398 13.81);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="mint"].dark,
+  [data-design-theme="mint"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.015 154.48);
+    --border: oklch(28% 0.015 154.48);
+    --default: oklch(27.4% 0.015 154.48);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.03 154.48);
+    --field-border: oklch(28% 0.015 154.48);
+    --field-foreground: oklch(99.11% 0.015 154.48);
+    --field-placeholder: oklch(70.5% 0.03 154.48);
+    --foreground: oklch(99.11% 0.015 154.48);
+    --link: oklch(99.11% 0.015 154.48);
+    --muted: oklch(70.5% 0.03 154.48);
+    --overlay: oklch(21.03% 0.03 154.48);
+    --overlay-foreground: oklch(99.11% 0.015 154.48);
+    --scrollbar: oklch(70.5% 0.015 154.48);
+    --segment: oklch(39.64% 0.015 154.48);
+    --segment-foreground: oklch(99.11% 0.015 154.48);
+    --separator: oklch(25% 0.015 154.48);
+    --surface: oklch(21.03% 0.03 154.48);
+    --surface-foreground: oklch(99.11% 0.015 154.48);
+    --surface-secondary: oklch(25.7% 0.0225 154.48);
+    --surface-secondary-foreground: oklch(99.11% 0.015 154.48);
+    --surface-tertiary: oklch(27.21% 0.0225 154.48);
+    --surface-tertiary-foreground: oklch(99.11% 0.015 154.48);
+    --accent: oklch(87.12% 0.1363 154.48);
+    --accent-foreground: oklch(15% 0.0273 154.48);
+    --focus: oklch(87.12% 0.1363 154.48);
+    --success: oklch(73.29% 0.1992 138.91);
+    --success-foreground: oklch(21.03% 0.0059 138.91);
+    --warning: oklch(78.19% 0.1631 60.4);
+    --warning-foreground: oklch(21.03% 0.0059 60.4);
+    --danger: oklch(65.32% 0.2398 13.81);
+    --danger-foreground: oklch(99.11% 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Netflix theme */
+  [data-design-theme="netflix"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.008 27.98);
+    --border: oklch(90% 0.008 27.98);
+    --default: oklch(94% 0.008 27.98);
+    --default-foreground: oklch(21.03% 0.0059 27.98);
+    --field-background: oklch(100% 0.004 27.98);
+    --field-border: oklch(90% 0.008 27.98);
+    --field-foreground: oklch(21.03% 0.008 27.98);
+    --field-placeholder: oklch(55.17% 0.016 27.98);
+    --foreground: oklch(21.03% 0.008 27.98);
+    --link: oklch(21.03% 0.008 27.98);
+    --muted: oklch(55.17% 0.016 27.98);
+    --overlay: oklch(100% 0.0024 27.98);
+    --overlay-foreground: oklch(21.03% 0.008 27.98);
+    --scrollbar: oklch(87.1% 0.008 27.98);
+    --segment: oklch(100% 0.008 27.98);
+    --segment-foreground: oklch(21.03% 0.008 27.98);
+    --separator: oklch(92% 0.008 27.98);
+    --surface: oklch(100% 0.004 27.98);
+    --surface-foreground: oklch(21.03% 0.008 27.98);
+    --surface-secondary: oklch(95.24% 0.012 27.98);
+    --surface-secondary-foreground: oklch(21.03% 0.008 27.98);
+    --surface-tertiary: oklch(93.73% 0.012 27.98);
+    --surface-tertiary-foreground: oklch(21.03% 0.008 27.98);
+    --accent: oklch(58.14% 0.2348 27.98);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(58.14% 0.2348 27.98);
+    --success: oklch(0.5148 0.1337 146.82);
+    --success-foreground: oklch(99.11% 0 0);
+    --warning: oklch(0.561 0.116571 78.9352);
+    --warning-foreground: oklch(99.11% 0 0);
+    --danger: oklch(0.4823 0.1938 27.64);
+    --danger-foreground: oklch(99.11% 0 0);
+    --radius: 0.125rem;
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="netflix"].dark,
+  [data-design-theme="netflix"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.008 27.98);
+    --border: oklch(28% 0.008 27.98);
+    --default: oklch(27.4% 0.008 27.98);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.016 27.98);
+    --field-border: oklch(28% 0.008 27.98);
+    --field-foreground: oklch(99.11% 0.008 27.98);
+    --field-placeholder: oklch(70.5% 0.016 27.98);
+    --foreground: oklch(99.11% 0.008 27.98);
+    --link: oklch(99.11% 0.008 27.98);
+    --muted: oklch(70.5% 0.016 27.98);
+    --overlay: oklch(21.03% 0.016 27.98);
+    --overlay-foreground: oklch(99.11% 0.008 27.98);
+    --scrollbar: oklch(70.5% 0.008 27.98);
+    --segment: oklch(39.64% 0.008 27.98);
+    --segment-foreground: oklch(99.11% 0.008 27.98);
+    --separator: oklch(25% 0.008 27.98);
+    --surface: oklch(21.03% 0.016 27.98);
+    --surface-foreground: oklch(99.11% 0.008 27.98);
+    --surface-secondary: oklch(25.7% 0.012 27.98);
+    --surface-secondary-foreground: oklch(99.11% 0.008 27.98);
+    --surface-tertiary: oklch(27.21% 0.012 27.98);
+    --surface-tertiary-foreground: oklch(99.11% 0.008 27.98);
+    --accent: oklch(58.14% 0.2348 27.98);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(58.14% 0.2348 27.98);
+    --success: oklch(0.7677 0.1899 148.1);
+    --success-foreground: oklch(15% 0.05 148.1);
+    --warning: oklch(0.8239 0.153 74.6);
+    --warning-foreground: oklch(15% 0.0459 74.6);
+    --danger: oklch(0.4964 0.1994 28.56);
+    --danger-foreground: oklch(99.11% 0 0);
+    --radius: 0.125rem;
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Uber theme */
+  [data-design-theme="uber"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.005 0);
+    --border: oklch(90% 0.005 0);
+    --default: oklch(94% 0.005 0);
+    --default-foreground: oklch(21.03% 0.0059 0);
+    --field-background: oklch(100% 0.0025 0);
+    --field-border: oklch(90% 0.005 0);
+    --field-foreground: oklch(21.03% 0.005 0);
+    --field-placeholder: oklch(55.17% 0.01 0);
+    --foreground: oklch(21.03% 0.005 0);
+    --link: oklch(21.03% 0.005 0);
+    --muted: oklch(55.17% 0.01 0);
+    --overlay: oklch(100% 0.0015 0);
+    --overlay-foreground: oklch(21.03% 0.005 0);
+    --scrollbar: oklch(87.1% 0.005 0);
+    --segment: oklch(100% 0.005 0);
+    --segment-foreground: oklch(21.03% 0.005 0);
+    --separator: oklch(92% 0.005 0);
+    --surface: oklch(100% 0.0025 0);
+    --surface-foreground: oklch(21.03% 0.005 0);
+    --surface-secondary: oklch(95.24% 0.0075 0);
+    --surface-secondary-foreground: oklch(21.03% 0.005 0);
+    --surface-tertiary: oklch(93.73% 0.0075 0);
+    --surface-tertiary-foreground: oklch(21.03% 0.005 0);
+    --accent: oklch(0% 0 0);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(0% 0 0);
+    --success: oklch(0.6277 0.1604 153.06);
+    --success-foreground: oklch(99.11% 0 0);
+    --warning: oklch(0.8446 0.1525 80.6);
+    --warning-foreground: oklch(15% 0.0457 80.6);
+    --danger: oklch(0.573 0.2249 21.97);
+    --danger-foreground: oklch(99.11% 0 0);
+    --radius: 0.25rem;
+    --field-radius: 0.25rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="uber"].dark,
+  [data-design-theme="uber"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.005 0);
+    --border: oklch(28% 0.005 0);
+    --default: oklch(27.4% 0.005 0);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.01 0);
+    --field-border: oklch(28% 0.005 0);
+    --field-foreground: oklch(99.11% 0.005 0);
+    --field-placeholder: oklch(70.5% 0.01 0);
+    --foreground: oklch(99.11% 0.005 0);
+    --link: oklch(99.11% 0.005 0);
+    --muted: oklch(70.5% 0.01 0);
+    --overlay: oklch(21.03% 0.01 0);
+    --overlay-foreground: oklch(99.11% 0.005 0);
+    --scrollbar: oklch(70.5% 0.005 0);
+    --segment: oklch(39.64% 0.005 0);
+    --segment-foreground: oklch(99.11% 0.005 0);
+    --separator: oklch(25% 0.005 0);
+    --surface: oklch(21.03% 0.01 0);
+    --surface-foreground: oklch(99.11% 0.005 0);
+    --surface-secondary: oklch(25.7% 0.0075 0);
+    --surface-secondary-foreground: oklch(99.11% 0.005 0);
+    --surface-tertiary: oklch(27.21% 0.0075 0);
+    --surface-tertiary-foreground: oklch(99.11% 0.005 0);
+    --accent: oklch(98.48% 0 0);
+    --accent-foreground: oklch(15% 0 0);
+    --focus: oklch(98.48% 0 0);
+    --success: oklch(0.6514 0.1321 156.22);
+    --success-foreground: oklch(15% 0.0396 156.22);
+    --warning: oklch(0.8803 0.1348 86.06);
+    --warning-foreground: oklch(15% 0.0404 86.06);
+    --danger: oklch(0.7044 0.1872 23.19);
+    --danger-foreground: oklch(15% 0.05 23.19);
+    --radius: 0.25rem;
+    --field-radius: 0.25rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Spotify theme */
+  [data-design-theme="spotify"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.002 148.69);
+    --border: oklch(90% 0.002 148.69);
+    --default: oklch(94% 0.002 148.69);
+    --default-foreground: oklch(21.03% 0.0059 148.69);
+    --field-background: oklch(100% 0.001 148.69);
+    --field-border: oklch(90% 0.002 148.69);
+    --field-foreground: oklch(21.03% 0.002 148.69);
+    --field-placeholder: oklch(55.17% 0.004 148.69);
+    --foreground: oklch(21.03% 0.002 148.69);
+    --link: oklch(21.03% 0.002 148.69);
+    --muted: oklch(55.17% 0.004 148.69);
+    --overlay: oklch(100% 0.0006 148.69);
+    --overlay-foreground: oklch(21.03% 0.002 148.69);
+    --scrollbar: oklch(87.1% 0.002 148.69);
+    --segment: oklch(100% 0.002 148.69);
+    --segment-foreground: oklch(21.03% 0.002 148.69);
+    --separator: oklch(92% 0.002 148.69);
+    --surface: oklch(100% 0.001 148.69);
+    --surface-foreground: oklch(21.03% 0.002 148.69);
+    --surface-secondary: oklch(95.24% 0.003 148.69);
+    --surface-secondary-foreground: oklch(21.03% 0.002 148.69);
+    --surface-tertiary: oklch(93.73% 0.003 148.69);
+    --surface-tertiary-foreground: oklch(21.03% 0.002 148.69);
+    --accent: oklch(76.97% 0.2123 148.69);
+    --accent-foreground: oklch(15% 0.03 148.69);
+    --focus: oklch(76.97% 0.2123 148.69);
+    --success: oklch(0.6072 0.1647 149.02);
+    --success-foreground: oklch(99.11% 0 0);
+    --warning: oklch(0.6972 0.1687 54.22);
+    --warning-foreground: oklch(15% 0.05 54.22);
+    --danger: oklch(0.5509 0.2166 25.29);
+    --danger-foreground: oklch(99.11% 0 0);
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="spotify"].dark,
+  [data-design-theme="spotify"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.002 148.69);
+    --border: oklch(28% 0.002 148.69);
+    --default: oklch(27.4% 0.002 148.69);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.004 148.69);
+    --field-border: oklch(28% 0.002 148.69);
+    --field-foreground: oklch(99.11% 0.002 148.69);
+    --field-placeholder: oklch(70.5% 0.004 148.69);
+    --foreground: oklch(99.11% 0.002 148.69);
+    --link: oklch(99.11% 0.002 148.69);
+    --muted: oklch(70.5% 0.004 148.69);
+    --overlay: oklch(21.03% 0.004 148.69);
+    --overlay-foreground: oklch(99.11% 0.002 148.69);
+    --scrollbar: oklch(70.5% 0.002 148.69);
+    --segment: oklch(39.64% 0.002 148.69);
+    --segment-foreground: oklch(99.11% 0.002 148.69);
+    --separator: oklch(25% 0.002 148.69);
+    --surface: oklch(21.03% 0.004 148.69);
+    --surface-foreground: oklch(99.11% 0.002 148.69);
+    --surface-secondary: oklch(25.7% 0.003 148.69);
+    --surface-secondary-foreground: oklch(99.11% 0.002 148.69);
+    --surface-tertiary: oklch(27.21% 0.003 148.69);
+    --surface-tertiary-foreground: oklch(99.11% 0.002 148.69);
+    --accent: oklch(76.97% 0.2123 148.69);
+    --accent-foreground: oklch(15% 0.03 148.69);
+    --focus: oklch(76.97% 0.2123 148.69);
+    --success: oklch(0.7697 0.2124 148.67);
+    --success-foreground: oklch(15% 0.05 148.67);
+    --warning: oklch(0.7921 0.1626 67.42);
+    --warning-foreground: oklch(15% 0.0488 67.42);
+    --danger: oklch(0.5931 0.2338 25.42);
+    --danger-foreground: oklch(99.11% 0 0);
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Coinbase theme */
+  [data-design-theme="coinbase"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.002 277.63);
+    --border: oklch(90% 0.002 277.63);
+    --default: oklch(94% 0.002 277.63);
+    --default-foreground: oklch(21.03% 0.0059 277.63);
+    --field-background: oklch(100% 0.001 277.63);
+    --field-border: oklch(90% 0.002 277.63);
+    --field-foreground: oklch(21.03% 0.002 277.63);
+    --field-placeholder: oklch(55.17% 0.004 277.63);
+    --foreground: oklch(21.03% 0.002 277.63);
+    --link: oklch(21.03% 0.002 277.63);
+    --muted: oklch(55.17% 0.004 277.63);
+    --overlay: oklch(100% 0.0006 277.63);
+    --overlay-foreground: oklch(21.03% 0.002 277.63);
+    --scrollbar: oklch(87.1% 0.002 277.63);
+    --segment: oklch(100% 0.002 277.63);
+    --segment-foreground: oklch(21.03% 0.002 277.63);
+    --separator: oklch(92% 0.002 277.63);
+    --surface: oklch(100% 0.001 277.63);
+    --surface-foreground: oklch(21.03% 0.002 277.63);
+    --surface-secondary: oklch(95.24% 0.003 277.63);
+    --surface-secondary-foreground: oklch(21.03% 0.002 277.63);
+    --surface-tertiary: oklch(93.73% 0.003 277.63);
+    --surface-tertiary-foreground: oklch(21.03% 0.002 277.63);
+    --accent: oklch(50.31% 0.2262 277.63);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(50.31% 0.2262 277.63);
+    --success: oklch(0.5438 0.1268 157.17);
+    --success-foreground: oklch(99.11% 0 0);
+    --warning: oklch(0.8095 0.1119 61.69);
+    --warning-foreground: oklch(15% 0.0336 61.69);
+    --danger: oklch(0.5507 0.2062 24);
+    --danger-foreground: oklch(99.11% 0 0);
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="coinbase"].dark,
+  [data-design-theme="coinbase"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.002 277.63);
+    --border: oklch(28% 0.002 277.63);
+    --default: oklch(27.4% 0.002 277.63);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.004 277.63);
+    --field-border: oklch(28% 0.002 277.63);
+    --field-foreground: oklch(99.11% 0.002 277.63);
+    --field-placeholder: oklch(70.5% 0.004 277.63);
+    --foreground: oklch(99.11% 0.002 277.63);
+    --link: oklch(99.11% 0.002 277.63);
+    --muted: oklch(70.5% 0.004 277.63);
+    --overlay: oklch(21.03% 0.004 277.63);
+    --overlay-foreground: oklch(99.11% 0.002 277.63);
+    --scrollbar: oklch(70.5% 0.002 277.63);
+    --segment: oklch(39.64% 0.002 277.63);
+    --segment-foreground: oklch(99.11% 0.002 277.63);
+    --separator: oklch(25% 0.002 277.63);
+    --surface: oklch(21.03% 0.004 277.63);
+    --surface-foreground: oklch(99.11% 0.002 277.63);
+    --surface-secondary: oklch(25.7% 0.003 277.63);
+    --surface-secondary-foreground: oklch(99.11% 0.002 277.63);
+    --surface-tertiary: oklch(27.21% 0.003 277.63);
+    --surface-tertiary-foreground: oklch(99.11% 0.002 277.63);
+    --accent: oklch(50.31% 0.2262 277.63);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(50.31% 0.2262 277.63);
+    --success: oklch(0.7574 0.180554 156.931);
+    --success-foreground: oklch(15% 0.05 156.93);
+    --warning: oklch(0.8095 0.1119 61.69);
+    --warning-foreground: oklch(15% 0.0336 61.69);
+    --danger: oklch(0.6545 0.2145 22.31);
+    --danger-foreground: oklch(15% 0.05 22.31);
+    --field-radius: 0.125rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Airbnb theme */
+  [data-design-theme="airbnb"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0 22.37);
+    --border: oklch(90% 0 22.37);
+    --default: oklch(94% 0 22.37);
+    --default-foreground: oklch(21.03% 0.0059 22.37);
+    --field-background: oklch(100% 0 22.37);
+    --field-border: oklch(90% 0 22.37);
+    --field-foreground: oklch(21.03% 0 22.37);
+    --field-placeholder: oklch(55.17% 0 22.37);
+    --foreground: oklch(21.03% 0 22.37);
+    --link: oklch(21.03% 0 22.37);
+    --muted: oklch(55.17% 0 22.37);
+    --overlay: oklch(100% 0 22.37);
+    --overlay-foreground: oklch(21.03% 0 22.37);
+    --scrollbar: oklch(87.1% 0 22.37);
+    --segment: oklch(100% 0 22.37);
+    --segment-foreground: oklch(21.03% 0 22.37);
+    --separator: oklch(92% 0 22.37);
+    --surface: oklch(100% 0 22.37);
+    --surface-foreground: oklch(21.03% 0 22.37);
+    --surface-secondary: oklch(95.24% 0 22.37);
+    --surface-secondary-foreground: oklch(21.03% 0 22.37);
+    --surface-tertiary: oklch(93.73% 0 22.37);
+    --surface-tertiary-foreground: oklch(21.03% 0 22.37);
+    --accent: oklch(68.92% 0.2004 22.37);
+    --accent-foreground: oklch(0.9911 0 0);
+    --focus: oklch(68.92% 0.2004 22.37);
+    --success: oklch(0.5573 0.0947 199.48);
+    --success-foreground: oklch(0.9911 0 0);
+    --warning: oklch(0.6904 0.1972 38.75);
+    --warning-foreground: oklch(0.9911 0 0);
+    --danger: oklch(0.5392 0.1816 33.72);
+    --danger-foreground: oklch(0.9911 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="airbnb"].dark,
+  [data-design-theme="airbnb"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0 22.37);
+    --border: oklch(28% 0 22.37);
+    --default: oklch(27.4% 0 22.37);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0 22.37);
+    --field-border: oklch(28% 0 22.37);
+    --field-foreground: oklch(99.11% 0 22.37);
+    --field-placeholder: oklch(70.5% 0 22.37);
+    --foreground: oklch(99.11% 0 22.37);
+    --link: oklch(99.11% 0 22.37);
+    --muted: oklch(70.5% 0 22.37);
+    --overlay: oklch(21.03% 0 22.37);
+    --overlay-foreground: oklch(99.11% 0 22.37);
+    --scrollbar: oklch(70.5% 0 22.37);
+    --segment: oklch(39.64% 0 22.37);
+    --segment-foreground: oklch(99.11% 0 22.37);
+    --separator: oklch(25% 0 22.37);
+    --surface: oklch(21.03% 0 22.37);
+    --surface-foreground: oklch(99.11% 0 22.37);
+    --surface-secondary: oklch(25.7% 0 22.37);
+    --surface-secondary-foreground: oklch(99.11% 0 22.37);
+    --surface-tertiary: oklch(27.21% 0 22.37);
+    --surface-tertiary-foreground: oklch(99.11% 0 22.37);
+    --accent: oklch(68.92% 0.2004 22.37);
+    --accent-foreground: oklch(0.9911 0 0);
+    --focus: oklch(68.92% 0.2004 22.37);
+    --success: oklch(0.652 0.114864 185.0749);
+    --success-foreground: oklch(0.9911 0 0);
+    --warning: oklch(0.8197 0.170602 78.4658);
+    --warning-foreground: oklch(15% 0.05 78.47);
+    --danger: oklch(0.5392 0.1816 33.72);
+    --danger-foreground: oklch(0.9911 0 0);
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Discord theme */
+  [data-design-theme="discord"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.01 273.85);
+    --border: oklch(90% 0.01 273.85);
+    --default: oklch(94% 0.01 273.85);
+    --default-foreground: oklch(21.03% 0.0059 273.85);
+    --field-background: oklch(100% 0.005 273.85);
+    --field-border: oklch(90% 0.01 273.85);
+    --field-foreground: oklch(21.03% 0.01 273.85);
+    --field-placeholder: oklch(55.17% 0.02 273.85);
+    --foreground: oklch(21.03% 0.01 273.85);
+    --link: oklch(21.03% 0.01 273.85);
+    --muted: oklch(55.17% 0.02 273.85);
+    --overlay: oklch(100% 0.003 273.85);
+    --overlay-foreground: oklch(21.03% 0.01 273.85);
+    --scrollbar: oklch(87.1% 0.01 273.85);
+    --segment: oklch(100% 0.01 273.85);
+    --segment-foreground: oklch(21.03% 0.01 273.85);
+    --separator: oklch(92% 0.01 273.85);
+    --surface: oklch(100% 0.005 273.85);
+    --surface-foreground: oklch(21.03% 0.01 273.85);
+    --surface-secondary: oklch(95.24% 0.015 273.85);
+    --surface-secondary-foreground: oklch(21.03% 0.01 273.85);
+    --surface-tertiary: oklch(93.73% 0.015 273.85);
+    --surface-tertiary-foreground: oklch(21.03% 0.01 273.85);
+    --accent: oklch(57.74% 0.2092 273.85);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(57.74% 0.2092 273.85);
+    --success: oklch(0.532 0.1238 151.57);
+    --success-foreground: oklch(99.11% 0 0);
+    --warning: oklch(0.9218 0.1571 99.87);
+    --warning-foreground: oklch(15% 0.0471 99.87);
+    --danger: oklch(0.5884 0.1993 24.39);
+    --danger-foreground: oklch(99.11% 0 0);
+    --radius: 0.25rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="discord"].dark,
+  [data-design-theme="discord"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.01 273.85);
+    --border: oklch(28% 0.01 273.85);
+    --default: oklch(27.4% 0.01 273.85);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.02 273.85);
+    --field-border: oklch(28% 0.01 273.85);
+    --field-foreground: oklch(99.11% 0.01 273.85);
+    --field-placeholder: oklch(70.5% 0.02 273.85);
+    --foreground: oklch(99.11% 0.01 273.85);
+    --link: oklch(99.11% 0.01 273.85);
+    --muted: oklch(70.5% 0.02 273.85);
+    --overlay: oklch(21.03% 0.02 273.85);
+    --overlay-foreground: oklch(99.11% 0.01 273.85);
+    --scrollbar: oklch(70.5% 0.01 273.85);
+    --segment: oklch(39.64% 0.01 273.85);
+    --segment-foreground: oklch(99.11% 0.01 273.85);
+    --separator: oklch(25% 0.01 273.85);
+    --surface: oklch(21.03% 0.02 273.85);
+    --surface-foreground: oklch(99.11% 0.01 273.85);
+    --surface-secondary: oklch(25.7% 0.015 273.85);
+    --surface-secondary-foreground: oklch(99.11% 0.01 273.85);
+    --surface-tertiary: oklch(27.21% 0.015 273.85);
+    --surface-tertiary-foreground: oklch(99.11% 0.01 273.85);
+    --accent: oklch(57.74% 0.2092 273.85);
+    --accent-foreground: oklch(99.11% 0 0);
+    --focus: oklch(57.74% 0.2092 273.85);
+    --success: oklch(0.8548 0.1967 150.16);
+    --success-foreground: oklch(15% 0.05 150.16);
+    --warning: oklch(0.9218 0.1571 99.87);
+    --warning-foreground: oklch(15% 0.0471 99.87);
+    --danger: oklch(0.6318 0.2075 24.57);
+    --danger-foreground: oklch(99.11% 0 0);
+    --radius: 0.25rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  /* Rabbit theme */
+  [data-design-theme="rabbit"]:not(.dark):not([data-theme="dark"]) {
+    --background: oklch(97.02% 0.01 43.48);
+    --border: oklch(90% 0.01 43.48);
+    --default: oklch(94% 0.01 43.48);
+    --default-foreground: oklch(21.03% 0.0059 43.48);
+    --field-background: oklch(100% 0.005 43.48);
+    --field-border: oklch(90% 0.01 43.48);
+    --field-foreground: oklch(21.03% 0.01 43.48);
+    --field-placeholder: oklch(55.17% 0.02 43.48);
+    --foreground: oklch(21.03% 0.01 43.48);
+    --link: oklch(21.03% 0.01 43.48);
+    --muted: oklch(55.17% 0.02 43.48);
+    --overlay: oklch(100% 0.003 43.48);
+    --overlay-foreground: oklch(21.03% 0.01 43.48);
+    --scrollbar: oklch(87.1% 0.01 43.48);
+    --segment: oklch(100% 0.01 43.48);
+    --segment-foreground: oklch(21.03% 0.01 43.48);
+    --separator: oklch(92% 0.01 43.48);
+    --surface: oklch(100% 0.005 43.48);
+    --surface-foreground: oklch(21.03% 0.01 43.48);
+    --surface-secondary: oklch(95.24% 0.015 43.48);
+    --surface-secondary-foreground: oklch(21.03% 0.01 43.48);
+    --surface-tertiary: oklch(93.73% 0.015 43.48);
+    --surface-tertiary-foreground: oklch(21.03% 0.01 43.48);
+    --accent: oklch(69.58% 0.2042 43.48);
+    --accent-foreground: oklch(15% 0.03 43.48);
+    --focus: oklch(69.58% 0.2042 43.48);
+    --success: oklch(0.7113 0.2043 140.81);
+    --success-foreground: oklch(15% 0.05 140.81);
+    --warning: oklch(78.19% 0.1616 47.08);
+    --warning-foreground: oklch(21.03% 0.0059 47.08);
+    --danger: oklch(0.6291 0.2565 29.09);
+    --danger-foreground: oklch(99.11% 0 0);
+    --field-radius: 1rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+
+  [data-design-theme="rabbit"].dark,
+  [data-design-theme="rabbit"][data-theme="dark"] {
+    color-scheme: dark;
+    --background: oklch(12% 0.01 43.48);
+    --border: oklch(28% 0.01 43.48);
+    --default: oklch(27.4% 0.01 43.48);
+    --default-foreground: oklch(99.11% 0 0);
+    --field-background: oklch(21.03% 0.02 43.48);
+    --field-border: oklch(28% 0.01 43.48);
+    --field-foreground: oklch(99.11% 0.01 43.48);
+    --field-placeholder: oklch(70.5% 0.02 43.48);
+    --foreground: oklch(99.11% 0.01 43.48);
+    --link: oklch(99.11% 0.01 43.48);
+    --muted: oklch(70.5% 0.02 43.48);
+    --overlay: oklch(21.03% 0.02 43.48);
+    --overlay-foreground: oklch(99.11% 0.01 43.48);
+    --scrollbar: oklch(70.5% 0.01 43.48);
+    --segment: oklch(39.64% 0.01 43.48);
+    --segment-foreground: oklch(99.11% 0.01 43.48);
+    --separator: oklch(25% 0.01 43.48);
+    --surface: oklch(21.03% 0.02 43.48);
+    --surface-foreground: oklch(99.11% 0.01 43.48);
+    --surface-secondary: oklch(25.7% 0.015 43.48);
+    --surface-secondary-foreground: oklch(99.11% 0.01 43.48);
+    --surface-tertiary: oklch(27.21% 0.015 43.48);
+    --surface-tertiary-foreground: oklch(99.11% 0.01 43.48);
+    --accent: oklch(69.58% 0.2042 43.48);
+    --accent-foreground: oklch(15% 0.03 43.48);
+    --focus: oklch(69.58% 0.2042 43.48);
+    --success: oklch(0.7113 0.2043 140.81);
+    --success-foreground: oklch(15% 0.05 140.81);
+    --warning: oklch(78.19% 0.1616 47.08);
+    --warning-foreground: oklch(21.03% 0.0059 47.08);
+    --danger: oklch(0.6291 0.2565 29.09);
+    --danger-foreground: oklch(99.11% 0 0);
+    --field-radius: 1rem;
+    --chart-1: oklch(from var(--accent) calc(l - 0.24) c h);
+    --chart-2: oklch(from var(--accent) calc(l - 0.12) c h);
+    --chart-3: var(--accent);
+    --chart-4: oklch(from var(--accent) calc(l + 0.12) c h);
+    --chart-5: oklch(from var(--accent) calc(l + 0.24) c h);
+  }
+}
diff --git a/apps/docs/src/utils/cn.ts b/apps/docs/src/utils/cn.ts
new file mode 100644
index 0000000..7eefc28
--- /dev/null
+++ b/apps/docs/src/utils/cn.ts
@@ -0,0 +1,13 @@
+import type {ClassValue} from "clsx";
+
+import clsx from "clsx";
+import {twMerge} from "tailwind-merge";
+
+/**
+ * We need to extend the tailwind merge to include HeroUI's custom classes.
+ *
+ * So we can use classes like `text-small` or `text-default-500` and override them.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
diff --git a/apps/docs/src/utils/compose-tw-render.ts b/apps/docs/src/utils/compose-tw-render.ts
new file mode 100644
index 0000000..d81a649
--- /dev/null
+++ b/apps/docs/src/utils/compose-tw-render.ts
@@ -0,0 +1,9 @@
+import {composeRenderProps} from "react-aria-components";
+import {twMerge} from "tailwind-merge";
+
+export function composeTailwindRenderProps<T>(
+  className: string | ((v: T) => string) | undefined,
+  tw: string,
+): string | ((v: T) => string) {
+  return composeRenderProps(className, (className) => twMerge(tw, className));
+}
diff --git a/apps/docs/src/utils/constants.ts b/apps/docs/src/utils/constants.ts
new file mode 100644
index 0000000..bdaf8dd
--- /dev/null
+++ b/apps/docs/src/utils/constants.ts
@@ -0,0 +1,50 @@
+import {__DEV__, __IS_PRE_RELEASE__, __PREVIEW__} from "@/utils/env";
+
+export const GITHUB_URL = "https://github.com";
+
+export const GITHUB_API_URL = "https://api.github.com";
+
+export const RAW_GITHUB_URL = "https://raw.githubusercontent.com";
+
+export const REPO_NAME = "heroui-inc/heroui";
+
+export const REPO_NAME_NATIVE = "heroui-inc/heroui-native";
+
+export const ISSUE_REPORT_URL = `${GITHUB_URL}/${REPO_NAME}/issues/new?assignees=&labels=bug&template=bug_report.yml&title=%5BBUG%5D+-+`;
+
+export const COMPONENT_PATH =
+  __IS_PRE_RELEASE__ || __PREVIEW__
+    ? `${GITHUB_URL}/${REPO_NAME}/tree/v3/packages/react/src/components`
+    : `${GITHUB_URL}/${REPO_NAME}/tree/main/packages/react/src/components`;
+
+export const COMPONENT_PATH_NATIVE = `${GITHUB_URL}/${REPO_NAME_NATIVE}/tree/main/src/components`;
+
+export const DOCS_CONTENT_PATH =
+  __IS_PRE_RELEASE__ || __PREVIEW__
+    ? `${GITHUB_URL}/${REPO_NAME}/blob/v3/apps/docs/content/docs`
+    : `${GITHUB_URL}/${REPO_NAME}/blob/main/apps/docs/content/docs`;
+
+export const RAW_DOCS_CONTENT_PATH =
+  __IS_PRE_RELEASE__ || __PREVIEW__
+    ? `${RAW_GITHUB_URL}/${REPO_NAME}/refs/heads/v3/apps/docs/content/docs`
+    : `${RAW_GITHUB_URL}/${REPO_NAME}/refs/heads/main/apps/docs/content/docs`;
+
+export const COMPONENT_STYLES_PATH =
+  __IS_PRE_RELEASE__ || __PREVIEW__
+    ? `${GITHUB_URL}/${REPO_NAME}/tree/v3/packages/styles/components`
+    : `${GITHUB_URL}/${REPO_NAME}/tree/main/packages/styles/components`;
+
+export const COMPONENT_STYLES_PATH_NATIVE = `${GITHUB_URL}/${REPO_NAME_NATIVE}/blob/main/src/components`;
+
+export const THEMES_PATH =
+  __IS_PRE_RELEASE__ || __PREVIEW__
+    ? `${GITHUB_URL}/${REPO_NAME}/tree/v3/packages/styles/themes`
+    : `${GITHUB_URL}/${REPO_NAME}/tree/main/packages/styles/themes`;
+
+export const STORYBOOK_URL = __DEV__
+  ? "http://localhost:6006"
+  : __IS_PRE_RELEASE__ || __PREVIEW__
+    ? "https://storybook-v3.heroui.com"
+    : "https://storybook.heroui.com";
+
+export const CDN_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com";
diff --git a/apps/docs/src/utils/design-theme.ts b/apps/docs/src/utils/design-theme.ts
new file mode 100644
index 0000000..2bf128f
--- /dev/null
+++ b/apps/docs/src/utils/design-theme.ts
@@ -0,0 +1,30 @@
+import type {ThemeId} from "@/app/[lang]/themes/constants";
+
+import {themeIds} from "@/app/[lang]/themes/constants";
+
+export const DEFAULT_DESIGN_THEME: ThemeId = "default";
+export const DESIGN_THEME_STORAGE_KEY = "heroui-docs-design-theme";
+export const DESIGN_THEME_CHANGE_EVENT = "heroui-docs-design-theme-change";
+export const VIBRANT_STORAGE_KEY = "heroui-docs-vibrant-palette";
+
+export function isDesignThemeId(value: string | null | undefined): value is ThemeId {
+  return themeIds.includes(value as ThemeId);
+}
+
+export function getStoredDesignTheme(): ThemeId {
+  if (typeof window === "undefined") {
+    return DEFAULT_DESIGN_THEME;
+  }
+
+  const stored = window.localStorage.getItem(DESIGN_THEME_STORAGE_KEY);
+
+  return isDesignThemeId(stored) ? stored : DEFAULT_DESIGN_THEME;
+}
+
+export function notifyDesignThemeChange(themeId: ThemeId) {
+  window.dispatchEvent(
+    new CustomEvent(DESIGN_THEME_CHANGE_EVENT, {
+      detail: {themeId},
+    }),
+  );
+}
diff --git a/apps/docs/src/utils/env.ts b/apps/docs/src/utils/env.ts
new file mode 100644
index 0000000..3312e04
--- /dev/null
+++ b/apps/docs/src/utils/env.ts
@@ -0,0 +1,25 @@
+import {env} from "~env";
+
+export const __IS_PRE_RELEASE__ = true;
+export const __DEV__ = env.NEXT_PUBLIC_APP_ENV === "development";
+export const __PREVIEW__ = env.NEXT_PUBLIC_APP_ENV === "preview";
+export const __PROD__ = env.NEXT_PUBLIC_APP_ENV === "production";
+
+const getBaseURL = (): URL => {
+  // default - dev
+  let host = "localhost:3000";
+
+  // preview
+  if (__PREVIEW__) host = "v3.heroui.com";
+
+  // production
+  if (__PROD__) host = "www.heroui.com";
+
+  // protocol
+  const protocol = host.startsWith("localhost") ? "http" : "https";
+
+  return new URL(`${protocol}://${host}`);
+};
+
+export const __BASE_URL__ = getBaseURL();
+export const __CDN_URL__ = env.NEXT_PUBLIC_CDN_URL;
diff --git a/apps/docs/src/utils/extract-links.ts b/apps/docs/src/utils/extract-links.ts
new file mode 100644
index 0000000..a60befe
--- /dev/null
+++ b/apps/docs/src/utils/extract-links.ts
@@ -0,0 +1,159 @@
+import matter from "gray-matter";
+
+import {siteConfig} from "@/config/site";
+import {
+  COMPONENT_PATH,
+  COMPONENT_PATH_NATIVE,
+  COMPONENT_STYLES_PATH,
+  COMPONENT_STYLES_PATH_NATIVE,
+  STORYBOOK_URL,
+  THEMES_PATH,
+} from "@/utils/constants";
+
+export interface ComponentLinksType {
+  rac?: string;
+  radix?: string;
+  source?: string;
+  source_native?: string;
+  styles?: string;
+  styles_native?: string;
+  storybook?: string;
+  themes?: string;
+  tailwind?: string;
+  figma?: boolean;
+  [key: string]: string | boolean | undefined;
+}
+
+export interface GithubInfoType {
+  pull?: number;
+}
+
+/**
+ * Extracts the links field from MDX frontmatter
+ * @param content - The raw MDX content string
+ * @returns The parsed links object or null if not found
+ */
+export function extractLinksFromMDX(content: string): ComponentLinksType | null {
+  try {
+    const {data} = matter(content);
+
+    if (data["links"] && typeof data["links"] === "object") {
+      return data["links"] as ComponentLinksType;
+    }
+
+    return null;
+  } catch (error) {
+    console.error("Error extracting links from MDX:", error);
+
+    return null;
+  }
+}
+
+/**
+ * Extracts the github field from MDX frontmatter
+ * @param content - The raw MDX content string
+ * @returns The parsed github object or null if not found
+ */
+export function extractGithubFromMDX(content: string): GithubInfoType | null {
+  try {
+    const {data} = matter(content);
+
+    if (data["github"] && typeof data["github"] === "object") {
+      return data["github"] as GithubInfoType;
+    }
+
+    return null;
+  } catch (error) {
+    console.error("Error extracting github info from MDX:", error);
+
+    return null;
+  }
+}
+
+/**
+ * Extracts the image field from MDX frontmatter
+ * @param content - The raw MDX content string
+ * @returns The image URL string or null if not found
+ */
+export function extractImageFromMDX(content: string): string | null {
+  try {
+    const {data} = matter(content);
+
+    if (data["image"] && typeof data["image"] === "string") {
+      return data["image"];
+    }
+
+    return null;
+  } catch (error) {
+    console.error("Error extracting image from MDX:", error);
+
+    return null;
+  }
+}
+
+/**
+ * Converts a Storybook title to a URL path segment
+ * Handles both grouped titles (e.g., "Components/Buttons/Button") and simple titles
+ * @param title - The Storybook title
+ * @returns URL-safe path segment
+ */
+function convertStorybookTitleToPath(title: string): string {
+  // Remove emojis and trim whitespace
+  const cleaned = title.replace(/[\u{1F300}-\u{1F9FF}]/gu, "").trim();
+
+  // Split by "/" and convert each part to kebab-case
+  return cleaned
+    .split("/")
+    .map((part) =>
+      part
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, ""),
+    )
+    .filter(Boolean)
+    .join("-");
+}
+
+/**
+ * Generates component link URLs based on the extracted links
+ * @param links - The extracted links object
+ * @returns An object with formatted URLs
+ */
+export function generateComponentLinks(links: ComponentLinksType | null) {
+  if (!links) return null;
+
+  // Handle storybook link: can be either a simple slug or a full title path
+  let storybookUrl: string | undefined;
+
+  if (links.storybook) {
+    // If the storybook value contains "/", treat it as a full Storybook title
+    if (links.storybook.includes("/")) {
+      const pathSegment = convertStorybookTitleToPath(links.storybook);
+
+      storybookUrl = `${STORYBOOK_URL}/?path=/docs/${pathSegment}`;
+    } else {
+      // Legacy support: treat as simple slug (kept for backward compatibility)
+      storybookUrl = `${STORYBOOK_URL}/?path=/docs/components-${links.storybook}`;
+    }
+  }
+
+  return {
+    figma: links.figma ? siteConfig.figmaCommunityFile : undefined,
+    rac: links.rac ? `https://react-aria.adobe.com/${links.rac}` : undefined,
+    radix: links.radix
+      ? `https://www.radix-ui.com/primitives/docs/components/${links.radix}`
+      : undefined,
+    source: links.source ? `${COMPONENT_PATH}/${links.source}` : undefined,
+    source_native: links.source_native
+      ? `${COMPONENT_PATH_NATIVE}/${links.source_native}`
+      : undefined,
+    storybook: storybookUrl,
+    styles: links.styles ? `${COMPONENT_STYLES_PATH}/${links.styles}` : undefined,
+    styles_native: links.styles_native
+      ? `${COMPONENT_STYLES_PATH_NATIVE}/${links.styles_native}`
+      : undefined,
+    tailwind: links.tailwind ? `https://tailwindcss.com/docs/${links.tailwind}` : undefined,
+    themes: links.themes ? THEMES_PATH : undefined,
+  };
+}
diff --git a/apps/docs/src/utils/focus.ts b/apps/docs/src/utils/focus.ts
new file mode 100644
index 0000000..0966b0a
--- /dev/null
+++ b/apps/docs/src/utils/focus.ts
@@ -0,0 +1,11 @@
+import {tv} from "tailwind-variants";
+
+export const focusRing = tv({
+  base: "outline outline-offset-2 outline-blue-600 dark:outline-blue-500 forced-colors:outline-[Highlight]",
+  variants: {
+    isFocusVisible: {
+      false: "outline-0",
+      true: "outline-2",
+    },
+  },
+});
diff --git a/apps/docs/src/utils/variants.ts b/apps/docs/src/utils/variants.ts
new file mode 100644
index 0000000..3016629
--- /dev/null
+++ b/apps/docs/src/utils/variants.ts
@@ -0,0 +1,15 @@
+import {buttonVariants} from "@heroui/react";
+import {tv} from "tailwind-variants";
+
+export const docsButtonVariants = tv({
+  defaultVariants: {
+    size: "sm",
+    variant: "tertiary",
+  },
+  extend: buttonVariants,
+  variants: {
+    variant: {
+      tertiary: "relative gap-2 dark:bg-default/70",
+    },
+  },
+});
diff --git a/apps/docs/src/utils/version.ts b/apps/docs/src/utils/version.ts
new file mode 100644
index 0000000..d5319a8
--- /dev/null
+++ b/apps/docs/src/utils/version.ts
@@ -0,0 +1,3 @@
+import pkg from "../../../../packages/react/package.json";
+
+export const currentVersion = pkg?.version;
diff --git a/apps/docs/test_skills_scripts.mjs b/apps/docs/test_skills_scripts.mjs
new file mode 100644
index 0000000..6cc2343
--- /dev/null
+++ b/apps/docs/test_skills_scripts.mjs
@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+/**
+ * Test suite for HeroUI Skill scripts (JavaScript/Node.js).
+ *
+ * Usage:
+ *     # Test against production (default)
+ *     node test_skills_scripts.mjs
+ *
+ *     # Test against staging
+ *     node test_skills_scripts.mjs --env staging
+ *
+ *     # Test against local dev
+ *     node test_skills_scripts.mjs --env dev
+ *
+ *     # Test specific script
+ *     node test_skills_scripts.mjs --script list_components
+ *
+ *     # Verbose output
+ *     node test_skills_scripts.mjs -v
+ *
+ * Environments:
+ *     - dev: http://localhost:8787
+ *     - staging: https://staging-mcp-api.heroui.com
+ *     - production: https://mcp-api.heroui.com
+ *
+ * Note: Tests are updated for v1 API endpoints which return {results: [...]} format
+ * for batch requests (multiple components).
+ */
+
+import {execFile} from "child_process";
+import {dirname, join} from "path";
+import {fileURLToPath} from "url";
+import {promisify} from "util";
+
+const execFileAsync = promisify(execFile);
+
+// Environment configurations
+const ENVIRONMENTS = {
+  dev: "http://localhost:8787",
+  production: "https://mcp-api.heroui.com",
+  staging: "https://staging-mcp-api.heroui.com",
+};
+
+// Get script directory
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SCRIPTS_DIR = join(__dirname, "..", "..", "skills/heroui-react/scripts");
+const NODE = "node";
+
+/**
+ * Result of a single test.
+ */
+class TestResult {
+  constructor(name, passed, duration, output, error = null) {
+    this.name = name;
+    this.passed = passed;
+    this.duration = duration;
+    this.output = output;
+    this.error = error;
+  }
+}
+
+/**
+ * Run a script and return (stdout, stderr, return_code, duration).
+ */
+async function runScript(scriptName, args = null, envVars = null, timeout = 30000) {
+  const scriptPath = join(SCRIPTS_DIR, scriptName);
+  const cmd = [NODE, scriptPath, ...(args || [])];
+
+  const env = {...process.env};
+
+  if (envVars) {
+    Object.assign(env, envVars);
+  }
+
+  const start = Date.now();
+
+  try {
+    // Use AbortController for timeout (Node 15+)
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const {stderr, stdout} = await execFileAsync(cmd[0], cmd.slice(1), {
+        encoding: "utf8",
+        env,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+      const duration = (Date.now() - start) / 1000;
+
+      return [stdout, stderr, 0, duration];
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error.signal === "SIGABRT" || error.code === "ABORT_ERR") {
+        const duration = (Date.now() - start) / 1000;
+
+        return ["", `Timeout after ${timeout / 1000}s`, -1, duration];
+      }
+
+      // execFile throws error with stdout/stderr in error object
+      const duration = (Date.now() - start) / 1000;
+
+      return [error.stdout || "", error.stderr || "", error.code || -1, duration];
+    }
+  } catch (error) {
+    const duration = (Date.now() - start) / 1000;
+
+    return ["", String(error), -1, duration];
+  }
+}
+
+async function testListComponents(apiBase, verbose = false) {
+  const name = "list_components";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript("list_components.mjs", null, envVars);
+
+  // Validate output
+  try {
+    const data = JSON.parse(stdout);
+    const hasComponents = "components" in data && data.components.length > 0;
+    const hasVersion = "latestVersion" in data;
+
+    if (!hasComponents) {
+      return new TestResult(name, false, duration, stdout, "No components in response");
+    }
+
+    if (!hasVersion) {
+      return new TestResult(name, false, duration, stdout, "No latestVersion in response");
+    }
+
+    if (verbose) {
+      console.log(`  Found ${data.components.length} components, version: ${data.latestVersion}`);
+    }
+
+    return new TestResult(name, true, duration, `Found ${data.components.length} components`);
+  } catch (e) {
+    return new TestResult(name, false, duration, stdout, `Invalid JSON: ${e.message}`);
+  }
+}
+
+async function testGetComponentDocs(apiBase, verbose = false) {
+  const name = "get_component_docs";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  // Test with single component
+  const [stdout, stderr, _code, duration] = await runScript(
+    "get_component_docs.mjs",
+    ["Button"],
+    envVars,
+  );
+
+  // Should contain MDX content
+  const hasContent = stdout.length > 100;
+
+  if (!hasContent) {
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "No content returned");
+  }
+
+  if (verbose) {
+    console.log(`  Received ${stdout.length} chars of documentation`);
+
+    if (stderr.toLowerCase().includes("fallback")) {
+      console.log(`  Note: Used fallback method`);
+    }
+  }
+
+  return new TestResult(name, true, duration, `Received ${stdout.length} chars`);
+}
+
+async function testGetComponentDocsMultiple(apiBase, verbose = false) {
+  const name = "get_component_docs_multiple";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript(
+    "get_component_docs.mjs",
+    ["Button", "Card"],
+    envVars,
+  );
+
+  // v1 API returns {results: [...]} format
+  try {
+    const data = JSON.parse(stdout);
+
+    // Check for v1 API format: {results: [...]}
+    if (data.results && Array.isArray(data.results) && data.results.length === 2) {
+      if (verbose) {
+        console.log(`  Received docs for ${data.results.length} components (v1 format)`);
+      }
+
+      return new TestResult(name, true, duration, `Received ${data.results.length} component docs`);
+    }
+
+    // Fallback: check if it's a plain array (fallback format)
+    if (Array.isArray(data) && data.length === 2) {
+      if (verbose) {
+        console.log(`  Received docs for ${data.length} components (fallback format)`);
+      }
+
+      return new TestResult(name, true, duration, `Received ${data.length} component docs`);
+    }
+
+    return new TestResult(
+      name,
+      false,
+      duration,
+      stdout.slice(0, 200),
+      "Expected {results: [...]} or array of 2 results",
+    );
+  } catch (e) {
+    // If not JSON, might be concatenated MDX (also acceptable)
+    if (stdout.length > 200) {
+      return new TestResult(name, true, duration, `Received ${stdout.length} chars (MDX format)`);
+    }
+
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "Invalid response format");
+  }
+}
+
+async function testGetSource(apiBase, verbose = false) {
+  const name = "get_source";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript("get_source.mjs", ["Button"], envVars);
+
+  // Should contain TypeScript/React code
+  const hasContent = stdout.length > 100;
+
+  if (!hasContent) {
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "No content returned");
+  }
+
+  if (verbose) {
+    console.log(`  Received ${stdout.length} chars of source code`);
+
+    if (stdout.includes("GitHub:")) {
+      console.log(`  Includes GitHub URL`);
+    }
+  }
+
+  return new TestResult(name, true, duration, `Received ${stdout.length} chars`);
+}
+
+async function testGetStyles(apiBase, verbose = false) {
+  const name = "get_styles";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript("get_styles.mjs", ["Button"], envVars);
+
+  // Should contain CSS
+  const hasBem = stdout.includes("--"); // BEM modifiers like .button--primary
+  const hasContent = stdout.length > 100;
+
+  if (!hasContent) {
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "No content returned");
+  }
+
+  if (verbose) {
+    console.log(`  Received ${stdout.length} chars of CSS`);
+
+    if (hasBem) {
+      console.log(`  Contains BEM classes`);
+    }
+  }
+
+  return new TestResult(name, true, duration, `Received ${stdout.length} chars`);
+}
+
+async function testGetTheme(apiBase, verbose = false) {
+  const name = "get_theme";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript("get_theme.mjs", null, envVars);
+
+  // Should contain CSS variables
+  const hasOklch = stdout.toLowerCase().includes("oklch");
+  const hasContent = stdout.length > 100;
+
+  if (!hasContent) {
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "No content returned");
+  }
+
+  if (verbose) {
+    console.log(`  Received ${stdout.length} chars of theme variables`);
+
+    if (hasOklch) {
+      console.log(`  Uses oklch color format`);
+    }
+  }
+
+  return new TestResult(name, true, duration, `Received ${stdout.length} chars`);
+}
+
+async function testGetDocs(apiBase, verbose = false) {
+  const name = "get_docs";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, _stderr, _code, duration] = await runScript(
+    "get_docs.mjs",
+    ["/docs/react/getting-started/theming"],
+    envVars,
+  );
+
+  // Should contain MDX content about theming
+  const hasContent = stdout.length > 100;
+
+  if (!hasContent) {
+    return new TestResult(name, false, duration, stdout.slice(0, 200), "No content returned");
+  }
+
+  if (verbose) {
+    console.log(`  Received ${stdout.length} chars of documentation`);
+  }
+
+  return new TestResult(name, true, duration, `Received ${stdout.length} chars`);
+}
+
+async function testGetDocsUsage(apiBase, verbose = false) {
+  const name = "get_docs_usage";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [_stdout, stderr, _code, duration] = await runScript("get_docs.mjs", null, envVars);
+
+  // Should show usage in stderr
+  const hasUsage =
+    stderr.toLowerCase().includes("usage") || stderr.toLowerCase().includes("example");
+
+  if (!hasUsage) {
+    return new TestResult(name, false, duration, stderr.slice(0, 200), "No usage info shown");
+  }
+
+  if (verbose) {
+    console.log(`  Shows usage instructions`);
+  }
+
+  return new TestResult(name, true, duration, "Shows usage instructions");
+}
+
+async function testErrorHandling(apiBase, verbose = false) {
+  const name = "error_handling";
+  const envVars = {HEROUI_API_BASE: apiBase};
+
+  const [stdout, stderr, _code, duration] = await runScript(
+    "get_component_docs.mjs",
+    ["NonExistentComponent12345"],
+    envVars,
+  );
+
+  // Should handle gracefully (either error message or empty result)
+  const combined = (stdout + stderr).toLowerCase();
+
+  if (verbose) {
+    if (combined.includes("error")) {
+      console.log(`  Returns error message for invalid component`);
+    } else if (stderr.toLowerCase().includes("fallback")) {
+      console.log(`  Uses fallback for invalid component`);
+    }
+  }
+
+  return new TestResult(name, true, duration, "Handles invalid input gracefully");
+}
+
+// All tests
+const ALL_TESTS = {
+  error_handling: testErrorHandling,
+  get_component_docs: testGetComponentDocs,
+  get_component_docs_multiple: testGetComponentDocsMultiple,
+  get_docs: testGetDocs,
+  get_docs_usage: testGetDocsUsage,
+  get_source: testGetSource,
+  get_styles: testGetStyles,
+  get_theme: testGetTheme,
+  list_components: testListComponents,
+};
+
+async function runTests(env, scripts = null, verbose = false) {
+  const apiBase = ENVIRONMENTS[env] || ENVIRONMENTS.production;
+  const results = [];
+
+  const testsToRun = Object.fromEntries(
+    Object.entries(ALL_TESTS).filter(([k]) => !scripts || scripts.includes(k)),
+  );
+
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(`HeroUI Skill Scripts Test Suite (JavaScript)`);
+  console.log(`${"=".repeat(60)}`);
+  console.log(`Environment: ${env} (${apiBase})`);
+  console.log(`Tests to run: ${Object.keys(testsToRun).length}`);
+  console.log(`${"=".repeat(60)}\n`);
+
+  for (const [name, testFunc] of Object.entries(testsToRun)) {
+    process.stdout.write(`Running: ${name}... `);
+    const result = await testFunc(apiBase, verbose);
+
+    results.push(result);
+
+    const status = result.passed ? "✓ PASS" : "✗ FAIL";
+
+    console.log(`${status} (${result.duration.toFixed(2)}s)`);
+
+    if (result.error && (verbose || !result.passed)) {
+      console.log(`  Error: ${result.error}`);
+    }
+  }
+
+  return results;
+}
+
+function printSummary(results) {
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  const totalTime = results.reduce((sum, r) => sum + r.duration, 0);
+
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(`Test Summary`);
+  console.log(`${"=".repeat(60)}`);
+  console.log(`Total:  ${results.length}`);
+  console.log(`Passed: ${passed}`);
+  console.log(`Failed: ${failed}`);
+  console.log(`Time:   ${totalTime.toFixed(2)}s`);
+  console.log(`${"=".repeat(60)}`);
+
+  if (failed > 0) {
+    console.log(`\nFailed tests:`);
+
+    for (const r of results) {
+      if (!r.passed) {
+        console.log(`  - ${r.name}: ${r.error}`);
+      }
+    }
+  }
+
+  return failed === 0;
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    env: "production",
+    list: false,
+    script: [],
+    verbose: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--env" || arg === "-e") {
+      options.env = args[++i];
+    } else if (arg === "--script" || arg === "-s") {
+      options.script.push(args[++i]);
+    } else if (arg === "--verbose" || arg === "-v") {
+      options.verbose = true;
+    } else if (arg === "--list" || arg === "-l") {
+      options.list = true;
+    }
+  }
+
+  return options;
+}
+
+async function main() {
+  const options = parseArgs();
+
+  if (options.list) {
+    console.log("Available tests:");
+
+    for (const name of Object.keys(ALL_TESTS)) {
+      console.log(`  - ${name}`);
+    }
+
+    return 0;
+  }
+
+  const results = await runTests(
+    options.env,
+    options.script.length > 0 ? options.script : null,
+    options.verbose,
+  );
+  const success = printSummary(results);
+
+  return success ? 0 : 1;
+}
+
+// Run main and exit with code
+main()
+  .then((code) => {
+    process.exit(code);
+  })
+  .catch((error) => {
+    console.error("Error:", error);
+    process.exit(1);
+  });
diff --git a/apps/docs/tsconfig.json b/apps/docs/tsconfig.json
new file mode 100644
index 0000000..ce8b536
--- /dev/null
+++ b/apps/docs/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@heroui/standard/tsconfig/next.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "preserve",
+    "paths": {
+      "@/.source": ["./.source/server.ts"],
+      "@/.source/*": ["./.source/*"],
+      "@/*": ["./src/*"],
+      "~env": ["./env.ts"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", "env.ts", "next-env.d.ts", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/commitlint.config.mjs b/commitlint.config.mjs
new file mode 100644
index 0000000..3efa54b
--- /dev/null
+++ b/commitlint.config.mjs
@@ -0,0 +1,32 @@
+import conventional from "@commitlint/config-conventional";
+
+/**
+ * Commitlint config
+ */
+const commitLintConfig = {
+  extends: ["@commitlint/config-conventional"],
+  helpUrl: "https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md#commit-convention",
+  rules: {
+    ...conventional.rules,
+    "header-max-length": [0],
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "refactor",
+        "style",
+        "docs",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert",
+        "feature",
+      ],
+    ],
+  },
+};
+
+export default commitLintConfig;
diff --git a/eslint.config.mjs b/eslint.config.mjs
new file mode 100644
index 0000000..f1abc3b
--- /dev/null
+++ b/eslint.config.mjs
@@ -0,0 +1,54 @@
+import baseConfig from "@heroui/standard/eslint/base.mjs";
+import {defineConfig} from "eslint/config";
+
+const config = defineConfig([
+  {
+    ignores: [
+      // Build outputs
+      "**/.temp",
+      "**/.next",
+      "**/.swc",
+      "**/.turbo",
+      "**/.cache",
+      "**/.build",
+      "**/.vercel",
+      "**/dist",
+      "**/build",
+      "**/storybook-static",
+      "**/.rollup.cache",
+      "**/.rollup.cache/**",
+      // Dependencies
+      "**/node_modules/",
+      "**/public/*",
+      // Generated files
+      "pnpm-lock.yaml",
+      "**/.contentlayer/",
+      "**/.source/**",
+      // Test coverage
+      "**/coverage",
+      "**/__snapshots__",
+      // OS files
+      "**/.DS_Store",
+      // Exceptions - files we want to lint
+      "!public/manifest.json",
+      "!.vscode",
+      "!scripts",
+      "!.*.js",
+      "!.*.cjs",
+      "!.*.mjs",
+      "!.*.ts",
+      "!contentlayer.config.ts",
+      "!next-sitemap.config.ts",
+    ],
+  },
+  ...baseConfig,
+  // Allow console usage in skill scripts
+  {
+    files: ["skills/**/*.mjs"],
+    rules: {
+      "no-console": "off",
+    },
+  },
+]);
+
+export default config;
diff --git a/lint-staged.config.mjs b/lint-staged.config.mjs
new file mode 100644
index 0000000..a05d30a
--- /dev/null
+++ b/lint-staged.config.mjs
@@ -0,0 +1,98 @@
+import fs from "fs";
+import {dirname, relative, resolve} from "path";
+
+import {ESLint} from "eslint";
+
+const projectRoot = process.cwd();
+
+// Eslint mode: "Experimental" | "Legacy"
+const LINT_MODE = "Experimental";
+
+const removeIgnoredFilesNew = async (files) => {
+  try {
+    const eslint = new ESLint();
+    const cwd = process.cwd();
+
+    const relativePaths = files.map((file) => relative(cwd, file));
+    const isIgnored = await Promise.all(relativePaths.map((file) => eslint.isPathIgnored(file)));
+
+    return files.filter((_, i) => !isIgnored[i]).join(" ");
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    process.exit(1);
+  }
+};
+
+function findPackageRoot(file) {
+  let dir = dirname(file);
+
+  while (dir !== "/") {
+    if (fs.existsSync(`${dir}/package.json`)) return dir;
+    const parentDir = dirname(dir);
+
+    if (parentDir === dir) break;
+    dir = parentDir;
+  }
+
+  return projectRoot;
+}
+
+async function removeIgnoredFilesLegacy(files, eslint) {
+  const isIgnored = await Promise.all(files.map((file) => eslint.isPathIgnored(file)));
+
+  return files.filter((_, i) => !isIgnored[i]);
+}
+
+const lintStaged = {
+  "**/*.{cjs,mjs,js,ts,jsx,tsx}": async (files) => {
+    if (LINT_MODE === "Experimental") {
+      // use ESLint with experimental configuration file resolution
+      const filesToLint = await removeIgnoredFilesNew(files);
+
+      return [
+        `eslint --flag v10_config_lookup_from_file --max-warnings=0 --no-warn-ignored --fix ${filesToLint}`,
+      ];
+    }
+
+    if (LINT_MODE === "Legacy") {
+      // Legacy with group files by package root and resolve ESLint config
+      const filesByPackage = new Map();
+
+      for (const file of files) {
+        const pkgRoot = findPackageRoot(file);
+
+        if (!filesByPackage.has(pkgRoot)) filesByPackage.set(pkgRoot, []);
+        filesByPackage.get(pkgRoot).push(file);
+      }
+
+      const commands = [];
+
+      for (const [pkgRoot, pkgFiles] of filesByPackage.entries()) {
+        // Check if the package has its own eslint.config.mjs
+        const configPath = fs.existsSync(resolve(pkgRoot, "eslint.config.mjs"))
+          ? resolve(pkgRoot, "eslint.config.mjs")
+          : resolve(projectRoot, "eslint.config.mjs");
+
+        const eslint = new ESLint({cwd: pkgRoot, overrideConfigFile: configPath});
+        const filesToLint = await removeIgnoredFilesLegacy(pkgFiles, eslint);
+
+        if (filesToLint.length) {
+          commands.push(
+            `eslint --config ${configPath} --max-warnings=0 --fix ${filesToLint.join(" ")}`,
+          );
+        }
+      }
+
+      return commands;
+    }
+
+    return [];
+  },
+
+  "**/*.{html,css,scss,json,jsonc,md,mdx}": async (files) => {
+    return [`prettier --ignore-path .prettierignore --write ${files.join(" ")}`];
+  },
+};
+
+export default lintStaged;
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..05cd55f
--- /dev/null
+++ b/package.json
@@ -0,0 +1,127 @@
+{
+  "name": "heroui",
+  "private": true,
+  "version": "3.2.2",
+  "license": "MIT",
+  "author": {
+    "name": "HeroUI",
+    "email": "support@heroui.com",
+    "url": "https://heroui.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heroui-inc/heroui"
+  },
+  "scripts": {
+    "dev": "dotenv -- turbo dev --filter=@heroui/storybook",
+    "dev:docs": "dotenv -- turbo dev --filter=@heroui/docs",
+    "build": "turbo build --filter=@heroui/styles --filter=@heroui/react",
+    "build:docs": "dotenv -- turbo build --filter=@heroui/docs",
+    "build:docs-cn": "dotenv -- turbo build --filter=@heroui/docs-cn",
+    "build:react": "turbo build --filter=@heroui/react",
+    "build:storybook": "dotenv -- turbo build --filter=@heroui/storybook",
+    "build:sb": "dotenv -- pnpm build:storybook",
+    "start:docs": "dotenv -- turbo start --filter=@heroui/docs",
+    "start:docs-cn": "dotenv -- turbo start --filter=@heroui/docs-cn",
+    "start:storybook": "dotenv -- turbo start --filter=@heroui/storybook",
+    "lint": "turbo lint",
+    "lint:fix": "turbo lint -- --fix",
+    "lint:docs": "dotenv -- turbo lint --filter=@heroui/docs",
+    "lint:docs-cn": "dotenv -- turbo lint --filter=@heroui/docs-cn",
+    "lint:react": "turbo lint --filter=@heroui/react",
+    "lint:storybook": "dotenv -- turbo lint --filter=@heroui/storybook",
+    "format": "prettier --ignore-path .prettierignore --check .",
+    "format:fix": "prettier --ignore-path .prettierignore --write .",
+    "typecheck": "turbo typecheck",
+    "typecheck:docs": "dotenv -- turbo typecheck --filter=@heroui/docs",
+    "typecheck:docs-cn": "dotenv -- turbo typecheck --filter=@heroui/docs-cn",
+    "typecheck:react": "turbo typecheck --filter=@heroui/react",
+    "typecheck:storybook": "dotenv -- turbo typecheck --filter=@heroui/storybook",
+    "typegen:docs": "dotenv -- pnpm --filter @heroui/docs typegen",
+    "typegen:docs-cn": "dotenv -- pnpm --filter @heroui/docs-cn typegen",
+    "version:bump": "bumpp package.json packages/react/package.json packages/styles/package.json",
+    "release": "pnpm run build && bumpp package.json packages/react/package.json packages/styles/package.json --all",
+    "clean": "pnpm clean:cache && pnpm i",
+    "clean:cache": "find . \\( -name '.turbo' -o -name '.next' -o -name 'dist' -o -name 'node_modules' -o -name '.source' -o -name '.contentlayer' -o -name 'pnpm-lock.yaml' \\) -prune -exec rm -rf '{}' +",
+    "upli": "pnpm up --filter \"./**\"  -L -i",
+    "prepare": "husky",
+    "postinstall": "pnpm --filter @heroui/styles build && pnpm typegen:docs && pnpm typegen:docs-cn"
+  },
+  "devDependencies": {
+    "@babel/core": "7.28.5",
+    "@babel/preset-react": "7.28.5",
+    "@babel/preset-typescript": "7.28.5",
+    "bumpp": "11.0.1",
+    "@commitlint/cli": "20.2.0",
+    "@commitlint/config-conventional": "20.2.0",
+    "@eslint/eslintrc": "3.3.3",
+    "@eslint/js": "9.39.2",
+    "@heroui/standard": "workspace:*",
+    "@next/eslint-plugin-next": "16.1.1",
+    "@rollup/plugin-babel": "6.1.0",
+    "@rollup/plugin-commonjs": "29.0.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@types/node": "25.0.3",
+    "@typescript-eslint/eslint-plugin": "8.50.1",
+    "@typescript-eslint/parser": "8.50.1",
+    "babel-plugin-react-compiler": "19.1.0-rc.3",
+    "clean-package": "2.2.0",
+    "dotenv": "17.2.3",
+    "dotenv-cli": "11.0.0",
+    "eslint": "9.39.2",
+    "eslint-config-next": "16.1.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsx-a11y": "6.10.2",
+    "eslint-plugin-only-warn": "1.1.0",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "7.0.1",
+    "eslint-plugin-react-refresh": "0.4.26",
+    "eslint-plugin-sort-destructure-keys": "2.0.0",
+    "eslint-plugin-sort-keys-fix": "1.1.2",
+    "eslint-plugin-storybook": "10.1.10",
+    "eslint-plugin-unused-imports": "4.3.0",
+    "globals": "16.5.0",
+    "husky": "9.1.7",
+    "jiti": "2.6.1",
+    "lint-staged": "16.2.7",
+    "parcel": "2.16.3",
+    "postcss": "8.5.6",
+    "prettier": "3.7.4",
+    "prettier-plugin-css-order": "2.1.2",
+    "prettier-plugin-tailwindcss": "0.7.2",
+    "rollup": "4.54.0",
+    "rollup-plugin-peer-deps-external": "2.2.4",
+    "rollup-plugin-postcss": "4.0.2",
+    "tsup": "8.5.1",
+    "tsx": "4.21.0",
+    "turbo": "2.7.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.50.1",
+    "vitest": "4.0.16"
+  },
+  "pnpm": {
+    "overrides": {
+      "shiki": "3.20.0",
+      "ts-morph": "27.0.2"
+    },
+    "onlyBuiltDependencies": [
+      "@parcel/watcher",
+      "@swc/core",
+      "core-js",
+      "esbuild",
+      "lmdb",
+      "msgpackr-extract",
+      "protobufjs",
+      "sharp",
+      "unrs-resolver"
+    ]
+  },
+  "engines": {
+    "node": ">=20.x",
+    "pnpm": ">=10.x"
+  },
+  "packageManager": "pnpm@10.26.2"
+}
diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md
new file mode 100644
index 0000000..315e08a
--- /dev/null
+++ b/packages/react/CHANGELOG.md
@@ -0,0 +1,33 @@
+# @heroui/react
+
+## 3.0.1
+
+### Patch Changes
+
+- README updated
+
+- Updated dependencies []:
+  - @heroui/styles@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- v3.0.0
+
+- [`b2b1912`](https://github.com/heroui-inc/heroui/commit/b2b19129ec5ae7bcd432bcd89f78c4c25c7ee9ae) Thanks [@jrgarciadev](https://github.com/jrgarciadev)! - Types fixed and removed needless folders from dist
+
+- Updated dependencies []:
+  - @heroui/styles@3.0.0
+
+## 3.0.0-alpha.3
+
+### Patch Changes
+
+- Types fixed and removed needless folders from dist
+
+## 3.0.0-alpha.2
+
+### Patch Changes
+
+- Set up alpha prerelease configuration to ensure v3 remains in alpha status and prevent accidental release of v3.0.0 stable version
diff --git a/packages/react/README.md b/packages/react/README.md
new file mode 100644
index 0000000..243aa97
--- /dev/null
+++ b/packages/react/README.md
@@ -0,0 +1,113 @@
+<p align="center">
+  <a href="https://heroui.com">
+      <img 
+        alt="HeroUI v3 logo" 
+        width="100%" 
+        src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg"
+      />
+  </a>
+</p>
+<p align="center">
+  <a href="https://github.com/heroui-inc/heroui/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/@heroui/react?style=flat" alt="License">
+  </a>
+  <a href="https://www.npmjs.com/package/@heroui/react">
+    <img src="https://img.shields.io/npm/dm/@heroui/react.svg?style=flat-round" alt="npm downloads">
+  </a>
+</p>
+
+## Why HeroUI?
+
+HeroUI (previously NextUI) is a production-ready React component library that combines the accessibility rigor of [React Aria](https://react-spectrum.adobe.com/react-aria/) with the utility-first styling of [Tailwind CSS v4](https://tailwindcss.com/). It ships a clean compound component API (`Card.Header`, `Card.Content`, `Select.Item`, …), requires no `<Provider>` wrapper, and works out of the box with React 19 and Next.js.
+
+- **Accessible by default** — Built on React Aria for WCAG-compliant keyboard, focus, and screen-reader behavior
+- **Tailwind CSS v4** — Modern engine, no CSS-in-JS runtime, smaller output, faster builds
+- **Compound components** — Composable API (`Card.Header`, `Card.Content`) instead of deeply nested props
+- **Zero boilerplate** — No Provider wrapper needed (unlike Chakra, MUI)
+- **AI-native** — MCP server, `llms.txt`, and agent skills so AI assistants understand your components
+- **Battle-tested** — Previously known as NextUI, trusted by thousands of production apps
+
+## Packages
+
+| Package | Description |
+|---|---|
+| [`@heroui/react`](https://www.npmjs.com/package/@heroui/react) | Full component bundle |
+| [`@heroui/styles`](https://www.npmjs.com/package/@heroui/styles) | Styles / theme only |
+| Individual packages | e.g. `@heroui/button`, `@heroui/modal` — tree-shakeable per-component imports |
+
+## Getting Started
+
+Visit [heroui.com/docs/react/getting-started/quick-start](https://heroui.com/docs/react/getting-started/quick-start) to get started with HeroUI.
+
+```bash
+npm install @heroui/react
+```
+
+## Who Is This For?
+
+HeroUI is a good fit if you are building:
+
+- **SaaS applications** — forms, tables, overlays, and notifications out of the box
+- **Dashboards & admin panels** — data-dense layouts with consistent design tokens
+- **E-commerce storefronts** — performant, accessible, SEO-friendly components
+- **Marketing sites & landing pages** — polished UI without a heavyweight runtime
+- **Any React / Next.js project** that values design quality and accessibility
+
+## AI-Powered Development
+
+HeroUI is built for the AI-assisted development workflow.
+
+| Tool | What it does |
+|---|---|
+| **MCP Server** (`@heroui/react-mcp`) | Components that understand your theme — install the server in Cursor, Claude Code, Windsurf, or any MCP-compatible editor |
+| **llms.txt** | Available at [heroui.com/llms.txt](https://heroui.com/llms.txt) — structured context for LLMs about every component |
+| **Agent Skills** | Run `npx heroui-cli agents-md` to install skills for Cursor, Claude Code, and more |
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **GitHub Copilot**, and any tool that supports MCP or `llms.txt`.
+
+## Compared To
+
+| Library | How HeroUI differs |
+|---|---|
+| **shadcn/ui** | HeroUI is batteries-included with a consistent design system; shadcn is copy-paste-customize |
+| **MUI** | HeroUI is lighter, Tailwind-native, no CSS-in-JS runtime overhead |
+| **Chakra UI** | HeroUI uses React Aria (stronger a11y primitives) and Tailwind v4 (better perf) |
+| **Mantine** | HeroUI has AI tooling (MCP, llms.txt), Tailwind-first styling |
+
+## Documentation
+
+- **Latest (v3)**: [heroui.com](https://heroui.com)
+- **v2**: [v2.heroui.com](https://v2.heroui.com)
+
+## Storybook
+
+Visit [storybook-v3.heroui.com](https://storybook-v3.heroui.com/) to view the storybook for all components.
+
+## Roadmap
+
+Visit [herouiv3.featurebase.app/roadmap](https://herouiv3.featurebase.app/roadmap) to view the roadmap for HeroUI v3.
+
+## Figma
+
+Visit the [HeroUI Figma Kit (v3)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3) to view the design kit.
+
+## Community
+
+We're excited to see the community adopt HeroUI, raise issues, and provide feedback.
+Whether it's a feature request, bug report, or a project to showcase, please get involved!
+
+- [Discord](https://discord.gg/9b6yyZKmH4)
+- [X](https://x.com/hero_ui)
+- [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
+
+## Contributing
+
+Contributions are always welcome!
+
+See [CONTRIBUTING.md](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md) for ways to get started.
+
+Please adhere to this project's [CODE_OF_CONDUCT](https://github.com/heroui-inc/heroui/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
diff --git a/packages/react/clean-package.config.json b/packages/react/clean-package.config.json
new file mode 100644
index 0000000..7d1137a
--- /dev/null
+++ b/packages/react/clean-package.config.json
@@ -0,0 +1,11 @@
+{
+  "remove": ["devDependencies", "scripts", "clean-package"],
+  "replace": {
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "type": "module",
+    "sideEffects": false
+  },
+  "backupPath": ".package.json.backup"
+}
diff --git a/packages/react/eslint.config.mjs b/packages/react/eslint.config.mjs
new file mode 100644
index 0000000..a2a0eef
--- /dev/null
+++ b/packages/react/eslint.config.mjs
@@ -0,0 +1,13 @@
+import baseReactConfig from "@heroui/standard/eslint/react.mjs";
+import {defineConfig} from "eslint/config";
+
+const config = defineConfig([
+  ...baseReactConfig,
+  {
+    rules: {
+      "react-hooks/rules-of-hooks": "off",
+    },
+  },
+]);
+
+export default config;
diff --git a/packages/react/package.json b/packages/react/package.json
new file mode 100644
index 0000000..9d3da5d
--- /dev/null
+++ b/packages/react/package.json
@@ -0,0 +1,91 @@
+{
+  "name": "@heroui/react",
+  "version": "3.2.2",
+  "description": "🚀 Beautiful and modern React UI library built with Tailwind CSS 4.0.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "HeroUI <support@heroui.com>",
+  "homepage": "https://heroui.com",
+  "keywords": [
+    "next",
+    "next ui",
+    "hero ui",
+    "components",
+    "modern components",
+    "react components",
+    "react ui"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    },
+    "./package.json": "./package.json",
+    "./styles": {
+      "default": "./src/styles.css",
+      "style": "./src/styles.css"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heroui-inc/heroui.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/heroui-inc/heroui/issues"
+  },
+  "scripts": {
+    "dev": "rollup -c rollup.config.mjs --watch",
+    "build": "node scripts/build.mjs --tsc",
+    "build:fast": "node scripts/build.mjs",
+    "add:component": "node scripts/add-component.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "prepack": "clean-package && node scripts/update-exports.mjs",
+    "postpack": "clean-package restore"
+  },
+  "clean-package": "./clean-package.config.json",
+  "dependencies": {
+    "@heroui/styles": "workspace:*",
+    "@radix-ui/react-avatar": "1.1.11",
+    "@react-aria/ssr": "3.10.1",
+    "@react-aria/i18n": "3.13.1",
+    "@react-aria/utils": "3.34.1",
+    "@react-types/shared": "3.36.0",
+    "@react-types/color": "3.2.0",
+    "@react-stately/utils": "3.12.1",
+    "input-otp": "1.4.2",
+    "react-aria": "^3.50.0",
+    "react-aria-components": "^1.19.0",
+    "tailwind-merge": "3.4.0",
+    "tailwind-variants": "3.2.2"
+  },
+  "devDependencies": {
+    "@heroui/standard": "workspace:*",
+    "@iconify/react": "6.0.2",
+    "@internationalized/date": "3.12.2",
+    "@react-stately/data": "3.16.1",
+    "@storybook/react": "10.1.10",
+    "@types/fs-extra": "11.0.4",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "fs-extra": "11.3.3",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "tailwindcss": "4.1.18"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "tailwindcss": ">=4.0.0"
+  }
+}
diff --git a/packages/react/rollup.config.mjs b/packages/react/rollup.config.mjs
new file mode 100644
index 0000000..bfcf2e6
--- /dev/null
+++ b/packages/react/rollup.config.mjs
@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+
+import babel from "@rollup/plugin-babel";
+import resolve from "@rollup/plugin-node-resolve";
+import {defineConfig} from "rollup";
+import peerDepsExternal from "rollup-plugin-peer-deps-external";
+import postcss from "rollup-plugin-postcss";
+
+const packageJson = JSON.parse(fs.readFileSync("./package.json", "utf-8"));
+
+// Custom plugin to replace version placeholder
+const replaceVersion = () => ({
+  name: "replace-version",
+  transform(code, id) {
+    if (id.includes("version.ts") || id.includes("version.js")) {
+      return code.replace("__HEROUI_VERSION__", packageJson.version);
+    }
+
+    return null;
+  },
+});
+
+// Get all component directories
+const componentDirs = fs.readdirSync("./src/components").filter((file) => {
+  const fullPath = path.join("./src/components", file);
+
+  return fs.statSync(fullPath).isDirectory() && fs.existsSync(path.join(fullPath, "index.ts"));
+});
+
+// Create individual entry points for each component
+const componentEntries = componentDirs.reduce((acc, dir) => {
+  acc[`components/${dir}/index`] = `src/components/${dir}/index.ts`;
+
+  return acc;
+}, {});
+
+// All entry points
+const input = {
+  index: "src/index.ts",
+  ...componentEntries,
+};
+
+const external = [
+  ...Object.keys(packageJson.peerDependencies || {}),
+  ...Object.keys(packageJson.dependencies || {}),
+  /^react($|\/)/,
+  /^react-dom($|\/)/,
+  /^@react-aria/,
+  /^@react-stately/,
+  /^@react-types\//,
+  /^@internationalized\//,
+  /^react-aria($|\/)/,
+  /^react-aria-components($|\/)/,
+  /^tailwind-merge/,
+  /^tailwind-variants/,
+];
+
+const plugins = [
+  peerDepsExternal(),
+  resolve({
+    extensions: [".js", ".jsx", ".ts", ".tsx"],
+  }),
+  replaceVersion(),
+  babel({
+    babelHelpers: "bundled",
+    exclude: "node_modules/**",
+    extensions: [".js", ".jsx", ".ts", ".tsx"],
+    presets: [["@babel/preset-react", {runtime: "automatic"}], "@babel/preset-typescript"],
+  }),
+  postcss({
+    extract: true,
+    minimize: true,
+    modules: false,
+  }),
+];
+
+export default defineConfig({
+  external,
+  input,
+  onwarn(warning, warn) {
+    // Ignore "use client" directive warnings
+    if (warning.code === "MODULE_LEVEL_DIRECTIVE") {
+      return;
+    }
+    warn(warning);
+  },
+  output: {
+    dir: "dist",
+    // Disable sourcemaps
+    // Optimize for tree shaking
+    exports: "named",
+    format: "es",
+    hoistTransitiveImports: false,
+    preserveModules: true,
+    preserveModulesRoot: "src",
+    sourcemap: false,
+  },
+  plugins,
+  treeshake: {
+    moduleSideEffects: false,
+    propertyReadSideEffects: false,
+  },
+});
diff --git a/packages/react/scripts/add-component.mjs b/packages/react/scripts/add-component.mjs
new file mode 100644
index 0000000..d34c7c0
--- /dev/null
+++ b/packages/react/scripts/add-component.mjs
@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import path from "path";
+import {fileURLToPath} from "url";
+
+import fs from "fs-extra";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+
+async function addComponent(componentName) {
+  if (!componentName) {
+    console.error("❌ Please provide a component name");
+    console.log("Usage: node scripts/add-component.mjs <component-name>");
+    process.exit(1);
+  }
+
+  // Convert to kebab-case if needed
+  const kebabName = componentName.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+  const componentDir = path.join(rootDir, "src/components", kebabName);
+
+  if (await fs.pathExists(componentDir)) {
+    console.error(`❌ Component "${kebabName}" already exists`);
+    process.exit(1);
+  }
+
+  console.log(`📦 Creating new component: ${kebabName}`);
+
+  // Create component directory
+  await fs.ensureDir(componentDir);
+
+  // Create component files
+  const componentContent = `"use client";
+
+import React from "react";
+
+import {${componentName}Variants, type ${componentName}VariantProps} from "./${kebabName}.styles";
+
+export interface ${componentName}Props extends ${componentName}VariantProps {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export const ${componentName} = React.forwardRef<HTMLDivElement, ${componentName}Props>(
+  ({children, className, ...props}, ref) => {
+    return (
+      <div ref={ref} className={${componentName}Variants({className, ...props})}>
+        {children}
+      </div>
+    );
+  }
+);
+
+${componentName}.displayName = "HeroUI.${componentName}";
+`;
+
+  const stylesContent = `import type {VariantProps} from "tailwind-variants";
+import {tv} from "tailwind-variants";
+
+export const ${componentName}Variants = tv({
+  base: "inline-flex items-center justify-center",
+  variants: {
+    variant: {
+      default: "bg-background text-foreground",
+      primary: "bg-primary text-primary-foreground",
+    },
+    size: {
+      sm: "h-8 px-3 text-sm",
+      md: "h-10 px-4",
+      lg: "h-12 px-6 text-lg",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+    size: "md",
+  },
+});
+
+export type ${componentName}VariantProps = VariantProps<typeof ${componentName}Variants>;
+`;
+
+  const storiesContent = `import type {Meta, StoryObj} from "@storybook/react";
+
+import {${componentName}} from "./${kebabName}";
+
+const meta: Meta<typeof ${componentName}> = {
+  title: "Components/${componentName}",
+  component: ${componentName},
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ${componentName}>;
+
+export const Default: Story = {
+  args: {
+    children: "${componentName} Component",
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <${componentName} variant="default">Default</${componentName}>
+      <${componentName} variant="primary">Primary</${componentName}>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <${componentName} size="sm">Small</${componentName}>
+      <${componentName} size="md">Medium</${componentName}>
+      <${componentName} size="lg">Large</${componentName}>
+    </div>
+  ),
+};
+`;
+
+  const indexContent = `export {${componentName}, type ${componentName}Props} from "./${kebabName}";
+export {${componentName}Variants, type ${componentName}VariantProps} from "./${kebabName}.styles";
+`;
+
+  // Write files
+  await fs.writeFile(path.join(componentDir, `${kebabName}.tsx`), componentContent);
+  await fs.writeFile(path.join(componentDir, `${kebabName}.styles.ts`), stylesContent);
+  await fs.writeFile(path.join(componentDir, `${kebabName}.stories.tsx`), storiesContent);
+  await fs.writeFile(path.join(componentDir, "index.ts"), indexContent);
+
+  // Update components index
+  const componentsIndexPath = path.join(rootDir, "src/components/index.ts");
+  const componentsIndex = await fs.readFile(componentsIndexPath, "utf-8");
+
+  // Find the right place to insert (alphabetically)
+  const lines = componentsIndex.split("\n");
+  const exportLine = `export * from "./${kebabName}";`;
+
+  let inserted = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('export * from "./') && lines[i] > exportLine) {
+      lines.splice(i, 0, exportLine);
+      inserted = true;
+      break;
+    }
+  }
+
+  if (!inserted) {
+    // Insert before the icons section or at the end
+    const iconsIndex = lines.findIndex((line) => line.includes("Icons"));
+
+    if (iconsIndex > 0) {
+      lines.splice(iconsIndex - 1, 0, exportLine);
+    } else {
+      lines.push(exportLine);
+    }
+  }
+
+  await fs.writeFile(componentsIndexPath, lines.join("\n"));
+
+  console.log(`✅ Component "${kebabName}" created successfully!`);
+  console.log("\n📁 Created files:");
+  console.log(`   - src/components/${kebabName}/${kebabName}.tsx`);
+  console.log(`   - src/components/${kebabName}/${kebabName}.styles.ts`);
+  console.log(`   - src/components/${kebabName}/${kebabName}.stories.tsx`);
+  console.log(`   - src/components/${kebabName}/index.ts`);
+  console.log("\n✏️  Updated src/components/index.ts");
+  console.log("\n🎯 Next steps:");
+  console.log("   1. Run 'pnpm build' to generate the export in package.json");
+  console.log("   2. The component will be available as:");
+  console.log(`      - import { ${componentName} } from "@heroui/react"`);
+  console.log(`      - import { ${componentName} } from "@heroui/react/${kebabName}"`);
+}
+
+// Get component name from command line
+const componentName = process.argv[2];
+
+addComponent(componentName).catch((error) => {
+  console.error("❌ Failed to create component:", error);
+  process.exit(1);
+});
diff --git a/packages/react/scripts/build.mjs b/packages/react/scripts/build.mjs
new file mode 100644
index 0000000..a5f3974
--- /dev/null
+++ b/packages/react/scripts/build.mjs
@@ -0,0 +1,297 @@
+/* eslint-disable no-console */
+import {execSync} from "child_process";
+import path from "path";
+import {fileURLToPath} from "url";
+import zlib from "zlib";
+
+import fs from "fs-extra";
+
+import {generateTypes} from "./generate-types.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+const distDir = path.join(rootDir, "dist");
+
+async function clean() {
+  console.log("🧹 Cleaning dist directory...");
+  await fs.remove(distDir);
+}
+
+async function build() {
+  console.log("📦 Building with Rollup...");
+  execSync("rollup -c rollup.config.mjs", {cwd: rootDir, stdio: "inherit"});
+}
+
+async function buildStyles() {
+  console.log("🎨 Creating styles export...");
+
+  // Simply copy the styles.css file to dist
+  const stylesPath = path.join(rootDir, "src/styles.css");
+  const outputPath = path.join(distDir, "styles.css");
+
+  await fs.copy(stylesPath, outputPath);
+
+  console.log("✅ Styles export created successfully");
+}
+
+async function logComponentCount() {
+  console.log("📊 Counting components...");
+
+  const componentsDir = path.join(rootDir, "src/components");
+  let componentCount = 0;
+
+  if (await fs.pathExists(componentsDir)) {
+    const items = await fs.readdir(componentsDir);
+
+    for (const item of items) {
+      const itemPath = path.join(componentsDir, item);
+      const stat = await fs.stat(itemPath);
+
+      // Check if it's a directory with an index.ts file
+      if (stat.isDirectory() && (await fs.pathExists(path.join(itemPath, "index.ts")))) {
+        // Skip special directories
+        if (item === "icons" || item === "utils" || item === "hooks") {
+          continue;
+        }
+        componentCount++;
+      }
+    }
+  }
+
+  console.log(`✅ Found ${componentCount} components`);
+  console.log(`   Note: Component exports will be generated during 'pnpm pack' via clean-package`);
+}
+
+async function addUseClientDirective() {
+  console.log("🔧 Adding directives to files...");
+
+  // Find all JS files in the components and hooks directories
+  const jsFiles = [];
+  const componentsDir = path.join(distDir, "components");
+  const hooksDir = path.join(distDir, "hooks");
+  const srcDir = path.join(rootDir, "src");
+
+  async function findJsFiles(dir) {
+    const items = await fs.readdir(dir);
+
+    for (const item of items) {
+      const fullPath = path.join(dir, item);
+      const stat = await fs.stat(fullPath);
+
+      if (stat.isDirectory()) {
+        await findJsFiles(fullPath);
+      } else if (item.endsWith(".js")) {
+        jsFiles.push(fullPath);
+      }
+    }
+  }
+
+  if (await fs.pathExists(componentsDir)) {
+    await findJsFiles(componentsDir);
+  }
+
+  if (await fs.pathExists(hooksDir)) {
+    await findJsFiles(hooksDir);
+  }
+
+  let useClientCount = 0;
+  let useStrictCount = 0;
+
+  // Add "use client" or "use strict" based on source file type
+  for (const jsFile of jsFiles) {
+    // Map the dist file back to its source file
+    const relativePath = path.relative(distDir, jsFile);
+    const sourcePathTs = path.join(srcDir, relativePath.replace(/\.js$/, ".ts"));
+    const sourcePathTsx = path.join(srcDir, relativePath.replace(/\.js$/, ".tsx"));
+
+    const content = await fs.readFile(jsFile, "utf-8");
+
+    // Skip if already has a directive
+    if (
+      content.startsWith('"use client"') ||
+      content.startsWith("'use client'") ||
+      content.startsWith('"use strict"') ||
+      content.startsWith("'use strict'")
+    ) {
+      continue;
+    }
+
+    // Check which source file exists
+    const isTsx = await fs.pathExists(sourcePathTsx);
+    const isTs = await fs.pathExists(sourcePathTs);
+
+    if (isTsx) {
+      // .tsx files get "use client"
+      await fs.writeFile(jsFile, `"use client";\n${content}`);
+      useClientCount++;
+    } else if (isTs) {
+      // .ts files get "use strict"
+      await fs.writeFile(jsFile, `"use strict";\n${content}`);
+      useStrictCount++;
+    }
+  }
+
+  console.log(`✅ Added "use client" to ${useClientCount} files (from .tsx)`);
+  console.log(`✅ Added "use strict" to ${useStrictCount} files (from .ts)`);
+}
+
+async function measureBundleSizes() {
+  console.log("📊 Measuring bundle sizes...");
+
+  const sizes = {
+    components: {},
+    css: {},
+    main: {},
+    plugin: {},
+    total: {gzip: 0, min: 0},
+  };
+
+  // Helper function to measure file size
+  async function measureFile(filePath) {
+    if (!(await fs.pathExists(filePath))) {
+      return null;
+    }
+
+    const content = await fs.readFile(filePath);
+    const minSize = Buffer.byteLength(content) / 1000;
+    const gzipSize = zlib.gzipSync(content, {level: 9}).length / 1000;
+
+    return {
+      gzip: gzipSize.toFixed(2),
+      min: minSize.toFixed(2),
+    };
+  }
+
+  // Measure main bundle
+  const mainPath = path.join(distDir, "index.js");
+  const mainSize = await measureFile(mainPath);
+
+  if (mainSize) {
+    sizes.main = mainSize;
+    sizes.total.min += parseFloat(mainSize.min);
+    sizes.total.gzip += parseFloat(mainSize.gzip);
+  }
+
+  // Measure plugin bundle
+  const pluginPath = path.join(distDir, "plugin.js");
+  const pluginSize = await measureFile(pluginPath);
+
+  if (pluginSize) {
+    sizes.plugin = pluginSize;
+    sizes.total.min += parseFloat(pluginSize.min);
+    sizes.total.gzip += parseFloat(pluginSize.gzip);
+  }
+
+  // Measure individual components
+  const componentsDir = path.join(distDir, "components");
+
+  if (await fs.pathExists(componentsDir)) {
+    const componentDirs = await fs.readdir(componentsDir);
+
+    for (const componentDir of componentDirs) {
+      const componentPath = path.join(componentsDir, componentDir, "index.js");
+      const componentSize = await measureFile(componentPath);
+
+      if (componentSize) {
+        sizes.components[componentDir] = componentSize;
+        sizes.total.min += parseFloat(componentSize.min);
+        sizes.total.gzip += parseFloat(componentSize.gzip);
+      }
+    }
+  }
+
+  // Measure CSS files
+  const cssPath = path.join(distDir, "index.css");
+  const cssSize = await measureFile(cssPath);
+
+  if (cssSize) {
+    sizes.css.main = cssSize;
+    sizes.total.min += parseFloat(cssSize.min);
+    sizes.total.gzip += parseFloat(cssSize.gzip);
+  }
+
+  // Measure styles.css
+  const stylesCssPath = path.join(distDir, "styles.css");
+  const stylesCssSize = await measureFile(stylesCssPath);
+
+  if (stylesCssSize) {
+    sizes.css.styles = stylesCssSize;
+    sizes.total.min += parseFloat(stylesCssSize.min);
+    sizes.total.gzip += parseFloat(stylesCssSize.gzip);
+  }
+
+  // Round totals
+  sizes.total.min = sizes.total.min.toFixed(2);
+  sizes.total.gzip = sizes.total.gzip.toFixed(2);
+
+  // Save sizes to JSON file
+  const sizesPath = path.join(rootDir, "bundle-sizes.json");
+
+  await fs.writeJson(sizesPath, sizes, {spaces: 2});
+
+  // Print size report
+  console.log("\n📦 Bundle Size Report");
+  console.log("═".repeat(50));
+  console.log(`Total: ${sizes.total.min}kb (${sizes.total.gzip}kb gzipped)`);
+  console.log("─".repeat(50));
+
+  console.log("\n📄 Main Bundles:");
+  console.log(`  index.js: ${sizes.main.min}kb (${sizes.main.gzip}kb gzipped)`);
+  if (sizes.plugin.min) {
+    console.log(`  plugin.js: ${sizes.plugin.min}kb (${sizes.plugin.gzip}kb gzipped)`);
+  }
+
+  if (sizes.css.main || sizes.css.styles) {
+    console.log("\n🎨 CSS:");
+    if (sizes.css.main) {
+      console.log(`  index.css: ${sizes.css.main.min}kb (${sizes.css.main.gzip}kb gzipped)`);
+    }
+    if (sizes.css.styles) {
+      console.log(`  styles.css: ${sizes.css.styles.min}kb (${sizes.css.styles.gzip}kb gzipped)`);
+    }
+  }
+
+  console.log("\n🧩 Components:");
+  const sortedComponents = Object.entries(sizes.components).sort(
+    (a, b) => parseFloat(b[1].gzip) - parseFloat(a[1].gzip),
+  );
+
+  for (const [component, size] of sortedComponents) {
+    console.log(`  ${component}: ${size.min}kb (${size.gzip}kb gzipped)`);
+  }
+
+  console.log("═".repeat(50));
+  console.log(`\n💾 Size report saved to: ${sizesPath}`);
+
+  return sizes;
+}
+
+async function main() {
+  try {
+    // Check if --tsc flag is passed
+    const shouldGenerateTypes = process.argv.includes("--tsc");
+
+    await clean();
+    // await generateThemes(); // Generate themes before build
+    await build();
+    await buildStyles();
+    await addUseClientDirective();
+
+    if (shouldGenerateTypes) {
+      await generateTypes();
+      console.log("✅ TypeScript declarations generated");
+    } else {
+      console.log("⚡ Skipping TypeScript generation (use --tsc to include)");
+    }
+
+    await logComponentCount();
+    await measureBundleSizes();
+
+    console.log("✨ Build completed successfully!");
+  } catch (error) {
+    console.error("❌ Build failed:", error);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/packages/react/scripts/generate-types.mjs b/packages/react/scripts/generate-types.mjs
new file mode 100644
index 0000000..ed5430c
--- /dev/null
+++ b/packages/react/scripts/generate-types.mjs
@@ -0,0 +1,72 @@
+/* eslint-disable no-console */
+import {execSync} from "child_process";
+import path from "path";
+import {fileURLToPath} from "url";
+
+import fs from "fs-extra";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+
+async function generateTypes() {
+  console.log("📝 Generating TypeScript declarations...");
+
+  // Create a temporary tsconfig for building types only
+  // Don't extend the base tsconfig because it has noEmit: true
+  const tsconfigBuild = {
+    compilerOptions: {
+      target: "ESNext",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["DOM", "DOM.Iterable", "ESNext"],
+      jsx: "react-jsx",
+      declaration: true,
+      declarationMap: false,
+      emitDeclarationOnly: true,
+      outDir: "./dist",
+      rootDir: "./src",
+      skipLibCheck: true,
+      strict: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+      resolveJsonModule: true,
+      isolatedModules: true,
+      allowSyntheticDefaultImports: true,
+      baseUrl: ".",
+    },
+    include: ["src"],
+    exclude: ["node_modules", "**/*.stories.*", "**/*.test.*", "dist", ".rollup.cache"],
+  };
+
+  // Write temporary tsconfig
+  const tsconfigPath = path.join(rootDir, "tsconfig.build.json");
+
+  await fs.writeJson(tsconfigPath, tsconfigBuild, {spaces: 2});
+
+  try {
+    // Run TypeScript compiler
+    console.log("Running tsc with tsconfig.build.json...");
+    execSync("npx tsc --project tsconfig.build.json", {
+      stdio: "inherit",
+      cwd: rootDir,
+    });
+
+    console.log("✅ TypeScript declarations generated successfully");
+  } catch (error) {
+    console.error("❌ Failed to generate TypeScript declarations:", error);
+    throw error;
+  } finally {
+    // Clean up temporary tsconfig
+    await fs.remove(tsconfigPath);
+  }
+}
+
+// Run if called directly
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  generateTypes().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+export {generateTypes};
diff --git a/packages/react/scripts/update-exports.mjs b/packages/react/scripts/update-exports.mjs
new file mode 100644
index 0000000..fda0745
--- /dev/null
+++ b/packages/react/scripts/update-exports.mjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import path from "path";
+import {fileURLToPath} from "url";
+
+import fs from "fs-extra";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+
+const PACKAGE_JSON_PATH = path.join(rootDir, "package.json");
+const COMPONENTS_DIR = path.join(rootDir, "src/components");
+
+/** Directories to skip when scanning components */
+const SKIP_DIRS = new Set(["icons", "utils", "hooks"]);
+
+/**
+ * Scan the components directory and return sorted component names
+ * that have an index.ts file.
+ */
+async function scanComponents() {
+  if (!(await fs.pathExists(COMPONENTS_DIR))) {
+    console.warn("⚠️  Components directory not found:", COMPONENTS_DIR);
+
+    return [];
+  }
+
+  const items = await fs.readdir(COMPONENTS_DIR);
+  const components = [];
+
+  for (const item of items) {
+    if (SKIP_DIRS.has(item)) continue;
+
+    const itemPath = path.join(COMPONENTS_DIR, item);
+    const stat = await fs.stat(itemPath);
+
+    if (stat.isDirectory() && (await fs.pathExists(path.join(itemPath, "index.ts")))) {
+      components.push(item);
+    } else if (stat.isDirectory()) {
+      console.warn(`⚠️  Skipping ${item}: index.ts not found`);
+    }
+  }
+
+  return components.sort();
+}
+
+/**
+ * Generate component exports and write them to package.json.
+ * Called after clean-package has already backed up and cleaned the file.
+ */
+async function generateExports() {
+  const packageJson = await fs.readJson(PACKAGE_JSON_PATH);
+  const components = await scanComponents();
+
+  console.log(`📦 Found ${components.length} components`);
+
+  const exports = {
+    ".": {
+      import: "./dist/index.js",
+      types: "./dist/index.d.ts",
+    },
+    "./package.json": "./package.json",
+    "./styles": {
+      default: "./dist/styles.css",
+      style: "./dist/styles.css",
+    },
+  };
+
+  for (const name of components) {
+    exports[`./${name}`] = {
+      import: `./dist/components/${name}/index.js`,
+      types: `./dist/components/${name}/index.d.ts`,
+    };
+  }
+
+  packageJson.exports = exports;
+
+  await fs.writeJson(PACKAGE_JSON_PATH, packageJson, {spaces: 2});
+  console.log(`✅ Updated package.json exports (${components.length} components)`);
+}
+
+generateExports().catch((error) => {
+  console.error("❌ Failed:", error);
+  process.exit(1);
+});
diff --git a/packages/react/src/components/accordion/accordion.stories.tsx b/packages/react/src/components/accordion/accordion.stories.tsx
new file mode 100644
index 0000000..10a5913
--- /dev/null
+++ b/packages/react/src/components/accordion/accordion.stories.tsx
@@ -0,0 +1,272 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+import {Accordion} from "./index";
+
+export default {
+  argTypes: {
+    allowsMultipleExpanded: {
+      control: {
+        type: "boolean",
+      },
+    },
+    isDisabled: {
+      control: {
+        type: "boolean",
+      },
+    },
+  },
+  component: Accordion,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/Accordion",
+} as Meta<typeof Accordion>;
+
+const defaultArgs: Accordion["RootProps"] = {
+  allowsMultipleExpanded: false,
+  isDisabled: false,
+};
+
+const Wrapper = ({children, className}: {children: React.ReactNode; className?: string}) => (
+  <div className={cn("w-full max-w-md", className)}>{children}</div>
+);
+
+const Template = (props: Accordion["RootProps"]) => (
+  <Wrapper>
+    <Accordion {...props}>
+      {items.map((item) => (
+        <Accordion.Item key={item.title}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <Icon className="mr-3 size-4 shrink-0 text-muted" icon={item.icon} />
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <Icon icon="gravity-ui:chevron-down" />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  </Wrapper>
+);
+
+const CustomTemplate = (props: Accordion["RootProps"]) => (
+  <div className="flex w-full justify-center px-4 py-8">
+    <div className="w-full max-w-2xl">
+      <div className="flex flex-col gap-1">
+        <h2 className="text-2xl font-bold">Frequently Asked Questions</h2>
+        <p className="mb-4 text-lg font-medium text-muted">
+          Everything you need to know about licensing and usage.
+        </p>
+      </div>
+      <div className="mt-2 flex flex-col gap-6">
+        {categories.map((category) => (
+          <div key={category.title}>
+            <p className="text-md mb-2 font-medium text-muted">{category.title}</p>
+            <div key={category.title}>
+              <Accordion {...props} className="w-full" variant="surface">
+                {category.items.map((item) => (
+                  <Accordion.Item key={item.title}>
+                    <Accordion.Heading>
+                      <Accordion.Trigger>
+                        {item.title}
+                        <Accordion.Indicator>
+                          <Icon icon="gravity-ui:chevron-down" />
+                        </Accordion.Indicator>
+                      </Accordion.Trigger>
+                    </Accordion.Heading>
+                    <Accordion.Panel>
+                      <Accordion.Body>{item.content}</Accordion.Body>
+                    </Accordion.Panel>
+                  </Accordion.Item>
+                ))}
+              </Accordion>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  </div>
+);
+
+export const Default = {
+  args: {
+    ...defaultArgs,
+    allowsMultipleExpanded: true,
+  },
+  render: Template,
+};
+
+export const SurfaceVariant = {
+  args: {
+    ...defaultArgs,
+    variant: "surface",
+    allowsMultipleExpanded: true,
+  },
+  render: (args: Accordion["RootProps"]) => (
+    <section className="flex h-screen w-screen items-center justify-center">
+      <Template {...args} />
+    </section>
+  ),
+};
+
+export const Custom = {
+  args: {
+    ...defaultArgs,
+    allowsMultipleExpanded: true,
+  },
+  render: (args: Accordion["RootProps"]) => (
+    <section className="flex h-screen w-screen items-center justify-center">
+      <CustomTemplate {...args} />
+    </section>
+  ),
+};
+
+const WithoutSeparatorTemplate = ({hideSeparator = true, ...props}: Accordion["RootProps"]) => (
+  <Wrapper>
+    <Accordion hideSeparator={hideSeparator} {...props}>
+      {items.map((item) => (
+        <Accordion.Item key={item.title}>
+          <Accordion.Heading>
+            <Accordion.Trigger>
+              {item.icon ? (
+                <Icon className="mr-3 size-4 shrink-0 text-muted" icon={item.icon} />
+              ) : null}
+              {item.title}
+              <Accordion.Indicator>
+                <Icon icon="gravity-ui:chevron-down" />
+              </Accordion.Indicator>
+            </Accordion.Trigger>
+          </Accordion.Heading>
+          <Accordion.Panel>
+            <Accordion.Body>{item.content}</Accordion.Body>
+          </Accordion.Panel>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  </Wrapper>
+);
+
+export const WithoutSeparator = {
+  args: {
+    ...defaultArgs,
+    allowsMultipleExpanded: true,
+  },
+  render: WithoutSeparatorTemplate,
+};
+
+const items = [
+  {
+    content:
+      "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+    icon: "gravity-ui:shopping-bag",
+    title: "How do I place an order?",
+  },
+  {
+    content:
+      "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+    icon: "gravity-ui:receipt",
+    title: "Can I modify or cancel my order?",
+  },
+  {
+    content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
+    icon: "gravity-ui:credit-card",
+    title: "What payment methods do you accept?",
+  },
+  {
+    content:
+      "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.",
+    icon: "gravity-ui:box",
+    title: "How much does shipping cost?",
+  },
+  {
+    content:
+      "Yes, we ship to most countries. Please check our shipping rates and policies for more information.",
+    icon: "gravity-ui:planet-earth",
+    title: "Do you ship internationally?",
+  },
+  {
+    content:
+      "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.",
+    icon: "gravity-ui:arrows-rotate-left",
+    title: "How do I request a refund?",
+  },
+];
+
+const categories = [
+  {
+    title: "General",
+    items: [
+      {
+        title: "How do I place an order?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+      {
+        title: "Can I modify or cancel my order?",
+        content:
+          "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
+      },
+    ],
+  },
+  {
+    title: "Licensing",
+    items: [
+      {
+        title: "How do I purchase a license?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+      {
+        title: "What is the difference between a standard and a pro license?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+    ],
+  },
+  {
+    title: "Usage",
+    items: [
+      {
+        title: "How do I use the HeroUI icon set?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+      {
+        title: "Can I use it with Tailwind CSS?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+    ],
+  },
+  {
+    title: "Support",
+    items: [
+      {
+        title: "How do I get support?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+    ],
+  },
+  {
+    title: "Other",
+    items: [
+      {
+        title: "How do I get support?",
+        content:
+          "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
+      },
+    ],
+  },
+];
diff --git a/packages/react/src/components/accordion/accordion.tsx b/packages/react/src/components/accordion/accordion.tsx
new file mode 100644
index 0000000..ca09f07
--- /dev/null
+++ b/packages/react/src/components/accordion/accordion.tsx
@@ -0,0 +1,241 @@
+"use client";
+
+import type {Booleanish} from "../../utils/assertion";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {AccordionVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {accordionVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button} from "react-aria-components/Button";
+import {
+  Disclosure,
+  Heading as DisclosureHeading,
+  DisclosurePanel,
+  DisclosureStateContext,
+} from "react-aria-components/Disclosure";
+import {DisclosureGroup} from "react-aria-components/DisclosureGroup";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronDown} from "../icons";
+import {SurfaceContext} from "../surface";
+
+const AccordionContext = createContext<{
+  slots?: ReturnType<typeof accordionVariants>;
+  hideSeparator?: boolean;
+}>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Accordion Root
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionRootProps
+  extends ComponentPropsWithRef<typeof DisclosureGroup>, AccordionVariants {
+  hideSeparator?: boolean;
+}
+
+const AccordionRoot = ({
+  children,
+  className,
+  hideSeparator = false,
+  variant,
+  ...props
+}: AccordionRootProps) => {
+  const slots = React.useMemo(() => accordionVariants({variant}), [variant]);
+
+  const content = (
+    <DisclosureGroup
+      className={composeTwRenderProps(className, slots.base())}
+      data-slot="accordion"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </DisclosureGroup>
+  );
+
+  return (
+    <AccordionContext value={{slots, hideSeparator}}>
+      {variant === "surface" ? (
+        // Allows inner components to apply "on-surface" colors for proper contrast
+        <SurfaceContext value={{variant: "default"}}>{content}</SurfaceContext>
+      ) : (
+        content
+      )}
+    </AccordionContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionItem
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionItemProps extends ComponentPropsWithRef<typeof Disclosure> {}
+
+const AccordionItem = ({className, ...props}: AccordionItemProps) => {
+  const {hideSeparator, slots} = use(AccordionContext);
+
+  return (
+    <Disclosure
+      className={composeTwRenderProps(className, slots?.item())}
+      data-hide-separator={hideSeparator ? "true" : undefined}
+      data-slot="accordion-item"
+      {...props}
+    >
+      {props.children}
+    </Disclosure>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionIndicator
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AccordionIndicator = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: AccordionIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof AccordionIndicatorProps<E>>) => {
+  const {slots} = use(AccordionContext);
+  const {isExpanded} = use(DisclosureStateContext)!;
+
+  if (children && React.isValidElement(children)) {
+    return React.cloneElement(
+      children as React.ReactElement<{
+        className?: string;
+        "data-slot"?: "accordion-indicator";
+        "data-expanded"?: Booleanish;
+      }>,
+      {
+        ...(props as any),
+        "data-expanded": dataAttr(isExpanded),
+        className: composeSlotClassName(slots?.indicator, className),
+        "data-slot": "accordion-indicator",
+      },
+    );
+  }
+
+  return (
+    <IconChevronDown
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-expanded={dataAttr(isExpanded)}
+      data-slot="accordion-indicator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionHeading
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionHeadingProps extends ComponentPropsWithRef<typeof DisclosureHeading> {
+  className?: string;
+}
+
+const AccordionHeading = ({className, ...props}: AccordionHeadingProps) => {
+  const {slots} = use(AccordionContext);
+
+  return (
+    <DisclosureHeading
+      className={composeSlotClassName(slots?.heading, className)}
+      data-slot="accordion-heading"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionTrigger
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionTriggerProps extends ComponentPropsWithRef<typeof Button> {}
+
+const AccordionTrigger = ({className, ...props}: AccordionTriggerProps) => {
+  const {slots} = use(AccordionContext);
+
+  return (
+    <Button
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="accordion-trigger"
+      slot="trigger"
+      {...props}
+    >
+      {(values) => (
+        <>{typeof props.children === "function" ? props.children(values) : props.children}</>
+      )}
+    </Button>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionBody
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionBodyProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AccordionBody = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: AccordionBodyProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof AccordionBodyProps<E>>) => {
+  const {slots} = use(AccordionContext);
+
+  return (
+    <dom.div className={slots?.body({})} data-slot="accordion-body" {...(props as any)}>
+      <div className={composeSlotClassName(slots?.bodyInner, className)}>{children}</div>
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionPanel
+ * -----------------------------------------------------------------------------------------------*/
+interface AccordionPanelProps extends ComponentPropsWithRef<typeof DisclosurePanel> {}
+
+const AccordionPanel = ({children, className, ...props}: AccordionPanelProps) => {
+  const {slots} = use(AccordionContext);
+  const {isExpanded} = use(DisclosureStateContext)!;
+
+  return (
+    <DisclosurePanel
+      className={composeTwRenderProps(className, slots?.panel())}
+      data-expanded={dataAttr(isExpanded)}
+      data-slot="accordion-panel"
+      {...props}
+    >
+      {children}
+    </DisclosurePanel>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AccordionRoot,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionPanel,
+  AccordionIndicator,
+  AccordionBody,
+  AccordionHeading,
+};
+
+export type {
+  AccordionRootProps,
+  AccordionItemProps,
+  AccordionTriggerProps,
+  AccordionPanelProps,
+  AccordionIndicatorProps,
+  AccordionBodyProps,
+  AccordionHeadingProps,
+};
diff --git a/packages/react/src/components/accordion/index.ts b/packages/react/src/components/accordion/index.ts
new file mode 100644
index 0000000..dfa07e0
--- /dev/null
+++ b/packages/react/src/components/accordion/index.ts
@@ -0,0 +1,66 @@
+import type {ComponentProps} from "react";
+
+import {
+  AccordionBody,
+  AccordionHeading,
+  AccordionIndicator,
+  AccordionItem,
+  AccordionPanel,
+  AccordionRoot,
+  AccordionTrigger,
+} from "./accordion";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Accordion = Object.assign(AccordionRoot, {
+  Root: AccordionRoot,
+  Item: AccordionItem,
+  Heading: AccordionHeading,
+  Trigger: AccordionTrigger,
+  Panel: AccordionPanel,
+  Indicator: AccordionIndicator,
+  Body: AccordionBody,
+});
+
+export type Accordion = {
+  Props: ComponentProps<typeof AccordionRoot>;
+  RootProps: ComponentProps<typeof AccordionRoot>;
+  ItemProps: ComponentProps<typeof AccordionItem>;
+  HeadingProps: ComponentProps<typeof AccordionHeading>;
+  TriggerProps: ComponentProps<typeof AccordionTrigger>;
+  PanelProps: ComponentProps<typeof AccordionPanel>;
+  IndicatorProps: ComponentProps<typeof AccordionIndicator>;
+  BodyProps: ComponentProps<typeof AccordionBody>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AccordionRoot,
+  AccordionItem,
+  AccordionHeading,
+  AccordionTrigger,
+  AccordionPanel,
+  AccordionIndicator,
+  AccordionBody,
+};
+
+export type {
+  AccordionRootProps,
+  AccordionRootProps as AccordionProps,
+  AccordionItemProps,
+  AccordionHeadingProps,
+  AccordionTriggerProps,
+  AccordionPanelProps,
+  AccordionIndicatorProps,
+  AccordionBodyProps,
+} from "./accordion";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {accordionVariants} from "@heroui/styles";
+
+export type {AccordionVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/alert-dialog/alert-dialog.stories.tsx b/packages/react/src/components/alert-dialog/alert-dialog.stories.tsx
new file mode 100644
index 0000000..39b173f
--- /dev/null
+++ b/packages/react/src/components/alert-dialog/alert-dialog.stories.tsx
@@ -0,0 +1,811 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useCallback, useRef, useState} from "react";
+
+import {useOverlayState} from "../../hooks/use-overlay-state";
+import {Button} from "../button";
+
+import {AlertDialog} from "./index";
+
+export default {
+  argTypes: {},
+  component: AlertDialog,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Overlays/AlertDialog",
+} as Meta<typeof AlertDialog>;
+
+export const Default = () => {
+  return (
+    <AlertDialog>
+      <Button variant="danger">Delete Project</Button>
+      <AlertDialog.Backdrop>
+        <AlertDialog.Container>
+          <AlertDialog.Dialog className="sm:max-w-[400px]">
+            <AlertDialog.CloseTrigger />
+            <AlertDialog.Header>
+              <AlertDialog.Icon status="danger" />
+              <AlertDialog.Heading>Delete project permanently?</AlertDialog.Heading>
+            </AlertDialog.Header>
+            <AlertDialog.Body>
+              <p>
+                This will permanently delete <strong>My Awesome Project</strong> and all of its
+                data. This action cannot be undone.
+              </p>
+            </AlertDialog.Body>
+            <AlertDialog.Footer>
+              <Button slot="close" variant="tertiary">
+                Cancel
+              </Button>
+              <Button slot="close" variant="danger">
+                Delete Project
+              </Button>
+            </AlertDialog.Footer>
+          </AlertDialog.Dialog>
+        </AlertDialog.Container>
+      </AlertDialog.Backdrop>
+    </AlertDialog>
+  );
+};
+
+export const Statuses = () => {
+  const examples = [
+    {
+      actions: {
+        cancel: "Stay Signed In",
+        confirm: "Sign Out",
+      },
+      body: "You'll need to sign in again to access your account. Any unsaved changes will be lost.",
+      classNames: "bg-accent-soft text-accent-soft-foreground",
+      header: "Sign out of your account?",
+      status: "accent",
+      trigger: "Sign Out",
+    },
+    {
+      actions: {
+        cancel: "Not Yet",
+        confirm: "Mark Complete",
+      },
+      body: "This will mark the task as complete and notify all team members. The task will be moved to your completed list.",
+      classNames: "bg-success-soft text-success-soft-foreground",
+      header: "Complete this task?",
+      status: "success",
+      trigger: "Complete Task",
+    },
+    {
+      actions: {
+        cancel: "Keep Editing",
+        confirm: "Discard",
+      },
+      body: "You have unsaved changes that will be permanently lost. Are you sure you want to discard them?",
+      classNames: "bg-warning-soft text-warning-soft-foreground",
+      header: "Discard unsaved changes?",
+      status: "warning",
+      trigger: "Discard Changes",
+    },
+    {
+      actions: {
+        cancel: "Cancel",
+        confirm: "Delete Account",
+      },
+      body: "This will permanently delete your account and remove all your data from our servers. This action is irreversible.",
+      classNames: "bg-danger-soft text-danger-soft-foreground",
+      header: "Delete your account?",
+      status: "danger",
+      trigger: "Delete Account",
+    },
+  ] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {examples.map(({actions, body, classNames, header, status, trigger}) => (
+        <AlertDialog key={status}>
+          <Button className={classNames}>{trigger}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status={status} />
+                  <AlertDialog.Heading>{header}</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>{body}</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    {actions.cancel}
+                  </Button>
+                  <Button slot="close" variant={status === "danger" ? "danger" : "primary"}>
+                    {actions.confirm}
+                  </Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+};
+
+export const Placements = () => {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <AlertDialog key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container placement={placement}>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    {placement === "auto"
+                      ? "Auto Placement"
+                      : `${placement.charAt(0).toUpperCase() + placement.slice(1)} Position`}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {placement === "auto"
+                      ? "Automatically positions at the bottom on mobile and center on desktop for optimal user experience."
+                      : `This dialog is positioned at the ${placement} of the viewport. Critical confirmations are typically centered for maximum attention.`}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+};
+
+export const Sizes = () => {
+  const sizes = ["xs", "sm", "md", "lg", "cover"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <AlertDialog key={size}>
+          <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button>
+          <AlertDialog.Backdrop>
+            <AlertDialog.Container size={size}>
+              <AlertDialog.Dialog>
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon className="bg-default text-foreground">
+                    <Icon className="size-5" icon="gravity-ui:rocket" />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>
+                    Size: {size.charAt(0).toUpperCase() + size.slice(1)}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        This alert dialog uses the <code>cover</code> size variant. It spans the
+                        full screen with margins: 16px on mobile and 40px on desktop. Maintains
+                        rounded corners and standard padding. Perfect for critical confirmations
+                        that need maximum width while preserving alert dialog aesthetics.
+                      </>
+                    ) : (
+                      <>
+                        This alert dialog uses the <code>{size}</code> size variant. On mobile
+                        devices, all sizes adapt to near full-width for optimal viewing. On desktop,
+                        each size provides a different maximum width to suit various content needs.
+                      </>
+                    )}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+};
+
+export const BackdropVariants = () => {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <AlertDialog key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <AlertDialog.Backdrop variant={variant}>
+            <AlertDialog.Container>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent" />
+                  <AlertDialog.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p>
+                    {variant === "opaque"
+                      ? "An opaque dark backdrop that completely obscures the background, providing maximum focus on the dialog."
+                      : variant === "blur"
+                        ? "A blurred backdrop that softly obscures the background while maintaining visual context."
+                        : "A transparent backdrop that keeps the background fully visible, useful for less critical confirmations."}
+                  </p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+};
+
+export const CustomIcon = () => (
+  <AlertDialog>
+    <Button variant="secondary">Reset Password</Button>
+    <AlertDialog.Backdrop>
+      <AlertDialog.Container>
+        <AlertDialog.Dialog className="sm:max-w-[400px]">
+          <AlertDialog.CloseTrigger />
+          <AlertDialog.Header>
+            <AlertDialog.Icon status="warning">
+              <Icon className="size-5" icon="gravity-ui:lock-open" />
+            </AlertDialog.Icon>
+            <AlertDialog.Heading>Reset your password?</AlertDialog.Heading>
+          </AlertDialog.Header>
+          <AlertDialog.Body>
+            <p>
+              We'll send a password reset link to your email address. You'll need to create a new
+              password to regain access to your account.
+            </p>
+          </AlertDialog.Body>
+          <AlertDialog.Footer>
+            <Button slot="close" variant="tertiary">
+              Cancel
+            </Button>
+            <Button slot="close">Send Reset Link</Button>
+          </AlertDialog.Footer>
+        </AlertDialog.Dialog>
+      </AlertDialog.Container>
+    </AlertDialog.Backdrop>
+  </AlertDialog>
+);
+
+export const CustomBackdrop = () => (
+  <AlertDialog>
+    <Button variant="danger">Delete Account</Button>
+    <AlertDialog.Backdrop
+      className="bg-linear-to-t from-red-950/90 via-red-950/50 to-transparent dark:from-red-950/95 dark:via-red-950/60"
+      variant="blur"
+    >
+      <AlertDialog.Container>
+        <AlertDialog.Dialog className="sm:max-w-[420px]">
+          <AlertDialog.CloseTrigger />
+          <AlertDialog.Header className="items-center text-center">
+            <AlertDialog.Icon status="danger">
+              <Icon className="size-5" icon="gravity-ui:triangle-exclamation" />
+            </AlertDialog.Icon>
+            <AlertDialog.Heading>Permanently delete your account?</AlertDialog.Heading>
+          </AlertDialog.Header>
+          <AlertDialog.Body>
+            <p>
+              This action cannot be undone. All your data, settings, and content will be permanently
+              removed from our servers. The dramatic red backdrop emphasizes the severity and
+              irreversibility of this decision.
+            </p>
+          </AlertDialog.Body>
+          <AlertDialog.Footer className="flex-col-reverse">
+            <Button className="w-full" slot="close">
+              Keep Account
+            </Button>
+            <Button className="w-full" slot="close" variant="danger">
+              Delete Forever
+            </Button>
+          </AlertDialog.Footer>
+        </AlertDialog.Dialog>
+      </AlertDialog.Container>
+    </AlertDialog.Backdrop>
+  </AlertDialog>
+);
+
+export const DismissBehavior = () => (
+  <div className="flex max-w-sm flex-col gap-6">
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">isDismissable</h3>
+      <p className="text-sm text-muted">
+        Controls whether the alert dialog can be dismissed by clicking the overlay backdrop. Alert
+        dialogs typically require explicit action, so this defaults to <code>false</code>. Set to{" "}
+        <code>true</code> for less critical confirmations.
+      </p>
+      <AlertDialog>
+        <Button variant="secondary">Open Alert Dialog</Button>
+        <AlertDialog.Backdrop isDismissable={false}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="danger">
+                  <Icon className="size-5" icon="gravity-ui:circle-info" />
+                </AlertDialog.Icon>
+                <AlertDialog.Heading>isDismissable = false</AlertDialog.Heading>
+                <p className="text-sm leading-5 text-muted">
+                  Clicking the backdrop won't close this alert dialog
+                </p>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  Try clicking outside this alert dialog on the overlay - it won't close. You must
+                  use the action buttons to dismiss it.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </AlertDialog>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+      <p className="text-sm text-muted">
+        Controls whether the ESC key can dismiss the alert dialog. Alert dialogs typically require
+        explicit action, so this defaults to <code>true</code>. When set to <code>false</code>, the
+        ESC key will be enabled.
+      </p>
+      <AlertDialog>
+        <Button variant="secondary">Open Alert Dialog</Button>
+        <AlertDialog.Backdrop isKeyboardDismissDisabled>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="accent">
+                  <Icon className="size-5" icon="gravity-ui:circle-info" />
+                </AlertDialog.Icon>
+                <AlertDialog.Heading>isKeyboardDismissDisabled = true</AlertDialog.Heading>
+                <p className="text-sm leading-5 text-muted">ESC key is disabled</p>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  Press ESC - nothing happens. You must use the action buttons to dismiss this alert
+                  dialog.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </AlertDialog>
+    </div>
+  </div>
+);
+
+export const CloseMethods = () => (
+  <div className="flex max-w-2xl flex-col gap-8">
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">Using slot="close"</h3>
+      <p className="text-sm text-muted">
+        The simplest way to close a dialog. Add <code>slot="close"</code> to any Button component
+        within the dialog. When clicked, it will automatically close the dialog.
+      </p>
+      <AlertDialog>
+        <Button variant="secondary">Open Dialog</Button>
+        <AlertDialog.Backdrop>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="accent" />
+                <AlertDialog.Heading>Using slot="close"</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  Click either button below - both have <code>slot="close"</code> and will close the
+                  dialog automatically.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </AlertDialog>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">Using Dialog render props</h3>
+      <p className="text-sm text-muted">
+        Access the <code>close</code> method from the Dialog's render props. This gives you full
+        control over when and how to close the dialog, allowing you to add custom logic before
+        closing.
+      </p>
+      <AlertDialog>
+        <Button variant="secondary">Open Dialog</Button>
+        <AlertDialog.Backdrop>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              {(renderProps) => (
+                <>
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="success" />
+                    <AlertDialog.Heading>Using Dialog render props</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p>
+                      The buttons below use the <code>close</code> method from render props. You can
+                      add validation or other logic before calling <code>renderProps.close()</code>.
+                    </p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button variant="tertiary" onPress={() => renderProps.close()}>
+                      Cancel
+                    </Button>
+                    <Button onPress={() => renderProps.close()}>Confirm</Button>
+                  </AlertDialog.Footer>
+                </>
+              )}
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </AlertDialog>
+    </div>
+  </div>
+);
+
+export const Controlled = () => {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Control the alert dialog using React's <code className="text-foreground">useState</code>{" "}
+          hook for simple state management. Perfect for basic use cases.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              Open Dialog
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="accent" />
+                <AlertDialog.Heading>Controlled with useState()</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  This alert dialog is controlled by React's <code>useState</code> hook. Pass{" "}
+                  <code>isOpen</code> and <code>onOpenChange</code> props to manage the dialog state
+                  externally.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API
+          with convenient methods like <code>open()</code>, <code>close()</code>, and{" "}
+          <code>toggle()</code>.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              Open Dialog
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <AlertDialog.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <AlertDialog.Container>
+            <AlertDialog.Dialog className="sm:max-w-[400px]">
+              <AlertDialog.CloseTrigger />
+              <AlertDialog.Header>
+                <AlertDialog.Icon status="success" />
+                <AlertDialog.Heading>Controlled with useOverlayState()</AlertDialog.Heading>
+              </AlertDialog.Header>
+              <AlertDialog.Body>
+                <p>
+                  The <code>useOverlayState</code> hook provides dedicated methods for common
+                  operations. No need to manually create callbacks—just use{" "}
+                  <code>state.open()</code>, <code>state.close()</code>, or{" "}
+                  <code>state.toggle()</code>.
+                </p>
+              </AlertDialog.Body>
+              <AlertDialog.Footer>
+                <Button slot="close" variant="tertiary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </AlertDialog.Footer>
+            </AlertDialog.Dialog>
+          </AlertDialog.Container>
+        </AlertDialog.Backdrop>
+      </div>
+    </div>
+  );
+};
+
+export const CustomTrigger = () => (
+  <AlertDialog>
+    <AlertDialog.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+      <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger-soft-foreground">
+        <Icon className="size-6" icon="gravity-ui:trash-bin" />
+      </div>
+      <div className="flex flex-1 flex-col gap-0.5">
+        <p className="text-sm font-semibold">Delete Item</p>
+        <p className="text-xs text-muted">Permanently remove this item</p>
+      </div>
+    </AlertDialog.Trigger>
+    <AlertDialog.Backdrop>
+      <AlertDialog.Container>
+        <AlertDialog.Dialog className="sm:max-w-[400px]">
+          <AlertDialog.CloseTrigger />
+          <AlertDialog.Header>
+            <AlertDialog.Icon status="danger">
+              <Icon className="size-5" icon="gravity-ui:trash-bin" />
+            </AlertDialog.Icon>
+            <AlertDialog.Heading>Delete this item?</AlertDialog.Heading>
+          </AlertDialog.Header>
+          <AlertDialog.Body>
+            <p>
+              Use <code>AlertDialog.Trigger</code> to create custom trigger elements beyond standard
+              buttons. This example shows a card-style trigger with icons and descriptive text.
+            </p>
+          </AlertDialog.Body>
+          <AlertDialog.Footer>
+            <Button slot="close" variant="tertiary">
+              Cancel
+            </Button>
+            <Button slot="close" variant="danger">
+              Delete Item
+            </Button>
+          </AlertDialog.Footer>
+        </AlertDialog.Dialog>
+      </AlertDialog.Container>
+    </AlertDialog.Backdrop>
+  </AlertDialog>
+);
+
+export const CustomAnimations = () => {
+  const animations = [
+    {
+      name: "Kinematic Scale",
+      description:
+        "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Alert Dialogs and Modals.",
+      icon: "gravity-ui:sparkles",
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+    },
+    {
+      name: "Fluid Slide",
+      description:
+        "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.",
+      icon: "gravity-ui:arrow-up-from-line",
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => (
+        <AlertDialog key={name}>
+          <Button variant="secondary">{name}</Button>
+          <AlertDialog.Backdrop className={classNames.backdrop}>
+            <AlertDialog.Container className={classNames.container}>
+              <AlertDialog.Dialog className="sm:max-w-[400px]">
+                <AlertDialog.CloseTrigger />
+                <AlertDialog.Header>
+                  <AlertDialog.Icon status="accent">
+                    <Icon className="size-5" icon={icon} />
+                  </AlertDialog.Icon>
+                  <AlertDialog.Heading>{name} Animation</AlertDialog.Heading>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <p className="mt-1">{description}</p>
+                </AlertDialog.Body>
+                <AlertDialog.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Close
+                  </Button>
+                  <Button slot="close">Try Again</Button>
+                </AlertDialog.Footer>
+              </AlertDialog.Dialog>
+            </AlertDialog.Container>
+          </AlertDialog.Backdrop>
+        </AlertDialog>
+      ))}
+    </div>
+  );
+};
+
+export const CustomPortal = () => {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          Render alert dialogs inside a custom container instead of <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the
+          container to create a new stacking context.
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <AlertDialog>
+            <Button>Open Alert Dialog</Button>
+            <AlertDialog.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <AlertDialog.Container className="h-full max-h-full">
+                <AlertDialog.Dialog className="h-full max-h-full sm:max-w-md">
+                  <AlertDialog.CloseTrigger />
+                  <AlertDialog.Header>
+                    <AlertDialog.Icon status="accent" />
+                    <AlertDialog.Heading>Custom Portal</AlertDialog.Heading>
+                  </AlertDialog.Header>
+                  <AlertDialog.Body>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                  </AlertDialog.Body>
+                  <AlertDialog.Footer>
+                    <Button slot="close" variant="tertiary">
+                      Cancel
+                    </Button>
+                    <Button slot="close">Confirm</Button>
+                  </AlertDialog.Footer>
+                </AlertDialog.Dialog>
+              </AlertDialog.Container>
+            </AlertDialog.Backdrop>
+          </AlertDialog>
+        )}
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react/src/components/alert-dialog/alert-dialog.tsx b/packages/react/src/components/alert-dialog/alert-dialog.tsx
new file mode 100644
index 0000000..ff8b7d7
--- /dev/null
+++ b/packages/react/src/components/alert-dialog/alert-dialog.tsx
@@ -0,0 +1,382 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {AlertDialogVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, HTMLAttributes, ReactNode} from "react";
+import type {ButtonProps as ButtonPrimitiveProps} from "react-aria-components/Button";
+import type {DialogProps as DialogPrimitiveProps} from "react-aria-components/Dialog";
+
+import {alertDialogVariants} from "@heroui/styles";
+import {createContext, use, useMemo} from "react";
+import {
+  DialogTrigger as AlertDialogTriggerPrimitive,
+  Dialog as DialogPrimitive,
+  Heading as HeadingPrimitive,
+} from "react-aria-components/Dialog";
+import {
+  ModalOverlay as ModalOverlayPrimitive,
+  Modal as ModalPrimitive,
+  Pressable as PressablePrimitive,
+} from "react-aria-components/Modal";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CloseButton} from "../close-button";
+import {DangerIcon, InfoIcon, SuccessIcon, WarningIcon} from "../icons";
+
+type AlertDialogPlacement = "auto" | "top" | "center" | "bottom";
+
+type AlertDialogStatus = "default" | "accent" | "success" | "warning" | "danger";
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Context
+ * -----------------------------------------------------------------------------------------------*/
+type AlertDialogContext = {
+  slots?: ReturnType<typeof alertDialogVariants>;
+  placement?: AlertDialogPlacement;
+};
+
+const AlertDialogContext = createContext<AlertDialogContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Root
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogRootProps extends ComponentPropsWithRef<typeof AlertDialogTriggerPrimitive> {}
+
+const AlertDialogRoot = ({children, ...props}: AlertDialogRootProps) => {
+  const alertDialogContext = useMemo<AlertDialogContext>(
+    () => ({slots: alertDialogVariants(), placement: undefined}),
+    [],
+  );
+
+  return (
+    <AlertDialogContext value={alertDialogContext}>
+      <AlertDialogTriggerPrimitive data-slot="alert-dialog-root" {...props}>
+        {children}
+      </AlertDialogTriggerPrimitive>
+    </AlertDialogContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogTriggerProps extends HTMLAttributes<HTMLDivElement> {}
+
+const AlertDialogTrigger = ({children, className, ...props}: AlertDialogTriggerProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <PressablePrimitive>
+      <div
+        className={composeSlotClassName(slots?.trigger, className)}
+        data-slot="alert-dialog-trigger"
+        role="button"
+        {...props}
+      >
+        {children}
+      </div>
+    </PressablePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Backdrop
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogBackdropProps extends ComponentPropsWithRef<typeof ModalOverlayPrimitive> {
+  variant?: AlertDialogVariants["variant"];
+  /**
+   * Whether to close the alert dialog when the user interacts outside it.
+   * Alert dialogs typically require explicit action, so this defaults to false.
+   * @default false
+   */
+  isDismissable?: boolean;
+  /**
+   * Whether pressing the escape key to close the modal should be disabled.
+   * Alert dialogs typically require explicit action, so this defaults to true.
+   * @default true
+   */
+  isKeyboardDismissDisabled?: boolean;
+}
+
+const AlertDialogBackdrop = ({
+  children,
+  className,
+  isDismissable = false,
+  isKeyboardDismissDisabled = true,
+  onClick,
+  variant,
+  ...props
+}: AlertDialogBackdropProps) => {
+  const {slots: contextSlots} = use(AlertDialogContext);
+
+  const updatedSlots = useMemo(() => alertDialogVariants({variant}), [variant]);
+
+  const updatedModalContext = useMemo<AlertDialogContext>(
+    () => ({slots: {...contextSlots, ...updatedSlots}}),
+    [contextSlots, updatedSlots],
+  );
+
+  return (
+    <ModalOverlayPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.backdrop())}
+      data-slot="alert-dialog-backdrop"
+      isDismissable={isDismissable}
+      isKeyboardDismissDisabled={isKeyboardDismissDisabled}
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick?.(e);
+      }}
+      {...props}
+    >
+      {(renderProps) => (
+        <AlertDialogContext value={updatedModalContext}>
+          {typeof children === "function" ? children(renderProps) : children}{" "}
+        </AlertDialogContext>
+      )}
+    </ModalOverlayPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Container
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogContainerProps extends Omit<
+  ComponentPropsWithRef<typeof ModalPrimitive>,
+  Exclude<keyof AlertDialogBackdropProps, "children" | "className">
+> {
+  /**
+   * The placement of the alert dialog on the screen.
+   * @default "auto"
+   */
+  placement?: AlertDialogPlacement;
+  size?: AlertDialogVariants["size"];
+}
+
+const AlertDialogContainer = ({
+  children,
+  className,
+  placement = "auto",
+  size,
+  ...props
+}: AlertDialogContainerProps) => {
+  const {slots: contextSlots} = use(AlertDialogContext);
+
+  const updatedSlots = useMemo(() => alertDialogVariants({size}), [size]);
+
+  const updatedContext = useMemo<AlertDialogContext>(
+    () => ({placement, slots: {...contextSlots, ...updatedSlots}}),
+    [placement, contextSlots, updatedSlots],
+  );
+
+  return (
+    <ModalPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.container())}
+      data-placement={placement}
+      data-slot="alert-dialog-container"
+      {...props}
+    >
+      {(renderProps) => (
+        <AlertDialogContext value={updatedContext}>
+          {typeof children === "function" ? children(renderProps) : children}
+        </AlertDialogContext>
+      )}
+    </ModalPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Dialog
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogDialogProps extends DialogPrimitiveProps {}
+
+const AlertDialogDialog = ({children, className, ...props}: AlertDialogDialogProps) => {
+  const {placement, slots} = use(AlertDialogContext);
+
+  return (
+    <DialogPrimitive
+      className={composeSlotClassName(slots?.dialog, className)}
+      data-placement={placement}
+      data-slot="alert-dialog-dialog"
+      role="alertdialog"
+      {...props}
+    >
+      {children}
+    </DialogPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Header
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogHeaderProps extends HTMLAttributes<HTMLDivElement> {}
+
+const AlertDialogHeader = ({children, className, ...props}: AlertDialogHeaderProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="alert-dialog-header"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Heading
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogHeadingProps extends ComponentPropsWithRef<typeof HeadingPrimitive> {}
+
+const AlertDialogHeading = ({children, className, ...props}: AlertDialogHeadingProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <HeadingPrimitive
+      className={composeSlotClassName(slots?.heading, className)}
+      data-slot="alert-dialog-heading"
+      slot="title"
+      {...props}
+    >
+      {children}
+    </HeadingPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Body
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogBodyProps extends HTMLAttributes<HTMLDivElement> {}
+
+const AlertDialogBody = ({children, className, ...props}: AlertDialogBodyProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.body, className)}
+      data-slot="alert-dialog-body"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Footer
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogFooterProps extends HTMLAttributes<HTMLDivElement> {}
+
+const AlertDialogFooter = ({children, className, ...props}: AlertDialogFooterProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.footer, className)}
+      data-slot="alert-dialog-footer"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Icon
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  /**
+   * The semantic status of the icon, affects background color and default icon
+   * @default "danger"
+   */
+  status?: AlertDialogStatus;
+}
+
+const AlertDialogIcon = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  status = "danger",
+  ...props
+}: AlertDialogIconProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof AlertDialogIconProps<E>>) => {
+  const slots = useMemo(() => alertDialogVariants({status}), [status]);
+
+  const getDefaultIcon = () => {
+    switch (status) {
+      case "default":
+        return <InfoIcon data-slot="alert-dialog-default-icon" />;
+      case "accent":
+        return <InfoIcon data-slot="alert-dialog-default-icon" />;
+      case "success":
+        return <SuccessIcon data-slot="alert-dialog-default-icon" />;
+      case "warning":
+        return <WarningIcon data-slot="alert-dialog-default-icon" />;
+      case "danger":
+        return <DangerIcon data-slot="alert-dialog-default-icon" />;
+      default:
+        return <DangerIcon data-slot="alert-dialog-default-icon" />;
+    }
+  };
+
+  return (
+    <dom.div className={slots?.icon({className})} data-slot="alert-dialog-icon" {...(props as any)}>
+      {children ?? getDefaultIcon()}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Close Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface AlertDialogCloseTriggerProps extends ButtonPrimitiveProps {}
+
+const AlertDialogCloseTrigger = ({className, ...rest}: AlertDialogCloseTriggerProps) => {
+  const {slots} = use(AlertDialogContext);
+
+  return (
+    <CloseButton
+      className={composeTwRenderProps(className, slots?.closeTrigger())}
+      data-slot="alert-dialog-close-trigger"
+      slot="close"
+      {...rest}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AlertDialogRoot,
+  AlertDialogTrigger,
+  AlertDialogBackdrop,
+  AlertDialogContainer,
+  AlertDialogDialog,
+  AlertDialogHeader,
+  AlertDialogHeading,
+  AlertDialogBody,
+  AlertDialogFooter,
+  AlertDialogIcon,
+  AlertDialogCloseTrigger,
+};
+
+export type {
+  AlertDialogRootProps,
+  AlertDialogTriggerProps,
+  AlertDialogBackdropProps,
+  AlertDialogContainerProps,
+  AlertDialogDialogProps,
+  AlertDialogHeaderProps,
+  AlertDialogHeadingProps,
+  AlertDialogBodyProps,
+  AlertDialogFooterProps,
+  AlertDialogIconProps,
+  AlertDialogCloseTriggerProps,
+  AlertDialogStatus,
+};
diff --git a/packages/react/src/components/alert-dialog/index.ts b/packages/react/src/components/alert-dialog/index.ts
new file mode 100644
index 0000000..3fa8efb
--- /dev/null
+++ b/packages/react/src/components/alert-dialog/index.ts
@@ -0,0 +1,86 @@
+import type {ComponentProps} from "react";
+
+import {
+  AlertDialogBackdrop,
+  AlertDialogBody,
+  AlertDialogCloseTrigger,
+  AlertDialogContainer,
+  AlertDialogDialog,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogHeading,
+  AlertDialogIcon,
+  AlertDialogRoot,
+  AlertDialogTrigger,
+} from "./alert-dialog";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const AlertDialog = Object.assign(AlertDialogRoot, {
+  Root: AlertDialogRoot,
+  Trigger: AlertDialogTrigger,
+  Backdrop: AlertDialogBackdrop,
+  Container: AlertDialogContainer,
+  Dialog: AlertDialogDialog,
+  Header: AlertDialogHeader,
+  Heading: AlertDialogHeading,
+  Body: AlertDialogBody,
+  Footer: AlertDialogFooter,
+  Icon: AlertDialogIcon,
+  CloseTrigger: AlertDialogCloseTrigger,
+});
+
+export type AlertDialog = {
+  Props: ComponentProps<typeof AlertDialogRoot>;
+  RootProps: ComponentProps<typeof AlertDialogRoot>;
+  TriggerProps: ComponentProps<typeof AlertDialogTrigger>;
+  BackdropProps: ComponentProps<typeof AlertDialogBackdrop>;
+  ContainerProps: ComponentProps<typeof AlertDialogContainer>;
+  DialogProps: ComponentProps<typeof AlertDialogDialog>;
+  HeaderProps: ComponentProps<typeof AlertDialogHeader>;
+  HeadingProps: ComponentProps<typeof AlertDialogHeading>;
+  BodyProps: ComponentProps<typeof AlertDialogBody>;
+  FooterProps: ComponentProps<typeof AlertDialogFooter>;
+  IconProps: ComponentProps<typeof AlertDialogIcon>;
+  CloseTriggerProps: ComponentProps<typeof AlertDialogCloseTrigger>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AlertDialogRoot,
+  AlertDialogTrigger,
+  AlertDialogBackdrop,
+  AlertDialogContainer,
+  AlertDialogDialog,
+  AlertDialogHeader,
+  AlertDialogHeading,
+  AlertDialogBody,
+  AlertDialogFooter,
+  AlertDialogIcon,
+  AlertDialogCloseTrigger,
+};
+
+export type {
+  AlertDialogRootProps,
+  AlertDialogRootProps as AlertDialogProps,
+  AlertDialogTriggerProps,
+  AlertDialogBackdropProps,
+  AlertDialogContainerProps,
+  AlertDialogDialogProps,
+  AlertDialogHeaderProps,
+  AlertDialogHeadingProps,
+  AlertDialogBodyProps,
+  AlertDialogFooterProps,
+  AlertDialogIconProps,
+  AlertDialogCloseTriggerProps,
+} from "./alert-dialog";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {alertDialogVariants} from "@heroui/styles";
+
+export type {AlertDialogVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/alert/alert.stories.tsx b/packages/react/src/components/alert/alert.stories.tsx
new file mode 100644
index 0000000..8387d45
--- /dev/null
+++ b/packages/react/src/components/alert/alert.stories.tsx
@@ -0,0 +1,149 @@
+import React from "react";
+
+import {Button} from "../button";
+import {CloseButton} from "../close-button";
+import {Spinner} from "../spinner";
+
+import {Alert} from "./index";
+
+export default {
+  argTypes: {},
+  component: Alert,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Feedback/Alert",
+};
+
+const defaultArgs = {};
+
+const Template = () => (
+  <div className="grid w-full max-w-xl gap-4">
+    {/* Default - General information */}
+    <Alert>
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>New features available</Alert.Title>
+        <Alert.Description>
+          Check out our latest updates including dark mode support and improved accessibility
+          features.
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+
+    {/* Accent - Important information with action */}
+    <Alert status="accent">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Update available</Alert.Title>
+        <Alert.Description>
+          A new version of the application is available. Please refresh to get the latest features
+          and bug fixes.
+        </Alert.Description>
+        <Button className="mt-2 sm:hidden" size="sm" variant="primary">
+          Refresh
+        </Button>
+      </Alert.Content>
+      <Button className="hidden sm:block" size="sm" variant="primary">
+        Refresh
+      </Button>
+    </Alert>
+
+    {/* Success - Confirmation */}
+    <Alert status="success">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Payment successful</Alert.Title>
+        <Alert.Description>
+          Your payment of $49.99 has been processed. A confirmation email has been sent to your
+          inbox.
+        </Alert.Description>
+        <Button className="mt-2 sm:hidden" size="sm" variant="secondary">
+          View Receipt
+        </Button>
+      </Alert.Content>
+      <Button className="hidden sm:block" size="sm" variant="secondary">
+        View Receipt
+      </Button>
+    </Alert>
+
+    {/* Warning - Attention needed */}
+    <Alert status="warning">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Storage almost full</Alert.Title>
+        <Alert.Description>
+          You're using 90% of your storage quota. Consider upgrading your plan or removing unused
+          files to avoid service interruption.
+        </Alert.Description>
+        <Button className="mt-2 sm:hidden" size="sm" variant="secondary">
+          Manage Storage
+        </Button>
+      </Alert.Content>
+      <Button className="hidden sm:block" size="sm" variant="secondary">
+        Manage Storage
+      </Button>
+    </Alert>
+
+    {/* Danger - Error with detailed steps */}
+    <Alert status="danger">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Unable to connect to server</Alert.Title>
+        <Alert.Description>
+          We're experiencing connection issues. Please try the following:
+          <ul className="mt-2 list-inside list-disc space-y-1 text-sm">
+            <li>Check your internet connection</li>
+            <li>Refresh the page</li>
+            <li>Clear your browser cache</li>
+          </ul>
+        </Alert.Description>
+        <Button className="mt-2 sm:hidden" size="sm" variant="danger">
+          Retry
+        </Button>
+      </Alert.Content>
+      <Button className="hidden sm:block" size="sm" variant="danger">
+        Retry
+      </Button>
+    </Alert>
+
+    {/* Without description */}
+    <Alert status="success">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Profile updated successfully</Alert.Title>
+      </Alert.Content>
+      <CloseButton />
+    </Alert>
+
+    {/* Custom indicator - Loading state */}
+    <Alert status="accent">
+      <Alert.Indicator>
+        <Spinner size="sm" />
+      </Alert.Indicator>
+      <Alert.Content>
+        <Alert.Title>Processing your request</Alert.Title>
+        <Alert.Description>
+          Please wait while we sync your data. This may take a few moments.
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+
+    {/* Without close button */}
+    <Alert status="warning">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>Scheduled maintenance</Alert.Title>
+        <Alert.Description>
+          Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for
+          scheduled maintenance.
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  </div>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
diff --git a/packages/react/src/components/alert/alert.tsx b/packages/react/src/components/alert/alert.tsx
new file mode 100644
index 0000000..109e0e5
--- /dev/null
+++ b/packages/react/src/components/alert/alert.tsx
@@ -0,0 +1,202 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {AlertVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {alertVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {DangerIcon, InfoIcon, SuccessIcon, WarningIcon} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Context
+ * --------------------------------------------------------------------------------------------- */
+type AlertContext = {
+  slots?: ReturnType<typeof alertVariants>;
+  status?: "default" | "accent" | "success" | "warning" | "danger";
+};
+
+const AlertContext = createContext<AlertContext>({});
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Root
+ * --------------------------------------------------------------------------------------------- */
+interface AlertRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+  /** Alert status. */
+  status?: AlertVariants["status"];
+}
+
+const AlertRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  status,
+  ...rest
+}: AlertRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof AlertRootProps<E>>) => {
+  const slots = React.useMemo(() => alertVariants({status}), [status]);
+
+  return (
+    <AlertContext value={{slots, status}}>
+      <SurfaceContext
+        value={{
+          variant: "default" as SurfaceVariants["variant"],
+        }}
+      >
+        <dom.div className={slots?.base({className})} data-slot="alert-root" {...(rest as any)}>
+          {children}
+        </dom.div>
+      </SurfaceContext>
+    </AlertContext>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Indicator
+ * --------------------------------------------------------------------------------------------- */
+interface AlertIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AlertIndicator = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...rest
+}: AlertIndicatorProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof AlertIndicatorProps<E>>) => {
+  const {slots, status} = use(AlertContext);
+
+  // Map status to default icons
+  const getDefaultIcon = () => {
+    switch (status) {
+      case "accent":
+        return <InfoIcon data-slot="alert-default-icon" />;
+      case "success":
+        return <SuccessIcon data-slot="alert-default-icon" />;
+      case "warning":
+        return <WarningIcon data-slot="alert-default-icon" />;
+      case "danger":
+        return <DangerIcon data-slot="alert-default-icon" />;
+      default:
+        return <InfoIcon data-slot="alert-default-icon" />;
+    }
+  };
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="alert-indicator"
+      {...(rest as any)}
+    >
+      {children ?? getDefaultIcon()}
+    </dom.div>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Content
+ * --------------------------------------------------------------------------------------------- */
+interface AlertContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AlertContent = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...rest
+}: AlertContentProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof AlertContentProps<E>>) => {
+  const {slots} = use(AlertContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.content, className)}
+      data-slot="alert-content"
+      {...(rest as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Title
+ * --------------------------------------------------------------------------------------------- */
+interface AlertTitleProps<E extends keyof React.JSX.IntrinsicElements = "p"> extends DOMRenderProps<
+  E,
+  undefined
+> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AlertTitle = <E extends keyof React.JSX.IntrinsicElements = "p">({
+  children,
+  className,
+  ...rest
+}: AlertTitleProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof AlertTitleProps<E>>) => {
+  const {slots} = use(AlertContext);
+
+  return (
+    <dom.p
+      className={composeSlotClassName(slots?.title, className)}
+      data-slot="alert-title"
+      {...(rest as any)}
+    >
+      {children}
+    </dom.p>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Alert Description
+ * --------------------------------------------------------------------------------------------- */
+interface AlertDescriptionProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AlertDescription = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...rest
+}: AlertDescriptionProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof AlertDescriptionProps<E>>) => {
+  const {slots} = use(AlertContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.description, className)}
+      data-slot="alert-description"
+      {...(rest as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Exports
+ * --------------------------------------------------------------------------------------------- */
+export {AlertRoot, AlertIndicator, AlertContent, AlertTitle, AlertDescription};
+
+export type {
+  AlertRootProps,
+  AlertIndicatorProps,
+  AlertContentProps,
+  AlertTitleProps,
+  AlertDescriptionProps,
+};
diff --git a/packages/react/src/components/alert/index.ts b/packages/react/src/components/alert/index.ts
new file mode 100644
index 0000000..bf3ba14
--- /dev/null
+++ b/packages/react/src/components/alert/index.ts
@@ -0,0 +1,44 @@
+import type {ComponentProps} from "react";
+
+import {AlertContent, AlertDescription, AlertIndicator, AlertRoot, AlertTitle} from "./alert";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Alert = Object.assign(AlertRoot, {
+  Root: AlertRoot,
+  Indicator: AlertIndicator,
+  Content: AlertContent,
+  Title: AlertTitle,
+  Description: AlertDescription,
+});
+
+export type Alert = {
+  Props: ComponentProps<typeof AlertRoot>;
+  RootProps: ComponentProps<typeof AlertRoot>;
+  IndicatorProps: ComponentProps<typeof AlertIndicator>;
+  ContentProps: ComponentProps<typeof AlertContent>;
+  TitleProps: ComponentProps<typeof AlertTitle>;
+  DescriptionProps: ComponentProps<typeof AlertDescription>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {AlertRoot, AlertIndicator, AlertContent, AlertTitle, AlertDescription};
+
+export type {
+  AlertRootProps,
+  AlertRootProps as AlertProps,
+  AlertIndicatorProps,
+  AlertContentProps,
+  AlertTitleProps,
+  AlertDescriptionProps,
+} from "./alert";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {alertVariants} from "@heroui/styles";
+
+export type {AlertVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/autocomplete/autocomplete.stories.tsx b/packages/react/src/components/autocomplete/autocomplete.stories.tsx
new file mode 100644
index 0000000..7b56730
--- /dev/null
+++ b/packages/react/src/components/autocomplete/autocomplete.stories.tsx
@@ -0,0 +1,1859 @@
+import type {Key} from "@heroui/react";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {useAsyncList} from "@react-stately/data";
+import React, {useState} from "react";
+import {useFilter} from "react-aria-components/Autocomplete";
+import {ListLayout, Virtualizer} from "react-aria-components/Virtualizer";
+import {cn} from "tailwind-variants";
+
+import {Avatar, AvatarFallback, AvatarImage} from "../avatar";
+import {Button} from "../button";
+import {Description} from "../description";
+import {EmptyState} from "../empty-state";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Header} from "../header";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {SearchField} from "../search-field";
+import {Separator} from "../separator";
+import {Spinner} from "../spinner";
+import {Surface} from "../surface";
+import {Tag} from "../tag";
+import {TagGroup} from "../tag-group";
+
+import {Autocomplete} from "./index";
+
+const meta: Meta<typeof Autocomplete> = {
+  component: Autocomplete,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Pickers/Autocomplete",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "cat", name: "Cat"},
+      {id: "dog", name: "Dog"},
+      {id: "elephant", name: "Elephant"},
+      {id: "lion", name: "Lion"},
+      {id: "tiger", name: "Tiger"},
+      {id: "giraffe", name: "Giraffe"},
+    ];
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select an animal"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>Favorite Animal</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search animals..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const WithClearButton: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "cat", name: "Cat"},
+      {id: "dog", name: "Dog"},
+      {id: "elephant", name: "Elephant"},
+      {id: "lion", name: "Lion"},
+      {id: "tiger", name: "Tiger"},
+      {id: "giraffe", name: "Giraffe"},
+    ];
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select an animal"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>Favorite Animal</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search animals..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const WithOnClearCallback: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const [clearCount, setClearCount] = useState(0);
+    const [lastClearedAt, setLastClearedAt] = useState<string | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "cat", name: "Cat"},
+      {id: "dog", name: "Dog"},
+      {id: "elephant", name: "Elephant"},
+      {id: "lion", name: "Lion"},
+      {id: "tiger", name: "Tiger"},
+      {id: "giraffe", name: "Giraffe"},
+    ];
+
+    const handleClear = () => {
+      setClearCount((prev) => prev + 1);
+      setLastClearedAt(new Date().toLocaleTimeString());
+      // eslint-disable-next-line no-console
+      console.log("onClear callback triggered!");
+    };
+
+    const selectedItem = items.find((item) => item.id === selectedKey);
+
+    return (
+      <div className="w-full space-y-4">
+        <Autocomplete
+          className="w-[256px]"
+          placeholder="Select an animal"
+          selectionMode="single"
+          value={selectedKey}
+          onChange={setSelectedKey}
+          onClear={handleClear}
+        >
+          <Label>Favorite Animal</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search animals..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {items.map((item) => (
+                  <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                    {item.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+        <div className="space-y-2 rounded-xl border border-border p-4">
+          <p className="text-sm font-medium">onClear Callback Info:</p>
+          <div className="space-y-1 text-sm text-muted">
+            <p>Clear button clicked: {clearCount} time(s)</p>
+            {!!lastClearedAt && <p>Last cleared at: {lastClearedAt}</p>}
+            {!!selectedItem && (
+              <p className="text-success">
+                Currently selected: <strong>{selectedItem.name}</strong>
+              </p>
+            )}
+            {!selectedItem && (
+              <p className="text-muted">No selection (click clear to see the callback)</p>
+            )}
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Variants: Story = {
+  render: () => {
+    const [selectedKey1, setSelectedKey1] = useState<Key | null>(null);
+    const [selectedKey2, setSelectedKey2] = useState<Key | null>(null);
+    const [selectedKeys1, setSelectedKeys1] = useState<Key[]>([]);
+    const [selectedKeys2, setSelectedKeys2] = useState<Key[]>([]);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "option1", name: "Option 1"},
+      {id: "option2", name: "Option 2"},
+      {id: "option3", name: "Option 3"},
+      {id: "option4", name: "Option 4"},
+    ];
+
+    const onRemoveTags1 = (keys: Set<Key>) => {
+      setSelectedKeys1((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    const onRemoveTags2 = (keys: Set<Key>) => {
+      setSelectedKeys2((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    return (
+      <div className="flex flex-col gap-8">
+        <div className="flex flex-col gap-4">
+          <h3 className="text-lg font-semibold">Single Select Variants</h3>
+          <div className="flex flex-col gap-4">
+            <Autocomplete
+              className="w-[256px]"
+              placeholder="Select one"
+              selectionMode="single"
+              value={selectedKey1}
+              variant="primary"
+              onChange={setSelectedKey1}
+            >
+              <Label>Primary variant</Label>
+              <Autocomplete.Trigger>
+                <Autocomplete.Value />
+                <Autocomplete.ClearButton />
+                <Autocomplete.Indicator />
+              </Autocomplete.Trigger>
+              <Autocomplete.Popover>
+                <Autocomplete.Filter filter={contains}>
+                  <SearchField autoFocus name="search" variant="secondary">
+                    <SearchField.Group>
+                      <SearchField.SearchIcon />
+                      <SearchField.Input placeholder="Search..." />
+                      <SearchField.ClearButton />
+                    </SearchField.Group>
+                  </SearchField>
+                  <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                    {items.map((item) => (
+                      <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                        {item.name}
+                        <ListBox.ItemIndicator />
+                      </ListBox.Item>
+                    ))}
+                  </ListBox>
+                </Autocomplete.Filter>
+              </Autocomplete.Popover>
+            </Autocomplete>
+            <Autocomplete
+              className="w-[256px]"
+              placeholder="Select one"
+              selectionMode="single"
+              value={selectedKey2}
+              variant="secondary"
+              onChange={setSelectedKey2}
+            >
+              <Label>Secondary variant</Label>
+              <Autocomplete.Trigger>
+                <Autocomplete.Value />
+                <Autocomplete.ClearButton />
+                <Autocomplete.Indicator />
+              </Autocomplete.Trigger>
+              <Autocomplete.Popover>
+                <Autocomplete.Filter filter={contains}>
+                  <SearchField autoFocus name="search" variant="secondary">
+                    <SearchField.Group>
+                      <SearchField.SearchIcon />
+                      <SearchField.Input placeholder="Search..." />
+                      <SearchField.ClearButton />
+                    </SearchField.Group>
+                  </SearchField>
+                  <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                    {items.map((item) => (
+                      <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                        {item.name}
+                        <ListBox.ItemIndicator />
+                      </ListBox.Item>
+                    ))}
+                  </ListBox>
+                </Autocomplete.Filter>
+              </Autocomplete.Popover>
+            </Autocomplete>
+          </div>
+        </div>
+        <div className="flex flex-col gap-4">
+          <h3 className="text-lg font-semibold">Multiple Select Variants</h3>
+          <div className="flex flex-col gap-4">
+            <Autocomplete
+              className="w-[256px]"
+              placeholder="Select multiple"
+              selectionMode="multiple"
+              value={selectedKeys1}
+              variant="primary"
+              onChange={(keys) => setSelectedKeys1(keys as Key[])}
+            >
+              <Label>Primary variant</Label>
+              <Autocomplete.Trigger>
+                <Autocomplete.Value>
+                  {({defaultChildren, isPlaceholder, state}) => {
+                    if (isPlaceholder || state.selectedItems.length === 0) {
+                      return defaultChildren;
+                    }
+
+                    const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                    return (
+                      <TagGroup size="sm" onRemove={onRemoveTags1}>
+                        <TagGroup.List>
+                          {selectedItemsKeys.map((selectedItemKey) => {
+                            const item = items.find((s) => s.id === selectedItemKey);
+
+                            if (!item) return null;
+
+                            return (
+                              <Tag key={item.id} id={item.id}>
+                                {item.name}
+                              </Tag>
+                            );
+                          })}
+                        </TagGroup.List>
+                      </TagGroup>
+                    );
+                  }}
+                </Autocomplete.Value>
+                <Autocomplete.ClearButton />
+                <Autocomplete.Indicator />
+              </Autocomplete.Trigger>
+              <Autocomplete.Popover>
+                <Autocomplete.Filter filter={contains}>
+                  <SearchField autoFocus name="search" variant="secondary">
+                    <SearchField.Group>
+                      <SearchField.SearchIcon />
+                      <SearchField.Input placeholder="Search..." />
+                      <SearchField.ClearButton />
+                    </SearchField.Group>
+                  </SearchField>
+                  <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                    {items.map((item) => (
+                      <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                        {item.name}
+                        <ListBox.ItemIndicator />
+                      </ListBox.Item>
+                    ))}
+                  </ListBox>
+                </Autocomplete.Filter>
+              </Autocomplete.Popover>
+            </Autocomplete>
+            <Autocomplete
+              className="w-[256px]"
+              placeholder="Select multiple"
+              selectionMode="multiple"
+              value={selectedKeys2}
+              variant="secondary"
+              onChange={(keys) => setSelectedKeys2(keys as Key[])}
+            >
+              <Label>Secondary variant</Label>
+              <Autocomplete.Trigger>
+                <Autocomplete.Value>
+                  {({defaultChildren, isPlaceholder, state}) => {
+                    if (isPlaceholder || state.selectedItems.length === 0) {
+                      return defaultChildren;
+                    }
+
+                    const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+                    return (
+                      <TagGroup size="sm" variant="surface" onRemove={onRemoveTags2}>
+                        <TagGroup.List>
+                          {selectedItemsKeys.map((selectedItemKey) => {
+                            const item = items.find((s) => s.id === selectedItemKey);
+
+                            if (!item) return null;
+
+                            return (
+                              <Tag key={item.id} id={item.id}>
+                                {item.name}
+                              </Tag>
+                            );
+                          })}
+                        </TagGroup.List>
+                      </TagGroup>
+                    );
+                  }}
+                </Autocomplete.Value>
+                <Autocomplete.ClearButton />
+                <Autocomplete.Indicator />
+              </Autocomplete.Trigger>
+              <Autocomplete.Popover>
+                <Autocomplete.Filter filter={contains}>
+                  <SearchField autoFocus name="search" variant="secondary">
+                    <SearchField.Group>
+                      <SearchField.SearchIcon />
+                      <SearchField.Input placeholder="Search..." />
+                      <SearchField.ClearButton />
+                    </SearchField.Group>
+                  </SearchField>
+                  <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                    {items.map((item) => (
+                      <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                        {item.name}
+                        <ListBox.ItemIndicator />
+                      </ListBox.Item>
+                    ))}
+                  </ListBox>
+                </Autocomplete.Filter>
+              </Autocomplete.Popover>
+            </Autocomplete>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const MultipleSelect: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "florida", name: "Florida"},
+      {id: "new-york", name: "New York"},
+      {id: "illinois", name: "Illinois"},
+      {id: "pennsylvania", name: "Pennsylvania"},
+    ];
+
+    const onRemoveTags = (keys: Set<Key>) => {
+      setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select states"
+        selectionMode="multiple"
+        value={selectedKeys}
+        onChange={(keys) => setSelectedKeys(keys as Key[])}
+      >
+        <Label>States</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+              return (
+                <TagGroup size="sm" onRemove={onRemoveTags}>
+                  <TagGroup.List>
+                    {selectedItemsKeys.map((selectedItemKey) => {
+                      const item = items.find((s) => s.id === selectedItemKey);
+
+                      if (!item) return null;
+
+                      return (
+                        <Tag key={item.id} id={item.id}>
+                          {item.name}
+                        </Tag>
+                      );
+                    })}
+                  </TagGroup.List>
+                </TagGroup>
+              );
+            }}
+          </Autocomplete.Value>
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const FullWidth: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    return (
+      <Surface className="w-[380px] space-y-4 rounded-3xl p-6">
+        <Autocomplete
+          fullWidth
+          placeholder="Select one"
+          selectionMode="single"
+          value={selectedKey}
+          variant="secondary"
+          onChange={setSelectedKey}
+        >
+          <Label>State</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search states..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {items.map((item) => (
+                  <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                    {item.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+      </Surface>
+    );
+  },
+};
+
+export const WithDescription: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select one"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+        <Description>Select your state of residence</Description>
+      </Autocomplete>
+    );
+  },
+};
+
+export const WithSections: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select a country"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>Country</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search countries..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              <ListBox.Section>
+                <Header>North America</Header>
+                <ListBox.Item id="usa" textValue="United States">
+                  United States
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="canada" textValue="Canada">
+                  Canada
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="mexico" textValue="Mexico">
+                  Mexico
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              </ListBox.Section>
+              <Separator />
+              <ListBox.Section>
+                <Header>Europe</Header>
+                <ListBox.Item id="uk" textValue="United Kingdom">
+                  United Kingdom
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="france" textValue="France">
+                  France
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="germany" textValue="Germany">
+                  Germany
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="spain" textValue="Spain">
+                  Spain
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="italy" textValue="Italy">
+                  Italy
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              </ListBox.Section>
+              <Separator />
+              <ListBox.Section>
+                <Header>Asia</Header>
+                <ListBox.Item id="japan" textValue="Japan">
+                  Japan
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="china" textValue="China">
+                  China
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="india" textValue="India">
+                  India
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+                <ListBox.Item id="south-korea" textValue="South Korea">
+                  South Korea
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              </ListBox.Section>
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const WithDisabledOptions: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        disabledKeys={["cat", "kangaroo"]}
+        placeholder="Select an animal"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>Animal</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search animals..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="bird" textValue="Bird">
+                Bird
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="elephant" textValue="Elephant">
+                Elephant
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="tiger" textValue="Tiger">
+                Tiger
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const CustomIndicator: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select one"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>State</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator className="size-3">
+            <Icon icon="gravity-ui:chevrons-expand-vertical" />
+          </Autocomplete.Indicator>
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search states..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {items.map((item) => (
+                <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const Required: Story = {
+  render: () => {
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const data: Record<string, string> = {};
+
+      // Convert FormData to plain object
+      formData.forEach((value, key) => {
+        data[key] = value.toString();
+      });
+
+      alert("Form submitted successfully!");
+    };
+
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const states = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    const countries = [
+      {id: "usa", name: "United States"},
+      {id: "canada", name: "Canada"},
+      {id: "mexico", name: "Mexico"},
+      {id: "uk", name: "United Kingdom"},
+      {id: "france", name: "France"},
+      {id: "germany", name: "Germany"},
+    ];
+
+    return (
+      <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+        <Autocomplete
+          isRequired
+          className="w-full"
+          name="state"
+          placeholder="Select one"
+          selectionMode="single"
+        >
+          <Label>State</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search states..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {states.map((state) => (
+                  <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                    {state.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+          <FieldError />
+        </Autocomplete>
+        <Autocomplete
+          isRequired
+          className="w-full"
+          name="country"
+          placeholder="Select a country"
+          selectionMode="single"
+        >
+          <Label>Country</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search countries..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {countries.map((country) => (
+                  <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                    {country.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+          <FieldError />
+        </Autocomplete>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const states = [
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "florida", name: "Florida"},
+      {id: "new-york", name: "New York"},
+      {id: "illinois", name: "Illinois"},
+      {id: "pennsylvania", name: "Pennsylvania"},
+    ];
+
+    const [state, setState] = React.useState<Key | null>("california");
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const selectedState = states.find((s) => s.id === state);
+
+    return (
+      <div className="space-y-2">
+        <Autocomplete
+          className="w-[256px]"
+          placeholder="Select a state"
+          selectionMode="single"
+          value={state}
+          onChange={setState}
+        >
+          <Label>State (controlled)</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search states..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {states.map((state) => (
+                  <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                    {state.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+        <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p>
+      </div>
+    );
+  },
+};
+
+export const ControlledOpenState: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = React.useState(false);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    return (
+      <div className="space-y-4">
+        <Autocomplete
+          className="w-[256px]"
+          isOpen={isOpen}
+          placeholder="Select one"
+          selectionMode="single"
+          onOpenChange={setIsOpen}
+        >
+          <Label>State</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search states..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {items.map((item) => (
+                  <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                    {item.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+        <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Autocomplete</Button>
+        <p className="text-sm text-muted">Autocomplete is {isOpen ? "open" : "closed"}</p>
+      </div>
+    );
+  },
+};
+
+interface Pokemon {
+  name: string;
+}
+
+export const AsynchronousFiltering: Story = {
+  render: () => {
+    const list = useAsyncList<Pokemon>({
+      async load({filterText, signal}) {
+        const res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, {
+          signal,
+        });
+
+        const json = await res.json();
+
+        return {
+          items: json.results,
+        };
+      },
+    });
+
+    return (
+      <Autocomplete
+        allowsEmptyCollection
+        className="w-[256px]"
+        placeholder="Search..."
+        selectionMode="single"
+      >
+        <Label>Search a Star Wars characters</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter inputValue={list.filterText} onInputChange={list.setFilterText}>
+            <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search characters..." />
+                <Spinner
+                  size="sm"
+                  className={cn("absolute top-1/2 right-2 -translate-y-1/2", {
+                    "pointer-events-none opacity-0": !list.isLoading,
+                  })}
+                />
+                <SearchField.ClearButton
+                  className={cn({"pointer-events-none opacity-0": !!list.isLoading})}
+                />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox
+              className="max-h-[420px] overflow-y-auto"
+              items={list.items}
+              renderEmptyState={() => <EmptyState>No results found</EmptyState>}
+            >
+              {(item: Pokemon) => (
+                <ListBox.Item id={item.name} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              )}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+interface User {
+  email: string;
+  id: number;
+  name: string;
+}
+
+function generateUsers(n: number): User[] {
+  const firstNames = [
+    "Emma",
+    "Liam",
+    "Olivia",
+    "Noah",
+    "Ava",
+    "James",
+    "Sophia",
+    "Oliver",
+    "Isabella",
+    "Lucas",
+    "Mia",
+    "Ethan",
+    "Charlotte",
+    "Mason",
+    "Amelia",
+    "Logan",
+    "Harper",
+    "Alexander",
+    "Ella",
+    "Benjamin",
+  ];
+  const lastNames = [
+    "Smith",
+    "Johnson",
+    "Williams",
+    "Brown",
+    "Jones",
+    "Garcia",
+    "Miller",
+    "Davis",
+    "Rodriguez",
+    "Martinez",
+    "Anderson",
+    "Taylor",
+    "Thomas",
+    "Jackson",
+    "White",
+    "Harris",
+    "Clark",
+    "Lewis",
+    "Robinson",
+    "Walker",
+  ];
+  const users: User[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const firstName = firstNames[i % firstNames.length]!;
+    const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!;
+    const name = `${firstName} ${lastName}`;
+
+    users.push({
+      email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
+      id: i + 1,
+      name,
+    });
+  }
+
+  return users;
+}
+
+export const Virtualization: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const [searchQuery, setSearchQuery] = useState("");
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const allUsers = React.useMemo(() => generateUsers(1000), []);
+
+    const filteredUsers = React.useMemo(() => {
+      if (!searchQuery) return allUsers;
+
+      return allUsers.filter(
+        (user) => contains(user.name, searchQuery) || contains(user.email, searchQuery),
+      );
+    }, [allUsers, contains, searchQuery]);
+
+    return (
+      <Autocomplete
+        allowsEmptyCollection
+        className="w-[300px]"
+        placeholder="Select a user"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>User</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter inputValue={searchQuery} onInputChange={setSearchQuery}>
+            <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search users..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+              <ListBox
+                items={filteredUsers}
+                renderEmptyState={() => <EmptyState>No results found</EmptyState>}
+              >
+                {(user) => (
+                  <ListBox.Item id={user.id} textValue={user.name}>
+                    <div className="flex flex-col">
+                      <Label>{user.name}</Label>
+                      <Description>{user.email}</Description>
+                    </div>
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                )}
+              </ListBox>
+            </Virtualizer>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => {
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const items = [
+      {id: "florida", name: "Florida"},
+      {id: "delaware", name: "Delaware"},
+      {id: "california", name: "California"},
+      {id: "texas", name: "Texas"},
+      {id: "new-york", name: "New York"},
+      {id: "washington", name: "Washington"},
+    ];
+
+    const countries = [
+      {id: "argentina", name: "Argentina"},
+      {id: "venezuela", name: "Venezuela"},
+      {id: "japan", name: "Japan"},
+      {id: "france", name: "France"},
+      {id: "italy", name: "Italy"},
+      {id: "spain", name: "Spain"},
+    ];
+
+    return (
+      <div className="flex flex-col gap-4">
+        <Autocomplete
+          isDisabled
+          className="w-[256px]"
+          defaultValue="california"
+          placeholder="Select one"
+          selectionMode="single"
+        >
+          <Label>State</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search states..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {items.map((item) => (
+                  <ListBox.Item key={item.id} id={item.id} textValue={item.name}>
+                    {item.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+        <Autocomplete
+          isDisabled
+          className="w-[256px]"
+          defaultValue={["argentina", "japan", "france"]}
+          placeholder="Select countries"
+          selectionMode="multiple"
+        >
+          <Label>Countries to Visit</Label>
+          <Autocomplete.Trigger>
+            <Autocomplete.Value />
+            <Autocomplete.ClearButton />
+            <Autocomplete.Indicator />
+          </Autocomplete.Trigger>
+          <Autocomplete.Popover>
+            <Autocomplete.Filter filter={contains}>
+              <SearchField autoFocus name="search" variant="secondary">
+                <SearchField.Group>
+                  <SearchField.SearchIcon />
+                  <SearchField.Input placeholder="Search countries..." />
+                  <SearchField.ClearButton />
+                </SearchField.Group>
+              </SearchField>
+              <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+                {countries.map((country) => (
+                  <ListBox.Item key={country.id} id={country.id} textValue={country.name}>
+                    {country.name}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Autocomplete.Filter>
+          </Autocomplete.Popover>
+        </Autocomplete>
+      </div>
+    );
+  },
+};
+
+export const UserSelection: Story = {
+  render: () => {
+    const users = [
+      {
+        id: "1",
+        name: "Bob",
+        email: "bob@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "B",
+      },
+      {
+        id: "2",
+        name: "Fred",
+        email: "fred@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "F",
+      },
+      {
+        id: "3",
+        name: "Martha",
+        email: "martha@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "M",
+      },
+      {
+        id: "4",
+        name: "John",
+        email: "john@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "J",
+      },
+      {
+        id: "5",
+        name: "Jane",
+        email: "jane@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "J",
+      },
+    ];
+
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select a user"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>User</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItems = state.selectedItems;
+
+              if (selectedItems.length > 1) {
+                return `${selectedItems.length} users selected`;
+              }
+
+              const selectedItem = users.find((user) => user.id === selectedItems[0].key);
+
+              if (!selectedItem) {
+                return defaultChildren;
+              }
+
+              return (
+                <div className="flex items-center gap-2">
+                  <Avatar className="size-4" size="sm">
+                    <AvatarImage src={selectedItem.avatarUrl} />
+                    <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                  </Avatar>
+                  <span>{selectedItem.name}</span>
+                </div>
+              );
+            }}
+          </Autocomplete.Value>
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search users..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {users.map((user) => (
+                <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                  <Avatar size="sm">
+                    <AvatarImage src={user.avatarUrl} />
+                    <AvatarFallback>{user.fallback}</AvatarFallback>
+                  </Avatar>
+                  <div className="flex flex-col">
+                    <Label>{user.name}</Label>
+                    <Description>{user.email}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const UserSelectionMultiple: Story = {
+  render: () => {
+    const users = [
+      {
+        id: "1",
+        name: "Bob",
+        email: "bob@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "B",
+      },
+      {
+        id: "2",
+        name: "Fred",
+        email: "fred@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "F",
+      },
+      {
+        id: "3",
+        name: "Martha",
+        email: "martha@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "M",
+      },
+      {
+        id: "4",
+        name: "John",
+        email: "john@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "J",
+      },
+      {
+        id: "5",
+        name: "Jane",
+        email: "jane@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "J",
+      },
+    ];
+
+    const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const onRemoveTags = (keys: Set<Key>) => {
+      setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        defaultValue={["1", "2"]}
+        placeholder="Select your teammates"
+        selectionMode="multiple"
+        value={selectedKeys}
+        onChange={(keys) => setSelectedKeys(keys as Key[])}
+      >
+        <Label>Users</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+              return (
+                <TagGroup size="sm" onRemove={onRemoveTags}>
+                  <TagGroup.List>
+                    {selectedItemsKeys.map((selectedItemKey) => {
+                      const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+                      if (!selectedItem) {
+                        return null;
+                      }
+
+                      return (
+                        <Tag key={selectedItem.id} id={selectedItem.id}>
+                          <Avatar className="size-4" size="sm">
+                            <AvatarImage src={selectedItem.avatarUrl} />
+                            <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                          </Avatar>
+                          <span>{selectedItem.name}</span>
+                        </Tag>
+                      );
+                    })}
+                  </TagGroup.List>
+                </TagGroup>
+              );
+            }}
+          </Autocomplete.Value>
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search users..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}>
+              {users.map((user) => (
+                <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                  <Avatar size="sm">
+                    <AvatarImage src={user.avatarUrl} />
+                    <AvatarFallback>{user.fallback}</AvatarFallback>
+                  </Avatar>
+                  <div className="flex flex-col">
+                    <Label>{user.name}</Label>
+                    <Description>{user.email}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+interface City {
+  name: string;
+  country: string;
+}
+
+export const LocationSearch: Story = {
+  render: () => {
+    const allCities: City[] = [
+      {name: "New York", country: "USA"},
+      {name: "Los Angeles", country: "USA"},
+      {name: "Chicago", country: "USA"},
+      {name: "London", country: "UK"},
+      {name: "Paris", country: "France"},
+      {name: "Tokyo", country: "Japan"},
+      {name: "Sydney", country: "Australia"},
+      {name: "Toronto", country: "Canada"},
+      {name: "Berlin", country: "Germany"},
+      {name: "Madrid", country: "Spain"},
+    ];
+
+    const [selectedKey, setSelectedKey] = useState<Key | null>(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    // Simulate async filtering
+    const customFilter = (text: string, inputValue: string) => {
+      if (!inputValue) return true;
+      setIsLoading(true);
+      setTimeout(() => setIsLoading(false), 300);
+
+      return contains(text, inputValue);
+    };
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Search for a city"
+        selectionMode="single"
+        value={selectedKey}
+        onChange={setSelectedKey}
+      >
+        <Label>City</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value />
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={customFilter}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search cities..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox
+              renderEmptyState={() => (
+                <EmptyState>{isLoading ? "Searching..." : "No cities found"}</EmptyState>
+              )}
+            >
+              {allCities.map((city) => (
+                <ListBox.Item key={city.name} id={city.name} textValue={city.name}>
+                  <div className="flex flex-col">
+                    <Label>{city.name}</Label>
+                    <Description>{city.country}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const TagGroupSelection: Story = {
+  render: () => {
+    const tags = [
+      {id: "react", name: "React"},
+      {id: "typescript", name: "TypeScript"},
+      {id: "javascript", name: "JavaScript"},
+      {id: "nodejs", name: "Node.js"},
+      {id: "python", name: "Python"},
+      {id: "vue", name: "Vue"},
+      {id: "angular", name: "Angular"},
+      {id: "nextjs", name: "Next.js"},
+    ];
+
+    const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const onRemoveTags = (keys: Set<Key>) => {
+      setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Select tags"
+        selectionMode="multiple"
+        value={selectedKeys}
+        onChange={(keys) => setSelectedKeys(keys as Key[])}
+      >
+        <Label>Tags</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+              return (
+                <TagGroup size="sm" onRemove={onRemoveTags}>
+                  <TagGroup.List>
+                    {selectedItemsKeys.map((selectedItemKey) => {
+                      const tag = tags.find((t) => t.id === selectedItemKey);
+
+                      if (!tag) return null;
+
+                      return (
+                        <Tag key={tag.id} id={tag.id}>
+                          {tag.name}
+                        </Tag>
+                      );
+                    })}
+                  </TagGroup.List>
+                </TagGroup>
+              );
+            }}
+          </Autocomplete.Value>
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search tags..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No tags found</EmptyState>}>
+              {tags.map((tag) => (
+                <ListBox.Item key={tag.id} id={tag.id} textValue={tag.name}>
+                  {tag.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
+
+export const EmailRecipients: Story = {
+  render: () => {
+    const emails = [
+      {id: "alice@example.com", name: "Alice Johnson", email: "alice@example.com"},
+      {id: "bob@example.com", name: "Bob Smith", email: "bob@example.com"},
+      {id: "charlie@example.com", name: "Charlie Brown", email: "charlie@example.com"},
+      {id: "diana@example.com", name: "Diana Prince", email: "diana@example.com"},
+      {id: "eve@example.com", name: "Eve Wilson", email: "eve@example.com"},
+    ];
+
+    const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+    const {contains} = useFilter({sensitivity: "base"});
+
+    const onRemoveTags = (keys: Set<Key>) => {
+      setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
+    };
+
+    return (
+      <Autocomplete
+        className="w-[256px]"
+        placeholder="Add recipients"
+        selectionMode="multiple"
+        value={selectedKeys}
+        onChange={(keys) => setSelectedKeys(keys as Key[])}
+      >
+        <Label>To</Label>
+        <Autocomplete.Trigger>
+          <Autocomplete.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+              return (
+                <TagGroup size="sm" onRemove={onRemoveTags}>
+                  <TagGroup.List>
+                    {selectedItemsKeys.map((selectedItemKey) => {
+                      const email = emails.find((e) => e.id === selectedItemKey);
+
+                      if (!email) return null;
+
+                      return (
+                        <Tag key={email.id} id={email.id}>
+                          {email.email}
+                        </Tag>
+                      );
+                    })}
+                  </TagGroup.List>
+                </TagGroup>
+              );
+            }}
+          </Autocomplete.Value>
+          <Autocomplete.ClearButton />
+          <Autocomplete.Indicator />
+        </Autocomplete.Trigger>
+        <Autocomplete.Popover>
+          <Autocomplete.Filter filter={contains}>
+            <SearchField autoFocus name="search" variant="secondary">
+              <SearchField.Group>
+                <SearchField.SearchIcon />
+                <SearchField.Input placeholder="Search emails..." />
+                <SearchField.ClearButton />
+              </SearchField.Group>
+            </SearchField>
+            <ListBox renderEmptyState={() => <EmptyState>No recipients found</EmptyState>}>
+              {emails.map((email) => (
+                <ListBox.Item key={email.id} id={email.id} textValue={email.email}>
+                  <div className="flex flex-col">
+                    <Label>{email.name}</Label>
+                    <Description>{email.email}</Description>
+                  </div>
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Autocomplete.Filter>
+        </Autocomplete.Popover>
+      </Autocomplete>
+    );
+  },
+};
diff --git a/packages/react/src/components/autocomplete/autocomplete.tsx b/packages/react/src/components/autocomplete/autocomplete.tsx
new file mode 100644
index 0000000..f7968c6
--- /dev/null
+++ b/packages/react/src/components/autocomplete/autocomplete.tsx
@@ -0,0 +1,347 @@
+"use client";
+
+import type {Booleanish} from "../../utils/assertion";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {AutocompleteVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode, RefObject} from "react";
+
+import {autocompleteVariants} from "@heroui/styles";
+import {mergeRefs, useResizeObserver} from "@react-aria/utils";
+import React, {createContext, use, useCallback, useRef, useState} from "react";
+import {Autocomplete as AutocompletePrimitive} from "react-aria-components/Autocomplete";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {Dialog as DialogPrimitive} from "react-aria-components/Dialog";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+import {Popover as PopoverPrimitive} from "react-aria-components/Popover";
+import {
+  Select as SelectPrimitive,
+  SelectStateContext,
+  SelectValue as SelectValuePrimitive,
+} from "react-aria-components/Select";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CloseIcon, IconChevronDown} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Context
+ * -----------------------------------------------------------------------------------------------*/
+type AutocompleteContext = {
+  slots?: ReturnType<typeof autocompleteVariants>;
+  onClear?: () => void;
+  triggerRef: RefObject<HTMLElement | null>;
+  clearButtonRef: RefObject<HTMLButtonElement | null>;
+  isDisabled?: boolean;
+};
+
+const AutocompleteContext = createContext<AutocompleteContext>({
+  triggerRef: {current: null} as RefObject<HTMLElement | null>,
+  clearButtonRef: {current: null} as RefObject<HTMLButtonElement | null>,
+  isDisabled: false,
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Root
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteRootProps<T extends object, M extends "single" | "multiple" = "single">
+  extends ComponentPropsWithRef<typeof SelectPrimitive<T, M>>, AutocompleteVariants {
+  items?: Iterable<T, M>;
+  // Handler that is called when the clear button is pressed.
+  onClear?: () => void;
+}
+
+const AutocompleteRoot = <T extends object = object, M extends "single" | "multiple" = "single">({
+  children,
+  className,
+  fullWidth,
+  isDisabled,
+  onClear,
+  variant,
+  ...props
+}: AutocompleteRootProps<T, M>) => {
+  const slots = React.useMemo(
+    () => autocompleteVariants({fullWidth, variant}),
+    [fullWidth, variant],
+  );
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const clearButtonRef = useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <AutocompleteContext value={{slots, triggerRef, clearButtonRef, onClear, isDisabled}}>
+      <SelectPrimitive
+        data-slot="autocomplete"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+        isDisabled={isDisabled}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </SelectPrimitive>
+    </AutocompleteContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteTriggerProps extends ComponentPropsWithRef<typeof GroupPrimitive> {}
+
+const AutocompleteTrigger = ({
+  children,
+  className,
+  isDisabled: isDisabledProp,
+  onClick,
+  ref,
+  ...props
+}: AutocompleteTriggerProps) => {
+  const {clearButtonRef, isDisabled: rootDisabled, slots, triggerRef} = use(AutocompleteContext);
+  const state = use(SelectStateContext);
+  const isDisabled = isDisabledProp ?? rootDisabled ?? false;
+
+  // Callback ref to update context ref
+  const contextRefCallback = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      triggerRef.current = node;
+    },
+    [triggerRef],
+  );
+
+  // Merge context ref callback with user-provided ref
+  const mergedRef = mergeRefs(contextRefCallback, ref);
+
+  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    // Don't toggle if clicking the clear button
+    if (clearButtonRef.current?.contains(e.target as Node)) {
+      return;
+    }
+    onClick?.(e);
+    state?.toggle();
+  };
+
+  return (
+    <GroupPrimitive
+      ref={mergedRef}
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="autocomplete-trigger"
+      isDisabled={isDisabled}
+      onClick={handleClick}
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </GroupPrimitive>
+  );
+};
+
+AutocompleteTrigger.displayName = "AutocompleteTrigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Value
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteValueProps extends ComponentPropsWithRef<typeof SelectValuePrimitive> {}
+
+const AutocompleteValue = ({children, className, ...props}: AutocompleteValueProps) => {
+  const {slots} = use(AutocompleteContext);
+
+  return (
+    <SelectValuePrimitive
+      className={composeTwRenderProps(className, slots?.value())}
+      data-slot="autocomplete-value"
+      {...props}
+    >
+      {children}
+    </SelectValuePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AutocompleteIndicator = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: AutocompleteIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof AutocompleteIndicatorProps<E>>) => {
+  const {slots} = use(AutocompleteContext);
+  const state = use(SelectStateContext);
+
+  if (children && React.isValidElement(children)) {
+    return React.cloneElement(
+      children as React.ReactElement<{
+        className?: string;
+        "data-slot"?: "autocomplete-indicator";
+        "data-open"?: Booleanish;
+      }>,
+      {
+        ...(props as any),
+        className: composeSlotClassName(slots?.indicator, className),
+        "data-slot": "autocomplete-indicator",
+        "data-open": dataAttr(state?.isOpen),
+      },
+    );
+  }
+
+  return (
+    <ButtonPrimitive>
+      <IconChevronDown
+        className={composeSlotClassName(slots?.indicator, className)}
+        data-open={dataAttr(state?.isOpen)}
+        data-slot="autocomplete-default-indicator"
+        {...(props as any)}
+      />
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompletePopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const AutocompletePopover = ({
+  children,
+  className,
+  placement = "bottom",
+  style,
+  ...props
+}: AutocompletePopoverProps) => {
+  const {slots, triggerRef} = use(AutocompleteContext);
+  const [triggerWidth, setTriggerWidth] = useState<string | null>(null);
+
+  const onResize = useCallback(() => {
+    if (triggerRef.current) {
+      setTriggerWidth(triggerRef.current.offsetWidth + "px");
+    }
+  }, [triggerRef]);
+
+  useResizeObserver({ref: triggerRef, onResize});
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="autocomplete-popover"
+        placement={placement}
+        triggerRef={triggerRef}
+        style={
+          {
+            "--trigger-width": triggerWidth,
+            ...(typeof style === "object" && style !== null ? style : {}),
+          } as React.CSSProperties
+        }
+      >
+        <DialogPrimitive className={slots?.popoverDialog()} data-slot="autocomplete-popover-dialog">
+          {children}
+        </DialogPrimitive>
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Filter
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteFilterProps extends ComponentPropsWithRef<typeof AutocompletePrimitive> {}
+
+const AutocompleteFilter = ({children, ...props}: AutocompleteFilterProps) => {
+  return (
+    <AutocompletePrimitive data-slot="autocomplete-filter" {...props}>
+      {children}
+    </AutocompletePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Autocomplete Clear Button
+ * -----------------------------------------------------------------------------------------------*/
+interface AutocompleteClearButtonProps<
+  E extends keyof React.JSX.IntrinsicElements = "button",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const AutocompleteClearButton = <E extends keyof React.JSX.IntrinsicElements = "button">({
+  className,
+  onClick,
+  ref,
+  ...props
+}: AutocompleteClearButtonProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof AutocompleteClearButtonProps<E>>) => {
+  const {clearButtonRef, isDisabled, onClear, slots} = use(AutocompleteContext);
+  const state = use(SelectStateContext);
+
+  const clearButtonRefCallback = React.useCallback(
+    (node: HTMLButtonElement | null) => {
+      clearButtonRef.current = node;
+    },
+    [clearButtonRef],
+  );
+
+  // Merge context ref callback with user-provided ref
+  const mergedRef = mergeRefs(clearButtonRefCallback, ref as any);
+
+  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+    state?.selectionManager.setSelectedKeys(new Set());
+    onClear?.();
+    onClick?.(e as any);
+  };
+
+  return (
+    <dom.button
+      ref={mergedRef}
+      aria-label="Clear selection"
+      className={slots?.clearButton({className})}
+      data-empty={dataAttr(state?.selectionManager.selectedKeys.size === 0)}
+      data-slot="autocomplete-clear-button"
+      disabled={isDisabled ?? false}
+      type="button"
+      onClick={handleClick}
+      {...(props as any)}
+    >
+      <CloseIcon data-slot="autocomplete-clear-button-icon" />
+    </dom.button>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AutocompleteRoot,
+  AutocompleteTrigger,
+  AutocompleteValue,
+  AutocompleteIndicator,
+  AutocompletePopover,
+  AutocompleteFilter,
+  AutocompleteClearButton,
+};
+
+export type {
+  AutocompleteRootProps,
+  AutocompleteTriggerProps,
+  AutocompleteValueProps,
+  AutocompleteIndicatorProps,
+  AutocompletePopoverProps,
+  AutocompleteFilterProps,
+  AutocompleteClearButtonProps,
+};
diff --git a/packages/react/src/components/autocomplete/index.ts b/packages/react/src/components/autocomplete/index.ts
new file mode 100644
index 0000000..431a57f
--- /dev/null
+++ b/packages/react/src/components/autocomplete/index.ts
@@ -0,0 +1,66 @@
+import type {ComponentProps} from "react";
+
+import {
+  AutocompleteClearButton,
+  AutocompleteFilter,
+  AutocompleteIndicator,
+  AutocompletePopover,
+  AutocompleteRoot,
+  AutocompleteTrigger,
+  AutocompleteValue,
+} from "./autocomplete";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Autocomplete = Object.assign(AutocompleteRoot, {
+  Root: AutocompleteRoot,
+  Trigger: AutocompleteTrigger,
+  Value: AutocompleteValue,
+  Indicator: AutocompleteIndicator,
+  Popover: AutocompletePopover,
+  Filter: AutocompleteFilter,
+  ClearButton: AutocompleteClearButton,
+});
+
+export type Autocomplete<T extends object = object, M extends "single" | "multiple" = "single"> = {
+  Props: ComponentProps<typeof AutocompleteRoot<T, M>>;
+  RootProps: ComponentProps<typeof AutocompleteRoot<T, M>>;
+  TriggerProps: ComponentProps<typeof AutocompleteTrigger>;
+  ValueProps: ComponentProps<typeof AutocompleteValue>;
+  IndicatorProps: ComponentProps<typeof AutocompleteIndicator>;
+  PopoverProps: ComponentProps<typeof AutocompletePopover>;
+  FilterProps: ComponentProps<typeof AutocompleteFilter>;
+  ClearButtonProps: ComponentProps<typeof AutocompleteClearButton>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  AutocompleteClearButton,
+  AutocompleteFilter,
+  AutocompleteTrigger,
+  AutocompleteIndicator,
+  AutocompletePopover,
+  AutocompleteRoot,
+  AutocompleteValue,
+};
+
+export type {
+  AutocompleteRootProps,
+  AutocompleteRootProps as AutocompleteProps,
+  AutocompleteTriggerProps,
+  AutocompleteValueProps,
+  AutocompleteIndicatorProps,
+  AutocompletePopoverProps,
+  AutocompleteFilterProps,
+  AutocompleteClearButtonProps,
+} from "./autocomplete";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {autocompleteVariants} from "@heroui/styles";
+
+export type {AutocompleteVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/avatar/avatar.stories.tsx b/packages/react/src/components/avatar/avatar.stories.tsx
new file mode 100644
index 0000000..9a02c84
--- /dev/null
+++ b/packages/react/src/components/avatar/avatar.stories.tsx
@@ -0,0 +1,384 @@
+import type {AvatarRootProps, AvatarVariants} from "./index";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Separator} from "../separator";
+
+import {Avatar} from "./index";
+
+export default {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["accent", "default", "success", "warning", "danger"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: Avatar,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Media/Avatar",
+} as Meta<typeof Avatar>;
+
+const defaultArgs: Avatar["RootProps"] = {};
+
+const users = [
+  {
+    id: 1,
+    image_url: "https://img.heroui.chat/image/avatar?w=400&h=400&u=3",
+    name: "John",
+  },
+  {
+    id: 2,
+    image_url: "https://img.heroui.chat/image/avatar?w=400&h=400&u=5",
+    name: "Kate",
+  },
+  {
+    id: 3,
+    image_url: "https://img.heroui.chat/image/avatar?w=400&h=400&u=20",
+    name: "Emily",
+  },
+  {
+    id: 4,
+    image_url: "https://img.heroui.chat/image/avatar?w=400&h=400&u=23",
+    name: "Michael",
+  },
+  {
+    id: 5,
+    image_url: "https://img.heroui.chat/image/avatar?w=400&h=400&u=16",
+    name: "Olivia",
+  },
+];
+
+const circles = [
+  {
+    id: 1,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "R",
+  },
+  {
+    id: 2,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "O",
+  },
+  {
+    id: 3,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "G",
+  },
+  {
+    id: 4,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/white.jpg",
+    name: "W",
+  },
+  {
+    id: 5,
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+    name: "B",
+  },
+];
+
+const Template = ({color, size}: Avatar["RootProps"]) => (
+  <div className="flex items-start gap-4">
+    <div className="flex flex-col gap-4">
+      <Avatar color={color} size={size}>
+        <Avatar.Fallback>PG</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Fallback>JR</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Fallback>
+          <Icon icon="gravity-ui:person" />
+        </Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Fallback>
+          <Icon icon="gravity-ui:person-gear" />
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+
+    <div className="flex flex-col gap-4">
+      <Avatar color={color} size={size}>
+        <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />
+        <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Junior Garcia"
+          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
+        />
+        <Avatar.Fallback delayMs={600}>JG</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Junior Garcia"
+          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
+        />
+        <Avatar.Fallback delayMs={600}>JG</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image alt="Paul" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=8" />
+        <Avatar.Fallback delayMs={600}>PG</Avatar.Fallback>
+      </Avatar>
+    </div>
+
+    <div className="flex flex-col gap-4">
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Red"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+        />
+        <Avatar.Fallback>R</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Orange"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+        />
+        <Avatar.Fallback>O</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Green"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
+        />
+        <Avatar.Fallback>G</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="White"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/white.jpg"
+        />
+        <Avatar.Fallback>W</Avatar.Fallback>
+      </Avatar>
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          alt="Black"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg"
+        />
+        <Avatar.Fallback>B</Avatar.Fallback>
+      </Avatar>
+    </div>
+  </div>
+);
+
+const TemplateWithDelay = ({
+  color,
+  delay = 300,
+  size,
+}: {
+  delay: number;
+  color: AvatarVariants["color"];
+  size: AvatarVariants["size"];
+}) => {
+  return (
+    <div className="flex flex-col gap-4">
+      <Avatar color={color} size={size}>
+        <Avatar.Image
+          src={`https://app.requestly.io/delay/${delay}/https://img.heroui.chat/image/avatar?w=400&h=400&u=3`}
+        />
+      </Avatar>
+    </div>
+  );
+};
+
+const TemplateWithColors = () => {
+  return (
+    <div className="flex items-center gap-4">
+      <Avatar color="default">
+        <Avatar.Fallback>DF</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="accent">
+        <Avatar.Fallback>AC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="success">
+        <Avatar.Fallback>SC</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="warning">
+        <Avatar.Fallback>WR</Avatar.Fallback>
+      </Avatar>
+      <Avatar color="danger">
+        <Avatar.Fallback>DG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+};
+
+const FallbackTemplate = () => {
+  return (
+    <div className="flex items-center gap-4">
+      {/* Text fallback */}
+      <Avatar>
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar>
+      {/* Icon fallback */}
+      <Avatar>
+        <Avatar.Fallback>
+          <Icon icon="gravity-ui:person" />
+        </Avatar.Fallback>
+      </Avatar>
+      {/* Fallback with delay */}
+      <Avatar>
+        <Avatar.Image
+          alt="Delayed Avatar"
+          src="https://invalid-url-to-show-fallback.com/image.jpg"
+        />
+        <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
+      </Avatar>
+      {/* Custom styled fallback */}
+      <Avatar>
+        <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white">
+          GB
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+  );
+};
+
+const AvatarGroupTemplate = () => {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center justify-center -space-x-2">
+        {users.map((user) => (
+          <Avatar key={user.id} className="ring-2 ring-background">
+            <Avatar.Image src={user.image_url} />
+            <Avatar.Fallback>{user.name.charAt(0)}</Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="border-none">+5</Avatar.Fallback>
+        </Avatar>
+      </div>
+      <div className="flex items-center justify-center -space-x-2">
+        {circles.map((circle) => (
+          <Avatar key={circle.id} className="ring-2 ring-background">
+            <Avatar.Image src={circle.image_url} />
+            <Avatar.Fallback>{circle.name}</Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="border-none">+5</Avatar.Fallback>
+        </Avatar>
+      </div>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithDelay = {
+  args: defaultArgs,
+  render: TemplateWithDelay,
+};
+
+export const WithColors = {
+  render: TemplateWithColors,
+};
+
+export const Fallback = {
+  render: FallbackTemplate,
+};
+
+export const Group = {
+  render: AvatarGroupTemplate,
+};
+
+export const Sizes = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Avatar size="sm">
+        <Avatar.Image alt="Small" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />
+        <Avatar.Fallback>SM</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="md">
+        <Avatar.Image alt="Medium" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4" />
+        <Avatar.Fallback>MD</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="lg">
+        <Avatar.Image alt="Large" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5" />
+        <Avatar.Fallback>LG</Avatar.Fallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+const VariantsTemplate = (props: AvatarRootProps) => {
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+  const variants = [
+    {label: "letter", type: "letter", content: "AG"},
+    {label: "letter soft", type: "letter-soft", content: "AG"},
+    {label: "icon", type: "icon", content: <Icon icon="gravity-ui:person" />},
+    {label: "icon soft", type: "icon-soft", content: <Icon icon="gravity-ui:person" />},
+    {
+      label: "img",
+      type: "img",
+      content: [
+        "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+        "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+      ],
+    },
+  ] as const;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Color labels header */}
+      <div className="flex items-center gap-3">
+        <div className="w-24 shrink-0" />
+        {colors.map((color) => (
+          <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+            <span className="text-xs text-muted capitalize">{color}</span>
+          </div>
+        ))}
+      </div>
+
+      <Separator />
+
+      {/* Variant rows */}
+      {variants.map((variant) => (
+        <div key={variant.label} className="flex items-center gap-3">
+          <div className="w-24 shrink-0 text-sm text-muted">{variant.label}</div>
+          {colors.map((color, colorIndex) => (
+            <div key={color} className="flex w-20 shrink-0 items-center justify-center">
+              <Avatar
+                {...props}
+                color={color}
+                variant={variant.type.includes("soft") ? "soft" : undefined}
+              >
+                {variant.type === "img" ? (
+                  <>
+                    <Avatar.Image
+                      alt={`Avatar ${color}`}
+                      src={Array.isArray(variant.content) ? variant.content[colorIndex] : ""}
+                    />
+                    <Avatar.Fallback>{color.charAt(0).toUpperCase()}</Avatar.Fallback>
+                  </>
+                ) : (
+                  <Avatar.Fallback>{variant.content}</Avatar.Fallback>
+                )}
+              </Avatar>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const Variants = {
+  args: defaultArgs,
+  render: VariantsTemplate,
+};
diff --git a/packages/react/src/components/avatar/avatar.tsx b/packages/react/src/components/avatar/avatar.tsx
new file mode 100644
index 0000000..b38543c
--- /dev/null
+++ b/packages/react/src/components/avatar/avatar.tsx
@@ -0,0 +1,96 @@
+"use client";
+
+import type {AvatarVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {avatarVariants} from "@heroui/styles";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+import React, {createContext} from "react";
+
+import {composeSlotClassName} from "../../utils/compose";
+
+/* ------------------------------------------------------------------------------------------------
+ * Avatar Context
+ * --------------------------------------------------------------------------------------------- */
+type AvatarContext = {
+  slots?: ReturnType<typeof avatarVariants>;
+};
+
+const AvatarContext = createContext<AvatarContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Avatar Root
+ * -----------------------------------------------------------------------------------------------*/
+interface AvatarRootProps
+  extends Omit<ComponentPropsWithRef<typeof AvatarPrimitive.Root>, "color">, AvatarVariants {}
+
+const AvatarRoot = ({children, className, color, size, variant, ...props}: AvatarRootProps) => {
+  const slots = React.useMemo(() => avatarVariants({color, size, variant}), [color, size, variant]);
+
+  return (
+    <AvatarContext value={{slots}}>
+      <AvatarPrimitive.Root className={slots.base({className})} {...props}>
+        {children}
+      </AvatarPrimitive.Root>
+    </AvatarContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Avatar Image
+ * -----------------------------------------------------------------------------------------------*/
+interface AvatarImageProps extends ComponentPropsWithRef<typeof AvatarPrimitive.Image> {}
+
+const AvatarImage = ({
+  className,
+  crossOrigin,
+  loading,
+  onError,
+  onLoad,
+  sizes,
+  src,
+  srcSet,
+  ...props
+}: AvatarImageProps) => {
+  const {slots} = React.use(AvatarContext);
+
+  return (
+    <AvatarPrimitive.Image
+      className={composeSlotClassName(slots?.image, className)}
+      crossOrigin={crossOrigin}
+      loading={loading}
+      sizes={sizes}
+      src={src}
+      srcSet={srcSet}
+      onError={onError}
+      onLoad={onLoad}
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Avatar Fallback
+ * -----------------------------------------------------------------------------------------------*/
+interface AvatarFallbackProps extends ComponentPropsWithRef<typeof AvatarPrimitive.Fallback> {
+  color?: AvatarVariants["color"];
+}
+
+const AvatarFallback = ({className, color, ...props}: AvatarFallbackProps) => {
+  const {slots} = React.use(AvatarContext);
+
+  return (
+    <AvatarPrimitive.Fallback
+      className={composeSlotClassName(slots?.fallback, className, {color})}
+      data-slot="avatar-fallback"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {AvatarRoot, AvatarImage, AvatarFallback};
+
+export type {AvatarRootProps, AvatarImageProps, AvatarFallbackProps};
diff --git a/packages/react/src/components/avatar/index.ts b/packages/react/src/components/avatar/index.ts
new file mode 100644
index 0000000..5ed8421
--- /dev/null
+++ b/packages/react/src/components/avatar/index.ts
@@ -0,0 +1,38 @@
+import type {ComponentProps} from "react";
+
+import {AvatarFallback, AvatarImage, AvatarRoot} from "./avatar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Avatar = Object.assign(AvatarRoot, {
+  Root: AvatarRoot,
+  Image: AvatarImage,
+  Fallback: AvatarFallback,
+});
+
+export type Avatar = {
+  Props: ComponentProps<typeof AvatarRoot>;
+  RootProps: ComponentProps<typeof AvatarRoot>;
+  ImageProps: ComponentProps<typeof AvatarImage>;
+  FallbackProps: ComponentProps<typeof AvatarFallback>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {AvatarRoot, AvatarImage, AvatarFallback};
+
+export type {
+  AvatarRootProps,
+  AvatarRootProps as AvatarProps,
+  AvatarImageProps,
+  AvatarFallbackProps,
+} from "./avatar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {avatarVariants} from "@heroui/styles";
+
+export type {AvatarVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/badge/badge.stories.tsx b/packages/react/src/components/badge/badge.stories.tsx
new file mode 100644
index 0000000..3dd6509
--- /dev/null
+++ b/packages/react/src/components/badge/badge.stories.tsx
@@ -0,0 +1,301 @@
+import type {BadgeProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Avatar} from "../avatar";
+import {Separator} from "../separator";
+
+import {Badge} from "./index";
+
+export default {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["default", "accent", "success", "warning", "danger"],
+    },
+    placement: {
+      control: "select",
+      options: ["top-right", "top-left", "bottom-right", "bottom-left"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "soft"],
+    },
+  },
+  component: Badge,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Data Display/Badge",
+} as Meta<typeof Badge>;
+
+const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
+
+const defaultArgs: BadgeProps = {
+  color: "accent",
+  placement: "top-right",
+  size: "sm",
+  variant: "primary",
+};
+
+const Template = (props: BadgeProps) => (
+  <Badge.Anchor>
+    <Avatar>
+      <Avatar.Image src={AVATAR_URL} />
+    </Avatar>
+    <Badge {...props}>5</Badge>
+  </Badge.Anchor>
+);
+
+const SizesTemplate = (props: BadgeProps) => (
+  <div className="flex items-center gap-8">
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar size="lg">
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} size="lg">
+          99+
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Large</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar size="md">
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} size="md">
+          99+
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Medium</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar size="sm">
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} size="sm">
+          99+
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Small</span>
+    </div>
+  </div>
+);
+
+const ColorsTemplate = (props: BadgeProps) => {
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex items-center gap-8">
+      {colors.map((color) => (
+        <div key={color} className="flex flex-col items-center gap-2">
+          <Badge.Anchor>
+            <Avatar>
+              <Avatar.Image src={AVATAR_URL} />
+            </Avatar>
+            <Badge {...props} color={color} />
+          </Badge.Anchor>
+          <span className="text-xs text-muted capitalize">{color}</span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+const WithContentTemplate = (props: BadgeProps) => (
+  <div className="flex items-center gap-8">
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} color="danger">
+          5
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Number</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} color="danger">
+          New
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Text</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} color="danger">
+          99+
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Overflow</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Badge.Anchor>
+        <Avatar>
+          <Avatar.Image src={AVATAR_URL} />
+        </Avatar>
+        <Badge {...props} color="accent">
+          <Icon icon="gravity-ui:bell" />
+        </Badge>
+      </Badge.Anchor>
+      <span className="text-xs text-muted">Icon</span>
+    </div>
+  </div>
+);
+
+const PlacementsTemplate = () => {
+  const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
+
+  return (
+    <div className="flex items-center gap-8">
+      {placements.map((placement) => (
+        <div key={placement} className="flex flex-col items-center gap-2">
+          <Badge.Anchor>
+            <Avatar>
+              <Avatar.Image src={AVATAR_URL} />
+            </Avatar>
+            <Badge color="accent" placement={placement} size="sm" />
+          </Badge.Anchor>
+          <span className="text-xs text-muted">{placement}</span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+const VariantsTemplate = () => {
+  const variants = ["primary", "secondary", "soft"] as const;
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {variants.map((variant, index) => (
+        <React.Fragment key={variant}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted capitalize">{variant}</h3>
+            <div className="flex items-center gap-8">
+              {colors.map((color) => (
+                <div key={color} className="flex flex-col items-center gap-2">
+                  <Badge.Anchor>
+                    <Avatar>
+                      <Avatar.Image src={AVATAR_URL} />
+                    </Avatar>
+                    <Badge color={color} size="sm" variant={variant}>
+                      5
+                    </Badge>
+                  </Badge.Anchor>
+                  <span className="text-xs text-muted capitalize">{color}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+          {index < variants.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+};
+
+const DotBadgeTemplate = () => {
+  const colors = ["accent", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-4">
+        <h3 className="text-sm font-semibold text-muted">Status Indicators</h3>
+        <div className="flex items-center gap-8">
+          {colors.map((color) => (
+            <Badge.Anchor key={color}>
+              <Avatar size="sm">
+                <Avatar.Image src={AVATAR_URL} />
+              </Avatar>
+              <Badge color={color} placement="bottom-right" size="sm" />
+            </Badge.Anchor>
+          ))}
+        </div>
+      </div>
+      <Separator />
+      <div className="flex flex-col gap-4">
+        <h3 className="text-sm font-semibold text-muted">Sizes</h3>
+        <div className="flex items-center gap-8">
+          <div className="flex flex-col items-center gap-2">
+            <Badge.Anchor>
+              <Avatar size="lg">
+                <Avatar.Image src={AVATAR_URL} />
+              </Avatar>
+              <Badge color="success" placement="bottom-right" size="lg" />
+            </Badge.Anchor>
+            <span className="text-xs text-muted">Large</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Badge.Anchor>
+              <Avatar size="md">
+                <Avatar.Image src={AVATAR_URL} />
+              </Avatar>
+              <Badge color="success" placement="bottom-right" size="md" />
+            </Badge.Anchor>
+            <span className="text-xs text-muted">Medium</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Badge.Anchor>
+              <Avatar size="sm">
+                <Avatar.Image src={AVATAR_URL} />
+              </Avatar>
+              <Badge color="success" placement="bottom-right" size="sm" />
+            </Badge.Anchor>
+            <span className="text-xs text-muted">Small</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Sizes = {
+  args: defaultArgs,
+  render: SizesTemplate,
+};
+
+export const Colors = {
+  args: defaultArgs,
+  render: ColorsTemplate,
+};
+
+export const WithContent = {
+  args: defaultArgs,
+  render: WithContentTemplate,
+};
+
+export const Placements = {
+  render: PlacementsTemplate,
+};
+
+export const Variants = {
+  render: VariantsTemplate,
+};
+
+export const DotBadge = {
+  render: DotBadgeTemplate,
+};
diff --git a/packages/react/src/components/badge/badge.tsx b/packages/react/src/components/badge/badge.tsx
new file mode 100644
index 0000000..2586273
--- /dev/null
+++ b/packages/react/src/components/badge/badge.tsx
@@ -0,0 +1,135 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {BadgeVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {badgeVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {cx} from "tailwind-variants";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Badge Context
+ * -----------------------------------------------------------------------------------------------*/
+type BadgeContext = {
+  slots?: ReturnType<typeof badgeVariants>;
+};
+
+const BadgeContext = createContext<BadgeContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Badge Anchor
+ * -----------------------------------------------------------------------------------------------*/
+interface BadgeAnchorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+  children: ReactNode;
+}
+
+const BadgeAnchor = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: BadgeAnchorProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof BadgeAnchorProps<E>>) => {
+  return (
+    <dom.span
+      {...(props as any)}
+      className={cx("badge-anchor", className) ?? undefined}
+      data-slot="badge-anchor"
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Badge Root
+ * -----------------------------------------------------------------------------------------------*/
+interface BadgeRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  /** Badge color. */
+  color?: BadgeVariants["color"];
+  /** Badge placement. */
+  placement?: BadgeVariants["placement"];
+  /** Badge size. */
+  size?: BadgeVariants["size"];
+  /** Badge variant. */
+  variant?: BadgeVariants["variant"];
+}
+
+const BadgeRoot = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  color,
+  placement,
+  size,
+  variant,
+  ...props
+}: BadgeRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof BadgeRootProps<E>>) => {
+  const slots = React.useMemo(
+    () => badgeVariants({color, placement, size, variant}),
+    [color, placement, size, variant],
+  );
+
+  const badgeChildren = React.useMemo(() => {
+    if (typeof children === "string" || typeof children === "number") {
+      return <BadgeLabel>{children}</BadgeLabel>;
+    }
+
+    return children;
+  }, [children]);
+
+  return (
+    <BadgeContext value={{slots}}>
+      <dom.span
+        {...(props as any)}
+        className={composeSlotClassName(slots.base, className)}
+        data-slot="badge"
+      >
+        {badgeChildren}
+      </dom.span>
+    </BadgeContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Badge Label
+ * -----------------------------------------------------------------------------------------------*/
+interface BadgeLabelProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const BadgeLabel = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: BadgeLabelProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof BadgeLabelProps<E>>) => {
+  const {slots} = use(BadgeContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.label, className)}
+      data-slot="badge-label"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {BadgeRoot, BadgeLabel, BadgeAnchor};
+
+export type {BadgeRootProps, BadgeLabelProps, BadgeAnchorProps};
diff --git a/packages/react/src/components/badge/index.ts b/packages/react/src/components/badge/index.ts
new file mode 100644
index 0000000..d54d967
--- /dev/null
+++ b/packages/react/src/components/badge/index.ts
@@ -0,0 +1,38 @@
+import type {ComponentProps} from "react";
+
+import {BadgeAnchor, BadgeLabel, BadgeRoot} from "./badge";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Badge = Object.assign(BadgeRoot, {
+  Anchor: BadgeAnchor,
+  Label: BadgeLabel,
+  Root: BadgeRoot,
+});
+
+export type Badge = {
+  AnchorProps: ComponentProps<typeof BadgeAnchor>;
+  LabelProps: ComponentProps<typeof BadgeLabel>;
+  Props: ComponentProps<typeof BadgeRoot>;
+  RootProps: ComponentProps<typeof BadgeRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {BadgeRoot, BadgeLabel, BadgeAnchor};
+
+export type {
+  BadgeRootProps,
+  BadgeRootProps as BadgeProps,
+  BadgeLabelProps,
+  BadgeAnchorProps,
+} from "./badge";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {badgeVariants} from "@heroui/styles";
+
+export type {BadgeVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/breadcrumbs/breadcrumbs.stories.tsx b/packages/react/src/components/breadcrumbs/breadcrumbs.stories.tsx
new file mode 100644
index 0000000..977c809
--- /dev/null
+++ b/packages/react/src/components/breadcrumbs/breadcrumbs.stories.tsx
@@ -0,0 +1,80 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Breadcrumbs, BreadcrumbsItem} from "./index";
+
+const meta: Meta<typeof Breadcrumbs> = {
+  component: Breadcrumbs,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Navigation/Breadcrumbs",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DefaultTemplate = () => (
+  <Breadcrumbs>
+    <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Electronics</BreadcrumbsItem>
+    <BreadcrumbsItem>Laptop</BreadcrumbsItem>
+  </Breadcrumbs>
+);
+
+const Level3Template = () => (
+  <Breadcrumbs>
+    <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Category</BreadcrumbsItem>
+    <BreadcrumbsItem>Current Page</BreadcrumbsItem>
+  </Breadcrumbs>
+);
+
+const Level2Template = () => (
+  <Breadcrumbs>
+    <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+    <BreadcrumbsItem>Current Page</BreadcrumbsItem>
+  </Breadcrumbs>
+);
+
+const CustomSeparatorTemplate = () => (
+  <Breadcrumbs separator={<Icon icon="gravity-ui:caret-right" />}>
+    <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Electronics</BreadcrumbsItem>
+    <BreadcrumbsItem>Laptop</BreadcrumbsItem>
+  </Breadcrumbs>
+);
+
+const DisabledTemplate = () => (
+  <Breadcrumbs isDisabled>
+    <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
+    <BreadcrumbsItem href="#">Electronics</BreadcrumbsItem>
+    <BreadcrumbsItem>Laptop</BreadcrumbsItem>
+  </Breadcrumbs>
+);
+
+export const Default: Story = {
+  render: DefaultTemplate,
+};
+
+export const Level3: Story = {
+  render: Level3Template,
+};
+
+export const Level2: Story = {
+  render: Level2Template,
+};
+
+export const CustomSeparator: Story = {
+  render: CustomSeparatorTemplate,
+};
+
+export const Disabled: Story = {
+  render: DisabledTemplate,
+};
diff --git a/packages/react/src/components/breadcrumbs/breadcrumbs.tsx b/packages/react/src/components/breadcrumbs/breadcrumbs.tsx
new file mode 100644
index 0000000..b1695f3
--- /dev/null
+++ b/packages/react/src/components/breadcrumbs/breadcrumbs.tsx
@@ -0,0 +1,113 @@
+"use client";
+
+import type {LinkProps} from "../link";
+import type {BreadcrumbsVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {breadcrumbsVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  Breadcrumb as BreadcrumbPrimitive,
+  Breadcrumbs as BreadcrumbsPrimitive,
+} from "react-aria-components/Breadcrumbs";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {IconChevronRight} from "../icons";
+import {Link} from "../link";
+
+/* -------------------------------------------------------------------------------------------------
+ * Breadcrumbs Context
+ * -----------------------------------------------------------------------------------------------*/
+type BreadcrumbsContext = {
+  slots?: ReturnType<typeof breadcrumbsVariants>;
+  separator?: React.ReactNode;
+};
+
+const BreadcrumbsContext = createContext<BreadcrumbsContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Breadcrumbs Root
+ * -----------------------------------------------------------------------------------------------*/
+interface BreadcrumbsRootProps
+  extends ComponentPropsWithRef<typeof BreadcrumbsPrimitive>, BreadcrumbsVariants {
+  separator?: React.ReactNode;
+}
+
+const BreadcrumbsRoot = ({children, className, separator, ...props}: BreadcrumbsRootProps) => {
+  const slots = React.useMemo(() => breadcrumbsVariants({}), []);
+
+  return (
+    <BreadcrumbsContext.Provider value={{slots, separator}}>
+      <BreadcrumbsPrimitive
+        data-slot="breadcrumbs"
+        {...props}
+        className={composeSlotClassName(slots.base, className)}
+      >
+        {children}
+      </BreadcrumbsPrimitive>
+    </BreadcrumbsContext.Provider>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Breadcrumbs Item
+ * -----------------------------------------------------------------------------------------------*/
+interface BreadcrumbsItemProps extends ComponentPropsWithRef<typeof BreadcrumbPrimitive> {}
+
+const BreadcrumbsItem = ({
+  children,
+  className,
+  ...props
+}: BreadcrumbsItemProps & Omit<LinkProps, "className">) => {
+  const {separator, slots} = use(BreadcrumbsContext);
+
+  const renderSeparator = () => {
+    if (!separator)
+      return <IconChevronRight className={slots?.separator()} data-slot="breadcrumbs-separator" />;
+
+    if (React.isValidElement(separator)) {
+      return React.cloneElement(
+        separator as React.ReactElement<{
+          className?: string;
+          "data-slot": "breadcrumbs-separator";
+        }>,
+        {
+          className: slots?.separator(),
+          "data-slot": "breadcrumbs-separator",
+        },
+      );
+    }
+
+    return separator;
+  };
+
+  return (
+    <BreadcrumbPrimitive
+      className={composeTwRenderProps(className, slots?.item())}
+      data-slot="breadcrumbs-item"
+      {...props}
+    >
+      {({isCurrent}) => {
+        if (typeof children === "function") {
+          return children({} as any);
+        }
+
+        return (
+          <>
+            <Link className={slots?.link()} {...props}>
+              {children}
+            </Link>
+            {!isCurrent && renderSeparator()}
+          </>
+        );
+      }}
+    </BreadcrumbPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {BreadcrumbsRoot, BreadcrumbsItem};
+
+export type {BreadcrumbsRootProps, BreadcrumbsItemProps};
diff --git a/packages/react/src/components/breadcrumbs/index.ts b/packages/react/src/components/breadcrumbs/index.ts
new file mode 100644
index 0000000..69e09a6
--- /dev/null
+++ b/packages/react/src/components/breadcrumbs/index.ts
@@ -0,0 +1,35 @@
+import type {ComponentProps} from "react";
+
+import {BreadcrumbsItem, BreadcrumbsRoot} from "./breadcrumbs";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Breadcrumbs = Object.assign(BreadcrumbsRoot, {
+  Root: BreadcrumbsRoot,
+  Item: BreadcrumbsItem,
+});
+
+export type Breadcrumbs = {
+  Props: ComponentProps<typeof BreadcrumbsRoot>;
+  RootProps: ComponentProps<typeof BreadcrumbsRoot>;
+  ItemProps: ComponentProps<typeof BreadcrumbsItem>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {BreadcrumbsRoot, BreadcrumbsItem};
+
+export type {
+  BreadcrumbsRootProps,
+  BreadcrumbsRootProps as BreadcrumbsProps,
+  BreadcrumbsItemProps,
+} from "./breadcrumbs";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {breadcrumbsVariants} from "@heroui/styles";
+
+export type {BreadcrumbsVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/button-group/button-group.stories.tsx b/packages/react/src/components/button-group/button-group.stories.tsx
new file mode 100644
index 0000000..fc9d75a
--- /dev/null
+++ b/packages/react/src/components/button-group/button-group.stories.tsx
@@ -0,0 +1,489 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {Chip} from "../chip";
+import {Description} from "../description";
+import {Dropdown} from "../dropdown";
+import {Label} from "../label";
+
+import {ButtonGroup} from "./";
+
+const meta: Meta<typeof ButtonGroup> = {
+  component: ButtonGroup,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Buttons/ButtonGroup",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ButtonGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Second
+      </Button>
+      <Button>
+        <ButtonGroup.Separator />
+        Third
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Small</p>
+        <ButtonGroup size="sm">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Medium (default)</p>
+        <ButtonGroup size="md">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Large</p>
+        <ButtonGroup size="lg">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-3">
+      <ButtonGroup fullWidth>
+        <Button>First</Button>
+        <Button>
+          <ButtonGroup.Separator />
+          Second
+        </Button>
+        <Button>
+          <ButtonGroup.Separator />
+          Third
+        </Button>
+      </ButtonGroup>
+      <ButtonGroup fullWidth>
+        <Button isIconOnly>
+          <Icon icon="gravity-ui:text-align-left" />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <Icon icon="gravity-ui:text-align-center" />
+        </Button>
+        <Button isIconOnly>
+          <ButtonGroup.Separator />
+          <Icon icon="gravity-ui:text-align-right" />
+        </Button>
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Primary</p>
+        <ButtonGroup variant="primary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Secondary</p>
+        <ButtonGroup variant="secondary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Tertiary</p>
+        <ButtonGroup variant="tertiary">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Outline</p>
+        <ButtonGroup variant="outline">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Ghost</p>
+        <ButtonGroup variant="ghost">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Danger</p>
+        <ButtonGroup variant="danger">
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">All buttons disabled</p>
+        <ButtonGroup isDisabled>
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Third
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Group disabled, but one button overrides</p>
+        <ButtonGroup isDisabled>
+          <Button>First</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Second
+          </Button>
+          <Button isDisabled={false}>
+            <ButtonGroup.Separator />
+            Third (enabled)
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">With icons</p>
+        <ButtonGroup variant="secondary">
+          <Button>
+            <Icon icon="gravity-ui:globe" />
+            Search
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:plus" />
+            Add
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:trash-bin" />
+            Delete
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Icon only buttons</p>
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <Icon icon="gravity-ui:globe" />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:plus" />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:trash-bin" />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const WithoutSeparator: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const Examples: Story = {
+  render: () => (
+    <div className="flex flex-col items-start gap-8">
+      {/* Single button with dropdown */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Single button with dropdown</p>
+        <ButtonGroup>
+          <Button>Merge pull request</Button>
+          <Dropdown>
+            <Button isIconOnly aria-label="More options">
+              <ButtonGroup.Separator />
+              <Icon icon="gravity-ui:chevron-down" />
+            </Button>
+            <Dropdown.Popover className="max-w-[290px]" placement="bottom end">
+              <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="merge"
+                  textValue="Create a merge commit"
+                >
+                  <Label>Create a merge commit</Label>
+                  <Description>
+                    All commits from this branch will be added to the base branch
+                  </Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="squash-and-merge"
+                  textValue="Squash and merge"
+                >
+                  <Label>Squash and merge</Label>
+                  <Description>
+                    The 14 commits from this branch will be combined into one commit in the base
+                    branch
+                  </Description>
+                </Dropdown.Item>
+                <Dropdown.Item
+                  className="flex flex-col items-start gap-1"
+                  id="rebase-and-merge"
+                  textValue="Rebase and merge"
+                >
+                  <Label>Rebase and merge</Label>
+                  <Description>
+                    The 14 commits from this branch will be rebased and added to the base branch
+                  </Description>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown>
+        </ButtonGroup>
+      </div>
+
+      {/* Individual buttons */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Individual buttons</p>
+        <div className="flex gap-2">
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Icon className="size-3.5" icon="gravity-ui:code-fork" />
+              Fork
+              <Chip color="accent" size="sm" variant="soft">
+                24
+              </Chip>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <Icon icon="gravity-ui:chevron-down" />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button isIconOnly>
+              <Icon icon="gravity-ui:qr-code" />
+            </Button>
+            <Button>
+              <ButtonGroup.Separator />
+              Scan to pay
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Icon icon="gravity-ui:thumbs-up" />
+              <span className="text-xs font-semibold">2.4K</span>
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <Icon icon="gravity-ui:thumbs-down" />
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Icon className="size-3.5" icon="gravity-ui:star" />
+              Star
+            </Button>
+            <Button className="px-2">
+              <ButtonGroup.Separator />
+              <Chip color="accent" size="sm" variant="soft">
+                104
+              </Chip>
+            </Button>
+          </ButtonGroup>
+          <ButtonGroup variant="tertiary">
+            <Button>
+              <Icon icon="gravity-ui:pin" />
+              Pinned
+            </Button>
+            <Button isIconOnly>
+              <ButtonGroup.Separator />
+              <Icon icon="gravity-ui:chevron-down" />
+            </Button>
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* Previous/Next Button Group */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Previous/Next navigation</p>
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <Icon icon="gravity-ui:chevron-left" />
+            Previous
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Next
+            <Icon icon="gravity-ui:chevron-right" />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Content Selection Button Group */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Content selection</p>
+        <ButtonGroup variant="tertiary">
+          <Button>
+            <Icon icon="gravity-ui:picture" />
+            Photos
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:video" />
+            Videos
+          </Button>
+          <Button isIconOnly aria-label="More options">
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:ellipsis" />
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Text Alignment Button Group */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Text alignment</p>
+        <ButtonGroup variant="tertiary">
+          <Button>Left</Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Center
+          </Button>
+          <Button>
+            <ButtonGroup.Separator />
+            Right
+          </Button>
+        </ButtonGroup>
+      </div>
+
+      {/* Icon-Only Alignment Button Group */}
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Icon-only alignment</p>
+        <ButtonGroup variant="tertiary">
+          <Button isIconOnly>
+            <Icon icon="gravity-ui:text-align-left" />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:text-align-center" />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:text-align-right" />
+          </Button>
+          <Button isIconOnly>
+            <ButtonGroup.Separator />
+            <Icon icon="gravity-ui:text-align-justify" />
+          </Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/button-group/button-group.tsx b/packages/react/src/components/button-group/button-group.tsx
new file mode 100644
index 0000000..0f6549f
--- /dev/null
+++ b/packages/react/src/components/button-group/button-group.tsx
@@ -0,0 +1,121 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ButtonProps} from "../button";
+import type {ButtonGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {buttonGroupVariants} from "@heroui/styles";
+import React, {Children, createContext, isValidElement, use} from "react";
+import {Group} from "react-aria-components/Group";
+import {useSlottedContext} from "react-aria-components/slots";
+import {ToggleButtonGroupContext as RACToggleButtonGroupContext} from "react-aria-components/ToggleButtonGroup";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ButtonGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type ButtonGroupContext = {
+  slots?: ReturnType<typeof buttonGroupVariants>;
+  size?: ButtonProps["size"];
+  variant?: ButtonProps["variant"];
+  isDisabled?: ButtonProps["isDisabled"];
+  fullWidth?: ButtonProps["fullWidth"];
+};
+
+const ButtonGroupContext = createContext<ButtonGroupContext>({});
+
+// Property name to mark direct children of ButtonGroup
+export const BUTTON_GROUP_CHILD = "__button_group_child";
+
+/* -------------------------------------------------------------------------------------------------
+ * ButtonGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ButtonGroupRootProps
+  extends
+    ComponentPropsWithRef<typeof Group>,
+    Pick<ButtonProps, "size" | "variant">,
+    ButtonGroupVariants {
+  /** The orientation of the button group */
+  orientation?: "horizontal" | "vertical";
+}
+
+const ButtonGroupRoot = ({
+  children,
+  className,
+  fullWidth,
+  isDisabled,
+  orientation: orientationProp,
+  size,
+  variant,
+  ...rest
+}: ButtonGroupRootProps) => {
+  const racContext = useSlottedContext(RACToggleButtonGroupContext);
+  const orientation = orientationProp ?? racContext?.orientation ?? "horizontal";
+
+  const slots = React.useMemo(
+    () => buttonGroupVariants({fullWidth, orientation}),
+    [fullWidth, orientation],
+  );
+
+  // Wrap only direct children with context provider
+  const wrappedChildren = Children.map(children as React.ReactNode, (child) => {
+    if (!isValidElement(child)) {
+      return child;
+    }
+
+    // Clone the child and add the special prop
+    return React.cloneElement(child, {
+      [BUTTON_GROUP_CHILD]: true,
+    } as any);
+  });
+
+  return (
+    <ButtonGroupContext value={{slots, size, variant, isDisabled, fullWidth}}>
+      <Group
+        className={composeTwRenderProps(className, slots.base())}
+        data-slot="button-group"
+        isDisabled={isDisabled}
+        {...rest}
+      >
+        {wrappedChildren}
+      </Group>
+    </ButtonGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ButtonGroup Separator
+ * -----------------------------------------------------------------------------------------------*/
+interface ButtonGroupSeparatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ButtonGroupSeparator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: ButtonGroupSeparatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ButtonGroupSeparatorProps<E>>) => {
+  const {slots} = use(ButtonGroupContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.separator, className)}
+      data-slot="button-group-separator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ButtonGroupRoot, ButtonGroupSeparator, ButtonGroupContext};
+
+export type {ButtonGroupRootProps, ButtonGroupSeparatorProps};
diff --git a/packages/react/src/components/button-group/index.ts b/packages/react/src/components/button-group/index.ts
new file mode 100644
index 0000000..1695f62
--- /dev/null
+++ b/packages/react/src/components/button-group/index.ts
@@ -0,0 +1,40 @@
+import type {ComponentProps} from "react";
+
+import {ButtonGroupRoot, ButtonGroupSeparator} from "./button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ButtonGroup = Object.assign(ButtonGroupRoot, {
+  Root: ButtonGroupRoot,
+  Separator: ButtonGroupSeparator,
+});
+
+export type ButtonGroup = {
+  Props: ComponentProps<typeof ButtonGroupRoot>;
+  RootProps: ComponentProps<typeof ButtonGroupRoot>;
+  SeparatorProps: ComponentProps<typeof ButtonGroupSeparator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ButtonGroupRoot, ButtonGroupSeparator};
+
+export type {
+  ButtonGroupRootProps,
+  ButtonGroupRootProps as ButtonGroupProps,
+  ButtonGroupSeparatorProps,
+} from "./button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Context
+ * -----------------------------------------------------------------------------------------------*/
+export {ButtonGroupContext, BUTTON_GROUP_CHILD} from "./button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {buttonGroupVariants} from "@heroui/styles";
+
+export type {ButtonGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/button/button.stories.tsx b/packages/react/src/components/button/button.stories.tsx
new file mode 100644
index 0000000..23e6db7
--- /dev/null
+++ b/packages/react/src/components/button/button.stories.tsx
@@ -0,0 +1,257 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useState} from "react";
+
+import {Spinner} from "../spinner";
+
+import {Button, buttonVariants} from "./index";
+
+export default {
+  argTypes: {
+    isDisabled: {
+      control: "boolean",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "tertiary", "outline", "ghost", "danger"],
+    },
+  },
+  component: Button,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Buttons/Button",
+} as Meta<typeof Button>;
+
+const defaultArgs: Button["RootProps"] = {
+  size: "md",
+};
+
+const Template = ({isDisabled, size}: Button["RootProps"]) => (
+  <div className="flex gap-3">
+    <Button isDisabled={isDisabled} size={size}>
+      Primary
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="secondary">
+      Secondary
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="tertiary">
+      Tertiary
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="outline">
+      Outline
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="ghost">
+      Ghost
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="danger">
+      Danger
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="danger-soft">
+      Danger Soft
+    </Button>
+  </div>
+);
+
+const TemplateWithLinkButton = ({isIconOnly, size, variant}: Button["RootProps"]) => (
+  <div className="flex flex-col gap-3">
+    <div className="flex gap-3">
+      <a
+        className={buttonVariants({size, variant, isIconOnly})}
+        href="https://www.google.com"
+        rel="noopener noreferrer"
+        target="_blank"
+      >
+        Google
+      </a>
+    </div>
+  </div>
+);
+
+const TemplateWithIcon = ({isDisabled, size}: Button["RootProps"]) => (
+  <div className="flex gap-3">
+    <Button isDisabled={isDisabled} size={size}>
+      <Icon icon="gravity-ui:globe" />
+      Search
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="secondary">
+      <Icon icon="gravity-ui:plus" />
+      Add Member
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="tertiary">
+      <Icon icon="gravity-ui:envelope" />
+      Email
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="danger">
+      <Icon icon="gravity-ui:trash-bin" />
+      Delete
+    </Button>
+    <Button isDisabled={isDisabled} size={size} variant="danger-soft">
+      <Icon icon="gravity-ui:trash-bin" />
+      Cancel
+    </Button>
+  </div>
+);
+
+const TemplateWithIconOnly = ({isDisabled, size, variant}: Button["RootProps"]) => (
+  <div className="flex gap-3">
+    <Button isIconOnly isDisabled={isDisabled} size={size} variant={variant ?? "tertiary"}>
+      <Icon icon="gravity-ui:ellipsis" />
+    </Button>
+  </div>
+);
+
+const TemplateWithSpinner = ({size, variant}: Button["RootProps"]) => (
+  <div className="flex gap-3">
+    <Button isPending size={size} variant={variant}>
+      <Spinner color="current" size="sm" />
+      Loading
+    </Button>
+  </div>
+);
+
+const TemplateWithLoadingState = ({size, variant}: Button["RootProps"]) => {
+  const [isLoading, setLoading] = useState(false);
+
+  const handlePress = () => {
+    setLoading(true);
+    setTimeout(() => {
+      setLoading(false);
+    }, 4500);
+  };
+
+  return (
+    <Button isPending={isLoading} size={size} variant={variant ?? "tertiary"} onPress={handlePress}>
+      {({isPending}) => (
+        <>
+          {isPending ? <Spinner color="current" size="sm" /> : <Icon icon="gravity-ui:paperclip" />}
+          {isLoading ? "Uploading..." : "Upload File"}
+        </>
+      )}
+    </Button>
+  );
+};
+
+const SizesTemplate = () => (
+  <div className="flex flex-col gap-6">
+    <div className="flex items-center gap-3">
+      <Button size="sm">Small</Button>
+      <Button size="md">Medium</Button>
+      <Button size="lg">Large</Button>
+    </div>
+    <div className="flex items-center gap-3">
+      <Button size="sm" variant="secondary">
+        <Icon icon="gravity-ui:plus" />
+        Small
+      </Button>
+      <Button size="md" variant="secondary">
+        <Icon icon="gravity-ui:plus" />
+        Medium
+      </Button>
+      <Button size="lg" variant="secondary">
+        <Icon icon="gravity-ui:plus" />
+        Large
+      </Button>
+    </div>
+    <div className="flex items-center gap-3">
+      <Button isIconOnly size="sm" variant="tertiary">
+        <Icon icon="gravity-ui:ellipsis" />
+      </Button>
+      <Button isIconOnly size="md" variant="tertiary">
+        <Icon icon="gravity-ui:ellipsis" />
+      </Button>
+      <Button isIconOnly size="lg" variant="tertiary">
+        <Icon icon="gravity-ui:ellipsis" />
+      </Button>
+    </div>
+  </div>
+);
+
+const TemplateWithSocialButton = ({size, variant}: Button["RootProps"]) => (
+  <div className="flex w-full max-w-xs flex-col gap-3">
+    <Button size={size} variant={variant ?? "tertiary"}>
+      <Icon icon="devicon:google" />
+      Sign in with Google
+    </Button>
+    <Button size={size} variant={variant ?? "tertiary"}>
+      <Icon icon="mdi:github" />
+      Sign in with GitHub
+    </Button>
+    <Button size={size} variant={variant ?? "tertiary"}>
+      <Icon icon="ion:logo-apple" />
+      Sign in with Apple
+    </Button>
+    <Button size={size} variant={variant ?? "tertiary"}>
+      <Icon icon="typcn:social-linkedin" />
+      Sign in with LinkedIn
+    </Button>
+  </div>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithLinkButton = {
+  args: defaultArgs,
+  render: TemplateWithLinkButton,
+};
+
+export const Sizes = {
+  render: SizesTemplate,
+};
+
+export const FullWidth = {
+  render: () => (
+    <div className="w-[400px] space-y-3">
+      <Button fullWidth>Primary</Button>
+      <Button fullWidth variant="secondary">
+        Secondary
+      </Button>
+      <Button fullWidth variant="tertiary">
+        Tertiary
+      </Button>
+      <Button fullWidth size="sm">
+        Small
+      </Button>
+      <Button fullWidth size="lg">
+        Large
+      </Button>
+      <Button fullWidth>
+        <Icon icon="gravity-ui:plus" />
+        With Icon
+      </Button>
+    </div>
+  ),
+};
+
+export const WithIcon = {
+  args: defaultArgs,
+  render: TemplateWithIcon,
+};
+
+export const WithIconOnly = {
+  args: defaultArgs,
+  render: TemplateWithIconOnly,
+};
+
+export const WithSpinner = {
+  args: defaultArgs,
+  render: TemplateWithSpinner,
+};
+
+export const WithLoadingState = {
+  args: defaultArgs,
+  render: TemplateWithLoadingState,
+};
+
+export const WithSocialButton = {
+  args: defaultArgs,
+  render: TemplateWithSocialButton,
+};
diff --git a/packages/react/src/components/button/button.tsx b/packages/react/src/components/button/button.tsx
new file mode 100644
index 0000000..64d602d
--- /dev/null
+++ b/packages/react/src/components/button/button.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import type {ButtonVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {buttonVariants} from "@heroui/styles";
+import {use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+
+import {composeTwRenderProps} from "../../utils";
+import {BUTTON_GROUP_CHILD, ButtonGroupContext} from "../button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Button Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ButtonRootProps extends ComponentPropsWithRef<typeof ButtonPrimitive>, ButtonVariants {
+  [BUTTON_GROUP_CHILD]?: boolean;
+}
+
+const ButtonRoot = ({
+  children,
+  className,
+  fullWidth,
+  isDisabled,
+  isIconOnly,
+  size,
+  slot,
+  style,
+  variant,
+  [BUTTON_GROUP_CHILD]: isButtonGroupChild,
+  ...rest
+}: ButtonRootProps) => {
+  const buttonGroupContext = use(ButtonGroupContext);
+
+  // Only use context if this button is a direct child of ButtonGroup
+  const shouldUseContext = isButtonGroupChild === true;
+
+  // Merge props with precedence: direct props > context props
+  const finalSize = size ?? (shouldUseContext ? buttonGroupContext?.size : undefined);
+  const finalVariant = variant ?? (shouldUseContext ? buttonGroupContext?.variant : undefined);
+  const finalIsDisabled =
+    isDisabled ?? (shouldUseContext ? buttonGroupContext?.isDisabled : undefined);
+  const finalFullWidth =
+    fullWidth ?? (shouldUseContext ? buttonGroupContext?.fullWidth : undefined);
+
+  const styles = buttonVariants({
+    fullWidth: finalFullWidth,
+    isIconOnly,
+    size: finalSize,
+    variant: finalVariant,
+  });
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, styles)}
+      data-slot="button"
+      isDisabled={finalIsDisabled}
+      slot={slot}
+      style={style}
+      {...rest}
+    >
+      {(renderProps) => (typeof children === "function" ? children(renderProps) : children)}
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ButtonRoot};
+
+export type {ButtonRootProps};
diff --git a/packages/react/src/components/button/index.ts b/packages/react/src/components/button/index.ts
new file mode 100644
index 0000000..c139945
--- /dev/null
+++ b/packages/react/src/components/button/index.ts
@@ -0,0 +1,36 @@
+import type {ComponentProps} from "react";
+
+import {BUTTON_GROUP_CHILD} from "../button-group";
+
+import {ButtonRoot} from "./button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Button = Object.assign(ButtonRoot, {
+  Root: ButtonRoot,
+});
+
+export type Button = {
+  Props: ComponentProps<typeof ButtonRoot>;
+  RootProps: ComponentProps<typeof ButtonRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ButtonRoot};
+
+export type {ButtonRootProps, ButtonRootProps as ButtonProps} from "./button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Re-export BUTTON_GROUP_CHILD for type declarations
+ * -----------------------------------------------------------------------------------------------*/
+export {BUTTON_GROUP_CHILD};
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {buttonVariants} from "@heroui/styles";
+
+export type {ButtonVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/calendar-year-picker/calendar-year-picker.tsx b/packages/react/src/components/calendar-year-picker/calendar-year-picker.tsx
new file mode 100644
index 0000000..2505afa
--- /dev/null
+++ b/packages/react/src/components/calendar-year-picker/calendar-year-picker.tsx
@@ -0,0 +1,611 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {CalendarYearPickerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {CalendarHeadingProps, CalendarYearPickerProps} from "react-aria/useCalendar";
+
+import {calendarYearPickerVariants} from "@heroui/styles";
+import React from "react";
+import {useCalendarHeading, useCalendarYearPicker} from "react-aria/useCalendar";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+
+import {getYearRange} from "../../utils/calendar";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronRight} from "../icons";
+
+import {useCalendarOrRangeState} from "./use-calendar-state";
+import {useYearPicker} from "./year-picker-context";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerTrigger
+ *
+ * Replaces Calendar.Heading. Shows "Month Year" with a chevron that rotates
+ * when the year picker is open.  Toggles isYearPickerOpen from CalendarBaseContext.
+ * -----------------------------------------------------------------------------------------------*/
+interface CalendarYearPickerTriggerProps
+  extends
+    Omit<ComponentPropsWithRef<typeof ButtonPrimitive>, "children">,
+    CalendarYearPickerVariants {
+  children: React.ReactNode | ((values: CalendarYearPickerTriggerRenderProps) => React.ReactNode);
+}
+
+interface CalendarYearPickerTriggerRenderProps {
+  isOpen: boolean;
+  monthYear: string;
+  toggle: () => void;
+}
+
+interface CalendarYearPickerTriggerHeadingProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+>
+  extends
+    DOMRenderProps<E, undefined>,
+    CalendarYearPickerVariants,
+    Pick<CalendarHeadingProps, "offset" | "format"> {
+  children?: ReactNode | ((values: CalendarYearPickerTriggerRenderProps) => ReactNode);
+  className?: string;
+}
+
+interface CalendarYearPickerTriggerIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+>
+  extends DOMRenderProps<E, undefined>, CalendarYearPickerVariants {
+  children?: ReactNode | ((values: CalendarYearPickerTriggerRenderProps) => ReactNode);
+  className?: string;
+}
+
+interface CalendarYearPickerTriggerContextValue extends CalendarYearPickerTriggerRenderProps {
+  slots: ReturnType<typeof calendarYearPickerVariants>;
+}
+
+const CalendarYearPickerTriggerContext =
+  React.createContext<CalendarYearPickerTriggerContextValue | null>(null);
+
+function useCalendarYearPickerTriggerContext(): CalendarYearPickerTriggerContextValue {
+  const context = React.use(CalendarYearPickerTriggerContext);
+
+  if (!context) {
+    throw new Error(
+      "CalendarYearPicker trigger components must be used within <CalendarYearPicker.Trigger>.",
+    );
+  }
+
+  return context;
+}
+
+const CalendarYearPickerTrigger = ({
+  children,
+  className,
+  onKeyDown,
+  onPress,
+  ...props
+}: CalendarYearPickerTriggerProps) => {
+  const {isYearPickerOpen, setIsYearPickerOpen} = useYearPicker();
+  const state = useCalendarOrRangeState();
+  const monthYear = useCalendarHeading({}, state);
+
+  const slots = React.useMemo(() => calendarYearPickerVariants(), []);
+
+  const handleToggle = React.useCallback(() => {
+    setIsYearPickerOpen(!isYearPickerOpen);
+  }, [isYearPickerOpen, setIsYearPickerOpen]);
+
+  const handleKeyDown = (
+    e: Parameters<NonNullable<CalendarYearPickerTriggerProps["onKeyDown"]>>[0],
+  ) => {
+    onKeyDown?.(e);
+
+    if (e.defaultPrevented) {
+      return;
+    }
+
+    if (e.key === "Escape" && isYearPickerOpen) {
+      e.preventDefault();
+      setIsYearPickerOpen(false);
+    }
+  };
+
+  const values: CalendarYearPickerTriggerRenderProps = React.useMemo(
+    () => ({
+      isOpen: isYearPickerOpen,
+      monthYear,
+      toggle: handleToggle,
+    }),
+    [handleToggle, isYearPickerOpen, monthYear],
+  );
+
+  const contextValue = React.useMemo(
+    () => ({
+      ...values,
+      slots,
+    }),
+    [slots, values],
+  );
+
+  return (
+    <CalendarYearPickerTriggerContext value={contextValue}>
+      <ButtonPrimitive
+        aria-expanded={isYearPickerOpen}
+        aria-label={`${monthYear}, year selector`}
+        className={composeTwRenderProps(className, slots.trigger())}
+        data-open={isYearPickerOpen || undefined}
+        data-slot="calendar-year-picker-trigger"
+        slot={null}
+        onKeyDown={handleKeyDown}
+        onPress={(event) => {
+          onPress?.(event);
+          handleToggle();
+        }}
+        {...props}
+      >
+        {typeof children === "function" ? children(values) : children}
+      </ButtonPrimitive>
+    </CalendarYearPickerTriggerContext>
+  );
+};
+
+CalendarYearPickerTrigger.displayName = "HeroUI.CalendarYearPicker.Trigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerTriggerHeading
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarYearPickerTriggerHeading = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  format,
+  offset,
+  ...props
+}: CalendarYearPickerTriggerHeadingProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CalendarYearPickerTriggerHeadingProps<E>>) => {
+  const {monthYear, slots, ...values} = useCalendarYearPickerTriggerContext();
+  const state = useCalendarOrRangeState();
+  const heading = useCalendarHeading({format, offset}, state);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots.triggerHeading, className)}
+      data-slot="calendar-year-picker-trigger-heading"
+      {...(props as any)}
+    >
+      {typeof children === "function" ? children({monthYear, ...values}) : children || heading}
+    </dom.span>
+  );
+};
+
+CalendarYearPickerTriggerHeading.displayName = "HeroUI.CalendarYearPicker.TriggerHeading";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerTriggerIndicator
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarYearPickerTriggerIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: CalendarYearPickerTriggerIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CalendarYearPickerTriggerIndicatorProps<E>>) => {
+  const {monthYear, slots, ...values} = useCalendarYearPickerTriggerContext();
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots.triggerIndicator, className)}
+      data-slot="calendar-year-picker-trigger-indicator"
+      {...(props as any)}
+    >
+      {typeof children === "function"
+        ? children({monthYear, ...values})
+        : children || <IconChevronRight height="1em" width="1em" />}
+    </dom.span>
+  );
+};
+
+CalendarYearPickerTriggerIndicator.displayName = "HeroUI.CalendarYearPicker.TriggerIndicator";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerGrid
+ *
+ * Renders a 3-column grid of year buttons. Hidden via CSS opacity when closed,
+ * visible when data-open="true".  tabIndex is toggled so only the active view
+ * receives keyboard focus.
+ * -----------------------------------------------------------------------------------------------*/
+interface CalendarYearPickerGridProps<E extends keyof React.JSX.IntrinsicElements = "div">
+  extends
+    DOMRenderProps<E, undefined>,
+    CalendarYearPickerVariants,
+    Pick<CalendarYearPickerProps, "format" | "visibleYears"> {
+  children?: ReactNode;
+  className?: string;
+}
+
+interface CalendarYearPickerCellRenderProps {
+  year: number;
+  formattedYear: string;
+  isSelected: boolean;
+  isCurrentYear: boolean;
+  isOpen: boolean;
+  selectYear: () => void;
+}
+
+interface CalendarYearPickerGridBodyProps {
+  children?: (values: CalendarYearPickerCellRenderProps) => React.ReactNode;
+}
+
+interface CalendarYearPickerCellProps
+  extends
+    Omit<ComponentPropsWithRef<typeof ButtonPrimitive>, "children">,
+    CalendarYearPickerVariants {
+  year: number;
+  children?: React.ReactNode | ((values: CalendarYearPickerCellRenderProps) => React.ReactNode);
+}
+
+interface CalendarYearPickerGridContextValue {
+  slots: ReturnType<typeof calendarYearPickerVariants>;
+  isYearPickerOpen: boolean;
+  activeYear: number;
+  focusedYear: number;
+  years: number[];
+  getFormattedYear: (year: number) => string;
+  selectYear: (year: number) => void;
+  setActiveYear: (year: number) => void;
+}
+
+const CalendarYearPickerGridContext =
+  React.createContext<CalendarYearPickerGridContextValue | null>(null);
+
+function useCalendarYearPickerGridContext(): CalendarYearPickerGridContextValue {
+  const context = React.use(CalendarYearPickerGridContext);
+
+  if (!context) {
+    throw new Error("CalendarYearPicker components must be used within <CalendarYearPicker.Grid>.");
+  }
+
+  return context;
+}
+
+const CalendarYearPickerGrid = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  format,
+  onKeyDown,
+  visibleYears: visibleYearsProp,
+  ...props
+}: CalendarYearPickerGridProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CalendarYearPickerGridProps<E>>) => {
+  const {calendarGridSlot, calendarRef, isYearPickerOpen, setIsYearPickerOpen} = useYearPicker();
+  const state = useCalendarOrRangeState();
+  const gridRef = React.useRef<HTMLDivElement>(null);
+
+  const slots = React.useMemo(() => calendarYearPickerVariants(), []);
+
+  const visibleYears = React.useMemo(() => {
+    if (visibleYearsProp != null) {
+      return visibleYearsProp;
+    }
+
+    if (!state.minValue || !state.maxValue) {
+      return 20;
+    }
+
+    return getYearRange(state.minValue, state.maxValue).length;
+  }, [state.maxValue, state.minValue, visibleYearsProp]);
+
+  const {
+    "aria-label": yearGridAriaLabel,
+    items,
+    onChange,
+    value: focusedItemId,
+  } = useCalendarYearPicker({format, visibleYears}, state);
+
+  // useCalendarYearPicker returns a new `items` array every render — derive a stable
+  // key so effects don't re-run and steal focus back to the selected year.
+  const itemsKey = items.map((item) => `${item.id}:${item.date.year}`).join("|");
+  const years = items.map((item) => item.date.year);
+  const itemByYear = new Map(items.map((item) => [item.date.year, item]));
+  const focusedYear = items[focusedItemId as number]?.date.year ?? state.focusedDate.year;
+
+  const getFormattedYear = React.useCallback(
+    (year: number) => itemByYear.get(year)?.formatted ?? String(year),
+    [itemByYear],
+  );
+
+  const [activeYear, setActiveYear] = React.useState(focusedYear);
+  const wasYearPickerOpenRef = React.useRef(false);
+
+  // Position the year grid to overlay the day grid
+  React.useEffect(() => {
+    const yearGrid = gridRef.current;
+
+    if (!yearGrid) return;
+
+    const calendar = calendarRef.current;
+    const calendarGrid = calendar?.querySelector(
+      `[data-slot='${calendarGridSlot}']`,
+    ) as HTMLElement | null;
+
+    if (calendarGrid) {
+      yearGrid.style.top = `${calendarGrid.offsetTop}px`;
+      yearGrid.style.height = `${calendarGrid.offsetHeight}px`;
+    }
+  }, [calendarGridSlot, calendarRef, state.focusedDate]);
+
+  const focusYearCell = React.useCallback((year: number) => {
+    const yearGrid = gridRef.current;
+
+    if (!yearGrid) return;
+
+    const yearCell = yearGrid.querySelector<HTMLElement>(`[data-year='${year}']`);
+
+    if (yearCell) {
+      yearCell.focus();
+    }
+  }, []);
+
+  // Anchor keyboard focus to the selected year only when the picker opens — not on
+  // every render while open (items from useCalendarYearPicker is unstable).
+  React.useEffect(() => {
+    const justOpened = isYearPickerOpen && !wasYearPickerOpenRef.current;
+
+    wasYearPickerOpenRef.current = isYearPickerOpen;
+
+    if (!justOpened || years.length === 0) return;
+
+    const [firstYear] = years;
+
+    if (firstYear == null) return;
+
+    const nextActiveYear = years.includes(focusedYear) ? focusedYear : firstYear;
+
+    setActiveYear(nextActiveYear);
+
+    const rafId = requestAnimationFrame(() => {
+      focusYearCell(nextActiveYear);
+    });
+
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, [focusYearCell, focusedYear, isYearPickerOpen, itemsKey, years.length]);
+
+  React.useEffect(() => {
+    if (!isYearPickerOpen || years.length === 0) return;
+
+    const [firstYear] = years;
+
+    if (firstYear == null) return;
+
+    if (!years.includes(activeYear)) {
+      setActiveYear(firstYear);
+    }
+  }, [activeYear, isYearPickerOpen, itemsKey, years]);
+
+  const handleYearSelect = React.useCallback(
+    (year: number) => {
+      const item = itemByYear.get(year);
+
+      if (item == null) {
+        return;
+      }
+
+      setIsYearPickerOpen(false);
+      onChange(item.id);
+    },
+    [itemByYear, onChange, setIsYearPickerOpen],
+  );
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    (onKeyDown as React.KeyboardEventHandler<HTMLDivElement>)?.(e);
+
+    if (e.defaultPrevented) {
+      return;
+    }
+
+    if (e.key === "Escape" && isYearPickerOpen) {
+      e.preventDefault();
+      setIsYearPickerOpen(false);
+
+      return;
+    }
+
+    if (!isYearPickerOpen || years.length === 0) {
+      return;
+    }
+
+    const currentIndex = years.indexOf(activeYear);
+
+    if (currentIndex === -1) {
+      return;
+    }
+
+    let nextIndex = currentIndex;
+
+    switch (e.key) {
+      case "ArrowRight":
+        nextIndex = Math.min(currentIndex + 1, years.length - 1);
+        break;
+      case "ArrowLeft":
+        nextIndex = Math.max(currentIndex - 1, 0);
+        break;
+      case "ArrowDown":
+        nextIndex = Math.min(currentIndex + 3, years.length - 1);
+        break;
+      case "ArrowUp":
+        nextIndex = Math.max(currentIndex - 3, 0);
+        break;
+      case "Home":
+        nextIndex = 0;
+        break;
+      case "End":
+        nextIndex = years.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    if (nextIndex !== currentIndex) {
+      const nextYear = years[nextIndex];
+
+      if (nextYear == null) return;
+
+      e.preventDefault();
+      setActiveYear(nextYear);
+      focusYearCell(nextYear);
+    }
+  };
+
+  const contextValue = React.useMemo(
+    () => ({
+      activeYear,
+      focusedYear,
+      getFormattedYear,
+      isYearPickerOpen,
+      selectYear: handleYearSelect,
+      setActiveYear,
+      slots,
+      years,
+    }),
+    [activeYear, focusedYear, getFormattedYear, handleYearSelect, isYearPickerOpen, slots, years],
+  );
+
+  return (
+    <CalendarYearPickerGridContext value={contextValue}>
+      <dom.div
+        ref={gridRef}
+        aria-hidden={!isYearPickerOpen}
+        aria-label={yearGridAriaLabel}
+        className={composeSlotClassName(slots.yearGrid, className)}
+        data-open={isYearPickerOpen || undefined}
+        data-slot="calendar-year-picker-grid"
+        role="listbox"
+        tabIndex={-1}
+        onKeyDown={handleKeyDown}
+        {...(props as any)}
+      >
+        {children}
+      </dom.div>
+    </CalendarYearPickerGridContext>
+  );
+};
+
+CalendarYearPickerGrid.displayName = "HeroUI.CalendarYearPicker.Grid";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerGridBody
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarYearPickerGridBody = ({children}: CalendarYearPickerGridBodyProps) => {
+  const {focusedYear, getFormattedYear, isYearPickerOpen, selectYear, years} =
+    useCalendarYearPickerGridContext();
+  const currentYear = new Date().getFullYear();
+
+  return (
+    <>
+      {years.map((year) => {
+        const isSelected = year === focusedYear;
+        const formattedYear = getFormattedYear(year);
+        const values: CalendarYearPickerCellRenderProps = {
+          formattedYear,
+          isCurrentYear: year === currentYear,
+          isOpen: isYearPickerOpen,
+          isSelected,
+          selectYear: () => selectYear(year),
+          year,
+        };
+
+        return (
+          <React.Fragment key={year}>
+            {typeof children === "function" ? (
+              children(values)
+            ) : (
+              <CalendarYearPickerCell year={year} />
+            )}
+          </React.Fragment>
+        );
+      })}
+    </>
+  );
+};
+
+CalendarYearPickerGridBody.displayName = "HeroUI.CalendarYearPicker.GridBody";
+
+/* -------------------------------------------------------------------------------------------------
+ * CalendarYearPickerCell
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarYearPickerCell = ({
+  children,
+  className,
+  excludeFromTabOrder,
+  onFocus,
+  onPress,
+  year,
+  ...props
+}: CalendarYearPickerCellProps) => {
+  const {
+    activeYear,
+    focusedYear,
+    getFormattedYear,
+    isYearPickerOpen,
+    selectYear,
+    setActiveYear,
+    slots,
+  } = useCalendarYearPickerGridContext();
+  const isSelected = year === focusedYear;
+  const isActive = year === activeYear;
+  const formattedYear = getFormattedYear(year);
+  const values: CalendarYearPickerCellRenderProps = {
+    formattedYear,
+    isCurrentYear: year === new Date().getFullYear(),
+    isOpen: isYearPickerOpen,
+    isSelected,
+    selectYear: () => selectYear(year),
+    year,
+  };
+
+  return (
+    <ButtonPrimitive
+      aria-label={formattedYear}
+      aria-selected={isSelected}
+      className={composeTwRenderProps(className, slots.yearCell())}
+      data-selected={isSelected || undefined}
+      data-slot="calendar-year-picker-year-cell"
+      data-year={year}
+      excludeFromTabOrder={excludeFromTabOrder ?? !(isYearPickerOpen && isActive)}
+      slot={null}
+      onFocus={(event) => {
+        onFocus?.(event);
+        setActiveYear(year);
+      }}
+      onPress={(event) => {
+        onPress?.(event);
+        selectYear(year);
+      }}
+      {...props}
+    >
+      {typeof children === "function" ? children(values) : children || formattedYear}
+    </ButtonPrimitive>
+  );
+};
+
+CalendarYearPickerCell.displayName = "HeroUI.CalendarYearPicker.Cell";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  CalendarYearPickerTrigger,
+  CalendarYearPickerTriggerHeading,
+  CalendarYearPickerTriggerIndicator,
+  CalendarYearPickerGrid,
+  CalendarYearPickerGridBody,
+  CalendarYearPickerCell,
+};
+export type {
+  CalendarYearPickerTriggerProps,
+  CalendarYearPickerTriggerHeadingProps,
+  CalendarYearPickerTriggerIndicatorProps,
+  CalendarYearPickerTriggerRenderProps,
+  CalendarYearPickerGridProps,
+  CalendarYearPickerGridBodyProps,
+  CalendarYearPickerCellProps,
+  CalendarYearPickerCellRenderProps,
+};
diff --git a/packages/react/src/components/calendar-year-picker/index.ts b/packages/react/src/components/calendar-year-picker/index.ts
new file mode 100644
index 0000000..c1becc8
--- /dev/null
+++ b/packages/react/src/components/calendar-year-picker/index.ts
@@ -0,0 +1,68 @@
+import type {ComponentProps} from "react";
+
+import {
+  CalendarYearPickerCell,
+  CalendarYearPickerGrid,
+  CalendarYearPickerGridBody,
+  CalendarYearPickerTrigger,
+  CalendarYearPickerTriggerHeading,
+  CalendarYearPickerTriggerIndicator,
+} from "./calendar-year-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const CalendarYearPicker = {
+  Trigger: CalendarYearPickerTrigger,
+  TriggerHeading: CalendarYearPickerTriggerHeading,
+  TriggerIndicator: CalendarYearPickerTriggerIndicator,
+  Grid: CalendarYearPickerGrid,
+  GridBody: CalendarYearPickerGridBody,
+  Cell: CalendarYearPickerCell,
+};
+
+export type CalendarYearPicker = {
+  TriggerProps: ComponentProps<typeof CalendarYearPickerTrigger>;
+  TriggerHeadingProps: ComponentProps<typeof CalendarYearPickerTriggerHeading>;
+  TriggerIndicatorProps: ComponentProps<typeof CalendarYearPickerTriggerIndicator>;
+  GridProps: ComponentProps<typeof CalendarYearPickerGrid>;
+  GridBodyProps: ComponentProps<typeof CalendarYearPickerGridBody>;
+  CellProps: ComponentProps<typeof CalendarYearPickerCell>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  CalendarYearPickerTrigger,
+  CalendarYearPickerTriggerHeading,
+  CalendarYearPickerTriggerIndicator,
+  CalendarYearPickerGrid,
+  CalendarYearPickerGridBody,
+  CalendarYearPickerCell,
+};
+
+export type {
+  CalendarYearPickerTriggerProps,
+  CalendarYearPickerTriggerHeadingProps,
+  CalendarYearPickerTriggerIndicatorProps,
+  CalendarYearPickerTriggerRenderProps,
+  CalendarYearPickerGridProps,
+  CalendarYearPickerGridBodyProps,
+  CalendarYearPickerCellProps,
+  CalendarYearPickerCellRenderProps,
+} from "./calendar-year-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * YearPickerContext
+ * -----------------------------------------------------------------------------------------------*/
+export {YearPickerContext, useYearPicker} from "./year-picker-context";
+export type {YearPickerContextValue} from "./year-picker-context";
+export {useCalendarOrRangeState} from "./use-calendar-state";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {calendarYearPickerVariants} from "@heroui/styles";
+
+export type {CalendarYearPickerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/calendar-year-picker/use-calendar-state.ts b/packages/react/src/components/calendar-year-picker/use-calendar-state.ts
new file mode 100644
index 0000000..469e1b9
--- /dev/null
+++ b/packages/react/src/components/calendar-year-picker/use-calendar-state.ts
@@ -0,0 +1,25 @@
+"use client";
+
+import {use} from "react";
+import {CalendarStateContext} from "react-aria-components/Calendar";
+import {RangeCalendarStateContext} from "react-aria-components/RangeCalendar";
+
+/**
+ * Returns the active Calendar or RangeCalendar state from RAC context.
+ * Must be used inside <Calendar> or <RangeCalendar>.
+ */
+function useCalendarOrRangeState() {
+  const calendarState = use(CalendarStateContext);
+  const rangeCalendarState = use(RangeCalendarStateContext);
+  const state = calendarState ?? rangeCalendarState;
+
+  if (!state) {
+    throw new Error(
+      "useCalendarOrRangeState must be used within a <Calendar> or <RangeCalendar> component.",
+    );
+  }
+
+  return state;
+}
+
+export {useCalendarOrRangeState};
diff --git a/packages/react/src/components/calendar-year-picker/year-picker-context.ts b/packages/react/src/components/calendar-year-picker/year-picker-context.ts
new file mode 100644
index 0000000..ee19357
--- /dev/null
+++ b/packages/react/src/components/calendar-year-picker/year-picker-context.ts
@@ -0,0 +1,36 @@
+"use client";
+
+import {createContext, use} from "react";
+
+/* -------------------------------------------------------------------------------------------------
+ * YearPickerContext
+ *
+ * Context provided by Calendar (and RangeCalendar) to control year-picker visibility.
+ * Internal child components consume this to toggle the year-picker open/close state,
+ * keeping the public API clean and wrapper-free.
+ * -----------------------------------------------------------------------------------------------*/
+interface YearPickerContextValue {
+  isYearPickerOpen: boolean;
+  setIsYearPickerOpen: (open: boolean) => void;
+  calendarRef: React.RefObject<HTMLDivElement | null>;
+  calendarGridSlot: "calendar-grid" | "range-calendar-grid";
+}
+
+const YearPickerContext = createContext<YearPickerContextValue | null>(null);
+
+/**
+ * Hook to consume YearPickerContext.
+ * Must be used inside Calendar or RangeCalendar.
+ */
+function useYearPicker(): YearPickerContextValue {
+  const context = use(YearPickerContext);
+
+  if (!context) {
+    throw new Error("useYearPicker must be used within a <Calendar> or <RangeCalendar> component.");
+  }
+
+  return context;
+}
+
+export {YearPickerContext, useYearPicker};
+export type {YearPickerContextValue};
diff --git a/packages/react/src/components/calendar/calendar-day-view-grid-body.tsx b/packages/react/src/components/calendar/calendar-day-view-grid-body.tsx
new file mode 100644
index 0000000..b830c1e
--- /dev/null
+++ b/packages/react/src/components/calendar/calendar-day-view-grid-body.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import type {CalendarDate, DateValue} from "@internationalized/date";
+import type {ReactElement} from "react";
+
+import React from "react";
+import {useLocale} from "react-aria-components/I18nProvider";
+
+import {getDayViewGridRows} from "../../utils/calendar";
+import {dom} from "../../utils/dom";
+
+interface CalendarDayViewGridBodyProps {
+  children: (date: CalendarDate) => ReactElement;
+  className?: string;
+  "data-slot"?: string;
+  firstDayOfWeek?: "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+  visibleRange: {end: DateValue; start: DateValue};
+}
+
+export function CalendarDayViewGridBody({
+  children,
+  className,
+  "data-slot": dataSlot = "calendar-grid-body",
+  firstDayOfWeek,
+  visibleRange,
+}: CalendarDayViewGridBodyProps) {
+  const {locale} = useLocale();
+  const rows = React.useMemo(
+    () => getDayViewGridRows(visibleRange.start, visibleRange.end, locale, firstDayOfWeek),
+    [firstDayOfWeek, locale, visibleRange.end, visibleRange.start],
+  );
+
+  return (
+    <dom.tbody className={className} data-slot={dataSlot}>
+      {rows.map((row, weekIndex) => (
+        <tr key={weekIndex}>
+          {row.map((date, dayIndex) =>
+            date ? (
+              React.cloneElement(children(date as CalendarDate), {key: dayIndex})
+            ) : (
+              <td key={dayIndex} />
+            ),
+          )}
+        </tr>
+      ))}
+    </dom.tbody>
+  );
+}
diff --git a/packages/react/src/components/calendar/calendar-day-view-grid-header.tsx b/packages/react/src/components/calendar/calendar-day-view-grid-header.tsx
new file mode 100644
index 0000000..e6868d9
--- /dev/null
+++ b/packages/react/src/components/calendar/calendar-day-view-grid-header.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import type {DateValue} from "@internationalized/date";
+import type {ReactElement} from "react";
+
+import React from "react";
+import {useLocale} from "react-aria-components/I18nProvider";
+
+import {getDayViewWeekDayLabels} from "../../utils/calendar";
+import {dom} from "../../utils/dom";
+
+interface CalendarDayViewGridHeaderProps {
+  children: (day: string) => ReactElement;
+  className?: string;
+  "data-slot"?: string;
+  firstDayOfWeek?: "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+  timeZone?: string;
+  visibleRange: {end: DateValue; start: DateValue};
+  weekdayStyle?: "narrow" | "short" | "long";
+}
+
+export function CalendarDayViewGridHeader({
+  children,
+  className,
+  "data-slot": dataSlot = "calendar-grid-header",
+  firstDayOfWeek,
+  timeZone = "UTC",
+  visibleRange,
+  weekdayStyle = "short",
+}: CalendarDayViewGridHeaderProps) {
+  const {locale} = useLocale();
+  const weekDays = React.useMemo(
+    () =>
+      getDayViewWeekDayLabels(visibleRange.start, locale, firstDayOfWeek, weekdayStyle, timeZone),
+    [firstDayOfWeek, locale, timeZone, visibleRange.start, weekdayStyle],
+  );
+
+  return (
+    <dom.thead aria-hidden className={className} data-slot={dataSlot}>
+      <tr>{weekDays.map((day, index) => React.cloneElement(children(day), {key: index}))}</tr>
+    </dom.thead>
+  );
+}
diff --git a/packages/react/src/components/calendar/calendar.stories.tsx b/packages/react/src/components/calendar/calendar.stories.tsx
new file mode 100644
index 0000000..55cdcd8
--- /dev/null
+++ b/packages/react/src/components/calendar/calendar.stories.tsx
@@ -0,0 +1,929 @@
+import type {DateValue} from "@internationalized/date";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {
+  getLocalTimeZone,
+  isToday,
+  isWeekend,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import React, {useState} from "react";
+import {I18nProvider, useLocale} from "react-aria-components/I18nProvider";
+
+import {Button} from "../button";
+import {ButtonGroup} from "../button-group";
+import {Description} from "../description";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Select} from "../select";
+
+import {Calendar} from "./index";
+
+const meta: Meta<typeof Calendar> = {
+  argTypes: {
+    isDisabled: {
+      control: "boolean",
+    },
+    isReadOnly: {
+      control: "boolean",
+    },
+    selectionMode: {
+      control: "select",
+      options: ["single", "multiple"],
+    },
+    weeksInMonth: {
+      control: {type: "number", min: 4, max: 6, step: 1},
+    },
+  },
+  component: Calendar,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/Calendar",
+};
+
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+
+/* -------------------------------------------------------------------------------------------------
+ * Helper component to render a basic calendar structure
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarTemplate = (props: Omit<React.ComponentProps<typeof Calendar>, "children">) => (
+  <Calendar {...props}>
+    <Calendar.Header>
+      <Calendar.Heading />
+      <Calendar.NavButton slot="previous" />
+      <Calendar.NavButton slot="next" />
+    </Calendar.Header>
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+    </Calendar.Grid>
+  </Calendar>
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Helper component to render a calendar with year picker
+ * -----------------------------------------------------------------------------------------------*/
+const CalendarTemplateWithYearPicker = (
+  props: Omit<React.ComponentProps<typeof Calendar>, "children">,
+) => (
+  <Calendar {...props}>
+    <Calendar.Header>
+      <Calendar.YearPickerTrigger>
+        <Calendar.YearPickerTriggerHeading />
+        <Calendar.YearPickerTriggerIndicator />
+      </Calendar.YearPickerTrigger>
+      <Calendar.NavButton slot="previous" />
+      <Calendar.NavButton slot="next" />
+    </Calendar.Header>
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+    </Calendar.Grid>
+    <Calendar.YearPickerGrid>
+      <Calendar.YearPickerGridBody>
+        {({year}) => <Calendar.YearPickerCell year={year} />}
+      </Calendar.YearPickerGridBody>
+    </Calendar.YearPickerGrid>
+  </Calendar>
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Stories
+ * -----------------------------------------------------------------------------------------------*/
+export const Default: Story = {
+  render: (args) => <CalendarTemplate {...args} aria-label="Event date" />,
+};
+
+export const WithYearPicker: Story = {
+  render: (args) => <CalendarTemplateWithYearPicker {...args} aria-label="Event date" />,
+};
+
+export const DefaultValue: Story = {
+  render: (args) => (
+    <CalendarTemplate {...args} aria-label="Event date" defaultValue={parseDate("2025-02-14")} />
+  ),
+};
+
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<DateValue | null>(null);
+    const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25"));
+    const {locale} = useLocale();
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <ButtonGroup variant="tertiary">
+          <Button
+            onPress={() => {
+              setValue(today(getLocalTimeZone()));
+              setFocusedDate(today(getLocalTimeZone()));
+            }}
+          >
+            Today
+          </Button>
+          <Button
+            onPress={() => {
+              const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale);
+
+              setValue(nextWeekStart);
+              setFocusedDate(nextWeekStart);
+            }}
+          >
+            Next week
+          </Button>
+          <Button
+            onPress={() => {
+              const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1}));
+
+              setValue(nextMonthStart);
+              setFocusedDate(nextMonthStart);
+            }}
+          >
+            Next month
+          </Button>
+        </ButtonGroup>
+        <CalendarTemplate
+          {...args}
+          aria-label="Event date"
+          focusedValue={focusedDate}
+          value={value}
+          onChange={setValue}
+          onFocusChange={setFocusedDate}
+        />
+        <Description className="text-center">
+          Selected date: {value ? value.toString() : "(none)"}
+        </Description>
+        <div className="flex gap-2">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const todayDate = today(getLocalTimeZone());
+
+              setValue(todayDate);
+              setFocusedDate(todayDate);
+            }}
+          >
+            Set Today
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const christmasDate = parseDate("2025-12-25");
+
+              setValue(christmasDate);
+              setFocusedDate(christmasDate);
+            }}
+          >
+            Set Christmas
+          </Button>
+          <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+            Clear
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const MinMaxDates: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+    const minDate = now;
+    const maxDate = now.add({months: 3});
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <Calendar {...args} aria-label="Appointment date" maxValue={maxDate} minValue={minDate}>
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.YearPickerTrigger>
+              <Calendar.YearPickerTriggerHeading />
+              <Calendar.YearPickerTriggerIndicator />
+            </Calendar.YearPickerTrigger>
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+          <Calendar.YearPickerGrid>
+            <Calendar.YearPickerGridBody>
+              {({year}) => <Calendar.YearPickerCell year={year} />}
+            </Calendar.YearPickerGridBody>
+          </Calendar.YearPickerGrid>
+        </Calendar>
+        <Description className="text-center">
+          Select a date between today and {maxDate.toString()}
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const UnavailableDates: Story = {
+  render: (args) => {
+    const {locale} = useLocale();
+
+    // Make weekends unavailable
+    const isDateUnavailable = (date: DateValue) => isWeekend(date, locale);
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <CalendarTemplate
+          {...args}
+          aria-label="Appointment date"
+          isDateUnavailable={isDateUnavailable}
+        />
+        <Description className="text-center">Weekends are unavailable</Description>
+      </div>
+    );
+  },
+};
+
+export const WeeksInMonth: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <CalendarTemplate {...args} aria-label="Event date" weeksInMonth={6} />
+      <Description className="text-center">
+        Fixed to 6 weeks per month to avoid layout shift
+      </Description>
+    </div>
+  ),
+};
+
+export const MultipleSelection: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<readonly DateValue[]>([]);
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <CalendarTemplate
+          {...args}
+          aria-label="Event dates"
+          selectionMode="multiple"
+          value={value}
+          onChange={setValue}
+        />
+        <Description className="text-center">
+          {value?.length ? `${value.length} date(s) selected` : "Select multiple dates"}
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const CustomUnavailableDates: Story = {
+  render: (args) => {
+    // Block specific dates (holidays, booked dates, etc.)
+    const blockedDates = [
+      parseDate("2025-02-14"), // Valentine's Day
+      parseDate("2025-02-17"), // President's Day
+      parseDate("2025-03-17"), // St. Patrick's Day
+    ];
+
+    const isDateUnavailable = (date: DateValue) => {
+      return blockedDates.some(
+        (blockedDate) =>
+          blockedDate.year === date.year &&
+          blockedDate.month === date.month &&
+          blockedDate.day === date.day,
+      );
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <CalendarTemplate {...args} aria-label="Event date" isDateUnavailable={isDateUnavailable} />
+        <Description className="text-center">
+          Feb 14, Feb 17, and Mar 17 are unavailable
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <CalendarTemplate
+        {...args}
+        isDisabled
+        aria-label="Event date"
+        defaultValue={today(getLocalTimeZone())}
+      />
+      <Description className="text-center">Calendar is disabled</Description>
+    </div>
+  ),
+};
+
+export const ReadOnly: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <CalendarTemplate
+        {...args}
+        isReadOnly
+        aria-label="Event date"
+        defaultValue={today(getLocalTimeZone())}
+      />
+      <Description className="text-center">Calendar is read-only</Description>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<DateValue | null>(parseDate("2025-01-15"));
+    const minDate = today(getLocalTimeZone());
+    const isInvalid = value !== null && value.compare(minDate) < 0;
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <CalendarTemplate
+          {...args}
+          aria-label="Event date"
+          isInvalid={isInvalid}
+          value={value}
+          onChange={setValue}
+        />
+        {isInvalid ? (
+          <p className="text-sm text-danger">Date must be today or in the future</p>
+        ) : (
+          <Description className="text-center">Select a future date</Description>
+        )}
+      </div>
+    );
+  },
+};
+
+export const FocusedValue: Story = {
+  render: (args) => {
+    const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <CalendarTemplate
+          {...args}
+          aria-label="Event date"
+          focusedValue={focusedDate}
+          onFocusChange={setFocusedDate}
+        />
+        <Description className="text-center">Focused: {focusedDate.toString()}</Description>
+        <div className="flex flex-wrap justify-center gap-2">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+          >
+            Go to Jan
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+          >
+            Go to Jun
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+          >
+            Go to Christmas
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+// Sample dates that have events (for demo purposes)
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export const WithIndicators: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.Heading />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => (
+            <Calendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <Calendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </Calendar.Cell>
+          )}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  ),
+};
+
+export const TodayIndicator: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
+      <Calendar.Header>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.Heading />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>
+          {(date) => (
+            <Calendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {isToday(date, getLocalTimeZone()) && <Calendar.CellIndicator />}
+                </>
+              )}
+            </Calendar.Cell>
+          )}
+        </Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  ),
+};
+
+export const MultipleMonths: Story = {
+  render: (args) => (
+    <Calendar
+      {...args}
+      aria-label="Trip dates"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+        <div className="w-64">
+          <Calendar.Header>
+            <div className="size-6" />
+            <Calendar.Heading className="flex-none" offset={{months: 1}} />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid offset={{months: 1}}>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+      </div>
+    </Calendar>
+  ),
+};
+
+const dayViewOptions = [
+  {id: "1", name: "1 day"},
+  {id: "5", name: "5 days"},
+  {id: "7", name: "7 days"},
+  {id: "8", name: "8 days"},
+  {id: "10", name: "10 days"},
+  {id: "14", name: "14 days"},
+  {id: "21", name: "21 days"},
+] as const;
+
+export const DayView: Story = {
+  render: (args) => {
+    const [days, setDays] = useState(5);
+
+    return (
+      <div className="flex flex-col items-center gap-6">
+        <Select
+          className="w-40"
+          value={String(days)}
+          onChange={(value) => value && setDays(Number(value))}
+        >
+          <Label>Visible days</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {dayViewOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                  {option.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        <Calendar {...args} aria-label="Day view" visibleDuration={{days}}>
+          <Calendar.Header>
+            <Calendar.Heading />
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </div>
+    );
+  },
+};
+
+const weekViewOptions = [
+  {id: "1", name: "1 week"},
+  {id: "2", name: "2 weeks"},
+  {id: "3", name: "3 weeks"},
+  {id: "4", name: "4 weeks"},
+  {id: "5", name: "5 weeks"},
+  {id: "6", name: "6 weeks"},
+  {id: "8", name: "8 weeks"},
+] as const;
+
+export const WeekView: Story = {
+  render: (args) => {
+    const [weeks, setWeeks] = useState(1);
+
+    return (
+      <div className="flex flex-col items-center gap-6">
+        <Select
+          className="w-40"
+          value={String(weeks)}
+          onChange={(value) => value && setWeeks(Number(value))}
+        >
+          <Label>Visible weeks</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {weekViewOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                  {option.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        <Calendar {...args} aria-label="Week view" visibleDuration={{weeks}}>
+          <Calendar.Header>
+            <Calendar.Heading />
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+      </div>
+    );
+  },
+};
+
+export const InternationalCalendar: Story = {
+  render: (args) => (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <CalendarTemplateWithYearPicker
+        {...args}
+        aria-label="Event date"
+        defaultValue={today(getLocalTimeZone())}
+      />
+    </I18nProvider>
+  ),
+};
+
+export const ThreeMonths: Story = {
+  render: (args) => (
+    <Calendar
+      {...args}
+      aria-label="Vacation planning"
+      className="@container-normal w-auto overflow-x-auto"
+      visibleDuration={{months: 3}}
+    >
+      <div className="flex w-max gap-7">
+        <div className="w-64">
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.Heading />
+            <div className="size-6" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+        <div className="w-64">
+          <Calendar.Header>
+            <div className="size-6" />
+            <Calendar.Heading offset={{months: 1}} />
+            <div className="size-6" />
+          </Calendar.Header>
+          <Calendar.Grid offset={{months: 1}}>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+        <div className="w-64">
+          <Calendar.Header>
+            <div className="size-6" />
+            <Calendar.Heading offset={{months: 2}} />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid offset={{months: 2}}>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+          </Calendar.Grid>
+        </div>
+      </div>
+    </Calendar>
+  ),
+};
+
+export const BookingCalendar: Story = {
+  render: (args) => {
+    const [selectedDate, setSelectedDate] = useState<DateValue | null>(null);
+    const {locale} = useLocale();
+
+    // Simulated booked dates
+    const bookedDates = [5, 6, 12, 13, 14, 20];
+
+    const isDateUnavailable = (date: DateValue) => {
+      // Weekends and already booked dates are unavailable
+      return isWeekend(date, locale) || bookedDates.includes(date.day);
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <Calendar
+          {...args}
+          aria-label="Booking date"
+          isDateUnavailable={isDateUnavailable}
+          minValue={today(getLocalTimeZone())}
+          value={selectedDate}
+          onChange={setSelectedDate}
+        >
+          <Calendar.Header>
+            <Calendar.NavButton slot="previous" />
+            <Calendar.Heading />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => (
+                <Calendar.Cell date={date}>
+                  {({formattedDate, isUnavailable}) => (
+                    <>
+                      {formattedDate}
+                      {!isUnavailable &&
+                        !isWeekend(date, locale) &&
+                        bookedDates.includes(date.day) && <Calendar.CellIndicator />}
+                    </>
+                  )}
+                </Calendar.Cell>
+              )}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+        <div className="flex flex-col gap-2 text-center">
+          <div className="flex items-center justify-center gap-4 text-xs text-muted">
+            <span className="flex items-center gap-1">
+              <span className="size-2 rounded-full bg-muted" /> Has bookings
+            </span>
+            <span className="flex items-center gap-1">
+              <span className="size-2 rounded-full bg-default" /> Weekend/Unavailable
+            </span>
+          </div>
+          {selectedDate ? (
+            <Button size="sm" variant="primary">
+              Book {selectedDate.toString()}
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const YearPicker: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({year}) => <Calendar.YearPickerCell year={year} />}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  ),
+};
+
+export const YearPickerStyledCells: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date with styled year cells">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({isCurrentYear, isSelected, year}) => (
+            <Calendar.YearPickerCell
+              year={year}
+              className={
+                isCurrentYear && !isSelected
+                  ? "text-accent ring-1 ring-accent/60 ring-inset"
+                  : undefined
+              }
+            />
+          )}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  ),
+};
+
+export const YearPickerCustomCells: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date with custom year cells">
+      <Calendar.Header>
+        <Calendar.YearPickerTrigger>
+          <Calendar.YearPickerTriggerHeading />
+          <Calendar.YearPickerTriggerIndicator />
+        </Calendar.YearPickerTrigger>
+        <Calendar.NavButton slot="previous" />
+        <Calendar.NavButton slot="next" />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+      <Calendar.YearPickerGrid>
+        <Calendar.YearPickerGridBody>
+          {({isCurrentYear, isSelected, year}) => (
+            <Calendar.YearPickerCell year={year}>
+              <span className="inline-flex items-center gap-1">
+                <span>{year}</span>
+                {isCurrentYear ? (
+                  <span className={isSelected ? "text-accent-foreground" : "text-accent"}>Now</span>
+                ) : null}
+              </span>
+            </Calendar.YearPickerCell>
+          )}
+        </Calendar.YearPickerGridBody>
+      </Calendar.YearPickerGrid>
+    </Calendar>
+  ),
+};
+
+export const CustomNavIcons: Story = {
+  render: (args) => (
+    <Calendar {...args} aria-label="Event date">
+      <Calendar.Header>
+        <Calendar.NavButton slot="previous">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+        <Calendar.Heading />
+        <Calendar.NavButton slot="next">
+          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
+            <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" />
+          </svg>
+        </Calendar.NavButton>
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader>
+          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+        </Calendar.GridHeader>
+        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+      </Calendar.Grid>
+    </Calendar>
+  ),
+};
+
+export const EventCalendar: Story = {
+  render: (args) => {
+    // Sample events data
+    const events: Record<number, {title: string; color: string}[]> = {
+      3: [{title: "Team Meeting", color: "bg-blue-500"}],
+      7: [{title: "Project Deadline", color: "bg-red-500"}],
+      12: [
+        {title: "Lunch", color: "bg-green-500"},
+        {title: "Review", color: "bg-purple-500"},
+      ],
+      15: [{title: "Conference", color: "bg-orange-500"}],
+      21: [{title: "Workshop", color: "bg-pink-500"}],
+      28: [{title: "Demo Day", color: "bg-cyan-500"}],
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <Calendar {...args} aria-label="Event calendar">
+          <Calendar.Header>
+            <Calendar.Heading />
+            <Calendar.NavButton slot="previous" />
+            <Calendar.NavButton slot="next" />
+          </Calendar.Header>
+          <Calendar.Grid>
+            <Calendar.GridHeader>
+              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+            </Calendar.GridHeader>
+            <Calendar.GridBody>
+              {(date) => (
+                <Calendar.Cell date={date}>
+                  {({formattedDate}) => (
+                    <>
+                      {formattedDate}
+                      {events[date.day] ? <Calendar.CellIndicator /> : null}
+                    </>
+                  )}
+                </Calendar.Cell>
+              )}
+            </Calendar.GridBody>
+          </Calendar.Grid>
+        </Calendar>
+        <div className="flex flex-col gap-1 text-xs text-muted">
+          <p>Dates with indicators have scheduled events</p>
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/calendar/calendar.tsx b/packages/react/src/components/calendar/calendar.tsx
new file mode 100644
index 0000000..26bdc76
--- /dev/null
+++ b/packages/react/src/components/calendar/calendar.tsx
@@ -0,0 +1,451 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {CalendarVariants} from "@heroui/styles";
+import type {CalendarIdentifier} from "@internationalized/date";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {
+  CalendarSelectionMode,
+  DateValue,
+  CalendarProps as RACCalendarProps,
+} from "react-aria-components/Calendar";
+
+import {calendarVariants} from "@heroui/styles";
+import {CalendarDate, DateFormatter, createCalendar} from "@internationalized/date";
+import {useControlledState} from "@react-stately/utils";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {
+  CalendarCell as CalendarCellPrimitive,
+  CalendarGridBody as CalendarGridBodyPrimitive,
+  CalendarGridHeader as CalendarGridHeaderPrimitive,
+  CalendarGrid as CalendarGridPrimitive,
+  CalendarHeaderCell as CalendarHeaderCellPrimitive,
+  CalendarHeading as CalendarHeadingPrimitive,
+  Calendar as CalendarPrimitive,
+} from "react-aria-components/Calendar";
+import {useLocale} from "react-aria-components/I18nProvider";
+import {cx} from "tailwind-variants";
+
+import {getGregorianYearOffset} from "../../utils/calendar";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {YearPickerContext} from "../calendar-year-picker/year-picker-context";
+import {IconChevronLeft, IconChevronRight} from "../icons";
+
+import {CalendarDayViewGridBody} from "./calendar-day-view-grid-body";
+import {CalendarDayViewGridHeader} from "./calendar-day-view-grid-header";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Context
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarDayViewContext {
+  days: number;
+  firstDayOfWeek?: CalendarRootProps["firstDayOfWeek"];
+  timeZone: string;
+  visibleRange: {end: DateValue; start: DateValue};
+  weekdayStyle?: "narrow" | "short" | "long";
+}
+
+interface CalendarContext {
+  dayView?: CalendarDayViewContext;
+  slots?: ReturnType<typeof calendarVariants>;
+}
+
+const CalendarContext = createContext<CalendarContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Root
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarRootProps<
+  T extends DateValue = DateValue,
+  M extends CalendarSelectionMode = "single",
+>
+  extends RACCalendarProps<T, M>, CalendarVariants {
+  isYearPickerOpen?: boolean;
+  onYearPickerOpenChange?: (isYearPickerOpen: boolean) => void;
+  defaultYearPickerOpen?: boolean;
+}
+
+function CalendarRoot<T extends DateValue = DateValue, M extends CalendarSelectionMode = "single">({
+  children,
+  className,
+  defaultYearPickerOpen: defaultYearPickerOpenProp = false,
+  firstDayOfWeek,
+  isYearPickerOpen: isYearPickerOpenProp,
+  maxValue: maxValueProp,
+  minValue: minValueProp,
+  onYearPickerOpenChange: onYearPickerOpenChangeProp,
+  visibleDuration,
+  ...rest
+}: CalendarRootProps<T, M>) {
+  const isWeekView = visibleDuration?.weeks != null;
+  const isDayView = visibleDuration?.days != null;
+  const visibleDays = visibleDuration?.days;
+  const {locale} = useLocale();
+  const slots = React.useMemo(() => calendarVariants(), []);
+  const calendarRef = React.useRef<HTMLDivElement>(null);
+  const [isYearPickerOpen, setIsYearPickerOpen] = useControlledState(
+    isYearPickerOpenProp,
+    defaultYearPickerOpenProp,
+    onYearPickerOpenChangeProp,
+  );
+  const calendarProp = React.useMemo(() => {
+    const calendarIdentifier = new DateFormatter(locale).resolvedOptions()
+      .calendar as CalendarIdentifier;
+
+    return createCalendar(calendarIdentifier);
+  }, [locale]);
+  const gregorianYearOffset = React.useMemo(
+    () => getGregorianYearOffset(calendarProp.identifier),
+    [calendarProp.identifier],
+  );
+  const minValue =
+    minValueProp ??
+    (new CalendarDate(calendarProp, 1900 + gregorianYearOffset, 1, 1) as unknown as T);
+  const maxValue =
+    maxValueProp ??
+    (new CalendarDate(calendarProp, 2099 + gregorianYearOffset, 12, 31) as unknown as T);
+
+  return (
+    <YearPickerContext
+      value={{
+        calendarGridSlot: "calendar-grid",
+        isYearPickerOpen,
+        setIsYearPickerOpen,
+        calendarRef,
+      }}
+    >
+      <CalendarPrimitive
+        ref={calendarRef}
+        data-slot="calendar"
+        firstDayOfWeek={firstDayOfWeek}
+        maxValue={maxValue}
+        minValue={minValue}
+        visibleDuration={visibleDuration}
+        {...rest}
+        className={composeTwRenderProps(
+          className,
+          cx(slots.base(), isWeekView && "calendar--week-view", isDayView && "calendar--day-view"),
+        )}
+      >
+        {(values) => (
+          <CalendarContext
+            value={{
+              dayView:
+                isDayView && visibleDays != null
+                  ? {
+                      days: visibleDays,
+                      firstDayOfWeek,
+                      timeZone: values.state.timeZone,
+                      visibleRange: values.state.visibleRange,
+                    }
+                  : undefined,
+              slots,
+            }}
+          >
+            {typeof children === "function" ? children(values) : children}
+          </CalendarContext>
+        )}
+      </CalendarPrimitive>
+    </YearPickerContext>
+  );
+}
+
+CalendarRoot.displayName = "HeroUI.Calendar";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Header
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarHeaderProps<
+  E extends keyof React.JSX.IntrinsicElements = "header",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CalendarHeader = <E extends keyof React.JSX.IntrinsicElements = "header">({
+  children,
+  className,
+  ...props
+}: CalendarHeaderProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CalendarHeaderProps<E>>) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <dom.header
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="calendar-header"
+      {...(props as any)}
+    >
+      {children}
+    </dom.header>
+  );
+};
+
+CalendarHeader.displayName = "HeroUI.Calendar.Header";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Heading
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarHeadingProps extends ComponentPropsWithRef<typeof CalendarHeadingPrimitive> {}
+
+const CalendarHeading = ({className, ...props}: CalendarHeadingProps) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <CalendarHeadingPrimitive
+      data-slot="calendar-heading"
+      {...props}
+      className={composeSlotClassName(slots?.heading, className)}
+    />
+  );
+};
+
+CalendarHeading.displayName = "HeroUI.Calendar.Heading";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Nav Button
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarNavButtonProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  slot?: "previous" | "next";
+}
+
+const CalendarNavButton = ({children, className, slot, ...props}: CalendarNavButtonProps) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <ButtonPrimitive
+      data-slot="calendar-nav-button"
+      slot={slot}
+      {...props}
+      className={composeTwRenderProps(className, slots?.navButton())}
+    >
+      {children ||
+        (slot === "previous" ? (
+          <IconChevronLeft
+            className={slots?.navButtonIcon()}
+            data-slot="calendar-nav-button-icon"
+          />
+        ) : (
+          <IconChevronRight
+            className={slots?.navButtonIcon()}
+            data-slot="calendar-nav-button-icon"
+          />
+        ))}
+    </ButtonPrimitive>
+  );
+};
+
+CalendarNavButton.displayName = "HeroUI.Calendar.NavButton";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Grid
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarGridProps extends ComponentPropsWithRef<typeof CalendarGridPrimitive> {}
+
+const CalendarGrid = ({
+  children,
+  className,
+  weekdayStyle = "short",
+  ...props
+}: CalendarGridProps) => {
+  const calendarContext = use(CalendarContext);
+  const {dayView, slots} = calendarContext;
+  const contextValue = React.useMemo(
+    () => ({
+      ...calendarContext,
+      dayView: dayView ? {...dayView, weekdayStyle} : undefined,
+    }),
+    [calendarContext, dayView, weekdayStyle],
+  );
+
+  return (
+    <CalendarContext value={contextValue}>
+      <CalendarGridPrimitive
+        data-slot="calendar-grid"
+        weekdayStyle={weekdayStyle}
+        {...props}
+        className={composeSlotClassName(slots?.grid, className)}
+      >
+        {children}
+      </CalendarGridPrimitive>
+    </CalendarContext>
+  );
+};
+
+CalendarGrid.displayName = "HeroUI.Calendar.Grid";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Grid Header
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarGridHeaderProps extends ComponentPropsWithRef<
+  typeof CalendarGridHeaderPrimitive
+> {}
+
+const CalendarGridHeader = ({children, className, ...props}: CalendarGridHeaderProps) => {
+  const {dayView, slots} = use(CalendarContext);
+
+  if (dayView && dayView.days >= 7 && typeof children === "function") {
+    return (
+      <CalendarDayViewGridHeader
+        className={composeSlotClassName(slots?.gridHeader, className)}
+        data-slot="calendar-grid-header"
+        firstDayOfWeek={dayView.firstDayOfWeek}
+        timeZone={dayView.timeZone}
+        visibleRange={dayView.visibleRange}
+        weekdayStyle={dayView.weekdayStyle}
+      >
+        {children}
+      </CalendarDayViewGridHeader>
+    );
+  }
+
+  return (
+    <CalendarGridHeaderPrimitive
+      data-slot="calendar-grid-header"
+      {...props}
+      className={composeSlotClassName(slots?.gridHeader, className)}
+    >
+      {children}
+    </CalendarGridHeaderPrimitive>
+  );
+};
+
+CalendarGridHeader.displayName = "HeroUI.Calendar.GridHeader";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Grid Body
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarGridBodyProps extends ComponentPropsWithRef<typeof CalendarGridBodyPrimitive> {}
+
+const CalendarGridBody = ({children, className, ...props}: CalendarGridBodyProps) => {
+  const {dayView, slots} = use(CalendarContext);
+
+  if (dayView && dayView.days >= 7 && typeof children === "function") {
+    return (
+      <CalendarDayViewGridBody
+        className={composeSlotClassName(slots?.gridBody, className)}
+        data-slot="calendar-grid-body"
+        firstDayOfWeek={dayView.firstDayOfWeek}
+        visibleRange={dayView.visibleRange}
+      >
+        {children}
+      </CalendarDayViewGridBody>
+    );
+  }
+
+  return (
+    <CalendarGridBodyPrimitive
+      data-slot="calendar-grid-body"
+      {...props}
+      className={composeSlotClassName(slots?.gridBody, className)}
+    >
+      {children}
+    </CalendarGridBodyPrimitive>
+  );
+};
+
+CalendarGridBody.displayName = "HeroUI.Calendar.GridBody";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Header Cell
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarHeaderCellProps extends ComponentPropsWithRef<
+  typeof CalendarHeaderCellPrimitive
+> {}
+
+const CalendarHeaderCell = ({className, ...props}: CalendarHeaderCellProps) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <CalendarHeaderCellPrimitive
+      data-slot="calendar-header-cell"
+      {...props}
+      className={composeSlotClassName(slots?.headerCell, className)}
+    />
+  );
+};
+
+CalendarHeaderCell.displayName = "HeroUI.Calendar.HeaderCell";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Cell
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarCellProps extends ComponentPropsWithRef<typeof CalendarCellPrimitive> {}
+
+const CalendarCell = ({children, className, ...props}: CalendarCellProps) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <CalendarCellPrimitive
+      data-slot="calendar-cell"
+      {...props}
+      className={composeTwRenderProps(className, slots?.cell())}
+    >
+      {(values) => {
+        const {formattedDate} = values;
+
+        return typeof children === "function" ? children(values) : children || formattedDate;
+      }}
+    </CalendarCellPrimitive>
+  );
+};
+
+CalendarCell.displayName = "HeroUI.Calendar.Cell";
+
+/* -------------------------------------------------------------------------------------------------
+| * Calendar Cell Indicator
+| * -----------------------------------------------------------------------------------------------*/
+interface CalendarCellIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CalendarCellIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: CalendarCellIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CalendarCellIndicatorProps<E>>) => {
+  const {slots} = use(CalendarContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.cellIndicator, className)}
+      data-slot="calendar-cell-indicator"
+      {...(props as any)}
+    />
+  );
+};
+
+CalendarCellIndicator.displayName = "HeroUI.Calendar.CellIndicator";
+
+/* -------------------------------------------------------------------------------------------------
+| * Exports
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  CalendarRoot,
+  CalendarHeader,
+  CalendarHeading,
+  CalendarNavButton,
+  CalendarGrid,
+  CalendarGridHeader,
+  CalendarGridBody,
+  CalendarHeaderCell,
+  CalendarCell,
+  CalendarCellIndicator,
+};
+export type {
+  CalendarRootProps,
+  CalendarHeaderProps,
+  CalendarHeadingProps,
+  CalendarNavButtonProps,
+  CalendarGridProps,
+  CalendarGridHeaderProps,
+  CalendarGridBodyProps,
+  CalendarHeaderCellProps,
+  CalendarCellProps,
+  CalendarCellIndicatorProps,
+};
diff --git a/packages/react/src/components/calendar/index.ts b/packages/react/src/components/calendar/index.ts
new file mode 100644
index 0000000..5a23e38
--- /dev/null
+++ b/packages/react/src/components/calendar/index.ts
@@ -0,0 +1,121 @@
+import type {CalendarRootProps} from "./calendar";
+import type {ComponentProps, ReactElement} from "react";
+import type {CalendarSelectionMode, DateValue} from "react-aria-components/Calendar";
+
+import {
+  CalendarYearPickerCell,
+  CalendarYearPickerGrid,
+  CalendarYearPickerGridBody,
+  CalendarYearPickerTrigger,
+  CalendarYearPickerTriggerHeading,
+  CalendarYearPickerTriggerIndicator,
+} from "../calendar-year-picker";
+
+import {
+  CalendarCell,
+  CalendarCellIndicator,
+  CalendarGrid,
+  CalendarGridBody,
+  CalendarGridHeader,
+  CalendarHeader,
+  CalendarHeaderCell,
+  CalendarHeading,
+  CalendarNavButton,
+  CalendarRoot,
+} from "./calendar";
+
+type CalendarComponent = <
+  T extends DateValue = DateValue,
+  M extends CalendarSelectionMode = "single",
+>(
+  props: CalendarRootProps<T, M>,
+) => ReactElement | null;
+
+/* -------------------------------------------------------------------------------------------------
+| * Compound Component
+| * -----------------------------------------------------------------------------------------------*/
+const CalendarCompound = Object.assign(CalendarRoot, {
+  Root: CalendarRoot,
+  Header: CalendarHeader,
+  Heading: CalendarHeading,
+  NavButton: CalendarNavButton,
+  Grid: CalendarGrid,
+  GridHeader: CalendarGridHeader,
+  GridBody: CalendarGridBody,
+  HeaderCell: CalendarHeaderCell,
+  Cell: CalendarCell,
+  CellIndicator: CalendarCellIndicator,
+  YearPickerTrigger: CalendarYearPickerTrigger,
+  YearPickerTriggerHeading: CalendarYearPickerTriggerHeading,
+  YearPickerTriggerIndicator: CalendarYearPickerTriggerIndicator,
+  YearPickerGrid: CalendarYearPickerGrid,
+  YearPickerGridBody: CalendarYearPickerGridBody,
+  YearPickerCell: CalendarYearPickerCell,
+});
+
+export const Calendar = CalendarCompound as CalendarComponent & typeof CalendarCompound;
+
+export type Calendar = {
+  Props: ComponentProps<typeof CalendarRoot>;
+  RootProps: ComponentProps<typeof CalendarRoot>;
+  HeaderProps: ComponentProps<typeof CalendarHeader>;
+  HeadingProps: ComponentProps<typeof CalendarHeading>;
+  NavButtonProps: ComponentProps<typeof CalendarNavButton>;
+  GridProps: ComponentProps<typeof CalendarGrid>;
+  GridHeaderProps: ComponentProps<typeof CalendarGridHeader>;
+  GridBodyProps: ComponentProps<typeof CalendarGridBody>;
+  HeaderCellProps: ComponentProps<typeof CalendarHeaderCell>;
+  CellProps: ComponentProps<typeof CalendarCell>;
+  CellIndicatorProps: ComponentProps<typeof CalendarCellIndicator>;
+  YearPickerTriggerProps: ComponentProps<typeof CalendarYearPickerTrigger>;
+  YearPickerTriggerHeadingProps: ComponentProps<typeof CalendarYearPickerTriggerHeading>;
+  YearPickerTriggerIndicatorProps: ComponentProps<typeof CalendarYearPickerTriggerIndicator>;
+  YearPickerGridProps: ComponentProps<typeof CalendarYearPickerGrid>;
+  YearPickerGridBodyProps: ComponentProps<typeof CalendarYearPickerGridBody>;
+  YearPickerCellProps: ComponentProps<typeof CalendarYearPickerCell>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * Named Component
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  CalendarRoot,
+  CalendarHeader,
+  CalendarHeading,
+  CalendarNavButton,
+  CalendarGrid,
+  CalendarGridHeader,
+  CalendarGridBody,
+  CalendarHeaderCell,
+  CalendarCell,
+  CalendarCellIndicator,
+};
+
+export type {
+  CalendarRootProps,
+  CalendarRootProps as CalendarProps,
+  CalendarHeaderProps,
+  CalendarHeadingProps,
+  CalendarNavButtonProps,
+  CalendarGridProps,
+  CalendarGridHeaderProps,
+  CalendarGridBodyProps,
+  CalendarHeaderCellProps,
+  CalendarCellProps,
+  CalendarCellIndicatorProps,
+} from "./calendar";
+
+/* -------------------------------------------------------------------------------------------------
+| * YearPickerContext (re-exported from calendar-year-picker for convenience)
+| * -----------------------------------------------------------------------------------------------*/
+export {YearPickerContext, useYearPicker, useCalendarOrRangeState} from "../calendar-year-picker";
+export type {YearPickerContextValue} from "../calendar-year-picker";
+
+/* -------------------------------------------------------------------------------------------------
+| * Variants
+| * -----------------------------------------------------------------------------------------------*/
+export {calendarVariants} from "@heroui/styles";
+
+export type {CalendarVariants} from "@heroui/styles";
+
+export type {CalendarSelectionMode} from "react-aria-components/Calendar";
diff --git a/packages/react/src/components/card/card.stories.tsx b/packages/react/src/components/card/card.stories.tsx
new file mode 100644
index 0000000..340be68
--- /dev/null
+++ b/packages/react/src/components/card/card.stories.tsx
@@ -0,0 +1,506 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Avatar} from "../avatar";
+import {Button} from "../button";
+import {CloseButton} from "../close-button";
+import {Form} from "../form";
+import {Input} from "../input";
+import {Label} from "../label";
+import {Link} from "../link";
+import {TextField} from "../textfield";
+
+import {Card} from "./index";
+
+const meta = {
+  argTypes: {
+    variant: {
+      control: {type: "select"},
+      options: ["transparent", "default", "secondary", "tertiary"],
+    },
+  },
+  component: Card,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Layout/Card",
+} satisfies Meta<typeof Card>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Card className="w-[400px]" {...args}>
+      <Icon
+        aria-label="Dollar sign icon"
+        className="text-primary size-6"
+        icon="gravity-ui:circle-dollar"
+        role="img"
+      />
+      <Card.Header>
+        <Card.Title>Become an Acme Creator!</Card.Title>
+        <Card.Description>
+          Visit the Acme Creator Hub to sign up today and start earning credits from your fans and
+          followers.
+        </Card.Description>
+      </Card.Header>
+      <Card.Footer>
+        <Link
+          aria-label="Go to Acme Creator Hub (opens in new tab)"
+          href="https://heroui.com"
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          Creator Hub
+          <Link.Icon aria-hidden="true" />
+        </Link>
+      </Card.Footer>
+    </Card>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Card className="w-[320px]" variant="transparent">
+        <Card.Header>
+          <Card.Title>Transparent</Card.Title>
+          <Card.Description>Minimal prominence with transparent background</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use for less important content or nested cards</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="default">
+        <Card.Header>
+          <Card.Title>Default</Card.Title>
+          <Card.Description>Standard card appearance (bg-surface)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>The default card variant for most use cases</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="secondary">
+        <Card.Header>
+          <Card.Title>Secondary</Card.Title>
+          <Card.Description>Medium prominence (bg-surface-secondary)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use to draw moderate attention</p>
+        </Card.Content>
+      </Card>
+
+      <Card className="w-[320px]" variant="tertiary">
+        <Card.Header>
+          <Card.Title>Tertiary</Card.Title>
+          <Card.Description>Higher prominence (bg-surface-tertiary)</Card.Description>
+        </Card.Header>
+        <Card.Content>
+          <p>Use for primary or featured content</p>
+        </Card.Content>
+      </Card>
+    </div>
+  ),
+};
+
+export const Horizontal: Story = {
+  render: (args) => (
+    <Card className="w-full items-stretch md:flex-row" {...args}>
+      <img
+        alt="Porsche 911 Golden Edition"
+        className="pointer-events-none aspect-square w-full rounded-3xl object-cover select-none md:max-w-[136px]"
+        loading="lazy"
+        src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/components/card/porsche-911.png"
+      />
+      <div className="flex flex-1 flex-col gap-3">
+        <Card.Header className="gap-1">
+          <Card.Title>Get the new Porsche 911 golden edition</Card.Title>
+          <Card.Description>
+            Experience unmatched luxury and performance with the Porsche 911 Golden Edition—where
+            sleek design meets cutting-edge tech and pure driving thrill.
+          </Card.Description>
+        </Card.Header>
+        <Card.Footer className="mt-auto flex w-full flex-row items-center justify-between">
+          <div className="flex flex-col">
+            <span
+              aria-label="Price: 36,799 US dollars"
+              className="text-sm font-medium text-foreground"
+            >
+              $36,799
+            </span>
+            <span aria-label="Available stock: 11 units" className="text-xs text-muted">
+              11 available
+            </span>
+          </div>
+          <Button>Buy Now</Button>
+        </Card.Footer>
+      </div>
+    </Card>
+  ),
+};
+
+export const WithAvatar: Story = {
+  render: (args) => (
+    <div className="flex gap-4">
+      <Card className="w-[200px] gap-2" {...args}>
+        <img
+          alt="Indie Hackers community"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+        />
+        <Card.Header>
+          <Card.Title>Indie Hackers</Card.Title>
+          <Card.Description>148 members</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="Martha's profile picture" className="size-5">
+            <Avatar.Image
+              alt="Martha's avatar"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+            />
+            <Avatar.Fallback className="text-xs">IH</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">By Martha</span>
+        </Card.Footer>
+      </Card>
+
+      <Card className="w-[200px] gap-2" {...args}>
+        <img
+          alt="AI Builders community"
+          className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none"
+          loading="lazy"
+          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+        />
+        <Card.Header>
+          <Card.Title>AI Builders</Card.Title>
+          <Card.Description>362 members</Card.Description>
+        </Card.Header>
+        <Card.Footer className="flex gap-2">
+          <Avatar aria-label="John's profile picture" className="size-5">
+            <Avatar.Image
+              alt="John's avatar - blue themed"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback className="text-xs">B</Avatar.Fallback>
+          </Avatar>
+          <span className="text-xs">By John</span>
+        </Card.Footer>
+      </Card>
+    </div>
+  ),
+};
+
+export const WithImages: Story = {
+  parameters: {
+    layout: "fullscreen",
+  },
+  render: (args) => (
+    <div className="flex w-full items-center justify-center">
+      <div className="grid w-full max-w-2xl grid-cols-12 gap-4 p-4">
+        {/* Row 1: Large Product Card - Available Soon */}
+        <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row" {...args}>
+          <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+            <img
+              alt="Cherries"
+              className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+              loading="lazy"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+            />
+          </div>
+          <div className="flex flex-1 flex-col gap-3">
+            <Card.Header className="gap-1">
+              <Card.Title className="pr-8">Become an ACME Creator!</Card.Title>
+              <Card.Description>
+                Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
+                faucibus etiam.
+              </Card.Description>
+              <CloseButton aria-label="Close banner" className="absolute top-3 right-3" />
+            </Card.Header>
+            <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
+              <div className="flex flex-col">
+                <span className="text-sm font-medium text-foreground">Only 10 spots</span>
+                <span className="text-xs text-muted">Submission ends Oct 10.</span>
+              </div>
+              <Button className="w-full sm:w-auto">Apply Now</Button>
+            </Card.Footer>
+          </div>
+        </Card>
+
+        {/* Row 2 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* Left Column */}
+          <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6">
+            {/* Top Card */}
+            <Card className="col-span-12">
+              <div className="absolute top-3 right-3 z-10">
+                <CloseButton aria-label="Close notification" />
+              </div>
+              <Card.Header className="gap-3">
+                <Icon
+                  aria-label="Dollar sign icon"
+                  className="text-primary size-8 shrink-0"
+                  icon="gravity-ui:circle-dollar"
+                  role="img"
+                />
+                <div className="flex flex-col gap-1">
+                  <span className="text-xs font-medium text-muted uppercase">PAYMENT</span>
+                  <Card.Title className="pr-8 text-sm sm:text-base">
+                    You can now withdraw on crypto
+                  </Card.Title>
+                  <Card.Description className="text-xs sm:text-sm">
+                    Add your wallet in settings to withdraw
+                  </Card.Description>
+                </div>
+              </Card.Header>
+              <Card.Footer>
+                <Link aria-label="Go to settings" href="#" rel="noopener noreferrer">
+                  Go to settings
+                  <Link.Icon aria-hidden="true" />
+                </Link>
+              </Card.Footer>
+            </Card>
+            {/* Bottom cards */}
+            <div className="col-span-12 grid grid-cols-12 gap-4">
+              {/* Left Card */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="Demo 1"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">Indie Hackers</p>
+                  <p className="text-xs text-muted">148 members</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="John"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+                    />
+                    <Avatar.Fallback>JK</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">By John</p>
+                </Card.Footer>
+              </Card>
+              {/* Right Card */}
+              <Card className="col-span-12 gap-2 sm:col-span-6">
+                <Card.Header>
+                  <Avatar className="size-[56px] rounded-xl">
+                    <Avatar.Image
+                      alt="Demo 2"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+                    />
+                    <Avatar.Fallback>AB</Avatar.Fallback>
+                  </Avatar>
+                </Card.Header>
+                <Card.Content className="mt-1">
+                  <p className="text-sm leading-4 font-medium">AI Builders</p>
+                  <p className="text-xs text-muted">362 members</p>
+                </Card.Content>
+                <Card.Footer className="flex items-center gap-2">
+                  <Avatar className="size-4">
+                    <Avatar.Image
+                      alt="John"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+                    />
+                    <Avatar.Fallback>M</Avatar.Fallback>
+                  </Avatar>
+                  <p className="text-xs text-muted">By Martha</p>
+                </Card.Footer>
+              </Card>
+            </div>
+          </div>
+          {/* Right Column */}
+          <Card className="col-span-12 min-h-[200px] rounded-3xl lg:col-span-6" {...args}>
+            {/* Background image */}
+            <img
+              alt="NEO Home Robot"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg"
+            />
+
+            {/* Header */}
+            <Card.Header className="z-10 text-white">
+              <Card.Title className="text-xs font-semibold tracking-wide text-black/70">
+                NEO
+              </Card.Title>
+              <Card.Description className="text-sm leading-5 font-medium text-black/50">
+                Home Robot
+              </Card.Description>
+            </Card.Header>
+
+            {/* Bottom gradient blur overlay */}
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute right-0 bottom-0 left-0 h-[64px]"
+            >
+              <div
+                className="absolute inset-0 h-[100%] rounded-b-[inherit] backdrop-blur-sm"
+                style={{
+                  WebkitMaskImage: "linear-gradient(to top, black 30%, transparent)",
+                  maskImage: "linear-gradient(to top, black 30%, transparent)",
+                  maskRepeat: "no-repeat",
+                  maskSize: "100% 100%",
+                }}
+              />
+            </div>
+            {/* Footer */}
+            <Card.Footer className="z-10 mt-auto flex items-center justify-between">
+              <div>
+                <div className="text-sm font-medium text-black">Available soon</div>
+                <div className="text-xs text-black/60">Get notified</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                Notify me
+              </Button>
+            </Card.Footer>
+          </Card>
+        </div>
+
+        {/* Row 3 */}
+        <div className="col-span-12 grid grid-cols-12 gap-4">
+          {/* Left Column: Card */}
+          <Card
+            className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]"
+            {...args}
+          >
+            <img
+              alt="NEO Home Robot"
+              aria-hidden="true"
+              className="absolute inset-0 h-full w-full object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo1.jpeg"
+            />
+
+            {/* Bottom gradient blur overlay */}
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute right-0 bottom-0 left-0 h-16 sm:h-20"
+            >
+              <div
+                className="absolute inset-0 h-[100%] rounded-b-[inherit] backdrop-blur-sm"
+                style={{
+                  WebkitMaskImage: "linear-gradient(to top, black 30%, transparent)",
+                  maskImage: "linear-gradient(to top, black 30%, transparent)",
+                  maskRepeat: "no-repeat",
+                  maskSize: "100% 100%",
+                }}
+              />
+            </div>
+            <Card.Footer className="z-10 mt-auto flex items-end justify-between">
+              <div>
+                <div className="text-base font-medium text-black sm:text-lg">NEO</div>
+                <div className="text-xs font-medium text-black/50 sm:text-sm">$499/m</div>
+              </div>
+              <Button className="bg-white text-black" size="sm" variant="tertiary">
+                Get now
+              </Button>
+            </Card.Footer>
+          </Card>
+
+          {/* Right Column: Cards Stack */}
+          <div className="col-span-12 flex flex-col gap-2 md:col-span-4 md:justify-between md:gap-0">
+            {/* 1 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Futuristic Robot"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Bridging the Future</Card.Title>
+                <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
+              </div>
+            </Card>
+            {/* 2 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Avocado"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Avocado Hackathon</Card.Title>
+                <Card.Description className="text-xs">Wed, 4:30 PM</Card.Description>
+              </div>
+            </Card>
+            {/* 3 */}
+            <Card className="flex flex-row gap-3 p-1" variant="transparent">
+              <img
+                alt="Sound Electro event"
+                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                loading="lazy"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg"
+              />
+              <div className="flex flex-1 flex-col justify-center gap-1">
+                <Card.Title className="text-sm">Sound Electro | Beyond art</Card.Title>
+                <Card.Description className="text-xs">Fri, 8:00 PM</Card.Description>
+              </div>
+            </Card>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const WithForm: Story = {
+  render: (args) => {
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const data: Record<string, string> = {};
+
+      // Convert FormData to plain object
+      formData.forEach((value, key) => {
+        data[key] = value.toString();
+      });
+
+      alert("Form submitted successfully!");
+    };
+
+    return (
+      <Card className="w-full max-w-md" {...args}>
+        <Card.Header>
+          <Card.Title>Login</Card.Title>
+          <Card.Description>Enter your credentials to access your account</Card.Description>
+        </Card.Header>
+        <Form onSubmit={onSubmit}>
+          <Card.Content>
+            <div className="flex flex-col gap-4">
+              <TextField name="email" type="email">
+                <Label>Email</Label>
+                <Input placeholder="email@example.com" variant="secondary" />
+              </TextField>
+              <TextField name="password" type="password">
+                <Label>Password</Label>
+                <Input placeholder="••••••••" variant="secondary" />
+              </TextField>
+            </div>
+          </Card.Content>
+          <Card.Footer className="mt-4 flex flex-col gap-2">
+            <Button className="w-full" type="submit">
+              Sign In
+            </Button>
+            <Link className="text-center text-sm" href="#">
+              Forgot password?
+            </Link>
+          </Card.Footer>
+        </Form>
+      </Card>
+    );
+  },
+};
diff --git a/packages/react/src/components/card/card.tsx b/packages/react/src/components/card/card.tsx
new file mode 100644
index 0000000..a454525
--- /dev/null
+++ b/packages/react/src/components/card/card.tsx
@@ -0,0 +1,214 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {CardVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {cardVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Context
+ * -----------------------------------------------------------------------------------------------*/
+interface CardContext {
+  slots?: ReturnType<typeof cardVariants>;
+}
+
+const CardContext = createContext<CardContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Root
+ * -----------------------------------------------------------------------------------------------*/
+interface CardRootProps<E extends keyof React.JSX.IntrinsicElements = "div"> extends DOMRenderProps<
+  E,
+  undefined
+> {
+  children: ReactNode;
+  className?: string;
+  /** Visual variant. @default "default" */
+  variant?: CardVariants["variant"];
+}
+
+const CardRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  variant = "default",
+  ...props
+}: CardRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CardRootProps<E>>) => {
+  const slots = React.useMemo(() => cardVariants({variant}), [variant]);
+
+  const content = (
+    <dom.div className={slots.base({className})} data-slot="card" {...(props as any)}>
+      {children}
+    </dom.div>
+  );
+
+  return (
+    <CardContext value={{slots}}>
+      {variant === "transparent" ? (
+        content
+      ) : (
+        // Allows inner components to apply "on-surface" colors for proper contrast
+        <SurfaceContext
+          value={{
+            variant: variant as SurfaceVariants["variant"],
+          }}
+        >
+          {content}
+        </SurfaceContext>
+      )}
+    </CardContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Header
+ * -----------------------------------------------------------------------------------------------*/
+interface CardHeaderProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CardHeader = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: CardHeaderProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CardHeaderProps<E>>) => {
+  const {slots} = use(CardContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="card-header"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Title
+ * -----------------------------------------------------------------------------------------------*/
+interface CardTitleProps<E extends keyof React.JSX.IntrinsicElements = "h3"> extends DOMRenderProps<
+  E,
+  undefined
+> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CardTitle = <E extends keyof React.JSX.IntrinsicElements = "h3">({
+  children,
+  className,
+  ...props
+}: CardTitleProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CardTitleProps<E>>) => {
+  const {slots} = use(CardContext);
+
+  return (
+    <dom.h3
+      className={composeSlotClassName(slots?.title, className)}
+      data-slot="card-title"
+      {...(props as any)}
+    >
+      {children}
+    </dom.h3>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Description
+ * -----------------------------------------------------------------------------------------------*/
+interface CardDescriptionProps<
+  E extends keyof React.JSX.IntrinsicElements = "p",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CardDescription = <E extends keyof React.JSX.IntrinsicElements = "p">({
+  children,
+  className,
+  ...props
+}: CardDescriptionProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CardDescriptionProps<E>>) => {
+  const {slots} = use(CardContext);
+
+  return (
+    <dom.p
+      className={composeSlotClassName(slots?.description, className)}
+      data-slot="card-description"
+      {...(props as any)}
+    >
+      {children}
+    </dom.p>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Content
+ * -----------------------------------------------------------------------------------------------*/
+interface CardContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CardContent = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: CardContentProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CardContentProps<E>>) => {
+  const {slots} = use(CardContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.content, className)}
+      data-slot="card-content"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Card Footer
+ * -----------------------------------------------------------------------------------------------*/
+interface CardFooterProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CardFooter = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: CardFooterProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof CardFooterProps<E>>) => {
+  const {slots} = use(CardContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.footer, className)}
+      data-slot="card-footer"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {CardRoot, CardHeader, CardTitle, CardDescription, CardContent, CardFooter};
+
+export type {
+  CardRootProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+};
diff --git a/packages/react/src/components/card/index.ts b/packages/react/src/components/card/index.ts
new file mode 100644
index 0000000..7ec791d
--- /dev/null
+++ b/packages/react/src/components/card/index.ts
@@ -0,0 +1,47 @@
+import type {ComponentProps} from "react";
+
+import {CardContent, CardDescription, CardFooter, CardHeader, CardRoot, CardTitle} from "./card";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Card = Object.assign(CardRoot, {
+  Root: CardRoot,
+  Header: CardHeader,
+  Title: CardTitle,
+  Description: CardDescription,
+  Content: CardContent,
+  Footer: CardFooter,
+});
+
+export type Card = {
+  Props: ComponentProps<typeof CardRoot>;
+  RootProps: ComponentProps<typeof CardRoot>;
+  HeaderProps: ComponentProps<typeof CardHeader>;
+  TitleProps: ComponentProps<typeof CardTitle>;
+  DescriptionProps: ComponentProps<typeof CardDescription>;
+  ContentProps: ComponentProps<typeof CardContent>;
+  FooterProps: ComponentProps<typeof CardFooter>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {CardRoot, CardHeader, CardTitle, CardDescription, CardContent, CardFooter};
+
+export type {
+  CardRootProps,
+  CardRootProps as CardProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+} from "./card";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {cardVariants} from "@heroui/styles";
+
+export type {CardVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/checkbox-group/checkbox-group.stories.tsx b/packages/react/src/components/checkbox-group/checkbox-group.stories.tsx
new file mode 100644
index 0000000..9eb4041
--- /dev/null
+++ b/packages/react/src/components/checkbox-group/checkbox-group.stories.tsx
@@ -0,0 +1,289 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Button} from "../button";
+import {Checkbox} from "../checkbox";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+
+import {CheckboxGroup} from "./index";
+
+export default {
+  argTypes: {},
+  parameters: {
+    layout: "centered",
+  },
+  component: CheckboxGroup,
+  title: "Components/Forms/CheckboxGroup",
+} as Meta<typeof CheckboxGroup>;
+
+type Story = StoryObj<typeof CheckboxGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <CheckboxGroup name="interests">
+      <Label>Select your interests</Label>
+      <Description>Choose all that apply</Description>
+      <Checkbox value="coding">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Coding
+        </Checkbox.Content>
+        <Description>Love building software</Description>
+      </Checkbox>
+      <Checkbox value="design">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Design
+        </Checkbox.Content>
+        <Description>Enjoy creating beautiful interfaces</Description>
+      </Checkbox>
+      <Checkbox value="writing">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Writing
+        </Checkbox.Content>
+        <Description>Passionate about content creation</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  ),
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <CheckboxGroup name="features">
+      <Label>Features</Label>
+      <Description>Select the features you want</Description>
+      <Checkbox value="notifications">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Email notifications
+        </Checkbox.Content>
+        <Description>Receive updates via email</Description>
+      </Checkbox>
+      <Checkbox value="newsletter">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg
+                    aria-hidden="true"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeLinecap="round"
+                    strokeWidth={2}
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Newsletter
+        </Checkbox.Content>
+        <Description>Get weekly newsletters</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  ),
+};
+
+export const Indeterminate: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState(["coding"]);
+    const allOptions = ["coding", "design", "writing"];
+
+    return (
+      <div>
+        <Checkbox
+          isIndeterminate={selected.length > 0 && selected.length < allOptions.length}
+          isSelected={selected.length === allOptions.length}
+          name="select-all"
+          onChange={(isSelected: boolean) => {
+            setSelected(isSelected ? allOptions : []);
+          }}
+        >
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Select all
+          </Checkbox.Content>
+        </Checkbox>
+        <div className="ml-6 flex flex-col gap-2">
+          <CheckboxGroup value={selected} onChange={setSelected}>
+            <Checkbox value="coding">
+              <Checkbox.Content>
+                <Checkbox.Control>
+                  <Checkbox.Indicator />
+                </Checkbox.Control>
+                Coding
+              </Checkbox.Content>
+            </Checkbox>
+            <Checkbox value="design">
+              <Checkbox.Content>
+                <Checkbox.Control>
+                  <Checkbox.Indicator />
+                </Checkbox.Control>
+                Design
+              </Checkbox.Content>
+            </Checkbox>
+            <Checkbox value="writing">
+              <Checkbox.Content>
+                <Checkbox.Control>
+                  <Checkbox.Indicator />
+                </Checkbox.Control>
+                Writing
+              </Checkbox.Content>
+            </Checkbox>
+          </CheckboxGroup>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Validation: Story = {
+  render: () => {
+    return (
+      <Form
+        className="flex flex-col gap-4 px-4"
+        onSubmit={(e) => {
+          e.preventDefault();
+
+          const formData = new FormData(e.currentTarget);
+          const values = formData.getAll("preferences");
+
+          alert(`Selected preferences: ${values.join(", ")}`);
+        }}
+      >
+        <CheckboxGroup isRequired name="preferences">
+          <Label>Preferences</Label>
+          <Description>Select at least one preference</Description>
+          <Checkbox value="email">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              Email notifications
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="sms">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              SMS notifications
+            </Checkbox.Content>
+          </Checkbox>
+          <Checkbox value="push">
+            <Checkbox.Content>
+              <Checkbox.Control>
+                <Checkbox.Indicator />
+              </Checkbox.Control>
+              Push notifications
+            </Checkbox.Content>
+          </Checkbox>
+          <FieldError>Please select at least one notification method.</FieldError>
+        </CheckboxGroup>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState(["coding", "design"]);
+
+    return (
+      <CheckboxGroup
+        className="min-w-[320px]"
+        name="skills"
+        value={selected}
+        onChange={setSelected}
+      >
+        <Label>Your skills</Label>
+        <Checkbox value="coding">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Coding
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="design">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Design
+          </Checkbox.Content>
+        </Checkbox>
+        <Checkbox value="writing">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Writing
+          </Checkbox.Content>
+        </Checkbox>
+        <Label className="my-4 text-sm text-muted">Selected: {selected.join(", ") || "None"}</Label>
+      </CheckboxGroup>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <CheckboxGroup isDisabled name="disabled-features">
+      <Label>Features</Label>
+      <Description>Feature selection is temporarily disabled</Description>
+      <Checkbox value="feature1">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Feature 1
+        </Checkbox.Content>
+        <Description>This feature is coming soon</Description>
+      </Checkbox>
+      <Checkbox value="feature2">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Feature 2
+        </Checkbox.Content>
+        <Description>This feature is coming soon</Description>
+      </Checkbox>
+    </CheckboxGroup>
+  ),
+};
diff --git a/packages/react/src/components/checkbox-group/checkbox-group.tsx b/packages/react/src/components/checkbox-group/checkbox-group.tsx
new file mode 100644
index 0000000..9fd4f65
--- /dev/null
+++ b/packages/react/src/components/checkbox-group/checkbox-group.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import type {CheckboxVariants} from "../checkbox";
+import type {CheckboxGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {checkboxGroupVariants} from "@heroui/styles";
+import React, {createContext} from "react";
+import {CheckboxGroup as CheckboxGroupPrimitive} from "react-aria-components/CheckboxGroup";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * CheckboxGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+interface CheckboxGroupContext {
+  variant?: CheckboxVariants["variant"];
+}
+
+const CheckboxGroupContext = createContext<CheckboxGroupContext>({});
+
+interface CheckboxGroupProps
+  extends ComponentPropsWithRef<typeof CheckboxGroupPrimitive>, CheckboxGroupVariants {}
+
+const CheckboxGroup = ({children, className, variant, ...props}: CheckboxGroupProps) => {
+  const styles = React.useMemo(() => checkboxGroupVariants({variant}), [variant]);
+
+  return (
+    <CheckboxGroupContext.Provider value={{variant}}>
+      <CheckboxGroupPrimitive
+        className={composeTwRenderProps(className, styles)}
+        data-slot="checkbox-group"
+        {...props}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </CheckboxGroupPrimitive>
+    </CheckboxGroupContext.Provider>
+  );
+};
+
+export {CheckboxGroup, CheckboxGroupContext};
+export type {CheckboxGroupProps};
diff --git a/packages/react/src/components/checkbox-group/index.ts b/packages/react/src/components/checkbox-group/index.ts
new file mode 100644
index 0000000..be1866e
--- /dev/null
+++ b/packages/react/src/components/checkbox-group/index.ts
@@ -0,0 +1,3 @@
+export {CheckboxGroup} from "./checkbox-group";
+export type {CheckboxGroupProps} from "./checkbox-group";
+export {checkboxGroupVariants, type CheckboxGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/checkbox/checkbox.stories.tsx b/packages/react/src/components/checkbox/checkbox.stories.tsx
new file mode 100644
index 0000000..41e1cc7
--- /dev/null
+++ b/packages/react/src/components/checkbox/checkbox.stories.tsx
@@ -0,0 +1,379 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cx} from "tailwind-variants";
+
+import {CheckboxGroup} from "../checkbox-group";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Label} from "../label";
+
+import {Checkbox} from "./index";
+
+export default {
+  argTypes: {},
+  component: Checkbox,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Forms/Checkbox",
+} as Meta<typeof Checkbox>;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+  render: () => (
+    <Checkbox name="terms">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Accept terms and conditions
+      </Checkbox.Content>
+    </Checkbox>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 px-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Primary variant</p>
+        <Checkbox name="primary" variant="primary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Primary checkbox
+          </Checkbox.Content>
+          <Description>Standard styling with default background</Description>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary variant</p>
+        <Checkbox name="secondary" variant="secondary">
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Secondary checkbox
+          </Checkbox.Content>
+          <Description>Lower emphasis variant for use in surfaces</Description>
+        </Checkbox>
+      </div>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <Checkbox name="terms">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Accept terms and conditions
+      </Checkbox.Content>
+      <Description>I agree to the terms and privacy policy</Description>
+    </Checkbox>
+  ),
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <div className="flex gap-4 px-4">
+      <Checkbox defaultSelected id="heart">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg viewBox="0 0 24 24">
+                    <path
+                      d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z"
+                      fill="currentColor"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Heart
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox defaultSelected id="plus">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isSelected}) =>
+                isSelected ? (
+                  <svg fill="none" viewBox="0 0 24 24">
+                    <path
+                      d="M6 12H18"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                    <path
+                      d="M12 18V6"
+                      stroke="currentColor"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth="3"
+                    />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Plus
+        </Checkbox.Content>
+      </Checkbox>
+      <Checkbox isIndeterminate id="indeterminate">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator>
+              {({isIndeterminate}) =>
+                isIndeterminate ? (
+                  <svg stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24">
+                    <line x1="21" x2="3" y1="12" y2="12" />
+                  </svg>
+                ) : null
+              }
+            </Checkbox.Indicator>
+          </Checkbox.Control>
+          Indeterminate
+        </Checkbox.Content>
+      </Checkbox>
+    </div>
+  ),
+};
+
+export const Indeterminate: Story = {
+  render: () => {
+    return (
+      <Checkbox isIndeterminate id="select-all">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+          Select all
+        </Checkbox.Content>
+        <Description>Shows indeterminate state</Description>
+      </Checkbox>
+    );
+  },
+};
+
+export const ControlOnly: Story = {
+  render: () => (
+    <Checkbox aria-label="Accept" name="control-only">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+      </Checkbox.Content>
+    </Checkbox>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <Checkbox isDisabled id="feature">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Feature
+      </Checkbox.Content>
+      <Description>This feature is coming soon</Description>
+    </Checkbox>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [isSelected, setIsSelected] = React.useState(true);
+
+    return (
+      <div className="flex flex-col gap-3 px-4">
+        <Checkbox id="notifications" isSelected={isSelected} onChange={setIsSelected}>
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Email notifications
+          </Checkbox.Content>
+        </Checkbox>
+        <p className="mt-2 text-sm text-muted">
+          Status: <span className="font-medium">{isSelected ? "Enabled" : "Disabled"}</span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const RenderProps: Story = {
+  render: () => (
+    <Checkbox id="terms">
+      {({isSelected}) => (
+        <>
+          <Checkbox.Content>
+            <Checkbox.Control>
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            {isSelected ? "Terms accepted" : "Accept terms"}
+          </Checkbox.Content>
+          <Description>
+            {isSelected ? "Thank you for accepting" : "Please read and accept the terms"}
+          </Description>
+        </>
+      )}
+    </Checkbox>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <Checkbox isInvalid isRequired name="agreement">
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        I agree to the terms
+      </Checkbox.Content>
+      <FieldError>You must accept the terms to continue</FieldError>
+    </Checkbox>
+  ),
+};
+
+export const Validation: Story = {
+  render: () => (
+    <Checkbox
+      isRequired
+      name="newsletter"
+      validate={(isSelected) => (isSelected ? true : "Please subscribe to continue")}
+    >
+      <Checkbox.Content>
+        <Checkbox.Control>
+          <Checkbox.Indicator />
+        </Checkbox.Control>
+        Subscribe to newsletter
+      </Checkbox.Content>
+      <FieldError />
+    </Checkbox>
+  ),
+};
+
+export const FullRounded: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 px-4">
+      <div className="flex flex-col gap-3">
+        <Label className="text-muted">Rounded checkboxes</Label>
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-2"
+          id="small-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-3 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Small size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox id="default-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-4 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Default size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox id="large-rounded">
+          <Checkbox.Content>
+            <Checkbox.Control className="size-5 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Large size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+      <div className="flex flex-col gap-3">
+        <Checkbox
+          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-4"
+          id="xl-rounded"
+        >
+          <Checkbox.Content>
+            <Checkbox.Control className="size-6 rounded-full before:rounded-full">
+              <Checkbox.Indicator />
+            </Checkbox.Control>
+            Extra large size
+          </Checkbox.Content>
+        </Checkbox>
+      </div>
+    </div>
+  ),
+};
+
+export const FeaturesAndAddOnsExample: Story = {
+  render: () => {
+    const addOns = [
+      {
+        title: "Email Notifications",
+        value: "email",
+        description: "Receive updates via email",
+        icon: "gravity-ui:envelope",
+      },
+      {
+        title: "SMS Alerts",
+        value: "sms",
+        description: "Get instant SMS notifications",
+        icon: "gravity-ui:comment",
+      },
+      {
+        title: "Push Notifications",
+        value: "push",
+        description: "Browser and mobile push alerts",
+        icon: "gravity-ui:bell",
+      },
+    ];
+
+    return (
+      <div className="flex w-full flex-col items-center gap-10 px-4 py-8">
+        <section className="flex w-full min-w-[320px] flex-col gap-4">
+          <CheckboxGroup name="notification-preferences">
+            <Label>Notification preferences</Label>
+            <Description>Choose how you want to receive updates</Description>
+            <div className="flex flex-col gap-2">
+              {addOns.map((addon) => (
+                <Checkbox key={addon.value} id={addon.value} value={addon.value}>
+                  <Checkbox.Content
+                    className={cx(
+                      "group relative flex w-full flex-row items-start justify-start gap-4 rounded-3xl bg-surface-tertiary px-5 py-4 transition-all",
+                      "data-[selected=true]:bg-accent/10",
+                    )}
+                  >
+                    <Checkbox.Control className="absolute top-3 right-4 size-5 rounded-full before:rounded-full">
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                    <Icon className="size-5 text-accent" icon={addon.icon} />
+                    <div className="flex flex-col gap-1">
+                      <span>{addon.title}</span>
+                      <Description>{addon.description}</Description>
+                    </div>
+                  </Checkbox.Content>
+                </Checkbox>
+              ))}
+            </div>
+          </CheckboxGroup>
+        </section>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/checkbox/checkbox.tsx b/packages/react/src/components/checkbox/checkbox.tsx
new file mode 100644
index 0000000..6a6978e
--- /dev/null
+++ b/packages/react/src/components/checkbox/checkbox.tsx
@@ -0,0 +1,195 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {CheckboxVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {
+  CheckboxButtonRenderProps,
+  CheckboxFieldRenderProps,
+} from "react-aria-components/Checkbox";
+
+import {checkboxVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  CheckboxButton as CheckboxButtonPrimitive,
+  CheckboxField as CheckboxFieldPrimitive,
+} from "react-aria-components/Checkbox";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CheckboxGroupContext} from "../checkbox-group/checkbox-group";
+
+interface CheckboxContext {
+  slots?: ReturnType<typeof checkboxVariants>;
+  state?: CheckboxFieldRenderProps;
+}
+
+const CheckboxContext = createContext<CheckboxContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Checkbox (Field) — React Aria `CheckboxField`.
+ * -----------------------------------------------------------------------------------------------*/
+interface CheckboxRootProps
+  extends ComponentPropsWithRef<typeof CheckboxFieldPrimitive>, CheckboxVariants {
+  /** The name of the checkbox, used when submitting an HTML form. */
+  name?: string;
+}
+
+const CheckboxRoot = ({children, className, variant, ...props}: CheckboxRootProps) => {
+  const checkboxGroupContext = use(CheckboxGroupContext);
+  const effectiveVariant = variant ?? checkboxGroupContext.variant;
+  const slots = React.useMemo(
+    () => checkboxVariants({variant: effectiveVariant}),
+    [effectiveVariant],
+  );
+
+  return (
+    <CheckboxFieldPrimitive
+      data-slot="checkbox"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(state) => (
+        <CheckboxContext value={{slots, state}}>
+          {typeof children === "function" ? children(state) : children}
+        </CheckboxContext>
+      )}
+    </CheckboxFieldPrimitive>
+  );
+};
+
+CheckboxRoot.displayName = "HeroUI.Checkbox";
+
+/* -------------------------------------------------------------------------------------------------
+ * Checkbox.Content — the clickable `CheckboxButton` label wrapping the control + `Label`.
+ * Keep `Description`/`FieldError` as siblings of `Checkbox.Content`.
+ * -----------------------------------------------------------------------------------------------*/
+interface CheckboxContentProps extends ComponentPropsWithRef<typeof CheckboxButtonPrimitive> {}
+
+const CheckboxContent = ({children, className, ...props}: CheckboxContentProps) => {
+  const {slots} = use(CheckboxContext);
+
+  return (
+    <CheckboxButtonPrimitive
+      data-slot="checkbox-content"
+      {...props}
+      className={composeTwRenderProps(className, slots?.content())}
+    >
+      {children}
+    </CheckboxButtonPrimitive>
+  );
+};
+
+CheckboxContent.displayName = "HeroUI.Checkbox.Content";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface CheckboxControlProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const CheckboxControl = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: CheckboxControlProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CheckboxControlProps<E>>) => {
+  const {slots} = use(CheckboxContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.control, className)}
+      data-slot="checkbox-control"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+CheckboxControl.displayName = "HeroUI.Checkbox.Control";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface CheckboxIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode | ((props: CheckboxFieldRenderProps) => ReactNode);
+  className?: string;
+}
+
+const CheckboxIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: CheckboxIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof CheckboxIndicatorProps<E>>) => {
+  const {slots, state} = use(CheckboxContext);
+
+  const isSelected = state?.isSelected;
+  const isIndeterminate = state?.isIndeterminate;
+
+  const content =
+    typeof children === "function" ? (
+      children(state ?? ({} as CheckboxFieldRenderProps))
+    ) : children ? (
+      children
+    ) : isIndeterminate ? (
+      <svg
+        aria-hidden="true"
+        data-slot="checkbox-default-indicator--indeterminate"
+        fill="none"
+        role="presentation"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeWidth={3}
+        viewBox="0 0 24 24"
+      >
+        <line x1="21" x2="3" y1="12" y2="12" />
+      </svg>
+    ) : (
+      <svg
+        aria-hidden="true"
+        data-slot="checkbox-default-indicator--checkmark"
+        fill="none"
+        role="presentation"
+        stroke="currentColor"
+        strokeDasharray={22}
+        strokeDashoffset={isSelected ? 44 : 66}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        viewBox="0 0 17 18"
+      >
+        <polyline points="1 9 7 14 15 4" />
+      </svg>
+    );
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="checkbox-indicator"
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+CheckboxIndicator.displayName = "HeroUI.Checkbox.Indicator";
+
+/* ----------------------------------------------------------------------------------------------*/
+
+export {CheckboxRoot, CheckboxContent, CheckboxControl, CheckboxIndicator};
+export type {
+  CheckboxRootProps,
+  CheckboxContentProps,
+  CheckboxControlProps,
+  CheckboxIndicatorProps,
+  CheckboxFieldRenderProps,
+  CheckboxButtonRenderProps,
+};
diff --git a/packages/react/src/components/checkbox/index.ts b/packages/react/src/components/checkbox/index.ts
new file mode 100644
index 0000000..2bc8a3b
--- /dev/null
+++ b/packages/react/src/components/checkbox/index.ts
@@ -0,0 +1,45 @@
+import type {ComponentProps} from "react";
+
+import {CheckboxContent, CheckboxControl, CheckboxIndicator, CheckboxRoot} from "./checkbox";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Checkbox = Object.assign(CheckboxRoot, {
+  Root: CheckboxRoot,
+  Content: CheckboxContent,
+  Control: CheckboxControl,
+  Indicator: CheckboxIndicator,
+});
+
+export type Checkbox = {
+  Props: ComponentProps<typeof CheckboxRoot>;
+  RootProps: ComponentProps<typeof CheckboxRoot>;
+  ContentProps: ComponentProps<typeof CheckboxContent>;
+  ControlProps: ComponentProps<typeof CheckboxControl>;
+  IndicatorProps: ComponentProps<typeof CheckboxIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {CheckboxContent, CheckboxControl, CheckboxIndicator, CheckboxRoot};
+
+export type {
+  CheckboxRootProps,
+  CheckboxRootProps as CheckboxProps,
+  CheckboxContentProps,
+  CheckboxControlProps,
+  CheckboxIndicatorProps,
+  CheckboxFieldRenderProps,
+  CheckboxButtonRenderProps,
+  /** @deprecated Use {@link CheckboxFieldRenderProps} for the root render prop, or {@link CheckboxButtonRenderProps} for content/control/indicator. */
+  CheckboxFieldRenderProps as CheckboxRenderProps,
+} from "./checkbox";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {checkboxVariants} from "@heroui/styles";
+
+export type {CheckboxVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/chip/chip.stories.tsx b/packages/react/src/components/chip/chip.stories.tsx
new file mode 100644
index 0000000..f129180
--- /dev/null
+++ b/packages/react/src/components/chip/chip.stories.tsx
@@ -0,0 +1,174 @@
+import type {ChipProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Separator} from "../separator";
+
+import {Chip} from "./index";
+
+export default {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["accent", "default", "success", "warning", "danger"],
+    },
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "tertiary", "soft"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+    //  TODO: Add sizes
+  },
+  component: Chip,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Data Display/Chip",
+} as Meta<typeof Chip>;
+
+const defaultArgs: ChipProps = {
+  children: "Label",
+  color: "accent",
+  variant: "secondary",
+};
+
+const Template = (props: ChipProps) => (
+  <div className="flex items-center gap-3">
+    <Chip {...props}>Label</Chip>
+  </div>
+);
+
+const SizesTemplate = (props: ChipProps) => (
+  <div className="flex items-center gap-3">
+    <Chip {...props} size="sm">
+      Small
+    </Chip>
+    <Chip {...props} size="md">
+      Medium
+    </Chip>
+    <Chip {...props} size="lg">
+      Large
+    </Chip>
+  </div>
+);
+
+const WithIconTemplate = (props: ChipProps) => (
+  <div className="flex items-center gap-3">
+    <Chip {...props}>
+      <Icon icon="gravity-ui:circle-dashed" />
+      <Chip.Label>Label</Chip.Label>
+      <Icon icon="gravity-ui:circle-dashed" />
+    </Chip>
+  </div>
+);
+
+const StatusesTemplate = (props: ChipProps) => {
+  const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {variants.map((variant) => (
+        <div key={variant} className="flex items-center gap-3">
+          <Chip {...props} variant={variant}>
+            <Icon icon="gravity-ui:circle-fill" width={6} />
+            <Chip.Label>Information</Chip.Label>
+          </Chip>
+          <Chip {...props} color="success" variant={variant}>
+            <Icon icon="gravity-ui:circle-fill" width={6} />
+            <Chip.Label>Completed</Chip.Label>
+          </Chip>
+          <Chip {...props} color="warning" variant={variant}>
+            <Icon icon="gravity-ui:circle-fill" width={6} />
+            <Chip.Label>Pending</Chip.Label>
+          </Chip>
+          <Chip {...props} color="danger" variant={variant}>
+            <Icon icon="gravity-ui:circle-fill" width={6} />
+            <Chip.Label>Failed</Chip.Label>
+          </Chip>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+const VariantsTemplate = (props: ChipProps) => {
+  const sizes = ["lg", "md", "sm"] as const;
+  const variants = ["primary", "secondary", "tertiary", "soft"] as const;
+  const colors = ["accent", "default", "success", "warning", "danger"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {sizes.map((size, index) => (
+        <React.Fragment key={size}>
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted capitalize">{size}</h3>
+            {/* Color labels header */}
+            <div className="flex items-center gap-3">
+              <div className="w-24 shrink-0" />
+              {colors.map((color) => (
+                <div
+                  key={color}
+                  className="flex shrink-0 items-center justify-center"
+                  style={{width: "130px"}}
+                >
+                  <span className="text-xs text-muted capitalize">{color}</span>
+                </div>
+              ))}
+            </div>
+            <div className="flex flex-col gap-3">
+              {variants.map((variant) => (
+                <div key={variant} className="flex items-center gap-3">
+                  <div className="w-24 shrink-0 text-sm text-muted capitalize">{variant}</div>
+                  {colors.map((color) => (
+                    <div
+                      key={color}
+                      className="flex shrink-0 items-center justify-center"
+                      style={{width: "130px"}}
+                    >
+                      <Chip {...props} color={color} size={size} variant={variant}>
+                        <Icon icon="gravity-ui:circle-dashed" />
+                        <Chip.Label>Label</Chip.Label>
+                        <Icon icon="gravity-ui:circle-dashed" />
+                      </Chip>
+                    </div>
+                  ))}
+                </div>
+              ))}
+            </div>
+          </div>
+          {index < sizes.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Sizes = {
+  args: defaultArgs,
+  render: SizesTemplate,
+};
+
+export const WithIcon = {
+  args: defaultArgs,
+  render: WithIconTemplate,
+};
+
+export const Statuses = {
+  args: defaultArgs,
+  render: StatusesTemplate,
+};
+
+export const Variants = {
+  args: defaultArgs,
+  render: VariantsTemplate,
+};
diff --git a/packages/react/src/components/chip/chip.tsx b/packages/react/src/components/chip/chip.tsx
new file mode 100644
index 0000000..a6c657b
--- /dev/null
+++ b/packages/react/src/components/chip/chip.tsx
@@ -0,0 +1,102 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ChipVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {chipVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Chip Context
+ * -----------------------------------------------------------------------------------------------*/
+type ChipContext = {
+  slots?: ReturnType<typeof chipVariants>;
+};
+
+const ChipContext = createContext<ChipContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Chip Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ChipRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+  /** Chip color. */
+  color?: ChipVariants["color"];
+  /** Chip size. */
+  size?: ChipVariants["size"];
+  /** Chip variant. */
+  variant?: ChipVariants["variant"];
+}
+
+const ChipRoot = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  color,
+  size,
+  variant,
+  ...props
+}: ChipRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ChipRootProps<E>>) => {
+  const slots = React.useMemo(() => chipVariants({color, size, variant}), [color, size, variant]);
+
+  const chipChildren = React.useMemo(() => {
+    if (typeof children === "string" || typeof children === "number") {
+      return <ChipLabel>{children}</ChipLabel>;
+    }
+
+    return children;
+  }, [children]);
+
+  return (
+    <ChipContext value={{slots}}>
+      <dom.span
+        {...(props as any)}
+        className={composeSlotClassName(slots.base, className)}
+        data-slot="chip"
+      >
+        {chipChildren}
+      </dom.span>
+    </ChipContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Chip Label
+ * -----------------------------------------------------------------------------------------------*/
+interface ChipLabelProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ChipLabel = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: ChipLabelProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ChipLabelProps<E>>) => {
+  const {slots} = use(ChipContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.label, className)}
+      data-slot="chip-label"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ChipRoot, ChipLabel};
+
+export type {ChipRootProps, ChipLabelProps};
diff --git a/packages/react/src/components/chip/index.ts b/packages/react/src/components/chip/index.ts
new file mode 100644
index 0000000..2c58ac7
--- /dev/null
+++ b/packages/react/src/components/chip/index.ts
@@ -0,0 +1,31 @@
+import type {ComponentProps} from "react";
+
+import {ChipLabel, ChipRoot} from "./chip";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Chip = Object.assign(ChipRoot, {
+  Root: ChipRoot,
+  Label: ChipLabel,
+});
+
+export type Chip = {
+  Props: ComponentProps<typeof ChipRoot>;
+  RootProps: ComponentProps<typeof ChipRoot>;
+  LabelProps: ComponentProps<typeof ChipLabel>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ChipRoot, ChipLabel};
+
+export type {ChipRootProps, ChipRootProps as ChipProps, ChipLabelProps} from "./chip";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {chipVariants} from "@heroui/styles";
+
+export type {ChipVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/close-button/close-button.stories.tsx b/packages/react/src/components/close-button/close-button.stories.tsx
new file mode 100644
index 0000000..32fafcf
--- /dev/null
+++ b/packages/react/src/components/close-button/close-button.stories.tsx
@@ -0,0 +1,74 @@
+import type {CloseButtonProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useState} from "react";
+
+import {CloseButton} from "./index";
+
+export default {
+  argTypes: {
+    isDisabled: {
+      control: "boolean",
+    },
+    variant: {
+      control: "select",
+      options: ["default"],
+    },
+  },
+  component: CloseButton,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Buttons/CloseButton",
+} as Meta<typeof CloseButton>;
+
+const defaultArgs: CloseButtonProps = {
+  variant: "default",
+  isDisabled: false,
+};
+
+const Template = (args: CloseButtonProps) => (
+  <div className="flex gap-3">
+    <CloseButton {...args} />
+  </div>
+);
+
+const TemplateWithCustomIcon = (args: CloseButtonProps) => (
+  <div className="flex gap-3">
+    <CloseButton {...args}>
+      <Icon icon="gravity-ui:circle-xmark" />
+    </CloseButton>
+  </div>
+);
+
+const InteractiveTemplate = (args: CloseButtonProps) => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4">
+      <CloseButton
+        {...args}
+        aria-label={`Close (clicked ${count} times)`}
+        onPress={() => setCount(count + 1)}
+      />
+
+      <span className="text-sm">Clicked: {count} times</span>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithCustomIcon = {
+  args: defaultArgs,
+  render: TemplateWithCustomIcon,
+};
+
+export const Interactive = {
+  args: defaultArgs,
+  render: InteractiveTemplate,
+};
diff --git a/packages/react/src/components/close-button/close-button.tsx b/packages/react/src/components/close-button/close-button.tsx
new file mode 100644
index 0000000..cad686e
--- /dev/null
+++ b/packages/react/src/components/close-button/close-button.tsx
@@ -0,0 +1,53 @@
+"use client";
+
+import type {CloseButtonVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {closeButtonVariants} from "@heroui/styles";
+import {useMemo} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+
+import {composeTwRenderProps} from "../../utils";
+import {CloseIcon} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * Close Button Root
+ * -----------------------------------------------------------------------------------------------*/
+interface CloseButtonRootProps
+  extends ComponentPropsWithRef<typeof ButtonPrimitive>, CloseButtonVariants {}
+
+const CloseButtonRoot = ({
+  children,
+  className,
+  slot,
+  style,
+  variant,
+  ...rest
+}: CloseButtonRootProps) => {
+  const styles = useMemo(() => closeButtonVariants({variant}), [variant]);
+
+  return (
+    <ButtonPrimitive
+      aria-label="Close"
+      className={composeTwRenderProps(className, styles)}
+      data-slot="close-button"
+      slot={slot}
+      style={style}
+      type="button"
+      {...rest}
+    >
+      {(renderProps) =>
+        typeof children === "function"
+          ? children(renderProps)
+          : (children ?? <CloseIcon data-slot="close-button-icon" />)
+      }
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {CloseButtonRoot};
+
+export type {CloseButtonRootProps};
diff --git a/packages/react/src/components/close-button/index.ts b/packages/react/src/components/close-button/index.ts
new file mode 100644
index 0000000..baa26ad
--- /dev/null
+++ b/packages/react/src/components/close-button/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {CloseButtonRoot} from "./close-button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const CloseButton = Object.assign(CloseButtonRoot, {
+  Root: CloseButtonRoot,
+});
+
+export type CloseButton = {
+  Props: ComponentProps<typeof CloseButtonRoot>;
+  RootProps: ComponentProps<typeof CloseButtonRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {CloseButtonRoot};
+
+export type {CloseButtonRootProps, CloseButtonRootProps as CloseButtonProps} from "./close-button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {closeButtonVariants} from "@heroui/styles";
+
+export type {CloseButtonVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-area/color-area.stories.tsx b/packages/react/src/components/color-area/color-area.stories.tsx
new file mode 100644
index 0000000..6869a91
--- /dev/null
+++ b/packages/react/src/components/color-area/color-area.stories.tsx
@@ -0,0 +1,137 @@
+import type {ColorAreaRootProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {ColorSwatch} from "../color-swatch";
+import {parseColor} from "../rac";
+
+import {ColorArea} from "./index";
+
+export default {
+  argTypes: {
+    showDots: {
+      control: "boolean",
+    },
+  },
+  component: ColorArea,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Colors/ColorArea",
+} as Meta<typeof ColorArea>;
+
+const defaultArgs: ColorAreaRootProps = {
+  showDots: false,
+};
+
+const Template = (props: ColorAreaRootProps) => (
+  <div className="w-[300px]">
+    <ColorArea {...props}>
+      <ColorArea.Thumb />
+    </ColorArea>
+  </div>
+);
+
+const WithDotsTemplate = (props: ColorAreaRootProps) => (
+  <div className="w-[300px]">
+    <ColorArea {...props} showDots>
+      <ColorArea.Thumb />
+    </ColorArea>
+  </div>
+);
+
+const ControlledTemplate = (_props: ColorAreaRootProps) => {
+  const [color, setColor] = React.useState(parseColor("hsl(50, 100%, 50%)"));
+
+  return (
+    <div className="flex w-full flex-col gap-4">
+      <ColorArea value={color} onChange={setColor}>
+        <ColorArea.Thumb />
+      </ColorArea>
+      <p className="w-full min-w-[300px] text-sm text-muted">
+        Current color: <span className="font-medium">{color.toString("hsl")}</span>
+      </p>
+    </div>
+  );
+};
+
+const ColorChannelsTemplate = (_props: ColorAreaRootProps) => (
+  <div className="flex flex-col gap-8">
+    <div className="flex flex-col gap-2">
+      <p className="text-sm font-medium text-muted">HSB: Saturation vs Brightness (default)</p>
+      <ColorArea defaultValue="hsl(30, 100%, 50%)">
+        <ColorArea.Thumb />
+      </ColorArea>
+    </div>
+    <div className="flex flex-col gap-2">
+      <p className="text-sm font-medium text-muted">RGB: Red vs Green</p>
+      <ColorArea defaultValue="rgb(255, 100, 50)" xChannel="red" yChannel="green">
+        <ColorArea.Thumb />
+      </ColorArea>
+    </div>
+    <div className="flex flex-col gap-2">
+      <p className="text-sm font-medium text-muted">RGB: Blue vs Green</p>
+      <ColorArea defaultValue="rgb(50, 100, 255)" xChannel="blue" yChannel="green">
+        <ColorArea.Thumb />
+      </ColorArea>
+    </div>
+  </div>
+);
+
+const DisabledTemplate = (_props: ColorAreaRootProps) => (
+  <div className="w-[300px]">
+    <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)">
+      <ColorArea.Thumb />
+    </ColorArea>
+  </div>
+);
+
+const WithColorPreviewTemplate = (_props: ColorAreaRootProps) => {
+  const [color, setColor] = React.useState(parseColor("hsl(200, 100%, 50%)"));
+
+  return (
+    <div className="flex min-w-[300px] flex-col gap-4">
+      <ColorArea showDots value={color} onChange={setColor}>
+        <ColorArea.Thumb />
+      </ColorArea>
+      <div className="flex items-center gap-3">
+        <ColorSwatch color={color.toString("css")} size="lg" />
+        <div className="flex flex-col gap-0.5">
+          <span className="text-sm font-medium">{color.toString("hsl")}</span>
+          <span className="text-xs text-muted">{color.toString("hex")}</span>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithDots = {
+  args: defaultArgs,
+  render: WithDotsTemplate,
+};
+
+export const Controlled = {
+  args: defaultArgs,
+  render: ControlledTemplate,
+};
+
+export const ColorChannels = {
+  args: defaultArgs,
+  render: ColorChannelsTemplate,
+};
+
+export const Disabled = {
+  args: defaultArgs,
+  render: DisabledTemplate,
+};
+
+export const WithColorPreview = {
+  args: defaultArgs,
+  render: WithColorPreviewTemplate,
+};
diff --git a/packages/react/src/components/color-area/color-area.tsx b/packages/react/src/components/color-area/color-area.tsx
new file mode 100644
index 0000000..3e5a27c
--- /dev/null
+++ b/packages/react/src/components/color-area/color-area.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import type {ColorAreaVariants} from "@heroui/styles";
+import type {CSSProperties, ComponentPropsWithRef} from "react";
+
+import {colorAreaVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  ColorArea as ColorAreaPrimitive,
+  ColorThumb as ColorThumbPrimitive,
+} from "react-aria-components/ColorArea";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorArea Context
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorAreaContext {
+  slots?: ReturnType<typeof colorAreaVariants>;
+}
+
+const ColorAreaContext = createContext<ColorAreaContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorArea Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorAreaRootProps
+  extends ComponentPropsWithRef<typeof ColorAreaPrimitive>, ColorAreaVariants {}
+
+const ColorAreaRoot = ({children, className, showDots, style, ...props}: ColorAreaRootProps) => {
+  const slots = React.useMemo(() => colorAreaVariants({showDots}), [showDots]);
+
+  return (
+    <ColorAreaContext value={{slots}}>
+      <ColorAreaPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots.base())}
+        data-slot="color-area"
+        style={(renderProps) => {
+          const userStyle = typeof style === "function" ? style(renderProps) : style;
+
+          return {
+            "--color-area-background": renderProps.defaultStyle.background,
+            ...userStyle,
+          } as CSSProperties;
+        }}
+      >
+        {children}
+      </ColorAreaPrimitive>
+    </ColorAreaContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorArea Thumb
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorAreaThumbProps extends ComponentPropsWithRef<typeof ColorThumbPrimitive> {}
+
+const ColorAreaThumb = ({className, style, ...props}: ColorAreaThumbProps) => {
+  const {slots} = use(ColorAreaContext);
+
+  return (
+    <ColorThumbPrimitive
+      className={composeTwRenderProps(className, slots?.thumb())}
+      data-slot="color-area-thumb"
+      style={(renderProps) => {
+        const userStyle = typeof style === "function" ? style(renderProps) : style;
+
+        return {
+          "--color-area-thumb-color": renderProps.defaultStyle.backgroundColor,
+          ...userStyle,
+        } as CSSProperties;
+      }}
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorAreaRoot, ColorAreaThumb};
+
+export type {ColorAreaRootProps, ColorAreaThumbProps};
diff --git a/packages/react/src/components/color-area/index.ts b/packages/react/src/components/color-area/index.ts
new file mode 100644
index 0000000..a23ba1a
--- /dev/null
+++ b/packages/react/src/components/color-area/index.ts
@@ -0,0 +1,35 @@
+import type {ComponentProps} from "react";
+
+import {ColorAreaRoot, ColorAreaThumb} from "./color-area";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorArea = Object.assign(ColorAreaRoot, {
+  Root: ColorAreaRoot,
+  Thumb: ColorAreaThumb,
+});
+
+export type ColorArea = {
+  Props: ComponentProps<typeof ColorAreaRoot>;
+  RootProps: ComponentProps<typeof ColorAreaRoot>;
+  ThumbProps: ComponentProps<typeof ColorAreaThumb>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorAreaRoot, ColorAreaThumb};
+
+export type {
+  ColorAreaRootProps,
+  ColorAreaRootProps as ColorAreaProps,
+  ColorAreaThumbProps,
+} from "./color-area";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorAreaVariants} from "@heroui/styles";
+
+export type {ColorAreaVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-field/color-field.stories.tsx b/packages/react/src/components/color-field/color-field.stories.tsx
new file mode 100644
index 0000000..0b4d54e
--- /dev/null
+++ b/packages/react/src/components/color-field/color-field.stories.tsx
@@ -0,0 +1,480 @@
+import type {Meta, StoryObj} from "@storybook/react";
+import type {Color} from "react-aria-components/ColorArea";
+
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {ColorSwatch} from "../color-swatch";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+import {parseColor} from "../rac";
+
+import {ColorField} from "./index";
+
+const meta: Meta<typeof ColorField> = {
+  component: ColorField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Colors/ColorField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DEFAULT_COLOR = parseColor("#0485F7");
+
+export const Default: Story = {
+  render: () => {
+    const [color, setColor] = useState<Color | null>(DEFAULT_COLOR);
+
+    return (
+      <ColorField className="w-[280px]" name="color" value={color} onChange={setColor}>
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Prefix>
+            <ColorSwatch color={color ?? undefined} size="xs" />
+          </ColorField.Prefix>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    );
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue={parseColor("#0485F7")} name="primary-color">
+        <Label>Primary variant</Label>
+        <ColorField.Group variant="primary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue={parseColor("#F43F5E")} name="secondary-color">
+        <Label>Secondary variant</Label>
+        <ColorField.Group variant="secondary">
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <ColorField fullWidth defaultValue={parseColor("#10B981")} name="color">
+        <Label>Brand Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField fullWidth defaultValue={parseColor("#8B5CF6")} name="color-with-suffix">
+        <Label>Theme Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColorField className="w-[280px]" defaultValue={parseColor("#3B82F6")} name="color">
+        <Label>Primary Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Enter your brand's primary color</Description>
+      </ColorField>
+      <ColorField className="w-[280px]" defaultValue={parseColor("#F59E0B")} name="accent-color">
+        <Label>Accent Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>Used for highlights and CTAs</Description>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColorField isRequired className="w-[280px]" name="color">
+        <Label>Brand Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+      </ColorField>
+      <ColorField isRequired className="w-[280px]" name="theme-color">
+        <Label>Theme Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>Required field</Description>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColorField isInvalid isRequired className="w-[280px]" name="color">
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <FieldError>Please enter a valid hex color</FieldError>
+      </ColorField>
+      <ColorField isInvalid className="w-[280px]" name="invalid-color">
+        <Label>Background Color</Label>
+        <ColorField.Group>
+          <ColorField.Input defaultValue="not-a-color" />
+        </ColorField.Group>
+        <FieldError>Invalid color format. Use hex (e.g., #FF5733)</FieldError>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ColorField
+        isDisabled
+        className="w-[280px]"
+        defaultValue={parseColor("#0485F7")}
+        name="color"
+      >
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input />
+        </ColorField.Group>
+        <Description>This color field is disabled</Description>
+      </ColorField>
+      <ColorField isDisabled className="w-[280px]" name="color-empty">
+        <Label>Color</Label>
+        <ColorField.Group>
+          <ColorField.Input placeholder="#000000" />
+        </ColorField.Group>
+        <Description>This color field is disabled</Description>
+      </ColorField>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<Color | null>(parseColor("#0485F7"));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}>
+          <Label>Color</Label>
+          <ColorField.Group>
+            <ColorField.Prefix>
+              <ColorSwatch color={value ?? undefined} size="xs" />
+            </ColorField.Prefix>
+            <ColorField.Input />
+          </ColorField.Group>
+          <Description>Current value: {value ? value.toString("hex") : "(empty)"}</Description>
+        </ColorField>
+        <div className="flex gap-2">
+          <Button variant="tertiary" onPress={() => setValue(parseColor("#EF4444"))}>
+            Set Red
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue(parseColor("#10B981"))}>
+            Set Green
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue(null)}>
+            Clear
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const ChannelEditing: Story = {
+  render: () => {
+    const [color, setColor] = useState<Color | null>(parseColor("#7F007F"));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <p className="text-sm text-muted">Edit individual HSL channels:</p>
+        <div className="flex gap-4">
+          <ColorField
+            channel="hue"
+            className="w-[100px]"
+            colorSpace="hsl"
+            name="hue"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Hue</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+          <ColorField
+            channel="saturation"
+            className="w-[100px]"
+            colorSpace="hsl"
+            name="saturation"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Saturation</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+              <ColorField.Suffix>
+                <span className="text-sm text-muted">%</span>
+              </ColorField.Suffix>
+            </ColorField.Group>
+          </ColorField>
+          <ColorField
+            channel="lightness"
+            className="w-[100px]"
+            colorSpace="hsl"
+            name="lightness"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Lightness</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+              <ColorField.Suffix>
+                <span className="text-sm text-muted">%</span>
+              </ColorField.Suffix>
+            </ColorField.Group>
+          </ColorField>
+        </div>
+        <div className="flex items-center gap-2">
+          <ColorSwatch className="size-8" color={color ?? undefined} size="xs" />
+          <span className="text-sm">Current: {color ? color.toString("hex") : "(empty)"}</span>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const RGBChannels: Story = {
+  render: () => {
+    const [color, setColor] = useState<Color | null>(parseColor("#3B82F6"));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <p className="text-sm text-muted">Edit individual RGB channels:</p>
+        <div className="flex gap-4">
+          <ColorField
+            channel="red"
+            className="w-[80px]"
+            colorSpace="rgb"
+            name="red"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Red</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+          <ColorField
+            channel="green"
+            className="w-[80px]"
+            colorSpace="rgb"
+            name="green"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Green</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+          <ColorField
+            channel="blue"
+            className="w-[80px]"
+            colorSpace="rgb"
+            name="blue"
+            value={color}
+            onChange={setColor}
+          >
+            <Label>Blue</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+            </ColorField.Group>
+          </ColorField>
+        </div>
+        <div className="flex items-center gap-2">
+          <ColorSwatch className="size-8" color={color ?? undefined} size="xs" />
+          <span className="text-sm">Current: {color?.toString("hex")}</span>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<Color | null>(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const isInvalid = value === null;
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+
+      if (!value) {
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        // eslint-disable-next-line no-console
+        console.log("Color submitted:", {color: value.toString("hex")});
+        setValue(null);
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <ColorField
+          fullWidth
+          isRequired
+          className="w-full"
+          isInvalid={Boolean(isInvalid && value !== null)}
+          name="brand-color"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Brand Color</Label>
+          <ColorField.Group>
+            <ColorField.Prefix>
+              <ColorSwatch color={value ?? undefined} size="xs" />
+            </ColorField.Prefix>
+            <ColorField.Input placeholder="#000000" />
+          </ColorField.Group>
+          <Description>Choose your brand's primary color</Description>
+        </ColorField>
+        <Button
+          className="w-full"
+          isDisabled={!value}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? "Saving..." : "Save Color"}
+        </Button>
+      </Form>
+    );
+  },
+};
+
+export const WithColorPresets: Story = {
+  render: () => {
+    const [value, setValue] = useState<Color | null>(parseColor("#0485F7"));
+    const presets = ["#EF4444", "#F59E0B", "#10B981", "#3B82F6", "#8B5CF6", "#EC4899"];
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}>
+          <Label>Color</Label>
+          <ColorField.Group>
+            <ColorField.Prefix>
+              <ColorSwatch color={value?.toString("hex") || "#E4E4E7"} size="xs" />
+            </ColorField.Prefix>
+            <ColorField.Input />
+          </ColorField.Group>
+          <Description>Select or enter a color</Description>
+        </ColorField>
+        <div className="flex gap-2">
+          {presets.map((preset) => (
+            <ColorSwatch
+              key={preset}
+              className="cursor-pointer"
+              color={preset}
+              size="lg"
+              onClick={() => setValue(parseColor(preset))}
+            />
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const AllVariations: Story = {
+  render: () => {
+    const [color1, setColor1] = useState<Color | null>(parseColor("#0485F7"));
+    const [color2, setColor2] = useState<Color | null>(parseColor("#10B981"));
+    const [color3, setColor3] = useState<Color | null>(parseColor("#F43F5E"));
+
+    return (
+      <div className="flex flex-col gap-6">
+        <div className="flex flex-col gap-4">
+          <ColorField
+            isRequired
+            className="w-[280px]"
+            name="color1"
+            value={color1}
+            onChange={setColor1}
+          >
+            <Label>With Prefix Icon</Label>
+            <ColorField.Group>
+              <ColorField.Prefix>
+                <ColorSwatch color={color1 ?? undefined} size="xs" />
+              </ColorField.Prefix>
+              <ColorField.Input />
+            </ColorField.Group>
+            <Description>Enter a hex color</Description>
+          </ColorField>
+
+          <ColorField
+            isRequired
+            className="w-[280px]"
+            name="color2"
+            value={color2}
+            onChange={setColor2}
+          >
+            <Label>With Suffix</Label>
+            <ColorField.Group>
+              <ColorField.Input />
+              <ColorField.Suffix>
+                <ColorSwatch color={color2 ?? undefined} size="xs" />
+              </ColorField.Suffix>
+            </ColorField.Group>
+            <Description>Enter a hex color</Description>
+          </ColorField>
+
+          <ColorField
+            isRequired
+            className="w-[280px]"
+            name="color3"
+            value={color3}
+            onChange={setColor3}
+          >
+            <Label>Secondary Variant</Label>
+            <ColorField.Group variant="secondary">
+              <ColorField.Prefix>
+                <ColorSwatch color={color3 ?? undefined} size="xs" />
+              </ColorField.Prefix>
+              <ColorField.Input />
+            </ColorField.Group>
+            <Description>Enter a hex color</Description>
+          </ColorField>
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/color-field/color-field.tsx b/packages/react/src/components/color-field/color-field.tsx
new file mode 100644
index 0000000..464ab65
--- /dev/null
+++ b/packages/react/src/components/color-field/color-field.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {ColorFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {Color} from "react-aria-components/ColorArea";
+
+import {colorFieldVariants} from "@heroui/styles";
+import React from "react";
+import {ColorField as ColorFieldPrimitive} from "react-aria-components/ColorField";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorFieldRootProps
+  extends ComponentPropsWithRef<typeof ColorFieldPrimitive>, ColorFieldVariants {}
+
+function ColorFieldRoot({children, className, fullWidth, ...props}: ColorFieldRootProps) {
+  const styles = React.useMemo(() => colorFieldVariants({fullWidth}), [fullWidth]);
+
+  return (
+    <ColorFieldPrimitive
+      data-required={dataAttr(props.isRequired)}
+      data-slot="color-field"
+      {...props}
+      className={composeTwRenderProps(className, styles)}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ColorFieldPrimitive>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorFieldRoot};
+
+export type {ColorFieldRootProps, Color as ColorValue};
diff --git a/packages/react/src/components/color-field/index.ts b/packages/react/src/components/color-field/index.ts
new file mode 100644
index 0000000..dcd00ef
--- /dev/null
+++ b/packages/react/src/components/color-field/index.ts
@@ -0,0 +1,48 @@
+import type {ComponentProps} from "react";
+
+import {
+  ColorInputGroupInput,
+  ColorInputGroupPrefix,
+  ColorInputGroupRoot,
+  ColorInputGroupSuffix,
+} from "../color-input-group";
+
+import {ColorFieldRoot} from "./color-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorField = Object.assign(ColorFieldRoot, {
+  Root: ColorFieldRoot,
+  Group: ColorInputGroupRoot,
+  Input: ColorInputGroupInput,
+  Prefix: ColorInputGroupPrefix,
+  Suffix: ColorInputGroupSuffix,
+});
+
+export type ColorField = {
+  Props: ComponentProps<typeof ColorFieldRoot>;
+  RootProps: ComponentProps<typeof ColorFieldRoot>;
+  GroupProps: ComponentProps<typeof ColorInputGroupRoot>;
+  InputProps: ComponentProps<typeof ColorInputGroupInput>;
+  PrefixProps: ComponentProps<typeof ColorInputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof ColorInputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorFieldRoot};
+
+export type {
+  ColorFieldRootProps,
+  ColorFieldRootProps as ColorFieldProps,
+  ColorValue,
+} from "./color-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorFieldVariants} from "@heroui/styles";
+
+export type {ColorFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-input-group/color-input-group.tsx b/packages/react/src/components/color-input-group/color-input-group.tsx
new file mode 100644
index 0000000..7c5d5e0
--- /dev/null
+++ b/packages/react/src/components/color-input-group/color-input-group.tsx
@@ -0,0 +1,143 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ColorInputGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {InputProps as InputPrimitiveProps} from "react-aria-components/Input";
+
+import {colorInputGroupVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+import {Input as InputPrimitive} from "react-aria-components/Input";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorInputGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type ColorInputGroupContext = {
+  slots?: ReturnType<typeof colorInputGroupVariants>;
+};
+
+const ColorInputGroupContext = createContext<ColorInputGroupContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorInputGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorInputGroupRootProps
+  extends ComponentPropsWithRef<typeof GroupPrimitive>, ColorInputGroupVariants {}
+
+const ColorInputGroupRoot = ({
+  children,
+  className,
+  fullWidth,
+  variant,
+  ...props
+}: ColorInputGroupRootProps) => {
+  const slots = React.useMemo(
+    () => colorInputGroupVariants({fullWidth, variant}),
+    [fullWidth, variant],
+  );
+
+  return (
+    <ColorInputGroupContext value={{slots}}>
+      <GroupPrimitive
+        className={composeTwRenderProps(className, slots?.base())}
+        data-slot="color-input-group"
+        {...props}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </GroupPrimitive>
+    </ColorInputGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorInputGroup Prefix
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorInputGroupPrefixProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ColorInputGroupPrefix = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ColorInputGroupPrefixProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ColorInputGroupPrefixProps<E>>) => {
+  const {slots} = use(ColorInputGroupContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.prefix, className)}
+      data-slot="color-input-group-prefix"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorInputGroup Input
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorInputGroupInputProps extends InputPrimitiveProps {
+  className?: string;
+}
+
+const ColorInputGroupInput = ({className, ...props}: ColorInputGroupInputProps) => {
+  const {slots} = use(ColorInputGroupContext);
+
+  return (
+    <InputPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="color-input-group-input"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorInputGroup Suffix
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorInputGroupSuffixProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ColorInputGroupSuffix = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ColorInputGroupSuffixProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ColorInputGroupSuffixProps<E>>) => {
+  const {slots} = use(ColorInputGroupContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.suffix, className)}
+      data-slot="color-input-group-suffix"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorInputGroupRoot, ColorInputGroupInput, ColorInputGroupPrefix, ColorInputGroupSuffix};
+
+export type {
+  ColorInputGroupRootProps,
+  ColorInputGroupInputProps,
+  ColorInputGroupPrefixProps,
+  ColorInputGroupSuffixProps,
+};
diff --git a/packages/react/src/components/color-input-group/index.ts b/packages/react/src/components/color-input-group/index.ts
new file mode 100644
index 0000000..6e81c8c
--- /dev/null
+++ b/packages/react/src/components/color-input-group/index.ts
@@ -0,0 +1,46 @@
+import type {ComponentProps} from "react";
+
+import {
+  ColorInputGroupInput,
+  ColorInputGroupPrefix,
+  ColorInputGroupRoot,
+  ColorInputGroupSuffix,
+} from "./color-input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorInputGroup = Object.assign(ColorInputGroupRoot, {
+  Root: ColorInputGroupRoot,
+  Input: ColorInputGroupInput,
+  Prefix: ColorInputGroupPrefix,
+  Suffix: ColorInputGroupSuffix,
+});
+
+export type ColorInputGroup = {
+  Props: ComponentProps<typeof ColorInputGroupRoot>;
+  RootProps: ComponentProps<typeof ColorInputGroupRoot>;
+  InputProps: ComponentProps<typeof ColorInputGroupInput>;
+  PrefixProps: ComponentProps<typeof ColorInputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof ColorInputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorInputGroupInput, ColorInputGroupPrefix, ColorInputGroupRoot, ColorInputGroupSuffix};
+
+export type {
+  ColorInputGroupRootProps,
+  ColorInputGroupRootProps as ColorInputGroupProps,
+  ColorInputGroupInputProps,
+  ColorInputGroupPrefixProps,
+  ColorInputGroupSuffixProps,
+} from "./color-input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorInputGroupVariants} from "@heroui/styles";
+
+export type {ColorInputGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-picker/color-picker.stories.tsx b/packages/react/src/components/color-picker/color-picker.stories.tsx
new file mode 100644
index 0000000..abbb5b9
--- /dev/null
+++ b/packages/react/src/components/color-picker/color-picker.stories.tsx
@@ -0,0 +1,325 @@
+import type {ColorChannel, ColorSpace} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+import {parseColor} from "react-aria-components/ColorArea";
+
+import {Button} from "../button";
+import {ColorArea} from "../color-area";
+import {ColorField} from "../color-field";
+import {ColorSlider} from "../color-slider";
+import {ColorSwatch} from "../color-swatch";
+import {ColorSwatchPicker} from "../color-swatch-picker";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Select} from "../select";
+
+import {ColorPicker} from "./index";
+
+const colorPresets = [
+  "#ef4444", // red-500
+  "#f97316", // orange-500
+  "#eab308", // yellow-500
+  "#22c55e", // green-500
+  "#06b6d4", // cyan-500
+  "#3b82f6", // blue-500
+  "#8b5cf6", // violet-500
+  "#ec4899", // pink-500
+  "#f43f5e", // rose-500
+];
+
+const meta: Meta<typeof ColorPicker> = {
+  component: ColorPicker,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Colors/ColorPicker",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <ColorPicker defaultValue="#0485F7">
+      <ColorPicker.Trigger>
+        <ColorSwatch size="lg" />
+        <Label>Pick a color</Label>
+      </ColorPicker.Trigger>
+      <ColorPicker.Popover>
+        <ColorArea
+          aria-label="Color area"
+          className="max-w-full"
+          colorSpace="hsb"
+          xChannel="saturation"
+          yChannel="brightness"
+        >
+          <ColorArea.Thumb />
+        </ColorArea>
+        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+          <Label>Hue</Label>
+          <ColorSlider.Output className="text-muted" />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </ColorPicker.Popover>
+    </ColorPicker>
+  ),
+};
+
+export const Controlled: Story = {
+  render: function ControlledColorPicker() {
+    const [color, setColor] = React.useState(parseColor("#325578"));
+
+    const shuffleColor = () => {
+      const randomHue = Math.floor(Math.random() * 360);
+      const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
+      const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
+
+      setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
+    };
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ColorPicker value={color} onChange={setColor}>
+          <ColorPicker.Trigger>
+            <ColorSwatch size="lg" />
+            <Label>Pick a color</Label>
+          </ColorPicker.Trigger>
+          <ColorPicker.Popover className="gap-2">
+            <ColorSwatchPicker className="justify-center pt-2" size="xs">
+              {colorPresets.map((preset) => (
+                <ColorSwatchPicker.Item key={preset} color={preset}>
+                  <ColorSwatchPicker.Swatch />
+                </ColorSwatchPicker.Item>
+              ))}
+            </ColorSwatchPicker>
+            <ColorArea
+              aria-label="Color area"
+              className="max-w-full"
+              colorSpace="hsb"
+              xChannel="saturation"
+              yChannel="brightness"
+            >
+              <ColorArea.Thumb />
+            </ColorArea>
+            <div className="flex items-center gap-2 px-1">
+              <ColorSlider
+                aria-label="Hue slider"
+                channel="hue"
+                className="flex-1"
+                colorSpace="hsb"
+              >
+                <ColorSlider.Track>
+                  <ColorSlider.Thumb />
+                </ColorSlider.Track>
+              </ColorSlider>
+              <Button
+                isIconOnly
+                aria-label="Shuffle color"
+                size="sm"
+                variant="tertiary"
+                onPress={shuffleColor}
+              >
+                <Icon className="size-4" icon="gravity-ui:shuffle" />
+              </Button>
+            </div>
+            <ColorField aria-label="Color field">
+              <ColorField.Group variant="secondary">
+                <ColorField.Prefix>
+                  <ColorSwatch size="xs" />
+                </ColorField.Prefix>
+                <ColorField.Input />
+              </ColorField.Group>
+            </ColorField>
+          </ColorPicker.Popover>
+        </ColorPicker>
+        <p className="w-60 text-sm text-muted">
+          Selected: <span className="font-medium">{color.toString("hex")}</span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const WithSwatches: Story = {
+  render: () => {
+    return (
+      <ColorPicker defaultValue="#F43F5E">
+        <ColorPicker.Trigger>
+          <ColorSwatch size="lg" />
+          <Label>Brand Color</Label>
+        </ColorPicker.Trigger>
+        <ColorPicker.Popover>
+          <ColorArea
+            aria-label="Color area"
+            className="max-w-full"
+            colorSpace="hsb"
+            xChannel="saturation"
+            yChannel="brightness"
+          >
+            <ColorArea.Thumb />
+          </ColorArea>
+          <ColorSlider
+            aria-label="Hue slider"
+            channel="hue"
+            className="gap-1 px-1"
+            colorSpace="hsb"
+          >
+            <Label>Hue</Label>
+            <ColorSlider.Output className="text-muted" />
+            <ColorSlider.Track>
+              <ColorSlider.Thumb />
+            </ColorSlider.Track>
+          </ColorSlider>
+          <ColorSwatchPicker className="justify-center px-1" size="xs">
+            {colorPresets.map((preset) => (
+              <ColorSwatchPicker.Item key={preset} color={preset}>
+                <ColorSwatchPicker.Swatch />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </ColorPicker.Popover>
+      </ColorPicker>
+    );
+  },
+};
+
+export const WidthFields: Story = {
+  render: () => {
+    const [colorSpace, setColorSpace] = React.useState<ColorSpace>("hsl");
+
+    const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+      hsl: ["hue", "saturation", "lightness"],
+      hsb: ["hue", "saturation", "brightness"],
+      rgb: ["red", "green", "blue"],
+    };
+
+    return (
+      <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)">
+        <ColorPicker.Trigger>
+          <ColorSwatch size="lg" />
+          <Label>Pick a color</Label>
+        </ColorPicker.Trigger>
+        <ColorPicker.Popover className="max-w-62 gap-2">
+          <ColorArea
+            aria-label="Color area"
+            className="max-w-full"
+            colorSpace="hsb"
+            xChannel="saturation"
+            yChannel="brightness"
+          >
+            <ColorArea.Thumb />
+          </ColorArea>
+          <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
+            <Label>Hue</Label>
+            <ColorSlider.Output className="text-muted" />
+            <ColorSlider.Track>
+              <ColorSlider.Thumb />
+            </ColorSlider.Track>
+          </ColorSlider>
+          <Select
+            aria-label="Color space"
+            value={colorSpace}
+            variant="secondary"
+            onChange={(value) => setColorSpace(value as ColorSpace)}
+          >
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {Object.keys(colorChannelsByColorSpace).map((space) => (
+                  <ListBox.Item key={space} id={space} textValue={space}>
+                    {space}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+          <div className="grid w-full grid-cols-3 items-center gap-2">
+            {colorChannelsByColorSpace[colorSpace].map((channel) => (
+              <ColorField
+                key={channel}
+                aria-label={channel}
+                channel={channel}
+                colorSpace={colorSpace}
+              >
+                <ColorField.Group variant="secondary">
+                  <ColorField.Input />
+                </ColorField.Group>
+              </ColorField>
+            ))}
+          </div>
+        </ColorPicker.Popover>
+      </ColorPicker>
+    );
+  },
+};
+
+export const WithSliders: Story = {
+  render: () => {
+    const [colorSpace, setColorSpace] = React.useState<ColorSpace>("hsl");
+
+    const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
+      hsl: ["hue", "saturation", "lightness", "alpha"],
+      hsb: ["hue", "saturation", "brightness", "alpha"],
+      rgb: ["red", "green", "blue", "alpha"],
+    };
+
+    return (
+      <ColorPicker defaultValue="hsl(219, 58%, 93%)">
+        <ColorPicker.Trigger>
+          <ColorSwatch size="lg" />
+          <Label>Pick a color</Label>
+        </ColorPicker.Trigger>
+        <ColorPicker.Popover className="max-w-62 gap-2 px-2 py-3">
+          <Select
+            aria-label="Color space"
+            value={colorSpace}
+            variant="secondary"
+            onChange={(value) => setColorSpace(value as ColorSpace)}
+          >
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {Object.keys(colorChannelsByColorSpace).map((space) => (
+                  <ListBox.Item key={space} id={space} textValue={space}>
+                    {space}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+          <div className="flex flex-col gap-2">
+            {colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
+              // @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
+              <ColorSlider
+                key={channel}
+                aria-label={channel}
+                channel={channel}
+                className="gap-1 px-1"
+                colorSpace={colorSpace}
+              >
+                <Label>{channel}</Label>
+                <ColorSlider.Output className="text-muted" />
+                <ColorSlider.Track>
+                  <ColorSlider.Thumb />
+                </ColorSlider.Track>
+              </ColorSlider>
+            ))}
+          </div>
+        </ColorPicker.Popover>
+      </ColorPicker>
+    );
+  },
+};
diff --git a/packages/react/src/components/color-picker/color-picker.tsx b/packages/react/src/components/color-picker/color-picker.tsx
new file mode 100644
index 0000000..90a3cc6
--- /dev/null
+++ b/packages/react/src/components/color-picker/color-picker.tsx
@@ -0,0 +1,116 @@
+"use client";
+
+import type {SurfaceVariants} from "../surface";
+import type {ColorPickerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {ColorPickerProps as ColorPickerPrimitiveProps} from "react-aria-components/ColorPicker";
+
+import {colorPickerVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {ColorPicker as ColorPickerPrimitive} from "react-aria-components/ColorPicker";
+import {
+  DialogTrigger as DialogTriggerPrimitive,
+  Popover as PopoverPrimitive,
+} from "react-aria-components/Popover";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorPicker Context
+ * -----------------------------------------------------------------------------------------------*/
+type ColorPickerContext = {
+  slots?: ReturnType<typeof colorPickerVariants>;
+};
+
+const ColorPickerContext = createContext<ColorPickerContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorPicker Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorPickerRootProps
+  extends Omit<ColorPickerPrimitiveProps, "children">, ColorPickerVariants {
+  /** Additional class name for the wrapper element */
+  className?: string;
+  /** Content of the color picker (Trigger, Popover, etc.) */
+  children: React.ReactNode;
+}
+
+const ColorPickerRoot = ({children, className, ...props}: ColorPickerRootProps) => {
+  const slots = React.useMemo(() => colorPickerVariants(), []);
+
+  return (
+    <ColorPickerContext value={{slots}}>
+      <ColorPickerPrimitive {...props}>
+        <DialogTriggerPrimitive>
+          <div className={composeSlotClassName(slots?.base, className)} data-slot="color-picker">
+            {children}
+          </div>
+        </DialogTriggerPrimitive>
+      </ColorPickerPrimitive>
+    </ColorPickerContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorPicker Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorPickerTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const ColorPickerTrigger = ({children, className, ...props}: ColorPickerTriggerProps) => {
+  const {slots} = use(ColorPickerContext);
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="color-picker-trigger"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorPicker Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorPickerPopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const ColorPickerPopover = ({
+  children,
+  className,
+  placement = "bottom left",
+  ...props
+}: ColorPickerPopoverProps) => {
+  const {slots} = use(ColorPickerContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="color-picker-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorPickerRoot, ColorPickerTrigger, ColorPickerPopover};
+
+export type {ColorPickerRootProps, ColorPickerTriggerProps, ColorPickerPopoverProps};
diff --git a/packages/react/src/components/color-picker/index.ts b/packages/react/src/components/color-picker/index.ts
new file mode 100644
index 0000000..f3c34be
--- /dev/null
+++ b/packages/react/src/components/color-picker/index.ts
@@ -0,0 +1,38 @@
+import type {ComponentProps} from "react";
+
+import {ColorPickerPopover, ColorPickerRoot, ColorPickerTrigger} from "./color-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorPicker = Object.assign(ColorPickerRoot, {
+  Root: ColorPickerRoot,
+  Trigger: ColorPickerTrigger,
+  Popover: ColorPickerPopover,
+});
+
+export type ColorPicker = {
+  Props: ComponentProps<typeof ColorPickerRoot>;
+  RootProps: ComponentProps<typeof ColorPickerRoot>;
+  TriggerProps: ComponentProps<typeof ColorPickerTrigger>;
+  PopoverProps: ComponentProps<typeof ColorPickerPopover>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorPickerPopover, ColorPickerRoot, ColorPickerTrigger};
+
+export type {
+  ColorPickerRootProps,
+  ColorPickerRootProps as ColorPickerProps,
+  ColorPickerTriggerProps,
+  ColorPickerPopoverProps,
+} from "./color-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorPickerVariants} from "@heroui/styles";
+
+export type {ColorPickerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-slider/color-slider.stories.tsx b/packages/react/src/components/color-slider/color-slider.stories.tsx
new file mode 100644
index 0000000..9924e34
--- /dev/null
+++ b/packages/react/src/components/color-slider/color-slider.stories.tsx
@@ -0,0 +1,266 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React, {useState} from "react";
+
+import {ColorSwatch} from "../color-swatch";
+import {Label} from "../label";
+import {parseColor} from "../rac";
+
+import {ColorSlider} from "./index";
+
+const meta: Meta<typeof ColorSlider> = {
+  argTypes: {
+    isDisabled: {
+      control: {type: "boolean"},
+    },
+    colorSpace: {
+      control: {type: "select"},
+      options: ["hsl", "hsb", "rgb"],
+    },
+    channel: {
+      control: {type: "select"},
+      options: ["hue", "saturation", "brightness", "lightness", "alpha", "red", "green", "blue"],
+    },
+    orientation: {
+      control: {type: "select"},
+      options: ["horizontal", "vertical"],
+    },
+  },
+  component: ColorSlider,
+  decorators: [
+    (Story) => (
+      <div className="w-64 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Colors/ColorSlider",
+};
+
+export default meta;
+type Story = StoryObj<typeof ColorSlider>;
+
+export const Default: Story = {
+  args: {
+    channel: "hue",
+    defaultValue: "hsl(0, 100%, 50%)",
+    isDisabled: false,
+    orientation: "horizontal",
+    colorSpace: "hsl",
+  },
+  render: (args) => {
+    const isVertical = args.orientation === "vertical";
+
+    return (
+      <div className={isVertical ? "h-64" : undefined}>
+        <ColorSlider {...args}>
+          <Label>Hue</Label>
+          <ColorSlider.Output />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </div>
+    );
+  },
+};
+
+export const SaturationChannel: Story = {
+  args: {
+    channel: "saturation",
+    defaultValue: "hsl(0, 100%, 50%)",
+    colorSpace: "hsl",
+  },
+  render: (args) => {
+    return (
+      <ColorSlider {...args}>
+        <Label>Saturation</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    );
+  },
+};
+
+export const LightnessChannel: Story = {
+  args: {
+    channel: "lightness",
+    defaultValue: "hsl(0, 100%, 50%)",
+    colorSpace: "hsl",
+  },
+  render: (args) => {
+    return (
+      <ColorSlider {...args}>
+        <Label>Lightness</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    );
+  },
+};
+
+export const AlphaChannel: Story = {
+  args: {
+    channel: "alpha",
+    defaultValue: "hsla(0, 100%, 50%, 0.5)",
+    colorSpace: "hsl",
+  },
+  render: (args) => {
+    return (
+      <ColorSlider {...args}>
+        <Label>Alpha</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    );
+  },
+};
+
+export const RGBChannels: Story = {
+  render: (_args) => {
+    const [color, setColor] = useState(parseColor("rgb(255, 0, 0)"));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ColorSlider channel="red" colorSpace="rgb" value={color} onChange={setColor}>
+          <Label>Red</Label>
+          <ColorSlider.Output />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSlider channel="green" colorSpace="rgb" value={color} onChange={setColor}>
+          <Label>Green</Label>
+          <ColorSlider.Output />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSlider channel="blue" colorSpace="rgb" value={color} onChange={setColor}>
+          <Label>Blue</Label>
+          <ColorSlider.Output />
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </div>
+    );
+  },
+};
+
+export const Vertical: Story = {
+  decorators: [
+    (Story) => (
+      <div className="flex h-64 gap-8 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  render: (_args) => {
+    return (
+      <>
+        <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" orientation="vertical">
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSlider channel="saturation" defaultValue="hsl(0, 100%, 50%)" orientation="vertical">
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+        <ColorSlider channel="lightness" defaultValue="hsl(0, 100%, 50%)" orientation="vertical">
+          <ColorSlider.Track>
+            <ColorSlider.Thumb />
+          </ColorSlider.Track>
+        </ColorSlider>
+      </>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    isDisabled: true,
+    channel: "hue",
+    defaultValue: "hsl(200, 100%, 50%)",
+  },
+  render: (args) => {
+    return (
+      <ColorSlider {...args}>
+        <Label>Hue</Label>
+        <ColorSlider.Output />
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: function ControlledColorSlider(_args) {
+    const [color, setColor] = React.useState(parseColor("hsl(0, 100%, 50%)"));
+
+    return (
+      <div className="flex w-full flex-col gap-4">
+        <div className="flex w-[200px] flex-col gap-4">
+          <ColorSlider channel="hue" value={color} onChange={setColor}>
+            <Label>Hue</Label>
+            <ColorSlider.Output />
+            <ColorSlider.Track>
+              <ColorSlider.Thumb />
+            </ColorSlider.Track>
+          </ColorSlider>
+          <ColorSlider channel="saturation" value={color} onChange={setColor}>
+            <Label>Saturation</Label>
+            <ColorSlider.Output />
+            <ColorSlider.Track>
+              <ColorSlider.Thumb />
+            </ColorSlider.Track>
+          </ColorSlider>
+          <ColorSlider channel="lightness" value={color} onChange={setColor}>
+            <Label>Lightness</Label>
+            <ColorSlider.Output />
+            <ColorSlider.Track>
+              <ColorSlider.Thumb />
+            </ColorSlider.Track>
+          </ColorSlider>
+        </div>
+        <div className="mt-3 flex w-[350px] items-center gap-3">
+          <ColorSwatch color={color} size="lg" />
+          <p className="text-sm text-muted">
+            Current color: <span className="font-mono">{color.toString("hsl")}</span>
+          </p>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithoutLabel: Story = {
+  args: {
+    channel: "hue",
+    defaultValue: "hsl(200, 100%, 50%)",
+    "aria-label": "Hue",
+  },
+  render: (args) => {
+    return (
+      <ColorSlider {...args}>
+        <ColorSlider.Track>
+          <ColorSlider.Thumb />
+        </ColorSlider.Track>
+      </ColorSlider>
+    );
+  },
+};
diff --git a/packages/react/src/components/color-slider/color-slider.tsx b/packages/react/src/components/color-slider/color-slider.tsx
new file mode 100644
index 0000000..41d5489
--- /dev/null
+++ b/packages/react/src/components/color-slider/color-slider.tsx
@@ -0,0 +1,266 @@
+"use client";
+
+import type {ColorSliderVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {ColorSliderRenderProps, ColorSpace} from "react-aria-components/ColorSlider";
+
+import {colorSliderVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  ColorSlider as ColorSliderPrimitive,
+  ColorThumb as ColorThumbPrimitive,
+  SliderOutput as SliderOutputPrimitive,
+  SliderTrack as SliderTrackPrimitive,
+} from "react-aria-components/ColorSlider";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Channel Types
+ * -----------------------------------------------------------------------------------------------*/
+
+/** Channels available in HSL color space */
+type HSLChannel = "hue" | "saturation" | "lightness" | "alpha";
+
+/** Channels available in HSB color space */
+type HSBChannel = "hue" | "saturation" | "brightness" | "alpha";
+
+/** Channels available in RGB color space */
+type RGBChannel = "red" | "green" | "blue" | "alpha";
+
+/** Channels shared between HSL and HSB (but NOT RGB) */
+type HSLHSBSharedChannel = "hue" | "saturation";
+
+/** Alpha channel works across ALL color spaces */
+type AlphaChannel = "alpha";
+
+/**
+ * Discriminated union type for valid channel/colorSpace combinations.
+ * This ensures TypeScript will error on invalid combinations like
+ * `channel="red"` with `colorSpace="hsl"` or `channel="saturation"` with `colorSpace="rgb"`.
+ */
+type ColorSliderChannelProps =
+  | {channel: HSLChannel; colorSpace?: "hsl"}
+  | {channel: HSBChannel; colorSpace?: "hsb"}
+  | {channel: RGBChannel; colorSpace?: "rgb"}
+  | {channel: HSLHSBSharedChannel; colorSpace?: "hsl" | "hsb"}
+  | {channel: AlphaChannel; colorSpace?: ColorSpace};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Validation Utilities
+ * -----------------------------------------------------------------------------------------------*/
+
+/** Maps channels to their required color space (for channels that are color-space specific) */
+const CHANNEL_TO_REQUIRED_COLORSPACE: Partial<Record<string, ColorSpace>> = {
+  red: "rgb",
+  green: "rgb",
+  blue: "rgb",
+  lightness: "hsl",
+  brightness: "hsb",
+};
+
+/** Channels that only work with HSL or HSB (not RGB) */
+const HSL_HSB_ONLY_CHANNELS = new Set(["hue", "saturation"]);
+
+/**
+ * Validates and returns a valid colorSpace for the given channel.
+ * If an invalid combination is detected, logs a warning and returns the correct colorSpace.
+ */
+function getValidColorSpace(channel: string, colorSpace?: ColorSpace): ColorSpace | undefined {
+  // Check if channel requires a specific color space (e.g., "red" requires "rgb")
+  const requiredSpace = CHANNEL_TO_REQUIRED_COLORSPACE[channel];
+
+  if (requiredSpace && colorSpace && colorSpace !== requiredSpace) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[HeroUI ColorSlider] Invalid combination: channel="${channel}" requires colorSpace="${requiredSpace}", ` +
+        `but received colorSpace="${colorSpace}". Auto-correcting to "${requiredSpace}".`,
+    );
+
+    return requiredSpace;
+  }
+
+  // Check if channel is HSL/HSB only (hue, saturation) but RGB was specified
+  if (HSL_HSB_ONLY_CHANNELS.has(channel) && colorSpace === "rgb") {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[HeroUI ColorSlider] Invalid combination: channel="${channel}" is not available in RGB color space. ` +
+        `Use colorSpace="hsl" or colorSpace="hsb" instead. Auto-correcting to "hsl".`,
+    );
+
+    return "hsl";
+  }
+
+  return colorSpace;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Context
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSliderContext {
+  channel?: string;
+  slots?: ReturnType<typeof colorSliderVariants>;
+  state?: ColorSliderRenderProps;
+}
+
+const ColorSliderContext = createContext<ColorSliderContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSliderRootBaseProps
+  extends
+    Omit<ComponentPropsWithRef<typeof ColorSliderPrimitive>, "channel" | "colorSpace">,
+    ColorSliderVariants {}
+
+type ColorSliderRootProps = ColorSliderRootBaseProps & ColorSliderChannelProps;
+
+const ColorSliderRoot = ({
+  channel,
+  children,
+  className,
+  colorSpace,
+  orientation = "horizontal",
+  ...props
+}: ColorSliderRootProps) => {
+  const slots = React.useMemo(() => colorSliderVariants({}), []);
+
+  // Validate and auto-correct invalid channel/colorSpace combinations
+  const validColorSpace = getValidColorSpace(channel, colorSpace);
+
+  return (
+    <ColorSliderPrimitive
+      channel={channel}
+      colorSpace={validColorSpace}
+      data-slot="color-slider"
+      orientation={orientation}
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(values) => (
+        <ColorSliderContext value={{channel, slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </ColorSliderContext>
+      )}
+    </ColorSliderPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Output
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSliderOutputProps extends ComponentPropsWithRef<typeof SliderOutputPrimitive> {}
+
+const ColorSliderOutput = ({children, className, ...props}: ColorSliderOutputProps) => {
+  const {slots} = use(ColorSliderContext);
+
+  return (
+    <SliderOutputPrimitive
+      className={composeTwRenderProps(className, slots?.output())}
+      data-slot="color-slider-output"
+      {...props}
+    >
+      {children
+        ? (values) => <>{typeof children === "function" ? children(values) : children}</>
+        : ({state}) => state.getThumbValueLabel(0)}
+    </SliderOutputPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Track
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSliderTrackProps extends ComponentPropsWithRef<typeof SliderTrackPrimitive> {}
+
+const ColorSliderTrack = ({children, className, style, ...props}: ColorSliderTrackProps) => {
+  const {channel, slots, state} = use(ColorSliderContext);
+  // Calculate start and end colors for the gradient edge caps
+  const displayColor = state?.state?.getDisplayColor();
+
+  const edgeColors = React.useMemo(() => {
+    // Access color through state.state.value (ColorSliderState.value)
+    if (!displayColor || !channel) {
+      return {end: "transparent", start: "transparent"};
+    }
+
+    const range = displayColor.getChannelRange(
+      channel as Parameters<typeof displayColor.getChannelRange>[0],
+    );
+
+    // Get colors at min and max values of the channel
+    const startColor = displayColor.withChannelValue(
+      channel as Parameters<typeof displayColor.withChannelValue>[0],
+      range.minValue,
+    );
+    const endColor = displayColor.withChannelValue(
+      channel as Parameters<typeof displayColor.withChannelValue>[0],
+      range.maxValue,
+    );
+
+    return {
+      end: endColor.toString("css"),
+      start: startColor.toString("css"),
+    };
+  }, [channel, displayColor]);
+
+  return (
+    <SliderTrackPrimitive
+      className={composeTwRenderProps(className, slots?.track())}
+      data-slot="color-slider-track"
+      style={({defaultStyle, ...rest}) => ({
+        // Add transparency checkerboard pattern for alpha channel
+        background: `${defaultStyle.background}, repeating-conic-gradient(#efefef 0% 25%, #f7f7f7 0% 50%) 50% / 16px 16px`,
+        // Pass edge colors as CSS custom properties for ::before and ::after
+        "--track-end-color": edgeColors.end,
+        "--track-start-color": edgeColors.start,
+        ...(typeof style === "function" ? style({defaultStyle, ...rest}) : style),
+      })}
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </SliderTrackPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider Thumb
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSliderThumbProps extends ComponentPropsWithRef<typeof ColorThumbPrimitive> {}
+
+const ColorSliderThumb = ({children, className, style, ...props}: ColorSliderThumbProps) => {
+  const {slots} = use(ColorSliderContext);
+
+  return (
+    <ColorThumbPrimitive
+      className={composeTwRenderProps(className, slots?.thumb())}
+      data-slot="color-slider-thumb"
+      style={({defaultStyle, isDisabled, ...rest}) => ({
+        ...defaultStyle,
+        backgroundColor: isDisabled ? undefined : defaultStyle.backgroundColor,
+        ...(typeof style === "function" ? style({defaultStyle, isDisabled, ...rest}) : style),
+      })}
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ColorThumbPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorSliderRoot, ColorSliderOutput, ColorSliderTrack, ColorSliderThumb};
+
+export type {
+  ColorSliderRootProps,
+  ColorSliderOutputProps,
+  ColorSliderTrackProps,
+  ColorSliderThumbProps,
+  // Channel types for type-safe usage
+  HSLChannel,
+  HSBChannel,
+  RGBChannel,
+  HSLHSBSharedChannel,
+  AlphaChannel,
+  ColorSliderChannelProps,
+};
diff --git a/packages/react/src/components/color-slider/index.ts b/packages/react/src/components/color-slider/index.ts
new file mode 100644
index 0000000..60b378d
--- /dev/null
+++ b/packages/react/src/components/color-slider/index.ts
@@ -0,0 +1,53 @@
+import type {ComponentProps} from "react";
+
+import {
+  ColorSliderOutput,
+  ColorSliderRoot,
+  ColorSliderThumb,
+  ColorSliderTrack,
+} from "./color-slider";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorSlider = Object.assign(ColorSliderRoot, {
+  Root: ColorSliderRoot,
+  Output: ColorSliderOutput,
+  Track: ColorSliderTrack,
+  Thumb: ColorSliderThumb,
+});
+
+export type ColorSlider = {
+  Props: ComponentProps<typeof ColorSliderRoot>;
+  RootProps: ComponentProps<typeof ColorSliderRoot>;
+  OutputProps: ComponentProps<typeof ColorSliderOutput>;
+  TrackProps: ComponentProps<typeof ColorSliderTrack>;
+  ThumbProps: ComponentProps<typeof ColorSliderThumb>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorSliderRoot, ColorSliderOutput, ColorSliderTrack, ColorSliderThumb};
+
+export type {
+  ColorSliderRootProps,
+  ColorSliderRootProps as ColorSliderProps,
+  ColorSliderOutputProps,
+  ColorSliderTrackProps,
+  ColorSliderThumbProps,
+  // Channel types for type-safe usage
+  HSLChannel,
+  HSBChannel,
+  RGBChannel,
+  HSLHSBSharedChannel,
+  AlphaChannel,
+  ColorSliderChannelProps,
+} from "./color-slider";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorSliderVariants} from "@heroui/styles";
+
+export type {ColorSliderVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-swatch-picker/color-swatch-picker.stories.tsx b/packages/react/src/components/color-swatch-picker/color-swatch-picker.stories.tsx
new file mode 100644
index 0000000..ae0413a
--- /dev/null
+++ b/packages/react/src/components/color-swatch-picker/color-swatch-picker.stories.tsx
@@ -0,0 +1,298 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {parseColor} from "../rac";
+
+import {ColorSwatchPicker} from "./index";
+
+export default {
+  argTypes: {
+    layout: {
+      control: "select",
+      options: ["grid", "stack"],
+    },
+    size: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg", "xl"],
+    },
+    variant: {
+      control: "select",
+      options: ["circle", "square"],
+    },
+  },
+  component: ColorSwatchPicker,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Colors/ColorSwatchPicker",
+} as Meta<typeof ColorSwatchPicker>;
+
+type Story = StoryObj<typeof ColorSwatchPicker>;
+
+const defaultColors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+const Template = (props: ColorSwatchPicker["RootProps"]) => (
+  <ColorSwatchPicker {...props}>
+    {defaultColors.map((color) => (
+      <ColorSwatchPicker.Item key={color} color={color}>
+        <ColorSwatchPicker.Swatch />
+        <ColorSwatchPicker.Indicator />
+      </ColorSwatchPicker.Item>
+    ))}
+  </ColorSwatchPicker>
+);
+
+export const Default: Story = {
+  args: {
+    variant: "circle",
+    size: "md",
+    layout: "grid",
+  },
+  render: Template,
+};
+
+const SizesTemplate = () => {
+  const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {sizes.map((size) => (
+        <div key={size} className="flex flex-col gap-2">
+          <span className="text-sm font-medium text-muted capitalize">{size}</span>
+          <ColorSwatchPicker size={size}>
+            {defaultColors.map((color) => (
+              <ColorSwatchPicker.Item key={color} color={color}>
+                <ColorSwatchPicker.Swatch />
+                <ColorSwatchPicker.Indicator />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const Sizes: Story = {
+  render: SizesTemplate,
+};
+
+const VariantsTemplate = () => {
+  const variants = ["circle", "square"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {variants.map((variant) => (
+        <div key={variant} className="flex flex-col gap-2">
+          <span className="text-sm font-medium text-muted capitalize">{variant}</span>
+          <ColorSwatchPicker variant={variant}>
+            {defaultColors.map((color) => (
+              <ColorSwatchPicker.Item key={color} color={color}>
+                <ColorSwatchPicker.Swatch />
+                <ColorSwatchPicker.Indicator />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const Variants: Story = {
+  render: VariantsTemplate,
+};
+
+const LayoutsTemplate = () => {
+  const layouts = ["grid", "stack"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {layouts.map((layout) => (
+        <div key={layout} className="flex flex-col gap-2">
+          <span className="text-sm font-medium text-muted capitalize">{layout}</span>
+          <ColorSwatchPicker layout={layout}>
+            {defaultColors.map((color) => (
+              <ColorSwatchPicker.Item key={color} color={color}>
+                <ColorSwatchPicker.Swatch />
+                <ColorSwatchPicker.Indicator />
+              </ColorSwatchPicker.Item>
+            ))}
+          </ColorSwatchPicker>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const Layouts: Story = {
+  render: LayoutsTemplate,
+};
+
+const AllVariantsTemplate = () => {
+  const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+  const variants = ["circle", "square"] as const;
+
+  return (
+    <div className="flex gap-16">
+      {variants.map((variant) => (
+        <div key={variant} className="flex flex-col gap-6">
+          <span className="text-sm font-semibold text-muted capitalize">{variant}</span>
+          {sizes.map((size) => (
+            <div key={size} className="flex items-center gap-4">
+              <span className="w-8 text-sm text-muted">{size}</span>
+              <ColorSwatchPicker size={size} variant={variant}>
+                {defaultColors.map((color) => (
+                  <ColorSwatchPicker.Item key={color} color={color}>
+                    <ColorSwatchPicker.Swatch />
+                    <ColorSwatchPicker.Indicator />
+                  </ColorSwatchPicker.Item>
+                ))}
+              </ColorSwatchPicker>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const AllVariants: Story = {
+  render: AllVariantsTemplate,
+};
+
+export const Controlled: Story = {
+  render: function ControlledComponent() {
+    const [value, setValue] = React.useState(parseColor("#F43F5E"));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ColorSwatchPicker value={value} onChange={setValue}>
+          {defaultColors.map((color) => (
+            <ColorSwatchPicker.Item key={color} color={color}>
+              <ColorSwatchPicker.Swatch />
+              <ColorSwatchPicker.Indicator />
+            </ColorSwatchPicker.Item>
+          ))}
+        </ColorSwatchPicker>
+        <p className="text-sm text-muted">
+          Selected: <span className="font-medium">{value.toString("hex")}</span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => {
+    const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
+
+    return (
+      <ColorSwatchPicker>
+        {colors.map((color) => (
+          <ColorSwatchPicker.Item key={color} isDisabled color={color}>
+            <ColorSwatchPicker.Swatch />
+            <ColorSwatchPicker.Indicator />
+          </ColorSwatchPicker.Item>
+        ))}
+      </ColorSwatchPicker>
+    );
+  },
+};
+
+export const WithDefaultValue: Story = {
+  render: () => (
+    <ColorSwatchPicker defaultValue="#8B5CF6">
+      {defaultColors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator />
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  ),
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <ColorSwatchPicker>
+      {defaultColors.map((color) => (
+        <ColorSwatchPicker.Item key={color} color={color}>
+          <ColorSwatchPicker.Swatch />
+          <ColorSwatchPicker.Indicator>
+            <Icon icon="gravity-ui:star-fill" />
+          </ColorSwatchPicker.Indicator>
+        </ColorSwatchPicker.Item>
+      ))}
+    </ColorSwatchPicker>
+  ),
+};
+
+const ExtendedPaletteTemplate = () => {
+  const palette = [
+    // Reds
+    "#FEE2E2",
+    "#FECACA",
+    "#FCA5A5",
+    "#F87171",
+    "#EF4444",
+    "#DC2626",
+    // Oranges
+    "#FFEDD5",
+    "#FED7AA",
+    "#FDBA74",
+    "#FB923C",
+    "#F97316",
+    "#EA580C",
+    // Yellows
+    "#FEF3C7",
+    "#FDE68A",
+    "#FCD34D",
+    "#FBBF24",
+    "#F59E0B",
+    "#D97706",
+    // Greens
+    "#DCFCE7",
+    "#BBF7D0",
+    "#86EFAC",
+    "#4ADE80",
+    "#22C55E",
+    "#16A34A",
+    // Blues
+    "#DBEAFE",
+    "#BFDBFE",
+    "#93C5FD",
+    "#60A5FA",
+    "#3B82F6",
+    "#2563EB",
+    // Purples
+    "#EDE9FE",
+    "#DDD6FE",
+    "#C4B5FD",
+    "#A78BFA",
+    "#8B5CF6",
+    "#7C3AED",
+    // White & Black
+    "#FFFFFF",
+    "#000000",
+  ];
+
+  return (
+    <div className="max-w-md">
+      <ColorSwatchPicker className="gap-1" size="sm">
+        {palette.map((color) => (
+          <ColorSwatchPicker.Item key={color} color={color}>
+            <ColorSwatchPicker.Swatch />
+            <ColorSwatchPicker.Indicator />
+          </ColorSwatchPicker.Item>
+        ))}
+      </ColorSwatchPicker>
+    </div>
+  );
+};
+
+export const ExtendedPalette: Story = {
+  render: ExtendedPaletteTemplate,
+};
diff --git a/packages/react/src/components/color-swatch-picker/color-swatch-picker.tsx b/packages/react/src/components/color-swatch-picker/color-swatch-picker.tsx
new file mode 100644
index 0000000..423889d
--- /dev/null
+++ b/packages/react/src/components/color-swatch-picker/color-swatch-picker.tsx
@@ -0,0 +1,203 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ColorSwatchPickerVariants} from "@heroui/styles";
+import type {CSSProperties, ComponentPropsWithRef} from "react";
+import type {ColorSwatchPickerItemRenderProps} from "react-aria-components/ColorSwatchPicker";
+
+import {colorSwatchPickerVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  ColorSwatchPickerItem as ColorSwatchPickerItemPrimitive,
+  ColorSwatchPicker as ColorSwatchPickerPrimitive,
+  ColorSwatch as ColorSwatchPrimitive,
+} from "react-aria-components/ColorSwatchPicker";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPicker Context
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerContext {
+  slots?: ReturnType<typeof colorSwatchPickerVariants>;
+}
+
+const ColorSwatchPickerContext = createContext<ColorSwatchPickerContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPickerItem Context
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerItemContext {
+  state?: ColorSwatchPickerItemRenderProps;
+}
+
+const ColorSwatchPickerItemContext = createContext<ColorSwatchPickerItemContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPicker Root
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerRootProps
+  extends ComponentPropsWithRef<typeof ColorSwatchPickerPrimitive>, ColorSwatchPickerVariants {}
+
+const ColorSwatchPickerRoot = ({
+  children,
+  className,
+  layout,
+  size,
+  variant,
+  ...props
+}: ColorSwatchPickerRootProps) => {
+  const slots = React.useMemo(
+    () => colorSwatchPickerVariants({layout, size, variant}),
+    [layout, size, variant],
+  );
+
+  return (
+    <ColorSwatchPickerContext value={{slots}}>
+      <ColorSwatchPickerPrimitive
+        data-slot="color-swatch-picker"
+        {...props}
+        className={composeTwRenderProps(className, slots.base())}
+      >
+        {children}
+      </ColorSwatchPickerPrimitive>
+    </ColorSwatchPickerContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPicker Item
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerItemProps extends ComponentPropsWithRef<
+  typeof ColorSwatchPickerItemPrimitive
+> {}
+
+const ColorSwatchPickerItem = ({children, className, ...props}: ColorSwatchPickerItemProps) => {
+  const {slots} = use(ColorSwatchPickerContext);
+
+  return (
+    <ColorSwatchPickerItemPrimitive
+      data-slot="color-swatch-picker-item"
+      {...props}
+      className={composeTwRenderProps(className, slots?.item())}
+      style={(renderProps) =>
+        ({
+          "--color-swatch-current": renderProps.color.toString("css"),
+        }) as CSSProperties
+      }
+    >
+      {(renderProps) => (
+        <ColorSwatchPickerItemContext value={{state: renderProps}}>
+          {typeof children === "function" ? children(renderProps) : children}
+        </ColorSwatchPickerItemContext>
+      )}
+    </ColorSwatchPickerItemPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPicker Swatch
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerSwatchProps extends ComponentPropsWithRef<typeof ColorSwatchPrimitive> {}
+
+const ColorSwatchPickerSwatch = ({className, ...props}: ColorSwatchPickerSwatchProps) => {
+  const {slots} = use(ColorSwatchPickerContext);
+
+  return (
+    <ColorSwatchPrimitive
+      className={composeTwRenderProps(className, slots?.swatch())}
+      data-slot="color-swatch-picker-swatch"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * ColorSwatchPicker Indicator
+| * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchPickerIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode | ((props: ColorSwatchPickerItemRenderProps) => React.ReactNode);
+  className?: string;
+}
+
+/**
+ * Calculate relative luminance of a color
+ * Uses the formula: L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ * Returns a value between 0 (black) and 1 (white)
+ */
+function getColorLuminance(color: ColorSwatchPickerItemRenderProps["color"]): number {
+  // Get RGB values (0-255 range)
+  const r = color.getChannelValue("red");
+  const g = color.getChannelValue("green");
+  const b = color.getChannelValue("blue");
+
+  // Normalize to 0-1 and calculate luminance
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+
+const ColorSwatchPickerIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: ColorSwatchPickerIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ColorSwatchPickerIndicatorProps<E>>) => {
+  const {slots} = use(ColorSwatchPickerContext);
+  const {state} = use(ColorSwatchPickerItemContext);
+
+  // Determine if the background color is light (luminance > 0.5)
+  // Use white checkmark on dark backgrounds, black on light backgrounds
+  const isLightColor = state?.color ? getColorLuminance(state.color) > 0.5 : false;
+
+  const content =
+    typeof children === "function" ? (
+      children(state ?? ({} as ColorSwatchPickerItemRenderProps))
+    ) : children ? (
+      children
+    ) : (
+      <svg
+        aria-hidden="true"
+        data-slot="color-swatch-picker-checkmark"
+        fill="none"
+        role="presentation"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={1.5}
+        viewBox="0 0 12 12"
+      >
+        <polyline points="2.5 6 5 8.5 9.5 3" />
+      </svg>
+    );
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-light-color={isLightColor ? "true" : undefined}
+      data-slot="color-swatch-picker-indicator"
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * Exports
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  ColorSwatchPickerRoot,
+  ColorSwatchPickerItem,
+  ColorSwatchPickerSwatch,
+  ColorSwatchPickerIndicator,
+};
+
+export type {
+  ColorSwatchPickerRootProps,
+  ColorSwatchPickerItemProps,
+  ColorSwatchPickerSwatchProps,
+  ColorSwatchPickerIndicatorProps,
+};
diff --git a/packages/react/src/components/color-swatch-picker/index.ts b/packages/react/src/components/color-swatch-picker/index.ts
new file mode 100644
index 0000000..9337ce4
--- /dev/null
+++ b/packages/react/src/components/color-swatch-picker/index.ts
@@ -0,0 +1,51 @@
+import type {ComponentProps} from "react";
+
+import {
+  ColorSwatchPickerIndicator,
+  ColorSwatchPickerItem,
+  ColorSwatchPickerRoot,
+  ColorSwatchPickerSwatch,
+} from "./color-swatch-picker";
+
+/* -------------------------------------------------------------------------------------------------
+| * Compound Component
+| * -----------------------------------------------------------------------------------------------*/
+export const ColorSwatchPicker = Object.assign(ColorSwatchPickerRoot, {
+  Root: ColorSwatchPickerRoot,
+  Item: ColorSwatchPickerItem,
+  Swatch: ColorSwatchPickerSwatch,
+  Indicator: ColorSwatchPickerIndicator,
+});
+
+export type ColorSwatchPicker = {
+  Props: ComponentProps<typeof ColorSwatchPickerRoot>;
+  RootProps: ComponentProps<typeof ColorSwatchPickerRoot>;
+  ItemProps: ComponentProps<typeof ColorSwatchPickerItem>;
+  SwatchProps: ComponentProps<typeof ColorSwatchPickerSwatch>;
+  IndicatorProps: ComponentProps<typeof ColorSwatchPickerIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * Named Component
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  ColorSwatchPickerRoot,
+  ColorSwatchPickerItem,
+  ColorSwatchPickerSwatch,
+  ColorSwatchPickerIndicator,
+};
+
+export type {
+  ColorSwatchPickerRootProps,
+  ColorSwatchPickerRootProps as ColorSwatchPickerProps,
+  ColorSwatchPickerItemProps,
+  ColorSwatchPickerSwatchProps,
+  ColorSwatchPickerIndicatorProps,
+} from "./color-swatch-picker";
+
+/* -------------------------------------------------------------------------------------------------
+| * Variants
+| * -----------------------------------------------------------------------------------------------*/
+export {colorSwatchPickerVariants} from "@heroui/styles";
+
+export type {ColorSwatchPickerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/color-swatch/color-swatch.stories.tsx b/packages/react/src/components/color-swatch/color-swatch.stories.tsx
new file mode 100644
index 0000000..3283b88
--- /dev/null
+++ b/packages/react/src/components/color-swatch/color-swatch.stories.tsx
@@ -0,0 +1,209 @@
+import type {ColorSwatchProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {ColorSwatch} from "./index";
+
+export default {
+  argTypes: {
+    shape: {
+      control: "select",
+      options: ["circle", "square"],
+    },
+    size: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg", "xl"],
+    },
+    color: {
+      control: "color",
+    },
+  },
+  component: ColorSwatch,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Colors/ColorSwatch",
+} as Meta<typeof ColorSwatch>;
+
+const defaultArgs: ColorSwatchProps = {
+  color: "#0485F7",
+};
+
+const Template = (props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch className="h-5 w-5" {...props} />
+  </div>
+);
+
+const ShapesTemplate = (props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch {...props} shape="circle" />
+    <ColorSwatch {...props} shape="square" />
+  </div>
+);
+
+const ColorsTemplate = (_props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch aria-label="Blue" color="#0485F7" />
+    <ColorSwatch aria-label="Red" color="#EF4444" />
+    <ColorSwatch aria-label="Amber" color="#F59E0B" />
+    <ColorSwatch aria-label="Green" color="#10B981" />
+    <ColorSwatch aria-label="Fuchsia" color="#D946EF" />
+  </div>
+);
+
+const SizesTemplate = (props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch {...props} color="#0485F7" size="xs" />
+    <ColorSwatch {...props} color="#EF4444" size="sm" />
+    <ColorSwatch {...props} color="#F59E0B" size="md" />
+    <ColorSwatch {...props} color="#10B981" size="lg" />
+    <ColorSwatch {...props} color="#D946EF" size="xl" />
+  </div>
+);
+
+const TransparencyTemplate = (_props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch aria-label="100% opacity" color="rgba(4, 133, 247, 1)" />
+    <ColorSwatch aria-label="75% opacity" color="rgba(4, 133, 247, 0.75)" />
+    <ColorSwatch aria-label="50% opacity" color="rgba(4, 133, 247, 0.5)" />
+    <ColorSwatch aria-label="25% opacity" color="rgba(4, 133, 247, 0.25)" />
+    <ColorSwatch aria-label="0% opacity" color="rgba(4, 133, 247, 0)" />
+  </div>
+);
+
+const WithColorNameTemplate = (_props: ColorSwatchProps) => (
+  <div className="flex items-center gap-3">
+    <ColorSwatch aria-label="Primary color" color="#0485F7" colorName="Primary blue" />
+    <ColorSwatch aria-label="Danger color" color="#EF4444" colorName="Danger red" />
+    <ColorSwatch aria-label="Warning color" color="#F59E0B" colorName="Warning amber" />
+    <ColorSwatch aria-label="Success color" color="#10B981" colorName="Success green" />
+    <ColorSwatch aria-label="Accent color" color="#D946EF" colorName="Accent fuchsia" />
+  </div>
+);
+
+const StyleRenderPropsTemplate = (_props: ColorSwatchProps) => {
+  const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Custom border using render props */}
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold text-muted">Custom Border</h3>
+        <div className="flex items-center gap-3">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="lg"
+              style={({color: c}) => ({
+                boxShadow: `0 0 0 3px ${c.toString("css")}40`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Custom shadow using render props */}
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold text-muted">Custom Shadow</h3>
+        <div className="flex items-center gap-3">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="lg"
+              style={({color: c}) => ({
+                boxShadow: `0 4px 14px ${c.toString("css")}80`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Outline style using render props */}
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold text-muted">Outline Style</h3>
+        <div className="flex items-center gap-3">
+          {colors.map((color) => (
+            <ColorSwatch
+              key={color}
+              color={color}
+              size="lg"
+              style={({color: c}) => ({
+                boxShadow: `inset 0 0 0 2px ${c.toString("css")}, inset 0 0 0 4px white`,
+              })}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+const AllVariantsTemplate = (_props: ColorSwatchProps) => {
+  const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+  const shapes = ["circle", "square"] as const;
+  const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
+
+  return (
+    <div className="flex flex-col gap-6">
+      {shapes.map((shape) => (
+        <div key={shape} className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted capitalize">{shape}</h3>
+          <div className="flex flex-col gap-3">
+            {sizes.map((size) => (
+              <div key={size} className="flex items-center gap-3">
+                <div className="w-12 text-sm text-muted">{size}</div>
+                {colors.map((color) => (
+                  <ColorSwatch key={color} color={color} shape={shape} size={size} />
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Shapes = {
+  args: defaultArgs,
+  render: ShapesTemplate,
+};
+
+export const Colors = {
+  args: defaultArgs,
+  render: ColorsTemplate,
+};
+
+export const Sizes = {
+  args: defaultArgs,
+  render: SizesTemplate,
+};
+
+export const Transparency = {
+  args: defaultArgs,
+  render: TransparencyTemplate,
+};
+
+export const WithColorName = {
+  args: defaultArgs,
+  render: WithColorNameTemplate,
+};
+
+export const StyleRenderProps = {
+  args: defaultArgs,
+  render: StyleRenderPropsTemplate,
+};
+
+export const AllVariants = {
+  args: defaultArgs,
+  render: AllVariantsTemplate,
+};
diff --git a/packages/react/src/components/color-swatch/color-swatch.tsx b/packages/react/src/components/color-swatch/color-swatch.tsx
new file mode 100644
index 0000000..7a24c75
--- /dev/null
+++ b/packages/react/src/components/color-swatch/color-swatch.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {ColorSwatchVariants} from "@heroui/styles";
+import type {CSSProperties, ComponentPropsWithRef} from "react";
+
+import {colorSwatchVariants} from "@heroui/styles";
+import {ColorSwatch as ColorSwatchPrimitive} from "react-aria-components/ColorSwatch";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSwatch Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ColorSwatchRootProps
+  extends ComponentPropsWithRef<typeof ColorSwatchPrimitive>, ColorSwatchVariants {}
+
+const ColorSwatchRoot = ({className, shape, size, style, ...props}: ColorSwatchRootProps) => {
+  return (
+    <ColorSwatchPrimitive
+      {...props}
+      className={composeTwRenderProps(className, colorSwatchVariants({shape, size}))}
+      data-slot="color-swatch"
+      style={(renderProps) => {
+        const userStyle = typeof style === "function" ? style(renderProps) : style;
+
+        return {
+          "--color-swatch-current": renderProps.color.toString("css"),
+          ...userStyle,
+        } as CSSProperties;
+      }}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorSwatchRoot};
+
+export type {ColorSwatchRootProps};
diff --git a/packages/react/src/components/color-swatch/index.ts b/packages/react/src/components/color-swatch/index.ts
new file mode 100644
index 0000000..d727b93
--- /dev/null
+++ b/packages/react/src/components/color-swatch/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {ColorSwatchRoot} from "./color-swatch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ColorSwatch = Object.assign(ColorSwatchRoot, {
+  Root: ColorSwatchRoot,
+});
+
+export type ColorSwatch = {
+  Props: ComponentProps<typeof ColorSwatchRoot>;
+  RootProps: ComponentProps<typeof ColorSwatchRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ColorSwatchRoot};
+
+export type {ColorSwatchRootProps, ColorSwatchRootProps as ColorSwatchProps} from "./color-swatch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {colorSwatchVariants} from "@heroui/styles";
+
+export type {ColorSwatchVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/combo-box/combo-box.stories.tsx b/packages/react/src/components/combo-box/combo-box.stories.tsx
new file mode 100644
index 0000000..c03b3f6
--- /dev/null
+++ b/packages/react/src/components/combo-box/combo-box.stories.tsx
@@ -0,0 +1,907 @@
+import type {Key} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {useAsyncList} from "@react-stately/data";
+import React from "react";
+
+import {Avatar, AvatarFallback, AvatarImage} from "../avatar";
+import {Button} from "../button";
+import {Description} from "../description";
+import {EmptyState} from "../empty-state";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Header} from "../header";
+import {Input} from "../input";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Collection, ListBoxLoadMoreItem} from "../rac";
+import {Separator} from "../separator";
+import {Spinner} from "../spinner";
+
+import {ComboBox} from "./index";
+
+const meta: Meta<typeof ComboBox> = {
+  component: ComboBox,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Pickers/ComboBox",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <ComboBox fullWidth>
+        <Label>Favorite Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="Aardvark">
+              Aardvark
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="dog" textValue="Dog">
+              Dog
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+      <ComboBox fullWidth isRequired>
+        <Label>Favorite Animal</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            <ListBox.Item id="aardvark" textValue="Aardvark">
+              Aardvark
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="cat" textValue="Cat">
+              Cat
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </ComboBox.Popover>
+        <FieldError />
+      </ComboBox>
+    </div>
+  ),
+};
+
+export const DefaultSelectedKey: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]" defaultSelectedKey="cat">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>Search and select your favorite animal</Description>
+    </ComboBox>
+  ),
+};
+
+export const WithSections: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]">
+      <Label>Country</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search countries..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="Mexico">
+              Mexico
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="Germany">
+              Germany
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Asia</Header>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="China">
+              China
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="India">
+              India
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="South Korea">
+              South Korea
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const WithDisabledOptions: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]" disabledKeys={["cat", "kangaroo"]}>
+      <Label>Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="Bird">
+            Bird
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="Elephant">
+            Elephant
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="Tiger">
+            Tiger
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const CustomIndicator: Story = {
+  render: () => (
+    <ComboBox className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger className="size-3">
+          <Icon icon="gravity-ui:chevrons-expand-vertical" />
+        </ComboBox.Trigger>
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const Required: Story = {
+  render: () => {
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const data: Record<string, string> = {};
+
+      formData.forEach((value, key) => {
+        data[key] = value.toString();
+      });
+
+      alert("Form submitted successfully!");
+    };
+
+    return (
+      <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+        <ComboBox isRequired className="w-full" name="animal">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <FieldError />
+        </ComboBox>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+export const CustomValue: Story = {
+  render: () => {
+    const users = [
+      {
+        id: "1",
+        name: "Bob",
+        email: "bob@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "B",
+      },
+      {
+        id: "2",
+        name: "Fred",
+        email: "fred@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "F",
+      },
+      {
+        id: "3",
+        name: "Martha",
+        email: "martha@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "M",
+      },
+      {
+        id: "4",
+        name: "John",
+        email: "john@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "J",
+      },
+      {
+        id: "5",
+        name: "Jane",
+        email: "jane@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "J",
+      },
+    ];
+
+    return (
+      <ComboBox className="w-[256px]">
+        <Label>User</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search users..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const animals = [
+      {
+        id: "cat",
+        name: "Cat",
+      },
+      {
+        id: "dog",
+        name: "Dog",
+      },
+      {
+        id: "bird",
+        name: "Bird",
+      },
+      {
+        id: "fish",
+        name: "Fish",
+      },
+      {
+        id: "hamster",
+        name: "Hamster",
+      },
+    ];
+
+    const [selectedKey, setSelectedKey] = React.useState<Key | null>("cat");
+
+    const selectedAnimal = animals.find((a) => a.id === selectedKey);
+
+    return (
+      <div className="space-y-2">
+        <ComboBox
+          className="w-[256px]"
+          selectedKey={selectedKey}
+          onSelectionChange={(key) => setSelectedKey(key)}
+        >
+          <Label>Animal (controlled)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              {animals.map((animal) => (
+                <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+                  {animal.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </ComboBox.Popover>
+        </ComboBox>
+        <p className="text-sm text-muted">Selected: {selectedAnimal?.name || "None"}</p>
+      </div>
+    );
+  },
+};
+
+export const ControlledInputValue: Story = {
+  render: () => {
+    const [inputValue, setInputValue] = React.useState("");
+
+    return (
+      <div className="space-y-2">
+        <ComboBox className="w-[256px]" inputValue={inputValue} onInputChange={setInputValue}>
+          <Label>Search (controlled input)</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Type to search..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+        </ComboBox>
+        <p className="text-sm text-muted">Input value: {inputValue || "(empty)"}</p>
+      </div>
+    );
+  },
+};
+
+interface Character {
+  name: string;
+}
+
+export const AsynchronousLoading: Story = {
+  render: () => {
+    const list = useAsyncList<Character>({
+      async load({cursor, filterText, signal}) {
+        if (cursor) {
+          cursor = cursor.replace(/^http:\/\//i, "https://");
+        }
+
+        const res = await fetch(
+          cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`,
+          {
+            signal,
+          },
+        );
+        const json = await res.json();
+
+        return {
+          items: json.results,
+          cursor: json.next,
+        };
+      },
+    });
+
+    return (
+      <ComboBox
+        allowsEmptyCollection
+        className="w-[256px]"
+        inputValue={list.filterText}
+        onInputChange={list.setFilterText}
+      >
+        <Label>Pick a Character</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Star Wars characters..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox renderEmptyState={() => <EmptyState />}>
+            <Collection items={list.items}>
+              {(item) => (
+                <ListBox.Item id={item.name} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              )}
+            </Collection>
+            <ListBoxLoadMoreItem
+              isLoading={list.loadingState === "loadingMore"}
+              onLoadMore={list.loadMore}
+            >
+              <div className="flex items-center justify-center gap-2 py-2">
+                <Spinner size="sm" />
+                <span className="muted text-sm">Loading more...</span>
+              </div>
+            </ListBoxLoadMoreItem>
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+    );
+  },
+};
+
+export const CustomFiltering: Story = {
+  render: () => {
+    const animals = [
+      {id: "cat", name: "Cat"},
+      {id: "dog", name: "Dog"},
+      {id: "bird", name: "Bird"},
+      {id: "fish", name: "Fish"},
+      {id: "hamster", name: "Hamster"},
+    ];
+
+    return (
+      <ComboBox
+        className="w-[256px]"
+        defaultFilter={(text, inputValue) => {
+          if (!inputValue) return true;
+
+          return text.toLowerCase().includes(inputValue.toLowerCase());
+        }}
+      >
+        <Label>Animal (custom filter)</Label>
+        <ComboBox.InputGroup>
+          <Input placeholder="Search animals..." />
+          <ComboBox.Trigger />
+        </ComboBox.InputGroup>
+        <ComboBox.Popover>
+          <ListBox>
+            {animals.map((animal) => (
+              <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}>
+                {animal.name}
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </ComboBox.Popover>
+      </ComboBox>
+    );
+  },
+};
+
+export const AllowsCustomValue: Story = {
+  render: () => (
+    <ComboBox allowsCustomValue className="w-[256px]">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search or type an animal..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+      <Description>You can type any animal name, even if it's not in the list</Description>
+    </ComboBox>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <ComboBox isDisabled className="w-[256px]" defaultSelectedKey="cat">
+      <Label>Favorite Animal</Label>
+      <ComboBox.InputGroup>
+        <Input placeholder="Search animals..." />
+        <ComboBox.Trigger />
+      </ComboBox.InputGroup>
+      <ComboBox.Popover>
+        <ListBox>
+          <ListBox.Item id="aardvark" textValue="Aardvark">
+            Aardvark
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="panda" textValue="Panda">
+            Panda
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="snake" textValue="Snake">
+            Snake
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </ComboBox.Popover>
+    </ComboBox>
+  ),
+};
+
+export const MenuTrigger: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Focus (default)</p>
+        <ComboBox className="w-[256px]" menuTrigger="focus">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>Popover opens when the input is focused</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Input</p>
+        <ComboBox className="w-[256px]" menuTrigger="input">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>Popover opens when the user edits the input text</Description>
+        </ComboBox>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Manual</p>
+        <ComboBox className="w-[256px]" menuTrigger="manual">
+          <Label>Favorite Animal</Label>
+          <ComboBox.InputGroup>
+            <Input placeholder="Search animals..." />
+            <ComboBox.Trigger />
+          </ComboBox.InputGroup>
+          <ComboBox.Popover>
+            <ListBox>
+              <ListBox.Item id="aardvark" textValue="Aardvark">
+                Aardvark
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="cat" textValue="Cat">
+                Cat
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="dog" textValue="Dog">
+                Dog
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="kangaroo" textValue="Kangaroo">
+                Kangaroo
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="panda" textValue="Panda">
+                Panda
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="snake" textValue="Snake">
+                Snake
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </ComboBox.Popover>
+          <Description>
+            Popover only opens when the trigger button is pressed or arrow keys are used
+          </Description>
+        </ComboBox>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/combo-box/combo-box.tsx b/packages/react/src/components/combo-box/combo-box.tsx
new file mode 100644
index 0000000..58a85d7
--- /dev/null
+++ b/packages/react/src/components/combo-box/combo-box.tsx
@@ -0,0 +1,155 @@
+"use client";
+
+import type {SurfaceVariants} from "../surface";
+import type {ComboBoxVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {ButtonProps} from "react-aria-components/Button";
+
+import {comboBoxVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button} from "react-aria-components/Button";
+import {
+  ComboBox as ComboBoxPrimitive,
+  ComboBoxStateContext,
+  Popover as PopoverPrimitive,
+} from "react-aria-components/ComboBox";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {IconChevronDown} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * ComboBox Context
+ * -----------------------------------------------------------------------------------------------*/
+type ComboBoxContext = {
+  slots?: ReturnType<typeof comboBoxVariants>;
+  variant?: "primary" | "secondary";
+};
+
+const ComboBoxContext = createContext<ComboBoxContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ComboBox Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ComboBoxRootProps<T extends object>
+  extends ComponentPropsWithRef<typeof ComboBoxPrimitive<T>>, ComboBoxVariants {
+  items?: Iterable<T>;
+  /**
+   * The variant of the combo box.
+   * @default "primary"
+   */
+  variant?: "primary" | "secondary";
+}
+
+const ComboBoxRoot = <T extends object = object>({
+  children,
+  className,
+  fullWidth,
+  menuTrigger = "focus",
+  variant,
+  ...props
+}: ComboBoxRootProps<T>) => {
+  const slots = React.useMemo(() => comboBoxVariants({fullWidth}), [fullWidth]);
+
+  return (
+    <ComboBoxContext value={{slots, variant}}>
+      <ComboBoxPrimitive
+        data-slot="combo-box"
+        menuTrigger={menuTrigger}
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </ComboBoxPrimitive>
+    </ComboBoxContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ComboBox InputGroup
+ * -----------------------------------------------------------------------------------------------*/
+interface ComboBoxInputGroupProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+const ComboBoxInputGroup = ({children, className, ...props}: ComboBoxInputGroupProps) => {
+  const {slots} = use(ComboBoxContext);
+  const inputGroupClassName = composeSlotClassName(slots?.inputGroup, className);
+
+  return (
+    <div className={inputGroupClassName} data-slot="combo-box-input-group" {...props}>
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ComboBox Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface ComboBoxTriggerProps extends ButtonProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+const ComboBoxTrigger = ({children, className, ...rest}: ComboBoxTriggerProps) => {
+  const {slots} = use(ComboBoxContext);
+  const state = use(ComboBoxStateContext);
+
+  return (
+    <Button
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-open={dataAttr(state?.isOpen)}
+      data-slot="combo-box-trigger"
+      {...rest}
+    >
+      {children ?? <IconChevronDown data-slot="combo-box-trigger-default-icon" />}
+    </Button>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ComboBox Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface ComboBoxPopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const ComboBoxPopover = ({
+  children,
+  className,
+  placement = "bottom",
+  ...props
+}: ComboBoxPopoverProps) => {
+  const {slots} = use(ComboBoxContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="combo-box-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ComboBoxRoot, ComboBoxInputGroup, ComboBoxTrigger, ComboBoxPopover, ComboBoxContext};
+
+export type {
+  ComboBoxRootProps,
+  ComboBoxInputGroupProps,
+  ComboBoxTriggerProps,
+  ComboBoxPopoverProps,
+};
diff --git a/packages/react/src/components/combo-box/index.ts b/packages/react/src/components/combo-box/index.ts
new file mode 100644
index 0000000..6b63514
--- /dev/null
+++ b/packages/react/src/components/combo-box/index.ts
@@ -0,0 +1,46 @@
+import type {ComponentProps} from "react";
+
+import {ComboBoxInputGroup, ComboBoxPopover, ComboBoxRoot, ComboBoxTrigger} from "./combo-box";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ComboBox = Object.assign(ComboBoxRoot, {
+  Root: ComboBoxRoot,
+  InputGroup: ComboBoxInputGroup,
+  Trigger: ComboBoxTrigger,
+  Popover: ComboBoxPopover,
+});
+
+export type ComboBox<T extends object = object> = {
+  Props: ComponentProps<typeof ComboBoxRoot<T>>;
+  RootProps: ComponentProps<typeof ComboBoxRoot<T>>;
+  InputGroupProps: ComponentProps<typeof ComboBoxInputGroup>;
+  TriggerProps: ComponentProps<typeof ComboBoxTrigger>;
+  PopoverProps: ComponentProps<typeof ComboBoxPopover>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ComboBoxInputGroup, ComboBoxPopover, ComboBoxRoot, ComboBoxTrigger};
+
+export type {
+  ComboBoxRootProps,
+  ComboBoxRootProps as ComboBoxProps,
+  ComboBoxInputGroupProps,
+  ComboBoxTriggerProps,
+  ComboBoxPopoverProps,
+} from "./combo-box";
+
+/* -------------------------------------------------------------------------------------------------
+ * Context
+ * -----------------------------------------------------------------------------------------------*/
+export {ComboBoxContext} from "./combo-box";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {comboBoxVariants} from "@heroui/styles";
+
+export type {ComboBoxVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/date-field/date-field.stories.tsx b/packages/react/src/components/date-field/date-field.stories.tsx
new file mode 100644
index 0000000..2097823
--- /dev/null
+++ b/packages/react/src/components/date-field/date-field.stories.tsx
@@ -0,0 +1,469 @@
+import type {DateValue} from "@internationalized/date";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {getLocalTimeZone, parseDate, parseZonedDateTime, today} from "@internationalized/date";
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Select} from "../select";
+import {Tooltip} from "../tooltip";
+
+import {DateField} from "./index";
+
+const meta: Meta<typeof DateField> = {
+  component: DateField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/DateField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="primary-date">
+        <Label>Primary variant</Label>
+        <DateField.Group variant="primary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField className="w-[256px]" name="secondary-date">
+        <Label>Secondary variant</Label>
+        <DateField.Group variant="secondary">
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <DateField fullWidth name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField fullWidth name="date-icons">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+          </DateField.Prefix>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+          </DateField.Suffix>
+        </DateField.Group>
+      </DateField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <DateField className="w-[256px]" name="date">
+        <Label>Birth date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter your date of birth</Description>
+      </DateField>
+      <DateField className="w-[256px]" name="appointment-date">
+        <Label>Appointment date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Enter a date for your appointment</Description>
+      </DateField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <DateField isRequired className="w-[256px]" name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+      </DateField>
+      <DateField isRequired className="w-[256px]" name="start-date">
+        <Label>Start date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>Required field</Description>
+      </DateField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <DateField isInvalid isRequired className="w-[256px]" name="date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>Please enter a valid date</FieldError>
+      </DateField>
+      <DateField isInvalid className="w-[256px]" name="invalid-date">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <FieldError>Date must be in the future</FieldError>
+      </DateField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <DateField isDisabled className="w-[256px]" name="date" value={today(getLocalTimeZone())}>
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>This date field is disabled</Description>
+      </DateField>
+      <DateField isDisabled className="w-[256px]" name="date-empty">
+        <Label>Date</Label>
+        <DateField.Group>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        </DateField.Group>
+        <Description>This date field is disabled</Description>
+      </DateField>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(null);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DateField className="w-[256px]" name="date" value={value} onChange={setValue}>
+          <Label>Date</Label>
+          <DateField.Group>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+          </DateField.Group>
+          <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+        </DateField>
+        <div className="flex gap-2">
+          <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
+            Set today
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue(null)}>
+            Clear
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(null);
+    const todayDate = today(getLocalTimeZone());
+    const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DateField
+          isRequired
+          className="w-[256px]"
+          isInvalid={isInvalid}
+          minValue={todayDate}
+          name="date"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Date</Label>
+          <DateField.Group>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+          </DateField.Group>
+          {isInvalid ? (
+            <FieldError>Date must be today or in the future</FieldError>
+          ) : (
+            <Description>Enter a date from today onwards</Description>
+          )}
+        </DateField>
+      </div>
+    );
+  },
+};
+
+export const WithPrefixIcon: Story = {
+  render: () => (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      </DateField.Group>
+    </DateField>
+  ),
+};
+
+export const WithSuffixIcon: Story = {
+  render: () => (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+        </DateField.Suffix>
+      </DateField.Group>
+    </DateField>
+  ),
+};
+
+export const WithPrefixAndSuffix: Story = {
+  render: () => (
+    <DateField className="w-[256px]" name="date">
+      <Label>Date</Label>
+      <DateField.Group>
+        <DateField.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+        </DateField.Prefix>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Enter a date</Description>
+    </DateField>
+  ),
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const todayDate = today(getLocalTimeZone());
+    const isInvalid = value !== null && value.compare(todayDate) < 0;
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+
+      if (!value || isInvalid) {
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        // eslint-disable-next-line no-console
+        console.log("Date submitted:", {date: value});
+        setValue(null);
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <DateField
+          isRequired
+          className="w-full"
+          isInvalid={isInvalid}
+          minValue={todayDate}
+          name="date"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Appointment date</Label>
+          <DateField.Group>
+            <DateField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+            </DateField.Prefix>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+          </DateField.Group>
+          {isInvalid ? (
+            <FieldError>Date must be today or in the future</FieldError>
+          ) : (
+            <Description>Enter a date from today onwards</Description>
+          )}
+        </DateField>
+        <Button
+          className="w-full"
+          isDisabled={!value || isInvalid}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? "Submitting..." : "Submit"}
+        </Button>
+      </Form>
+    );
+  },
+};
+
+export const Granularity: Story = {
+  render: () => {
+    const granularityOptions = [
+      {id: "day", label: "Day"},
+      {id: "hour", label: "Hour"},
+      {id: "minute", label: "Minute"},
+      {id: "second", label: "Second"},
+    ] as const;
+
+    const [granularity, setGranularity] = useState<"day" | "hour" | "minute" | "second">("day");
+
+    // Determine appropriate default value based on granularity
+    let defaultValue: DateValue;
+
+    if (granularity === "day") {
+      defaultValue = parseDate("2025-02-03");
+    } else {
+      // hour, minute, second
+      defaultValue = parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]");
+    }
+
+    return (
+      <div className="flex gap-4">
+        <DateField
+          className="w-[256px]"
+          defaultValue={defaultValue}
+          granularity={granularity}
+          name="granularity-date"
+        >
+          <Label>Appointment Date</Label>
+          <DateField.Group>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+          </DateField.Group>
+        </DateField>
+        <div className="flex flex-col gap-1">
+          <div className="flex items-center gap-2">
+            <Label>Granularity</Label>
+            <Tooltip delay={0}>
+              <Tooltip.Trigger aria-label="Granularity information">
+                <Icon className="size-4 text-muted" icon="gravity-ui:circle-question" />
+              </Tooltip.Trigger>
+              <Tooltip.Content placement="bottom start">
+                <p>
+                  Determines the smallest unit displayed in the date picker. By default, this is
+                  "day" for dates, and "minute" for times.
+                </p>
+              </Tooltip.Content>
+            </Tooltip>
+          </div>
+          <Select
+            className="w-[110px]"
+            placeholder="Select granularity"
+            value={granularity}
+            variant="secondary"
+            onChange={(value) => setGranularity(value as typeof granularity)}
+          >
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Indicator />
+            </Select.Trigger>
+            <Select.Popover>
+              <ListBox>
+                {granularityOptions.map((option) => (
+                  <ListBox.Item key={option.id} id={option.id} textValue={option.label}>
+                    {option.label}
+                    <ListBox.ItemIndicator />
+                  </ListBox.Item>
+                ))}
+              </ListBox>
+            </Select.Popover>
+          </Select>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const AllVariations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-4">
+        <DateField isRequired className="w-[256px]" name="date1">
+          <Label>Date</Label>
+          <DateField.Group>
+            <DateField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+            </DateField.Prefix>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+          </DateField.Group>
+          <Description>Enter a date</Description>
+        </DateField>
+
+        <DateField isRequired className="w-[256px]" name="date2">
+          <Label>Date</Label>
+          <DateField.Group>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+            <DateField.Suffix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+            </DateField.Suffix>
+          </DateField.Group>
+          <Description>Enter a date</Description>
+        </DateField>
+
+        <DateField isRequired className="w-[256px]" name="date3">
+          <Label>Date</Label>
+          <DateField.Group>
+            <DateField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:calendar" />
+            </DateField.Prefix>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+            <DateField.Suffix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+            </DateField.Suffix>
+          </DateField.Group>
+          <Description>Enter a date</Description>
+        </DateField>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/date-field/date-field.tsx b/packages/react/src/components/date-field/date-field.tsx
new file mode 100644
index 0000000..1eff883
--- /dev/null
+++ b/packages/react/src/components/date-field/date-field.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import type {DateFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {DateValue} from "react-aria-components/Calendar";
+
+import {dateFieldVariants} from "@heroui/styles";
+import React from "react";
+import {DateField as DateFieldPrimitive} from "react-aria-components/DateField";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DateFieldRootProps<T extends DateValue>
+  extends ComponentPropsWithRef<typeof DateFieldPrimitive<T>>, DateFieldVariants {}
+
+function DateFieldRoot<T extends DateValue>({
+  children,
+  className,
+  fullWidth,
+  ...props
+}: DateFieldRootProps<T>) {
+  const styles = React.useMemo(() => dateFieldVariants({fullWidth}), [fullWidth]);
+
+  return (
+    <DateFieldPrimitive
+      data-required={dataAttr(props.isRequired)}
+      data-slot="date-field"
+      {...props}
+      className={composeTwRenderProps(className, styles)}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </DateFieldPrimitive>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {DateFieldRoot};
+
+export type {DateFieldRootProps};
diff --git a/packages/react/src/components/date-field/index.ts b/packages/react/src/components/date-field/index.ts
new file mode 100644
index 0000000..163ee87
--- /dev/null
+++ b/packages/react/src/components/date-field/index.ts
@@ -0,0 +1,50 @@
+import type {ComponentProps} from "react";
+
+import {
+  DateInputGroupInput,
+  DateInputGroupInputContainer,
+  DateInputGroupPrefix,
+  DateInputGroupRoot,
+  DateInputGroupSegment,
+  DateInputGroupSuffix,
+} from "../date-input-group";
+
+import {DateFieldRoot} from "./date-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const DateField = Object.assign(DateFieldRoot, {
+  Root: DateFieldRoot,
+  Group: DateInputGroupRoot,
+  Input: DateInputGroupInput,
+  InputContainer: DateInputGroupInputContainer,
+  Segment: DateInputGroupSegment,
+  Prefix: DateInputGroupPrefix,
+  Suffix: DateInputGroupSuffix,
+});
+
+export type DateField = {
+  Props: ComponentProps<typeof DateFieldRoot>;
+  RootProps: ComponentProps<typeof DateFieldRoot>;
+  GroupProps: ComponentProps<typeof DateInputGroupRoot>;
+  InputProps: ComponentProps<typeof DateInputGroupInput>;
+  InputContainerProps: ComponentProps<typeof DateInputGroupInputContainer>;
+  SegmentProps: ComponentProps<typeof DateInputGroupSegment>;
+  PrefixProps: ComponentProps<typeof DateInputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof DateInputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {DateFieldRoot};
+
+export type {DateFieldRootProps, DateFieldRootProps as DateFieldProps} from "./date-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {dateFieldVariants} from "@heroui/styles";
+
+export type {DateFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/date-input-group/date-input-group.tsx b/packages/react/src/components/date-input-group/date-input-group.tsx
new file mode 100644
index 0000000..8af865f
--- /dev/null
+++ b/packages/react/src/components/date-input-group/date-input-group.tsx
@@ -0,0 +1,220 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {DateInputGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {
+  DateInputProps as DateInputPrimitiveProps,
+  DateSegmentProps as DateSegmentPrimitiveProps,
+  DateInputProps as TimeInputPrimitiveProps,
+  DateSegmentProps as TimeSegmentPrimitiveProps,
+} from "react-aria-components/DateField";
+
+import {dateInputGroupVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  DateInput as DateInputPrimitive,
+  DateSegment as DateSegmentPrimitive,
+} from "react-aria-components/DateField";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type DateInputGroupContext = {
+  slots?: ReturnType<typeof dateInputGroupVariants>;
+};
+
+const DateInputGroupContext = createContext<DateInputGroupContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DateInputGroupRootProps
+  extends ComponentPropsWithRef<typeof GroupPrimitive>, DateInputGroupVariants {}
+
+const DateInputGroupRoot = ({
+  children,
+  className,
+  fullWidth,
+  variant,
+  ...props
+}: DateInputGroupRootProps) => {
+  const slots = React.useMemo(
+    () => dateInputGroupVariants({fullWidth, variant}),
+    [fullWidth, variant],
+  );
+
+  return (
+    <DateInputGroupContext value={{slots}}>
+      <GroupPrimitive
+        className={composeTwRenderProps(className, slots?.base())}
+        data-slot="date-input-group"
+        {...props}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </GroupPrimitive>
+    </DateInputGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Prefix
+ * -----------------------------------------------------------------------------------------------*/
+interface DateInputGroupPrefixProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DateInputGroupPrefix = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DateInputGroupPrefixProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DateInputGroupPrefixProps<E>>) => {
+  const {slots} = use(DateInputGroupContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.prefix, className)}
+      data-slot="date-input-group-prefix"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Input
+ * -----------------------------------------------------------------------------------------------*/
+interface DateInputGroupInputProps
+  extends
+    DateInputPrimitiveProps,
+    Partial<Omit<TimeInputPrimitiveProps, keyof DateInputPrimitiveProps>> {}
+
+const DateInputGroupInput = ({className, ...props}: DateInputGroupInputProps) => {
+  const {slots} = use(DateInputGroupContext);
+
+  // TimeInput and DateInput have compatible interfaces
+  // React Aria Components will handle the correct primitive based on parent context (TimeField vs DateField)
+  // We use DateInputPrimitive as the default, but it will work with TimeField context
+  return (
+    <DateInputPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="date-input-group-input"
+      {...(props as DateInputPrimitiveProps)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Segment
+ * -----------------------------------------------------------------------------------------------*/
+
+interface DateInputGroupSegmentProps
+  extends
+    DateSegmentPrimitiveProps,
+    Partial<Omit<TimeSegmentPrimitiveProps, keyof DateSegmentPrimitiveProps>> {
+  className?: string;
+}
+
+const DateInputGroupSegment = ({className, segment, ...props}: DateInputGroupSegmentProps) => {
+  const {slots} = use(DateInputGroupContext);
+
+  // TimeSegment and DateSegment have compatible interfaces
+  // React Aria Components will handle the correct primitive based on parent context
+  // We use DateSegmentPrimitive as the default, but it will work with TimeField context
+  return (
+    <DateSegmentPrimitive
+      className={composeSlotClassName(slots?.segment, className)}
+      data-slot="date-input-group-segment"
+      segment={segment}
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup InputContainer
+ * -----------------------------------------------------------------------------------------------*/
+interface DateInputGroupInputContainerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DateInputGroupInputContainer = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DateInputGroupInputContainerProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DateInputGroupInputContainerProps<E>>) => {
+  const {slots} = use(DateInputGroupContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.inputContainer, className)}
+      data-slot="date-input-group-input-container"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * DateInputGroup Suffix
+ * -----------------------------------------------------------------------------------------------*/
+interface DateInputGroupSuffixProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DateInputGroupSuffix = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DateInputGroupSuffixProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DateInputGroupSuffixProps<E>>) => {
+  const {slots} = use(DateInputGroupContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.suffix, className)}
+      data-slot="date-input-group-suffix"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DateInputGroupRoot,
+  DateInputGroupInput,
+  DateInputGroupInputContainer,
+  DateInputGroupSegment,
+  DateInputGroupPrefix,
+  DateInputGroupSuffix,
+};
+
+export type {
+  DateInputGroupRootProps,
+  DateInputGroupInputProps,
+  DateInputGroupInputContainerProps,
+  DateInputGroupSegmentProps,
+  DateInputGroupPrefixProps,
+  DateInputGroupSuffixProps,
+};
diff --git a/packages/react/src/components/date-input-group/index.ts b/packages/react/src/components/date-input-group/index.ts
new file mode 100644
index 0000000..9670711
--- /dev/null
+++ b/packages/react/src/components/date-input-group/index.ts
@@ -0,0 +1,61 @@
+import type {ComponentProps} from "react";
+
+import {
+  DateInputGroupInput,
+  DateInputGroupInputContainer,
+  DateInputGroupPrefix,
+  DateInputGroupRoot,
+  DateInputGroupSegment,
+  DateInputGroupSuffix,
+} from "./date-input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const DateInputGroup = Object.assign(DateInputGroupRoot, {
+  Root: DateInputGroupRoot,
+  Input: DateInputGroupInput,
+  InputContainer: DateInputGroupInputContainer,
+  Segment: DateInputGroupSegment,
+  Prefix: DateInputGroupPrefix,
+  Suffix: DateInputGroupSuffix,
+});
+
+export type DateInputGroup = {
+  Props: ComponentProps<typeof DateInputGroupRoot>;
+  RootProps: ComponentProps<typeof DateInputGroupRoot>;
+  InputProps: ComponentProps<typeof DateInputGroupInput>;
+  InputContainerProps: ComponentProps<typeof DateInputGroupInputContainer>;
+  SegmentProps: ComponentProps<typeof DateInputGroupSegment>;
+  PrefixProps: ComponentProps<typeof DateInputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof DateInputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DateInputGroupInput,
+  DateInputGroupInputContainer,
+  DateInputGroupPrefix,
+  DateInputGroupRoot,
+  DateInputGroupSegment,
+  DateInputGroupSuffix,
+};
+
+export type {
+  DateInputGroupRootProps,
+  DateInputGroupRootProps as DateInputGroupProps,
+  DateInputGroupInputProps,
+  DateInputGroupInputContainerProps,
+  DateInputGroupSegmentProps,
+  DateInputGroupPrefixProps,
+  DateInputGroupSuffixProps,
+} from "./date-input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {dateInputGroupVariants} from "@heroui/styles";
+
+export type {DateInputGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/date-picker/date-picker.stories.tsx b/packages/react/src/components/date-picker/date-picker.stories.tsx
new file mode 100644
index 0000000..0e563e2
--- /dev/null
+++ b/packages/react/src/components/date-picker/date-picker.stories.tsx
@@ -0,0 +1,223 @@
+import type {DateValue} from "@internationalized/date";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {Calendar} from "../calendar";
+import {DateField} from "../date-field";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+
+import {DatePicker} from "./index";
+
+const meta: Meta<typeof DatePicker> = {
+  component: DatePicker,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/DatePicker",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const CalendarContent = () => (
+  <Calendar aria-label="Selected date">
+    <Calendar.Header>
+      <Calendar.YearPickerTrigger>
+        <Calendar.YearPickerTriggerHeading />
+        <Calendar.YearPickerTriggerIndicator />
+      </Calendar.YearPickerTrigger>
+      <Calendar.NavButton slot="previous" />
+      <Calendar.NavButton slot="next" />
+    </Calendar.Header>
+    <Calendar.Grid>
+      <Calendar.GridHeader>
+        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
+      </Calendar.GridHeader>
+      <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
+    </Calendar.Grid>
+    <Calendar.YearPickerGrid>
+      <Calendar.YearPickerGridBody>
+        {({year}) => <Calendar.YearPickerCell year={year} />}
+      </Calendar.YearPickerGridBody>
+    </Calendar.YearPickerGrid>
+  </Calendar>
+);
+
+const DatePickerField = ({showDescription = false}: {showDescription?: boolean}) => (
+  <>
+    <Label>Date</Label>
+    <DateField.Group fullWidth>
+      <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+      <DateField.Suffix>
+        <DatePicker.Trigger>
+          <DatePicker.TriggerIndicator />
+        </DatePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    {showDescription ? <Description>Select a date from the calendar.</Description> : null}
+    <DatePicker.Popover>
+      <CalendarContent />
+    </DatePicker.Popover>
+  </>
+);
+
+export const Default: Story = {
+  render: () => (
+    <DatePicker className="w-[280px]" name="date">
+      <DatePickerField />
+    </DatePicker>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(today(getLocalTimeZone()));
+
+    return (
+      <div className="flex w-64 flex-col gap-2">
+        <DatePicker name="date" value={value} onChange={setValue}>
+          <DatePickerField showDescription />
+        </DatePicker>
+        <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <DatePicker isDisabled className="w-64" name="date" value={today(getLocalTimeZone())}>
+      <DatePickerField />
+    </DatePicker>
+  ),
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(null);
+    const currentDate = today(getLocalTimeZone());
+    const isInvalid = value != null && value.compare(currentDate) < 0;
+
+    return (
+      <DatePicker
+        isRequired
+        className="w-64"
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        name="date"
+        value={value}
+        onChange={setValue}
+      >
+        <Label>Appointment date</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+          <DateField.Suffix>
+            <DatePicker.Trigger>
+              <DatePicker.TriggerIndicator />
+            </DatePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Date must be today or in the future.</FieldError>
+        ) : (
+          <Description>Select a date from today onward.</Description>
+        )}
+        <DatePicker.Popover>
+          <CalendarContent />
+        </DatePicker.Popover>
+      </DatePicker>
+    );
+  },
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <DatePicker className="w-64" name="date">
+      <Label>Date</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+        <DateField.Suffix>
+          <DatePicker.Trigger>
+            <DatePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DatePicker.TriggerIndicator>
+          </DatePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>Use a custom trigger icon while keeping DatePicker behavior.</Description>
+      <DatePicker.Popover>
+        <CalendarContent />
+      </DatePicker.Popover>
+    </DatePicker>
+  ),
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateValue | null>(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const currentDate = today(getLocalTimeZone());
+    const isInvalid = value != null && value.compare(currentDate) < 0;
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+      if (!value || isInvalid) return;
+
+      setIsSubmitting(true);
+
+      setTimeout(() => {
+        setValue(null);
+        setIsSubmitting(false);
+      }, 1200);
+    };
+
+    return (
+      <Form className="flex w-64 flex-col gap-3" onSubmit={handleSubmit}>
+        <DatePicker
+          isRequired
+          isInvalid={isInvalid}
+          minValue={currentDate}
+          name="appointmentDate"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Appointment date</Label>
+          <DateField.Group fullWidth>
+            <DateField.Input>
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+            <DateField.Suffix>
+              <DatePicker.Trigger>
+                <DatePicker.TriggerIndicator />
+              </DatePicker.Trigger>
+            </DateField.Suffix>
+          </DateField.Group>
+          {isInvalid ? (
+            <FieldError>Date must be today or in the future.</FieldError>
+          ) : (
+            <Description>Choose a valid appointment date.</Description>
+          )}
+          <DatePicker.Popover>
+            <CalendarContent />
+          </DatePicker.Popover>
+        </DatePicker>
+        <Button
+          className="w-full"
+          isDisabled={!value || isInvalid}
+          isPending={isSubmitting}
+          type="submit"
+        >
+          {isSubmitting ? "Submitting..." : "Submit"}
+        </Button>
+      </Form>
+    );
+  },
+};
diff --git a/packages/react/src/components/date-picker/date-picker.tsx b/packages/react/src/components/date-picker/date-picker.tsx
new file mode 100644
index 0000000..928b793
--- /dev/null
+++ b/packages/react/src/components/date-picker/date-picker.tsx
@@ -0,0 +1,209 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {DatePickerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {DateValue} from "react-aria-components/Calendar";
+
+import {datePickerVariants} from "@heroui/styles";
+import {mergeRefs} from "@react-aria/utils";
+import React, {createContext, use, useEffect, useRef} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {
+  DatePicker as DatePickerPrimitive,
+  Popover as PopoverPrimitive,
+} from "react-aria-components/DatePicker";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconCalendar} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * DatePicker Context
+ * -----------------------------------------------------------------------------------------------*/
+type DatePickerContext = {
+  slots?: ReturnType<typeof datePickerVariants>;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+};
+
+const DatePickerContext = createContext<DatePickerContext>({
+  triggerRef: {current: null},
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * DatePicker Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DatePickerRootProps<T extends DateValue>
+  extends ComponentPropsWithRef<typeof DatePickerPrimitive<T>>, DatePickerVariants {}
+
+const DatePickerRoot = <T extends DateValue>({
+  children,
+  className,
+  onOpenChange,
+  ...props
+}: DatePickerRootProps<T>) => {
+  const slots = React.useMemo(() => datePickerVariants(), []);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [isOpen, setIsOpen] = React.useState(false);
+  const shouldRestoreFocusToTriggerRef = useRef(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleGlobalKeyDown = (event: KeyboardEvent) => {
+      if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+        shouldRestoreFocusToTriggerRef.current = true;
+      }
+    };
+
+    window.addEventListener("keydown", handleGlobalKeyDown, true);
+
+    return () => {
+      window.removeEventListener("keydown", handleGlobalKeyDown, true);
+    };
+  }, [isOpen]);
+
+  const handleOpenChange = (nextIsOpen: boolean) => {
+    setIsOpen(nextIsOpen);
+
+    if (!nextIsOpen && shouldRestoreFocusToTriggerRef.current) {
+      window.requestAnimationFrame(() => {
+        triggerRef.current?.focus();
+      });
+    }
+
+    shouldRestoreFocusToTriggerRef.current = false;
+    onOpenChange?.(nextIsOpen);
+  };
+
+  return (
+    <DatePickerContext value={{slots, triggerRef}}>
+      <DatePickerPrimitive
+        data-required={dataAttr(props.isRequired)}
+        data-slot="date-picker"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+        onOpenChange={handleOpenChange}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </DatePickerPrimitive>
+    </DatePickerContext>
+  );
+};
+
+DatePickerRoot.displayName = "HeroUI.DatePicker";
+
+/* -------------------------------------------------------------------------------------------------
+ * DatePicker Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DatePickerTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const DatePickerTrigger = ({children, className, ref, ...props}: DatePickerTriggerProps) => {
+  const {slots, triggerRef} = use(DatePickerContext);
+
+  const contextRefCallback = React.useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerRef.current = node;
+    },
+    [triggerRef],
+  );
+  const mergedRef = mergeRefs(contextRefCallback, ref);
+
+  return (
+    <ButtonPrimitive
+      ref={mergedRef}
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="date-picker-trigger"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ButtonPrimitive>
+  );
+};
+
+DatePickerTrigger.displayName = "HeroUI.DatePicker.Trigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * DatePicker Trigger Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface DatePickerTriggerIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+const DatePickerTriggerIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: DatePickerTriggerIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DatePickerTriggerIndicatorProps<E>>) => {
+  const {slots} = use(DatePickerContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.triggerIndicator, className)}
+      data-slot="date-picker-trigger-indicator"
+      {...(props as any)}
+    >
+      {children || <IconCalendar />}
+    </dom.span>
+  );
+};
+
+DatePickerTriggerIndicator.displayName = "HeroUI.DatePicker.TriggerIndicator";
+
+/* -------------------------------------------------------------------------------------------------
+ * DatePicker Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface DatePickerPopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const DatePickerPopover = ({
+  children,
+  className,
+  placement = "bottom",
+  ...props
+}: DatePickerPopoverProps) => {
+  const {slots} = use(DatePickerContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="date-picker-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+DatePickerPopover.displayName = "HeroUI.DatePicker.Popover";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {DatePickerRoot, DatePickerTrigger, DatePickerTriggerIndicator, DatePickerPopover};
+
+export type {
+  DatePickerRootProps,
+  DatePickerTriggerProps,
+  DatePickerTriggerIndicatorProps,
+  DatePickerPopoverProps,
+};
diff --git a/packages/react/src/components/date-picker/index.ts b/packages/react/src/components/date-picker/index.ts
new file mode 100644
index 0000000..e7a7d42
--- /dev/null
+++ b/packages/react/src/components/date-picker/index.ts
@@ -0,0 +1,46 @@
+import type {ComponentProps} from "react";
+
+import {
+  DatePickerPopover,
+  DatePickerRoot,
+  DatePickerTrigger,
+  DatePickerTriggerIndicator,
+} from "./date-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const DatePicker = Object.assign(DatePickerRoot, {
+  Root: DatePickerRoot,
+  Trigger: DatePickerTrigger,
+  TriggerIndicator: DatePickerTriggerIndicator,
+  Popover: DatePickerPopover,
+});
+
+export type DatePicker = {
+  Props: ComponentProps<typeof DatePickerRoot>;
+  RootProps: ComponentProps<typeof DatePickerRoot>;
+  TriggerProps: ComponentProps<typeof DatePickerTrigger>;
+  TriggerIndicatorProps: ComponentProps<typeof DatePickerTriggerIndicator>;
+  PopoverProps: ComponentProps<typeof DatePickerPopover>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {DatePickerRoot, DatePickerTrigger, DatePickerTriggerIndicator, DatePickerPopover};
+
+export type {
+  DatePickerRootProps,
+  DatePickerRootProps as DatePickerProps,
+  DatePickerTriggerProps,
+  DatePickerTriggerIndicatorProps,
+  DatePickerPopoverProps,
+} from "./date-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {datePickerVariants} from "@heroui/styles";
+
+export type {DatePickerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/date-range-picker/date-range-picker.stories.tsx b/packages/react/src/components/date-range-picker/date-range-picker.stories.tsx
new file mode 100644
index 0000000..e9ee7a1
--- /dev/null
+++ b/packages/react/src/components/date-range-picker/date-range-picker.stories.tsx
@@ -0,0 +1,277 @@
+import type {DateValue} from "@internationalized/date";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {getLocalTimeZone, today} from "@internationalized/date";
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {DateField} from "../date-field";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+import {RangeCalendar} from "../range-calendar";
+
+import {DateRangePicker} from "./index";
+
+const meta: Meta<typeof DateRangePicker> = {
+  component: DateRangePicker,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/DateRangePicker",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+const RangeCalendarContent = () => (
+  <RangeCalendar aria-label="Selected range">
+    <RangeCalendar.Header>
+      <RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.YearPickerTriggerHeading />
+        <RangeCalendar.YearPickerTriggerIndicator />
+      </RangeCalendar.YearPickerTrigger>
+      <RangeCalendar.NavButton slot="previous" />
+      <RangeCalendar.NavButton slot="next" />
+    </RangeCalendar.Header>
+    <RangeCalendar.Grid>
+      <RangeCalendar.GridHeader>
+        {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+      </RangeCalendar.GridHeader>
+      <RangeCalendar.GridBody>
+        {(date) => <RangeCalendar.Cell date={date} />}
+      </RangeCalendar.GridBody>
+    </RangeCalendar.Grid>
+    <RangeCalendar.YearPickerGrid>
+      <RangeCalendar.YearPickerGridBody>
+        {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+      </RangeCalendar.YearPickerGridBody>
+    </RangeCalendar.YearPickerGrid>
+  </RangeCalendar>
+);
+
+const DateRangePickerField = ({showDescription = false}: {showDescription?: boolean}) => (
+  <>
+    <Label>Trip dates</Label>
+    <DateField.Group fullWidth>
+      <DateField.Input slot="start">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateRangePicker.RangeSeparator />
+      <DateField.Input slot="end">
+        {(segment) => <DateField.Segment segment={segment} />}
+      </DateField.Input>
+      <DateField.Suffix>
+        <DateRangePicker.Trigger>
+          <DateRangePicker.TriggerIndicator />
+        </DateRangePicker.Trigger>
+      </DateField.Suffix>
+    </DateField.Group>
+    {showDescription ? <Description>Select your check-in and check-out dates.</Description> : null}
+    <DateRangePicker.Popover>
+      <RangeCalendarContent />
+    </DateRangePicker.Popover>
+  </>
+);
+
+export const Default: Story = {
+  render: () => (
+    <DateRangePicker className="w-[320px]" endName="endDate" startName="startDate">
+      <DateRangePickerField />
+    </DateRangePicker>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const start = today(getLocalTimeZone());
+    const [value, setValue] = useState<DateRange | null>({end: start.add({days: 4}), start});
+
+    return (
+      <div className="flex w-[320px] flex-col gap-2">
+        <DateRangePicker
+          endName="endDate"
+          startName="startDate"
+          value={value}
+          onChange={(nextValue) => setValue(nextValue as DateRange | null)}
+        >
+          <DateRangePickerField showDescription />
+        </DateRangePicker>
+        <Description>
+          Current value:{" "}
+          {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(empty)"}
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => {
+    const start = today(getLocalTimeZone());
+
+    return (
+      <DateRangePicker
+        isDisabled
+        className="w-[320px]"
+        endName="endDate"
+        startName="startDate"
+        value={{end: start.add({days: 4}), start}}
+      >
+        <DateRangePickerField />
+      </DateRangePicker>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateRange | null>(null);
+    const currentDate = today(getLocalTimeZone());
+    const isInvalid =
+      value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+    return (
+      <DateRangePicker
+        isRequired
+        className="w-[320px]"
+        endName="endDate"
+        isInvalid={isInvalid}
+        minValue={currentDate}
+        startName="startDate"
+        value={value}
+        onChange={(nextValue) => setValue(nextValue as DateRange | null)}
+      >
+        <Label>Booking period</Label>
+        <DateField.Group fullWidth>
+          <DateField.Input slot="start">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateRangePicker.RangeSeparator />
+          <DateField.Input slot="end">
+            {(segment) => <DateField.Segment segment={segment} />}
+          </DateField.Input>
+          <DateField.Suffix>
+            <DateRangePicker.Trigger>
+              <DateRangePicker.TriggerIndicator />
+            </DateRangePicker.Trigger>
+          </DateField.Suffix>
+        </DateField.Group>
+        {isInvalid ? (
+          <FieldError>Select a valid range starting today or later.</FieldError>
+        ) : (
+          <Description>Choose a check-in and check-out date.</Description>
+        )}
+        <DateRangePicker.Popover>
+          <RangeCalendarContent />
+        </DateRangePicker.Popover>
+      </DateRangePicker>
+    );
+  },
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <DateRangePicker className="w-[320px]" endName="endDate" startName="startDate">
+      <Label>Trip dates</Label>
+      <DateField.Group fullWidth>
+        <DateField.Input slot="start">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateRangePicker.RangeSeparator />
+        <DateField.Input slot="end">
+          {(segment) => <DateField.Segment segment={segment} />}
+        </DateField.Input>
+        <DateField.Suffix>
+          <DateRangePicker.Trigger>
+            <DateRangePicker.TriggerIndicator>
+              <Icon className="size-4" icon="gravity-ui:chevron-down" />
+            </DateRangePicker.TriggerIndicator>
+          </DateRangePicker.Trigger>
+        </DateField.Suffix>
+      </DateField.Group>
+      <Description>
+        Use a custom trigger icon while preserving DateRangePicker behavior.
+      </Description>
+      <DateRangePicker.Popover>
+        <RangeCalendarContent />
+      </DateRangePicker.Popover>
+    </DateRangePicker>
+  ),
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateRange | null>(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const currentDate = today(getLocalTimeZone());
+    const isInvalid =
+      value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0);
+
+    const handleSubmit = (event: React.FormEvent) => {
+      event.preventDefault();
+      if (!value || isInvalid) return;
+
+      setIsSubmitting(true);
+
+      setTimeout(() => {
+        setValue(null);
+        setIsSubmitting(false);
+      }, 1200);
+    };
+
+    return (
+      <Form className="flex w-[320px] flex-col gap-3" onSubmit={handleSubmit}>
+        <DateRangePicker
+          isRequired
+          endName="tripEndDate"
+          isInvalid={isInvalid}
+          minValue={currentDate}
+          startName="tripStartDate"
+          value={value}
+          onChange={(nextValue) => setValue(nextValue as DateRange | null)}
+        >
+          <Label>Trip dates</Label>
+          <DateField.Group fullWidth>
+            <DateField.Input slot="start">
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+            <DateRangePicker.RangeSeparator />
+            <DateField.Input slot="end">
+              {(segment) => <DateField.Segment segment={segment} />}
+            </DateField.Input>
+            <DateField.Suffix>
+              <DateRangePicker.Trigger>
+                <DateRangePicker.TriggerIndicator />
+              </DateRangePicker.Trigger>
+            </DateField.Suffix>
+          </DateField.Group>
+          {isInvalid ? (
+            <FieldError>Please choose a valid range in the future.</FieldError>
+          ) : (
+            <Description>Select your check-in and check-out dates.</Description>
+          )}
+          <DateRangePicker.Popover>
+            <RangeCalendarContent />
+          </DateRangePicker.Popover>
+        </DateRangePicker>
+        <Button
+          className="w-full"
+          isDisabled={!value || isInvalid}
+          isPending={isSubmitting}
+          type="submit"
+        >
+          {isSubmitting ? "Submitting..." : "Submit"}
+        </Button>
+      </Form>
+    );
+  },
+};
diff --git a/packages/react/src/components/date-range-picker/date-range-picker.tsx b/packages/react/src/components/date-range-picker/date-range-picker.tsx
new file mode 100644
index 0000000..e4b21c6
--- /dev/null
+++ b/packages/react/src/components/date-range-picker/date-range-picker.tsx
@@ -0,0 +1,253 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {DateRangePickerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {DateValue} from "react-aria-components/Calendar";
+
+import {dateRangePickerVariants} from "@heroui/styles";
+import {mergeRefs} from "@react-aria/utils";
+import React, {createContext, use, useEffect, useRef} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {
+  DateRangePicker as DateRangePickerPrimitive,
+  Popover as PopoverPrimitive,
+} from "react-aria-components/DateRangePicker";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconCalendar} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Context
+ * -----------------------------------------------------------------------------------------------*/
+type DateRangePickerContext = {
+  slots?: ReturnType<typeof dateRangePickerVariants>;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+};
+
+const DateRangePickerContext = createContext<DateRangePickerContext>({
+  triggerRef: {current: null},
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DateRangePickerRootProps<T extends DateValue>
+  extends ComponentPropsWithRef<typeof DateRangePickerPrimitive<T>>, DateRangePickerVariants {}
+
+const DateRangePickerRoot = <T extends DateValue>({
+  children,
+  className,
+  onOpenChange,
+  ...props
+}: DateRangePickerRootProps<T>) => {
+  const slots = React.useMemo(() => dateRangePickerVariants(), []);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [isOpen, setIsOpen] = React.useState(false);
+  const shouldRestoreFocusToTriggerRef = useRef(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleGlobalKeyDown = (event: KeyboardEvent) => {
+      if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+        shouldRestoreFocusToTriggerRef.current = true;
+      }
+    };
+
+    window.addEventListener("keydown", handleGlobalKeyDown, true);
+
+    return () => {
+      window.removeEventListener("keydown", handleGlobalKeyDown, true);
+    };
+  }, [isOpen]);
+
+  const handleOpenChange = (nextIsOpen: boolean) => {
+    setIsOpen(nextIsOpen);
+
+    if (!nextIsOpen && shouldRestoreFocusToTriggerRef.current) {
+      window.requestAnimationFrame(() => {
+        triggerRef.current?.focus();
+      });
+    }
+
+    shouldRestoreFocusToTriggerRef.current = false;
+    onOpenChange?.(nextIsOpen);
+  };
+
+  return (
+    <DateRangePickerContext value={{slots, triggerRef}}>
+      <DateRangePickerPrimitive
+        data-required={dataAttr(props.isRequired)}
+        data-slot="date-range-picker"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+        onOpenChange={handleOpenChange}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </DateRangePickerPrimitive>
+    </DateRangePickerContext>
+  );
+};
+
+DateRangePickerRoot.displayName = "HeroUI.DateRangePicker";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DateRangePickerTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const DateRangePickerTrigger = ({
+  children,
+  className,
+  ref,
+  ...props
+}: DateRangePickerTriggerProps) => {
+  const {slots, triggerRef} = use(DateRangePickerContext);
+
+  const contextRefCallback = React.useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerRef.current = node;
+    },
+    [triggerRef],
+  );
+  const mergedRef = mergeRefs(contextRefCallback, ref);
+
+  return (
+    <ButtonPrimitive
+      ref={mergedRef}
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="date-range-picker-trigger"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ButtonPrimitive>
+  );
+};
+
+DateRangePickerTrigger.displayName = "HeroUI.DateRangePicker.Trigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Trigger Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface DateRangePickerTriggerIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+const DateRangePickerTriggerIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: DateRangePickerTriggerIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DateRangePickerTriggerIndicatorProps<E>>) => {
+  const {slots} = use(DateRangePickerContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.triggerIndicator, className)}
+      data-slot="date-range-picker-trigger-indicator"
+      {...(props as any)}
+    >
+      {children || <IconCalendar />}
+    </dom.span>
+  );
+};
+
+DateRangePickerTriggerIndicator.displayName = "HeroUI.DateRangePicker.TriggerIndicator";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Range Separator
+ * -----------------------------------------------------------------------------------------------*/
+interface DateRangePickerRangeSeparatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DateRangePickerRangeSeparator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children = " - ",
+  className,
+  ...props
+}: DateRangePickerRangeSeparatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DateRangePickerRangeSeparatorProps<E>>) => {
+  const {slots} = use(DateRangePickerContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.rangeSeparator, className)}
+      data-slot="date-range-picker-range-separator"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+DateRangePickerRangeSeparator.displayName = "HeroUI.DateRangePicker.RangeSeparator";
+
+/* -------------------------------------------------------------------------------------------------
+ * DateRangePicker Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface DateRangePickerPopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const DateRangePickerPopover = ({
+  children,
+  className,
+  placement = "bottom",
+  ...props
+}: DateRangePickerPopoverProps) => {
+  const {slots} = use(DateRangePickerContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="date-range-picker-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+DateRangePickerPopover.displayName = "HeroUI.DateRangePicker.Popover";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DateRangePickerRoot,
+  DateRangePickerTrigger,
+  DateRangePickerTriggerIndicator,
+  DateRangePickerRangeSeparator,
+  DateRangePickerPopover,
+};
+
+export type {
+  DateRangePickerRootProps,
+  DateRangePickerTriggerProps,
+  DateRangePickerTriggerIndicatorProps,
+  DateRangePickerRangeSeparatorProps,
+  DateRangePickerPopoverProps,
+};
diff --git a/packages/react/src/components/date-range-picker/index.ts b/packages/react/src/components/date-range-picker/index.ts
new file mode 100644
index 0000000..e3a0498
--- /dev/null
+++ b/packages/react/src/components/date-range-picker/index.ts
@@ -0,0 +1,56 @@
+import type {ComponentProps} from "react";
+
+import {
+  DateRangePickerPopover,
+  DateRangePickerRangeSeparator,
+  DateRangePickerRoot,
+  DateRangePickerTrigger,
+  DateRangePickerTriggerIndicator,
+} from "./date-range-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const DateRangePicker = Object.assign(DateRangePickerRoot, {
+  Root: DateRangePickerRoot,
+  Trigger: DateRangePickerTrigger,
+  TriggerIndicator: DateRangePickerTriggerIndicator,
+  RangeSeparator: DateRangePickerRangeSeparator,
+  Popover: DateRangePickerPopover,
+});
+
+export type DateRangePicker = {
+  Props: ComponentProps<typeof DateRangePickerRoot>;
+  RootProps: ComponentProps<typeof DateRangePickerRoot>;
+  TriggerProps: ComponentProps<typeof DateRangePickerTrigger>;
+  TriggerIndicatorProps: ComponentProps<typeof DateRangePickerTriggerIndicator>;
+  RangeSeparatorProps: ComponentProps<typeof DateRangePickerRangeSeparator>;
+  PopoverProps: ComponentProps<typeof DateRangePickerPopover>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DateRangePickerRoot,
+  DateRangePickerTrigger,
+  DateRangePickerTriggerIndicator,
+  DateRangePickerRangeSeparator,
+  DateRangePickerPopover,
+};
+
+export type {
+  DateRangePickerRootProps,
+  DateRangePickerRootProps as DateRangePickerProps,
+  DateRangePickerTriggerProps,
+  DateRangePickerTriggerIndicatorProps,
+  DateRangePickerRangeSeparatorProps,
+  DateRangePickerPopoverProps,
+} from "./date-range-picker";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {dateRangePickerVariants} from "@heroui/styles";
+
+export type {DateRangePickerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/description/description.tsx b/packages/react/src/components/description/description.tsx
new file mode 100644
index 0000000..2afaaf1
--- /dev/null
+++ b/packages/react/src/components/description/description.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import type {DescriptionVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {TextProps} from "react-aria-components/Text";
+
+import {descriptionVariants} from "@heroui/styles";
+import {Text} from "react-aria-components/Text";
+
+/* -------------------------------------------------------------------------------------------------
+ * Description Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DescriptionRootProps
+  extends ComponentPropsWithRef<typeof Text>, TextProps, DescriptionVariants {}
+
+const DescriptionRoot = ({children, className, ...rest}: DescriptionRootProps) => {
+  return (
+    <Text
+      className={descriptionVariants({className})}
+      data-slot="description"
+      slot="description"
+      {...rest}
+    >
+      {children}
+    </Text>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {DescriptionRoot};
+
+export type {DescriptionRootProps};
diff --git a/packages/react/src/components/description/index.ts b/packages/react/src/components/description/index.ts
new file mode 100644
index 0000000..11bfbd6
--- /dev/null
+++ b/packages/react/src/components/description/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {DescriptionRoot} from "./description";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Description = Object.assign(DescriptionRoot, {
+  Root: DescriptionRoot,
+});
+
+export type Description = {
+  Props: ComponentProps<typeof DescriptionRoot>;
+  RootProps: ComponentProps<typeof DescriptionRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {DescriptionRoot};
+
+export type {DescriptionRootProps, DescriptionRootProps as DescriptionProps} from "./description";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {descriptionVariants} from "@heroui/styles";
+
+export type {DescriptionVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/disclosure-group/disclosure-group.stories.tsx b/packages/react/src/components/disclosure-group/disclosure-group.stories.tsx
new file mode 100644
index 0000000..9f1f2cf
--- /dev/null
+++ b/packages/react/src/components/disclosure-group/disclosure-group.stories.tsx
@@ -0,0 +1,489 @@
+import type {DisclosureGroupProps} from "./index";
+import type {ButtonProps} from "@heroui/react";
+import type {Meta} from "@storybook/react";
+import type {SVGProps} from "react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cn} from "tailwind-variants";
+
+import {Button} from "../button";
+import {Disclosure} from "../disclosure";
+import {Separator} from "../separator";
+
+import {DisclosureGroup, useDisclosureGroupNavigation} from "./index";
+
+export default {
+  argTypes: {
+    isDisabled: {
+      control: {
+        type: "boolean",
+      },
+    },
+    allowsMultipleExpanded: {
+      control: {
+        type: "boolean",
+      },
+    },
+  },
+  component: DisclosureGroup,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/DisclosureGroup",
+} as Meta<typeof DisclosureGroup>;
+
+const defaultArgs: DisclosureGroupProps = {
+  isDisabled: false,
+  allowsMultipleExpanded: false,
+};
+
+const Template = (props: DisclosureGroupProps) => {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 rounded-3xl bg-surface p-4 shadow-surface">
+        <DisclosureGroup {...props} expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="Preview HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="gravity-ui:qr-code" />
+                  Preview HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />
+                  Preview on Expo Go
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="Download HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download on App Store
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+};
+
+const ControlledTemplate = (props: DisclosureGroupProps) => {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"]));
+  const itemIds = ["preview", "download"]; // Track our disclosure items
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <div className="w-full max-w-md">
+      <div className="flex flex-col gap-4 rounded-3xl bg-surface p-4 shadow-surface">
+        <div className="mb-2 flex items-center justify-between">
+          <h3 className="text-lg font-semibold">HeroUI Native</h3>
+          <div className="flex gap-2">
+            <Button
+              aria-label="Previous disclosure"
+              isDisabled={isPrevDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onPrevious}
+            >
+              <Icon className="size-4" icon="lucide:chevron-up" />
+            </Button>
+            <Button
+              aria-label="Next disclosure"
+              isDisabled={isNextDisabled}
+              size="sm"
+              variant="secondary"
+              onPress={onNext}
+            >
+              <Icon className="size-4" icon="lucide:chevron-down" />
+            </Button>
+          </div>
+        </div>
+        <DisclosureGroup {...props} expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
+          <Disclosure aria-label="Preview HeroUI Native" id="preview">
+            <Disclosure.Heading>
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("preview") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("preview"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="gravity-ui:qr-code" />
+                  Preview HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />
+                  Preview on Expo Go
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+          <Separator className="my-2" />
+          <Disclosure id="download">
+            <Disclosure.Heading aria-label="Download HeroUI Native">
+              <Button
+                slot="trigger"
+                variant={expandedKeys.has("download") ? "secondary" : "tertiary"}
+                className={cn("w-full border-none", {
+                  "bg-transparent": !expandedKeys.has("download"),
+                })}
+              >
+                <div className="flex w-full items-center justify-start gap-2">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download HeroUI Native
+                </div>
+                <Disclosure.Indicator className="text-muted" />
+              </Button>
+            </Disclosure.Heading>
+            <Disclosure.Content>
+              <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center">
+                <p className="text-sm text-muted">
+                  Scan this QR code with your camera app to preview the HeroUI native components.
+                </p>
+                <img
+                  alt="Expo Go QR Code"
+                  className="aspect-square w-full max-w-54 object-cover"
+                  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+                />
+                <p className="text-sm text-muted">Expo must be installed on your device.</p>
+                <Button className="mt-4" variant="primary">
+                  <Icon icon="tabler:brand-apple-filled" />
+                  Download on App Store
+                </Button>
+              </Disclosure.Body>
+            </Disclosure.Content>
+          </Disclosure>
+        </DisclosureGroup>
+      </div>
+    </div>
+  );
+};
+
+function AppleShowcaseButton({
+  children,
+  className,
+  isSelected,
+  ...props
+}: ButtonProps & {isSelected: boolean}) {
+  return (
+    <Button
+      className={cn(
+        "h-14 rounded-full bg-[#1e1e20] text-[17px] text-[#f5f5f7] duration-[400ms] ease-in-out-quad hover:bg-[#272729]",
+        isSelected && "bg-[#272729]",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Button>
+  );
+}
+
+function SelectedIphoneColorSwatch({color, name}: {color: string; name: string}) {
+  return (
+    <span
+      className="group relative size-6 rounded-lg shadow-[inset_0px_-1px_0px_0px_rgba(255,255,255,.5)]"
+      style={{
+        backgroundColor: `${color}`,
+      }}
+    >
+      <span className="sr-only">Copy {name} color</span>
+    </span>
+  );
+}
+
+function PlusIcon({className, height = 24, width = 24, ...props}: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      className={cn("size-6 flex-none", className)}
+      height={height}
+      viewBox="0 0 24 24"
+      width={width}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <circle cx="12" cy="12" fill="none" r="11.3" stroke="currentColor" />
+      <g fill="currentColor" stroke="none" transform="translate(7 7)">
+        <path d="m9 4h-3v-3c0-0.553-0.447-1-1-1s-1 0.447-1 1v3h-3c-0.553 0-1 0.447-1 1s0.447 1 1 1h3v3c0 0.553 0.447 1 1 1s1-0.447 1-1v-3h3c0.553 0 1-0.447 1-1s-0.447-1-1-1" />
+      </g>
+    </svg>
+  );
+}
+
+const showcase1Items = [
+  {
+    id: "colors",
+    label: "Colors",
+    content: "Choose from three bold finishes. iPhone 17 Pro shown in Cosmic Orange.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/colors_orange__f2ug4x6ry8uq_large_2x.jpg",
+  },
+  {
+    id: "aluminum",
+    label: "Aluminum unibody",
+    content:
+      "Optimized for performance and battery. Aluminum alloy is remarkably light and has exceptional thermal conductivity.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_aluminum_endframe__fypyvk9kkg2m_large_2x.jpg",
+  },
+  {
+    id: "vapor-chamber",
+    label: "Vapor chamber",
+    content:
+      "Deionized water sealed inside moves heat away from the A19 Pro chip, allowing for even higher sustained performance.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_vapor_chamber_endframe__dst8qkmuys4m_large_2x.jpg",
+  },
+  {
+    id: "ceramic-shield",
+    label: "Ceramic shield",
+    content:
+      "Protects the back of iPhone 17 Pro, making it 4x more resistant to cracks. New Ceramic Shield 2 on the front has 3x better scratch resistance.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/ceramic_shield__de0653vp43cm_large_2x.jpg",
+  },
+  {
+    id: "immersive-pro-display",
+    label: "Immersive pro display",
+    content:
+      "Our best‑ever 6.3‑inch and 6.9‑inch Super Retina XDR displays.5 Brighter. Better anti‑reflection. ProMotion up to 120Hz.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/pro_display__c0jmzc5emcae_large_2x.jpg",
+  },
+  {
+    id: "camera-control",
+    label: "Camera control",
+    content:
+      "Instantly take a photo, record video, adjust settings, and more. So you never miss a moment.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/camera_control__cy5kilwa0kwi_large_2x.jpg",
+  },
+  {
+    id: "action-button",
+    label: "Action button",
+    content:
+      " A customizable fast track to your favorite feature. Long press to launch the action you want — Silent mode, Translation, Shortcuts, and more.",
+    imgSrc:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/product-viewer/viewer_action_button_startframe__bb2coc4lpj2a_large_2x.jpg",
+  },
+];
+
+const Showcase1Template = (props: DisclosureGroupProps) => {
+  const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["colors"]));
+  const itemIds = showcase1Items.map((item) => item.id);
+  const isAnyItemExpanded = expandedKeys.size > 0;
+
+  const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({
+    expandedKeys,
+    itemIds,
+    onExpandedChange: setExpandedKeys,
+  });
+
+  return (
+    <section className="w-full overflow-hidden bg-surface">
+      {/* Left content */}
+      <div className="flex w-full items-center gap-8 px-8 py-8">
+        {/* Controls */}
+        <div
+          data-expanded={isAnyItemExpanded}
+          className={cn(
+            "z-[1] hidden flex-col gap-5 opacity-0 sm:flex",
+            // Animation
+            "transition-all duration-300 ease-out-quad data-[expanded=true]:duration-400",
+            "translate-y-[120px] data-[expanded=true]:translate-y-0 data-[expanded=true]:opacity-100",
+            "scale-50 data-[expanded=true]:scale-100",
+          )}
+        >
+          <Button
+            isIconOnly
+            aria-label="Previous disclosure"
+            className="rounded-full transition-all duration-250 ease-smooth"
+            isDisabled={isPrevDisabled}
+            variant="secondary"
+            onPress={onPrevious}
+          >
+            <svg className="size-8 fill-foreground" viewBox="0 0 36 36">
+              <path d="m11 20c0-.3838.1465-.7676.4395-1.0605l5.5-5.5c.5854-.5859 1.5356-.5859 2.1211 0l5.5 5.5c.5859.5859.5859 1.5352 0 2.1211-.5854.5859-1.5356.5859-2.1211 0l-4.4395-4.4395-4.4395 4.4395c-.5854.5859-1.5356.5859-2.1211 0-.293-.293-.4395-.6768-.4395-1.0605z" />
+            </svg>
+          </Button>
+          <Button
+            isIconOnly
+            aria-label="Next disclosure"
+            className="rounded-full transition-all duration-250 ease-smooth"
+            isDisabled={isNextDisabled}
+            variant="secondary"
+            onPress={onNext}
+          >
+            <svg className="size-8 fill-foreground" viewBox="0 0 36 36">
+              <path d="m19.0625 22.5597 5.5-5.5076c.5854-.5854.5825-1.5323-.0039-2.1157-.5869-.5835-1.5366-.5815-2.1211.0039l-4.4375 4.4438-4.4375-4.4438c-.5845-.5854-1.5342-.5874-2.1211-.0039-.2944.2922-.4414.676-.4414 1.0598 0 .3818.1455.7637.4375 1.0559l5.5 5.5076c.2813.2815.6636.4403 1.0625.4403s.7812-.1588 1.0625-.4403z" />
+            </svg>
+          </Button>
+        </div>
+        <div className="z-[1] w-full max-w-md">
+          <DisclosureGroup
+            {...props}
+            className="flex flex-col gap-y-3"
+            expandedKeys={expandedKeys}
+            onExpandedChange={setExpandedKeys}
+          >
+            {showcase1Items.map((item) => (
+              <Disclosure key={item.id} aria-label={item.label} id={item.id}>
+                <Disclosure.Heading>
+                  <AppleShowcaseButton isSelected={expandedKeys.has(item.id)} slot="trigger">
+                    <div className="flex w-full items-center justify-start gap-3">
+                      {item.id === "colors" ? (
+                        <SelectedIphoneColorSwatch color="#f77314" name="Cosmic Orange" />
+                      ) : (
+                        <PlusIcon />
+                      )}
+                      {item.label}
+                    </div>
+                  </AppleShowcaseButton>
+                </Disclosure.Heading>
+                <Disclosure.Content className="duration-[420ms] ease-[cubic-bezier(0.95,0.05,0.795,0.035)] ease-out-quad">
+                  <Disclosure.Body
+                    data-expanded={expandedKeys.has(item.id)}
+                    className={cn(
+                      "mt-3 flex max-w-sm flex-col items-center gap-2 rounded-2xl bg-[rgba(42,42,45,0.72)] p-7 text-left backdrop-blur-[20px]",
+                    )}
+                  >
+                    <p
+                      data-expanded={expandedKeys.has(item.id)}
+                      className={cn(
+                        "text-[17px] font-light text-[#F5F5F7]",
+                        "translate-y-[20px] opacity-0",
+                        "data-[expanded=true]:translate-y-0 data-[expanded=true]:opacity-100",
+                      )}
+                      style={{
+                        transition: expandedKeys.has(item.id)
+                          ? "opacity 1200ms ease-out, translate 800ms cubic-bezier(0.18,0.89,0.32,1.27)"
+                          : " ",
+                        willChange: "opacity, translate",
+                      }}
+                    >
+                      <strong className="font-medium">{item.label}</strong>.&nbsp;{item.content}
+                    </p>
+                  </Disclosure.Body>
+                </Disclosure.Content>
+              </Disclosure>
+            ))}
+          </DisclosureGroup>
+        </div>
+      </div>
+      {/* Right image */}
+      {showcase1Items.map((item) => (
+        <img
+          key={item.id}
+          alt={item.label}
+          data-selected={expandedKeys.has(item.id)}
+          src={item.imgSrc}
+          className={cn(
+            "pointer-events-none absolute top-1/2 right-[10%] z-[0] hidden w-full max-w-6xl -translate-y-1/2 scale-[1.5] opacity-0 lg:block",
+            "translate-x-[10%] data-[selected=true]:translate-x-0 data-[selected=true]:opacity-100",
+          )}
+          style={{
+            transition: expandedKeys.has(item.id)
+              ? "opacity 1000ms ease-out, translate 900ms var(--ease-out-quad)"
+              : " ",
+            willChange: "opacity, translate",
+          }}
+        />
+      ))}
+    </section>
+  );
+};
+
+export const Default = {
+  args: {
+    ...defaultArgs,
+  },
+  render: Template,
+};
+
+export const Controlled = {
+  args: {
+    ...defaultArgs,
+  },
+  render: ControlledTemplate,
+};
+
+export const Showcase1 = {
+  args: {
+    children: null,
+  },
+  render: Showcase1Template,
+  name: "Showcases/Apple iPhone 17 Pro Disclosure Group",
+};
diff --git a/packages/react/src/components/disclosure-group/disclosure-group.tsx b/packages/react/src/components/disclosure-group/disclosure-group.tsx
new file mode 100644
index 0000000..d1f475a
--- /dev/null
+++ b/packages/react/src/components/disclosure-group/disclosure-group.tsx
@@ -0,0 +1,48 @@
+"use client";
+
+import type {DisclosureGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {disclosureGroupVariants} from "@heroui/styles";
+import React, {createContext} from "react";
+import {DisclosureGroup as DisclosureGroupPrimitive} from "react-aria-components/DisclosureGroup";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Group Context
+ * -----------------------------------------------------------------------------------------------*/
+type DisclosureGroupContext = {
+  slots?: ReturnType<typeof disclosureGroupVariants>;
+};
+
+const DisclosureGroupContext = createContext<DisclosureGroupContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Group Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureGroupRootProps
+  extends ComponentPropsWithRef<typeof DisclosureGroupPrimitive>, DisclosureGroupVariants {}
+
+const DisclosureGroupRoot = ({children, className, ...props}: DisclosureGroupRootProps) => {
+  const slots = React.useMemo(() => disclosureGroupVariants({}), []);
+
+  return (
+    <DisclosureGroupContext value={{slots}}>
+      <DisclosureGroupPrimitive
+        data-slot="disclosure-group"
+        {...props}
+        className={composeTwRenderProps(className, slots.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </DisclosureGroupPrimitive>
+    </DisclosureGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {DisclosureGroupRoot};
+
+export type {DisclosureGroupRootProps};
diff --git a/packages/react/src/components/disclosure-group/index.ts b/packages/react/src/components/disclosure-group/index.ts
new file mode 100644
index 0000000..6cff3d6
--- /dev/null
+++ b/packages/react/src/components/disclosure-group/index.ts
@@ -0,0 +1,42 @@
+import type {ComponentProps} from "react";
+
+import {DisclosureGroupRoot} from "./disclosure-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const DisclosureGroup = Object.assign(DisclosureGroupRoot, {
+  Root: DisclosureGroupRoot,
+});
+
+export type DisclosureGroup = {
+  Props: ComponentProps<typeof DisclosureGroupRoot>;
+  RootProps: ComponentProps<typeof DisclosureGroupRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {DisclosureGroupRoot};
+
+export type {
+  DisclosureGroupRootProps,
+  DisclosureGroupRootProps as DisclosureGroupProps,
+} from "./disclosure-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {disclosureGroupVariants} from "@heroui/styles";
+
+export type {DisclosureGroupVariants} from "@heroui/styles";
+
+/* -------------------------------------------------------------------------------------------------
+ * Hooks
+ * -----------------------------------------------------------------------------------------------*/
+export {useDisclosureGroupNavigation} from "./use-disclosure-group-navigation";
+
+export type {
+  UseDisclosureGroupNavigationProps,
+  UseDisclosureGroupNavigationReturn,
+} from "./use-disclosure-group-navigation";
diff --git a/packages/react/src/components/disclosure-group/use-disclosure-group-navigation.ts b/packages/react/src/components/disclosure-group/use-disclosure-group-navigation.ts
new file mode 100644
index 0000000..ebeef46
--- /dev/null
+++ b/packages/react/src/components/disclosure-group/use-disclosure-group-navigation.ts
@@ -0,0 +1,84 @@
+import {useCallback, useMemo} from "react";
+
+export interface UseDisclosureGroupNavigationProps {
+  expandedKeys: Set<string | number>;
+  itemIds: string[];
+  onExpandedChange: (keys: Set<string | number>) => void;
+  allowsMultipleExpanded?: boolean;
+}
+
+export interface UseDisclosureGroupNavigationReturn {
+  currentIndex: number;
+  isPrevDisabled: boolean;
+  isNextDisabled: boolean;
+  onPrevious: () => void;
+  onNext: () => void;
+}
+
+export function useDisclosureGroupNavigation({
+  allowsMultipleExpanded = false,
+  expandedKeys,
+  itemIds = [],
+  onExpandedChange,
+}: UseDisclosureGroupNavigationProps): UseDisclosureGroupNavigationReturn {
+  const currentIndex = useMemo(() => {
+    const expandedItems = itemIds.filter((id) => expandedKeys.has(id));
+    const currentItem = expandedItems.length > 0 ? expandedItems[0] : itemIds[0];
+
+    if (!currentItem) return -1;
+
+    return itemIds.indexOf(currentItem);
+  }, [expandedKeys, itemIds]);
+
+  const handlePrevious = useCallback(() => {
+    if (currentIndex <= 0) return;
+
+    const prevItem = itemIds[currentIndex - 1];
+
+    if (!prevItem) return;
+
+    if (allowsMultipleExpanded) {
+      const newKeys = new Set(expandedKeys);
+
+      newKeys.add(prevItem);
+      onExpandedChange(newKeys);
+    } else {
+      onExpandedChange(new Set([prevItem]));
+    }
+  }, [currentIndex, itemIds, expandedKeys, onExpandedChange, allowsMultipleExpanded]);
+
+  const handleNext = useCallback(() => {
+    if (currentIndex >= itemIds.length - 1) return;
+
+    const nextItem = itemIds[currentIndex + 1];
+
+    if (!nextItem) return;
+
+    if (allowsMultipleExpanded) {
+      const newKeys = new Set(expandedKeys);
+
+      newKeys.add(nextItem);
+      onExpandedChange(newKeys);
+    } else {
+      onExpandedChange(new Set([nextItem]));
+    }
+  }, [
+    currentIndex,
+    itemIds.length,
+    itemIds,
+    expandedKeys,
+    onExpandedChange,
+    allowsMultipleExpanded,
+  ]);
+
+  const isPrevDisabled = currentIndex <= 0;
+  const isNextDisabled = currentIndex >= itemIds.length - 1;
+
+  return {
+    currentIndex,
+    isPrevDisabled,
+    isNextDisabled,
+    onPrevious: handlePrevious,
+    onNext: handleNext,
+  };
+}
diff --git a/packages/react/src/components/disclosure/disclosure.stories.tsx b/packages/react/src/components/disclosure/disclosure.stories.tsx
new file mode 100644
index 0000000..6170263
--- /dev/null
+++ b/packages/react/src/components/disclosure/disclosure.stories.tsx
@@ -0,0 +1,191 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {Chip} from "../chip";
+
+import {Disclosure} from "./index";
+
+export default {
+  argTypes: {
+    isDisabled: {
+      control: {
+        type: "boolean",
+      },
+    },
+    isExpanded: {
+      control: {
+        type: "boolean",
+      },
+    },
+  },
+  component: Disclosure,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/Disclosure",
+} as Meta<typeof Disclosure>;
+
+const defaultArgs: Disclosure["RootProps"] = {
+  isDisabled: false,
+  isExpanded: false,
+};
+
+const Template = (props: Disclosure["RootProps"]) => {
+  const [isExpanded, setIsExpanded] = React.useState(props.isExpanded ?? false);
+
+  return (
+    <div className="w-full max-w-md text-center">
+      <Disclosure {...props} isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
+        <Disclosure.Heading>
+          <Button slot="trigger" variant="secondary">
+            <Icon icon="gravity-ui:qr-code" />
+            Preview HeroUI Native
+            <Disclosure.Indicator />
+          </Button>
+        </Disclosure.Heading>
+        <Disclosure.Content>
+          <Disclosure.Body className="flex flex-col items-center rounded-3xl bg-surface p-2 p-4 text-center shadow-surface">
+            <p className="text-sm text-muted">
+              Scan this QR code with your camera app to preview the HeroUI native components.
+            </p>
+            <img
+              alt="Expo Go QR Code"
+              className="aspect-square w-full max-w-54 object-cover"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png"
+            />
+            <p className="text-sm text-muted">Expo must be installed on your device.</p>
+            <Button className="mt-4" variant="primary">
+              <Icon icon="tabler:brand-apple-filled" />
+              Download on App Store
+            </Button>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+};
+
+const ControlledTemplate = (props: Disclosure["RootProps"]) => {
+  const [isExpanded, setIsExpanded] = React.useState(false);
+
+  return (
+    <div className="w-full max-w-md space-y-4">
+      <div className="flex items-center gap-4">
+        <Button variant="primary" onPress={() => setIsExpanded(!isExpanded)}>
+          {isExpanded ? "Collapse" : "Expand"} from outside
+        </Button>
+        <Chip color={isExpanded ? "success" : "default"}>
+          State: {isExpanded ? "Expanded" : "Collapsed"}
+        </Chip>
+      </div>
+      <Disclosure {...props} isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
+        <Disclosure.Trigger className="mb-2 flex w-full items-center justify-between rounded-md border border-gray-300 px-4 py-2 text-left hover:bg-gray-50">
+          <span>Toggle content</span>
+          <Icon
+            className="size-4 transition-transform duration-200 data-[state=open]:rotate-180"
+            icon="gravity-ui:chevron-down"
+          />
+        </Disclosure.Trigger>
+        <Disclosure.Content>
+          <Disclosure.Body className="rounded-lg border p-4">
+            <p className="text-sm">
+              This disclosure is controlled from outside. You can toggle it using the button above
+              or by clicking the trigger.
+            </p>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+};
+
+const ProductDetailsTemplate = (props: Disclosure["RootProps"]) => {
+  const [isExpanded, setIsExpanded] = React.useState(false);
+
+  return (
+    <div className="w-full max-w-md">
+      <Disclosure {...props} isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
+        <Disclosure.Trigger className="flex w-full items-center justify-between rounded-md border border-gray-300 px-4 py-2 text-left hover:bg-gray-50">
+          <span className="flex items-center gap-2">
+            <Icon icon="gravity-ui:box" />
+            View product details
+          </span>
+          <Icon
+            className="size-4 transition-transform duration-200"
+            icon={isExpanded ? "gravity-ui:chevron-up" : "gravity-ui:chevron-down"}
+          />
+        </Disclosure.Trigger>
+        <Disclosure.Content>
+          <Disclosure.Body className="pt-2">
+            <div className="space-y-4 rounded-lg border p-4">
+              <h3 className="text-lg font-semibold">Product Details</h3>
+              <div className="grid gap-2 text-sm">
+                <div className="flex justify-between">
+                  <span className="text-muted-foreground">Material:</span>
+                  <span>100% Cotton</span>
+                </div>
+                <div className="flex justify-between">
+                  <span className="text-muted-foreground">Size:</span>
+                  <span>Medium (38-40)</span>
+                </div>
+                <div className="flex justify-between">
+                  <span className="text-muted-foreground">Color:</span>
+                  <span>Navy Blue</span>
+                </div>
+                <div className="flex justify-between">
+                  <span className="text-muted-foreground">Care:</span>
+                  <span>Machine wash cold</span>
+                </div>
+              </div>
+              <div className="flex gap-2 pt-2">
+                <Chip color="success">Free Shipping</Chip>
+                <Chip color="accent">1 Year Warranty</Chip>
+                <Chip color="warning">Eco-Friendly</Chip>
+              </div>
+            </div>
+          </Disclosure.Body>
+        </Disclosure.Content>
+      </Disclosure>
+    </div>
+  );
+};
+
+export const Default = {
+  args: {
+    ...defaultArgs,
+  },
+  render: Template,
+};
+
+export const Controlled = {
+  args: {
+    ...defaultArgs,
+  },
+  render: ControlledTemplate,
+};
+
+export const ProductDetails = {
+  args: {
+    ...defaultArgs,
+  },
+  render: ProductDetailsTemplate,
+};
+
+export const InitiallyExpanded = {
+  args: {
+    ...defaultArgs,
+    isExpanded: true,
+  },
+  render: Template,
+};
+
+export const Disabled = {
+  args: {
+    ...defaultArgs,
+    isDisabled: true,
+  },
+  render: Template,
+};
diff --git a/packages/react/src/components/disclosure/disclosure.tsx b/packages/react/src/components/disclosure/disclosure.tsx
new file mode 100644
index 0000000..32a9846
--- /dev/null
+++ b/packages/react/src/components/disclosure/disclosure.tsx
@@ -0,0 +1,208 @@
+"use client";
+
+import type {Booleanish} from "../../utils/assertion";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {DisclosureVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {ButtonProps} from "react-aria-components/Button";
+
+import {disclosureVariants} from "@heroui/styles";
+import React, {createContext, use, useRef} from "react";
+import {Button} from "react-aria-components/Button";
+import {
+  DisclosurePanel,
+  Disclosure as DisclosurePrimitive,
+  DisclosureStateContext,
+} from "react-aria-components/Disclosure";
+import {Heading as DisclosureHeadingPrimitive} from "react-aria-components/Heading";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronDown} from "../icons";
+
+/* ------------------------------------------------------------------------------------------------
+ * Disclosure Context
+ * --------------------------------------------------------------------------------------------- */
+type DisclosureContext = {
+  slots?: ReturnType<typeof disclosureVariants>;
+};
+
+const DisclosureContext = createContext<DisclosureContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureRootProps
+  extends ComponentPropsWithRef<typeof DisclosurePrimitive>, DisclosureVariants {}
+
+const DisclosureRoot = ({children, className, ...props}: DisclosureRootProps) => {
+  const slots = React.useMemo(() => disclosureVariants({}), []);
+
+  return (
+    <DisclosureContext value={{slots}}>
+      <DisclosurePrimitive
+        data-slot="disclosure"
+        {...props}
+        className={composeTwRenderProps(className, slots.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </DisclosurePrimitive>
+    </DisclosureContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Heading
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureHeadingProps extends ComponentPropsWithRef<typeof DisclosureHeadingPrimitive> {
+  className?: string;
+}
+
+const DisclosureHeading = ({className, ...props}: DisclosureHeadingProps) => {
+  const {slots} = use(DisclosureContext);
+
+  return (
+    <DisclosureHeadingPrimitive
+      className={composeSlotClassName(slots?.heading, className)}
+      data-slot="disclosure-heading"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureTriggerProps extends ButtonProps {}
+
+const DisclosureTrigger = ({className, ...props}: DisclosureTriggerProps) => {
+  const {slots} = use(DisclosureContext);
+
+  return (
+    <Button
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="disclosure-trigger"
+      slot="trigger"
+      {...props}
+    >
+      {(values) => (
+        <>{typeof props.children === "function" ? props.children(values) : props.children}</>
+      )}
+    </Button>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Content
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureContentProps extends ComponentPropsWithRef<typeof DisclosurePanel> {}
+
+const DisclosureContent = ({children, className, ...props}: DisclosureContentProps) => {
+  const {slots} = use(DisclosureContext);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const {isExpanded} = use(DisclosureStateContext)!;
+
+  return (
+    <DisclosurePanel
+      ref={contentRef}
+      className={composeTwRenderProps(className, slots?.content())}
+      data-expanded={dataAttr(isExpanded)}
+      data-slot="disclosure-content"
+      {...props}
+    >
+      {children}
+    </DisclosurePanel>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Body
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureBodyContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DisclosureBody = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DisclosureBodyContentProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DisclosureBodyContentProps<E>>) => {
+  const {slots} = use(DisclosureContext);
+
+  return (
+    <dom.div className={slots?.body({})} data-slot="disclosure-body" {...(props as any)}>
+      <div className={composeSlotClassName(slots?.bodyInner, className)}>{children}</div>
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disclosure Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface DisclosureIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DisclosureIndicator = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: DisclosureIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof DisclosureIndicatorProps<E>>) => {
+  const {isExpanded} = use(DisclosureStateContext)!;
+  const {slots} = use(DisclosureContext);
+
+  if (children && React.isValidElement(children)) {
+    return React.cloneElement(
+      children as React.ReactElement<{
+        className?: string;
+        "data-slot"?: "disclosure-indicator";
+        "data-expanded"?: Booleanish;
+      }>,
+      {
+        ...(props as any),
+        "data-expanded": dataAttr(isExpanded),
+        className: composeSlotClassName(slots?.indicator, className),
+        "data-slot": "disclosure-indicator",
+      },
+    );
+  }
+
+  return (
+    <IconChevronDown
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-expanded={dataAttr(isExpanded)}
+      data-slot="disclosure-indicator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DisclosureRoot,
+  DisclosureHeading,
+  DisclosureTrigger,
+  DisclosureContent,
+  DisclosureBody,
+  DisclosureIndicator,
+};
+
+export type {
+  DisclosureRootProps,
+  DisclosureContentProps,
+  DisclosureHeadingProps,
+  DisclosureTriggerProps,
+  DisclosureIndicatorProps,
+  DisclosureBodyContentProps,
+};
diff --git a/packages/react/src/components/disclosure/index.ts b/packages/react/src/components/disclosure/index.ts
new file mode 100644
index 0000000..ae28995
--- /dev/null
+++ b/packages/react/src/components/disclosure/index.ts
@@ -0,0 +1,61 @@
+import type {ComponentProps} from "react";
+
+import {
+  DisclosureBody,
+  DisclosureContent,
+  DisclosureHeading,
+  DisclosureIndicator,
+  DisclosureRoot,
+  DisclosureTrigger,
+} from "./disclosure";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Disclosure = Object.assign(DisclosureRoot, {
+  Root: DisclosureRoot,
+  Heading: DisclosureHeading,
+  Trigger: DisclosureTrigger,
+  Content: DisclosureContent,
+  Body: DisclosureBody,
+  Indicator: DisclosureIndicator,
+});
+
+export type Disclosure = {
+  Props: ComponentProps<typeof DisclosureRoot>;
+  RootProps: ComponentProps<typeof DisclosureRoot>;
+  HeadingProps: ComponentProps<typeof DisclosureHeading>;
+  TriggerProps: ComponentProps<typeof DisclosureTrigger>;
+  ContentProps: ComponentProps<typeof DisclosureContent>;
+  BodyProps: ComponentProps<typeof DisclosureBody>;
+  IndicatorProps: ComponentProps<typeof DisclosureIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DisclosureRoot,
+  DisclosureHeading,
+  DisclosureTrigger,
+  DisclosureContent,
+  DisclosureBody,
+  DisclosureIndicator,
+};
+
+export type {
+  DisclosureRootProps,
+  DisclosureRootProps as DisclosureProps,
+  DisclosureContentProps,
+  DisclosureHeadingProps,
+  DisclosureTriggerProps,
+  DisclosureIndicatorProps,
+  DisclosureBodyContentProps,
+} from "./disclosure";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {disclosureVariants} from "@heroui/styles";
+
+export type {DisclosureVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/drawer/drawer.stories.tsx b/packages/react/src/components/drawer/drawer.stories.tsx
new file mode 100644
index 0000000..8821b4f
--- /dev/null
+++ b/packages/react/src/components/drawer/drawer.stories.tsx
@@ -0,0 +1,308 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {Input} from "../input";
+import {Label} from "../label";
+import {TextField} from "../textfield";
+
+import {Drawer} from "./index";
+
+export default {
+  argTypes: {},
+  component: Drawer,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Overlays/Drawer",
+} as Meta<typeof Drawer>;
+
+export const Default = () => {
+  return (
+    <Drawer>
+      <Button variant="secondary">Open Drawer</Button>
+      <Drawer.Backdrop>
+        <Drawer.Content>
+          <Drawer.Dialog>
+            <Drawer.Handle />
+            <Drawer.Header>
+              <Drawer.Heading>Drawer Title</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>
+                This is a bottom drawer built with React Aria's Modal component. It slides up from
+                the bottom of the screen with a smooth CSS transition.
+              </p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Cancel
+              </Button>
+              <Button slot="close">Confirm</Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+};
+
+export const Placements = () => {
+  const placements = ["bottom", "top", "left", "right"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Drawer key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <Drawer.Backdrop>
+            <Drawer.Content placement={placement}>
+              <Drawer.Dialog>
+                <Drawer.CloseTrigger />
+                {placement === "bottom" && <Drawer.Handle />}
+                <Drawer.Header>
+                  <Drawer.Heading>
+                    {placement.charAt(0).toUpperCase() + placement.slice(1)} Drawer
+                  </Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    This drawer slides in from the <strong>{placement}</strong> edge of the screen.
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button slot="close" variant="secondary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Done</Button>
+                </Drawer.Footer>
+                {placement === "top" && <Drawer.Handle />}
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+};
+
+export const BackdropVariants = () => {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Drawer key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <Drawer.Backdrop variant={variant}>
+            <Drawer.Content>
+              <Drawer.Dialog>
+                <Drawer.Handle />
+                <Drawer.CloseTrigger />
+                <Drawer.Header>
+                  <Drawer.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </Drawer.Heading>
+                </Drawer.Header>
+                <Drawer.Body>
+                  <p>
+                    This drawer uses the <code>{variant}</code> backdrop variant.
+                  </p>
+                </Drawer.Body>
+                <Drawer.Footer>
+                  <Button className="w-full" slot="close">
+                    Close
+                  </Button>
+                </Drawer.Footer>
+              </Drawer.Dialog>
+            </Drawer.Content>
+          </Drawer.Backdrop>
+        </Drawer>
+      ))}
+    </div>
+  );
+};
+
+export const WithForm = () => (
+  <Drawer>
+    <Button variant="secondary">Edit Profile</Button>
+    <Drawer.Backdrop>
+      <Drawer.Content placement="right">
+        <Drawer.Dialog>
+          <Drawer.CloseTrigger />
+          <Drawer.Header>
+            <Drawer.Heading>Edit Profile</Drawer.Heading>
+          </Drawer.Header>
+          <Drawer.Body>
+            <form className="flex flex-col gap-4">
+              <TextField className="w-full" name="name" type="text">
+                <Label>Name</Label>
+                <Input placeholder="Enter your name" variant="secondary" />
+              </TextField>
+              <TextField className="w-full" name="email" type="email">
+                <Label>Email</Label>
+                <Input placeholder="Enter your email" variant="secondary" />
+              </TextField>
+              <TextField className="w-full" name="bio">
+                <Label>Bio</Label>
+                <Input placeholder="Tell us about yourself" variant="secondary" />
+              </TextField>
+            </form>
+          </Drawer.Body>
+          <Drawer.Footer>
+            <Button slot="close" variant="secondary">
+              Cancel
+            </Button>
+            <Button slot="close">Save Changes</Button>
+          </Drawer.Footer>
+        </Drawer.Dialog>
+      </Drawer.Content>
+    </Drawer.Backdrop>
+  </Drawer>
+);
+
+export const WithScrollableContent = () => (
+  <Drawer>
+    <Button variant="secondary">Terms & Conditions</Button>
+    <Drawer.Backdrop>
+      <Drawer.Content>
+        <Drawer.Dialog>
+          <Drawer.Handle />
+          <Drawer.CloseTrigger />
+          <Drawer.Header>
+            <Drawer.Heading>Terms & Conditions</Drawer.Heading>
+          </Drawer.Header>
+          <Drawer.Body>
+            {Array.from({length: 20}).map((_, i) => (
+              <p key={i} className="mb-3">
+                Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam
+                pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus,
+                sed porttitor quam.
+              </p>
+            ))}
+          </Drawer.Body>
+          <Drawer.Footer>
+            <Button slot="close" variant="secondary">
+              Decline
+            </Button>
+            <Button slot="close">Accept</Button>
+          </Drawer.Footer>
+        </Drawer.Dialog>
+      </Drawer.Content>
+    </Drawer.Backdrop>
+  </Drawer>
+);
+
+export const NavigationDrawer = () => {
+  const navItems = [
+    {icon: "gravity-ui:house", label: "Home"},
+    {icon: "gravity-ui:magnifier", label: "Search"},
+    {icon: "gravity-ui:bell", label: "Notifications"},
+    {icon: "gravity-ui:envelope", label: "Messages"},
+    {icon: "gravity-ui:person", label: "Profile"},
+    {icon: "gravity-ui:gear", label: "Settings"},
+  ];
+
+  return (
+    <Drawer>
+      <Button variant="secondary">
+        <Icon icon="gravity-ui:bars" />
+        Menu
+      </Button>
+      <Drawer.Backdrop>
+        <Drawer.Content placement="left">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Navigation</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <nav className="flex flex-col gap-1">
+                {navItems.map((item) => (
+                  <button
+                    key={item.label}
+                    className="flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm text-foreground transition-colors hover:bg-default"
+                    type="button"
+                  >
+                    <Icon className="size-5 text-muted" icon={item.icon} />
+                    {item.label}
+                  </button>
+                ))}
+              </nav>
+            </Drawer.Body>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </Drawer>
+  );
+};
+
+export const NonDismissable = () => (
+  <Drawer>
+    <Button variant="secondary">Important Action</Button>
+    <Drawer.Backdrop isDismissable={false}>
+      <Drawer.Content>
+        <Drawer.Dialog>
+          <Drawer.Header>
+            <Drawer.Heading>Confirm Action</Drawer.Heading>
+          </Drawer.Header>
+          <Drawer.Body>
+            <p>
+              This drawer cannot be dismissed by clicking outside. You must use one of the buttons
+              below.
+            </p>
+          </Drawer.Body>
+          <Drawer.Footer>
+            <Button slot="close" variant="secondary">
+              Cancel
+            </Button>
+            <Button slot="close">Confirm</Button>
+          </Drawer.Footer>
+        </Drawer.Dialog>
+      </Drawer.Content>
+    </Drawer.Backdrop>
+  </Drawer>
+);
+
+export const Controlled = () => {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-3">
+        <Button variant="secondary" onPress={() => setIsOpen(true)}>
+          Open Drawer
+        </Button>
+        <p className="text-sm text-muted">
+          Status:{" "}
+          <span className="font-mono font-medium text-foreground">
+            {isOpen ? "open" : "closed"}
+          </span>
+        </p>
+      </div>
+
+      <Drawer.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Drawer.Content placement="right">
+          <Drawer.Dialog>
+            <Drawer.CloseTrigger />
+            <Drawer.Header>
+              <Drawer.Heading>Controlled Drawer</Drawer.Heading>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>This drawer is controlled externally via React state.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button slot="close" variant="secondary">
+                Close
+              </Button>
+            </Drawer.Footer>
+          </Drawer.Dialog>
+        </Drawer.Content>
+      </Drawer.Backdrop>
+    </div>
+  );
+};
diff --git a/packages/react/src/components/drawer/drawer.tsx b/packages/react/src/components/drawer/drawer.tsx
new file mode 100644
index 0000000..b4ffe0d
--- /dev/null
+++ b/packages/react/src/components/drawer/drawer.tsx
@@ -0,0 +1,577 @@
+"use client";
+
+import type {UseOverlayStateProps, UseOverlayStateReturn} from "../../hooks/use-overlay-state";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {DrawerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {ButtonProps as ButtonPrimitiveProps} from "react-aria-components/Button";
+import type {DialogProps as DialogPrimitiveProps} from "react-aria-components/Dialog";
+
+import {drawerVariants} from "@heroui/styles";
+import {mergeProps} from "@react-aria/utils";
+import React, {createContext, use, useCallback, useMemo, useRef} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {
+  Dialog as DialogPrimitive,
+  DialogTrigger as DrawerTriggerPrimitive,
+  Heading as HeadingPrimitive,
+  OverlayTriggerStateContext,
+} from "react-aria-components/Dialog";
+import {
+  ModalOverlay as ModalOverlayPrimitive,
+  Modal as ModalPrimitive,
+} from "react-aria-components/Modal";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CloseButton} from "../close-button";
+import {SurfaceContext} from "../surface";
+
+type DrawerPlacement = "top" | "bottom" | "left" | "right";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Drag Hook
+ * Tracks pointer events to enable drag-to-dismiss with CSS transforms.
+ * Drag only initiates from handle/header/footer areas — body is excluded to avoid scroll conflicts.
+ * -----------------------------------------------------------------------------------------------*/
+
+const DRAG_THRESHOLD = 8; // px before drag activates
+const DISMISS_FRACTION = 0.3; // dismiss if dragged > 30% of dimension
+const VELOCITY_THRESHOLD = 0.5; // px/ms — dismiss on fast flick
+
+function useDrawerDrag(placement: DrawerPlacement | undefined, isDismissable: boolean) {
+  const overlayState = use(OverlayTriggerStateContext);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+  const isActive = useRef(false);
+  const startPos = useRef(0);
+  const currentOffset = useRef(0);
+  const velocity = useRef(0);
+  const lastTime = useRef(0);
+  const lastPos = useRef(0);
+
+  const isVertical = placement === "top" || placement === "bottom";
+
+  const getPos = useCallback(
+    (e: React.PointerEvent) => (isVertical ? e.clientY : e.clientX),
+    [isVertical],
+  );
+
+  const clamp = useCallback(
+    (delta: number) => {
+      // Only allow drag in the dismiss direction
+      switch (placement) {
+        case "bottom":
+          return Math.max(0, delta);
+        case "top":
+          return Math.min(0, delta);
+        case "right":
+          return Math.max(0, delta);
+        case "left":
+          return Math.min(0, delta);
+        default:
+          return delta;
+      }
+    },
+    [placement],
+  );
+
+  const onPointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      if (!isDismissable) return;
+      if (e.button !== 0) return;
+
+      const target = e.target as HTMLElement;
+
+      // Don't drag from interactive elements or scrollable body
+      if (
+        target.closest(
+          "input, textarea, button, [role='button'], select, a, [data-slot='drawer-body']",
+        )
+      ) {
+        return;
+      }
+
+      isDragging.current = true;
+      isActive.current = false;
+      startPos.current = getPos(e);
+      lastPos.current = startPos.current;
+      lastTime.current = Date.now();
+      currentOffset.current = 0;
+      velocity.current = 0;
+    },
+    [getPos, isDismissable],
+  );
+
+  const onPointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      if (!isDragging.current || !dialogRef.current) return;
+
+      const pos = getPos(e);
+      const rawDelta = pos - startPos.current;
+      const delta = clamp(rawDelta);
+
+      // Activate only after passing threshold to avoid false starts
+      if (!isActive.current) {
+        if (Math.abs(rawDelta) < DRAG_THRESHOLD) return;
+        isActive.current = true;
+        dialogRef.current.style.transition = "none";
+        dialogRef.current.setPointerCapture(e.pointerId);
+      }
+
+      currentOffset.current = delta;
+
+      // Track velocity for flick detection
+      const now = Date.now();
+      const dt = now - lastTime.current;
+
+      if (dt > 0) {
+        velocity.current = (pos - lastPos.current) / dt;
+        lastTime.current = now;
+        lastPos.current = pos;
+      }
+
+      const axis = isVertical ? "Y" : "X";
+
+      dialogRef.current.style.transform = `translate${axis}(${delta}px)`;
+    },
+    [getPos, clamp, isVertical],
+  );
+
+  const onPointerUp = useCallback(
+    (e: React.PointerEvent) => {
+      if (!isDragging.current) return;
+      isDragging.current = false;
+
+      const el = dialogRef.current;
+
+      if (!el || !isActive.current) {
+        isActive.current = false;
+
+        return;
+      }
+      isActive.current = false;
+
+      // Release pointer capture
+      try {
+        el.releasePointerCapture(e.pointerId);
+      } catch {
+        // Pointer capture may already be released
+      }
+
+      const dimension = isVertical ? el.offsetHeight : el.offsetWidth;
+      const absOffset = Math.abs(currentOffset.current);
+      const absVelocity = Math.abs(velocity.current);
+
+      const shouldDismiss =
+        absOffset > dimension * DISMISS_FRACTION || absVelocity > VELOCITY_THRESHOLD;
+
+      if (shouldDismiss && overlayState) {
+        // Keep the inline transform — it compounds with the content exit animation
+        // so the drawer continues sliding from the dragged position
+        overlayState.close();
+      } else {
+        // Snap back with a spring-like ease
+        el.style.transition = "transform 300ms cubic-bezier(0.32, 0.72, 0, 1)";
+        el.style.transform = "";
+
+        const cleanup = () => {
+          el.style.transition = "";
+        };
+
+        el.addEventListener("transitionend", cleanup, {once: true});
+      }
+
+      currentOffset.current = 0;
+      velocity.current = 0;
+    },
+    [isVertical, overlayState],
+  );
+
+  return {
+    dialogRef,
+    dragHandlers: isDismissable
+      ? {
+          onPointerDown,
+          onPointerMove,
+          onPointerUp,
+        }
+      : {},
+  };
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Context
+ * -----------------------------------------------------------------------------------------------*/
+type DrawerContext = {
+  slots?: ReturnType<typeof drawerVariants>;
+  placement?: DrawerPlacement;
+  isDismissable?: boolean;
+};
+
+const DrawerContext = createContext<DrawerContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Root
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerRootProps extends ComponentPropsWithRef<typeof DrawerTriggerPrimitive> {
+  state?: UseOverlayStateReturn;
+}
+
+const DrawerRoot = ({children, state, ...props}: DrawerRootProps) => {
+  const drawerContext = useMemo<DrawerContext>(
+    () => ({slots: drawerVariants(), placement: undefined, isDismissable: true}),
+    [],
+  );
+
+  const controlledProps = useMemo<UseOverlayStateProps>(
+    () => (state ? {isOpen: state.isOpen, onOpenChange: state.setOpen} : {}),
+    [state],
+  );
+
+  return (
+    <DrawerContext value={drawerContext}>
+      <DrawerTriggerPrimitive data-slot="drawer-root" {...mergeProps(props, controlledProps)}>
+        {children}
+      </DrawerTriggerPrimitive>
+    </DrawerContext>
+  );
+};
+
+DrawerRoot.displayName = "HeroUI.Drawer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const DrawerTrigger = ({children, className, ...props}: DrawerTriggerProps) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="drawer-trigger"
+      {...props}
+    >
+      {children}
+    </ButtonPrimitive>
+  );
+};
+
+DrawerTrigger.displayName = "HeroUI.Drawer.Trigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Backdrop
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerBackdropProps extends ComponentPropsWithRef<typeof ModalOverlayPrimitive> {
+  variant?: DrawerVariants["variant"];
+  /**
+   * Whether to close the drawer when the user interacts outside it.
+   * @default true
+   */
+  isDismissable?: boolean;
+}
+
+const DrawerBackdrop = ({
+  children,
+  className,
+  isDismissable = true,
+  variant,
+  ...props
+}: DrawerBackdropProps) => {
+  const {slots: contextSlots} = use(DrawerContext);
+
+  const updatedSlots = useMemo(() => drawerVariants({variant}), [variant]);
+
+  const updatedDrawerContext = useMemo<DrawerContext>(
+    () => ({slots: {...contextSlots, ...updatedSlots}, isDismissable}),
+    [contextSlots, updatedSlots, isDismissable],
+  );
+
+  return (
+    <ModalOverlayPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.backdrop())}
+      data-slot="drawer-backdrop"
+      isDismissable={isDismissable}
+      {...props}
+    >
+      {(renderProps) => (
+        <DrawerContext value={updatedDrawerContext}>
+          {typeof children === "function" ? children(renderProps) : children}
+        </DrawerContext>
+      )}
+    </ModalOverlayPrimitive>
+  );
+};
+
+DrawerBackdrop.displayName = "HeroUI.Drawer.Backdrop";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Content
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerContentProps extends Omit<
+  ComponentPropsWithRef<typeof ModalPrimitive>,
+  Exclude<keyof DrawerBackdropProps, "children" | "className">
+> {
+  placement?: DrawerPlacement;
+}
+
+const DrawerContent = ({
+  children,
+  className,
+  placement = "bottom",
+  ...props
+}: DrawerContentProps) => {
+  const {isDismissable, slots: contextSlots} = use(DrawerContext);
+
+  const updatedSlots = useMemo(() => drawerVariants({placement}), [placement]);
+
+  const updatedDrawerContext = useMemo<DrawerContext>(
+    () => ({placement, isDismissable, slots: {...contextSlots, ...updatedSlots}}),
+    [contextSlots, placement, isDismissable, updatedSlots],
+  );
+
+  return (
+    <ModalPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.content())}
+      data-placement={placement}
+      data-slot="drawer-content"
+      {...props}
+    >
+      {(renderProps) => (
+        <DrawerContext value={updatedDrawerContext}>
+          {typeof children === "function" ? children(renderProps) : children}
+        </DrawerContext>
+      )}
+    </ModalPrimitive>
+  );
+};
+
+DrawerContent.displayName = "HeroUI.Drawer.Content";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Dialog
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerDialogProps extends DialogPrimitiveProps {}
+
+const DrawerDialog = ({children, className, ...props}: DrawerDialogProps) => {
+  const {isDismissable = true, placement, slots} = use(DrawerContext);
+  const {dialogRef, dragHandlers} = useDrawerDrag(placement, isDismissable);
+
+  return (
+    <SurfaceContext value={{variant: "default" as SurfaceVariants["variant"]}}>
+      <DialogPrimitive
+        ref={dialogRef}
+        className={composeSlotClassName(slots?.dialog, className)}
+        data-placement={placement}
+        data-slot="drawer-dialog"
+        style={isDismissable ? {touchAction: "none"} : undefined}
+        {...dragHandlers}
+        {...props}
+      >
+        {children}
+      </DialogPrimitive>
+    </SurfaceContext>
+  );
+};
+
+DrawerDialog.displayName = "HeroUI.Drawer.Dialog";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Header
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerHeaderProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DrawerHeader = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DrawerHeaderProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof DrawerHeaderProps<E>>) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="drawer-header"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+DrawerHeader.displayName = "HeroUI.Drawer.Header";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Body
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerBodyProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DrawerBody = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DrawerBodyProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof DrawerBodyProps<E>>) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.body, className)}
+      data-slot="drawer-body"
+      style={{touchAction: "pan-y"}}
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+DrawerBody.displayName = "HeroUI.Drawer.Body";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Footer
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerFooterProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DrawerFooter = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: DrawerFooterProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof DrawerFooterProps<E>>) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.footer, className)}
+      data-slot="drawer-footer"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+DrawerFooter.displayName = "HeroUI.Drawer.Footer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Heading
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerHeadingProps extends ComponentPropsWithRef<typeof HeadingPrimitive> {}
+
+const DrawerHeading = ({children, className, ...props}: DrawerHeadingProps) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <HeadingPrimitive
+      className={composeSlotClassName(slots?.heading, className)}
+      data-slot="drawer-heading"
+      slot="title"
+      {...props}
+    >
+      {children}
+    </HeadingPrimitive>
+  );
+};
+
+DrawerHeading.displayName = "HeroUI.Drawer.Heading";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Handle
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerHandleProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const DrawerHandle = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: DrawerHandleProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof DrawerHandleProps<E>>) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <dom.div
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.handle, className)}
+      data-slot="drawer-handle"
+      {...(props as any)}
+    >
+      <div data-slot="drawer-handle-bar" />
+    </dom.div>
+  );
+};
+
+DrawerHandle.displayName = "HeroUI.Drawer.Handle";
+
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Close Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DrawerCloseTriggerProps extends ButtonPrimitiveProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+const DrawerCloseTrigger = ({className, ...rest}: DrawerCloseTriggerProps) => {
+  const {slots} = use(DrawerContext);
+
+  return (
+    <CloseButton
+      className={composeTwRenderProps(className, slots?.closeTrigger())}
+      data-slot="drawer-close-trigger"
+      slot="close"
+      {...rest}
+    />
+  );
+};
+
+DrawerCloseTrigger.displayName = "HeroUI.Drawer.CloseTrigger";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DrawerRoot,
+  DrawerTrigger,
+  DrawerBackdrop,
+  DrawerContent,
+  DrawerDialog,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerBody,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerCloseTrigger,
+};
+
+export type {
+  DrawerRootProps,
+  DrawerTriggerProps,
+  DrawerBackdropProps,
+  DrawerContentProps,
+  DrawerDialogProps,
+  DrawerHeaderProps,
+  DrawerHeadingProps,
+  DrawerBodyProps,
+  DrawerFooterProps,
+  DrawerHandleProps,
+  DrawerCloseTriggerProps,
+};
diff --git a/packages/react/src/components/drawer/index.ts b/packages/react/src/components/drawer/index.ts
new file mode 100644
index 0000000..7e25218
--- /dev/null
+++ b/packages/react/src/components/drawer/index.ts
@@ -0,0 +1,86 @@
+import type {ComponentProps} from "react";
+
+import {
+  DrawerBackdrop,
+  DrawerBody,
+  DrawerCloseTrigger,
+  DrawerContent,
+  DrawerDialog,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerRoot,
+  DrawerTrigger,
+} from "./drawer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Drawer = Object.assign(DrawerRoot, {
+  Root: DrawerRoot,
+  Trigger: DrawerTrigger,
+  Backdrop: DrawerBackdrop,
+  Content: DrawerContent,
+  Dialog: DrawerDialog,
+  Header: DrawerHeader,
+  Heading: DrawerHeading,
+  Body: DrawerBody,
+  Footer: DrawerFooter,
+  Handle: DrawerHandle,
+  CloseTrigger: DrawerCloseTrigger,
+});
+
+export type Drawer = {
+  Props: ComponentProps<typeof DrawerRoot>;
+  RootProps: ComponentProps<typeof DrawerRoot>;
+  TriggerProps: ComponentProps<typeof DrawerTrigger>;
+  BackdropProps: ComponentProps<typeof DrawerBackdrop>;
+  ContentProps: ComponentProps<typeof DrawerContent>;
+  DialogProps: ComponentProps<typeof DrawerDialog>;
+  HeaderProps: ComponentProps<typeof DrawerHeader>;
+  HeadingProps: ComponentProps<typeof DrawerHeading>;
+  BodyProps: ComponentProps<typeof DrawerBody>;
+  FooterProps: ComponentProps<typeof DrawerFooter>;
+  HandleProps: ComponentProps<typeof DrawerHandle>;
+  CloseTriggerProps: ComponentProps<typeof DrawerCloseTrigger>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DrawerRoot,
+  DrawerTrigger,
+  DrawerBackdrop,
+  DrawerContent,
+  DrawerDialog,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerBody,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerCloseTrigger,
+};
+
+export type {
+  DrawerRootProps,
+  DrawerRootProps as DrawerProps,
+  DrawerTriggerProps,
+  DrawerBackdropProps,
+  DrawerContentProps,
+  DrawerDialogProps,
+  DrawerHeaderProps,
+  DrawerHeadingProps,
+  DrawerBodyProps,
+  DrawerFooterProps,
+  DrawerHandleProps,
+  DrawerCloseTriggerProps,
+} from "./drawer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {drawerVariants} from "@heroui/styles";
+
+export type {DrawerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/dropdown/dropdown.stories.tsx b/packages/react/src/components/dropdown/dropdown.stories.tsx
new file mode 100644
index 0000000..52e682a
--- /dev/null
+++ b/packages/react/src/components/dropdown/dropdown.stories.tsx
@@ -0,0 +1,905 @@
+import type {Selection} from "@react-types/shared";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import * as React from "react";
+
+import {Avatar} from "../avatar";
+import {Button} from "../button";
+import {Description} from "../description";
+import {Header} from "../header";
+import {Kbd} from "../kbd";
+import {Label} from "../label";
+import {Separator} from "../separator";
+
+import {Dropdown} from "./index";
+
+const meta: Meta<typeof Dropdown> = {
+  component: Dropdown,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Collections/Dropdown",
+};
+
+export default meta;
+type Story = StoryObj<typeof Dropdown>;
+
+export const Default: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Section>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <Label>New file</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="copy-link" textValue="Copy link">
+              <Label>Copy link</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="Edit file">
+              <Label>Edit file</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <Label>Delete file</Label>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithSingleSelection: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Selection>(new Set(["apple"]));
+
+    return (
+      <Dropdown>
+        <Button aria-label="Menu" variant="secondary">
+          Fruit
+        </Button>
+        <Dropdown.Popover className="min-w-[256px]">
+          <Dropdown.Menu
+            selectedKeys={selected}
+            selectionMode="single"
+            onSelectionChange={setSelected}
+          >
+            <Dropdown.Section>
+              <Header>Select a fruit</Header>
+              <Dropdown.Item id="apple" textValue="Apple">
+                <Dropdown.ItemIndicator />
+                <Label>Apple</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="banana" textValue="Banana">
+                <Dropdown.ItemIndicator />
+                <Label>Banana</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="cherry" textValue="Cherry">
+                <Dropdown.ItemIndicator />
+                <Label>Cherry</Label>
+              </Dropdown.Item>
+            </Dropdown.Section>
+            <Dropdown.Item id="orange" textValue="Orange">
+              <Dropdown.ItemIndicator />
+              <Label>Orange</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="pear" textValue="Pear">
+              <Dropdown.ItemIndicator />
+              <Label>Pear</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    );
+  },
+};
+
+export const SingleWithCustomIndicator: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Selection>(new Set(["apple"]));
+
+    const CustomCheckmarkIcon = (
+      <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+        <path
+          className="text-accent"
+          clipRule="evenodd"
+          d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m3.1-8.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
+          fill="currentColor"
+          fillRule="evenodd"
+        />
+      </svg>
+    );
+
+    return (
+      <Dropdown>
+        <Button aria-label="Menu" variant="secondary">
+          Fruits
+        </Button>
+        <Dropdown.Popover className="min-w-[256px]">
+          <Dropdown.Menu
+            selectedKeys={selected}
+            selectionMode="single"
+            onSelectionChange={setSelected}
+          >
+            <Dropdown.Section>
+              <Header>Select a fruit</Header>
+              <Dropdown.Item id="apple" textValue="Apple">
+                <Dropdown.ItemIndicator>
+                  {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+                </Dropdown.ItemIndicator>
+                <Label>Apple</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="banana" textValue="Banana">
+                <Dropdown.ItemIndicator>
+                  {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+                </Dropdown.ItemIndicator>
+                <Label>Banana</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="cherry" textValue="Cherry">
+                <Dropdown.ItemIndicator>
+                  {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+                </Dropdown.ItemIndicator>
+                <Label>Cherry</Label>
+              </Dropdown.Item>
+            </Dropdown.Section>
+            <Dropdown.Item id="orange" textValue="Orange">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>Orange</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="pear" textValue="Pear">
+              <Dropdown.ItemIndicator>
+                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
+              </Dropdown.ItemIndicator>
+              <Label>Pear</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    );
+  },
+};
+
+export const WithMultipleSelection: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Selection>(new Set(["apple"]));
+
+    return (
+      <Dropdown>
+        <Button aria-label="Menu" variant="secondary">
+          Preferred Fruits
+        </Button>
+        <Dropdown.Popover className="min-w-[256px]">
+          <Dropdown.Menu
+            selectedKeys={selected}
+            selectionMode="multiple"
+            onSelectionChange={setSelected}
+          >
+            <Dropdown.Section>
+              <Header>Select a fruit</Header>
+              <Dropdown.Item id="apple" textValue="Apple">
+                <Dropdown.ItemIndicator />
+                <Label>Apple</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="banana" textValue="Banana">
+                <Dropdown.ItemIndicator />
+                <Label>Banana</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="cherry" textValue="Cherry">
+                <Dropdown.ItemIndicator />
+                <Label>Cherry</Label>
+              </Dropdown.Item>
+            </Dropdown.Section>
+            <Dropdown.Item id="orange" textValue="Orange">
+              <Dropdown.ItemIndicator />
+              <Label>Orange</Label>
+            </Dropdown.Item>
+            <Dropdown.Item id="pear" textValue="Pear">
+              <Dropdown.ItemIndicator />
+              <Label>Pear</Label>
+            </Dropdown.Item>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    );
+  },
+};
+
+export const WithSectionLevelSelection: Story = {
+  render: () => {
+    const [textStyles, setTextStyles] = React.useState<Selection>(new Set(["bold", "italic"]));
+    const [textAlignment, setTextAlignment] = React.useState<Selection>(new Set(["left"]));
+
+    return (
+      <Dropdown>
+        <Button aria-label="Menu" variant="secondary">
+          Styles
+        </Button>
+        <Dropdown.Popover className="min-w-[256px]">
+          <Dropdown.Menu>
+            <Dropdown.Section>
+              <Header>Actions</Header>
+              <Dropdown.Item id="cut" textValue="Cut">
+                <Label>Cut</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>X</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="copy" textValue="Copy">
+                <Label>Copy</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>C</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="paste" textValue="Paste">
+                <Label>Paste</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>U</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+            </Dropdown.Section>
+            <Separator />
+            <Dropdown.Section
+              selectedKeys={textStyles}
+              selectionMode="multiple"
+              onSelectionChange={setTextStyles}
+            >
+              <Header>Text Style</Header>
+              <Dropdown.Item id="bold" textValue="Bold">
+                <Dropdown.ItemIndicator />
+                <Label>Bold</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>B</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="italic" textValue="Italic">
+                <Dropdown.ItemIndicator />
+                <Label>Italic</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>I</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="underline" textValue="Underline">
+                <Dropdown.ItemIndicator />
+                <Label>Underline</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="command" />
+                  <Kbd.Content>U</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+            </Dropdown.Section>
+            <Separator />
+            <Dropdown.Section
+              selectedKeys={textAlignment}
+              selectionMode="single"
+              onSelectionChange={setTextAlignment}
+            >
+              <Header>Text Alignment</Header>
+              <Dropdown.Item id="left" textValue="Left">
+                <Dropdown.ItemIndicator type="dot" />
+                <Label>Left</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="alt" />
+                  <Kbd.Content>A</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="center" textValue="Center">
+                <Dropdown.ItemIndicator type="dot" />
+                <Label>Center</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="alt" />
+                  <Kbd.Content>H</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+              <Dropdown.Item id="right" textValue="Right">
+                <Dropdown.ItemIndicator type="dot" />
+                <Label>Right</Label>
+                <Kbd className="ms-auto" slot="keyboard" variant="light">
+                  <Kbd.Abbr keyValue="alt" />
+                  <Kbd.Content>D</Kbd.Content>
+                </Kbd>
+              </Dropdown.Item>
+            </Dropdown.Section>
+          </Dropdown.Menu>
+        </Dropdown.Popover>
+      </Dropdown>
+    );
+  },
+};
+
+export const WithKeyboardShortcuts: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Item id="new" textValue="New">
+            <Label>New</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open" textValue="Open">
+            <Label>Open</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save" textValue="Save">
+            <Label>Save</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete" textValue="Delete" variant="danger">
+            <Label>Delete</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+            <Label>New file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:folder-open" />
+            <Label>Open file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:floppy-disk" />
+            <Label>Save file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+            <Label>Delete file</Label>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const LongPressTrigger: Story = {
+  render: () => (
+    <Dropdown trigger="longPress">
+      <Button aria-label="Menu" variant="secondary">
+        Long Press
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <Label>New file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <Label>Open file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <Label>Save file</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <Label>Delete file</Label>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithDescriptions: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Actions
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="open-file" textValue="Open file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:folder-open" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Open file</Label>
+              <Description>Open an existing file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>O</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="save-file" textValue="Save file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:floppy-disk" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Save file</Label>
+              <Description>Save the current file</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>S</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" slot="keyboard" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithSections: Story = {
+  render: () => (
+    <Dropdown>
+      <Dropdown.Trigger
+        aria-label="Menu"
+        className="button button-md button--secondary button--icon-only data-[focus-visible=true]:status-focused"
+      >
+        <Icon className="outline-none" icon="gravity-ui:ellipsis-vertical" />
+      </Dropdown.Trigger>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Section>
+            <Header>Actions</Header>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+              </div>
+              <div className="flex flex-col">
+                <Label>New file</Label>
+                <Description>Create a new file</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="Edit file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:pencil" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Edit file</Label>
+                <Description>Make changes</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>Danger zone</Header>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Delete file</Label>
+                <Description>Move to trash</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithDisabledItems: Story = {
+  render: () => (
+    <Dropdown>
+      <Button isIconOnly aria-label="Menu" variant="secondary">
+        <Icon className="outline-none" icon="gravity-ui:bars" />
+      </Button>
+      <Dropdown.Popover className="min-w-[220px]">
+        <Dropdown.Menu disabledKeys={["delete-file"]} onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Section>
+            <Header>Actions</Header>
+            <Dropdown.Item id="new-file" textValue="New file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+              </div>
+              <div className="flex flex-col">
+                <Label>New file</Label>
+                <Description>Create a new file</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>N</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+            <Dropdown.Item id="edit-file" textValue="Edit file">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:pencil" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Edit file</Label>
+                <Description>Make changes</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Content>E</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+          <Separator />
+          <Dropdown.Section>
+            <Header>Danger zone</Header>
+            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+              <div className="flex h-8 items-start justify-center pt-px">
+                <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+              </div>
+              <div className="flex flex-col">
+                <Label>Delete file</Label>
+                <Description>Move to trash</Description>
+              </div>
+              <Kbd className="ms-auto" slot="keyboard" variant="light">
+                <Kbd.Abbr keyValue="command" />
+                <Kbd.Abbr keyValue="shift" />
+                <Kbd.Content>D</Kbd.Content>
+              </Kbd>
+            </Dropdown.Item>
+          </Dropdown.Section>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithSubmenus: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Share
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="Copy Link">
+            <Label>Copy Link</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="twitter" textValue="Twitter">
+            <Label>X / Twitter</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="Share">
+              <Label>Other</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="Email">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator />
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="Work email">
+                        <Label>Work email</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="Personal email">
+                        <Label>Personal email</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const WithCustomSubmenuIndicator: Story = {
+  render: () => (
+    <Dropdown>
+      <Button aria-label="Menu" variant="secondary">
+        Share
+      </Button>
+      <Dropdown.Popover>
+        <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
+          <Dropdown.Item id="copy-link" textValue="Copy Link">
+            <Label>Copy Link</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="facebook" textValue="Facebook">
+            <Label>Facebook</Label>
+          </Dropdown.Item>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="share" textValue="Share">
+              <Label>More options</Label>
+              <Dropdown.SubmenuIndicator>
+                <Icon className="size-3.5 text-muted" icon="gravity-ui:arrow-right" />
+              </Dropdown.SubmenuIndicator>
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
+                  <Label>WhatsApp</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="telegram" textValue="Telegram">
+                  <Label>Telegram</Label>
+                </Dropdown.Item>
+                <Dropdown.SubmenuTrigger>
+                  <Dropdown.Item id="email" textValue="Email">
+                    <Label>Email</Label>
+                    <Dropdown.SubmenuIndicator>
+                      <svg
+                        className="size-3.5 text-muted"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth="2"
+                        viewBox="0 0 24 24"
+                      >
+                        <path d="M9 18l6-6-6-6" />
+                      </svg>
+                    </Dropdown.SubmenuIndicator>
+                  </Dropdown.Item>
+                  <Dropdown.Popover>
+                    <Dropdown.Menu>
+                      <Dropdown.Item id="work" textValue="Work email">
+                        <Label>Work email</Label>
+                      </Dropdown.Item>
+                      <Dropdown.Item id="personal" textValue="Personal email">
+                        <Label>Personal email</Label>
+                      </Dropdown.Item>
+                    </Dropdown.Menu>
+                  </Dropdown.Popover>
+                </Dropdown.SubmenuTrigger>
+                <Dropdown.Item id="discord" textValue="Discord">
+                  <Label>Discord</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+          <Dropdown.SubmenuTrigger>
+            <Dropdown.Item id="other" textValue="Other">
+              <Label>Other (default indicator)</Label>
+              <Dropdown.SubmenuIndicator />
+            </Dropdown.Item>
+            <Dropdown.Popover>
+              <Dropdown.Menu>
+                <Dropdown.Item id="sms" textValue="SMS">
+                  <Label>SMS</Label>
+                </Dropdown.Item>
+              </Dropdown.Menu>
+            </Dropdown.Popover>
+          </Dropdown.SubmenuTrigger>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Selection>(new Set(["bold"]));
+
+    const selectedItems = Array.from(selected);
+
+    return (
+      <div className="min-w-sm space-y-4">
+        <Dropdown>
+          <Button aria-label="Menu" variant="secondary">
+            Actions
+          </Button>
+          <Dropdown.Popover>
+            <Dropdown.Menu
+              selectedKeys={selected}
+              selectionMode="multiple"
+              onSelectionChange={setSelected}
+            >
+              <Dropdown.Item id="bold" textValue="Bold">
+                <Label>Bold</Label>
+                <Dropdown.ItemIndicator />
+              </Dropdown.Item>
+              <Dropdown.Item id="italic" textValue="Italic">
+                <Label>Italic</Label>
+                <Dropdown.ItemIndicator />
+              </Dropdown.Item>
+              <Dropdown.Item id="underline" textValue="Underline">
+                <Label>Underline</Label>
+                <Dropdown.ItemIndicator />
+              </Dropdown.Item>
+            </Dropdown.Menu>
+          </Dropdown.Popover>
+        </Dropdown>
+        <p className="text-sm text-muted">
+          Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
+        </p>
+      </div>
+    );
+  },
+};
+
+export const ControlledOpenState: Story = {
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+
+    return (
+      <div className="min-w-sm space-y-4">
+        <p className="text-sm text-muted">
+          Dropdown is: <strong>{open ? "open" : "closed"}</strong>
+        </p>
+        <Dropdown isOpen={open} onOpenChange={setOpen}>
+          <Button aria-label="Menu" variant="secondary">
+            Actions
+          </Button>
+          <Dropdown.Popover>
+            <Dropdown.Menu>
+              <Dropdown.Item id="new-file" textValue="New file">
+                <Label>New file</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="open-file" textValue="Open file">
+                <Label>Open file</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="save-file" textValue="Save file">
+                <Label>Save file</Label>
+              </Dropdown.Item>
+              <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
+                <Label>Delete file</Label>
+              </Dropdown.Item>
+            </Dropdown.Menu>
+          </Dropdown.Popover>
+        </Dropdown>
+      </div>
+    );
+  },
+};
+
+export const CustomTrigger: Story = {
+  render: () => (
+    <Dropdown>
+      <Dropdown.Trigger className="rounded-full">
+        <Avatar>
+          <Avatar.Image
+            alt="Junior Garcia"
+            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+          />
+          <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+        </Avatar>
+      </Dropdown.Trigger>
+      <Dropdown.Popover>
+        <div className="px-3 pt-3 pb-1">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image
+                alt="Jane"
+                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
+              />
+              <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col gap-0">
+              <p className="text-sm leading-5 font-medium">Jane Doe</p>
+              <p className="text-xs leading-none text-muted">jane@example.com</p>
+            </div>
+          </div>
+        </div>
+        <Dropdown.Menu>
+          <Dropdown.Item id="dashboard" textValue="Dashboard">
+            <Label>Dashboard</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="profile" textValue="Profile">
+            <Label>Profile</Label>
+          </Dropdown.Item>
+          <Dropdown.Item id="settings" textValue="Settings">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Settings</Label>
+              <Icon className="size-3.5 text-muted" icon="gravity-ui:gear" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="new-project" textValue="New project">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Create Team</Label>
+              <Icon className="size-3.5 text-muted" icon="gravity-ui:persons" />
+            </div>
+          </Dropdown.Item>
+          <Dropdown.Item id="logout" textValue="Logout" variant="danger">
+            <div className="flex w-full items-center justify-between gap-2">
+              <Label>Log Out</Label>
+              <Icon className="size-3.5 text-danger" icon="gravity-ui:arrow-right-from-square" />
+            </div>
+          </Dropdown.Item>
+        </Dropdown.Menu>
+      </Dropdown.Popover>
+    </Dropdown>
+  ),
+};
diff --git a/packages/react/src/components/dropdown/dropdown.tsx b/packages/react/src/components/dropdown/dropdown.tsx
new file mode 100644
index 0000000..b13b68e
--- /dev/null
+++ b/packages/react/src/components/dropdown/dropdown.tsx
@@ -0,0 +1,196 @@
+"use client";
+
+import type {SurfaceVariants} from "../surface";
+import type {DropdownVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {dropdownVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button} from "react-aria-components/Button";
+import {
+  Menu as MenuPrimitive,
+  MenuTrigger as MenuTriggerPrimitive,
+  Popover as PopoverPrimitive,
+  SubmenuTrigger as SubmenuTriggerPrimitive,
+} from "react-aria-components/Menu";
+
+import {composeTwRenderProps} from "../../utils/compose";
+import {MenuItemIndicator, MenuItemRoot, MenuItemSubmenuIndicator} from "../menu-item";
+import {MenuSectionRoot} from "../menu-section";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Context
+ * -----------------------------------------------------------------------------------------------*/
+type DropdownContext = {
+  slots?: ReturnType<typeof dropdownVariants>;
+};
+
+const DropdownContext = createContext<DropdownContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Root (MenuTrigger wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownRootProps
+  extends ComponentPropsWithRef<typeof MenuTriggerPrimitive>, DropdownVariants {
+  className?: string;
+}
+
+const DropdownRoot = ({children, ...props}: DropdownRootProps) => {
+  const slots = React.useMemo(() => dropdownVariants(), []);
+
+  return (
+    <DropdownContext value={{slots}}>
+      <MenuTriggerPrimitive {...props}>{children}</MenuTriggerPrimitive>
+    </DropdownContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Trigger (Button wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownTriggerProps extends ComponentPropsWithRef<typeof Button> {}
+
+const DropdownTrigger = ({children, className, ...props}: DropdownTriggerProps) => {
+  const {slots} = use(DropdownContext);
+
+  return (
+    <Button
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="dropdown-trigger"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </Button>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Popover (Popover wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownPopoverProps
+  extends Omit<ComponentPropsWithRef<typeof PopoverPrimitive>, "children">, DropdownVariants {
+  children: React.ReactNode;
+}
+
+const DropdownPopover = ({children, className, placement, ...props}: DropdownPopoverProps) => {
+  const {slots} = use(DropdownContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="dropdown-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Menu (Menu wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownMenuProps<T extends object>
+  extends ComponentPropsWithRef<typeof MenuPrimitive<T>>, DropdownVariants {
+  className?: string;
+}
+
+function DropdownMenu<T extends object>({className, ...props}: DropdownMenuProps<T>) {
+  const {slots} = use(DropdownContext);
+
+  return (
+    <MenuPrimitive
+      className={composeTwRenderProps(className, slots?.menu())}
+      data-selection-mode={props.selectionMode}
+      data-slot="dropdown-menu"
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Item (MenuItem wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownItemProps extends ComponentPropsWithRef<typeof MenuItemRoot> {}
+
+const DropdownItem = (props: DropdownItemProps) => {
+  return <MenuItemRoot {...props} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Submenu Indicator (MenuItemSubmenuIndicator wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownSubmenuIndicatorProps extends ComponentPropsWithRef<
+  typeof MenuItemSubmenuIndicator
+> {}
+
+const DropdownSubmenuIndicator = (props: DropdownSubmenuIndicatorProps) => {
+  return <MenuItemSubmenuIndicator {...props} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Submenu Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownSubmenuTriggerProps extends ComponentPropsWithRef<
+  typeof SubmenuTriggerPrimitive
+> {}
+
+const DropdownSubmenuTrigger = ({children, ...props}: DropdownSubmenuTriggerProps) => {
+  return (
+    <SubmenuTriggerPrimitive data-slot="dropdown-submenu-trigger" {...props}>
+      {children}
+    </SubmenuTriggerPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Item Indicator (MenuItemIndicator wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownItemIndicatorProps extends ComponentPropsWithRef<typeof MenuItemIndicator> {}
+
+const DropdownItemIndicator = (props: DropdownItemIndicatorProps) => {
+  return <MenuItemIndicator {...props} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Dropdown Section (MenuSection wrapper)
+ * -----------------------------------------------------------------------------------------------*/
+interface DropdownSectionProps extends ComponentPropsWithRef<typeof MenuSectionRoot> {}
+
+const DropdownSection = (props: DropdownSectionProps) => {
+  return <MenuSectionRoot {...props} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DropdownItem,
+  DropdownItemIndicator,
+  DropdownMenu,
+  DropdownPopover,
+  DropdownRoot,
+  DropdownSection,
+  DropdownSubmenuIndicator,
+  DropdownSubmenuTrigger,
+  DropdownTrigger,
+};
+
+export type {
+  DropdownItemIndicatorProps,
+  DropdownItemProps,
+  DropdownMenuProps,
+  DropdownPopoverProps,
+  DropdownRootProps,
+  DropdownSectionProps,
+  DropdownSubmenuIndicatorProps,
+  DropdownSubmenuTriggerProps,
+  DropdownTriggerProps,
+};
diff --git a/packages/react/src/components/dropdown/index.ts b/packages/react/src/components/dropdown/index.ts
new file mode 100644
index 0000000..d67f717
--- /dev/null
+++ b/packages/react/src/components/dropdown/index.ts
@@ -0,0 +1,76 @@
+import type {ComponentProps} from "react";
+
+import {
+  DropdownItem,
+  DropdownItemIndicator,
+  DropdownMenu,
+  DropdownPopover,
+  DropdownRoot,
+  DropdownSection,
+  DropdownSubmenuIndicator,
+  DropdownSubmenuTrigger,
+  DropdownTrigger,
+} from "./dropdown";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Dropdown = Object.assign(DropdownRoot, {
+  Root: DropdownRoot,
+  Trigger: DropdownTrigger,
+  Popover: DropdownPopover,
+  Menu: DropdownMenu,
+  Section: DropdownSection,
+  Item: DropdownItem,
+  ItemIndicator: DropdownItemIndicator,
+  SubmenuIndicator: DropdownSubmenuIndicator,
+  SubmenuTrigger: DropdownSubmenuTrigger,
+});
+
+export type Dropdown<T extends object = object> = {
+  Props: ComponentProps<typeof DropdownRoot>;
+  RootProps: ComponentProps<typeof DropdownRoot>;
+  TriggerProps: ComponentProps<typeof DropdownTrigger>;
+  PopoverProps: ComponentProps<typeof DropdownPopover>;
+  MenuProps: ComponentProps<typeof DropdownMenu<T>>;
+  SectionProps: ComponentProps<typeof DropdownSection>;
+  ItemProps: ComponentProps<typeof DropdownItem>;
+  ItemIndicatorProps: ComponentProps<typeof DropdownItemIndicator>;
+  SubmenuIndicatorProps: ComponentProps<typeof DropdownSubmenuIndicator>;
+  SubmenuTriggerProps: ComponentProps<typeof DropdownSubmenuTrigger>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  DropdownItem,
+  DropdownItemIndicator,
+  DropdownMenu,
+  DropdownPopover,
+  DropdownRoot,
+  DropdownSection,
+  DropdownSubmenuIndicator,
+  DropdownSubmenuTrigger,
+  DropdownTrigger,
+};
+
+export type {
+  DropdownItemIndicatorProps,
+  DropdownItemProps,
+  DropdownMenuProps,
+  DropdownPopoverProps,
+  DropdownRootProps,
+  DropdownRootProps as DropdownProps,
+  DropdownSectionProps,
+  DropdownSubmenuIndicatorProps,
+  DropdownSubmenuTriggerProps,
+  DropdownTriggerProps,
+} from "./dropdown";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {dropdownVariants} from "@heroui/styles";
+
+export type {DropdownVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/empty-state/empty-state.tsx b/packages/react/src/components/empty-state/empty-state.tsx
new file mode 100644
index 0000000..fc52dca
--- /dev/null
+++ b/packages/react/src/components/empty-state/empty-state.tsx
@@ -0,0 +1,36 @@
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ReactNode} from "react";
+
+import {emptyStateVariants} from "@heroui/styles";
+import React from "react";
+
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * EmptyState Root
+ * -----------------------------------------------------------------------------------------------*/
+interface EmptyStateRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const EmptyStateRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...rest
+}: EmptyStateRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof EmptyStateRootProps<E>>) => {
+  return (
+    <dom.div className={emptyStateVariants({className})} data-slot="empty-state" {...(rest as any)}>
+      {children || "No results found"}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {EmptyStateRoot};
+
+export type {EmptyStateRootProps};
diff --git a/packages/react/src/components/empty-state/index.ts b/packages/react/src/components/empty-state/index.ts
new file mode 100644
index 0000000..1a17af8
--- /dev/null
+++ b/packages/react/src/components/empty-state/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {EmptyStateRoot} from "./empty-state";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const EmptyState = Object.assign(EmptyStateRoot, {
+  Root: EmptyStateRoot,
+});
+
+export type EmptyState = {
+  Props: ComponentProps<typeof EmptyStateRoot>;
+  RootProps: ComponentProps<typeof EmptyStateRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {EmptyStateRoot};
+
+export type {EmptyStateRootProps, EmptyStateRootProps as EmptyStateProps} from "./empty-state";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {emptyStateVariants} from "@heroui/styles";
+
+export type {EmptyStateVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/error-message/error-message.tsx b/packages/react/src/components/error-message/error-message.tsx
new file mode 100644
index 0000000..77c5fa0
--- /dev/null
+++ b/packages/react/src/components/error-message/error-message.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import type {ErrorMessageVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {TextProps} from "react-aria-components/Text";
+
+import {errorMessageVariants} from "@heroui/styles";
+import {Text} from "react-aria-components/Text";
+
+/* -------------------------------------------------------------------------------------------------
+ * Error Message Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ErrorMessageRootProps
+  extends ComponentPropsWithRef<typeof Text>, TextProps, ErrorMessageVariants {}
+
+const ErrorMessageRoot = ({children, className, ...rest}: ErrorMessageRootProps) => {
+  return (
+    <Text
+      className={errorMessageVariants({className})}
+      data-slot="error-message"
+      slot="errorMessage"
+      {...rest}
+    >
+      {children}
+    </Text>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ErrorMessageRoot};
+
+export type {ErrorMessageRootProps};
diff --git a/packages/react/src/components/error-message/index.ts b/packages/react/src/components/error-message/index.ts
new file mode 100644
index 0000000..6de7c33
--- /dev/null
+++ b/packages/react/src/components/error-message/index.ts
@@ -0,0 +1,32 @@
+import type {ComponentProps} from "react";
+
+import {ErrorMessageRoot} from "./error-message";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ErrorMessage = Object.assign(ErrorMessageRoot, {
+  Root: ErrorMessageRoot,
+});
+
+export type ErrorMessage = {
+  Props: ComponentProps<typeof ErrorMessageRoot>;
+  RootProps: ComponentProps<typeof ErrorMessageRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ErrorMessageRoot};
+
+export type {
+  ErrorMessageRootProps,
+  ErrorMessageRootProps as ErrorMessageProps,
+} from "./error-message";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {errorMessageVariants} from "@heroui/styles";
+
+export type {ErrorMessageVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/field-error/field-error.tsx b/packages/react/src/components/field-error/field-error.tsx
new file mode 100644
index 0000000..3b9fa27
--- /dev/null
+++ b/packages/react/src/components/field-error/field-error.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import type {FieldErrorVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {fieldErrorVariants} from "@heroui/styles";
+import {FieldError as FieldErrorPrimitive} from "react-aria-components/FieldError";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * Field Error Root
+ * -----------------------------------------------------------------------------------------------*/
+interface FieldErrorRootProps
+  extends ComponentPropsWithRef<typeof FieldErrorPrimitive>, FieldErrorVariants {}
+
+const FieldErrorRoot = ({children, className, ...rest}: FieldErrorRootProps) => {
+  return (
+    <FieldErrorPrimitive
+      data-visible
+      className={composeTwRenderProps(className, fieldErrorVariants())}
+      data-slot="field-error"
+      {...rest}
+    >
+      {(renderProps) => (typeof children === "function" ? children(renderProps) : children)}
+    </FieldErrorPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {FieldErrorRoot};
+
+export type {FieldErrorRootProps};
diff --git a/packages/react/src/components/field-error/index.ts b/packages/react/src/components/field-error/index.ts
new file mode 100644
index 0000000..a713cce
--- /dev/null
+++ b/packages/react/src/components/field-error/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {FieldErrorRoot} from "./field-error";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const FieldError = Object.assign(FieldErrorRoot, {
+  Root: FieldErrorRoot,
+});
+
+export type FieldError = {
+  Props: ComponentProps<typeof FieldErrorRoot>;
+  RootProps: ComponentProps<typeof FieldErrorRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {FieldErrorRoot};
+
+export type {FieldErrorRootProps, FieldErrorRootProps as FieldErrorProps} from "./field-error";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {fieldErrorVariants} from "@heroui/styles";
+
+export type {FieldErrorVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/fieldset/fieldset.stories.tsx b/packages/react/src/components/fieldset/fieldset.stories.tsx
new file mode 100644
index 0000000..08cfd86
--- /dev/null
+++ b/packages/react/src/components/fieldset/fieldset.stories.tsx
@@ -0,0 +1,100 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Input} from "../input";
+import {Label} from "../label";
+import {TextArea} from "../textarea";
+import {TextField} from "../textfield";
+
+import {Fieldset} from "./index";
+
+const meta: Meta<typeof Fieldset> = {
+  component: Fieldset,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Forms/Fieldset",
+};
+
+export default meta;
+type Story = StoryObj<typeof Fieldset>;
+
+export const Default: Story = {
+  render: () => {
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const data: Record<string, string> = {};
+
+      // Convert FormData to plain object
+      formData.forEach((value, key) => {
+        data[key] = value.toString();
+      });
+
+      alert("Form submitted successfully!");
+    };
+
+    return (
+      <Form onSubmit={onSubmit}>
+        <Fieldset className="w-96">
+          <Fieldset.Legend>Profile Settings</Fieldset.Legend>
+          <Description>Update your profile information.</Description>
+          <Fieldset.Group>
+            <TextField
+              isRequired
+              name="name"
+              validate={(value) => {
+                if (value.length < 3) {
+                  return "Name must be at least 3 characters";
+                }
+
+                return null;
+              }}
+            >
+              <Label>Name</Label>
+              <Input placeholder="John Doe" />
+              <FieldError />
+            </TextField>
+            <TextField isRequired name="email" type="email">
+              <Label>Email</Label>
+              <Input placeholder="john@example.com" />
+              <FieldError />
+            </TextField>
+            <TextField
+              isRequired
+              name="bio"
+              validate={(value) => {
+                if (value.length < 10) {
+                  return "Bio must be at least 10 characters";
+                }
+
+                return null;
+              }}
+            >
+              <Label>Bio</Label>
+              <TextArea placeholder="Tell us about yourself..." />
+              <Description>Minimum 10 characters</Description>
+              <FieldError />
+            </TextField>
+          </Fieldset.Group>
+          <Fieldset.Actions>
+            <Button type="submit">
+              <Icon icon="gravity-ui:floppy-disk" />
+              Save changes
+            </Button>
+            <Button type="reset" variant="tertiary">
+              Cancel
+            </Button>
+          </Fieldset.Actions>
+        </Fieldset>
+      </Form>
+    );
+  },
+};
diff --git a/packages/react/src/components/fieldset/fieldset.tsx b/packages/react/src/components/fieldset/fieldset.tsx
new file mode 100644
index 0000000..acb66f2
--- /dev/null
+++ b/packages/react/src/components/fieldset/fieldset.tsx
@@ -0,0 +1,182 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ReactNode} from "react";
+
+import {fieldsetVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  ButtonContext,
+  CheckboxGroupContext,
+  LinkContext,
+  Provider,
+  RadioGroupContext,
+  SliderContext,
+  ToggleButtonContext,
+  ToggleButtonGroupContext,
+} from "react-aria-components";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Fieldset Context
+ * -----------------------------------------------------------------------------------------------*/
+type FieldsetContext = {
+  slots?: ReturnType<typeof fieldsetVariants>;
+};
+
+const FieldsetContext = createContext<FieldsetContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Fieldset Root
+ * -----------------------------------------------------------------------------------------------*/
+interface FieldsetRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "fieldset",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const FieldsetRoot = <E extends keyof React.JSX.IntrinsicElements = "fieldset">({
+  children,
+  className,
+  ...props
+}: FieldsetRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof FieldsetRootProps<E>>) => {
+  const slots = React.useMemo(() => fieldsetVariants({}), []);
+
+  // Mirror native `<fieldset disabled>` as `data-disabled="true"` so the
+  // existing `[data-disabled="true"] .label` (and similar) ancestor selectors
+  // cascade disabled styling to descendant fields, just like a direct
+  // `isDisabled` prop on TextField/Checkbox/etc. would.
+  const isDisabled = "disabled" in props && props.disabled === true;
+
+  return (
+    <FieldsetContext value={{slots}}>
+      <dom.fieldset
+        className={slots?.base({className})}
+        data-disabled={isDisabled || undefined}
+        data-slot="fieldset"
+        {...(props as any)}
+      >
+        {isDisabled ? (
+          // Forward `isDisabled` through React Aria contexts so descendant
+          // components stay consistent with the native `<fieldset disabled>`
+          // behaviour. There are two reasons we need to do this manually:
+          //
+          // 1. Some primitives (Slider, RadioGroup, CheckboxGroup, ...) render
+          //    as `<div>` so the browser does not propagate the fieldset's
+          //    `disabled` attribute to them — without this, they would still
+          //    look enabled and remain interactive.
+          // 2. Other primitives (Button, ToggleButton, Link, ...) do get
+          //    natively disabled by the browser, but React Aria's internal
+          //    `isDisabled` state — which drives `data-disabled` and the
+          //    `{isDisabled}` render prop — only updates from props/context.
+          //    Without this, the button is unclickable but its render prop
+          //    keeps returning `isDisabled: false`.
+          <Provider
+            values={[
+              [ButtonContext, {isDisabled: true}],
+              [CheckboxGroupContext, {isDisabled: true}],
+              [LinkContext, {isDisabled: true}],
+              [RadioGroupContext, {isDisabled: true}],
+              [SliderContext, {isDisabled: true}],
+              [ToggleButtonContext, {isDisabled: true}],
+              [ToggleButtonGroupContext, {isDisabled: true}],
+            ]}
+          >
+            {children}
+          </Provider>
+        ) : (
+          children
+        )}
+      </dom.fieldset>
+    </FieldsetContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Fieldset Legend
+ * -----------------------------------------------------------------------------------------------*/
+interface FieldsetLegendProps<
+  E extends keyof React.JSX.IntrinsicElements = "legend",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const FieldsetLegend = <E extends keyof React.JSX.IntrinsicElements = "legend">({
+  className,
+  ...props
+}: FieldsetLegendProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof FieldsetLegendProps<E>>) => {
+  const {slots} = use(FieldsetContext);
+
+  return (
+    <dom.legend
+      className={composeSlotClassName(slots?.legend, className)}
+      data-slot="fieldset-legend"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Field Group
+ * -----------------------------------------------------------------------------------------------*/
+interface FieldGroupProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const FieldGroup = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...rest
+}: FieldGroupProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof FieldGroupProps<E>>) => {
+  const {slots} = use(FieldsetContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.fieldGroup, className)}
+      data-slot="fieldset-field-group"
+      {...(rest as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Field Actions
+ * -----------------------------------------------------------------------------------------------*/
+interface FieldsetActionsProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const FieldsetActions = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...rest
+}: FieldsetActionsProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof FieldsetActionsProps<E>>) => {
+  const {slots} = use(FieldsetContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.actions, className)}
+      data-slot="fieldset-actions"
+      {...(rest as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {FieldsetRoot, FieldsetLegend, FieldGroup, FieldsetActions};
+
+export type {FieldsetRootProps, FieldsetLegendProps, FieldGroupProps, FieldsetActionsProps};
diff --git a/packages/react/src/components/fieldset/index.ts b/packages/react/src/components/fieldset/index.ts
new file mode 100644
index 0000000..e16516e
--- /dev/null
+++ b/packages/react/src/components/fieldset/index.ts
@@ -0,0 +1,41 @@
+import type {ComponentProps} from "react";
+
+import {FieldGroup, FieldsetActions, FieldsetLegend, FieldsetRoot} from "./fieldset";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Fieldset = Object.assign(FieldsetRoot, {
+  Root: FieldsetRoot,
+  Legend: FieldsetLegend,
+  Group: FieldGroup,
+  Actions: FieldsetActions,
+});
+
+export type Fieldset = {
+  Props: ComponentProps<typeof FieldsetRoot>;
+  RootProps: ComponentProps<typeof FieldsetRoot>;
+  LegendProps: ComponentProps<typeof FieldsetLegend>;
+  GroupProps: ComponentProps<typeof FieldGroup>;
+  ActionsProps: ComponentProps<typeof FieldsetActions>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {FieldsetRoot, FieldsetLegend, FieldGroup, FieldsetActions};
+
+export type {
+  FieldsetRootProps,
+  FieldsetRootProps as FieldsetProps,
+  FieldsetLegendProps,
+  FieldGroupProps,
+  FieldsetActionsProps,
+} from "./fieldset";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {fieldsetVariants} from "@heroui/styles";
+
+export type {FieldsetVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/form/form.tsx b/packages/react/src/components/form/form.tsx
new file mode 100644
index 0000000..0a9930a
--- /dev/null
+++ b/packages/react/src/components/form/form.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import type {ComponentPropsWithRef} from "react";
+
+import React from "react";
+import {Form as FormPrimitive} from "react-aria-components/Form";
+
+/* -------------------------------------------------------------------------------------------------
+ * Form Root
+ * -----------------------------------------------------------------------------------------------*/
+interface FormRootProps extends ComponentPropsWithRef<typeof FormPrimitive> {}
+
+const FormRoot = ({...props}: FormRootProps) => {
+  return <FormPrimitive {...props} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {FormRoot};
+
+export type {FormRootProps};
diff --git a/packages/react/src/components/form/index.ts b/packages/react/src/components/form/index.ts
new file mode 100644
index 0000000..68c936c
--- /dev/null
+++ b/packages/react/src/components/form/index.ts
@@ -0,0 +1,22 @@
+import type {ComponentProps} from "react";
+
+import {FormRoot} from "./form";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Form = Object.assign(FormRoot, {
+  Root: FormRoot,
+});
+
+export type Form = {
+  Props: ComponentProps<typeof FormRoot>;
+  RootProps: ComponentProps<typeof FormRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {FormRoot};
+
+export type {FormRootProps, FormRootProps as FormProps} from "./form";
diff --git a/packages/react/src/components/header/header.tsx b/packages/react/src/components/header/header.tsx
new file mode 100644
index 0000000..db4182f
--- /dev/null
+++ b/packages/react/src/components/header/header.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import type {ComponentPropsWithRef} from "react";
+
+import {headerVariants} from "@heroui/styles";
+import {Header as HeaderPrimitive} from "react-aria-components/Header";
+
+/* -------------------------------------------------------------------------------------------------
+ * Header Root
+ * -----------------------------------------------------------------------------------------------*/
+interface HeaderRootProps extends ComponentPropsWithRef<typeof HeaderPrimitive> {}
+
+const HeaderRoot = ({children, className, ...rest}: HeaderRootProps) => {
+  return (
+    <HeaderPrimitive className={headerVariants({className})} data-slot="header" {...rest}>
+      {children}
+    </HeaderPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {HeaderRoot};
+
+export type {HeaderRootProps};
diff --git a/packages/react/src/components/header/index.ts b/packages/react/src/components/header/index.ts
new file mode 100644
index 0000000..0477772
--- /dev/null
+++ b/packages/react/src/components/header/index.ts
@@ -0,0 +1,24 @@
+import type {ComponentProps} from "react";
+
+import {HeaderRoot} from "./header";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Header = HeaderRoot;
+
+export type Header = {
+  Props: ComponentProps<typeof HeaderRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {HeaderRoot};
+
+export type {HeaderRootProps, HeaderRootProps as HeaderProps} from "./header";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {headerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/icons.tsx b/packages/react/src/components/icons.tsx
new file mode 100644
index 0000000..04c735a
--- /dev/null
+++ b/packages/react/src/components/icons.tsx
@@ -0,0 +1,314 @@
+import React from "react";
+
+interface IconProps extends React.SVGProps<SVGSVGElement> {}
+
+export const IconChevronDown = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Chevron down icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconChevronUp = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Chevron up icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 0 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconChevronLeft = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Chevron left icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M10.53 2.97a.75.75 0 0 1 0 1.06L6.56 8l3.97 3.97a.75.75 0 1 1-1.06 1.06l-4.5-4.5a.75.75 0 0 1 0-1.06l4.5-4.5a.75.75 0 0 1 1.06 0"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconChevronRight = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Chevron right icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M5.47 2.97a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06l-4.5 4.5a.75.75 0 1 1-1.06-1.06L9.44 8 5.47 4.03a.75.75 0 0 1 0-1.06Z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const ExternalLinkIcon = ({height = 9, width = 9, ...props}: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="External link icon"
+    fill="none"
+    height={height}
+    role="presentation"
+    viewBox="0 0 7 7"
+    width={width}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M1.20592 6.84333L0.379822 6.01723L4.52594 1.8672H1.37819L1.38601 0.731812H6.48742V5.83714H5.34421L5.35203 2.6933L1.20592 6.84333Z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+export const CircleDashedIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Circle dashed icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M6.906 1.085a7.047 7.047 0 0 1 2.188 0 .75.75 0 0 1-.232 1.482 5.546 5.546 0 0 0-1.724 0 .75.75 0 0 1-.232-1.482ZM4.933 2.502a.75.75 0 0 1-.166 1.048c-.466.34-.878.75-1.217 1.217a.75.75 0 0 1-1.213-.882 7.036 7.036 0 0 1 1.548-1.548.75.75 0 0 1 1.048.165Zm6.135 0a.75.75 0 0 1 1.047-.165 7.037 7.037 0 0 1 1.548 1.548.75.75 0 0 1-1.213.882 5.533 5.533 0 0 0-1.217-1.217.75.75 0 0 1-.165-1.048ZM1.943 6.28a.75.75 0 0 1 .624.857 5.546 5.546 0 0 0 0 1.724.75.75 0 0 1-1.482.232 7.047 7.047 0 0 1 0-2.188.75.75 0 0 1 .858-.625Zm12.114 0a.75.75 0 0 1 .858.625 7.048 7.048 0 0 1 0 2.188.75.75 0 1 1-1.482-.232 5.54 5.54 0 0 0 0-1.724.75.75 0 0 1 .624-.857ZM2.502 11.068a.75.75 0 0 1 1.048.165c.34.466.75.878 1.217 1.217a.75.75 0 0 1-.882 1.213 7.037 7.037 0 0 1-1.548-1.548.75.75 0 0 1 .165-1.047Zm10.996 0a.75.75 0 0 1 .165 1.047 7.037 7.037 0 0 1-1.548 1.548.75.75 0 0 1-.883-1.213 5.53 5.53 0 0 0 1.218-1.217.75.75 0 0 1 1.048-.165Zm-7.217 2.99a.75.75 0 0 1 .857-.625 5.54 5.54 0 0 0 1.724 0 .75.75 0 0 1 .232 1.482 7.048 7.048 0 0 1-2.188 0 .75.75 0 0 1-.625-.857Z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+export const CloseIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Close icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M3.47 3.47a.75.75 0 0 1 1.06 0L8 6.94l3.47-3.47a.75.75 0 1 1 1.06 1.06L9.06 8l3.47 3.47a.75.75 0 1 1-1.06 1.06L8 9.06l-3.47 3.47a.75.75 0 0 1-1.06-1.06L6.94 8 3.47 4.53a.75.75 0 0 1 0-1.06Z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const InfoIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Info icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M8 13.5a5.5 5.5 0 1 0 0-11a5.5 5.5 0 0 0 0 11M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m1-9.5a1 1 0 1 1-2 0a1 1 0 0 1 2 0m-.25 3a.75.75 0 0 0-1.5 0V11a.75.75 0 0 0 1.5 0z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const WarningIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Warning icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M7.134 2.994L2.217 11.5a1 1 0 0 0 .866 1.5h9.834a1 1 0 0 0 .866-1.5L8.866 2.993a1 1 0 0 0-1.732 0m3.03-.75c-.962-1.665-3.366-1.665-4.329 0L.918 10.749c-.963 1.666.24 3.751 2.165 3.751h9.834c1.925 0 3.128-2.085 2.164-3.751zM8 5a.75.75 0 0 1 .75.75v2a.75.75 0 0 1-1.5 0v-2A.75.75 0 0 1 8 5m1 5.75a1 1 0 1 1-2 0a1 1 0 0 1 2 0"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const DangerIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Danger icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M8 13.5a5.5 5.5 0 1 0 0-11a5.5 5.5 0 0 0 0 11M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m1-4.5a1 1 0 1 1-2 0a1 1 0 0 1 2 0M8.75 5a.75.75 0 0 0-1.5 0v2.5a.75.75 0 0 0 1.5 0z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const SuccessIcon = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Success icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M13.5 8a5.5 5.5 0 1 1-11 0a5.5 5.5 0 0 1 11 0M15 8A7 7 0 1 1 1 8a7 7 0 0 1 14 0m-3.9-1.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconMinus = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Minus icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M1.75 8a.75.75 0 0 1 .75-.75h11a.75.75 0 0 1 0 1.5h-11A.75.75 0 0 1 1.75 8"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconPlus = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Plus icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M8 1.75a.75.75 0 0 1 .75.75v4.75h4.75a.75.75 0 0 1 0 1.5H8.75v4.75a.75.75 0 0 1-1.5 0V8.75H2.5a.75.75 0 0 1 0-1.5h4.75V2.5A.75.75 0 0 1 8 1.75"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconSearch = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Search icon"
+    fill="none"
+    height={16}
+    role="presentation"
+    viewBox="0 0 16 16"
+    width={16}
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M11.5 7a4.5 4.5 0 1 1-9 0a4.5 4.5 0 0 1 9 0m-.82 4.74a6 6 0 1 1 1.06-1.06l2.79 2.79a.75.75 0 1 1-1.06 1.06z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
+
+export const IconCalendar = (props: IconProps) => (
+  <svg
+    aria-hidden="true"
+    aria-label="Calendar icon"
+    fill="none"
+    height="1em"
+    role="presentation"
+    viewBox="0 0 13 14"
+    width="1em"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      clipRule="evenodd"
+      d="M3.75 4.5A.75.75 0 0 1 3 3.75v-.748a1.5 1.5 0 0 0-1.5 1.5v1h10v-1a1.5 1.5 0 0 0-1.5-1.5v.75a.75.75 0 1 1-1.5 0v-.75h-4v.747a.75.75 0 0 1-.75.75ZM8.5 1.501h-4V.75a.75.75 0 0 0-1.5 0v.752a3 3 0 0 0-3 3v6a3 3 0 0 0 3 3h7a3 3 0 0 0 3-3v-6a3 3 0 0 0-3-3v-.75a.75.75 0 0 0-1.5 0v.75Zm-7 5.5v3.5a1.5 1.5 0 0 0 1.5 1.5h7a1.5 1.5 0 0 0 1.5-1.5v-3.5h-10Z"
+      fill="currentColor"
+      fillRule="evenodd"
+    />
+  </svg>
+);
diff --git a/packages/react/src/components/index.ts b/packages/react/src/components/index.ts
new file mode 100644
index 0000000..5caf030
--- /dev/null
+++ b/packages/react/src/components/index.ts
@@ -0,0 +1,99 @@
+//  ===================================
+//  Components
+//  ===================================
+
+// completed
+export * from "./accordion";
+export * from "./alert-dialog";
+export * from "./autocomplete";
+export * from "./avatar";
+export * from "./badge";
+export * from "./breadcrumbs";
+export * from "./button";
+export * from "./button-group";
+export * from "./card";
+export * from "./checkbox";
+export * from "./checkbox-group";
+export * from "./chip";
+export * from "./color-area";
+export * from "./color-field";
+export * from "./color-picker";
+export * from "./color-slider";
+export * from "./color-swatch";
+export * from "./color-swatch-picker";
+export * from "./close-button";
+export * from "./combo-box";
+export * from "./date-field";
+export * from "./date-picker";
+export * from "./date-range-picker";
+export * from "./drawer";
+export * from "./progress-bar";
+export * from "./progress-circle";
+export * from "./time-field";
+export * from "./disclosure";
+export * from "./disclosure-group";
+export * from "./error-message";
+export * from "./kbd";
+export * from "./link";
+export * from "./popover";
+export * from "./scroll-shadow";
+export * from "./separator";
+export * from "./skeleton";
+export * from "./spinner";
+export * from "./surface";
+export * from "./toast";
+export * from "./toggle-button";
+export * from "./switch";
+export * from "./switch-group";
+export * from "./tabs";
+export * from "./tag";
+export * from "./tag-group";
+export * from "./toggle-button-group";
+export * from "./toolbar";
+export * from "./tooltip";
+export * from "./input";
+export * from "./input-group";
+export * from "./textarea";
+export * from "./textfield";
+export * from "./search-field";
+export * from "./typography";
+export * from "./label";
+export * from "./description";
+export * from "./empty-state";
+export * from "./field-error";
+export * from "./fieldset";
+export * from "./form";
+export * from "./header";
+export * from "./radio";
+export * from "./radio-group";
+export * from "./input-otp";
+export * from "./alert";
+export * from "./list-box";
+export * from "./list-box-item";
+export * from "./list-box-section";
+export * from "./dropdown";
+export * from "./menu";
+export * from "./menu-item";
+export * from "./menu-section";
+export * from "./modal";
+export * from "./number-field";
+export * from "./pagination";
+export * from "./select";
+export * from "./meter";
+export * from "./slider";
+export * from "./table";
+
+// in progress
+export * from "./calendar";
+export * from "./calendar-year-picker";
+export * from "./range-calendar";
+
+//  ===================================
+//  Icons
+//  ===================================
+export * from "./icons";
+
+//  ===================================
+//  React Aria Components
+//  ===================================
+export * from "./rac";
diff --git a/packages/react/src/components/input-group/index.ts b/packages/react/src/components/input-group/index.ts
new file mode 100644
index 0000000..31991f8
--- /dev/null
+++ b/packages/react/src/components/input-group/index.ts
@@ -0,0 +1,50 @@
+import type {ComponentProps} from "react";
+
+import {
+  InputGroupInput,
+  InputGroupPrefix,
+  InputGroupRoot,
+  InputGroupSuffix,
+  InputGroupTextArea,
+} from "./input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const InputGroup = Object.assign(InputGroupRoot, {
+  Root: InputGroupRoot,
+  Input: InputGroupInput,
+  TextArea: InputGroupTextArea,
+  Prefix: InputGroupPrefix,
+  Suffix: InputGroupSuffix,
+});
+
+export type InputGroup = {
+  Props: ComponentProps<typeof InputGroupRoot>;
+  RootProps: ComponentProps<typeof InputGroupRoot>;
+  InputProps: ComponentProps<typeof InputGroupInput>;
+  TextAreaProps: ComponentProps<typeof InputGroupTextArea>;
+  PrefixProps: ComponentProps<typeof InputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof InputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {InputGroupInput, InputGroupPrefix, InputGroupRoot, InputGroupSuffix, InputGroupTextArea};
+
+export type {
+  InputGroupRootProps,
+  InputGroupRootProps as InputGroupProps,
+  InputGroupInputProps,
+  InputGroupTextAreaProps,
+  InputGroupPrefixProps,
+  InputGroupSuffixProps,
+} from "./input-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {inputGroupVariants} from "@heroui/styles";
+
+export type {InputGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/input-group/input-group.stories.tsx b/packages/react/src/components/input-group/input-group.stories.tsx
new file mode 100644
index 0000000..9b34a89
--- /dev/null
+++ b/packages/react/src/components/input-group/input-group.stories.tsx
@@ -0,0 +1,550 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {Chip} from "../chip";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Kbd} from "../kbd";
+import {Label} from "../label";
+import {Spinner} from "../spinner";
+import {TextField} from "../textfield";
+import {Tooltip} from "../tooltip";
+
+import {InputGroup} from "./index";
+
+const meta: Meta<typeof InputGroup> = {
+  component: InputGroup,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Forms/InputGroup",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <TextField className="w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField className="w-[280px]" name="primary">
+        <Label>Primary variant</Label>
+        <InputGroup variant="primary">
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField className="w-[280px]" name="secondary">
+        <Label>Secondary variant</Label>
+        <InputGroup variant="secondary">
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="email">
+        <Label>Email address</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField fullWidth name="password">
+        <Label>Password</Label>
+        <InputGroup fullWidth>
+          <InputGroup.Input placeholder="Enter password" type="password" />
+          <InputGroup.Suffix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:eye" />
+          </InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  ),
+};
+
+export const WithPrefixIcon: Story = {
+  render: () => (
+    <TextField className="w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+      </InputGroup>
+      <Description>We'll never share this with anyone else</Description>
+    </TextField>
+  ),
+};
+
+export const WithSuffixIcon: Story = {
+  render: () => (
+    <TextField className="w-[280px]" name="email">
+      <Label>Email address</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+        <InputGroup.Suffix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+        </InputGroup.Suffix>
+      </InputGroup>
+      <Description>We don't send spam</Description>
+    </TextField>
+  ),
+};
+
+export const WithPrefixAndSuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="10" name="price">
+      <Label>Set a price</Label>
+      <InputGroup>
+        <InputGroup.Prefix>$</InputGroup.Prefix>
+        <InputGroup.Input className="w-[200px]" type="number" />
+        <InputGroup.Suffix>USD</InputGroup.Suffix>
+      </InputGroup>
+      <Description>What customers would pay</Description>
+    </TextField>
+  ),
+};
+
+export const WithTextPrefix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>https://</InputGroup.Prefix>
+        <InputGroup.Input className="w-[280px]" />
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithTextSuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="heroui" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithIconPrefixAndTextSuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="heroui" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:globe" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-[280px]" />
+        <InputGroup.Suffix>.com</InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithCopySuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
+            <Icon className="size-4" icon="gravity-ui:copy" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithIconPrefixAndCopySuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="heroui.com" name="website">
+      <Label>Website</Label>
+      <InputGroup>
+        <InputGroup.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:globe" />
+        </InputGroup.Prefix>
+        <InputGroup.Input className="w-[280px]" />
+        <InputGroup.Suffix className="pr-0">
+          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
+            <Icon className="size-4" icon="gravity-ui:copy" />
+          </Button>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const PasswordWithToggle: Story = {
+  render: () => {
+    const [isVisible, setIsVisible] = useState(false);
+
+    return (
+      <TextField className="w-[280px]" name="password">
+        <Label>Password</Label>
+        <InputGroup>
+          <InputGroup.Input
+            className="w-[280px]"
+            type={isVisible ? "text" : "password"}
+            value={isVisible ? "87$2h.3diua" : "••••••••"}
+          />
+          <InputGroup.Suffix className="pr-0">
+            <Button
+              isIconOnly
+              aria-label={isVisible ? "Hide password" : "Show password"}
+              size="sm"
+              variant="ghost"
+              onPress={() => setIsVisible(!isVisible)}
+            >
+              <Icon
+                className="size-4"
+                icon={isVisible ? "gravity-ui:eye" : "gravity-ui:eye-slash"}
+              />
+            </Button>
+          </InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    );
+  },
+};
+
+export const WithLoadingSuffix: Story = {
+  render: () => (
+    <TextField className="w-[280px]" defaultValue="Sending..." name="status">
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" />
+        <InputGroup.Suffix>
+          <Spinner className="size-4" />
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithKeyboardShortcut: Story = {
+  render: () => (
+    <TextField aria-label="Command" className="w-[280px]" name="command">
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" placeholder="Command" />
+        <InputGroup.Suffix className="pr-2">
+          <Kbd>
+            <Kbd.Abbr keyValue="command" />
+            <Kbd.Content>K</Kbd.Content>
+          </Kbd>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const WithBadgeSuffix: Story = {
+  render: () => (
+    <TextField aria-label="Email address" className="w-[280px]" name="email">
+      <InputGroup>
+        <InputGroup.Input className="w-[280px]" placeholder="Email address" />
+        <InputGroup.Suffix className="pr-2">
+          <Chip color="accent" size="md" variant="soft">
+            Pro
+          </Chip>
+        </InputGroup.Suffix>
+      </InputGroup>
+    </TextField>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isRequired className="w-[280px]" name="email">
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+      </TextField>
+      <TextField isRequired name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <Description>What customers would pay</Description>
+      </TextField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isInvalid isRequired className="w-[280px]" name="email">
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+        </InputGroup>
+        <FieldError>Please enter a valid email address</FieldError>
+      </TextField>
+      <TextField isInvalid isRequired className="w-[280px]" name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-[200px]" placeholder="0" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+        <FieldError>Price must be greater than 0</FieldError>
+      </TextField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isDisabled className="w-[280px]" defaultValue="name@email.com" name="email">
+        <Label>Email address</Label>
+        <InputGroup>
+          <InputGroup.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+          </InputGroup.Prefix>
+          <InputGroup.Input className="w-[280px]" />
+        </InputGroup>
+      </TextField>
+      <TextField isDisabled className="w-[280px]" defaultValue="10" name="price">
+        <Label>Set a price</Label>
+        <InputGroup>
+          <InputGroup.Prefix>$</InputGroup.Prefix>
+          <InputGroup.Input className="w-[200px]" type="number" />
+          <InputGroup.Suffix>USD</InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    </div>
+  ),
+};
+
+export const WithTextArea: Story = {
+  render: () => {
+    const [value, setValue] = useState("");
+    const [isSubmitting, setIsSubmitting] = useState(false);
+
+    const handleSubmit = () => {
+      if (!value.trim()) return;
+
+      setIsSubmitting(true);
+
+      setTimeout(() => {
+        setIsSubmitting(false);
+        setValue("");
+      }, 1000);
+    };
+
+    return (
+      <TextField
+        fullWidth
+        aria-label="Prompt input"
+        className="flex w-sm flex-col sm:w-lg"
+        name="prompt"
+      >
+        <InputGroup fullWidth className="flex flex-col gap-2 rounded-3xl py-2">
+          <InputGroup.Prefix className="px-3 py-0">
+            <Button aria-label="Add context" size="sm" variant="outline">
+              <Icon icon="gravity-ui:at" />
+              Add Context
+            </Button>
+          </InputGroup.Prefix>
+          <InputGroup.TextArea
+            className="w-full resize-none px-3.5 py-0"
+            placeholder="Assign tasks or ask anything..."
+            rows={5}
+            value={value}
+            onChange={(event) => setValue(event.target.value)}
+          />
+          <InputGroup.Suffix className="flex w-full items-center gap-1.5 px-3 py-0">
+            <Tooltip delay={0}>
+              <Button isIconOnly aria-label="Attach file" size="sm" variant="tertiary">
+                <Icon icon="gravity-ui:plus" />
+              </Button>
+              <Tooltip.Content>
+                <p className="text-xs">Add a files and more</p>
+              </Tooltip.Content>
+            </Tooltip>
+            <Tooltip delay={0}>
+              <Button isIconOnly aria-label="Connect Apps" size="sm" variant="tertiary">
+                <Icon icon="gravity-ui:plug-connection" />
+              </Button>
+              <Tooltip.Content>
+                <p className="text-xs">Connect apps</p>
+              </Tooltip.Content>
+            </Tooltip>
+            <div className="ml-auto flex items-center gap-1.5">
+              <Tooltip delay={0}>
+                <Button isIconOnly aria-label="Voice input" size="sm" variant="ghost">
+                  <Icon icon="gravity-ui:microphone" />
+                </Button>
+                <Tooltip.Content>
+                  <p className="text-xs">Voice input</p>
+                </Tooltip.Content>
+              </Tooltip>
+              <Tooltip delay={0}>
+                <Button
+                  isIconOnly
+                  aria-label="Send prompt"
+                  isDisabled={!value.trim()}
+                  isPending={isSubmitting}
+                  onPress={handleSubmit}
+                >
+                  {({isPending}) =>
+                    isPending ? (
+                      <Spinner color="current" size="sm" />
+                    ) : (
+                      <Icon icon="gravity-ui:arrow-up" />
+                    )
+                  }
+                </Button>
+                <Tooltip.Content className="flex items-center gap-1">
+                  <p className="text-xs">Send</p>
+                  <Kbd className="h-4 rounded-sm px-1">
+                    <Kbd.Abbr keyValue="enter" />
+                  </Kbd>
+                </Tooltip.Content>
+              </Tooltip>
+            </div>
+          </InputGroup.Suffix>
+        </InputGroup>
+      </TextField>
+    );
+  },
+};
+
+export const AllVariations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-4">
+        <TextField className="w-[280px]" name="email1">
+          <Label>Email address *</Label>
+          <InputGroup>
+            <InputGroup.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+            </InputGroup.Prefix>
+            <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+          </InputGroup>
+          <Description>We'll never share this with anyone else</Description>
+        </TextField>
+
+        <TextField className="w-[280px]" name="email2">
+          <Label>Email address *</Label>
+          <InputGroup>
+            <InputGroup.Input className="w-[280px]" placeholder="name@email.com" />
+            <InputGroup.Suffix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:envelope" />
+            </InputGroup.Suffix>
+          </InputGroup>
+          <Description>We don't send spam</Description>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="10" name="price">
+          <Label>Set a price</Label>
+          <InputGroup>
+            <InputGroup.Prefix>$</InputGroup.Prefix>
+            <InputGroup.Input className="w-[200px]" type="number" />
+            <InputGroup.Suffix>USD</InputGroup.Suffix>
+          </InputGroup>
+          <Description>What customers would pay</Description>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="heroui.com" name="website1">
+          <Label>Website</Label>
+          <InputGroup>
+            <InputGroup.Prefix>https://</InputGroup.Prefix>
+            <InputGroup.Input className="w-[280px]" />
+          </InputGroup>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="heroui" name="website2">
+          <Label>Website</Label>
+          <InputGroup>
+            <InputGroup.Input className="w-[280px]" />
+            <InputGroup.Suffix>.com</InputGroup.Suffix>
+          </InputGroup>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="heroui" name="website3">
+          <Label>Website</Label>
+          <InputGroup>
+            <InputGroup.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:globe" />
+            </InputGroup.Prefix>
+            <InputGroup.Input className="w-[280px]" />
+            <InputGroup.Suffix>.com</InputGroup.Suffix>
+          </InputGroup>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="heroui.com" name="website4">
+          <Label>Website</Label>
+          <InputGroup>
+            <InputGroup.Input className="w-[280px]" />
+            <InputGroup.Suffix className="pr-0">
+              <Button isIconOnly aria-label="Copy" className="h-auto p-0" size="sm" variant="ghost">
+                <Icon className="size-4" icon="gravity-ui:copy" />
+              </Button>
+            </InputGroup.Suffix>
+          </InputGroup>
+        </TextField>
+
+        <TextField className="w-[280px]" defaultValue="heroui.com" name="website5">
+          <Label>Website</Label>
+          <InputGroup>
+            <InputGroup.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:globe" />
+            </InputGroup.Prefix>
+            <InputGroup.Input className="w-[280px]" />
+            <InputGroup.Suffix className="pr-0">
+              <Button isIconOnly aria-label="Copy" className="h-auto p-0" size="sm" variant="ghost">
+                <Icon className="size-4" icon="gravity-ui:copy" />
+              </Button>
+            </InputGroup.Suffix>
+          </InputGroup>
+        </TextField>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/input-group/input-group.tsx b/packages/react/src/components/input-group/input-group.tsx
new file mode 100644
index 0000000..f9d2567
--- /dev/null
+++ b/packages/react/src/components/input-group/input-group.tsx
@@ -0,0 +1,156 @@
+"use client";
+
+import type {InputGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {inputGroupVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+import {Input as InputPrimitive} from "react-aria-components/Input";
+import {TextArea as TextAreaPrimitive} from "react-aria-components/TextArea";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {TextFieldContext} from "../textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type InputGroupContext = {
+  slots?: ReturnType<typeof inputGroupVariants>;
+};
+
+const InputGroupContext = createContext<InputGroupContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+interface InputGroupRootProps
+  extends ComponentPropsWithRef<typeof GroupPrimitive>, InputGroupVariants {}
+
+const InputGroupRoot = ({
+  children,
+  className,
+  fullWidth,
+  onClick,
+  variant,
+  ...props
+}: InputGroupRootProps) => {
+  const textFieldContext = use(TextFieldContext);
+  const resolvedVariant = variant ?? textFieldContext?.variant;
+  const groupRef = React.useRef<HTMLDivElement>(null);
+
+  const slots = React.useMemo(
+    () => inputGroupVariants({fullWidth, variant: resolvedVariant}),
+    [fullWidth, resolvedVariant],
+  );
+
+  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    const target = e.target as HTMLElement;
+    const input = groupRef.current?.querySelector("input");
+
+    if (input && target !== input && !input.contains(target)) {
+      input.focus();
+    }
+
+    onClick?.(e);
+  };
+
+  return (
+    <InputGroupContext value={{slots}}>
+      <GroupPrimitive
+        {...props}
+        ref={groupRef}
+        className={composeTwRenderProps(className, slots?.base())}
+        data-slot="input-group"
+        onClick={handleClick}
+      >
+        {(renderProps) => (typeof children === "function" ? children(renderProps) : children)}
+      </GroupPrimitive>
+    </InputGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup Input
+ * -----------------------------------------------------------------------------------------------*/
+interface InputGroupInputProps extends ComponentPropsWithRef<typeof InputPrimitive> {}
+
+const InputGroupInput = ({className, ...props}: InputGroupInputProps) => {
+  const {slots} = use(InputGroupContext);
+
+  return (
+    <InputPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="input-group-input"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup Prefix
+ * -----------------------------------------------------------------------------------------------*/
+interface InputGroupPrefixProps extends ComponentPropsWithRef<"div"> {}
+
+const InputGroupPrefix = ({children, className, ...props}: InputGroupPrefixProps) => {
+  const {slots} = use(InputGroupContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.prefix, className)}
+      data-slot="input-group-prefix"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup TextArea
+ * -----------------------------------------------------------------------------------------------*/
+interface InputGroupTextAreaProps extends ComponentPropsWithRef<typeof TextAreaPrimitive> {}
+
+const InputGroupTextArea = ({className, ...props}: InputGroupTextAreaProps) => {
+  const {slots} = use(InputGroupContext);
+
+  return (
+    <TextAreaPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="input-group-textarea"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * InputGroup Suffix
+ * -----------------------------------------------------------------------------------------------*/
+interface InputGroupSuffixProps extends ComponentPropsWithRef<"div"> {}
+
+const InputGroupSuffix = ({children, className, ...props}: InputGroupSuffixProps) => {
+  const {slots} = use(InputGroupContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.suffix, className)}
+      data-slot="input-group-suffix"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {InputGroupRoot, InputGroupInput, InputGroupTextArea, InputGroupPrefix, InputGroupSuffix};
+
+export type {
+  InputGroupRootProps,
+  InputGroupInputProps,
+  InputGroupTextAreaProps,
+  InputGroupPrefixProps,
+  InputGroupSuffixProps,
+};
diff --git a/packages/react/src/components/input-otp/index.ts b/packages/react/src/components/input-otp/index.ts
new file mode 100644
index 0000000..5645c58
--- /dev/null
+++ b/packages/react/src/components/input-otp/index.ts
@@ -0,0 +1,48 @@
+import type {ComponentProps} from "react";
+
+import {InputOTPGroup, InputOTPRoot, InputOTPSeparator, InputOTPSlot} from "./input-otp";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const InputOTP = Object.assign(InputOTPRoot, {
+  Root: InputOTPRoot,
+  Group: InputOTPGroup,
+  Slot: InputOTPSlot,
+  Separator: InputOTPSeparator,
+});
+
+export type InputOTP = {
+  Props: ComponentProps<typeof InputOTPRoot>;
+  RootProps: ComponentProps<typeof InputOTPRoot>;
+  GroupProps: ComponentProps<typeof InputOTPGroup>;
+  SlotProps: ComponentProps<typeof InputOTPSlot>;
+  SeparatorProps: ComponentProps<typeof InputOTPSeparator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {InputOTPRoot, InputOTPGroup, InputOTPSlot, InputOTPSeparator};
+
+export type {
+  InputOTPRootProps,
+  InputOTPRootProps as InputOTPProps,
+  InputOTPGroupProps,
+  InputOTPSlotProps,
+  InputOTPSeparatorProps,
+} from "./input-otp";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {inputOTPVariants} from "@heroui/styles";
+
+export type {InputOTPVariants} from "@heroui/styles";
+
+//  ===================================
+// Regular Expressions
+//  ===================================
+export const REGEXP_ONLY_DIGITS = "^\\d+$";
+export const REGEXP_ONLY_CHARS = "^[a-zA-Z]+$";
+export const REGEXP_ONLY_DIGITS_AND_CHARS = "^[a-zA-Z0-9]+$";
diff --git a/packages/react/src/components/input-otp/input-otp.stories.tsx b/packages/react/src/components/input-otp/input-otp.stories.tsx
new file mode 100644
index 0000000..3b3f588
--- /dev/null
+++ b/packages/react/src/components/input-otp/input-otp.stories.tsx
@@ -0,0 +1,427 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {Form} from "../form";
+import {Label} from "../label";
+import {Link} from "../link";
+import {Spinner} from "../spinner";
+
+import {InputOTP, REGEXP_ONLY_CHARS} from "./index";
+
+const meta: Meta<typeof InputOTP> = {
+  argTypes: {
+    isDisabled: {
+      control: "boolean",
+    },
+    isInvalid: {
+      control: "boolean",
+    },
+    maxLength: {
+      control: "number",
+    },
+  },
+  component: InputOTP,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Forms/InputOTP",
+};
+
+export default meta;
+type Story = StoryObj<typeof InputOTP>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="flex w-[280px] flex-col gap-2">
+      <div className="flex flex-col gap-1">
+        <Label>Verify account</Label>
+        <p className="text-sm text-muted">We&apos;ve sent a code to a****@gmail.com</p>
+      </div>
+      <InputOTP {...args} maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+      <div className="flex items-center gap-[5px] px-1 pt-1">
+        <p className="text-sm text-muted">Didn&apos;t receive a code?</p>
+        <Link className="text-foreground" underline="always">
+          Resend
+        </Link>
+      </div>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <Label>Primary variant</Label>
+        <InputOTP maxLength={6} variant="primary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label>Secondary variant</Label>
+        <InputOTP maxLength={6} variant="secondary">
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+      </div>
+    </div>
+  ),
+};
+
+export const FourDigits: Story = {
+  render: (args) => (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>Enter PIN</Label>
+      <InputOTP {...args} maxLength={4}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+          <InputOTP.Slot index={3} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label isDisabled>Verify account</Label>
+      <Description>Code verification is currently disabled</Description>
+      <InputOTP {...args} isDisabled maxLength={6}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  ),
+};
+
+export const WithPattern: Story = {
+  render: (args) => (
+    <div className="flex w-[280px] flex-col gap-2">
+      <Label>Enter code (letters only)</Label>
+      <Description>Only alphabetic characters are allowed</Description>
+      <InputOTP {...args} maxLength={6} pattern={REGEXP_ONLY_CHARS}>
+        <InputOTP.Group>
+          <InputOTP.Slot index={0} />
+          <InputOTP.Slot index={1} />
+          <InputOTP.Slot index={2} />
+        </InputOTP.Group>
+        <InputOTP.Separator />
+        <InputOTP.Group>
+          <InputOTP.Slot index={3} />
+          <InputOTP.Slot index={4} />
+          <InputOTP.Slot index={5} />
+        </InputOTP.Group>
+      </InputOTP>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState("");
+
+    return (
+      <div className="flex w-[280px] flex-col gap-2">
+        <Label>Verify account</Label>
+        <InputOTP {...args} maxLength={6} value={value} onChange={setValue}>
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <Description>
+          {value.length > 0 ? (
+            <>
+              Value: {value} ({value.length}/6) •{" "}
+              <button
+                className="font-medium text-foreground underline"
+                onClick={() => setValue("")}
+              >
+                Clear
+              </button>
+            </>
+          ) : (
+            "Enter a 6-digit code"
+          )}
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState("");
+    const [isInvalid, setIsInvalid] = React.useState(false);
+
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const code = formData.get("code");
+
+      if (code !== "123456") {
+        setIsInvalid(true);
+
+        return;
+      }
+
+      setIsInvalid(false);
+      setValue("");
+
+      alert("Code verified successfully!");
+    };
+
+    const handleChange = (val: string) => {
+      setValue(val);
+      setIsInvalid(false);
+    };
+
+    return (
+      <div className="flex w-[280px] flex-col gap-2">
+        <Form className="flex flex-col gap-2" onSubmit={onSubmit}>
+          <Label>Verify account</Label>
+          <Description>Hint: The code is 123456</Description>
+          <InputOTP
+            {...args}
+            aria-describedby={isInvalid ? "code-error" : undefined}
+            isInvalid={isInvalid}
+            maxLength={6}
+            name="code"
+            value={value}
+            onChange={handleChange}
+          >
+            <InputOTP.Group>
+              <InputOTP.Slot index={0} />
+              <InputOTP.Slot index={1} />
+              <InputOTP.Slot index={2} />
+            </InputOTP.Group>
+            <InputOTP.Separator />
+            <InputOTP.Group>
+              <InputOTP.Slot index={3} />
+              <InputOTP.Slot index={4} />
+              <InputOTP.Slot index={5} />
+            </InputOTP.Group>
+          </InputOTP>
+          <span className="field-error" data-visible={isInvalid} id="code-error">
+            Invalid code. Please try again.
+          </span>
+          <Button isDisabled={value.length !== 6} type="submit">
+            Submit
+          </Button>
+        </Form>
+      </div>
+    );
+  },
+};
+
+export const OnComplete: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState("");
+    const [isComplete, setIsComplete] = React.useState(false);
+    const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+    const handleComplete = (code: string) => {
+      setIsComplete(true);
+      // eslint-disable-next-line no-console
+      console.log("Code complete:", code);
+    };
+
+    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+
+      setIsSubmitting(true);
+      // Simulate API call
+      setTimeout(() => {
+        setIsSubmitting(false);
+        setValue("");
+        setIsComplete(false);
+      }, 2000);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-2" onSubmit={handleSubmit}>
+        <Label>Verify account</Label>
+        <InputOTP
+          {...args}
+          maxLength={6}
+          value={value}
+          onComplete={handleComplete}
+          onChange={(val) => {
+            setValue(val);
+            setIsComplete(false);
+          }}
+        >
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <Button
+          className="mt-2 w-full"
+          isDisabled={!isComplete}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? (
+            <>
+              <Spinner color="current" size="sm" />
+              Verifying...
+            </>
+          ) : (
+            "Verify Code"
+          )}
+        </Button>
+      </Form>
+    );
+  },
+};
+
+export const FormExample: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState("");
+    const [error, setError] = React.useState("");
+    const [isSubmitting, setIsSubmitting] = React.useState(false);
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+      setError("");
+
+      if (value.length !== 6) {
+        setError("Please enter all 6 digits");
+
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        if (value === "123456") {
+          // eslint-disable-next-line no-console
+          console.log("Code verified successfully!");
+          setValue("");
+        } else {
+          setError("Invalid code. Please try again.");
+        }
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <div className="flex flex-col gap-2">
+          <Label>Two-factor authentication</Label>
+          <Description>Enter the 6-digit code from your authenticator app</Description>
+          <InputOTP
+            {...args}
+            isInvalid={!!error}
+            maxLength={6}
+            value={value}
+            onChange={(val) => {
+              setValue(val);
+              setError("");
+            }}
+          >
+            <InputOTP.Group>
+              <InputOTP.Slot index={0} />
+              <InputOTP.Slot index={1} />
+              <InputOTP.Slot index={2} />
+            </InputOTP.Group>
+            <InputOTP.Separator />
+            <InputOTP.Group>
+              <InputOTP.Slot index={3} />
+              <InputOTP.Slot index={4} />
+              <InputOTP.Slot index={5} />
+            </InputOTP.Group>
+          </InputOTP>
+          <span className="field-error" data-visible={!!error} id="code-error">
+            {error}
+          </span>
+        </div>
+        <Button
+          className="w-full"
+          isDisabled={value.length !== 6}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? (
+            <>
+              <Spinner color="current" size="sm" />
+              Verifying...
+            </>
+          ) : (
+            "Verify"
+          )}
+        </Button>
+        <div className="flex items-center justify-center gap-1">
+          <p className="text-sm text-muted">Having trouble?</p>
+          <Link className="text-sm text-foreground" underline="always">
+            Use backup code
+          </Link>
+        </div>
+      </Form>
+    );
+  },
+};
diff --git a/packages/react/src/components/input-otp/input-otp.tsx b/packages/react/src/components/input-otp/input-otp.tsx
new file mode 100644
index 0000000..500ee2c
--- /dev/null
+++ b/packages/react/src/components/input-otp/input-otp.tsx
@@ -0,0 +1,161 @@
+"use client";
+
+import type {InputOTPVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {ValidationResult} from "react-aria-components/CheckboxGroup";
+
+import {inputOTPVariants} from "@heroui/styles";
+import {OTPInput, OTPInputContext} from "input-otp";
+import React, {createContext, use} from "react";
+import {FieldErrorContext} from "react-aria-components/FieldError";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * Input OTP Context
+ * -----------------------------------------------------------------------------------------------*/
+interface InputOTPContext {
+  slots?: ReturnType<typeof inputOTPVariants>;
+  isDisabled?: boolean;
+  isInvalid?: boolean;
+}
+
+const InputOTPContext = createContext<InputOTPContext>({
+  isDisabled: false,
+  isInvalid: false,
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * Input OTP Root
+ * -----------------------------------------------------------------------------------------------*/
+interface InputOTPRootProps
+  extends
+    Omit<ComponentPropsWithRef<typeof OTPInput>, "disabled" | "containerClassName" | "render">,
+    InputOTPVariants {
+  isDisabled?: boolean;
+  isInvalid?: boolean;
+  validationErrors?: string[];
+  validationDetails?: ValidityState;
+  inputClassName?: string;
+  children: React.ReactNode;
+}
+
+const InputOTPRoot = ({
+  className,
+  inputClassName,
+  isDisabled = false,
+  isInvalid = false,
+  validationDetails,
+  validationErrors = [],
+  variant,
+  ...props
+}: InputOTPRootProps) => {
+  const slots = React.useMemo(() => inputOTPVariants({variant}), [variant]);
+
+  const validation = React.useMemo(
+    () =>
+      ({
+        isInvalid,
+        validationErrors,
+        validationDetails,
+      }) as ValidationResult,
+    [isInvalid, validationErrors, validationDetails],
+  );
+
+  return (
+    <InputOTPContext value={{slots, isDisabled, isInvalid}}>
+      <FieldErrorContext value={validation}>
+        <OTPInput
+          // OTP Input package uses the `className` prop for the actual `input` element which is not visible to the user so no need to pass it to the base container
+          className={slots.input({className: inputClassName})}
+          containerClassName={slots.base({className})}
+          data-disabled={dataAttr(isDisabled)}
+          data-invalid={dataAttr(isInvalid)}
+          data-slot="input-otp"
+          disabled={isDisabled}
+          {...props}
+        />
+      </FieldErrorContext>
+    </InputOTPContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Input OTP Group
+ * -----------------------------------------------------------------------------------------------*/
+
+interface InputOTPGroupProps extends ComponentPropsWithRef<"div"> {}
+
+const InputOTPGroup = ({className, ...props}: InputOTPGroupProps) => {
+  const {slots} = use(InputOTPContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.group, className)}
+      data-slot="input-otp-group"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Input OTP Slot
+ * -----------------------------------------------------------------------------------------------*/
+interface InputOTPSlotProps extends ComponentPropsWithRef<"div"> {
+  index: number;
+}
+
+const InputOTPSlot = ({className, index, ...props}: InputOTPSlotProps) => {
+  const {isDisabled, isInvalid, slots} = use(InputOTPContext);
+
+  const inputOTPContext = use(OTPInputContext);
+  const {char, hasFakeCaret, isActive} = inputOTPContext?.slots[index] ?? {};
+
+  return (
+    <div
+      {...props}
+      className={composeSlotClassName(slots?.slot, className)}
+      data-active={dataAttr(isActive)}
+      data-disabled={dataAttr(isDisabled)}
+      data-filled={dataAttr(!!char)}
+      data-invalid={dataAttr(isInvalid)}
+      data-slot="input-otp-slot"
+    >
+      {char ? (
+        <div className={slots?.slotValue()} data-slot="input-otp-slot-value">
+          {char}
+        </div>
+      ) : null}
+      {hasFakeCaret && isActive ? (
+        <div className={slots?.caret()} data-slot="input-otp-caret" />
+      ) : null}
+    </div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Input OTP Separator
+ * -----------------------------------------------------------------------------------------------*/
+interface InputOTPSeparatorProps extends ComponentPropsWithRef<"div"> {
+  className?: string;
+}
+
+const InputOTPSeparator = ({className, ...props}: InputOTPSeparatorProps) => {
+  const {slots} = use(InputOTPContext);
+
+  return (
+    <div
+      className={composeSlotClassName(slots?.separator, className)}
+      data-slot="input-otp-separator"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {InputOTPRoot, InputOTPGroup, InputOTPSlot, InputOTPSeparator};
+
+export type {InputOTPRootProps, InputOTPGroupProps, InputOTPSlotProps, InputOTPSeparatorProps};
diff --git a/packages/react/src/components/input/index.ts b/packages/react/src/components/input/index.ts
new file mode 100644
index 0000000..019eac3
--- /dev/null
+++ b/packages/react/src/components/input/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {InputRoot} from "./input";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Input = Object.assign(InputRoot, {
+  Root: InputRoot,
+});
+
+export type Input = {
+  Props: ComponentProps<typeof InputRoot>;
+  RootProps: ComponentProps<typeof InputRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {InputRoot};
+
+export type {InputRootProps, InputRootProps as InputProps} from "./input";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {inputVariants} from "@heroui/styles";
+
+export type {InputVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/input/input.stories.tsx b/packages/react/src/components/input/input.stories.tsx
new file mode 100644
index 0000000..9f19161
--- /dev/null
+++ b/packages/react/src/components/input/input.stories.tsx
@@ -0,0 +1,85 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Surface} from "../surface";
+
+import {Input} from "./index";
+
+export default {
+  argTypes: {},
+  component: Input,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Forms/Input",
+} as Meta<typeof Input>;
+
+type Story = StoryObj<typeof Input>;
+
+export const Default: Story = {
+  render: () => <Input placeholder="Your name" />,
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex w-[240px] flex-col gap-2">
+      <Input fullWidth placeholder="Primary input" variant="primary" />
+      <Input fullWidth placeholder="Secondary input" variant="secondary" />
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-3">
+      <Input fullWidth placeholder="Full width input" />
+      <div className="flex h-[180px] items-center justify-center rounded-3xl bg-surface p-4">
+        <Surface className="w-full">
+          <Input fullWidth placeholder="Full width input on surface" variant="secondary" />
+        </Surface>
+      </div>
+    </div>
+  ),
+};
+
+export const OnSurfaces: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Default Surface</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <Input className="w-full" placeholder="Your name" variant="primary" />
+          <Input className="w-full" placeholder="Your name" variant="secondary" />
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary Surface</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <Input className="w-full" placeholder="Your name" variant="primary" />
+          <Input className="w-full" placeholder="Your name" variant="secondary" />
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Tertiary Surface</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <Input className="w-full" placeholder="Your name" variant="primary" />
+          <Input className="w-full" placeholder="Your name" variant="secondary" />
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Transparent Surface</p>
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <Input className="w-full" placeholder="Your name" variant="primary" />
+          <Input className="w-full" placeholder="Your name" variant="secondary" />
+        </Surface>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/input/input.tsx b/packages/react/src/components/input/input.tsx
new file mode 100644
index 0000000..a6c92dc
--- /dev/null
+++ b/packages/react/src/components/input/input.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {InputVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {inputVariants} from "@heroui/styles";
+import React, {use} from "react";
+import {Input as InputPrimitive} from "react-aria-components/Input";
+
+import {composeTwRenderProps} from "../../utils";
+import {ComboBoxContext} from "../combo-box";
+import {TextFieldContext} from "../textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * Input Root
+ * -----------------------------------------------------------------------------------------------*/
+interface InputRootProps extends ComponentPropsWithRef<typeof InputPrimitive>, InputVariants {}
+
+const InputRoot = ({className, fullWidth, variant: variantProp, ...rest}: InputRootProps) => {
+  const textFieldContext = use(TextFieldContext);
+  const comboBoxContext = use(ComboBoxContext);
+
+  // Use variant from context if not explicitly provided
+  const variant = variantProp ?? textFieldContext.variant ?? comboBoxContext.variant;
+
+  return (
+    <InputPrimitive
+      className={composeTwRenderProps(className, inputVariants({fullWidth, variant}))}
+      data-slot="input"
+      {...rest}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {InputRoot};
+
+export type {InputRootProps};
diff --git a/packages/react/src/components/kbd/index.ts b/packages/react/src/components/kbd/index.ts
new file mode 100644
index 0000000..6479a4f
--- /dev/null
+++ b/packages/react/src/components/kbd/index.ts
@@ -0,0 +1,40 @@
+import type {ComponentProps} from "react";
+
+import {KbdAbbr, KbdContent, KbdRoot} from "./kbd";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Kbd = Object.assign(KbdRoot, {
+  Root: KbdRoot,
+  Abbr: KbdAbbr,
+  Content: KbdContent,
+});
+
+export type Kbd = {
+  Props: ComponentProps<typeof KbdRoot>;
+  RootProps: ComponentProps<typeof KbdRoot>;
+  AbbrProps: ComponentProps<typeof KbdAbbr>;
+  ContentProps: ComponentProps<typeof KbdContent>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {KbdRoot, KbdAbbr, KbdContent};
+
+export type {KbdRootProps, KbdAbbrProps, KbdContentProps, KbdRootProps as KbdProps} from "./kbd";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {kbdVariants} from "@heroui/styles";
+
+export type {KbdVariants} from "@heroui/styles";
+
+/* -------------------------------------------------------------------------------------------------
+ * Constants
+ * -----------------------------------------------------------------------------------------------*/
+export {kbdKeysMap, kbdKeysLabelMap} from "./kbd.constants";
+
+export type {KbdKey} from "./kbd.constants";
diff --git a/packages/react/src/components/kbd/kbd.constants.ts b/packages/react/src/components/kbd/kbd.constants.ts
new file mode 100644
index 0000000..f6a1859
--- /dev/null
+++ b/packages/react/src/components/kbd/kbd.constants.ts
@@ -0,0 +1,73 @@
+export type KbdKey =
+  | "command"
+  | "shift"
+  | "ctrl"
+  | "option"
+  | "enter"
+  | "delete"
+  | "escape"
+  | "tab"
+  | "capslock"
+  | "up"
+  | "right"
+  | "down"
+  | "left"
+  | "pageup"
+  | "pagedown"
+  | "home"
+  | "end"
+  | "help"
+  | "space"
+  | "fn"
+  | "win"
+  | "alt";
+
+export const kbdKeysMap: Record<KbdKey, string> = {
+  command: "⌘",
+  shift: "⇧",
+  ctrl: "⌃",
+  option: "⌥",
+  enter: "↵",
+  delete: "⌫",
+  escape: "⎋",
+  tab: "⇥",
+  capslock: "⇪",
+  up: "↑",
+  right: "→",
+  down: "↓",
+  left: "←",
+  pageup: "⇞",
+  pagedown: "⇟",
+  home: "↖",
+  end: "↘",
+  help: "?",
+  space: "␣",
+  fn: "Fn",
+  win: "⌘",
+  alt: "⌥",
+};
+
+export const kbdKeysLabelMap: Record<KbdKey, string> = {
+  command: "Command",
+  shift: "Shift",
+  ctrl: "Control",
+  option: "Option",
+  enter: "Enter",
+  delete: "Delete",
+  escape: "Escape",
+  tab: "Tab",
+  capslock: "Caps Lock",
+  up: "Up",
+  right: "Right",
+  down: "Down",
+  left: "Left",
+  pageup: "Page Up",
+  pagedown: "Page Down",
+  home: "Home",
+  end: "End",
+  help: "Help",
+  space: "Space",
+  fn: "Fn",
+  win: "Win",
+  alt: "Alt",
+};
diff --git a/packages/react/src/components/kbd/kbd.stories.tsx b/packages/react/src/components/kbd/kbd.stories.tsx
new file mode 100644
index 0000000..ed33c69
--- /dev/null
+++ b/packages/react/src/components/kbd/kbd.stories.tsx
@@ -0,0 +1,299 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Kbd} from "./index";
+
+const meta: Meta<typeof Kbd> = {
+  title: "Components/Typography/Kbd",
+  component: Kbd,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "light"],
+    },
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Kbd>
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  ),
+};
+
+export const WithSingleKey: Story = {
+  render: () => (
+    <Kbd>
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  ),
+};
+
+export const WithMultipleKeys: Story = {
+  render: () => (
+    <Kbd>
+      <Kbd.Abbr keyValue="command" />
+      <Kbd.Abbr keyValue="shift" />
+      <Kbd.Content>K</Kbd.Content>
+    </Kbd>
+  ),
+};
+
+export const KeyCombinations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>Copy:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Paste:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Cut:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Undo:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Redo:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+    </div>
+  ),
+};
+
+export const LightVariant: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>Copy:</span>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>C</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Paste:</span>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>V</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Cut:</span>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>X</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Undo:</span>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Redo:</span>
+        <Kbd variant="light">
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>Z</Kbd.Content>
+        </Kbd>
+      </div>
+    </div>
+  ),
+};
+
+export const NavigationKeys: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Kbd>
+        <Kbd.Abbr keyValue="up" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="down" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="left" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="right" />
+      </Kbd>
+    </div>
+  ),
+};
+
+export const SpecialKeys: Story = {
+  render: () => (
+    <div className="grid grid-cols-4 gap-4">
+      <Kbd>
+        <Kbd.Abbr keyValue="enter" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="delete" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="escape" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="tab" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="capslock" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="space" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="pageup" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="pagedown" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="home" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="end" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="help" />
+      </Kbd>
+      <Kbd>
+        <Kbd.Abbr keyValue="fn" />
+      </Kbd>
+    </div>
+  ),
+};
+
+export const ComplexShortcuts: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>Open Spotlight:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="space" />
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Force Quit:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="option" />
+          <Kbd.Abbr keyValue="escape" />
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Screenshot:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>3</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Switch Apps:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="tab" />
+        </Kbd>
+      </div>
+    </div>
+  ),
+};
+
+export const InlineUsage: Story = {
+  render: () => (
+    <div className="space-y-2">
+      <p className="text-sm">
+        Press{" "}
+        <Kbd>
+          <Kbd.Content>Esc</Kbd.Content>
+        </Kbd>{" "}
+        to close the dialog.
+      </p>
+      <p className="text-sm">
+        Use{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Content>K</Kbd.Content>
+        </Kbd>{" "}
+        to open the command palette.
+      </p>
+      <p className="text-sm">
+        Navigate with{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="up" />
+        </Kbd>{" "}
+        and{" "}
+        <Kbd>
+          <Kbd.Abbr keyValue="down" />
+        </Kbd>{" "}
+        arrow keys.
+      </p>
+    </div>
+  ),
+};
+
+export const CustomContent: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <span>Select word:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="option" />
+          <Kbd.Abbr keyValue="left" />
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Delete line:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="ctrl" />
+          <Kbd.Content>K</Kbd.Content>
+        </Kbd>
+      </div>
+      <div className="flex items-center gap-2">
+        <span>Multiple modifiers:</span>
+        <Kbd>
+          <Kbd.Abbr keyValue="command" />
+          <Kbd.Abbr keyValue="option" />
+          <Kbd.Abbr keyValue="shift" />
+          <Kbd.Content>4</Kbd.Content>
+        </Kbd>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/kbd/kbd.tsx b/packages/react/src/components/kbd/kbd.tsx
new file mode 100644
index 0000000..d07cc18
--- /dev/null
+++ b/packages/react/src/components/kbd/kbd.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import type {KbdKey} from "./kbd.constants";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {KbdVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {kbdVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+import {kbdKeysLabelMap, kbdKeysMap} from "./kbd.constants";
+
+/* -------------------------------------------------------------------------------------------------
+ * Kbd Context
+ * -----------------------------------------------------------------------------------------------*/
+type KbdContext = {
+  slots?: ReturnType<typeof kbdVariants>;
+};
+
+const KbdContext = createContext<KbdContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Kbd Root
+ * -----------------------------------------------------------------------------------------------*/
+interface KbdRootProps<E extends keyof React.JSX.IntrinsicElements = "kbd"> extends DOMRenderProps<
+  E,
+  undefined
+> {
+  children: ReactNode;
+  className?: string;
+  /** Visual variant. */
+  variant?: KbdVariants["variant"];
+}
+
+const KbdRoot = <E extends keyof React.JSX.IntrinsicElements = "kbd">({
+  children,
+  className,
+  variant,
+  ...props
+}: KbdRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof KbdRootProps<E>>) => {
+  const slots = React.useMemo(() => kbdVariants({variant}), [variant]);
+
+  return (
+    <KbdContext value={{slots}}>
+      <dom.kbd {...(props as any)} className={slots.base({className})}>
+        {children}
+      </dom.kbd>
+    </KbdContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Kbd Abbr
+ * -----------------------------------------------------------------------------------------------*/
+interface KbdAbbrProps<E extends keyof React.JSX.IntrinsicElements = "abbr"> extends DOMRenderProps<
+  E,
+  undefined
+> {
+  className?: string;
+  /** The keyboard key to display */
+  keyValue: KbdKey;
+}
+
+const KbdAbbr = <E extends keyof React.JSX.IntrinsicElements = "abbr">({
+  className,
+  keyValue,
+  ...props
+}: KbdAbbrProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof KbdAbbrProps<E>>) => {
+  const {slots} = use(KbdContext);
+
+  return (
+    <dom.abbr
+      className={composeSlotClassName(slots?.abbr, className)}
+      title={kbdKeysLabelMap[keyValue]}
+      {...(props as any)}
+    >
+      {kbdKeysMap[keyValue]}
+    </dom.abbr>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Kbd Content
+ * -----------------------------------------------------------------------------------------------*/
+interface KbdContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+}
+
+const KbdContent = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: KbdContentProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof KbdContentProps<E>>) => {
+  const {slots} = use(KbdContext);
+
+  return (
+    <dom.span className={composeSlotClassName(slots?.content, className)} {...(props as any)}>
+      {children}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {KbdRoot, KbdAbbr, KbdContent};
+
+export type {KbdRootProps, KbdAbbrProps, KbdContentProps};
diff --git a/packages/react/src/components/label/index.ts b/packages/react/src/components/label/index.ts
new file mode 100644
index 0000000..2db9a2d
--- /dev/null
+++ b/packages/react/src/components/label/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {LabelRoot} from "./label";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Label = Object.assign(LabelRoot, {
+  Root: LabelRoot,
+});
+
+export type Label = {
+  Props: ComponentProps<typeof LabelRoot>;
+  RootProps: ComponentProps<typeof LabelRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {LabelRoot};
+
+export type {LabelRootProps, LabelRootProps as LabelProps} from "./label";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {labelVariants} from "@heroui/styles";
+
+export type {LabelVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/label/label.tsx b/packages/react/src/components/label/label.tsx
new file mode 100644
index 0000000..9fd6e91
--- /dev/null
+++ b/packages/react/src/components/label/label.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import type {LabelVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {labelVariants} from "@heroui/styles";
+import {Label as LabelPrimitive} from "react-aria-components/Label";
+
+/* -------------------------------------------------------------------------------------------------
+ * Label Root
+ * -----------------------------------------------------------------------------------------------*/
+interface LabelRootProps extends ComponentPropsWithRef<typeof LabelPrimitive>, LabelVariants {}
+
+const LabelRoot = ({
+  children,
+  className,
+  isDisabled,
+  isInvalid,
+  isRequired,
+  ...rest
+}: LabelRootProps) => {
+  return (
+    <LabelPrimitive
+      className={labelVariants({isRequired, isDisabled, isInvalid, className})}
+      data-slot="label"
+      {...rest}
+    >
+      {children}
+    </LabelPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {LabelRoot};
+
+export type {LabelRootProps};
diff --git a/packages/react/src/components/link/index.ts b/packages/react/src/components/link/index.ts
new file mode 100644
index 0000000..31d5c2f
--- /dev/null
+++ b/packages/react/src/components/link/index.ts
@@ -0,0 +1,31 @@
+import type {ComponentProps} from "react";
+
+import {LinkIcon, LinkRoot} from "./link";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Link = Object.assign(LinkRoot, {
+  Root: LinkRoot,
+  Icon: LinkIcon,
+});
+
+export type Link = {
+  Props: ComponentProps<typeof LinkRoot>;
+  RootProps: ComponentProps<typeof LinkRoot>;
+  IconProps: ComponentProps<typeof LinkIcon>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {LinkRoot, LinkIcon};
+
+export type {LinkRootProps, LinkIconProps, LinkRootProps as LinkProps} from "./link";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {linkVariants} from "@heroui/styles";
+
+export type {LinkVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/link/link.stories.tsx b/packages/react/src/components/link/link.stories.tsx
new file mode 100644
index 0000000..b6da956
--- /dev/null
+++ b/packages/react/src/components/link/link.stories.tsx
@@ -0,0 +1,146 @@
+import type {LinkProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {buttonVariants} from "../button/index";
+import {ExternalLinkIcon} from "../icons";
+
+import {Link} from "./index";
+
+export default {
+  argTypes: {},
+  component: Link,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/Link",
+} as Meta<typeof Link>;
+
+const DefaultTemplate = (_props: Link["RootProps"]) => (
+  <div className="flex items-center gap-4">
+    <Link href="#">
+      Call to action
+      <Link.Icon />
+    </Link>
+    <Link isDisabled href="#">
+      Call to action
+      <Link.Icon />
+    </Link>
+    <Link
+      href="https://heroui.com"
+      rel="noopener noreferrer"
+      target="_blank"
+      className={buttonVariants({
+        className: "gap-0 px-3 py-0.5 no-underline",
+        size: "md",
+        variant: "tertiary",
+      })}
+    >
+      HeroUI
+      <Link.Icon className="h-2 w-2" />
+    </Link>
+  </div>
+);
+
+const CustomIconTemplate = (_props: Link["RootProps"]) => (
+  <div className="flex items-center gap-4">
+    <Link href="#">
+      External Link
+      <Link.Icon>
+        <ExternalLinkIcon className="h-3 w-3" />
+      </Link.Icon>
+    </Link>
+    <Link href="#">
+      <Link.Icon>
+        <svg className="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
+          <path d="M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5ZM9.5 4a1.5 1.5 0 1 1 0 3 1.5 1.5 0 0 1 0-3ZM12 15H8a1 1 0 0 1 0-2h1v-3H8a1 1 0 0 1 0-2h2a1 1 0 0 1 1 1v4h1a1 1 0 0 1 0 2Z" />
+        </svg>
+      </Link.Icon>
+      Info Link
+    </Link>
+  </div>
+);
+
+const IconPlacementTemplate = (_props: Link["RootProps"]) => (
+  <div className="flex flex-col gap-4">
+    <Link href="#">
+      Icon at end (default)
+      <Link.Icon />
+    </Link>
+    <Link href="#">
+      <Link.Icon />
+      Icon at start
+    </Link>
+  </div>
+);
+
+const UnderlineVariantsTemplate = (_props: LinkProps) => (
+  <div className="flex flex-col gap-6">
+    <div className="flex flex-col gap-2">
+      <p className="text-sm text-muted">Default hover underline</p>
+      <Link href="#">
+        Hover to see the underline
+        <Link.Icon />
+      </Link>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <p className="text-sm text-muted">Always visible underline</p>
+      <Link className="underline" href="#">
+        Underline always visible
+        <Link.Icon />
+      </Link>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <p className="text-sm text-muted">No underline</p>
+      <Link className="no-underline" href="#">
+        Link without any underline
+        <Link.Icon />
+      </Link>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <p className="text-sm text-muted">Changing the underline offset</p>
+      <div className="flex flex-col gap-3">
+        <Link className="underline-offset-1" href="#">
+          Offset 1 (1px space)
+          <Link.Icon />
+        </Link>
+        <Link className="underline-offset-2" href="#">
+          Offset 2 (2px space)
+          <Link.Icon />
+        </Link>
+        <Link className="underline-offset-3" href="#">
+          Offset 3 (3px space)
+          <Link.Icon />
+        </Link>
+        <Link className="underline-offset-4" href="#">
+          Offset 4 (4px space)
+          <Link.Icon />
+        </Link>
+      </div>
+    </div>
+  </div>
+);
+
+export const Default = {
+  args: {},
+  render: DefaultTemplate,
+};
+
+export const CustomIcon = {
+  args: {},
+  render: CustomIconTemplate,
+};
+
+export const IconPlacement = {
+  args: {},
+  render: IconPlacementTemplate,
+};
+
+export const UnderlineVariants = {
+  args: {},
+  render: UnderlineVariantsTemplate,
+};
diff --git a/packages/react/src/components/link/link.tsx b/packages/react/src/components/link/link.tsx
new file mode 100644
index 0000000..e224d84
--- /dev/null
+++ b/packages/react/src/components/link/link.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {LinkVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {linkVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Link as LinkPrimitive} from "react-aria-components/Link";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {ExternalLinkIcon} from "../icons";
+
+/* ------------------------------------------------------------------------------------------------
+ * Link Context
+ * --------------------------------------------------------------------------------------------- */
+type LinkContext = {
+  slots?: ReturnType<typeof linkVariants>;
+};
+
+const LinkContext = createContext<LinkContext>({});
+
+/* ------------------------------------------------------------------------------------------------
+ * Link Root
+ * --------------------------------------------------------------------------------------------- */
+interface LinkRootProps extends ComponentPropsWithRef<typeof LinkPrimitive>, LinkVariants {}
+
+const LinkRoot = ({children, className, ...props}: LinkRootProps) => {
+  const slots = React.useMemo(() => linkVariants(), []);
+
+  return (
+    <LinkContext value={{slots}}>
+      <LinkPrimitive {...props} className={composeTwRenderProps(className, slots?.base())}>
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </LinkPrimitive>
+    </LinkContext>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Link Icon
+ * --------------------------------------------------------------------------------------------- */
+interface LinkIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const LinkIcon = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...rest
+}: LinkIconProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof LinkIconProps<E>>) => {
+  const {slots} = use(LinkContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.icon, className)}
+      data-default-icon={dataAttr(!children)}
+      data-slot="link-icon"
+      {...(rest as any)}
+    >
+      {children ?? <ExternalLinkIcon data-slot="link-default-icon" />}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {LinkRoot, LinkIcon};
+
+export type {LinkRootProps, LinkIconProps};
diff --git a/packages/react/src/components/list-box-item/index.ts b/packages/react/src/components/list-box-item/index.ts
new file mode 100644
index 0000000..a57e5b1
--- /dev/null
+++ b/packages/react/src/components/list-box-item/index.ts
@@ -0,0 +1,34 @@
+import type {ComponentProps} from "react";
+
+import {ListBoxItemIndicator, ListBoxItemRoot} from "./list-box-item";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ListBoxItem = Object.assign(ListBoxItemRoot, {
+  Root: ListBoxItemRoot,
+  Indicator: ListBoxItemIndicator,
+});
+
+export type ListBoxItem = {
+  Props: ComponentProps<typeof ListBoxItemRoot>;
+  RootProps: ComponentProps<typeof ListBoxItemRoot>;
+  IndicatorProps: ComponentProps<typeof ListBoxItemIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxItemRoot, ListBoxItemIndicator};
+
+export type {
+  ListBoxItemRootProps,
+  ListBoxItemRootProps as ListBoxItemProps,
+  ListBoxItemIndicatorProps,
+} from "./list-box-item";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {listboxItemVariants} from "@heroui/styles";
+export type {ListBoxItemVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/list-box-item/list-box-item.tsx b/packages/react/src/components/list-box-item/list-box-item.tsx
new file mode 100644
index 0000000..d017ecc
--- /dev/null
+++ b/packages/react/src/components/list-box-item/list-box-item.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ListBoxItemVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {ListBoxItemRenderProps} from "react-aria-components/ListBox";
+
+import {listboxItemVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {ListBoxItem as ListBoxItemPrimitive} from "react-aria-components/ListBox";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ListBox Item Context
+ * -----------------------------------------------------------------------------------------------*/
+interface ListBoxItemContext {
+  slots?: ReturnType<typeof listboxItemVariants>;
+  state?: ListBoxItemRenderProps;
+}
+
+const ListBoxItemContext = createContext<ListBoxItemContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ListBox Item Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ListBoxItemRootProps
+  extends ComponentPropsWithRef<typeof ListBoxItemPrimitive>, ListBoxItemVariants {
+  className?: string;
+}
+
+const ListBoxItemRoot = ({children, className, variant, ...props}: ListBoxItemRootProps) => {
+  const slots = React.useMemo(() => listboxItemVariants({variant}), [variant]);
+
+  return (
+    <ListBoxItemPrimitive
+      className={composeTwRenderProps(className, slots.item())}
+      data-slot="list-box-item"
+      {...props}
+    >
+      {(values) => (
+        <ListBoxItemContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </ListBoxItemContext>
+      )}
+    </ListBoxItemPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ListBox Item Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface ListBoxItemIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode | ((props: ListBoxItemRenderProps) => React.ReactNode);
+  className?: string;
+}
+
+const ListBoxItemIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: ListBoxItemIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ListBoxItemIndicatorProps<E>>) => {
+  const {slots, state} = use(ListBoxItemContext);
+  const isSelected = state?.isSelected;
+
+  const content =
+    typeof children === "function" ? (
+      children(state ?? ({} as ListBoxItemRenderProps))
+    ) : children ? (
+      children
+    ) : (
+      <svg
+        aria-hidden="true"
+        data-slot="list-box-item-indicator--checkmark"
+        fill="none"
+        role="presentation"
+        stroke="currentColor"
+        strokeDasharray={22}
+        strokeDashoffset={isSelected ? 44 : 66}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        viewBox="0 0 17 18"
+      >
+        <polyline points="1 9 7 14 15 4" />
+      </svg>
+    );
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="list-box-item-indicator"
+      data-visible={isSelected || undefined}
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxItemRoot, ListBoxItemIndicator};
+
+export type {ListBoxItemRootProps, ListBoxItemIndicatorProps};
diff --git a/packages/react/src/components/list-box-section/index.ts b/packages/react/src/components/list-box-section/index.ts
new file mode 100644
index 0000000..beb6890
--- /dev/null
+++ b/packages/react/src/components/list-box-section/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {ListBoxSectionRoot} from "./list-box-section";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ListBoxSection = ListBoxSectionRoot;
+
+export type ListBoxSection = {
+  Props: ComponentProps<typeof ListBoxSectionRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxSectionRoot};
+
+export type {
+  ListBoxSectionRootProps,
+  ListBoxSectionRootProps as ListBoxSectionProps,
+} from "./list-box-section";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {listboxSectionVariants} from "@heroui/styles";
+
+export type {ListBoxSectionVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/list-box-section/list-box-section.tsx b/packages/react/src/components/list-box-section/list-box-section.tsx
new file mode 100644
index 0000000..1c25949
--- /dev/null
+++ b/packages/react/src/components/list-box-section/list-box-section.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import type {ComponentPropsWithRef} from "react";
+
+import {listboxSectionVariants} from "@heroui/styles";
+import React from "react";
+import {ListBoxSection as ListBoxSectionPrimitive} from "react-aria-components/ListBox";
+
+/* -------------------------------------------------------------------------------------------------
+ * ListBox Section Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ListBoxSectionRootProps extends ComponentPropsWithRef<typeof ListBoxSectionPrimitive> {
+  className?: string;
+}
+
+const ListBoxSectionRoot = ({children, className, ...props}: ListBoxSectionRootProps) => {
+  const styles = React.useMemo(
+    () => listboxSectionVariants({class: typeof className === "string" ? className : undefined}),
+    [className],
+  );
+
+  return (
+    <ListBoxSectionPrimitive className={styles} {...props}>
+      {children}
+    </ListBoxSectionPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxSectionRoot};
+
+export type {ListBoxSectionRootProps};
diff --git a/packages/react/src/components/list-box/index.ts b/packages/react/src/components/list-box/index.ts
new file mode 100644
index 0000000..6361316
--- /dev/null
+++ b/packages/react/src/components/list-box/index.ts
@@ -0,0 +1,37 @@
+import type {ComponentProps} from "react";
+
+import {ListBoxItem, ListBoxItemIndicator} from "../list-box-item";
+import {ListBoxSection} from "../list-box-section";
+
+import {ListBoxRoot} from "./list-box";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ListBox = Object.assign(ListBoxRoot, {
+  Root: ListBoxRoot,
+  Item: ListBoxItem,
+  ItemIndicator: ListBoxItemIndicator,
+  Section: ListBoxSection,
+});
+
+export type ListBox = {
+  Props: ComponentProps<typeof ListBoxRoot>;
+  RootProps: ComponentProps<typeof ListBoxRoot>;
+  ItemProps: ComponentProps<typeof ListBoxItem>;
+  SectionProps: ComponentProps<typeof ListBoxSection>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxRoot};
+
+export type {ListBoxRootProps, ListBoxRootProps as ListBoxProps} from "./list-box";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {listboxVariants} from "@heroui/styles";
+
+export type {ListBoxVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/list-box/list-box.stories.tsx b/packages/react/src/components/list-box/list-box.stories.tsx
new file mode 100644
index 0000000..3c3ccfb
--- /dev/null
+++ b/packages/react/src/components/list-box/list-box.stories.tsx
@@ -0,0 +1,458 @@
+import type {Selection} from "@react-types/shared";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import * as React from "react";
+import {ListLayout, Virtualizer} from "react-aria-components/Virtualizer";
+
+import {Avatar, AvatarFallback, AvatarImage} from "../avatar";
+import {Description} from "../description";
+import {Header} from "../header";
+import {Kbd} from "../kbd";
+import {Label} from "../label";
+import {Separator} from "../separator";
+import {Surface} from "../surface";
+
+import {ListBox} from "./index";
+
+const meta: Meta<typeof ListBox> = {
+  component: ListBox,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Collections/ListBox",
+};
+
+export default meta;
+type Story = StoryObj<typeof ListBox>;
+
+export const Default: Story = {
+  render: () => (
+    <ListBox aria-label="Users" className="w-[220px]" selectionMode="single">
+      <ListBox.Item id="1" textValue="Bob">
+        <Avatar size="sm">
+          <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+          <AvatarFallback>B</AvatarFallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Bob</Label>
+          <Description>bob@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="2" textValue="Fred">
+        <Avatar size="sm">
+          <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+          <AvatarFallback>F</AvatarFallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Fred</Label>
+          <Description>fred@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+      <ListBox.Item id="3" textValue="Martha">
+        <Avatar size="sm">
+          <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+          <AvatarFallback>M</AvatarFallback>
+        </Avatar>
+        <div className="flex flex-col">
+          <Label>Martha</Label>
+          <Description>martha@heroui.com</Description>
+        </div>
+        <ListBox.ItemIndicator />
+      </ListBox.Item>
+    </ListBox>
+  ),
+};
+
+export const WithSections: Story = {
+  render: () => (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="File actions"
+        className="w-full p-2"
+        selectionMode="none"
+        onAction={(key) => alert(`Selected item: ${key}`)}
+      >
+        <ListBox.Section>
+          <Header>Actions</Header>
+          <ListBox.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="Edit file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:pencil" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Edit file</Label>
+              <Description>Make changes</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>Danger zone</Header>
+          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  ),
+};
+
+export const WithDisabledItems: Story = {
+  render: () => (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox
+        aria-label="File actions"
+        className="w-full p-2"
+        disabledKeys={["delete-file"]}
+        selectionMode="none"
+        onAction={(key) => alert(`Selected item: ${key}`)}
+      >
+        <ListBox.Section>
+          <Header>Actions</Header>
+          <ListBox.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:square-plus" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="Edit file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-muted" icon="gravity-ui:pencil" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Edit file</Label>
+              <Description>Make changes</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>Danger zone</Header>
+          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Icon className="size-4 shrink-0 text-danger" icon="gravity-ui:trash-bin" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  ),
+};
+
+export const MultiSelect: Story = {
+  render: () => (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="Users" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+            <AvatarFallback>B</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+            <AvatarFallback>F</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+            <AvatarFallback>M</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator />
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  ),
+};
+
+export const CustomCheckIcon: Story = {
+  render: () => (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="Users" selectionMode="multiple">
+        <ListBox.Item id="1" textValue="Bob">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+            <AvatarFallback>B</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Bob</Label>
+            <Description>bob@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Icon className="size-4 text-accent" icon="gravity-ui:check" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="2" textValue="Fred">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+            <AvatarFallback>F</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Fred</Label>
+            <Description>fred@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Icon className="size-4 text-accent" icon="gravity-ui:check" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+        <ListBox.Item id="3" textValue="Martha">
+          <Avatar size="sm">
+            <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+            <AvatarFallback>M</AvatarFallback>
+          </Avatar>
+          <div className="flex flex-col">
+            <Label>Martha</Label>
+            <Description>martha@heroui.com</Description>
+          </div>
+          <ListBox.ItemIndicator>
+            {({isSelected}) =>
+              isSelected ? <Icon className="size-4 text-accent" icon="gravity-ui:check" /> : null
+            }
+          </ListBox.ItemIndicator>
+        </ListBox.Item>
+      </ListBox>
+    </Surface>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Selection>(new Set(["1"]));
+
+    const selectedItems = Array.from(selected);
+
+    return (
+      <div className="space-y-4">
+        <Surface className="w-[256px] rounded-3xl shadow-surface">
+          <ListBox
+            aria-label="Users"
+            selectedKeys={selected}
+            selectionMode="multiple"
+            onSelectionChange={setSelected}
+          >
+            <ListBox.Item id="1" textValue="Bob">
+              <Avatar size="sm">
+                <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+                <AvatarFallback>B</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>Bob</Label>
+                <Description>bob@heroui.com</Description>
+              </div>
+              <ListBox.ItemIndicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <Icon className="size-4 text-accent" icon="gravity-ui:check" />
+                  ) : null
+                }
+              </ListBox.ItemIndicator>
+            </ListBox.Item>
+            <ListBox.Item id="2" textValue="Fred">
+              <Avatar size="sm">
+                <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+                <AvatarFallback>F</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>Fred</Label>
+                <Description>fred@heroui.com</Description>
+              </div>
+              <ListBox.ItemIndicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <Icon className="size-4 text-accent" icon="gravity-ui:check" />
+                  ) : null
+                }
+              </ListBox.ItemIndicator>
+            </ListBox.Item>
+            <ListBox.Item id="3" textValue="Martha">
+              <Avatar size="sm">
+                <AvatarImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+                <AvatarFallback>M</AvatarFallback>
+              </Avatar>
+              <div className="flex flex-col">
+                <Label>Martha</Label>
+                <Description>martha@heroui.com</Description>
+              </div>
+              <ListBox.ItemIndicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <Icon className="size-4 text-accent" icon="gravity-ui:check" />
+                  ) : null
+                }
+              </ListBox.ItemIndicator>
+            </ListBox.Item>
+          </ListBox>
+        </Surface>
+        <p className="text-sm text-muted">
+          Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Virtualization: Story = {
+  render: () => {
+    const firstNames = [
+      "Emma",
+      "Liam",
+      "Olivia",
+      "Noah",
+      "Ava",
+      "James",
+      "Sophia",
+      "Oliver",
+      "Isabella",
+      "Lucas",
+      "Mia",
+      "Ethan",
+      "Charlotte",
+      "Mason",
+      "Amelia",
+      "Logan",
+      "Harper",
+      "Alexander",
+      "Ella",
+      "Benjamin",
+    ];
+
+    const lastNames = [
+      "Smith",
+      "Johnson",
+      "Williams",
+      "Brown",
+      "Jones",
+      "Garcia",
+      "Miller",
+      "Davis",
+      "Rodriguez",
+      "Martinez",
+      "Anderson",
+      "Taylor",
+      "Thomas",
+      "Jackson",
+      "White",
+      "Harris",
+      "Clark",
+      "Lewis",
+      "Robinson",
+      "Walker",
+    ];
+
+    interface User {
+      id: number;
+      name: string;
+      email: string;
+    }
+
+    function generateUsers(n: number): User[] {
+      const users: User[] = [];
+
+      for (let i = 0; i < n; i++) {
+        const firstName = firstNames[i % firstNames.length];
+        const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+        const name = `${firstName} ${lastName}`;
+
+        users.push({
+          id: i + 1,
+          name,
+          email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
+        });
+      }
+
+      return users;
+    }
+
+    const users = generateUsers(1000);
+
+    return (
+      <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}>
+        <ListBox
+          aria-label="Virtualized list with 1000 items"
+          className="h-[400px] w-[300px] overflow-y-auto"
+          items={users}
+        >
+          {(user) => (
+            <ListBox.Item id={user.id} textValue={user.name}>
+              <div className="flex flex-col">
+                <Label>{user.name}</Label>
+                <Description>{user.email}</Description>
+              </div>
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          )}
+        </ListBox>
+      </Virtualizer>
+    );
+  },
+};
diff --git a/packages/react/src/components/list-box/list-box.tsx b/packages/react/src/components/list-box/list-box.tsx
new file mode 100644
index 0000000..5a23826
--- /dev/null
+++ b/packages/react/src/components/list-box/list-box.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {ListBoxVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {listboxVariants} from "@heroui/styles";
+import React from "react";
+import {ListBox as ListBoxPrimitive} from "react-aria-components/ListBox";
+
+import {composeTwRenderProps} from "../../utils";
+
+/* -------------------------------------------------------------------------------------------------
+ * ListBox Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ListBoxRootProps<T extends object>
+  extends ComponentPropsWithRef<typeof ListBoxPrimitive<T>>, ListBoxVariants {
+  className?: string;
+}
+
+function ListBoxRoot<T extends object>({className, variant, ...props}: ListBoxRootProps<T>) {
+  const styles = React.useMemo(() => listboxVariants({variant}), [variant]);
+
+  return (
+    <ListBoxPrimitive
+      className={composeTwRenderProps(className, styles)}
+      data-slot="list-box"
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ListBoxRoot};
+
+export type {ListBoxRootProps};
diff --git a/packages/react/src/components/menu-item/index.ts b/packages/react/src/components/menu-item/index.ts
new file mode 100644
index 0000000..f134027
--- /dev/null
+++ b/packages/react/src/components/menu-item/index.ts
@@ -0,0 +1,37 @@
+import type {ComponentProps} from "react";
+
+import {MenuItemIndicator, MenuItemRoot, MenuItemSubmenuIndicator} from "./menu-item";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const MenuItem = Object.assign(MenuItemRoot, {
+  Root: MenuItemRoot,
+  Indicator: MenuItemIndicator,
+  SubmenuIndicator: MenuItemSubmenuIndicator,
+});
+
+export type MenuItem = {
+  Props: ComponentProps<typeof MenuItemRoot>;
+  RootProps: ComponentProps<typeof MenuItemRoot>;
+  IndicatorProps: ComponentProps<typeof MenuItemIndicator>;
+  SubmenuIndicatorProps: ComponentProps<typeof MenuItemSubmenuIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuItemRoot, MenuItemIndicator, MenuItemSubmenuIndicator};
+
+export type {
+  MenuItemRootProps,
+  MenuItemRootProps as MenuItemProps,
+  MenuItemIndicatorProps,
+  MenuItemSubmenuIndicatorProps,
+} from "./menu-item";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {menuItemVariants} from "@heroui/styles";
+export type {MenuItemVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/menu-item/menu-item.tsx b/packages/react/src/components/menu-item/menu-item.tsx
new file mode 100644
index 0000000..4e62396
--- /dev/null
+++ b/packages/react/src/components/menu-item/menu-item.tsx
@@ -0,0 +1,165 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {MenuItemVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {MenuItemRenderProps} from "react-aria-components/Menu";
+
+import {menuItemVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {MenuItem as MenuItemPrimitive} from "react-aria-components/Menu";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils";
+import {dom} from "../../utils/dom";
+import {IconChevronRight} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Item Context
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuItemContext {
+  slots?: ReturnType<typeof menuItemVariants>;
+  state?: MenuItemRenderProps;
+}
+
+const MenuItemContext = createContext<MenuItemContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Item Root
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuItemRootProps
+  extends ComponentPropsWithRef<typeof MenuItemPrimitive>, MenuItemVariants {
+  className?: string;
+}
+
+const MenuItemRoot = ({children, className, variant, ...props}: MenuItemRootProps) => {
+  const slots = React.useMemo(() => menuItemVariants({variant}), [variant]);
+
+  return (
+    <MenuItemPrimitive
+      className={composeTwRenderProps(className, slots.item())}
+      data-slot="menu-item"
+      {...props}
+    >
+      {(values) => (
+        <MenuItemContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </MenuItemContext>
+      )}
+    </MenuItemPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Item Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuItemIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode | ((props: MenuItemRenderProps) => React.ReactNode);
+  className?: string;
+  type?: "checkmark" | "dot";
+}
+
+const MenuItemIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  type = "checkmark",
+  ...props
+}: MenuItemIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof MenuItemIndicatorProps<E>>) => {
+  const {slots, state} = use(MenuItemContext);
+  const isSelected = state?.isSelected;
+
+  const content =
+    typeof children === "function" ? (
+      children(state ?? ({} as MenuItemRenderProps))
+    ) : children ? (
+      children
+    ) : type === "dot" ? (
+      <svg
+        aria-hidden="true"
+        data-slot="menu-item-indicator--dot"
+        fill="currentColor"
+        fillRule="evenodd"
+        role="presentation"
+        viewBox="0 0 16 16"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path clipRule="evenodd" d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14" fillRule="evenodd" />
+      </svg>
+    ) : (
+      <svg
+        aria-hidden="true"
+        data-slot="menu-item-indicator--checkmark"
+        fill="none"
+        role="presentation"
+        stroke="currentColor"
+        strokeDasharray={22}
+        strokeDashoffset={isSelected ? 44 : 66}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        viewBox="0 0 17 18"
+      >
+        <polyline points="1 9 7 14 15 4" />
+      </svg>
+    );
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="menu-item-indicator"
+      data-type={type}
+      data-visible={isSelected || undefined}
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Item Submenu Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuItemSubmenuIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+const MenuItemSubmenuIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: MenuItemSubmenuIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof MenuItemSubmenuIndicatorProps<E>>) => {
+  const {slots, state} = use(MenuItemContext);
+  const hasSubmenu = state?.hasSubmenu;
+
+  if (!hasSubmenu) {
+    return null;
+  }
+
+  const defaultContent = <IconChevronRight />;
+  const content = children ?? defaultContent;
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.submenuIndicator, className)}
+      data-slot="submenu-indicator"
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuItemRoot, MenuItemIndicator, MenuItemSubmenuIndicator};
+
+export type {MenuItemRootProps, MenuItemIndicatorProps, MenuItemSubmenuIndicatorProps};
diff --git a/packages/react/src/components/menu-section/index.ts b/packages/react/src/components/menu-section/index.ts
new file mode 100644
index 0000000..da7dfae
--- /dev/null
+++ b/packages/react/src/components/menu-section/index.ts
@@ -0,0 +1,26 @@
+import type {ComponentProps} from "react";
+
+import {MenuSectionRoot} from "./menu-section";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const MenuSection = MenuSectionRoot;
+
+export type MenuSection = {
+  Props: ComponentProps<typeof MenuSectionRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuSectionRoot};
+
+export type {MenuSectionRootProps, MenuSectionRootProps as MenuSectionProps} from "./menu-section";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {menuSectionVariants} from "@heroui/styles";
+
+export type {MenuSectionVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/menu-section/menu-section.tsx b/packages/react/src/components/menu-section/menu-section.tsx
new file mode 100644
index 0000000..cb90c46
--- /dev/null
+++ b/packages/react/src/components/menu-section/menu-section.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import type {ComponentPropsWithRef} from "react";
+
+import {menuSectionVariants} from "@heroui/styles";
+import React from "react";
+import {MenuSection as MenuSectionPrimitive} from "react-aria-components/Menu";
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Section Root
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuSectionRootProps extends ComponentPropsWithRef<typeof MenuSectionPrimitive> {
+  className?: string;
+}
+
+const MenuSectionRoot = ({children, className, ...props}: MenuSectionRootProps) => {
+  const styles = React.useMemo(
+    () => menuSectionVariants({class: typeof className === "string" ? className : undefined}),
+    [className],
+  );
+
+  return (
+    <MenuSectionPrimitive className={styles} {...props}>
+      {children}
+    </MenuSectionPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuSectionRoot};
+
+export type {MenuSectionRootProps};
diff --git a/packages/react/src/components/menu/index.ts b/packages/react/src/components/menu/index.ts
new file mode 100644
index 0000000..ea22d6e
--- /dev/null
+++ b/packages/react/src/components/menu/index.ts
@@ -0,0 +1,39 @@
+import type {MenuItemRoot} from "../menu-item";
+import type {MenuSectionRoot} from "../menu-section";
+import type {ComponentProps} from "react";
+
+import {MenuItem, MenuItemIndicator} from "../menu-item";
+import {MenuSection} from "../menu-section";
+
+import {MenuRoot} from "./menu";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Menu = Object.assign(MenuRoot, {
+  Root: MenuRoot,
+  Item: MenuItem,
+  ItemIndicator: MenuItemIndicator,
+  Section: MenuSection,
+});
+
+export type Menu<T extends object = object> = {
+  Props: ComponentProps<typeof MenuRoot<T>>;
+  RootProps: ComponentProps<typeof MenuRoot<T>>;
+  ItemProps: ComponentProps<typeof MenuItemRoot>;
+  SectionProps: ComponentProps<typeof MenuSectionRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuRoot};
+
+export type {MenuRootProps, MenuRootProps as MenuProps} from "./menu";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {menuVariants} from "@heroui/styles";
+
+export type {MenuVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/menu/menu.tsx b/packages/react/src/components/menu/menu.tsx
new file mode 100644
index 0000000..5d4b396
--- /dev/null
+++ b/packages/react/src/components/menu/menu.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {MenuVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {menuVariants} from "@heroui/styles";
+import React from "react";
+import {Menu as MenuPrimitive} from "react-aria-components/Menu";
+
+import {composeTwRenderProps} from "../../utils";
+
+/* -------------------------------------------------------------------------------------------------
+ * Menu Root
+ * -----------------------------------------------------------------------------------------------*/
+interface MenuRootProps<T extends object>
+  extends ComponentPropsWithRef<typeof MenuPrimitive<T>>, MenuVariants {
+  className?: string;
+}
+
+function MenuRoot<T extends object>({className, ...props}: MenuRootProps<T>) {
+  const styles = React.useMemo(() => menuVariants(), []);
+
+  return (
+    <MenuPrimitive
+      className={composeTwRenderProps(className, styles)}
+      data-slot="menu"
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {MenuRoot};
+
+export type {MenuRootProps};
diff --git a/packages/react/src/components/meter/index.ts b/packages/react/src/components/meter/index.ts
new file mode 100644
index 0000000..cdb8ffd
--- /dev/null
+++ b/packages/react/src/components/meter/index.ts
@@ -0,0 +1,41 @@
+import type {ComponentProps} from "react";
+
+import {MeterFill, MeterOutput, MeterRoot, MeterTrack} from "./meter";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Meter = Object.assign(MeterRoot, {
+  Root: MeterRoot,
+  Output: MeterOutput,
+  Track: MeterTrack,
+  Fill: MeterFill,
+});
+
+export type Meter = {
+  Props: ComponentProps<typeof MeterRoot>;
+  RootProps: ComponentProps<typeof MeterRoot>;
+  OutputProps: ComponentProps<typeof MeterOutput>;
+  TrackProps: ComponentProps<typeof MeterTrack>;
+  FillProps: ComponentProps<typeof MeterFill>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {MeterRoot, MeterOutput, MeterTrack, MeterFill};
+
+export type {
+  MeterRootProps,
+  MeterRootProps as MeterProps,
+  MeterOutputProps,
+  MeterTrackProps,
+  MeterFillProps,
+} from "./meter";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {meterVariants} from "@heroui/styles";
+
+export type {MeterVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/meter/meter.stories.tsx b/packages/react/src/components/meter/meter.stories.tsx
new file mode 100644
index 0000000..6bda589
--- /dev/null
+++ b/packages/react/src/components/meter/meter.stories.tsx
@@ -0,0 +1,156 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Label} from "../label";
+
+import {Meter} from "./index";
+
+const meta: Meta<typeof Meter> = {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["default", "accent", "success", "warning", "danger"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: Meter,
+  decorators: [
+    (Story) => (
+      <div className="w-96 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Feedback/Meter",
+};
+
+export default meta;
+type Story = StoryObj<typeof Meter>;
+
+export const Default: Story = {
+  render: (args) => {
+    return (
+      <Meter value={60} {...args}>
+        <Label>Storage</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => {
+    return (
+      <div className="flex w-full flex-col gap-6">
+        <Meter size="sm" value={40} {...args}>
+          <Label>Small</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter size="md" value={60} {...args}>
+          <Label>Medium</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter size="lg" value={80} {...args}>
+          <Label>Large</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+      </div>
+    );
+  },
+};
+
+export const Colors: Story = {
+  render: (args) => {
+    return (
+      <div className="flex w-full flex-col gap-6">
+        <Meter color="default" value={50} {...args}>
+          <Label>Default</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter color="accent" value={50} {...args}>
+          <Label>Accent</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter color="success" value={50} {...args}>
+          <Label>Success</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter color="warning" value={50} {...args}>
+          <Label>Warning</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+        <Meter color="danger" value={50} {...args}>
+          <Label>Danger</Label>
+          <Meter.Output />
+          <Meter.Track>
+            <Meter.Fill />
+          </Meter.Track>
+        </Meter>
+      </div>
+    );
+  },
+};
+
+export const CustomValue: Story = {
+  render: (args) => {
+    return (
+      <Meter
+        formatOptions={{style: "currency", currency: "USD"}}
+        maxValue={1000}
+        minValue={0}
+        value={750}
+        {...args}
+      >
+        <Label>Revenue</Label>
+        <Meter.Output />
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    );
+  },
+};
+
+export const WithoutLabel: Story = {
+  render: (args) => {
+    return (
+      <Meter aria-label="Storage usage" value={45} {...args}>
+        <Meter.Track>
+          <Meter.Fill />
+        </Meter.Track>
+      </Meter>
+    );
+  },
+};
diff --git a/packages/react/src/components/meter/meter.tsx b/packages/react/src/components/meter/meter.tsx
new file mode 100644
index 0000000..9101443
--- /dev/null
+++ b/packages/react/src/components/meter/meter.tsx
@@ -0,0 +1,148 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {MeterVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {MeterRenderProps} from "react-aria-components/Meter";
+
+import {meterVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Meter as MeterPrimitive} from "react-aria-components/Meter";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Meter Context
+ * -----------------------------------------------------------------------------------------------*/
+interface MeterContext {
+  slots?: ReturnType<typeof meterVariants>;
+  state?: MeterRenderProps;
+}
+
+const MeterContext = createContext<MeterContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Meter Root
+ * -----------------------------------------------------------------------------------------------*/
+interface MeterRootProps extends ComponentPropsWithRef<typeof MeterPrimitive>, MeterVariants {}
+
+const MeterRoot = ({children, className, color, size, ...props}: MeterRootProps) => {
+  const slots = React.useMemo(() => meterVariants({color, size}), [color, size]);
+
+  return (
+    <MeterPrimitive
+      data-slot="meter"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(values) => (
+        <MeterContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </MeterContext>
+      )}
+    </MeterPrimitive>
+  );
+};
+
+MeterRoot.displayName = "HeroUI.Meter";
+
+/* -------------------------------------------------------------------------------------------------
+ * Meter Output
+ * -----------------------------------------------------------------------------------------------*/
+interface MeterOutputProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const MeterOutput = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: MeterOutputProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof MeterOutputProps<E>>) => {
+  const {slots, state} = use(MeterContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.output, className)}
+      data-slot="meter-output"
+      {...(props as any)}
+    >
+      {children ?? state?.valueText}
+    </dom.span>
+  );
+};
+
+MeterOutput.displayName = "HeroUI.Meter.Output";
+
+/* -------------------------------------------------------------------------------------------------
+ * Meter Track
+ * -----------------------------------------------------------------------------------------------*/
+interface MeterTrackProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const MeterTrack = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: MeterTrackProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof MeterTrackProps<E>>) => {
+  const {slots} = use(MeterContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.track, className)}
+      data-slot="meter-track"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+MeterTrack.displayName = "HeroUI.Meter.Track";
+
+/* -------------------------------------------------------------------------------------------------
+ * Meter Fill
+ * -----------------------------------------------------------------------------------------------*/
+interface MeterFillProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+const MeterFill = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  style,
+  ...props
+}: MeterFillProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof MeterFillProps<E>>) => {
+  const {slots, state} = use(MeterContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.fill, className)}
+      data-slot="meter-fill"
+      style={{
+        ...style,
+        width: `${state?.percentage ?? 0}%`,
+      }}
+      {...(props as any)}
+    />
+  );
+};
+
+MeterFill.displayName = "HeroUI.Meter.Fill";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {MeterRoot, MeterOutput, MeterTrack, MeterFill};
+
+export type {MeterRootProps, MeterOutputProps, MeterTrackProps, MeterFillProps};
diff --git a/packages/react/src/components/modal/index.ts b/packages/react/src/components/modal/index.ts
new file mode 100644
index 0000000..eae3f24
--- /dev/null
+++ b/packages/react/src/components/modal/index.ts
@@ -0,0 +1,86 @@
+import type {ComponentProps} from "react";
+
+import {
+  ModalBackdrop,
+  ModalBody,
+  ModalCloseTrigger,
+  ModalContainer,
+  ModalDialog,
+  ModalFooter,
+  ModalHeader,
+  ModalHeading,
+  ModalIcon,
+  ModalRoot,
+  ModalTrigger,
+} from "./modal";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Modal = Object.assign(ModalRoot, {
+  Root: ModalRoot,
+  Trigger: ModalTrigger,
+  Backdrop: ModalBackdrop,
+  Container: ModalContainer,
+  Dialog: ModalDialog,
+  Header: ModalHeader,
+  Icon: ModalIcon,
+  Heading: ModalHeading,
+  Body: ModalBody,
+  Footer: ModalFooter,
+  CloseTrigger: ModalCloseTrigger,
+});
+
+export type Modal = {
+  Props: ComponentProps<typeof ModalRoot>;
+  RootProps: ComponentProps<typeof ModalRoot>;
+  TriggerProps: ComponentProps<typeof ModalTrigger>;
+  BackdropProps: ComponentProps<typeof ModalBackdrop>;
+  ContainerProps: ComponentProps<typeof ModalContainer>;
+  DialogProps: ComponentProps<typeof ModalDialog>;
+  HeaderProps: ComponentProps<typeof ModalHeader>;
+  IconProps: ComponentProps<typeof ModalIcon>;
+  HeadingProps: ComponentProps<typeof ModalHeading>;
+  BodyProps: ComponentProps<typeof ModalBody>;
+  FooterProps: ComponentProps<typeof ModalFooter>;
+  CloseTriggerProps: ComponentProps<typeof ModalCloseTrigger>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  ModalRoot,
+  ModalTrigger,
+  ModalBackdrop,
+  ModalContainer,
+  ModalDialog,
+  ModalHeader,
+  ModalIcon,
+  ModalHeading,
+  ModalBody,
+  ModalFooter,
+  ModalCloseTrigger,
+};
+
+export type {
+  ModalRootProps,
+  ModalRootProps as ModalProps,
+  ModalTriggerProps,
+  ModalBackdropProps,
+  ModalContainerProps,
+  ModalDialogProps,
+  ModalHeaderProps,
+  ModalIconProps,
+  ModalHeadingProps,
+  ModalBodyProps,
+  ModalFooterProps,
+  ModalCloseTriggerProps,
+} from "./modal";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {modalVariants} from "@heroui/styles";
+
+export type {ModalVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/modal/modal.stories.tsx b/packages/react/src/components/modal/modal.stories.tsx
new file mode 100644
index 0000000..e0db97e
--- /dev/null
+++ b/packages/react/src/components/modal/modal.stories.tsx
@@ -0,0 +1,832 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useCallback, useRef, useState} from "react";
+
+import {useOverlayState} from "../../hooks/use-overlay-state";
+import {Button} from "../button";
+import {Input} from "../input";
+import {Label} from "../label";
+import {Radio} from "../radio";
+import {RadioGroup} from "../radio-group";
+import {Surface} from "../surface";
+import {TextField} from "../textfield";
+
+import {Modal} from "./index";
+
+export default {
+  argTypes: {},
+  component: Modal,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Overlays/Modal",
+} as Meta<typeof Modal>;
+
+export const Default = () => {
+  return (
+    <Modal>
+      <Button variant="secondary">Open Modal</Button>
+      <Modal.Backdrop>
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-[360px]">
+            <Modal.CloseTrigger />
+            <Modal.Header>
+              <Modal.Icon className="bg-default text-foreground">
+                <Icon className="size-5" icon="gravity-ui:rocket" />
+              </Modal.Icon>
+              <Modal.Heading>Welcome to HeroUI</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p>
+                A beautiful, fast, and modern React UI library for building accessible and
+                customizable web applications with ease.
+              </p>
+            </Modal.Body>
+            <Modal.Footer>
+              <Button className="w-full" slot="close">
+                Continue
+              </Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+};
+
+export const Placements = () => {
+  const placements = ["auto", "top", "center", "bottom"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {placements.map((placement) => (
+        <Modal key={placement}>
+          <Button variant="secondary">
+            {placement.charAt(0).toUpperCase() + placement.slice(1)}
+          </Button>
+          <Modal.Backdrop>
+            <Modal.Container placement={placement}>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Icon className="size-5" icon="gravity-ui:rocket" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Placement: {placement.charAt(0).toUpperCase() + placement.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    This modal uses the <code>{placement}</code> placement option. Try different
+                    placements to see how the modal positions itself on the screen.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Continue
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+};
+
+export const BackdropVariants = () => {
+  const variants = ["opaque", "blur", "transparent"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {variants.map((variant) => (
+        <Modal key={variant}>
+          <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button>
+          <Modal.Backdrop variant={variant}>
+            <Modal.Container>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Icon className="size-5" icon="gravity-ui:rocket" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    This modal uses the <code>{variant}</code> backdrop variant. Compare the
+                    different visual effects: opaque provides full opacity, blur adds a backdrop
+                    filter, and transparent removes the background.
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button className="w-full" slot="close">
+                    Continue
+                  </Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+};
+
+export const Sizes = () => {
+  const sizes = ["xs", "sm", "md", "lg", "cover", "full"] as const;
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {sizes.map((size) => (
+        <Modal key={size}>
+          <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button>
+          <Modal.Backdrop>
+            <Modal.Container size={size}>
+              <Modal.Dialog>
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Icon className="size-5" icon="gravity-ui:rocket" />
+                  </Modal.Icon>
+                  <Modal.Heading>
+                    Size: {size.charAt(0).toUpperCase() + size.slice(1)}
+                  </Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p>
+                    {size === "cover" ? (
+                      <>
+                        This modal uses the <code>cover</code> size variant. It spans the full
+                        screen with margins: 16px on mobile and 40px on desktop. Maintains rounded
+                        corners and standard padding. Perfect for cover-style content that needs
+                        maximum width while preserving modal aesthetics.
+                      </>
+                    ) : size === "full" ? (
+                      <>
+                        This modal uses the <code>full</code> size variant. It occupies the entire
+                        viewport without any margins, rounded corners, or shadows, creating a true
+                        fullscreen experience. Ideal for immersive content or full-page
+                        interactions.
+                      </>
+                    ) : (
+                      <>
+                        This modal uses the <code>{size}</code> size variant. On mobile devices, all
+                        sizes adapt to near full-width for optimal viewing. On desktop, each size
+                        provides a different maximum width to suit various content needs.
+                      </>
+                    )}
+                  </p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="secondary">
+                    Cancel
+                  </Button>
+                  <Button slot="close">Confirm</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+};
+
+export const CustomBackdrop = () => (
+  <Modal>
+    <Button variant="secondary">Custom Backdrop</Button>
+    <Modal.Backdrop
+      className="bg-linear-to-t from-black/80 via-black/40 to-transparent dark:from-zinc-800/80 dark:via-zinc-800/40"
+      variant="blur"
+    >
+      <Modal.Container>
+        <Modal.Dialog className="sm:max-w-[360px]">
+          <Modal.Header className="items-center text-center">
+            <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+              <Icon className="size-5" icon="gravity-ui:sparkles" />
+            </Modal.Icon>
+            <Modal.Heading>Premium Backdrop</Modal.Heading>
+          </Modal.Header>
+          <Modal.Body>
+            <p>
+              This backdrop features a sophisticated gradient that transitions from a dark color at
+              the bottom to complete transparency at the top, combined with a smooth blur effect.
+              The gradient automatically adapts its intensity for optimal contrast in both light and
+              dark modes.
+            </p>
+          </Modal.Body>
+          <Modal.Footer className="flex-col-reverse">
+            <Button className="w-full" slot="close">
+              Amazing!
+            </Button>
+            <Button className="w-full" slot="close" variant="secondary">
+              Close
+            </Button>
+          </Modal.Footer>
+          <Modal.CloseTrigger />
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  </Modal>
+);
+
+export const DismissBehavior = () => (
+  <div className="flex max-w-sm flex-col gap-6">
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">isDismissable</h3>
+      <p className="text-sm text-muted">
+        Controls whether the modal can be dismissed by clicking the overlay backdrop. Defaults to{" "}
+        <code>true</code>. Set to <code>false</code> to require explicit close action.
+      </p>
+      <Modal>
+        <Button variant="secondary">Open Modal</Button>
+        <Modal.Backdrop isDismissable={false}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-default text-foreground">
+                  <Icon className="size-5" icon="gravity-ui:circle-info" />
+                </Modal.Icon>
+                <Modal.Heading>isDismissable = false</Modal.Heading>
+                <p className="text-sm leading-5 text-muted">
+                  Clicking the backdrop won't close this modal
+                </p>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  Try clicking outside this modal on the overlay - it won't close. You must use the
+                  close button or press ESC to dismiss it.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button className="w-full" slot="close">
+                  Close
+                </Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3>
+      <p className="text-sm text-muted">
+        Controls whether the ESC key can dismiss the modal. When set to <code>true</code>, the ESC
+        key will be disabled and users must use explicit close actions.
+      </p>
+      <Modal>
+        <Button variant="secondary">Open Modal</Button>
+        <Modal.Backdrop isKeyboardDismissDisabled>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-default text-foreground">
+                  <Icon className="size-5" icon="gravity-ui:circle-info" />
+                </Modal.Icon>
+                <Modal.Heading>isKeyboardDismissDisabled = true</Modal.Heading>
+                <p className="text-sm leading-5 text-muted">ESC key is disabled</p>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  Press ESC - nothing happens. You must use the close button or click the overlay
+                  backdrop to dismiss this modal.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button className="w-full" slot="close">
+                  Close
+                </Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+  </div>
+);
+
+export const CloseMethods = () => (
+  <div className="flex max-w-2xl flex-col gap-8">
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">Using slot="close"</h3>
+      <p className="text-sm text-muted">
+        The simplest way to close a modal. Add <code>slot="close"</code> to any Button component
+        within the modal. When clicked, it will automatically close the modal.
+      </p>
+      <Modal>
+        <Button variant="secondary">Open Modal</Button>
+        <Modal.Backdrop>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.Header>
+                <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                  <Icon className="size-5" icon="gravity-ui:circle-info" />
+                </Modal.Icon>
+                <Modal.Heading>Using slot="close"</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  Click either button below - both have <code>slot="close"</code> and will close the
+                  modal automatically.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+
+    <div className="flex flex-col gap-2">
+      <h3 className="text-lg font-semibold">Using Dialog render props</h3>
+      <p className="text-sm text-muted">
+        Access the <code>close</code> method from the Dialog's render props. This gives you full
+        control over when and how to close the modal, allowing you to add custom logic before
+        closing.
+      </p>
+      <Modal>
+        <Button variant="secondary">Open Modal</Button>
+        <Modal.Backdrop>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              {(renderProps) => (
+                <>
+                  <Modal.Header>
+                    <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                      <Icon className="size-5" icon="gravity-ui:circle-check" />
+                    </Modal.Icon>
+                    <Modal.Heading>Using Dialog render props</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p>
+                      The buttons below use the <code>close</code> method from render props. You can
+                      add validation or other logic before calling <code>renderProps.close()</code>.
+                    </p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button variant="secondary" onPress={() => renderProps.close()}>
+                      Cancel
+                    </Button>
+                    <Button onPress={() => renderProps.close()}>Confirm</Button>
+                  </Modal.Footer>
+                </>
+              )}
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+  </div>
+);
+
+export const ScrollComparison = () => {
+  const [scroll, setScroll] = useState<"inside" | "outside">("inside");
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RadioGroup
+        orientation="horizontal"
+        value={scroll}
+        onChange={(value) => setScroll(value as "inside" | "outside")}
+      >
+        <Radio value="inside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            <Label>Inside</Label>
+          </Radio.Content>
+        </Radio>
+        <Radio value="outside">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            <Label>Outside</Label>
+          </Radio.Content>
+        </Radio>
+      </RadioGroup>
+
+      <Modal>
+        <Button variant="secondary">
+          Open Modal ({scroll.charAt(0).toUpperCase() + scroll.slice(1)})
+        </Button>
+        <Modal.Backdrop>
+          <Modal.Container scroll={scroll}>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.Header>
+                <Modal.Heading>
+                  Scroll: {scroll.charAt(0).toUpperCase() + scroll.slice(1)}
+                </Modal.Heading>
+                <p className="text-sm leading-5 text-muted">
+                  Compare scroll behaviors - inside keeps content scrollable within the modal,
+                  outside allows page scrolling
+                </p>
+              </Modal.Header>
+              <Modal.Body>
+                {Array.from({length: 30}).map((_, i) => (
+                  <p key={i} className="mb-3">
+                    Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                    Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet
+                    hendrerit risus, sed porttitor quam.
+                  </p>
+                ))}
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+              <Modal.CloseTrigger />
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </Modal>
+    </div>
+  );
+};
+
+export const Controlled = () => {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const state = useOverlayState();
+
+  return (
+    <div className="flex max-w-md flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Control the modal using React's <code className="text-foreground">useState</code> hook for
+          simple state management. Perfect for basic use cases.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}>
+              Open Modal
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                  <Icon className="size-5" icon="gravity-ui:circle-check" />
+                </Modal.Icon>
+                <Modal.Heading>Controlled with useState()</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  This modal is controlled by React's <code>useState</code> hook. Pass{" "}
+                  <code>isOpen</code> and <code>onOpenChange</code> props to manage the modal state
+                  externally.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3>
+        <p className="text-sm leading-relaxed text-pretty text-muted">
+          Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API
+          with convenient methods like <code>open()</code>, <code>close()</code>, and{" "}
+          <code>toggle()</code>.
+        </p>
+        <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm">
+          <div className="flex w-full items-center justify-between">
+            <p className="text-xs text-muted">
+              Status:{" "}
+              <span className="font-mono font-medium text-foreground">
+                {state.isOpen ? "open" : "closed"}
+              </span>
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button size="sm" variant="secondary" onPress={state.open}>
+              Open Modal
+            </Button>
+            <Button size="sm" variant="tertiary" onPress={state.toggle}>
+              Toggle
+            </Button>
+          </div>
+        </div>
+
+        <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}>
+          <Modal.Container>
+            <Modal.Dialog className="sm:max-w-[360px]">
+              <Modal.CloseTrigger />
+              <Modal.Header>
+                <Modal.Icon className="bg-success-soft text-success-soft-foreground">
+                  <Icon className="size-5" icon="gravity-ui:circle-check" />
+                </Modal.Icon>
+                <Modal.Heading>Controlled with useOverlayState()</Modal.Heading>
+              </Modal.Header>
+              <Modal.Body>
+                <p>
+                  The <code>useOverlayState</code> hook provides dedicated methods for common
+                  operations. No need to manually create callbacks—just use{" "}
+                  <code>state.open()</code>, <code>state.close()</code>, or{" "}
+                  <code>state.toggle()</code>.
+                </p>
+              </Modal.Body>
+              <Modal.Footer>
+                <Button slot="close" variant="secondary">
+                  Cancel
+                </Button>
+                <Button slot="close">Confirm</Button>
+              </Modal.Footer>
+            </Modal.Dialog>
+          </Modal.Container>
+        </Modal.Backdrop>
+      </div>
+    </div>
+  );
+};
+
+export const WithForm = () => (
+  <Modal>
+    <Button variant="secondary">Open Contact Form</Button>
+    <Modal.Backdrop>
+      <Modal.Container placement="auto">
+        <Modal.Dialog className="sm:max-w-md">
+          <Modal.CloseTrigger />
+          <Modal.Header>
+            <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+              <Icon className="size-5" icon="gravity-ui:envelope" />
+            </Modal.Icon>
+            <Modal.Heading>Contact Us</Modal.Heading>
+            <p className="mt-1.5 text-sm leading-5 text-muted">
+              Fill out the form below and we'll get back to you. The modal adapts automatically when
+              the keyboard appears on mobile.
+            </p>
+          </Modal.Header>
+          <Modal.Body>
+            <Surface variant="default">
+              <form className="flex flex-col gap-4">
+                <TextField className="w-full" name="name" type="text">
+                  <Label>Name</Label>
+                  <Input placeholder="Enter your name" />
+                </TextField>
+                <TextField className="w-full" name="email" type="email">
+                  <Label>Email</Label>
+                  <Input placeholder="Enter your email" />
+                </TextField>
+                <TextField className="w-full" name="phone" type="tel">
+                  <Label>Phone</Label>
+                  <Input placeholder="Enter your phone number" />
+                </TextField>
+                <TextField className="w-full" name="company">
+                  <Label>Company</Label>
+                  <Input placeholder="Enter your company name" />
+                </TextField>
+                <TextField className="w-full" name="message">
+                  <Label>Message</Label>
+                  <Input placeholder="Enter your message" />
+                </TextField>
+              </form>
+            </Surface>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button slot="close" variant="secondary">
+              Cancel
+            </Button>
+            <Button slot="close">Send Message</Button>
+          </Modal.Footer>
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  </Modal>
+);
+
+export const CustomTrigger = () => (
+  <Modal>
+    <Modal.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary">
+      <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-accent-soft text-accent-soft-foreground">
+        <Icon className="size-6" icon="gravity-ui:gear" />
+      </div>
+      <div className="flex flex-1 flex-col gap-0.5">
+        <p className="text-sm font-semibold">Settings</p>
+        <p className="text-xs text-muted">Manage your preferences</p>
+      </div>
+    </Modal.Trigger>
+    <Modal.Backdrop>
+      <Modal.Container>
+        <Modal.Dialog className="sm:max-w-[360px]">
+          <Modal.CloseTrigger />
+          <Modal.Header>
+            <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+              <Icon className="size-5" icon="gravity-ui:gear" />
+            </Modal.Icon>
+            <Modal.Heading>Settings</Modal.Heading>
+          </Modal.Header>
+          <Modal.Body>
+            <p>
+              Use <code>Modal.Trigger</code> to create custom trigger elements beyond standard
+              buttons. This example shows a card-style trigger with icons and descriptive text.
+            </p>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button slot="close" variant="secondary">
+              Cancel
+            </Button>
+            <Button slot="close">Save</Button>
+          </Modal.Footer>
+        </Modal.Dialog>
+      </Modal.Container>
+    </Modal.Backdrop>
+  </Modal>
+);
+
+export const CustomAnimations = () => {
+  const animations = [
+    {
+      name: "Kinematic Scale",
+      description:
+        "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Modals and Popovers.",
+      icon: "gravity-ui:sparkles",
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:zoom-in-95",
+          "data-[entering]:duration-400",
+          "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:zoom-out-95",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]",
+        ].join(" "),
+      },
+    },
+    {
+      name: "Fluid Slide",
+      description:
+        "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.",
+      icon: "gravity-ui:arrow-up-from-line",
+      classNames: {
+        backdrop: [
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+        container: [
+          "data-[entering]:animate-in",
+          "data-[entering]:fade-in-0",
+          "data-[entering]:slide-in-from-bottom-4",
+          "data-[entering]:duration-500",
+          "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]",
+          "data-[exiting]:animate-out",
+          "data-[exiting]:fade-out-0",
+          "data-[exiting]:slide-out-to-bottom-2",
+          "data-[exiting]:duration-200",
+          "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]",
+        ].join(" "),
+      },
+    },
+  ];
+
+  return (
+    <div className="flex flex-wrap gap-4">
+      {animations.map(({classNames, description, icon, name}) => (
+        <Modal key={name}>
+          <Button variant="secondary">{name}</Button>
+          <Modal.Backdrop className={classNames.backdrop}>
+            <Modal.Container className={classNames.container}>
+              <Modal.Dialog className="sm:max-w-[360px]">
+                <Modal.CloseTrigger />
+                <Modal.Header>
+                  <Modal.Icon className="bg-default text-foreground">
+                    <Icon className="size-5" icon={icon} />
+                  </Modal.Icon>
+                  <Modal.Heading>{name} Animation</Modal.Heading>
+                </Modal.Header>
+                <Modal.Body>
+                  <p className="mt-1">{description}</p>
+                </Modal.Body>
+                <Modal.Footer>
+                  <Button slot="close" variant="tertiary">
+                    Close
+                  </Button>
+                  <Button slot="close">Try Again</Button>
+                </Modal.Footer>
+              </Modal.Dialog>
+            </Modal.Container>
+          </Modal.Backdrop>
+        </Modal>
+      ))}
+    </div>
+  );
+};
+
+export const CustomPortal = () => {
+  const portalRef = useRef<HTMLDivElement>(null);
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+
+  const setPortalRef = useCallback((node: HTMLDivElement | null) => {
+    portalRef.current = node;
+    setPortalContainer(node);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-sm">
+          Render modals inside a custom container instead of <code>document.body</code>
+        </p>
+        <p className="text-sm text-muted">
+          Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the
+          container to create a new stacking context.
+        </p>
+      </div>
+      <div
+        ref={setPortalRef}
+        className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20"
+        // new stacking context
+        style={{transform: "translate(0)"}}
+      >
+        {!!portalContainer && (
+          <Modal>
+            <Button>Open Modal</Button>
+            <Modal.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}>
+              <Modal.Container className="h-full max-h-full">
+                <Modal.Dialog className="h-full max-h-full sm:max-w-md">
+                  <Modal.CloseTrigger />
+                  <Modal.Header>
+                    <Modal.Heading>Custom Portal</Modal.Heading>
+                  </Modal.Header>
+                  <Modal.Body>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                    <p className="text-sm text-muted">
+                      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                      incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+                      nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                    </p>
+                  </Modal.Body>
+                  <Modal.Footer>
+                    <Button slot="close" variant="secondary">
+                      Close
+                    </Button>
+                  </Modal.Footer>
+                </Modal.Dialog>
+              </Modal.Container>
+            </Modal.Backdrop>
+          </Modal>
+        )}
+      </div>
+    </div>
+  );
+};
diff --git a/packages/react/src/components/modal/modal.tsx b/packages/react/src/components/modal/modal.tsx
new file mode 100644
index 0000000..fe692ba
--- /dev/null
+++ b/packages/react/src/components/modal/modal.tsx
@@ -0,0 +1,398 @@
+"use client";
+
+import type {UseOverlayStateProps, UseOverlayStateReturn} from "../../hooks/use-overlay-state";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {ModalVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {Button as ButtonPrimitive} from "react-aria-components/Button";
+import type {DialogProps as DialogPrimitiveProps} from "react-aria-components/Dialog";
+
+import {modalVariants} from "@heroui/styles";
+import {mergeProps} from "@react-aria/utils";
+import {createContext, use, useMemo} from "react";
+import {
+  Dialog as DialogPrimitive,
+  Heading as HeadingPrimitive,
+  DialogTrigger as ModalTriggerPrimitive,
+} from "react-aria-components/Dialog";
+import {
+  ModalOverlay as ModalOverlayPrimitive,
+  Modal as ModalPrimitive,
+  Pressable as PressablePrimitive,
+} from "react-aria-components/Modal";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CloseButton} from "../close-button";
+import {SurfaceContext} from "../surface";
+
+type ModalPlacement = "auto" | "top" | "center" | "bottom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Context
+ * -----------------------------------------------------------------------------------------------*/
+type ModalContext = {
+  slots?: ReturnType<typeof modalVariants>;
+  placement?: ModalPlacement;
+};
+
+const ModalContext = createContext<ModalContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalRootProps extends ComponentPropsWithRef<typeof ModalTriggerPrimitive> {
+  state?: UseOverlayStateReturn;
+}
+
+const ModalRoot = ({children, state, ...props}: ModalRootProps) => {
+  const modalContext = useMemo<ModalContext>(
+    () => ({slots: modalVariants(), placement: undefined}),
+    [],
+  );
+
+  const controlledProps = useMemo<UseOverlayStateProps>(
+    () => (state ? {isOpen: state.isOpen, onOpenChange: state.setOpen} : {}),
+    [state],
+  );
+
+  return (
+    <ModalContext value={modalContext}>
+      <ModalTriggerPrimitive data-slot="modal-root" {...mergeProps(props, controlledProps)}>
+        {children}
+      </ModalTriggerPrimitive>
+    </ModalContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalTriggerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ModalTrigger = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ModalTriggerProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ModalTriggerProps<E>>) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <PressablePrimitive>
+      <dom.div
+        className={composeSlotClassName(slots?.trigger, className)}
+        data-slot="modal-trigger"
+        role="button"
+        {...(props as any)}
+      >
+        {children}
+      </dom.div>
+    </PressablePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Backdrop
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalBackdropProps extends ComponentPropsWithRef<typeof ModalOverlayPrimitive> {
+  variant?: ModalVariants["variant"];
+  /**
+   * Whether to close the modal when the user interacts outside it.
+   * @default true
+   */
+  isDismissable?: boolean;
+}
+
+const ModalBackdrop = ({
+  children,
+  className,
+  isDismissable = true,
+  onClick,
+  variant,
+  ...props
+}: ModalBackdropProps) => {
+  const {slots: contextSlots} = use(ModalContext);
+
+  const updatedSlots = useMemo(() => modalVariants({variant}), [variant]);
+
+  const updatedModalContext = useMemo<ModalContext>(
+    () => ({slots: {...contextSlots, ...updatedSlots}}),
+    [contextSlots, updatedSlots],
+  );
+
+  return (
+    <ModalOverlayPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.backdrop())}
+      data-slot="modal-backdrop"
+      isDismissable={isDismissable}
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick?.(e);
+      }}
+      {...props}
+    >
+      {(renderProps) => (
+        <ModalContext value={updatedModalContext}>
+          {typeof children === "function" ? children(renderProps) : children}{" "}
+        </ModalContext>
+      )}
+    </ModalOverlayPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Container
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalContainerProps extends Omit<
+  ComponentPropsWithRef<typeof ModalPrimitive>,
+  Exclude<keyof ModalBackdropProps, "children" | "className">
+> {
+  placement?: ModalPlacement;
+  scroll?: ModalVariants["scroll"];
+  size?: ModalVariants["size"];
+}
+
+const ModalContainer = ({
+  children,
+  className,
+  placement = "auto",
+  scroll,
+  size,
+  ...props
+}: ModalContainerProps) => {
+  const {slots: contextSlots} = use(ModalContext);
+
+  const updatedSlots = useMemo(() => modalVariants({scroll, size}), [scroll, size]);
+
+  const updatedModalContext = useMemo<ModalContext>(
+    () => ({placement, slots: {...contextSlots, ...updatedSlots}}),
+    [contextSlots, placement, updatedSlots],
+  );
+
+  return (
+    <ModalPrimitive
+      className={composeTwRenderProps(className, updatedSlots?.container())}
+      data-placement={placement}
+      data-slot="modal-container"
+      {...props}
+    >
+      {(renderProps) => (
+        <ModalContext value={updatedModalContext}>
+          {typeof children === "function" ? children(renderProps) : children}
+        </ModalContext>
+      )}
+    </ModalPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Dialog
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalDialogProps extends DialogPrimitiveProps {}
+
+const ModalDialog = ({children, className, ...props}: ModalDialogProps) => {
+  const {placement, slots} = use(ModalContext);
+
+  return (
+    <SurfaceContext value={{variant: "default" as SurfaceVariants["variant"]}}>
+      <DialogPrimitive
+        className={composeSlotClassName(slots?.dialog, className)}
+        data-placement={placement}
+        data-slot="modal-dialog"
+        {...props}
+      >
+        {children}
+      </DialogPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Header
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalHeaderProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ModalHeader = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ModalHeaderProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ModalHeaderProps<E>>) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="modal-header"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Body
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalBodyProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ModalBody = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ModalBodyProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ModalBodyProps<E>>) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.body, className)}
+      data-slot="modal-body"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Footer
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalFooterProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ModalFooter = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ModalFooterProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ModalFooterProps<E>>) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.footer, className)}
+      data-slot="modal-footer"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Heading
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalHeadingProps extends ComponentPropsWithRef<typeof HeadingPrimitive> {}
+
+const ModalHeading = ({children, className, ...props}: ModalHeadingProps) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <HeadingPrimitive
+      className={composeSlotClassName(slots?.heading, className)}
+      data-slot="modal-heading"
+      slot="title"
+      {...props}
+    >
+      {children}
+    </HeadingPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Icon
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ModalIcon = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ModalIconProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ModalIconProps<E>>) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.icon, className)}
+      data-slot="modal-icon"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Modal Close Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface ModalCloseTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  className?: string;
+  children?: ReactNode;
+}
+
+const ModalCloseTrigger = ({className, ...rest}: ModalCloseTriggerProps) => {
+  const {slots} = use(ModalContext);
+
+  return (
+    <CloseButton
+      className={composeTwRenderProps(className, slots?.closeTrigger())}
+      data-slot="modal-close-trigger"
+      slot="close"
+      {...rest}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  ModalRoot,
+  ModalTrigger,
+  ModalBackdrop,
+  ModalContainer,
+  ModalDialog,
+  ModalHeader,
+  ModalIcon,
+  ModalHeading,
+  ModalBody,
+  ModalFooter,
+  ModalCloseTrigger,
+};
+
+export type {
+  ModalRootProps,
+  ModalTriggerProps,
+  ModalBackdropProps,
+  ModalContainerProps,
+  ModalDialogProps,
+  ModalHeaderProps,
+  ModalIconProps,
+  ModalHeadingProps,
+  ModalBodyProps,
+  ModalFooterProps,
+  ModalCloseTriggerProps,
+};
diff --git a/packages/react/src/components/number-field/index.ts b/packages/react/src/components/number-field/index.ts
new file mode 100644
index 0000000..11daffc
--- /dev/null
+++ b/packages/react/src/components/number-field/index.ts
@@ -0,0 +1,56 @@
+import type {ComponentProps} from "react";
+
+import {
+  NumberFieldDecrementButton,
+  NumberFieldGroup,
+  NumberFieldIncrementButton,
+  NumberFieldInput,
+  NumberFieldRoot,
+} from "./number-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const NumberField = Object.assign(NumberFieldRoot, {
+  Root: NumberFieldRoot,
+  Group: NumberFieldGroup,
+  Input: NumberFieldInput,
+  IncrementButton: NumberFieldIncrementButton,
+  DecrementButton: NumberFieldDecrementButton,
+});
+
+export type NumberField = {
+  Props: ComponentProps<typeof NumberFieldRoot>;
+  RootProps: ComponentProps<typeof NumberFieldRoot>;
+  GroupProps: ComponentProps<typeof NumberFieldGroup>;
+  InputProps: ComponentProps<typeof NumberFieldInput>;
+  IncrementButtonProps: ComponentProps<typeof NumberFieldIncrementButton>;
+  DecrementButtonProps: ComponentProps<typeof NumberFieldDecrementButton>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  NumberFieldDecrementButton,
+  NumberFieldGroup,
+  NumberFieldIncrementButton,
+  NumberFieldInput,
+  NumberFieldRoot,
+};
+
+export type {
+  NumberFieldRootProps,
+  NumberFieldRootProps as NumberFieldProps,
+  NumberFieldGroupProps,
+  NumberFieldInputProps,
+  NumberFieldIncrementButtonProps,
+  NumberFieldDecrementButtonProps,
+} from "./number-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {numberFieldVariants} from "@heroui/styles";
+
+export type {NumberFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/number-field/number-field.stories.tsx b/packages/react/src/components/number-field/number-field.stories.tsx
new file mode 100644
index 0000000..d355ba3
--- /dev/null
+++ b/packages/react/src/components/number-field/number-field.stories.tsx
@@ -0,0 +1,546 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+import {Spinner} from "../spinner";
+
+import {NumberField} from "./index";
+
+const meta: Meta<typeof NumberField> = {
+  component: NumberField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Forms/NumberField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <NumberField defaultValue={1024} minValue={0} name="width">
+      <Label>Width</Label>
+      <NumberField.Group>
+        <NumberField.DecrementButton />
+        <NumberField.Input className="w-[120px]" />
+        <NumberField.IncrementButton />
+      </NumberField.Group>
+    </NumberField>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={100} minValue={0} name="primary-width" variant="primary">
+        <Label>Primary variant</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField defaultValue={100} minValue={0} name="secondary-width" variant="secondary">
+        <Label>Secondary variant</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <NumberField fullWidth defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Enter the width in pixels</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Value must be between 0 and 100</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField isRequired minValue={0} name="quantity">
+        <Label>Quantity</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+      </NumberField>
+      <NumberField isRequired defaultValue={1} maxValue={10} minValue={1} name="rating">
+        <Label>Rating</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Rate from 1 to 10</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField isInvalid isRequired minValue={0} name="quantity" value={-5}>
+        <Label>Quantity</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>Quantity must be greater than or equal to 0</FieldError>
+      </NumberField>
+      <NumberField
+        isInvalid
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+        value={1.5}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <FieldError>Percentage must be between 0 and 100</FieldError>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField isDisabled defaultValue={1024} minValue={0} name="width">
+        <Label>Width</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Enter the width in pixels</Description>
+      </NumberField>
+      <NumberField
+        isDisabled
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.1}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Value must be between 0 and 100</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState(1024);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <NumberField minValue={0} name="width" value={value} onChange={setValue}>
+          <Label>Width</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input className="w-[120px]" />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+          <Description>Current value: {value}</Description>
+        </NumberField>
+        <div className="flex gap-2">
+          <Button variant="tertiary" onPress={() => setValue(0)}>
+            Reset to 0
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue(2048)}>
+            Set to 2048
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<number | undefined>(undefined);
+    const isInvalid = value !== undefined && (value < 0 || value > 100);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <NumberField
+          isRequired
+          formatOptions={{style: "percent"}}
+          isInvalid={isInvalid}
+          maxValue={1}
+          minValue={0}
+          name="percentage"
+          step={0.1}
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Percentage</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input className="w-[120px]" />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+          {isInvalid ? (
+            <FieldError>Percentage must be between 0 and 100</FieldError>
+          ) : (
+            <Description>Enter a value between 0 and 100</Description>
+          )}
+        </NumberField>
+      </div>
+    );
+  },
+};
+
+export const WithStep: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step1" step={1}>
+        <Label>Step: 1</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 1</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}>
+        <Label>Step: 5</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 5</Description>
+      </NumberField>
+      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}>
+        <Label>Step: 10</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Increments by 10</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const WithFormatOptions: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField
+        defaultValue={99}
+        minValue={0}
+        name="currency-eur"
+        formatOptions={{
+          style: "currency",
+          currency: "EUR",
+          currencySign: "accounting",
+        }}
+      >
+        <Label>Currency (EUR - Accounting)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Accounting format with EUR currency</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={99.99}
+        minValue={0}
+        name="currency-usd"
+        formatOptions={{
+          style: "currency",
+          currency: "USD",
+        }}
+      >
+        <Label>Currency (USD)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Standard USD currency format</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={0.5}
+        formatOptions={{style: "percent"}}
+        maxValue={1}
+        minValue={0}
+        name="percentage"
+        step={0.01}
+      >
+        <Label>Percentage</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Percentage format (0-1, where 0.5 = 50%)</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1234.56}
+        minValue={0}
+        name="decimal"
+        formatOptions={{
+          style: "decimal",
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }}
+      >
+        <Label>Decimal (2 decimal places)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Decimal format with 2 decimal places</Description>
+      </NumberField>
+      <NumberField
+        defaultValue={1000}
+        minValue={0}
+        name="unit"
+        formatOptions={{
+          style: "unit",
+          unit: "kilogram",
+          unitDisplay: "short",
+        }}
+      >
+        <Label>Unit (Kilograms)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton />
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton />
+        </NumberField.Group>
+        <Description>Unit format with kilograms</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const CustomIcons: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <NumberField defaultValue={1024} minValue={0} name="width">
+        <Label>Width (Custom Icons)</Label>
+        <NumberField.Group>
+          <NumberField.DecrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+          <NumberField.Input className="w-[120px]" />
+          <NumberField.IncrementButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+        </NumberField.Group>
+        <Description>Custom icon children</Description>
+      </NumberField>
+    </div>
+  ),
+};
+
+export const WithChevrons: Story = {
+  render: () => (
+    <NumberField
+      defaultValue={99}
+      minValue={0}
+      name="amount"
+      formatOptions={{
+        style: "currency",
+        currency: "EUR",
+        currencySign: "accounting",
+      }}
+    >
+      <Label>Number field with chevrons</Label>
+      <NumberField.Group className="flex">
+        <NumberField.Input className="flex-1" />
+        <div className="flex h-full flex-col border-l border-field-placeholder/15">
+          <NumberField.IncrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pt-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.IncrementButton>
+          <NumberField.DecrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-0 pb-0.5 text-sm">
+            <svg
+              aria-hidden="true"
+              height="11"
+              viewBox="0 0 16 16"
+              width="11"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                clipRule="evenodd"
+                d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </NumberField.DecrementButton>
+        </div>
+      </NumberField.Group>
+    </NumberField>
+  ),
+};
+
+export const FormExample: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState<number | undefined>(undefined);
+    const [isSubmitting, setIsSubmitting] = React.useState(false);
+    const STOCK_AVAILABLE = 3;
+    const isOutOfStock = value !== undefined && value > STOCK_AVAILABLE;
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+
+      if (value === undefined || value === null || value < 1 || value > STOCK_AVAILABLE) {
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        // eslint-disable-next-line no-console
+        console.log("Order submitted:", {quantity: value});
+        setValue(undefined);
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <NumberField
+          {...args}
+          isRequired
+          isInvalid={isOutOfStock}
+          maxValue={5}
+          minValue={1}
+          name="quantity"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Order quantity</Label>
+          <NumberField.Group>
+            <NumberField.DecrementButton />
+            <NumberField.Input className="w-[120px]" />
+            <NumberField.IncrementButton />
+          </NumberField.Group>
+          {isOutOfStock ? (
+            <FieldError>Only {STOCK_AVAILABLE} items left in stock</FieldError>
+          ) : (
+            <Description>Only {STOCK_AVAILABLE} items available</Description>
+          )}
+        </NumberField>
+        <Button
+          className="w-full"
+          isDisabled={value === undefined || value < 1 || value > STOCK_AVAILABLE}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? (
+            <>
+              <Spinner color="current" size="sm" />
+              Processing...
+            </>
+          ) : (
+            "Place Order"
+          )}
+        </Button>
+      </Form>
+    );
+  },
+};
diff --git a/packages/react/src/components/number-field/number-field.tsx b/packages/react/src/components/number-field/number-field.tsx
new file mode 100644
index 0000000..acbaec1
--- /dev/null
+++ b/packages/react/src/components/number-field/number-field.tsx
@@ -0,0 +1,165 @@
+"use client";
+
+import type {NumberFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {numberFieldVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+import {Input as InputPrimitive} from "react-aria-components/Input";
+import {NumberField as NumberFieldPrimitive} from "react-aria-components/NumberField";
+
+import {composeTwRenderProps} from "../../utils/compose";
+import {IconMinus, IconPlus} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Context
+ * -----------------------------------------------------------------------------------------------*/
+type NumberFieldContext = {
+  slots?: ReturnType<typeof numberFieldVariants>;
+};
+
+const NumberFieldContext = createContext<NumberFieldContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface NumberFieldRootProps
+  extends ComponentPropsWithRef<typeof NumberFieldPrimitive>, NumberFieldVariants {}
+
+const NumberFieldRoot = ({
+  children,
+  className,
+  fullWidth,
+  variant,
+  ...props
+}: NumberFieldRootProps) => {
+  const slots = React.useMemo(
+    () => numberFieldVariants({fullWidth, variant}),
+    [fullWidth, variant],
+  );
+
+  return (
+    <NumberFieldContext value={{slots}}>
+      <NumberFieldPrimitive
+        data-slot="number-field"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </NumberFieldPrimitive>
+    </NumberFieldContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Group
+ * -----------------------------------------------------------------------------------------------*/
+interface NumberFieldGroupProps extends ComponentPropsWithRef<typeof GroupPrimitive> {}
+
+const NumberFieldGroup = ({children, className, ...props}: NumberFieldGroupProps) => {
+  const {slots} = use(NumberFieldContext);
+
+  return (
+    <GroupPrimitive
+      className={composeTwRenderProps(className, slots?.group())}
+      data-slot="number-field-group"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </GroupPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Input
+ * -----------------------------------------------------------------------------------------------*/
+interface NumberFieldInputProps extends ComponentPropsWithRef<typeof InputPrimitive> {}
+
+const NumberFieldInput = ({className, ...props}: NumberFieldInputProps) => {
+  const {slots} = use(NumberFieldContext);
+
+  return (
+    <InputPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="number-field-input"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Increment Button
+ * -----------------------------------------------------------------------------------------------*/
+interface NumberFieldIncrementButtonProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const NumberFieldIncrementButton = ({
+  children,
+  className,
+  ...props
+}: NumberFieldIncrementButtonProps) => {
+  const {slots} = use(NumberFieldContext);
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, slots?.incrementButton())}
+      data-slot="number-field-increment-button"
+      slot="increment"
+      {...props}
+    >
+      {children && React.isValidElement(children) ? (
+        children
+      ) : (
+        <IconPlus data-slot="number-field-increment-button-icon" />
+      )}
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * NumberField Decrement Button
+ * -----------------------------------------------------------------------------------------------*/
+interface NumberFieldDecrementButtonProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const NumberFieldDecrementButton = ({
+  children,
+  className,
+  ...props
+}: NumberFieldDecrementButtonProps) => {
+  const {slots} = use(NumberFieldContext);
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, slots?.decrementButton())}
+      data-slot="number-field-decrement-button"
+      slot="decrement"
+      {...props}
+    >
+      {children && React.isValidElement(children) ? (
+        children
+      ) : (
+        <IconMinus data-slot="number-field-decrement-button-icon" />
+      )}
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  NumberFieldRoot,
+  NumberFieldGroup,
+  NumberFieldInput,
+  NumberFieldIncrementButton,
+  NumberFieldDecrementButton,
+};
+
+export type {
+  NumberFieldRootProps,
+  NumberFieldGroupProps,
+  NumberFieldInputProps,
+  NumberFieldIncrementButtonProps,
+  NumberFieldDecrementButtonProps,
+};
diff --git a/packages/react/src/components/pagination/index.ts b/packages/react/src/components/pagination/index.ts
new file mode 100644
index 0000000..505c996
--- /dev/null
+++ b/packages/react/src/components/pagination/index.ts
@@ -0,0 +1,81 @@
+import type {ComponentProps} from "react";
+
+import {
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationNextIcon,
+  PaginationPrevious,
+  PaginationPreviousIcon,
+  PaginationRoot,
+  PaginationSummary,
+} from "./pagination";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Pagination = Object.assign(PaginationRoot, {
+  Content: PaginationContent,
+  Ellipsis: PaginationEllipsis,
+  Item: PaginationItem,
+  Link: PaginationLink,
+  Next: PaginationNext,
+  NextIcon: PaginationNextIcon,
+  Previous: PaginationPrevious,
+  PreviousIcon: PaginationPreviousIcon,
+  Root: PaginationRoot,
+  Summary: PaginationSummary,
+});
+
+export type Pagination = {
+  ContentProps: ComponentProps<typeof PaginationContent>;
+  EllipsisProps: ComponentProps<typeof PaginationEllipsis>;
+  ItemProps: ComponentProps<typeof PaginationItem>;
+  LinkProps: ComponentProps<typeof PaginationLink>;
+  NextIconProps: ComponentProps<typeof PaginationNextIcon>;
+  NextProps: ComponentProps<typeof PaginationNext>;
+  PreviousIconProps: ComponentProps<typeof PaginationPreviousIcon>;
+  PreviousProps: ComponentProps<typeof PaginationPrevious>;
+  Props: ComponentProps<typeof PaginationRoot>;
+  RootProps: ComponentProps<typeof PaginationRoot>;
+  SummaryProps: ComponentProps<typeof PaginationSummary>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  PaginationRoot,
+  PaginationSummary,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationPreviousIcon,
+  PaginationNext,
+  PaginationNextIcon,
+  PaginationEllipsis,
+};
+
+export type {
+  PaginationRootProps,
+  PaginationRootProps as PaginationProps,
+  PaginationSummaryProps,
+  PaginationContentProps,
+  PaginationItemProps,
+  PaginationLinkProps,
+  PaginationPreviousProps,
+  PaginationPreviousIconProps,
+  PaginationNextProps,
+  PaginationNextIconProps,
+  PaginationEllipsisProps,
+} from "./pagination";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {paginationVariants} from "@heroui/styles";
+
+export type {PaginationVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/pagination/pagination.stories.tsx b/packages/react/src/components/pagination/pagination.stories.tsx
new file mode 100644
index 0000000..c532361
--- /dev/null
+++ b/packages/react/src/components/pagination/pagination.stories.tsx
@@ -0,0 +1,402 @@
+import type {PaginationProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Separator} from "../separator";
+
+import {Pagination} from "./index";
+
+export default {
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: Pagination,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/Pagination",
+} as Meta<typeof Pagination>;
+
+const defaultArgs: PaginationProps = {
+  children: null,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Default
+ * -----------------------------------------------------------------------------------------------*/
+const DefaultTemplate = (props: PaginationProps) => (
+  <Pagination {...props}>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon />
+          <span>Previous</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>2</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>3</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: DefaultTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Sizes
+ * -----------------------------------------------------------------------------------------------*/
+const SizesTemplate = (props: PaginationProps) => {
+  const sizes = ["sm", "md", "lg"] as const;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {sizes.map((size, index) => (
+        <React.Fragment key={size}>
+          <div className="flex flex-col gap-2">
+            <span className="text-sm font-semibold text-muted capitalize">{size}</span>
+            <Pagination {...props} size={size}>
+              <Pagination.Content>
+                <Pagination.Item>
+                  <Pagination.Previous>
+                    <Pagination.PreviousIcon />
+                    <span>Previous</span>
+                  </Pagination.Previous>
+                </Pagination.Item>
+                <Pagination.Item>
+                  <Pagination.Link isActive>1</Pagination.Link>
+                </Pagination.Item>
+                <Pagination.Item>
+                  <Pagination.Link>2</Pagination.Link>
+                </Pagination.Item>
+                <Pagination.Item>
+                  <Pagination.Link>3</Pagination.Link>
+                </Pagination.Item>
+                <Pagination.Item>
+                  <Pagination.Next>
+                    <span>Next</span>
+                    <Pagination.NextIcon />
+                  </Pagination.Next>
+                </Pagination.Item>
+              </Pagination.Content>
+            </Pagination>
+          </div>
+          {index < sizes.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+    </div>
+  );
+};
+
+export const Sizes = {
+  args: defaultArgs,
+  render: SizesTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * With Ellipsis
+ * -----------------------------------------------------------------------------------------------*/
+const WithEllipsisTemplate = (props: PaginationProps) => (
+  <Pagination {...props}>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon />
+          <span>Previous</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>2</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>3</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Ellipsis />
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>10</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>11</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>12</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+
+export const WithEllipsis = {
+  args: defaultArgs,
+  render: WithEllipsisTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Simple (Prev / Next only)
+ * -----------------------------------------------------------------------------------------------*/
+const SimplePrevNextTemplate = (props: PaginationProps) => (
+  <Pagination {...props}>
+    <Pagination.Summary>1 to 5 of 10 invoices</Pagination.Summary>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon />
+          <span>Prev</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+
+export const SimplePrevNext = {
+  args: defaultArgs,
+  render: SimplePrevNextTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * With Summary
+ * -----------------------------------------------------------------------------------------------*/
+const WithSummaryTemplate = (props: PaginationProps) => (
+  <div className="w-full min-w-[640px]">
+    <Pagination {...props}>
+      <Pagination.Summary>Showing 1-10 of 120 results</Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous>
+            <Pagination.PreviousIcon />
+            <span>Previous</span>
+          </Pagination.Previous>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link isActive>1</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>2</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>3</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Ellipsis />
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>10</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>11</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Link>12</Pagination.Link>
+        </Pagination.Item>
+        <Pagination.Item>
+          <Pagination.Next>
+            <span>Next</span>
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  </div>
+);
+
+export const WithSummary = {
+  args: defaultArgs,
+  render: WithSummaryTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Custom Icons
+ * -----------------------------------------------------------------------------------------------*/
+const CustomIconsTemplate = (props: PaginationProps) => (
+  <Pagination {...props}>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous>
+          <Pagination.PreviousIcon>
+            <Icon icon="gravity-ui:arrow-left" />
+          </Pagination.PreviousIcon>
+          <span>Back</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>2</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>3</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Forward</span>
+          <Pagination.NextIcon>
+            <Icon icon="gravity-ui:arrow-right" />
+          </Pagination.NextIcon>
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+
+export const CustomIcons = {
+  args: defaultArgs,
+  render: CustomIconsTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Controlled (with state management)
+ * -----------------------------------------------------------------------------------------------*/
+const ControlledTemplate = (props: PaginationProps) => {
+  const [page, setPage] = React.useState(1);
+  const totalPages = 12;
+  const itemsPerPage = 10;
+  const totalItems = 120;
+
+  const getPageNumbers = () => {
+    const pages: (number | "start-ellipsis" | "end-ellipsis")[] = [];
+
+    if (totalPages <= 7) {
+      for (let i = 1; i <= totalPages; i++) {
+        pages.push(i);
+      }
+    } else {
+      pages.push(1);
+
+      if (page > 3) {
+        pages.push("start-ellipsis");
+      }
+
+      const start = Math.max(2, page - 1);
+      const end = Math.min(totalPages - 1, page + 1);
+
+      for (let i = start; i <= end; i++) {
+        pages.push(i);
+      }
+
+      if (page < totalPages - 2) {
+        pages.push("end-ellipsis");
+      }
+
+      pages.push(totalPages);
+    }
+
+    return pages;
+  };
+
+  const startItem = (page - 1) * itemsPerPage + 1;
+  const endItem = Math.min(page * itemsPerPage, totalItems);
+
+  return (
+    <div className="w-full min-w-[640px]">
+      <Pagination {...props}>
+        <Pagination.Summary>
+          Showing {startItem}-{endItem} of {totalItems} results
+        </Pagination.Summary>
+        <Pagination.Content>
+          <Pagination.Item>
+            <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}>
+              <Pagination.PreviousIcon />
+              <span>Previous</span>
+            </Pagination.Previous>
+          </Pagination.Item>
+          {getPageNumbers().map((p) =>
+            p === "start-ellipsis" || p === "end-ellipsis" ? (
+              <Pagination.Item key={p}>
+                <Pagination.Ellipsis />
+              </Pagination.Item>
+            ) : (
+              <Pagination.Item key={p}>
+                <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+                  {p}
+                </Pagination.Link>
+              </Pagination.Item>
+            ),
+          )}
+          <Pagination.Item>
+            <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}>
+              <span>Next</span>
+              <Pagination.NextIcon />
+            </Pagination.Next>
+          </Pagination.Item>
+        </Pagination.Content>
+      </Pagination>
+    </div>
+  );
+};
+
+export const Controlled = {
+  args: defaultArgs,
+  render: ControlledTemplate,
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Disabled
+ * -----------------------------------------------------------------------------------------------*/
+const DisabledTemplate = (props: PaginationProps) => (
+  <Pagination {...props}>
+    <Pagination.Content>
+      <Pagination.Item>
+        <Pagination.Previous isDisabled>
+          <Pagination.PreviousIcon />
+          <span>Previous</span>
+        </Pagination.Previous>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link isActive>1</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>2</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Link>3</Pagination.Link>
+      </Pagination.Item>
+      <Pagination.Item>
+        <Pagination.Next>
+          <span>Next</span>
+          <Pagination.NextIcon />
+        </Pagination.Next>
+      </Pagination.Item>
+    </Pagination.Content>
+  </Pagination>
+);
+
+export const Disabled = {
+  args: defaultArgs,
+  render: DisabledTemplate,
+};
diff --git a/packages/react/src/components/pagination/pagination.tsx b/packages/react/src/components/pagination/pagination.tsx
new file mode 100644
index 0000000..fb39997
--- /dev/null
+++ b/packages/react/src/components/pagination/pagination.tsx
@@ -0,0 +1,348 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {PaginationVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {paginationVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+
+import {composeTwRenderProps} from "../../utils";
+import {composeSlotClassName} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronLeft, IconChevronRight} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Context
+ * -----------------------------------------------------------------------------------------------*/
+type PaginationContext = {
+  slots?: ReturnType<typeof paginationVariants>;
+};
+
+const PaginationContext = createContext<PaginationContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Root
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "nav",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+  /** Pagination size. */
+  size?: PaginationVariants["size"];
+}
+
+const PaginationRoot = <E extends keyof React.JSX.IntrinsicElements = "nav">({
+  children,
+  className,
+  size,
+  ...props
+}: PaginationRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof PaginationRootProps<E>>) => {
+  const slots = React.useMemo(() => paginationVariants({size}), [size]);
+
+  return (
+    <PaginationContext value={{slots}}>
+      <dom.nav
+        aria-label="pagination"
+        data-slot="pagination"
+        role="navigation"
+        {...(props as any)}
+        className={composeSlotClassName(slots.base, className)}
+      >
+        {children}
+      </dom.nav>
+    </PaginationContext>
+  );
+};
+
+PaginationRoot.displayName = "HeroUI.Pagination";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Summary
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationSummaryProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+}
+
+const PaginationSummary = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: PaginationSummaryProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof PaginationSummaryProps<E>>) => {
+  const {slots} = use(PaginationContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.summary, className)}
+      data-slot="pagination-summary"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+PaginationSummary.displayName = "HeroUI.Pagination.Summary";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Content
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "ul",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+}
+
+const PaginationContent = <E extends keyof React.JSX.IntrinsicElements = "ul">({
+  children,
+  className,
+  ...props
+}: PaginationContentProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof PaginationContentProps<E>>) => {
+  const {slots} = use(PaginationContext);
+
+  return (
+    <dom.ul
+      className={composeSlotClassName(slots?.content, className)}
+      data-slot="pagination-content"
+      {...(props as any)}
+    >
+      {children}
+    </dom.ul>
+  );
+};
+
+PaginationContent.displayName = "HeroUI.Pagination.Content";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Item
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationItemProps<
+  E extends keyof React.JSX.IntrinsicElements = "li",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+}
+
+const PaginationItem = <E extends keyof React.JSX.IntrinsicElements = "li">({
+  children,
+  className,
+  ...props
+}: PaginationItemProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof PaginationItemProps<E>>) => {
+  const {slots} = use(PaginationContext);
+
+  return (
+    <dom.li
+      className={composeSlotClassName(slots?.item, className)}
+      data-slot="pagination-item"
+      {...(props as any)}
+    >
+      {children}
+    </dom.li>
+  );
+};
+
+PaginationItem.displayName = "HeroUI.Pagination.Item";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Link
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationLinkProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  className?: string;
+  children: React.ReactNode;
+  isActive?: boolean;
+}
+
+const PaginationLink = ({children, className, isActive, ...props}: PaginationLinkProps) => {
+  const {slots} = use(PaginationContext);
+
+  return (
+    <ButtonPrimitive
+      aria-current={isActive ? "page" : undefined}
+      className={composeTwRenderProps(className, slots?.link())}
+      data-active={isActive ? "true" : undefined}
+      data-slot="pagination-link"
+      {...props}
+    >
+      {children}
+    </ButtonPrimitive>
+  );
+};
+
+PaginationLink.displayName = "HeroUI.Pagination.Link";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Previous
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationPreviousProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  className?: string;
+  children: React.ReactNode;
+}
+
+const PaginationPrevious = ({children, className, ...props}: PaginationPreviousProps) => {
+  const {slots} = use(PaginationContext);
+  const baseClass = `${slots?.link() ?? ""} pagination__link--nav`.trim();
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, baseClass)}
+      data-slot="pagination-previous"
+      {...props}
+    >
+      {children}
+    </ButtonPrimitive>
+  );
+};
+
+PaginationPrevious.displayName = "HeroUI.Pagination.Previous";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Previous Icon
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationPreviousIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const PaginationPreviousIcon = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: PaginationPreviousIconProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof PaginationPreviousIconProps<E>>) => {
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={className}
+      data-slot="pagination-previous-icon"
+      {...(props as any)}
+    >
+      {children ?? <IconChevronLeft />}
+    </dom.span>
+  );
+};
+
+PaginationPreviousIcon.displayName = "HeroUI.Pagination.PreviousIcon";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Next
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationNextProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  className?: string;
+  children: React.ReactNode;
+}
+
+const PaginationNext = ({children, className, ...props}: PaginationNextProps) => {
+  const {slots} = use(PaginationContext);
+  const baseClass = `${slots?.link() ?? ""} pagination__link--nav`.trim();
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, baseClass)}
+      data-slot="pagination-next"
+      {...props}
+    >
+      {children}
+    </ButtonPrimitive>
+  );
+};
+
+PaginationNext.displayName = "HeroUI.Pagination.Next";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Next Icon
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationNextIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const PaginationNextIcon = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: PaginationNextIconProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof PaginationNextIconProps<E>>) => {
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={className}
+      data-slot="pagination-next-icon"
+      {...(props as any)}
+    >
+      {children ?? <IconChevronRight />}
+    </dom.span>
+  );
+};
+
+PaginationNextIcon.displayName = "HeroUI.Pagination.NextIcon";
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Ellipsis
+ * -----------------------------------------------------------------------------------------------*/
+interface PaginationEllipsisProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const PaginationEllipsis = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: PaginationEllipsisProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof PaginationEllipsisProps<E>>) => {
+  const {slots} = use(PaginationContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.ellipsis, className)}
+      data-slot="pagination-ellipsis"
+      {...(props as any)}
+    >
+      &hellip;
+    </dom.span>
+  );
+};
+
+PaginationEllipsis.displayName = "HeroUI.Pagination.Ellipsis";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  PaginationRoot,
+  PaginationSummary,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationPreviousIcon,
+  PaginationNext,
+  PaginationNextIcon,
+  PaginationEllipsis,
+};
+
+export type {
+  PaginationRootProps,
+  PaginationSummaryProps,
+  PaginationContentProps,
+  PaginationItemProps,
+  PaginationLinkProps,
+  PaginationPreviousProps,
+  PaginationPreviousIconProps,
+  PaginationNextProps,
+  PaginationNextIconProps,
+  PaginationEllipsisProps,
+};
diff --git a/packages/react/src/components/popover/index.ts b/packages/react/src/components/popover/index.ts
new file mode 100644
index 0000000..e3e2674
--- /dev/null
+++ b/packages/react/src/components/popover/index.ts
@@ -0,0 +1,54 @@
+import type {ComponentProps} from "react";
+
+import {
+  PopoverArrow,
+  PopoverContent,
+  PopoverDialog,
+  PopoverHeading,
+  PopoverRoot,
+  PopoverTrigger,
+} from "./popover";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Popover = Object.assign(PopoverRoot, {
+  Root: PopoverRoot,
+  Trigger: PopoverTrigger,
+  Dialog: PopoverDialog,
+  Arrow: PopoverArrow,
+  Content: PopoverContent,
+  Heading: PopoverHeading,
+});
+
+export type Popover = {
+  Props: ComponentProps<typeof PopoverRoot>;
+  RootProps: ComponentProps<typeof PopoverRoot>;
+  TriggerProps: ComponentProps<typeof PopoverTrigger>;
+  DialogProps: ComponentProps<typeof PopoverDialog>;
+  ArrowProps: ComponentProps<typeof PopoverArrow>;
+  ContentProps: ComponentProps<typeof PopoverContent>;
+  HeadingProps: ComponentProps<typeof PopoverHeading>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {PopoverArrow, PopoverContent, PopoverDialog, PopoverHeading, PopoverRoot, PopoverTrigger};
+
+export type {
+  PopoverRootProps,
+  PopoverRootProps as PopoverProps,
+  PopoverTriggerProps,
+  PopoverDialogProps,
+  PopoverArrowProps,
+  PopoverContentProps,
+  PopoverHeadingProps,
+} from "./popover";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {popoverVariants} from "@heroui/styles";
+
+export type {PopoverVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/popover/popover.stories.tsx b/packages/react/src/components/popover/popover.stories.tsx
new file mode 100644
index 0000000..3f09ec4
--- /dev/null
+++ b/packages/react/src/components/popover/popover.stories.tsx
@@ -0,0 +1,254 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Avatar} from "../avatar";
+import {Button} from "../button";
+import {Card} from "../card";
+
+import {Popover} from "./index";
+
+export default {
+  argTypes: {
+    offset: {
+      control: "number",
+    },
+    placement: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom left",
+        "bottom right",
+        "bottom start",
+        "bottom end",
+        "top",
+        "top left",
+        "top right",
+        "top start",
+        "top end",
+        "left",
+        "left top",
+        "left bottom",
+        "start",
+        "start top",
+        "start bottom",
+        "right",
+        "right top",
+        "right bottom",
+        "end",
+        "end top",
+        "end bottom",
+      ],
+    },
+  },
+  component: Popover,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Overlays/Popover",
+} as Meta<typeof Popover>;
+
+const defaultArgs: Omit<Popover["ContentProps"], "children"> = {};
+
+const Template = (props: Popover["ContentProps"]) => (
+  <div className="flex items-center gap-3">
+    <Popover>
+      <Button isIconOnly aria-label="Popover trigger" variant="tertiary">
+        <Icon icon="gravity-ui:circle-info" />
+      </Button>
+      <Popover.Content {...props}>
+        <Popover.Dialog>
+          <Popover.Heading>Popover heading</Popover.Heading>
+          <p>This is the popover content</p>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  </div>
+);
+
+const TemplateWithArrow = (props: Popover["ContentProps"]) => (
+  <div className="flex items-center gap-3">
+    <Popover>
+      <Button isIconOnly aria-label="Popover trigger" variant="tertiary">
+        <Icon icon="gravity-ui:circle-info" />
+      </Button>
+      <Popover.Content {...props}>
+        <Popover.Dialog>
+          <Popover.Arrow />
+          <Popover.Heading>Popover heading</Popover.Heading>
+          <p>This is the popover content</p>
+        </Popover.Dialog>
+      </Popover.Content>
+    </Popover>
+  </div>
+);
+
+const TemplateWithCustomContent = (props: Popover["ContentProps"]) => {
+  const [isFollowing, setIsFollowing] = React.useState(false);
+
+  return (
+    <div className="flex items-center gap-3">
+      <Popover>
+        <Popover.Trigger aria-label="Popover trigger">
+          <div className="flex items-center gap-2">
+            <Avatar size="sm">
+              <Avatar.Image alt="Zoe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5" />
+              <Avatar.Fallback>Z</Avatar.Fallback>
+            </Avatar>
+            <div className="flex flex-col gap-0">
+              <p className="text-sm leading-5 font-medium">Zoe</p>
+              <p className="text-xs leading-none text-muted">zoe@heroui.com</p>
+            </div>
+          </div>
+        </Popover.Trigger>
+        <Popover.Content {...props} className="w-[290px]">
+          <Popover.Dialog className="flex flex-col gap-3">
+            <Popover.Heading>
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                  <Avatar size="md">
+                    <Avatar.Image
+                      alt="Zoe"
+                      src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
+                    />
+                    <Avatar.Fallback>Z</Avatar.Fallback>
+                  </Avatar>
+                  <div className="flex h-full flex-col items-start justify-center">
+                    <span className="text-sm font-medium">Zoey Lang</span>
+                    <span className="text-sm leading-4 font-normal tracking-tight text-muted">
+                      @zoe
+                    </span>
+                  </div>
+                </div>
+                <Button
+                  className="rounded-full text-xs font-normal"
+                  size="sm"
+                  variant={isFollowing ? "tertiary" : "primary"}
+                  onPress={() => setIsFollowing(!isFollowing)}
+                >
+                  {isFollowing ? "Following" : "Follow"}
+                </Button>
+              </div>
+            </Popover.Heading>
+            <div>
+              <p className="pl-px text-sm">
+                Design Engineer, @hero_ui lover she/her. SF Bay Area&nbsp;
+                <span aria-label="confetti" role="img">
+                  🎉
+                </span>
+              </p>
+            </div>
+            <div className="flex gap-3">
+              <div className="flex gap-1">
+                <p className="text-sm font-semibold">4</p>
+                <p className="text-sm text-muted">Following</p>
+              </div>
+              <div className="flex gap-1">
+                <p className="text-sm font-semibold">97.1K</p>
+                <p className="text-sm text-muted">Followers</p>
+              </div>
+            </div>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithArrow = {
+  args: defaultArgs,
+  render: TemplateWithArrow,
+};
+
+export const WithCustomContent = {
+  args: defaultArgs,
+  render: TemplateWithCustomContent,
+};
+
+const SpringAnimationTemplate = (props: Popover["ContentProps"]) => (
+  <div className="flex flex-col items-center gap-8 p-8">
+    <h1 className="text-xl font-semibold">Popover with Spring Animation</h1>
+    <p className="text-sm text-muted">
+      The popover now uses a spring easing function for a more dynamic feel
+    </p>
+
+    <div className="flex items-center gap-8">
+      <Popover>
+        <Button>Click for Spring Animation</Button>
+        <Popover.Content
+          {...props}
+          className="data-[entering]:ease-spring data-[entering]:animate-in data-[entering]:duration-600 data-[entering]:fade-in-0 data-[entering]:zoom-in-90"
+        >
+          <Popover.Dialog>
+            <Popover.Arrow />
+            <Popover.Heading>Spring Animation 🎉</Popover.Heading>
+            <p className="mt-2 text-sm text-muted">
+              Notice the subtle bounce effect when the popover appears and disappears.
+            </p>
+            <p className="mt-4 text-xs text-muted">Easing: cubic-bezier(0.36, 1.66, 0.04, 1)</p>
+          </Popover.Dialog>
+        </Popover.Content>
+      </Popover>
+    </div>
+
+    <div className="space-y-1 text-center text-xs text-muted">
+      <p>Animation classes applied:</p>
+      <code className="rounded bg-surface px-2 py-1 text-xs">
+        data-[entering]:animate-in data-[entering]:zoom-in-90 data-[entering]:fade-in-0
+        data-[entering]:ease-spring data-[entering]:duration-600
+      </code>
+    </div>
+  </div>
+);
+
+export const SpringAnimation = {
+  args: defaultArgs,
+  render: SpringAnimationTemplate,
+};
+
+const CardWithHelptextTemplate = (props: Popover["ContentProps"]) => (
+  <Card className="w-[400px]">
+    <Card.Header>
+      <div className="flex items-center gap-2">
+        <Card.Title>Card Title</Card.Title>
+        <Popover>
+          <Popover.Trigger aria-label="Help information">
+            <Button isIconOnly aria-label="Help" size="sm" variant="ghost">
+              <Icon className="text-muted" icon="gravity-ui:circle-info" />
+            </Button>
+          </Popover.Trigger>
+          <Popover.Content {...props} className="max-w-[200px]" placement="right">
+            <Popover.Dialog>
+              <Popover.Arrow />
+              <Popover.Heading>Help Information</Popover.Heading>
+              <p className="text-sm text-muted">
+                This is a helptext popover that appears on top of the card surface. It provides
+                additional context or information about the card title.
+              </p>
+            </Popover.Dialog>
+          </Popover.Content>
+        </Popover>
+      </div>
+      <Card.Description>
+        This card demonstrates how a popover looks when displayed on top of a card surface.
+      </Card.Description>
+    </Card.Header>
+    <Card.Content>
+      <p className="text-sm">
+        The popover help icon is positioned right after the title, allowing users to access
+        additional information without cluttering the main content area.
+      </p>
+    </Card.Content>
+  </Card>
+);
+
+export const CardWithHelptext = {
+  args: defaultArgs,
+  render: CardWithHelptextTemplate,
+};
diff --git a/packages/react/src/components/popover/popover.tsx b/packages/react/src/components/popover/popover.tsx
new file mode 100644
index 0000000..799cbba
--- /dev/null
+++ b/packages/react/src/components/popover/popover.tsx
@@ -0,0 +1,203 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {PopoverVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {popoverVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  Dialog as DialogPrimitive,
+  Heading as HeadingPrimitive,
+  DialogTrigger as PopoverTriggerPrimitive,
+} from "react-aria-components/Dialog";
+import {
+  OverlayArrow,
+  Popover as PopoverPrimitive,
+  Pressable as PressablePrimitive,
+} from "react-aria-components/Popover";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Context
+ * -----------------------------------------------------------------------------------------------*/
+type PopoverContext = {
+  slots?: ReturnType<typeof popoverVariants>;
+};
+
+const PopoverContext = createContext<PopoverContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Root
+ * -----------------------------------------------------------------------------------------------*/
+type PopoverRootProps = ComponentPropsWithRef<typeof PopoverTriggerPrimitive>;
+
+const PopoverRoot = ({
+  children,
+  ...props
+}: ComponentPropsWithRef<typeof PopoverTriggerPrimitive>) => {
+  const slots = React.useMemo(() => popoverVariants(), []);
+
+  return (
+    <PopoverContext value={{slots}}>
+      <PopoverTriggerPrimitive data-slot="popover-root" {...props}>
+        {children}
+      </PopoverTriggerPrimitive>
+    </PopoverContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Content
+ * -----------------------------------------------------------------------------------------------*/
+interface PopoverContentProps
+  extends Omit<ComponentPropsWithRef<typeof PopoverPrimitive>, "children">, PopoverVariants {
+  children: React.ReactNode;
+}
+
+const PopoverContent = ({children, className, ...props}: PopoverContentProps) => {
+  const {slots} = use(PopoverContext);
+
+  return (
+    <PopoverContext value={{slots}}>
+      <SurfaceContext
+        value={{
+          variant: "default" as SurfaceVariants["variant"],
+        }}
+      >
+        <PopoverPrimitive {...props} className={composeTwRenderProps(className, slots?.base())}>
+          {children}
+        </PopoverPrimitive>
+      </SurfaceContext>
+    </PopoverContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Arrow
+ * -----------------------------------------------------------------------------------------------*/
+type PopoverArrowProps = Omit<ComponentPropsWithRef<typeof OverlayArrow>, "children"> & {
+  children?: React.ReactNode;
+};
+
+const PopoverArrow = ({children, className, ...props}: PopoverArrowProps) => {
+  const defaultArrow = (
+    <svg
+      data-slot="popover-overlay-arrow"
+      fill="none"
+      height="12"
+      viewBox="0 0 12 12"
+      width="12"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M0 0C5.48483 8 6.5 8 12 0Z" />
+    </svg>
+  );
+
+  const arrow = React.isValidElement(children)
+    ? React.cloneElement(
+        children as React.ReactElement<{
+          className?: string;
+          "data-slot"?: "popover-overlay-arrow";
+        }>,
+        {
+          "data-slot": "popover-overlay-arrow",
+        },
+      )
+    : defaultArrow;
+
+  return (
+    <OverlayArrow data-slot="popover-overlay-arrow-group" {...props} className={className}>
+      {arrow}
+    </OverlayArrow>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Dialog
+ * -----------------------------------------------------------------------------------------------*/
+type PopoverDialogProps = Omit<ComponentPropsWithRef<typeof DialogPrimitive>, "children"> & {
+  children: React.ReactNode;
+};
+
+const PopoverDialog = ({children, className, ...props}: PopoverDialogProps) => {
+  const {slots} = use(PopoverContext);
+
+  return (
+    <DialogPrimitive
+      data-slot="popover-dialog"
+      {...props}
+      className={composeSlotClassName(slots?.dialog, className)}
+    >
+      {children}
+    </DialogPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface PopoverTriggerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const PopoverTrigger = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: PopoverTriggerProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof PopoverTriggerProps<E>>) => {
+  const {slots} = use(PopoverContext);
+
+  return (
+    <PressablePrimitive>
+      <dom.div
+        className={composeSlotClassName(slots?.trigger, className)}
+        data-slot="popover-trigger"
+        role="button"
+        {...(props as any)}
+      >
+        {children}
+      </dom.div>
+    </PressablePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Popover Heading
+ * -----------------------------------------------------------------------------------------------*/
+type PopoverHeadingProps = ComponentPropsWithRef<typeof HeadingPrimitive> & {};
+
+const PopoverHeading = ({children, className, ...props}: PopoverHeadingProps) => {
+  const {slots} = use(PopoverContext);
+
+  return (
+    <HeadingPrimitive
+      slot="title"
+      {...props}
+      className={composeSlotClassName(slots?.heading, className)}
+    >
+      {children}
+    </HeadingPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {PopoverRoot, PopoverTrigger, PopoverDialog, PopoverArrow, PopoverContent, PopoverHeading};
+
+export type {
+  PopoverRootProps,
+  PopoverTriggerProps,
+  PopoverDialogProps,
+  PopoverArrowProps,
+  PopoverContentProps,
+  PopoverHeadingProps,
+};
diff --git a/packages/react/src/components/progress-bar/index.ts b/packages/react/src/components/progress-bar/index.ts
new file mode 100644
index 0000000..24f7b86
--- /dev/null
+++ b/packages/react/src/components/progress-bar/index.ts
@@ -0,0 +1,46 @@
+import type {ComponentProps} from "react";
+
+import {
+  ProgressBarFill,
+  ProgressBarOutput,
+  ProgressBarRoot,
+  ProgressBarTrack,
+} from "./progress-bar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ProgressBar = Object.assign(ProgressBarRoot, {
+  Root: ProgressBarRoot,
+  Output: ProgressBarOutput,
+  Track: ProgressBarTrack,
+  Fill: ProgressBarFill,
+});
+
+export type ProgressBar = {
+  Props: ComponentProps<typeof ProgressBarRoot>;
+  RootProps: ComponentProps<typeof ProgressBarRoot>;
+  OutputProps: ComponentProps<typeof ProgressBarOutput>;
+  TrackProps: ComponentProps<typeof ProgressBarTrack>;
+  FillProps: ComponentProps<typeof ProgressBarFill>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ProgressBarRoot, ProgressBarOutput, ProgressBarTrack, ProgressBarFill};
+
+export type {
+  ProgressBarRootProps,
+  ProgressBarRootProps as ProgressBarProps,
+  ProgressBarOutputProps,
+  ProgressBarTrackProps,
+  ProgressBarFillProps,
+} from "./progress-bar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {progressBarVariants} from "@heroui/styles";
+
+export type {ProgressBarVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/progress-bar/progress-bar.stories.tsx b/packages/react/src/components/progress-bar/progress-bar.stories.tsx
new file mode 100644
index 0000000..b2d209a
--- /dev/null
+++ b/packages/react/src/components/progress-bar/progress-bar.stories.tsx
@@ -0,0 +1,169 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Label} from "../label";
+
+import {ProgressBar} from "./index";
+
+const meta: Meta<typeof ProgressBar> = {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["default", "accent", "success", "warning", "danger"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: ProgressBar,
+  decorators: [
+    (Story) => (
+      <div className="w-96 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Feedback/ProgressBar",
+};
+
+export default meta;
+type Story = StoryObj<typeof ProgressBar>;
+
+export const Default: Story = {
+  render: (args) => {
+    return (
+      <ProgressBar value={60} {...args}>
+        <Label>Loading</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => {
+    return (
+      <div className="flex w-full flex-col gap-6">
+        <ProgressBar size="sm" value={40} {...args}>
+          <Label>Small</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar size="md" value={60} {...args}>
+          <Label>Medium</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar size="lg" value={80} {...args}>
+          <Label>Large</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+      </div>
+    );
+  },
+};
+
+export const Colors: Story = {
+  render: (args) => {
+    return (
+      <div className="flex w-full flex-col gap-6">
+        <ProgressBar color="default" value={50} {...args}>
+          <Label>Default</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar color="accent" value={50} {...args}>
+          <Label>Accent</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar color="success" value={50} {...args}>
+          <Label>Success</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar color="warning" value={50} {...args}>
+          <Label>Warning</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+        <ProgressBar color="danger" value={50} {...args}>
+          <Label>Danger</Label>
+          <ProgressBar.Output />
+          <ProgressBar.Track>
+            <ProgressBar.Fill />
+          </ProgressBar.Track>
+        </ProgressBar>
+      </div>
+    );
+  },
+};
+
+export const Indeterminate: Story = {
+  render: (args) => {
+    return (
+      <ProgressBar isIndeterminate {...args}>
+        <Label>Loading...</Label>
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    );
+  },
+};
+
+export const CustomValue: Story = {
+  render: (args) => {
+    return (
+      <ProgressBar
+        formatOptions={{style: "currency", currency: "USD"}}
+        maxValue={1000}
+        minValue={0}
+        value={750}
+        {...args}
+      >
+        <Label>Revenue</Label>
+        <ProgressBar.Output />
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    );
+  },
+};
+
+export const WithoutLabel: Story = {
+  render: (args) => {
+    return (
+      <ProgressBar aria-label="Loading progress" value={45} {...args}>
+        <ProgressBar.Track>
+          <ProgressBar.Fill />
+        </ProgressBar.Track>
+      </ProgressBar>
+    );
+  },
+};
diff --git a/packages/react/src/components/progress-bar/progress-bar.tsx b/packages/react/src/components/progress-bar/progress-bar.tsx
new file mode 100644
index 0000000..acfc2d8
--- /dev/null
+++ b/packages/react/src/components/progress-bar/progress-bar.tsx
@@ -0,0 +1,157 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ProgressBarVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {ProgressBarRenderProps} from "react-aria-components/ProgressBar";
+
+import {progressBarVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {ProgressBar as ProgressBarPrimitive} from "react-aria-components/ProgressBar";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressBar Context
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressBarContext {
+  slots?: ReturnType<typeof progressBarVariants>;
+  state?: ProgressBarRenderProps;
+}
+
+const ProgressBarContext = createContext<ProgressBarContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressBar Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressBarRootProps
+  extends ComponentPropsWithRef<typeof ProgressBarPrimitive>, ProgressBarVariants {}
+
+const ProgressBarRoot = ({children, className, color, size, ...props}: ProgressBarRootProps) => {
+  const slots = React.useMemo(() => progressBarVariants({color, size}), [color, size]);
+
+  return (
+    <ProgressBarPrimitive
+      data-slot="progress-bar"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(values) => (
+        <ProgressBarContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </ProgressBarContext>
+      )}
+    </ProgressBarPrimitive>
+  );
+};
+
+ProgressBarRoot.displayName = "HeroUI.ProgressBar";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressBar Output
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressBarOutputProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ProgressBarOutput = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: ProgressBarOutputProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressBarOutputProps<E>>) => {
+  const {slots, state} = use(ProgressBarContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.output, className)}
+      data-slot="progress-bar-output"
+      {...(props as any)}
+    >
+      {children ?? state?.valueText}
+    </dom.span>
+  );
+};
+
+ProgressBarOutput.displayName = "HeroUI.ProgressBar.Output";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressBar Track
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressBarTrackProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ProgressBarTrack = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: ProgressBarTrackProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressBarTrackProps<E>>) => {
+  const {slots} = use(ProgressBarContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.track, className)}
+      data-slot="progress-bar-track"
+      {...(props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+ProgressBarTrack.displayName = "HeroUI.ProgressBar.Track";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressBar Fill
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressBarFillProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+const ProgressBarFill = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  style,
+  ...props
+}: ProgressBarFillProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressBarFillProps<E>>) => {
+  const {slots, state} = use(ProgressBarContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.fill, className)}
+      data-slot="progress-bar-fill"
+      style={{
+        ...style,
+        width: state?.isIndeterminate ? undefined : `${state?.percentage ?? 0}%`,
+      }}
+      {...(props as any)}
+    />
+  );
+};
+
+ProgressBarFill.displayName = "HeroUI.ProgressBar.Fill";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ProgressBarRoot, ProgressBarOutput, ProgressBarTrack, ProgressBarFill};
+
+export type {
+  ProgressBarRootProps,
+  ProgressBarOutputProps,
+  ProgressBarTrackProps,
+  ProgressBarFillProps,
+};
diff --git a/packages/react/src/components/progress-circle/index.ts b/packages/react/src/components/progress-circle/index.ts
new file mode 100644
index 0000000..1815a3f
--- /dev/null
+++ b/packages/react/src/components/progress-circle/index.ts
@@ -0,0 +1,51 @@
+import type {ComponentProps} from "react";
+
+import {
+  ProgressCircleFillCircle,
+  ProgressCircleRoot,
+  ProgressCircleTrack,
+  ProgressCircleTrackCircle,
+} from "./progress-circle";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ProgressCircle = Object.assign(ProgressCircleRoot, {
+  Root: ProgressCircleRoot,
+  Track: ProgressCircleTrack,
+  TrackCircle: ProgressCircleTrackCircle,
+  FillCircle: ProgressCircleFillCircle,
+});
+
+export type ProgressCircle = {
+  Props: ComponentProps<typeof ProgressCircleRoot>;
+  RootProps: ComponentProps<typeof ProgressCircleRoot>;
+  TrackProps: ComponentProps<typeof ProgressCircleTrack>;
+  TrackCircleProps: ComponentProps<typeof ProgressCircleTrackCircle>;
+  FillCircleProps: ComponentProps<typeof ProgressCircleFillCircle>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  ProgressCircleRoot,
+  ProgressCircleTrack,
+  ProgressCircleTrackCircle,
+  ProgressCircleFillCircle,
+};
+
+export type {
+  ProgressCircleRootProps,
+  ProgressCircleRootProps as ProgressCircleProps,
+  ProgressCircleTrackProps,
+  ProgressCircleTrackCircleProps,
+  ProgressCircleFillCircleProps,
+} from "./progress-circle";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {progressCircleVariants} from "@heroui/styles";
+
+export type {ProgressCircleVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/progress-circle/progress-circle.stories.tsx b/packages/react/src/components/progress-circle/progress-circle.stories.tsx
new file mode 100644
index 0000000..2e859a6
--- /dev/null
+++ b/packages/react/src/components/progress-circle/progress-circle.stories.tsx
@@ -0,0 +1,137 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Label} from "../label";
+
+import {ProgressCircle} from "./index";
+
+const meta: Meta<typeof ProgressCircle> = {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["default", "accent", "success", "warning", "danger"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: ProgressCircle,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Feedback/ProgressCircle",
+};
+
+export default meta;
+type Story = StoryObj<typeof ProgressCircle>;
+
+export const Default: Story = {
+  render: (args) => {
+    return (
+      <ProgressCircle aria-label="Loading" value={60} {...args}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => {
+    return (
+      <div className="flex items-center gap-6">
+        <ProgressCircle aria-label="Loading" size="sm" value={40} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" size="md" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" size="lg" value={80} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+      </div>
+    );
+  },
+};
+
+export const Colors: Story = {
+  render: (args) => {
+    return (
+      <div className="flex items-center gap-6">
+        <ProgressCircle aria-label="Loading" color="default" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" color="accent" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" color="success" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" color="warning" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <ProgressCircle aria-label="Loading" color="danger" value={60} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+      </div>
+    );
+  },
+};
+
+export const Indeterminate: Story = {
+  render: (args) => {
+    return (
+      <ProgressCircle isIndeterminate aria-label="Loading" {...args}>
+        <ProgressCircle.Track>
+          <ProgressCircle.TrackCircle />
+          <ProgressCircle.FillCircle />
+        </ProgressCircle.Track>
+      </ProgressCircle>
+    );
+  },
+};
+
+export const WithLabel: Story = {
+  render: (args) => {
+    return (
+      <div className="flex items-center gap-3">
+        <ProgressCircle aria-label="Loading" value={75} {...args}>
+          <ProgressCircle.Track>
+            <ProgressCircle.TrackCircle />
+            <ProgressCircle.FillCircle />
+          </ProgressCircle.Track>
+        </ProgressCircle>
+        <Label>75% Complete</Label>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/progress-circle/progress-circle.tsx b/packages/react/src/components/progress-circle/progress-circle.tsx
new file mode 100644
index 0000000..b18a961
--- /dev/null
+++ b/packages/react/src/components/progress-circle/progress-circle.tsx
@@ -0,0 +1,184 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ProgressCircleVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {ProgressBarRenderProps} from "react-aria-components/ProgressBar";
+
+import {progressCircleVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {ProgressBar as ProgressBarPrimitive} from "react-aria-components/ProgressBar";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle Constants
+ * -----------------------------------------------------------------------------------------------*/
+const STROKE_WIDTH = 4;
+const CENTER = 18;
+const RADIUS = CENTER - STROKE_WIDTH / 2;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle Context
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressCircleContext {
+  slots?: ReturnType<typeof progressCircleVariants>;
+  state?: ProgressBarRenderProps;
+}
+
+const ProgressCircleContext = createContext<ProgressCircleContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressCircleRootProps
+  extends ComponentPropsWithRef<typeof ProgressBarPrimitive>, ProgressCircleVariants {}
+
+const ProgressCircleRoot = ({
+  children,
+  className,
+  color,
+  size,
+  ...props
+}: ProgressCircleRootProps) => {
+  const slots = React.useMemo(() => progressCircleVariants({color, size}), [color, size]);
+
+  return (
+    <ProgressBarPrimitive
+      data-slot="progress-circle"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(values) => (
+        <ProgressCircleContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </ProgressCircleContext>
+      )}
+    </ProgressBarPrimitive>
+  );
+};
+
+ProgressCircleRoot.displayName = "HeroUI.ProgressCircle";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle Track
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressCircleTrackProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ProgressCircleTrack = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: ProgressCircleTrackProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressCircleTrackProps<E>>) => {
+  const {slots} = use(ProgressCircleContext);
+
+  return (
+    <dom.svg
+      className={composeSlotClassName(slots?.track, className)}
+      data-slot="progress-circle-track"
+      fill="none"
+      viewBox={`0 0 ${CENTER * 2} ${CENTER * 2}`}
+      {...(props as any)}
+    >
+      {children}
+    </dom.svg>
+  );
+};
+
+ProgressCircleTrack.displayName = "HeroUI.ProgressCircle.Track";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle TrackCircle
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressCircleTrackCircleProps<
+  E extends keyof React.JSX.IntrinsicElements = "circle",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ProgressCircleTrackCircle = <E extends keyof React.JSX.IntrinsicElements = "circle">({
+  className,
+  ...props
+}: ProgressCircleTrackCircleProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressCircleTrackCircleProps<E>>) => {
+  const {slots} = use(ProgressCircleContext);
+
+  return (
+    <dom.circle
+      className={composeSlotClassName(slots?.trackCircle, className)}
+      cx={CENTER}
+      cy={CENTER}
+      data-slot="progress-circle-track-circle"
+      r={RADIUS}
+      strokeWidth={STROKE_WIDTH}
+      {...(props as any)}
+    />
+  );
+};
+
+ProgressCircleTrackCircle.displayName = "HeroUI.ProgressCircle.TrackCircle";
+
+/* -------------------------------------------------------------------------------------------------
+ * ProgressCircle FillCircle
+ * -----------------------------------------------------------------------------------------------*/
+interface ProgressCircleFillCircleProps<
+  E extends keyof React.JSX.IntrinsicElements = "circle",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const ProgressCircleFillCircle = <E extends keyof React.JSX.IntrinsicElements = "circle">({
+  className,
+  ...props
+}: ProgressCircleFillCircleProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ProgressCircleFillCircleProps<E>>) => {
+  const {slots, state} = use(ProgressCircleContext);
+  const percentage = state?.percentage ?? 0;
+  const isIndeterminate = state?.isIndeterminate ?? false;
+  const strokeDashoffset = CIRCUMFERENCE - (percentage / 100) * CIRCUMFERENCE;
+
+  return (
+    <dom.circle
+      className={composeSlotClassName(slots?.fillCircle, className)}
+      cx={CENTER}
+      cy={CENTER}
+      data-slot="progress-circle-fill-circle"
+      r={RADIUS}
+      strokeDasharray={CIRCUMFERENCE}
+      strokeDashoffset={isIndeterminate ? CIRCUMFERENCE * 0.75 : strokeDashoffset}
+      strokeLinecap="round"
+      strokeWidth={STROKE_WIDTH}
+      transform={`rotate(-90 ${CENTER} ${CENTER})`}
+      {...(props as any)}
+    />
+  );
+};
+
+ProgressCircleFillCircle.displayName = "HeroUI.ProgressCircle.FillCircle";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  ProgressCircleRoot,
+  ProgressCircleTrack,
+  ProgressCircleTrackCircle,
+  ProgressCircleFillCircle,
+};
+
+export type {
+  ProgressCircleRootProps,
+  ProgressCircleTrackProps,
+  ProgressCircleTrackCircleProps,
+  ProgressCircleFillCircleProps,
+};
diff --git a/packages/react/src/components/rac/components.tsx b/packages/react/src/components/rac/components.tsx
new file mode 100644
index 0000000..caedbd3
--- /dev/null
+++ b/packages/react/src/components/rac/components.tsx
@@ -0,0 +1,3 @@
+"use client";
+
+export {Collection, ListBoxLoadMoreItem, RouterProvider, I18nProvider} from "react-aria-components";
diff --git a/packages/react/src/components/rac/index.ts b/packages/react/src/components/rac/index.ts
new file mode 100644
index 0000000..36b21f1
--- /dev/null
+++ b/packages/react/src/components/rac/index.ts
@@ -0,0 +1,34 @@
+export {
+  isRTL,
+  useLocale,
+  useFilter,
+  Virtualizer,
+  TableLayout,
+  ListLayout,
+} from "react-aria-components";
+export {getLocalizationScript} from "react-aria-components/i18n";
+export {Collection, ListBoxLoadMoreItem, RouterProvider, I18nProvider} from "./components";
+export {parseColor} from "./utils";
+export type {
+  Key,
+  Direction,
+  Orientation,
+  PressEvent,
+  PointerType,
+  KeyboardEvent,
+  HoverEvent,
+  Selection,
+  TimeValue,
+  DateValue,
+  DateRange,
+  ValidationResult,
+  RangeValue,
+  RouterConfig,
+  Color,
+  ColorFormat,
+  ColorSpace,
+  ColorChannel,
+  ColorChannelRange,
+  ColorAxes,
+  SortDescriptor,
+} from "./types";
diff --git a/packages/react/src/components/rac/types.ts b/packages/react/src/components/rac/types.ts
new file mode 100644
index 0000000..19b47a2
--- /dev/null
+++ b/packages/react/src/components/rac/types.ts
@@ -0,0 +1,22 @@
+export type {
+  Key,
+  Direction,
+  Orientation,
+  PressEvent,
+  PointerType,
+  KeyboardEvent,
+  HoverEvent,
+  Selection,
+  RangeValue,
+  ValidationResult,
+  RouterConfig,
+} from "@react-types/shared";
+export type {TimeValue, DateValue, DateRange, SortDescriptor} from "react-aria-components";
+export type {
+  Color,
+  ColorFormat,
+  ColorSpace,
+  ColorChannel,
+  ColorChannelRange,
+  ColorAxes,
+} from "@react-types/color";
diff --git a/packages/react/src/components/rac/utils.tsx b/packages/react/src/components/rac/utils.tsx
new file mode 100644
index 0000000..2eb38ce
--- /dev/null
+++ b/packages/react/src/components/rac/utils.tsx
@@ -0,0 +1,3 @@
+"use client";
+
+export {parseColor} from "react-aria-components";
diff --git a/packages/react/src/components/radio-group/index.ts b/packages/react/src/components/radio-group/index.ts
new file mode 100644
index 0000000..bbf3c33
--- /dev/null
+++ b/packages/react/src/components/radio-group/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {RadioGroupRoot} from "./radio-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const RadioGroup = Object.assign(RadioGroupRoot, {
+  Root: RadioGroupRoot,
+});
+
+export type RadioGroup = {
+  Props: ComponentProps<typeof RadioGroupRoot>;
+  RootProps: ComponentProps<typeof RadioGroupRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {RadioGroupRoot};
+
+export type {RadioGroupRootProps, RadioGroupRootProps as RadioGroupProps} from "./radio-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {radioGroupVariants} from "@heroui/styles";
+
+export type {RadioGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/radio-group/radio-group.stories.tsx b/packages/react/src/components/radio-group/radio-group.stories.tsx
new file mode 100644
index 0000000..4642e1d
--- /dev/null
+++ b/packages/react/src/components/radio-group/radio-group.stories.tsx
@@ -0,0 +1,523 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+import {cx} from "tailwind-variants";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+import {Radio} from "../radio";
+
+import {RadioGroup} from "./index";
+
+export default {
+  argTypes: {},
+  component: RadioGroup,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Forms/RadioGroup",
+} as Meta<typeof RadioGroup>;
+
+type Story = StoryObj<typeof RadioGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="px-4">
+      <RadioGroup defaultValue="premium" name="plan">
+        <Label>Plan selection</Label>
+        <Description>Choose the plan that suits you best</Description>
+        <Radio value="basic">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Basic Plan
+          </Radio.Content>
+          <Description>Includes 100 messages per month</Description>
+        </Radio>
+        <Radio value="premium">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Premium Plan
+          </Radio.Content>
+          <Description>Includes 200 messages per month</Description>
+        </Radio>
+        <Radio value="business">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Business Plan
+          </Radio.Content>
+          <Description>Unlimited messages</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8 px-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Primary variant</p>
+        <RadioGroup defaultValue="option1" name="primary-plan" variant="primary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 1
+            </Radio.Content>
+            <Description>Standard styling with default background</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 2
+            </Radio.Content>
+            <Description>Another option with primary styling</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary variant</p>
+        <RadioGroup defaultValue="option1" name="secondary-plan" variant="secondary">
+          <Radio value="option1">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 1
+            </Radio.Content>
+            <Description>Lower emphasis variant for use in surfaces</Description>
+          </Radio>
+          <Radio value="option2">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Option 2
+            </Radio.Content>
+            <Description>Another option with secondary styling</Description>
+          </Radio>
+        </RadioGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const PerRadioInvalid: Story = {
+  render: () => (
+    <div className="px-4">
+      <RadioGroup defaultValue="premium" name="plan-invalid">
+        <Label>Plan selection</Label>
+        <Radio isInvalid isRequired value="basic">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Basic Plan
+          </Radio.Content>
+          <FieldError>This plan is not available for your account</FieldError>
+        </Radio>
+        <Radio value="premium">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Premium Plan
+          </Radio.Content>
+          <Description>Includes 200 messages per month</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  ),
+};
+
+export const WithCustomIndicator: Story = {
+  render: () => (
+    <div className="px-4">
+      <RadioGroup defaultValue="premium" name="plan-custom-indicator">
+        <Label>Plan selection</Label>
+        <Description>Choose the plan that suits you best</Description>
+        <Radio value="basic">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <span className="text-xs leading-none text-background">✓</span>
+                  ) : null
+                }
+              </Radio.Indicator>
+            </Radio.Control>
+            Basic Plan
+          </Radio.Content>
+          <Description>Includes 100 messages per month</Description>
+        </Radio>
+        <Radio value="premium">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <span className="text-xs leading-none text-background">✓</span>
+                  ) : null
+                }
+              </Radio.Indicator>
+            </Radio.Control>
+            Premium Plan
+          </Radio.Content>
+          <Description>Includes 200 messages per month</Description>
+        </Radio>
+        <Radio value="business">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator>
+                {({isSelected}) =>
+                  isSelected ? (
+                    <span className="text-xs leading-none text-background">✓</span>
+                  ) : null
+                }
+              </Radio.Indicator>
+            </Radio.Control>
+            Business Plan
+          </Radio.Content>
+          <Description>Unlimited messages</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  ),
+};
+
+export const Orientation: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 px-4">
+      <Label>Subscription plan</Label>
+      <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal">
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects and small teams</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting and analytics</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Share access with up to 10 teammates</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  ),
+};
+
+export const Validation: Story = {
+  render: () => {
+    return (
+      <Form
+        className="flex flex-col gap-4 px-4"
+        onSubmit={(e) => {
+          e.preventDefault();
+
+          const formData = new FormData(e.currentTarget);
+          const value = formData.get("plan-validation");
+
+          alert(`Your chosen plan is: ${value}`);
+        }}
+      >
+        <RadioGroup isRequired name="plan-validation">
+          <Label>Subscription plan</Label>
+          <Radio value="starter">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Starter
+            </Radio.Content>
+            <Description>For side projects and small teams</Description>
+          </Radio>
+          <Radio value="pro">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Pro
+            </Radio.Content>
+            <Description>Advanced reporting and analytics</Description>
+          </Radio>
+          <Radio value="teams">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Teams
+            </Radio.Content>
+            <Description>Share access with up to 10 teammates</Description>
+          </Radio>
+          <FieldError>Choose a subscription before continuing.</FieldError>
+        </RadioGroup>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState("pro");
+
+    return (
+      <div className="flex flex-col gap-3 px-4">
+        <RadioGroup name="plan-controlled" value={value} onChange={setValue}>
+          <Label>Subscription plan</Label>
+          <Radio value="starter">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Starter
+            </Radio.Content>
+            <Description>For side projects and small teams</Description>
+          </Radio>
+          <Radio value="pro">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Pro
+            </Radio.Content>
+            <Description>Advanced reporting and analytics</Description>
+          </Radio>
+          <Radio value="teams">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Teams
+            </Radio.Content>
+            <Description>Share access with up to 10 teammates</Description>
+          </Radio>
+        </RadioGroup>
+        <p className="mt-2 text-sm text-muted">
+          Selected plan: <span className="font-medium">{value}</span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Uncontrolled: Story = {
+  render: () => {
+    const [selection, setSelection] = React.useState("pro");
+
+    return (
+      <div className="flex flex-col gap-3 px-4">
+        <RadioGroup
+          defaultValue="pro"
+          name="plan-uncontrolled"
+          onChange={(nextValue) => setSelection(nextValue)}
+        >
+          <Label>Subscription plan</Label>
+          <Radio value="starter">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Starter
+            </Radio.Content>
+            <Description>For side projects and small teams</Description>
+          </Radio>
+          <Radio value="pro">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Pro
+            </Radio.Content>
+            <Description>Advanced reporting and analytics</Description>
+          </Radio>
+          <Radio value="teams">
+            <Radio.Content>
+              <Radio.Control>
+                <Radio.Indicator />
+              </Radio.Control>
+              Teams
+            </Radio.Content>
+            <Description>Share access with up to 10 teammates</Description>
+          </Radio>
+        </RadioGroup>
+        <p className="mt-2 text-sm text-muted">
+          Last chosen plan: <span className="font-medium">{selection}</span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="px-4">
+      <RadioGroup isDisabled defaultValue="pro" name="plan-disabled">
+        <Label>Subscription plan</Label>
+        <Description>Plan changes are temporarily paused while we roll out updates.</Description>
+        <Radio value="starter">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Starter
+          </Radio.Content>
+          <Description>For side projects and small teams</Description>
+        </Radio>
+        <Radio value="pro">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Pro
+          </Radio.Content>
+          <Description>Advanced reporting and analytics</Description>
+        </Radio>
+        <Radio value="teams">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+            Teams
+          </Radio.Content>
+          <Description>Share access with up to 10 teammates</Description>
+        </Radio>
+      </RadioGroup>
+    </div>
+  ),
+};
+
+export const DeliveryAndPaymentExample: Story = {
+  render: () => {
+    const deliveryOptions = [
+      {
+        description: "4-10 business days",
+        price: "$5.00",
+        value: "standard",
+        title: "Standard",
+      },
+      {
+        description: "2-5 business days",
+        price: "$16.00",
+        value: "express",
+        title: "Express",
+      },
+      {
+        description: "1 business day",
+        price: "$25.00",
+        value: "super-fast",
+        title: "Super Fast",
+      },
+    ];
+
+    const paymentOptions = [
+      {
+        title: "**** 8304",
+        value: "mastercard",
+        description: "Exp. on 01/2026",
+        icon: "uim:master-card",
+      },
+      {
+        title: "**** 0123",
+        value: "visa",
+        description: "Exp. on 01/2026",
+        icon: "streamline-logos:visa-logo-solid",
+      },
+      {
+        title: "PayPal",
+        description: "Pay with PayPal",
+        value: "paypal",
+        icon: "ic:baseline-paypal",
+      },
+    ];
+
+    return (
+      <div className="flex w-full flex-col items-center gap-10 px-4 py-8">
+        <section className="flex w-full max-w-lg flex-col gap-4">
+          <RadioGroup defaultValue="express" name="delivery">
+            <Label>Delivery method</Label>
+            <div className="grid gap-x-4 md:grid-cols-3">
+              {deliveryOptions.map((option) => (
+                <Radio key={option.value} value={option.value}>
+                  <Radio.Content
+                    className={cx(
+                      "group relative flex w-full flex-col gap-6 rounded-xl bg-surface-tertiary px-5 py-4 transition-all data-[selected=true]:border-accent data-[selected=true]:bg-accent/10",
+                      "data-[focus-visible=true]:bg-accent/10",
+                    )}
+                  >
+                    <Radio.Control className="absolute top-3 right-4 size-5">
+                      <Radio.Indicator />
+                    </Radio.Control>
+                    <div className="flex flex-col gap-1">
+                      <span>{option.title}</span>
+                      <Description>{option.description}</Description>
+                    </div>
+                    <span className="text-sm font-semibold">{option.price}</span>
+                  </Radio.Content>
+                </Radio>
+              ))}
+            </div>
+          </RadioGroup>
+        </section>
+        <section className="flex w-full max-w-lg flex-col gap-4">
+          <RadioGroup defaultValue="visa" name="payment">
+            <div className="flex flex-wrap items-center justify-between gap-4">
+              <Label>Payment method</Label>
+            </div>
+            <div className="grid gap-x-4 md:grid-cols-2">
+              {paymentOptions.map((option) => (
+                <Radio key={option.value} value={option.value}>
+                  <Radio.Content
+                    className={cx(
+                      "group relative flex w-full flex-row items-start justify-start gap-4 rounded-xl bg-surface-tertiary px-5 py-4 transition-all",
+                      "data-[selected=true]:bg-accent/10",
+                    )}
+                  >
+                    <Radio.Control className="absolute top-3 right-4 size-5">
+                      <Radio.Indicator />
+                    </Radio.Control>
+                    <Icon className="size-6 text-accent" icon={option.icon} />
+                    <div className="flex flex-col gap-1">
+                      <span>{option.title}</span>
+                      <Description>{option.description}</Description>
+                    </div>
+                  </Radio.Content>
+                </Radio>
+              ))}
+            </div>
+          </RadioGroup>
+        </section>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/radio-group/radio-group.tsx b/packages/react/src/components/radio-group/radio-group.tsx
new file mode 100644
index 0000000..bcb1d41
--- /dev/null
+++ b/packages/react/src/components/radio-group/radio-group.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import type {RadioGroupVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {radioGroupVariants} from "@heroui/styles";
+import React from "react";
+import {RadioGroup as RadioGroupPrimitive} from "react-aria-components/RadioGroup";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * Radio Group Root
+ * -----------------------------------------------------------------------------------------------*/
+interface RadioGroupRootProps
+  extends ComponentPropsWithRef<typeof RadioGroupPrimitive>, RadioGroupVariants {}
+
+const RadioGroupRoot = ({children, className, variant, ...props}: RadioGroupRootProps) => {
+  const styles = React.useMemo(() => radioGroupVariants({variant}), [variant]);
+
+  return (
+    <RadioGroupPrimitive
+      data-slot="radio-group"
+      {...props}
+      className={composeTwRenderProps(className, styles)}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </RadioGroupPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {RadioGroupRoot};
+
+export type {RadioGroupRootProps};
diff --git a/packages/react/src/components/radio/index.ts b/packages/react/src/components/radio/index.ts
new file mode 100644
index 0000000..a9f5bc0
--- /dev/null
+++ b/packages/react/src/components/radio/index.ts
@@ -0,0 +1,43 @@
+import type {ComponentProps} from "react";
+
+import {RadioContent, RadioControl, RadioIndicator, RadioRoot} from "./radio";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Radio = Object.assign(RadioRoot, {
+  Root: RadioRoot,
+  Content: RadioContent,
+  Control: RadioControl,
+  Indicator: RadioIndicator,
+});
+
+export type Radio = {
+  Props: ComponentProps<typeof RadioRoot>;
+  RootProps: ComponentProps<typeof RadioRoot>;
+  ContentProps: ComponentProps<typeof RadioContent>;
+  ControlProps: ComponentProps<typeof RadioControl>;
+  IndicatorProps: ComponentProps<typeof RadioIndicator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {RadioContent, RadioControl, RadioIndicator, RadioRoot};
+
+export type {
+  RadioRootProps,
+  RadioRootProps as RadioProps,
+  RadioContentProps,
+  RadioControlProps,
+  RadioIndicatorProps,
+  RadioFieldRenderProps,
+  RadioButtonRenderProps,
+} from "./radio";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {radioVariants} from "@heroui/styles";
+
+export type {RadioVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/radio/radio.tsx b/packages/react/src/components/radio/radio.tsx
new file mode 100644
index 0000000..36ca40a
--- /dev/null
+++ b/packages/react/src/components/radio/radio.tsx
@@ -0,0 +1,146 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {RadioButtonRenderProps, RadioFieldRenderProps} from "react-aria-components/RadioGroup";
+
+import {radioVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  RadioButton as RadioButtonPrimitive,
+  RadioField as RadioFieldPrimitive,
+} from "react-aria-components/RadioGroup";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+interface RadioContext {
+  slots?: ReturnType<typeof radioVariants>;
+  state?: RadioFieldRenderProps;
+}
+
+const RadioContext = createContext<RadioContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Radio (Field) — React Aria `RadioField`.
+ * -----------------------------------------------------------------------------------------------*/
+interface RadioRootProps extends ComponentPropsWithRef<typeof RadioFieldPrimitive> {
+  /** The name of the radio button, used when submitting an HTML form. */
+  name?: string;
+}
+
+const RadioRoot = ({children, className, ...props}: RadioRootProps) => {
+  const slots = React.useMemo(() => radioVariants(), []);
+
+  return (
+    <RadioFieldPrimitive
+      data-slot="radio"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(state) => (
+        <RadioContext value={{slots, state}}>
+          {typeof children === "function" ? children(state) : children}
+        </RadioContext>
+      )}
+    </RadioFieldPrimitive>
+  );
+};
+
+RadioRoot.displayName = "HeroUI.Radio";
+
+/* -------------------------------------------------------------------------------------------------
+ * Radio.Content — the clickable `RadioButton` label wrapping the control + `Label`.
+ * Keep `Description`/`FieldError` as siblings of `Radio.Content`.
+ * -----------------------------------------------------------------------------------------------*/
+interface RadioContentProps extends ComponentPropsWithRef<typeof RadioButtonPrimitive> {}
+
+const RadioContent = ({children, className, ...props}: RadioContentProps) => {
+  const {slots} = use(RadioContext);
+
+  return (
+    <RadioButtonPrimitive
+      data-slot="radio-content"
+      {...props}
+      className={composeTwRenderProps(className, slots?.content())}
+    >
+      {children}
+    </RadioButtonPrimitive>
+  );
+};
+
+RadioContent.displayName = "HeroUI.Radio.Content";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface RadioControlProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const RadioControl = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: RadioControlProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof RadioControlProps<E>>) => {
+  const {slots} = use(RadioContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.control, className)}
+      data-slot="radio-control"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+RadioControl.displayName = "HeroUI.Radio.Control";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface RadioIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode | ((props: RadioFieldRenderProps) => ReactNode);
+  className?: string;
+}
+
+const RadioIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: RadioIndicatorProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof RadioIndicatorProps<E>>) => {
+  const {slots, state} = use(RadioContext);
+
+  const content =
+    typeof children === "function" ? children(state ?? ({} as RadioFieldRenderProps)) : children;
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="radio-indicator"
+      {...(props as any)}
+    >
+      {content}
+    </dom.span>
+  );
+};
+
+RadioIndicator.displayName = "HeroUI.Radio.Indicator";
+
+/* ----------------------------------------------------------------------------------------------*/
+
+export {RadioRoot, RadioContent, RadioControl, RadioIndicator};
+export type {
+  RadioRootProps,
+  RadioContentProps,
+  RadioControlProps,
+  RadioIndicatorProps,
+  RadioFieldRenderProps,
+  RadioButtonRenderProps,
+};
diff --git a/packages/react/src/components/range-calendar/index.ts b/packages/react/src/components/range-calendar/index.ts
new file mode 100644
index 0000000..a188d07
--- /dev/null
+++ b/packages/react/src/components/range-calendar/index.ts
@@ -0,0 +1,108 @@
+import type {ComponentProps} from "react";
+
+import {
+  CalendarYearPickerCell,
+  CalendarYearPickerGrid,
+  CalendarYearPickerGridBody,
+  CalendarYearPickerTrigger,
+  CalendarYearPickerTriggerHeading,
+  CalendarYearPickerTriggerIndicator,
+} from "../calendar-year-picker";
+
+import {
+  RangeCalendarCell,
+  RangeCalendarCellIndicator,
+  RangeCalendarGrid,
+  RangeCalendarGridBody,
+  RangeCalendarGridHeader,
+  RangeCalendarHeader,
+  RangeCalendarHeaderCell,
+  RangeCalendarHeading,
+  RangeCalendarNavButton,
+  RangeCalendarRoot,
+} from "./range-calendar";
+
+/* -------------------------------------------------------------------------------------------------
+| * Compound Component
+| * -----------------------------------------------------------------------------------------------*/
+export const RangeCalendar = Object.assign(RangeCalendarRoot, {
+  Root: RangeCalendarRoot,
+  Header: RangeCalendarHeader,
+  Heading: RangeCalendarHeading,
+  NavButton: RangeCalendarNavButton,
+  Grid: RangeCalendarGrid,
+  GridHeader: RangeCalendarGridHeader,
+  GridBody: RangeCalendarGridBody,
+  HeaderCell: RangeCalendarHeaderCell,
+  Cell: RangeCalendarCell,
+  CellIndicator: RangeCalendarCellIndicator,
+  YearPickerTrigger: CalendarYearPickerTrigger,
+  YearPickerTriggerHeading: CalendarYearPickerTriggerHeading,
+  YearPickerTriggerIndicator: CalendarYearPickerTriggerIndicator,
+  YearPickerGrid: CalendarYearPickerGrid,
+  YearPickerGridBody: CalendarYearPickerGridBody,
+  YearPickerCell: CalendarYearPickerCell,
+});
+
+export type RangeCalendar = {
+  Props: ComponentProps<typeof RangeCalendarRoot>;
+  RootProps: ComponentProps<typeof RangeCalendarRoot>;
+  HeaderProps: ComponentProps<typeof RangeCalendarHeader>;
+  HeadingProps: ComponentProps<typeof RangeCalendarHeading>;
+  NavButtonProps: ComponentProps<typeof RangeCalendarNavButton>;
+  GridProps: ComponentProps<typeof RangeCalendarGrid>;
+  GridHeaderProps: ComponentProps<typeof RangeCalendarGridHeader>;
+  GridBodyProps: ComponentProps<typeof RangeCalendarGridBody>;
+  HeaderCellProps: ComponentProps<typeof RangeCalendarHeaderCell>;
+  CellProps: ComponentProps<typeof RangeCalendarCell>;
+  CellIndicatorProps: ComponentProps<typeof RangeCalendarCellIndicator>;
+  YearPickerTriggerProps: ComponentProps<typeof CalendarYearPickerTrigger>;
+  YearPickerTriggerHeadingProps: ComponentProps<typeof CalendarYearPickerTriggerHeading>;
+  YearPickerTriggerIndicatorProps: ComponentProps<typeof CalendarYearPickerTriggerIndicator>;
+  YearPickerGridProps: ComponentProps<typeof CalendarYearPickerGrid>;
+  YearPickerGridBodyProps: ComponentProps<typeof CalendarYearPickerGridBody>;
+  YearPickerCellProps: ComponentProps<typeof CalendarYearPickerCell>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+| * Named Component
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  RangeCalendarRoot,
+  RangeCalendarHeader,
+  RangeCalendarHeading,
+  RangeCalendarNavButton,
+  RangeCalendarGrid,
+  RangeCalendarGridHeader,
+  RangeCalendarGridBody,
+  RangeCalendarHeaderCell,
+  RangeCalendarCell,
+  RangeCalendarCellIndicator,
+};
+
+export type {
+  RangeCalendarRootProps,
+  RangeCalendarRootProps as RangeCalendarProps,
+  RangeCalendarHeaderProps,
+  RangeCalendarHeadingProps,
+  RangeCalendarNavButtonProps,
+  RangeCalendarGridProps,
+  RangeCalendarGridHeaderProps,
+  RangeCalendarGridBodyProps,
+  RangeCalendarHeaderCellProps,
+  RangeCalendarCellProps,
+  RangeCalendarCellIndicatorProps,
+} from "./range-calendar";
+
+/* -------------------------------------------------------------------------------------------------
+| * YearPickerContext (re-exported from calendar-year-picker for convenience)
+| * -----------------------------------------------------------------------------------------------*/
+export {YearPickerContext, useYearPicker, useCalendarOrRangeState} from "../calendar-year-picker";
+export type {YearPickerContextValue} from "../calendar-year-picker";
+
+/* -------------------------------------------------------------------------------------------------
+| * Variants
+| * -----------------------------------------------------------------------------------------------*/
+export {rangeCalendarVariants} from "@heroui/styles";
+
+export type {RangeCalendarVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/range-calendar/range-calendar.stories.tsx b/packages/react/src/components/range-calendar/range-calendar.stories.tsx
new file mode 100644
index 0000000..eb693bd
--- /dev/null
+++ b/packages/react/src/components/range-calendar/range-calendar.stories.tsx
@@ -0,0 +1,793 @@
+import type {CalendarDate, DateValue} from "@internationalized/date";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {
+  getLocalTimeZone,
+  isToday,
+  isWeekend,
+  parseDate,
+  startOfMonth,
+  startOfWeek,
+  today,
+} from "@internationalized/date";
+import React, {useState} from "react";
+import {I18nProvider, useLocale} from "react-aria-components/I18nProvider";
+
+import {Button} from "../button";
+import {ButtonGroup} from "../button-group";
+import {Description} from "../description";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Select} from "../select";
+
+import {RangeCalendar} from "./index";
+
+const meta: Meta<typeof RangeCalendar> = {
+  argTypes: {
+    allowsNonContiguousRanges: {
+      control: "boolean",
+    },
+    isDisabled: {
+      control: "boolean",
+    },
+    isReadOnly: {
+      control: "boolean",
+    },
+    weeksInMonth: {
+      control: {type: "number", min: 4, max: 6, step: 1},
+    },
+  },
+  component: RangeCalendar,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/RangeCalendar",
+};
+
+export default meta;
+type Story = StoryObj<typeof RangeCalendar>;
+
+type DateRange = {
+  start: DateValue;
+  end: DateValue;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Helper component to render a basic range calendar structure
+ * -----------------------------------------------------------------------------------------------*/
+const RangeCalendarTemplate = (
+  props: Omit<React.ComponentProps<typeof RangeCalendar>, "children">,
+) => (
+  <RangeCalendar {...props}>
+    <RangeCalendar.Header>
+      <RangeCalendar.Heading />
+      <RangeCalendar.NavButton slot="previous" />
+      <RangeCalendar.NavButton slot="next" />
+    </RangeCalendar.Header>
+    <RangeCalendar.Grid>
+      <RangeCalendar.GridHeader>
+        {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+      </RangeCalendar.GridHeader>
+      <RangeCalendar.GridBody>
+        {(date) => <RangeCalendar.Cell date={date} />}
+      </RangeCalendar.GridBody>
+    </RangeCalendar.Grid>
+  </RangeCalendar>
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Helper component to render a range calendar with year picker
+ * -----------------------------------------------------------------------------------------------*/
+const RangeCalendarTemplateWithYearPicker = (
+  props: Omit<React.ComponentProps<typeof RangeCalendar>, "children">,
+) => (
+  <RangeCalendar {...props}>
+    <RangeCalendar.Header>
+      <RangeCalendar.YearPickerTrigger>
+        <RangeCalendar.YearPickerTriggerHeading />
+        <RangeCalendar.YearPickerTriggerIndicator />
+      </RangeCalendar.YearPickerTrigger>
+      <RangeCalendar.NavButton slot="previous" />
+      <RangeCalendar.NavButton slot="next" />
+    </RangeCalendar.Header>
+    <RangeCalendar.Grid>
+      <RangeCalendar.GridHeader>
+        {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+      </RangeCalendar.GridHeader>
+      <RangeCalendar.GridBody>
+        {(date) => <RangeCalendar.Cell date={date} />}
+      </RangeCalendar.GridBody>
+    </RangeCalendar.Grid>
+    <RangeCalendar.YearPickerGrid>
+      <RangeCalendar.YearPickerGridBody>
+        {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+      </RangeCalendar.YearPickerGridBody>
+    </RangeCalendar.YearPickerGrid>
+  </RangeCalendar>
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Stories
+ * -----------------------------------------------------------------------------------------------*/
+export const Default: Story = {
+  render: (args) => <RangeCalendarTemplate {...args} aria-label="Trip dates" />,
+};
+
+export const WithYearPicker: Story = {
+  render: (args) => <RangeCalendarTemplateWithYearPicker {...args} aria-label="Trip dates" />,
+};
+
+export const DefaultValue: Story = {
+  render: (args) => (
+    <RangeCalendarTemplate
+      {...args}
+      aria-label="Trip dates"
+      defaultValue={{end: parseDate("2025-02-12"), start: parseDate("2025-02-03")}}
+    />
+  ),
+};
+
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<DateRange | null>(null);
+    const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25"));
+    const {locale} = useLocale();
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <ButtonGroup variant="tertiary">
+          <Button
+            onPress={() => {
+              const start = today(getLocalTimeZone());
+
+              setValue({end: start.add({days: 6}), start});
+              setFocusedDate(start);
+            }}
+          >
+            This week
+          </Button>
+          <Button
+            onPress={() => {
+              const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale);
+
+              setValue({end: nextWeekStart.add({days: 6}), start: nextWeekStart});
+              setFocusedDate(nextWeekStart);
+            }}
+          >
+            Next week
+          </Button>
+          <Button
+            onPress={() => {
+              const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1}));
+
+              setValue({end: nextMonthStart.add({days: 9}), start: nextMonthStart});
+              setFocusedDate(nextMonthStart);
+            }}
+          >
+            Next month
+          </Button>
+        </ButtonGroup>
+        <RangeCalendarTemplate
+          {...args}
+          aria-label="Trip dates"
+          focusedValue={focusedDate}
+          value={value}
+          onChange={setValue}
+          onFocusChange={setFocusedDate}
+        />
+        <Description className="text-center">
+          Selected range:{" "}
+          {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(none)"}
+        </Description>
+        <div className="flex gap-2">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const start = today(getLocalTimeZone());
+
+              setValue({end: start.add({days: 6}), start});
+              setFocusedDate(start);
+            }}
+          >
+            Set 1 week
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => {
+              const start = parseDate("2025-12-20");
+
+              setValue({end: parseDate("2025-12-31"), start});
+              setFocusedDate(start);
+            }}
+          >
+            Set Holidays
+          </Button>
+          <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
+            Clear
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const MinMaxDates: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+    const minDate = now;
+    const maxDate = now.add({months: 3});
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendar
+          {...args}
+          aria-label="Trip dates"
+          defaultValue={{end: now.add({days: 5}), start: now.add({days: 2})}}
+          maxValue={maxDate}
+          minValue={minDate}
+        >
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.YearPickerTrigger>
+              <RangeCalendar.YearPickerTriggerHeading />
+              <RangeCalendar.YearPickerTriggerIndicator />
+            </RangeCalendar.YearPickerTrigger>
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+          <RangeCalendar.YearPickerGrid>
+            <RangeCalendar.YearPickerGridBody>
+              {({year}) => <RangeCalendar.YearPickerCell year={year} />}
+            </RangeCalendar.YearPickerGridBody>
+          </RangeCalendar.YearPickerGrid>
+        </RangeCalendar>
+        <Description className="text-center">
+          Select dates between today and {maxDate.toString()}
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const UnavailableDates: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+    const blockedRanges = [
+      [now.add({days: 2}), now.add({days: 5})],
+      [now.add({days: 12}), now.add({days: 13})],
+    ] as const;
+
+    const isDateUnavailable = (date: DateValue) => {
+      return blockedRanges.some(
+        ([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0,
+      );
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendarTemplate
+          {...args}
+          aria-label="Trip dates"
+          defaultValue={{end: now.add({days: 9}), start: now.add({days: 6})}}
+          isDateUnavailable={isDateUnavailable}
+        />
+        <Description className="text-center">Some days are unavailable</Description>
+      </div>
+    );
+  },
+};
+
+export const WeeksInMonth: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendarTemplate {...args} aria-label="Trip dates" weeksInMonth={6} />
+      <Description className="text-center">
+        Fixed to 6 weeks per month to avoid layout shift
+      </Description>
+    </div>
+  ),
+};
+
+export const AnchorUnavailableDates: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+
+    const isDateUnavailable = (date: DateValue, anchorDate: CalendarDate | null) => {
+      return anchorDate != null && Math.abs(date.compare(anchorDate)) > 7;
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendarTemplate
+          {...args}
+          aria-label="Trip dates"
+          isDateUnavailable={isDateUnavailable}
+          minValue={now}
+        />
+        <Description className="text-center">
+          After selecting a start date, only dates within 7 days are available
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const AllowsNonContiguousRanges: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+    const blockedRanges = [
+      [now.add({days: 2}), now.add({days: 5})],
+      [now.add({days: 12}), now.add({days: 13})],
+    ] as const;
+
+    const isDateUnavailable = (date: DateValue) => {
+      return blockedRanges.some(
+        ([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0,
+      );
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendarTemplate
+          {...args}
+          allowsNonContiguousRanges
+          aria-label="Trip dates"
+          defaultValue={{end: now.add({days: 9}), start: now.add({days: 1})}}
+          isDateUnavailable={isDateUnavailable}
+        />
+        <Description className="text-center">
+          Non-contiguous ranges are allowed across unavailable dates
+        </Description>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendarTemplate
+        {...args}
+        isDisabled
+        aria-label="Trip dates"
+        defaultValue={{
+          end: today(getLocalTimeZone()).add({days: 4}),
+          start: today(getLocalTimeZone()),
+        }}
+      />
+      <Description className="text-center">Range calendar is disabled</Description>
+    </div>
+  ),
+};
+
+export const ReadOnly: Story = {
+  render: (args) => (
+    <div className="flex flex-col items-center gap-4">
+      <RangeCalendarTemplate
+        {...args}
+        isReadOnly
+        aria-label="Trip dates"
+        defaultValue={{
+          end: today(getLocalTimeZone()).add({days: 4}),
+          start: today(getLocalTimeZone()),
+        }}
+      />
+      <Description className="text-center">Range calendar is read-only</Description>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: (args) => {
+    const now = today(getLocalTimeZone());
+    const [value, setValue] = useState<DateRange>({
+      end: now.add({days: 14}),
+      start: now.add({days: 6}),
+    });
+    const isInvalid = value.end.compare(value.start) > 7;
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendarTemplate
+          {...args}
+          aria-label="Trip dates"
+          isInvalid={isInvalid}
+          value={value}
+          onChange={setValue}
+        />
+        {isInvalid ? (
+          <p className="text-sm text-danger">Maximum stay duration is 1 week</p>
+        ) : (
+          <Description className="text-center">Select a stay of up to 7 days</Description>
+        )}
+      </div>
+    );
+  },
+};
+
+export const FocusedValue: Story = {
+  render: (args) => {
+    const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendarTemplate
+          {...args}
+          aria-label="Trip dates"
+          focusedValue={focusedDate}
+          onFocusChange={setFocusedDate}
+        />
+        <Description className="text-center">Focused: {focusedDate.toString()}</Description>
+        <div className="flex flex-wrap justify-center gap-2">
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-01-01"))}
+          >
+            Go to Jan
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-06-15"))}
+          >
+            Go to Jun
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onPress={() => setFocusedDate(parseDate("2025-12-25"))}
+          >
+            Go to Christmas
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+// Sample dates that have events (for demo purposes)
+const datesWithEvents = [3, 7, 12, 15, 21, 28];
+
+export const WithIndicators: Story = {
+  render: (args) => (
+    <RangeCalendar {...args} aria-label="Trip dates">
+      <RangeCalendar.Header>
+        <RangeCalendar.NavButton slot="previous" />
+        <RangeCalendar.Heading />
+        <RangeCalendar.NavButton slot="next" />
+      </RangeCalendar.Header>
+      <RangeCalendar.Grid>
+        <RangeCalendar.GridHeader>
+          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+        </RangeCalendar.GridHeader>
+        <RangeCalendar.GridBody>
+          {(date) => (
+            <RangeCalendar.Cell date={date}>
+              {({formattedDate}) => (
+                <>
+                  {formattedDate}
+                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
+                    <RangeCalendar.CellIndicator />
+                  )}
+                </>
+              )}
+            </RangeCalendar.Cell>
+          )}
+        </RangeCalendar.GridBody>
+      </RangeCalendar.Grid>
+    </RangeCalendar>
+  ),
+};
+
+export const MultipleMonths: Story = {
+  render: (args) => (
+    <RangeCalendar
+      {...args}
+      aria-label="Trip dates"
+      className="@container-normal w-full max-w-none overflow-x-auto"
+      visibleDuration={{months: 2}}
+    >
+      <div className="mx-auto flex w-max gap-8">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading className="flex-none" />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading className="flex-none" offset={{months: 1}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  ),
+};
+
+export const ThreeMonths: Story = {
+  render: (args) => (
+    <RangeCalendar
+      {...args}
+      aria-label="Vacation planning"
+      className="@container-normal w-auto overflow-x-auto"
+      visibleDuration={{months: 3}}
+    >
+      <div className="flex w-max gap-7">
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading offset={{months: 1}} />
+            <div className="size-6" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 1}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+        <div className="w-64">
+          <RangeCalendar.Header>
+            <div className="size-6" />
+            <RangeCalendar.Heading offset={{months: 2}} />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid offset={{months: 2}}>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </div>
+      </div>
+    </RangeCalendar>
+  ),
+};
+
+const dayViewOptions = [
+  {id: "1", name: "1 day"},
+  {id: "5", name: "5 days"},
+  {id: "7", name: "7 days"},
+  {id: "8", name: "8 days"},
+  {id: "10", name: "10 days"},
+  {id: "14", name: "14 days"},
+  {id: "21", name: "21 days"},
+] as const;
+
+export const DayView: Story = {
+  render: (args) => {
+    const [days, setDays] = useState(5);
+
+    return (
+      <div className="flex flex-col items-center gap-6">
+        <Select
+          className="w-40"
+          value={String(days)}
+          onChange={(value) => value && setDays(Number(value))}
+        >
+          <Label>Visible days</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {dayViewOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                  {option.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        <RangeCalendar key={days} {...args} aria-label="Trip dates" visibleDuration={{days}}>
+          <RangeCalendar.Header>
+            <RangeCalendar.Heading />
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </div>
+    );
+  },
+};
+
+const weekViewOptions = [
+  {id: "1", name: "1 week"},
+  {id: "2", name: "2 weeks"},
+  {id: "3", name: "3 weeks"},
+  {id: "4", name: "4 weeks"},
+  {id: "5", name: "5 weeks"},
+  {id: "6", name: "6 weeks"},
+  {id: "8", name: "8 weeks"},
+] as const;
+
+export const WeekView: Story = {
+  render: (args) => {
+    const [weeks, setWeeks] = useState(1);
+
+    return (
+      <div className="flex flex-col items-center gap-6">
+        <Select
+          className="w-40"
+          value={String(weeks)}
+          onChange={(value) => value && setWeeks(Number(value))}
+        >
+          <Label>Visible weeks</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {weekViewOptions.map((option) => (
+                <ListBox.Item key={option.id} id={option.id} textValue={option.name}>
+                  {option.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        <RangeCalendar key={weeks} {...args} aria-label="Trip dates" visibleDuration={{weeks}}>
+          <RangeCalendar.Header>
+            <RangeCalendar.Heading />
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => <RangeCalendar.Cell date={date} />}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+      </div>
+    );
+  },
+};
+
+export const InternationalCalendar: Story = {
+  render: (args) => (
+    <I18nProvider locale="hi-IN-u-ca-indian">
+      <RangeCalendarTemplateWithYearPicker
+        {...args}
+        aria-label="Trip dates"
+        defaultValue={{
+          end: today(getLocalTimeZone()).add({days: 7}),
+          start: today(getLocalTimeZone()),
+        }}
+      />
+    </I18nProvider>
+  ),
+};
+
+export const BookingCalendar: Story = {
+  render: (args) => {
+    const [selectedRange, setSelectedRange] = useState<DateRange | null>(null);
+    const {locale} = useLocale();
+
+    // Simulated blocked dates
+    const blockedDates = [5, 6, 12, 13, 14, 20];
+
+    const isDateUnavailable = (date: DateValue) => {
+      // Weekends and already blocked dates are unavailable
+      return isWeekend(date, locale) || blockedDates.includes(date.day);
+    };
+
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <RangeCalendar
+          {...args}
+          aria-label="Booking range"
+          isDateUnavailable={isDateUnavailable}
+          minValue={today(getLocalTimeZone())}
+          value={selectedRange}
+          onChange={setSelectedRange}
+        >
+          <RangeCalendar.Header>
+            <RangeCalendar.NavButton slot="previous" />
+            <RangeCalendar.Heading />
+            <RangeCalendar.NavButton slot="next" />
+          </RangeCalendar.Header>
+          <RangeCalendar.Grid>
+            <RangeCalendar.GridHeader>
+              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
+            </RangeCalendar.GridHeader>
+            <RangeCalendar.GridBody>
+              {(date) => (
+                <RangeCalendar.Cell date={date}>
+                  {({formattedDate, isUnavailable}) => (
+                    <>
+                      {formattedDate}
+                      {!isUnavailable &&
+                        !isWeekend(date, locale) &&
+                        blockedDates.includes(date.day) && <RangeCalendar.CellIndicator />}
+                    </>
+                  )}
+                </RangeCalendar.Cell>
+              )}
+            </RangeCalendar.GridBody>
+          </RangeCalendar.Grid>
+        </RangeCalendar>
+        <div className="flex flex-col gap-2 text-center">
+          <div className="flex items-center justify-center gap-4 text-xs text-muted">
+            <span className="flex items-center gap-1">
+              <span className="size-2 rounded-full bg-muted" /> Blocked dates
+            </span>
+            <span className="flex items-center gap-1">
+              <span className="size-2 rounded-full bg-default" /> Weekend/Unavailable
+            </span>
+          </div>
+          {selectedRange ? (
+            <Button size="sm" variant="primary">
+              Book {selectedRange.start.toString()} -&gt; {selectedRange.end.toString()}
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/range-calendar/range-calendar.tsx b/packages/react/src/components/range-calendar/range-calendar.tsx
new file mode 100644
index 0000000..e4ecf41
--- /dev/null
+++ b/packages/react/src/components/range-calendar/range-calendar.tsx
@@ -0,0 +1,472 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {RangeCalendarVariants} from "@heroui/styles";
+import type {CalendarIdentifier} from "@internationalized/date";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {DateValue} from "react-aria-components/Calendar";
+
+import {rangeCalendarVariants} from "@heroui/styles";
+import {CalendarDate, DateFormatter, createCalendar} from "@internationalized/date";
+import {useControlledState} from "@react-stately/utils";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {useLocale} from "react-aria-components/I18nProvider";
+import {
+  CalendarCell as CalendarCellPrimitive,
+  CalendarGridBody as CalendarGridBodyPrimitive,
+  CalendarGridHeader as CalendarGridHeaderPrimitive,
+  CalendarGrid as CalendarGridPrimitive,
+  CalendarHeaderCell as CalendarHeaderCellPrimitive,
+  CalendarHeading as CalendarHeadingPrimitive,
+  RangeCalendar as RangeCalendarPrimitive,
+} from "react-aria-components/RangeCalendar";
+import {cx} from "tailwind-variants";
+
+import {dataAttr} from "../../utils/assertion";
+import {getGregorianYearOffset} from "../../utils/calendar";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {CalendarDayViewGridBody} from "../calendar/calendar-day-view-grid-body";
+import {CalendarDayViewGridHeader} from "../calendar/calendar-day-view-grid-header";
+import {YearPickerContext} from "../calendar-year-picker/year-picker-context";
+import {IconChevronLeft, IconChevronRight} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Context
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarDayViewContext {
+  days: number;
+  firstDayOfWeek?: RangeCalendarRootProps["firstDayOfWeek"];
+  timeZone: string;
+  visibleRange: {end: DateValue; start: DateValue};
+  weekdayStyle?: "narrow" | "short" | "long";
+}
+
+interface RangeCalendarContext {
+  dayView?: RangeCalendarDayViewContext;
+  slots?: ReturnType<typeof rangeCalendarVariants>;
+}
+
+const RangeCalendarContext = createContext<RangeCalendarContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Root
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarRootProps<T extends DateValue = DateValue>
+  extends ComponentPropsWithRef<typeof RangeCalendarPrimitive<T>>, RangeCalendarVariants {
+  isYearPickerOpen?: boolean;
+  onYearPickerOpenChange?: (isYearPickerOpen: boolean) => void;
+  defaultYearPickerOpen?: boolean;
+}
+
+function RangeCalendarRoot<T extends DateValue = DateValue>({
+  children,
+  className,
+  defaultYearPickerOpen: defaultYearPickerOpenProp = false,
+  firstDayOfWeek,
+  isYearPickerOpen: isYearPickerOpenProp,
+  maxValue: maxValueProp,
+  minValue: minValueProp,
+  onYearPickerOpenChange: onYearPickerOpenChangeProp,
+  visibleDuration,
+  ...rest
+}: RangeCalendarRootProps<T>) {
+  const isWeekView = visibleDuration?.weeks != null;
+  const isDayView = visibleDuration?.days != null;
+  const visibleDays = visibleDuration?.days;
+  const {locale} = useLocale();
+  const slots = React.useMemo(() => rangeCalendarVariants(), []);
+  const calendarRef = React.useRef<HTMLDivElement>(null);
+  const [isYearPickerOpen, setIsYearPickerOpen] = useControlledState(
+    isYearPickerOpenProp,
+    defaultYearPickerOpenProp,
+    onYearPickerOpenChangeProp,
+  );
+  const calendarProp = React.useMemo(() => {
+    const calendarIdentifier = new DateFormatter(locale).resolvedOptions()
+      .calendar as CalendarIdentifier;
+
+    return createCalendar(calendarIdentifier);
+  }, [locale]);
+  const gregorianYearOffset = React.useMemo(
+    () => getGregorianYearOffset(calendarProp.identifier),
+    [calendarProp.identifier],
+  );
+  const minValue =
+    minValueProp ??
+    (new CalendarDate(calendarProp, 1900 + gregorianYearOffset, 1, 1) as unknown as T);
+  const maxValue =
+    maxValueProp ??
+    (new CalendarDate(calendarProp, 2099 + gregorianYearOffset, 12, 31) as unknown as T);
+
+  return (
+    <YearPickerContext
+      value={{
+        calendarGridSlot: "range-calendar-grid",
+        isYearPickerOpen,
+        setIsYearPickerOpen,
+        calendarRef,
+      }}
+    >
+      <RangeCalendarPrimitive
+        ref={calendarRef}
+        data-slot="range-calendar"
+        firstDayOfWeek={firstDayOfWeek}
+        maxValue={maxValue}
+        minValue={minValue}
+        visibleDuration={visibleDuration}
+        {...rest}
+        className={composeTwRenderProps(
+          className,
+          cx(
+            slots.base(),
+            isWeekView && "range-calendar--week-view",
+            isDayView && "range-calendar--day-view",
+          ),
+        )}
+      >
+        {(values) => (
+          <RangeCalendarContext
+            value={{
+              dayView:
+                isDayView && visibleDays != null
+                  ? {
+                      days: visibleDays,
+                      firstDayOfWeek,
+                      timeZone: values.state.timeZone,
+                      visibleRange: values.state.visibleRange,
+                    }
+                  : undefined,
+              slots,
+            }}
+          >
+            {typeof children === "function" ? children(values) : children}
+          </RangeCalendarContext>
+        )}
+      </RangeCalendarPrimitive>
+    </YearPickerContext>
+  );
+}
+
+RangeCalendarRoot.displayName = "HeroUI.RangeCalendar";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Header
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarHeaderProps<
+  E extends keyof React.JSX.IntrinsicElements = "header",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const RangeCalendarHeader = <E extends keyof React.JSX.IntrinsicElements = "header">({
+  children,
+  className,
+  ...props
+}: RangeCalendarHeaderProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof RangeCalendarHeaderProps<E>>) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <dom.header
+      className={composeSlotClassName(slots?.header, className)}
+      data-slot="range-calendar-header"
+      {...(props as any)}
+    >
+      {children}
+    </dom.header>
+  );
+};
+
+RangeCalendarHeader.displayName = "HeroUI.RangeCalendar.Header";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Heading
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarHeadingProps extends ComponentPropsWithRef<
+  typeof CalendarHeadingPrimitive
+> {}
+
+const RangeCalendarHeading = ({className, ...props}: RangeCalendarHeadingProps) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <CalendarHeadingPrimitive
+      data-slot="range-calendar-heading"
+      {...props}
+      className={composeSlotClassName(slots?.heading, className)}
+    />
+  );
+};
+
+RangeCalendarHeading.displayName = "HeroUI.RangeCalendar.Heading";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Nav Button
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarNavButtonProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {
+  slot?: "previous" | "next";
+}
+
+const RangeCalendarNavButton = ({
+  children,
+  className,
+  slot,
+  ...props
+}: RangeCalendarNavButtonProps) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <ButtonPrimitive
+      data-slot="range-calendar-nav-button"
+      slot={slot}
+      {...props}
+      className={composeTwRenderProps(className, slots?.navButton())}
+    >
+      {children ||
+        (slot === "previous" ? (
+          <IconChevronLeft
+            className={slots?.navButtonIcon()}
+            data-slot="range-calendar-nav-button-icon"
+          />
+        ) : (
+          <IconChevronRight
+            className={slots?.navButtonIcon()}
+            data-slot="range-calendar-nav-button-icon"
+          />
+        ))}
+    </ButtonPrimitive>
+  );
+};
+
+RangeCalendarNavButton.displayName = "HeroUI.RangeCalendar.NavButton";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Grid
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarGridProps extends ComponentPropsWithRef<typeof CalendarGridPrimitive> {}
+
+const RangeCalendarGrid = ({
+  children,
+  className,
+  weekdayStyle = "short",
+  ...props
+}: RangeCalendarGridProps) => {
+  const rangeCalendarContext = use(RangeCalendarContext);
+  const {dayView, slots} = rangeCalendarContext;
+  const contextValue = React.useMemo(
+    () => ({
+      ...rangeCalendarContext,
+      dayView: dayView ? {...dayView, weekdayStyle} : undefined,
+    }),
+    [dayView, rangeCalendarContext, weekdayStyle],
+  );
+
+  return (
+    <RangeCalendarContext value={contextValue}>
+      <CalendarGridPrimitive
+        data-slot="range-calendar-grid"
+        weekdayStyle={weekdayStyle}
+        {...props}
+        className={composeSlotClassName(slots?.grid, className)}
+      >
+        {children}
+      </CalendarGridPrimitive>
+    </RangeCalendarContext>
+  );
+};
+
+RangeCalendarGrid.displayName = "HeroUI.RangeCalendar.Grid";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Grid Header
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarGridHeaderProps extends ComponentPropsWithRef<
+  typeof CalendarGridHeaderPrimitive
+> {}
+
+const RangeCalendarGridHeader = ({children, className, ...props}: RangeCalendarGridHeaderProps) => {
+  const {dayView, slots} = use(RangeCalendarContext);
+
+  if (dayView && dayView.days >= 7 && typeof children === "function") {
+    return (
+      <CalendarDayViewGridHeader
+        className={composeSlotClassName(slots?.gridHeader, className)}
+        data-slot="range-calendar-grid-header"
+        firstDayOfWeek={dayView.firstDayOfWeek}
+        timeZone={dayView.timeZone}
+        visibleRange={dayView.visibleRange}
+        weekdayStyle={dayView.weekdayStyle}
+      >
+        {children}
+      </CalendarDayViewGridHeader>
+    );
+  }
+
+  return (
+    <CalendarGridHeaderPrimitive
+      data-slot="range-calendar-grid-header"
+      {...props}
+      className={composeSlotClassName(slots?.gridHeader, className)}
+    >
+      {children}
+    </CalendarGridHeaderPrimitive>
+  );
+};
+
+RangeCalendarGridHeader.displayName = "HeroUI.RangeCalendar.GridHeader";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Grid Body
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarGridBodyProps extends ComponentPropsWithRef<
+  typeof CalendarGridBodyPrimitive
+> {}
+
+const RangeCalendarGridBody = ({children, className, ...props}: RangeCalendarGridBodyProps) => {
+  const {dayView, slots} = use(RangeCalendarContext);
+
+  if (dayView && dayView.days >= 7 && typeof children === "function") {
+    return (
+      <CalendarDayViewGridBody
+        className={composeSlotClassName(slots?.gridBody, className)}
+        data-slot="range-calendar-grid-body"
+        firstDayOfWeek={dayView.firstDayOfWeek}
+        visibleRange={dayView.visibleRange}
+      >
+        {children}
+      </CalendarDayViewGridBody>
+    );
+  }
+
+  return (
+    <CalendarGridBodyPrimitive
+      data-slot="range-calendar-grid-body"
+      {...props}
+      className={composeSlotClassName(slots?.gridBody, className)}
+    >
+      {children}
+    </CalendarGridBodyPrimitive>
+  );
+};
+
+RangeCalendarGridBody.displayName = "HeroUI.RangeCalendar.GridBody";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Header Cell
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarHeaderCellProps extends ComponentPropsWithRef<
+  typeof CalendarHeaderCellPrimitive
+> {}
+
+const RangeCalendarHeaderCell = ({className, ...props}: RangeCalendarHeaderCellProps) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <CalendarHeaderCellPrimitive
+      data-slot="range-calendar-header-cell"
+      {...props}
+      className={composeSlotClassName(slots?.headerCell, className)}
+    />
+  );
+};
+
+RangeCalendarHeaderCell.displayName = "HeroUI.RangeCalendar.HeaderCell";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Cell
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarCellProps extends ComponentPropsWithRef<typeof CalendarCellPrimitive> {}
+
+const RangeCalendarCell = ({children, className, ...props}: RangeCalendarCellProps) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <CalendarCellPrimitive
+      data-slot="range-calendar-cell"
+      {...props}
+      className={composeTwRenderProps(className, slots?.cell())}
+    >
+      {(values) => {
+        const {formattedDate, isDisabled, isHovered, isPressed, isSelectionEnd, isSelectionStart} =
+          values;
+
+        const content =
+          typeof children === "function" ? children(values) : children || formattedDate;
+
+        return (
+          <span
+            className="range-calendar__cell-button"
+            data-disabled={dataAttr(isDisabled)}
+            data-hovered={dataAttr(isHovered)}
+            data-pressed={dataAttr(isPressed)}
+            data-selected={dataAttr(isSelectionStart || isSelectionEnd)}
+            data-slot="range-calendar-cell-button"
+          >
+            {content}
+          </span>
+        );
+      }}
+    </CalendarCellPrimitive>
+  );
+};
+
+RangeCalendarCell.displayName = "HeroUI.RangeCalendar.Cell";
+
+/* -------------------------------------------------------------------------------------------------
+| * RangeCalendar Cell Indicator
+| * -----------------------------------------------------------------------------------------------*/
+interface RangeCalendarCellIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const RangeCalendarCellIndicator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: RangeCalendarCellIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof RangeCalendarCellIndicatorProps<E>>) => {
+  const {slots} = use(RangeCalendarContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.cellIndicator, className)}
+      data-slot="range-calendar-cell-indicator"
+      {...(props as any)}
+    />
+  );
+};
+
+RangeCalendarCellIndicator.displayName = "HeroUI.RangeCalendar.CellIndicator";
+
+/* -------------------------------------------------------------------------------------------------
+| * Exports
+| * -----------------------------------------------------------------------------------------------*/
+export {
+  RangeCalendarRoot,
+  RangeCalendarHeader,
+  RangeCalendarHeading,
+  RangeCalendarNavButton,
+  RangeCalendarGrid,
+  RangeCalendarGridHeader,
+  RangeCalendarGridBody,
+  RangeCalendarHeaderCell,
+  RangeCalendarCell,
+  RangeCalendarCellIndicator,
+};
+export type {
+  RangeCalendarRootProps,
+  RangeCalendarHeaderProps,
+  RangeCalendarHeadingProps,
+  RangeCalendarNavButtonProps,
+  RangeCalendarGridProps,
+  RangeCalendarGridHeaderProps,
+  RangeCalendarGridBodyProps,
+  RangeCalendarHeaderCellProps,
+  RangeCalendarCellProps,
+  RangeCalendarCellIndicatorProps,
+};
diff --git a/packages/react/src/components/scroll-shadow/index.ts b/packages/react/src/components/scroll-shadow/index.ts
new file mode 100644
index 0000000..a98eed4
--- /dev/null
+++ b/packages/react/src/components/scroll-shadow/index.ts
@@ -0,0 +1,40 @@
+import type {ComponentProps} from "react";
+
+import {ScrollShadowRoot} from "./scroll-shadow";
+
+/* -------------------------------------------------------------------------------------------------
+ * Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ScrollShadow = Object.assign(ScrollShadowRoot, {
+  Root: ScrollShadowRoot,
+});
+
+export type ScrollShadow = {
+  Props: ComponentProps<typeof ScrollShadowRoot>;
+  RootProps: ComponentProps<typeof ScrollShadowRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ScrollShadowRoot};
+
+export type {
+  ScrollShadowRootProps,
+  ScrollShadowRootProps as ScrollShadowProps,
+  ScrollShadowVisibility,
+} from "./scroll-shadow";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {scrollShadowVariants} from "@heroui/styles";
+
+export type {ScrollShadowVariants} from "@heroui/styles";
+
+/* -------------------------------------------------------------------------------------------------
+ * Hooks
+ * -----------------------------------------------------------------------------------------------*/
+export {useScrollShadow} from "./use-scroll-shadow";
+
+export type {UseScrollShadowProps} from "./use-scroll-shadow";
diff --git a/packages/react/src/components/scroll-shadow/scroll-shadow.stories.tsx b/packages/react/src/components/scroll-shadow/scroll-shadow.stories.tsx
new file mode 100644
index 0000000..83281cd
--- /dev/null
+++ b/packages/react/src/components/scroll-shadow/scroll-shadow.stories.tsx
@@ -0,0 +1,234 @@
+import type {ScrollShadowVisibility} from ".";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {Card} from "../card";
+
+import {ScrollShadow} from ".";
+
+const meta: Meta<typeof ScrollShadow> = {
+  title: "Components/Utilities/ScrollShadow",
+  component: ScrollShadow,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ScrollShadow>;
+
+const LoremContent = () => (
+  <div className="space-y-4">
+    {Array.from({length: 10}).map((_, idx) => (
+      <p key={`scroll-shadow-lorem-content-${idx}`}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus
+        hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi
+        accumsan cursus enim, sed ultricies sapien.
+      </p>
+    ))}
+  </div>
+);
+
+const LoremCards = () => {
+  const images = [
+    "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
+    "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
+    "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
+  ];
+
+  const getRandomImage = (idx: number) => {
+    return images[idx % images.length];
+  };
+
+  return (
+    <div className="flex flex-row gap-4">
+      {Array.from({length: 10}).map((_, idx) => (
+        <Card
+          key={`scroll-shadow-lorem-cards-${idx}`}
+          className="flex min-w-[200px] flex-row gap-3 p-1"
+          variant="transparent"
+        >
+          <img
+            alt="Lorem Card"
+            className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+            loading="lazy"
+            src={getRandomImage(idx)}
+          />
+          <div className="flex flex-1 flex-col justify-center gap-1">
+            <Card.Title className="text-sm">Bridging the Future</Card.Title>
+            <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
+          </div>
+        </Card>
+      ))}
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow className="max-h-[240px] p-4" {...args}>
+        <LoremContent />
+      </ScrollShadow>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Fade (Opacity Effect)</h4>
+        <div className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[240px] p-4" {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </div>
+      </div>
+
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Blur (Blur Effect)</h4>
+        <div className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[240px] p-4" {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const Orientation: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Vertical</h4>
+        <Card className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[240px] p-4" orientation="vertical" {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </Card>
+      </div>
+
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Horizontal</h4>
+        <Card className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="p-4" orientation="horizontal" {...args}>
+            <LoremCards />
+          </ScrollShadow>
+        </Card>
+      </div>
+    </div>
+  ),
+};
+
+export const HideScrollBar: Story = {
+  render: (args) => (
+    <div className="w-full p-0 sm:max-w-sm">
+      <ScrollShadow hideScrollBar className="max-h-[240px] p-4" {...args}>
+        <LoremContent />
+      </ScrollShadow>
+    </div>
+  ),
+};
+
+export const CustomSize: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Small Shadow (20px)</h4>
+        <div className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[200px] p-4" size={20} {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </div>
+      </div>
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Default Shadow (40px)</h4>
+        <div className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[200px] p-4" {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </div>
+      </div>
+      <div>
+        <h4 className="mb-2 text-sm font-semibold">Large Shadow (80px)</h4>
+        <div className="w-full p-0 sm:max-w-sm">
+          <ScrollShadow className="max-h-[200px] p-4" size={80} {...args}>
+            <LoremContent />
+          </ScrollShadow>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const VisibilityChange: Story = {
+  render: (args) => {
+    const [verticalState, setVerticalState] = useState<ScrollShadowVisibility>("none");
+    const [horizontalState, setHorizontalState] = useState<ScrollShadowVisibility>("none");
+
+    return (
+      <>
+        <div className="mb-4 flex flex-col gap-4">
+          <div className="rounded bg-default p-4">
+            <p className="text-sm font-semibold">Vertical Shadow State: {verticalState}</p>
+          </div>
+          <div className="w-full p-0 sm:max-w-sm">
+            <ScrollShadow
+              className="max-h-[240px] p-4"
+              orientation="vertical"
+              onVisibilityChange={(visibility) => setVerticalState(visibility)}
+              {...args}
+            >
+              <LoremContent />
+            </ScrollShadow>
+          </div>
+        </div>
+
+        <div className="flex flex-col gap-4">
+          <div className="rounded bg-default p-4">
+            <p className="text-sm font-semibold">Horizontal Shadow State: {horizontalState}</p>
+          </div>
+          <div className="w-full p-0 sm:max-w-sm">
+            <ScrollShadow
+              className="p-4"
+              orientation="horizontal"
+              onVisibilityChange={(visibility) => setHorizontalState(visibility)}
+              {...args}
+            >
+              <LoremCards />
+            </ScrollShadow>
+          </div>
+        </div>
+      </>
+    );
+  },
+};
+
+export const WithCard: Story = {
+  render: (args) => (
+    <Card className="max-w-[400px]">
+      <Card.Header>
+        <Card.Title>Terms and Conditions</Card.Title>
+        <Card.Description>Please review before proceeding</Card.Description>
+      </Card.Header>
+      <Card.Content className="p-0">
+        <ScrollShadow className="h-[300px] px-4" size={80} {...args}>
+          <LoremContent />
+        </ScrollShadow>
+      </Card.Content>
+      <Card.Footer className="mt-4 flex flex-row gap-2">
+        <Button className="w-full" variant="secondary">
+          Cancel
+        </Button>
+        <Button className="w-full">Accept</Button>
+      </Card.Footer>
+    </Card>
+  ),
+};
diff --git a/packages/react/src/components/scroll-shadow/scroll-shadow.tsx b/packages/react/src/components/scroll-shadow/scroll-shadow.tsx
new file mode 100644
index 0000000..c4e059c
--- /dev/null
+++ b/packages/react/src/components/scroll-shadow/scroll-shadow.tsx
@@ -0,0 +1,125 @@
+"use client";
+
+import type {ScrollShadowVariants} from "@heroui/styles";
+import type {RefObject} from "react";
+
+import {scrollShadowVariants} from "@heroui/styles";
+import {mergeRefs} from "@react-aria/utils";
+import {useMemo, useRef} from "react";
+
+import {useSafeLayoutEffect} from "../../hooks/use-safe-layout-effect";
+
+import {useScrollShadow} from "./use-scroll-shadow";
+
+export type ScrollShadowVisibility = "auto" | "both" | "top" | "bottom" | "left" | "right" | "none";
+
+export interface ScrollShadowRootProps
+  extends Omit<React.ComponentProps<"div">, "size">, ScrollShadowVariants {
+  /**
+   * The shadow size in pixels
+   * @default 40
+   */
+  size?: number;
+
+  /**
+   * The scroll offset before showing shadows (in pixels)
+   * @default 0
+   */
+  offset?: number;
+
+  /**
+   * Controlled shadow visibility state
+   * @default "auto"
+   */
+  visibility?: ScrollShadowVisibility;
+
+  /**
+   * Whether scroll shadow detection is enabled
+   * @default true
+   */
+  isEnabled?: boolean;
+
+  /**
+   * Callback invoked when shadow visibility changes
+   */
+  onVisibilityChange?: (visibility: ScrollShadowVisibility) => void;
+}
+
+export const ScrollShadowRoot = ({
+  children,
+  className,
+  hideScrollBar = false,
+  isEnabled = true,
+  offset = 0,
+  onVisibilityChange,
+  orientation = "vertical",
+  ref,
+  size = 40,
+  variant = "fade",
+  visibility = "auto",
+  ...props
+}: ScrollShadowRootProps) => {
+  const internalRef = useRef<HTMLDivElement | null>(null);
+
+  useScrollShadow({
+    containerRef: internalRef as RefObject<HTMLElement>,
+    isEnabled,
+    offset,
+    onVisibilityChange,
+    orientation,
+    visibility,
+  });
+
+  // Handle controlled visibility mode
+  useSafeLayoutEffect(() => {
+    const el = internalRef.current;
+
+    if (!el || visibility === "auto") return;
+
+    // Clear all data attributes
+    delete el.dataset["topScroll"];
+    delete el.dataset["bottomScroll"];
+    delete el.dataset["topBottomScroll"];
+    delete el.dataset["leftScroll"];
+    delete el.dataset["rightScroll"];
+    delete el.dataset["leftRightScroll"];
+
+    // Set controlled visibility
+    if (visibility === "both") {
+      el.dataset[orientation === "vertical" ? "topBottomScroll" : "leftRightScroll"] = "true";
+    } else if (visibility !== "none") {
+      el.dataset[`${visibility}Scroll`] = "true";
+    }
+  }, [visibility, orientation]);
+
+  const slots = useMemo(
+    () =>
+      scrollShadowVariants({
+        hideScrollBar,
+        orientation,
+        variant,
+      }),
+    [orientation, hideScrollBar, variant],
+  );
+
+  const style = {
+    "--scroll-shadow-size": `${size}px`,
+    ...props.style,
+  } as React.CSSProperties;
+
+  return (
+    <div
+      ref={mergeRefs(internalRef, ref)}
+      className={slots.base({className})}
+      data-orientation={orientation}
+      data-scroll-shadow-size={size}
+      data-slot="scroll-shadow"
+      style={style}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+ScrollShadowRoot.displayName = "HeroUI.ScrollShadow";
diff --git a/packages/react/src/components/scroll-shadow/use-scroll-shadow.ts b/packages/react/src/components/scroll-shadow/use-scroll-shadow.ts
new file mode 100644
index 0000000..1223a9b
--- /dev/null
+++ b/packages/react/src/components/scroll-shadow/use-scroll-shadow.ts
@@ -0,0 +1,141 @@
+"use client";
+
+import type {ScrollShadowVisibility} from "./scroll-shadow";
+import type {RefObject} from "react";
+
+import {useCallback, useEffect, useRef} from "react";
+
+export interface UseScrollShadowProps {
+  containerRef: RefObject<HTMLElement>;
+  orientation: "vertical" | "horizontal";
+  offset: number;
+  visibility: ScrollShadowVisibility;
+  isEnabled: boolean;
+  onVisibilityChange?: (visibility: ScrollShadowVisibility) => void;
+}
+
+export const useScrollShadow = (props: UseScrollShadowProps) => {
+  const {containerRef, isEnabled, offset, onVisibilityChange, orientation, visibility} = props;
+
+  // Cache previous state to avoid unnecessary DOM updates
+  const prevStateRef = useRef<{
+    hasScrollBefore: boolean;
+    hasScrollAfter: boolean;
+  } | null>(null);
+
+  // Track pending RAF to avoid multiple scheduled updates
+  const rafIdRef = useRef<number | null>(null);
+
+  const checkOverflow = useCallback(() => {
+    const el = containerRef.current;
+
+    if (!el) return;
+
+    const isVertical = orientation === "vertical";
+    const scrollStart = isVertical ? el.scrollTop : el.scrollLeft;
+    const scrollSize = isVertical ? el.scrollHeight : el.scrollWidth;
+    const clientSize = isVertical ? el.clientHeight : el.clientWidth;
+
+    const hasScrollBefore = scrollStart > offset;
+    const hasScrollAfter = scrollStart + clientSize + offset < scrollSize;
+
+    // Skip DOM updates if state hasn't changed
+    const prevState = prevStateRef.current;
+
+    if (
+      prevState &&
+      prevState.hasScrollBefore === hasScrollBefore &&
+      prevState.hasScrollAfter === hasScrollAfter
+    ) {
+      return;
+    }
+
+    // Update state cache
+    prevStateRef.current = {hasScrollBefore, hasScrollAfter};
+
+    // Cancel previous pending update
+    if (rafIdRef.current !== null) {
+      cancelAnimationFrame(rafIdRef.current);
+    }
+
+    // Batch DOM updates with RAF for better performance
+    rafIdRef.current = requestAnimationFrame(() => {
+      rafIdRef.current = null;
+
+      if (isVertical) {
+        if (hasScrollBefore && hasScrollAfter) {
+          el.dataset["topBottomScroll"] = "true";
+          delete el.dataset["topScroll"];
+          delete el.dataset["bottomScroll"];
+
+          onVisibilityChange?.("both");
+        } else {
+          el.dataset["topScroll"] = String(hasScrollBefore);
+          el.dataset["bottomScroll"] = String(hasScrollAfter);
+          delete el.dataset["topBottomScroll"];
+
+          if (onVisibilityChange) {
+            if (hasScrollBefore) {
+              onVisibilityChange("top");
+            } else if (hasScrollAfter) {
+              onVisibilityChange("bottom");
+            } else {
+              onVisibilityChange("none");
+            }
+          }
+        }
+      } else {
+        if (hasScrollBefore && hasScrollAfter) {
+          el.dataset["leftRightScroll"] = "true";
+          delete el.dataset["leftScroll"];
+          delete el.dataset["rightScroll"];
+
+          onVisibilityChange?.("both");
+        } else {
+          el.dataset["leftScroll"] = String(hasScrollBefore);
+          el.dataset["rightScroll"] = String(hasScrollAfter);
+          delete el.dataset["leftRightScroll"];
+
+          if (onVisibilityChange) {
+            if (hasScrollBefore) {
+              onVisibilityChange("left");
+            } else if (hasScrollAfter) {
+              onVisibilityChange("right");
+            } else {
+              onVisibilityChange("none");
+            }
+          }
+        }
+      }
+    });
+  }, [containerRef, orientation, offset, onVisibilityChange]);
+
+  useEffect(() => {
+    const el = containerRef.current;
+
+    if (!el || !isEnabled || visibility !== "auto") return;
+
+    // Initial check
+    checkOverflow();
+
+    // Use passive listener for better scroll performance
+    el.addEventListener("scroll", checkOverflow, {passive: true});
+
+    // Monitor size changes
+    const resizeObserver = new ResizeObserver(checkOverflow);
+
+    resizeObserver.observe(el);
+
+    return () => {
+      el.removeEventListener("scroll", checkOverflow);
+      resizeObserver.disconnect();
+
+      // Cancel pending RAF and cleanup cache
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+      }
+      prevStateRef.current = null;
+    };
+  }, [containerRef, visibility, isEnabled, checkOverflow]);
+};
diff --git a/packages/react/src/components/search-field/index.ts b/packages/react/src/components/search-field/index.ts
new file mode 100644
index 0000000..d650891
--- /dev/null
+++ b/packages/react/src/components/search-field/index.ts
@@ -0,0 +1,56 @@
+import type {ComponentProps} from "react";
+
+import {
+  SearchFieldClearButton,
+  SearchFieldGroup,
+  SearchFieldInput,
+  SearchFieldRoot,
+  SearchFieldSearchIcon,
+} from "./search-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const SearchField = Object.assign(SearchFieldRoot, {
+  Root: SearchFieldRoot,
+  Group: SearchFieldGroup,
+  Input: SearchFieldInput,
+  SearchIcon: SearchFieldSearchIcon,
+  ClearButton: SearchFieldClearButton,
+});
+
+export type SearchField = {
+  Props: ComponentProps<typeof SearchFieldRoot>;
+  RootProps: ComponentProps<typeof SearchFieldRoot>;
+  GroupProps: ComponentProps<typeof SearchFieldGroup>;
+  InputProps: ComponentProps<typeof SearchFieldInput>;
+  SearchIconProps: ComponentProps<typeof SearchFieldSearchIcon>;
+  ClearButtonProps: ComponentProps<typeof SearchFieldClearButton>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  SearchFieldClearButton,
+  SearchFieldGroup,
+  SearchFieldInput,
+  SearchFieldRoot,
+  SearchFieldSearchIcon,
+};
+
+export type {
+  SearchFieldRootProps,
+  SearchFieldRootProps as SearchFieldProps,
+  SearchFieldGroupProps,
+  SearchFieldInputProps,
+  SearchFieldSearchIconProps,
+  SearchFieldClearButtonProps,
+} from "./search-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {searchFieldVariants} from "@heroui/styles";
+
+export type {SearchFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/search-field/search-field.stories.tsx b/packages/react/src/components/search-field/search-field.stories.tsx
new file mode 100644
index 0000000..7b9fb31
--- /dev/null
+++ b/packages/react/src/components/search-field/search-field.stories.tsx
@@ -0,0 +1,388 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Kbd} from "../kbd";
+import {Label} from "../label";
+import {Spinner} from "../spinner";
+
+import {SearchField} from "./index";
+
+const meta: Meta<typeof SearchField> = {
+  component: SearchField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Forms/SearchField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <SearchField name="search">
+      <Label>Search</Label>
+      <SearchField.Group>
+        <SearchField.SearchIcon />
+        <SearchField.Input className="w-[280px]" placeholder="Search..." />
+        <SearchField.ClearButton />
+      </SearchField.Group>
+    </SearchField>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField name="primary-search" variant="primary">
+        <Label>Primary variant</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField name="secondary-search" variant="secondary">
+        <Label>Secondary variant</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <SearchField fullWidth name="search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search">
+        <Label>Search products</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search products..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Enter keywords to search for products</Description>
+      </SearchField>
+      <SearchField name="search-users">
+        <Label>Search users</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search users..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Search by name, email, or username</Description>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField isRequired name="search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+      </SearchField>
+      <SearchField isRequired name="search-query">
+        <Label>Search query</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Enter search query..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Minimum 3 characters required</Description>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField isInvalid isRequired name="search" value="ab">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>Search query must be at least 3 characters</FieldError>
+      </SearchField>
+      <SearchField isInvalid name="search-invalid">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." value="invalid@query" />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <FieldError>Invalid characters in search query</FieldError>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField isDisabled name="search" value="Disabled search">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>This search field is disabled</Description>
+      </SearchField>
+      <SearchField isDisabled name="search-empty">
+        <Label>Search</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>This search field is disabled</Description>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState("");
+
+    return (
+      <div className="flex flex-col gap-4">
+        <SearchField name="search" value={value} onChange={setValue}>
+          <Label>Search</Label>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input className="w-[280px]" placeholder="Search..." />
+            <SearchField.ClearButton />
+          </SearchField.Group>
+          <Description>Current value: {value || "(empty)"}</Description>
+        </SearchField>
+        <div className="flex gap-2">
+          <Button variant="tertiary" onPress={() => setValue("")}>
+            Clear
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue("example query")}>
+            Set example
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = React.useState("");
+    const isInvalid = value.length > 0 && value.length < 3;
+
+    return (
+      <div className="flex flex-col gap-4">
+        <SearchField
+          isRequired
+          isInvalid={isInvalid}
+          name="search"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Search</Label>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input className="w-[280px]" placeholder="Search..." />
+            <SearchField.ClearButton />
+          </SearchField.Group>
+          {isInvalid ? (
+            <FieldError>Search query must be at least 3 characters</FieldError>
+          ) : (
+            <Description>Enter at least 3 characters to search</Description>
+          )}
+        </SearchField>
+      </div>
+    );
+  },
+};
+
+export const CustomIcons: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <SearchField name="search-custom">
+        <Label>Search (Custom Icons)</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.SearchIcon>
+          <SearchField.Input className="w-[280px]" placeholder="Search..." />
+          <SearchField.ClearButton>
+            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
+              <path
+                clipRule="evenodd"
+                d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z"
+                fill="currentColor"
+                fillRule="evenodd"
+              />
+            </svg>
+          </SearchField.ClearButton>
+        </SearchField.Group>
+        <Description>Custom icon children</Description>
+      </SearchField>
+    </div>
+  ),
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = React.useState("");
+    const [isSubmitting, setIsSubmitting] = React.useState(false);
+    const MIN_LENGTH = 3;
+    const isInvalid = value.length > 0 && value.length < MIN_LENGTH;
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+
+      if (value.length < MIN_LENGTH) {
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        // eslint-disable-next-line no-console
+        console.log("Search submitted:", {query: value});
+        setValue("");
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <SearchField
+          isRequired
+          isInvalid={isInvalid}
+          name="search"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Search products</Label>
+          <SearchField.Group>
+            <SearchField.SearchIcon />
+            <SearchField.Input className="w-full" placeholder="Search products..." />
+            <SearchField.ClearButton />
+          </SearchField.Group>
+          {isInvalid ? (
+            <FieldError>Search query must be at least {MIN_LENGTH} characters</FieldError>
+          ) : (
+            <Description>Enter at least {MIN_LENGTH} characters to search</Description>
+          )}
+        </SearchField>
+        <Button
+          className="w-full"
+          isDisabled={value.length < MIN_LENGTH}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? (
+            <>
+              <Spinner color="current" size="sm" />
+              Searching...
+            </>
+          ) : (
+            "Search"
+          )}
+        </Button>
+      </Form>
+    );
+  },
+};
+
+export const WithKeyboardShortcut: Story = {
+  render: () => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const [value, setValue] = React.useState("");
+
+    React.useEffect(() => {
+      const handleKeyDown = (e: KeyboardEvent) => {
+        // Check for CMD+K (Meta+K) or CTRL+K
+        if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+          e.preventDefault();
+          inputRef.current?.focus();
+        }
+        // Check for ESC key to blur the input
+        if (e.key === "Escape" && document.activeElement === inputRef.current) {
+          inputRef.current?.blur();
+        }
+      };
+
+      // Add global event listener
+      window.addEventListener("keydown", handleKeyDown);
+
+      // Cleanup on unmount
+      return () => {
+        window.removeEventListener("keydown", handleKeyDown);
+      };
+    }, []);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <div>
+          <SearchField name="search" value={value} onChange={setValue}>
+            <Label>Search</Label>
+            <SearchField.Group>
+              <SearchField.SearchIcon />
+              <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="Search..." />
+              <SearchField.ClearButton />
+            </SearchField.Group>
+            <Description>Use keyboard shortcut to quickly focus this field</Description>
+          </SearchField>
+        </div>
+        <div className="text-default-500 flex items-center gap-2 text-sm">
+          <span>Press</span>
+          <Kbd>
+            <Kbd.Abbr keyValue="command" />
+            <Kbd.Content>K</Kbd.Content>
+          </Kbd>
+          <span>to focus the search field</span>
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/search-field/search-field.tsx b/packages/react/src/components/search-field/search-field.tsx
new file mode 100644
index 0000000..a54e8ce
--- /dev/null
+++ b/packages/react/src/components/search-field/search-field.tsx
@@ -0,0 +1,169 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SearchFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {searchFieldVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Group as GroupPrimitive} from "react-aria-components/Group";
+import {Input as InputPrimitive} from "react-aria-components/Input";
+import {SearchField as SearchFieldPrimitive} from "react-aria-components/SearchField";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {CloseButton} from "../close-button";
+import {IconSearch} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Context
+ * -----------------------------------------------------------------------------------------------*/
+type SearchFieldContext = {
+  slots?: ReturnType<typeof searchFieldVariants>;
+};
+
+const SearchFieldContext = createContext<SearchFieldContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SearchFieldRootProps
+  extends ComponentPropsWithRef<typeof SearchFieldPrimitive>, SearchFieldVariants {}
+
+const SearchFieldRoot = ({
+  children,
+  className,
+  fullWidth,
+  variant,
+  ...props
+}: SearchFieldRootProps) => {
+  const slots = React.useMemo(
+    () => searchFieldVariants({fullWidth, variant}),
+    [fullWidth, variant],
+  );
+
+  return (
+    <SearchFieldContext value={{slots}}>
+      <SearchFieldPrimitive
+        data-slot="search-field"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </SearchFieldPrimitive>
+    </SearchFieldContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Group
+ * -----------------------------------------------------------------------------------------------*/
+interface SearchFieldGroupProps extends ComponentPropsWithRef<typeof GroupPrimitive> {}
+
+const SearchFieldGroup = ({children, className, ...props}: SearchFieldGroupProps) => {
+  const {slots} = use(SearchFieldContext);
+
+  return (
+    <GroupPrimitive
+      className={composeTwRenderProps(className, slots?.group())}
+      data-slot="search-field-group"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </GroupPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Input
+ * -----------------------------------------------------------------------------------------------*/
+interface SearchFieldInputProps extends ComponentPropsWithRef<typeof InputPrimitive> {}
+
+const SearchFieldInput = ({className, ...props}: SearchFieldInputProps) => {
+  const {slots} = use(SearchFieldContext);
+
+  return (
+    <InputPrimitive
+      className={composeTwRenderProps(className, slots?.input())}
+      data-slot="search-field-input"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Search Icon
+ * -----------------------------------------------------------------------------------------------*/
+interface SearchFieldSearchIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+const SearchFieldSearchIcon = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: SearchFieldSearchIconProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof SearchFieldSearchIconProps<E>>) => {
+  const {slots} = use(SearchFieldContext);
+
+  if (children && React.isValidElement(children)) {
+    return React.cloneElement(
+      children as React.ReactElement<{
+        className?: string;
+        "data-slot"?: string;
+      }>,
+      {
+        ...(props as any),
+        className: composeSlotClassName(slots?.searchIcon, className),
+        "data-slot": "search-field-search-icon",
+      },
+    );
+  }
+
+  return (
+    <IconSearch
+      className={composeSlotClassName(slots?.searchIcon, className)}
+      data-slot="search-field-search-icon"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * SearchField Clear Button
+ * -----------------------------------------------------------------------------------------------*/
+interface SearchFieldClearButtonProps extends ComponentPropsWithRef<typeof CloseButton> {}
+
+const SearchFieldClearButton = ({className, ...props}: SearchFieldClearButtonProps) => {
+  const {slots} = use(SearchFieldContext);
+
+  return (
+    <CloseButton
+      className={composeTwRenderProps(className, slots?.clearButton())}
+      data-slot="search-field-clear-button"
+      slot="clear"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  SearchFieldRoot,
+  SearchFieldGroup,
+  SearchFieldInput,
+  SearchFieldSearchIcon,
+  SearchFieldClearButton,
+};
+
+export type {
+  SearchFieldRootProps,
+  SearchFieldGroupProps,
+  SearchFieldInputProps,
+  SearchFieldSearchIconProps,
+  SearchFieldClearButtonProps,
+};
diff --git a/packages/react/src/components/select/index.ts b/packages/react/src/components/select/index.ts
new file mode 100644
index 0000000..1db854c
--- /dev/null
+++ b/packages/react/src/components/select/index.ts
@@ -0,0 +1,44 @@
+import type {ComponentProps} from "react";
+
+import {SelectIndicator, SelectPopover, SelectRoot, SelectTrigger, SelectValue} from "./select";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Select = Object.assign(SelectRoot, {
+  Root: SelectRoot,
+  Trigger: SelectTrigger,
+  Value: SelectValue,
+  Indicator: SelectIndicator,
+  Popover: SelectPopover,
+});
+
+export type Select<T extends object = object> = {
+  Props: ComponentProps<typeof SelectRoot<T>>;
+  RootProps: ComponentProps<typeof SelectRoot<T>>;
+  TriggerProps: ComponentProps<typeof SelectTrigger>;
+  ValueProps: ComponentProps<typeof SelectValue>;
+  IndicatorProps: ComponentProps<typeof SelectIndicator>;
+  PopoverProps: ComponentProps<typeof SelectPopover>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SelectIndicator, SelectPopover, SelectRoot, SelectTrigger, SelectValue};
+
+export type {
+  SelectRootProps,
+  SelectRootProps as SelectProps,
+  SelectTriggerProps,
+  SelectValueProps,
+  SelectIndicatorProps,
+  SelectPopoverProps,
+} from "./select";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {selectVariants} from "@heroui/styles";
+
+export type {SelectVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/select/select.stories.tsx b/packages/react/src/components/select/select.stories.tsx
new file mode 100644
index 0000000..7a5615f
--- /dev/null
+++ b/packages/react/src/components/select/select.stories.tsx
@@ -0,0 +1,995 @@
+import type {Key} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {useAsyncList} from "@react-stately/data";
+import React from "react";
+
+import {Avatar, AvatarFallback, AvatarImage} from "../avatar";
+import {Button} from "../button";
+import {Chip} from "../chip";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Header} from "../header";
+import {Label} from "../label";
+import {ListBox} from "../list-box";
+import {Collection, ListBoxLoadMoreItem} from "../rac";
+import {Separator} from "../separator";
+import {Spinner} from "../spinner";
+
+import {Select} from "./index";
+
+const meta: Meta<typeof Select> = {
+  component: Select,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Pickers/Select",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Select className="w-[256px]" placeholder="Select one" variant="primary">
+        <Label>Primary variant</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="Option 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="Option 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select className="w-[256px]" placeholder="Select one" variant="secondary">
+        <Label>Secondary variant</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="option1" textValue="Option 1">
+              Option 1
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="option2" textValue="Option 2">
+              Option 2
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <Select fullWidth placeholder="Select one">
+        <Label>State</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="Delaware">
+              Delaware
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+      <Description>Select your state of residence</Description>
+    </Select>
+  ),
+};
+
+export const MultipleSelect: Story = {
+  render: () => (
+    <Select className="w-[256px]" placeholder="Select countries" selectionMode="multiple">
+      <Label>Countries to Visit</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox selectionMode="multiple">
+          <ListBox.Item id="argentina" textValue="Argentina">
+            Argentina
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="venezuela" textValue="Venezuela">
+            Venezuela
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="japan" textValue="Japan">
+            Japan
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="france" textValue="France">
+            France
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="italy" textValue="Italy">
+            Italy
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="spain" textValue="Spain">
+            Spain
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="thailand" textValue="Thailand">
+            Thailand
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-zealand" textValue="New Zealand">
+            New Zealand
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="iceland" textValue="Iceland">
+            Iceland
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  ),
+};
+
+export const WithSections: Story = {
+  render: () => (
+    <Select className="w-[256px]" placeholder="Select a country">
+      <Label>Country</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Section>
+            <Header>North America</Header>
+            <ListBox.Item id="usa" textValue="United States">
+              United States
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="canada" textValue="Canada">
+              Canada
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="mexico" textValue="Mexico">
+              Mexico
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Europe</Header>
+            <ListBox.Item id="uk" textValue="United Kingdom">
+              United Kingdom
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="germany" textValue="Germany">
+              Germany
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+          <Separator />
+          <ListBox.Section>
+            <Header>Asia</Header>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="china" textValue="China">
+              China
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="india" textValue="India">
+              India
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="south-korea" textValue="South Korea">
+              South Korea
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  ),
+};
+
+export const WithDisabledOptions: Story = {
+  render: () => (
+    <Select className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="Select an animal">
+      <Label>Animal</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="dog" textValue="Dog">
+            Dog
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="cat" textValue="Cat">
+            Cat
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="bird" textValue="Bird">
+            Bird
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="kangaroo" textValue="Kangaroo">
+            Kangaroo
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="elephant" textValue="Elephant">
+            Elephant
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="tiger" textValue="Tiger">
+            Tiger
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  ),
+};
+
+export const CustomIndicator: Story = {
+  render: () => (
+    <Select className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator className="size-3">
+          <Icon icon="gravity-ui:chevrons-expand-vertical" />
+        </Select.Indicator>
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  ),
+};
+
+export const Required: Story = {
+  render: () => {
+    const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const data: Record<string, string> = {};
+
+      // Convert FormData to plain object
+      formData.forEach((value, key) => {
+        data[key] = value.toString();
+      });
+
+      alert("Form submitted successfully!");
+    };
+
+    return (
+      <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}>
+        <Select isRequired className="w-full" name="state" placeholder="Select one">
+          <Label>State</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="florida" textValue="Florida">
+                Florida
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="delaware" textValue="Delaware">
+                Delaware
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="california" textValue="California">
+                California
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="texas" textValue="Texas">
+                Texas
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="new-york" textValue="New York">
+                New York
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="washington" textValue="Washington">
+                Washington
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Select isRequired className="w-full" name="country" placeholder="Select a country">
+          <Label>Country</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="usa" textValue="United States">
+                United States
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="Canada">
+                Canada
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="mexico" textValue="Mexico">
+                Mexico
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="uk" textValue="United Kingdom">
+                United Kingdom
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="france" textValue="France">
+                France
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="Germany">
+                Germany
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+          <FieldError />
+        </Select>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+export const CustomValue: Story = {
+  render: () => {
+    const users = [
+      {
+        id: "1",
+        name: "Bob",
+        email: "bob@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "B",
+      },
+      {
+        id: "2",
+        name: "Fred",
+        email: "fred@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "F",
+      },
+      {
+        id: "3",
+        name: "Martha",
+        email: "martha@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "M",
+      },
+      {
+        id: "4",
+        name: "John",
+        email: "john@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "J",
+      },
+      {
+        id: "5",
+        name: "Jane",
+        email: "jane@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "J",
+      },
+    ];
+
+    return (
+      <Select className="w-[256px]" placeholder="Select a user">
+        <Label>User</Label>
+        <Select.Trigger>
+          <Select.Value>
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItems = state.selectedItems;
+
+              if (selectedItems.length > 1) {
+                return `${selectedItems.length} users selected`;
+              }
+
+              const selectedItem = users.find((user) => user.id === selectedItems[0].key);
+
+              if (!selectedItem) {
+                return defaultChildren;
+              }
+
+              return (
+                <div className="flex items-center gap-2">
+                  <Avatar className="size-4" size="sm">
+                    <AvatarImage src={selectedItem.avatarUrl} />
+                    <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                  </Avatar>
+                  <span>{selectedItem.name}</span>
+                </div>
+              );
+            }}
+          </Select.Value>
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    );
+  },
+};
+
+export const CustomValueMultiple: Story = {
+  render: () => {
+    const users = [
+      {
+        id: "1",
+        name: "Bob",
+        email: "bob@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+        fallback: "B",
+      },
+      {
+        id: "2",
+        name: "Fred",
+        email: "fred@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+        fallback: "F",
+      },
+      {
+        id: "3",
+        name: "Martha",
+        email: "martha@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+        fallback: "M",
+      },
+      {
+        id: "4",
+        name: "John",
+        email: "john@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+        fallback: "J",
+      },
+      {
+        id: "5",
+        name: "Jane",
+        email: "jane@heroui.com",
+        avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+        fallback: "J",
+      },
+    ];
+
+    return (
+      <Select
+        className="w-[256px]"
+        defaultValue={["1", "2"]}
+        placeholder="Select your teammates"
+        selectionMode="multiple"
+      >
+        <Label>Users</Label>
+        <Select.Trigger>
+          <Select.Value className="no-truncate flex flex-wrap gap-2">
+            {({defaultChildren, isPlaceholder, state}) => {
+              if (isPlaceholder || state.selectedItems.length === 0) {
+                return defaultChildren;
+              }
+
+              const selectedItemsKeys = state.selectedItems.map((item) => item.key);
+
+              return selectedItemsKeys.map((selectedItemKey) => {
+                const selectedItem = users.find((user) => user.id === selectedItemKey);
+
+                if (!selectedItem) {
+                  return null;
+                }
+
+                return (
+                  <Chip key={selectedItemKey} variant="soft">
+                    <Avatar className="size-4" size="sm">
+                      <AvatarImage src={selectedItem.avatarUrl} />
+                      <AvatarFallback>{selectedItem.fallback}</AvatarFallback>
+                    </Avatar>
+                    <Chip.Label>{selectedItem.name}</Chip.Label>
+                  </Chip>
+                );
+              });
+            }}
+          </Select.Value>
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            {users.map((user) => (
+              <ListBox.Item key={user.id} id={user.id} textValue={user.name}>
+                <Avatar size="sm">
+                  <AvatarImage src={user.avatarUrl} />
+                  <AvatarFallback>{user.fallback}</AvatarFallback>
+                </Avatar>
+                <div className="flex flex-col">
+                  <Label>{user.name}</Label>
+                  <Description>{user.email}</Description>
+                </div>
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            ))}
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const states = [
+      {
+        id: "california",
+        name: "California",
+      },
+      {
+        id: "texas",
+        name: "Texas",
+      },
+      {
+        id: "florida",
+        name: "Florida",
+      },
+      {
+        id: "new-york",
+        name: "New York",
+      },
+      {
+        id: "illinois",
+        name: "Illinois",
+      },
+      {
+        id: "pennsylvania",
+        name: "Pennsylvania",
+      },
+    ];
+
+    const [state, setState] = React.useState<Key | null>("california");
+
+    const selectedState = states.find((s) => s.id === state);
+
+    return (
+      <div className="space-y-2">
+        <Select
+          className="w-[256px]"
+          placeholder="Select a state"
+          value={state}
+          onChange={(value) => setState(value)}
+        >
+          <Label>State (controlled)</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              {states.map((state) => (
+                <ListBox.Item key={state.id} id={state.id} textValue={state.name}>
+                  {state.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              ))}
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p>
+      </div>
+    );
+  },
+};
+
+export const ControlledMultiple: Story = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Key[]>(["california", "texas"]);
+
+    return (
+      <div className="space-y-4">
+        <Select
+          className="w-[256px]"
+          placeholder="Select states"
+          selectionMode="multiple"
+          value={selected}
+          onChange={(keys) => setSelected(keys as Key[])}
+        >
+          <Label>States (controlled multiple)</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox selectionMode="multiple">
+              <ListBox.Item id="california" textValue="California">
+                California
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="texas" textValue="Texas">
+                Texas
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="florida" textValue="Florida">
+                Florida
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="new-york" textValue="New York">
+                New York
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="illinois" textValue="Illinois">
+                Illinois
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="pennsylvania" textValue="Pennsylvania">
+                Pennsylvania
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <p className="text-sm text-muted">
+          Selected: {selected.length > 0 ? selected.join(", ") : "None"}
+        </p>
+      </div>
+    );
+  },
+};
+
+export const ControlledOpenState: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = React.useState(false);
+
+    return (
+      <div className="space-y-4">
+        <Select
+          className="w-[256px]"
+          isOpen={isOpen}
+          placeholder="Select one"
+          onOpenChange={setIsOpen}
+        >
+          <Label>State</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="florida" textValue="Florida">
+                Florida
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="delaware" textValue="Delaware">
+                Delaware
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="california" textValue="California">
+                California
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="texas" textValue="Texas">
+                Texas
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="new-york" textValue="New York">
+                New York
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="washington" textValue="Washington">
+                Washington
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+        </Select>
+        <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Select</Button>
+        <p className="text-sm text-muted">Select is {isOpen ? "open" : "closed"}</p>
+      </div>
+    );
+  },
+};
+
+interface Pokemon {
+  name: string;
+}
+
+export const AsynchronousLoading: Story = {
+  render: () => {
+    const list = useAsyncList<Pokemon>({
+      async load({cursor, signal}) {
+        const res = await fetch(cursor || `https://pokeapi.co/api/v2/pokemon`, {signal});
+        const json = await res.json();
+
+        return {
+          items: json.results,
+          cursor: json.next,
+        };
+      },
+    });
+
+    return (
+      <Select className="w-[256px]" placeholder="Select a Pokemon">
+        <Label>Pick a Pokemon</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <Collection items={list.items}>
+              {(item: Pokemon) => (
+                <ListBox.Item id={item.name} textValue={item.name}>
+                  {item.name}
+                  <ListBox.ItemIndicator />
+                </ListBox.Item>
+              )}
+            </Collection>
+            <ListBoxLoadMoreItem
+              isLoading={list.loadingState === "loadingMore"}
+              onLoadMore={list.loadMore}
+            >
+              <div className="flex items-center justify-center gap-2 py-2">
+                <Spinner size="sm" />
+                <span className="text-sm text-muted">Loading more...</span>
+              </div>
+            </ListBoxLoadMoreItem>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Select isDisabled className="w-[256px]" defaultValue="california" placeholder="Select one">
+        <Label>State</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="florida" textValue="Florida">
+              Florida
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="delaware" textValue="Delaware">
+              Delaware
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="california" textValue="California">
+              California
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="texas" textValue="Texas">
+              Texas
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="new-york" textValue="New York">
+              New York
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="washington" textValue="Washington">
+              Washington
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+      <Select
+        isDisabled
+        className="w-[256px]"
+        defaultValue={["argentina", "japan", "france"]}
+        placeholder="Select countries"
+        selectionMode="multiple"
+      >
+        <Label>Countries to Visit</Label>
+        <Select.Trigger>
+          <Select.Value />
+          <Select.Indicator />
+        </Select.Trigger>
+        <Select.Popover>
+          <ListBox>
+            <ListBox.Item id="argentina" textValue="Argentina">
+              Argentina
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="venezuela" textValue="Venezuela">
+              Venezuela
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="japan" textValue="Japan">
+              Japan
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="france" textValue="France">
+              France
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="italy" textValue="Italy">
+              Italy
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+            <ListBox.Item id="spain" textValue="Spain">
+              Spain
+              <ListBox.ItemIndicator />
+            </ListBox.Item>
+          </ListBox>
+        </Select.Popover>
+      </Select>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/select/select.tsx b/packages/react/src/components/select/select.tsx
new file mode 100644
index 0000000..22e8ee9
--- /dev/null
+++ b/packages/react/src/components/select/select.tsx
@@ -0,0 +1,193 @@
+"use client";
+
+import type {Booleanish} from "../../utils/assertion";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "../surface";
+import type {SelectVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {selectVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {Button as ButtonPrimitive} from "react-aria-components/Button";
+import {Popover as PopoverPrimitive} from "react-aria-components/Popover";
+import {
+  Select as SelectPrimitive,
+  SelectStateContext,
+  SelectValue as SelectValuePrimitive,
+} from "react-aria-components/Select";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {IconChevronDown} from "../icons";
+import {SurfaceContext} from "../surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Context
+ * -----------------------------------------------------------------------------------------------*/
+type SelectContext = {
+  slots?: ReturnType<typeof selectVariants>;
+};
+
+const SelectContext = createContext<SelectContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SelectRootProps<T extends object, M extends "single" | "multiple" = "single">
+  extends ComponentPropsWithRef<typeof SelectPrimitive<T, M>>, SelectVariants {
+  items?: Iterable<T, M>;
+}
+
+const SelectRoot = <T extends object = object, M extends "single" | "multiple" = "single">({
+  children,
+  className,
+  fullWidth,
+  variant,
+  ...props
+}: SelectRootProps<T, M>) => {
+  const slots = React.useMemo(() => selectVariants({fullWidth, variant}), [fullWidth, variant]);
+
+  return (
+    <SelectContext value={{slots}}>
+      <SelectPrimitive
+        data-slot="select"
+        {...props}
+        className={composeTwRenderProps(className, slots?.base())}
+      >
+        {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+      </SelectPrimitive>
+    </SelectContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface SelectTriggerProps extends ComponentPropsWithRef<typeof ButtonPrimitive> {}
+
+const SelectTrigger = ({children, className, ...props}: SelectTriggerProps) => {
+  const {slots} = use(SelectContext);
+
+  return (
+    <ButtonPrimitive
+      className={composeTwRenderProps(className, slots?.trigger())}
+      data-slot="select-trigger"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </ButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Value
+ * -----------------------------------------------------------------------------------------------*/
+interface SelectValueProps extends ComponentPropsWithRef<typeof SelectValuePrimitive> {}
+
+const SelectValue = ({children, className, ...props}: SelectValueProps) => {
+  const {slots} = use(SelectContext);
+
+  return (
+    <SelectValuePrimitive
+      className={composeTwRenderProps(className, slots?.value())}
+      data-slot="select-value"
+      {...props}
+    >
+      {children}
+    </SelectValuePrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface SelectIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "svg",
+> extends DOMRenderProps<E, undefined> {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+const SelectIndicator = <E extends keyof React.JSX.IntrinsicElements = "svg">({
+  children,
+  className,
+  ...props
+}: SelectIndicatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof SelectIndicatorProps<E>>) => {
+  const {slots} = use(SelectContext);
+  const state = use(SelectStateContext);
+
+  if (children && React.isValidElement(children)) {
+    return React.cloneElement(
+      children as React.ReactElement<{
+        className?: string;
+        "data-slot"?: "select-indicator";
+        "data-open"?: Booleanish;
+      }>,
+      {
+        ...(props as any),
+        className: composeSlotClassName(slots?.indicator, className),
+        "data-slot": "select-indicator",
+        "data-open": dataAttr(state?.isOpen),
+      },
+    );
+  }
+
+  return (
+    <IconChevronDown
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-open={dataAttr(state?.isOpen)}
+      data-slot="select-default-indicator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Select Popover
+ * -----------------------------------------------------------------------------------------------*/
+interface SelectPopoverProps extends Omit<
+  ComponentPropsWithRef<typeof PopoverPrimitive>,
+  "children"
+> {
+  children: React.ReactNode;
+}
+
+const SelectPopover = ({
+  children,
+  className,
+  placement = "bottom",
+  ...props
+}: SelectPopoverProps) => {
+  const {slots} = use(SelectContext);
+
+  return (
+    <SurfaceContext
+      value={{
+        variant: "default" as SurfaceVariants["variant"],
+      }}
+    >
+      <PopoverPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots?.popover())}
+        data-slot="select-popover"
+        placement={placement}
+      >
+        {children}
+      </PopoverPrimitive>
+    </SurfaceContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SelectRoot, SelectTrigger, SelectValue, SelectIndicator, SelectPopover};
+
+export type {
+  SelectRootProps,
+  SelectTriggerProps,
+  SelectValueProps,
+  SelectIndicatorProps,
+  SelectPopoverProps,
+};
diff --git a/packages/react/src/components/separator/index.ts b/packages/react/src/components/separator/index.ts
new file mode 100644
index 0000000..de642a5
--- /dev/null
+++ b/packages/react/src/components/separator/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {SeparatorRoot} from "./separator";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Separator = Object.assign(SeparatorRoot, {
+  Root: SeparatorRoot,
+});
+
+export type Separator = {
+  Props: ComponentProps<typeof SeparatorRoot>;
+  RootProps: ComponentProps<typeof SeparatorRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SeparatorRoot};
+
+export type {SeparatorRootProps, SeparatorRootProps as SeparatorProps} from "./separator";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {separatorVariants} from "@heroui/styles";
+
+export type {SeparatorVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/separator/separator.stories.tsx b/packages/react/src/components/separator/separator.stories.tsx
new file mode 100644
index 0000000..d0edef6
--- /dev/null
+++ b/packages/react/src/components/separator/separator.stories.tsx
@@ -0,0 +1,104 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Separator} from "./index";
+
+const meta: Meta<typeof Separator> = {
+  title: "Components/Layout/Separator",
+  component: Separator,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    orientation: {
+      control: {type: "radio"},
+      options: ["horizontal", "vertical"],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <div className="space-y-1">
+        <h4 className="text-medium font-medium">HeroUI v3 Components</h4>
+        <p className="text-small text-default-400">Beautiful, fast and modern React UI library.</p>
+      </div>
+      <Separator className="my-4" />
+      <div className="text-small flex h-5 items-center space-x-4">
+        <div>Blog</div>
+        <Separator orientation="vertical" />
+        <div>Docs</div>
+        <Separator orientation="vertical" />
+        <div>Source</div>
+      </div>
+    </div>
+  ),
+};
+
+export const Vertical: Story = {
+  render: () => (
+    <div className="text-small flex h-5 items-center space-x-4">
+      <div>Blog</div>
+      <Separator orientation="vertical" />
+      <div>Docs</div>
+      <Separator orientation="vertical" />
+      <div>Source</div>
+    </div>
+  ),
+};
+
+const items = [
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
+    subtitle: "Receive account activity updates",
+    title: "Set Up Notifications",
+  },
+  {
+    iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
+    subtitle: "Connect your browser to your account",
+    title: "Set up Browser Extension",
+  },
+  {
+    iconUrl:
+      "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
+    subtitle: "Create your first collectible",
+    title: "Mint Collectible",
+  },
+];
+
+export const WithContent: Story = {
+  render: () => (
+    <div className="max-w-md space-y-4 rounded-3xl bg-surface p-4 shadow-surface">
+      {items.map((item, index) => (
+        <div key={item.title}>
+          <div className="flex items-center gap-3">
+            <img alt={item.title} className="size-12" src={item.iconUrl} />
+            <div className="flex-1 space-y-0">
+              <h4 className="text-small font-medium">{item.title}</h4>
+              <p className="text-sm text-muted">{item.subtitle}</p>
+            </div>
+          </div>
+          {index < items.length - 1 && <Separator className="my-4" />}
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex max-w-md flex-col items-center gap-3">
+      <div>Default Variant</div>
+      <Separator variant="default" />
+      <div>Secondary Variant</div>
+      <Separator variant="secondary" />
+      <div>Tertiary Variant</div>
+      <Separator variant="tertiary" />
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/separator/separator.tsx b/packages/react/src/components/separator/separator.tsx
new file mode 100644
index 0000000..b96f6a5
--- /dev/null
+++ b/packages/react/src/components/separator/separator.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import type {SeparatorVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {separatorVariants} from "@heroui/styles";
+import React from "react";
+import {SeparatorContext, Separator as SeparatorPrimitive} from "react-aria-components/Separator";
+import {useSlottedContext} from "react-aria-components/slots";
+
+/* -------------------------------------------------------------------------------------------------
+ * Separator Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SeparatorRootProps
+  extends ComponentPropsWithRef<typeof SeparatorPrimitive>, SeparatorVariants {}
+
+const SeparatorRoot = ({className, orientation, variant, ...props}: SeparatorRootProps) => {
+  const context = useSlottedContext(SeparatorContext);
+  const resolvedOrientation = orientation ?? context?.orientation ?? "horizontal";
+
+  return (
+    <SeparatorPrimitive
+      data-orientation={resolvedOrientation}
+      data-slot="separator"
+      orientation={resolvedOrientation}
+      className={separatorVariants({
+        orientation: resolvedOrientation,
+        variant,
+        className,
+      })}
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SeparatorRoot};
+
+export type {SeparatorRootProps};
diff --git a/packages/react/src/components/skeleton/index.ts b/packages/react/src/components/skeleton/index.ts
new file mode 100644
index 0000000..3d90d58
--- /dev/null
+++ b/packages/react/src/components/skeleton/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {SkeletonRoot} from "./skeleton";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Skeleton = Object.assign(SkeletonRoot, {
+  Root: SkeletonRoot,
+});
+
+export type Skeleton = {
+  Props: ComponentProps<typeof SkeletonRoot>;
+  RootProps: ComponentProps<typeof SkeletonRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SkeletonRoot};
+
+export type {SkeletonRootProps, SkeletonRootProps as SkeletonProps} from "./skeleton";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {skeletonVariants} from "@heroui/styles";
+
+export type {SkeletonVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/skeleton/skeleton.stories.tsx b/packages/react/src/components/skeleton/skeleton.stories.tsx
new file mode 100644
index 0000000..4adc0dc
--- /dev/null
+++ b/packages/react/src/components/skeleton/skeleton.stories.tsx
@@ -0,0 +1,67 @@
+import type {SkeletonProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {Skeleton} from "./index";
+
+export default {
+  argTypes: {
+    animationType: {
+      control: "select",
+      options: ["shimmer", "pulse", "none"],
+    },
+  },
+  component: Skeleton,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Feedback/Skeleton",
+} as Meta<typeof Skeleton>;
+
+const defaultArgs: SkeletonProps = {};
+
+const Template = (props: SkeletonProps) => (
+  <div className="bg-surface-1 w-[200px] space-y-5 rounded-3xl p-4 shadow-surface">
+    <Skeleton className="h-24 rounded-xl" {...props} />
+    <div className="space-y-3">
+      <Skeleton className="h-3 w-3/5 rounded-lg" {...props} />
+      <Skeleton className="h-3 w-4/5 rounded-lg" {...props} />
+      <Skeleton className="h-3 w-2/5 rounded-lg" {...props} />
+    </div>
+  </div>
+);
+
+const GridTemplate = (props: SkeletonProps) => (
+  <div className="grid w-[450px] grid-cols-3 gap-4">
+    <Skeleton className="h-24 rounded-xl" {...props} />
+    <Skeleton className="h-24 rounded-xl" {...props} />
+    <Skeleton className="h-24 rounded-xl" {...props} />
+  </div>
+);
+
+const SingleShimmerTemplate = (props: SkeletonProps) => (
+  <div className="skeleton--shimmer relative grid w-[450px] grid-cols-3 gap-4 overflow-hidden rounded-xl">
+    <Skeleton className="h-24 rounded-xl" {...props} />
+    <Skeleton className="h-24 rounded-xl" {...props} />
+    <Skeleton className="h-24 rounded-xl" {...props} />
+  </div>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Grid = {
+  args: defaultArgs,
+  render: GridTemplate,
+};
+
+export const SingleShimmer = {
+  args: {
+    ...defaultArgs,
+    animationType: "none",
+  },
+  render: SingleShimmerTemplate,
+};
diff --git a/packages/react/src/components/skeleton/skeleton.tsx b/packages/react/src/components/skeleton/skeleton.tsx
new file mode 100644
index 0000000..fcc6e0f
--- /dev/null
+++ b/packages/react/src/components/skeleton/skeleton.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SkeletonVariants} from "@heroui/styles";
+
+import {skeletonVariants} from "@heroui/styles";
+import React from "react";
+
+import {useCSSVariable} from "../../hooks/use-css-variable";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Skeleton Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SkeletonRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+  /** Animation type. */
+  animationType?: SkeletonVariants["animationType"];
+}
+
+const SkeletonRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  animationType,
+  className,
+  ...props
+}: SkeletonRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SkeletonRootProps<E>>) => {
+  // Use the new hook to get CSS variable value with SSR support
+  const resolvedAnimationType = useCSSVariable("--skeleton-animation", animationType);
+  const slots = React.useMemo(
+    () =>
+      skeletonVariants({
+        animationType: resolvedAnimationType as SkeletonVariants["animationType"],
+      }),
+    [resolvedAnimationType],
+  );
+
+  return <dom.div className={slots.base({className})} {...(props as any)} />;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SkeletonRoot};
+
+export type {SkeletonRootProps};
diff --git a/packages/react/src/components/slider/index.ts b/packages/react/src/components/slider/index.ts
new file mode 100644
index 0000000..743f4f2
--- /dev/null
+++ b/packages/react/src/components/slider/index.ts
@@ -0,0 +1,54 @@
+import type {ComponentProps} from "react";
+
+import {
+  SliderFill,
+  SliderMarks,
+  SliderOutput,
+  SliderRoot,
+  SliderThumb,
+  SliderTrack,
+} from "./slider";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Slider = Object.assign(SliderRoot, {
+  Root: SliderRoot,
+  Output: SliderOutput,
+  Track: SliderTrack,
+  Fill: SliderFill,
+  Thumb: SliderThumb,
+  Marks: SliderMarks,
+});
+
+export type Slider = {
+  Props: ComponentProps<typeof SliderRoot>;
+  RootProps: ComponentProps<typeof SliderRoot>;
+  OutputProps: ComponentProps<typeof SliderOutput>;
+  TrackProps: ComponentProps<typeof SliderTrack>;
+  FillProps: ComponentProps<typeof SliderFill>;
+  ThumbProps: ComponentProps<typeof SliderThumb>;
+  MarksProps: ComponentProps<typeof SliderMarks>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SliderRoot, SliderOutput, SliderTrack, SliderFill, SliderThumb, SliderMarks};
+
+export type {
+  SliderRootProps,
+  SliderRootProps as SliderProps,
+  SliderOutputProps,
+  SliderTrackProps,
+  SliderFillProps,
+  SliderThumbProps,
+  SliderMarksProps,
+} from "./slider";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {sliderVariants} from "@heroui/styles";
+
+export type {SliderVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/slider/slider.stories.tsx b/packages/react/src/components/slider/slider.stories.tsx
new file mode 100644
index 0000000..7849bc1
--- /dev/null
+++ b/packages/react/src/components/slider/slider.stories.tsx
@@ -0,0 +1,115 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Label} from "../label";
+
+import {Slider} from "./index";
+
+const meta: Meta<typeof Slider> = {
+  argTypes: {
+    isDisabled: {
+      control: {type: "boolean"},
+    },
+    orientation: {
+      control: {type: "select"},
+      options: ["horizontal", "vertical"],
+    },
+  },
+  component: Slider,
+  decorators: [
+    (Story) => (
+      <div className="w-96 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Controls/Slider",
+};
+
+export default meta;
+type Story = StoryObj<typeof Slider>;
+
+export const Default: Story = {
+  render: (args) => {
+    return (
+      <Slider defaultValue={30} {...args}>
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    );
+  },
+};
+
+export const Vertical: Story = {
+  decorators: [
+    (Story) => (
+      <div className="h-96 p-8">
+        <Story />
+      </div>
+    ),
+  ],
+  render: (args) => {
+    return (
+      <Slider defaultValue={30} orientation="vertical" {...args}>
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: (args) => {
+    return (
+      <Slider isDisabled defaultValue={30} {...args}>
+        <Label>Volume</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    );
+  },
+};
+
+export const Range: Story = {
+  render: (args) => {
+    return (
+      <Slider
+        defaultValue={[100, 500]}
+        formatOptions={{style: "currency", currency: "USD"}}
+        maxValue={1000}
+        minValue={0}
+        step={50}
+        {...args}
+      >
+        <Label>Price Range</Label>
+        <Slider.Output />
+        <Slider.Track>
+          {({state}) => (
+            <>
+              <Slider.Fill />
+              {state.values.map((_, i) => (
+                <Slider.Thumb key={i} index={i} />
+              ))}
+            </>
+          )}
+        </Slider.Track>
+      </Slider>
+    );
+  },
+};
diff --git a/packages/react/src/components/slider/slider.tsx b/packages/react/src/components/slider/slider.tsx
new file mode 100644
index 0000000..4a494cb
--- /dev/null
+++ b/packages/react/src/components/slider/slider.tsx
@@ -0,0 +1,231 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SliderVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {SliderRenderProps} from "react-aria-components/Slider";
+
+import {sliderVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  SliderOutput as SliderOutputPrimitive,
+  Slider as SliderPrimitive,
+  SliderThumb as SliderThumbPrimitive,
+  SliderTrack as SliderTrackPrimitive,
+} from "react-aria-components/Slider";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Component Status: Preview
+ * -----------------------------------------------------------------------------------------------*/
+
+// TODO: steps support
+// TODO: marks support
+// TODO: rtl support
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Context
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderContext {
+  slots?: ReturnType<typeof sliderVariants>;
+  state?: SliderRenderProps;
+}
+
+const SliderContext = createContext<SliderContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderRootProps extends ComponentPropsWithRef<typeof SliderPrimitive>, SliderVariants {}
+
+const SliderRoot = ({
+  children,
+  className,
+  orientation = "horizontal",
+  ...props
+}: SliderRootProps) => {
+  const slots = React.useMemo(() => sliderVariants({}), []);
+
+  return (
+    <SliderPrimitive
+      data-slot="slider"
+      orientation={orientation}
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(values) => (
+        <SliderContext value={{slots, state: values}}>
+          {typeof children === "function" ? children(values) : children}
+        </SliderContext>
+      )}
+    </SliderPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Output
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderOutputProps extends ComponentPropsWithRef<typeof SliderOutputPrimitive> {}
+
+const SliderOutput = ({children, className, ...props}: SliderOutputProps) => {
+  const {slots} = use(SliderContext);
+
+  return (
+    <SliderOutputPrimitive
+      className={composeTwRenderProps(className, slots?.output())}
+      data-slot="slider-output"
+      {...props}
+    >
+      {children
+        ? (values) => <>{typeof children === "function" ? children(values) : children}</>
+        : ({state}) => state.values.map((_, i) => state.getThumbValueLabel(i)).join(" – ")}
+    </SliderOutputPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Track
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderTrackProps extends ComponentPropsWithRef<typeof SliderTrackPrimitive> {}
+
+const SliderTrack = ({children, className, ...props}: SliderTrackProps) => {
+  const {slots, state} = use(SliderContext);
+
+  const {getThumbPercent, values} = state?.state || {};
+
+  const singleThumb = values?.length && values.length === 1;
+
+  const [startOffset, endOffset] = [
+    values?.length && values.length > 1 ? getThumbPercent?.(0) : 0,
+    getThumbPercent?.(values?.length ? values.length - 1 : 0),
+  ].sort();
+
+  const fillWidth = (endOffset! - startOffset!) * 100;
+
+  return (
+    <SliderTrackPrimitive
+      className={composeTwRenderProps(className, slots?.track())}
+      data-disabled={dataAttr(state?.isDisabled)}
+      data-slot="slider-track"
+      {...(singleThumb
+        ? {
+            "data-fill-start": dataAttr(fillWidth > 0),
+            "data-fill-end": dataAttr(fillWidth == 100),
+          }
+        : {
+            "data-fill-start": dataAttr(startOffset == 0),
+            "data-fill-end": dataAttr(startOffset! * 100 + fillWidth == 100),
+          })}
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </SliderTrackPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Fill
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderFillProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const SliderFill = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  style,
+  ...props
+}: SliderFillProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SliderFillProps<E>>) => {
+  const {slots, state} = use(SliderContext);
+
+  const {getThumbPercent, orientation, values} = state?.state || {};
+
+  const [startOffset, endOffset] = [
+    values?.length && values.length > 1 ? getThumbPercent?.(0) : 0,
+    getThumbPercent?.(values?.length ? values.length - 1 : 0),
+  ].sort();
+
+  const isVertical = orientation === "vertical";
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.fill, className)}
+      data-disabled={dataAttr(state?.isDisabled)}
+      data-slot="slider-fill"
+      style={{
+        ...style,
+        // TODO: rtl support
+        [isVertical ? "bottom" : "left"]: `${startOffset! * 100}%`,
+        ...(isVertical
+          ? {
+              height: `${(endOffset! - startOffset!) * 100}%`,
+            }
+          : {
+              width: `${(endOffset! - startOffset!) * 100}%`,
+            }),
+      }}
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Slider Thumb
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderThumbProps extends ComponentPropsWithRef<typeof SliderThumbPrimitive> {}
+
+const SliderThumb = ({children, className, ...props}: SliderThumbProps) => {
+  const {slots} = use(SliderContext);
+
+  return (
+    <SliderThumbPrimitive
+      className={composeTwRenderProps(className, slots?.thumb())}
+      data-slot="slider-thumb"
+      {...props}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </SliderThumbPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * TODO: Slider Marks
+ * -----------------------------------------------------------------------------------------------*/
+interface SliderMarksProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const SliderMarks = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: SliderMarksProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SliderMarksProps<E>>) => {
+  const {slots} = use(SliderContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.marks, className)}
+      data-slot="slider-marks"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SliderRoot, SliderOutput, SliderTrack, SliderFill, SliderThumb, SliderMarks};
+
+export type {
+  SliderRootProps,
+  SliderOutputProps,
+  SliderTrackProps,
+  SliderFillProps,
+  SliderThumbProps,
+  SliderMarksProps,
+};
diff --git a/packages/react/src/components/spinner/index.ts b/packages/react/src/components/spinner/index.ts
new file mode 100644
index 0000000..1f53c9d
--- /dev/null
+++ b/packages/react/src/components/spinner/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {SpinnerRoot} from "./spinner";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Spinner = Object.assign(SpinnerRoot, {
+  Root: SpinnerRoot,
+});
+
+export type Spinner = {
+  Props: ComponentProps<typeof SpinnerRoot>;
+  RootProps: ComponentProps<typeof SpinnerRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SpinnerRoot};
+
+export type {SpinnerRootProps, SpinnerRootProps as SpinnerProps} from "./spinner";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {spinnerVariants} from "@heroui/styles";
+
+export type {SpinnerVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/spinner/spinner.stories.tsx b/packages/react/src/components/spinner/spinner.stories.tsx
new file mode 100644
index 0000000..55d4c56
--- /dev/null
+++ b/packages/react/src/components/spinner/spinner.stories.tsx
@@ -0,0 +1,93 @@
+import type {SpinnerProps} from "./index";
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {Spinner} from "./index";
+
+export default {
+  argTypes: {
+    color: {
+      control: "select",
+      options: ["accent", "current", "danger", "success", "warning"],
+    },
+    size: {
+      control: "select",
+      options: ["lg", "md", "sm", "xl"],
+    },
+  },
+  component: Spinner,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Feedback/Spinner",
+} as Meta<typeof Spinner>;
+
+const defaultArgs: SpinnerProps = {};
+
+const Template = (props: SpinnerProps) => (
+  <div className="flex items-center gap-3">
+    <Spinner {...props} />
+  </div>
+);
+
+const ColorsTemplate = (props: SpinnerProps) => (
+  <div className="flex items-center gap-8">
+    <div className="flex flex-col items-center gap-2">
+      <Spinner color="accent" {...props} />
+      <span className="text-xs text-muted">Accent</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner color="current" {...props} />
+      <span className="text-xs text-muted">Current</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner color="success" {...props} />
+      <span className="text-xs text-muted">Success</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner color="warning" {...props} />
+      <span className="text-xs text-muted">Warning</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner color="danger" {...props} />
+      <span className="text-xs text-muted">Danger</span>
+    </div>
+  </div>
+);
+
+const SizesTemplate = (props: SpinnerProps) => (
+  <div className="flex items-center gap-8">
+    <div className="flex flex-col items-center gap-2">
+      <Spinner size="sm" {...props} />
+      <span className="text-xs text-muted">Small</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner size="md" {...props} />
+      <span className="text-xs text-muted">Medium</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner size="lg" {...props} />
+      <span className="text-xs text-muted">Large</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Spinner size="xl" {...props} />
+      <span className="text-xs text-muted">Extra Large</span>
+    </div>
+  </div>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Colors = {
+  args: defaultArgs,
+  render: ColorsTemplate,
+};
+
+export const Sizes = {
+  args: defaultArgs,
+  render: SizesTemplate,
+};
diff --git a/packages/react/src/components/spinner/spinner.tsx b/packages/react/src/components/spinner/spinner.tsx
new file mode 100644
index 0000000..eb5961a
--- /dev/null
+++ b/packages/react/src/components/spinner/spinner.tsx
@@ -0,0 +1,102 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SpinnerVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {spinnerVariants} from "@heroui/styles";
+import React, {useId} from "react";
+
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Internal
+ * -------------------------------------------------------------------------------------------------
+ * Spinner Primitive
+ * -----------------------------------------------------------------------------------------------*/
+interface SpinnerPrimitiveProps extends ComponentPropsWithRef<"svg"> {}
+
+const SpinnerPrimitive = ({...props}: SpinnerPrimitiveProps) => {
+  const id = useId();
+
+  return (
+    <svg data-slot="spinner-icon" viewBox="0 0 24 24" {...props}>
+      <defs>
+        <linearGradient
+          id={`«data-slot-icon-def-1»-${id}`}
+          x1="50%"
+          x2="50%"
+          y1="5.271%"
+          y2="91.793%"
+        >
+          <stop offset="0%" stopColor="currentColor" />
+          <stop offset="100%" stopColor="currentColor" stopOpacity={0.55} />
+        </linearGradient>
+        <linearGradient
+          id={`«data-slot-icon-def-2»-${id}`}
+          x1="50%"
+          x2="50%"
+          y1="15.24%"
+          y2="87.15%"
+        >
+          <stop offset="0%" stopColor="currentColor" stopOpacity={0} />
+          <stop offset="100%" stopColor="currentColor" stopOpacity={0.55} />
+        </linearGradient>
+      </defs>
+      <g fill="none">
+        <path d="m12.593 23.258l-.011.002l-.071.035l-.02.004l-.014-.004l-.071-.035q-.016-.005-.024.005l-.004.01l-.017.428l.005.02l.01.013l.104.074l.015.004l.012-.004l.104-.074l.012-.016l.004-.017l-.017-.427q-.004-.016-.017-.018m.265-.113l-.013.002l-.185.093l-.01.01l-.003.011l.018.43l.005.012l.008.007l.201.093q.019.005.029-.008l.004-.014l-.034-.614q-.005-.018-.02-.022m-.715.002a.02.02 0 0 0-.027.006l-.006.014l-.034.614q.001.018.017.024l.015-.002l.201-.093l.01-.008l.004-.011l.017-.43l-.003-.012l-.01-.01z" />
+        <path
+          d="M8.749.021a1.5 1.5 0 0 1 .497 2.958A7.5 7.5 0 0 0 3 10.375a7.5 7.5 0 0 0 7.5 7.5v3c-5.799 0-10.5-4.7-10.5-10.5C0 5.23 3.726.865 8.749.021"
+          fill={`url(#«data-slot-icon-def-1»-${id})`}
+          transform="translate(1.5 1.625)"
+        />
+        <path
+          d="M15.392 2.673a1.5 1.5 0 0 1 2.119-.115A10.48 10.48 0 0 1 21 10.375c0 5.8-4.701 10.5-10.5 10.5v-3a7.5 7.5 0 0 0 5.007-13.084a1.5 1.5 0 0 1-.115-2.118"
+          fill={`url(#«data-slot-icon-def-2»-${id})`}
+          transform="translate(1.5 1.625)"
+        />
+      </g>
+    </svg>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Spinner Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SpinnerRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+  /** Spinner color. */
+  color?: SpinnerVariants["color"];
+  /** Spinner size. */
+  size?: SpinnerVariants["size"];
+}
+
+const SpinnerRoot = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  color,
+  size,
+  ...props
+}: SpinnerRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SpinnerRootProps<E>>) => {
+  return (
+    <dom.span
+      data-slot="spinner"
+      {...(props as any)}
+      className={spinnerVariants({
+        className,
+        color,
+        size,
+      })}
+    >
+      <SpinnerPrimitive aria-hidden aria-label="Loading" role="presentation" />
+    </dom.span>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SpinnerRoot};
+
+export type {SpinnerRootProps};
diff --git a/packages/react/src/components/surface/index.ts b/packages/react/src/components/surface/index.ts
new file mode 100644
index 0000000..a8e737b
--- /dev/null
+++ b/packages/react/src/components/surface/index.ts
@@ -0,0 +1,34 @@
+import type {ComponentProps} from "react";
+
+import {SurfaceRoot} from "./surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Surface = Object.assign(SurfaceRoot, {
+  Root: SurfaceRoot,
+});
+
+export type Surface = {
+  Props: ComponentProps<typeof SurfaceRoot>;
+  RootProps: ComponentProps<typeof SurfaceRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SurfaceRoot} from "./surface";
+
+export type {SurfaceRootProps, SurfaceRootProps as SurfaceProps} from "./surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Context
+ * -----------------------------------------------------------------------------------------------*/
+export {SurfaceContext} from "./surface";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {surfaceVariants} from "@heroui/styles";
+
+export type {SurfaceVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/surface/surface.stories.tsx b/packages/react/src/components/surface/surface.stories.tsx
new file mode 100644
index 0000000..3cfc692
--- /dev/null
+++ b/packages/react/src/components/surface/surface.stories.tsx
@@ -0,0 +1,84 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Input} from "../input";
+import {Label} from "../label";
+import {TextField} from "../textfield";
+
+import {Surface} from "./index";
+
+const meta: Meta<typeof Surface> = {
+  argTypes: {},
+  component: Surface,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Layout/Surface",
+};
+
+export default meta;
+type Story = StoryObj<typeof Surface>;
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Transparent</p>
+        <Surface
+          className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
+          variant="transparent"
+        >
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <TextField isRequired name="email" type="email">
+            <Label>Email</Label>
+            <Input className="w-[280px]" placeholder="john@example.com" />
+          </TextField>
+          <p className="text-sm text-muted">
+            This is a default surface variant. It uses bg-surface styling.
+          </p>
+        </Surface>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Default</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <TextField isRequired name="email" type="email" variant="secondary">
+            <Label>Email</Label>
+            <Input className="w-[280px] border border-border/20" placeholder="john@example.com" />
+          </TextField>
+          <p className="text-sm text-muted">
+            This is a default surface variant. It uses bg-surface styling.
+          </p>
+        </Surface>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Secondary</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <TextField isRequired name="email" type="email">
+            <Label>Email</Label>
+            <Input className="w-[280px]" placeholder="john@example.com" />
+          </TextField>
+          <p className="text-sm text-muted">
+            This is a secondary surface variant. It uses bg-surface-secondary styling.
+          </p>
+        </Surface>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <p className="text-sm font-medium text-muted">Tertiary</p>
+        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
+          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
+          <TextField isRequired name="email" type="email">
+            <Label>Email</Label>
+            <Input className="w-[280px]" placeholder="john@example.com" />
+          </TextField>
+          <p className="text-sm text-muted">
+            This is a tertiary surface variant. It uses bg-surface-tertiary styling.
+          </p>
+        </Surface>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/surface/surface.tsx b/packages/react/src/components/surface/surface.tsx
new file mode 100644
index 0000000..c38b016
--- /dev/null
+++ b/packages/react/src/components/surface/surface.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SurfaceVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {surfaceVariants} from "@heroui/styles";
+import React, {createContext} from "react";
+
+import {dom} from "../../utils/dom";
+
+/* ------------------------------------------------------------------------------------------------
+ * Surface Context
+ * --------------------------------------------------------------------------------------------- */
+type SurfaceContext = {
+  variant?: SurfaceVariants["variant"];
+};
+
+const SurfaceContext = createContext<SurfaceContext>({});
+
+/* ------------------------------------------------------------------------------------------------
+ * Surface Root
+ * --------------------------------------------------------------------------------------------- */
+interface SurfaceRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children: ReactNode;
+  className?: string;
+  /** Visual variant. @default "default" */
+  variant?: SurfaceVariants["variant"];
+}
+
+const SurfaceRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  variant = "default",
+  ...rest
+}: SurfaceRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SurfaceRootProps<E>>) => {
+  return (
+    <SurfaceContext value={{variant}}>
+      <dom.div
+        className={surfaceVariants({variant, className})}
+        data-slot="surface"
+        {...(rest as any)}
+      >
+        {children}
+      </dom.div>
+    </SurfaceContext>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Exports
+ * --------------------------------------------------------------------------------------------- */
+export {SurfaceRoot, SurfaceContext};
+
+export type {SurfaceRootProps};
diff --git a/packages/react/src/components/switch-group/index.ts b/packages/react/src/components/switch-group/index.ts
new file mode 100644
index 0000000..f4c6bb3
--- /dev/null
+++ b/packages/react/src/components/switch-group/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {SwitchGroupRoot} from "./switch-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const SwitchGroup = Object.assign(SwitchGroupRoot, {
+  Root: SwitchGroupRoot,
+});
+
+export type SwitchGroup = {
+  Props: ComponentProps<typeof SwitchGroupRoot>;
+  RootProps: ComponentProps<typeof SwitchGroupRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SwitchGroupRoot};
+
+export type {SwitchGroupRootProps, SwitchGroupRootProps as SwitchGroupProps} from "./switch-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {switchGroupVariants} from "@heroui/styles";
+
+export type {SwitchGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/switch-group/switch-group.stories.tsx b/packages/react/src/components/switch-group/switch-group.stories.tsx
new file mode 100644
index 0000000..363acb4
--- /dev/null
+++ b/packages/react/src/components/switch-group/switch-group.stories.tsx
@@ -0,0 +1,130 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Button} from "../button";
+import {Switch} from "../switch";
+
+import {SwitchGroup} from "./index";
+
+export default {
+  argTypes: {},
+  component: SwitchGroup,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Controls/SwitchGroup",
+} as Meta<typeof SwitchGroup>;
+
+type Story = StoryObj<typeof SwitchGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <SwitchGroup>
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Allow Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing emails
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Social media updates
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  ),
+};
+
+export const Horizontal: Story = {
+  render: () => (
+    <SwitchGroup className="overflow-x-auto" orientation="horizontal">
+      <Switch name="notifications">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Notifications
+        </Switch.Content>
+      </Switch>
+      <Switch name="marketing">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Marketing
+        </Switch.Content>
+      </Switch>
+      <Switch name="social">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Social
+        </Switch.Content>
+      </Switch>
+    </SwitchGroup>
+  ),
+};
+
+export const Form: Story = {
+  render: function FormExample() {
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+      const formData = new FormData(e.target as HTMLFormElement);
+
+      alert(
+        `Form submitted with:\n${Array.from(formData.entries())
+          .map(([key, value]) => `${key}: ${value}`)
+          .join("\n")}`,
+      );
+    };
+
+    return (
+      <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
+        <SwitchGroup>
+          <Switch name="notifications" value="on">
+            <Switch.Content>
+              <Switch.Control>
+                <Switch.Thumb />
+              </Switch.Control>
+              Enable notifications
+            </Switch.Content>
+          </Switch>
+          <Switch defaultSelected name="newsletter" value="on">
+            <Switch.Content>
+              <Switch.Control>
+                <Switch.Thumb />
+              </Switch.Control>
+              Subscribe to newsletter
+            </Switch.Content>
+          </Switch>
+          <Switch name="marketing" value="on">
+            <Switch.Content>
+              <Switch.Control>
+                <Switch.Thumb />
+              </Switch.Control>
+              Receive marketing updates
+            </Switch.Content>
+          </Switch>
+        </SwitchGroup>
+        <Button className="mt-4" size="sm" type="submit" variant="primary">
+          Submit
+        </Button>
+      </form>
+    );
+  },
+};
diff --git a/packages/react/src/components/switch-group/switch-group.tsx b/packages/react/src/components/switch-group/switch-group.tsx
new file mode 100644
index 0000000..b7afd98
--- /dev/null
+++ b/packages/react/src/components/switch-group/switch-group.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SwitchGroupVariants} from "@heroui/styles";
+import type {ReactNode} from "react";
+
+import {switchGroupVariants} from "@heroui/styles";
+import React from "react";
+
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Switch Group Root
+ * -----------------------------------------------------------------------------------------------*/
+interface SwitchGroupRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  /** Layout orientation. */
+  orientation?: SwitchGroupVariants["orientation"];
+}
+
+const SwitchGroupRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  orientation,
+  ...props
+}: SwitchGroupRootProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof SwitchGroupRootProps<E>>) => {
+  const slots = React.useMemo(() => switchGroupVariants({orientation}), [orientation]);
+
+  return (
+    <dom.div data-slot="switch-group" {...(props as any)} className={slots.base({className})}>
+      <dom.div className={slots.items()} data-slot="switch-group-items">
+        {children}
+      </dom.div>
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {SwitchGroupRoot};
+
+export type {SwitchGroupRootProps};
diff --git a/packages/react/src/components/switch/index.ts b/packages/react/src/components/switch/index.ts
new file mode 100644
index 0000000..771c09c
--- /dev/null
+++ b/packages/react/src/components/switch/index.ts
@@ -0,0 +1,48 @@
+import type {ComponentProps} from "react";
+
+import {SwitchContent, SwitchControl, SwitchIcon, SwitchRoot, SwitchThumb} from "./switch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Switch = Object.assign(SwitchRoot, {
+  Root: SwitchRoot,
+  Content: SwitchContent,
+  Control: SwitchControl,
+  Thumb: SwitchThumb,
+  Icon: SwitchIcon,
+});
+
+export type Switch = {
+  Props: ComponentProps<typeof SwitchRoot>;
+  RootProps: ComponentProps<typeof SwitchRoot>;
+  ContentProps: ComponentProps<typeof SwitchContent>;
+  ControlProps: ComponentProps<typeof SwitchControl>;
+  ThumbProps: ComponentProps<typeof SwitchThumb>;
+  IconProps: ComponentProps<typeof SwitchIcon>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {SwitchContent, SwitchControl, SwitchIcon, SwitchRoot, SwitchThumb};
+
+export type {
+  SwitchRootProps,
+  SwitchRootProps as SwitchProps,
+  SwitchContentProps,
+  SwitchControlProps,
+  SwitchThumbProps,
+  SwitchIconProps,
+  SwitchFieldRenderProps,
+  SwitchButtonRenderProps,
+  /** @deprecated Use {@link SwitchFieldRenderProps} for the root render prop, or {@link SwitchButtonRenderProps} for control. */
+  SwitchFieldRenderProps as SwitchRenderProps,
+} from "./switch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {switchVariants} from "@heroui/styles";
+
+export type {SwitchVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/switch/switch.stories.tsx b/packages/react/src/components/switch/switch.stories.tsx
new file mode 100644
index 0000000..68499bb
--- /dev/null
+++ b/packages/react/src/components/switch/switch.stories.tsx
@@ -0,0 +1,295 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+
+import {Switch} from "./index";
+
+export default {
+  argTypes: {},
+  component: Switch,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Controls/Switch",
+} as Meta<typeof Switch>;
+
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {
+  render: () => (
+    <Switch>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <Switch isDisabled>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const DefaultSelected: Story = {
+  render: () => (
+    <Switch defaultSelected>
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const DisabledDefaultSelected: Story = {
+  render: () => (
+    <Switch defaultSelected isDisabled aria-label="Enable notifications">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const Controlled: Story = {
+  render: function ControlledSwitch() {
+    const [isSelected, setIsSelected] = React.useState(false);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <Switch isSelected={isSelected} onChange={setIsSelected}>
+          <Switch.Content>
+            <Switch.Control>
+              <Switch.Thumb />
+            </Switch.Control>
+            Enable notifications
+          </Switch.Content>
+        </Switch>
+        <p className="text-sm text-muted">Switch is {isSelected ? "on" : "off"}</p>
+      </div>
+    );
+  },
+};
+
+export const WithoutLabel: Story = {
+  render: () => (
+    <Switch aria-label="Enable notifications">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <Switch isInvalid isRequired name="notifications">
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Enable notifications
+      </Switch.Content>
+      <FieldError>You must enable notifications to continue</FieldError>
+    </Switch>
+  ),
+};
+
+export const Validation: Story = {
+  render: () => (
+    <Switch
+      isRequired
+      name="terms-switch"
+      validate={(isSelected) => (isSelected ? true : "You must accept to continue")}
+    >
+      <Switch.Content>
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        Accept terms
+      </Switch.Content>
+      <FieldError />
+    </Switch>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex gap-6">
+      <Switch size="sm">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Small
+        </Switch.Content>
+      </Switch>
+      <Switch size="md">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Medium
+        </Switch.Content>
+      </Switch>
+      <Switch size="lg">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Large
+        </Switch.Content>
+      </Switch>
+    </div>
+  ),
+};
+
+export const LabelBefore: Story = {
+  render: () => (
+    <Switch>
+      <Switch.Content>
+        Enable notifications
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+      </Switch.Content>
+    </Switch>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="max-w-sm">
+      <Switch>
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          Public profile
+        </Switch.Content>
+        <Description>Allow others to see your profile information</Description>
+      </Switch>
+    </div>
+  ),
+};
+
+export const WithCustomStyles: Story = {
+  render: () => (
+    <Switch aria-label="Power">
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control
+            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
+          >
+            <Switch.Thumb
+              className={`size-[27px] bg-white shadow-sm ${isSelected ? "ms-[22px] shadow-lg" : ""}`}
+            >
+              <Switch.Icon>
+                <Icon
+                  className={`size-4 ${isSelected ? "text-cyan-600" : "text-blue-600"}`}
+                  icon={isSelected ? "gravity-ui:check" : "gravity-ui:power"}
+                />
+              </Switch.Icon>
+            </Switch.Thumb>
+          </Switch.Control>
+        </Switch.Content>
+      )}
+    </Switch>
+  ),
+};
+
+export const WithIcons: Story = {
+  render: () => {
+    const icons = {
+      lock: {
+        off: "gravity-ui:volume-fill",
+        on: "gravity-ui:volume-slash-fill",
+        selectedControlClass: "bg-blue-500",
+        selectedIconClass: "text-blue-600",
+      },
+      microphone: {
+        off: "gravity-ui:microphone",
+        on: "gravity-ui:microphone-slash",
+        selectedControlClass: "bg-red-500",
+        selectedIconClass: "text-red-600",
+      },
+      check: {
+        off: "gravity-ui:power",
+        on: "gravity-ui:check",
+        selectedControlClass: "bg-green-500",
+        selectedIconClass: "text-green-600",
+      },
+      darkMode: {
+        off: "gravity-ui:moon",
+        on: "gravity-ui:sun",
+        selectedControlClass: "",
+        selectedIconClass: "",
+      },
+      notification: {
+        off: "gravity-ui:bell-slash",
+        on: "gravity-ui:bell-fill",
+        selectedControlClass: "bg-purple-500",
+        selectedIconClass: "text-purple-600",
+      },
+    };
+
+    return (
+      <div className="flex gap-3">
+        {Object.entries(icons).map(([key, value]) => (
+          <Switch key={key} defaultSelected aria-label={key} size="lg">
+            {({isSelected}) => (
+              <Switch.Content>
+                <Switch.Control className={isSelected ? value.selectedControlClass : ""}>
+                  <Switch.Thumb>
+                    <Switch.Icon>
+                      <Icon
+                        className={`${isSelected ? `opacity-100 ${value.selectedIconClass}` : "opacity-70"} size-3 text-inherit`}
+                        icon={isSelected ? value.on : value.off}
+                      />
+                    </Switch.Icon>
+                  </Switch.Thumb>
+                </Switch.Control>
+              </Switch.Content>
+            )}
+          </Switch>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const RenderProps: Story = {
+  render: () => (
+    <Switch>
+      {({isSelected}) => (
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          {isSelected ? "Enabled" : "Disabled"}
+        </Switch.Content>
+      )}
+    </Switch>
+  ),
+};
diff --git a/packages/react/src/components/switch/switch.tsx b/packages/react/src/components/switch/switch.tsx
new file mode 100644
index 0000000..ddcde20
--- /dev/null
+++ b/packages/react/src/components/switch/switch.tsx
@@ -0,0 +1,171 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {SwitchVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+import type {SwitchButtonRenderProps, SwitchFieldRenderProps} from "react-aria-components/Switch";
+
+import {switchVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  SwitchButton as SwitchButtonPrimitive,
+  SwitchField as SwitchFieldPrimitive,
+} from "react-aria-components/Switch";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+
+interface SwitchContext {
+  slots?: ReturnType<typeof switchVariants>;
+  state?: SwitchFieldRenderProps;
+}
+
+const SwitchContext = createContext<SwitchContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Switch (Field) — React Aria `SwitchField`.
+ * -----------------------------------------------------------------------------------------------*/
+interface SwitchRootProps
+  extends ComponentPropsWithRef<typeof SwitchFieldPrimitive>, SwitchVariants {}
+
+const SwitchRoot = ({children, className, size, ...props}: SwitchRootProps) => {
+  const slots = React.useMemo(() => switchVariants({size}), [size]);
+
+  return (
+    <SwitchFieldPrimitive
+      data-slot="switch"
+      {...props}
+      className={composeTwRenderProps(className, slots.base())}
+    >
+      {(state) => (
+        <SwitchContext value={{slots, state}}>
+          {typeof children === "function" ? children(state) : children}
+        </SwitchContext>
+      )}
+    </SwitchFieldPrimitive>
+  );
+};
+
+SwitchRoot.displayName = "HeroUI.Switch";
+
+/* -------------------------------------------------------------------------------------------------
+ * Switch.Content — the clickable `SwitchButton` label wrapping the control + `Label`.
+ * Keep `Description`/`FieldError` as siblings of `Switch.Content`.
+ * -----------------------------------------------------------------------------------------------*/
+interface SwitchContentProps extends ComponentPropsWithRef<typeof SwitchButtonPrimitive> {}
+
+const SwitchContent = ({children, className, ...props}: SwitchContentProps) => {
+  const {slots} = use(SwitchContext);
+
+  return (
+    <SwitchButtonPrimitive
+      data-slot="switch-content"
+      {...props}
+      className={composeTwRenderProps(className, slots?.content())}
+    >
+      {children}
+    </SwitchButtonPrimitive>
+  );
+};
+
+SwitchContent.displayName = "HeroUI.Switch.Content";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface SwitchControlProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const SwitchControl = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: SwitchControlProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SwitchControlProps<E>>) => {
+  const {slots} = use(SwitchContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.control, className)}
+      data-slot="switch-control"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+SwitchControl.displayName = "HeroUI.Switch.Control";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface SwitchThumbProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const SwitchThumb = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: SwitchThumbProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SwitchThumbProps<E>>) => {
+  const {slots} = use(SwitchContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.thumb, className)}
+      data-slot="switch-thumb"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+SwitchThumb.displayName = "HeroUI.Switch.Thumb";
+
+/* -----------------------------------------------------------------------------------------------*/
+
+interface SwitchIconProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const SwitchIcon = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  children,
+  className,
+  ...props
+}: SwitchIconProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof SwitchIconProps<E>>) => {
+  const {slots} = use(SwitchContext);
+
+  return (
+    <dom.span
+      className={composeSlotClassName(slots?.icon, className)}
+      data-slot="switch-icon"
+      {...(props as any)}
+    >
+      {children}
+    </dom.span>
+  );
+};
+
+SwitchIcon.displayName = "HeroUI.Switch.Icon";
+
+/* ----------------------------------------------------------------------------------------------*/
+
+export {SwitchRoot, SwitchContent, SwitchControl, SwitchThumb, SwitchIcon};
+export type {
+  SwitchRootProps,
+  SwitchContentProps,
+  SwitchControlProps,
+  SwitchThumbProps,
+  SwitchIconProps,
+  SwitchFieldRenderProps,
+  SwitchButtonRenderProps,
+};
diff --git a/packages/react/src/components/table/index.ts b/packages/react/src/components/table/index.ts
new file mode 100644
index 0000000..a548086
--- /dev/null
+++ b/packages/react/src/components/table/index.ts
@@ -0,0 +1,105 @@
+import type {ComponentProps} from "react";
+
+import {
+  TableBody,
+  TableCell,
+  TableCollection,
+  TableColumn,
+  TableColumnResizer,
+  TableContent,
+  TableFooter,
+  TableHeader,
+  TableLoadMoreContent,
+  TableLoadMoreItem,
+  TableResizableContainer,
+  TableRoot,
+  TableRow,
+  TableScrollContainer,
+  TableSortableColumnHeader,
+} from "./table";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Table = Object.assign(TableRoot, {
+  Body: TableBody,
+  Cell: TableCell,
+  Collection: TableCollection,
+  Column: TableColumn,
+  ColumnResizer: TableColumnResizer,
+  Content: TableContent,
+  Footer: TableFooter,
+  Header: TableHeader,
+  LoadMore: TableLoadMoreItem,
+  LoadMoreContent: TableLoadMoreContent,
+  ResizableContainer: TableResizableContainer,
+  Root: TableRoot,
+  Row: TableRow,
+  ScrollContainer: TableScrollContainer,
+  SortableColumnHeader: TableSortableColumnHeader,
+});
+
+export type Table = {
+  Props: ComponentProps<typeof TableRoot>;
+  RootProps: ComponentProps<typeof TableRoot>;
+  ScrollContainerProps: ComponentProps<typeof TableScrollContainer>;
+  ContentProps: ComponentProps<typeof TableContent>;
+  HeaderProps: ComponentProps<typeof TableHeader>;
+  ColumnProps: ComponentProps<typeof TableColumn>;
+  ColumnResizerProps: ComponentProps<typeof TableColumnResizer>;
+  BodyProps: ComponentProps<typeof TableBody>;
+  RowProps: ComponentProps<typeof TableRow>;
+  CellProps: ComponentProps<typeof TableCell>;
+  FooterProps: ComponentProps<typeof TableFooter>;
+  LoadMoreProps: ComponentProps<typeof TableLoadMoreItem>;
+  LoadMoreContentProps: ComponentProps<typeof TableLoadMoreContent>;
+  ResizableContainerProps: ComponentProps<typeof TableResizableContainer>;
+  SortableColumnHeaderProps: ComponentProps<typeof TableSortableColumnHeader>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  TableRoot,
+  TableScrollContainer,
+  TableContent,
+  TableHeader,
+  TableColumn,
+  TableColumnResizer,
+  TableBody,
+  TableRow,
+  TableCell,
+  TableFooter,
+  TableCollection,
+  TableLoadMoreItem,
+  TableLoadMoreContent,
+  TableResizableContainer,
+  TableSortableColumnHeader,
+};
+
+export type {
+  TableRootProps,
+  TableRootProps as TableProps,
+  TableScrollContainerProps,
+  TableContentProps,
+  TableHeaderProps,
+  TableColumnProps,
+  TableColumnResizerProps,
+  TableBodyProps,
+  TableRowProps,
+  TableCellProps,
+  TableFooterProps,
+  TableLoadMoreItemProps,
+  TableLoadMoreContentProps,
+  TableResizableContainerProps,
+  TableSortableColumnHeaderProps,
+  TableSortDirection,
+} from "./table";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {tableVariants} from "@heroui/styles";
+
+export type {TableVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/table/table.stories.tsx b/packages/react/src/components/table/table.stories.tsx
new file mode 100644
index 0000000..0ebf6a6
--- /dev/null
+++ b/packages/react/src/components/table/table.stories.tsx
@@ -0,0 +1,905 @@
+import type {Meta, StoryObj} from "@storybook/react";
+import type {Selection, SortDescriptor} from "react-aria-components/Table";
+
+import {cn} from "@heroui/styles";
+import {Icon} from "@iconify/react";
+import React from "react";
+import {TableLayout, Virtualizer} from "react-aria-components/Virtualizer";
+
+import {Avatar} from "../avatar";
+import {Button} from "../button";
+import {Checkbox} from "../checkbox";
+import {Chip} from "../chip";
+import {EmptyState} from "../empty-state";
+import {Pagination} from "../pagination";
+import {Spinner} from "../spinner";
+
+import {Table} from "./index";
+
+export default {
+  component: Table,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Data Display/Table",
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["primary", "secondary"],
+    },
+  },
+} as Meta<typeof Table>;
+
+type Story = StoryObj<typeof Table>;
+
+/* -------------------------------------------------------------------------------------------------
+ * Sample Data
+ * -----------------------------------------------------------------------------------------------*/
+interface User {
+  id: number;
+  name: string;
+  image_url: string;
+  role: string;
+  status: "Active" | "Inactive" | "On Leave";
+  email: string;
+}
+
+const users: User[] = [
+  {
+    email: "kate@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    id: 4586932,
+    name: "Kate Moore",
+    role: "Chief Executive Officer",
+    status: "Active",
+  },
+  {
+    email: "john@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    id: 5273849,
+    name: "John Smith",
+    role: "Chief Technology Officer",
+    status: "Active",
+  },
+  {
+    email: "sara@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    id: 7492836,
+    name: "Sara Johnson",
+    role: "Chief Marketing Officer",
+    status: "On Leave",
+  },
+  {
+    email: "michael@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    id: 8293746,
+    name: "Michael Brown",
+    role: "Chief Financial Officer",
+    status: "Active",
+  },
+  {
+    email: "emily@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    id: 1234567,
+    name: "Emily Davis",
+    role: "Product Manager",
+    status: "Inactive",
+  },
+  {
+    email: "davis@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+    id: 9876543,
+    name: "Davis Wilson",
+    role: "Lead Designer",
+    status: "Active",
+  },
+  {
+    email: "olivia@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    id: 3456789,
+    name: "Olivia Martinez",
+    role: "Frontend Engineer",
+    status: "Active",
+  },
+  {
+    email: "james@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    id: 4567890,
+    name: "James Taylor",
+    role: "Backend Engineer",
+    status: "Active",
+  },
+  {
+    email: "sophia@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    id: 5678901,
+    name: "Sophia Anderson",
+    role: "QA Engineer",
+    status: "On Leave",
+  },
+  {
+    email: "liam@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    id: 6789012,
+    name: "Liam Thomas",
+    role: "DevOps Engineer",
+    status: "Active",
+  },
+  {
+    email: "ava@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    id: 7890123,
+    name: "Ava Jackson",
+    role: "Data Analyst",
+    status: "Inactive",
+  },
+  {
+    email: "noah@acme.com",
+    image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+    id: 8901234,
+    name: "Noah White",
+    role: "Security Engineer",
+    status: "Active",
+  },
+];
+
+const columns = [
+  {id: "name", isRowHeader: true, name: "Name"},
+  {id: "role", name: "Role"},
+  {id: "status", name: "Status"},
+  {id: "email", name: "Email"},
+];
+
+/* -------------------------------------------------------------------------------------------------
+ * Wrapper
+ * -----------------------------------------------------------------------------------------------*/
+const Wrapper = ({children}: {children: React.ReactNode}) => (
+  <div className="w-full max-w-4xl">{children}</div>
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Pagination Helpers
+ * -----------------------------------------------------------------------------------------------*/
+const ROWS_PER_PAGE = 4;
+
+function usePagination<T>(items: T[], rowsPerPage = ROWS_PER_PAGE) {
+  const [page, setPage] = React.useState(1);
+  const totalPages = Math.ceil(items.length / rowsPerPage);
+
+  const paginatedItems = React.useMemo(() => {
+    const start = (page - 1) * rowsPerPage;
+
+    return items.slice(start, start + rowsPerPage);
+  }, [items, page, rowsPerPage]);
+
+  const start = (page - 1) * rowsPerPage + 1;
+  const end = Math.min(page * rowsPerPage, items.length);
+
+  return {end, page, paginatedItems, setPage, start, total: items.length, totalPages};
+}
+
+function TablePaginationFooter({pagination}: {pagination: ReturnType<typeof usePagination>}) {
+  const {end, page, setPage, start, total, totalPages} = pagination;
+  const pages = Array.from({length: totalPages}, (_, i) => i + 1);
+
+  return (
+    <Pagination size="sm">
+      <Pagination.Summary>
+        {start} to {end} of {total} results
+      </Pagination.Summary>
+      <Pagination.Content>
+        <Pagination.Item>
+          <Pagination.Previous
+            isDisabled={page === 1}
+            onPress={() => setPage((p) => Math.max(1, p - 1))}
+          >
+            <Pagination.PreviousIcon />
+            Prev
+          </Pagination.Previous>
+        </Pagination.Item>
+        {pages.map((p) => (
+          <Pagination.Item key={p}>
+            <Pagination.Link isActive={p === page} onPress={() => setPage(p)}>
+              {p}
+            </Pagination.Link>
+          </Pagination.Item>
+        ))}
+        <Pagination.Item>
+          <Pagination.Next
+            isDisabled={page === totalPages}
+            onPress={() => setPage((p) => Math.min(totalPages, p + 1))}
+          >
+            Next
+            <Pagination.NextIcon />
+          </Pagination.Next>
+        </Pagination.Item>
+      </Pagination.Content>
+    </Pagination>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Stories
+ * -----------------------------------------------------------------------------------------------*/
+
+const statusColorMap: Record<string, "success" | "danger" | "warning"> = {
+  Active: "success",
+  Inactive: "danger",
+  "On Leave": "warning",
+};
+
+/**
+ * Shared template for Default and SecondaryVariant stories.
+ */
+function DefaultTableTemplate({variant = "primary"}: {variant?: "primary" | "secondary"}) {
+  const [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set());
+  const [sortDescriptor, setSortDescriptor] = React.useState<SortDescriptor>({
+    column: "name",
+    direction: "ascending",
+  });
+
+  const sortedUsers = React.useMemo(() => {
+    return [...users].sort((a, b) => {
+      const col = sortDescriptor.column as keyof User;
+      const first = String(a[col]);
+      const second = String(b[col]);
+      let cmp = first.localeCompare(second);
+
+      if (sortDescriptor.direction === "descending") {
+        cmp *= -1;
+      }
+
+      return cmp;
+    });
+  }, [sortDescriptor]);
+
+  const pagination = usePagination(sortedUsers);
+
+  return (
+    <Wrapper>
+      <Table variant={variant}>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="Custom cells"
+            className="min-w-[800px]"
+            selectedKeys={selectedKeys}
+            selectionMode="multiple"
+            sortDescriptor={sortDescriptor}
+            onSelectionChange={setSelectedKeys}
+            onSortChange={setSortDescriptor}
+          >
+            <Table.Header>
+              <Table.Column className="pr-0">
+                <Checkbox aria-label="Select all" slot="selection">
+                  <Checkbox.Content>
+                    <Checkbox.Control>
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                  </Checkbox.Content>
+                </Checkbox>
+              </Table.Column>
+              <Table.Column allowsSorting isRowHeader className="after:hidden" id="id">
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    Worker ID
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+              <Table.Column allowsSorting id="name">
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    Member
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+              <Table.Column allowsSorting id="role">
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    Role
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+              <Table.Column allowsSorting id="status">
+                {({sortDirection}) => (
+                  <Table.SortableColumnHeader sortDirection={sortDirection}>
+                    Status
+                  </Table.SortableColumnHeader>
+                )}
+              </Table.Column>
+              <Table.Column className="text-end">Actions</Table.Column>
+            </Table.Header>
+            <Table.Body>
+              {pagination.paginatedItems.map((user) => (
+                <Table.Row key={user.id} id={user.id}>
+                  <Table.Cell className="pr-0">
+                    <Checkbox
+                      aria-label={`Select ${user.name}`}
+                      slot="selection"
+                      variant="secondary"
+                    >
+                      <Checkbox.Content>
+                        <Checkbox.Control>
+                          <Checkbox.Indicator />
+                        </Checkbox.Control>
+                      </Checkbox.Content>
+                    </Checkbox>
+                  </Table.Cell>
+                  <Table.Cell className="font-medium">
+                    <div className="flex items-center gap-2">
+                      #{user.id.toString()}{" "}
+                      <Button isIconOnly size="sm" variant="ghost">
+                        <Icon className="size-4 text-muted" icon="gravity-ui:copy" />
+                      </Button>
+                    </div>
+                  </Table.Cell>
+                  <Table.Cell>
+                    <div className="flex items-center gap-3">
+                      <Avatar size="sm">
+                        <Avatar.Image src={user.image_url} />
+                        <Avatar.Fallback>
+                          {user.name
+                            .split(" ")
+                            .map((n) => n[0])
+                            .join("")}
+                        </Avatar.Fallback>
+                      </Avatar>
+                      <div className="flex flex-col">
+                        <span className="text-xs">{user.name}</span>
+                        <span className="text-xs text-muted">{user.email}</span>
+                      </div>
+                    </div>
+                  </Table.Cell>
+                  <Table.Cell className="min-w-52">{user.role}</Table.Cell>
+                  <Table.Cell className="min-w-25">
+                    <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                      {user.status}
+                    </Chip>
+                  </Table.Cell>
+                  <Table.Cell>
+                    <div className="flex items-center gap-1">
+                      <Button isIconOnly size="sm" variant="tertiary">
+                        <Icon className="size-4" icon="gravity-ui:eye" />
+                      </Button>
+                      <Button isIconOnly size="sm" variant="tertiary">
+                        <Icon className="size-4" icon="gravity-ui:pencil" />
+                      </Button>
+                      <Button isIconOnly size="sm" variant="danger-soft">
+                        <Icon className="size-4" icon="gravity-ui:trash-bin" />
+                      </Button>
+                    </div>
+                  </Table.Cell>
+                </Table.Row>
+              ))}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+        <Table.Footer>
+          <TablePaginationFooter pagination={pagination} />
+        </Table.Footer>
+      </Table>
+    </Wrapper>
+  );
+}
+
+/**
+ * Default table with custom cells: avatars, chips, action buttons, and sortable columns.
+ */
+export const Default: Story = {
+  args: {
+    variant: "primary",
+  },
+  render: ({variant}) => <DefaultTableTemplate variant={variant} />,
+};
+
+/**
+ * Secondary variant: same content as Default with secondary styling.
+ */
+export const SecondaryVariant: Story = {
+  render: () => <DefaultTableTemplate variant="secondary" />,
+};
+
+/**
+ * Empty state via user-provided renderEmptyState.
+ */
+export const EmptyStateDemo: Story = {
+  args: {
+    variant: "primary",
+  },
+  render: ({variant}) => (
+    <Wrapper>
+      <Table className="min-h-[200px] min-w-[600px]" variant={variant}>
+        <Table.ScrollContainer>
+          <Table.Content aria-label="Empty state" className="h-full">
+            <Table.Header>
+              {columns.map((col) => (
+                <Table.Column key={col.id} id={col.id} isRowHeader={col.isRowHeader}>
+                  {col.name}
+                </Table.Column>
+              ))}
+            </Table.Header>
+            <Table.Body
+              renderEmptyState={() => (
+                <EmptyState className="flex h-full w-full flex-col items-center justify-center gap-4 text-center">
+                  <Icon className="size-6 text-muted" icon="gravity-ui:tray" />
+                  <span className="text-sm text-muted">No results found</span>
+                </EmptyState>
+              )}
+            >
+              {[]}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+      </Table>
+    </Wrapper>
+  ),
+};
+
+/**
+ * Dynamic collection with items prop.
+ * Uses Table.Collection to render dynamic cells within rows,
+ * which also allows placing static cells (e.g. checkbox) before the dynamic ones.
+ */
+export const DynamicCollection: Story = {
+  render: () => {
+    const pagination = usePagination(users);
+
+    return (
+      <Wrapper>
+        <Table>
+          <Table.ScrollContainer>
+            <Table.Content aria-label="Dynamic collection" className="min-w-[600px]">
+              <Table.Header columns={columns}>
+                {(column) => (
+                  <Table.Column isRowHeader={column.isRowHeader}>{column.name}</Table.Column>
+                )}
+              </Table.Header>
+              <Table.Body items={pagination.paginatedItems}>
+                {(user) => (
+                  <Table.Row>
+                    <Table.Collection items={columns}>
+                      {(column) => <Table.Cell>{user[column.id as keyof User]}</Table.Cell>}
+                    </Table.Collection>
+                  </Table.Row>
+                )}
+              </Table.Body>
+            </Table.Content>
+          </Table.ScrollContainer>
+          <Table.Footer>
+            <TablePaginationFooter pagination={pagination} />
+          </Table.Footer>
+        </Table>
+      </Wrapper>
+    );
+  },
+};
+
+/**
+ * Dynamic collection with selection — shows how Table.Collection lets you
+ * add static cells (checkbox) alongside dynamic column-based cells.
+ */
+const DynamicWithSelectionTemplate = () => {
+  const [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set());
+  const pagination = usePagination(users);
+
+  return (
+    <Wrapper>
+      <Table>
+        <Table.ScrollContainer>
+          <Table.Content
+            aria-label="Dynamic with selection"
+            className="min-w-[650px]"
+            selectedKeys={selectedKeys}
+            selectionMode="multiple"
+            onSelectionChange={setSelectedKeys}
+          >
+            <Table.Header>
+              <Table.Column>
+                <Checkbox aria-label="Select all" slot="selection">
+                  <Checkbox.Content>
+                    <Checkbox.Control>
+                      <Checkbox.Indicator />
+                    </Checkbox.Control>
+                  </Checkbox.Content>
+                </Checkbox>
+              </Table.Column>
+              <Table.Collection items={columns}>
+                {(column) => (
+                  <Table.Column isRowHeader={column.isRowHeader}>{column.name}</Table.Column>
+                )}
+              </Table.Collection>
+            </Table.Header>
+            <Table.Body items={pagination.paginatedItems}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>
+                    <Checkbox
+                      aria-label={`Select ${user.name}`}
+                      slot="selection"
+                      variant="secondary"
+                    >
+                      <Checkbox.Content>
+                        <Checkbox.Control>
+                          <Checkbox.Indicator />
+                        </Checkbox.Control>
+                      </Checkbox.Content>
+                    </Checkbox>
+                  </Table.Cell>
+                  <Table.Collection items={columns}>
+                    {(column) => <Table.Cell>{user[column.id]}</Table.Cell>}
+                  </Table.Collection>
+                </Table.Row>
+              )}
+            </Table.Body>
+          </Table.Content>
+        </Table.ScrollContainer>
+        <Table.Footer>
+          <TablePaginationFooter pagination={pagination} />
+        </Table.Footer>
+      </Table>
+    </Wrapper>
+  );
+};
+
+export const DynamicWithSelection: Story = {
+  render: () => <DynamicWithSelectionTemplate />,
+};
+
+/**
+ * Column resizing with drag handles between columns.
+ */
+export const ColumnResizing: Story = {
+  render: () => (
+    <Wrapper>
+      <Table>
+        <Table.ResizableContainer>
+          <Table.Content aria-label="Column resizing" className="min-w-[700px]">
+            <Table.Header>
+              <Table.Column isRowHeader defaultWidth="1fr" id="name" minWidth={160}>
+                Name
+                <Table.ColumnResizer />
+              </Table.Column>
+              <Table.Column defaultWidth="1fr" id="role" minWidth={220}>
+                Role
+                <Table.ColumnResizer />
+              </Table.Column>
+              <Table.Column defaultWidth="1fr" id="status" minWidth={100}>
+                Status
+                <Table.ColumnResizer />
+              </Table.Column>
+              <Table.Column defaultWidth="1fr" id="email" minWidth={200}>
+                Email
+              </Table.Column>
+            </Table.Header>
+            <Table.Body items={users}>
+              {(user) => (
+                <Table.Row>
+                  <Table.Cell>{user.name}</Table.Cell>
+                  <Table.Cell>{user.role}</Table.Cell>
+                  <Table.Cell>
+                    <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                      {user.status}
+                    </Chip>
+                  </Table.Cell>
+                  <Table.Cell>{user.email}</Table.Cell>
+                </Table.Row>
+              )}
+            </Table.Body>
+          </Table.Content>
+        </Table.ResizableContainer>
+      </Table>
+    </Wrapper>
+  ),
+};
+
+/**
+ * Async loading with infinite scroll using Table.LoadMore.
+ * Simulates fetching paginated data — scroll to the bottom to load more rows.
+ */
+const ITEMS_PER_PAGE = 6;
+
+function useAsyncUsers() {
+  const [items, setItems] = React.useState<User[]>(() => users.slice(0, ITEMS_PER_PAGE));
+  const [isLoading, setIsLoading] = React.useState(false);
+  const isLoadingRef = React.useRef(false);
+  const hasMore = items.length < users.length;
+
+  const loadMore = React.useCallback(() => {
+    if (!hasMore || isLoadingRef.current) return;
+    isLoadingRef.current = true;
+    setIsLoading(true);
+    // Simulate network delay
+    setTimeout(() => {
+      setItems((prev) => users.slice(0, prev.length + ITEMS_PER_PAGE));
+      setIsLoading(false);
+      requestAnimationFrame(() => {
+        isLoadingRef.current = false;
+      });
+    }, 1500);
+  }, [hasMore]);
+
+  return {hasMore, isLoading, items, loadMore};
+}
+
+export const AsyncLoading: Story = {
+  args: {
+    variant: "primary",
+  },
+  render: ({variant}) => {
+    const {hasMore, isLoading, items, loadMore} = useAsyncUsers();
+
+    return (
+      <Wrapper>
+        <Table variant={variant}>
+          <Table.ScrollContainer className="h-[280px] overflow-y-auto">
+            <Table.Content aria-label="Async loading" className="min-w-[600px]">
+              <Table.Header className="sticky top-0 z-10 bg-surface-secondary">
+                {columns.map((col) => (
+                  <Table.Column key={col.id} id={col.id} isRowHeader={col.isRowHeader}>
+                    {col.name}
+                  </Table.Column>
+                ))}
+              </Table.Header>
+              <Table.Body>
+                <Table.Collection items={items}>
+                  {(user) => (
+                    <Table.Row>
+                      <Table.Cell>{user.name}</Table.Cell>
+                      <Table.Cell>{user.role}</Table.Cell>
+                      <Table.Cell>
+                        <Chip color={statusColorMap[user.status]} size="sm" variant="soft">
+                          {user.status}
+                        </Chip>
+                      </Table.Cell>
+                      <Table.Cell>{user.email}</Table.Cell>
+                    </Table.Row>
+                  )}
+                </Table.Collection>
+                {!!hasMore && (
+                  <Table.LoadMore isLoading={isLoading} scrollOffset={0} onLoadMore={loadMore}>
+                    <Table.LoadMoreContent>
+                      <Spinner size="md" />
+                    </Table.LoadMoreContent>
+                  </Table.LoadMore>
+                )}
+              </Table.Body>
+            </Table.Content>
+          </Table.ScrollContainer>
+        </Table>
+      </Wrapper>
+    );
+  },
+};
+
+export const Virtualization: Story = {
+  render: () => {
+    const roles = [
+      "Software Engineer",
+      "Senior Engineer",
+      "Staff Engineer",
+      "Product Manager",
+      "Designer",
+      "Data Analyst",
+      "QA Engineer",
+      "DevOps Engineer",
+      "Marketing Manager",
+      "Sales Representative",
+    ];
+
+    const statuses: User["status"][] = ["Active", "Inactive", "On Leave"];
+
+    const firstNames = [
+      "Emma",
+      "Liam",
+      "Olivia",
+      "Noah",
+      "Ava",
+      "James",
+      "Sophia",
+      "Oliver",
+      "Isabella",
+      "Lucas",
+      "Mia",
+      "Ethan",
+      "Charlotte",
+      "Mason",
+      "Amelia",
+      "Logan",
+      "Harper",
+      "Alexander",
+      "Ella",
+      "Benjamin",
+    ];
+
+    const lastNames = [
+      "Smith",
+      "Johnson",
+      "Williams",
+      "Brown",
+      "Jones",
+      "Garcia",
+      "Miller",
+      "Davis",
+      "Rodriguez",
+      "Martinez",
+      "Anderson",
+      "Taylor",
+      "Thomas",
+      "Jackson",
+      "White",
+      "Harris",
+      "Clark",
+      "Lewis",
+      "Robinson",
+      "Walker",
+    ];
+
+    function generateUsers(n: number): User[] {
+      const users: User[] = [];
+
+      for (let i = 0; i < n; i++) {
+        const firstName = firstNames[i % firstNames.length];
+        const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
+        const name = `${firstName} ${lastName}`;
+
+        users.push({
+          id: i + 1,
+          name,
+          image_url: `https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg`,
+          role: roles[i % roles.length],
+          status: statuses[i % statuses.length],
+          email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
+        });
+      }
+
+      return users;
+    }
+
+    const virtualizedUsers = generateUsers(1000);
+
+    return (
+      <Virtualizer
+        layout={TableLayout}
+        layoutOptions={{
+          rowHeight: 42,
+          headingHeight: 42,
+        }}
+      >
+        <Table>
+          <Table.ScrollContainer>
+            <Table.Content
+              aria-label="Virtualized table with 1000 rows"
+              className="h-[500px] min-w-[700px] overflow-auto scrollbar"
+            >
+              <Table.Header className="h-full w-full">
+                <Table.Column isRowHeader id="name" minWidth={160}>
+                  Name
+                </Table.Column>
+                <Table.Column id="role" minWidth={220}>
+                  Role
+                </Table.Column>
+                <Table.Column id="email" minWidth={240}>
+                  Email
+                </Table.Column>
+              </Table.Header>
+              <Table.Body items={virtualizedUsers}>
+                {(user) => (
+                  <Table.Row>
+                    <Table.Cell>{user.name}</Table.Cell>
+                    <Table.Cell>{user.role}</Table.Cell>
+                    <Table.Cell>{user.email}</Table.Cell>
+                  </Table.Row>
+                )}
+              </Table.Body>
+            </Table.Content>
+          </Table.ScrollContainer>
+        </Table>
+      </Virtualizer>
+    );
+  },
+};
+
+export const ExpandableRows: Story = {
+  render: () => {
+    type Row = {
+      children: Row[];
+      date: string;
+      id: string;
+      title: string;
+      type: string;
+    };
+
+    const data: Row[] = [
+      {
+        children: [
+          {
+            children: [
+              {children: [], date: "7/10/2025", id: "3", title: "Weekly Report", type: "File"},
+              {children: [], date: "8/20/2025", id: "4", title: "Budget", type: "File"},
+            ],
+            date: "8/2/2025",
+            id: "2",
+            title: "Project",
+            type: "Directory",
+          },
+        ],
+        date: "10/20/2025",
+        id: "1",
+        title: "Documents",
+        type: "Directory",
+      },
+      {
+        children: [
+          {children: [], date: "1/23/2026", id: "6", title: "Image 1", type: "File"},
+          {children: [], date: "2/3/2026", id: "7", title: "Image 2", type: "File"},
+        ],
+        date: "2/3/2026",
+        id: "5",
+        title: "Photos",
+        type: "Directory",
+      },
+    ];
+
+    const [expandedKeys, setExpandedKeys] = React.useState<Selection>(() => new Set(["1"]));
+
+    const renderExpandableRow = (item: Row) => {
+      return (
+        <Table.Row id={item.id} textValue={item.title}>
+          <Table.Cell textValue={item.title}>
+            {({hasChildItems, isDisabled, isExpanded, isTreeColumn}) => (
+              <span className="flex items-center gap-1">
+                {hasChildItems && isTreeColumn ? (
+                  <Button
+                    isIconOnly
+                    aria-label="Toggle row"
+                    isDisabled={isDisabled}
+                    size="sm"
+                    slot="chevron"
+                    variant="ghost"
+                  >
+                    <Icon
+                      aria-hidden
+                      icon="gravity-ui:chevron-right"
+                      className={cn(
+                        "size-4 text-muted transition-transform duration-150",
+                        isExpanded ? "rotate-90" : "",
+                      )}
+                    />
+                  </Button>
+                ) : null}
+                <span>{item.title}</span>
+              </span>
+            )}
+          </Table.Cell>
+          <Table.Cell>{item.type}</Table.Cell>
+          <Table.Cell>{item.date}</Table.Cell>
+          <Table.Collection items={item.children}>{renderExpandableRow}</Table.Collection>
+        </Table.Row>
+      );
+    };
+
+    return (
+      <Wrapper>
+        <Table>
+          <Table.ScrollContainer>
+            <Table.Content
+              aria-label="Files"
+              className="min-w-[520px]"
+              expandedKeys={expandedKeys}
+              treeColumn="name"
+              onExpandedChange={setExpandedKeys}
+            >
+              <Table.Header>
+                <Table.Column isRowHeader id="name">
+                  Name
+                </Table.Column>
+                <Table.Column id="type">Type</Table.Column>
+                <Table.Column id="date">Date Modified</Table.Column>
+              </Table.Header>
+              <Table.Body items={data}>{renderExpandableRow}</Table.Body>
+            </Table.Content>
+          </Table.ScrollContainer>
+        </Table>
+      </Wrapper>
+    );
+  },
+};
diff --git a/packages/react/src/components/table/table.tsx b/packages/react/src/components/table/table.tsx
new file mode 100644
index 0000000..0275012
--- /dev/null
+++ b/packages/react/src/components/table/table.tsx
@@ -0,0 +1,462 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {TableVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {tableVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {
+  Cell as CellPrimitive,
+  Collection as CollectionPrimitive,
+  Column as ColumnPrimitive,
+  ColumnResizer as ColumnResizerPrimitive,
+  ResizableTableContainer as ResizableTableContainerPrimitive,
+  Row as RowPrimitive,
+  TableBody as TableBodyPrimitive,
+  TableHeader as TableHeaderPrimitive,
+  TableLoadMoreItem as TableLoadMoreItemPrimitive,
+  Table as TablePrimitive,
+} from "react-aria-components/Table";
+import {cx} from "tailwind-variants";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronUp} from "../icons";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Context
+ * -----------------------------------------------------------------------------------------------*/
+const TableContext = createContext<{
+  slots?: ReturnType<typeof tableVariants>;
+}>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TableRootProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  /** Visual variant. */
+  variant?: TableVariants["variant"];
+}
+
+const TableRoot = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  variant,
+  ...props
+}: TableRootProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof TableRootProps<E>>) => {
+  const slots = React.useMemo(() => tableVariants({variant}), [variant]);
+
+  return (
+    <TableContext value={{slots}}>
+      <dom.div className={slots.base({className})} data-slot="table" {...(props as any)}>
+        {children}
+      </dom.div>
+    </TableContext>
+  );
+};
+
+TableRoot.displayName = "HeroUI.Table";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Scroll Container
+ * -----------------------------------------------------------------------------------------------*/
+interface TableScrollContainerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const TableScrollContainer = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: TableScrollContainerProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof TableScrollContainerProps<E>>) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.scrollContainer, className)}
+      data-slot="table-scroll-container"
+      {...(props as any)}
+    />
+  );
+};
+
+TableScrollContainer.displayName = "HeroUI.Table.ScrollContainer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Content
+ * -----------------------------------------------------------------------------------------------*/
+interface TableContentProps extends Omit<
+  ComponentPropsWithRef<typeof TablePrimitive>,
+  "className"
+> {
+  className?: string;
+}
+
+function TableContent({className, ...props}: TableContentProps) {
+  const {slots} = use(TableContext);
+
+  return (
+    <TablePrimitive
+      className={composeTwRenderProps(className, slots?.content())}
+      data-slot="table-content"
+      {...props}
+    />
+  );
+}
+
+(TableContent as React.FC).displayName = "HeroUI.Table.Content";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Header
+ * -----------------------------------------------------------------------------------------------*/
+interface TableHeaderProps<T extends object> extends ComponentPropsWithRef<
+  typeof TableHeaderPrimitive<T>
+> {}
+
+function TableHeader<T extends object>({className, ...props}: TableHeaderProps<T>) {
+  const {slots} = use(TableContext);
+
+  return (
+    <TableHeaderPrimitive
+      className={composeTwRenderProps(className, slots?.header())}
+      data-slot="table-header"
+      {...props}
+    />
+  );
+}
+
+(TableHeader as React.FC).displayName = "HeroUI.Table.Header";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Column
+ * -----------------------------------------------------------------------------------------------*/
+interface TableColumnProps extends ComponentPropsWithRef<typeof ColumnPrimitive> {}
+
+const TableColumn = ({className, ref, ...props}: TableColumnProps) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <ColumnPrimitive
+      ref={ref}
+      className={composeTwRenderProps(className, slots?.column())}
+      data-slot="table-column"
+      {...props}
+    />
+  );
+};
+
+TableColumn.displayName = "HeroUI.Table.Column";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Body
+ * -----------------------------------------------------------------------------------------------*/
+interface TableBodyProps<T extends object> extends ComponentPropsWithRef<
+  typeof TableBodyPrimitive<T>
+> {}
+
+function TableBody<T extends object>({className, ...props}: TableBodyProps<T>) {
+  const {slots} = use(TableContext);
+
+  return (
+    <TableBodyPrimitive
+      className={composeTwRenderProps(className, slots?.body())}
+      data-slot="table-body"
+      {...props}
+    />
+  );
+}
+
+(TableBody as React.FC).displayName = "HeroUI.Table.Body";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Row
+ * -----------------------------------------------------------------------------------------------*/
+interface TableRowProps<T extends object> extends ComponentPropsWithRef<typeof RowPrimitive<T>> {}
+
+function TableRow<T extends object>({className, ...props}: TableRowProps<T>) {
+  const {slots} = use(TableContext);
+
+  return (
+    <RowPrimitive
+      className={composeTwRenderProps(className, slots?.row())}
+      data-slot="table-row"
+      {...props}
+    />
+  );
+}
+
+(TableRow as React.FC).displayName = "HeroUI.Table.Row";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Cell
+ * -----------------------------------------------------------------------------------------------*/
+interface TableCellProps extends ComponentPropsWithRef<typeof CellPrimitive> {}
+
+const TableCell = ({className, ref, ...props}: TableCellProps) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <CellPrimitive
+      ref={ref}
+      className={composeTwRenderProps(className, slots?.cell())}
+      data-slot="table-cell"
+      {...props}
+    />
+  );
+};
+
+TableCell.displayName = "HeroUI.Table.Cell";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Footer
+ * -----------------------------------------------------------------------------------------------*/
+interface TableFooterProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const TableFooter = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: TableFooterProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof TableFooterProps<E>>) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.footer, className)}
+      data-slot="table-footer"
+      {...(props as any)}
+    />
+  );
+};
+
+TableFooter.displayName = "HeroUI.Table.Footer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Resizable Container
+ * -----------------------------------------------------------------------------------------------*/
+interface TableResizableContainerProps extends ComponentPropsWithRef<
+  typeof ResizableTableContainerPrimitive
+> {}
+
+const TableResizableContainer = ({className, ref, ...props}: TableResizableContainerProps) => {
+  return (
+    <ResizableTableContainerPrimitive
+      ref={ref}
+      className={cx("table__resizable-container", className)}
+      data-slot="table-resizable-container"
+      {...props}
+    />
+  );
+};
+
+TableResizableContainer.displayName = "HeroUI.Table.ResizableContainer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Column Resizer
+ * -----------------------------------------------------------------------------------------------*/
+interface TableColumnResizerProps extends ComponentPropsWithRef<typeof ColumnResizerPrimitive> {}
+
+const TableColumnResizer = ({className, ref, ...props}: TableColumnResizerProps) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <ColumnResizerPrimitive
+      ref={ref}
+      className={composeTwRenderProps(className, slots?.columnResizer())}
+      data-slot="table-column-resizer"
+      {...props}
+    />
+  );
+};
+
+TableColumnResizer.displayName = "HeroUI.Table.ColumnResizer";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Load More Item
+ * -----------------------------------------------------------------------------------------------*/
+interface TableLoadMoreItemProps extends ComponentPropsWithRef<typeof TableLoadMoreItemPrimitive> {}
+
+const TableLoadMoreItem = ({className, ref, ...props}: TableLoadMoreItemProps) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <TableLoadMoreItemPrimitive
+      ref={ref}
+      className={composeSlotClassName(slots?.loadMore, className)}
+      data-slot="table-load-more"
+      {...props}
+    />
+  );
+};
+
+TableLoadMoreItem.displayName = "HeroUI.Table.LoadMore";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Load More Content
+ * -----------------------------------------------------------------------------------------------*/
+interface TableLoadMoreContentProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const TableLoadMoreContent = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  className,
+  ...props
+}: TableLoadMoreContentProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof TableLoadMoreContentProps<E>>) => {
+  const {slots} = use(TableContext);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.loadMoreContent, className)}
+      data-slot="table-load-more-content"
+      {...(props as any)}
+    />
+  );
+};
+
+TableLoadMoreContent.displayName = "HeroUI.Table.LoadMoreContent";
+
+/* -------------------------------------------------------------------------------------------------
+ * Table Sortable Column Header
+ * -----------------------------------------------------------------------------------------------*/
+type TableSortDirection = "ascending" | "descending";
+
+interface TableSortableColumnHeaderProps extends Omit<
+  React.ComponentPropsWithRef<"span">,
+  "children"
+> {
+  /** Label content of the column header. */
+  children?: ReactNode;
+  /**
+   * Current sort direction for the column. Pass the `sortDirection` value
+   * received from `Table.Column`'s render-prop callback.
+   */
+  sortDirection?: TableSortDirection;
+  /**
+   * Whether to render the sort indicator icon when a direction is set.
+   * @default true
+   */
+  showIndicator?: boolean;
+  /**
+   * Custom indicator element. When provided, overrides the default chevron.
+   * The indicator receives a `data-direction` attribute reflecting the
+   * current sort direction.
+   */
+  indicator?: ReactNode;
+}
+
+const TableSortableColumnHeader = ({
+  children,
+  className,
+  indicator,
+  ref,
+  showIndicator = true,
+  sortDirection,
+  ...props
+}: TableSortableColumnHeaderProps) => {
+  const {slots} = use(TableContext);
+
+  const shouldRenderIndicator = showIndicator && !!sortDirection;
+
+  let indicatorElement: ReactNode = null;
+
+  if (shouldRenderIndicator) {
+    if (indicator === undefined) {
+      indicatorElement = (
+        <IconChevronUp
+          className={slots?.sortableColumnIndicator()}
+          data-direction={sortDirection}
+          data-slot="table-sortable-column-indicator"
+        />
+      );
+    } else if (React.isValidElement(indicator)) {
+      const element = indicator as React.ReactElement<{
+        className?: string;
+        "data-direction"?: TableSortDirection;
+        "data-slot"?: "table-sortable-column-indicator";
+      }>;
+
+      indicatorElement = React.cloneElement(element, {
+        className: composeSlotClassName(slots?.sortableColumnIndicator, element.props.className),
+        "data-direction": sortDirection,
+        "data-slot": "table-sortable-column-indicator",
+      });
+    } else {
+      indicatorElement = indicator;
+    }
+  }
+
+  return (
+    <span
+      ref={ref}
+      className={composeSlotClassName(slots?.sortableColumnHeader, className)}
+      data-direction={sortDirection}
+      data-slot="table-sortable-column-header"
+      {...props}
+    >
+      {children}
+      {indicatorElement}
+    </span>
+  );
+};
+
+TableSortableColumnHeader.displayName = "HeroUI.Table.SortableColumnHeader";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+// Re-export Collection from React Aria for dynamic cell rendering within rows.
+// Users wrap their dynamic cells in <Table.Collection items={columns}> when they
+// need to render additional static cells (e.g. checkbox, drag handle) alongside
+// dynamic column-based cells.
+const TableCollection = CollectionPrimitive;
+
+export {
+  TableRoot,
+  TableScrollContainer,
+  TableContent,
+  TableHeader,
+  TableColumn,
+  TableColumnResizer,
+  TableBody,
+  TableRow,
+  TableCell,
+  TableFooter,
+  TableCollection,
+  TableLoadMoreItem,
+  TableLoadMoreContent,
+  TableResizableContainer,
+  TableSortableColumnHeader,
+};
+
+export type {
+  TableRootProps,
+  TableScrollContainerProps,
+  TableContentProps,
+  TableHeaderProps,
+  TableColumnProps,
+  TableColumnResizerProps,
+  TableBodyProps,
+  TableRowProps,
+  TableCellProps,
+  TableFooterProps,
+  TableLoadMoreItemProps,
+  TableLoadMoreContentProps,
+  TableResizableContainerProps,
+  TableSortableColumnHeaderProps,
+  TableSortDirection,
+};
diff --git a/packages/react/src/components/tabs/index.ts b/packages/react/src/components/tabs/index.ts
new file mode 100644
index 0000000..ad48cea
--- /dev/null
+++ b/packages/react/src/components/tabs/index.ts
@@ -0,0 +1,58 @@
+import type {ComponentProps} from "react";
+
+import {
+  Tab,
+  TabIndicator,
+  TabList,
+  TabListContainer,
+  TabPanel,
+  TabSeparator,
+  TabsRoot,
+} from "./tabs";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Tabs = Object.assign(TabsRoot, {
+  Root: TabsRoot,
+  ListContainer: TabListContainer,
+  List: TabList,
+  Tab,
+  Indicator: TabIndicator,
+  Separator: TabSeparator,
+  Panel: TabPanel,
+});
+
+export type Tabs = {
+  Props: ComponentProps<typeof TabsRoot>;
+  RootProps: ComponentProps<typeof TabsRoot>;
+  ListContainer: ComponentProps<typeof TabListContainer>;
+  ListProps: ComponentProps<typeof TabList>;
+  TabProps: ComponentProps<typeof Tab>;
+  IndicatorProps: ComponentProps<typeof TabIndicator>;
+  SeparatorProps: ComponentProps<typeof TabSeparator>;
+  PanelProps: ComponentProps<typeof TabPanel>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabSeparator, TabPanel};
+
+export type {
+  TabsRootProps,
+  TabsRootProps as TabsProps,
+  TabListContainerProps,
+  TabListProps,
+  TabProps,
+  TabIndicatorProps,
+  TabSeparatorProps,
+  TabPanelProps,
+} from "./tabs";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {tabsVariants} from "@heroui/styles";
+
+export type {TabsVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/tabs/tabs.stories.tsx b/packages/react/src/components/tabs/tabs.stories.tsx
new file mode 100644
index 0000000..a9d77f9
--- /dev/null
+++ b/packages/react/src/components/tabs/tabs.stories.tsx
@@ -0,0 +1,568 @@
+import type {Key} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+import {cn} from "tailwind-variants";
+
+import {Tabs} from "./index";
+
+const meta = {
+  argTypes: {},
+  component: Tabs,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Navigation/Tabs",
+} satisfies Meta<typeof Tabs>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const DefaultTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[600px]">
+      <Tabs {...args}>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Options">
+            <Tabs.Tab id="overview">
+              Overview
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="analytics">
+              Analytics
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="reports">
+              Reports
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="pt-4" id="overview">
+          <p>View your project overview and recent activity.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="analytics">
+          <p>Track your metrics and analyze performance data.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="reports">
+          <p>Generate and download detailed reports.</p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const overflowItems = [
+  {id: "overview", label: "Overview"},
+  {id: "analytics", label: "Analytics"},
+  {id: "reports", label: "Reports"},
+  {id: "performance", label: "Performance"},
+  {id: "engagement", label: "Engagement"},
+  {id: "audience", label: "Audience"},
+  {id: "acquisition", label: "Acquisition"},
+  {id: "retention", label: "Retention"},
+  {id: "settings", label: "Settings"},
+];
+
+const OverflowTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[400px]">
+      <Tabs {...args}>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Overflow options">
+            {overflowItems.map((item) => (
+              <Tabs.Tab key={item.id} id={item.id}>
+                {item.label}
+                <Tabs.Indicator />
+              </Tabs.Tab>
+            ))}
+          </Tabs.List>
+        </Tabs.ListContainer>
+        {overflowItems.map((item) => (
+          <Tabs.Panel key={item.id} className="pt-4" id={item.id}>
+            <p>{item.label} panel content.</p>
+          </Tabs.Panel>
+        ))}
+      </Tabs>
+    </div>
+  );
+};
+
+const VerticalTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[600px]">
+      <Tabs {...args} orientation="vertical">
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Vertical tabs">
+            <Tabs.Tab id="account">
+              Account
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="security">
+              Security
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="notifications">
+              Notifications
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="billing">
+              Billing
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="px-4" id="account">
+          <h3 className="mb-2 font-semibold">Account Settings</h3>
+          <p className="text-sm text-gray-600">Manage your account information and preferences.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="security">
+          <h3 className="mb-2 font-semibold">Security Settings</h3>
+          <p className="text-sm text-gray-600">
+            Configure two-factor authentication and password settings.
+          </p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="notifications">
+          <h3 className="mb-2 font-semibold">Notification Preferences</h3>
+          <p className="text-sm text-gray-600">
+            Choose how and when you want to receive notifications.
+          </p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="billing">
+          <h3 className="mb-2 font-semibold">Billing Information</h3>
+          <p className="text-sm text-gray-600">
+            View and manage your subscription and payment methods.
+          </p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const DisabledTabTemplate = (args: Story["args"]) => (
+  <div className="w-[600px]">
+    <Tabs {...args}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Tabs with disabled">
+          <Tabs.Tab id="active">
+            Active
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab isDisabled id="disabled">
+            Disabled
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="available">
+            Available
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="active">
+        <p>This tab is active and can be selected.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="disabled">
+        <p>This content cannot be accessed.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="available">
+        <p>This tab is also available for selection.</p>
+      </Tabs.Panel>
+    </Tabs>
+  </div>
+);
+
+const DefaultSelectedTemplate = (args: Story["args"]) => (
+  <div className="w-[600px]">
+    <Tabs defaultSelectedKey="default" {...args}>
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Tabs with default options">
+          <Tabs.Tab id="active">
+            Active
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="default">
+            Default
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="available">
+            Available
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+      <Tabs.Panel className="pt-4" id="active">
+        <p>This tab is active and can be selected.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="default">
+        <p>This tab is the default selection.</p>
+      </Tabs.Panel>
+      <Tabs.Panel className="pt-4" id="available">
+        <p>This tab is available for selection as well.</p>
+      </Tabs.Panel>
+    </Tabs>
+  </div>
+);
+
+const ControlledSelectionTemplate = (args: Story["args"]) => {
+  const [selectedKey, setSelectedKey] = React.useState<Key>("controlled");
+
+  return (
+    <div className="w-[600px]">
+      <p className="my-2">Selected: {selectedKey}</p>
+      <Tabs selectedKey={selectedKey} onSelectionChange={setSelectedKey} {...args}>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Tabs with controlled options">
+            <Tabs.Tab id="active">
+              Active
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="controlled">
+              Controlled
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="available">
+              Available
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="pt-4" id="active">
+          <p>This tab is active and can be selected.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="controlled">
+          <p>This tab is the controlled selection.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="available">
+          <p>This tab is available for selection as well.</p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const CustomStyleTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[380px]">
+      <Tabs {...args}>
+        <Tabs.ListContainer>
+          <Tabs.List
+            aria-label="Options"
+            className="w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal *:data-[selected=true]:text-accent-foreground"
+          >
+            <Tabs.Tab id="daily">
+              Daily
+              <Tabs.Indicator className="bg-accent" />
+            </Tabs.Tab>
+            <Tabs.Tab id="weekly">
+              Weekly
+              <Tabs.Indicator className="bg-accent" />
+            </Tabs.Tab>
+            <Tabs.Tab id="bi-weekly">
+              Bi-Weekly
+              <Tabs.Indicator className="bg-accent" />
+            </Tabs.Tab>
+            <Tabs.Tab id="monthly">
+              Monthly
+              <Tabs.Indicator className="bg-accent" />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+      </Tabs>
+    </div>
+  );
+};
+
+const WithSeparatorTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[600px]">
+      <Tabs {...args}>
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Options">
+            <Tabs.Tab id="overview">
+              Overview
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="analytics">
+              <Tabs.Separator />
+              Analytics
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="reports">
+              <Tabs.Separator />
+              Reports
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="pt-4" id="overview">
+          <p>View your project overview and recent activity.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="analytics">
+          <p>Track your metrics and analyze performance data.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="reports">
+          <p>Generate and download detailed reports.</p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const SecondaryTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[600px]">
+      <Tabs {...args} variant="secondary">
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Options">
+            <Tabs.Tab id="overview">
+              Overview
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="analytics">
+              Analytics
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="reports">
+              Reports
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="pt-4" id="overview">
+          <p>View your project overview and recent activity.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="analytics">
+          <p>Track your metrics and analyze performance data.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="pt-4" id="reports">
+          <p>Generate and download detailed reports.</p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const SecondaryVerticalTemplate = (args: Story["args"]) => {
+  return (
+    <div className="w-[600px]">
+      <Tabs {...args} orientation="vertical" variant="secondary">
+        <Tabs.ListContainer>
+          <Tabs.List aria-label="Vertical tabs">
+            <Tabs.Tab id="account">
+              Account
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="security">
+              Security
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="notifications">
+              Notifications
+              <Tabs.Indicator />
+            </Tabs.Tab>
+            <Tabs.Tab id="billing">
+              Billing
+              <Tabs.Indicator />
+            </Tabs.Tab>
+          </Tabs.List>
+        </Tabs.ListContainer>
+        <Tabs.Panel className="px-4" id="account">
+          <h3 className="mb-2 font-semibold">Account Settings</h3>
+          <p className="text-sm text-gray-600">Manage your account information and preferences.</p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="security">
+          <h3 className="mb-2 font-semibold">Security Settings</h3>
+          <p className="text-sm text-gray-600">
+            Configure two-factor authentication and password settings.
+          </p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="notifications">
+          <h3 className="mb-2 font-semibold">Notification Preferences</h3>
+          <p className="text-sm text-gray-600">
+            Choose how and when you want to receive notifications.
+          </p>
+        </Tabs.Panel>
+        <Tabs.Panel className="px-4" id="billing">
+          <h3 className="mb-2 font-semibold">Billing Information</h3>
+          <p className="text-sm text-gray-600">
+            View and manage your subscription and payment methods.
+          </p>
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+};
+
+const Showcase1Template = (args: Story["args"]) => {
+  const DEFAULT_ZOOM = 200;
+  const [selectedZoom, setSelectedZoom] = React.useState<Key>(DEFAULT_ZOOM);
+
+  const zoomLevels = [200, 100, 48, 35, 28, 24, 13, "macro"];
+
+  const zoomXMap: Record<number | "macro", string> = {
+    [200]: "8x",
+    [100]: "4x",
+    [48]: "2x",
+    [35]: "1.5x",
+    [28]: "1.2x",
+    [24]: "1x",
+    [13]: "0.5x",
+    ["macro"]: "0.2x",
+  };
+
+  const zoomImgMap: Record<number | "macro", string> = {
+    [200]:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/200mm__c8kya18imsqe_large_2x.jpg",
+    [100]:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/100mm__cykxcenbhvue_large_2x.jpg",
+    [48]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/48mm__bmrwps1q6w76_large_2x.jpg",
+    [35]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/35mm__k375wbkrjp2e_large_2x.jpg",
+    [28]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/28mm__fylmxo06jq6i_large_2x.jpg",
+    [24]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/24mm__e54cxtdkdrwy_large_2x.jpg",
+    [13]: "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/13mm__dzafu9h1kaye_large_2x.jpg",
+    ["macro"]:
+      "https://www.apple.com/v/iphone-17-pro/a/images/overview/cameras/zoom/macro__bb7oud7ri2o2_large_2x.jpg",
+  };
+
+  return (
+    <div className="w-full">
+      <div className="flex flex-col items-center">
+        <div className="relative aspect-[7/5] w-full max-w-[840px] sm:h-[400px] md:h-[500px] lg:h-[600px]">
+          {Object.keys(zoomImgMap).map((key) => (
+            <img
+              key={key}
+              aria-hidden={selectedZoom !== key}
+              className="absolute inset-0 h-full w-full object-cover opacity-0 transition-opacity delay-200 duration-[800ms] ease-in-out data-[selected=true]:opacity-100 data-[selected=true]:delay-0"
+              data-selected={selectedZoom === key}
+              src={zoomImgMap[key]}
+            />
+          ))}
+        </div>
+        <Tabs {...args} defaultSelectedKey={DEFAULT_ZOOM} onSelectionChange={setSelectedZoom}>
+          <Tabs.ListContainer className="scrollbar-hide my-4 w-full max-w-full overflow-x-auto bg-transparent sm:my-6">
+            <Tabs.List
+              aria-label="Options"
+              className="w-fit min-w-min rounded-full bg-[#333336] *:h-8 *:w-fit *:px-3 *:text-xs *:font-normal *:text-white *:opacity-80 *:hover:opacity-100 *:data-[selected=true]:text-black sm:*:h-9 sm:*:px-4 sm:*:text-sm"
+            >
+              {zoomLevels.map((zoom) => (
+                <Tabs.Tab
+                  key={zoom}
+                  className={zoom === "macro" ? "capitalize" : ""}
+                  id={zoom.toString()}
+                >
+                  {zoom} {zoom === "macro" ? "" : "mm"}
+                  <Tabs.Indicator className="rounded-full bg-white shadow-none duration-[320ms]" />
+                </Tabs.Tab>
+              ))}
+            </Tabs.List>
+          </Tabs.ListContainer>
+        </Tabs>
+        <div className="relative h-10 w-10">
+          {Object.keys(zoomXMap).map((key) => (
+            <p
+              key={key}
+              aria-hidden={selectedZoom !== key}
+              data-selected={selectedZoom === key}
+              className={cn(
+                "absolute top-1/2 left-1/2 origin-center -translate-x-1/2 -translate-y-1/2 scale-75 text-[21px] font-medium text-foreground opacity-0 transition-[scale,opacity] duration-[300ms] ease-[cubic-bezier(0.33,1,0.68,1)] ease-in-out-quad data-[selected=true]:scale-100 data-[selected=true]:opacity-100 data-[selected=true]:delay-200",
+                {
+                  "sr-only": selectedZoom !== key,
+                },
+              )}
+            >
+              {zoomXMap[key]}
+            </p>
+          ))}
+        </div>
+        <footer className="mt-4 w-full px-4 text-center text-xs text-muted/30 sm:text-sm">
+          <a href="https://www.apple.com/iphone-17-pro/" rel="noopener noreferrer" target="_blank">
+            Showcase based on Apple&apos;s iPhone 17 Pro camera zoom showcase
+          </a>
+        </footer>
+      </div>
+    </div>
+  );
+};
+
+export const Default: Story = {
+  args: {
+    children: null,
+  },
+  render: DefaultTemplate,
+};
+
+export const Overflow: Story = {
+  args: {
+    children: null,
+  },
+  render: OverflowTemplate,
+};
+
+export const Vertical: Story = {
+  args: {
+    children: null,
+    orientation: "vertical",
+  },
+  render: VerticalTemplate,
+};
+
+export const WithDisabledTab: Story = {
+  args: {
+    children: null,
+  },
+  render: DisabledTabTemplate,
+};
+
+export const WithDefaultSelectedTab: Story = {
+  args: {
+    children: null,
+  },
+  render: DefaultSelectedTemplate,
+};
+
+export const WithControlledSelectionTab: Story = {
+  args: {
+    children: null,
+  },
+  render: ControlledSelectionTemplate,
+};
+
+export const WithCustomStyle: Story = {
+  args: {
+    children: null,
+  },
+  render: CustomStyleTemplate,
+};
+
+export const WithSeparator: Story = {
+  args: {
+    children: null,
+  },
+  render: WithSeparatorTemplate,
+};
+
+export const Showcase1: Story = {
+  args: {
+    children: null,
+  },
+  render: Showcase1Template,
+  name: "Showcases/Apple iPhone 17 Pro cameras",
+};
+
+export const Secondary: Story = {
+  args: {
+    children: null,
+    variant: "secondary",
+  },
+  render: SecondaryTemplate,
+};
+
+export const SecondaryVertical: Story = {
+  args: {
+    children: null,
+    orientation: "vertical",
+    variant: "secondary",
+  },
+  render: SecondaryVerticalTemplate,
+};
diff --git a/packages/react/src/components/tabs/tabs.tsx b/packages/react/src/components/tabs/tabs.tsx
new file mode 100644
index 0000000..70f07fa
--- /dev/null
+++ b/packages/react/src/components/tabs/tabs.tsx
@@ -0,0 +1,251 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {TabsVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {tabsVariants} from "@heroui/styles";
+import React, {createContext, use, useRef} from "react";
+import {SelectionIndicator as SelectionIndicatorPrimitive} from "react-aria-components/SelectionIndicator";
+import {
+  TabList as TabListPrimitive,
+  TabPanel as TabPanelPrimitive,
+  Tab as TabPrimitive,
+  Tabs as TabsPrimitive,
+} from "react-aria-components/Tabs";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {IconChevronDown, IconChevronLeft, IconChevronRight, IconChevronUp} from "../icons";
+import {ScrollShadow} from "../scroll-shadow";
+
+/* -------------------------------------------------------------------------------------------------
+ * Tabs Context
+ * -----------------------------------------------------------------------------------------------*/
+type TabsContext = {
+  orientation?: "horizontal" | "vertical";
+  slots?: ReturnType<typeof tabsVariants>;
+};
+
+const TabsContext = createContext<TabsContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Tabs Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TabsRootProps extends ComponentPropsWithRef<typeof TabsPrimitive>, TabsVariants {
+  children: React.ReactNode;
+  className?: string;
+}
+
+const TabsRoot = ({
+  children,
+  className,
+  orientation = "horizontal",
+  variant,
+  ...props
+}: TabsRootProps) => {
+  const slots = React.useMemo(() => tabsVariants({variant}), [variant]);
+
+  return (
+    <TabsContext value={{orientation, slots}}>
+      <TabsPrimitive
+        {...props}
+        className={composeTwRenderProps(className, slots.base())}
+        data-slot="tabs"
+        orientation={orientation}
+      >
+        {children}
+      </TabsPrimitive>
+    </TabsContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tabs List Container
+ * -----------------------------------------------------------------------------------------------*/
+interface TabListContainerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const TabListContainer = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: TabListContainerProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof TabListContainerProps<E>>) => {
+  const {orientation = "horizontal", slots} = use(TabsContext);
+  const scrollerRef = useRef<HTMLDivElement | null>(null);
+  const isVertical = orientation === "vertical";
+
+  const scrollBy = (direction: 1 | -1) => {
+    const el = scrollerRef.current;
+
+    if (!el) return;
+    const size = isVertical ? el.clientHeight : el.clientWidth;
+
+    el.scrollBy({behavior: "smooth", [isVertical ? "top" : "left"]: direction * size * 0.8});
+  };
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.tabListContainer, className)}
+      data-slot="tabs-list-container"
+      {...(props as any)}
+    >
+      <ScrollShadow
+        ref={scrollerRef}
+        hideScrollBar
+        className={composeSlotClassName(slots?.scroller)}
+        orientation={orientation}
+        size={64}
+      >
+        {children}
+      </ScrollShadow>
+      <button
+        aria-label={isVertical ? "Scroll tabs up" : "Scroll tabs left"}
+        className={composeSlotClassName(slots?.scrollPrev)}
+        tabIndex={-1}
+        type="button"
+        onClick={() => scrollBy(-1)}
+      >
+        {isVertical ? <IconChevronUp /> : <IconChevronLeft />}
+      </button>
+      <button
+        aria-label={isVertical ? "Scroll tabs down" : "Scroll tabs right"}
+        className={composeSlotClassName(slots?.scrollNext)}
+        tabIndex={-1}
+        type="button"
+        onClick={() => scrollBy(1)}
+      >
+        {isVertical ? <IconChevronDown /> : <IconChevronRight />}
+      </button>
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tabs List
+ * -----------------------------------------------------------------------------------------------*/
+interface TabListProps extends ComponentPropsWithRef<typeof TabListPrimitive<object>> {
+  children: React.ReactNode;
+  className?: string;
+}
+
+const TabList = ({children, className, ...props}: TabListProps) => {
+  const {slots} = use(TabsContext);
+
+  return (
+    <TabListPrimitive
+      {...props}
+      className={composeTwRenderProps(className, slots?.tabList())}
+      data-slot="tabs-list"
+    >
+      {children}
+    </TabListPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tab
+ * -----------------------------------------------------------------------------------------------*/
+interface TabProps extends ComponentPropsWithRef<typeof TabPrimitive> {
+  className?: string;
+}
+
+const Tab = ({children, className, ...props}: TabProps) => {
+  const {slots} = use(TabsContext);
+
+  return (
+    <TabPrimitive
+      {...props}
+      className={composeTwRenderProps(className, slots?.tab())}
+      data-slot="tabs-tab"
+    >
+      {children}
+    </TabPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tab Indicator
+ * -----------------------------------------------------------------------------------------------*/
+interface TabIndicatorProps extends ComponentPropsWithRef<typeof SelectionIndicatorPrimitive> {
+  className?: string;
+}
+
+const TabIndicator = ({className, ...props}: TabIndicatorProps) => {
+  const {slots} = use(TabsContext);
+
+  return (
+    <SelectionIndicatorPrimitive
+      className={composeSlotClassName(slots?.tabIndicator, className)}
+      data-slot="tabs-indicator"
+      {...props}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tab Panel
+ * -----------------------------------------------------------------------------------------------*/
+interface TabPanelProps extends Omit<ComponentPropsWithRef<typeof TabPanelPrimitive>, "children"> {
+  children: React.ReactNode;
+  className?: string;
+}
+
+const TabPanel = ({children, className, ...props}: TabPanelProps) => {
+  const {slots} = use(TabsContext);
+
+  return (
+    <TabPanelPrimitive
+      {...props}
+      className={composeTwRenderProps(className, slots?.tabPanel())}
+      data-slot="tabs-panel"
+    >
+      {children}
+    </TabPanelPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tab Separator
+ * -----------------------------------------------------------------------------------------------*/
+interface TabSeparatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const TabSeparator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: TabSeparatorProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof TabSeparatorProps<E>>) => {
+  const {slots} = use(TabsContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.separator, className)}
+      data-slot="tabs-separator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabPanel, TabSeparator};
+
+export type {
+  TabsRootProps,
+  TabListContainerProps,
+  TabListProps,
+  TabProps,
+  TabIndicatorProps,
+  TabPanelProps,
+  TabSeparatorProps,
+};
diff --git a/packages/react/src/components/tag-group/index.ts b/packages/react/src/components/tag-group/index.ts
new file mode 100644
index 0000000..0b4fa41
--- /dev/null
+++ b/packages/react/src/components/tag-group/index.ts
@@ -0,0 +1,35 @@
+import type {ComponentProps} from "react";
+
+import {TagGroupContext, TagGroupList, TagGroupRoot} from "./tag-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const TagGroup = Object.assign(TagGroupRoot, {
+  Root: TagGroupRoot,
+  List: TagGroupList,
+});
+
+export type TagGroup = {
+  Props: ComponentProps<typeof TagGroupRoot>;
+  RootProps: ComponentProps<typeof TagGroupRoot>;
+  ListProps: ComponentProps<typeof TagGroupList>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TagGroupRoot, TagGroupList, TagGroupContext};
+
+export type {
+  TagGroupRootProps,
+  TagGroupRootProps as TagGroupProps,
+  TagGroupListProps,
+} from "./tag-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {tagGroupVariants} from "@heroui/styles";
+
+export type {TagGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/tag-group/tag-group.stories.tsx b/packages/react/src/components/tag-group/tag-group.stories.tsx
new file mode 100644
index 0000000..5570a06
--- /dev/null
+++ b/packages/react/src/components/tag-group/tag-group.stories.tsx
@@ -0,0 +1,495 @@
+import type {Key} from "../";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useMemo, useState} from "react";
+
+import {Avatar, Description, EmptyState, ErrorMessage, Label, Tag} from "../";
+import {useListData} from "../../";
+
+import {TagGroup} from "./";
+
+const meta: Meta<typeof TagGroup> = {
+  component: TagGroup,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Collections/TagGroup",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TagGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <TagGroup aria-label="Tags" selectionMode="single">
+      <TagGroup.List>
+        <Tag id="default-news">
+          <Icon icon="gravity-ui:square-article" />
+          News
+        </Tag>
+        <Tag id="default-travel">
+          <Icon icon="gravity-ui:planet-earth" />
+          Travel
+        </Tag>
+        <Tag id="default-gaming">
+          <Icon icon="gravity-ui:rocket" />
+          Gaming
+        </Tag>
+        <Tag id="default-shopping">
+          <Icon icon="gravity-ui:shopping-bag" />
+          Shopping
+        </Tag>
+      </TagGroup.List>
+    </TagGroup>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <TagGroup selectionMode="single" size="sm">
+        <Label>Small</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="md">
+        <Label>Medium</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+      <TagGroup selectionMode="single" size="lg">
+        <Label>Large</Label>
+        <TagGroup.List>
+          <Tag>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag>Gaming</Tag>
+        </TagGroup.List>
+      </TagGroup>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => {
+    return (
+      <div className="flex flex-col gap-8">
+        <TagGroup selectionMode="single" variant="default">
+          <Label>Default</Label>
+          <TagGroup.List>
+            <Tag>News</Tag>
+            <Tag>Travel</Tag>
+            <Tag>Gaming</Tag>
+          </TagGroup.List>
+        </TagGroup>
+
+        <TagGroup selectionMode="single" variant="surface">
+          <Label>Surface</Label>
+          <TagGroup.List>
+            <Tag>News</Tag>
+            <Tag>Travel</Tag>
+            <Tag>Gaming</Tag>
+          </TagGroup.List>
+        </TagGroup>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TagGroup selectionMode="single">
+        <Label>Disabled Tags</Label>
+        <TagGroup.List>
+          <Tag isDisabled>News</Tag>
+          <Tag>Travel</Tag>
+          <Tag isDisabled>Gaming</Tag>
+        </TagGroup.List>
+        <Description>Some tags are disabled</Description>
+      </TagGroup>
+
+      <TagGroup disabledKeys={["disabled-travel"]} selectionMode="single">
+        <Label>Disabled Keys</Label>
+        <TagGroup.List>
+          <Tag id="disabled-news">News</Tag>
+          <Tag id="disabled-travel">Travel</Tag>
+          <Tag id="disabled-gaming">Gaming</Tag>
+        </TagGroup.List>
+        <Description>Tags disabled via disabledKeys prop</Description>
+      </TagGroup>
+    </div>
+  ),
+};
+
+export const SelectionModes: Story = {
+  render: () => {
+    const [singleSelected, setSingleSelected] = useState<Iterable<Key>>(new Set(["news"]));
+    const [multipleSelected, setMultipleSelected] = useState<Iterable<Key>>(
+      new Set(["news", "travel"]),
+    );
+
+    return (
+      <div className="flex flex-col gap-8">
+        <TagGroup
+          selectedKeys={singleSelected}
+          selectionMode="single"
+          onSelectionChange={(keys) => setSingleSelected(keys)}
+        >
+          <Label>Single Selection</Label>
+          <TagGroup.List>
+            <Tag>News</Tag>
+            <Tag>Travel</Tag>
+            <Tag>Gaming</Tag>
+            <Tag>Shopping</Tag>
+          </TagGroup.List>
+          <Description>Choose one category</Description>
+        </TagGroup>
+
+        <TagGroup
+          selectedKeys={multipleSelected}
+          selectionMode="multiple"
+          onSelectionChange={(keys) => setMultipleSelected(keys)}
+        >
+          <Label>Multiple Selection</Label>
+          <TagGroup.List>
+            <Tag>News</Tag>
+            <Tag>Travel</Tag>
+            <Tag>Gaming</Tag>
+            <Tag>Shopping</Tag>
+          </TagGroup.List>
+          <Description>Choose multiple categories</Description>
+        </TagGroup>
+      </div>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Iterable<Key>>(new Set(["news", "travel"]));
+
+    return (
+      <div className="flex flex-col gap-3">
+        <TagGroup
+          selectedKeys={selected}
+          selectionMode="multiple"
+          onSelectionChange={(keys) => setSelected(keys)}
+        >
+          <Label>Categories (controlled)</Label>
+          <TagGroup.List>
+            <Tag id="news">News</Tag>
+            <Tag id="travel">Travel</Tag>
+            <Tag id="gaming">Gaming</Tag>
+            <Tag id="shopping">Shopping</Tag>
+          </TagGroup.List>
+          <Description>
+            Selected: {Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "None"}
+          </Description>
+        </TagGroup>
+      </div>
+    );
+  },
+};
+
+export const WithErrorMessage: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Iterable<Key>>(new Set());
+
+    const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
+
+    return (
+      <TagGroup
+        selectedKeys={selected}
+        selectionMode="multiple"
+        onSelectionChange={(keys) => setSelected(keys)}
+      >
+        <Label>Amenities</Label>
+        <TagGroup.List>
+          <Tag id="laundry">Laundry</Tag>
+          <Tag id="fitness">Fitness center</Tag>
+          <Tag id="parking">Parking</Tag>
+          <Tag id="pool">Swimming pool</Tag>
+          <Tag id="breakfast">Breakfast</Tag>
+        </TagGroup.List>
+        <Description>
+          {isInvalid
+            ? "Select at least one category"
+            : "Selected: " + Array.from(selected).join(", ")}
+        </Description>
+        {!!isInvalid && <ErrorMessage>Please select at least one category</ErrorMessage>}
+      </TagGroup>
+    );
+  },
+};
+
+export const WithPrefix: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <TagGroup selectionMode="single">
+        <Label>With Icons</Label>
+        <TagGroup.List>
+          <Tag>
+            <Icon icon="gravity-ui:square-article" />
+            News
+          </Tag>
+          <Tag>
+            <Icon icon="gravity-ui:planet-earth" />
+            Travel
+          </Tag>
+          <Tag>
+            <Icon icon="gravity-ui:rocket" />
+            Gaming
+          </Tag>
+          <Tag>
+            <Icon icon="gravity-ui:shopping-bag" />
+            Shopping
+          </Tag>
+        </TagGroup.List>
+        <Description>Tags with icons</Description>
+      </TagGroup>
+
+      <TagGroup selectionMode="single">
+        <Label>With Avatars</Label>
+        <TagGroup.List>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
+              <Avatar.Fallback>F</Avatar.Fallback>
+            </Avatar>
+            Fred
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
+              <Avatar.Fallback>M</Avatar.Fallback>
+            </Avatar>
+            Michael
+          </Tag>
+          <Tag>
+            <Avatar className="size-4">
+              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
+              <Avatar.Fallback>J</Avatar.Fallback>
+            </Avatar>
+            Jane
+          </Tag>
+        </TagGroup.List>
+        <Description>Tags with avatars</Description>
+      </TagGroup>
+    </div>
+  ),
+};
+
+export const WithRemoveButton: Story = {
+  render: () => {
+    type Tag = {id: string; name: string};
+
+    const [tags, setTags] = useState<Tag[]>([
+      {id: "news", name: "News"},
+      {id: "travel", name: "Travel"},
+      {id: "gaming", name: "Gaming"},
+      {id: "shopping", name: "Shopping"},
+    ]);
+
+    const [frameworks, setFrameworks] = useState<Tag[]>([
+      {id: "react", name: "React"},
+      {id: "vue", name: "Vue"},
+      {id: "angular", name: "Angular"},
+      {id: "svelte", name: "Svelte"},
+    ]);
+
+    const onRemoveTags = (keys: Set<Key>) => {
+      setTags(tags.filter((tag) => !keys.has(tag.id)));
+    };
+
+    const onRemoveFrameworks = (keys: Set<Key>) => {
+      setFrameworks(frameworks.filter((framework) => !keys.has(framework.id)));
+    };
+
+    return (
+      <div className="flex flex-col gap-8">
+        <div className="w-sm">
+          <TagGroup selectionMode="single" onRemove={onRemoveTags}>
+            <Label>Default Remove Button</Label>
+            <TagGroup.List
+              items={tags}
+              renderEmptyState={() => <EmptyState className="p-1">No categories found</EmptyState>}
+            >
+              {(tag) => (
+                <Tag key={tag.name} id={tag.id} textValue={tag.name}>
+                  {tag.name}
+                </Tag>
+              )}
+            </TagGroup.List>
+            <Description>Click the X to remove tags</Description>
+          </TagGroup>
+        </div>
+
+        <div className="w-md">
+          <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}>
+            <Label>Custom Remove Button (Render Props)</Label>
+            <TagGroup.List
+              items={frameworks}
+              renderEmptyState={() => <EmptyState className="p-1">No frameworks found</EmptyState>}
+            >
+              {(tag) => (
+                <Tag key={tag.id} id={tag.id} textValue={tag.name}>
+                  {(renderProps) => (
+                    <>
+                      {tag.name}
+                      {!!renderProps.allowsRemoving && (
+                        <Tag.RemoveButton>
+                          <Icon icon="gravity-ui:circle-xmark-fill" />
+                        </Tag.RemoveButton>
+                      )}
+                    </>
+                  )}
+                </Tag>
+              )}
+            </TagGroup.List>
+            <Description>Custom remove button with icon using render props</Description>
+          </TagGroup>
+        </div>
+
+        <div className="w-md">
+          <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}>
+            <Label>Custom Remove Button (Compound Component)</Label>
+            <TagGroup.List
+              items={frameworks}
+              renderEmptyState={() => <EmptyState className="p-1">No frameworks found</EmptyState>}
+            >
+              {(tag) => (
+                <Tag key={tag.id} id={tag.id} textValue={tag.name}>
+                  {tag.name}
+                  <Tag.RemoveButton>
+                    <Icon icon="gravity-ui:circle-xmark-fill" />
+                  </Tag.RemoveButton>
+                </Tag>
+              )}
+            </TagGroup.List>
+            <Description>Custom remove button using compound component pattern</Description>
+          </TagGroup>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithListData: Story = {
+  render: () => {
+    type User = {
+      id: string;
+      name: string;
+      avatar: string;
+      fallback: string;
+    };
+
+    const list = useListData<User>({
+      initialItems: [
+        {
+          id: "fred",
+          name: "Fred",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+          fallback: "F",
+        },
+        {
+          id: "michael",
+          name: "Michael",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+          fallback: "M",
+        },
+        {
+          id: "jane",
+          name: "Jane",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+          fallback: "J",
+        },
+        {
+          id: "alice",
+          name: "Alice",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+          fallback: "A",
+        },
+        {
+          id: "bob",
+          name: "Bob",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+          fallback: "B",
+        },
+        {
+          id: "charlie",
+          name: "Charlie",
+          avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+          fallback: "C",
+        },
+      ],
+      initialSelectedKeys: new Set(["fred", "michael"]),
+      getKey: (item) => item.id,
+    });
+
+    const onRemove = (keys: Set<Key>) => {
+      list.remove(...keys);
+    };
+
+    return (
+      <div className="w-sm">
+        <TagGroup
+          selectedKeys={list.selectedKeys}
+          selectionMode="multiple"
+          onRemove={onRemove}
+          onSelectionChange={(keys) => list.setSelectedKeys(keys)}
+        >
+          <Label>Team Members</Label>
+          <TagGroup.List
+            items={list.items}
+            renderEmptyState={() => <EmptyState className="p-1">No team members</EmptyState>}
+          >
+            {(user) => (
+              <Tag key={user.id} id={user.id} textValue={user.name}>
+                <Avatar className="size-4" size="sm">
+                  <Avatar.Image src={user.avatar} />
+                  <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+                </Avatar>
+                {user.name}
+              </Tag>
+            )}
+          </TagGroup.List>
+          <Description>Select team members for your project</Description>
+        </TagGroup>
+        {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
+          <div className="mt-4 flex flex-col gap-2">
+            <p className="text-sm font-medium text-muted">Selected:</p>
+            <div className="flex flex-wrap gap-2">
+              {Array.from(list.selectedKeys).map((key) => {
+                const user = list.getItem(key);
+
+                if (!user) return null;
+
+                return (
+                  <div
+                    key={`${user.id}-selected`}
+                    className="flex items-center gap-2 rounded-lg bg-surface-tertiary px-2 py-1"
+                  >
+                    <Avatar className="size-4" size="sm">
+                      <Avatar.Image src={user.avatar} />
+                      <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
+                    </Avatar>
+                    <span className="text-sm">{user.name}</span>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/tag-group/tag-group.tsx b/packages/react/src/components/tag-group/tag-group.tsx
new file mode 100644
index 0000000..3726ae8
--- /dev/null
+++ b/packages/react/src/components/tag-group/tag-group.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type {TagVariants} from "../tag";
+import type {ComponentPropsWithRef} from "react";
+
+import {tagGroupVariants} from "@heroui/styles";
+import React, {createContext, use, useMemo} from "react";
+import {
+  TagGroup as TagGroupPrimitive,
+  TagList as TagListPrimitive,
+} from "react-aria-components/TagGroup";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * TagGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type TagGroupContext = {
+  slots?: ReturnType<typeof tagGroupVariants>;
+  size?: TagVariants["size"];
+  variant?: TagVariants["variant"];
+};
+
+const TagGroupContext = createContext<TagGroupContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * TagGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+type TagGroupRootProps = ComponentPropsWithRef<typeof TagGroupPrimitive> & {
+  size?: TagVariants["size"];
+  variant?: TagVariants["variant"];
+};
+
+const TagGroupRoot = ({children, className, size, variant, ...restProps}: TagGroupRootProps) => {
+  const slots = useMemo(() => tagGroupVariants(), []);
+
+  return (
+    <TagGroupContext
+      value={{
+        slots,
+        size,
+        variant,
+      }}
+    >
+      <TagGroupPrimitive className={slots.base({className})} data-slot="tag-group" {...restProps}>
+        {children}
+      </TagGroupPrimitive>
+    </TagGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * TagGroup List
+ * -----------------------------------------------------------------------------------------------*/
+type TagGroupListProps<T extends object> = ComponentPropsWithRef<typeof TagListPrimitive<T>> & {};
+
+const TagGroupList = <T extends object>({
+  children,
+  className,
+  ...restProps
+}: TagGroupListProps<T>) => {
+  const {slots} = use(TagGroupContext);
+
+  return (
+    <TagListPrimitive
+      className={composeTwRenderProps(className, slots?.list())}
+      data-slot="tag-group-list"
+      {...restProps}
+    >
+      {children}
+    </TagListPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TagGroupRoot, TagGroupList, TagGroupContext};
+
+export type {TagGroupRootProps, TagGroupListProps};
diff --git a/packages/react/src/components/tag/index.ts b/packages/react/src/components/tag/index.ts
new file mode 100644
index 0000000..601e05a
--- /dev/null
+++ b/packages/react/src/components/tag/index.ts
@@ -0,0 +1,31 @@
+import type {ComponentProps} from "react";
+
+import {TagRemoveButton, TagRoot} from "./tag";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Tag = Object.assign(TagRoot, {
+  Root: TagRoot,
+  RemoveButton: TagRemoveButton,
+});
+
+export type Tag = {
+  Props: ComponentProps<typeof TagRoot>;
+  RootProps: ComponentProps<typeof TagRoot>;
+  RemoveButtonProps: ComponentProps<typeof TagRemoveButton>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TagRoot, TagRemoveButton};
+
+export type {TagRootProps, TagRemoveButtonProps} from "./tag";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {tagVariants} from "@heroui/styles";
+
+export type {TagVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/tag/tag.tsx b/packages/react/src/components/tag/tag.tsx
new file mode 100644
index 0000000..e819252
--- /dev/null
+++ b/packages/react/src/components/tag/tag.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import type {TagVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {Button as ButtonPrimitive} from "react-aria-components/Button";
+
+import {tagVariants} from "@heroui/styles";
+import React, {Children, createContext, use, useMemo} from "react";
+import {Tag as TagPrimitive} from "react-aria-components/TagGroup";
+
+import {pickChildren} from "../../utils/children";
+import {composeTwRenderProps} from "../../utils/compose";
+import {CloseButton} from "../close-button";
+import {TagGroupContext} from "../tag-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Tag Context
+ * -----------------------------------------------------------------------------------------------*/
+type TagContext = {
+  slots?: ReturnType<typeof tagVariants>;
+};
+
+const TagContext = createContext<TagContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Tag Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TagRootProps extends ComponentPropsWithRef<typeof TagPrimitive>, TagVariants {}
+
+const TagRoot = ({children, className, ...restProps}: TagRootProps) => {
+  const {size, variant} = use(TagGroupContext);
+
+  const slots = useMemo(() => tagVariants({size, variant}), [size, variant]);
+
+  const textValue = useMemo(() => {
+    if (typeof children === "string") {
+      return children;
+    }
+
+    if (typeof children === "object") {
+      return Children.toArray(children)
+        .filter((node) => typeof node === "string")
+        .at(0);
+    }
+
+    return undefined;
+  }, [children]);
+
+  // Extract custom RemoveButton from children if present
+  const [childrenWithoutRemoveButton, removeButtonChildren] = useMemo(() => {
+    if (typeof children === "function") {
+      return [children, undefined];
+    }
+
+    return pickChildren(children, TagRemoveButton);
+  }, [children]);
+
+  return (
+    <TagPrimitive
+      className={composeTwRenderProps(className, slots.base())}
+      data-slot="tag"
+      textValue={textValue}
+      {...restProps}
+    >
+      {(renderProps) => (
+        <TagContext value={{slots}}>
+          {typeof children === "function" ? (
+            children(renderProps)
+          ) : (
+            <>
+              {childrenWithoutRemoveButton}
+              {!!renderProps.allowsRemoving &&
+                (removeButtonChildren && removeButtonChildren.length > 0 ? (
+                  removeButtonChildren
+                ) : (
+                  <TagRemoveButton />
+                ))}
+            </>
+          )}
+        </TagContext>
+      )}
+    </TagPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tag Remove Button
+ * -----------------------------------------------------------------------------------------------*/
+type TagRemoveButtonProps = ComponentPropsWithRef<typeof ButtonPrimitive> & {
+  children?: React.ReactNode;
+};
+
+const TagRemoveButton = ({children, className, ...restProps}: TagRemoveButtonProps) => {
+  const {slots} = use(TagContext);
+
+  return (
+    <CloseButton
+      aria-label="Remove tag"
+      className={composeTwRenderProps(className, slots?.removeButton())}
+      data-slot="tag-remove-button"
+      slot="remove"
+      {...restProps}
+    >
+      {children}
+    </CloseButton>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TagRoot, TagRemoveButton};
+
+export type {TagRootProps, TagRemoveButtonProps};
diff --git a/packages/react/src/components/textarea/index.ts b/packages/react/src/components/textarea/index.ts
new file mode 100644
index 0000000..2b963a4
--- /dev/null
+++ b/packages/react/src/components/textarea/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {TextAreaRoot} from "./textarea";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const TextArea = Object.assign(TextAreaRoot, {
+  Root: TextAreaRoot,
+});
+
+export type TextArea = {
+  Props: ComponentProps<typeof TextAreaRoot>;
+  RootProps: ComponentProps<typeof TextAreaRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TextAreaRoot};
+
+export type {TextAreaRootProps, TextAreaRootProps as TextAreaProps} from "./textarea";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {textAreaVariants} from "@heroui/styles";
+
+export type {TextAreaVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/textarea/textarea.stories.tsx b/packages/react/src/components/textarea/textarea.stories.tsx
new file mode 100644
index 0000000..20f0b9b
--- /dev/null
+++ b/packages/react/src/components/textarea/textarea.stories.tsx
@@ -0,0 +1,42 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Surface} from "../surface";
+
+import {TextArea} from "./index";
+
+export default {
+  argTypes: {},
+  component: TextArea,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Forms/Textarea",
+} as Meta<typeof TextArea>;
+
+type Story = StoryObj<typeof TextArea>;
+
+export const Default: Story = {
+  render: () => <TextArea placeholder="Describe your product" />,
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex w-[280px] flex-col gap-2">
+      <TextArea fullWidth placeholder="Primary textarea" variant="primary" />
+      <TextArea fullWidth placeholder="Secondary textarea" variant="secondary" />
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-3">
+      <TextArea fullWidth placeholder="Full width textarea" />
+      <Surface className="w-full rounded-3xl p-6">
+        <TextArea fullWidth placeholder="Full width textarea on surface" variant="secondary" />
+      </Surface>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/textarea/textarea.tsx b/packages/react/src/components/textarea/textarea.tsx
new file mode 100644
index 0000000..de53c07
--- /dev/null
+++ b/packages/react/src/components/textarea/textarea.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import type {TextAreaVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {textAreaVariants} from "@heroui/styles";
+import React, {use} from "react";
+import {TextArea as TextAreaPrimitive} from "react-aria-components/TextArea";
+
+import {composeTwRenderProps} from "../../utils";
+import {TextFieldContext} from "../textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * TextArea Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TextAreaRootProps
+  extends ComponentPropsWithRef<typeof TextAreaPrimitive>, TextAreaVariants {}
+
+const TextAreaRoot = ({className, fullWidth, variant, ...rest}: TextAreaRootProps) => {
+  const textFieldContext = use(TextFieldContext);
+  const resolvedVariant = variant ?? textFieldContext?.variant;
+
+  return (
+    <TextAreaPrimitive
+      data-slot="textarea"
+      className={composeTwRenderProps(
+        className,
+        textAreaVariants({fullWidth, variant: resolvedVariant}),
+      )}
+      {...rest}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TextAreaRoot};
+
+export type {TextAreaRootProps};
diff --git a/packages/react/src/components/textfield/index.ts b/packages/react/src/components/textfield/index.ts
new file mode 100644
index 0000000..b150090
--- /dev/null
+++ b/packages/react/src/components/textfield/index.ts
@@ -0,0 +1,34 @@
+import type {ComponentProps} from "react";
+
+import {TextFieldRoot} from "./textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const TextField = Object.assign(TextFieldRoot, {
+  Root: TextFieldRoot,
+});
+
+export type TextField = {
+  Props: ComponentProps<typeof TextFieldRoot>;
+  RootProps: ComponentProps<typeof TextFieldRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TextFieldRoot};
+
+export type {TextFieldRootProps, TextFieldRootProps as TextFieldProps} from "./textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * Context
+ * -----------------------------------------------------------------------------------------------*/
+export {TextFieldContext} from "./textfield";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {textFieldVariants} from "@heroui/styles";
+
+export type {TextFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/textfield/textfield.stories.tsx b/packages/react/src/components/textfield/textfield.stories.tsx
new file mode 100644
index 0000000..1542039
--- /dev/null
+++ b/packages/react/src/components/textfield/textfield.stories.tsx
@@ -0,0 +1,226 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import React from "react";
+
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Input} from "../input";
+import {Label} from "../label";
+import {TextArea} from "../textarea";
+
+import {TextField} from "./index";
+
+const meta: Meta<typeof TextField> = {
+  component: TextField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Forms/TextField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <TextField name="name">
+      <Label>Your name</Label>
+      <Input className="w-[280px]" placeholder="John" />
+    </TextField>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <TextField fullWidth name="name">
+        <Label>Your name</Label>
+        <Input placeholder="John" />
+      </TextField>
+      <TextField fullWidth name="productDescription">
+        <Label>Describe your product</Label>
+        <TextArea placeholder="My product is..." />
+      </TextField>
+      <TextField fullWidth isInvalid isRequired name="password" type="password">
+        <Label>Password</Label>
+        <Input />
+        <FieldError>Password must be longer than 8 characters</FieldError>
+      </TextField>
+    </div>
+  ),
+};
+
+export const WithTextArea: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField name="productDescription">
+        <Label>Describe your product</Label>
+        <TextArea className="w-[280px]" placeholder="My product is..." />
+      </TextField>
+      <TextField name="detailedDescription">
+        <Label>Detailed description</Label>
+        <TextArea className="w-[280px]" placeholder="Provide more details..." rows={4} />
+        <Description>Minimum 4 rows</Description>
+      </TextField>
+      <TextField name="review">
+        <Label>Review</Label>
+        <TextArea
+          className="w-[280px]"
+          placeholder="Share your experience..."
+          rows={6}
+          style={{resize: "vertical"}}
+        />
+        <Description>Resizable vertically</Description>
+      </TextField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isRequired name="email" type="email">
+        <Label>Email</Label>
+        <Input className="w-[280px]" placeholder="john@example.com" />
+      </TextField>
+      <TextField isRequired name="address">
+        <Label>Delivery address</Label>
+        <TextArea className="w-[280px]" placeholder="123 Main St, Anytown, USA" />
+        <Description>Make sure to include the zip code</Description>
+      </TextField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField name="name">
+        <Label>Your name</Label>
+        <Input className="w-[280px]" placeholder="John" />
+        <Description>We'll never share this with anyone else</Description>
+      </TextField>
+      <TextField name="address">
+        <Label>Delivery address</Label>
+        <TextArea className="w-[280px]" placeholder="123 Main St, Anytown, USA" />
+        <Description>Make sure to include the zip code</Description>
+      </TextField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isInvalid isRequired name="password" type="password">
+        <Label>Your password</Label>
+        <Input className="w-[280px]" />
+        <FieldError>Password must be longer than 8 characters</FieldError>
+      </TextField>
+      <TextField isInvalid isRequired name="address">
+        <Label>Delivery address</Label>
+        <TextArea className="w-[280px]" placeholder="123 Main St, Anytown, USA" />
+        <FieldError>The address is invalid</FieldError>
+      </TextField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TextField isDisabled name="name">
+        <Label>Your name</Label>
+        <Input className="w-[280px]" placeholder="John" />
+        <Description>We'll never share this with anyone else</Description>
+      </TextField>
+      <TextField isDisabled name="message">
+        <Label>Your message</Label>
+        <TextArea className="w-[280px]" placeholder="Tell us more about yourself..." />
+        <Description>Min 50 characters</Description>
+      </TextField>
+    </div>
+  ),
+};
+
+export const InputTypes: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <TextField name="age" type="number">
+        <Label>Your age</Label>
+        <Input className="w-[280px]" placeholder="18" />
+      </TextField>
+
+      <TextField name="password" type="password">
+        <Label>Your password</Label>
+        <Input className="w-[280px]" placeholder="••••••••" />
+      </TextField>
+
+      <TextField name="email" type="email">
+        <Label>Your email</Label>
+        <Input className="w-[280px]" placeholder="john@example.com" />
+      </TextField>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [inputValue, setInputValue] = React.useState("");
+    const [TextAreaValue, setTextAreaValue] = React.useState("");
+
+    return (
+      <div className="flex flex-col gap-4">
+        <TextField name="name" value={inputValue} onChange={setInputValue}>
+          <Label>Your name</Label>
+          <Input className="w-[280px]" placeholder="John" />
+          <Description>Character count: {inputValue.length}</Description>
+        </TextField>
+        <TextField name="bio" value={TextAreaValue} onChange={setTextAreaValue}>
+          <Label>Your bio</Label>
+          <TextArea className="w-[280px]" placeholder="Tell us about yourself..." />
+          <Description>Character count: {TextAreaValue.length} / 500</Description>
+        </TextField>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [username, setUsername] = React.useState("");
+    const [bio, setBio] = React.useState("");
+    const isUsernameInvalid = username.length > 0 && username.length < 3;
+    const isBioInvalid = bio.length > 0 && bio.length < 20;
+
+    return (
+      <div className="flex flex-col gap-4">
+        <TextField
+          isRequired
+          isInvalid={isUsernameInvalid}
+          name="username"
+          value={username}
+          onChange={setUsername}
+        >
+          <Label>Username</Label>
+          <Input className="w-[280px]" placeholder="john_doe" />
+          {isUsernameInvalid ? (
+            <FieldError>Username must be at least 3 characters</FieldError>
+          ) : (
+            <Description>Choose a unique username</Description>
+          )}
+        </TextField>
+        <TextField isRequired isInvalid={isBioInvalid} name="bio" value={bio} onChange={setBio}>
+          <Label>Bio</Label>
+          <TextArea className="w-[280px]" placeholder="Tell us about yourself..." />
+          {isBioInvalid ? (
+            <FieldError>Bio must be at least 20 characters</FieldError>
+          ) : (
+            <Description>Min 20 characters ({bio.length}/20)</Description>
+          )}
+        </TextField>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/textfield/textfield.tsx b/packages/react/src/components/textfield/textfield.tsx
new file mode 100644
index 0000000..c5cabc0
--- /dev/null
+++ b/packages/react/src/components/textfield/textfield.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import type {TextFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {textFieldVariants} from "@heroui/styles";
+import React, {createContext} from "react";
+import {TextField as TextFieldPrimitive} from "react-aria-components/TextField";
+
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* ------------------------------------------------------------------------------------------------
+ * TextField Context
+ * --------------------------------------------------------------------------------------------- */
+type TextFieldContext = {
+  variant?: "primary" | "secondary";
+};
+
+const TextFieldContext = createContext<TextFieldContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * TextField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TextFieldRootProps
+  extends ComponentPropsWithRef<typeof TextFieldPrimitive>, TextFieldVariants {
+  /**
+   * The variant of the text field.
+   * @default "primary"
+   */
+  variant?: "primary" | "secondary";
+}
+
+const TextFieldRoot = ({children, className, fullWidth, variant, ...props}: TextFieldRootProps) => {
+  const styles = React.useMemo(() => textFieldVariants({fullWidth}), [fullWidth]);
+
+  return (
+    <TextFieldPrimitive
+      data-slot="textfield"
+      {...props}
+      className={composeTwRenderProps(className, styles)}
+    >
+      {(values) => (
+        <TextFieldContext value={{variant}}>
+          <>{typeof children === "function" ? children(values) : children}</>
+        </TextFieldContext>
+      )}
+    </TextFieldPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TextFieldRoot, TextFieldContext};
+
+export type {TextFieldRootProps};
diff --git a/packages/react/src/components/time-field/index.ts b/packages/react/src/components/time-field/index.ts
new file mode 100644
index 0000000..7f8315c
--- /dev/null
+++ b/packages/react/src/components/time-field/index.ts
@@ -0,0 +1,50 @@
+import type {ComponentProps} from "react";
+
+import {
+  DateInputGroupInput,
+  DateInputGroupInputContainer,
+  DateInputGroupPrefix,
+  DateInputGroupRoot,
+  DateInputGroupSegment,
+  DateInputGroupSuffix,
+} from "../date-input-group";
+
+import {TimeFieldRoot} from "./time-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const TimeField = Object.assign(TimeFieldRoot, {
+  Root: TimeFieldRoot,
+  Group: DateInputGroupRoot,
+  Input: DateInputGroupInput,
+  InputContainer: DateInputGroupInputContainer,
+  Segment: DateInputGroupSegment,
+  Prefix: DateInputGroupPrefix,
+  Suffix: DateInputGroupSuffix,
+});
+
+export type TimeField = {
+  Props: ComponentProps<typeof TimeFieldRoot>;
+  RootProps: ComponentProps<typeof TimeFieldRoot>;
+  GroupProps: ComponentProps<typeof DateInputGroupRoot>;
+  InputProps: ComponentProps<typeof DateInputGroupInput>;
+  InputContainerProps: ComponentProps<typeof DateInputGroupInputContainer>;
+  SegmentProps: ComponentProps<typeof DateInputGroupSegment>;
+  PrefixProps: ComponentProps<typeof DateInputGroupPrefix>;
+  SuffixProps: ComponentProps<typeof DateInputGroupSuffix>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TimeFieldRoot};
+
+export type {TimeFieldRootProps, TimeFieldRootProps as TimeFieldProps} from "./time-field";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {timeFieldVariants} from "@heroui/styles";
+
+export type {TimeFieldVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/time-field/time-field.stories.tsx b/packages/react/src/components/time-field/time-field.stories.tsx
new file mode 100644
index 0000000..608d4eb
--- /dev/null
+++ b/packages/react/src/components/time-field/time-field.stories.tsx
@@ -0,0 +1,388 @@
+import type {TimeValue} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import {Time, getLocalTimeZone, now, parseTime} from "@internationalized/date";
+import React, {useState} from "react";
+
+import {Button} from "../button";
+import {Description} from "../description";
+import {FieldError} from "../field-error";
+import {Form} from "../form";
+import {Label} from "../label";
+
+import {TimeField} from "./index";
+
+const meta: Meta<typeof TimeField> = {
+  component: TimeField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Date and Time/TimeField",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-4">
+      <TimeField fullWidth name="time">
+        <Label>Time</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField fullWidth name="time-icons">
+        <Label>Time</Label>
+        <TimeField.Group fullWidth>
+          <TimeField.Prefix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+          </TimeField.Prefix>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+          <TimeField.Suffix>
+            <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+          </TimeField.Suffix>
+        </TimeField.Group>
+      </TimeField>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TimeField className="w-[256px]" name="time">
+        <Label>Start time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter the start time</Description>
+      </TimeField>
+      <TimeField className="w-[256px]" name="end-time">
+        <Label>End time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Enter the end time</Description>
+      </TimeField>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TimeField isRequired className="w-[256px]" name="time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+      </TimeField>
+      <TimeField isRequired className="w-[256px]" name="appointment-time">
+        <Label>Appointment time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <Description>Required field</Description>
+      </TimeField>
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TimeField isInvalid isRequired className="w-[256px]" name="time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>Please enter a valid time</FieldError>
+      </TimeField>
+      <TimeField isInvalid className="w-[256px]" name="invalid-time">
+        <Label>Time</Label>
+        <TimeField.Group>
+          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        </TimeField.Group>
+        <FieldError>Time must be within business hours</FieldError>
+      </TimeField>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => {
+    const currentTime = now(getLocalTimeZone());
+    const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <TimeField isDisabled className="w-[256px]" name="time" value={timeValue}>
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          <Description>This time field is disabled</Description>
+        </TimeField>
+        <TimeField isDisabled className="w-[256px]" name="time-empty">
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          <Description>This time field is disabled</Description>
+        </TimeField>
+      </div>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<TimeValue | null>(null);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <TimeField className="w-[256px]" name="time" value={value} onChange={setValue}>
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
+        </TimeField>
+        <div className="flex gap-2">
+          <Button
+            variant="tertiary"
+            onPress={() => {
+              const currentTime = now(getLocalTimeZone());
+
+              setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second));
+            }}
+          >
+            Set now
+          </Button>
+          <Button variant="tertiary" onPress={() => setValue(null)}>
+            Clear
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = useState<Time | null>(null);
+    const minTime = parseTime("09:00");
+    const maxTime = parseTime("17:00");
+    const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <TimeField
+          isRequired
+          className="w-[256px]"
+          isInvalid={isInvalid}
+          maxValue={maxTime}
+          minValue={minTime}
+          name="time"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          {isInvalid ? (
+            <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
+          ) : (
+            <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
+          )}
+        </TimeField>
+      </div>
+    );
+  },
+};
+
+export const WithPrefixIcon: Story = {
+  render: () => (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+      </TimeField.Group>
+    </TimeField>
+  ),
+};
+
+export const WithSuffixIcon: Story = {
+  render: () => (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+    </TimeField>
+  ),
+};
+
+export const WithPrefixAndSuffix: Story = {
+  render: () => (
+    <TimeField className="w-[256px]" name="time">
+      <Label>Time</Label>
+      <TimeField.Group>
+        <TimeField.Prefix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+        </TimeField.Prefix>
+        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
+        <TimeField.Suffix>
+          <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+        </TimeField.Suffix>
+      </TimeField.Group>
+      <Description>Enter a time</Description>
+    </TimeField>
+  ),
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<Time | null>(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const minTime = parseTime("09:00");
+    const maxTime = parseTime("17:00");
+    const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+
+      if (!value || isInvalid) {
+        return;
+      }
+
+      setIsSubmitting(true);
+
+      // Simulate API call
+      setTimeout(() => {
+        // eslint-disable-next-line no-console
+        console.log("Time submitted:", {time: value});
+        setValue(null);
+        setIsSubmitting(false);
+      }, 1500);
+    };
+
+    return (
+      <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
+        <TimeField
+          isRequired
+          className="w-full"
+          isInvalid={isInvalid}
+          maxValue={maxTime}
+          minValue={minTime}
+          name="time"
+          value={value}
+          onChange={setValue}
+        >
+          <Label>Appointment time</Label>
+          <TimeField.Group>
+            <TimeField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+            </TimeField.Prefix>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          {isInvalid ? (
+            <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
+          ) : (
+            <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
+          )}
+        </TimeField>
+        <Button
+          className="w-full"
+          isDisabled={!value || isInvalid}
+          isPending={isSubmitting}
+          type="submit"
+          variant="primary"
+        >
+          {isSubmitting ? "Submitting..." : "Submit"}
+        </Button>
+      </Form>
+    );
+  },
+};
+
+export const AllVariations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-4">
+        <TimeField isRequired className="w-[256px]" name="time1">
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+            </TimeField.Prefix>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+          </TimeField.Group>
+          <Description>Enter a time</Description>
+        </TimeField>
+
+        <TimeField isRequired className="w-[256px]" name="time2">
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+            <TimeField.Suffix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+            </TimeField.Suffix>
+          </TimeField.Group>
+          <Description>Enter a time</Description>
+        </TimeField>
+
+        <TimeField isRequired className="w-[256px]" name="time3">
+          <Label>Time</Label>
+          <TimeField.Group>
+            <TimeField.Prefix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:clock" />
+            </TimeField.Prefix>
+            <TimeField.Input>
+              {(segment) => <TimeField.Segment segment={segment} />}
+            </TimeField.Input>
+            <TimeField.Suffix>
+              <Icon className="size-4 text-muted" icon="gravity-ui:chevron-down" />
+            </TimeField.Suffix>
+          </TimeField.Group>
+          <Description>Enter a time</Description>
+        </TimeField>
+      </div>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/time-field/time-field.tsx b/packages/react/src/components/time-field/time-field.tsx
new file mode 100644
index 0000000..74a37cc
--- /dev/null
+++ b/packages/react/src/components/time-field/time-field.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import type {TimeFieldVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+import type {TimeValue} from "react-aria-components/TimeField";
+
+import {timeFieldVariants} from "@heroui/styles";
+import React from "react";
+import {TimeField as TimeFieldPrimitive} from "react-aria-components/TimeField";
+
+import {dataAttr} from "../../utils/assertion";
+import {composeTwRenderProps} from "../../utils/compose";
+
+/* -------------------------------------------------------------------------------------------------
+ * TimeField Root
+ * -----------------------------------------------------------------------------------------------*/
+interface TimeFieldRootProps<T extends TimeValue>
+  extends ComponentPropsWithRef<typeof TimeFieldPrimitive<T>>, TimeFieldVariants {}
+
+function TimeFieldRoot<T extends TimeValue>({
+  children,
+  className,
+  fullWidth,
+  ...props
+}: TimeFieldRootProps<T>) {
+  const styles = React.useMemo(() => timeFieldVariants({fullWidth}), [fullWidth]);
+
+  return (
+    <TimeFieldPrimitive
+      data-required={dataAttr(props.isRequired)}
+      data-slot="time-field"
+      {...props}
+      className={composeTwRenderProps(className, styles)}
+    >
+      {(values) => <>{typeof children === "function" ? children(values) : children}</>}
+    </TimeFieldPrimitive>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TimeFieldRoot};
+
+export type {TimeFieldRootProps};
diff --git a/packages/react/src/components/toast/constants.ts b/packages/react/src/components/toast/constants.ts
new file mode 100644
index 0000000..3ffe86e
--- /dev/null
+++ b/packages/react/src/components/toast/constants.ts
@@ -0,0 +1,12 @@
+// Default gap between toasts
+export const DEFAULT_GAP = 12;
+// The default maximum number of visible toasts (visual only).
+export const DEFAULT_MAX_VISIBLE_TOAST = 3;
+// The maximum number of toasts to render in the RAC queue.
+export const DEFAULT_RAC_MAX_VISIBLE_TOAST = Number.MAX_SAFE_INTEGER;
+// The default scale factor for toasts.
+export const DEFAULT_SCALE_FACTOR = 0.05;
+// The default width of the toast.
+export const DEFAULT_TOAST_WIDTH = 460;
+// The default timeout for toasts in milliseconds (matches sonner's default).
+export const DEFAULT_TOAST_TIMEOUT = 4000;
diff --git a/packages/react/src/components/toast/index.ts b/packages/react/src/components/toast/index.ts
new file mode 100644
index 0000000..c3adc1b
--- /dev/null
+++ b/packages/react/src/components/toast/index.ts
@@ -0,0 +1,81 @@
+import type {ComponentProps} from "react";
+
+import {
+  ToastActionButton,
+  ToastCloseButton,
+  ToastContent,
+  ToastDescription,
+  ToastIndicator,
+  ToastProvider,
+  Toast as ToastRoot,
+  ToastTitle,
+} from "./toast";
+import {ToastQueue, toast, toastQueue} from "./toast-queue";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Toast = Object.assign(ToastRoot, {
+  Provider: ToastProvider,
+  Content: ToastContent,
+  Indicator: ToastIndicator,
+  Title: ToastTitle,
+  Description: ToastDescription,
+  ActionButton: ToastActionButton,
+  CloseButton: ToastCloseButton,
+  Queue: ToastQueue,
+  toast,
+});
+
+export type Toast = {
+  Props: ComponentProps<typeof ToastRoot>;
+  ProviderProps: ComponentProps<typeof ToastProvider>;
+  ContentProps: ComponentProps<typeof ToastContent>;
+  IndicatorProps: ComponentProps<typeof ToastIndicator>;
+  TitleProps: ComponentProps<typeof ToastTitle>;
+  DescriptionProps: ComponentProps<typeof ToastDescription>;
+  ActionProps: ComponentProps<typeof ToastActionButton>;
+  CloseButtonProps: ComponentProps<typeof ToastCloseButton>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {
+  ToastProvider,
+  ToastContent,
+  ToastIndicator,
+  ToastTitle,
+  ToastDescription,
+  ToastActionButton,
+  ToastCloseButton,
+};
+
+export type {
+  ToastCloseButtonProps,
+  ToastProviderProps,
+  ToastContentProps,
+  ToastDescriptionProps,
+  ToastIndicatorProps,
+  ToastProps,
+  ToastTitleProps,
+} from "./toast";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {toastVariants} from "@heroui/styles";
+
+export type {ToastVariants} from "@heroui/styles";
+
+/* -------------------------------------------------------------------------------------------------
+ * Utilities
+ * -----------------------------------------------------------------------------------------------*/
+export {ToastQueue, toast, toastQueue};
+
+/* -------------------------------------------------------------------------------------------------
+ * Constants
+ * -----------------------------------------------------------------------------------------------*/
+export {DEFAULT_MAX_VISIBLE_TOAST, DEFAULT_GAP, DEFAULT_TOAST_TIMEOUT} from "./constants";
+
+export type {ToastQueueOptions, ToastContentValue} from "./toast-queue";
diff --git a/packages/react/src/components/toast/toast-queue.ts b/packages/react/src/components/toast/toast-queue.ts
new file mode 100644
index 0000000..f797142
--- /dev/null
+++ b/packages/react/src/components/toast/toast-queue.ts
@@ -0,0 +1,257 @@
+"use client";
+
+import type {ButtonProps} from "../button";
+import type {ReactNode} from "react";
+import type {
+  ToastOptions as RACToastOptions,
+  UNSTABLE_ToastQueue as ToastQueuePrimitiveType,
+} from "react-aria-components/Toast";
+
+import {UNSTABLE_ToastQueue as ToastQueuePrimitive} from "react-aria-components/Toast";
+import {flushSync} from "react-dom";
+
+import {DEFAULT_RAC_MAX_VISIBLE_TOAST, DEFAULT_TOAST_TIMEOUT} from "./constants";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Queue Options
+ * --------------------------------------------------------------------------------------------- */
+export interface ToastQueueOptions {
+  /** The maximum number of toasts to display at a time (visual only). */
+  maxVisibleToasts?: number;
+  /** Function to wrap updates in (i.e. document.startViewTransition()). */
+  wrapUpdate?: (fn: () => void) => void;
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Queue
+ * --------------------------------------------------------------------------------------------- */
+/** The underlying react-stately queue passed to `ToastRegion` (not the HeroUI `ToastQueue` wrapper). */
+export type StatelyToastQueue<T extends object = ToastContentValue> = ToastQueuePrimitiveType<T>;
+
+export class ToastQueue<T extends object = ToastContentValue> {
+  private queue: ToastQueuePrimitiveType<T>;
+  readonly maxVisibleToasts?: number;
+
+  constructor(options?: ToastQueueOptions) {
+    this.maxVisibleToasts = options?.maxVisibleToasts;
+
+    // Serialize successive ViewTransitions through a tail-extending promise
+    // chain. The View Transitions API only allows one active transition at a
+    // time — starting a second while the first is still animating aborts the
+    // first with a "Transition was skipped" DOMException (which surfaces as an
+    // unhandled rejection on .ready). Appending each new transition to the end
+    // of the chain (rather than attaching them all to the first active one)
+    // keeps them strictly ordered even when three or more mutations stack
+    // inside a single microtask, as happens during toast.promise() while the
+    // loading toast's own add transition is still in flight.
+    let transitionChain: Promise<unknown> = Promise.resolve();
+
+    const defaultWrapUpdate = (fn: () => void): void => {
+      if (typeof document === "undefined" || !("startViewTransition" in document)) {
+        fn();
+
+        return;
+      }
+
+      const runNext = (): Promise<unknown> => {
+        const transition = document.startViewTransition(() => {
+          flushSync(fn);
+        });
+
+        // When a transition is superseded or aborted, it's `ready` that
+        // rejects (e.g. "AbortError: Transition was skipped" /
+        // "InvalidStateError: Transition was aborted because of invalid
+        // state"); `finished` still fulfills. Catch `ready` so the rejection
+        // doesn't surface as an unhandled promise rejection.
+        transition.ready.catch(() => {});
+
+        // Swallow the "skipped" rejection so that chain steps after a
+        // superseded transition still run.
+        return transition.finished.catch(() => {});
+      };
+
+      transitionChain = transitionChain.then(runNext, runNext);
+    };
+
+    this.queue = new ToastQueuePrimitive<T>({
+      maxVisibleToasts: DEFAULT_RAC_MAX_VISIBLE_TOAST,
+      wrapUpdate: options?.wrapUpdate ?? defaultWrapUpdate,
+    });
+  }
+
+  add(content: T, options?: RACToastOptions): string {
+    // Apply default timeout if not provided, but respect explicit 0 (persistent toast)
+    const timeout = options?.timeout !== undefined ? options.timeout : DEFAULT_TOAST_TIMEOUT;
+
+    return this.queue.add(content, {
+      ...options,
+      timeout,
+    });
+  }
+
+  close(key: string): void {
+    this.queue.close(key);
+  }
+
+  pauseAll(): void {
+    this.queue.pauseAll();
+  }
+
+  resumeAll(): void {
+    this.queue.resumeAll();
+  }
+
+  clear(): void {
+    this.queue.clear();
+  }
+
+  subscribe(fn: () => void): () => void {
+    return this.queue.subscribe(fn);
+  }
+
+  get visibleToasts() {
+    return this.queue.visibleToasts;
+  }
+
+  getQueue(): ToastQueuePrimitiveType<T> {
+    return this.queue;
+  }
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Queue Instance
+ * --------------------------------------------------------------------------------------------- */
+
+export interface ToastContentValue {
+  indicator?: ReactNode | undefined;
+  title?: ReactNode | undefined;
+  description?: ReactNode | undefined;
+  variant?: "default" | "accent" | "success" | "warning" | "danger" | undefined;
+  actionProps?: ButtonProps | undefined;
+  isLoading?: boolean | undefined;
+}
+
+export interface HeroUIToastOptions {
+  description?: ReactNode;
+  indicator?: ReactNode;
+  variant?: ToastContentValue["variant"];
+  actionProps?: ButtonProps;
+  isLoading?: boolean;
+  timeout?: number;
+  onClose?: () => void;
+}
+
+export interface ToastPromiseOptions<T = unknown> {
+  loading: ReactNode;
+  success: ((data: T) => ReactNode) | ReactNode;
+  error: ((error: Error) => ReactNode) | ReactNode;
+}
+
+// Helper function to create toast
+function createToastFunction(queue: ToastQueue<ToastContentValue>) {
+  const toastFn = (message: ReactNode, options?: HeroUIToastOptions): string => {
+    // Use default timeout if not provided, but respect explicit 0 (persistent toast)
+    const timeout = options?.timeout !== undefined ? options.timeout : DEFAULT_TOAST_TIMEOUT;
+
+    return queue.add(
+      {
+        title: message,
+        description: options?.description,
+        indicator: options?.indicator,
+        variant: options?.variant || "default",
+        actionProps: options?.actionProps,
+        isLoading: options?.isLoading,
+      },
+      {
+        timeout,
+        onClose: () => {
+          requestAnimationFrame(() => {
+            options?.onClose?.();
+          });
+        },
+      },
+    );
+  };
+
+  // Variant methods
+  toastFn.success = (message: ReactNode, options?: Omit<HeroUIToastOptions, "variant">): string => {
+    return toastFn(message, {...options, variant: "success"});
+  };
+
+  toastFn.danger = (message: ReactNode, options?: Omit<HeroUIToastOptions, "variant">): string => {
+    return toastFn(message, {...options, variant: "danger"});
+  };
+
+  toastFn.info = (message: ReactNode, options?: Omit<HeroUIToastOptions, "variant">): string => {
+    return toastFn(message, {...options, variant: "accent"});
+  };
+
+  toastFn.warning = (message: ReactNode, options?: Omit<HeroUIToastOptions, "variant">): string => {
+    return toastFn(message, {...options, variant: "warning"});
+  };
+
+  // Promise support
+  toastFn.promise = <T>(
+    promise: Promise<T> | (() => Promise<T>),
+    options: ToastPromiseOptions<T>,
+  ): string => {
+    const promiseFn = typeof promise === "function" ? promise() : promise;
+    const loadingId = queue.add(
+      {
+        title: options.loading,
+        variant: "default",
+        isLoading: true,
+      },
+      {
+        timeout: 0, // Don't auto-close loading toasts
+      },
+    );
+
+    promiseFn
+      .then((data) => {
+        const successMessage =
+          typeof options.success === "function" ? options.success(data) : options.success;
+
+        queue.close(loadingId);
+
+        return toastFn.success(successMessage);
+      })
+      .catch((error: Error) => {
+        const errorMessage =
+          typeof options.error === "function" ? options.error(error) : options.error;
+
+        queue.close(loadingId);
+
+        return toastFn.danger(errorMessage);
+      });
+
+    return loadingId;
+  };
+
+  // Expose queue methods for advanced usage
+  toastFn.getQueue = () => queue.getQueue();
+  toastFn.close = (key: string) => queue.close(key);
+  toastFn.pauseAll = () => queue.pauseAll();
+  toastFn.resumeAll = () => queue.resumeAll();
+  toastFn.clear = () => queue.clear();
+
+  return toastFn as typeof toastFn & {
+    success: typeof toastFn.success;
+    danger: typeof toastFn.danger;
+    info: typeof toastFn.info;
+    warning: typeof toastFn.warning;
+    promise: typeof toastFn.promise;
+    getQueue: () => ReturnType<typeof queue.getQueue>;
+    close: typeof queue.close;
+    pauseAll: typeof queue.pauseAll;
+    resumeAll: typeof queue.resumeAll;
+    clear: typeof queue.clear;
+  };
+}
+
+const toastQueue = new ToastQueue<ToastContentValue>({
+  maxVisibleToasts: DEFAULT_RAC_MAX_VISIBLE_TOAST,
+});
+
+export const toast = createToastFunction(toastQueue);
+export {toastQueue};
diff --git a/packages/react/src/components/toast/toast.stories.tsx b/packages/react/src/components/toast/toast.stories.tsx
new file mode 100644
index 0000000..865ef57
--- /dev/null
+++ b/packages/react/src/components/toast/toast.stories.tsx
@@ -0,0 +1,663 @@
+import type {ToastContentValue, ToastVariants} from "./index";
+import type {HeroUIToastOptions} from "./toast-queue";
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+
+import {
+  Toast,
+  ToastContent,
+  ToastDescription,
+  ToastIndicator,
+  ToastQueue,
+  ToastTitle,
+  toast,
+} from "./index";
+
+type Placement = NonNullable<ToastVariants["placement"]>;
+
+interface ToastStoryProps extends Omit<HeroUIToastOptions, "variant"> {
+  placement?: Placement;
+}
+
+const meta: Meta<ToastStoryProps> = {
+  argTypes: {
+    placement: {
+      control: "radio",
+      options: ["top start", "top", "top end", "bottom start", "bottom", "bottom end"],
+    },
+    timeout: {
+      control: "number",
+    },
+  },
+  args: {
+    placement: "bottom",
+    timeout: undefined,
+  },
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Feedback/Toast",
+};
+
+export default meta;
+
+const noop = () => {};
+
+const Template = () => {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" />
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          className="text-muted"
+          size="sm"
+          variant="tertiary"
+          onPress={() => {
+            toast("You have been invited to join a team", {
+              actionProps: {
+                children: "Dismiss",
+                onPress: () => toast.clear(),
+                variant: "tertiary",
+              },
+              description: "Bob sent you an invitation to join HeroUI team",
+              indicator: <Icon icon="gravity-ui:persons" />,
+              variant: "default",
+            });
+          }}
+        >
+          Default toast
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.info("You have 2 credits left", {
+              actionProps: {children: "Upgrade", onPress: noop},
+              description: "Get a paid plan for more credits",
+            })
+          }
+        >
+          Accent toast
+        </Button>
+        <Button
+          className="text-success"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.success("You have upgraded your plan", {
+              actionProps: {
+                children: "Billing",
+                className: "bg-success text-success-foreground",
+                onPress: noop,
+              },
+              description: "You can continue using HeroUI Chat",
+            })
+          }
+        >
+          Success toast
+        </Button>
+        <Button
+          className="text-warning"
+          size="sm"
+          variant="tertiary"
+          onPress={() =>
+            toast.warning("You have no credits left", {
+              actionProps: {
+                children: "Upgrade",
+                className: "bg-warning text-warning-foreground",
+                onPress: noop,
+              },
+              description: "Upgrade to a paid plan to continue",
+            })
+          }
+        >
+          Warning toast
+        </Button>
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() =>
+            toast.danger("Storage is full", {
+              actionProps: {children: "Remove", onPress: noop, variant: "danger"},
+              description:
+                "Remove files to release space. Adding more text to demonstrate longer content display",
+              indicator: <Icon icon="gravity-ui:hard-drive" />,
+            })
+          }
+        >
+          Danger toast
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const Default = {
+  args: {},
+  render: Template,
+};
+
+const placements = ["top start", "top", "top end", "bottom start", "bottom", "bottom end"] as const;
+
+// Create a separate queue for each placement
+const placementQueues = Object.fromEntries(
+  placements.map((p) => [p, new ToastQueue({maxVisibleToasts: 3})]),
+) as Record<Placement, ToastQueue>;
+
+const PlacementsTemplate = () => {
+  const showToast = (placement: Placement) => {
+    placementQueues[placement].add({
+      description: "Event has been created",
+      title: "Event created",
+      variant: "default",
+    });
+  };
+
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-6">
+      {/* Render a ToastProvider for each placement */}
+      {placements.map((p) => (
+        <Toast.Provider key={p} placement={p} queue={placementQueues[p]} />
+      ))}
+      <div className="flex max-w-xs flex-wrap justify-center gap-2">
+        {placements.map((p) => (
+          <Button key={p} size="sm" variant="secondary" onPress={() => showToast(p)}>
+            {p}
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export const Placements = {
+  render: PlacementsTemplate,
+};
+
+// Simple Toast - Title only, minimal examples
+const SimpleToastTemplate = () => {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" />
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button size="sm" variant="secondary" onPress={() => toast("Simple message")}>
+          Default
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.success("Operation completed")}>
+          Success
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.info("New update available")}>
+          Info
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => toast.warning("Please check your settings")}
+        >
+          Warning
+        </Button>
+        <Button size="sm" variant="secondary" onPress={() => toast.danger("Something went wrong")}>
+          Error
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const SimpleToast = {
+  render: SimpleToastTemplate,
+};
+
+// Promise Toast - Async operations with loading/success/error states
+const PromiseToastTemplate = () => {
+  const uploadFile = (): Promise<{filename: string; size: number}> => {
+    return new Promise((resolve) => {
+      setTimeout(() => resolve({filename: "document.pdf", size: 1024}), 2000);
+    });
+  };
+
+  const createEvent = (): Promise<never> => {
+    return new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Network error. Please try again.")), 2000);
+    });
+  };
+
+  const saveData = (): Promise<{count: number}> => {
+    return new Promise((resolve, reject) => {
+      setTimeout(() => {
+        if (Math.random() > 0.5) {
+          resolve({count: 42});
+        } else {
+          reject(new Error("Failed to save data"));
+        }
+      }, 2000);
+    });
+  };
+
+  const fetchUser = (): Promise<{name: string; email: string}> => {
+    return new Promise((resolve) => {
+      setTimeout(() => resolve({name: "John Doe", email: "john@example.com"}), 2000);
+    });
+  };
+
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" />
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            toast.promise(uploadFile(), {
+              error: "Failed to upload file",
+              loading: "Uploading file...",
+              success: (data) => `File ${data.filename} uploaded (${data.size}KB)`,
+            });
+          }}
+        >
+          Upload file
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            toast.promise(createEvent(), {
+              error: (err) => err.message,
+              loading: "Creating event...",
+              success: "Event created",
+            });
+          }}
+        >
+          Create event (error)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            toast.promise(saveData(), {
+              error: (err) => err.message,
+              loading: "Saving changes...",
+              success: (data) => `Saved ${data.count} items`,
+            });
+          }}
+        >
+          Save data (random)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            toast.promise(fetchUser(), {
+              error: "Failed to fetch user",
+              loading: "Loading user...",
+              success: (data) => `Welcome back, ${data.name}!`,
+            });
+          }}
+        >
+          Fetch user
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const PromiseToast = {
+  render: PromiseToastTemplate,
+};
+
+// Custom Indicator - Custom or no indicators
+const CustomIndicatorTemplate = () => {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" />
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() =>
+          toast("Custom icon indicator", {
+            indicator: <Icon icon="gravity-ui:star" />,
+          })
+        }
+      >
+        Custom indicator
+      </Button>
+    </div>
+  );
+};
+
+export const CustomIndicator = {
+  render: CustomIndicatorTemplate,
+};
+
+// Loading State - Manual loading toasts
+const LoadingStateTemplate = () => {
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" />
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const loadingId = toast("Uploading file...", {
+              description: "Please wait while we upload your file",
+              isLoading: true,
+              timeout: 0,
+            });
+
+            setTimeout(() => {
+              toast.close(loadingId);
+              toast.success("File uploaded", {
+                description: "Your file has been uploaded successfully",
+              });
+            }, 3000);
+          }}
+        >
+          Upload with loading
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const loadingId = toast("Processing payment...", {
+              isLoading: true,
+              timeout: 0,
+            });
+
+            setTimeout(() => {
+              toast.close(loadingId);
+              toast.success("Payment processed", {
+                description: "Your payment has been processed successfully",
+              });
+            }, 2500);
+          }}
+        >
+          Payment processing
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            const loadingId = toast("Saving changes...", {
+              isLoading: true,
+              timeout: 0,
+            });
+
+            setTimeout(() => {
+              toast.close(loadingId);
+              toast.danger("Failed to save", {
+                description: "Please try again",
+              });
+            }, 2000);
+          }}
+        >
+          Loading to error
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const LoadingState = {
+  render: LoadingStateTemplate,
+};
+
+// With Callbacks - Timeout and onClose
+const WithCallbacksTemplate = () => {
+  const [closedHistory, setClosedHistory] = React.useState<Array<{message: string; time: string}>>(
+    [],
+  );
+
+  const addToHistory = (message: string) => {
+    const time = new Date().toLocaleTimeString();
+
+    setClosedHistory((prev) => [{message, time}, ...prev].slice(0, 5));
+  };
+
+  return (
+    <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-6">
+      <Toast.Provider placement="bottom" />
+
+      {/* Toast Buttons */}
+      <div className="flex w-full flex-wrap items-center justify-center gap-4">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("File saved", {
+              onClose: () => {
+                addToHistory("File saved (closed after 3 seconds)");
+              },
+              timeout: 3000,
+            })
+          }
+        >
+          Custom timeout (3s)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("Changes saved", {
+              onClose: () => {
+                addToHistory("Changes saved (closed after 10 seconds)");
+              },
+              timeout: 10000,
+            })
+          }
+        >
+          Custom timeout (10s)
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast.success("Event created", {
+              onClose: () => {
+                addToHistory("Event created (closed after default timeout)");
+              },
+            })
+          }
+        >
+          With onClose callback
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() =>
+            toast("Important notification", {
+              description: "This toast will stay until dismissed",
+              onClose: () => {
+                addToHistory("Important notification (manually closed)");
+              },
+              timeout: 0,
+            })
+          }
+        >
+          Persistent toast
+        </Button>
+      </div>
+
+      {/* Closed History Panel */}
+      <div className="w-full space-y-2">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium">Closed History</h3>
+          {closedHistory.length > 0 && (
+            <Button
+              className="h-6 text-xs"
+              size="sm"
+              variant="tertiary"
+              onPress={() => setClosedHistory([])}
+            >
+              Clear
+            </Button>
+          )}
+        </div>
+        <div className="min-h-[120px] space-y-2 rounded-lg border border-border bg-surface p-4">
+          {closedHistory.length === 0 ? (
+            <p className="text-sm text-muted">No toasts closed yet. Try closing one above!</p>
+          ) : (
+            closedHistory.map((item, index) => (
+              <div
+                key={`${item.time}-${index}`}
+                className="flex animate-in items-start justify-between gap-3 rounded-md border border-border bg-default px-3 py-2 text-sm duration-200 fade-in slide-in-from-top-2"
+                style={{
+                  animationDelay: `${index * 50}ms`,
+                }}
+              >
+                <div className="flex-1">
+                  <span className="font-medium">{item.message}</span>
+                  <span className="ml-2 text-xs text-muted">({item.time})</span>
+                </div>
+                <div className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-success/10 text-success">
+                  <svg
+                    className="size-3"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    viewBox="0 0 24 24"
+                  >
+                    <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" />
+                  </svg>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const WithCallbacks = {
+  render: WithCallbacksTemplate,
+};
+
+// Custom Toast - Custom rendering with children
+const CustomToastTemplate = () => {
+  const customQueue = new ToastQueue();
+
+  return (
+    <div className="flex h-full max-w-xl flex-col items-center justify-center">
+      <Toast.Provider placement="bottom" queue={customQueue}>
+        {({toast: toastItem}) => {
+          const content = toastItem.content as ToastContentValue;
+
+          return (
+            <Toast
+              className="rounded-xl border border-border"
+              toast={toastItem}
+              variant={content.variant}
+            >
+              <ToastContent>
+                <div className="flex items-center gap-2">
+                  <ToastIndicator className="text-accent" variant={content.variant} />
+                  <div className="flex flex-col pr-6">
+                    {content.title ? (
+                      <ToastTitle className="text-accent">{content.title}</ToastTitle>
+                    ) : null}
+                    {content.description ? (
+                      <ToastDescription>{content.description}</ToastDescription>
+                    ) : null}
+                  </div>
+                </div>
+              </ToastContent>
+              <Toast.CloseButton className="absolute top-1/2 right-2 -translate-y-1/2 border-none bg-transparent opacity-100 [&>svg]:size-4" />
+            </Toast>
+          );
+        }}
+      </Toast.Provider>
+      <Button
+        size="sm"
+        variant="secondary"
+        onPress={() => {
+          customQueue.add({
+            description: "This uses a custom render function",
+            title: "Custom layout toast",
+            variant: "default",
+          });
+        }}
+      >
+        Custom toast
+      </Button>
+    </div>
+  );
+};
+
+export const CustomToast = {
+  render: CustomToastTemplate,
+};
+
+// Custom Queue - Multiple queue instances
+const CustomQueueTemplate = () => {
+  const notificationQueue = new ToastQueue({maxVisibleToasts: 2});
+  const errorQueue = new ToastQueue({maxVisibleToasts: 3});
+  const successQueue = new ToastQueue({maxVisibleToasts: 1});
+
+  return (
+    <div className="flex h-full max-w-4xl items-center justify-center gap-4">
+      {/* Notification Queue */}
+      <Toast.Provider placement="bottom" queue={notificationQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            notificationQueue.add({
+              description: "You have a new message",
+              title: "New notification",
+              variant: "default",
+            });
+          }}
+        >
+          Add notification (max 2)
+        </Button>
+      </div>
+
+      {/* Error Queue */}
+      <Toast.Provider placement="top" queue={errorQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          size="sm"
+          variant="danger-soft"
+          onPress={() => {
+            errorQueue.add({
+              description: "Failed to save changes",
+              title: "Error occurred",
+              variant: "danger",
+            });
+          }}
+        >
+          Add error (max 3)
+        </Button>
+      </div>
+
+      {/* Success Queue */}
+      <Toast.Provider placement="bottom end" queue={successQueue} />
+      <div className="flex justify-center gap-2">
+        <Button
+          className="text-success"
+          size="sm"
+          variant="secondary"
+          onPress={() => {
+            successQueue.add({
+              description: `Operation ${Date.now()}`,
+              title: "Success!",
+              variant: "success",
+            });
+          }}
+        >
+          Add success (max 1)
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const CustomQueue = {
+  render: CustomQueueTemplate,
+};
diff --git a/packages/react/src/components/toast/toast.tsx b/packages/react/src/components/toast/toast.tsx
new file mode 100644
index 0000000..759da88
--- /dev/null
+++ b/packages/react/src/components/toast/toast.tsx
@@ -0,0 +1,534 @@
+"use client";
+
+import type {StatelyToastQueue, ToastContentValue} from "./toast-queue";
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ToastVariants} from "@heroui/styles";
+import type {CSSProperties, ComponentPropsWithRef, ReactNode} from "react";
+import type {QueuedToast, ToastProps as ToastPrimitiveProps} from "react-aria-components/Toast";
+
+import {toastVariants} from "@heroui/styles";
+import React, {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react";
+import {Text as TextPrimitive} from "react-aria-components/Text";
+import {
+  UNSTABLE_ToastContent as ToastContentPrimitive,
+  UNSTABLE_Toast as ToastPrimitive,
+  UNSTABLE_ToastRegion as ToastRegionPrimitive,
+  UNSTABLE_ToastStateContext as ToastStateContext,
+} from "react-aria-components/Toast";
+
+import {useMeasuredHeight, useMediaQuery} from "../../hooks";
+import {dataAttr} from "../../utils/assertion";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {dom} from "../../utils/dom";
+import {Button} from "../button";
+import {CloseButton} from "../close-button";
+import {DangerIcon, InfoIcon, SuccessIcon, WarningIcon} from "../icons";
+import {Spinner} from "../spinner";
+
+import {
+  DEFAULT_GAP,
+  DEFAULT_MAX_VISIBLE_TOAST,
+  DEFAULT_SCALE_FACTOR,
+  DEFAULT_TOAST_WIDTH,
+} from "./constants";
+import {ToastQueue, toast as defaultToastQueue} from "./toast-queue";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Context
+ * --------------------------------------------------------------------------------------------- */
+type ToastContext = {
+  slots?: ReturnType<typeof toastVariants>;
+  placement?: ToastVariants["placement"];
+  width?: number | string;
+  scaleFactor?: number;
+  gap?: number;
+  maxVisibleToasts?: number;
+  heightsByKey?: Record<string, number>;
+  onToastHeightChange?: (key: string, height: number) => void;
+  onToastHeightRemove?: (key: string) => void;
+};
+
+const ToastContext = createContext<ToastContext>({});
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast
+ * --------------------------------------------------------------------------------------------- */
+interface ToastProps<T extends object = ToastContentValue>
+  extends ToastPrimitiveProps<T>, ToastVariants {
+  scaleFactor?: number;
+}
+
+const Toast = <T extends object = ToastContentValue>({
+  children,
+  className,
+  placement,
+  scaleFactor = DEFAULT_SCALE_FACTOR,
+  toast,
+  variant,
+  ...rest
+}: ToastProps<T>) => {
+  const {
+    gap = DEFAULT_GAP,
+    heightsByKey,
+    maxVisibleToasts = DEFAULT_MAX_VISIBLE_TOAST,
+    onToastHeightChange,
+    onToastHeightRemove,
+    placement: contextPlacement,
+    scaleFactor: contextScaleFactor,
+    slots,
+  } = use(ToastContext);
+
+  const finalPlacement = placement ?? contextPlacement;
+  const finalScaleFactor = scaleFactor ?? contextScaleFactor;
+
+  const state = use(ToastStateContext)!;
+  const visibleToasts = state.visibleToasts;
+  const index = visibleToasts.indexOf(toast);
+  const isFrontmost = index <= 0;
+  const isBottom = finalPlacement?.startsWith("bottom");
+  const isHidden = index >= maxVisibleToasts;
+  const toastKey = toast?.key;
+  const toastRef = useRef<HTMLDivElement | null>(null);
+  const {height: toastHeight} = useMeasuredHeight(toastRef);
+
+  useEffect(() => {
+    if (toastKey && typeof toastHeight === "number") {
+      onToastHeightChange?.(toastKey, toastHeight);
+    }
+  }, [toastKey, toastHeight, onToastHeightChange]);
+
+  // Drop this toast's entry from the provider's height map when it unmounts
+  // (or when its key changes). Keeps `toastHeights` bounded to currently
+  // mounted toasts without reading external mutable state inside a setState
+  // updater.
+  useEffect(() => {
+    if (!toastKey) return;
+
+    return () => {
+      onToastHeightRemove?.(toastKey);
+    };
+  }, [toastKey, onToastHeightRemove]);
+
+  // ToastProps from react-aria-components does not expose tabIndex as a typed
+  // prop, so set it imperatively on the underlying DOM node. Only the frontmost
+  // toast is reachable via keyboard; stacked/hidden toasts are removed from
+  // the tab order.
+  useLayoutEffect(() => {
+    const el = toastRef.current;
+
+    if (el) {
+      el.tabIndex = isFrontmost ? 0 : -1;
+    }
+  }, [isFrontmost]);
+
+  const style = useMemo<CSSProperties>(() => {
+    const frontToastKey = visibleToasts[0]?.key;
+
+    const frontHeight =
+      (frontToastKey ? heightsByKey?.[frontToastKey] : undefined) ?? toastHeight ?? 0;
+
+    const offset = index * gap;
+    const translateY = (isBottom ? -1 : 1) * offset;
+    const scale = 1 - index * finalScaleFactor;
+
+    return {
+      scale: `${scale}`,
+      translate: `0 ${translateY}px 0`,
+      viewTransitionName: `toast-${String(toast.key).replace(/[^a-zA-Z0-9]/g, "-")}`,
+      zIndex: visibleToasts.length - index,
+      ...(frontHeight
+        ? ({
+            "--front-height": `${frontHeight}px`,
+          } as CSSProperties)
+        : null),
+      opacity: isHidden ? 0 : 1,
+      pointerEvents: isHidden ? "none" : "auto",
+      ...rest.style,
+    } as const;
+  }, [
+    finalScaleFactor,
+    gap,
+    heightsByKey,
+    index,
+    isBottom,
+    isFrontmost,
+    isHidden,
+    rest.style,
+    toast?.key,
+    toastHeight,
+    visibleToasts,
+  ]);
+
+  return (
+    <ToastPrimitive
+      ref={toastRef}
+      aria-hidden={isHidden}
+      className={composeTwRenderProps(className, slots?.toast({variant}))}
+      data-frontmost={dataAttr(isFrontmost)}
+      data-hidden={dataAttr(isHidden)}
+      data-index={index}
+      data-slot="toast"
+      style={style}
+      toast={toast}
+      {...rest}
+    >
+      {children}
+    </ToastPrimitive>
+  );
+};
+
+Toast.displayName = "HeroUI.Toast";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Content
+ * --------------------------------------------------------------------------------------------- */
+interface ToastContentProps extends ComponentPropsWithRef<typeof ToastContentPrimitive> {}
+
+const ToastContent = ({children, className, ...rest}: ToastContentProps) => {
+  const {slots} = use(ToastContext);
+
+  return (
+    <ToastContentPrimitive
+      className={composeSlotClassName(slots?.content, className)}
+      data-slot="toast-content"
+      {...rest}
+    >
+      {children}
+    </ToastContentPrimitive>
+  );
+};
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Indicator
+ * --------------------------------------------------------------------------------------------- */
+interface ToastIndicatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+  variant?: ToastVariants["variant"];
+}
+
+const ToastIndicator = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  variant,
+  ...rest
+}: ToastIndicatorProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof ToastIndicatorProps<E>>) => {
+  const {slots} = use(ToastContext);
+
+  const getDefaultIcon = useCallback(() => {
+    switch (variant) {
+      case "accent":
+        return <InfoIcon data-slot="toast-default-icon" />;
+      case "success":
+        return <SuccessIcon data-slot="toast-default-icon" />;
+      case "warning":
+        return <WarningIcon data-slot="toast-default-icon" />;
+      case "danger":
+        return <DangerIcon data-slot="toast-default-icon" />;
+      default:
+        return <InfoIcon data-slot="toast-default-icon" />;
+    }
+  }, [variant]);
+
+  return (
+    <dom.div
+      className={composeSlotClassName(slots?.indicator, className)}
+      data-slot="toast-indicator"
+      {...(rest as any)}
+    >
+      {children ?? getDefaultIcon()}
+    </dom.div>
+  );
+};
+
+ToastIndicator.displayName = "HeroUI.ToastIndicator";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Title
+ * --------------------------------------------------------------------------------------------- */
+interface ToastTitleProps extends ComponentPropsWithRef<typeof TextPrimitive> {}
+
+const ToastTitle = ({children, className, ...rest}: ToastTitleProps) => {
+  const {slots} = use(ToastContext);
+
+  return (
+    <TextPrimitive
+      className={composeSlotClassName(slots?.title, className)}
+      data-slot="toast-title"
+      slot="title"
+      {...rest}
+    >
+      {children}
+    </TextPrimitive>
+  );
+};
+
+ToastTitle.displayName = "HeroUI.ToastTitle";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Description
+ * --------------------------------------------------------------------------------------------- */
+interface ToastDescriptionProps extends ComponentPropsWithRef<typeof TextPrimitive> {}
+
+const ToastDescription = ({children, className, ...rest}: ToastDescriptionProps) => {
+  const {slots} = use(ToastContext);
+
+  return (
+    <TextPrimitive
+      className={composeSlotClassName(slots?.description, className)}
+      data-slot="toast-description"
+      slot="description"
+      {...rest}
+    >
+      {children}
+    </TextPrimitive>
+  );
+};
+
+ToastDescription.displayName = "HeroUI.ToastDescription";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Close Button
+ * --------------------------------------------------------------------------------------------- */
+interface ToastCloseButtonProps extends ComponentPropsWithRef<typeof CloseButton> {}
+
+const ToastCloseButton = ({className, ...rest}: ToastCloseButtonProps) => {
+  const {slots} = use(ToastContext);
+
+  return (
+    <CloseButton
+      className={composeTwRenderProps(className, slots?.close())}
+      data-slot="toast-close"
+      slot="close"
+      {...rest}
+    />
+  );
+};
+
+ToastCloseButton.displayName = "HeroUI.ToastCloseButton";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Action Button
+ * --------------------------------------------------------------------------------------------- */
+interface ToastActionButtonProps extends ComponentPropsWithRef<typeof Button> {}
+
+const ToastActionButton = ({children, className, ...rest}: ToastActionButtonProps) => {
+  const {slots} = use(ToastContext);
+
+  return (
+    <Button
+      className={composeTwRenderProps(className, slots?.action?.())}
+      data-slot="toast-action-button"
+      {...rest}
+    >
+      {children}
+    </Button>
+  );
+};
+
+ToastActionButton.displayName = "HeroUI.ToastActionButton";
+
+/* ------------------------------------------------------------------------------------------------
+ * Toast Region
+ * --------------------------------------------------------------------------------------------- */
+type ToastRegionPrimitiveProps<T extends object = ToastContentValue> = ComponentPropsWithRef<
+  typeof ToastRegionPrimitive<T>
+>;
+
+interface ToastProviderProps<T extends object = ToastContentValue> extends Omit<
+  ToastRegionPrimitiveProps<T>,
+  "queue" | "children"
+> {
+  children?: ToastRegionPrimitiveProps<T>["children"];
+  /** The gap between toasts. @default 8 */
+  gap?: number;
+  /** The maximum number of toasts to display at a time (visual only). */
+  maxVisibleToasts?: number;
+  /** The scale factor for toasts. @default 0.05 */
+  scaleFactor?: number;
+  placement?: ToastVariants["placement"];
+  queue?: ToastQueue<T>;
+  /** The width of the toast. @default 460 */
+  width?: number | string;
+}
+
+const ToastProvider = <T extends object = ToastContentValue>({
+  children,
+  className,
+  gap = DEFAULT_GAP,
+  maxVisibleToasts,
+  placement = "bottom",
+  queue: queueProp,
+  scaleFactor = DEFAULT_SCALE_FACTOR,
+  width = DEFAULT_TOAST_WIDTH,
+  ...rest
+}: ToastProviderProps<T>) => {
+  const slots = useMemo(() => toastVariants({placement}), [placement]);
+  const isMobile = useMediaQuery("(max-width: 768px)");
+  const [toastHeights, setToastHeights] = React.useState<Record<string, number>>({});
+
+  const toastQueue = useMemo((): StatelyToastQueue<T> => {
+    if (queueProp) {
+      // Region consumes the underlying react-stately queue, not the HeroUI wrapper.
+      return queueProp.getQueue();
+    }
+
+    return defaultToastQueue.getQueue() as StatelyToastQueue<T>;
+  }, [queueProp]);
+
+  const resolvedMaxVisibleToasts = useMemo(() => {
+    const queueLimit =
+      queueProp && "maxVisibleToasts" in queueProp ? queueProp.maxVisibleToasts : undefined;
+
+    return maxVisibleToasts ?? queueLimit ?? DEFAULT_MAX_VISIBLE_TOAST;
+  }, [maxVisibleToasts, queueProp]);
+
+  const handleToastHeightChange = useCallback((key: string, height: number) => {
+    setToastHeights((prev) => {
+      if (prev[key] === height) {
+        return prev;
+      }
+
+      return {
+        ...prev,
+        [key]: height,
+      };
+    });
+  }, []);
+
+  // Removes a toast's height entry when it unmounts (called from each Toast's
+  // effect cleanup). Keeps `toastHeights` bounded to currently mounted toasts.
+  const handleToastHeightRemove = useCallback((key: string) => {
+    setToastHeights((prev) => {
+      if (!(key in prev)) {
+        return prev;
+      }
+
+      const next = {...prev};
+
+      delete next[key];
+
+      return next;
+    });
+  }, []);
+
+  const getDefaultChildren = useCallback(
+    (renderProps: {toast: QueuedToast<T>}) => {
+      const {actionProps, description, indicator, isLoading, title, variant} =
+        (renderProps.toast.content as ToastContentValue) ?? {};
+
+      return (
+        <Toast
+          placement={placement}
+          scaleFactor={scaleFactor}
+          toast={renderProps.toast}
+          variant={variant}
+        >
+          {indicator === null ? null : isLoading ? (
+            <ToastIndicator variant={variant}>
+              <Spinner color="current" size="sm" />
+            </ToastIndicator>
+          ) : (
+            <ToastIndicator variant={variant}>{indicator}</ToastIndicator>
+          )}
+          <ToastContent>
+            {!!title && <ToastTitle>{title}</ToastTitle>}
+            {!!description && <ToastDescription>{description}</ToastDescription>}
+            {isMobile && actionProps?.children ? (
+              <ToastActionButton {...actionProps}>{actionProps.children}</ToastActionButton>
+            ) : null}
+          </ToastContent>
+          {!isMobile && actionProps?.children ? (
+            <ToastActionButton {...actionProps}>{actionProps.children}</ToastActionButton>
+          ) : null}
+          <ToastCloseButton />
+        </Toast>
+      );
+    },
+    [isMobile, placement, scaleFactor],
+  );
+
+  return (
+    <ToastRegionPrimitive<T>
+      className={composeTwRenderProps(className, slots?.region())}
+      data-slot="toast-region"
+      queue={toastQueue}
+      style={{
+        // @ts-expect-error - CSS variables
+        "--gap": `${gap}px`,
+        "--placement": placement,
+        "--scale-factor": scaleFactor,
+        "--toast-width": typeof width === "number" ? `${width}px` : width,
+      }}
+      {...rest}
+    >
+      {(renderProps) => {
+        const content = renderProps.toast.content as ToastContentValue;
+        const renderPropsWithIsLoading = {
+          ...renderProps,
+          isLoading: content?.isLoading ?? false,
+        };
+
+        return (
+          <ToastContext
+            value={{
+              gap,
+              heightsByKey: toastHeights,
+              maxVisibleToasts: resolvedMaxVisibleToasts,
+              onToastHeightChange: handleToastHeightChange,
+              onToastHeightRemove: handleToastHeightRemove,
+              placement,
+              scaleFactor,
+              slots,
+              width,
+            }}
+          >
+            {typeof children === "undefined"
+              ? getDefaultChildren(renderProps)
+              : typeof children === "function"
+                ? children(renderPropsWithIsLoading)
+                : children}
+          </ToastContext>
+        );
+      }}
+    </ToastRegionPrimitive>
+  );
+};
+
+ToastProvider.displayName = "HeroUI.ToastProvider";
+
+/* ------------------------------------------------------------------------------------------------
+ * Exports
+ * --------------------------------------------------------------------------------------------- */
+export {
+  ToastQueue,
+  Toast,
+  ToastActionButton,
+  ToastCloseButton,
+  ToastContent,
+  ToastDescription,
+  ToastIndicator,
+  ToastProvider,
+  ToastTitle,
+};
+
+export type {
+  ToastActionButtonProps,
+  ToastCloseButtonProps,
+  ToastContentProps,
+  ToastDescriptionProps,
+  ToastIndicatorProps,
+  ToastProps,
+  ToastProviderProps,
+  ToastTitleProps,
+};
diff --git a/packages/react/src/components/toggle-button-group/index.ts b/packages/react/src/components/toggle-button-group/index.ts
new file mode 100644
index 0000000..45fd4ff
--- /dev/null
+++ b/packages/react/src/components/toggle-button-group/index.ts
@@ -0,0 +1,40 @@
+import type {ComponentProps} from "react";
+
+import {ToggleButtonGroupRoot, ToggleButtonGroupSeparator} from "./toggle-button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ToggleButtonGroup = Object.assign(ToggleButtonGroupRoot, {
+  Root: ToggleButtonGroupRoot,
+  Separator: ToggleButtonGroupSeparator,
+});
+
+export type ToggleButtonGroup = {
+  Props: ComponentProps<typeof ToggleButtonGroupRoot>;
+  RootProps: ComponentProps<typeof ToggleButtonGroupRoot>;
+  SeparatorProps: ComponentProps<typeof ToggleButtonGroupSeparator>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ToggleButtonGroupRoot, ToggleButtonGroupSeparator};
+
+export type {
+  ToggleButtonGroupRootProps,
+  ToggleButtonGroupRootProps as ToggleButtonGroupProps,
+  ToggleButtonGroupSeparatorProps,
+} from "./toggle-button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Context
+ * -----------------------------------------------------------------------------------------------*/
+export {ToggleButtonGroupContext, TOGGLE_BUTTON_GROUP_CHILD} from "./toggle-button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {toggleButtonGroupVariants} from "@heroui/styles";
+
+export type {ToggleButtonGroupVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/toggle-button-group/toggle-button-group.stories.tsx b/packages/react/src/components/toggle-button-group/toggle-button-group.stories.tsx
new file mode 100644
index 0000000..27076f5
--- /dev/null
+++ b/packages/react/src/components/toggle-button-group/toggle-button-group.stories.tsx
@@ -0,0 +1,520 @@
+import type {Key} from "../rac";
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useState} from "react";
+
+import {ToggleButton} from "../toggle-button";
+
+import {ToggleButtonGroup} from "./";
+
+const meta: Meta<typeof ToggleButtonGroup> = {
+  argTypes: {
+    fullWidth: {
+      control: "boolean",
+    },
+    isDetached: {
+      control: "boolean",
+    },
+    isDisabled: {
+      control: "boolean",
+    },
+    orientation: {
+      control: "select",
+      options: ["horizontal", "vertical"],
+    },
+    selectionMode: {
+      control: "select",
+      options: ["single", "multiple"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  component: ToggleButtonGroup,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Buttons/ToggleButtonGroup",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ToggleButtonGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="Bold" id="bold">
+        <Icon icon="gravity-ui:bold" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Italic" id="italic">
+        <ToggleButtonGroup.Separator />
+        <Icon icon="gravity-ui:italic" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Underline" id="underline">
+        <ToggleButtonGroup.Separator />
+        <Icon icon="gravity-ui:underline" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+        <ToggleButtonGroup.Separator />
+        <Icon icon="gravity-ui:strikethrough" />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Small</p>
+        <ToggleButtonGroup selectionMode="multiple" size="sm">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Medium (default)</p>
+        <ToggleButtonGroup selectionMode="multiple" size="md">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Large</p>
+        <ToggleButtonGroup selectionMode="multiple" size="lg">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const Orientation: Story = {
+  render: () => (
+    <div className="flex items-start gap-8">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Horizontal</p>
+        <ToggleButtonGroup orientation="horizontal" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Vertical</p>
+        <ToggleButtonGroup orientation="vertical" selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const AttachedVsDetached: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Attached (default)</p>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Detached</p>
+        <ToggleButtonGroup isDetached selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const FullWidth: Story = {
+  render: () => (
+    <div className="w-[400px] space-y-3">
+      <ToggleButtonGroup fullWidth selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Icon icon="gravity-ui:bold" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:strikethrough" />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <ToggleButtonGroup fullWidth selectionMode="single">
+        <ToggleButton id="left">
+          <Icon icon="gravity-ui:text-align-left" />
+          Left
+        </ToggleButton>
+        <ToggleButton id="center">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:text-align-center" />
+          Center
+        </ToggleButton>
+        <ToggleButton id="right">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:text-align-right" />
+          Right
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </div>
+  ),
+};
+
+export const SelectionMode: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Single selection</p>
+        <ToggleButtonGroup defaultSelectedKeys={["center"]} selectionMode="single">
+          <ToggleButton id="left">
+            <Icon icon="gravity-ui:text-align-left" />
+            Left
+          </ToggleButton>
+          <ToggleButton id="center">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:text-align-center" />
+            Center
+          </ToggleButton>
+          <ToggleButton id="right">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:text-align-right" />
+            Right
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Multiple selection</p>
+        <ToggleButtonGroup defaultSelectedKeys={["bold", "underline"]} selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: function ControlledStory() {
+    const [selectedKeys, setSelectedKeys] = useState(new Set<Key>(["bold"]));
+
+    return (
+      <div className="flex flex-col gap-4">
+        <ToggleButtonGroup
+          selectedKeys={selectedKeys}
+          selectionMode="multiple"
+          onSelectionChange={setSelectedKeys}
+        >
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:strikethrough" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+        <p className="text-sm text-muted">
+          Selected:{" "}
+          <span className="font-medium">
+            {selectedKeys.size > 0 ? [...selectedKeys].join(", ") : "None"}
+          </span>
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">All buttons disabled</p>
+        <ToggleButtonGroup isDisabled selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted">Individual button disabled</p>
+        <ToggleButtonGroup selectionMode="multiple">
+          <ToggleButton isIconOnly aria-label="Bold" id="bold">
+            <Icon icon="gravity-ui:bold" />
+          </ToggleButton>
+          <ToggleButton isDisabled isIconOnly aria-label="Italic" id="italic">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:italic" />
+          </ToggleButton>
+          <ToggleButton isIconOnly aria-label="Underline" id="underline">
+            <ToggleButtonGroup.Separator />
+            <Icon icon="gravity-ui:underline" />
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </div>
+    </div>
+  ),
+};
+
+export const WithoutSeparator: Story = {
+  render: () => (
+    <ToggleButtonGroup selectionMode="multiple">
+      <ToggleButton isIconOnly aria-label="Bold" id="bold">
+        <Icon icon="gravity-ui:bold" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Italic" id="italic">
+        <Icon icon="gravity-ui:italic" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Underline" id="underline">
+        <Icon icon="gravity-ui:underline" />
+      </ToggleButton>
+      <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+        <Icon icon="gravity-ui:strikethrough" />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  ),
+};
+
+export const WithLabels: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <ToggleButtonGroup defaultSelectedKeys={["italic"]} selectionMode="multiple">
+        <ToggleButton id="bold">
+          <Icon icon="gravity-ui:bold" />
+          Bold
+        </ToggleButton>
+        <ToggleButton id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+          Italic
+        </ToggleButton>
+        <ToggleButton id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+          Underline
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </div>
+  ),
+};
+
+export const Examples: Story = {
+  render: function ExamplesStory() {
+    const [alignment, setAlignment] = useState(new Set<Key>(["left"]));
+    const [formatting, setFormatting] = useState(new Set<Key>(["bold", "underline"]));
+
+    return (
+      <div className="flex flex-col items-start gap-8">
+        {/* Text formatting toolbar */}
+        <div className="flex flex-col gap-2">
+          <p className="text-sm text-muted">Text formatting toolbar</p>
+          <div className="flex gap-2">
+            <ToggleButtonGroup
+              selectedKeys={formatting}
+              selectionMode="multiple"
+              onSelectionChange={setFormatting}
+            >
+              <ToggleButton isIconOnly aria-label="Bold" id="bold">
+                <Icon icon="gravity-ui:bold" />
+              </ToggleButton>
+              <ToggleButton isIconOnly aria-label="Italic" id="italic">
+                <ToggleButtonGroup.Separator />
+                <Icon icon="gravity-ui:italic" />
+              </ToggleButton>
+              <ToggleButton isIconOnly aria-label="Underline" id="underline">
+                <ToggleButtonGroup.Separator />
+                <Icon icon="gravity-ui:underline" />
+              </ToggleButton>
+              <ToggleButton isIconOnly aria-label="Strikethrough" id="strikethrough">
+                <ToggleButtonGroup.Separator />
+                <Icon icon="gravity-ui:strikethrough" />
+              </ToggleButton>
+            </ToggleButtonGroup>
+            <ToggleButtonGroup
+              disallowEmptySelection
+              selectedKeys={alignment}
+              selectionMode="single"
+              onSelectionChange={setAlignment}
+            >
+              <ToggleButton isIconOnly aria-label="Align left" id="left">
+                <Icon icon="gravity-ui:text-align-left" />
+              </ToggleButton>
+              <ToggleButton isIconOnly aria-label="Align center" id="center">
+                <ToggleButtonGroup.Separator />
+                <Icon icon="gravity-ui:text-align-center" />
+              </ToggleButton>
+              <ToggleButton isIconOnly aria-label="Align right" id="right">
+                <ToggleButtonGroup.Separator />
+                <Icon icon="gravity-ui:text-align-right" />
+              </ToggleButton>
+            </ToggleButtonGroup>
+          </div>
+        </div>
+
+        {/* View mode switcher */}
+        <div className="flex flex-col gap-2">
+          <p className="text-sm text-muted">View mode switcher</p>
+          <ToggleButtonGroup
+            disallowEmptySelection
+            defaultSelectedKeys={["grid"]}
+            selectionMode="single"
+            size="sm"
+          >
+            <ToggleButton isIconOnly aria-label="Grid view" id="grid">
+              <Icon icon="gravity-ui:layout-cells-large" />
+            </ToggleButton>
+            <ToggleButton isIconOnly aria-label="List view" id="list">
+              <ToggleButtonGroup.Separator />
+              <Icon icon="gravity-ui:list-ul" />
+            </ToggleButton>
+            <ToggleButton isIconOnly aria-label="Columns view" id="columns">
+              <ToggleButtonGroup.Separator />
+              <Icon icon="gravity-ui:layout-columns-3" />
+            </ToggleButton>
+          </ToggleButtonGroup>
+        </div>
+
+        {/* Vertical toolbar */}
+        <div className="flex flex-col gap-2">
+          <p className="text-sm text-muted">Vertical toolbar</p>
+          <ToggleButtonGroup orientation="vertical" selectionMode="multiple">
+            <ToggleButton isIconOnly aria-label="Bold" id="bold">
+              <Icon icon="gravity-ui:bold" />
+            </ToggleButton>
+            <ToggleButton isIconOnly aria-label="Italic" id="italic">
+              <ToggleButtonGroup.Separator />
+              <Icon icon="gravity-ui:italic" />
+            </ToggleButton>
+            <ToggleButton isIconOnly aria-label="Underline" id="underline">
+              <ToggleButtonGroup.Separator />
+              <Icon icon="gravity-ui:underline" />
+            </ToggleButton>
+          </ToggleButtonGroup>
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/react/src/components/toggle-button-group/toggle-button-group.tsx b/packages/react/src/components/toggle-button-group/toggle-button-group.tsx
new file mode 100644
index 0000000..c2719a0
--- /dev/null
+++ b/packages/react/src/components/toggle-button-group/toggle-button-group.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {ToggleButtonGroupVariants, ToggleButtonVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {toggleButtonGroupVariants} from "@heroui/styles";
+import React, {createContext, use} from "react";
+import {useSlottedContext} from "react-aria-components/slots";
+import {
+  ToggleButtonGroupContext as RACToggleButtonGroupContext,
+  ToggleButtonGroup as ToggleButtonGroupPrimitive,
+} from "react-aria-components/ToggleButtonGroup";
+
+import {composeSlotClassName, composeTwRenderProps} from "../../utils";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * ToggleButtonGroup Context
+ * -----------------------------------------------------------------------------------------------*/
+type ToggleButtonGroupContext = {
+  slots?: ReturnType<typeof toggleButtonGroupVariants>;
+  size?: ToggleButtonVariants["size"];
+  isDisabled?: boolean;
+};
+
+const ToggleButtonGroupContext = createContext<ToggleButtonGroupContext>({});
+
+// Property name to mark direct children of ToggleButtonGroup
+export const TOGGLE_BUTTON_GROUP_CHILD = "__toggle_button_group_child";
+
+/* -------------------------------------------------------------------------------------------------
+ * ToggleButtonGroup Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ToggleButtonGroupRootProps
+  extends ComponentPropsWithRef<typeof ToggleButtonGroupPrimitive>, ToggleButtonGroupVariants {
+  /** Size to propagate to all child ToggleButtons */
+  size?: ToggleButtonVariants["size"];
+  /** Whether the group buttons are visually separated (detached) instead of connected */
+  isDetached?: boolean;
+}
+
+const ToggleButtonGroupRoot = ({
+  children,
+  className,
+  fullWidth,
+  isDetached = false,
+  isDisabled,
+  orientation: orientationProp,
+  size,
+  ...rest
+}: ToggleButtonGroupRootProps) => {
+  const racContext = useSlottedContext(RACToggleButtonGroupContext);
+  const orientation = orientationProp ?? racContext?.orientation ?? "horizontal";
+
+  const slots = React.useMemo(
+    () => toggleButtonGroupVariants({fullWidth, isDetached, orientation}),
+    [fullWidth, isDetached, orientation],
+  );
+
+  return (
+    <ToggleButtonGroupContext value={{slots, size, isDisabled}}>
+      <ToggleButtonGroupPrimitive
+        className={composeTwRenderProps(className, slots.base())}
+        data-slot="toggle-button-group"
+        isDisabled={isDisabled}
+        orientation={orientation}
+        {...rest}
+      >
+        {children}
+      </ToggleButtonGroupPrimitive>
+    </ToggleButtonGroupContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * ToggleButtonGroup Separator
+ * -----------------------------------------------------------------------------------------------*/
+interface ToggleButtonGroupSeparatorProps<
+  E extends keyof React.JSX.IntrinsicElements = "span",
+> extends DOMRenderProps<E, undefined> {
+  className?: string;
+}
+
+const ToggleButtonGroupSeparator = <E extends keyof React.JSX.IntrinsicElements = "span">({
+  className,
+  ...props
+}: ToggleButtonGroupSeparatorProps<E> &
+  Omit<React.JSX.IntrinsicElements[E], keyof ToggleButtonGroupSeparatorProps<E>>) => {
+  const {slots} = use(ToggleButtonGroupContext);
+
+  return (
+    <dom.span
+      aria-hidden="true"
+      className={composeSlotClassName(slots?.separator, className)}
+      data-slot="toggle-button-group-separator"
+      {...(props as any)}
+    />
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ToggleButtonGroupRoot, ToggleButtonGroupSeparator, ToggleButtonGroupContext};
+
+export type {ToggleButtonGroupRootProps, ToggleButtonGroupSeparatorProps};
diff --git a/packages/react/src/components/toggle-button/index.ts b/packages/react/src/components/toggle-button/index.ts
new file mode 100644
index 0000000..03f6e21
--- /dev/null
+++ b/packages/react/src/components/toggle-button/index.ts
@@ -0,0 +1,32 @@
+import type {ComponentProps} from "react";
+
+import {ToggleButtonRoot} from "./toggle-button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const ToggleButton = Object.assign(ToggleButtonRoot, {
+  Root: ToggleButtonRoot,
+});
+
+export type ToggleButton = {
+  Props: ComponentProps<typeof ToggleButtonRoot>;
+  RootProps: ComponentProps<typeof ToggleButtonRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ToggleButtonRoot};
+
+export type {
+  ToggleButtonRootProps,
+  ToggleButtonRootProps as ToggleButtonProps,
+} from "./toggle-button";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {toggleButtonVariants} from "@heroui/styles";
+
+export type {ToggleButtonVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/toggle-button/toggle-button.stories.tsx b/packages/react/src/components/toggle-button/toggle-button.stories.tsx
new file mode 100644
index 0000000..28d0073
--- /dev/null
+++ b/packages/react/src/components/toggle-button/toggle-button.stories.tsx
@@ -0,0 +1,212 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React, {useState} from "react";
+
+import {ToggleButton} from "./index";
+
+export default {
+  argTypes: {
+    isDisabled: {
+      control: "boolean",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+    variant: {
+      control: "select",
+      options: ["default", "ghost"],
+    },
+  },
+  component: ToggleButton,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Buttons/ToggleButton",
+} as Meta<typeof ToggleButton>;
+
+const defaultArgs: ToggleButton["RootProps"] = {
+  size: "md",
+};
+
+const Template = ({isDisabled, size, variant}: ToggleButton["RootProps"]) => (
+  <div className="flex gap-3">
+    <ToggleButton isDisabled={isDisabled} size={size} variant={variant}>
+      <Icon icon="gravity-ui:heart" />
+      Like
+    </ToggleButton>
+    <ToggleButton isDisabled={isDisabled} size={size} variant={variant ?? "ghost"}>
+      <Icon icon="gravity-ui:heart" />
+      Like
+    </ToggleButton>
+  </div>
+);
+
+const VariantsTemplate = ({isDisabled, size}: ToggleButton["RootProps"]) => (
+  <div className="flex flex-col gap-4">
+    <div className="flex flex-col gap-2">
+      <p className="text-sm font-medium text-muted">Default</p>
+      <div className="flex gap-3">
+        <ToggleButton isDisabled={isDisabled} size={size}>
+          <Icon icon="gravity-ui:heart" />
+          Like
+        </ToggleButton>
+        <ToggleButton defaultSelected isDisabled={isDisabled} size={size}>
+          <Icon icon="gravity-ui:heart-fill" />
+          Like
+        </ToggleButton>
+      </div>
+    </div>
+    <div className="flex flex-col gap-2">
+      <p className="text-sm font-medium text-muted">Ghost</p>
+      <div className="flex gap-3">
+        <ToggleButton isDisabled={isDisabled} size={size} variant="ghost">
+          <Icon icon="gravity-ui:heart" />
+          Like
+        </ToggleButton>
+        <ToggleButton defaultSelected isDisabled={isDisabled} size={size} variant="ghost">
+          <Icon icon="gravity-ui:heart-fill" />
+          Like
+        </ToggleButton>
+      </div>
+    </div>
+  </div>
+);
+
+const SizesTemplate = () => (
+  <div className="flex flex-col gap-6">
+    <div className="flex items-center gap-3">
+      <ToggleButton size="sm">
+        <Icon icon="gravity-ui:heart" />
+        Small
+      </ToggleButton>
+      <ToggleButton size="md">
+        <Icon icon="gravity-ui:heart" />
+        Medium
+      </ToggleButton>
+      <ToggleButton size="lg">
+        <Icon icon="gravity-ui:heart" />
+        Large
+      </ToggleButton>
+    </div>
+    <div className="flex items-center gap-3">
+      <ToggleButton isIconOnly size="sm">
+        <Icon icon="gravity-ui:heart" />
+      </ToggleButton>
+      <ToggleButton isIconOnly size="md">
+        <Icon icon="gravity-ui:heart" />
+      </ToggleButton>
+      <ToggleButton isIconOnly size="lg">
+        <Icon icon="gravity-ui:heart" />
+      </ToggleButton>
+    </div>
+  </div>
+);
+
+const IconOnlyTemplate = ({isDisabled, size, variant}: ToggleButton["RootProps"]) => (
+  <div className="flex gap-3">
+    <ToggleButton isIconOnly isDisabled={isDisabled} size={size} variant={variant}>
+      <Icon icon="gravity-ui:heart" />
+    </ToggleButton>
+    <ToggleButton isIconOnly isDisabled={isDisabled} size={size} variant={variant ?? "ghost"}>
+      <Icon icon="gravity-ui:bookmark" />
+    </ToggleButton>
+  </div>
+);
+
+const ControlledTemplate = () => {
+  const [isSelected, setIsSelected] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex gap-3">
+        <ToggleButton isSelected={isSelected} onChange={setIsSelected}>
+          {({isSelected: selected}) => (
+            <>
+              <Icon icon={selected ? "gravity-ui:heart-fill" : "gravity-ui:heart"} />
+              {selected ? "Liked" : "Like"}
+            </>
+          )}
+        </ToggleButton>
+      </div>
+      <p className="text-sm text-muted">
+        Status: <span className="font-medium">{isSelected ? "Selected" : "Not selected"}</span>
+      </p>
+    </div>
+  );
+};
+
+const DisabledTemplate = () => (
+  <div className="flex gap-3">
+    <ToggleButton isDisabled>
+      <Icon icon="gravity-ui:heart" />
+      Like
+    </ToggleButton>
+    <ToggleButton defaultSelected isDisabled>
+      <Icon icon="gravity-ui:heart-fill" />
+      Like
+    </ToggleButton>
+  </div>
+);
+
+const RealWorldTemplate = () => {
+  const [bookmarked, setBookmarked] = useState(false);
+  const [liked, setLiked] = useState(false);
+  const [pinned, setPinned] = useState(true);
+
+  return (
+    <div className="flex items-center gap-2">
+      <ToggleButton isSelected={liked} size="sm" onChange={setLiked}>
+        {({isSelected}) => (
+          <>
+            <Icon icon={isSelected ? "gravity-ui:heart-fill" : "gravity-ui:heart"} />
+            Like
+          </>
+        )}
+      </ToggleButton>
+      <ToggleButton isSelected={bookmarked} size="sm" variant="ghost" onChange={setBookmarked}>
+        {({isSelected}) => (
+          <>
+            <Icon icon={isSelected ? "gravity-ui:bookmark-fill" : "gravity-ui:bookmark"} />
+            Save
+          </>
+        )}
+      </ToggleButton>
+      <ToggleButton isIconOnly isSelected={pinned} size="sm" variant="ghost" onChange={setPinned}>
+        {({isSelected}) => <Icon icon={isSelected ? "gravity-ui:pin-fill" : "gravity-ui:pin"} />}
+      </ToggleButton>
+    </div>
+  );
+};
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const Variants = {
+  args: defaultArgs,
+  render: VariantsTemplate,
+};
+
+export const Sizes = {
+  render: SizesTemplate,
+};
+
+export const IconOnly = {
+  args: defaultArgs,
+  render: IconOnlyTemplate,
+};
+
+export const Controlled = {
+  render: ControlledTemplate,
+};
+
+export const Disabled = {
+  render: DisabledTemplate,
+};
+
+export const RealWorld = {
+  render: RealWorldTemplate,
+};
diff --git a/packages/react/src/components/toggle-button/toggle-button.tsx b/packages/react/src/components/toggle-button/toggle-button.tsx
new file mode 100644
index 0000000..26ece9e
--- /dev/null
+++ b/packages/react/src/components/toggle-button/toggle-button.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import type {ToggleButtonVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {toggleButtonVariants} from "@heroui/styles";
+import {use} from "react";
+import {ToggleButton as ToggleButtonPrimitive} from "react-aria-components/ToggleButton";
+
+import {composeTwRenderProps} from "../../utils";
+import {ToggleButtonGroupContext} from "../toggle-button-group";
+
+/* -------------------------------------------------------------------------------------------------
+ * ToggleButton Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ToggleButtonRootProps
+  extends ComponentPropsWithRef<typeof ToggleButtonPrimitive>, ToggleButtonVariants {}
+
+const ToggleButtonRoot = ({
+  children,
+  className,
+  isIconOnly,
+  size,
+  style,
+  variant,
+  ...rest
+}: ToggleButtonRootProps) => {
+  const groupContext = use(ToggleButtonGroupContext);
+
+  // Merge props with precedence: direct props > context props
+  const finalSize = size ?? groupContext?.size;
+
+  const styles = toggleButtonVariants({
+    isIconOnly,
+    size: finalSize,
+    variant,
+  });
+
+  return (
+    <ToggleButtonPrimitive
+      className={composeTwRenderProps(className, styles)}
+      data-slot="toggle-button"
+      style={style}
+      {...rest}
+    >
+      {(renderProps) => (typeof children === "function" ? children(renderProps) : children)}
+    </ToggleButtonPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ToggleButtonRoot};
+
+export type {ToggleButtonRootProps};
diff --git a/packages/react/src/components/toolbar/index.ts b/packages/react/src/components/toolbar/index.ts
new file mode 100644
index 0000000..f74b4bd
--- /dev/null
+++ b/packages/react/src/components/toolbar/index.ts
@@ -0,0 +1,29 @@
+import type {ComponentProps} from "react";
+
+import {ToolbarRoot} from "./toolbar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Toolbar = Object.assign(ToolbarRoot, {
+  Root: ToolbarRoot,
+});
+
+export type Toolbar = {
+  Props: ComponentProps<typeof ToolbarRoot>;
+  RootProps: ComponentProps<typeof ToolbarRoot>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {ToolbarRoot} from "./toolbar";
+
+export type {ToolbarRootProps, ToolbarRootProps as ToolbarProps} from "./toolbar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {toolbarVariants} from "@heroui/styles";
+
+export type {ToolbarVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/toolbar/toolbar.stories.tsx b/packages/react/src/components/toolbar/toolbar.stories.tsx
new file mode 100644
index 0000000..0bbfbfe
--- /dev/null
+++ b/packages/react/src/components/toolbar/toolbar.stories.tsx
@@ -0,0 +1,166 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {ButtonGroup} from "../button-group";
+import {Separator} from "../separator";
+import {ToggleButton} from "../toggle-button";
+import {ToggleButtonGroup} from "../toggle-button-group";
+
+import {Toolbar} from "./index";
+
+const meta: Meta<typeof Toolbar> = {
+  argTypes: {
+    orientation: {
+      control: "select",
+      options: ["horizontal", "vertical"],
+    },
+  },
+  component: Toolbar,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Layout/Toolbar",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Toolbar>;
+
+export const Default: Story = {
+  render: () => (
+    <Toolbar aria-label="Text formatting">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Icon icon="gravity-ui:bold" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup>
+        <Button isIconOnly aria-label="Copy" variant="secondary">
+          <Icon icon="gravity-ui:copy" />
+        </Button>
+        <ButtonGroup.Separator />
+        <Button isIconOnly aria-label="Cut" variant="secondary">
+          <Icon icon="gravity-ui:scissors" />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  ),
+};
+
+export const Vertical: Story = {
+  render: () => (
+    <Toolbar aria-label="Tools" orientation="vertical">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Icon icon="gravity-ui:bold" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup>
+        <Button isIconOnly aria-label="Undo" variant="secondary">
+          <Icon icon="gravity-ui:arrow-uturn-ccw-left" />
+        </Button>
+        <ButtonGroup.Separator />
+        <Button isIconOnly aria-label="Redo" variant="secondary">
+          <Icon icon="gravity-ui:arrow-uturn-cw-right" />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  ),
+};
+
+export const WithButtonGroup: Story = {
+  render: () => (
+    <Toolbar aria-label="Editor toolbar">
+      <ButtonGroup>
+        <Button variant="secondary">
+          <Icon icon="gravity-ui:arrow-uturn-ccw-left" />
+          Undo
+        </Button>
+        <ButtonGroup.Separator />
+        <Button variant="secondary">
+          <Icon icon="gravity-ui:arrow-uturn-cw-right" />
+          Redo
+        </Button>
+      </ButtonGroup>
+      <Separator />
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Icon icon="gravity-ui:bold" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup>
+        <Button isIconOnly aria-label="Align left" variant="secondary">
+          <Icon icon="gravity-ui:text-align-left" />
+        </Button>
+        <ButtonGroup.Separator />
+        <Button isIconOnly aria-label="Align center" variant="secondary">
+          <Icon icon="gravity-ui:text-align-center" />
+        </Button>
+        <ButtonGroup.Separator />
+        <Button isIconOnly aria-label="Align right" variant="secondary">
+          <Icon icon="gravity-ui:text-align-right" />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  ),
+};
+
+export const Attached: Story = {
+  render: () => (
+    <Toolbar isAttached aria-label="Attached toolbar">
+      <ToggleButtonGroup aria-label="Text style" selectionMode="multiple">
+        <ToggleButton isIconOnly aria-label="Bold" id="bold">
+          <Icon icon="gravity-ui:bold" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Italic" id="italic">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:italic" />
+        </ToggleButton>
+        <ToggleButton isIconOnly aria-label="Underline" id="underline">
+          <ToggleButtonGroup.Separator />
+          <Icon icon="gravity-ui:underline" />
+        </ToggleButton>
+      </ToggleButtonGroup>
+      <Separator />
+      <ButtonGroup>
+        <Button isIconOnly aria-label="Copy" variant="secondary">
+          <Icon icon="gravity-ui:copy" />
+        </Button>
+        <ButtonGroup.Separator />
+        <Button isIconOnly aria-label="Cut" variant="secondary">
+          <Icon icon="gravity-ui:scissors" />
+        </Button>
+      </ButtonGroup>
+    </Toolbar>
+  ),
+};
diff --git a/packages/react/src/components/toolbar/toolbar.tsx b/packages/react/src/components/toolbar/toolbar.tsx
new file mode 100644
index 0000000..6079280
--- /dev/null
+++ b/packages/react/src/components/toolbar/toolbar.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import type {ToolbarVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef} from "react";
+
+import {toolbarVariants} from "@heroui/styles";
+import React from "react";
+import {SeparatorContext} from "react-aria-components/Separator";
+import {ToggleButtonGroupContext} from "react-aria-components/ToggleButtonGroup";
+import {Toolbar as ToolbarPrimitive} from "react-aria-components/Toolbar";
+
+import {composeTwRenderProps} from "../../utils";
+
+/* -------------------------------------------------------------------------------------------------
+ * Toolbar Root
+ * -----------------------------------------------------------------------------------------------*/
+interface ToolbarRootProps
+  extends ComponentPropsWithRef<typeof ToolbarPrimitive>, ToolbarVariants {}
+
+const ToolbarRoot = ({
+  children,
+  className,
+  isAttached,
+  orientation = "horizontal",
+  ...props
+}: ToolbarRootProps) => {
+  const styles = React.useMemo(
+    () => toolbarVariants({isAttached, orientation}),
+    [isAttached, orientation],
+  );
+
+  return (
+    <ToggleButtonGroupContext.Provider value={{orientation}}>
+      <SeparatorContext.Provider
+        value={{orientation: orientation === "horizontal" ? "vertical" : "horizontal"}}
+      >
+        <ToolbarPrimitive
+          className={composeTwRenderProps(className, styles)}
+          data-slot="toolbar"
+          orientation={orientation}
+          {...props}
+        >
+          {children}
+        </ToolbarPrimitive>
+      </SeparatorContext.Provider>
+    </ToggleButtonGroupContext.Provider>
+  );
+};
+
+ToolbarRoot.displayName = "HeroUI.Toolbar";
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {ToolbarRoot};
+export type {ToolbarRootProps};
diff --git a/packages/react/src/components/tooltip/index.ts b/packages/react/src/components/tooltip/index.ts
new file mode 100644
index 0000000..a00d3bd
--- /dev/null
+++ b/packages/react/src/components/tooltip/index.ts
@@ -0,0 +1,41 @@
+import type {ComponentProps} from "react";
+
+import {TooltipArrow, TooltipContent, TooltipRoot, TooltipTrigger} from "./tooltip";
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+export const Tooltip = Object.assign(TooltipRoot, {
+  Root: TooltipRoot,
+  Trigger: TooltipTrigger,
+  Content: TooltipContent,
+  Arrow: TooltipArrow,
+});
+
+export type Tooltip = {
+  Props: ComponentProps<typeof TooltipRoot>;
+  RootProps: ComponentProps<typeof TooltipRoot>;
+  TriggerProps: ComponentProps<typeof TooltipTrigger>;
+  ContentProps: ComponentProps<typeof TooltipContent>;
+  ArrowProps: ComponentProps<typeof TooltipArrow>;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Named Component
+ * -----------------------------------------------------------------------------------------------*/
+export {TooltipRoot, TooltipTrigger, TooltipContent, TooltipArrow};
+
+export type {
+  TooltipRootProps,
+  TooltipRootProps as TooltipProps,
+  TooltipArrowProps,
+  TooltipContentProps,
+  TooltipTriggerProps,
+} from "./tooltip";
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+export {tooltipVariants} from "@heroui/styles";
+
+export type {TooltipVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/tooltip/tooltip.stories.tsx b/packages/react/src/components/tooltip/tooltip.stories.tsx
new file mode 100644
index 0000000..2e4692b
--- /dev/null
+++ b/packages/react/src/components/tooltip/tooltip.stories.tsx
@@ -0,0 +1,122 @@
+import type {Meta} from "@storybook/react";
+
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {Button} from "../button";
+import {Card} from "../card";
+
+import {Tooltip} from "./index";
+
+export default {
+  argTypes: {
+    offset: {
+      control: "number",
+    },
+    placement: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom left",
+        "bottom right",
+        "bottom start",
+        "bottom end",
+        "top",
+        "top left",
+        "top right",
+        "top start",
+        "top end",
+        "left",
+        "left top",
+        "left bottom",
+        "start",
+        "start top",
+        "start bottom",
+        "right",
+        "right top",
+        "right bottom",
+        "end",
+        "end top",
+        "end bottom",
+      ],
+    },
+  },
+  component: Tooltip,
+  parameters: {
+    layout: "centered",
+  },
+  title: "Components/Overlays/Tooltip",
+} as Meta<typeof Tooltip>;
+
+const defaultArgs: Omit<Tooltip["ContentProps"], "children"> = {
+  showArrow: true,
+};
+
+const Template = (props: Tooltip["ContentProps"]) => (
+  <div className="flex items-center justify-center gap-3">
+    <Tooltip delay={0}>
+      <Button isIconOnly variant="tertiary">
+        <Icon icon="gravity-ui:circle-info" />
+      </Button>
+      <Tooltip.Content {...props}>
+        <Tooltip.Arrow />
+        <p>Tooltip content</p>
+      </Tooltip.Content>
+    </Tooltip>
+  </div>
+);
+
+const TemplateWithTrigger = (props: Tooltip["ContentProps"]) => (
+  <div className="flex items-center gap-3">
+    <Tooltip delay={0}>
+      <Tooltip.Trigger aria-label="Tooltip trigger">
+        <div className="rounded-full bg-accent-soft p-2">
+          <Icon icon="gravity-ui:circle-info" />
+        </div>
+      </Tooltip.Trigger>
+      <Tooltip.Content {...props}>
+        <Tooltip.Arrow />
+        <p>Tooltip content</p>
+      </Tooltip.Content>
+    </Tooltip>
+  </div>
+);
+
+export const Default = {
+  args: defaultArgs,
+  render: Template,
+};
+
+export const WithTrigger = {
+  args: defaultArgs,
+  render: TemplateWithTrigger,
+};
+
+const CardWithTooltipTemplate = (props: Tooltip["ContentProps"]) => (
+  <Card className="w-[200px]">
+    <Card.Content className="flex items-center justify-center p-6">
+      <Tooltip delay={0}>
+        <Tooltip.Trigger aria-label="Attach a file">
+          <Button
+            isIconOnly
+            aria-label="Attach file"
+            className="rounded-full"
+            size="lg"
+            variant="secondary"
+          >
+            <Icon icon="gravity-ui:paperclip" />
+          </Button>
+        </Tooltip.Trigger>
+        <Tooltip.Content {...props}>
+          <Tooltip.Arrow />
+          <p>Attach a file</p>
+        </Tooltip.Content>
+      </Tooltip>
+    </Card.Content>
+  </Card>
+);
+
+export const CardWithTooltip = {
+  args: defaultArgs,
+  render: CardWithTooltipTemplate,
+};
diff --git a/packages/react/src/components/tooltip/tooltip.tsx b/packages/react/src/components/tooltip/tooltip.tsx
new file mode 100644
index 0000000..5882c78
--- /dev/null
+++ b/packages/react/src/components/tooltip/tooltip.tsx
@@ -0,0 +1,179 @@
+"use client";
+
+import type {DOMRenderProps} from "../../utils/dom";
+import type {TooltipVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {tooltipVariants} from "@heroui/styles";
+import {mergeProps} from "@react-aria/utils";
+import React, {createContext, use, useRef} from "react";
+import {useFocusable} from "react-aria/useFocusable";
+import {
+  OverlayArrow,
+  Tooltip as TooltipPrimitive,
+  TooltipTrigger as TooltipTriggerPrimitive,
+} from "react-aria-components/Tooltip";
+
+import {useCSSVariable} from "../../hooks/use-css-variable";
+import {composeSlotClassName, composeTwRenderProps} from "../../utils/compose";
+import {parseCSSTime} from "../../utils/css";
+import {dom} from "../../utils/dom";
+
+/* -------------------------------------------------------------------------------------------------
+ * Tooltip Context
+ * -----------------------------------------------------------------------------------------------*/
+type TooltipContext = {
+  slots?: ReturnType<typeof tooltipVariants>;
+};
+
+const TooltipContext = createContext<TooltipContext>({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Tooltip Root
+ * -----------------------------------------------------------------------------------------------*/
+type TooltipRootProps = ComponentPropsWithRef<typeof TooltipTriggerPrimitive>;
+
+const TooltipRoot = ({
+  children,
+  closeDelay,
+  delay,
+  ...props
+}: ComponentPropsWithRef<typeof TooltipTriggerPrimitive>) => {
+  const slots = React.useMemo(() => tooltipVariants(), []);
+
+  const cssDelay = useCSSVariable("--tooltip-delay");
+  const cssCloseDelay = useCSSVariable("--tooltip-close-delay");
+
+  const resolvedDelay = delay ?? parseCSSTime(cssDelay);
+  const resolvedCloseDelay = closeDelay ?? parseCSSTime(cssCloseDelay);
+
+  return (
+    <TooltipContext value={{slots}}>
+      <TooltipTriggerPrimitive
+        closeDelay={resolvedCloseDelay}
+        data-slot="tooltip-root"
+        delay={resolvedDelay}
+        {...props}
+      >
+        {children}
+      </TooltipTriggerPrimitive>
+    </TooltipContext>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tooltip Content
+ * -----------------------------------------------------------------------------------------------*/
+interface TooltipContentProps
+  extends Omit<ComponentPropsWithRef<typeof TooltipPrimitive>, "children">, TooltipVariants {
+  showArrow?: boolean;
+  children: React.ReactNode;
+}
+
+const TooltipContent = ({
+  children,
+  className,
+  offset: offsetProp,
+  showArrow = false,
+  ...props
+}: TooltipContentProps) => {
+  const {slots} = use(TooltipContext);
+  const offset = offsetProp ? offsetProp : showArrow ? 7 : 3;
+
+  return (
+    <TooltipPrimitive
+      {...props}
+      className={composeTwRenderProps(className, slots?.base())}
+      offset={offset}
+    >
+      {children}
+    </TooltipPrimitive>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tooltip Arrow
+ * -----------------------------------------------------------------------------------------------*/
+type TooltipArrowProps = Omit<ComponentPropsWithRef<typeof OverlayArrow>, "children"> & {
+  children?: React.ReactNode;
+};
+
+const TooltipArrow = ({children, className, ...props}: TooltipArrowProps) => {
+  const defaultArrow = (
+    <svg
+      data-slot="overlay-arrow"
+      fill="none"
+      height="12"
+      viewBox="0 0 12 12"
+      width="12"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M0 0C5.48483 8 6.5 8 12 0Z" />
+    </svg>
+  );
+
+  const arrow = React.isValidElement(children)
+    ? React.cloneElement(
+        children as React.ReactElement<{
+          className?: string;
+          "data-slot"?: "overlay-arrow";
+        }>,
+        {
+          "data-slot": "overlay-arrow",
+        },
+      )
+    : defaultArrow;
+
+  return (
+    <OverlayArrow data-slot="tooltip-arrow" {...props} className={className}>
+      {arrow}
+    </OverlayArrow>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Tooltip Trigger
+ * -----------------------------------------------------------------------------------------------*/
+interface TooltipTriggerProps<
+  E extends keyof React.JSX.IntrinsicElements = "div",
+> extends DOMRenderProps<E, undefined> {
+  children?: ReactNode;
+  className?: string;
+}
+
+const TooltipTrigger = <E extends keyof React.JSX.IntrinsicElements = "div">({
+  children,
+  className,
+  ...props
+}: TooltipTriggerProps<E> & Omit<React.JSX.IntrinsicElements[E], keyof TooltipTriggerProps<E>>) => {
+  const {slots} = use(TooltipContext);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  // Use the `useFocusable` hook directly rather than the `<Focusable>` wrapper component.
+  // Both consume the FocusableContext provided by TooltipTriggerPrimitive's internal
+  // <FocusableProvider> (which carries the tooltip trigger props + triggerRef) and produce
+  // the same `focusableProps` (tabIndex, focus, keyboard handlers). However, the wrapper
+  // component runs a dev-only `isFocusable(el)` assertion in a useEffect that walks the
+  // ancestor chain for `inert`. When the Tooltip mounts inside an inert subtree (e.g. behind
+  // an open Drawer/Modal), that check produces a false-positive warning:
+  // "<Focusable> child must be focusable. Please ensure the tabIndex prop is passed through."
+  const {focusableProps} = useFocusable({}, triggerRef as React.RefObject<HTMLElement>);
+
+  return (
+    <dom.div
+      ref={triggerRef as unknown as React.Ref<HTMLDivElement>}
+      className={composeSlotClassName(slots?.trigger, className)}
+      data-slot="tooltip-trigger"
+      role="button"
+      {...mergeProps(focusableProps, props as any)}
+    >
+      {children}
+    </dom.div>
+  );
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Exports
+ * -----------------------------------------------------------------------------------------------*/
+export {TooltipRoot, TooltipTrigger, TooltipContent, TooltipArrow};
+
+export type {TooltipRootProps, TooltipArrowProps, TooltipContentProps, TooltipTriggerProps};
diff --git a/packages/react/src/components/typography/index.ts b/packages/react/src/components/typography/index.ts
new file mode 100644
index 0000000..8dc636f
--- /dev/null
+++ b/packages/react/src/components/typography/index.ts
@@ -0,0 +1,35 @@
+import type {ComponentProps} from "react";
+
+import {Code, Heading, Paragraph, Prose, TypographyRoot} from "./typography";
+
+export const Typography = Object.assign(TypographyRoot, {
+  Code,
+  Heading,
+  Paragraph,
+  Prose,
+  Root: TypographyRoot,
+});
+
+export type Typography = {
+  CodeProps: ComponentProps<typeof Code>;
+  HeadingProps: ComponentProps<typeof Heading>;
+  ParagraphProps: ComponentProps<typeof Paragraph>;
+  ProseProps: ComponentProps<typeof Prose>;
+  Props: ComponentProps<typeof TypographyRoot>;
+  RootProps: ComponentProps<typeof TypographyRoot>;
+};
+
+export {Code, Heading, Paragraph, Prose, TypographyRoot};
+
+export type {
+  CodeProps,
+  HeadingProps,
+  ParagraphProps,
+  ProseProps,
+  TypographyRootProps,
+  TypographyRootProps as TypographyProps,
+} from "./typography";
+
+export {typographyVariants} from "@heroui/styles";
+
+export type {TypographyVariants} from "@heroui/styles";
diff --git a/packages/react/src/components/typography/typography.stories.tsx b/packages/react/src/components/typography/typography.stories.tsx
new file mode 100644
index 0000000..fbde55a
--- /dev/null
+++ b/packages/react/src/components/typography/typography.stories.tsx
@@ -0,0 +1,328 @@
+import type {Meta, StoryObj} from "@storybook/react";
+
+import {Typography} from "./index";
+
+const meta: Meta<typeof Typography> = {
+  argTypes: {
+    align: {
+      control: "select",
+      options: ["start", "center", "end", "justify"],
+    },
+    color: {
+      control: "select",
+      options: ["default", "muted"],
+    },
+    type: {
+      control: "select",
+      options: ["h1", "h2", "h3", "h4", "h5", "h6", "body", "body-sm", "body-xs", "code"],
+    },
+    weight: {
+      control: "select",
+      options: ["normal", "medium", "semibold", "bold"],
+    },
+  },
+  component: Typography,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  title: "Components/Typography",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: "HeroUI Typography",
+    type: "body",
+  },
+};
+
+export const HeadingScale: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-6">
+      <Typography.Heading level={1}>Heading Level 1</Typography.Heading>
+      <Typography.Heading level={2}>Heading Level 2</Typography.Heading>
+      <Typography.Heading level={3}>Heading Level 3</Typography.Heading>
+      <Typography.Heading level={4}>Heading Level 4</Typography.Heading>
+      <Typography.Heading level={5}>Heading Level 5</Typography.Heading>
+      <Typography.Heading level={6}>Heading Level 6</Typography.Heading>
+    </div>
+  ),
+};
+
+export const BodySizes: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-6">
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          BODY — DEFAULT (BASE)
+        </Typography>
+        <Typography.Paragraph>
+          Until now, trying to style an article, document, or blog post with Tailwind has been a
+          tedious task that required a keen eye for typography and a lot of complex custom CSS.
+        </Typography.Paragraph>
+      </div>
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          BODY — SMALL
+        </Typography>
+        <Typography.Paragraph size="sm">
+          By default, Tailwind removes all of the default browser styling from paragraphs, headings,
+          lists and more. This ends up being really useful for building application UIs because you
+          spend less time undoing user-agent styles.
+        </Typography.Paragraph>
+      </div>
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          BODY — EXTRA SMALL
+        </Typography>
+        <Typography.Paragraph size="xs">
+          Fine print, captions, and secondary information are rendered at the smallest body size.
+          This size is ideal for metadata, timestamps, or auxiliary details that should not compete
+          with the primary content.
+        </Typography.Paragraph>
+      </div>
+    </div>
+  ),
+};
+
+export const InlineCode: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-4">
+      <Typography.Paragraph>
+        Install the package with <Typography.Code>pnpm add @heroui/react</Typography.Code> and
+        import <Typography.Code>{"<Typography>"}</Typography.Code> from the library.
+      </Typography.Paragraph>
+      <Typography.Paragraph size="sm">
+        The <Typography.Code>typographyVariants</Typography.Code> function accepts{" "}
+        <Typography.Code>type</Typography.Code>, <Typography.Code>align</Typography.Code>,{" "}
+        <Typography.Code>color</Typography.Code>, and <Typography.Code>weight</Typography.Code>{" "}
+        props.
+      </Typography.Paragraph>
+    </div>
+  ),
+};
+
+export const Alignment: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-6">
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          START (DEFAULT)
+        </Typography>
+        <Typography align="start">
+          Text aligned to the start edge. In LTR layouts this means left-aligned; in RTL it flips
+          automatically.
+        </Typography>
+      </div>
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          CENTER
+        </Typography>
+        <Typography align="center">
+          Center-aligned text works well for hero sections, headings, and call-to-action blocks
+          where symmetry is important.
+        </Typography>
+      </div>
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          END
+        </Typography>
+        <Typography align="end">
+          End-aligned text is useful for numerical columns, timestamps, or any content that benefits
+          from right-alignment in LTR contexts.
+        </Typography>
+      </div>
+      <div>
+        <Typography color="muted" type="body-xs" weight="semibold">
+          JUSTIFY
+        </Typography>
+        <Typography align="justify">
+          Justified text stretches each line so that both left and right edges are flush. This style
+          is common in print design and long-form reading experiences where a clean text block is
+          desired.
+        </Typography>
+      </div>
+    </div>
+  ),
+};
+
+export const WeightScale: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-4">
+      <Typography weight="normal">Normal weight — the browser default for body text.</Typography>
+      <Typography weight="medium">Medium weight — slightly heavier for subtle emphasis.</Typography>
+      <Typography weight="semibold">Semibold weight — used for subheadings and labels.</Typography>
+      <Typography weight="bold">Bold weight — strong emphasis for important content.</Typography>
+    </div>
+  ),
+};
+
+export const MutedColor: Story = {
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-4">
+      <Typography.Heading level={3}>Account Settings</Typography.Heading>
+      <Typography.Paragraph>
+        Manage your account preferences and personal information below.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" size="sm">
+        Changes to your profile may take up to 24 hours to propagate across all services. Contact
+        support if you need immediate assistance.
+      </Typography.Paragraph>
+    </div>
+  ),
+};
+
+export const Truncation: Story = {
+  render: () => (
+    <div className="flex max-w-xs flex-col gap-4">
+      <Typography color="muted" type="body-xs" weight="semibold">
+        WITHOUT TRUNCATION
+      </Typography>
+      <Typography>
+        This is a long piece of text that will wrap naturally across multiple lines in a narrow
+        container without any truncation applied.
+      </Typography>
+      <Typography color="muted" type="body-xs" weight="semibold">
+        WITH TRUNCATION
+      </Typography>
+      <Typography truncate>
+        This is a long piece of text that will be truncated with an ellipsis when it exceeds the
+        available width of its container.
+      </Typography>
+    </div>
+  ),
+};
+
+export const ArticleExample: Story = {
+  render: () => (
+    <article className="flex max-w-2xl flex-col gap-4">
+      <Typography.Heading level={1}>Crafting a Design System</Typography.Heading>
+      <Typography.Paragraph color="muted" size="sm">
+        Published May 2026 · 8 min read
+      </Typography.Paragraph>
+      <Typography.Paragraph>
+        A design system is more than a collection of reusable components. It is a shared language
+        that unifies product teams, accelerates development, and ensures visual consistency at every
+        level of an application.
+      </Typography.Paragraph>
+      <Typography.Heading level={2}>Why Typography Matters</Typography.Heading>
+      <Typography.Paragraph>
+        Typography accounts for roughly 95% of web design. The typefaces you choose, the scale you
+        define, and the rhythm you establish between headings and body text determine how users
+        perceive your product before they interact with a single button or form.
+      </Typography.Paragraph>
+      <Typography.Paragraph>
+        A well-tuned type scale creates a clear visual hierarchy. Readers can scan a page, locate
+        the information they need, and absorb your content without friction.
+      </Typography.Paragraph>
+      <Typography.Heading level={3}>Building the Scale</Typography.Heading>
+      <Typography.Paragraph>
+        Start with a base size — <Typography.Code>16px</Typography.Code> (1rem) is the industry
+        standard — and derive heading sizes using a consistent ratio. HeroUI uses a tracking-tight
+        heading stack from <Typography.Code>text-base</Typography.Code> through{" "}
+        <Typography.Code>text-4xl</Typography.Code>, giving six levels of hierarchy.
+      </Typography.Paragraph>
+      <Typography.Heading level={3}>Readable Body Copy</Typography.Heading>
+      <Typography.Paragraph>
+        Good body text should feel effortless to read. A line height of 1.75 (Tailwind's{" "}
+        <Typography.Code>leading-7</Typography.Code>) paired with a measure of roughly 65 characters
+        keeps readers comfortable across long passages.
+      </Typography.Paragraph>
+      <Typography.Paragraph color="muted" size="sm">
+        Shorter paragraphs, generous whitespace, and intentional weight contrast all contribute to
+        readability. These defaults work out of the box with HeroUI's Typography primitive.
+      </Typography.Paragraph>
+    </article>
+  ),
+};
+
+export const ProseBlock: Story = {
+  render: () => (
+    <Typography.Prose className="max-w-2xl">
+      <h1>Getting Started with HeroUI</h1>
+      <p>
+        HeroUI is a modern React component library built on top of <strong>Tailwind CSS v4</strong>{" "}
+        and <strong>React Aria</strong>. It provides accessible, customizable primitives that you
+        can compose into complex interfaces.
+      </p>
+
+      <h2>Installation</h2>
+      <p>
+        Add the library to your project using your preferred package manager. The{" "}
+        <code>@heroui/react</code> package includes every component:
+      </p>
+      <pre>
+        <code>pnpm add @heroui/react</code>
+      </pre>
+
+      <h3>Quick Setup</h3>
+      <p>
+        Import the stylesheet in your application entry point and wrap your app with the provider:
+      </p>
+
+      <blockquote>
+        Good design is as little design as possible. Less, but better — because it concentrates on
+        the essential aspects, and the products are not burdened with non-essentials.
+      </blockquote>
+
+      <h3>Key Features</h3>
+      <ul>
+        <li>Fully accessible components built on React Aria primitives</li>
+        <li>Compound component API inspired by Radix UI for maximum flexibility</li>
+        <li>Tailwind CSS v4 styling with BEM-inspired class naming</li>
+        <li>TypeScript-first with comprehensive type exports</li>
+        <li>Dark mode support out of the box via CSS custom properties</li>
+      </ul>
+
+      <h3>Component Categories</h3>
+      <ol>
+        <li>
+          <strong>Layout</strong> — Card, Surface, Header, Separator
+        </li>
+        <li>
+          <strong>Navigation</strong> — Tabs, Accordion, Breadcrumbs, Link
+        </li>
+        <li>
+          <strong>Forms</strong> — TextField, Checkbox, Radio, Select, Switch
+        </li>
+        <li>
+          <strong>Feedback</strong> — Alert, Spinner, Toast, Progress
+        </li>
+        <li>
+          <strong>Typography</strong> — Typography, Heading, Code, Prose
+        </li>
+      </ol>
+
+      <hr />
+
+      <h2>Next Steps</h2>
+      <p>
+        Explore the <a href="https://heroui.com">component stories</a> in Storybook to see every
+        variant and composition in action. Each component ships with comprehensive documentation and
+        live examples.
+      </p>
+    </Typography.Prose>
+  ),
+};
+
+export const CompoundPrimitives: Story = {
+  render: () => (
+    <div className="flex max-w-xl flex-col gap-4">
+      <Typography.Heading level={1}>Dashboard</Typography.Heading>
+      <Typography.Paragraph>
+        Convenience primitives are thin wrappers over Typography for explicit composition. Use{" "}
+        <Typography.Code>Typography.Heading</Typography.Code>,{" "}
+        <Typography.Code>Typography.Paragraph</Typography.Code>, and{" "}
+        <Typography.Code>Typography.Code</Typography.Code> when you want the semantic element chosen
+        automatically.
+      </Typography.Paragraph>
+      <Typography.Heading level={4}>Recent Activity</Typography.Heading>
+      <Typography.Paragraph color="muted" size="sm">
+        No new notifications. Check back later for updates on your projects and team activity.
+      </Typography.Paragraph>
+    </div>
+  ),
+};
diff --git a/packages/react/src/components/typography/typography.tsx b/packages/react/src/components/typography/typography.tsx
new file mode 100644
index 0000000..8fb03d2
--- /dev/null
+++ b/packages/react/src/components/typography/typography.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import type {TypographyVariants} from "@heroui/styles";
+import type {ComponentPropsWithRef, ReactNode} from "react";
+
+import {typographyVariants} from "@heroui/styles";
+import {Text as TextPrimitive} from "react-aria-components/Text";
+
+import {composeSlotClassName} from "../../utils/compose";
+
+type TypographyType = NonNullable<TypographyVariants["type"]>;
+type TypographyAlign = NonNullable<TypographyVariants["align"]>;
+type TypographyColor = NonNullable<TypographyVariants["color"]>;
+type TypographyWeight = NonNullable<TypographyVariants["weight"]>;
+
+const defaultElementByType: Record<TypographyType, string> = {
+  body: "p",
+  "body-sm": "p",
+  "body-xs": "p",
+  code: "code",
+  h1: "h1",
+  h2: "h2",
+  h3: "h3",
+  h4: "h4",
+  h5: "h5",
+  h6: "h6",
+};
+
+interface TypographyRootProps extends Omit<
+  ComponentPropsWithRef<typeof TextPrimitive>,
+  "className" | "elementType"
+> {
+  align?: TypographyAlign;
+  children?: ReactNode;
+  className?: string;
+  color?: TypographyColor;
+  type?: TypographyType;
+  truncate?: boolean;
+  weight?: TypographyWeight;
+}
+
+const TypographyRoot = ({
+  align = "start",
+  children,
+  className,
+  color = "default",
+  truncate,
+  type = "body",
+  weight,
+  ...props
+}: TypographyRootProps) => {
+  const slots = typographyVariants({align, color, truncate, type, weight});
+
+  return (
+    <TextPrimitive
+      className={composeSlotClassName(slots.base, className)}
+      data-slot="typography"
+      data-type={type}
+      elementType={defaultElementByType[type]}
+      {...props}
+    >
+      {children}
+    </TextPrimitive>
+  );
+};
+
+interface HeadingProps extends Omit<TypographyRootProps, "type"> {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+const Heading = ({level = 1, ...props}: HeadingProps) => {
+  return <TypographyRoot type={`h${level}` as TypographyType} {...props} />;
+};
+
+interface ParagraphProps extends Omit<TypographyRootProps, "type"> {
+  size?: "base" | "sm" | "xs";
+}
+
+const Paragraph = ({size = "base", ...props}: ParagraphProps) => {
+  const type = size === "base" ? "body" : (`body-${size}` as TypographyType);
+
+  return <TypographyRoot type={type} {...props} />;
+};
+
+interface CodeProps extends Omit<TypographyRootProps, "type"> {}
+
+const Code = (props: CodeProps) => {
+  return <TypographyRoot type="code" {...props} />;
+};
+
+interface ProseProps extends Omit<ComponentPropsWithRef<"div">, "color"> {
+  children: ReactNode;
+}
+
+const Prose = ({children, className, ...props}: ProseProps) => {
+  const slots = typographyVariants();
+
+  return (
+    <div className={composeSlotClassName(slots.prose, className)} data-slot="prose" {...props}>
+      {children}
+    </div>
+  );
+};
+
+export {Code, Heading, Paragraph, Prose, TypographyRoot};
+
+export type {CodeProps, HeadingProps, ParagraphProps, ProseProps, TypographyRootProps};
diff --git a/packages/react/src/hooks/index.ts b/packages/react/src/hooks/index.ts
new file mode 100644
index 0000000..b7c2467
--- /dev/null
+++ b/packages/react/src/hooks/index.ts
@@ -0,0 +1,10 @@
+export * from "./use-css-variable";
+export * from "./use-is-hydrated";
+export * from "./use-list-data";
+export * from "./use-measured-height";
+export * from "./use-mounted";
+export * from "./use-overlay-state";
+export * from "./use-safe-layout-effect";
+export * from "./use-isomorphic-layout-effect";
+export * from "./use-media-query";
+export * from "./use-theme";
diff --git a/packages/react/src/hooks/use-css-variable.ts b/packages/react/src/hooks/use-css-variable.ts
new file mode 100644
index 0000000..ad360df
--- /dev/null
+++ b/packages/react/src/hooks/use-css-variable.ts
@@ -0,0 +1,78 @@
+"use client";
+
+import {useIsSSR} from "@react-aria/ssr";
+import * as React from "react";
+
+// Cache for CSS variable values to avoid repeated DOM queries
+const cssVariableCache = new Map<string, string | undefined>();
+
+/**
+ * A hook that safely retrieves CSS custom property values from the document element
+ * with SSR support, automatic fallback handling, and optional caching.
+ *
+ * @example
+ * ```jsx
+ * function Component() {
+ *   const animationType = useCSSVariable('--skeleton-animation')
+ *   // Returns the CSS variable value or undefined (cached by default)
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * function Component({ color }) {
+ *   // Override with prop if provided
+ *   const themeColor = useCSSVariable('--theme-color', color)
+ *   // Returns color prop if defined, otherwise CSS variable value
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * function Component() {
+ *   // Disable caching for dynamic CSS variables
+ *   const dynamicValue = useCSSVariable('--dynamic-value', undefined, false)
+ *   // Will always query the DOM for fresh value
+ * }
+ * ```
+ *
+ * @param variableName - The CSS custom property name (e.g., '--my-variable')
+ * @param override - Optional override value that takes precedence over CSS variable
+ * @param cache - Whether to cache the CSS variable value (default: true)
+ * @returns The CSS variable value, override value, or undefined
+ */
+export function useCSSVariable(
+  variableName: string,
+  override?: string,
+  cache: boolean = true,
+): string | undefined {
+  const isSSR = useIsSSR();
+
+  return React.useMemo(() => {
+    // Return override if provided
+    if (override !== undefined) return override;
+
+    // Return undefined during SSR
+    if (isSSR) return undefined;
+
+    // Check cache first if caching is enabled
+    if (cache && cssVariableCache.has(variableName)) {
+      return cssVariableCache.get(variableName);
+    }
+
+    try {
+      const root = document.documentElement;
+      const value = getComputedStyle(root).getPropertyValue(variableName).trim() || undefined;
+
+      // Cache the value if caching is enabled
+      if (cache) {
+        cssVariableCache.set(variableName, value);
+      }
+
+      return value;
+    } catch {
+      // Return undefined if any error occurs (e.g., document not available)
+      return undefined;
+    }
+  }, [variableName, override, isSSR, cache]);
+}
diff --git a/packages/react/src/hooks/use-is-hydrated.ts b/packages/react/src/hooks/use-is-hydrated.ts
new file mode 100644
index 0000000..86a38ca
--- /dev/null
+++ b/packages/react/src/hooks/use-is-hydrated.ts
@@ -0,0 +1,30 @@
+import * as React from "react";
+
+/**
+ * A hook that returns true if the component is mounted on the client (hydrated)
+ * and false when rendering on the server.
+ *
+ * @example
+ * ```jsx
+ * function Component() {
+ *   const isHydrated = useIsHydrated()
+ *
+ *   if (!isHydrated) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   return <div>Client rendered content</div>
+ * }
+ * ```
+ * @returns boolean indicating if the component is hydrated
+ */
+
+export function useIsHydrated() {
+  const subscribe = () => () => {};
+
+  return React.useSyncExternalStore(
+    subscribe,
+    () => true,
+    () => false,
+  );
+}
diff --git a/packages/react/src/hooks/use-isomorphic-layout-effect.ts b/packages/react/src/hooks/use-isomorphic-layout-effect.ts
new file mode 100644
index 0000000..5d0d8a4
--- /dev/null
+++ b/packages/react/src/hooks/use-isomorphic-layout-effect.ts
@@ -0,0 +1,6 @@
+"use client";
+
+import {useEffect, useLayoutEffect} from "react";
+
+export const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
diff --git a/packages/react/src/hooks/use-list-data.ts b/packages/react/src/hooks/use-list-data.ts
new file mode 100644
index 0000000..b19a6f5
--- /dev/null
+++ b/packages/react/src/hooks/use-list-data.ts
@@ -0,0 +1,473 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ *
+ * This file is based on the useListData hook from @react-stately/data package.
+ * Original source: https://github.com/adobe/react-spectrum/blob/main/packages/%40react-stately/data/src/useListData.ts
+ *
+ * Why we copied this code instead of using @react-stately/data as a dependency:
+ * We copied this implementation to avoid adding @react-stately/data as a dependency, which is a
+ * large package that would significantly increase our bundle size. We maintain full attribution to
+ * Adobe and comply with the Apache License 2.0 requirements.
+ */
+"use client";
+
+import type {Key, Selection} from "@react-types/shared";
+
+import {useMemo, useState} from "react";
+
+export interface ListOptions<T> {
+  /** Initial items in the list. */
+  initialItems?: T[];
+  /** The keys for the initially selected items. */
+  initialSelectedKeys?: "all" | Iterable<Key>;
+  /** The initial text to filter the list by. */
+  initialFilterText?: string;
+  /** A function that returns a unique key for an item object. */
+  getKey?: (item: T) => Key;
+  /** A function that returns whether a item matches the current filter text. */
+  filter?: (item: T, filterText: string) => boolean;
+}
+
+export interface ListData<T> {
+  /** The items in the list. */
+  items: T[];
+
+  /** The keys of the currently selected items in the list. */
+  selectedKeys: Selection;
+
+  /** Sets the selected keys. */
+  setSelectedKeys(keys: Selection): void;
+
+  /** Adds the given keys to the current selected keys. */
+  addKeysToSelection(keys: Selection): void;
+
+  /** Removes the given keys from the current selected keys. */
+  removeKeysFromSelection(keys: Selection): void;
+
+  /** The current filter text. */
+  filterText: string;
+
+  /** Sets the filter text. */
+  setFilterText(filterText: string): void;
+
+  /**
+   * Gets an item from the list by key.
+   * @param key - The key of the item to retrieve.
+   */
+  getItem(key: Key): T | undefined;
+
+  /**
+   * Inserts items into the list at the given index.
+   * @param index - The index to insert into.
+   * @param values - The values to insert.
+   */
+  insert(index: number, ...values: T[]): void;
+
+  /**
+   * Inserts items into the list before the item at the given key.
+   * @param key - The key of the item to insert before.
+   * @param values - The values to insert.
+   */
+  insertBefore(key: Key, ...values: T[]): void;
+
+  /**
+   * Inserts items into the list after the item at the given key.
+   * @param key - The key of the item to insert after.
+   * @param values - The values to insert.
+   */
+  insertAfter(key: Key, ...values: T[]): void;
+
+  /**
+   * Appends items to the list.
+   * @param values - The values to insert.
+   */
+  append(...values: T[]): void;
+
+  /**
+   * Prepends items to the list.
+   * @param value - The value to insert.
+   */
+  prepend(...values: T[]): void;
+
+  /**
+   * Removes items from the list by their keys.
+   * @param keys - The keys of the item to remove.
+   */
+  remove(...keys: Key[]): void;
+
+  /**
+   * Removes all items from the list that are currently
+   * in the set of selected items.
+   */
+  removeSelectedItems(): void;
+
+  /**
+   * Moves an item within the list.
+   * @param key - The key of the item to move.
+   * @param toIndex - The index to move the item to.
+   */
+  move(key: Key, toIndex: number): void;
+
+  /**
+   * Moves one or more items before a given key.
+   * @param key - The key of the item to move the items before.
+   * @param keys - The keys of the items to move.
+   */
+  moveBefore(key: Key, keys: Iterable<Key>): void;
+
+  /**
+   * Moves one or more items after a given key.
+   * @param key - The key of the item to move the items after.
+   * @param keys - The keys of the items to move.
+   */
+  moveAfter(key: Key, keys: Iterable<Key>): void;
+
+  /**
+   * Updates an item in the list.
+   * @param key - The key of the item to update.
+   * @param newValue - The new value for the item, or a function that returns the new value based on the previous value.
+   */
+  update(key: Key, newValue: T | ((prev: T) => T)): void;
+}
+
+export interface ListState<T> {
+  items: T[];
+  selectedKeys: Selection;
+  filterText: string;
+}
+
+interface CreateListOptions<T, C> extends ListOptions<T> {
+  cursor?: C;
+}
+
+/**
+ * Manages state for an immutable list data structure, and provides convenience methods to
+ * update the data over time.
+ */
+export function useListData<T>(options: ListOptions<T>): ListData<T> {
+  const {
+    filter,
+    getKey = (item: any) => item.id ?? item.key,
+    initialFilterText = "",
+    initialItems = [],
+    initialSelectedKeys,
+  } = options;
+
+  // Store both items and filteredItems in state so we can go back to the unfiltered list
+  const [state, setState] = useState<ListState<T>>({
+    items: initialItems,
+    selectedKeys: initialSelectedKeys === "all" ? "all" : new Set(initialSelectedKeys || []),
+    filterText: initialFilterText,
+  });
+
+  const filteredItems = useMemo(
+    () => (filter ? state.items.filter((item) => filter(item, state.filterText)) : state.items),
+    [state.items, state.filterText, filter],
+  );
+
+  return {
+    ...state,
+    items: filteredItems,
+    ...createListActions({getKey}, setState),
+    getItem(key: Key) {
+      return state.items.find((item) => getKey(item) === key);
+    },
+  };
+}
+
+export function createListActions<T, C>(
+  opts: CreateListOptions<T, C>,
+  dispatch: (updater: (state: ListState<T>) => ListState<T>) => void,
+): Omit<ListData<T>, "items" | "selectedKeys" | "getItem" | "filterText"> {
+  const {cursor, getKey} = opts;
+
+  return {
+    setSelectedKeys(selectedKeys: Selection) {
+      dispatch((state) => ({
+        ...state,
+        selectedKeys,
+      }));
+    },
+    addKeysToSelection(selectedKeys: Selection) {
+      dispatch((state) => {
+        if (state.selectedKeys === "all") {
+          return state;
+        }
+        if (selectedKeys === "all") {
+          return {
+            ...state,
+            selectedKeys: "all",
+          };
+        }
+
+        return {
+          ...state,
+          selectedKeys: new Set([...state.selectedKeys, ...selectedKeys]),
+        };
+      });
+    },
+    removeKeysFromSelection(selectedKeys: Selection) {
+      dispatch((state) => {
+        if (selectedKeys === "all") {
+          return {
+            ...state,
+            selectedKeys: new Set(),
+          };
+        }
+
+        const selection: Selection =
+          state.selectedKeys === "all"
+            ? new Set(state.items.map(getKey!))
+            : new Set(state.selectedKeys);
+
+        for (const key of selectedKeys) {
+          selection.delete(key);
+        }
+
+        return {
+          ...state,
+          selectedKeys: selection,
+        };
+      });
+    },
+    setFilterText(filterText: string) {
+      dispatch((state) => ({
+        ...state,
+        filterText,
+      }));
+    },
+    insert(index: number, ...values: T[]) {
+      dispatch((state) => insert(state, index, ...values));
+    },
+    insertBefore(key: Key, ...values: T[]) {
+      dispatch((state) => {
+        let index = state.items.findIndex((item) => getKey?.(item) === key);
+
+        if (index === -1) {
+          if (state.items.length === 0) {
+            index = 0;
+          } else {
+            return state;
+          }
+        }
+
+        return insert(state, index, ...values);
+      });
+    },
+    insertAfter(key: Key, ...values: T[]) {
+      dispatch((state) => {
+        let index = state.items.findIndex((item) => getKey?.(item) === key);
+
+        if (index === -1) {
+          if (state.items.length === 0) {
+            index = 0;
+          } else {
+            return state;
+          }
+        }
+
+        return insert(state, index + 1, ...values);
+      });
+    },
+    prepend(...values: T[]) {
+      dispatch((state) => insert(state, 0, ...values));
+    },
+    append(...values: T[]) {
+      dispatch((state) => insert(state, state.items.length, ...values));
+    },
+    remove(...keys: Key[]) {
+      dispatch((state) => {
+        const keySet = new Set(keys);
+        const items = state.items.filter((item) => !keySet.has(getKey!(item)));
+
+        let selection: Selection = "all";
+
+        if (state.selectedKeys !== "all") {
+          selection = new Set(state.selectedKeys);
+          for (const key of keys) {
+            selection.delete(key);
+          }
+        }
+        if (cursor == null && items.length === 0) {
+          selection = new Set();
+        }
+
+        return {
+          ...state,
+          items,
+          selectedKeys: selection,
+        };
+      });
+    },
+    removeSelectedItems() {
+      dispatch((state) => {
+        if (state.selectedKeys === "all") {
+          return {
+            ...state,
+            items: [],
+            selectedKeys: new Set(),
+          };
+        }
+
+        const selectedKeys = state.selectedKeys;
+        const items = state.items.filter((item) => !selectedKeys.has(getKey!(item)));
+
+        return {
+          ...state,
+          items,
+          selectedKeys: new Set(),
+        };
+      });
+    },
+    move(key: Key, toIndex: number) {
+      dispatch((state) => {
+        const index = state.items.findIndex((item) => getKey!(item) === key);
+
+        if (index === -1) {
+          return state;
+        }
+
+        const copy = state.items.slice();
+        const [item] = copy.splice(index, 1);
+
+        if (item !== undefined) {
+          copy.splice(toIndex, 0, item);
+        }
+
+        return {
+          ...state,
+          items: copy,
+        };
+      });
+    },
+    moveBefore(key: Key, keys: Iterable<Key>) {
+      dispatch((state) => {
+        const toIndex = state.items.findIndex((item) => getKey!(item) === key);
+
+        if (toIndex === -1) {
+          return state;
+        }
+
+        // Find indices of keys to move. Sort them so that the order in the list is retained.
+        const keyArray = Array.isArray(keys) ? keys : [...keys];
+        const indices = keyArray
+          .map((key) => state.items.findIndex((item) => getKey!(item) === key))
+          .sort((a, b) => a - b);
+
+        return move(state, indices, toIndex);
+      });
+    },
+    moveAfter(key: Key, keys: Iterable<Key>) {
+      dispatch((state) => {
+        const toIndex = state.items.findIndex((item) => getKey!(item) === key);
+
+        if (toIndex === -1) {
+          return state;
+        }
+
+        const keyArray = Array.isArray(keys) ? keys : [...keys];
+        const indices = keyArray
+          .map((key) => state.items.findIndex((item) => getKey!(item) === key))
+          .sort((a, b) => a - b);
+
+        return move(state, indices, toIndex + 1);
+      });
+    },
+    update(key: Key, newValue: T | ((prev: T) => T)) {
+      dispatch((state) => {
+        const index = state.items.findIndex((item) => getKey!(item) === key);
+
+        if (index === -1) {
+          return state;
+        }
+
+        const currentItem = state.items[index];
+
+        if (currentItem === undefined) {
+          return state;
+        }
+
+        let updatedValue: T;
+
+        if (typeof newValue === "function") {
+          updatedValue = (newValue as (prev: T) => T)(currentItem);
+        } else {
+          updatedValue = newValue;
+        }
+
+        return {
+          ...state,
+          items: [...state.items.slice(0, index), updatedValue, ...state.items.slice(index + 1)],
+        };
+      });
+    },
+  };
+}
+
+function insert<T>(state: ListState<T>, index: number, ...values: T[]): ListState<T> {
+  return {
+    ...state,
+    items: [...state.items.slice(0, index), ...values, ...state.items.slice(index)],
+  };
+}
+
+function move<T>(state: ListState<T>, indices: number[], toIndex: number): ListState<T> {
+  // Shift the target down by the number of items being moved from before the target
+  toIndex -= indices.filter((index) => index < toIndex).length;
+
+  const moves = indices.map((from) => ({
+    from,
+    to: toIndex++,
+  }));
+
+  // Shift later from indices down if they have a larger index
+  for (let i = 0; i < moves.length; i++) {
+    const a = moves[i]!;
+
+    for (let j = i; j < moves.length; j++) {
+      const b = moves[j]!;
+
+      if (b.from > a.from) {
+        b.from--;
+      }
+    }
+  }
+
+  // Interleave the moves so they can be applied one by one rather than all at once
+  for (let i = 0; i < moves.length; i++) {
+    const a = moves[i]!;
+
+    for (let j = moves.length - 1; j > i; j--) {
+      const b = moves[j]!;
+
+      if (b.from < a.to) {
+        a.to++;
+      } else {
+        b.from++;
+      }
+    }
+  }
+
+  const copy = state.items.slice();
+
+  for (const moveItem of moves) {
+    const [item] = copy.splice(moveItem.from, 1);
+
+    if (item !== undefined) {
+      copy.splice(moveItem.to, 0, item);
+    }
+  }
+
+  return {
+    ...state,
+    items: copy,
+  };
+}
diff --git a/packages/react/src/hooks/use-measured-height.ts b/packages/react/src/hooks/use-measured-height.ts
new file mode 100644
index 0000000..239b50f
--- /dev/null
+++ b/packages/react/src/hooks/use-measured-height.ts
@@ -0,0 +1,58 @@
+"use client";
+
+import type {RefObject} from "react";
+
+import {useCallback, useEffect, useState} from "react";
+
+export const useMeasuredHeight = (ref: RefObject<HTMLDivElement | null>) => {
+  const [height, setHeight] = useState<number | undefined>(undefined);
+
+  const calculateHeight = useCallback(() => {
+    if (ref.current) {
+      const measuredHeight = ref.current.scrollHeight;
+
+      setHeight((prevHeight) => {
+        // Only update if height actually changed
+        return prevHeight !== measuredHeight ? measuredHeight : prevHeight;
+      });
+    }
+  }, [ref]);
+
+  useEffect(() => {
+    const element = ref.current;
+
+    if (!element) {
+      return;
+    }
+
+    // Use ResizeObserver's initial notification instead of manual call
+    const resizeObserver = new ResizeObserver(calculateHeight);
+
+    // Optimize MutationObserver callback
+    const mutationObserver = new MutationObserver((mutations) => {
+      // Check if any mutation is aria-hidden before calculating
+      const hasAriaHiddenChange = mutations.some(
+        (mutation) => mutation.type === "attributes" && mutation.attributeName === "aria-hidden",
+      );
+
+      if (hasAriaHiddenChange) {
+        calculateHeight();
+      }
+    });
+
+    resizeObserver.observe(element);
+    mutationObserver.observe(element, {
+      attributeFilter: ["aria-hidden"],
+      attributes: true,
+    });
+
+    return () => {
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+    };
+  }, [ref, calculateHeight]);
+
+  return {
+    height,
+  };
+};
diff --git a/packages/react/src/hooks/use-media-query.ts b/packages/react/src/hooks/use-media-query.ts
new file mode 100644
index 0000000..1d28246
--- /dev/null
+++ b/packages/react/src/hooks/use-media-query.ts
@@ -0,0 +1,62 @@
+"use client";
+
+import {useState} from "react";
+
+import {useIsomorphicLayoutEffect} from "./use-isomorphic-layout-effect";
+
+type UseMediaQueryOptions = {
+  defaultValue?: boolean;
+  initializeWithValue?: boolean;
+};
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useMediaQuery(
+  query: string,
+  {defaultValue = false, initializeWithValue = true}: UseMediaQueryOptions = {},
+): boolean {
+  const getMatches = (query: string): boolean => {
+    if (IS_SERVER) {
+      return defaultValue;
+    }
+
+    return window.matchMedia(query).matches;
+  };
+
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (initializeWithValue) {
+      return getMatches(query);
+    }
+
+    return defaultValue;
+  });
+
+  // Handles the change event of the media query.
+  function handleChange() {
+    setMatches(getMatches(query));
+  }
+
+  useIsomorphicLayoutEffect(() => {
+    const matchMedia = window.matchMedia(query);
+
+    // Triggered at the first client-side load and if query changes
+    handleChange();
+
+    // Use deprecated `addListener` and `removeListener` to support Safari < 14 (#135)
+    if (matchMedia.addListener) {
+      matchMedia.addListener(handleChange);
+    } else {
+      matchMedia.addEventListener("change", handleChange);
+    }
+
+    return () => {
+      if (matchMedia.removeListener) {
+        matchMedia.removeListener(handleChange);
+      } else {
+        matchMedia.removeEventListener("change", handleChange);
+      }
+    };
+  }, [query]);
+
+  return matches;
+}
diff --git a/packages/react/src/hooks/use-mounted.ts b/packages/react/src/hooks/use-mounted.ts
new file mode 100644
index 0000000..c19c656
--- /dev/null
+++ b/packages/react/src/hooks/use-mounted.ts
@@ -0,0 +1,17 @@
+"use client";
+
+import {useCallback, useEffect, useRef} from "react";
+
+export function useIsMounted(): () => boolean {
+  const isMounted = useRef(false);
+
+  useEffect(() => {
+    isMounted.current = true;
+
+    return () => {
+      isMounted.current = false;
+    };
+  }, []);
+
+  return useCallback(() => isMounted.current, []);
+}
diff --git a/packages/react/src/hooks/use-overlay-state.ts b/packages/react/src/hooks/use-overlay-state.ts
new file mode 100644
index 0000000..21a8220
--- /dev/null
+++ b/packages/react/src/hooks/use-overlay-state.ts
@@ -0,0 +1,110 @@
+"use client";
+
+import {useCallback, useEffect, useRef, useState} from "react";
+
+export interface UseOverlayStateProps {
+  /**
+   * Whether the overlay is currently open (controlled)
+   */
+  isOpen?: boolean;
+  /**
+   * Whether the overlay is open by default (uncontrolled)
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Handler that is called when the overlay's open state changes
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+}
+
+export interface UseOverlayStateReturn {
+  /**
+   * Whether the overlay is currently open
+   */
+  readonly isOpen: boolean;
+  /**
+   * Sets the overlay's open state
+   */
+  setOpen(isOpen: boolean): void;
+  /**
+   * Opens the overlay
+   */
+  open(): void;
+  /**
+   * Closes the overlay
+   */
+  close(): void;
+  /**
+   * Toggles the overlay's open state
+   */
+  toggle(): void;
+}
+
+/**
+ * Hook to manage overlay trigger state (Modal, AlertDialog, Popover, etc.)
+ * Provides methods to open, close, and toggle the overlay
+ *
+ * @example
+ * ```tsx
+ * const state = useOverlayState();
+ *
+ * <Button onPress={state.open}>Open Dialog</Button>
+ * <Modal isOpen={state.isOpen} onOpenChange={state.setOpen}>
+ *   <Button onPress={state.close}>Close</Button>
+ * </Modal>
+ * ```
+ */
+export const useOverlayState = (props: UseOverlayStateProps = {}): UseOverlayStateReturn => {
+  const {defaultOpen = false, isOpen: controlledIsOpen, onOpenChange} = props;
+
+  // Internal state for uncontrolled mode
+  const [uncontrolledIsOpen, setUncontrolledIsOpen] = useState<boolean>(defaultOpen);
+
+  // Determine if controlled
+  const isControlled = controlledIsOpen !== undefined;
+  const isOpen = isControlled ? controlledIsOpen : uncontrolledIsOpen;
+
+  // Keep a stable reference to onOpenChange to avoid recreating callbacks
+  const onOpenChangeRef = useRef(onOpenChange);
+
+  // Update ref in effect to avoid updating during render
+  useEffect(() => {
+    onOpenChangeRef.current = onOpenChange;
+  }, [onOpenChange]);
+
+  // Stable setter function that works for both controlled and uncontrolled modes
+  const setOpen = useCallback(
+    (nextIsOpen: boolean) => {
+      // Always call the onChange callback if provided
+      onOpenChangeRef.current?.(nextIsOpen);
+
+      // Update internal state only in uncontrolled mode
+      if (!isControlled) {
+        setUncontrolledIsOpen(nextIsOpen);
+      }
+    },
+    [isControlled],
+  );
+
+  // Memoized convenience methods
+  const open = useCallback(() => {
+    setOpen(true);
+  }, [setOpen]);
+
+  const close = useCallback(() => {
+    setOpen(false);
+  }, [setOpen]);
+
+  const toggle = useCallback(() => {
+    setOpen(!isOpen);
+  }, [setOpen, isOpen]);
+
+  return {
+    close,
+    isOpen,
+    open,
+    setOpen,
+    toggle,
+  };
+};
diff --git a/packages/react/src/hooks/use-safe-layout-effect.ts b/packages/react/src/hooks/use-safe-layout-effect.ts
new file mode 100644
index 0000000..d1fb067
--- /dev/null
+++ b/packages/react/src/hooks/use-safe-layout-effect.ts
@@ -0,0 +1,5 @@
+"use client";
+
+import {useEffect, useLayoutEffect} from "react";
+
+export const useSafeLayoutEffect = globalThis?.document ? useLayoutEffect : useEffect;
diff --git a/packages/react/src/hooks/use-theme.ts b/packages/react/src/hooks/use-theme.ts
new file mode 100644
index 0000000..8c7f317
--- /dev/null
+++ b/packages/react/src/hooks/use-theme.ts
@@ -0,0 +1,110 @@
+"use client";
+
+import {useCallback, useRef, useState, useSyncExternalStore} from "react";
+
+import {useIsomorphicLayoutEffect} from "./use-isomorphic-layout-effect";
+
+const THEME_STORAGE_KEY = "heroui-theme";
+const PREFERS_DARK_MEDIA = "(prefers-color-scheme: dark)";
+
+export type Theme = string;
+
+/**
+ * Subscribes to OS color-scheme changes. No-op on the server.
+ */
+function subscribeSystemPreference(callback: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+
+  const media = window.matchMedia(PREFERS_DARK_MEDIA);
+
+  media.addEventListener("change", callback);
+
+  return () => media.removeEventListener("change", callback);
+}
+
+/**
+ * Reads the current OS color-scheme preference. Client-only.
+ */
+function getSystemPreference(): "dark" | "light" {
+  return window.matchMedia?.(PREFERS_DARK_MEDIA).matches ? "dark" : "light";
+}
+
+/**
+ * Server snapshot for the system preference — unknown without `window.matchMedia`.
+ */
+function getServerSystemPreference(): undefined {
+  return undefined;
+}
+
+/**
+ * Applies the resolved theme to the document element (classList + data-theme attribute).
+ * No-op when the resolved value matches the previously-applied class to avoid
+ * redundant DOM writes (which can trigger MutationObservers and view transitions).
+ */
+function applyThemeToDOM(resolved: string, previous?: string) {
+  if (previous === resolved) return;
+
+  if (previous) {
+    document.documentElement.classList.remove(previous);
+  }
+
+  document.documentElement.classList.add(resolved);
+  document.documentElement.setAttribute("data-theme", resolved);
+}
+
+/**
+ * React hook to switch between themes.
+ *
+ * Accepts any theme name ("light", "dark", "brutalism-light", etc.).
+ * Pass "system" to follow the OS preference (resolves to "light" or "dark").
+ *
+ * @param defaultTheme - the initial theme name (defaults to "system")
+ * @returns `theme` (the stored intent, e.g. "system"), `resolvedTheme` (the
+ *          concrete class applied to the DOM — undefined during SSR), and `setTheme`.
+ */
+export function useTheme(defaultTheme: Theme = "system") {
+  // The stored theme value — the user's intent (may be "system" or a concrete name).
+  const [theme, setThemeState] = useState<Theme>(() => {
+    // SSR guard — browser APIs are not available on the server.
+    if (typeof window === "undefined") return defaultTheme;
+
+    return localStorage.getItem(THEME_STORAGE_KEY) ?? defaultTheme;
+  });
+
+  // Reactive snapshot of the OS color-scheme preference.
+  // Returns `undefined` on the server (no `matchMedia`).
+  const systemTheme = useSyncExternalStore(
+    subscribeSystemPreference,
+    getSystemPreference,
+    getServerSystemPreference,
+  );
+
+  // Derived during render — no extra state, no setState-in-effect.
+  // When `theme === "system"`, follows the OS; otherwise echoes `theme`.
+  const resolvedTheme: string | undefined = theme === "system" ? systemTheme : theme;
+
+  // Track the last class written to the DOM so we can remove it on change.
+  const appliedRef = useRef<string | undefined>(undefined);
+
+  // Sync the document with the resolved theme.
+  // Uses a layout effect so the DOM is updated before paint (no FOUC).
+  useIsomorphicLayoutEffect(() => {
+    if (!resolvedTheme) return;
+
+    applyThemeToDOM(resolvedTheme, appliedRef.current);
+    appliedRef.current = resolvedTheme;
+  }, [resolvedTheme]);
+
+  // Stable callback — empty deps, reads nothing from the render closure.
+  const setTheme = useCallback((newTheme: Theme) => {
+    // SSR guard
+    if (typeof window === "undefined") return;
+
+    // Persist the user's intent (e.g. "system"), not the resolved value.
+    localStorage.setItem(THEME_STORAGE_KEY, newTheme);
+    setThemeState(newTheme);
+    // The DOM is updated in the layout effect above when `resolvedTheme` changes.
+  }, []);
+
+  return {resolvedTheme, setTheme, theme};
+}
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
new file mode 100644
index 0000000..78ebee5
--- /dev/null
+++ b/packages/react/src/index.ts
@@ -0,0 +1,13 @@
+//  ===================================
+//  Components
+//  ===================================
+export * from "./components";
+//  ===================================
+//  Hooks
+//  ===================================
+export * from "./hooks";
+//  ===================================
+//  Utils
+//  ===================================
+export * from "./utils/dom";
+export {tv, cn, type VariantProps} from "tailwind-variants";
diff --git a/packages/react/src/styles.css b/packages/react/src/styles.css
new file mode 100644
index 0000000..0665d0e
--- /dev/null
+++ b/packages/react/src/styles.css
@@ -0,0 +1,2 @@
+/* Placeholder file for build process */
+@import "@heroui/styles";
diff --git a/packages/react/src/utils/assertion.ts b/packages/react/src/utils/assertion.ts
new file mode 100644
index 0000000..daa6fac
--- /dev/null
+++ b/packages/react/src/utils/assertion.ts
@@ -0,0 +1,36 @@
+export type Dict<T = any> = Record<string, T>;
+
+export function isArray<T>(value: any): value is Array<T> {
+  return Array.isArray(value);
+}
+
+export function isEmptyArray(value: any) {
+  return isArray(value) && value.length === 0;
+}
+
+export function isObject(value: any): value is Dict {
+  const type = typeof value;
+
+  return value != null && (type === "object" || type === "function") && !isArray(value);
+}
+
+export function isEmptyObject(value: any) {
+  return isObject(value) && Object.keys(value).length === 0;
+}
+
+// Empty assertions
+export function isEmpty(value: any): boolean {
+  if (isArray(value)) return isEmptyArray(value);
+  if (isObject(value)) return isEmptyObject(value);
+  if (value == null || value === "") return true;
+
+  return false;
+}
+
+export type Booleanish = boolean | "true" | "false";
+
+export const dataAttr = (condition: boolean | undefined) =>
+  (condition ? "true" : undefined) as Booleanish;
+
+export const isNumeric = (value?: string | number) =>
+  value != null && parseInt(value.toString(), 10) > 0;
diff --git a/packages/react/src/utils/calendar.ts b/packages/react/src/utils/calendar.ts
new file mode 100644
index 0000000..a50a56c
--- /dev/null
+++ b/packages/react/src/utils/calendar.ts
@@ -0,0 +1,143 @@
+import type {DateValue} from "@internationalized/date";
+
+import {isSameDay, startOfWeek, startOfYear} from "@internationalized/date";
+
+/**
+ * Returns the year offset between the Gregorian calendar and the given
+ * calendar system.  Used to compute sensible default min/max year bounds.
+ */
+export function getGregorianYearOffset(identifier: string): number {
+  switch (identifier) {
+    case "buddhist":
+      return 543;
+    case "ethiopic":
+    case "ethioaa":
+      return -8;
+    case "coptic":
+      return -284;
+    case "hebrew":
+      return 3760;
+    case "indian":
+      return -78;
+    case "islamic-civil":
+    case "islamic-tbla":
+    case "islamic-umalqura":
+      return -579;
+    case "persian":
+      return -600;
+    case "roc":
+    case "japanese":
+    case "gregory":
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Iterates from `start` to `end` using calendar-aware arithmetic so that
+ * non-Gregorian calendars (e.g. Japanese, Hebrew) produce correct year
+ * boundaries.  Ported from HeroUI v2.
+ */
+export function getYearRange(start?: DateValue | null, end?: DateValue | null): DateValue[] {
+  const years: DateValue[] = [];
+
+  if (!start || !end) return years;
+
+  let current = startOfYear(start);
+
+  while (current.compare(end) <= 0) {
+    years.push(current);
+    current = startOfYear(current.add({years: 1}));
+  }
+
+  return years;
+}
+
+type DayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+
+type WeekdayStyle = "narrow" | "short" | "long";
+
+export function getDayViewWeekDayLabels(
+  start: DateValue,
+  locale: string,
+  firstDayOfWeek: DayOfWeek | undefined,
+  weekdayStyle: WeekdayStyle = "short",
+  timeZone = "UTC",
+): string[] {
+  const formatter = new Intl.DateTimeFormat(locale, {weekday: weekdayStyle, timeZone});
+  const weekStart = startOfWeek(start, locale, firstDayOfWeek);
+  const labels: string[] = [];
+  let date = weekStart;
+
+  for (let index = 0; index < 7; index++) {
+    labels.push(formatter.format(date.toDate(timeZone)));
+    const next = date.add({days: 1});
+
+    if (isSameDay(date, next)) {
+      break;
+    }
+
+    date = next;
+  }
+
+  while (labels.length < 7) {
+    labels.push("");
+  }
+
+  return labels;
+}
+
+function buildDayViewWeekRow(rowStart: DateValue, end: DateValue): (DateValue | null)[] {
+  const row: (DateValue | null)[] = [];
+  let date = rowStart;
+
+  for (let index = 0; index < 7; index++) {
+    row.push(date.compare(end) > 0 ? null : date);
+
+    const next = date.add({days: 1});
+
+    if (isSameDay(date, next)) {
+      while (row.length < 7) {
+        row.push(null);
+      }
+
+      return row;
+    }
+
+    date = next;
+  }
+
+  return row;
+}
+
+/**
+ * Builds week-aligned rows for day view. The first row starts at `startOfWeek(start)`
+ * (leading dates before `start` are shown but disabled by RAC). Each subsequent row
+ * starts on the next week boundary.
+ */
+export function getDayViewGridRows(
+  start: DateValue,
+  end: DateValue,
+  locale: string,
+  firstDayOfWeek?: DayOfWeek,
+): (DateValue | null)[][] {
+  const rows: (DateValue | null)[][] = [];
+  let rowStart = startOfWeek(start, locale, firstDayOfWeek);
+
+  rows.push(buildDayViewWeekRow(rowStart, end));
+
+  rowStart = rowStart.add({weeks: 1});
+
+  while (rowStart.compare(end) <= 0) {
+    rows.push(buildDayViewWeekRow(rowStart, end));
+    const nextWeek = rowStart.add({weeks: 1});
+
+    if (isSameDay(rowStart, nextWeek)) {
+      break;
+    }
+
+    rowStart = nextWeek;
+  }
+
+  return rows;
+}
diff --git a/packages/react/src/utils/children.ts b/packages/react/src/utils/children.ts
new file mode 100644
index 0000000..fb66a58
--- /dev/null
+++ b/packages/react/src/utils/children.ts
@@ -0,0 +1,37 @@
+import type {ReactNode} from "react";
+
+import {Children, isValidElement} from "react";
+
+/**
+ * Gets only the valid children of a component,
+ * and ignores any nullish or falsy child.
+ *
+ * @param children the children
+ */
+export function getValidChildren(children: React.ReactNode) {
+  return Children.toArray(children).filter((child) =>
+    isValidElement(child),
+  ) as React.ReactElement[];
+}
+
+export const pickChildren = <T = ReactNode>(
+  children: T | undefined,
+  targetChild: React.ElementType,
+): [T | undefined, T[] | undefined] => {
+  const target: T[] = [];
+
+  const withoutTargetChildren = Children.map(children, (item) => {
+    if (!isValidElement(item)) return item;
+    if (item.type === targetChild) {
+      target.push(item as T);
+
+      return null;
+    }
+
+    return item;
+  })?.filter(Boolean) as T;
+
+  const targetChildren = target.length >= 0 ? target : undefined;
+
+  return [withoutTargetChildren, targetChildren];
+};
diff --git a/packages/react/src/utils/compose.ts b/packages/react/src/utils/compose.ts
new file mode 100644
index 0000000..68c1ecf
--- /dev/null
+++ b/packages/react/src/utils/compose.ts
@@ -0,0 +1,29 @@
+"use client";
+
+import {composeRenderProps} from "react-aria-components/composeRenderProps";
+import {cx} from "tailwind-variants";
+
+// Re-export utility classes from @heroui/styles for backward compatibility
+export {disabledClasses, focusRingClasses, ariaDisabledClasses} from "@heroui/styles";
+
+function composeTwRenderProps<T>(
+  className: string | ((v: T) => string) | undefined,
+  tailwind?: string | ((v: T) => string | undefined),
+): string | ((v: T) => string) {
+  return composeRenderProps(className, (className, renderProps): string => {
+    const tw = typeof tailwind === "function" ? (tailwind(renderProps) ?? "") : (tailwind ?? "");
+    const cls = className ?? "";
+
+    return cx(tw, cls) ?? "";
+  });
+}
+
+export const composeSlotClassName = (
+  slotFn: ((args?: {className?: string; [key: string]: any}) => string) | undefined,
+  className?: string,
+  variants?: Record<string, any>,
+): string | undefined => {
+  return typeof slotFn === "function" ? slotFn({...(variants ?? {}), className}) : className;
+};
+
+export {composeTwRenderProps};
diff --git a/packages/react/src/utils/css.ts b/packages/react/src/utils/css.ts
new file mode 100644
index 0000000..7f085ea
--- /dev/null
+++ b/packages/react/src/utils/css.ts
@@ -0,0 +1,11 @@
+export const parseCSSTime = (value: string | undefined): number | undefined => {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const val = parseFloat(trimmed);
+
+  if (Number.isNaN(val)) return undefined;
+  if (trimmed.endsWith("ms")) return val;
+  if (trimmed.endsWith("s")) return val * 1000;
+
+  return val;
+};
diff --git a/packages/react/src/utils/dom.tsx b/packages/react/src/utils/dom.tsx
new file mode 100644
index 0000000..e2633be
--- /dev/null
+++ b/packages/react/src/utils/dom.tsx
@@ -0,0 +1,88 @@
+"use client";
+
+/* eslint-disable no-console */
+/*
+ * From https://github.com/adobe/react-spectrum/blob/0e69a1bf028448551b8e6c3ee936f41b8f70109a/packages/react-aria-components/src/utils.tsx
+ * Remove it and import directly from react-aria-components when they export it.
+ */
+
+import type {AllHTMLAttributes, ReactElement} from "react";
+
+import {mergeRefs, useLayoutEffect} from "@react-aria/utils";
+import React, {useMemo, useRef} from "react";
+
+export type DOMRenderFunction<E extends keyof React.JSX.IntrinsicElements, T> = (
+  props: React.JSX.IntrinsicElements[E],
+  renderProps: T,
+) => ReactElement;
+export interface DOMRenderProps<E extends keyof React.JSX.IntrinsicElements, T> {
+  /**
+   * Overrides the default DOM element with a custom render function.
+   * This allows rendering existing components with built-in styles and behaviors
+   * such as router links, animation libraries, and pre-styled components.
+   *
+   * Requirements:
+   *
+   * * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`).
+   * * Only a single root DOM element can be rendered (no fragments).
+   * * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
+   */
+  render?: DOMRenderFunction<E, T>;
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+function DOMElement(
+  ElementType: string,
+  props: DOMRenderProps<any, any> & AllHTMLAttributes<HTMLElement> & {ref?: React.Ref<HTMLElement>},
+) {
+  const {ref: forwardedRef, render, ...otherProps} = props;
+  const elementRef = useRef<HTMLElement | null>(null);
+  const ref = useMemo(() => mergeRefs(forwardedRef, elementRef), [forwardedRef, elementRef]);
+
+  useLayoutEffect(() => {
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production" && render) {
+      if (!elementRef.current) {
+        console.warn(
+          "Ref was not connected to DOM element returned by custom `render` function. Did you forget to pass through or merge the `ref`?",
+        );
+      }
+    }
+  }, [ElementType, render]);
+
+  const domProps: any = {...otherProps, ref};
+
+  if (render) {
+    return render(domProps, undefined);
+  }
+
+  return <ElementType {...domProps} />;
+}
+
+type DOMComponents = {
+  [E in keyof React.JSX.IntrinsicElements]: (
+    props: DOMRenderProps<E, any> & React.JSX.IntrinsicElements[E],
+  ) => ReactElement;
+};
+
+const domComponentCache: Record<string, unknown> = {};
+
+// Dynamically generates and caches components for each DOM element (e.g. `dom.button`).
+export const dom = new Proxy(
+  {},
+  {
+    get(_target, elementType) {
+      if (typeof elementType !== "string") {
+        return undefined;
+      }
+
+      let res = domComponentCache[elementType];
+
+      if (!res) {
+        res = DOMElement.bind(null, elementType);
+        domComponentCache[elementType] = res;
+      }
+
+      return res;
+    },
+  },
+) as DOMComponents;
diff --git a/packages/react/src/utils/index.ts b/packages/react/src/utils/index.ts
new file mode 100644
index 0000000..89c6152
--- /dev/null
+++ b/packages/react/src/utils/index.ts
@@ -0,0 +1,8 @@
+export * from "./calendar";
+export * from "./css";
+export * from "./compose";
+export * from "./logger";
+export * from "./dom";
+export * from "./variants";
+export {tv} from "./tv";
+export type {VariantProps} from "./tv";
diff --git a/packages/react/src/utils/logger.ts b/packages/react/src/utils/logger.ts
new file mode 100644
index 0000000..25aa171
--- /dev/null
+++ b/packages/react/src/utils/logger.ts
@@ -0,0 +1,102 @@
+/* eslint-disable no-console */
+/**
+ * Logger utility for HeroUI Core
+ * Provides formatted console output with levels and prefixes
+ */
+
+const colors = {
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  magenta: "\x1b[35m",
+  red: "\x1b[31m",
+  reset: "\x1b[0m",
+  yellow: "\x1b[33m",
+} as const;
+
+type LogLevel = "info" | "success" | "warn" | "error" | "debug";
+
+interface LoggerOptions {
+  enabled?: boolean;
+  prefix?: string;
+}
+
+const levelColors: Record<LogLevel, string> = {
+  debug: colors.magenta,
+  error: colors.red,
+  info: colors.blue,
+  success: colors.green,
+  warn: colors.yellow,
+};
+
+const levelEmojis: Record<LogLevel, string> = {
+  debug: "🔍",
+  error: "❌",
+  info: "ℹ️",
+  success: "✅",
+  warn: "⚠️",
+};
+
+export class Logger {
+  private enabled: boolean;
+  private prefix: string;
+
+  constructor(options: LoggerOptions = {}) {
+    this.enabled = options.enabled ?? true;
+    this.prefix = options.prefix ?? "HeroUI";
+  }
+
+  private formatMessage(level: LogLevel, message: string): string {
+    const color = levelColors[level];
+    const emoji = levelEmojis[level];
+
+    return `${color}[${this.prefix}]${colors.reset} ${emoji}  ${message}`;
+  }
+
+  private log(level: LogLevel, message: string, ...args: any[]): void {
+    if (!this.enabled) return;
+
+    const formattedMessage = this.formatMessage(level, message);
+
+    switch (level) {
+      case "error":
+        console.error(formattedMessage, ...args);
+        break;
+      case "warn":
+        console.warn(formattedMessage, ...args);
+        break;
+      default:
+        console.log(formattedMessage, ...args);
+    }
+  }
+
+  info(message: string, ...args: any[]): void {
+    this.log("info", message, ...args);
+  }
+
+  success(message: string, ...args: any[]): void {
+    this.log("success", message, ...args);
+  }
+
+  warn(message: string, ...args: any[]): void {
+    this.log("warn", message, ...args);
+  }
+
+  error(message: string, ...args: any[]): void {
+    this.log("error", message, ...args);
+  }
+
+  debug(message: string, ...args: any[]): void {
+    this.log("debug", message, ...args);
+  }
+
+  divider(char: string = "=", length: number = 80): void {
+    if (!this.enabled) return;
+    console.log(char.repeat(length));
+  }
+
+  newline(): void {
+    if (!this.enabled) return;
+    console.log();
+  }
+}
diff --git a/packages/react/src/utils/tv.ts b/packages/react/src/utils/tv.ts
new file mode 100644
index 0000000..552fea2
--- /dev/null
+++ b/packages/react/src/utils/tv.ts
@@ -0,0 +1,20 @@
+import type {TV} from "tailwind-variants";
+
+import {tv as tvBase} from "tailwind-variants";
+
+export type {VariantProps} from "tailwind-variants";
+
+export const tv: TV = (options, config) =>
+  tvBase(options, {
+    ...config,
+    twMerge: config?.twMerge ?? false,
+    twMergeConfig: {
+      ...config?.twMergeConfig,
+      classGroups: {
+        ...config?.twMergeConfig?.classGroups,
+      },
+      theme: {
+        ...config?.twMergeConfig?.theme,
+      },
+    },
+  });
diff --git a/packages/react/src/utils/variants.ts b/packages/react/src/utils/variants.ts
new file mode 100644
index 0000000..8b6c2eb
--- /dev/null
+++ b/packages/react/src/utils/variants.ts
@@ -0,0 +1,179 @@
+export const mapPropsVariants = <T extends Record<string, any>, K extends keyof T>(
+  props: T,
+  variantKeys?: K[],
+  removeVariantProps = true,
+): readonly [Omit<T, K> | T, Pick<T, K> | {}] => {
+  if (!variantKeys) {
+    return [props, {}];
+  }
+
+  const picked = variantKeys.reduce((acc, key) => {
+    // Only include the key in `picked` if it exists in `props`
+    if (key in props) {
+      return {...acc, [key]: props[key]};
+    } else {
+      return acc;
+    }
+  }, {});
+
+  if (removeVariantProps) {
+    const omitted = Object.keys(props)
+      .filter((key) => !variantKeys.includes(key as K))
+      .reduce((acc, key) => ({...acc, [key]: props[key as keyof T]}), {});
+
+    return [omitted, picked] as [Omit<T, K>, Pick<T, K>];
+  } else {
+    return [props, picked] as [T, Pick<T, K>];
+  }
+};
+
+/**
+ * Utility for creating BEM-style class names with variants
+ */
+
+export type VariantConfig<T extends Record<string, any>> = {
+  base: string;
+  variants?: T;
+  modifiers?: Record<string, boolean | undefined>;
+};
+
+/**
+ * Creates a class name builder for components with variants
+ * @param config - The variant configuration
+ * @returns A function that builds the class name string
+ *
+ * @example
+ * const getButtonClasses = createVariantBuilder({
+ *   base: 'button',
+ *   variants: {
+ *     size: 'md',
+ *     variant: 'primary'
+ *   },
+ *   modifiers: {
+ *     'icon-only': isIconOnly
+ *   }
+ * });
+ * // Returns: "button button--md button--primary button--icon-only"
+ */
+export function createVariantBuilder<T extends Record<string, string>>(baseClass: string) {
+  return (
+    config: {
+      variants?: Partial<T>;
+      modifiers?: Record<string, boolean | undefined>;
+    } = {},
+  ) => {
+    const classes = [baseClass];
+
+    // Add variant classes
+    if (config.variants) {
+      Object.values(config.variants).forEach((value) => {
+        if (value) {
+          classes.push(`${baseClass}--${value}`);
+        }
+      });
+    }
+
+    // Add modifier classes
+    if (config.modifiers) {
+      Object.entries(config.modifiers).forEach(([modifier, enabled]) => {
+        if (enabled) {
+          classes.push(`${baseClass}--${modifier}`);
+        }
+      });
+    }
+
+    return classes.join(" ");
+  };
+}
+
+/**
+ * Alternative API using a more declarative approach
+ */
+export interface VariantDefinition<V extends Record<string, readonly string[]>> {
+  base: string;
+  variants: V;
+  defaults?: Partial<{[K in keyof V]: V[K][number]}>;
+}
+
+/**
+ * Creates a typed variant class builder
+ * @param definition - The variant definition
+ * @returns A function that builds class names based on variant props
+ *
+ * @example
+ * const buttonVariants = createVariants({
+ *   base: 'button',
+ *   variants: {
+ *     size: ['sm', 'md', 'lg'] as const,
+ *     variant: ['primary', 'secondary', 'tertiary', 'ghost', 'danger'] as const,
+ *   },
+ *   defaults: {
+ *     size: 'md',
+ *     variant: 'primary'
+ *   }
+ * });
+ *
+ * const className = buttonVariants({
+ *   size: 'lg',
+ *   variant: 'danger',
+ *   modifiers: { 'icon-only': true }
+ * });
+ * // Returns: "button button--lg button--danger button--icon-only"
+ */
+export function createVariants<V extends Record<string, readonly string[]>>(
+  definition: VariantDefinition<V>,
+) {
+  type VariantProps = {
+    [K in keyof V]?: V[K][number];
+  } & {
+    modifiers?: Record<string, boolean | undefined>;
+  };
+
+  return (props: VariantProps = {}) => {
+    const classes = [definition.base];
+
+    // Merge props with defaults, filtering out undefined values
+    const mergedProps: Record<string, any> = {};
+
+    // First apply defaults
+    if (definition.defaults) {
+      Object.entries(definition.defaults).forEach(([key, value]) => {
+        mergedProps[key] = value;
+      });
+    }
+
+    // Then apply provided props, but only if they're not undefined
+    Object.entries(props).forEach(([key, value]) => {
+      if (value !== undefined) {
+        mergedProps[key] = value;
+      }
+    });
+
+    // Add variant classes
+    Object.entries(mergedProps).forEach(([key, value]) => {
+      if (key !== "modifiers" && value) {
+        classes.push(`${definition.base}--${value}`);
+      }
+    });
+
+    // Add modifier classes
+    if (props.modifiers) {
+      Object.entries(props.modifiers).forEach(([modifier, enabled]) => {
+        if (enabled) {
+          classes.push(`${definition.base}--${modifier}`);
+        }
+      });
+    }
+
+    return classes.join(" ");
+  };
+}
+
+/**
+ * Type helpers for extracting variant props from a variant definition
+ */
+export type VariantPropsOf<T extends ReturnType<typeof createVariants>> = T extends (
+  props: infer P,
+) => string
+  ? P
+  : never;
diff --git a/packages/react/src/version.ts b/packages/react/src/version.ts
new file mode 100644
index 0000000..99a30ec
--- /dev/null
+++ b/packages/react/src/version.ts
@@ -0,0 +1,3 @@
+// This file is generated during the build process
+// It will be replaced with the actual version from package.json
+export const HEROUI_VERSION = "__HEROUI_VERSION__";
diff --git a/packages/react/tsconfig.json b/packages/react/tsconfig.json
new file mode 100644
index 0000000..6df5e2d
--- /dev/null
+++ b/packages/react/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@heroui/standard/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "preserve"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "**/*.stories.*", "**/*.test.*", "dist", ".rollup.cache"]
+}
diff --git a/packages/react/vitest.config.ts b/packages/react/vitest.config.ts
new file mode 100644
index 0000000..e69de29
diff --git a/packages/standard/eslint/base.mjs b/packages/standard/eslint/base.mjs
new file mode 100644
index 0000000..770cbb4
--- /dev/null
+++ b/packages/standard/eslint/base.mjs
@@ -0,0 +1,197 @@
+import js from "@eslint/js";
+import typescriptPlugin from "@typescript-eslint/eslint-plugin";
+import typescriptParser from "@typescript-eslint/parser";
+import {defineConfig} from "eslint/config";
+import prettierConfig from "eslint-config-prettier";
+import importPlugin from "eslint-plugin-import";
+import onlyWarnPlugin from "eslint-plugin-only-warn";
+import prettierPlugin from "eslint-plugin-prettier";
+import sortDestructureKeysPlugin from "eslint-plugin-sort-destructure-keys";
+import sortKeysFixPlugin from "eslint-plugin-sort-keys-fix";
+import unusedImportsPlugin from "eslint-plugin-unused-imports";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+const config = defineConfig([
+  // ESLint recommended rules
+  js.configs.recommended,
+  // TypeScript ESLint recommended rules
+  ...tseslint.configs.recommended,
+  // Prettier config - disables conflicting ESLint rules
+  {
+    rules: {
+      ...prettierConfig.rules,
+    },
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      globals: {
+        ...globals.node,
+        ...globals.es2025,
+      },
+      parser: typescriptParser,
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+      sourceType: "module",
+    },
+    plugins: {
+      "@typescript-eslint": typescriptPlugin,
+      import: importPlugin,
+      "only-warn": onlyWarnPlugin,
+      prettier: prettierPlugin,
+      "sort-destructure-keys": sortDestructureKeysPlugin,
+      "sort-keys-fix": sortKeysFixPlugin,
+      "unused-imports": unusedImportsPlugin,
+    },
+    rules: {
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-empty-object-type": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "import/consistent-type-specifier-style": ["error", "prefer-top-level"],
+      "import/newline-after-import": ["error", {count: 1}],
+      "import/no-duplicates": "error",
+      "import/order": [
+        "error",
+        {
+          alphabetize: {
+            caseInsensitive: true,
+            order: "asc",
+          },
+          groups: [
+            "type",
+            "builtin",
+            "external",
+            "internal",
+            "parent",
+            "sibling",
+            "index",
+            "object",
+            "unknown",
+          ],
+          "newlines-between": "always",
+          pathGroups: [
+            {
+              group: "type",
+              pattern: "server-only",
+              position: "before",
+            },
+            {
+              group: "unknown",
+              pattern: "**/*.+(css|sass|scss)",
+              patternOptions: {dot: true, nocomment: true},
+              position: "after",
+            },
+            {
+              group: "unknown",
+              pattern: "{.,..}/**/*.+(css|sass|scss)",
+              patternOptions: {dot: true, nocomment: true},
+              position: "after",
+            },
+            {
+              group: "internal",
+              pattern: "~env",
+              position: "before",
+            },
+            {
+              group: "internal",
+              pattern: "@/**",
+              position: "after",
+            },
+          ],
+          pathGroupsExcludedImportTypes: ["type"],
+          warnOnUnassignedImports: true,
+        },
+      ],
+      "no-console": "warn",
+      "no-unused-vars": "off",
+      "object-curly-spacing": ["error", "never"],
+      "padding-line-between-statements": [
+        "error",
+        {blankLine: "always", next: "*", prev: "directive"},
+        {blankLine: "any", next: "directive", prev: "directive"},
+        {blankLine: "always", next: "*", prev: ["const", "let", "var"]},
+        {blankLine: "any", next: ["const", "let", "var"], prev: ["const", "let", "var"]},
+        {blankLine: "always", next: "return", prev: "*"},
+      ],
+      "prettier/prettier": "error",
+      "sort-destructure-keys/sort-destructure-keys": [
+        "error",
+        {
+          caseSensitive: true,
+        },
+      ],
+      "sort-imports": [
+        "error",
+        {
+          allowSeparatedGroups: true,
+          ignoreCase: false,
+          ignoreDeclarationSort: true,
+          ignoreMemberSort: false,
+          memberSyntaxSortOrder: ["none", "all", "multiple", "single"],
+        },
+      ],
+      "sort-keys": [
+        "error",
+        "asc",
+        {
+          caseSensitive: true,
+          minKeys: 2,
+          natural: false,
+        },
+      ],
+      "sort-keys-fix/sort-keys-fix": "error",
+      "unused-imports/no-unused-imports": "error",
+      "unused-imports/no-unused-vars": [
+        "error",
+        {
+          args: "after-used",
+          argsIgnorePattern: "^_",
+          caughtErrors: "none",
+          vars: "all",
+          varsIgnorePattern: "^_",
+        },
+      ],
+    },
+    settings: {
+      "import/resolver": {
+        node: true,
+        typescript: true,
+      },
+    },
+  },
+  // Disable type checking for config files (.*.js, .*.cjs, .*.mjs)
+  {
+    files: [".*.js", ".*.cjs", ".*.mjs"],
+    ...tseslint.configs.disableTypeChecked,
+  },
+  {
+    ignores: [
+      "**/.temp/**",
+      "**/.next/**",
+      "**/.swc/**",
+      "**/.turbo/**",
+      "**/.cache/**",
+      "**/.build/**",
+      "**/.vercel/**",
+      "**/.DS_Store",
+      "**/dist/**",
+      "**/build/**",
+      "**/public/**",
+      "**/node_modules/**",
+      "**/coverage/**",
+      "**/.contentlayer/",
+      "**/__snapshots__/**",
+      "**/pnpm-lock.yaml",
+      "**/.source/**",
+      "**/next-env.d.ts",
+      "!.vscode/**",
+      "!scripts/**",
+    ],
+  },
+]);
+
+export default config;
diff --git a/packages/standard/eslint/next.mjs b/packages/standard/eslint/next.mjs
new file mode 100644
index 0000000..ec1faf9
--- /dev/null
+++ b/packages/standard/eslint/next.mjs
@@ -0,0 +1,95 @@
+import typescriptParser from "@typescript-eslint/parser";
+import {defineConfig} from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import reactRefreshPlugin from "eslint-plugin-react-refresh";
+import globals from "globals";
+
+import baseConfig from "./base.mjs";
+
+const config = defineConfig([
+  // Next.js configs - handle both array and object formats
+  ...(Array.isArray(nextVitals) ? nextVitals : [nextVitals]),
+  ...(Array.isArray(nextTs) ? nextTs : [nextTs]),
+  ...baseConfig,
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.es2025,
+      },
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+    plugins: {
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
+      "react-refresh": reactRefreshPlugin,
+    },
+    rules: {
+      "@next/next/no-html-link-for-pages": "off",
+      "@next/next/no-img-element": "off",
+      "no-console": "off",
+      "react-hooks/exhaustive-deps": "off",
+      "react-refresh/only-export-components": "off",
+      "react/jsx-boolean-value": [
+        "error",
+        "never",
+        {
+          always: ["personal"],
+        },
+      ],
+      "react/jsx-curly-brace-presence": [
+        "error",
+        {
+          children: "never",
+          props: "never",
+        },
+      ],
+      "react/jsx-no-leaked-render": [
+        "error",
+        {
+          validStrategies: ["coerce", "ternary"],
+        },
+      ],
+      "react/jsx-sort-props": [
+        "error",
+        {
+          callbacksLast: true,
+          ignoreCase: true,
+          locale: "auto",
+          multiline: "last",
+          noSortAlphabetically: false,
+          reservedFirst: true,
+          shorthandFirst: true,
+          shorthandLast: false,
+        },
+      ],
+      "react/jsx-uses-react": "off",
+      "react/no-unescaped-entities": "off",
+      "react/prop-types": "off",
+      "react/react-in-jsx-scope": "off",
+      "react/self-closing-comp": [
+        "error",
+        {
+          component: true,
+          html: true,
+        },
+      ],
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+  },
+]);
+
+export default config;
diff --git a/packages/standard/eslint/node.mjs b/packages/standard/eslint/node.mjs
new file mode 100644
index 0000000..cfdd39b
--- /dev/null
+++ b/packages/standard/eslint/node.mjs
@@ -0,0 +1,24 @@
+import {defineConfig} from "eslint/config";
+import globals from "globals";
+
+import baseConfig from "./base.mjs";
+
+export default defineConfig([
+  ...baseConfig,
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ["**/__tests__/**/*"],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+  },
+]);
diff --git a/packages/standard/eslint/react.mjs b/packages/standard/eslint/react.mjs
new file mode 100644
index 0000000..e9096ff
--- /dev/null
+++ b/packages/standard/eslint/react.mjs
@@ -0,0 +1,106 @@
+import typescriptParser from "@typescript-eslint/parser";
+import {defineConfig} from "eslint/config";
+import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import reactRefreshPlugin from "eslint-plugin-react-refresh";
+import storybookPlugin from "eslint-plugin-storybook";
+import globals from "globals";
+
+import baseConfig from "./base.mjs";
+
+const config = defineConfig([
+  ...baseConfig,
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.es2025,
+        JSX: true,
+        React: true,
+      },
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+    plugins: {
+      "jsx-a11y": jsxA11yPlugin,
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
+      "react-refresh": reactRefreshPlugin,
+      storybook: storybookPlugin,
+    },
+    rules: {
+      // React recommended rules
+      ...reactPlugin.configs.recommended.rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+      ...jsxA11yPlugin.configs.recommended.rules,
+      // Storybook recommended rules
+      ...storybookPlugin.configs.recommended.rules,
+      // Custom overrides
+      "jsx-a11y/alt-text": "off",
+      "jsx-a11y/click-events-have-key-events": "warn",
+      "jsx-a11y/interactive-supports-focus": "warn",
+      "jsx-a11y/no-autofocus": "off",
+      "react-hooks/exhaustive-deps": "off",
+      "react-refresh/only-export-components": ["warn", {allowConstantExport: true}],
+      "react/jsx-boolean-value": [
+        "error",
+        "never",
+        {
+          always: ["personal"],
+        },
+      ],
+      "react/jsx-curly-brace-presence": [
+        "error",
+        {
+          children: "never",
+          props: "never",
+        },
+      ],
+      "react/jsx-no-leaked-render": [
+        "error",
+        {
+          validStrategies: ["coerce", "ternary"],
+        },
+      ],
+      "react/jsx-sort-props": [
+        "error",
+        {
+          callbacksLast: true,
+          ignoreCase: true,
+          locale: "auto",
+          multiline: "last",
+          noSortAlphabetically: false,
+          reservedFirst: true,
+          shorthandFirst: true,
+          shorthandLast: false,
+        },
+      ],
+      "react/jsx-uses-react": "off",
+      "react/no-unescaped-entities": "off",
+      "react/prop-types": "off",
+      "react/react-in-jsx-scope": "off",
+      "react/self-closing-comp": [
+        "error",
+        {
+          component: true,
+          html: true,
+        },
+      ],
+      "sort-keys": "off",
+      "sort-keys-fix/sort-keys-fix": "off",
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+  },
+]);
+
+export default config;
diff --git a/packages/standard/package.json b/packages/standard/package.json
new file mode 100644
index 0000000..2402c37
--- /dev/null
+++ b/packages/standard/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@heroui/standard",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Standardized code style & lint rules for HeroUI.",
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/packages/standard/prettier/base.mjs b/packages/standard/prettier/base.mjs
new file mode 100644
index 0000000..6c8c991
--- /dev/null
+++ b/packages/standard/prettier/base.mjs
@@ -0,0 +1,19 @@
+/**
+ * Prettier preset configuration
+ *
+ * @see https://prettier.io/docs/en/configuration.html
+ * @type {import("prettier").Config}
+ */
+export default {
+  arrowParens: "always",
+  bracketSameLine: false,
+  bracketSpacing: false,
+  endOfLine: "auto",
+  jsxSingleQuote: false,
+  printWidth: 100,
+  semi: true,
+  singleQuote: false,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false,
+};
diff --git a/packages/standard/tsconfig/base.json b/packages/standard/tsconfig/base.json
new file mode 100644
index 0000000..801edfb
--- /dev/null
+++ b/packages/standard/tsconfig/base.json
@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Base",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "Node",
+    "lib": ["ESNext"],
+    "allowJs": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "checkJs": true,
+    "declaration": false,
+    "declarationMap": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/standard/tsconfig/next.json b/packages/standard/tsconfig/next.json
new file mode 100644
index 0000000..218cca0
--- /dev/null
+++ b/packages/standard/tsconfig/next.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Next",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "plugins": [{"name": "next"}]
+  },
+  "include": [],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/standard/tsconfig/node.json b/packages/standard/tsconfig/node.json
new file mode 100644
index 0000000..7b9b0c7
--- /dev/null
+++ b/packages/standard/tsconfig/node.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "Display": "Node",
+  "extends": "./base.json",
+  "compilerOptions": {},
+  "include": [],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/standard/tsconfig/react.json b/packages/standard/tsconfig/react.json
new file mode 100644
index 0000000..ed529c8
--- /dev/null
+++ b/packages/standard/tsconfig/react.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/standard/tsconfig/vite.json b/packages/standard/tsconfig/vite.json
new file mode 100644
index 0000000..91795b3
--- /dev/null
+++ b/packages/standard/tsconfig/vite.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Vite",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "types": ["vite/client"]
+  },
+  "include": [],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/storybook/.storybook/addons/i18n/constants.ts b/packages/storybook/.storybook/addons/i18n/constants.ts
new file mode 100644
index 0000000..79d9a07
--- /dev/null
+++ b/packages/storybook/.storybook/addons/i18n/constants.ts
@@ -0,0 +1,230 @@
+export const I18N_ADDON_ID = "heroui-i18n-addon";
+export const I18N_GLOBAL_TYPE_ID = "heroui-i18n";
+export const I18N_PARAM_KEY = "heroui-i18n";
+
+export const LOCALES = [
+  {
+    country: "Auto",
+    direction: "ltr",
+    label: "Auto",
+    value: "Auto",
+  },
+  {
+    country: "France",
+    direction: "ltr",
+    label: "French",
+    value: "fr-FR",
+  },
+  {
+    country: "Canada",
+    direction: "ltr",
+    label: "French (Canada)",
+    value: "fr-CA",
+  },
+  {
+    country: "Germany",
+    direction: "ltr",
+    label: "German",
+    value: "de-DE",
+  },
+  {
+    country: "United Kingdom",
+    direction: "ltr",
+    label: "English (UK)",
+    value: "en-GB",
+  },
+  {
+    country: "United States",
+    direction: "ltr",
+    label: "English (US)",
+    value: "en-US",
+  },
+  {
+    country: "Japan",
+    direction: "ltr",
+    label: "Japanese",
+    value: "ja-JP",
+  },
+  {
+    country: "Denmark",
+    direction: "ltr",
+    label: "Danish",
+    value: "da-DK",
+  },
+  {
+    country: "Netherlands",
+    direction: "ltr",
+    label: "Dutch",
+    value: "nl-NL",
+  },
+  {
+    country: "Finland",
+    direction: "ltr",
+    label: "Finnish",
+    value: "fi-FI",
+  },
+  {
+    country: "Italy",
+    direction: "ltr",
+    label: "Italian",
+    value: "it-IT",
+  },
+  {
+    country: "Norway",
+    direction: "ltr",
+    label: "Norwegian",
+    value: "nb-NO",
+  },
+  {
+    country: "Spain",
+    direction: "ltr",
+    label: "Spanish",
+    value: "es-ES",
+  },
+  {
+    country: "Sweden",
+    direction: "ltr",
+    label: "Swedish",
+    value: "sv-SE",
+  },
+  {
+    country: "Brazil",
+    direction: "ltr",
+    label: "Portuguese (Brazil)",
+    value: "pt-BR",
+  },
+  {
+    country: "Portugal",
+    direction: "ltr",
+    label: "Portuguese (Portugal)",
+    value: "pt-PT",
+  },
+  {
+    country: "China",
+    direction: "ltr",
+    label: "Chinese (Simplified)",
+    value: "zh-CN",
+  },
+  {
+    country: "Taiwan",
+    direction: "ltr",
+    label: "Chinese (Traditional)",
+    value: "zh-TW",
+  },
+  {
+    country: "South Korea",
+    direction: "ltr",
+    label: "Korean",
+    value: "ko-KR",
+  },
+  {
+    country: "Bulgaria",
+    direction: "ltr",
+    label: "Bulgarian",
+    value: "bg-BG",
+  },
+  {
+    country: "Croatia",
+    direction: "ltr",
+    label: "Croatian",
+    value: "hr-HR",
+  },
+  {
+    country: "Czech Republic",
+    direction: "ltr",
+    label: "Czech",
+    value: "cs-CZ",
+  },
+  {
+    country: "Estonia",
+    direction: "ltr",
+    label: "Estonian",
+    value: "et-EE",
+  },
+  {
+    country: "Hungary",
+    direction: "ltr",
+    label: "Hungarian",
+    value: "hu-HU",
+  },
+  {
+    country: "Latvia",
+    direction: "ltr",
+    label: "Latvian",
+    value: "lv-LV",
+  },
+  {
+    country: "Lithuania",
+    direction: "ltr",
+    label: "Lithuanian",
+    value: "lt-LT",
+  },
+  {
+    country: "Poland",
+    direction: "ltr",
+    label: "Polish",
+    value: "pl-PL",
+  },
+  {
+    country: "Romania",
+    direction: "ltr",
+    label: "Romanian",
+    value: "ro-RO",
+  },
+  {
+    country: "Russia",
+    direction: "ltr",
+    label: "Russian",
+    value: "ru-RU",
+  },
+  {
+    country: "Serbia",
+    direction: "ltr",
+    label: "Serbian",
+    value: "sr-RS",
+  },
+  {
+    country: "Slovakia",
+    direction: "ltr",
+    label: "Slovak",
+    value: "sk-SK",
+  },
+  {
+    country: "Slovenia",
+    direction: "ltr",
+    label: "Slovenian",
+    value: "sl-SI",
+  },
+  {
+    country: "Turkey",
+    direction: "ltr",
+    label: "Turkish",
+    value: "tr-TR",
+  },
+  {
+    country: "Ukraine",
+    direction: "ltr",
+    label: "Ukrainian",
+    value: "uk-UA",
+  },
+  {
+    country: "United Arab Emirates",
+    direction: "rtl",
+    label: "Arabic",
+    value: "ar-AE",
+  },
+  {
+    country: "Greece",
+    direction: "ltr",
+    label: "Greek",
+    value: "el-GR",
+  },
+  {
+    country: "Israel",
+    direction: "rtl",
+    label: "Hebrew",
+    value: "he-IL",
+  },
+];
+
+export const DEFAULT_LOCALE = "Auto";
diff --git a/packages/storybook/.storybook/addons/i18n/decorator.tsx b/packages/storybook/.storybook/addons/i18n/decorator.tsx
new file mode 100644
index 0000000..c7525cb
--- /dev/null
+++ b/packages/storybook/.storybook/addons/i18n/decorator.tsx
@@ -0,0 +1,38 @@
+import type {Decorator} from "@storybook/react";
+
+import React, {useEffect} from "react";
+import {useGlobals} from "storybook/preview-api";
+
+import {DEFAULT_LOCALE, I18N_GLOBAL_TYPE_ID, LOCALES} from "./constants";
+
+export const withInternationalization: Decorator = (Story) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  const [globals] = useGlobals();
+  const selectedLocale = globals[I18N_GLOBAL_TYPE_ID] || DEFAULT_LOCALE;
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  useEffect(() => {
+    // If auto, use navigator language, otherwise use selected
+    const localeValue =
+      selectedLocale === "Auto"
+        ? typeof navigator !== "undefined"
+          ? navigator.language
+          : "en-US"
+        : selectedLocale;
+
+    // Find the full locale object to get direction
+    // Fallback to English/LTR if not found or if Auto resolves to something we don't have explicit config for
+    // (though we mainly need direction here)
+    const localeConfig =
+      LOCALES.find((l) => l.value === localeValue) ||
+      LOCALES.find((l) => l.value.startsWith(localeValue.split("-")[0])) ||
+      LOCALES.find((l) => l.value === "en-US");
+
+    if (localeConfig) {
+      document.documentElement.lang = localeConfig.value;
+      document.documentElement.dir = localeConfig.direction;
+    }
+  }, [selectedLocale]);
+
+  return <Story />;
+};
diff --git a/packages/storybook/.storybook/addons/i18n/preview.ts b/packages/storybook/.storybook/addons/i18n/preview.ts
new file mode 100644
index 0000000..e8f0b41
--- /dev/null
+++ b/packages/storybook/.storybook/addons/i18n/preview.ts
@@ -0,0 +1,23 @@
+import {DEFAULT_LOCALE, I18N_GLOBAL_TYPE_ID, LOCALES} from "./constants";
+
+export {I18N_GLOBAL_TYPE_ID};
+
+export const i18nGlobalType = {
+  [I18N_GLOBAL_TYPE_ID]: {
+    name: "I18n",
+    description: "Internationalization locale",
+    defaultValue: DEFAULT_LOCALE,
+    toolbar: {
+      icon: "globe",
+      items: LOCALES.map((locale) => ({
+        value: locale.value,
+        title: locale.label,
+        right: locale.value === "Auto" ? undefined : locale.value,
+      })).sort((a, b) =>
+        a.value === "Auto" ? -1 : b.value === "Auto" ? 1 : a.title.localeCompare(b.title),
+      ),
+      showName: true,
+      dynamicTitle: true,
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/addons/react-scan/constants.ts b/packages/storybook/.storybook/addons/react-scan/constants.ts
new file mode 100644
index 0000000..99c023b
--- /dev/null
+++ b/packages/storybook/.storybook/addons/react-scan/constants.ts
@@ -0,0 +1,8 @@
+export const REACT_SCAN_ADDON_ID = "heroui-react-scan-addon";
+export const REACT_SCAN_GLOBAL_TYPE_ID = "heroui-react-scan";
+export const REACT_SCAN_PARAM_KEY = "heroui-react-scan";
+
+export const REACT_SCAN_VALUES = ["true", "false"] as const;
+export type ReactScanKey = (typeof REACT_SCAN_VALUES)[number];
+
+export const DEFAULT_REACT_SCAN: ReactScanKey = "false";
diff --git a/packages/storybook/.storybook/addons/react-scan/decorator.tsx b/packages/storybook/.storybook/addons/react-scan/decorator.tsx
new file mode 100644
index 0000000..6081b54
--- /dev/null
+++ b/packages/storybook/.storybook/addons/react-scan/decorator.tsx
@@ -0,0 +1,22 @@
+import type {Decorator} from "@storybook/react";
+
+import React, {useEffect} from "react";
+import {scan} from "react-scan";
+import {useGlobals} from "storybook/preview-api";
+
+import {REACT_SCAN_GLOBAL_TYPE_ID} from "./constants";
+
+export const withReactScan: Decorator = (Story) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  const [globals] = useGlobals();
+  const isEnabled = globals[REACT_SCAN_GLOBAL_TYPE_ID] === "true";
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  useEffect(() => {
+    scan({
+      enabled: isEnabled,
+    });
+  }, [isEnabled]);
+
+  return <Story />;
+};
diff --git a/packages/storybook/.storybook/addons/react-scan/preview.ts b/packages/storybook/.storybook/addons/react-scan/preview.ts
new file mode 100644
index 0000000..4738b94
--- /dev/null
+++ b/packages/storybook/.storybook/addons/react-scan/preview.ts
@@ -0,0 +1,19 @@
+import {DEFAULT_REACT_SCAN, REACT_SCAN_GLOBAL_TYPE_ID} from "./constants";
+
+export {REACT_SCAN_GLOBAL_TYPE_ID};
+
+export const reactScanGlobalType = {
+  [REACT_SCAN_GLOBAL_TYPE_ID]: {
+    name: "React Scan",
+    description: "Enable React Scan to detect performance issues (Only works in isolation mode)",
+    defaultValue: DEFAULT_REACT_SCAN,
+    toolbar: {
+      icon: "eye",
+      items: [
+        {value: "false", title: "React Scan Off", icon: "eyeclose"},
+        {value: "true", title: "React Scan On", icon: "eye"},
+      ],
+      showName: true,
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/addons/reduce-motion/constants.ts b/packages/storybook/.storybook/addons/reduce-motion/constants.ts
new file mode 100644
index 0000000..733975b
--- /dev/null
+++ b/packages/storybook/.storybook/addons/reduce-motion/constants.ts
@@ -0,0 +1,27 @@
+export const REDUCE_MOTION_ADDON_ID = "heroui-reduce-motion-addon";
+export const REDUCE_MOTION_GLOBAL_TYPE_ID = "heroui-reduce-motion";
+export const REDUCE_MOTION_PARAM_KEY = "heroui-reduce-motion";
+
+export const REDUCE_MOTION_VALUES = ["true", "false"] as const;
+export type ReduceMotionKey = (typeof REDUCE_MOTION_VALUES)[number];
+
+export const DEFAULT_REDUCE_MOTION: ReduceMotionKey = "false";
+
+export interface ReduceMotionOption {
+  value: ReduceMotionKey;
+  title: string;
+  icon?: string;
+}
+
+export const REDUCE_MOTION_OPTIONS: ReduceMotionOption[] = [
+  {
+    value: "false",
+    title: "Motion On",
+    icon: "play",
+  },
+  {
+    value: "true",
+    title: "Motion Reduced",
+    icon: "stop",
+  },
+];
diff --git a/packages/storybook/.storybook/addons/reduce-motion/decorator.tsx b/packages/storybook/.storybook/addons/reduce-motion/decorator.tsx
new file mode 100644
index 0000000..f58cf15
--- /dev/null
+++ b/packages/storybook/.storybook/addons/reduce-motion/decorator.tsx
@@ -0,0 +1,23 @@
+import type {Decorator} from "@storybook/react";
+
+import React, {useEffect} from "react";
+import {useGlobals} from "storybook/preview-api";
+
+import {REDUCE_MOTION_GLOBAL_TYPE_ID} from "./constants";
+
+export const withReduceMotion: Decorator = (Story) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  const [globals] = useGlobals();
+  const reduceMotion = globals[REDUCE_MOTION_GLOBAL_TYPE_ID] === "true";
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  useEffect(() => {
+    if (reduceMotion) {
+      document.documentElement.setAttribute("data-reduce-motion", "true");
+    } else {
+      document.documentElement.removeAttribute("data-reduce-motion");
+    }
+  }, [reduceMotion]);
+
+  return <Story />;
+};
diff --git a/packages/storybook/.storybook/addons/reduce-motion/preview.ts b/packages/storybook/.storybook/addons/reduce-motion/preview.ts
new file mode 100644
index 0000000..46e73af
--- /dev/null
+++ b/packages/storybook/.storybook/addons/reduce-motion/preview.ts
@@ -0,0 +1,25 @@
+import {
+  DEFAULT_REDUCE_MOTION,
+  REDUCE_MOTION_GLOBAL_TYPE_ID,
+  REDUCE_MOTION_OPTIONS,
+} from "./constants";
+
+export {REDUCE_MOTION_GLOBAL_TYPE_ID};
+
+export const reduceMotionGlobalType = {
+  [REDUCE_MOTION_GLOBAL_TYPE_ID]: {
+    name: "Reduce Motion",
+    description: "Reduce motion for components",
+    defaultValue: DEFAULT_REDUCE_MOTION,
+    toolbar: {
+      icon: "play",
+      items: REDUCE_MOTION_OPTIONS.map((option) => ({
+        value: option.value,
+        title: option.title,
+        icon: option.icon,
+      })),
+      showName: true,
+      dynamicTitle: true,
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/addons/strict-mode/constants.ts b/packages/storybook/.storybook/addons/strict-mode/constants.ts
new file mode 100644
index 0000000..9a5604a
--- /dev/null
+++ b/packages/storybook/.storybook/addons/strict-mode/constants.ts
@@ -0,0 +1,8 @@
+export const STRICT_MODE_ADDON_ID = "heroui-strict-mode-addon";
+export const STRICT_MODE_GLOBAL_TYPE_ID = "heroui-strict-mode";
+export const STRICT_MODE_PARAM_KEY = "heroui-strict-mode";
+
+export const STRICT_MODE_VALUES = ["true", "false"] as const;
+export type StrictModeKey = (typeof STRICT_MODE_VALUES)[number];
+
+export const DEFAULT_STRICT_MODE: StrictModeKey = "true";
diff --git a/packages/storybook/.storybook/addons/strict-mode/decorator.tsx b/packages/storybook/.storybook/addons/strict-mode/decorator.tsx
new file mode 100644
index 0000000..ac6146d
--- /dev/null
+++ b/packages/storybook/.storybook/addons/strict-mode/decorator.tsx
@@ -0,0 +1,20 @@
+import type {Decorator} from "@storybook/react";
+
+import React, {StrictMode} from "react";
+import {useGlobals} from "storybook/preview-api";
+
+import {STRICT_MODE_GLOBAL_TYPE_ID} from "./constants";
+
+export const withReactStrictMode: Decorator = (Story) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  const [globals] = useGlobals();
+  const isStrict = globals[STRICT_MODE_GLOBAL_TYPE_ID] === "true";
+
+  return isStrict ? (
+    <StrictMode>
+      <Story />
+    </StrictMode>
+  ) : (
+    <Story />
+  );
+};
diff --git a/packages/storybook/.storybook/addons/strict-mode/preview.ts b/packages/storybook/.storybook/addons/strict-mode/preview.ts
new file mode 100644
index 0000000..829e981
--- /dev/null
+++ b/packages/storybook/.storybook/addons/strict-mode/preview.ts
@@ -0,0 +1,19 @@
+import {DEFAULT_STRICT_MODE, STRICT_MODE_GLOBAL_TYPE_ID} from "./constants";
+
+export {STRICT_MODE_GLOBAL_TYPE_ID};
+
+export const strictModeGlobalType = {
+  [STRICT_MODE_GLOBAL_TYPE_ID]: {
+    name: "Strict Mode",
+    description: "Enable React Strict Mode",
+    defaultValue: DEFAULT_STRICT_MODE,
+    toolbar: {
+      icon: "lock",
+      items: [
+        {value: "false", title: "Strict Mode Off", icon: "unlock"},
+        {value: "true", title: "Strict Mode On", icon: "lock"},
+      ],
+      showName: true,
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/addons/theme/constants.ts b/packages/storybook/.storybook/addons/theme/constants.ts
new file mode 100644
index 0000000..1d878d9
--- /dev/null
+++ b/packages/storybook/.storybook/addons/theme/constants.ts
@@ -0,0 +1,34 @@
+export const THEME_ADDON_ID = "heroui-theme-addon";
+export const THEME_GLOBAL_TYPE_ID = "heroui-theme";
+export const THEME_PARAM_KEY = "heroui-theme";
+export const THEME_EVENT_NAME = "heroui-theme-changed";
+
+export const THEME_VALUES = ["light", "dark"] as const;
+export type ThemeKey = (typeof THEME_VALUES)[number];
+
+export const DEFAULT_THEME: ThemeKey = THEME_VALUES[0];
+
+export interface ThemeOption {
+  value: string;
+  title: string;
+  description?: string;
+}
+
+export const THEME_OPTIONS: ThemeOption[] = [
+  {
+    value: THEME_VALUES[0],
+    title: "Light",
+    description: "Light theme",
+  },
+  {
+    value: THEME_VALUES[1],
+    title: "Dark",
+    description: "Dark theme",
+  },
+];
+
+export const isThemeKey = (value: string | undefined | null): value is ThemeKey =>
+  !!value && THEME_VALUES.includes(value as ThemeKey);
+
+export const ensureThemeKey = (value: string | undefined | null): ThemeKey =>
+  isThemeKey(value) ? value : DEFAULT_THEME;
diff --git a/packages/storybook/.storybook/addons/theme/decorator.tsx b/packages/storybook/.storybook/addons/theme/decorator.tsx
new file mode 100644
index 0000000..290d9a7
--- /dev/null
+++ b/packages/storybook/.storybook/addons/theme/decorator.tsx
@@ -0,0 +1,54 @@
+import type {Decorator} from "@storybook/react";
+
+import React, {useEffect} from "react";
+import {addons, useGlobals} from "storybook/preview-api";
+
+import {THEME_ADDON_ID, THEME_EVENT_NAME, THEME_GLOBAL_TYPE_ID, ensureThemeKey} from "./constants";
+
+/** Update preview iframe with theme (only preview uses CSS selectors) */
+const updatePreviewTheme = (theme: string) => {
+  const root = document.documentElement;
+
+  root.setAttribute("data-theme", theme);
+  root.classList.remove("light", "dark");
+  root.classList.add(theme);
+};
+
+export const withTheme: Decorator = (Story, context) => {
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  const [globals] = useGlobals();
+  const theme = ensureThemeKey(globals[THEME_GLOBAL_TYPE_ID] as string | undefined);
+
+  // Update theme in memory and apply to preview/docs
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  useEffect(() => {
+    updatePreviewTheme(theme);
+
+    // Notify manager about theme change
+    const channel = addons.getChannel();
+
+    if (channel) {
+      channel.emit(THEME_EVENT_NAME, {theme}, {source: THEME_ADDON_ID});
+    }
+  }, [theme]);
+
+  // Listen for STORY_CHANGED and SET_STORIES events to ensure preview theme is applied
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- Storybook decorators are valid hook consumers
+  useEffect(() => {
+    const channel = addons.getChannel();
+
+    const handleEvent = () => {
+      updatePreviewTheme(theme);
+    };
+
+    channel.on("STORY_CHANGED", handleEvent);
+    channel.on("SET_STORIES", handleEvent);
+
+    return () => {
+      channel.removeListener("STORY_CHANGED", handleEvent);
+      channel.removeListener("SET_STORIES", handleEvent);
+    };
+  }, [theme]);
+
+  return <Story {...context} />;
+};
diff --git a/packages/storybook/.storybook/addons/theme/manager.ts b/packages/storybook/.storybook/addons/theme/manager.ts
new file mode 100644
index 0000000..9aff255
--- /dev/null
+++ b/packages/storybook/.storybook/addons/theme/manager.ts
@@ -0,0 +1,94 @@
+import {addons} from "storybook/manager-api";
+
+import {
+  DEFAULT_THEME,
+  THEME_EVENT_NAME,
+  THEME_GLOBAL_TYPE_ID,
+  ensureThemeKey,
+} from "../../addons/theme/constants";
+import {themes} from "../../styles/theme";
+
+// Register addon to hook into the manager lifecycle properly
+addons.register("heroui-theme-manager", (api) => {
+  let lastTheme = DEFAULT_THEME;
+
+  const updateManagerTheme = (theme: string) => {
+    const selectedTheme = themes[theme as keyof typeof themes] || themes.light;
+
+    // Get current config to preserve other settings
+    const currentConfig = (addons as any).getConfig?.() || {};
+
+    addons.setConfig({
+      ...currentConfig,
+      theme: selectedTheme,
+      enableShortcuts: currentConfig.enableShortcuts ?? false,
+      sidebar: {
+        ...currentConfig.sidebar,
+        showRoots: currentConfig.sidebar?.showRoots ?? false,
+      },
+    });
+  };
+
+  const applyTheme = (theme: string) => {
+    const next = ensureThemeKey(theme);
+
+    lastTheme = next;
+    updateManagerTheme(next);
+  };
+
+  // Initialize loop to ensure channel connection
+  const init = () => {
+    // Try to get channel from API first (more reliable in register callback), then fallback to addons
+    const channel = api.getChannel() || addons.getChannel();
+
+    if (!channel) {
+      setTimeout(init, 100);
+
+      return;
+    }
+
+    // Initialize with default
+    applyTheme(DEFAULT_THEME);
+
+    // Listen for custom theme event
+    channel.on(THEME_EVENT_NAME, (event: {theme: string}) => {
+      applyTheme(event?.theme);
+    });
+
+    // Listen for globals updates
+    channel.on("GLOBALS_UPDATED", (payload: {globals?: Record<string, unknown>}) => {
+      const theme = payload?.globals?.[THEME_GLOBAL_TYPE_ID] as string | undefined;
+
+      if (theme) applyTheme(theme);
+    });
+
+    // Replay on lifecycle events to override defaults
+    const replayEvents = [
+      "STORIES_CONFIGURED",
+      "SET_STORIES",
+      "SELECT_STORY",
+      "STORY_RENDERED",
+      "DOCS_RENDERED",
+    ] as const;
+
+    replayEvents.forEach((eventName) => {
+      channel.on(eventName, () => {
+        applyTheme(lastTheme);
+      });
+    });
+
+    // Also try to read initial globals from state if available
+    try {
+      const state = (api as any).getData?.();
+      const initialGlobalTheme = state?.globals?.[THEME_GLOBAL_TYPE_ID];
+
+      if (initialGlobalTheme) {
+        applyTheme(initialGlobalTheme as string);
+      }
+    } catch (e) {
+      // ignore
+    }
+  };
+
+  init();
+});
diff --git a/packages/storybook/.storybook/addons/theme/preview.ts b/packages/storybook/.storybook/addons/theme/preview.ts
new file mode 100644
index 0000000..9efbc0b
--- /dev/null
+++ b/packages/storybook/.storybook/addons/theme/preview.ts
@@ -0,0 +1,22 @@
+import {DEFAULT_THEME, THEME_GLOBAL_TYPE_ID, THEME_OPTIONS, THEME_VALUES} from "./constants";
+
+export {THEME_GLOBAL_TYPE_ID};
+
+export const themeGlobalType = {
+  [THEME_GLOBAL_TYPE_ID]: {
+    name: "Theme",
+    description: "HeroUI theme for components",
+    defaultValue: DEFAULT_THEME,
+    toolbar: {
+      icon: "paintbrush",
+      items: THEME_OPTIONS.filter((option) => THEME_VALUES.includes(option.value as any)).map(
+        (option) => ({
+          value: option.value,
+          title: option.title,
+        }),
+      ),
+      showName: true,
+      dynamicTitle: true,
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/components/color-picker.tsx b/packages/storybook/.storybook/components/color-picker.tsx
new file mode 100644
index 0000000..6c968a4
--- /dev/null
+++ b/packages/storybook/.storybook/components/color-picker.tsx
@@ -0,0 +1,497 @@
+import type {
+  ColorPickerProps as AriaColorPickerProps,
+  Color,
+  ColorSpace,
+} from "react-aria-components";
+
+import {ChevronLeft, ChevronRight, Shuffle} from "@gravity-ui/icons";
+import {Button, InputGroup, ListBox, Popover, Select, parseColor} from "@heroui/react";
+import React, {useState} from "react";
+import {
+  ColorArea as AriaColorArea,
+  ColorField as AriaColorField,
+  ColorPicker as AriaColorPicker,
+  ColorSlider as AriaColorSlider,
+  ColorSwatch as AriaColorSwatch,
+  ColorSwatchPicker,
+  ColorSwatchPickerItem,
+  ColorThumb,
+  Input,
+  Label,
+  SliderTrack,
+} from "react-aria-components";
+import {tv} from "tailwind-variants";
+
+import {cn} from "../utils/cn";
+import {composeTailwindRenderProps} from "../utils/compose-tw-render";
+import {focusRing} from "../utils/focus";
+
+/* -------------------------------------------------------------------------------------------------
+ * Styles
+ * -----------------------------------------------------------------------------------------------*/
+
+const colorSwatchStyles = tv({
+  base: "size-8 rounded-full border border-black/10 shadow-sm forced-colors:bg-[Canvas]",
+  extend: focusRing,
+});
+
+const colorAreaStyles = tv({
+  base: "size-full min-h-48 min-w-48 shrink-0 rounded-xl forced-colors:bg-[GrayText]",
+});
+
+const colorThumbStyles = tv({
+  base: "size-6 rounded-full border-[3px] border-white shadow-lg forced-colors:bg-[Canvas]!",
+  extend: focusRing,
+});
+
+const colorSliderTrackStyles = tv({
+  base: "h-8 w-full rounded-full forced-colors:bg-[GrayText]",
+  variants: {
+    orientation: {
+      horizontal: "h-8 w-full",
+      vertical: "ml-2 h-full w-8",
+    },
+  },
+});
+
+const colorFieldStyles = tv({
+  base: "flex flex-1 flex-col gap-1",
+});
+
+const colorFieldInputStyles = tv({
+  base: "h-12 w-full rounded-xl border-none bg-default px-4 text-sm text-foreground transition-all outline-none placeholder:text-muted",
+  extend: focusRing,
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * Default Swatches
+ * -----------------------------------------------------------------------------------------------*/
+
+const defaultSwatches = [
+  // Original 8 colors
+  "hsla(26, 35%, 92%, 1)", // Light beige
+  "hsla(338, 77%, 78%, 1)", // Pink
+  "hsla(309, 23%, 55%, 1)", // Muted purple
+  "hsla(355, 85%, 66%, 1)", // Coral/red
+  "hsla(16, 100%, 67%, 1)", // Orange
+  "hsla(47, 92%, 66%, 1)", // Yellow
+  "hsla(152, 80%, 56%, 1)", // Green
+  "hsla(197, 59%, 64%, 1)", // Blue
+  "hsla(220, 13%, 18%, 1)", // Dark slate (backgrounds)
+  "hsla(220, 70%, 50%, 1)", // Royal blue
+  "hsla(210, 100%, 56%, 1)", // Bright blue
+  "hsla(180, 100%, 25%, 1)", // Teal
+  "hsla(170, 50%, 65%, 1)", // Seafoam
+  "hsla(150, 60%, 75%, 1)", // Mint green
+  "hsla(280, 60%, 60%, 1)", // Violet
+  "hsla(270, 50%, 70%, 1)", // Lavender
+  "hsla(350, 100%, 88%, 1)", // Blush
+  "hsla(10, 80%, 65%, 1)", // Tomato red
+  "hsla(30, 90%, 55%, 1)", // Dark orange
+  "hsla(45, 100%, 51%, 1)", // Gold
+  "hsla(60, 90%, 85%, 1)", // Pale yellow
+  "hsla(0, 0%, 95%, 1)", // Cloud white
+  "hsla(0, 0%, 70%, 1)", // Medium gray
+  "hsla(0, 0%, 40%, 1)", // Charcoal
+];
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSwatch (Trigger Button)
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ColorSwatchProps {
+  className?: string;
+}
+
+function ColorSwatch({className}: ColorSwatchProps) {
+  return (
+    <AriaColorSwatch
+      className={cn(colorSwatchStyles(), className)}
+      style={({color}) => ({
+        background: color.toString("css"),
+      })}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorArea
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ColorAreaProps {
+  colorSpace?: ColorSpace;
+  xChannel?: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  yChannel?: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  className?: string;
+}
+
+function ColorArea({className, colorSpace = "hsb", xChannel, yChannel}: ColorAreaProps) {
+  return (
+    <AriaColorArea
+      className={composeTailwindRenderProps(className, colorAreaStyles())}
+      colorSpace={colorSpace}
+      xChannel={xChannel}
+      yChannel={yChannel}
+    >
+      <ColorThumb
+        className={colorThumbStyles}
+        style={({color}) => ({
+          background: color.toString("css"),
+        })}
+      />
+    </AriaColorArea>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorSlider
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ColorSliderProps {
+  channel: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  colorSpace?: ColorSpace;
+  orientation?: "horizontal" | "vertical";
+  label?: string;
+  showOutput?: boolean;
+  className?: string;
+}
+
+function ColorSlider({
+  channel,
+  className,
+  colorSpace,
+  orientation = "horizontal",
+}: ColorSliderProps) {
+  return (
+    <AriaColorSlider
+      channel={channel}
+      className={cn("group flex w-full flex-col gap-1", className)}
+      colorSpace={colorSpace}
+      orientation={orientation}
+    >
+      <SliderTrack
+        className={colorSliderTrackStyles({orientation})}
+        style={({defaultStyle}) => ({
+          background: `${defaultStyle.background}`,
+        })}
+      >
+        <ColorThumb
+          className={cn(colorThumbStyles(), orientation === "horizontal" ? "top-1/2" : "left-1/2")}
+          style={({color}) => ({
+            background: color.toString("css"),
+          })}
+        />
+      </SliderTrack>
+    </AriaColorSlider>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorField
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ColorFieldProps {
+  label?: string;
+  channel?: "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+  colorSpace?: ColorSpace;
+  className?: string;
+}
+
+function ColorField({channel, className, colorSpace, label}: ColorFieldProps) {
+  return (
+    <AriaColorField
+      channel={channel}
+      className={cn(colorFieldStyles(), className)}
+      colorSpace={colorSpace}
+    >
+      {label ? <Label className="text-sm font-medium text-foreground">{label}</Label> : null}
+      <Input className={colorFieldInputStyles} />
+    </AriaColorField>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorPicker
+ * -----------------------------------------------------------------------------------------------*/
+
+export interface ColorPickerProps extends Omit<AriaColorPickerProps, "children"> {
+  /** Label for the trigger button */
+  label?: string;
+  /** Custom children for the popover content */
+  children?: React.ReactNode;
+  /** Show alpha slider */
+  showAlpha?: boolean;
+  /** Show hex/color field */
+  showColorField?: boolean;
+  /** Show color swatches */
+  showSwatches?: boolean;
+  /** Custom swatches array */
+  swatches?: string[];
+  /** Show shuffle/random button */
+  showShuffle?: boolean;
+  /** Custom trigger element */
+  trigger?: React.ReactNode;
+  /** Class name for popover content */
+  popoverClassName?: string;
+}
+
+// Helper to chunk array into pages
+function chunkArray<T>(array: T[], chunkSize: number): T[][] {
+  const chunks: T[][] = [];
+
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize));
+  }
+
+  return chunks;
+}
+
+const handleParseColor = (color: string | Color) => {
+  try {
+    if (typeof color === "string") {
+      return parseColor(color);
+    }
+
+    return color;
+  } catch (error) {
+    return parseColor("#006FEE");
+  }
+};
+
+const SWATCHES_PER_PAGE = 8;
+
+export default function ColorPicker({
+  children,
+  defaultValue = "#006FEE",
+  onChange,
+  popoverClassName,
+  showAlpha = false,
+  showColorField = true,
+  showShuffle = true,
+  showSwatches = true,
+  swatches = defaultSwatches,
+  trigger,
+  value: controlledValue,
+  ...props
+}: ColorPickerProps) {
+  const [colorFormat, setColorFormat] = useState<"hex" | "hsl" | "rgb" | "hsb">("hex");
+
+  // Chunk swatches into pages of 8
+  const swatchPages = React.useMemo(() => chunkArray(swatches, SWATCHES_PER_PAGE), [swatches]);
+  const totalPages = swatchPages.length;
+
+  // Safely parse color - react-aria doesn't support OKLCH or other modern color formats
+  const safeDefaultValue = React.useMemo(() => {
+    if (!defaultValue) return parseColor("#006FEE");
+
+    // If it's already a Color object, return as-is
+    if (typeof defaultValue !== "string") return defaultValue;
+
+    // Check for unsupported color formats (oklch, oklab, lab, lch, etc.)
+    const unsupportedFormats = ["oklch", "oklab", "lab(", "lch(", "color("];
+
+    if (unsupportedFormats.some((format) => defaultValue.toLowerCase().startsWith(format))) {
+      return parseColor("#006FEE"); // Fallback to default blue
+    }
+
+    // Try to parse, fallback if it fails
+    try {
+      return parseColor(defaultValue);
+    } catch {
+      return parseColor("#006FEE");
+    }
+  }, [defaultValue]);
+
+  // Internal color state for uncontrolled mode
+  const [internalColor, setInternalColor] = useState<Color>(safeDefaultValue);
+
+  // Use controlled value if provided, otherwise use internal state
+  const color = controlledValue ? handleParseColor(controlledValue) : internalColor;
+
+  // Calculate initial swatch page based on current color - using lazy initializer
+  const [swatchPage, setSwatchPage] = useState(() => {
+    const currentColorHex =
+      (controlledValue as string | undefined)?.toLowerCase() ??
+      safeDefaultValue.toString("hex").toLowerCase();
+    const swatchIndex = swatches.findIndex((s) => s.toLowerCase() === currentColorHex);
+
+    return swatchIndex !== -1 ? Math.floor(swatchIndex / SWATCHES_PER_PAGE) : 0;
+  });
+
+  const handleColorChange = (newColor: Color) => {
+    if (!controlledValue) {
+      setInternalColor(newColor);
+    }
+    onChange?.(newColor);
+  };
+
+  const navigateSwatches = (direction: "left" | "right") => {
+    setSwatchPage((prev) => {
+      if (direction === "left") {
+        return Math.max(0, prev - 1);
+      }
+
+      return Math.min(totalPages - 1, prev + 1);
+    });
+  };
+
+  const isFirstPage = swatchPage === 0;
+  const isLastPage = swatchPage === totalPages - 1;
+
+  const handleShuffle = () => {
+    // Generate a random color
+    const randomHue = Math.floor(Math.random() * 360);
+    const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
+    const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
+    const randomColor = parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`);
+
+    handleColorChange(randomColor);
+  };
+
+  return (
+    <AriaColorPicker value={color} onChange={handleColorChange} {...props}>
+      {({color}) => (
+        <Popover>
+          <Popover.Trigger>{trigger}</Popover.Trigger>
+          <Popover.Content className={cn("w-[248px]", popoverClassName)} placement="top">
+            <Popover.Dialog className="flex flex-col gap-2 px-2 pt-4 pb-2">
+              {children ?? (
+                <>
+                  {/* Color Swatches Carousel */}
+                  {showSwatches && totalPages > 0 ? (
+                    <div className="flex items-center gap-2">
+                      <Button
+                        isIconOnly
+                        className="size-4 min-w-4 shrink-0 rounded-full"
+                        isDisabled={isFirstPage}
+                        size="sm"
+                        variant="ghost"
+                        onPress={() => navigateSwatches("left")}
+                      >
+                        <ChevronLeft className="size-4" />
+                      </Button>
+                      {/* Carousel container */}
+                      <div className="relative flex-1 overflow-hidden">
+                        {/* Sliding track containing all pages */}
+                        <div
+                          className="flex transition-transform duration-300 ease-out"
+                          style={{
+                            transform: `translateX(-${swatchPage * 100}%)`,
+                          }}
+                        >
+                          {swatchPages.map((pageSwatches, pageIndex) => (
+                            <div
+                              key={pageIndex}
+                              className="flex h-[22px] w-full shrink-0 justify-center"
+                            >
+                              <ColorSwatchPicker className="flex items-center justify-start gap-1.5">
+                                {pageSwatches.map((swatch) => (
+                                  <ColorSwatchPickerItem
+                                    key={swatch}
+                                    className="size-4 rounded-full transition-all data-selected:ring-2 data-selected:ring-foreground data-selected:ring-offset-1"
+                                    color={swatch}
+                                  >
+                                    <AriaColorSwatch
+                                      className="size-full cursor-pointer rounded-full"
+                                      style={{background: swatch}}
+                                    />
+                                  </ColorSwatchPickerItem>
+                                ))}
+                              </ColorSwatchPicker>
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                      <Button
+                        isIconOnly
+                        className="size-4 min-w-4 shrink-0 rounded-full"
+                        isDisabled={isLastPage}
+                        size="sm"
+                        variant="ghost"
+                        onPress={() => navigateSwatches("right")}
+                      >
+                        <ChevronRight className="size-4" />
+                      </Button>
+                    </div>
+                  ) : null}
+
+                  {/* Color Area */}
+                  <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness" />
+
+                  {/* Hue Slider with Shuffle */}
+                  <div className="flex items-center gap-2">
+                    <ColorSlider channel="hue" className="h-5 flex-1" colorSpace="hsb" />
+                    {showShuffle ? (
+                      <Button
+                        isIconOnly
+                        className="size-8 min-w-8 shrink-0 rounded-full"
+                        size="sm"
+                        variant="tertiary"
+                        onPress={handleShuffle}
+                      >
+                        <Shuffle className="size-4" />
+                      </Button>
+                    ) : null}
+                  </div>
+
+                  {/* Alpha Slider */}
+                  {showAlpha ? <ColorSlider channel="alpha" /> : null}
+
+                  {/* Color Field with Color Space Selector */}
+                  {showColorField ? (
+                    <InputGroup fullWidth className="rounded-xl">
+                      <InputGroup.Input
+                        readOnly
+                        className="w-full flex-1 px-4 text-sm"
+                        value={color.toString(colorFormat)}
+                      />
+                      <InputGroup.Suffix className="border-l border-separator px-0">
+                        <Select
+                          aria-label="Color format"
+                          value={colorFormat}
+                          onChange={(key) => {
+                            if (key) {
+                              setColorFormat(key as "hex" | "hsl" | "rgb" | "hsb");
+                            }
+                          }}
+                        >
+                          <Select.Trigger className="h-full min-w-17 rounded-none border-none bg-transparent px-3">
+                            <Select.Value />
+                            <Select.Indicator />
+                          </Select.Trigger>
+                          <Select.Popover>
+                            <ListBox>
+                              <ListBox.Item id="hex" textValue="HEX">
+                                HEX
+                              </ListBox.Item>
+                              <ListBox.Item id="hsl" textValue="HSL">
+                                HSL
+                              </ListBox.Item>
+                              <ListBox.Item id="rgb" textValue="RGB">
+                                RGB
+                              </ListBox.Item>
+                              <ListBox.Item id="hsb" textValue="HSB">
+                                HSB
+                              </ListBox.Item>
+                            </ListBox>
+                          </Select.Popover>
+                        </Select>
+                      </InputGroup.Suffix>
+                    </InputGroup>
+                  ) : null}
+                </>
+              )}
+            </Popover.Dialog>
+          </Popover.Content>
+        </Popover>
+      )}
+    </AriaColorPicker>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Additional Export for Flexibility
+ * -----------------------------------------------------------------------------------------------*/
+
+// eslint-disable-next-line react-refresh/only-export-components
+export {ColorArea, ColorField, ColorSlider, ColorSwatch, parseColor};
diff --git a/packages/storybook/.storybook/components/colors-demo/color-controls.tsx b/packages/storybook/.storybook/components/colors-demo/color-controls.tsx
new file mode 100644
index 0000000..9f3c0f7
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/color-controls.tsx
@@ -0,0 +1,301 @@
+import {Label} from "@heroui/react";
+import React, {useCallback, useRef} from "react";
+import {tv} from "tailwind-variants";
+
+import {cn} from "../../utils/cn";
+
+/* -------------------------------------------------------------------------------------------------
+ * Styles
+ * -----------------------------------------------------------------------------------------------*/
+
+const sliderTrackStyles = tv({
+  base: "relative h-8 w-full cursor-pointer rounded-full",
+});
+
+const sliderThumbStyles = tv({
+  base: [
+    "absolute top-1/2 -translate-x-1/2 -translate-y-1/2",
+    "size-6 rounded-full border-[3px] border-white shadow-lg",
+    "cursor-grab active:cursor-grabbing",
+    "outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2",
+    "transition-shadow",
+  ],
+});
+
+/* -------------------------------------------------------------------------------------------------
+ * HueSlider - A slider for selecting hue (0-360)
+ * -----------------------------------------------------------------------------------------------*/
+
+interface HueSliderProps {
+  value: number;
+  chroma: number;
+  onChange: (value: number) => void;
+  className?: string;
+}
+
+function HueSlider({chroma, className, onChange, value}: HueSliderProps) {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+
+  const getValueFromPosition = useCallback(
+    (clientX: number) => {
+      if (!trackRef.current) return value;
+      const rect = trackRef.current.getBoundingClientRect();
+      const percentage = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+
+      return Math.round(percentage * 360);
+    },
+    [value],
+  );
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      isDragging.current = true;
+      onChange(getValueFromPosition(e.clientX));
+
+      const handleMouseMove = (e: MouseEvent) => {
+        if (isDragging.current) {
+          onChange(getValueFromPosition(e.clientX));
+        }
+      };
+
+      const handleMouseUp = () => {
+        isDragging.current = false;
+        document.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseup", handleMouseUp);
+      };
+
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+    },
+    [getValueFromPosition, onChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      let newValue = value;
+
+      switch (e.key) {
+        case "ArrowLeft":
+        case "ArrowDown":
+          newValue = Math.max(0, value - (e.shiftKey ? 10 : 1));
+          break;
+        case "ArrowRight":
+        case "ArrowUp":
+          newValue = Math.min(360, value + (e.shiftKey ? 10 : 1));
+          break;
+        case "Home":
+          newValue = 0;
+          break;
+        case "End":
+          newValue = 360;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChange(newValue);
+    },
+    [value, onChange],
+  );
+
+  // Calculate thumb position (0-100%)
+  const thumbPosition = (value / 360) * 100;
+
+  // Current color at this hue - use the chroma value for the gradient
+  const displayChroma = Math.max(0.2, chroma);
+  const currentColor = `oklch(0.7 ${displayChroma} ${value})`;
+
+  // Build gradient with the current chroma level for accurate representation
+  const gradientStops = [0, 60, 120, 180, 240, 300, 360]
+    .map((h) => `oklch(0.7 ${displayChroma} ${h})`)
+    .join(", ");
+
+  return (
+    <div
+      ref={trackRef}
+      aria-label="Base tone"
+      aria-valuemax={360}
+      aria-valuemin={0}
+      aria-valuenow={value}
+      className={cn(sliderTrackStyles(), className)}
+      role="slider"
+      tabIndex={0}
+      style={{
+        background: `linear-gradient(to right, ${gradientStops})`,
+      }}
+      onKeyDown={handleKeyDown}
+      onMouseDown={handleMouseDown}
+    >
+      <div
+        className={sliderThumbStyles()}
+        style={{
+          left: `${thumbPosition}%`,
+          backgroundColor: currentColor,
+        }}
+      />
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ChromaSlider - A slider for selecting chroma/saturation (0-0.2)
+ * Reference: https://codepen.io example uses 0-0.2 range with step 0.001
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ChromaSliderProps {
+  value: number;
+  hue: number;
+  onChange: (value: number) => void;
+  className?: string;
+}
+
+// Max chroma for subtle gray tinting - 0.02 keeps colors professional without high contrast
+const MAX_CHROMA = 0.02;
+
+function ChromaSlider({className, hue, onChange, value}: ChromaSliderProps) {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+
+  const getValueFromPosition = useCallback(
+    (clientX: number) => {
+      if (!trackRef.current) return value;
+      const rect = trackRef.current.getBoundingClientRect();
+      const percentage = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+
+      // Round to 4 decimal places for finer control with smaller max
+      return Math.round(percentage * MAX_CHROMA * 10000) / 10000;
+    },
+    [value],
+  );
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      isDragging.current = true;
+      onChange(getValueFromPosition(e.clientX));
+
+      const handleMouseMove = (e: MouseEvent) => {
+        if (isDragging.current) {
+          onChange(getValueFromPosition(e.clientX));
+        }
+      };
+
+      const handleMouseUp = () => {
+        isDragging.current = false;
+        document.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseup", handleMouseUp);
+      };
+
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+    },
+    [getValueFromPosition, onChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      let newValue = value;
+      const step = e.shiftKey ? 0.002 : 0.0002;
+
+      switch (e.key) {
+        case "ArrowLeft":
+        case "ArrowDown":
+          newValue = Math.max(0, value - step);
+          break;
+        case "ArrowRight":
+        case "ArrowUp":
+          newValue = Math.min(MAX_CHROMA, value + step);
+          break;
+        case "Home":
+          newValue = 0;
+          break;
+        case "End":
+          newValue = MAX_CHROMA;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChange(Math.round(newValue * 10000) / 10000);
+    },
+    [value, onChange],
+  );
+
+  // Calculate thumb position (0-100%)
+  const thumbPosition = (value / MAX_CHROMA) * 100;
+
+  // Current color at this chroma level
+  const currentColor = `oklch(0.7 ${value} ${hue})`;
+
+  return (
+    <div
+      ref={trackRef}
+      aria-label="Amount of color in gray"
+      aria-valuemax={MAX_CHROMA}
+      aria-valuemin={0}
+      aria-valuenow={value}
+      className={cn(sliderTrackStyles(), className)}
+      role="slider"
+      tabIndex={0}
+      style={{
+        background: `linear-gradient(to right, oklch(0.7 0 ${hue}), oklch(0.7 ${MAX_CHROMA} ${hue}))`,
+      }}
+      onKeyDown={handleKeyDown}
+      onMouseDown={handleMouseDown}
+    >
+      <div
+        className={sliderThumbStyles()}
+        style={{
+          left: `${thumbPosition}%`,
+          backgroundColor: currentColor,
+        }}
+      />
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * ColorControls
+ * -----------------------------------------------------------------------------------------------*/
+
+interface ColorControlsProps {
+  baseHue: number;
+  grayChroma: number;
+  onBaseHueChange: (hue: number) => void;
+  onGrayChromaChange: (chroma: number) => void;
+}
+
+export function ColorControls({
+  baseHue,
+  grayChroma,
+  onBaseHueChange,
+  onGrayChromaChange,
+}: ColorControlsProps) {
+  return (
+    <div className="flex items-center justify-start gap-8 p-4">
+      {/* Base Tone Slider */}
+      <div className="flex items-center gap-3">
+        <Label className="text-sm font-medium whitespace-nowrap text-foreground">Base tone</Label>
+        <HueSlider
+          chroma={grayChroma}
+          className="w-[240px]"
+          value={baseHue}
+          onChange={onBaseHueChange}
+        />
+      </div>
+
+      {/* Gray Chroma Slider */}
+      <div className="flex items-center gap-3">
+        <Label className="text-sm font-medium whitespace-nowrap text-foreground">
+          Amount of color in gray
+        </Label>
+        <ChromaSlider
+          className="w-[240px]"
+          hue={baseHue}
+          value={grayChroma}
+          onChange={onGrayChromaChange}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/components/colors-demo/color-variables-list.tsx b/packages/storybook/.storybook/components/colors-demo/color-variables-list.tsx
new file mode 100644
index 0000000..066b4fb
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/color-variables-list.tsx
@@ -0,0 +1,93 @@
+import type {ColorVariableValue} from "../../hooks/use-color-variables";
+
+import React from "react";
+
+import {groupVariablesByCategory} from "../../hooks/use-color-variables";
+
+interface ColorVariablesListProps {
+  variables: ColorVariableValue[];
+}
+
+interface ColorSwatchProps {
+  value: string;
+  name: string;
+}
+
+function ColorSwatch({name, value}: ColorSwatchProps) {
+  return (
+    <div
+      className="size-6 shrink-0 rounded border border-border/50"
+      style={{backgroundColor: value}}
+      title={`${name}: ${value}`}
+    />
+  );
+}
+
+interface ColorVariableRowProps {
+  variable: ColorVariableValue;
+}
+
+function ColorVariableRow({variable}: ColorVariableRowProps) {
+  const displayValue = variable.computedValue || variable.rawValue || "unset";
+
+  return (
+    <div className="flex items-start gap-2 py-1">
+      <div className="flex flex-col gap-0.5">
+        <div className="flex items-center gap-2">
+          <span className="font-mono text-xs font-semibold text-foreground">{variable.name}</span>
+          <ColorSwatch name={variable.name} value={displayValue} />
+        </div>
+        <span className="font-mono text-xs text-accent">{displayValue}</span>
+      </div>
+    </div>
+  );
+}
+
+export function ColorVariablesList({variables}: ColorVariablesListProps) {
+  const groupedVariables = groupVariablesByCategory(variables);
+
+  const categoryOrder = [
+    "primitive",
+    "base",
+    "surface",
+    "overlay",
+    "semantic",
+    "accent",
+    "status",
+    "field",
+    "border",
+  ];
+
+  const categoryLabels: Record<string, string> = {
+    primitive: "Primitives",
+    base: "Base",
+    surface: "Surface",
+    overlay: "Overlay",
+    semantic: "Semantic",
+    accent: "Accent",
+    status: "Status",
+    field: "Fields",
+    border: "Borders",
+  };
+
+  return (
+    <div className="flex h-full flex-col gap-4 overflow-y-auto pr-2 text-sm">
+      {categoryOrder.map((category) => {
+        const categoryVars = groupedVariables[category];
+
+        if (!categoryVars || categoryVars.length === 0) return null;
+
+        return (
+          <div key={category} className="flex flex-col gap-1">
+            <h3 className="mb-1 text-xs font-semibold tracking-wider text-muted uppercase">
+              {categoryLabels[category] || category}
+            </h3>
+            {categoryVars.map((variable) => (
+              <ColorVariableRow key={variable.name} variable={variable} />
+            ))}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/components/colors-demo/colors-demo.tsx b/packages/storybook/.storybook/components/colors-demo/colors-demo.tsx
new file mode 100644
index 0000000..670cc70
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/colors-demo.tsx
@@ -0,0 +1,197 @@
+import type {ColorVariable, OklchColor} from "../../utils/oklch-utils";
+
+import React, {useCallback, useEffect, useRef, useState} from "react";
+
+import {buildThemeCssVars, generateThemeColors} from "../../utils/apcach-colors";
+import {COLOR_VARIABLES, parseOklch} from "../../utils/oklch-utils";
+
+import {ColorControls} from "./color-controls";
+import {ColorVariablesList} from "./color-variables-list";
+import {PreviewColumn} from "./preview-column";
+
+interface ColorVariableValue {
+  name: string;
+  label: string;
+  category: string;
+  rawValue: string;
+  computedValue: string;
+  oklch: OklchColor | null;
+}
+
+export function ColorsDemo() {
+  const lightRef = useRef<HTMLDivElement>(null);
+  const darkRef = useRef<HTMLDivElement>(null);
+
+  // Initialize with values matching the default theme's accent (blue, hue ~254)
+  // Reference default chroma: 0.0015 (very subtle)
+  const [baseHue, setBaseHue] = useState(245);
+  const [grayChroma, setGrayChroma] = useState(0.0015);
+  const [variables, setVariables] = useState<ColorVariableValue[]>([]);
+  const [initialized, setInitialized] = useState(false);
+
+  /**
+   * Read CSS variables from an element
+   */
+  const readVariables = useCallback(() => {
+    const element = lightRef.current || document.documentElement;
+    const computedStyle = getComputedStyle(element);
+
+    const values: ColorVariableValue[] = COLOR_VARIABLES.map((variable: ColorVariable) => {
+      const rawValue = computedStyle.getPropertyValue(variable.name).trim();
+      const computedValue = rawValue || "unset";
+      const oklch = parseOklch(computedValue);
+
+      return {
+        name: variable.name,
+        label: variable.label,
+        category: variable.category,
+        rawValue,
+        computedValue,
+        oklch,
+      };
+    });
+
+    setVariables(values);
+  }, []);
+
+  /**
+   * Get or create the style element for CSS variable overrides
+   */
+  const styleRef = useRef<HTMLStyleElement | null>(null);
+
+  /**
+   * Apply CSS variable changes by injecting a style element
+   * Uses apcach for APCA-based contrast calculations
+   */
+  const applyColorChanges = useCallback(
+    (hue: number, chroma: number) => {
+      // Create or update the style element
+      if (!styleRef.current) {
+        styleRef.current = document.createElement("style");
+        styleRef.current.id = "colors-demo-overrides";
+        document.head.appendChild(styleRef.current);
+      }
+
+      // Generate colors using apcach library (APCA-based contrast)
+      const colors = generateThemeColors(hue, chroma);
+
+      // Build CSS for both light and dark themes
+      const lightCss = buildThemeCssVars(colors, "light");
+      const darkCss = buildThemeCssVars(colors, "dark");
+
+      // Generate CSS with high specificity selectors
+      styleRef.current.textContent = `
+        .light, [data-theme="light"] {
+          ${lightCss};
+        }
+        .dark, [data-theme="dark"] {
+          ${darkCss};
+        }
+      `;
+
+      // Re-read variables after applying changes
+      setTimeout(readVariables, 50);
+    },
+    [readVariables],
+  );
+
+  // Cleanup style element on unmount
+  useEffect(() => {
+    return () => {
+      if (styleRef.current) {
+        styleRef.current.remove();
+        styleRef.current = null;
+      }
+    };
+  }, []);
+
+  /**
+   * Handle base hue change
+   */
+  const handleBaseHueChange = useCallback(
+    (hue: number) => {
+      setBaseHue(hue);
+      applyColorChanges(hue, grayChroma);
+    },
+    [grayChroma, applyColorChanges],
+  );
+
+  /**
+   * Handle gray chroma change
+   */
+  const handleGrayChromaChange = useCallback(
+    (chroma: number) => {
+      setGrayChroma(chroma);
+      applyColorChanges(baseHue, chroma);
+    },
+    [baseHue, applyColorChanges],
+  );
+
+  // Initialize by reading actual CSS values and applying them
+  useEffect(() => {
+    if (initialized) return;
+
+    // Read current accent color from CSS
+    const computedStyle = getComputedStyle(document.documentElement);
+    const accentValue = computedStyle.getPropertyValue("--accent").trim();
+    const accentOklch = parseOklch(accentValue);
+
+    let initialHue = 245; // Default blue hue
+
+    if (accentOklch) {
+      initialHue = Math.round(accentOklch.h);
+    }
+
+    // Read current background chroma
+    const bgValue = computedStyle.getPropertyValue("--background").trim();
+    const bgOklch = parseOklch(bgValue);
+    let initialChroma = 0.0015; // Very subtle default
+
+    if (bgOklch && bgOklch.c > 0) {
+      initialChroma = bgOklch.c;
+    }
+
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setBaseHue(initialHue);
+
+    setGrayChroma(initialChroma);
+
+    // Apply initial colors with apcach
+    applyColorChanges(initialHue, initialChroma);
+
+    readVariables();
+    setInitialized(true);
+  }, [initialized, readVariables, applyColorChanges]);
+
+  return (
+    <div className="flex flex-col">
+      {/* Top Controls - Fixed at top */}
+      <div className="sticky top-0 z-10 shrink-0 bg-background text-foreground">
+        <ColorControls
+          baseHue={baseHue}
+          grayChroma={grayChroma}
+          onBaseHueChange={handleBaseHueChange}
+          onGrayChromaChange={handleGrayChromaChange}
+        />
+      </div>
+      {/* Main Content */}
+      <div className="flex min-h-0 flex-1">
+        {/* Left Sidebar - Color Variables */}
+        <div className="w-60 shrink-0 overflow-y-auto">
+          <div className="p-4">
+            <h2 className="mb-4 text-sm font-semibold">Color Variables</h2>
+            <ColorVariablesList variables={variables} />
+          </div>
+        </div>
+
+        {/* Preview Columns */}
+        <div className="flex flex-1 gap-3 overflow-x-auto pt-2 pb-24">
+          {/* Light Theme Preview */}
+          <PreviewColumn ref={lightRef} theme="light" />
+          {/* Dark Theme Preview */}
+          <PreviewColumn ref={darkRef} theme="dark" />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/components/colors-demo/component-showcase.tsx b/packages/storybook/.storybook/components/colors-demo/component-showcase.tsx
new file mode 100644
index 0000000..c5bc2c4
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/component-showcase.tsx
@@ -0,0 +1,902 @@
+/* eslint-disable jsx-a11y/anchor-is-valid */
+import {
+  Alert,
+  AlertDialog,
+  Avatar,
+  Button,
+  Card,
+  Checkbox,
+  Chip,
+  CloseButton,
+  Dropdown,
+  Header,
+  Input,
+  Label,
+  Link,
+  ListBox,
+  Modal,
+  Popover,
+  Radio,
+  RadioGroup,
+  Select,
+  Separator,
+  Slider,
+  Spinner,
+  Surface,
+  Switch,
+  Tabs,
+} from "@heroui/react";
+import {Icon} from "@iconify/react";
+import React from "react";
+
+import {HeroUILogo} from "../heroui-logo";
+
+export function ComponentShowcase() {
+  return (
+    <div>
+      {/* Navigation */}
+      <nav className="flex items-end gap-4 border-b border-border px-6 pt-4 pb-3 text-sm font-medium">
+        <HeroUILogo size={24} />
+        <a className="text-foreground hover:text-accent" href="#">
+          Pricing
+        </a>
+        <a className="text-foreground hover:text-accent" href="#">
+          Docs
+        </a>
+        <a className="text-foreground hover:text-accent" href="#">
+          Blog
+        </a>
+      </nav>
+      <main className="flex flex-col gap-4 p-6">
+        {/* Hero Section */}
+        <h1 className="text-3xl leading-tight font-extrabold text-foreground">
+          Beautiful by default.
+          <br />
+          Customizable by design.
+          <br />
+        </h1>
+        <p className="rounded-xl text-sm text-muted">
+          HeroUI is the modern UI library for web and mobile.
+        </p>
+        {/* Buttons */}
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm">Primary</Button>
+          <Button size="sm" variant="secondary">
+            Secondary
+          </Button>
+          <Button size="sm" variant="tertiary">
+            Tertiary
+          </Button>
+          <Button size="sm" variant="outline">
+            Outline
+          </Button>
+          <Button size="sm" variant="ghost">
+            Ghost
+          </Button>
+          <Button size="sm" variant="danger">
+            Danger
+          </Button>
+          <Button size="sm" variant="danger-soft">
+            Danger Soft
+          </Button>
+        </div>
+
+        <Separator />
+
+        {/* Chips Section */}
+        <h3 className="text-sm font-semibold text-muted">Status Chips</h3>
+        <div className="flex flex-wrap gap-2">
+          <Chip color="accent" variant="secondary">
+            Accent
+          </Chip>
+          <Chip color="default" variant="secondary">
+            Default
+          </Chip>
+          <Chip color="success" variant="secondary">
+            Success
+          </Chip>
+          <Chip color="warning" variant="secondary">
+            Warning
+          </Chip>
+          <Chip color="danger" variant="secondary">
+            Danger
+          </Chip>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          <Chip color="accent" variant="soft">
+            Accent Soft
+          </Chip>
+          <Chip color="success" variant="soft">
+            Success Soft
+          </Chip>
+          <Chip color="warning" variant="soft">
+            Warning Soft
+          </Chip>
+          <Chip color="danger" variant="soft">
+            Danger Soft
+          </Chip>
+        </div>
+
+        {/* Borders and Surfaces Section */}
+        <div className="grid grid-cols-2 gap-4">
+          {/* Borders */}
+          <div className="flex flex-col gap-3">
+            <h3 className="text-sm font-semibold text-muted">Borders</h3>
+            <div className="flex flex-col gap-2">
+              <div className="flex h-12 items-center justify-start rounded-xl border border-border pl-3">
+                <span className="text-sm text-foreground">Border default</span>
+              </div>
+              <div className="flex h-12 items-center justify-start rounded-xl border border-border-secondary pl-3">
+                <span className="text-sm text-foreground">Border secondary</span>
+              </div>
+              <div className="flex h-12 items-center justify-start rounded-xl border border-border-tertiary pl-3">
+                <span className="text-sm text-foreground">Border tertiary</span>
+              </div>
+            </div>
+          </div>
+
+          {/* Surfaces */}
+          <div className="flex flex-col gap-3">
+            <h3 className="text-sm font-semibold text-muted">Surfaces</h3>
+            <div className="flex flex-col gap-2">
+              <Surface className="rounded-xl p-3" variant="default">
+                <span className="text-sm text-foreground">Surface default</span>
+              </Surface>
+              <Surface className="rounded-xl p-3" variant="secondary">
+                <span className="text-sm text-foreground">Surface secondary</span>
+              </Surface>
+              <Surface className="rounded-xl p-3" variant="tertiary">
+                <span className="text-sm text-foreground">Surface tertiary</span>
+              </Surface>
+            </div>
+          </div>
+        </div>
+
+        {/* Cards Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Cards</h3>
+          <div className="flex w-full items-center justify-center">
+            <div className="grid w-full max-w-2xl grid-cols-12 gap-4">
+              {/* Row 1: Large Product Card - Available Soon */}
+              <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row">
+                <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
+                  <img
+                    alt="Cherries"
+                    className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
+                    loading="lazy"
+                    src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
+                  />
+                </div>
+                <div className="flex flex-1 flex-col gap-3">
+                  <Card.Header className="gap-1">
+                    <Card.Title className="pr-8">Become an ACME Creator!</Card.Title>
+                    <Card.Description>
+                      Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam.
+                    </Card.Description>
+                    <CloseButton aria-label="Close banner" className="absolute top-3 right-3" />
+                  </Card.Header>
+                  <Card.Footer className="mt-auto flex w-full items-center justify-between gap-3">
+                    <span className="text-sm font-medium text-foreground">Only 10 spots</span>
+                    <Button className="w-full sm:w-auto">Apply Now</Button>
+                  </Card.Footer>
+                </div>
+              </Card>
+
+              {/* Row 2 */}
+              <div className="col-span-12 grid grid-cols-12 gap-4">
+                {/* Left Column */}
+                <div className="col-span-12 grid grid-cols-12 gap-4">
+                  {/* Top Card */}
+                  <Card className="col-span-12">
+                    <div className="absolute top-3 right-3 z-10">
+                      <CloseButton aria-label="Close notification" />
+                    </div>
+                    <Card.Header className="gap-3">
+                      <Icon
+                        aria-label="Dollar sign icon"
+                        className="text-primary size-8 shrink-0"
+                        icon="gravity-ui:circle-dollar"
+                        role="img"
+                      />
+                      <div className="flex flex-col gap-1">
+                        <span className="text-xs font-medium text-muted uppercase">PAYMENT</span>
+                        <Card.Title className="pr-8 text-sm sm:text-base">
+                          You can now withdraw on crypto
+                        </Card.Title>
+                        <Card.Description className="text-xs sm:text-sm">
+                          Add your wallet in settings to withdraw
+                        </Card.Description>
+                      </div>
+                    </Card.Header>
+                    <Card.Footer>
+                      <Link aria-label="Go to settings" href="#" rel="noopener noreferrer">
+                        Go to settings
+                        <Link.Icon aria-hidden="true" />
+                      </Link>
+                    </Card.Footer>
+                  </Card>
+                  {/* Bottom cards */}
+                  <div className="col-span-12 grid grid-cols-12 gap-4">
+                    {/* Left Card */}
+                    <Card className="col-span-12 gap-2 sm:col-span-6">
+                      <Card.Header>
+                        <Avatar className="size-[56px] rounded-xl">
+                          <Avatar.Image
+                            alt="Demo 1"
+                            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+                          />
+                          <Avatar.Fallback>JK</Avatar.Fallback>
+                        </Avatar>
+                      </Card.Header>
+                      <Card.Content className="mt-1">
+                        <p className="text-sm leading-4 font-medium">Indie Hackers</p>
+                        <p className="text-xs text-muted">148 members</p>
+                      </Card.Content>
+                      <Card.Footer className="flex items-center gap-2">
+                        <Avatar className="size-4">
+                          <Avatar.Image
+                            alt="John"
+                            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+                          />
+                          <Avatar.Fallback>JK</Avatar.Fallback>
+                        </Avatar>
+                        <p className="text-xs text-muted">By John</p>
+                      </Card.Footer>
+                    </Card>
+                    {/* Right Card */}
+                    <Card className="col-span-12 gap-2 sm:col-span-6">
+                      <Card.Header>
+                        <Avatar className="size-[56px] rounded-xl">
+                          <Avatar.Image
+                            alt="Demo 2"
+                            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+                          />
+                          <Avatar.Fallback>AB</Avatar.Fallback>
+                        </Avatar>
+                      </Card.Header>
+                      <Card.Content className="mt-1">
+                        <p className="text-sm leading-4 font-medium">AI Builders</p>
+                        <p className="text-xs text-muted">362 members</p>
+                      </Card.Content>
+                      <Card.Footer className="flex items-center gap-2">
+                        <Avatar className="size-4">
+                          <Avatar.Image
+                            alt="John"
+                            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+                          />
+                          <Avatar.Fallback>M</Avatar.Fallback>
+                        </Avatar>
+                        <p className="text-xs text-muted">By Martha</p>
+                      </Card.Footer>
+                    </Card>
+                  </div>
+                </div>
+              </div>
+
+              {/* Row 3 */}
+              <div className="col-span-12 grid grid-cols-12 gap-4">
+                {/* Right Column: Cards Stack */}
+                <div className="col-span-12 flex flex-col gap-2 md:col-span-12 md:justify-between md:gap-2">
+                  {/* 1 */}
+                  <Card className="flex flex-row gap-3 p-1 shadow-none" variant="secondary">
+                    <img
+                      alt="Avocado"
+                      className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                      loading="lazy"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg"
+                    />
+                    <div className="flex flex-1 flex-col justify-center gap-1">
+                      <Card.Title className="text-sm">Avocado Hackathon</Card.Title>
+                      <Card.Description className="text-xs">Wed, 4:30 PM</Card.Description>
+                    </div>
+                  </Card>
+                  {/* 2 */}
+                  <Card className="flex flex-row gap-3 p-1 shadow-none" variant="tertiary">
+                    <img
+                      alt="Sound Electro event"
+                      className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
+                      loading="lazy"
+                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg"
+                    />
+                    <div className="flex flex-1 flex-col justify-center gap-1">
+                      <Card.Title className="text-sm">Sound Electro | Beyond art</Card.Title>
+                      <Card.Description className="text-xs">Fri, 8:00 PM</Card.Description>
+                    </div>
+                  </Card>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Tabs Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Tabs</h3>
+          <Tabs>
+            <Tabs.ListContainer>
+              <Tabs.List aria-label="Options">
+                <Tabs.Tab id="overview">
+                  Overview
+                  <Tabs.Indicator />
+                </Tabs.Tab>
+                <Tabs.Tab id="analytics">
+                  Analytics
+                  <Tabs.Indicator />
+                </Tabs.Tab>
+                <Tabs.Tab id="settings">
+                  Settings
+                  <Tabs.Indicator />
+                </Tabs.Tab>
+              </Tabs.List>
+            </Tabs.ListContainer>
+            <Tabs.Panel className="pt-2 text-sm text-muted" id="overview">
+              Overview content goes here.
+            </Tabs.Panel>
+            <Tabs.Panel className="pt-2 text-sm text-muted" id="analytics">
+              Analytics content goes here.
+            </Tabs.Panel>
+            <Tabs.Panel className="pt-2 text-sm text-muted" id="settings">
+              Settings content goes here.
+            </Tabs.Panel>
+          </Tabs>
+        </div>
+
+        {/* Controls Section */}
+        <div className="grid grid-cols-2 gap-4">
+          {/* Checkbox & Switch */}
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted">Controls</h3>
+
+            <Checkbox defaultSelected name="notifications">
+              <Checkbox.Content>
+                <Checkbox.Control>
+                  <Checkbox.Indicator />
+                </Checkbox.Control>
+                <Label className="text-sm">Enable notifications</Label>
+              </Checkbox.Content>
+            </Checkbox>
+
+            <Checkbox name="marketing">
+              <Checkbox.Content>
+                <Checkbox.Control>
+                  <Checkbox.Indicator />
+                </Checkbox.Control>
+                <Label className="text-sm">Marketing emails</Label>
+              </Checkbox.Content>
+            </Checkbox>
+
+            <Separator />
+
+            <Switch defaultSelected>
+              <Switch.Content>
+                <Switch.Control>
+                  <Switch.Thumb />
+                </Switch.Control>
+                <Label className="text-sm">Dark mode</Label>
+              </Switch.Content>
+            </Switch>
+
+            <Switch>
+              <Switch.Content>
+                <Switch.Control>
+                  <Switch.Thumb />
+                </Switch.Control>
+                <Label className="text-sm">Auto-save</Label>
+              </Switch.Content>
+            </Switch>
+          </div>
+
+          {/* Avatars & Spinners */}
+          <div className="flex flex-col gap-4">
+            <h3 className="text-sm font-semibold text-muted">Avatars</h3>
+            <div className="flex flex-wrap items-center gap-2">
+              <Avatar color="accent">
+                <Avatar.Fallback>AC</Avatar.Fallback>
+              </Avatar>
+              <Avatar color="success">
+                <Avatar.Fallback>SC</Avatar.Fallback>
+              </Avatar>
+              <Avatar color="warning">
+                <Avatar.Fallback>WR</Avatar.Fallback>
+              </Avatar>
+              <Avatar color="danger">
+                <Avatar.Fallback>DG</Avatar.Fallback>
+              </Avatar>
+              <Avatar>
+                <Avatar.Image
+                  alt="User"
+                  src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3"
+                />
+                <Avatar.Fallback>US</Avatar.Fallback>
+              </Avatar>
+            </div>
+
+            <h3 className="text-sm font-semibold text-muted">Spinners</h3>
+            <div className="flex items-center gap-4">
+              <Spinner color="accent" size="sm" />
+              <Spinner color="current" size="sm" />
+              <Spinner color="success" size="sm" />
+              <Spinner color="warning" size="sm" />
+              <Spinner color="danger" size="sm" />
+            </div>
+          </div>
+        </div>
+
+        {/* Slider Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Slider</h3>
+          <Slider defaultValue={60}>
+            <div className="flex items-center justify-between">
+              <Label className="text-sm">Volume</Label>
+              <Slider.Output className="text-sm text-muted" />
+            </div>
+            <Slider.Track>
+              <Slider.Fill />
+              <Slider.Thumb />
+            </Slider.Track>
+          </Slider>
+        </div>
+
+        {/* Radio Group Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Radio Group</h3>
+          <RadioGroup defaultValue="pro" name="plan" orientation="horizontal">
+            <Radio value="starter">
+              <Radio.Content>
+                <Radio.Control>
+                  <Radio.Indicator />
+                </Radio.Control>
+                <Label className="text-sm">Starter</Label>
+              </Radio.Content>
+            </Radio>
+            <Radio value="pro">
+              <Radio.Content>
+                <Radio.Control>
+                  <Radio.Indicator />
+                </Radio.Control>
+                <Label className="text-sm">Pro</Label>
+              </Radio.Content>
+            </Radio>
+            <Radio value="enterprise">
+              <Radio.Content>
+                <Radio.Control>
+                  <Radio.Indicator />
+                </Radio.Control>
+                <Label className="text-sm">Enterprise</Label>
+              </Radio.Content>
+            </Radio>
+          </RadioGroup>
+        </div>
+
+        {/* Alert Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Alerts</h3>
+          <div className="flex flex-col gap-2">
+            <Alert status="accent">
+              <Alert.Indicator />
+              <Alert.Content>
+                <Alert.Title>Update available</Alert.Title>
+              </Alert.Content>
+            </Alert>
+            <Alert status="success">
+              <Alert.Indicator />
+              <Alert.Content>
+                <Alert.Title>Payment successful</Alert.Title>
+              </Alert.Content>
+            </Alert>
+            <Alert status="warning">
+              <Alert.Indicator />
+              <Alert.Content>
+                <Alert.Title>Storage almost full</Alert.Title>
+              </Alert.Content>
+            </Alert>
+            <Alert status="danger">
+              <Alert.Indicator />
+              <Alert.Content>
+                <Alert.Title>Connection error</Alert.Title>
+              </Alert.Content>
+            </Alert>
+          </div>
+        </div>
+
+        {/* Links Section */}
+        <div className="flex flex-col gap-3">
+          <h3 className="text-sm font-semibold text-muted">Links</h3>
+          <div className="flex flex-wrap gap-4">
+            <Link href="#">
+              Learn more
+              <Link.Icon />
+            </Link>
+            <Link href="#">
+              Documentation
+              <Link.Icon />
+            </Link>
+            <Link href="#">
+              View source
+              <Link.Icon />
+            </Link>
+          </div>
+        </div>
+
+        {/* Input Example */}
+        <div className="flex flex-col gap-2">
+          <Label className="text-sm font-medium">Email</Label>
+          <Input fullWidth placeholder="Enter your email" type="email" />
+        </div>
+
+        {/* Select Example */}
+        <Select className="w-full" placeholder="Select an option">
+          <Label>Country</Label>
+          <Select.Trigger>
+            <Select.Value />
+            <Select.Indicator />
+          </Select.Trigger>
+          <Select.Popover>
+            <ListBox>
+              <ListBox.Item id="usa" textValue="United States">
+                United States
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="uk" textValue="United Kingdom">
+                United Kingdom
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="canada" textValue="Canada">
+                Canada
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+              <ListBox.Item id="germany" textValue="Germany">
+                Germany
+                <ListBox.ItemIndicator />
+              </ListBox.Item>
+            </ListBox>
+          </Select.Popover>
+        </Select>
+
+        {/* Dropdown Example */}
+        <Dropdown>
+          <Button aria-label="Menu" variant="secondary">
+            Actions
+          </Button>
+          <Dropdown.Popover>
+            <Dropdown.Menu onAction={() => {}}>
+              <Dropdown.Section>
+                <Header>File Actions</Header>
+                <Dropdown.Item id="new" textValue="New file">
+                  <Label>New file</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="copy" textValue="Copy">
+                  <Label>Copy</Label>
+                </Dropdown.Item>
+                <Dropdown.Item id="edit" textValue="Edit">
+                  <Label>Edit</Label>
+                </Dropdown.Item>
+              </Dropdown.Section>
+              <Separator />
+              <Dropdown.Section>
+                <Dropdown.Item id="delete" textValue="Delete" variant="danger">
+                  <Label>Delete</Label>
+                </Dropdown.Item>
+              </Dropdown.Section>
+            </Dropdown.Menu>
+          </Dropdown.Popover>
+        </Dropdown>
+
+        {/* Overlays Section */}
+        <div className="flex flex-col justify-center gap-4">
+          <h3 className="text-sm font-semibold text-muted">Overlays</h3>
+          <div className="flex flex-wrap gap-3">
+            {/* Modal */}
+            <Modal>
+              <Button size="sm" variant="secondary">
+                Open Modal
+              </Button>
+              <Modal.Backdrop>
+                <Modal.Container>
+                  <Modal.Dialog className="sm:max-w-[360px]">
+                    <Modal.CloseTrigger />
+                    <Modal.Header>
+                      <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                        <Icon className="size-5" icon="gravity-ui:rocket" />
+                      </Modal.Icon>
+                      <Modal.Heading>Welcome to HeroUI</Modal.Heading>
+                    </Modal.Header>
+                    <Modal.Body>
+                      <p className="text-sm text-muted">
+                        A beautiful, fast, and modern React UI library for building accessible and
+                        customizable web applications with ease.
+                      </p>
+                    </Modal.Body>
+                    <Modal.Footer>
+                      <Button className="w-full" slot="close">
+                        Continue
+                      </Button>
+                    </Modal.Footer>
+                  </Modal.Dialog>
+                </Modal.Container>
+              </Modal.Backdrop>
+            </Modal>
+
+            {/* Popover */}
+            <Popover>
+              <Button isIconOnly aria-label="Info" size="sm" variant="tertiary">
+                <Icon icon="gravity-ui:circle-info" />
+              </Button>
+              <Popover.Content>
+                <Popover.Dialog>
+                  <Popover.Arrow />
+                  <Popover.Heading>Popover Info</Popover.Heading>
+                  <p className="text-sm text-muted">This is a popover with helpful information.</p>
+                </Popover.Dialog>
+              </Popover.Content>
+            </Popover>
+
+            {/* Alert Dialog - Danger */}
+            <AlertDialog>
+              <Button size="sm" variant="danger">
+                Delete
+              </Button>
+              <AlertDialog.Backdrop>
+                <AlertDialog.Container>
+                  <AlertDialog.Dialog className="sm:max-w-[400px]">
+                    <AlertDialog.CloseTrigger />
+                    <AlertDialog.Header>
+                      <AlertDialog.Icon status="danger" />
+                      <AlertDialog.Heading>Delete item permanently?</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p className="text-sm text-muted">
+                        This action cannot be undone. All data will be permanently removed.
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer>
+                      <Button slot="close" variant="tertiary">
+                        Cancel
+                      </Button>
+                      <Button slot="close" variant="danger">
+                        Delete
+                      </Button>
+                    </AlertDialog.Footer>
+                  </AlertDialog.Dialog>
+                </AlertDialog.Container>
+              </AlertDialog.Backdrop>
+            </AlertDialog>
+          </div>
+
+          {/* Additional Alert Dialog variants */}
+          <div className="flex flex-wrap gap-3">
+            <AlertDialog>
+              <Button className="bg-success-soft text-success-soft-foreground" size="sm">
+                Confirm
+              </Button>
+              <AlertDialog.Backdrop>
+                <AlertDialog.Container>
+                  <AlertDialog.Dialog className="sm:max-w-[400px]">
+                    <AlertDialog.CloseTrigger />
+                    <AlertDialog.Header>
+                      <AlertDialog.Icon status="success" />
+                      <AlertDialog.Heading>Complete this task?</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p className="text-sm text-muted">
+                        This will mark the task as complete and notify all team members.
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer>
+                      <Button slot="close" variant="tertiary">
+                        Not Yet
+                      </Button>
+                      <Button slot="close">Mark Complete</Button>
+                    </AlertDialog.Footer>
+                  </AlertDialog.Dialog>
+                </AlertDialog.Container>
+              </AlertDialog.Backdrop>
+            </AlertDialog>
+
+            <AlertDialog>
+              <Button className="bg-warning-soft text-warning-soft-foreground" size="sm">
+                Discard
+              </Button>
+              <AlertDialog.Backdrop>
+                <AlertDialog.Container>
+                  <AlertDialog.Dialog className="sm:max-w-[400px]">
+                    <AlertDialog.CloseTrigger />
+                    <AlertDialog.Header>
+                      <AlertDialog.Icon status="warning" />
+                      <AlertDialog.Heading>Discard unsaved changes?</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p className="text-sm text-muted">
+                        You have unsaved changes that will be permanently lost.
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer>
+                      <Button slot="close" variant="tertiary">
+                        Keep Editing
+                      </Button>
+                      <Button slot="close">Discard</Button>
+                    </AlertDialog.Footer>
+                  </AlertDialog.Dialog>
+                </AlertDialog.Container>
+              </AlertDialog.Backdrop>
+            </AlertDialog>
+
+            {/* Popover with User Card */}
+            <Popover>
+              <Popover.Trigger aria-label="User info" className="flex items-center">
+                <div className="flex cursor-pointer items-center gap-2">
+                  <Avatar className="size-5" size="sm">
+                    <Avatar.Image
+                      alt="Zoe"
+                      src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
+                    />
+                    <Avatar.Fallback>Z</Avatar.Fallback>
+                  </Avatar>
+                  <span className="text-sm font-medium">Zoe</span>
+                </div>
+              </Popover.Trigger>
+              <Popover.Content className="w-[280px]">
+                <Popover.Dialog className="flex flex-col gap-3">
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-3">
+                      <Avatar size="md">
+                        <Avatar.Image
+                          alt="Zoe"
+                          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
+                        />
+                        <Avatar.Fallback>Z</Avatar.Fallback>
+                      </Avatar>
+                      <div className="flex flex-col">
+                        <span className="text-sm font-medium">Zoey Lang</span>
+                        <span className="text-xs text-muted">@zoe</span>
+                      </div>
+                    </div>
+                    <Button size="sm">Follow</Button>
+                  </div>
+                  <p className="text-sm text-muted">Design Engineer, @hero_ui lover 🎉</p>
+                  <div className="flex gap-3">
+                    <div className="flex gap-1">
+                      <span className="text-sm font-semibold">4</span>
+                      <span className="text-sm text-muted">Following</span>
+                    </div>
+                    <div className="flex gap-1">
+                      <span className="text-sm font-semibold">97.1K</span>
+                      <span className="text-sm text-muted">Followers</span>
+                    </div>
+                  </div>
+                </Popover.Dialog>
+              </Popover.Content>
+            </Popover>
+          </div>
+        </div>
+
+        {/* Modal Variations */}
+        <div className="flex flex-col gap-4">
+          <h3 className="text-sm font-semibold text-muted">Modal Variations</h3>
+          <div className="flex flex-wrap gap-3">
+            {/* Modal with Form */}
+            <Modal>
+              <Button size="sm" variant="secondary">
+                Contact Form
+              </Button>
+              <Modal.Backdrop>
+                <Modal.Container>
+                  <Modal.Dialog className="sm:max-w-md">
+                    <Modal.CloseTrigger />
+                    <Modal.Header>
+                      <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                        <Icon className="size-5" icon="gravity-ui:envelope" />
+                      </Modal.Icon>
+                      <Modal.Heading>Contact Us</Modal.Heading>
+                      <p className="text-sm text-muted">
+                        Fill out the form below and we'll get back to you.
+                      </p>
+                    </Modal.Header>
+                    <Modal.Body className="p-0.5">
+                      <Surface variant="default">
+                        <div className="flex flex-col gap-4">
+                          <div className="flex flex-col gap-1">
+                            <Label className="text-sm">Name</Label>
+                            <Input fullWidth placeholder="Enter your name" variant="secondary" />
+                          </div>
+                          <div className="flex flex-col gap-1">
+                            <Label className="text-sm">Email</Label>
+                            <Input
+                              fullWidth
+                              placeholder="Enter your email"
+                              type="email"
+                              variant="secondary"
+                            />
+                          </div>
+                        </div>
+                      </Surface>
+                    </Modal.Body>
+                    <Modal.Footer>
+                      <Button slot="close" variant="secondary">
+                        Cancel
+                      </Button>
+                      <Button slot="close">Send Message</Button>
+                    </Modal.Footer>
+                  </Modal.Dialog>
+                </Modal.Container>
+              </Modal.Backdrop>
+            </Modal>
+
+            {/* Modal with Custom Backdrop */}
+            <Modal>
+              <Button size="sm" variant="secondary">
+                Premium Modal
+              </Button>
+              <Modal.Backdrop
+                className="bg-linear-to-t from-accent-soft/80 via-accent-soft/40 to-transparent dark:from-accent-soft/80 dark:via-accent-soft/40"
+                variant="blur"
+              >
+                <Modal.Container>
+                  <Modal.Dialog className="sm:max-w-[360px]">
+                    <Modal.Header className="items-center text-center">
+                      <Modal.Icon className="bg-accent-soft text-accent-soft-foreground">
+                        <Icon className="size-5" icon="gravity-ui:sparkles" />
+                      </Modal.Icon>
+                      <Modal.Heading>Premium Feature</Modal.Heading>
+                    </Modal.Header>
+                    <Modal.Body>
+                      <p className="text-center text-sm text-muted">
+                        This modal features a sophisticated gradient backdrop with blur effect that
+                        adapts to light and dark modes.
+                      </p>
+                    </Modal.Body>
+                    <Modal.Footer className="flex-col-reverse">
+                      <Button className="w-full" slot="close">
+                        Amazing!
+                      </Button>
+                      <Button className="w-full" slot="close" variant="secondary">
+                        Close
+                      </Button>
+                    </Modal.Footer>
+                    <Modal.CloseTrigger />
+                  </Modal.Dialog>
+                </Modal.Container>
+              </Modal.Backdrop>
+            </Modal>
+
+            {/* Alert Dialog with Custom Backdrop */}
+            <AlertDialog>
+              <Button size="sm" variant="danger">
+                Delete Account
+              </Button>
+              <AlertDialog.Backdrop
+                className="bg-linear-to-t from-danger-soft/90 via-danger-soft/50 to-transparent dark:from-danger-soft/95 dark:via-danger-soft/60"
+                variant="blur"
+              >
+                <AlertDialog.Container>
+                  <AlertDialog.Dialog className="sm:max-w-[420px]">
+                    <AlertDialog.CloseTrigger />
+                    <AlertDialog.Header className="items-center text-center">
+                      <AlertDialog.Icon status="danger">
+                        <Icon className="size-5" icon="gravity-ui:triangle-exclamation" />
+                      </AlertDialog.Icon>
+                      <AlertDialog.Heading>Delete your account?</AlertDialog.Heading>
+                    </AlertDialog.Header>
+                    <AlertDialog.Body>
+                      <p className="text-center text-sm text-muted">
+                        This action cannot be undone. All your data will be permanently removed.
+                      </p>
+                    </AlertDialog.Body>
+                    <AlertDialog.Footer className="flex-col-reverse">
+                      <Button className="w-full" slot="close" variant="tertiary">
+                        Keep Account
+                      </Button>
+                      <Button className="w-full" slot="close" variant="danger">
+                        Delete Forever
+                      </Button>
+                    </AlertDialog.Footer>
+                  </AlertDialog.Dialog>
+                </AlertDialog.Container>
+              </AlertDialog.Backdrop>
+            </AlertDialog>
+          </div>
+        </div>
+      </main>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/components/colors-demo/index.ts b/packages/storybook/.storybook/components/colors-demo/index.ts
new file mode 100644
index 0000000..73ddea9
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/index.ts
@@ -0,0 +1,5 @@
+export {ColorsDemo} from "./colors-demo";
+export {ColorControls} from "./color-controls";
+export {ColorVariablesList} from "./color-variables-list";
+export {ComponentShowcase} from "./component-showcase";
+export {PreviewColumn} from "./preview-column";
diff --git a/packages/storybook/.storybook/components/colors-demo/preview-column.tsx b/packages/storybook/.storybook/components/colors-demo/preview-column.tsx
new file mode 100644
index 0000000..0825c7f
--- /dev/null
+++ b/packages/storybook/.storybook/components/colors-demo/preview-column.tsx
@@ -0,0 +1,67 @@
+import type {Theme} from "../../hooks/use-theme-toggle";
+
+import {Chip} from "@heroui/react";
+import React, {forwardRef, useEffect} from "react";
+
+import {ComponentShowcase} from "./component-showcase";
+
+interface PreviewColumnProps {
+  theme: Theme;
+  className?: string;
+}
+
+export const PreviewColumn = forwardRef<HTMLDivElement, PreviewColumnProps>(function PreviewColumn(
+  {className = "", theme},
+  ref,
+) {
+  useEffect(() => {
+    const element = ref && "current" in ref ? ref.current : null;
+
+    if (element) {
+      // Remove existing theme classes
+      element.classList.remove("light", "dark");
+      // Apply theme class and attribute
+      element.classList.add(theme);
+      element.setAttribute("data-theme", theme);
+    }
+  }, [theme, ref]);
+
+  return (
+    <div
+      ref={ref}
+      className={`flex flex-1 flex-col rounded-2xl border border-border bg-background text-foreground ${theme} ${className}`}
+      data-theme={theme}
+    >
+      {/* Header */}
+      <div className="shrink-0 p-2 pb-0">
+        <Chip className="capitalize" variant="soft">
+          <svg
+            fill="none"
+            height="12"
+            viewBox="0 0 12 12"
+            width="12"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <g clipPath="url(#clip0_17699_1194)">
+              <rect fill="currentColor" height="2.25" rx="1.125" width="2.25" x="4.875" y="4.875" />
+              <path
+                d="M8.48033 1.47949L9.99807 2.41887C10.5824 2.78056 10.9402 3.41695 10.9454 4.10418L10.96 6L10.9454 7.89582C10.9402 8.58305 10.5824 9.21944 9.99807 9.58113L8.48033 10.5205L7.02456 11.3889C6.3934 11.7653 5.6066 11.7653 4.97544 11.3889L3.51967 10.5205L2.00193 9.58113C1.41755 9.21944 1.05981 8.58305 1.05455 7.89582L1.04004 6L1.05455 4.10418C1.05981 3.41695 1.41755 2.78056 2.00193 2.41887L3.51967 1.47949L4.97545 0.611137C5.6066 0.234657 6.3934 0.234657 7.02456 0.611138L8.48033 1.47949ZM4.06181 2.44922L3.06635 3.06477C2.4814 3.42648 2.12333 4.06337 2.11826 4.7511L2.109 6.00879L2.1182 7.24858C2.1233 7.93609 2.48118 8.57278 3.06585 8.93452L4.05833 9.54858L4.97541 10.0955C5.60659 10.4719 6.39337 10.4719 7.02449 10.0953L7.94098 9.54858L8.93379 8.93432C9.51827 8.57269 9.87612 7.93626 9.88143 7.24897L9.891 6.00879L9.88136 4.7505C9.8761 4.0631 9.51817 3.42657 8.93356 3.06493L7.93849 2.4494C7.9383 2.44928 7.93807 2.44922 7.93784 2.44922C7.93761 2.44922 7.93739 2.44916 7.9372 2.44904L7.02489 1.90448C6.39357 1.52765 5.60639 1.52759 4.97501 1.90432L4.06181 2.44922Z"
+                fill="currentColor"
+              />
+            </g>
+            <defs>
+              <clipPath id="clip0_17699_1194">
+                <rect fill="white" height="12" width="12" />
+              </clipPath>
+            </defs>
+          </svg>
+          <Chip.Label>{theme}</Chip.Label>
+        </Chip>
+      </div>
+      {/* Scrollable Content */}
+      <div className="flex-1 overflow-y-auto">
+        <ComponentShowcase />
+      </div>
+    </div>
+  );
+});
diff --git a/packages/storybook/.storybook/components/docs-container.tsx b/packages/storybook/.storybook/components/docs-container.tsx
new file mode 100644
index 0000000..bb04f77
--- /dev/null
+++ b/packages/storybook/.storybook/components/docs-container.tsx
@@ -0,0 +1,64 @@
+import type {Preview} from "@storybook/react";
+
+import {DocsContainer as StorybookDocsContainer} from "@storybook/addon-docs/blocks";
+import React, {useEffect, useMemo, useState} from "react";
+import {addons} from "storybook/preview-api";
+
+import {
+  DEFAULT_THEME,
+  THEME_EVENT_NAME,
+  THEME_GLOBAL_TYPE_ID,
+  ensureThemeKey,
+} from "../addons/theme/constants";
+import {themes} from "../styles/theme";
+
+/**
+ * Custom DocsContainer that synchronizes the documentation theme
+ * with the global theme state selected in the toolbar.
+ */
+export const DocsContainer: NonNullable<Preview["parameters"]>["docs"]["container"] = ({
+  children,
+  context,
+}) => {
+  const initialTheme = useMemo(
+    () =>
+      ensureThemeKey((context?.globals?.[THEME_GLOBAL_TYPE_ID] as string | undefined) || undefined),
+    [context?.globals],
+  );
+
+  const [themeKey, setThemeKey] = useState<string>(initialTheme);
+
+  // Sync state when globals change (e.g. via toolbar)
+  useEffect(() => {
+    const next = ensureThemeKey(
+      (context?.globals?.[THEME_GLOBAL_TYPE_ID] as string | undefined) || undefined,
+    );
+
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- Guarded update to prevent unnecessary renders
+    setThemeKey((prev) => (prev === next ? prev : next));
+  }, [context?.globals]);
+
+  // Sync state when custom theme event fires (ensures immediate update)
+  useEffect(() => {
+    const channel = addons.getChannel();
+    const handleThemeChange = (event: {theme: string}) => {
+      const next = ensureThemeKey(event.theme);
+
+      setThemeKey((prev) => (prev === next ? prev : next));
+    };
+
+    channel.on(THEME_EVENT_NAME, handleThemeChange);
+
+    return () => {
+      channel.off(THEME_EVENT_NAME, handleThemeChange);
+    };
+  }, []);
+
+  const selectedTheme = themes[themeKey as keyof typeof themes] || themes[DEFAULT_THEME];
+
+  return (
+    <StorybookDocsContainer context={context} theme={selectedTheme}>
+      {children}
+    </StorybookDocsContainer>
+  );
+};
diff --git a/packages/storybook/.storybook/components/heroui-logo.tsx b/packages/storybook/.storybook/components/heroui-logo.tsx
new file mode 100644
index 0000000..92290db
--- /dev/null
+++ b/packages/storybook/.storybook/components/heroui-logo.tsx
@@ -0,0 +1,66 @@
+import React from "react";
+
+interface HeroUILogoProps {
+  className?: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+
+export function HeroUILogo({className, height, size = 26, width}: HeroUILogoProps) {
+  // Calculate dimensions based on original aspect ratio (140:44)
+  const aspectRatio = 140 / 44;
+  const svgHeight = height || size;
+  const svgWidth = width || Math.round(svgHeight * aspectRatio);
+
+  return (
+    <>
+      <svg
+        aria-hidden="true"
+        className={className}
+        fill="none"
+        height={svgHeight}
+        viewBox="0 0 140 44"
+        width={svgWidth}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M0.677734 11.3847V24.0405C0.677734 24.6387 0.985209 25.1946 1.49107 25.5109L10.1195 30.9067C11.2693 31.6257 12.7586 30.796 12.7586 29.4363V18.7981C12.7586 18.186 13.0803 17.6194 13.605 17.3074L18.8683 14.1785V41.4437C18.8683 42.7988 20.3486 43.6293 21.4988 42.9195L30.4044 37.4229C30.9152 37.1076 31.2264 36.549 31.2264 35.9471V9.76484C31.2264 8.41634 29.759 7.58483 28.6085 8.28139L18.8683 14.1785V2.55643C18.8683 1.21158 17.408 0.379537 16.2574 1.06878L1.51927 9.89703C0.997365 10.2097 0.677734 10.7747 0.677734 11.3847Z"
+          fill="currentColor"
+        />
+        <path
+          d="M63.8763 24.0707C63.8763 20.4817 62.4078 18.8253 59.4709 18.8253C56.1076 18.8253 53.7391 21.0799 53.7391 26.1412V37.7363H47.6756V5.52769H53.7391V17.3069C55.2075 14.9142 57.6234 13.7179 60.9394 13.7179C66.5764 13.7179 69.8924 17.1688 69.8924 22.9664V37.7363H63.8763V24.0707Z"
+          fill="currentColor"
+        />
+        <path
+          d="M84.8996 38.4725C77.3677 38.4725 72.5832 33.5952 72.5832 26.0952C72.5832 18.6872 77.3203 13.7179 84.8996 13.7179C93.0947 13.7179 97.5475 19.5154 96.3158 27.6596H78.6467C78.9783 31.5247 81.252 33.7333 84.8996 33.7333C87.8839 33.7333 89.684 32.2149 90.1577 30.6964H96.1737C95.2263 35.2057 91.0577 38.4725 84.8996 38.4725ZM78.7888 23.6566H90.4419C90.3945 20.4817 88.3102 18.3191 84.7574 18.3191C81.5836 18.3191 79.3572 20.1596 78.7888 23.6566Z"
+          fill="currentColor"
+        />
+        <path
+          d="M99.6225 20.3437C99.6225 16.5246 101.754 14.4541 105.828 14.4541H113.597V19.4234H105.686V37.7363H99.6225V20.3437Z"
+          fill="currentColor"
+        />
+        <path
+          d="M126.863 38.4725C119.189 38.4725 114.31 33.5492 114.31 26.0952C114.31 18.6412 119.189 13.7179 126.863 13.7179C134.442 13.7179 139.322 18.6412 139.322 26.0952C139.322 33.5492 134.442 38.4725 126.863 38.4725ZM126.863 33.4572C130.653 33.4572 133.163 30.5584 133.163 26.0952C133.163 21.632 130.653 18.6872 126.863 18.6872C123.026 18.6872 120.515 21.632 120.515 26.0952C120.515 30.5584 123.026 33.4572 126.863 33.4572Z"
+          fill="currentColor"
+        />
+      </svg>
+      <span
+        className="sr-only"
+        style={{
+          borderWidth: 0,
+          clip: "rect(0, 0, 0, 0)",
+          height: "1px",
+          margin: "-1px",
+          overflow: "hidden",
+          padding: "0",
+          position: "absolute",
+          whiteSpace: "nowrap",
+          width: "1px",
+        }}
+      >
+        HeroUI
+      </span>
+    </>
+  );
+}
diff --git a/packages/storybook/.storybook/globals.css b/packages/storybook/.storybook/globals.css
new file mode 100644
index 0000000..422d433
--- /dev/null
+++ b/packages/storybook/.storybook/globals.css
@@ -0,0 +1,32 @@
+@import "../styles/globals.css";
+
+:root {
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  --font-sans:
+    Inter, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+    "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+:root,
+.light,
+.default,
+[data-theme="light"],
+[data-theme="default"] {
+  --background: lab(96.5432% -0.0000596046 0);
+  --foreground: lab(8.34178% 0.607349 -2.12998);
+}
+
+html,
+body {
+  font-family: var(--font-sans);
+}
+
+.dark,
+[data-theme="dark"] {
+  --background: lab(1.54547% 0.178337 -0.64671);
+  --foreground: lab(98.9676% -0.0000298023 -0.0000119209);
+}
diff --git a/packages/storybook/.storybook/hooks/index.ts b/packages/storybook/.storybook/hooks/index.ts
new file mode 100644
index 0000000..beff8b1
--- /dev/null
+++ b/packages/storybook/.storybook/hooks/index.ts
@@ -0,0 +1,5 @@
+export {useColorVariables, groupVariablesByCategory} from "./use-color-variables";
+export type {ColorVariableValue} from "./use-color-variables";
+
+export {useThemeToggle, getSystemTheme} from "./use-theme-toggle";
+export type {Theme} from "./use-theme-toggle";
diff --git a/packages/storybook/.storybook/hooks/use-color-variables.ts b/packages/storybook/.storybook/hooks/use-color-variables.ts
new file mode 100644
index 0000000..58cb11a
--- /dev/null
+++ b/packages/storybook/.storybook/hooks/use-color-variables.ts
@@ -0,0 +1,172 @@
+import type {ColorVariable, OklchColor} from "../utils/oklch-utils";
+
+import {useCallback, useEffect, useState} from "react";
+
+import {COLOR_VARIABLES, formatOklch, parseOklch} from "../utils/oklch-utils";
+
+export interface ColorVariableValue {
+  name: string;
+  label: string;
+  category: string;
+  rawValue: string;
+  computedValue: string;
+  oklch: OklchColor | null;
+}
+
+/**
+ * Read a CSS custom property value from an element
+ */
+function getCssVariableValue(element: Element, variableName: string): string {
+  const computedStyle = getComputedStyle(element);
+
+  return computedStyle.getPropertyValue(variableName).trim();
+}
+
+/**
+ * Set a CSS custom property value on an element
+ */
+function setCssVariableValue(element: HTMLElement, variableName: string, value: string): void {
+  element.style.setProperty(variableName, value);
+}
+
+/**
+ * Hook to read and manage CSS color variables
+ */
+export function useColorVariables(containerRef?: React.RefObject<HTMLElement>) {
+  const [variables, setVariables] = useState<ColorVariableValue[]>([]);
+  const [baseHue, setBaseHue] = useState(360); // Default hue
+  const [grayChroma, setGrayChroma] = useState(0.114); // Default chroma amount for grays
+
+  /**
+   * Read all color variables from the target element
+   */
+  const readVariables = useCallback(() => {
+    const element = containerRef?.current || document.documentElement;
+
+    const values: ColorVariableValue[] = COLOR_VARIABLES.map((variable: ColorVariable) => {
+      const rawValue = getCssVariableValue(element, variable.name);
+      const computedValue = rawValue || "unset";
+      const oklch = parseOklch(computedValue);
+
+      return {
+        name: variable.name,
+        label: variable.label,
+        category: variable.category,
+        rawValue,
+        computedValue,
+        oklch,
+      };
+    });
+
+    setVariables(values);
+  }, [containerRef]);
+
+  /**
+   * Update a single CSS variable
+   */
+  const updateVariable = useCallback(
+    (variableName: string, value: string) => {
+      const element = containerRef?.current || document.documentElement;
+
+      setCssVariableValue(element, variableName, value);
+      readVariables();
+    },
+    [containerRef, readVariables],
+  );
+
+  /**
+   * Update multiple variables at once based on base hue and gray chroma
+   */
+  const updateColorScheme = useCallback(
+    (hue: number, chroma: number) => {
+      const element = containerRef?.current || document.documentElement;
+
+      // Update accent color with new hue
+      const accentOklch: OklchColor = {
+        l: 0.6204, // Default accent lightness
+        c: 0.195,
+        h: hue,
+      };
+
+      setCssVariableValue(element, "--accent", formatOklch(accentOklch));
+      setCssVariableValue(element, "--focus", formatOklch(accentOklch));
+
+      // Update gray-based colors with chroma adjustment
+      const grayColors = [
+        {name: "--background", l: 0.9702, baseC: 0},
+        {name: "--surface", l: 1, baseC: 0},
+        {name: "--muted", l: 0.5517, baseC: 0.0138},
+        {name: "--default", l: 0.94, baseC: 0.001},
+        {name: "--border", l: 0.9, baseC: 0.004},
+        {name: "--separator", l: 0.92, baseC: 0.004},
+      ];
+
+      grayColors.forEach(({baseC, l, name}) => {
+        const adjustedChroma = baseC * (chroma / 0.114); // Normalize to default chroma
+        const oklch: OklchColor = {
+          l,
+          c: adjustedChroma,
+          h: hue,
+        };
+
+        setCssVariableValue(element, name, formatOklch(oklch));
+      });
+
+      setBaseHue(hue);
+      setGrayChroma(chroma);
+      readVariables();
+    },
+    [containerRef, readVariables],
+  );
+
+  /**
+   * Reset all variables to their original values
+   */
+  const resetVariables = useCallback(() => {
+    const element = containerRef?.current || document.documentElement;
+
+    // Remove inline styles to fall back to CSS defaults
+    COLOR_VARIABLES.forEach((variable) => {
+      element.style.removeProperty(variable.name);
+    });
+
+    setBaseHue(360);
+    setGrayChroma(0.114);
+    readVariables();
+  }, [containerRef, readVariables]);
+
+  // Initial read
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    readVariables();
+  }, [readVariables]);
+
+  return {
+    variables,
+    baseHue,
+    grayChroma,
+    readVariables,
+    updateVariable,
+    updateColorScheme,
+    resetVariables,
+    setBaseHue,
+    setGrayChroma,
+  };
+}
+
+/**
+ * Get variables grouped by category
+ */
+export function groupVariablesByCategory(variables: ColorVariableValue[]) {
+  return variables.reduce(
+    (acc, variable) => {
+      if (!acc[variable.category]) {
+        acc[variable.category] = [];
+      }
+      acc[variable.category].push(variable);
+
+      return acc;
+    },
+    {} as Record<string, ColorVariableValue[]>,
+  );
+}
diff --git a/packages/storybook/.storybook/hooks/use-theme-toggle.ts b/packages/storybook/.storybook/hooks/use-theme-toggle.ts
new file mode 100644
index 0000000..3e7e124
--- /dev/null
+++ b/packages/storybook/.storybook/hooks/use-theme-toggle.ts
@@ -0,0 +1,64 @@
+import {useCallback, useEffect, useState} from "react";
+
+export type Theme = "light" | "dark";
+
+/**
+ * Hook to manage theme switching for a specific container
+ */
+export function useThemeToggle(containerRef?: React.RefObject<HTMLElement>) {
+  const [theme, setTheme] = useState<Theme>("light");
+
+  /**
+   * Apply theme to the container element
+   */
+  const applyTheme = useCallback(
+    (newTheme: Theme) => {
+      const element = containerRef?.current;
+
+      if (element) {
+        // Remove existing theme classes/attributes
+        element.classList.remove("light", "dark");
+        element.removeAttribute("data-theme");
+
+        // Apply new theme
+        element.classList.add(newTheme);
+        element.setAttribute("data-theme", newTheme);
+      }
+
+      setTheme(newTheme);
+    },
+    [containerRef],
+  );
+
+  /**
+   * Toggle between light and dark themes
+   */
+  const toggleTheme = useCallback(() => {
+    const newTheme = theme === "light" ? "dark" : "light";
+
+    applyTheme(newTheme);
+  }, [theme, applyTheme]);
+
+  /**
+   * Initialize theme on mount
+   */
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    applyTheme(theme);
+  }, [applyTheme, theme]);
+
+  return {
+    theme,
+    setTheme: applyTheme,
+    toggleTheme,
+  };
+}
+
+/**
+ * Get system preferred color scheme
+ */
+export function getSystemTheme(): Theme {
+  if (typeof window === "undefined") return "light";
+
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
diff --git a/packages/storybook/.storybook/main.ts b/packages/storybook/.storybook/main.ts
new file mode 100644
index 0000000..fb43123
--- /dev/null
+++ b/packages/storybook/.storybook/main.ts
@@ -0,0 +1,50 @@
+import type {StorybookConfig} from "@storybook/react-vite";
+
+import {readFileSync as fsReadFileSync} from "fs";
+import {dirname, join as pathJoin} from "path";
+import {fileURLToPath} from "url";
+
+import {sync as globSync} from "glob";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const getStories = () => {
+  const __STORYBOOK_READY_ONLY__ = process.env.STORYBOOK_READY_ONLY === "true";
+
+  if (!__STORYBOOK_READY_ONLY__)
+    return [pathJoin(__dirname, "../../react/src/**/*.stories.@(ts|tsx)")];
+
+  const readyStories = globSync(
+    pathJoin(__dirname, "../../react/src/**/*.stories.@(ts|tsx)"),
+  ).filter((file) => {
+    const content = fsReadFileSync(file, "utf-8");
+
+    return /title:\s*["']Components/.test(content);
+  });
+
+  return readyStories;
+};
+
+const config: StorybookConfig = {
+  addons: ["@storybook/addon-a11y", "@storybook/addon-docs"],
+  core: {
+    disableTelemetry: true,
+    disableWhatsNewNotifications: true,
+    enableCrashReports: false,
+  },
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+  staticDirs: [pathJoin(__dirname, "../public")],
+  stories: [
+    "./welcome.mdx",
+    "./stories/colors.stories.tsx",
+    "./stories/colors-demo.stories.tsx",
+    "./stories/demo.stories.tsx",
+    ...getStories(),
+  ],
+};
+
+export default config;
diff --git a/packages/storybook/.storybook/manager.ts b/packages/storybook/.storybook/manager.ts
new file mode 100644
index 0000000..210ee35
--- /dev/null
+++ b/packages/storybook/.storybook/manager.ts
@@ -0,0 +1 @@
+import "./addons/theme/manager";
diff --git a/packages/storybook/.storybook/preview-head.html b/packages/storybook/.storybook/preview-head.html
new file mode 100644
index 0000000..002adf4
--- /dev/null
+++ b/packages/storybook/.storybook/preview-head.html
@@ -0,0 +1,17 @@
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap"
+  rel="stylesheet"
+/>
+
+<style>
+  html,
+  body,
+  #storybook-root {
+    height: 100%;
+    font-family:
+      Inter, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+      "Segoe UI Symbol", "Noto Color Emoji";
+  }
+</style>
diff --git a/packages/storybook/.storybook/preview.tsx b/packages/storybook/.storybook/preview.tsx
new file mode 100644
index 0000000..bf0f249
--- /dev/null
+++ b/packages/storybook/.storybook/preview.tsx
@@ -0,0 +1,59 @@
+import type {Preview} from "@storybook/react";
+
+import {withInternationalization} from "./addons/i18n/decorator";
+import {i18nGlobalType} from "./addons/i18n/preview";
+import {withReactScan} from "./addons/react-scan/decorator";
+import {reactScanGlobalType} from "./addons/react-scan/preview";
+import {withReduceMotion} from "./addons/reduce-motion/decorator";
+import {reduceMotionGlobalType} from "./addons/reduce-motion/preview";
+import {withReactStrictMode} from "./addons/strict-mode/decorator";
+import {strictModeGlobalType} from "./addons/strict-mode/preview";
+import {withTheme} from "./addons/theme/decorator";
+import {themeGlobalType} from "./addons/theme/preview";
+import {DocsContainer} from "./components/docs-container";
+
+import "./globals.css";
+
+const parameters: Preview["parameters"] = {
+  layout: "fullscreen",
+  controls: {
+    matchers: {
+      color: /(background|color)$/i,
+      date: /Date$/,
+    },
+  },
+  options: {
+    storySort: {
+      method: "alphabetical",
+      order: ["Welcome", "Color System", "Components Demo", "Colors Demo"],
+    },
+  },
+  docs: {
+    container: DocsContainer,
+  },
+};
+
+const decorators: Preview["decorators"] = [
+  withReactStrictMode,
+  withTheme,
+  withInternationalization,
+  withReduceMotion,
+  withReactScan,
+];
+
+const globalTypes = {
+  ...i18nGlobalType,
+  ...themeGlobalType,
+  ...reduceMotionGlobalType,
+  ...strictModeGlobalType,
+  ...reactScanGlobalType,
+};
+
+const preview: Preview = {
+  decorators,
+  parameters,
+  globalTypes,
+  tags: ["autodocs"],
+};
+
+export default preview;
diff --git a/packages/storybook/.storybook/stories/colors-demo.stories.tsx b/packages/storybook/.storybook/stories/colors-demo.stories.tsx
new file mode 100644
index 0000000..006c08c
--- /dev/null
+++ b/packages/storybook/.storybook/stories/colors-demo.stories.tsx
@@ -0,0 +1,27 @@
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {ColorsDemo} from "../components/colors-demo";
+
+const meta: Meta = {
+  title: "Colors Demo",
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+
+export const Default = () => {
+  return <ColorsDemo />;
+};
+
+Default.parameters = {
+  docs: {
+    description: {
+      story:
+        "An interactive color palette generator showcasing HeroUI's color system. Adjust the base tone and gray chroma to see how colors change across light and dark themes.",
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/stories/colors.stories.tsx b/packages/storybook/.storybook/stories/colors.stories.tsx
new file mode 100644
index 0000000..c34bec0
--- /dev/null
+++ b/packages/storybook/.storybook/stories/colors.stories.tsx
@@ -0,0 +1,231 @@
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+const meta: Meta = {
+  title: "Color System",
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+
+interface ColorItemProps {
+  name: string;
+  variable: string;
+  cssVariable?: string;
+}
+
+const ColorItem = ({cssVariable, name, variable}: ColorItemProps) => {
+  const computedColor =
+    typeof window !== "undefined"
+      ? getComputedStyle(document.documentElement)
+          .getPropertyValue(cssVariable || variable)
+          .trim()
+      : "";
+
+  return (
+    <div className="flex items-center gap-4 rounded-3xl bg-surface p-4 shadow-surface">
+      <div
+        className="size-12 shrink-0 rounded-xl border border-border"
+        style={{backgroundColor: `var(${variable})`}}
+      />
+      <div className="flex flex-1 flex-col gap-1">
+        <span className="text-sm font-medium text-foreground">{name}</span>
+        <code className="text-xs text-muted">{variable}</code>
+      </div>
+      {!!computedColor && (
+        <div className="text-right">
+          <code className="font-mono text-xs text-muted">{computedColor}</code>
+        </div>
+      )}
+    </div>
+  );
+};
+
+interface ColorSectionProps {
+  title: string;
+  colors: ColorItemProps[];
+}
+
+const ColorSection = ({colors, title}: ColorSectionProps) => {
+  return (
+    <div className="mb-8">
+      <h3 className="mb-4 text-lg font-semibold text-foreground">{title}</h3>
+      <div className="grid gap-3">
+        {colors.map((color) => (
+          <ColorItem key={color.variable} {...color} />
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export const AllColors = () => {
+  const baseColors: ColorItemProps[] = [
+    {name: "Background", variable: "--color-background"},
+    {name: "Foreground", variable: "--color-foreground"},
+    {name: "Surface", variable: "--color-surface"},
+    {name: "Surface Foreground", variable: "--color-surface-foreground"},
+    {name: "Surface Hover", variable: "--color-surface-hover"},
+    {name: "Overlay", variable: "--color-overlay"},
+    {name: "Overlay Foreground", variable: "--color-overlay-foreground"},
+  ];
+
+  const brandColors: ColorItemProps[] = [
+    {name: "Accent", variable: "--color-accent"},
+    {name: "Accent Foreground", variable: "--color-accent-foreground"},
+  ];
+
+  const semanticColors: ColorItemProps[] = [
+    {name: "Default", variable: "--color-default"},
+    {name: "Default Foreground", variable: "--color-default-foreground"},
+    {name: "Success", variable: "--color-success"},
+    {name: "Success Foreground", variable: "--color-success-foreground"},
+    {name: "Warning", variable: "--color-warning"},
+    {name: "Warning Foreground", variable: "--color-warning-foreground"},
+    {name: "Danger", variable: "--color-danger"},
+    {name: "Danger Foreground", variable: "--color-danger-foreground"},
+  ];
+
+  const componentColors: ColorItemProps[] = [
+    {name: "Muted", variable: "--color-muted"},
+    {name: "Border", variable: "--color-border"},
+    {name: "Separator", variable: "--color-separator"},
+    {name: "Focus", variable: "--color-focus"},
+    {name: "Link", variable: "--color-link"},
+    {name: "Segment", variable: "--color-segment"},
+    {name: "Segment Foreground", variable: "--color-segment-foreground"},
+  ];
+
+  const formFieldColors: ColorItemProps[] = [
+    {name: "Field Background", variable: "--color-field"},
+    {name: "Field Foreground", variable: "--color-field-foreground"},
+    {name: "Field Placeholder", variable: "--color-field-placeholder"},
+    {name: "Field Border", variable: "--color-field-border"},
+  ];
+
+  const primitiveColors: ColorItemProps[] = [
+    {name: "White", variable: "--white"},
+    {name: "Black", variable: "--black"},
+    {name: "Snow", variable: "--snow"},
+    {name: "Eclipse", variable: "--eclipse"},
+  ];
+
+  const calculatedBackgroundColors: ColorItemProps[] = [
+    {name: "Background Secondary", variable: "--color-background-secondary"},
+    {name: "Background Tertiary", variable: "--color-background-tertiary"},
+    {name: "Background Inverse", variable: "--color-background-inverse"},
+  ];
+
+  const calculatedHoverColors: ColorItemProps[] = [
+    {name: "Default Hover", variable: "--color-default-hover"},
+    {name: "Accent Hover", variable: "--color-accent-hover"},
+    {name: "Success Hover", variable: "--color-success-hover"},
+    {name: "Warning Hover", variable: "--color-warning-hover"},
+    {name: "Danger Hover", variable: "--color-danger-hover"},
+  ];
+
+  const calculatedSoftColors: ColorItemProps[] = [
+    {name: "Accent Soft", variable: "--color-accent-soft"},
+    {name: "Accent Soft Foreground", variable: "--color-accent-soft-foreground"},
+    {name: "Accent Soft Hover", variable: "--color-accent-soft-hover"},
+    {name: "Danger Soft", variable: "--color-danger-soft"},
+    {name: "Danger Soft Foreground", variable: "--color-danger-soft-foreground"},
+    {name: "Danger Soft Hover", variable: "--color-danger-soft-hover"},
+    {name: "Warning Soft", variable: "--color-warning-soft"},
+    {name: "Warning Soft Foreground", variable: "--color-warning-soft-foreground"},
+    {name: "Warning Soft Hover", variable: "--color-warning-soft-hover"},
+    {name: "Success Soft", variable: "--color-success-soft"},
+    {name: "Success Soft Foreground", variable: "--color-success-soft-foreground"},
+    {name: "Success Soft Hover", variable: "--color-success-soft-hover"},
+  ];
+
+  const calculatedSurfaceColors: ColorItemProps[] = [
+    {name: "Surface", variable: "--color-surface"},
+    {name: "Surface Secondary", variable: "--color-surface-secondary"},
+    {name: "Surface Tertiary", variable: "--color-surface-tertiary"},
+  ];
+
+  const calculatedFieldColors: ColorItemProps[] = [
+    {name: "Field Hover", variable: "--color-field-hover"},
+    {name: "Field Focus", variable: "--color-field-focus"},
+    {name: "Field Border Hover", variable: "--color-field-border-hover"},
+    {name: "Field Border Focus", variable: "--color-field-border-focus"},
+  ];
+
+  const calculatedInSurfaceColors: ColorItemProps[] = [
+    {name: "On Surface", variable: "--color-on-surface"},
+    {name: "On Surface Foreground", variable: "--color-on-surface-foreground"},
+    {name: "On Surface Hover", variable: "--color-on-surface-hover"},
+    {name: "On Surface Focus", variable: "--color-on-surface-focus"},
+  ];
+
+  const calculatedInSurfaceSecondaryColors: ColorItemProps[] = [
+    {name: "On Surface Secondary", variable: "--color-on-surface-secondary"},
+    {name: "On Surface Secondary Foreground", variable: "--color-on-surface-secondary-foreground"},
+    {name: "On Surface Secondary Hover", variable: "--color-on-surface-secondary-hover"},
+    {name: "On Surface Secondary Focus", variable: "--color-on-surface-secondary-focus"},
+  ];
+
+  const calculatedInSurfaceTertiaryColors: ColorItemProps[] = [
+    {name: "On Surface Tertiary", variable: "--color-on-surface-tertiary"},
+    {name: "On Surface Tertiary Foreground", variable: "--color-on-surface-tertiary-foreground"},
+    {name: "On Surface Tertiary Hover", variable: "--color-on-surface-tertiary-hover"},
+    {name: "On Surface Tertiary Focus", variable: "--color-on-surface-tertiary-focus"},
+  ];
+
+  const calculatedSeparatorColors: ColorItemProps[] = [
+    {name: "Separator", variable: "--color-separator"},
+    {name: "Separator Secondary", variable: "--color-separator-secondary"},
+    {name: "Separator Tertiary", variable: "--color-separator-tertiary"},
+  ];
+
+  return (
+    <div className="mx-auto max-w-4xl p-6">
+      <div className="mb-8">
+        <h1 className="mb-2 text-3xl font-bold text-foreground">Color System</h1>
+        <p className="text-muted">HeroUI's color palette with CSS variables and computed values</p>
+      </div>
+
+      <ColorSection colors={baseColors} title="Base Colors" />
+      <ColorSection colors={brandColors} title="Brand Colors" />
+      <ColorSection colors={semanticColors} title="Semantic Colors" />
+      <ColorSection colors={componentColors} title="Component Colors" />
+      <ColorSection colors={formFieldColors} title="Form Field Colors" />
+      <ColorSection colors={primitiveColors} title="Primitive Colors" />
+
+      <div className="mb-8">
+        <h2 className="mb-4 text-2xl font-bold text-foreground">Calculated Colors</h2>
+        <p className="mb-6 text-sm text-muted">
+          These colors are dynamically calculated using color-mix() from base colors
+        </p>
+        <ColorSection colors={calculatedBackgroundColors} title="Background Shades" />
+        <ColorSection colors={calculatedHoverColors} title="Hover States" />
+        <ColorSection colors={calculatedSoftColors} title="Soft Variants" />
+        <ColorSection colors={calculatedSurfaceColors} title="Surface Levels" />
+        <ColorSection colors={calculatedInSurfaceColors} title="On Surface Colors" />
+        <ColorSection
+          colors={calculatedInSurfaceSecondaryColors}
+          title="On Surface Colors - Secondary"
+        />
+        <ColorSection
+          colors={calculatedInSurfaceTertiaryColors}
+          title="On Surface Colors - Tertiary"
+        />
+        <ColorSection colors={calculatedSeparatorColors} title="Separator Colors" />
+        <ColorSection colors={calculatedFieldColors} title="Field States" />
+      </div>
+    </div>
+  );
+};
+
+AllColors.parameters = {
+  docs: {
+    description: {
+      story:
+        "A comprehensive overview of all color tokens available in the HeroUI design system. Each color shows its CSS variable name and computed value.",
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/stories/demo.stories.tsx b/packages/storybook/.storybook/stories/demo.stories.tsx
new file mode 100644
index 0000000..83c23ee
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demo.stories.tsx
@@ -0,0 +1,27 @@
+import type {Meta} from "@storybook/react";
+
+import React from "react";
+
+import {DemoComponents} from "./demos";
+
+const meta: Meta = {
+  title: "Components Demo",
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+
+export const Components = () => {
+  return <DemoComponents />;
+};
+
+Components.parameters = {
+  docs: {
+    description: {
+      story:
+        "A comprehensive showcase of HeroUI components in action. These demos demonstrate real-world usage patterns and component combinations.",
+    },
+  },
+};
diff --git a/packages/storybook/.storybook/stories/demos/alert-demo.tsx b/packages/storybook/.storybook/stories/demos/alert-demo.tsx
new file mode 100644
index 0000000..59363f4
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/alert-demo.tsx
@@ -0,0 +1,15 @@
+import {Alert, Button} from "@heroui/react";
+import React from "react";
+
+export function AlertDemo() {
+  return (
+    <Alert className="w-[400px] items-center">
+      <Alert.Indicator />
+      <Alert.Content>
+        <Alert.Title>You have 2 credits left</Alert.Title>
+        <Alert.Description>Get a paid plan for more credits</Alert.Description>
+      </Alert.Content>
+      <Button variant="tertiary">Upgrade</Button>
+    </Alert>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/alert-dialog-demo.tsx b/packages/storybook/.storybook/stories/demos/alert-dialog-demo.tsx
new file mode 100644
index 0000000..2a5ee65
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/alert-dialog-demo.tsx
@@ -0,0 +1,26 @@
+import {FloppyDisk} from "@gravity-ui/icons";
+import {Avatar, Button, Card, CloseButton} from "@heroui/react";
+import React from "react";
+
+export function AlertDialogDemo() {
+  return (
+    <Card className="h-[208px] w-[340px] items-start justify-center p-5">
+      <Card.Header className="flex w-full items-start justify-center gap-2 px-1">
+        <Avatar color="warning" variant="soft">
+          <Avatar.Fallback>
+            <FloppyDisk className="text-lg" />
+          </Avatar.Fallback>
+        </Avatar>
+        <Card.Title>Unsaved changes</Card.Title>
+        <Card.Description>Do you want to save or discard changes?</Card.Description>
+        <CloseButton className="absolute top-3 right-3" />
+      </Card.Header>
+      <Card.Footer className="flex w-full items-center gap-2 px-0.5 pt-3">
+        <Button className="w-full" variant="tertiary">
+          Discard
+        </Button>
+        <Button className="w-full">Save changes</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/allow-notifications-demo.tsx b/packages/storybook/.storybook/stories/demos/allow-notifications-demo.tsx
new file mode 100644
index 0000000..9bab055
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/allow-notifications-demo.tsx
@@ -0,0 +1,20 @@
+import {Description, Label, Switch} from "@heroui/react";
+import React from "react";
+
+export function AllowNotificationsDemo() {
+  return (
+    <div className="flex w-full justify-center">
+      <Switch defaultSelected>
+        <div className="flex gap-8 p-4">
+          <div className="-mt-0.5 flex flex-col justify-start gap-1">
+            <Label className="w-fit text-sm font-medium">Allow notifications</Label>
+            <Description>Receive push notifications from HeroUI</Description>
+          </div>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </div>
+      </Switch>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/avatar-group-demo.tsx b/packages/storybook/.storybook/stories/demos/avatar-group-demo.tsx
new file mode 100644
index 0000000..91aad02
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/avatar-group-demo.tsx
@@ -0,0 +1,58 @@
+import {Avatar} from "@heroui/react";
+import React from "react";
+
+const avatars = [
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Blue",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
+    name: "Green",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
+    name: "Purple",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
+    name: "Orange",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
+    name: "red",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
+    name: "Blue",
+  },
+  {
+    image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
+    name: "Black",
+  },
+];
+
+export function AvatarGroupDemo() {
+  return (
+    <div className="flex w-full justify-center">
+      <div className="flex -space-x-2">
+        {avatars.slice(0, 5).map((item, index) => (
+          <Avatar key={`${item.name}-${index}`} className="ring-2 ring-background">
+            <Avatar.Image alt={item.name} src={item.image} />
+            <Avatar.Fallback>
+              {item.name
+                .split(" ")
+                .map((n) => n[0])
+                .join("")}
+            </Avatar.Fallback>
+          </Avatar>
+        ))}
+        <Avatar className="ring-2 ring-background">
+          <Avatar.Fallback className="bg-surface text-xs font-medium text-muted">
+            +{avatars.length - 2}
+          </Avatar.Fallback>
+        </Avatar>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/buttons-demo.tsx b/packages/storybook/.storybook/stories/demos/buttons-demo.tsx
new file mode 100644
index 0000000..702e661
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/buttons-demo.tsx
@@ -0,0 +1,25 @@
+import {Button} from "@heroui/react";
+import React from "react";
+
+export const ButtonsDemo = () => {
+  return (
+    <div className="grid grid-cols-3 gap-2">
+      <Button size="sm">Call to action</Button>
+      <Button size="sm" variant="secondary">
+        Call to action
+      </Button>
+      <Button size="sm" variant="tertiary">
+        Call to action
+      </Button>
+      <Button size="sm" variant="danger">
+        Call to action
+      </Button>
+      <Button size="sm" variant="danger-soft">
+        Call to action
+      </Button>
+      <Button size="sm" variant="ghost">
+        Call to action
+      </Button>
+    </div>
+  );
+};
diff --git a/packages/storybook/.storybook/stories/demos/components/icons.tsx b/packages/storybook/.storybook/stories/demos/components/icons.tsx
new file mode 100644
index 0000000..4485b72
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/components/icons.tsx
@@ -0,0 +1,264 @@
+import type {Ref, SVGProps} from "react";
+
+import React, {forwardRef, memo, useId} from "react";
+import {cn} from "tailwind-variants";
+
+const AppleIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-foreground", className)}
+      fill="none"
+      focusable="false"
+      height={16}
+      role="presentation"
+      viewBox="0 0 16 16"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M11.367 13.52c-.654.633-1.367.533-2.054.233-.726-.306-1.393-.32-2.16 0-.96.414-1.466.294-2.04-.233-3.253-3.353-2.773-8.46.92-8.647.9.047 1.527.494 2.054.534.786-.16 1.54-.62 2.38-.56 1.006.08 1.766.48 2.266 1.2-2.08 1.246-1.586 3.986.32 4.753-.38 1-.873 1.993-1.693 2.727l.007-.007ZM8.02 4.833C7.92 3.347 9.127 2.12 10.513 2c.194 1.72-1.56 3-2.493 2.833Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export const AppleIcon = memo(forwardRef(AppleIconRender));
+
+const GoogleIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn(className)}
+      fill="none"
+      focusable="false"
+      height={16}
+      role="presentation"
+      viewBox="0 0 16 16"
+      width={16}
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M5.877 1.46a6.921 6.921 0 0 0 .474 13.224c1.159.3 2.373.312 3.539.038a6.248 6.248 0 0 0 2.833-1.472 6.28 6.28 0 0 0 1.75-2.872 8.125 8.125 0 0 0 .176-3.673h-6.51v2.7h3.77a3.25 3.25 0 0 1-1.385 2.136c-.46.304-.98.509-1.523.601a4.517 4.517 0 0 1-1.652 0 4.068 4.068 0 0 1-1.537-.67 4.299 4.299 0 0 1-1.586-2.124 4.189 4.189 0 0 1 0-2.694c.208-.613.551-1.17 1.005-1.631a4.066 4.066 0 0 1 4.096-1.07c.558.172 1.07.471 1.492.875.425-.423.849-.847 1.273-1.272.218-.228.457-.446.672-.68a6.693 6.693 0 0 0-2.227-1.374 7 7 0 0 0-4.66-.042Z"
+        fill="#fff"
+      />
+      <path
+        d="M5.877 1.46a7 7 0 0 1 4.66.04c.826.31 1.582.78 2.226 1.381-.219.234-.45.453-.672.68l-1.272 1.267a3.752 3.752 0 0 0-1.492-.875 4.066 4.066 0 0 0-4.098 1.065A4.293 4.293 0 0 0 4.225 6.65L1.958 4.894A6.949 6.949 0 0 1 5.877 1.46Z"
+        fill="#E33629"
+      />
+      <path
+        d="M1.356 6.633a6.89 6.89 0 0 1 .602-1.74l2.267 1.76a4.19 4.19 0 0 0 0 2.694c-.755.584-1.511 1.17-2.267 1.76a6.927 6.927 0 0 1-.602-4.474Z"
+        fill="#F8BD00"
+      />
+      <path
+        d="M8.139 6.704h6.51a8.127 8.127 0 0 1-.176 3.673 6.283 6.283 0 0 1-1.75 2.872c-.732-.571-1.467-1.138-2.199-1.709a3.25 3.25 0 0 0 1.385-2.137h-3.77v-2.7Z"
+        fill="#587DBD"
+      />
+      <path
+        d="M1.957 11.106a539.69 539.69 0 0 0 2.267-1.759 4.298 4.298 0 0 0 1.588 2.125c.462.326.987.552 1.54.665a4.517 4.517 0 0 0 1.652 0 3.96 3.96 0 0 0 1.524-.602c.731.57 1.466 1.137 2.198 1.708a6.25 6.25 0 0 1-2.833 1.474 7.394 7.394 0 0 1-3.54-.039 6.967 6.967 0 0 1-4.397-3.572Z"
+        fill="#319F43"
+      />
+    </svg>
+  );
+};
+
+export const GoogleIcon = memo(forwardRef(GoogleIconRender));
+
+const VerifiedBadgeIconRender = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => {
+  const {className, ...restProps} = props;
+
+  const uid = useId();
+  const filterId = `verified-badge-filter-${uid}`;
+  const gradientId = `verified-badge-gradient-${uid}`;
+
+  return (
+    <svg
+      ref={ref}
+      aria-hidden="true"
+      className={cn("text-2xl", className)}
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      xmlns="http://www.w3.org/2000/svg"
+      {...restProps}
+    >
+      <path
+        d="M13.9844 3.40625L14.2471 3.65625L14.6055 3.60645L18.0098 3.13281L18.5977 6.48145L18.6611 6.84375L18.9873 7.01562L22.0059 8.60156L20.4941 11.6963L20.332 12.0283L20.4961 12.3594L22.002 15.3994L18.9873 16.9844L18.6611 17.1562L18.5977 17.5186L18.0098 20.8662L14.6055 20.3936L14.2471 20.3438L13.9844 20.5938L11.5 22.9629L9.01562 20.5938L8.75293 20.3438L8.39453 20.3936L4.98926 20.8662L4.40234 17.5186L4.33887 17.1562L4.0127 16.9844L0.99707 15.3994L2.50391 12.3594L2.66797 12.0283L2.50586 11.6963L0.993164 8.60156L4.0127 7.01562L4.33887 6.84375L4.40234 6.48145L4.98926 3.13281L8.39453 3.60645L8.75293 3.65625L9.01562 3.40625L11.5 1.03613L13.9844 3.40625Z"
+        fill={`url(#${gradientId})`}
+      />
+      <path
+        d="M13.9844 3.40625L14.2471 3.65625L14.6055 3.60645L18.0098 3.13281L18.5977 6.48145L18.6611 6.84375L18.9873 7.01562L22.0059 8.60156L20.4941 11.6963L20.332 12.0283L20.4961 12.3594L22.002 15.3994L18.9873 16.9844L18.6611 17.1562L18.5977 17.5186L18.0098 20.8662L14.6055 20.3936L14.2471 20.3438L13.9844 20.5938L11.5 22.9629L9.01562 20.5938L8.75293 20.3438L8.39453 20.3936L4.98926 20.8662L4.40234 17.5186L4.33887 17.1562L4.0127 16.9844L0.99707 15.3994L2.50391 12.3594L2.66797 12.0283L2.50586 11.6963L0.993164 8.60156L4.0127 7.01562L4.33887 6.84375L4.40234 6.48145L4.98926 3.13281L8.39453 3.60645L8.75293 3.65625L9.01562 3.40625L11.5 1.03613L13.9844 3.40625Z"
+        stroke="#D4D4D8"
+        strokeWidth="1.5"
+        style={{mixBlendMode: "overlay" as const}}
+      />
+      <g filter={`url(#${filterId})`}>
+        <path
+          d="M6 12.3279L9.76623 16L16 9.35519L14.5281 8L9.67965 13.1585L7.42857 10.929L6 12.3279Z"
+          fill="#F4F4F5"
+        />
+      </g>
+      <defs>
+        <filter
+          colorInterpolationFilters="sRGB"
+          filterUnits="userSpaceOnUse"
+          height="10.1"
+          id={filterId}
+          width="10"
+          x="6"
+          y="8"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.3" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.785986 0 0 0 0 0.532335 0 0 0 0 0.21662 0 0 0 1 0"
+          />
+          <feBlend in2="BackgroundImageFix" mode="normal" result="effect1_dropShadow_1_1856" />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.6" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect1_dropShadow_1_1856"
+            mode="normal"
+            result="effect2_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="0.9" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect2_dropShadow_1_1856"
+            mode="normal"
+            result="effect3_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.2" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect3_dropShadow_1_1856"
+            mode="normal"
+            result="effect4_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.5" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect4_dropShadow_1_1856"
+            mode="normal"
+            result="effect5_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="1.8" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect5_dropShadow_1_1856"
+            mode="normal"
+            result="effect6_dropShadow_1_1856"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            result="hardAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+          />
+          <feOffset dy="2.1" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0.784314 0 0 0 0 0.533333 0 0 0 0 0.215686 0 0 0 1 0"
+          />
+          <feBlend
+            in2="effect6_dropShadow_1_1856"
+            mode="normal"
+            result="effect7_dropShadow_1_1856"
+          />
+          <feBlend
+            in="SourceGraphic"
+            in2="effect7_dropShadow_1_1856"
+            mode="normal"
+            result="shape"
+          />
+        </filter>
+        <linearGradient
+          gradientUnits="userSpaceOnUse"
+          id={gradientId}
+          x1="6"
+          x2="16.5"
+          y1="1"
+          y2="25"
+        >
+          <stop stopColor="#F1DF76" />
+          <stop offset="0.0001" stopColor="#FFEF8F" />
+          <stop offset="0.479167" stopColor="#EECA37" />
+          <stop offset="1" stopColor="#DEB200" />
+        </linearGradient>
+      </defs>
+    </svg>
+  );
+};
+
+export const VerifiedBadgeIcon = memo(forwardRef(VerifiedBadgeIconRender));
diff --git a/packages/storybook/.storybook/stories/demos/index.tsx b/packages/storybook/.storybook/stories/demos/index.tsx
new file mode 100644
index 0000000..852875f
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/index.tsx
@@ -0,0 +1,50 @@
+import React from "react";
+
+import {AlertDemo} from "./alert-demo";
+import {AlertDialogDemo} from "./alert-dialog-demo";
+import {AllowNotificationsDemo} from "./allow-notifications-demo";
+import {AvatarGroupDemo} from "./avatar-group-demo";
+import {ButtonsDemo} from "./buttons-demo";
+import {InputOTPDemo} from "./input-otp-demo";
+import {ListBoxDemo} from "./list-box-demo";
+import {LoginDemo} from "./login-demo";
+import {SelectDemo} from "./select-demo";
+import {SliderDemo} from "./slider-demo";
+import {SubtleCardsDemo} from "./subtle-cards-demo";
+import {TabsDemo1} from "./tabs-1-demo";
+import {TabsDemo2} from "./tabs-2-demo";
+import {TextfieldDemo} from "./textfield-demo";
+import {UIComponentsDemo} from "./ui-components-demo";
+import {XProfileDemo} from "./x-profile-demo";
+
+export function DemoComponents() {
+  return (
+    <div className="mx-auto grid grid-cols-3 gap-8 py-24">
+      {/* Left */}
+      <div className="flex flex-col items-center gap-10">
+        <TextfieldDemo />
+        <SelectDemo />
+        <UIComponentsDemo />
+        <SliderDemo />
+        <TabsDemo1 />
+        <TabsDemo2 />
+        <ListBoxDemo />
+      </div>
+      {/* Center */}
+      <div className="flex flex-col items-center gap-10">
+        <AvatarGroupDemo />
+        <InputOTPDemo />
+        <ButtonsDemo />
+        <XProfileDemo />
+        <AlertDemo />
+        <AllowNotificationsDemo />
+      </div>
+      {/* Right */}
+      <div className="flex flex-col items-center gap-10">
+        <LoginDemo />
+        <SubtleCardsDemo />
+        <AlertDialogDemo />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/input-otp-demo.tsx b/packages/storybook/.storybook/stories/demos/input-otp-demo.tsx
new file mode 100644
index 0000000..559a755
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/input-otp-demo.tsx
@@ -0,0 +1,37 @@
+import {InputOTP, Label, Link} from "@heroui/react";
+import React, {useState} from "react";
+
+export function InputOTPDemo() {
+  // HERO - 4320 - easter egg
+  const [value, setValue] = useState("4320");
+
+  return (
+    <div className="flex w-full justify-center">
+      <div className="flex w-[280px] flex-col items-start justify-center gap-2">
+        <div className="flex flex-col items-start gap-1">
+          <Label>Verify account</Label>
+          <p className="text-sm text-muted">We&apos;ve sent a code to a****@gmail.com</p>
+        </div>
+        <InputOTP maxLength={6} value={value} onChange={setValue}>
+          <InputOTP.Group>
+            <InputOTP.Slot index={0} />
+            <InputOTP.Slot index={1} />
+            <InputOTP.Slot index={2} />
+          </InputOTP.Group>
+          <InputOTP.Separator />
+          <InputOTP.Group>
+            <InputOTP.Slot index={3} />
+            <InputOTP.Slot index={4} />
+            <InputOTP.Slot index={5} />
+          </InputOTP.Group>
+        </InputOTP>
+        <div className="flex items-center gap-[5px] px-1 pt-1">
+          <p className="text-sm text-muted">Didn&apos;t receive a code?</p>
+          <Link className="text-foreground" underline="always">
+            Resend
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/list-box-demo.tsx b/packages/storybook/.storybook/stories/demos/list-box-demo.tsx
new file mode 100644
index 0000000..c6dbefa
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/list-box-demo.tsx
@@ -0,0 +1,59 @@
+import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
+import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
+import React from "react";
+
+export function ListBoxDemo() {
+  return (
+    <Surface className="w-[256px] rounded-3xl shadow-surface">
+      <ListBox aria-label="File actions" className="w-full p-2" selectionMode="none">
+        <ListBox.Section>
+          <Header>Actions</Header>
+          <ListBox.Item id="new-file" textValue="New file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <SquarePlus className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>New file</Label>
+              <Description>Create a new file</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>N</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+          <ListBox.Item id="edit-file" textValue="Edit file">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <Pencil className="size-4 shrink-0 text-muted" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Edit file</Label>
+              <Description>Make changes</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Content>E</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+        <Separator />
+        <ListBox.Section>
+          <Header>Danger zone</Header>
+          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
+            <div className="flex h-8 items-start justify-center pt-px">
+              <TrashBin className="size-4 shrink-0 text-danger" />
+            </div>
+            <div className="flex flex-col">
+              <Label>Delete file</Label>
+              <Description>Move to trash</Description>
+            </div>
+            <Kbd className="ms-auto" variant="light">
+              <Kbd.Abbr keyValue="command" />
+              <Kbd.Abbr keyValue="shift" />
+              <Kbd.Content>D</Kbd.Content>
+            </Kbd>
+          </ListBox.Item>
+        </ListBox.Section>
+      </ListBox>
+    </Surface>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/login-demo.tsx b/packages/storybook/.storybook/stories/demos/login-demo.tsx
new file mode 100644
index 0000000..f98c4e2
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/login-demo.tsx
@@ -0,0 +1,40 @@
+import {Person} from "@gravity-ui/icons";
+import {Avatar, Button, Card, CloseButton, Separator} from "@heroui/react";
+import React from "react";
+
+import {AppleIcon, GoogleIcon} from "./components/icons";
+
+export function LoginDemo() {
+  return (
+    <Card className="w-[320px] items-start justify-center p-5">
+      <Card.Header className="flex w-full items-center justify-center gap-2">
+        <Avatar>
+          <Avatar.Fallback>
+            <Person />
+          </Avatar.Fallback>
+        </Avatar>
+        <Card.Title>Create an account</Card.Title>
+        <CloseButton className="absolute top-3 right-3" />
+      </Card.Header>
+      <Card.Content className="gap-2">
+        <p className="text-center text-sm font-medium text-muted">
+          Start your free 7-day trial. No credit card required.
+        </p>
+        <Button className="w-full">Get Started</Button>
+        <div className="flex w-full items-center gap-2 py-2">
+          <Separator className="flex-1" />
+          <p className="text-center text-xs font-medium text-muted uppercase">Or</p>
+          <Separator className="flex-1" />
+        </div>
+        <Button className="w-full" variant="tertiary">
+          <GoogleIcon />
+          Continue with Google
+        </Button>
+        <Button className="w-full" variant="tertiary">
+          <AppleIcon />
+          Continue with Apple
+        </Button>
+      </Card.Content>
+    </Card>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/select-demo.tsx b/packages/storybook/.storybook/stories/demos/select-demo.tsx
new file mode 100644
index 0000000..4399cdb
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/select-demo.tsx
@@ -0,0 +1,42 @@
+import {Label, ListBox, Select} from "@heroui/react";
+import React from "react";
+
+export function SelectDemo() {
+  return (
+    <Select isRequired className="w-[256px]" placeholder="Select one">
+      <Label>State</Label>
+      <Select.Trigger>
+        <Select.Value />
+        <Select.Indicator />
+      </Select.Trigger>
+      <Select.Popover>
+        <ListBox>
+          <ListBox.Item id="florida" textValue="Florida">
+            Florida
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="delaware" textValue="Delaware">
+            Delaware
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="california" textValue="California">
+            California
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="texas" textValue="Texas">
+            Texas
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="new-york" textValue="New York">
+            New York
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+          <ListBox.Item id="washington" textValue="Washington">
+            Washington
+            <ListBox.ItemIndicator />
+          </ListBox.Item>
+        </ListBox>
+      </Select.Popover>
+    </Select>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/slider-demo.tsx b/packages/storybook/.storybook/stories/demos/slider-demo.tsx
new file mode 100644
index 0000000..bd82d35
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/slider-demo.tsx
@@ -0,0 +1,24 @@
+import {Label, Slider} from "@heroui/react";
+import React from "react";
+
+export function SliderDemo() {
+  return (
+    <div className="w-[256px] px-1">
+      <Slider
+        className="w-full max-w-xs"
+        defaultValue={250}
+        formatOptions={{currency: "USD", style: "currency"}}
+        maxValue={500}
+        minValue={0}
+        step={10}
+      >
+        <Label>Price</Label>
+        <Slider.Output />
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/subtle-cards-demo.tsx b/packages/storybook/.storybook/stories/demos/subtle-cards-demo.tsx
new file mode 100644
index 0000000..0372169
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/subtle-cards-demo.tsx
@@ -0,0 +1,72 @@
+import {Avatar, Card} from "@heroui/react";
+import React from "react";
+import {tv} from "tailwind-variants";
+
+const cardStyles = tv({
+  slots: {
+    avatar: "size-[56px] rounded-xl",
+    card: "w-full",
+    cardContent: "items-start",
+    footer: "items-center gap-2",
+    footerAvatar: "size-4",
+  },
+});
+
+export function SubtleCardsDemo() {
+  const {avatar, card, cardContent, footer, footerAvatar} = cardStyles();
+
+  return (
+    <div className="flex w-full flex-row gap-4">
+      <Card className={card()}>
+        <Card.Header>
+          <Avatar className={avatar()}>
+            <Avatar.Image
+              alt="Demo 1"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
+            />
+            <Avatar.Fallback>JK</Avatar.Fallback>
+          </Avatar>
+        </Card.Header>
+        <Card.Content className={cardContent()}>
+          <p className="text-sm font-medium">Indie Hackers</p>
+          <p className="text-sm text-muted">148 members</p>
+        </Card.Content>
+        <Card.Footer className={footer()}>
+          <Avatar className={footerAvatar()}>
+            <Avatar.Image
+              alt="John"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
+            />
+            <Avatar.Fallback>JK</Avatar.Fallback>
+          </Avatar>
+          <p className="text-xs text-muted">By John</p>
+        </Card.Footer>
+      </Card>
+      <Card className={card()}>
+        <Card.Header>
+          <Avatar className={avatar()}>
+            <Avatar.Image
+              alt="AI Builders"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
+            />
+            <Avatar.Fallback>J</Avatar.Fallback>
+          </Avatar>
+        </Card.Header>
+        <Card.Content className={cardContent()}>
+          <p className="text-sm font-medium">AI Builders</p>
+          <p className="text-sm text-muted">362 members</p>
+        </Card.Content>
+        <Card.Footer className={footer()}>
+          <Avatar className={footerAvatar()}>
+            <Avatar.Image
+              alt="Martha"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
+            />
+            <Avatar.Fallback>M</Avatar.Fallback>
+          </Avatar>
+          <p className="text-xs text-muted">By Martha</p>
+        </Card.Footer>
+      </Card>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/tabs-1-demo.tsx b/packages/storybook/.storybook/stories/demos/tabs-1-demo.tsx
new file mode 100644
index 0000000..799b38b
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/tabs-1-demo.tsx
@@ -0,0 +1,33 @@
+import {Tabs} from "@heroui/react";
+import React from "react";
+
+export function TabsDemo1() {
+  return (
+    <Tabs className="w-[256px]">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab id="1d">
+            1D
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="7d">
+            7D
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="1m">
+            1M
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="1y">
+            1Y
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab id="all">
+            All
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/tabs-2-demo.tsx b/packages/storybook/.storybook/stories/demos/tabs-2-demo.tsx
new file mode 100644
index 0000000..7b27553
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/tabs-2-demo.tsx
@@ -0,0 +1,24 @@
+import {Comment, Envelope} from "@gravity-ui/icons";
+import {Tabs} from "@heroui/react";
+import React from "react";
+
+export function TabsDemo2() {
+  return (
+    <Tabs className="w-[256px]">
+      <Tabs.ListContainer>
+        <Tabs.List aria-label="Options">
+          <Tabs.Tab className="gap-1.5" id="chats">
+            <Comment />
+            <span>Chats</span>
+            <Tabs.Indicator />
+          </Tabs.Tab>
+          <Tabs.Tab className="gap-1.5" id="emails">
+            <Envelope />
+            <span>Emails</span>
+            <Tabs.Indicator />
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs.ListContainer>
+    </Tabs>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/textfield-demo.tsx b/packages/storybook/.storybook/stories/demos/textfield-demo.tsx
new file mode 100644
index 0000000..3b00380
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/textfield-demo.tsx
@@ -0,0 +1,15 @@
+import {Description, FieldError, Input, Label, TextField} from "@heroui/react";
+import React from "react";
+
+export function TextfieldDemo() {
+  return (
+    <div>
+      <TextField isRequired className="items-start" name="name">
+        <Label>Your email</Label>
+        <Input className="w-[256px]" placeholder="john@email.com" />
+        <Description className="mt-0.5">We'll never share this with anyone else</Description>
+        <FieldError>The email is invalid</FieldError>
+      </TextField>
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/ui-components-demo.tsx b/packages/storybook/.storybook/stories/demos/ui-components-demo.tsx
new file mode 100644
index 0000000..803aa07
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/ui-components-demo.tsx
@@ -0,0 +1,53 @@
+import {Checkbox, Radio, RadioGroup, Spinner, Switch} from "@heroui/react";
+import React from "react";
+
+export function UIComponentsDemo() {
+  return (
+    <div className="flex w-full items-center justify-center gap-8">
+      {/* Checkbox - Selected State */}
+      <Checkbox defaultSelected aria-label="Checkbox Indicator Example">
+        <Checkbox.Content>
+          <Checkbox.Control>
+            <Checkbox.Indicator />
+          </Checkbox.Control>
+        </Checkbox.Content>
+      </Checkbox>
+
+      {/* Switch - On State */}
+      <Switch defaultSelected aria-label="Switch On State Example">
+        <Switch.Content>
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+        </Switch.Content>
+      </Switch>
+
+      {/* Radio Buttons - Unselected and Selected */}
+      <RadioGroup
+        aria-label="Radio Buttons Example"
+        className="gap-8"
+        defaultValue="option2"
+        name="demo"
+        orientation="horizontal"
+      >
+        <Radio value="option1">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+          </Radio.Content>
+        </Radio>
+        <Radio value="option2">
+          <Radio.Content>
+            <Radio.Control>
+              <Radio.Indicator />
+            </Radio.Control>
+          </Radio.Content>
+        </Radio>
+      </RadioGroup>
+
+      {/* Spinner */}
+      <Spinner />
+    </div>
+  );
+}
diff --git a/packages/storybook/.storybook/stories/demos/x-profile-demo.tsx b/packages/storybook/.storybook/stories/demos/x-profile-demo.tsx
new file mode 100644
index 0000000..1709ea3
--- /dev/null
+++ b/packages/storybook/.storybook/stories/demos/x-profile-demo.tsx
@@ -0,0 +1,49 @@
+import {Avatar, Card} from "@heroui/react";
+import React from "react";
+
+import {VerifiedBadgeIcon} from "./components/icons";
+
+export function XProfileDemo() {
+  return (
+    <Card className="w-[400px] items-start justify-center">
+      <Card.Header className="items-top w-full flex-row justify-between">
+        <div className="flex items-center gap-3">
+          <Avatar size="sm">
+            <Avatar.Image
+              alt="HeroUI"
+              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui_isotipo.png"
+            />
+            <Avatar.Fallback>H</Avatar.Fallback>
+          </Avatar>
+          <div className="flex h-full flex-col items-start justify-center">
+            <div className="flex items-center gap-0.5">
+              <span className="text-sm leading-4 font-semibold">HeroUI</span>
+              <VerifiedBadgeIcon height={18} width={18} />
+            </div>
+            <span className="text-sm tracking-tight text-muted">@hero_ui</span>
+          </div>
+        </div>
+      </Card.Header>
+      <Card.Content className="flex-row text-left">
+        <p className="pl-px text-sm font-medium">
+          Building the future of UI for web & mobile.&nbsp;
+          <br />
+          <span aria-label="confetti" role="img">
+            🚀
+          </span>
+          &nbsp;(YC S24)&nbsp;
+        </p>
+      </Card.Content>
+      <Card.Footer className="gap-2">
+        <div className="flex gap-1">
+          <p className="text-sm font-semibold">4</p>
+          <p className="text-sm text-muted">Following</p>
+        </div>
+        <div className="flex gap-1">
+          <p className="text-sm font-semibold">97.1K</p>
+          <p className="text-sm text-muted">Followers</p>
+        </div>
+      </Card.Footer>
+    </Card>
+  );
+}
diff --git a/packages/storybook/.storybook/styles/theme.ts b/packages/storybook/.storybook/styles/theme.ts
new file mode 100644
index 0000000..972d7bc
--- /dev/null
+++ b/packages/storybook/.storybook/styles/theme.ts
@@ -0,0 +1,128 @@
+import {create, themes as storybookThemes} from "storybook/theming";
+
+// HeroUI Colors (OKLCH -> Hex approximation)
+const colors = {
+  white: "#FFFFFF",
+  black: "#000000",
+  zinc: {
+    50: "#FAFAFA",
+    100: "#F4F4F5",
+    200: "#E4E4E7",
+    300: "#D4D4D8",
+    400: "#A1A1AA",
+    500: "#71717A",
+    600: "#52525B",
+    700: "#3F3F46",
+    800: "#27272A",
+    900: "#18181B",
+    950: "#09090B",
+  },
+  light: {
+    background: "#f5f5f5",
+    foreground: "#18181b",
+    border: "#E4E4E7",
+  },
+  dark: {
+    background: "#060607",
+    foreground: "#fcfcfc",
+    border: "#27272A",
+  },
+  accent: {
+    DEFAULT: "#006FEE",
+    foreground: "#FFFFFF",
+  },
+};
+
+const fontBase = [
+  "ui-sans-serif",
+  "system-ui",
+  "sans-serif",
+  '"Apple Color Emoji"',
+  '"Segoe UI Emoji"',
+  '"Segoe UI Symbol"',
+  '"Noto Color Emoji"',
+].join(",");
+
+const fontCode = [
+  "ui-monospace",
+  "SFMono-Regular",
+  "Menlo",
+  "Monaco",
+  "Consolas",
+  '"Liberation Mono"',
+  '"Courier New"',
+  "monospace",
+].join(",");
+
+const lightTheme = create({
+  ...storybookThemes.light,
+  base: "light",
+  brandTitle: `<img src="/logo-dark.svg" style="width: 120px; height: auto;" alt="HeroUI"/>`,
+  // brandUrl: "https://heroui.com",
+  brandTarget: "_self",
+  // Colors
+  colorPrimary: colors.accent.DEFAULT,
+  colorSecondary: colors.accent.DEFAULT,
+  // UI
+  appBg: colors.light.background,
+  appContentBg: colors.light.background,
+  appPreviewBg: colors.light.background,
+  appBorderColor: colors.light.border,
+  appBorderRadius: 12,
+  // Typography
+  fontBase,
+  fontCode,
+  // Text
+  textColor: colors.light.foreground,
+  textInverseColor: colors.accent.foreground,
+  textMutedColor: colors.zinc[500],
+  // Toolbar
+  barBg: colors.light.background,
+  barTextColor: colors.zinc[500],
+  barSelectedColor: colors.accent.DEFAULT,
+  barHoverColor: colors.light.foreground,
+  // Form colors
+  inputBg: colors.white,
+  inputBorder: colors.light.border,
+  inputTextColor: colors.light.foreground,
+  inputBorderRadius: 8,
+});
+
+const darkTheme = create({
+  ...storybookThemes.dark,
+  base: "dark",
+  brandTitle: `<img src="/logo-light.svg" style="width: 120px; height: auto;" alt="HeroUI"/>`,
+  // brandUrl: "https://heroui.com",
+  brandTarget: "_self",
+  // Colors
+  colorPrimary: colors.accent.DEFAULT,
+  colorSecondary: colors.accent.DEFAULT,
+  // UI
+  appBg: colors.dark.background,
+  appContentBg: colors.dark.background,
+  appPreviewBg: colors.dark.background,
+  appBorderColor: colors.dark.border,
+  appBorderRadius: 12,
+  // Typography
+  fontBase,
+  fontCode,
+  // Text
+  textColor: colors.dark.foreground,
+  textInverseColor: colors.accent.foreground,
+  textMutedColor: colors.zinc[400],
+  // Toolbar
+  barBg: colors.dark.background,
+  barTextColor: colors.zinc[400],
+  barSelectedColor: colors.accent.DEFAULT,
+  barHoverColor: colors.dark.foreground,
+  // Form colors
+  inputBg: colors.zinc[800],
+  inputBorder: colors.dark.border,
+  inputTextColor: colors.dark.foreground,
+  inputBorderRadius: 8,
+});
+
+export const themes = {
+  dark: darkTheme,
+  light: lightTheme,
+};
diff --git a/packages/storybook/.storybook/utils/apcach-colors.ts b/packages/storybook/.storybook/utils/apcach-colors.ts
new file mode 100644
index 0000000..844725d
--- /dev/null
+++ b/packages/storybook/.storybook/utils/apcach-colors.ts
@@ -0,0 +1,646 @@
+/**
+ * Color calculation utilities using apcach for APCA-based contrast calculations
+ * Aligned with HeroUI theme system - starts with defaults from variables.css and applies hue/chroma adjustments
+ */
+import {formatRgb, parse} from "culori";
+
+/* -------------------------------------------------------------------------------------------------
+ * Default Theme Values (from packages/styles/themes/default/variables.css)
+ * -----------------------------------------------------------------------------------------------*/
+
+// Default base hue from accent color in variables.css
+const DEFAULT_BASE_HUE = 253.83; // From --accent: oklch(0.6204 0.195 253.83)
+const SEMANTIC_HUE_BLEND_FACTOR = 0.12; // 12% influence from base hue
+const WARNING_HUE_DARK = 76.34; // Warning hue for dark theme (different from light theme)
+
+// Default theme values from variables.css - these are the baseline that will be adjusted
+const DEFAULT_THEME_VALUES = {
+  light: {
+    background: {l: 0.9702, c: 0, h: 0},
+    foreground: {l: 0.2103, c: 0.0059, h: 285.89},
+    surface: {l: 1, c: 0, h: 0}, // Pure white (var(--white): oklch(100% 0 0))
+    surfaceSecondary: {l: 0.9524, c: 0.0013, h: 286.37},
+    surfaceTertiary: {l: 0.9373, c: 0.0013, h: 286.37},
+    overlay: {l: 1, c: 0, h: 0}, // Pure white (var(--white): oklch(100% 0 0))
+    muted: {l: 0.5517, c: 0.0138, h: 285.94},
+    scrollbar: {l: 0.871, c: 0.006, h: 286.286},
+    default: {l: 0.94, c: 0.001, h: 286.375},
+    accent: {l: 0.6204, c: 0.195, h: 253.83},
+    border: {l: 0.9, c: 0.004, h: 286.32},
+    separator: {l: 0.92, c: 0.004, h: 286.32},
+    segment: {l: 1, c: 0, h: 0}, // Pure white (var(--white): oklch(100% 0 0))
+    success: {l: 0.7329, c: 0.1935, h: 150.81},
+    warning: {l: 0.7819, c: 0.1585, h: 72.33},
+    danger: {l: 0.6532, c: 0.2328, h: 25.74},
+  },
+  dark: {
+    background: {l: 0.12, c: 0.005, h: 285.823},
+    foreground: {l: 0.9911, c: 0, h: 0}, // var(--snow): oklch(0.9911 0 0)
+    surface: {l: 0.2103, c: 0.0059, h: 285.89},
+    surfaceSecondary: {l: 0.257, c: 0.0037, h: 286.14},
+    surfaceTertiary: {l: 0.2721, c: 0.0024, h: 247.91},
+    overlay: {l: 0.2103, c: 0.0059, h: 285.89},
+    muted: {l: 0.705, c: 0.015, h: 286.067},
+    scrollbar: {l: 0.705, c: 0.015, h: 286.067},
+    default: {l: 0.274, c: 0.006, h: 286.033},
+    accent: {l: 0.6204, c: 0.195, h: 253.83}, // Same as light
+    border: {l: 0.28, c: 0.006, h: 286.033},
+    separator: {l: 0.25, c: 0.006, h: 286.033},
+    segment: {l: 0.3964, c: 0.01, h: 285.93},
+    success: {l: 0.7329, c: 0.1935, h: 150.81}, // Same as light
+    warning: {l: 0.8203, c: 0.1388, h: WARNING_HUE_DARK},
+    danger: {l: 0.594, c: 0.1967, h: 24.63},
+  },
+};
+
+// Semantic color defaults (from variables.css)
+const SEMANTIC_COLORS = {
+  success: {
+    hue: 150.81,
+    chromaLight: 0.1935,
+    chromaDark: 0.1935,
+    lightnessLight: 0.7329,
+    lightnessDark: 0.7329,
+  },
+  warning: {
+    hue: 72.33,
+    chromaLight: 0.1585,
+    chromaDark: 0.1388,
+    lightnessLight: 0.7819,
+    lightnessDark: 0.8203,
+  },
+  danger: {
+    hue: 25.74,
+    chromaLight: 0.2328,
+    chromaDark: 0.1967,
+    lightnessLight: 0.6532,
+    lightnessDark: 0.594,
+  },
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Types
+ * -----------------------------------------------------------------------------------------------*/
+
+export interface ThemeColor {
+  name: string;
+  oklchLight: string;
+  oklchDark: string;
+}
+
+export interface GeneratedColors {
+  background: ThemeColor;
+  foreground: ThemeColor;
+  accent: ThemeColor;
+  accentForeground: ThemeColor;
+  muted: ThemeColor;
+  default: ThemeColor;
+  defaultForeground: ThemeColor;
+  surface: ThemeColor;
+  surfaceSecondary: ThemeColor;
+  surfaceSecondaryForeground: ThemeColor;
+  surfaceTertiary: ThemeColor;
+  surfaceTertiaryForeground: ThemeColor;
+  overlay: ThemeColor;
+  scrollbar: ThemeColor;
+  segment: ThemeColor;
+  border: ThemeColor;
+  separator: ThemeColor;
+  // Semantic colors
+  success: ThemeColor;
+  successForeground: ThemeColor;
+  warning: ThemeColor;
+  warningForeground: ThemeColor;
+  danger: ThemeColor;
+  dangerForeground: ThemeColor;
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Utility Functions
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Adjust hue of a color object, keeping lightness and chroma
+ */
+function adjustHue(
+  color: {l: number; c: number; h: number},
+  newHue: number,
+): {l: number; c: number; h: number} {
+  return {...color, h: newHue};
+}
+
+/**
+ * Adjust chroma of a color object, keeping lightness and hue
+ */
+function adjustChroma(
+  color: {l: number; c: number; h: number},
+  newChroma: number,
+): {l: number; c: number; h: number} {
+  return {...color, c: Math.max(0, newChroma)};
+}
+
+/**
+ * Format a color object to OKLCH string
+ */
+function formatOklch(color: {l: number; c: number; h: number}): string {
+  return `oklch(${color.l * 100}% ${color.c} ${color.h})`;
+}
+
+/**
+ * Parse an OKLCH string or handle CSS variable references
+ */
+function parseOklchValue(
+  value: string | {l: number; c: number; h: number},
+): {l: number; c: number; h: number} | null {
+  if (typeof value === "string") {
+    // If it's a CSS variable reference, return null (will be handled separately)
+    if (value.startsWith("var(")) {
+      return null;
+    }
+    // Parse OKLCH string
+    const match = value.match(/oklch\(([0-9.]+)%?\s+([0-9.]+)\s+([0-9.]+)\)/);
+
+    if (match) {
+      const l = match[1].includes("%") ? parseFloat(match[1]) / 100 : parseFloat(match[1]);
+      const c = parseFloat(match[2]);
+      const h = parseFloat(match[3]);
+
+      return {l, c, h};
+    }
+
+    return null;
+  }
+
+  return value;
+}
+
+/**
+ * Calculate a blended hue for semantic colors based on the base hue
+ * This creates cohesion while maintaining semantic meaning
+ */
+function calculateSemanticHue(semanticDefaultHue: number, baseHue: number): number {
+  const hueOffset = (baseHue - DEFAULT_BASE_HUE) * SEMANTIC_HUE_BLEND_FACTOR;
+  let newHue = semanticDefaultHue + hueOffset;
+
+  // Normalize to 0-360 range
+  while (newHue < 0) newHue += 360;
+  while (newHue >= 360) newHue -= 360;
+
+  return newHue;
+}
+
+/**
+ * Generate a semantic color with APCA-based contrast for foreground
+ */
+function generateSemanticColor(
+  name: string,
+  config: typeof SEMANTIC_COLORS.success,
+  baseHue: number,
+  grayChroma: number,
+): {color: ThemeColor; foreground: ThemeColor} {
+  // Calculate blended hue
+  const adjustedHue = calculateSemanticHue(config.hue, baseHue);
+
+  // Scale chroma slightly based on gray chroma for visual harmony
+  // When gray chroma is low, keep semantic colors vibrant
+  // When gray chroma is high, we can boost semantic colors slightly
+  const chromaBoost = 1 + grayChroma * 2; // Small boost based on gray chroma
+
+  const chromaLight = Math.min(config.chromaLight * chromaBoost, 0.35);
+  const chromaDark = Math.min(config.chromaDark * chromaBoost, 0.35);
+
+  const colorLight = `oklch(${config.lightnessLight * 100}% ${chromaLight} ${adjustedHue})`;
+  const colorDark = `oklch(${config.lightnessDark * 100}% ${chromaDark} ${adjustedHue})`;
+
+  // Determine foreground color based on semantic color lightness
+  // Threshold ~0.67 matches original design:
+  // - Success (0.73), Warning (0.78) → dark foreground
+  // - Danger (0.65) → light foreground
+  const LIGHTNESS_THRESHOLD = 0.67;
+
+  // Light theme foreground: dark text for light backgrounds, light text for dark backgrounds
+  const fgLightTheme =
+    config.lightnessLight > LIGHTNESS_THRESHOLD
+      ? `oklch(21.03% 0.0059 ${adjustedHue})` // Eclipse-like (dark)
+      : `oklch(99.11% 0 0)`; // Snow (white)
+
+  // Dark theme foreground: similar logic but for dark theme semantic colors
+  const fgDarkTheme =
+    config.lightnessDark > LIGHTNESS_THRESHOLD
+      ? `oklch(21.03% 0.0059 ${adjustedHue})` // Eclipse-like (dark)
+      : `oklch(99.11% 0 0)`; // Snow (white)
+
+  return {
+    color: {
+      name: `--${name}`,
+      oklchLight: colorLight,
+      oklchDark: colorDark,
+    },
+    foreground: {
+      name: `--${name}-foreground`,
+      oklchLight: fgLightTheme,
+      oklchDark: fgDarkTheme,
+    },
+  };
+}
+
+/**
+ * Convert OKLCH to RGB string (for fallback)
+ */
+export function oklchToRgb(oklchString: string): string {
+  const parsed = parse(oklchString);
+
+  if (!parsed) return oklchString;
+
+  return formatRgb(parsed);
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Main Color Generation Function
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Generate all theme colors based on hue and chroma adjustments to defaults
+ * Starts with values from variables.css and applies hue/chroma adjustments
+ */
+export function generateThemeColors(hue: number, chroma: number): GeneratedColors {
+  // Helper to create ThemeColor from adjusted color values
+  const createThemeColor = (
+    name: string,
+    lightValue: string | {l: number; c: number; h: number},
+    darkValue: string | {l: number; c: number; h: number},
+  ): ThemeColor => {
+    // Handle CSS variable references (like var(--white), var(--eclipse))
+    if (typeof lightValue === "string" && lightValue.startsWith("var(")) {
+      return {
+        name,
+        oklchLight: lightValue,
+        oklchDark: typeof darkValue === "string" ? darkValue : formatOklch(darkValue),
+      };
+    }
+
+    const lightColor = typeof lightValue === "string" ? parseOklchValue(lightValue) : lightValue;
+    const darkColor = typeof darkValue === "string" ? parseOklchValue(darkValue) : darkValue;
+
+    return {
+      name,
+      oklchLight: lightColor
+        ? formatOklch(lightColor)
+        : typeof lightValue === "string"
+          ? lightValue
+          : formatOklch(lightValue),
+      oklchDark: darkColor
+        ? formatOklch(darkColor)
+        : typeof darkValue === "string"
+          ? darkValue
+          : formatOklch(darkValue),
+    };
+  };
+
+  // Get defaults
+  const defaultsLight = DEFAULT_THEME_VALUES.light;
+  const defaultsDark = DEFAULT_THEME_VALUES.dark;
+
+  // --background: Apply hue and chroma adjustments
+  const background: ThemeColor = {
+    name: "--background",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.background, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.background, hue), chroma)),
+  };
+
+  // --foreground: Uses CSS variables (eclipse/snow), no adjustment needed
+  const foreground: ThemeColor = {
+    name: "--foreground",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.foreground, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.foreground, hue), chroma)),
+  };
+
+  // --accent: Keep original chroma but adjust hue
+  const accent: ThemeColor = {
+    name: "--accent",
+    oklchLight: formatOklch(adjustHue(defaultsLight.accent, hue)),
+    oklchDark: formatOklch(adjustHue(defaultsDark.accent, hue)),
+  };
+
+  // --accent-foreground: Uses CSS variable (snow), no adjustment needed
+  const accentForeground: ThemeColor = createThemeColor(
+    "--accent-foreground",
+    "var(--snow)",
+    "var(--snow)",
+  );
+
+  // --muted: Apply hue and chroma adjustments
+  const muted: ThemeColor = {
+    name: "--muted",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.muted, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.muted, hue), chroma)),
+  };
+
+  // --default: Apply hue and chroma adjustments
+  const defaultColor: ThemeColor = {
+    name: "--default",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.default, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.default, hue), chroma)),
+  };
+
+  // --default-foreground: Uses CSS variables (eclipse/snow), adjust hue for eclipse
+  const defaultForeground: ThemeColor = {
+    name: "--default-foreground",
+    oklchLight: `oklch(21.03% 0.0059 ${hue})`, // Eclipse with adjusted hue
+    oklchDark: "var(--snow)", // Snow (white)
+  };
+
+  // --surface: Apply hue and chroma adjustments
+  const surfaceColor: ThemeColor = {
+    name: "--surface",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.surface, hue), chroma * 0.5)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.surface, hue), chroma * 2)),
+  };
+
+  // --surface-secondary: Apply hue and chroma adjustments
+  const surfaceSecondaryColor: ThemeColor = {
+    name: "--surface-secondary",
+    oklchLight: formatOklch(
+      adjustChroma(adjustHue(defaultsLight.surfaceSecondary, hue), chroma * 0.8),
+    ),
+    oklchDark: formatOklch(
+      adjustChroma(adjustHue(defaultsDark.surfaceSecondary, hue), chroma * 1.5),
+    ),
+  };
+
+  // --surface-secondary-foreground: Uses foreground value
+  const surfaceSecondaryForeground: ThemeColor = {
+    name: "--surface-secondary-foreground",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.foreground, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.foreground, hue), chroma)),
+  };
+
+  // --surface-tertiary: Apply hue and chroma adjustments
+  const surfaceTertiaryColor: ThemeColor = {
+    name: "--surface-tertiary",
+    oklchLight: formatOklch(
+      adjustChroma(adjustHue(defaultsLight.surfaceTertiary, hue), chroma * 0.8),
+    ),
+    oklchDark: formatOklch(
+      adjustChroma(adjustHue(defaultsDark.surfaceTertiary, hue), chroma * 1.5),
+    ),
+  };
+
+  // --surface-tertiary-foreground: Uses foreground value
+  const surfaceTertiaryForeground: ThemeColor = {
+    name: "--surface-tertiary-foreground",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.foreground, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.foreground, hue), chroma)),
+  };
+
+  // --overlay: Apply hue and chroma adjustments
+  const overlayColor: ThemeColor = {
+    name: "--overlay",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.overlay, hue), chroma * 0.3)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.overlay, hue), chroma * 2)),
+  };
+
+  // --scrollbar: Apply hue and chroma adjustments
+  const scrollbar: ThemeColor = {
+    name: "--scrollbar",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.scrollbar, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.scrollbar, hue), chroma)),
+  };
+
+  // --segment: Apply hue and chroma adjustments
+  const segment: ThemeColor = {
+    name: "--segment",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.segment, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.segment, hue), chroma)),
+  };
+
+  // --border: Apply hue and chroma adjustments
+  const border: ThemeColor = {
+    name: "--border",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.border, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.border, hue), chroma)),
+  };
+
+  // --separator: Apply hue and chroma adjustments
+  const separator: ThemeColor = {
+    name: "--separator",
+    oklchLight: formatOklch(adjustChroma(adjustHue(defaultsLight.separator, hue), chroma)),
+    oklchDark: formatOklch(adjustChroma(adjustHue(defaultsDark.separator, hue), chroma)),
+  };
+
+  // Generate semantic colors with base hue blending
+  const successColors = generateSemanticColor("success", SEMANTIC_COLORS.success, hue, chroma);
+  const warningColors = generateSemanticColor("warning", SEMANTIC_COLORS.warning, hue, chroma);
+  const dangerColors = generateSemanticColor("danger", SEMANTIC_COLORS.danger, hue, chroma);
+
+  return {
+    background,
+    foreground,
+    accent,
+    accentForeground,
+    muted,
+    default: defaultColor,
+    defaultForeground,
+    surface: surfaceColor,
+    surfaceSecondary: surfaceSecondaryColor,
+    surfaceSecondaryForeground,
+    surfaceTertiary: surfaceTertiaryColor,
+    surfaceTertiaryForeground,
+    overlay: overlayColor,
+    scrollbar,
+    segment,
+    border,
+    separator,
+    // Semantic colors
+    success: successColors.color,
+    successForeground: successColors.foreground,
+    warning: warningColors.color,
+    warningForeground: warningColors.foreground,
+    danger: dangerColors.color,
+    dangerForeground: dangerColors.foreground,
+  };
+}
+
+/**
+ * Build CSS variables string for a theme
+ * Only generates variables that exist in variables.css
+ */
+export function buildThemeCssVars(colors: GeneratedColors, theme: "light" | "dark"): string {
+  const isLight = theme === "light";
+  const vars: string[] = [];
+
+  const getValue = (color: ThemeColor) => (isLight ? color.oklchLight : color.oklchDark);
+
+  // Background and foreground
+  vars.push(`--background: ${getValue(colors.background)}`);
+  vars.push(`--color-background: ${getValue(colors.background)}`);
+  vars.push(`--foreground: ${getValue(colors.foreground)}`);
+  vars.push(`--color-foreground: ${getValue(colors.foreground)}`);
+
+  // Accent colors
+  vars.push(`--accent: ${getValue(colors.accent)}`);
+  vars.push(`--color-accent: ${getValue(colors.accent)}`);
+  vars.push(`--accent-foreground: ${getValue(colors.accentForeground)}`);
+  vars.push(`--color-accent-foreground: ${getValue(colors.accentForeground)}`);
+  vars.push(`--focus: ${getValue(colors.accent)}`);
+  vars.push(`--color-focus: ${getValue(colors.accent)}`);
+
+  // Accent variations using color-mix (calculated in theme.css)
+  const accentValue = getValue(colors.accent);
+  const accentFgValue = getValue(colors.accentForeground);
+
+  vars.push(`--color-accent-hover: color-mix(in oklab, ${accentValue} 90%, ${accentFgValue} 10%)`);
+  vars.push(`--color-accent-soft: color-mix(in oklab, ${accentValue} 15%, transparent)`);
+  vars.push(`--color-accent-soft-foreground: ${accentValue}`);
+  vars.push(`--color-accent-soft-hover: color-mix(in oklab, ${accentValue} 20%, transparent)`);
+
+  // Muted
+  vars.push(`--muted: ${getValue(colors.muted)}`);
+  vars.push(`--color-muted: ${getValue(colors.muted)}`);
+  vars.push(`--field-placeholder: ${getValue(colors.muted)}`);
+  vars.push(`--color-field-placeholder: ${getValue(colors.muted)}`);
+
+  // Default (switch track, slider track, secondary buttons)
+  vars.push(`--default: ${getValue(colors.default)}`);
+  vars.push(`--color-default: ${getValue(colors.default)}`);
+
+  // Default foreground
+  vars.push(`--default-foreground: ${getValue(colors.defaultForeground)}`);
+  vars.push(`--color-default-foreground: ${getValue(colors.defaultForeground)}`);
+
+  // Default hover (calculated in theme.css)
+  const defaultValue = getValue(colors.default);
+
+  vars.push(
+    `--color-default-hover: color-mix(in oklab, ${defaultValue} 90%, ${getValue(colors.foreground)} 10%)`,
+  );
+
+  // Surface (solid color for cards, accordions, etc.)
+  vars.push(`--surface: ${getValue(colors.surface)}`);
+  vars.push(`--color-surface: ${getValue(colors.surface)}`);
+  vars.push(`--surface-foreground: ${getValue(colors.foreground)}`);
+  vars.push(`--color-surface-foreground: ${getValue(colors.foreground)}`);
+
+  // Surface secondary
+  vars.push(`--surface-secondary: ${getValue(colors.surfaceSecondary)}`);
+  vars.push(`--color-surface-secondary: ${getValue(colors.surfaceSecondary)}`);
+  vars.push(`--surface-secondary-foreground: ${getValue(colors.surfaceSecondaryForeground)}`);
+  vars.push(`--color-surface-secondary-foreground: ${getValue(colors.surfaceSecondaryForeground)}`);
+
+  // Surface tertiary
+  vars.push(`--surface-tertiary: ${getValue(colors.surfaceTertiary)}`);
+  vars.push(`--color-surface-tertiary: ${getValue(colors.surfaceTertiary)}`);
+  vars.push(`--surface-tertiary-foreground: ${getValue(colors.surfaceTertiaryForeground)}`);
+  vars.push(`--color-surface-tertiary-foreground: ${getValue(colors.surfaceTertiaryForeground)}`);
+
+  // Overlay (tooltips, popovers, modals)
+  vars.push(`--overlay: ${getValue(colors.overlay)}`);
+  vars.push(`--color-overlay: ${getValue(colors.overlay)}`);
+  vars.push(`--overlay-foreground: ${getValue(colors.foreground)}`);
+  vars.push(`--color-overlay-foreground: ${getValue(colors.foreground)}`);
+
+  // Scrollbar
+  vars.push(`--scrollbar: ${getValue(colors.scrollbar)}`);
+  vars.push(`--color-scrollbar: ${getValue(colors.scrollbar)}`);
+
+  // Segment (segmented controls)
+  vars.push(`--segment: ${getValue(colors.segment)}`);
+  vars.push(`--color-segment: ${getValue(colors.segment)}`);
+  vars.push(`--segment-foreground: ${getValue(colors.foreground)}`);
+  vars.push(`--color-segment-foreground: ${getValue(colors.foreground)}`);
+
+  // Border
+  vars.push(`--border: ${getValue(colors.border)}`);
+  vars.push(`--color-border: ${getValue(colors.border)}`);
+
+  // Separator
+  vars.push(`--separator: ${getValue(colors.separator)}`);
+  vars.push(`--color-separator: ${getValue(colors.separator)}`);
+
+  // Semantic colors (success, warning, danger)
+  // These are blended with the base hue for visual cohesion
+  vars.push(`--success: ${getValue(colors.success)}`);
+  vars.push(`--color-success: ${getValue(colors.success)}`);
+  vars.push(`--success-foreground: ${getValue(colors.successForeground)}`);
+  vars.push(`--color-success-foreground: ${getValue(colors.successForeground)}`);
+
+  // Success soft variants using color-mix (calculated in theme.css)
+  const successValue = getValue(colors.success);
+
+  vars.push(
+    `--color-success-hover: color-mix(in oklab, ${successValue} 90%, ${getValue(colors.successForeground)} 10%)`,
+  );
+  vars.push(`--color-success-soft: color-mix(in oklab, ${successValue} 15%, transparent)`);
+  vars.push(`--color-success-soft-foreground: ${successValue}`);
+  vars.push(`--color-success-soft-hover: color-mix(in oklab, ${successValue} 20%, transparent)`);
+
+  vars.push(`--warning: ${getValue(colors.warning)}`);
+  vars.push(`--color-warning: ${getValue(colors.warning)}`);
+  vars.push(`--warning-foreground: ${getValue(colors.warningForeground)}`);
+  vars.push(`--color-warning-foreground: ${getValue(colors.warningForeground)}`);
+
+  // Warning soft variants (calculated in theme.css)
+  const warningValue = getValue(colors.warning);
+
+  vars.push(
+    `--color-warning-hover: color-mix(in oklab, ${warningValue} 90%, ${getValue(colors.warningForeground)} 10%)`,
+  );
+  vars.push(`--color-warning-soft: color-mix(in oklab, ${warningValue} 15%, transparent)`);
+  vars.push(`--color-warning-soft-foreground: ${warningValue}`);
+  vars.push(`--color-warning-soft-hover: color-mix(in oklab, ${warningValue} 20%, transparent)`);
+
+  vars.push(`--danger: ${getValue(colors.danger)}`);
+  vars.push(`--color-danger: ${getValue(colors.danger)}`);
+  vars.push(`--danger-foreground: ${getValue(colors.dangerForeground)}`);
+  vars.push(`--color-danger-foreground: ${getValue(colors.dangerForeground)}`);
+
+  // Danger soft variants (calculated in theme.css)
+  const dangerValue = getValue(colors.danger);
+
+  vars.push(
+    `--color-danger-hover: color-mix(in oklab, ${dangerValue} 90%, ${getValue(colors.dangerForeground)} 10%)`,
+  );
+  vars.push(`--color-danger-soft: color-mix(in oklab, ${dangerValue} 15%, transparent)`);
+  vars.push(`--color-danger-soft-foreground: ${dangerValue}`);
+  vars.push(`--color-danger-soft-hover: color-mix(in oklab, ${dangerValue} 20%, transparent)`);
+
+  return vars.join(";\n  ");
+}
+
+/**
+ * Get all generated colors as a flat array for display
+ */
+export function getColorVariablesArray(
+  colors: GeneratedColors,
+  theme: "light" | "dark",
+): Array<{name: string; value: string}> {
+  const isLight = theme === "light";
+  const getValue = (color: ThemeColor) => (isLight ? color.oklchLight : color.oklchDark);
+
+  return [
+    {name: "--background", value: getValue(colors.background)},
+    {name: "--foreground", value: getValue(colors.foreground)},
+    {name: "--surface", value: getValue(colors.surface)},
+    {name: "--surface-secondary", value: getValue(colors.surfaceSecondary)},
+    {name: "--surface-secondary-foreground", value: getValue(colors.surfaceSecondaryForeground)},
+    {name: "--surface-tertiary", value: getValue(colors.surfaceTertiary)},
+    {name: "--surface-tertiary-foreground", value: getValue(colors.surfaceTertiaryForeground)},
+    {name: "--overlay", value: getValue(colors.overlay)},
+    {name: "--default", value: getValue(colors.default)},
+    {name: "--default-foreground", value: getValue(colors.defaultForeground)},
+    {name: "--accent", value: getValue(colors.accent)},
+    {name: "--accent-foreground", value: getValue(colors.accentForeground)},
+    {name: "--muted", value: getValue(colors.muted)},
+    {name: "--scrollbar", value: getValue(colors.scrollbar)},
+    {name: "--segment", value: getValue(colors.segment)},
+    {name: "--border", value: getValue(colors.border)},
+    {name: "--separator", value: getValue(colors.separator)},
+    // Semantic colors
+    {name: "--success", value: getValue(colors.success)},
+    {name: "--success-foreground", value: getValue(colors.successForeground)},
+    {name: "--warning", value: getValue(colors.warning)},
+    {name: "--warning-foreground", value: getValue(colors.warningForeground)},
+    {name: "--danger", value: getValue(colors.danger)},
+    {name: "--danger-foreground", value: getValue(colors.dangerForeground)},
+  ];
+}
diff --git a/packages/storybook/.storybook/utils/cn.ts b/packages/storybook/.storybook/utils/cn.ts
new file mode 100644
index 0000000..9d2473c
--- /dev/null
+++ b/packages/storybook/.storybook/utils/cn.ts
@@ -0,0 +1,2 @@
+// Re-export cn from @heroui/react for convenience
+export {cn} from "@heroui/react";
diff --git a/packages/storybook/.storybook/utils/compose-tw-render.ts b/packages/storybook/.storybook/utils/compose-tw-render.ts
new file mode 100644
index 0000000..d81a649
--- /dev/null
+++ b/packages/storybook/.storybook/utils/compose-tw-render.ts
@@ -0,0 +1,9 @@
+import {composeRenderProps} from "react-aria-components";
+import {twMerge} from "tailwind-merge";
+
+export function composeTailwindRenderProps<T>(
+  className: string | ((v: T) => string) | undefined,
+  tw: string,
+): string | ((v: T) => string) {
+  return composeRenderProps(className, (className) => twMerge(tw, className));
+}
diff --git a/packages/storybook/.storybook/utils/css-variable-reader.ts b/packages/storybook/.storybook/utils/css-variable-reader.ts
new file mode 100644
index 0000000..d363a59
--- /dev/null
+++ b/packages/storybook/.storybook/utils/css-variable-reader.ts
@@ -0,0 +1,290 @@
+/**
+ * CSS Variable Reader Utility
+ * Reads CSS variable values from the DOM and resolves variable references
+ */
+
+import {parseOklch} from "./oklch-utils";
+
+/**
+ * Theme values structure matching DEFAULT_THEME_VALUES format
+ */
+export interface ThemeValues {
+  background: {l: number; c: number; h: number};
+  foreground: {l: number; c: number; h: number};
+  surface: {l: number; c: number; h: number};
+  overlay: {l: number; c: number; h: number};
+  muted: {l: number; c: number; h: number};
+  scrollbar: {l: number; c: number; h: number};
+  default: {l: number; c: number; h: number};
+  accent: {l: number; c: number; h: number};
+  border: {l: number; c: number; h: number};
+  separator: {l: number; c: number; h: number};
+  segment: {l: number; c: number; h: number};
+  success: {l: number; c: number; h: number};
+  warning: {l: number; c: number; h: number};
+  danger: {l: number; c: number; h: number};
+}
+
+/**
+ * Read a CSS variable value from an element
+ * Handles theme-specific selectors by reading from the appropriate element context
+ */
+export function readCssVariable(element: HTMLElement, variableName: string): string {
+  // Get computed style from the element
+  const computedStyle = getComputedStyle(element);
+  const value = computedStyle.getPropertyValue(variableName).trim();
+
+  return value;
+}
+
+/**
+ * Resolve CSS variable references recursively
+ * Handles var(--reference) by resolving to actual OKLCH values
+ */
+export function resolveCssVariable(
+  element: HTMLElement,
+  variableName: string,
+  theme: "light" | "dark",
+  visited: Set<string> = new Set(),
+): string | null {
+  // Prevent infinite loops
+  if (visited.has(variableName)) {
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.warn(`Circular reference detected for CSS variable: ${variableName}`);
+    }
+
+    return null;
+  }
+
+  visited.add(variableName);
+
+  const value = readCssVariable(element, variableName);
+
+  if (!value) {
+    return null;
+  }
+
+  // If it's a CSS variable reference, resolve it
+  if (value.startsWith("var(")) {
+    // Extract variable name from var(--name) or var(--name, fallback)
+    const match = value.match(/var\(\s*([^,)]+)(?:\s*,\s*([^)]+))?\s*\)/);
+
+    if (match) {
+      const refVarName = match[1].trim();
+      const fallback = match[2]?.trim();
+
+      // Try to resolve the referenced variable
+      const resolved = resolveCssVariable(element, refVarName, theme, visited);
+
+      if (resolved) {
+        return resolved;
+      }
+
+      // If resolution failed and there's a fallback, use it
+      if (fallback) {
+        // If fallback is another var(), resolve it
+        if (fallback.startsWith("var(")) {
+          return resolveCssVariable(element, fallback, theme, visited);
+        }
+
+        return fallback;
+      }
+    }
+
+    return null;
+  }
+
+  // Return the resolved value (should be OKLCH or other CSS value)
+  return value;
+}
+
+/**
+ * Parse OKLCH value and convert to {l, c, h} format
+ * Handles percentage format (12% -> 0.12) and decimal format (0.12 -> 0.12)
+ */
+function parseOklchToObject(value: string): {l: number; c: number; h: number} | null {
+  const oklch = parseOklch(value);
+
+  if (!oklch) {
+    return null;
+  }
+
+  return {
+    l: oklch.l,
+    c: oklch.c,
+    h: oklch.h,
+  };
+}
+
+/**
+ * Read default theme values from CSS variables in the DOM
+ * Resolves all variable references and parses OKLCH values
+ */
+export function readDefaultThemeValues(
+  element: HTMLElement,
+  theme: "light" | "dark",
+): ThemeValues | null {
+  // Always use document.documentElement (html element) which has CSS variables defined
+  // CSS variables are defined on :root, .light, [data-theme="light"], etc.
+  // The html element should already have these classes/attributes applied
+  const htmlElement = document.documentElement;
+
+  // Temporarily ensure the correct theme is set on html element
+  const originalClasses = htmlElement.className;
+  const originalDataTheme = htmlElement.getAttribute("data-theme");
+
+  // Set theme context on html element
+  htmlElement.classList.remove("light", "dark", "default");
+  htmlElement.classList.add(theme);
+  htmlElement.setAttribute("data-theme", theme);
+
+  // Force a reflow to ensure CSS is applied
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  htmlElement.offsetHeight;
+
+  // Verify CSS variables are available by checking a primitive variable
+  const testValue = getComputedStyle(htmlElement).getPropertyValue("--white").trim();
+
+  if (!testValue && process.env.NODE_ENV === "development") {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "CSS variables may not be loaded. Check that @packages/styles CSS files are imported.",
+    );
+  }
+
+  try {
+    // Read all required CSS variables from the html element
+    const backgroundValue = resolveCssVariable(htmlElement, "--background", theme);
+    const foregroundValue = resolveCssVariable(htmlElement, "--foreground", theme);
+    const surfaceValue = resolveCssVariable(htmlElement, "--surface", theme);
+    const overlayValue = resolveCssVariable(htmlElement, "--overlay", theme);
+    const mutedValue = resolveCssVariable(htmlElement, "--muted", theme);
+    const scrollbarValue = resolveCssVariable(htmlElement, "--scrollbar", theme);
+    const defaultValue = resolveCssVariable(htmlElement, "--default", theme);
+    const accentValue = resolveCssVariable(htmlElement, "--accent", theme);
+    const borderValue = resolveCssVariable(htmlElement, "--border", theme);
+    const separatorValue = resolveCssVariable(htmlElement, "--separator", theme);
+    const segmentValue = resolveCssVariable(htmlElement, "--segment", theme);
+    const successValue = resolveCssVariable(htmlElement, "--success", theme);
+    const warningValue = resolveCssVariable(htmlElement, "--warning", theme);
+    const dangerValue = resolveCssVariable(htmlElement, "--danger", theme);
+
+    // Parse all values to OKLCH objects
+    const background = backgroundValue ? parseOklchToObject(backgroundValue) : null;
+    const foreground = foregroundValue ? parseOklchToObject(foregroundValue) : null;
+    const surface = surfaceValue ? parseOklchToObject(surfaceValue) : null;
+    const overlay = overlayValue ? parseOklchToObject(overlayValue) : null;
+    const muted = mutedValue ? parseOklchToObject(mutedValue) : null;
+    const scrollbar = scrollbarValue ? parseOklchToObject(scrollbarValue) : null;
+    const defaultColor = defaultValue ? parseOklchToObject(defaultValue) : null;
+    const accent = accentValue ? parseOklchToObject(accentValue) : null;
+    const border = borderValue ? parseOklchToObject(borderValue) : null;
+    const separator = separatorValue ? parseOklchToObject(separatorValue) : null;
+    const segment = segmentValue ? parseOklchToObject(segmentValue) : null;
+    const success = successValue ? parseOklchToObject(successValue) : null;
+    const warning = warningValue ? parseOklchToObject(warningValue) : null;
+    const danger = dangerValue ? parseOklchToObject(dangerValue) : null;
+
+    // Check if all required values were successfully parsed
+    if (
+      !background ||
+      !foreground ||
+      !surface ||
+      !overlay ||
+      !muted ||
+      !scrollbar ||
+      !defaultColor ||
+      !accent ||
+      !border ||
+      !separator ||
+      !segment ||
+      !success ||
+      !warning ||
+      !danger
+    ) {
+      // Collect missing values for better error reporting
+      const missing: string[] = [];
+      const rawValues: Record<string, string | null> = {};
+
+      if (!background) missing.push("--background");
+      if (!foreground) missing.push("--foreground");
+      if (!surface) missing.push("--surface");
+      if (!overlay) missing.push("--overlay");
+      if (!muted) missing.push("--muted");
+      if (!scrollbar) missing.push("--scrollbar");
+      if (!defaultColor) missing.push("--default");
+      if (!accent) missing.push("--accent");
+      if (!border) missing.push("--border");
+      if (!separator) missing.push("--separator");
+      if (!segment) missing.push("--segment");
+      if (!success) missing.push("--success");
+      if (!warning) missing.push("--warning");
+      if (!danger) missing.push("--danger");
+
+      // Get raw values for debugging
+      rawValues["--background"] = backgroundValue;
+      rawValues["--foreground"] = foregroundValue;
+      rawValues["--surface"] = surfaceValue;
+      rawValues["--overlay"] = overlayValue;
+      rawValues["--muted"] = mutedValue;
+      rawValues["--scrollbar"] = scrollbarValue;
+      rawValues["--default"] = defaultValue;
+      rawValues["--accent"] = accentValue;
+      rawValues["--border"] = borderValue;
+      rawValues["--separator"] = separatorValue;
+      rawValues["--segment"] = segmentValue;
+      rawValues["--success"] = successValue;
+      rawValues["--warning"] = warningValue;
+      rawValues["--danger"] = dangerValue;
+
+      // Check if primitive variables are available (they should always be available)
+      const whiteValue = resolveCssVariable(htmlElement, "--white", theme);
+      const eclipseValue = resolveCssVariable(htmlElement, "--eclipse", theme);
+      const snowValue = resolveCssVariable(htmlElement, "--snow", theme);
+
+      if (process.env.NODE_ENV === "development") {
+        // eslint-disable-next-line no-console
+        console.warn("Failed to parse some CSS variables. Missing values:", {
+          missing,
+          rawValues,
+          theme,
+          htmlElementClasses: htmlElement.className,
+          htmlElementDataTheme: htmlElement.getAttribute("data-theme"),
+          primitiveVariables: {
+            "--white": whiteValue,
+            "--eclipse": eclipseValue,
+            "--snow": snowValue,
+          },
+        });
+      }
+
+      return null;
+    }
+
+    return {
+      background,
+      foreground,
+      surface,
+      overlay,
+      muted,
+      scrollbar,
+      default: defaultColor,
+      accent,
+      border,
+      separator,
+      segment,
+      success,
+      warning,
+      danger,
+    };
+  } finally {
+    // Restore original classes and data-theme on html element
+    htmlElement.className = originalClasses;
+    if (originalDataTheme) {
+      htmlElement.setAttribute("data-theme", originalDataTheme);
+    } else {
+      htmlElement.removeAttribute("data-theme");
+    }
+  }
+}
diff --git a/packages/storybook/.storybook/utils/focus.ts b/packages/storybook/.storybook/utils/focus.ts
new file mode 100644
index 0000000..0966b0a
--- /dev/null
+++ b/packages/storybook/.storybook/utils/focus.ts
@@ -0,0 +1,11 @@
+import {tv} from "tailwind-variants";
+
+export const focusRing = tv({
+  base: "outline outline-offset-2 outline-blue-600 dark:outline-blue-500 forced-colors:outline-[Highlight]",
+  variants: {
+    isFocusVisible: {
+      false: "outline-0",
+      true: "outline-2",
+    },
+  },
+});
diff --git a/packages/storybook/.storybook/utils/index.ts b/packages/storybook/.storybook/utils/index.ts
new file mode 100644
index 0000000..e26a1f6
--- /dev/null
+++ b/packages/storybook/.storybook/utils/index.ts
@@ -0,0 +1,4 @@
+export {cn} from "./cn";
+export {focusRing} from "./focus";
+export {composeTailwindRenderProps} from "./compose-tw-render";
+export * from "./oklch-utils";
diff --git a/packages/storybook/.storybook/utils/oklch-utils.ts b/packages/storybook/.storybook/utils/oklch-utils.ts
new file mode 100644
index 0000000..7f9934b
--- /dev/null
+++ b/packages/storybook/.storybook/utils/oklch-utils.ts
@@ -0,0 +1,171 @@
+/**
+ * Oklch color utilities for parsing and manipulating Oklch color values
+ */
+
+export interface OklchColor {
+  /** Lightness (0-1) */
+  l: number;
+  /** Chroma (0-0.4+) */
+  c: number;
+  /** Hue (0-360) */
+  h: number;
+  /** Alpha (0-1) */
+  alpha?: number;
+}
+
+/**
+ * Parse an Oklch color string into its components
+ * Supports formats: oklch(L C H), oklch(L C H / A), oklch(L% C H)
+ */
+export function parseOklch(colorString: string): OklchColor | null {
+  if (!colorString) return null;
+
+  const trimmed = colorString.trim().toLowerCase();
+
+  // Match oklch(...) format
+  const match = trimmed.match(
+    /^oklch\(\s*([0-9.]+%?)\s+([0-9.]+)\s+([0-9.]+)\s*(?:\/\s*([0-9.]+%?))?\s*\)$/,
+  );
+
+  if (!match) return null;
+
+  let l = parseFloat(match[1]);
+  const c = parseFloat(match[2]);
+  const h = parseFloat(match[3]);
+  let alpha = match[4] ? parseFloat(match[4]) : 1;
+
+  // Handle percentage for lightness
+  if (match[1].includes("%")) {
+    l = l / 100;
+  }
+
+  // Handle percentage for alpha
+  if (match[4]?.includes("%")) {
+    alpha = alpha / 100;
+  }
+
+  return {l, c, h, alpha};
+}
+
+/**
+ * Format an OklchColor object back to a CSS string
+ */
+export function formatOklch(color: OklchColor, includeAlpha = false): string {
+  const {alpha, c, h, l} = color;
+
+  if (includeAlpha && alpha !== undefined && alpha < 1) {
+    return `oklch(${l.toFixed(4)} ${c.toFixed(4)} ${h.toFixed(2)} / ${alpha})`;
+  }
+
+  return `oklch(${l.toFixed(4)} ${c.toFixed(4)} ${h.toFixed(2)})`;
+}
+
+/**
+ * Create an Oklch color with modified hue
+ */
+export function withHue(color: OklchColor, hue: number): OklchColor {
+  return {...color, h: hue % 360};
+}
+
+/**
+ * Create an Oklch color with modified chroma
+ */
+export function withChroma(color: OklchColor, chroma: number): OklchColor {
+  return {...color, c: Math.max(0, chroma)};
+}
+
+/**
+ * Create an Oklch color with modified lightness
+ */
+export function withLightness(color: OklchColor, lightness: number): OklchColor {
+  return {...color, l: Math.max(0, Math.min(1, lightness))};
+}
+
+/**
+ * Generate a palette of colors based on a base hue and chroma
+ * @param baseHue - The base hue angle (0-360)
+ * @param chroma - The chroma/saturation value
+ * @param steps - Number of lightness steps to generate
+ */
+export function generatePalette(baseHue: number, chroma: number, steps = 10): OklchColor[] {
+  const palette: OklchColor[] = [];
+
+  for (let i = 0; i < steps; i++) {
+    const lightness = 0.95 - (i / (steps - 1)) * 0.8; // Range from 0.95 to 0.15
+
+    palette.push({
+      l: lightness,
+      c: chroma,
+      h: baseHue,
+    });
+  }
+
+  return palette;
+}
+
+/**
+ * Calculate appropriate foreground color (black or white) for a given Oklch background
+ */
+export function calculateForegroundColor(bgColor: OklchColor): "black" | "white" {
+  // Use lightness to determine foreground - simple threshold at 0.6
+  return bgColor.l > 0.6 ? "black" : "white";
+}
+
+/**
+ * Adjust chroma for gray tones
+ * @param baseChroma - The base chroma value
+ * @param grayAmount - Amount of color in gray (0-1, where 0 is pure gray)
+ */
+export function adjustGrayChroma(baseChroma: number, grayAmount: number): number {
+  return baseChroma * grayAmount;
+}
+
+/**
+ * List of CSS color variable names that use Oklch values in HeroUI
+ */
+export const COLOR_VARIABLES = [
+  // Primitive colors
+  {name: "--white", label: "White", category: "primitive"},
+  {name: "--black", label: "Black", category: "primitive"},
+  {name: "--snow", label: "Snow", category: "primitive"},
+  {name: "--eclipse", label: "Eclipse", category: "primitive"},
+
+  // Base colors
+  {name: "--background", label: "Background", category: "base"},
+  {name: "--foreground", label: "Foreground", category: "base"},
+  {name: "--surface", label: "Surface", category: "surface"},
+  {name: "--surface-foreground", label: "Surface Foreground", category: "surface"},
+  {name: "--surface-secondary", label: "Surface Secondary", category: "surface"},
+  {name: "--surface-secondary-foreground", label: "Surface Secondary FG", category: "surface"},
+  {name: "--surface-tertiary", label: "Surface Tertiary", category: "surface"},
+  {name: "--surface-tertiary-foreground", label: "Surface Tertiary FG", category: "surface"},
+  {name: "--overlay", label: "Overlay", category: "overlay"},
+  {name: "--overlay-foreground", label: "Overlay Foreground", category: "overlay"},
+
+  // Semantic colors
+  {name: "--muted", label: "Muted", category: "semantic"},
+  {name: "--default", label: "Default", category: "semantic"},
+  {name: "--default-foreground", label: "Default Foreground", category: "semantic"},
+  {name: "--accent", label: "Accent", category: "accent"},
+  {name: "--accent-foreground", label: "Accent Foreground", category: "accent"},
+
+  // Status colors
+  {name: "--success", label: "Success", category: "status"},
+  {name: "--success-foreground", label: "Success Foreground", category: "status"},
+  {name: "--warning", label: "Warning", category: "status"},
+  {name: "--warning-foreground", label: "Warning Foreground", category: "status"},
+  {name: "--danger", label: "Danger", category: "status"},
+  {name: "--danger-foreground", label: "Danger Foreground", category: "status"},
+
+  // Field colors
+  {name: "--field-background", label: "Field Background", category: "field"},
+  {name: "--field-foreground", label: "Field Foreground", category: "field"},
+  {name: "--field-placeholder", label: "Field Placeholder", category: "field"},
+
+  // Border colors
+  {name: "--border", label: "Border", category: "border"},
+  {name: "--separator", label: "Separator", category: "border"},
+  {name: "--focus", label: "Focus", category: "border"},
+] as const;
+
+export type ColorVariable = (typeof COLOR_VARIABLES)[number];
diff --git a/packages/storybook/.storybook/welcome.mdx b/packages/storybook/.storybook/welcome.mdx
new file mode 100644
index 0000000..aca8f04
--- /dev/null
+++ b/packages/storybook/.storybook/welcome.mdx
@@ -0,0 +1,124 @@
+import {Meta} from "@storybook/addon-docs/blocks";
+import {buttonVariants} from "@heroui/react";
+
+<Meta title="Welcome" />
+
+<br />
+
+# Welcome 👋🏼
+
+<br />
+
+## HeroUI Version 3 - Design system
+
+<div className="max-w-xl text-base! text-foreground! [&>p]:text-base [&>p]:text-foreground">
+  Here you can find the guidelines, components APIs and examples to help you build your next project
+  with HeroUI version 3.
+</div>
+
+<div className="flex flex-col gap-8">
+  <div className="flex flex-row justify-start items-center mt-8 gap-4">
+    <a
+      href="https://heroui.com"
+      target="_blank"
+      className={buttonVariants({
+        variant: "primary",
+      })}
+    >
+      <span className="[&>p]:text-white! [&>p]:font-semibold!">
+       Website
+      </span>
+      <svg
+        aria-hidden="true"
+        className="flex stroke-current text-white! self-center"
+        fill="none"
+        height="1em"
+        shapeRendering="geometricPrecision"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.5"
+        viewBox="0 0 24 24"
+        width="1em"
+      >
+        <path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6" />
+        <path d="M15 3h6v6" />
+        <path d="M10 14L21 3" />
+      </svg>
+    </a>
+    <a
+      href="https://github.com/heroui-inc/heroui"
+      target="_blank"
+      className={buttonVariants({
+        variant: "secondary",
+        className: "[&>p]:font-semibold!",
+      })}
+    >
+      Github
+      <svg
+        aria-hidden="true"
+        className="flex stroke-current self-center"
+        fill="none"
+        height="1em"
+        shapeRendering="geometricPrecision"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.5"
+        viewBox="0 0 24 24"
+        width="1em"
+      >
+        <path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6" />
+        <path d="M15 3h6v6" />
+        <path d="M10 14L21 3" />
+      </svg>
+    </a>
+    <a
+      href="https://discord.gg/9b6yyZKmH4"
+      target="_blank"
+      className={buttonVariants({
+        variant: "secondary",
+        className: "[&>p]:font-semibold!",
+      })}
+    >
+      Discord
+      <svg
+        aria-hidden="true"
+        className="flex stroke-current self-center"
+        fill="none"
+        height="1em"
+        shapeRendering="geometricPrecision"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="1.5"
+        viewBox="0 0 24 24"
+        width="1em"
+      >
+        <path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6" />
+        <path d="M15 3h6v6" />
+        <path d="M10 14L21 3" />
+      </svg>
+    </a>
+  </div>
+
+  <div className="flex items-center gap-2">
+    <img src="/logo-dark.svg" style={{width: "120px", height: "auto"}} />
+  </div>
+</div>
+
+<br />
+
+export const currentDate = new Date();
+
+export const isoDate = currentDate.toISOString().split("T")[0];
+
+export const formattedDate = currentDate.toLocaleDateString("en-US", {
+  month: "short",
+  day: "numeric",
+  year: "numeric",
+});
+
+<div className="[&>p]:text-default-400 block text-xs">
+  Last updated on <time dateTime={isoDate}>{formattedDate}</time>
+</div>
diff --git a/packages/storybook/eslint.config.mjs b/packages/storybook/eslint.config.mjs
new file mode 100644
index 0000000..9789f16
--- /dev/null
+++ b/packages/storybook/eslint.config.mjs
@@ -0,0 +1,11 @@
+import baseReactConfig from "@heroui/standard/eslint/react.mjs";
+import {defineConfig} from "eslint/config";
+
+const config = defineConfig([
+  ...baseReactConfig,
+  {
+    ignores: ["storybook-static/**", "storybook-static"],
+  },
+]);
+
+export default config;
diff --git a/packages/storybook/package.json b/packages/storybook/package.json
new file mode 100644
index 0000000..49ebf3a
--- /dev/null
+++ b/packages/storybook/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@heroui/storybook",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "storybook dev --host 127.0.0.1 --port 6006 --no-open",
+    "build": "storybook build",
+    "start": "storybook start",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@gravity-ui/icons": "2.16.0",
+    "@heroui/react": "workspace:*",
+    "@heroui/styles": "workspace:*",
+    "@iconify/react": "6.0.2",
+    "apcach": "0.6.4",
+    "culori": "4.0.2",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "react-aria-components": "1.19.0",
+    "react-scan": "0.4.3",
+    "tailwind-variants": "^3.2.2"
+  },
+  "devDependencies": {
+    "@heroui/standard": "workspace:*",
+    "@storybook/addon-a11y": "10.1.10",
+    "@storybook/addon-docs": "10.1.10",
+    "@storybook/icons": "2.0.1",
+    "@storybook/react": "10.1.10",
+    "@storybook/react-vite": "10.1.10",
+    "@tailwindcss/postcss": "4.3.0",
+    "@tailwindcss/vite": "4.3.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "5.1.2",
+    "glob": "13.0.0",
+    "postcss": "8.5.6",
+    "storybook": "10.1.10",
+    "tailwindcss": "4.3.0",
+    "vite": "7.3.0"
+  }
+}
diff --git a/packages/storybook/postcss.config.mjs b/packages/storybook/postcss.config.mjs
new file mode 100644
index 0000000..c2ddf74
--- /dev/null
+++ b/packages/storybook/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
diff --git a/packages/storybook/public/favicon.svg b/packages/storybook/public/favicon.svg
new file mode 100644
index 0000000..697d352
--- /dev/null
+++ b/packages/storybook/public/favicon.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="544" height="544" viewBox="0 0 544 544"><image width="544" height="544" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiAAAAIgCAYAAAC8idIcAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAABlZSURBVHgB7d0/f1NpdgfwA7vFdsu8ghXddni6dLG7dGHKVGvKVJhqS0yVpAK6dNhduoEqSYXmFeDp0vnuK8B0SeXoWL4gPLIsS/c+un++38/nsWRZBns+HvTzOed57oOgKZNbbh9dr/THhfs3P7bqsVV/H8DYVVs8Z/Hxi9n6snB/cS0+VgVbexCskkFgcr3q+39auP8o1g8MAAxLFd/CSN7+LeYB5Sy+BZWLYCkBZG4yW3vXt08W7gsWAGxjMZD8en2/ur4dtTEGkAwVT+Nb0NgLQQOAsupgkuuX+BZMRmMMASTDxf5s/X3Mg8ckAKB76kDyYbamMfD2zVADSIaOw9n6x5iHDwDom+lsnV7fVjEwQwogdaXjeQgdAAzLNOZh5CQGYggBJINHho6jMMsBwLBVMQ8jr6LnVZE+B5D92fpLzFstADA2J9HjINLHADKZrdcxHygFgLE7iR4GkYfRH9leyeBxHsIHANQOY/7a+C56tNPzd9EPL2frP8JwKQDcJs+1yl/Q8xf2X6Ljut6C2Y+eJToA6IBqtp7FfGC1k7ragqnbLR9D+ACA+5rE/DW0s7/Ed7EFsz9b/zlb/xAAwDbqtkxe5bdT15/pUgDJqse/zNa/h/M8AKAp9TXQ8va/oyO6MgMyCe0WAGhbNVsH0YEtu12YAcnDxD6F8AEAbZvE/DX3KHZs1y2YHDT919n6QwAAJeRrbj1nubPturtqwWQf6udwrgcA7NI05tt1qyhsFwFkEuY9AKArqtjBXEjpGZDcDiR8AEB3TGL+2rwXBZWsgNThwxZbAOiei5hXQoqcF1KqAlLvdBE+AKCb8jU6X6v/EgWU2AWT38hJAAB9kIeWVbP1a7So7QAifABA/7QeQtqcAcmZj08BAPTVj9HSTEhbMyD1wCkA0F+t7Y5powIyCVttAWAoqmjhnJCmA8gkhA8AGJoq5u2Yi2hI0y2YdyF8AMDQTGJ+CZXGNLkL5uVsHQYAMESTmJ8V8t/RgKYCyPOYX9UWABiuv4uGtuc2MQMyCaecAsBY5BxIzoNUsYUmAsh5mPsAgDGpYsuh1G1bMK9n6x8CABiT7Hr8IbaYB9mmAnIY810vAMA45fkg09jApgFkEs77AICxq2LDVsymLZhsvewHADBmG7diNqmA7IfrvAAA39y7FbNJALHrBQBYVM3W4/t8wn1bMHna6dMAAPgmWzFZ1Jiu+wn3qYBMwuApALBcDqI+jjUHUu9TATF4CgDc5g9xj4HUdSsgk5jPfgAArJJVkOquJz2M9bwMAIC7vV7nSetUQCah+gEArO/ObbnrVEBUPwCA+/jLXU+4qwIyCdUPAOD+fogVO2Lu2gWTfZy9AAC4n/+LFW2YuyogTj0FADax8lyQVTMghyF8AACbydNR92/74KoAcucACQDACs9v+8BtLZhJGD4FALa3dBj1tgrIfgAAbO9w2YO3BRDtFwCgCf+47MFlLZgcGvkcAADN+E0bZlkFZD8AAJqzf/OBZQFkaakEAGBD+zcfWBZAnHwKADTpN8WNmzMgk7D9FgBo3ndzIDcrIKofAEAbni6+czOA7AcAQPO+K3LcDCBPAgCged9ljJszIHn+x6MAAGhWzn/8UL+zWAHJ0ojwAQC0ITPGpH5nMYBMAgCgPV/nQB4uexAAoAWT+s5iADGACgC06WvWWAwg5j8AgDZ97bYs7oKxAwYAaNPXnTB1BeRRCB8AQLu+5o06gEwCAKB9k3yzWAEBAGjbJN/UAcQWXACghO9aMCogAEAJk3xjBgQAKOlP+ebh4jsAAC37bhsuAEAJ31VAJgEA0L6rudP6JNTLAABo39VpqAIIAFDag2zBTAIAoJxJBhBngAAARQkgAEBpE9twAYDiVEAAgNLMgAAA5QkgAEBpjwQQAKC0R4ZQAYDiVEAAgNK0YACA4v6oBQMAFCeAAADFZQD5UwAAlPODCggAUJoZEACgPAEEAChOAAEAihNAAIDSrg4imwQAQDmuBQMAlCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUNyD2boMAICCVEAAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQIBGPHr0KI6OjuLjx4/x+fPnuLy8/Lo+ffoU7969i/39/QBID2brMgA2lMHj+fPnV+Ej79+lqqr46aef4uzsLIBxu7Qsy9pkzSoal+fn55ebePnyZa++V8uyml0qIMC9TSaTRloqJycn8ezZswDG53ezdRwAa8gWy1//+ter4PDnP/85trW3t3d1+8svvwQwLiogwFqy2pFVj6x+NO3g4CCm02kA42EXDLBSBo7c2ZKrjfCRXr58GcC4CCDAUtluyWBwfn7e+vbZ/PNt0YVxEUCA33j69OnV2R3Hx8dRigAC4/L7ALjW1O6WTdQDqcA4qIAARdstt3ny5EkA46ECAiOX7ZbXr1+3NmAKsIwAAiO1y3YLgBYMjEwX2i0AKiAwIoeHh1ftlnUuGgfQJgEERiB3mGTwUPEAukILBgYsKx0ZPPJMD+ED6BIVEBgo7RagywQQGBjtFqAPtGBgILRbgD5RAYEB0G4B+kYAgR7TbgH6SgsGeki7Beg7FRDomefPn8fx8bF2C9BrAgj0RFY68gh1FQ9gCAQQ6Lj62i1HR0cBMBQCCHSYdgswVAIIdJB2CzB0Agh0iHYLMBYCCHSEdgswJgII7Jh2CzBGAgjsiHYLMGYCCOyAdgswdgIIFKTdAjAngEAB2i0A3xNAoGXaLQC/JYBAS7RbAG4ngEDDtFsA7iaAQIO0WwDWI4BAA7LN8vr169jb2wsA7iaAwBay0pHB4/DwMABY38MANpLtlvPzc+EDYAMqIHBP2i0A2xNAYE3aLQDN0YKBNWi3ADRLBQRW0G4BaIcKCCwxmUzi3bt38fHjR+EDoAUqIHBDfYqpw8QA2iOAwLVst2TVI6sf0AUZgrMClyvvX1xcRFVVcXZ2dnULfXdpWWNes8Bx+fPPP1+yW+fn5736uWlzzcLw5az9t/K/16dPny4PDw8vm/x7Lavw6tUXa1mNrlm75fLz58+X7J4AMg/DdwWPZf/dMrD06fu0rOvVqy/WshpZ+Q92/sNNd4w5gMzaK1uH4fz8Pn3PlhU9+2Ita6ul3dJdYw0gTYbho6OjXn3v1riXbbiMRu5umfXN4+nTpwG7lsPOszB8tdW7qcHnPLMmh6mhD+yCYfDsbqFr2tzqnT/rjx8/Dug6FRAGKwNH/nbZ5G+YsI0Mw3mk//HxcWvnzOTPuioffSCAMDj5D3vdblGOpgvyZ7Lpdssqee0i6DotGAZFu4WuyTDQZsVjmcWDy6CrVEAYBO0WuibDcFbh3rx5U/xY//z7/H9A1wkg9Jp2C12TP5NduJChAELXacHQW9otdM0u2i23cTFFuk4AoXfqgT4VD7oifxazEudnEtYngNAr9ayHqgddULcA80wP4H4EEHpD+KBLutRugT4SQOiNbLsIH+yadgs0QwChFw4PD3e6owC0W6BZAgi9kP/ww65kAM4LvWm3QHMEEDovS91aL+xCVt1cYRba4SAyOs+FtSgtKx0ZPBxwB+1RAaHznjx5ElBKBt484E67BdolgNB5XggoIdt8GTxUPKAMLRg6TwChTfXulvPzc+EDClIBAUYr2y0562HIGcoTQIDR0W6B3RNAgNHIdkseoZ6HiWntwW4JIMAoZLUjqx7aLdANAggwaNot0E0CCDBI2i3QbQIIMDjaLdB9zgEBBiMDx88//xwfP34UPqDjVECAQcjDxLRboD8EEKDXtFugn7RggF7SboF+E0CA3sndLZ8+fbo6Sh3oJy0YoDey3ZLXbtnb2wug3wQQoPNysDSDx+HhYQDDoAUDdFq2W87Pz4UPGBgVEKCTst2SW2sdoQ7DJIAAnZLtlvpMD2C4BBCgM7Ldcnx87DAxGAEBBNi56XQap6enVweKAeNgCBXYmYuLi3jx4kUcHBxchRBgPFRAgJ14+/btVbslQwgwPgIIUFRWOrLqcXZ2FsB4CSBAEXW75eTkJAAEEKB1r169ijdv3mi3AF8JIEBrst3y7NmzqKoqABYJIEDjMnBk8LCzBbiNAAI0JlssubtFuwW4iwACNEK7BbgPAQTYinYLsAkBBNiIdguwDQEEuLf3799fnemh3QJsSgAB1qbdAjTFxeiAO2WLJQ8Te/z4sfABNEIFBFgpj07Pdos5D6BJKiDAUlnpODg4uGq5CB9A01RAgO/U7Zbc3QLQFgEE+Cq31R4fH6t4AK0TQICrdktWPQyYAqUIIDBi2i3ArgggMFLaLcAu2QUDI5RVj6OjI+ED2BkBBEYmw0dWPgB2SQCBEclruAgfQBcIIDAieaIpQBcIIDASeaS6q9cCXSGAwEicnp4GQFcIIDACudvFIWNAlwggMAJnZ2cB0CUCCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnABC511cXAQAwyKA0Hm//vprADAsAgidd3Z2FgAMiwBC552cnAQAwyKA0Hk5AzKdTgOA4RBA6IVnz54ZRgUYEAGEXqiqKl69ehUADIMAQm+8efNGCAEYCAGEXjk+PhZCAAZAAKF3MoQ8fvz4qi0DQD8JIPRSho8MIaohAP0kgNBrdTXk9PQ0AOgPAYTey2rI4eHh1VZdbRmAfhBAGIw8MfXg4EA1BKAHBBAGpa6GGFIF6DYBhEEypArQbQIIg2ZIFaCbBBAGz5AqQPcIIIyGIVWA7hBAGBVDqgDdIIAwSoZUAXZLAGHUDKkC7IYAwugZUgUoTwCBa4ZUAcoRQGCBIVWAMgQQWGJxSPXi4iIAaJYAAivkkOqPP/6oLQPQMAEE7mBIFaB5AgisqR5Sffv2bQCwHQEE7iErIEdHR4ZUAbYkgMAGDKkCbEcAgS0YUgXYjAACWzKkCnB/Agg0xJAqwPoEEGiQIVWA9Qgg0AJDqgCrCSDQoq4MqarGAF0jgEDLujCk+uXLlwDoEgEECtnlkOrZ2VkAdIkAAgXtakh1Op0GQJcIILADJYdUP3z4YAYE6BwBBHaoxJBqVlwAukYAgR1rc0g1501UP4AuEkCgI5oeUs3BU9UPoKsEEOiQpoZUc+g0wwxAVwkg0EH1kOqLFy/uNaSaz83PyfDhBFagywQQ6LA3b958HVJdVRHJsJE7ajK05OcAdN3vA+i0ekg17e3txWQyubqtP5azHg4aA/pGAIEeqcPG+/fvA6DPtGAAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABAIoTQACA4gQQAKA4AQQAKE4AAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoTgABGKCqqgK6TAABGKCLi4uALhNAAAYmw8fZ2VlAlwkgAAPz/v37gK4TQAAG5vT0NKDrBBCAAZlOp1cLuk4AARiInP149uxZQB8IIAADkeHD9lv6QgAB6Lm68mH4lD75fQDQWznvofJBH6mAAPRQVj1evHgRBwcHwge9pAIC0DNv376N4+Njp53SawIIQE/k6aZZ9bDNliEQQAA6LisdddUDhkIAAegwQ6YMlQAC0EEZODJ4aLcwVHbBAHTMq1ev4scffxQ+GDQVEICOyMCRQ6Y5bApDpwICsGOLZ3oIH4yFCgjADjnTg7ESQAB2wJApY6cFA1BQVjpyyPTx48fCB6OmAgJQiDM94BsBBKBl2i3wW1owAC3KIVNnesBvqYAAtMCZHrCaCghAg5zpAetRAQFoyMnJyVX4cKYH3E0AAdiSIVO4Py0YgA050wM2pwICsAFnesB2VEAA7iEDx08//XQ1ZCp8wOYEEIA11Wd6vH//PoDtaMEA3CHbLTnrYc4DmiOAANyiHjJ98+ZNAM0SQACWcKYHtEsAAVjgTA8oQwABOmHXlYb8+3PINNstqh7QvgezdRkAHfD58+d49OhRlOZMDyjPNlygM0pfvC0rHc70gN0QQIDO+PDhQ5SS7ZY8Qt2ZHrAbWjBAZ2T75fz8vNU2jDM9oBtUQIDOqAdB2/qzc1tttluED9g9FRCgU7L68enTp5hMJtGUbLPkkKndLdAdAgjQORk+MoRs24pxpgd0lxYM0DkZHPKib5vuTKmPUM8/Q/iA7rq0LMvq4ppVQi5PTk4u7+Pjx49Xn9en79OyRrp69cValjXCVQeRz58/Lw0d+XgGj/39/V59X5Y15mUGBOiVvb29qxmRej4kDy/LVo0BU+gXAQQAKM4QKgBQnAACABQngAAAxQkgAEBxAggAUJwAAgAUJ4AAAMUJIABAcQIIAFCcAAIAFCeAAADFCSAAQHECCABQnAACABQngAAAxQkgAEBxGUCqAAAop1IBAQCKE0AAgOIEEACgOAEEAChOAAEAihNAAIDiBBAAoDgBBAAoLgPIRQAAlFMJIABAcVowAEBxAggAUJwAAgAUZwYEACguA8iXAAAop9KCAQCKE0AAgOLMgAAApX0RQACA0i60YACA4lRAAIDSLgQQAKA0LRgAoLirAFIFAEA5KiAAQHkqIABAaSogAEBxFw+u71wGAEAZD+oKiK24AEAxAggAUFKVbwQQAKCkKt88XHwHAKCEOoB8CQCA9lX5RgUEACjpb/lGAAEASrqaOzWECgCUdJZvVEAAgJK+q4BUAQDQvirfLLZgtGEAgDZ9zRuLF6OrAgCgPWf1ncUA8msAALTn67ljiwHkLAAA2rO0AlIFAEB7lgYQFRAAoE1VfefBjQ98nq1HAQDQrNz98kP9zsMbH1QFAQDa8F3GuBlA7IQBANrwXcZQAQEASpguvnNzBiTnPz4HAECzHsfCEOrNCshF2I4LADQrOyzV4gMPlzzpQwAANOc3Ix7LAsg0AACa85vixoMlTzIHAgA0Kc//uFh8YFkFJJ8wDQCA7U3jRvhID295sjkQAKAJp8sefHDLk7VhAIAmfLf9tnZbBUQbBgDY1jRuOd7j4YpPehsAAJs7ve0DD1Z8UrZhzsPVcQGA+6ti3n5ZalUFJNswqiAAwCamqz64qgKSDKMCAJtYOnxaW1UBSVkFOQ0AgPWdxB3XlrurApL2Z+tjAACsZ2X1I91VAUnT2XofAAB3O4k7wkdapwKSJjHfEQMAsMqd1Y+0TgUkrv8gO2IAgFVOYo3wkdatgCTnggAAt6lm6yDWDCDrVkCSc0EAgNvkrtlq3SffpwJSyyrIJAAA5qpYcerpMvepgNSeBQDAN/fOBr+L+6tm64fZ+rsAAMbuJDYY0dikBZNyEPVTaMUAwJhVcY/B00WbtGBSDqRqxQDAuL2KDcJH2qQFU6tCKwYAxirbLv8aG9q0BVPTigGA8aninrtebtq0BVPLVszB9S0AMHz1a/9Wtg0gqZqtFwEAjMHGcx+LtpkBWXQW5kEAYOgyfGw897Fo2xmQmz7O1n4AAEMzjQZaL7WmA4ihVAAYnio2PO/jNk3MgCyqB1OqAACGoIoWXtubroDU9mLejnkUAEBf1YWFs2hYWwEkZQj5FABAX/0YLYSP1HQLZlF+wY5rB4B+ytfwVsJHamob7m3yC//bbD0NAKAvMnycRIvaDiBJCAGA/mg9fKQ2Z0BuMpgKAN3V2sDpMm3OgNyU35AtugDQPVUUDB+pZAWkNol5JWQSAMCuVbGDAkHJCkitivk3Og0AYJemMd9qW0VhJYZQl8k+02nMKzD7AQCU9na2/mm2/jd2YFcBpDadrS8xv4ruHwIAaFsWAf45Grqq7aZ2MQOyzCTMhQBA26royIaQXcyALFPN1uOYl4MAgObla+xO5j2W2XUL5qb/ivmhZXlmiPNCAGB71Wz9NFv/Hjua91imawEk5R7kD7P1Q8yDCACwmXrQ9H+iY7oyA3Kb/dl6F2ZDAOA+qpgfqT6NjupiBWRRFfP0lkFpEtoyALBK7nD5t5i3XKrosK4HkNo0tGUAYJX8hT2Dx39FD3S9BbPMZLaOZ+svAQC8n60X0bNrrfUxgNQmIYgAMF4nMT9VfBo91OcAUpvEPIj8fRhWBWDYcsYjWy1vru/31hACyKLDmFdE9gMAhmMa8+CRt70OHrWhBZDaJOYhRBgBoK+mMd+AcRIDCR2LhhpAFuXW3f3ZejpbT8IuGgC6qYp54JjGgCodtxlDALlpEvMQsh/fAonzRQAoKcNFnvz96/Xt+xh44LhpjAFkmQwhk+vbDCWPQjABYHsZKqr4Fjbq+3k7agLIahlAJvF9IPlTfNttMwk7bwDG6GJhVde3f1u4Xy3cZwkBpDmTmAeUumry6MaqH/vjjc+57c9a5+8DYL1qQh0WVj32ZeH9xY9Vt9yyhf8HN0L9g51rDFEAAAAASUVORK5CYII="></image><style>@media (prefers-color-scheme: light) { :root { filter: none; } }
+@media (prefers-color-scheme: dark) { :root { filter: invert(100%); } }
+</style></svg>
\ No newline at end of file
diff --git a/packages/storybook/public/logo-dark.svg b/packages/storybook/public/logo-dark.svg
new file mode 100644
index 0000000..8e086df
--- /dev/null
+++ b/packages/storybook/public/logo-dark.svg
@@ -0,0 +1,7 @@
+<svg width="275" height="84" viewBox="0 0 275 84" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 20.9484V46.0463C0 47.2326 0.609876 48.335 1.61325 48.9623L18.7276 59.6627C21.0083 61.0887 23.9623 59.4432 23.9623 56.7468V35.65C23.9623 34.4362 24.6006 33.3125 25.6413 32.6939L36.081 26.489V80.5589C36.081 83.2462 39.0172 84.8932 41.2985 83.4855L58.9629 72.5851C59.976 71.9599 60.5932 70.852 60.5932 69.6585V17.7361C60.5932 15.0618 57.6826 13.4129 55.4006 14.7942L36.081 26.489V3.44098C36.081 0.773993 33.1845 -0.876045 30.9022 0.490798L1.66918 17.9982C0.633988 18.6182 0 19.7387 0 20.9484Z" fill="#18181B"/>
+<path d="M125.354 46.1061C125.354 38.9888 122.442 35.7039 116.616 35.7039C109.945 35.7039 105.247 40.175 105.247 50.2123V73.2067H93.2203V9.33333H105.247V32.6927C108.16 27.9479 112.952 25.5754 119.529 25.5754C130.71 25.5754 137.287 32.419 137.287 43.9162V73.2067H125.354V46.1061Z" fill="#18181B"/>
+<path d="M167.054 74.6667C152.114 74.6667 142.625 64.9944 142.625 50.121C142.625 35.4302 152.021 25.5754 167.054 25.5754C183.309 25.5754 192.141 37.0726 189.698 53.2235H154.651C155.309 60.8883 159.819 65.2682 167.054 65.2682C172.973 65.2682 176.544 62.257 177.483 59.2458H189.416C187.537 68.1881 179.269 74.6667 167.054 74.6667ZM154.933 45.2849H178.047C177.953 38.9888 173.819 34.7002 166.772 34.7002C160.477 34.7002 156.061 38.3501 154.933 45.2849Z" fill="#18181B"/>
+<path d="M196.257 38.7151C196.257 31.1415 200.485 27.0354 208.566 27.0354H223.975V36.8901H208.284V73.2067H196.257V38.7151Z" fill="#18181B"/>
+<path d="M250.289 74.6667C235.067 74.6667 225.389 64.9032 225.389 50.121C225.389 35.3389 235.067 25.5754 250.289 25.5754C265.322 25.5754 275 35.3389 275 50.121C275 64.9032 265.322 74.6667 250.289 74.6667ZM250.289 64.7207C257.805 64.7207 262.785 58.9721 262.785 50.121C262.785 41.27 257.805 35.4302 250.289 35.4302C242.678 35.4302 237.698 41.27 237.698 50.121C237.698 58.9721 242.678 64.7207 250.289 64.7207Z" fill="#18181B"/>
+</svg>
diff --git a/packages/storybook/public/logo-light.svg b/packages/storybook/public/logo-light.svg
new file mode 100644
index 0000000..5f3d001
--- /dev/null
+++ b/packages/storybook/public/logo-light.svg
@@ -0,0 +1,7 @@
+<svg width="275" height="84" viewBox="0 0 275 84" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 20.9484V46.0463C0 47.2326 0.609876 48.335 1.61325 48.9623L18.7276 59.6627C21.0083 61.0887 23.9623 59.4432 23.9623 56.7468V35.65C23.9623 34.4362 24.6006 33.3125 25.6413 32.6939L36.081 26.489V80.5589C36.081 83.2462 39.0172 84.8932 41.2985 83.4855L58.9629 72.5851C59.976 71.9599 60.5932 70.852 60.5932 69.6586V17.7361C60.5932 15.0618 57.6826 13.4129 55.4006 14.7942L36.081 26.489V3.44098C36.081 0.773993 33.1845 -0.876045 30.9022 0.490798L1.66918 17.9982C0.633988 18.6182 0 19.7387 0 20.9484Z" fill="white"/>
+<path d="M125.354 46.1061C125.354 38.9888 122.442 35.7039 116.616 35.7039C109.945 35.7039 105.247 40.175 105.247 50.2123V73.2067H93.2203V9.33333H105.247V32.6927C108.16 27.9479 112.952 25.5754 119.529 25.5754C130.71 25.5754 137.287 32.419 137.287 43.9162V73.2067H125.354V46.1061Z" fill="white"/>
+<path d="M167.054 74.6667C152.114 74.6667 142.625 64.9944 142.625 50.121C142.625 35.4302 152.021 25.5754 167.054 25.5754C183.309 25.5754 192.141 37.0726 189.698 53.2235H154.651C155.309 60.8883 159.819 65.2682 167.054 65.2682C172.973 65.2682 176.544 62.257 177.483 59.2458H189.416C187.537 68.1881 179.269 74.6667 167.054 74.6667ZM154.933 45.2849H178.047C177.953 38.9888 173.819 34.7002 166.772 34.7002C160.477 34.7002 156.061 38.3501 154.933 45.2849Z" fill="white"/>
+<path d="M196.257 38.7151C196.257 31.1415 200.485 27.0354 208.566 27.0354H223.975V36.8901H208.284V73.2067H196.257V38.7151Z" fill="white"/>
+<path d="M250.289 74.6667C235.067 74.6667 225.389 64.9032 225.389 50.121C225.389 35.3389 235.067 25.5754 250.289 25.5754C265.322 25.5754 275 35.3389 275 50.121C275 64.9032 265.322 74.6667 250.289 74.6667ZM250.289 64.7207C257.805 64.7207 262.785 58.9721 262.785 50.121C262.785 41.27 257.805 35.4302 250.289 35.4302C242.678 35.4302 237.698 41.27 237.698 50.121C237.698 58.9721 242.678 64.7207 250.289 64.7207Z" fill="white"/>
+</svg>
diff --git a/packages/storybook/styles/globals.css b/packages/storybook/styles/globals.css
new file mode 100644
index 0000000..a0420b1
--- /dev/null
+++ b/packages/storybook/styles/globals.css
@@ -0,0 +1,80 @@
+@import "@heroui/styles";
+
+@source "../../react/src/components/**/*.{ts,tsx,js,jsx}";
+
+/* Important: This source is important to make sure storybook styles are compiled */
+
+/* Custom theme overrides - Just use CSS! */
+:root {
+  /* Your values */
+  /* --radius: 2.5rem; */
+  /* --spacing: 0.1rem; */
+  /* font-size: 20px; */
+
+  /* --accent: oklch(0.5671 0.209451 257.9449); */
+  /* Use OS-native cursor for interactive elements (macOS style) */
+  --cursor-interactive: pointer;
+
+  /* theme.css */
+
+  /* variables.css */
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  /* Overrides light theme field tokens */
+  /* --field-background: var(--color-neutral-200);
+  --field-foreground: var(--foreground);
+  --field-placeholder: var(--color-neutral-500);
+  --field-border: var(--border);
+  --field-border-width: 0px;
+  --field-radius: calc(var(--radius) * 0.75);
+  --field-shadow: none; */
+
+  /* Way to make components and text bigger on mobile - a11y */
+  /* @media (max-width: 640px) {
+    font-size: 24px;
+  } */
+}
+
+[data-theme="light"],
+.light {
+  /* --background: #f9f9f9; */
+  /* --skeleton-animation: none; */ /* possible values: shimmer, pulse, none */
+}
+
+/* Dark theme overrides using data-theme or class */
+[data-theme="dark"],
+.dark {
+  /* Your values */
+  /* --radius: 0.5rem; */
+  /* --cursor: default; */
+
+  --cursor-interactive: pointer;
+}
+
+/* @theme inline { */
+/* Radius */
+/* --radius-xs: calc(var(--radius) * 0.25);
+  --radius-sm: calc(var(--radius) * 0.5);
+  --radius-md: calc(var(--radius) * 0.75);
+  --radius-lg: calc(var(--radius) * 1);
+  --radius-xl: calc(var(--radius) * 1.5);
+  --radius-2xl: calc(var(--radius) * 2);
+  --radius-3xl: calc(var(--radius) * 3);
+  --radius-4xl: calc(var(--radius) * 4);
+} */
+
+/* @utility button {
+  @apply rounded-lg;
+} */
+
+@theme inline {
+  /* --color-field-focus: var(--color-neutral-300); */
+}
+
+body {
+  background-color: var(--background);
+}
diff --git a/packages/storybook/tsconfig.json b/packages/storybook/tsconfig.json
new file mode 100644
index 0000000..3889525
--- /dev/null
+++ b/packages/storybook/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@heroui/standard/tsconfig/react.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "preserve"
+  },
+  "include": [".storybook", "vite.config.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/storybook/vite.config.ts b/packages/storybook/vite.config.ts
new file mode 100644
index 0000000..7622e4b
--- /dev/null
+++ b/packages/storybook/vite.config.ts
@@ -0,0 +1,11 @@
+import {default as tailwindcss} from "@tailwindcss/vite";
+import {default as react} from "@vitejs/plugin-react";
+import {defineConfig} from "vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  optimizeDeps: {
+    include: ["@mdx-js/react"],
+    exclude: ["sb-vite"],
+  },
+});
diff --git a/packages/styles/CHANGELOG.md b/packages/styles/CHANGELOG.md
new file mode 100644
index 0000000..765bf72
--- /dev/null
+++ b/packages/styles/CHANGELOG.md
@@ -0,0 +1,13 @@
+# @heroui/styles
+
+## 3.0.1
+
+### Patch Changes
+
+- README updated
+
+## 3.0.0
+
+### Patch Changes
+
+- v3.0.0
diff --git a/packages/styles/README.md b/packages/styles/README.md
new file mode 100644
index 0000000..8a818d5
--- /dev/null
+++ b/packages/styles/README.md
@@ -0,0 +1,265 @@
+# @heroui/styles
+
+The core HeroUI styles package containing CSS files for components, themes, and utilities. This package provides the foundation for HeroUI's design system using Tailwind CSS v4 and is framework-agnostic.
+
+## Documentation
+
+It's the [heroui.com](https://heroui.com) website for the latest version of HeroUI.
+
+- **Latest (v3)**: [https://heroui.com](https://heroui.com)
+- **v2**: [https://v2.heroui.com](https://v2.heroui.com)
+
+## Installation
+
+```bash
+npm install @heroui/styles
+# or
+pnpm add @heroui/styles
+# or
+yarn add @heroui/styles
+```
+
+## Usage
+
+### Basic Setup
+
+Import the HeroUI styles in your main CSS file:
+
+```css
+@import "@heroui/styles";
+```
+
+This will import:
+
+- Tailwind CSS base styles
+- HeroUI component styles
+- HeroUI utilities
+- Default theme variables
+- Animation utilities from tw-animate-css
+
+### Package Structure
+
+The package exports CSS files organized into:
+
+```
+@heroui/styles/
+├── index.css          # Main entry point
+├── base/              # Base styles and CSS variables
+│   └── base.css       # Layout tokens, typography, scrollbar
+├── components/        # Component-specific styles
+│   ├── accordion.css
+│   ├── avatar.css
+│   ├── button.css
+│   ├── chip.css
+│   ├── link.css
+│   ├── popover.css
+│   └── tooltip.css
+├── themes/            # Theme definitions
+│   ├── default/       # Default theme
+│   │   ├── index.css  # Theme entry point
+│   │   └── variables.css  # Theme variables (light/dark)
+│   └── shared/        # Shared theme utilities
+│       └── theme.css  # Calculated variables and utilities
+└── utilities/         # Utility classes
+    ├── backdrop.css
+    └── index.css
+```
+
+### Importing Specific Components
+
+Instead of importing everything, you can import only what you need:
+
+```css
+/* Import Tailwind CSS base */
+@import "tailwindcss";
+
+/* Import only specific components */
+@import "@heroui/styles/components/button.css" layer(components);
+@import "@heroui/styles/components/chip.css" layer(components);
+
+/* Import theme */
+@import "@heroui/styles/themes/default" layer(base);
+```
+
+### Component Classes
+
+Components use a BEM-like naming convention:
+
+- Base: `.button`
+- Variants: `.button--primary`, `.button--danger`
+- Sizes: `.button--sm`, `.button--lg`
+- Modifiers: `.button--icon-only`
+
+#### Button Example
+
+```html
+<!-- Basic button -->
+<button class="button">Click me</button>
+
+<!-- Primary variant -->
+<button class="button button--primary">Save</button>
+
+<!-- Small size -->
+<button class="button button--sm">Small</button>
+
+<!-- Icon-only button -->
+<button class="button button--icon-only">
+  <svg>...</svg>
+</button>
+
+<!-- Combining classes -->
+<button class="button button--primary button--sm">Small Primary</button>
+```
+
+### Themes
+
+The default theme provides automatic light/dark mode support:
+
+- **Light mode**: Applied by default to `:root`
+- **Dark mode**: Applied with `.dark` class or `[data-theme="dark"]` attribute
+
+```html
+<!-- Dark mode with class -->
+<html class="dark">
+  <!-- Dark mode with data attribute -->
+  <html data-theme="dark"></html>
+</html>
+```
+
+### CSS Variables
+
+The package provides a comprehensive set of CSS variables for customization:
+
+#### Layout Tokens
+
+```css
+:root {
+  /* Spacing */
+  --spacing: 0.25rem;
+
+  /* Border */
+  --border-width: 0px; /* no border by default */
+  --field-border-width: var(--border-width);
+  --disabled-opacity: 0.5;
+
+  /* Radius */
+  --radius: 0.5rem;
+  --field-radius: calc(var(--radius) * 1.5);
+
+  /* Ring offset - Used for focus ring */
+  --ring-offset-width: 2px;
+
+  /* Cursor */
+  --cursor-interactive: pointer;
+  --cursor-disabled: not-allowed;
+}
+```
+
+#### Theme Colors
+
+```css
+:root {
+  /* Primitive Colors (Do not change between light and dark) */
+  --white: oklch(100% 0 0);
+  --black: oklch(0% 0 0);
+  --snow: oklch(0.9911 0 0);
+  --eclipse: oklch(0.2103 0.0059 285.89);
+
+  /* Base Colors */
+  --background: oklch(0.9702 0 0);
+  --foreground: var(--eclipse);
+
+  /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+  --surface: var(--white);
+  --surface-foreground: var(--foreground);
+
+  /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
+  --overlay: var(--white);
+  --overlay-foreground: var(--foreground);
+
+  --muted: oklch(0.5517 0.0138 285.94);
+  --scrollbar: oklch(87.1% 0.006 286.286);
+
+  --default: oklch(94% 0.001 286.375);
+  --default-foreground: var(--eclipse);
+
+  /* Interactive Colors */
+  --accent: oklch(0.6204 0.195 253.83);
+  --accent-foreground: var(--snow);
+
+  /* Status Colors */
+  --success: oklch(0.7329 0.1935 150.81);
+  --success-foreground: var(--eclipse);
+
+  --warning: oklch(0.7819 0.1585 72.33);
+  --warning-foreground: var(--eclipse);
+
+  --danger: oklch(0.6532 0.2328 25.74);
+  --danger-foreground: var(--snow);
+
+  /* Component Colors */
+  --segment: var(--white);
+  --segment-foreground: var(--eclipse);
+
+  /* UI Colors */
+  --border: oklch(0 0 0 / 0%);
+  --separator: oklch(92% 0.004 286.32);
+  --focus: var(--accent);
+  --link: var(--foreground);
+
+  /* Shadows */
+  --surface-shadow:
+    0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+  --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
+  --field-shadow:
+    0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
+}
+```
+
+**Note**: Dark mode overrides specific variables (like `--background`, `--surface`, `--overlay`, `--muted`, `--scrollbar`, `--default`, `--warning`, `--danger`, `--segment`, `--separator`, and shadow values) when `.dark` class or `[data-theme="dark"]` attribute is applied.
+
+#### Field Tokens
+
+```css
+:root {
+  /* Form field defaults */
+  --field-background: var(--white);
+  --field-foreground: oklch(0.2103 0.0059 285.89);
+  --field-placeholder: var(--muted);
+  --field-border: transparent; /* no border by default on form fields */
+  --field-border-width: var(--border-width);
+  --field-radius: calc(var(--radius) * 1.5);
+}
+```
+
+Providing any of these knobs automatically updates the generated utilities (`bg-field`, `placeholder:text-field-placeholder`, `rounded-field`, etc.) along with the calculated hover/focus variants.
+
+#### Calculated Variables
+
+The theme also provides calculated variables for hover states, soft colors, and surface levels (defined in `themes/shared/theme.css`):
+
+- **Hover states**: `--color-accent-hover`, `--color-success-hover`, `--color-warning-hover`, `--color-danger-hover`, `--color-default-hover`
+- **Soft colors**: `--color-accent-soft`, `--color-danger-soft`, `--color-warning-soft`, `--color-success-soft` (with their foreground and hover variants)
+- **Surface levels**: `--color-surface-secondary`, `--color-surface-tertiary`
+- **Radius scale**: `--radius-xs` through `--radius-4xl` (calculated from `--radius`)
+- **Transition timing functions**: Various easing curves like `--ease-smooth`, `--ease-out-fuild`, etc.
+
+## Dependencies
+
+- **Tailwind CSS v4+**: Required peer dependency
+- **tw-animate-css**: Provides animation utilities
+
+## Build Output
+
+The package provides:
+
+- `index.css`: Main unminified CSS file
+- `heroui.min.css`: Minified production-ready CSS (generated during build)
+
+## Framework Integration
+
+This package is designed to work with any framework. For React-specific components, use `@heroui/react` which builds on top of these core styles.
+
+## License
+
+MIT
diff --git a/packages/styles/base/base.css b/packages/styles/base/base.css
new file mode 100644
index 0000000..df198b3
--- /dev/null
+++ b/packages/styles/base/base.css
@@ -0,0 +1,31 @@
+/*
+ * Scrollbar styles
+ *
+ * TODO: This is a temporary workaround by removing the scrollbar styles.
+ * Global scrollbar styling causes modal/overlay interaction/closure issues
+ * (e.g. backdrop clicks not closing the overlay) and should be removed.
+ */
+/*
+*:not(.alert-dialog__backdrop):not(.modal__backdrop) {
+  scrollbar-color: var(--scrollbar) transparent;
+  scrollbar-width: thin;
+}
+*/
+
+/* Border color inheritance */
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  border-color: var(--border, currentColor);
+}
+
+/* Keeps main page content interactive during view transitions */
+:root {
+  view-transition-name: none;
+}
+
+::view-transition {
+  pointer-events: none;
+}
diff --git a/packages/styles/base/scrollbar.css b/packages/styles/base/scrollbar.css
new file mode 100644
index 0000000..52f27ca
--- /dev/null
+++ b/packages/styles/base/scrollbar.css
@@ -0,0 +1,30 @@
+/* =============================================================================
+ * HeroUI scrollbar system
+ *
+ * Modes via data-scrollbar on any ancestor:
+ *   (unset) — HeroUI scrollbar from theme --scrollbar-width/color/gutter (light/dark)
+ *   thin    — HeroUI themed thin scrollbar, useful for overriding inherited default mode
+ *   default — OS / browser scrollbar (auto)
+ *   none    — hidden (inherited to descendants using @apply scrollbar)
+ *
+ * Each scroll container applies @apply scrollbar | scrollbar-thin | scrollbar-none | scrollbar-default
+ * in its own component CSS file.
+ * ============================================================================= */
+
+[data-scrollbar="thin"] {
+  --scrollbar-width: thin;
+  --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+  --scrollbar-gutter: auto;
+}
+
+[data-scrollbar="default"] {
+  --scrollbar-width: auto;
+  --scrollbar-color: auto;
+  --scrollbar-gutter: auto;
+}
+
+[data-scrollbar="none"] {
+  --scrollbar-width: none;
+  --scrollbar-color: auto;
+  --scrollbar-gutter: auto;
+}
diff --git a/packages/styles/bundle-size.json b/packages/styles/bundle-size.json
new file mode 100644
index 0000000..59c9ce9
--- /dev/null
+++ b/packages/styles/bundle-size.json
@@ -0,0 +1,252 @@
+{
+  "timestamp": "2025-12-28T21:05:44.088Z",
+  "uncompressed": {
+    "bytes": 544,
+    "kb": 0.531,
+    "formatted": "544 B"
+  },
+  "minified": {
+    "bytes": 249668,
+    "kb": 243.816,
+    "formatted": "243.82 KB"
+  },
+  "componentsTotal": {
+    "bytes": 131299,
+    "kb": 128.222,
+    "formatted": "128.22 KB"
+  },
+  "components": {
+    "accordion.css": {
+      "bytes": 3180,
+      "kb": 3.105
+    },
+    "alert-dialog.css": {
+      "bytes": 6099,
+      "kb": 5.956
+    },
+    "alert.css": {
+      "bytes": 1156,
+      "kb": 1.129
+    },
+    "avatar.css": {
+      "bytes": 1481,
+      "kb": 1.446
+    },
+    "breadcrumbs.css": {
+      "bytes": 513,
+      "kb": 0.501
+    },
+    "button-group.css": {
+      "bytes": 1447,
+      "kb": 1.413
+    },
+    "button.css": {
+      "bytes": 3539,
+      "kb": 3.456
+    },
+    "card.css": {
+      "bytes": 873,
+      "kb": 0.853
+    },
+    "checkbox-group.css": {
+      "bytes": 93,
+      "kb": 0.091
+    },
+    "checkbox.css": {
+      "bytes": 9206,
+      "kb": 8.99
+    },
+    "chip.css": {
+      "bytes": 2026,
+      "kb": 1.979
+    },
+    "close-button.css": {
+      "bytes": 1431,
+      "kb": 1.397
+    },
+    "combo-box.css": {
+      "bytes": 3844,
+      "kb": 3.754
+    },
+    "date-field.css": {
+      "bytes": 358,
+      "kb": 0.35
+    },
+    "date-input-group.css": {
+      "bytes": 4891,
+      "kb": 4.776
+    },
+    "description.css": {
+      "bytes": 102,
+      "kb": 0.1
+    },
+    "disclosure-group.css": {
+      "bytes": 158,
+      "kb": 0.154
+    },
+    "disclosure.css": {
+      "bytes": 1127,
+      "kb": 1.101
+    },
+    "dropdown.css": {
+      "bytes": 2942,
+      "kb": 2.873
+    },
+    "empty-state.css": {
+      "bytes": 80,
+      "kb": 0.078
+    },
+    "error-message.css": {
+      "bytes": 347,
+      "kb": 0.339
+    },
+    "field-error.css": {
+      "bytes": 409,
+      "kb": 0.399
+    },
+    "fieldset.css": {
+      "bytes": 258,
+      "kb": 0.252
+    },
+    "header.css": {
+      "bytes": 269,
+      "kb": 0.263
+    },
+    "input-group.css": {
+      "bytes": 5803,
+      "kb": 5.667
+    },
+    "input-otp.css": {
+      "bytes": 3862,
+      "kb": 3.771
+    },
+    "input.css": {
+      "bytes": 3079,
+      "kb": 3.007
+    },
+    "kbd.css": {
+      "bytes": 576,
+      "kb": 0.563
+    },
+    "label.css": {
+      "bytes": 785,
+      "kb": 0.767
+    },
+    "link.css": {
+      "bytes": 2795,
+      "kb": 2.729
+    },
+    "list-box-item.css": {
+      "bytes": 2773,
+      "kb": 2.708
+    },
+    "list-box-section.css": {
+      "bytes": 254,
+      "kb": 0.248
+    },
+    "list-box.css": {
+      "bytes": 437,
+      "kb": 0.427
+    },
+    "menu-item.css": {
+      "bytes": 3694,
+      "kb": 3.607
+    },
+    "menu-section.css": {
+      "bytes": 248,
+      "kb": 0.242
+    },
+    "menu.css": {
+      "bytes": 389,
+      "kb": 0.38
+    },
+    "modal.css": {
+      "bytes": 6249,
+      "kb": 6.103
+    },
+    "number-field.css": {
+      "bytes": 5725,
+      "kb": 5.591
+    },
+    "popover.css": {
+      "bytes": 1941,
+      "kb": 1.896
+    },
+    "radio-group.css": {
+      "bytes": 2074,
+      "kb": 2.025
+    },
+    "radio.css": {
+      "bytes": 4250,
+      "kb": 4.15
+    },
+    "scroll-shadow.css": {
+      "bytes": 2559,
+      "kb": 2.499
+    },
+    "search-field.css": {
+      "bytes": 4716,
+      "kb": 4.605
+    },
+    "select.css": {
+      "bytes": 6101,
+      "kb": 5.958
+    },
+    "separator.css": {
+      "bytes": 1632,
+      "kb": 1.594
+    },
+    "skeleton.css": {
+      "bytes": 1156,
+      "kb": 1.129
+    },
+    "slider.css": {
+      "bytes": 3706,
+      "kb": 3.619
+    },
+    "spinner.css": {
+      "bytes": 557,
+      "kb": 0.544
+    },
+    "surface.css": {
+      "bytes": 313,
+      "kb": 0.306
+    },
+    "switch-group.css": {
+      "bytes": 289,
+      "kb": 0.282
+    },
+    "switch.css": {
+      "bytes": 5515,
+      "kb": 5.386
+    },
+    "tabs.css": {
+      "bytes": 3876,
+      "kb": 3.785
+    },
+    "tag-group.css": {
+      "bytes": 299,
+      "kb": 0.292
+    },
+    "tag.css": {
+      "bytes": 4155,
+      "kb": 4.058
+    },
+    "textfield.css": {
+      "bytes": 458,
+      "kb": 0.447
+    },
+    "textarea.css": {
+      "bytes": 3159,
+      "kb": 3.085
+    },
+    "time-field.css": {
+      "bytes": 358,
+      "kb": 0.35
+    },
+    "tooltip.css": {
+      "bytes": 1687,
+      "kb": 1.647
+    }
+  }
+}
diff --git a/packages/styles/clean-package.config.json b/packages/styles/clean-package.config.json
new file mode 100644
index 0000000..a516c1d
--- /dev/null
+++ b/packages/styles/clean-package.config.json
@@ -0,0 +1,37 @@
+{
+  "remove": ["devDependencies", "scripts", "clean-package"],
+  "replace": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "style": "./dist/index.css",
+    "browser": "./dist/heroui.min.css",
+    "sideEffects": ["*.css"],
+    "exports": {
+      ".": {
+        "style": "./dist/index.css",
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./css": {
+        "style": "./dist/index.css",
+        "default": "./dist/index.css"
+      },
+      "./components/*": {
+        "types": "./dist/components/*/index.d.ts",
+        "import": "./dist/components/*/index.js",
+        "default": "./dist/components/*/index.js"
+      },
+      "./base": "./dist/base/base.css",
+      "./base/*.css": "./dist/base/*.css",
+      "./components/*.css": "./dist/components/*.css",
+      "./themes/default": "./dist/themes/default/index.css",
+      "./themes/*/*.css": "./dist/themes/*/*.css",
+      "./themes/*.css": "./dist/themes/*.css",
+      "./utilities": "./dist/utilities/index.css",
+      "./variants": "./dist/variants/index.css",
+      "./package.json": "./package.json"
+    }
+  },
+  "backupPath": ".package.json.backup"
+}
diff --git a/packages/styles/components/accordion.css b/packages/styles/components/accordion.css
new file mode 100644
index 0000000..4f18f44
--- /dev/null
+++ b/packages/styles/components/accordion.css
@@ -0,0 +1,152 @@
+/* Base accordion styles */
+.accordion {
+  @apply w-full;
+
+  /* Performance optimization - contain layout changes */
+  contain: layout style;
+}
+
+/* Accordion elements */
+.accordion__body {
+  @apply text-sm;
+}
+
+.accordion__body-inner {
+  @apply px-4 pt-0 pb-4 text-muted;
+}
+
+.accordion__heading {
+  @apply flex;
+}
+
+.accordion__indicator {
+  @apply ml-auto size-4 shrink-0 text-muted;
+
+  /**
+   * Transitions
+   */
+  @apply transition duration-250 motion-reduce:transition-none;
+
+  /* Expanded state for indicator rotation */
+  &[data-expanded="true"] {
+    @apply -rotate-180;
+  }
+}
+
+/* Accordion Item - Separator styles */
+.accordion__item {
+  @apply relative border-none;
+}
+
+.accordion__item::after {
+  content: "";
+  @apply absolute bottom-0 left-0 h-px w-full rounded-xs bg-separator;
+}
+
+.accordion__item:last-child::after {
+  content: none;
+}
+
+/* Hide separator when hideSeparator prop is set */
+.accordion__item[data-hide-separator="true"]::after {
+  display: none;
+}
+/* ------------------------------------ */
+
+.accordion__trigger {
+  cursor: var(--cursor-interactive);
+
+  /* Base Styles */
+  @apply flex flex-1 items-center justify-between px-4 py-4 text-left text-sm font-medium no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    opacity 150ms var(--ease-out),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not([aria-expanded="true"]),
+    &[data-hovered="true"]:not([aria-expanded="true"]) {
+      background-color: color-mix(in oklab, var(--foreground) 3%, transparent 90%);
+    }
+  }
+
+  /* Pressed state */
+  &[data-pressed="true"]:not([aria-expanded="true"]) {
+  }
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled State */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.accordion__panel {
+  opacity: 0;
+  height: var(--disclosure-panel-height);
+  overflow: clip;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    height 200ms var(--ease-out-quad),
+    opacity 200ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  &[data-expanded="true"] {
+    will-change: height, opacity;
+    opacity: 1;
+  }
+}
+
+/* Surface variant */
+.accordion--surface {
+  @apply bg-surface;
+  border-radius: min(32px, var(--radius-3xl));
+
+  .accordion__trigger {
+    @media (hover: hover) {
+      &:hover:not([aria-expanded="true"]),
+      &[data-hovered="true"]:not([aria-expanded="true"]) {
+        @apply bg-default;
+      }
+    }
+  }
+
+  .accordion__item::after {
+    @apply bg-surface-foreground/6;
+  }
+}
+
+.accordion--surface .accordion__item {
+  /* Surface variant separator styling */
+  &::after {
+    @apply left-[3%] w-[94%];
+  }
+
+  /* Special rounding for first and last items in surface variant */
+  &:first-child [data-slot="accordion-trigger"] {
+    border-top-left-radius: min(32px, var(--radius-3xl));
+    border-top-right-radius: min(32px, var(--radius-3xl));
+  }
+
+  &:last-child:not(:has([data-slot="accordion-trigger"][aria-expanded="true"]))
+    [data-slot="accordion-trigger"] {
+    border-bottom-left-radius: min(32px, var(--radius-3xl));
+    border-bottom-right-radius: min(32px, var(--radius-3xl));
+  }
+}
diff --git a/packages/styles/components/alert-dialog.css b/packages/styles/components/alert-dialog.css
new file mode 100644
index 0000000..644d380
--- /dev/null
+++ b/packages/styles/components/alert-dialog.css
@@ -0,0 +1,314 @@
+/* -------------------------------------------------------------------------------------------------
+ * AlertDialog Component Styles
+ * Block: alert-dialog
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Element: trigger - the element that opens the modal
+ */
+.alert-dialog__trigger {
+  @apply inline-block;
+  @apply cursor-(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Active/pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.97);
+  }
+}
+
+/**
+ * Element: backdrop - the overlay behind the dialog
+ */
+.alert-dialog__backdrop {
+  @apply fixed inset-0 z-50;
+  @apply flex flex-row items-center justify-center;
+  @apply h-(--visual-viewport-height) w-full;
+
+  /* Entering animation */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-out fade-in-0;
+  }
+
+  /* Exiting animation */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-out fade-out-0;
+  }
+
+  /**
+   * Reduce Animation
+   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
+   */
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply will-change-[opacity];
+    @apply motion-reduce:animate-none;
+  }
+}
+
+/**
+ * Modifier: backdrop--transparent
+ */
+.alert-dialog__backdrop--transparent {
+  @apply bg-transparent;
+}
+
+/**
+ * Modifier: backdrop--opaque
+ */
+.alert-dialog__backdrop--opaque {
+  @apply bg-backdrop;
+}
+
+/**
+ * Modifier: backdrop--blur
+ */
+.alert-dialog__backdrop--blur {
+  @apply bg-backdrop backdrop-blur-md;
+}
+
+/**
+ * Element: container - the positioning wrapper for the modal
+ */
+.alert-dialog__container {
+  @apply flex flex-col items-center;
+  @apply h-(--visual-viewport-height) w-full min-w-0 flex-1;
+  @apply p-4;
+  @apply sm:w-fit sm:p-10;
+  @apply pointer-events-none;
+
+  /* Entering animation */
+  &[data-entering="true"] {
+    @apply animate-in duration-250 ease-out-quad fade-in-0 zoom-in-105;
+
+    &[data-placement="auto"] {
+      @apply slide-in-from-bottom-1;
+      @apply sm:slide-in-from-bottom-0;
+    }
+
+    &[data-placement="top"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="center"] {
+      @apply slide-in-from-top-0;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-bottom-1;
+    }
+  }
+
+  /* Exiting animation */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-out-quad fade-out-0 zoom-out-95;
+  }
+
+  /**
+   * Reduce Animation
+   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
+   */
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply will-change-[opacity,transform];
+    @apply motion-reduce:animate-none;
+  }
+}
+
+/**
+ * Element: dialog - the content container for the modal
+ */
+.alert-dialog__dialog {
+  @apply relative;
+  @apply flex min-h-0 w-full flex-col;
+  @apply max-h-full;
+  @apply bg-overlay shadow-overlay outline-none;
+  border-radius: min(32px, var(--radius-3xl));
+  @apply p-6;
+  @apply overflow-clip;
+  @apply pointer-events-auto;
+
+  &[data-placement="auto"] {
+    @apply mt-auto;
+    @apply sm:my-auto;
+  }
+
+  &[data-placement="center"] {
+    @apply my-auto;
+  }
+
+  &[data-placement="bottom"] {
+    @apply mt-auto;
+  }
+
+  &[data-placement="top"] {
+    @apply mt-0;
+  }
+}
+
+/**
+ * Modifier: dialog--xs
+ */
+.alert-dialog__dialog--xs {
+  @apply max-w-xs;
+}
+
+/**
+ * Modifier: dialog--sm
+ */
+.alert-dialog__dialog--sm {
+  @apply max-w-sm;
+}
+
+/**
+ * Modifier: dialog--md
+ */
+.alert-dialog__dialog--md {
+  @apply max-w-md;
+}
+
+/**
+ * Modifier: dialog--lg
+ */
+.alert-dialog__dialog--lg {
+  @apply max-w-lg;
+}
+
+/**
+ * Modifier: dialog--cover
+ */
+.alert-dialog__dialog--cover {
+  @apply h-full min-h-full w-full;
+}
+
+/**
+ * Element: header - the top section with the title
+ */
+.alert-dialog__header {
+  @apply flex flex-col gap-3;
+  @apply mb-0;
+
+  /* When header contains icon, use flex-col layout with gap */
+  & > .modal__icon {
+    @apply mb-0;
+  }
+}
+
+/**
+ * Element: heading - the main title text
+ */
+.alert-dialog__heading {
+  @apply align-middle;
+  @apply text-base font-medium text-foreground;
+}
+
+/**
+ * Element: icon - the optional icon indicator
+ */
+.alert-dialog__icon {
+  @apply flex items-center justify-center;
+  @apply size-10 shrink-0;
+  @apply rounded-3xl select-none;
+
+  [data-slot="alert-dialog-default-icon"] {
+    @apply box-content size-5;
+  }
+}
+
+/**
+ * Modifier: icon--default
+ */
+.alert-dialog__icon--default {
+  @apply bg-default text-foreground;
+}
+
+/**
+ * Modifier: icon--accent
+ */
+.alert-dialog__icon--accent {
+  @apply bg-accent-soft text-accent-soft-foreground;
+}
+
+/**
+ * Modifier: icon--success
+ */
+.alert-dialog__icon--success {
+  @apply bg-success-soft text-success-soft-foreground;
+}
+
+/**
+ * Modifier: icon--warning
+ */
+.alert-dialog__icon--warning {
+  @apply bg-warning-soft text-warning-soft-foreground;
+}
+
+/**
+ * Modifier: icon--danger
+ */
+.alert-dialog__icon--danger {
+  @apply bg-danger-soft text-danger-soft-foreground;
+}
+
+/**
+ * Element: body - the main content area
+ */
+.alert-dialog__body {
+  @apply min-h-0 flex-1 scrollbar;
+  @apply text-sm leading-[1.43] text-muted;
+  @apply -m-[3px] my-0 p-[3px];
+  @apply overflow-y-auto overscroll-contain;
+  -webkit-overflow-scrolling: touch;
+}
+
+/**
+ * Element: footer - the bottom action section
+ */
+.alert-dialog__footer {
+  @apply flex flex-row items-center justify-end gap-2;
+  @apply mt-0;
+}
+
+/**
+ * Element: close-trigger - the optional x icon button to close the modal
+ */
+.alert-dialog__close-trigger {
+  @apply absolute top-4 right-4;
+}
+
+/**
+ * Elements Spacing
+ */
+.alert-dialog__header + .alert-dialog__body {
+  @apply mt-2;
+}
+
+.alert-dialog__header + .alert-dialog__footer {
+  @apply mt-5;
+}
+
+.alert-dialog__body + .alert-dialog__footer {
+  @apply mt-5;
+}
diff --git a/packages/styles/components/alert.css b/packages/styles/components/alert.css
new file mode 100644
index 0000000..3c63ecd
--- /dev/null
+++ b/packages/styles/components/alert.css
@@ -0,0 +1,69 @@
+/* Alert component styles */
+
+/* Base alert styles */
+.alert {
+  @apply flex w-full flex-row items-start justify-start gap-4 bg-surface px-4 py-3 shadow-surface;
+  border-radius: min(32px, var(--radius-3xl));
+}
+
+/* Alert elements */
+.alert__content {
+  @apply flex h-full grow flex-col items-start;
+}
+
+.alert__indicator {
+  @apply flex items-center justify-center p-1 select-none;
+
+  [data-slot="alert-default-icon"] {
+    @apply box-content size-4;
+  }
+}
+
+.alert__title {
+  @apply text-sm leading-6 font-medium;
+}
+
+.alert__description {
+  @apply text-sm text-muted;
+}
+
+/* Variant modifiers */
+.alert--default .alert__indicator {
+  @apply text-foreground;
+}
+
+.alert--default .alert__title {
+  @apply text-foreground;
+}
+
+.alert--accent .alert__indicator {
+  @apply text-accent-soft-foreground;
+}
+
+.alert--accent .alert__title {
+  @apply text-accent-soft-foreground;
+}
+
+.alert--success .alert__indicator {
+  @apply text-success-soft-foreground;
+}
+
+.alert--success .alert__title {
+  @apply text-success-soft-foreground;
+}
+
+.alert--warning .alert__indicator {
+  @apply text-warning-soft-foreground;
+}
+
+.alert--warning .alert__title {
+  @apply text-warning-soft-foreground;
+}
+
+.alert--danger .alert__indicator {
+  @apply text-danger-soft-foreground;
+}
+
+.alert--danger .alert__title {
+  @apply text-danger-soft-foreground;
+}
diff --git a/packages/styles/components/autocomplete.css b/packages/styles/components/autocomplete.css
new file mode 100644
index 0000000..fb82bc2
--- /dev/null
+++ b/packages/styles/components/autocomplete.css
@@ -0,0 +1,289 @@
+/* Autocomplete styles */
+.autocomplete {
+  @apply flex flex-col gap-1;
+}
+
+.autocomplete__trigger {
+  @apply relative isolate inline-flex min-h-9 rounded-field border bg-field px-3 py-2 text-sm text-field-foreground shadow-field outline-none select-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /* Add inline-end padding when indicator is present */
+  &:has(.autocomplete__indicator) {
+    @apply pe-7;
+  }
+
+  /* Hover state - exclude when clear button is hovered to prevent double hover effect */
+  @media (hover: hover) {
+    &:hover:not(:has(.autocomplete__clear-button:hover)),
+    &[data-hovered="true"]:not(:has(.autocomplete__clear-button:hover)) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  /* Invalid state */
+  .autocomplete[data-invalid="true"] &,
+  .autocomplete[aria-invalid="true"] & {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* Variant property definitions */
+.autocomplete--primary {
+  /* Default styles */
+}
+
+.autocomplete--secondary .autocomplete__trigger {
+  @apply shadow-none;
+  background-color: var(--autocomplete-trigger-bg);
+
+  --autocomplete-trigger-bg: var(--default);
+  --autocomplete-trigger-bg-hover: var(--default-hover);
+  --autocomplete-trigger-bg-focus: var(--default);
+
+  /* Exclude when clear button is hovered to prevent double hover effect */
+  @media (hover: hover) {
+    &:hover:not(:has(.autocomplete__clear-button:hover)),
+    &[data-hovered="true"]:not(:has(.autocomplete__clear-button:hover)) {
+      background-color: var(--autocomplete-trigger-bg-hover);
+    }
+  }
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    background-color: var(--autocomplete-trigger-bg-focus);
+  }
+
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  .autocomplete[data-invalid="true"] &,
+  .autocomplete[aria-invalid="true"] & {
+    background-color: var(--autocomplete-trigger-bg-focus);
+  }
+}
+
+.autocomplete__value {
+  @apply flex-1 text-start text-base wrap-break-word text-current sm:text-sm;
+
+  &[data-placeholder="true"] {
+    @apply text-field-placeholder;
+  }
+
+  /* Removes the list-box-item indicator element from the autocomplete value*/
+  [data-slot="list-box-item-indicator"] {
+    @apply hidden;
+  }
+}
+
+.autocomplete__indicator {
+  @apply absolute inset-y-0 end-2 my-auto flex shrink-0 items-center justify-center text-field-placeholder transition duration-150;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  &[data-open="true"] {
+    @apply rotate-180;
+  }
+
+  &[data-slot="autocomplete-default-indicator"] {
+    @apply size-4;
+  }
+}
+
+/* Similar to popover content styles */
+.autocomplete__popover {
+  @apply w-(--trigger-width) max-w-(--trigger-width) origin-(--trigger-anchor-point) scroll-py-1 overflow-hidden overscroll-contain bg-overlay p-0 pt-2 text-sm;
+  border-radius: min(32px, var(--radius-3xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-250 ease-out-fluid fade-in-0 zoom-in-95;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-out-quad zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="popover-overlay-arrow"] {
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="popover-overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="popover-overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="popover-overlay-arrow"] {
+    rotate: 90deg;
+  }
+
+  /* Listbox styles */
+  [data-slot="list-box"] {
+    @apply max-h-[320px] scrollbar overflow-y-auto p-1.5 outline-none;
+  }
+
+  [data-slot="list-box-item"] {
+    @apply px-2.5;
+  }
+
+  /* Virtualized rows: react-aria's Virtualizer wraps each row in an absolutely-positioned
+   * [role="presentation"] element whose width equals the scroll container's clientWidth
+   * (which includes the list-box horizontal padding) while sitting inside the padded content
+   * box. Without this, rows overflow the right padding and the hover background reaches the
+   * popover edge. Subtract the horizontal padding (2 × p-1.5 = 12px) to keep rows aligned. */
+  [role="presentation"] > [data-slot="list-box-item"] {
+    width: calc(100% - var(--spacing) * 3);
+  }
+
+  /* As the popover closes fast in single-select mode, the default item indicator transition is not even visible - so we disable it only for single-select */
+  [data-slot="list-box"]:not([aria-multiselectable="true"]) [data-slot="list-box-item-indicator"],
+  [data-slot="list-box"]:not([aria-multiselectable="true"])
+    [data-slot="list-box-item-indicator"]
+    [data-slot="list-box-item-indicator--checkmark"] {
+    @apply transition-none;
+  }
+
+  /* Search Field styles */
+  [data-slot="search-field"] {
+    @apply px-3 py-1 outline-none;
+  }
+
+  /* Empty State */
+  [data-slot="empty-state"] {
+    @apply text-center text-sm text-overlay-foreground/60;
+  }
+}
+
+/* Popover dialog — mirrors Popover.Dialog focus management without a visible focus ring */
+.autocomplete__popover-dialog {
+  @apply outline-none;
+
+  &:focus,
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+}
+
+/* Full width modifier */
+.autocomplete--full-width {
+  @apply w-full;
+}
+
+.autocomplete__trigger--full-width {
+  @apply w-full;
+}
+
+/* Clear Button styles */
+.autocomplete__clear-button {
+  @apply relative isolate inline-flex h-6 w-6 shrink-0 origin-center items-center justify-center rounded-xl p-1 text-muted select-none no-highlight;
+  @apply me-0 size-5 shrink-0 self-center bg-transparent;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  @apply transform-gpu;
+
+  /* Transition only when visible - disappears immediately when cleared */
+  &:not([data-empty="true"]) {
+    transition: opacity 150ms var(--ease-smooth);
+    @apply motion-reduce:transition-none;
+  }
+
+  &[data-empty="true"] {
+    @apply pointer-events-none opacity-0;
+  }
+
+  [data-slot="autocomplete-clear-button-icon"] {
+    @apply size-3.5;
+  }
+
+  &:active,
+  &[data-pressed="true"] {
+  }
+
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default-hover;
+    }
+  }
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.93);
+  }
+}
diff --git a/packages/styles/components/avatar.css b/packages/styles/components/avatar.css
new file mode 100644
index 0000000..dd2c079
--- /dev/null
+++ b/packages/styles/components/avatar.css
@@ -0,0 +1,82 @@
+/* Base avatar styles */
+.avatar {
+  @apply relative flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-3xl bg-default;
+}
+
+/* Avatar fallback element */
+.avatar__fallback {
+  @apply flex size-full items-center justify-center bg-default text-sm font-medium;
+}
+
+/* Avatar image element */
+.avatar__image {
+  @apply absolute inset-0 aspect-square size-full;
+
+  /**
+   * Transitions
+   */
+  @apply transition-opacity duration-250 motion-reduce:transition-none;
+}
+
+/* Size modifiers */
+.avatar--sm {
+  @apply size-8 rounded-2xl;
+}
+
+.avatar--md {
+  /* No styles as this is the default size */
+}
+
+.avatar--lg {
+  @apply size-12 rounded-3xl;
+
+  .avatar__fallback {
+    @apply text-base;
+  }
+}
+
+/* Color modifiers for fallback */
+.avatar__fallback--accent {
+  @apply text-accent-soft-foreground;
+}
+
+.avatar__fallback--default {
+  @apply text-default-soft-foreground;
+}
+
+.avatar__fallback--success {
+  @apply text-success-soft-foreground;
+}
+
+.avatar__fallback--warning {
+  @apply text-warning-soft-foreground;
+}
+
+.avatar__fallback--danger {
+  @apply text-danger-soft-foreground;
+}
+
+/* Variant modifiers */
+.avatar--soft {
+  @apply bg-transparent;
+}
+
+.avatar--soft .avatar__fallback--accent {
+  @apply bg-accent-soft text-accent-soft-foreground;
+}
+
+.avatar--soft .avatar__fallback--success {
+  @apply bg-success-soft text-success-soft-foreground;
+}
+
+.avatar--soft .avatar__fallback--warning {
+  @apply bg-warning-soft text-warning-soft-foreground;
+}
+
+.avatar--soft .avatar__fallback--default {
+  @apply bg-default-soft text-default-soft-foreground;
+}
+
+.avatar--soft .avatar__fallback--danger {
+  @apply bg-danger-soft text-danger-soft-foreground;
+}
diff --git a/packages/styles/components/badge.css b/packages/styles/components/badge.css
new file mode 100644
index 0000000..2784de1
--- /dev/null
+++ b/packages/styles/components/badge.css
@@ -0,0 +1,166 @@
+/* ==========================================================================
+   Badge - Small informational badges for displaying labels, statuses, and categories.
+   ========================================================================== */
+
+/* Base styles */
+.badge {
+  @apply inline-flex shrink-0 items-center justify-center gap-0.5 font-medium;
+
+  /* Default size (matches --md) */
+  @apply min-h-7 min-w-7 rounded-3xl text-xs leading-[1.34];
+
+  /* Default tokens */
+  --badge-bg: var(--default);
+  --badge-fg: var(--default-foreground);
+  --badge-border: var(--background);
+
+  background-color: var(--badge-bg);
+  color: var(--badge-fg);
+  border: 1px solid var(--badge-border);
+}
+
+.badge__label {
+  @apply px-0.5;
+}
+
+.badge-anchor {
+  @apply relative inline-flex shrink-0;
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.badge--lg {
+  @apply min-h-8 min-w-8 rounded-2xl text-sm leading-[1.43];
+}
+
+.badge--md {
+  /* No styles as this is the default size */
+}
+
+.badge--sm {
+  @apply min-h-4 min-w-4 rounded-xl text-[10px] leading-[1.34];
+}
+
+/* ==========================================================================
+   Color variants - set foreground color
+   ========================================================================== */
+
+.badge--accent {
+  --badge-fg: var(--accent-soft-foreground);
+}
+
+.badge--default {
+  --badge-fg: var(--default-foreground);
+}
+
+.badge--success {
+  --badge-fg: var(--success-soft-foreground);
+}
+
+.badge--warning {
+  --badge-fg: var(--warning-soft-foreground);
+}
+
+.badge--danger {
+  --badge-fg: var(--danger-soft-foreground);
+}
+
+/* ==========================================================================
+   Variant styles
+   ========================================================================== */
+
+.badge--primary {
+  /* Solid background - compound variants below handle bg/fg per color */
+}
+
+.badge--secondary {
+  /* Default background with colored text - base behavior */
+}
+
+.badge--soft {
+  /* Soft/muted background - compound variants below handle bg/fg per color */
+}
+
+/* ==========================================================================
+   Placement variants
+   ========================================================================== */
+
+.badge--top-right {
+  @apply absolute top-0 right-0;
+  transform: translate(25%, -25%);
+}
+
+.badge--top-left {
+  @apply absolute top-0 left-0;
+  transform: translate(-25%, -25%);
+}
+
+.badge--bottom-right {
+  @apply absolute right-0 bottom-0;
+  transform: translate(25%, 25%);
+}
+
+.badge--bottom-left {
+  @apply absolute bottom-0 left-0;
+  transform: translate(-25%, 25%);
+}
+
+/* ==========================================================================
+   Compound variants - Primary (solid background)
+   ========================================================================== */
+
+.badge--primary.badge--accent {
+  --badge-bg: var(--accent);
+  --badge-fg: var(--accent-foreground);
+}
+
+.badge--primary.badge--default {
+  --badge-bg: var(--default);
+  --badge-fg: var(--default-foreground);
+}
+
+.badge--primary.badge--success {
+  --badge-bg: var(--success);
+  --badge-fg: var(--success-foreground);
+}
+
+.badge--primary.badge--warning {
+  --badge-bg: var(--warning);
+  --badge-fg: var(--warning-foreground);
+}
+
+.badge--primary.badge--danger {
+  --badge-bg: var(--danger);
+  --badge-fg: var(--danger-foreground);
+}
+
+/* ==========================================================================
+   Compound variants - Soft (muted background)
+   ========================================================================== */
+
+.badge--soft.badge--accent {
+  --badge-bg: var(--accent-soft);
+  --badge-fg: var(--accent-soft-foreground);
+}
+
+.badge--soft.badge--default {
+  --badge-bg: var(--default-soft);
+  --badge-fg: var(--default-soft-foreground);
+}
+
+.badge--soft.badge--success {
+  --badge-bg: var(--success-soft);
+  --badge-fg: var(--success-soft-foreground);
+}
+
+.badge--soft.badge--warning {
+  --badge-bg: var(--warning-soft);
+  --badge-fg: var(--warning-soft-foreground);
+}
+
+.badge--soft.badge--danger {
+  --badge-bg: var(--danger-soft);
+  --badge-fg: var(--danger-soft-foreground);
+}
diff --git a/packages/styles/components/breadcrumbs.css b/packages/styles/components/breadcrumbs.css
new file mode 100644
index 0000000..c7a38a4
--- /dev/null
+++ b/packages/styles/components/breadcrumbs.css
@@ -0,0 +1,28 @@
+/* Base breadcrumbs container */
+.breadcrumbs {
+  @apply flex items-center;
+
+  /* Breadcrumb link */
+  .breadcrumbs__link {
+    @apply relative px-0.5 text-sm leading-5 font-medium text-muted no-underline opacity-100;
+
+    &:hover,
+    &[data-hovered="true"] {
+      @apply underline;
+    }
+
+    &[data-current="true"] {
+      @apply text-link opacity-100;
+    }
+  }
+
+  /* Breadcrumb item wrapper */
+  .breadcrumbs__item {
+    @apply flex shrink-0 items-center justify-center gap-0.5 px-0.5;
+  }
+
+  /* Separator icon */
+  .breadcrumbs__separator {
+    @apply size-3 text-muted rtl:rotate-180;
+  }
+}
diff --git a/packages/styles/components/button-group.css b/packages/styles/components/button-group.css
new file mode 100644
index 0000000..55828aa
--- /dev/null
+++ b/packages/styles/components/button-group.css
@@ -0,0 +1,145 @@
+/* ==========================================================================
+   ButtonGroup - Groups related buttons together
+   ========================================================================== */
+
+/* Base button group styles */
+.button-group {
+  @apply inline-flex h-auto items-center justify-center gap-0;
+}
+
+/* ==========================================================================
+   Orientation variants
+   ========================================================================== */
+
+.button-group--horizontal {
+  @apply flex-row;
+}
+
+.button-group--vertical {
+  @apply flex-col;
+}
+
+/* Remove border radius from all buttons in group */
+.button-group .button {
+  @apply rounded-none;
+}
+
+/* Apply border radius to first button (start edge) */
+.button-group--horizontal .button:first-child {
+  @apply rounded-s-3xl;
+}
+
+/* Apply border radius to last button (end edge) */
+.button-group--horizontal .button:last-child {
+  @apply rounded-e-3xl;
+}
+
+/* If only one button, apply both rounded edges */
+.button-group--horizontal .button:first-child:last-child {
+  @apply rounded-3xl;
+}
+
+/* Apply border radius to first button (top edge) in vertical */
+.button-group--vertical .button:first-child {
+  @apply rounded-t-3xl;
+}
+
+/* Apply border radius to last button (bottom edge) in vertical */
+.button-group--vertical .button:last-child {
+  @apply rounded-b-3xl;
+}
+
+/* If only one button in vertical, apply all rounded edges */
+.button-group--vertical .button:first-child:last-child {
+  @apply rounded-3xl;
+}
+
+/* Remove scale transform on active/pressed state for buttons in group */
+.button-group .button:active,
+.button-group .button[data-pressed="true"] {
+  transform: none;
+}
+
+/* Override focus ring to use inset style so it stays within button bounds */
+.button-group .button:focus-visible:not(:focus),
+.button-group .button[data-focus-visible="true"] {
+  --tw-ring-offset-width: 0px;
+  @apply ring-inset;
+}
+
+/* ==========================================================================
+   Separator (compound component)
+   ========================================================================== */
+
+.button-group__separator {
+  @apply rounded-sm bg-current opacity-15;
+  position: absolute;
+  pointer-events: none;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition: opacity 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+
+  /* Horizontal orientation - vertical divider */
+  .button-group--horizontal & {
+    left: -1px;
+    top: 25%;
+    width: 1px;
+    height: 50%;
+  }
+
+  /* Vertical orientation - horizontal divider */
+  .button-group--vertical & {
+    left: 25%;
+    top: -1px;
+    width: 50%;
+    height: 1px;
+  }
+}
+
+/* ==========================================================================
+   Outline button border handling
+   ========================================================================== */
+
+/* Remove adjacent borders from outline buttons in horizontal group */
+/* First button: remove end border (right in LTR, left in RTL) */
+.button-group--horizontal .button--outline:first-child {
+  @apply border-e-0;
+}
+
+/* Last button: remove start border (left in LTR, right in RTL) */
+.button-group--horizontal .button--outline:last-child {
+  @apply border-s-0;
+}
+
+/* Middle buttons: remove both inline borders */
+.button-group--horizontal .button--outline:not(:first-child):not(:last-child) {
+  @apply border-x-0;
+}
+
+/* Remove adjacent borders from outline buttons in vertical group */
+/* First button: remove bottom border */
+.button-group--vertical .button--outline:first-child {
+  @apply border-b-0;
+}
+
+/* Last button: remove top border */
+.button-group--vertical .button--outline:last-child {
+  @apply border-t-0;
+}
+
+/* Middle buttons: remove both block borders */
+.button-group--vertical .button--outline:not(:first-child):not(:last-child) {
+  @apply border-y-0;
+}
+
+/* ==========================================================================
+   Full width modifier
+   ========================================================================== */
+
+.button-group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/button.css b/packages/styles/components/button.css
new file mode 100644
index 0000000..1173aec
--- /dev/null
+++ b/packages/styles/components/button.css
@@ -0,0 +1,158 @@
+/* Button component styles */
+
+/* Base button styles */
+.button {
+  @apply relative isolate inline-flex h-10 w-fit origin-center items-center justify-center gap-2 rounded-3xl px-4 text-sm font-medium whitespace-nowrap outline-none select-none no-highlight md:h-9;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-smooth),
+    background-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out);
+  @apply transform-gpu will-change-transform motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Default tokens (fallback behavior) */
+  --button-bg: transparent;
+  --button-bg-hover: var(--button-bg);
+  --button-bg-pressed: var(--button-bg-hover);
+  --button-fg: currentColor;
+
+  background-color: var(--button-bg);
+  color: var(--button-fg);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Pending state */
+  &[data-pending="true"] {
+    @apply status-pending;
+  }
+
+  /* Active / pressed */
+  &:active,
+  &[data-pressed="true"] {
+    background-color: var(--button-bg-pressed);
+    transform: scale(0.97);
+  }
+
+  /* Hover */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      background-color: var(--button-bg-hover);
+    }
+  }
+
+  /* SVG icon styling - exclude spinner and link-icon svgs */
+  & svg:not([data-slot="spinner"] svg, [data-slot="link-icon"] svg) {
+    @apply pointer-events-none -mx-0.5 my-0.5 size-5 shrink-0 self-center sm:my-1 sm:size-4;
+  }
+}
+
+/* Size variants */
+.button--sm {
+  @apply h-9 px-3 md:h-8;
+
+  & svg:not([data-slot="spinner"] svg, [data-slot="link-icon"] svg) {
+    @apply size-4;
+  }
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.98);
+  }
+}
+
+.button--md {
+  /* No styles as this is the default size */
+}
+
+.button--lg {
+  @apply h-11 text-base md:h-10;
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.96);
+  }
+}
+
+/* Color variants - only set custom property values */
+.button--primary {
+  --button-bg: var(--accent);
+  --button-bg-hover: var(--accent-hover);
+  --button-bg-pressed: var(--accent-hover);
+  --button-fg: var(--accent-foreground);
+}
+
+.button--secondary {
+  --button-bg: var(--default);
+  --button-bg-hover: var(--default-hover);
+  --button-bg-pressed: var(--default-hover);
+  --button-fg: var(--accent-soft-foreground);
+}
+
+.button--tertiary {
+  --button-bg: var(--default);
+  --button-bg-hover: var(--default-hover);
+  --button-bg-pressed: var(--default-hover);
+}
+
+.button--ghost,
+.button--outline {
+  --button-bg: transparent;
+  --button-bg-hover: var(--default);
+  --button-bg-pressed: var(--default);
+  --button-fg: var(--default-foreground);
+}
+
+.button--outline {
+  @apply border border-border;
+  --button-bg-hover: color-mix(in srgb, var(--default) 60%, transparent);
+}
+
+.button--danger {
+  --button-bg: var(--danger);
+  --button-bg-hover: var(--danger-hover);
+  --button-bg-pressed: var(--danger-hover);
+  --button-fg: var(--danger-foreground);
+}
+
+.button--danger-soft {
+  --button-bg: var(--danger-soft);
+  --button-bg-hover: var(--danger-soft-hover);
+  --button-bg-pressed: var(--danger-soft-hover);
+  --button-fg: var(--danger-soft-foreground);
+}
+
+/* Icon-only modifier */
+.button--icon-only {
+  @apply w-10 p-0 md:w-9;
+}
+
+.button--icon-only.button--sm {
+  @apply w-9 md:w-8;
+}
+
+.button--icon-only.button--lg {
+  @apply w-11 md:w-10;
+}
+
+/* Full width modifier */
+.button--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/calendar-year-picker.css b/packages/styles/components/calendar-year-picker.css
new file mode 100644
index 0000000..009a062
--- /dev/null
+++ b/packages/styles/components/calendar-year-picker.css
@@ -0,0 +1,159 @@
+/* =============================================================================
+ * Calendar Year Picker Component Styles
+ *
+ * Internal component used inside Calendar / RangeCalendar to provide a
+ * toggleable year selector. Uses CSS :has() on the parent .calendar to
+ * drive crossfade transitions.
+ *
+ * The year grid is absolutely positioned and sized via JS to match the
+ * day grid's exact area. This keeps the calendar's original block layout
+ * completely untouched.
+ *
+ * BEM naming: calendar-year-picker__element, calendar-year-picker--modifier
+ * ============================================================================= */
+
+/* -----------------------------------------------------------------------------
+ * Positioning Context
+ * -------------------------------------------------------------------------- */
+.calendar:has(.calendar-year-picker__year-grid),
+.range-calendar:has(.calendar-year-picker__year-grid) {
+  position: relative;
+}
+
+/* -----------------------------------------------------------------------------
+ * Crossfade + Blur Transitions
+ *
+ * The crossfade is staggered to avoid both grids being semi-transparent at
+ * the same time (ghosting). When opening, the day grid fades out first,
+ * then the year grid fades in. When closing, the year grid fades out first,
+ * then the day grid fades in (via transition-delay).
+ *
+ * -------------------------------------------------------------------------- */
+
+/* Day grid – default visible */
+.calendar:has(.calendar-year-picker__year-grid) > [data-slot="calendar-grid"],
+.range-calendar:has(.calendar-year-picker__year-grid) > [data-slot="range-calendar-grid"] {
+  will-change: opacity;
+  transition:
+    opacity 150ms var(--ease-out),
+    visibility 0ms linear;
+  @apply motion-reduce:transition-none;
+}
+
+/* Day grid – hidden when year picker is open (fade + blur out) */
+.calendar:has(.calendar-year-picker__year-grid[data-open="true"]) > [data-slot="calendar-grid"],
+.range-calendar:has(.calendar-year-picker__year-grid[data-open="true"])
+  > [data-slot="range-calendar-grid"] {
+  @apply pointer-events-none opacity-0;
+  visibility: hidden;
+  transition:
+    opacity 150ms var(--ease-out),
+    visibility 0ms linear 150ms;
+  @apply motion-reduce:transition-none;
+}
+
+/* -----------------------------------------------------------------------------
+ * Trigger Button
+ * -------------------------------------------------------------------------- */
+.calendar-year-picker__trigger {
+  @apply flex flex-1 items-center justify-start gap-1 rounded-lg outline-none;
+
+  cursor: var(--cursor-interactive);
+  touch-action: manipulation;
+
+  /* Focus state */
+  &:focus-visible {
+    @apply status-focused;
+  }
+}
+
+.calendar-year-picker__trigger-heading {
+  @apply text-sm font-medium;
+
+  transition: color 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+}
+
+.calendar-year-picker__trigger-indicator {
+  @apply text-xs text-accent-soft-foreground;
+
+  transition: transform 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+}
+
+/* Rotate chevron when open */
+.calendar-year-picker__trigger[data-open="true"] .calendar-year-picker__trigger-indicator {
+  transform: rotate(90deg);
+}
+
+.calendar-year-picker__trigger[data-open="true"] .calendar-year-picker__trigger-heading {
+  @apply text-accent-soft-foreground;
+}
+
+/* -----------------------------------------------------------------------------
+ * Year Grid Container
+ *
+ * Absolutely positioned over the day grid area. The exact `top` and `height`
+ * are set via JS to match the sibling day grid element.
+ * -------------------------------------------------------------------------- */
+.calendar-year-picker__year-grid {
+  @apply pointer-events-none absolute right-0 left-0 grid content-start gap-1 overflow-y-auto p-1 opacity-0 scrollbar;
+  grid-template-columns: repeat(3, 1fr);
+
+  /* When closing: instant (no transition) */
+  will-change: opacity;
+}
+
+.calendar-year-picker__year-grid[data-open="true"] {
+  @apply pointer-events-auto opacity-100;
+
+  /* When opening: slight delay so the day grid starts fading out first */
+  transition: opacity 200ms var(--ease-out) 50ms;
+  @apply motion-reduce:transition-none;
+}
+
+/* -----------------------------------------------------------------------------
+ * Year Cell
+ * -------------------------------------------------------------------------- */
+.calendar-year-picker__year-cell {
+  @apply relative inline-flex h-8 items-center justify-center rounded-3xl px-2.5 text-sm font-medium outline-none select-none no-highlight;
+  touch-action: manipulation;
+
+  /**
+   * Transitions – same as .tag
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 100ms var(--ease-smooth),
+    scale 100ms var(--ease-smooth),
+    opacity 100ms var(--ease-smooth),
+    background-color 100ms var(--ease-smooth),
+    box-shadow 100ms var(--ease-out);
+  @apply origin-center transform-gpu motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Hover state (when not selected) – only on devices that support hover */
+  @media (hover: hover) and (pointer: fine) {
+    &:is(:hover, [data-hovered="true"]):not([data-selected="true"]) {
+      @apply bg-default text-default-foreground;
+    }
+  }
+
+  /* Selected state (current year) – same as .tag[data-selected] */
+  &[data-selected="true"],
+  &[aria-selected="true"] {
+    @apply bg-accent text-accent-foreground;
+
+    @media (hover: hover) and (pointer: fine) {
+      &:is(:hover, [data-hovered="true"]) {
+        @apply bg-accent-hover;
+      }
+    }
+  }
+
+  /* Focus state */
+  &:focus-visible {
+    @apply status-focused;
+  }
+}
diff --git a/packages/styles/components/calendar.css b/packages/styles/components/calendar.css
new file mode 100644
index 0000000..c9e9835
--- /dev/null
+++ b/packages/styles/components/calendar.css
@@ -0,0 +1,273 @@
+/* =============================================================================
+ * Calendar Component Styles
+ *
+ * A compound component for date selection.
+ * Uses BEM naming convention: calendar, calendar__element, calendar--modifier
+ * ============================================================================= */
+
+/* -----------------------------------------------------------------------------
+ * Base Calendar Styles
+ * -------------------------------------------------------------------------- */
+.calendar {
+  @apply w-63 max-w-63;
+
+  container-type: inline-size;
+}
+
+/* Week view – visibleDuration={{ weeks: n }} */
+.calendar--week-view {
+  .calendar__cell {
+    /* Keep cells circular on the 7-column grid; only filled cells take space. */
+    @apply aspect-square size-auto w-full place-self-center;
+  }
+}
+
+/* Day view – visibleDuration={{ days: n }} */
+.calendar--day-view {
+  .calendar__cell {
+    @apply aspect-square size-auto w-full place-self-center;
+  }
+
+  /*
+   * Isolate header and body into separate 7-column grids. With display:contents
+   * on the root grid, fewer than 7 weekday headers flow into the same row as dates.
+   */
+  .calendar__grid {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .calendar__grid-header {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    @apply w-full;
+
+    & > tr {
+      display: contents;
+    }
+  }
+
+  .calendar__grid-body {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    @apply mt-1 w-full;
+
+    & > tr {
+      display: contents;
+    }
+
+    & > tr:first-child > td {
+      @apply mt-0;
+    }
+  }
+}
+
+/* -----------------------------------------------------------------------------
+ * Calendar Header
+ * -------------------------------------------------------------------------- */
+.calendar__header {
+  @apply flex items-center justify-between px-0.5 pb-4;
+
+  &:has(.calendar-year-picker__trigger[data-open="true"]) {
+    .calendar__nav-button {
+      @apply pointer-events-none opacity-0;
+    }
+  }
+}
+
+.calendar__heading {
+  @apply flex-1 text-sm font-medium;
+}
+
+.calendar__nav-button {
+  @apply flex size-6 items-center justify-center rounded-2xl text-accent-soft-foreground;
+
+  will-change: scale;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out),
+    background-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out),
+    opacity 150ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Hover state – only on devices that support hover (avoids false triggers on touch) */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default text-accent-soft-foreground;
+    }
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.95);
+  }
+
+  /* Focus state */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.calendar__nav-button-icon {
+  @apply size-4;
+}
+
+/* -----------------------------------------------------------------------------
+ * Calendar Grid
+ * -------------------------------------------------------------------------- */
+.calendar__grid {
+  /* Override table display with CSS Grid for easier customization */
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  @apply w-full;
+
+  &[aria-readonly="true"] {
+    .calendar__cell {
+      @apply pointer-events-none;
+    }
+  }
+}
+
+.calendar__grid-header {
+  /* Grid header (thead) styles */
+  display: contents;
+
+  & > tr {
+    display: contents;
+  }
+}
+
+.calendar__grid-body {
+  /* Grid body (tbody) styles */
+  display: contents;
+
+  & > tr {
+    display: contents;
+  }
+
+  /* Add top spacing between header and first body row */
+  & > tr:first-child > td {
+    @apply mt-1;
+  }
+}
+
+.calendar__grid-row {
+  /* Use 'contents' so cells participate directly in grid */
+  /* Note: This class can be used for custom row styling if needed */
+  display: contents;
+}
+
+.calendar__header-cell {
+  /* Header cell (th - weekday names) styles */
+  @apply flex items-center justify-center pb-2 text-xs font-medium text-muted;
+}
+
+/* -----------------------------------------------------------------------------
+ * Calendar Cells
+ * -------------------------------------------------------------------------- */
+.calendar__cell {
+  /* Cell (td) wrapper styles - margins now work with grid layout */
+  @apply relative flex aspect-square size-full items-center justify-center rounded-3xl text-center text-sm font-medium outline-none no-highlight;
+
+  will-change: scale;
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out),
+    box-shadow 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Today indicator */
+  &[data-today="true"] {
+    @apply bg-accent-soft text-accent-soft-foreground;
+
+    @media (hover: hover) {
+      &:hover:not([data-selected="true"]),
+      &[data-hovered="true"]:not([data-selected="true"]) {
+        @apply bg-accent-soft-hover;
+      }
+    }
+  }
+
+  /* Selected state */
+  &[data-selected="true"] {
+    @apply bg-accent text-accent-foreground;
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    @apply bg-default;
+    transform: scale(0.95);
+
+    &[data-selected="true"] {
+      @apply bg-accent-hover;
+    }
+  }
+
+  /* Hover state – only on devices that support hover (avoids false triggers on touch) */
+  @media (hover: hover) {
+    &:hover:not([data-selected="true"]),
+    &[data-hovered="true"]:not([data-selected="true"]) {
+      @apply bg-default;
+    }
+  }
+
+  /* Outside month (previous/next month days) */
+  &[data-outside-month="true"] {
+    @apply text-muted opacity-50;
+  }
+
+  &[data-selected="true"][data-outside-month="true"] {
+    @apply bg-default;
+  }
+
+  /* Unavailable dates */
+  &[data-unavailable="true"] {
+    @apply status-disabled;
+  }
+
+  /* Disabled state */
+  &:disabled:not([data-outside-month="true"]),
+  &[data-disabled="true"]:not([data-outside-month="true"]) {
+    @apply status-disabled;
+
+    text-decoration: line-through;
+  }
+}
+
+/* Cell indicator - small dot at bottom center of cell */
+.calendar__cell-indicator {
+  @apply absolute bottom-1 left-1/2 size-[3px] -translate-x-1/2 rounded-xs bg-muted;
+
+  /* Indicator color changes when cell is selected */
+  [data-selected="true"] > & {
+    @apply bg-accent-foreground;
+  }
+}
diff --git a/packages/styles/components/card.css b/packages/styles/components/card.css
new file mode 100644
index 0000000..34db18c
--- /dev/null
+++ b/packages/styles/components/card.css
@@ -0,0 +1,51 @@
+/* Card component styles */
+
+/* Block */
+.card {
+  @apply relative flex flex-col gap-3 overflow-visible p-4;
+  @apply shadow-surface;
+  border-radius: min(32px, var(--radius-3xl));
+}
+
+/* Element - header */
+.card__header {
+  @apply flex flex-col;
+}
+
+/* Element - title */
+.card__title {
+  @apply text-sm leading-6 font-medium text-foreground;
+}
+
+/* Element - description */
+.card__description {
+  @apply text-sm leading-5 text-muted;
+}
+
+/* Element - content */
+.card__content {
+  @apply flex flex-1 flex-col gap-1;
+}
+
+/* Element - footer */
+.card__footer {
+  @apply flex flex-row items-center;
+}
+
+/* Modifier - variant */
+
+.card--transparent {
+  @apply border-none bg-transparent shadow-none;
+}
+
+.card--default {
+  @apply bg-surface;
+}
+
+.card--secondary {
+  @apply bg-surface-secondary;
+}
+
+.card--tertiary {
+  @apply bg-surface-tertiary;
+}
diff --git a/packages/styles/components/checkbox-group.css b/packages/styles/components/checkbox-group.css
new file mode 100644
index 0000000..61a39eb
--- /dev/null
+++ b/packages/styles/components/checkbox-group.css
@@ -0,0 +1,7 @@
+.checkbox-group {
+  @apply flex flex-col;
+
+  [data-slot="checkbox"] {
+    @apply mt-4;
+  }
+}
diff --git a/packages/styles/components/checkbox.css b/packages/styles/components/checkbox.css
new file mode 100644
index 0000000..24985e8
--- /dev/null
+++ b/packages/styles/components/checkbox.css
@@ -0,0 +1,264 @@
+/* ==========================================================================
+   Base checkbox styles
+   ========================================================================== */
+
+.checkbox {
+  @apply flex flex-col items-start gap-1 outline-none no-highlight;
+
+  cursor: var(--cursor-interactive);
+
+  /* Field-level help text (siblings of the button), indented to align under the label */
+  & > [data-slot="description"],
+  & > [data-slot="field-error"] {
+    @apply w-full min-w-0 cursor-default ps-7 text-xs text-wrap wrap-break-word text-muted select-none;
+  }
+
+  [data-slot="label"] {
+    @apply select-none;
+  }
+
+  .checkbox__content [data-slot="label"] {
+    cursor: var(--cursor-interactive);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="description"],
+    [data-slot="field-error"] {
+      @apply status-disabled;
+    }
+  }
+
+  /* Indicator styles */
+  &[data-selected="true"],
+  &[data-indeterminate="true"] {
+    .checkbox__indicator {
+      border-color: var(--accent-foreground);
+    }
+  }
+
+  /* Checkmark SVG indicator */
+  [data-slot="checkbox-default-indicator--checkmark"] {
+    @apply size-2.5 stroke-[2.5px] text-accent-foreground;
+
+    /**
+     * Transitions
+     */
+    @apply transition-all duration-200 motion-reduce:transition-none;
+  }
+
+  &[data-selected="true"] [data-slot="checkbox-default-indicator--checkmark"] {
+    transition: stroke-dashoffset 150ms linear 15ms;
+  }
+
+  /* Invalid + Selected: checkmark icon color */
+  &[data-invalid="true"][data-selected="true"] [data-slot="checkbox-default-indicator--checkmark"],
+  &[data-invalid="true"][aria-checked="true"] [data-slot="checkbox-default-indicator--checkmark"],
+  &[aria-invalid="true"][data-selected="true"] [data-slot="checkbox-default-indicator--checkmark"],
+  &[aria-invalid="true"][aria-checked="true"] [data-slot="checkbox-default-indicator--checkmark"] {
+    @apply text-danger-foreground;
+  }
+
+  /* Indeterminate line indicator */
+  &[data-indeterminate="true"] {
+    [data-slot="checkbox-default-indicator--indeterminate"] {
+      @apply size-3;
+    }
+  }
+
+  /* Invalid + Indeterminate: indeterminate icon color */
+  &[data-indeterminate="true"][data-invalid="true"]
+    [data-slot="checkbox-default-indicator--indeterminate"],
+  &[data-indeterminate="true"][aria-invalid="true"]
+    [data-slot="checkbox-default-indicator--indeterminate"] {
+    @apply text-danger-foreground;
+  }
+}
+
+/* ==========================================================================
+   Checkbox control (the square button)
+   ========================================================================== */
+
+.checkbox__control {
+  @apply relative inline-flex size-4 shrink-0 items-center justify-center overflow-hidden rounded-md border [border-width:var(--border-width-field)] border-field-border bg-field shadow-field outline-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 200ms var(--ease-out),
+    border-color 200ms var(--ease-out),
+    transform 100ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Background indicator pseudo-element */
+  &::before {
+    @apply pointer-events-none absolute inset-0 z-0 origin-center scale-70 rounded-md bg-accent opacity-0 content-[''];
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition:
+      scale 100ms var(--ease-linear),
+      opacity 200ms var(--ease-linear),
+      background-color 200ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+  }
+
+  /* Interactive states */
+  /* Focus */
+  .checkbox:focus-visible &,
+  .checkbox:has([data-slot="checkbox-content"][data-focus-visible="true"]) &,
+  .checkbox [data-slot="checkbox-content"][data-focus-visible="true"] & {
+    @apply status-focused;
+  }
+
+  /* Hover */
+  .checkbox:hover &,
+  .checkbox:has([data-slot="checkbox-content"][data-hovered="true"]) &,
+  .checkbox [data-slot="checkbox-content"][data-hovered="true"] & {
+    @apply border-field-border-hover;
+
+    &::before {
+      @apply bg-accent-hover;
+    }
+  }
+
+  /* Pressed */
+  .checkbox:active &,
+  .checkbox:has([data-slot="checkbox-content"][data-pressed="true"]) &,
+  .checkbox [data-slot="checkbox-content"][data-pressed="true"] & {
+  }
+
+  /* Selection states */
+  /* Selected */
+  .checkbox[aria-checked="true"] &,
+  .checkbox[data-selected="true"] & {
+    @apply border-transparent text-accent-foreground;
+
+    &::before {
+      @apply scale-100 opacity-100;
+    }
+  }
+
+  /* Indeterminate */
+  .checkbox[data-indeterminate="true"] & {
+    @apply bg-accent text-accent-foreground;
+  }
+
+  /* Indeterminate + Pressed */
+  .checkbox:active[data-indeterminate="true"] &,
+  .checkbox[data-pressed="true"][data-indeterminate="true"] &,
+  .checkbox:has([data-slot="checkbox-content"][data-pressed="true"])[data-indeterminate="true"] & {
+    @apply bg-accent-hover;
+  }
+
+  /* Validation states */
+  /* Invalid (only when not selected/indeterminate) */
+  .checkbox[data-invalid="true"]:not([aria-checked="true"]):not([data-selected="true"]):not(
+      [data-indeterminate="true"]
+    )
+    &,
+  .checkbox[aria-invalid="true"]:not([aria-checked="true"]):not([data-selected="true"]):not(
+      [data-indeterminate="true"]
+    )
+    & {
+    @apply status-invalid-field;
+  }
+
+  /* Invalid + Selected */
+  .checkbox[data-invalid="true"][aria-checked="true"] &,
+  .checkbox[data-invalid="true"][data-selected="true"] &,
+  .checkbox[aria-invalid="true"][aria-checked="true"] &,
+  .checkbox[aria-invalid="true"][data-selected="true"] & {
+    @apply border-transparent bg-danger text-danger-foreground;
+
+    &::before {
+      @apply scale-100 bg-danger opacity-100;
+    }
+  }
+
+  /* Invalid + Indeterminate */
+  .checkbox[data-indeterminate="true"][aria-invalid="true"] &,
+  .checkbox[data-indeterminate="true"][data-invalid="true"] & {
+    @apply bg-danger text-danger-foreground;
+  }
+}
+
+/* ==========================================================================
+   Checkbox indicator
+   ========================================================================== */
+
+.checkbox__indicator {
+  @apply relative z-10 flex size-3 items-center justify-center;
+
+  & svg {
+    @apply size-full transform-gpu;
+  }
+}
+
+/* ==========================================================================
+   Disabled modifier
+   ========================================================================== */
+
+.checkbox--disabled {
+  @apply status-disabled;
+}
+
+/* ==========================================================================
+   Variant property definitions
+   ========================================================================== */
+
+.checkbox--primary {
+  /* Default styles */
+}
+
+.checkbox--secondary .checkbox__control {
+  @apply shadow-none;
+  background-color: var(--checkbox-control-bg);
+
+  --checkbox-control-bg: var(--default);
+
+  /* Hover state */
+  .checkbox:hover &,
+  .checkbox:has([data-slot="checkbox-content"][data-hovered="true"]) &,
+  .checkbox [data-slot="checkbox-content"][data-hovered="true"] & {
+    @apply border-field-border-hover;
+  }
+}
+
+/* Checkbox content — the clickable label (control + label text) */
+.checkbox__content {
+  @apply relative inline-flex cursor-[inherit] items-center gap-3 text-sm font-medium text-foreground outline-none select-none no-highlight;
+}
+
+/* Unselected state background for secondary variant */
+.checkbox--secondary:not([aria-checked="true"]):not([data-selected="true"]):not(
+    [data-indeterminate="true"]
+  )
+  .checkbox__control {
+  background-color: var(--checkbox-control-bg);
+}
+
+/* Selected state on secondary variant */
+.checkbox--secondary[aria-checked="true"] .checkbox__control,
+.checkbox--secondary[data-selected="true"] .checkbox__control {
+  &::before {
+    @apply bg-accent;
+  }
+}
+
+/* Indeterminate state on secondary variant */
+.checkbox--secondary[data-indeterminate="true"] .checkbox__control {
+  @apply bg-accent;
+
+  &::before {
+    @apply bg-accent;
+  }
+}
diff --git a/packages/styles/components/chip.css b/packages/styles/components/chip.css
new file mode 100644
index 0000000..43e7871
--- /dev/null
+++ b/packages/styles/components/chip.css
@@ -0,0 +1,112 @@
+/* Base styles */
+.chip {
+  @apply inline-flex w-fit shrink-0 items-center gap-0.5 rounded-2xl px-2 py-0.5 text-xs leading-5 font-medium;
+
+  /* Default tokens */
+  --chip-bg: var(--default);
+  --chip-fg: currentColor;
+
+  background-color: var(--chip-bg);
+  color: var(--chip-fg);
+}
+
+.chip__label {
+  @apply px-0.5;
+}
+
+/* Color variants - set foreground color */
+.chip--accent {
+  --chip-fg: var(--accent-soft-foreground);
+}
+
+.chip--danger {
+  --chip-fg: var(--danger-soft-foreground);
+}
+
+.chip--default {
+  --chip-fg: var(--default-foreground);
+}
+
+.chip--success {
+  --chip-fg: var(--success-soft-foreground);
+}
+
+.chip--warning {
+  --chip-fg: var(--warning-soft-foreground);
+}
+
+/* Variant styles */
+.chip--primary {
+}
+
+.chip--secondary {
+  /* No additional styles for secondary variant */
+}
+
+.chip--tertiary {
+  --chip-bg: transparent;
+}
+
+/* Size variants */
+.chip--sm {
+  @apply px-1 py-0 text-xs;
+}
+
+.chip--md {
+  @apply text-xs;
+}
+
+.chip--lg {
+  @apply px-3 py-1 text-sm font-medium;
+}
+
+/* ====================== */
+/* = Compound variants = */
+/* ====================== */
+
+/* Primary variants - solid backgrounds */
+.chip--primary.chip--accent {
+  --chip-bg: var(--accent);
+  --chip-fg: var(--accent-foreground);
+}
+
+.chip--primary.chip--success {
+  --chip-bg: var(--success);
+  --chip-fg: var(--success-foreground);
+}
+
+.chip--primary.chip--warning {
+  --chip-bg: var(--warning);
+  --chip-fg: var(--warning-foreground);
+}
+
+.chip--primary.chip--danger {
+  --chip-bg: var(--danger);
+  --chip-fg: var(--danger-foreground);
+}
+
+/* Soft variants - muted backgrounds */
+.chip--accent.chip--soft {
+  --chip-bg: var(--accent-soft);
+  --chip-fg: var(--accent-soft-foreground);
+}
+
+.chip--success.chip--soft {
+  --chip-bg: var(--success-soft);
+  --chip-fg: var(--success-soft-foreground);
+}
+
+.chip--warning.chip--soft {
+  --chip-bg: var(--warning-soft);
+  --chip-fg: var(--warning-soft-foreground);
+}
+
+.chip--danger.chip--soft {
+  --chip-bg: var(--danger-soft);
+  --chip-fg: var(--danger-soft-foreground);
+}
+
+.chip--default.chip--soft {
+  --chip-bg: var(--default-soft);
+  --chip-fg: var(--default-soft-foreground);
+}
diff --git a/packages/styles/components/close-button.css b/packages/styles/components/close-button.css
new file mode 100644
index 0000000..b820d73
--- /dev/null
+++ b/packages/styles/components/close-button.css
@@ -0,0 +1,65 @@
+/* Close Button component styles */
+
+/* Base close button styles */
+.close-button {
+  @apply relative isolate inline-flex h-6 w-6 shrink-0 origin-center items-center justify-center rounded-xl p-1 select-none no-highlight;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    color 150ms var(--ease-out),
+    background-color 100ms var(--ease-out),
+    box-shadow 150ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Pending state */
+  &[data-pending="true"] {
+    @apply status-pending;
+  }
+
+  /* SVG icon styling*/
+  & svg {
+    @apply pointer-events-none;
+    @apply size-4 shrink-0 self-center;
+    @apply -mx-0.5 my-0.5;
+  }
+}
+
+/* Variants */
+.close-button--default {
+  @apply bg-default text-muted;
+
+  &:active,
+  &[data-pressed="true"] {
+  }
+
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default-hover;
+    }
+  }
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.93);
+  }
+}
diff --git a/packages/styles/components/color-area.css b/packages/styles/components/color-area.css
new file mode 100644
index 0000000..631c9e8
--- /dev/null
+++ b/packages/styles/components/color-area.css
@@ -0,0 +1,80 @@
+/* ==========================================================================
+   ColorArea - 2D color picker for selecting colors from a gradient area
+   ========================================================================== */
+
+/* Base styles */
+.color-area {
+  @apply relative w-full max-w-56 shrink-0 rounded-2xl no-highlight;
+
+  /* Square aspect ratio */
+  aspect-ratio: 1 / 1;
+
+  /* Color gradient background from React Aria */
+  background: var(--color-area-background);
+
+  /* Inner shadow for depth */
+  box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.1);
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   Dots overlay variant
+   ========================================================================== */
+
+.color-area--show-dots {
+  /* Dot pattern overlay using radial gradient */
+  &::after {
+    content: "";
+    @apply pointer-events-none absolute inset-0 rounded-[inherit];
+
+    background-image: radial-gradient(circle, rgba(255, 255, 255, 0.2) 1px, transparent 1px);
+    background-size: 8px 8px;
+  }
+}
+
+/* ==========================================================================
+   Thumb element
+   ========================================================================== */
+
+.color-area__thumb {
+  @apply size-4 rounded-xl will-change-[width,height];
+
+  /* Current color from React Aria */
+  background-color: var(--color-area-thumb-color);
+
+  /* White border for visibility */
+  border: 3px solid white;
+
+  /* Inner shadow for depth */
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.1),
+    inset 0 0 0 1px rgba(0, 0, 0, 0.1);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    width 150ms var(--ease-out),
+    height 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Focus state */
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Dragging state */
+  &[data-dragging="true"] {
+    @apply size-5;
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
diff --git a/packages/styles/components/color-field.css b/packages/styles/components/color-field.css
new file mode 100644
index 0000000..f3e73d1
--- /dev/null
+++ b/packages/styles/components/color-field.css
@@ -0,0 +1,24 @@
+/* ==========================================================================
+   ColorField - Form field for editing hex colors or individual color channels
+   ========================================================================== */
+
+/* Base styles */
+.color-field {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+}
+
+/* Full width modifier */
+.color-field--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/color-input-group.css b/packages/styles/components/color-input-group.css
new file mode 100644
index 0000000..c1fc7e8
--- /dev/null
+++ b/packages/styles/components/color-input-group.css
@@ -0,0 +1,135 @@
+/* ==========================================================================
+   ColorInputGroup - Input group for color field with prefix/suffix support
+   ========================================================================== */
+
+/* Base styles */
+.color-input-group {
+  @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus within state */
+  &[data-focus-within="true"],
+  &:focus-within {
+    @apply status-focused-field;
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+    border-color: var(--color-field-border-invalid);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   Elements
+   ========================================================================== */
+
+.color-input-group__input {
+  @apply flex h-full flex-1 cursor-text items-center rounded-none border-0 bg-transparent px-3 py-2 text-base shadow-none outline-none sm:text-sm;
+
+  /* Placeholder styling */
+  &::placeholder {
+    @apply text-field-placeholder;
+  }
+
+  /* Remove border radius on left side when prefix is present */
+  .color-input-group:has([data-slot="color-input-group-prefix"]) & {
+    @apply rounded-l-none pl-2;
+  }
+
+  /* Remove border radius on right side when suffix is present */
+  .color-input-group:has([data-slot="color-input-group-suffix"]) & {
+    @apply rounded-r-none pr-2;
+  }
+
+  /* Focus state - handled by group */
+  &:focus,
+  &:focus-visible {
+    @apply outline-none;
+  }
+}
+
+.color-input-group__prefix {
+  @apply shrink-0 text-field-placeholder;
+  @apply mr-0 ml-3 flex items-center;
+}
+
+.color-input-group__suffix {
+  @apply shrink-0 text-field-placeholder;
+  @apply mr-3 flex items-center;
+}
+
+/* ==========================================================================
+   Variant modifiers
+   ========================================================================== */
+
+.color-input-group--primary {
+  /* Default styles - primary variant uses the base field styling */
+}
+
+.color-input-group--secondary {
+  @apply shadow-none;
+  background-color: var(--color-input-group-bg);
+
+  --color-input-group-bg: var(--default);
+  --color-input-group-bg-hover: var(--default-hover);
+  --color-input-group-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      background-color: var(--color-input-group-bg-hover);
+    }
+  }
+
+  &:focus-within,
+  &[data-focus-within="true"] {
+    background-color: var(--color-input-group-bg-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    border-color: var(--color-field-border-invalid);
+    background-color: var(--color-input-group-bg-focus);
+  }
+
+  [data-slot="color-input-group-input"] {
+    @apply bg-transparent;
+  }
+}
+
+/* ==========================================================================
+   Full width modifier
+   ========================================================================== */
+
+.color-input-group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/color-picker.css b/packages/styles/components/color-picker.css
new file mode 100644
index 0000000..c32c3e0
--- /dev/null
+++ b/packages/styles/components/color-picker.css
@@ -0,0 +1,95 @@
+/* ==========================================================================
+   ColorPicker - Color selection component with popover
+   ========================================================================== */
+
+/* Base color-picker styles */
+.color-picker {
+  @apply inline-flex;
+}
+
+/* ==========================================================================
+   Trigger
+   ========================================================================== */
+
+.color-picker__trigger {
+  @apply inline-flex items-center gap-3 rounded-sm text-sm no-highlight;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  [data-slot="label"] {
+    cursor: var(--cursor-interactive);
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   Popover
+   ========================================================================== */
+
+.color-picker__popover {
+  @apply min-w-62 origin-(--trigger-anchor-point) overflow-x-hidden overflow-y-auto overscroll-contain bg-overlay px-2 pt-2 pb-3 scrollbar-none;
+  box-shadow: var(--shadow-overlay);
+  border-radius: min(32px, calc(var(--radius) * 2.5));
+  /* Content layout */
+  @apply flex flex-col gap-3;
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-95;
+
+    /* Placement-specific translations */
+    &[data-placement^="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement^="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement^="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement^="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+}
diff --git a/packages/styles/components/color-slider.css b/packages/styles/components/color-slider.css
new file mode 100644
index 0000000..bad2c1e
--- /dev/null
+++ b/packages/styles/components/color-slider.css
@@ -0,0 +1,255 @@
+/* ==========================================================================
+   ColorSlider - A slider for adjusting individual color channel values
+   ========================================================================== */
+
+/* Base styles */
+.color-slider {
+  @apply grid w-full gap-1;
+
+  grid-template-areas:
+    "label output"
+    "track track";
+  grid-template-columns: 1fr auto;
+  grid-template-rows: auto auto;
+
+  /* When neither label nor output exist, collapse to single row */
+  &:not(:has([data-slot="label"])):not(:has(.color-slider__output)) {
+    grid-template-areas: "track";
+    grid-template-columns: 1fr;
+    grid-template-rows: auto;
+    gap: 0;
+  }
+
+  /* When only label exists (no output) */
+  &:has([data-slot="label"]):not(:has(.color-slider__output)) {
+    grid-template-areas:
+      "label"
+      "track";
+    grid-template-columns: 1fr;
+  }
+
+  /* When only output exists (no label) */
+  &:not(:has([data-slot="label"])):has(.color-slider__output) {
+    grid-template-areas:
+      "output"
+      "track";
+    grid-template-columns: 1fr;
+
+    .color-slider__output {
+      justify-self: end;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit text-sm font-medium;
+
+    grid-area: label;
+  }
+
+  .color-slider__output {
+    @apply text-sm font-medium tabular-nums;
+
+    grid-area: output;
+  }
+
+  .color-slider__track {
+    @apply relative rounded-2xl;
+
+    grid-area: track;
+    /* Edge cap pseudo-elements */
+    &::before,
+    &::after {
+      content: "";
+      position: absolute;
+      z-index: 0;
+      pointer-events: none;
+    }
+  }
+
+  .color-slider__thumb {
+    /* Flex container for centering */
+    @apply absolute flex cursor-grab items-center justify-center rounded-2xl no-highlight;
+
+    /* Border to create white ring around the thumb */
+    @apply border-3 border-white shadow-overlay;
+
+    /* Ensure thumb is above edge caps */
+    z-index: 1;
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition:
+      transform 250ms var(--ease-out),
+      box-shadow 150ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+
+    /* Dragging state - cursor changes and thumb scales down */
+    &[data-dragging="true"] {
+      @apply cursor-grabbing;
+    }
+
+    /* Focus state - show focus ring */
+    &[data-focus-visible="true"] {
+      @apply z-10 status-focused;
+    }
+
+    /* Disabled state */
+    &[data-disabled="true"] {
+      @apply cursor-default bg-default;
+    }
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="label"] {
+      @apply opacity-100;
+    }
+  }
+
+  /* Horizontal orientation */
+  &[data-orientation="horizontal"] {
+    flex-direction: column;
+
+    .color-slider__track {
+      @apply h-5 justify-self-center rounded-none;
+      width: calc(100% - 1.25rem);
+
+      /* Default border for visibility against similar backgrounds */
+      box-shadow:
+        inset 0 1px 0 0 rgba(0, 0, 0, 0.1),
+        inset 0 -1px 0 0 rgba(0, 0, 0, 0.1);
+
+      /* Edge caps for horizontal orientation */
+      &::before,
+      &::after {
+        @apply top-0 h-full;
+        width: 0.625rem; /* Half thumb width + 2px gap */
+      }
+
+      &::before {
+        @apply rounded-tl-2xl rounded-bl-2xl;
+        left: -0.625rem;
+        box-shadow:
+          inset 1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 1px 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 -1px 0 0 rgba(0, 0, 0, 0.1);
+        background:
+          linear-gradient(var(--track-start-color, transparent)),
+          repeating-conic-gradient(#efefef 0% 25%, #f7f7f7 0% 50%) 50% / 16px 16px;
+      }
+
+      &::after {
+        @apply rounded-tr-2xl rounded-br-2xl;
+        right: -0.625rem;
+        box-shadow:
+          inset -1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 1px 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 -1px 0 0 rgba(0, 0, 0, 0.1);
+        background-color: var(--track-end-color, transparent);
+      }
+    }
+
+    .color-slider__thumb {
+      @apply top-1/2 size-4;
+    }
+  }
+
+  /* Vertical orientation */
+  &[data-orientation="vertical"] {
+    @apply h-full gap-2;
+
+    flex-direction: row;
+    grid-template-areas:
+      "output"
+      "track"
+      "label";
+    grid-template-rows: auto 1fr auto;
+    grid-template-columns: 1fr;
+    align-items: center;
+    justify-items: center;
+
+    /* When neither label nor output exist in vertical, just show track */
+    &:not(:has([data-slot="label"])):not(:has(.color-slider__output)) {
+      grid-template-areas: "track";
+      grid-template-rows: 1fr;
+      gap: 0;
+    }
+
+    /* When only label exists in vertical (no output) */
+    &:has([data-slot="label"]):not(:has(.color-slider__output)) {
+      grid-template-areas:
+        "track"
+        "label";
+      grid-template-rows: 1fr auto;
+    }
+
+    /* When only output exists in vertical (no label) */
+    &:not(:has([data-slot="label"])):has(.color-slider__output) {
+      grid-template-areas:
+        "output"
+        "track";
+      grid-template-rows: auto 1fr;
+    }
+
+    .color-slider__output {
+      text-align: center;
+    }
+
+    [data-slot="label"] {
+      text-align: center;
+    }
+
+    .color-slider__track {
+      @apply w-5 justify-self-center rounded-none;
+      height: calc(100% - 1.25rem);
+
+      /* Left and right borders for vertical track */
+      box-shadow:
+        inset 1px 0 0 0 rgba(0, 0, 0, 0.1),
+        inset -1px 0 0 0 rgba(0, 0, 0, 0.1);
+
+      /* Edge caps for vertical orientation */
+      &::before,
+      &::after {
+        @apply left-0 w-full;
+        height: 0.625rem; /* Half thumb height + 2px gap */
+      }
+
+      &::before {
+        bottom: -0.625rem;
+        border-bottom-left-radius: 999px;
+        border-bottom-right-radius: 999px;
+        /* Left, right, and bottom borders for bottom cap */
+        box-shadow:
+          inset 1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset -1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 -1px 0 0 rgba(0, 0, 0, 0.1);
+        background:
+          linear-gradient(var(--track-start-color, transparent)),
+          repeating-conic-gradient(#efefef 0% 25%, #f7f7f7 0% 50%) 50% / 16px 16px;
+      }
+
+      &::after {
+        top: -0.625rem;
+        border-top-left-radius: 999px;
+        border-top-right-radius: 999px;
+        /* Left, right, and top borders for top cap */
+        box-shadow:
+          inset 1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset -1px 0 0 0 rgba(0, 0, 0, 0.1),
+          inset 0 1px 0 0 rgba(0, 0, 0, 0.1);
+        background-color: var(--track-end-color, transparent);
+      }
+    }
+
+    .color-slider__thumb {
+      @apply left-1/2 size-4;
+    }
+  }
+}
diff --git a/packages/styles/components/color-swatch-picker.css b/packages/styles/components/color-swatch-picker.css
new file mode 100644
index 0000000..1c88e2f
--- /dev/null
+++ b/packages/styles/components/color-swatch-picker.css
@@ -0,0 +1,239 @@
+/* ==========================================================================
+   ColorSwatchPicker - A list of color swatches for selection
+   ========================================================================== */
+
+/* Base styles */
+.color-swatch-picker {
+  @apply flex flex-wrap items-center gap-2;
+}
+
+/* ==========================================================================
+   Item - Individual swatch picker item
+   ========================================================================== */
+
+.color-swatch-picker__item {
+  @apply relative flex size-8 items-center justify-center rounded-2xl border-2 border-transparent outline-none no-highlight;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    border-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Focus state */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Selected state */
+  &[data-selected="true"] {
+    border-color: var(--color-swatch-current);
+    box-shadow: var(--field-shadow);
+    /* Shrink the swatch to reveal the white gap */
+    .color-swatch-picker__swatch {
+      transform: scale(0.77);
+    }
+  }
+}
+
+/* ==========================================================================
+   Swatch - The color swatch visual
+   ========================================================================== */
+
+.color-swatch-picker__swatch {
+  @apply block size-full;
+
+  /* Inherit border-radius from item */
+  border-radius: inherit;
+  /**
+  * Transitions
+  * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+  */
+  transition: transform 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  @media (hover: hover) {
+    &:hover {
+      transform: scale(1.1);
+    }
+  }
+}
+
+/* ==========================================================================
+   Indicator - Checkmark indicator for selected state
+   ========================================================================== */
+
+.color-swatch-picker__indicator {
+  @apply pointer-events-none absolute inset-0 z-10 flex items-center justify-center;
+
+  /* Checkmark SVG styles - default to white for dark backgrounds */
+  & > * {
+    @apply size-1/3 text-white;
+
+    /* Start scaled down - use translateZ(0) for GPU acceleration */
+    transform: scale(0) translateZ(0);
+
+    /**
+     * Transitions
+     */
+    transition: transform 150ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+  }
+
+  /* Use black checkmark on light backgrounds */
+  &[data-light-color="true"] & > * {
+    @apply text-black;
+  }
+
+  /* Scale up when parent item is selected */
+  .color-swatch-picker__item[data-selected="true"] & > * {
+    transform: scale(1) translateZ(0);
+  }
+}
+
+/* ==========================================================================
+   Layout variants
+   ========================================================================== */
+
+.color-swatch-picker--grid {
+  /* Default is already grid (flex-wrap) - no additional styles needed */
+}
+
+.color-swatch-picker--stack {
+  @apply flex-col;
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.color-swatch-picker--xs {
+  .color-swatch-picker__item {
+    @apply size-4 rounded-lg border;
+  }
+}
+
+.color-swatch-picker--sm {
+  .color-swatch-picker__item {
+    @apply size-6 rounded-xl border-2;
+  }
+}
+
+.color-swatch-picker--md {
+  .color-swatch-picker__item {
+    /* No styles as this is the default size */
+  }
+}
+
+.color-swatch-picker--lg {
+  .color-swatch-picker__item {
+    @apply size-9 rounded-3xl border-3;
+  }
+}
+
+.color-swatch-picker--xl {
+  .color-swatch-picker__item {
+    @apply size-10 rounded-3xl border-3;
+  }
+}
+
+/* ==========================================================================
+   Shape variants
+   ========================================================================== */
+
+/* Circle variant (default) - no additional styles needed */
+.color-swatch-picker--circle .color-swatch-picker__item {
+  /* Default is already circle - radius set per size */
+}
+
+/* Square variant */
+.color-swatch-picker--square {
+  .color-swatch-picker__item {
+    @apply rounded-xl;
+    .color-swatch-picker__swatch {
+      @apply rounded-lg;
+    }
+    &[data-selected="true"] {
+      .color-swatch-picker__swatch {
+        @apply rounded-lg;
+      }
+    }
+  }
+}
+
+/* Square variant - item radius for xs */
+.color-swatch-picker--square.color-swatch-picker--xs {
+  .color-swatch-picker__item {
+    @apply rounded-md;
+    .color-swatch-picker__swatch {
+      @apply rounded-md;
+    }
+    &[data-selected="true"] {
+      .color-swatch-picker__swatch {
+        @apply rounded-md;
+      }
+    }
+  }
+}
+
+/* Square variant - item radius for sm */
+.color-swatch-picker--square.color-swatch-picker--sm {
+  .color-swatch-picker__item {
+    @apply rounded-lg;
+    .color-swatch-picker__swatch {
+      @apply rounded-lg;
+    }
+    &[data-selected="true"] {
+      .color-swatch-picker__swatch {
+        @apply rounded-md;
+      }
+    }
+  }
+}
+
+/* Square variant - item radius for md (default) */
+.color-swatch-picker--square.color-swatch-picker--md {
+  /* No styles as this is the default size */
+}
+
+/* Square variant - item radius for lg */
+.color-swatch-picker--square.color-swatch-picker--lg {
+  .color-swatch-picker__item {
+    @apply rounded-xl;
+    .color-swatch-picker__swatch {
+      @apply rounded-lg;
+    }
+    &[data-selected="true"] {
+      .color-swatch-picker__swatch {
+        @apply rounded-lg;
+      }
+    }
+  }
+}
+
+/* Square variant - item radius for xl */
+.color-swatch-picker--square.color-swatch-picker--xl {
+  .color-swatch-picker__item {
+    @apply rounded-xl;
+    .color-swatch-picker__swatch {
+      @apply rounded-lg;
+    }
+    &[data-selected="true"] {
+      .color-swatch-picker__swatch {
+        @apply rounded-lg;
+      }
+    }
+  }
+}
diff --git a/packages/styles/components/color-swatch.css b/packages/styles/components/color-swatch.css
new file mode 100644
index 0000000..725a8d7
--- /dev/null
+++ b/packages/styles/components/color-swatch.css
@@ -0,0 +1,58 @@
+/* Base color-swatch styles */
+.color-swatch {
+  @apply relative box-border size-8 shrink-0;
+
+  /* Checkered background pattern for transparency */
+  background:
+    linear-gradient(var(--color-swatch-current), var(--color-swatch-current)),
+    repeating-conic-gradient(#efefef 0% 25%, #f7f7f7 0% 50%) 50% / 16px 16px;
+
+  /* Default border for visibility against similar backgrounds */
+  box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.1);
+}
+
+/* Shape variants */
+.color-swatch--circle {
+  @apply rounded-2xl;
+}
+
+.color-swatch--square {
+  @apply rounded-md;
+}
+
+/* Size variants */
+.color-swatch--xs {
+  @apply size-4;
+
+  &.color-swatch--circle {
+    @apply rounded-lg;
+  }
+}
+
+.color-swatch--sm {
+  @apply size-6;
+
+  &.color-swatch--circle {
+    @apply rounded-xl;
+  }
+}
+
+.color-swatch--md {
+  /* No additional styles — default size (32px) uses circle's base rounded-2xl */
+}
+
+.color-swatch--lg {
+  @apply size-9;
+
+  &.color-swatch--circle {
+    @apply rounded-3xl;
+  }
+}
+
+.color-swatch--xl {
+  @apply size-10;
+
+  &.color-swatch--circle {
+    @apply rounded-3xl;
+  }
+}
diff --git a/packages/styles/components/combo-box.css b/packages/styles/components/combo-box.css
new file mode 100644
index 0000000..6fa2f5b
--- /dev/null
+++ b/packages/styles/components/combo-box.css
@@ -0,0 +1,171 @@
+/* ComboBox styles */
+.combo-box {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+
+  [data-slot="input"] {
+    @apply min-w-0 flex-1;
+
+    /* Add inline-end padding when trigger is present */
+    &:has(+ .combo-box__trigger) {
+      @apply pe-7;
+    }
+
+    /* Focus state (input.css only has focus-visible, but combo-box also needs focus) */
+    &:focus,
+    &[data-focus] {
+      @apply status-focused-field;
+      border-color: var(--field-border-focus);
+      background-color: var(--field-focus);
+    }
+
+    /* Disabled state */
+    &:disabled,
+    &[data-disabled],
+    &[aria-disabled="true"] {
+      @apply status-disabled;
+    }
+  }
+}
+
+.combo-box__input-group {
+  @apply relative isolate inline-flex items-center;
+}
+
+.combo-box__trigger {
+  @apply absolute top-1/2 end-0 flex h-full shrink-0 -translate-y-1/2 cursor-pointer items-center justify-center pe-2 text-field-placeholder transition duration-150 no-highlight;
+
+  /* Remove default button styles */
+  @apply border-none bg-transparent outline-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply text-field-foreground;
+    }
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply rounded ring-2 ring-focus ring-offset-2 ring-offset-background outline-none;
+  }
+
+  /* Pressed state */
+  &[data-pressed="true"] {
+    @apply opacity-70;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled],
+  &[aria-disabled="true"] {
+    @apply cursor-not-allowed opacity-50;
+  }
+
+  [data-slot="combo-box-trigger-default-icon"] {
+    @apply size-4 transition-transform duration-150 motion-reduce:transition-none;
+  }
+
+  /* Rotate icon when trigger is open */
+  &[data-open="true"] [data-slot="combo-box-trigger-default-icon"] {
+    @apply rotate-180;
+  }
+}
+
+/* Similar to popover content styles */
+.combo-box__popover {
+  @apply min-w-(--trigger-width) origin-(--trigger-anchor-point) scroll-py-1 overflow-y-auto overscroll-contain bg-overlay p-0 text-sm scrollbar;
+  border-radius: min(32px, var(--radius-3xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-95;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="popover-overlay-arrow"] {
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="popover-overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="popover-overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="popover-overlay-arrow"] {
+    rotate: 90deg;
+  }
+
+  /* Listbox styles */
+  [data-slot="list-box"] {
+    @apply p-1.5 outline-none;
+  }
+
+  [data-slot="list-box-item"] {
+    @apply px-2.5;
+
+    /* As the combo-box is single-select, we don't need to animate the checkmark */
+    [data-slot="list-box-item-indicator--checkmark"] {
+      @apply transition-none;
+    }
+  }
+}
+
+/* Full width modifier */
+.combo-box--full-width {
+  @apply w-full;
+}
+
+.combo-box__input-group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/date-field.css b/packages/styles/components/date-field.css
new file mode 100644
index 0000000..8e72a19
--- /dev/null
+++ b/packages/styles/components/date-field.css
@@ -0,0 +1,20 @@
+/* Date field styles */
+.date-field {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+}
+
+/* Full width modifier */
+.date-field--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/date-input-group.css b/packages/styles/components/date-input-group.css
new file mode 100644
index 0000000..fb81d65
--- /dev/null
+++ b/packages/styles/components/date-input-group.css
@@ -0,0 +1,182 @@
+/* Date input group styles */
+.date-input-group {
+  @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus within state */
+  &[data-focus-within="true"]:not(
+      :has(
+        [data-slot="date-picker-trigger"]:focus,
+        [data-slot="date-picker-trigger"][data-focused="true"],
+        [data-slot="date-range-picker-trigger"]:focus,
+        [data-slot="date-range-picker-trigger"][data-focused="true"]
+      )
+    ),
+  &:focus-within:not(
+      :has(
+        [data-slot="date-picker-trigger"]:focus,
+        [data-slot="date-picker-trigger"][data-focused="true"],
+        [data-slot="date-range-picker-trigger"]:focus,
+        [data-slot="date-range-picker-trigger"][data-focused="true"]
+      )
+    ) {
+    @apply status-focused-field;
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+    border-color: var(--color-field-border-invalid);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.date-input-group__input {
+  @apply flex flex-1 cursor-text items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 text-base shadow-none outline-none sm:text-sm;
+
+  /* Remove border radius on left side when prefix is present */
+  .date-input-group:has([data-slot="date-input-group-prefix"]) & {
+    @apply rounded-l-none pl-2;
+  }
+
+  /* Remove border radius on right side when suffix is present */
+  .date-input-group:has([data-slot="date-input-group-suffix"]) & {
+    @apply rounded-r-none pr-2;
+  }
+
+  .date-input-group:has(.date-range-picker__range-separator) & {
+    &[slot="start"] {
+      @apply flex-none pr-0;
+    }
+    &[slot="end"] {
+      @apply pl-0;
+    }
+  }
+
+  /* Focus state - handled by group */
+  &:focus,
+  &:focus-visible {
+    @apply outline-none;
+  }
+}
+
+.date-input-group__input-container {
+  @apply flex flex-1 items-center scrollbar-none;
+  width: fit-content;
+  overflow-x: auto;
+  overflow-y: clip;
+}
+
+.date-input-group__segment {
+  @apply inline-block rounded-md px-0.5 text-end text-nowrap outline-none;
+
+  /* Segment separators styling "/" */
+  &[data-type="literal"] {
+    @apply p-0 text-muted;
+  }
+
+  /* Placeholder styling */
+  &[data-placeholder="true"] {
+    @apply text-field-placeholder;
+  }
+
+  /* Focused segment */
+  &:focus,
+  &[data-focused="true"] {
+    @apply bg-accent-soft text-accent-soft-foreground;
+  }
+
+  /* Disabled segment */
+  &[data-disabled="true"] {
+    @apply opacity-50;
+  }
+
+  /* Invalid segment */
+  &[data-invalid="true"] {
+    @apply text-danger;
+
+    /* Focused segment */
+    &:focus,
+    &[data-focused="true"] {
+      @apply bg-danger-soft text-danger-soft-foreground;
+    }
+  }
+}
+
+.date-input-group__prefix {
+  @apply pointer-events-none shrink-0 text-field-placeholder;
+  @apply mr-0 ml-3 flex items-center;
+}
+
+.date-input-group__suffix {
+  @apply pointer-events-none shrink-0 text-field-placeholder;
+  @apply mr-3 flex items-center;
+}
+
+/* Variant property definitions */
+.date-input-group--primary {
+  /* Default styles */
+}
+
+.date-input-group--secondary {
+  @apply shadow-none;
+  background-color: var(--date-input-group-bg);
+
+  --date-input-group-bg: var(--default);
+  --date-input-group-bg-hover: var(--default-hover);
+  --date-input-group-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      background-color: var(--date-input-group-bg-hover);
+    }
+  }
+
+  &:focus-within,
+  &[data-focus-within="true"] {
+    background-color: var(--date-input-group-bg-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    border-color: var(--color-field-border-invalid);
+    background-color: var(--date-input-group-bg-focus);
+  }
+
+  [data-slot="date-input-group-input"] {
+    @apply bg-transparent;
+  }
+}
+
+/* Full width modifier */
+.date-input-group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/date-picker.css b/packages/styles/components/date-picker.css
new file mode 100644
index 0000000..fe621ef
--- /dev/null
+++ b/packages/styles/components/date-picker.css
@@ -0,0 +1,82 @@
+/* ==========================================================================
+   DatePicker - Date selection trigger and popover container
+   ========================================================================== */
+
+.date-picker {
+  @apply inline-flex flex-col gap-1;
+
+  .date-input-group__suffix,
+  .date-input-group__prefix {
+    @apply pointer-events-auto;
+  }
+}
+
+.date-picker__trigger {
+  @apply inline-flex w-full items-center rounded-field p-1 text-sm no-highlight;
+
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition: box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.date-picker__trigger-indicator {
+  @apply inline-flex size-4 items-center justify-center text-field-placeholder;
+}
+
+.date-picker__popover {
+  @apply w-fit origin-(--trigger-anchor-point) scrollbar-none overflow-y-auto overscroll-contain bg-overlay p-3;
+  @apply motion-reduce:transition-none;
+
+  box-shadow: var(--shadow-overlay);
+  border-radius: min(32px, calc(var(--radius) * 2.5));
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-95;
+
+    &[data-placement^="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement^="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement^="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement^="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+}
diff --git a/packages/styles/components/date-range-picker.css b/packages/styles/components/date-range-picker.css
new file mode 100644
index 0000000..dde5167
--- /dev/null
+++ b/packages/styles/components/date-range-picker.css
@@ -0,0 +1,86 @@
+/* ==========================================================================
+   DateRangePicker - Date range selection trigger and popover container
+   ========================================================================== */
+
+.date-range-picker {
+  @apply inline-flex flex-col gap-1;
+
+  .date-input-group__suffix,
+  .date-input-group__prefix {
+    @apply pointer-events-auto;
+  }
+}
+
+.date-range-picker__trigger {
+  @apply inline-flex w-full items-center rounded-field p-1 text-sm no-highlight;
+
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition: box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.date-range-picker__trigger-indicator {
+  @apply inline-flex size-4 items-center justify-center text-field-placeholder;
+}
+
+.date-range-picker__range-separator {
+  @apply px-1 text-field-placeholder select-none;
+}
+
+.date-range-picker__popover {
+  @apply w-fit origin-(--trigger-anchor-point) scrollbar-none overflow-y-auto overscroll-contain bg-overlay p-3;
+  @apply motion-reduce:transition-none;
+
+  box-shadow: var(--shadow-overlay);
+  border-radius: min(32px, calc(var(--radius) * 2.5));
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-95;
+
+    &[data-placement^="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement^="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement^="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement^="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+}
diff --git a/packages/styles/components/description.css b/packages/styles/components/description.css
new file mode 100644
index 0000000..ab417df
--- /dev/null
+++ b/packages/styles/components/description.css
@@ -0,0 +1,4 @@
+/* Base description styles */
+.description {
+  @apply text-xs text-wrap wrap-break-word text-muted;
+}
diff --git a/packages/styles/components/disclosure-group.css b/packages/styles/components/disclosure-group.css
new file mode 100644
index 0000000..3d7dc49
--- /dev/null
+++ b/packages/styles/components/disclosure-group.css
@@ -0,0 +1,7 @@
+/* Base disclosure-group styles */
+.disclosure-group {
+  @apply w-full;
+
+  /* Performance optimization - contain layout changes */
+  contain: layout style;
+}
diff --git a/packages/styles/components/disclosure.css b/packages/styles/components/disclosure.css
new file mode 100644
index 0000000..d6c407f
--- /dev/null
+++ b/packages/styles/components/disclosure.css
@@ -0,0 +1,63 @@
+/* Base disclosure styles */
+.disclosure {
+  @apply relative;
+}
+
+.accordion__heading {
+  @apply flex;
+}
+
+.disclosure__trigger {
+  cursor: var(--cursor-interactive);
+  @apply inline-block no-highlight;
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.disclosure__indicator {
+  @apply ml-auto size-4 shrink-0 text-inherit;
+
+  /**
+   * Transitions
+   */
+  @apply transition duration-250 motion-reduce:transition-none;
+
+  /* Expanded state for indicator rotation */
+  &[data-expanded="true"] {
+    @apply -rotate-180;
+  }
+}
+
+.disclosure__content {
+  opacity: 0;
+  height: var(--disclosure-panel-height);
+  overflow: clip;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    height 200ms var(--ease-out-quad),
+    opacity 200ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  &[data-expanded="true"] {
+    will-change: height, opacity;
+    opacity: 1;
+  }
+}
+
+.disclosure__body {
+  @apply p-2;
+}
diff --git a/packages/styles/components/drawer.css b/packages/styles/components/drawer.css
new file mode 100644
index 0000000..055ac50
--- /dev/null
+++ b/packages/styles/components/drawer.css
@@ -0,0 +1,298 @@
+/* -------------------------------------------------------------------------------------------------
+ * Drawer Component Styles
+ * Block: drawer
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Element: trigger - the element that opens the drawer
+ */
+.drawer__trigger {
+  @apply inline-block cursor-(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Active/pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.97);
+  }
+}
+
+/**
+ * Element: backdrop - the overlay behind the drawer
+ */
+.drawer__backdrop {
+  @apply fixed inset-0 z-50;
+  @apply h-(--visual-viewport-height) w-full;
+  opacity: 1;
+  transition: opacity 250ms cubic-bezier(0.32, 0.72, 0, 1);
+
+  &[data-entering="true"] {
+    opacity: 0;
+  }
+
+  &[data-exiting="true"] {
+    opacity: 0;
+    transition-duration: 200ms;
+    transition-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    will-change: opacity;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}
+
+/**
+ * Modifier: backdrop--transparent
+ */
+.drawer__backdrop--transparent {
+  @apply bg-transparent;
+}
+
+/**
+ * Modifier: backdrop--opaque
+ */
+.drawer__backdrop--opaque {
+  @apply bg-backdrop;
+}
+
+/**
+ * Modifier: backdrop--blur
+ */
+.drawer__backdrop--blur {
+  @apply bg-backdrop backdrop-blur-md;
+}
+
+/**
+ * Element: content - the positioning wrapper for the drawer panel
+ */
+.drawer__content {
+  @apply pointer-events-none;
+  @apply fixed inset-0 z-50 flex;
+  @apply h-(--visual-viewport-height) w-full min-w-0;
+}
+
+/**
+ * Modifier: content--bottom (default)
+ * Slides up from the bottom edge
+ */
+.drawer__content--bottom {
+  @apply items-end;
+}
+
+/**
+ * Modifier: content--top
+ * Slides down from the top edge
+ */
+.drawer__content--top {
+  @apply items-start;
+}
+
+/**
+ * Modifier: content--left
+ * Slides in from the left edge
+ */
+.drawer__content--left {
+  @apply justify-start;
+}
+
+/**
+ * Modifier: content--right
+ * Slides in from the right edge
+ */
+.drawer__content--right {
+  @apply justify-end;
+}
+
+/**
+ * Element: dialog - the drawer panel itself
+ */
+.drawer__dialog {
+  @apply relative;
+  @apply flex flex-col;
+  @apply bg-overlay shadow-overlay outline-none;
+  @apply p-6;
+  @apply pointer-events-auto;
+
+  --drawer-enter-duration: 250ms;
+  --drawer-exit-duration: 200ms;
+  --drawer-enter-ease: cubic-bezier(0.32, 0.72, 0, 1);
+  --drawer-exit-ease: cubic-bezier(0.32, 0.72, 0, 1);
+
+  will-change: translate;
+  transition: translate var(--drawer-enter-duration) var(--drawer-enter-ease);
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+
+  /* Bottom/top placement: full width, auto height */
+  &[data-placement="bottom"] {
+    @apply w-full;
+    @apply max-h-[85vh];
+    border-top-left-radius: min(32px, var(--radius-2xl));
+    border-top-right-radius: min(32px, var(--radius-2xl));
+  }
+
+  &[data-placement="top"] {
+    @apply w-full;
+    @apply max-h-[85vh];
+    border-bottom-left-radius: min(32px, var(--radius-2xl));
+    border-bottom-right-radius: min(32px, var(--radius-2xl));
+  }
+
+  /* Left/right placement: auto width, full height */
+  &[data-placement="left"] {
+    @apply h-full rounded-none;
+    @apply w-80 max-w-[85vw] sm:w-96;
+  }
+
+  &[data-placement="right"] {
+    @apply h-full rounded-none;
+    @apply w-80 max-w-[85vw] sm:w-96;
+  }
+}
+
+[data-exiting="true"] .drawer__dialog {
+  transition-duration: var(--drawer-exit-duration);
+  transition-timing-function: var(--drawer-exit-ease);
+}
+
+.drawer__content--left .drawer__dialog,
+.drawer__content--right .drawer__dialog,
+.drawer__content--top .drawer__dialog,
+.drawer__content--bottom .drawer__dialog {
+  translate: 0 0;
+}
+
+.drawer__content--left[data-entering="true"] .drawer__dialog,
+.drawer__content--left[data-exiting="true"] .drawer__dialog {
+  translate: -100% 0;
+}
+
+.drawer__content--right[data-entering="true"] .drawer__dialog,
+.drawer__content--right[data-exiting="true"] .drawer__dialog {
+  translate: 100% 0;
+}
+
+.drawer__content--top[data-entering="true"] .drawer__dialog,
+.drawer__content--top[data-exiting="true"] .drawer__dialog {
+  translate: 0 -100%;
+}
+
+.drawer__content--bottom[data-entering="true"] .drawer__dialog,
+.drawer__content--bottom[data-exiting="true"] .drawer__dialog {
+  translate: 0 100%;
+}
+
+.drawer__dialog--top {
+  @apply pb-2;
+  .drawer__handle {
+    @apply pb-0;
+  }
+}
+
+/**
+ * Element: header - the top section with the title
+ */
+.drawer__header {
+  @apply flex flex-col gap-3;
+  @apply mb-0;
+}
+
+/**
+ * Element: heading - the main title text
+ */
+.drawer__heading {
+  @apply align-middle;
+  @apply text-base font-medium text-foreground;
+}
+
+/**
+ * Element: body - the main content area
+ * touch-action: pan-y allows vertical scrolling while the dialog captures drag gestures
+ */
+.drawer__body {
+  @apply min-h-0 flex-1 scrollbar;
+  @apply text-sm leading-[1.43] text-muted;
+  @apply -m-[3px] my-0 p-[3px];
+  @apply overflow-y-auto overscroll-contain;
+  -webkit-overflow-scrolling: touch;
+}
+
+/**
+ * Element: footer - the bottom action section
+ */
+.drawer__footer {
+  @apply flex flex-row items-center justify-end gap-2;
+  @apply mt-0;
+}
+
+/**
+ * Element: handle - visual drag handle indicator
+ */
+.drawer__handle {
+  @apply flex items-center justify-center;
+  @apply pb-2;
+
+  /* The handle bar */
+  & > [data-slot="drawer-handle-bar"] {
+    @apply h-1 w-9 rounded-xs;
+    @apply bg-separator;
+  }
+}
+
+/**
+ * Element: close-trigger - the close button
+ */
+.drawer__close-trigger {
+  @apply absolute top-4 right-4;
+}
+
+/**
+ * Elements Spacing
+ */
+.drawer__header + .drawer__body {
+  @apply mt-2;
+}
+
+.drawer__header + .drawer__footer {
+  @apply mt-5;
+}
+
+.drawer__body + .drawer__footer {
+  @apply mt-5;
+}
+
+.drawer__handle + .drawer__header {
+  @apply mt-0;
+}
+
+.drawer__handle + .drawer__body {
+  @apply mt-0;
+}
diff --git a/packages/styles/components/dropdown.css b/packages/styles/components/dropdown.css
new file mode 100644
index 0000000..47916ac
--- /dev/null
+++ b/packages/styles/components/dropdown.css
@@ -0,0 +1,129 @@
+/* ==========================================================================
+   Base dropdown styles
+   ========================================================================== */
+
+.dropdown {
+  @apply flex flex-col gap-1;
+}
+
+.dropdown__trigger {
+  @apply inline-block;
+  /* Only visible when using a custom trigger  - not passing "Button" as a child - hence we use some button styles (custom trigger) */
+  @apply outline-none;
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Pending state */
+  &[data-pending="true"] {
+    @apply status-pending;
+  }
+
+  /* Default active/pressed state - scale transform */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.97);
+  }
+}
+
+/* Similar to select popover styles */
+.dropdown__popover {
+  @apply max-w-[48svw] origin-(--trigger-anchor-point) scroll-py-1 scrollbar overflow-y-auto overscroll-contain bg-overlay p-0 text-sm will-change-transform md:min-w-55;
+  border-radius: min(32px, var(--radius-3xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-90;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="popover-overlay-arrow"] {
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="popover-overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="popover-overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="popover-overlay-arrow"] {
+    rotate: 90deg;
+  }
+
+  /* Menu styles */
+  [data-slot="dropdown-menu"] {
+    @apply p-1.5 outline-none;
+  }
+
+  [data-slot="menu-item"] {
+    @apply px-2.5;
+  }
+}
+
+.dropdown__menu {
+  @apply relative flex w-full flex-col gap-0.5 overflow-clip p-1;
+
+  /* This makes the separator take up 94% of the width and be centered */
+  [data-slot="separator"] {
+    @apply ml-[3%] w-[94%];
+  }
+}
diff --git a/packages/styles/components/empty-state.css b/packages/styles/components/empty-state.css
new file mode 100644
index 0000000..547156d
--- /dev/null
+++ b/packages/styles/components/empty-state.css
@@ -0,0 +1,4 @@
+/* Base empty-state styles */
+.empty-state {
+  @apply p-2 text-sm text-muted;
+}
diff --git a/packages/styles/components/error-message.css b/packages/styles/components/error-message.css
new file mode 100644
index 0000000..e9dcab9
--- /dev/null
+++ b/packages/styles/components/error-message.css
@@ -0,0 +1,13 @@
+/* Base error message styles */
+.error-message {
+  @apply h-auto text-xs wrap-break-word text-danger;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    opacity 150ms var(--ease-out),
+    height 350ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+}
diff --git a/packages/styles/components/field-error.css b/packages/styles/components/field-error.css
new file mode 100644
index 0000000..962e8db
--- /dev/null
+++ b/packages/styles/components/field-error.css
@@ -0,0 +1,27 @@
+/* Field error styles */
+.field-error {
+  @apply h-0 px-1 text-xs wrap-break-word text-danger opacity-0 data-visible:h-auto data-visible:opacity-100;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    opacity 150ms var(--ease-out),
+    height 350ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+}
+
+/*
+ * Toggle fields (checkbox/switch): stack below the label like description.
+ * Disable collapsible height/opacity — those styles break flex-col content layout.
+ */
+.checkbox > .field-error,
+.checkbox > [data-slot="field-error"],
+.switch > .field-error,
+.switch > [data-slot="field-error"],
+.radio > .field-error,
+.radio > [data-slot="field-error"] {
+  @apply m-0 h-auto min-h-0 p-0 text-muted opacity-100;
+  transition: none;
+}
diff --git a/packages/styles/components/fieldset.css b/packages/styles/components/fieldset.css
new file mode 100644
index 0000000..fbd2d7a
--- /dev/null
+++ b/packages/styles/components/fieldset.css
@@ -0,0 +1,18 @@
+/* Base component styles */
+.fieldset {
+  @apply flex flex-col gap-6;
+  /* fix flexbox issue in Safari when fieldset with legend is inside a flexbox */
+  @apply shrink grow basis-0;
+}
+
+.fieldset__legend {
+  @apply text-base font-medium text-foreground;
+}
+
+.fieldset__field_group {
+  @apply w-full space-y-4;
+}
+
+.fieldset__actions {
+  @apply flex items-center gap-2 pt-1;
+}
diff --git a/packages/styles/components/header.css b/packages/styles/components/header.css
new file mode 100644
index 0000000..90b093e
--- /dev/null
+++ b/packages/styles/components/header.css
@@ -0,0 +1,7 @@
+/* ==========================================================================
+   Base header styles
+   ========================================================================== */
+
+.header {
+  @apply w-full px-2 pt-1.5 pb-1 text-left text-xs font-medium text-muted;
+}
diff --git a/packages/styles/components/index.css b/packages/styles/components/index.css
new file mode 100644
index 0000000..64bbd69
--- /dev/null
+++ b/packages/styles/components/index.css
@@ -0,0 +1,160 @@
+/* ------------------------------------------------------------------------------------------------
+ * Component Styles
+ * ------------------------------------------------------------------------------------------------
+ * CRITICAL: Import order matters for CSS specificity and style overrides.
+ *
+ * General Rule: Shared/primitive components MUST be imported FIRST, before components that use them.
+ * This ensures that parent component styles can properly override shared component defaults.
+ *
+ * Organization: Components are grouped by their Storybook categories (Components/Category/Name)
+ * to maintain consistency between documentation and implementation.
+ * ------------------------------------------------------------------------------------------------ */
+
+/* ------------------------------------------------------------------------------------------------
+ * Shared Components - MUST Import FIRST
+ * ------------------------------------------------------------------------------------------------
+ * These are used by multiple components and must be imported early to allow proper overrides.
+ * ------------------------------------------------------------------------------------------------ */
+@import "./close-button.css";
+@import "./description.css";
+@import "./error-message.css";
+@import "./field-error.css";
+@import "./label.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Navigation
+ * ------------------------------------------------------------------------------------------------ */
+@import "./accordion.css";
+@import "./breadcrumbs.css";
+@import "./disclosure-group.css";
+@import "./disclosure.css";
+@import "./link.css";
+@import "./pagination.css";
+@import "./tabs.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Buttons
+ * ------------------------------------------------------------------------------------------------ */
+@import "./button.css";
+@import "./button-group.css";
+@import "./toggle-button.css";
+@import "./toggle-button-group.css";
+@import "./toolbar.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Collections
+ * ------------------------------------------------------------------------------------------------ */
+@import "./dropdown.css";
+@import "./list-box-item.css";
+@import "./list-box-section.css";
+@import "./list-box.css";
+@import "./menu-item.css";
+@import "./menu-section.css";
+@import "./menu.css";
+@import "./tag-group.css";
+@import "./tag.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Colors
+ * ------------------------------------------------------------------------------------------------ */
+@import "./color-area.css";
+@import "./color-picker.css";
+@import "./color-slider.css";
+@import "./color-swatch.css";
+@import "./color-swatch-picker.css";
+@import "./color-input-group.css";
+@import "./color-field.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Controls
+ * ------------------------------------------------------------------------------------------------ */
+@import "./slider.css";
+@import "./switch.css";
+@import "./switch-group.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * DataDisplay
+ * ------------------------------------------------------------------------------------------------ */
+@import "./badge.css";
+@import "./chip.css";
+@import "./table.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Feedback
+ * ------------------------------------------------------------------------------------------------ */
+@import "./alert.css";
+@import "./empty-state.css";
+@import "./skeleton.css";
+@import "./meter.css";
+@import "./progress-bar.css";
+@import "./progress-circle.css";
+@import "./spinner.css";
+@import "./toast.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Forms
+ * ------------------------------------------------------------------------------------------------ */
+@import "./checkbox-group.css";
+@import "./checkbox.css";
+@import "./fieldset.css";
+@import "./input-otp.css";
+@import "./input.css";
+@import "./input-group.css";
+@import "./number-field.css";
+@import "./radio-group.css";
+@import "./radio.css";
+@import "./textfield.css";
+@import "./search-field.css";
+@import "./textarea.css";
+
+/* ------------------------------------------------------------------------------------------------
+* Date & Time
+* ------------------------------------------------------------------------------------------------ */
+@import "./calendar.css";
+@import "./range-calendar.css";
+@import "./calendar-year-picker.css";
+@import "./date-field.css";
+@import "./time-field.css";
+@import "./date-input-group.css";
+@import "./date-picker.css";
+@import "./date-range-picker.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Layout
+ * ------------------------------------------------------------------------------------------------ */
+@import "./card.css";
+@import "./header.css";
+@import "./separator.css";
+@import "./surface.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Media
+ * ------------------------------------------------------------------------------------------------ */
+@import "./avatar.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Overlays
+ * ------------------------------------------------------------------------------------------------ */
+@import "./alert-dialog.css";
+@import "./drawer.css";
+@import "./modal.css";
+@import "./popover.css";
+@import "./tooltip.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Pickers
+ * ------------------------------------------------------------------------------------------------ */
+@import "./combo-box.css";
+@import "./select.css";
+@import "./autocomplete.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Typography
+ * ------------------------------------------------------------------------------------------------ */
+@import "./kbd.css";
+@import "./typography.css";
+
+/* ------------------------------------------------------------------------------------------------
+ * Utilities
+ * ------------------------------------------------------------------------------------------------ */
+@import "./scroll-shadow.css";
diff --git a/packages/styles/components/input-group.css b/packages/styles/components/input-group.css
new file mode 100644
index 0000000..c449f81
--- /dev/null
+++ b/packages/styles/components/input-group.css
@@ -0,0 +1,207 @@
+/* Input group styles */
+.input-group {
+  @apply inline-flex min-h-9 items-center rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /* When textarea is present, align items to start and allow height to grow */
+  &:has([data-slot="input-group-textarea"]) {
+    @apply items-start;
+    height: auto;
+  }
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus within state - only when input/textarea is focused */
+  &:has([data-slot="input-group-input"]:focus),
+  &:has([data-slot="input-group-textarea"]:focus) {
+    @apply status-focused-field;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+    border-color: var(--color-field-border-invalid);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /**
+   * Browser autofill state.
+   * The user-agent paints `:-webkit-autofill`/`:autofill` on the inner <input>
+   * element only, inside its content box. Because the inner input has its
+   * border-radius stripped on whichever side touches a prefix/suffix, the
+   * autofill highlight ends up as a sharp-cornered rectangle and the
+   * prefix/suffix slots receive no highlight at all. Lift the highlight
+   * onto the group so the rounded shell + prefix + suffix all share it.
+   */
+  &:has([data-slot="input-group-input"]:-webkit-autofill),
+  &:has([data-slot="input-group-input"]:autofill) {
+    background-color: var(--field-focus);
+    border-color: var(--field-border-focus);
+  }
+}
+
+.input-group__input {
+  @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 text-base shadow-none outline-none placeholder:text-field-placeholder sm:text-sm;
+
+  /* Remove border radius on left side when prefix is present */
+  .input-group:has([data-slot="input-group-prefix"]) & {
+    @apply rounded-l-none pl-0;
+  }
+
+  /* Remove border radius on right side when suffix is present */
+  .input-group:has([data-slot="input-group-suffix"]) & {
+    @apply rounded-r-none pr-0;
+  }
+
+  /* Focus state - handled by group */
+  &:focus,
+  &:focus-visible {
+    @apply outline-none;
+  }
+
+  /**
+   * Neutralize the browser's per-input autofill paint so the inner <input>
+   * doesn't draw a sharp-cornered yellow rectangle. The unified highlight
+   * is applied to `.input-group` above. Preserve the autofilled text and
+   * caret colors, and pin the background-color transition so the inset
+   * box-shadow trick doesn't flicker on state changes.
+   */
+  &:-webkit-autofill,
+  &:-webkit-autofill:hover,
+  &:-webkit-autofill:focus,
+  &:-webkit-autofill:active,
+  &:autofill {
+    -webkit-box-shadow: 0 0 0 1000px transparent inset;
+    box-shadow: 0 0 0 1000px transparent inset;
+    -webkit-text-fill-color: var(--field-foreground);
+    caret-color: var(--field-foreground);
+    transition: background-color 9999s ease-in-out 0s;
+  }
+}
+
+/* TextArea within InputGroup - uses same base class as input but with textarea-specific styles */
+.input-group__input[data-slot="input-group-textarea"] {
+  min-height: 38px;
+  resize: vertical;
+}
+
+.input-group__prefix {
+  @apply flex h-full items-center justify-center rounded-l-field rounded-r-none bg-transparent px-3 text-field-placeholder;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+  border-style: solid;
+  border-right-color: var(--field-border);
+  border-left: none;
+  border-top: none;
+  border-bottom: none;
+
+  /* Align to top when textarea is present */
+  .input-group:has([data-slot="input-group-textarea"]) & {
+    @apply items-start;
+    padding-top: 0.5rem;
+  }
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+}
+
+.input-group__suffix {
+  @apply flex h-full items-center justify-center rounded-l-none rounded-r-field bg-transparent px-3 text-field-placeholder;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+  border-style: solid;
+  border-left-color: var(--field-border);
+  border-right: none;
+  border-top: none;
+  border-bottom: none;
+
+  /* Align to top when textarea is present */
+  .input-group:has([data-slot="input-group-textarea"]) & {
+    @apply items-start;
+    padding-top: 0.5rem;
+  }
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+}
+
+/* Variant property definitions */
+.input-group--primary {
+  /* Default styles */
+}
+
+.input-group--secondary {
+  @apply shadow-none;
+  background-color: var(--input-group-bg);
+
+  --input-group-bg: var(--default);
+  --input-group-bg-hover: var(--default-hover);
+  --input-group-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      background-color: var(--input-group-bg-hover);
+    }
+  }
+
+  &:has([data-slot="input-group-input"]:focus),
+  &:has([data-slot="input-group-textarea"]:focus) {
+    background-color: var(--input-group-bg-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    border-color: var(--color-field-border-invalid);
+    background-color: var(--input-group-bg-focus);
+  }
+
+  [data-slot="input-group-input"],
+  [data-slot="input-group-textarea"] {
+    @apply bg-transparent;
+  }
+}
+
+/* Full width modifier */
+.input-group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/input-otp.css b/packages/styles/components/input-otp.css
new file mode 100644
index 0000000..769e398
--- /dev/null
+++ b/packages/styles/components/input-otp.css
@@ -0,0 +1,124 @@
+/* Base container */
+.input-otp {
+  @apply relative flex items-center gap-2;
+
+  &[data-disabled="true"] {
+    @apply cursor-not-allowed opacity-50;
+  }
+}
+
+/* Group - slots separated with gap */
+.input-otp__group {
+  @apply flex items-center gap-2;
+}
+
+/* Individual slot box - fully rounded, standalone */
+.input-otp__slot {
+  @apply relative flex h-10 w-9.5 flex-1 items-center justify-center;
+  @apply border bg-field text-field-foreground shadow-field;
+  @apply rounded-field text-sm font-semibold outline-none;
+
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Active/Focus */
+  &[data-active="true"] {
+    @apply z-10 bg-field-focus status-focused-field;
+  }
+
+  /* Filled */
+  &[data-filled="true"] {
+    @apply bg-field-focus;
+  }
+
+  /* Disabled */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Invalid */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+  }
+}
+
+/* Slot value */
+.input-otp__slot-value {
+  @apply text-lg leading-6 tracking-[-0.27px];
+
+  /**
+   * Animations
+   * CRITICAL: motion-reduce must be AFTER animation for correct override specificity
+   */
+  animation: slot-value-in 250ms var(--ease-smooth) both;
+  transform-origin: bottom center;
+  @apply motion-reduce:animate-none;
+}
+
+/* Caret */
+.input-otp__caret {
+  @apply absolute h-4 w-[2px] animate-caret-blink rounded-sm bg-field-placeholder;
+}
+
+/* Separator */
+.input-otp__separator {
+  @apply h-[2px] w-[6px] shrink-0 rounded-sm bg-separator;
+}
+
+/* Variant property definitions */
+.input-otp--primary {
+  /* Default styles */
+}
+
+.input-otp--secondary .input-otp__slot {
+  @apply shadow-none;
+  background-color: var(--input-otp-slot-bg);
+
+  --input-otp-slot-bg: var(--default);
+  --input-otp-slot-bg-hover: var(--default-hover);
+  --input-otp-slot-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      background-color: var(--input-otp-slot-bg-hover);
+    }
+  }
+
+  &[data-active="true"],
+  &[data-filled="true"] {
+    background-color: var(--input-otp-slot-bg-focus);
+  }
+}
+
+/* Animations */
+@keyframes slot-value-in {
+  0% {
+    opacity: 0;
+    transform: translateY(8px) scale(0.8);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
diff --git a/packages/styles/components/input.css b/packages/styles/components/input.css
new file mode 100644
index 0000000..e45403c
--- /dev/null
+++ b/packages/styles/components/input.css
@@ -0,0 +1,92 @@
+.input {
+  @apply rounded-field border bg-field px-3 py-2 text-base text-field-foreground shadow-field outline-none placeholder:text-field-placeholder sm:text-sm;
+
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  @media (hover: hover) {
+    &:hover:not(:focus):not(:focus-visible),
+    &[data-hovered="true"]:not([data-focused="true"]):not([data-focus-visible="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focused="true"] {
+    @apply status-focused-field;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* Variant property definitions */
+.input--primary {
+  /* Default styles */
+}
+
+.input--secondary {
+  @apply shadow-none;
+  background-color: var(--input-bg);
+
+  --input-bg: var(--default);
+  --input-bg-hover: var(--default-hover);
+  --input-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus):not(:focus-visible),
+    &[data-hovered="true"]:not([data-focus-visible="true"]):not([data-focused="true"]) {
+      background-color: var(--input-bg-hover);
+    }
+  }
+
+  &:focus,
+  &[data-focused="true"] {
+    background-color: var(--input-bg-focus);
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--input-bg-focus);
+  }
+}
+
+/* Full width modifier */
+.input--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/kbd.css b/packages/styles/components/kbd.css
new file mode 100644
index 0000000..d8646a0
--- /dev/null
+++ b/packages/styles/components/kbd.css
@@ -0,0 +1,27 @@
+/* Base styles */
+.kbd {
+  @apply inline-flex h-6 items-center space-x-0.5 rounded-lg bg-default px-2 text-center font-sans text-sm font-medium whitespace-nowrap text-muted rtl:space-x-reverse;
+  word-spacing: -0.25rem;
+}
+
+/* Key abbreviation styles */
+.kbd__abbr {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  width: 100%;
+  height: 100%;
+  text-decoration: none;
+}
+
+/* Content wrapper */
+.kbd__content {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+/* Variant styles */
+.kbd--light {
+  @apply bg-transparent;
+}
diff --git a/packages/styles/components/label.css b/packages/styles/components/label.css
new file mode 100644
index 0000000..42c17a7
--- /dev/null
+++ b/packages/styles/components/label.css
@@ -0,0 +1,28 @@
+/* Base label styles */
+.label {
+  /* Base styling */
+  @apply text-sm font-medium text-foreground;
+}
+
+/*
+ * Exclude group-level components (RadioGroup, CheckboxGroup) and radio/checkbox items
+ * to ensure asterisks only appear on atomic form field labels and group labels,
+ * not on individual options within those groups
+ */
+.label--required,
+[data-required="true"]:not([role="group"]):not([role="radiogroup"]):not([role="checkboxgroup"])
+  > .label,
+[data-required="true"]:not([data-slot="radio"]):not([data-slot="checkbox"]) > .label {
+  @apply after:ml-0.5 after:text-danger after:content-['*'];
+}
+
+.label--disabled,
+[data-disabled="true"] .label {
+  @apply status-disabled;
+}
+
+.label--invalid,
+[data-invalid="true"] .label,
+[aria-invalid="true"] .label {
+  @apply text-danger;
+}
diff --git a/packages/styles/components/link.css b/packages/styles/components/link.css
new file mode 100644
index 0000000..a7bc1a0
--- /dev/null
+++ b/packages/styles/components/link.css
@@ -0,0 +1,79 @@
+/* Base link styles */
+.link {
+  @apply relative inline-flex h-fit w-fit items-center rounded-xl font-medium text-link no-underline decoration-separator-tertiary decoration-[1.5px] underline-offset-4 no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 100ms var(--ease-smooth),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out),
+    opacity 100ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply underline decoration-muted/50;
+
+      .link__icon {
+        @apply opacity-100;
+      }
+    }
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    @apply underline decoration-muted;
+
+    .link__icon {
+      @apply opacity-100;
+    }
+  }
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+
+    .link__icon {
+      @apply opacity-100;
+    }
+  }
+
+  /* Disabled state */
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  .link__icon {
+    @apply pointer-events-none inline-flex size-[0.75em] shrink-0 items-center justify-center text-current opacity-60;
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition: opacity 150ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+
+    & svg {
+      @apply transform-gpu;
+    }
+  }
+
+  .link__icon[data-default-icon="true"] {
+    @apply ml-1 pb-1.5;
+  }
+
+  /* Handle Link with Button Variants */
+  &.button {
+    @apply gap-0 no-underline;
+  }
+}
diff --git a/packages/styles/components/list-box-item.css b/packages/styles/components/list-box-item.css
new file mode 100644
index 0000000..9dbb5a0
--- /dev/null
+++ b/packages/styles/components/list-box-item.css
@@ -0,0 +1,116 @@
+/* ==========================================================================
+   Base list-box item styles
+   ========================================================================== */
+
+.list-box-item {
+  @apply relative flex min-h-9 w-full items-center justify-start gap-3 rounded-2xl px-2 py-1.5 outline-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    box-shadow 150ms var(--ease-out);
+
+  @apply motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  [data-slot="label"] {
+    @apply pointer-events-none w-fit select-none;
+  }
+
+  [data-slot="description"] {
+    @apply pointer-events-none text-wrap select-none;
+  }
+
+  /* Add inline-end padding when indicator is present */
+  &:has(.list-box-item__indicator) {
+    @apply pe-7;
+  }
+
+  /* Focus visible state (keyboard focus only) */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.98);
+  }
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default;
+    }
+  }
+
+  /* Selected state */
+  &[aria-selected="true"],
+  &[data-selected="true"] {
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   List-box item indicator
+   ========================================================================== */
+
+.list-box-item__indicator {
+  @apply absolute top-1/2 end-2 flex size-4 shrink-0 -translate-y-1/2 items-center justify-center text-default-foreground;
+
+  /**
+   * Transitions
+   */
+  @apply transition duration-250 motion-reduce:transition-none;
+
+  /* Checkmark SVG indicator */
+  [data-slot="list-box-item-indicator--checkmark"] {
+    @apply size-2.5;
+
+    /**
+     * Transitions
+     */
+    @apply transition-all duration-300 motion-reduce:transition-none;
+  }
+
+  .list-box-item[aria-selected="true"] [data-slot="list-box-item-indicator--checkmark"],
+  .list-box-item[data-selected="true"] [data-slot="list-box-item-indicator--checkmark"] {
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition: stroke-dashoffset 250ms linear;
+    @apply motion-reduce:transition-none;
+  }
+}
+
+/* Default variant */
+.list-box-item--default {
+}
+
+/* Danger variant */
+.list-box-item--danger {
+  .list-box-item__indicator {
+    @apply text-danger;
+  }
+
+  [data-slot="label"] {
+    @apply text-danger;
+  }
+}
diff --git a/packages/styles/components/list-box-section.css b/packages/styles/components/list-box-section.css
new file mode 100644
index 0000000..1ef325c
--- /dev/null
+++ b/packages/styles/components/list-box-section.css
@@ -0,0 +1,7 @@
+/* ==========================================================================
+   Base list-box section styles
+   ========================================================================== */
+
+.list-box-section {
+  @apply flex flex-col items-start gap-0;
+}
diff --git a/packages/styles/components/list-box.css b/packages/styles/components/list-box.css
new file mode 100644
index 0000000..00687da
--- /dev/null
+++ b/packages/styles/components/list-box.css
@@ -0,0 +1,25 @@
+/* ==========================================================================
+   Base list-box styles
+   ========================================================================== */
+
+.list-box {
+  @apply relative w-full overflow-clip p-1;
+
+  /**
+   * Spacing between direct children.
+   *
+   * NOTE: We intentionally avoid `display: flex` + `gap` here because
+   * react-aria's Virtualizer renders a `position: relative` content
+   * div with an explicit large height (e.g. 50000px) as the only child
+   * of the ListBox. Flex shrinking would collapse that height and break
+   * scrollbar sizing during virtualized scroll.
+   */
+  & > * + * {
+    @apply mt-1;
+  }
+
+  /* This makes the horizontal separator take up 94% of the width and be centered */
+  [data-slot="separator"][data-orientation="horizontal"] {
+    @apply ml-[3%] w-[94%];
+  }
+}
diff --git a/packages/styles/components/menu-item.css b/packages/styles/components/menu-item.css
new file mode 100644
index 0000000..182bb9d
--- /dev/null
+++ b/packages/styles/components/menu-item.css
@@ -0,0 +1,163 @@
+/* ==========================================================================
+   Base menu item styles
+   ========================================================================== */
+
+.menu-item {
+  @apply relative flex min-h-9 w-full items-center justify-start gap-3 rounded-2xl px-2 py-1.5 outline-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    box-shadow 150ms var(--ease-out);
+
+  @apply will-change-transform motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  [data-slot="label"] {
+    @apply pointer-events-none w-fit select-none;
+  }
+
+  [data-slot="description"] {
+    @apply pointer-events-none text-wrap select-none;
+  }
+
+  [data-slot="submenu-indicator"] svg {
+    @apply size-3.5;
+  }
+
+  /* Add inline-start padding when indicator is present */
+  &:has(.menu-item__indicator) {
+    @apply ps-7;
+  }
+
+  /* Add inline-end padding when indicator is present and has submenu */
+  &[data-has-submenu="true"]:has(.menu-item__indicator) {
+    @apply ps-2 pe-7;
+  }
+
+  /* Focus visible state (keyboard focus only) */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.98);
+  }
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default;
+    }
+  }
+
+  /* Selected state */
+  &[aria-checked="true"],
+  &[aria-selected="true"],
+  &[data-selected="true"] {
+    [data-slot="menu-item-indicator--checkmark"] {
+      /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+      transition: stroke-dashoffset 100ms linear;
+      @apply motion-reduce:transition-none;
+    }
+
+    [data-slot="menu-item-indicator--dot"] {
+      /**
+       * Selected state: visible and scaled up
+       */
+      @apply scale-100 opacity-100;
+    }
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   Menu item indicator
+   ========================================================================== */
+
+.menu-item__indicator {
+  @apply absolute start-2 top-1/2 flex size-4 shrink-0 -translate-y-1/2 items-center justify-center text-muted;
+
+  /**
+   * Transitions
+   */
+  @apply transition duration-250 motion-reduce:transition-none;
+
+  /* Position on the inline-end when menu item has submenu */
+  .menu-item[data-has-submenu="true"] & {
+    @apply start-auto end-2;
+  }
+
+  /* Checkmark SVG indicator */
+  [data-slot="menu-item-indicator--checkmark"] {
+    @apply size-2.5;
+
+    .menu-item[data-selection-mode="multiple"] & {
+      /**
+       * Transitions
+       */
+      @apply transition-all duration-300 motion-reduce:transition-none;
+    }
+  }
+
+  /* Dot SVG indicator */
+  [data-slot="menu-item-indicator--dot"] {
+    @apply size-2;
+
+    .menu-item[data-selection-mode="multiple"] & {
+      /**
+     * Transitions
+     */
+      @apply transition-all duration-250 motion-reduce:transition-none;
+    }
+    /**
+     * Default state: hidden and scaled down
+     */
+    @apply scale-70 opacity-0;
+  }
+}
+
+/* Submenu indicator (chevron-right) */
+.menu-item__indicator--submenu {
+  @apply text-muted;
+
+  svg {
+    @apply size-3;
+  }
+}
+
+/* Default variant */
+.menu-item--default {
+}
+
+/* Danger variant */
+.menu-item--danger {
+  .menu-item__indicator {
+    @apply text-danger;
+  }
+
+  [data-slot="label"] {
+    @apply text-danger;
+  }
+}
diff --git a/packages/styles/components/menu-section.css b/packages/styles/components/menu-section.css
new file mode 100644
index 0000000..287eaad
--- /dev/null
+++ b/packages/styles/components/menu-section.css
@@ -0,0 +1,7 @@
+/* ==========================================================================
+   Base menu section styles
+   ========================================================================== */
+
+.menu-section {
+  @apply flex flex-col items-start gap-0;
+}
diff --git a/packages/styles/components/menu.css b/packages/styles/components/menu.css
new file mode 100644
index 0000000..e6991e0
--- /dev/null
+++ b/packages/styles/components/menu.css
@@ -0,0 +1,12 @@
+/* ==========================================================================
+   Base menu styles
+   ========================================================================== */
+
+.menu {
+  @apply relative flex w-full flex-col gap-1 overflow-clip p-1;
+
+  /* This makes the separator take up 94% of the width and be centered */
+  [data-slot="separator"] {
+    @apply ml-[3%] w-[94%];
+  }
+}
diff --git a/packages/styles/components/meter.css b/packages/styles/components/meter.css
new file mode 100644
index 0000000..a16943b
--- /dev/null
+++ b/packages/styles/components/meter.css
@@ -0,0 +1,112 @@
+/* ==========================================================================
+   Meter - A quantity indicator within a known range
+   ========================================================================== */
+
+/* Base styles */
+.meter {
+  @apply grid w-full gap-1;
+  grid-template-areas:
+    "label output"
+    "track track";
+  grid-template-columns: 1fr auto;
+
+  /* Default color tokens (accent) */
+  --meter-fill: var(--accent);
+
+  [data-slot="label"] {
+    @apply w-fit text-sm font-medium;
+
+    grid-area: label;
+  }
+
+  .meter__output {
+    @apply text-sm font-medium tabular-nums;
+
+    grid-area: output;
+  }
+
+  .meter__track {
+    @apply relative overflow-hidden rounded-sm bg-default;
+
+    grid-area: track;
+
+    /* Default height (matches --md) */
+    @apply h-2;
+  }
+
+  .meter__fill {
+    @apply absolute top-0 left-0 h-full rounded-sm;
+
+    background-color: var(--meter-fill);
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition: width 300ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="label"] {
+      @apply opacity-100;
+    }
+  }
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.meter--sm {
+  .meter__track {
+    @apply h-1 rounded-xs;
+  }
+
+  .meter__fill {
+    @apply rounded-xs;
+  }
+}
+
+.meter--md {
+  /* No styles as this is the default size */
+}
+
+.meter--lg {
+  .meter__track {
+    @apply h-3 rounded-md;
+  }
+
+  .meter__fill {
+    @apply rounded-md;
+  }
+}
+
+/* ==========================================================================
+   Color variants
+   ========================================================================== */
+
+.meter--default {
+  --meter-fill: var(--default-foreground);
+}
+
+.meter--accent {
+  --meter-fill: var(--accent);
+}
+
+.meter--success {
+  --meter-fill: var(--success);
+}
+
+.meter--warning {
+  --meter-fill: var(--warning);
+}
+
+.meter--danger {
+  --meter-fill: var(--danger);
+}
diff --git a/packages/styles/components/modal.css b/packages/styles/components/modal.css
new file mode 100644
index 0000000..e0ffdec
--- /dev/null
+++ b/packages/styles/components/modal.css
@@ -0,0 +1,335 @@
+/* -------------------------------------------------------------------------------------------------
+ * Modal Component Styles
+ * Block: modal
+ * -----------------------------------------------------------------------------------------------*/
+
+/**
+ * Element: trigger - the element that opens the modal
+ */
+.modal__trigger {
+  @apply inline-block cursor-(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out-quart),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Active/pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.97);
+  }
+}
+
+/**
+ * Element: backdrop - the overlay behind the dialog
+ */
+.modal__backdrop {
+  @apply fixed inset-0 z-50;
+  @apply flex flex-row items-center justify-center;
+  @apply h-(--visual-viewport-height) w-full;
+
+  /* Entering animation */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-out fade-in-0;
+  }
+
+  /* Exiting animation */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-out fade-out-0;
+  }
+
+  /**
+   * Reduce Animation
+   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
+   */
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply will-change-[opacity];
+    @apply motion-reduce:animate-none;
+  }
+}
+
+/**
+ * Modifier: backdrop--transparent
+ */
+.modal__backdrop--transparent {
+  @apply bg-transparent;
+}
+
+/**
+ * Modifier: backdrop--opaque
+ */
+.modal__backdrop--opaque {
+  @apply bg-backdrop;
+}
+
+/**
+ * Modifier: backdrop--blur
+ */
+.modal__backdrop--blur {
+  @apply bg-backdrop backdrop-blur-md;
+}
+
+/**
+ * Element: container - the positioning wrapper for the modal
+ */
+.modal__container {
+  @apply flex flex-col items-center;
+  @apply h-(--visual-viewport-height) w-full min-w-0 flex-1;
+  @apply p-4;
+  @apply sm:w-fit sm:p-10;
+  @apply pointer-events-none;
+
+  /* Entering animation */
+  &[data-entering="true"] {
+    @apply animate-in duration-250 ease-out-quad fade-in-0 zoom-in-105;
+
+    &[data-placement="auto"] {
+      @apply slide-in-from-bottom-1;
+      @apply sm:slide-in-from-bottom-0;
+    }
+
+    &[data-placement="top"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="center"] {
+      @apply slide-in-from-top-0;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-bottom-1;
+    }
+  }
+
+  /* Exiting animation */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-out-quad fade-out-0 zoom-out-95;
+  }
+
+  /**
+   * Reduce Animation
+   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
+   */
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply will-change-[opacity,transform];
+    @apply motion-reduce:animate-none;
+  }
+}
+
+/**
+ * Modifier: container--scroll-outside
+ */
+.modal__container--scroll-outside {
+  @apply scrollbar overflow-y-auto;
+  @apply pointer-events-auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+/**
+ * Modifier: container--full
+ */
+.modal__container--full {
+  @apply p-0 sm:p-0;
+
+  /* Entering animation */
+  &[data-entering="true"] {
+    @apply slide-in-from-bottom-0 zoom-in-100;
+    @apply sm:slide-in-from-bottom-0;
+  }
+
+  /* Exiting animation */
+  &[data-exiting="true"] {
+    @apply zoom-out-100;
+  }
+}
+
+/**
+ * Element: dialog - the content container for the modal
+ */
+.modal__dialog {
+  @apply relative;
+  @apply flex w-full flex-col;
+  @apply bg-overlay shadow-overlay outline-none;
+  border-radius: min(32px, var(--radius-3xl));
+  @apply p-6;
+  @apply pointer-events-auto;
+
+  &[data-placement="auto"] {
+    @apply mt-auto;
+    @apply sm:my-auto;
+  }
+
+  &[data-placement="center"] {
+    @apply my-auto;
+  }
+
+  &[data-placement="bottom"] {
+    @apply mt-auto;
+  }
+
+  &[data-placement="top"] {
+    @apply mt-0;
+  }
+}
+
+/**
+ * Modifier: dialog--scroll-inside
+ */
+.modal__dialog--scroll-inside {
+  @apply max-h-full min-h-0 overflow-clip;
+}
+
+/**
+ * Modifier: dialog--scroll-outside
+ */
+.modal__dialog--scroll-outside {
+  @apply h-auto;
+  @apply min-h-0 shrink-0;
+}
+
+/**
+ * Modifier: dialog--xs
+ */
+.modal__dialog--xs {
+  @apply max-w-xs;
+}
+
+/**
+ * Modifier: dialog--sm
+ */
+.modal__dialog--sm {
+  @apply max-w-sm;
+}
+
+/**
+ * Modifier: dialog--md
+ */
+.modal__dialog--md {
+  @apply max-w-md;
+}
+
+/**
+ * Modifier: dialog--lg
+ */
+.modal__dialog--lg {
+  @apply max-w-lg;
+}
+
+/**
+ * Modifier: dialog--cover
+ */
+.modal__dialog--cover {
+  @apply h-full min-h-full w-full;
+}
+
+/**
+ * Modifier: dialog--full
+ */
+.modal__dialog--full {
+  @apply h-full min-h-full w-full;
+  @apply rounded-none shadow-none;
+}
+
+/**
+ * Element: header - the top section with the title
+ */
+.modal__header {
+  @apply flex flex-col gap-3;
+  @apply mb-0;
+
+  /* When header contains icon, use flex-col layout with gap */
+  & > .modal__icon {
+    @apply mb-0;
+  }
+}
+
+/**
+ * Element: heading - the main title text
+ */
+.modal__heading {
+  @apply align-middle;
+  @apply text-base font-medium text-foreground;
+}
+
+/**
+ * Element: icon - the optional icon indicator
+ */
+.modal__icon {
+  @apply flex items-center justify-center;
+  @apply size-10 shrink-0;
+  @apply rounded-3xl select-none;
+}
+
+/**
+ * Element: body - the main content area
+ */
+.modal__body {
+  @apply min-h-0 flex-1;
+  @apply text-sm leading-[1.43] text-muted;
+  @apply -m-[3px] my-0 overflow-visible p-[3px];
+}
+
+/**
+ * Modifier: body--scroll-inside
+ */
+.modal__body--scroll-inside {
+  @apply scrollbar overflow-y-auto overscroll-contain;
+  -webkit-overflow-scrolling: touch;
+}
+
+/**
+ * Modifier: body--scroll-outside
+ */
+.modal__body--scroll-outside {
+  @apply overflow-y-visible;
+}
+
+/**
+ * Element: footer - the bottom action section
+ */
+.modal__footer {
+  @apply flex flex-row items-center justify-end gap-2;
+  @apply mt-0;
+}
+
+/**
+ * Element: close-trigger - the optional x icon button to close the modal
+ */
+.modal__close-trigger {
+  @apply absolute top-4 right-4;
+}
+
+/**
+ * Elements Spacing
+ */
+.modal__header + .modal__body {
+  @apply mt-2;
+}
+
+.modal__header + .modal__footer {
+  @apply mt-5;
+}
+
+.modal__body + .modal__footer {
+  @apply mt-5;
+}
diff --git a/packages/styles/components/number-field.css b/packages/styles/components/number-field.css
new file mode 100644
index 0000000..1094ed7
--- /dev/null
+++ b/packages/styles/components/number-field.css
@@ -0,0 +1,220 @@
+/* Number field styles */
+.number-field {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+}
+
+.number-field__group {
+  @apply grid h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+  grid-template-columns: 40px 1fr 40px;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus within state */
+  &[data-focus-within="true"],
+  &:focus-within {
+    @apply status-focused-field;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+    border-color: var(--color-field-border-invalid);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /**
+   * Browser autofill state.
+   * The user-agent paints `:-webkit-autofill`/`:autofill` on the inner <input>
+   * only. Because the input has its border-radius stripped on whichever side
+   * touches the increment/decrement buttons, the autofill highlight ends up
+   * as a sharp-cornered rectangle and the buttons receive no highlight.
+   * Lift the highlight onto the group so the rounded shell + buttons all
+   * share it. (Affects autofilled numeric fields, e.g. OTP/year inputs.)
+   */
+  &:has([data-slot="number-field-input"]:-webkit-autofill),
+  &:has([data-slot="number-field-input"]:autofill) {
+    background-color: var(--field-focus);
+    border-color: var(--field-border-focus);
+  }
+}
+
+.number-field__input {
+  @apply min-w-0 rounded-none border-0 bg-transparent px-3 py-2 text-base tabular-nums shadow-none outline-none sm:text-sm;
+
+  /* Remove border radius on left side when decrement button is present */
+  .number-field__group:has([slot="decrement"]) & {
+    @apply rounded-l-none;
+  }
+
+  /* Remove border radius on right side when increment button is present */
+  .number-field__group:has([slot="increment"]) & {
+    @apply rounded-r-none;
+  }
+
+  /* Focus state - handled by group */
+  &:focus,
+  &:focus-visible {
+    @apply outline-none;
+  }
+
+  /**
+   * Neutralize the browser's per-input autofill paint so the inner <input>
+   * doesn't draw a sharp-cornered yellow rectangle. The unified highlight
+   * is applied to `.number-field__group` above. Preserve the autofilled
+   * text and caret colors, and pin the background-color transition so the
+   * inset box-shadow trick doesn't flicker on state changes.
+   */
+  &:-webkit-autofill,
+  &:-webkit-autofill:hover,
+  &:-webkit-autofill:focus,
+  &:-webkit-autofill:active,
+  &:autofill {
+    -webkit-box-shadow: 0 0 0 1000px transparent inset;
+    box-shadow: 0 0 0 1000px transparent inset;
+    -webkit-text-fill-color: var(--field-foreground);
+    caret-color: var(--field-foreground);
+    transition: background-color 9999s ease-in-out 0s;
+  }
+}
+
+.number-field__increment-button,
+.number-field__decrement-button {
+  @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent text-field-foreground outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+  border-style: solid;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Hover state */
+  &:hover,
+  &[data-hovered="true"] {
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    @apply bg-field-foreground/10;
+    transform: scale(0.97);
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Icon styling */
+  [data-slot="number-field-increment-button-icon"],
+  [data-slot="number-field-decrement-button-icon"] {
+    @apply size-4;
+  }
+}
+
+.number-field__increment-button {
+  @apply rounded-l-none rounded-r-field border-l border-field-placeholder/15;
+}
+
+.number-field__decrement-button {
+  @apply rounded-l-field rounded-r-none border-r border-field-placeholder/15;
+}
+
+/* Variant property definitions */
+.number-field--primary {
+  /* Default styles */
+}
+
+.number-field--secondary .number-field__group {
+  @apply shadow-none;
+  background-color: var(--number-field-group-bg);
+
+  --number-field-group-bg: var(--default);
+  --number-field-group-bg-hover: var(--default-hover);
+  --number-field-group-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      background-color: var(--number-field-group-bg-hover);
+    }
+  }
+
+  &:focus-within,
+  &[data-focus-within="true"] {
+    background-color: var(--number-field-group-bg-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    border-color: var(--color-field-border-invalid);
+    background-color: var(--number-field-group-bg-focus);
+  }
+
+  [data-slot="number-field-input"] {
+    @apply bg-transparent;
+  }
+}
+
+/* Full width modifier */
+.number-field--full-width {
+  @apply w-full;
+}
+
+.number-field__group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/pagination.css b/packages/styles/components/pagination.css
new file mode 100644
index 0000000..56dc477
--- /dev/null
+++ b/packages/styles/components/pagination.css
@@ -0,0 +1,147 @@
+/* ==========================================================================
+   Pagination - Page navigation component
+   ========================================================================== */
+
+/* Base styles */
+.pagination {
+  @apply flex w-full flex-col items-center justify-between gap-4 sm:flex-row;
+}
+
+/* Summary - left side info container */
+.pagination__summary {
+  @apply flex items-center gap-2 self-start text-sm text-muted sm:self-center;
+}
+
+/* Content - container for pagination items */
+.pagination__content {
+  @apply flex items-center gap-1 self-start sm:self-center;
+}
+
+/* Item - list item wrapper */
+.pagination__item {
+  @apply inline-flex;
+}
+
+/* Link - page number button (ghost button style) */
+.pagination__link {
+  @apply relative isolate inline-flex size-9 origin-center items-center justify-center rounded-3xl text-sm font-medium whitespace-nowrap outline-none select-none no-highlight md:size-8;
+
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-smooth),
+    background-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Ghost button tokens */
+  --pagination-link-bg: transparent;
+  --pagination-link-bg-hover: var(--default-hover);
+  --pagination-link-bg-pressed: var(--default-hover);
+  --pagination-link-fg: var(--default-foreground);
+
+  background-color: var(--pagination-link-bg);
+  color: var(--pagination-link-fg);
+
+  /* Focus state */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      background-color: var(--pagination-link-bg-hover);
+    }
+  }
+
+  /* Active / pressed */
+  &:active,
+  &[data-pressed="true"] {
+    background-color: var(--pagination-link-bg-pressed);
+    transform: scale(0.97);
+  }
+
+  /* Active page - tertiary button style */
+  &[data-active="true"] {
+    --pagination-link-bg: var(--default);
+    --pagination-link-bg-hover: var(--default-hover);
+    --pagination-link-bg-pressed: var(--default-hover);
+  }
+}
+
+/* Ellipsis */
+.pagination__ellipsis {
+  @apply inline-flex size-9 items-center justify-center text-sm text-muted select-none md:size-8;
+}
+
+/* Navigation buttons (Previous / Next) */
+.pagination__link--nav {
+  @apply w-auto gap-1.5 px-2.5;
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.pagination--sm {
+  .pagination__link {
+    @apply size-8 text-xs md:size-7;
+
+    &:active,
+    &[data-pressed="true"] {
+      transform: scale(0.98);
+    }
+  }
+
+  .pagination__link--nav {
+    @apply w-auto px-2;
+  }
+
+  .pagination__ellipsis {
+    @apply size-8 text-xs md:size-7;
+  }
+
+  .pagination__summary {
+    @apply text-xs;
+  }
+}
+
+.pagination--md {
+  /* No styles as this is the default size */
+}
+
+.pagination--lg {
+  .pagination__link {
+    @apply size-10 text-base md:size-9;
+
+    &:active,
+    &[data-pressed="true"] {
+      transform: scale(0.96);
+    }
+  }
+
+  .pagination__link--nav {
+    @apply w-auto px-3;
+  }
+
+  .pagination__ellipsis {
+    @apply size-10 text-base md:size-9;
+  }
+
+  .pagination__summary {
+    @apply text-base;
+  }
+}
diff --git a/packages/styles/components/popover.css b/packages/styles/components/popover.css
new file mode 100644
index 0000000..a42da9d
--- /dev/null
+++ b/packages/styles/components/popover.css
@@ -0,0 +1,97 @@
+/* Popover component styles */
+
+/* Base popover styles */
+.popover {
+  @apply origin-(--trigger-anchor-point) bg-overlay p-0 text-sm;
+  border-radius: min(32px, var(--radius-3xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-90;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="popover-overlay-arrow"] {
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="popover-overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="popover-overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="popover-overlay-arrow"] {
+    rotate: 90deg;
+  }
+}
+
+/* Popover dialog */
+.popover__dialog {
+  @apply p-4 outline-none;
+}
+
+/* Popover heading */
+.popover__heading {
+  @apply font-medium;
+}
+
+/* Popover trigger */
+.popover__trigger {
+  @apply inline-block;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 150ms var(--ease-smooth),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
diff --git a/packages/styles/components/progress-bar.css b/packages/styles/components/progress-bar.css
new file mode 100644
index 0000000..ef2b492
--- /dev/null
+++ b/packages/styles/components/progress-bar.css
@@ -0,0 +1,136 @@
+/* ==========================================================================
+   ProgressBar - Shows determinate or indeterminate progress
+   ========================================================================== */
+
+/* Base styles */
+.progress-bar {
+  @apply grid w-full gap-1;
+  grid-template-areas:
+    "label output"
+    "track track";
+  grid-template-columns: 1fr auto;
+
+  /* Default color token (accent) */
+  --progress-bar-fill: var(--accent);
+
+  [data-slot="label"] {
+    @apply w-fit text-sm font-medium;
+
+    grid-area: label;
+  }
+
+  .progress-bar__output {
+    @apply text-sm font-medium tabular-nums;
+
+    grid-area: output;
+  }
+
+  .progress-bar__track {
+    @apply relative overflow-hidden rounded-sm bg-default;
+
+    grid-area: track;
+
+    /* Default height (matches --md) */
+    @apply h-2;
+  }
+
+  .progress-bar__fill {
+    @apply absolute top-0 left-0 h-full rounded-sm;
+
+    background-color: var(--progress-bar-fill);
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition: width 300ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+  }
+
+  /* Indeterminate state - when no aria-valuenow is set */
+  &:not([aria-valuenow]) {
+    .progress-bar__fill {
+      @apply w-2/5;
+
+      animation: progress-bar-indeterminate 1.5s cubic-bezier(0.65, 0, 0.35, 1) infinite;
+
+      @apply motion-reduce:animate-none;
+    }
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="label"] {
+      @apply opacity-100;
+    }
+  }
+}
+
+/* ==========================================================================
+   Indeterminate animation
+   ========================================================================== */
+
+@keyframes progress-bar-indeterminate {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(350%);
+  }
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.progress-bar--sm {
+  .progress-bar__track {
+    @apply h-1 rounded-xs;
+  }
+
+  .progress-bar__fill {
+    @apply rounded-xs;
+  }
+}
+
+.progress-bar--md {
+  /* No styles as this is the default size */
+}
+
+.progress-bar--lg {
+  .progress-bar__track {
+    @apply h-3 rounded-md;
+  }
+
+  .progress-bar__fill {
+    @apply rounded-md;
+  }
+}
+
+/* ==========================================================================
+   Color variants
+   ========================================================================== */
+
+.progress-bar--default {
+  --progress-bar-fill: var(--default-foreground);
+}
+
+.progress-bar--accent {
+  --progress-bar-fill: var(--accent);
+}
+
+.progress-bar--success {
+  --progress-bar-fill: var(--success);
+}
+
+.progress-bar--warning {
+  --progress-bar-fill: var(--warning);
+}
+
+.progress-bar--danger {
+  --progress-bar-fill: var(--danger);
+}
diff --git a/packages/styles/components/progress-circle.css b/packages/styles/components/progress-circle.css
new file mode 100644
index 0000000..ff71e7a
--- /dev/null
+++ b/packages/styles/components/progress-circle.css
@@ -0,0 +1,105 @@
+/* ==========================================================================
+   ProgressCircle - Circular progress indicator
+   ========================================================================== */
+
+/* Base styles */
+.progress-circle {
+  @apply inline-flex items-center justify-center;
+
+  /* Default color token (accent) */
+  --progress-circle-stroke: var(--accent);
+  --progress-circle-track-stroke: var(--default);
+
+  .progress-circle__track {
+    /* Default size (matches --md) */
+    @apply size-7;
+  }
+
+  .progress-circle__track-circle {
+    stroke: var(--progress-circle-track-stroke);
+  }
+
+  .progress-circle__fill-circle {
+    stroke: var(--progress-circle-stroke);
+
+    /**
+     * Transitions
+     * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+     */
+    transition: stroke-dashoffset 300ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+  }
+
+  /* Indeterminate state - when no aria-valuenow is set */
+  &:not([aria-valuenow]) {
+    .progress-circle__track {
+      animation: progress-circle-spin 1s linear infinite;
+
+      @apply motion-reduce:animate-none;
+    }
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* ==========================================================================
+   Indeterminate animation
+   ========================================================================== */
+
+@keyframes progress-circle-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.progress-circle--sm {
+  .progress-circle__track {
+    @apply size-5;
+  }
+}
+
+.progress-circle--md {
+  /* No styles as this is the default size */
+}
+
+.progress-circle--lg {
+  .progress-circle__track {
+    @apply size-9;
+  }
+}
+
+/* ==========================================================================
+   Color variants
+   ========================================================================== */
+
+.progress-circle--default {
+  --progress-circle-stroke: var(--default-foreground);
+}
+
+.progress-circle--accent {
+  --progress-circle-stroke: var(--accent);
+}
+
+.progress-circle--success {
+  --progress-circle-stroke: var(--success);
+}
+
+.progress-circle--warning {
+  --progress-circle-stroke: var(--warning);
+}
+
+.progress-circle--danger {
+  --progress-circle-stroke: var(--danger);
+}
diff --git a/packages/styles/components/radio-group.css b/packages/styles/components/radio-group.css
new file mode 100644
index 0000000..c127cf8
--- /dev/null
+++ b/packages/styles/components/radio-group.css
@@ -0,0 +1,49 @@
+/* Radio Group base styles */
+.radio-group {
+  @apply flex flex-col;
+
+  /* Default orientation */
+  &[data-orientation="vertical"] {
+    [data-slot="radio"] {
+      @apply mt-4;
+    }
+  }
+
+  &[data-orientation="horizontal"] {
+    @apply flex-row flex-wrap gap-4;
+  }
+}
+
+/* Variant property definitions */
+.radio-group--primary {
+  /* Default styles */
+}
+
+.radio-group--secondary .radio__control {
+  @apply shadow-none;
+  background-color: var(--radio-control-bg);
+
+  --radio-control-bg: var(--default);
+  --radio-control-bg-hover: var(--default-hover);
+
+  /* Hover state */
+  .radio:has([data-slot="radio-content"][data-hovered="true"]) &,
+  .radio [data-slot="radio-content"][data-hovered="true"] & {
+    @apply border-field-border-hover;
+  }
+
+  /* Default indicator color (unselected) */
+  .radio:not([data-selected]):not(:has(input:checked)) & .radio__indicator:empty::before {
+    background-color: var(--radio-control-bg);
+  }
+
+  /* Hover indicator color (unselected) */
+  .radio:has([data-slot="radio-content"][data-hovered="true"]):not([data-selected]):not(
+      :has(input:checked)
+    )
+    & {
+    .radio__indicator:empty::before {
+      background-color: var(--radio-control-bg-hover);
+    }
+  }
+}
diff --git a/packages/styles/components/radio.css b/packages/styles/components/radio.css
new file mode 100644
index 0000000..25e6ee6
--- /dev/null
+++ b/packages/styles/components/radio.css
@@ -0,0 +1,183 @@
+/* ==========================================================================
+   Base radio styles
+
+   Structure (explicit composition):
+     .radio                      → RadioField wrapper (column)
+       .radio__content            → RadioButton: the clickable row (control + label)
+         .radio__control
+         [data-slot="label"]
+       [data-slot="description"] → field-level sibling, below the row
+       [data-slot="field-error"]
+   ========================================================================== */
+
+.radio {
+  @apply flex flex-col items-start gap-1 outline-none no-highlight;
+
+  cursor: var(--cursor-interactive);
+
+  [data-slot="label"] {
+    @apply select-none;
+  }
+
+  .radio__content [data-slot="label"] {
+    cursor: var(--cursor-interactive);
+  }
+
+  /* Field-level help text (siblings of the button), indented to align under the label */
+  & > [data-slot="description"],
+  & > [data-slot="field-error"] {
+    @apply w-full min-w-0 cursor-default ps-7 text-xs text-wrap wrap-break-word text-muted select-none;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="description"],
+    [data-slot="field-error"] {
+      @apply status-disabled;
+    }
+  }
+}
+
+/* Radio content — the clickable label (control + label text) */
+.radio__content {
+  @apply relative inline-flex cursor-[inherit] items-center gap-3 text-sm font-medium text-foreground outline-none select-none no-highlight;
+}
+
+/* ==========================================================================
+   Radio control (the circular button)
+   ========================================================================== */
+
+.radio__control {
+  @apply relative inline-flex size-4 shrink-0 items-center justify-center rounded-lg border [border-width:var(--border-width-field)] border-field-border bg-field shadow-field outline-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 200ms var(--ease-out),
+    border-color 200ms var(--ease-out),
+    transform 100ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Interactive states */
+  /* Focus */
+  .radio:has([data-slot="radio-content"][data-focus-visible="true"]) &,
+  .radio [data-slot="radio-content"][data-focus-visible="true"] & {
+    @apply status-focused;
+  }
+
+  /* Hover */
+  .radio:has([data-slot="radio-content"][data-hovered="true"]) &,
+  .radio [data-slot="radio-content"][data-hovered="true"] & {
+    @apply border-field-border-hover;
+  }
+
+  /* Hover - only when not selected */
+  .radio:has([data-slot="radio-content"][data-hovered="true"]):not([data-selected]):not(
+      :has(input:checked)
+    )
+    & {
+    .radio__indicator:empty::before {
+      @apply bg-field-hover;
+    }
+  }
+
+  /* Pressed */
+  .radio:has([data-slot="radio-content"][data-pressed="true"]) &,
+  .radio [data-slot="radio-content"][data-pressed="true"] & {
+    @apply scale-95;
+  }
+
+  /* Selection states */
+  /* Selected */
+  .radio[data-selected] &,
+  .radio:has([data-slot="radio-content"][aria-checked="true"]) &,
+  .radio:has(input:checked) & {
+    @apply border-transparent bg-accent;
+  }
+
+  /* Selected + Pressed */
+  .radio[data-selected]:has([data-slot="radio-content"][data-pressed="true"]) &,
+  .radio:has([data-slot="radio-content"][data-pressed="true"][aria-checked="true"]) &,
+  .radio:has(input:checked):has([data-slot="radio-content"][data-pressed="true"]) & {
+    @apply bg-accent-hover;
+  }
+
+  /* Validation states */
+  /* Invalid */
+  .radio[data-invalid="true"] &,
+  .radio[aria-invalid="true"] & {
+    @apply status-invalid-field;
+  }
+
+  /* Invalid + Selected */
+  .radio[data-invalid="true"][data-selected] &,
+  .radio[aria-invalid="true"][data-selected] &,
+  .radio[data-invalid="true"]:has(input:checked) &,
+  .radio[aria-invalid="true"]:has(input:checked) & {
+    @apply status-invalid-field;
+  }
+}
+
+/* ==========================================================================
+   Radio indicator (the inner dot)
+   ========================================================================== */
+
+.radio__indicator {
+  @apply absolute inset-0 flex items-center justify-center;
+
+  pointer-events: none;
+}
+
+/* :empty pseudo-class ensures these styles only apply when the indicator has no custom children
+   (e.g., custom icon). When custom content is present, these default dot styles are not applied. */
+.radio__indicator:empty::before {
+  content: "";
+  @apply rounded-lg bg-field;
+
+  width: 100%;
+  height: 100%;
+  scale: 1;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    scale 200ms var(--ease-out),
+    background-color 200ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+}
+
+/* Selected state */
+.radio[data-selected] .radio__indicator:empty::before,
+.radio:has([data-slot="radio-content"][aria-checked="true"]) .radio__indicator:empty::before,
+.radio:has(input:checked) .radio__indicator:empty::before {
+  @apply bg-accent-foreground;
+  scale: 0.4286; /* 6px */
+}
+
+/* Selected + Pressed state */
+.radio[data-selected]:has([data-slot="radio-content"][data-pressed="true"])
+  .radio__indicator:empty::before,
+.radio:has([data-slot="radio-content"][data-pressed="true"][aria-checked="true"])
+  .radio__indicator:empty::before,
+.radio:has(input:checked):has([data-slot="radio-content"][data-pressed="true"])
+  .radio__indicator:empty::before {
+  scale: 0.5714; /* 8px */
+}
+
+/* ==========================================================================
+   Disabled modifier
+   ========================================================================== */
+
+.radio--disabled {
+  @apply status-disabled;
+}
diff --git a/packages/styles/components/range-calendar.css b/packages/styles/components/range-calendar.css
new file mode 100644
index 0000000..f84924d
--- /dev/null
+++ b/packages/styles/components/range-calendar.css
@@ -0,0 +1,361 @@
+/* =============================================================================
+ * RangeCalendar Component Styles
+ *
+ * A compound component for contiguous date range selection.
+ * Uses BEM naming convention: range-calendar, range-calendar__element, range-calendar--modifier
+ * ============================================================================= */
+
+/* -----------------------------------------------------------------------------
+ * Base RangeCalendar Styles
+ * -------------------------------------------------------------------------- */
+.range-calendar {
+  @apply w-63 max-w-63;
+
+  container-type: inline-size;
+}
+
+/* Week view – visibleDuration={{ weeks: n }} */
+.range-calendar--week-view {
+  .range-calendar__cell {
+    /* Keep cells circular on the 7-column grid; only filled cells take space. */
+    @apply aspect-square size-auto w-full place-self-center;
+  }
+}
+
+/* Day view – visibleDuration={{ days: n }} */
+.range-calendar--day-view {
+  .range-calendar__cell {
+    @apply aspect-square size-auto w-full place-self-center;
+  }
+
+  /*
+   * Isolate header and body into separate 7-column grids. With display:contents
+   * on the root grid, fewer than 7 weekday headers flow into the same row as dates.
+   */
+  .range-calendar__grid {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .range-calendar__grid-header {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    @apply w-full;
+
+    & > tr {
+      display: contents;
+    }
+  }
+
+  .range-calendar__grid-body {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    @apply mt-1 w-full;
+
+    & > tr {
+      display: contents;
+    }
+
+    & > tr:first-child > td {
+      @apply mt-0;
+    }
+  }
+}
+
+/* -----------------------------------------------------------------------------
+ * RangeCalendar Header
+ * -------------------------------------------------------------------------- */
+.range-calendar__header {
+  @apply flex items-center justify-between px-0.5 pb-4;
+
+  &:has(.calendar-year-picker__trigger[data-open="true"]) {
+    .range-calendar__nav-button {
+      @apply pointer-events-none opacity-0;
+    }
+  }
+}
+
+.range-calendar__heading {
+  @apply flex-1 text-sm font-medium;
+}
+
+.range-calendar__nav-button {
+  @apply flex size-6 items-center justify-center rounded-xl text-accent-soft-foreground;
+
+  will-change: scale;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-out),
+    background-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out),
+    opacity 150ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  cursor: var(--cursor-interactive);
+
+  /* Hover state – only on devices that support hover (avoids false triggers on touch) */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default text-accent-soft-foreground;
+    }
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.95);
+  }
+
+  /* Focus state */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+.range-calendar__nav-button-icon {
+  @apply size-4;
+}
+
+/* -----------------------------------------------------------------------------
+ * RangeCalendar Grid
+ * -------------------------------------------------------------------------- */
+.range-calendar__grid {
+  /* Override table display with CSS Grid for easier customization */
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  @apply w-full;
+
+  &[aria-readonly="true"] {
+    .range-calendar__cell {
+      @apply pointer-events-none;
+    }
+  }
+}
+
+.range-calendar__grid-header {
+  /* Grid header (thead) styles */
+  display: contents;
+
+  & > tr {
+    display: contents;
+  }
+}
+
+.range-calendar__grid-body {
+  /* Grid body (tbody) styles */
+  display: contents;
+
+  & > tr {
+    display: contents;
+  }
+
+  /* Add top spacing between header and first body row */
+  & > tr:first-child > td {
+    @apply mt-1;
+  }
+}
+
+.range-calendar__grid-row {
+  /* Use 'contents' so cells participate directly in grid */
+  /* Note: This class can be used for custom row styling if needed */
+  display: contents;
+}
+
+.range-calendar__header-cell {
+  /* Header cell (th - weekday names) styles */
+  @apply flex items-center justify-center pb-2 text-xs font-medium text-muted;
+}
+
+/* -----------------------------------------------------------------------------
+ * RangeCalendar Cells
+ * -------------------------------------------------------------------------- */
+.range-calendar__cell {
+  @apply relative z-1 mx-0 my-[2px] rounded-3xl p-0 outline-none;
+  cursor: var(--cursor-interactive);
+
+  will-change: background-color, border-color;
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    box-shadow 100ms var(--ease-out),
+    border-color 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Inner interactive circle/capsule (equivalent to React Aria "button-base") */
+  .range-calendar__cell-button {
+    @apply flex aspect-square w-full items-center justify-center rounded-3xl text-sm font-medium text-foreground no-highlight;
+
+    will-change: scale;
+    transition: scale 200ms var(--ease-out);
+    @apply transform-gpu motion-reduce:transition-none;
+  }
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply z-2;
+
+    .range-calendar__cell-button {
+      @apply status-focused;
+    }
+  }
+
+  /* Today indicator */
+  &[data-today="true"] {
+    .range-calendar__cell-button {
+      @apply bg-accent-soft text-accent-soft-foreground;
+    }
+
+    @media (hover: hover) {
+      &:hover:not([data-selected="true"]),
+      &[data-hovered="true"]:not([data-selected="true"]) {
+        .range-calendar__cell-button {
+          @apply bg-accent-soft-hover;
+        }
+      }
+    }
+  }
+
+  /* Range selected track (middle segment) */
+  &[data-selected="true"]:not([data-outside-month="true"]) {
+    @apply rounded-none bg-accent-soft;
+  }
+
+  /* Round row boundaries so the range track looks continuous across weeks */
+  &[data-selected="true"]:is(td:first-child > *, [aria-disabled] + td > *) {
+    @apply rounded-ss-lg rounded-es-lg;
+    &[data-selection-start="true"] {
+      @apply rounded-ss-3xl rounded-es-3xl;
+    }
+  }
+
+  &[data-selected="true"]:is(td:last-child > *, td:has(+ [aria-disabled]) > *) {
+    @apply rounded-se-lg rounded-ee-lg;
+    &[data-selection-end="true"] {
+      @apply rounded-se-3xl rounded-ee-3xl;
+    }
+  }
+
+  /* Range caps (start/end) */
+  &[data-selection-start="true"]:not([data-outside-month="true"]),
+  &[data-selection-end="true"]:not([data-outside-month="true"]) {
+    @apply z-2;
+
+    .range-calendar__cell-button {
+      @apply bg-accent text-accent-foreground;
+    }
+  }
+
+  /* &[data-selection-start="true"]:has(+ [data-selection-end="true"]) {
+    @apply rounded-full;
+  } */
+
+  &[data-selection-start="true"]:not([data-outside-month="true"]) {
+    @apply rounded-tl-3xl rounded-bl-3xl;
+  }
+
+  &[data-selection-end="true"]:not([data-outside-month="true"]) {
+    @apply rounded-tr-3xl rounded-br-3xl;
+  }
+
+  /* Pressed state */
+  &:active,
+  &[data-pressed="true"] {
+    .range-calendar__cell-button {
+      scale: 0.9;
+    }
+
+    &[data-selection-start="true"],
+    &[data-selection-end="true"] {
+      .range-calendar__cell-button {
+        @apply bg-accent-hover;
+      }
+    }
+  }
+
+  /* Hover state for non-selected days */
+  @media (hover: hover) {
+    &:hover:not([data-selected="true"]),
+    &[data-hovered="true"]:not([data-selected="true"]) {
+      .range-calendar__cell-button {
+        @apply bg-default;
+      }
+    }
+  }
+
+  /* Outside month (previous/next month days) */
+  &[data-outside-month="true"] {
+    @apply text-muted opacity-50;
+  }
+
+  &[data-selected="true"][data-outside-month="true"]:not(
+      [data-selection-start="true"],
+      [data-selection-end="true"]
+    ) {
+    @apply bg-default/20;
+  }
+
+  /* Unavailable dates */
+  &[data-unavailable="true"] {
+    @apply status-disabled;
+  }
+
+  /* Disabled state */
+  &:disabled:not([data-outside-month="true"]),
+  &[data-disabled="true"]:not([data-outside-month="true"]) {
+    @apply status-disabled;
+
+    text-decoration: line-through;
+  }
+}
+
+/* Outside-month cell followed by selected cell across adjacent table cells */
+.range-calendar__grid-body
+  td:has(> .range-calendar__cell[data-outside-month="true"])
+  + td
+  > .range-calendar__cell[data-selected="true"] {
+  @apply rounded-ss-lg rounded-es-lg;
+
+  &[data-outside-month="true"],
+  &[data-selection-start="true"] {
+    @apply rounded-ss-3xl rounded-es-3xl;
+  }
+}
+
+/* Selected cell followed by outside-month cell across adjacent table cells */
+.range-calendar__grid-body
+  td:has(> .range-calendar__cell[data-selected="true"]):has(
+    + td > .range-calendar__cell[data-outside-month="true"]
+  )
+  > .range-calendar__cell[data-selected="true"] {
+  @apply rounded-se-lg rounded-ee-lg;
+
+  &[data-outside-month="true"],
+  &[data-selection-end="true"] {
+    @apply rounded-se-3xl rounded-ee-3xl;
+  }
+}
+
+/* Cell indicator - small dot at bottom center of cell */
+.range-calendar__cell-indicator {
+  @apply absolute bottom-1 left-1/2 size-[3px] -translate-x-1/2 rounded-xs bg-muted;
+
+  /* Indicator color changes when cell is selected */
+  [data-selected="true"] > & {
+    @apply bg-accent-foreground;
+  }
+}
diff --git a/packages/styles/components/scroll-shadow.css b/packages/styles/components/scroll-shadow.css
new file mode 100644
index 0000000..20b445b
--- /dev/null
+++ b/packages/styles/components/scroll-shadow.css
@@ -0,0 +1,93 @@
+/* Base scroll-shadow component */
+.scroll-shadow {
+  @apply relative;
+  --scroll-shadow-size: 40px;
+  --scroll-shadow-scrollbar-size: 10px;
+}
+
+/* Orientation: Vertical */
+.scroll-shadow--vertical {
+  @apply scrollbar overflow-y-auto;
+}
+
+/* Orientation: Horizontal */
+.scroll-shadow--horizontal {
+  @apply scrollbar overflow-x-auto;
+}
+
+/* Variant: Fade - Vertical */
+.scroll-shadow--fade.scroll-shadow--vertical {
+  &:where([data-top-scroll="true"], [data-bottom-scroll="true"], [data-top-bottom-scroll="true"]) {
+    mask-image: linear-gradient(var(--scroll-linear-gradient)), linear-gradient(#000, #000);
+    mask-position:
+      left top,
+      right top;
+    mask-repeat: no-repeat;
+    mask-size:
+      calc(100% - var(--scroll-shadow-scrollbar-size)) 100%,
+      var(--scroll-shadow-scrollbar-size) 100%;
+    -webkit-mask-image: linear-gradient(var(--scroll-linear-gradient)), linear-gradient(#000, #000);
+    -webkit-mask-position:
+      left top,
+      right top;
+    -webkit-mask-repeat: no-repeat;
+    -webkit-mask-size:
+      calc(100% - var(--scroll-shadow-scrollbar-size)) 100%,
+      var(--scroll-shadow-scrollbar-size) 100%;
+  }
+
+  &[data-top-scroll="true"] {
+    --scroll-linear-gradient: 0deg, #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+
+  &[data-bottom-scroll="true"] {
+    --scroll-linear-gradient: 180deg, #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+
+  &[data-top-bottom-scroll="true"] {
+    --scroll-linear-gradient:
+      #000, #000, transparent 0, #000 var(--scroll-shadow-size),
+      #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+}
+
+/* Variant: Fade - Horizontal */
+.scroll-shadow--fade.scroll-shadow--horizontal {
+  &:where([data-left-scroll="true"], [data-right-scroll="true"], [data-left-right-scroll="true"]) {
+    mask-image: linear-gradient(var(--scroll-linear-gradient)), linear-gradient(#000, #000);
+    mask-position:
+      left top,
+      left bottom;
+    mask-repeat: no-repeat;
+    mask-size:
+      100% calc(100% - var(--scroll-shadow-scrollbar-size)),
+      100% var(--scroll-shadow-scrollbar-size);
+    -webkit-mask-image: linear-gradient(var(--scroll-linear-gradient)), linear-gradient(#000, #000);
+    -webkit-mask-position:
+      left top,
+      left bottom;
+    -webkit-mask-repeat: no-repeat;
+    -webkit-mask-size:
+      100% calc(100% - var(--scroll-shadow-scrollbar-size)),
+      100% var(--scroll-shadow-scrollbar-size);
+  }
+
+  &[data-left-scroll="true"] {
+    --scroll-linear-gradient: 270deg, #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+
+  &[data-right-scroll="true"] {
+    --scroll-linear-gradient: 90deg, #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+
+  &[data-left-right-scroll="true"] {
+    --scroll-linear-gradient:
+      to right, #000, #000, transparent 0, #000 var(--scroll-shadow-size),
+      #000 calc(100% - var(--scroll-shadow-size)), transparent;
+  }
+}
+
+.scroll-shadow--hide-scrollbar {
+  @apply scrollbar-none;
+  --scroll-shadow-scrollbar-size: 0px;
+}
diff --git a/packages/styles/components/search-field.css b/packages/styles/components/search-field.css
new file mode 100644
index 0000000..c4cb3b6
--- /dev/null
+++ b/packages/styles/components/search-field.css
@@ -0,0 +1,186 @@
+/* Search field styles */
+.search-field {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+
+  &[data-empty="true"] {
+    [data-slot="search-field-clear-button"] {
+      @apply pointer-events-none opacity-0;
+    }
+  }
+}
+
+.search-field__group {
+  @apply relative inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus within state */
+  &[data-focus-within="true"],
+  &:focus-within {
+    @apply status-focused-field;
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+    border-color: var(--color-field-border-invalid);
+  }
+
+  /* Disabled state */
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /**
+   * Browser autofill state.
+   * The user-agent paints `:-webkit-autofill`/`:autofill` on the inner <input>
+   * only. Because the input has its border-radius stripped on whichever side
+   * touches the search icon or clear button, the autofill highlight ends up
+   * as a sharp-cornered rectangle and the sibling slots receive no highlight.
+   * Lift the highlight onto the group so the rounded shell + icon + clear
+   * button all share it.
+   */
+  &:has([data-slot="search-field-input"]:-webkit-autofill),
+  &:has([data-slot="search-field-input"]:autofill) {
+    background-color: var(--field-focus);
+    border-color: var(--field-border-focus);
+  }
+}
+
+.search-field__input {
+  @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 text-base shadow-none outline-none sm:text-sm;
+
+  /* Hide browser default search clear button */
+  &::-webkit-search-cancel-button,
+  &::-webkit-search-decoration {
+    -webkit-appearance: none;
+    appearance: none;
+  }
+
+  /* Remove border radius on left side when search icon is present */
+  .search-field__group:has([data-slot="search-field-search-icon"]) & {
+    @apply rounded-l-none pl-2;
+  }
+
+  /* Remove border radius on right side when clear button is present */
+  .search-field__group:has([slot="clear"]) & {
+    @apply rounded-r-none pr-2;
+  }
+
+  /* Focus state - handled by group */
+  &:focus,
+  &:focus-visible {
+    @apply outline-none;
+  }
+
+  /**
+   * Neutralize the browser's per-input autofill paint so the inner <input>
+   * doesn't draw a sharp-cornered yellow rectangle. The unified highlight
+   * is applied to `.search-field__group` above. Preserve the autofilled
+   * text and caret colors, and pin the background-color transition so the
+   * inset box-shadow trick doesn't flicker on state changes.
+   */
+  &:-webkit-autofill,
+  &:-webkit-autofill:hover,
+  &:-webkit-autofill:focus,
+  &:-webkit-autofill:active,
+  &:autofill {
+    -webkit-box-shadow: 0 0 0 1000px transparent inset;
+    box-shadow: 0 0 0 1000px transparent inset;
+    -webkit-text-fill-color: var(--field-foreground);
+    caret-color: var(--field-foreground);
+    transition: background-color 9999s ease-in-out 0s;
+  }
+}
+
+.search-field__search-icon {
+  @apply pointer-events-none shrink-0 text-field-placeholder;
+  @apply mr-0 ml-3 size-4;
+}
+
+.search-field__clear-button {
+  @apply mr-2 size-5 shrink-0;
+
+  /* Overrides close button default icon size from 16px to 12px */
+  [data-slot="close-button-icon"] {
+    @apply size-3;
+  }
+}
+
+/* Variant property definitions */
+.search-field--primary {
+  /* Default styles */
+}
+
+.search-field--secondary .search-field__group {
+  @apply shadow-none;
+  background-color: var(--search-field-group-bg);
+
+  --search-field-group-bg: var(--default);
+  --search-field-group-bg-hover: var(--default-hover);
+  --search-field-group-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus-within),
+    &[data-hovered="true"]:not([data-focus-within="true"]) {
+      background-color: var(--search-field-group-bg-hover);
+    }
+  }
+
+  &:focus-within,
+  &[data-focus-within="true"] {
+    background-color: var(--search-field-group-bg-focus);
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    border-color: var(--color-field-border-invalid);
+    background-color: var(--search-field-group-bg-focus);
+  }
+
+  [data-slot="search-field-input"] {
+    @apply bg-transparent;
+  }
+}
+
+/* Full width modifier */
+.search-field--full-width {
+  @apply w-full;
+}
+
+.search-field__group--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/select.css b/packages/styles/components/select.css
new file mode 100644
index 0000000..1b9710b
--- /dev/null
+++ b/packages/styles/components/select.css
@@ -0,0 +1,225 @@
+/* Select styles */
+.select {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+}
+
+.select__trigger {
+  @apply relative isolate inline-flex min-h-9 rounded-field border bg-field px-3 py-2 text-sm text-field-foreground shadow-field outline-none select-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /* Add inline-end padding when indicator is present */
+  &:has(.select__indicator) {
+    @apply pe-7;
+  }
+
+  /* Hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  /* Invalid state */
+  .select[data-invalid="true"] &,
+  .select[aria-invalid="true"] & {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* Variant property definitions */
+.select--primary {
+  /* Default styles */
+}
+
+.select--secondary .select__trigger {
+  @apply shadow-none;
+  background-color: var(--select-trigger-bg);
+
+  --select-trigger-bg: var(--default);
+  --select-trigger-bg-hover: var(--default-hover);
+  --select-trigger-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      background-color: var(--select-trigger-bg-hover);
+    }
+  }
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    background-color: var(--select-trigger-bg-focus);
+  }
+
+  &:focus,
+  &[data-focus="true"] {
+  }
+
+  .select[data-invalid="true"] &,
+  .select[aria-invalid="true"] & {
+    background-color: var(--select-trigger-bg-focus);
+  }
+}
+
+.select__value {
+  @apply flex-1 text-start text-base wrap-break-word text-current sm:text-sm;
+
+  &[data-placeholder="true"] {
+    @apply text-field-placeholder;
+  }
+
+  /* Removes the list-box-item indicator element from the select value*/
+  [data-slot="list-box-item-indicator"] {
+    @apply hidden;
+  }
+}
+
+.select__indicator {
+  @apply absolute inset-y-0 end-2 my-auto flex shrink-0 items-center justify-center text-field-placeholder transition duration-150;
+
+  &[data-open="true"] {
+    @apply rotate-180;
+  }
+
+  &[data-slot="select-default-indicator"] {
+    @apply size-4;
+  }
+}
+
+/* Similar to popover content styles */
+.select__popover {
+  @apply min-w-(--trigger-width) origin-(--trigger-anchor-point) scroll-py-1 overflow-y-auto overscroll-contain bg-overlay p-0 text-sm scrollbar;
+  border-radius: min(32px, var(--radius-3xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-95;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="popover-overlay-arrow"] {
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="popover-overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="popover-overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="popover-overlay-arrow"] {
+    rotate: 90deg;
+  }
+
+  /* Listbox styles */
+  [data-slot="list-box"] {
+    @apply p-1.5 outline-none;
+  }
+
+  [data-slot="list-box-item"] {
+    @apply px-2.5;
+  }
+
+  /* As the popover closes fast in single-select mode, the default item indicator transition is not even visible - so we disable it only for single-select */
+  [data-slot="list-box"]:not([aria-multiselectable="true"]) [data-slot="list-box-item-indicator"],
+  [data-slot="list-box"]:not([aria-multiselectable="true"])
+    [data-slot="list-box-item-indicator"]
+    [data-slot="list-box-item-indicator--checkmark"] {
+    @apply transition-none;
+  }
+}
+
+/* Full width modifier */
+.select--full-width {
+  @apply w-full;
+}
+
+.select__trigger--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/separator.css b/packages/styles/components/separator.css
new file mode 100644
index 0000000..6d69a91
--- /dev/null
+++ b/packages/styles/components/separator.css
@@ -0,0 +1,59 @@
+/* Separator Component Styles */
+
+/* Base separator with default horizontal orientation */
+.separator {
+  @apply shrink-0 rounded-sm border-t-0 border-b-0 bg-separator;
+
+  /* Default size - horizontal orientation */
+  @apply h-px w-full;
+}
+
+/* Orientation variants */
+.separator--horizontal {
+  @apply h-px w-full;
+}
+
+.separator--vertical {
+  @apply h-auto min-h-2 w-px self-stretch;
+}
+
+/* Color variants */
+.separator--default {
+  @apply bg-separator;
+}
+
+.separator--secondary {
+  @apply bg-separator-secondary;
+}
+
+.separator--tertiary {
+  @apply bg-separator-tertiary;
+}
+
+.separator__container {
+  @apply flex items-center gap-3;
+}
+
+.separator__container--horizontal {
+  @apply w-full flex-row;
+}
+
+.separator__container--vertical {
+  @apply h-full flex-col justify-center;
+}
+
+.separator__line {
+  @apply shrink-0 grow;
+}
+
+.separator__content {
+  @apply inline-flex items-center justify-center text-center whitespace-nowrap text-muted;
+}
+
+.separator__content--horizontal {
+  @apply text-center;
+}
+
+.separator__content--vertical {
+  @apply text-center;
+}
diff --git a/packages/styles/components/skeleton.css b/packages/styles/components/skeleton.css
new file mode 100644
index 0000000..4f33db7
--- /dev/null
+++ b/packages/styles/components/skeleton.css
@@ -0,0 +1,48 @@
+.skeleton {
+  @apply pointer-events-none relative overflow-hidden rounded-sm bg-surface-tertiary/70;
+}
+
+/* TODO: Skeleton with parent are not visible */
+
+/* Animation types */
+.skeleton--shimmer {
+  &::after {
+    @apply absolute inset-0 -translate-x-full animate-skeleton bg-linear-to-r from-transparent via-surface-tertiary to-transparent content-[''];
+  }
+
+  /* When applied to a parent container with multiple skeletons */
+  &:has(.skeleton) {
+    &::after {
+      content: none;
+    }
+
+    /* Single synchronized shimmer that passes over all children */
+    &::before {
+      @apply absolute inset-0 -translate-x-full animate-skeleton content-[''];
+      background: linear-gradient(
+        90deg,
+        transparent 0%,
+        rgba(255, 255, 255, 0.5) 50%,
+        transparent 100%
+      );
+      z-index: 10;
+      pointer-events: none;
+      /* Use mix-blend-mode to only show over skeleton elements */
+      mix-blend-mode: overlay;
+    }
+
+    /* Ensure children don't have their own shimmer */
+    & .skeleton {
+      &::after {
+        content: none;
+      }
+    }
+  }
+}
+
+.skeleton--pulse {
+  @apply animate-pulse;
+}
+
+.skeleton--none {
+}
diff --git a/packages/styles/components/slider.css b/packages/styles/components/slider.css
new file mode 100644
index 0000000..6ffd4d5
--- /dev/null
+++ b/packages/styles/components/slider.css
@@ -0,0 +1,179 @@
+/* Slider styles */
+
+.slider {
+  @apply grid w-full gap-1;
+
+  grid-template-areas:
+    "label output"
+    "track track";
+  grid-template-columns: 1fr auto;
+
+  [data-slot="label"] {
+    @apply w-fit text-sm font-medium;
+
+    grid-area: label;
+  }
+
+  .slider__output {
+    @apply text-sm font-medium tabular-nums;
+
+    grid-area: output;
+  }
+
+  .slider__track {
+    @apply relative rounded-xl bg-default;
+
+    grid-area: track;
+  }
+
+  .slider__fill {
+    @apply pointer-events-none absolute bg-accent;
+  }
+
+  .slider__thumb {
+    /* Flex container for centering pseudo-elements */
+    @apply absolute flex cursor-grab items-center justify-center rounded-xl bg-accent no-highlight;
+
+    /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+    transition:
+      background-color 250ms var(--ease-smooth),
+      transform 250ms var(--ease-out),
+      box-shadow 150ms var(--ease-out);
+    @apply motion-reduce:transition-none;
+
+    /* after: Visible thumb element */
+    &::after {
+      @apply relative z-10 rounded-lg bg-accent-foreground text-black shadow-field;
+      content: "";
+
+      /**
+       * Transitions
+       */
+      @apply origin-center transition-all motion-reduce:transition-none;
+    }
+
+    /* Dragging state - cursor changes and thumb scales down */
+    &[data-dragging="true"] {
+      @apply cursor-grabbing;
+
+      &::after {
+        @apply scale-[0.9] motion-reduce:scale-100;
+      }
+    }
+
+    /* Focus state - increase z-index */
+    &[data-focus-visible="true"] {
+      @apply z-10 status-focused;
+    }
+
+    /* Disabled state */
+    &[data-disabled="true"] {
+      @apply cursor-default;
+    }
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="label"] {
+      @apply opacity-100;
+    }
+  }
+
+  /* Horizontal orientation */
+  &[data-orientation="horizontal"] {
+    flex-direction: column;
+
+    .slider__track {
+      @apply h-5 w-full;
+      /* Add transparent borders to provide space for thumb at edges */
+      /* Thumb width is 1.5rem (24px), so half is 0.75rem (12px) */
+      @apply border-x-[0.75rem] border-x-transparent;
+
+      &[data-fill-start="true"] {
+        @apply border-s-accent;
+      }
+
+      &[data-fill-end="true"] {
+        @apply border-e-accent;
+      }
+    }
+
+    .slider__fill,
+    .slider__thumb {
+      @apply h-full;
+    }
+
+    .slider__thumb {
+      @apply top-1/2;
+
+      /* Thumb width + border width */
+      width: calc(1.5rem + 0.25rem);
+
+      &::after {
+        width: 1.5rem;
+        height: 1rem;
+      }
+    }
+  }
+
+  /* Vertical orientation */
+  &[data-orientation="vertical"] {
+    @apply h-full gap-2;
+
+    flex-direction: row;
+    grid-template-areas:
+      "output"
+      "track"
+      "label";
+    grid-template-rows: auto 1fr auto;
+    grid-template-columns: 1fr;
+
+    .slider__output {
+      text-align: center;
+    }
+
+    [data-slot="label"] {
+      text-align: center;
+    }
+
+    .slider__track {
+      @apply h-full w-5;
+      /* Add transparent borders to provide space for thumb at edges */
+      /* Thumb height is 1.5rem (24px), so half is 0.75rem (12px) */
+      @apply border-y-[0.75rem] border-y-transparent;
+      justify-self: center;
+
+      &[data-fill-start="true"] {
+        @apply border-b-accent;
+      }
+
+      &[data-fill-end="true"] {
+        @apply border-t-accent;
+      }
+    }
+
+    .slider__fill,
+    .slider__thumb {
+      @apply w-full;
+    }
+
+    .slider__thumb {
+      @apply left-1/2;
+
+      /* Thumb height + border height */
+      height: calc(1.5rem + 0.25rem);
+
+      &::after {
+        width: 1rem;
+        height: 1.5rem;
+      }
+    }
+  }
+}
diff --git a/packages/styles/components/spinner.css b/packages/styles/components/spinner.css
new file mode 100644
index 0000000..b9d77ca
--- /dev/null
+++ b/packages/styles/components/spinner.css
@@ -0,0 +1,42 @@
+/* Base spinner styles */
+.spinner {
+  @apply pointer-events-none inline-flex size-6 shrink-0 animate-spin-fast motion-reduce:animate-none;
+}
+
+/* Size variants */
+.spinner--sm {
+  @apply size-4;
+}
+
+.spinner--md {
+  /* No styles as this is the default size */
+}
+
+.spinner--lg {
+  @apply size-8;
+}
+
+.spinner--xl {
+  @apply size-10;
+}
+
+/* Color variants */
+.spinner--current {
+  color: inherit;
+}
+
+.spinner--accent {
+  color: var(--accent);
+}
+
+.spinner--danger {
+  color: var(--danger);
+}
+
+.spinner--success {
+  color: var(--success);
+}
+
+.spinner--warning {
+  color: var(--warning);
+}
diff --git a/packages/styles/components/surface.css b/packages/styles/components/surface.css
new file mode 100644
index 0000000..52a653f
--- /dev/null
+++ b/packages/styles/components/surface.css
@@ -0,0 +1,23 @@
+/* Surface component styles */
+
+/* Block */
+.surface {
+  @apply relative text-foreground;
+}
+
+/* Modifier - variant */
+.surface--transparent {
+  @apply bg-transparent;
+}
+
+.surface--default {
+  @apply bg-surface text-surface-foreground;
+}
+
+.surface--secondary {
+  @apply bg-surface-secondary text-surface-secondary-foreground;
+}
+
+.surface--tertiary {
+  @apply bg-surface-tertiary text-surface-tertiary-foreground;
+}
diff --git a/packages/styles/components/switch-group.css b/packages/styles/components/switch-group.css
new file mode 100644
index 0000000..f1d4e07
--- /dev/null
+++ b/packages/styles/components/switch-group.css
@@ -0,0 +1,17 @@
+/* Switch Group styles */
+.switch-group {
+  @apply flex flex-col gap-6;
+}
+
+.switch-group__items {
+  @apply flex gap-4;
+}
+
+/* Orientation modifiers */
+.switch-group--horizontal .switch-group__items {
+  @apply flex-row;
+}
+
+.switch-group--vertical .switch-group__items {
+  @apply flex-col;
+}
diff --git a/packages/styles/components/switch.css b/packages/styles/components/switch.css
new file mode 100644
index 0000000..2e80b2a
--- /dev/null
+++ b/packages/styles/components/switch.css
@@ -0,0 +1,242 @@
+/* Switch base styles */
+.switch {
+  @apply flex flex-col items-start gap-1 no-highlight;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Default tokens for switch control states */
+  --switch-control-bg: var(--default);
+  --switch-control-bg-hover: color-mix(in oklab, var(--switch-control-bg), transparent 20%);
+  --switch-control-bg-pressed: var(--switch-control-bg-hover);
+  --switch-control-bg-checked: var(--accent);
+  --switch-control-bg-checked-hover: var(--accent-hover);
+
+  /* Disabled state */
+  &[data-disabled="true"] {
+    @apply status-disabled;
+
+    [data-slot="description"],
+    [data-slot="field-error"] {
+      @apply status-disabled;
+    }
+
+    .switch__thumb {
+      @apply bg-default-foreground/20;
+    }
+  }
+
+  /* Field-level help text below the control + label row */
+  & > [data-slot="description"] {
+    @apply w-full min-w-0 ps-[calc(2.5rem+0.75rem)];
+  }
+
+  & > [data-slot="field-error"] {
+    @apply w-full min-w-0 ps-[calc(2.5rem+0.75rem)] text-xs text-muted;
+  }
+
+  &.switch--sm > [data-slot="description"] {
+    @apply ps-[calc(2rem+0.75rem)];
+  }
+
+  &.switch--sm > [data-slot="field-error"] {
+    @apply ps-[calc(2rem+0.75rem)];
+  }
+
+  &.switch--lg > [data-slot="description"] {
+    @apply ps-[calc(3rem+0.75rem)];
+  }
+
+  &.switch--lg > [data-slot="field-error"] {
+    @apply ps-[calc(3rem+0.75rem)];
+  }
+
+  /* Disabled + Selected state */
+  &:disabled[aria-checked="true"],
+  &:disabled[data-selected="true"],
+  &[data-disabled="true"][aria-checked="true"],
+  &[data-disabled="true"][data-selected="true"],
+  &[aria-disabled="true"][aria-checked="true"],
+  &[aria-disabled="true"][data-selected="true"] {
+    .switch__thumb {
+      opacity: 0.4;
+    }
+  }
+}
+
+/* Size variants - default is medium */
+.switch--sm {
+  /* Small size modifier */
+}
+
+.switch--md {
+  /* Medium size - no styles as this is the default */
+}
+
+.switch--lg {
+  /* Large size modifier */
+}
+
+/* Switch control (track) */
+.switch__control {
+  /* Default size (medium) */
+  @apply relative flex shrink-0 items-center overflow-hidden rounded-xl;
+  height: 1.25rem; /* 20px on desktop (14px base), 20px on mobile (16px base) - scales with font-size */
+  width: 2.5rem; /* 35px on desktop, 40px on mobile - scales with font-size */
+
+  background-color: var(--switch-control-bg);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 250ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Focus states */
+  .switch:focus-visible &,
+  .switch:has([data-slot="switch-content"][data-focus-visible="true"]) &,
+  .switch [data-slot="switch-content"][data-focus-visible="true"] & {
+    @apply status-focused;
+  }
+
+  /* Hover states */
+  .switch:hover &,
+  .switch:has([data-slot="switch-content"][data-hovered="true"]) &,
+  .switch [data-slot="switch-content"][data-hovered="true"] & {
+    background-color: var(--switch-control-bg-hover);
+  }
+
+  /* Pressed states */
+  .switch:active &,
+  .switch:has([data-slot="switch-content"][data-pressed="true"]) &,
+  .switch [data-slot="switch-content"][data-pressed="true"] & {
+    background-color: var(--switch-control-bg-pressed);
+    @apply motion-reduce:transform-none;
+  }
+
+  /* Checked states */
+  .switch[aria-checked="true"] &,
+  .switch[data-selected="true"] & {
+    background-color: var(--switch-control-bg-checked);
+  }
+
+  /* Checked + Hover states */
+  .switch[aria-checked="true"]:hover &,
+  .switch[data-selected="true"]:hover &,
+  .switch[aria-checked="true"][data-hovered="true"] &,
+  .switch[data-selected="true"][data-hovered="true"] &,
+  .switch:has([data-slot="switch-content"][data-hovered="true"])[data-selected="true"] & {
+    background-color: var(--switch-control-bg-checked-hover);
+  }
+
+  /* Checked + Pressed states */
+  .switch[aria-checked="true"]:active &,
+  .switch[data-selected="true"]:active &,
+  .switch[aria-checked="true"][data-pressed="true"] &,
+  .switch[data-selected="true"][data-pressed="true"] &,
+  .switch:has([data-slot="switch-content"][data-pressed="true"])[data-selected="true"] & {
+    background-color: var(--switch-control-bg-checked-hover);
+  }
+}
+
+/* Switch content — the clickable label (control + label text) */
+.switch__content {
+  @apply relative inline-flex cursor-[inherit] items-center gap-3 text-sm font-medium text-foreground outline-none select-none no-highlight;
+}
+
+/* Size-specific control dimensions */
+.switch--sm .switch__control {
+  @apply rounded-lg;
+  height: 1rem; /* ~14px on desktop, ~16px on mobile */
+  width: 2rem; /* ~32px on desktop, ~36px on mobile */
+}
+
+.switch--md .switch__control {
+  /* No styles as this is the default size */
+}
+
+.switch--lg .switch__control {
+  height: 1.5rem; /* ~21px on desktop, ~24px on mobile */
+  width: 3rem; /* ~48px on desktop, ~56px on mobile */
+}
+
+/* Switch thumb */
+.switch__thumb {
+  /* Default size (medium) with margin-based positioning */
+  @apply ms-0.5 flex origin-center rounded-lg bg-white text-black shadow-field;
+  height: 1rem; /* ~14px on desktop, ~16px on mobile */
+  width: 1.375rem; /* ~19px on desktop, ~22px on mobile */
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    margin 300ms var(--ease-out-fluid),
+    background-color 200ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  /* Selected/checked state - use margin instead of translate */
+  .switch[aria-checked="true"] &,
+  .switch[data-selected="true"] & {
+    @apply ms-[calc(100%-1.5rem)] bg-accent-foreground text-accent;
+    box-shadow:
+      0px 0px 5px 0px rgb(0 0 0 / 0.02),
+      0px 2px 10px 0px rgb(0 0 0 / 0.06),
+      0px 0px 1px 0px rgb(0 0 0 / 0.3);
+  }
+
+  .switch:active &,
+  .switch[data-pressed="true"] & {
+  }
+}
+
+/* Size-specific thumb dimensions */
+.switch--sm .switch__thumb {
+  @apply rounded-md;
+  height: 0.75rem; /* ~10.5px on desktop, ~12px on mobile */
+  width: 1.03125rem; /* ~14.4px on desktop, ~16.5px on mobile - maintains 1.375:1 ratio */
+
+  /* Small selected state positioning */
+  .switch[aria-checked="true"] &,
+  .switch[data-selected="true"] & {
+    @apply ms-[calc(100%-1.15625rem)];
+  }
+}
+
+.switch--lg .switch__thumb {
+  @apply rounded-xl;
+  height: 1.25rem; /* ~17.5px on desktop, ~20px on mobile */
+  width: 1.71875rem; /* ~24px on desktop, ~27.5px on mobile - maintains 1.375:1 ratio */
+
+  /* Large selected state positioning */
+  .switch[aria-checked="true"] &,
+  .switch[data-selected="true"] & {
+    @apply ms-[calc(100%-1.84375rem)];
+  }
+}
+
+/* Switch thumb content container */
+.switch__thumb > * {
+  @apply flex size-full items-center justify-center;
+}
+
+/* Switch label */
+.switch__label {
+  @apply text-base font-medium text-foreground;
+}
+
+.switch [data-slot="label"] {
+  @apply select-none;
+}
+
+.switch__content [data-slot="label"] {
+  cursor: var(--cursor-interactive);
+}
+
+.switch [data-slot="description"] {
+  @apply cursor-default select-none;
+}
diff --git a/packages/styles/components/table.css b/packages/styles/components/table.css
new file mode 100644
index 0000000..6ca5c66
--- /dev/null
+++ b/packages/styles/components/table.css
@@ -0,0 +1,396 @@
+/* ==========================================================================
+   Table — Data display component for structured tabular data.
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   Table Root — Outer container for table + optional footer.
+   Primary variant: gray background with the table body as a white card inside.
+   -------------------------------------------------------------------------- */
+.table-root {
+  @apply relative grid w-full overflow-clip;
+  grid-template-columns: minmax(0, 1fr);
+}
+
+/* --------------------------------------------------------------------------
+   Scroll Container — Allows the table to scroll horizontally while the
+   wrapper and footer remain at full width. The parent grid with
+   minmax(0, 1fr) creates a hard width boundary that table layout
+   cannot push beyond.
+   -------------------------------------------------------------------------- */
+.table__scroll-container {
+  @apply scrollbar overflow-x-auto;
+  scrollbar-gutter: auto;
+}
+
+.table-root--primary {
+  @apply bg-surface-secondary px-1 pb-1;
+  border-radius: min(32px, calc(var(--radius) * 2.5));
+}
+
+.table-root--secondary {
+  /* No background, padding, or rounding on the root */
+}
+
+/* Secondary: header is a standalone rounded card.
+   Background is on cells (not <thead>) because Firefox does not support */
+.table-root--secondary .table__header {
+  @apply border-b-0 bg-transparent;
+}
+
+.table-root--secondary .table__column {
+  @apply bg-surface-secondary;
+}
+
+/* Round only the truly first/last column header.
+   Non-virtualized: column is a <th> child of <tr>.
+   Virtualized: column is wrapped in a `VirtualizerItem` (role="presentation") so
+   `:first-child` / `:last-child` on `.table__column` would match every column
+   (each is the only child of its wrapper). Walk up to the row instead. */
+.table-root--secondary
+  :is(
+    th.table__column:first-child,
+    [role="row"] > [role="presentation"]:first-of-type > .table__column
+  ) {
+  border-start-start-radius: min(32px, var(--radius-2xl));
+  border-end-start-radius: min(32px, var(--radius-2xl));
+}
+
+.table-root--secondary
+  :is(
+    th.table__column:last-child,
+    [role="row"] > [role="presentation"]:last-of-type > .table__column
+  ) {
+  border-start-end-radius: min(32px, var(--radius-2xl));
+  border-end-end-radius: min(32px, var(--radius-2xl));
+}
+
+/* Secondary: body has no shadow or rounded corners */
+.table-root--secondary .table__body {
+  @apply shadow-none;
+
+  /* Non-virtualized */
+  & tr:first-child td:first-child,
+  & tr:first-child td:last-child,
+  & tr:last-child td:first-child,
+  & tr:last-child td:last-child {
+    @apply rounded-none;
+  }
+
+  /* Virtualized: undo the rounding applied by .table__body:not(tbody) */
+  &:not(tbody) {
+    @apply overflow-visible rounded-none;
+  }
+}
+
+/* Secondary: rows are transparent and keep bottom border on every row */
+.table-root--secondary .table__row {
+  .table__cell {
+    @apply border-b border-separator-tertiary/50 bg-transparent;
+  }
+
+  @media (hover: hover) {
+    &:hover .table__cell,
+    &[data-hovered="true"] .table__cell {
+      @apply bg-default/50;
+    }
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Table Content (<table> element) — the white card inside the root
+   -------------------------------------------------------------------------- */
+.table__content {
+  @apply w-full border-separate border-spacing-0 text-sm;
+}
+
+/* Primary variant: table gets the white surface card look */
+.table-root--primary .table__content {
+  @apply overflow-clip;
+}
+
+/* --------------------------------------------------------------------------
+   Table Header (<thead>)
+   -------------------------------------------------------------------------- */
+.table__header {
+  @apply border-b border-separator/50 bg-surface-secondary;
+}
+
+/* --------------------------------------------------------------------------
+   Table Column (<th>)
+   -------------------------------------------------------------------------- */
+.table__column {
+  @apply relative px-4 py-2.5 text-left text-xs font-medium text-muted;
+
+  /* Separator between columns — a short vertical line on the right edge */
+  &::after {
+    content: "";
+    @apply pointer-events-none absolute end-0 top-1/2 h-4 w-px -translate-y-1/2 rounded-sm bg-separator;
+  }
+
+  &:last-child:not(:only-child)::after {
+    content: none;
+  }
+
+  /* Sortable columns */
+  &[data-allows-sorting="true"] {
+    cursor: var(--cursor-interactive);
+  }
+
+  @media (hover: hover) {
+    &[data-allows-sorting="true"]:hover,
+    &[data-allows-sorting="true"][data-hovered="true"] {
+      @apply text-foreground;
+    }
+  }
+
+  /* Focus visible — inset shadow for consistent table focus styling */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply rounded-lg outline-none;
+    box-shadow: inset 0 0 0 2px var(--focus);
+  }
+}
+
+/* Virtualized: each column is wrapped in a `VirtualizerItem` (role="presentation"),
+   so `.table__column:last-child:not(:only-child)::after` above never matches.
+   Hide the trailing separator on the rightmost wrapper instead. */
+[role="row"] > [role="presentation"]:last-of-type:not(:only-of-type) > .table__column::after {
+  content: none;
+}
+
+/* --------------------------------------------------------------------------
+   Sortable Column Header — wraps the column label and an optional indicator
+   icon. Rendered inside a sortable `Table.Column`'s render prop callback.
+   -------------------------------------------------------------------------- */
+.table__sortable-column-header {
+  @apply flex items-center justify-between;
+}
+
+/* --------------------------------------------------------------------------
+   Sortable Column Indicator — chevron that flips based on `data-direction`.
+   Defaults to pointing up (ascending) and rotates 180° for descending.
+   -------------------------------------------------------------------------- */
+.table__sortable-column-indicator {
+  @apply size-3 transform transition-transform duration-100 ease-out;
+
+  &[data-direction="descending"] {
+    @apply rotate-180;
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Table Body (<tbody>)
+   -------------------------------------------------------------------------- */
+.table__body {
+  /* Non-virtualized: round corners via first/last cells
+     (border-radius on <tbody> itself has no effect).
+     Logical properties so corners follow `dir` in RTL. */
+  & tr:first-child td:first-child {
+    border-start-start-radius: min(32px, var(--radius-2xl));
+  }
+  & tr:first-child td:last-child {
+    border-start-end-radius: min(32px, var(--radius-2xl));
+  }
+  & tr:last-child td:first-child {
+    border-end-start-radius: min(32px, var(--radius-2xl));
+  }
+  & tr:last-child td:last-child {
+    border-end-end-radius: min(32px, var(--radius-2xl));
+  }
+
+  /* Virtualized: elements are divs, not tr/td. VirtualizerItem wrappers
+     break :first-child/:last-child on rows and cells, so round the body
+     itself and clip overflow instead. */
+  &:not(tbody) {
+    @apply relative h-full overflow-clip;
+    border-radius: min(32px, var(--radius-2xl));
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Table Row (<tr>)
+   -------------------------------------------------------------------------- */
+.table__row {
+  @apply relative h-full;
+
+  /* Bottom separator */
+  @apply border-b border-separator/50;
+
+  /* Last row in body has no bottom border */
+  &:last-child {
+    @apply border-b-0;
+  }
+
+  /* Hover state — applied to cells so Firefox clips bg to border-radius */
+  @media (hover: hover) {
+    &:hover .table__cell,
+    &[data-hovered="true"] .table__cell {
+      @apply bg-surface/40;
+    }
+  }
+
+  /* Selected state */
+  &[data-selected="true"] .table__cell {
+    @apply bg-surface/10;
+  }
+
+  /* Disabled state */
+  &[aria-disabled="true"],
+  &[data-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Row focus ring: see “Table row focus ring” block below (after `.table__cell`). */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply outline-none;
+  }
+
+  /* Dragging state */
+  &[data-dragging="true"] {
+    @apply opacity-50;
+  }
+
+  /* Drop target state */
+  &[data-drop-target="true"] .table__cell {
+    @apply bg-accent-soft;
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Table Cell (<td>)
+   -------------------------------------------------------------------------- */
+.table__cell {
+  @apply h-full bg-surface px-4 py-3 align-middle text-sm text-foreground;
+
+  @apply border-b border-separator-tertiary/50;
+
+  /* Focus visible — inset shadow so focus stays within the cell boundaries */
+  &:focus-visible,
+  &[data-focus-visible="true"] {
+    @apply rounded-lg outline-none;
+    box-shadow: inset 0 0 0 2px var(--focus);
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Table row focus ring — must follow `.table__cell` (cascade). One continuous
+   inset ring split across cells; `:is(.table__cell, .table__column)` + direct vs
+   `> *:…` covers virtualized wrappers. `:is(:focus-visible, [data-focus-visible])`
+   matches row keyboard focus from RAC.
+   -------------------------------------------------------------------------- */
+.table__row:is(:focus-visible, [data-focus-visible="true"]) :is(.table__cell, .table__column) {
+  @apply shadow-none;
+}
+
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > :is(.table__cell, .table__column):only-child,
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > *:only-child
+  :is(.table__cell, .table__column) {
+  @apply rounded-lg shadow-[inset_0_0_0_2px_var(--focus)] outline-none;
+}
+
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > :is(.table__cell, .table__column):first-child:not(:only-child),
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > *:first-child:not(:only-child)
+  :is(.table__cell, .table__column) {
+  @apply rounded-l-lg shadow-[inset_2px_0_0_0_var(--focus),inset_0_2px_0_0_var(--focus),inset_0_-2px_0_0_var(--focus)] outline-none;
+}
+
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > :is(.table__cell, .table__column):last-child:not(:only-child),
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > *:last-child:not(:only-child)
+  :is(.table__cell, .table__column) {
+  @apply rounded-r-lg shadow-[inset_-2px_0_0_0_var(--focus),inset_0_2px_0_0_var(--focus),inset_0_-2px_0_0_var(--focus)] outline-none;
+}
+
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > :is(.table__cell, .table__column):not(:first-child):not(:last-child):not(:only-child),
+.table__row:is(:focus-visible, [data-focus-visible="true"])
+  > *:not(:first-child):not(:last-child):not(:only-child)
+  :is(.table__cell, .table__column) {
+  @apply shadow-[inset_0_2px_0_0_var(--focus),inset_0_-2px_0_0_var(--focus)] outline-none;
+}
+
+/* --------------------------------------------------------------------------
+   Tree / expandable rows — indent the tree column by depth (any level).
+   React Aria sets `--table-row-level` (1-based) on each body row and
+   `data-level` on cells; tree column cells expose `[data-tree-column]`.
+   The row custom property inherits onto cells (1rem per level).
+   -------------------------------------------------------------------------- */
+.table__cell[data-tree-column] {
+  padding-inline-start: calc(1rem * var(--table-row-level, 1));
+}
+
+/* --------------------------------------------------------------------------
+   Table Footer (div outside <table>, sits on gray bg)
+   -------------------------------------------------------------------------- */
+.table__footer {
+  @apply flex items-center px-4 py-2.5;
+}
+
+/* --------------------------------------------------------------------------
+   Resizable Container — wraps table to enable column resizing via React Aria.
+   -------------------------------------------------------------------------- */
+.table__resizable-container {
+  @apply relative scrollbar overflow-auto;
+  scrollbar-gutter: auto;
+}
+
+/* --------------------------------------------------------------------------
+   Column Resizer — drag handle between resizable columns.
+   Replaces the ::after separator when present.
+   -------------------------------------------------------------------------- */
+.table__column-resizer {
+  /* Match the ::after separator: absolute, right edge, short vertical line */
+  @apply absolute end-0 top-1/2 h-4 w-px -translate-y-1/2 rounded-sm bg-separator;
+  /* Make it interactive — wider hit area with transparent padding */
+  @apply box-content translate-x-1/2 cursor-col-resize touch-none px-2;
+  /* Reset appearance */
+  @apply border-none bg-clip-content outline-none;
+
+  &[data-hovered="true"],
+  &:hover {
+    @apply h-full w-0.5 bg-accent;
+  }
+
+  &[data-resizing="true"] {
+    @apply h-full w-0.5 bg-accent;
+  }
+
+  &[data-focus-visible="true"],
+  &:focus-visible {
+    @apply h-full w-0.5 bg-focus;
+  }
+}
+
+/* Hide the ::after separator when a resizer is present in the column */
+.table__column:has(.table__column-resizer)::after {
+  content: none;
+}
+
+/* --------------------------------------------------------------------------
+   Load More Item — sentinel row for infinite scrolling.
+   Non-virtualized: <tr> with <td colSpan=N> inside.
+   Virtualized: <div> with <div role="rowheader"> inside.
+   -------------------------------------------------------------------------- */
+.table__load-more {
+  & td,
+  & [role="rowheader"] {
+    @apply py-3 text-center;
+    & > * {
+      @apply mx-auto;
+    }
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Load More Content — styled container for the loading indicator inside
+   the load-more sentinel row.
+   -------------------------------------------------------------------------- */
+.table__load-more-content {
+  @apply flex items-center justify-center gap-2 py-2;
+}
diff --git a/packages/styles/components/tabs.css b/packages/styles/components/tabs.css
new file mode 100644
index 0000000..9ec9110
--- /dev/null
+++ b/packages/styles/components/tabs.css
@@ -0,0 +1,278 @@
+/* Base tabs component */
+.tabs {
+  @apply flex gap-2;
+
+  /* Orientation styles */
+  &[data-orientation="horizontal"] {
+    @apply flex-col;
+  }
+
+  &[data-orientation="vertical"] {
+    @apply flex-row;
+  }
+}
+
+/* Tab list container */
+.tabs__list-container {
+  @apply relative bg-default;
+
+  border-radius: calc(var(--radius) * 2.5);
+
+  /* Vertical scroller fills the container height so overflow detection
+     engages when the wrapper height is constrained (e.g. h-[240px]) */
+  > .tabs__list-container__scroller[data-orientation="vertical"] {
+    @apply h-full;
+  }
+
+  /* Overflow chevron buttons */
+  > .tabs__list-container__scroll-prev,
+  > .tabs__list-container__scroll-next {
+    @apply absolute z-2 hidden size-4 cursor-(--cursor-interactive) items-center justify-center rounded-full border-0 bg-transparent p-0 text-foreground outline-none;
+
+    /**
+    * Transitions
+    * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+    */
+    transition: opacity 150ms var(--ease-smooth);
+    @apply motion-reduce:transition-none;
+
+    @media (hover: hover) {
+      &:hover {
+        @apply opacity-70;
+      }
+    }
+
+    &:focus-visible {
+      @apply status-focused;
+    }
+  }
+
+  /* Chevron position - horizontal orientation */
+  &:has([data-orientation="horizontal"]) {
+    > .tabs__list-container__scroll-prev {
+      @apply top-1/2 left-1 -translate-y-1/2;
+    }
+
+    > .tabs__list-container__scroll-next {
+      @apply top-1/2 right-1 -translate-y-1/2;
+    }
+  }
+
+  /* Chevron position - vertical orientation */
+  &:has([data-orientation="vertical"]) {
+    > .tabs__list-container__scroll-prev {
+      @apply top-1 left-1/2 -translate-x-1/2;
+    }
+
+    > .tabs__list-container__scroll-next {
+      @apply bottom-1 left-1/2 -translate-x-1/2;
+    }
+  }
+
+  /* Show chevrons only when ScrollShadow reports scrolling is possible */
+  &:has(
+      > :is(
+        [data-left-scroll="true"],
+        [data-left-right-scroll="true"],
+        [data-top-scroll="true"],
+        [data-top-bottom-scroll="true"]
+      )
+    )
+    > .tabs__list-container__scroll-prev {
+    @apply inline-flex;
+  }
+
+  &:has(
+      > :is(
+        [data-right-scroll="true"],
+        [data-left-right-scroll="true"],
+        [data-bottom-scroll="true"],
+        [data-top-bottom-scroll="true"]
+      )
+    )
+    > .tabs__list-container__scroll-next {
+    @apply inline-flex;
+  }
+}
+
+/* Tab list */
+.tabs__list {
+  @apply inline-flex p-1;
+
+  /* Horizontal orientation - grow with content so ScrollShadow can detect overflow */
+  &[data-orientation="horizontal"] {
+    @apply w-max min-w-full flex-row;
+  }
+
+  /* Vertical orientation */
+  &[data-orientation="vertical"] {
+    @apply flex-col gap-1;
+
+    .tabs__tab {
+      @apply min-w-20;
+    }
+  }
+}
+
+/* Individual tab */
+.tabs__tab {
+  @apply relative flex h-8 w-full items-center justify-center rounded-3xl px-4 text-center text-sm font-medium text-muted outline-none no-highlight;
+
+  z-index: 1;
+  cursor: var(--cursor-interactive);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 150ms var(--ease-smooth),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out),
+    opacity 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+
+  /* Selected state */
+  &[data-selected="true"] {
+    @apply text-segment-foreground;
+
+    /* Hide separator on the selected tab and the one following it */
+    .tabs__separator,
+    & + .tabs__tab .tabs__separator {
+      @apply opacity-0;
+    }
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Hover states - both approaches for compatibility */
+  @media (hover: hover) {
+    &:not([data-selected="true"]):not([data-disabled="true"]):hover,
+    &[data-hovered="true"]:not([data-selected="true"]):not([data-disabled="true"]) {
+      @apply opacity-70;
+    }
+  }
+
+  /* Focus states - comprehensive fallback */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+}
+
+/* Tab separator */
+.tabs__separator {
+  @apply pointer-events-none absolute rounded-sm bg-muted/25;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition: opacity 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+
+  /* Horizontal tabs - vertical separator */
+  .tabs__list[data-orientation="horizontal"] & {
+    @apply top-1/4 left-0 h-1/2 w-px;
+  }
+
+  /* Vertical tabs - horizontal separator */
+  .tabs__list[data-orientation="vertical"] & {
+    @apply top-0 left-[5%] h-px w-[90%];
+  }
+}
+
+/* Tab panel */
+.tabs__panel {
+  @apply w-full p-2 outline-none;
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply absolute top-0 left-0 w-full;
+  }
+
+  /* Orientation spacing */
+  &[data-orientation="horizontal"] {
+    @apply mt-4;
+  }
+
+  &[data-orientation="vertical"] {
+    @apply ml-4;
+  }
+}
+
+/* Tab indicator - React Aria's SelectionIndicator */
+.tabs__indicator {
+  @apply absolute top-0 left-0 size-full rounded-3xl bg-segment shadow-surface;
+
+  z-index: -1;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition-duration: 250ms;
+  transition-property: translate, width, height;
+  transition-timing-function: var(--ease-out-fluid);
+  @apply motion-reduce:transition-none;
+}
+
+/* ==========================================================================
+   Secondary Variant
+   ========================================================================== */
+
+.tabs--secondary {
+  /* Container - flat, no pill. Underline on container (not list) so it stays
+     stable when the inner list scrolls horizontally inside the ScrollShadow. */
+  > .tabs__list-container {
+    @apply rounded-none bg-transparent;
+
+    /* Tab list - remove padding */
+    .tabs__list {
+      @apply p-0;
+    }
+
+    /* Hide separators in secondary variant */
+    .tabs__separator {
+      @apply hidden;
+    }
+
+    /* Tab - adjust for secondary variant */
+    .tabs__tab {
+      @apply rounded-none;
+
+      /* Selected state - use text-foreground */
+      &[data-selected="true"] {
+        @apply text-foreground;
+      }
+    }
+
+    /* Tab indicator - line style */
+    .tabs__indicator {
+      @apply rounded-none bg-accent shadow-none;
+    }
+  }
+
+  /* Horizontal orientation - bottom border + bottom line indicator */
+  &[data-orientation="horizontal"] > .tabs__list-container {
+    @apply border-b border-border;
+
+    .tabs__indicator {
+      @apply top-auto bottom-0 h-0.5;
+    }
+  }
+
+  /* Vertical orientation - left border + left line indicator */
+  &[data-orientation="vertical"] > .tabs__list-container {
+    @apply border-l border-border;
+
+    .tabs__indicator {
+      @apply top-0 left-0 h-full w-0.5;
+    }
+  }
+}
diff --git a/packages/styles/components/tag-group.css b/packages/styles/components/tag-group.css
new file mode 100644
index 0000000..096e431
--- /dev/null
+++ b/packages/styles/components/tag-group.css
@@ -0,0 +1,15 @@
+/* Base styles */
+.tag-group {
+  @apply relative flex flex-col gap-1;
+}
+
+.tag-group__list {
+  @apply relative flex flex-wrap gap-1.5;
+}
+
+.tag-group [slot="description"],
+.tag-group [data-slot="description"],
+.tag-group [slot="errorMessage"],
+.tag-group [data-slot="error-message"] {
+  @apply p-1;
+}
diff --git a/packages/styles/components/tag.css b/packages/styles/components/tag.css
new file mode 100644
index 0000000..617a9b8
--- /dev/null
+++ b/packages/styles/components/tag.css
@@ -0,0 +1,98 @@
+/* Tag component styles */
+.tag {
+  --optical-offset: 0.031em;
+
+  @apply relative inline-flex items-center gap-1 rounded-xl font-medium select-none no-highlight;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 100ms var(--ease-smooth),
+    scale 100ms var(--ease-smooth),
+    opacity 100ms var(--ease-smooth),
+    background-color 100ms var(--ease-smooth),
+    box-shadow 100ms var(--ease-out);
+  @apply origin-center transform-gpu motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* SVG icon styling */
+  & svg {
+    @apply pointer-events-none size-3 shrink-0 self-center text-current;
+  }
+}
+
+/* Disabled state */
+.tag:is([data-disabled="true"], [aria-disabled="true"]) {
+  @apply status-disabled;
+}
+
+/* Focus visible state (keyboard focus only) */
+.tag:is(:focus-visible, [data-focus-visible]) {
+  @apply status-focused;
+}
+
+/* Pressed/Active state */
+.tag:is(:active, [data-pressed="true"]) {
+}
+
+/* Selected state */
+.tag:is([data-selected="true"], [aria-selected="true"]) {
+  @apply bg-accent-soft text-accent-soft-foreground;
+
+  /* Selected + Hover state */
+  @media (hover: hover) {
+    &:is(:hover, [data-hovered="true"]) {
+      @apply bg-accent-soft-hover;
+    }
+  }
+}
+
+/* Size */
+.tag--sm {
+  @apply px-2 py-0.5 text-xs;
+}
+
+.tag--md {
+  @apply px-2 py-1 text-xs;
+}
+
+.tag--lg {
+  @apply rounded-2xl px-2.5 py-1.5 text-sm;
+}
+
+/* Variant */
+.tag--default {
+  @apply bg-default text-default-foreground;
+
+  /* Hover state (when not selected or disabled) */
+  @media (hover: hover) {
+    &:is(:hover, [data-hovered="true"]):not([data-selected="true"]):not([data-disabled="true"]) {
+      @apply bg-default-hover;
+    }
+  }
+}
+
+.tag--surface {
+  @apply bg-surface text-surface-foreground;
+
+  /* Hover state (when not selected or disabled) */
+  @media (hover: hover) {
+    &:is(:hover, [data-hovered="true"]):not([data-selected="true"]):not([data-disabled="true"]) {
+      @apply bg-surface-hover;
+    }
+  }
+}
+
+/* Remove Button  */
+.tag__remove-button {
+  @apply size-3 text-inherit;
+
+  /* SVG icon styling */
+  & svg {
+    @apply size-[inherit] shrink-0 self-center text-current;
+  }
+}
diff --git a/packages/styles/components/textarea.css b/packages/styles/components/textarea.css
new file mode 100644
index 0000000..489afa0
--- /dev/null
+++ b/packages/styles/components/textarea.css
@@ -0,0 +1,94 @@
+/* use textarea instead of text-area to avoid conflict with Tailwind `text-` prefix */
+.textarea {
+  @apply rounded-field border bg-field px-3 py-2 text-base text-field-foreground shadow-field outline-none placeholder:text-field-placeholder sm:text-sm;
+
+  min-height: 38px;
+
+  border-width: var(--border-width-field);
+  border-color: var(--field-border);
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    background-color 150ms var(--ease-smooth),
+    border-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  @media (hover: hover) {
+    &:hover:not(:focus):not(:focus-visible),
+    &[data-hovered="true"]:not([data-focused="true"]):not([data-focus-visible="true"]) {
+      @apply bg-field-hover;
+      border-color: var(--field-border-hover);
+    }
+  }
+
+  /* Focus state */
+  &:focus,
+  &[data-focused="true"] {
+    @apply status-focused-field;
+    border-color: var(--field-border-focus);
+    background-color: var(--field-focus);
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+  }
+
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--field-focus);
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[data-disabled="true"],
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+}
+
+/* Variant property definitions */
+.textarea--primary {
+  /* Default styles */
+}
+
+.textarea--secondary {
+  @apply shadow-none;
+  background-color: var(--textarea-bg);
+
+  --textarea-bg: var(--default);
+  --textarea-bg-hover: var(--default-hover);
+  --textarea-bg-focus: var(--default);
+
+  @media (hover: hover) {
+    &:hover:not(:focus):not(:focus-visible),
+    &[data-hovered="true"]:not([data-focused="true"]):not([data-focus-visible="true"]) {
+      background-color: var(--textarea-bg-hover);
+    }
+  }
+
+  &:focus,
+  &[data-focused="true"] {
+    background-color: var(--textarea-bg-focus);
+  }
+
+  /* Focus visible state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+  }
+
+  /* Invalid state */
+  &[data-invalid="true"] {
+    @apply status-invalid-field;
+    background-color: var(--textarea-bg-focus);
+  }
+}
+
+/* Full width modifier */
+.textarea--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/textfield.css b/packages/styles/components/textfield.css
new file mode 100644
index 0000000..8c47063
--- /dev/null
+++ b/packages/styles/components/textfield.css
@@ -0,0 +1,23 @@
+/* Text field styles */
+/* use textfield instead of text-field to avoid conflict with Tailwind `text-` prefix */
+.textfield {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+}
+
+/* Full width modifier */
+.textfield--full-width {
+  @apply w-full;
+
+  /* Automatically make Input full width when TextField is full width */
+  [data-slot="input"],
+  [data-slot="textarea"] {
+    @apply w-full;
+  }
+}
diff --git a/packages/styles/components/time-field.css b/packages/styles/components/time-field.css
new file mode 100644
index 0000000..221bf8a
--- /dev/null
+++ b/packages/styles/components/time-field.css
@@ -0,0 +1,20 @@
+/* Time field styles */
+.time-field {
+  @apply flex flex-col gap-1;
+
+  &[data-invalid="true"],
+  &[aria-invalid="true"] {
+    [data-slot="description"] {
+      @apply hidden;
+    }
+  }
+
+  [data-slot="label"] {
+    @apply w-fit;
+  }
+}
+
+/* Full width modifier */
+.time-field--full-width {
+  @apply w-full;
+}
diff --git a/packages/styles/components/toast.css b/packages/styles/components/toast.css
new file mode 100644
index 0000000..f91788c
--- /dev/null
+++ b/packages/styles/components/toast.css
@@ -0,0 +1,247 @@
+/* Toast component styles */
+
+/* Toast Region - Container for all toasts */
+.toast-region {
+  @apply pointer-events-none fixed z-50 outline-none;
+  @apply w-[calc(100vw-2rem)] sm:w-auto sm:min-w-(--toast-width);
+
+  display: block;
+}
+
+/* Placement variants - Bottom */
+.toast-region--bottom {
+  @apply bottom-4 left-1/2 -translate-x-1/2;
+}
+
+.toast-region--bottom-start {
+  @apply bottom-4 left-4;
+}
+
+.toast-region--bottom-end {
+  @apply right-4 bottom-4;
+}
+
+/* Placement variants - Top */
+.toast-region--top {
+  @apply top-4 left-1/2 -translate-x-1/2;
+}
+
+.toast-region--top-start {
+  @apply top-4 left-4;
+}
+
+.toast-region--top-end {
+  @apply top-4 right-4;
+}
+
+.toast-region:focus-visible {
+  @apply outline-2 outline-offset-2 outline-focus;
+}
+
+/* Base toast styles */
+.toast {
+  position: absolute;
+  left: 0;
+  right: 0;
+
+  @apply pointer-events-auto flex flex-row items-start justify-start gap-1.5 bg-surface px-4 py-3 shadow-overlay;
+  border-radius: min(32px, var(--radius-3xl));
+}
+
+.toast--bottom,
+.toast--bottom-start,
+.toast--bottom-end {
+  bottom: 0;
+}
+
+.toast--top,
+.toast--top-start,
+.toast--top-end {
+  top: 0;
+}
+
+.toast:not([data-frontmost="true"]) {
+  @apply pointer-events-none;
+
+  height: var(--front-height);
+  overflow: hidden;
+
+  .toast__close-button {
+    @apply pointer-events-none opacity-0;
+    outline: none;
+  }
+}
+
+.toast[data-hidden="true"] {
+  @apply pointer-events-none flex opacity-0;
+}
+
+.toast:focus-visible {
+  @apply outline-2 outline-offset-2 outline-focus;
+}
+
+/* Toast placements + view transitions */
+.toast--bottom,
+.toast--bottom-start,
+.toast--bottom-end {
+  view-transition-class: toast-bottom;
+}
+
+.toast--top,
+.toast--top-start,
+.toast--top-end {
+  view-transition-class: toast-top;
+}
+
+/* Toast content */
+.toast__content {
+  @apply flex h-full grow flex-col items-start self-center;
+}
+
+/* Toast indicator */
+.toast__indicator {
+  @apply flex shrink-0 items-center justify-center p-1 text-overlay-foreground select-none;
+
+  [data-slot="toast-default-icon"] {
+    @apply box-content size-4;
+  }
+
+  /* Spinner styles override for toast */
+  [data-slot="spinner"] {
+    @apply size-4;
+  }
+
+  [data-slot="spinner-icon"] {
+    @apply size-4;
+  }
+}
+
+/* Toast title */
+.toast__title {
+  @apply text-sm leading-5 font-medium text-overlay-foreground;
+}
+
+/* Toast description */
+.toast__description {
+  @apply text-sm text-muted;
+}
+
+/* Toast close button */
+.toast__close-button {
+  @apply pointer-events-none absolute -top-1 -right-1 size-5 border-border bg-default opacity-0 sm:border sm:bg-overlay;
+  transition: opacity 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+  /* Overrides close button default icon size from 16px to 12px */
+  [data-slot="close-button-icon"] {
+    @apply size-3.5 sm:size-3;
+  }
+
+  /* Overrides close button hover state */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      @apply bg-default;
+    }
+  }
+}
+
+/* Only show close button on hover for frontmost toast */
+.toast[data-frontmost="true"]:hover .toast__close-button {
+  @apply pointer-events-auto opacity-100;
+}
+
+/* Toast action button */
+.toast__action {
+  @apply mt-2 sm:mt-0;
+}
+
+/* Variant modifiers */
+.toast--accent .toast__title {
+  @apply text-accent-soft-foreground;
+}
+
+.toast--success .toast__title {
+  @apply text-success-soft-foreground;
+}
+
+.toast--success .toast__indicator {
+  @apply text-success-soft-foreground;
+}
+
+.toast--warning .toast__title {
+  @apply text-warning-soft-foreground;
+}
+
+.toast--warning .toast__indicator {
+  @apply text-warning-soft-foreground;
+}
+
+.toast--danger .toast__title {
+  @apply text-danger-soft-foreground;
+}
+
+.toast--danger .toast__indicator {
+  @apply text-danger-soft-foreground;
+}
+
+/* View transition animations */
+::view-transition-group(.toast-bottom),
+::view-transition-group(.toast-top) {
+}
+
+::view-transition-old(*),
+::view-transition-new(*) {
+  will-change: translate, opacity;
+}
+
+/* Bottom */
+::view-transition-new(.toast-bottom):only-child {
+  animation: toast-slide-bottom-in 350ms;
+}
+
+::view-transition-old(.toast-bottom):only-child {
+  animation: toast-slide-bottom-out 350ms;
+  animation-fill-mode: forwards;
+}
+
+/* Top */
+::view-transition-new(.toast-top):only-child {
+  animation: toast-slide-top-in 350ms;
+}
+
+::view-transition-old(.toast-top):only-child {
+  animation: toast-slide-top-out 350ms;
+  animation-fill-mode: forwards;
+}
+
+/* Keyframes */
+
+/* Bottom */
+@keyframes toast-slide-bottom-in {
+  from {
+    translate: 0 100%;
+    opacity: 0;
+  }
+}
+
+@keyframes toast-slide-bottom-out {
+  to {
+    translate: 0 100%;
+    opacity: 0;
+  }
+}
+
+/* Top */
+@keyframes toast-slide-top-in {
+  from {
+    translate: 0 -100%;
+    opacity: 0;
+  }
+}
+
+@keyframes toast-slide-top-out {
+  to {
+    translate: 0 -100%;
+    opacity: 0;
+  }
+}
diff --git a/packages/styles/components/toggle-button-group.css b/packages/styles/components/toggle-button-group.css
new file mode 100644
index 0000000..62694e9
--- /dev/null
+++ b/packages/styles/components/toggle-button-group.css
@@ -0,0 +1,136 @@
+/* ==========================================================================
+   ToggleButtonGroup - Groups multiple ToggleButtons into a unified control
+   ========================================================================== */
+
+/* Base styles */
+.toggle-button-group {
+  @apply inline-flex h-auto w-fit items-center justify-center gap-0;
+}
+
+/* ==========================================================================
+   Orientation variants
+   ========================================================================== */
+
+.toggle-button-group--horizontal {
+  @apply flex-row;
+}
+
+.toggle-button-group--vertical {
+  @apply flex-col;
+}
+
+/* ==========================================================================
+   Full width modifier
+   ========================================================================== */
+
+.toggle-button-group--full-width {
+  @apply w-full;
+}
+
+/* ==========================================================================
+   Attached mode (default) - buttons connected with dividers
+   ========================================================================== */
+
+/* Remove border radius from all toggle buttons in attached group */
+.toggle-button-group .toggle-button {
+  @apply rounded-none;
+}
+
+/* Apply border radius to first button (start edge) */
+.toggle-button-group--horizontal .toggle-button:first-child {
+  @apply rounded-s-3xl;
+}
+
+/* Apply border radius to last button (end edge) */
+.toggle-button-group--horizontal .toggle-button:last-child {
+  @apply rounded-e-3xl;
+}
+
+/* If only one button, apply both rounded edges */
+.toggle-button-group--horizontal .toggle-button:first-child:last-child {
+  @apply rounded-3xl;
+}
+
+/* Apply border radius to first button (top edge) in vertical */
+.toggle-button-group--vertical .toggle-button:first-child {
+  @apply rounded-t-3xl;
+}
+
+/* Apply border radius to last button (bottom edge) in vertical */
+.toggle-button-group--vertical .toggle-button:last-child {
+  @apply rounded-b-3xl;
+}
+
+/* If only one button in vertical, apply all rounded edges */
+.toggle-button-group--vertical .toggle-button:first-child:last-child {
+  @apply rounded-3xl;
+}
+
+/* Remove scale transform on active/pressed state for buttons in group */
+.toggle-button-group .toggle-button:active,
+.toggle-button-group .toggle-button[data-pressed="true"] {
+  transform: none;
+}
+
+/* Override focus ring to use inset style so it stays within button bounds */
+.toggle-button-group .toggle-button:focus-visible:not(:focus),
+.toggle-button-group .toggle-button[data-focus-visible="true"] {
+  --tw-ring-offset-width: 0px;
+  @apply ring-inset;
+}
+
+/* Full width: stretch each toggle button */
+.toggle-button-group--full-width .toggle-button {
+  @apply flex-1;
+}
+
+/* ==========================================================================
+   Separator (compound component)
+   ========================================================================== */
+
+.toggle-button-group__separator {
+  @apply rounded-sm bg-current opacity-15;
+  position: absolute;
+  pointer-events: none;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition: opacity 150ms var(--ease-smooth);
+  @apply motion-reduce:transition-none;
+
+  /* Horizontal orientation - vertical divider */
+  .toggle-button-group--horizontal & {
+    left: -1px;
+    top: 25%;
+    width: 1px;
+    height: 50%;
+  }
+
+  /* Vertical orientation - horizontal divider */
+  .toggle-button-group--vertical & {
+    left: 25%;
+    top: -1px;
+    width: 50%;
+    height: 1px;
+  }
+}
+
+/* ==========================================================================
+   Detached mode - buttons separated with gaps
+   ========================================================================== */
+
+.toggle-button-group--detached {
+  @apply gap-1;
+}
+
+/* Restore border radius in detached mode */
+.toggle-button-group--detached .toggle-button {
+  @apply rounded-3xl;
+}
+
+/* Hide separators in detached mode */
+.toggle-button-group--detached .toggle-button-group__separator {
+  display: none;
+}
diff --git a/packages/styles/components/toggle-button.css b/packages/styles/components/toggle-button.css
new file mode 100644
index 0000000..56e648b
--- /dev/null
+++ b/packages/styles/components/toggle-button.css
@@ -0,0 +1,149 @@
+/* ==========================================================================
+   ToggleButton - Interactive toggle control for on/off states
+   ========================================================================== */
+
+/* Base styles */
+.toggle-button {
+  @apply relative isolate inline-flex h-10 w-fit origin-center items-center justify-center gap-2 rounded-3xl px-4 text-sm font-medium whitespace-nowrap outline-none select-none no-highlight md:h-9;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    transform 250ms var(--ease-smooth),
+    background-color 100ms var(--ease-out),
+    box-shadow 100ms var(--ease-out);
+  @apply transform-gpu motion-reduce:transition-none;
+
+  /* Cursor */
+  cursor: var(--cursor-interactive);
+
+  /* Default tokens (unselected state) */
+  --toggle-button-bg: var(--default);
+  --toggle-button-bg-hover: var(--default-hover);
+  --toggle-button-bg-pressed: var(--default-hover);
+  --toggle-button-fg: currentColor;
+
+  /* Selected state tokens */
+  --toggle-button-bg-selected: var(--accent-soft);
+  --toggle-button-bg-selected-hover: var(--accent-soft-hover);
+  --toggle-button-bg-selected-pressed: var(--accent-soft-hover);
+  --toggle-button-fg-selected: var(--accent-soft-foreground);
+
+  background-color: var(--toggle-button-bg);
+  color: var(--toggle-button-fg);
+
+  /* Focus state */
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+
+  /* Disabled state */
+  &:disabled,
+  &[aria-disabled="true"] {
+    @apply status-disabled;
+  }
+
+  /* Hover */
+  @media (hover: hover) {
+    &:hover,
+    &[data-hovered="true"] {
+      background-color: var(--toggle-button-bg-hover);
+    }
+  }
+
+  /* Active / pressed */
+  &:active,
+  &[data-pressed="true"] {
+    background-color: var(--toggle-button-bg-pressed);
+    transform: scale(0.97);
+  }
+
+  /* Selected state */
+  &[data-selected="true"] {
+    background-color: var(--toggle-button-bg-selected);
+    color: var(--toggle-button-fg-selected);
+
+    @media (hover: hover) {
+      &:hover,
+      &[data-hovered="true"] {
+        background-color: var(--toggle-button-bg-selected-hover);
+      }
+    }
+
+    &:active,
+    &[data-pressed="true"] {
+      background-color: var(--toggle-button-bg-selected-pressed);
+    }
+  }
+
+  /* SVG icon styling */
+  & svg {
+    @apply pointer-events-none -mx-0.5 my-0.5 size-5 shrink-0 self-center sm:my-1 sm:size-4;
+  }
+}
+
+/* ==========================================================================
+   Size variants
+   ========================================================================== */
+
+.toggle-button--sm {
+  @apply h-9 px-3 md:h-8;
+
+  & svg {
+    @apply size-4;
+  }
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.98);
+  }
+}
+
+.toggle-button--md {
+  /* No styles as this is the default size */
+}
+
+.toggle-button--lg {
+  @apply h-11 text-base md:h-10;
+
+  &:active,
+  &[data-pressed="true"] {
+    transform: scale(0.96);
+  }
+}
+
+/* ==========================================================================
+   Variant styles
+   ========================================================================== */
+
+.toggle-button--default {
+  --toggle-button-bg: var(--default);
+  --toggle-button-bg-hover: var(--default-hover);
+  --toggle-button-bg-pressed: var(--default-hover);
+}
+
+.toggle-button--ghost {
+  --toggle-button-bg: transparent;
+  --toggle-button-bg-hover: var(--default);
+  --toggle-button-bg-pressed: var(--default);
+  --toggle-button-fg: var(--default-foreground);
+}
+
+/* ==========================================================================
+   Icon-only modifier
+   ========================================================================== */
+
+.toggle-button--icon-only {
+  @apply w-10 p-0 md:w-9;
+}
+
+.toggle-button--icon-only.toggle-button--sm {
+  @apply w-9 md:w-8;
+}
+
+.toggle-button--icon-only.toggle-button--lg {
+  @apply w-11 md:w-10;
+}
diff --git a/packages/styles/components/toolbar.css b/packages/styles/components/toolbar.css
new file mode 100644
index 0000000..5dde425
--- /dev/null
+++ b/packages/styles/components/toolbar.css
@@ -0,0 +1,32 @@
+/* ==========================================================================
+   Toolbar - Container for interactive controls with arrow key navigation
+   ========================================================================== */
+
+/* Base styles */
+.toolbar {
+  @apply grid w-fit grid-flow-col items-center gap-2;
+
+  .separator--vertical {
+    @apply h-1/2 self-center;
+  }
+
+  .separator--horizontal {
+    @apply w-1/2 justify-center justify-self-center;
+  }
+}
+
+/* Orientation variants */
+.toolbar--horizontal {
+}
+
+.toolbar--vertical {
+  @apply grid-flow-row items-start justify-start;
+  .button-group {
+    @apply justify-start;
+  }
+}
+
+/* Attached variant */
+.toolbar--attached {
+  @apply rounded-3xl bg-surface p-1 shadow-overlay;
+}
diff --git a/packages/styles/components/tooltip.css b/packages/styles/components/tooltip.css
new file mode 100644
index 0000000..8453db3
--- /dev/null
+++ b/packages/styles/components/tooltip.css
@@ -0,0 +1,79 @@
+/* Tooltip component styles */
+
+/* Base tooltip styles */
+.tooltip {
+  @apply max-w-xs origin-(--trigger-anchor-point) bg-overlay p-2 text-xs break-all;
+  border-radius: min(32px, var(--radius-xl));
+  box-shadow: var(--shadow-overlay);
+
+  /* Entering animations */
+  &[data-entering="true"] {
+    @apply animate-in duration-150 ease-smooth fade-in-0 zoom-in-90;
+
+    /* Placement-specific translations */
+    &[data-placement="top"] {
+      @apply slide-in-from-bottom-1;
+    }
+
+    &[data-placement="bottom"] {
+      @apply slide-in-from-top-1;
+    }
+
+    &[data-placement="left"] {
+      @apply slide-in-from-right-1;
+    }
+
+    &[data-placement="right"] {
+      @apply slide-in-from-left-1;
+    }
+  }
+
+  /* Exiting animations */
+  &[data-exiting="true"] {
+    @apply animate-out duration-100 ease-smooth zoom-out-95 fade-out;
+  }
+
+  &[data-exiting="true"],
+  &[data-entering="true"] {
+    @apply transition-[opacity,transform] will-change-[opacity,transform];
+  }
+
+  /* Arrow styling */
+  & [data-slot="overlay-arrow"] {
+    @apply stroke-border/40;
+    fill: var(--overlay);
+  }
+
+  /* Arrow rotation based on placement */
+  &[data-placement="bottom"] [data-slot="overlay-arrow"] {
+    rotate: 180deg;
+  }
+
+  &[data-placement="left"] [data-slot="overlay-arrow"] {
+    rotate: -90deg;
+  }
+
+  &[data-placement="right"] [data-slot="overlay-arrow"] {
+    rotate: 90deg;
+  }
+}
+
+/* Tooltip trigger */
+.tooltip__trigger {
+  @apply inline-block;
+
+  /**
+   * Transitions
+   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
+   */
+  transition:
+    color 150ms var(--ease-smooth),
+    background-color 150ms var(--ease-smooth),
+    box-shadow 150ms var(--ease-out);
+  @apply motion-reduce:transition-none;
+
+  &:focus-visible:not(:focus),
+  &[data-focus-visible="true"] {
+    @apply status-focused;
+  }
+}
diff --git a/packages/styles/components/typography.css b/packages/styles/components/typography.css
new file mode 100644
index 0000000..7960dc4
--- /dev/null
+++ b/packages/styles/components/typography.css
@@ -0,0 +1,163 @@
+.typography {
+  @apply text-foreground;
+}
+
+.typography-prose {
+  @apply text-foreground;
+}
+
+.typography-prose h1 {
+  @apply text-4xl font-semibold tracking-tight;
+}
+
+.typography-prose h2 {
+  @apply text-3xl font-semibold tracking-tight;
+}
+
+.typography-prose h3 {
+  @apply text-2xl font-semibold tracking-tight;
+}
+
+.typography-prose h4 {
+  @apply text-xl font-semibold tracking-tight;
+}
+
+.typography-prose h5 {
+  @apply text-lg font-semibold tracking-tight;
+}
+
+.typography-prose h6 {
+  @apply text-base font-semibold tracking-tight;
+}
+
+.typography-prose p {
+  @apply text-base leading-7;
+}
+
+.typography-prose code {
+  @apply rounded-md bg-default px-1.5 py-0.5 font-mono text-sm text-foreground;
+}
+
+.typography-prose a {
+  @apply font-medium text-link underline underline-offset-4;
+}
+
+.typography-prose blockquote {
+  @apply mt-4 border-l-4 border-border pl-4 text-muted italic;
+}
+
+.typography-prose ul {
+  @apply my-4 list-disc space-y-2 pl-6;
+}
+
+.typography-prose ol {
+  @apply my-4 list-decimal space-y-2 pl-6;
+}
+
+.typography-prose li {
+  @apply text-base leading-7;
+}
+
+.typography-prose hr {
+  @apply my-8 border-separator;
+}
+
+.typography-prose pre {
+  @apply my-4 overflow-x-auto rounded-xl bg-default p-4 font-mono text-sm leading-relaxed;
+}
+
+.typography-prose strong {
+  @apply font-semibold text-foreground;
+}
+
+.typography-prose em {
+  @apply italic;
+}
+
+.typography-prose img {
+  @apply my-4 rounded-xl;
+}
+
+.typography--h1 {
+  @apply text-4xl font-semibold tracking-tight;
+}
+
+.typography--h2 {
+  @apply text-3xl font-semibold tracking-tight;
+}
+
+.typography--h3 {
+  @apply text-2xl font-semibold tracking-tight;
+}
+
+.typography--h4 {
+  @apply text-xl font-semibold tracking-tight;
+}
+
+.typography--h5 {
+  @apply text-lg font-semibold tracking-tight;
+}
+
+.typography--h6 {
+  @apply text-base font-semibold tracking-tight;
+}
+
+.typography--body {
+  @apply text-base leading-7;
+}
+
+.typography--body-sm {
+  @apply text-sm leading-6;
+}
+
+.typography--body-xs {
+  @apply text-xs leading-5;
+}
+
+.typography--code {
+  @apply rounded-md bg-default px-1.5 py-0.5 font-mono text-sm text-foreground;
+}
+
+.typography--align-start {
+  @apply text-left rtl:text-right;
+}
+
+.typography--align-center {
+  @apply text-center;
+}
+
+.typography--align-end {
+  @apply text-right rtl:text-left;
+}
+
+.typography--align-justify {
+  @apply text-justify;
+}
+
+.typography--color-default {
+  @apply text-foreground;
+}
+
+.typography--color-muted {
+  @apply text-muted;
+}
+
+.typography--truncate {
+  @apply block truncate;
+}
+
+.typography--weight-normal {
+  @apply font-normal;
+}
+
+.typography--weight-medium {
+  @apply font-medium;
+}
+
+.typography--weight-semibold {
+  @apply font-semibold;
+}
+
+.typography--weight-bold {
+  @apply font-bold;
+}
diff --git a/packages/styles/eslint.config.mjs b/packages/styles/eslint.config.mjs
new file mode 100644
index 0000000..2898468
--- /dev/null
+++ b/packages/styles/eslint.config.mjs
@@ -0,0 +1,6 @@
+import baseConfig from "@heroui/standard/eslint/node.mjs";
+import {defineConfig} from "eslint/config";
+
+const config = defineConfig([...baseConfig]);
+
+export default config;
diff --git a/packages/styles/index.css b/packages/styles/index.css
new file mode 100644
index 0000000..e05ee82
--- /dev/null
+++ b/packages/styles/index.css
@@ -0,0 +1,23 @@
+@layer theme, base, components, utilities;
+
+/* HeroUI v3 Styles - Layered Theme Architecture */
+
+/* Base layer - Tailwind CSS v4 */
+@import "tailwindcss";
+@import "tw-animate-css";
+
+/* Base styles */
+@import "./base/base.css" layer(base);
+@import "./base/scrollbar.css" layer(base);
+
+/* Base component structures (unstyled) */
+@import "./components/index.css" layer(components);
+
+/* Default theme (variables + component customizations) */
+@import "./themes/default/index.css" layer(theme);
+
+/* Utilities */
+@import "./utilities/index.css";
+
+/* Variants */
+@import "./variants/index.css";
diff --git a/packages/styles/package.json b/packages/styles/package.json
new file mode 100644
index 0000000..83775bf
--- /dev/null
+++ b/packages/styles/package.json
@@ -0,0 +1,72 @@
+{
+  "name": "@heroui/styles",
+  "version": "3.2.2",
+  "description": "HeroUI core styles and Tailwind plugin",
+  "author": "HeroUI <support@heroui.com>",
+  "homepage": "https://heroui.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heroui-inc/heroui.git",
+    "directory": "packages/styles"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "style": "./index.css",
+  "exports": {
+    ".": {
+      "style": "./index.css",
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./css": {
+      "style": "./index.css",
+      "default": "./index.css"
+    },
+    "./components/*": {
+      "types": "./src/components/*/index.ts",
+      "import": "./src/components/*/index.ts",
+      "default": "./src/components/*/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs --tsc",
+    "dev": "rollup -c rollup.config.mjs --watch",
+    "measure-size": "node scripts/measure-bundle-size.mjs",
+    "clean": "rm -rf dist .turbo tsconfig.tsbuildinfo",
+    "prepack": "clean-package",
+    "postpack": "clean-package restore",
+    "typecheck": "tsc --noEmit"
+  },
+  "clean-package": "./clean-package.config.json",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tailwind-variants": "3.2.2",
+    "tw-animate-css": "1.4.0"
+  },
+  "devDependencies": {
+    "@heroui/standard": "workspace:*",
+    "@tailwindcss/cli": "4.3.0",
+    "@types/fs-extra": "11.0.4",
+    "clean-package": "2.2.0",
+    "fs-extra": "11.3.3",
+    "rimraf": "6.1.2",
+    "tailwindcss": "4.3.0",
+    "typescript": "5.8.3"
+  },
+  "peerDependencies": {
+    "tailwindcss": ">=4.0.0"
+  }
+}
diff --git a/packages/styles/rollup.config.mjs b/packages/styles/rollup.config.mjs
new file mode 100644
index 0000000..33ed243
--- /dev/null
+++ b/packages/styles/rollup.config.mjs
@@ -0,0 +1,66 @@
+import fs from "fs";
+import path from "path";
+
+import resolve from "@rollup/plugin-node-resolve";
+import typescript from "@rollup/plugin-typescript";
+import {defineConfig} from "rollup";
+import peerDepsExternal from "rollup-plugin-peer-deps-external";
+
+const packageJson = JSON.parse(fs.readFileSync("./package.json", "utf-8"));
+
+// Get all component directories
+const componentDirs = fs.readdirSync("./src/components").filter((file) => {
+  const fullPath = path.join("./src/components", file);
+
+  return fs.statSync(fullPath).isDirectory() && fs.existsSync(path.join(fullPath, "index.ts"));
+});
+
+// Create individual entry points for each component
+const componentEntries = componentDirs.reduce((acc, dir) => {
+  acc[`components/${dir}/index`] = `src/components/${dir}/index.ts`;
+
+  return acc;
+}, {});
+
+// All entry points
+const input = {
+  index: "src/index.ts",
+  ...componentEntries,
+};
+
+const external = [
+  ...Object.keys(packageJson.peerDependencies || {}),
+  ...Object.keys(packageJson.dependencies || {}),
+  /^tailwind-variants/,
+];
+
+const plugins = [
+  peerDepsExternal(),
+  resolve({
+    extensions: [".js", ".ts"],
+  }),
+  typescript({
+    declaration: false,
+    exclude: ["node_modules", "dist"],
+    tsconfig: "./tsconfig.json",
+  }),
+];
+
+export default defineConfig({
+  external,
+  input,
+  output: {
+    dir: "dist",
+    exports: "named",
+    format: "es",
+    hoistTransitiveImports: false,
+    preserveModules: true,
+    preserveModulesRoot: "src",
+    sourcemap: false,
+  },
+  plugins,
+  treeshake: {
+    moduleSideEffects: false,
+    propertyReadSideEffects: false,
+  },
+});
diff --git a/packages/styles/scripts/build.mjs b/packages/styles/scripts/build.mjs
new file mode 100644
index 0000000..a6d28c9
--- /dev/null
+++ b/packages/styles/scripts/build.mjs
@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import {execSync} from "child_process";
+import path from "path";
+import {fileURLToPath} from "url";
+
+import fs from "fs-extra";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+const distDir = path.join(rootDir, "dist");
+
+async function clean() {
+  console.log("🧹 Cleaning dist directory...");
+  await fs.remove(distDir);
+}
+
+async function build() {
+  console.log("📦 Building with Rollup...");
+  execSync("rollup -c rollup.config.mjs", {cwd: rootDir, stdio: "inherit"});
+}
+
+async function generateTypes() {
+  console.log("📝 Generating TypeScript declarations...");
+  execSync("tsc --emitDeclarationOnly", {cwd: rootDir, stdio: "inherit"});
+  console.log("✅ TypeScript declarations generated");
+}
+
+async function copyCss() {
+  console.log("🎨 Copying CSS files...");
+  execSync("node scripts/copy-css.mjs", {cwd: rootDir, stdio: "inherit"});
+}
+
+async function minifyCss() {
+  console.log("🗜️  Minifying CSS...");
+  execSync("npx @tailwindcss/cli -i ./dist/index.css -o dist/heroui.min.css --minify", {
+    cwd: rootDir,
+    stdio: "inherit",
+  });
+}
+
+async function main() {
+  try {
+    // Check if --tsc flag is passed
+    const shouldGenerateTypes = process.argv.includes("--tsc");
+
+    await clean();
+    await build();
+
+    if (shouldGenerateTypes) {
+      await generateTypes();
+    } else {
+      console.log("⚡ Skipping TypeScript generation (use --tsc to include)");
+    }
+
+    await copyCss();
+    await minifyCss();
+
+    console.log("✨ Build completed successfully!");
+  } catch (error) {
+    console.error("❌ Build failed:", error);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/packages/styles/scripts/copy-css.mjs b/packages/styles/scripts/copy-css.mjs
new file mode 100644
index 0000000..1b613ed
--- /dev/null
+++ b/packages/styles/scripts/copy-css.mjs
@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import fs from "fs";
+import path from "path";
+import {fileURLToPath} from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+const distDir = path.join(rootDir, "dist");
+
+// Create dist directory if it doesn't exist
+if (!fs.existsSync(distDir)) {
+  fs.mkdirSync(distDir, {recursive: true});
+}
+
+console.log("Copying CSS files to dist...");
+
+// Helper function to recursively copy CSS files
+const copyCssDirectory = (dirName) => {
+  const srcDirPath = path.join(rootDir, dirName);
+  const distDirPath = path.join(distDir, dirName);
+
+  if (!fs.existsSync(srcDirPath)) {
+    return;
+  }
+
+  // Create directory in dist
+  if (!fs.existsSync(distDirPath)) {
+    fs.mkdirSync(distDirPath, {recursive: true});
+  }
+
+  // Read all files in the directory
+  const files = fs.readdirSync(srcDirPath);
+
+  for (const file of files) {
+    const srcFilePath = path.join(srcDirPath, file);
+    const distFilePath = path.join(distDirPath, file);
+    const stat = fs.statSync(srcFilePath);
+
+    if (stat.isDirectory()) {
+      // Recursively copy subdirectories
+      copyCssDirectory(path.join(dirName, file));
+    } else if (file.endsWith(".css")) {
+      // Copy CSS files
+      fs.copyFileSync(srcFilePath, distFilePath);
+      console.log(`✓ Copied: ${path.join(dirName, file)}`);
+    }
+  }
+};
+
+// Copy root index.css
+const indexPath = path.join(rootDir, "index.css");
+
+if (fs.existsSync(indexPath)) {
+  fs.copyFileSync(indexPath, path.join(distDir, "index.css"));
+  console.log("✓ Copied: index.css");
+}
+
+// Copy all CSS files from these directories
+const directories = ["base", "components", "themes", "utilities", "variants"];
+
+for (const dir of directories) {
+  copyCssDirectory(dir);
+}
+
+console.log("✅ CSS files copied successfully!");
diff --git a/packages/styles/scripts/fix-css-attributes.js b/packages/styles/scripts/fix-css-attributes.js
new file mode 100644
index 0000000..c633315
--- /dev/null
+++ b/packages/styles/scripts/fix-css-attributes.js
@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * Script to fix CSS attribute selectors missing ="true" suffix
+ *
+ * Usage:
+ *   node fix-css-attributes.js --dry-run  # Preview changes
+ *   node fix-css-attributes.js            # Apply changes
+ */
+
+import fs from "fs";
+import path from "path";
+import {fileURLToPath} from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Target directory
+const COMPONENTS_DIR = path.join(__dirname, "..", "components");
+
+// Patterns to replace: [attribute] -> [attribute="true"]
+const REPLACEMENT_PATTERNS = [
+  // ARIA attributes
+  {pattern: /\[aria-disabled\](?!=")/g, replacement: '[aria-disabled="true"]'},
+  {pattern: /\[aria-invalid\](?!=")/g, replacement: '[aria-invalid="true"]'},
+  {pattern: /\[aria-checked\](?!=")/g, replacement: '[aria-checked="true"]'},
+  {pattern: /\[aria-selected\](?!=")/g, replacement: '[aria-selected="true"]'},
+  {pattern: /\[aria-expanded\](?!=")/g, replacement: '[aria-expanded="true"]'},
+  {pattern: /\[aria-multiselectable\](?!=")/g, replacement: '[aria-multiselectable="true"]'},
+
+  // Data attributes
+  {pattern: /\[data-hovered\](?!=")/g, replacement: '[data-hovered="true"]'},
+  {pattern: /\[data-focus-visible\](?!=")/g, replacement: '[data-focus-visible="true"]'},
+  {pattern: /\[data-pressed\](?!=")/g, replacement: '[data-pressed="true"]'},
+  {pattern: /\[data-pending\](?!=")/g, replacement: '[data-pending="true"]'},
+  {pattern: /\[data-entering\](?!=")/g, replacement: '[data-entering="true"]'},
+  {pattern: /\[data-exiting\](?!=")/g, replacement: '[data-exiting="true"]'},
+  {pattern: /\[data-open\](?!=")/g, replacement: '[data-open="true"]'},
+  {pattern: /\[data-invalid\](?!=")/g, replacement: '[data-invalid="true"]'},
+];
+
+/**
+ * Check if a file should be processed
+ */
+function shouldProcessFile(filePath) {
+  return filePath.endsWith(".css");
+}
+
+/**
+ * Process a single CSS file
+ */
+function processFile(filePath, dryRun = false) {
+  const content = fs.readFileSync(filePath, "utf8");
+  let modifiedContent = content;
+  const changes = [];
+  const lines = content.split("\n");
+
+  // Collect all matches from all patterns first
+  const allMatches = [];
+
+  for (const {pattern, replacement} of REPLACEMENT_PATTERNS) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    let match;
+
+    regex.lastIndex = 0;
+    while ((match = regex.exec(content)) !== null) {
+      allMatches.push({
+        index: match.index,
+        length: match[0].length,
+        replacement,
+        text: match[0],
+      });
+    }
+  }
+
+  if (allMatches.length === 0) {
+    return {changed: false};
+  }
+
+  // Sort matches by index in descending order for safe replacement
+  allMatches.sort((a, b) => b.index - a.index);
+
+  // Track which lines have changes
+  const lineChanges = new Map();
+
+  // Process matches in reverse order to preserve indices
+  for (const {index, length, replacement, text} of allMatches) {
+    // Find which line this match is on
+    const beforeMatch = content.substring(0, index);
+    const lineNumber = beforeMatch.split("\n").length;
+    const line = lines[lineNumber - 1];
+
+    // Calculate position in line
+    const lastNewlineIndex = beforeMatch.lastIndexOf("\n");
+    const positionInLine = index - (lastNewlineIndex === -1 ? 0 : lastNewlineIndex + 1);
+
+    // Track the change for this line
+    if (!lineChanges.has(lineNumber)) {
+      lineChanges.set(lineNumber, {
+        line: lineNumber,
+        original: line,
+        replacements: [],
+      });
+    }
+
+    const lineChange = lineChanges.get(lineNumber);
+
+    lineChange.replacements.push({
+      length,
+      position: positionInLine,
+      replacement,
+      text,
+    });
+
+    // Perform replacement in content (in reverse order, so indices stay valid)
+    modifiedContent =
+      modifiedContent.substring(0, index) + replacement + modifiedContent.substring(index + length);
+  }
+
+  // Build final change list with properly replaced lines
+  for (const [lineNumber, lineChange] of lineChanges.entries()) {
+    // Sort replacements by position in reverse order
+    lineChange.replacements.sort((a, b) => b.position - a.position);
+
+    let modifiedLine = lineChange.original;
+
+    for (const {length, position, replacement} of lineChange.replacements) {
+      modifiedLine =
+        modifiedLine.substring(0, position) +
+        replacement +
+        modifiedLine.substring(position + length);
+    }
+
+    changes.push({
+      line: lineNumber,
+      original: lineChange.original.trim(),
+      replacement: modifiedLine.trim(),
+    });
+  }
+
+  // Sort changes by line number for display
+  changes.sort((a, b) => a.line - b.line);
+
+  // Only write if content changed
+  if (modifiedContent !== content) {
+    if (!dryRun) {
+      fs.writeFileSync(filePath, modifiedContent, "utf8");
+    }
+
+    return {
+      changed: true,
+      changes,
+      modifiedContent,
+      originalContent: content,
+    };
+  }
+
+  return {changed: false};
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+
+  console.log(
+    `\n${dryRun ? "🔍 DRY RUN MODE - No files will be modified" : "✏️  APPLYING CHANGES"}\n`,
+  );
+  console.log(`Scanning directory: ${COMPONENTS_DIR}\n`);
+
+  // Get all CSS files
+  const files = fs
+    .readdirSync(COMPONENTS_DIR)
+    .filter((file) => shouldProcessFile(file))
+    .map((file) => path.join(COMPONENTS_DIR, file))
+    .sort();
+
+  console.log(`Found ${files.length} CSS file(s)\n`);
+
+  let totalFilesChanged = 0;
+  let totalReplacements = 0;
+
+  // Process each file
+  for (const filePath of files) {
+    const fileName = path.basename(filePath);
+    const result = processFile(filePath, dryRun);
+
+    if (result.changed) {
+      totalFilesChanged++;
+      const replacementCount = result.changes.length;
+
+      totalReplacements += replacementCount;
+
+      console.log(`📝 ${fileName}`);
+      console.log(`   ${replacementCount} replacement(s)`);
+
+      // Show first few changes
+      if (result.changes.length > 0) {
+        const previewCount = Math.min(3, result.changes.length);
+
+        result.changes.slice(0, previewCount).forEach(({line, original, replacement}) => {
+          console.log(`   Line ${line}:`);
+          console.log(`     - ${original}`);
+          console.log(`     + ${replacement}`);
+        });
+        if (result.changes.length > previewCount) {
+          console.log(`   ... and ${result.changes.length - previewCount} more`);
+        }
+      }
+      console.log("");
+    }
+  }
+
+  // Summary
+  console.log("─".repeat(60));
+  console.log(`\nSummary:`);
+  console.log(`  Files processed: ${files.length}`);
+  console.log(`  Files changed: ${totalFilesChanged}`);
+  console.log(`  Total replacements: ${totalReplacements}`);
+
+  if (dryRun) {
+    console.log(`\n💡 Run without --dry-run to apply these changes\n`);
+  } else {
+    console.log(`\n✅ Changes applied successfully!\n`);
+  }
+}
+
+// Run the script
+main();
diff --git a/packages/styles/scripts/measure-bundle-size.mjs b/packages/styles/scripts/measure-bundle-size.mjs
new file mode 100644
index 0000000..1ecd664
--- /dev/null
+++ b/packages/styles/scripts/measure-bundle-size.mjs
@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import {execSync} from "child_process";
+import fs from "fs";
+import path from "path";
+import {fileURLToPath} from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+const distDir = path.join(rootDir, "dist");
+const componentsDir = path.join(rootDir, "components");
+const outputFile = path.join(rootDir, "bundle-size.json");
+
+/**
+ * Get file size in bytes
+ */
+function getFileSize(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+
+    return stats.size;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format bytes to human readable string
+ */
+function formatBytes(bytes) {
+  if (bytes === null) return "N/A";
+  const kb = bytes / 1024;
+
+  return {
+    bytes,
+    formatted: kb >= 1 ? `${kb.toFixed(2)} KB` : `${bytes} B`,
+    kb: Math.round(kb * 1000) / 1000,
+  };
+}
+
+/**
+ * Get sizes for all component CSS files
+ */
+function getComponentSizes() {
+  const components = {};
+
+  if (!fs.existsSync(componentsDir)) {
+    return components;
+  }
+
+  const files = fs
+    .readdirSync(componentsDir)
+    .filter((f) => f.endsWith(".css") && f !== "index.css");
+
+  for (const file of files) {
+    const filePath = path.join(componentsDir, file);
+    const size = getFileSize(filePath);
+
+    if (size !== null) {
+      components[file] = {
+        bytes: size,
+        kb: Math.round((size / 1024) * 1000) / 1000,
+      };
+    }
+  }
+
+  return components;
+}
+
+/**
+ * Build the CSS bundle
+ */
+function buildBundle() {
+  console.log("Building CSS bundle...");
+  try {
+    execSync("npm run build", {
+      cwd: rootDir,
+      stdio: "inherit",
+    });
+    console.log("Build completed.\n");
+
+    return true;
+  } catch (error) {
+    console.error("Build failed:", error.message);
+
+    return false;
+  }
+}
+
+/**
+ * Load previous measurement for comparison
+ */
+function loadPreviousMeasurement() {
+  try {
+    if (fs.existsSync(outputFile)) {
+      const content = fs.readFileSync(outputFile, "utf-8");
+
+      return JSON.parse(content);
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return null;
+}
+
+/**
+ * Calculate and display comparison
+ */
+function showComparison(current, previous, _) {
+  if (!previous) return "";
+
+  const diff = current - previous;
+  const percent = ((diff / previous) * 100).toFixed(2);
+  const arrow = diff > 0 ? "↑" : diff < 0 ? "↓" : "→";
+  const sign = diff > 0 ? "+" : "";
+
+  return ` (${arrow} ${sign}${formatBytes(diff).formatted}, ${sign}${percent}%)`;
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const skipBuild = args.includes("--skip-build");
+  const compareOnly = args.includes("--compare");
+
+  console.log("=".repeat(60));
+  console.log("HeroUI CSS Bundle Size Measurement");
+  console.log("=".repeat(60));
+  console.log();
+
+  // Load previous measurement
+  const previous = loadPreviousMeasurement();
+
+  if (compareOnly && previous) {
+    console.log("Previous measurement from:", previous.timestamp);
+    console.log();
+    console.log("Uncompressed (index.css):", formatBytes(previous.uncompressed.bytes).formatted);
+    console.log("Minified (heroui.min.css):", formatBytes(previous.minified.bytes).formatted);
+    console.log();
+    console.log("Component breakdown:");
+
+    const sortedComponents = Object.entries(previous.components).sort(
+      (a, b) => b[1].bytes - a[1].bytes,
+    );
+
+    for (const [name, size] of sortedComponents.slice(0, 10)) {
+      console.log(`  ${name.padEnd(30)} ${formatBytes(size.bytes).formatted}`);
+    }
+    if (sortedComponents.length > 10) {
+      console.log(`  ... and ${sortedComponents.length - 10} more`);
+    }
+
+    return;
+  }
+
+  // Build unless skipped
+  if (!skipBuild) {
+    const buildSuccess = buildBundle();
+
+    if (!buildSuccess) {
+      process.exit(1);
+    }
+  }
+
+  // Measure sizes
+  const indexPath = path.join(distDir, "index.css");
+  const minifiedPath = path.join(distDir, "heroui.min.css");
+
+  const uncompressedSize = getFileSize(indexPath);
+  const minifiedSize = getFileSize(minifiedPath);
+
+  if (uncompressedSize === null) {
+    console.error("Error: dist/index.css not found. Run build first.");
+    process.exit(1);
+  }
+
+  const components = getComponentSizes();
+
+  // Calculate totals
+  const totalComponentBytes = Object.values(components).reduce((sum, c) => sum + c.bytes, 0);
+
+  // Create result object
+  const result = {
+    components,
+    componentsTotal: formatBytes(totalComponentBytes),
+    minified: formatBytes(minifiedSize),
+    timestamp: new Date().toISOString(),
+    uncompressed: formatBytes(uncompressedSize),
+  };
+
+  // Display results
+  console.log("Bundle Sizes:");
+  console.log("-".repeat(60));
+  console.log(
+    `Uncompressed (index.css):   ${result.uncompressed.formatted}${previous ? showComparison(uncompressedSize, previous.uncompressed.bytes, "uncompressed") : ""}`,
+  );
+  console.log(
+    `Minified (heroui.min.css):  ${result.minified.formatted}${previous ? showComparison(minifiedSize, previous.minified.bytes, "minified") : ""}`,
+  );
+  console.log(
+    `Components total:           ${result.componentsTotal.formatted}${previous ? showComparison(totalComponentBytes, previous.componentsTotal?.bytes, "components") : ""}`,
+  );
+  console.log();
+
+  // Component breakdown (top 10 largest)
+  console.log("Top 10 Largest Components:");
+  console.log("-".repeat(60));
+
+  const sortedComponents = Object.entries(components).sort((a, b) => b[1].bytes - a[1].bytes);
+
+  for (const [name, size] of sortedComponents.slice(0, 10)) {
+    const prevSize = previous?.components?.[name]?.bytes;
+    const comparison = prevSize ? showComparison(size.bytes, prevSize, name) : "";
+
+    console.log(
+      `  ${name.padEnd(30)} ${formatBytes(size.bytes).formatted.padStart(12)}${comparison}`,
+    );
+  }
+
+  console.log();
+
+  // Save results
+  fs.writeFileSync(outputFile, JSON.stringify(result, null, 2));
+  console.log(`Results saved to: bundle-size.json`);
+
+  // Summary comparison
+  if (previous) {
+    console.log();
+    console.log("=".repeat(60));
+    console.log("Summary vs Previous Measurement");
+    console.log("=".repeat(60));
+
+    const uncompressedDiff = uncompressedSize - previous.uncompressed.bytes;
+    const minifiedDiff = minifiedSize - previous.minified.bytes;
+
+    console.log(`Previous timestamp: ${previous.timestamp}`);
+    console.log(`Current timestamp:  ${result.timestamp}`);
+    console.log();
+    console.log(
+      `Uncompressed change: ${uncompressedDiff > 0 ? "+" : ""}${formatBytes(uncompressedDiff).formatted}`,
+    );
+    console.log(
+      `Minified change:     ${minifiedDiff > 0 ? "+" : ""}${formatBytes(minifiedDiff).formatted}`,
+    );
+
+    if (minifiedDiff < 0) {
+      const savedPercent = ((-minifiedDiff / previous.minified.bytes) * 100).toFixed(2);
+
+      console.log();
+      console.log(`🎉 Bundle size reduced by ${savedPercent}%!`);
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error("Error:", error);
+  process.exit(1);
+});
diff --git a/packages/styles/src/components/accordion/accordion.styles.ts b/packages/styles/src/components/accordion/accordion.styles.ts
new file mode 100644
index 0000000..b6f3d71
--- /dev/null
+++ b/packages/styles/src/components/accordion/accordion.styles.ts
@@ -0,0 +1,32 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const accordionVariants = tv({
+  slots: {
+    base: "accordion",
+    body: "accordion__body",
+    bodyInner: "accordion__body-inner",
+    heading: "accordion__heading",
+    indicator: "accordion__indicator",
+    item: "accordion__item",
+    panel: "accordion__panel",
+    trigger: "accordion__trigger",
+  },
+  variants: {
+    variant: {
+      default: {},
+      surface: {
+        base: "accordion--surface",
+      },
+    },
+  },
+});
+
+// Render props that should be excluded from AccordionVariants (framework-specific)
+type DisclosureRenderPropsKeys = "isExpanded" | "isDisabled" | "state";
+
+export type AccordionVariants = Omit<
+  VariantProps<typeof accordionVariants>,
+  DisclosureRenderPropsKeys
+>;
diff --git a/packages/styles/src/components/accordion/index.ts b/packages/styles/src/components/accordion/index.ts
new file mode 100644
index 0000000..e91726a
--- /dev/null
+++ b/packages/styles/src/components/accordion/index.ts
@@ -0,0 +1 @@
+export * from "./accordion.styles";
diff --git a/packages/styles/src/components/alert-dialog/alert-dialog.styles.ts b/packages/styles/src/components/alert-dialog/alert-dialog.styles.ts
new file mode 100644
index 0000000..0d66437
--- /dev/null
+++ b/packages/styles/src/components/alert-dialog/alert-dialog.styles.ts
@@ -0,0 +1,72 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const alertDialogVariants = tv({
+  defaultVariants: {
+    size: "md",
+    status: "danger",
+    variant: "opaque",
+  },
+  slots: {
+    backdrop: "alert-dialog__backdrop",
+    body: "alert-dialog__body",
+    closeTrigger: "alert-dialog__close-trigger",
+    container: "alert-dialog__container",
+    dialog: "alert-dialog__dialog",
+    footer: "alert-dialog__footer",
+    header: "alert-dialog__header",
+    heading: "alert-dialog__heading",
+    icon: "alert-dialog__icon",
+    trigger: "alert-dialog__trigger",
+  },
+  variants: {
+    size: {
+      cover: {
+        dialog: "alert-dialog__dialog--cover",
+      },
+      lg: {
+        dialog: "alert-dialog__dialog--lg",
+      },
+      md: {
+        dialog: "alert-dialog__dialog--md",
+      },
+      sm: {
+        dialog: "alert-dialog__dialog--sm",
+      },
+      xs: {
+        dialog: "alert-dialog__dialog--xs",
+      },
+    },
+    status: {
+      accent: {
+        icon: "alert-dialog__icon--accent",
+      },
+      danger: {
+        icon: "alert-dialog__icon--danger",
+      },
+      default: {
+        icon: "alert-dialog__icon--default",
+      },
+      success: {
+        icon: "alert-dialog__icon--success",
+      },
+      warning: {
+        icon: "alert-dialog__icon--warning",
+      },
+    },
+    variant: {
+      blur: {
+        backdrop: "alert-dialog__backdrop--blur",
+      },
+      opaque: {
+        backdrop: "alert-dialog__backdrop--opaque",
+      },
+      transparent: {
+        backdrop: "alert-dialog__backdrop--transparent",
+      },
+    },
+  },
+});
+
+export type AlertDialogVariants = VariantProps<typeof alertDialogVariants>;
diff --git a/packages/styles/src/components/alert-dialog/index.ts b/packages/styles/src/components/alert-dialog/index.ts
new file mode 100644
index 0000000..13615d8
--- /dev/null
+++ b/packages/styles/src/components/alert-dialog/index.ts
@@ -0,0 +1 @@
+export * from "./alert-dialog.styles";
diff --git a/packages/styles/src/components/alert/alert.styles.ts b/packages/styles/src/components/alert/alert.styles.ts
new file mode 100644
index 0000000..5cb3404
--- /dev/null
+++ b/packages/styles/src/components/alert/alert.styles.ts
@@ -0,0 +1,37 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const alertVariants = tv({
+  defaultVariants: {
+    status: "default",
+  },
+  slots: {
+    base: "alert",
+    content: "alert__content",
+    description: "alert__description",
+    indicator: "alert__indicator",
+    title: "alert__title",
+  },
+  variants: {
+    status: {
+      accent: {
+        base: "alert--accent",
+      },
+      danger: {
+        base: "alert--danger",
+      },
+      default: {
+        base: "alert--default",
+      },
+      success: {
+        base: "alert--success",
+      },
+      warning: {
+        base: "alert--warning",
+      },
+    },
+  },
+});
+
+export type AlertVariants = VariantProps<typeof alertVariants>;
diff --git a/packages/styles/src/components/alert/index.ts b/packages/styles/src/components/alert/index.ts
new file mode 100644
index 0000000..03e0c6b
--- /dev/null
+++ b/packages/styles/src/components/alert/index.ts
@@ -0,0 +1 @@
+export * from "./alert.styles";
diff --git a/packages/styles/src/components/autocomplete/autocomplete.styles.ts b/packages/styles/src/components/autocomplete/autocomplete.styles.ts
new file mode 100644
index 0000000..69fa335
--- /dev/null
+++ b/packages/styles/src/components/autocomplete/autocomplete.styles.ts
@@ -0,0 +1,39 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const autocompleteVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "autocomplete",
+    clearButton: "autocomplete__clear-button",
+    filter: "autocomplete__filter",
+    indicator: "autocomplete__indicator",
+    popover: "autocomplete__popover",
+    popoverDialog: "autocomplete__popover-dialog",
+    trigger: "autocomplete__trigger",
+    value: "autocomplete__value",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "autocomplete--full-width",
+        trigger: "autocomplete__trigger--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "autocomplete--primary",
+      },
+      secondary: {
+        base: "autocomplete--secondary",
+      },
+    },
+  },
+});
+
+export type AutocompleteVariants = VariantProps<typeof autocompleteVariants>;
diff --git a/packages/styles/src/components/autocomplete/index.ts b/packages/styles/src/components/autocomplete/index.ts
new file mode 100644
index 0000000..beecdb3
--- /dev/null
+++ b/packages/styles/src/components/autocomplete/index.ts
@@ -0,0 +1 @@
+export * from "./autocomplete.styles";
diff --git a/packages/styles/src/components/avatar/avatar.styles.ts b/packages/styles/src/components/avatar/avatar.styles.ts
new file mode 100644
index 0000000..49722ef
--- /dev/null
+++ b/packages/styles/src/components/avatar/avatar.styles.ts
@@ -0,0 +1,53 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const avatarVariants = tv({
+  defaultVariants: {
+    color: "default",
+    size: "md",
+  },
+  slots: {
+    base: "avatar",
+    fallback: "avatar__fallback",
+    image: "avatar__image",
+  },
+  variants: {
+    color: {
+      accent: {
+        fallback: "avatar__fallback--accent",
+      },
+      danger: {
+        fallback: "avatar__fallback--danger",
+      },
+      default: {
+        fallback: "avatar__fallback--default",
+      },
+      success: {
+        fallback: "avatar__fallback--success",
+      },
+      warning: {
+        fallback: "avatar__fallback--warning",
+      },
+    },
+    size: {
+      lg: {
+        base: "avatar--lg",
+      },
+      md: {
+        base: "avatar--md",
+      },
+      sm: {
+        base: "avatar--sm",
+      },
+    },
+    variant: {
+      default: {},
+      soft: {
+        base: "avatar--soft",
+      },
+    },
+  },
+});
+
+export type AvatarVariants = VariantProps<typeof avatarVariants>;
diff --git a/packages/styles/src/components/avatar/index.ts b/packages/styles/src/components/avatar/index.ts
new file mode 100644
index 0000000..6260123
--- /dev/null
+++ b/packages/styles/src/components/avatar/index.ts
@@ -0,0 +1 @@
+export * from "./avatar.styles";
diff --git a/packages/styles/src/components/badge/badge.styles.ts b/packages/styles/src/components/badge/badge.styles.ts
new file mode 100644
index 0000000..f491dc7
--- /dev/null
+++ b/packages/styles/src/components/badge/badge.styles.ts
@@ -0,0 +1,74 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const badgeVariants = tv({
+  defaultVariants: {
+    color: "default",
+    placement: "top-right",
+    size: "md",
+    variant: "primary",
+  },
+  slots: {
+    anchor: "badge-anchor",
+    base: "badge",
+    label: "badge__label",
+  },
+  variants: {
+    color: {
+      accent: {
+        base: "badge--accent",
+      },
+      danger: {
+        base: "badge--danger",
+      },
+      default: {
+        base: "badge--default",
+      },
+      success: {
+        base: "badge--success",
+      },
+      warning: {
+        base: "badge--warning",
+      },
+    },
+    placement: {
+      "bottom-left": {
+        base: "badge--bottom-left",
+      },
+      "bottom-right": {
+        base: "badge--bottom-right",
+      },
+      "top-left": {
+        base: "badge--top-left",
+      },
+      "top-right": {
+        base: "badge--top-right",
+      },
+    },
+    size: {
+      lg: {
+        base: "badge--lg",
+      },
+      md: {
+        base: "badge--md",
+      },
+      sm: {
+        base: "badge--sm",
+      },
+    },
+    variant: {
+      primary: {
+        base: "badge--primary",
+      },
+      secondary: {
+        base: "badge--secondary",
+      },
+      soft: {
+        base: "badge--soft",
+      },
+    },
+  },
+});
+
+export type BadgeVariants = VariantProps<typeof badgeVariants>;
diff --git a/packages/styles/src/components/badge/index.ts b/packages/styles/src/components/badge/index.ts
new file mode 100644
index 0000000..7ef39e5
--- /dev/null
+++ b/packages/styles/src/components/badge/index.ts
@@ -0,0 +1 @@
+export * from "./badge.styles";
diff --git a/packages/styles/src/components/breadcrumbs/breadcrumbs.styles.ts b/packages/styles/src/components/breadcrumbs/breadcrumbs.styles.ts
new file mode 100644
index 0000000..edc4f59
--- /dev/null
+++ b/packages/styles/src/components/breadcrumbs/breadcrumbs.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const breadcrumbsVariants = tv({
+  slots: {
+    base: "breadcrumbs",
+    item: "breadcrumbs__item",
+    link: "breadcrumbs__link",
+    separator: "breadcrumbs__separator",
+  },
+});
+
+export type BreadcrumbsVariants = VariantProps<typeof breadcrumbsVariants>;
diff --git a/packages/styles/src/components/breadcrumbs/index.ts b/packages/styles/src/components/breadcrumbs/index.ts
new file mode 100644
index 0000000..dbc34a7
--- /dev/null
+++ b/packages/styles/src/components/breadcrumbs/index.ts
@@ -0,0 +1 @@
+export * from "./breadcrumbs.styles";
diff --git a/packages/styles/src/components/button-group/button-group.styles.ts b/packages/styles/src/components/button-group/button-group.styles.ts
new file mode 100644
index 0000000..3b271e2
--- /dev/null
+++ b/packages/styles/src/components/button-group/button-group.styles.ts
@@ -0,0 +1,32 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const buttonGroupVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    orientation: "horizontal",
+  },
+  slots: {
+    base: "button-group",
+    separator: "button-group__separator",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "button-group--full-width",
+      },
+    },
+    orientation: {
+      horizontal: {
+        base: "button-group--horizontal",
+      },
+      vertical: {
+        base: "button-group--vertical",
+      },
+    },
+  },
+});
+
+export type ButtonGroupVariants = VariantProps<typeof buttonGroupVariants>;
diff --git a/packages/styles/src/components/button-group/index.ts b/packages/styles/src/components/button-group/index.ts
new file mode 100644
index 0000000..88d5d26
--- /dev/null
+++ b/packages/styles/src/components/button-group/index.ts
@@ -0,0 +1 @@
+export * from "./button-group.styles";
diff --git a/packages/styles/src/components/button/button.styles.ts b/packages/styles/src/components/button/button.styles.ts
new file mode 100644
index 0000000..283c87c
--- /dev/null
+++ b/packages/styles/src/components/button/button.styles.ts
@@ -0,0 +1,38 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const buttonVariants = tv({
+  base: "button",
+  defaultVariants: {
+    fullWidth: false,
+    isIconOnly: false,
+    size: "md",
+    variant: "primary",
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "button--full-width",
+    },
+    isIconOnly: {
+      true: "button--icon-only",
+    },
+    size: {
+      lg: "button--lg",
+      md: "button--md",
+      sm: "button--sm",
+    },
+    variant: {
+      danger: "button--danger",
+      "danger-soft": "button--danger-soft",
+      ghost: "button--ghost",
+      outline: "button--outline",
+      primary: "button--primary",
+      secondary: "button--secondary",
+      tertiary: "button--tertiary",
+    },
+  },
+});
+
+export type ButtonVariants = VariantProps<typeof buttonVariants>;
diff --git a/packages/styles/src/components/button/index.ts b/packages/styles/src/components/button/index.ts
new file mode 100644
index 0000000..70489eb
--- /dev/null
+++ b/packages/styles/src/components/button/index.ts
@@ -0,0 +1 @@
+export * from "./button.styles";
diff --git a/packages/styles/src/components/calendar-year-picker/calendar-year-picker.styles.ts b/packages/styles/src/components/calendar-year-picker/calendar-year-picker.styles.ts
new file mode 100644
index 0000000..c8a4904
--- /dev/null
+++ b/packages/styles/src/components/calendar-year-picker/calendar-year-picker.styles.ts
@@ -0,0 +1,15 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const calendarYearPickerVariants = tv({
+  slots: {
+    trigger: "calendar-year-picker__trigger",
+    triggerHeading: "calendar-year-picker__trigger-heading",
+    triggerIndicator: "calendar-year-picker__trigger-indicator",
+    yearCell: "calendar-year-picker__year-cell",
+    yearGrid: "calendar-year-picker__year-grid",
+  },
+});
+
+export type CalendarYearPickerVariants = VariantProps<typeof calendarYearPickerVariants>;
diff --git a/packages/styles/src/components/calendar-year-picker/index.ts b/packages/styles/src/components/calendar-year-picker/index.ts
new file mode 100644
index 0000000..1c842f2
--- /dev/null
+++ b/packages/styles/src/components/calendar-year-picker/index.ts
@@ -0,0 +1 @@
+export * from "./calendar-year-picker.styles";
diff --git a/packages/styles/src/components/calendar/calendar.styles.ts b/packages/styles/src/components/calendar/calendar.styles.ts
new file mode 100644
index 0000000..f010368
--- /dev/null
+++ b/packages/styles/src/components/calendar/calendar.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const calendarVariants = tv({
+  defaultVariants: {},
+  slots: {
+    /** Root calendar container */
+    base: "calendar",
+    /** Calendar cell (td) */
+    cell: "calendar__cell",
+    /** Cell indicator (small dot at bottom of cell) */
+    cellIndicator: "calendar__cell-indicator",
+    /** Calendar grid (table) */
+    grid: "calendar__grid",
+    /** Grid body (tbody) */
+    gridBody: "calendar__grid-body",
+    /** Grid header (thead) */
+    gridHeader: "calendar__grid-header",
+    /** Grid row (tr) */
+    gridRow: "calendar__grid-row",
+    /** Calendar header containing heading and navigation */
+    header: "calendar__header",
+    /** Header cell (th - day names) */
+    headerCell: "calendar__header-cell",
+    /** Month/year heading text */
+    heading: "calendar__heading",
+    /** Previous/Next navigation button */
+    navButton: "calendar__nav-button",
+    /** Navigation button icon */
+    navButtonIcon: "calendar__nav-button-icon",
+  },
+  variants: {},
+});
+
+export type CalendarVariants = VariantProps<typeof calendarVariants>;
diff --git a/packages/styles/src/components/calendar/index.ts b/packages/styles/src/components/calendar/index.ts
new file mode 100644
index 0000000..5ccdbce
--- /dev/null
+++ b/packages/styles/src/components/calendar/index.ts
@@ -0,0 +1 @@
+export * from "./calendar.styles";
diff --git a/packages/styles/src/components/card/card.styles.ts b/packages/styles/src/components/card/card.styles.ts
new file mode 100644
index 0000000..23f1dac
--- /dev/null
+++ b/packages/styles/src/components/card/card.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+const cardVariants = tv({
+  defaultVariants: {
+    variant: "default",
+  },
+  slots: {
+    base: "card",
+    content: "card__content",
+    description: "card__description",
+    footer: "card__footer",
+    header: "card__header",
+    title: "card__title",
+  },
+  variants: {
+    variant: {
+      default: {
+        base: "card--default",
+      },
+      secondary: {
+        base: "card--secondary",
+      },
+      tertiary: {
+        base: "card--tertiary",
+      },
+      transparent: {
+        base: "card--transparent",
+      },
+    },
+  },
+});
+
+export {cardVariants};
+export type CardVariants = VariantProps<typeof cardVariants>;
diff --git a/packages/styles/src/components/card/index.ts b/packages/styles/src/components/card/index.ts
new file mode 100644
index 0000000..a0ce40a
--- /dev/null
+++ b/packages/styles/src/components/card/index.ts
@@ -0,0 +1 @@
+export * from "./card.styles";
diff --git a/packages/styles/src/components/checkbox-group/checkbox-group.styles.ts b/packages/styles/src/components/checkbox-group/checkbox-group.styles.ts
new file mode 100644
index 0000000..8d642a9
--- /dev/null
+++ b/packages/styles/src/components/checkbox-group/checkbox-group.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const checkboxGroupVariants = tv({
+  base: "checkbox-group",
+  defaultVariants: {
+    variant: "primary",
+  },
+  variants: {
+    variant: {
+      primary: "checkbox-group--primary",
+      secondary: "checkbox-group--secondary",
+    },
+  },
+});
+
+export type CheckboxGroupVariants = VariantProps<typeof checkboxGroupVariants>;
diff --git a/packages/styles/src/components/checkbox-group/index.ts b/packages/styles/src/components/checkbox-group/index.ts
new file mode 100644
index 0000000..5df42e3
--- /dev/null
+++ b/packages/styles/src/components/checkbox-group/index.ts
@@ -0,0 +1 @@
+export * from "./checkbox-group.styles";
diff --git a/packages/styles/src/components/checkbox/checkbox.styles.ts b/packages/styles/src/components/checkbox/checkbox.styles.ts
new file mode 100644
index 0000000..3ecf61e
--- /dev/null
+++ b/packages/styles/src/components/checkbox/checkbox.styles.ts
@@ -0,0 +1,27 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const checkboxVariants = tv({
+  defaultVariants: {
+    variant: "primary",
+  },
+  slots: {
+    base: "checkbox",
+    content: "checkbox__content",
+    control: "checkbox__control",
+    indicator: "checkbox__indicator",
+  },
+  variants: {
+    variant: {
+      primary: {
+        base: "checkbox--primary",
+      },
+      secondary: {
+        base: "checkbox--secondary",
+      },
+    },
+  },
+});
+
+export type CheckboxVariants = VariantProps<typeof checkboxVariants>;
diff --git a/packages/styles/src/components/checkbox/index.ts b/packages/styles/src/components/checkbox/index.ts
new file mode 100644
index 0000000..067873e
--- /dev/null
+++ b/packages/styles/src/components/checkbox/index.ts
@@ -0,0 +1 @@
+export * from "./checkbox.styles";
diff --git a/packages/styles/src/components/chip/chip.styles.ts b/packages/styles/src/components/chip/chip.styles.ts
new file mode 100644
index 0000000..5a3e899
--- /dev/null
+++ b/packages/styles/src/components/chip/chip.styles.ts
@@ -0,0 +1,60 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const chipVariants = tv({
+  defaultVariants: {
+    color: "default",
+    variant: "secondary",
+  },
+  slots: {
+    base: "chip",
+    label: "chip__label",
+  },
+  variants: {
+    color: {
+      accent: {
+        base: "chip--accent",
+      },
+      danger: {
+        base: "chip--danger",
+      },
+      default: {
+        base: "chip--default",
+      },
+      success: {
+        base: "chip--success",
+      },
+      warning: {
+        base: "chip--warning",
+      },
+    },
+    size: {
+      lg: {
+        base: "chip--lg",
+      },
+      md: {
+        base: "chip--md",
+      },
+      sm: {
+        base: "chip--sm",
+      },
+    },
+    variant: {
+      primary: {
+        base: "chip--primary",
+      },
+      secondary: {
+        base: "chip--secondary",
+      },
+      soft: {
+        base: "chip--soft",
+      },
+      tertiary: {
+        base: "chip--tertiary",
+      },
+    },
+  },
+});
+
+export type ChipVariants = VariantProps<typeof chipVariants>;
diff --git a/packages/styles/src/components/chip/index.ts b/packages/styles/src/components/chip/index.ts
new file mode 100644
index 0000000..2a5552f
--- /dev/null
+++ b/packages/styles/src/components/chip/index.ts
@@ -0,0 +1 @@
+export * from "./chip.styles";
diff --git a/packages/styles/src/components/close-button/close-button.styles.ts b/packages/styles/src/components/close-button/close-button.styles.ts
new file mode 100644
index 0000000..697d018
--- /dev/null
+++ b/packages/styles/src/components/close-button/close-button.styles.ts
@@ -0,0 +1,17 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const closeButtonVariants = tv({
+  base: "close-button",
+  defaultVariants: {
+    variant: "default",
+  },
+  variants: {
+    variant: {
+      default: "close-button--default",
+    },
+  },
+});
+
+export type CloseButtonVariants = VariantProps<typeof closeButtonVariants>;
diff --git a/packages/styles/src/components/close-button/index.ts b/packages/styles/src/components/close-button/index.ts
new file mode 100644
index 0000000..9dab0c9
--- /dev/null
+++ b/packages/styles/src/components/close-button/index.ts
@@ -0,0 +1 @@
+export * from "./close-button.styles";
diff --git a/packages/styles/src/components/color-area/color-area.styles.ts b/packages/styles/src/components/color-area/color-area.styles.ts
new file mode 100644
index 0000000..063a1c3
--- /dev/null
+++ b/packages/styles/src/components/color-area/color-area.styles.ts
@@ -0,0 +1,23 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorAreaVariants = tv({
+  defaultVariants: {
+    showDots: false,
+  },
+  slots: {
+    base: "color-area",
+    thumb: "color-area__thumb",
+  },
+  variants: {
+    showDots: {
+      false: {},
+      true: {
+        base: "color-area--show-dots",
+      },
+    },
+  },
+});
+
+export type ColorAreaVariants = VariantProps<typeof colorAreaVariants>;
diff --git a/packages/styles/src/components/color-area/index.ts b/packages/styles/src/components/color-area/index.ts
new file mode 100644
index 0000000..f3bca65
--- /dev/null
+++ b/packages/styles/src/components/color-area/index.ts
@@ -0,0 +1 @@
+export * from "./color-area.styles";
diff --git a/packages/styles/src/components/color-field/color-field.styles.ts b/packages/styles/src/components/color-field/color-field.styles.ts
new file mode 100644
index 0000000..ce65e3a
--- /dev/null
+++ b/packages/styles/src/components/color-field/color-field.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorFieldVariants = tv({
+  base: "color-field",
+  defaultVariants: {
+    fullWidth: false,
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "color-field--full-width",
+    },
+  },
+});
+
+export type ColorFieldVariants = VariantProps<typeof colorFieldVariants>;
diff --git a/packages/styles/src/components/color-field/index.ts b/packages/styles/src/components/color-field/index.ts
new file mode 100644
index 0000000..039646b
--- /dev/null
+++ b/packages/styles/src/components/color-field/index.ts
@@ -0,0 +1 @@
+export * from "./color-field.styles";
diff --git a/packages/styles/src/components/color-input-group/color-input-group.styles.ts b/packages/styles/src/components/color-input-group/color-input-group.styles.ts
new file mode 100644
index 0000000..7d10ead
--- /dev/null
+++ b/packages/styles/src/components/color-input-group/color-input-group.styles.ts
@@ -0,0 +1,34 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorInputGroupVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "color-input-group",
+    input: "color-input-group__input",
+    prefix: "color-input-group__prefix",
+    suffix: "color-input-group__suffix",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "color-input-group--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "color-input-group--primary",
+      },
+      secondary: {
+        base: "color-input-group--secondary",
+      },
+    },
+  },
+});
+
+export type ColorInputGroupVariants = VariantProps<typeof colorInputGroupVariants>;
diff --git a/packages/styles/src/components/color-input-group/index.ts b/packages/styles/src/components/color-input-group/index.ts
new file mode 100644
index 0000000..76c19c1
--- /dev/null
+++ b/packages/styles/src/components/color-input-group/index.ts
@@ -0,0 +1 @@
+export * from "./color-input-group.styles";
diff --git a/packages/styles/src/components/color-picker/color-picker.styles.ts b/packages/styles/src/components/color-picker/color-picker.styles.ts
new file mode 100644
index 0000000..602e620
--- /dev/null
+++ b/packages/styles/src/components/color-picker/color-picker.styles.ts
@@ -0,0 +1,13 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorPickerVariants = tv({
+  slots: {
+    base: "color-picker",
+    popover: "color-picker__popover",
+    trigger: "color-picker__trigger",
+  },
+});
+
+export type ColorPickerVariants = VariantProps<typeof colorPickerVariants>;
diff --git a/packages/styles/src/components/color-picker/index.ts b/packages/styles/src/components/color-picker/index.ts
new file mode 100644
index 0000000..26cf1f5
--- /dev/null
+++ b/packages/styles/src/components/color-picker/index.ts
@@ -0,0 +1 @@
+export * from "./color-picker.styles";
diff --git a/packages/styles/src/components/color-slider/color-slider.styles.ts b/packages/styles/src/components/color-slider/color-slider.styles.ts
new file mode 100644
index 0000000..b9d631f
--- /dev/null
+++ b/packages/styles/src/components/color-slider/color-slider.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorSliderVariants = tv({
+  slots: {
+    base: "color-slider",
+    output: "color-slider__output",
+    thumb: "color-slider__thumb",
+    track: "color-slider__track",
+  },
+});
+
+export type ColorSliderVariants = VariantProps<typeof colorSliderVariants>;
diff --git a/packages/styles/src/components/color-slider/index.ts b/packages/styles/src/components/color-slider/index.ts
new file mode 100644
index 0000000..cf3da52
--- /dev/null
+++ b/packages/styles/src/components/color-slider/index.ts
@@ -0,0 +1 @@
+export * from "./color-slider.styles";
diff --git a/packages/styles/src/components/color-swatch-picker/color-swatch-picker.styles.ts b/packages/styles/src/components/color-swatch-picker/color-swatch-picker.styles.ts
new file mode 100644
index 0000000..62f05b5
--- /dev/null
+++ b/packages/styles/src/components/color-swatch-picker/color-swatch-picker.styles.ts
@@ -0,0 +1,54 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorSwatchPickerVariants = tv({
+  defaultVariants: {
+    layout: "grid",
+    size: "md",
+    variant: "circle",
+  },
+  slots: {
+    base: "color-swatch-picker",
+    indicator: "color-swatch-picker__indicator",
+    item: "color-swatch-picker__item",
+    swatch: "color-swatch-picker__swatch",
+  },
+  variants: {
+    layout: {
+      grid: {
+        base: "color-swatch-picker--grid",
+      },
+      stack: {
+        base: "color-swatch-picker--stack",
+      },
+    },
+    size: {
+      lg: {
+        base: "color-swatch-picker--lg",
+      },
+      md: {
+        base: "color-swatch-picker--md",
+      },
+      sm: {
+        base: "color-swatch-picker--sm",
+      },
+      xl: {
+        base: "color-swatch-picker--xl",
+      },
+      xs: {
+        base: "color-swatch-picker--xs",
+      },
+    },
+    variant: {
+      circle: {
+        base: "color-swatch-picker--circle",
+      },
+      square: {
+        base: "color-swatch-picker--square",
+      },
+    },
+  },
+});
+
+export type ColorSwatchPickerVariants = VariantProps<typeof colorSwatchPickerVariants>;
diff --git a/packages/styles/src/components/color-swatch-picker/index.ts b/packages/styles/src/components/color-swatch-picker/index.ts
new file mode 100644
index 0000000..cc773b3
--- /dev/null
+++ b/packages/styles/src/components/color-swatch-picker/index.ts
@@ -0,0 +1 @@
+export * from "./color-swatch-picker.styles";
diff --git a/packages/styles/src/components/color-swatch/color-swatch.styles.ts b/packages/styles/src/components/color-swatch/color-swatch.styles.ts
new file mode 100644
index 0000000..742bbd3
--- /dev/null
+++ b/packages/styles/src/components/color-swatch/color-swatch.styles.ts
@@ -0,0 +1,26 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const colorSwatchVariants = tv({
+  base: "color-swatch",
+  defaultVariants: {
+    shape: "circle",
+    size: "md",
+  },
+  variants: {
+    shape: {
+      circle: "color-swatch--circle",
+      square: "color-swatch--square",
+    },
+    size: {
+      lg: "color-swatch--lg",
+      md: "color-swatch--md",
+      sm: "color-swatch--sm",
+      xl: "color-swatch--xl",
+      xs: "color-swatch--xs",
+    },
+  },
+});
+
+export type ColorSwatchVariants = VariantProps<typeof colorSwatchVariants>;
diff --git a/packages/styles/src/components/color-swatch/index.ts b/packages/styles/src/components/color-swatch/index.ts
new file mode 100644
index 0000000..132f907
--- /dev/null
+++ b/packages/styles/src/components/color-swatch/index.ts
@@ -0,0 +1 @@
+export * from "./color-swatch.styles";
diff --git a/packages/styles/src/components/combo-box/combo-box.styles.ts b/packages/styles/src/components/combo-box/combo-box.styles.ts
new file mode 100644
index 0000000..aa3c336
--- /dev/null
+++ b/packages/styles/src/components/combo-box/combo-box.styles.ts
@@ -0,0 +1,26 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const comboBoxVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+  },
+  slots: {
+    base: "combo-box",
+    inputGroup: "combo-box__input-group",
+    popover: "combo-box__popover",
+    trigger: "combo-box__trigger",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "combo-box--full-width",
+        inputGroup: "combo-box__input-group--full-width",
+      },
+    },
+  },
+});
+
+export type ComboBoxVariants = VariantProps<typeof comboBoxVariants>;
diff --git a/packages/styles/src/components/combo-box/index.ts b/packages/styles/src/components/combo-box/index.ts
new file mode 100644
index 0000000..e31d1d2
--- /dev/null
+++ b/packages/styles/src/components/combo-box/index.ts
@@ -0,0 +1 @@
+export * from "./combo-box.styles";
diff --git a/packages/styles/src/components/date-field/date-field.styles.ts b/packages/styles/src/components/date-field/date-field.styles.ts
new file mode 100644
index 0000000..d3e7793
--- /dev/null
+++ b/packages/styles/src/components/date-field/date-field.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const dateFieldVariants = tv({
+  base: "date-field",
+  defaultVariants: {
+    fullWidth: false,
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "date-field--full-width",
+    },
+  },
+});
+
+export type DateFieldVariants = VariantProps<typeof dateFieldVariants>;
diff --git a/packages/styles/src/components/date-field/index.ts b/packages/styles/src/components/date-field/index.ts
new file mode 100644
index 0000000..40977b1
--- /dev/null
+++ b/packages/styles/src/components/date-field/index.ts
@@ -0,0 +1 @@
+export * from "./date-field.styles";
diff --git a/packages/styles/src/components/date-input-group/date-input-group.styles.ts b/packages/styles/src/components/date-input-group/date-input-group.styles.ts
new file mode 100644
index 0000000..636de3e
--- /dev/null
+++ b/packages/styles/src/components/date-input-group/date-input-group.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const dateInputGroupVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "date-input-group",
+    input: "date-input-group__input",
+    inputContainer: "date-input-group__input-container",
+    prefix: "date-input-group__prefix",
+    segment: "date-input-group__segment",
+    suffix: "date-input-group__suffix",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "date-input-group--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "date-input-group--primary",
+      },
+      secondary: {
+        base: "date-input-group--secondary",
+      },
+    },
+  },
+});
+
+export type DateInputGroupVariants = VariantProps<typeof dateInputGroupVariants>;
diff --git a/packages/styles/src/components/date-input-group/index.ts b/packages/styles/src/components/date-input-group/index.ts
new file mode 100644
index 0000000..c3858d3
--- /dev/null
+++ b/packages/styles/src/components/date-input-group/index.ts
@@ -0,0 +1 @@
+export * from "./date-input-group.styles";
diff --git a/packages/styles/src/components/date-picker/date-picker.styles.ts b/packages/styles/src/components/date-picker/date-picker.styles.ts
new file mode 100644
index 0000000..d77347d
--- /dev/null
+++ b/packages/styles/src/components/date-picker/date-picker.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const datePickerVariants = tv({
+  slots: {
+    base: "date-picker",
+    popover: "date-picker__popover",
+    trigger: "date-picker__trigger",
+    triggerIndicator: "date-picker__trigger-indicator",
+  },
+});
+
+export type DatePickerVariants = VariantProps<typeof datePickerVariants>;
diff --git a/packages/styles/src/components/date-picker/index.ts b/packages/styles/src/components/date-picker/index.ts
new file mode 100644
index 0000000..69a1641
--- /dev/null
+++ b/packages/styles/src/components/date-picker/index.ts
@@ -0,0 +1 @@
+export * from "./date-picker.styles";
diff --git a/packages/styles/src/components/date-range-picker/date-range-picker.styles.ts b/packages/styles/src/components/date-range-picker/date-range-picker.styles.ts
new file mode 100644
index 0000000..b6b706f
--- /dev/null
+++ b/packages/styles/src/components/date-range-picker/date-range-picker.styles.ts
@@ -0,0 +1,15 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const dateRangePickerVariants = tv({
+  slots: {
+    base: "date-range-picker",
+    popover: "date-range-picker__popover",
+    rangeSeparator: "date-range-picker__range-separator",
+    trigger: "date-range-picker__trigger",
+    triggerIndicator: "date-range-picker__trigger-indicator",
+  },
+});
+
+export type DateRangePickerVariants = VariantProps<typeof dateRangePickerVariants>;
diff --git a/packages/styles/src/components/date-range-picker/index.ts b/packages/styles/src/components/date-range-picker/index.ts
new file mode 100644
index 0000000..f2bbcef
--- /dev/null
+++ b/packages/styles/src/components/date-range-picker/index.ts
@@ -0,0 +1 @@
+export * from "./date-range-picker.styles";
diff --git a/packages/styles/src/components/description/description.styles.ts b/packages/styles/src/components/description/description.styles.ts
new file mode 100644
index 0000000..8abd802
--- /dev/null
+++ b/packages/styles/src/components/description/description.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const descriptionVariants = tv({
+  base: "description",
+});
+
+export type DescriptionVariants = VariantProps<typeof descriptionVariants>;
diff --git a/packages/styles/src/components/description/index.ts b/packages/styles/src/components/description/index.ts
new file mode 100644
index 0000000..de956ac
--- /dev/null
+++ b/packages/styles/src/components/description/index.ts
@@ -0,0 +1 @@
+export * from "./description.styles";
diff --git a/packages/styles/src/components/disclosure-group/disclosure-group.styles.ts b/packages/styles/src/components/disclosure-group/disclosure-group.styles.ts
new file mode 100644
index 0000000..29fa94a
--- /dev/null
+++ b/packages/styles/src/components/disclosure-group/disclosure-group.styles.ts
@@ -0,0 +1,13 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const disclosureGroupVariants = tv({
+  defaultVariants: {},
+  slots: {
+    base: "disclosure-group",
+  },
+  variants: {},
+});
+
+export type DisclosureGroupVariants = VariantProps<typeof disclosureGroupVariants>;
diff --git a/packages/styles/src/components/disclosure-group/index.ts b/packages/styles/src/components/disclosure-group/index.ts
new file mode 100644
index 0000000..06a29a0
--- /dev/null
+++ b/packages/styles/src/components/disclosure-group/index.ts
@@ -0,0 +1 @@
+export * from "./disclosure-group.styles";
diff --git a/packages/styles/src/components/disclosure/disclosure.styles.ts b/packages/styles/src/components/disclosure/disclosure.styles.ts
new file mode 100644
index 0000000..7877d82
--- /dev/null
+++ b/packages/styles/src/components/disclosure/disclosure.styles.ts
@@ -0,0 +1,25 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const disclosureVariants = tv({
+  defaultVariants: {},
+  slots: {
+    base: "disclosure",
+    body: "disclosure__body",
+    bodyInner: "disclosure__body-inner",
+    content: "disclosure__content",
+    heading: "disclosure__heading",
+    indicator: "disclosure__indicator",
+    trigger: "disclosure__trigger",
+  },
+  variants: {},
+});
+
+// Render props that should be excluded from DisclosureVariants (framework-specific)
+type DisclosureRenderPropsKeys = "isExpanded" | "isDisabled" | "state";
+
+export type DisclosureVariants = Omit<
+  VariantProps<typeof disclosureVariants>,
+  DisclosureRenderPropsKeys
+>;
diff --git a/packages/styles/src/components/disclosure/index.ts b/packages/styles/src/components/disclosure/index.ts
new file mode 100644
index 0000000..6974373
--- /dev/null
+++ b/packages/styles/src/components/disclosure/index.ts
@@ -0,0 +1 @@
+export * from "./disclosure.styles";
diff --git a/packages/styles/src/components/drawer/drawer.styles.ts b/packages/styles/src/components/drawer/drawer.styles.ts
new file mode 100644
index 0000000..77da703
--- /dev/null
+++ b/packages/styles/src/components/drawer/drawer.styles.ts
@@ -0,0 +1,55 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const drawerVariants = tv({
+  defaultVariants: {
+    placement: "bottom",
+    variant: "opaque",
+  },
+  slots: {
+    backdrop: "drawer__backdrop",
+    body: "drawer__body",
+    closeTrigger: "drawer__close-trigger",
+    content: "drawer__content",
+    dialog: "drawer__dialog",
+    footer: "drawer__footer",
+    handle: "drawer__handle",
+    header: "drawer__header",
+    heading: "drawer__heading",
+    trigger: "drawer__trigger",
+  },
+  variants: {
+    placement: {
+      bottom: {
+        content: "drawer__content--bottom",
+        dialog: "drawer__dialog--bottom",
+      },
+      left: {
+        content: "drawer__content--left",
+        dialog: "drawer__dialog--left",
+      },
+      right: {
+        content: "drawer__content--right",
+        dialog: "drawer__dialog--right",
+      },
+      top: {
+        content: "drawer__content--top",
+        dialog: "drawer__dialog--top",
+      },
+    },
+    variant: {
+      blur: {
+        backdrop: "drawer__backdrop--blur",
+      },
+      opaque: {
+        backdrop: "drawer__backdrop--opaque",
+      },
+      transparent: {
+        backdrop: "drawer__backdrop--transparent",
+      },
+    },
+  },
+});
+
+export type DrawerVariants = VariantProps<typeof drawerVariants>;
diff --git a/packages/styles/src/components/drawer/index.ts b/packages/styles/src/components/drawer/index.ts
new file mode 100644
index 0000000..e8d7865
--- /dev/null
+++ b/packages/styles/src/components/drawer/index.ts
@@ -0,0 +1 @@
+export * from "./drawer.styles";
diff --git a/packages/styles/src/components/dropdown/dropdown.styles.ts b/packages/styles/src/components/dropdown/dropdown.styles.ts
new file mode 100644
index 0000000..a6c1e98
--- /dev/null
+++ b/packages/styles/src/components/dropdown/dropdown.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const dropdownVariants = tv({
+  slots: {
+    menu: "dropdown__menu",
+    popover: "dropdown__popover",
+    root: "dropdown",
+    trigger: "dropdown__trigger",
+  },
+});
+
+export type DropdownVariants = VariantProps<typeof dropdownVariants>;
diff --git a/packages/styles/src/components/dropdown/index.ts b/packages/styles/src/components/dropdown/index.ts
new file mode 100644
index 0000000..98b013a
--- /dev/null
+++ b/packages/styles/src/components/dropdown/index.ts
@@ -0,0 +1 @@
+export * from "./dropdown.styles";
diff --git a/packages/styles/src/components/empty-state/empty-state.styles.ts b/packages/styles/src/components/empty-state/empty-state.styles.ts
new file mode 100644
index 0000000..db98ba5
--- /dev/null
+++ b/packages/styles/src/components/empty-state/empty-state.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const emptyStateVariants = tv({
+  base: "empty-state",
+});
+
+export type EmptyStateVariants = VariantProps<typeof emptyStateVariants>;
diff --git a/packages/styles/src/components/empty-state/index.ts b/packages/styles/src/components/empty-state/index.ts
new file mode 100644
index 0000000..33ef84e
--- /dev/null
+++ b/packages/styles/src/components/empty-state/index.ts
@@ -0,0 +1 @@
+export * from "./empty-state.styles";
diff --git a/packages/styles/src/components/error-message/error-message.styles.ts b/packages/styles/src/components/error-message/error-message.styles.ts
new file mode 100644
index 0000000..eec57c1
--- /dev/null
+++ b/packages/styles/src/components/error-message/error-message.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const errorMessageVariants = tv({
+  base: "error-message",
+});
+
+export type ErrorMessageVariants = VariantProps<typeof errorMessageVariants>;
diff --git a/packages/styles/src/components/error-message/index.ts b/packages/styles/src/components/error-message/index.ts
new file mode 100644
index 0000000..a0e850f
--- /dev/null
+++ b/packages/styles/src/components/error-message/index.ts
@@ -0,0 +1 @@
+export * from "./error-message.styles";
diff --git a/packages/styles/src/components/field-error/field-error.styles.ts b/packages/styles/src/components/field-error/field-error.styles.ts
new file mode 100644
index 0000000..0c87d3c
--- /dev/null
+++ b/packages/styles/src/components/field-error/field-error.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const fieldErrorVariants = tv({
+  base: "field-error",
+});
+
+export type FieldErrorVariants = VariantProps<typeof fieldErrorVariants>;
diff --git a/packages/styles/src/components/field-error/index.ts b/packages/styles/src/components/field-error/index.ts
new file mode 100644
index 0000000..5d45e39
--- /dev/null
+++ b/packages/styles/src/components/field-error/index.ts
@@ -0,0 +1 @@
+export * from "./field-error.styles";
diff --git a/packages/styles/src/components/fieldset/fieldset.styles.ts b/packages/styles/src/components/fieldset/fieldset.styles.ts
new file mode 100644
index 0000000..8accd5e
--- /dev/null
+++ b/packages/styles/src/components/fieldset/fieldset.styles.ts
@@ -0,0 +1,15 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const fieldsetVariants = tv({
+  slots: {
+    actions: "fieldset__actions",
+    base: "fieldset",
+    description: "fieldset__description",
+    fieldGroup: "fieldset__field_group",
+    legend: "fieldset__legend",
+  },
+});
+
+export type FieldsetVariants = VariantProps<typeof fieldsetVariants>;
diff --git a/packages/styles/src/components/fieldset/index.ts b/packages/styles/src/components/fieldset/index.ts
new file mode 100644
index 0000000..d7096ad
--- /dev/null
+++ b/packages/styles/src/components/fieldset/index.ts
@@ -0,0 +1 @@
+export * from "./fieldset.styles";
diff --git a/packages/styles/src/components/header/header.styles.ts b/packages/styles/src/components/header/header.styles.ts
new file mode 100644
index 0000000..6bbdb4b
--- /dev/null
+++ b/packages/styles/src/components/header/header.styles.ts
@@ -0,0 +1,5 @@
+import {tv} from "tailwind-variants";
+
+export const headerVariants = tv({
+  base: "header",
+});
diff --git a/packages/styles/src/components/header/index.ts b/packages/styles/src/components/header/index.ts
new file mode 100644
index 0000000..a731d57
--- /dev/null
+++ b/packages/styles/src/components/header/index.ts
@@ -0,0 +1 @@
+export * from "./header.styles";
diff --git a/packages/styles/src/components/index.ts b/packages/styles/src/components/index.ts
new file mode 100644
index 0000000..281a810
--- /dev/null
+++ b/packages/styles/src/components/index.ts
@@ -0,0 +1,84 @@
+// Component variant exports
+export * from "./accordion";
+export * from "./alert";
+export * from "./alert-dialog";
+export * from "./autocomplete";
+export * from "./avatar";
+export * from "./badge";
+export * from "./breadcrumbs";
+export * from "./button";
+export * from "./button-group";
+export * from "./calendar";
+export * from "./calendar-year-picker";
+export * from "./range-calendar";
+export * from "./card";
+export * from "./checkbox";
+export * from "./checkbox-group";
+export * from "./chip";
+export * from "./color-area";
+export * from "./color-field";
+export * from "./color-input-group";
+export * from "./color-picker";
+export * from "./color-slider";
+export * from "./color-swatch";
+export * from "./close-button";
+export * from "./color-swatch-picker";
+export * from "./combo-box";
+export * from "./date-field";
+export * from "./date-picker";
+export * from "./date-range-picker";
+export * from "./date-input-group";
+export * from "./description";
+export * from "./drawer";
+export * from "./disclosure";
+export * from "./disclosure-group";
+export * from "./dropdown";
+export * from "./empty-state";
+export * from "./error-message";
+export * from "./field-error";
+export * from "./fieldset";
+export * from "./header";
+export * from "./input";
+export * from "./input-group";
+export * from "./input-otp";
+export * from "./kbd";
+export * from "./label";
+export * from "./link";
+export * from "./list-box";
+export * from "./list-box-item";
+export * from "./list-box-section";
+export * from "./menu";
+export * from "./meter";
+export * from "./progress-bar";
+export * from "./progress-circle";
+export * from "./menu-item";
+export * from "./menu-section";
+export * from "./modal";
+export * from "./number-field";
+export * from "./pagination";
+export * from "./popover";
+export * from "./radio";
+export * from "./radio-group";
+export * from "./scroll-shadow";
+export * from "./search-field";
+export * from "./select";
+export * from "./separator";
+export * from "./skeleton";
+export * from "./slider";
+export * from "./spinner";
+export * from "./surface";
+export * from "./switch";
+export * from "./switch-group";
+export * from "./table";
+export * from "./tabs";
+export * from "./tag";
+export * from "./tag-group";
+export * from "./typography";
+export * from "./textfield";
+export * from "./textarea";
+export * from "./time-field";
+export * from "./toast";
+export * from "./toggle-button";
+export * from "./toggle-button-group";
+export * from "./toolbar";
+export * from "./tooltip";
diff --git a/packages/styles/src/components/input-group/index.ts b/packages/styles/src/components/input-group/index.ts
new file mode 100644
index 0000000..6c793d5
--- /dev/null
+++ b/packages/styles/src/components/input-group/index.ts
@@ -0,0 +1 @@
+export * from "./input-group.styles";
diff --git a/packages/styles/src/components/input-group/input-group.styles.ts b/packages/styles/src/components/input-group/input-group.styles.ts
new file mode 100644
index 0000000..a5da0bd
--- /dev/null
+++ b/packages/styles/src/components/input-group/input-group.styles.ts
@@ -0,0 +1,34 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const inputGroupVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "input-group",
+    input: "input-group__input",
+    prefix: "input-group__prefix",
+    suffix: "input-group__suffix",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "input-group--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "input-group--primary",
+      },
+      secondary: {
+        base: "input-group--secondary",
+      },
+    },
+  },
+});
+
+export type InputGroupVariants = VariantProps<typeof inputGroupVariants>;
diff --git a/packages/styles/src/components/input-otp/index.ts b/packages/styles/src/components/input-otp/index.ts
new file mode 100644
index 0000000..b4d20f3
--- /dev/null
+++ b/packages/styles/src/components/input-otp/index.ts
@@ -0,0 +1 @@
+export * from "./input-otp.styles";
diff --git a/packages/styles/src/components/input-otp/input-otp.styles.ts b/packages/styles/src/components/input-otp/input-otp.styles.ts
new file mode 100644
index 0000000..3d9e5c9
--- /dev/null
+++ b/packages/styles/src/components/input-otp/input-otp.styles.ts
@@ -0,0 +1,30 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const inputOTPVariants = tv({
+  defaultVariants: {
+    variant: "primary",
+  },
+  slots: {
+    base: "input-otp",
+    caret: "input-otp__caret",
+    group: "input-otp__group",
+    input: "input-otp__input",
+    separator: "input-otp__separator",
+    slot: "input-otp__slot",
+    slotValue: "input-otp__slot-value",
+  },
+  variants: {
+    variant: {
+      primary: {
+        base: "input-otp--primary",
+      },
+      secondary: {
+        base: "input-otp--secondary",
+      },
+    },
+  },
+});
+
+export type InputOTPVariants = VariantProps<typeof inputOTPVariants>;
diff --git a/packages/styles/src/components/input/index.ts b/packages/styles/src/components/input/index.ts
new file mode 100644
index 0000000..8e552ea
--- /dev/null
+++ b/packages/styles/src/components/input/index.ts
@@ -0,0 +1 @@
+export * from "./input.styles";
diff --git a/packages/styles/src/components/input/input.styles.ts b/packages/styles/src/components/input/input.styles.ts
new file mode 100644
index 0000000..28ce3b9
--- /dev/null
+++ b/packages/styles/src/components/input/input.styles.ts
@@ -0,0 +1,23 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const inputVariants = tv({
+  base: "input",
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "input--full-width",
+    },
+    variant: {
+      primary: "input--primary",
+      secondary: "input--secondary",
+    },
+  },
+});
+
+export type InputVariants = VariantProps<typeof inputVariants>;
diff --git a/packages/styles/src/components/kbd/index.ts b/packages/styles/src/components/kbd/index.ts
new file mode 100644
index 0000000..8aa989e
--- /dev/null
+++ b/packages/styles/src/components/kbd/index.ts
@@ -0,0 +1 @@
+export * from "./kbd.styles";
diff --git a/packages/styles/src/components/kbd/kbd.styles.ts b/packages/styles/src/components/kbd/kbd.styles.ts
new file mode 100644
index 0000000..f2cb3f6
--- /dev/null
+++ b/packages/styles/src/components/kbd/kbd.styles.ts
@@ -0,0 +1,20 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const kbdVariants = tv({
+  defaultVariants: {},
+  slots: {
+    abbr: "kbd__abbr",
+    base: "kbd",
+    content: "kbd__content",
+  },
+  variants: {
+    variant: {
+      default: "kbd--default",
+      light: "kbd--light",
+    },
+  },
+});
+
+export type KbdVariants = VariantProps<typeof kbdVariants>;
diff --git a/packages/styles/src/components/label/index.ts b/packages/styles/src/components/label/index.ts
new file mode 100644
index 0000000..0fef74e
--- /dev/null
+++ b/packages/styles/src/components/label/index.ts
@@ -0,0 +1 @@
+export * from "./label.styles";
diff --git a/packages/styles/src/components/label/label.styles.ts b/packages/styles/src/components/label/label.styles.ts
new file mode 100644
index 0000000..c57bdd8
--- /dev/null
+++ b/packages/styles/src/components/label/label.styles.ts
@@ -0,0 +1,25 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const labelVariants = tv({
+  base: "label",
+  defaultVariants: {
+    isDisabled: false,
+    isInvalid: false,
+    isRequired: false,
+  },
+  variants: {
+    isDisabled: {
+      true: "label--disabled",
+    },
+    isInvalid: {
+      true: "label--invalid",
+    },
+    isRequired: {
+      true: "label--required",
+    },
+  },
+});
+
+export type LabelVariants = VariantProps<typeof labelVariants>;
diff --git a/packages/styles/src/components/link/index.ts b/packages/styles/src/components/link/index.ts
new file mode 100644
index 0000000..ad704d8
--- /dev/null
+++ b/packages/styles/src/components/link/index.ts
@@ -0,0 +1 @@
+export * from "./link.styles";
diff --git a/packages/styles/src/components/link/link.styles.ts b/packages/styles/src/components/link/link.styles.ts
new file mode 100644
index 0000000..81380ab
--- /dev/null
+++ b/packages/styles/src/components/link/link.styles.ts
@@ -0,0 +1,21 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const linkVariants = tv({
+  slots: {
+    base: "link",
+    icon: "link__icon",
+  },
+});
+
+// Render props that should be excluded from LinkVariants (framework-specific)
+type LinkRenderPropsKeys =
+  | "isCurrent"
+  | "isHovered"
+  | "isPressed"
+  | "isFocused"
+  | "isFocusVisible"
+  | "isDisabled";
+
+export type LinkVariants = Omit<VariantProps<typeof linkVariants>, LinkRenderPropsKeys>;
diff --git a/packages/styles/src/components/list-box-item/index.ts b/packages/styles/src/components/list-box-item/index.ts
new file mode 100644
index 0000000..110e10f
--- /dev/null
+++ b/packages/styles/src/components/list-box-item/index.ts
@@ -0,0 +1 @@
+export * from "./list-box-item.styles";
diff --git a/packages/styles/src/components/list-box-item/list-box-item.styles.ts b/packages/styles/src/components/list-box-item/list-box-item.styles.ts
new file mode 100644
index 0000000..f9bafa4
--- /dev/null
+++ b/packages/styles/src/components/list-box-item/list-box-item.styles.ts
@@ -0,0 +1,25 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const listboxItemVariants = tv({
+  defaultVariants: {
+    variant: "default",
+  },
+  slots: {
+    indicator: "list-box-item__indicator",
+    item: "list-box-item",
+  },
+  variants: {
+    variant: {
+      danger: {
+        item: "list-box-item--danger",
+      },
+      default: {
+        item: "list-box-item--default",
+      },
+    },
+  },
+});
+
+export type ListBoxItemVariants = VariantProps<typeof listboxItemVariants>;
diff --git a/packages/styles/src/components/list-box-section/index.ts b/packages/styles/src/components/list-box-section/index.ts
new file mode 100644
index 0000000..e143f1a
--- /dev/null
+++ b/packages/styles/src/components/list-box-section/index.ts
@@ -0,0 +1 @@
+export * from "./list-box-section.styles";
diff --git a/packages/styles/src/components/list-box-section/list-box-section.styles.ts b/packages/styles/src/components/list-box-section/list-box-section.styles.ts
new file mode 100644
index 0000000..1745e94
--- /dev/null
+++ b/packages/styles/src/components/list-box-section/list-box-section.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const listboxSectionVariants = tv({
+  base: "list-box-section",
+});
+
+export type ListBoxSectionVariants = VariantProps<typeof listboxSectionVariants>;
diff --git a/packages/styles/src/components/list-box/index.ts b/packages/styles/src/components/list-box/index.ts
new file mode 100644
index 0000000..35d64a3
--- /dev/null
+++ b/packages/styles/src/components/list-box/index.ts
@@ -0,0 +1 @@
+export * from "./list-box.styles";
diff --git a/packages/styles/src/components/list-box/list-box.styles.ts b/packages/styles/src/components/list-box/list-box.styles.ts
new file mode 100644
index 0000000..d85775b
--- /dev/null
+++ b/packages/styles/src/components/list-box/list-box.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const listboxVariants = tv({
+  base: "list-box",
+  defaultVariants: {
+    variant: "default",
+  },
+  variants: {
+    variant: {
+      danger: "list-box--danger",
+      default: "list-box--default",
+    },
+  },
+});
+
+export type ListBoxVariants = VariantProps<typeof listboxVariants>;
diff --git a/packages/styles/src/components/menu-item/index.ts b/packages/styles/src/components/menu-item/index.ts
new file mode 100644
index 0000000..13e6d7c
--- /dev/null
+++ b/packages/styles/src/components/menu-item/index.ts
@@ -0,0 +1 @@
+export * from "./menu-item.styles";
diff --git a/packages/styles/src/components/menu-item/menu-item.styles.ts b/packages/styles/src/components/menu-item/menu-item.styles.ts
new file mode 100644
index 0000000..a29e86f
--- /dev/null
+++ b/packages/styles/src/components/menu-item/menu-item.styles.ts
@@ -0,0 +1,26 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const menuItemVariants = tv({
+  defaultVariants: {
+    variant: "default",
+  },
+  slots: {
+    indicator: "menu-item__indicator",
+    item: "menu-item",
+    submenuIndicator: "menu-item__indicator menu-item__indicator--submenu",
+  },
+  variants: {
+    variant: {
+      danger: {
+        item: "menu-item--danger",
+      },
+      default: {
+        item: "menu-item--default",
+      },
+    },
+  },
+});
+
+export type MenuItemVariants = VariantProps<typeof menuItemVariants>;
diff --git a/packages/styles/src/components/menu-section/index.ts b/packages/styles/src/components/menu-section/index.ts
new file mode 100644
index 0000000..3190f05
--- /dev/null
+++ b/packages/styles/src/components/menu-section/index.ts
@@ -0,0 +1 @@
+export * from "./menu-section.styles";
diff --git a/packages/styles/src/components/menu-section/menu-section.styles.ts b/packages/styles/src/components/menu-section/menu-section.styles.ts
new file mode 100644
index 0000000..1188452
--- /dev/null
+++ b/packages/styles/src/components/menu-section/menu-section.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const menuSectionVariants = tv({
+  base: "menu-section",
+});
+
+export type MenuSectionVariants = VariantProps<typeof menuSectionVariants>;
diff --git a/packages/styles/src/components/menu/index.ts b/packages/styles/src/components/menu/index.ts
new file mode 100644
index 0000000..382d63c
--- /dev/null
+++ b/packages/styles/src/components/menu/index.ts
@@ -0,0 +1 @@
+export * from "./menu.styles";
diff --git a/packages/styles/src/components/menu/menu.styles.ts b/packages/styles/src/components/menu/menu.styles.ts
new file mode 100644
index 0000000..885c11c
--- /dev/null
+++ b/packages/styles/src/components/menu/menu.styles.ts
@@ -0,0 +1,9 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const menuVariants = tv({
+  base: "menu",
+});
+
+export type MenuVariants = VariantProps<typeof menuVariants>;
diff --git a/packages/styles/src/components/meter/index.ts b/packages/styles/src/components/meter/index.ts
new file mode 100644
index 0000000..2945086
--- /dev/null
+++ b/packages/styles/src/components/meter/index.ts
@@ -0,0 +1 @@
+export * from "./meter.styles";
diff --git a/packages/styles/src/components/meter/meter.styles.ts b/packages/styles/src/components/meter/meter.styles.ts
new file mode 100644
index 0000000..fcc1762
--- /dev/null
+++ b/packages/styles/src/components/meter/meter.styles.ts
@@ -0,0 +1,48 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const meterVariants = tv({
+  defaultVariants: {
+    color: "accent",
+    size: "md",
+  },
+  slots: {
+    base: "meter",
+    fill: "meter__fill",
+    output: "meter__output",
+    track: "meter__track",
+  },
+  variants: {
+    color: {
+      accent: {
+        base: "meter--accent",
+      },
+      danger: {
+        base: "meter--danger",
+      },
+      default: {
+        base: "meter--default",
+      },
+      success: {
+        base: "meter--success",
+      },
+      warning: {
+        base: "meter--warning",
+      },
+    },
+    size: {
+      lg: {
+        base: "meter--lg",
+      },
+      md: {
+        base: "meter--md",
+      },
+      sm: {
+        base: "meter--sm",
+      },
+    },
+  },
+});
+
+export type MeterVariants = VariantProps<typeof meterVariants>;
diff --git a/packages/styles/src/components/modal/index.ts b/packages/styles/src/components/modal/index.ts
new file mode 100644
index 0000000..c37e25c
--- /dev/null
+++ b/packages/styles/src/components/modal/index.ts
@@ -0,0 +1 @@
+export * from "./modal.styles";
diff --git a/packages/styles/src/components/modal/modal.styles.ts b/packages/styles/src/components/modal/modal.styles.ts
new file mode 100644
index 0000000..d68103f
--- /dev/null
+++ b/packages/styles/src/components/modal/modal.styles.ts
@@ -0,0 +1,70 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const modalVariants = tv({
+  defaultVariants: {
+    scroll: "inside",
+    size: "md",
+    variant: "opaque",
+  },
+  slots: {
+    backdrop: "modal__backdrop",
+    body: "modal__body",
+    closeTrigger: "modal__close-trigger",
+    container: "modal__container",
+    dialog: "modal__dialog",
+    footer: "modal__footer",
+    header: "modal__header",
+    heading: "modal__heading",
+    icon: "modal__icon",
+    trigger: "modal__trigger",
+  },
+  variants: {
+    scroll: {
+      inside: {
+        body: "modal__body--scroll-inside",
+        dialog: "modal__dialog--scroll-inside",
+      },
+      outside: {
+        body: "modal__body--scroll-outside",
+        container: "modal__container--scroll-outside",
+        dialog: "modal__dialog--scroll-outside",
+      },
+    },
+    size: {
+      cover: {
+        dialog: "modal__dialog--cover",
+      },
+      full: {
+        container: "modal__container--full",
+        dialog: "modal__dialog--full",
+      },
+      lg: {
+        dialog: "modal__dialog--lg",
+      },
+      md: {
+        dialog: "modal__dialog--md",
+      },
+      sm: {
+        dialog: "modal__dialog--sm",
+      },
+      xs: {
+        dialog: "modal__dialog--xs",
+      },
+    },
+    variant: {
+      blur: {
+        backdrop: "modal__backdrop--blur",
+      },
+      opaque: {
+        backdrop: "modal__backdrop--opaque",
+      },
+      transparent: {
+        backdrop: "modal__backdrop--transparent",
+      },
+    },
+  },
+});
+
+export type ModalVariants = VariantProps<typeof modalVariants>;
diff --git a/packages/styles/src/components/number-field/index.ts b/packages/styles/src/components/number-field/index.ts
new file mode 100644
index 0000000..42679a0
--- /dev/null
+++ b/packages/styles/src/components/number-field/index.ts
@@ -0,0 +1 @@
+export * from "./number-field.styles";
diff --git a/packages/styles/src/components/number-field/number-field.styles.ts b/packages/styles/src/components/number-field/number-field.styles.ts
new file mode 100644
index 0000000..6f7b1fb
--- /dev/null
+++ b/packages/styles/src/components/number-field/number-field.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const numberFieldVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "number-field",
+    decrementButton: "number-field__decrement-button",
+    group: "number-field__group",
+    incrementButton: "number-field__increment-button",
+    input: "number-field__input",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "number-field--full-width",
+        group: "number-field__group--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "number-field--primary",
+      },
+      secondary: {
+        base: "number-field--secondary",
+      },
+    },
+  },
+});
+
+export type NumberFieldVariants = VariantProps<typeof numberFieldVariants>;
diff --git a/packages/styles/src/components/pagination/index.ts b/packages/styles/src/components/pagination/index.ts
new file mode 100644
index 0000000..6ca2037
--- /dev/null
+++ b/packages/styles/src/components/pagination/index.ts
@@ -0,0 +1 @@
+export * from "./pagination.styles";
diff --git a/packages/styles/src/components/pagination/pagination.styles.ts b/packages/styles/src/components/pagination/pagination.styles.ts
new file mode 100644
index 0000000..21b1c0f
--- /dev/null
+++ b/packages/styles/src/components/pagination/pagination.styles.ts
@@ -0,0 +1,32 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const paginationVariants = tv({
+  defaultVariants: {
+    size: "md",
+  },
+  slots: {
+    base: "pagination",
+    content: "pagination__content",
+    ellipsis: "pagination__ellipsis",
+    item: "pagination__item",
+    link: "pagination__link",
+    summary: "pagination__summary",
+  },
+  variants: {
+    size: {
+      lg: {
+        base: "pagination--lg",
+      },
+      md: {
+        base: "pagination--md",
+      },
+      sm: {
+        base: "pagination--sm",
+      },
+    },
+  },
+});
+
+export type PaginationVariants = VariantProps<typeof paginationVariants>;
diff --git a/packages/styles/src/components/popover/index.ts b/packages/styles/src/components/popover/index.ts
new file mode 100644
index 0000000..2c49152
--- /dev/null
+++ b/packages/styles/src/components/popover/index.ts
@@ -0,0 +1 @@
+export * from "./popover.styles";
diff --git a/packages/styles/src/components/popover/popover.styles.ts b/packages/styles/src/components/popover/popover.styles.ts
new file mode 100644
index 0000000..68722b7
--- /dev/null
+++ b/packages/styles/src/components/popover/popover.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const popoverVariants = tv({
+  slots: {
+    base: "popover",
+    dialog: "popover__dialog",
+    heading: "popover__heading",
+    trigger: "popover__trigger",
+  },
+});
+
+export type PopoverVariants = VariantProps<typeof popoverVariants>;
diff --git a/packages/styles/src/components/progress-bar/index.ts b/packages/styles/src/components/progress-bar/index.ts
new file mode 100644
index 0000000..96eb471
--- /dev/null
+++ b/packages/styles/src/components/progress-bar/index.ts
@@ -0,0 +1 @@
+export * from "./progress-bar.styles";
diff --git a/packages/styles/src/components/progress-bar/progress-bar.styles.ts b/packages/styles/src/components/progress-bar/progress-bar.styles.ts
new file mode 100644
index 0000000..367930e
--- /dev/null
+++ b/packages/styles/src/components/progress-bar/progress-bar.styles.ts
@@ -0,0 +1,48 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const progressBarVariants = tv({
+  defaultVariants: {
+    color: "accent",
+    size: "md",
+  },
+  slots: {
+    base: "progress-bar",
+    fill: "progress-bar__fill",
+    output: "progress-bar__output",
+    track: "progress-bar__track",
+  },
+  variants: {
+    color: {
+      accent: {
+        base: "progress-bar--accent",
+      },
+      danger: {
+        base: "progress-bar--danger",
+      },
+      default: {
+        base: "progress-bar--default",
+      },
+      success: {
+        base: "progress-bar--success",
+      },
+      warning: {
+        base: "progress-bar--warning",
+      },
+    },
+    size: {
+      lg: {
+        base: "progress-bar--lg",
+      },
+      md: {
+        base: "progress-bar--md",
+      },
+      sm: {
+        base: "progress-bar--sm",
+      },
+    },
+  },
+});
+
+export type ProgressBarVariants = VariantProps<typeof progressBarVariants>;
diff --git a/packages/styles/src/components/progress-circle/index.ts b/packages/styles/src/components/progress-circle/index.ts
new file mode 100644
index 0000000..77964a4
--- /dev/null
+++ b/packages/styles/src/components/progress-circle/index.ts
@@ -0,0 +1 @@
+export * from "./progress-circle.styles";
diff --git a/packages/styles/src/components/progress-circle/progress-circle.styles.ts b/packages/styles/src/components/progress-circle/progress-circle.styles.ts
new file mode 100644
index 0000000..7d6b989
--- /dev/null
+++ b/packages/styles/src/components/progress-circle/progress-circle.styles.ts
@@ -0,0 +1,48 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const progressCircleVariants = tv({
+  defaultVariants: {
+    color: "accent",
+    size: "md",
+  },
+  slots: {
+    base: "progress-circle",
+    fillCircle: "progress-circle__fill-circle",
+    track: "progress-circle__track",
+    trackCircle: "progress-circle__track-circle",
+  },
+  variants: {
+    color: {
+      accent: {
+        base: "progress-circle--accent",
+      },
+      danger: {
+        base: "progress-circle--danger",
+      },
+      default: {
+        base: "progress-circle--default",
+      },
+      success: {
+        base: "progress-circle--success",
+      },
+      warning: {
+        base: "progress-circle--warning",
+      },
+    },
+    size: {
+      lg: {
+        base: "progress-circle--lg",
+      },
+      md: {
+        base: "progress-circle--md",
+      },
+      sm: {
+        base: "progress-circle--sm",
+      },
+    },
+  },
+});
+
+export type ProgressCircleVariants = VariantProps<typeof progressCircleVariants>;
diff --git a/packages/styles/src/components/radio-group/index.ts b/packages/styles/src/components/radio-group/index.ts
new file mode 100644
index 0000000..8829db5
--- /dev/null
+++ b/packages/styles/src/components/radio-group/index.ts
@@ -0,0 +1 @@
+export * from "./radio-group.styles";
diff --git a/packages/styles/src/components/radio-group/radio-group.styles.ts b/packages/styles/src/components/radio-group/radio-group.styles.ts
new file mode 100644
index 0000000..4d05c0f
--- /dev/null
+++ b/packages/styles/src/components/radio-group/radio-group.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const radioGroupVariants = tv({
+  base: "radio-group",
+  defaultVariants: {
+    variant: "primary",
+  },
+  variants: {
+    variant: {
+      primary: "radio-group--primary",
+      secondary: "radio-group--secondary",
+    },
+  },
+});
+
+export type RadioGroupVariants = VariantProps<typeof radioGroupVariants>;
diff --git a/packages/styles/src/components/radio/index.ts b/packages/styles/src/components/radio/index.ts
new file mode 100644
index 0000000..a40e591
--- /dev/null
+++ b/packages/styles/src/components/radio/index.ts
@@ -0,0 +1 @@
+export * from "./radio.styles";
diff --git a/packages/styles/src/components/radio/radio.styles.ts b/packages/styles/src/components/radio/radio.styles.ts
new file mode 100644
index 0000000..70294c7
--- /dev/null
+++ b/packages/styles/src/components/radio/radio.styles.ts
@@ -0,0 +1,14 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const radioVariants = tv({
+  slots: {
+    base: "radio",
+    content: "radio__content",
+    control: "radio__control",
+    indicator: "radio__indicator",
+  },
+});
+
+export type RadioVariants = VariantProps<typeof radioVariants>;
diff --git a/packages/styles/src/components/range-calendar/index.ts b/packages/styles/src/components/range-calendar/index.ts
new file mode 100644
index 0000000..78e7d9b
--- /dev/null
+++ b/packages/styles/src/components/range-calendar/index.ts
@@ -0,0 +1 @@
+export * from "./range-calendar.styles";
diff --git a/packages/styles/src/components/range-calendar/range-calendar.styles.ts b/packages/styles/src/components/range-calendar/range-calendar.styles.ts
new file mode 100644
index 0000000..93ef0b1
--- /dev/null
+++ b/packages/styles/src/components/range-calendar/range-calendar.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const rangeCalendarVariants = tv({
+  defaultVariants: {},
+  slots: {
+    /** Root range calendar container */
+    base: "range-calendar",
+    /** Calendar cell (td) */
+    cell: "range-calendar__cell",
+    /** Cell indicator (small dot at bottom of cell) */
+    cellIndicator: "range-calendar__cell-indicator",
+    /** Calendar grid (table) */
+    grid: "range-calendar__grid",
+    /** Grid body (tbody) */
+    gridBody: "range-calendar__grid-body",
+    /** Grid header (thead) */
+    gridHeader: "range-calendar__grid-header",
+    /** Grid row (tr) */
+    gridRow: "range-calendar__grid-row",
+    /** Calendar header containing heading and navigation */
+    header: "range-calendar__header",
+    /** Header cell (th - day names) */
+    headerCell: "range-calendar__header-cell",
+    /** Month/year heading text */
+    heading: "range-calendar__heading",
+    /** Previous/Next navigation button */
+    navButton: "range-calendar__nav-button",
+    /** Navigation button icon */
+    navButtonIcon: "range-calendar__nav-button-icon",
+  },
+  variants: {},
+});
+
+export type RangeCalendarVariants = VariantProps<typeof rangeCalendarVariants>;
diff --git a/packages/styles/src/components/scroll-shadow/index.ts b/packages/styles/src/components/scroll-shadow/index.ts
new file mode 100644
index 0000000..c935291
--- /dev/null
+++ b/packages/styles/src/components/scroll-shadow/index.ts
@@ -0,0 +1 @@
+export * from "./scroll-shadow.styles";
diff --git a/packages/styles/src/components/scroll-shadow/scroll-shadow.styles.ts b/packages/styles/src/components/scroll-shadow/scroll-shadow.styles.ts
new file mode 100644
index 0000000..a0c0699
--- /dev/null
+++ b/packages/styles/src/components/scroll-shadow/scroll-shadow.styles.ts
@@ -0,0 +1,37 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const scrollShadowVariants = tv({
+  defaultVariants: {
+    hideScrollBar: false,
+    orientation: "vertical",
+    variant: "fade",
+  },
+  slots: {
+    base: "scroll-shadow",
+  },
+  variants: {
+    hideScrollBar: {
+      false: {},
+      true: {
+        base: "scroll-shadow--hide-scrollbar",
+      },
+    },
+    orientation: {
+      horizontal: {
+        base: "scroll-shadow--horizontal",
+      },
+      vertical: {
+        base: "scroll-shadow--vertical",
+      },
+    },
+    variant: {
+      fade: {
+        base: "scroll-shadow--fade",
+      },
+    },
+  },
+});
+
+export type ScrollShadowVariants = VariantProps<typeof scrollShadowVariants>;
diff --git a/packages/styles/src/components/search-field/index.ts b/packages/styles/src/components/search-field/index.ts
new file mode 100644
index 0000000..989a895
--- /dev/null
+++ b/packages/styles/src/components/search-field/index.ts
@@ -0,0 +1 @@
+export * from "./search-field.styles";
diff --git a/packages/styles/src/components/search-field/search-field.styles.ts b/packages/styles/src/components/search-field/search-field.styles.ts
new file mode 100644
index 0000000..2884200
--- /dev/null
+++ b/packages/styles/src/components/search-field/search-field.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const searchFieldVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "search-field",
+    clearButton: "search-field__clear-button",
+    group: "search-field__group",
+    input: "search-field__input",
+    searchIcon: "search-field__search-icon",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "search-field--full-width",
+        group: "search-field__group--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "search-field--primary",
+      },
+      secondary: {
+        base: "search-field--secondary",
+      },
+    },
+  },
+});
+
+export type SearchFieldVariants = VariantProps<typeof searchFieldVariants>;
diff --git a/packages/styles/src/components/select/index.ts b/packages/styles/src/components/select/index.ts
new file mode 100644
index 0000000..122788c
--- /dev/null
+++ b/packages/styles/src/components/select/index.ts
@@ -0,0 +1 @@
+export * from "./select.styles";
diff --git a/packages/styles/src/components/select/select.styles.ts b/packages/styles/src/components/select/select.styles.ts
new file mode 100644
index 0000000..3195153
--- /dev/null
+++ b/packages/styles/src/components/select/select.styles.ts
@@ -0,0 +1,36 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const selectVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  slots: {
+    base: "select",
+    indicator: "select__indicator",
+    popover: "select__popover",
+    trigger: "select__trigger",
+    value: "select__value",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "select--full-width",
+        trigger: "select__trigger--full-width",
+      },
+    },
+    variant: {
+      primary: {
+        base: "select--primary",
+      },
+      secondary: {
+        base: "select--secondary",
+      },
+    },
+  },
+});
+
+export type SelectVariants = VariantProps<typeof selectVariants>;
diff --git a/packages/styles/src/components/separator/index.ts b/packages/styles/src/components/separator/index.ts
new file mode 100644
index 0000000..bed8299
--- /dev/null
+++ b/packages/styles/src/components/separator/index.ts
@@ -0,0 +1 @@
+export * from "./separator.styles";
diff --git a/packages/styles/src/components/separator/separator.styles.ts b/packages/styles/src/components/separator/separator.styles.ts
new file mode 100644
index 0000000..5380395
--- /dev/null
+++ b/packages/styles/src/components/separator/separator.styles.ts
@@ -0,0 +1,25 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+const separatorVariants = tv({
+  base: "separator",
+  defaultVariants: {
+    orientation: "horizontal",
+    variant: "default",
+  },
+  variants: {
+    orientation: {
+      horizontal: "separator--horizontal",
+      vertical: "separator--vertical",
+    },
+    variant: {
+      default: "separator--default",
+      secondary: "separator--secondary",
+      tertiary: "separator--tertiary",
+    },
+  },
+});
+
+export {separatorVariants};
+export type SeparatorVariants = VariantProps<typeof separatorVariants>;
diff --git a/packages/styles/src/components/skeleton/index.ts b/packages/styles/src/components/skeleton/index.ts
new file mode 100644
index 0000000..1166a90
--- /dev/null
+++ b/packages/styles/src/components/skeleton/index.ts
@@ -0,0 +1 @@
+export * from "./skeleton.styles";
diff --git a/packages/styles/src/components/skeleton/skeleton.styles.ts b/packages/styles/src/components/skeleton/skeleton.styles.ts
new file mode 100644
index 0000000..218ca18
--- /dev/null
+++ b/packages/styles/src/components/skeleton/skeleton.styles.ts
@@ -0,0 +1,21 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const skeletonVariants = tv({
+  defaultVariants: {
+    animationType: "shimmer",
+  },
+  slots: {
+    base: "skeleton",
+  },
+  variants: {
+    animationType: {
+      none: "skeleton--none",
+      pulse: "skeleton--pulse",
+      shimmer: "skeleton--shimmer",
+    },
+  },
+});
+
+export type SkeletonVariants = VariantProps<typeof skeletonVariants>;
diff --git a/packages/styles/src/components/slider/index.ts b/packages/styles/src/components/slider/index.ts
new file mode 100644
index 0000000..12fb1f5
--- /dev/null
+++ b/packages/styles/src/components/slider/index.ts
@@ -0,0 +1 @@
+export * from "./slider.styles";
diff --git a/packages/styles/src/components/slider/slider.styles.ts b/packages/styles/src/components/slider/slider.styles.ts
new file mode 100644
index 0000000..06a8693
--- /dev/null
+++ b/packages/styles/src/components/slider/slider.styles.ts
@@ -0,0 +1,16 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const sliderVariants = tv({
+  slots: {
+    base: "slider",
+    fill: "slider__fill",
+    marks: "slider__marks",
+    output: "slider__output",
+    thumb: "slider__thumb",
+    track: "slider__track",
+  },
+});
+
+export type SliderVariants = VariantProps<typeof sliderVariants>;
diff --git a/packages/styles/src/components/spinner/index.ts b/packages/styles/src/components/spinner/index.ts
new file mode 100644
index 0000000..644472c
--- /dev/null
+++ b/packages/styles/src/components/spinner/index.ts
@@ -0,0 +1 @@
+export * from "./spinner.styles";
diff --git a/packages/styles/src/components/spinner/spinner.styles.ts b/packages/styles/src/components/spinner/spinner.styles.ts
new file mode 100644
index 0000000..795eb70
--- /dev/null
+++ b/packages/styles/src/components/spinner/spinner.styles.ts
@@ -0,0 +1,28 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const spinnerVariants = tv({
+  base: "spinner",
+  defaultVariants: {
+    color: "accent",
+    size: "md",
+  },
+  variants: {
+    color: {
+      accent: "spinner--accent",
+      current: "spinner--current",
+      danger: "spinner--danger",
+      success: "spinner--success",
+      warning: "spinner--warning",
+    },
+    size: {
+      lg: "spinner--lg",
+      md: "spinner--md",
+      sm: "spinner--sm",
+      xl: "spinner--xl",
+    },
+  },
+});
+
+export type SpinnerVariants = VariantProps<typeof spinnerVariants>;
diff --git a/packages/styles/src/components/surface/index.ts b/packages/styles/src/components/surface/index.ts
new file mode 100644
index 0000000..22f567e
--- /dev/null
+++ b/packages/styles/src/components/surface/index.ts
@@ -0,0 +1 @@
+export * from "./surface.styles";
diff --git a/packages/styles/src/components/surface/surface.styles.ts b/packages/styles/src/components/surface/surface.styles.ts
new file mode 100644
index 0000000..15ac0e4
--- /dev/null
+++ b/packages/styles/src/components/surface/surface.styles.ts
@@ -0,0 +1,20 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const surfaceVariants = tv({
+  base: "surface",
+  defaultVariants: {
+    variant: "default",
+  },
+  variants: {
+    variant: {
+      default: "surface--default",
+      secondary: "surface--secondary",
+      tertiary: "surface--tertiary",
+      transparent: "surface--transparent",
+    },
+  },
+});
+
+export type SurfaceVariants = VariantProps<typeof surfaceVariants>;
diff --git a/packages/styles/src/components/switch-group/index.ts b/packages/styles/src/components/switch-group/index.ts
new file mode 100644
index 0000000..6a9bf7b
--- /dev/null
+++ b/packages/styles/src/components/switch-group/index.ts
@@ -0,0 +1 @@
+export * from "./switch-group.styles";
diff --git a/packages/styles/src/components/switch-group/switch-group.styles.ts b/packages/styles/src/components/switch-group/switch-group.styles.ts
new file mode 100644
index 0000000..43139f4
--- /dev/null
+++ b/packages/styles/src/components/switch-group/switch-group.styles.ts
@@ -0,0 +1,25 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const switchGroupVariants = tv({
+  defaultVariants: {
+    orientation: "vertical",
+  },
+  slots: {
+    base: "switch-group",
+    items: "switch-group__items",
+  },
+  variants: {
+    orientation: {
+      horizontal: {
+        base: "switch-group--horizontal",
+      },
+      vertical: {
+        base: "switch-group--vertical",
+      },
+    },
+  },
+});
+
+export type SwitchGroupVariants = VariantProps<typeof switchGroupVariants>;
diff --git a/packages/styles/src/components/switch/index.ts b/packages/styles/src/components/switch/index.ts
new file mode 100644
index 0000000..2eb58ef
--- /dev/null
+++ b/packages/styles/src/components/switch/index.ts
@@ -0,0 +1 @@
+export * from "./switch.styles";
diff --git a/packages/styles/src/components/switch/switch.styles.ts b/packages/styles/src/components/switch/switch.styles.ts
new file mode 100644
index 0000000..7210163
--- /dev/null
+++ b/packages/styles/src/components/switch/switch.styles.ts
@@ -0,0 +1,31 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const switchVariants = tv({
+  defaultVariants: {
+    size: "md",
+  },
+  slots: {
+    base: "switch",
+    content: "switch__content",
+    control: "switch__control",
+    icon: "switch__icon",
+    thumb: "switch__thumb",
+  },
+  variants: {
+    size: {
+      lg: {
+        base: "switch--lg",
+      },
+      md: {
+        base: "switch--md",
+      },
+      sm: {
+        base: "switch--sm",
+      },
+    },
+  },
+});
+
+export type SwitchVariants = VariantProps<typeof switchVariants>;
diff --git a/packages/styles/src/components/table/index.ts b/packages/styles/src/components/table/index.ts
new file mode 100644
index 0000000..987ef4f
--- /dev/null
+++ b/packages/styles/src/components/table/index.ts
@@ -0,0 +1 @@
+export * from "./table.styles";
diff --git a/packages/styles/src/components/table/table.styles.ts b/packages/styles/src/components/table/table.styles.ts
new file mode 100644
index 0000000..fecc510
--- /dev/null
+++ b/packages/styles/src/components/table/table.styles.ts
@@ -0,0 +1,49 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const tableVariants = tv({
+  defaultVariants: {
+    variant: "primary",
+  },
+  slots: {
+    base: "table-root",
+    body: "table__body",
+    cell: "table__cell",
+    column: "table__column",
+    columnResizer: "table__column-resizer",
+    content: "table__content",
+    footer: "table__footer",
+    header: "table__header",
+    loadMore: "table__load-more",
+    loadMoreContent: "table__load-more-content",
+    resizableContainer: "table__resizable-container",
+    row: "table__row",
+    scrollContainer: "table__scroll-container",
+    sortableColumnHeader: "table__sortable-column-header",
+    sortableColumnIndicator: "table__sortable-column-indicator",
+  },
+  variants: {
+    variant: {
+      primary: {
+        base: "table-root--primary",
+      },
+      secondary: {
+        base: "table-root--secondary",
+      },
+    },
+  },
+});
+
+// Exclude React Aria render prop keys from the variant types
+type TableRenderPropsKeys =
+  | "isHovered"
+  | "isFocused"
+  | "isFocusVisible"
+  | "isSelected"
+  | "isDisabled"
+  | "isDragging"
+  | "isDropTarget"
+  | "state";
+
+export type TableVariants = Omit<VariantProps<typeof tableVariants>, TableRenderPropsKeys>;
diff --git a/packages/styles/src/components/tabs/index.ts b/packages/styles/src/components/tabs/index.ts
new file mode 100644
index 0000000..8de32b3
--- /dev/null
+++ b/packages/styles/src/components/tabs/index.ts
@@ -0,0 +1 @@
+export * from "./tabs.styles";
diff --git a/packages/styles/src/components/tabs/tabs.styles.ts b/packages/styles/src/components/tabs/tabs.styles.ts
new file mode 100644
index 0000000..1865034
--- /dev/null
+++ b/packages/styles/src/components/tabs/tabs.styles.ts
@@ -0,0 +1,34 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const tabsVariants = tv({
+  defaultVariants: {
+    variant: "primary",
+  },
+  slots: {
+    base: "tabs",
+    scrollNext: "tabs__list-container__scroll-next",
+    scrollPrev: "tabs__list-container__scroll-prev",
+    scroller: "tabs__list-container__scroller",
+    separator: "tabs__separator",
+    tab: "tabs__tab",
+    tabIndicator: "tabs__indicator",
+    tabList: "tabs__list",
+    tabListContainer: "tabs__list-container",
+    tabPanel: "tabs__panel",
+  },
+  variants: {
+    variant: {
+      primary: {},
+      secondary: {
+        base: "tabs--secondary",
+      },
+    },
+  },
+});
+
+// Render props that should be excluded from TabsVariants (framework-specific)
+type TabsRenderPropsKeys = "selectedKey";
+
+export type TabsVariants = Omit<VariantProps<typeof tabsVariants>, TabsRenderPropsKeys>;
diff --git a/packages/styles/src/components/tag-group/index.ts b/packages/styles/src/components/tag-group/index.ts
new file mode 100644
index 0000000..e7b2934
--- /dev/null
+++ b/packages/styles/src/components/tag-group/index.ts
@@ -0,0 +1 @@
+export * from "./tag-group.styles";
diff --git a/packages/styles/src/components/tag-group/tag-group.styles.ts b/packages/styles/src/components/tag-group/tag-group.styles.ts
new file mode 100644
index 0000000..e98906f
--- /dev/null
+++ b/packages/styles/src/components/tag-group/tag-group.styles.ts
@@ -0,0 +1,12 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const tagGroupVariants = tv({
+  slots: {
+    base: "tag-group",
+    list: "tag-group__list",
+  },
+});
+
+export type TagGroupVariants = VariantProps<typeof tagGroupVariants>;
diff --git a/packages/styles/src/components/tag/index.ts b/packages/styles/src/components/tag/index.ts
new file mode 100644
index 0000000..c11e5fd
--- /dev/null
+++ b/packages/styles/src/components/tag/index.ts
@@ -0,0 +1 @@
+export * from "./tag.styles";
diff --git a/packages/styles/src/components/tag/tag.styles.ts b/packages/styles/src/components/tag/tag.styles.ts
new file mode 100644
index 0000000..7153a14
--- /dev/null
+++ b/packages/styles/src/components/tag/tag.styles.ts
@@ -0,0 +1,37 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const tagVariants = tv({
+  defaultVariants: {
+    size: "md",
+    variant: "default",
+  },
+  slots: {
+    base: "tag",
+    removeButton: "tag__remove-button",
+  },
+  variants: {
+    size: {
+      lg: {
+        base: "tag--lg",
+      },
+      md: {
+        base: "tag--md",
+      },
+      sm: {
+        base: "tag--sm",
+      },
+    },
+    variant: {
+      default: {
+        base: "tag--default",
+      },
+      surface: {
+        base: "tag--surface",
+      },
+    },
+  },
+});
+
+export type TagVariants = VariantProps<typeof tagVariants>;
diff --git a/packages/styles/src/components/textarea/index.ts b/packages/styles/src/components/textarea/index.ts
new file mode 100644
index 0000000..6843ca9
--- /dev/null
+++ b/packages/styles/src/components/textarea/index.ts
@@ -0,0 +1 @@
+export * from "./textarea.styles";
diff --git a/packages/styles/src/components/textarea/textarea.styles.ts b/packages/styles/src/components/textarea/textarea.styles.ts
new file mode 100644
index 0000000..bad1792
--- /dev/null
+++ b/packages/styles/src/components/textarea/textarea.styles.ts
@@ -0,0 +1,23 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const textAreaVariants = tv({
+  base: "textarea",
+  defaultVariants: {
+    fullWidth: false,
+    variant: "primary",
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "textarea--full-width",
+    },
+    variant: {
+      primary: "textarea--primary",
+      secondary: "textarea--secondary",
+    },
+  },
+});
+
+export type TextAreaVariants = VariantProps<typeof textAreaVariants>;
diff --git a/packages/styles/src/components/textfield/index.ts b/packages/styles/src/components/textfield/index.ts
new file mode 100644
index 0000000..4a5a8dc
--- /dev/null
+++ b/packages/styles/src/components/textfield/index.ts
@@ -0,0 +1 @@
+export * from "./textfield.styles";
diff --git a/packages/styles/src/components/textfield/textfield.styles.ts b/packages/styles/src/components/textfield/textfield.styles.ts
new file mode 100644
index 0000000..bd325ba
--- /dev/null
+++ b/packages/styles/src/components/textfield/textfield.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const textFieldVariants = tv({
+  base: "textfield",
+  defaultVariants: {
+    fullWidth: false,
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "textfield--full-width",
+    },
+  },
+});
+
+export type TextFieldVariants = VariantProps<typeof textFieldVariants>;
diff --git a/packages/styles/src/components/time-field/index.ts b/packages/styles/src/components/time-field/index.ts
new file mode 100644
index 0000000..339256b
--- /dev/null
+++ b/packages/styles/src/components/time-field/index.ts
@@ -0,0 +1 @@
+export * from "./time-field.styles";
diff --git a/packages/styles/src/components/time-field/time-field.styles.ts b/packages/styles/src/components/time-field/time-field.styles.ts
new file mode 100644
index 0000000..4eeafb6
--- /dev/null
+++ b/packages/styles/src/components/time-field/time-field.styles.ts
@@ -0,0 +1,18 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const timeFieldVariants = tv({
+  base: "time-field",
+  defaultVariants: {
+    fullWidth: false,
+  },
+  variants: {
+    fullWidth: {
+      false: "",
+      true: "time-field--full-width",
+    },
+  },
+});
+
+export type TimeFieldVariants = VariantProps<typeof timeFieldVariants>;
diff --git a/packages/styles/src/components/toast/index.ts b/packages/styles/src/components/toast/index.ts
new file mode 100644
index 0000000..a125ffe
--- /dev/null
+++ b/packages/styles/src/components/toast/index.ts
@@ -0,0 +1 @@
+export * from "./toast.styles";
diff --git a/packages/styles/src/components/toast/toast.styles.ts b/packages/styles/src/components/toast/toast.styles.ts
new file mode 100644
index 0000000..a839023
--- /dev/null
+++ b/packages/styles/src/components/toast/toast.styles.ts
@@ -0,0 +1,67 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const toastVariants = tv({
+  defaultVariants: {
+    placement: "bottom",
+    variant: "default",
+  },
+  slots: {
+    action: "toast__action",
+    close: "toast__close-button",
+    content: "toast__content",
+    description: "toast__description",
+    indicator: "toast__indicator",
+    region: "toast-region",
+    title: "toast__title",
+    toast: "toast",
+  },
+  variants: {
+    placement: {
+      bottom: {
+        region: "toast-region--bottom",
+        toast: "toast--bottom",
+      },
+      "bottom end": {
+        region: "toast-region--bottom-end",
+        toast: "toast--bottom-end",
+      },
+      "bottom start": {
+        region: "toast-region--bottom-start",
+        toast: "toast--bottom-start",
+      },
+      top: {
+        region: "toast-region--top",
+        toast: "toast--top",
+      },
+      "top end": {
+        region: "toast-region--top-end",
+        toast: "toast--top-end",
+      },
+      "top start": {
+        region: "toast-region--top-start",
+        toast: "toast--top-start",
+      },
+    },
+    variant: {
+      accent: {
+        toast: "toast--accent",
+      },
+      danger: {
+        toast: "toast--danger",
+      },
+      default: {
+        toast: "toast--default",
+      },
+      success: {
+        toast: "toast--success",
+      },
+      warning: {
+        toast: "toast--warning",
+      },
+    },
+  },
+});
+
+export type ToastVariants = VariantProps<typeof toastVariants>;
diff --git a/packages/styles/src/components/toggle-button-group/index.ts b/packages/styles/src/components/toggle-button-group/index.ts
new file mode 100644
index 0000000..4f5d728
--- /dev/null
+++ b/packages/styles/src/components/toggle-button-group/index.ts
@@ -0,0 +1 @@
+export * from "./toggle-button-group.styles";
diff --git a/packages/styles/src/components/toggle-button-group/toggle-button-group.styles.ts b/packages/styles/src/components/toggle-button-group/toggle-button-group.styles.ts
new file mode 100644
index 0000000..8b6f3d9
--- /dev/null
+++ b/packages/styles/src/components/toggle-button-group/toggle-button-group.styles.ts
@@ -0,0 +1,39 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const toggleButtonGroupVariants = tv({
+  defaultVariants: {
+    fullWidth: false,
+    isDetached: false,
+    orientation: "horizontal",
+  },
+  slots: {
+    base: "toggle-button-group",
+    separator: "toggle-button-group__separator",
+  },
+  variants: {
+    fullWidth: {
+      false: {},
+      true: {
+        base: "toggle-button-group--full-width",
+      },
+    },
+    isDetached: {
+      false: {},
+      true: {
+        base: "toggle-button-group--detached",
+      },
+    },
+    orientation: {
+      horizontal: {
+        base: "toggle-button-group--horizontal",
+      },
+      vertical: {
+        base: "toggle-button-group--vertical",
+      },
+    },
+  },
+});
+
+export type ToggleButtonGroupVariants = VariantProps<typeof toggleButtonGroupVariants>;
diff --git a/packages/styles/src/components/toggle-button/index.ts b/packages/styles/src/components/toggle-button/index.ts
new file mode 100644
index 0000000..93cc8ed
--- /dev/null
+++ b/packages/styles/src/components/toggle-button/index.ts
@@ -0,0 +1 @@
+export * from "./toggle-button.styles";
diff --git a/packages/styles/src/components/toggle-button/toggle-button.styles.ts b/packages/styles/src/components/toggle-button/toggle-button.styles.ts
new file mode 100644
index 0000000..f9c1b33
--- /dev/null
+++ b/packages/styles/src/components/toggle-button/toggle-button.styles.ts
@@ -0,0 +1,28 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const toggleButtonVariants = tv({
+  base: "toggle-button",
+  defaultVariants: {
+    isIconOnly: false,
+    size: "md",
+    variant: "default",
+  },
+  variants: {
+    isIconOnly: {
+      true: "toggle-button--icon-only",
+    },
+    size: {
+      lg: "toggle-button--lg",
+      md: "toggle-button--md",
+      sm: "toggle-button--sm",
+    },
+    variant: {
+      default: "toggle-button--default",
+      ghost: "toggle-button--ghost",
+    },
+  },
+});
+
+export type ToggleButtonVariants = VariantProps<typeof toggleButtonVariants>;
diff --git a/packages/styles/src/components/toolbar/index.ts b/packages/styles/src/components/toolbar/index.ts
new file mode 100644
index 0000000..1ba200c
--- /dev/null
+++ b/packages/styles/src/components/toolbar/index.ts
@@ -0,0 +1 @@
+export * from "./toolbar.styles";
diff --git a/packages/styles/src/components/toolbar/toolbar.styles.ts b/packages/styles/src/components/toolbar/toolbar.styles.ts
new file mode 100644
index 0000000..5f9e460
--- /dev/null
+++ b/packages/styles/src/components/toolbar/toolbar.styles.ts
@@ -0,0 +1,23 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+const toolbarVariants = tv({
+  base: "toolbar",
+  defaultVariants: {
+    isAttached: false,
+    orientation: "horizontal",
+  },
+  variants: {
+    isAttached: {
+      true: "toolbar--attached",
+    },
+    orientation: {
+      horizontal: "toolbar--horizontal",
+      vertical: "toolbar--vertical",
+    },
+  },
+});
+
+export {toolbarVariants};
+export type ToolbarVariants = VariantProps<typeof toolbarVariants>;
diff --git a/packages/styles/src/components/tooltip/index.ts b/packages/styles/src/components/tooltip/index.ts
new file mode 100644
index 0000000..cd580dd
--- /dev/null
+++ b/packages/styles/src/components/tooltip/index.ts
@@ -0,0 +1 @@
+export * from "./tooltip.styles";
diff --git a/packages/styles/src/components/tooltip/tooltip.styles.ts b/packages/styles/src/components/tooltip/tooltip.styles.ts
new file mode 100644
index 0000000..0e63816
--- /dev/null
+++ b/packages/styles/src/components/tooltip/tooltip.styles.ts
@@ -0,0 +1,12 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const tooltipVariants = tv({
+  slots: {
+    base: "tooltip",
+    trigger: "tooltip__trigger",
+  },
+});
+
+export type TooltipVariants = VariantProps<typeof tooltipVariants>;
diff --git a/packages/styles/src/components/typography/index.ts b/packages/styles/src/components/typography/index.ts
new file mode 100644
index 0000000..beb6608
--- /dev/null
+++ b/packages/styles/src/components/typography/index.ts
@@ -0,0 +1 @@
+export * from "./typography.styles";
diff --git a/packages/styles/src/components/typography/typography.styles.ts b/packages/styles/src/components/typography/typography.styles.ts
new file mode 100644
index 0000000..3b81eab
--- /dev/null
+++ b/packages/styles/src/components/typography/typography.styles.ts
@@ -0,0 +1,50 @@
+import type {VariantProps} from "tailwind-variants";
+
+import {tv} from "tailwind-variants";
+
+export const typographyVariants = tv({
+  defaultVariants: {
+    align: "start",
+    color: "default",
+    type: "body",
+  },
+  slots: {
+    base: "typography",
+    prose: "typography-prose",
+  },
+  variants: {
+    align: {
+      center: "typography--align-center",
+      end: "typography--align-end",
+      justify: "typography--align-justify",
+      start: "typography--align-start",
+    },
+    color: {
+      default: "typography--color-default",
+      muted: "typography--color-muted",
+    },
+    truncate: {
+      true: "typography--truncate",
+    },
+    type: {
+      body: "typography--body",
+      "body-sm": "typography--body-sm",
+      "body-xs": "typography--body-xs",
+      code: "typography--code",
+      h1: "typography--h1",
+      h2: "typography--h2",
+      h3: "typography--h3",
+      h4: "typography--h4",
+      h5: "typography--h5",
+      h6: "typography--h6",
+    },
+    weight: {
+      bold: "typography--weight-bold",
+      medium: "typography--weight-medium",
+      normal: "typography--weight-normal",
+      semibold: "typography--weight-semibold",
+    },
+  },
+});
+
+export type TypographyVariants = VariantProps<typeof typographyVariants>;
diff --git a/packages/styles/src/index.ts b/packages/styles/src/index.ts
new file mode 100644
index 0000000..49f04c1
--- /dev/null
+++ b/packages/styles/src/index.ts
@@ -0,0 +1,8 @@
+// Re-export tailwind-variants for convenience
+export {tv, cn, type VariantProps} from "tailwind-variants";
+
+// Export utility classes
+export * from "./utils";
+
+// Export all component variants
+export * from "./components";
diff --git a/packages/styles/src/utils/index.ts b/packages/styles/src/utils/index.ts
new file mode 100644
index 0000000..e41312e
--- /dev/null
+++ b/packages/styles/src/utils/index.ts
@@ -0,0 +1,13 @@
+/**
+ * Utility CSS class strings for common component patterns
+ * These are framework-agnostic and can be used with any styling approach
+ */
+
+export const focusRingClasses =
+  "focus-visible:ring-focus focus-visible:ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2";
+
+export const disabledClasses =
+  "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-[var(--disabled-opacity)]";
+
+export const ariaDisabledClasses =
+  "aria-disabled:pointer-events-none aria-disabled:cursor-not-allowed aria-disabled:opacity-[var(--disabled-opacity)]";
diff --git a/packages/styles/themes/default/components/index.css b/packages/styles/themes/default/components/index.css
new file mode 100644
index 0000000..981544a
--- /dev/null
+++ b/packages/styles/themes/default/components/index.css
@@ -0,0 +1,6 @@
+/* Default theme component customizations */
+/* 
+ * This file can contain theme-specific overrides for component styles.
+ * Since the default theme uses the base styles as-is, this file is empty.
+ * Custom themes can override specific component styles here.
+ */
diff --git a/packages/styles/themes/default/index.css b/packages/styles/themes/default/index.css
new file mode 100644
index 0000000..b746d65
--- /dev/null
+++ b/packages/styles/themes/default/index.css
@@ -0,0 +1,8 @@
+/* Declares the theme variables - @see https://tailwindcss.com/docs/theme */
+@import "../shared/theme.css";
+
+/* Default Theme */
+@import "./variables.css" layer(theme);
+
+/* Component customizations for default theme */
+@import "./components/index.css" layer(components);
diff --git a/packages/styles/themes/default/variables.css b/packages/styles/themes/default/variables.css
new file mode 100644
index 0000000..8ae3537
--- /dev/null
+++ b/packages/styles/themes/default/variables.css
@@ -0,0 +1,310 @@
+@layer base {
+  /* HeroUI Default Theme */
+  :root,
+  .light,
+  .default,
+  [data-theme="light"],
+  [data-theme="default"] {
+    color-scheme: light;
+
+    /* == Common Variables == */
+
+    /* Primitive Colors (Do not change between light and dark) */
+    --white: oklch(100% 0 0);
+    --black: oklch(0% 0 0);
+    --snow: oklch(0.9911 0 0);
+    --eclipse: oklch(0.2103 0.0059 285.89);
+
+    /* Spacing scale */
+    --spacing: 0.25rem;
+
+    /* Border */
+    --border-width: 1px;
+    --field-border-width: 0px;
+    --disabled-opacity: 0.5;
+
+    /* Ring offset - Used for focus ring */
+    --ring-offset-width: 2px;
+
+    /* Cursor */
+    --cursor-interactive: pointer;
+    --cursor-disabled: not-allowed;
+
+    /* Radius */
+    --radius: 0.5rem;
+    --field-radius: calc(var(--radius) * 1.5);
+
+    /* == Light Theme Variables == */
+
+    /* Base Colors */
+    --background: oklch(0.9702 0 0);
+    --foreground: var(--eclipse);
+
+    /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+    --surface: var(--white);
+    --surface-foreground: var(--foreground);
+
+    --surface-secondary: oklch(0.9524 0.0013 286.37);
+    --surface-secondary-foreground: var(--foreground);
+
+    --surface-tertiary: oklch(0.9373 0.0013 286.37);
+    --surface-tertiary-foreground: var(--foreground);
+
+    /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
+    --overlay: var(--white);
+    --overlay-foreground: var(--foreground);
+
+    --muted: oklch(0.5517 0.0138 285.94);
+
+    --scrollbar: var(--scrollbar-thumb);
+    --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+    --scrollbar-track: transparent;
+    --scrollbar-gutter: auto;
+    --scrollbar-width: thin;
+    --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+
+    --default: oklch(94% 0.001 286.375);
+    --default-foreground: var(--eclipse);
+
+    --accent: oklch(0.6204 0.195 253.83);
+    --accent-foreground: var(--snow);
+
+    /* Form Fields */
+    --field-background: var(--white);
+    --field-foreground: oklch(0.2103 0.0059 285.89);
+    --field-placeholder: var(--muted);
+    --field-border: transparent; /* no border by default on form fields */
+
+    /* Status Colors */
+    --success: oklch(0.7329 0.1935 150.81);
+    --success-foreground: var(--eclipse);
+
+    --warning: oklch(0.7819 0.1585 72.33);
+    --warning-foreground: var(--eclipse);
+
+    --danger: oklch(0.6532 0.2328 25.74);
+    --danger-foreground: var(--snow);
+
+    /* Component Colors */
+    --segment: var(--white);
+    --segment-foreground: var(--eclipse);
+
+    /* Misc Colors */
+    --border: oklch(90% 0.004 286.32);
+    --separator: oklch(92% 0.004 286.32);
+    --focus: var(--accent);
+    --link: var(--foreground);
+
+    /* Backdrop */
+    --backdrop: rgba(0, 0, 0, 0.5);
+
+    /* Calculated Colors */
+    --surface-hover: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+
+    --background-secondary: color-mix(in oklab, var(--background) 96%, var(--foreground) 4%);
+    --background-tertiary: color-mix(in oklab, var(--background) 92%, var(--foreground) 8%);
+    --background-inverse: var(--foreground);
+
+    --default-hover: color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%);
+    --accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+    --success-hover: color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%);
+    --warning-hover: color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%);
+    --danger-hover: color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%);
+
+    --field-hover: color-mix(
+      in oklab,
+      var(--field-background, var(--default)) 90%,
+      var(--field-foreground, var(--foreground)) 2%
+    );
+    --field-focus: var(--field-background, var(--default));
+    --field-border-hover: color-mix(
+      in oklab,
+      var(--field-border, var(--border)) 88%,
+      var(--field-foreground, var(--foreground)) 10%
+    );
+    --field-border-focus: color-mix(
+      in oklab,
+      var(--field-border, var(--border)) 74%,
+      var(--field-foreground, var(--foreground)) 22%
+    );
+
+    --default-soft: color-mix(in oklab, var(--default) 50%, transparent);
+    --default-soft-foreground: var(--default-foreground);
+    --default-soft-hover: color-mix(in oklab, var(--default) 60%, transparent);
+
+    --accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
+    --accent-soft-foreground: color-mix(in oklab, var(--accent) 70%, var(--foreground) 30%);
+    --accent-soft-hover: color-mix(in oklab, var(--accent) 20%, transparent);
+
+    --danger-soft: color-mix(in oklab, var(--danger) 15%, transparent);
+    --danger-soft-foreground: color-mix(in oklab, var(--danger) 70%, var(--foreground) 40%);
+    --danger-soft-hover: color-mix(in oklab, var(--danger) 20%, transparent);
+
+    --warning-soft: color-mix(in oklab, var(--warning) 15%, transparent);
+    --warning-soft-foreground: color-mix(in oklab, var(--warning) 80%, var(--foreground) 70%);
+    --warning-soft-hover: color-mix(in oklab, var(--warning) 20%, transparent);
+
+    --success-soft: color-mix(in oklab, var(--success) 15%, transparent);
+    --success-soft-foreground: color-mix(in oklab, var(--success) 80%, var(--foreground) 60%);
+    --success-soft-hover: color-mix(in oklab, var(--success) 20%, transparent);
+
+    --separator-secondary: color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%);
+    --separator-tertiary: color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%);
+
+    --border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+    --border-tertiary: color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%);
+
+    /* Shadows */
+    /* --surface-shadow: 0 0px 0px 0 rgba(24, 24, 27, 0.03), 0 2px 10px 0 rgba(24, 24, 27, 0.08); */
+    --surface-shadow:
+      0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+      0 0 1px 0 rgba(0, 0, 0, 0.06);
+    /* Overlay shadow */
+    --overlay-shadow:
+      0 2px 8px 0 rgba(0, 0, 0, 0.06), 0 -6px 12px 0 rgba(0, 0, 0, 0.03),
+      0 14px 28px 0 rgba(0, 0, 0, 0.08);
+    --field-shadow:
+      0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
+      0 0 1px 0 rgba(0, 0, 0, 0.06);
+    /* Skeleton Default Global Animation */
+    --skeleton-animation: shimmer; /* shimmer, pulse, none */
+
+    /* Tooltip Default Delays */
+    --tooltip-delay: 1500ms;
+    --tooltip-close-delay: 500ms;
+  }
+
+  .dark,
+  [data-theme="dark"] {
+    color-scheme: dark;
+    /* == Dark Theme Variables == */
+
+    /* Base Colors */
+    --background: oklch(12% 0.005 285.823);
+    --foreground: var(--snow);
+
+    /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+    --surface: oklch(0.2103 0.0059 285.89);
+    --surface-foreground: var(--foreground);
+
+    --surface-secondary: oklch(0.257 0.0037 286.14);
+    --surface-tertiary: oklch(0.2721 0.0024 247.91);
+
+    /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) - lighter for contrast */
+    --overlay: oklch(0.2103 0.0059 285.89);
+    --overlay-foreground: var(--foreground);
+
+    --muted: oklch(70.5% 0.015 286.067);
+
+    --scrollbar: var(--scrollbar-thumb);
+    --scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
+    --scrollbar-track: transparent;
+    --scrollbar-gutter: auto;
+    --scrollbar-width: thin;
+    --scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+
+    --default: oklch(27.4% 0.006 286.033);
+    --default-foreground: var(--snow);
+
+    /* Form Fields */
+    --field-background: oklch(0.2103 0.0059 285.89);
+    --field-foreground: var(--foreground);
+
+    /* Status Colors */
+    --warning: oklch(0.8203 0.1388 76.34);
+    --warning-foreground: var(--eclipse);
+
+    --danger: oklch(0.594 0.1967 24.63);
+    --danger-foreground: var(--snow);
+
+    /* Component Colors */
+    --segment: oklch(0.3964 0.01 285.93);
+    --segment-foreground: var(--foreground);
+
+    /* Misc Colors */
+    --border: oklch(28% 0.006 286.033);
+    --separator: oklch(25% 0.006 286.033);
+    --focus: var(--accent);
+    --link: var(--foreground);
+
+    /* Backdrop */
+    --backdrop: rgba(0, 0, 0, 0.6);
+
+    /* Shadows */
+    --surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
+    --overlay-shadow: 0 0 1px 0 rgba(255, 255, 255, 0.3) inset;
+    --field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
+
+    /* Calculated Colors */
+    --surface-hover: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
+
+    --background-secondary: color-mix(in oklab, var(--background) 96%, var(--foreground) 4%);
+    --background-tertiary: color-mix(in oklab, var(--background) 92%, var(--foreground) 8%);
+    --background-inverse: var(--foreground);
+
+    --default-hover: color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%);
+    --accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
+    --success-hover: color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%);
+    --warning-hover: color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%);
+    --danger-hover: color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%);
+
+    --field-hover: color-mix(
+      in oklab,
+      var(--field-background, var(--default)) 90%,
+      var(--field-foreground, var(--foreground)) 2%
+    );
+    --field-focus: var(--field-background, var(--default));
+    --field-border-hover: color-mix(
+      in oklab,
+      var(--field-border, var(--border)) 88%,
+      var(--field-foreground, var(--foreground)) 10%
+    );
+    --field-border-focus: color-mix(
+      in oklab,
+      var(--field-border, var(--border)) 74%,
+      var(--field-foreground, var(--foreground)) 22%
+    );
+
+    --default-soft: color-mix(in oklab, var(--default) 50%, transparent);
+    --default-soft-foreground: var(--default-foreground);
+    --default-soft-hover: color-mix(in oklab, var(--default) 60%, transparent);
+
+    --accent-soft: color-mix(in oklab, var(--accent) 12%, transparent);
+    --accent-soft-foreground: color-mix(in oklab, var(--accent) 80%, var(--foreground) 30%);
+    --accent-soft-hover: color-mix(in oklab, var(--accent) 16%, transparent);
+
+    --danger-soft: color-mix(in oklab, var(--danger) 15%, transparent);
+    --danger-soft-foreground: color-mix(in oklab, var(--danger) 80%, var(--foreground) 30%);
+    --danger-soft-hover: color-mix(in oklab, var(--danger) 20%, transparent);
+
+    --warning-soft: color-mix(in oklab, var(--warning) 12%, transparent);
+    --warning-soft-foreground: color-mix(in oklab, var(--warning) 80%, var(--foreground) 30%);
+    --warning-soft-hover: color-mix(in oklab, var(--warning) 16%, transparent);
+
+    --success-soft: color-mix(in oklab, var(--success) 12%, transparent);
+    --success-soft-foreground: color-mix(in oklab, var(--success) 80%, var(--foreground) 30%);
+    --success-soft-hover: color-mix(in oklab, var(--success) 16%, transparent);
+
+    --separator-secondary: color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%);
+    --separator-tertiary: color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%);
+
+    --border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
+    --border-tertiary: color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%);
+  }
+
+  /* Vibrant palette - more saturated soft foregrounds, less contrast */
+  [data-vibrant-palette="true"]:not(.dark):not([data-theme="dark"]) {
+    --accent-soft-foreground: color-mix(in oklab, var(--accent) 92%, var(--foreground) 8%);
+    --danger-soft-foreground: color-mix(in oklab, var(--danger) 92%, var(--foreground) 8%);
+    --warning-soft-foreground: color-mix(in oklab, var(--warning) 92%, var(--foreground) 8%);
+    --success-soft-foreground: color-mix(in oklab, var(--success) 92%, var(--foreground) 8%);
+  }
+
+  [data-vibrant-palette="true"].dark,
+  [data-vibrant-palette="true"][data-theme="dark"] {
+    --accent-soft-foreground: color-mix(in oklab, var(--accent) 92%, var(--foreground) 8%);
+    --danger-soft-foreground: color-mix(in oklab, var(--danger) 92%, var(--foreground) 8%);
+    --warning-soft-foreground: color-mix(in oklab, var(--warning) 92%, var(--foreground) 8%);
+    --success-soft-foreground: color-mix(in oklab, var(--success) 92%, var(--foreground) 8%);
+  }
+}
diff --git a/packages/styles/themes/shared/theme.css b/packages/styles/themes/shared/theme.css
new file mode 100644
index 0000000..1d5fe2c
--- /dev/null
+++ b/packages/styles/themes/shared/theme.css
@@ -0,0 +1,166 @@
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+
+  --color-surface: var(--surface);
+  --color-surface-foreground: var(--surface-foreground);
+  --color-surface-hover: var(--surface-hover);
+
+  --color-surface-secondary: var(--surface-secondary);
+  --color-surface-secondary-foreground: var(--surface-secondary-foreground);
+
+  --color-surface-tertiary: var(--surface-tertiary);
+  --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
+
+  --color-overlay: var(--overlay);
+  --color-overlay-foreground: var(--overlay-foreground);
+
+  --color-muted: var(--muted);
+
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-segment: var(--segment);
+  --color-segment-foreground: var(--segment-foreground);
+
+  --color-border: var(--border);
+  --color-separator: var(--separator);
+  --color-focus: var(--focus);
+  --color-link: var(--link);
+
+  --color-default: var(--default);
+  --color-default-foreground: var(--default-foreground);
+
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+
+  --color-backdrop: var(--backdrop);
+
+  --shadow-surface: var(--surface-shadow);
+  --shadow-overlay: var(--overlay-shadow);
+  --shadow-field: var(--field-shadow);
+
+  /* Form Field Tokens */
+  --color-field: var(--field-background, var(--default));
+  --color-field-hover: var(--field-hover);
+  --color-field-foreground: var(--field-foreground, var(--foreground));
+  --color-field-placeholder: var(--field-placeholder, var(--muted));
+  --color-field-border: var(--field-border, var(--border));
+  --radius-field: var(--field-radius, calc(var(--radius) * 1.5));
+  --border-width-field: var(--field-border-width, var(--border-width));
+
+  /* Color Tokens */
+  --color-background-secondary: var(--background-secondary);
+  --color-background-tertiary: var(--background-tertiary);
+  --color-background-inverse: var(--background-inverse);
+
+  --color-default-hover: var(--default-hover);
+  --color-accent-hover: var(--accent-hover);
+  --color-success-hover: var(--success-hover);
+  --color-warning-hover: var(--warning-hover);
+  --color-danger-hover: var(--danger-hover);
+
+  /* Form Field Colors */
+  --color-field-focus: var(--field-focus);
+  --color-field-border-hover: var(--field-border-hover);
+  --color-field-border-focus: var(--field-border-focus);
+
+  /* Soft Colors */
+  --color-default-soft: var(--default-soft);
+  --color-default-soft-foreground: var(--default-soft-foreground);
+  --color-default-soft-hover: var(--default-soft-hover);
+
+  --color-accent-soft: var(--accent-soft);
+  --color-accent-soft-foreground: var(--accent-soft-foreground);
+  --color-accent-soft-hover: var(--accent-soft-hover);
+
+  --color-danger-soft: var(--danger-soft);
+  --color-danger-soft-foreground: var(--danger-soft-foreground);
+  --color-danger-soft-hover: var(--danger-soft-hover);
+
+  --color-warning-soft: var(--warning-soft);
+  --color-warning-soft-foreground: var(--warning-soft-foreground);
+  --color-warning-soft-hover: var(--warning-soft-hover);
+
+  --color-success-soft: var(--success-soft);
+  --color-success-soft-foreground: var(--success-soft-foreground);
+  --color-success-soft-hover: var(--success-soft-hover);
+
+  /* Separator Colors - Levels */
+  --color-separator-secondary: var(--separator-secondary);
+  --color-separator-tertiary: var(--separator-tertiary);
+
+  /* Border Colors - Levels */
+  --color-border-secondary: var(--border-secondary);
+  --color-border-tertiary: var(--border-tertiary);
+
+  /* Radius and default sizes - defaults can change by just changing the --radius */
+  --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
+  --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
+  --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
+  --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
+  --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
+  --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
+  --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
+  --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
+
+  /* Transition Timing Functions  */
+  --ease-smooth: ease; /* same as transition: ease; */
+  /* These custom curves are made by https://twitter.com/bdc */
+
+  /* From smoother to faster */
+  --ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
+  --ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
+  --ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
+  --ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
+  --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);
+  /* From slower to faster */
+  --ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+  --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
+  --ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
+  --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+  --ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
+  /* Custom smooth-out curve: fast start, smooth stop - Apple style */
+  --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
+  /* From slower to faster */
+  --ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+  --ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
+  --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
+  --ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
+  --ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
+  --ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
+
+  /* Linear */
+  --ease-linear: linear;
+
+  /* Animations */
+  --animate-spin-fast: spin 0.75s linear infinite;
+  --animate-skeleton: skeleton 2s linear infinite;
+  --animate-caret-blink: caret-blink 1.2s ease-out infinite;
+
+  @keyframes skeleton {
+    100% {
+      transform: translateX(200%);
+    }
+  }
+
+  @keyframes caret-blink {
+    0%,
+    70%,
+    100% {
+      opacity: 1;
+    }
+    20%,
+    50% {
+      opacity: 0;
+    }
+  }
+}
diff --git a/packages/styles/tsconfig.json b/packages/styles/tsconfig.json
new file mode 100644
index 0000000..745a349
--- /dev/null
+++ b/packages/styles/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@heroui/standard/tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "noEmit": false,
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/styles/utilities/index.css b/packages/styles/utilities/index.css
new file mode 100644
index 0000000..26a767f
--- /dev/null
+++ b/packages/styles/utilities/index.css
@@ -0,0 +1,83 @@
+/* === Focus Ring === */
+@utility focus-ring {
+  @apply ring-2 ring-focus ring-offset-0 ring-offset-background outline-none;
+  /* Overrides the ring offset from the theme variables */
+  --tw-ring-offset-width: var(--ring-offset-width);
+}
+
+@utility focus-field-ring {
+  @apply ring-2 ring-focus ring-offset-0 outline-none;
+  /* No separation - ring sits directly against the element */
+  --tw-ring-offset-width: 0px;
+}
+
+@utility invalid-field-ring {
+  /* Unfocused: show 1px outline */
+  @apply outline-1 outline-danger outline-solid;
+  --tw-ring-offset-width: 3px;
+
+  /* Focused: show 2px ring in danger color, remove outline */
+  &:focus,
+  &:focus-visible,
+  &[data-focused="true"],
+  &[data-focus-visible="true"],
+  &:focus-within,
+  &[data-focus-within="true"] {
+    @apply ring-2 ring-danger ring-offset-0;
+    --tw-ring-offset-width: 0px;
+  }
+}
+
+@utility no-highlight {
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* === Statuses === */
+@utility status-focused {
+  @apply focus-ring;
+}
+
+@utility status-focused-field {
+  @apply focus-field-ring;
+}
+
+@utility status-invalid-field {
+  @apply invalid-field-ring;
+}
+
+@utility status-disabled {
+  opacity: var(--disabled-opacity);
+  cursor: var(--cursor-disabled);
+  pointer-events: none;
+}
+
+@utility status-pending {
+  @apply pointer-events-none;
+}
+
+/* === Scrollbars (standards-only; apply per scroll slot in component CSS) === */
+@utility scrollbar {
+  scrollbar-width: var(--scrollbar-width);
+  scrollbar-color: var(--scrollbar-color);
+  scrollbar-gutter: var(--scrollbar-gutter);
+}
+
+@utility scrollbar-thin {
+  scrollbar-width: thin;
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+  scrollbar-gutter: auto;
+}
+
+@utility scrollbar-default {
+  scrollbar-width: auto;
+  scrollbar-color: auto;
+  scrollbar-gutter: auto;
+}
+
+/* Direct properties only — does not inherit none to nested scroll slots */
+@utility scrollbar-none {
+  scrollbar-width: none;
+  scrollbar-color: auto;
+  scrollbar-gutter: auto;
+  -ms-overflow-style: none;
+}
diff --git a/packages/styles/variants/index.css b/packages/styles/variants/index.css
new file mode 100644
index 0000000..97c05e3
--- /dev/null
+++ b/packages/styles/variants/index.css
@@ -0,0 +1,106 @@
+/**
+ * ================================================================================================
+ * HeroUI Custom Tailwind CSS Variants
+ * ================================================================================================
+ *
+ * Custom variants with intelligent fallback: explicit controls override system preferences.
+ *
+ * Usage:
+ *   motion-reduce:opacity-0      - Reduced motion accessibility
+ *   motion-safe:animate-spin     - Full motion effects
+ *   dark:bg-gray-900             - Dark mode styles
+ *
+ * Priority: Explicit data attributes/classes → System preferences (fallback)
+ * ================================================================================================
+ */
+
+/* -------------------------------------------------------------------------------------------------
+ * motion-reduce — Minimize animations for accessibility
+ * Priority: data-reduce-motion="true" → prefers-reduced-motion: reduce
+ * ------------------------------------------------------------------------------------------------- */
+@custom-variant motion-reduce {
+  /* Explicit: data-reduce-motion="true" on element or ancestor */
+  &:is([data-reduce-motion="true"], [data-reduce-motion="true"] *) {
+    @slot;
+
+    &::before,
+    &::after {
+      @slot;
+    }
+  }
+
+  /* Fallback: system prefers-reduced-motion setting */
+  @media (prefers-reduced-motion: reduce) {
+    &:not(:is([data-reduce-motion="true"], [data-reduce-motion="true"] *)) {
+      @slot;
+
+      &::before,
+      &::after {
+        @slot;
+      }
+    }
+  }
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * motion-safe — Enable full animations and transitions
+ * Priority: data-reduce-motion="false" → prefers-reduced-motion: no-preference
+ * ------------------------------------------------------------------------------------------------- */
+@custom-variant motion-safe {
+  /* Explicit: data-reduce-motion="false" on element or ancestor */
+  &:is([data-reduce-motion="false"], [data-reduce-motion="false"] *) {
+    @slot;
+
+    &::before,
+    &::after {
+      @slot;
+    }
+  }
+
+  /* Fallback: system has no motion preference set */
+  @media (prefers-reduced-motion: no-preference) {
+    &:not(
+      :is(
+        [data-reduce-motion="true"],
+        [data-reduce-motion="true"] *,
+        [data-reduce-motion="false"],
+        [data-reduce-motion="false"] *
+      )
+    ) {
+      @slot;
+
+      &::before,
+      &::after {
+        @slot;
+      }
+    }
+  }
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * dark — Dark mode styles
+ * Priority: .dark class / data-theme="dark" → prefers-color-scheme: dark
+ * ------------------------------------------------------------------------------------------------- */
+@custom-variant dark {
+  /* Explicit: .dark class or data-theme="dark" on element or ancestor */
+  &:is(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *) {
+    @slot;
+
+    &::before,
+    &::after {
+      @slot;
+    }
+  }
+
+  /* Fallback: system prefers dark color scheme */
+  @media (prefers-color-scheme: dark) {
+    &:not(:is(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *)) & {
+      @slot;
+
+      &::before,
+      &::after {
+        @slot;
+      }
+    }
+  }
+}
diff --git a/packages/vitest/configs/base.ts b/packages/vitest/configs/base.ts
new file mode 100644
index 0000000..7d8147a
--- /dev/null
+++ b/packages/vitest/configs/base.ts
@@ -0,0 +1,18 @@
+import {defineConfig} from "vitest/config";
+
+export const baseConfig = defineConfig({
+  test: {
+    coverage: {
+      enabled: true,
+      provider: "istanbul",
+      reporter: [
+        [
+          "json",
+          {
+            file: `../coverage.json`,
+          },
+        ],
+      ],
+    },
+  },
+});
diff --git a/packages/vitest/configs/react.ts b/packages/vitest/configs/react.ts
new file mode 100644
index 0000000..036f61a
--- /dev/null
+++ b/packages/vitest/configs/react.ts
@@ -0,0 +1,13 @@
+import {defineProject, mergeConfig} from "vitest/config";
+
+import {baseConfig} from "./base";
+
+export const uiConfig = mergeConfig(
+  baseConfig,
+  defineProject({
+    test: {
+      environment: "jsdom",
+      globals: true,
+    },
+  }),
+);
diff --git a/packages/vitest/package.json b/packages/vitest/package.json
new file mode 100644
index 0000000..3d0b8c7
--- /dev/null
+++ b/packages/vitest/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@heroui/vitest",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "collect-json-reports": "node dist/scripts/collect-json-outputs.js",
+    "merge-json-reports": "nyc merge coverage/raw coverage/merged/merged-coverage.json",
+    "build": "storybook build",
+    "start": "storybook start"
+  },
+  "devDependencies": {
+    "@heroui/standard": "workspace:*",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.1",
+    "@testing-library/user-event": "14.6.1",
+    "glob": "13.0.0"
+  }
+}
diff --git a/packages/vitest/scripts/collect-json-outputs.ts b/packages/vitest/scripts/collect-json-outputs.ts
new file mode 100644
index 0000000..0fc9e6a
--- /dev/null
+++ b/packages/vitest/scripts/collect-json-outputs.ts
@@ -0,0 +1,61 @@
+import fs from "fs/promises";
+import path from "path";
+
+import {glob} from "glob";
+
+async function collectCoverageFiles() {
+  try {
+    const patterns = ["../../apps/*", "../../packages/*"];
+
+    const destinationDir = path.join(process.cwd(), "coverage/raw");
+
+    await fs.mkdir(destinationDir, {recursive: true});
+
+    const allDirectories = [];
+    const directoriesWithCoverage = [];
+
+    for (const pattern of patterns) {
+      const matches = await glob(pattern);
+
+      for (const match of matches) {
+        const stats = await fs.stat(match);
+
+        if (stats.isDirectory()) {
+          allDirectories.push(match);
+          const coverageFilePath = path.join(match, "coverage.json");
+
+          try {
+            await fs.access(coverageFilePath);
+
+            directoriesWithCoverage.push(match);
+
+            const directoryName = path.basename(match);
+            const destinationFile = path.join(destinationDir, `${directoryName}.json`);
+
+            await fs.copyFile(coverageFilePath, destinationFile);
+          } catch (error) {
+            // eslint-disable-next-line no-console
+            console.log(`File doesn't exist in this directory, skip: ${coverageFilePath}`);
+          }
+        }
+      }
+    }
+
+    const replaceDotPatterns = (str: string) => str.replace(/\.\.\//g, "");
+
+    if (directoriesWithCoverage.length > 0) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `Found coverage.json in: ${directoriesWithCoverage.map(replaceDotPatterns).join(", ")}`,
+      );
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`Coverage collected into: ${path.join(process.cwd())}`);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error("Error collecting coverage files:", error);
+  }
+}
+
+collectCoverageFiles();
diff --git a/packages/vitest/tsconfig.json b/packages/vitest/tsconfig.json
new file mode 100644
index 0000000..ba957cc
--- /dev/null
+++ b/packages/vitest/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@heroui/standard/tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": ["src", "scripts"],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/vitest/turbo.json b/packages/vitest/turbo.json
new file mode 100644
index 0000000..951ac45
--- /dev/null
+++ b/packages/vitest/turbo.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "extends": ["//"],
+  "tasks": {
+    "collect-json-reports": {
+      "cache": false
+    },
+    "merge-json-reports": {
+      "dependsOn": ["collect-json-reports"],
+      "inputs": ["coverage/raw/**"],
+      "outputs": ["coverage/merged/**"]
+    },
+    "build": {
+      "dependsOn": ["merge-json-reports"],
+      "inputs": ["coverage/merge"],
+      "outputs": ["coverage/report/**"]
+    },
+    "start": {
+      "dependsOn": ["report"],
+      "cache": false
+    }
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
new file mode 100644
index 0000000..a867dfb
--- /dev/null
+++ b/pnpm-lock.yaml
@@ -0,0 +1,15102 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+overrides:
+  shiki: 3.20.0
+  ts-morph: 27.0.2
+
+importers:
+
+  .:
+    devDependencies:
+      '@babel/core':
+        specifier: 7.28.5
+        version: 7.28.5
+      '@babel/preset-react':
+        specifier: 7.28.5
+        version: 7.28.5(@babel/core@7.28.5)
+      '@babel/preset-typescript':
+        specifier: 7.28.5
+        version: 7.28.5(@babel/core@7.28.5)
+      '@commitlint/cli':
+        specifier: 20.2.0
+        version: 20.2.0(@types/node@25.0.3)(conventional-commits-parser@6.4.0)(typescript@5.9.3)
+      '@commitlint/config-conventional':
+        specifier: 20.2.0
+        version: 20.2.0
+      '@eslint/eslintrc':
+        specifier: 3.3.3
+        version: 3.3.3
+      '@eslint/js':
+        specifier: 9.39.2
+        version: 9.39.2
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:packages/standard
+      '@next/eslint-plugin-next':
+        specifier: 16.1.1
+        version: 16.1.1
+      '@rollup/plugin-babel':
+        specifier: 6.1.0
+        version: 6.1.0(@babel/core@7.28.5)(@types/babel__core@7.20.5)(rollup@4.54.0)
+      '@rollup/plugin-commonjs':
+        specifier: 29.0.0
+        version: 29.0.0(rollup@4.54.0)
+      '@rollup/plugin-node-resolve':
+        specifier: 16.0.3
+        version: 16.0.3(rollup@4.54.0)
+      '@rollup/plugin-typescript':
+        specifier: 12.3.0
+        version: 12.3.0(rollup@4.54.0)(tslib@2.8.1)(typescript@5.9.3)
+      '@types/node':
+        specifier: 25.0.3
+        version: 25.0.3
+      '@typescript-eslint/eslint-plugin':
+        specifier: 8.50.1
+        version: 8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/parser':
+        specifier: 8.50.1
+        version: 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      babel-plugin-react-compiler:
+        specifier: 19.1.0-rc.3
+        version: 19.1.0-rc.3
+      bumpp:
+        specifier: 11.0.1
+        version: 11.0.1
+      clean-package:
+        specifier: 2.2.0
+        version: 2.2.0
+      dotenv:
+        specifier: 17.2.3
+        version: 17.2.3
+      dotenv-cli:
+        specifier: 11.0.0
+        version: 11.0.0
+      eslint:
+        specifier: 9.39.2
+        version: 9.39.2(jiti@2.6.1)
+      eslint-config-next:
+        specifier: 16.1.1
+        version: 16.1.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      eslint-config-prettier:
+        specifier: 10.1.8
+        version: 10.1.8(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import:
+        specifier: 2.32.0
+        version: 2.32.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-jsx-a11y:
+        specifier: 6.10.2
+        version: 6.10.2(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-only-warn:
+        specifier: 1.1.0
+        version: 1.1.0
+      eslint-plugin-prettier:
+        specifier: 5.5.4
+        version: 5.5.4(eslint-config-prettier@10.1.8(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))(prettier@3.7.4)
+      eslint-plugin-react:
+        specifier: 7.37.5
+        version: 7.37.5(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react-hooks:
+        specifier: 7.0.1
+        version: 7.0.1(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react-refresh:
+        specifier: 0.4.26
+        version: 0.4.26(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-sort-destructure-keys:
+        specifier: 2.0.0
+        version: 2.0.0(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-sort-keys-fix:
+        specifier: 1.1.2
+        version: 1.1.2
+      eslint-plugin-storybook:
+        specifier: 10.1.10
+        version: 10.1.10(eslint@9.39.2(jiti@2.6.1))(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)
+      eslint-plugin-unused-imports:
+        specifier: 4.3.0
+        version: 4.3.0(@typescript-eslint/eslint-plugin@8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))
+      globals:
+        specifier: 16.5.0
+        version: 16.5.0
+      husky:
+        specifier: 9.1.7
+        version: 9.1.7
+      jiti:
+        specifier: 2.6.1
+        version: 2.6.1
+      lint-staged:
+        specifier: 16.2.7
+        version: 16.2.7
+      parcel:
+        specifier: 2.16.3
+        version: 2.16.3(@swc/helpers@0.5.23)
+      postcss:
+        specifier: 8.5.6
+        version: 8.5.6
+      prettier:
+        specifier: 3.7.4
+        version: 3.7.4
+      prettier-plugin-css-order:
+        specifier: 2.1.2
+        version: 2.1.2(postcss@8.5.6)(prettier@3.7.4)
+      prettier-plugin-tailwindcss:
+        specifier: 0.7.2
+        version: 0.7.2(prettier-plugin-css-order@2.1.2(postcss@8.5.6)(prettier@3.7.4))(prettier@3.7.4)
+      rollup:
+        specifier: 4.54.0
+        version: 4.54.0
+      rollup-plugin-peer-deps-external:
+        specifier: 2.2.4
+        version: 2.2.4(rollup@4.54.0)
+      rollup-plugin-postcss:
+        specifier: 4.0.2
+        version: 4.0.2(postcss@8.5.6)
+      tsup:
+        specifier: 8.5.1
+        version: 8.5.1(@swc/core@1.15.40(@swc/helpers@0.5.23))(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      tsx:
+        specifier: 4.21.0
+        version: 4.21.0
+      turbo:
+        specifier: 2.7.2
+        version: 2.7.2
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+      typescript-eslint:
+        specifier: 8.50.1
+        version: 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      vitest:
+        specifier: 4.0.16
+        version: 4.0.16(@opentelemetry/api@1.9.1)(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  apps/docs:
+    dependencies:
+      '@fumadocs/language':
+        specifier: 0.0.1
+        version: 0.0.1(15443bcb60600a3f8a026059ee77d437)
+      '@gravity-ui/icons':
+        specifier: 2.16.0
+        version: 2.16.0(react@19.2.6)
+      '@heroui/react':
+        specifier: workspace:*
+        version: link:../../packages/react
+      '@iconify-json/gravity-ui':
+        specifier: 1.2.10
+        version: 1.2.10
+      '@iconify/react':
+        specifier: 6.0.2
+        version: 6.0.2(react@19.2.6)
+      '@internationalized/date':
+        specifier: 3.12.2
+        version: 3.12.2
+      '@lglab/react-qr-code':
+        specifier: 1.7.0
+        version: 1.7.0(react@19.2.6)
+      '@react-aria/overlays':
+        specifier: 3.32.1
+        version: 3.32.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-stately/data':
+        specifier: 3.16.1
+        version: 3.16.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@t3-oss/env-nextjs':
+        specifier: 0.13.10
+        version: 0.13.10(typescript@5.9.3)(zod@4.2.1)
+      '@tailwindcss/typography':
+        specifier: 0.5.19
+        version: 0.5.19(tailwindcss@4.3.0)
+      '@tanstack/react-table':
+        specifier: 8.21.3
+        version: 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@vercel/analytics':
+        specifier: 1.6.1
+        version: 1.6.1(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6)
+      '@vercel/og':
+        specifier: 0.8.6
+        version: 0.8.6
+      calligraph:
+        specifier: 1.3.0
+        version: 1.3.0(motion@12.23.26(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      clsx:
+        specifier: 2.1.1
+        version: 2.1.1
+      color-convert:
+        specifier: 3.1.3
+        version: 3.1.3
+      color2k:
+        specifier: 2.0.3
+        version: 2.0.3
+      culori:
+        specifier: 4.0.2
+        version: 4.0.2
+      feed:
+        specifier: 5.1.0
+        version: 5.1.0
+      fumadocs-core:
+        specifier: 16.9.0
+        version: 16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1)
+      fumadocs-mdx:
+        specifier: 14.2.2
+        version: 14.2.2(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      fumadocs-typescript:
+        specifier: 5.0.0
+        version: 5.0.0(cdcaa0f702fde0940675ed572330cf20)
+      fumadocs-ui:
+        specifier: 16.9.0
+        version: 16.9.0(@tailwindcss/oxide@4.3.0)(@types/mdx@2.0.13)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tailwindcss@4.3.0)
+      gray-matter:
+        specifier: 4.0.3
+        version: 4.0.3
+      lucide-react:
+        specifier: 0.562.0
+        version: 0.562.0(react@19.2.6)
+      m3-ripple:
+        specifier: 1.1.3
+        version: 1.1.3(react@19.2.6)
+      motion:
+        specifier: 12.23.26
+        version: 12.23.26(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      next:
+        specifier: 16.2.6
+        version: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      next-mdx-remote:
+        specifier: 6.0.0
+        version: 6.0.0(@types/react@19.2.14)(react@19.2.6)
+      next-sitemap:
+        specifier: 4.2.3
+        version: 4.2.3(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
+      next-themes:
+        specifier: 0.4.6
+        version: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      nuqs:
+        specifier: 2.8.6
+        version: 2.8.6(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6)
+      posthog-node:
+        specifier: 5.21.0
+        version: 5.21.0
+      react:
+        specifier: 19.2.6
+        version: 19.2.6
+      react-aria-components:
+        specifier: 1.19.0
+        version: 1.19.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom:
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
+      remark:
+        specifier: 15.0.1
+        version: 15.0.1
+      remark-gfm:
+        specifier: 4.0.1
+        version: 4.0.1
+      remark-mdx:
+        specifier: 3.1.1
+        version: 3.1.1
+      shiki:
+        specifier: 3.20.0
+        version: 3.20.0
+      tailwind-merge:
+        specifier: 3.4.0
+        version: 3.4.0
+      tailwind-variants:
+        specifier: 3.2.2
+        version: 3.2.2(tailwind-merge@3.4.0)(tailwindcss@4.3.0)
+      ts-morph:
+        specifier: 27.0.2
+        version: 27.0.2
+      usehooks-ts:
+        specifier: 3.1.1
+        version: 3.1.1(react@19.2.6)
+      zod:
+        specifier: 4.2.1
+        version: 4.2.1
+    devDependencies:
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:../../packages/standard
+      '@heroui/styles':
+        specifier: workspace:*
+        version: link:../../packages/styles
+      '@tailwindcss/postcss':
+        specifier: 4.3.0
+        version: 4.3.0
+      '@types/color-convert':
+        specifier: 2.0.4
+        version: 2.0.4
+      '@types/culori':
+        specifier: 4.0.1
+        version: 4.0.1
+      '@types/mdx':
+        specifier: 2.0.13
+        version: 2.0.13
+      '@types/react':
+        specifier: 19.2.14
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: 19.2.3
+        version: 19.2.3(@types/react@19.2.14)
+      babel-plugin-react-compiler:
+        specifier: 1.0.0
+        version: 1.0.0
+      postcss:
+        specifier: 8.5.6
+        version: 8.5.6
+      source-map-support:
+        specifier: 0.5.21
+        version: 0.5.21
+      tailwindcss:
+        specifier: 4.3.0
+        version: 4.3.0
+      tar:
+        specifier: 7.5.7
+        version: 7.5.7
+
+  packages/react:
+    dependencies:
+      '@heroui/styles':
+        specifier: workspace:*
+        version: link:../styles
+      '@radix-ui/react-avatar':
+        specifier: 1.1.11
+        version: 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-aria/i18n':
+        specifier: 3.13.1
+        version: 3.13.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-aria/ssr':
+        specifier: 3.10.1
+        version: 3.10.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-aria/utils':
+        specifier: 3.34.1
+        version: 3.34.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-stately/utils':
+        specifier: 3.12.1
+        version: 3.12.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-types/color':
+        specifier: 3.2.0
+        version: 3.2.0(@react-spectrum/provider@3.11.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-types/shared':
+        specifier: 3.36.0
+        version: 3.36.0(react@19.2.6)
+      input-otp:
+        specifier: 1.4.2
+        version: 1.4.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-aria:
+        specifier: ^3.50.0
+        version: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-aria-components:
+        specifier: ^1.19.0
+        version: 1.19.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tailwind-merge:
+        specifier: 3.4.0
+        version: 3.4.0
+      tailwind-variants:
+        specifier: 3.2.2
+        version: 3.2.2(tailwind-merge@3.4.0)(tailwindcss@4.1.18)
+    devDependencies:
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:../standard
+      '@iconify/react':
+        specifier: 6.0.2
+        version: 6.0.2(react@19.2.6)
+      '@internationalized/date':
+        specifier: 3.12.2
+        version: 3.12.2
+      '@react-stately/data':
+        specifier: 3.16.1
+        version: 3.16.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@storybook/react':
+        specifier: 10.1.10
+        version: 10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)
+      '@types/fs-extra':
+        specifier: 11.0.4
+        version: 11.0.4
+      '@types/react':
+        specifier: 19.2.14
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: 19.2.3
+        version: 19.2.3(@types/react@19.2.14)
+      fs-extra:
+        specifier: 11.3.3
+        version: 11.3.3
+      react:
+        specifier: 19.2.6
+        version: 19.2.6
+      react-dom:
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
+      tailwindcss:
+        specifier: 4.1.18
+        version: 4.1.18
+
+  packages/standard: {}
+
+  packages/storybook:
+    dependencies:
+      '@gravity-ui/icons':
+        specifier: 2.16.0
+        version: 2.16.0(react@19.2.6)
+      '@heroui/react':
+        specifier: workspace:*
+        version: link:../react
+      '@heroui/styles':
+        specifier: workspace:*
+        version: link:../styles
+      '@iconify/react':
+        specifier: 6.0.2
+        version: 6.0.2(react@19.2.6)
+      apcach:
+        specifier: 0.6.4
+        version: 0.6.4
+      culori:
+        specifier: 4.0.2
+        version: 4.0.2
+      react:
+        specifier: 19.2.6
+        version: 19.2.6
+      react-aria-components:
+        specifier: 1.19.0
+        version: 1.19.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom:
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
+      react-scan:
+        specifier: 0.4.3
+        version: 0.4.3(@types/react@19.2.14)(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(rollup@4.54.0)
+      tailwind-variants:
+        specifier: ^3.2.2
+        version: 3.2.2(tailwind-merge@3.6.0)(tailwindcss@4.3.0)
+    devDependencies:
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:../standard
+      '@storybook/addon-a11y':
+        specifier: 10.1.10
+        version: 10.1.10(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
+      '@storybook/addon-docs':
+        specifier: 10.1.10
+        version: 10.1.10(@types/react@19.2.14)(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@storybook/icons':
+        specifier: 2.0.1
+        version: 2.0.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@storybook/react':
+        specifier: 10.1.10
+        version: 10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)
+      '@storybook/react-vite':
+        specifier: 10.1.10
+        version: 10.1.10(esbuild@0.27.7)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@tailwindcss/postcss':
+        specifier: 4.3.0
+        version: 4.3.0
+      '@tailwindcss/vite':
+        specifier: 4.3.0
+        version: 4.3.0(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@types/react':
+        specifier: 19.2.14
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: 19.2.3
+        version: 19.2.3(@types/react@19.2.14)
+      '@vitejs/plugin-react':
+        specifier: 5.1.2
+        version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      glob:
+        specifier: 13.0.0
+        version: 13.0.0
+      postcss:
+        specifier: 8.5.6
+        version: 8.5.6
+      storybook:
+        specifier: 10.1.10
+        version: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tailwindcss:
+        specifier: 4.3.0
+        version: 4.3.0
+      vite:
+        specifier: 7.3.0
+        version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/styles:
+    dependencies:
+      tailwind-variants:
+        specifier: 3.2.2
+        version: 3.2.2(tailwind-merge@3.6.0)(tailwindcss@4.3.0)
+      tw-animate-css:
+        specifier: 1.4.0
+        version: 1.4.0
+    devDependencies:
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:../standard
+      '@tailwindcss/cli':
+        specifier: 4.3.0
+        version: 4.3.0
+      '@types/fs-extra':
+        specifier: 11.0.4
+        version: 11.0.4
+      clean-package:
+        specifier: 2.2.0
+        version: 2.2.0
+      fs-extra:
+        specifier: 11.3.3
+        version: 11.3.3
+      rimraf:
+        specifier: 6.1.2
+        version: 6.1.2
+      tailwindcss:
+        specifier: 4.3.0
+        version: 4.3.0
+      typescript:
+        specifier: 5.8.3
+        version: 5.8.3
+
+  packages/vitest:
+    devDependencies:
+      '@heroui/standard':
+        specifier: workspace:*
+        version: link:../standard
+      '@testing-library/jest-dom':
+        specifier: 6.9.1
+        version: 6.9.1
+      '@testing-library/react':
+        specifier: 16.3.1
+        version: 16.3.1(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@testing-library/user-event':
+        specifier: 14.6.1
+        version: 14.6.1(@testing-library/dom@10.4.1)
+      glob:
+        specifier: 13.0.0
+        version: 13.0.0
+
+packages:
+
+  '@adobe/css-tools@4.5.0':
+    resolution: {integrity: sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==}
+
+  '@adobe/react-spectrum-ui@1.2.1':
+    resolution: {integrity: sha512-wcrbEE2O/9WnEn6avBnaVRRx88S5PLFsPLr4wffzlbMfXeQsy+RMQwaJd3cbzrn18/j04Isit7f7Emfn0dhrJA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0
+
+  '@adobe/react-spectrum-workflow@2.3.5':
+    resolution: {integrity: sha512-b53VIPwPWKb/T5gzE3qs+QlGP5gVrw/LnWV3xMksDU+CRl3rzOKUwxIGiZO8ICyYh1WiyqY4myGlPU/nAynBUg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0
+
+  '@adobe/react-spectrum@3.47.1':
+    resolution: {integrity: sha512-mijNyd8XmA6KoBMbqKc4Rp+S2voKdZkPydJFjQbG0SkOjOKcgqVpJdKGsKdLMZBn9Jk5SgEuklyrhc7Uvot2tA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@alloc/quick-lru@5.2.0':
+    resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
+    engines: {node: '>=10'}
+
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.7':
+    resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.28.5':
+    resolution: {integrity: sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-annotate-as-pure@7.29.7':
+    resolution: {integrity: sha512-OoK6239jHPuSQOoS0kfTVKn0b/rVTk0seKq4Gd2UMLtmOVLjDC0ki3e+c90Trqv2gMfvJFqkiljrr568+qddiw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@7.29.7':
+    resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-create-class-features-plugin@7.29.7':
+    resolution: {integrity: sha512-IY3ZD9Tmooqr3TUhc3DUWxiuo8xx1DWLhd5M7hQ+ZWJamqM2BbalrBJb2MisSLoYorOj75U03qULCxQTY9r3hg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-member-expression-to-functions@7.29.7':
+    resolution: {integrity: sha512-j+7JYmk1JYDtACIGj0QJqqWZjoUpMoEikQGADMaHgCMCSDqd2+P32rfcibUNrGOMWrlzK1WJBdxrB3JJQZwWtg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.29.7':
+    resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-optimise-call-expression@7.29.7':
+    resolution: {integrity: sha512-+kmGVjcT9RGYzoDwdwEqEvGgKe3BYq+O1iGzjFubaNgZHwYHP6lsF2Yghf4kEuv9BV7tYDZ913aBW9am6YKong==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-plugin-utils@7.29.7':
+    resolution: {integrity: sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-replace-supers@7.29.7':
+    resolution: {integrity: sha512-atfGXWSeCiF4DnKZIfmJfQRkSw9b9gNNXR1kqKjbhG4pGYCOnkp8OcTB8E3NXjBu8NpheSnOeNKz8KT7UNFTmQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
+    resolution: {integrity: sha512-brcMGQaVzIeUb+6/bs1Av0f8YuNNjKY2JyvfRCsFuFsdKccEQ5Ges2y74D74NZ1Rz8lKJ9ksJkfqwQFJ/iNEyQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@7.29.7':
+    resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/plugin-syntax-jsx@7.29.7':
+    resolution: {integrity: sha512-TSu8+mHCoEaaCDEZ0I3+6mvTBYR4PCxQwf2z9/r5Tbztv6NaLR3B9thGTTxX2WGuGHJqRiAbKPeGTJ5XWXVg6A==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-syntax-typescript@7.29.7':
+    resolution: {integrity: sha512-ngr+82Sh0xMz25TPCZi+nC2iTzjfCdWS2ONXTp/PtSCHCgaCNBpdMqgvJ2ccdLlClVZ7sisIgB914j/JFe+RZA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-modules-commonjs@7.29.7':
+    resolution: {integrity: sha512-j0vCldybPC5b5dwCQOJ21uKtHzt7hxLygJTg9eF1ScfaikEDNfzn94XoW5Fi+seBR0nCyL23xaBFFkq7dTM8XQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-display-name@7.29.7':
+    resolution: {integrity: sha512-+1wdDMGNb4UPeY3Q4L5yLiYe6TXPXubs4NjrgRFw13hPRLJfEMw2Q5OXkee6/IfdqePIeW4Jjwe3aBh7SdKz4Q==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-development@7.29.7':
+    resolution: {integrity: sha512-Xfy3UVMF04+ypnFbkhvfqtmvwfe92qwQdbGZVonhE+6v35GzlofmOnA1szaZqzb9xYWr0nl1e5EMmzi0DNON1g==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-self@7.29.7':
+    resolution: {integrity: sha512-TL0hMc9xzy86VD31nUiwzd5otRAcyEPcsegCxolO0PvcXuH1v0kECe/UIznYFihpkvU5wg/jk4v0TTEFfm53fw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-source@7.29.7':
+    resolution: {integrity: sha512-06IyK09H3wi4cGbhDBwp5gUGo0IKtnYa8tyTiephirPCK6fbobVGiXMMI5zLQ4aKEYP3wZ3ArU44o+8KMrSG/Q==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx@7.29.7':
+    resolution: {integrity: sha512-WsZulLVBUHXVj2cUcPVx6UE21TpalB6bHbSFErKT0Ib++ax24jjXe73FqlWvdylFOjiuPHYi6VCcgRad1ItN+A==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-pure-annotations@7.29.7':
+    resolution: {integrity: sha512-H5E+HBgDpr6Q5t+Aj11tL7XkIui1jhbIoArVQnqjgXo5/3YxkN7ZEBcWF4RQlB0T4rrxJQbXS6kiFV6B7XTqUA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-typescript@7.29.7':
+    resolution: {integrity: sha512-jK52h8LaLc7JarhQV2ofeFMts4H7vnOXnqZNA6fYglBTZewRBE51KWt3BUltW1P+KoPsYkHoJeXePuz4zo2LMw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/preset-react@7.28.5':
+    resolution: {integrity: sha512-Z3J8vhRq7CeLjdC58jLv4lnZ5RKFUJWqH5emvxmv9Hv3BD1T9R/Im713R4MTKwvFaV74ejZ3sM01LyEKk4ugNQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/preset-typescript@7.28.5':
+    resolution: {integrity: sha512-+bQy5WOI2V6LJZpPVxY+yp66XdZ2yifu0Mc1aP5CQKgjn4QM5IN2i5fAZ4xKop47pr8rpVhiAeu+nDQa12C8+g==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/runtime@7.29.7':
+    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
+  '@clack/core@0.3.5':
+    resolution: {integrity: sha512-5cfhQNH+1VQ2xLQlmzXMqUoiaH0lRBq9/CLW9lTyMbuKLC3+xEK01tHVvyut++mLOn5urSHmkm6I0Lg9MaJSTQ==}
+
+  '@clack/prompts@0.8.2':
+    resolution: {integrity: sha512-6b9Ab2UiZwJYA9iMyboYyW9yJvAO9V753ZhS+DHKEjZRKAxPPOb7MXXu84lsPFG+vZt6FRFniZ8rXi+zCIw4yQ==}
+
+  '@commitlint/cli@20.2.0':
+    resolution: {integrity: sha512-l37HkrPZ2DZy26rKiTUvdq/LZtlMcxz+PeLv9dzK9NzoFGuJdOQyYU7IEkEQj0pO++uYue89wzOpZ0hcTtoqUA==}
+    engines: {node: '>=v18'}
+    hasBin: true
+
+  '@commitlint/config-conventional@20.2.0':
+    resolution: {integrity: sha512-MsRac+yNIbTB4Q/psstKK4/ciVzACHicSwz+04Sxve+4DW+PiJeTjU0JnS4m/oOnulrXYN+yBPlKaBSGemRfgQ==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/config-validator@20.5.0':
+    resolution: {integrity: sha512-T/Uh6iJUzyx7j35GmHWdIiGRQB+ouZDk0pwAaYq4SXgB54KZhFdJ0vYmxiW6AMYICTIWuyMxDBl1jK74oFp/Gw==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/ensure@20.5.3':
+    resolution: {integrity: sha512-4i4AgNvH62owG9MwSiWKrle7HGNpBHHdLnWFIp5fTsHUYe5kRuh15t08L/0pdbbrRk8JKXQxxN4hZQcn+szkrw==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/execute-rule@20.0.0':
+    resolution: {integrity: sha512-xyCoOShoPuPL44gVa+5EdZsBVao/pNzpQhkzq3RdtlFdKZtjWcLlUFQHSWBuhk5utKYykeJPSz2i8ABHQA+ZZw==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/format@20.5.0':
+    resolution: {integrity: sha512-TI9EwFU/qZWSK7a5qyXMpKPPv3qta7FO4tKW+Wt2al7sgMbLWTsAcDpX1cU8k16TRdsiiet9aOw0zpvRXNJu7Q==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/is-ignored@20.5.0':
+    resolution: {integrity: sha512-JWLarAsurHJhPozbuAH6GbP4p/hdOCoqS9zJMfqwswne+/GPs5V0+rrsfOkP68Y8PSLphwtFXV0EzJ+GTXTTGg==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/lint@20.5.3':
+    resolution: {integrity: sha512-M7JbWBNr2gXKaPc4i/KipsuW1gkDHpj35KPjWtKy3Z+2AQw5wu1gBi1LIO0uoaij67CqY4K8PxPZSGens4evCw==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/load@20.5.3':
+    resolution: {integrity: sha512-1FDZWuKyu98Myb8i7Tp31jPU2rZpOwAdYRyJcy2KoGg7Xk2A+bgHN8smhMaaNSNkmE8fwt53BokywZq8Gv/5XQ==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/message@20.4.3':
+    resolution: {integrity: sha512-6akwCYrzcrFcTYz9GyUaWlhisY4lmQ3KvrnabmhoeAV8nRH4dXJAh4+EUQ3uArtxxKQkvxJS78hNX2EU3USgxQ==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/parse@20.5.0':
+    resolution: {integrity: sha512-SeKWHBMk7YOTnnEWUhx+d1a9vHsjjuo6Uo1xRfPNfeY4bdYFasCH1dDpAv13Lyn+dDPOels+jP6D2GRZqzc5fA==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/read@20.5.0':
+    resolution: {integrity: sha512-JDEIJ2+GnWpK8QqwfmW7O42h0aycJEWNqcdkJnyzLD11nf9dW2dWLTVEa8Wtlo4IZFGLPATjR5neA5QlOvIH1w==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/resolve-extends@20.5.3':
+    resolution: {integrity: sha512-+ogW9v/u9JqpvAgTrLra/YTFo0KkjU6iNblF89pPsj4NebNc+DAWctsludwezI8YnsjBmfHpApSwcXprN/f/ew==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/rules@20.5.3':
+    resolution: {integrity: sha512-MPlMnb9D3wbszYMp+1hPtuhtPJndRo6I6yfkZVA4+jR8w7Kqp0u2u/Y+gzbaItx5Lltq5rw7FSZQWJMoXUC4NQ==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/to-lines@20.0.0':
+    resolution: {integrity: sha512-2l9gmwiCRqZNWgV+pX1X7z4yP0b3ex/86UmUFgoRt672Ez6cAM2lOQeHFRUTuE6sPpi8XBCGnd8Kh3bMoyHwJw==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/top-level@20.4.3':
+    resolution: {integrity: sha512-qD9xfP6dFg5jQ3NMrOhG0/w5y3bBUsVGyJvXxdWEwBm8hyx4WOk3kKXw28T5czBYvyeCVJgJJ6aoJZUWDpaacQ==}
+    engines: {node: '>=v18'}
+
+  '@commitlint/types@20.5.0':
+    resolution: {integrity: sha512-ZJoS8oSq2CAZEpc/YI9SulLrdiIyXeHb/OGqGrkUP6Q7YV+0ouNAa7GjqRdXeQPncHQIDz/jbCTlHScvYvO/gA==}
+    engines: {node: '>=v18'}
+
+  '@conventional-changelog/git-client@2.7.0':
+    resolution: {integrity: sha512-j7A8/LBEQ+3rugMzPXoKYzyUPpw/0CBQCyvtTR7Lmu4olG4yRC/Tfkq79Mr3yuPs0SUitlO2HwGP3gitMJnRFw==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      conventional-commits-filter: ^5.0.0
+      conventional-commits-parser: ^6.4.0
+    peerDependenciesMeta:
+      conventional-commits-filter:
+        optional: true
+      conventional-commits-parser:
+        optional: true
+
+  '@corex/deepmerge@4.0.43':
+    resolution: {integrity: sha512-N8uEMrMPL0cu/bdboEWpQYb/0i2K5Qn8eCsxzOmxSggJbbQte7ljMRoXm917AbntqTGOzdTu+vP3KOOzoC70HQ==}
+
+  '@emnapi/core@1.10.0':
+    resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==}
+
+  '@emnapi/runtime@1.10.0':
+    resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
+
+  '@emnapi/wasi-threads@1.2.1':
+    resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
+
+  '@esbuild/aix-ppc64@0.25.12':
+    resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/aix-ppc64@0.27.7':
+    resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.25.12':
+    resolution: {integrity: sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm64@0.27.7':
+    resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.25.12':
+    resolution: {integrity: sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.7':
+    resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.25.12':
+    resolution: {integrity: sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.7':
+    resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.25.12':
+    resolution: {integrity: sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-arm64@0.27.7':
+    resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.25.12':
+    resolution: {integrity: sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.7':
+    resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.25.12':
+    resolution: {integrity: sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.25.12':
+    resolution: {integrity: sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.7':
+    resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.25.12':
+    resolution: {integrity: sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm64@0.27.7':
+    resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.25.12':
+    resolution: {integrity: sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.7':
+    resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.25.12':
+    resolution: {integrity: sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.7':
+    resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.25.12':
+    resolution: {integrity: sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.7':
+    resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.25.12':
+    resolution: {integrity: sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.7':
+    resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.25.12':
+    resolution: {integrity: sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.7':
+    resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.25.12':
+    resolution: {integrity: sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.7':
+    resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.25.12':
+    resolution: {integrity: sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.7':
+    resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.25.12':
+    resolution: {integrity: sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.7':
+    resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.25.12':
+    resolution: {integrity: sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.7':
+    resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.25.12':
+    resolution: {integrity: sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.7':
+    resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.25.12':
+    resolution: {integrity: sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.25.12':
+    resolution: {integrity: sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/sunos-x64@0.27.7':
+    resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.25.12':
+    resolution: {integrity: sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-arm64@0.27.7':
+    resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.25.12':
+    resolution: {integrity: sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.7':
+    resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.25.12':
+    resolution: {integrity: sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.7':
+    resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@eslint-community/eslint-utils@4.9.1':
+    resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
+  '@eslint-community/regexpp@4.12.2':
+    resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
+    engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
+
+  '@eslint/config-array@0.21.2':
+    resolution: {integrity: sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/config-helpers@0.4.2':
+    resolution: {integrity: sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/core@0.17.0':
+    resolution: {integrity: sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/eslintrc@3.3.3':
+    resolution: {integrity: sha512-Kr+LPIUVKz2qkx1HAMH8q1q6azbqBAsXJUxBl/ODDuVPX45Z9DfwB8tPjTi6nNZ8BuM3nbJxC5zCAg5elnBUTQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/js@9.39.2':
+    resolution: {integrity: sha512-q1mjIoW1VX4IvSocvM/vbTiveKC4k9eLrajNEuSsmjymSDEbpGddtpfOoN7YGAqBK3NG+uqo8ia4PDTt8buCYA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/object-schema@2.1.7':
+    resolution: {integrity: sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/plugin-kit@0.4.1':
+    resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/react-dom@2.1.8':
+    resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@formatjs/ecma402-abstract@2.3.6':
+    resolution: {integrity: sha512-HJnTFeRM2kVFVr5gr5kH1XP6K0JcJtE7Lzvtr3FS/so5f1kpsqqqxy5JF+FRaO6H2qmcMfAUIox7AJteieRtVw==}
+
+  '@formatjs/fast-memoize@2.2.7':
+    resolution: {integrity: sha512-Yabmi9nSvyOMrlSeGGWDiH7rf3a7sIwplbvo/dlz9WCIjzIQAfy1RMf4S0X3yG724n5Ghu2GmEl5NJIV6O9sZQ==}
+
+  '@formatjs/icu-messageformat-parser@2.11.4':
+    resolution: {integrity: sha512-7kR78cRrPNB4fjGFZg3Rmj5aah8rQj9KPzuLsmcSn4ipLXQvC04keycTI1F7kJYDwIXtT2+7IDEto842CfZBtw==}
+
+  '@formatjs/icu-skeleton-parser@1.8.16':
+    resolution: {integrity: sha512-H13E9Xl+PxBd8D5/6TVUluSpxGNvFSlN/b3coUp0e0JpuWXXnQDiavIpY3NnvSp4xhEMoXyyBvVfdFX8jglOHQ==}
+
+  '@formatjs/intl-localematcher@0.6.2':
+    resolution: {integrity: sha512-XOMO2Hupl0wdd172Y06h6kLpBz6Dv+J4okPLl4LPtzbr8f66WbIoy4ev98EBuZ6ZK4h5ydTN6XneT4QVpD7cdA==}
+
+  '@fumadocs/language@0.0.1':
+    resolution: {integrity: sha512-4NRZLP2Yso6j5sCSzioXm9SY/QyeHLKVr/t8AOlvSvl6msAuBamTbRi1SpelRZDB8+4+4uJjP53trkGATQIJyQ==}
+    peerDependencies:
+      '@fumadocs/story': '*'
+      fumadocs-core: '*'
+      fumadocs-openapi: '*'
+      fumadocs-ui: '*'
+    peerDependenciesMeta:
+      '@fumadocs/story':
+        optional: true
+      fumadocs-core:
+        optional: true
+      fumadocs-openapi:
+        optional: true
+      fumadocs-ui:
+        optional: true
+
+  '@fumadocs/tailwind@0.0.5':
+    resolution: {integrity: sha512-ENKPWUDRmriccsrUDE4bDBq3FNr/ms3BP2rWlsAEMV1yP23pcCaan+ceGfeBUsAQjw7sj9Q3R4Kl3g/TCStPzQ==}
+    peerDependencies:
+      '@tailwindcss/oxide': ^4.0.0
+      tailwindcss: ^4.0.0
+    peerDependenciesMeta:
+      '@tailwindcss/oxide':
+        optional: true
+      tailwindcss:
+        optional: true
+
+  '@gravity-ui/icons@2.16.0':
+    resolution: {integrity: sha512-AMjPSO+7yPpvcCa9k+ZFNOZ+8cmIauLyRMswhoyfQ7SeoJOVzsAa2OP/B+Dd+AZRvzTaeJha4m2iEk93JvAklA==}
+    peerDependencies:
+      react: '*'
+    peerDependenciesMeta:
+      react:
+        optional: true
+
+  '@humanfs/core@0.19.2':
+    resolution: {integrity: sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/node@0.16.8':
+    resolution: {integrity: sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/types@0.15.0':
+    resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanwhocodes/module-importer@1.0.1':
+    resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==}
+    engines: {node: '>=12.22'}
+
+  '@humanwhocodes/retry@0.4.3':
+    resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
+    engines: {node: '>=18.18'}
+
+  '@iconify-json/gravity-ui@1.2.10':
+    resolution: {integrity: sha512-GpLMMrVCc1XkKuNVQ0HaA37dW2fnkWED/2zcsd288QIncv1pQ8RG/Hr/mCDgGHe4Nec/1eu9OBk6yVqqQiR5Gw==}
+
+  '@iconify/react@6.0.2':
+    resolution: {integrity: sha512-SMmC2sactfpJD427WJEDN6PMyznTFMhByK9yLW0gOTtnjzzbsi/Ke/XqsumsavFPwNiXs8jSiYeZTmLCLwO+Fg==}
+    peerDependencies:
+      react: '>=16'
+
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@img/colour@1.1.0':
+    resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
+    engines: {node: '>=18'}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
+    os: [linux]
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@internationalized/date@3.12.2':
+    resolution: {integrity: sha512-FY1Y+H64NDs+HAF6omlnWxm3mEpfgaCSWtL5l551ZZfImA+kGjPFgrnJrGjH6lfmLL0g8Z/mBu1R3kufeCp6Jw==}
+
+  '@internationalized/message@3.1.10':
+    resolution: {integrity: sha512-nc0Or6EdWHqZRcsXb6P9hBIpLsfSl/ILh0rk5h/OVBpzmhdExXtPy2cQtWsq8XKRBpRHwDNnAHt4OpolcB7dog==}
+
+  '@internationalized/number@3.6.7':
+    resolution: {integrity: sha512-3ji1fcrT+FPAK86UqEhB/psHixYo6niWPJtt7+qRaYFynt/BaJG8GhAPimtWUpEiVSTq8ZM8L5psMxGquiB/Vg==}
+
+  '@internationalized/string@3.2.9':
+    resolution: {integrity: sha512-kzP/M/mbQxODlmOt4bIQZ2SBVUWUSqMLXooXixnX7noche8WHaQcA+nwFN1K2KCF/cp+LDUhcJsCicwkvhD1pg==}
+
+  '@isaacs/fs-minipass@4.0.1':
+    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
+    engines: {node: '>=18.0.0'}
+
+  '@joshwooding/vite-plugin-react-docgen-typescript@0.6.4':
+    resolution: {integrity: sha512-6PyZBYKnnVNqOSB0YFly+62R7dmov8segT27A+RVTBVd4iAE6kbW9QBJGlyR2yG4D4ohzhZSTIu7BK1UTtmFFA==}
+    peerDependencies:
+      typescript: '>= 4.3.x'
+      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@lezer/common@1.5.2':
+    resolution: {integrity: sha512-sxQE460fPZyU3sdc8lafxiPwJHBzZRy/udNFynGQky1SePYBdhkBl1kOagA9uT3pxR8K09bOrmTUqA9wb/PjSQ==}
+
+  '@lezer/lr@1.4.10':
+    resolution: {integrity: sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==}
+
+  '@lglab/react-qr-code@1.7.0':
+    resolution: {integrity: sha512-nocFONGSsDkgCKpMEvBkOsBZc7OXih4d9TDRBMdikLnlN4p5a63i2zfs2fEnsyyF02gBfhw8rgLWpFZNOyfabQ==}
+    peerDependencies:
+      react: ^18 || ^19
+
+  '@lmdb/lmdb-darwin-arm64@2.8.5':
+    resolution: {integrity: sha512-KPDeVScZgA1oq0CiPBcOa3kHIqU+pTOwRFDIhxvmf8CTNvqdZQYp5cCKW0bUk69VygB2PuTiINFWbY78aR2pQw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@lmdb/lmdb-darwin-x64@2.8.5':
+    resolution: {integrity: sha512-w/sLhN4T7MW1nB3R/U8WK5BgQLz904wh+/SmA2jD8NnF7BLLoUgflCNxOeSPOWp8geP6nP/+VjWzZVip7rZ1ug==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@lmdb/lmdb-linux-arm64@2.8.5':
+    resolution: {integrity: sha512-vtbZRHH5UDlL01TT5jB576Zox3+hdyogvpcbvVJlmU5PdL3c5V7cj1EODdh1CHPksRl+cws/58ugEHi8bcj4Ww==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@lmdb/lmdb-linux-arm@2.8.5':
+    resolution: {integrity: sha512-c0TGMbm2M55pwTDIfkDLB6BpIsgxV4PjYck2HiOX+cy/JWiBXz32lYbarPqejKs9Flm7YVAKSILUducU9g2RVg==}
+    cpu: [arm]
+    os: [linux]
+
+  '@lmdb/lmdb-linux-x64@2.8.5':
+    resolution: {integrity: sha512-Xkc8IUx9aEhP0zvgeKy7IQ3ReX2N8N1L0WPcQwnZweWmOuKfwpS3GRIYqLtK5za/w3E60zhFfNdS+3pBZPytqQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@lmdb/lmdb-win32-x64@2.8.5':
+    resolution: {integrity: sha512-4wvrf5BgnR8RpogHhtpCPJMKBmvyZPhhUtEwMJbXh0ni2BucpfF07jlmyM11zRqQ2XIq6PbC2j7W7UCCcm1rRQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@mdx-js/mdx@3.1.1':
+    resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
+
+  '@mdx-js/react@3.1.1':
+    resolution: {integrity: sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==}
+    peerDependencies:
+      '@types/react': '>=16'
+      react: '>=16'
+
+  '@mischnic/json-sourcemap@0.1.1':
+    resolution: {integrity: sha512-iA7+tyVqfrATAIsIRWQG+a7ZLLD0VaOCKV2Wd/v4mqIU3J9c4jx9p7S0nw1XH3gJCKNBOOwACOPYYSUu9pgT+w==}
+    engines: {node: '>=12.0.0'}
+
+  '@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4':
+    resolution: {integrity: sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4':
+    resolution: {integrity: sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4':
+    resolution: {integrity: sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4':
+    resolution: {integrity: sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4':
+    resolution: {integrity: sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4':
+    resolution: {integrity: sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@napi-rs/wasm-runtime@1.1.4':
+    resolution: {integrity: sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
+  '@next/env@13.5.11':
+    resolution: {integrity: sha512-fbb2C7HChgM7CemdCY+y3N1n8pcTKdqtQLbC7/EQtPdLvlMUT9JX/dBYl8MMZAtYG4uVMyPFHXckb68q/NRwqg==}
+
+  '@next/env@16.2.6':
+    resolution: {integrity: sha512-gd8HoHN4ufj73WmR3JmVolrpJR47ILK6LouP5xElPglaVxir6e1a7VzvTvDWkOoPXT9rkkTzyCxBu4yeZfZwcw==}
+
+  '@next/eslint-plugin-next@16.1.1':
+    resolution: {integrity: sha512-Ovb/6TuLKbE1UiPcg0p39Ke3puyTCIKN9hGbNItmpQsp+WX3qrjO3WaMVSi6JHr9X1NrmthqIguVHodMJbh/dw==}
+
+  '@next/swc-darwin-arm64@16.2.6':
+    resolution: {integrity: sha512-ZJGkkcNfYgrrMkqOdZ7zoLa1TOy0qpcMfk/z4Mh/FKUz40gVO+HNQWqmLxf67Z5WB64DRp0dhEbyHfel+6sJUg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@next/swc-darwin-x64@16.2.6':
+    resolution: {integrity: sha512-v/YLBHIY132Ced3puBJ7YJKw1lqsCrgcNo2aRJlCEyQrrCeRJlvGlnmxhPxNQI3KE3N1DN5r9TPNPvka3nq5RQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    resolution: {integrity: sha512-RPOvqlYBbcQjkz9VQQDZ2T2bARIjXZV1KFlt+V2Mr6SW/e4I9fcKsaA0hdyf2FHoTlsV2xnBd5Y912rP/1Ce6w==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    resolution: {integrity: sha512-URUTu1+dMkxJsPFgm+OeEvq9wf5sujw0EvgYy80TDGHTSLTnIHeqb0Eu8A3sC95IRgjejQL+kC4mw+4yPxiAXA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    resolution: {integrity: sha512-DOj182mPV8G3UkrayLoREM5YEYI+Dk5wv7Ox9xl1fFibAELEsFD0lDPfHIeILlutMMfdyhlzYPELG3peuKaurw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    resolution: {integrity: sha512-HKQ5SP/V/ub73UvF7n/zeJlxk2kLmtL7Wzrg4WfmkjmNos5onJ2tKu7yZOPdL18A6Svfn3max29ym+ry7NkK4g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    resolution: {integrity: sha512-LZXpTlPyS5v7HhSmnvsLGP3iIYgYOBnc8r8ArlT55sGHV89bR2HlDdBjWQ+PY6SJMmk8TuVGFuxalnP3k/0Dwg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    resolution: {integrity: sha512-F0+4i0h9J6C4eE3EAPWsoCk7UW/dbzOjyzxY0qnDUOYFu6FFmdZ6l97/XdV3/Nz3VYyO7UWjyEJUXkGqcoXfMA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
+  '@nolyfill/is-core-module@1.0.39':
+    resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
+    engines: {node: '>=12.4.0'}
+
+  '@opentelemetry/api@1.9.1':
+    resolution: {integrity: sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==}
+    engines: {node: '>=8.0.0'}
+
+  '@orama/orama@3.1.18':
+    resolution: {integrity: sha512-a61ljmRVVyG5MC/698C8/FfFDw5a8LOIvyOLW5fztgUXqUpc1jOfQzOitSCbge657OgXXThmY3Tk8fpiDb4UcA==}
+    engines: {node: '>= 20.0.0'}
+
+  '@parcel/bundler-default@2.16.3':
+    resolution: {integrity: sha512-zCW2KzMfcEXqpVSU+MbLFMV3mHIzm/7UK1kT8mceuj4UwUScw7Lmjmulc2Ev4hcnwnaAFyaVkyFE5JXA4GKsLQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/cache@2.16.3':
+    resolution: {integrity: sha512-iWlbdTk9h7yTG1fxpGvftUD7rVbXVQn1+U21BGqFyYxfrd+wgdN624daIG6+eqI6yBuaBTEwH+cb3kaI9sH1ng==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/codeframe@2.16.3':
+    resolution: {integrity: sha512-oXZx8PUqExnXnAHCLhxulTDeFvTBqPAwJU4AVZwnYFToaQ6nltXWWYaDGUu2f/V3Z17LObWiOROHT7HYXAe62Q==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/compressor-raw@2.16.3':
+    resolution: {integrity: sha512-84lI0ULxvjnqDn3yHorMHj2X2g0oQsIwNFYopQWz9UWjnF7g5IU0EFgAAqMCQxKKUV6fttqaQiDDPikXLR6hHA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/config-default@2.16.3':
+    resolution: {integrity: sha512-OgB6f+EpCzjeFLoVB5qJzKy0ybB2wPK0hB2aXgD3oYCHWLny7LJOGaktY9OskSn1jfz7Tdit9zLNXOhBTMRujw==}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/core@2.16.3':
+    resolution: {integrity: sha512-b9ll4jaFYfXSv6NZAOJ2P0uuyT/Doel7ho2AHLSUz2thtcL6HEb2+qdV2f9wriVvbEoPAj9VuSOgNc0t0f5iMw==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/diagnostic@2.16.3':
+    resolution: {integrity: sha512-NBoGGFMqOmbs8i0zGVwTeU0alQ0BkEZe894zAb5jEBQqsRBPmdqogwmARsT4Ix2bN1QBco4o0gn9kBtalFC6IQ==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/error-overlay@2.16.3':
+    resolution: {integrity: sha512-JqJR4Fl5SwTmqDEuCAC8F1LmNLWpjfiJ+hGp3CoLb0/9EElRxlpkuP/SxTe2/hyXevpfn3bfvS1cn/mWhHUc3w==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/events@2.16.3':
+    resolution: {integrity: sha512-rAh/yXwtHYcKWmi9Tjjf5t95UdBVhhlyJkIYN25/PYKdSRBcQ9c1rd8/fvOeZKy1/fSiOcEXqm6dK7bhLSCaww==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/feature-flags@2.16.3':
+    resolution: {integrity: sha512-D15/cM/mAO8yv0NQ9kFBxXZ7C3A+jAq+9tVfrjYegofMk18pQoXJz6X/po2Kq1PzO7pjydn7PqYMB/O9p/+zbQ==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/fs@2.16.3':
+    resolution: {integrity: sha512-InMXHVIfDUSimjBoGJcdNlNjoIsDQ8MUDN8UJG4jnjJQ6DDor+W+yg4sw/40tToUqIyi99lVhQlpkBA+nHLpOQ==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/graph@3.6.3':
+    resolution: {integrity: sha512-3qV99HCHrPR1CnMOHkwwpmPBimVMd3d/GcEcgOHUKi+2mS0KZ4TwMs/THaIWtJx7q5jrhqEht+IyQ1Smupo49g==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/logger@2.16.3':
+    resolution: {integrity: sha512-dHUJk8dvo2wOg3dIqSjNGqlVqsRn4hTZVbgTShaImaLTWdueaKfMojxo79P7T3em49y0dQb0m+xl2SunDhtwsA==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/markdown-ansi@2.16.3':
+    resolution: {integrity: sha512-r0QQpS44jNueY8lcZcSoUua3kJfI5kDZrJvFgi1jrkyxwDUfq3L0xWQjxHrXzv8K6uFAeU+teoq8JcWLVLXa1w==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/namer-default@2.16.3':
+    resolution: {integrity: sha512-4MwRm8ZnloMdQ6sAMrTDxMiPVN1fV+UcBIrA0Fpp4kD3XLkqSAUCLnjl13+VrPelfh01irM6QnpK4JTKBqRk0A==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/node-resolver-core@3.7.3':
+    resolution: {integrity: sha512-0xdXyhGcGwtYmfWwEwzdVVGnTaADdTScx1S8IXiK0Nh3S1b4ilGqnKzw8fVsJCsBMvQA5e251EDFeG3qTnUsnw==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/optimizer-css@2.16.3':
+    resolution: {integrity: sha512-j/o9bGtu1Fe7gJYQD+/SeJ5yR7FmS6Z7e6CtTkVxjeeq0/IdR0KoZOCkJ4cRETPnm+wkyQVlY8koAAFbEEqV8w==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/optimizer-html@2.16.3':
+    resolution: {integrity: sha512-EBmjY+QRa/in05wRWiL6B/kQ1ERemdg4W9py+V2w0tJx1n6yOvtjPGvivYtU+s82rlVlx6DN3DFU13iGRt0FuQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/optimizer-image@2.16.3':
+    resolution: {integrity: sha512-PbGsDXbbWyOnkpWn3jgZxtAp8l8LNXl7DCv5Q4l1TR6k4sULjmxTTPY6+AkY6H84cAN7s5h6F8k2XeN3ygXWCA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/optimizer-svg@2.16.3':
+    resolution: {integrity: sha512-fgQhrqu5pKtEaM9G//PvBZSuCDP6ZVbGyFnePKCzqnXJ173/Y+4kUbNOrPi7wE4HupWMsJRNUf/vyCu+lXdOiQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/optimizer-swc@2.16.3':
+    resolution: {integrity: sha512-8P5Bis2SynQ6sPW1bwB6H8WK+nFF61RCKzlGnTPoh1YE36dubYqUreYYISMLFt/rG8eb+Ja78DQLPZTVP3sfQQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/package-manager@2.16.3':
+    resolution: {integrity: sha512-TySTY93SyGfu8E5YWiekumw6sm/2+LBHcpv1JWWAfNd+1b/x3WB5QcRyEk6mpnOo7ChQOfqykzUaBcrmLBGaSw==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/packager-css@2.16.3':
+    resolution: {integrity: sha512-CUwMRif1ZGBfociDt6m18L7sgafsquo0+NYRDXCTHmig3w7zm5saE4PXborfzRI/Lj3kBUkJYH//NQGITHv1Yg==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/packager-html@2.16.3':
+    resolution: {integrity: sha512-hluJXpvcW2EwmBxO/SalBiX5SIYJ7jGTkhFq5ka2wrQewFxaAOv2BVTuFjl1AAnWzjigcNhC4n0jkQUckCNW4g==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/packager-js@2.16.3':
+    resolution: {integrity: sha512-01fufzVOs9reEDq9OTUyu5Kpasd8nGvBJEUytagM6rvNlEpmlUX5HvoAzUMSTyYeFSH+1VnX6HzK6EcQNY9Y8Q==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/packager-raw@2.16.3':
+    resolution: {integrity: sha512-GCehb36D2xe8P8gftyZcjNr3XcUzBgRzWcasM4I0oPaLRZw4nuIu60cwTsGk6/HhUYDq8uPze+gr1L4pApRrjw==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/packager-svg@2.16.3':
+    resolution: {integrity: sha512-1TLmU8zcRBySOD3WXGUhTjmIurJoOMwQ3aIiyHXn4zjrl4+VPw/WnUoVGpMwUW1T7rb2/22BKPGAAxbOLDqxLQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/packager-wasm@2.16.3':
+    resolution: {integrity: sha512-RfRM/RaA4eWV+qUt7A9Vo2VlvZx50Rfs81kZ4WBhxzey2BGAvBSJWceYEUnI7JuDmrHjDMDe6y0+gLNmELeL1g==}
+    engines: {node: '>=16.0.0', parcel: ^2.16.3}
+
+  '@parcel/plugin@2.16.3':
+    resolution: {integrity: sha512-w4adN/E2MBbNzUwuGWcUkilrf7B6eQThPRdgiw2awIY0/t0C1gN/hhBfUeWt7vt0WcvWlXcyR/OGzU/r0nPteA==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/profiler@2.16.3':
+    resolution: {integrity: sha512-/4cVsLfv36fdphm+JiReeXXT3RD6258L79C2kjpD06i84sxyNPQVbFldgWRppbHW2KBR/D6XhIzHcwoDUYtTbw==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/reporter-cli@2.16.3':
+    resolution: {integrity: sha512-kIwhJy97xlgvNsUhn3efp6PxUfWCiiPG9ciDnAGBXpFmKWl63WQR6QIXNuNgrQremUTzIHJ02h6/+LyBJD4wjw==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/reporter-dev-server@2.16.3':
+    resolution: {integrity: sha512-c2YEHU3ePOSUO+JXoehn3r0ruUlP2i4xvHfwHLHI3NW/Ymlp4Gy9rWyyYve/zStfoEOyMN/vKRWKtxr6nCy9DQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/reporter-tracer@2.16.3':
+    resolution: {integrity: sha512-DqQQRQC6JKQcYo8fAC69JGri++WC9cTRZFH2QJdbcMXnmeCW0YjBwHsl65C0Q/8aO6lwVlV0P1waMPW3iQw+uA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/resolver-default@2.16.3':
+    resolution: {integrity: sha512-2bf2VRKt1fZRZbi85SBLrePr4Eid0zXUQMy+MRcFoVZ8MaxsjvWjnlxHW71cWNcRQATUOX/0w0z0Gcf7Kjrh2g==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/runtime-browser-hmr@2.16.3':
+    resolution: {integrity: sha512-dN5Kv6/BLaKAf80zogimvSPZYQRA+h+o3rKQLnxid2FilVRTCjz+FOcuMsT/EqAJXai1mKjrxtqlM9IJ4oSV1A==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/runtime-js@2.16.3':
+    resolution: {integrity: sha512-Xk1G7A0g5Dbm374V8piDbxLRQoQ1JiKIChXzQuiQ755A22JYOSP0yA2djBEuB7KWPwFKDd4f9DFTVDn6VclPaQ==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/runtime-rsc@2.16.3':
+    resolution: {integrity: sha512-QR+4BjGE2OqLcjh6WfAMrNoM0FubxvJNH9p31yjI4H1ivrvTJECanvVZ6C7QRR/30l+WAYb5USrcYJVMwHi1zg==}
+    engines: {node: '>= 12.0.0', parcel: ^2.16.3}
+
+  '@parcel/runtime-service-worker@2.16.3':
+    resolution: {integrity: sha512-O+jhRFNThRAxsHOW6RYcYR6+sA9MxeGTmbVRguFyM12OqzuXRTuuv9x2RDSGP/cgBBCpVuq5JvK8KwS2RB26Gg==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/rust-darwin-arm64@2.16.3':
+    resolution: {integrity: sha512-9JG19DDNjIpvlI1b8VYIjvCaulftd6/J09/Rj2A8KgREv6EtCDkus8jCsNw7Jacj2HIWg23kxJY3XKcJ9pkiug==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@parcel/rust-darwin-x64@2.16.3':
+    resolution: {integrity: sha512-9mG6M6SGYiCO9IfD85Bixg5udXoy2IQHCRdBoQmpNej5+FrDW1a3FeDwDzqOFtl9b7axpzPEVb7zp+WK36Rn4w==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@parcel/rust-linux-arm-gnueabihf@2.16.3':
+    resolution: {integrity: sha512-zSA1Dz5JWS28DkEMjEQNmf8qk55dR6rcKtwrw5CMg3Ndt30ugrGtRechsqEpXSYYxcDY1kmZ779LwiTUdkdCrQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@parcel/rust-linux-arm64-gnu@2.16.3':
+    resolution: {integrity: sha512-PvjO0U6qM0JjRCH2eKi3JNKgBVWDBP3VrMEUXJJM8K37ylfLTozK0f7oK2M03voCS1WjKrduRGjJNk8EZrBPow==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/rust-linux-arm64-musl@2.16.3':
+    resolution: {integrity: sha512-a4TZB9/Y/y8DQ55XZXh9bNb5yIC9CAoK2YK8g3OytauC8OrHGtIIVlF+E1UCn/FPBFr2dobYOeih/InvLKITpQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/rust-linux-x64-gnu@2.16.3':
+    resolution: {integrity: sha512-6/a/5jDcVwE0xpLSLGI9T2pclgnad0jVFRH/4Gm9yQ5fl2gpYghjg3fcCNeSjJ/aBNFKlOeKLlp/oBSlTtlkoQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/rust-linux-x64-musl@2.16.3':
+    resolution: {integrity: sha512-gTUlFvJBLR3UxNjGs076wVuFZyx+X6G6opJzBFaSG9XqLhLo+VrpqHpjCx+SCwSufDLTVq8rWJbwpvbe2EhRJg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/rust-win32-x64-msvc@2.16.3':
+    resolution: {integrity: sha512-/kyr5CL4XFJpMj9CvW8K1NNNqkzyOhxc7ibXhykiPyPiGOwO/ZbqnfDhqVx3JMSjOASeW1e6UlGNjnfTPvFkGQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@parcel/rust@2.16.3':
+    resolution: {integrity: sha512-pUsgURnDdlHA9AqvEcm124/9+DB7GM7Mk0qQ9XDNiznl09n8XZ67lf/IIvaMW7y0vQ7FpTzRIrRzAJhGyMRbMw==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      napi-wasm: ^1.1.2
+    peerDependenciesMeta:
+      napi-wasm:
+        optional: true
+
+  '@parcel/source-map@2.1.1':
+    resolution: {integrity: sha512-Ejx1P/mj+kMjQb8/y5XxDUn4reGdr+WyKYloBljpppUy8gs42T+BNoEOuRYqDVdgPc6NxduzIDoJS9pOFfV5Ew==}
+    engines: {node: ^12.18.3 || >=14}
+
+  '@parcel/transformer-babel@2.16.3':
+    resolution: {integrity: sha512-Jsusa2xWlgrmBYmvuC70/SIvcNdYZj3NyQhCxTOARV2scksSKH8iSvNsMKepYiZl6nHRNOmnGOShz9xJqNpUDw==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-css@2.16.3':
+    resolution: {integrity: sha512-RKGfjvQQVYpd27Ag7QHzBEjqfN/hj6Yf6IlbUdOp06bo+XOXQXe5/n2ulJ1EL9ZjyDOtXbB94A7QzSQmtFGEow==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-html@2.16.3':
+    resolution: {integrity: sha512-j/f+fR3hS9g3Kw4mySyF2sN4mp0t6amq3x52SAptpa4C7w8XVWproc+3ZLgjzi91OPqNeQAQUNQMy86AfuMuEw==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-image@2.16.3':
+    resolution: {integrity: sha512-q8BhaGSaGtIP1JPxDpRoRxs5Oa17sVR4c0kyPyxwP0QoihKth1eQElbINx+7Ikbt7LoGucPUKEsnxrDzkUt8og==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/transformer-js@2.16.3':
+    resolution: {integrity: sha512-k83yElHagwDRYfza7BrADdf9NRGpizX3zOfctfEsQWh9mEZLNJENivP6ZLB9Aje9H0GaaSTiYU8VwOWLXbLgOw==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@parcel/transformer-json@2.16.3':
+    resolution: {integrity: sha512-iT4IKGT95+S/7RBK1MUY/KxD8ad9FUlElF+w40NBLv4lm012wkYogFRhEHnyElPOByZL1aJ8GaVOGbZL9yuZfg==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-node@2.16.3':
+    resolution: {integrity: sha512-FIbSphLisxmzwqE43ALsGeSPSYBA3ZE6xmhAIgwoFdeI6VfTSkCZnGhSqUhP3m9R55IuWm/+NP6BlePWADmkwg==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-postcss@2.16.3':
+    resolution: {integrity: sha512-OMjU17OwPhPBK2LIzqQozBezolqI8jPgoT+CmoOkKr1GlgWMzCcHFpW6KQZxVVR+vI0lUEJp+RZc9MzhNndv4A==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-posthtml@2.16.3':
+    resolution: {integrity: sha512-y3iuM+yp8nPbt8sbQayPGR0saVGR6uj0aYr7hWoS0oUe9vZsH1mP3BTP6L6ABe/dZKU3QcFmMQgLwH6WC/apAA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-raw@2.16.3':
+    resolution: {integrity: sha512-Lha1+z75QbNAsxMAffp5K+ykGXEYSNOFUqI/8XtetYfuqIvS5s/OBkwsg8MWbjtPkbKo1F3EwNBaIAagw/BbIg==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-react-refresh-wrap@2.16.3':
+    resolution: {integrity: sha512-8rzO5iKF5bYrPUnbw4At0H7AwE+UHkuNNo385JL0VzXggrA0VsXsjjJwXVyhSeMvEbo2ioo/+nYUlazTQBABwA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/transformer-svg@2.16.3':
+    resolution: {integrity: sha512-fDpUWSBZxt/R5pZUNd4gV/BX0c7B074lw/wmqwowjcwQU/QxhzPJBDlAsyTvOJ75PeJiQf/qFtnIK5bNwMoasA==}
+    engines: {node: '>= 16.0.0', parcel: ^2.16.3}
+
+  '@parcel/types-internal@2.16.3':
+    resolution: {integrity: sha512-zi2GKdJHpNeW9sspTBfM68A9lekEztTWU8Dxs1ouPk90lfA0tfrMznAvkD5iJdKsM6usbgcqjjI8s+Ow8OrsBg==}
+
+  '@parcel/types@2.16.3':
+    resolution: {integrity: sha512-aIJJFMif/A7u86UEt3sJPZ/F7suQW56ugiCp2Y2mYTPHpTJbI2Knk9yO4fkWHNO1BrH6a/VUWh7bWIOsQtzL1Q==}
+
+  '@parcel/utils@2.16.3':
+    resolution: {integrity: sha512-g/yqVWSdZqPvTiS96dEK9MEl7q6w31u+luD5VGt6f9w6PQCpuVajhhDNuXf9uzDU/dL4sSZPKUhLteVZDqryHA==}
+    engines: {node: '>= 16.0.0'}
+
+  '@parcel/watcher-android-arm64@2.5.6':
+    resolution: {integrity: sha512-YQxSS34tPF/6ZG7r/Ih9xy+kP/WwediEUsqmtf0cuCV5TPPKw/PQHRhueUo6JdeFJaqV3pyjm0GdYjZotbRt/A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  '@parcel/watcher-darwin-arm64@2.5.6':
+    resolution: {integrity: sha512-Z2ZdrnwyXvvvdtRHLmM4knydIdU9adO3D4n/0cVipF3rRiwP+3/sfzpAwA/qKFL6i1ModaabkU7IbpeMBgiVEA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@parcel/watcher-darwin-x64@2.5.6':
+    resolution: {integrity: sha512-HgvOf3W9dhithcwOWX9uDZyn1lW9R+7tPZ4sug+NGrGIo4Rk1hAXLEbcH1TQSqxts0NYXXlOWqVpvS1SFS4fRg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@parcel/watcher-freebsd-x64@2.5.6':
+    resolution: {integrity: sha512-vJVi8yd/qzJxEKHkeemh7w3YAn6RJCtYlE4HPMoVnCpIXEzSrxErBW5SJBgKLbXU3WdIpkjBTeUNtyBVn8TRng==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@parcel/watcher-linux-arm-glibc@2.5.6':
+    resolution: {integrity: sha512-9JiYfB6h6BgV50CCfasfLf/uvOcJskMSwcdH1PHH9rvS1IrNy8zad6IUVPVUfmXr+u+Km9IxcfMLzgdOudz9EQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm-musl@2.5.6':
+    resolution: {integrity: sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm64-glibc@2.5.6':
+    resolution: {integrity: sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm64-musl@2.5.6':
+    resolution: {integrity: sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/watcher-linux-x64-glibc@2.5.6':
+    resolution: {integrity: sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/watcher-linux-x64-musl@2.5.6':
+    resolution: {integrity: sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/watcher-win32-arm64@2.5.6':
+    resolution: {integrity: sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@parcel/watcher-win32-ia32@2.5.6':
+    resolution: {integrity: sha512-k35yLp1ZMwwee3Ez/pxBi5cf4AoBKYXj00CZ80jUz5h8prpiaQsiRPKQMxoLstNuqe2vR4RNPEAEcjEFzhEz/g==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@parcel/watcher-win32-x64@2.5.6':
+    resolution: {integrity: sha512-hbQlYcCq5dlAX9Qx+kFb0FHue6vbjlf0FrNzSKdYK2APUf7tGfGxQCk2ihEREmbR6ZMc0MVAD5RIX/41gpUzTw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  '@parcel/watcher@2.5.6':
+    resolution: {integrity: sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==}
+    engines: {node: '>= 10.0.0'}
+
+  '@parcel/workers@2.16.3':
+    resolution: {integrity: sha512-SxIXRnrlQFhw377wxWC5WIl1FL1Y9IedhUtuc7j3uac3tlbCQJJ+3rFr5/BDUknJbTktvVsPakE98fH7TIJyyw==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      '@parcel/core': ^2.16.3
+
+  '@pivanov/utils@0.0.2':
+    resolution: {integrity: sha512-q9CN0bFWxWgMY5hVVYyBgez1jGiLBa6I+LkG37ycylPhFvEGOOeaADGtUSu46CaZasPnlY8fCdVJZmrgKb1EPA==}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  '@pkgr/core@0.3.6':
+    resolution: {integrity: sha512-SEeaJLb3qBNF/OaXnaR1NmmBbFYk1zC0ZH/52fATcRPLFg/p791YrcyFFy44Bo9sLaGuSuLp5Q6axbb/O+v/RA==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+
+  '@posthog/core@1.9.1':
+    resolution: {integrity: sha512-kRb1ch2dhQjsAapZmu6V66551IF2LnCbc1rnrQqnR7ArooVyJN9KOPXre16AJ3ObJz2eTfuP7x25BMyS2Y5Exw==}
+
+  '@preact/signals-core@1.14.2':
+    resolution: {integrity: sha512-RZHdBj9ZF4n40Rp4jS052EHHjBWf96P9oNdXPfhQTovCuWY9iQn3Gq+gOTJSgBO9A/JBuPfMOWsSX/lIU9Pc/A==}
+
+  '@preact/signals@1.3.4':
+    resolution: {integrity: sha512-TPMkStdT0QpSc8FpB63aOwXoSiZyIrPsP9Uj347KopdS6olZdAYeeird/5FZv/M1Yc1ge5qstub2o8VDbvkT4g==}
+    peerDependencies:
+      preact: 10.x
+
+  '@quansync/fs@1.0.0':
+    resolution: {integrity: sha512-4TJ3DFtlf1L5LDMaM6CanJ/0lckGNtJcMjQ1NAV6zDmA0tEHKZtxNKin8EgPaVX1YzljbxckyT2tJrpQKAtngQ==}
+
+  '@radix-ui/number@1.1.2':
+    resolution: {integrity: sha512-ceTwaxc4I5IOi97DgCotl3pqiyRGvffcc0oOsE2dQYaJOFIDsDt4VWG6xEbg1QePv9QWausCEIppud/tJ1wNig==}
+
+  '@radix-ui/primitive@1.1.4':
+    resolution: {integrity: sha512-7AdCK9PQyiljKoBDbN8OuctCbd/esdwZPQ8RtOE3SsyQtUpiPb+ND75q0jEhC1m1ecBI0MFNeLJvwIh9iKHRcQ==}
+
+  '@radix-ui/react-accordion@1.2.13':
+    resolution: {integrity: sha512-xITxBB2p5m5tAe7M0F95kb4uAh7jSIKGlExMEm93HlW+XxZHV2eXFbPWLktd4JhRiwcnXNbO7iekcrbZy6ZCvA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-arrow@1.1.9':
+    resolution: {integrity: sha512-yqHW5WQ/cTpU/un7dqqIKNy2iRU8BC0JB78PEzTfCCYvZu1U6W9KwObAniMk9nhSfyotKPQTYaUD/HB0f5muig==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-avatar@1.1.11':
+    resolution: {integrity: sha512-0Qk603AHGV28BOBO34p7IgD5m+V5Sg/YovfayABkoDDBM5d3NCx0Mp4gGrjzLGes1jV5eNOE1r3itqOR33VC6Q==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collapsible@1.1.13':
+    resolution: {integrity: sha512-F0s8+p2XNpfc3k02zBfB0jPWbkHVG162+p7BdUMyJ2308QMqZ+oaclX+FAzKFovgL5OqRU+Rvy6f/vbdlJVaqA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collection@1.1.9':
+    resolution: {integrity: sha512-zuSVi7ziP7uQRqc+yGxsKJfNkdyHv3ZKDaHe0gzg4dRgws96TPKWIiz84tVHP4GEcEl8bC0mdt17NkcxaJHmaQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-compose-refs@1.1.2':
+    resolution: {integrity: sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-compose-refs@1.1.3':
+    resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context@1.1.3':
+    resolution: {integrity: sha512-ieIFACdMpYfMEjF0rEf5KLvfVyIkOz6PDGyNnP+u+4xQ6jny3VCgA4OgXOwNx2aUkxn8zx9fiVcM8CfFYv9Lxw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context@1.1.4':
+    resolution: {integrity: sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.1.16':
+    resolution: {integrity: sha512-l9ok83YBclEZhbjgzt76Hw733e6cvRKPNgO6GJ/IETlufXG9p+fRu2wlvpImQvR6xdJ8h7J8J2DBvsPEiEsKMw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-direction@1.1.2':
+    resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.12':
+    resolution: {integrity: sha512-MhoruH6xEzsbvOmo4TNgMfmtvRGyDZw4MDSdf4ybMHfezjqwzv6hyd4lsMzBp8K9Sn6sGzCF62x1I7BYUECXOg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.4':
+    resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.1.9':
+    resolution: {integrity: sha512-9Se8t+Zry+1rEOL7Y6l/4ANYU/TOtAtf8O2fKdwLltcaMcm6kOqYGbzO4tMFQ0bvzO920pRAoHpFZ4W85S3keQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.2':
+    resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-navigation-menu@1.2.15':
+    resolution: {integrity: sha512-/fS8hKCcRt4DwCGa5QIB3juRXmfYSOk4a2AEe/BDIyy7Hm+eje2Y13oUx5zejl+wFt1owrM7E8NWlbaEl5EGpg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popover@1.1.16':
+    resolution: {integrity: sha512-8brVpAU5Uq7Bh0c8EFc4ZTf2JJTYn0o+1L+CUJB3UYIOkTjKGMgoHvduylrahdmNlr3DfH0rFq2DrbNZXgaspw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popper@1.3.0':
+    resolution: {integrity: sha512-9PB589e1aWZbrlFUHdz6WiPCL+xLZHQFX7oibqG/6Q0SwOkxDyQX9W/cyPa+sAPPKuC8cpLCpRczE5a/1DiwVQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.11':
+    resolution: {integrity: sha512-UEytdjgEh2tJGgD/gZK4FUx6t1rNIlM3U0DENhSrG7I75FGm1DnaDuVUWF1pWAWUwGmn1sCJ1VGHn8LhN1aTOw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.6':
+    resolution: {integrity: sha512-zdTk4PlUO0E18HnZ3wYbW0KkJJxWCdiNYp6g6X1PtONFhxVkg01vliTJAmwIszU6mHiyBOoW9P0rAugl5/hULQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.4':
+    resolution: {integrity: sha512-9hQc4+GNVtJAIEPEqlYqW5RiYdrr8ea5XQ0ZOnD6fgru+83kqT15mq2OCcbe8KnjRZl5vF3ks69AKz3kh1jrhg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.5':
+    resolution: {integrity: sha512-zifXeB8Y88qCYx8PLZ5oQb32KwZub+s925mMoZsBBq9KUQqWKkREubTfs6ASjRPPBe7Jt9O8OHH89+95VG+grA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-roving-focus@1.1.12':
+    resolution: {integrity: sha512-FvgPt1bRmg8Xt2QpF7NUZW3dE0ZQHGm41dAdgT2J2GJPoIXz+9Em3NobAxf4fupcxhgHu03E5CRiU2MWvObXyg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-scroll-area@1.2.11':
+    resolution: {integrity: sha512-DS39ziOgea75U/TrXKU2/oKp0be2jrDHnzFLvahg/0iNAT1Zq16e4Uw0WXwyXvsK+mG3BRyMb7A3NRZMDuEXtQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.2.4':
+    resolution: {integrity: sha512-Jl+bCv8HxKnlTLVrcDE8zTMJ09R9/ukw4qBs/oZClOfoQk/cOTbDn+NceXfV7j09YPVQUryJPHurafcSg6EVKA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-slot@1.2.5':
+    resolution: {integrity: sha512-rCMO3QsIVKv5JTY5CVbo2MvO77SpEqqYc8AvRE7OWqRDOIqAKjsp+DrmnY9uc8NPdxB5E2z47HTYGeE2+NTptg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-tabs@1.1.14':
+    resolution: {integrity: sha512-D5jwp9JNuwDeCw3CYD2Fz+sSHo0droQjC8u75dJHe4aWr5q6yBiXZU+hurXnKudRgEpUkD5TsI6bjHPo5ThUxA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.1':
+    resolution: {integrity: sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.2':
+    resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.3':
+    resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.3':
+    resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-escape-keydown@1.1.2':
+    resolution: {integrity: sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-is-hydrated@0.1.0':
+    resolution: {integrity: sha512-U+UORVEq+cTnRIaostJv9AGdV3G6Y+zbVd+12e18jQ5A3c0xL03IhnHuiU4UV69wolOQp5GfR58NW/EgdQhwOA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.1':
+    resolution: {integrity: sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.2':
+    resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-previous@1.1.2':
+    resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-rect@1.1.2':
+    resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-size@1.1.2':
+    resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-visually-hidden@1.2.5':
+    resolution: {integrity: sha512-tPcHNI3FajdDBFpl/Ez1m2WL0ufJqBKyHxMDBvKitopamK36WwBGOMicuMEZKkM5Wce41QxUyv6BsiqfrWBiGg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/rect@1.1.2':
+    resolution: {integrity: sha512-xnXE7wG13PI+cxieVssYXlQJuYVRhH9NBoxt3KNwzghDIA69GMm7d4wXRouHIYjE+KvS6U/MsMO73NdS2MH9ZA==}
+
+  '@react-aria/color@3.2.1':
+    resolution: {integrity: sha512-v/pZh1yBNeayQ5Kio0xRIX0gBf6uu+KjCRW4QSydTyRpmhvk6sMzHT9i9/vIMdaDHaYHBXlXF+Tp/mvS9CG4Zw==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-aria/i18n@3.13.1':
+    resolution: {integrity: sha512-z56ZYcbfpNmMyiGLhyEjytpmEfoTlBaksk84q4kds3HvNkf7QWKj+DJVfVDrJX+c1LyuBsszLSX7yxJRiHsYKQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-aria/overlays@3.32.1':
+    resolution: {integrity: sha512-jjVLcEK5qaGsz3SmW+eLV3QFiJzdDFzgNofPwvzBS1KTPox0a2x5u1ITUPmHwyUNiyexy531h5eVjN3tULEzHQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-aria/ssr@3.10.1':
+    resolution: {integrity: sha512-jn038/ZYmu6DpfXJ6r2U9zFFppjbc9wnApPJSCxao2RZVEqep4YyoniHSy8qv6V21/xyS4IV7W9a+X2jOjSuag==}
+    engines: {node: '>= 12'}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-aria/utils@3.34.1':
+    resolution: {integrity: sha512-H6+rGZL+0f58bBNaUMfctEnT+NogqwAk+nHiB8sR3K+YlQ37GTuCijy2U/pPvQtFMS5mURrjZeBH5JNNXsx14A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-spectrum/color@3.2.1':
+    resolution: {integrity: sha512-FbB+GaVufsN+obNJmUAe8XGZTeJjEWvEf/k/7nxDxoDCBdg/o6eEPONAZyID5Dj1f8BZKNym8VURxDZx7IIyuQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-spectrum/provider@3.11.1':
+    resolution: {integrity: sha512-TsoNdVdmlQ7L+75ILq5Yb3+wp/I1AtIeat0o+Y+ZBxP+TtWpwT1ZtCB5l3cplFVzHzOpZlzO0VaDrDP9ElGYDw==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-stately/color@3.10.1':
+    resolution: {integrity: sha512-v4YlLa/oRQpPa/M9Yq1e0Bl8Z7xzGZdNDAIbfIMZuiJtacaOKriPW+AOgjjT/Ab0fNX2YDbwIYvkiMOJBnTi5A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-stately/data@3.16.1':
+    resolution: {integrity: sha512-pHLN4kry+t2fd3N8GgGM4It0y4hMPWhSxcrnetGmrgTPJPEzBZmvZcCkJaIny0XaH+7SBlQ5oKvTnP/L8SeNbA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-stately/utils@3.12.1':
+    resolution: {integrity: sha512-NqKfzrknpfwiewx7R2vk1P+CneClInPDsIhw15+jOcUYSEfej0nta4cJywuKQJ2gsPwqX/ojDNixedCve9FWGw==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-types/color@3.2.0':
+    resolution: {integrity: sha512-beV3vz80nzZ1EuYUM7296Kyi3AHcMrbQw0qub/9yzHWVTKKc5sy/e4dCMKcWL/ArkeAyc7jDOiui190RQ4l0Fw==}
+    peerDependencies:
+      '@react-spectrum/provider': ^3.0.0
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-types/shared@3.36.0':
+    resolution: {integrity: sha512-DkP/H0C2YjjS7gZWKNqOmU8a16qHPjQNdzMwmTq9SzplM6Iw0kVMTZ0OIoe6FOgGqa+FwMsE2QbPjh/n3g/jXQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@resvg/resvg-wasm@2.4.0':
+    resolution: {integrity: sha512-C7c51Nn4yTxXFKvgh2txJFNweaVcfUPQxwEUFw4aWsCmfiBDJsTSwviIF8EcwjQ6k8bPyMWCl1vw4BdxE569Cg==}
+    engines: {node: '>= 10'}
+
+  '@rolldown/pluginutils@1.0.0-beta.53':
+    resolution: {integrity: sha512-vENRlFU4YbrwVqNDZ7fLvy+JR1CRkyr01jhSiDpE1u6py3OMzQfztQU2jxykW3ALNxO4kSlqIDeYyD0Y9RcQeQ==}
+
+  '@rollup/plugin-babel@6.1.0':
+    resolution: {integrity: sha512-dFZNuFD2YRcoomP4oYf+DvQNSUA9ih+A3vUqopQx5EdtPGo3WBnQcI/S8pwpz91UsGfL0HsMSOlaMld8HrbubA==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+      '@types/babel__core': ^7.1.9
+      rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0
+    peerDependenciesMeta:
+      '@types/babel__core':
+        optional: true
+      rollup:
+        optional: true
+
+  '@rollup/plugin-commonjs@29.0.0':
+    resolution: {integrity: sha512-U2YHaxR2cU/yAiwKJtJRhnyLk7cifnQw0zUpISsocBDoHDJn+HTV74ABqnwr5bEgWUwFZC9oFL6wLe21lHu5eQ==}
+    engines: {node: '>=16.0.0 || 14 >= 14.17'}
+    peerDependencies:
+      rollup: ^2.68.0||^3.0.0||^4.0.0
+    peerDependenciesMeta:
+      rollup:
+        optional: true
+
+  '@rollup/plugin-node-resolve@16.0.3':
+    resolution: {integrity: sha512-lUYM3UBGuM93CnMPG1YocWu7X802BrNF3jW2zny5gQyLQgRFJhV1Sq0Zi74+dh/6NBx1DxFC4b4GXg9wUCG5Qg==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      rollup: ^2.78.0||^3.0.0||^4.0.0
+    peerDependenciesMeta:
+      rollup:
+        optional: true
+
+  '@rollup/plugin-typescript@12.3.0':
+    resolution: {integrity: sha512-7DP0/p7y3t67+NabT9f8oTBFE6gGkto4SA6Np2oudYmZE/m1dt8RB0SjL1msMxFpLo631qjRCcBlAbq1ml/Big==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      rollup: ^2.14.0||^3.0.0||^4.0.0
+      tslib: '*'
+      typescript: '>=3.7.0'
+    peerDependenciesMeta:
+      rollup:
+        optional: true
+      tslib:
+        optional: true
+
+  '@rollup/pluginutils@5.4.0':
+    resolution: {integrity: sha512-MfPp06CjRLfXQ3wY0R8vJDYBy/MvVcc9OulEfR0B8Iv9ko+GCNaRZ+EpJYFl27LhKsZK0o420sYCRHCjfCgeUg==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0
+    peerDependenciesMeta:
+      rollup:
+        optional: true
+
+  '@rollup/rollup-android-arm-eabi@4.54.0':
+    resolution: {integrity: sha512-OywsdRHrFvCdvsewAInDKCNyR3laPA2mc9bRYJ6LBp5IyvF3fvXbbNR0bSzHlZVFtn6E0xw2oZlyjg4rKCVcng==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.54.0':
+    resolution: {integrity: sha512-Skx39Uv+u7H224Af+bDgNinitlmHyQX1K/atIA32JP3JQw6hVODX5tkbi2zof/E69M1qH2UoN3Xdxgs90mmNYw==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.54.0':
+    resolution: {integrity: sha512-k43D4qta/+6Fq+nCDhhv9yP2HdeKeP56QrUUTW7E6PhZP1US6NDqpJj4MY0jBHlJivVJD5P8NxrjuobZBJTCRw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.54.0':
+    resolution: {integrity: sha512-cOo7biqwkpawslEfox5Vs8/qj83M/aZCSSNIWpVzfU2CYHa2G3P1UN5WF01RdTHSgCkri7XOlTdtk17BezlV3A==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.54.0':
+    resolution: {integrity: sha512-miSvuFkmvFbgJ1BevMa4CPCFt5MPGw094knM64W9I0giUIMMmRYcGW/JWZDriaw/k1kOBtsWh1z6nIFV1vPNtA==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.54.0':
+    resolution: {integrity: sha512-KGXIs55+b/ZfZsq9aR026tmr/+7tq6VG6MsnrvF4H8VhwflTIuYh+LFUlIsRdQSgrgmtM3fVATzEAj4hBQlaqQ==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.54.0':
+    resolution: {integrity: sha512-EHMUcDwhtdRGlXZsGSIuXSYwD5kOT9NVnx9sqzYiwAc91wfYOE1g1djOEDseZJKKqtHAHGwnGPQu3kytmfaXLQ==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.54.0':
+    resolution: {integrity: sha512-+pBrqEjaakN2ySv5RVrj/qLytYhPKEUwk+e3SFU5jTLHIcAtqh2rLrd/OkbNuHJpsBgxsD8ccJt5ga/SeG0JmA==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-gnu@4.54.0':
+    resolution: {integrity: sha512-NSqc7rE9wuUaRBsBp5ckQ5CVz5aIRKCwsoa6WMF7G01sX3/qHUw/z4pv+D+ahL1EIKy6Enpcnz1RY8pf7bjwng==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-musl@4.54.0':
+    resolution: {integrity: sha512-gr5vDbg3Bakga5kbdpqx81m2n9IX8M6gIMlQQIXiLTNeQW6CucvuInJ91EuCJ/JYvc+rcLLsDFcfAD1K7fMofg==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-gnu@4.54.0':
+    resolution: {integrity: sha512-gsrtB1NA3ZYj2vq0Rzkylo9ylCtW/PhpLEivlgWe0bpgtX5+9j9EZa0wtZiCjgu6zmSeZWyI/e2YRX1URozpIw==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.54.0':
+    resolution: {integrity: sha512-y3qNOfTBStmFNq+t4s7Tmc9hW2ENtPg8FeUD/VShI7rKxNW7O4fFeaYbMsd3tpFlIg1Q8IapFgy7Q9i2BqeBvA==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.54.0':
+    resolution: {integrity: sha512-89sepv7h2lIVPsFma8iwmccN7Yjjtgz0Rj/Ou6fEqg3HDhpCa+Et+YSufy27i6b0Wav69Qv4WBNl3Rs6pwhebQ==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-musl@4.54.0':
+    resolution: {integrity: sha512-ZcU77ieh0M2Q8Ur7D5X7KvK+UxbXeDHwiOt/CPSBTI1fBmeDMivW0dPkdqkT4rOgDjrDDBUed9x4EgraIKoR2A==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-s390x-gnu@4.54.0':
+    resolution: {integrity: sha512-2AdWy5RdDF5+4YfG/YesGDDtbyJlC9LHmL6rZw6FurBJ5n4vFGupsOBGfwMRjBYH7qRQowT8D/U4LoSvVwOhSQ==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-gnu@4.54.0':
+    resolution: {integrity: sha512-WGt5J8Ij/rvyqpFexxk3ffKqqbLf9AqrTBbWDk7ApGUzaIs6V+s2s84kAxklFwmMF/vBNGrVdYgbblCOFFezMQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-musl@4.54.0':
+    resolution: {integrity: sha512-JzQmb38ATzHjxlPHuTH6tE7ojnMKM2kYNzt44LO/jJi8BpceEC8QuXYA908n8r3CNuG/B3BV8VR3Hi1rYtmPiw==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-openharmony-arm64@4.54.0':
+    resolution: {integrity: sha512-huT3fd0iC7jigGh7n3q/+lfPcXxBi+om/Rs3yiFxjvSxbSB6aohDFXbWvlspaqjeOh+hx7DDHS+5Es5qRkWkZg==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.54.0':
+    resolution: {integrity: sha512-c2V0W1bsKIKfbLMBu/WGBz6Yci8nJ/ZJdheE0EwB73N3MvHYKiKGs3mVilX4Gs70eGeDaMqEob25Tw2Gb9Nqyw==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.54.0':
+    resolution: {integrity: sha512-woEHgqQqDCkAzrDhvDipnSirm5vxUXtSKDYTVpZG3nUdW/VVB5VdCYA2iReSj/u3yCZzXID4kuKG7OynPnB3WQ==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.54.0':
+    resolution: {integrity: sha512-dzAc53LOuFvHwbCEOS0rPbXp6SIhAf2txMP5p6mGyOXXw5mWY8NGGbPMPrs4P1WItkfApDathBj/NzMLUZ9rtQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.54.0':
+    resolution: {integrity: sha512-hYT5d3YNdSh3mbCU1gwQyPgQd3T2ne0A3KG8KSBdav5TiBg6eInVmV+TeR5uHufiIgSFg0XsOWGW5/RhNcSvPg==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rtsao/scc@1.1.0':
+    resolution: {integrity: sha512-zt6OdqaDoOnJ1ZYsCYGt9YmWzDXl4vQdKTyJev62gFhRGKdx7mcT54V9KIjg+d2wi9EXsPvAPKe7i7WjfVWB8g==}
+
+  '@shikijs/core@3.20.0':
+    resolution: {integrity: sha512-f2ED7HYV4JEk827mtMDwe/yQ25pRiXZmtHjWF8uzZKuKiEsJR7Ce1nuQ+HhV9FzDcbIo4ObBCD9GPTzNuy9S1g==}
+
+  '@shikijs/engine-javascript@3.20.0':
+    resolution: {integrity: sha512-OFx8fHAZuk7I42Z9YAdZ95To6jDePQ9Rnfbw9uSRTSbBhYBp1kEOKv/3jOimcj3VRUKusDYM6DswLauwfhboLg==}
+
+  '@shikijs/engine-oniguruma@3.20.0':
+    resolution: {integrity: sha512-Yx3gy7xLzM0ZOjqoxciHjA7dAt5tyzJE3L4uQoM83agahy+PlW244XJSrmJRSBvGYELDhYXPacD4R/cauV5bzQ==}
+
+  '@shikijs/langs@3.20.0':
+    resolution: {integrity: sha512-le+bssCxcSHrygCWuOrYJHvjus6zhQ2K7q/0mgjiffRbkhM4o1EWu2m+29l0yEsHDbWaWPNnDUTRVVBvBBeKaA==}
+
+  '@shikijs/themes@3.20.0':
+    resolution: {integrity: sha512-U1NSU7Sl26Q7ErRvJUouArxfM2euWqq1xaSrbqMu2iqa+tSp0D1Yah8216sDYbdDHw4C8b75UpE65eWorm2erQ==}
+
+  '@shikijs/types@3.20.0':
+    resolution: {integrity: sha512-lhYAATn10nkZcBQ0BlzSbJA3wcmL5MXUUF8d2Zzon6saZDlToKaiRX60n2+ZaHJCmXEcZRWNzn+k9vplr8Jhsw==}
+
+  '@shikijs/vscode-textmate@10.0.2':
+    resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+
+  '@shuding/opentype.js@1.4.0-beta.0':
+    resolution: {integrity: sha512-3NgmNyH3l/Hv6EvsWJbsvpcpUba6R8IREQ83nH83cyakCw7uM1arZKNfHwv1Wz6jgqrF/j4x5ELvR6PnK9nTcA==}
+    engines: {node: '>= 8.0.0'}
+    hasBin: true
+
+  '@simple-libs/child-process-utils@1.0.2':
+    resolution: {integrity: sha512-/4R8QKnd/8agJynkNdJmNw2MBxuFTRcNFnE5Sg/G+jkSsV8/UBgULMzhizWWW42p8L5H7flImV2ATi79Ove2Tw==}
+    engines: {node: '>=18'}
+
+  '@simple-libs/stream-utils@1.2.0':
+    resolution: {integrity: sha512-KxXvfapcixpz6rVEB6HPjOUZT22yN6v0vI0urQSk1L8MlEWPDFCZkhw2xmkyoTGYeFw7tWTZd7e3lVzRZRN/EA==}
+    engines: {node: '>=18'}
+
+  '@spectrum-icons/ui@3.7.1':
+    resolution: {integrity: sha512-veQymocUYo5OciXQajSailOdbWe+k6+2ehfF8D4d0V923D4xOUadtT253xXZ5vEQjPat6Kyp2WDKeQNjd7kL1w==}
+    peerDependencies:
+      '@adobe/react-spectrum': ^3.47.0
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@spectrum-icons/workflow@4.3.1':
+    resolution: {integrity: sha512-kDF+/EbFVyLGytotqqdYt4uSij4j/PQmDQO5km/C6DyzKjyuic3FnSBFinR+mA6oFv1OjMcLvrrDBqK3wbqRlA==}
+    peerDependencies:
+      '@adobe/react-spectrum': ^3.47.0
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@standard-schema/spec@1.0.0':
+    resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}
+
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
+  '@storybook/addon-a11y@10.1.10':
+    resolution: {integrity: sha512-lXVFywCSdA39uCR0KEFz3F6WTjzoqSi5gQYtWrFelzaUiMH46uBLHPYaKlpUuNbTL/o9ctrhX1YNzegujrXSoQ==}
+    peerDependencies:
+      storybook: ^10.1.10
+
+  '@storybook/addon-docs@10.1.10':
+    resolution: {integrity: sha512-PSJVtawnGNrEkeLJQn9TTdeqrtDij8onvmnFtfkDaFG5IaUdQaLX9ibJ4gfxYakq+BEtlCcYiWErNJcqDrDluQ==}
+    peerDependencies:
+      storybook: ^10.1.10
+
+  '@storybook/builder-vite@10.1.10':
+    resolution: {integrity: sha512-6m6zOyDhHLynv3lvkH70s1YoIkIFPhbpGsBKvHchRLrZLe8hCPeafIFLfZRPoD4yIPwBS6rWbjMsSvBMFlR+ag==}
+    peerDependencies:
+      storybook: ^10.1.10
+      vite: ^5.0.0 || ^6.0.0 || ^7.0.0
+
+  '@storybook/csf-plugin@10.1.10':
+    resolution: {integrity: sha512-2dri4TRU8uuj/skmx/ZBw+GnnXf8EZHiMDMeijVRdBQtYFWPeoYzNIrGRpNfbuGpnDP0dcxrqti/TsedoxwFkA==}
+    peerDependencies:
+      esbuild: '*'
+      rollup: '*'
+      storybook: ^10.1.10
+      vite: '*'
+      webpack: '*'
+    peerDependenciesMeta:
+      esbuild:
+        optional: true
+      rollup:
+        optional: true
+      vite:
+        optional: true
+      webpack:
+        optional: true
+
+  '@storybook/global@5.0.0':
+    resolution: {integrity: sha512-FcOqPAXACP0I3oJ/ws6/rrPT9WGhu915Cg8D02a9YxLo0DE9zI+a9A5gRGvmQ09fiWPukqI8ZAEoQEdWUKMQdQ==}
+
+  '@storybook/icons@2.0.1':
+    resolution: {integrity: sha512-/smVjw88yK3CKsiuR71vNgWQ9+NuY2L+e8X7IMrFjexjm6ZR8ULrV2DRkTA61aV6ryefslzHEGDInGpnNeIocg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@storybook/react-dom-shim@10.1.10':
+    resolution: {integrity: sha512-9pmUbEr1MeMHg9TG0c2jVUfHWr2AA86vqZGphY/nT6mbe/rGyWtBl5EnFLrz6WpI8mo3h+Kxs6p2oiuIYieRtw==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      storybook: ^10.1.10
+
+  '@storybook/react-vite@10.1.10':
+    resolution: {integrity: sha512-6kE4/88YuwO07P0DR6caKNDNvCB/VnpimPmj4Jv6qmqrBgnoOOiXHIKyHJD+EjNyrbbwv4ygG01RVEajpjQaDA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      storybook: ^10.1.10
+      vite: ^5.0.0 || ^6.0.0 || ^7.0.0
+
+  '@storybook/react@10.1.10':
+    resolution: {integrity: sha512-9Rpr8/wX0p5/EaulrxpqrjKjhGaA/Ab9HgxzTqs2Shz0gvMAQHoiRnTEp7RCCkP49ruFYnIp0yGRSovu03LakQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      storybook: ^10.1.10
+      typescript: '>= 4.9.x'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  '@swc/core-darwin-arm64@1.15.40':
+    resolution: {integrity: sha512-PaYyclfmQ++77D8ityYvmmVzHv9aG8ROwt2GfG6/ccloy4Hgf80qtOnzb9VYvPsUT7Ty1uhuDRhv3XYpf62qhQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@swc/core-darwin-x64@1.15.40':
+    resolution: {integrity: sha512-HbbPzvfLBUXjIB1Ezks+//lNUjmLjfyd63XSwprJgrZaXYdm70kohXPJUWdqKZozolFxbPaO+xtBaiUp6BoueA==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@swc/core-linux-arm-gnueabihf@1.15.40':
+    resolution: {integrity: sha512-SlRZsCjOCPR2LvFs0Ri/Xrx/5o5TCt8vl4gW6mX1hEZOG0a625RxzRHpHdAQNGykmAN/7IeaFAJG+QnNmxlHcA==}
+    engines: {node: '>=10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@swc/core-linux-arm64-gnu@1.15.40':
+    resolution: {integrity: sha512-Q8byxJt2fh8CR3EUX6snBpy47AoBVm+In/+Z3rjDHMjC38ZvR9/gtUUNCT0tfrn4EdVsO8/QPi59nxrxvqxvBQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@swc/core-linux-arm64-musl@1.15.40':
+    resolution: {integrity: sha512-4z0MgHU+7M0pZDqBN1El7mFXDI1SBwinfcUkAyA4v8QrhOIUOZltySt2aStQLZGrdXVXM4Y4ylfiTC04ED+MoQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@swc/core-linux-ppc64-gnu@1.15.40':
+    resolution: {integrity: sha512-fLI4iUgeSZu0eRWUXwe6YzPFx9gHbFiPkl8Rp3mJfP8OpNR3nTQCGPvHdDh9xniW7mVvgMY4ni7A4VzqI1KrpA==}
+    engines: {node: '>=10'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@swc/core-linux-s390x-gnu@1.15.40':
+    resolution: {integrity: sha512-YqeKMAb7d4nQSGMJQ454IlaCENpzcDqhvBE9+CPfdnYpnUXxd+BSrB6Xk0YjW8UyoEhUj4p6quATCxbsp6J3jg==}
+    engines: {node: '>=10'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@swc/core-linux-x64-gnu@1.15.40':
+    resolution: {integrity: sha512-7HOuS1iGcme/j/TuL1TfmmLGiMQrjv/GmjyZeydl00FKPtpGXEldwqfI56xgd1YzrzoB2svWjxbGGyQ0TEASxg==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@swc/core-linux-x64-musl@1.15.40':
+    resolution: {integrity: sha512-h4kZYHc7dpc9P9u4brRJaS8Pl7tPVHAeiLSzw7T5RfIJgAoSdaCMKzI/2Uay9gFhaw8uyCDl0L5q37r0EpAfIA==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@swc/core-win32-arm64-msvc@1.15.40':
+    resolution: {integrity: sha512-+mQgKZXSj6mV38Zh05QaxSjUDmGP/R2JWlXZTDLSPkDzHU6p3GxN9eeSf5dfyDVU86946fmCvSzyl/ucImx8+A==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@swc/core-win32-ia32-msvc@1.15.40':
+    resolution: {integrity: sha512-yvwdPLGd25mcj/mNatjNQ0lZujtQD6psH3v9PNmMb+fSzjbNG8KIDxjFWrcV+fsFVLOkyOmdJsFmX7NAFjVyPw==}
+    engines: {node: '>=10'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@swc/core-win32-x64-msvc@1.15.40':
+    resolution: {integrity: sha512-OXtKsLU1bVtInzzDEAY2sYiF/rl4tvAnLLLpuMp3HzAOQZ5A+i69AKDhA1YLQTaMAqO3vzyYNVAYVRMPtSYD4w==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@swc/core@1.15.40':
+    resolution: {integrity: sha512-2kwzJikRvgtNAG7MwVZY2vEzZjTxKIq5jXOihuSV/8U+Hej8Va22t65aKnJZs3P+NwojZvR8Mf8kyM7O+V8sQg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@swc/helpers': '>=0.5.17'
+    peerDependenciesMeta:
+      '@swc/helpers':
+        optional: true
+
+  '@swc/counter@0.1.3':
+    resolution: {integrity: sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==}
+
+  '@swc/helpers@0.5.15':
+    resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
+
+  '@swc/helpers@0.5.23':
+    resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
+
+  '@swc/types@0.1.26':
+    resolution: {integrity: sha512-lyMwd7WGgG79RS7EERZV3T8wMdmPq3xwyg+1nmAM64kIhx5yl+juO2PYIHb7vTiPgPCj8LYjsNV2T5wiQHUEaw==}
+
+  '@t3-oss/env-core@0.13.10':
+    resolution: {integrity: sha512-NNFfdlJ+HmPHkLi2HKy7nwuat9SIYOxei9K10lO2YlcSObDILY7mHZNSHsieIM3A0/5OOzw/P/b+yLvPdaG52g==}
+    peerDependencies:
+      arktype: ^2.1.0
+      typescript: '>=5.0.0'
+      valibot: ^1.0.0-beta.7 || ^1.0.0
+      zod: ^3.24.0 || ^4.0.0
+    peerDependenciesMeta:
+      arktype:
+        optional: true
+      typescript:
+        optional: true
+      valibot:
+        optional: true
+      zod:
+        optional: true
+
+  '@t3-oss/env-nextjs@0.13.10':
+    resolution: {integrity: sha512-JfSA2WXOnvcc/uMdp31paMsfbYhhdvLLRxlwvrnlPE9bwM/n0Z+Qb9xRv48nPpvfMhOrkrTYw1I5Yc06WIKBJQ==}
+    peerDependencies:
+      arktype: ^2.1.0
+      typescript: '>=5.0.0'
+      valibot: ^1.0.0-beta.7 || ^1.0.0
+      zod: ^3.24.0 || ^4.0.0
+    peerDependenciesMeta:
+      arktype:
+        optional: true
+      typescript:
+        optional: true
+      valibot:
+        optional: true
+      zod:
+        optional: true
+
+  '@tailwindcss/cli@4.3.0':
+    resolution: {integrity: sha512-X9kdlqyMopO9fewbgHsEeuy31YzMHbdZ9VsKt004tB+mxSg1CNbyhZYCzvhciN0AM4R4b5lvIprPjtNq7iQxpQ==}
+    hasBin: true
+
+  '@tailwindcss/node@4.3.0':
+    resolution: {integrity: sha512-aFb4gUhFOgdh9AXo4IzBEOzBkkAxm9VigwDJnMIYv3lcfXCJVesNfbEaBl4BNgVRyid92AmdviqwBUBRKSeY3g==}
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    resolution: {integrity: sha512-TJPiq67tKlLuObP6RkwvVGDoxCMBVtDgKkLfa/uyj7/FyxvQwHS+UOnVrXXgbEsfUaMgiVvC4KbJnRr26ho4Ng==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    resolution: {integrity: sha512-oMN/WZRb+SO37BmUElEgeEWuU8E/HXRkiODxJxLe1UTHVXLrdVSgfaJV7pSlhRGMSOiXLuxTIjfsF3wYvz8cgQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    resolution: {integrity: sha512-N6CUmu4a6bKVADfw77p+iw6Yd9Q3OBhe0veaDX+QazfuVYlQsHfDgxBrsjQ/IW+zywL8mTrNd0SdJT/zgtvMdA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    resolution: {integrity: sha512-zDL5hBkQdH5C6MpqbK3gQAgP80tsMwSI26vjOzjJtNCMUo0lFgOItzHKBIupOZNQxt3ouPH7RPhvNhiTfCe5CQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    resolution: {integrity: sha512-R06HdNi7A7OEoMsf6d4tjZ71RCWnZQPHj2mnotSFURjNLdBC+cIgXQ7l81CqeoiQftjf6OOblxXMInMgN2VzMA==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    resolution: {integrity: sha512-qTJHELX8jetjhRQHCLilkVLmybpzNQAtaI/gaoVoidn/ufbNDbAo8KlK2J+yPoc8wQxvDxCmh/5lr8nC1+lTbg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    resolution: {integrity: sha512-Z6sukiQsngnWO+l39X4pPbiWT81IC+PLKF+PHxIlyZbGNb9MODfYlXEVlFvej5BOZInWX01kVyzeLvHsXhfczQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    resolution: {integrity: sha512-DRNdQRpSGzRGfARVuVkxvM8Q12nh19l4BF/G7zGA1oe+9wcC6saFBHTISrpIcKzhiXtSrlSrluCfvMuledoCTQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    resolution: {integrity: sha512-Z0IADbDo8bh6I7h2IQMx601AdXBLfFpEdUotft86evd/8ZPflZe9COPO8Q1vw+pfLWIUo9zN/JGZvwuAJqduqg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    resolution: {integrity: sha512-HNZGOUxEmElksYR7S6sC5jTeNGpobAsy9u7Gu0AskJ8/20FR9GqebUyB+HBcU/ax6BHuiuJi+Oda4B+YX6H1yA==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    resolution: {integrity: sha512-Pe+RPVTi1T+qymuuRpcdvwSVZjnll/f7n8gBxMMh3xLTctMDKqpdfGimbMyioqtLhUYZxdJ9wGNhV7MKHvgZsQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    resolution: {integrity: sha512-Mvrf2kXW/yeW/OTezZlCGOirXRcUuLIBx/5Y12BaPM7wJoryG6dfS/NJL8aBPqtTEx/Vm4T4vKzFUcKDT+TKUA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.3.0':
+    resolution: {integrity: sha512-F7HZGBeN9I0/AuuJS5PwcD8xayx5ri5GhjYUDBEVYUkexyA/giwbDNjRVrxSezE3T250OU2K/wp/ltWx3UOefg==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/postcss@4.3.0':
+    resolution: {integrity: sha512-Jm05Tjx+9yCLGv5qw1c+84Psds8MnyrEQYCB+FFk2lgGiUjlRqdxke4mVTuYrj2xnVZqKim2Apr5ySuQRYAw/w==}
+
+  '@tailwindcss/typography@0.5.19':
+    resolution: {integrity: sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==}
+    peerDependencies:
+      tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
+
+  '@tailwindcss/vite@4.3.0':
+    resolution: {integrity: sha512-t6J3OrB5Fc0ExuhohouH0fWUGMYL6PTLhW+E7zIk/pdbnJARZDCwjBznFnkh5ynRnIRSI4YjtTH0t6USjJISrw==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
+  '@tanstack/react-table@8.21.3':
+    resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      react: '>=16.8'
+      react-dom: '>=16.8'
+
+  '@tanstack/table-core@8.21.3':
+    resolution: {integrity: sha512-ldZXEhOBb8Is7xLs01fR3YEc3DERiz5silj8tnGkFZytt1abEvl/GhUmCE0PMLaMPTa3Jk4HbKmRlHmu+gCftg==}
+    engines: {node: '>=12'}
+
+  '@testing-library/dom@10.4.1':
+    resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
+    engines: {node: '>=18'}
+
+  '@testing-library/jest-dom@6.9.1':
+    resolution: {integrity: sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==}
+    engines: {node: '>=14', npm: '>=6', yarn: '>=1'}
+
+  '@testing-library/react@16.3.1':
+    resolution: {integrity: sha512-gr4KtAWqIOQoucWYD/f6ki+j5chXfcPc74Col/6poTyqTmn7zRmodWahWRCp8tYd+GMqBonw6hstNzqjbs6gjw==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@testing-library/dom': ^10.0.0
+      '@types/react': ^18.0.0 || ^19.0.0
+      '@types/react-dom': ^18.0.0 || ^19.0.0
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@testing-library/user-event@14.6.1':
+    resolution: {integrity: sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==}
+    engines: {node: '>=12', npm: '>=6'}
+    peerDependencies:
+      '@testing-library/dom': '>=7.21.4'
+
+  '@ts-morph/common@0.28.1':
+    resolution: {integrity: sha512-W74iWf7ILp1ZKNYXY5qbddNaml7e9Sedv5lvU1V8lftlitkc9Pq1A+jlH23ltDgWYeZFFEqGCD1Ies9hqu3O+g==}
+
+  '@tybys/wasm-util@0.10.2':
+    resolution: {integrity: sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==}
+
+  '@types/aria-query@5.0.4':
+    resolution: {integrity: sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==}
+
+  '@types/babel__core@7.20.5':
+    resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
+
+  '@types/babel__generator@7.27.0':
+    resolution: {integrity: sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==}
+
+  '@types/babel__template@7.4.4':
+    resolution: {integrity: sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==}
+
+  '@types/babel__traverse@7.28.0':
+    resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
+
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/color-convert@2.0.4':
+    resolution: {integrity: sha512-Ub1MmDdyZ7mX//g25uBAoH/mWGd9swVbt8BseymnaE18SU4po/PjmCrHxqIIRjBo3hV/vh1KGr0eMxUhp+t+dQ==}
+
+  '@types/color-name@1.1.5':
+    resolution: {integrity: sha512-j2K5UJqGTxeesj6oQuGpMgifpT5k9HprgQd8D1Y0lOFqKHl3PJu5GMeS4Y5EgjS55AE6OQxf8mPED9uaGbf4Cg==}
+
+  '@types/culori@4.0.1':
+    resolution: {integrity: sha512-43M51r/22CjhbOXyGT361GZ9vncSVQ39u62x5eJdBQFviI8zWp2X5jzqg7k4M6PVgDQAClpy2bUe2dtwEgEDVQ==}
+
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
+  '@types/doctrine@0.0.9':
+    resolution: {integrity: sha512-eOIHzCUSH7SMfonMG1LsC2f8vxBFtho6NGBznK41R84YzPuvSBzrhEps33IsQiOW9+VL6NQ9DbjQJznk/S4uRA==}
+
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
+  '@types/estree@1.0.8':
+    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/fs-extra@11.0.4':
+    resolution: {integrity: sha512-yTbItCNreRooED33qjunPthRcSjERP1r4MqCZc7wv0u2sUkzTFp45tgUfS5+r7FrZPdmCCNflLhVSP/o+SemsQ==}
+
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
+  '@types/json-schema@7.0.15':
+    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+
+  '@types/json5@0.0.29':
+    resolution: {integrity: sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==}
+
+  '@types/jsonfile@6.1.4':
+    resolution: {integrity: sha512-D5qGUYwjvnNNextdU59/+fI+spnwtTFmyQP0h+PfIOSkNfpU6AOICUOkm4i0OnSk+NyjdPJrxCDro0sJsWlRpQ==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/mdx@2.0.13':
+    resolution: {integrity: sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
+  '@types/node@20.19.42':
+    resolution: {integrity: sha512-5L7SUaFC1RyDraj2yRhyBzHTobyXHmohD100CChNtyPyleoq37Mqab5Gn8XEKI04dfN/oqPdpHk38MgcQWHbZg==}
+
+  '@types/node@25.0.3':
+    resolution: {integrity: sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react-reconciler@0.28.9':
+    resolution: {integrity: sha512-HHM3nxyUZ3zAylX8ZEyrDNd2XZOnQ0D5XfunJF5FLQnZbHHYq4UWvW1QfelQNXv1ICNkwYhfxjwfnqivYB6bFg==}
+    peerDependencies:
+      '@types/react': '*'
+
+  '@types/react@19.2.14':
+    resolution: {integrity: sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==}
+
+  '@types/resolve@1.20.2':
+    resolution: {integrity: sha512-60BCwRFOZCQhDncwQdxxeOEEkbc5dIMccYLwbxsS4TUNeVECQ/pBJ0j09mrHOl/JJvpRPGwO9SvE4nR2Nb/a4Q==}
+
+  '@types/resolve@1.20.6':
+    resolution: {integrity: sha512-A4STmOXPhMUtHH+S6ymgE2GiBSMqf4oTvcQZMcHzokuTLVYzXTB8ttjcgxOVaAp2lGwEdzZ0J+cRbbeevQj1UQ==}
+
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
+  '@typescript-eslint/eslint-plugin@8.50.1':
+    resolution: {integrity: sha512-PKhLGDq3JAg0Jk/aK890knnqduuI/Qj+udH7wCf0217IGi4gt+acgCyPVe79qoT+qKUvHMDQkwJeKW9fwl8Cyw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.50.1
+      eslint: ^8.57.0 || ^9.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/parser@8.50.1':
+    resolution: {integrity: sha512-hM5faZwg7aVNa819m/5r7D0h0c9yC4DUlWAOvHAtISdFTc8xB86VmX5Xqabrama3wIPJ/q9RbGS1worb6JfnMg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/project-service@8.50.1':
+    resolution: {integrity: sha512-E1ur1MCVf+YiP89+o4Les/oBAVzmSbeRB0MQLfSlYtbWU17HPxZ6Bhs5iYmKZRALvEuBoXIZMOIRRc/P++Ortg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/project-service@8.60.1':
+    resolution: {integrity: sha512-eXkTH2bxmXlqD1RnOPmLZ9ZM9D3VwSx04JOwBnP9RQ+yUA5a2Mu7SfW8uaV2Aon53NJzZlZYuX7tn91Izf+xaw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/scope-manager@8.50.1':
+    resolution: {integrity: sha512-mfRx06Myt3T4vuoHaKi8ZWNTPdzKPNBhiblze5N50//TSHOAQQevl/aolqA/BcqqbJ88GUnLqjjcBc8EWdBcVw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/scope-manager@8.60.1':
+    resolution: {integrity: sha512-gvI5OQoptnxQnchOirukCuQ55svJSTuD/4k5+pC267xyBtYry748R9/c3tYUzb/iE6RZfllRz2lVulLCHkTm4w==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.50.1':
+    resolution: {integrity: sha512-ooHmotT/lCWLXi55G4mvaUF60aJa012QzvLK0Y+Mp4WdSt17QhMhWOaBWeGTFVkb2gDgBe19Cxy1elPXylslDw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/tsconfig-utils@8.60.1':
+    resolution: {integrity: sha512-nh8w4qAteiKuZu3pSSzG/yGKpw0OlkrKnzFmbVRenKaD4qc+7i1GrmZaLVkr8rk4uipiPGMOW4YsM6WmKZ5CvA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/type-utils@8.50.1':
+    resolution: {integrity: sha512-7J3bf022QZE42tYMO6SL+6lTPKFk/WphhRPe9Tw/el+cEwzLz1Jjz2PX3GtGQVxooLDKeMVmMt7fWpYRdG5Etg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/types@8.50.1':
+    resolution: {integrity: sha512-v5lFIS2feTkNyMhd7AucE/9j/4V9v5iIbpVRncjk/K0sQ6Sb+Np9fgYS/63n6nwqahHQvbmujeBL7mp07Q9mlA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/types@8.60.1':
+    resolution: {integrity: sha512-4h0tY8ppCkdCzcrl2YM5M3my0xsE1Tf8om3owEu5oPWmXwkKRmk0j0LGDzYBGUcAlesEbxBhazqu/K4cu3Ug7w==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.50.1':
+    resolution: {integrity: sha512-woHPdW+0gj53aM+cxchymJCrh0cyS7BTIdcDxWUNsclr9VDkOSbqC13juHzxOmQ22dDkMZEpZB+3X1WpUvzgVQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/typescript-estree@8.60.1':
+    resolution: {integrity: sha512-alpRkfG8hlVE5kdJW2GkfgDgXxold3e8e4l6EnmhRmRLbekgAPCCGDVD++sABy9FcgPFroq+uFcCSM1vR57Cew==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/utils@8.50.1':
+    resolution: {integrity: sha512-lCLp8H1T9T7gPbEuJSnHwnSuO9mDf8mfK/Nion5mZmiEaQD9sWf9W4dfeFqRyqRjF06/kBuTmAqcs9sewM2NbQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/utils@8.60.1':
+    resolution: {integrity: sha512-h2MPBLoNtjc3qZWfY3Tl51yPorQ2McHn8pJfcMNTcIvrrZrr90Ykffit0yjrPFWQcRcUxzH20+6OcVdW4yHtUg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/visitor-keys@8.50.1':
+    resolution: {integrity: sha512-IrDKrw7pCRUR94zeuCSUWQ+w8JEf5ZX5jl/e6AHGSLi1/zIr0lgutfn/7JpfCey+urpgQEdrZVYzCaVVKiTwhQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/visitor-keys@8.60.1':
+    resolution: {integrity: sha512-EbGRQg4FhrmwLodl+t3JNAnXHWVr9Vp+Zl1QBZVPY4ByfkzIT8cX3K6QWODHtkIZqqJVEWvhHSx3v5PDHsaQag==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@ungap/structured-clone@1.3.1':
+    resolution: {integrity: sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==}
+
+  '@unrs/resolver-binding-android-arm-eabi@1.12.2':
+    resolution: {integrity: sha512-g5T90pqg1bo/7mytQx6F4iBNC0Wsh9cu+z9veDbFjc7HjpesJFWD7QMS0NGStXM075+7dJPPVvBbpZlnrdpi/w==}
+    cpu: [arm]
+    os: [android]
+
+  '@unrs/resolver-binding-android-arm64@1.12.2':
+    resolution: {integrity: sha512-YGCRZv/9GLhwmz6mYDeTsm/92BAyR28l6c2ReweVW5pWgfsitWLY8upvfRlGdoyD8HjeTHSYJWyZGD4KJA/nFQ==}
+    cpu: [arm64]
+    os: [android]
+
+  '@unrs/resolver-binding-darwin-arm64@1.12.2':
+    resolution: {integrity: sha512-u9DiNT1auQMO20A9SyTuG3wUgQWB9Z7KjAg0uFuCDR1FsAY8A0CG2S6JpHS1xwm/w1G08bjXZDcyOCjv1WAm2w==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@unrs/resolver-binding-darwin-x64@1.12.2':
+    resolution: {integrity: sha512-f7rPLi/T1HVKZu/u6t87lroib16n8vrSzcyxI7lg4BGO9UF26KhQL44sd9eOUgrTYhvRXtWOIZT5PejdPyJfUA==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@unrs/resolver-binding-freebsd-x64@1.12.2':
+    resolution: {integrity: sha512-BpcOjWCJub6nRZUS2zA20pmLvjtqAtGejETaIyRLiZiQf++cbrjltLA5NN/xaXfqeOBOSlMFbemIl5/S5tljmg==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@unrs/resolver-binding-linux-arm-gnueabihf@1.12.2':
+    resolution: {integrity: sha512-vZTDvdSISZjJx66OzJqtsOhzifbqRjbmI1Mnu49fQDwog5GtDI4QidRiEAYbZCRj9C8YZEW+3ZjqsyS9GR4k2A==}
+    cpu: [arm]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-arm-musleabihf@1.12.2':
+    resolution: {integrity: sha512-BiPI+IrIlwcW4nLLMM21+B1dFPzd55yAVgVGrdgDjNef+ch03GdxrcyaIz8X9SsQirh/kCQ7mviyWlMxdh2D7g==}
+    cpu: [arm]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-arm64-gnu@1.12.2':
+    resolution: {integrity: sha512-zJc0H99FEPoFfSrNpa91HYfxzfAJCr502oxNK1cfdC9hlaFI43RT+JFCann9JUgZmLzzntChHyn13Sgn9ljHNg==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-arm64-musl@1.12.2':
+    resolution: {integrity: sha512-KQ3Lki6l+Pz1k/eBipN41ES+YUK30beLGb9YqcB1O542cyLCNE6GaxrfcY3T6EezmGGk84wb5XyO9loTM9tkcA==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-loong64-gnu@1.12.2':
+    resolution: {integrity: sha512-3SJGEh1DborhG6pyxvhPzCT4bbSIVihsvgJc13P1bHG7KLdNDaF9T3gsTwFc7Jw/5Y5/iWOjkEx7Zy0NvCGX3Q==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-loong64-musl@1.12.2':
+    resolution: {integrity: sha512-jiuG/Obbel7uw1PwHNFfrkiKhLAF6mnyZ6aWlOAVN9WqKm8v0OFGnciJIHu8+CMvXLQ8AD51LPzAoUfT21D5Ew==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-ppc64-gnu@1.12.2':
+    resolution: {integrity: sha512-q7xRvVpmcfeL+LlZg8Pbbo6QaTZwDU5BaGZbwfhkEsXJn3Was8xYfE0RBH266xZt0rM6B7i8xAYIvjthuUIWHg==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-riscv64-gnu@1.12.2':
+    resolution: {integrity: sha512-0CVdx6lcnT3Q9inOH8tsMIOJ6ImndllMjqJHg8RLVdB7Vq4SfkEXl9mCSsVNuNA4MCYycRicCUxPCabVHJRr6A==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-riscv64-musl@1.12.2':
+    resolution: {integrity: sha512-iOwlRo9vnp6R6ohHQS11n0NnfdXx/omhkocmIfaPRpQhKZ+3BDMkkdRVh53qjkFkpPddf+FETA28NwGN7l5l+w==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-s390x-gnu@1.12.2':
+    resolution: {integrity: sha512-HYJtLfXq94q8iZNFT1lknx258wlkkWhZeUXJRqzKBBUJ00CvZ+N33zgbCqimLjsyw5Va6uUxhVa12mI+kaveEw==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-x64-gnu@1.12.2':
+    resolution: {integrity: sha512-mPsUhunKKDih5O96Y6enDQyHc1SqBPlY1E/SfMWDM3EdJ95Z9CArPeCVwCCqbP45ljvivdEk8Fxn+SIb1rDAJQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-x64-musl@1.12.2':
+    resolution: {integrity: sha512-azrt6+5ydLd8Vt210AAFis/lZevSfPw93EJRIJG+xPu4WCJ8K0kppCTpMyLPcKT7H15M4Jnt2tMp5bOvCkRC6A==}
+    cpu: [x64]
+    os: [linux]
+
+  '@unrs/resolver-binding-openharmony-arm64@1.12.2':
+    resolution: {integrity: sha512-YZ9hP4O0X9PQb8eO980qmLNGH4zT3I9+SZTdt0Pr0YyuGQhYKoOZkV02VzrzyOZJ5xIJ3UFIenKkUkGg8GjgWQ==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@unrs/resolver-binding-wasm32-wasi@1.12.2':
+    resolution: {integrity: sha512-tYFDIkMxSflfEc/h92ZWNsZlHSwgimbNHSO3PL2JWQHfCuC2q316jMyYU9TIWZsFK2bQwyK5VAdYgn8ygPj69A==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@unrs/resolver-binding-win32-arm64-msvc@1.12.2':
+    resolution: {integrity: sha512-qzNyg3xL0VPQmCaUh+N5jSitce6k+uCBfMDesWRnlULOZaqUkaJ0ybdT+UqlAWJoQjuqfIU/0Ptx9bteN4D82g==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@unrs/resolver-binding-win32-ia32-msvc@1.12.2':
+    resolution: {integrity: sha512-WD9sY00OfpHVGfsnHZoA8jVT+esS/Bg8z8jzxp5BnDCjjwsuKsPQrzswwpFy4J1AUJbXPRfkpcX0mXrzeXW79g==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@unrs/resolver-binding-win32-x64-msvc@1.12.2':
+    resolution: {integrity: sha512-nAB74NfSNKknqQ1RrYj6uz8FcXEomu/MATJZxh/x+BArzN2U3JbOYC0APYzUIGhVY3m5hRxA8VPNdPBoG8txlA==}
+    cpu: [x64]
+    os: [win32]
+
+  '@vercel/analytics@1.6.1':
+    resolution: {integrity: sha512-oH9He/bEM+6oKlv3chWuOOcp8Y6fo6/PSro8hEkgCW3pu9/OiCXiUpRUogDh3Fs3LH2sosDrx8CxeOLBEE+afg==}
+    peerDependencies:
+      '@remix-run/react': ^2
+      '@sveltejs/kit': ^1 || ^2
+      next: '>= 13'
+      react: ^18 || ^19 || ^19.0.0-rc
+      svelte: '>= 4'
+      vue: ^3
+      vue-router: ^4
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      '@sveltejs/kit':
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      svelte:
+        optional: true
+      vue:
+        optional: true
+      vue-router:
+        optional: true
+
+  '@vercel/og@0.8.6':
+    resolution: {integrity: sha512-hBcWIOppZV14bi+eAmCZj8Elj8hVSUZJTpf1lgGBhVD85pervzQ1poM/qYfFUlPraYSZYP+ASg6To5BwYmUSGQ==}
+    engines: {node: '>=16'}
+
+  '@vitejs/plugin-react@5.1.2':
+    resolution: {integrity: sha512-EcA07pHJouywpzsoTUqNh5NwGayl2PPVEJKUSinGGSxFGYn+shYbqMGBg6FXDqgXum9Ou/ecb+411ssw8HImJQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+
+  '@vitest/expect@3.2.4':
+    resolution: {integrity: sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==}
+
+  '@vitest/expect@4.0.16':
+    resolution: {integrity: sha512-eshqULT2It7McaJkQGLkPjPjNph+uevROGuIMJdG3V+0BSR2w9u6J9Lwu+E8cK5TETlfou8GRijhafIMhXsimA==}
+
+  '@vitest/mocker@3.2.4':
+    resolution: {integrity: sha512-46ryTE9RZO/rfDd7pEqFl7etuyzekzEhUbTW3BvmeO/BcCMEgq59BKhek3dXDWgAj4oMK6OZi+vRr1wPW6qjEQ==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^5.0.0 || ^6.0.0 || ^7.0.0-0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/mocker@4.0.16':
+    resolution: {integrity: sha512-yb6k4AZxJTB+q9ycAvsoxGn+j/po0UaPgajllBgt1PzoMAAmJGYFdDk0uCcRcxb3BrME34I6u8gHZTQlkqSZpg==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0-0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@3.2.4':
+    resolution: {integrity: sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==}
+
+  '@vitest/pretty-format@4.0.16':
+    resolution: {integrity: sha512-eNCYNsSty9xJKi/UdVD8Ou16alu7AYiS2fCPRs0b1OdhJiV89buAXQLpTbe+X8V9L6qrs9CqyvU7OaAopJYPsA==}
+
+  '@vitest/runner@4.0.16':
+    resolution: {integrity: sha512-VWEDm5Wv9xEo80ctjORcTQRJ539EGPB3Pb9ApvVRAY1U/WkHXmmYISqU5E79uCwcW7xYUV38gwZD+RV755fu3Q==}
+
+  '@vitest/snapshot@4.0.16':
+    resolution: {integrity: sha512-sf6NcrYhYBsSYefxnry+DR8n3UV4xWZwWxYbCJUt2YdvtqzSPR7VfGrY0zsv090DAbjFZsi7ZaMi1KnSRyK1XA==}
+
+  '@vitest/spy@3.2.4':
+    resolution: {integrity: sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==}
+
+  '@vitest/spy@4.0.16':
+    resolution: {integrity: sha512-4jIOWjKP0ZUaEmJm00E0cOBLU+5WE0BpeNr3XN6TEF05ltro6NJqHWxXD0kA8/Zc8Nh23AT8WQxwNG+WeROupw==}
+
+  '@vitest/utils@3.2.4':
+    resolution: {integrity: sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==}
+
+  '@vitest/utils@4.0.16':
+    resolution: {integrity: sha512-h8z9yYhV3e1LEfaQ3zdypIrnAg/9hguReGZoS7Gl0aBG5xgA410zBqECqmaF/+RkTggRsfnzc1XaAHA6bmUufA==}
+
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn@7.4.1:
+    resolution: {integrity: sha512-nQyp0o1/mNdbTO1PO6kHkwSrmgZ0MT/jCCpNiwbUjGoRN4dlBhqJtoQuCnEOKzgTVwg0ZWiCoQy6SxMebQVh8A==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  acorn@8.16.0:
+    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  ajv@6.15.0:
+    resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
+
+  ajv@8.20.0:
+    resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
+
+  ansi-escapes@7.3.0:
+    resolution: {integrity: sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==}
+    engines: {node: '>=18'}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  ansi-styles@5.2.0:
+    resolution: {integrity: sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==}
+    engines: {node: '>=10'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
+  any-promise@1.3.0:
+    resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
+
+  apca-w3@0.1.9:
+    resolution: {integrity: sha512-Zrf6AeBeQjNe/fxK7U1jCo5zfdjDl6T4/kdw5Xlky3G7u+EJTZkyItjMYQGtwf9pkftsINxcYyOpuLkzKf1ITQ==}
+
+  apcach@0.6.4:
+    resolution: {integrity: sha512-btUArMSP/xPuI1eBFp2TrrgTy4vRsqekLDaxNbnY9nygd/oJCinFm5LunR3FX/81c+/25Fuol6pPYYg79uH7pw==}
+
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  args-tokenizer@0.3.0:
+    resolution: {integrity: sha512-xXAd7G2Mll5W8uo37GETpQ2VrE84M181Z7ugHFGQnJZ50M2mbOv0osSZ9VsSgPfJQ+LVG0prSi0th+ELMsno7Q==}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
+    engines: {node: '>=10'}
+
+  aria-query@5.3.0:
+    resolution: {integrity: sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==}
+
+  aria-query@5.3.2:
+    resolution: {integrity: sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==}
+    engines: {node: '>= 0.4'}
+
+  array-buffer-byte-length@1.0.2:
+    resolution: {integrity: sha512-LHE+8BuR7RYGDKvnrmcuSq3tDcKv9OFEXQt/HpbZhY7V6h0zlUXutnAD82GiFx9rdieCMjkvtcsPqBwgUl1Iiw==}
+    engines: {node: '>= 0.4'}
+
+  array-ify@1.0.0:
+    resolution: {integrity: sha512-c5AMf34bKdvPhQ7tBGhqkgKNUzMr4WUs+WDtC2ZUGOUncbxKMTvqxYctiseW3+L4bA8ec+GcZ6/A/FW4m8ukng==}
+
+  array-includes@3.1.9:
+    resolution: {integrity: sha512-FmeCCAenzH0KH381SPT5FZmiA/TmpndpcaShhfgEN9eCVjnFBqq3l1xrI42y8+PPLI6hypzou4GXw00WHmPBLQ==}
+    engines: {node: '>= 0.4'}
+
+  array.prototype.findlast@1.2.5:
+    resolution: {integrity: sha512-CVvd6FHg1Z3POpBLxO6E6zr+rSKEQ9L6rZHAaY7lLfhKsWYUBBOuMs0e9o24oopj6H+geRCX0YJ+TJLBK2eHyQ==}
+    engines: {node: '>= 0.4'}
+
+  array.prototype.findlastindex@1.2.6:
+    resolution: {integrity: sha512-F/TKATkzseUExPlfvmwQKGITM3DGTK+vkAsCZoDc5daVygbJBnjEUCbgkAvVFsgfXfX4YIqZ/27G3k3tdXrTxQ==}
+    engines: {node: '>= 0.4'}
+
+  array.prototype.flat@1.3.3:
+    resolution: {integrity: sha512-rwG/ja1neyLqCuGZ5YYrznA62D4mZXg0i1cIskIUKSiqF3Cje9/wXAls9B9s1Wa2fomMsIv8czB8jZcPmxCXFg==}
+    engines: {node: '>= 0.4'}
+
+  array.prototype.flatmap@1.3.3:
+    resolution: {integrity: sha512-Y7Wt51eKJSyi80hFrJCePGGNo5ktJCslFuboqJsbf57CCPcm5zztluPlc4/aD8sWsKvlwatezpV4U1efk8kpjg==}
+    engines: {node: '>= 0.4'}
+
+  array.prototype.tosorted@1.1.4:
+    resolution: {integrity: sha512-p6Fx8B7b7ZhL/gmUsAy0D15WhvDccw3mnGNbZpi3pmeJdxtWsj2jEaI4Y6oo3XiHfzuSgPwKc04MYt6KgvC/wA==}
+    engines: {node: '>= 0.4'}
+
+  arraybuffer.prototype.slice@1.0.4:
+    resolution: {integrity: sha512-BNoCY6SXXPQ7gF2opIP4GBE+Xw7U+pHMYKuzjgCN3GwiaIR09UUeKfheyIry77QtrCBlC0KK0q5/TER/tYh3PQ==}
+    engines: {node: '>= 0.4'}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  ast-types-flow@0.0.8:
+    resolution: {integrity: sha512-OH/2E5Fg20h2aPrbe+QL8JZQFko0YZaF+j4mnQ7BGhfavO7OpSLa8a0y9sBwomHdSbkhTS8TQNayBfnW5DwbvQ==}
+
+  ast-types@0.16.1:
+    resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
+    engines: {node: '>=4'}
+
+  astring@1.9.0:
+    resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
+    hasBin: true
+
+  async-function@1.0.0:
+    resolution: {integrity: sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==}
+    engines: {node: '>= 0.4'}
+
+  available-typed-arrays@1.0.7:
+    resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
+    engines: {node: '>= 0.4'}
+
+  axe-core@4.12.0:
+    resolution: {integrity: sha512-FTavr/7Ba0IptwGOPxnQvdyW2tAsdLBMTBXz7rKH6xJ2skpyxpBxyHkDdBs4lf69yRqYpkqCdfhnwS8YULGOmg==}
+    engines: {node: '>=4'}
+
+  axobject-query@4.1.0:
+    resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
+    engines: {node: '>= 0.4'}
+
+  babel-plugin-react-compiler@1.0.0:
+    resolution: {integrity: sha512-Ixm8tFfoKKIPYdCCKYTsqv+Fd4IJ0DQqMyEimo+pxUOMUR9cVPlwTrFt9Avu+3cb6Zp3mAzl+t1MrG2fxxKsxw==}
+
+  babel-plugin-react-compiler@19.1.0-rc.3:
+    resolution: {integrity: sha512-mjRn69WuTz4adL0bXGx8Rsyk1086zFJeKmes6aK0xPuK3aaXmDJdLHqwKKMrpm6KAI1MCoUK72d2VeqQbu8YIA==}
+
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
+  balanced-match@1.0.2:
+    resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  base-x@3.0.11:
+    resolution: {integrity: sha512-xz7wQ8xDhdyP7tQxwdteLYeFfS68tSMNCZ/Y37WJ4bhGfKPpqEIlmIyueQHqOyoPhE6xNUqjzRr8ra0eF9VRvA==}
+
+  base64-js@0.0.8:
+    resolution: {integrity: sha512-3XSA2cR/h/73EzlXXdU6YNycmYI7+kicTxks4eJg2g39biHR84slg2+des+p7iHYhbRg/udIS4TD53WabcOUkw==}
+    engines: {node: '>= 0.4'}
+
+  baseline-browser-mapping@2.10.34:
+    resolution: {integrity: sha512-IMDedajPifLnHNY0X9n8hKxRTQ6/eTHwr5bDo04WnuqxyKw6LYtQywCuuqPZwhl3aBXMvQpJov42GLCwRRdQzw==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  bippy@0.3.34:
+    resolution: {integrity: sha512-vmptmU/20UdIWHHhq7qCSHhHzK7Ro3YJ1utU0fBG7ujUc58LEfTtilKxcF0IOgSjT5XLcm7CBzDjbv4lcKApGQ==}
+    peerDependencies:
+      react: '>=17.0.1'
+
+  boolbase@1.0.0:
+    resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
+
+  brace-expansion@1.1.15:
+    resolution: {integrity: sha512-EwOCDEex4quD37XhqM3omwtMoJjr//isUZz1JopUNWms+4Z2ViyM/k1YIRePpoVNnQhENnxtFjLaxNHrT7xIUg==}
+
+  brace-expansion@2.1.1:
+    resolution: {integrity: sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==}
+
+  brace-expansion@5.0.6:
+    resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
+    engines: {node: 18 || 20 || >=22}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  browserslist@4.28.2:
+    resolution: {integrity: sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  buffer-from@1.1.2:
+    resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
+
+  bumpp@11.0.1:
+    resolution: {integrity: sha512-X0ti27I/ewsx/u0EJSyl0IZWWOE95q+wIpAG/60kc5gqMNR4a23YJdd3lL7JsBN11TgLbCM4KpfGMuFfdigb4g==}
+    engines: {node: '>=20.19.0'}
+    hasBin: true
+
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
+  bundle-require@5.1.0:
+    resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    peerDependencies:
+      esbuild: '>=0.18'
+
+  cac@6.7.14:
+    resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==}
+    engines: {node: '>=8'}
+
+  cac@7.0.0:
+    resolution: {integrity: sha512-tixWYgm5ZoOD+3g6UTea91eow5z6AAHaho3g0V9CNSNb45gM8SmflpAc+GRd1InC4AqN/07Unrgp56Y94N9hJQ==}
+    engines: {node: '>=20.19.0'}
+
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bind@1.0.9:
+    resolution: {integrity: sha512-a/hy+pNsFUTR+Iz8TCJvXudKVLAnz/DyeSUo10I5yvFDQJBFU2s9uqQpoSrJlroHUKoKqzg+epxyP9lqFdzfBQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  calligraph@1.3.0:
+    resolution: {integrity: sha512-rLRh39Mr842VGQGzNeaPz9vjlmORCa5YQg7hXtcOO0/D5N9qDLH2neBqWyxNW6rS7J/ZGi3IPeogMc4ultuV9w==}
+    peerDependencies:
+      motion: '>=11'
+      react: '>=18'
+      react-dom: '>=18'
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  camelize@1.0.1:
+    resolution: {integrity: sha512-dU+Tx2fsypxTgtLoE36npi3UqcjSSMNYfkqgmoEhtZrraP5VWq0K7FkWVTYa8eMPtnU/G2txVsfdCJTn9uzpuQ==}
+
+  caniuse-api@3.0.0:
+    resolution: {integrity: sha512-bsTwuIg/BZZK/vreVTYYbSWoe2F+71P7K5QGEX+pT250DZbfU1MQ5prOKpPR+LL6uWKK3KMwMCAS74QB3Um1uw==}
+
+  caniuse-lite@1.0.30001797:
+    resolution: {integrity: sha512-l8xKG+gwAIExZGl9FrF7KUwuOmk6wbEPC9Xoy/RtnWv1XG0Q4LFlagaLpUv3Kiza3W/wm27zy0yWJEieYKAP6w==}
+
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
+  chai@5.3.3:
+    resolution: {integrity: sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==}
+    engines: {node: '>=18'}
+
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
+  check-error@2.1.3:
+    resolution: {integrity: sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==}
+    engines: {node: '>= 16'}
+
+  chokidar@4.0.3:
+    resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
+    engines: {node: '>= 14.16.0'}
+
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
+
+  chownr@3.0.0:
+    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
+    engines: {node: '>=18'}
+
+  chrome-trace-event@1.0.4:
+    resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
+    engines: {node: '>=6.0'}
+
+  class-variance-authority@0.7.1:
+    resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
+
+  clean-package@2.2.0:
+    resolution: {integrity: sha512-vLv8kRqvh4smPDpqAYFPLEijTppAd/cfCz4yBcUGoVl/JKu6ZWKhlo+G/cAmwlSa29RudfBeuyiNEzas8bTwEQ==}
+    hasBin: true
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-truncate@5.2.0:
+    resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
+    engines: {node: '>=20'}
+
+  client-only@0.0.1:
+    resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  clone@2.1.2:
+    resolution: {integrity: sha512-3Pe/CF1Nn94hyhIYpjtiLhdCoEoz0DqQ+988E9gmeEdQZlojxnOb74wctFyuwWQHzqyf9X7C7MG8juUpqBJT8w==}
+    engines: {node: '>=0.8'}
+
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
+  code-block-writer@13.0.3:
+    resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
+
+  collapse-white-space@2.1.0:
+    resolution: {integrity: sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-convert@3.1.3:
+    resolution: {integrity: sha512-fasDH2ont2GqF5HpyO4w0+BcewlhHEZOFn9c1ckZdHpJ56Qb7MHhH/IcJZbBGgvdtwdwNbLvxiBEdg336iA9Sg==}
+    engines: {node: '>=14.6'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  color-name@2.1.0:
+    resolution: {integrity: sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==}
+    engines: {node: '>=12.20'}
+
+  color2k@2.0.3:
+    resolution: {integrity: sha512-zW190nQTIoXcGCaU08DvVNFTmQhUpnJfVuAKfWqUQkflXKpaDdpaYoM0iluLS9lgJNHyBF58KKA2FBEwkD7wog==}
+
+  colord@2.9.3:
+    resolution: {integrity: sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==}
+
+  colorette@2.0.20:
+    resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
+
+  colorparsley@0.1.8:
+    resolution: {integrity: sha512-rObESTTTE6G5qO5WFwFxWPggpw4KfpxnLC6Ssl8bITBnNVRhDsyCeTRAUxWQNVTx2pRknKlO2nddYTxjkdNFaw==}
+
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
+  commander@12.1.0:
+    resolution: {integrity: sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==}
+    engines: {node: '>=18'}
+
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
+  commander@4.1.1:
+    resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
+    engines: {node: '>= 6'}
+
+  commander@7.2.0:
+    resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
+    engines: {node: '>= 10'}
+
+  commondir@1.0.1:
+    resolution: {integrity: sha512-W9pAhw0ja1Edb5GVdIF1mjZw/ASI0AlShXM83UUGe2DVr5TdAPEA1OA8m/g8zWp9x6On7gqufY+FatDbC3MDQg==}
+
+  compare-func@2.0.0:
+    resolution: {integrity: sha512-zHig5N+tPWARooBnb0Zx1MFcdfpyJrfTJ3Y5L+IFvUm8rM74hHz66z0gw0x4tijh5CorKkKUCnW82R2vmpeCRA==}
+
+  compute-scroll-into-view@3.1.1:
+    resolution: {integrity: sha512-VRhuHOLoKYOy4UbilLbUzbYg93XLjv2PncJC50EuTWPA3gaja1UjBsUP/D/9/juV3vQFr6XBEzn9KCAHdUvOHw==}
+
+  concat-map@0.0.1:
+    resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
+
+  concat-with-sourcemaps@1.1.0:
+    resolution: {integrity: sha512-4gEjHJFT9e+2W/77h/DS5SGUgwDaOwprX8L/gl5+3ixnzkVJJsZWDSelmN3Oilw3LNDZjZV0yqH1hLG3k6nghg==}
+
+  confbox@0.1.8:
+    resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
+
+  consola@3.4.2:
+    resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
+    engines: {node: ^14.18.0 || >=16.10.0}
+
+  conventional-changelog-angular@8.3.1:
+    resolution: {integrity: sha512-6gfI3otXK5Ph5DfCOI1dblr+kN3FAm5a97hYoQkqNZxOaYa5WKfXH+AnpsmS+iUH2mgVC2Cg2Qw9m5OKcmNrIg==}
+    engines: {node: '>=18'}
+
+  conventional-changelog-conventionalcommits@7.0.2:
+    resolution: {integrity: sha512-NKXYmMR/Hr1DevQegFB4MwfM5Vv0m4UIxKZTTYuD98lpTknaZlSRrDOG4X7wIXpGkfsYxZTghUN+Qq+T0YQI7w==}
+    engines: {node: '>=16'}
+
+  conventional-commits-parser@6.4.0:
+    resolution: {integrity: sha512-tvRg7FIBNlyPzjdG8wWRlPHQJJHI7DylhtRGeU9Lq+JuoPh5BKpPRX83ZdLrvXuOSu5Eo/e7SzOQhU4Hd2Miuw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cosmiconfig-typescript-loader@6.3.0:
+    resolution: {integrity: sha512-Akr82WH1Wfqatyiqpj8HDkO2o2KmJRu1FhKfSNJP3K4IdXwHfEyL7MOb62i1AGQVLtIQM+iCE9CGOtrfhR+mmA==}
+    engines: {node: '>=v18'}
+    peerDependencies:
+      '@types/node': '*'
+      cosmiconfig: '>=9'
+      typescript: '>=5'
+
+  cosmiconfig@9.0.1:
+    resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  css-background-parser@0.1.0:
+    resolution: {integrity: sha512-2EZLisiZQ+7m4wwur/qiYJRniHX4K5Tc9w93MT3AS0WS1u5kaZ4FKXlOTBhOjc+CgEgPiGY+fX1yWD8UwpEqUA==}
+
+  css-box-shadow@1.0.0-3:
+    resolution: {integrity: sha512-9jaqR6e7Ohds+aWwmhe6wILJ99xYQbfmK9QQB9CcMjDbTxPZjwEmUQpU91OG05Xgm8BahT5fW+svbsQGjS/zPg==}
+
+  css-color-keywords@1.0.0:
+    resolution: {integrity: sha512-FyyrDHZKEjXDpNJYvVsV960FiqQyXc/LlYmsxl2BcdMb2WPx0OGRVgTg55rPSyLSNMqP52R9r8geSp7apN3Ofg==}
+    engines: {node: '>=4'}
+
+  css-declaration-sorter@6.4.1:
+    resolution: {integrity: sha512-rtdthzxKuyq6IzqX6jEcIzQF/YqccluefyCYheovBOLhFT/drQA9zj/UbRAa9J7C0o6EG6u3E6g+vKkay7/k3g==}
+    engines: {node: ^10 || ^12 || >=14}
+    peerDependencies:
+      postcss: ^8.0.9
+
+  css-declaration-sorter@7.4.0:
+    resolution: {integrity: sha512-LTuzjPoyA2vMGKKcaOqKSp7Ub2eGrNfKiZH4LpezxpNrsICGCSFvsQOI29psISxNZtaXibkC2CXzrQ5enMeGGw==}
+    engines: {node: ^14 || ^16 || >=18}
+    peerDependencies:
+      postcss: ^8.0.9
+
+  css-gradient-parser@0.0.16:
+    resolution: {integrity: sha512-3O5QdqgFRUbXvK1x5INf1YkBz1UKSWqrd63vWsum8MNHDBYD5urm3QtxZbKU259OrEXNM26lP/MPY3d1IGkBgA==}
+    engines: {node: '>=16'}
+
+  css-select@4.3.0:
+    resolution: {integrity: sha512-wPpOYtnsVontu2mODhA19JrqWxNsfdatRKd64kmpRbQgh1KtItko5sTnEpPdpSaJszTOhEMlF/RPz28qj4HqhQ==}
+
+  css-to-react-native@3.2.0:
+    resolution: {integrity: sha512-e8RKaLXMOFii+02mOlqwjbD00KSEKqblnpO9e++1aXS1fPQOpS1YoqdVHBqPjHNoxeF2mimzVqawm2KCbEdtHQ==}
+
+  css-tree@1.1.3:
+    resolution: {integrity: sha512-tRpdppF7TRazZrjJ6v3stzv93qxRcSsFmW6cX0Zm2NVKpxE1WV1HblnghVv9TreireHkqI/VDEsfolRF1p6y7Q==}
+    engines: {node: '>=8.0.0'}
+
+  css-what@6.2.2:
+    resolution: {integrity: sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==}
+    engines: {node: '>= 6'}
+
+  css.escape@1.5.1:
+    resolution: {integrity: sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==}
+
+  cssesc@3.0.0:
+    resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  cssnano-preset-default@5.2.14:
+    resolution: {integrity: sha512-t0SFesj/ZV2OTylqQVOrFgEh5uanxbO6ZAdeCrNsUQ6fVuXwYTxJPNAGvGTxHbD68ldIJNec7PyYZDBrfDQ+6A==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  cssnano-utils@3.1.0:
+    resolution: {integrity: sha512-JQNR19/YZhz4psLX/rQ9M83e3z2Wf/HdJbryzte4a3NSuafyp9w/I4U+hx5C2S9g41qlstH7DEWnZaaj83OuEA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  cssnano@5.1.15:
+    resolution: {integrity: sha512-j+BKgDcLDQA+eDifLx0EO4XSA56b7uut3BQFH+wbSaSTuGLuiyTa/wbRYthUXX8LC9mLg+WWKe8h+qJuwTAbHw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  csso@4.2.0:
+    resolution: {integrity: sha512-wvlcdIbf6pwKEk7vHj8/Bkc0B4ylXZruLvOgs9doS5eOsOpuodOV2zJChSpkp+pRpYQLQMeF04nr3Z68Sta9jA==}
+    engines: {node: '>=8.0.0'}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  culori@3.3.0:
+    resolution: {integrity: sha512-pHJg+jbuFsCjz9iclQBqyL3B2HLCBF71BwVNujUYEvCeQMvV97R59MNK3R2+jgJ3a1fcZgI9B3vYgz8lzr/BFQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  culori@4.0.2:
+    resolution: {integrity: sha512-1+BhOB8ahCn4O0cep0Sh2l9KCOfOdY+BXJnKMHFFzDEouSr/el18QwXEMRlOj9UY5nCeA8UN3a/82rUWRBeyBw==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  damerau-levenshtein@1.0.8:
+    resolution: {integrity: sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==}
+
+  data-view-buffer@1.0.2:
+    resolution: {integrity: sha512-EmKO5V3OLXh1rtK2wgXRansaK1/mtVdTUEiEI0W8RkvgT05kfxaH29PliLnpLP73yYO6142Q72QNa8Wx/A5CqQ==}
+    engines: {node: '>= 0.4'}
+
+  data-view-byte-length@1.0.2:
+    resolution: {integrity: sha512-tuhGbE6CfTM9+5ANGf+oQb72Ky/0+s3xKUpHvShfiz2RxMFgFPjsXuRLBVMtvMs15awe45SRb83D6wH4ew6wlQ==}
+    engines: {node: '>= 0.4'}
+
+  data-view-byte-offset@1.0.1:
+    resolution: {integrity: sha512-BS8PfmtDGnrgYdOonGZQdLZslWIeCGFP9tpan0hi1Co2Zr2NKADsvGYA8XxuG/4UWgJ6Cjtv+YJnB6MM69QGlQ==}
+    engines: {node: '>= 0.4'}
+
+  debug@3.2.7:
+    resolution: {integrity: sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decimal.js@10.6.0:
+    resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==}
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
+  deep-eql@5.0.2:
+    resolution: {integrity: sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==}
+    engines: {node: '>=6'}
+
+  deep-is@0.1.4:
+    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+
+  deepmerge@4.3.1:
+    resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
+    engines: {node: '>=0.10.0'}
+
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  define-data-property@1.1.4:
+    resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
+    engines: {node: '>= 0.4'}
+
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
+  define-properties@1.2.1:
+    resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
+    engines: {node: '>= 0.4'}
+
+  defu@6.1.7:
+    resolution: {integrity: sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  detect-libc@1.0.3:
+    resolution: {integrity: sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==}
+    engines: {node: '>=0.10'}
+    hasBin: true
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
+
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
+  doctrine@2.1.0:
+    resolution: {integrity: sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==}
+    engines: {node: '>=0.10.0'}
+
+  doctrine@3.0.0:
+    resolution: {integrity: sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==}
+    engines: {node: '>=6.0.0'}
+
+  dom-accessibility-api@0.5.16:
+    resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
+
+  dom-accessibility-api@0.6.3:
+    resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}
+
+  dom-helpers@5.2.1:
+    resolution: {integrity: sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==}
+
+  dom-serializer@1.4.1:
+    resolution: {integrity: sha512-VHwB3KfrcOOkelEG2ZOfxqLZdfkil8PtJi4P8N2MMXucZq2yLp75ClViUlOVwyoHEDjYU433Aq+5zWP61+RGag==}
+
+  domelementtype@2.3.0:
+    resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==}
+
+  domhandler@4.3.1:
+    resolution: {integrity: sha512-GrwoxYN+uWlzO8uhUXRl0P+kHE4GtVPfYzVLcUxPL7KNdHKj66vvlhiweIHqYYXWlw+T8iLMp42Lm67ghw4WMQ==}
+    engines: {node: '>= 4'}
+
+  domutils@2.8.0:
+    resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==}
+
+  dot-prop@5.3.0:
+    resolution: {integrity: sha512-QM8q3zDe58hqUqjraQOmzZ1LIH9SWQJTlEKCH4kJ2oQvLZk7RbQXvtDM2XEq3fwkV9CCvvH4LA0AV+ogFsBM2Q==}
+    engines: {node: '>=8'}
+
+  dot-prop@6.0.1:
+    resolution: {integrity: sha512-tE7ztYzXHIeyvc7N+hR3oi7FIbf/NIjVP9hmAt3yMXzrQ072/fpjGLx2GxNxGxUl5V73MEqYzioOMoVhGMJ5cA==}
+    engines: {node: '>=10'}
+
+  dotenv-cli@11.0.0:
+    resolution: {integrity: sha512-r5pA8idbk7GFWuHEU7trSTflWcdBpQEK+Aw17UrSHjS6CReuhrrPcyC3zcQBPQvhArRHnBo/h6eLH1fkCvNlww==}
+    hasBin: true
+
+  dotenv-expand@11.0.7:
+    resolution: {integrity: sha512-zIHwmZPRshsCdpMDyVsqGmgyP0yT8GAgXUnkdAoJisxvf33k7yO6OuoKmcTGuXPWSsm8Oh88nZicRLA9Y0rUeA==}
+    engines: {node: '>=12'}
+
+  dotenv-expand@12.0.3:
+    resolution: {integrity: sha512-uc47g4b+4k/M/SeaW1y4OApx+mtLWl92l5LMPP0GNXctZqELk+YGgOPIIC5elYmUH4OuoK3JLhuRUYegeySiFA==}
+    engines: {node: '>=12'}
+
+  dotenv@16.6.1:
+    resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
+    engines: {node: '>=12'}
+
+  dotenv@17.2.3:
+    resolution: {integrity: sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w==}
+    engines: {node: '>=12'}
+
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
+  electron-to-chromium@1.5.368:
+    resolution: {integrity: sha512-7RckJJK4uESJF9PxvfMWd3TGqIiieUTG4HxnKaKuIpGbcr+r2ZEB3g2gAhCP3Fqm42vJSzLfgab9eva/C4/XVw==}
+
+  emoji-regex-xs@2.0.1:
+    resolution: {integrity: sha512-1QFuh8l7LqUcKe24LsPUNzjrzJQ7pgRwp1QMcZ5MX6mFplk2zQ08NVCM84++1cveaUUYtcCYHmeFEuNg16sU4g==}
+    engines: {node: '>=10.0.0'}
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  emoji-regex@9.2.2:
+    resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
+
+  empathic@2.0.1:
+    resolution: {integrity: sha512-YGRs8knHhKHVShLkFET/rWAU8kmHbOV5LwN938RHI0pljAJ1Gf6SzXsSmRaEzcXTtOOmVqJ5+WtQPL5uigY50Q==}
+    engines: {node: '>=14'}
+
+  enhanced-resolve@5.23.0:
+    resolution: {integrity: sha512-yJN/BOOLxcOW2aQgeif9mSnaUB8KtvmMMp56oA1kx1CRfBKbhZm2pJ+NBY+3eOboHxix8lfjWpHE0Ei5U8RbSA==}
+    engines: {node: '>=10.13.0'}
+
+  entities@2.2.0:
+    resolution: {integrity: sha512-p92if5Nz619I0w+akJrLZH0MX0Pb5DX39XOwQTtXSdQQOaYH03S1uIQp4mhOZtAXrxq4ViO67YTiLBo2638o9A==}
+
+  entities@6.0.1:
+    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
+    engines: {node: '>=0.12'}
+
+  env-paths@2.2.1:
+    resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
+    engines: {node: '>=6'}
+
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
+
+  es-abstract@1.24.2:
+    resolution: {integrity: sha512-2FpH9Q5i2RRwyEP1AylXe6nYLR5OhaJTZwmlcP0dL/+JCbgg7yyEo/sEK6HeGZRf3dFpWwThaRHVApXSkW3xeg==}
+    engines: {node: '>= 0.4'}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-iterator-helpers@1.3.2:
+    resolution: {integrity: sha512-HVLACW1TppGYjJ8H6/jqH/pqOtKRw6wMlrB23xfExmFWxFquAIWCmwoLsOyN96K4a5KbmOf5At9ZUO3GZbetAw==}
+    engines: {node: '>= 0.4'}
+
+  es-module-lexer@1.7.0:
+    resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==}
+
+  es-object-atoms@1.1.2:
+    resolution: {integrity: sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==}
+    engines: {node: '>= 0.4'}
+
+  es-set-tostringtag@2.1.0:
+    resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
+    engines: {node: '>= 0.4'}
+
+  es-shim-unscopables@1.1.0:
+    resolution: {integrity: sha512-d9T8ucsEhh8Bi1woXCf+TIKDIROLG5WCkxg8geBCbvk22kzwC5G2OnXVMO6FUsvQlgUUXQ2itephWDLqDzbeCw==}
+    engines: {node: '>= 0.4'}
+
+  es-to-primitive@1.3.0:
+    resolution: {integrity: sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g==}
+    engines: {node: '>= 0.4'}
+
+  es-toolkit@1.47.0:
+    resolution: {integrity: sha512-n1GuoD0WEQZMBk5tttoZSqwgyLx01oqa5XsBmCHwPyNe1S9jPBEmtR2pSgp2kJuWE3ciFZ6yRHmY4pM4C3OOkw==}
+
+  esast-util-from-estree@2.0.0:
+    resolution: {integrity: sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==}
+
+  esast-util-from-js@2.0.1:
+    resolution: {integrity: sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==}
+
+  esbuild@0.25.12:
+    resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  esbuild@0.27.7:
+    resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
+  eslint-config-next@16.1.1:
+    resolution: {integrity: sha512-55nTpVWm3qeuxoQKLOjQVciKZJUphKrNM0fCcQHAIOGl6VFXgaqeMfv0aKJhs7QtcnlAPhNVqsqRfRjeKBPIUA==}
+    peerDependencies:
+      eslint: '>=9.0.0'
+      typescript: '>=3.3.1'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  eslint-config-prettier@10.1.8:
+    resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==}
+    hasBin: true
+    peerDependencies:
+      eslint: '>=7.0.0'
+
+  eslint-import-resolver-node@0.3.10:
+    resolution: {integrity: sha512-tRrKqFyCaKict5hOd244sL6EQFNycnMQnBe+j8uqGNXYzsImGbGUU4ibtoaBmv5FLwJwcFJNeg1GeVjQfbMrDQ==}
+
+  eslint-import-resolver-typescript@3.10.1:
+    resolution: {integrity: sha512-A1rHYb06zjMGAxdLSkN2fXPBwuSaQ0iO5M/hdyS0Ajj1VBaRp0sPD3dn1FhME3c/JluGFbwSxyCfqdSbtQLAHQ==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      eslint: '*'
+      eslint-plugin-import: '*'
+      eslint-plugin-import-x: '*'
+    peerDependenciesMeta:
+      eslint-plugin-import:
+        optional: true
+      eslint-plugin-import-x:
+        optional: true
+
+  eslint-module-utils@2.13.0:
+    resolution: {integrity: sha512-bLohSkT6469rRs8czj0tLTD8vaeIS/whvPRJVjDr7IuoTT1k5DYDERlNycjDj/HkOlvQdYurmfZ/g3fG5bgeLQ==}
+    engines: {node: '>=4'}
+    peerDependencies:
+      '@typescript-eslint/parser': '*'
+      eslint: '*'
+      eslint-import-resolver-node: '*'
+      eslint-import-resolver-typescript: '*'
+      eslint-import-resolver-webpack: '*'
+    peerDependenciesMeta:
+      '@typescript-eslint/parser':
+        optional: true
+      eslint:
+        optional: true
+      eslint-import-resolver-node:
+        optional: true
+      eslint-import-resolver-typescript:
+        optional: true
+      eslint-import-resolver-webpack:
+        optional: true
+
+  eslint-plugin-import@2.32.0:
+    resolution: {integrity: sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==}
+    engines: {node: '>=4'}
+    peerDependencies:
+      '@typescript-eslint/parser': '*'
+      eslint: ^2 || ^3 || ^4 || ^5 || ^6 || ^7.2.0 || ^8 || ^9
+    peerDependenciesMeta:
+      '@typescript-eslint/parser':
+        optional: true
+
+  eslint-plugin-jsx-a11y@6.10.2:
+    resolution: {integrity: sha512-scB3nz4WmG75pV8+3eRUQOHZlNSUhFNq37xnpgRkCCELU3XMvXAxLk1eqWWyE22Ki4Q01Fnsw9BA3cJHDPgn2Q==}
+    engines: {node: '>=4.0'}
+    peerDependencies:
+      eslint: ^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9
+
+  eslint-plugin-only-warn@1.1.0:
+    resolution: {integrity: sha512-2tktqUAT+Q3hCAU0iSf4xAN1k9zOpjK5WO8104mB0rT/dGhOa09582HN5HlbxNbPRZ0THV7nLGvzugcNOSjzfA==}
+    engines: {node: '>=6'}
+
+  eslint-plugin-prettier@5.5.4:
+    resolution: {integrity: sha512-swNtI95SToIz05YINMA6Ox5R057IMAmWZ26GqPxusAp1TZzj+IdY9tXNWWD3vkF/wEqydCONcwjTFpxybBqZsg==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      '@types/eslint': '>=8.0.0'
+      eslint: '>=8.0.0'
+      eslint-config-prettier: '>= 7.0.0 <10.0.0 || >=10.1.0'
+      prettier: '>=3.0.0'
+    peerDependenciesMeta:
+      '@types/eslint':
+        optional: true
+      eslint-config-prettier:
+        optional: true
+
+  eslint-plugin-react-hooks@7.0.1:
+    resolution: {integrity: sha512-O0d0m04evaNzEPoSW+59Mezf8Qt0InfgGIBJnpC0h3NH/WjUAR7BIKUfysC6todmtiZ/A0oUVS8Gce0WhBrHsA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      eslint: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0
+
+  eslint-plugin-react-refresh@0.4.26:
+    resolution: {integrity: sha512-1RETEylht2O6FM/MvgnyvT+8K21wLqDNg4qD51Zj3guhjt433XbnnkVttHMyaVyAFD03QSV4LPS5iE3VQmO7XQ==}
+    peerDependencies:
+      eslint: '>=8.40'
+
+  eslint-plugin-react@7.37.5:
+    resolution: {integrity: sha512-Qteup0SqU15kdocexFNAJMvCJEfa2xUKNV4CC1xsVMrIIqEy3SQ/rqyxCWNzfrd3/ldy6HMlD2e0JDVpDg2qIA==}
+    engines: {node: '>=4'}
+    peerDependencies:
+      eslint: ^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9.7
+
+  eslint-plugin-sort-destructure-keys@2.0.0:
+    resolution: {integrity: sha512-4w1UQCa3o/YdfWaLr9jY8LfGowwjwjmwClyFLxIsToiyIdZMq3x9Ti44nDn34DtTPP7PWg96tUONKVmATKhYGQ==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      eslint: 5 - 9
+
+  eslint-plugin-sort-keys-fix@1.1.2:
+    resolution: {integrity: sha512-DNPHFGCA0/hZIsfODbeLZqaGY/+q3vgtshF85r+YWDNCQ2apd9PNs/zL6ttKm0nD1IFwvxyg3YOTI7FHl4unrw==}
+    engines: {node: '>=0.10.0'}
+
+  eslint-plugin-storybook@10.1.10:
+    resolution: {integrity: sha512-ITr6Aq3buR/DuDATkq1BafUVJLybyo676fY+tj9Zjd1Ak+UXBAMQcQ++tiBVVHm1RqADwM3b1o6bnWHK2fPPKw==}
+    peerDependencies:
+      eslint: '>=8'
+      storybook: ^10.1.10
+
+  eslint-plugin-unused-imports@4.3.0:
+    resolution: {integrity: sha512-ZFBmXMGBYfHttdRtOG9nFFpmUvMtbHSjsKrS20vdWdbfiVYsO3yA2SGYy9i9XmZJDfMGBflZGBCm70SEnFQtOA==}
+    peerDependencies:
+      '@typescript-eslint/eslint-plugin': ^8.0.0-0 || ^7.0.0 || ^6.0.0 || ^5.0.0
+      eslint: ^9.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@typescript-eslint/eslint-plugin':
+        optional: true
+
+  eslint-scope@8.4.0:
+    resolution: {integrity: sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@1.3.0:
+    resolution: {integrity: sha512-6J72N8UNa462wa/KFODt/PJ3IU60SDpC3QXC1Hjc1BXXpfL2C9R5+AU7jhe0F6GREqVMh4Juu+NY7xn+6dipUQ==}
+    engines: {node: '>=4'}
+
+  eslint-visitor-keys@3.4.3:
+    resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
+  eslint-visitor-keys@4.2.1:
+    resolution: {integrity: sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@5.0.1:
+    resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint@9.39.2:
+    resolution: {integrity: sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    hasBin: true
+    peerDependencies:
+      jiti: '*'
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+
+  esm@3.2.25:
+    resolution: {integrity: sha512-U1suiZ2oDVWv4zPO56S0NcR5QriEahGtdN2OR6FiOG4WJvcjBVFB0qI4+eKoWFH483PKGuLuu6V8Z4T5g63UVA==}
+    engines: {node: '>=6'}
+
+  espree@10.4.0:
+    resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  espree@6.2.1:
+    resolution: {integrity: sha512-ysCxRQY3WaXJz9tdbWOwuWr5Y/XrPTGX9Kiz3yoUXwW0VZ4w30HTkQLaGx/+ttFjF8i+ACbArnB4ce68a9m5hw==}
+    engines: {node: '>=6.0.0'}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  esquery@1.7.0:
+    resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
+    engines: {node: '>=0.10'}
+
+  esrecurse@4.3.0:
+    resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
+    engines: {node: '>=4.0'}
+
+  estraverse@5.3.0:
+    resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
+    engines: {node: '>=4.0'}
+
+  estree-util-attach-comments@3.0.0:
+    resolution: {integrity: sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==}
+
+  estree-util-build-jsx@3.0.1:
+    resolution: {integrity: sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==}
+
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
+  estree-util-scope@1.0.0:
+    resolution: {integrity: sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==}
+
+  estree-util-to-js@2.0.0:
+    resolution: {integrity: sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==}
+
+  estree-util-value-to-estree@3.5.0:
+    resolution: {integrity: sha512-aMV56R27Gv3QmfmF1MY12GWkGzzeAezAX+UplqHVASfjc9wNzI/X6hC0S9oxq61WT4aQesLGslWP9tKk6ghRZQ==}
+
+  estree-util-visit@2.0.0:
+    resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==}
+
+  estree-walker@0.6.1:
+    resolution: {integrity: sha512-SqmZANLWS0mnatqbSfRP5g8OXZC12Fgg1IwNtLsyHDzJizORW4khDfjPqJZsemPWBB2uqykUah5YpQ6epsqC/w==}
+
+  estree-walker@2.0.2:
+    resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  esutils@2.0.3:
+    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
+    engines: {node: '>=0.10.0'}
+
+  eventemitter3@4.0.7:
+    resolution: {integrity: sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==}
+
+  eventemitter3@5.0.4:
+    resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
+
+  expect-type@1.3.0:
+    resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
+    engines: {node: '>=12.0.0'}
+
+  extend-shallow@2.0.1:
+    resolution: {integrity: sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==}
+    engines: {node: '>=0.10.0'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-diff@1.3.0:
+    resolution: {integrity: sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==}
+
+  fast-glob@3.3.1:
+    resolution: {integrity: sha512-kNFPyjhh5cKjrUltxs+wFx+ZkbRaxxmZ+X0ZU31SOsxCEtP9VPgtq2teZw1DebupL5GmDaNQ6yKMMVcM41iqDg==}
+    engines: {node: '>=8.6.0'}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
+  fast-json-stable-stringify@2.1.0:
+    resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
+
+  fast-levenshtein@2.0.6:
+    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+
+  fast-uri@3.1.2:
+    resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==}
+
+  fastq@1.20.1:
+    resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  feed@5.1.0:
+    resolution: {integrity: sha512-qGNhgYygnefSkAHHrNHqC7p3R8J0/xQDS/cYUud8er/qD9EFGWyCdUDfULHTJQN1d3H3WprzVwMc9MfB4J50Wg==}
+    engines: {node: '>=20', pnpm: '>=10'}
+
+  fflate@0.7.4:
+    resolution: {integrity: sha512-5u2V/CDW15QM1XbbgS+0DfPxVB+jUKhWEKuuFuHncbk3tEEqzmoXL+2KyOFuKGqOnmdIy0/davWF1CkuwtibCw==}
+
+  file-entry-cache@8.0.0:
+    resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
+    engines: {node: '>=16.0.0'}
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  find-up@5.0.0:
+    resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
+    engines: {node: '>=10'}
+
+  fix-dts-default-cjs-exports@1.0.1:
+    resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
+
+  flat-cache@4.0.1:
+    resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
+    engines: {node: '>=16'}
+
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
+
+  for-each@0.3.5:
+    resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
+    engines: {node: '>= 0.4'}
+
+  framer-motion@12.40.0:
+    resolution: {integrity: sha512-uaBd3qC1v3KQqBEjwTUd183K6PbS+j0yR9w9VmEOLWA/tnUcSn8Xa3uck7t4dgpDoUss8xQTcj8W2L07lrnLFg==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
+  fs-extra@11.3.3:
+    resolution: {integrity: sha512-VWSRii4t0AFm6ixFFmLLx1t7wS1gh+ckoa84aOeapGum0h+EZd1EhEumSB+ZdDLnEPuucsVB9oB7cxJHap6Afg==}
+    engines: {node: '>=14.14'}
+
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  fumadocs-core@16.9.0:
+    resolution: {integrity: sha512-L5bXpKsN0m7kK483KqviQ7g0l6PA7M32K5yCXS0KUrVWJDUu038ASb08G59RFwWjxhahCAHf0H0ntwzF91lqnQ==}
+    peerDependencies:
+      '@mdx-js/mdx': '*'
+      '@mixedbread/sdk': 0.x.x
+      '@orama/core': 1.x.x
+      '@oramacloud/client': 2.x.x
+      '@tanstack/react-router': 1.x.x
+      '@types/estree-jsx': '*'
+      '@types/hast': '*'
+      '@types/mdast': '*'
+      '@types/react': '*'
+      algoliasearch: 5.x.x
+      flexsearch: '*'
+      lucide-react: '*'
+      next: 16.x.x
+      react: ^19.2.0
+      react-dom: ^19.2.0
+      react-router: 7.x.x
+      waku: '*'
+      zod: 4.x.x
+    peerDependenciesMeta:
+      '@mdx-js/mdx':
+        optional: true
+      '@mixedbread/sdk':
+        optional: true
+      '@orama/core':
+        optional: true
+      '@oramacloud/client':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      '@types/estree-jsx':
+        optional: true
+      '@types/hast':
+        optional: true
+      '@types/mdast':
+        optional: true
+      '@types/react':
+        optional: true
+      algoliasearch:
+        optional: true
+      flexsearch:
+        optional: true
+      lucide-react:
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+      react-router:
+        optional: true
+      waku:
+        optional: true
+      zod:
+        optional: true
+
+  fumadocs-mdx@14.2.2:
+    resolution: {integrity: sha512-ClRjZd5WloWhbNHcUgA0PvbiTFuVKjv+qmrfF4aAeHzae6jeZtm1dvSYZ6iKoEHjFz6bt3UqiCgLHAUuXS8ifg==}
+    hasBin: true
+    peerDependencies:
+      '@fumadocs/mdx-remote': ^1.4.0
+      '@types/react': '*'
+      fumadocs-core: ^15.0.0 || ^16.0.0
+      next: ^15.3.0 || ^16.0.0
+      react: '*'
+      vite: 6.x.x || 7.x.x
+    peerDependenciesMeta:
+      '@fumadocs/mdx-remote':
+        optional: true
+      '@types/react':
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      vite:
+        optional: true
+
+  fumadocs-typescript@5.0.0:
+    resolution: {integrity: sha512-j41gj+/ZOGRZHdh+8teLErfqVAwaK3wK7dS04OSp5BMxJsJxRrHXOlClTOB+w2rnT3Tr4hZI4C8tXuXcvmaXlw==}
+    peerDependencies:
+      '@types/react': '*'
+      fumadocs-core: ^15.7.0 || ^16.0.0
+      fumadocs-ui: ^15.7.0 || ^16.0.0
+      typescript: '*'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      fumadocs-ui:
+        optional: true
+
+  fumadocs-ui@16.9.0:
+    resolution: {integrity: sha512-z4w93vuhrsNp1cup7mcEoo8GSDQRCgDMkGnIvUEz+YB7IwSDhrUqf3lXuSKDaqPLXPdRvR0Cf+BAqARBW71c0Q==}
+    peerDependencies:
+      '@takumi-rs/image-response': '*'
+      '@types/mdx': '*'
+      '@types/react': '*'
+      fumadocs-core: 16.9.0
+      next: 16.x.x
+      react: ^19.2.0
+      react-dom: ^19.2.0
+    peerDependenciesMeta:
+      '@takumi-rs/image-response':
+        optional: true
+      '@types/mdx':
+        optional: true
+      '@types/react':
+        optional: true
+      next:
+        optional: true
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  function.prototype.name@1.1.8:
+    resolution: {integrity: sha512-e5iwyodOHhbMr/yNrc7fDYG4qlbIvI5gajyzPnb5TCwyhjApznQh1BMFou9b30SevY43gCJKXycoCBjMbsuW0Q==}
+    engines: {node: '>= 0.4'}
+
+  functions-have-names@1.2.3:
+    resolution: {integrity: sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==}
+
+  generator-function@2.0.1:
+    resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
+    engines: {node: '>= 0.4'}
+
+  generic-names@4.0.0:
+    resolution: {integrity: sha512-ySFolZQfw9FoDb3ed9d80Cm9f0+r7qj+HJkWjeD9RBfpxEVTlVhol+gvaQB/78WbwYfbnNh8nWHHBSlg072y6A==}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-east-asian-width@1.6.0:
+    resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
+    engines: {node: '>=18'}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
+    engines: {node: '>=6'}
+
+  get-port@4.2.0:
+    resolution: {integrity: sha512-/b3jarXkH8KJoOMQc3uVGHASwGLPq3gSFJ7tgJm2diza+bydJPTGOibin2steecKeOylE8oY2JERlVWkAJO6yw==}
+    engines: {node: '>=6'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  get-symbol-description@1.1.0:
+    resolution: {integrity: sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg==}
+    engines: {node: '>= 0.4'}
+
+  get-tsconfig@4.14.0:
+    resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}
+
+  git-raw-commits@5.0.1:
+    resolution: {integrity: sha512-Y+csSm2GD/PCSh6Isd/WiMjNAydu0VBiG9J7EdQsNA5P9uXvLayqjmTsNlK5Gs9IhblFZqOU0yid5Il5JPoLiQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  github-slugger@2.0.0:
+    resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
+  glob-parent@6.0.2:
+    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
+    engines: {node: '>=10.13.0'}
+
+  glob@13.0.0:
+    resolution: {integrity: sha512-tvZgpqk6fz4BaNZ66ZsRaZnbHvP/jG3uKJvAZOwEVUL4RTA5nJeeLYfyN9/VA8NX/V3IBG+hkeuGpKjvELkVhA==}
+    engines: {node: 20 || >=22}
+
+  glob@13.0.6:
+    resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
+    engines: {node: 18 || 20 || >=22}
+
+  global-directory@5.0.0:
+    resolution: {integrity: sha512-1pgFdhK3J2LeM+dVf2Pd424yHx2ou338lC0ErNP2hPx4j8eW1Sp0XqSjNxtk6Tc4Kr5wlWtSvz8cn2yb7/SG/w==}
+    engines: {node: '>=20'}
+
+  globals@13.24.0:
+    resolution: {integrity: sha512-AhO5QUcj8llrbG09iWhPU2B204J1xnPeL8kQmVorSsy+Sjj1sk8gIyh6cUocGmH4L0UuhAJy+hJMRA4mgA4mFQ==}
+    engines: {node: '>=8'}
+
+  globals@14.0.0:
+    resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
+    engines: {node: '>=18'}
+
+  globals@16.4.0:
+    resolution: {integrity: sha512-ob/2LcVVaVGCYN+r14cnwnoDPUufjiYgSqRhiFD0Q1iI4Odora5RE8Iv1D24hAz5oMophRGkGz+yuvQmmUMnMw==}
+    engines: {node: '>=18'}
+
+  globals@16.5.0:
+    resolution: {integrity: sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==}
+    engines: {node: '>=18'}
+
+  globalthis@1.0.4:
+    resolution: {integrity: sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==}
+    engines: {node: '>= 0.4'}
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  gray-matter@4.0.3:
+    resolution: {integrity: sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==}
+    engines: {node: '>=6.0'}
+
+  has-bigints@1.1.0:
+    resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==}
+    engines: {node: '>= 0.4'}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-property-descriptors@1.0.2:
+    resolution: {integrity: sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==}
+
+  has-proto@1.2.0:
+    resolution: {integrity: sha512-KIL7eQPfHQRC8+XluaIw7BHUwwqL19bQn4hzNgdr+1wXoU0KKj6rufu47lhY7KbJR2C6T6+PfyN0Ea7wkSS+qQ==}
+    engines: {node: '>= 0.4'}
+
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  has-tostringtag@1.0.2:
+    resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
+    engines: {node: '>= 0.4'}
+
+  hast-util-from-parse5@8.0.3:
+    resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
+
+  hast-util-parse-selector@4.0.0:
+    resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==}
+
+  hast-util-raw@9.1.0:
+    resolution: {integrity: sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==}
+
+  hast-util-to-estree@3.1.3:
+    resolution: {integrity: sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==}
+
+  hast-util-to-html@9.0.5:
+    resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
+
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-to-parse5@8.0.1:
+    resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  hastscript@9.0.1:
+    resolution: {integrity: sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==}
+
+  hermes-estree@0.25.1:
+    resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
+
+  hermes-parser@0.25.1:
+    resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
+
+  hex-rgb@4.3.0:
+    resolution: {integrity: sha512-Ox1pJVrDCyGHMG9CFg1tmrRUMRPRsAWYc/PinY0XzJU4K7y7vjNoLKIQ7BR5UJMCxNN8EM1MNDmHWA/B3aZUuw==}
+    engines: {node: '>=6'}
+
+  html-void-elements@3.0.0:
+    resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
+  husky@9.1.7:
+    resolution: {integrity: sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  icss-replace-symbols@1.1.0:
+    resolution: {integrity: sha512-chIaY3Vh2mh2Q3RGXttaDIzeiPvaVXJ+C4DAh/w3c37SKZ/U6PGMmuicR2EQQp9bKG8zLMCl7I+PtIoOOPp8Gg==}
+
+  icss-utils@5.1.0:
+    resolution: {integrity: sha512-soFhflCVWLfRNOPU3iv5Z9VUdT44xFRbzjLsEzSr5AQmgqPMTHdU3PMT1Cf1ssx8fLNJDA1juftYl+PUcv3MqA==}
+    engines: {node: ^10 || ^12 || >= 14}
+    peerDependencies:
+      postcss: ^8.1.0
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  ignore@7.0.5:
+    resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
+    engines: {node: '>= 4'}
+
+  import-cwd@3.0.0:
+    resolution: {integrity: sha512-4pnzH16plW+hgvRECbDWpQl3cqtvSofHWh44met7ESfZ8UZOWWddm8hEyDTqREJ9RbYHY8gi8DqmaelApoOGMg==}
+    engines: {node: '>=8'}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
+  import-from@3.0.0:
+    resolution: {integrity: sha512-CiuXOFFSzkU5x/CR0+z7T91Iht4CXgfCxVOFRhh2Zyhg5wOpWvvDLQUsWl+gcN+QscYBjez8hDCt85O7RLDttQ==}
+    engines: {node: '>=8'}
+
+  import-meta-resolve@4.2.0:
+    resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
+
+  imurmurhash@0.1.4:
+    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
+    engines: {node: '>=0.8.19'}
+
+  indent-string@4.0.0:
+    resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==}
+    engines: {node: '>=8'}
+
+  ini@6.0.0:
+    resolution: {integrity: sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
+  input-otp@1.4.2:
+    resolution: {integrity: sha512-l3jWwYNvrEa6NTCt7BECfCm48GvwuZzkoeG3gBL2w4CHeOXW3eKFmf9UNYkNfYc3mxMrthMnxjIE07MT0zLBQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
+  internal-slot@1.1.0:
+    resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
+    engines: {node: '>= 0.4'}
+
+  intl-messageformat@10.7.18:
+    resolution: {integrity: sha512-m3Ofv/X/tV8Y3tHXLohcuVuhWKo7BBq62cqY15etqmLxg2DZ34AGGgQDeR+SCta2+zICb1NX83af0GJmbQ1++g==}
+
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
+  is-array-buffer@3.0.5:
+    resolution: {integrity: sha512-DDfANUiiG2wC1qawP66qlTugJeL5HyzMpfr8lLK+jMQirGzNod0B12cFB/9q838Ru27sBwfw78/rdoU7RERz6A==}
+    engines: {node: '>= 0.4'}
+
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
+
+  is-async-function@2.1.1:
+    resolution: {integrity: sha512-9dgM/cZBnNvjzaMYHVoxxfPj2QXt22Ev7SuuPrs+xav0ukGB0S6d4ydZdEiM48kLx5kDV+QBPrpVnFyefL8kkQ==}
+    engines: {node: '>= 0.4'}
+
+  is-bigint@1.1.0:
+    resolution: {integrity: sha512-n4ZT37wG78iz03xPRKJrHTdZbe3IicyucEtdRsV5yglwc3GyUfbAfpSeD0FJ41NbUNSt5wbhqfp1fS+BgnvDFQ==}
+    engines: {node: '>= 0.4'}
+
+  is-boolean-object@1.2.2:
+    resolution: {integrity: sha512-wa56o2/ElJMYqjCjGkXri7it5FbebW5usLw/nPmCMs5DeZ7eziSYZhSmPRn0txqeW4LnAmQQU7FgqLpsEFKM4A==}
+    engines: {node: '>= 0.4'}
+
+  is-bun-module@2.0.0:
+    resolution: {integrity: sha512-gNCGbnnnnFAUGKeZ9PdbyeGYJqewpmc2aKHUEMO5nQPWU9lOmv7jcmQIv+qHD8fXW6W7qfuCwX4rY9LNRjXrkQ==}
+
+  is-callable@1.2.7:
+    resolution: {integrity: sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==}
+    engines: {node: '>= 0.4'}
+
+  is-core-module@2.16.2:
+    resolution: {integrity: sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==}
+    engines: {node: '>= 0.4'}
+
+  is-data-view@1.0.2:
+    resolution: {integrity: sha512-RKtWF8pGmS87i2D6gqQu/l7EYRlVdfzemCJN/P3UOs//x1QE7mfhvzHIApBTRf7axvT6DMGwSwBXYCT0nfB9xw==}
+    engines: {node: '>= 0.4'}
+
+  is-date-object@1.1.0:
+    resolution: {integrity: sha512-PwwhEakHVKTdRNVOw+/Gyh0+MzlCl4R6qKvkhuvLtPMggI1WAHt9sOwZxQLSGpUaDnrdyDsomoRgNnCfKNSXXg==}
+    engines: {node: '>= 0.4'}
+
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
+  is-docker@3.0.0:
+    resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    hasBin: true
+
+  is-extendable@0.1.1:
+    resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==}
+    engines: {node: '>=0.10.0'}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-finalizationregistry@1.1.1:
+    resolution: {integrity: sha512-1pC6N8qWJbWoPtEjgcL2xyhQOP491EQjeUo3qTKcmV8YSDDJrOepfG8pcC7h/QgnQHYSv0mJ3Z/ZWxmatVrysg==}
+    engines: {node: '>= 0.4'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-fullwidth-code-point@5.1.0:
+    resolution: {integrity: sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==}
+    engines: {node: '>=18'}
+
+  is-generator-function@1.1.2:
+    resolution: {integrity: sha512-upqt1SkGkODW9tsGNG5mtXTXtECizwtS2kA161M+gJPc1xdb/Ax629af6YrTwcOeQHbewrPNlE5Dx7kzvXTizA==}
+    engines: {node: '>= 0.4'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
+  is-inside-container@1.0.0:
+    resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
+    engines: {node: '>=14.16'}
+    hasBin: true
+
+  is-map@2.0.3:
+    resolution: {integrity: sha512-1Qed0/Hr2m+YqxnM09CjA2d/i6YZNfF6R2oRAOj36eUdS6qIV/huPJNSEpKbupewFs+ZsJlxsjjPbc0/afW6Lw==}
+    engines: {node: '>= 0.4'}
+
+  is-module@1.0.0:
+    resolution: {integrity: sha512-51ypPSPCoTEIN9dy5Oy+h4pShgJmPCygKfyRCISBI+JoWT/2oJvK8QPxmwv7b/p239jXrm9M1mlQbyKJ5A152g==}
+
+  is-negative-zero@2.0.3:
+    resolution: {integrity: sha512-5KoIu2Ngpyek75jXodFvnafB6DJgr3u8uuK0LEZJjrU19DrMD3EVERaR8sjz8CCGgpZvxPl9SuE1GMVPFHx1mw==}
+    engines: {node: '>= 0.4'}
+
+  is-number-object@1.1.1:
+    resolution: {integrity: sha512-lZhclumE1G6VYD8VHe35wFaIif+CTy5SJIi5+3y4psDgWu4wPDoBhF8NxUOinEc7pHgiTsT6MaBb92rKhhD+Xw==}
+    engines: {node: '>= 0.4'}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-obj@2.0.0:
+    resolution: {integrity: sha512-drqDG3cbczxxEJRoOXcOjtdp1J/lyp1mNn0xaznRs8+muBhgQcrnbspox5X5fOw0HnMnbfDzvnEMEtqDEJEo8w==}
+    engines: {node: '>=8'}
+
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
+  is-reference@1.2.1:
+    resolution: {integrity: sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ==}
+
+  is-regex@1.2.1:
+    resolution: {integrity: sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==}
+    engines: {node: '>= 0.4'}
+
+  is-set@2.0.3:
+    resolution: {integrity: sha512-iPAjerrse27/ygGLxw+EBR9agv9Y6uLeYVJMu+QNCoouJ1/1ri0mGrcWpfCqFZuzzx3WjtwxG098X+n4OuRkPg==}
+    engines: {node: '>= 0.4'}
+
+  is-shared-array-buffer@1.0.4:
+    resolution: {integrity: sha512-ISWac8drv4ZGfwKl5slpHG9OwPNty4jOWPRIhBpxOoD+hqITiwuipOQ2bNthAzwA3B4fIjO4Nln74N0S9byq8A==}
+    engines: {node: '>= 0.4'}
+
+  is-string@1.1.1:
+    resolution: {integrity: sha512-BtEeSsoaQjlSPBemMQIrY1MY0uM6vnS1g5fmufYOtnxLGUZM2178PKbhsk7Ffv58IX+ZtcvoGwccYsh0PglkAA==}
+    engines: {node: '>= 0.4'}
+
+  is-symbol@1.1.1:
+    resolution: {integrity: sha512-9gGx6GTtCQM73BgmHQXfDmLtfjjTUDSyoxTCbp5WtoixAhfgsDirWIcVQ/IHpvI5Vgd5i/J5F7B9cN/WlVbC/w==}
+    engines: {node: '>= 0.4'}
+
+  is-typed-array@1.1.15:
+    resolution: {integrity: sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==}
+    engines: {node: '>= 0.4'}
+
+  is-weakmap@2.0.2:
+    resolution: {integrity: sha512-K5pXYOm9wqY1RgjpL3YTkF39tni1XajUIkawTLUo9EZEVUFga5gSQJF8nNS7ZwJQ02y+1YCNYcMh+HIf1ZqE+w==}
+    engines: {node: '>= 0.4'}
+
+  is-weakref@1.1.1:
+    resolution: {integrity: sha512-6i9mGWSlqzNMEqpCp93KwRS1uUOodk2OJ6b+sq7ZPDSy2WuI5NFIxp/254TytR8ftefexkWn5xNiHUNpPOfSew==}
+    engines: {node: '>= 0.4'}
+
+  is-weakset@2.0.4:
+    resolution: {integrity: sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==}
+    engines: {node: '>= 0.4'}
+
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
+  isarray@2.0.5:
+    resolution: {integrity: sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  iterator.prototype@1.1.5:
+    resolution: {integrity: sha512-H0dkQoCa3b2VEeKQBOxFph+JAbcrQdE7KC0UkqwpLmv2EC4P41QXP+rqo9wYodACiG5/WM5s9oDApTU8utwj9g==}
+    engines: {node: '>= 0.4'}
+
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+    hasBin: true
+
+  joycon@3.1.1:
+    resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
+    engines: {node: '>=10'}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@3.14.2:
+    resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==}
+    hasBin: true
+
+  js-yaml@4.2.0:
+    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
+    hasBin: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-buffer@3.0.1:
+    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
+
+  json-schema-traverse@0.4.1:
+    resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-stable-stringify-without-jsonify@1.0.1:
+    resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+
+  json5@1.0.2:
+    resolution: {integrity: sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA==}
+    hasBin: true
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
+  jsonfile@6.2.1:
+    resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
+
+  jsx-ast-utils@3.3.5:
+    resolution: {integrity: sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==}
+    engines: {node: '>=4.0'}
+
+  keyv@4.5.4:
+    resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
+
+  kind-of@6.0.3:
+    resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
+    engines: {node: '>=0.10.0'}
+
+  kleur@4.1.5:
+    resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
+    engines: {node: '>=6'}
+
+  language-subtag-registry@0.3.23:
+    resolution: {integrity: sha512-0K65Lea881pHotoGEa5gDlMxt3pctLi2RplBb7Ezh4rRdLEOtgi7n4EwK9lamnUCkKBqaeKRVebTq6BAxSkpXQ==}
+
+  language-tags@1.0.9:
+    resolution: {integrity: sha512-MbjN408fEndfiQXbFQ1vnd+1NoLDsnQW41410oQBXiyXDMYH5z505juWa4KUE1LqxRC7DgOgZDbKLxHIwm27hA==}
+    engines: {node: '>=0.10'}
+
+  levn@0.4.1:
+    resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
+    engines: {node: '>= 0.8.0'}
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  lilconfig@2.1.0:
+    resolution: {integrity: sha512-utWOt/GHzuUxnLKxB6dk81RoOeoNeHgbrXiuGk4yyF5qlRz+iIVWu56E2fqGHFrXz0QNUhLB/8nKqvRH66JKGQ==}
+    engines: {node: '>=10'}
+
+  lilconfig@3.1.3:
+    resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
+    engines: {node: '>=14'}
+
+  linebreak@1.1.0:
+    resolution: {integrity: sha512-MHp03UImeVhB7XZtjd0E4n6+3xr5Dq/9xI/5FptGk5FrbDR3zagPa2DS6U8ks/3HjbKWG9Q1M2ufOzxV2qLYSQ==}
+
+  lines-and-columns@1.2.4:
+    resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
+
+  lint-staged@16.2.7:
+    resolution: {integrity: sha512-lDIj4RnYmK7/kXMya+qJsmkRFkGolciXjrsZ6PC25GdTfWOAWetR0ZbsNXRAj1EHHImRSalc+whZFg56F5DVow==}
+    engines: {node: '>=20.17'}
+    hasBin: true
+
+  listr2@9.0.5:
+    resolution: {integrity: sha512-ME4Fb83LgEgwNw96RKNvKV4VTLuXfoKudAmm2lP8Kk87KaMK0/Xrx/aAkMWmT8mDb+3MlFDspfbCs7adjRxA2g==}
+    engines: {node: '>=20.0.0'}
+
+  lmdb@2.8.5:
+    resolution: {integrity: sha512-9bMdFfc80S+vSldBmG3HOuLVHnxRdNTlpzR6QDnzqCQtCzGUEAGTzBKYMeIM+I/sU4oZfgbcbS7X7F65/z/oxQ==}
+    hasBin: true
+
+  load-tsconfig@0.2.5:
+    resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  loader-utils@3.3.1:
+    resolution: {integrity: sha512-FMJTLMXfCLMLfJxcX9PFqX5qD88Z5MRGaZCVzfuqeZSPsyiBzs+pahDQjbIWz2QIzPZz0NX9Zy4FX3lmK6YHIg==}
+    engines: {node: '>= 12.13.0'}
+
+  locate-path@6.0.0:
+    resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
+    engines: {node: '>=10'}
+
+  lodash.camelcase@4.3.0:
+    resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
+
+  lodash.debounce@4.0.8:
+    resolution: {integrity: sha512-FT1yDzDYEoYWhnSGnpE/4Kj1fLZkDFyqRb7fNt6FdYOSxlUWAtp42Eh6Wb0rGIv/m9Bgo7x4GhQbm5Ys4SG5ow==}
+
+  lodash.memoize@4.1.2:
+    resolution: {integrity: sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag==}
+
+  lodash.merge@4.6.2:
+    resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
+
+  lodash.uniq@4.5.0:
+    resolution: {integrity: sha512-xfBaXQd9ryd9dlSDvnvI0lvxfLJlYAZzXomUYzLKtUeOQvOP5piqAWuGtrhWeqaXK9hhoM/iyJc5AV+XfsX3HQ==}
+
+  log-update@6.1.0:
+    resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
+    engines: {node: '>=18'}
+
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
+  loose-envify@1.4.0:
+    resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
+    hasBin: true
+
+  loupe@3.2.1:
+    resolution: {integrity: sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==}
+
+  lru-cache@11.5.1:
+    resolution: {integrity: sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==}
+    engines: {node: 20 || >=22}
+
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  lucide-react@0.562.0:
+    resolution: {integrity: sha512-82hOAu7y0dbVuFfmO4bYF1XEwYk/mEbM5E+b1jgci/udUBEE/R7LF5Ip0CCEmXe8AybRM8L+04eP+LGZeDvkiw==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  lucide-react@1.17.0:
+    resolution: {integrity: sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  lz-string@1.5.0:
+    resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
+    hasBin: true
+
+  m3-ripple@1.1.3:
+    resolution: {integrity: sha512-ERPnwcri3lsNKKvq8gCf4Hxbfkjeo9bdQt1PpoVTE5c5pPMulWAObbP/3D+/Rw55hjd6cph98nGVDzzCZmgeXQ==}
+    peerDependencies:
+      react: '>= 18.0.0'
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  markdown-extensions@2.0.0:
+    resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==}
+    engines: {node: '>=16'}
+
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdx@3.0.0:
+    resolution: {integrity: sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
+  mdn-data@2.0.14:
+    resolution: {integrity: sha512-dn6wd0uw5GsdswPFfsgMp5NSB0/aDe6fK94YJV/AJDYXL6HVLWBsxeq7js7Ad+mU2K9LAlwpk6kN2D5mwCPVow==}
+
+  meow@13.2.0:
+    resolution: {integrity: sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA==}
+    engines: {node: '>=18'}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-extension-mdx-expression@3.0.1:
+    resolution: {integrity: sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==}
+
+  micromark-extension-mdx-jsx@3.0.2:
+    resolution: {integrity: sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==}
+
+  micromark-extension-mdx-md@2.0.0:
+    resolution: {integrity: sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==}
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    resolution: {integrity: sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==}
+
+  micromark-extension-mdxjs@3.0.0:
+    resolution: {integrity: sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-mdx-expression@2.0.3:
+    resolution: {integrity: sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-events-to-acorn@2.0.3:
+    resolution: {integrity: sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
+  min-indent@1.0.1:
+    resolution: {integrity: sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==}
+    engines: {node: '>=4'}
+
+  minimatch@10.2.5:
+    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minimatch@3.1.5:
+    resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==}
+
+  minimatch@9.0.9:
+    resolution: {integrity: sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minizlib@3.1.0:
+    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
+    engines: {node: '>= 18'}
+
+  mlly@1.8.2:
+    resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==}
+
+  motion-dom@12.40.0:
+    resolution: {integrity: sha512-HxU3ZaBwNPVQUBQf1xxgq+7JrPNZvjLVxgbpEZL7RrWJnsxOf0/OM+yrHG9ogLQ31Do/r57Oz2gQWPK+6q62mg==}
+
+  motion-utils@12.39.0:
+    resolution: {integrity: sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==}
+
+  motion@12.23.26:
+    resolution: {integrity: sha512-Ll8XhVxY8LXMVYTCfme27WH2GjBrCIzY4+ndr5QKxsK+YwCtOi2B/oBi5jcIbik5doXuWT/4KKDOVAZJkeY5VQ==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
+  motion@12.40.0:
+    resolution: {integrity: sha512-yjrHUrBFW6kQvjJwRsoiPSAhC5tRwRqNGJWmiJ4CrGnbKp0V88AdzkhBmDoqIsIPfarOe0Uddd37Xq43/gIocA==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
+  mri@1.2.0:
+    resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
+    engines: {node: '>=4'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  msgpackr-extract@3.0.4:
+    resolution: {integrity: sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw==}
+    hasBin: true
+
+  msgpackr@1.11.13:
+    resolution: {integrity: sha512-pWaxg0k1iiNdkAayUQ7Zlz/vYNfVefUttmHxqFcQjjtyqFa3w4x5rginOEzy/GvbWhBDD9K65/ZXyq8qz8utaQ==}
+
+  mz@2.7.0:
+    resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
+
+  nano-spawn@2.1.0:
+    resolution: {integrity: sha512-yTW+2okrElHiH4fsiz/+/zc0EDo9BDDoC3iKk8dpv1GeRc9nUWzUZHx6TofMWErchhUQR8hY9/Eu1Uja9x1nqA==}
+    engines: {node: '>=20.17'}
+
+  nanoid@3.3.12:
+    resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  napi-postinstall@0.3.4:
+    resolution: {integrity: sha512-PHI5f1O0EP5xJ9gQmFGMS6IZcrVvTjpXjz7Na41gTE7eE2hK11lg04CECCYEEjdc17EV4DO+fkGEtt7TpTaTiQ==}
+    engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
+    hasBin: true
+
+  natural-compare-lite@1.4.0:
+    resolution: {integrity: sha512-Tj+HTDSJJKaZnfiuw+iaF9skdPpTo2GtEly5JHnWV/hfv2Qj/9RKsGISQtLh2ox3l5EAGw487hnBee0sIJ6v2g==}
+
+  natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+
+  next-mdx-remote@6.0.0:
+    resolution: {integrity: sha512-cJEpEZlgD6xGjB4jL8BnI8FaYdN9BzZM4NwadPe1YQr7pqoWjg9EBCMv3nXBkuHqMRfv2y33SzUsuyNh9LFAQQ==}
+    engines: {node: '>=14', npm: '>=7'}
+    peerDependencies:
+      react: '>=16'
+
+  next-sitemap@4.2.3:
+    resolution: {integrity: sha512-vjdCxeDuWDzldhCnyFCQipw5bfpl4HmZA7uoo3GAaYGjGgfL4Cxb1CiztPuWGmS+auYs7/8OekRS8C2cjdAsjQ==}
+    engines: {node: '>=14.18'}
+    hasBin: true
+    peerDependencies:
+      next: '*'
+
+  next-themes@0.4.6:
+    resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
+    peerDependencies:
+      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+
+  next@16.2.6:
+    resolution: {integrity: sha512-qOVgKJg1+At15NpeUP+eJgCHvTCgXsogweq87Ri/Ix7PkqQHg4sdaXmSFqKlgaIXE4kW0g25LE68W87UANlHtw==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
+  node-addon-api@6.1.0:
+    resolution: {integrity: sha512-+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==}
+
+  node-addon-api@7.1.1:
+    resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
+
+  node-exports-info@1.6.0:
+    resolution: {integrity: sha512-pyFS63ptit/P5WqUkt+UUfe+4oevH+bFeIiPPdfb0pFeYEu/1ELnJu5l+5EcTKYL5M7zaAa7S8ddywgXypqKCw==}
+    engines: {node: '>= 0.4'}
+
+  node-gyp-build-optional-packages@5.1.1:
+    resolution: {integrity: sha512-+P72GAjVAbTxjjwUmwjVrqrdZROD4nf8KgpBoDxqXXTiYZZt/ud60dE5yvCSr9lRO8e8yv6kgJIC0K0PfZFVQw==}
+    hasBin: true
+
+  node-gyp-build-optional-packages@5.2.2:
+    resolution: {integrity: sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw==}
+    hasBin: true
+
+  node-releases@2.0.47:
+    resolution: {integrity: sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==}
+    engines: {node: '>=18'}
+
+  normalize-url@6.1.0:
+    resolution: {integrity: sha512-DlL+XwOy3NxAQ8xuC0okPgK46iuVNAK01YN7RueYBqqFeGsBjV9XmCAzAdgt+667bCl5kPh9EqKKDwnaPG1I7A==}
+    engines: {node: '>=10'}
+
+  nth-check@2.1.1:
+    resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
+
+  nullthrows@1.1.1:
+    resolution: {integrity: sha512-2vPPEi+Z7WqML2jZYddDIfy5Dqb0r2fze2zTxNNknZaFpVHU3mFB3R+DWeJWGVx0ecvttSGlJTI+WG+8Z4cDWw==}
+
+  nuqs@2.8.6:
+    resolution: {integrity: sha512-aRxeX68b4ULmhio8AADL2be1FWDy0EPqaByPvIYWrA7Pm07UjlrICp/VPlSnXJNAG0+3MQwv3OporO2sOXMVGA==}
+    peerDependencies:
+      '@remix-run/react': '>=2'
+      '@tanstack/react-router': ^1
+      next: '>=14.2.0'
+      react: '>=18.2.0 || ^19.0.0-0'
+      react-router: ^5 || ^6 || ^7
+      react-router-dom: ^5 || ^6 || ^7
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      next:
+        optional: true
+      react-router:
+        optional: true
+      react-router-dom:
+        optional: true
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  object-keys@1.1.1:
+    resolution: {integrity: sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==}
+    engines: {node: '>= 0.4'}
+
+  object.assign@4.1.7:
+    resolution: {integrity: sha512-nK28WOo+QIjBkDduTINE4JkF/UJJKyf2EJxvJKfblDpyg0Q+pkOHNTL0Qwy6NP6FhE/EnzV73BxxqcJaXY9anw==}
+    engines: {node: '>= 0.4'}
+
+  object.entries@1.1.9:
+    resolution: {integrity: sha512-8u/hfXFRBD1O0hPUjioLhoWFHRmt6tKA4/vZPyckBr18l1KE9uHrFaFaUi8MDRTpi4uak2goyPTSNJLXX2k2Hw==}
+    engines: {node: '>= 0.4'}
+
+  object.fromentries@2.0.8:
+    resolution: {integrity: sha512-k6E21FzySsSK5a21KRADBd/NGneRegFO5pLHfdQLpRDETUNJueLXs3WCzyQ3tFRDYgbq3KHGXfTbi2bs8WQ6rQ==}
+    engines: {node: '>= 0.4'}
+
+  object.groupby@1.0.3:
+    resolution: {integrity: sha512-+Lhy3TQTuzXI5hevh8sBGqbmurHbbIjAi0Z4S63nthVLmLxfbj4T54a4CfZrXIrt9iP4mVAPYMo/v99taj3wjQ==}
+    engines: {node: '>= 0.4'}
+
+  object.values@1.2.1:
+    resolution: {integrity: sha512-gXah6aZrcUxjWg2zR2MwouP2eHlCBzdV4pygudehaKXSGW4v2AsRQUK+lwwXhii6KFZcunEnmSUoYp5CXibxtA==}
+    engines: {node: '>= 0.4'}
+
+  obug@2.1.2:
+    resolution: {integrity: sha512-AWGB9WFcRXOQs48Z/udjI5ZcZMHXwX8XPByNpOydgcGsDLIzjGizhoMWJyKAWze7AVW/2W1i+/gPX4YtKe5cyg==}
+    engines: {node: '>=12.20.0'}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  oniguruma-parser@0.12.2:
+    resolution: {integrity: sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==}
+
+  oniguruma-to-es@4.3.6:
+    resolution: {integrity: sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==}
+
+  open@10.2.0:
+    resolution: {integrity: sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==}
+    engines: {node: '>=18'}
+
+  optionator@0.9.4:
+    resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
+    engines: {node: '>= 0.8.0'}
+
+  ordered-binary@1.6.1:
+    resolution: {integrity: sha512-QkCdPooczexPLiXIrbVOPYkR3VO3T6v2OyKRkR1Xbhpy7/LAVXwahnRCgRp78Oe/Ehf0C/HATAxfSr6eA1oX+w==}
+
+  own-keys@1.0.1:
+    resolution: {integrity: sha512-qFOyK5PjiWZd+QQIh+1jhdb9LpxTF0qs7Pm8o5QHYZ0M3vKqSqzsZaEB6oWlxZ+q2sJBMI/Ktgd2N5ZwQoRHfg==}
+    engines: {node: '>= 0.4'}
+
+  p-finally@1.0.0:
+    resolution: {integrity: sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow==}
+    engines: {node: '>=4'}
+
+  p-limit@3.1.0:
+    resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
+    engines: {node: '>=10'}
+
+  p-locate@5.0.0:
+    resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
+    engines: {node: '>=10'}
+
+  p-queue@6.6.2:
+    resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}
+    engines: {node: '>=8'}
+
+  p-timeout@3.2.0:
+    resolution: {integrity: sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg==}
+    engines: {node: '>=8'}
+
+  package-json-from-dist@1.0.1:
+    resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
+
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
+  pako@0.2.9:
+    resolution: {integrity: sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==}
+
+  parcel@2.16.3:
+    resolution: {integrity: sha512-N9jnwcTeVEaRjjJCCHmYfPCvjjJeHZuuO50qL4CCNcQX4RjwPuOaDft7hvTT2W8PIb4XhhZKDYB1lstZhXLJRQ==}
+    engines: {node: '>= 16.0.0'}
+    hasBin: true
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parse-css-color@0.2.1:
+    resolution: {integrity: sha512-bwS/GGIFV3b6KS4uwpzCFj4w297Yl3uqnSgIPsoQkx7GMLROXfMnWvxfNkL0oh8HVhZA4hvJoEoEIqonfJ3BWg==}
+
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
+    engines: {node: '>=8'}
+
+  parse5@7.3.0:
+    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
+
+  path-browserify@1.0.1:
+    resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-parse@1.0.7:
+    resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==}
+
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
+  pathval@2.0.1:
+    resolution: {integrity: sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==}
+    engines: {node: '>= 14.16'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
+    engines: {node: '>=8.6'}
+
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
+  pidtree@0.6.0:
+    resolution: {integrity: sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==}
+    engines: {node: '>=0.10'}
+    hasBin: true
+
+  pify@5.0.0:
+    resolution: {integrity: sha512-eW/gHNMlxdSP6dmG6uJip6FXN0EQBwm2clYYd8Wul42Cwu/DK8HEftzsapcNdYe2MfLiIwZqsDk2RDEsTE79hA==}
+    engines: {node: '>=10'}
+
+  pirates@4.0.7:
+    resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
+    engines: {node: '>= 6'}
+
+  pkg-types@1.3.1:
+    resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
+
+  playwright-core@1.60.0:
+    resolution: {integrity: sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.60.0:
+    resolution: {integrity: sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  possible-typed-array-names@1.1.0:
+    resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
+    engines: {node: '>= 0.4'}
+
+  postcss-calc@8.2.4:
+    resolution: {integrity: sha512-SmWMSJmB8MRnnULldx0lQIyhSNvuDl9HfrZkaqqE/WHAhToYsAvDq+yAsA/kIyINDszOp3Rh0GFoNuH5Ypsm3Q==}
+    peerDependencies:
+      postcss: ^8.2.2
+
+  postcss-colormin@5.3.1:
+    resolution: {integrity: sha512-UsWQG0AqTFQmpBegeLLc1+c3jIqBNB0zlDGRWR+dQ3pRKJL1oeMzyqmH3o2PIfn9MBdNrVPWhDbT769LxCTLJQ==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-convert-values@5.1.3:
+    resolution: {integrity: sha512-82pC1xkJZtcJEfiLw6UXnXVXScgtBrjlO5CBmuDQc+dlb88ZYheFsjTn40+zBVi3DkfF7iezO0nJUPLcJK3pvA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-discard-comments@5.1.2:
+    resolution: {integrity: sha512-+L8208OVbHVF2UQf1iDmRcbdjJkuBF6IS29yBDSiWUIzpYaAhtNl6JYnYm12FnkeCwQqF5LeklOu6rAqgfBZqQ==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-discard-duplicates@5.1.0:
+    resolution: {integrity: sha512-zmX3IoSI2aoenxHV6C7plngHWWhUOV3sP1T8y2ifzxzbtnuhk1EdPwm0S1bIUNaJ2eNbWeGLEwzw8huPD67aQw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-discard-empty@5.1.1:
+    resolution: {integrity: sha512-zPz4WljiSuLWsI0ir4Mcnr4qQQ5e1Ukc3i7UfE2XcrwKK2LIPIqE5jxMRxO6GbI3cv//ztXDsXwEWT3BHOGh3A==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-discard-overridden@5.1.0:
+    resolution: {integrity: sha512-21nOL7RqWR1kasIVdKs8HNqQJhFxLsyRfAnUDm4Fe4t4mCWL9OJiHvlHPjcd8zc5Myu89b/7wZDnOSjFgeWRtw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-less@6.0.0:
+    resolution: {integrity: sha512-FPX16mQLyEjLzEuuJtxA8X3ejDLNGGEG503d2YGZR5Ask1SpDN8KmZUMpzCvyalWRywAn1n1VOA5dcqfCLo5rg==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      postcss: ^8.3.5
+
+  postcss-load-config@3.1.4:
+    resolution: {integrity: sha512-6DiM4E7v4coTE4uzA8U//WhtPwyhiim3eyjEMFCnUpzbrkK9wJHgKDT2mR+HbtSrd/NubVaYTOpSpjUl8NQeRg==}
+    engines: {node: '>= 10'}
+    peerDependencies:
+      postcss: '>=8.0.9'
+      ts-node: '>=9.0.0'
+    peerDependenciesMeta:
+      postcss:
+        optional: true
+      ts-node:
+        optional: true
+
+  postcss-load-config@6.0.1:
+    resolution: {integrity: sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==}
+    engines: {node: '>= 18'}
+    peerDependencies:
+      jiti: '>=1.21.0'
+      postcss: '>=8.0.9'
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+      postcss:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  postcss-merge-longhand@5.1.7:
+    resolution: {integrity: sha512-YCI9gZB+PLNskrK0BB3/2OzPnGhPkBEwmwhfYk1ilBHYVAZB7/tkTHFBAnCrvBBOmeYyMYw3DMjT55SyxMBzjQ==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-merge-rules@5.1.4:
+    resolution: {integrity: sha512-0R2IuYpgU93y9lhVbO/OylTtKMVcHb67zjWIfCiKR9rWL3GUk1677LAqD/BcHizukdZEjT8Ru3oHRoAYoJy44g==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-minify-font-values@5.1.0:
+    resolution: {integrity: sha512-el3mYTgx13ZAPPirSVsHqFzl+BBBDrXvbySvPGFnQcTI4iNslrPaFq4muTkLZmKlGk4gyFAYUBMH30+HurREyA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-minify-gradients@5.1.1:
+    resolution: {integrity: sha512-VGvXMTpCEo4qHTNSa9A0a3D+dxGFZCYwR6Jokk+/3oB6flu2/PnPXAh2x7x52EkY5xlIHLm+Le8tJxe/7TNhzw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-minify-params@5.1.4:
+    resolution: {integrity: sha512-+mePA3MgdmVmv6g+30rn57USjOGSAyuxUmkfiWpzalZ8aiBkdPYjXWtHuwJGm1v5Ojy0Z0LaSYhHaLJQB0P8Jw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-minify-selectors@5.2.1:
+    resolution: {integrity: sha512-nPJu7OjZJTsVUmPdm2TcaiohIwxP+v8ha9NehQ2ye9szv4orirRU3SDdtUmKH+10nzn0bAyOXZ0UEr7OpvLehg==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-modules-extract-imports@3.1.0:
+    resolution: {integrity: sha512-k3kNe0aNFQDAZGbin48pL2VNidTF0w4/eASDsxlyspobzU3wZQLOGj7L9gfRe0Jo9/4uud09DsjFNH7winGv8Q==}
+    engines: {node: ^10 || ^12 || >= 14}
+    peerDependencies:
+      postcss: ^8.1.0
+
+  postcss-modules-local-by-default@4.2.0:
+    resolution: {integrity: sha512-5kcJm/zk+GJDSfw+V/42fJ5fhjL5YbFDl8nVdXkJPLLW+Vf9mTD5Xe0wqIaDnLuL2U6cDNpTr+UQ+v2HWIBhzw==}
+    engines: {node: ^10 || ^12 || >= 14}
+    peerDependencies:
+      postcss: ^8.1.0
+
+  postcss-modules-scope@3.2.1:
+    resolution: {integrity: sha512-m9jZstCVaqGjTAuny8MdgE88scJnCiQSlSrOWcTQgM2t32UBe+MUmFSO5t7VMSfAf/FJKImAxBav8ooCHJXCJA==}
+    engines: {node: ^10 || ^12 || >= 14}
+    peerDependencies:
+      postcss: ^8.1.0
+
+  postcss-modules-values@4.0.0:
+    resolution: {integrity: sha512-RDxHkAiEGI78gS2ofyvCsu7iycRv7oqw5xMWn9iMoR0N/7mf9D50ecQqUo5BZ9Zh2vH4bCUR/ktCqbB9m8vJjQ==}
+    engines: {node: ^10 || ^12 || >= 14}
+    peerDependencies:
+      postcss: ^8.1.0
+
+  postcss-modules@4.3.1:
+    resolution: {integrity: sha512-ItUhSUxBBdNamkT3KzIZwYNNRFKmkJrofvC2nWab3CPKhYBQ1f27XXh1PAPE27Psx58jeelPsxWB/+og+KEH0Q==}
+    peerDependencies:
+      postcss: ^8.0.0
+
+  postcss-normalize-charset@5.1.0:
+    resolution: {integrity: sha512-mSgUJ+pd/ldRGVx26p2wz9dNZ7ji6Pn8VWBajMXFf8jk7vUoSrZ2lt/wZR7DtlZYKesmZI680qjr2CeFF2fbUg==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-display-values@5.1.0:
+    resolution: {integrity: sha512-WP4KIM4o2dazQXWmFaqMmcvsKmhdINFblgSeRgn8BJ6vxaMyaJkwAzpPpuvSIoG/rmX3M+IrRZEz2H0glrQNEA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-positions@5.1.1:
+    resolution: {integrity: sha512-6UpCb0G4eofTCQLFVuI3EVNZzBNPiIKcA1AKVka+31fTVySphr3VUgAIULBhxZkKgwLImhzMR2Bw1ORK+37INg==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-repeat-style@5.1.1:
+    resolution: {integrity: sha512-mFpLspGWkQtBcWIRFLmewo8aC3ImN2i/J3v8YCFUwDnPu3Xz4rLohDO26lGjwNsQxB3YF0KKRwspGzE2JEuS0g==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-string@5.1.0:
+    resolution: {integrity: sha512-oYiIJOf4T9T1N4i+abeIc7Vgm/xPCGih4bZz5Nm0/ARVJ7K6xrDlLwvwqOydvyL3RHNf8qZk6vo3aatiw/go3w==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-timing-functions@5.1.0:
+    resolution: {integrity: sha512-DOEkzJ4SAXv5xkHl0Wa9cZLF3WCBhF3o1SKVxKQAa+0pYKlueTpCgvkFAHfk+Y64ezX9+nITGrDZeVGgITJXjg==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-unicode@5.1.1:
+    resolution: {integrity: sha512-qnCL5jzkNUmKVhZoENp1mJiGNPcsJCs1aaRmURmeJGES23Z/ajaln+EPTD+rBeNkSryI+2WTdW+lwcVdOikrpA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-url@5.1.0:
+    resolution: {integrity: sha512-5upGeDO+PVthOxSmds43ZeMeZfKH+/DKgGRD7TElkkyS46JXAUhMzIKiCa7BabPeIy3AQcTkXwVVN7DbqsiCew==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-normalize-whitespace@5.1.1:
+    resolution: {integrity: sha512-83ZJ4t3NUDETIHTa3uEg6asWjSBYL5EdkVB0sDncx9ERzOKBVJIUeDO9RyA9Zwtig8El1d79HBp0JEi8wvGQnA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-ordered-values@5.1.3:
+    resolution: {integrity: sha512-9UO79VUhPwEkzbb3RNpqqghc6lcYej1aveQteWY+4POIwlqkYE21HKWaLDF6lWNuqCobEAyTovVhtI32Rbv2RQ==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-reduce-initial@5.1.2:
+    resolution: {integrity: sha512-dE/y2XRaqAi6OvjzD22pjTUQ8eOfc6m/natGHgKFBK9DxFmIm69YmaRVQrGgFlEfc1HePIurY0TmDeROK05rIg==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-reduce-transforms@5.1.0:
+    resolution: {integrity: sha512-2fbdbmgir5AvpW9RLtdONx1QoYG2/EtqpNQbFASDlixBbAYuTcJ0dECwlqNqH7VbaUnEnh8SrxOe2sRIn24XyQ==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-scss@4.0.9:
+    resolution: {integrity: sha512-AjKOeiwAitL/MXxQW2DliT28EKukvvbEWx3LBmJIRN8KfBGZbRTxNYW0kSqi1COiTZ57nZ9NW06S6ux//N1c9A==}
+    engines: {node: '>=12.0'}
+    peerDependencies:
+      postcss: ^8.4.29
+
+  postcss-selector-parser@6.0.10:
+    resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
+    engines: {node: '>=4'}
+
+  postcss-selector-parser@6.1.2:
+    resolution: {integrity: sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==}
+    engines: {node: '>=4'}
+
+  postcss-selector-parser@7.1.1:
+    resolution: {integrity: sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==}
+    engines: {node: '>=4'}
+
+  postcss-svgo@5.1.0:
+    resolution: {integrity: sha512-D75KsH1zm5ZrHyxPakAxJWtkyXew5qwS70v56exwvw542d9CRtTo78K0WeFxZB4G7JXKKMbEZtZayTGdIky/eA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-unique-selectors@5.1.1:
+    resolution: {integrity: sha512-5JiODlELrz8L2HwxfPnhOWZYWDxVHWL83ufOv84NrcgipI7TaeRsatAhK4Tr2/ZiYldpK/wBvw5BD3qfaK96GA==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  postcss-value-parser@4.2.0:
+    resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
+
+  postcss@8.4.31:
+    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postcss@8.5.6:
+    resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  posthog-node@5.21.0:
+    resolution: {integrity: sha512-M7v/+Zyz/z3ZDC4u896K2Lb/pLbPA1Czo6Tp/WeQ1vuBsJtJajqWO3vRev3BHFTP92nao5YCrU0aIM+Flwbv1A==}
+    engines: {node: '>=20'}
+
+  preact@10.29.2:
+    resolution: {integrity: sha512-7tNmwg/7mzzAoB/8kSg6Hl37JraAZw3Z3A0JSY7VXlZwo82Xn0G7wKbNNs2qoF4ZEEsQGTwDAroNdqKs1ofJxQ==}
+
+  prelude-ls@1.2.1:
+    resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
+    engines: {node: '>= 0.8.0'}
+
+  prettier-linter-helpers@1.0.1:
+    resolution: {integrity: sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg==}
+    engines: {node: '>=6.0.0'}
+
+  prettier-plugin-css-order@2.1.2:
+    resolution: {integrity: sha512-vomxPjHI6pOMYcBuouSJHxxQClJXaUpU9rsV9IAO2wrSTZILRRlrxAAR8t9UF6wtczLkLfNRFUwM+ZbGXOONUA==}
+    engines: {node: '>=16'}
+    peerDependencies:
+      prettier: 3.x
+
+  prettier-plugin-tailwindcss@0.7.2:
+    resolution: {integrity: sha512-LkphyK3Fw+q2HdMOoiEHWf93fNtYJwfamoKPl7UwtjFQdei/iIBoX11G6j706FzN3ymX9mPVi97qIY8328vdnA==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@ianvs/prettier-plugin-sort-imports': '*'
+      '@prettier/plugin-hermes': '*'
+      '@prettier/plugin-oxc': '*'
+      '@prettier/plugin-pug': '*'
+      '@shopify/prettier-plugin-liquid': '*'
+      '@trivago/prettier-plugin-sort-imports': '*'
+      '@zackad/prettier-plugin-twig': '*'
+      prettier: ^3.0
+      prettier-plugin-astro: '*'
+      prettier-plugin-css-order: '*'
+      prettier-plugin-jsdoc: '*'
+      prettier-plugin-marko: '*'
+      prettier-plugin-multiline-arrays: '*'
+      prettier-plugin-organize-attributes: '*'
+      prettier-plugin-organize-imports: '*'
+      prettier-plugin-sort-imports: '*'
+      prettier-plugin-svelte: '*'
+    peerDependenciesMeta:
+      '@ianvs/prettier-plugin-sort-imports':
+        optional: true
+      '@prettier/plugin-hermes':
+        optional: true
+      '@prettier/plugin-oxc':
+        optional: true
+      '@prettier/plugin-pug':
+        optional: true
+      '@shopify/prettier-plugin-liquid':
+        optional: true
+      '@trivago/prettier-plugin-sort-imports':
+        optional: true
+      '@zackad/prettier-plugin-twig':
+        optional: true
+      prettier-plugin-astro:
+        optional: true
+      prettier-plugin-css-order:
+        optional: true
+      prettier-plugin-jsdoc:
+        optional: true
+      prettier-plugin-marko:
+        optional: true
+      prettier-plugin-multiline-arrays:
+        optional: true
+      prettier-plugin-organize-attributes:
+        optional: true
+      prettier-plugin-organize-imports:
+        optional: true
+      prettier-plugin-sort-imports:
+        optional: true
+      prettier-plugin-svelte:
+        optional: true
+
+  prettier@3.7.4:
+    resolution: {integrity: sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==}
+    engines: {node: '>=14'}
+    hasBin: true
+
+  pretty-format@27.5.1:
+    resolution: {integrity: sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==}
+    engines: {node: ^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0}
+
+  promise.series@0.2.0:
+    resolution: {integrity: sha512-VWQJyU2bcDTgZw8kpfBpB/ejZASlCrzwz5f2hjb/zlujOEB4oeiAhHygAWq8ubsX2GVkD4kCU5V2dwOTaCY5EQ==}
+    engines: {node: '>=0.12'}
+
+  prop-types@15.8.1:
+    resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==}
+
+  property-information@7.2.0:
+    resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  quansync@1.0.0:
+    resolution: {integrity: sha512-5xZacEEufv3HSTPQuchrvV6soaiACMFnq1H8wkVioctoH3TRha9Sz66lOxRwPK/qZj7HPiSveih9yAyh98gvqA==}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
+  react-aria-components@1.18.0:
+    resolution: {integrity: sha512-FhRQjuDkH4WhgFv+O2sYTzK3JzdZTGpBeaqfRlfTo+DcSZzD8elJEkytHe7SDpcexVKeire8NVd7OruZHfCVoA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-aria-components@1.19.0:
+    resolution: {integrity: sha512-2smSS5nqJ8cGYMQezuUXveZm7eMyHCqTN6mDpylQBYLYbdF5dxCCuW1DHn1VKLe1DybSfPvX/cZtJlDmvFfn8A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-aria@3.49.0:
+    resolution: {integrity: sha512-4+oK9FwJQWYhyA5zLfj/feOGY0zZbkE1muoF4gyxMroHVypjcYaRSTlJwvxph2zIlxt757KX6xIK2wJ5Aw1Kog==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-aria@3.50.0:
+    resolution: {integrity: sha512-S0Os6QZk33fzUAKu1QLT9afoUaCBt1ZNdoiq0n2YMVgKIdNIQS8zxiZ8O9hYE6QyDkHKjD6q39LQZ+qaSAIgjw==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+      react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-docgen-typescript@2.4.0:
+    resolution: {integrity: sha512-ZtAp5XTO5HRzQctjPU0ybY0RRCQO19X/8fxn3w7y2VVTUbGHDKULPTL4ky3vB05euSgG5NpALhEhDPvQ56wvXg==}
+    peerDependencies:
+      typescript: '>= 4.3.x'
+
+  react-docgen@8.0.3:
+    resolution: {integrity: sha512-aEZ9qP+/M+58x2qgfSFEWH1BxLyHe5+qkLNJOZQb5iGS017jpbRnoKhNRrXPeA6RfBrZO5wZrT9DMC1UqE1f1w==}
+    engines: {node: ^20.9.0 || >=22}
+
+  react-dom@19.2.6:
+    resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
+    peerDependencies:
+      react: ^19.2.6
+
+  react-is@16.13.1:
+    resolution: {integrity: sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==}
+
+  react-is@17.0.2:
+    resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
+
+  react-refresh@0.16.0:
+    resolution: {integrity: sha512-FPvF2XxTSikpJxcr+bHut2H4gJ17+18Uy20D5/F+SKzFap62R3cM5wH6b8WN3LyGSYeQilLEcJcR1fjBSI2S1A==}
+    engines: {node: '>=0.10.0'}
+
+  react-refresh@0.18.0:
+    resolution: {integrity: sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==}
+    engines: {node: '>=0.10.0'}
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-scan@0.4.3:
+    resolution: {integrity: sha512-jhAQuQ1nja6HUYrSpbmNFHqZPsRCXk8Yqu0lHoRIw9eb8N96uTfXCpVyQhTTnJ/nWqnwuvxbpKVG/oWZT8+iTQ==}
+    hasBin: true
+    peerDependencies:
+      '@remix-run/react': '>=1.0.0'
+      next: '>=13.0.0'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-router: ^5.0.0 || ^6.0.0 || ^7.0.0
+      react-router-dom: ^5.0.0 || ^6.0.0 || ^7.0.0
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      next:
+        optional: true
+      react-router:
+        optional: true
+      react-router-dom:
+        optional: true
+
+  react-stately@3.47.0:
+    resolution: {integrity: sha512-H3ar+SOWP920EbVg7qWfP3fZjZiwhlEJAEJQqjt+w8oKijCwFgr0+R4941PIHscOXRNRvEOjvWilitImC0DdBg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-stately@3.48.0:
+    resolution: {integrity: sha512-ImicSAG+lTotAe5izcs1fz49Zk48w7pDusqYg04WaPhCoej8BJ24soMu3iLXIrsi273s4P1gZrYGrqReMfgEEA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-transition-group@4.4.5:
+    resolution: {integrity: sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==}
+    peerDependencies:
+      react: '>=16.6.0'
+      react-dom: '>=16.6.0'
+
+  react@19.2.6:
+    resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
+    engines: {node: '>=0.10.0'}
+
+  readdirp@4.1.2:
+    resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
+    engines: {node: '>= 14.18.0'}
+
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
+  recast@0.23.11:
+    resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
+    engines: {node: '>= 4'}
+
+  recma-build-jsx@1.0.0:
+    resolution: {integrity: sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==}
+
+  recma-jsx@1.0.1:
+    resolution: {integrity: sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  recma-parse@1.0.0:
+    resolution: {integrity: sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==}
+
+  recma-stringify@1.0.0:
+    resolution: {integrity: sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==}
+
+  redent@3.0.0:
+    resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==}
+    engines: {node: '>=8'}
+
+  reflect.getprototypeof@1.0.10:
+    resolution: {integrity: sha512-00o4I+DVrefhv+nX0ulyi3biSHCPDe+yLv5o/p6d/UVlirijB8E16FtfwSAi4g3tcqrQ4lRAqQSoFEZJehYEcw==}
+    engines: {node: '>= 0.4'}
+
+  regenerator-runtime@0.14.1:
+    resolution: {integrity: sha512-dYnhHh0nJoMfnkZs6GmmhFknAGRrLznOu5nc9ML+EJxGvrx6H7teuevqVqCuPcPK//3eDrrjQhehXVx9cnkGdw==}
+
+  regex-recursion@6.0.2:
+    resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}
+
+  regex-utilities@2.3.0:
+    resolution: {integrity: sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==}
+
+  regex@6.1.0:
+    resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
+
+  regexp.prototype.flags@1.5.4:
+    resolution: {integrity: sha512-dYqgNSZbDwkaJ2ceRd9ojCGjBq+mOm9LmtXnAnEGyHhN/5R7iDW2TRw3h+o/jCFxus3P2LfWIIiwowAjANm7IA==}
+    engines: {node: '>= 0.4'}
+
+  rehype-raw@7.0.0:
+    resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==}
+
+  rehype-recma@1.0.0:
+    resolution: {integrity: sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==}
+
+  relative-luminance@2.0.1:
+    resolution: {integrity: sha512-wFuITNthJilFPwkK7gNJcULxXBcfFZvZORsvdvxeOdO44wCeZnuQkf3nFFzOR/dpJNxYsdRZJLsepWbyKhnMww==}
+
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-mdx@3.1.1:
+    resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
+  remark@15.0.1:
+    resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  requireindex@1.2.0:
+    resolution: {integrity: sha512-L9jEkOi3ASd9PYit2cwRfyppc9NoABujTP8/5gFcbERmo5jUoAKovIC3fsF17pkTnGsrByysqX+Kxd2OTNI1ww==}
+    engines: {node: '>=0.10.5'}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
+  resolve-from@5.0.0:
+    resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
+    engines: {node: '>=8'}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  resolve@1.22.12:
+    resolution: {integrity: sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==}
+    engines: {node: '>= 0.4'}
+    hasBin: true
+
+  resolve@2.0.0-next.7:
+    resolution: {integrity: sha512-tqt+NBWwyaMgw3zDsnygx4CByWjQEJHOPMdslYhppaQSJUtL/D4JO9CcBBlhPoI8lz9oJIDXkwXfhF4aWqP8xQ==}
+    engines: {node: '>= 0.4'}
+    hasBin: true
+
+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  rfdc@1.4.1:
+    resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
+
+  rimraf@6.1.2:
+    resolution: {integrity: sha512-cFCkPslJv7BAXJsYlK1dZsbP8/ZNLkCAQ0bi1hf5EKX2QHegmDFEFA6QhuYJlk7UDdc+02JjO80YSOrWPpw06g==}
+    engines: {node: 20 || >=22}
+    hasBin: true
+
+  rollup-plugin-peer-deps-external@2.2.4:
+    resolution: {integrity: sha512-AWdukIM1+k5JDdAqV/Cxd+nejvno2FVLVeZ74NKggm3Q5s9cbbcOgUPGdbxPi4BXu7xGaZ8HG12F+thImYu/0g==}
+    peerDependencies:
+      rollup: '*'
+
+  rollup-plugin-postcss@4.0.2:
+    resolution: {integrity: sha512-05EaY6zvZdmvPUDi3uCcAQoESDcYnv8ogJJQRp6V5kZ6J6P7uAVJlrTZcaaA20wTH527YTnKfkAoPxWI/jPp4w==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      postcss: 8.x
+
+  rollup-pluginutils@2.8.2:
+    resolution: {integrity: sha512-EEp9NhnUkwY8aif6bxgovPHMoMoNr2FulJziTndpt5H9RdwC47GSGuII9XxpSdzVGM0GWrNPHV6ie1LTNJPaLQ==}
+
+  rollup@4.54.0:
+    resolution: {integrity: sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
+  safe-array-concat@1.1.4:
+    resolution: {integrity: sha512-wtZlHyOje6OZTGqAoaDKxFkgRtkF9CnHAVnCHKfuj200wAgL+bSJhdsCD2l0Qx/2ekEXjPWcyKkfGb5CPboslg==}
+    engines: {node: '>=0.4'}
+
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
+  safe-identifier@0.4.2:
+    resolution: {integrity: sha512-6pNbSMW6OhAi9j+N8V+U715yBQsaWJ7eyEUaOrawX+isg5ZxhUlV1NipNtgaKHmFGiABwt+ZF04Ii+3Xjkg+8w==}
+
+  safe-push-apply@1.0.0:
+    resolution: {integrity: sha512-iKE9w/Z7xCzUMIZqdBsp6pEQvwuEebH4vdpjcDWnyzaI6yl6O9FHvVpmGelvEHNsoY6wGblkxR6Zty/h00WiSA==}
+    engines: {node: '>= 0.4'}
+
+  safe-regex-test@1.1.0:
+    resolution: {integrity: sha512-x/+Cz4YrimQxQccJf5mKEbIa1NzeCRNI5Ecl/ekmlYaampdNLPalVyIcCZNNH3MvmqBugV5TMYZXv0ljslUlaw==}
+    engines: {node: '>= 0.4'}
+
+  satori@0.16.0:
+    resolution: {integrity: sha512-ZvHN3ygzZ8FuxjSNB+mKBiF/NIoqHzlBGbD0MJiT+MvSsFOvotnWOhdTjxKzhHRT2wPC1QbhLzx2q/Y83VhfYQ==}
+    engines: {node: '>=16'}
+
+  sax@1.6.0:
+    resolution: {integrity: sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==}
+    engines: {node: '>=11.0.0'}
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  scroll-into-view-if-needed@3.1.0:
+    resolution: {integrity: sha512-49oNpRjWRvnU8NyGVmUaYG4jtTkNonFZI86MmGRDqBphEK2EXT9gdEUoQPZhuBM8yWHxCWbobltqYO5M4XrUvQ==}
+
+  section-matter@1.0.0:
+    resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==}
+    engines: {node: '>=4'}
+
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
+  semver@7.8.2:
+    resolution: {integrity: sha512-c8jsqUZm3omBOI66G90z1Dyw5z622G8oLG+omfsHBJf3CWQTlOcwOjvOG6wtiNfW6anKm/eA39LMwMtMez2TiQ==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  set-function-length@1.2.2:
+    resolution: {integrity: sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==}
+    engines: {node: '>= 0.4'}
+
+  set-function-name@2.0.2:
+    resolution: {integrity: sha512-7PGFlmtwsEADb0WYyvCMa1t+yke6daIG4Wirafur5kcf+MhUnPms1UeR0CKQdTZD81yESwMHbtn+TR+dMviakQ==}
+    engines: {node: '>= 0.4'}
+
+  set-proto@1.0.0:
+    resolution: {integrity: sha512-RJRdvCo6IAnPdsvP/7m6bsQqNnn1FCBX5ZNtFL98MmFF/4xAIJTIg1YbHW5DC2W5SKZanrC6i4HsJqlajw/dZw==}
+    engines: {node: '>= 0.4'}
+
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  shiki@3.20.0:
+    resolution: {integrity: sha512-kgCOlsnyWb+p0WU+01RjkCH+eBVsjL1jOwUYWv0YDWkM2/A46+LDKVs5yZCUXjJG6bj4ndFoAg5iLIIue6dulg==}
+
+  side-channel-list@1.0.1:
+    resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.0:
+    resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==}
+    engines: {node: '>= 0.4'}
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
+  slice-ansi@7.1.2:
+    resolution: {integrity: sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==}
+    engines: {node: '>=18'}
+
+  slice-ansi@8.0.0:
+    resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
+    engines: {node: '>=20'}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  source-map-support@0.5.21:
+    resolution: {integrity: sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==}
+
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.7.6:
+    resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
+    engines: {node: '>= 12'}
+
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
+  stable-hash@0.0.5:
+    resolution: {integrity: sha512-+L3ccpzibovGXFK+Ap/f8LOS0ahMrHTf3xu7mMLSpEGU0EO9ucaysSylKo9eRDFNhWve/y275iPmIZ4z39a9iA==}
+
+  stable@0.1.8:
+    resolution: {integrity: sha512-ji9qxRnOVfcuLDySj9qzhGSEFVobyt1kIOSkj1qZzYLzq7Tos/oUUWvotUPQLlrsidqsK6tBH89Bc9kL5zHA6w==}
+    deprecated: 'Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#browser_compatibility'
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  std-env@3.10.0:
+    resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
+
+  stop-iteration-iterator@1.1.0:
+    resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
+    engines: {node: '>= 0.4'}
+
+  storybook@10.1.10:
+    resolution: {integrity: sha512-oK0t0jEogiKKfv5Z1ao4Of99+xWw1TMUGuGRYDQS4kp2yyBsJQEgu7NI7OLYsCDI6gzt5p3RPtl1lqdeVLUi8A==}
+    hasBin: true
+    peerDependencies:
+      prettier: ^2 || ^3
+    peerDependenciesMeta:
+      prettier:
+        optional: true
+
+  string-argv@0.3.2:
+    resolution: {integrity: sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==}
+    engines: {node: '>=0.6.19'}
+
+  string-hash@1.1.3:
+    resolution: {integrity: sha512-kJUvRUFK49aub+a7T1nNE66EJbZBMnBgoC1UbCZ5n6bsZKBRga4KgBRTMn/pFkeCZSYtNeSyMxPDM0AXWELk2A==}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  string-width@8.2.1:
+    resolution: {integrity: sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==}
+    engines: {node: '>=20'}
+
+  string.prototype.codepointat@0.2.1:
+    resolution: {integrity: sha512-2cBVCj6I4IOvEnjgO/hWqXjqBGsY+zwPmHl12Srk9IXSZ56Jwwmy+66XO5Iut/oQVR7t5ihYdLB0GMa4alEUcg==}
+
+  string.prototype.includes@2.0.1:
+    resolution: {integrity: sha512-o7+c9bW6zpAdJHTtujeePODAhkuicdAryFsfVKwA+wGw89wJ4GTY484WTucM9hLtDEOpOvI+aHnzqnC5lHp4Rg==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.matchall@4.0.12:
+    resolution: {integrity: sha512-6CC9uyBL+/48dYizRf7H7VAYCMCNTBeM78x/VTUe9bFEaxBepPJDa1Ow99LqI/1yF7kuy7Q3cQsYMrcjGUcskA==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.repeat@1.0.0:
+    resolution: {integrity: sha512-0u/TldDbKD8bFCQ/4f5+mNRrXwZ8hg2w7ZR8wa16e8z9XpePWl3eGEcUD0OXpEH/VJH/2G3gjUtR3ZOiBe2S/w==}
+
+  string.prototype.trim@1.2.11:
+    resolution: {integrity: sha512-PwvK7BU+CMTJGYQCTZb5RWXIML92lftJLhQz1tBzgKiqGxJaMlBAa48POXaNAC2s4y8jr3EFqrkF9+44neS46w==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.trimend@1.0.10:
+    resolution: {integrity: sha512-2+3aDAOmPTmuFwjDnmJG2ctEkQKVki7vOSqaxkv42Mowj1V6PnvuwFCRrR5lChUux1TBskPjfkeTOhqczDMxTw==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.trimstart@1.0.8:
+    resolution: {integrity: sha512-UXSH262CSZY1tfu3G3Secr6uGLCFVPMhIqHjlgCUtCCcgihYc/xKs9djMTMUOb2j1mVSeU8EU6NWc/iQKU6Gfg==}
+    engines: {node: '>= 0.4'}
+
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-bom-string@1.0.0:
+    resolution: {integrity: sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==}
+    engines: {node: '>=0.10.0'}
+
+  strip-bom@3.0.0:
+    resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
+    engines: {node: '>=4'}
+
+  strip-indent@3.0.0:
+    resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==}
+    engines: {node: '>=8'}
+
+  strip-indent@4.1.1:
+    resolution: {integrity: sha512-SlyRoSkdh1dYP0PzclLE7r0M9sgbFKKMFXpFRUMNuKhQSbC6VQIGzq3E0qsfvGJaUFJPGv6Ws1NZ/haTAjfbMA==}
+    engines: {node: '>=12'}
+
+  strip-json-comments@3.1.1:
+    resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
+    engines: {node: '>=8'}
+
+  style-inject@0.3.0:
+    resolution: {integrity: sha512-IezA2qp+vcdlhJaVm5SOdPPTUu0FCEqfNSli2vRuSIBbu5Nq5UvygTk/VzeCqfLz2Atj3dVII5QBKGZRZ0edzw==}
+
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
+  styled-jsx@5.1.6:
+    resolution: {integrity: sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==}
+    engines: {node: '>= 12.0.0'}
+    peerDependencies:
+      '@babel/core': '*'
+      babel-plugin-macros: '*'
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0 || ^19.0.0-0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      babel-plugin-macros:
+        optional: true
+
+  stylehacks@5.1.1:
+    resolution: {integrity: sha512-sBpcd5Hx7G6seo7b1LkpttvTz7ikD0LlH5RmdcBNb6fFR0Fl7LQwHDFr300q4cwUqi+IYrFGmsIHieMBfnN/Bw==}
+    engines: {node: ^10 || ^12 || >=14.0}
+    peerDependencies:
+      postcss: ^8.2.15
+
+  sucrase@3.35.1:
+    resolution: {integrity: sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==}
+    engines: {node: '>=16 || 14 >=14.17'}
+    hasBin: true
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  supports-preserve-symlinks-flag@1.0.0:
+    resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
+    engines: {node: '>= 0.4'}
+
+  svgo@2.8.2:
+    resolution: {integrity: sha512-TyzE4NVGLUFy+H/Uy4N6c3G0HEeprsVfge6Lmq+0FdQQ/zqoVYB62IsBZORsiL+o96s6ff/V6/3UQo/C0cgCAA==}
+    engines: {node: '>=10.13.0'}
+    hasBin: true
+
+  synckit@0.11.13:
+    resolution: {integrity: sha512-eNRKgb3z66Yp3D2CixVujOUvXLFUTij/zVnV8KRyvFdQwpz7I5DS8UfRkTeLzb64u+dkzDSdelE24izu+zSSUg==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+
+  tailwind-merge@3.4.0:
+    resolution: {integrity: sha512-uSaO4gnW+b3Y2aWoWfFpX62vn2sR3skfhbjsEnaBI81WD1wBLlHZe5sWf0AqjksNdYTbGBEd0UasQMT3SNV15g==}
+
+  tailwind-merge@3.6.0:
+    resolution: {integrity: sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w==}
+
+  tailwind-variants@3.2.2:
+    resolution: {integrity: sha512-Mi4kHeMTLvKlM98XPnK+7HoBPmf4gygdFmqQPaDivc3DpYS6aIY6KiG/PgThrGvii5YZJqRsPz0aPyhoFzmZgg==}
+    engines: {node: '>=16.x', pnpm: '>=7.x'}
+    peerDependencies:
+      tailwind-merge: '>=3.0.0'
+      tailwindcss: '*'
+    peerDependenciesMeta:
+      tailwind-merge:
+        optional: true
+
+  tailwindcss@4.1.18:
+    resolution: {integrity: sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==}
+
+  tailwindcss@4.3.0:
+    resolution: {integrity: sha512-y6nxMGB1nMW9R6k96e5gdIFzcfL/gTJRNaqGes1YvkLnPVXzWgbqFF2yLC0T8G774n24cx3Pe8XrKoniCOAH+Q==}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
+  tar@7.5.7:
+    resolution: {integrity: sha512-fov56fJiRuThVFXD6o6/Q354S7pnWMJIVlDBYijsTNx6jKSE4pvrDTs6lUnmGvNyfJwFQQwWy3owKz1ucIhveQ==}
+    engines: {node: '>=18'}
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+
+  term-size@2.2.1:
+    resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==}
+    engines: {node: '>=8'}
+
+  thenify-all@1.6.0:
+    resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
+    engines: {node: '>=0.8'}
+
+  thenify@3.3.1:
+    resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==}
+
+  tiny-inflate@1.0.3:
+    resolution: {integrity: sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==}
+
+  tiny-invariant@1.3.3:
+    resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@0.3.2:
+    resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
+
+  tinyexec@1.2.4:
+    resolution: {integrity: sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  tinyrainbow@2.0.0:
+    resolution: {integrity: sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==}
+    engines: {node: '>=14.0.0'}
+
+  tinyrainbow@3.1.0:
+    resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
+    engines: {node: '>=14.0.0'}
+
+  tinyspy@4.0.4:
+    resolution: {integrity: sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==}
+    engines: {node: '>=14.0.0'}
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
+  tree-kill@1.2.2:
+    resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
+    hasBin: true
+
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
+  ts-api-utils@2.5.0:
+    resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
+    engines: {node: '>=18.12'}
+    peerDependencies:
+      typescript: '>=4.8.4'
+
+  ts-dedent@2.2.0:
+    resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==}
+    engines: {node: '>=6.10'}
+
+  ts-interface-checker@0.1.13:
+    resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
+
+  ts-morph@27.0.2:
+    resolution: {integrity: sha512-fhUhgeljcrdZ+9DZND1De1029PrE+cMkIP7ooqkLRTrRLTqcki2AstsyJm0vRNbTbVCNJ0idGlbBrfqc7/nA8w==}
+
+  tsconfig-paths@3.15.0:
+    resolution: {integrity: sha512-2Ac2RgzDe/cn48GvOe3M+o82pEFewD3UPbyoUHHdKasHwJKjds4fLXWf/Ux5kATBKN20oaFGu+jbElp1pos0mg==}
+
+  tsconfig-paths@4.2.0:
+    resolution: {integrity: sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg==}
+    engines: {node: '>=6'}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tsup@8.5.1:
+    resolution: {integrity: sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==}
+    engines: {node: '>=18'}
+    hasBin: true
+    peerDependencies:
+      '@microsoft/api-extractor': ^7.36.0
+      '@swc/core': ^1
+      postcss: ^8.4.12
+      typescript: '>=4.5.0'
+    peerDependenciesMeta:
+      '@microsoft/api-extractor':
+        optional: true
+      '@swc/core':
+        optional: true
+      postcss:
+        optional: true
+      typescript:
+        optional: true
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  turbo-darwin-64@2.7.2:
+    resolution: {integrity: sha512-dxY3X6ezcT5vm3coK6VGixbrhplbQMwgNsCsvZamS/+/6JiebqW9DKt4NwpgYXhDY2HdH00I7FWs3wkVuan4rA==}
+    cpu: [x64]
+    os: [darwin]
+
+  turbo-darwin-arm64@2.7.2:
+    resolution: {integrity: sha512-1bXmuwPLqNFt3mzrtYcVx1sdJ8UYb124Bf48nIgcpMCGZy3kDhgxNv1503kmuK/37OGOZbsWSQFU4I08feIuSg==}
+    cpu: [arm64]
+    os: [darwin]
+
+  turbo-linux-64@2.7.2:
+    resolution: {integrity: sha512-kP+TiiMaiPugbRlv57VGLfcjFNsFbo8H64wMBCPV2270Or2TpDCBULMzZrvEsvWFjT3pBFvToYbdp8/Kw0jAQg==}
+    cpu: [x64]
+    os: [linux]
+
+  turbo-linux-arm64@2.7.2:
+    resolution: {integrity: sha512-VDJwQ0+8zjAfbyY6boNaWfP6RIez4ypKHxwkuB6SrWbOSk+vxTyW5/hEjytTwK8w/TsbKVcMDyvpora8tEsRFw==}
+    cpu: [arm64]
+    os: [linux]
+
+  turbo-windows-64@2.7.2:
+    resolution: {integrity: sha512-rPjqQXVnI6A6oxgzNEE8DNb6Vdj2Wwyhfv3oDc+YM3U9P7CAcBIlKv/868mKl4vsBtz4ouWpTQNXG8vljgJO+w==}
+    cpu: [x64]
+    os: [win32]
+
+  turbo-windows-arm64@2.7.2:
+    resolution: {integrity: sha512-tcnHvBhO515OheIFWdxA+qUvZzNqqcHbLVFc1+n+TJ1rrp8prYicQtbtmsiKgMvr/54jb9jOabU62URAobnB7g==}
+    cpu: [arm64]
+    os: [win32]
+
+  turbo@2.7.2:
+    resolution: {integrity: sha512-5JIA5aYBAJSAhrhbyag1ZuMSgUZnHtI+Sq3H8D3an4fL8PeF+L1yYvbEJg47akP1PFfATMf5ehkqFnxfkmuwZQ==}
+    hasBin: true
+
+  tw-animate-css@1.4.0:
+    resolution: {integrity: sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ==}
+
+  type-check@0.4.0:
+    resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
+    engines: {node: '>= 0.8.0'}
+
+  type-fest@0.20.2:
+    resolution: {integrity: sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==}
+    engines: {node: '>=10'}
+
+  typed-array-buffer@1.0.3:
+    resolution: {integrity: sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-byte-length@1.0.3:
+    resolution: {integrity: sha512-BaXgOuIxz8n8pIq3e7Atg/7s+DpiYrxn4vdot3w9KbnBhcRQq6o3xemQdIfynqSeXeDrF32x+WvfzmOjPiY9lg==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-byte-offset@1.0.4:
+    resolution: {integrity: sha512-bTlAFB/FBYMcuX81gbL4OcpH5PmlFHqlCCpAl8AlEzMz5k53oNDvN8p1PNOWLEmI2x4orp3raOFB51tv9X+MFQ==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-length@1.0.8:
+    resolution: {integrity: sha512-phPGCwqr2+Qo0fwniCE8e4pKnGu/yFb5nD5Y8bf0EEeiI5GklnACYA9GFy/DrAeRrKHXvHn+1SUsOWgJp6RO+g==}
+    engines: {node: '>= 0.4'}
+
+  typescript-eslint@8.50.1:
+    resolution: {integrity: sha512-ytTHO+SoYSbhAH9CrYnMhiLx8To6PSSvqnvXyPUgPETCvB6eBKmTI9w6XMPS3HsBRGkwTVBX+urA8dYQx6bHfQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  typescript@5.8.3:
+    resolution: {integrity: sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  ufo@1.6.4:
+    resolution: {integrity: sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==}
+
+  unbox-primitive@1.1.0:
+    resolution: {integrity: sha512-nWJ91DjeOkej/TA8pXQ3myruKpKEYgqvpw9lz4OPHj/NWFNluYrjbz9j01CJ8yKQd2g4jFoOkINCTW2I5LEEyw==}
+    engines: {node: '>= 0.4'}
+
+  unconfig-core@7.5.0:
+    resolution: {integrity: sha512-Su3FauozOGP44ZmKdHy2oE6LPjk51M/TRRjHv2HNCWiDvfvCoxC2lno6jevMA91MYAdCdwP05QnWdWpSbncX/w==}
+
+  unconfig@7.5.0:
+    resolution: {integrity: sha512-oi8Qy2JV4D3UQ0PsopR28CzdQ3S/5A1zwsUwp/rosSbfhJ5z7b90bIyTwi/F7hCLD4SGcZVjDzd4XoUQcEanvA==}
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+  unicode-trie@2.0.0:
+    resolution: {integrity: sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ==}
+
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position-from-estree@2.0.0:
+    resolution: {integrity: sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-remove-position@5.0.0:
+    resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==}
+
+  unist-util-remove@4.0.0:
+    resolution: {integrity: sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
+  universalify@2.0.1:
+    resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
+    engines: {node: '>= 10.0.0'}
+
+  unplugin@2.1.0:
+    resolution: {integrity: sha512-us4j03/499KhbGP8BU7Hrzrgseo+KdfJYWcbcajCOqsAyb8Gk0Yn2kiUIcZISYCb1JFaZfIuG3b42HmguVOKCQ==}
+    engines: {node: '>=18.12.0'}
+
+  unplugin@2.3.11:
+    resolution: {integrity: sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww==}
+    engines: {node: '>=18.12.0'}
+
+  unrs-resolver@1.12.2:
+    resolution: {integrity: sha512-dmlRxBJJayXjqTwC+JtF1HhJmgf3ftQ3YejFcZrf4+KKtJv0qDsK1pjqaaVjG7wJ5NJ6UVP1OqRMQ71Z4C3rxQ==}
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  uri-js@4.4.1:
+    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  usehooks-ts@3.1.1:
+    resolution: {integrity: sha512-I4diPp9Cq6ieSUH2wu+fDAVQO43xwtulo+fKEidHUwZPnYImbtkTjzIJYcDcJqxgmX31GVqNFURodvcgHcW0pA==}
+    engines: {node: '>=16.15.0'}
+    peerDependencies:
+      react: ^16.8.0  || ^17 || ^18 || ^19 || ^19.0.0-rc
+
+  util-deprecate@1.0.2:
+    resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
+
+  utility-types@3.11.0:
+    resolution: {integrity: sha512-6Z7Ma2aVEWisaL6TvBCy7P8rm2LQoPv6dJ7ecIaIixHcwfbJ0x7mWdbcwlIM5IGQxPZSFYeqRCqlOOeKoJYMkw==}
+    engines: {node: '>= 4'}
+
+  vfile-location@5.0.3:
+    resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
+
+  vfile-matter@5.0.1:
+    resolution: {integrity: sha512-o6roP82AiX0XfkyTHyRCMXgHfltUNlXSEqCIS80f+mbAyiQBE2fxtDVMtseyytGx75sihiJFo/zR6r/4LTs2Cw==}
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
+  vite@7.3.0:
+    resolution: {integrity: sha512-dZwN5L1VlUBewiP6H9s2+B3e3Jg96D0vzN+Ry73sOefebhYr9f94wwkMNN/9ouoU8pV1BqA1d1zGk8928cx0rg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      lightningcss: ^1.21.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vitest@4.0.16:
+    resolution: {integrity: sha512-E4t7DJ9pESL6E3I8nFjPa4xGUd3PmiWDLsDztS2qXSJWfHtbQnwAWylaBvSNY48I3vr8PTqIZlyK8TE3V3CA4Q==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.0.16
+      '@vitest/browser-preview': 4.0.16
+      '@vitest/browser-webdriverio': 4.0.16
+      '@vitest/ui': 4.0.16
+      happy-dom: '*'
+      jsdom: '*'
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  wcag-contrast@3.0.0:
+    resolution: {integrity: sha512-RWbpg/S7FOXDCwqC2oFhN/vh8dHzj0OS6dpyOSDHyQFSmqmR+lAUStV/ziTT1GzDqL9wol+nZQB4vCi5yEak+w==}
+
+  weak-lru-cache@1.2.2:
+    resolution: {integrity: sha512-DEAoo25RfSYMuTGc9vPJzZcZullwIqRDSI9LOy+fkCJPi6hykCnfKaXTuPBDuXAUcqHXyOgFtHNp/kB2FjYHbw==}
+
+  web-namespaces@2.0.1:
+    resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+
+  webpack-virtual-modules@0.6.2:
+    resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
+
+  which-boxed-primitive@1.1.1:
+    resolution: {integrity: sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==}
+    engines: {node: '>= 0.4'}
+
+  which-builtin-type@1.2.1:
+    resolution: {integrity: sha512-6iBczoX+kDQ7a3+YJBnh3T+KZRxM/iYNPXicqk66/Qfm1b93iu+yOImkg0zHbj5LNOcNv1TEADiZ0xa34B4q6Q==}
+    engines: {node: '>= 0.4'}
+
+  which-collection@1.0.2:
+    resolution: {integrity: sha512-K4jVyjnBdgvc86Y6BkaLZEN933SwYOuBFkdmBu9ZfkcAbdVbpITnDmjvZ/aQjRXQrv5EPkTnD1s39GiiqbngCw==}
+    engines: {node: '>= 0.4'}
+
+  which-typed-array@1.1.22:
+    resolution: {integrity: sha512-fvO4ExWMFsqyhG3AiPAObMuY1lxaqgYcxbc49CNdWDDECOJNgQyvsOWVwbZc+qf3rzRtxojBK+CMEv0Ld5CYpw==}
+    engines: {node: '>= 0.4'}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  word-wrap@1.2.5:
+    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
+    engines: {node: '>=0.10.0'}
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  wrap-ansi@9.0.2:
+    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
+    engines: {node: '>=18'}
+
+  ws@8.21.0:
+    resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
+  wsl-utils@0.1.0:
+    resolution: {integrity: sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==}
+    engines: {node: '>=18'}
+
+  xml-js@1.6.11:
+    resolution: {integrity: sha512-7rVi2KMfwfWFl+GpPg6m80IVMWXLRjO+PxTq7V2CDhoGak0wzYzFgUY2m4XJ47OGdXd8eLE8EmwfAmdjw7lC1g==}
+    hasBin: true
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
+  yallist@5.0.0:
+    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
+    engines: {node: '>=18'}
+
+  yaml@1.10.3:
+    resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==}
+    engines: {node: '>= 6'}
+
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@17.7.2:
+    resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
+    engines: {node: '>=12'}
+
+  yocto-queue@0.1.0:
+    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
+    engines: {node: '>=10'}
+
+  yoga-layout@3.2.1:
+    resolution: {integrity: sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==}
+
+  zod-validation-error@4.0.2:
+    resolution: {integrity: sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+
+  zod@4.2.1:
+    resolution: {integrity: sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw==}
+
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
+snapshots:
+
+  '@adobe/css-tools@4.5.0': {}
+
+  '@adobe/react-spectrum-ui@1.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@adobe/react-spectrum-workflow@2.3.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@adobe/react-spectrum@3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@spectrum-icons/ui': 3.7.1(@adobe/react-spectrum@3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@spectrum-icons/workflow': 4.3.1(@adobe/react-spectrum@3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      client-only: 0.0.1
+      clsx: 2.1.1
+      react: 19.2.6
+      react-aria: 3.49.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-aria-components: 1.18.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.47.0(react@19.2.6)
+      react-transition-group: 4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      use-sync-external-store: 1.6.0(react@19.2.6)
+
+  '@alloc/quick-lru@5.2.0': {}
+
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.7': {}
+
+  '@babel/core@7.28.5':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-compilation-targets': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.28.5)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-annotate-as-pure@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/helper-compilation-targets@7.29.7':
+    dependencies:
+      '@babel/compat-data': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      browserslist: 4.28.2
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-create-class-features-plugin@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-member-expression-to-functions': 7.29.7
+      '@babel/helper-optimise-call-expression': 7.29.7
+      '@babel/helper-replace-supers': 7.29.7(@babel/core@7.28.5)
+      '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
+      '@babel/traverse': 7.29.7
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-member-expression-to-functions@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-optimise-call-expression@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/helper-plugin-utils@7.29.7': {}
+
+  '@babel/helper-replace-supers@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-member-expression-to-functions': 7.29.7
+      '@babel/helper-optimise-call-expression': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/helper-validator-option@7.29.7': {}
+
+  '@babel/helpers@7.29.7':
+    dependencies:
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-modules-commonjs@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.28.5)
+      '@babel/helper-plugin-utils': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-react-display-name@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-react-jsx-development@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/plugin-transform-react-jsx': 7.29.7(@babel/core@7.28.5)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-react-jsx-self@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-react-jsx-source@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-react-jsx@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.28.5)
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-react-pure-annotations@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-typescript@7.29.7(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-create-class-features-plugin': 7.29.7(@babel/core@7.28.5)
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
+      '@babel/plugin-syntax-typescript': 7.29.7(@babel/core@7.28.5)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/preset-react@7.28.5(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      '@babel/plugin-transform-react-display-name': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-react-jsx': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-react-jsx-development': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-react-pure-annotations': 7.29.7(@babel/core@7.28.5)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/preset-typescript@7.28.5(@babel/core@7.28.5)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-modules-commonjs': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-typescript': 7.29.7(@babel/core@7.28.5)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/runtime@7.29.7': {}
+
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
+  '@clack/core@0.3.5':
+    dependencies:
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
+  '@clack/prompts@0.8.2':
+    dependencies:
+      '@clack/core': 0.3.5
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
+  '@commitlint/cli@20.2.0(@types/node@25.0.3)(conventional-commits-parser@6.4.0)(typescript@5.9.3)':
+    dependencies:
+      '@commitlint/format': 20.5.0
+      '@commitlint/lint': 20.5.3
+      '@commitlint/load': 20.5.3(@types/node@25.0.3)(typescript@5.9.3)
+      '@commitlint/read': 20.5.0(conventional-commits-parser@6.4.0)
+      '@commitlint/types': 20.5.0
+      tinyexec: 1.2.4
+      yargs: 17.7.2
+    transitivePeerDependencies:
+      - '@types/node'
+      - conventional-commits-filter
+      - conventional-commits-parser
+      - typescript
+
+  '@commitlint/config-conventional@20.2.0':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      conventional-changelog-conventionalcommits: 7.0.2
+
+  '@commitlint/config-validator@20.5.0':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      ajv: 8.20.0
+
+  '@commitlint/ensure@20.5.3':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      es-toolkit: 1.47.0
+
+  '@commitlint/execute-rule@20.0.0': {}
+
+  '@commitlint/format@20.5.0':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      picocolors: 1.1.1
+
+  '@commitlint/is-ignored@20.5.0':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      semver: 7.8.2
+
+  '@commitlint/lint@20.5.3':
+    dependencies:
+      '@commitlint/is-ignored': 20.5.0
+      '@commitlint/parse': 20.5.0
+      '@commitlint/rules': 20.5.3
+      '@commitlint/types': 20.5.0
+
+  '@commitlint/load@20.5.3(@types/node@25.0.3)(typescript@5.9.3)':
+    dependencies:
+      '@commitlint/config-validator': 20.5.0
+      '@commitlint/execute-rule': 20.0.0
+      '@commitlint/resolve-extends': 20.5.3
+      '@commitlint/types': 20.5.0
+      cosmiconfig: 9.0.1(typescript@5.9.3)
+      cosmiconfig-typescript-loader: 6.3.0(@types/node@25.0.3)(cosmiconfig@9.0.1(typescript@5.9.3))(typescript@5.9.3)
+      es-toolkit: 1.47.0
+      is-plain-obj: 4.1.0
+      picocolors: 1.1.1
+    transitivePeerDependencies:
+      - '@types/node'
+      - typescript
+
+  '@commitlint/message@20.4.3': {}
+
+  '@commitlint/parse@20.5.0':
+    dependencies:
+      '@commitlint/types': 20.5.0
+      conventional-changelog-angular: 8.3.1
+      conventional-commits-parser: 6.4.0
+
+  '@commitlint/read@20.5.0(conventional-commits-parser@6.4.0)':
+    dependencies:
+      '@commitlint/top-level': 20.4.3
+      '@commitlint/types': 20.5.0
+      git-raw-commits: 5.0.1(conventional-commits-parser@6.4.0)
+      minimist: 1.2.8
+      tinyexec: 1.2.4
+    transitivePeerDependencies:
+      - conventional-commits-filter
+      - conventional-commits-parser
+
+  '@commitlint/resolve-extends@20.5.3':
+    dependencies:
+      '@commitlint/config-validator': 20.5.0
+      '@commitlint/types': 20.5.0
+      es-toolkit: 1.47.0
+      global-directory: 5.0.0
+      import-meta-resolve: 4.2.0
+      resolve-from: 5.0.0
+
+  '@commitlint/rules@20.5.3':
+    dependencies:
+      '@commitlint/ensure': 20.5.3
+      '@commitlint/message': 20.4.3
+      '@commitlint/to-lines': 20.0.0
+      '@commitlint/types': 20.5.0
+
+  '@commitlint/to-lines@20.0.0': {}
+
+  '@commitlint/top-level@20.4.3':
+    dependencies:
+      escalade: 3.2.0
+
+  '@commitlint/types@20.5.0':
+    dependencies:
+      conventional-commits-parser: 6.4.0
+      picocolors: 1.1.1
+
+  '@conventional-changelog/git-client@2.7.0(conventional-commits-parser@6.4.0)':
+    dependencies:
+      '@simple-libs/child-process-utils': 1.0.2
+      '@simple-libs/stream-utils': 1.2.0
+      semver: 7.8.2
+    optionalDependencies:
+      conventional-commits-parser: 6.4.0
+
+  '@corex/deepmerge@4.0.43': {}
+
+  '@emnapi/core@1.10.0':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.1
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.10.0':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@esbuild/aix-ppc64@0.25.12':
+    optional: true
+
+  '@esbuild/aix-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm@0.25.12':
+    optional: true
+
+  '@esbuild/android-arm@0.27.7':
+    optional: true
+
+  '@esbuild/android-x64@0.25.12':
+    optional: true
+
+  '@esbuild/android-x64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-x64@0.25.12':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm@0.25.12':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ia32@0.25.12':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/linux-loong64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.25.12':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-s390x@0.25.12':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.7':
+    optional: true
+
+  '@esbuild/linux-x64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/sunos-x64@0.25.12':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-ia32@0.25.12':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/win32-x64@0.25.12':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.7':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.9.1(eslint@9.39.2(jiti@2.6.1))':
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.21.2':
+    dependencies:
+      '@eslint/object-schema': 2.1.7
+      debug: 4.4.3
+      minimatch: 3.1.5
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/config-helpers@0.4.2':
+    dependencies:
+      '@eslint/core': 0.17.0
+
+  '@eslint/core@0.17.0':
+    dependencies:
+      '@types/json-schema': 7.0.15
+
+  '@eslint/eslintrc@3.3.3':
+    dependencies:
+      ajv: 6.15.0
+      debug: 4.4.3
+      espree: 10.4.0
+      globals: 14.0.0
+      ignore: 5.3.2
+      import-fresh: 3.3.1
+      js-yaml: 4.2.0
+      minimatch: 3.1.5
+      strip-json-comments: 3.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/js@9.39.2': {}
+
+  '@eslint/object-schema@2.1.7': {}
+
+  '@eslint/plugin-kit@0.4.1':
+    dependencies:
+      '@eslint/core': 0.17.0
+      levn: 0.4.1
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/react-dom@2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@formatjs/ecma402-abstract@2.3.6':
+    dependencies:
+      '@formatjs/fast-memoize': 2.2.7
+      '@formatjs/intl-localematcher': 0.6.2
+      decimal.js: 10.6.0
+      tslib: 2.8.1
+
+  '@formatjs/fast-memoize@2.2.7':
+    dependencies:
+      tslib: 2.8.1
+
+  '@formatjs/icu-messageformat-parser@2.11.4':
+    dependencies:
+      '@formatjs/ecma402-abstract': 2.3.6
+      '@formatjs/icu-skeleton-parser': 1.8.16
+      tslib: 2.8.1
+
+  '@formatjs/icu-skeleton-parser@1.8.16':
+    dependencies:
+      '@formatjs/ecma402-abstract': 2.3.6
+      tslib: 2.8.1
+
+  '@formatjs/intl-localematcher@0.6.2':
+    dependencies:
+      tslib: 2.8.1
+
+  '@fumadocs/language@0.0.1(15443bcb60600a3f8a026059ee77d437)':
+    optionalDependencies:
+      fumadocs-core: 16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1)
+      fumadocs-ui: 16.9.0(@tailwindcss/oxide@4.3.0)(@types/mdx@2.0.13)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tailwindcss@4.3.0)
+
+  '@fumadocs/tailwind@0.0.5(@tailwindcss/oxide@4.3.0)(tailwindcss@4.3.0)':
+    optionalDependencies:
+      '@tailwindcss/oxide': 4.3.0
+      tailwindcss: 4.3.0
+
+  '@gravity-ui/icons@2.16.0(react@19.2.6)':
+    dependencies:
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.6
+
+  '@humanfs/core@0.19.2':
+    dependencies:
+      '@humanfs/types': 0.15.0
+
+  '@humanfs/node@0.16.8':
+    dependencies:
+      '@humanfs/core': 0.19.2
+      '@humanfs/types': 0.15.0
+      '@humanwhocodes/retry': 0.4.3
+
+  '@humanfs/types@0.15.0': {}
+
+  '@humanwhocodes/module-importer@1.0.1': {}
+
+  '@humanwhocodes/retry@0.4.3': {}
+
+  '@iconify-json/gravity-ui@1.2.10':
+    dependencies:
+      '@iconify/types': 2.0.0
+
+  '@iconify/react@6.0.2(react@19.2.6)':
+    dependencies:
+      '@iconify/types': 2.0.0
+      react: 19.2.6
+
+  '@iconify/types@2.0.0': {}
+
+  '@img/colour@1.1.0':
+    optional: true
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-s390x@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.10.0
+    optional: true
+
+  '@img/sharp-win32-arm64@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
+  '@internationalized/date@3.12.2':
+    dependencies:
+      '@swc/helpers': 0.5.23
+
+  '@internationalized/message@3.1.10':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      intl-messageformat: 10.7.18
+
+  '@internationalized/number@3.6.7':
+    dependencies:
+      '@swc/helpers': 0.5.23
+
+  '@internationalized/string@3.2.9':
+    dependencies:
+      '@swc/helpers': 0.5.23
+
+  '@isaacs/fs-minipass@4.0.1':
+    dependencies:
+      minipass: 7.1.3
+
+  '@joshwooding/vite-plugin-react-docgen-typescript@0.6.4(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      glob: 13.0.6
+      react-docgen-typescript: 2.4.0(typescript@5.9.3)
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+    optionalDependencies:
+      typescript: 5.9.3
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@lezer/common@1.5.2': {}
+
+  '@lezer/lr@1.4.10':
+    dependencies:
+      '@lezer/common': 1.5.2
+
+  '@lglab/react-qr-code@1.7.0(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+
+  '@lmdb/lmdb-darwin-arm64@2.8.5':
+    optional: true
+
+  '@lmdb/lmdb-darwin-x64@2.8.5':
+    optional: true
+
+  '@lmdb/lmdb-linux-arm64@2.8.5':
+    optional: true
+
+  '@lmdb/lmdb-linux-arm@2.8.5':
+    optional: true
+
+  '@lmdb/lmdb-linux-x64@2.8.5':
+    optional: true
+
+  '@lmdb/lmdb-win32-x64@2.8.5':
+    optional: true
+
+  '@mdx-js/mdx@3.1.1':
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdx': 2.0.13
+      acorn: 8.16.0
+      collapse-white-space: 2.1.0
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-util-scope: 1.0.0
+      estree-walker: 3.0.3
+      hast-util-to-jsx-runtime: 2.3.6
+      markdown-extensions: 2.0.0
+      recma-build-jsx: 1.0.0
+      recma-jsx: 1.0.1(acorn@8.16.0)
+      recma-stringify: 1.0.0
+      rehype-recma: 1.0.0
+      remark-mdx: 3.1.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      source-map: 0.7.6
+      unified: 11.0.5
+      unist-util-position-from-estree: 2.0.0
+      unist-util-stringify-position: 4.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@types/mdx': 2.0.13
+      '@types/react': 19.2.14
+      react: 19.2.6
+
+  '@mischnic/json-sourcemap@0.1.1':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/lr': 1.4.10
+      json5: 2.2.3
+
+  '@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4':
+    optional: true
+
+  '@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4':
+    optional: true
+
+  '@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4':
+    optional: true
+
+  '@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4':
+    optional: true
+
+  '@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4':
+    optional: true
+
+  '@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4':
+    optional: true
+
+  '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@tybys/wasm-util': 0.10.2
+    optional: true
+
+  '@next/env@13.5.11': {}
+
+  '@next/env@16.2.6': {}
+
+  '@next/eslint-plugin-next@16.1.1':
+    dependencies:
+      fast-glob: 3.3.1
+
+  '@next/swc-darwin-arm64@16.2.6':
+    optional: true
+
+  '@next/swc-darwin-x64@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    optional: true
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    optional: true
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
+  '@nolyfill/is-core-module@1.0.39': {}
+
+  '@opentelemetry/api@1.9.1':
+    optional: true
+
+  '@orama/orama@3.1.18': {}
+
+  '@parcel/bundler-default@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/graph': 3.6.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/cache@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/fs': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/logger': 2.16.3
+      '@parcel/utils': 2.16.3
+      lmdb: 2.8.5
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/codeframe@2.16.3':
+    dependencies:
+      chalk: 4.1.2
+
+  '@parcel/compressor-raw@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/config-default@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)':
+    dependencies:
+      '@parcel/bundler-default': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/compressor-raw': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/namer-default': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/optimizer-css': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/optimizer-html': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/optimizer-image': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/optimizer-svg': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/optimizer-swc': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)
+      '@parcel/packager-css': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/packager-html': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/packager-js': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/packager-raw': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/packager-svg': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/packager-wasm': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/reporter-dev-server': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/resolver-default': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/runtime-browser-hmr': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/runtime-js': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/runtime-rsc': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/runtime-service-worker': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-babel': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-css': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-html': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-image': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-js': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-json': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-node': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-postcss': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-posthtml': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-raw': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-react-refresh-wrap': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/transformer-svg': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@swc/helpers'
+      - napi-wasm
+
+  '@parcel/core@2.16.3(@swc/helpers@0.5.23)':
+    dependencies:
+      '@mischnic/json-sourcemap': 0.1.1
+      '@parcel/cache': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/events': 2.16.3
+      '@parcel/feature-flags': 2.16.3
+      '@parcel/fs': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/graph': 3.6.3
+      '@parcel/logger': 2.16.3
+      '@parcel/package-manager': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/profiler': 2.16.3
+      '@parcel/rust': 2.16.3
+      '@parcel/source-map': 2.1.1
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      base-x: 3.0.11
+      browserslist: 4.28.2
+      clone: 2.1.2
+      dotenv: 16.6.1
+      dotenv-expand: 11.0.7
+      json5: 2.2.3
+      msgpackr: 1.11.13
+      nullthrows: 1.1.1
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - '@swc/helpers'
+      - napi-wasm
+
+  '@parcel/diagnostic@2.16.3':
+    dependencies:
+      '@mischnic/json-sourcemap': 0.1.1
+      nullthrows: 1.1.1
+
+  '@parcel/error-overlay@2.16.3': {}
+
+  '@parcel/events@2.16.3': {}
+
+  '@parcel/feature-flags@2.16.3': {}
+
+  '@parcel/fs@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/feature-flags': 2.16.3
+      '@parcel/rust': 2.16.3
+      '@parcel/types-internal': 2.16.3
+      '@parcel/utils': 2.16.3
+      '@parcel/watcher': 2.5.6
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/graph@3.6.3':
+    dependencies:
+      '@parcel/feature-flags': 2.16.3
+      nullthrows: 1.1.1
+
+  '@parcel/logger@2.16.3':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/events': 2.16.3
+
+  '@parcel/markdown-ansi@2.16.3':
+    dependencies:
+      chalk: 4.1.2
+
+  '@parcel/namer-default@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/node-resolver-core@3.7.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@mischnic/json-sourcemap': 0.1.1
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/fs': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/optimizer-css@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      browserslist: 4.28.2
+      lightningcss: 1.32.0
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/optimizer-html@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/optimizer-image@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/optimizer-svg@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/optimizer-swc@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      '@swc/core': 1.15.40(@swc/helpers@0.5.23)
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - '@swc/helpers'
+      - napi-wasm
+
+  '@parcel/package-manager@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/fs': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/logger': 2.16.3
+      '@parcel/node-resolver-core': 3.7.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@swc/core': 1.15.40(@swc/helpers@0.5.23)
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - '@swc/helpers'
+      - napi-wasm
+
+  '@parcel/packager-css@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      lightningcss: 1.32.0
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/packager-html@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/packager-js@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/source-map': 2.1.1
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      globals: 13.24.0
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/packager-raw@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/packager-svg@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/packager-wasm@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/plugin@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/profiler@2.16.3':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/events': 2.16.3
+      '@parcel/types-internal': 2.16.3
+      chrome-trace-event: 1.0.4
+
+  '@parcel/reporter-cli@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/types': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      chalk: 4.1.2
+      term-size: 2.2.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/reporter-dev-server@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/codeframe': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/reporter-tracer@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      chrome-trace-event: 1.0.4
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/resolver-default@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/node-resolver-core': 3.7.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/runtime-browser-hmr@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/runtime-js@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/runtime-rsc@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/runtime-service-worker@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/rust-darwin-arm64@2.16.3':
+    optional: true
+
+  '@parcel/rust-darwin-x64@2.16.3':
+    optional: true
+
+  '@parcel/rust-linux-arm-gnueabihf@2.16.3':
+    optional: true
+
+  '@parcel/rust-linux-arm64-gnu@2.16.3':
+    optional: true
+
+  '@parcel/rust-linux-arm64-musl@2.16.3':
+    optional: true
+
+  '@parcel/rust-linux-x64-gnu@2.16.3':
+    optional: true
+
+  '@parcel/rust-linux-x64-musl@2.16.3':
+    optional: true
+
+  '@parcel/rust-win32-x64-msvc@2.16.3':
+    optional: true
+
+  '@parcel/rust@2.16.3':
+    optionalDependencies:
+      '@parcel/rust-darwin-arm64': 2.16.3
+      '@parcel/rust-darwin-x64': 2.16.3
+      '@parcel/rust-linux-arm-gnueabihf': 2.16.3
+      '@parcel/rust-linux-arm64-gnu': 2.16.3
+      '@parcel/rust-linux-arm64-musl': 2.16.3
+      '@parcel/rust-linux-x64-gnu': 2.16.3
+      '@parcel/rust-linux-x64-musl': 2.16.3
+      '@parcel/rust-win32-x64-msvc': 2.16.3
+
+  '@parcel/source-map@2.1.1':
+    dependencies:
+      detect-libc: 1.0.3
+
+  '@parcel/transformer-babel@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      browserslist: 4.28.2
+      json5: 2.2.3
+      nullthrows: 1.1.1
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-css@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      browserslist: 4.28.2
+      lightningcss: 1.32.0
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-html@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-image@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/transformer-js@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/source-map': 2.1.1
+      '@parcel/utils': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@swc/helpers': 0.5.23
+      browserslist: 4.28.2
+      nullthrows: 1.1.1
+      regenerator-runtime: 0.14.1
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/transformer-json@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      json5: 2.2.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-node@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-postcss@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+      '@parcel/utils': 2.16.3
+      clone: 2.1.2
+      nullthrows: 1.1.1
+      postcss-value-parser: 4.2.0
+      semver: 7.8.2
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-posthtml@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-raw@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-react-refresh-wrap@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/error-overlay': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      react-refresh: 0.16.0
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/transformer-svg@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/plugin': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/rust': 2.16.3
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/types-internal@2.16.3':
+    dependencies:
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/feature-flags': 2.16.3
+      '@parcel/source-map': 2.1.1
+      utility-types: 3.11.0
+
+  '@parcel/types@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/types-internal': 2.16.3
+      '@parcel/workers': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+    transitivePeerDependencies:
+      - '@parcel/core'
+      - napi-wasm
+
+  '@parcel/utils@2.16.3':
+    dependencies:
+      '@parcel/codeframe': 2.16.3
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/logger': 2.16.3
+      '@parcel/markdown-ansi': 2.16.3
+      '@parcel/rust': 2.16.3
+      '@parcel/source-map': 2.1.1
+      chalk: 4.1.2
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@parcel/watcher-android-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-darwin-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-darwin-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-freebsd-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm64-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm64-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-x64-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-x64-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-ia32@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher@2.5.6':
+    dependencies:
+      detect-libc: 2.1.2
+      is-glob: 4.0.3
+      node-addon-api: 7.1.1
+      picomatch: 4.0.4
+    optionalDependencies:
+      '@parcel/watcher-android-arm64': 2.5.6
+      '@parcel/watcher-darwin-arm64': 2.5.6
+      '@parcel/watcher-darwin-x64': 2.5.6
+      '@parcel/watcher-freebsd-x64': 2.5.6
+      '@parcel/watcher-linux-arm-glibc': 2.5.6
+      '@parcel/watcher-linux-arm-musl': 2.5.6
+      '@parcel/watcher-linux-arm64-glibc': 2.5.6
+      '@parcel/watcher-linux-arm64-musl': 2.5.6
+      '@parcel/watcher-linux-x64-glibc': 2.5.6
+      '@parcel/watcher-linux-x64-musl': 2.5.6
+      '@parcel/watcher-win32-arm64': 2.5.6
+      '@parcel/watcher-win32-ia32': 2.5.6
+      '@parcel/watcher-win32-x64': 2.5.6
+
+  '@parcel/workers@2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))':
+    dependencies:
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/logger': 2.16.3
+      '@parcel/profiler': 2.16.3
+      '@parcel/types-internal': 2.16.3
+      '@parcel/utils': 2.16.3
+      nullthrows: 1.1.1
+    transitivePeerDependencies:
+      - napi-wasm
+
+  '@pivanov/utils@0.0.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@pkgr/core@0.3.6': {}
+
+  '@posthog/core@1.9.1':
+    dependencies:
+      cross-spawn: 7.0.6
+
+  '@preact/signals-core@1.14.2': {}
+
+  '@preact/signals@1.3.4(preact@10.29.2)':
+    dependencies:
+      '@preact/signals-core': 1.14.2
+      preact: 10.29.2
+
+  '@quansync/fs@1.0.0':
+    dependencies:
+      quansync: 1.0.0
+
+  '@radix-ui/number@1.1.2': {}
+
+  '@radix-ui/primitive@1.1.4': {}
+
+  '@radix-ui/react-accordion@1.2.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-arrow@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-avatar@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.4(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collapsible@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collection@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.5(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-compose-refs@1.1.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-context@1.1.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-context@1.1.4(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dialog@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.5(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-direction@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-id@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popover@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.5(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popper@1.3.0(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-rect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/rect': 1.1.2
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-portal@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-presence@1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-primitive@2.1.4(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.4(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-primitive@2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.5(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-slot@1.2.4(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-slot@1.2.5(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-tabs@1.1.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-context': 1.1.4(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-effect-event@0.0.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-is-hydrated@0.1.0(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-previous@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-rect@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/rect': 1.1.2
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-size@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/rect@1.1.2': {}
+
+  '@react-aria/color@3.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-aria/i18n@3.13.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@internationalized/message': 3.1.10
+      '@internationalized/string': 3.2.9
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-aria/overlays@3.32.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-aria/ssr@3.10.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-aria/utils@3.34.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  '@react-spectrum/color@3.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@adobe/react-spectrum': 3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  '@react-spectrum/provider@3.11.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@adobe/react-spectrum': 3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-stately/color@3.10.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  '@react-stately/data@3.16.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  '@react-stately/utils@3.12.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  '@react-types/color@3.2.0(@react-spectrum/provider@3.11.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@react-aria/color': 3.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-spectrum/color': 3.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-spectrum/provider': 3.11.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-stately/color': 3.10.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@react-types/shared@3.36.0(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+
+  '@resvg/resvg-wasm@2.4.0': {}
+
+  '@rolldown/pluginutils@1.0.0-beta.53': {}
+
+  '@rollup/plugin-babel@6.1.0(@babel/core@7.28.5)(@types/babel__core@7.20.5)(rollup@4.54.0)':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/helper-module-imports': 7.29.7
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+    optionalDependencies:
+      '@types/babel__core': 7.20.5
+      rollup: 4.54.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@rollup/plugin-commonjs@29.0.0(rollup@4.54.0)':
+    dependencies:
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+      commondir: 1.0.1
+      estree-walker: 2.0.2
+      fdir: 6.5.0(picomatch@4.0.4)
+      is-reference: 1.2.1
+      magic-string: 0.30.21
+      picomatch: 4.0.4
+    optionalDependencies:
+      rollup: 4.54.0
+
+  '@rollup/plugin-node-resolve@16.0.3(rollup@4.54.0)':
+    dependencies:
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+      '@types/resolve': 1.20.2
+      deepmerge: 4.3.1
+      is-module: 1.0.0
+      resolve: 1.22.12
+    optionalDependencies:
+      rollup: 4.54.0
+
+  '@rollup/plugin-typescript@12.3.0(rollup@4.54.0)(tslib@2.8.1)(typescript@5.9.3)':
+    dependencies:
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+      resolve: 1.22.12
+      typescript: 5.9.3
+    optionalDependencies:
+      rollup: 4.54.0
+      tslib: 2.8.1
+
+  '@rollup/pluginutils@5.4.0(rollup@4.54.0)':
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-walker: 2.0.2
+      picomatch: 4.0.4
+    optionalDependencies:
+      rollup: 4.54.0
+
+  '@rollup/rollup-android-arm-eabi@4.54.0':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.54.0':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.54.0':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.54.0':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.54.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.54.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.54.0':
+    optional: true
+
+  '@rtsao/scc@1.1.0': {}
+
+  '@shikijs/core@3.20.0':
+    dependencies:
+      '@shikijs/types': 3.20.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+      hast-util-to-html: 9.0.5
+
+  '@shikijs/engine-javascript@3.20.0':
+    dependencies:
+      '@shikijs/types': 3.20.0
+      '@shikijs/vscode-textmate': 10.0.2
+      oniguruma-to-es: 4.3.6
+
+  '@shikijs/engine-oniguruma@3.20.0':
+    dependencies:
+      '@shikijs/types': 3.20.0
+      '@shikijs/vscode-textmate': 10.0.2
+
+  '@shikijs/langs@3.20.0':
+    dependencies:
+      '@shikijs/types': 3.20.0
+
+  '@shikijs/themes@3.20.0':
+    dependencies:
+      '@shikijs/types': 3.20.0
+
+  '@shikijs/types@3.20.0':
+    dependencies:
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/vscode-textmate@10.0.2': {}
+
+  '@shuding/opentype.js@1.4.0-beta.0':
+    dependencies:
+      fflate: 0.7.4
+      string.prototype.codepointat: 0.2.1
+
+  '@simple-libs/child-process-utils@1.0.2':
+    dependencies:
+      '@simple-libs/stream-utils': 1.2.0
+
+  '@simple-libs/stream-utils@1.2.0': {}
+
+  '@spectrum-icons/ui@3.7.1(@adobe/react-spectrum@3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@adobe/react-spectrum': 3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@adobe/react-spectrum-ui': 1.2.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@babel/runtime': 7.29.7
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@spectrum-icons/workflow@4.3.1(@adobe/react-spectrum@3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@adobe/react-spectrum': 3.47.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@adobe/react-spectrum-workflow': 2.3.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@standard-schema/spec@1.0.0': {}
+
+  '@standard-schema/spec@1.1.0': {}
+
+  '@storybook/addon-a11y@10.1.10(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))':
+    dependencies:
+      '@storybook/global': 5.0.0
+      axe-core: 4.12.0
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
+  '@storybook/addon-docs@10.1.10(@types/react@19.2.14)(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@mdx-js/react': 3.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@storybook/csf-plugin': 10.1.10(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@storybook/icons': 2.0.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@storybook/react-dom-shim': 10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      ts-dedent: 2.2.0
+    transitivePeerDependencies:
+      - '@types/react'
+      - esbuild
+      - rollup
+      - vite
+      - webpack
+
+  '@storybook/builder-vite@10.1.10(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@storybook/csf-plugin': 10.1.10(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/mocker': 3.2.4(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      ts-dedent: 2.2.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - esbuild
+      - msw
+      - rollup
+      - webpack
+
+  '@storybook/csf-plugin@10.1.10(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      unplugin: 2.3.11
+    optionalDependencies:
+      esbuild: 0.27.7
+      rollup: 4.54.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@storybook/global@5.0.0': {}
+
+  '@storybook/icons@2.0.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@storybook/react-dom-shim@10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))':
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
+  '@storybook/react-vite@10.1.10(esbuild@0.27.7)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@joshwooding/vite-plugin-react-docgen-typescript': 0.6.4(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+      '@storybook/builder-vite': 10.1.10(esbuild@0.27.7)(rollup@4.54.0)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@storybook/react': 10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)
+      empathic: 2.0.1
+      magic-string: 0.30.21
+      react: 19.2.6
+      react-docgen: 8.0.3
+      react-dom: 19.2.6(react@19.2.6)
+      resolve: 1.22.12
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tsconfig-paths: 4.2.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - esbuild
+      - msw
+      - rollup
+      - supports-color
+      - typescript
+      - webpack
+
+  '@storybook/react@10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3)':
+    dependencies:
+      '@storybook/global': 5.0.0
+      '@storybook/react-dom-shim': 10.1.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))
+      react: 19.2.6
+      react-docgen: 8.0.3
+      react-dom: 19.2.6(react@19.2.6)
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@swc/core-darwin-arm64@1.15.40':
+    optional: true
+
+  '@swc/core-darwin-x64@1.15.40':
+    optional: true
+
+  '@swc/core-linux-arm-gnueabihf@1.15.40':
+    optional: true
+
+  '@swc/core-linux-arm64-gnu@1.15.40':
+    optional: true
+
+  '@swc/core-linux-arm64-musl@1.15.40':
+    optional: true
+
+  '@swc/core-linux-ppc64-gnu@1.15.40':
+    optional: true
+
+  '@swc/core-linux-s390x-gnu@1.15.40':
+    optional: true
+
+  '@swc/core-linux-x64-gnu@1.15.40':
+    optional: true
+
+  '@swc/core-linux-x64-musl@1.15.40':
+    optional: true
+
+  '@swc/core-win32-arm64-msvc@1.15.40':
+    optional: true
+
+  '@swc/core-win32-ia32-msvc@1.15.40':
+    optional: true
+
+  '@swc/core-win32-x64-msvc@1.15.40':
+    optional: true
+
+  '@swc/core@1.15.40(@swc/helpers@0.5.23)':
+    dependencies:
+      '@swc/counter': 0.1.3
+      '@swc/types': 0.1.26
+    optionalDependencies:
+      '@swc/core-darwin-arm64': 1.15.40
+      '@swc/core-darwin-x64': 1.15.40
+      '@swc/core-linux-arm-gnueabihf': 1.15.40
+      '@swc/core-linux-arm64-gnu': 1.15.40
+      '@swc/core-linux-arm64-musl': 1.15.40
+      '@swc/core-linux-ppc64-gnu': 1.15.40
+      '@swc/core-linux-s390x-gnu': 1.15.40
+      '@swc/core-linux-x64-gnu': 1.15.40
+      '@swc/core-linux-x64-musl': 1.15.40
+      '@swc/core-win32-arm64-msvc': 1.15.40
+      '@swc/core-win32-ia32-msvc': 1.15.40
+      '@swc/core-win32-x64-msvc': 1.15.40
+      '@swc/helpers': 0.5.23
+
+  '@swc/counter@0.1.3': {}
+
+  '@swc/helpers@0.5.15':
+    dependencies:
+      tslib: 2.8.1
+
+  '@swc/helpers@0.5.23':
+    dependencies:
+      tslib: 2.8.1
+
+  '@swc/types@0.1.26':
+    dependencies:
+      '@swc/counter': 0.1.3
+
+  '@t3-oss/env-core@0.13.10(typescript@5.9.3)(zod@4.2.1)':
+    optionalDependencies:
+      typescript: 5.9.3
+      zod: 4.2.1
+
+  '@t3-oss/env-nextjs@0.13.10(typescript@5.9.3)(zod@4.2.1)':
+    dependencies:
+      '@t3-oss/env-core': 0.13.10(typescript@5.9.3)(zod@4.2.1)
+    optionalDependencies:
+      typescript: 5.9.3
+      zod: 4.2.1
+
+  '@tailwindcss/cli@4.3.0':
+    dependencies:
+      '@parcel/watcher': 2.5.6
+      '@tailwindcss/node': 4.3.0
+      '@tailwindcss/oxide': 4.3.0
+      enhanced-resolve: 5.23.0
+      mri: 1.2.0
+      picocolors: 1.1.1
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/node@4.3.0':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.23.0
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide@4.3.0':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-x64': 4.3.0
+      '@tailwindcss/oxide-freebsd-x64': 4.3.0
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.0
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.0
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.0
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.0
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.0
+
+  '@tailwindcss/postcss@4.3.0':
+    dependencies:
+      '@alloc/quick-lru': 5.2.0
+      '@tailwindcss/node': 4.3.0
+      '@tailwindcss/oxide': 4.3.0
+      postcss: 8.5.15
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.3.0)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/vite@4.3.0(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@tailwindcss/node': 4.3.0
+      '@tailwindcss/oxide': 4.3.0
+      tailwindcss: 4.3.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@tanstack/react-table@8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@tanstack/table-core': 8.21.3
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@tanstack/table-core@8.21.3': {}
+
+  '@testing-library/dom@10.4.1':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/runtime': 7.29.7
+      '@types/aria-query': 5.0.4
+      aria-query: 5.3.0
+      dom-accessibility-api: 0.5.16
+      lz-string: 1.5.0
+      picocolors: 1.1.1
+      pretty-format: 27.5.1
+
+  '@testing-library/jest-dom@6.9.1':
+    dependencies:
+      '@adobe/css-tools': 4.5.0
+      aria-query: 5.3.2
+      css.escape: 1.5.1
+      dom-accessibility-api: 0.6.3
+      picocolors: 1.1.1
+      redent: 3.0.0
+
+  '@testing-library/react@16.3.1(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@testing-library/dom': 10.4.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@testing-library/user-event@14.6.1(@testing-library/dom@10.4.1)':
+    dependencies:
+      '@testing-library/dom': 10.4.1
+
+  '@ts-morph/common@0.28.1':
+    dependencies:
+      minimatch: 10.2.5
+      path-browserify: 1.0.1
+      tinyglobby: 0.2.17
+
+  '@tybys/wasm-util@0.10.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@types/aria-query@5.0.4': {}
+
+  '@types/babel__core@7.20.5':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@types/babel__generator': 7.27.0
+      '@types/babel__template': 7.4.4
+      '@types/babel__traverse': 7.28.0
+
+  '@types/babel__generator@7.27.0':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@types/babel__template@7.4.4':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@types/babel__traverse@7.28.0':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/color-convert@2.0.4':
+    dependencies:
+      '@types/color-name': 1.1.5
+
+  '@types/color-name@1.1.5': {}
+
+  '@types/culori@4.0.1': {}
+
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/deep-eql@4.0.2': {}
+
+  '@types/doctrine@0.0.9': {}
+
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.9
+
+  '@types/estree@1.0.8': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@types/fs-extra@11.0.4':
+    dependencies:
+      '@types/jsonfile': 6.1.4
+      '@types/node': 25.0.3
+
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/json-schema@7.0.15': {}
+
+  '@types/json5@0.0.29': {}
+
+  '@types/jsonfile@6.1.4':
+    dependencies:
+      '@types/node': 25.0.3
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdx@2.0.13': {}
+
+  '@types/ms@2.1.0': {}
+
+  '@types/node@20.19.42':
+    dependencies:
+      undici-types: 6.21.0
+
+  '@types/node@25.0.3':
+    dependencies:
+      undici-types: 7.16.0
+
+  '@types/react-dom@19.2.3(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@types/react-reconciler@0.28.9(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@types/react@19.2.14':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/resolve@1.20.2': {}
+
+  '@types/resolve@1.20.6': {}
+
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
+  '@typescript-eslint/eslint-plugin@8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/scope-manager': 8.50.1
+      '@typescript-eslint/type-utils': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.50.1
+      eslint: 9.39.2(jiti@2.6.1)
+      ignore: 7.0.5
+      natural-compare: 1.4.0
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.50.1
+      '@typescript-eslint/types': 8.50.1
+      '@typescript-eslint/typescript-estree': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.50.1
+      debug: 4.4.3
+      eslint: 9.39.2(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.50.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.50.1
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.60.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.60.1
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.50.1':
+    dependencies:
+      '@typescript-eslint/types': 8.50.1
+      '@typescript-eslint/visitor-keys': 8.50.1
+
+  '@typescript-eslint/scope-manager@8.60.1':
+    dependencies:
+      '@typescript-eslint/types': 8.60.1
+      '@typescript-eslint/visitor-keys': 8.60.1
+
+  '@typescript-eslint/tsconfig-utils@8.50.1(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/tsconfig-utils@8.60.1(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/type-utils@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.50.1
+      '@typescript-eslint/typescript-estree': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      debug: 4.4.3
+      eslint: 9.39.2(jiti@2.6.1)
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.50.1': {}
+
+  '@typescript-eslint/types@8.60.1': {}
+
+  '@typescript-eslint/typescript-estree@8.50.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.50.1
+      '@typescript-eslint/visitor-keys': 8.50.1
+      debug: 4.4.3
+      minimatch: 9.0.9
+      semver: 7.8.2
+      tinyglobby: 0.2.17
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/typescript-estree@8.60.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.60.1(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.60.1
+      '@typescript-eslint/visitor-keys': 8.60.1
+      debug: 4.4.3
+      minimatch: 10.2.5
+      semver: 7.8.2
+      tinyglobby: 0.2.17
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@2.6.1))
+      '@typescript-eslint/scope-manager': 8.50.1
+      '@typescript-eslint/types': 8.50.1
+      '@typescript-eslint/typescript-estree': 8.50.1(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.60.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@2.6.1))
+      '@typescript-eslint/scope-manager': 8.60.1
+      '@typescript-eslint/types': 8.60.1
+      '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.50.1':
+    dependencies:
+      '@typescript-eslint/types': 8.50.1
+      eslint-visitor-keys: 4.2.1
+
+  '@typescript-eslint/visitor-keys@8.60.1':
+    dependencies:
+      '@typescript-eslint/types': 8.60.1
+      eslint-visitor-keys: 5.0.1
+
+  '@ungap/structured-clone@1.3.1': {}
+
+  '@unrs/resolver-binding-android-arm-eabi@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-android-arm64@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-darwin-arm64@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-darwin-x64@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-freebsd-x64@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm-gnueabihf@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm-musleabihf@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm64-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm64-musl@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-loong64-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-loong64-musl@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-ppc64-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-riscv64-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-riscv64-musl@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-s390x-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-x64-gnu@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-linux-x64-musl@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-openharmony-arm64@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-wasm32-wasi@1.12.2':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    optional: true
+
+  '@unrs/resolver-binding-win32-arm64-msvc@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-win32-ia32-msvc@1.12.2':
+    optional: true
+
+  '@unrs/resolver-binding-win32-x64-msvc@1.12.2':
+    optional: true
+
+  '@vercel/analytics@1.6.1(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6)':
+    optionalDependencies:
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+
+  '@vercel/og@0.8.6':
+    dependencies:
+      '@resvg/resvg-wasm': 2.4.0
+      satori: 0.16.0
+
+  '@vitejs/plugin-react@5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/plugin-transform-react-jsx-self': 7.29.7(@babel/core@7.28.5)
+      '@babel/plugin-transform-react-jsx-source': 7.29.7(@babel/core@7.28.5)
+      '@rolldown/pluginutils': 1.0.0-beta.53
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.18.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@vitest/expect@3.2.4':
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/spy': 3.2.4
+      '@vitest/utils': 3.2.4
+      chai: 5.3.3
+      tinyrainbow: 2.0.0
+
+  '@vitest/expect@4.0.16':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.0.16
+      '@vitest/utils': 4.0.16
+      chai: 6.2.2
+      tinyrainbow: 3.1.0
+
+  '@vitest/mocker@3.2.4(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 3.2.4
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@vitest/mocker@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 4.0.16
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@vitest/pretty-format@3.2.4':
+    dependencies:
+      tinyrainbow: 2.0.0
+
+  '@vitest/pretty-format@4.0.16':
+    dependencies:
+      tinyrainbow: 3.1.0
+
+  '@vitest/runner@4.0.16':
+    dependencies:
+      '@vitest/utils': 4.0.16
+      pathe: 2.0.3
+
+  '@vitest/snapshot@4.0.16':
+    dependencies:
+      '@vitest/pretty-format': 4.0.16
+      magic-string: 0.30.21
+      pathe: 2.0.3
+
+  '@vitest/spy@3.2.4':
+    dependencies:
+      tinyspy: 4.0.4
+
+  '@vitest/spy@4.0.16': {}
+
+  '@vitest/utils@3.2.4':
+    dependencies:
+      '@vitest/pretty-format': 3.2.4
+      loupe: 3.2.1
+      tinyrainbow: 2.0.0
+
+  '@vitest/utils@4.0.16':
+    dependencies:
+      '@vitest/pretty-format': 4.0.16
+      tinyrainbow: 3.1.0
+
+  acorn-jsx@5.3.2(acorn@7.4.1):
+    dependencies:
+      acorn: 7.4.1
+
+  acorn-jsx@5.3.2(acorn@8.16.0):
+    dependencies:
+      acorn: 8.16.0
+
+  acorn@7.4.1: {}
+
+  acorn@8.16.0: {}
+
+  ajv@6.15.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-json-stable-stringify: 2.1.0
+      json-schema-traverse: 0.4.1
+      uri-js: 4.4.1
+
+  ajv@8.20.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.2
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  ansi-escapes@7.3.0:
+    dependencies:
+      environment: 1.1.0
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@5.2.0: {}
+
+  ansi-styles@6.2.3: {}
+
+  any-promise@1.3.0: {}
+
+  apca-w3@0.1.9:
+    dependencies:
+      colorparsley: 0.1.8
+
+  apcach@0.6.4:
+    dependencies:
+      apca-w3: 0.1.9
+      culori: 3.3.0
+      wcag-contrast: 3.0.0
+
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
+  argparse@2.0.1: {}
+
+  args-tokenizer@0.3.0: {}
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
+  aria-query@5.3.0:
+    dependencies:
+      dequal: 2.0.3
+
+  aria-query@5.3.2: {}
+
+  array-buffer-byte-length@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      is-array-buffer: 3.0.5
+
+  array-ify@1.0.0: {}
+
+  array-includes@3.1.9:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-object-atoms: 1.1.2
+      get-intrinsic: 1.3.0
+      is-string: 1.1.1
+      math-intrinsics: 1.1.0
+
+  array.prototype.findlast@1.2.5:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      es-shim-unscopables: 1.1.0
+
+  array.prototype.findlastindex@1.2.6:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      es-shim-unscopables: 1.1.0
+
+  array.prototype.flat@1.3.3:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-shim-unscopables: 1.1.0
+
+  array.prototype.flatmap@1.3.3:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-shim-unscopables: 1.1.0
+
+  array.prototype.tosorted@1.1.4:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-shim-unscopables: 1.1.0
+
+  arraybuffer.prototype.slice@1.0.4:
+    dependencies:
+      array-buffer-byte-length: 1.0.2
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      is-array-buffer: 3.0.5
+
+  assertion-error@2.0.1: {}
+
+  ast-types-flow@0.0.8: {}
+
+  ast-types@0.16.1:
+    dependencies:
+      tslib: 2.8.1
+
+  astring@1.9.0: {}
+
+  async-function@1.0.0: {}
+
+  available-typed-arrays@1.0.7:
+    dependencies:
+      possible-typed-array-names: 1.1.0
+
+  axe-core@4.12.0: {}
+
+  axobject-query@4.1.0: {}
+
+  babel-plugin-react-compiler@1.0.0:
+    dependencies:
+      '@babel/types': 7.29.7
+
+  babel-plugin-react-compiler@19.1.0-rc.3:
+    dependencies:
+      '@babel/types': 7.29.7
+
+  bail@2.0.2: {}
+
+  balanced-match@1.0.2: {}
+
+  balanced-match@4.0.4: {}
+
+  base-x@3.0.11:
+    dependencies:
+      safe-buffer: 5.2.1
+
+  base64-js@0.0.8: {}
+
+  baseline-browser-mapping@2.10.34: {}
+
+  bippy@0.3.34(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      '@types/react-reconciler': 0.28.9(@types/react@19.2.14)
+      react: 19.2.6
+    transitivePeerDependencies:
+      - '@types/react'
+
+  boolbase@1.0.0: {}
+
+  brace-expansion@1.1.15:
+    dependencies:
+      balanced-match: 1.0.2
+      concat-map: 0.0.1
+
+  brace-expansion@2.1.1:
+    dependencies:
+      balanced-match: 1.0.2
+
+  brace-expansion@5.0.6:
+    dependencies:
+      balanced-match: 4.0.4
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  browserslist@4.28.2:
+    dependencies:
+      baseline-browser-mapping: 2.10.34
+      caniuse-lite: 1.0.30001797
+      electron-to-chromium: 1.5.368
+      node-releases: 2.0.47
+      update-browserslist-db: 1.2.3(browserslist@4.28.2)
+
+  buffer-from@1.1.2: {}
+
+  bumpp@11.0.1:
+    dependencies:
+      args-tokenizer: 0.3.0
+      cac: 7.0.0
+      jsonc-parser: 3.3.1
+      package-manager-detector: 1.6.0
+      semver: 7.8.2
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      unconfig: 7.5.0
+      yaml: 2.9.0
+
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
+  bundle-require@5.1.0(esbuild@0.27.7):
+    dependencies:
+      esbuild: 0.27.7
+      load-tsconfig: 0.2.5
+
+  cac@6.7.14: {}
+
+  cac@7.0.0: {}
+
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bind@1.0.9:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      get-intrinsic: 1.3.0
+      set-function-length: 1.2.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  calligraph@1.3.0(motion@12.23.26(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      motion: 12.23.26(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  callsites@3.1.0: {}
+
+  camelize@1.0.1: {}
+
+  caniuse-api@3.0.0:
+    dependencies:
+      browserslist: 4.28.2
+      caniuse-lite: 1.0.30001797
+      lodash.memoize: 4.1.2
+      lodash.uniq: 4.5.0
+
+  caniuse-lite@1.0.30001797: {}
+
+  ccount@2.0.1: {}
+
+  chai@5.3.3:
+    dependencies:
+      assertion-error: 2.0.1
+      check-error: 2.1.3
+      deep-eql: 5.0.2
+      loupe: 3.2.1
+      pathval: 2.0.1
+
+  chai@6.2.2: {}
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
+  check-error@2.1.3: {}
+
+  chokidar@4.0.3:
+    dependencies:
+      readdirp: 4.1.2
+
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
+
+  chownr@3.0.0: {}
+
+  chrome-trace-event@1.0.4: {}
+
+  class-variance-authority@0.7.1:
+    dependencies:
+      clsx: 2.1.1
+
+  clean-package@2.2.0:
+    dependencies:
+      dot-prop: 6.0.1
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-truncate@5.2.0:
+    dependencies:
+      slice-ansi: 8.0.0
+      string-width: 8.2.1
+
+  client-only@0.0.1: {}
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  clone@2.1.2: {}
+
+  clsx@2.1.1: {}
+
+  code-block-writer@13.0.3: {}
+
+  collapse-white-space@2.1.0: {}
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-convert@3.1.3:
+    dependencies:
+      color-name: 2.1.0
+
+  color-name@1.1.4: {}
+
+  color-name@2.1.0: {}
+
+  color2k@2.0.3: {}
+
+  colord@2.9.3: {}
+
+  colorette@2.0.20: {}
+
+  colorparsley@0.1.8: {}
+
+  comma-separated-tokens@2.0.3: {}
+
+  commander@12.1.0: {}
+
+  commander@14.0.3: {}
+
+  commander@4.1.1: {}
+
+  commander@7.2.0: {}
+
+  commondir@1.0.1: {}
+
+  compare-func@2.0.0:
+    dependencies:
+      array-ify: 1.0.0
+      dot-prop: 5.3.0
+
+  compute-scroll-into-view@3.1.1: {}
+
+  concat-map@0.0.1: {}
+
+  concat-with-sourcemaps@1.1.0:
+    dependencies:
+      source-map: 0.6.1
+
+  confbox@0.1.8: {}
+
+  consola@3.4.2: {}
+
+  conventional-changelog-angular@8.3.1:
+    dependencies:
+      compare-func: 2.0.0
+
+  conventional-changelog-conventionalcommits@7.0.2:
+    dependencies:
+      compare-func: 2.0.0
+
+  conventional-commits-parser@6.4.0:
+    dependencies:
+      '@simple-libs/stream-utils': 1.2.0
+      meow: 13.2.0
+
+  convert-source-map@2.0.0: {}
+
+  cosmiconfig-typescript-loader@6.3.0(@types/node@25.0.3)(cosmiconfig@9.0.1(typescript@5.9.3))(typescript@5.9.3):
+    dependencies:
+      '@types/node': 25.0.3
+      cosmiconfig: 9.0.1(typescript@5.9.3)
+      jiti: 2.6.1
+      typescript: 5.9.3
+
+  cosmiconfig@9.0.1(typescript@5.9.3):
+    dependencies:
+      env-paths: 2.2.1
+      import-fresh: 3.3.1
+      js-yaml: 4.2.0
+      parse-json: 5.2.0
+    optionalDependencies:
+      typescript: 5.9.3
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  css-background-parser@0.1.0: {}
+
+  css-box-shadow@1.0.0-3: {}
+
+  css-color-keywords@1.0.0: {}
+
+  css-declaration-sorter@6.4.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  css-declaration-sorter@7.4.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  css-gradient-parser@0.0.16: {}
+
+  css-select@4.3.0:
+    dependencies:
+      boolbase: 1.0.0
+      css-what: 6.2.2
+      domhandler: 4.3.1
+      domutils: 2.8.0
+      nth-check: 2.1.1
+
+  css-to-react-native@3.2.0:
+    dependencies:
+      camelize: 1.0.1
+      css-color-keywords: 1.0.0
+      postcss-value-parser: 4.2.0
+
+  css-tree@1.1.3:
+    dependencies:
+      mdn-data: 2.0.14
+      source-map: 0.6.1
+
+  css-what@6.2.2: {}
+
+  css.escape@1.5.1: {}
+
+  cssesc@3.0.0: {}
+
+  cssnano-preset-default@5.2.14(postcss@8.5.6):
+    dependencies:
+      css-declaration-sorter: 6.4.1(postcss@8.5.6)
+      cssnano-utils: 3.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-calc: 8.2.4(postcss@8.5.6)
+      postcss-colormin: 5.3.1(postcss@8.5.6)
+      postcss-convert-values: 5.1.3(postcss@8.5.6)
+      postcss-discard-comments: 5.1.2(postcss@8.5.6)
+      postcss-discard-duplicates: 5.1.0(postcss@8.5.6)
+      postcss-discard-empty: 5.1.1(postcss@8.5.6)
+      postcss-discard-overridden: 5.1.0(postcss@8.5.6)
+      postcss-merge-longhand: 5.1.7(postcss@8.5.6)
+      postcss-merge-rules: 5.1.4(postcss@8.5.6)
+      postcss-minify-font-values: 5.1.0(postcss@8.5.6)
+      postcss-minify-gradients: 5.1.1(postcss@8.5.6)
+      postcss-minify-params: 5.1.4(postcss@8.5.6)
+      postcss-minify-selectors: 5.2.1(postcss@8.5.6)
+      postcss-normalize-charset: 5.1.0(postcss@8.5.6)
+      postcss-normalize-display-values: 5.1.0(postcss@8.5.6)
+      postcss-normalize-positions: 5.1.1(postcss@8.5.6)
+      postcss-normalize-repeat-style: 5.1.1(postcss@8.5.6)
+      postcss-normalize-string: 5.1.0(postcss@8.5.6)
+      postcss-normalize-timing-functions: 5.1.0(postcss@8.5.6)
+      postcss-normalize-unicode: 5.1.1(postcss@8.5.6)
+      postcss-normalize-url: 5.1.0(postcss@8.5.6)
+      postcss-normalize-whitespace: 5.1.1(postcss@8.5.6)
+      postcss-ordered-values: 5.1.3(postcss@8.5.6)
+      postcss-reduce-initial: 5.1.2(postcss@8.5.6)
+      postcss-reduce-transforms: 5.1.0(postcss@8.5.6)
+      postcss-svgo: 5.1.0(postcss@8.5.6)
+      postcss-unique-selectors: 5.1.1(postcss@8.5.6)
+
+  cssnano-utils@3.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  cssnano@5.1.15(postcss@8.5.6):
+    dependencies:
+      cssnano-preset-default: 5.2.14(postcss@8.5.6)
+      lilconfig: 2.1.0
+      postcss: 8.5.6
+      yaml: 1.10.3
+
+  csso@4.2.0:
+    dependencies:
+      css-tree: 1.1.3
+
+  csstype@3.2.3: {}
+
+  culori@3.3.0: {}
+
+  culori@4.0.2: {}
+
+  damerau-levenshtein@1.0.8: {}
+
+  data-view-buffer@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  data-view-byte-length@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  data-view-byte-offset@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  debug@3.2.7:
+    dependencies:
+      ms: 2.1.3
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decimal.js@10.6.0: {}
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
+  deep-eql@5.0.2: {}
+
+  deep-is@0.1.4: {}
+
+  deepmerge@4.3.1: {}
+
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  define-data-property@1.1.4:
+    dependencies:
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  define-lazy-prop@3.0.0: {}
+
+  define-properties@1.2.1:
+    dependencies:
+      define-data-property: 1.1.4
+      has-property-descriptors: 1.0.2
+      object-keys: 1.1.1
+
+  defu@6.1.7: {}
+
+  dequal@2.0.3: {}
+
+  detect-libc@1.0.3: {}
+
+  detect-libc@2.1.2: {}
+
+  detect-node-es@1.1.0: {}
+
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
+  doctrine@2.1.0:
+    dependencies:
+      esutils: 2.0.3
+
+  doctrine@3.0.0:
+    dependencies:
+      esutils: 2.0.3
+
+  dom-accessibility-api@0.5.16: {}
+
+  dom-accessibility-api@0.6.3: {}
+
+  dom-helpers@5.2.1:
+    dependencies:
+      '@babel/runtime': 7.29.7
+      csstype: 3.2.3
+
+  dom-serializer@1.4.1:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+      entities: 2.2.0
+
+  domelementtype@2.3.0: {}
+
+  domhandler@4.3.1:
+    dependencies:
+      domelementtype: 2.3.0
+
+  domutils@2.8.0:
+    dependencies:
+      dom-serializer: 1.4.1
+      domelementtype: 2.3.0
+      domhandler: 4.3.1
+
+  dot-prop@5.3.0:
+    dependencies:
+      is-obj: 2.0.0
+
+  dot-prop@6.0.1:
+    dependencies:
+      is-obj: 2.0.0
+
+  dotenv-cli@11.0.0:
+    dependencies:
+      cross-spawn: 7.0.6
+      dotenv: 17.2.3
+      dotenv-expand: 12.0.3
+      minimist: 1.2.8
+
+  dotenv-expand@11.0.7:
+    dependencies:
+      dotenv: 16.6.1
+
+  dotenv-expand@12.0.3:
+    dependencies:
+      dotenv: 16.6.1
+
+  dotenv@16.6.1: {}
+
+  dotenv@17.2.3: {}
+
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  electron-to-chromium@1.5.368: {}
+
+  emoji-regex-xs@2.0.1: {}
+
+  emoji-regex@10.6.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  emoji-regex@9.2.2: {}
+
+  empathic@2.0.1: {}
+
+  enhanced-resolve@5.23.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
+  entities@2.2.0: {}
+
+  entities@6.0.1: {}
+
+  env-paths@2.2.1: {}
+
+  environment@1.1.0: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-abstract@1.24.2:
+    dependencies:
+      array-buffer-byte-length: 1.0.2
+      arraybuffer.prototype.slice: 1.0.4
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      data-view-buffer: 1.0.2
+      data-view-byte-length: 1.0.2
+      data-view-byte-offset: 1.0.1
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      es-set-tostringtag: 2.1.0
+      es-to-primitive: 1.3.0
+      function.prototype.name: 1.1.8
+      get-intrinsic: 1.3.0
+      get-proto: 1.0.1
+      get-symbol-description: 1.1.0
+      globalthis: 1.0.4
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+      has-proto: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.4
+      internal-slot: 1.1.0
+      is-array-buffer: 3.0.5
+      is-callable: 1.2.7
+      is-data-view: 1.0.2
+      is-negative-zero: 2.0.3
+      is-regex: 1.2.1
+      is-set: 2.0.3
+      is-shared-array-buffer: 1.0.4
+      is-string: 1.1.1
+      is-typed-array: 1.1.15
+      is-weakref: 1.1.1
+      math-intrinsics: 1.1.0
+      object-inspect: 1.13.4
+      object-keys: 1.1.1
+      object.assign: 4.1.7
+      own-keys: 1.0.1
+      regexp.prototype.flags: 1.5.4
+      safe-array-concat: 1.1.4
+      safe-push-apply: 1.0.0
+      safe-regex-test: 1.1.0
+      set-proto: 1.0.0
+      stop-iteration-iterator: 1.1.0
+      string.prototype.trim: 1.2.11
+      string.prototype.trimend: 1.0.10
+      string.prototype.trimstart: 1.0.8
+      typed-array-buffer: 1.0.3
+      typed-array-byte-length: 1.0.3
+      typed-array-byte-offset: 1.0.4
+      typed-array-length: 1.0.8
+      unbox-primitive: 1.1.0
+      which-typed-array: 1.1.22
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es-iterator-helpers@1.3.2:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-set-tostringtag: 2.1.0
+      function-bind: 1.1.2
+      get-intrinsic: 1.3.0
+      globalthis: 1.0.4
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+      has-proto: 1.2.0
+      has-symbols: 1.1.0
+      internal-slot: 1.1.0
+      iterator.prototype: 1.1.5
+      math-intrinsics: 1.1.0
+
+  es-module-lexer@1.7.0: {}
+
+  es-object-atoms@1.1.2:
+    dependencies:
+      es-errors: 1.3.0
+
+  es-set-tostringtag@2.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      has-tostringtag: 1.0.2
+      hasown: 2.0.4
+
+  es-shim-unscopables@1.1.0:
+    dependencies:
+      hasown: 2.0.4
+
+  es-to-primitive@1.3.0:
+    dependencies:
+      is-callable: 1.2.7
+      is-date-object: 1.1.0
+      is-symbol: 1.1.1
+
+  es-toolkit@1.47.0: {}
+
+  esast-util-from-estree@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      unist-util-position-from-estree: 2.0.0
+
+  esast-util-from-js@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      acorn: 8.16.0
+      esast-util-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  esbuild@0.25.12:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.25.12
+      '@esbuild/android-arm': 0.25.12
+      '@esbuild/android-arm64': 0.25.12
+      '@esbuild/android-x64': 0.25.12
+      '@esbuild/darwin-arm64': 0.25.12
+      '@esbuild/darwin-x64': 0.25.12
+      '@esbuild/freebsd-arm64': 0.25.12
+      '@esbuild/freebsd-x64': 0.25.12
+      '@esbuild/linux-arm': 0.25.12
+      '@esbuild/linux-arm64': 0.25.12
+      '@esbuild/linux-ia32': 0.25.12
+      '@esbuild/linux-loong64': 0.25.12
+      '@esbuild/linux-mips64el': 0.25.12
+      '@esbuild/linux-ppc64': 0.25.12
+      '@esbuild/linux-riscv64': 0.25.12
+      '@esbuild/linux-s390x': 0.25.12
+      '@esbuild/linux-x64': 0.25.12
+      '@esbuild/netbsd-arm64': 0.25.12
+      '@esbuild/netbsd-x64': 0.25.12
+      '@esbuild/openbsd-arm64': 0.25.12
+      '@esbuild/openbsd-x64': 0.25.12
+      '@esbuild/openharmony-arm64': 0.25.12
+      '@esbuild/sunos-x64': 0.25.12
+      '@esbuild/win32-arm64': 0.25.12
+      '@esbuild/win32-ia32': 0.25.12
+      '@esbuild/win32-x64': 0.25.12
+
+  esbuild@0.27.7:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.7
+      '@esbuild/android-arm': 0.27.7
+      '@esbuild/android-arm64': 0.27.7
+      '@esbuild/android-x64': 0.27.7
+      '@esbuild/darwin-arm64': 0.27.7
+      '@esbuild/darwin-x64': 0.27.7
+      '@esbuild/freebsd-arm64': 0.27.7
+      '@esbuild/freebsd-x64': 0.27.7
+      '@esbuild/linux-arm': 0.27.7
+      '@esbuild/linux-arm64': 0.27.7
+      '@esbuild/linux-ia32': 0.27.7
+      '@esbuild/linux-loong64': 0.27.7
+      '@esbuild/linux-mips64el': 0.27.7
+      '@esbuild/linux-ppc64': 0.27.7
+      '@esbuild/linux-riscv64': 0.27.7
+      '@esbuild/linux-s390x': 0.27.7
+      '@esbuild/linux-x64': 0.27.7
+      '@esbuild/netbsd-arm64': 0.27.7
+      '@esbuild/netbsd-x64': 0.27.7
+      '@esbuild/openbsd-arm64': 0.27.7
+      '@esbuild/openbsd-x64': 0.27.7
+      '@esbuild/openharmony-arm64': 0.27.7
+      '@esbuild/sunos-x64': 0.27.7
+      '@esbuild/win32-arm64': 0.27.7
+      '@esbuild/win32-ia32': 0.27.7
+      '@esbuild/win32-x64': 0.27.7
+
+  escalade@3.2.0: {}
+
+  escape-html@1.0.3: {}
+
+  escape-string-regexp@4.0.0: {}
+
+  escape-string-regexp@5.0.0: {}
+
+  eslint-config-next@16.1.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
+    dependencies:
+      '@next/eslint-plugin-next': 16.1.1
+      eslint: 9.39.2(jiti@2.6.1)
+      eslint-import-resolver-node: 0.3.10
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
+      globals: 16.4.0
+      typescript-eslint: 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@typescript-eslint/parser'
+      - eslint-import-resolver-webpack
+      - eslint-plugin-import-x
+      - supports-color
+
+  eslint-config-prettier@10.1.8(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+
+  eslint-import-resolver-node@0.3.10:
+    dependencies:
+      debug: 3.2.7
+      is-core-module: 2.16.2
+      resolve: 2.0.0-next.7
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      '@nolyfill/is-core-module': 1.0.39
+      debug: 4.4.3
+      eslint: 9.39.2(jiti@2.6.1)
+      get-tsconfig: 4.14.0
+      is-bun-module: 2.0.0
+      stable-hash: 0.0.5
+      tinyglobby: 0.2.17
+      unrs-resolver: 1.12.2
+    optionalDependencies:
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-module-utils@2.13.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      debug: 3.2.7
+    optionalDependencies:
+      '@typescript-eslint/parser': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
+      eslint-import-resolver-node: 0.3.10
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      '@rtsao/scc': 1.1.0
+      array-includes: 3.1.9
+      array.prototype.findlastindex: 1.2.6
+      array.prototype.flat: 1.3.3
+      array.prototype.flatmap: 1.3.3
+      debug: 3.2.7
+      doctrine: 2.1.0
+      eslint: 9.39.2(jiti@2.6.1)
+      eslint-import-resolver-node: 0.3.10
+      eslint-module-utils: 2.13.0(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      hasown: 2.0.4
+      is-core-module: 2.16.2
+      is-glob: 4.0.3
+      minimatch: 3.1.5
+      object.fromentries: 2.0.8
+      object.groupby: 1.0.3
+      object.values: 1.2.1
+      semver: 6.3.1
+      string.prototype.trimend: 1.0.10
+      tsconfig-paths: 3.15.0
+    optionalDependencies:
+      '@typescript-eslint/parser': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+    transitivePeerDependencies:
+      - eslint-import-resolver-typescript
+      - eslint-import-resolver-webpack
+      - supports-color
+
+  eslint-plugin-jsx-a11y@6.10.2(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      aria-query: 5.3.2
+      array-includes: 3.1.9
+      array.prototype.flatmap: 1.3.3
+      ast-types-flow: 0.0.8
+      axe-core: 4.12.0
+      axobject-query: 4.1.0
+      damerau-levenshtein: 1.0.8
+      emoji-regex: 9.2.2
+      eslint: 9.39.2(jiti@2.6.1)
+      hasown: 2.0.4
+      jsx-ast-utils: 3.3.5
+      language-tags: 1.0.9
+      minimatch: 3.1.5
+      object.fromentries: 2.0.8
+      safe-regex-test: 1.1.0
+      string.prototype.includes: 2.0.1
+
+  eslint-plugin-only-warn@1.1.0: {}
+
+  eslint-plugin-prettier@5.5.4(eslint-config-prettier@10.1.8(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))(prettier@3.7.4):
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+      prettier: 3.7.4
+      prettier-linter-helpers: 1.0.1
+      synckit: 0.11.13
+    optionalDependencies:
+      eslint-config-prettier: 10.1.8(eslint@9.39.2(jiti@2.6.1))
+
+  eslint-plugin-react-hooks@7.0.1(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/parser': 7.29.7
+      eslint: 9.39.2(jiti@2.6.1)
+      hermes-parser: 0.25.1
+      zod: 4.2.1
+      zod-validation-error: 4.0.2(zod@4.2.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-plugin-react-refresh@0.4.26(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+
+  eslint-plugin-react@7.37.5(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      array-includes: 3.1.9
+      array.prototype.findlast: 1.2.5
+      array.prototype.flatmap: 1.3.3
+      array.prototype.tosorted: 1.1.4
+      doctrine: 2.1.0
+      es-iterator-helpers: 1.3.2
+      eslint: 9.39.2(jiti@2.6.1)
+      estraverse: 5.3.0
+      hasown: 2.0.4
+      jsx-ast-utils: 3.3.5
+      minimatch: 3.1.5
+      object.entries: 1.1.9
+      object.fromentries: 2.0.8
+      object.values: 1.2.1
+      prop-types: 15.8.1
+      resolve: 2.0.0-next.7
+      semver: 6.3.1
+      string.prototype.matchall: 4.0.12
+      string.prototype.repeat: 1.0.0
+
+  eslint-plugin-sort-destructure-keys@2.0.0(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+      natural-compare-lite: 1.4.0
+
+  eslint-plugin-sort-keys-fix@1.1.2:
+    dependencies:
+      espree: 6.2.1
+      esutils: 2.0.3
+      natural-compare: 1.4.0
+      requireindex: 1.2.0
+
+  eslint-plugin-storybook@10.1.10(eslint@9.39.2(jiti@2.6.1))(storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/utils': 8.60.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
+      storybook: 10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+    transitivePeerDependencies:
+      - supports-color
+      - typescript
+
+  eslint-plugin-unused-imports@4.3.0(@typescript-eslint/eslint-plugin@8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.2(jiti@2.6.1)
+    optionalDependencies:
+      '@typescript-eslint/eslint-plugin': 8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+
+  eslint-scope@8.4.0:
+    dependencies:
+      esrecurse: 4.3.0
+      estraverse: 5.3.0
+
+  eslint-visitor-keys@1.3.0: {}
+
+  eslint-visitor-keys@3.4.3: {}
+
+  eslint-visitor-keys@4.2.1: {}
+
+  eslint-visitor-keys@5.0.1: {}
+
+  eslint@9.39.2(jiti@2.6.1):
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@2.6.1))
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.21.2
+      '@eslint/config-helpers': 0.4.2
+      '@eslint/core': 0.17.0
+      '@eslint/eslintrc': 3.3.3
+      '@eslint/js': 9.39.2
+      '@eslint/plugin-kit': 0.4.1
+      '@humanfs/node': 0.16.8
+      '@humanwhocodes/module-importer': 1.0.1
+      '@humanwhocodes/retry': 0.4.3
+      '@types/estree': 1.0.9
+      ajv: 6.15.0
+      chalk: 4.1.2
+      cross-spawn: 7.0.6
+      debug: 4.4.3
+      escape-string-regexp: 4.0.0
+      eslint-scope: 8.4.0
+      eslint-visitor-keys: 4.2.1
+      espree: 10.4.0
+      esquery: 1.7.0
+      esutils: 2.0.3
+      fast-deep-equal: 3.1.3
+      file-entry-cache: 8.0.0
+      find-up: 5.0.0
+      glob-parent: 6.0.2
+      ignore: 5.3.2
+      imurmurhash: 0.1.4
+      is-glob: 4.0.3
+      json-stable-stringify-without-jsonify: 1.0.1
+      lodash.merge: 4.6.2
+      minimatch: 3.1.5
+      natural-compare: 1.4.0
+      optionator: 0.9.4
+    optionalDependencies:
+      jiti: 2.6.1
+    transitivePeerDependencies:
+      - supports-color
+
+  esm@3.2.25: {}
+
+  espree@10.4.0:
+    dependencies:
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
+      eslint-visitor-keys: 4.2.1
+
+  espree@6.2.1:
+    dependencies:
+      acorn: 7.4.1
+      acorn-jsx: 5.3.2(acorn@7.4.1)
+      eslint-visitor-keys: 1.3.0
+
+  esprima@4.0.1: {}
+
+  esquery@1.7.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  esrecurse@4.3.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  estraverse@5.3.0: {}
+
+  estree-util-attach-comments@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  estree-util-build-jsx@3.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-walker: 3.0.3
+
+  estree-util-is-identifier-name@3.0.0: {}
+
+  estree-util-scope@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+
+  estree-util-to-js@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      astring: 1.9.0
+      source-map: 0.7.6
+
+  estree-util-value-to-estree@3.5.0:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  estree-util-visit@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/unist': 3.0.3
+
+  estree-walker@0.6.1: {}
+
+  estree-walker@2.0.2: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  esutils@2.0.3: {}
+
+  eventemitter3@4.0.7: {}
+
+  eventemitter3@5.0.4: {}
+
+  expect-type@1.3.0: {}
+
+  extend-shallow@2.0.1:
+    dependencies:
+      is-extendable: 0.1.1
+
+  extend@3.0.2: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-diff@1.3.0: {}
+
+  fast-glob@3.3.1:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fast-json-stable-stringify@2.1.0: {}
+
+  fast-levenshtein@2.0.6: {}
+
+  fast-uri@3.1.2: {}
+
+  fastq@1.20.1:
+    dependencies:
+      reusify: 1.1.0
+
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
+  feed@5.1.0:
+    dependencies:
+      xml-js: 1.6.11
+
+  fflate@0.7.4: {}
+
+  file-entry-cache@8.0.0:
+    dependencies:
+      flat-cache: 4.0.1
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  find-up@5.0.0:
+    dependencies:
+      locate-path: 6.0.0
+      path-exists: 4.0.0
+
+  fix-dts-default-cjs-exports@1.0.1:
+    dependencies:
+      magic-string: 0.30.21
+      mlly: 1.8.2
+      rollup: 4.54.0
+
+  flat-cache@4.0.1:
+    dependencies:
+      flatted: 3.4.2
+      keyv: 4.5.4
+
+  flatted@3.4.2: {}
+
+  for-each@0.3.5:
+    dependencies:
+      is-callable: 1.2.7
+
+  framer-motion@12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      motion-dom: 12.40.0
+      motion-utils: 12.39.0
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  fs-extra@11.3.3:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.1
+      universalify: 2.0.1
+
+  fsevents@2.3.2:
+    optional: true
+
+  fsevents@2.3.3:
+    optional: true
+
+  fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1):
+    dependencies:
+      '@orama/orama': 3.1.18
+      estree-util-value-to-estree: 3.5.0
+      github-slugger: 2.0.0
+      hast-util-to-estree: 3.1.3
+      hast-util-to-jsx-runtime: 2.3.6
+      js-yaml: 4.2.0
+      mdast-util-mdx: 3.0.0
+      mdast-util-to-markdown: 2.1.2
+      remark: 15.0.1
+      remark-gfm: 4.0.1
+      remark-rehype: 11.1.2
+      scroll-into-view-if-needed: 3.1.0
+      shiki: 3.20.0
+      tinyglobby: 0.2.17
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    optionalDependencies:
+      '@mdx-js/mdx': 3.1.1
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/react': 19.2.14
+      lucide-react: 0.562.0(react@19.2.6)
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      zod: 4.2.1
+    transitivePeerDependencies:
+      - supports-color
+
+  fumadocs-mdx@14.2.2(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)):
+    dependencies:
+      '@mdx-js/mdx': 3.1.1
+      '@standard-schema/spec': 1.1.0
+      chokidar: 5.0.0
+      esbuild: 0.27.7
+      estree-util-value-to-estree: 3.5.0
+      fumadocs-core: 16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1)
+      js-yaml: 4.2.0
+      mdast-util-to-markdown: 2.1.2
+      picocolors: 1.1.1
+      picomatch: 4.0.4
+      remark-mdx: 3.1.1
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      unified: 11.0.5
+      unist-util-remove-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      zod: 4.2.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  fumadocs-typescript@5.0.0(cdcaa0f702fde0940675ed572330cf20):
+    dependencies:
+      estree-util-value-to-estree: 3.5.0
+      fumadocs-core: 16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1)
+      hast-util-to-estree: 3.1.3
+      hast-util-to-jsx-runtime: 2.3.6
+      remark: 15.0.1
+      remark-rehype: 11.1.2
+      tinyglobby: 0.2.17
+      ts-morph: 27.0.2
+      typescript: 5.9.3
+      unist-util-visit: 5.1.0
+    optionalDependencies:
+      '@types/react': 19.2.14
+      fumadocs-ui: 16.9.0(@tailwindcss/oxide@4.3.0)(@types/mdx@2.0.13)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tailwindcss@4.3.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  fumadocs-ui@16.9.0(@tailwindcss/oxide@4.3.0)(@types/mdx@2.0.13)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(fumadocs-core@16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tailwindcss@4.3.0):
+    dependencies:
+      '@fumadocs/tailwind': 0.0.5(@tailwindcss/oxide@4.3.0)(tailwindcss@4.3.0)
+      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-popover': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.5(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      class-variance-authority: 0.7.1
+      fumadocs-core: 16.9.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(lucide-react@0.562.0(react@19.2.6))(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(zod@4.2.1)
+      lucide-react: 1.17.0(react@19.2.6)
+      motion: 12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+      rehype-raw: 7.0.0
+      scroll-into-view-if-needed: 3.1.0
+      shiki: 3.20.0
+      tailwind-merge: 3.6.0
+      unist-util-visit: 5.1.0
+    optionalDependencies:
+      '@types/mdx': 2.0.13
+      '@types/react': 19.2.14
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+    transitivePeerDependencies:
+      - '@emotion/is-prop-valid'
+      - '@tailwindcss/oxide'
+      - '@types/react-dom'
+      - tailwindcss
+
+  function-bind@1.1.2: {}
+
+  function.prototype.name@1.1.8:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      functions-have-names: 1.2.3
+      hasown: 2.0.4
+      is-callable: 1.2.7
+
+  functions-have-names@1.2.3: {}
+
+  generator-function@2.0.1: {}
+
+  generic-names@4.0.0:
+    dependencies:
+      loader-utils: 3.3.1
+
+  gensync@1.0.0-beta.2: {}
+
+  get-caller-file@2.0.5: {}
+
+  get-east-asian-width@1.6.0: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.4
+      math-intrinsics: 1.1.0
+
+  get-nonce@1.0.1: {}
+
+  get-port@4.2.0: {}
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.2
+
+  get-symbol-description@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+
+  get-tsconfig@4.14.0:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  git-raw-commits@5.0.1(conventional-commits-parser@6.4.0):
+    dependencies:
+      '@conventional-changelog/git-client': 2.7.0(conventional-commits-parser@6.4.0)
+      meow: 13.2.0
+    transitivePeerDependencies:
+      - conventional-commits-filter
+      - conventional-commits-parser
+
+  github-slugger@2.0.0: {}
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  glob-parent@6.0.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  glob@13.0.0:
+    dependencies:
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      path-scurry: 2.0.2
+
+  glob@13.0.6:
+    dependencies:
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      path-scurry: 2.0.2
+
+  global-directory@5.0.0:
+    dependencies:
+      ini: 6.0.0
+
+  globals@13.24.0:
+    dependencies:
+      type-fest: 0.20.2
+
+  globals@14.0.0: {}
+
+  globals@16.4.0: {}
+
+  globals@16.5.0: {}
+
+  globalthis@1.0.4:
+    dependencies:
+      define-properties: 1.2.1
+      gopd: 1.2.0
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  gray-matter@4.0.3:
+    dependencies:
+      js-yaml: 3.14.2
+      kind-of: 6.0.3
+      section-matter: 1.0.0
+      strip-bom-string: 1.0.0
+
+  has-bigints@1.1.0: {}
+
+  has-flag@4.0.0: {}
+
+  has-property-descriptors@1.0.2:
+    dependencies:
+      es-define-property: 1.0.1
+
+  has-proto@1.2.0:
+    dependencies:
+      dunder-proto: 1.0.1
+
+  has-symbols@1.1.0: {}
+
+  has-tostringtag@1.0.2:
+    dependencies:
+      has-symbols: 1.1.0
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  hast-util-from-parse5@8.0.3:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      hastscript: 9.0.1
+      property-information: 7.2.0
+      vfile: 6.0.3
+      vfile-location: 5.0.3
+      web-namespaces: 2.0.1
+
+  hast-util-parse-selector@4.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hast-util-raw@9.1.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      '@ungap/structured-clone': 1.3.1
+      hast-util-from-parse5: 8.0.3
+      hast-util-to-parse5: 8.0.1
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      parse5: 7.3.0
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
+
+  hast-util-to-estree@3.1.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-attach-comments: 3.0.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      zwitch: 2.0.4
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-to-html@9.0.5:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      comma-separated-tokens: 2.0.3
+      hast-util-whitespace: 3.0.0
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      stringify-entities: 4.0.4
+      zwitch: 2.0.4
+
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-to-parse5@8.0.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hastscript@9.0.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      hast-util-parse-selector: 4.0.0
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+
+  hermes-estree@0.25.1: {}
+
+  hermes-parser@0.25.1:
+    dependencies:
+      hermes-estree: 0.25.1
+
+  hex-rgb@4.3.0: {}
+
+  html-void-elements@3.0.0: {}
+
+  husky@9.1.7: {}
+
+  icss-replace-symbols@1.1.0: {}
+
+  icss-utils@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  ignore@5.3.2: {}
+
+  ignore@7.0.5: {}
+
+  import-cwd@3.0.0:
+    dependencies:
+      import-from: 3.0.0
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  import-from@3.0.0:
+    dependencies:
+      resolve-from: 5.0.0
+
+  import-meta-resolve@4.2.0: {}
+
+  imurmurhash@0.1.4: {}
+
+  indent-string@4.0.0: {}
+
+  ini@6.0.0: {}
+
+  inline-style-parser@0.2.7: {}
+
+  input-otp@1.4.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  internal-slot@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      hasown: 2.0.4
+      side-channel: 1.1.0
+
+  intl-messageformat@10.7.18:
+    dependencies:
+      '@formatjs/ecma402-abstract': 2.3.6
+      '@formatjs/fast-memoize': 2.2.7
+      '@formatjs/icu-messageformat-parser': 2.11.4
+      tslib: 2.8.1
+
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
+  is-array-buffer@3.0.5:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+
+  is-arrayish@0.2.1: {}
+
+  is-async-function@2.1.1:
+    dependencies:
+      async-function: 1.0.0
+      call-bound: 1.0.4
+      get-proto: 1.0.1
+      has-tostringtag: 1.0.2
+      safe-regex-test: 1.1.0
+
+  is-bigint@1.1.0:
+    dependencies:
+      has-bigints: 1.1.0
+
+  is-boolean-object@1.2.2:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-bun-module@2.0.0:
+    dependencies:
+      semver: 7.8.2
+
+  is-callable@1.2.7: {}
+
+  is-core-module@2.16.2:
+    dependencies:
+      hasown: 2.0.4
+
+  is-data-view@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+      is-typed-array: 1.1.15
+
+  is-date-object@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-decimal@2.0.1: {}
+
+  is-docker@3.0.0: {}
+
+  is-extendable@0.1.1: {}
+
+  is-extglob@2.1.1: {}
+
+  is-finalizationregistry@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-fullwidth-code-point@5.1.0:
+    dependencies:
+      get-east-asian-width: 1.6.0
+
+  is-generator-function@1.1.2:
+    dependencies:
+      call-bound: 1.0.4
+      generator-function: 2.0.1
+      get-proto: 1.0.1
+      has-tostringtag: 1.0.2
+      safe-regex-test: 1.1.0
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-hexadecimal@2.0.1: {}
+
+  is-inside-container@1.0.0:
+    dependencies:
+      is-docker: 3.0.0
+
+  is-map@2.0.3: {}
+
+  is-module@1.0.0: {}
+
+  is-negative-zero@2.0.3: {}
+
+  is-number-object@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-number@7.0.0: {}
+
+  is-obj@2.0.0: {}
+
+  is-plain-obj@4.1.0: {}
+
+  is-reference@1.2.1:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  is-regex@1.2.1:
+    dependencies:
+      call-bound: 1.0.4
+      gopd: 1.2.0
+      has-tostringtag: 1.0.2
+      hasown: 2.0.4
+
+  is-set@2.0.3: {}
+
+  is-shared-array-buffer@1.0.4:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-string@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-symbol@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-symbols: 1.1.0
+      safe-regex-test: 1.1.0
+
+  is-typed-array@1.1.15:
+    dependencies:
+      which-typed-array: 1.1.22
+
+  is-weakmap@2.0.2: {}
+
+  is-weakref@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-weakset@2.0.4:
+    dependencies:
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
+  isarray@2.0.5: {}
+
+  isexe@2.0.0: {}
+
+  iterator.prototype@1.1.5:
+    dependencies:
+      define-data-property: 1.1.4
+      es-object-atoms: 1.1.2
+      get-intrinsic: 1.3.0
+      get-proto: 1.0.1
+      has-symbols: 1.1.0
+      set-function-name: 2.0.2
+
+  jiti@2.6.1: {}
+
+  joycon@3.1.1: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@3.14.2:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
+  js-yaml@4.2.0:
+    dependencies:
+      argparse: 2.0.1
+
+  jsesc@3.1.0: {}
+
+  json-buffer@3.0.1: {}
+
+  json-parse-even-better-errors@2.3.1: {}
+
+  json-schema-traverse@0.4.1: {}
+
+  json-schema-traverse@1.0.0: {}
+
+  json-stable-stringify-without-jsonify@1.0.1: {}
+
+  json5@1.0.2:
+    dependencies:
+      minimist: 1.2.8
+
+  json5@2.2.3: {}
+
+  jsonc-parser@3.3.1: {}
+
+  jsonfile@6.2.1:
+    dependencies:
+      universalify: 2.0.1
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  jsx-ast-utils@3.3.5:
+    dependencies:
+      array-includes: 3.1.9
+      array.prototype.flat: 1.3.3
+      object.assign: 4.1.7
+      object.values: 1.2.1
+
+  keyv@4.5.4:
+    dependencies:
+      json-buffer: 3.0.1
+
+  kind-of@6.0.3: {}
+
+  kleur@4.1.5: {}
+
+  language-subtag-registry@0.3.23: {}
+
+  language-tags@1.0.9:
+    dependencies:
+      language-subtag-registry: 0.3.23
+
+  levn@0.4.1:
+    dependencies:
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  lilconfig@2.1.0: {}
+
+  lilconfig@3.1.3: {}
+
+  linebreak@1.1.0:
+    dependencies:
+      base64-js: 0.0.8
+      unicode-trie: 2.0.0
+
+  lines-and-columns@1.2.4: {}
+
+  lint-staged@16.2.7:
+    dependencies:
+      commander: 14.0.3
+      listr2: 9.0.5
+      micromatch: 4.0.8
+      nano-spawn: 2.1.0
+      pidtree: 0.6.0
+      string-argv: 0.3.2
+      yaml: 2.9.0
+
+  listr2@9.0.5:
+    dependencies:
+      cli-truncate: 5.2.0
+      colorette: 2.0.20
+      eventemitter3: 5.0.4
+      log-update: 6.1.0
+      rfdc: 1.4.1
+      wrap-ansi: 9.0.2
+
+  lmdb@2.8.5:
+    dependencies:
+      msgpackr: 1.11.13
+      node-addon-api: 6.1.0
+      node-gyp-build-optional-packages: 5.1.1
+      ordered-binary: 1.6.1
+      weak-lru-cache: 1.2.2
+    optionalDependencies:
+      '@lmdb/lmdb-darwin-arm64': 2.8.5
+      '@lmdb/lmdb-darwin-x64': 2.8.5
+      '@lmdb/lmdb-linux-arm': 2.8.5
+      '@lmdb/lmdb-linux-arm64': 2.8.5
+      '@lmdb/lmdb-linux-x64': 2.8.5
+      '@lmdb/lmdb-win32-x64': 2.8.5
+
+  load-tsconfig@0.2.5: {}
+
+  loader-utils@3.3.1: {}
+
+  locate-path@6.0.0:
+    dependencies:
+      p-locate: 5.0.0
+
+  lodash.camelcase@4.3.0: {}
+
+  lodash.debounce@4.0.8: {}
+
+  lodash.memoize@4.1.2: {}
+
+  lodash.merge@4.6.2: {}
+
+  lodash.uniq@4.5.0: {}
+
+  log-update@6.1.0:
+    dependencies:
+      ansi-escapes: 7.3.0
+      cli-cursor: 5.0.0
+      slice-ansi: 7.1.2
+      strip-ansi: 7.2.0
+      wrap-ansi: 9.0.2
+
+  longest-streak@3.1.0: {}
+
+  loose-envify@1.4.0:
+    dependencies:
+      js-tokens: 4.0.0
+
+  loupe@3.2.1: {}
+
+  lru-cache@11.5.1: {}
+
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  lucide-react@0.562.0(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  lucide-react@1.17.0(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  lz-string@1.5.0: {}
+
+  m3-ripple@1.1.3(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  markdown-extensions@2.0.0: {}
+
+  markdown-table@3.0.4: {}
+
+  math-intrinsics@1.1.0: {}
+
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx@3.0.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.1
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
+  mdn-data@2.0.14: {}
+
+  meow@13.2.0: {}
+
+  merge2@1.4.1: {}
+
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-expression@3.0.1:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-jsx@3.0.2:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-extension-mdx-md@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-extension-mdxjs@3.0.0:
+    dependencies:
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
+      micromark-extension-mdx-expression: 3.0.1
+      micromark-extension-mdx-jsx: 3.0.2
+      micromark-extension-mdx-md: 2.0.0
+      micromark-extension-mdxjs-esm: 3.0.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-mdx-expression@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-events-to-acorn@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  mimic-function@5.0.1: {}
+
+  min-indent@1.0.1: {}
+
+  minimatch@10.2.5:
+    dependencies:
+      brace-expansion: 5.0.6
+
+  minimatch@3.1.5:
+    dependencies:
+      brace-expansion: 1.1.15
+
+  minimatch@9.0.9:
+    dependencies:
+      brace-expansion: 2.1.1
+
+  minimist@1.2.8: {}
+
+  minipass@7.1.3: {}
+
+  minizlib@3.1.0:
+    dependencies:
+      minipass: 7.1.3
+
+  mlly@1.8.2:
+    dependencies:
+      acorn: 8.16.0
+      pathe: 2.0.3
+      pkg-types: 1.3.1
+      ufo: 1.6.4
+
+  motion-dom@12.40.0:
+    dependencies:
+      motion-utils: 12.39.0
+
+  motion-utils@12.39.0: {}
+
+  motion@12.23.26(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      framer-motion: 12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  motion@12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      framer-motion: 12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  mri@1.2.0: {}
+
+  ms@2.1.3: {}
+
+  msgpackr-extract@3.0.4:
+    dependencies:
+      node-gyp-build-optional-packages: 5.2.2
+    optionalDependencies:
+      '@msgpackr-extract/msgpackr-extract-darwin-arm64': 3.0.4
+      '@msgpackr-extract/msgpackr-extract-darwin-x64': 3.0.4
+      '@msgpackr-extract/msgpackr-extract-linux-arm': 3.0.4
+      '@msgpackr-extract/msgpackr-extract-linux-arm64': 3.0.4
+      '@msgpackr-extract/msgpackr-extract-linux-x64': 3.0.4
+      '@msgpackr-extract/msgpackr-extract-win32-x64': 3.0.4
+    optional: true
+
+  msgpackr@1.11.13:
+    optionalDependencies:
+      msgpackr-extract: 3.0.4
+
+  mz@2.7.0:
+    dependencies:
+      any-promise: 1.3.0
+      object-assign: 4.1.1
+      thenify-all: 1.6.0
+
+  nano-spawn@2.1.0: {}
+
+  nanoid@3.3.12: {}
+
+  napi-postinstall@0.3.4: {}
+
+  natural-compare-lite@1.4.0: {}
+
+  natural-compare@1.4.0: {}
+
+  next-mdx-remote@6.0.0(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@mdx-js/mdx': 3.1.1
+      '@mdx-js/react': 3.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      unist-util-remove: 4.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      vfile-matter: 5.0.1
+    transitivePeerDependencies:
+      - '@types/react'
+      - supports-color
+
+  next-sitemap@4.2.3(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)):
+    dependencies:
+      '@corex/deepmerge': 4.0.43
+      '@next/env': 13.5.11
+      fast-glob: 3.3.3
+      minimist: 1.2.8
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
+  next-themes@0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@next/env': 16.2.6
+      '@swc/helpers': 0.5.15
+      baseline-browser-mapping: 2.10.34
+      caniuse-lite: 1.0.30001797
+      postcss: 8.4.31
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-jsx: 5.1.6(@babel/core@7.28.5)(react@19.2.6)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.2.6
+      '@next/swc-darwin-x64': 16.2.6
+      '@next/swc-linux-arm64-gnu': 16.2.6
+      '@next/swc-linux-arm64-musl': 16.2.6
+      '@next/swc-linux-x64-gnu': 16.2.6
+      '@next/swc-linux-x64-musl': 16.2.6
+      '@next/swc-win32-arm64-msvc': 16.2.6
+      '@next/swc-win32-x64-msvc': 16.2.6
+      '@opentelemetry/api': 1.9.1
+      babel-plugin-react-compiler: 1.0.0
+      sharp: 0.34.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - babel-plugin-macros
+
+  node-addon-api@6.1.0: {}
+
+  node-addon-api@7.1.1: {}
+
+  node-exports-info@1.6.0:
+    dependencies:
+      array.prototype.flatmap: 1.3.3
+      es-errors: 1.3.0
+      object.entries: 1.1.9
+      semver: 6.3.1
+
+  node-gyp-build-optional-packages@5.1.1:
+    dependencies:
+      detect-libc: 2.1.2
+
+  node-gyp-build-optional-packages@5.2.2:
+    dependencies:
+      detect-libc: 2.1.2
+    optional: true
+
+  node-releases@2.0.47: {}
+
+  normalize-url@6.1.0: {}
+
+  nth-check@2.1.1:
+    dependencies:
+      boolbase: 1.0.0
+
+  nullthrows@1.1.1: {}
+
+  nuqs@2.8.6(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@standard-schema/spec': 1.0.0
+      react: 19.2.6
+    optionalDependencies:
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
+  object-assign@4.1.1: {}
+
+  object-inspect@1.13.4: {}
+
+  object-keys@1.1.1: {}
+
+  object.assign@4.1.7:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.2
+      has-symbols: 1.1.0
+      object-keys: 1.1.1
+
+  object.entries@1.1.9:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.2
+
+  object.fromentries@2.0.8:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-object-atoms: 1.1.2
+
+  object.groupby@1.0.3:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+
+  object.values@1.2.1:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.2
+
+  obug@2.1.2: {}
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  oniguruma-parser@0.12.2: {}
+
+  oniguruma-to-es@4.3.6:
+    dependencies:
+      oniguruma-parser: 0.12.2
+      regex: 6.1.0
+      regex-recursion: 6.0.2
+
+  open@10.2.0:
+    dependencies:
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-inside-container: 1.0.0
+      wsl-utils: 0.1.0
+
+  optionator@0.9.4:
+    dependencies:
+      deep-is: 0.1.4
+      fast-levenshtein: 2.0.6
+      levn: 0.4.1
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+      word-wrap: 1.2.5
+
+  ordered-binary@1.6.1: {}
+
+  own-keys@1.0.1:
+    dependencies:
+      get-intrinsic: 1.3.0
+      object-keys: 1.1.1
+      safe-push-apply: 1.0.0
+
+  p-finally@1.0.0: {}
+
+  p-limit@3.1.0:
+    dependencies:
+      yocto-queue: 0.1.0
+
+  p-locate@5.0.0:
+    dependencies:
+      p-limit: 3.1.0
+
+  p-queue@6.6.2:
+    dependencies:
+      eventemitter3: 4.0.7
+      p-timeout: 3.2.0
+
+  p-timeout@3.2.0:
+    dependencies:
+      p-finally: 1.0.0
+
+  package-json-from-dist@1.0.1: {}
+
+  package-manager-detector@1.6.0: {}
+
+  pako@0.2.9: {}
+
+  parcel@2.16.3(@swc/helpers@0.5.23):
+    dependencies:
+      '@parcel/config-default': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)
+      '@parcel/core': 2.16.3(@swc/helpers@0.5.23)
+      '@parcel/diagnostic': 2.16.3
+      '@parcel/events': 2.16.3
+      '@parcel/feature-flags': 2.16.3
+      '@parcel/fs': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/logger': 2.16.3
+      '@parcel/package-manager': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))(@swc/helpers@0.5.23)
+      '@parcel/reporter-cli': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/reporter-dev-server': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/reporter-tracer': 2.16.3(@parcel/core@2.16.3(@swc/helpers@0.5.23))
+      '@parcel/utils': 2.16.3
+      chalk: 4.1.2
+      commander: 12.1.0
+      get-port: 4.2.0
+    transitivePeerDependencies:
+      - '@swc/helpers'
+      - napi-wasm
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-css-color@0.2.1:
+    dependencies:
+      color-name: 1.1.4
+      hex-rgb: 4.3.0
+
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
+  parse5@7.3.0:
+    dependencies:
+      entities: 6.0.1
+
+  path-browserify@1.0.1: {}
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-parse@1.0.7: {}
+
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.5.1
+      minipass: 7.1.3
+
+  pathe@2.0.3: {}
+
+  pathval@2.0.1: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@2.3.2: {}
+
+  picomatch@4.0.4: {}
+
+  pidtree@0.6.0: {}
+
+  pify@5.0.0: {}
+
+  pirates@4.0.7: {}
+
+  pkg-types@1.3.1:
+    dependencies:
+      confbox: 0.1.8
+      mlly: 1.8.2
+      pathe: 2.0.3
+
+  playwright-core@1.60.0: {}
+
+  playwright@1.60.0:
+    dependencies:
+      playwright-core: 1.60.0
+    optionalDependencies:
+      fsevents: 2.3.2
+
+  possible-typed-array-names@1.1.0: {}
+
+  postcss-calc@8.2.4(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-selector-parser: 6.1.2
+      postcss-value-parser: 4.2.0
+
+  postcss-colormin@5.3.1(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      caniuse-api: 3.0.0
+      colord: 2.9.3
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-convert-values@5.1.3(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-discard-comments@5.1.2(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-discard-duplicates@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-discard-empty@5.1.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-discard-overridden@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-less@6.0.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-load-config@3.1.4(postcss@8.5.6):
+    dependencies:
+      lilconfig: 2.1.0
+      yaml: 1.10.3
+    optionalDependencies:
+      postcss: 8.5.6
+
+  postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      lilconfig: 3.1.3
+    optionalDependencies:
+      jiti: 2.6.1
+      postcss: 8.5.6
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  postcss-merge-longhand@5.1.7(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+      stylehacks: 5.1.1(postcss@8.5.6)
+
+  postcss-merge-rules@5.1.4(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      caniuse-api: 3.0.0
+      cssnano-utils: 3.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-selector-parser: 6.1.2
+
+  postcss-minify-font-values@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-minify-gradients@5.1.1(postcss@8.5.6):
+    dependencies:
+      colord: 2.9.3
+      cssnano-utils: 3.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-minify-params@5.1.4(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      cssnano-utils: 3.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-minify-selectors@5.2.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-selector-parser: 6.1.2
+
+  postcss-modules-extract-imports@3.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-modules-local-by-default@4.2.0(postcss@8.5.6):
+    dependencies:
+      icss-utils: 5.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-selector-parser: 7.1.1
+      postcss-value-parser: 4.2.0
+
+  postcss-modules-scope@3.2.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-selector-parser: 7.1.1
+
+  postcss-modules-values@4.0.0(postcss@8.5.6):
+    dependencies:
+      icss-utils: 5.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+
+  postcss-modules@4.3.1(postcss@8.5.6):
+    dependencies:
+      generic-names: 4.0.0
+      icss-replace-symbols: 1.1.0
+      lodash.camelcase: 4.3.0
+      postcss: 8.5.6
+      postcss-modules-extract-imports: 3.1.0(postcss@8.5.6)
+      postcss-modules-local-by-default: 4.2.0(postcss@8.5.6)
+      postcss-modules-scope: 3.2.1(postcss@8.5.6)
+      postcss-modules-values: 4.0.0(postcss@8.5.6)
+      string-hash: 1.1.3
+
+  postcss-normalize-charset@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-normalize-display-values@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-positions@5.1.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-repeat-style@5.1.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-string@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-timing-functions@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-unicode@5.1.1(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-url@5.1.0(postcss@8.5.6):
+    dependencies:
+      normalize-url: 6.1.0
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-normalize-whitespace@5.1.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-ordered-values@5.1.3(postcss@8.5.6):
+    dependencies:
+      cssnano-utils: 3.1.0(postcss@8.5.6)
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-reduce-initial@5.1.2(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      caniuse-api: 3.0.0
+      postcss: 8.5.6
+
+  postcss-reduce-transforms@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+
+  postcss-scss@4.0.9(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+
+  postcss-selector-parser@6.0.10:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss-selector-parser@6.1.2:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss-selector-parser@7.1.1:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss-svgo@5.1.0(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-value-parser: 4.2.0
+      svgo: 2.8.2
+
+  postcss-unique-selectors@5.1.1(postcss@8.5.6):
+    dependencies:
+      postcss: 8.5.6
+      postcss-selector-parser: 6.1.2
+
+  postcss-value-parser@4.2.0: {}
+
+  postcss@8.4.31:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  postcss@8.5.6:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  posthog-node@5.21.0:
+    dependencies:
+      '@posthog/core': 1.9.1
+
+  preact@10.29.2: {}
+
+  prelude-ls@1.2.1: {}
+
+  prettier-linter-helpers@1.0.1:
+    dependencies:
+      fast-diff: 1.3.0
+
+  prettier-plugin-css-order@2.1.2(postcss@8.5.6)(prettier@3.7.4):
+    dependencies:
+      css-declaration-sorter: 7.4.0(postcss@8.5.6)
+      postcss-less: 6.0.0(postcss@8.5.6)
+      postcss-scss: 4.0.9(postcss@8.5.6)
+      prettier: 3.7.4
+    transitivePeerDependencies:
+      - postcss
+
+  prettier-plugin-tailwindcss@0.7.2(prettier-plugin-css-order@2.1.2(postcss@8.5.6)(prettier@3.7.4))(prettier@3.7.4):
+    dependencies:
+      prettier: 3.7.4
+    optionalDependencies:
+      prettier-plugin-css-order: 2.1.2(postcss@8.5.6)(prettier@3.7.4)
+
+  prettier@3.7.4: {}
+
+  pretty-format@27.5.1:
+    dependencies:
+      ansi-regex: 5.0.1
+      ansi-styles: 5.2.0
+      react-is: 17.0.2
+
+  promise.series@0.2.0: {}
+
+  prop-types@15.8.1:
+    dependencies:
+      loose-envify: 1.4.0
+      object-assign: 4.1.1
+      react-is: 16.13.1
+
+  property-information@7.2.0: {}
+
+  punycode@2.3.1: {}
+
+  quansync@1.0.0: {}
+
+  queue-microtask@1.2.3: {}
+
+  react-aria-components@1.18.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      client-only: 0.0.1
+      react: 19.2.6
+      react-aria: 3.49.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.47.0(react@19.2.6)
+
+  react-aria-components@1.19.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      client-only: 0.0.1
+      react: 19.2.6
+      react-aria: 3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+
+  react-aria@3.49.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@internationalized/number': 3.6.7
+      '@internationalized/string': 3.2.9
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      aria-hidden: 1.2.6
+      clsx: 2.1.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.47.0(react@19.2.6)
+      use-sync-external-store: 1.6.0(react@19.2.6)
+
+  react-aria@3.50.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@internationalized/number': 3.6.7
+      '@internationalized/string': 3.2.9
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      aria-hidden: 1.2.6
+      clsx: 2.1.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-stately: 3.48.0(react@19.2.6)
+      use-sync-external-store: 1.6.0(react@19.2.6)
+
+  react-docgen-typescript@2.4.0(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  react-docgen@8.0.3:
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@types/babel__core': 7.20.5
+      '@types/babel__traverse': 7.28.0
+      '@types/doctrine': 0.0.9
+      '@types/resolve': 1.20.6
+      doctrine: 3.0.0
+      resolve: 1.22.12
+      strip-indent: 4.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  react-dom@19.2.6(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      scheduler: 0.27.0
+
+  react-is@16.13.1: {}
+
+  react-is@17.0.2: {}
+
+  react-refresh@0.16.0: {}
+
+  react-refresh@0.18.0: {}
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.6)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-remove-scroll@2.7.2(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.14)(react@19.2.6)
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.6)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.14)(react@19.2.6)
+      use-sidecar: 1.1.3(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-scan@0.4.3(@types/react@19.2.14)(next@16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(rollup@4.54.0):
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/generator': 7.29.7
+      '@babel/types': 7.29.7
+      '@clack/core': 0.3.5
+      '@clack/prompts': 0.8.2
+      '@pivanov/utils': 0.0.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@preact/signals': 1.3.4(preact@10.29.2)
+      '@rollup/pluginutils': 5.4.0(rollup@4.54.0)
+      '@types/node': 20.19.42
+      bippy: 0.3.34(@types/react@19.2.14)(react@19.2.6)
+      esbuild: 0.25.12
+      estree-walker: 3.0.3
+      kleur: 4.1.5
+      mri: 1.2.0
+      playwright: 1.60.0
+      preact: 10.29.2
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      tsx: 4.21.0
+    optionalDependencies:
+      next: 16.2.6(@babel/core@7.28.5)(@opentelemetry/api@1.9.1)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      unplugin: 2.1.0
+    transitivePeerDependencies:
+      - '@types/react'
+      - rollup
+      - supports-color
+
+  react-stately@3.47.0(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@internationalized/number': 3.6.7
+      '@internationalized/string': 3.2.9
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+
+  react-stately@3.48.0(react@19.2.6):
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@internationalized/number': 3.6.7
+      '@internationalized/string': 3.2.9
+      '@react-types/shared': 3.36.0(react@19.2.6)
+      '@swc/helpers': 0.5.23
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+
+  react-style-singleton@2.2.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-transition-group@4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@babel/runtime': 7.29.7
+      dom-helpers: 5.2.1
+      loose-envify: 1.4.0
+      prop-types: 15.8.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  react@19.2.6: {}
+
+  readdirp@4.1.2: {}
+
+  readdirp@5.0.0: {}
+
+  recast@0.23.11:
+    dependencies:
+      ast-types: 0.16.1
+      esprima: 4.0.1
+      source-map: 0.6.1
+      tiny-invariant: 1.3.3
+      tslib: 2.8.1
+
+  recma-build-jsx@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-util-build-jsx: 3.0.1
+      vfile: 6.0.3
+
+  recma-jsx@1.0.1(acorn@8.16.0):
+    dependencies:
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
+      estree-util-to-js: 2.0.0
+      recma-parse: 1.0.0
+      recma-stringify: 1.0.0
+      unified: 11.0.5
+
+  recma-parse@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      esast-util-from-js: 2.0.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  recma-stringify@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-util-to-js: 2.0.0
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  redent@3.0.0:
+    dependencies:
+      indent-string: 4.0.0
+      strip-indent: 3.0.0
+
+  reflect.getprototypeof@1.0.10:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      get-intrinsic: 1.3.0
+      get-proto: 1.0.1
+      which-builtin-type: 1.2.1
+
+  regenerator-runtime@0.14.1: {}
+
+  regex-recursion@6.0.2:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  regex-utilities@2.3.0: {}
+
+  regex@6.1.0:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  regexp.prototype.flags@1.5.4:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-errors: 1.3.0
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      set-function-name: 2.0.2
+
+  rehype-raw@7.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      hast-util-raw: 9.1.0
+      vfile: 6.0.3
+
+  rehype-recma@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.4
+      hast-util-to-estree: 3.1.3
+    transitivePeerDependencies:
+      - supports-color
+
+  relative-luminance@2.0.1:
+    dependencies:
+      esm: 3.2.25
+
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-mdx@3.1.1:
+    dependencies:
+      mdast-util-mdx: 3.0.0
+      micromark-extension-mdxjs: 3.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
+  remark@15.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  requireindex@1.2.0: {}
+
+  resolve-from@4.0.0: {}
+
+  resolve-from@5.0.0: {}
+
+  resolve-pkg-maps@1.0.0: {}
+
+  resolve@1.22.12:
+    dependencies:
+      es-errors: 1.3.0
+      is-core-module: 2.16.2
+      path-parse: 1.0.7
+      supports-preserve-symlinks-flag: 1.0.0
+
+  resolve@2.0.0-next.7:
+    dependencies:
+      es-errors: 1.3.0
+      is-core-module: 2.16.2
+      node-exports-info: 1.6.0
+      object-keys: 1.1.1
+      path-parse: 1.0.7
+      supports-preserve-symlinks-flag: 1.0.0
+
+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
+  reusify@1.1.0: {}
+
+  rfdc@1.4.1: {}
+
+  rimraf@6.1.2:
+    dependencies:
+      glob: 13.0.0
+      package-json-from-dist: 1.0.1
+
+  rollup-plugin-peer-deps-external@2.2.4(rollup@4.54.0):
+    dependencies:
+      rollup: 4.54.0
+
+  rollup-plugin-postcss@4.0.2(postcss@8.5.6):
+    dependencies:
+      chalk: 4.1.2
+      concat-with-sourcemaps: 1.1.0
+      cssnano: 5.1.15(postcss@8.5.6)
+      import-cwd: 3.0.0
+      p-queue: 6.6.2
+      pify: 5.0.0
+      postcss: 8.5.6
+      postcss-load-config: 3.1.4(postcss@8.5.6)
+      postcss-modules: 4.3.1(postcss@8.5.6)
+      promise.series: 0.2.0
+      resolve: 1.22.12
+      rollup-pluginutils: 2.8.2
+      safe-identifier: 0.4.2
+      style-inject: 0.3.0
+    transitivePeerDependencies:
+      - ts-node
+
+  rollup-pluginutils@2.8.2:
+    dependencies:
+      estree-walker: 0.6.1
+
+  rollup@4.54.0:
+    dependencies:
+      '@types/estree': 1.0.8
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.54.0
+      '@rollup/rollup-android-arm64': 4.54.0
+      '@rollup/rollup-darwin-arm64': 4.54.0
+      '@rollup/rollup-darwin-x64': 4.54.0
+      '@rollup/rollup-freebsd-arm64': 4.54.0
+      '@rollup/rollup-freebsd-x64': 4.54.0
+      '@rollup/rollup-linux-arm-gnueabihf': 4.54.0
+      '@rollup/rollup-linux-arm-musleabihf': 4.54.0
+      '@rollup/rollup-linux-arm64-gnu': 4.54.0
+      '@rollup/rollup-linux-arm64-musl': 4.54.0
+      '@rollup/rollup-linux-loong64-gnu': 4.54.0
+      '@rollup/rollup-linux-ppc64-gnu': 4.54.0
+      '@rollup/rollup-linux-riscv64-gnu': 4.54.0
+      '@rollup/rollup-linux-riscv64-musl': 4.54.0
+      '@rollup/rollup-linux-s390x-gnu': 4.54.0
+      '@rollup/rollup-linux-x64-gnu': 4.54.0
+      '@rollup/rollup-linux-x64-musl': 4.54.0
+      '@rollup/rollup-openharmony-arm64': 4.54.0
+      '@rollup/rollup-win32-arm64-msvc': 4.54.0
+      '@rollup/rollup-win32-ia32-msvc': 4.54.0
+      '@rollup/rollup-win32-x64-gnu': 4.54.0
+      '@rollup/rollup-win32-x64-msvc': 4.54.0
+      fsevents: 2.3.3
+
+  run-applescript@7.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  safe-array-concat@1.1.4:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+      has-symbols: 1.1.0
+      isarray: 2.0.5
+
+  safe-buffer@5.2.1: {}
+
+  safe-identifier@0.4.2: {}
+
+  safe-push-apply@1.0.0:
+    dependencies:
+      es-errors: 1.3.0
+      isarray: 2.0.5
+
+  safe-regex-test@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-regex: 1.2.1
+
+  satori@0.16.0:
+    dependencies:
+      '@shuding/opentype.js': 1.4.0-beta.0
+      css-background-parser: 0.1.0
+      css-box-shadow: 1.0.0-3
+      css-gradient-parser: 0.0.16
+      css-to-react-native: 3.2.0
+      emoji-regex-xs: 2.0.1
+      escape-html: 1.0.3
+      linebreak: 1.1.0
+      parse-css-color: 0.2.1
+      postcss-value-parser: 4.2.0
+      yoga-layout: 3.2.1
+
+  sax@1.6.0: {}
+
+  scheduler@0.27.0: {}
+
+  scroll-into-view-if-needed@3.1.0:
+    dependencies:
+      compute-scroll-into-view: 3.1.1
+
+  section-matter@1.0.0:
+    dependencies:
+      extend-shallow: 2.0.1
+      kind-of: 6.0.3
+
+  semver@6.3.1: {}
+
+  semver@7.8.2: {}
+
+  set-function-length@1.2.2:
+    dependencies:
+      define-data-property: 1.1.4
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+      get-intrinsic: 1.3.0
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+
+  set-function-name@2.0.2:
+    dependencies:
+      define-data-property: 1.1.4
+      es-errors: 1.3.0
+      functions-have-names: 1.2.3
+      has-property-descriptors: 1.0.2
+
+  set-proto@1.0.0:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.1.0
+      detect-libc: 2.1.2
+      semver: 7.8.2
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+    optional: true
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  shiki@3.20.0:
+    dependencies:
+      '@shikijs/core': 3.20.0
+      '@shikijs/engine-javascript': 3.20.0
+      '@shikijs/engine-oniguruma': 3.20.0
+      '@shikijs/langs': 3.20.0
+      '@shikijs/themes': 3.20.0
+      '@shikijs/types': 3.20.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  side-channel-list@1.0.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.1
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
+  siginfo@2.0.0: {}
+
+  signal-exit@4.1.0: {}
+
+  sisteransi@1.0.5: {}
+
+  slice-ansi@7.1.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  slice-ansi@8.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  source-map-js@1.2.1: {}
+
+  source-map-support@0.5.21:
+    dependencies:
+      buffer-from: 1.1.2
+      source-map: 0.6.1
+
+  source-map@0.6.1: {}
+
+  source-map@0.7.6: {}
+
+  space-separated-tokens@2.0.2: {}
+
+  sprintf-js@1.0.3: {}
+
+  stable-hash@0.0.5: {}
+
+  stable@0.1.8: {}
+
+  stackback@0.0.2: {}
+
+  std-env@3.10.0: {}
+
+  stop-iteration-iterator@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      internal-slot: 1.1.0
+
+  storybook@10.1.10(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@storybook/global': 5.0.0
+      '@storybook/icons': 2.0.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@testing-library/jest-dom': 6.9.1
+      '@testing-library/user-event': 14.6.1(@testing-library/dom@10.4.1)
+      '@vitest/expect': 3.2.4
+      '@vitest/spy': 3.2.4
+      esbuild: 0.27.7
+      open: 10.2.0
+      recast: 0.23.11
+      semver: 7.8.2
+      use-sync-external-store: 1.6.0(react@19.2.6)
+      ws: 8.21.0
+    optionalDependencies:
+      prettier: 3.7.4
+    transitivePeerDependencies:
+      - '@testing-library/dom'
+      - bufferutil
+      - react
+      - react-dom
+      - utf-8-validate
+
+  string-argv@0.3.2: {}
+
+  string-hash@1.1.3: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.6.0
+      strip-ansi: 7.2.0
+
+  string-width@8.2.1:
+    dependencies:
+      get-east-asian-width: 1.6.0
+      strip-ansi: 7.2.0
+
+  string.prototype.codepointat@0.2.1: {}
+
+  string.prototype.includes@2.0.1:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+
+  string.prototype.matchall@4.0.12:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      get-intrinsic: 1.3.0
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      internal-slot: 1.1.0
+      regexp.prototype.flags: 1.5.4
+      set-function-name: 2.0.2
+      side-channel: 1.1.0
+
+  string.prototype.repeat@1.0.0:
+    dependencies:
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+
+  string.prototype.trim@1.2.11:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-data-property: 1.1.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-object-atoms: 1.1.2
+      has-property-descriptors: 1.0.2
+      safe-regex-test: 1.1.0
+
+  string.prototype.trimend@1.0.10:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.2
+
+  string.prototype.trimstart@1.0.8:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.2
+
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-bom-string@1.0.0: {}
+
+  strip-bom@3.0.0: {}
+
+  strip-indent@3.0.0:
+    dependencies:
+      min-indent: 1.0.1
+
+  strip-indent@4.1.1: {}
+
+  strip-json-comments@3.1.1: {}
+
+  style-inject@0.3.0: {}
+
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
+  styled-jsx@5.1.6(@babel/core@7.28.5)(react@19.2.6):
+    dependencies:
+      client-only: 0.0.1
+      react: 19.2.6
+    optionalDependencies:
+      '@babel/core': 7.28.5
+
+  stylehacks@5.1.1(postcss@8.5.6):
+    dependencies:
+      browserslist: 4.28.2
+      postcss: 8.5.6
+      postcss-selector-parser: 6.1.2
+
+  sucrase@3.35.1:
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      commander: 4.1.1
+      lines-and-columns: 1.2.4
+      mz: 2.7.0
+      pirates: 4.0.7
+      tinyglobby: 0.2.17
+      ts-interface-checker: 0.1.13
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  supports-preserve-symlinks-flag@1.0.0: {}
+
+  svgo@2.8.2:
+    dependencies:
+      commander: 7.2.0
+      css-select: 4.3.0
+      css-tree: 1.1.3
+      csso: 4.2.0
+      picocolors: 1.1.1
+      sax: 1.6.0
+      stable: 0.1.8
+
+  synckit@0.11.13:
+    dependencies:
+      '@pkgr/core': 0.3.6
+
+  tailwind-merge@3.4.0: {}
+
+  tailwind-merge@3.6.0: {}
+
+  tailwind-variants@3.2.2(tailwind-merge@3.4.0)(tailwindcss@4.1.18):
+    dependencies:
+      tailwindcss: 4.1.18
+    optionalDependencies:
+      tailwind-merge: 3.4.0
+
+  tailwind-variants@3.2.2(tailwind-merge@3.4.0)(tailwindcss@4.3.0):
+    dependencies:
+      tailwindcss: 4.3.0
+    optionalDependencies:
+      tailwind-merge: 3.4.0
+
+  tailwind-variants@3.2.2(tailwind-merge@3.6.0)(tailwindcss@4.3.0):
+    dependencies:
+      tailwindcss: 4.3.0
+    optionalDependencies:
+      tailwind-merge: 3.6.0
+
+  tailwindcss@4.1.18: {}
+
+  tailwindcss@4.3.0: {}
+
+  tapable@2.3.3: {}
+
+  tar@7.5.7:
+    dependencies:
+      '@isaacs/fs-minipass': 4.0.1
+      chownr: 3.0.0
+      minipass: 7.1.3
+      minizlib: 3.1.0
+      yallist: 5.0.0
+
+  term-size@2.2.1: {}
+
+  thenify-all@1.6.0:
+    dependencies:
+      thenify: 3.3.1
+
+  thenify@3.3.1:
+    dependencies:
+      any-promise: 1.3.0
+
+  tiny-inflate@1.0.3: {}
+
+  tiny-invariant@1.3.3: {}
+
+  tinybench@2.9.0: {}
+
+  tinyexec@0.3.2: {}
+
+  tinyexec@1.2.4: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinyrainbow@2.0.0: {}
+
+  tinyrainbow@3.1.0: {}
+
+  tinyspy@4.0.4: {}
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  tree-kill@1.2.2: {}
+
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
+  ts-api-utils@2.5.0(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  ts-dedent@2.2.0: {}
+
+  ts-interface-checker@0.1.13: {}
+
+  ts-morph@27.0.2:
+    dependencies:
+      '@ts-morph/common': 0.28.1
+      code-block-writer: 13.0.3
+
+  tsconfig-paths@3.15.0:
+    dependencies:
+      '@types/json5': 0.0.29
+      json5: 1.0.2
+      minimist: 1.2.8
+      strip-bom: 3.0.0
+
+  tsconfig-paths@4.2.0:
+    dependencies:
+      json5: 2.2.3
+      minimist: 1.2.8
+      strip-bom: 3.0.0
+
+  tslib@2.8.1: {}
+
+  tsup@8.5.1(@swc/core@1.15.40(@swc/helpers@0.5.23))(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0):
+    dependencies:
+      bundle-require: 5.1.0(esbuild@0.27.7)
+      cac: 6.7.14
+      chokidar: 4.0.3
+      consola: 3.4.2
+      debug: 4.4.3
+      esbuild: 0.27.7
+      fix-dts-default-cjs-exports: 1.0.1
+      joycon: 3.1.1
+      picocolors: 1.1.1
+      postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0)
+      resolve-from: 5.0.0
+      rollup: 4.54.0
+      source-map: 0.7.6
+      sucrase: 3.35.1
+      tinyexec: 0.3.2
+      tinyglobby: 0.2.17
+      tree-kill: 1.2.2
+    optionalDependencies:
+      '@swc/core': 1.15.40(@swc/helpers@0.5.23)
+      postcss: 8.5.6
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - jiti
+      - supports-color
+      - tsx
+      - yaml
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.7
+      get-tsconfig: 4.14.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  turbo-darwin-64@2.7.2:
+    optional: true
+
+  turbo-darwin-arm64@2.7.2:
+    optional: true
+
+  turbo-linux-64@2.7.2:
+    optional: true
+
+  turbo-linux-arm64@2.7.2:
+    optional: true
+
+  turbo-windows-64@2.7.2:
+    optional: true
+
+  turbo-windows-arm64@2.7.2:
+    optional: true
+
+  turbo@2.7.2:
+    optionalDependencies:
+      turbo-darwin-64: 2.7.2
+      turbo-darwin-arm64: 2.7.2
+      turbo-linux-64: 2.7.2
+      turbo-linux-arm64: 2.7.2
+      turbo-windows-64: 2.7.2
+      turbo-windows-arm64: 2.7.2
+
+  tw-animate-css@1.4.0: {}
+
+  type-check@0.4.0:
+    dependencies:
+      prelude-ls: 1.2.1
+
+  type-fest@0.20.2: {}
+
+  typed-array-buffer@1.0.3:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-typed-array: 1.1.15
+
+  typed-array-byte-length@1.0.3:
+    dependencies:
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      has-proto: 1.2.0
+      is-typed-array: 1.1.15
+
+  typed-array-byte-offset@1.0.4:
+    dependencies:
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      has-proto: 1.2.0
+      is-typed-array: 1.1.15
+      reflect.getprototypeof: 1.0.10
+
+  typed-array-length@1.0.8:
+    dependencies:
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      is-typed-array: 1.1.15
+      possible-typed-array-names: 1.1.0
+      reflect.getprototypeof: 1.0.10
+
+  typescript-eslint@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.50.1(@typescript-eslint/parser@8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/typescript-estree': 8.50.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.50.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.8.3: {}
+
+  typescript@5.9.3: {}
+
+  ufo@1.6.4: {}
+
+  unbox-primitive@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      has-bigints: 1.1.0
+      has-symbols: 1.1.0
+      which-boxed-primitive: 1.1.1
+
+  unconfig-core@7.5.0:
+    dependencies:
+      '@quansync/fs': 1.0.0
+      quansync: 1.0.0
+
+  unconfig@7.5.0:
+    dependencies:
+      '@quansync/fs': 1.0.0
+      defu: 6.1.7
+      jiti: 2.6.1
+      quansync: 1.0.0
+      unconfig-core: 7.5.0
+
+  undici-types@6.21.0: {}
+
+  undici-types@7.16.0: {}
+
+  unicode-trie@2.0.0:
+    dependencies:
+      pako: 0.2.9
+      tiny-inflate: 1.0.3
+
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position-from-estree@2.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-remove-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-visit: 5.1.0
+
+  unist-util-remove@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  universalify@2.0.1: {}
+
+  unplugin@2.1.0:
+    dependencies:
+      acorn: 8.16.0
+      webpack-virtual-modules: 0.6.2
+    optional: true
+
+  unplugin@2.3.11:
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      acorn: 8.16.0
+      picomatch: 4.0.4
+      webpack-virtual-modules: 0.6.2
+
+  unrs-resolver@1.12.2:
+    dependencies:
+      napi-postinstall: 0.3.4
+    optionalDependencies:
+      '@unrs/resolver-binding-android-arm-eabi': 1.12.2
+      '@unrs/resolver-binding-android-arm64': 1.12.2
+      '@unrs/resolver-binding-darwin-arm64': 1.12.2
+      '@unrs/resolver-binding-darwin-x64': 1.12.2
+      '@unrs/resolver-binding-freebsd-x64': 1.12.2
+      '@unrs/resolver-binding-linux-arm-gnueabihf': 1.12.2
+      '@unrs/resolver-binding-linux-arm-musleabihf': 1.12.2
+      '@unrs/resolver-binding-linux-arm64-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-arm64-musl': 1.12.2
+      '@unrs/resolver-binding-linux-loong64-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-loong64-musl': 1.12.2
+      '@unrs/resolver-binding-linux-ppc64-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-riscv64-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-riscv64-musl': 1.12.2
+      '@unrs/resolver-binding-linux-s390x-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-x64-gnu': 1.12.2
+      '@unrs/resolver-binding-linux-x64-musl': 1.12.2
+      '@unrs/resolver-binding-openharmony-arm64': 1.12.2
+      '@unrs/resolver-binding-wasm32-wasi': 1.12.2
+      '@unrs/resolver-binding-win32-arm64-msvc': 1.12.2
+      '@unrs/resolver-binding-win32-ia32-msvc': 1.12.2
+      '@unrs/resolver-binding-win32-x64-msvc': 1.12.2
+
+  update-browserslist-db@1.2.3(browserslist@4.28.2):
+    dependencies:
+      browserslist: 4.28.2
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  uri-js@4.4.1:
+    dependencies:
+      punycode: 2.3.1
+
+  use-callback-ref@1.3.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sidecar@1.1.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sync-external-store@1.6.0(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  usehooks-ts@3.1.1(react@19.2.6):
+    dependencies:
+      lodash.debounce: 4.0.8
+      react: 19.2.6
+
+  util-deprecate@1.0.2: {}
+
+  utility-types@3.11.0: {}
+
+  vfile-location@5.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile: 6.0.3
+
+  vfile-matter@5.0.1:
+    dependencies:
+      vfile: 6.0.3
+      yaml: 2.9.0
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
+  vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.27.7
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.6
+      rollup: 4.54.0
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 25.0.3
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vitest@4.0.16(@opentelemetry/api@1.9.1)(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@vitest/expect': 4.0.16
+      '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/pretty-format': 4.0.16
+      '@vitest/runner': 4.0.16
+      '@vitest/snapshot': 4.0.16
+      '@vitest/spy': 4.0.16
+      '@vitest/utils': 4.0.16
+      es-module-lexer: 1.7.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.2
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      tinyrainbow: 3.1.0
+      vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@opentelemetry/api': 1.9.1
+      '@types/node': 25.0.3
+    transitivePeerDependencies:
+      - jiti
+      - less
+      - lightningcss
+      - msw
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - terser
+      - tsx
+      - yaml
+
+  wcag-contrast@3.0.0:
+    dependencies:
+      relative-luminance: 2.0.1
+
+  weak-lru-cache@1.2.2: {}
+
+  web-namespaces@2.0.1: {}
+
+  webpack-virtual-modules@0.6.2: {}
+
+  which-boxed-primitive@1.1.1:
+    dependencies:
+      is-bigint: 1.1.0
+      is-boolean-object: 1.2.2
+      is-number-object: 1.1.1
+      is-string: 1.1.1
+      is-symbol: 1.1.1
+
+  which-builtin-type@1.2.1:
+    dependencies:
+      call-bound: 1.0.4
+      function.prototype.name: 1.1.8
+      has-tostringtag: 1.0.2
+      is-async-function: 2.1.1
+      is-date-object: 1.1.0
+      is-finalizationregistry: 1.1.1
+      is-generator-function: 1.1.2
+      is-regex: 1.2.1
+      is-weakref: 1.1.1
+      isarray: 2.0.5
+      which-boxed-primitive: 1.1.1
+      which-collection: 1.0.2
+      which-typed-array: 1.1.22
+
+  which-collection@1.0.2:
+    dependencies:
+      is-map: 2.0.3
+      is-set: 2.0.3
+      is-weakmap: 2.0.2
+      is-weakset: 2.0.4
+
+  which-typed-array@1.1.22:
+    dependencies:
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      for-each: 0.3.5
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-tostringtag: 1.0.2
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  word-wrap@1.2.5: {}
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrap-ansi@9.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  ws@8.21.0: {}
+
+  wsl-utils@0.1.0:
+    dependencies:
+      is-wsl: 3.1.1
+
+  xml-js@1.6.11:
+    dependencies:
+      sax: 1.6.0
+
+  y18n@5.0.8: {}
+
+  yallist@3.1.1: {}
+
+  yallist@5.0.0: {}
+
+  yaml@1.10.3: {}
+
+  yaml@2.9.0: {}
+
+  yargs-parser@21.1.1: {}
+
+  yargs@17.7.2:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  yocto-queue@0.1.0: {}
+
+  yoga-layout@3.2.1: {}
+
+  zod-validation-error@4.0.2(zod@4.2.1):
+    dependencies:
+      zod: 4.2.1
+
+  zod@4.2.1: {}
+
+  zwitch@2.0.4: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..a57910b
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,3 @@
+packages:
+  - "apps/**/**"
+  - "packages/**/**"
diff --git a/prettier.config.mjs b/prettier.config.mjs
new file mode 100644
index 0000000..0849e10
--- /dev/null
+++ b/prettier.config.mjs
@@ -0,0 +1,22 @@
+import path from "path";
+
+import preset from "@heroui/standard/prettier/base.mjs";
+
+/** @type {import("prettier").Config} */
+const config = {
+  ...preset,
+  overrides: [
+    {
+      files: "./packages/styles/utilities/motions.css",
+      options: {
+        printWidth: 50,
+      },
+    },
+  ],
+  plugins: ["prettier-plugin-tailwindcss"],
+  tailwindAttributes: ["className", "classNames"],
+  tailwindFunctions: ["tv", "clsx", "cn"],
+  tailwindStylesheet: path.resolve(import.meta.dirname, "./packages/styles/index.css"),
+};
+
+export default config;
diff --git a/prompts/README.md b/prompts/README.md
new file mode 100644
index 0000000..64ca7d4
--- /dev/null
+++ b/prompts/README.md
@@ -0,0 +1,42 @@
+# HeroUI v3 — AI Integration Prompt Packs
+
+System prompts that teach AI code-generation tools to produce correct, idiomatic HeroUI v3 code.
+
+## What's in this directory
+
+| File | Purpose |
+|------|---------|
+| `heroui-system-prompt.md` | Universal prompt — works with any LLM or AI coding tool (Claude, ChatGPT, Cursor, Copilot, etc.) |
+| `v0-heroui.md` | Tailored for [v0.dev](https://v0.dev) — emphasizes Next.js App Router, RSC patterns, and Tailwind v4 |
+| `bolt-heroui.md` | Tailored for [bolt.new](https://bolt.new) / StackBlitz — includes full Vite setup and runnable single-file examples |
+
+These prompts also work well with **Lovable**, **Replit Agent**, **Windsurf**, and similar AI-powered code generation platforms.
+
+## How to use
+
+### v0.dev
+
+Paste the contents of `v0-heroui.md` into v0's system instructions or prepend it to your prompt.
+
+### bolt.new / StackBlitz
+
+Paste the contents of `bolt-heroui.md` at the start of your prompt when creating a new project. It includes the full Vite + Tailwind v4 setup so bolt can scaffold the project correctly.
+
+### Cursor / Claude / ChatGPT / Copilot
+
+Use `heroui-system-prompt.md` as a custom instruction, system prompt, or `.cursorrules` file. It gives the AI a complete reference of HeroUI v3 components and patterns.
+
+### Any other tool
+
+The universal `heroui-system-prompt.md` works with any tool that accepts system-level instructions.
+
+## Richer integrations
+
+For deeper integration beyond system prompts:
+
+- **MCP Server** — The HeroUI MCP server provides real-time component docs, source code, and theme tokens to AI agents. See the [`@heroui/mcp`](https://www.npmjs.com/package/@heroui/mcp) package.
+- **llms.txt** — Full-context documentation following the llms.txt standard, available at [heroui.com/llms.txt](https://heroui.com/llms.txt).
+
+## Contributing
+
+When updating these prompts, verify that the component names, APIs, and import patterns match the actual v3 source code in this repo. Run a quick check against the component docs in `apps/docs/content/docs/react/components/` to catch any drift.
diff --git a/prompts/bolt-heroui.md b/prompts/bolt-heroui.md
new file mode 100644
index 0000000..b250b8e
--- /dev/null
+++ b/prompts/bolt-heroui.md
@@ -0,0 +1,407 @@
+# HeroUI v3 — Prompt for bolt.new / StackBlitz
+
+You are an expert frontend React developer using **HeroUI v3** (`@heroui/react`) with Vite and Tailwind CSS v4. You generate complete, runnable single-file components that work in StackBlitz.
+
+## Project Setup (Vite + React + Tailwind v4)
+
+### package.json dependencies
+
+```json
+{
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@heroui/react": "latest"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "vite": "^6.0.0",
+    "@vitejs/plugin-react": "^4.0.0"
+  }
+}
+```
+
+### vite.config.ts
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+### src/index.css (Tailwind v4 — CSS-based config)
+
+```css
+@import "tailwindcss";
+@import "@heroui/react/styles.css";
+```
+
+### src/main.tsx
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+### index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>HeroUI App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+No Provider wrapper is needed — just import components and use them.
+
+---
+
+## Import Pattern
+
+```tsx
+import { Button, Card, Input, Modal, Table } from "@heroui/react";
+```
+
+All components come from `@heroui/react`. Sub-components use dot notation (e.g. `Card.Header`, `Modal.Dialog`).
+
+## Key Components
+
+### Button
+
+```tsx
+<Button variant="primary" size="md" onPress={() => {}}>Save</Button>
+<Button variant="outline">Cancel</Button>
+<Button variant="danger">Delete</Button>
+<Button isIconOnly aria-label="Close"><XIcon /></Button>
+```
+
+Variants: `primary`, `secondary`, `tertiary`, `outline`, `ghost`, `danger`.
+Sizes: `sm`, `md`, `lg`. Use `onPress` (not `onClick`).
+
+### Card
+
+```tsx
+<Card>
+  <Card.Header>
+    <Card.Title>Title</Card.Title>
+    <Card.Description>Subtitle</Card.Description>
+  </Card.Header>
+  <Card.Content>Body content</Card.Content>
+  <Card.Footer>
+    <Button variant="primary">Action</Button>
+  </Card.Footer>
+</Card>
+```
+
+### TextField (labeled input with validation)
+
+```tsx
+<TextField>
+  <Label>Email</Label>
+  <Input type="email" placeholder="you@example.com" />
+  <Description>We'll never share your email.</Description>
+  <FieldError />
+</TextField>
+```
+
+### Select
+
+```tsx
+<Select>
+  <Label>Country</Label>
+  <Select.Trigger>
+    <Select.Value placeholder="Choose..." />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      <ListBox.Item id="us">United States</ListBox.Item>
+      <ListBox.Item id="uk">United Kingdom</ListBox.Item>
+    </ListBox>
+  </Select.Popover>
+</Select>
+```
+
+### Checkbox / RadioGroup / Switch
+
+```tsx
+<Checkbox>
+  <Checkbox.Content>
+    <Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
+    Accept terms
+  </Checkbox.Content>
+</Checkbox>
+
+<RadioGroup>
+  <Label>Plan</Label>
+  <Radio value="free">
+    <Radio.Content>
+      <Radio.Control><Radio.Indicator /></Radio.Control>
+      Free
+    </Radio.Content>
+  </Radio>
+  <Radio value="pro">
+    <Radio.Content>
+      <Radio.Control><Radio.Indicator /></Radio.Control>
+      Pro
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+
+<Switch>
+  <Switch.Content>
+    <Switch.Control><Switch.Thumb /></Switch.Control>
+    Dark mode
+  </Switch.Content>
+</Switch>
+```
+
+### Table
+
+```tsx
+<Table>
+  <Table.ScrollContainer>
+    <Table.Content aria-label="Users">
+      <Table.Header>
+        <Table.Column isRowHeader>Name</Table.Column>
+        <Table.Column>Role</Table.Column>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Jane Cooper</Table.Cell>
+          <Table.Cell>Developer</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+### Tabs
+
+```tsx
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Sections">
+      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="settings">Settings<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+### Modal
+
+```tsx
+<Modal>
+  <Button>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.CloseTrigger />
+        <Modal.Header><Modal.Heading>Title</Modal.Heading></Modal.Header>
+        <Modal.Body><p>Content</p></Modal.Body>
+        <Modal.Footer>
+          <Button slot="close" variant="ghost">Cancel</Button>
+          <Button variant="primary">Confirm</Button>
+        </Modal.Footer>
+      </Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+### Drawer
+
+```tsx
+<Drawer>
+  <Button>Open Drawer</Button>
+  <Drawer.Backdrop>
+    <Drawer.Content>
+      <Drawer.Dialog>
+        <Drawer.CloseTrigger />
+        <Drawer.Header><Drawer.Heading>Panel</Drawer.Heading></Drawer.Header>
+        <Drawer.Body>Drawer content</Drawer.Body>
+        <Drawer.Footer><Button slot="close">Done</Button></Drawer.Footer>
+      </Drawer.Dialog>
+    </Drawer.Content>
+  </Drawer.Backdrop>
+</Drawer>
+```
+
+### Dropdown
+
+```tsx
+<Dropdown>
+  <Dropdown.Trigger><Button>Actions</Button></Dropdown.Trigger>
+  <Dropdown.Popover>
+    <Dropdown.Menu aria-label="Actions">
+      <Dropdown.Item id="edit"><Label>Edit</Label></Dropdown.Item>
+      <Dropdown.Item id="delete"><Label>Delete</Label></Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### Other Components
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Done</Alert.Title>
+    <Alert.Description>Changes saved.</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Spinner />
+
+<Skeleton className="h-4 w-48 rounded" />
+
+<Chip>Active</Chip>
+
+<Avatar>
+  <Avatar.Image src="/photo.jpg" alt="User" />
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar>
+
+<Badge.Anchor>
+  <Avatar><Avatar.Fallback>AB</Avatar.Fallback></Avatar>
+  <Badge color="danger">3</Badge>
+</Badge.Anchor>
+
+<Tooltip>
+  <Tooltip.Trigger><Button>Hover</Button></Tooltip.Trigger>
+  <Tooltip.Content>Tooltip text</Tooltip.Content>
+</Tooltip>
+
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+</Breadcrumbs>
+
+<Link href="/about">About<Link.Icon /></Link>
+
+<Separator />
+```
+
+### Toast (requires provider in main.tsx)
+
+```tsx
+// Add to App or main layout:
+<Toast.Provider />
+
+// Trigger from any component:
+import { toast } from "@heroui/react";
+toast("Saved!");
+toast.success("Done");
+toast.error("Failed");
+```
+
+### ProgressBar
+
+```tsx
+<ProgressBar value={60}>
+  <Label>Loading</Label>
+  <ProgressBar.Output />
+  <ProgressBar.Track><ProgressBar.Fill /></ProgressBar.Track>
+</ProgressBar>
+```
+
+---
+
+## Complete Single-File Example (src/App.tsx)
+
+```tsx
+import {
+  Button,
+  Card,
+  TextField,
+  Label,
+  Input,
+  Description,
+  Toast,
+  toast,
+} from "@heroui/react";
+
+export default function App() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-gray-50 p-8">
+      <Toast.Provider />
+      <Card className="w-full max-w-md">
+        <Card.Header>
+          <Card.Title>Sign Up</Card.Title>
+          <Card.Description>Create your account to get started.</Card.Description>
+        </Card.Header>
+        <Card.Content className="flex flex-col gap-4">
+          <TextField>
+            <Label>Full Name</Label>
+            <Input placeholder="Jane Doe" />
+          </TextField>
+          <TextField>
+            <Label>Email</Label>
+            <Input type="email" placeholder="jane@example.com" />
+            <Description>We'll never share your email.</Description>
+          </TextField>
+        </Card.Content>
+        <Card.Footer>
+          <Button
+            variant="primary"
+            fullWidth
+            onPress={() => toast.success("Account created!")}
+          >
+            Create Account
+          </Button>
+        </Card.Footer>
+      </Card>
+    </div>
+  );
+}
+```
+
+---
+
+## Styling
+
+HeroUI works with Tailwind CSS v4 utilities via `className`:
+
+```tsx
+<Button className="rounded-full px-8">Pill Button</Button>
+<Card className="border border-blue-200 shadow-xl">...</Card>
+```
+
+---
+
+## Rules — Do Not Break These
+
+1. **Never** wrap in a HeroUI Provider — not needed in v3.
+2. **Never** import from `@nextui-org/*` — that is the old v2 library.
+3. **Never** use Tailwind v3 config (`tailwind.config.js`). Use Tailwind CSS v4 with `@import "tailwindcss"` in CSS.
+4. **Always** use dot notation: `Card.Header` not `CardHeader`.
+5. **Always** use `onPress` on Button, not `onClick`.
+6. **Always** add `aria-label` to icon-only buttons and to `Table.Content`.
+7. **Always** import `@heroui/react/styles.css` in your main CSS file.
+8. **Always** use Vite with `@tailwindcss/vite` plugin and `@vitejs/plugin-react`.
diff --git a/prompts/heroui-system-prompt.md b/prompts/heroui-system-prompt.md
new file mode 100644
index 0000000..620418b
--- /dev/null
+++ b/prompts/heroui-system-prompt.md
@@ -0,0 +1,295 @@
+# HeroUI v3 — System Prompt for AI Code Generation
+
+You generate React code using **HeroUI v3**, a component library built on React Aria with Tailwind CSS v4.
+
+## Setup
+
+```bash
+npm install @heroui/react
+```
+
+No Provider or context wrapper is needed — just import and use.
+
+## Imports
+
+```tsx
+import { Button, Card, Input, Modal } from "@heroui/react";
+```
+
+Per-component: `import { Button } from "@heroui/button"`.
+
+## Core Concepts
+
+- **Compound components** — dot notation: `Card.Header`, `Modal.Dialog`, `Table.Row`.
+- **Tailwind CSS v4** — style via `className`. Standard Tailwind v4 utilities work.
+- **React Aria** — use `onPress` on Button (not `onClick`). Accessibility is built in.
+---
+
+## Components
+
+### Button
+
+```tsx
+<Button variant="primary" size="md" onPress={() => {}}>Save</Button>
+<Button variant="outline">Cancel</Button>
+<Button variant="danger">Delete</Button>
+<Button isIconOnly aria-label="Close"><XIcon /></Button>
+<Button isPending>Saving...</Button>
+```
+
+Variants: `primary` | `secondary` | `tertiary` | `outline` | `ghost` | `danger`. Sizes: `sm` | `md` | `lg`.
+
+### Card
+
+```tsx
+<Card>
+  <Card.Header>
+    <Card.Title>Title</Card.Title>
+    <Card.Description>Subtitle</Card.Description>
+  </Card.Header>
+  <Card.Content><p>Body</p></Card.Content>
+  <Card.Footer><Button variant="primary">Action</Button></Card.Footer>
+</Card>
+```
+
+Variants: `transparent` | `default` | `secondary` | `tertiary`.
+
+### TextField + Input
+
+```tsx
+<TextField>
+  <Label>Email</Label>
+  <Input type="email" placeholder="you@example.com" />
+  <Description>We'll never share your email.</Description>
+  <FieldError />
+</TextField>
+```
+
+`Input` is a primitive; `TextField` wraps it with `Label`, `Description`, `FieldError`. `TextArea` works the same way for multiline.
+
+### Select
+
+```tsx
+<Select>
+  <Label>Country</Label>
+  <Select.Trigger><Select.Value placeholder="Choose..." /><Select.Indicator /></Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      <ListBox.Item id="us">United States</ListBox.Item>
+      <ListBox.Item id="uk">United Kingdom</ListBox.Item>
+    </ListBox>
+  </Select.Popover>
+</Select>
+```
+
+### Checkbox / RadioGroup / Switch
+
+```tsx
+<Checkbox>
+  <Checkbox.Content>
+    <Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
+    Accept terms
+  </Checkbox.Content>
+</Checkbox>
+
+<RadioGroup>
+  <Label>Plan</Label>
+  <Radio value="free"><Radio.Content><Radio.Control><Radio.Indicator /></Radio.Control>Free</Radio.Content></Radio>
+  <Radio value="pro"><Radio.Content><Radio.Control><Radio.Indicator /></Radio.Control>Pro</Radio.Content></Radio>
+</RadioGroup>
+
+<Switch><Switch.Content><Switch.Control><Switch.Thumb /></Switch.Control>Dark mode</Switch.Content></Switch>
+```
+
+### Slider
+
+```tsx
+<Slider defaultValue={50} minValue={0} maxValue={100}>
+  <Label>Volume</Label>
+  <Slider.Output />
+  <Slider.Track><Slider.Fill /><Slider.Thumb /></Slider.Track>
+</Slider>
+```
+
+### DatePicker
+
+Composed from `DatePicker`, `DateField`, and `Calendar`:
+
+```tsx
+<DatePicker>
+  <Label>Date</Label>
+  <DateField.Group>
+    <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
+    <DateField.Suffix><DatePicker.Trigger><DatePicker.TriggerIndicator /></DatePicker.Trigger></DateField.Suffix>
+  </DateField.Group>
+  <DatePicker.Popover>
+    <Calendar aria-label="Choose date">
+      <Calendar.Header><Calendar.NavButton slot="previous" /><Calendar.Heading /><Calendar.NavButton slot="next" /></Calendar.Header>
+      <Calendar.Grid>{(date) => <Calendar.Cell date={date} />}</Calendar.Grid>
+    </Calendar>
+  </DatePicker.Popover>
+</DatePicker>
+```
+
+### Table
+
+```tsx
+<Table>
+  <Table.ScrollContainer>
+    <Table.Content aria-label="Users">
+      <Table.Header>
+        <Table.Column isRowHeader>Name</Table.Column>
+        <Table.Column>Role</Table.Column>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row><Table.Cell>Jane Cooper</Table.Cell><Table.Cell>Developer</Table.Cell></Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+### Chip / Badge / Avatar
+
+```tsx
+<Chip>Active</Chip>
+<Chip variant="outline">Draft</Chip>
+
+<Badge.Anchor>
+  <Avatar><Avatar.Fallback>JD</Avatar.Fallback></Avatar>
+  <Badge color="danger">3</Badge>
+</Badge.Anchor>
+
+<Avatar><Avatar.Image src="/photo.jpg" alt="User" /><Avatar.Fallback>JD</Avatar.Fallback></Avatar>
+```
+
+### Tabs
+
+```tsx
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Options">
+      <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="tab1">Content 1</Tabs.Panel>
+  <Tabs.Panel id="tab2">Content 2</Tabs.Panel>
+</Tabs>
+```
+
+### Breadcrumbs / Link / Pagination / Separator
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+</Breadcrumbs>
+
+<Link href="/about">About<Link.Icon /></Link>
+<Separator />
+
+<Pagination><Pagination.Content>
+  <Pagination.Item><Pagination.Previous /></Pagination.Item>
+  <Pagination.Item><Pagination.Link isActive>1</Pagination.Link></Pagination.Item>
+  <Pagination.Item><Pagination.Link>2</Pagination.Link></Pagination.Item>
+  <Pagination.Item><Pagination.Next /></Pagination.Item>
+</Pagination.Content></Pagination>
+```
+
+### Modal
+
+```tsx
+<Modal>
+  <Button>Open</Button>
+  <Modal.Backdrop><Modal.Container><Modal.Dialog>
+    <Modal.CloseTrigger />
+    <Modal.Header><Modal.Heading>Title</Modal.Heading></Modal.Header>
+    <Modal.Body><p>Content</p></Modal.Body>
+    <Modal.Footer><Button slot="close" variant="ghost">Cancel</Button><Button variant="primary">Confirm</Button></Modal.Footer>
+  </Modal.Dialog></Modal.Container></Modal.Backdrop>
+</Modal>
+```
+
+### Drawer (same structure as Modal)
+
+```tsx
+<Drawer>
+  <Button>Open Drawer</Button>
+  <Drawer.Backdrop><Drawer.Content><Drawer.Dialog>
+    <Drawer.CloseTrigger />
+    <Drawer.Header><Drawer.Heading>Settings</Drawer.Heading></Drawer.Header>
+    <Drawer.Body>Content</Drawer.Body>
+    <Drawer.Footer><Button slot="close">Done</Button></Drawer.Footer>
+  </Drawer.Dialog></Drawer.Content></Drawer.Backdrop>
+</Drawer>
+```
+
+### Dropdown / Popover / Tooltip
+
+```tsx
+<Dropdown>
+  <Dropdown.Trigger><Button>Actions</Button></Dropdown.Trigger>
+  <Dropdown.Popover><Dropdown.Menu aria-label="Actions">
+    <Dropdown.Item id="edit"><Label>Edit</Label></Dropdown.Item>
+    <Dropdown.Item id="delete"><Label>Delete</Label></Dropdown.Item>
+  </Dropdown.Menu></Dropdown.Popover>
+</Dropdown>
+
+<Popover>
+  <Popover.Trigger><Button>Info</Button></Popover.Trigger>
+  <Popover.Content><Popover.Dialog><p>Details</p></Popover.Dialog></Popover.Content>
+</Popover>
+
+<Tooltip>
+  <Tooltip.Trigger><Button>Hover</Button></Tooltip.Trigger>
+  <Tooltip.Content>Helpful tip</Tooltip.Content>
+</Tooltip>
+```
+
+### Alert / Toast / ProgressBar / Spinner / Skeleton
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content><Alert.Title>Saved</Alert.Title><Alert.Description>Changes are live.</Alert.Description></Alert.Content>
+</Alert>
+
+<Toast.Provider /> {/* place once in root */}
+toast("Saved!"); toast.success("Done"); toast.error("Failed");
+
+<ProgressBar value={60}><Label>Loading</Label><ProgressBar.Output /><ProgressBar.Track><ProgressBar.Fill /></ProgressBar.Track></ProgressBar>
+
+<Spinner />
+<Skeleton className="h-4 w-48 rounded" />
+```
+
+---
+
+## Common Patterns
+
+**Form in a Card** — wrap `TextField`s in `Card.Content`, action button in `Card.Footer`:
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <Card.Header><Card.Title>Sign Up</Card.Title></Card.Header>
+  <Card.Content className="flex flex-col gap-4">
+    <TextField><Label>Name</Label><Input placeholder="Jane Doe" /></TextField>
+    <TextField><Label>Email</Label><Input type="email" placeholder="jane@example.com" /></TextField>
+  </Card.Content>
+  <Card.Footer><Button variant="primary" fullWidth>Create Account</Button></Card.Footer>
+</Card>
+```
+
+**Card Grid** — use CSS grid: `<div className="grid grid-cols-1 md:grid-cols-3 gap-4">` with Card children.
+
+---
+
+## Rules
+
+1. **Never** wrap in a HeroUI Provider — not needed.
+2. **Never** import from `@nextui-org/*` — that is the old v2.
+3. **Never** use Tailwind v3 config. HeroUI v3 uses Tailwind CSS v4 with CSS-based config.
+4. **Always** use dot notation: `Card.Header`, not `CardHeader`.
+5. **Always** use `onPress` on Button, not `onClick`.
+6. **Always** add `aria-label` to icon-only buttons and `Table.Content`.
diff --git a/prompts/v0-heroui.md b/prompts/v0-heroui.md
new file mode 100644
index 0000000..6eeaf95
--- /dev/null
+++ b/prompts/v0-heroui.md
@@ -0,0 +1,325 @@
+# HeroUI v3 — Prompt for v0.dev
+
+You are an expert frontend React developer. You always use the latest stable versions of HeroUI, React, and Tailwind CSS, and you follow best practices for Next.js App Router.
+
+When the user asks you to build a UI, **always use HeroUI v3** (`@heroui/react`) as the component library.
+
+## Setup
+
+HeroUI v3 requires:
+- `@heroui/react` — the component library
+- Tailwind CSS **v4** — HeroUI ships its own CSS built on Tailwind v4
+
+```bash
+npm install @heroui/react
+```
+
+No Provider or wrapper component is needed. Import and use directly.
+
+## Import Pattern
+
+```tsx
+import { Button, Card, Input, Modal, Table } from "@heroui/react";
+```
+
+All components come from `@heroui/react`. Sub-components use dot notation (e.g. `Card.Header`, `Modal.Dialog`).
+
+## Next.js App Router Compatibility
+
+- All HeroUI components work in both Server Components and Client Components.
+- For interactive state (e.g. controlled modals, form handlers), mark the file `"use client"`.
+- Static rendering of HeroUI components (cards, badges, layout) works in Server Components without `"use client"`.
+
+## Key Components and Usage
+
+### Button
+
+```tsx
+<Button variant="primary" size="md" onPress={() => {}}>Save</Button>
+<Button variant="outline">Cancel</Button>
+<Button variant="danger">Delete</Button>
+<Button isIconOnly aria-label="Close"><XIcon /></Button>
+```
+
+Variants: `primary`, `secondary`, `tertiary`, `outline`, `ghost`, `danger`.
+Sizes: `sm`, `md`, `lg`. Use `onPress` (not `onClick`).
+
+### Card
+
+```tsx
+<Card>
+  <Card.Header>
+    <Card.Title>Title</Card.Title>
+    <Card.Description>Subtitle</Card.Description>
+  </Card.Header>
+  <Card.Content>Body content</Card.Content>
+  <Card.Footer>
+    <Button variant="primary">Action</Button>
+  </Card.Footer>
+</Card>
+```
+
+### TextField (labeled input with validation)
+
+```tsx
+<TextField>
+  <Label>Email</Label>
+  <Input type="email" placeholder="you@example.com" />
+  <Description>We'll never share your email.</Description>
+  <FieldError />
+</TextField>
+```
+
+### Select
+
+```tsx
+<Select>
+  <Label>Country</Label>
+  <Select.Trigger>
+    <Select.Value placeholder="Choose..." />
+    <Select.Indicator />
+  </Select.Trigger>
+  <Select.Popover>
+    <ListBox>
+      <ListBox.Item id="us">United States</ListBox.Item>
+      <ListBox.Item id="uk">United Kingdom</ListBox.Item>
+    </ListBox>
+  </Select.Popover>
+</Select>
+```
+
+### Checkbox
+
+```tsx
+<Checkbox>
+  <Checkbox.Content>
+    <Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
+    Accept terms
+  </Checkbox.Content>
+</Checkbox>
+```
+
+### RadioGroup
+
+```tsx
+<RadioGroup>
+  <Label>Plan</Label>
+  <Radio value="free">
+    <Radio.Content>
+      <Radio.Control><Radio.Indicator /></Radio.Control>
+      Free
+    </Radio.Content>
+  </Radio>
+  <Radio value="pro">
+    <Radio.Content>
+      <Radio.Control><Radio.Indicator /></Radio.Control>
+      Pro
+    </Radio.Content>
+  </Radio>
+</RadioGroup>
+```
+
+### Switch
+
+```tsx
+<Switch>
+  <Switch.Content>
+    <Switch.Control><Switch.Thumb /></Switch.Control>
+    Notifications
+  </Switch.Content>
+</Switch>
+```
+
+### Table
+
+```tsx
+<Table>
+  <Table.ScrollContainer>
+    <Table.Content aria-label="Users">
+      <Table.Header>
+        <Table.Column isRowHeader>Name</Table.Column>
+        <Table.Column>Role</Table.Column>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Jane Cooper</Table.Cell>
+          <Table.Cell>Developer</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Content>
+  </Table.ScrollContainer>
+</Table>
+```
+
+### Tabs
+
+```tsx
+<Tabs>
+  <Tabs.ListContainer>
+    <Tabs.List aria-label="Sections">
+      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
+      <Tabs.Tab id="settings">Settings<Tabs.Indicator /></Tabs.Tab>
+    </Tabs.List>
+  </Tabs.ListContainer>
+  <Tabs.Panel id="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+### Modal
+
+```tsx
+<Modal>
+  <Button>Open</Button>
+  <Modal.Backdrop>
+    <Modal.Container>
+      <Modal.Dialog>
+        <Modal.CloseTrigger />
+        <Modal.Header><Modal.Heading>Title</Modal.Heading></Modal.Header>
+        <Modal.Body><p>Content here</p></Modal.Body>
+        <Modal.Footer>
+          <Button slot="close" variant="ghost">Cancel</Button>
+          <Button variant="primary">Confirm</Button>
+        </Modal.Footer>
+      </Modal.Dialog>
+    </Modal.Container>
+  </Modal.Backdrop>
+</Modal>
+```
+
+### Drawer
+
+```tsx
+<Drawer>
+  <Button>Open Drawer</Button>
+  <Drawer.Backdrop>
+    <Drawer.Content>
+      <Drawer.Dialog>
+        <Drawer.CloseTrigger />
+        <Drawer.Header><Drawer.Heading>Settings</Drawer.Heading></Drawer.Header>
+        <Drawer.Body>Content</Drawer.Body>
+        <Drawer.Footer><Button slot="close">Done</Button></Drawer.Footer>
+      </Drawer.Dialog>
+    </Drawer.Content>
+  </Drawer.Backdrop>
+</Drawer>
+```
+
+### Dropdown
+
+```tsx
+<Dropdown>
+  <Dropdown.Trigger><Button>Actions</Button></Dropdown.Trigger>
+  <Dropdown.Popover>
+    <Dropdown.Menu aria-label="Actions">
+      <Dropdown.Item id="edit"><Label>Edit</Label></Dropdown.Item>
+      <Dropdown.Item id="delete"><Label>Delete</Label></Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown.Popover>
+</Dropdown>
+```
+
+### Alert, Spinner, Skeleton, Chip, Avatar, Badge, Tooltip, Popover
+
+```tsx
+<Alert status="success">
+  <Alert.Indicator />
+  <Alert.Content>
+    <Alert.Title>Saved</Alert.Title>
+    <Alert.Description>Your changes are live.</Alert.Description>
+  </Alert.Content>
+</Alert>
+
+<Spinner />
+
+<Skeleton className="h-4 w-48 rounded" />
+
+<Chip>Active</Chip>
+
+<Avatar>
+  <Avatar.Image src="/photo.jpg" alt="User" />
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar>
+
+<Badge.Anchor>
+  <Avatar><Avatar.Fallback>AB</Avatar.Fallback></Avatar>
+  <Badge color="danger">3</Badge>
+</Badge.Anchor>
+
+<Tooltip>
+  <Tooltip.Trigger><Button>Hover</Button></Tooltip.Trigger>
+  <Tooltip.Content>Tooltip text</Tooltip.Content>
+</Tooltip>
+
+<Popover>
+  <Popover.Trigger><Button>Info</Button></Popover.Trigger>
+  <Popover.Content>
+    <Popover.Dialog><p>Details here</p></Popover.Dialog>
+  </Popover.Content>
+</Popover>
+```
+
+### Breadcrumbs, Link, Pagination, Separator
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/docs">Docs</Breadcrumbs.Item>
+  <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+</Breadcrumbs>
+
+<Link href="/about">About<Link.Icon /></Link>
+
+<Separator />
+
+<Pagination>
+  <Pagination.Content>
+    <Pagination.Item><Pagination.Previous /></Pagination.Item>
+    <Pagination.Item><Pagination.Link isActive>1</Pagination.Link></Pagination.Item>
+    <Pagination.Item><Pagination.Link>2</Pagination.Link></Pagination.Item>
+    <Pagination.Item><Pagination.Next /></Pagination.Item>
+  </Pagination.Content>
+</Pagination>
+```
+
+### Toast (requires provider)
+
+```tsx
+// In root layout:
+<Toast.Provider />
+
+// Trigger anywhere:
+import { toast } from "@heroui/react";
+toast("Saved!");
+toast.success("Done");
+toast.error("Failed");
+```
+
+### ProgressBar
+
+```tsx
+<ProgressBar value={60}>
+  <Label>Loading</Label>
+  <ProgressBar.Output />
+  <ProgressBar.Track><ProgressBar.Fill /></ProgressBar.Track>
+</ProgressBar>
+```
+
+## Styling
+
+HeroUI works with Tailwind CSS v4 classes via `className`:
+
+```tsx
+<Button className="rounded-full">Pill</Button>
+<Card className="border border-blue-200 shadow-xl">...</Card>
+```
+
+## Rules — Do Not Break These
+
+1. **Never** wrap in a HeroUI Provider — not needed in v3.
+2. **Never** import from `@nextui-org/*` — that is the old v2 library.
+3. **Never** use Tailwind v3 config (`tailwind.config.js`). HeroUI v3 requires Tailwind CSS v4 with CSS-based configuration.
+4. **Always** use dot notation: `Card.Header` not `CardHeader`.
+5. **Always** use `onPress` on Button, not `onClick`.
+6. **Always** add `aria-label` to icon-only buttons and to `Table.Content`.
+7. **Always** add `"use client"` when the component uses React state, effects, or event handlers.
diff --git a/skills/heroui-migration/LICENSE.txt b/skills/heroui-migration/LICENSE.txt
new file mode 100644
index 0000000..bf4dfe2
--- /dev/null
+++ b/skills/heroui-migration/LICENSE.txt
@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/heroui-migration/SKILL.md b/skills/heroui-migration/SKILL.md
new file mode 100644
index 0000000..611d31c
--- /dev/null
+++ b/skills/heroui-migration/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: heroui-migration
+description: "HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI."
+metadata:
+  author: heroui
+  version: "2.0.0"
+  status: preview
+---
+
+# HeroUI v2 to v3 Migration Guide
+
+This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-migration
+```
+
+---
+
+## CRITICAL: Always Fetch Migration Docs Before Applying
+
+**Do NOT assume v2 patterns work in v3.** Always fetch migration guides before implementing changes.
+
+### Key v2 → v3 Changes
+
+| Feature       | v2 (Migrate From)          | v3 (Migrate To)                        |
+| ------------- | -------------------------- | -------------------------------------- |
+| Provider      | `<HeroUIProvider>` required | **No Provider needed**                 |
+| Component API | Flat props: `<Card title="x">` | Compound: `<Card><Card.Header>`      |
+| Event handlers | `onClick`                 | `onPress`                              |
+| Styling       | `classNames` prop         | `className` prop                       |
+| Hooks         | `useSwitch`, `useDisclosure`, etc. | Compound components, `useOverlayState` |
+| Packages      | `@heroui/system`, `@heroui/theme` | `@heroui/react`, `@heroui/styles` |
+
+---
+
+## Accessing Migration Documentation
+
+**For migration details, examples, and step-by-step guides, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available component migration guides
+node scripts/list_migration_guides.mjs
+
+# Get main migration workflow (full or incremental)
+node scripts/get_migration_guide.mjs full
+node scripts/get_migration_guide.mjs incremental
+
+# Get component-specific migration guides
+node scripts/get_component_migration_guides.mjs button
+node scripts/get_component_migration_guides.mjs button card modal
+
+# Get styling migration guide
+node scripts/get_styling_migration_guide.mjs
+
+# Get hooks migration guide
+node scripts/get_hooks_migration_guide.mjs
+```
+
+### Direct URLs
+
+Migration docs (preview): `https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}`
+
+Examples:
+
+- Full migration: `.../agent-guide-full.mdx`
+- Incremental: `.../agent-guide-incremental.mdx`
+- Button: `.../button.mdx`
+- Styling: `.../styling.mdx`
+- Hooks: `.../hooks.mdx`
+
+Override base URL with `HEROUI_MIGRATION_DOCS_BASE` when docs are merged to production.
+
+### MCP Alternative
+
+When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:
+
+```json
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+---
+
+## Migration Strategies
+
+### Full Migration
+
+- Best for: Projects that can dedicate focused time; teams comfortable with temporarily broken code
+- Migrate all component code first (project broken during migration)
+- Switch dependencies to v3
+- Complete styling migration
+
+### Incremental Migration
+
+- Best for: Projects that must stay functional; large codebases migrating gradually
+- Set up coexistence (pnpm aliases or component packages)
+- Migrate components one-by-one
+- Both v2 and v3 coexist during migration
+
+**Always fetch the agent guide before starting:** `node scripts/get_migration_guide.mjs full` or `incremental`
+
+---
+
+## Core Principles
+
+1. **Fetch first**: Use scripts to get migration guides before applying changes
+2. **Compound components**: v3 uses `Card.Header`, `Card.Title`, `Button` with children—not flat props
+3. **No Provider**: Remove `HeroUIProvider` when migrating
+4. **onPress not onClick**: All interactive components use `onPress`
+5. **Workflow**: Analyze → Migrate components → Switch deps → Styling migration
+
+---
+
+## Migration Workflow Summary
+
+1. Create migration branch
+2. Analyze project (HeroUI imports, component usage)
+3. Fetch main guide: `node scripts/get_migration_guide.mjs full`
+4. Migrate components in batches (fetch component guides per batch)
+5. Switch dependencies to v3
+6. Fetch styling guide: `node scripts/get_styling_migration_guide.mjs`
+7. Apply styling updates
+
+---
+
+## Preview Mode
+
+This skill targets the staging deployment of the `docs/migration` branch. Once docs are merged to main and live on heroui.com, set `HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration` or update the default in scripts.
diff --git a/skills/heroui-migration/scripts/get_component_migration_guides.mjs b/skills/heroui-migration/scripts/get_component_migration_guides.mjs
new file mode 100644
index 0000000..2bed636
--- /dev/null
+++ b/skills/heroui-migration/scripts/get_component_migration_guides.mjs
@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Get migration guides for HeroUI components (v2 to v3).
+ *
+ * Usage:
+ *   node get_component_migration_guides.mjs button
+ *   node get_component_migration_guides.mjs button card modal
+ *
+ * Output:
+ *   MDX migration guide content for each component
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+/**
+ * Convert PascalCase or mixed case to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase()
+    .trim();
+}
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(error.message);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_migration_guides.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_migration_guides.mjs button card modal");
+    console.error("\nUse list_migration_guides.mjs to see all available components.");
+    process.exit(1);
+  }
+
+  const components = args.map((c) => toKebabCase(c));
+
+  console.error(`# Fetching migration guides for: ${components.join(", ")}...`);
+
+  const results = [];
+
+  for (const component of components) {
+    const filename = `${component}.mdx`;
+
+    try {
+      const content = await fetchDoc(filename);
+      const title = component.charAt(0).toUpperCase() + component.slice(1).replace(/-/g, " ");
+
+      results.push({
+        component,
+        content: `# ${title} Migration Guide\n\n**Component:** ${component}\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+      });
+    } catch (error) {
+      results.push({
+        component,
+        error: error.message,
+      });
+    }
+  }
+
+  const failed = results.filter((r) => r.error);
+
+  if (failed.length > 0) {
+    failed.forEach((r) => console.error(`# Error for ${r.component}: ${r.error}`));
+  }
+
+  if (results.length === 1) {
+    const r = results[0];
+
+    if (r.content) {
+      console.log(r.content);
+    } else {
+      console.log(JSON.stringify(r, null, 2));
+      process.exit(1);
+    }
+  } else {
+    const output = results
+      .map((r) => (r.content ? r.content : `# ${r.component} Migration Guide\n\nError: ${r.error}`))
+      .join("\n\n---\n\n");
+
+    console.log(output);
+    if (failed.length === results.length) {
+      process.exit(1);
+    }
+  }
+}
+
+main();
diff --git a/skills/heroui-migration/scripts/get_hooks_migration_guide.mjs b/skills/heroui-migration/scripts/get_hooks_migration_guide.mjs
new file mode 100644
index 0000000..72fe248
--- /dev/null
+++ b/skills/heroui-migration/scripts/get_hooks_migration_guide.mjs
@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Get the hooks migration guide for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_hooks_migration_guide.mjs
+ *
+ * Output:
+ *   MDX hooks migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const filename = "hooks.mdx";
+
+  console.error("# Fetching hooks migration guide...");
+
+  try {
+    const content = await fetchDoc(filename);
+
+    console.log(
+      `# HeroUI v2 to v3 Hooks Migration Guide\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+    );
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/skills/heroui-migration/scripts/get_migration_guide.mjs b/skills/heroui-migration/scripts/get_migration_guide.mjs
new file mode 100644
index 0000000..423e326
--- /dev/null
+++ b/skills/heroui-migration/scripts/get_migration_guide.mjs
@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Get the main migration workflow guide (full or incremental) for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_migration_guide.mjs [full|incremental]
+ *
+ * Default: full
+ *
+ * Output:
+ *   MDX migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const arg = (process.argv[2] || "full").toLowerCase();
+  const migrationType = arg === "incremental" ? "incremental" : "full";
+  const filename =
+    migrationType === "incremental" ? "agent-guide-incremental.mdx" : "agent-guide-full.mdx";
+
+  console.error(`# Fetching ${migrationType} migration guide...`);
+
+  try {
+    const content = await fetchDoc(filename);
+    const title =
+      migrationType === "incremental"
+        ? "HeroUI v2 to v3 Agent Migration Guide - Incremental Migration"
+        : "HeroUI v2 to v3 Agent Migration Guide - Full Migration";
+
+    console.log(`# ${title}\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`);
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/skills/heroui-migration/scripts/get_styling_migration_guide.mjs b/skills/heroui-migration/scripts/get_styling_migration_guide.mjs
new file mode 100644
index 0000000..68e3566
--- /dev/null
+++ b/skills/heroui-migration/scripts/get_styling_migration_guide.mjs
@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Get the styling migration guide for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_styling_migration_guide.mjs
+ *
+ * Output:
+ *   MDX styling migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const filename = "styling.mdx";
+
+  console.error("# Fetching styling migration guide...");
+
+  try {
+    const content = await fetchDoc(filename);
+
+    console.log(
+      `# HeroUI v2 to v3 Styling Migration Guide\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+    );
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/skills/heroui-migration/scripts/list_migration_guides.mjs b/skills/heroui-migration/scripts/list_migration_guides.mjs
new file mode 100644
index 0000000..91982c0
--- /dev/null
+++ b/skills/heroui-migration/scripts/list_migration_guides.mjs
@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI v2 to v3 component migration guides.
+ *
+ * Usage:
+ *   node list_migration_guides.mjs
+ *
+ * Output:
+ *   List of component names that have migration guides
+ *
+ * Note: Keep in sync with migration-mcp list-migration-guides.ts when adding components.
+ */
+
+// Component migration guides available - must match migration-mcp list-migration-guides.ts
+const AVAILABLE_COMPONENTS = [
+  "accordion",
+  "alert",
+  "autocomplete",
+  "avatar",
+  "breadcrumbs",
+  "button",
+  "button-group",
+  "card",
+  "checkbox",
+  "checkbox-group",
+  "chip",
+  "code",
+  "divider",
+  "dropdown",
+  "form",
+  "image",
+  "input",
+  "input-otp",
+  "kbd",
+  "link",
+  "listbox",
+  "modal",
+  "navbar",
+  "numberinput",
+  "popover",
+  "radio",
+  "radio-group",
+  "scroll-shadow",
+  "select",
+  "skeleton",
+  "slider",
+  "snippet",
+  "spacer",
+  "spinner",
+  "switch",
+  "tabs",
+  "toast",
+  "tooltip",
+  "user",
+];
+
+function main() {
+  const componentsList = AVAILABLE_COMPONENTS.map((name) => `  - ${name}`).join("\n");
+
+  console.log(
+    `# Available Component Migration Guides\n\nFound ${AVAILABLE_COMPONENTS.length} component migration guides:\n\n${componentsList}\n\nUse get_component_migration_guides.mjs with component names to fetch specific guides.\nExample: node get_component_migration_guides.mjs button card modal`,
+  );
+}
+
+main();
diff --git a/skills/heroui-native/LICENSE.txt b/skills/heroui-native/LICENSE.txt
new file mode 100644
index 0000000..bf4dfe2
--- /dev/null
+++ b/skills/heroui-native/LICENSE.txt
@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/heroui-native/SKILL.md b/skills/heroui-native/SKILL.md
new file mode 100644
index 0000000..33ace07
--- /dev/null
+++ b/skills/heroui-native/SKILL.md
@@ -0,0 +1,229 @@
+---
+name: heroui-native
+description: "HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind, mobile components."
+metadata:
+  author: heroui
+  version: "2.0.1"
+---
+
+# HeroUI Native Development Guide
+
+HeroUI Native is a component library built on **Uniwind (Tailwind CSS for React Native)** and **React Native**, providing accessible, customizable UI components for mobile applications.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-native
+```
+
+---
+
+## CRITICAL: Native Only - Do Not Use Web Patterns
+
+**This guide is for HeroUI Native ONLY.** Do NOT apply HeroUI React (web) patterns — the package, styling engine, and color format all differ:
+
+| Feature      | React (Web)          | Native (Mobile)                     |
+| ------------ | -------------------- | ----------------------------------- |
+| **Styling**  | Tailwind CSS v4      | Uniwind (Tailwind for React Native) |
+| **Colors**   | oklch format         | HSL format                          |
+| **Package**  | `@heroui/react` 	  | `heroui-native`                     |
+| **Platform** | Web browsers         | iOS & Android                       |
+
+```tsx
+// CORRECT — Native pattern
+import { Button } from "heroui-native";
+
+<Button variant="primary" onPress={() => console.log("Pressed!")}>
+	Click me
+</Button>;
+```
+
+**Always fetch Native docs before implementing.**
+
+---
+
+## Core Principles
+
+- Semantic variants (`primary`, `secondary`, `tertiary`) over visual descriptions
+- Composition over configuration (compound components)
+- Theme variables with HSL color format
+- React Native StyleSheet patterns with Uniwind utilities
+
+---
+
+## Accessing Documentation & Component Information
+
+**For component details, examples, props, and implementation patterns, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available components
+node scripts/list_components.mjs
+
+# Get component documentation (MDX)
+node scripts/get_component_docs.mjs Button
+node scripts/get_component_docs.mjs Button Card TextField
+
+# Get theme variables
+node scripts/get_theme.mjs
+
+# Get non-component docs (guides, releases)
+node scripts/get_docs.mjs /docs/native/getting-started/theming
+```
+
+### Direct MDX URLs
+
+Component docs: `https://heroui.com/docs/native/components/{component-name}.mdx`
+
+Examples:
+
+- Button: `https://heroui.com/docs/native/components/button.mdx`
+- Dialog: `https://heroui.com/docs/native/components/dialog.mdx`
+- TextField: `https://heroui.com/docs/native/components/text-field.mdx`
+
+Getting started guides: `https://heroui.com/docs/native/getting-started/{topic}.mdx`
+
+**Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
+
+---
+
+## Installation Essentials
+
+### Quick Install
+
+```bash
+npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
+```
+
+### Framework Setup (Expo - Recommended)
+
+1. **Install dependencies:**
+
+```bash
+npx create-expo-app MyApp
+cd MyApp
+npm i heroui-native uniwind tailwindcss
+npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
+```
+
+2. **Create `global.css`:**
+
+```css
+@import "tailwindcss";
+@import "uniwind";
+@import "heroui-native/styles";
+
+@source "./node_modules/heroui-native/lib";
+```
+
+3. **Wrap app with providers:**
+
+```tsx
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { HeroUINativeProvider } from "heroui-native";
+import "./global.css";
+
+export default function Layout() {
+	return (
+		<GestureHandlerRootView style={{ flex: 1 }}>
+			<HeroUINativeProvider>
+				<App />
+			</HeroUINativeProvider>
+		</GestureHandlerRootView>
+	);
+}
+```
+
+### Critical Setup Requirements
+
+1. **Uniwind is Required** - HeroUI Native uses Uniwind (Tailwind CSS for React Native)
+2. **HeroUINativeProvider Required** - Wrap your app with `HeroUINativeProvider`
+3. **GestureHandlerRootView Required** - Wrap with `GestureHandlerRootView` from react-native-gesture-handler
+4. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Body`)
+5. **Use onPress, not onClick** - React Native uses `onPress` event handlers
+6. **Platform-Specific Code** - Use `Platform.OS` for iOS/Android differences
+
+---
+
+## Component Patterns
+
+HeroUI Native uses **compound component patterns**. Each component has subcomponents accessed via dot notation.
+
+**Example - Card:**
+
+```tsx
+<Card>
+	<Card.Header>{/* Icons, badges */}</Card.Header>
+	<Card.Body>
+		<Card.Title>Title</Card.Title>
+		<Card.Description>Description</Card.Description>
+	</Card.Body>
+	<Card.Footer>{/* Actions */}</Card.Footer>
+</Card>
+```
+
+**Key Points:**
+
+- Always use compound structure - don't flatten to props
+- Subcomponents are accessed via dot notation (e.g., `Card.Header`)
+- Native Card uses `Card.Body` (not `Card.Content`); Title and Description go inside Body
+- **Fetch component docs for complete anatomy and examples**
+
+---
+
+## Semantic Variants
+
+HeroUI uses semantic naming to communicate functional intent:
+
+| Variant       | Purpose                           | Usage          |
+| ------------- | --------------------------------- | -------------- |
+| `primary`     | Main action to move forward       | 1 per context  |
+| `secondary`   | Alternative actions               | Multiple       |
+| `tertiary`    | Dismissive actions (cancel, skip) | Sparingly      |
+| `danger`      | Destructive actions               | When needed    |
+| `danger-soft` | Soft destructive actions          | Less prominent |
+| `ghost`       | Low-emphasis actions              | Minimal weight |
+| `outline`     | Secondary actions                 | Bordered style |
+
+**Don't use raw colors** - semantic variants adapt to themes and accessibility.
+
+---
+
+## Theming
+
+HeroUI Native uses CSS variables via Tailwind/Uniwind for theming. Theme colors are defined in `global.css`:
+
+```css
+@theme {
+	--color-accent: hsl(260, 100%, 70%);
+	--color-accent-foreground: hsl(0, 0%, 100%);
+}
+```
+
+**Get current theme variables:**
+
+```bash
+node scripts/get_theme.mjs
+```
+
+**Access theme colors programmatically:**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+const accentColor = useThemeColor("accent");
+```
+
+**Theme switching (Light/Dark Mode):**
+
+```tsx
+import { Uniwind, useUniwind } from "uniwind";
+
+const { theme } = useUniwind();
+Uniwind.setTheme(theme === "light" ? "dark" : "light");
+```
+
+For detailed theming, fetch: `https://heroui.com/docs/native/getting-started/theming.mdx`
diff --git a/skills/heroui-native/scripts/get_component_docs.mjs b/skills/heroui-native/scripts/get_component_docs.mjs
new file mode 100755
index 0000000..1cec325
--- /dev/null
+++ b/skills/heroui-native/scripts/get_component_docs.mjs
@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Get complete component documentation (MDX) for HeroUI Native components.
+ *
+ * Usage:
+ *   node get_component_docs.mjs Button
+ *   node get_component_docs.mjs Button Card TextField
+ *
+ * Output:
+ *   MDX documentation including imports, usage, variants, props, examples
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=native-skills";
+
+/**
+ * Convert PascalCase to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Native-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(component) {
+  const kebabName = toKebabCase(component);
+  const url = `${FALLBACK_BASE}/docs/native/components/${kebabName}.mdx`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {component, error: `Failed to fetch docs for ${component}`};
+    }
+
+    const content = await response.text();
+
+    return {
+      component,
+      content,
+      contentType: "mdx",
+      source: "fallback",
+      url,
+    };
+  } catch {
+    return {component, error: `Failed to fetch docs for ${component}`};
+  }
+}
+
+/**
+ * Main function to get component documentation.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_docs.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_docs.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first - use POST /v1/components/docs for batch requests
+  console.error(`# Fetching Native docs for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/docs", "POST", {components});
+
+  if (data && data.results) {
+    // Output results
+    if (data.results.length === 1) {
+      // Single component - output content directly for easier reading
+      const result = data.results[0];
+
+      if (result.content) {
+        console.log(result.content);
+      } else if (result.error) {
+        console.error(`# Error for ${result.component}: ${result.error}`);
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      // Multiple components - output as JSON array
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to individual component fetches
+  console.error("# API failed, using fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchFallback(component);
+
+    results.push(result);
+  }
+
+  // Output results
+  if (results.length === 1) {
+    // Single component - output content directly for easier reading
+    const result = results[0];
+
+    if (result.content) {
+      console.log(result.content);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    // Multiple components - output as JSON array
+    console.log(JSON.stringify(results, null, 2));
+  }
+}
+
+main();
diff --git a/skills/heroui-native/scripts/get_docs.mjs b/skills/heroui-native/scripts/get_docs.mjs
new file mode 100755
index 0000000..cf3a47e
--- /dev/null
+++ b/skills/heroui-native/scripts/get_docs.mjs
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Get non-component HeroUI Native documentation (guides, theming, releases).
+ *
+ * Usage:
+ *   node get_docs.mjs /docs/native/getting-started/theming
+ *   node get_docs.mjs /docs/native/releases/beta-12
+ *
+ * Output:
+ *   MDX documentation content
+ *
+ * Note: For component docs, use get_component_docs.mjs instead.
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=native-skills";
+
+/**
+ * Fetch documentation from HeroUI Native API.
+ * Uses v1 endpoint pattern: /v1/docs/:path
+ */
+async function fetchApi(path) {
+  // The v1 API expects path without /docs/ prefix
+  // Input: /docs/native/getting-started/theming
+  // API expects: native/getting-started/theming (route is /v1/docs/:path(*))
+  let apiPath = path.startsWith("/docs/")
+    ? path.slice(6) // Remove /docs/ prefix
+    : path.startsWith("/")
+      ? path.slice(1) // Remove leading /
+      : path;
+
+  const separator = "?";
+  const url = `${API_BASE}/v1/docs/${apiPath}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(path) {
+  // Ensure path starts with /docs and ends with .mdx
+  let cleanPath = path.replace(/^\//, "");
+
+  if (!cleanPath.endsWith(".mdx")) {
+    cleanPath = `${cleanPath}.mdx`;
+  }
+
+  const url = `${FALLBACK_BASE}/${cleanPath}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {error: `HTTP ${response.status}: ${response.statusText}`, path};
+    }
+
+    const content = await response.text();
+
+    return {
+      content,
+      contentType: "mdx",
+      path,
+      source: "fallback",
+      url,
+    };
+  } catch (error) {
+    return {error: `Fetch Error: ${error.message}`, path};
+  }
+}
+
+/**
+ * Main function to get documentation for specified path.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_docs.mjs <path>");
+    console.error("Example: node get_docs.mjs /docs/native/getting-started/theming");
+    console.error();
+    console.error("Available paths include:");
+    console.error("  /docs/native/getting-started/theming");
+    console.error("  /docs/native/getting-started/colors");
+    console.error("  /docs/native/getting-started/styling");
+    console.error("  /docs/native/releases/beta-12");
+    console.error();
+    console.error("Note: For component docs, use get_component_docs.mjs instead.");
+    process.exit(1);
+  }
+
+  const path = args[0];
+
+  // Check if user is trying to get component docs
+  if (path.includes("/components/")) {
+    console.error("# Warning: Use get_component_docs.mjs for component documentation.");
+    const componentName = path.split("/").pop().replace(".mdx", "");
+    const titleCase = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+    console.error(`# Example: node get_component_docs.mjs ${titleCase}`);
+  }
+
+  // Validate Native path
+  if (!path.startsWith("/docs/native/")) {
+    console.error("# Warning: Native documentation paths should start with /docs/native/");
+    console.error(`# Provided path: ${path}`);
+  }
+
+  console.error(`# Fetching Native documentation for ${path}...`);
+
+  // Try API first
+  const data = await fetchApi(path);
+
+  if (data && data.content) {
+    data.source = "api";
+    console.log(data.content);
+
+    return;
+  }
+
+  // Fallback to direct fetch
+  console.error("# API failed, using fallback...");
+  const fallbackData = await fetchFallback(path);
+
+  if (fallbackData.content) {
+    console.log(fallbackData.content);
+  } else {
+    console.log(JSON.stringify(fallbackData, null, 2));
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/skills/heroui-native/scripts/get_theme.mjs b/skills/heroui-native/scripts/get_theme.mjs
new file mode 100755
index 0000000..88faf95
--- /dev/null
+++ b/skills/heroui-native/scripts/get_theme.mjs
@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * Get theme variables and design tokens for HeroUI Native.
+ *
+ * Usage:
+ *   node get_theme.mjs
+ *
+ * Output:
+ *   Theme variables organized by light/dark with HSL color format
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const APP_PARAM = "app=native-skills";
+
+// Fallback theme reference when API is unavailable
+const FALLBACK_THEME = {
+  borderRadius: {
+    full: 9999,
+    lg: 12,
+    md: 8,
+    sm: 6,
+  },
+  dark: {
+    colors: [
+      {
+        category: "base",
+        name: "--color-background",
+        value: "hsl(0, 0%, 14.5%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-foreground",
+        value: "hsl(0, 0%, 98.4%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-accent",
+        value: "hsl(264.1, 100%, 55.1%)",
+      },
+      {
+        category: "status",
+        name: "--color-danger",
+        value: "hsl(25.3, 100%, 63.7%)",
+      },
+      {
+        category: "status",
+        name: "--color-success",
+        value: "hsl(163.2, 100%, 76.5%)",
+      },
+      {
+        category: "status",
+        name: "--color-warning",
+        value: "hsl(86.0, 100%, 79.5%)",
+      },
+    ],
+  },
+  latestVersion: "beta",
+  light: {
+    colors: [
+      {
+        category: "base",
+        name: "--color-background",
+        value: "hsl(0, 0%, 100%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-foreground",
+        value: "hsl(285.89, 5.9%, 21.03%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-accent",
+        value: "hsl(253.83, 100%, 62.04%)",
+      },
+      {
+        category: "status",
+        name: "--color-danger",
+        value: "hsl(25.74, 100%, 65.32%)",
+      },
+      {
+        category: "status",
+        name: "--color-success",
+        value: "hsl(150.81, 100%, 73.29%)",
+      },
+      {
+        category: "status",
+        name: "--color-warning",
+        value: "hsl(72.33, 100%, 78.19%)",
+      },
+    ],
+  },
+  note: "This is a fallback. For complete theme variables, ensure the API is accessible.",
+  opacity: {
+    disabled: 0.4,
+    hover: 0.8,
+    pressed: 0.6,
+  },
+  source: "fallback",
+  theme: "default",
+};
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Format colors grouped by category.
+ */
+function formatColors(colors) {
+  const grouped = {};
+
+  for (const color of colors) {
+    const category = color.category || "semantic";
+
+    if (!grouped[category]) {
+      grouped[category] = [];
+    }
+    grouped[category].push(color);
+  }
+
+  const lines = [];
+
+  for (const [category, tokens] of Object.entries(grouped)) {
+    lines.push(`  /* ${category.charAt(0).toUpperCase() + category.slice(1)} Colors */`);
+    for (const token of tokens) {
+      const name = token.name || "";
+      const value = token.value || "";
+
+      lines.push(`  ${name}: ${value};`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Main function to get theme variables.
+ */
+async function main() {
+  console.error("# Fetching Native theme variables...");
+
+  const rawData = await fetchApi("/v1/themes/variables?theme=default");
+
+  let data;
+  let version;
+
+  if (!rawData) {
+    console.error("# API failed, using fallback theme reference...");
+    data = FALLBACK_THEME;
+    version = FALLBACK_THEME.latestVersion || "unknown";
+  } else {
+    // Handle API response format
+    data = rawData;
+    version = rawData.latestVersion || "unknown";
+  }
+
+  // Output as formatted structure for readability
+  console.log("/* HeroUI Native Theme Variables */");
+  console.log(`/* Theme: ${data.theme || "default"} */`);
+  console.log(`/* Version: ${version} */`);
+  console.log();
+
+  // Light mode colors
+  if (data.light && data.light.colors) {
+    console.log("/* Light Mode Colors */");
+    console.log(formatColors(data.light.colors));
+  }
+
+  // Dark mode colors
+  if (data.dark && data.dark.colors) {
+    console.log("/* Dark Mode Colors */");
+    console.log(formatColors(data.dark.colors));
+  }
+
+  // Border radius
+  if (data.borderRadius) {
+    console.log("/* Border Radius */");
+    for (const [key, value] of Object.entries(data.borderRadius)) {
+      console.log(`  --radius-${key}: ${value};`);
+    }
+    console.log();
+  }
+
+  // Opacity
+  if (data.opacity) {
+    console.log("/* Opacity */");
+    for (const [key, value] of Object.entries(data.opacity)) {
+      console.log(`  --opacity-${key}: ${value};`);
+    }
+    console.log();
+  }
+
+  // Also output raw JSON to stderr for programmatic use
+  console.error("\n# Raw JSON output:");
+  console.error(JSON.stringify(rawData || data, null, 2));
+}
+
+main();
diff --git a/skills/heroui-native/scripts/list_components.mjs b/skills/heroui-native/scripts/list_components.mjs
new file mode 100755
index 0000000..5210eb4
--- /dev/null
+++ b/skills/heroui-native/scripts/list_components.mjs
@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI Native components.
+ *
+ * Usage:
+ *   node list_components.mjs
+ *
+ * Output:
+ *   JSON with components array, latestVersion, and count
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const APP_PARAM = "app=native-skills";
+const LLMS_TXT_URL = "https://heroui.com/native/llms.txt";
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`HTTP Error ${response.status}: ${response.statusText}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch component list from llms.txt fallback URL.
+ */
+async function fetchFallback() {
+  try {
+    const response = await fetch(LLMS_TXT_URL, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const content = await response.text();
+
+    // Parse markdown to extract component names from pattern: - [ComponentName](url)
+    // Look for links under the Components section (### Components)
+    const components = [];
+    let inComponentsSection = false;
+
+    for (const line of content.split("\n")) {
+      // Check if we're entering the Components section (uses ### header)
+      if (line.trim() === "### Components") {
+        inComponentsSection = true;
+        continue;
+      }
+
+      // Check if we're leaving the Components section (another ### header)
+      if (inComponentsSection && line.trim().startsWith("### ")) {
+        break;
+      }
+
+      // Extract component name from markdown link pattern
+      // Match: - [ComponentName](https://www.heroui.com/docs/native/components/component-name)
+      // Skip "All Components" which links to /components without a specific component
+      if (inComponentsSection) {
+        const match = line.match(
+          /^\s*-\s*\[([^\]]+)\]\(https:\/\/www\.heroui\.com\/docs\/native\/components\/[a-z]/,
+        );
+
+        if (match) {
+          components.push(match[1]);
+        }
+      }
+    }
+
+    if (components.length > 0) {
+      console.error(`# Using fallback: ${LLMS_TXT_URL}`);
+
+      return {
+        components: components.sort(),
+        count: components.length,
+        latestVersion: "unknown",
+      };
+    }
+
+    return null;
+  } catch (error) {
+    console.error(`Fallback Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Main function to list all available HeroUI Native components.
+ */
+async function main() {
+  let data = await fetchApi("/v1/components");
+
+  // Check if API returned valid data with components
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("# API returned no components, trying fallback...");
+    data = await fetchFallback();
+  }
+
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("Error: Failed to fetch component list from API and fallback");
+    process.exit(1);
+  }
+
+  // Output formatted JSON
+  console.log(JSON.stringify(data, null, 2));
+
+  // Print summary to stderr for human readability
+  console.error(
+    `\n# Found ${data.components.length} Native components (${data.latestVersion || "unknown"})`,
+  );
+}
+
+main();
diff --git a/skills/heroui-react/LICENSE.txt b/skills/heroui-react/LICENSE.txt
new file mode 100644
index 0000000..bf4dfe2
--- /dev/null
+++ b/skills/heroui-react/LICENSE.txt
@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/heroui-react/SKILL.md b/skills/heroui-react/SKILL.md
new file mode 100644
index 0000000..330da8f
--- /dev/null
+++ b/skills/heroui-react/SKILL.md
@@ -0,0 +1,234 @@
+---
+name: heroui-react
+description: "HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles."
+metadata:
+  author: heroui
+  version: "3.0.1"
+---
+
+# HeroUI v3 React Development Guide
+
+HeroUI v3 is a component library built on **Tailwind CSS v4** and **React Aria Components**, providing accessible, customizable UI components for React applications.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-react
+```
+
+---
+
+## CRITICAL: v3 Only - Ignore v2 Knowledge
+
+**This guide is for HeroUI v3 ONLY.** Do NOT apply v2 patterns — the provider, styling, and component API all changed:
+
+| Feature       | v2 (DO NOT USE)                   | v3 (USE THIS)                               |
+| ------------- | --------------------------------- | ------------------------------------------- |
+| Provider      | `<HeroUIProvider>` required       | **No Provider needed**                      |
+| Animations    | `framer-motion` package           | CSS-based, no extra deps                    |
+| Component API | Flat props: `<Card title="x">`    | Compound: `<Card><Card.Header>`             |
+| Styling       | Tailwind v3 + `@heroui/theme`     | Tailwind v4 + `@heroui/styles`         	  |
+| Packages      | `@heroui/system`, `@heroui/theme` | `@heroui/react`, `@heroui/styles` 		  |
+
+```tsx
+// DO NOT DO THIS - v2 pattern
+import { HeroUIProvider } from "@heroui/react";
+import { motion } from "framer-motion";
+
+<HeroUIProvider>
+	<Card title="Product" description="A great product" />
+</HeroUIProvider>;
+```
+
+### CORRECT (v3 patterns)
+
+```tsx
+// DO THIS - v3 pattern (no provider, compound components)
+import { Card } from "@heroui/react";
+
+<Card>
+	<Card.Header>
+		<Card.Title>Product</Card.Title>
+		<Card.Description>A great product</Card.Description>
+	</Card.Header>
+</Card>;
+```
+
+**Always fetch v3 docs before implementing.**
+
+---
+
+## Core Principles
+
+- Semantic variants (`primary`, `secondary`, `tertiary`) over visual descriptions
+- Composition over configuration (compound components)
+- CSS variable-based theming with `oklch` color space
+- BEM naming convention for predictable styling
+
+---
+
+## Accessing Documentation & Component Information
+
+**For component details, examples, props, and implementation patterns, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available components
+node scripts/list_components.mjs
+
+# Get component documentation (MDX)
+node scripts/get_component_docs.mjs Button
+node scripts/get_component_docs.mjs Button Card TextField
+
+# Get component source code
+node scripts/get_source.mjs Button
+
+# Get component CSS styles (BEM classes)
+node scripts/get_styles.mjs Button
+
+# Get theme variables
+node scripts/get_theme.mjs
+
+# Get non-component docs (guides, releases)
+node scripts/get_docs.mjs /docs/react/getting-started/theming
+```
+
+### Direct MDX URLs
+
+Component docs: `https://heroui.com/docs/react/components/{component-name}.mdx`
+
+Examples:
+
+- Button: `https://heroui.com/docs/react/components/button.mdx`
+- Modal: `https://heroui.com/docs/react/components/modal.mdx`
+- Form: `https://heroui.com/docs/react/components/form.mdx`
+
+Getting started guides: `https://heroui.com/docs/react/getting-started/{topic}.mdx`
+
+**Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
+
+---
+
+## Installation Essentials
+
+### Quick Install
+
+```bash
+npm i @heroui/styles @heroui/react tailwind-variants
+```
+
+### Framework Setup (Next.js App Router - Recommended)
+
+1. **Install dependencies:**
+
+```bash
+npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
+```
+
+2. **Create/update `app/globals.css`:**
+
+```css
+/* Tailwind CSS v4 - Must be first */
+@import "tailwindcss";
+
+/* HeroUI v3 styles - Must be after Tailwind */
+@import "@heroui/styles";
+```
+
+3. **Import in `app/layout.tsx`:**
+
+```tsx
+import "./globals.css";
+
+export default function RootLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	return (
+		<html lang="en" suppressHydrationWarning>
+			<body>
+				{/* No Provider needed in HeroUI v3! */}
+				{children}
+			</body>
+		</html>
+	);
+}
+```
+
+4. **Configure PostCSS (`postcss.config.mjs`):**
+
+```js
+export default {
+	plugins: {
+		"@tailwindcss/postcss": {},
+	},
+};
+```
+
+### Critical Setup Requirements
+
+1. **Tailwind CSS v4 is MANDATORY** - HeroUI v3 will NOT work with Tailwind CSS v3
+2. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Content`)
+3. **Use onPress, not onClick** - For better accessibility, use `onPress` event handlers
+4. **Import Order Matters** - Always import Tailwind CSS before HeroUI styles
+
+---
+
+## Component Patterns
+
+All components use the **compound pattern** shown above (dot-notation subcomponents like `Card.Header`, `Card.Content`). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.
+
+---
+
+## Semantic Variants
+
+HeroUI uses semantic naming to communicate functional intent:
+
+| Variant     | Purpose                           | Usage          |
+| ----------- | --------------------------------- | -------------- |
+| `primary`   | Main action to move forward       | 1 per context  |
+| `secondary` | Alternative actions               | Multiple       |
+| `tertiary`  | Dismissive actions (cancel, skip) | Sparingly      |
+| `danger`    | Destructive actions               | When needed    |
+| `ghost`     | Low-emphasis actions              | Minimal weight |
+| `outline`   | Secondary actions                 | Bordered style |
+
+**Don't use raw colors** - semantic variants adapt to themes and accessibility.
+
+---
+
+## Theming
+
+HeroUI v3 uses CSS variables with `oklch` color space:
+
+```css
+:root {
+	--accent: oklch(0.6204 0.195 253.83);
+	--accent-foreground: var(--snow);
+	--background: oklch(0.9702 0 0);
+	--foreground: var(--eclipse);
+}
+```
+
+**Get current theme variables:**
+
+```bash
+node scripts/get_theme.mjs
+```
+
+**Color naming:**
+
+- Without suffix = background (e.g., `--accent`)
+- With `-foreground` = text color (e.g., `--accent-foreground`)
+
+**Theme switching:**
+
+```html
+<html class="dark" data-theme="dark"></html>
+```
+
+For detailed theming, fetch: `https://heroui.com/docs/react/getting-started/theming.mdx`
diff --git a/skills/heroui-react/scripts/get_component_docs.mjs b/skills/heroui-react/scripts/get_component_docs.mjs
new file mode 100644
index 0000000..41c6f05
--- /dev/null
+++ b/skills/heroui-react/scripts/get_component_docs.mjs
@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Get complete component documentation (MDX) for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_component_docs.mjs Button
+ *   node get_component_docs.mjs Button Card TextField
+ *
+ * Output:
+ *   MDX documentation including imports, usage, variants, props, examples
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Convert PascalCase to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(component) {
+  const kebabName = toKebabCase(component);
+  const url = `${FALLBACK_BASE}/docs/react/components/${kebabName}.mdx`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {component, error: `Failed to fetch docs for ${component}`};
+    }
+
+    const content = await response.text();
+
+    return {
+      component,
+      content,
+      contentType: "mdx",
+      source: "fallback",
+      url,
+    };
+  } catch {
+    return {component, error: `Failed to fetch docs for ${component}`};
+  }
+}
+
+/**
+ * Main function to get component documentation.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_docs.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_docs.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first - use POST /v1/components/docs for batch requests
+  console.error(`# Fetching docs for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/docs", "POST", {components});
+
+  if (data && data.results) {
+    // Output results
+    if (data.results.length === 1) {
+      // Single component - output content directly for easier reading
+      const result = data.results[0];
+
+      if (result.content) {
+        console.log(result.content);
+      } else if (result.error) {
+        console.error(`# Error for ${result.component}: ${result.error}`);
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      // Multiple components - output as JSON array
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to individual component fetches
+  console.error("# API failed, using fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchFallback(component);
+
+    results.push(result);
+  }
+
+  // Output results
+  if (results.length === 1) {
+    // Single component - output content directly for easier reading
+    const result = results[0];
+
+    if (result.content) {
+      console.log(result.content);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    // Multiple components - output as JSON array
+    console.log(JSON.stringify(results, null, 2));
+  }
+}
+
+main();
diff --git a/skills/heroui-react/scripts/get_docs.mjs b/skills/heroui-react/scripts/get_docs.mjs
new file mode 100644
index 0000000..8d3529b
--- /dev/null
+++ b/skills/heroui-react/scripts/get_docs.mjs
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Get non-component HeroUI documentation (guides, theming, releases).
+ *
+ * Usage:
+ *   node get_docs.mjs /docs/react/getting-started/theming
+ *   node get_docs.mjs /docs/react/releases/v3-0-0-beta-3
+ *
+ * Output:
+ *   MDX documentation content
+ *
+ * Note: For component docs, use get_component_docs.mjs instead.
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch documentation from HeroUI API.
+ * Uses v1 endpoint pattern: /v1/docs/:path
+ */
+async function fetchApi(path) {
+  // The v1 API expects path without /docs/ prefix
+  // Input: /docs/react/getting-started/theming
+  // API expects: react/getting-started/theming (route is /v1/docs/:path(*))
+  let apiPath = path.startsWith("/docs/")
+    ? path.slice(6) // Remove /docs/ prefix
+    : path.startsWith("/")
+      ? path.slice(1) // Remove leading /
+      : path;
+
+  const separator = "?";
+  const url = `${API_BASE}/v1/docs/${apiPath}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(path) {
+  // Ensure path starts with /docs and ends with .mdx
+  let cleanPath = path.replace(/^\//, "");
+
+  if (!cleanPath.endsWith(".mdx")) {
+    cleanPath = `${cleanPath}.mdx`;
+  }
+
+  const url = `${FALLBACK_BASE}/${cleanPath}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {error: `HTTP ${response.status}: ${response.statusText}`, path};
+    }
+
+    const content = await response.text();
+
+    return {
+      content,
+      contentType: "mdx",
+      path,
+      source: "fallback",
+      url,
+    };
+  } catch (error) {
+    return {error: `Fetch Error: ${error.message}`, path};
+  }
+}
+
+/**
+ * Main function to get documentation for specified path.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_docs.mjs <path>");
+    console.error("Example: node get_docs.mjs /docs/react/getting-started/theming");
+    console.error();
+    console.error("Available paths include:");
+    console.error("  /docs/react/getting-started/theming");
+    console.error("  /docs/react/getting-started/colors");
+    console.error("  /docs/react/getting-started/animations");
+    console.error("  /docs/react/releases/v3-0-0-beta-3");
+    console.error();
+    console.error("Note: For component docs, use get_component_docs.mjs instead.");
+    process.exit(1);
+  }
+
+  const path = args[0];
+
+  // Check if user is trying to get component docs
+  if (path.includes("/components/")) {
+    console.error("# Warning: Use get_component_docs.mjs for component documentation.");
+    const componentName = path.split("/").pop().replace(".mdx", "");
+    const titleCase = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+    console.error(`# Example: node get_component_docs.mjs ${titleCase}`);
+  }
+
+  console.error(`# Fetching documentation for ${path}...`);
+
+  // Try API first
+  const data = await fetchApi(path);
+
+  if (data && data.content) {
+    data.source = "api";
+    console.log(data.content);
+
+    return;
+  }
+
+  // Fallback to direct fetch
+  console.error("# API failed, using fallback...");
+  const fallbackData = await fetchFallback(path);
+
+  if (fallbackData.content) {
+    console.log(fallbackData.content);
+  } else {
+    console.log(JSON.stringify(fallbackData, null, 2));
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/skills/heroui-react/scripts/get_source.mjs b/skills/heroui-react/scripts/get_source.mjs
new file mode 100644
index 0000000..9dc3355
--- /dev/null
+++ b/skills/heroui-react/scripts/get_source.mjs
@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Get React/TypeScript source code implementation for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_source.mjs Button
+ *   node get_source.mjs Button Accordion Card
+ *
+ * Output:
+ *   Full TSX source code with GitHub URL for each component
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch source code directly from GitHub as fallback.
+ */
+async function fetchGithubFallback(component) {
+  // Try common patterns for component paths
+  const patterns = [
+    `packages/react/src/components/${component.toLowerCase()}/${component.toLowerCase()}.tsx`,
+    `packages/react/src/components/${component.toLowerCase()}/index.tsx`,
+  ];
+
+  for (const path of patterns) {
+    const url = `${GITHUB_RAW_BASE}/${path}`;
+
+    try {
+      const response = await fetch(url, {
+        headers: {"User-Agent": "HeroUI-Skill/1.0"},
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (response.ok) {
+        const content = await response.text();
+
+        return {
+          component,
+          filePath: path,
+          githubUrl: `https://github.com/heroui-inc/heroui/blob/v3/${path}`,
+          source: "fallback",
+          sourceCode: content,
+        };
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {component, error: `Failed to fetch source for ${component}`};
+}
+
+/**
+ * Main function to get source code for specified components.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_source.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_source.mjs Button Accordion");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first
+  console.error(`# Fetching source code for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/source", "POST", {components});
+
+  if (data && data.results) {
+    for (const result of data.results) {
+      result.source = "api";
+    }
+
+    // Output results
+    if (data.results.length === 1) {
+      const result = data.results[0];
+
+      if (result.sourceCode) {
+        console.log(`// File: ${result.filePath || "unknown"}`);
+        console.log(`// GitHub: ${result.githubUrl || "unknown"}`);
+        console.log();
+        console.log(result.sourceCode);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to GitHub direct fetch
+  console.error("# API failed, using GitHub fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchGithubFallback(component);
+
+    results.push(result);
+  }
+
+  if (results.length === 1) {
+    const result = results[0];
+
+    if (result.sourceCode) {
+      console.log(`// File: ${result.filePath || "unknown"}`);
+      console.log(`// GitHub: ${result.githubUrl || "unknown"}`);
+      console.log();
+      console.log(result.sourceCode);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    console.log(JSON.stringify({results}, null, 2));
+  }
+}
+
+main();
diff --git a/skills/heroui-react/scripts/get_styles.mjs b/skills/heroui-react/scripts/get_styles.mjs
new file mode 100644
index 0000000..5323806
--- /dev/null
+++ b/skills/heroui-react/scripts/get_styles.mjs
@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Get CSS styles (BEM classes) for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_styles.mjs Button
+ *   node get_styles.mjs Button Card Chip
+ *
+ * Output:
+ *   CSS file content with BEM classes and GitHub URL for each component
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch CSS styles directly from GitHub as fallback.
+ */
+async function fetchGithubFallback(component) {
+  // Try common patterns for style paths
+  const patterns = [
+    `packages/styles/src/components/${component.toLowerCase()}.css`,
+    `packages/styles/components/${component.toLowerCase()}.css`,
+  ];
+
+  for (const path of patterns) {
+    const url = `${GITHUB_RAW_BASE}/${path}`;
+
+    try {
+      const response = await fetch(url, {
+        headers: {"User-Agent": "HeroUI-Skill/1.0"},
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (response.ok) {
+        const content = await response.text();
+
+        return {
+          component,
+          filePath: path,
+          githubUrl: `https://github.com/heroui-inc/heroui/blob/v3/${path}`,
+          source: "fallback",
+          stylesCode: content,
+        };
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {component, error: `Failed to fetch styles for ${component}`};
+}
+
+/**
+ * Main function to get CSS styles for specified components.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_styles.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_styles.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first
+  console.error(`# Fetching styles for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/styles", "POST", {components});
+
+  if (data && data.results) {
+    for (const result of data.results) {
+      result.source = "api";
+    }
+
+    // Output results
+    if (data.results.length === 1) {
+      const result = data.results[0];
+
+      if (result.stylesCode) {
+        console.log(`/* File: ${result.filePath || "unknown"} */`);
+        console.log(`/* GitHub: ${result.githubUrl || "unknown"} */`);
+        console.log();
+        console.log(result.stylesCode);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to GitHub direct fetch
+  console.error("# API failed, using GitHub fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchGithubFallback(component);
+
+    results.push(result);
+  }
+
+  if (results.length === 1) {
+    const result = results[0];
+
+    if (result.stylesCode) {
+      console.log(`/* File: ${result.filePath || "unknown"} */`);
+      console.log(`/* GitHub: ${result.githubUrl || "unknown"} */`);
+      console.log();
+      console.log(result.stylesCode);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    console.log(JSON.stringify({results}, null, 2));
+  }
+}
+
+main();
diff --git a/skills/heroui-react/scripts/get_theme.mjs b/skills/heroui-react/scripts/get_theme.mjs
new file mode 100644
index 0000000..32bfe5e
--- /dev/null
+++ b/skills/heroui-react/scripts/get_theme.mjs
@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Get theme variables and design tokens for HeroUI v3.
+ *
+ * Usage:
+ *   node get_theme.mjs
+ *
+ * Output:
+ *   Theme variables organized by common/light/dark with oklch color format
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const APP_PARAM = "app=react-skills";
+
+// Fallback theme reference when API is unavailable
+const FALLBACK_THEME = {
+  common: {
+    base: [
+      {name: "--font-sans", value: "ui-sans-serif, system-ui, sans-serif"},
+      {name: "--font-mono", value: "ui-monospace, monospace"},
+      {name: "--radius-sm", value: "0.375rem"},
+      {name: "--radius-md", value: "0.5rem"},
+      {name: "--radius-lg", value: "0.75rem"},
+      {name: "--radius-full", value: "9999px"},
+    ],
+    calculated: [{name: "--spacing-unit", value: "0.25rem"}],
+  },
+  dark: {
+    semantic: [
+      {name: "--color-background", value: "oklch(14.5% 0 0)"},
+      {name: "--color-foreground", value: "oklch(98.4% 0 0)"},
+      {name: "--color-accent", value: "oklch(55.1% 0.228 264.1)"},
+      {name: "--color-danger", value: "oklch(63.7% 0.237 25.3)"},
+      {name: "--color-success", value: "oklch(76.5% 0.177 163.2)"},
+      {name: "--color-warning", value: "oklch(79.5% 0.184 86.0)"},
+    ],
+  },
+  latestVersion: "3.0.0-beta",
+  light: {
+    semantic: [
+      {name: "--color-background", value: "oklch(100% 0 0)"},
+      {name: "--color-foreground", value: "oklch(14.5% 0 0)"},
+      {name: "--color-accent", value: "oklch(55.1% 0.228 264.1)"},
+      {name: "--color-danger", value: "oklch(63.7% 0.237 25.3)"},
+      {name: "--color-success", value: "oklch(76.5% 0.177 163.2)"},
+      {name: "--color-warning", value: "oklch(79.5% 0.184 86.0)"},
+    ],
+  },
+  note: "This is a fallback. For complete theme variables, ensure the API is accessible.",
+  source: "fallback",
+  theme: "default",
+};
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Format theme variables for display.
+ */
+function formatVariables(variables) {
+  const lines = [];
+
+  for (const variable of variables) {
+    const name = variable.name || "";
+    const value = variable.value || "";
+    const desc = variable.description || "";
+
+    if (desc) {
+      lines.push(`  ${name}: ${value}; /* ${desc} */`);
+    } else {
+      lines.push(`  ${name}: ${value};`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Main function to get theme variables.
+ */
+async function main() {
+  console.error("# Fetching theme variables...");
+
+  const rawData = await fetchApi("/v1/themes/variables?theme=default");
+
+  let data;
+  let version;
+
+  if (!rawData) {
+    console.error("# API failed, using fallback theme reference...");
+    data = FALLBACK_THEME;
+    version = FALLBACK_THEME.latestVersion || "unknown";
+  } else {
+    // Handle API response format: { themes: [...], latestVersion: "..." }
+    if (rawData.themes && rawData.themes.length > 0) {
+      data = rawData.themes[0]; // Get first theme (default)
+      version = rawData.latestVersion || rawData.version || "unknown";
+    } else {
+      // Direct format
+      data = rawData;
+      version = rawData.latestVersion || "unknown";
+    }
+  }
+
+  // Output as formatted CSS-like structure for readability
+  console.log("/* HeroUI v3 Theme Variables */");
+  console.log(`/* Theme: ${data.theme || "default"} */`);
+  console.log(`/* Version: ${version} */`);
+  console.log();
+
+  // Common variables
+  if (data.common) {
+    console.log(":root {");
+    console.log("  /* Base Variables */");
+    if (data.common.base) {
+      console.log(formatVariables(data.common.base));
+    }
+    console.log();
+    console.log("  /* Calculated Variables */");
+    if (data.common.calculated) {
+      console.log(formatVariables(data.common.calculated));
+    }
+    console.log("}");
+    console.log();
+  }
+
+  // Light mode
+  if (data.light) {
+    console.log(":root, [data-theme='light'] {");
+    console.log("  /* Light Mode Semantic Variables */");
+    if (data.light.semantic) {
+      console.log(formatVariables(data.light.semantic));
+    }
+    console.log("}");
+    console.log();
+  }
+
+  // Dark mode
+  if (data.dark) {
+    console.log("[data-theme='dark'] {");
+    console.log("  /* Dark Mode Semantic Variables */");
+    if (data.dark.semantic) {
+      console.log(formatVariables(data.dark.semantic));
+    }
+    console.log("}");
+  }
+
+  // Also output raw JSON to stderr for programmatic use
+  console.error("\n# Raw JSON output:");
+  console.error(JSON.stringify(rawData || data, null, 2));
+}
+
+main();
diff --git a/skills/heroui-react/scripts/list_components.mjs b/skills/heroui-react/scripts/list_components.mjs
new file mode 100644
index 0000000..44eb499
--- /dev/null
+++ b/skills/heroui-react/scripts/list_components.mjs
@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI v3 components.
+ *
+ * Usage:
+ *   node list_components.mjs
+ *
+ * Output:
+ *   JSON with components array, latestVersion, and count
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const APP_PARAM = "app=react-skills";
+const LLMS_TXT_URL = "https://heroui.com/react/llms.txt";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`HTTP Error ${response.status}: ${response.statusText}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch component list from llms.txt fallback URL.
+ */
+async function fetchFallback() {
+  try {
+    const response = await fetch(LLMS_TXT_URL, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const content = await response.text();
+
+    // Parse markdown to extract component names from pattern: - [ComponentName](url)
+    // Look for links under the Components section (### Components)
+    const components = [];
+    let inComponentsSection = false;
+
+    for (const line of content.split("\n")) {
+      // Check if we're entering the Components section (uses ### header)
+      if (line.trim() === "### Components") {
+        inComponentsSection = true;
+        continue;
+      }
+
+      // Check if we're leaving the Components section (another ### header)
+      if (inComponentsSection && line.trim().startsWith("### ")) {
+        break;
+      }
+
+      // Extract component name from markdown link pattern
+      // Match: - [ComponentName](https://www.heroui.com/docs/react/components/component-name)
+      // Skip "All Components" which links to /components without a specific component
+      if (inComponentsSection) {
+        const match = line.match(
+          /^\s*-\s*\[([^\]]+)\]\(https:\/\/www\.heroui\.com\/docs\/react\/components\/[a-z]/,
+        );
+
+        if (match) {
+          components.push(match[1]);
+        }
+      }
+    }
+
+    if (components.length > 0) {
+      console.error(`# Using fallback: ${LLMS_TXT_URL}`);
+
+      return {
+        components: components.sort(),
+        count: components.length,
+        latestVersion: "unknown",
+      };
+    }
+
+    return null;
+  } catch (error) {
+    console.error(`Fallback Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Main function to list all available HeroUI v3 components.
+ */
+async function main() {
+  let data = await fetchApi("/v1/components");
+
+  // Check if API returned valid data with components
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("# API returned no components, trying fallback...");
+    data = await fetchFallback();
+  }
+
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("Error: Failed to fetch component list from API and fallback");
+    process.exit(1);
+  }
+
+  // Output formatted JSON
+  console.log(JSON.stringify(data, null, 2));
+
+  // Print summary to stderr for human readability
+  console.error(
+    `\n# Found ${data.components.length} components (${data.latestVersion || "unknown"})`,
+  );
+}
+
+main();
diff --git a/turbo.json b/turbo.json
new file mode 100644
index 0000000..a4fa9ef
--- /dev/null
+++ b/turbo.json
@@ -0,0 +1,40 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalEnv": [
+    "VERCEL_ENV",
+    "STORYBOOK_READY_ONLY",
+    "LOOPS_API_ENDPOINT",
+    "LOOPS_API_KEY",
+    "FEATUREBASE_API_ENDPOINT",
+    "FEATUREBASE_API_KEY"
+  ],
+  "tasks": {
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [".next/**", ".source/**", "dist/**", "storybook-static/**"]
+    },
+    "start": {
+      "dependsOn": ["^build"],
+      "outputs": []
+    },
+    "lint": {
+      "outputs": []
+    },
+    "format": {
+      "dependsOn": [],
+      "outputs": []
+    },
+    "test": {
+      "dependsOn": [],
+      "outputs": []
+    },
+    "typecheck": {
+      "dependsOn": [],
+      "outputs": []
+    }
+  }
+}
diff --git a/vercel.json b/vercel.json
new file mode 100644
index 0000000..0b16236
--- /dev/null
+++ b/vercel.json
@@ -0,0 +1,6 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "github": {
+    "autoJobCancelation": true
+  }
+}